romdevtools 0.23.0 → 0.25.0

package/src/platforms/gg/MENTAL_MODEL.md

@@ -160,6 +160,30 @@ void main(void) {
 }
 ```
 
+## MCP debug & inspection tooling
+
+Game Gear runs on the same genesis_plus_gx (gpgx, patched) core as SMS, so the
+inspectors are identical. **The canonical reference lives in the SMS
+MENTAL_MODEL** (`src/platforms/sms/MENTAL_MODEL.md`, "MCP debug & inspection
+tooling" section): `sprites({op:'inspect'})`, `tiles({op:'png'})`,
+`cpu({op:'read'})` (Z80), `background({view:'renderState'})`,
+`audioDebug({op:'inspect', chip:'psg'})` (SN76489, the shared
+SMS/GG/Genesis region), and the z80 `objdump` disasm pipeline all apply
+unchanged.
+
+Game-Gear-only deltas:
+
+- **`palette({source:'live'})`** decodes **12-bit BGR (4-4-4)**, twice the
+  depth of SMS's 6-bit. CRAM is **64 bytes** (2 little-endian bytes per
+  entry) instead of 32.
+- The Game-Gear memory regions are **`gg_vram`** and **`gg_cram`** (the
+  64-byte palette); use these instead of `sms_vram` / `sms_cram`. The
+  `sms_vdp_regs` / `sms_z80_regs` register regions are shared (same VDP and
+  Z80).
+- `sprites({op:'inspect'})` X/Y fields are reported in **256×192 hardware
+  coordinates**, not the 160×144 visible window — match them with
+  hardware-coord arithmetic (see "Sprite coords are hardware-space" above).
+
 ## Differences from SMS — quick reference
 
 - Visible 160×144 vs 256×192 — center content

package/src/platforms/lynx/MENTAL_MODEL.md

@@ -35,13 +35,39 @@ Mikey handles:
 - **Joystick** — read via SWITCHES register at `$FCB0`. cc65 provides
   `joy_read(JOY_1)` + `JOY_LEFT/RIGHT/UP/DOWN/BTN_1/BTN_2` macros.
 
-**Live debug:** `audioDebug({op:'inspect', chip:"mikey"})` decodes the 4 audio voices
-(volume, period→freq→note, LFSR state); `palette({source:'live'})` reads the 16-entry
-palette; `background({view:'renderState'})` shows DISPCTL + the display base address;
-`cpu({op:'read'})` reads the 65C02; `breakpoint({on:'write'})` is the write watchpoint. **Sprites
-are the exception** — the Lynx has no fixed OAM (sprites are SCB linked lists
-walked by Suzy), so `sprites({op:'inspect'})` returns the SCB list head ($FC10/$FC11) and
-you walk the chain over `system_ram`, rather than reading a sprite table.
+**Live debug:** the MCP inspectors (`palette` / `cpu` / `audioDebug` /
+`background` / `breakpoint`, and the SCB-list-head `sprites` special case) are
+documented in "MCP debug & inspection tooling" below.
+
+## MCP debug & inspection tooling
+
+The Lynx runs on handy (patched). The inspectors read the *live* core state —
+reach for them when a sprite or palette renders wrong and the source alone
+doesn't explain it. Details and the per-tool facts:
+
+- **`palette({source:'live'})`** — the **16-entry, 12-bit RGB** Mikey palette
+  (`$FDA0-$FDBF`) converted to RGB.
+- **`cpu({op:'read'})`** — 65C02 dump: A / X / Y / P / SP / PC plus the
+  decoded flag bits.
+- **`audioDebug({op:'inspect', chip:'mikey'})`** — the 4 Mikey voices: volume,
+  the timer→period→frequency→note chain, and the **12-bit LFSR** state.
+- **`background({view:'renderState'})`** — decodes DISPCTL: the DMA-enable,
+  flip, and color-mode bits plus the display base address.
+- **`sprites({op:'inspect'})` is the special case.** The Lynx has **no fixed
+  OAM** — sprites are **SCB (Sprite Control Block) linked lists in RAM** that
+  Suzy walks at blit time. So this tool can't return a sprite table; instead
+  it returns the **SCB list head (SCBNEXT, `$FC10`/`$FC11`)** plus
+  instructions to walk the chain yourself over `system_ram`.
+
+### Memory regions (`memory({op:'read', region:…})`)
+
+| Region          | Address / size        | Contents                                              |
+|-----------------|-----------------------|-------------------------------------------------------|
+| `lynx_cpu_regs` | —                     | 65C02 register snapshot                               |
+| `lynx_hw_regs`  | $FC00-$FDFF window     | the **Suzy + Mikey** register window — sprite-engine regs, LCD control, audio, palette |
+| `system_ram`    | 64 KB                 | full address space (also where the SCB chain lives)   |
+
+Pair these with `breakpoint({on:'write'})` for the full live-debug loop.
 
 ## Frame heartbeat (cc65 + tgi)
 

package/src/platforms/msx/MENTAL_MODEL.md

@@ -117,3 +117,30 @@ exactly this.
   generator + the envelope (period + shape bits).
 - `memory({op:'read'})` regions: `msx_vram`, `msx_vdp_regs`, `msx_vdp_status`,
   `msx_palette`, `msx_cpu_regs`, `msx_psg_regs`, plus `system_ram` (work RAM).
+
+## MCP debug & inspection tooling
+
+MSX is a **Tier-1** platform with deep introspection — the full set of
+inspectors and memory regions is listed under **"Debugging tools"** above
+(`cpu` / `background` / `palette` / `sprites` / `symbols` / `audioDebug` for
+the AY-3-8910 PSG, and the `msx_vram` / `msx_vdp_regs` / `msx_vdp_status` /
+`msx_palette` / `msx_cpu_regs` / `msx_psg_regs` / `system_ram` regions). The
+PSG-channel decode means `audioDebug({op:'inspect', chip:'ay8910'})` gives
+you the 3 square-wave channels plus the shared noise generator and envelope
+without poking at `msx_psg_regs` by hand.
+
+### ColecoVision shares this core family — but is bring-up only
+
+ColecoVision runs the same toolchain family and exposes only the **standard**
+introspection: `system_ram` + `save_ram` + `video_ram`. It has **no deep
+inspectors** (no `palette` / `sprites` / `background` / `audioDebug` decode)
+and **no MENTAL_MODEL of its own** — treat it as a bring-up target, not a
+finished Tier-1 platform.
+
+### Extending introspection (for whoever adds a platform)
+
+Deeper, decoded inspectors are not free — each is implemented by **patching
+the emulator core** to expose the extra register/VRAM regions, then wiring a
+decoder. To add deep introspection to ColecoVision (or any thin platform),
+follow the existing core-patch pattern used for snes9x / gpgx / fceumm / vice
+under **`scripts/patches/`**.

package/src/platforms/nes/MENTAL_MODEL.md

@@ -25,6 +25,13 @@ The cc65 runtime claims:
 - ZP $1C+ available to your game (with our chr-ram crt0)
 - `$0500-$07FF` (3 pages): cc65 C parameter stack
 
+> **cc65 zero-page starts at $02, not $00 (applies to every cc65 platform —
+> NES, C64, Atari, Lynx, …).** cc65 reserves `$00-$01` for its runtime, so your
+> first `.res 1` in the `ZEROPAGE` segment lands at **$02**, not $00. If you
+> hand-write asm that assumes a zero-page var is at $00 you'll clobber the
+> runtime. Confirm actual addresses with `symbols({op:'map'})` after
+> `build({output:'romWithDebug'})`.
+
 ## PPU memory map (separate from CPU bus!)
 
 ```
