romdevtools 0.41.0 → 0.42.0

package/CHANGELOG.md

@@ -4,6 +4,76 @@ All notable changes to `romdevtools`. Dates are release dates.
 (Published as `romdev-mcp` through 0.11.0; renamed to `romdevtools` in 0.13.0 —
 the `romdev-mcp` bin is kept as an alias.)
 
+## 0.42.0 — 2026-06-24
+
+### v0.41.0 feedback batch + the NES→SNES port engine
+
+A round driven by RE-session feedback (cheats, ergonomics, the human-playtest
+eviction case) plus the flagship port-engine work.
+
+#### Fixed — `cheats` raw RAM codes were inert
+
+`cheats({op:'make'})` for a sub-`$0100` RAM address emitted the short `32:09`
+form, which libretro cores PARSE but never bind — and `apply` then falsely
+reported `applied:true`. `encodeRaw` now pads the address to a binding width
+(`0032:09`); `apply` re-encodes a hand-typed short code too. Verified on fceumm.
+
+#### New — hex-string forms on address params
+
+A hex literal in a JSON arg (`address: 0xC06C`) was a hard parse error. All
+address-like params (`address`/`offset`/`pc`/`compare`/…) now accept the STRING
+forms `"0xC06C"` / `"$C06C"` / decimal strings, coerced before validation —
+centralized so every tool gets it.
+
+#### New — `catalog({op:'status'}).capabilities`
+
+A map of which debug ops the loaded core/toolchain implement (pcBreakpoint,
+watchpointExact, rangeWatch, cheats, da65Toolchain, …) so an agent picks a
+working trace strategy up front instead of probing by failure.
+
+#### New — `callStack` on breakpoint hits (13 of 14 platforms)
+
+`breakpoint({on:'pc'|'write'})` hits carry a decoded call stack: the server walks
+the stack from the captured stack pointer and returns each caller PC. Covers the
+6502 family (JSR-opcode validated), m68k (Genesis — 4-byte BE return), and Z80/
+SM83 (SMS/GG/MSX/GB/GBC — 2-byte LE return). GBA (ARM) is the lone exclusion: its
+calls return through the link register, not the stack.
+
+#### New — `references` finds inline jump-table / trampoline call sites
+
+When no `jsr/jmp/branch` names a CODE address (it's reached via a computed jump),
+`references` now scans the raw ROM for the address as a 16-bit pointer (LE/BE) and
+reports `tableHits`. Per-platform header skip (NES/SNES/7800/Lynx); the 6502
+RTS-trick `addr-1` form is scanned only on the 6502 family.
+
+#### New — `disasm({target:'pointerTable'})` (all mapped platforms)
+
+Static index→handler decode of a jump/pointer table: contiguous `dw`, SPLIT
+lo/hi arrays at two bases, the RTS-trick (`+1`), and a REVERSE lookup (handler →
+dispatch index). The static complement to the live `breakpoint({on:'jumptable'})`.
+Works on every platform with an address mapper (nes/snes/sms/gg/gb/gbc/2600/7800/
+c64/genesis); the endian default follows the CPU (Genesis/m68k → BE).
+
+#### New — playtest eviction survivability
+
+While a playtest window is open, romdev rolls a `.state` to disk every ~15s (and
+on F2), so a session eviction can't lose a human's manual progress — the recovery
+hint points at `state({op:'load', path})`. Surfaced in `playtest({op:'status'})`.
+
+#### Leaner schemas
+
+The last inline 62-value region enum in the watch/breakpoint tool schemas is now
+a runtime-validated string — the full enum lives once on `memory`'s `region`.
+
+#### Port engine — NES→SNES static recompile renders + plays
+
+`disasm({target:'recompile'})` now draws the original ROM's screen on SNES
+(`withShim`, phase-1 static — fixed the `cpx.w` upload bug) and animates sprites
++ runs the game's NMI each vblank (`withRuntime`, phase-2 live). The recompiler
+follows the real reset vector and anchors the entry to the routine's first
+instruction. (Plus the `frame` port-compare oracles: compareRam/compareRender/
+findDiverge/portStatus + side-by-side two-core capture.)
+
 ## 0.41.0 — 2026-06-12
 
 ### RE engine round — bank-aware decompile, live jumptable recovery, readable 6502 output

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 14 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
   "type": "module",
   "main": "src/mcp/server.js",
@@ -80,6 +80,8 @@
   "files": [
     "src",
     "!src/**/*.test.js",
+    "!src/cores/wasm/**",
+    "!src/toolchains/*/wasm/**",
     "examples",
     "AGENTS.md",
     "README.md",

package/src/analysis/analyze.js

@@ -12,7 +12,7 @@
 // resolved by the existing disasm mappers — analysis here is whole-file.
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { runRizin, runRizinJson, RIZIN_ARCH } from "./rizin.js";
+import { runRizinJson, RIZIN_ARCH } from "./rizin.js";
 import { decompileFunction, SLEIGH_LANGID } from "./decompile.js";
 import { registersForPlatform } from "../platforms/common/registers.js";
 

package/src/analysis/backtrace.js

@@ -0,0 +1,198 @@
+// Call-stack reconstruction from a CPU register snapshot + the stack RAM. Turns
+// "who called this routine?" from a captureMemory read + several lines of by-hand,
+// off-by-one-prone return-address pointer math into one decoded field on a
+// breakpoint hit. (v0.41.0 feedback note 005444 N1.)
+//
+// The ISA-specific part is the return-address convention. Phase 1 covers the
+// 6502 family (the dominant RE target); the structure generalizes to Z80 / SM83 /
+// m68k by adding a decoder. We DON'T claim a frame is real beyond what the raw
+// stack bytes say — a 6502 stack also holds saved registers and data pushes, so
+// each candidate is validated (the byte two-before the return target must be a
+// `jsr` opcode $20) and flagged `confident` accordingly. Unvalidated candidates
+// are still returned (some callers use jmp-based trampolines) but marked.
+//
+// Plain JS ESM + JSDoc.
+
+/** 6502 JSR opcode. A real call frame's return address points just past it. */
+const JSR_6502 = 0x20;
+
+/**
+ * Decode a 6502-family call stack from the stack page.
+ *
+ * 6502 stack model: page 1 ($0100-$01FF), SP points to the NEXT-FREE slot, so the
+ * topmost pushed byte is at $0100 + ((S + 1) & 0xFF). JSR pushes the return
+ * address (the address of its LAST operand byte = JSR_addr + 2) high byte first
+ * then low byte — so on the stack the low byte sits at the lower address. To
+ * recover the caller: read a little-endian word off the stack, subtract 2 (→ the
+ * JSR instruction), and confirm the byte there is $20.
+ *
+ * @param {number} sp                 the S register (0x00-0xFF)
+ * @param {Uint8Array} stackPage      the 256 bytes of $0100-$01FF
+ * @param {(cpuAddr:number)=>(number|null)} readByteAt  read one byte at a CPU
+ *   address (used to validate the $20 opcode); may return null if unmapped.
+ * @param {number} [maxDepth=8]
+ * @returns {Array<{ returnAddr:number, callerPc:number, confident:boolean }>}
+ */
+export function decode6502Backtrace(sp, stackPage, readByteAt, maxDepth = 8) {
+  const frames = [];
+  // Walk upward from the first occupied slot toward $01FF, reading LE words.
+  let idx = (sp + 1) & 0xff; // index into the page of the topmost pushed byte
+  while (frames.length < maxDepth && idx <= 0xfe) {
+    const lo = stackPage[idx];
+    const hi = stackPage[idx + 1];
+    if (lo == null || hi == null) break;
+    const returnAddr = (hi << 8) | lo;
+    const callerPc = (returnAddr - 2) & 0xffff;
+    let confident = false;
+    if (returnAddr >= 0x8000) {
+      // a plausible code return address; validate the JSR opcode if we can read it
+      const op = readByteAt ? readByteAt(callerPc) : null;
+      confident = op === JSR_6502;
+    }
+    if (confident) {
+      frames.push({ returnAddr, callerPc, confident });
+    } else if (returnAddr >= 0x8000 && frames.every((f) => !f.confident)) {
+      // keep plausible-but-unvalidated frames only while we haven't yet locked
+      // onto a confident call chain (some callers use jmp-trampolines, no $20).
+      frames.push({ returnAddr, callerPc, confident });
+    } else if (frames.some((f) => f.confident)) {
+      // we had a confident chain and hit a non-call word ($FF padding, saved
+      // data) → we've walked off the live frames. Stop cleanly.
+      break;
+    }
+    idx += 2;
+  }
+  // If any frame validated as a real JSR, drop trailing unconfident noise so the
+  // caller sees the trustworthy chain. Otherwise return the best-effort guesses.
+  const anyConfident = frames.some((f) => f.confident);
+  return anyConfident ? frames.filter((f) => f.confident) : frames;
+}
+
+/** Parse a hex register value that may carry a "$"/"0x" prefix → number, or NaN. */
+function regNum(v) {
+  return parseInt(String(v ?? "").replace(/^\$|^0x/i, ""), 16);
+}
+
+/**
+ * Decode a stack of 16-bit LE return addresses (Z80 `call` / SM83 `call`): the
+ * stack grows DOWN and SP points at the low byte of the topmost return address;
+ * each `call` pushed a 2-byte LE return = the address of the instruction AFTER
+ * the call. We can't cheaply recover the call instruction's own length (Z80 call
+ * is 3 bytes, but a computed jump-in differs), so callerPc IS the return address
+ * and we mark it `confident` when it lands in a plausible code range. SP-relative,
+ * so the caller supplies a word reader (handles the platform's RAM mapping).
+ *
+ * @param {number} sp
+ * @param {(cpuAddr:number)=>(number|null)} readWordLE  read a 16-bit LE word
+ * @param {number} [maxDepth=8]
+ * @param {number} [codeMin=0x0000]  return addresses below this are treated as data
+ */
+function decode16BitStack(sp, readWordLE, maxDepth = 8, codeMin = 0x0150) {
+  const frames = [];
+  let addr = sp & 0xffff;
+  for (let i = 0; i < maxDepth; i++) {
+    const ret = readWordLE(addr);
+    if (ret == null) break;
+    const confident = ret >= codeMin && ret <= 0xffff;
+    if (confident) {
+      frames.push({ returnAddr: ret, callerPc: ret, confident: true });
+    } else if (frames.every((f) => !f.confident)) {
+      frames.push({ returnAddr: ret, callerPc: ret, confident: false });
+    } else {
+      break; // had a confident chain, hit a non-code word → off the frames
+    }
+    addr = (addr + 2) & 0xffff;
+  }
+  const anyConfident = frames.some((f) => f.confident);
+  return anyConfident ? frames.filter((f) => f.confident) : frames;
+}
+
+/**
+ * Decode an m68k call stack. `jsr`/`bsr` push a 4-byte (longword) return address;
+ * the stack grows down and A7 (SP) points at the topmost return longword (stored
+ * big-endian). The return address is the instruction AFTER the jsr/bsr; we report
+ * it as callerPc (recovering the call's own length needs a disasm pass). Genesis
+ * RAM is $FF0000-$FFFFFF (mirrored), so SP is a 24-bit bus address.
+ *
+ * @param {number} sp
+ * @param {(cpuAddr:number)=>(number|null)} readLongBE  read a 32-bit BE longword
+ * @param {number} [maxDepth=8]
+ */
+function decodeM68kStack(sp, readLongBE, maxDepth = 8) {
+  const frames = [];
+  let addr = sp >>> 0;
+  for (let i = 0; i < maxDepth; i++) {
+    const ret = readLongBE(addr);
+    if (ret == null) break;
+    // Plausible m68k code address: even, inside the 24-bit address space, and not
+    // obviously garbage ($00000000 / $FFFFFFFF). ROM is $000000+; RAM is $FF0000+.
+    const a = ret & 0xffffff;
+    const confident = (a & 1) === 0 && a !== 0 && a !== 0xffffff && a < 0x1000000;
+    if (confident) {
+      frames.push({ returnAddr: a, callerPc: a, confident: true });
+    } else if (frames.every((f) => !f.confident)) {
+      frames.push({ returnAddr: a, callerPc: a, confident: false });
+    } else {
+      break;
+    }
+    addr = (addr + 4) >>> 0;
+  }
+  const anyConfident = frames.some((f) => f.confident);
+  return anyConfident ? frames.filter((f) => f.confident) : frames;
+}
+
+/**
+ * Build a backtrace from a register snapshot + a stack reader, dispatching on CPU
+ * family. Returns null if the platform isn't supported or the snapshot lacks a
+ * stack pointer — callers treat null as "no backtrace available", not an error.
+ *
+ * Coverage: 6502 family (nes/2600/7800/c64/lynx/pce), m68k (genesis), Z80
+ * (sms/gg/msx), SM83 (gb/gbc) — 13 of 14. GBA (ARM) is intentionally excluded:
+ * ARM's BL leaves the return address in the LINK REGISTER, not on the stack, so a
+ * stack walk doesn't recover the call chain without frame-pointer/unwind analysis.
+ *
+ * @param {Object} opts
+ * @param {string} opts.platform
+ * @param {Object} opts.regs           the `named` register map (hex strings)
+ * @param {(region:string, offset:number, length:number)=>Uint8Array} opts.readMemory
+ * @param {(cpuAddr:number)=>(number|null)} [opts.readByteAt]  validate the 6502 JSR opcode
+ * @param {(cpuAddr:number, bytes:number)=>(number|null)} [opts.readCpuWord]  read
+ *   a little-endian word at a CPU address (Z80/SM83 stacks live in work RAM at the
+ *   SP, not a fixed page) — required for z80/sm83.
+ * @param {(cpuAddr:number)=>(number|null)} [opts.readCpuLongBE]  read a 32-bit
+ *   big-endian longword at a 68K bus address — required for genesis.
+ * @param {number} [opts.maxDepth=8]
+ * @returns {{ frames: Array, isa: string } | null}
+ */
+export function buildBacktrace({ platform, regs, readMemory, readByteAt, readCpuWord, readCpuLongBE, maxDepth = 8 }) {
+  if (!regs) return null;
+  const SIXTYFIVE_OH_TWO = new Set(["nes", "atari2600", "atari7800", "c64", "lynx", "pce"]);
+  const Z80_FAMILY = new Set(["sms", "gg", "msx", "gb", "gbc"]); // z80 + sm83: same 2-byte LE call frame
+  if (SIXTYFIVE_OH_TWO.has(platform)) {
+    const sp = regNum(regs.s);
+    if (Number.isNaN(sp)) return null;
+    let stackPage;
+    try { stackPage = readMemory("system_ram", 0x0100, 0x100); } catch { return null; }
+    if (stackPage.length < 0x100) {
+      const full = new Uint8Array(0x100);
+      full.set(stackPage.subarray(0, 0x100));
+      stackPage = full;
+    }
+    const frames = decode6502Backtrace(sp, stackPage, readByteAt, maxDepth);
+    return { isa: "6502", frames };
+  }
+  if (Z80_FAMILY.has(platform)) {
+    const sp = regNum(regs.sp);
+    if (Number.isNaN(sp) || !readCpuWord) return null;
+    const readWordLE = (a) => readCpuWord(a, 2);
+    const frames = decode16BitStack(sp, readWordLE, maxDepth);
+    return { isa: platform === "gb" || platform === "gbc" ? "sm83" : "z80", frames };
+  }
+  if (platform === "genesis") {
+    const sp = regNum(regs.sp);
+    if (Number.isNaN(sp) || !readCpuLongBE) return null;
+    const frames = decodeM68kStack(sp, readCpuLongBE, maxDepth);
+    return { isa: "m68k", frames };
+  }
+  return null; // gba (ARM, link-register calls) — not a stack walk
+}

package/src/analysis/nes-ppu-runtime.js

@@ -0,0 +1,220 @@
+// NES-PPU-on-SNES PER-FRAME runtime — phase 2. The static shim
+// (nes-ppu-shim.js) draws the boot picture ONCE then stubs the PPU seam; this
+// runtime keeps it LIVE: every vblank it flushes the game's sprite state to SNES
+// OAM and runs the game's own NMI handler, so animation actually moves. Pairs
+// with recompile-65816.js (which wires the seam + NMI vector to these labels).
+//
+// WHY THIS IS TRACTABLE (not a full NES PPU in 65816):
+//   The recompiled NES logic runs in 65816 EMULATION mode, so the game's NES RAM
+//   IS SNES low RAM at the same addresses. A typical NES game builds a 256-byte
+//   "shadow OAM" in RAM (commonly $0200) and copies it to the PPU each frame via
+//   OAMDMA (`sta $4014`, A = source page). That shadow OAM therefore already
+//   exists in SNES WRAM — the runtime just (a) learns the page from the OAMDMA
+//   write, and (b) each vblank converts those 64 NES sprites to SNES OAM format
+//   and DMAs them in. Sprites are the dominant per-frame change, so this single
+//   feature turns "static screenshot" into "the sprites move."
+//
+// SCOPE (phase 2): sprites (OAM) + running the game's NMI each vblank + honoring
+//   PPUCTRL NMI-enable. Background stays as the shim uploaded it (live $2007
+//   nametable streaming is phase 3). APU is still no-op.
+//
+// FORMATS:
+//   NES OAM (4 bytes/sprite): [0]=Y, [1]=tile, [2]=attr, [3]=X
+//     attr: bit7=V-flip bit6=H-flip bit5=priority bits0-1=palette(4-7)
+//   SNES low OAM (4 bytes): [0]=X, [1]=Y, [2]=tile, [3]=attr
+//     attr: bit0=tile-bit8 bits1-3=palette bits4-5=priority bit6=H bit7=V
+//   SNES high OAM (2 bits/sprite): X-bit8 + size. Phase 2 writes it all-zero
+//     (X<256, small sprites).
+//   Conversion (verified on snes9x): SNES.X=NES.X, SNES.Y=NES.Y, SNES.tile=NES.tile,
+//     SNES.attr = (NES.attr & $C0) | ((NES.attr & 3) << 1).
+//
+// Plain JS ESM + JSDoc.
+
+/**
+ * Fixed runtime state in SNES low RAM ($0010-$0012 — a small window most NES
+ * games leave free in zero page; the NMI also saves/restores DP scratch $00).
+ */
+export const RT_RAM = {
+  OAMDMA_PAGE: "$0010", // high byte of the shadow-OAM source page (set by $4014)
+};
+
+/** The $7E WRAM staging buffer for the SNES OAM image (288 bytes: 256 + 32). */
+const OAM_STAGE = 0x1000;
+
+/**
+ * Emit the phase-2 runtime as asar source: NES_RT_INIT (enable NMI + sprite
+ * setup), NES_RT_NMI (the per-vblank flush + game NMI), NES_RT_FLUSH_SPRITES
+ * (the verified OAM conversion+DMA), and the seam bodies that maintain the
+ * OAMDMA-page mirror. recompile-65816 includes this INSTEAD of the v1 seam stub
+ * when the runtime is on, points the native NMI vector at NES_RT_NMI, and calls
+ * NES_RT_INIT from RESET_ENTRY.
+ *
+ * @param {Object} opts
+ * @param {string|null} opts.nesNmiLabel  the translated NES NMI handler's entry
+ *   label (the game's per-frame logic). If null, only the sprite flush runs.
+ * @param {number} [opts.oamPage=0x02]    default shadow-OAM page until $4014 sets
+ *   it (0x02 = $0200, the de-facto standard).
+ * @returns {string} asar source.
+ */
+export function emitPpuRuntime({ nesNmiLabel = null, oamPage = 0x02 } = {}) {
+  const stageHex = "$" + OAM_STAGE.toString(16).toUpperCase();
+  const highHex = "$" + (OAM_STAGE + 0x100).toString(16).toUpperCase();
+
+  // We are already in EMULATION mode here (NES_RT_NMI switched back before this),
+  // so just call the game's 6502 NMI body directly — no mode switch.
+  const callGameNmi = nesNmiLabel
+    ? [
+        "        ; run the game's own NMI handler (its per-frame logic), in E-mode",
+        `        jsr     ${nesNmiLabel}`,
+      ]
+    : ["        ; (no translated NES NMI handler — sprite flush only)"];
+
+  return [
+    "; ── NES-PPU-on-SNES per-frame runtime (phase 2: live sprites) ─────────",
+    "",
+    "!INIDISP  = $2100",
+    "!OBSEL    = $2101",
+    "!OAMADDL  = $2102",
+    "!OAMADDH  = $2103",
+    "!TM       = $212C",
+    "!NMITIMEN = $4200",
+    "!MDMAEN   = $420B",
+    "!DMAP0    = $4300",
+    "!BBAD0    = $4301",
+    "!A1T0L    = $4302",
+    "!A1B0     = $4304",
+    "!DAS0L    = $4305",
+    "",
+    "; called from RESET_ENTRY (native mode) before the game's reset runs.",
+    "NES_RT_INIT:",
+    "        php",
+    "        sep #$20",
+    "        rep #$10",
+    `        lda #$${oamPage.toString(16).padStart(2, "0")}`,
+    `        sta ${RT_RAM.OAMDMA_PAGE}   ; default shadow-OAM page until $4014 sets it`,
+    "        lda #$00",
+    "        sta !OBSEL              ; 8x8 sprites, sprite tiles share VRAM word $0000",
+    "        lda #$10",
+    "        sta !TM                 ; enable OBJ (sprites) on the main screen",
+    "        lda #$80",
+    "        sta !NMITIMEN           ; enable the vblank NMI (the game's heartbeat)",
+    "        plp",
+    "        rts",
+    "",
+    "; The per-vblank NMI handler. The recompiled game runs in 65816 EMULATION",
+    "; mode, so this is entered with e=1 (8-bit regs, page-1 stack, 6502-style NMI",
+    "; frame on the stack). We save the 8-bit regs, drop to NATIVE mode for the",
+    "; 16-bit-index sprite flush, come back to emulation, run the game's NMI, then",
+    "; rti in emulation mode so the pushed PC/P frame returns correctly.",
+    "NES_RT_NMI:",
+    "        pha",
+    "        phx",
+    "        phy",
+    "        ; save bank + DP, then go native for the flush.",
+    "        phb",
+    "        phd",
+    "        clc",
+    "        xce                     ; e=1 → native (saves e in carry)",
+    "        pea $0000",
+    "        pld                     ; DP = $0000 for scratch + low-RAM reads",
+    "        sep #$30",
+    "",
+    "        jsr NES_RT_FLUSH_SPRITES",
+    "",
+    "        sec",
+    "        xce                     ; native → back to EMULATION mode",
+    "",
+    ...callGameNmi,
+    "",
+    "        pld",
+    "        plb",
+    "        ply",
+    "        plx",
+    "        pla",
+    "        rti                     ; emulation-mode rti (pops P + 16-bit PC)",
+    "",
+    "; NES shadow OAM → SNES OAM. Verified on snes9x. Phase 2 reads the shadow OAM",
+    "; from $0200 (the de-facto-standard page); the OAMDMA seam records the actual",
+    "; page in OAMDMA_PAGE, and the init seeds it to $02. X walks the NES sprites,",
+    "; Y the SNES low table — both step by 4 in lockstep.",
+    "NES_RT_FLUSH_SPRITES:",
+    "        php",
+    "        sep #$20",
+    "        rep #$10",
+    "        lda #$7E",
+    "        pha",
+    "        plb                     ; DBR = $7E for the staging stores",
+    "        ldx #$0000              ; NES sprite byte index (0,4,..252) — DBR-independent",
+    "        ldy #$0000              ; SNES low-table byte index",
+    "-",
+    "        lda $0200,x             ; NES Y    ($0200 is bank-0 low RAM == $7E:0200)",
+    `        sta ${stageHex}+1,y     ; SNES [1] = Y`,
+    "        lda $0201,x             ; NES tile",
+    `        sta ${stageHex}+2,y     ; SNES [2] = tile`,
+    "        lda $0203,x             ; NES X",
+    `        sta ${stageHex}+0,y     ; SNES [0] = X`,
+    "        lda $0202,x             ; NES attr",
+    "        pha",
+    "        and #$C0                ; V/H flip bits (already aligned)",
+    "        sta $00",
+    "        pla",
+    "        and #$03                ; NES palette 0-3",
+    "        asl                     ; → SNES palette bits 1-3",
+    "        ora $00",
+    `        sta ${stageHex}+3,y     ; SNES [3] = attr`,
+    "        inx",
+    "        inx",
+    "        inx",
+    "        inx",
+    "        iny",
+    "        iny",
+    "        iny",
+    "        iny",
+    "        cpy.w #$0100            ; 64 sprites",
+    "        bne -",
+    "        ; high table (32 bytes) = all zero",
+    "        ldx #$0000",
+    "        lda #$00",
+    "-",
+    `        sta ${highHex},x`,
+    "        inx",
+    "        cpx.w #$0020",
+    "        bne -",
+    "        lda #$00",
+    "        pha",
+    "        plb                     ; DBR = $00",
+    "        ; DMA staging buffer → OAM",
+    "        lda #$00",
+    "        sta !OAMADDL",
+    "        sta !OAMADDH",
+    "        sta !DMAP0              ; 1-reg, increment",
+    "        lda #$04",
+    "        sta !BBAD0              ; B-bus = $2104 (OAMDATA)",
+    `        ldx #${stageHex}`,
+    "        stx !A1T0L              ; src addr low 16",
+    "        lda #$7E",
+    "        sta !A1B0               ; src bank",
+    "        ldx #$0120              ; 288 bytes",
+    "        stx !DAS0L",
+    "        lda #$01",
+    "        sta !MDMAEN             ; fire DMA channel 0",
+    "        plp",
+    "        rts",
+    "",
+    "; ── seam: maintain the OAMDMA-page mirror; no-op the rest in phase 2 ──",
+    "NES_PPU_WRITE:",
+    "        cpx #$14                ; $4014 (OAMDMA)?",
+    "        bne +",
+    `        sta ${RT_RAM.OAMDMA_PAGE}   ; A = the shadow-OAM source page`,
+    "+",
+    "        rts",
+    "NES_PPU_READ:",
+    "        lda #$80                ; PPUSTATUS vblank set → boot wait-loops exit",
+    "        rts",
+    "NES_APU_WRITE:",
+    "        rts",
+    "NES_OAM_DMA:",
+    "        rts",
+    "",
+  ].join("\n");
+}