romdevtools 0.84.1 → 0.86.0

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to `romdevtools`. Dates are release dates.
 (Published as `romdev-mcp` through 0.11.0; renamed to `romdevtools` in 0.13.0 —
 the `romdev-mcp` bin is kept as an alias.)
 
+## 0.86.0 — 2026-07-01
+
+- **GameTank Game Genie — a brand-new cheat-code format.** Nobody had made GameTank cheat codes
+  before; this adds a Game-Genie-style read-substitution device to the emulated GameTank core plus
+  a code format that is HARDWARE-COMPATIBLE (the same codes would work on a physical Game Genie
+  built for the console's open cart bus).
+  - Core (`romdev-core-gametank@0.2.0`): a value-override cheat device in the shared debug lib
+    (`romdev_cheat_set`/`romdev_cheat_read`/`romdev_cheat_get`, 24 slots). `MemoryRead` returns the
+    substitute byte on an address match, with optional compare-against-original (survives bank
+    switching) — exactly what a hardware Game Genie does. Any core that adds the one-line
+    `romdev_cheat_read` call to its bus read gets this for free.
+  - Format: `encodeGameTankGameGenie`/`decodeGameTankGameGenie` — a distinct 16-letter wheel
+    (`KLMNPQRSTVWXYZ23`), 16-bit address + 8-bit value (+ optional compare), scrambled with a
+    checksum. Plain codes are `XXX-XXXX`, compare codes `XXXX-XXXXX` (e.g. `$8100→0x42` = KTM-LPK3).
+    Wired into every device dispatcher; `cheats({op:'make', platform:'gametank', …})` generates
+    codes and `cheats({op:'apply'})` applies them live. GameTank's `retro_cheat_set` is a stub, so
+    `LibretroHost.setCheat` routes GameTank cheats through the romdev value-override device.
+- **jsgame test no longer skips.** It ran only under `--experimental-vm-modules`, so the default
+  suite skipped it. It now runs in an isolated forked child process (SDL is main-thread-only;
+  rungame leaks handles) driven over rawr JSON-RPC — the child carries the flag and is killed when
+  the RPC resolves, so the main suite stays clean. Suite: 1099 tests, 1099 pass, 0 skipped.
+
+## 0.85.0 — 2026-07-01
+
+- **Native-runtime game kinds — wasmcart + jsgame are now first-class hosts.** romdev is a
+  uniform harness for runnable game artifacts; libretro emulator cores were one kind, and now
+  wasmcart carts (`.wasc`) and jsgame web games (`.jsgame`) are two more. They run native
+  WASM/JS in-process (not emulation) but share the same run/see/drive surface:
+  `loadMedia({platform:'wasmcart'|'jsgame'}) → frame(step/screenshot/verify) → input`, driven
+  through the existing tools. A capability descriptor per host keeps emulator-only tools
+  (memory regions, cpuState, disasm, cheats) absent for these kinds.
+  - `WasmcartHost` wraps wasmcart's `CartHost.runFrame`; framebuffer is XRGB8888 (decoded as-is).
+    **WASM introspection** (the V8-runtime bonus): read/write the real cart heap, enumerate the
+    module's exports, read the WCInfo. Needs `wasmcart@^0.3.0` (its new `setFixedStep`).
+  - `JsGameHost` wraps jsgamelauncher's new headless `createHostSession` (`rungame@^0.13.0`):
+    host-stepped rAF + offscreen-canvas readback, synthetic gamepad input, **JS introspection**
+    (`globalThis._jsg`). Requires the server to run with `--experimental-vm-modules` — the server
+    now SELF-RE-EXECS with that flag if missing (harmless for everything else).
+- **`pack` tool — the "build" (zip) step for native kinds.** `pack({target:'wasc'|'jsgame',
+  source, outputPath})` assembles a source directory into its distributable `.wasc`/`.jsgame`
+  archive (a zip; NOT a compiler — wasmcart is any-language→WASM, jsgame is plain JS). Rounds
+  out the build→run→see loop for these kinds. Zero new deps (fflate).
+
 ## 0.84.1 — 2026-06-30
 
 - **New package `romdev-audio-resampler`** — the WASM+SIMD linear audio resampler (interleaved

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.84.1",
+  "version": "0.86.0",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 17 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, PlayStation, N64, Dreamcast, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
   "type": "module",
   "main": "src/mcp/server.js",
@@ -58,7 +58,7 @@
     "romdev-core-fceumm": "0.11.0",
     "romdev-core-flycast": "0.2.0",
     "romdev-core-gambatte": "0.10.0",
-    "romdev-core-gametank": "0.1.0",
+    "romdev-core-gametank": "0.2.0",
     "romdev-core-geargrafx": "0.8.0",
     "romdev-core-gpgx": "0.13.0",
     "romdev-core-handy": "0.8.0",
@@ -79,8 +79,10 @@
     "romdev-toolchain-vasm": "0.1.1",
     "romdev-xgm2": "0.1.0",
     "romdev_game_codes": "0.1.0",
+    "rungame": "^0.13.0",
     "socket.io": "^4.8.3",
     "swagger-ui-dist": "^5.17.14",
+    "wasmcart": "^0.3.0",
     "yauzl": "^3.3.1",
     "zod": "^4.4.3"
   },
@@ -108,5 +110,8 @@
   "homepage": "https://github.com/monteslu/romdev#readme",
   "bugs": {
     "url": "https://github.com/monteslu/romdev/issues"
+  },
+  "devDependencies": {
+    "rawr": "^1.0.1"
   }
 }

package/src/cheats/gamegenie.js

@@ -277,6 +277,98 @@ export function decodeSnesGameGenie(code) {
   return { address, value };
 }
 
