romdevtools 0.22.1 → 0.24.0

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/sms/lib/c/sms_crt0.s

@@ -22,6 +22,8 @@
         .globl  l__INITIALIZER
         .globl  s__INITIALIZER
         .globl  s__INITIALIZED
+        .globl  s__DATA
+        .globl  l__DATA
 
 ;; ─── Reset vector at $0000 ────────────────────────────────────────
         .area _HEADER (ABS)
@@ -72,7 +74,19 @@
 ;; call main. The initializer area is filled by sdcc when it sees
 ;; global initializations.
 
+        ;; AREA ORDERING IS LOad-BEARING. `_INITIALIZER` (the ROM image of
+        ;; every value-initialised `static` global) MUST be declared in the
+        ;; ROM group here — BEFORE the `_DATA` RAM block. If it isn't, sdld
+        ;; places `_INITIALIZER` in RAM right after `_INITIALIZED`, so the
+        ;; gsinit copy below copies uninitialised RAM onto itself and every
+        ;; `static uint8_t x = 5;` boots as 0. (Bug found 2026-06-08: a GBC
+        ;; Columns agent's `static uint32_t rng = 0x1357;` booted as 0, so
+        ;; the xorshift PRNG stayed 0 and every "random" roll came out the
+        ;; same — a "monochrome RNG" that looked like an SDCC codegen bug
+        ;; but was really this missing ROM placement. The sm83 GB crt0 has
+        ;; always placed _INITIALIZER in ROM; the z80 crt0s never did.)
         .area   _HOME
+        .area   _INITIALIZER
         .area   _CODE
         .area   _GSINIT
         .area   _GSFINAL
@@ -86,6 +100,32 @@
         .area   _CODE
 
 gsinit:
+        ;; ── Zero the BSS segment (`_DATA`). ──────────────────────────
+        ;; Every uninitialised `static` global lands in `_DATA` and MUST
+        ;; read back 0 at boot. Without this, `static uint8_t flag;` boots
+        ;; with whatever power-on WRAM byte was there (gambatte/gpgx leave
+        ;; garbage), and `if (flag)` spuriously fires. Mirrors the sm83 GB
+        ;; crt0's gsinit_data loop.
+        ld      bc, #l__DATA
+        ld      a, b
+        or      a, c
+        jr      Z, gsinit_bss_done
+        ld      hl, #s__DATA
+        ld      (hl), #0x00
+        ld      d, h
+        ld      e, l
+        inc     de
+        dec     bc
+        ld      a, b
+        or      a, c
+        jr      Z, gsinit_bss_done
+        ldir                            ; propagate the 0 across _DATA
+gsinit_bss_done:
+
+        ;; ── Copy `_INITIALIZER` (ROM) → `_INITIALIZED` (RAM). ────────
+        ;; The value-initialised-statics path: `static uint8_t lives = 3;`
+        ;; lives in _INITIALIZED at runtime; its initial value sits in
+        ;; _INITIALIZER in ROM (now correctly ROM-placed, see above).
         ld      bc, #l__INITIALIZER
         ld      a, b
         or      a, c

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/src/toolchains/sdcc/preflight-lint.js

@@ -152,12 +152,29 @@ export function lintSdccSource(source, file = "main.c", opts = {}) {
   }
 
   // ─── __xdata / VRAM byte-copy miscompile ────────────────────────
-  // SDCC sm83 miscompiles `for (i...) dst[i] = src[i];` when dst is an
+  // SDCC sm83 miscompiles `for (i...) dst[i] = src[i];` ONLY when dst is an
   // __xdata pointer (e.g. into VRAM $8000) — it writes through the return
