zandronum-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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/PROTOCOL.md

@@ -0,0 +1,51 @@
+# Bridge protocol (v1)
+
+The single source of truth for the wire contract between the **engine bridge**
+(`engine-bridge/overlay/mcp_bridge.cpp`) and the **MCP server** (`src/`).
+
+- **Transport:** loopback TCP, `127.0.0.1` only. Instance _N_ listens on
+  `ZANDRONUM_BRIDGE_PORT + (N - 1)`.
+- **Framing:** newline-delimited JSON (NDJSON). One JSON object per line.
+- **Versioning:** every message carries `"v"`. The client checks the `hello`
+  version and refuses to proceed on mismatch. Bump `v` ONLY when this contract
+  changes (independent of npm semver and of the engine tag).
+
+## Messages
+
+### engine → MCP
+
+`hello` — sent once, immediately on connect. `caps` lists what the bridge
+supports so the client can degrade gracefully:
+```json
+{"v":1,"t":"hello","engine":"zandronum","bridge":"0.2.0","caps":["cmd","event"]}
+```
+
+`out` — one line of console output, streamed asynchronously:
+```json
+{"v":1,"t":"out","level":0,"text":"Unknown actor 'DoomImp'"}
+```
+
+### MCP → engine
+
+`cmd` — a console command to execute:
+```json
+{"v":1,"t":"cmd","text":"summon DoomImp ; echo __MCPDONE_a1__"}
+```
+
+`event` — a raw input event posted via `D_PostEvent` (requires the `event` cap).
+Fire-and-forget; the engine sends no reply. Menus read GUI key events
+(`evtype=4` EV_GUI_Event, `subtype=1` EV_GUI_KeyDown, `data1=GK_*`):
+```json
+{"v":1,"t":"event","evtype":4,"subtype":1,"data1":10,"data2":0}
+```
+
+## Correlation
+
+The bridge is intentionally dumb — it does not match output to commands. The MCP
+server appends `; echo <sentinel>` to each command, then collects every `out`
+line until it sees the sentinel echoed back. Because console output is a single
+shared stream, **commands must be issued serially per instance.**
+
+The bridge's only job: feed `text` to `AddCommandString`, and mirror every
+printed line back as an `out` message. Everything else is the server's problem
+(which is exactly why almost all of the code — and the tests — live in TS).

package/README.md