@@ -94,6 +101,15 @@ The `nes_runtime` helper `tile_set_palette(nt, x, y, palette)` does
 the read-modify-write dance and the bit-twiddling — use it instead
 of writing attributes by hand.
 
+> **256-tile cap per pattern table (the busy-image trap).** The nametable's
+> tile index is 8-bit, so a single pattern table holds at most **256 unique
+> tiles** — and a per-frame BG can therefore use at most 256 distinct tiles.
+> Auto-converting a busy full-screen illustration almost always needs more than
+> 256 unique 8×8 tiles and **overflows**; `encodeArt({stage:'tilemap'})` warns
+> when it does. The only real workaround is mid-frame CHR bank switching
+> (an MMC3-class mapper) — the bundled NROM presets can't do it, so design BG
+> art to reuse tiles (≤256 unique per table).
+
 ## Palettes
 
 32 bytes at $3F00-$3F1F:
@@ -329,6 +345,25 @@ incorrectly aligned."
   scrolling worlds you need to manage the nametable buffer + bank
   switching yourself.
 
+## MCP debug & inspection tooling
+
+The shipped fceumm core is patched for live introspection — read state
+instead of guessing:
+
+- **Sprites:** `sprites({op:'inspect'})` decodes live OAM.
+- **Palette:** `palette({source:'live'})` reads the live 32-byte palette RAM.
+- **CPU:** `cpu({op:'read'})` reads the 6502.
+- **Background render state:** `background({view:'renderState'})` decodes
+  PPUCTRL/PPUMASK and resolves the active CHR bank (plus its file offset) —
+  this is what tells you which pattern table BG vs sprites are fetching from
+  (the bit-4 footgun above).
+- **Memory regions:** `memory({op:'read'})` exposes OAM, Palette,
+  Nametables (CIRAM — including the 2-bit-per-16x16 attribute data that
+  selects each tile group's sub-palette, decoded by `inspectBackgroundMap`),
+  CHR (live MMC1-banked CHR — don't parse the iNES file), CPU_REGS,
+  PPU_REGS, and APU_REGS (the synthesized $4000-$4017 snapshot consumed by
+  `audioDebug`).
+
 ## Rebuilding a CHR-ROM NROM image (reverse-engineering)
 
 The homebrew presets above are CHR-**RAM** (the CPU uploads tiles at runtime).

package/src/platforms/sms/MENTAL_MODEL.md

@@ -267,6 +267,57 @@ Loadable via genesis_plus_gx (`loadMedia`).
 - Game Gear-specific buttons add port $00 read (Start) and stereo
   PSG control on port $06.
 
+## MCP debug & inspection tooling
+
+SMS and Game Gear share the genesis_plus_gx (gpgx, patched) core, so the
+inspectors below behave identically on both. This section is the **canonical
+shared reference**; the Game Gear MENTAL_MODEL points back here and only lists
+its own deltas (12-bit CRAM, etc.). Reach for these when something renders
+wrong and you can't see why from the source alone — they read the *live* core
+state, which beats trusting comments.
+
+- **`sprites({op:'inspect'})`** — decodes the live SAT (sprite attribute
+  table) and renders a sprite-sheet PNG. Reports each slot's X/Y/tile plus
+  `spriteTileDataBase` (the VRAM address the VDP is actually fetching sprite
+  tiles from). This is the tool that catches the $D0-terminator and the
+  R6/$2000-vs-$0000 sprite-bank footguns described above — trust its bytes
+  over any comment.
+- **`palette({source:'live'})`** — reads CRAM and converts to RGB. On SMS
+  that's **6-bit BGR** (2-2-2, 32 bytes). On Game Gear it's **12-bit BGR**
+  (4-4-4, 64 bytes) — see the GG MENTAL_MODEL for that delta.
+- **`tiles({op:'png'})`** — dumps VRAM tile patterns as a sheet. The format
+  is 4bpp bitplane-interleaved (32 bytes/tile); the 16 KB VRAM renders as a
+  512-tile sheet.
+- **`cpu({op:'read'})`** — Z80 register dump: A/F, BC/DE/HL, IX/IY, the
+  shadow register set, the flag bits, and interrupt state (IM mode / IFF).
+- **`audioDebug({op:'inspect', chip:'psg'})`** — decodes the live SN76489:
+  3 tone channels + 1 noise channel. The PSG region is shared by SMS, GG, and
+  Genesis (same gpgx region).
+- **`background({view:'renderState'})`** — reads the VDP registers and reports
+  the derived addresses (name table, BG-tile base, sprite-tile base, SAT base),
+  the scroll registers, and the display-enable / mode state. Use this to
+  confirm the R2/R4/R5/R6 baseline matches where you actually uploaded data.
+
+### Memory regions (`memory({op:'read', region:…})`)
+
+| Region          | Contents                                             |
+|-----------------|------------------------------------------------------|
+| `sms_vram`      | 16 KB VRAM — tiles + name table + SAT + sprite tiles |
+| `sms_cram`      | 32-byte palette (2-2-2 BGR)                          |
+| `sms_vdp_regs`  | the 11 VDP control registers ($00-$0A)              |
+| `sms_z80_regs`  | Z80 register snapshot                                |
+| `gg_vram`       | Game Gear VRAM                                        |
+| `gg_cram`       | Game Gear 64-byte palette (4-4-4 BGR)                |
+
+### Disassembly (`disasm({target:…})`)
+
+`disasm({target:'rom'})`, `disasm({target:'references'})`, and
+`disasm({target:'project'})` all run the live ROM through the native binutils
+**z80 `objdump`** (WASM, `-m z80`). It has full prefix coverage —
+CB/ED/DD/FD/DDCB/FDCB — and feeds the same auto-label, register-annotation,
+file-offset, and `untilReturn` pipeline used by the NES and SNES
+disassemblers.
+
 ## Horizontal scrolling (for side-scrollers)
 
 The `platformer` scaffold is single-screen. To make it a side-scroller:

package/src/platforms/snes/MENTAL_MODEL.md

@@ -208,6 +208,27 @@ per-voice vol/pitch/ADSR + `env` (0 = silent regardless of vol) + `bufLastSample
 produced output" from "muted by mixer." GOTCHA: S-DSP FLG is $6C, KOFF is $5C
 (many refs swap them); power-on FLG=$E0 means your driver MUST clear bit 6.
 
+## MCP debug & inspection tooling
+
+The shipped snes9x core is patched for deep introspection — both audio and
+video are fully readable, so you assert live state instead of guessing:
+
+- **Sprites:** `sprites({op:'inspect'})` decodes live OAM (per-sprite
+  renderable/hidden, resolved tile VRAM addr, CGRAM palette range, and the
+  uninitialized-OBJ-palette warning described under "The OBJ stable-path
+  recipe").
+- **Palette:** `palette({source:'live'})` reads live CGRAM.
+- **CPUs:** `cpu({op:'read', cpu:'main'})` for the 65816, `cpu({op:'read',
+  cpu:'spc700'})` for the sound CPU.
+- **Audio:** the S-DSP is fully decodable — full per-voice state plus the
+  master mixer (see "Debugging sound" above for `audioDebug`).
+- **Memory regions:** `memory({op:'read'})` exposes OAM, CGRAM, ARAM (SPC700
+  audio RAM), and **FillRAM**. Note the FillRAM quirk: snes9x mirrors the
+  PPU registers $2100-$213F (OBSEL/BGMODE/TM/TS/color-math, etc.) into
+  FillRAM indexed by the FULL address (e.g. `FillRAM[0x2101]` = OBSEL), so
+  the PPU register state is readable through the `snes_fillram` region — no
+  core patch needed.
+
 ## ROM layout (LoROM)
 
 ```

package/src/platforms/snes/TROUBLESHOOTING.md

@@ -193,6 +193,49 @@ Expected. tcc-65816.wasm + wla-65816.wasm cold-load + compile takes
 1-2s. Subsequent builds reuse the warm worker pool (R12 crash
 isolation infrastructure). Steady-state builds are sub-second.
 
+## "asm build fails with `ok:false` and an empty/cryptic `issues[]`" (asar idioms)
+
+The `language:"asm"` SNES path runs through **asar**, which **silently crashes**
+(a heap-pointer Emscripten exit code, no diagnostic) on a handful of source
+idioms. romdev's asar wrapper has a preflight that catches the common cases and,
+when asar dies with `ok:false` and no parsed errors, retries with `--verbose` and
+synthesizes a fallback `issues[]` entry with a hint. The idioms to avoid:
+
+- **`$ - label` size expressions** (current-PC minus a label) crash asar. Use an
+  explicit `end_label - start_label` difference instead:
+  ```asm
+  ; WRONG — crashes asar silently
+  my_size = $ - my_data
+  ; RIGHT
+  my_data_end:
+  my_size = my_data_end - my_data
+  ```
+- **Opcode + operand arithmetic on an `=`-defined symbol**, e.g.
+  `STA SYMBOL + N` where `SYMBOL` is a `=` constant (not a label), can also crash
+  silently. The preflight flags the label-arithmetic-across-bank case
+  (`label-arithmetic constant`); for the rest, if you see `ok:false` with no real
+  error, suspect a `SYMBOL + N` and rewrite to a plain label or pre-compute the
+  address.
+- **Bank-border crossed.** If your `org` + `dw`/data runs past `$00FFFF` you've
+  crossed a bank boundary and the layout is wrong. Native interrupt vectors live
+  at `$FFE4-$FFEE`, emulation vectors at `$FFF4-$FFFF` — keep your header/vector
+  block where the layout expects it. Use
+  `scaffold({op:'snippets', platform:"snes", mode:"get", name:"lorom_header.asm"})`
+  for the canonical layout (and `lorom_multibank.asm` for multi-bank).
+
+(This is the asar/asm path. The default PVSnesLib **C** path goes through
+tcc-65816 + wla-65816 and has its own C89 trap, above.)
+
+## "CHR and tilemap overlap in VRAM / background renders as garbage tiles"
+
+SNES CHR (tile patterns) and the BG tilemap share the 64 KB VRAM, addressed in
+**words**. CHR starts at word `$0000`; if your CHR is 16 KB it occupies words
+`$0000-$1FFF`, so a tilemap placed at word `$2000` collides with the tail of CHR
+and you get garbage. **Put the tilemap at word `$4000` or later when your CHR is
+big.** Verify the bases with `background({view:'renderState', platform:'snes'})`
+(it decodes the BG char/map base) and cross-check the tile region with
+`tiles({op:'png'})` at the CHR base.
+
 ## "I want to use real graphics from a PNG"
 
 `gfx4snes` (the PVSnesLib companion tool) converts PNG → .pic + .pal.

package/src/playtest/playtest.js

@@ -231,6 +231,32 @@ const KEY_TO_LIBRETRO_BIT = {
   w: 11,                       // R shoulder
 };
 
+// C64-only keyboard fallback: PC key → the virtual C64 button name the host's
+// C64 layer maps to the key matrix (Space/Run-Stop/Return/F1-F7). Lets a human
+// with NO controller still reach the C64 keyboard keys games need to start.
+// (Arrows + Z give the joystick + Fire via KEY_TO_LIBRETRO_BIT above.)
+const C64_KEYBOARD_FALLBACK = {
+  f1: "c64_f1", f2: "c64_f3", f3: "c64_f5", f4: "c64_f7",  // F1-F4 → C64 F1/F3/F5/F7
+  space: "west",          // Space
+  return: "r2",           // Return (also START via the standard map — harmless)
+  escape: "l2",           // Run/Stop (note: ESC also closes — see handler order)
+};
+
+// Human-readable C64 controls (controller + keyboard), relayed to the user when
+// a C64 game is in the playtest window so they're not guessing.
+export const C64_BINDINGS_HELP = `C64 — a CONTROLLER alone is enough (no keyboard needed):
+  D-pad / Left stick   Joystick (port 2 by default)
+  Z / bottom face      Fire
+  X face / Space key   Space
+  L2                   Run/Stop
+  R2 / Enter           Return
+  Right stick  ↑/←/→/↓  F1 / F3 / F5 / F7   (the 1-player / start keys)
+  Top face             F1 (also)
+
+No controller? Keyboard fallback: Arrows = joystick, Z = Fire, F1-F4 = C64
+F1/F3/F5/F7, Space = Space, Enter = Return, ESC = Run/Stop (hold; ESC tapped
+also closes the window). Switch joystick port with input({op:'joyport'}).`;
+
 // Human-readable summary printed by --help and at playtest startup.
 export const KEYBOARD_BINDINGS_HELP = `Keyboard:
   Arrow keys           D-pad
@@ -578,6 +604,7 @@ export async function playtest(args) {
     // into its own port object; the agent's setInput is overwritten each
     // tick (matching prior behavior). Select+Start on any controller quits.
     let quit = false;
+    const isC64 = h.status?.platform === "c64";
     function readControllerInto(port, inst) {
       if (!inst) return;
       const btn = inst.buttons || {};
@@ -595,6 +622,18 @@ export async function playtest(args) {
       else if (lx < -STICK_DEADZONE) port.left = true;
       if (ly > STICK_DEADZONE) port.down = true;
       else if (ly < -STICK_DEADZONE) port.up = true;
+      // C64: the RIGHT stick selects the function keys (F1/F3/F5/F7) — the
+      // Batocera/RetroDeck convention so a controller alone reaches the keyboard
+      // keys C64 setup screens need. Emitted as virtual buttons the host's C64
+      // layer maps to the key matrix; harmless on other platforms (no mapping).
+      if (isC64) {
+        const rx = axes.rightStickX ?? 0;
+        const ry = axes.rightStickY ?? 0;
+        if (ry < -STICK_DEADZONE) port.c64_f1 = true;        // up    → F1
+        else if (ry > STICK_DEADZONE) port.c64_f7 = true;    // down  → F7
+        if (rx < -STICK_DEADZONE) port.c64_f3 = true;        // left  → F3
+        else if (rx > STICK_DEADZONE) port.c64_f5 = true;    // right → F5
+      }
     }
 
     const port0 = {};
@@ -619,6 +658,15 @@ export async function playtest(args) {
       for (const [keyName, bit] of Object.entries(KEY_TO_LIBRETRO_BIT)) {
         if (heldKeys.has(keyName)) port0[bitToName(bit)] = true;
       }
+      // C64 keyboard fallback (no controller / mixing): map PC keys to the C64
+      // KEYBOARD keys games need — the host's C64 layer routes these virtual
+      // button names to the key matrix. (Arrows + Z=Fire already give the
+      // joystick above.) The agent relays these to the human.
+      if (isC64) {
+        for (const [keyName, vbtn] of Object.entries(C64_KEYBOARD_FALLBACK)) {
+          if (heldKeys.has(keyName)) port0[vbtn] = true;
+        }
+      }
       const isRewinding = heldKeys.has("r") && rewindBuffer.length > 0;
       if (isRewinding) {
         // Restore the previous snapshot and run one frame to produce its visual.

package/examples/msx/catch_game/_verify.mjs

@@ -1,93 +0,0 @@
-import { readFileSync, writeFileSync } from "node:fs";
-import { buildForPlatform } from "/home/monteslu/code/cliemu/romdev/packages/romdev/src/toolchains/index.js";
-import { resolveCore } from "/home/monteslu/code/cliemu/romdev/packages/romdev/src/cores/registry.js";
-import { LibretroHost } from "/home/monteslu/code/cliemu/romdev/packages/romdev/src/host/LibretroHost.js";
-
-const LIBDIR = "/home/monteslu/code/cliemu/romdev/packages/romdev/src/platforms/msx/lib/c";
-const DIR = "/home/monteslu/code/cliemu/romdev/packages/romdev/examples/msx/catch_game";
-
-const SRC  = readFileSync(`${DIR}/main.c`, "utf8");
-const LIB  = readFileSync(`${LIBDIR}/msx_vdp.c`, "utf8");
-const CRT0 = readFileSync(`${LIBDIR}/msx_crt0.s`, "utf8");
-const HDR  = readFileSync(`${LIBDIR}/msx_hw.h`, "utf8");
-
-const PLATFORM = "msx";
-
-console.log("== building ==");
-const build = await buildForPlatform({
-  platform: PLATFORM,
-  sources: { "main.c": SRC, "msx_vdp.c": LIB, "msx_crt0.s": CRT0 },
-  includes: { "msx_hw.h": HDR },
-  crt0: ".module empty\n",
-  sourceName: "main.c",
-});
-
-if (!build.binary) {
-  console.log(build.log || build.stderr || JSON.stringify(build));
-  console.log("BUILD FAILED stage=", build.stage, "exit=", build.exitCode);
-  process.exit(1);
-}
-console.log("build OK, bytes=", build.binary.length);
-
-const c = resolveCore(PLATFORM);
-const h = new LibretroHost();
-await h.loadCore(c.jsPath, c.wasmPath);
-await h.loadMedia({ platform: PLATFORM, bytes: build.binary });
-
-// ---- honest pixel helpers over raw RGBA ----
-function nonBlackFraction(rgba) {
-  let nb = 0;
-  for (let i = 0; i < rgba.length; i += 4) {
-    if (rgba[i] > 16 || rgba[i + 1] > 16 || rgba[i + 2] > 16) nb++;
-  }
-  return nb / (rgba.length / 4);
-}
-// Find the brightest-pixel X centroid in a horizontal band of rows (the basket
-// rides near the bottom; the basket sprite is white). Returns -1 if no bright px.
-function brightCentroidX(frame, y0, y1) {
-  const { width, height, rgba } = frame;
-  let sx = 0, n = 0;
-  for (let y = y0; y < Math.min(y1, height); y++) {
-    for (let x = 0; x < width; x++) {
-      const i = (y * width + x) * 4;
-      // white basket: all channels high
-      if (rgba[i] > 180 && rgba[i + 1] > 180 && rgba[i + 2] > 180) { sx += x; n++; }
-    }
-  }
-  return n ? sx / n : -1;
-}
-
-// boot past the C-BIOS logo + a few game frames
-for (let i = 0; i < 320; i++) h.stepFrames(1);
-
-const sa = h.screenshotRgba();
-writeFileSync(`${DIR}/shot_before.png`, Buffer.from(h.screenshot().pngBase64, "base64"));
-// basket band: BASKET_Y=160 in a 192-tall internal buffer; band 150..180
-const fracA = nonBlackFraction(sa.rgba);
-const basketA = brightCentroidX(sa, Math.floor(sa.height * 0.78), Math.floor(sa.height * 0.95));
-console.log(`before: ${sa.width}x${sa.height} nonBlack=${(fracA*100).toFixed(2)}% basketX=${basketA.toFixed(1)}`);
-
-// Drive RIGHT for many frames
-for (let i = 0; i < 120; i++) { h.setInput({ ports: [{ right: true }] }); h.stepFrames(1); }
-const sb = h.screenshotRgba();
-writeFileSync(`${DIR}/shot_after_right.png`, Buffer.from(h.screenshot().pngBase64, "base64"));
-const basketB = brightCentroidX(sb, Math.floor(sb.height * 0.78), Math.floor(sb.height * 0.95));
-console.log(`after RIGHT: basketX=${basketB.toFixed(1)}`);
-
-// Drive LEFT for many frames
-for (let i = 0; i < 200; i++) { h.setInput({ ports: [{ left: true }] }); h.stepFrames(1); }
-const sc = h.screenshotRgba();
-writeFileSync(`${DIR}/shot_after_left.png`, Buffer.from(h.screenshot().pngBase64, "base64"));
-const basketC = brightCentroidX(sc, Math.floor(sc.height * 0.78), Math.floor(sc.height * 0.95));
-console.log(`after LEFT: basketX=${basketC.toFixed(1)}`);
-
-// ---- verdict ----
-const visible = fracA > 0.005;            // playfield is not black
-const movedRight = basketB > basketA + 5; // basket moved right with input
-const movedLeft  = basketC < basketB - 5; // basket moved back left
-console.log("VISIBLE:", visible, "MOVED_RIGHT:", movedRight, "MOVED_LEFT:", movedLeft);
-if (visible && movedRight && movedLeft) {
-  console.log("VERIFIED_OK");
-} else {
-  console.log("VERIFY_INCOMPLETE");
-}

package/examples/pce/catch_game/_verify.mjs

@@ -1,75 +0,0 @@
-import fs from "node:fs";
-import { buildForPlatform } from "/home/monteslu/code/cliemu/romdev/packages/romdev/src/toolchains/index.js";
-import { resolveCore } from "/home/monteslu/code/cliemu/romdev/packages/romdev/src/cores/registry.js";
-import { LibretroHost } from "/home/monteslu/code/cliemu/romdev/packages/romdev/src/host/LibretroHost.js";
-
-const LIB = "/home/monteslu/code/cliemu/romdev/packages/romdev/src/platforms/pce/lib/c";
-const DIR = "/home/monteslu/code/cliemu/romdev/packages/romdev/examples/pce/catch_game";
-
-const read = (p) => fs.readFileSync(p, "utf8");
-
-const sources = {
-  "main.c": read(DIR + "/main.c"),
-  "pce_video.c": read(LIB + "/pce_video.c"),
-  "pce_input.c": read(LIB + "/pce_input.c"),
-  "pce_sound.c": read(LIB + "/pce_sound.c"),
-};
-const headers = { "pce_hw.h": read(LIB + "/pce_hw.h") };
-
-console.log("Building catch_game...");
-const build = await buildForPlatform({
-  platform: "pce",
-  sources,
-  headers,
-  includes: headers,
-  sourceName: "main.c",
-});
-
-if (!build || !build.binary) {
-  console.log("BUILD FAILED");
-  console.log(JSON.stringify(build, null, 2));
-  process.exit(1);
-}
-console.log("BUILD OK, binary bytes =", build.binary.length);
-if (build.log) console.log("log tail:", String(build.log).slice(-400));
-
-const PLATFORM = "pce";
-const h = new LibretroHost();
-const c = resolveCore(PLATFORM);
-await h.loadCore(c.jsPath, c.wasmPath);
-await h.loadMedia({ platform: PLATFORM, bytes: build.binary });
-
-// boot
-for (let i = 0; i < 120; i++) h.stepFrames(1);
-
-function nonBlack(shot) {
-  const buf = Buffer.from(shot.pngBase64, "base64");
-  // crude: count distinct-ish bytes; rely on file size + later pixel scan
-  return buf.length;
-}
-
-// screenshot BEFORE input
-let shotA = h.screenshot();
-fs.writeFileSync(DIR + "/shot_before.png", Buffer.from(shotA.pngBase64, "base64"));
-console.log("before:", shotA.width, "x", shotA.height, "png bytes", nonBlack(shotA));
-
-// drive RIGHT for ~60 frames to move catcher and let fruit fall/catch
-for (let i = 0; i < 90; i++) {
-  h.setInput({ ports: [{ right: true }] });
-  h.stepFrames(1);
-}
-// then LEFT for a bit
-for (let i = 0; i < 60; i++) {
-  h.setInput({ ports: [{ left: true }] });
-  h.stepFrames(1);
-}
-
-let shotB = h.screenshot();
-fs.writeFileSync(DIR + "/shot_after.png", Buffer.from(shotB.pngBase64, "base64"));
-console.log("after:", shotB.width, "x", shotB.height, "png bytes", nonBlack(shotB));
-
-// pixel diff: decode both PNGs to raw via the host's framebuffer if available
-const same = shotA.pngBase64 === shotB.pngBase64;
-console.log("identical PNG?", same);
-
-console.log("done — see shot_before.png / shot_after.png");

package/src/mcp/tool-manifest.js

@@ -1,92 +0,0 @@
-// Tool manifest — the SINGLE SOURCE OF TRUTH for the consolidated tool surface.
-//
-// The 132→34 consolidation (see internal CONSOLIDATION_PLAN) merges narrow tools
-// into domain tools with a typed operation axis. This manifest records, for each
-// consolidated tool, the OLD tools it absorbs and the axis it routes on — so:
-//   1. a coverage-gate test can assert every old tool name maps to exactly one
-//      new tool (no capability silently dropped, no dupe);
-//   2. a tool-count budget test can fail the build if the surface regrows;
-//   3. docs + the rename map for downstream agents derive from one place.
-//
-// GOVERNANCE: a new capability is a new PARAMETER/op-value on an existing tool by
-// default — NOT a new top-level tool. Adding an entry here is a deliberate act the
-// budget test surfaces at PR time.
-//
-// Each MERGE_MAP entry: newTool → { absorbs:[...oldNames], axis:'op'|'as'|... }.
-// `absorbs: []` + `unchanged:true` means the tool kept its name (no merge).
-// This map grows one domain at a time as each consolidated tool lands.
-
-export const MERGE_MAP = {
-  // ── files (generic disk I/O) ──
-  files: { absorbs: ["writeAsset", "readAsset", "listAssets"], axis: "op" },
-  // ── cheats (DB lookup/search + apply/clear + make) ──
-  cheats: { absorbs: ["gameCheats", "searchCheats", "applyCheat", "clearCheats", "makeCheat"], axis: "op" },
-  // ── text (custom-font learn/encode/find for romhacking) ──
-  text: { absorbs: ["learnFontMap", "encodeTextForRom", "findEncodedText"], axis: "op" },
-  // ── symbols (name↔addr, memory map, PC→symbol). buildSourceWithDebug stays for `build`. ──
-  symbols: { absorbs: ["resolveSymbol", "lookupAddress", "getMemoryMap", "listSymbols", "addressToSymbol"], axis: "op" },
-  // ── disasm (raw bytes / ROM / project / references) ──
-  disasm: { absorbs: ["disassemble", "disassembleRom", "disassembleProject", "findReferences"], axis: "target" },
-  // ── state (save/load/list/export/dump/diff; diffState moved here from memory.js) ──
-  state: { absorbs: ["saveState", "loadState", "listStates", "exportState", "dumpState", "diffState"], axis: "op" },
-  // ── input (set/press/sequence/navigate/layout; getInputLayout folded in) ──
-  input: { absorbs: ["setInput", "pressButton", "inputSequence", "navigate", "getInputLayout"], axis: "op" },
-  // ── platform (list/resolve/toolchains/docs/doc; spans platforms.js+platform-docs.js+toolchain.js) ──
-  platform: { absorbs: ["listPlatforms", "resolvePlatform", "listToolchains", "installToolchain", "listPlatformDocs", "getPlatformDoc"], axis: "op" },
-  // ── host (unload/shutdown/reset/pause/resume FSM; loadMedia + getStatus stay separate) ──
-  host: { absorbs: ["unloadMedia", "shutdown", "reset", "pause", "resume"], axis: "op" },
-  // ── frame (step/screenshot/stepAndShot/stepInstruction; stepInstruction folded from watch-memory.js) ──
-  frame: { absorbs: ["stepFrames", "screenshot", "stepAndScreenshot", "stepInstruction"], axis: "op" },
-  // ── scaffold (project/game + snippets; patchGbHeader folded into romPatch op:'gbHeader') ──
-  scaffold: { absorbs: ["createProject", "createGame", "starterSnippets", "copyStarterSnippets"], axis: "op" },
-  // ── cart (identify/extract/wrap; identifyRom from rom-id.js, rest from cart-parts.js) ──
-  cart: { absorbs: ["identifyRom", "extractCart", "wrapRomFromParts"], axis: "op" },
-  // ── palette (live/platformMaster/lospec; spans platform-tools.js + lospec.js) ──
-  palette: { absorbs: ["inspectPalette", "getPlatformPalettePng", "getLospecPalette"], axis: "source" },
-  // ── audioDebug (inspect/record; getAudioState from platform-tools.js, recordAudio from audio.js; pcmToBrr/wavToXgm2Pcm stay) ──
-  audioDebug: { absorbs: ["getAudioState", "recordAudio"], axis: "op" },
-  // ── sprites (inspect OAM + meta-sprite pipeline; inspectSprites from platform-tools.js, rest from metasprite-tools.js; validateGenesisTiles stays for encodeArt) ──
-  sprites: { absorbs: ["inspectSprites", "groupVisibleSprites", "previewVisibleSprites", "captureMetaSprite", "renderMetaSpritePreview", "emitMetaSpriteRenderer", "extractSpriteFromScreenshot"], axis: "op" },
-  // ── background (tilemap/render-state; inspectBackgroundMap from platform-tools.js, getRenderingContext from rendering-context.js, whichTilesAreRendered from which-tiles.js) ──
-  background: { absorbs: ["inspectBackgroundMap", "getRenderingContext", "whichTilesAreRendered"], axis: "view" },
-  // ── tiles (decode/render tile bytes; inspectPatternTiles from platform-tools.js, getTile/tileFingerprints/tilesAscii from tile-inspect.js, extractSpriteSheet from rom-id.js, previewTileArt from preview-tile.js) ──
-  tiles: { absorbs: ["inspectPatternTiles", "getTile", "tileFingerprints", "tilesAscii", "extractSpriteSheet", "previewTileArt"], axis: "op" },
-  // ── encodeArt (PNG→native art; convertImageToTiles+imageToTilemap from platform-tools.js, quantizePngForPlatform+cropSpriteSheet from sprite-pipeline.js, validateGenesisTiles from metasprite-tools.js) ──
-  encodeArt: { absorbs: ["convertImageToTiles", "imageToTilemap", "quantizePngForPlatform", "cropSpriteSheet", "validateGenesisTiles"], axis: "stage" },
-  // ── importArt (editor-file/ROM → native tiles; load* from art-loaders.js, crossPlatformSpriteImport from sprite-pipeline.js as from:'rom') ──
-  importArt: { absorbs: ["loadAsepriteSheet", "loadGifAnimation", "loadSpriteSheet", "loadTilemap", "crossPlatformSpriteImport"], axis: "from" },
-  // ── memory (read/write/search; all 8 from memory.js) ──
-  memory: { absorbs: ["readMemory", "writeMemory", "readCartRom", "snapshotMemory", "diffMemory", "classifyRegion", "searchValue", "searchNext"], axis: "op" },
-  // ── cpu (read/drive; getCPUState from platform-tools.js, setRegister/callSubroutine/decompressWith from watch-memory.js) ──
-  cpu: { absorbs: ["getCPUState", "setRegister", "callSubroutine", "decompressWith"], axis: "op" },
-  // ── breakpoint (STOP-on-first; all 4 from watch-memory.js) ──
-  breakpoint: { absorbs: ["findWriter", "runUntilWrite", "runUntilPC", "runUntilRead"], axis: "on" },
-  // ── watch (LOG-ALL; watchMemory/watchRange/logPCRange + Genesis VDP-DMA trace
-  //    on:'dma' from watchDma/traceVramSource — all from watch-memory.js +
-  //    trace-vram-source.js. dmaTrace was folded in as watch({on:'dma'}).) ──
-  watch: { absorbs: ["watchMemory", "watchRange", "logPCRange", "watchDma", "traceVramSource"], axis: "on" },
-  // ── build (compile/run; buildSource/buildProject/runSource from toolchain.js, buildSourceWithDebug from symbols.js). ENTRY-TIER. ──
-  build: { absorbs: ["buildSource", "buildSourceWithDebug", "buildProject", "runSource"], axis: "output" },
-  // ── romPatch (9-op ROM-hack toolkit; patchFile/patchRom from rom-id.js, spliceCHR from splice-chr.js, relocateBlock/makeStoredBlock/findPointerTo from reinject.js, findFreeSpace from free-space.js, diffRoms from diff-roms.js, patchGbHeader as op:'gbHeader') ──
-  romPatch: { absorbs: ["patchFile", "patchRom", "spliceCHR", "relocateBlock", "makeStoredBlock", "findFreeSpace", "findPointerTo", "diffRoms", "patchGbHeader"], axis: "op" },
-  // ── catalog (orient; listCategories + getStatus, both entry-tier in index.js) ──
-  catalog: { absorbs: ["listCategories", "getStatus"], axis: "op" },
-  // ── playtest (show-a-human window FSM; all 4 from playtest.js). ENTRY-TIER. ──
-  playtest: { absorbs: ["playtestStop", "playtestStatus", "playtestFramebuffer"], axis: "op" },
-  // ── encodeAudio (external clip → native sample format; pcmToBrr + wavToXgm2Pcm from audio.js) ──
-  encodeAudio: { absorbs: ["pcmToBrr", "wavToXgm2Pcm"], axis: "target" },
-};
-
-/** Every OLD tool name that the consolidation removes (absorbed into a new tool). */
-export function absorbedToolNames() {
-  const names = [];
-  for (const entry of Object.values(MERGE_MAP)) {
-    if (entry.absorbs) names.push(...entry.absorbs);
-  }
-  return names;
-}
-
-/** The consolidated (new) tool names this manifest defines. */
-export function consolidatedToolNames() {
-  return Object.keys(MERGE_MAP);
-}