romdevtools 0.84.1 → 0.85.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.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.85.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",
@@ -13,7 +13,8 @@
     "postinstall": "node src/install/postinstall.mjs",
     "smoke": "node --enable-source-maps src/cli/smoke.js",
     "mcp": "node --enable-source-maps src/mcp/server.js",
-    "test": "node --test 'src/**/*.test.js' 'test/**/*.test.js'"
+    "test": "node --test 'src/**/*.test.js' 'test/**/*.test.js'",
+    "test:jsgame": "node --experimental-vm-modules --test-force-exit --test test/jsgame-host.test.js"
   },
   "keywords": [
     "mcp",
@@ -79,8 +80,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"
   },

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/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/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}'.`);
+    }),
+  );
+}