romdevtools 0.41.0 → 0.42.0

package/src/cores/registry.js

@@ -1,8 +1,12 @@
-// Core registry. Maps platform IDs to bundled libretro WASM cores.
+// Core registry. Maps platform IDs to their libretro WASM core.
 //
-// All v1 cores ship inside the npm package under src/cores/wasm/. Resolution
-// is a simple path lookup — there is no fetcher because there is nothing to
-// fetch.
+// The shipped core wasm lives in the per-platform binary packages
+// (romdev-core-* / romdev-platform-*) — NOT in this package. `resolveCore`
+// resolves each platform from the `pkg` named in its CORES entry. The local
+// `src/cores/wasm/` dir is a gitignored BUILD-STAGING area: `scripts/build-*.sh`
+// emit there, and it serves as a dev fallback when you're working in-tree
+// without the satellite packages built. It is empty in a fresh clone and does
+// NOT ship in the npm tarball.
 
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -11,81 +15,69 @@ import path from "node:path";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-/** Directory holding all bundled `.js` + `.wasm` libretro core pairs. */
+/** Build-staging dir for `.js` + `.wasm` core pairs (gitignored; dev fallback
+ *  only — the shipped wasm resolves from the satellite packages). */
 export const CORES_DIR = path.resolve(__dirname, "wasm");
 
 /**
  * @typedef {Object} CoreInfo
  * @property {string} platform     short platform id ("nes", "gb", ...)
  * @property {string} coreName     filename stem (matches `<coreName>_libretro.js`)
+ * @property {string} pkg          binary package that SHIPS this core's wasm.
+ *   `romdev-core-*` = a standalone core (often shared: gpgx serves genesis/sms/
+ *   gg, gambatte serves gb/gbc). `romdev-platform-*` = a core bundled WITH the
+ *   dedicated toolchain nothing else uses (snes9x+asar+wla, mGBA+arm-gcc,
+ *   stella+dasm) — they ship together because only that platform needs them.
  * @property {string} displayName
  * @property {string} [aka]        comma-separated synonyms accepted in resolvers
  */
 
 /**
+ * The single source of truth for every platform's core: its filename stem, the
+ * package that ships it, and display metadata — all in one record so there's no
+ * second map to keep in sync.
  * @type {Record<string, CoreInfo>}
  */
 export const CORES = {
-  nes: { platform: "nes", coreName: "fceumm", displayName: "Nintendo Entertainment System (fceumm)" },
-  gb: { platform: "gb", coreName: "gambatte", displayName: "Game Boy / GBC (gambatte)" },
-  gbc: { platform: "gbc", coreName: "gambatte", displayName: "Game Boy / GBC (gambatte)" },
-  atari2600: { platform: "atari2600", coreName: "stella2014", displayName: "Atari 2600 (Stella)" },
-  atari7800: { platform: "atari7800", coreName: "prosystem", displayName: "Atari 7800 (ProSystem)" },
-  lynx: { platform: "lynx", coreName: "handy", displayName: "Atari Lynx (Handy)" },
-  sms: { platform: "sms", coreName: "genesis_plus_gx", displayName: "Sega Master System (Genesis Plus GX)" },
-  gg: { platform: "gg", coreName: "genesis_plus_gx", displayName: "Sega Game Gear (Genesis Plus GX)" },
-  genesis: { platform: "genesis", coreName: "genesis_plus_gx", displayName: "Sega Genesis / Mega Drive (Genesis Plus GX)" },
-  snes: { platform: "snes", coreName: "snes9x", displayName: "SNES (snes9x)" },
-  gba: { platform: "gba", coreName: "mgba", displayName: "Game Boy Advance (mGBA)" },
-  c64: { platform: "c64", coreName: "vice_x64", displayName: "Commodore 64 (VICE x64)" },
-  pce: { platform: "pce", coreName: "geargrafx", displayName: "PC Engine / TurboGrafx-16 (Geargrafx)", aka: "turbografx,tg16,pcengine" },
-  msx: { platform: "msx", coreName: "bluemsx", displayName: "MSX / MSX2 (blueMSX)", aka: "msx2" },
+  nes: { platform: "nes", coreName: "fceumm", pkg: "romdev-core-fceumm", displayName: "Nintendo Entertainment System (fceumm)" },
+  gb: { platform: "gb", coreName: "gambatte", pkg: "romdev-core-gambatte", displayName: "Game Boy / GBC (gambatte)" },
+  gbc: { platform: "gbc", coreName: "gambatte", pkg: "romdev-core-gambatte", displayName: "Game Boy / GBC (gambatte)" },
+  atari2600: { platform: "atari2600", coreName: "stella2014", pkg: "romdev-platform-atari2600", displayName: "Atari 2600 (Stella)" },
+  atari7800: { platform: "atari7800", coreName: "prosystem", pkg: "romdev-core-prosystem", displayName: "Atari 7800 (ProSystem)" },
+  lynx: { platform: "lynx", coreName: "handy", pkg: "romdev-core-handy", displayName: "Atari Lynx (Handy)" },
+  sms: { platform: "sms", coreName: "genesis_plus_gx", pkg: "romdev-core-gpgx", displayName: "Sega Master System (Genesis Plus GX)" },
+  gg: { platform: "gg", coreName: "genesis_plus_gx", pkg: "romdev-core-gpgx", displayName: "Sega Game Gear (Genesis Plus GX)" },
+  genesis: { platform: "genesis", coreName: "genesis_plus_gx", pkg: "romdev-core-gpgx", displayName: "Sega Genesis / Mega Drive (Genesis Plus GX)" },
+  snes: { platform: "snes", coreName: "snes9x", pkg: "romdev-platform-snes", displayName: "SNES (snes9x)" },
+  gba: { platform: "gba", coreName: "mgba", pkg: "romdev-platform-gba", displayName: "Game Boy Advance (mGBA)" },
+  c64: { platform: "c64", coreName: "vice_x64", pkg: "romdev-core-vice", displayName: "Commodore 64 (VICE x64)" },
+  pce: { platform: "pce", coreName: "geargrafx", pkg: "romdev-core-geargrafx", displayName: "PC Engine / TurboGrafx-16 (Geargrafx)", aka: "turbografx,tg16,pcengine" },
+  msx: { platform: "msx", coreName: "bluemsx", pkg: "romdev-core-bluemsx", displayName: "MSX / MSX2 (blueMSX)", aka: "msx2" },
 };
 
