romdevtools 0.13.0

package/src/platforms/c64/MENTAL_MODEL.md

@@ -0,0 +1,188 @@
+# Commodore 64 — mental model
+
+One page. Read once before you write your first C64 game. The
+TROUBLESHOOTING.md alongside this file is for when something's broken.
+
+The C64 is the architectural outlier of romdev's 6502-class platforms.
+It has KERNAL + BASIC ROMs always available (and your code can call
+them or override them), 64 KB of contiguous RAM with bank-switching to
+get under the I/O area, two CIAs for I/O, and a VIC-II that doesn't
+think in "tiles" — it thinks in **character cells**.
+
+## CPU memory map (6510 — a 6502 with a tiny I/O port)
+
+```
+$0000-$0001   6510 internal I/O — bank-switch control
+$0002-$00FF   zero page
+$0100-$01FF   stack
+$0200-$03FF   KERNAL+BASIC scratch / vectors (rarely touch directly)
+$0400-$07E7   default screen RAM (40×25 char matrix)
+$07E8-$07FF   sprite pointers ($07F8-$07FF = 8 bytes, one per MOB)
+$0800-$9FFF   user RAM (cc65 puts code + data here for typical .prg)
+$A000-$BFFF   BASIC ROM (banked; RAM underneath)
+$C000-$CFFF   RAM (no ROM overlay)
+$D000-$D3FF   VIC-II registers (banked; CHAREN bit selects)
+$D400-$D7FF   SID registers
+$D800-$DBE7   color RAM (1 KB nibble RAM — low 4 bits hold color index)
+$DC00-$DC0F   CIA1 (keyboard, joystick, timers)
+$DD00-$DD0F   CIA2 (serial, VIC bank select, user port)
+$E000-$FFFF   KERNAL ROM (banked; RAM underneath)
+```
+
+The 6510's I/O port at `$0001` selects which ROMs are visible:
+
+```
+bit 0 (LORAM):  1 = BASIC ROM visible at $A000
+bit 1 (HIRAM):  1 = KERNAL ROM visible at $E000
+bit 2 (CHAREN): 0 = char ROM at $D000, 1 = I/O regs visible
+```
+
+Default after boot = `$37` (all three set) — BASIC + KERNAL ROMs +
+I/O regs. Set CHAREN=0 to read the character-set bitmaps from ROM;
+set HIRAM=0 to swap KERNAL out for RAM (useful for low-memory tricks).
+
+## VIC-II — character cells, NOT tiles
+
+The C64's video chip displays 25 rows × 40 cols of 8×8 character
+glyphs. Each cell:
+
+- Screen RAM ($0400) holds the **character code** (0-255).
+- Color RAM ($D800) holds the **color index** (0-15) for that cell.
+  Color RAM is nibble RAM — only the low 4 bits are wired up.
+- The character set itself is at $D000 (ROM) or wherever VIC's char
+  base register points (`VIC_MEMORY` at $D018).
+
+Two character sets in ROM:
+- "Uppercase + graphics": chars $00-$3F = uppercase letters + symbols
+- "Lowercase + uppercase": chars $00-$3F = lowercase + UPPERCASE shifted
+
+You can also point VIC at custom character RAM and write your own
+glyphs (this is how every published C64 game does its art).
+
+## VIC-II screen modes
+
+```
+text         default — 40×25 cells × 8×8 chars, 16 colors per cell
+multicolor   half-res horizontal (40×25 cells, but 4-color cells with shared MC1/MC2)
+hires bitmap 320×200 pixels, 2 colors per 8×8 cell
+multi bitmap 160×200 pixels, 4 colors per 8×8 cell
+```
+
+Most C64 games use either text mode with a custom char set (cheap +
+fast) or multicolor bitmap (more detail but harder to update).
+
+## VIC-II sprites (MOBs)
+
+8 hardware sprites, each:
+- 24×21 pixels (3 bytes/row × 21 rows = 63 bytes; allocated in 64-byte
+  slots so the leftover byte is unused padding)
+- Stored in the VIC's current 16 KB **bank** (default $0000-$3FFF)
+- Located via the **sprite pointer** at $07F8+N: pointer value × 64 =
+  byte address WITHIN the bank
+- Position: `VIC_SPRITE_X(N)` / `VIC_SPRITE_Y(N)` are 8-bit; X high
+  bits live in `VIC_SPRITES_X8` at $D010 (for X >= 256)
+- Color: `VIC_SPR_COL(N)` at $D027+N (single-color sprites)
+- Enable: bit N of `VIC_SPR_ENA` at $D015
+
+Sprite Y is offset 50 px from the screen's top edge; sprite X is
+offset 24 px from the left edge. So `VIC_SPRITE_Y = 50` puts the
+sprite at the visible top-left.
+
+## CIA1 — joysticks + keyboard
+
+CIA1 at $DC00-$DC0F. The chip is dual-purpose:
+- $DC00 (CIA1_PRA): joystick PORT 2 + keyboard column select
+- $DC01 (CIA1_PRB): joystick PORT 1 + keyboard row read
+
+Joystick bits (active LOW — pressed = 0, released = 1):
+```
+bit 0: UP    bit 1: DOWN   bit 2: LEFT
+bit 3: RIGHT bit 4: FIRE
+```
+
+**Convention:** read joystick from PORT 2 (CIA1_PRA) unless you have
+a specific reason not to. Reading PRB clashes with keyboard scanning,
+which is what the KERNAL's IRQ uses to update key state every
+1/60 sec — you'd get garbled input from your jiffy timer.
+
+### Driving input over MCP
+
+The C64 joystick has **one** fire button. Over MCP press it with
+`input({op:'set', b: true})` or the spatial `input({op:'set', south: true})` — both clear
+`$DC00` bit 4 (verified live against vice). `input({op:'set', a: true})` is a **no-op**
+(no second button — not in `input({op:'layout'})`'s `physicalButtons`). So drive fire
+with `b`/`south`, plus the d-pad. ⚠ A cc65 `.prg` only starts after BASIC
+auto-`RUN`s it — step ~70+ frames past load before input/reads register.
+
+## SID — three voices of fame
+
+Three voices at $D400-$D418. Per-voice:
+- 16-bit frequency (`SID_FREQ_LO/HI`)
+- 12-bit pulse-width (for the pulse waveform)
+- Control byte: gate / sync / ring / test / wave-select (triangle / saw /
+  pulse / noise)
+- 16-bit ADSR envelope (`SID_AD`, `SID_SR`)
+
+Global `SID_VOL_MODE` ($D418) holds master volume + filter routing
+bits. SID is famous for sounding incredible with very little code — see
+the `sid_play.s` starter snippet.
+
+**Debugging sound:** `audioDebug({op:'inspect', chip:"sid"})` decodes all 3 voices live —
+waveform, freq→note, pulse-width, ADSR — plus the filter cutoff/resonance/mode.
+Handy for verifying a `sid_play` routine is actually gating notes.
+
+## Cartridge / load file format
+
+The .prg format is dead simple:
+- First 2 bytes = little-endian load address
+- Rest = data, loaded sequentially into RAM starting at that address
+
+cc65 produces .prg files with the load address set to $0801 (BASIC
+start) so they can be `LOAD"*",8,1` / `RUN` from a BASIC prompt. The
+KERNAL handles the load; your code runs from the cc65-generated BASIC
+stub that does a `SYS` to the C entry point.
+
+For game ROMs you typically just let the user load the .prg into the
+emulator and the rest takes care of itself.
+
+## Frame heartbeat
+
+The C64 has no dedicated vblank interrupt by default. Two approaches:
+
+1. **Poll VIC_RASTER** ($D012): waits for the raster to reach line 250+
+   (off the bottom of the visible region) — gives you a reliable per-
+   frame tick. This is what the bundled `hello_sprite` and `tile_engine`
+   templates do.
+2. **Raster interrupt**: program VIC_RASTER + IRQ_ENA to fire an IRQ
+   at a specific line. More complex; required for tricks like
+   mid-screen mode changes, multiplexed sprites, etc.
+
+## Build pipeline
+
+When you call `build({output:'rom', platform:"c64", language:"c"})`:
+
+1. cc65 compiles your `.c` → 6502 `.s`.
+2. ca65 assembles each `.s` → `.o`.
+3. ld65 links + the bundled c64.cfg → `.prg` with a 2-byte load-address
+   header.
+
+Loadable via vice_x64 (`loadMedia`).
+
+## Horizontal scrolling (for side-scrollers)
+
+The `platformer` scaffold is single-screen. C64 scrolling is the fiddliest of
+the platforms because the VIC-II only does a 0-7 px *fine* scroll in hardware;
+moving further is a software char-cell shift.
+
+- **Fine scroll:** the low 3 bits of `$D016` set a 0-7 px horizontal offset.
+  To hide the garbage column that the fine scroll exposes at the edge, switch
+  to 38-column mode (clear `$D016` bit 3) which masks the side borders.
+- **Coarse scroll:** when the fine offset wraps past 7, reset it to 0 and
+  shift the whole **screen RAM** ($0400) AND **color RAM** ($D800) left by one
+  char column, then fill the new rightmost column from your world map. This is
+  ~1000+1000 byte moves — do it across the frame or with the screen split.
+- **Smoothness:** update `$D016` early in the frame (e.g. a raster IRQ) so the
+  fine offset is set before the visible area is drawn.
+
+Track `camX` in pixels: `fine = camX & 7` → `$D016`; `coarseCol = camX >> 3`
+indexes your world map for which columns are on screen.

package/src/platforms/c64/TROUBLESHOOTING.md

@@ -0,0 +1,130 @@
+# Commodore 64 — troubleshooting
+
+When something's broken. Read MENTAL_MODEL.md first
+(via `platform({op:'doc', platform:"c64", name:"mental_model"})`).
+
+## "Screen is blank or filled with the wrong characters"
+
+Three common modes:
+
+1. **You wrote to $0400+ before the KERNAL finished clearing the
+   screen during boot.** cc65's startup code typically runs after the
+   KERNAL clears the screen, so this is rare under cc65 — but if you
+   `org $0801` and run before vector setup, you can lose your writes.
+   Easy fix: wait 2-3 frames after main() entry before drawing.
+2. **VIC_MEMORY ($D018) points at the wrong screen RAM.** Default is
+   $0400 (low nibble of D018 = $1, screen base = $0400). If you
+   accidentally write D018, the VIC reads garbage instead.
+3. **Wrong character set selected.** D018's high nibble selects char
+   base. Default $14 means char base = $1000 (which maps to char ROM
+   at $D000 with CHAREN=0). Set to $16 for the lowercase set.
+
+## "Sprite doesn't appear"
+
+Most common cause: forgot to set the sprite pointer at $07F8+N.
+The sprite enable bit ($D015 bit N) just turns the rendering on;
+the data location is in the pointer slot.
+
+Sprite pointer value × 64 = byte offset within the current VIC bank
+(default bank = $0000-$3FFF). So pointer = $20 means sprite data at
+$20 * $40 = $0800.
+
+Other gotchas:
+- Sprite X is 8-bit, but the visible screen is 320 px wide. For X
+  positions ≥ 256, set the corresponding bit in `VIC_SPRITES_X8`
+  ($D010).
+- Sprite Y offset is 50 (so Y=50 is the visible top edge); X offset
+  is 24. Set Y=0 and your sprite is invisible above the screen.
+- Color RAM stores nibbles ($0..$F), not full bytes. Writing the wrong
+  high nibble has no effect, but writing junk for the low nibble gives
+  unintended colors.
+
+## "Sprite is invisible behind a character cell"
+
+VIC-II has per-sprite background-priority bits at $D01B
+(`VIC_SPR_BG_PRI`). Bit N = 1 means sprite N is drawn BEHIND the
+character matrix (for cells with bit 7 of their color byte set as
+"foreground"). Default = all 0 = sprites in front. If you accidentally
+write $FF to $D01B, all sprites disappear behind the BG layer.
+
+## "POKE / PEEK macro redefinition error"
+
+cc65 already defines POKE / PEEK in `<peekpoke.h>` (and it gets pulled
+in automatically by some other headers, like cbm.h). If you write your
+own:
+
+```c
+#define POKE(addr, val)  (*(volatile uint8_t*)(addr) = (val))
+```
+
+…cc65 complains "Macro redefinition is not identical."
+
+Workarounds:
+- Use cc65's stock POKE / PEEK from peekpoke.h (no volatile, address
+  as integer).
+- Or define yours under different names like `WR` / `RD` — the
+  bundled `tile_engine` template uses this convention.
+
+## "Joystick input feels random / wrong"
+
+Most likely cause: you're reading port 1 (CIA1_PRB at $DC01) instead
+of port 2 (CIA1_PRA at $DC00).
+
+Port 1 input is multiplexed with the keyboard scan matrix. Every 1/60
+sec the KERNAL's IRQ reads CIA1_PRB to populate the key buffer; your
+joystick read happens between IRQ ticks and sees whatever column the
+KERNAL last selected. Result: ghost input.
+
+**Use port 2 (CIA1_PRA) by default.** All bundled C64 templates do.
+
+## "Audio is silent / SID doesn't play"
+
+Three things to check:
+
+1. `SID_VOL_MODE` ($D418) is 0 by default — set it to $0F or higher
+   for any voice to be audible.
+2. The voice's CONTROL register ($D404 + voice*7) needs both a
+   waveform bit AND the GATE bit set:
+   - Wave bits: $10 (triangle), $20 (saw), $40 (pulse), $80 (noise)
+   - GATE bit $01: starts the ADSR envelope. Clear → release phase.
+3. The voice frequency ($D400 + voice*7) is two bytes (LO + HI).
+   Default = 0 = inaudible. SID frequency is a 16-bit value where
+   FREQ = (HZ × 16777216) / 985248. So middle-C ≈ 4467 → write
+   LO=$73, HI=$11.
+
+## "VIC raster wait hangs"
+
+If you do:
+
+```c
+while (PEEK(VIC_RASTER) < 250) { }
+```
+
+and the VIC's interrupt configuration has bit 7 of $D011 set (which is
+the 9th bit of the raster line counter — for lines >= 256), then the
+raster register is effectively 9-bit but you're reading only 8 bits.
+Result: raster appears to wrap weirdly.
+
+Default $D011 = $1B (display on, 25 rows, mode 0, bit 7 = 0). Don't
+write bit 7 of $D011 unless you know what you're doing.
+
+## "cc65 reports 'unresolved external'"
+
+cc65 needs you to link against the c64.cfg system library that
+defines RESET / NMI / IRQ vectors + the BASIC stub. Our build pipeline
+does this automatically; if you're writing a standalone ca65 .s with
+custom org, you may need to provide your own startup.
+
+## "Save state breaks the running game"
+
+vice's snapshot includes CIA state but NOT necessarily every cycle-
+exact VIC register write you made between the snapshot point and the
+next vblank. If your game uses raster IRQs for mid-screen tricks, a
+load-state mid-frame may render garbage for one frame. Game-side
+workaround: re-initialize VIC IRQ vectors at the top of every frame
+loop.
+
+## "First build is slow but later ones are fast"
+
+Expected. cc65 + ca65 + ld65 cold-load is ~1-2s. Steady-state builds
+are sub-second.

