Wand Enhancer APIs: Main Entry Points and Bridge Architecture

Wand Enhancer exposes a WebSocket-based bridge API centered on createBridgeServer, BridgeState, and RemoteSessionClient, enabling remote control of the Wand desktop patcher through a minimal set of TypeScript modules.

The Wand Enhancer repository provides a modular runtime for injecting a remote web panel into the Wand application via Electron ASAR patching. Its architecture relies on a small set of well-defined APIs that mediate between the desktop bridge and the remote UI, all exposed through TypeScript modules in the web-panel directory.

Core Bridge Server API (createBridgeServer)

The primary entry point for initializing the runtime is createBridgeServer, defined in web-panel/bridge/src/server.ts. This function starts an HTTP and WebSocket server that serves the remote panel UI, handles health-check requests, and mediates remote commands.

When invoked, createBridgeServer accepts an optional configuration object specifying panelRoot, host, and port, then returns an API surface for registering handlers and pushing state updates:

import { createBridgeServer } from './web-panel/bridge/src/server';

const bridge = createBridgeServer({
  panelRoot: './dist',
  host: 'localhost',
  port: 8080
});

// Register remote command handlers
bridge.setCommandHandler('launch', (gameId: string) => {
  // Execute game launch logic
});

// Push full state synchronization
bridge.sync();

State Management (BridgeState)

The BridgeState class in web-panel/bridge/src/bridge-state.ts maintains the canonical snapshot of the remote session. It tracks installed applications, trainer status, and current game state, providing helper methods to synchronize data with connected clients.

Key synchronization methods include:

• sync() – Pushes the complete state snapshot to all connected clients
• syncGameStatus() – Updates only the game status subset
• syncInstalledApps() – Refreshes the installed applications list
• valueChanged() – Notifies clients of trainer value mutations

All UI updates flow through this state object, ensuring a single source of truth for the remote panel.

WebSocket Communication Layer

Low-Level Frame Processing (websocket-codec.ts)

The websocket-codec.ts module in web-panel/bridge/src/ provides low-level utilities for encoding and decoding WebSocket frames, handling ping/pong heartbeats, and sending JSON messages via sendJson and parseFrame functions. These utilities implement the custom bridge protocol used by the server to communicate with connected clients.

Front-End Client (RemoteSessionClient)

On the client side, RemoteSessionClient in web-panel/src/remote-session/remote-session.client.ts abstracts the WebSocket API for the UI layer. It manages the initial hello handshake and dispatches protocol messages such as remote_command_result and set_value_result.

import { RemoteSessionClient } from './web-panel/src/remote-session/remote-session.client';

const client = new RemoteSessionClient('ws://localhost:8080/remote/ws');
await client.connect();

// Send remote command
client.sendRemoteCommand({ action: 'launch', gameId: '1234' });

Protocol Definitions and Constants

The messages.ts file in web-panel/protocol/messages.ts defines the type-safe enumeration of all message shapes exchanged over the bridge. This includes contracts for hello, remote_command, set_value, game-status, and their corresponding result types, serving as the canonical contract that both server and UI must obey.

Configuration values reside in constants.ts (web-panel/bridge/src/constants.ts), which exports:

• REMOTE_WS_PATH (/remote/ws) – The WebSocket endpoint path
• Protocol version numbers
• Default host and port settings
• WebSocket opcode values

Data Persistence and Normalization

For UI state persistence, storage.ts (web-panel/src/shared/storage.ts) provides centralized wrappers around localStorage:

• loadJson() / saveJson() – For structured data objects
• loadStringSet() / saveStringSet() – For collections like pinned cheats and presets

Payload normalization occurs in web-panel/bridge/src/normalizers/, particularly trainer.ts, which converts raw Wand RPC payloads into the bridge's normalized format. This abstraction shields the rest of the codebase from Wand version changes.

Summary

• The createBridgeServer function in web-panel/bridge/src/server.ts initializes the HTTP/WebSocket bridge and returns methods to register command handlers (setCommandHandler, setHandler) and push updates
• BridgeState manages session snapshots through sync, syncGameStatus, and valueChanged methods, ensuring consistent UI state
• websocket-codec.ts handles low-level frame processing, while RemoteSessionClient provides the front-end WebSocket abstraction
• Protocol contracts in messages.ts and constants.ts define the type-safe message shapes and connection parameters like REMOTE_WS_PATH
• storage.ts and the normalizers directory handle persistence and payload transformation, isolating version-specific changes

Frequently Asked Questions

What is the primary entry point to start the Wand Enhancer bridge?

The createBridgeServer function exported from web-panel/bridge/src/server.ts is the main entry point. It initializes the HTTP and WebSocket server, optionally accepting panelRoot, host, and port parameters, and returns an object with methods to register command handlers and synchronize state through BridgeState.

How does the bridge communicate with the remote panel UI?

Communication occurs over WebSocket via the path defined in REMOTE_WS_PATH (/remote/ws) as specified in web-panel/bridge/src/constants.ts. After a hello handshake, the server pushes state snapshots through BridgeState methods, while the client (RemoteSessionClient) sends commands like remote_command and set_value defined in web-panel/protocol/messages.ts.

Where are trainer values and game status normalized?

The web-panel/bridge/src/normalizers/ directory contains utilities that convert raw Wand RPC payloads into the bridge's normalized format. This abstraction shields the API from version-specific changes in the underlying Wand implementation, with specific logic for trainer actions and game status updates.

How does the UI persist settings like pinned cheats and presets?

All UI components use the helpers in web-panel/src/shared/storage.ts, which provide type-safe wrappers for localStorage operations including loadJson, saveJson, loadStringSet, and saveStringSet, ensuring a single source of truth for application state across the remote panel.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}