-/**
- * Resolve a platform id to absolute paths for its core.
- * Returns null if the core isn't bundled.
- * @param {string} platform
- * @returns {{ platform: string, coreName: string, displayName: string, jsPath: string, wasmPath: string } | null}
- */
-// Platform → the @romdev binary package that ships its core wasm. Resolution
-// tries the package first (the shipped layout), then falls back to a local
-// src/cores/wasm copy (transition / dev). Add a row here as each platform's
-// package is carved out; platforms not listed still resolve locally.
-const CORE_PACKAGES = {
-  atari2600: "romdev-platform-atari2600",
-  nes: "romdev-core-fceumm",
-  gb: "romdev-core-gambatte",
-  gbc: "romdev-core-gambatte",
-  genesis: "romdev-core-gpgx",
-  sms: "romdev-core-gpgx",
-  gg: "romdev-core-gpgx",
-  c64: "romdev-core-vice",
-  lynx: "romdev-core-handy",
-  atari7800: "romdev-core-prosystem",
-  snes: "romdev-platform-snes",
-  gba: "romdev-platform-gba",
-  pce: "romdev-core-geargrafx",
-  msx: "romdev-core-bluemsx",
-};
-
-/** Try to get {jsPath,wasmPath} for a core from its @romdev package. */
-function resolveCoreFromPackage(platform, coreName) {
-  const pkg = CORE_PACKAGES[platform];
+/** Try to get {jsPath,wasmPath} for a core from its binary package. */
+function resolveCoreFromPackage(pkg, coreName) {
   if (!pkg) return null;
   try {
     const dir = path.dirname(fileURLToPath(import.meta.resolve(pkg)));
     const jsPath = path.join(dir, "wasm", `${coreName}_libretro.js`);
     const wasmPath = path.join(dir, "wasm", `${coreName}_libretro.wasm`);
     if (existsSync(jsPath) && existsSync(wasmPath)) return { jsPath, wasmPath };
-  } catch { /* package not resolvable — fall through to local */ }
+  } catch { /* package not resolvable — fall through to the dev-staging dir */ }
   return null;
 }
 
