romdev-mcp 0.1.1

package/src/platforms/common/metasprite.js

@@ -0,0 +1,89 @@
+// Public meta-sprite entry points: capture from a live host, and re-render
+// from saved files. All platform specifics live in metasprite-adapters.js
+// (live decode) + the tile decoders below (saved-file decode).
+
+import { buildAdapter } from "./metasprite-adapters.js";
+import { captureFromAdapter, renderSavedMetaSprite, clusterSprites } from "./metasprite-core.js";
+
+/** Capture a meta-sprite from the current frame on `host` for `platform`. */
+export async function captureMetaSprite(host, platform, opts = {}) {
+  const adapter = await buildAdapter(host, platform);
+  return captureFromAdapter(adapter, opts);
+}
+
+/** Cluster the on-screen sprites into likely objects. */
+export async function groupVisibleSprites(host, platform, opts = {}) {
+  const adapter = await buildAdapter(host, platform);
+  return clusterSprites(adapter.sprites, opts);
+}
+
+// ---- saved-file re-render ----
+// Decode tiles.bin back into 8x8 index grids using the layout's platform +
+// bpp (inverse of the encoders in metasprite-adapters.js), then re-render
+// via the same core path used at capture time.
+
+function decodeTilesBin(tiles, platform, bpp) {
+  const grids = [];
+  const tileBytes = bpp === 4 ? 32 : 16;
+  const count = Math.floor(tiles.length / tileBytes);
+  for (let t = 0; t < count; t++) {
+    const base = t * tileBytes;
+    const g = Array.from({ length: 8 }, () => new Array(8).fill(0));
+    if (platform === "nes") {
+      // 2bpp planar: plane0 bytes 0-7, plane1 bytes 8-15
+      for (let y = 0; y < 8; y++) { const p0 = tiles[base + y], p1 = tiles[base + 8 + y]; for (let x = 0; x < 8; x++) { const b = 7 - x; g[y][x] = ((p0 >> b) & 1) | (((p1 >> b) & 1) << 1); } }
+    } else if (platform === "gb" || platform === "gbc") {
+      // 2bpp interleaved: per row [lo,hi]
+      for (let y = 0; y < 8; y++) { const lo = tiles[base + y * 2], hi = tiles[base + y * 2 + 1]; for (let x = 0; x < 8; x++) { const b = 7 - x; g[y][x] = ((lo >> b) & 1) | (((hi >> b) & 1) << 1); } }
+    } else if (platform === "genesis") {
+      // 4bpp packed: high nibble = left pixel
+      for (let y = 0; y < 8; y++) for (let half = 0; half < 4; half++) { const byte = tiles[base + y * 4 + half]; g[y][half * 2] = (byte >> 4) & 0xF; g[y][half * 2 + 1] = byte & 0xF; }
+    } else if (platform === "sms" || platform === "gg") {
+      // 4bpp interleaved: per row [p0,p1,p2,p3]
+      for (let y = 0; y < 8; y++) { const p0 = tiles[base + y * 4], p1 = tiles[base + y * 4 + 1], p2 = tiles[base + y * 4 + 2], p3 = tiles[base + y * 4 + 3]; for (let x = 0; x < 8; x++) { const b = 7 - x; g[y][x] = ((p0 >> b) & 1) | (((p1 >> b) & 1) << 1) | (((p2 >> b) & 1) << 2) | (((p3 >> b) & 1) << 3); } }
+    } else { // snes: 4bpp planar-pairs
+      for (let y = 0; y < 8; y++) { const p0 = tiles[base + y * 2], p1 = tiles[base + y * 2 + 1], p2 = tiles[base + 16 + y * 2], p3 = tiles[base + 16 + y * 2 + 1]; for (let x = 0; x < 8; x++) { const b = 7 - x; g[y][x] = ((p0 >> b) & 1) | (((p1 >> b) & 1) << 1) | (((p2 >> b) & 1) << 2) | (((p3 >> b) & 1) << 3); } }
+    }
+    grids.push(g);
+  }
+  return grids;
+}
+
+/**
+ * Re-render a saved meta-sprite (tiles.bin + layout.json) to a PNG. The
+ * palette comes from the layout's `palettes` (hex strings), so palette.bin
+ * isn't strictly needed for the preview.
+ * @param {Uint8Array} tiles
+ * @param {object} layout
+ */
+export function renderSaved(tiles, layout) {
+  const bpp = layout.bpp ?? (["genesis", "snes", "sms", "gg"].includes(layout.platform) ? 4 : 2);
+  const exportTiles = decodeTilesBin(tiles, layout.platform, bpp);
+  // Palette: parse hex strings from layout.palettes into rgb arrays keyed by
+  // the same palette index the pieces reference.
+  const palMap = {};
+  for (const [k, hexes] of Object.entries(layout.palettes || {})) {
+    palMap[k] = hexes.map((h) => {
+      const m = /^#?([0-9a-fA-F]{6})$/.exec(h); if (!m) return [0, 0, 0];
+      const n = parseInt(m[1], 16); return [(n >> 16) & 0xFF, (n >> 8) & 0xFF, n & 0xFF];
+    });
+  }
+  // A minimal adapter the core's renderer can use: cell order from layout +
+  // a palette lookup. Reuse the same cell-order rules.
+  const colMajor = !!layout.tileColumnMajor;
+  const order = colMajor
+    ? (w, h) => { const o = []; for (let c = 0; c < w; c++) for (let r = 0; r < h; r++) o.push(c * h + r); return o; }
+    : (w, h) => { const o = []; for (let r = 0; r < h; r++) for (let c = 0; c < w; c++) o.push(r * w + c); return o; };
+  const pos = colMajor
+    ? (w, h) => { const p = []; for (let c = 0; c < w; c++) for (let r = 0; r < h; r++) p.push({ col: c, row: r }); return p; }
+    : (w, h) => { const p = []; for (let r = 0; r < h; r++) for (let c = 0; c < w; c++) p.push({ col: c, row: r }); return p; };
+  const adapter = {
+    platform: layout.platform,
+    cellTileOrder: order,
+    cellGridPositions: pos,
+    getPaletteRgb: (p) => palMap[String(p)] || palMap[Object.keys(palMap)[0]] || [[0, 0, 0]],
+  };
+  return renderSavedMetaSprite({ adapter, layout, exportTiles });
+}
+
+export { emitMetaSpriteCode } from "./metasprite-codegen.js";