package/src/platforms/c64/UPSTREAM_SOURCES.md

@@ -0,0 +1,35 @@
+# Commodore 64 — source you can read
+
+Trust hierarchy:
+
+1. **Bundled examples** (`examples/c64/templates/*.c`).
+2. **Bundled runtime** — `src/platforms/c64/lib/c/c64_sfx.c`,
+   `c64_music.c`, `c64_registers.h`, asm helpers in `lib/*.s`.
+3. **Bundled cc65 C64 libsrc** (R58) at `src/platforms/c64/lib/
+   cc65-src/`. cc65's C64 target: joystick, conio, VIC/SID/CIA
+   helpers, header builder, the BASIC stub.
+4. **Upstream**:
+
+   | What | Upstream |
+   |---|---|
+   | cc65 | https://github.com/cc65/cc65 |
+   | VICE x64 libretro core | https://github.com/libretro/vice-libretro |
+   | VICE proper | https://vice-emu.sourceforge.io/ |
+
+## C64 hardware docs
+
+- **C64 Programmer's Reference Guide** (the canonical book, scanned):
+  https://www.lemon64.com/forum/viewtopic.php?t=44525
+- **codebase64** (modern dev wiki): https://codebase64.org/
+- **VIC-II reference**: https://www.zimmers.net/cbmpics/cbm/c64/vic-ii.txt
+- **SID reference**: https://codebase64.org/doku.php?id=base:start_at_the_beginning_-_setting_up_the_sid
+- **6510 instruction set**: same as 6502 + the I/O port at $0001
+
+## When to use what
+
+- "What's at $D000-$DFFF?" → VIC-II ($D000) / SID ($D400) / CIA1
+  ($DC00) / CIA2 ($DD00) — see `c64_registers.h`
+- "How does the SID envelope work?" → `c64_music.c` ADSR setup
+  + codebase64 SID page
+- "BASIC stub — what's `SYS 2061`?" → `lib/basic_stub.s` header
+- "VICE doesn't expose register X" → libretro vice-libretro

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

