ue-mcp 0.4.0-alpha

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Lyon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# UE-MCP
+
+**Unreal Engine Model Context Protocol Server** — gives AI assistants deep read/write access to the Unreal Editor through 19 category tools covering 300+ actions.
+
+```mermaid
+flowchart LR
+    AI[AI Assistant] -->|stdio| MCP[MCP Server<br/>TypeScript / Node.js]
+    MCP -->|WebSocket<br/>JSON-RPC| Plugin[C++ Bridge Plugin<br/>inside Unreal Editor]
+    Plugin -->|UE API| Editor[Editor Subsystems]
+    MCP -->|direct fs| FS[Config INI<br/>C++ Headers<br/>Asset Listing]
+```
+
+Blueprints, materials, levels, actors, animation, VFX, landscape, PCG, foliage, audio, UI, physics, navigation, AI, GAS, networking, sequencer, build pipeline — all programmable through natural language.
+
+## Quick Start
+
+```bash
+git clone https://github.com/db-lyon/ue-mcp.git
+cd ue-mcp
+npm install && npm run build
+```
+
+Add to your MCP client config (Claude Code, Claude Desktop, Cursor, etc.):
+
+```json
+{
+  "mcpServers": {
+    "ue-mcp": {
+      "command": "node",
+      "args": [
+        "C:/path/to/ue-mcp/dist/index.js",
+        "C:/path/to/MyGame.uproject"
+      ]
+    }
+  }
+}
+```
+
+Restart the editor once after first run to load the C++ bridge plugin. Then:
+
+```
+project(action="get_status")        — verify connection
+level(action="get_outliner")        — see what's in the level
+asset(action="list")                — browse project assets
+```
+
+## Documentation
+
+**[db-lyon.github.io/ue-mcp](https://db-lyon.github.io/ue-mcp/)**
+
+- [Getting Started](https://db-lyon.github.io/ue-mcp/getting-started/) — Installation, configuration, first run
+- [Architecture](https://db-lyon.github.io/ue-mcp/architecture/) — How the pieces fit together
+- [Tool Reference](https://db-lyon.github.io/ue-mcp/tool-reference/) — All 19 tools with every action
+- [Configuration](https://db-lyon.github.io/ue-mcp/configuration/) — `.ue-mcp.json` and MCP client config
+- [Neon Shrine Demo](https://db-lyon.github.io/ue-mcp/neon-shrine-demo/) — Interactive guided demo
+- [Feedback](https://db-lyon.github.io/ue-mcp/feedback/) — Agent feedback system
+- [Troubleshooting](https://db-lyon.github.io/ue-mcp/troubleshooting/) — Common issues and fixes
+- [Development](https://db-lyon.github.io/ue-mcp/development/) — Building, testing, contributing
+
+## What Can It Do?
+
+| Category | Examples |
+|----------|----------|
+| **Levels** | Place/move/delete actors, spawn lights and volumes, manage splines |
+| **Blueprints** | Read/write graphs, add nodes, connect pins, compile |
+| **Materials** | Create materials and instances, author expression graphs |
+| **Assets** | CRUD, import meshes/textures/animations, datatables |
+| **Animation** | Anim blueprints, montages, blendspaces, skeletons |
+| **VFX** | Niagara systems, emitters, parameters |
+| **Landscape** | Sculpt terrain, paint layers, import heightmaps |
+| **PCG** | Author and execute Procedural Content Generation graphs |
+| **Gameplay** | Physics, collision, navigation, behavior trees, EQS, perception |
+| **GAS** | Gameplay Ability System — attributes, abilities, effects, cues |
+| **Networking** | Replication, dormancy, relevancy, net priority |
+| **UI** | UMG widgets, editor utility widgets and blueprints |
+| **Editor** | Console, Python, PIE, viewport, sequencer, build pipeline, logs |
+| **Reflection** | Class/struct/enum introspection, gameplay tags |
+
+## Supported Versions
+
+Tested with UE 5.4–5.7. Requires `PythonScriptPlugin` (ships with UE 4.26+).
+
+## Contributing
+
+Issues and pull requests welcome. If an AI agent had to fall back to `execute_python` during your session, it will offer to submit structured feedback automatically — this helps us prioritize which native handlers to add next.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/bridge.d.ts

@@ -0,0 +1,25 @@
+export interface BridgeResponse {
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+export declare class EditorBridge {
+    host: string;
+    port: number;
+    private ws;
+    private pending;
+    private reconnectTimer;
+    private idCounter;
+    constructor(host?: string, port?: number);
+    get isConnected(): boolean;
+    connect(timeoutMs?: number): Promise<void>;
+    startReconnecting(intervalMs?: number): void;
+    stopReconnecting(): void;
+    call(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    callOrThrow(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    disconnect(): void;
+    private setupListeners;
+}

package/dist/bridge.js

@@ -0,0 +1,124 @@
+import WebSocket from "ws";
+export class EditorBridge {
+    host;
+    port;
+    ws = null;
+    pending = new Map();
+    reconnectTimer = null;
+    idCounter = 0;
+    constructor(host = "localhost", port = 9877) {
+        this.host = host;
+        this.port = port;
+    }
+    get isConnected() {
+        return this.ws?.readyState === WebSocket.OPEN;
+    }
+    async connect(timeoutMs = 3000) {
+        if (this.isConnected)
+            return;
+        this.ws?.terminate();
+        const url = `ws://${this.host}:${this.port}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                ws.terminate();
+                reject(new Error(`Connection to editor bridge timed out (${url})`));
+            }, timeoutMs);
+            const ws = new WebSocket(url);
+            ws.on("open", () => {
+                clearTimeout(timer);
+                this.ws = ws;
+                this.setupListeners(ws);
+                resolve();
+            });
+            ws.on("error", (err) => {
+                clearTimeout(timer);
+                reject(new Error(`Failed to connect to editor bridge at ${url}: ${err.message}`));
+            });
+        });
+    }
+    startReconnecting(intervalMs = 15000) {
+        if (this.reconnectTimer)
+            return;
+        this.reconnectTimer = setInterval(async () => {
+            if (this.isConnected)
+                return;
+            try {
+                await this.connect();
+                console.error("[ue-mcp] Editor bridge reconnected");
+            }
+            catch {
+                // silent retry
+            }
+        }, intervalMs);
+    }
+    stopReconnecting() {
+        if (this.reconnectTimer) {
+            clearInterval(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    async call(method, params) {
+        if (!this.isConnected) {
+            throw new Error("Not connected to editor bridge. Is Unreal Editor running with the MCP bridge plugin?");
+        }
+        const id = String(++this.idCounter);
+        const request = { id, method, params: params ?? {} };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`Bridge call '${method}' timed out after 30s`));
+            }, 30_000);
+            this.pending.set(id, { resolve, reject, timer });
+            this.ws.send(JSON.stringify(request));
+        });
+    }
+    async callOrThrow(method, params) {
+        const result = await this.call(method, params);
+        return result;
+    }
+    disconnect() {
+        this.stopReconnecting();
+        for (const [, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error("Bridge disconnected"));
+        }
+        this.pending.clear();
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+    setupListeners(ws) {
+        ws.on("message", (data) => {
+            try {
+                const msg = JSON.parse(data.toString());
+                const pending = this.pending.get(msg.id);
+                if (!pending)
+                    return;
+                this.pending.delete(msg.id);
+                clearTimeout(pending.timer);
+                if (msg.error) {
+                    pending.reject(new Error(`Bridge error: ${msg.error.message}`));
+                }
+                else {
+                    pending.resolve(msg.result);
+                }
+            }
+            catch {
+                // malformed message, ignore
+            }
+        });
+        ws.on("close", () => {
+            for (const [, pending] of this.pending) {
+                clearTimeout(pending.timer);
+                pending.reject(new Error("Bridge connection lost"));
+            }
+            this.pending.clear();
+            this.ws = null;
+        });
+        ws.on("error", () => {
+            // handled by close
+        });
+    }
+}
+//# sourceMappingURL=bridge.js.map

package/dist/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"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"}

package/dist/deployer.d.ts

@@ -0,0 +1,18 @@
+import type { ProjectContext } from "./project.js";
+export interface DeployResult {
+    pythonPluginEnabled: boolean;
+    cppPluginDeployed: boolean;
+    cppPluginEnabled: boolean;
+    error?: string;
+}
+/**
+ * Deploy the C++ bridge plugin to the target UE project.
+ *
+ * Copies plugin source from plugin/ue_mcp_bridge/ into the target
+ * project's Plugins/UE_MCP_Bridge/ directory (skipping build artifacts).
+ * Also enables PythonScriptPlugin in the .uproject because the C++
+ * bridge's `execute_python` handler calls into it at runtime.
+ */
+export declare function deploy(context: ProjectContext): DeployResult;
+export declare function deploySummary(r: DeployResult): string;
+export declare function findEngineInstall(engineAssociation: string | null): string | null;

package/dist/deployer.js

@@ -0,0 +1,175 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execSync } from "node:child_process";
+/**
+ * Deploy the C++ bridge plugin to the target UE project.
+ *
+ * Copies plugin source from plugin/ue_mcp_bridge/ into the target
+ * project's Plugins/UE_MCP_Bridge/ directory (skipping build artifacts).
+ * Also enables PythonScriptPlugin in the .uproject because the C++
+ * bridge's `execute_python` handler calls into it at runtime.
+ */
+export function deploy(context) {
+    const result = {
+        pythonPluginEnabled: false,
+        cppPluginDeployed: false,
+        cppPluginEnabled: false,
+    };
+    try {
+        result.pythonPluginEnabled = ensurePythonPlugin(context.projectPath);
+        result.cppPluginDeployed = deployCppPlugin(context.projectPath);
+        result.cppPluginEnabled = ensureCppPluginEnabled(context.projectPath);
+    }
+    catch (e) {
+        result.error = e instanceof Error ? e.message : String(e);
+    }
+    return result;
+}
+export function deploySummary(r) {
+    if (r.error)
+        return `Bridge deployment failed: ${r.error}`;
+    const changes = [];
+    if (r.pythonPluginEnabled)
+        changes.push("enabled PythonScriptPlugin");
+    if (r.cppPluginDeployed)
+        changes.push("deployed C++ bridge plugin");
+    if (r.cppPluginEnabled)
+        changes.push("enabled UE_MCP_Bridge in .uproject");
+    if (changes.length === 0)
+        return "Bridge already configured";
+    return "Bridge setup: " + changes.join(", ");
+}
+/* ------------------------------------------------------------------ */
+/*  PythonScriptPlugin — still needed for execute_python escape hatch */
+/* ------------------------------------------------------------------ */
+function ensurePythonPlugin(uprojectPath) {
+    const raw = fs.readFileSync(uprojectPath, "utf-8");
+    const root = JSON.parse(raw);
+    if (!root.Plugins)
+        root.Plugins = [];
+    const already = root.Plugins.some((p) => p.Name?.toLowerCase() === "pythonscriptplugin");
+    if (already)
+        return false;
+    root.Plugins.unshift({ Name: "PythonScriptPlugin", Enabled: true });
+    fs.writeFileSync(uprojectPath, JSON.stringify(root, null, "\t"));
+    return true;
+}
+/* ------------------------------------------------------------------ */
+/*  C++ Plugin deployment                                             */
+/* ------------------------------------------------------------------ */
+function deployCppPlugin(uprojectPath) {
+    const projectDir = path.dirname(uprojectPath);
+    const pluginsDir = path.join(projectDir, "Plugins");
+    const sourcePluginDir = path.resolve(import.meta.dirname ?? path.dirname(new URL(import.meta.url).pathname), "..", "plugin", "ue_mcp_bridge");
+    if (!fs.existsSync(sourcePluginDir)) {
+        console.error(`[ue-mcp] C++ plugin source not found at ${sourcePluginDir}`);
+        return false;
+    }
+    const targetPluginDir = path.join(pluginsDir, "UE_MCP_Bridge");
+    let anyDeployed = false;
+    function copyRecursive(src, dest) {
+        if (!fs.existsSync(dest)) {
+            fs.mkdirSync(dest, { recursive: true });
+        }
+        for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+            const srcPath = path.join(src, entry.name);
+            const destPath = path.join(dest, entry.name);
+            // Skip build artifacts
+            if (entry.name === "Binaries" ||
+                entry.name === "Intermediate" ||
+                entry.name === "Saved") {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                copyRecursive(srcPath, destPath);
+            }
+            else {
+                const srcBytes = fs.readFileSync(srcPath);
+                let shouldWrite = true;
+                if (fs.existsSync(destPath)) {
+                    const destBytes = fs.readFileSync(destPath);
+                    shouldWrite = !srcBytes.equals(destBytes);
+                }
+                if (shouldWrite) {
+                    fs.writeFileSync(destPath, srcBytes);
+                    anyDeployed = true;
+                }
+            }
+        }
+    }
+    copyRecursive(sourcePluginDir, targetPluginDir);
+    return anyDeployed;
+}
+function ensureCppPluginEnabled(uprojectPath) {
+    const raw = fs.readFileSync(uprojectPath, "utf-8");
+    const root = JSON.parse(raw);
+    if (!root.Plugins)
+        root.Plugins = [];
+    const already = root.Plugins.some((p) => p.Name === "UE_MCP_Bridge");
+    if (already)
+        return false;
+    root.Plugins.push({
+        Name: "UE_MCP_Bridge",
+        Enabled: true,
+    });
+    fs.writeFileSync(uprojectPath, JSON.stringify(root, null, "\t"));
+    return true;
+}
+/* ------------------------------------------------------------------ */
+/*  Engine discovery (used by editor-control)                         */
+/* ------------------------------------------------------------------ */
+export function findEngineInstall(engineAssociation) {
+    if (!engineAssociation)
+        return null;
+    const guidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    if (guidRegex.test(engineAssociation)) {
+        return findEngineByGuid(engineAssociation);
+    }
+    return findLauncherEngine(engineAssociation);
+}
+function findEngineByGuid(guid) {
+    try {
+        const output = execSync(`reg query "HKCU\\SOFTWARE\\Epic Games\\Unreal Engine\\Builds" /v "${guid}"`, { stdio: "pipe", encoding: "utf-8" });
+        const match = output.match(/REG_SZ\s+(.+)/);
+        if (match) {
+            const p = match[1].trim();
+            if (fs.existsSync(p))
+                return p;
+        }
+    }
+    catch {
+        // registry key not found
+    }
+    return null;
+}
+function findLauncherEngine(association) {
+    const launcherDat = path.join(process.env.PROGRAMDATA || "C:\\ProgramData", "Epic", "UnrealEngineLauncher", "LauncherInstalled.dat");
+    if (fs.existsSync(launcherDat)) {
+        try {
+            const data = JSON.parse(fs.readFileSync(launcherDat, "utf-8"));
+            for (const entry of data.InstallationList ?? []) {
+                if (entry.AppName?.toLowerCase() ===
+                    `ue_${association}`.toLowerCase()) {
+                    if (fs.existsSync(entry.InstallLocation)) {
+                        return entry.InstallLocation;
+                    }
+                }
+            }
+        }
+        catch {
+            // malformed manifest
+        }
+    }
+    for (const root of [
+        "C:\\Program Files\\Epic Games",
+        "D:\\Program Files\\Epic Games",
+        "C:\\Epic Games",
+        "D:\\Epic Games",
+    ]) {
+        const candidate = path.join(root, `UE_${association}`);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+//# sourceMappingURL=deployer.js.map

package/dist/deployer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployer.js","sourceRoot":"","sources":["../src/deployer.ts"],"names":[],"mappings":"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"}

package/dist/editor-control.d.ts

@@ -0,0 +1,15 @@
+import type { ProjectContext } from "./project.js";
+export declare function startEditor(project: ProjectContext): Promise<{
+    success: boolean;
+    message: string;
+}>;
+export declare function stopEditor(force?: boolean): Promise<{
+    success: boolean;
+    message: string;
+}>;
+export declare function restartEditor(project: ProjectContext, bridge?: {
+    connect: (timeoutMs?: number) => Promise<void>;
+}): Promise<{
+    success: boolean;
+    message: string;
+}>;

package/dist/editor-control.js

@@ -0,0 +1,181 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawn, execSync } from "child_process";
+import * as net from "net";
+let editorProcess = null;
+function findUEBuildTool() {
+    const envPath = process.env.UE_BUILD_TOOL_PATH;
+    if (envPath)
+        return envPath;
+    const versions = ["5.7", "5.6", "5.5", "5.4", "5.3"];
+    const basePath = "C:/Program Files/Epic Games";
+    for (const version of versions) {
+        const buildToolPath = path.join(basePath, `UE_${version}`, "Engine", "Build", "BatchFiles", "Build.bat");
+        if (fs.existsSync(buildToolPath)) {
+            return buildToolPath;
+        }
+    }
+    return null;
+}
+function findEditorExecutable() {
+    const envPath = process.env.UE_EDITOR_PATH;
+    if (envPath)
+        return envPath;
+    const buildTool = findUEBuildTool();
+    if (!buildTool)
+        return null;
+    const engineRoot = path.resolve(buildTool, "..", "..", "..", "..");
+    const editorExe = path.join(engineRoot, "Engine", "Binaries", "Win64", "UnrealEditor.exe");
+    if (fs.existsSync(editorExe)) {
+        return editorExe;
+    }
+    return null;
+}
+function isEditorRunning() {
+    try {
+        execSync('tasklist /FI "IMAGENAME eq UnrealEditor.exe" | find /I "UnrealEditor.exe"', { stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function isBridgeAvailable(host = "localhost", port = 9877, timeoutMs = 1000) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        let resolved = false;
+        const timer = setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                socket.destroy();
+                resolve(false);
+            }
+        }, timeoutMs);
+        socket.once("connect", () => {
+            if (!resolved) {
+                resolved = true;
+                clearTimeout(timer);
+                socket.destroy();
+                resolve(true);
+            }
+        });
+        socket.once("error", () => {
+            if (!resolved) {
+                resolved = true;
+                clearTimeout(timer);
+                resolve(false);
+            }
+        });
+        socket.connect(port, host);
+    });
+}
+async function waitForBridge(maxWaitSeconds = 120, checkIntervalMs = 2000) {
+    const startTime = Date.now();
+    const maxWaitMs = maxWaitSeconds * 1000;
+    while (Date.now() - startTime < maxWaitMs) {
+        if (await isBridgeAvailable()) {
+            return true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, checkIntervalMs));
+    }
+    return false;
+}
+export async function startEditor(project) {
+    if (isEditorRunning()) {
+        return { success: false, message: "Editor is already running" };
+    }
+    const editorExe = findEditorExecutable();
+    if (!editorExe) {
+        return {
+            success: false,
+            message: "Unreal Editor executable not found. Set UE_EDITOR_PATH environment variable or install UE5.3+ to default location.",
+        };
+    }
+    if (!project.projectPath) {
+        return { success: false, message: "No project loaded. Use project(action='set_project') first." };
+    }
+    try {
+        editorProcess = spawn(editorExe, [project.projectPath], {
+            stdio: "ignore",
+            detached: true,
+        });
+        editorProcess.unref();
+        // Wait for bridge to become available (editor fully started)
+        const bridgeAvailable = await waitForBridge(120, 2000);
+        if (!bridgeAvailable) {
+            return {
+                success: false,
+                message: "Editor launched but bridge did not become available within 120 seconds. Editor may still be starting up.",
+            };
+        }
+        return { success: true, message: `Editor launched and bridge available: ${editorExe}` };
+    }
+    catch (error) {
+        return {
+            success: false,
+            message: `Failed to launch editor: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+export async function stopEditor(force = false) {
+    if (!isEditorRunning()) {
+        return { success: false, message: "Editor is not running" };
+    }
+    try {
+        if (force) {
+            execSync('taskkill /F /IM UnrealEditor.exe', { stdio: "pipe" });
+            editorProcess = null;
+            return { success: true, message: "Editor force-killed" };
+        }
+        // Graceful close - sends WM_CLOSE, allows save dialogs
+        execSync('taskkill /IM UnrealEditor.exe', { stdio: "pipe" });
+        // Wait up to 10 seconds for editor to close gracefully
+        for (let i = 0; i < 10; i++) {
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+            if (!isEditorRunning()) {
+                editorProcess = null;
+                return { success: true, message: "Editor closed successfully" };
+            }
+        }
+        // Graceful close failed — force kill
+        execSync('taskkill /F /IM UnrealEditor.exe', { stdio: "pipe" });
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        editorProcess = null;
+        if (!isEditorRunning()) {
+            return { success: true, message: "Editor force-killed after graceful close timed out" };
+        }
+        return {
+            success: false,
+            message: "Editor still running after force kill attempt. Close manually.",
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            message: `Failed to stop editor: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+export async function restartEditor(project, bridge) {
+    const stopResult = await stopEditor();
+    if (!stopResult.success && isEditorRunning()) {
+        return { success: false, message: `Failed to stop editor: ${stopResult.message}` };
+    }
+    // Wait for process to fully terminate and release locks
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+    const startResult = await startEditor(project);
+    if (!startResult.success) {
+        return startResult;
+    }
+    // Reconnect the bridge if provided
+    if (bridge) {
+        try {
+            await bridge.connect(5000);
+        }
+        catch {
+            // Bridge reconnect timer will handle it
+        }
+    }
+    return startResult;
+}
+//# sourceMappingURL=editor-control.js.map