romdev-mcp 0.1.1

package/src/platforms/sms/MENTAL_MODEL.md

@@ -0,0 +1,267 @@
+# Sega Master System / Game Gear — mental model
+
+One page. Read once before you write your first SMS / GG game. The
+TROUBLESHOOTING.md alongside this file is for when something's broken;
+this is the "what's going on" version.
+
+## CPU memory map (Z80, 16-bit address space)
+
+```
+$0000-$BFFF   ROM (typical 48 KB; mapper extends to 4 MB)
+$C000-$DFFF   work RAM (8 KB, mirrored to $E000-$FFFF)
+$DFF0+        stack (grows down) — sms_crt0 sets SP here
+$FFFC-$FFFF   mapper registers (Sega mapper, page select per slot)
+```
+
+Cartridge is paged in 16 KB slots ($0000, $4000, $8000) via the Sega
+mapper at $FFFC-$FFFF. Slot 0 (`$0000-$3FFF`) holds the boot ROM /
+fixed bank with the interrupt vectors and the first chunk of code;
+slots 1 and 2 are bank-switched on demand. Our minimal templates
+fit in 32 KB so we never page.
+
+The Z80 has separate **I/O port** address space (`in`/`out`
+instructions). Game logic talks to the VDP and joypads via ports,
+NOT via memory-mapped registers.
+
+## I/O ports
+
+```
+$3E   memory control (cartridge slot + RAM enable)
+$3F   I/O control (joypad direction polarity)
+$7E   V-counter (read)        / PSG (write — sound)
+$7F   H-counter (read)
+$BE   VDP data port
+$BF   VDP control port
+$DC   P1 joypad + P2 dpad
+$DD   P2 buttons + reset / cart-detect
+```
+
+In C with SDCC's `__sfr __at` declarations:
+
+```c
+__sfr __at 0xBE PORT_VDP_DATA;
+__sfr __at 0xBF PORT_VDP_CTRL;
+__sfr __at 0xDC PORT_JOY_A;
+```
+
+Reading the variable compiles to `in a,(port)`, writing to
+`out (port),a`. See `src/platforms/sms/lib/c/sms_hw.h` for the full
+set.
+
+## VDP (Video Display Processor)
+
+The SMS VDP is a derivative of the TMS9918, with mode-4 (the SMS
+graphics mode) doing most of the lifting. It has its own VRAM
+(16 KB) and CRAM (32 bytes — palette).
+
+```
+VRAM   16 KB    tile patterns + name table + sprite attr table + sprite tile data
+CRAM   32 B     32 palette entries × 1 byte (2-2-2 BGR)
+```
+
+VRAM is reached through port $BE (data) + port $BF (control). To set
+the destination address X for a write:
+
+```c
+PORT_VDP_CTRL = X & 0xFF;             /* low byte */
+PORT_VDP_CTRL = ((X >> 8) & 0x3F) | 0x40;  /* high byte + WRITE prefix */
+```
+
+Then subsequent writes to PORT_VDP_DATA push bytes sequentially.
+
+The 11 VDP registers ($00-$0A) control the display. Idiomatic
+baseline (set by `sms_vdp_init()`):
+
+```
+R0 = 0x36   Mode 4 + line-IRQ
+R1 = 0x80   display OFF, vblank IRQ off, 192-line
+R2 = 0xFF   name table at $3800
+R4 = 0xFF   BG tile data at $0000
+R5 = 0xFF   sprite attr table at $3F00
+R6 = 0xFB   sprite tile data at $0000 (NOT $2000 — see footgun below)
+R7 = 0x00   border colour
+```
+
+Then later: `R1 = 0xE0` to enable display + vblank IRQ.
+
+## Tiles + name table
+
+Tiles are 8×8 pixels, **4 bits per pixel** in **bitplane-interleaved
+format**: 32 bytes per tile, 4 bytes per row (one byte per plane).
+512 tiles max in VRAM (256 BG + 256 sprite, by default config).
+
+The BG name table at $3800 is 32 cols × 28 rows × 2 bytes/entry.
+Each entry packs:
+
+```
+byte 0: low 8 bits of tile index
+byte 1: 0 0 0 priority palette vflip hflip tile_idx_bit9
+```
+
+Where `palette = 0` → BG palette ($00-$0F in CRAM), `palette = 1` →
+sprite palette ($10-$1F).
+
+## Sprites (sprite attribute table)
+
+SAT at VRAM $3F00. 64 sprite slots × 4 bytes:
+
+```
+$3F00-$3F3F:  64 Y bytes — Y = 0xD0 hides all subsequent sprites
+$3F80-$3FFF:  64 (X, tile) pairs interleaved
+```
+
+So Y bytes and X/tile pairs are split into TWO regions of the SAT.
+`src/platforms/sms/lib/c/sprite_table.c` keeps a 256-byte shadow
+buffer in WRAM and uploads it to the SAT each vblank.
+
+### Two footguns the bundled scaffolds keep hitting
+
+1. **8 sprites per scanline limit.** The VDP draws up to 8 sprites per
+   scanline; the 9th+ are silently dropped. If you draw a "CATCH THE
+   COIN" text using 14 sprite tiles on the same Y row, **only the
+   first 8 letters appear** and the rest vanish with no warning. Fix:
+   split text across multiple Y rows OR draw it via the BG name
+   table (which has no per-line limit).
+
+2. **SAT $D0 terminator.** The VDP treats Y=$D0 in any OAM Y byte as
+   a HARD terminator — it stops scanning further slots immediately.
+   Earlier rounds of `sms_sprite_init()` wrote $D0 to every Y byte
+   to "hide" sprites at boot, which caused the classic "I populated
+   slots 0..5 and slot 6 was still $D0 so the renderer halted at
+   slot 5" footgun.
+
+   **The runtime now initialises unused slots to $E0** (off-screen,
+   below the 192-line area, but NOT the terminator). Slots you
+   don't touch stay invisible AND don't kill the renderer. You only
+   have to worry about $D0 if you write it explicitly — e.g. as an
+   early-out optimisation.
+
+   If sprites past a certain slot are missing in `inspectSprites`,
+   check the live OAM Y bytes for $D0 in a slot before them.
+
+`inspectSprites` shows the live OAM bytes + reports
+`spriteTileDataBase` — trust it over comments when sprites misbehave.
+
+### R6 sprite-tile-base default: $0000, NOT $2000
+
+`sms_vdp_init()` sets R6 = 0xFB. R6 bit 2 is the SA13 select for
+sprite tile data — and bit 2 is **CLEAR** in 0xFB. That means
+sprite tiles read from `$0000-$1FFF`, **sharing the bank with BG
+tiles**. Many references (including older comments in our own
+`vdp_init.c` and `load_tiles.c`, since fixed) say "R6=0xFB → sprite
+tiles at $2000" — that's wrong.
+
+If you want sprite tiles in their own bank at $2000, set
+`vdp_write_reg(6, 0xFF)` AND upload tiles to VRAM $2000. Otherwise
+upload sprite tiles to $0000 alongside BG tiles (just make sure
+they don't collide).
+
+## Palette (CRAM)
+
+32 entries × 1 byte = 32 bytes. 2-2-2 BGR encoding:
+
+```
+bit 0-1: red          0..3
+bit 2-3: green        0..3
+bit 4-5: blue         0..3
+```
+
+Brightest white = `0x3F`. Entry $00 is the BG backdrop; $10 is the
+sprite-palette colour 0 (transparent).
+
+**Game Gear** uses 4-4-4 BGR (2 bytes per entry, 64 total bytes).
+The runtime has both `sms_load_palette` (32 bytes) and
+`gg_load_palette` (64 bytes).
+
+## Frame heartbeat
+
+```c
+sms_vblank_wait();          /* poll VDP status byte bit 7 until set */
+sms_sat_upload();           /* push shadow SAT to VRAM $3F00 */
+/* update game state */
+```
+
+The vblank poll is the heartbeat. There's also a vblank IRQ if you
+need cycle-accurate timing, but for most games polling is fine.
+
+## Input
+
+`sms_joypad_read()` returns a packed byte with the buttons inverted
+(active high — pressed = 1). Bits:
+
+```
+JOY_UP    0x01
+JOY_DOWN  0x02
+JOY_LEFT  0x04
+JOY_RIGHT 0x08
+JOY_B1    0x10
+JOY_B2    0x20
+```
+
+Edge-detect by AND'ing `pad & !prev`.
+
+## Sound
+
+PSG (SN76489) on port $7F. 4 channels: 3 square waves + 1 noise.
+Writes are byte-wise; the high bit selects "latch register" vs
+"continue previous register".
+
+A full driver is beyond the scope of these scaffolds. For
+playable SFX, manually pulse $7F with the latch-register byte
+followed by data bytes. Real games ship a music driver in WRAM.
+
+## Cartridge layout
+
+```
+$0000-$0037   reset + interrupt vectors (RST jumps)
+$0038         interrupt handler entry (IM 1 mode)
+$0066         NMI entry (pause button on SMS)
+$7FF0-$7FFF   ROM header — "TMR SEGA" trademark + checksum + region/size
+```
+
+Our minimal templates don't bother with the header (real consoles
+boot ROMs even without it; an emulator-side compatibility test
+might flag them). `sms_crt0.s` provides the RST table + the IM 1
+setup that lets vblank IRQs fire.
+
+## Build pipeline
+
+When you call `buildSource({platform:"sms", language:"c"})`:
+
+1. SDCC (z80 port) compiles each `.c` → `.rel` object.
+2. `sms_crt0.s` is auto-injected as the startup file (assembled to
+   `.rel`).
+3. `sdld` links all `.rel` + the z80 standard library → `.ihx`
+   Intel HEX.
+4. The IHX is converted to a flat 32 KB `.sms` ROM.
+
+Loadable via genesis_plus_gx (`loadMedia`).
+
+## Game Gear differences
+
+- Smaller screen: 160×144 visible (vs SMS 256×192). VDP is the
+  same; cropping happens in hardware.
+- 12-bit CRAM (4 bits per channel). Use `gg_load_palette` (64 bytes
+  per palette).
+- Start button on port $00 (separate from the SMS pause-via-NMI).
+- ROM size cap is higher: GG games can go up to 1 MB.
+- Game Gear-specific buttons add port $00 read (Start) and stereo
+  PSG control on port $06.
+
+## Horizontal scrolling (for side-scrollers)
+
+The `platformer` scaffold is single-screen. To make it a side-scroller:
+
+- **Hardware scroll:** write VDP register 8 (horizontal scroll) each frame =
+  `-camX & 0xFF` (the reg scrolls the screen; the name table is 32×28 and
+  wraps). This gives smooth scrolling through one name-table's worth.
+- **Streaming:** for a world wider than 256 px, rewrite the name-table column
+  about to enter view each time `camX` crosses an 8-px boundary — write the
+  next world column's tile entries into the off-screen column. Do VDP writes
+  during vblank.
+- **Fixed HUD / status bar:** VDP register 0 bit 6 ("horizontal scroll lock")
+  freezes the top two rows of the screen regardless of the scroll register —
+  use it for a fixed HUD band while the rest scrolls.
+
+Track `camX` in pixels; actor screen-X = `worldX - camX`. (Game Gear is the
+same VDP — only the visible window differs.)