@@ -0,0 +1,190 @@
+// C64 image → charset/screen/color conversion.
+//
+// The C64 has no "tilemap" in the NES sense, but its standard hi-res
+// character mode is the direct analog: a 40×25 grid of 8×8 cells, each
+// cell a char code into a 2 KB charset (256 chars × 8 bytes, 1bpp). Per
+// cell you get ONE foreground color (from Color RAM, $D800) over a SINGLE
+// shared background color ($D021). So each 8×8 cell is 2-color.
+//
+// This maps onto the generic imageToTilemap contract:
+//   chr        → charset bytes (deduped 8×8 1bpp chars, ≤256 × 8 = ≤2048 B)
+//   nametable  → screen RAM (1000 bytes, char code per cell)
+//   attr       → color RAM (1000 bytes, low nibble = fg color 0..15 per cell)
+//   palette    → 1 byte: the shared background color index
+//
+// Input must be 320×200, already quantized to the 16-color C64 palette
+// (use getPlatformPalettePng({platform:"c64"}) as the ImageMagick -remap
+// target). Each 8×8 cell may use at most 2 of those colors (one is the
+// global background, the other is that cell's foreground) — hi-res char
+// mode's hard constraint. Cells that violate it are reported.
+
+import { PNG } from "pngjs";
+import { C64_PALETTE } from "./vic.js";
+
+const W = 320;
+const H = 200;
+const COLS = 40;
+const ROWS = 25;
+
+/** nearest C64 palette index for an (r,g,b) — exact match preferred. */
+function nearestC64Index(r, g, b) {
+  let best = 0;
+  let bestD = Infinity;
+  for (let i = 0; i < 16; i++) {
+    const [pr, pg, pb] = C64_PALETTE[i];
+    const d = (pr - r) ** 2 + (pg - g) ** 2 + (pb - b) ** 2;
+    if (d < bestD) { bestD = d; best = i; }
+  }
+  return best;
+}
+
+/**
+ * Convert a 320×200 PNG into C64 hi-res character-mode assets.
+ *
+ * @param {{ pngBytes: Buffer|Uint8Array, backdrop?: number }} args
+ *   backdrop: force a specific palette index (0..15) as the shared
+ *   background color. If omitted, the most-common color is chosen.
+ * @returns {{
+ *   chr: Uint8Array, nametable: Uint8Array, attr: Uint8Array,
+ *   palette: Uint8Array, uniqueTilesBeforeMerge: number, uniqueTiles: number,
+ *   imageColors: number, backgroundColor: number, previewPng: Buffer,
+ *   warnings: string[]
+ * }}
+ */
+export function c64ImageToTilemap(args) {
+  const png = PNG.sync.read(Buffer.from(args.pngBytes));
+  if (png.width !== W || png.height !== H) {
+    throw new Error(`C64 hi-res image must be ${W}×${H}, got ${png.width}×${png.height}`);
+  }
+
+  // Quantize every pixel to a C64 palette index.
+  const pxIdx = new Uint8Array(W * H);
+  const colorHist = new Array(16).fill(0);
+  for (let i = 0; i < W * H; i++) {
+    const k = i * 4;
+    const ci = nearestC64Index(png.data[k], png.data[k + 1], png.data[k + 2]);
+    pxIdx[i] = ci;
+    colorHist[ci]++;
+  }
+
+  // Choose the shared background color: caller override, else most common.
+  let bg = args.backdrop;
+  if (bg == null) {
+    bg = 0;
+    for (let i = 1; i < 16; i++) if (colorHist[i] > colorHist[bg]) bg = i;
+  }
+
+  const warnings = [];
+  const charByKey = new Map();
+  const chars = []; // each: Uint8Array(8)
+  const screen = new Uint8Array(COLS * ROWS);
+  const color = new Uint8Array(COLS * ROWS);
+  let uniqueBefore = 0;
+  let overflowReported = false;
+  let multiColorCells = 0;
+
+  for (let cy = 0; cy < ROWS; cy++) {
+    for (let cx = 0; cx < COLS; cx++) {
+      uniqueBefore++;
+      // Determine this cell's foreground color: the most-common non-bg
+      // color in the cell. Any pixel that's neither bg nor fg is forced
+      // to fg (and counted as a constraint violation).
+      const cellHist = new Array(16).fill(0);
+      for (let y = 0; y < 8; y++) {
+        for (let x = 0; x < 8; x++) {
+          cellHist[pxIdx[(cy * 8 + y) * W + (cx * 8 + x)]]++;
+        }
+      }
+      let fg = -1;
+      for (let i = 0; i < 16; i++) {
+        if (i === bg) continue;
+        if (fg === -1 || cellHist[i] > cellHist[fg]) fg = i;
+      }
+      if (fg === -1) fg = bg; // solid-background cell
+      const distinctNonBg = cellHist.filter((c, i) => c > 0 && i !== bg).length;
+      if (distinctNonBg > 1) multiColorCells++;
+
+      // Encode the 8×8 char: bit set = foreground pixel.
+      const ch = new Uint8Array(8);
+      for (let y = 0; y < 8; y++) {
+        let byte = 0;
+        for (let x = 0; x < 8; x++) {
+          const p = pxIdx[(cy * 8 + y) * W + (cx * 8 + x)];
+          // A pixel is "foreground" if it's not the bg color.
+          if (p !== bg) byte |= 1 << (7 - x);
+        }
+        ch[y] = byte;
+      }
+
+      let key = "";
+      for (const b of ch) key += b.toString(16).padStart(2, "0");
+      let idx = charByKey.get(key);
+      if (idx === undefined) {
+        if (chars.length >= 256) {
+          if (!overflowReported) {
+            warnings.push(
+              `Image needs more than 256 unique chars after dedup — extra cells reuse char 0. ` +
+              `Reduce detail or split across multiple charsets/screens.`
+            );
+            overflowReported = true;
+          }
+          idx = 0;
+        } else {
+          idx = chars.length;
+          charByKey.set(key, idx);
+          chars.push(ch);
+        }
+      }
+      screen[cy * COLS + cx] = idx;
+      color[cy * COLS + cx] = fg & 0x0F;
+    }
+  }
+
+  if (multiColorCells > 0) {
+    warnings.push(
+      `${multiColorCells} of ${COLS * ROWS} cells contain >2 colors (bg + >1 fg). ` +
+      `Hi-res char mode is 2 colors per 8×8 cell — those cells collapsed all non-background ` +
+      `pixels to a single foreground color. For 3-4 colors per cell use multicolor mode ` +
+      `(half horizontal resolution) — not yet implemented; pre-author the image to 2 colors/cell.`
+    );
+  }
+
+  const chrFlat = new Uint8Array(chars.length * 8);
+  for (let i = 0; i < chars.length; i++) chrFlat.set(chars[i], i * 8);
+
+  // Preview: re-render from encoded charset + screen + color.
+  const preview = new PNG({ width: W, height: H });
+  const [bgr, bgg, bgb] = C64_PALETTE[bg];
+  for (let cy = 0; cy < ROWS; cy++) {
+    for (let cx = 0; cx < COLS; cx++) {
+      const charCode = screen[cy * COLS + cx];
+      const fg = color[cy * COLS + cx];
+      const [fr, fgg, fb] = C64_PALETTE[fg];
+      const base = charCode * 8;
+      for (let y = 0; y < 8; y++) {
+        const byte = chrFlat[base + y];
+        for (let x = 0; x < 8; x++) {
+          const on = (byte >> (7 - x)) & 1;
+          const o = ((cy * 8 + y) * W + (cx * 8 + x)) * 4;
+          preview.data[o + 0] = on ? fr : bgr;
+          preview.data[o + 1] = on ? fgg : bgg;
+          preview.data[o + 2] = on ? fb : bgb;
+          preview.data[o + 3] = 0xFF;
+        }
+      }
+    }
+  }
+
+  return {
+    chr: chrFlat,
+    nametable: screen,
+    attr: color,
+    palette: new Uint8Array([bg]),
+    uniqueTilesBeforeMerge: uniqueBefore,
+    uniqueTiles: chars.length,
+    imageColors: colorHist.filter((c) => c > 0).length,
+    backgroundColor: bg,
+    previewPng: PNG.sync.write(preview),
+    warnings,
+  };
+}

