romdevtools 0.40.2 → 0.42.0

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

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

@@ -0,0 +1,263 @@
+// NES-PPU-on-SNES runtime shim — the piece that fills the STUBBED seam left by
+// the NES→SNES recompile backend (recompile-65816.js). Without it, a recompiled
+// port boots and runs the 6502 logic but renders BLANK, because every NES PPU
+// write the logic makes is trapped to rts. This shim makes the boot picture
+// actually appear on SNES hardware.
+//
+// STATUS: WORKING (phase-1 static boot picture). The CONVERSION half
+// (nesTileToSnes4bpp / nesColorToBgr555 / buildSnesAssets) is correct and
+// unit-tested, and the emitted 65816 UPLOAD routine (emitPpuShim →
+// NES_SHIM_PRESENT) now DMAs tiles+tilemap+palette to SNES VRAM/CGRAM and turns
+// the screen on — verified end-to-end on snes9x (test/recompile-shim-render.test.js
+// asserts the converted assets land in VRAM/CGRAM; a recompiled NES boot screen
+// renders in color). The recompile op still gates the shim behind withShim:true
+// because phase 1 only draws the STATIC first screen — the recompiled NES logic
+// then runs in emulation mode against a STUBBED PPU seam, so animation/scroll/
+// sprites are not maintained yet (next layer; see the design note below).
+//
+// The bug that made this "experimental" for a while: `rep #$10` makes X 16-bit at
+// runtime, but asar sizes index immediates by the literal and assembled a bare
+// `cpx #32` (the small CGRAM count) as an 8-bit instruction — the CPU then decoded
+// 3 bytes, ate the next opcode, and the whole routine derailed (blank screen +
+// CPU runaway). Fix: `cpx.w` on every loop. The compareRender/findDiverge oracles
+// were the tools that localized it.
+//
+// DESIGN (phase 1 — the STATIC boot picture). Rather than hand-write a full NES
+// PPU emulator in 65816 asm, the shim is generated at recompile time from the
+// LIVE NES PPU state: the recompiler already boots the original ROM, so we read
+// its CHR (tiles), nametable (the background map), and palette AFTER boot,
+// CONVERT them to SNES formats in JS, and emit:
+//   - SNES tile data (NES 2bpp → SNES 4bpp), as bytes to incbin/db
+//   - a SNES tilemap (from the NES nametable), and
+//   - a SNES palette (NES indices → BGR555 CGRAM)
+//   - a small fixed 65816 routine that DMAs all three to VRAM/CGRAM and turns
+//     the screen on.
+// The result: the port shows the same first screen as the original. This is the
+// static path; animated/scrolling/sprite presentation is the next layer (the
+// shim would then run per-frame off the seam's maintained NES-VRAM mirror).
+//
+// Plain JS ESM + JSDoc. Pairs with recompile-65816.js + the NES PPU read/decode
+// helpers in platforms/nes/ppu.js.
+
+import { decodeTile, nesPaletteIndexToRgb } from "../platforms/nes/ppu.js";
+
+/**
+ * Convert one NES 2bpp tile (16 bytes) to one SNES 4bpp tile (32 bytes).
+ *
+ * NES tile: 8 bytes plane0 then 8 bytes plane1 (bit per pixel each), giving a
+ * 2-bit (0-3) index per pixel. SNES 4bpp tile: 32 bytes as TWO bitplane pairs —
+ * bytes 0-15 are planes 0&1 row-interleaved (lo,hi,lo,hi,... per row), bytes
+ * 16-31 are planes 2&3 the same way. We map the NES 2-bit index straight into
+ * the low two SNES planes; planes 2&3 stay 0 (NES only has 4 colors per tile).
+ *
+ * @param {Uint8Array} nesTile16
+ * @returns {Uint8Array} 32-byte SNES 4bpp tile
+ */
+export function nesTileToSnes4bpp(nesTile16) {
+  const px = decodeTile(nesTile16); // 64 entries, each 0-3
+  const out = new Uint8Array(32);
+  for (let y = 0; y < 8; y++) {
+    let p0 = 0, p1 = 0;
+    for (let x = 0; x < 8; x++) {
+      const v = px[y * 8 + x];
+      const bit = 7 - x;
+      if (v & 1) p0 |= 1 << bit;
+      if (v & 2) p1 |= 1 << bit;
+    }
+    // planes 0&1 row-interleaved in the first 16 bytes
+    out[y * 2] = p0;
+    out[y * 2 + 1] = p1;
+    // planes 2&3 (bytes 16-31) remain 0
+  }
+  return out;
+}
+
+/**
+ * Convert a NES palette byte (a 6-bit NES color index) to a SNES BGR555 uint16.
+ * NES index → RGB888 (via the canonical NES palette) → BGR555 (5 bits each,
+ * blue high). This is the CGRAM word format.
+ * @param {number} nesIndex
+ * @returns {number} 0..0x7FFF
+ */
+export function nesColorToBgr555(nesIndex) {
+  const [r, g, b] = nesPaletteIndexToRgb(nesIndex & 0x3f);
+  const r5 = (r >> 3) & 0x1f;
+  const g5 = (g >> 3) & 0x1f;
+  const b5 = (b >> 3) & 0x1f;
+  return (b5 << 10) | (g5 << 5) | r5;
+}
+
+/**
+ * Build the SNES presentation assets from live NES PPU state.
+ *
+ * @param {Object} state
+ * @param {Uint8Array} state.chr        NES pattern data (>=4096 bytes; the BG
+ *   pattern table — we take the first 256 tiles / 4KB).
+ * @param {Uint8Array} state.nametable  one 32x30 NES nametable's tile indices
+ *   (960 bytes; the attribute bytes that follow are ignored in phase 1).
+ * @param {Uint8Array} state.palette    32-byte NES palette ($3F00-$3F1F). We use
+ *   the BG palette (first 16 bytes) for CGRAM.
+ * @returns {{ tiles: Uint8Array, tilemap: Uint8Array, cgram: Uint8Array,
+ *             tileCount: number, mapEntries: number }}
+ */
+export function buildSnesAssets({ chr, nametable, palette }) {
+  // Tiles: first 256 NES tiles (4KB) → 256 SNES 4bpp tiles (8KB).
+  const tileCount = Math.min(256, Math.floor(chr.length / 16));
+  const tiles = new Uint8Array(tileCount * 32);
+  for (let t = 0; t < tileCount; t++) {
+    const nes = chr.subarray(t * 16, t * 16 + 16);
+    tiles.set(nesTileToSnes4bpp(nes), t * 32);
+  }
+
+  // Tilemap: NES nametable is 32x30 of 1-byte tile indices. SNES BG map entries
+  // are 16-bit (tile# in low 10 bits + palette/priority/flip in the high bits).
+  // Phase 1: palette 0, no flip/priority → entry = tile index. SNES BG map is
+  // 32x32; we fill the first 30 rows and leave the bottom 2 as tile 0.
+  const mapEntries = 32 * 32;
+  const tilemap = new Uint8Array(mapEntries * 2);
+  for (let row = 0; row < 30; row++) {
+    for (let col = 0; col < 32; col++) {
+      const nesTile = nametable[row * 32 + col] ?? 0;
+      const e = (row * 32 + col) * 2;
+      tilemap[e] = nesTile;     // low byte = tile index
+      tilemap[e + 1] = 0;       // high byte = palette 0, no flip/prio
+    }
+  }
+
+  // CGRAM: NES BG palette (16 bytes) → 16 BGR555 colors. NES color 0 ($3F00) is
+  // the universal backdrop → CGRAM index 0.
+  const cgram = new Uint8Array(16 * 2);
+  for (let i = 0; i < 16; i++) {
+    const bgr = nesColorToBgr555(palette[i] ?? 0);
+    cgram[i * 2] = bgr & 0xff;
+    cgram[i * 2 + 1] = (bgr >> 8) & 0xff;
+  }
+
+  return { tiles, tilemap, cgram, tileCount, mapEntries };
+}
+
+/** Format a byte array as asar `db $xx,$xx,...` lines (16 per line). */
+function dbLines(bytes, indent = "        ") {
+  const lines = [];
+  for (let i = 0; i < bytes.length; i += 16) {
+    const chunk = Array.from(bytes.subarray(i, i + 16))
+      .map((b) => "$" + b.toString(16).padStart(2, "0"))
+      .join(",");
+    lines.push(`${indent}db ${chunk}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Emit the SNES PPU shim as asar source: the converted data tables + a fixed
+ * 65816 routine `NES_SHIM_PRESENT` that DMAs tiles→VRAM, tilemap→VRAM,
+ * palette→CGRAM, sets BG mode 0 / bases, and turns the screen on. The
+ * recompiled reset wrapper calls NES_SHIM_PRESENT once after the game's boot
+ * logic has run (so the NES state is fully set up before we snapshot+convert).
+ *
+ * VRAM layout (word addresses): tiles at $0000, BG1 tilemap at $4000.
+ *
+ * @param {ReturnType<typeof buildSnesAssets>} assets
+ * @returns {string} asar source (define NES_SHIM_PRESENT + the data)
+ */
+export function emitPpuShim(assets) {
+  const { tiles, tilemap, cgram, tileCount } = assets;
+  return [
+    "; ── NES-PPU-on-SNES shim (phase 1: static boot picture) ──────────────",
+    "; Converted from the original ROM's live PPU state at recompile time:",
+    `;   ${tileCount} tiles (NES 2bpp → SNES 4bpp), a 32x30 BG tilemap, 16 colors.`,
+    "; NES_SHIM_PRESENT DMAs them to VRAM/CGRAM and enables BG1. Call it once",
+    "; after the game's boot logic has set up its PPU state.",
+    "",
+    "; SNES PPU registers used by the shim",
+    "!INIDISP = $2100",
+    "!BGMODE  = $2105",
+    "!BG1SC   = $2107   ; BG1 map base + size",
+    "!BG12NBA = $210B   ; BG1/BG2 char base",
+    "!VMAIN   = $2115",
+    "!VMADDL  = $2116",
+    "!VMDATAL = $2118",
+    "!CGADD   = $2121",
+    "!CGDATA  = $2122",
+    "!TM      = $212C",
+    "",
+    "NES_SHIM_PRESENT:",
+    "        php",
+    "        sep #$20                 ; 8-bit A for register writes",
+    "        rep #$10                 ; 16-bit X/Y for loop indices",
+    "",
+    "        lda #$80",
+    "        sta !INIDISP             ; forced blank during upload",
+    "        lda #$80",
+    "        sta !VMAIN               ; VRAM addr +1 word after the HIGH-byte write",
+    "",
+    "        ; ── tiles → VRAM word $0000 ── (word writes via VMDATAL/H)",
+    "        ldx #$0000",
+    "        stx !VMADDL              ; VRAM word address $0000 (16-bit store)",
+    "        ldx #$0000",
+    "-       lda.l NES_SHIM_TILES,x",
+    "        sta !VMDATAL             ; low byte",
+    "        inx",
+    "        lda.l NES_SHIM_TILES,x",
+    "        sta !VMDATAL+1           ; high byte → triggers +1 word",
+    "        inx",
+    // `cpx.w` forces the 16-bit immediate form. We ran `rep #$10`, so X is
+    // 16-bit at RUNTIME, but asar does NOT track register width across rep/sep —
+    // it sizes index immediates by the literal, defaulting <256 to 8-bit. A bare
+    // `cpx #32` would assemble to 2 bytes while the CPU decodes 3, eating the
+    // next opcode and derailing the routine. The big tile/map counts (>255)
+    // happen to force 16-bit anyway; the small CGRAM count (32) is the one that
+    // bit us — so make ALL three explicit with `.w` and never rely on the value.
+    `        cpx.w #${tiles.length}`,
+    "        bne -",
+    "",
+    "        ; ── tilemap → VRAM word $4000 ──",
+    "        ldx #$4000",
+    "        stx !VMADDL              ; VRAM word address $4000",
+    "        ldx #$0000",
+    "-       lda.l NES_SHIM_MAP,x",
+    "        sta !VMDATAL",
+    "        inx",
+    "        lda.l NES_SHIM_MAP,x",
+    "        sta !VMDATAL+1",
+    "        inx",
+    `        cpx.w #${tilemap.length}`,
+    "        bne -",
+    "",
+    "        ; ── palette → CGRAM index 0 ──",
+    "        lda #$00",
+    "        sta !CGADD",
+    "        ldx #$0000",
+    `-       lda.l NES_SHIM_CGRAM,x`,
+    "        sta !CGDATA              ; CGADD auto-increments after each byte",
+    "        inx",
+    `        cpx.w #${cgram.length}    ; .w: 16-bit X at runtime (see note above)`,
+    "        bne -",
+    "",
+    "        ; ── BG setup + screen on ──",
+    "        lda #$00",
+    "        sta !BGMODE              ; mode 0, 8x8 tiles",
+    "        lda #$40",
+    "        sta !BG1SC               ; BG1 map base = VRAM word $4000 ((reg>>2)<<10)",
+    "        lda #$00",
+    "        sta !BG12NBA             ; BG1 char base = VRAM word $0000",
+    "        lda #$01",
+    "        sta !TM                  ; enable BG1 on main screen",
+    "        lda #$0f",
+    "        sta !INIDISP             ; full brightness, blank off",
+    "        plp",
+    "        rts",
+    "",
+    "; Shim data in its OWN bank so `lda.l TABLE,x` indexing never straddles a",
+    "; LoROM 32KB bank boundary (the 8KB tile table would otherwise wrap). Bank 2",
+    "; ($02:8000) is free after the code (bank 0) and the recompiled body.",
+    "org $028000",
+    "NES_SHIM_TILES:",
+    dbLines(tiles),
+    "NES_SHIM_MAP:",
+    dbLines(tilemap),
+    "NES_SHIM_CGRAM:",
+    dbLines(cgram),
+    "",
+  ].join("\n");
+}