romdev-mcp 0.1.1

package/src/platforms/nes/lib/nmi_safe.s

@@ -0,0 +1,65 @@
+; NES — safe NMI/VBlank handler skeleton.
+;
+; The NES 6502's NMI doesn't preserve registers — you MUST push them
+; yourself. Gotchas this snippet covers:
+;
+; 1. **Register preservation.** Push A, X, Y. Without this, your main
+;    code's loop variable gets clobbered mid-frame and animations break
+;    in inscrutable ways.
+;
+; 2. **PPU register order.** OAM DMA ($4014) must run with the OAM
+;    address ($2003) reset to 0 first. If main code was mid-PPU-access
+;    when NMI fired, the address may be at random offsets.
+;
+; 3. **PPUSTATUS ($2002) clears the vblank flag on read.** A read in
+;    NMI is fine, but be aware that reading it from main code (e.g. in
+;    a wait_vblank loop) will lose the next NMI's "vblank started"
+;    signal if you race.
+;
+; 4. **vblank_ready flag.** Main-code loops should test a software flag
+;    that NMI sets, not poll $2002 directly. Polling races NMI's read.
+;
+; This skeleton: push A/X/Y, do OAM DMA + any pending PPU writes, set
+; the vblank flag, restore registers.
+
+.proc nmi_handler
+  ; ---- preserve regs ----
+  pha
+  txa
+  pha
+  tya
+  pha
+
+  ; ---- OAM DMA (typically the first thing in VBlank) ----
+  lda #$00
+  sta $2003                ; OAMADDR = 0
+  lda #$02                 ; soft-OAM at $0200
+  sta $4014                ; trigger 256-byte DMA
+
+  ; ---- per-frame PPU work goes here ----
+  ; e.g. palette updates, nametable patches via PPUDATA $2007
+  ; jsr update_palette_if_changed
+
+  ; ---- set vblank-ready flag for main code ----
+  lda #1
+  sta vblank_ready
+
+  ; ---- restore + return ----
+  pla
+  tay
+  pla
+  tax
+  pla
+  rti
+.endproc
+
+; In your main loop:
+;   wait_vblank:
+;     lda vblank_ready
+;     beq wait_vblank
+;     lda #0
+;     sta vblank_ready
+;     ; ... per-frame logic ...
+;
+; ---- ZP reservations ----
+;   vblank_ready: .res 1   ; set by NMI, consumed by main loop

package/src/platforms/nes/lib/oam_dma.s

@@ -0,0 +1,16 @@
+; NES — copy 256-byte shadow OAM at $0200 to the PPU via DMA.
+;
+; Call this inside your NMI handler. It transfers all 64 sprites' attributes
+; in ~513 cycles, which is the only fast way to update sprites without
+; tearing.
+;
+; The shadow OAM is at $0200-$02FF by convention; that's the page we tell
+; the DMA register $4014 to copy from (just write the high byte).
+
+.proc oam_dma
+  lda #0
+  sta $2003       ; set OAM address to start
+  lda #$02
+  sta $4014       ; trigger DMA from page $02
+  rts
+.endproc

package/src/platforms/nes/lib/read_pad.s

@@ -0,0 +1,46 @@
+; NES — read controller 1 into the keydown byte.
+;
+; After calling read_pad, keydown holds the button state:
+;   bit 7 = A     bit 6 = B     bit 5 = Select  bit 4 = Start
+;   bit 3 = Up    bit 2 = Down  bit 1 = Left    bit 0 = Right
+;
+; Also computes keynew = buttons newly pressed this frame
+; (useful for one-shot events like jump-on-tap, menu confirm).
+;
+; Requires these zeropage variables (declare in your own .segment "ZEROPAGE"):
+;   keydown: .res 1
+;   keylast: .res 1
+;   keynew:  .res 1
+;
+; Uses a counted 8-iteration loop — the seed-bit-through-rol idiom is
+; fragile and platform-dependent; this is the safe version.
+
+JOY1 = $4016
+
+.proc read_pad
+  lda keydown
+  sta keylast
+
+  ; Strobe: write 1 then 0 to $4016 to latch the current button state.
+  lda #1
+  sta JOY1
+  lda #0
+  sta JOY1
+
+  ; Read 8 bits, one per loop iteration. Each $4016 read returns the
+  ; next button in bit 0; we shift that bit into keydown via carry.
+  ldx #8
+@loop:
+  lda JOY1
+  lsr a            ; bit 0 -> carry
+  rol keydown      ; carry -> bit 0 of keydown; high bits shift up
+  dex
+  bne @loop
+
+  ; keynew = (NOT keylast) AND keydown -> buttons pressed THIS frame only
+  lda keylast
+  eor #$ff
+  and keydown
+  sta keynew
+  rts
+.endproc