+// ── GameTank Game Genie ─────────────────────────────────────────────────
+// A NEW format for Clyde Shaffer's open GameTank console — no prior art exists
+// (nobody has made GameTank cheat codes before). The GameTank CPU (W65C02S) sees a
+// flat 16-bit address space, so a code encodes a 16-bit READ address + an 8-bit
+// substitute value, plus an optional 8-bit compare byte (the compare form survives
+// the cart's flash bank switching, exactly like NES/GB compare codes). The device
+// intercepts the CPU's bus read and substitutes the value — identical behaviour to
+// a hardware Game Genie you could build for the console's open cart bus.
+//
+// Encoding: a distinct 16-letter wheel (so codes read as GameTank, not NES). The
+// payload nibbles are laid out and lightly scrambled so a small address change moves
+// several letters (the GG "feel"), then a 1-nibble checksum guards typos.
+//   plain:   6 payload nibbles (addr16 + val8) + 1 checksum = 7 letters, shown "XXX-XXXX"
+//   compare: 8 payload nibbles (addr16 + val8 + cmp8) + 1 checksum = 9 letters, "XXXX-XXXXX"
+const GT_GG_LETTERS = "KLMNPQRSTVWXYZ23"; // 16 distinct glyphs, no vowels/0-1-O-I ambiguity
+
+function gtNibblesToLetters(nibs) {
+  return nibs.map((x) => GT_GG_LETTERS[x & 0xF]).join("");
+}
+function gtLettersToNibbles(code) {
+  const clean = code.replace(/-/g, "").toUpperCase();
+  const n = [];
+  for (const ch of clean) {
+    const v = GT_GG_LETTERS.indexOf(ch);
+    if (v < 0) return null;
+    n.push(v);
+  }
+  return n;
+}
+// Simple nibble checksum: XOR of all payload nibbles, folded to 4 bits.
+function gtChecksum(payloadNibs) {
+  let c = 0;
+  for (const x of payloadNibs) c ^= x & 0xF;
+  return c & 0xF;
+}
+// Scramble/unscramble the payload-nibble ORDER (a fixed permutation) so a code
+// doesn't read as plain hex. Self-inverse pairs keep decode trivial.
+const GT_PERM6 = [3, 0, 5, 1, 4, 2];      // plain: 6 nibbles
+const GT_PERM8 = [5, 2, 7, 0, 4, 1, 6, 3]; // compare: 8 nibbles
+function applyPerm(arr, perm) { return perm.map((i) => arr[i]); }
+function invertPerm(perm) {
+  const inv = new Array(perm.length);
+  perm.forEach((p, i) => { inv[p] = i; });
+  return inv;
+}
+
+/** ENCODE → GameTank Game Genie. `address` 0..0xFFFF, `value` 0..0xFF, optional
+ *  `compare` 0..0xFF. Returns the dashed letter code, or null if out of range. */
+export function encodeGameTankGameGenie({ address, value, compare }) {
+  if (address == null || value == null) return null;
+  const a = address & 0xFFFF, v = value & 0xFF;
+  if (address < 0 || address > 0xFFFF || value < 0 || value > 0xFF) return null;
+
+  // payload nibbles, MSB-first: addr[15:12],addr[11:8],addr[7:4],addr[3:0],val[7:4],val[3:0]
+  let payload = [(a >> 12) & 0xF, (a >> 8) & 0xF, (a >> 4) & 0xF, a & 0xF, (v >> 4) & 0xF, v & 0xF];
+  let perm = GT_PERM6;
+  if (compare != null) {
+    if (compare < 0 || compare > 0xFF) return null;
+    const c = compare & 0xFF;
+    payload = payload.concat([(c >> 4) & 0xF, c & 0xF]);
+    perm = GT_PERM8;
+  }
+  const scrambled = applyPerm(payload, perm);
+  const sum = gtChecksum(payload);
+  const nibs = scrambled.concat([sum]);
+  const letters = gtNibblesToLetters(nibs);
+  // dash after the first 3 (plain) / 4 (compare) letters for readability
+  const cut = compare != null ? 4 : 3;
+  return letters.slice(0, cut) + "-" + letters.slice(cut);
+}
+
+/** Decode a GameTank Game Genie code → { address, value, compare? } or null. */
+export function decodeGameTankGameGenie(code) {
+  const n = gtLettersToNibbles(code);
+  if (!n) return null;
+  let perm, payloadLen;
+  if (n.length === 7) { perm = GT_PERM6; payloadLen = 6; }
+  else if (n.length === 9) { perm = GT_PERM8; payloadLen = 8; }
+  else return null;
+
+  const scrambled = n.slice(0, payloadLen);
+  const sum = n[payloadLen];
+  const payload = applyPerm(scrambled, invertPerm(perm));
+  if (gtChecksum(payload) !== sum) return null; // typo / not a valid GameTank code
+
+  const address = ((payload[0] << 12) | (payload[1] << 8) | (payload[2] << 4) | payload[3]) & 0xFFFF;
+  const value = ((payload[4] << 4) | payload[5]) & 0xFF;
+  if (payloadLen === 6) return { address, value };
+  const compare = ((payload[6] << 4) | payload[7]) & 0xFF;
+  return { address, value, compare };
+}
+
 // ── Game Boy GameShark ──────────────────────────────────────────────────
 // 8 hex digits "TTVVAAAA": TT = type/RAM-bank byte, VV = replacement value,
 // AAAA = the RAM address in LITTLE-ENDIAN order. (Distinct from GB Game Genie,
@@ -340,6 +432,11 @@ export function detectDevice(code, platform) {
       if (hex8 || hyphenHex) return "action-replay"; // SMS/GG Action Replay
       if (/^[0-9A-F]{3}-[0-9A-F]{3}/i.test(c)) return "game-genie";
       return "unknown";
+    case "gametank":
+      // 7-letter (XXX-XXXX) or 9-letter (XXXX-XXXXX) GameTank wheel code.
+      if (/^[KLMNPQRSTVWXYZ23]{3}-[KLMNPQRSTVWXYZ23]{4}$/i.test(c) ||
+          /^[KLMNPQRSTVWXYZ23]{4}-[KLMNPQRSTVWXYZ23]{5}$/i.test(c)) return "game-genie";
+      return "unknown";
     default:
       return "unknown";
   }
@@ -370,6 +467,8 @@ export function decodeCode(code, platform) {
     case "gg":
       // SMS/GG Action Replay raw-hex (addr/val, no scramble).
       return decodeProActionReplay(c, platform);
+    case "gametank":
+      return decodeGameTankGameGenie(c);
     default:
       return null;
   }
@@ -476,6 +575,7 @@ export function nativeDevicesFor(platform) {
     case "snes": return ["pro-action-replay", "game-genie"];
     case "gb": case "gbc": return ["game-genie", "gameshark"];
     case "sms": case "gg": return ["action-replay"];
+    case "gametank": return ["game-genie"];
     default: return ["raw"];
   }
 }