package/src/platforms/common/platform-palette.js

@@ -0,0 +1,137 @@
+// platform-palette.js — single accessor for every platform's master RGB palette.
+//
+// The per-platform palette PNG generators (nesPalettePng, snesPalettePng, ...)
+// each hardcoded their RGB list inline. Lospec / hex / indexed-PNG validation
+// all need that same list. Extracted here once.
+//
+// Returns an array of [r, g, b] (0..255 each). One entry per color the platform
+// can actually display from its master palette.
+
+import { NES_PALETTE, nesIndexToRgb } from "../nes/palette.js";
+import { DMG_PALETTE } from "../gb/ppu.js";
+import { C64_PALETTE } from "../c64/vic.js";
+import { A78_PALETTE } from "../atari7800/maria.js";
+import { NTSC_PALETTE } from "../atari2600/tia.js";
+
+/* ── SNES master swatch — 16 well-spaced colors (matches snesPalettePng) ── */
+const SNES_SWATCH = [
+  [0, 0, 0], [128, 128, 128], [255, 255, 255], [128, 0, 0],
+  [255, 0, 0], [255, 128, 0], [255, 255, 0], [0, 128, 0],
+  [0, 255, 0], [0, 128, 128], [0, 255, 255], [0, 0, 128],
+  [0, 0, 255], [128, 0, 128], [255, 0, 255], [128, 64, 0],
+];
+
+/* ── Genesis: full 9-bit VDP gamut (512 colors), 3 bits each channel ── */
+function genesisRgb() {
+  const expand = (n3) => (n3 << 5) | (n3 << 2) | (n3 >> 1);
+  const out = [];
+  for (let i = 0; i < 512; i++) {
+    const r = expand(i & 0x7);
+    const g = expand((i >> 3) & 0x7);
+    const b = expand((i >> 6) & 0x7);
+    out.push([r, g, b]);
+  }
+  return out;
+}
+
+/* ── SMS: full 6-bit gamut (64 colors), 2 bits per channel ── */
+function smsRgb() {
+  const out = [];
+  for (let i = 0; i < 64; i++) {
+    const r2 = i & 0x3;
+    const g2 = (i >> 2) & 0x3;
+    const b2 = (i >> 4) & 0x3;
+    // expand 2 bits → 8 bits: 0,85,170,255
+    const expand = (n2) => (n2 * 85);
+    out.push([expand(r2), expand(g2), expand(b2)]);
+  }
+  return out;
+}
+
+/* ── GG: full 12-bit gamut (4096 colors), 4 bits per channel ── */
+function ggRgb() {
+  const out = [];
+  for (let i = 0; i < 4096; i++) {
+    const r4 = i & 0xF;
+    const g4 = (i >> 4) & 0xF;
+    const b4 = (i >> 8) & 0xF;
+    const expand = (n4) => (n4 << 4) | n4;
+    out.push([expand(r4), expand(g4), expand(b4)]);
+  }
+  return out;
+}
+
+/* ── NES: 53 usable colors (skipping the 11 "black duplicates") ── */
+function nesRgb() {
+  const SKIP = new Set([0x0d, 0x0e, 0x1d, 0x1e, 0x1f, 0x2d, 0x2e, 0x2f, 0x3d, 0x3e, 0x3f]);
+  const out = [];
+  // Put canonical black ($0F) first to match nesPalettePng().
+  out.push(nesIndexToRgb(0x0f));
+  for (let i = 0; i < 64; i++) {
+    if (i === 0x0f || SKIP.has(i)) continue;
+    out.push(NES_PALETTE[i]);
+  }
+  return out;
+}
+
+/**
+ * Return the platform's master RGB palette as an array of [r,g,b].
+ * The list is the same set of colors the platform's `*PalettePng()`
+ * generator produces (in the same order, so PLTE indices line up).
+ *
+ * @param {string} platform
+ * @returns {[number, number, number][]}
+ */
+export function getPlatformPaletteRgb(platform) {
+  switch (platform) {
+    case "nes":        return nesRgb();
+    case "gb":
+    case "gbc":        return [...DMG_PALETTE];     // 4 shades
+    case "snes":       return SNES_SWATCH;
+    case "genesis":    return genesisRgb();
+    case "sms":        return smsRgb();
+    case "gg":         return ggRgb();
+    case "c64":        return [...C64_PALETTE];     // 16 colors
+    case "atari2600":  return [...NTSC_PALETTE];    // 128 NTSC entries
+    case "atari7800":  return [...A78_PALETTE];     // 256 entries
+    default:
+      throw new Error(`getPlatformPaletteRgb: no master palette defined for platform '${platform}'`);
+  }
+}
+
+/**
+ * Check if a color is within tolerance of any palette entry.
+ * Used by indexed-PNG validation — sRGB gamma drift can shift exported
+ * pixels by 1-2 per channel even when the artist used the right swatch.
+ *
+ * @param {[number,number,number][]} palette
+ * @param {number} r @param {number} g @param {number} b
+ * @param {number} [tolerance=0]  max per-channel delta
+ * @returns {boolean}
+ */
+export function paletteContains(palette, r, g, b, tolerance = 0) {
+  for (const [pr, pg, pb] of palette) {
+    if (Math.abs(pr - r) <= tolerance &&
+        Math.abs(pg - g) <= tolerance &&
+        Math.abs(pb - b) <= tolerance) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Format an RGB triple as "#RRGGBB" (uppercase hex with leading hash).
+ */
+export function rgbHex(r, g, b) {
+  const h = (n) => n.toString(16).toUpperCase().padStart(2, "0");
+  return `#${h(r)}${h(g)}${h(b)}`;
+}
+
+/**
+ * Format an RGB triple as "rrggbb" (lowercase hex, no hash) — Lospec style.
+ */
+export function rgbHexLospec(r, g, b) {
+  const h = (n) => n.toString(16).padStart(2, "0");
+  return `${h(r)}${h(g)}${h(b)}`;
+}

package/src/platforms/common/registers.js

@@ -0,0 +1,329 @@
+// Hardware register lookup tables for disassembly annotation.
+//
+// Each platform's table maps an address (16- or 24-bit, hex) to a register
+// shorthand like "PPUCTRL". The disassembler walks asm output line-by-line
+// and appends `  ; <REG>` whenever an operand resolves to one of these.
+//
+// Tables are intentionally compact — register *names* only, not full
+// descriptions. Agents look up details via the existing input-layout /
+// platform-tools when they need bit-level meaning.
+
+/** @typedef {Record<number, string>} RegisterTable */
+
+/** @type {RegisterTable} */
+export const NES_REGISTERS = {
+  // PPU $2000-$2007 + open-bus mirrors.
+  0x2000: "PPUCTRL",
+  0x2001: "PPUMASK",
+  0x2002: "PPUSTATUS",
+  0x2003: "OAMADDR",
+  0x2004: "OAMDATA",
+  0x2005: "PPUSCROLL",
+  0x2006: "PPUADDR",
+  0x2007: "PPUDATA",
+  // APU $4000-$4017
+  0x4000: "SQ1_VOL",
+  0x4001: "SQ1_SWEEP",
+  0x4002: "SQ1_LO",
+  0x4003: "SQ1_HI",
+  0x4004: "SQ2_VOL",
+  0x4005: "SQ2_SWEEP",
+  0x4006: "SQ2_LO",
+  0x4007: "SQ2_HI",
+  0x4008: "TRI_LINEAR",
+  0x400A: "TRI_LO",
+  0x400B: "TRI_HI",
+  0x400C: "NOISE_VOL",
+  0x400E: "NOISE_LO",
+  0x400F: "NOISE_HI",
+  0x4010: "DMC_FREQ",
+  0x4011: "DMC_RAW",
+  0x4012: "DMC_START",
+  0x4013: "DMC_LEN",
+  0x4014: "OAMDMA",
+  0x4015: "SND_CHN",
+  0x4016: "JOY1",
+  0x4017: "JOY2",
+};
+
+/** @type {RegisterTable} */
+export const SNES_REGISTERS = {
+  // PPU regs $2100-$213F
+  0x2100: "INIDISP", 0x2101: "OBSEL", 0x2102: "OAMADDL", 0x2103: "OAMADDH",
+  0x2104: "OAMDATA", 0x2105: "BGMODE", 0x2106: "MOSAIC",
+  0x2107: "BG1SC", 0x2108: "BG2SC", 0x2109: "BG3SC", 0x210A: "BG4SC",
+  0x210B: "BG12NBA", 0x210C: "BG34NBA",
+  0x210D: "BG1HOFS", 0x210E: "BG1VOFS",
+  0x210F: "BG2HOFS", 0x2110: "BG2VOFS",
+  0x2111: "BG3HOFS", 0x2112: "BG3VOFS",
+  0x2113: "BG4HOFS", 0x2114: "BG4VOFS",
+  0x2115: "VMAIN", 0x2116: "VMADDL", 0x2117: "VMADDH",
+  0x2118: "VMDATAL", 0x2119: "VMDATAH",
+  0x211A: "M7SEL", 0x211B: "M7A", 0x211C: "M7B", 0x211D: "M7C", 0x211E: "M7D",
+  0x211F: "M7X", 0x2120: "M7Y",
+  0x2121: "CGADD", 0x2122: "CGDATA",
+  0x2123: "W12SEL", 0x2124: "W34SEL", 0x2125: "WOBJSEL",
+  0x2126: "WH0", 0x2127: "WH1", 0x2128: "WH2", 0x2129: "WH3",
+  0x212A: "WBGLOG", 0x212B: "WOBJLOG",
+  0x212C: "TM", 0x212D: "TS", 0x212E: "TMW", 0x212F: "TSW",
+  0x2130: "CGWSEL", 0x2131: "CGADSUB", 0x2132: "COLDATA", 0x2133: "SETINI",
+  0x2134: "MPYL", 0x2135: "MPYM", 0x2136: "MPYH",
+  0x2137: "SLHV", 0x2138: "OAMDATAREAD", 0x2139: "VMDATALREAD", 0x213A: "VMDATAHREAD",
+  0x213B: "CGDATAREAD", 0x213C: "OPHCT", 0x213D: "OPVCT",
+  0x213E: "STAT77", 0x213F: "STAT78",
+  // APU I/O
+  0x2140: "APUIO0", 0x2141: "APUIO1", 0x2142: "APUIO2", 0x2143: "APUIO3",
+  // WRAM access ports
+  0x2180: "WMDATA", 0x2181: "WMADDL", 0x2182: "WMADDM", 0x2183: "WMADDH",
+  // CPU regs $4200-$420D
+  0x4200: "NMITIMEN", 0x4201: "WRIO", 0x4202: "WRMPYA", 0x4203: "WRMPYB",
+  0x4204: "WRDIVL", 0x4205: "WRDIVH", 0x4206: "WRDIVB",
+  0x4207: "HTIMEL", 0x4208: "HTIMEH", 0x4209: "VTIMEL", 0x420A: "VTIMEH",
+  0x420B: "MDMAEN", 0x420C: "HDMAEN", 0x420D: "MEMSEL",
+  0x4210: "RDNMI", 0x4211: "TIMEUP", 0x4212: "HVBJOY", 0x4213: "RDIO",
+  0x4214: "RDDIVL", 0x4215: "RDDIVH", 0x4216: "RDMPYL", 0x4217: "RDMPYH",
+  0x4218: "JOY1L", 0x4219: "JOY1H", 0x421A: "JOY2L", 0x421B: "JOY2H",
+  0x421C: "JOY3L", 0x421D: "JOY3H", 0x421E: "JOY4L", 0x421F: "JOY4H",
+  // DMA channel registers $4300-$437F (8 channels × $10 each)
+  // We tag the channel-0 registers; agents who care about other channels
+  // will see "DMAPx" stride patterns and infer.
+  0x4300: "DMAP0", 0x4301: "BBAD0",
+  0x4302: "A1T0L", 0x4303: "A1T0H", 0x4304: "A1B0",
+  0x4305: "DAS0L", 0x4306: "DAS0H", 0x4307: "DAS0B",
+  0x4308: "A2A0L", 0x4309: "A2A0H", 0x430A: "NTRL0",
+};
+
+/** @type {RegisterTable} */
+export const GENESIS_REGISTERS = {
+  // VDP control / data ports
+  0xC00000: "VDP_DATA", 0xC00002: "VDP_DATA",
+  0xC00004: "VDP_CTRL", 0xC00006: "VDP_CTRL",
+  0xC00008: "VDP_HVCOUNTER",
+  0xC00011: "PSG_OUT",
+  // YM2612 (SN76489 PSG via $C00011; YM2612 at $A04000)
+  0xA04000: "YM2612_A0", 0xA04001: "YM2612_D0",
+  0xA04002: "YM2612_A1", 0xA04003: "YM2612_D1",
+  // I/O regs $A10000-$A1001F
+  0xA10001: "VERSION",
+  0xA10003: "DATA1", 0xA10005: "DATA2",
+  0xA10009: "CTRL1", 0xA1000B: "CTRL2",
+  // Z80 bus + reset
+  0xA11100: "Z80_BUSREQ",
+  0xA11200: "Z80_RESET",
+};
+
+/** @type {RegisterTable} */
+export const GB_REGISTERS = {
+  // CPU + system regs $FF00-$FF7F
+  0xFF00: "P1_JOYP",
+  0xFF01: "SB", 0xFF02: "SC",
+  0xFF04: "DIV", 0xFF05: "TIMA", 0xFF06: "TMA", 0xFF07: "TAC",
+  0xFF0F: "IF",
+  // APU
+  0xFF10: "NR10", 0xFF11: "NR11", 0xFF12: "NR12", 0xFF13: "NR13", 0xFF14: "NR14",
+  0xFF16: "NR21", 0xFF17: "NR22", 0xFF18: "NR23", 0xFF19: "NR24",
+  0xFF1A: "NR30", 0xFF1B: "NR31", 0xFF1C: "NR32", 0xFF1D: "NR33", 0xFF1E: "NR34",
+  0xFF20: "NR41", 0xFF21: "NR42", 0xFF22: "NR43", 0xFF23: "NR44",
+  0xFF24: "NR50", 0xFF25: "NR51", 0xFF26: "NR52",
+  // PPU
+  0xFF40: "LCDC", 0xFF41: "STAT",
+  0xFF42: "SCY", 0xFF43: "SCX",
+  0xFF44: "LY", 0xFF45: "LYC",
+  0xFF46: "DMA",
+  0xFF47: "BGP", 0xFF48: "OBP0", 0xFF49: "OBP1",
+  0xFF4A: "WY", 0xFF4B: "WX",
+  // GBC extras
+  0xFF4D: "KEY1", 0xFF4F: "VBK",
+  0xFF51: "HDMA1", 0xFF52: "HDMA2", 0xFF53: "HDMA3", 0xFF54: "HDMA4", 0xFF55: "HDMA5",
+  0xFF56: "RP",
+  0xFF68: "BCPS", 0xFF69: "BCPD", 0xFF6A: "OCPS", 0xFF6B: "OCPD",
+  0xFF70: "SVBK",
+  // Interrupt enable
+  0xFFFF: "IE",
+};
+
+/**
+ * SMS / Game Gear I/O ports + VDP. The Z80 sees these via IN/OUT
+ * instructions, not memory-mapped reads, but disassemblers commonly
+ * show the port number as an immediate — `out ($BE),a` etc — so
+ * annotating those operands is what helps.
+ *
+ * SMS uses 8-bit ports; we annotate on 8-bit hits. Code that does
+ * `out ($BE),a` should pick up `; VDP_DATA`.
+ *
+ * Key: SMS VDP register *numbers* (0-10) are NOT memory addresses —
+ * the agent writes them via VDP_CTRL. We annotate the VDP ports
+ * ($BE/$BF) and the I/O ports ($DC/$DD joypad, $3E/$3F memory control,
+ * $7E/$7F PSG/V-counter, $C0-$C1 GG-extras).
+ *
+ * @type {RegisterTable}
+ */
+export const SMS_REGISTERS = {
+  // VDP
+  0x00BE: "VDP_DATA",
+  0x00BF: "VDP_CTRL",
+  // PSG / V counter / H counter
+  0x007E: "V_COUNTER",  // read
+  0x007F: "H_COUNTER",  // read; same port writes PSG (overloaded)
+  // Joypad
+  0x00DC: "IO_PORT_A",  // P1 buttons + P2 D-pad
+  0x00DD: "IO_PORT_B",  // P2 buttons + reset/cart
+  // Memory + cartridge control
+  0x003E: "MEMORY_CTRL",
+  0x003F: "IO_CTRL",
+  // Game Gear extras ($00-$06 + $C0..)
+  0x0000: "GG_INPUT",   // GG: start button + region
+  0x0001: "GG_OUTPUT",
+  0x0002: "GG_DATA_DIR",
+  0x0003: "GG_TX_DATA",
+  0x0004: "GG_RX_DATA",
+  0x0005: "GG_SERIAL_CTRL",
+  0x0006: "GG_PSG_STEREO",
+  // SMS BIOS / control mirrors (some games hit these)
+  0x00F2: "FM_DETECTION",   // Japanese SMS only
+};
+
+/**
+ * Atari 2600 (TIA + RIOT). Write-side TIA registers $00-$2C, read-side
+ * TIA registers $30-$3D, and RIOT registers $280-$297. Most popular
+ * names per the dasm convention.
+ *
+ * @type {RegisterTable}
+ */
+export const ATARI2600_REGISTERS = {
+  // TIA write regs $00-$2C
+  0x00: "VSYNC",     0x01: "VBLANK",    0x02: "WSYNC",     0x03: "RSYNC",
+  0x04: "NUSIZ0",    0x05: "NUSIZ1",    0x06: "COLUP0",    0x07: "COLUP1",
+  0x08: "COLUPF",    0x09: "COLUBK",    0x0A: "CTRLPF",    0x0B: "REFP0",
+  0x0C: "REFP1",     0x0D: "PF0",       0x0E: "PF1",       0x0F: "PF2",
+  0x10: "RESP0",     0x11: "RESP1",     0x12: "RESM0",     0x13: "RESM1",
+  0x14: "RESBL",     0x15: "AUDC0",     0x16: "AUDC1",     0x17: "AUDF0",
+  0x18: "AUDF1",     0x19: "AUDV0",     0x1A: "AUDV1",     0x1B: "GRP0",
+  0x1C: "GRP1",      0x1D: "ENAM0",     0x1E: "ENAM1",     0x1F: "ENABL",
+  0x20: "HMP0",      0x21: "HMP1",      0x22: "HMM0",      0x23: "HMM1",
+  0x24: "HMBL",      0x25: "VDELP0",    0x26: "VDELP1",    0x27: "VDELBL",
+  0x28: "RESMP0",    0x29: "RESMP1",    0x2A: "HMOVE",     0x2B: "HMCLR",
+  0x2C: "CXCLR",
+  // TIA read regs $30-$3D
+  0x30: "CXM0P",     0x31: "CXM1P",     0x32: "CXP0FB",    0x33: "CXP1FB",
+  0x34: "CXM0FB",    0x35: "CXM1FB",    0x36: "CXBLPF",    0x37: "CXPPMM",
+  0x38: "INPT0",     0x39: "INPT1",     0x3A: "INPT2",     0x3B: "INPT3",
+  0x3C: "INPT4",     0x3D: "INPT5",
+  // RIOT regs $280-$297
+  0x0280: "SWCHA",   0x0281: "SWACNT",  0x0282: "SWCHB",   0x0283: "SWBCNT",
+  0x0284: "INTIM",   0x0285: "INSTAT",
+  0x0294: "TIM1T",   0x0295: "TIM8T",   0x0296: "TIM64T",  0x0297: "T1024T",
+};
+
+/**
+ * Atari 7800 (MARIA + TIA-audio + RIOT). Memory map differs from 2600 —
+ * registers live at the bottom of the 6502 address space.
+ *
+ * @type {RegisterTable}
+ */
+export const ATARI7800_REGISTERS = {
+  // TIA audio regs (subset, $15-$1A — overlap with 2600 names)
+  0x15: "AUDC0",     0x16: "AUDC1",     0x17: "AUDF0",     0x18: "AUDF1",
+  0x19: "AUDV0",     0x1A: "AUDV1",
+  // MARIA regs $20-$3F
+  0x20: "BACKGRND",
+  0x21: "P0C1",      0x22: "P0C2",      0x23: "P0C3",
+  0x25: "WSYNC",
+  0x26: "P1C1",      0x27: "P1C2",      0x28: "P1C3",
+  0x29: "MSTAT",
+  0x2A: "P2C1",      0x2B: "P2C2",      0x2C: "P2C3",
+  0x2E: "P3C1",      0x2F: "P3C2",      0x30: "P3C3",
+  0x32: "P4C1",      0x33: "P4C2",      0x34: "P4C3",
+  0x36: "P5C1",      0x37: "P5C2",      0x38: "P5C3",
+  0x3A: "P6C1",      0x3B: "P6C2",      0x3C: "P6C3",
+  0x3E: "P7C1",      0x3F: "P7C2",      // P7C3 lives at $40 in some refs
+  // DPP (display-list pointer) lives at $84/$85
+  0x84: "DPPH",      0x85: "DPPL",
+  0x87: "CHARBASE",
+  0x88: "OFFSET",
+  // MARIA control reg
+  0x3C: "CTRL",      // overlaps with P6C3 — convention varies; tag both
+  // RIOT (6532) regs at $280
+  0x0280: "SWCHA",   0x0281: "SWACNT",  0x0282: "SWCHB",   0x0283: "SWBCNT",
+  0x0284: "INTIM",
+};
+
+/**
+ * Commodore 64 register table — VIC-II ($D000-$D02E), SID ($D400-$D41C),
+ * CIA1 ($DC00-$DC0F), CIA2 ($DD00-$DD0F), plus the 6510 IO ports at $00/$01.
+ * @type {RegisterTable}
+ */
+export const C64_REGISTERS = {
+  // 6510 internal I/O ports
+  0x0000: "D6510",     0x0001: "R6510",
+  // VIC-II $D000-$D02E
+  0xD000: "SP0X",      0xD001: "SP0Y",      0xD002: "SP1X",      0xD003: "SP1Y",
+  0xD004: "SP2X",      0xD005: "SP2Y",      0xD006: "SP3X",      0xD007: "SP3Y",
+  0xD008: "SP4X",      0xD009: "SP4Y",      0xD00A: "SP5X",      0xD00B: "SP5Y",
+  0xD00C: "SP6X",      0xD00D: "SP6Y",      0xD00E: "SP7X",      0xD00F: "SP7Y",
+  0xD010: "MSIGX",     // sprite X bit-8s
+  0xD011: "SCROLY",    // control reg 1
+  0xD012: "RASTER",
+  0xD013: "LPENX",     0xD014: "LPENY",
+  0xD015: "SPENA",     // sprite enable
+  0xD016: "SCROLX",    // control reg 2
+  0xD017: "YXPAND",
+  0xD018: "VMCSB",     // memory pointers
+  0xD019: "VICIRQ",
+  0xD01A: "IRQMASK",
+  0xD01B: "SPBGPR",    // sprite-bg priority
+  0xD01C: "SPMC",      // sprite multicolor
+  0xD01D: "XXPAND",
+  0xD01E: "SPSPCL",    // sprite-sprite collision
+  0xD01F: "SPBGCL",    // sprite-data collision
+  0xD020: "EXTCOL",    // border
+  0xD021: "BGCOL0",    // background 0
+  0xD022: "BGCOL1",    0xD023: "BGCOL2",    0xD024: "BGCOL3",
+  0xD025: "SPMC0",     0xD026: "SPMC1",
+  0xD027: "SP0COL",    0xD028: "SP1COL",    0xD029: "SP2COL",    0xD02A: "SP3COL",
+  0xD02B: "SP4COL",    0xD02C: "SP5COL",    0xD02D: "SP6COL",    0xD02E: "SP7COL",
+  // SID $D400-$D41C
+  0xD400: "FRELO1",    0xD401: "FREHI1",    0xD402: "PWLO1",     0xD403: "PWHI1",
+  0xD404: "VCREG1",    0xD405: "ATDCY1",    0xD406: "SUREL1",
+  0xD407: "FRELO2",    0xD408: "FREHI2",    0xD409: "PWLO2",     0xD40A: "PWHI2",
+  0xD40B: "VCREG2",    0xD40C: "ATDCY2",    0xD40D: "SUREL2",
+  0xD40E: "FRELO3",    0xD40F: "FREHI3",    0xD410: "PWLO3",     0xD411: "PWHI3",
+  0xD412: "VCREG3",    0xD413: "ATDCY3",    0xD414: "SUREL3",
+  0xD415: "CUTLO",     0xD416: "CUTHI",     0xD417: "RESON",     0xD418: "SIGVOL",
+  0xD419: "POTX",      0xD41A: "POTY",      0xD41B: "RANDOM",    0xD41C: "ENV3",
+  // CIA1 $DC00-$DC0F (keyboard + joystick + timers + TOD)
+  0xDC00: "CIAPRA",    0xDC01: "CIAPRB",    0xDC02: "CIDDRA",    0xDC03: "CIDDRB",
+  0xDC04: "TIMALO",    0xDC05: "TIMAHI",    0xDC06: "TIMBLO",    0xDC07: "TIMBHI",
+  0xDC08: "TODTEN",    0xDC09: "TODSEC",    0xDC0A: "TODMIN",    0xDC0B: "TODHRS",
+  0xDC0C: "CIASDR",    0xDC0D: "CIAICR",    0xDC0E: "CIACRA",    0xDC0F: "CIACRB",
+  // CIA2 $DD00-$DD0F (serial bus + VIC bank select + RS232)
+  0xDD00: "CI2PRA",    0xDD01: "CI2PRB",    0xDD02: "C2DDRA",    0xDD03: "C2DDRB",
+  0xDD04: "TI2ALO",    0xDD05: "TI2AHI",    0xDD06: "TI2BLO",    0xDD07: "TI2BHI",
+  0xDD08: "TO2TEN",    0xDD09: "TO2SEC",    0xDD0A: "TO2MIN",    0xDD0B: "TO2HRS",
+  0xDD0C: "CI2SDR",    0xDD0D: "CI2ICR",    0xDD0E: "CI2CRA",    0xDD0F: "CI2CRB",
+};
+
+/**
+ * Look up the register table for a platform id, or null.
+ * @param {string} platform
+ * @returns {RegisterTable | null}
+ */
+export function registersForPlatform(platform) {
+  switch (platform) {
+    case "nes": return NES_REGISTERS;
+    case "snes": return SNES_REGISTERS;
+    case "genesis":
+    case "megadrive":
+    case "md": return GENESIS_REGISTERS;
+    case "gb":
+    case "gbc": return GB_REGISTERS;
+    case "sms":
+    case "gg": return SMS_REGISTERS;
+    case "atari2600":
+    case "a2600": return ATARI2600_REGISTERS;
+    case "atari7800":
+    case "a7800": return ATARI7800_REGISTERS;
+    case "c64": return C64_REGISTERS;
+    default: return null;
+  }
+}

package/src/platforms/common/render-tiles.js

@@ -0,0 +1,86 @@
+// Render a contiguous slice of tile bytes as a PNG grid.
+//
+// Works for any platform supported by the tile decoder. Picks a visualization
+// palette based on the platform: NES uses a sample of the NES master palette,
+// GB uses the DMG grays, others fall back to a generic ramp.
+
+import { PNG } from "pngjs";
+import { decodeTile } from "./tile-decode.js";
+import { TILE_SPECS } from "./image-to-tiles.js";
+import { NES_PALETTE } from "../nes/palette.js";
+
+/** Visualization palette per platform. */
+function vizPalette(platform, colors) {
+  if (platform === "nes") {
+    // Use a familiar mid-tone NES BG palette: dark blue/gray + 3 tones.
+    return [
+      NES_PALETTE[0x0f], // black
+      NES_PALETTE[0x00], // dark gray
+      NES_PALETTE[0x10], // light gray
+      NES_PALETTE[0x30], // white
+    ];
+  }
+  if (platform === "gb" || platform === "gbc") {
+    return [
+      [224, 248, 208],
+      [136, 192, 112],
+      [ 52, 104,  86],
+      [  8,  24,  32],
+    ];
+  }
+  // Generic: linear grayscale ramp scaled to `colors` entries.
+  const out = [];
+  for (let i = 0; i < colors; i++) {
+    const v = Math.round((i / Math.max(1, colors - 1)) * 255);
+    out.push([v, v, v]);
+  }
+  return out;
+}
+
+/**
+ * @param {Object} args
+ * @param {string} args.platform
+ * @param {Uint8Array} args.tileBytes  contiguous tile data in platform format
+ * @param {number} [args.tilesPerRow]
+ * @param {Array<[number,number,number]>} [args.paletteOverride]
+ *   Explicit RGB palette to use. Length must be >= spec.maxColors.
+ *   When provided, replaces the default grayscale visualization palette.
+ * @returns {Buffer} PNG bytes
+ */
+export function renderTilesGrid(args) {
+  const { platform, tileBytes, paletteOverride } = args;
+  const tilesPerRow = args.tilesPerRow ?? 16;
+  const spec = TILE_SPECS[platform];
+  if (!spec) throw new Error(`unknown platform '${platform}'`);
+  const bytesPerTile = (8 * 8 * spec.bpp) / 8;
+  const totalTiles = Math.floor(tileBytes.length / bytesPerTile);
+  const rows = Math.ceil(totalTiles / tilesPerRow);
+  const width = tilesPerRow * 8;
+  const height = rows * 8;
+
+  const png = new PNG({ width, height });
+  const dst = png.data;
+  const palette = paletteOverride && paletteOverride.length >= spec.maxColors
+    ? paletteOverride
+    : vizPalette(platform, spec.maxColors);
+
+  for (let t = 0; t < totalTiles; t++) {
+    const pixels = decodeTile(platform, tileBytes, t);
+    const tx = t % tilesPerRow;
+    const ty = Math.floor(t / tilesPerRow);
+    for (let y = 0; y < 8; y++) {
+      for (let x = 0; x < 8; x++) {
+        const idx = pixels[y * 8 + x];
+        const col = palette[idx] ?? palette[palette.length - 1];
+        const dx = tx * 8 + x;
+        const dy = ty * 8 + y;
+        const o = (dy * width + dx) * 4;
+        dst[o + 0] = col[0];
+        dst[o + 1] = col[1];
+        dst[o + 2] = col[2];
+        dst[o + 3] = 0xff;
+      }
+    }
+  }
+  return PNG.sync.write(png);
+}