# Wand Enhancer APIs: Main Entry Points and Bridge Architecture

> Discover Wand Enhancer's main entry points: createBridgeServer, BridgeState, and RemoteSessionClient. Learn how this WebSocket bridge enables remote control of the Wand desktop patcher.

- Repository: [k1tbyte/Wand-Enhancer](https://github.com/k1tbyte/Wand-Enhancer)
- Tags: architecture
- Published: 2026-07-13

---

**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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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:

```typescript
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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/websocket-codec.ts))

The **[`websocket-codec.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`.

```typescript
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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/messages.ts)** file in [`web-panel/protocol/messages.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/constants.ts)** ([`web-panel/bridge/src/constants.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/storage.ts)** ([`web-panel/src/shared/storage.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/websocket-codec.ts)** handles low-level frame processing, while **`RemoteSessionClient`** provides the front-end WebSocket abstraction
- Protocol contracts in **[`messages.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/messages.ts)** and **[`constants.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/constants.ts)** define the type-safe message shapes and connection parameters like `REMOTE_WS_PATH`
- **[`storage.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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.