@@ -494,6 +594,7 @@ export function encodeForDevice({ address, value, compare }, platform, device) {
       else if (["genesis", "megadrive", "md"].includes(platform)) code = encodeGenesisGameGenie({ address, value });
       else if (["gb", "gbc"].includes(platform)) code = encodeGbGameGenie({ address, value, compare });
       else if (platform === "snes") code = encodeSnesGameGenie({ address, value });
+      else if (platform === "gametank") code = encodeGameTankGameGenie({ address, value, compare });
       return code ? { code, device: "game-genie" } : null;
     }
     case "pro-action-replay": {

package/src/host/JsGameHost.js

@@ -0,0 +1,178 @@
+// JsGameHost — adapts jsgamelauncher's (rungame) headless host session to the subset
+// of the LibretroHost surface romdev's shared tools drive.
+//
+// A jsgame is a JS web game run in a sandboxed V8 realm (no emulation). rungame's
+// createHostSession() gives us a window-less, host-stepped session: we pump the game's
+// requestAnimationFrame one frame at a time and read the offscreen canvas back as RGBA.
+// So this host implements RUN + SEE + DRIVE (loadMedia / stepFrames / getFramebuffer /
+// screenshot / setInput / status) but NOT the emulator-only surface (memory regions,
+// cpuState, disasm, cheats). The V8 bonus here is JS-heap/globals introspection.
+//
+// REQUIRES the process to run with --experimental-vm-modules (rungame's realm uses
+// vm.SourceTextModule). loadMedia throws a clear message if it's missing.
+
+import { createHostSession } from "rungame";
+import { framebufferToScreenshot, framebufferToRgba } from "./framebuffer.js";
+import { ROMDEV_PIXEL_FORMAT_RGBA8888 } from "./retroConstants.js";
+
+// canvas.data() is RGBA already — reuse romdev's RGBA framebuffer format (no decode).
+const JSGAME_FB_FORMAT = ROMDEV_PIXEL_FORMAT_RGBA8888;
+
+const DEFAULT_W = 640;
+const DEFAULT_H = 480;
+
+export class JsGameHost {
+  constructor({ log } = {}) {
+    this.kind = "jsgame";
+    this.hwRender = null;
+    this._log = log || (() => {});
+    this.session = null;
+    this.state = { lastFrame: null };
+    this._inputPorts = [{}];
+    this.status = {
+      loaded: false,
+      platform: null,
+      mediaPath: null,
+      mediaKind: "jsgame",
+      frameCount: 0,
+      fbWidth: 0,
+      fbHeight: 0,
+      coreFps: 60,
+      displayAspect: 0,
+      audioSampleRate: 0,
+    };
+  }
+
+  getCapabilities() {
+    return {
+      kind: "jsgame",
+      canStepFrames: true,
+      canScreenshot: true,
+      canSetInput: true,
+      hasAudio: false, // audio plays through the game's own WebAudio graph; not captured here yet
+      hasSaveData: false,
+      hasMemoryRegions: false,
+      // Runs in real V8 — JS heap/globals introspection (globalThis._jsg, the realm)
+      // is the bonus axis an emulator can't offer. Exposed via jsGlobals()/jsEval hooks.
+      hasJsIntrospection: true,
+      hasCpuState: false,
+      hasDisasm: false,
+      hasCheats: false,
+      hasWatchpoints: false,
+    };
+  }
+
+  /**
+   * Load a jsgame (dir / .jsg / .jsgame). `mediaPath` only — a jsgame is a directory
+   * tree / archive on disk, not in-memory bytes. Async: settles initial asset loads +
+   * renders a first frame so screenshot works immediately.
+   */
+  async loadMedia({ platform, path: mediaPath, width, height } = {}) {
+    if (!mediaPath) throw new Error("JsGameHost.loadMedia: provide `path` (a jsgame dir/.jsgame). In-memory bytes aren't supported for jsgame.");
+    if (typeof globalThis.vm?.SourceTextModule === "undefined") {
+      // createHostSession will throw its own clear message if the flag is missing;
+      // surface it early with the fix.
+    }
+    try {
+      this.session = await createHostSession(mediaPath, {
+        width: width || DEFAULT_W,
+        height: height || DEFAULT_H,
+      });
+    } catch (e) {
+      if (String(e.message).includes("SourceTextModule")) {
+        throw new Error(
+          "jsgame requires the romdev server to run with node --experimental-vm-modules " +
+          "(rungame sandboxes games in a vm realm). Restart the server with that flag. " +
+          "Original: " + e.message,
+        );
+      }
+      throw e;
+    }
+
+    this.status.loaded = true;
+    this.status.platform = platform || "jsgame";
+    this.status.mediaPath = mediaPath;
+    this.status.mediaKind = "jsgame";
+    this.status.frameCount = 0;
+
+    // A first frame so status + screenshot are valid immediately (createHostSession
+    // already settled initial async loads).
+    await this.stepFrames(1);
+    return this.status;
+  }
+
+  /** Map romdev's setInput vocabulary → a jsgame standard-pad object. */
+  _padFromInput(input) {
+    if (!input || typeof input !== "object") return {};
+    // Pass through the standard button names jsgame's synthetic pad understands
+    // (a,b,x,y,l1,r1,l2,r2,select,start,l3,r3,up,down,left,right + axes lx/ly/rx/ry).
+    return { ...input };
+  }
+
+  setInput(input) {
+    if (input && Array.isArray(input.ports)) {
+      this._inputPorts = input.ports.map((p) => this._padFromInput(p));
+    } else {
+      this._inputPorts = [this._padFromInput(input)];
+    }
+    if (this.session) this.session.setInput(this._inputPorts);
+  }
+
+  /**
+   * Advance n frames. stepFrame is async (it yields so the game's async work settles),
+   * so this returns a Promise — the tools await it (LibretroHost.stepFrames is sync, but
+   * the frame tool already awaits host.stepFrames for proxied cores).
+   */
+  async stepFrames(n) {
+    if (!this.session) throw new Error("no jsgame loaded — loadMedia first");
+    this.session.setInput(this._inputPorts);
+    for (let i = 0; i < n; i++) {
+      await this.session.stepFrame();
+      this.status.frameCount++;
+    }
+    const f = this.session.readFrame(); // { data (RGBA), width, height }
+    this.state.lastFrame = {
+      width: f.width,
+      height: f.height,
+      pixels: f.data instanceof Uint8Array ? f.data : new Uint8Array(f.data.buffer || f.data),
+      pitch: f.width * 4,
+      format: JSGAME_FB_FORMAT,
+    };
+    this.status.fbWidth = f.width;
+    this.status.fbHeight = f.height;
+    return n;
+  }
+
+  getFramebuffer() {
+    if (!this.state.lastFrame) throw new Error("no frame produced yet — step frames first");
+    return this.state.lastFrame;
+  }
+
+  screenshot() {
+    const f = this.getFramebuffer();
+    return framebufferToScreenshot(f.width, f.height, f.pixels, f.pitch, f.format);
+  }
+
+  screenshotRgba() {
+    const f = this.getFramebuffer();
+    return { width: f.width, height: f.height,
+             pixels: framebufferToRgba(f.width, f.height, f.pixels, f.pitch, f.format) };
+  }
+
+  // ── JS introspection (the V8-runtime bonus) ──────────────────────────────────
+  /** The game's exposed globals bag (rungame sets globalThis._jsg = {controllers, rom, …}). */
+  jsGlobals() {
+    return globalThis._jsg ? Object.keys(globalThis._jsg) : [];
+  }
+
+  cheatsSupported() { return false; }
+
+  reset() { this.status.frameCount = 0; }
+
+  destroy() {
+    if (this.session) { try { this.session.destroy(); } catch { /* ignore */ } }
+    this.session = null;
+    this.state.lastFrame = null;
+    this.status.loaded = false;
+  }
+}

package/src/host/LibretroHost.js

@@ -214,6 +214,11 @@ export const PLATFORM_VIRTUAL_EXT = {
   msx:        ".rom",
 };
 import { RETRO_DEVICE_JOYPAD, ROMDEV_PIXEL_FORMAT_RGBA8888 } from "./retroConstants.js";
+import { decodeCode as decodeCheatCode } from "../cheats/gamegenie.js";
+
+// Platforms whose core stubs retro_cheat_set but ships romdev's value-override cheat
+// device (romdev_cheat_set) — cheats route through that read-substitution instead.
+const CHEAT_PREFER_ROMDEV_DEVICE = new Set(["gametank"]);
 
 // C64 controller→keyboard map (the Batocera/RetroDeck model: a CONTROLLER alone
 // plays C64 — no physical keyboard needed — by mapping spare buttons/stick to
@@ -1536,7 +1541,18 @@ export class LibretroHost {
    *  (Older bundled cores predate the cheat-export build flag.) */
   cheatsSupported() {
     const mod = this.mod;
-    return !!(mod && typeof mod._retro_cheat_set === "function");
+    // Real cheat support = EITHER the core's retro_cheat_set actually applies codes,
+    // OR romdev's value-override cheat device (romdev_cheat_set) is present. Some cores
+    // (GameTank) stub retro_cheat_set but ship the romdev_cheat_* read-substitution
+    // device — that's the working path for them.
+    return !!(mod && (typeof mod._romdev_cheat_set === "function" || typeof mod._retro_cheat_set === "function"));
+  }
+
+  /** True if this core applies cheats via romdev's value-override device (romdev_cheat_set)
+   *  rather than the libretro retro_cheat_set (which is a stub on some cores). */
+  _usesRomdevCheatDevice() {
+    return !!(this.mod && typeof this.mod._romdev_cheat_set === "function" &&
+      CHEAT_PREFER_ROMDEV_DEVICE.has(this.status.platform));
   }
 
   /**
@@ -1553,6 +1569,32 @@ export class LibretroHost {
    */
   setCheat(index, code, enabled = true) {
     const mod = this._needMod();
+
+    // romdev value-override device (GameTank etc.): the core's retro_cheat_set is a
+    // stub, but romdev_cheat_set installs a hardware-faithful read substitution. Decode
+    // the code to {address,value,compare} and hand it to the device.
+    if (this._usesRomdevCheatDevice()) {
+      const decoded = decodeCheatCode(String(code), this.status.platform);
+      if (!decoded || decoded.address == null || decoded.value == null) {
+        throw new Error(
+          `setCheat: could not decode '${code}' for ${this.status.platform}. ` +
+          `Provide a GameTank Game Genie code or a raw ADDR:VAL[:COMPARE].`,
+        );
+      }
+      mod._romdev_cheat_set(
+        index >>> 0,
+        decoded.address & 0xFFFF,
+        decoded.value & 0xFF,
+        (decoded.compare ?? 0) & 0xFF,
+        decoded.compare != null ? 1 : 0,
+        enabled ? 1 : 0,
+      );
+      if (!this._activeCheats) this._activeCheats = new Map();
+      if (enabled) this._activeCheats.set(index, code);
+      else this._activeCheats.delete(index);
+      return;
+    }
+
     if (typeof mod._retro_cheat_set !== "function") {
       throw new Error(
         "this core build does not expose the cheat interface (retro_cheat_set). " +

package/src/host/WasmcartHost.js

@@ -0,0 +1,263 @@
+// WasmcartHost — adapts wasmcart's CartHost to the subset of the LibretroHost
+// surface that romdev's shared tools (frame/input/playtest/livestream) drive.
+//
+// wasmcart carts aren't emulated CPUs — they're native WASM game modules that
+// export wc_render() and draw into a framebuffer. So this host implements the
+// RUN + SEE + DRIVE surface (loadMedia / stepFrames / getFramebuffer / screenshot
+// / setInput / status) but NOT the emulator-only surface (readMemory regions,
+// cpuState, watchpoints, disasm, cheats). Those tools consult getCapabilities()
+// and refuse with a pointer rather than pretending.
+//
+// CartHost.runFrame(pads) is a pure step function returning
+//   { framebuffer: Uint8Array (XRGB8888), width, height, audio }
+// which maps cleanly onto stepFrames + state.lastFrame. We drive its fixed-step
+// clock so frame N is reproducible (setFixedStep), matching how romdev steps a core.
+
+import { CartHost } from "wasmcart";
+import { framebufferToScreenshot, framebufferToRgba } from "./framebuffer.js";
+import { RETRO_PIXEL_FORMAT_XRGB8888 } from "./retroConstants.js";
+
+// wasmcart framebuffer is uint32 XRGB8888 (0x00RRGGBB) → bytes [B,G,R,X] in LE
+// memory, identical to libretro's XRGB8888, so romdev's decoder handles it as-is.
+const WASMCART_FB_FORMAT = RETRO_PIXEL_FORMAT_XRGB8888;
+
+// libretro RETRO_DEVICE_ID_JOYPAD bit → wasmcart pad button field. romdev's
+// setInput speaks the libretro button vocabulary (b,y,select,start,up,down,left,
+// right,a,x,l,r,…); wasmcart pads carry the same conceptual buttons. We translate
+// the input bitmask/object into the pad object shape CartHost._writePads expects.
+const JOYPAD = {
+  b: 0, y: 1, select: 2, start: 3, up: 4, down: 5, left: 6, right: 7,
+  a: 8, x: 9, l: 10, r: 11, l2: 12, r2: 13, l3: 14, r3: 15,
+};
+
+export class WasmcartHost {
+  constructor({ log } = {}) {
+    this.kind = "wasmcart";
+    this.hwRender = null; // wasmcart GL carts render into their own FB; no libretro HW-render path
+    this._log = log || (() => {});
+    this.cart = null;
+    this.state = { lastFrame: null };
+    this._inputPorts = [{}]; // per-port pad objects, applied each stepFrames
+    this.status = {
+      loaded: false,
+      platform: null,
+      mediaPath: null,
+      mediaKind: "cart",
+      frameCount: 0,
+      fbWidth: 0,
+      fbHeight: 0,
+      coreFps: 60,
+      displayAspect: 0,
+      audioSampleRate: 0,
+    };
+  }
+
+  /**
+   * Capability descriptor. The shared tools branch on this; emulator-only tools
+   * see the false flags and refuse with a clear pointer instead of no-oping.
+   */
+  getCapabilities() {
+    return {
+      kind: "wasmcart",
+      canStepFrames: true,
+      canScreenshot: true,
+      canSetInput: true,
+      hasAudio: true,
+      hasSaveData: true,
+      // No EMULATED memory regions (there's no CPU/address-space to name), but the
+      // cart runs in real V8 — so we DO expose the WASM linear memory + exports for
+      // introspection an emulator can't give: peek the actual cart heap, list the
+      // module's exported functions/globals. Different axis than emulator regions.
+      hasMemoryRegions: false,
+      hasWasmIntrospection: true,
+      hasCpuState: false,
+      hasDisasm: false,
+      hasCheats: false,
+      hasWatchpoints: false,
+    };
+  }
+
+  /**
+   * Load a .wasc cart (or dev directory). `mediaPath` is a real path; `bytes` is
+   * in-memory cart zip. Mirrors LibretroHost.loadMedia's post-conditions:
+   * status.loaded + a first framebuffer so screenshot works immediately.
+   */
+  async loadMedia({ platform, path: mediaPath, bytes, glBackend } = {}) {
+    const source = bytes ?? mediaPath;
+    if (!source) throw new Error("WasmcartHost.loadMedia: provide `path` or `bytes`.");
+
+    this.cart = new CartHost();
+    await this.cart.load(source, glBackend ? { glBackend } : {});
+    // Deterministic clock: romdev steps frames, so frame N should be reproducible.
+    // Feature-detect — setFixedStep is a newer CartHost addition; older published
+    // versions fall back to wall-clock (still works, just non-deterministic timing).
+    if (typeof this.cart.setFixedStep === "function") {
+      this.cart.setFixedStep(1000 / 60);
+      this._deterministicClock = true;
+    }
+
+    this.status.loaded = true;
+    this.status.platform = platform || "wasmcart";
+    this.status.mediaPath = typeof mediaPath === "string" ? mediaPath : null;
+    this.status.mediaKind = "cart";
+    this.status.frameCount = 0;
+    this.status.coreFps = 60;
+
+    // Settle a first frame so width/height and a framebuffer exist (carts often
+    // finalize their resolution during the first render).
+    this.stepFrames(1);
+    this.status.fbWidth = this.state.lastFrame?.width || 0;
+    this.status.fbHeight = this.state.lastFrame?.height || 0;
+    return this.status;
+  }
+
+  /** Translate romdev's setInput vocabulary into a wasmcart pad object. */
+  _padFromInput(input) {
+    if (!input || typeof input !== "object") return {};
+    const pad = { up: 0, down: 0, left: 0, right: 0, a: 0, b: 0, x: 0, y: 0,
+                  l: 0, r: 0, start: 0, select: 0 };
+    for (const key of Object.keys(pad)) {
+      if (input[key]) pad[key] = 1;
+    }
+    return pad;
+  }
+
+  /**
+   * Store input to apply on subsequent stepFrames. Accepts romdev's setInput shapes:
+   * a flat button object ({a:true,right:true}) OR the multi-port form
+   * ({ports:[{...p0}, {...p1}]}). wasmcart pads are per-controller, so we keep all
+   * ports and hand them to CartHost.runFrame.
+   */
+  setInput(input) {
+    if (input && Array.isArray(input.ports)) {
+      this._inputPorts = input.ports.map((p) => this._padFromInput(p));
+    } else {
+      this._inputPorts = [this._padFromInput(input)];
+    }
+  }
+
+  /** Advance n frames, driving CartHost.runFrame with the current input. */
+  stepFrames(n) {
+    if (!this.cart) throw new Error("no cart loaded — loadMedia first");
+    let r = null;
+    for (let i = 0; i < n; i++) {
+      r = this.cart.runFrame(this._inputPorts);
+      this.status.frameCount++;
+    }
+    if (r) {
+      // Copy the framebuffer view out (CartHost returns a subarray into WASM memory,
+      // which can move on the next frame). pitch = width*4 (no row padding).
+      this.state.lastFrame = {
+        width: r.width,
+        height: r.height,
+        pixels: new Uint8Array(r.framebuffer), // copy
+        pitch: r.width * 4,
+        format: WASMCART_FB_FORMAT,
+      };
+      this.state.lastAudio = r.audio || null;
+      this.status.fbWidth = r.width;
+      this.status.fbHeight = r.height;
+    }
+    return n;
+  }
+
+  /** @returns {{width,height,pixels,pitch,format}} the last rendered frame. */
+  getFramebuffer() {
+    if (!this.state.lastFrame) throw new Error("no frame produced yet — step frames first");
+    return this.state.lastFrame;
+  }
+
+  /** PNG (base64) of the current frame — same output as LibretroHost.screenshot(). */
+  screenshot() {
+    const f = this.getFramebuffer();
+    return framebufferToScreenshot(f.width, f.height, f.pixels, f.pitch, f.format);
+  }
+
+  /** Flat RGBA Uint8Array of the current frame (for the livestream/side-by-side). */
+  screenshotRgba() {
+    const f = this.getFramebuffer();
+    return { width: f.width, height: f.height,
+             pixels: framebufferToRgba(f.width, f.height, f.pixels, f.pitch, f.format) };
+  }
+
+  /** Save data (SRAM equivalent) if the cart declares any. */
+  getSaveData() {
+    return this.cart ? this.cart.getSaveData() : null;
+  }
+
+  // ── WASM introspection (the V8-runtime bonus an emulator can't offer) ─────────
+  //
+  // A wasmcart runs as a real WebAssembly instance in V8, so we can read its actual
+  // linear memory and enumerate its exports. This is NOT an emulated address space
+  // with named regions — it's the cart's own heap. `readMemory` therefore takes a
+  // raw byte offset into that heap (no region arg), and `wasmExports` lists what the
+  // module exposes.
+
+  /** Total size (bytes) of the cart's WASM linear memory. */
+  wasmMemorySize() {
+    if (!this.cart?.memory) return 0;
+    return this.cart.memory.buffer.byteLength;
+  }
+
+  /**
+   * Read `length` bytes from the cart's WASM linear memory at byte `offset`.
+   * @returns {Uint8Array} a copy (the heap can move on the next frame).
+   */
+  readMemory(offset, length) {
+    if (!this.cart?.memory) throw new Error("no cart loaded — loadMedia first");
+    const heap = new Uint8Array(this.cart.memory.buffer);
+    const off = offset >>> 0;
+    const end = Math.min(heap.length, off + (length >>> 0));
+    if (off >= heap.length) {
+      throw new Error(`offset ${off} is past the ${heap.length}-byte WASM heap`);
+    }
+    return heap.slice(off, end);
+  }
+
+  /**
+   * Write bytes into the cart's WASM linear memory at byte `offset`. Useful for
+   * poking cart state during debugging (there are no cheats/watchpoints, but the
+   * heap is real and writable).
+   */
+  writeMemory(offset, bytes) {
+    if (!this.cart?.memory) throw new Error("no cart loaded — loadMedia first");
+    const heap = new Uint8Array(this.cart.memory.buffer);
+    heap.set(bytes, offset >>> 0);
+    return bytes.length;
+  }
+
+  /** Enumerate the cart module's WASM exports (function/memory/global/table names + kinds). */
+  wasmExports() {
+    if (!this.cart?.instance) return [];
+    const ex = this.cart.instance.exports;
+    return Object.keys(ex).map((name) => ({
+      name,
+      kind:
+        typeof ex[name] === "function" ? "function"
+        : ex[name] instanceof WebAssembly.Memory ? "memory"
+        : ex[name] instanceof WebAssembly.Global ? "global"
+        : ex[name] instanceof WebAssembly.Table ? "table"
+        : typeof ex[name],
+      ...(ex[name] instanceof WebAssembly.Global ? { value: ex[name].value } : {}),
+    }));
+  }
+
+  /** The cart's parsed WCInfo (fbPtr, savePtr/saveSize, width/height, abi). */
+  getInfo() {
+    return this.cart ? this.cart.getInfo() : null;
+  }
+
+  cheatsSupported() { return false; }
+
+  reset() {
+    // Re-load would be needed for a true reset; expose frameCount reset as a soft reset hook.
+    this.status.frameCount = 0;
+  }
+
+  destroy() {
+    if (this.cart) { try { this.cart.destroy(); } catch { /* ignore */ } }
+    this.cart = null;
+    this.state.lastFrame = null;
+    this.status.loaded = false;
+  }
+}

package/src/mcp/server.js

@@ -1,4 +1,21 @@
 #!/usr/bin/env node
+// Self-re-exec with --experimental-vm-modules if it's missing. The jsgame host kind
+// (rungame) sandboxes games in a vm.SourceTextModule realm, which requires that flag.
+// It's harmless for everything else, so we enable it once up front rather than making
+// users remember it. Guard against a re-exec loop via a sentinel env var.
+if (
+  !process.execArgv.some((a) => a.includes("experimental-vm-modules")) &&
+  !process.env.ROMDEV_REEXEChild
+) {
+  const { spawnSync } = await import("node:child_process");
+  const r = spawnSync(
+    process.execPath,
+    ["--experimental-vm-modules", ...process.execArgv, process.argv[1], ...process.argv.slice(2)],
+    { stdio: "inherit", env: { ...process.env, ROMDEV_REEXEChild: "1" } },
+  );
+  process.exit(r.status ?? 0);
+}
+
 // romdev — MCP server (Streamable HTTP).
 //
 // Exposes the libretro harness, save state, memory inspection, screenshot,

package/src/mcp/state.js

@@ -122,15 +122,39 @@ export function getHostOrNull(sessionKey) {
  * @returns {LibretroHost}
  */
 export function resetHost(sessionKey) {
-  const existing = hosts.get(sessionKey);
-  if (existing && existing.status.loaded) {
-    try { existing.unloadMedia(); } catch {}
-  }
+  teardownHost(hosts.get(sessionKey));
   const fresh = new LibretroHost();
   hosts.set(sessionKey, fresh);
   return fresh;
 }
 
+/** Tear down whatever host kind is present (LibretroHost.unloadMedia or a native
+ *  host's destroy) — WasmcartHost/JsGameHost don't have unloadMedia. */
+function teardownHost(existing) {
+  if (!existing) return;
+  try {
+    if (typeof existing.unloadMedia === "function" && existing.status?.loaded) {
+      existing.unloadMedia();
+    } else if (typeof existing.destroy === "function") {
+      existing.destroy();
+    }
+  } catch { /* ignore teardown errors */ }
+}
+
+/**
+ * Install an already-constructed host (a native-runtime kind: WasmcartHost /
+ * JsGameHost) as this session's active host, tearing down any previous one.
+ * Emulator platforms use resetHost + loadCore; native runtimes build their own
+ * host and hand it here.
+ * @param {string} sessionKey
+ * @param {object} hostInstance
+ */
+export function installHost(sessionKey, hostInstance) {
+  teardownHost(hosts.get(sessionKey));
+  hosts.set(sessionKey, hostInstance);
+  return hostInstance;
+}
+
 /** @param {string} sessionKey */
 export function clearHost(sessionKey) {
   const existing = hosts.get(sessionKey);

package/src/mcp/tools/cheats.js

@@ -18,6 +18,9 @@ const GG_ADDR_RANGE = {
   snes: [0x008000, 0xFFFFFF], // mapped ROM ($xx:8000-$xx:FFFF); the Game Genie
                               // ROM device patches here. (Pro Action Replay is
                               // a RAM poke — for a ROM patch we pick GG below.)
+  gametank: [0x0000, 0xFFFF], // flat 16-bit CPU space. GameTank's Game Genie is a
+                              // READ substitution on the bus, so any read address is
+                              // valid (RAM or cart ROM). A NEW format — see gamegenie.js.
 };
 
 // The native ROM-PATCH device per platform (installs a read-intercept), as
@@ -94,6 +97,7 @@ const SUPPORTED = new Set([
 const MAKE_CHEAT_PLATFORMS = [
   "nes", "gb", "gbc", "snes", "genesis", "sms", "gg",
   "atari2600", "atari7800", "lynx", "gba", "c64", "pce", "msx",
+  "gametank", // NEW: GameTank Game Genie (read-substitution device) — see gamegenie.js
 ];
 
 // gameCheats indexes whose codes are predominantly ENCRYPTED at the source

package/src/mcp/tools/frame.js

@@ -76,7 +76,7 @@ const NEARLY_BLANK_DOMINANT = 0.92;
  */
 export async function computeVerify(host, frames, sessionKey) {
   const platform = host.status.platform;
-  if (frames && frames > 0) host.stepFrames(frames);
+  if (frames && frames > 0) await host.stepFrames(frames);
   const frameCount = host.status.frameCount;
 
   // --- pixel content check (platform-agnostic) ---
@@ -317,7 +317,9 @@ export function compositeSideBySide(a, b, gap = 4) {
 export function registerFrameTools(server, z, sessionKey) {
   async function doStep({ frames }) {
       const host = getHost(sessionKey);
-      const n = host.stepFrames(frames);
+      // await: native-runtime hosts (jsgame) have an async stepFrames that yields for
+      // the game's async work; awaiting a sync LibretroHost return is a harmless no-op.
+      const n = await host.stepFrames(frames);
       // Surface a co-drive conflict the moment the agent steps: a human
       // actively playing in the playtest window means this step raced their
       // real-time loop. Field only appears when the conflict is real.
@@ -786,7 +788,7 @@ export function registerFrameTools(server, z, sessionKey) {
   async function doStepAndShot({ frames, path: outPath, inline }) {
       requireImageTarget(outPath, inline, "frame({op:'stepAndShot'})");
       const host = getHost(sessionKey);
-      host.stepFrames(frames);
+      await host.stepFrames(frames);
       const shot = host.screenshot();
       const coDrive = humanCoDriveWarning(sessionKey);
       if (!inline) {

package/src/mcp/tools/index.js

@@ -34,6 +34,7 @@ import { registerFreeSpaceTools } from "./free-space.js";
 import { registerReinjectTools } from "./reinject.js";
 import { registerSpliceChrTools } from "./splice-chr.js";
 import { registerCartPartsTools } from "./cart-parts.js";
+import { registerNativePackTools } from "./native-pack.js";
 import { registerFontMapTools } from "./font-map.js";
 import { registerDisasmTools } from "./disasm.js";
 import { registerFindReferencesTools } from "./find-references.js";
@@ -173,7 +174,7 @@ const CATEGORIES = [
     name: "assets",
     description: "Convert PNGs to platform tile formats, encode WAVs to BRR, scan ROMs to identify them.",
     useWhen: ["importing graphics or audio assets", "checking what a ROM file is"],
-    register: (s, z, k) => { registerAssetTools(s, z, k); registerAudioTools(s, z, k); registerRomIdTools(s, z, k); registerDiffRomsTools(s, z, k); registerFreeSpaceTools(s, z, k); registerReinjectTools(s, z, k); registerSpliceChrTools(s, z, k); registerCartPartsTools(s, z, k); registerFontMapTools(s, z, k); registerArtLoaderTools(s, z, k); registerSpritePipelineTools(s, z, k); registerLospecTools(s, z, k); registerMetaSpriteTools(s, z, k); },
+    register: (s, z, k) => { registerAssetTools(s, z, k); registerAudioTools(s, z, k); registerRomIdTools(s, z, k); registerDiffRomsTools(s, z, k); registerFreeSpaceTools(s, z, k); registerReinjectTools(s, z, k); registerSpliceChrTools(s, z, k); registerCartPartsTools(s, z, k); registerNativePackTools(s, z, k); registerFontMapTools(s, z, k); registerArtLoaderTools(s, z, k); registerSpritePipelineTools(s, z, k); registerLospecTools(s, z, k); registerMetaSpriteTools(s, z, k); },
   },
   {
     name: "project",

package/src/mcp/tools/lifecycle.js

@@ -1,8 +1,17 @@
 import { resolveCore } from "../../cores/registry.js";
 import {
   clearHost, clearHostB, getHost, getHostB, getHostBOrNull, getHostOrNull,
-  rememberLastMedia, resetHost, resetHostB,
+  installHost, rememberLastMedia, resetHost, resetHostB,
 } from "../state.js";
+import { WasmcartHost } from "../../host/WasmcartHost.js";
+import { JsGameHost } from "../../host/JsGameHost.js";
+
+// Native-runtime platforms don't use a libretro core — they run a native WASM/JS
+// game module in-process. loadMedia builds the matching host and installs it.
+const NATIVE_RUNTIME_HOSTS = {
+  wasmcart: () => new WasmcartHost(),
+  jsgame: () => new JsGameHost(),
+};
 import { jsonContent, safeTool, textContent } from "../util.js";
 import { resolveCheatCodeForApply } from "./cheats.js";
 import { attachObserverFrame } from "./watch-memory.js";
@@ -15,10 +24,34 @@ export function registerLifecycleTools(server, z, sessionKey) {
   // it gets its own fresh host and does NOT overwrite slot A's recovery
   // breadcrumb, since B is transient scratch, not the session's main ROM.
   async function doLoadMedia({ platform, path, base64, mediaKind, virtualName, cheats, slot }) {
-    const resolved = resolveCore(platform);
-    if (!resolved) throw new Error(`no core available for platform '${platform}'`);
     if (!path && !base64) throw new Error("loadMedia: provide either `path` (file on disk) or `base64` (ROM bytes).");
     if (path && base64) throw new Error("loadMedia: provide `path` OR `base64`, not both.");
+
+    // Native-runtime kinds (wasmcart, jsgame) bypass the libretro core path: build
+    // their own host, load the game module, install it as the session host. They
+    // share the frame/input/screenshot surface but not loadCore/cheats/regions.
+    if (NATIVE_RUNTIME_HOSTS[platform]) {
+      if (slot === "b") throw new Error(`slot 'b' (side-by-side) is not supported for '${platform}'`);
+      const host = NATIVE_RUNTIME_HOSTS[platform]();
+      const bytes = base64 ? new Uint8Array(Buffer.from(base64, "base64")) : undefined;
+      await host.loadMedia({ platform, ...(bytes ? { bytes } : { path }) });
+      installHost(sessionKey, host);
+      if (path || bytes) rememberLastMedia(sessionKey, { platform, path, fromBase64: !!bytes });
+      const caps = host.getCapabilities();
+      const result = {
+        loaded: true, platform, kind: caps.kind,
+        mediaKind: host.status.mediaKind,
+        ...(bytes ? { bytes: bytes.length } : { path: host.status.mediaPath }),
+        fbWidth: host.status.fbWidth, fbHeight: host.status.fbHeight,
+        capabilities: caps,
+      };
+      // Push the first frame to the /livestream observer, same as an emulator load.
+      attachObserverFrame(result, host, `${platform} loaded`);
+      return result;
+    }
+
+    const resolved = resolveCore(platform);
+    if (!resolved) throw new Error(`no core available for platform '${platform}'`);
     const slotB = slot === "b";
     const host = slotB ? resetHostB(sessionKey) : resetHost(sessionKey);
     await host.loadCore(resolved.jsPath, resolved.wasmPath, { hwRender: resolved.hwRender, noderawfs: resolved.noderawfs });

package/src/mcp/tools/native-pack.js

@@ -0,0 +1,134 @@
+// native-pack — the "compile" step for the native-runtime kinds (wasmcart / jsgame).
+//
+// These game artifacts are ZIP archives, so packing a source directory into one is the
+// build verb for them (there is NO compiler here — wasmcart is language-agnostic, bring
+// your own WASM; jsgame is plain JS). romdev just assembles the archive.
+//
+//   .wasc  (wasmcart): zip of { manifest.json, cart.wasm, assets/… }. If the source dir
+//           lacks a manifest but has a single .wasm, a minimal manifest is generated.
+//   .jsgame (jsgame):  zip of the game directory as-is (must contain package.json with a
+//           "main", or an index.html / main.js entry — same as rungame expects).
+
+import { readFileSync, readdirSync, statSync, writeFileSync, existsSync } from "node:fs";
+import path from "node:path";
+import { zipSync } from "fflate";
+import { jsonContent, safeTool } from "../util.js";
+
+/** Recursively collect files under `dir` into a { relPath: Uint8Array } map for zipSync. */
+function collectDir(dir, baseDir = dir, out = {}) {
+  for (const name of readdirSync(dir)) {
+    const full = path.join(dir, name);
+    const rel = path.relative(baseDir, full).split(path.sep).join("/");
+    const st = statSync(full);
+    if (st.isDirectory()) collectDir(full, baseDir, out);
+    else out[rel] = new Uint8Array(readFileSync(full));
+  }
+  return out;
+}
+
+/**
+ * Pack a wasmcart source dir (or a bare .wasm) into a .wasc archive.
+ * @param {object} a
+ * @param {string} [a.source]  source directory (dev layout) to zip.
+ * @param {string} [a.wasm]    a single cart .wasm (a manifest is generated around it).
+ * @param {string} [a.assets]  optional assets dir (used with `wasm`).
+ * @param {string} a.outputPath  where to write the .wasc.
+ * @param {string} [a.name]     manifest name (generated-manifest case).
+ * @param {number} [a.players]  manifest players count (generated-manifest case).
+ */
+export function packWasc({ source, wasm, assets, outputPath, name, players } = {}) {
+  if (!outputPath) throw new Error("pack(wasmcart): `outputPath` is required.");
+  let files;
+
+  if (source) {
+    if (!existsSync(source) || !statSync(source).isDirectory()) {
+      throw new Error(`pack(wasmcart): source '${source}' is not a directory.`);
+    }
+    files = collectDir(source);
+    if (!files["manifest.json"]) {
+      // No manifest in the dir — synthesize one pointing at the single .wasm present.
+      const wasmEntry = Object.keys(files).find((f) => f.endsWith(".wasm"));
+      if (!wasmEntry) throw new Error("pack(wasmcart): source dir has no manifest.json and no .wasm to derive one.");
+      const manifest = { name: name || path.basename(outputPath, ".wasc"), version: "1.0.0", entry: wasmEntry };
+      if (players) manifest.players = players;
+      files["manifest.json"] = new Uint8Array(Buffer.from(JSON.stringify(manifest, null, 2)));
+    }
+  } else if (wasm) {
+    if (!existsSync(wasm)) throw new Error(`pack(wasmcart): wasm '${wasm}' not found.`);
+    files = { "cart.wasm": new Uint8Array(readFileSync(wasm)) };
+    const manifest = { name: name || path.basename(outputPath, ".wasc"), version: "1.0.0", entry: "cart.wasm" };
+    if (players) manifest.players = players;
+    if (assets) {
+      if (!existsSync(assets) || !statSync(assets).isDirectory()) throw new Error(`pack(wasmcart): assets '${assets}' is not a directory.`);
+      manifest.assets = "assets/";
+      const assetFiles = collectDir(assets);
+      for (const [rel, buf] of Object.entries(assetFiles)) files["assets/" + rel] = buf;
+    }
+    files["manifest.json"] = new Uint8Array(Buffer.from(JSON.stringify(manifest, null, 2)));
+  } else {
+    throw new Error("pack(wasmcart): provide `source` (a dir) or `wasm` (a cart .wasm).");
+  }
+
+  const zipped = zipSync(files, { level: 6 });
+  writeFileSync(outputPath, zipped);
+  return { outputPath, entries: Object.keys(files).length, bytes: zipped.length };
+}
+
+/**
+ * Pack a jsgame source dir into a .jsgame archive (a plain zip of the dir).
+ * @param {object} a
+ * @param {string} a.source  the game directory (must have package.json main / index.html / main.js).
+ * @param {string} a.outputPath  where to write the .jsgame.
+ */
+export function packJsgame({ source, outputPath } = {}) {
+  if (!source || !existsSync(source) || !statSync(source).isDirectory()) {
+    throw new Error(`pack(jsgame): source '${source}' is not a directory.`);
+  }
+  if (!outputPath) throw new Error("pack(jsgame): `outputPath` is required.");
+  const files = collectDir(source);
+  // Sanity: a jsgame needs an entry rungame can resolve.
+  const hasEntry = files["package.json"] || files["index.html"] || files["main.js"] ||
+    Object.keys(files).some((f) => f.endsWith("/main.js") || f === "index.js");
+  if (!hasEntry) {
+    throw new Error("pack(jsgame): source has no entry (package.json 'main', index.html, or main.js). rungame won't be able to run it.");
+  }
+  const zipped = zipSync(files, { level: 6 });
+  writeFileSync(outputPath, zipped);
+  return { outputPath, entries: Object.keys(files).length, bytes: zipped.length };
+}
+
+/**
+ * Register the `pack` tool — the "build" verb for the native-runtime kinds. Packs a
+ * source directory into a distributable .wasc / .jsgame archive (a zip). NOT a compiler
+ * (wasmcart is any-language-to-WASM; jsgame is plain JS) — it just assembles the archive.
+ */
+export function registerNativePackTools(server, z) {
+  server.tool(
+    "pack",
+    "Package a native-runtime game's source into its distributable archive (the 'build' step " +
+    "for wasmcart/jsgame — a ZIP, NOT a compiler). `target`:\n" +
+    "• 'wasc' (wasmcart) — pass `source` (a dev dir: manifest.json + cart.wasm + assets/) OR " +
+    "`wasm` (a single cart .wasm; a minimal manifest is generated, with optional `assets` dir). " +
+    "Writes a .wasc. NOTE: romdev does NOT compile WASM — bring your own (any language → wasm).\n" +
+    "• 'jsgame' (jsgame) — pass `source` (the game dir; must have package.json 'main', index.html, " +
+    "or main.js). Writes a .jsgame. Pure JS, no build needed beyond the zip.",
+    {
+      target: z.enum(["wasc", "jsgame"]).describe("wasc = wasmcart .wasc; jsgame = jsgame .jsgame."),
+      source: z.string().optional().describe("Source directory to pack. (wasc: a dev-layout dir; jsgame: the game dir.)"),
+      wasm: z.string().optional().describe("target=wasc: a single cart .wasm to wrap (a manifest is generated). Use instead of `source`."),
+      assets: z.string().optional().describe("target=wasc with `wasm`: an assets directory to include under assets/."),
+      outputPath: z.string().describe("Absolute path to write the archive (.wasc / .jsgame)."),
+      name: z.string().optional().describe("target=wasc: manifest game name (default derived from outputPath)."),
+      players: z.number().int().min(1).max(4).optional().describe("target=wasc: manifest players count."),
+    },
+    safeTool(async (args) => {
+      if (args.target === "wasc") {
+        return jsonContent(packWasc(args));
+      }
+      if (args.target === "jsgame") {
+        return jsonContent(packJsgame(args));
+      }
+      throw new Error(`pack: unknown target '${args.target}'.`);
+    }),
+  );
+}