romdev-mcp 0.1.1

package/src/platforms/atari7800/lib/palette_load.asm

@@ -0,0 +1,53 @@
+; ── Load 8 palettes + backdrop ─────────────────────────────────────
+; Copies 25 bytes (1 backdrop + 8 palettes × 3 colors) into the MARIA
+; palette registers. Each palette index 0 in a sprite refers to BACKGRND
+; ($20); indices 1/2/3 refer to PnC1/PnC2/PnC3.
+;
+; Pass a pointer to a 25-byte palette block in ZP $80/$81 before JSR.
+
+.include "maria_registers.h"
+
+PAL_PTR_LO = $80
+PAL_PTR_HI = $81
+
+.proc palette_load
+    LDY #0
+    ; backdrop ($20)
+    LDA (PAL_PTR_LO),Y
+    STA BACKGRND
+    INY
+    ; palette 0 ($21-$23)
+    LDX #0
+:   LDA (PAL_PTR_LO),Y
+    STA P0C1,X
+    INX
+    INY
+    CPX #3
+    BNE :-
+    ; palette 1 ($25-$27)
+    LDX #0
+:   LDA (PAL_PTR_LO),Y
+    STA P1C1,X
+    INX
+    INY
+    CPX #3
+    BNE :-
+    ; palette 2..7 follow the same pattern; for brevity callers usually
+    ; copy with a generic loop (see palette_load_loop below).
+    RTS
+.endproc
+
+; Slower but compact: load a flat palette table by walking a parallel
+; address table. Each entry is the MARIA register address for the
+; palette slot.
+.segment "RODATA"
+PALETTE_ADDR_TABLE:
+    .byte BACKGRND
+    .byte P0C1, P0C2, P0C3
+    .byte P1C1, P1C2, P1C3
+    .byte P2C1, P2C2, P2C3
+    .byte P3C1, P3C2, P3C3
+    .byte P4C1, P4C2, P4C3
+    .byte P5C1, P5C2, P5C3
+    .byte P6C1, P6C2, P6C3
+    .byte P7C1, P7C2, P7C3

package/src/platforms/atari7800/lib/read_pad.asm

@@ -0,0 +1,57 @@
+; ── Read 7800 joystick + fire buttons ──────────────────────────────
+; The 7800 ports work via RIOT just like the 2600 PLUS analog inputs:
+;   SWCHA ($280)    — directional bits (active-low) for both sticks
+;   INPT0-3 ($08-$0B) — analog input dump (latched paddles, etc.)
+;   INPT4-5 ($0C-$0D) — digital fire button (active-low)
+;
+; 7800 ProLine controllers have TWO fire buttons. The right button
+; appears on INPT0/INPT2 (or INPT1/INPT3 depending on the port — INPTCTRL
+; selects between 2-button and 1-button modes).
+
+.include "maria_registers.h"
+
+JOY0_STATE = $90        ; bits 7-4 = right/left/down/up (active-low cleared)
+JOY1_STATE = $91
+FIRE0_R    = $92        ; bit 7 = right-fire pressed
+FIRE0_L    = $93        ; bit 7 = left-fire pressed
+FIRE1_R    = $94
+FIRE1_L    = $95
+
+.proc read_pad
+    LDA SWCHA
+    PHA
+    AND #$F0            ; upper nibble = joystick 0
+    EOR #$F0            ; invert → 1 = direction held
+    STA JOY0_STATE
+
+    PLA
+    AND #$0F            ; lower nibble = joystick 1
+    ASL                 ; shift to upper for symmetric storage
+    ASL
+    ASL
+    ASL
+    EOR #$F0
+    STA JOY1_STATE
+
+    ; Digital fire buttons (INPT4 = stick 0, INPT5 = stick 1).
+    ; Active-low, so EOR to flip sense.
+    LDA $0C
+    EOR #$80
+    STA FIRE0_R
+
+    LDA $0D
+    EOR #$80
+    STA FIRE1_R
+
+    ; Left-fire on 7800 ProLine — read from INPT0 / INPT2 (latched analog).
+    ; INPTCTRL=$01 at boot routes "2-button" mode. Bit 7 = button.
+    LDA $08
+    EOR #$80
+    STA FIRE0_L
+
+    LDA $0A
+    EOR #$80
+    STA FIRE1_L
+
+    RTS
+.endproc

package/src/platforms/atari7800/lib/vblank_wait.asm

@@ -0,0 +1,16 @@
+; ── Wait for next vblank ───────────────────────────────────────────
+; MSTAT bit 7 is set during vertical blanking (MARIA is not currently
+; rendering). Spin until we see vblank starting (transition 0 → 1).
+; Useful as the sync point for per-frame game updates.
+
+.include "maria_registers.h"
+
+.proc vblank_wait
+    ; Wait for vblank to clear first (we might already be in it).
+:   LDA MSTAT
+    BMI :-
+    ; Then wait for it to set.
+:   LDA MSTAT
+    BPL :-
+    RTS
+.endproc