+/**
+ * Resolve a platform id to absolute paths for its core. Tries the binary
+ * package first (the shipped layout), then the gitignored `src/cores/wasm/`
+ * build-staging dir (in-tree dev fallback). Returns null if neither has it.
+ * @param {string} platform
+ * @returns {{ platform: string, coreName: string, pkg: string, displayName: string, jsPath: string, wasmPath: string } | null}
+ */
 export function resolveCore(platform) {
   const info = CORES[platform];
   if (!info) return null;
-  const fromPkg = resolveCoreFromPackage(platform, info.coreName);
+  const fromPkg = resolveCoreFromPackage(info.pkg, info.coreName);
   if (fromPkg) return { ...info, ...fromPkg };
   const jsPath = path.join(CORES_DIR, `${info.coreName}_libretro.js`);
   const wasmPath = path.join(CORES_DIR, `${info.coreName}_libretro.wasm`);

package/src/mcp/state.js

@@ -10,10 +10,41 @@
 // layer is responsible for calling clearHost(key) on session close.
 
 import { LibretroHost } from "../host/index.js";
+import path from "node:path";
+import os from "node:os";
+import { existsSync } from "node:fs";
 
 /** @type {Map<string, LibretroHost>} */
 const hosts = new Map();
 
+/**
+ * Disk path for a playtest session's rolling auto-checkpoint (eviction
+ * survivability). Deterministic per (session, rom) so the eviction-recovery hint
+ * can name it WITHOUT any bookkeeping. Next to the ROM when it's a real on-disk
+ * file; else a stable per-session file under the OS temp dir. (v0.41.0 feedback
+ * note 125904.) Shared by the playtest tool (writer) and getHost (recovery hint).
+ * @param {string} sessionKey
+ * @param {string|null} mediaPath
+ */
+export function playtestCheckpointPath(sessionKey, mediaPath) {
+  const safeSession = String(sessionKey).replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 40);
+  if (mediaPath && !mediaPath.startsWith("<") && path.isAbsolute(mediaPath)) {
+    const dir = path.dirname(mediaPath);
+    const base = path.basename(mediaPath, path.extname(mediaPath));
+    return path.join(dir, `${base}.playtest-autosave.state`);
+  }
+  return path.join(os.tmpdir(), `romdev-playtest-${safeSession}.autosave.state`);
+}
+
+// Secondary host slot ("B") per session. The primary slot above is what every
+// tool uses by default; slot B exists for the ONE workflow that needs two cores
+// live at once: side-by-side comparison (e.g. an original ROM vs. its port).
+// loadMedia({slot:'b'}) loads here; frame({op:'sideBySide'}) captures both. It
+// is entirely opt-in — a session that never loads slot B pays nothing, and the
+// per-session teardown below clears both slots together.
+/** @type {Map<string, LibretroHost>} */
+const hostsB = new Map();
+
 // What this session last loaded, kept OUTSIDE the host map so it SURVIVES a
 // host eviction (server restart / session reconnect / unload). The host itself
 // is gone in those cases, so the "No ROM loaded" error has nothing to read —