@@ -0,0 +1,118 @@
+<p align="center">
+  <img src="assets/zandromcp.png" alt="zandronum-mcp" width="200">
+</p>
+
+# zandronum-mcp
+
+Let an AI assistant supercharge Zandronum development from your editor: Write C++ code, ACS, DECORATE, fix bugs, the works.
+
+
+## Setup
+
+**Easiest:** grab a prebuilt, bridge-patched engine from
+[Releases](https://github.com/rc4l/ZandronumMCP/releases) (Windows for now), set
+`ZANDRONUM_EXE` to it, and add the server with `npx` (see "Add it to your client").
+No source build.
+
+To build it yourself — one-time, in order (redo only when you update Zandronum):
+
+1. You: Clone the Zandronum source.
+2. You: Compile and build Zandronum.
+3. You: Build this server — `npm run build` (needs Node 20+).
+4. You: Point your MCP client at it (see below).
+5. Your AI Agent: applies the bridge patch and rebuilds the engine.
+6. You: Tell your agent to launch the game and start working.
+
+## Patch Zandronum
+
+Point the patch script at your Zandronum source tree:
+
+```bash
+node engine-bridge/apply-bridge.mjs --src path/to/zandronum
+```
+
+It copies the overlay files in and adds a few one-line, idempotent hooks; re-running
+skips anything already applied. `--revert` removes the overlay files.
+
+## Build Zandronum
+
+Compiling Zandronum is Zandronum's own build, not something this repo provides — the
+patch just adds source files to its existing CMake build. If you've never built it,
+start from the official guides at <https://wiki.zandronum.com/> ("Compiling
+Zandronum") to get the toolchain set up.
+
+Then build as usual:
+
+- Windows: however you normally build it.
+- Linux / macOS: `cmake -B build -DCMAKE_BUILD_TYPE=Release . && cmake --build build`
+  from the source tree.
+
+The bridge builds on all three (Winsock on Windows, BSD sockets elsewhere).
+
+## Build this server
+
+```bash
+npm install
+npm run build
+```
+
+That creates `dist/server.js`, which is what your MCP client runs.
+
+## Add it to your client
+
+Most clients (Claude Code, Claude Desktop, Cursor, ...) take a JSON block. Using the
+published package (no clone needed):
+
+```json
+{
+  "mcpServers": {
+    "zandronum": {
+      "command": "npx",
+      "args": ["-y", "zandronum-mcp"],
+      "env": {
+        "ZANDRONUM_BRIDGE_HOST": "127.0.0.1",
+        "ZANDRONUM_BRIDGE_PORT": "7777",
+        "ZANDRONUM_EXE": "C:/path/to/zandronum.exe"
+      }
+    }
+  }
+}
+```
+
+Claude Code one-liner: `claude mcp add zandronum -- npx -y zandronum-mcp`.
+
+From a local build instead? Use `"command": "node"` with the path to your
+`dist/server.js`. Either way, set `ZANDRONUM_EXE` to the patched binary if you want
+the assistant to launch the game itself. Restart the client to pick up the server.
+
+## Run
+
+Launch the patched build with the bridge on:
+
+```powershell
+# Windows
+$env:ZANDRONUM_BRIDGE_PORT = "7777"; ./zandronum.exe -iwad freedoom2.wad
+```
+
+```bash
+# Linux / macOS
+ZANDRONUM_BRIDGE_PORT=7777 ./zandronum -iwad freedoom2.wad
+```
+
+The bridge only starts when that variable is set, so a normal launch is unaffected.
+Instance 1 uses 7777, instance 2 uses 7778, and so on.
+
+Then ask the assistant to do things. Some of the tools:
+
+- run_command — run any console command
+- list_actor_classes — list the actors the game knows about
+- summon — spawn an actor
+- give — give yourself an item
+- load_map — load a map by name (MAP01, E1M1, ...)
+
+## Dev
+
+```bash
+npm test
+npm run coverage
+```

package/dist/acs/bytecode.d.ts

@@ -0,0 +1,6 @@
+export interface BytecodeNames {
+    functions: string[];
+    namedScripts: string[];
+}
+/** Extract function + named-script names from a BEHAVIOR lump buffer. */
+export declare function parseBehaviorNames(lump: Buffer): BytecodeNames;

package/dist/acs/bytecode.js

@@ -0,0 +1,68 @@
+// Read function and named-script names out of a compiled ACS BEHAVIOR lump, for
+// mods that ship bytecode but no source. Ports the engine's chunk logic
+// (FBehavior load + FindChunk, p_acs.cpp): FNAM = function names, SNAM = named
+// scripts. Numbered scripts have no names in bytecode (their source #define
+// aliases are compiled away) — only the source indexer can recover those.
+const MAGIC_ACS0 = 0x00534341; // "ACS\0"
+const MAGIC_ACSE = 0x45534341; // "ACSE"
+const MAGIC_ACSe = 0x65534341; // "ACSe"
+const ID_FNAM = 0x4d414e46; // "FNAM"
+const ID_SNAM = 0x4d414e53; // "SNAM"
+/** Where the chunk region lives + how far it runs. null if not chunked bytecode. */
+function locateChunks(lump) {
+    if (lump.length < 8)
+        return null;
+    const magic = lump.readUInt32LE(0);
+    if (magic === MAGIC_ACSE || magic === MAGIC_ACSe) {
+        return { offset: lump.readUInt32LE(4), end: lump.length };
+    }
+    if (magic === MAGIC_ACS0) {
+        // Old header may embed enhanced chunks: two DWORDs sit just before the
+        // directory — [chunks offset][pretag]. (p_acs.cpp:2407-2419)
+        const dirofs = lump.readUInt32LE(4);
+        if (dirofs >= 24 && dirofs <= lump.length) {
+            const pretag = lump.readUInt32LE(dirofs - 4);
+            if (pretag === MAGIC_ACSE || pretag === MAGIC_ACSe) {
+                return { offset: lump.readUInt32LE(dirofs - 8), end: dirofs - 8 };
+            }
+        }
+    }
+    return null;
+}
+/** Walk the chunk list ([id][size][data]) for a chunk id; -1 if absent. */
+function findChunk(lump, region, id) {
+    let o = region.offset;
+    while (o + 8 <= region.end) {
+        if (lump.readUInt32LE(o) === id)
+            return o;
+        o += lump.readUInt32LE(o + 4) + 8;
+    }
+    return -1;
+}
+/** A name chunk: [count][offset×count][nul-terminated strings], offsets relative to chunk+8. */
+function readNameChunk(lump, chunkStart) {
+    const base = chunkStart + 8;
+    const count = lump.readUInt32LE(base);
+    const names = [];
+    for (let i = 0; i < count; i++) {
+        const start = base + lump.readUInt32LE(base + 4 + i * 4);
+        let end = start;
+        while (end < lump.length && lump[end] !== 0)
+            end++;
+        names.push(lump.toString("latin1", start, end));
+    }
+    return names;
+}
+/** Extract function + named-script names from a BEHAVIOR lump buffer. */
+export function parseBehaviorNames(lump) {
+    const region = locateChunks(lump);
+    if (!region)
+        return { functions: [], namedScripts: [] };
+    const fnam = findChunk(lump, region, ID_FNAM);
+    const snam = findChunk(lump, region, ID_SNAM);
+    return {
+        functions: fnam >= 0 ? readNameChunk(lump, fnam) : [],
+        namedScripts: snam >= 0 ? readNameChunk(lump, snam) : [],
+    };
+}
+//# sourceMappingURL=bytecode.js.map

package/dist/acs/bytecode.js.map

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

package/dist/acs/collect.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Collect every compiled ACS bytecode lump in a WAD or PK3: compiled `#library`
+ * lumps (a zip entry that is itself ACS bytecode) plus the BEHAVIOR lump of each
+ * contained map WAD. This is what lets bytecode name-reading work on a
+ * source-less mod, where the scripts live in a compiled library.
+ */
+export declare function collectAcsLumps(buffer: Buffer): Buffer[];

package/dist/acs/collect.js

@@ -0,0 +1,34 @@
+import { parseWad } from "../map/wad.js";
+import { isZip, listZipEntries, readZipEntry } from "../map/zip.js";
+// ACS bytecode magics: "ACS\0", "ACSE", "ACSe".
+const ACS_MAGICS = new Set([0x00534341, 0x45534341, 0x65534341]);
+function looksLikeAcs(buf) {
+    return buf.length >= 4 && ACS_MAGICS.has(buf.readUInt32LE(0));
+}
+function behaviorLumps(wadBuf) {
+    return parseWad(wadBuf)
+        .lumps.filter((l) => l.name === "BEHAVIOR" && l.size > 0)
+        .map((l) => wadBuf.subarray(l.offset, l.offset + l.size));
+}
+/**
+ * Collect every compiled ACS bytecode lump in a WAD or PK3: compiled `#library`
+ * lumps (a zip entry that is itself ACS bytecode) plus the BEHAVIOR lump of each
+ * contained map WAD. This is what lets bytecode name-reading work on a
+ * source-less mod, where the scripts live in a compiled library.
+ */
+export function collectAcsLumps(buffer) {
+    if (looksLikeAcs(buffer))
+        return [buffer]; // a raw compiled .o / BEHAVIOR file
+    if (!isZip(buffer))
+        return behaviorLumps(buffer);
+    const out = [];
+    for (const entry of listZipEntries(buffer)) {
+        const data = readZipEntry(buffer, entry);
+        if (looksLikeAcs(data))
+            out.push(data);
+        else if (entry.name.toLowerCase().endsWith(".wad"))
+            out.push(...behaviorLumps(data));
+    }
+    return out;
+}
+//# sourceMappingURL=collect.js.map

package/dist/acs/collect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.js","sourceRoot":"","sources":["../../src/acs/collect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEpE,gDAAgD;AAChD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;AAEjE,SAAS,YAAY,CAAC,GAAW;IAC/B,OAAO,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,aAAa,CAAC,MAAc;IACnC,OAAO,QAAQ,CAAC,MAAM,CAAC;SACpB,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;SACxD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,IAAI,YAAY,CAAC,MAAM,CAAC;QAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,oCAAoC;IAC/E,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,KAAK,IAAI,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACzC,IAAI,YAAY,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;aAClC,IAAI,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/acs/symbols.d.ts

@@ -0,0 +1,31 @@
+export interface AcsSymbol {
+    kind: "script" | "function";
+    name: string | null;
+    number: number | null;
+    file: string;
+    line: number;
+    /** Script type keyword (OPEN/ENTER/...), if present. */
+    type: string | null;
+}
+export interface AcsIndex {
+    symbols: AcsSymbol[];
+    defines: Record<string, number>;
+}
+/** Parse `#define` / `#libdefine NAME <int>` lines into a name→number map. */
+export declare function parseDefines(text: string): Record<string, number>;
+interface RawDecl {
+    kind: "script" | "function";
+    ref: string;
+    type: string | null;
+    line: number;
+}
+/** Parse `script <ref> [type]` and `function <ret> <name>(` declarations. */
+export declare function parseDeclarations(text: string): RawDecl[];
+/** Build a symbol index across files, resolving script names ↔ numbers via defines. */
+export declare function buildIndex(files: Array<{
+    path: string;
+    text: string;
+}>): AcsIndex;
+/** Find symbols by script number or by name (case-insensitive). */
+export declare function findSymbol(index: AcsIndex, ref: string): AcsSymbol[];
+export {};

package/dist/acs/symbols.js

@@ -0,0 +1,82 @@
+// Static ACS source indexer: parse a mod's .acs files into a symbol index so a
+// profiler "script 1017" can be resolved to its name + file:line. Pure — the
+// server reads the files and feeds (path, text) pairs in.
+const DEFINE_RE = /^\s*#(?:lib)?define\s+(\w+)\s+(-?\d+)\b/;
+const SCRIPT_RE = /^\s*script\s+("[^"]*"|-?\d+|[A-Za-z_]\w*)\s*([A-Za-z_]\w*)?/i;
+const FUNCTION_RE = /^\s*function\s+\w+\s+([A-Za-z_]\w*)\s*\(/i;
+function baseName(path) {
+    const parts = path.split(/[/\\]/);
+    return parts[parts.length - 1];
+}
+/** Parse `#define` / `#libdefine NAME <int>` lines into a name→number map. */
+export function parseDefines(text) {
+    const out = {};
+    for (const line of text.split(/\r?\n/)) {
+        const m = line.match(DEFINE_RE);
+        if (m)
+            out[m[1]] = Number(m[2]);
+    }
+    return out;
+}
+/** Parse `script <ref> [type]` and `function <ret> <name>(` declarations. */
+export function parseDeclarations(text) {
+    const out = [];
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const sm = lines[i].match(SCRIPT_RE);
+        if (sm) {
+            out.push({ kind: "script", ref: sm[1], type: sm[2] ?? null, line: i + 1 });
+            continue;
+        }
+        const fm = lines[i].match(FUNCTION_RE);
+        if (fm)
+            out.push({ kind: "function", ref: fm[1], type: null, line: i + 1 });
+    }
+    return out;
+}
+/** Build a symbol index across files, resolving script names ↔ numbers via defines. */
+export function buildIndex(files) {
+    const defines = {};
+    for (const f of files)
+        Object.assign(defines, parseDefines(f.text));
+    // ACS identifiers are case-insensitive, so resolve define refs that way.
+    const definesLower = {};
+    const reverse = {};
+    for (const [name, num] of Object.entries(defines)) {
+        definesLower[name.toLowerCase()] = num;
+        if (!(num in reverse))
+            reverse[num] = name;
+    }
+    const symbols = [];
+    for (const f of files) {
+        const file = baseName(f.path);
+        for (const d of parseDeclarations(f.text)) {
+            if (d.kind === "function") {
+                symbols.push({ kind: "function", name: d.ref, number: null, file, line: d.line, type: null });
+            }
+            else if (d.ref.startsWith('"')) {
+                symbols.push({ kind: "script", name: d.ref.slice(1, -1), number: null, file, line: d.line, type: d.type });
+            }
+            else if (/^-?\d+$/.test(d.ref)) {
+                const n = Number(d.ref);
+                symbols.push({ kind: "script", name: reverse[n] ?? null, number: n, file, line: d.line, type: d.type });
+            }
+            else {
+                const key = d.ref.toLowerCase();
+                const n = key in definesLower ? definesLower[key] : null;
+                symbols.push({ kind: "script", name: d.ref, number: n, file, line: d.line, type: d.type });
+            }
+        }
+    }
+    return { symbols, defines };
+}
+/** Find symbols by script number or by name (case-insensitive). */
+export function findSymbol(index, ref) {
+    if (/^-?\d+$/.test(ref)) {
+        const n = Number(ref);
+        return index.symbols.filter((s) => s.number === n);
+    }
+    const lower = ref.toLowerCase();
+    return index.symbols.filter((s) => s.name !== null && s.name.toLowerCase() === lower);
+}
+//# sourceMappingURL=symbols.js.map

package/dist/acs/symbols.js.map

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

package/dist/bridge/framing.d.ts

@@ -0,0 +1,15 @@
+import type { BridgeMessage } from "../types.js";
+/** Serialize a message to a single NDJSON line (newline-terminated). */
+export declare function encodeMessage(msg: BridgeMessage): string;
+/**
+ * Streaming NDJSON decoder. Feed it raw socket chunks; it returns whole
+ * messages and buffers any trailing partial line until the rest arrives.
+ *
+ * Pure and I/O-free — this is the most-tested unit in the bridge layer.
+ */
+export declare class NdjsonDecoder {
+    private buffer;
+    push(chunk: string): BridgeMessage[];
+    /** Bytes buffered but not yet terminated by a newline. */
+    get pending(): number;
+}

package/dist/bridge/framing.js

@@ -0,0 +1,45 @@
+/** Serialize a message to a single NDJSON line (newline-terminated). */
+export function encodeMessage(msg) {
+    return JSON.stringify(msg) + "\n";
+}
+/**
+ * Streaming NDJSON decoder. Feed it raw socket chunks; it returns whole
+ * messages and buffers any trailing partial line until the rest arrives.
+ *
+ * Pure and I/O-free — this is the most-tested unit in the bridge layer.
+ */
+export class NdjsonDecoder {
+    buffer = "";
+    push(chunk) {
+        this.buffer += chunk;
+        const messages = [];
+        let newlineIndex;
+        while ((newlineIndex = this.buffer.indexOf("\n")) !== -1) {
+            const line = this.buffer.slice(0, newlineIndex).trim();
+            this.buffer = this.buffer.slice(newlineIndex + 1);
+            if (line.length === 0)
+                continue;
+            const parsed = tryParse(line);
+            if (parsed)
+                messages.push(parsed);
+        }
+        return messages;
+    }
+    /** Bytes buffered but not yet terminated by a newline. */
+    get pending() {
+        return this.buffer.length;
+    }
+}
+function tryParse(line) {
+    try {
+        const obj = JSON.parse(line);
+        if (obj && typeof obj === "object" && typeof obj.t === "string") {
+            return obj;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=framing.js.map

package/dist/bridge/framing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"framing.js","sourceRoot":"","sources":["../../src/bridge/framing.ts"],"names":[],"mappings":"AAEA,wEAAwE;AACxE,MAAM,UAAU,aAAa,CAAC,GAAkB;IAC9C,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IAChB,MAAM,GAAG,EAAE,CAAC;IAEpB,IAAI,CAAC,KAAa;QAChB,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC;QACrB,MAAM,QAAQ,GAAoB,EAAE,CAAC;QACrC,IAAI,YAAoB,CAAC;QACzB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YACzD,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC;YACvD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;YAClD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAChC,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC9B,IAAI,MAAM;gBAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACpC,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,0DAA0D;IAC1D,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,IAAI,CAAC;QACH,MAAM,GAAG,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAQ,GAAqB,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;YACnF,OAAO,GAAoB,CAAC;QAC9B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/bridge/transport.d.ts

@@ -0,0 +1,35 @@
+import { EventEmitter } from "node:events";
+import type { HelloMessage } from "../types.js";
+export interface BridgeClientOptions {
+    host?: string;
+    port: number;
+    commandTimeoutMs?: number;
+}
+/**
+ * Talks to one bridge-patched Zandronum instance over loopback TCP.
+ *
+ * NOTE: console output is a single shared stream, so commands are correlated by
+ * a unique echo sentinel and MUST be issued serially per instance. Callers
+ * should await each runCommand before sending the next.
+ */
+export declare class BridgeClient extends EventEmitter {
+    private socket?;
+    private readonly decoder;
+    private pending;
+    private capsSet;
+    private seq;
+    private readonly host;
+    private readonly port;
+    private readonly commandTimeoutMs;
+    constructor(opts: BridgeClientOptions);
+    connect(): Promise<HelloMessage>;
+    private dispatch;
+    private checkPending;
+    runCommand(text: string): Promise<string[]>;
+    /** Whether the connected bridge advertised a capability in its hello. */
+    supports(cap: string): boolean;
+    /** Post a raw input event to the engine (fire-and-forget; no reply). */
+    sendEvent(evtype: number, subtype: number, data1: number, data2?: number): void;
+    private failAllPending;
+    close(): void;
+}