romdevtools 0.13.0

package/src/platforms/nes/ppu.js

@@ -0,0 +1,448 @@
+// 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;
+}
+
+/**
+ * Decode one 1KB NES nametable (960 tile indices + 64-byte attribute table)
+ * into structured, ready-to-use data — so an agent reverse-engineering a
+ * screen doesn't have to slice CIRAM and hand-decode the 2-bit-per-16×16-block
+ * attribute format itself.
+ *
+ * The attribute table packs the BG sub-palette (0-3) for each 16×16-pixel
+ * region (= 2×2 tiles): one byte per 32×32 area, four 2-bit quadrants
+ * (bits 0-1 = top-left, 2-3 = top-right, 4-5 = bottom-left, 6-7 = bottom-right).
+ * We expand it to a per-TILE grid so it lines up cell-for-cell with `tiles`.
+ *
+ * @param {Uint8Array} ciram a 1KB (or larger) region; first 1024 bytes are one
+ *   nametable: bytes 0-959 tile indices (32×30), 960-1023 attribute table.
+ * @param {Object} [opts]
+ * @param {number} [opts.which=0] which 1KB nametable when `ciram` holds ≥2.
+ * @param {{x:number,y:number,w:number,h:number}} [opts.region] tile sub-rect to
+ *   return (clipped to 32×30). Omit for the whole nametable.
+ * @returns {{
+ *   width: number, height: number, region: {x,y,w,h},
+ *   tiles: number[][],          // [row][col] tile index
+ *   subPaletteGrid: number[][], // [row][col] BG sub-palette 0-3 (per tile)
+ *   distinctTiles: number[],    // sorted unique tile indices in the region
+ *   attrTableHex: string,       // the raw 64-byte attribute table, for reference
+ * }}
+ */
+export function decodeNametable(ciram, opts = {}) {
+  const which = opts.which ?? 0;
+  const base = which * 0x400;
+  if (ciram.length < base + 1024) {
+    throw new Error(`decodeNametable: need ≥${base + 1024} bytes for nametable ${which}, got ${ciram.length}`);
+  }
+  const nt = ciram.subarray(base, base + 0x400);
+  const attr = nt.subarray(960, 1024); // 64 bytes
+
+  // Per-tile sub-palette: attr byte index = (row>>2)*8 + (col>>2); within it,
+  // quadrant = ((row>>1)&1)*2 + ((col>>1)&1) → shift 0/2/4/6.
+  const subPalAt = (col, row) => {
+    const byte = attr[(row >> 2) * 8 + (col >> 2)] ?? 0;
+    const shift = (((row >> 1) & 1) << 1 | ((col >> 1) & 1)) * 2;
+    return (byte >> shift) & 0x3;
+  };
+
+  // Clip the requested region to the 32×30 visible grid.
+  const rx = Math.max(0, opts.region?.x ?? 0);
+  const ry = Math.max(0, opts.region?.y ?? 0);
+  const rw = Math.min(32 - rx, opts.region?.w ?? 32);
+  const rh = Math.min(30 - ry, opts.region?.h ?? 30);
+
+  const tiles = [];
+  const subPaletteGrid = [];
+  const distinct = new Set();
+  for (let r = 0; r < rh; r++) {
+    const trow = [];
+    const prow = [];
+    for (let c = 0; c < rw; c++) {
+      const col = rx + c, row = ry + r;
+      const t = nt[row * 32 + col];
+      trow.push(t);
+      prow.push(subPalAt(col, row));
+      distinct.add(t);
+    }
+    tiles.push(trow);
+    subPaletteGrid.push(prow);
+  }
+
+  return {
+    width: rw,
+    height: rh,
+    region: { x: rx, y: ry, w: rw, h: rh },
+    tiles,
+    subPaletteGrid,
+    distinctTiles: Array.from(distinct).sort((a, b) => a - b),
+    attrTableHex: Array.from(attr, (b) => b.toString(16).padStart(2, "0")).join(""),
+  };
+}
+
+/**
+ * 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,
+  };
+}

package/src/platforms/pce/MENTAL_MODEL.md

@@ -0,0 +1,98 @@
+# PC Engine / TurboGrafx-16 — mental model
+
+One page. Read once before you write your first PC Engine game. The
+TROUBLESHOOTING.md alongside this file is for when something's broken; this is
+the "what's going on" version.
+
+## Start here — don't write the register pokes from scratch
+
+romdev ships a **hardware helper library** (`src/platforms/pce/lib/c/`:
+`pce_hw.h` + `pce_video.c` + `pce_input.c` + `pce_sound.c`) so you call
+`vce_set_color()`, `vram_write()`, `set_sprite()`, `satb_dma()`, `pce_joy_read()`,
+`psg_tone()` instead of poking VDC/VCE registers by hand. cc65 has **no** sprite
+library, so this lib is how you get pixels on screen.
+
+The fastest way to a working game: **`scaffold({op:'project', platform: "pce", template:
+"sprite_move"})`** (also `music_sfx`, `catch_game`). It drops a complete,
+*building* project — a verified playable example + the helper lib + docs. Read
+the example's `main.c`, then change it. The examples live in `examples/pce/`.
+
+## CPU — HuC6280 (a 65C02 superset)
+
+The HuC6280 is a 65C02 core with extras: a memory-mapping unit (MPR registers),
+a built-in sound chip (PSG), a timer, and block-transfer instructions (`tii`,
+`tia`, etc.). For C development with cc65 you mostly don't touch the MPR — the
+`pce` target's runtime maps the HuCard and 8 KB of work RAM for you.
+
+```
+CPU address space (16-bit, banked via 8 MPRs that map $2000 windows):
+  $0000-$1FFF   work RAM (8 KB) — also the stack ($21xx page)
+  $4000-$BFFF   (mapped HuCard / hardware via MPR)
+  $E000-$FFFF   HuCard ROM (reset/IRQ vectors at $FFF6+)
+```
+
+cc65 links your C `_CODE` into ROM and runs `pce/crt0.s`, which clears `.bss`,
+copies `.data`, sets the stack, runs constructors, then calls `main`.
+
+## Video — HuC6270 VDC + HuC6260 VCE (two chips)
+
+The **HuC6270 VDC** owns 64 KB of VRAM (word-addressed) and the display:
+- A tiled background ("BAT" = Background Attribute Table in VRAM) — there is NO
+  separate nametable region; the map lives in VRAM. Virtual screen size is set
+  by VDC register R9 (MWR).
+- 64 hardware **sprites** via the SATB (Sprite Attribute Table), 16/32 wide ×
+  16/32/64 tall. The SATB is DMA'd from VRAM (source in R19).
+- VDC register **R5 (CR)** is the master switch: bit 7 = BG enable, bit 6 = SPR
+  enable. If both are clear you see only the backdrop color. `background({view:'renderState'})`
+  reads this and tells you.
+
+The **HuC6260 VCE** owns color: a 512-entry table (256 BG + 256 SPR sub-palette
+slots), each a **9-bit GRB** value (`0bGGG_RRR_BBB`, 3 bits per channel). Slot 0
+of every 16-color sub-palette is transparent/backdrop. `palette({source:'live'})` decodes it.
+
+## Frame heartbeat
+
+The VDC raises VBlank once per frame (~60 Hz NTSC). cc65 gives you `waitvsync()`
+(libsrc/pce/waitvsync.s) to sync to it — update VRAM during VBlank to avoid
+tearing. There is no NMI; the VDC IRQ (R5 bits 2-3 enable raster/vblank IRQ)
+drives interrupt-based code.
+
+## Build pipeline
+
+`build({output:'rom', platform: "pce"})` → cc65 (C89) → ca65 → ld65 with `pce.cfg`
+→ a HuCard `.pce` image. The fastest visible output is cc65's **conio** text
+library (`#include <conio.h>`): `clrscr()` inits the VDC+VCE and uploads a font,
+`cputs()`/`gotoxy()` draw text. The `hello_pce.c` starter snippet does exactly
+this.
+
+## The one trap that will bite you
+
+cc65's `pce/crt0.s` clears `.bss` with a block instruction sized `__BSS_SIZE__-1`.
+If your program has **no globals/statics**, `__BSS_SIZE__` is 0, the `-1`
+underflows, and you get a **"Range error in pce/crt0.s"** at link AND a black
+screen. Keep at least one (2+ byte) global. See TROUBLESHOOTING.md.
+
+## Art + input
+
+- `encodeArt({stage:'tiles', platform: "pce"})` — PNG → 4bpp HuC6270 tiles (the
+  "planar-pairs" layout: 32 B/tile, 16 B plane 0+1 then 16 B plane 2+3). Returns
+  a suggested 16-color palette too. DMA the bytes to your VRAM pattern base.
+- `input({op:'layout', platform: "pce"})` — the 2-button pad + how the joyport
+  scan works. **Driving input over MCP:** geargrafx maps `input({op:'set'})` straight
+  through (verified live, no inversion): `{a}`→button I, `{b}`→button II,
+  `{start}`→Run, `{select}`→Select; spatial east→I, west→II. So
+  `input({op:'set', a: true})` presses button I as expected — unlike the
+  genesis_plus_gx platforms, there's no surprise here.
+
+## Debugging tools
+
+- `cpu({op:'read'})` — HuC6280 PC/A/X/Y/S/P + flags + timer/IRQ state.
+- `background({view:'renderState'})` — VDC R5 screen-enable, BG scroll, SATB source.
+- `palette({source:'live'})` — VCE 512-entry 9-bit GRB (area:'bg'|'sprite').
+- `sprites({op:'inspect'})` — SATB 64 sprites (x/y/tile/palette/size/flip).
+- `symbols({op:'map'})` — where cc65 placed your variables (after buildSourceWithDebug).
+- `audioDebug({op:'inspect', chip: "pce"})` — the HuC6280 PSG: 6 wavetable channels
+  (per-channel freq/volume/wave; channels 4-5 can also do noise) + main amplitude
+  + LFO.
+- `memory({op:'read'})` regions: `pce_vdc_vram`, `pce_vdc_satb`, `pce_vdc_regs`,
+  `pce_vce_palette`, `pce_cpu_regs`, `pce_psg_regs`.

package/src/platforms/pce/TROUBLESHOOTING.md

@@ -0,0 +1,54 @@
+# PC Engine — troubleshooting (symptom → cause → fix)
+
+Read this when something's broken. For the "how it works" overview, read
+MENTAL_MODEL.md first.
+
+## Black screen + "Range error in module 'pce/crt0.s'" at link
+
+**THE most common PCE trap.** cc65's crt0 clears `.bss` with a block-copy sized
+`__BSS_SIZE__ - 1`. With NO globals/statics, `__BSS_SIZE__` is 0 → the `- 1`
+underflows → ld65 throws the range error AND the ROM boots to a black screen
+(the VDC never initializes, even if you call conio).
+
+**Fix:** add at least one global/static variable so `.bss` is non-empty. A
+1-byte `.bss` uploads only a partial conio font on some builds; use **2+ bytes**
+to be safe. The `hello_pce.c` starter keeps a `static unsigned char _keep_bss[4];`
+for exactly this reason — don't delete it until you have real globals.
+
+## Black screen, no link error
+
+The HuC6270 VDC's display is OFF. Call `background({view:'renderState'})`:
+- `bgEnable:false, spEnable:false` → VDC register R5 (CR) bits 7/6 are clear.
+  If you're using conio, `clrscr()` should enable it — make sure you called it
+  and that the program didn't crash before reaching it (check `cpu({op:'read'}).pc`).
+- Using raw VDC writes? Set R5 bit 7 (BG) and/or bit 6 (SPR) and load a BAT +
+  tiles into VRAM first.
+
+## Text/tiles show but colors are wrong
+
+The HuC6260 VCE palette is **9-bit GRB** (`0bGGG_RRR_BBB`), NOT RGB and NOT the
+Genesis BGR layout. Each channel is 3 bits (0-7). `palette({source:'live'})` decodes it
+correctly — compare its `hex` values against what you wrote. Remember slot 0 of
+each 16-color sub-palette is transparent.
+
+## Sprites invisible
+
+- `sprites({op:'inspect'})` shows `visible:false` for all → they're parked off-screen
+  (Y = -64 means the SATB entry is zeroed; the VDC's Y is stored +64).
+- Sprites present but not drawn → VDC R5 bit 6 (SPR enable) is clear, or the
+  SATB hasn't been DMA'd from VRAM (the VDC copies it from the address in R19).
+- Wrong pattern → the SATB pattern field is in **16×16 cells**; `pattern << 6`
+  is the VRAM word address.
+
+## Program builds but PC is stuck / garbage
+
+`cpu({op:'read'})` shows the HuC6280 PC. If it's spinning in a tight range you're
+probably in your intended idle loop. If it's in ROM vector territory unexpectedly,
+you likely hit a BRK or an unhandled IRQ — check that you didn't enable a VDC IRQ
+(R5 bits 2-3) without an ISR.
+
+## conio prints nothing
+
+`clrscr()` must run before `cputs()` (it inits the font + VDC). Also confirm
+`.bss` is non-empty (see the first entry) — a broken crt0 means conio's font
+upload never happened.

package/src/platforms/pce/UPSTREAM_SOURCES.md

@@ -0,0 +1,38 @@
+# PC Engine — upstream sources
+
+Pointers to the bundled library source + upstream repos, for when romdev's
+examples aren't enough and you need ground truth.
+
+## Toolchain — cc65 (HuC6280 / `pce` target)
+
+- Upstream: https://github.com/cc65/cc65 (the `pce` target).
+- Bundled in romdev-toolchain-cc65. The PCE runtime lives in cc65's
+  `libsrc/pce/` — `crt0.s` (startup), `vdc.s` / `vce.s` (video helpers),
+  `waitvsync.s`, `psg.s` (sound), `color.s`, plus the generic conio
+  (`libsrc/cbm`-style `clrscr.s` / `cputc.s` / `gotoxy.s` adapted for the VDC).
+- Headers: `include/pce.h` (hardware defines, joypad masks, colors),
+  `include/conio.h` (text API). Linker config: `cfg/pce.cfg` (the HuCard memory
+  layout: ZP, MAIN RAM at $2200, ROM banks).
+- cc65 is **C89** — declare all locals at the top of a block, no `//` comments
+  in strict mode, no variadic-heavy stdio.
+
+## Emulator core — Geargrafx
+
+- Upstream: https://github.com/drhelius/Geargrafx (by Ignacio Sánchez / drhelius,
+  GPL-3.0). A clean, accurate PCE/TG-16 emulator with separate HuC6280 / HuC6270
+  (×2) / HuC6260 / PSG classes.
+- romdev pins a specific commit (see scripts/versions.json) and applies
+  `scripts/patches/geargrafx-romdev-memory-regions.patch` to expose the VDC
+  VRAM/SATB/regs, VCE palette, and HuC6280 CPU snapshot via
+  `retro_get_memory_data` for the inspect tools.
+- Ground-truth files (in the Geargrafx source): `src/huc6270.cpp/.h` (VDC + the
+  actual sprite renderer at ~line 803 — the canonical SATB format), `src/huc6260.cpp`
+  (the 9-bit GRB → RGB conversion at ~line 74), `src/huc6280.h` (CPU state struct).
+
+## Hardware references
+
+- The PC Engine VDC (HuC6270) and VCE (HuC6260) are documented in the Charles
+  MacDonald / pcedev community docs. The register numbers and color format used
+  by romdev's adapters match Geargrafx's implementation exactly (see above).
+- Sprite SATB, BAT (background map), and palette layouts are summarized in this
+  package's MENTAL_MODEL.md.