@@ -47,11 +78,18 @@ export function getHost(sessionKey) {
       const recall = prev.path
         ? `loadMedia({ platform: "${prev.platform}", path: "${prev.path}" })`
         : `loadMedia({ platform: "${prev.platform}", base64: ... })  (your ROM came from base64 — re-supply the bytes)`;
+      // If a playtest window was open, a rolling auto-checkpoint may be on disk —
+      // restoring it recovers the human's MANUAL progress, not just a fresh boot.
+      const ckpt = playtestCheckpointPath(sessionKey, prev.path ?? null);
+      const ckptHint = existsSync(ckpt)
+        ? `\nA playtest auto-checkpoint is on disk (your last ~15s of play): after the load above, run\n  state({ op: "load", path: "${ckpt}" })\nto restore the human's progress instead of replaying from boot.`
+        : "";
       throw new Error(
         "No ROM loaded in this session — the host was evicted (the server restarted, " +
         "your session reconnected, or the media was unloaded). Emulator state lives in " +
         "server memory only, so it did not survive. RECOVER by re-running your last load:\n  " +
         recall +
+        ckptHint +
         "\nThen replay any boot/navigate steps to get back to where you were. " +
         "(If instead you expected a DIFFERENT session, you may be sending an inconsistent " +
         "`x-romdev-session` header — reuse one stable id on every call.)",
@@ -100,11 +138,57 @@ export function clearHost(sessionKey) {
     try { existing.unloadMedia(); } catch {}
   }
   hosts.delete(sessionKey);
+  // A session shutdown tears down BOTH slots — slot B is part of the same
+  // session's footprint and must not outlive it.
+  clearHostB(sessionKey);
+}
+
+// --- Secondary host slot ("B") ----------------------------------------------
+// Same lifecycle helpers as the primary, scoped to the hostsB map. getHostB
+// throws a slot-specific error (no recovery breadcrumb — slot B is transient
+// scratch for a comparison, not the session's main ROM).
+
+/** @param {string} sessionKey @returns {LibretroHost} */
+export function getHostB(sessionKey) {
+  const host = hostsB.get(sessionKey);
+  if (!host) {
+    throw new Error(
+      "No ROM loaded in comparison slot B for this session — load one with " +
+      "loadMedia({ slot: 'b', platform, path }). Slot B is the second core used " +
+      "by frame({op:'sideBySide'}); it is not the session's primary ROM.",
+    );
+  }
+  return host;
+}
+
+/** @param {string} sessionKey */
+export function getHostBOrNull(sessionKey) {
+  return hostsB.get(sessionKey) ?? null;
+}
+
+/** @param {string} sessionKey @returns {LibretroHost} */
+export function resetHostB(sessionKey) {
+  const existing = hostsB.get(sessionKey);
+  if (existing && existing.status.loaded) {
+    try { existing.unloadMedia(); } catch {}
+  }
+  const fresh = new LibretroHost();
+  hostsB.set(sessionKey, fresh);
+  return fresh;
 }
 
-/** Test-only: number of live hosts. */
+/** @param {string} sessionKey */
+export function clearHostB(sessionKey) {
+  const existing = hostsB.get(sessionKey);
+  if (existing && existing.status.loaded) {
+    try { existing.unloadMedia(); } catch {}
+  }
+  hostsB.delete(sessionKey);
+}
+
+/** Test-only: number of live hosts (both slots). */
 export function _liveHostCount() {
-  return hosts.size;
+  return hosts.size + hostsB.size;
 }
 
 /** Test-only: inject a (possibly fake) host for a session key. */
@@ -112,6 +196,11 @@ export function _setHostForTest(sessionKey, host) {
   hosts.set(sessionKey, host);
 }
 
+/** Test-only: inject a (possibly fake) host into comparison slot B. */
+export function _setHostBForTest(sessionKey, host) {
+  hostsB.set(sessionKey, host);
+}
+
 // Shared reference to the per-session disclosure manager, so tool
 // handlers outside index.js (toolchain.js, etc.) can call consumeHint()
 // to emit session-scoped one-shot nudges (e.g. "loadCategory('show') to

package/src/mcp/tools/cheats.js

@@ -4,7 +4,7 @@ import { getHost } from "../state.js";
 import { jsonContent, safeTool } from "../util.js";
 import { attachObserverFrame } from "./watch-memory.js";
 import { lookupCheats, searchCheatGames } from "../../cheats/lookup.js";
-import { encodeForDevice, nativeDevicesFor, decodeCode } from "../../cheats/gamegenie.js";
+import { encodeForDevice, nativeDevicesFor, decodeCode, encodeRaw } from "../../cheats/gamegenie.js";
 
 // Per-platform cheat address space (for makeCheat validation). A Game Genie
 // letter code can only address these ranges; out-of-range → raw ADDR:VAL only.
@@ -57,6 +57,15 @@ export function resolveCheatCodeForApply(rawCode, platform) {
       else appliedAs = "rom-unencodable";
     } else if (decoded) {
       appliedAs = "ram";
+      // Normalize the raw RAM code so a short hand-typed `AA:VV` (e.g. "32:09")
+      // is re-emitted in the binding width ("0032:09"). The libretro parser
+      // (verified on fceumm) silently DROPS an under-padded RAM address — it
+      // parses but never pokes — so passing the user's short string through
+      // verbatim is the inert-cheat footgun. encodeRaw pads the address to the
+      // width the core honors. (No-op for already-padded codes.)
+      const norm = encodeRaw(decoded);
+      if (norm !== rawCode) reencodedFrom = rawCode;
+      code = norm;
     }
   }
   return { code, appliedAs, reencodedFrom };