package/src/platforms/sms/TROUBLESHOOTING.md

@@ -0,0 +1,124 @@
+# Sega Master System / Game Gear — troubleshooting
+
+When something's broken. Read MENTAL_MODEL.md first for the
+"what's going on" version (via `getPlatformDoc({platform:"sms", name:"mental_model"})`).
+
+## "ROM builds but the screen is blank / black"
+
+The VDP starts with display disabled (R1 bit 6 = 0). You have to
+explicitly turn it on AFTER you've uploaded palette + tiles +
+name table:
+
+```c
+sms_vdp_init();       /* sets display OFF as a side effect */
+sms_load_palette(...);
+sms_load_tiles(...);
+sms_set_tilemap_cell(...);
+sms_vdp_display_on(); /* ← without this, blank forever */
+```
+
+If you forget `sms_vdp_display_on()` your ROM boots and runs, but
+the display register R1 keeps bit 6 clear and you see nothing.
+
+## "Sprites are invisible / stuck at top of screen"
+
+Two common modes:
+
+1. **You forgot to call `sms_sat_upload()`.** The SAT shadow lives
+   in WRAM; `sms_sprite_set()` only updates the shadow.
+   `sms_sat_upload()` pushes the shadow to VRAM $3F00. Skip it →
+   the VDP draws whatever stale SAT it had from boot.
+2. **Y = 0xD0 anywhere in the SAT.** The SMS uses Y = 0xD0 as a
+   "stop renderer at this slot" marker. If your first sprite has
+   Y = 0xD0 (or you leave the default after `sms_sprite_init`), NO
+   sprites render. Always set Y to a real value before drawing.
+
+## "Colors look wrong / too dark"
+
+SMS CRAM is **2 bits per channel** (4 levels: 0, 1, 2, 3 → encoded
+as 0x00, 0x01, 0x02, 0x03 in the channel). So:
+
+```
+0x00 = black
+0x3F = white (red=3, green=3, blue=3 — all max)
+0x03 = pure red
+0x0C = pure green
+0x30 = pure blue
+```
+
+If your colours look "washed out greenish," you may be passing
+6-bit-per-channel values that get truncated, or you may have the
+Game Gear's 4-bit-per-channel encoding wrongly applied to SMS.
+Run on a real SMS-mode emulator to confirm.
+
+## "SDCC crashes during compile (dbuf_append_str NULL / aopGet)"
+
+R7-era SDCC sm83 had multiple register-allocator regressions
+(see `feedback_sdcc_sm83_crashes.md`). Most are fixed in the
+4.4.0 we ship with the 8 MB stack patch (R12). If you still hit
+one:
+
+- Wrap aggressive `for (;;) { switch + __sfr write }` loops in
+  `do { ... } while (1)` (matches the bundled `default` template's
+  branchless update pattern).
+- Split very-long functions into smaller ones.
+- Avoid mid-block `uint8_t var = expr;` — hoist to function top
+  (SDCC z80 is C89-strict).
+
+The full list of patterns and workarounds is in
+`src/platforms/sms/lib/README.md` (look for the SMS-14 codegen
+notes).
+
+## "Sound from PSG is silent / distorted"
+
+Three things to check:
+
+1. **PSG writes are byte-wise on port $7F.** A `uint16_t` write
+   only sends the low byte; the high byte is dropped.
+2. **The latch-register byte must come first.** Each PSG channel
+   needs `0x80 | (chan << 5) | (vol & 0x0F)` etc., then the data
+   bytes. Random write order = silent or random noise.
+3. **Audio is disabled in some emulator save-state restores.** Try
+   `reset()` first before debugging.
+
+## "Game Gear ROM boots black / wrong colors"
+
+GG ROMs need:
+
+- 4-bit-per-channel palette (use `gg_load_palette`, not `sms_load_palette`)
+- Lower-left 160×144 area of the 256×192 VDP framebuffer (it's
+  hardware-cropped on the GG screen — content outside that window
+  is invisible)
+- Some GG-specific I/O (port $00 for Start, port $06 for stereo
+  PSG mute control)
+
+If you ported an SMS ROM straight to `.gg` it'll boot and run, but
+the colours will be very dark (2-bit values reinterpreted as 4-bit)
+and the visible area is in the top-left corner.
+
+## "ROM > 32 KB doesn't run"
+
+The default template is single-bank (32 KB). To use the Sega
+mapper for larger ROMs, write `bank_n` to `$FFFE` (slot 1) or
+`$FFFF` (slot 2) before reading from $4000-$7FFF / $8000-$BFFF
+respectively. SDCC's default sm83/z80 link doesn't auto-page;
+you write the bank-switch yourself in code, then `jp` into the
+new bank.
+
+For most agent-driven games, stay in 32 KB and the mapper never
+matters.
+
+## "Save states don't restore VDP state"
+
+genesis_plus_gx (which we use for SMS) snapshots VDP/CRAM/VRAM
+fully. If you find a sprite missing after `loadState`, the cause
+is usually game-side: your shadow OAM lives in WRAM, which IS
+snapshotted, but your `oam_dma_flush`/`sms_sat_upload`-equivalent
+fires *next frame* — so the very first frame after load may show
+stale SAT until your loop ticks once.
+
+## "First build is slow but later ones are fast"
+
+Expected. SDCC z80 + sdasz80 + sdld cold-load takes ~1-2s for
+the WASM mmap + class init. Steady-state builds are sub-second
+thanks to the worker pool (R12).