package/src/platforms/nes/lib/reset.s

@@ -0,0 +1,46 @@
+; NES — standard reset routine.
+;
+; Sets up the CPU + APU + PPU to a known clean state. Standard idiom every
+; NES game uses; copy this verbatim into a new project's reset handler and
+; call your init code at the end.
+
+.proc reset_init
+  sei             ; disable IRQs
+  cld             ; clear decimal mode (NES 2A03 doesn't support BCD anyway)
+  ldx #$40
+  stx $4017       ; disable APU frame IRQ
+  ldx #$ff
+  txs             ; stack at $01FF
+  inx             ; X = 0
+  stx $2000       ; disable NMI
+  stx $2001       ; disable rendering
+  stx $4010       ; disable DMC IRQ
+
+  ; wait for first vblank
+@v1:
+  bit $2002
+  bpl @v1
+
+  ; zero RAM ($0000-$07FF), set OAM shadow ($0200-$02FF) to Y=$FF off-screen
+  ldx #0
+@clrmem:
+  lda #0
+  sta $0000, x
+  sta $0100, x
+  sta $0300, x
+  sta $0400, x
+  sta $0500, x
+  sta $0600, x
+  sta $0700, x
+  lda #$ff
+  sta $0200, x
+  inx
+  bne @clrmem
+
+  ; wait for second vblank — PPU is fully warm now
+@v2:
+  bit $2002
+  bpl @v2
+
+  rts             ; caller turns on rendering when ready
+.endproc

package/src/platforms/nes/lib/sprite_table_populate.s

@@ -0,0 +1,75 @@
+; NES — populating the OAM sprite table.
+;
+; OAM is 256 bytes: 64 sprites × 4 bytes each.
+;   byte 0: Y position (NOTE: stored as actual_y - 1; e.g. y=$10 means
+;           the sprite's top edge is at scanline $11)
+;   byte 1: tile number (0..255; PPUCTRL bit 3 picks tile bank for 8x8
+;           mode; for 8x16 mode, bit 0 of the tile number picks the
+;           bank and bits 1-7 are the tile index *2)
+;   byte 2: attribute  — vhpxxxpp
+;            bit 7: V flip
+;            bit 6: H flip
+;            bit 5: behind background (0 = in front)
+;            bits 0-1: palette (0..3 selects sprite palette 0..3)
+;   byte 3: X position
+;
+; Gotchas:
+;   • Y = $EF (239) or higher hides the sprite — the PPU treats it as
+;     "off screen". So unused sprite slots are conventionally set to
+;     Y=$FF to hide them.
+;   • Tile bank for 8x8 sprites is global (PPUCTRL bit 3) and CAN'T be
+;     per-sprite. For 8x16 mode (PPUCTRL bit 5), the tile byte's bit 0
+;     selects the bank per sprite instead — strange but powerful.
+;   • OAM can only be written via $2003/$2004 (slow, one byte at a
+;     time) or via DMA from a page-aligned RAM buffer (256 bytes
+;     in 513 cycles). ALWAYS use DMA in real code.
+;   • The OAM DMA source MUST be page-aligned (high byte is the page,
+;     low byte starts at $00). Convention: put soft OAM at $0200.
+
+; ---- soft OAM in RAM (page-aligned at $0200) ----
+SOFT_OAM = $0200
+
+; ---- example: write sprite N at (x, y) tile T attr A ----
+; Inputs:
+;   A = slot (0..63)
+;   x_pos, y_pos, tile_num, attr in zeropage (set by caller)
+
+.proc write_sprite
+  asl
+  asl                       ; A = slot * 4 = byte offset
+  tax                       ; X = byte offset
+  lda y_pos
+  sta SOFT_OAM, x
+  lda tile_num
+  sta SOFT_OAM + 1, x
+  lda attr
+  sta SOFT_OAM + 2, x
+  lda x_pos
+  sta SOFT_OAM + 3, x
+  rts
+.endproc
+
+; ---- hide all sprites: set every Y to $FF ----
+.proc clear_oam
+  ldx #0
+  lda #$FF
+@loop:
+  sta SOFT_OAM, x
+  inx
+  inx
+  inx
+  inx                       ; skip to next sprite's Y byte
+  bne @loop
+  rts
+.endproc
+
+; ---- OAM DMA: run this at the START of vblank, NOT in the NMI body ----
+; Writing $2003=$00 then $4014=$02 copies 256 bytes from $0200-$02FF
+; to OAM[$00..$FF]. Takes 513 CPU cycles (~1 scanline).
+.proc oam_dma
+  lda #$00
+  sta $2003                 ; OAMADDR = 0
+  lda #$02                  ; page $02 = $0200
+  sta $4014                 ; trigger DMA
+  rts
+.endproc

package/src/platforms/nes/lib/wait_vblank.s

@@ -0,0 +1,12 @@
+; NES — wait for vblank (PPU status bit 7).
+;
+; Use during reset / setup before touching PPU registers, so you know the
+; PPU is in a safe state. Standard idiom: two waits before enabling
+; rendering, because the PPU is unstable for the first ~30k cycles.
+
+.proc wait_vblank
+@wait:
+  bit $2002
+  bpl @wait
+  rts
+.endproc

package/src/platforms/nes/palette.js

@@ -0,0 +1,39 @@
+// NES 64-color master palette. Each entry is one of the colors the PPU can
+// emit; the NES uses indexes into this table (with 4 entries forming a
+// per-tile palette).
+//
+// These are the standard "NTSC NES Classic" RGB approximations published
+// widely on NESdev. Different cores use slightly different palettes; this
+// one is what fceumm renders by default.
+
+/** @type {[number, number, number][]} 64 (r, g, b) tuples. */
+export const NES_PALETTE = [
+  [124,124,124], [  0,  0,252], [  0,  0,188], [ 68, 40,188],
+  [148,  0,132], [168,  0, 32], [168, 16,  0], [136, 20,  0],
+  [ 80, 48,  0], [  0,120,  0], [  0,104,  0], [  0, 88,  0],
+  [  0, 64, 88], [  0,  0,  0], [  0,  0,  0], [  0,  0,  0],
+
+  [188,188,188], [  0,120,248], [  0, 88,248], [104, 68,252],
+  [216,  0,204], [228,  0, 88], [248, 56,  0], [228, 92, 16],
+  [172,124,  0], [  0,184,  0], [  0,168,  0], [  0,168, 68],
+  [  0,136,136], [  0,  0,  0], [  0,  0,  0], [  0,  0,  0],
+
+  [248,248,248], [ 60,188,252], [104,136,252], [152,120,248],
+  [248,120,248], [248, 88,152], [248,120, 88], [252,160, 68],
+  [248,184,  0], [184,248, 24], [ 88,216, 84], [ 88,248,152],
+  [  0,232,216], [120,120,120], [  0,  0,  0], [  0,  0,  0],
+
+  [252,252,252], [164,228,252], [184,184,248], [216,184,248],
+  [248,184,248], [248,164,192], [240,208,176], [252,224,168],
+  [248,216,120], [216,248,120], [184,248,184], [184,248,216],
+  [  0,252,252], [248,216,248], [  0,  0,  0], [  0,  0,  0],
+];
+
+/**
+ * Look up the RGB for a NES palette index (0..63).
+ * @param {number} idx
+ * @returns {[number, number, number]}
+ */
+export function nesIndexToRgb(idx) {
+  return NES_PALETTE[idx & 0x3f];
+}

package/src/platforms/nes/ppu.js

@@ -0,0 +1,372 @@
+// NES PPU decoders.
+//
+// Reads VIDEO_RAM (pattern tables, name tables) and active palette from
+// SYSTEM_RAM or directly from the libretro VIDEO_RAM region, and produces
+// PNG images the agent can view through MCP.
+//
+// The NES PPU has its own 16KB address space, but libretro exposes the
+// 8KB CHR ROM/RAM (pattern tables) via RETRO_MEMORY_VIDEO_RAM. fceumm and
+// nestopia both follow this convention.
+//
+// Pattern table layout (8×8 tiles, 2bpp):
+//   16 bytes per tile.
+//   bytes 0..7  = bit plane 0 (low bit of pixel)
+//   bytes 8..15 = bit plane 1 (high bit of pixel)
+//   pixel(x, y) = ((byte[y]   >> (7-x)) & 1)
+//               | (((byte[y+8] >> (7-x)) & 1) << 1)
+//
+// Name table layout (32×30 tiles in screen position, then a 64-byte
+// attribute table). We render the visible tile grid using the pattern
+// table at $0000 and a default palette since we don't know which palette
+// each region uses without parsing the attribute table.
+
+import { PNG } from "pngjs";
+import { NES_PALETTE } from "./palette.js";
+
+/**
+ * Decode a single 8×8 tile from a 16-byte slice into an array of 64 2-bit
+ * pixel values (row-major, top-left first).
+ * @param {Uint8Array} tile16
+ * @returns {Uint8Array} length 64
+ */
+export function decodeTile(tile16) {
+  const out = new Uint8Array(64);
+  for (let y = 0; y < 8; y++) {
+    const lo = tile16[y];
+    const hi = tile16[y + 8];
+    for (let x = 0; x < 8; x++) {
+      const bit = 7 - x;
+      const p = ((lo >> bit) & 1) | (((hi >> bit) & 1) << 1);
+      out[y * 8 + x] = p;
+    }
+  }
+  return out;
+}
+
+/**
+ * Render a 256-tile pattern table (4KB) as a 128×128 PNG (16 tiles per row).
+ *
+ * @param {Uint8Array} chr4k 4096 bytes of pattern table data
+ * @param {[number, number, number][]} [palette] 4 (r,g,b) entries; default
+ *   light gray ramp so empty tiles are visible.
+ * @returns {Buffer} PNG bytes
+ */
+export function renderPatternTablePng(chr4k, palette) {
+  if (chr4k.length !== 4096) {
+    throw new Error(`pattern table must be 4096 bytes, got ${chr4k.length}`);
+  }
+  const pal = palette ?? [
+    [  0,  0,  0],   // 0 = transparent → black
+    [ 80, 80, 80],
+    [160,160,160],
+    [240,240,240],
+  ];
+
+  const png = new PNG({ width: 128, height: 128 });
+  const dst = png.data;
+  for (let t = 0; t < 256; t++) {
+    const tile = decodeTile(chr4k.subarray(t * 16, t * 16 + 16));
+    const tx = t % 16;
+    const ty = Math.floor(t / 16);
+    for (let y = 0; y < 8; y++) {
+      for (let x = 0; x < 8; x++) {
+        const p = tile[y * 8 + x];
+        const [r, g, b] = pal[p];
+        const dx = tx * 8 + x;
+        const dy = ty * 8 + y;
+        const o = (dy * 128 + dx) * 4;
+        dst[o + 0] = r;
+        dst[o + 1] = g;
+        dst[o + 2] = b;
+        dst[o + 3] = 0xff;
+      }
+    }
+  }
+  return PNG.sync.write(png);
+}
+
+/**
+ * Render BOTH 4KB pattern tables side by side as a 256×128 PNG.
+ *
+ * @param {Uint8Array} chr8k 8192 bytes (both tables)
+ * @returns {Buffer}
+ */
+export function renderBothPatternTablesPng(chr8k) {
+  if (chr8k.length !== 8192) {
+    throw new Error(`expected 8192 bytes of CHR, got ${chr8k.length}`);
+  }
+  const left = renderPatternTablePng(chr8k.subarray(0, 4096));
+  const right = renderPatternTablePng(chr8k.subarray(4096));
+  // Stitch together. Decode + recompose.
+  const l = PNG.sync.read(left);
+  const r = PNG.sync.read(right);
+  const png = new PNG({ width: 256, height: 128 });
+  for (let y = 0; y < 128; y++) {
+    for (let x = 0; x < 128; x++) {
+      const sIdx = (y * 128 + x) * 4;
+      const dIdxL = (y * 256 + x) * 4;
+      const dIdxR = (y * 256 + (x + 128)) * 4;
+      png.data[dIdxL + 0] = l.data[sIdx + 0];
+      png.data[dIdxL + 1] = l.data[sIdx + 1];
+      png.data[dIdxL + 2] = l.data[sIdx + 2];
+      png.data[dIdxL + 3] = l.data[sIdx + 3];
+      png.data[dIdxR + 0] = r.data[sIdx + 0];
+      png.data[dIdxR + 1] = r.data[sIdx + 1];
+      png.data[dIdxR + 2] = r.data[sIdx + 2];
+      png.data[dIdxR + 3] = r.data[sIdx + 3];
+    }
+  }
+  return PNG.sync.write(png);
+}
+
+/**
+ * Convert a NES palette entry (0..63) to the RGB triple. Convenience wrapper.
+ * @param {number} idx
+ * @returns {[number, number, number]}
+ */
+export function nesPaletteIndexToRgb(idx) {
+  return NES_PALETTE[idx & 0x3f];
+}
+
+/**
+ * Normalize the active NES palette into the generic shape used by
+ * inspectPalette across every platform: `{index, r, g, b, rawWord}[]`.
+ * On NES, rawWord is the 6-bit palette ROM index (0..63).
+ * @param {Uint8Array} palette32
+ * @returns {Array<{ index: number, r: number, g: number, b: number, rawWord: number }>}
+ */
+export function paletteToGenericColors(palette32) {
+  const out = [];
+  for (let i = 0; i < 32; i++) {
+    const idx = palette32[i] & 0x3F;
+    const [r, g, b] = NES_PALETTE[idx];
+    out.push({ index: i, r, g, b, rawWord: idx });
+  }
+  return out;
+}
+
+/**
+ * Render a NES background nametable into a real 256×240 PNG by compositing:
+ *   - the 32×30 tile indices from the nametable
+ *   - the active 4 BG palettes from the palette region
+ *   - the active background CHR pattern table
+ *   - the 64-byte attribute table at the end of the nametable
+ *
+ * @param {Object} args
+ * @param {Uint8Array} args.nametable   1024 bytes (32×30 tiles + 64 attr bytes + 64 byte tile padding)
+ * @param {Uint8Array} args.chr         4096 bytes — a single CHR pattern table
+ * @param {Uint8Array} args.palette     32 bytes from $3F00-$3F1F
+ * @returns {Buffer} PNG bytes
+ */
+export function renderNametablePng(args) {
+  const { nametable, chr, palette } = args;
+  if (nametable.length < 1024) throw new Error(`nametable must be ≥1024 bytes, got ${nametable.length}`);
+  if (chr.length < 4096) throw new Error(`chr must be ≥4096 bytes, got ${chr.length}`);
+  if (palette.length < 32) throw new Error(`palette must be ≥32 bytes, got ${palette.length}`);
+
+  const png = new PNG({ width: 256, height: 240 });
+  const dst = png.data;
+  // Attribute table starts at +960 (32*30 = 960 tile indices), 64 bytes
+  // covering 8×8 attribute cells (each cell = 4×4 tiles = 32×32 px).
+  const attrBase = 960;
+
+  for (let tileY = 0; tileY < 30; tileY++) {
+    for (let tileX = 0; tileX < 32; tileX++) {
+      const tileIdx = nametable[tileY * 32 + tileX];
+
+      // Determine which BG palette this tile uses via the attribute table.
+      const attrX = tileX >> 2;
+      const attrY = tileY >> 2;
+      const attrByte = nametable[attrBase + attrY * 8 + attrX];
+      // Each 32x32 region splits into 4 16x16 quadrants. Which one are we in?
+      const quadX = (tileX & 2) >> 1;
+      const quadY = (tileY & 2) >> 1;
+      const shift = (quadY * 2 + quadX) * 2;
+      const palIdx = (attrByte >> shift) & 0x3;
+      // BG palette base: $3F00 + palIdx * 4
+      const palBase = palIdx * 4;
+      const colors = [
+        palette[0],            // universal background
+        palette[palBase + 1],
+        palette[palBase + 2],
+        palette[palBase + 3],
+      ];
+
+      // Decode the tile bitplanes.
+      for (let py = 0; py < 8; py++) {
+        const lo = chr[tileIdx * 16 + py];
+        const hi = chr[tileIdx * 16 + py + 8];
+        for (let px = 0; px < 8; px++) {
+          const bit = 7 - px;
+          const p = ((lo >> bit) & 1) | (((hi >> bit) & 1) << 1);
+          const palByte = colors[p];
+          const [r, g, b] = NES_PALETTE[palByte & 0x3f];
+          const sx = tileX * 8 + px;
+          const sy = tileY * 8 + py;
+          const o = (sy * 256 + sx) * 4;
+          dst[o + 0] = r;
+          dst[o + 1] = g;
+          dst[o + 2] = b;
+          dst[o + 3] = 0xff;
+        }
+      }
+    }
+  }
+  return PNG.sync.write(png);
+}
+
+/**
+ * Convenience: snapshot the active background from a loaded NES host.
+ * Reads nametable, palette, and CHR via the patched fceumm memory regions
+ * and composites them into a single PNG.
+ *
+ * @param {import("../../host/index.js").LibretroHost} host
+ * @param {Object} [opts]
+ * @param {0 | 1} [opts.which] which 1KB nametable (0 = $2000, 1 = $2400). Default 0.
+ * @returns {Buffer}
+ */
+export function snapshotNametable(host, opts = {}) {
+  const which = opts.which ?? 0;
+  const nt = host.readMemory("nes_nametables", which * 1024, 1024);
+  const palette = host.readMemory("nes_palette", 0, 32);
+  const chr = host.readMemory("nes_chr", 0, 4096); // BG pattern table is at 0x0000
+  return renderNametablePng({ nametable: nt, chr, palette });
+}
+
+/**
+ * Render a 32-byte palette block (the NES has 32 palette entries total,
+ * 16 BG + 16 sprite) as a 16×2 grid of swatches at 16px each → 256×32 PNG.
+ *
+ * @param {Uint8Array} palette32 32 bytes from $3F00–$3F1F
+ * @returns {Buffer}
+ */
+export function renderPalettePng(palette32) {
+  if (palette32.length !== 32) {
+    throw new Error(`expected 32 bytes of palette, got ${palette32.length}`);
+  }
+  const SW = 16;
+  const png = new PNG({ width: 16 * SW, height: 2 * SW });
+  for (let i = 0; i < 32; i++) {
+    const col = i % 16;
+    const row = Math.floor(i / 16);
+    const [r, g, b] = NES_PALETTE[palette32[i] & 0x3f];
+    for (let y = 0; y < SW; y++) {
+      for (let x = 0; x < SW; x++) {
+        const dx = col * SW + x;
+        const dy = row * SW + y;
+        const o = (dy * 16 * SW + dx) * 4;
+        png.data[o + 0] = r;
+        png.data[o + 1] = g;
+        png.data[o + 2] = b;
+        png.data[o + 3] = 0xff;
+      }
+    }
+  }
+  return PNG.sync.write(png);
+}
+
+/**
+ * Read the pattern tables from a loaded NES host and return a PNG of all
+ * 512 tiles laid out as 32 columns × 16 rows of 8×8 tiles → 256×128 image.
+ *
+ * Preferred path: our patched fceumm exposes CHR via memory region
+ * `nes_chr` (gathered from VPage[0..7]). That works for both CHR-ROM and
+ * CHR-RAM carts and reflects the *current* state of pattern tables (some
+ * games rewrite CHR-RAM mid-frame). Fallback path: parse the iNES file
+ * on disk for carts where the memory region isn't available.
+ *
+ * @param {import("../../host/index.js").LibretroHost} host
+ * @returns {Promise<{ width: number, height: number, png: Buffer, source: "live"|"ines" }>}
+ */
+export async function snapshotPatternTables(host) {
+  // Read iNES header first to make the CHR-ROM vs CHR-RAM decision deterministic
+  // (rather than guessing from all-zero live reads). iNES byte 5 = chrBanks:
+  //   > 0  → CHR-ROM cart, baked-in tiles never change at runtime → use file.
+  //   = 0  → CHR-RAM cart, tiles are written by the game at runtime → use live.
+  // Agent feedback (2026-05-23): the all-zero heuristic mis-classified a real
+  // CHR-ROM cart as CHR-RAM when the live read happened to return zeros before
+  // the core fully loaded. Reading byte 5 is unambiguous.
+  const { readFile } = await import("node:fs/promises");
+  const status = host.getStatus();
+  let inesBytes = null;
+  if (status.mediaPath) {
+    try {
+      inesBytes = await readFile(status.mediaPath);
+    } catch {
+      // mediaPath may have been a virtual path (loadMediaBytes); fall through.
+    }
+  }
+  const chrBanks = inesBytes && inesBytes.length >= 6 &&
+    inesBytes[0] === 0x4e && inesBytes[1] === 0x45 && inesBytes[2] === 0x53 && inesBytes[3] === 0x1a
+    ? inesBytes[5]
+    : null;
+
+  // CHR-ROM cart: the on-disk CHR is authoritative (it never changes).
+  if (chrBanks !== null && chrBanks > 0 && inesBytes) {
+    const ines = chrFromINes(inesBytes);
+    return { ...ines, source: "ines" };
+  }
+
+  // CHR-RAM cart OR header unavailable (e.g. loaded via bytes): use live region.
+  try {
+    const chr = host.readMemory("nes_chr", 0, 8192);
+    return {
+      width: 256,
+      height: 128,
+      png: renderBothPatternTablesPng(chr),
+      source: "live",
+      hasChr: chrBanks === 0
+        ? null  // CHR-RAM: "hasChr" doesn't really apply; live data is what game wrote
+        : true,
+    };
+  } catch {
+    // Region not exposed by this core (rare; needs the romdev fceumm patch).
+  }
+
+  // Last resort: nothing we can show.
+  throw new Error(
+    "inspectPatternTiles: could not read CHR. " +
+    (status.mediaPath
+      ? "ROM at " + status.mediaPath + " has no valid iNES header and the core didn't expose nes_chr."
+      : "No ROM loaded — call loadMedia or loadMediaBytes first.")
+  );
+}
+
+/**
+ * Decode the CHR bank from an iNES file and render both pattern tables.
+ *
+ * iNES layout:
+ *   bytes 0..15  header (PRG bank count at byte 4, CHR bank count at byte 5)
+ *   bytes 16..   PRG ROM (prgBanks * 16384 bytes)
+ *   then         CHR ROM (chrBanks * 8192 bytes)
+ *
+ * Returns a 256×128 PNG of both 4KB tables side by side. If the cart has
+ * no CHR ROM (CHR-RAM only — chrBanks=0), returns a blank image since
+ * the runtime CHR-RAM isn't accessible to us.
+ *
+ * @param {Uint8Array} ines full iNES file bytes
+ * @returns {{ width: number, height: number, png: Buffer, hasChr: boolean }}
+ */
+export function chrFromINes(ines) {
+  if (ines.length < 16 || ines[0] !== 0x4e || ines[1] !== 0x45 || ines[2] !== 0x53 || ines[3] !== 0x1a) {
+    throw new Error("not a valid iNES file");
+  }
+  const prgBanks = ines[4];
+  const chrBanks = ines[5];
+  const chrOffset = 16 + prgBanks * 16384;
+  if (chrBanks === 0) {
+    // No CHR ROM (CHR-RAM cart). Return a placeholder 256×128 blank image.
+    const blank = renderBothPatternTablesPng(new Uint8Array(8192));
+    return { width: 256, height: 128, png: blank, hasChr: false };
+  }
+  const chr = ines.subarray(chrOffset, chrOffset + 8192);
+  if (chr.length !== 8192) {
+    throw new Error(`expected 8192 bytes of CHR at offset ${chrOffset}, got ${chr.length}`);
+  }
+  return {
+    width: 256,
+    height: 128,
+    png: renderBothPatternTablesPng(new Uint8Array(chr)),
+    hasChr: true,
+  };
+}