romdevtools 0.23.0 → 0.24.0

package/src/host/LibretroHost.js

@@ -138,6 +138,51 @@ export const PLATFORM_VIRTUAL_EXT = {
 };
 import { RETRO_DEVICE_JOYPAD } from "./retroConstants.js";
 
+// C64 controller→keyboard map (the Batocera/RetroDeck model: a CONTROLLER alone
+// plays C64 — no physical keyboard needed — by mapping spare buttons/stick to
+// the C64 keyboard keys games need at setup screens). Keyed by the button NAME
+// setInput receives (libretro + spatial names + the playtest right-stick virtual
+// buttons c64_f1..f7). The joystick itself (d-pad + Fire) is NOT here — those
+// stay a real joypad. Everything here is routed to the key matrix instead.
+//   B / south = Fire        → joystick (handled as joypad, not a key)
+//   X / west  = Space        L2 = Run/Stop   R2 / start = Return
+//   R-stick   = F1/F3/F5/F7  (playtest emits c64_f1..f7 from the right stick)
+const C64_BUTTON_KEYS = {
+  west: "space", y: "space",
+  l2: "run/stop",
+  r2: "return", start: "return",
+  c64_f1: "f1", c64_f3: "f3", c64_f5: "f5", c64_f7: "f7",
+  north: "f1", x: "f1",   // also expose F1 on the top face (1-player select is the #1 need)
+};
+// The buttons that ARE the C64 joystick (pass through to the joypad mask):
+const C64_JOY_BUTTONS = new Set(["up", "down", "left", "right", "b", "south", "a", "east"]);
+
+// C64 keyboard matrix: key name (lowercase) → [row, col] in the 8×8 matrix the
+// KERNAL scans via CIA1. Drives romdev_key_matrix() in the VICE core. Values
+// taken from VICE's own C64 positional keymap (data/C64/sdl_pos_uk.vkm).
+// Covers the keys RE/startup flows need; extend as needed.
+const C64_KEY_MATRIX = {
+  // function keys (the common "1 player / start" selectors)
+  f1: [0, 4], f3: [0, 5], f5: [0, 6], f7: [0, 3],
+  // editing / control
+  return: [0, 1], enter: [0, 1], space: [7, 4], del: [0, 0], backspace: [0, 0],
+  "run/stop": [7, 7], runstop: [7, 7], stop: [7, 7],
+  ctrl: [7, 2], cbm: [7, 5], commodore: [7, 5],
+  lshift: [1, 7], rshift: [6, 4], home: [6, 3], clr: [6, 3],
+  // cursor keys (C64 has DOWN + RIGHT; UP/LEFT are the shifted forms — use
+  // shift+down / shift+right for those)
+  "crsr-down": [0, 7], "crsr-right": [0, 2], down: [0, 7], right: [0, 2],
+  // digits
+  "0": [4, 3], "1": [7, 0], "2": [7, 3], "3": [1, 0], "4": [1, 3],
+  "5": [2, 0], "6": [2, 3], "7": [3, 0], "8": [3, 3], "9": [4, 0],
+  // letters
+  a: [1, 2], b: [3, 4], c: [2, 4], d: [2, 2], e: [1, 6], f: [2, 5],
+  g: [3, 2], h: [3, 5], i: [4, 1], j: [4, 2], k: [4, 5], l: [5, 2],
+  m: [4, 4], n: [4, 7], o: [4, 6], p: [5, 1], q: [7, 6], r: [2, 1],
+  s: [1, 5], t: [2, 6], u: [3, 6], v: [3, 7], w: [1, 1], x: [2, 7],
+  y: [3, 1], z: [1, 4],
+};
+
 export class LibretroHost {
   /**
    * @param {Object} [opts]
@@ -570,12 +615,55 @@ export class LibretroHost {
   /** @param {import("./types.js").FrameInput} input */
   setInput(input) {
     const platform = this.status.platform ?? undefined;
+    // C64: route the keyboard-mapped controller buttons (Space/Run-Stop/Return/
+    // F1-F7) to the key matrix so a CONTROLLER alone can play — the
+    // Batocera/RetroDeck model. The joystick bits (d-pad + Fire) still flow to
+    // the joypad mask below. Applies to BOTH playtest and the agent's setInput.
+    if (platform === "c64" && this.mod && typeof this.mod._romdev_key_matrix === "function") {
+      this._applyC64ButtonKeys(input.ports[0] || {});
+    }
     for (let port = 0; port < this.state.inputPorts.length; port++) {
-      const portInput = input.ports[port];
+      const portInput = this._c64StripKeyButtons(input.ports[port], platform);
       this.state.inputPorts[port][0] = portInputToMask(portInput, platform);
     }
   }
 
+  /** C64: press/release matrix keys for the held keyboard-mapped buttons on a
+   *  port, edge-tracked so a key releases when its button is no longer held. */
+  _applyC64ButtonKeys(portInput) {
+    const held = this._c64HeldKeys || (this._c64HeldKeys = new Set());
+    const want = new Set();
+    for (const [btn, key] of Object.entries(C64_BUTTON_KEYS)) {
+      if (portInput[btn] === true) want.add(key);
+    }
+    // press newly-wanted, release no-longer-wanted
+    for (const key of want) {
+      if (!held.has(key)) {
+        const pos = C64_KEY_MATRIX[key];
+        if (pos) this.mod._romdev_key_matrix(pos[0], pos[1], 1);
+        held.add(key);
+      }
+    }
+    for (const key of [...held]) {
+      if (!want.has(key)) {
+        const pos = C64_KEY_MATRIX[key];
+        if (pos) this.mod._romdev_key_matrix(pos[0], pos[1], 0);
+        held.delete(key);
+      }
+    }
+  }
+
+  /** Strip the C64 keyboard-mapped buttons out of a port so they don't ALSO
+   *  press a joystick direction/fire (only the real joystick bits remain). */
+  _c64StripKeyButtons(portInput, platform) {
+    if (platform !== "c64" || !portInput) return portInput;
+    const out = {};
+    for (const k of Object.keys(portInput)) {
+      if (C64_JOY_BUTTONS.has(k)) out[k] = portInput[k];
+    }
+    return out;
+  }
+
   /** @param {string} name */
   saveState(name) {
     const snapshot = this.serializeState();
@@ -802,6 +890,87 @@ export class LibretroHost {
     }
   }
 
+  // ── C64 keyboard + joyport (VICE core only) ──────────────────────────
+  // C64 games need KEYBOARD input (F1 = 1 player, RUN/STOP, SPACE/RETURN at
+  // setup screens) before joystick gameplay — joystick alone can't pass them.
+  // The VICE core exports romdev_key_matrix / romdev_kbdbuf_feed /
+  // romdev_joyport_* (see scripts/patches/vice-romdev-memory-regions.patch).
+
+  /** True if the loaded core exposes C64 keyboard injection (VICE only). */
+  keyboardSupported() {
+    const mod = this.mod;
+    return !!(mod && typeof mod._romdev_key_matrix === "function");
+  }
+
+  /**
+   * Press (and optionally auto-release) a single C64 key by name. Drives the
+   * C64 8×8 key matrix directly via the core. Held for `frames` then released.
+   * @param {string} key  a name from C64_KEY_MATRIX (case-insensitive)
+   * @param {number} [frames] frames to hold before release (default 4)
+   * @returns {{key:string, row:number, col:number, frames:number}}
+   */
+  pressC64Key(key, frames = 4) {
+    const mod = this._needMod();
+    if (typeof mod._romdev_key_matrix !== "function") {
+      throw new Error("this core build does not expose C64 keyboard input (C64/VICE only).");
+    }
+    const pos = C64_KEY_MATRIX[String(key).toLowerCase()];
+    if (!pos) {
+      throw new Error(
+        `unknown C64 key '${key}'. Known: ${Object.keys(C64_KEY_MATRIX).join(", ")}.`,
+      );
+    }
+    const [row, col] = pos;
+    mod._romdev_key_matrix(row, col, 1);    // press
+    this.stepFrames(Math.max(1, frames | 0));
+    mod._romdev_key_matrix(row, col, 0);    // release
+    this.stepFrames(1);
+    return { key: String(key).toLowerCase(), row, col, frames: Math.max(1, frames | 0) };
+  }
+
+  /**
+   * Feed a PETSCII string into the C64 kernal keyboard buffer (for typing
+   * LOAD/RUN/filenames). `\r` (or `\n`) becomes RETURN. Non-blocking — the
+   * kernal drains it as the screen editor runs, so step frames after.
+   * @param {string} text
+   * @returns {number} kbdbuf_feed's result (>=0 ok)
+   */
+  typeC64Text(text) {
+    const mod = this._needMod();
+    if (typeof mod._romdev_kbdbuf_feed !== "function") {
+      throw new Error("this core build does not expose C64 text input (C64/VICE only).");
+    }
+    const s = String(text).replace(/\n/g, "\r");
+    const bytes = Buffer.from(s + "\0", "latin1");
+    const ptr = mod._malloc(bytes.length);
+    try {
+      mod.HEAPU8.set(bytes, ptr);
+      return mod._romdev_kbdbuf_feed(ptr) | 0;
+    } finally {
+      mod._free(ptr);
+    }
+  }
+
+  /** Get the active C64 joystick port (1 or 2) the RetroPad drives. */
+  getC64JoyPort() {
+    const mod = this._needMod();
+    if (typeof mod._romdev_joyport_get !== "function") {
+      throw new Error("this core build does not expose C64 joyport (C64/VICE only).");
+    }
+    return mod._romdev_joyport_get() | 0;
+  }
+
+  /** Set the active C64 joystick port (1 or 2). Default is 2 (most games). */
+  setC64JoyPort(port) {
+    const mod = this._needMod();
+    if (typeof mod._romdev_joyport_set !== "function") {
+      throw new Error("this core build does not expose C64 joyport (C64/VICE only).");
+    }
+    if (port !== 1 && port !== 2) throw new Error("C64 joyport must be 1 or 2.");
+    mod._romdev_joyport_set(port | 0);
+    return port | 0;
+  }
+
   reset() {
     const mod = this._needMod();
     mod._retro_reset();

package/src/http/skill-doc.js

@@ -112,7 +112,7 @@ export function sanitizeForSkillChannel(text) {
     // there's no session-id header / reconnect / "connect your agent" step here;
     // the skillPreamble already gives the skill-appropriate intro + prereq).
     if (/Mcp-Session-Id|re-?initialize|session not found|MCP client|MCP connection|MCP sessions/i.test(line)) continue;
-    if (/you are reading this because romdev is connected|connect your (agent|coding agent)|restart its MCP connection|restart your MCP|your MCP client should/i.test(line)) continue;
+    if (/connect your (agent|coding agent)|restart its MCP connection|restart your MCP|your MCP client should/i.test(line)) continue;
 
     let l = line
       // section header that frames romdev as "a server you connect to"

package/src/mcp/tools/input-layout.js

@@ -74,6 +74,16 @@ const HARDWARE_LAYOUTS = {
     readSequence: "Bits 0-4 are Up/Down/Left/Right/Fire, active-low.",
     bitOrder: ["Up", "Down", "Left", "Right", "Fire"],
     faceButtons: FACE_BUTTON_MAP.c64,
+    // The C64 needs more than joystick: many games use KEYBOARD setup screens
+    // (F1=1 player, RUN/STOP, SPACE/RETURN) before joystick gameplay starts.
+    keyboard: {
+      note: "C64 games often need keyboard input to START (F1 to pick 1 player, fire/RETURN to begin). Joystick alone can't pass these. Use input({op:'pressKey', key}) for a single key, input({op:'typeText', text}) to type a string (LOAD/RUN/filenames).",
+      keys: ["f1", "f3", "f5", "f7", "return", "space", "run/stop", "ctrl", "cbm", "home", "down", "right", "lshift", "rshift", "0-9", "a-z"],
+    },
+    joyport: {
+      note: "The RetroPad drives ONE C64 joystick port at a time. Default is port 2 (most games). Use input({op:'joyport'}) to read it, input({op:'joyport', joyport:1|2}) to switch.",
+      default: 2,
+    },
   },
   sms: {
     register: "I/O port $DC (controllers, read via `in a,($DC)`) and $DD (port 2 high bits + reset)",

package/src/mcp/tools/input.js

@@ -213,17 +213,21 @@ export function registerInputTools(server, z, sessionKey) {
     "when ITS code polls; re-apply immediately before the consuming stepFrames and verify via the held-buttons RAM " +
     "byte, not this echo.",
     {
-      op: z.enum(["set", "press", "sequence", "navigate", "layout"]).describe("set/hold buttons; press one button; run a sequence; navigate a menu; or get the input layout."),
+      op: z.enum(["set", "press", "sequence", "navigate", "layout", "pressKey", "typeText", "joyport"]).describe("set/hold buttons; press one button; run a sequence; navigate a menu; get the input layout. C64-ONLY: pressKey (press a C64 KEYBOARD key — F1/Return/Space/Run-Stop — many C64 games need these to start, joystick alone can't); typeText (feed a string into the C64 keyboard buffer — LOAD/RUN/filenames); joyport (get/set which C64 joystick port the pad drives, 1 or 2; default 2)."),
       // set
       ports: z.array(port).min(1).max(2).optional().describe("op=set: per-port input. [{a:true,right:true}] holds A+Right on port 0."),
       // press
       button: z.enum(BUTTON_ENUM).optional().describe("op=press: button to press (native aliases + spatial names accepted)."),
-      frames: z.number().int().min(1).max(600).default(2).describe("op=press: frames to hold the button."),
+      frames: z.number().int().min(1).max(600).default(2).describe("op=press: frames to hold the button. op=pressKey: frames to hold the C64 key (default 4)."),
       port: z.number().int().min(0).max(1).default(0).describe("op=press: which port (default 0)."),
       // sequence
       steps: z.array(z.any()).optional().describe("op=sequence: [{input:{ports:[...]}, frames}]. op=navigate: [{button, holdFrames?, maxWaitFrames?, settleFrames?}]. (Two distinct step shapes by op.)"),
       // layout
       platform: z.string().optional().describe("op=layout: platform id (nes, gb, snes, genesis, ...)."),
+      // C64 keyboard
+      key: z.string().optional().describe("op=pressKey (C64): key name — f1/f3/f5/f7, return, space, run/stop, a-z, 0-9, ctrl, cbm, home, down, right, lshift, rshift."),
+      text: z.string().optional().describe("op=typeText (C64): string fed into the keyboard buffer; \\r / \\n become RETURN. e.g. 'LOAD\"*\",8,1\\rRUN\\r'."),
+      joyport: z.number().int().min(1).max(2).optional().describe("op=joyport (C64): set the active joystick port (1 or 2). Omit to just GET the current port. Default is 2 (most C64 games)."),
     },
     safeTool(async (args) => {
       switch (args.op) {
@@ -249,6 +253,26 @@ export function registerInputTools(server, z, sessionKey) {
           if (!args.platform) throw new Error("input({op:'layout'}): `platform` is required.");
           return jsonContent(getInputLayoutCore(args));
         }
+        case "pressKey": {
+          if (!args.key) throw new Error("input({op:'pressKey'}): `key` is required (C64 keyboard key, e.g. 'f1', 'return', 'run/stop').");
+          const host = getHost(sessionKey);
+          const r = host.pressC64Key(args.key, args.frames ?? 4);
+          return jsonContent({ pressedKey: r.key, matrix: [r.row, r.col], frames: r.frames, frameCount: host.status.frameCount });
+        }
+        case "typeText": {
+          if (typeof args.text !== "string") throw new Error("input({op:'typeText'}): `text` is required (string fed into the C64 keyboard buffer).");
+          const host = getHost(sessionKey);
+          const rc = host.typeC64Text(args.text);
+          return jsonContent({ typed: args.text, fedResult: rc, note: "Queued into the C64 keyboard buffer — step frames so the screen editor drains it." });
+        }
+        case "joyport": {
+          const host = getHost(sessionKey);
+          if (args.joyport === undefined) {
+            return jsonContent({ joyport: host.getC64JoyPort(), note: "Active C64 joystick port. Most C64 games use port 2 (the default). Pass `joyport:1` or `joyport:2` to change it." });
+          }
+          const set = host.setC64JoyPort(args.joyport);
+          return jsonContent({ joyport: set, set: true });
+        }
         default: throw new Error(`input: unknown op '${args.op}'`);
       }
     }),

package/src/mcp/tools/playtest.js

@@ -126,7 +126,7 @@ export function registerPlaytestTools(server, z, sessionKey) {
         });
       }
 
-      const { playtest, KEYBOARD_BINDINGS_HELP } = await import("../../playtest/playtest.js");
+      const { playtest, KEYBOARD_BINDINGS_HELP, C64_BINDINGS_HELP } = await import("../../playtest/playtest.js");
       let session;
       try {
         // Pass a live-host accessor so the window FOLLOWS rebuilds: runSource/
@@ -214,6 +214,7 @@ export function registerPlaytestTools(server, z, sessionKey) {
       // isn't left guessing which keys drive the game. (A pad hot-plugged later
       // is picked up automatically — this is just the at-open state.)
       const noController = session.controllerCount === 0;
+      const isC64 = host.status?.platform === "c64";
       return jsonContent({
         opened: true,
         reusedExistingWindow: false,
@@ -222,7 +223,21 @@ export function registerPlaytestTools(server, z, sessionKey) {
         scale,
         aspect,
         controllerCount: session.controllerCount,
-        ...(noController
+        // C64 input is non-obvious (games need keyboard keys to START), so ALWAYS
+        // relay the controls — a controller alone IS enough (spare buttons/stick
+        // map to F1/Run-Stop/Space/Return), and the keyboard fallback covers the
+        // no-controller case. This is the Batocera/RetroDeck model.
+        ...(isC64
+          ? {
+              c64Controls: C64_BINDINGS_HELP,
+              tellUser:
+                "C64 game: RELAY `c64Controls` to the user. A CONTROLLER ALONE is " +
+                "enough — they do NOT need a keyboard. Most C64 games need a " +
+                "keyboard key to START (e.g. F1 for 1 player); the pad's spare " +
+                "buttons/right-stick map to those (F1/F3/F5/F7, Space, Run/Stop, " +
+                "Return). Default joystick port is 2; change with input({op:'joyport'}).",
+            }
+          : noController
           ? {
               keyboardControls: KEYBOARD_BINDINGS_HELP,
               tellUser:

package/src/platforms/_guides/ROMHACKING_PLAYBOOK.md

@@ -22,6 +22,32 @@ read that platform's `platform({op:'doc', platform, name:'mental_model'})`.
 The cheat DB is bundled (`romdev_game_codes`). Do **not** scan the user's disk for
 `.cht` files — if it's not in the bundled DB, treat it as absent and RE it.
 
+**Reading a `cheats({op:'lookup'})` hit as a RAM/code map.** Each decoded part carries an
+`address`, a `value`, a `kind` (`ram` = a labeled variable; `code` = a labeled ROM
+patch site, has a `compare`), and a `device` (`game-genie`/`pro-action-replay`/
+`gameshark`/`action-replay`/`raw`). So "which byte holds magic?" → one `lookup` call.
+Filter a long list with `filter:"health"` or `kind:"ram"`. A match is by No-Intro
+**name/filename, NOT a verified CRC** — it's PROBABLE (a different region/revision can
+move addresses), so confirm before patching. The cheapest confirmation is to apply it
+and watch: `cheats({op:'apply', path, desc})` → `frame({op:'screenshot'})`.
+
+`cheats({op:'apply'})` is non-destructive (volatile core state, the RetroArch way — the ROM
+file is never touched; `host({op:'reset'})`/`state({op:'load'})`/`cheats({op:'clear'})` removes it). It takes a
+matched `desc`, a raw `code`, or `loadMedia({cheats:[…]})` to seed codes BEFORE frame 0.
+`appliedAs` reports how it went in (`ram` poke / `rom` read-intercept / `raw` device
+code). DB coverage is 13/14 (every tier-1 system except C64); GBA cheats are
+encrypted, so apply-only (no labeled-address map — see `mapNote`).
+
+**Creating a NEW code — `cheats({op:'make', platform, address, value, compare?})`.** The inverse of
+decoding: turn a byte you found (via §1 or `breakpoint`) into a shareable, verified code,
+for ANY ROM incl. your own homebrew/WIP. A RAM cheat needs just `address`+`value`; a ROM
+patch adds `compare` (the byte currently there). It encodes for the platform's native
+device(s) and labels each (NES/Genesis → Game Genie; SNES → Pro Action Replay **and**
+Game Genie; GB/GBC → Game Genie + GameShark; SMS/GG → Action Replay) plus the raw
+`ADDR:VAL`; each carries `verified:true` (round-trips against the full DB). Systems with no
+letter-code device (Atari 2600/7800, Lynx, GBA, C64, PC Engine, MSX) get a verified raw
+code. Works on all 14. Nothing is ever written to a ROM file.
+
 ---
 
 ## 1. To find the RAM address of a value (score / timer / stat / HP / record-id)
@@ -50,12 +76,20 @@ usually a struct/entity array, each island one record.
 The #1 trap: visible names/labels are often **pre-rendered tile GRAPHICS**, not
 font-rendered from an ASCII string. Patching the ASCII string then does nothing.
 
-1. `text({op:'learn'})` on the on-screen text. If it reports
-   `likelyPreRenderedGraphic:true` (unique sequential tiles, no font reuse),
-   **stop** — the text is a bitmap. Editing it means changing tile pixels, not a
-   string. Do not patch any ASCII string you found; it isn't the source.
-2. If it IS font-rendered, find the string with `text({op:'find'})` /
-   `text({op:'encode'})` and patch that.
+1. `text({op:'learn'})` on the on-screen text — it infers the game's char→tile-ID map
+   (games use their own encoding: Excitebike A=$0A, Mario ASCII-offset, FF sparse). Two
+   modes: ROM mode `knownStrings:[{text, offset}]` when you found the bytes; **LIVE mode
+   `fromScreen:[{text, row, col}]`** reads the tile IDs straight off the live BG map at a
+   tile position (`background({view:'map'})` shows where the text sits) — this breaks the
+   chicken-and-egg of needing the offset you're still hunting. Live mode works on every
+   tilemap platform (NES/SNES/Genesis/GB/GBC/SMS/GG/C64); atari2600/7800, lynx, gba have
+   no text nametable → ROM mode only. If `learn` reports `likelyPreRenderedGraphic:true`
+   (unique sequential tiles, no font reuse), **stop** — the text is a bitmap. Editing it
+   means changing tile pixels, not a string. Do not patch any ASCII string you found.
+2. If it IS font-rendered: `text({op:'find', romPath, text, fontMap})` locates the string
+   (returns `fileOffset`, `prgFileOffset`, and a bank-aware `cpuAddress`+`bank` to feed
+   `disasm({target:'rom'})`; flags a likely length-prefix byte to avoid the overrun trap),
+   then `text({op:'encode', text, fontMap})` → bytes for `romPatch({op:'write'})`.
 3. To find where a graphic/text was sourced from: on **Genesis**, `watch({on:'dma', precision:'sampled'})`
    — drive to the screen that shows the graphic, and it reports the ROM offset(s)
    the tiles were DMA'd from (decoded from the VDP DMA registers). Edit the tile
@@ -103,6 +137,15 @@ from a SOURCE struct rather than written in place. Don't conclude "the address
 is wrong." Find the source: `memory({op:'search'})` the live value to locate the struct
 the copy reads from, then `breakpoint({on:'write'})` on THAT.
 
+**Precision — exact vs sampled.** The default `breakpoint({on:'write'})` is a core-level write
+watchpoint: it returns the EXACT writing instruction's PC, captured inside the CPU write
+path — correct even for NMI/IRQ-driven writes (the common case where a frame-sampled PC
+is just the idle loop). On a banked mapper it reports the `bank` (NES/GB/SMS-GG) so you
+can pass `{startAddress, bank}` to `disasm({target:'rom'})`. The lighter
+`breakpoint({on:'write', precision:'sampled'})` (a.k.a. `watch({on:'mem'})`) steps until the byte changes
+and returns a frame-boundary PC — a lead, not a guarantee under interrupts; use it for the
+value timeline or when you just want the change history, and cross-check the value trace.
+
 ---
 
 ## 5b. To READ a register at an instruction — execution breakpoints (all 14)
@@ -254,6 +297,101 @@ and `input({op:'set'})` state it too.)
 
 ---
 
+## 7. Authoring & verifying the byte patch
+
+Once you know WHAT to change, the write loop is a handful of calls — no custom scripts:
+
+- **`assembleSnippet({cpu, origin, code})`** — assemble a tiny asm chunk to raw bytes (no
+  header/linker/segments). CPUs: `6502 / 65c02 / 65816 / 68k / z80 / sm83 / gb / gbc /
+  huc6280`. **Z80 gotcha:** the sdas dialect requires `#` on immediates (`ld a,#5`, not
+  `ld a,5`).
+- **`romPatch({op:'write', path, offset, hex, expect})`** — the splicer THE other hack tools
+  compose through. **Always pass `expect`** (the current bytes) — it refuses the write if
+  they don't match, catching a hex/dec slip or a patch authored against region A applied to
+  region B. `allowExpand` for size-changing edits.
+- **`romPatch({op:'diff', platform, a, b})`** — mapper-aware ROM diff: reports CPU addresses
+  (NROM-128 mirrors, SNES LoROM `XX:XXXX`), per-region tallies (PRG vs CHR vs header), and
+  `tile:N` annotations on CHR changes for direct sprite-hack identification. Use it to
+  confirm a patch landed where you meant.
+- **`disasm({target:'references', path, platform, address})`** — find every instruction that
+  references a target address, classified `call/jump/branch/read/write/use/ref` (walks the
+  vector table too). The fast "who touches this?" for a STATIC image. Limitation: direct
+  addressing only — indirect/computed jumps aren't detected (use the runtime `watch`/
+  `breakpoint` tools in §5/§5d for those).
+- **`cart({op:'extract', path, outputDir})`** — split a ROM into standard parts (NES header/
+  prg/chr; SNES copier_header+rom+internal header; Genesis vectors/header/body; GB boot/
+  header/body) + a `manifest.json` (mapper, mirroring…). **`cart({op:'wrap'})`** is the inverse:
+  emits `wrapperSource` + `linkerConfig` ready for `build({output:'rom'})`.
+
+Verify-before-patch: `memory({op:'write', region:'system_ram', offset, hex})` on the LIVE emulator and
+watch the screen react — cheaper than shipping a wrong ROM patch.
+
+## 7b. Whole-ROM rebuildable disassembly — `disasm({target:'project'})`
+
+For a STRUCTURAL hack (new logic, not a byte poke), turn the whole ROM into a
+re-buildable project in one call: `disasm({target:'project', path, outputDir})`. It splits
+the ROM into regions (per-16KB bank for banked NES, per-32KB for SNES LoROM, slot0+slotX
+for GB, one flat region for SMS/Genesis/C64/Atari), disassembles each through the CPU's
+native objdump, then **reassembles + verifies byte-exact** against the original; any line
+that won't reproduce faithfully heals to a `.byte`/`db` of its real bytes, so the emitted
+`.asm` ALWAYS rebuilds (`roundTrip.allByteExact`). `readablePercent` per region tells you
+how much came back as real instructions vs. data. Alongside the `.asm` it writes the
+turnkey **rebuild glue**: data blobs (NES CHR-ROM → `chr.bin`; stripped Genesis/GBA/Lynx/MSX
+cartridge header → `*.bin`), a `BUILD.md` with the exact steps, and — where a one-call
+rebuild exists — a `rebuild.json` of the precise `build({...})` args. So the loop is
+`disasm({target:'project'})` → edit a `.asm` → rebuild → `romPatch({op:'diff'})` to confirm.
+
+**Two rebuild tiers** (the disasm emits each CPU's native-reassembler syntax — ca65 for
+6502/65816, GNU `as` for m68k/arm/z80/gbz80 — which only some `build()` toolchains consume):
+- **One-call `build()` rebuild, byte-identical** — **NES, C64, Atari 7800, Lynx**. Feed
+  `rebuild.json` straight to `build`. (Lynx: `build()` yields the headerless image; prepend
+  the shipped `lnx_header.bin` for the full `.lnx`.)
+- **Native-recipe rebuild (`buildCall:null`), byte-identical, steps in `BUILD.md`** — **SMS,
+  GG, MSX, GB, GBC, Genesis, GBA, Atari 2600**. Their `build()` toolchains (SDCC/RGBDS/asar/
+  dasm/vasm) can't reassemble ca65/GNU-as syntax, so `BUILD.md` gives the proven native
+  `as`/`ld`/`objcopy` chain.
+- **PC Engine** is the one not-yet-byte-exact case (the region trims real padding / doesn't
+  strip a copier header) — `BUILD.md` flags it.
+
+**Rebuilding a commercial NES (NROM CHR-ROM) game — `build({inesHeader})`:** the most common
+NES RE rebuild. `build({output:'rom', platform:'nes', inesHeader:{prgBanks, chrBanks, mapper,
+mirroring}, sourcesPaths:{…the PRG…}, binaryIncludePaths:{"chr.bin":…}})` auto-emits the
+16-byte iNES header + CHARS-segment wiring + flat NROM `.cfg` — no hand-derived header bytes.
+`disasm({target:'project'})` puts exactly this call in `rebuild.json`. (For homebrew C that
+ships fixed tile art, `linkerConfig:"chr-rom"` is the segment-split equivalent.)
+
+**Readability caveats** (the bytes are ALWAYS correct; only instruction-vs-`.byte` coverage
+varies): SNES and large Genesis ROMs come back byte-exact but DATA-ONLY (flat whole-ROM
+disasm of a mostly-data image heals to `.byte` — meaningful coverage needs recursive
+entry-point following, a known follow-up). GBA reads LOW because GBA C compiles mostly to
+Thumb reached via an ARM crt0 stub, so an ARM-mode disasm decodes Thumb spans as `.byte`.
+Banked-NES is the strongest case (~100% instructions); GB/GBC, SMS/GG, C64, Atari are also
+near-100%.
+
+## 8. Graphics swaps — PNG ↔ tiles round-trip
+
+For sprite/tile edits (not text), don't hand-roll the tile-format math:
+
+- **`tiles({op:'png', source:'path', platform, path, bank, paletteFromEmulator, paletteIndex})`** —
+  a source ROM's tiles → PNG. `bank:N` (NES 4 KB CHR bank) replaces magic file-offset math;
+  `paletteFromEmulator:true`+`paletteIndex` colors the export with the LIVE palette (vs
+  grayscale) so the art is recognizable to edit.
+- **`importArt({from:'rom', sourceRom, sourcePlatform, sourceBank, sourceTileX/Y/W/H, targetPlatform,
+  outputPng, intent, paletteIndex})`** — one-call lift of a tile region from a source ROM into
+  the target platform's format (extract+crop+quantize). `intent:"homebrew"` reads the live
+  source palette; `intent:"rom-hack"` preserves source bytes verbatim.
+- **`encodeArt({stage:'tiles', platform, pngBase64})`** → target-platform tile bytes.
+- **`romPatch({op:'spliceCHR', path, platform, pngBase64, tileIndex, expect, bank, paletteHint})`** —
+  PNG → tile bytes → splice into CHR at tile slot N (auto-locates iNES CHR base; `expect`
+  checks the existing tile bytes; `paletteHint:["#RRGGBB",…]` gives explicit RGB→index
+  mapping). Composes the `encodeArt`+`romPatch({op:'write'})` step in one call.
+- **`background({view:'rendered'})`** — at the current state, the set of tile IDs actually drawn
+  (BG nametable + OAM). Sample at title/gameplay/menu and diff the sets to map tile IDs to
+  assets without scanning sheets by eye. (`romPatch({op:'findFree'})` locates $FF/$00 runs for asm
+  overlays, longest-first.)
+
+---
+
 ## Quick reference
 
 | Goal | Tool |
@@ -276,4 +414,15 @@ and `input({op:'set'})` state it too.)
 | Where did a VRAM graphic come from (Genesis) | `watch({on:'dma', precision:'sampled'})` (ROM offset of the DMA source) |
 | Drive a menu fast | `input({op:'navigate'})` (advances on screen change) |
 | Free RAM map for a known game | `cheats({op:'lookup'})` / `cheats({op:'search'})` |
+| Apply a cheat live (non-destructive) | `cheats({op:'apply'})` (verify a label / fun) |
+| Create a shareable code from a byte | `cheats({op:'make'})` (verified, all 14) |
+| Read on-screen text's tile map | `text({op:'learn', fromScreen})` (live, no offset needed) |
+| Find / encode a font-rendered string | `text({op:'find'})` → `text({op:'encode'})` |
+| Assemble asm → raw patch bytes | `assembleSnippet({cpu, origin, code})` |
+| Mapper-aware diff of two ROMs | `romPatch({op:'diff'})` (CPU addrs, CHR `tile:N`) |
+| Who references this address (static) | `disasm({target:'references'})` (direct modes only) |
+| Split / rebuild a ROM into parts | `cart({op:'extract'})` / `cart({op:'wrap'})` |
+| Swap a sprite/tile (PNG round-trip) | `tiles({op:'png'})` → edit → `romPatch({op:'spliceCHR'})` |
+| Lift art from another game's ROM | `importArt({from:'rom'})` |
+| Tile IDs actually being drawn now | `background({view:'rendered'})` |
 | Safe patch | `romPatch({op:'write'})`/`romPatch({op:'writeMany'})` with `expect` |

package/src/platforms/atari2600/MENTAL_MODEL.md

@@ -192,3 +192,40 @@ When you call `build({output:'rom', platform:"atari2600", source: ...})`:
 2. The result is `.a26` — loadable in stella (`loadMedia`).
 
 There's no linker — dasm produces a complete cart in one pass.
+
+## MCP debug & inspection tooling
+
+The 2600 runs on the **stella2014 (patched)** core. Because the 2600 has
+no framebuffer and no standard sound chip, its inspectors look different
+from the tilemap consoles — they decode the live TIA snapshot instead.
+
+What you can read:
+
+- **`palette({source:'live'})`** — the NTSC 128-color palette as a PNG,
+  with the *current* TIA background luma+hue extracted from the live
+  snapshot so you can see what color the beam is painting right now. This
+  is the same 128-entry `HHHHLLLL` palette the 7800 uses.
+- **`sprites({op:'inspect'})`** — there is **no OAM** on the 2600, so this
+  returns the state of the 5 TIA graphics objects (P0, P1, M0, M1, Ball)
+  plus a current-scanline PNG showing how the TIA is composing that line.
+- **`cpu({op:'read'})`** — the 6502 register file (A / X / Y / P / SP / PC)
+  pulled from the M6502 core's internal regs.
+- **`background({view:'renderState'})`** — decodes the 32-byte TIA snapshot
+  into the playfield pattern, per-object enables/positions, and the color
+  registers.
+- **`disasm({target:'rom'})`** and **`disasm({target:'references'})`** —
+  both anchor to the top of the bank (`$F000-$FFFF`) and label the vector
+  table (NMI / RESET / IRQ at `$FFFA`).
+
+Memory regions for **`memory({op:'read'})`**:
+
+| Region | Size | What it is |
+| --- | --- | --- |
+| `system_ram` | 128 bytes | the RIOT RAM — that's the *entire* console RAM |
+| `a26_tia_regs` | 32 bytes | the live TIA register snapshot |
+| `a26_cpu_regs` | 7 bytes | the 6502 register snapshot |
+
+**No `audioDebug` inspector.** The 2600's sound comes from the two TIA
+audio voices (`AUDC/AUDF/AUDV` at `$15-$1A`), not a standard PSG/FM chip,
+so there's no `audioDebug` decode — read the audio state directly out of
+the `a26_tia_regs` snapshot instead.

package/src/platforms/atari7800/MENTAL_MODEL.md

@@ -322,3 +322,39 @@ When you call `build({output:'rom', platform:"atari7800", language:"c"})`:
 3. ld65 links + atari7800.cfg → flat `.a78` ROM.
 
 Loadable via prosystem (`loadMedia`).
+
+## MCP debug & inspection tooling
+
+The 7800 runs on the **prosystem (patched)** core. Like the 2600 it has
+no framebuffer and no tile/sprite-attribute tables, so its inspectors
+decode MARIA's display-list machinery rather than a tilemap.
+
+What you can read:
+
+- **`palette({source:'live'})`** — a 256-color master palette PNG, with
+  the live MARIA palette block at `$20-$3F` decoded into the 8 palettes ×
+  3 colors each, plus the backdrop. This is the Atari NTSC palette shared
+  with the 2600.
+- **`sprites({op:'inspect'})`** — there is **no OAM** on the 7800. Instead
+  this returns the MARIA control registers and the **DPP** display-list-
+  list pointer, leaving the agent to walk the DLL → DL hierarchy itself
+  (the same structure described under "MARIA: the unusual one" above).
+- **`cpu({op:'read'})`** — the 6502 ("Sally") register file (A / X / Y /
+  P / SP / PC) read from prosystem's `sally` globals.
+- **`background({view:'renderState'})`** — the MARIA CTRL bits, DPP,
+  CHARBASE, and the current `dlistPtr`.
+- **`disasm({target:'rom'})`** and **`disasm({target:'references'})`** —
+  both default to the top 16 KB (`$C000-$FFFF`), where the reset vector
+  lands.
+
+Memory regions for **`memory({op:'read'})`**:
+
+| Region | Size | What it is |
+| --- | --- | --- |
+| `system_ram` | 64 KB | the *entire* 6502 address space — MARIA regs, RAM, and ROM are all visible through this one region |
+| `a78_cpu_regs` | — | the 6502 register snapshot |
+
+**No `audioDebug` inspector.** The 7800's standard audio is the same TIA
+chip carried over from the 2600 (`$15-$1A`), not a decodable PSG/FM chip,
+so there's no `audioDebug` decode. (Some carts add a POKEY, but it's
+non-standard — don't assume it's present.)