package/src/platforms/sms/UPSTREAM_SOURCES.md

@@ -0,0 +1,29 @@
+# Master System — source you can read
+
+Trust hierarchy:
+
+1. **Bundled examples** (`examples/sms/templates/*.c`).
+2. **Bundled runtime** — `src/platforms/sms/lib/c/sms_crt0.s`,
+   `vdp_init.c`, `joypad_read.c`, `sprite_table.c`, `sms_sfx.c`,
+   `sms_music.c`. All ~50-100 lines each, fully readable.
+3. **SDCC z80 port** — WASM compiler shipped, source not bundled.
+4. **Upstream GitHub**:
+
+   | What | Upstream |
+   |---|---|
+   | SDCC | http://sdcc.sourceforge.net/ |
+   | genesis_plus_gx libretro (handles SMS) | https://github.com/libretro/Genesis-Plus-GX |
+
+## SMS hardware docs
+
+- **SMS Power!** (canonical homebrew dev hub): https://www.smspower.org/Development/Documents
+- **SN76489 PSG ref**: https://www.smspower.org/Development/SN76489
+- **VDP register reference**: https://www.smspower.org/Development/VDPRegisters
+- **Z80 reference**: https://www.zilog.com/docs/z80/um0080.pdf
+
+## When to use what
+
+- "How does my sprite SAT terminator work?" → MENTAL_MODEL § SAT $D0
+- "SN76489 latch byte layout" → SMS Power PSG ref
+- "VDP mode 4 specifics" → SMS Power VDP registers
+- "genesis_plus_gx doesn't expose register X" → libretro GitHub

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