package/src/platforms/atari7800/maria.js

@@ -0,0 +1,220 @@
+// Atari 7800 MARIA helpers.
+//
+// MARIA is the 7800's display chip — fundamentally different from the 2600's
+// TIA. It reads a "display list" from RAM each scanline, where each entry
+// points at a chunk of pixel data + says how to draw it. No tile maps in
+// the conventional sense — just lists of (sprite/character) draws per zone.
+//
+// Memory layout (6502 sees it):
+//   $0000-$001F  MARIA + TIA register file (writes only; some MARIA regs)
+//   $0020-$003F  MARIA palette + control + scrolling regs
+//   $0040-$00FF  zero-page RAM
+//   $0100-$01FF  stack
+//   $0140-$017F  shadow MARIA regs (writes only)
+//   $0180-$01BF  shadow registers (P1C1 etc)
+//   $01C0-$01FF  more shadow regs
+//   $1800-$27FF  4 KB main RAM
+//   $4000-$FFFF  cart ROM
+//
+// MARIA palette: 8 software palettes × 4 colors. Each color is one byte
+// from the 256-color master palette (4 hues × 16 luma sweeps × 4 levels —
+// see NTSC master).
+//
+// memory_ram[65536] (returned via "system_ram") is the full 6502 address
+// space — agents read $20-$3F to get MARIA regs, $1800-$27FF for RAM.
+
+import { PNG } from "pngjs";
+
+/**
+ * Atari 7800 NTSC master palette — 256 colors arranged as 16 hues × 16
+ * luminance levels. The 16 luma levels make sweeps smoother than the
+ * 2600's 8. Color byte format: (hue << 4) | lum.
+ *
+ * This is an approximation of the canonical 7800 palette used by
+ * homebrew (matches what prosystem renders).
+ */
+export const A78_PALETTE = (() => {
+  // Approximate NTSC 7800 chart — same hue arrangement as 2600 but with
+  // 16 luma levels instead of 8.
+  const hues = [
+    { r: 0x00, g: 0x00, b: 0x00 },   // 0: grayscale
+    { r: 0x40, g: 0x40, b: 0x00 },
+    { r: 0x68, g: 0x28, b: 0x00 },
+    { r: 0x80, g: 0x18, b: 0x00 },
+    { r: 0x84, g: 0x00, b: 0x18 },
+    { r: 0x78, g: 0x00, b: 0x58 },
+    { r: 0x48, g: 0x00, b: 0x78 },
+    { r: 0x14, g: 0x00, b: 0x84 },
+    { r: 0x00, g: 0x18, b: 0x88 },
+    { r: 0x00, g: 0x2C, b: 0x78 },
+    { r: 0x00, g: 0x44, b: 0x54 },
+    { r: 0x00, g: 0x54, b: 0x14 },
+    { r: 0x14, g: 0x60, b: 0x00 },
+    { r: 0x40, g: 0x58, b: 0x00 },
+    { r: 0x68, g: 0x48, b: 0x00 },
+    { r: 0x70, g: 0x30, b: 0x00 },
+  ];
+  const out = [];
+  for (let h = 0; h < 16; h++) {
+    for (let l = 0; l < 16; l++) {
+      const base = hues[h];
+      const t = l / 15;
+      const r = Math.round(base.r * 0.5 + 255 * t * 0.5);
+      const g = Math.round(base.g * 0.5 + 255 * t * 0.5);
+      const b = Math.round(base.b * 0.5 + 255 * t * 0.5);
+      out.push([r, g, b]);
+    }
+  }
+  return out;
+})();
+
+/** Atari 7800 color byte → RGB triple. */
+export function a78ColorToRgb(byte) {
+  return A78_PALETTE[byte & 0xFF];
+}
+
+/** Render the 7800 master palette as a 16×16 PNG. */
+export function renderA78MasterPalettePng() {
+  const cell = 16;
+  const w = 16 * cell;
+  const h = 16 * cell;
+  const png = new PNG({ width: w, height: h });
+  for (let i = 0; i < 256; i++) {
+    const hue = i >> 4;
+    const lum = i & 0x0F;
+    const cx = lum * cell;
+    const cy = hue * cell;
+    const [r, g, b] = A78_PALETTE[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);
+}
+
+// ─── MARIA register decode ────────────────────────────────────────
+
+/**
+ * Decode MARIA registers from a slice of the 6502 address space (regs
+ * live at $0020-$003F). Input: 32-byte buffer starting at $20.
+ */
+export function decodeMariaRegs(bytes20) {
+  const b = bytes20;
+  return {
+    background: { byte: b[0x00], rgb: a78ColorToRgb(b[0x00]) },
+    palette0:   colorTriplet(b, 0x01),   // P0C1, P0C2, P0C3 at $21/22/23
+    palette1:   colorTriplet(b, 0x06),   // $26/27/28
+    palette2:   colorTriplet(b, 0x0A),   // $2A/2B/2C
+    palette3:   colorTriplet(b, 0x0E),   // $2E/2F/30
+    palette4:   colorTriplet(b, 0x12),   // $32/33/34
+    palette5:   colorTriplet(b, 0x16),   // $36/37/38
+    palette6:   colorTriplet(b, 0x1A),   // $3A/3B/3C
+    palette7:   colorTriplet(b, 0x1E),   // $3E/3F/00 (P7C3 lives at $40 — caveat)
+    ctrl: {
+      hex: "0x" + b[0x1C].toString(16).toUpperCase().padStart(2, "0"),
+      // CTRL bits: 0=color kill, 1=DMA enable, 2=character control width,
+      // 3=border control, 4=kangaroo mode, 5-6=read mode, 7=color burst
+      colorKill:       !!(b[0x1C] & 0x80),
+      dmaDisable:      !!(b[0x1C] & 0x40),
+      characterWidth:  (b[0x1C] & 0x10) ? "2-byte" : "1-byte",
+      borderControl:   (b[0x1C] & 0x08) ? "border" : "none",
+      kangarooMode:    !!(b[0x1C] & 0x04),
+      readMode:        (b[0x1C] >> 1) & 0x01,
+      colorBurst:      !!(b[0x1C] & 0x01),
+    },
+  };
+}
+
+function colorTriplet(b, baseOffset) {
+  const c1 = b[baseOffset];
+  const c2 = b[baseOffset + 1];
+  const c3 = b[baseOffset + 2];
+  return [
+    { byte: c1, rgb: a78ColorToRgb(c1) },
+    { byte: c2, rgb: a78ColorToRgb(c2) },
+    { byte: c3, rgb: a78ColorToRgb(c3) },
+  ];
+}
+
+/**
+ * Decode the MARIA palette + render a swatch PNG.
+ *   8 palettes × 4 colors (color 0 = backgroundColor shared, then P[n]C1/C2/C3).
+ */
+export function snapshotPalette(host) {
+  const ram = host.readMemory("system_ram", 0x0020, 0x20);
+  const decoded = decodeMariaRegs(ram);
+  const bg = decoded.background;
+  const palettes = [
+    [bg, ...decoded.palette0],
+    [bg, ...decoded.palette1],
+    [bg, ...decoded.palette2],
+    [bg, ...decoded.palette3],
+    [bg, ...decoded.palette4],
+    [bg, ...decoded.palette5],
+    [bg, ...decoded.palette6],
+    [bg, ...decoded.palette7],
+  ];
+  // Render 8×4 grid.
+  const cell = 24;
+  const w = 4 * cell;
+  const h = 8 * cell;
+  const png = new PNG({ width: w, height: h });
+  for (let p = 0; p < 8; p++) {
+    for (let c = 0; c < 4; c++) {
+      const [r, g, b] = palettes[p][c].rgb;
+      for (let y = 0; y < cell; y++) {
+        for (let x = 0; x < cell; x++) {
+          const o = ((p * cell + y) * w + (c * cell + x)) * 4;
+          png.data[o + 0] = r;
+          png.data[o + 1] = g;
+          png.data[o + 2] = b;
+          png.data[o + 3] = 0xff;
+        }
+      }
+    }
+  }
+  // Flatten to generic {index, r, g, b, rawWord}[] (32 entries).
+  const colors = [];
+  for (let p = 0; p < 8; p++) {
+    for (let c = 0; c < 4; c++) {
+      const entry = palettes[p][c];
+      colors.push({
+        index: p * 4 + c,
+        r: entry.rgb[0],
+        g: entry.rgb[1],
+        b: entry.rgb[2],
+        rawWord: entry.byte,
+        paletteEntry: { palette: p, colorIndex: c },
+      });
+    }
+  }
+  return { colors, png: PNG.sync.write(png), regs: decoded };
+}
+
+// ─── 6502 CPU state decode (shares format with 2600) ──────────────
+
+export function decodeA78CpuState(b) {
+  const pc = b[0] | (b[1] << 8);
+  const p = b[5];
+  return {
+    pc,
+    sp: 0x100 | b[6],
+    registers: { A: b[2], X: b[3], Y: b[4], P: p, SP: b[6] },
+    flags: {
+      N: !!(p & 0x80),
+      V: !!(p & 0x40),
+      B: !!(p & 0x10),
+      D: !!(p & 0x08),
+      I: !!(p & 0x04),
+      Z: !!(p & 0x02),
+      C: !!(p & 0x01),
+      raw: "0x" + p.toString(16).toUpperCase().padStart(2, "0"),
+    },
+  };
+}

package/src/platforms/c64/MENTAL_MODEL.md

@@ -0,0 +1,175 @@
+# 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.
+
+## 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.
+
+## 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 `buildSource({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 `getPlatformDoc({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