package/src/platforms/c64/lib/README.md

@@ -0,0 +1,52 @@
+Commodore 64 starter snippets
+=============================
+
+Hand-vetted boilerplate for cc65-targeted C64 development. cc65 ships C
+as the default language; assembly via ca65 is also supported. The snippets
+here mix C (for the most common workflows) and asm (for where you need
+cycle-level control or are touching VIC-II / SID registers directly).
+
+Files
+-----
+
+- **c64_registers.h** — symbolic names for VIC-II ($D000-$D02E), SID
+  ($D400-$D41C), CIA1/2 ($DC00/$DD00) registers. `#include` from C; ca65
+  imports it as well.
+- **vic_init.s** — boot-time setup: black-out the screen, set border + bg
+  colors, switch char-ROM/RAM banking.
+- **sprite_table.s** — load 8 sprite pixel-data blocks + position + enable
+  + color. The classic "render moving sprites" recipe.
+- **read_joystick.s** — read joystick port 2 (the usual game port) from
+  CIA1 $DC00 into a zp byte. Includes the "fire is bit 4" trap.
+- **sid_play.s** — start a SID voice (waveform + ADSR + gate). Pair with
+  setting frequency from main loop for arpeggios / sound effects.
+- **basic_stub.s** — the canonical 12-byte BASIC stub at $0801 that just
+  does `SYS 2061` (jumps to your machine code at $080D). Lets your program
+  start with `LOAD"NAME",8,1` then `RUN`.
+
+Toolchain
+---------
+
+Build via `build({output:'rom', platform: "c64", source: <C or asm>})`. cc65
+auto-sniffs C vs asm; for explicit control pass `language: "c"` or `"asm"`.
+
+Foot-guns
+---------
+
+1. **The 6510's I/O port at $00/$01 controls ROM banking.** Writing the
+   wrong value can hide the KERNAL or character ROM. Default is $37
+   (LORAM=1, HIRAM=1, CHAREN=1) which means BASIC + KERNAL + I/O are all
+   visible. Most games don't change this.
+2. **VIC bank select is in CIA2 $DD00 bits 0-1** (inverted). VIC sees
+   one of 4 × 16 KB banks of main RAM. Default = bank 0 ($0000-$3FFF),
+   which puts screen RAM at $0400 and char ROM at $1000 (via mirror).
+3. **Color RAM is 4-bit only.** $D800-$DBE7 stores the foreground color
+   nibble for each text cell — only the low 4 bits are used; high bits
+   read back as garbage.
+4. **The IRQ vector at $FFFE points through $0314/$0315 by default**
+   (KERNAL interrupt thunk). To install your own raster IRQ, write your
+   handler addr to $0314/$0315.
+5. **Sprite pixel data lives in RAM, not VIC.** $D000-$D02E only stores
+   X/Y/color/enable. The actual 64-byte pixel block per sprite is at
+   `screen_ram[$3F8 + sprite_index] × 64` — write that address to point
+   at your sprite data.

package/src/platforms/c64/lib/basic_stub.s

@@ -0,0 +1,25 @@
+; ── BASIC stub: SYS 2061 ────────────────────────────────────────────
+; The standard 12-byte BASIC bootstrap at $0801 that lets a user type
+; `LOAD"NAME",8,1` followed by `RUN`. The stub is a one-line BASIC
+; program tokenized to SYS 2061, where 2061 = $080D = the first byte
+; AFTER the stub. So your machine-code main routine should start at $080D.
+;
+; Bytes:
+;   $0801  $0B $08   ; pointer to next BASIC line ($080B)
+;          $0A $00   ; line number 10
+;          $9E       ; SYS token
+;          "2061"    ; ASCII "2061"
+;          $00       ; end of statement
+;          $00 $00   ; end of BASIC program (null pointer)
+;
+; After this stub, put `.org $080D` (or just continue assembling) and
+; place your real main routine there.
+
+.segment "STARTUP"
+    .word $080B                ; next line pointer
+    .word 10                   ; line number
+    .byte $9E                  ; SYS
+    .byte "2061", $00          ; "2061" + line terminator
+    .word $0000                ; end-of-program
+
+; Your code starts at $080D — define your reset entry there.