# How Wand‑Enhancer Injects the Remote Panel Bridge into the Wand Electron App

> Discover how Wand-Enhancer injects the remote panel bridge by compiling TypeScript, embedding into the ASAR archive, and patching the main process for IPC bridge initialization.

- Repository: [k1tbyte/Wand-Enhancer](https://github.com/k1tbyte/Wand-Enhancer)
- Tags: internals
- Published: 2026-09-01

---

**Wand‑Enhancer injects the remote panel bridge by compiling TypeScript sources into a CommonJS bundle, embedding the output into the Electron ASAR archive, and patching the main process entry point to initialize the IPC bridge at application startup.**

The **k1tbyte/Wand-Enhancer** repository provides a runtime modification system that augments the original Wand Electron binary with a remote control interface. This injection pipeline embeds a web‑based panel and a TypeScript bridge that connects the UI to Wand’s native services without requiring changes to the original source code.

## Build the Bridge and Renderer Scripts

The injection process begins by compiling the TypeScript sources located in `web-panel/bridge/src/` into a production‑ready bundle.

Running `pnpm run build` (or specifically `pnpm run build:bridge`) triggers the build pipeline. This process compiles the bridge logic into a single CommonJS file at **`web-panel/dist/bridge.cjs`**. Simultaneously, the build generates default renderer scripts and places them under `web-panel/dist/renderer-scripts/`, as documented in [`web-panel/scripts/custom/README.md`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/scripts/custom/README.md).

These compiled assets serve as the runtime payload that the enhancer later embeds into the target application.

## Embed Assets into the ASAR Archive

Once the bridge is built, **Wand‑Enhancer** modifies the Electron application bundle to include these assets permanently.

In [`WandEnhancer/Core/Enhancer.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Core/Enhancer.cs), the tool extracts the original `resources/app.asar` (along with its unpacked counterpart) from the Wand installation directory. It creates a new folder named **`remote-panel`** inside the extracted tree and copies the entire `web-panel/dist` directory into `remote-panel/`. This places `bridge.cjs` and the renderer scripts at `remote-panel/dist/bridge.cjs` within the ASAR structure.

The configuration constants defining these paths are declared in the source:
- `RemotePanelDirectoryName = "remote-panel"`
- `EmbeddedRemotePanelDistPrefix = "remote-panel/dist/"`

After copying, the tool repackages the ASAR, ensuring the bridge code becomes part of the Electron runtime environment.

## Patch the Main Process Entry Point

The core injection logic resides in [`WandEnhancer/Core/EnhancerConfig.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Core/EnhancerConfig.cs), which generates a runtime patch replacing the application's entry point.

When the patched app launches, the generated code wraps the original startup routine with a `whenReady` handler that loads the embedded bridge:

```csharp
${app}.whenReady().then(() => {
    try {
        const path = require("node:path");
        require(path.join(__dirname, "remote-panel", "bridge.cjs"))
            .installWandRuntime(require("electron"));
    } catch (e) {
        const fs = require("node:fs"),
              os = require("node:os"),
              p  = require("node:path");
        fs.appendFileSync(
            p.join(os.tmpdir(), "wand-remote-bridge.log"),
            `[${new Date().toISOString()}] [boot-error] ${e && e.stack || e}\n`);
    }
    return run();
});

```

This snippet executes three critical actions:
1. **Resolves the path** to `remote-panel/bridge.cjs` inside the ASAR.
2. **Invokes `installWandRuntime`** exported by the bridge bundle, passing the Electron module.
3. **Implements error logging** to a temporary log file at `wand-remote-bridge.log` for debugging boot failures.

## Initialize the IPC Bridge at Runtime

The `installWandRuntime` function, implemented in [`web-panel/bridge/src/wand/runtime.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/bridge/src/wand/runtime.ts), establishes the communication layer between the remote UI and Wand’s backend services.

```typescript
// web-panel/bridge/src/wand/runtime.ts
export function installWandRuntime(electron: ElectronPort, options: BridgeOptions = {}) {
    const { ipcRenderer: c } = electron;
    const send = (channel: string, payload?: any) => {
        try { return c.invoke(channel, payload && JSON.parse(JSON.stringify(payload))); }
        catch (e) { /* ignore */ }
    };
    return {
        sync: (s) => send("wand-remote-sync", s),
        valueChanged: (s) => send("wand-remote-value-changed", s),
        setHandler: (h) => {
            if ((globalThis as any).__wandRemoteBridgeBound) return;
            (globalThis as any).__wandRemoteBridgeBound = true;
            c.invoke("wand-remote-set-handler-bind");
            c.on("wand-remote-set-value", (_e, req) => h(req));
        },
    };
}

```

This function creates **`createBridgeRuntime`** and **`ensureBridge`** internal utilities, then registers IPC methods including `sync`, `valueChanged`, and `setHandler`. It exposes a **global `__wandRemoteBridge`** object on the renderer window, enabling the remote panel to send commands and receive game‑status updates through Electron’s `ipcRenderer` channels.

## Renderer-Side Hook Installation

After the main process initializes the bridge, a secondary injection targets the renderer process to complete the circuit.

The patch generated by [`EnhancerConfig.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/EnhancerConfig.cs) inserts a script that instantiates the `__wandRemoteBridge` object and binds incoming remote‑panel actions to Wand’s trainer services. This ensures that UI commands—such as launching games or modifying cheat values—forward correctly to the native Wand runtime.

The renderer scripts located in `web-panel/dist/renderer-scripts/` (and documented in the custom scripts README) provide cleanup utilities like [`remote-popup-cleanup.js`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/remote-popup-cleanup.js), which removes tooltip and QR‑code artifacts, demonstrating the bridge’s runtime impact on the UI layer.

## Summary

- **Build Phase**: TypeScript sources in `web-panel/bridge/src/` compile into `web-panel/dist/bridge.cjs` via `pnpm run build`.
- **Embedding Phase**: [`WandEnhancer/Core/Enhancer.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Core/Enhancer.cs) extracts `app.asar`, creates a `remote-panel` directory, copies the dist folder, and repackages the archive.
- **Injection Phase**: [`WandEnhancer/Core/EnhancerConfig.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Core/EnhancerConfig.cs) patches the main process entry point to require `bridge.cjs` inside a `whenReady` hook.
- **Runtime Phase**: The `installWandRuntime` function in [`web-panel/bridge/src/wand/runtime.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/bridge/src/wand/runtime.ts) initializes IPC channels and exposes the global `__wandRemoteBridge` API.
- **Error Handling**: Boot failures log to the system temp directory at `wand-remote-bridge.log` for diagnostics.

## Frequently Asked Questions

### How does Wand‑Enhancer modify the Electron ASAR without corrupting the application?

**[`WandEnhancer/Core/Enhancer.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Core/Enhancer.cs)** performs a surgical extraction of `resources/app.asar`, inserts the `remote-panel` directory containing the compiled bridge assets, and repackages the archive using standard Electron ASAR tooling. This preserves the original file structure while adding the new runtime components, ensuring the app remains fully functional.

### What is the purpose of the `bridge.cjs` file in the injection process?

**`bridge.cjs`** is the compiled output of the TypeScript bridge source located at [`web-panel/bridge/src/wand/runtime.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/web-panel/bridge/src/wand/runtime.ts). It exports the `installWandRuntime` function, which establishes the IPC communication layer between the remote panel UI and Wand’s native services. The main process loader invokes this function at startup to activate the bridge.

### How does the remote panel communicate with Wand's trainer services?

The remote panel uses the global **`__wandRemoteBridge`** object exposed by the bridge. This object provides methods like `sync`, `valueChanged`, and `setHandler` that wrap Electron’s `ipcRenderer.invoke` calls. When the UI triggers an action, it calls these methods, which transmit messages through the IPC bridge to handlers registered in the main process.

### Where does Wand‑Enhancer store logs if the bridge fails to initialize?

If the bridge fails to load during the `whenReady` hook, the catch block in the generated patch writes error details to **`wand-remote-bridge.log`** in the system temporary directory (retrieved via `os.tmpdir()`). This log includes timestamps and stack traces to facilitate debugging injection failures.