-  // address and crashes the CPU. Hard to prove the pointer target
-  // statically, so flag the SHAPE (an array-index copy `a[i] = b[i];`
-  // inside a for-loop) as ADVISORY, pointing at memcpy_vram. Conservative:
-  // require a for-loop on the line/just above + an indexed-to-indexed copy.
+  // address and crashes the CPU. A plain WRAM array copy (`static uint8_t
+  // rb[78]; ... rb[i]=grid[i];`) is perfectly fine. The old lint flagged the
+  // SHAPE unconditionally as a "warning" — every WRAM copy in every genre
+  // scaffold cried wolf, training agents to distrust the linter. We now
+  // classify the DESTINATION identifier before deciding the severity:
+  //
+  //   • PROVABLY VRAM/__xdata  → "warning" (the real crash-class footgun)
+  //       - dst is declared as a POINTER (`type *dst`) — only pointers can
+  //         alias __xdata; an indexed write through one is the bug.
+  //       - dst is a known-VRAM name (vram*, VRAM, *vram*, bgmap, _VRAM*).
+  //       - dst is assigned from a cast/literal in $8000-$9FFF anywhere in
+  //         the source (e.g. `dst = (uint8_t*)0x9800;`).
+  //   • PLAIN RAM ARRAY        → SUPPRESS (declared `type dst[N];` here).
+  //   • UNKNOWN (bare ident,   → "info" — visible, not scary. Better to
+  //     no decl in this TU)      occasionally downgrade a real VRAM case to
+  //                              info than to keep crying wolf on WRAM.
+  //
+  // The crash cases that MATTER (the documented memcpy_vram footgun) are
+  // pointer-to-VRAM, which the "provably VRAM" path still catches as a
+  // warning.
+  const dstClass = classifyCopyDest(lines);
   for (let i = 0; i < lines.length; i++) {
     const code = lines[i].replace(/\/\/.*$/, "").replace(/\/\*.*?\*\//g, "");
     // indexed-to-indexed copy: ident[idx] = ident[idx];  (same index token)
@@ -168,17 +185,72 @@ export function lintSdccSource(source, file = "main.c", opts = {}) {
     // Require a for-loop driving this copy (this line or the 2 above).
     const ctx = (lines[i] + "\n" + (lines[i - 1] || "") + "\n" + (lines[i - 2] || ""));
     if (!/\bfor\s*\(/.test(ctx)) continue;
+    const dst = cp[1];
+    // A VRAM-suggestive NAME promotes an otherwise-unknown dest to VRAM even
+    // with no decl in this TU (e.g. `vram_buf[i] = tiles[i];`). A declared
+    // plain array still wins as "array" (suppress) — names rarely collide.
+    const klass = dstClass.get(dst) || (isVramName(dst) ? "vram" : "unknown");
+    if (klass === "array") continue; // plain WRAM array — provably safe, suppress
+    const isVram = klass === "vram";
     issues.push({
-      severity: "warning",
+      // Provably-VRAM → warning (the crash-class footgun). Unknown bare
+      // pointer → info (visible, not "your code is broken"). Never critical:
+      // even the VRAM case only miscompiles, it isn't an unconditional hang.
+      severity: isVram ? "warning" : "info",
       file,
       line: i + 1,
       stage: "lint",
-      message: `byte-copy loop \`${cp[1]}[${idx1}] = ${cp[3]}[${idx2}]\` — miscompiles if the destination is VRAM/__xdata`,
-      details: `${portLabel} miscompiles this pattern when '${cp[1]}' points into VRAM ($8000-$9FFF) or another __xdata region — it writes through the return address and crashes the CPU (PC near $002B, sprites/tiles never show). If '${cp[1]}' is a VRAM/__xdata pointer, use \`memcpy_vram(${cp[1]}, ${cp[3]}, n)\` (in gb_runtime.c) instead. Ignore if '${cp[1]}' is plain WRAM/an array. See GB TROUBLESHOOTING § the #1 SDCC footgun.`,
+      message: isVram
+        ? `byte-copy loop \`${dst}[${idx1}] = ${cp[3]}[${idx2}]\` into VRAM/__xdata — ${portLabel} miscompiles this`
+        : `byte-copy loop \`${dst}[${idx1}] = ${cp[3]}[${idx2}]\` — safe for WRAM arrays, but miscompiles if '${dst}' points into VRAM/__xdata`,
+      details: isVram
+        ? `${portLabel} miscompiles this pattern when '${dst}' points into VRAM ($8000-$9FFF) or another __xdata region — it writes through the return address and crashes the CPU (PC near $002B, sprites/tiles never show). Use \`memcpy_vram(${dst}, ${cp[3]}, n)\` (in gb_runtime.c) instead. See GB TROUBLESHOOTING § the #1 SDCC footgun.`
+        : `If '${dst}' is a plain WRAM array (\`type ${dst}[N];\`) this is FINE — ignore. ${portLabel} only miscompiles it when '${dst}' is a pointer into VRAM ($8000-$9FFF)/__xdata, where it writes through the return address and crashes the CPU. If '${dst}' is a VRAM pointer, use \`memcpy_vram(${dst}, ${cp[3]}, n)\` instead. See GB TROUBLESHOOTING § the #1 SDCC footgun.`,
       ref: "xdata-copy-miscompile",
     });
   }
 
+  // ─── hardcoded $C000-area WRAM pointer overlaps the C statics ───
+  // SDCC links `_DATA`/`_INITIALIZED` (value-init statics) + `_BSS` (zero-init
+  // statics) at the BOTTOM of WRAM starting $C000. A program that ALSO pokes a
+  // hardcoded pointer into that low range (e.g. `(uint8_t*)0xC000`) scribbles
+  // over its own statics — the seed of a PRNG, a collision grid, the score —
+  // and the symptom looks EXACTLY like an SDCC codegen bug (a 32-bit xorshift
+  // that "degenerates" because its seed got clobbered, never a real
+  // miscompile). This was the real root cause behind a GBC Columns agent's
+  // "monochrome RNG" report (2026-06-08); the math itself compiles correctly.
+  //
+  // ONLY for the sm83/z80 GB/SMS-family, whose WRAM base is $C000. Flag the
+  // low 256 bytes ($C000-$C0FF) where _DATA/_INITIALIZED live (small projects'
+  // statics sit here; $C100 is shadow_oam; $C200+ is the documented-safe
+  // scratch floor). INFO severity — visible, not "your code is broken": a
+  // hardcoded low pointer is occasionally legitimate (e.g. you've checked the
+  // map). NEVER critical.
+  if (port === "sm83" || port === "z80") {
+    // pointer cast/decl/assignment to a $C0xx literal: `(uint8_t*)0xC000`,
+    // `uint8_t *p = (uint8_t*)0xc010;`, `p = 0xC0FF;`
+    const ptrLit = /\(\s*(?:volatile\s+|const\s+|unsigned\s+|signed\s+)*[A-Za-z_]\w*\s*\*+\s*\)\s*0x(C0[0-9a-fA-F]{2})\b/;
+    const seen = new Set();
+    for (let i = 0; i < lines.length; i++) {
+      const code = lines[i].replace(/\/\/.*$/, "").replace(/\/\*.*?\*\//g, "");
+      const m = code.match(ptrLit);
+      if (!m) continue;
+      const addr = parseInt(m[1], 16); // already the full $C0xx address
+      const key = i + ":" + addr;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      issues.push({
+        severity: "info",
+        file,
+        line: i + 1,
+        stage: "lint",
+        message: `hardcoded WRAM pointer $${addr.toString(16).toUpperCase()} overlaps the C static-data segment ($C000-)`,
+        details: `${portLabel} links your value- and zero-initialised \`static\` globals (PRNG seeds, grids, scores) at the BOTTOM of WRAM from $C000. A hardcoded pointer into $C000-$C0FF can scribble over them — the classic symptom is a PRNG/array that looks "miscompiled" (e.g. an xorshift whose seed got clobbered so every roll is identical) when the math is actually fine. Prefer a \`static\` array and let the linker place it; if you must hardcode, use $C200+ and verify with the linker map (build with includeSymbols:true → check s__DATA/s__BSS). $C100 is shadow_oam. See ${port === "sm83" ? "GB/GBC" : "SMS/GG"} SDCC_GOTCHAS.md § "sm83 codegen traps in plain game logic".`,
+        ref: "wram-static-overlap",
+      });
+    }
+  }
+
   // Mid-block declarations (rough heuristic — flags any `type name [=...] ;`
   // that appears after a non-decl, non-blank statement at deeper indent
   // than the function opening brace).
@@ -206,6 +278,90 @@ export function lintSources(sources, opts = {}) {
 
 // ─── helpers ───────────────────────────────────────────────────────
 
+/**
+ * Known-VRAM symbol names (GB/GBC/SMS conventions). Case-insensitive;
+ * substring "vram" matches vram_ptr / pVRAM / VRAMbase, plus the common
+ * GB BG-map / tile-data symbols. A dest with such a name is treated as a
+ * VRAM pointer even with no visible declaration.
+ * @param {string} n
+ * @returns {boolean}
+ */
+function isVramName(n) {
+  return /vram/i.test(n) || /^(?:bgmap|tilemap|tiledata|chrram|_VRAM)/i.test(n);
+}
+
+/**
+ * Classify each identifier that is the destination of a copy loop into one
+ * of: "vram" (provably a VRAM/__xdata pointer → real crash-class footgun),
+ * "array" (declared as a plain `type name[N];` RAM array → provably safe,
+ * suppress the warning), or absent (unknown — caller treats as "info").
+ *
+ * This is a whole-TU pass: a name is classified by scanning the ENTIRE
+ * source, so a `uint8_t *dst;` decl far above the loop, or a later
+ * `dst = (uint8_t*)0x9800;` assignment, still classifies it as VRAM.
+ *
+ * Precedence: VRAM wins over array (a name that is BOTH a pointer and,
+ * say, shadowed by an array elsewhere should still be treated as the
+ * dangerous case — but in practice a single name is one or the other).
+ *
+ * @param {string[]} lines  source split into lines
+ * @returns {Map<string,"vram"|"array">}
+ */
+function classifyCopyDest(lines) {
+  /** @type {Map<string,"vram"|"array">} */
+  const klass = new Map();
+  const setVram  = (n) => { klass.set(n, "vram"); };
+  const setArray = (n) => { if (klass.get(n) !== "vram") klass.set(n, "array"); };
+
+  // A literal/cast value lands in VRAM if it's 0x8000–0x9FFF.
+  const inVramRange = (hexOrDec) => {
+    const v = /^0x/i.test(hexOrDec) ? parseInt(hexOrDec, 16) : parseInt(hexOrDec, 10);
+    return Number.isFinite(v) && v >= 0x8000 && v <= 0x9fff;
+  };
+  // Type keywords that introduce a declaration (subset is fine — we only
+  // need to tell "pointer decl" from "array decl").
+  const TYPE = "(?:unsigned\\s+|signed\\s+)?(?:char|short|int|long|void|u?int(?:8|16|32|64)_t|u8|u16|u32|u64|uint8|uint16|uint32|uint64|int8|int16|int32|int64|size_t|[A-Z][A-Za-z0-9_]*_t)";
+  const QUAL = "(?:static\\s+|const\\s+|register\\s+|volatile\\s+|extern\\s+|auto\\s+|__xdata\\s+|__at\\s*\\([^)]*\\)\\s*)*";
+  // Pointer declaration: `<quals> <type> * name`  (one or more `*`).
+  const ptrDeclRe   = new RegExp(`\\b${QUAL}${TYPE}\\s*\\*+\\s*([A-Za-z_]\\w*)`, "g");
+  // Array declaration:   `<quals> <type> name[ ... ]`  (NOT a pointer).
+  const arrDeclRe   = new RegExp(`\\b${QUAL}${TYPE}\\s+([A-Za-z_]\\w*)\\s*\\[`, "g");
+  // Pointer assigned a VRAM literal/cast:  name = (cast?) 0x8xxx/0x9xxx
+  // e.g.  dst = (uint8_t*)0x9800;   p = (void*)0x8000;   q = 0x8800;
+  const vramAssignRe = /\b([A-Za-z_]\w*)\s*=\s*(?:\([^)]*\)\s*)?(0x[0-9a-fA-F]+|\d{4,})\b/g;
+  // Pointer DECL with an inline VRAM initializer:
+  //   uint8_t *dst = (uint8_t*)0x8000;
+  const ptrInitVramRe = new RegExp(`\\b${QUAL}${TYPE}\\s*\\*+\\s*([A-Za-z_]\\w*)\\s*=\\s*(?:\\([^)]*\\)\\s*)?(0x[0-9a-fA-F]+|\\d{4,})`, "g");
+
+  for (let i = 0; i < lines.length; i++) {
+    const code = lines[i].replace(/\/\/.*$/, "").replace(/\/\*.*?\*\//g, "");
+
+    // 1) pointer decl with a VRAM-range initializer → VRAM (strongest).
+    ptrInitVramRe.lastIndex = 0;
+    for (let m; (m = ptrInitVramRe.exec(code)); ) {
+      if (inVramRange(m[2])) setVram(m[1]);
+    }
+    // 2) any name assigned a VRAM-range literal/cast → VRAM.
+    vramAssignRe.lastIndex = 0;
+    for (let m; (m = vramAssignRe.exec(code)); ) {
+      if (inVramRange(m[2])) setVram(m[1]);
+    }
+    // 3) pointer declarations → VRAM-candidate (only pointers can alias
+    //    __xdata; an indexed write through one is the documented bug).
+    ptrDeclRe.lastIndex = 0;
+    for (let m; (m = ptrDeclRe.exec(code)); ) setVram(m[1]);
+    // 4) plain array declarations → safe RAM array (unless already VRAM).
+    arrDeclRe.lastIndex = 0;
+    for (let m; (m = arrDeclRe.exec(code)); ) setArray(m[1]);
+  }
+
+  // 5) name-based VRAM override: any dest named like VRAM is VRAM even if
+  //    it was (mis)classified as an array by a same-named decl elsewhere.
+  for (const n of klass.keys()) if (isVramName(n)) setVram(n);
+
+  return klass;
+}
+
 /**
  * Detect mid-block variable declarations (C89 violation). Simple state
  * machine: track block depth + whether we've seen a non-decl statement

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");