romdevtools 0.13.0

package/src/platforms/genesis/TROUBLESHOOTING.md

@@ -0,0 +1,226 @@
+# Sega Genesis / Mega Drive — troubleshooting
+
+When something's broken. Read MENTAL_MODEL.md first for the "what's
+going on" version (via `platform({op:'doc', platform:"genesis", name:"mental_model"})`).
+
+## "My C build is throwing 68000 assembler errors (identifier expected / missing reset vector)"
+
+That means the file was assembled as 68k by vasm68k instead of compiled as
+C. **Genesis C builds through m68k-elf-gcc + SGDK** (`#include <genesis.h>`),
+**not** vasm68k — vasm68k is only for hand-written 68000 assembly. You do NOT
+need to write assembly. The build now infers the language from your source
+(a `.c` file / C content → gcc), so the common cause is forcing it the wrong
+way: if you passed `language:"asm"`, drop it; if your source has no `.c`
+filename AND no obvious C tokens, pass `language:"c"` explicitly. (Reverse case:
+a `.s` asm file builds via vasm68k — that's correct.)
+
+## "I drive the game with setInput but the jump/action button doesn't fire"
+
+The Genesis button map is **inverted** vs the libretro names. genesis_plus_gx
+maps Genesis A/B/C onto libretro **y/b/a** — so `input({op:'set', a:true})` presses
+Genesis **C**, not A. An SGDK action bound to `BUTTON_A` (the usual jump) won't
+fire from `{a:true}`.
+
+Fix — press the button you actually mean:
+- `BUTTON_A` → `input({op:'set', ports:[{y:true}]})` or spatial `{west:true}`
+- `BUTTON_B` → `{b:true}` / `{south:true}`
+- `BUTTON_C` → `{a:true}` / `{east:true}`
+
+Prefer the spatial names or `input({op:'press', button:'c'})` (they resolve correctly
+per platform). `input({op:'layout', platform:'genesis'})` has the full map. (Note:
+`input({op:'set'})` takes a `ports` array — `{ports:[{y:true}]}`, not a bare `{y:true}`.)
+
+## "ROM builds but the screen is blank / black"
+
+The Genesis VDP starts in forced-blank state. SGDK's sega.s + libmd
+lift the blank during boot, but only if your `main()` calls into the
+SGDK frame heartbeat. **You MUST call `SYS_doVBlankProcess()` at least
+once** before anything appears on screen — it primes the DMA queue,
+flushes initial palette + tile uploads, and ticks the sprite engine.
+
+Specifically: a `main()` that just runs `while (1) { /* nothing */ }`
+will boot, but you'll never see anything because the DMA queue never
+runs.
+
+Fix:
+
+```c
+while (1) {
+    /* ... your per-frame work ... */
+    SYS_doVBlankProcess();
+}
+```
+
+## "Sprites don't appear"
+
+Two failure modes:
+
+1. **You staged sprites via `VDP_setSprite()` but didn't call
+   `VDP_updateSprites(n, DMA)`.** SGDK buffers SAT writes in a RAM-
+   side cache and only flushes them to VRAM when you call
+   `VDP_updateSprites`. Without the flush, the VDP draws stale (or
+   zero) SAT entries.
+2. **You used the sprite engine (`SPR_init`/`SPR_addSprite`) but
+   didn't call `SPR_update()` each frame.** Same problem at a
+   different layer — the engine maintains its own state and only
+   pushes to the SAT on `SPR_update`.
+
+Either fix:
+
+```c
+/* low-level path */
+VDP_setSprite(0, x, y, SPRITE_SIZE(1,1), TILE_ATTR_FULL(...));
+VDP_updateSprites(1, DMA);
+
+/* high-level path */
+SPR_setPosition(player, x, y);
+SPR_update();
+```
+
+## "Colors are wrong / everything is one shade of green"
+
+The Genesis colour encoding is **BGR**, not RGB, and each channel is
+3 bits (0..7). The full word is `0BGR` packed in 4-bit nibbles:
+
+- `$0EEE` = white (B=14, G=14, R=14 — 14 saturates to 7 in hw)
+- `$000E` = bright red
+- `$00E0` = bright green
+- `$0E00` = bright blue
+- `$0000` = black
+
+If you're seeing all-green, you wrote RGB-ordered values (the green
+nibble is in the middle of both layouts, so it survives).
+
+## "Build fails with `undefined reference to '_system'`"
+
+You're using a newlib that wasn't patched for bare-metal m68k. Our
+WASM toolchain's libc was built with `-DNO_EXEC` and you shouldn't
+see this. If you do, you may be linking against a different libc
+that the project shipped — check that `libmd.a` + the bundled
+`libc.a` are what link is finding.
+
+## "Build fails with `relocation truncated to fit: R_68K_PC16`"
+
+68000 short-form branches (`bra.s`, `bcc.s`) reach only ±128 bytes.
+Long-form (`bra`, `bcc`) reach ±32 KB. Some compiler-generated jump
+tables and stub helpers fall foul when libgcc.a / libc.a links pull
+in too much. Workarounds:
+
+- Use `-fno-jump-tables` to suppress jump-table generation.
+- Compile with `-Os` (size-optimize) — packs code more densely.
+- Split monolithic functions into smaller ones (each gets its own
+  PC-relative branch budget).
+
+## "ROM boots in genesis_plus_gx but fails on real hardware (TMSS)"
+
+TMSS-equipped consoles (model 2 onward) require the 68000 to write
+the four ASCII bytes `'S' 'E' 'G' 'A'` to $A14000 within ~500ms of
+boot. SGDK's sega.s does this. If you bypassed SGDK's crt0 (e.g.
+custom linker script that doesn't include `sega.o`), you'll boot
+fine on genesis_plus_gx (no TMSS) but fail on real hardware.
+
+Fix: keep `sega.o` (built from `sega.preprocessed.s`) in your link
+list. Or, write your own TMSS unlock in your custom crt0.
+
+## "Sound is silent"
+
+Three layered things to check:
+
+1. **YM2612 is muted at reset.** SGDK's XGM2_init() unmutes it; if
+   you're using XGM2, just call `XGM2_init()` once before
+   `XGM2_play()`. (The R58 driver fn is `XGM2_play`, not `XGM2_startPlay` —
+   and feed it a COMPILED XGM2 blob from `encodeAudio({target:'xgm2', vgmPath})`,
+   not raw VGM.)
+2. **Z80 reset/busreq isn't released.** If you bypass SGDK's sound
+   API and want to write YM2612 registers directly, you must first
+   write 1 to `$A11200` (Z80 reset off) and 0 to `$A11100` (busreq
+   off). Genesis Plus GX is lenient here; real hardware isn't.
+3. **PSG (SN76489) writes go to $C00011 *byte-wise*.** A `move.w` to
+   $C00011 silently writes only the low byte; use `move.b`.
+
+## "Save states don't restore Z80 state"
+
+The libretro core needs to capture the Z80 RAM ($A00000-$A0FFFF) +
+the bus-grant state. If you've stored game state in Z80 RAM (rare
+but possible) and save state is missing your data on reload, it's
+likely the core doesn't snapshot Z80 RAM by default. Workaround:
+keep persistent state in 68000 WRAM ($FF0000+) — that's always
+snapshotted.
+
+## "First C build is slow (1-2 s) but later ones are instant"
+
+This is expected. cc1-m68k.wasm is 17.5 MB and gets mmap-loaded into
+a worker on first invocation. Subsequent builds reuse the warm worker
+pool (R12 crash-isolation infrastructure). The cold-start hit is
+unavoidable; the steady-state cost is sub-second.
+
+## "Genesis ROM header is wrong (region, IO support, ROM range)"
+
+`rom_header.c` defines these via `const u32 rom_header[]` style arrays
+that the C compiler emits as the 256-byte SEGA header. The bundled
+default declares NTSC + PAL + JP region, 3-button + 6-button + mouse
+IO support, and a 4 MB ROM size. Edit `rom_header.c` (it's plain C
+data) to change these.
+
+The header checksum at offset $18E is computed by the link step from
+your code+data; don't hand-edit it.
+
+## "My splash / title screen is the right shapes but all one color and choppy/striped"
+
+You hand-rolled the PNG→tile conversion and got the byte encoding
+wrong. The symptom — correct silhouette, everything in one color
+(usually red), vertical striping — means your tile bytes were raw
+RGB-ish values instead of 4bpp **palette indices**, and/or the row
+stride / nibble packing was off. The high nibble of each byte is the
+LEFT pixel; each nibble is a 0..15 index into a 16-color CRAM line,
+not a color.
+
+**Don't hand-roll it. Use the `encodeArt({stage:'tilemap'})` MCP tool** — it dedupes
+tiles, bin-packs colors across the 4 palette lines, and emits correct
+4bpp packed bytes + a 16-bit-BE name-table + the CRAM palette in one
+call:
+
+```
+# 1. Source must be 320×224.
+# 2. Quantize to the Genesis palette:
+palette({ source:'platformMaster', platform:"genesis", format:"png", outputPath:"/tmp/gen_pal.png" })
+magick splash.png -dither FloydSteinberg -remap /tmp/gen_pal.png splash_q.png
+# 3. Convert:
+encodeArt({ stage:'tilemap', platform:"genesis", pngPath:"splash_q.png", outputDir:"splash_out/" })
+```
+
+You get `splash_out/chr.bin` (deduped tiles), `nametable.bin`
+(40×28 16-bit-BE entries), `palette.bin` (4×16 CRAM words), and
+`preview.png`. **Open `preview.png` first** — it's the tool rendering
+its own output, so a correct preview guarantees a correct in-game
+result. Then DMA `chr.bin` to VRAM, load `palette.bin` into CRAM, and
+write `nametable.bin` to your Plane A base (set plane width = 64 cells).
+The tool response `note` restates the exact sizes + destinations.
+
+If `encodeArt({stage:'tilemap'})` returns `genesis.warnings[]` about cells with >16
+colors, your source crams too many colors into one 8×8 cell (the VDP's
+hard limit) — re-author those regions or accept the per-cell
+approximation.
+
+## "I want to use SGDK's image converter / `bmp.h` / .bmp loading"
+
+First choice for any PNG → tiles+tilemap+palette conversion: the
+**`encodeArt({stage:'tilemap'})` MCP tool** (see the splash-screen section above). It
+needs no native tools and produces ready-to-DMA blobs.
+
+Some SGDK helper tools (`rescomp`, `bintos`, `convsym`) aren't ported to WASM;
+you can run them natively on a build machine to produce .bin / .o / .pal /
+.tileset blobs, then drop them into your romdev project as binary includes — the
+build will just incbin them.
+
+**Music is covered, though:** VGM→XGM2 compilation (SGDK's Java `xgm2tool`) is
+ported to pure JS and exposed as `encodeAudio({target:'xgm2', vgmPath, name})`
+— it emits a 256-aligned C array you `#include` and `XGM2_play()`. No native
+tool / Java needed. (PCM SFX: `encodeAudio({target:'xgm2pcm'})`.)
+
+For a handful of hand-drawn tiles, you can also author them as
+`u32[8]` arrays in C (4bpp tile format = 8 rows × 4 bytes each, two
+pixels per byte). The shipped `hello_sprite`, `tile_engine`, `shmup`,
+`platformer`, `puzzle` templates use this approach. **But never
+hand-encode a full-screen image this way** — that's the red/choppy
+failure above.

package/src/platforms/genesis/UPSTREAM_SOURCES.md

@@ -0,0 +1,53 @@
+# Genesis / Mega Drive — source you can read
+
+Trust hierarchy:
+
+1. **Bundled examples** (`examples/genesis/templates/*.c`).
+2. **Bundled runtime source** — `src/platforms/genesis/lib/c/
+   genesis_sfx.c` (PSG wrapper); `lib/sgdk/sega.s` (boot crt0);
+   `lib/sgdk/rom_header.c` (cart header builder).
+3. **Bundled library source** (R58) — full SGDK source tree at
+   `src/platforms/genesis/lib/sgdk/src/`. Every SGDK API (VDP_*,
+   SPR_*, JOY_*, XGM2_*, BMP_*, etc.) has readable C here.
+4. **Upstream GitHub** (NOT bundled):
+
+   | What | Upstream |
+   |---|---|
+   | SGDK | https://github.com/Stephane-D/SGDK |
+   | m68k-elf-gcc / binutils / newlib (bundled WASM, build instructions only) | https://gcc.gnu.org/ |
+   | vasm (the assembler we ship as the alternative path) | http://sun.hasenbraten.de/vasm/ |
+   | genesis_plus_gx libretro core | https://github.com/libretro/Genesis-Plus-GX |
+
+## Genesis hardware docs
+
+- **Genesis Software Manual** (Sega official, scanned): https://segaretro.org/Sega_Mega_Drive/Documents
+- **Mega Drive technical info** (genesis-effects.blogspot, modern): https://mode5.dev/
+- **Plutiedev** (homebrew tutorial site): https://plutiedev.com/
+- **Copetti**: https://www.copetti.org/writings/consoles/mega-drive-genesis/
+- **VDP register reference**: https://md.railgun.works/index.php?title=Main_Page
+
+## YM2612 + PSG (audio)
+
+The Genesis has TWO audio chips:
+- **SN76489 PSG** (3 squares + 1 noise) — what our `genesis_sfx`
+  wrapper drives via SGDK's `PSG_*` helpers
+- **YM2612 FM synth** (6 channels of 4-op FM) — driven by the Z80
+  side via SGDK's XGM2 driver (compiled XGM2 blobs)
+
+The Z80 sound CPU runs a separate program (XGM2 driver) loaded into
+Z80 RAM at boot. To get music: compose in DefleMask or similar →
+export `.vgm` → compile to XGM2 with `encodeAudio({target:'xgm2', vgmPath, name})`
+(a pure-JS port of SGDK's Java `xgm2tool`; emits a 256-aligned C array) → `#include`
+→ `XGM2_play(music)`. (The driver fn is `XGM2_play`; the older C `xgmtool`/`.xgc`
+is the LEGACY `XGM_*` v1 format — different driver, don't mix.)
+
+For YM2612 register-level work: https://www.smspower.org/Development/YM2612
+
+## When to use what
+
+- "How does `VDP_drawText` work?" → `sgdk/src/vdp_bg.c` + `sgdk/src/font.c`
+- "What does `SPR_addSprite` actually queue?" → `sgdk/src/sprite_eng.c`
+- "Why does `JOY_readJoypad(JOY_1)` not see Start?" → `sgdk/src/joy.c`
+  (controller polling) + Plutiedev's joypad doc
+- "How does XGM2_play sync with vblank?" → `sgdk/src/snd/xgm2.c`
+- "VDP register X does what?" → md.railgun.works VDP reference

package/src/platforms/genesis/image-to-tilemap.js

@@ -0,0 +1,351 @@
+// Genesis (VDP) — palette PNG generator for the -remap workflow.
+//
+// The Genesis VDP supports 512 distinct colors total: 8 levels per channel
+// (R, G, B), 3 bits each, 9-bit overall. Hardware spec is "non-linear" —
+// the ladder isn't perfectly evenly spaced — but for input-image
+// quantization the linear approximation is what most tools use and
+// matches what gpgx renders.
+//
+// Workflow: agent calls getPlatformPalettePng({platform:"genesis"}),
+// saves to disk, runs `magick in.png -dither FloydSteinberg -remap
+// genesis_palette.png out.png` to constrain colors to what the VDP can
+// display, then passes out.png to imageToTilemap.
+
+import { PNG } from "pngjs";
+import { rgbToGenesisColor, decodeCRAM } from "./vdp.js";
+
+const W = 320;
+const H = 224;
+
+/**
+ * Convert a 320×224 PNG into Genesis VDP tilemap assets.
+ *
+ * Output shape matches the other platforms' imageToTilemap so the generic
+ * dispatcher + the imageToTilemap MCP tool consume it directly:
+ *   chr        → 4bpp packed tile data (32 B/tile, high nibble = left pixel)
+ *   nametable  → 16-bit big-endian name-table entries
+ *                (bit15 priority, 14-13 palette line, 12 vflip, 11 hflip, 10-0 tile)
+ *   attr       → empty (Genesis packs palette/flip into the nametable entry)
+ *   palette    → up to 4 lines × 16 colors × uint16 BE CRAM words (128 B)
+ *
+ * The Genesis can show 4 palette LINES of 16 colors each, and every 8×8
+ * cell selects ONE line. We quantize the image to ≤64 distinct Genesis
+ * colors, pack them into up to 4 lines, then per tile pick the line that
+ * contains all of that tile's colors. Tiles whose colors span more than
+ * one line are reported (the image needs authoring to ≤16 colors per 8×8
+ * cell — the VDP's hard constraint, same as SNES/SMS).
+ *
+ * @param {Object} args
+ * @param {Buffer|Uint8Array} args.pngBytes  320×224 PNG, pre-dithered to the Genesis palette.
+ * @returns {{ chr:Uint8Array, nametable:Uint8Array, attr:Uint8Array, palette:Uint8Array,
+ *   uniqueTilesBeforeMerge:number, uniqueTiles:number, imageColors:number,
+ *   paletteLines:number, previewPng:Buffer, warnings:string[] }}
+ */
+export function genesisImageToTilemap(args) {
+  const png = PNG.sync.read(Buffer.from(args.pngBytes));
+  if (png.width !== W || png.height !== H) {
+    throw new Error(`Genesis image must be ${W}×${H}, got ${png.width}×${png.height}`);
+  }
+  const warnings = [];
+
+  // 1) Quantize every pixel to a Genesis 9-bit color WORD (the value the
+  //    VDP actually stores). This collapses near-identical RGB to the same
+  //    hardware color so the ≤64 budget is measured in real CRAM entries.
+  const wordOf = new Uint16Array(W * H);
+  const distinct = new Map(); // genesisWord → count
+  for (let i = 0; i < W * H; i++) {
+    const k = i * 4;
+    const w = rgbToGenesisColor(png.data[k], png.data[k + 1], png.data[k + 2]);
+    wordOf[i] = w;
+    distinct.set(w, (distinct.get(w) || 0) + 1);
+  }
+  const imageColors = distinct.size;
+
+  // 2) Per-tile color sets (sets of genesis words used by each 8×8 cell).
+  const tilesAcross = W / 8; // 40
+  const tilesDown = H / 8;   // 28
+  const tileColorSets = [];
+  for (let ty = 0; ty < tilesDown; ty++) {
+    for (let tx = 0; tx < tilesAcross; tx++) {
+      const set = new Set();
+      for (let row = 0; row < 8; row++) {
+        for (let col = 0; col < 8; col++) {
+          set.add(wordOf[(ty * 8 + row) * W + (tx * 8 + col)]);
+        }
+      }
+      tileColorSets.push(set);
+    }
+  }
+
+  // 3) Build up to 4 palette lines (16 colors each). Greedy bin-packing:
+  //    walk tiles, try to fit each tile's color set into an existing line;
+  //    if it fits (line ∪ tileColors ≤ 16), merge; else open a new line.
+  //    Color index 0 within a line is reserved as transparent/background.
+  const lines = []; // each: Set<genesisWord>, with the backdrop word forced at idx 0
+  const backdropEntry = [...distinct.entries()].sort((a, b) => b[1] - a[1])[0];
+  const backdrop = backdropEntry[0]; // most common
+  const tilePalLine = new Int8Array(tilesAcross * tilesDown).fill(-1);
+
+  // FOOTGUN GUARD: the most-common color is forced to palette index 0, which is
+  // TRANSPARENT on a scroll plane (it shows the hardware backdrop, not the
+  // color). For a full-screen BG whose dominant color is a visible fill (e.g. a
+  // white/blue sky), this silently renders that area as the backdrop color
+  // (usually black) in-game. Warn — and the fix is one call: set that color as
+  // the hardware backdrop so index 0 actually shows it.
+  {
+    const r0 = backdrop & 7, g0 = (backdrop >> 3) & 7, b0 = (backdrop >> 6) & 7;
+    const dominantFrac = backdropEntry[1] / (png.width * png.height);
+    if ((r0 || g0 || b0) && dominantFrac >= 0.15) {
+      const hex = "#" + [r0, g0, b0].map((c) => Math.round((c / 7) * 255).toString(16).padStart(2, "0")).join("");
+      warnings.push(
+        `palette index 0 = a VISIBLE color (~${hex}, ${Math.round(dominantFrac * 100)}% of the image) — on a scroll PLANE index 0 is TRANSPARENT and shows the hardware backdrop (usually black), so this area will render wrong in-game. Fix: call VDP_setBackgroundColor() with this color's CRAM slot (palette-line*16 + 0) so the backdrop matches, OR recolor so index 0 is an intentional transparent/background color.`
+      );
+    }
+  }
+
+  // Sort tiles by descending color count so the hard ones grab lines first.
+  const order = [...tileColorSets.keys()].sort((a, b) => tileColorSets[b].size - tileColorSets[a].size);
+  for (const t of order) {
+    const cols = tileColorSets[t];
+    if (cols.size > 16) {
+      warnings.push(`tile at cell ${t % tilesAcross},${Math.floor(t / tilesAcross)} uses ${cols.size} colors (>16); extra colors will be clamped.`);
+    }
+    let placed = -1;
+    for (let li = 0; li < lines.length; li++) {
+      // Would the union fit in 16 (counting backdrop at slot 0)?
+      const union = new Set(lines[li]);
+      for (const c of cols) union.add(c);
+      union.add(backdrop);
+      if (union.size <= 16) {
+        lines[li] = union;
+        placed = li;
+        break;
+      }
+    }
+    if (placed === -1) {
+      if (lines.length < 4) {
+        const nl = new Set([backdrop, ...cols]);
+        lines.push(nl);
+        placed = lines.length - 1;
+      } else {
+        // No room — assign to the line that already covers the most of this
+        // tile's colors (best-effort; off-palette pixels map to nearest).
+        let best = 0, bestHit = -1;
+        for (let li = 0; li < 4; li++) {
+          let hit = 0;
+          for (const c of cols) if (lines[li].has(c)) hit++;
+          if (hit > bestHit) { bestHit = hit; best = li; }
+        }
+        placed = best;
+        warnings.push(`out of palette lines (max 4) — cell ${t % tilesAcross},${Math.floor(t / tilesAcross)} forced onto line ${best}; some colors approximated.`);
+      }
+    }
+    tilePalLine[t] = placed;
+  }
+  if (lines.length === 0) lines.push(new Set([backdrop]));
+
+  // 4) Materialize each line as an ordered 16-entry color array (index→word),
+  //    backdrop at 0. Build a word→index lookup per line.
+  const lineWords = lines.map((set) => {
+    const arr = [backdrop, ...[...set].filter((w) => w !== backdrop)].slice(0, 16);
+    while (arr.length < 16) arr.push(0);
+    return arr;
+  });
+  const lineLookup = lineWords.map((arr) => {
+    const m = new Map();
+    arr.forEach((w, i) => { if (!m.has(w)) m.set(w, i); });
+    return m;
+  });
+
+  // Nearest-index fallback for a word not in a line (decode the line to RGB
+  // and pick the closest).
+  const lineRgb = lineWords.map((arr) => {
+    const bytes = new Uint8Array(arr.length * 2);
+    arr.forEach((w, i) => { bytes[i * 2] = (w >> 8) & 0xFF; bytes[i * 2 + 1] = w & 0xFF; });
+    return decodeCRAM(bytes);
+  });
+  const wordRgbCache = new Map();
+  const decodeWord = (w) => {
+    if (!wordRgbCache.has(w)) {
+      const b = new Uint8Array([(w >> 8) & 0xFF, w & 0xFF]);
+      wordRgbCache.set(w, decodeCRAM(b)[0]);
+    }
+    return wordRgbCache.get(w);
+  };
+  const indexInLine = (w, li) => {
+    const hit = lineLookup[li].get(w);
+    if (hit !== undefined) return hit;
+    const [r, g, b] = decodeWord(w);
+    let best = 0, bestD = Infinity;
+    lineRgb[li].forEach((c, i) => {
+      const d = (c[0] - r) ** 2 + (c[1] - g) ** 2 + (c[2] - b) ** 2;
+      if (d < bestD) { bestD = d; best = i; }
+    });
+    return best;
+  };
+
+  // 5) Encode tiles to 4bpp packed bytes (high nibble = left pixel), dedup
+  //    with h/v flip detection. A tile's bytes depend on its palette line,
+  //    so dedup keys include the line index implicitly (same pixels + same
+  //    line → same bytes).
+  const makeTile = (tx, ty, line) => {
+    const t = new Uint8Array(32);
+    for (let row = 0; row < 8; row++) {
+      for (let half = 0; half < 4; half++) {
+        const x0 = tx * 8 + half * 2;
+        const hi = indexInLine(wordOf[(ty * 8 + row) * W + x0], line);
+        const lo = indexInLine(wordOf[(ty * 8 + row) * W + x0 + 1], line);
+        t[row * 4 + half] = ((hi & 0xF) << 4) | (lo & 0xF);
+      }
+    }
+    return t;
+  };
+  const flipH = (tile) => {
+    const out = new Uint8Array(32);
+    for (let row = 0; row < 8; row++) {
+      for (let half = 0; half < 4; half++) {
+        const b = tile[row * 4 + (3 - half)];
+        // swap nibbles (left/right pixel) too
+        out[row * 4 + half] = ((b & 0x0F) << 4) | ((b >> 4) & 0x0F);
+      }
+    }
+    return out;
+  };
+  const flipV = (tile) => {
+    const out = new Uint8Array(32);
+    for (let row = 0; row < 8; row++) {
+      const src = 7 - row;
+      for (let half = 0; half < 4; half++) out[row * 4 + half] = tile[src * 4 + half];
+    }
+    return out;
+  };
+  const toKey = (t) => { let s = ""; for (let i = 0; i < 32; i++) s += t[i].toString(16).padStart(2, "0"); return s; };
+
+  const tileByKey = new Map();
+  const chr = [];
+  const nametable = new Uint8Array(tilesAcross * tilesDown * 2);
+  let uniqueBeforeMerge = 0;
+
+  for (let ty = 0; ty < tilesDown; ty++) {
+    for (let tx = 0; tx < tilesAcross; tx++) {
+      const cellIdx = ty * tilesAcross + tx;
+      const line = Math.max(0, tilePalLine[cellIdx]);
+      const base = makeTile(tx, ty, line);
+      uniqueBeforeMerge++;
+      let flipBits = 0; // bit11 hflip (0x0800), bit12 vflip (0x1000)
+      let chosenKey = toKey(base);
+      if (!tileByKey.has(chosenKey)) {
+        const h = flipH(base), v = flipV(base), hv = flipV(flipH(base));
+        const hK = toKey(h), vK = toKey(v), hvK = toKey(hv);
+        if (tileByKey.has(hK)) { chosenKey = hK; flipBits = 0x0800; }
+        else if (tileByKey.has(vK)) { chosenKey = vK; flipBits = 0x1000; }
+        else if (tileByKey.has(hvK)) { chosenKey = hvK; flipBits = 0x1800; }
+        else { tileByKey.set(chosenKey, chr.length); chr.push(base); }
+      }
+      const tileIdx = tileByKey.get(chosenKey);
+      // Big-endian 16-bit: pcc v h ttttttttttt
+      const entry = (tileIdx & 0x07FF) | flipBits | ((line & 0x3) << 13);
+      const off = cellIdx * 2;
+      nametable[off] = (entry >> 8) & 0xFF;
+      nametable[off + 1] = entry & 0xFF;
+    }
+  }
+
+  // 6) Flatten chr + build the 128-byte palette (4 lines × 16 words BE).
+  const chrFlat = new Uint8Array(chr.length * 32);
+  for (let i = 0; i < chr.length; i++) chrFlat.set(chr[i], i * 32);
+  const palette = new Uint8Array(128);
+  for (let li = 0; li < 4; li++) {
+    const arr = lineWords[li] || new Array(16).fill(0);
+    for (let i = 0; i < 16; i++) {
+      const w = arr[i] || 0;
+      palette[(li * 16 + i) * 2] = (w >> 8) & 0xFF;
+      palette[(li * 16 + i) * 2 + 1] = w & 0xFF;
+    }
+  }
+
+  // 7) Preview re-render from the encoded data.
+  const preview = new PNG({ width: W, height: H });
+  for (let ty = 0; ty < tilesDown; ty++) {
+    for (let tx = 0; tx < tilesAcross; tx++) {
+      const off = (ty * tilesAcross + tx) * 2;
+      const entry = (nametable[off] << 8) | nametable[off + 1];
+      const tileIdx = entry & 0x07FF;
+      const hflip = !!(entry & 0x0800);
+      const vflip = !!(entry & 0x1000);
+      const line = (entry >> 13) & 0x3;
+      const tb = tileIdx * 32;
+      for (let row = 0; row < 8; row++) {
+        const srcRow = vflip ? 7 - row : row;
+        for (let col = 0; col < 8; col++) {
+          const srcCol = hflip ? 7 - col : col;
+          const byte = chrFlat[tb + srcRow * 4 + (srcCol >> 1)];
+          const ci = (srcCol & 1) ? (byte & 0x0F) : ((byte >> 4) & 0x0F);
+          const [r, g, b] = lineRgb[line] ? lineRgb[line][ci] : [0, 0, 0];
+          const o = ((ty * 8 + row) * W + (tx * 8 + col)) * 4;
+          preview.data[o] = r; preview.data[o + 1] = g; preview.data[o + 2] = b; preview.data[o + 3] = 0xFF;
+        }
+      }
+    }
+  }
+
+  return {
+    chr: chrFlat,
+    nametable,
+    attr: new Uint8Array(0),
+    palette,
+    uniqueTilesBeforeMerge: uniqueBeforeMerge,
+    uniqueTiles: chr.length,
+    imageColors,
+    paletteLines: lineWords.length,
+    previewPng: PNG.sync.write(preview),
+    warnings,
+  };
+}
+
+/**
+ * Generate a PNG containing all 512 Genesis-displayable colors arranged
+ * in a 32×16 grid. Each cell is 16×16 px for visibility (final image:
+ * 512×256). Useful as the -remap target for ImageMagick.
+ *
+ * The Genesis VDP word format (per CRAM):
+ *   bits 0:    unused
+ *   bits 1-3:  R (3 bits)
+ *   bit 4:     unused
+ *   bits 5-7:  G (3 bits)
+ *   bit 8:     unused
+ *   bits 9-11: B (3 bits)
+ *
+ * 3-bit → 8-bit expansion uses (n << 5) | (n << 2) | (n >> 1), the same
+ * formula used in decodeGenesisCRAM (see host/gpgx-state.js).
+ *
+ * @returns {Buffer} PNG bytes
+ */
+export function genesisPalettePng() {
+  const COLS = 32, ROWS = 16; // 32 × 16 = 512 colors
+  const CELL = 16;
+  const png = new PNG({ width: COLS * CELL, height: ROWS * CELL });
+  const expand = (n3) => (n3 << 5) | (n3 << 2) | (n3 >> 1);
+  for (let i = 0; i < 512; i++) {
+    const r3 = i & 0x7;
+    const g3 = (i >> 3) & 0x7;
+    const b3 = (i >> 6) & 0x7;
+    const r = expand(r3);
+    const g = expand(g3);
+    const b = expand(b3);
+    const cx = i % COLS;
+    const cy = Math.floor(i / COLS);
+    for (let py = 0; py < CELL; py++) {
+      for (let px = 0; px < CELL; px++) {
+        const x = cx * CELL + px;
+        const y = cy * CELL + py;
+        const o = (y * png.width + x) * 4;
+        png.data[o] = r;
+        png.data[o + 1] = g;
+        png.data[o + 2] = b;
+        png.data[o + 3] = 0xFF;
+      }
+    }
+  }
+  return PNG.sync.write(png);
+}