@@ -0,0 +1,260 @@
+// SMS / Game Gear image-to-tilemap converter (4bpp mode 4).
+//
+// SMS resolution: 256×192 (32 × 24 cells). 4bpp interleaved tile layout:
+//   tile = 32 bytes = 8 rows × 4 bytes/row
+//   each row = p0, p1, p2, p3 in that order (one byte per plane)
+//
+// SMS palette: 32 entries × 6-bit BGR (1 byte each).
+//   Entries 0..15 = BG palette
+//   Entries 16..31 = sprite palette
+//
+// Name table format: each cell is 2 bytes little-endian:
+//   bit 0-8: tile index (0..511)
+//   bit 9:   horizontal flip
+//   bit 10:  vertical flip
+//   bit 11:  palette (0 = BG, 1 = sprite)
+//   bit 12:  priority (1 = above sprites)
+
+import { PNG } from "pngjs";
+
+const W = 256;
+const H = 192;
+
+/** RGB → SMS 6-bit BGR byte (2 bits per channel). */
+function rgbToSmsByte(r, g, b) {
+  const r2 = (r >> 6) & 0x03;
+  const g2 = (g >> 6) & 0x03;
+  const b2 = (b >> 6) & 0x03;
+  return r2 | (g2 << 2) | (b2 << 4);
+}
+
+/** SMS 6-bit byte → RGB triple. */
+function smsByteToRgb(byte) {
+  const r2 = byte & 0x03;
+  const g2 = (byte >> 2) & 0x03;
+  const b2 = (byte >> 4) & 0x03;
+  const expand = (v) => (v << 6) | (v << 4) | (v << 2) | v;
+  return [expand(r2), expand(g2), expand(b2)];
+}
+
+/**
+ * @param {Object} args
+ * @param {Buffer | Uint8Array} args.pngBytes  256×192 PNG, ideally pre-dithered to ≤16 colors.
+ * @returns {{
+ *   chr: Uint8Array,
+ *   nametable: Uint8Array,
+ *   attr: Uint8Array,
+ *   palette: Uint8Array,
+ *   uniqueTilesBeforeMerge: number,
+ *   uniqueTiles: number,
+ *   imageColors: number,
+ *   previewPng: Buffer,
+ * }}
+ */
+export function smsImageToTilemap(args) {
+  const png = PNG.sync.read(Buffer.from(args.pngBytes));
+  if (png.width !== W || png.height !== H) {
+    throw new Error(`SMS image must be ${W}×${H}, got ${png.width}×${png.height}`);
+  }
+
+  // 1) Quantize to ≤16 distinct colors.
+  /** @type {Map<number, number>} */
+  const colorIndex = new Map();
+  const pxIdx = new Uint8Array(W * H);
+  for (let i = 0; i < W * H; i++) {
+    const k = i * 4;
+    const c = rgbToSmsByte(png.data[k], png.data[k + 1], png.data[k + 2]);
+    let idx = colorIndex.get(c);
+    if (idx === undefined) {
+      idx = colorIndex.size;
+      if (idx >= 16) {
+        throw new Error(
+          `SMS 4bpp BG layer takes ≤16 colors; image quantizes to more. ` +
+          `Use \`magick … -colors 16 -dither FloydSteinberg\` first, or ` +
+          `pre-remap against getPlatformPalettePng({platform:"sms"}).`
+        );
+      }
+      colorIndex.set(c, idx);
+    }
+    pxIdx[i] = idx;
+  }
+
+  // 2) Build 32-byte palette (BG only — sprites stay zero).
+  const palette = new Uint8Array(32);
+  for (const [c, idx] of colorIndex) palette[idx] = c;
+
+  // 3) Encode each 8×8 tile. Dedupe + detect h/v flips.
+  const tilesAcross = W / 8;   // 32
+  const tilesDown = H / 8;     // 24
+
+  const makeTile = (tx, ty) => {
+    const t = new Uint8Array(32);
+    for (let row = 0; row < 8; row++) {
+      let p0 = 0, p1 = 0, p2 = 0, p3 = 0;
+      for (let col = 0; col < 8; col++) {
+        const c = pxIdx[(ty * 8 + row) * W + (tx * 8 + col)];
+        if (c & 1) p0 |= 1 << (7 - col);
+        if (c & 2) p1 |= 1 << (7 - col);
+        if (c & 4) p2 |= 1 << (7 - col);
+        if (c & 8) p3 |= 1 << (7 - col);
+      }
+      t[row * 4 + 0] = p0;
+      t[row * 4 + 1] = p1;
+      t[row * 4 + 2] = p2;
+      t[row * 4 + 3] = p3;
+    }
+    return t;
+  };
+
+  const flipH = (tile) => {
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+      let b = tile[i];
+      // Reverse bits in this byte (this row's plane).
+      b = ((b >> 1) & 0x55) | ((b & 0x55) << 1);
+      b = ((b >> 2) & 0x33) | ((b & 0x33) << 2);
+      b = ((b >> 4) & 0x0F) | ((b & 0x0F) << 4);
+      out[i] = b & 0xFF;
+    }
+    return out;
+  };
+  const flipV = (tile) => {
+    const out = new Uint8Array(32);
+    for (let row = 0; row < 8; row++) {
+      const srcRow = 7 - row;
+      out[row * 4 + 0] = tile[srcRow * 4 + 0];
+      out[row * 4 + 1] = tile[srcRow * 4 + 1];
+      out[row * 4 + 2] = tile[srcRow * 4 + 2];
+      out[row * 4 + 3] = tile[srcRow * 4 + 3];
+    }
+    return out;
+  };
+
+  const tileBytesByKey = new Map();   // raw-tile-key → tile-index in chr
+  const chr = [];
+  const nametable = new Uint8Array(tilesAcross * tilesDown * 2);
+
+  const toKey = (t) => {
+    // Hex string of 32 bytes — small enough for Map keys.
+    let s = "";
+    for (let i = 0; i < 32; i++) s += t[i].toString(16).padStart(2, "0");
+    return s;
+  };
+
+  let uniqueBeforeMerge = 0;
+  for (let ty = 0; ty < tilesDown; ty++) {
+    for (let tx = 0; tx < tilesAcross; tx++) {
+      const base = makeTile(tx, ty);
+      uniqueBeforeMerge++;
+      const baseKey = toKey(base);
+      let flipBits = 0;
+      let chosenKey = null;
+      if (tileBytesByKey.has(baseKey)) {
+        chosenKey = baseKey;
+      } else {
+        const h = flipH(base);
+        const v = flipV(base);
+        const hv = flipV(h);
+        const hKey = toKey(h);
+        const vKey = toKey(v);
+        const hvKey = toKey(hv);
+        if (tileBytesByKey.has(hKey))  { chosenKey = hKey; flipBits = 0x02; }      // hflip bit 9
+        else if (tileBytesByKey.has(vKey))  { chosenKey = vKey; flipBits = 0x04; } // vflip bit 10
+        else if (tileBytesByKey.has(hvKey)) { chosenKey = hvKey; flipBits = 0x06; }
+        else {
+          chosenKey = baseKey;
+          tileBytesByKey.set(baseKey, chr.length);
+          chr.push(base);
+        }
+      }
+      const tileIdx = tileBytesByKey.get(chosenKey);
+      // Name table entry (little-endian):
+      //   bit 0-8: tile index (0..511)
+      //   bit 9:   hflip
+      //   bit 10:  vflip
+      //   bit 11:  palette (0 = BG)
+      //   bit 12:  priority
+      const cellOff = (ty * tilesAcross + tx) * 2;
+      nametable[cellOff + 0] = tileIdx & 0xFF;
+      nametable[cellOff + 1] = ((tileIdx >> 8) & 0x01) | flipBits;
+    }
+  }
+
+  // 4) Flatten chr.
+  const chrFlat = new Uint8Array(chr.length * 32);
+  for (let i = 0; i < chr.length; i++) chrFlat.set(chr[i], i * 32);
+
+  // 5) Preview PNG — re-render from the encoded data so the agent can
+  // sanity-check what the SMS will actually display.
+  const preview = new PNG({ width: W, height: H });
+  for (let ty = 0; ty < tilesDown; ty++) {
+    for (let tx = 0; tx < tilesAcross; tx++) {
+      const cellOff = (ty * tilesAcross + tx) * 2;
+      const lo = nametable[cellOff];
+      const hi = nametable[cellOff + 1];
+      const tileIdx = lo | ((hi & 0x01) << 8);
+      const hflip = !!(hi & 0x02);
+      const vflip = !!(hi & 0x04);
+      const tileBase = tileIdx * 32;
+      for (let row = 0; row < 8; row++) {
+        const srcRow = vflip ? 7 - row : row;
+        const p0 = chrFlat[tileBase + srcRow * 4 + 0];
+        const p1 = chrFlat[tileBase + srcRow * 4 + 1];
+        const p2 = chrFlat[tileBase + srcRow * 4 + 2];
+        const p3 = chrFlat[tileBase + srcRow * 4 + 3];
+        for (let col = 0; col < 8; col++) {
+          const srcBit = hflip ? col : 7 - col;
+          const pi = ((p0 >> srcBit) & 1)
+                  | (((p1 >> srcBit) & 1) << 1)
+                  | (((p2 >> srcBit) & 1) << 2)
+                  | (((p3 >> srcBit) & 1) << 3);
+          const [r, g, b] = smsByteToRgb(palette[pi] ?? 0);
+          const o = ((ty * 8 + row) * W + (tx * 8 + col)) * 4;
+          preview.data[o + 0] = r;
+          preview.data[o + 1] = g;
+          preview.data[o + 2] = b;
+          preview.data[o + 3] = 0xff;
+        }
+      }
+    }
+  }
+
+  return {
+    chr: chrFlat,
+    nametable,
+    attr: new Uint8Array(0),  // SMS attributes are per-cell in the nametable
+    palette,
+    uniqueTilesBeforeMerge: uniqueBeforeMerge,
+    uniqueTiles: chr.length,
+    imageColors: colorIndex.size,
+    previewPng: PNG.sync.write(preview),
+  };
+}
+
+/**
+ * Generate a PNG containing every distinct SMS color (64 swatches).
+ * Used as the -remap target for imagemagick dithering.
+ */
+export function smsPalettePng() {
+  const cell = 16;
+  const cols = 8;
+  const rows = 8;
+  const w = cols * cell;
+  const h = rows * cell;
+  const png = new PNG({ width: w, height: h });
+  for (let i = 0; i < 64; i++) {
+    const cx = (i % 8) * cell;
+    const cy = Math.floor(i / 8) * cell;
+    const [r, g, b] = smsByteToRgb(i);
+    for (let y = 0; y < cell; y++) {
+      for (let x = 0; x < cell; x++) {
+        const o = ((cy + y) * w + (cx + x)) * 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);
+}