romdevtools 0.13.0

package/src/platforms/gg/song.js

@@ -0,0 +1,189 @@
+// Game Gear (SN76489 PSG) song compiler — a simple note/duration song → the
+// music_note_t table the bundled driver (lib/c/gg_music.c + gg_music.h) plays.
+//
+// This is NOT a port of an external tool: there's no single canonical Game Gear
+// "song compiler" — the playable format is whatever OUR driver reads. gg_music's
+// engine walks an array of `music_note_t` rows, one per note, advancing one note
+// per call to music_update() (once per 60 Hz frame). Each row is:
+//
+//   typedef struct {
+//     uint16_t note;   // SN76489 10-bit freq divider, or 0 for rest
+//     uint8_t  dur;    // duration in frames (60 Hz); 0 = end-of-song
+//   } music_note_t;     // packed as 3 bytes here: note_lo, note_hi, dur
+//
+//   ...rows...
+//   { 0, 0 }            // end-of-song sentinel (note 0 AND dur 0)
+//
+// A "note" is a pre-baked SN76489 tone-register divider, NOT Hz. The chip latches
+// this 10-bit value into the divide-by-N counter of one tone channel; the output
+// frequency is  PSG_CLOCK / (32 * divider). So to author a note we invert that:
+//
+//   divider = round( 3579545 / (32 * freq_hz) )     // NTSC PSG clock 3.579545 MHz
+//
+// (3579545 / 32 = 111860.78 — the chip's max tone update rate.) Higher divider =
+// LOWER pitch. The divider is 10-bit, so valid range is 1..1023; 0 means rest
+// (the engine silences the channel). divider==1 is the highest tone the chip can
+// make (~111.86 kHz, inaudible); musically useful values sit in ~107..1023.
+//
+// Input: a compact song — an array of {note, dur} (or shorthand strings). The note
+// is a scientific-pitch name ("C4", "A#3", "G-5") or a raw divider ({div: 254}).
+// We resolve names to Hz via equal temperament around A4=440 (configurable), then
+// to a divider via the formula above. Output: the 3-byte-per-row table + the
+// {0,0} sentinel, either as raw bytes or as a C `music_note_t[]` block to drop
+// straight into gg_music.c.
+
+/** Semitone index within an octave for each note letter (C=0). */
+const NOTE_BASE = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
+
+/** NTSC SN76489 PSG clock in Hz (Game Gear / SMS). */
+export const PSG_CLOCK = 3579545;
+
+/** Tone divider is 10 bits on the SN76489. */
+const DIVIDER_MAX = 0x3ff; // 1023
+
+/**
+ * Parse a scientific-pitch note name ("C4", "A#3", "Gb5", "C-4") to an absolute
+ * semitone number where C0 = 0, C4 = 48 (so A4 = 57). Copied from the SNES song
+ * compiler so the two files stay independent.
+ * @param {string} name
+ * @returns {number} absolute semitone index
+ */
+export function noteToSemitone(name) {
+  const m = /^([A-Ga-g])([#b-]?)(-?\d+)$/.exec(String(name).trim());
+  if (!m) throw new Error(`GG song: bad note name "${name}" (expected like "C4", "A#3", "Gb5").`);
+  const letter = m[1].toUpperCase();
+  let semi = NOTE_BASE[letter];
+  if (m[2] === '#') semi += 1;
+  else if (m[2] === 'b') semi -= 1;
+  // '-' is just a separator (FamiTracker-style "C-4"), no accidental.
+  const octave = parseInt(m[3], 10);
+  return octave * 12 + semi;
+}
+
+/**
+ * Equal-temperament frequency (Hz) for an absolute semitone, tuned so that
+ * `a4Semi` (default A4 = semitone 57) sounds at `a4Hz` (default 440).
+ * @param {number} semi   absolute semitone index (C0 = 0)
+ * @param {number} [a4Hz=440]
+ * @param {number} [a4Semi]  absolute semitone of the A4 reference (default 57)
+ * @returns {number} frequency in Hz
+ */
+export function semitoneToHz(semi, a4Hz = 440, a4Semi = noteToSemitone('A4')) {
+  return a4Hz * Math.pow(2, (semi - a4Semi) / 12);
+}
+
+/**
+ * SN76489 tone divider for a frequency.
+ *   divider = round( PSG_CLOCK / (32 * freq_hz) )
+ * Clamped to the chip's 10-bit range (1..1023). This is the exact formula the
+ * driver header documents and its NOTE_* table was baked with.
+ * @param {number} hz   frequency in Hz
+ * @param {number} [clock=PSG_CLOCK]
+ * @returns {number} 10-bit divider value
+ */
+export function hzToDivider(hz, clock = PSG_CLOCK) {
+  if (!(hz > 0)) throw new Error(`GG song: frequency must be > 0 (got ${hz}).`);
+  const d = Math.round(clock / (32 * hz));
+  return Math.max(1, Math.min(DIVIDER_MAX, d));
+}
+
+/**
+ * Convenience: scientific-pitch note name → SN76489 divider.
+ * @param {string} name  e.g. "A4"
+ * @param {object} [opts]
+ * @param {number} [opts.a4Hz=440]
+ * @param {number} [opts.clock=PSG_CLOCK]
+ * @returns {number} 10-bit divider value
+ */
+export function noteToDivider(name, opts = {}) {
+  const semi = noteToSemitone(name);
+  const hz = semitoneToHz(semi, opts.a4Hz ?? 440);
+  return hzToDivider(hz, opts.clock ?? PSG_CLOCK);
+}
+
+/**
+ * Compile a song to the gg_music music_note_t row table.
+ *
+ * @param {object} song
+ * @param {Array<{note?:string, div?:number, dur?:number, ticks?:number}|string>} song.rows
+ *   One entry per note. `{note:"C4", dur:18}` resolves the divider from the name;
+ *   `{div:254, dur:18}` uses a raw 10-bit divider. A bare string "C4" or "C4:18"
+ *   is shorthand (default duration from `song.defaultDur`). A `null`/`"rest"`
+ *   entry (or `{note:"rest"}`) emits divider 0 — the engine silences the channel
+ *   for that row's duration, which is a true musical rest on this driver.
+ * @param {number} [song.a4Hz=440]  concert-A reference for equal temperament.
+ * @param {number} [song.clock=PSG_CLOCK]  PSG clock (Hz); NTSC GG/SMS = 3579545.
+ * @param {number} [song.defaultDur=18]  duration (frames) for shorthand entries.
+ * @param {string} [song.name="song0"]   C array identifier in the emitted snippet.
+ * @returns {{ bytes: Uint8Array, rows: number, cSource: string, asm: string }}
+ *   bytes = the raw table (3 bytes/row: note_lo, note_hi, dur) + a {0,0} sentinel
+ *   (3 trailing zero bytes). cSource = a `music_note_t[]` C block. `asm` is an
+ *   alias of `cSource` so callers expecting the SNES `.asm` field still work.
+ */
+export function compileSong(song) {
+  if (!song || !Array.isArray(song.rows)) {
+    throw new Error('GG song: expected { rows: [...] }.');
+  }
+  const a4Hz = song.a4Hz ?? 440;
+  const clock = song.clock ?? PSG_CLOCK;
+  const defaultDur = song.defaultDur ?? 18;
+  const arrName = song.name ?? 'song0';
+
+  const out = [];
+  const cRows = [];
+
+  for (const raw of song.rows) {
+    let note, div, dur;
+    if (typeof raw === 'string') {
+      // "C4" or "C4:18"
+      const [n, d] = raw.split(':');
+      note = n;
+      dur = d != null ? parseInt(d, 10) : defaultDur;
+    } else {
+      note = raw.note;
+      div = raw.div;
+      // accept `ticks` as a synonym for `dur` so SNES-shaped songs reuse cleanly
+      dur = raw.dur ?? raw.ticks ?? defaultDur;
+    }
+    if (!Number.isInteger(dur) || dur < 1 || dur > 255) {
+      throw new Error(`GG song: dur ${dur} out of range 1..255.`);
+    }
+
+    let label;
+    if (div == null) {
+      if (note == null || note === 'rest' || note === null) {
+        div = 0; // true rest — driver silences the channel
+        label = 'rest';
+      } else {
+        div = noteToDivider(note, { a4Hz, clock });
+        label = note;
+      }
+    } else {
+      label = `div=${div}`;
+    }
+    if (!Number.isInteger(div) || div < 0 || div > DIVIDER_MAX) {
+      throw new Error(`GG song: divider ${div} out of 10-bit range 0..${DIVIDER_MAX}.`);
+    }
+
+    const lo = div & 0xff;
+    const hi = (div >> 8) & 0xff; // top 2 bits of the 10-bit divider
+    out.push(lo, hi, dur & 0xff);
+    cRows.push(`  { ${String(div).padStart(4, ' ')}, ${String(dur).padStart(3, ' ')} },  /* ${label} */`);
+  }
+
+  // End-of-song sentinel {0, 0}: note 0 AND dur 0. Packed as 3 zero bytes.
+  out.push(0x00, 0x00, 0x00);
+  cRows.push('  { 0, 0 },  /* end-of-song sentinel */');
+
+  const cSource =
+    `static const music_note_t ${arrName}[] = {\n${cRows.join('\n')}\n};\n`;
+
+  return {
+    bytes: new Uint8Array(out),
+    rows: song.rows.length,
+    cSource,
+    asm: cSource, // alias for parity with the SNES compiler's { asm } shape
+  };
+}
+
+export default compileSong;

package/src/platforms/index.js

@@ -0,0 +1,7 @@
+// Platform-specific interpretation modules.
+//
+// These do NOT live in the host. They are layers on top — symbol parsing,
+// tile decoders, palette readers, etc. Per platform.
+//
+// Empty for now; modules added per platform as we ship them.
+export {};

package/src/platforms/lynx/MENTAL_MODEL.md

@@ -0,0 +1,248 @@
+# Atari Lynx — mental model
+
+The first handheld with color + hardware-blitter sprites. 6502-class
+CPU + two custom chips (Suzy + Mikey). cc65 targets it natively;
+handy emulates it.
+
+## CPU + memory
+
+- **65SC02** at ~4 MHz (CMOS 6502 variant).
+- **64 KB RAM** (entire address space is RAM after boot).
+- ROM is *paged* through a mapper — the cartridge has the ROM, paged
+  in via Mikey-controlled bank-switching. Most homebrew fits in a
+  single 64KB image.
+
+## Suzy (sprite/blitter chip)
+
+Suzy is a **hardware sprite blitter**. You build a sprite-control-block
+(SCB) in RAM describing what to draw, write its address to
+`SCB_NEXT_LO/HI`, kick the blitter via the `SPRGO` bit — Suzy walks
+the SCB list and renders all sprites at once into the framebuffer.
+
+cc65's TGI driver wraps this behind `tgi_install` + `tgi_bar` /
+`tgi_setcolor` / `tgi_outtextxy` — you get rectangle + text drawing
+without writing SCBs manually. For pixel-level sprites use raw Suzy
+calls or `tgi_sprite(scb_ptr)`.
+
+## Mikey (everything else)
+
+Mikey handles:
+- **Display** — 160×102 visible viewport, 4bpp paletted (16 colors)
+- **Palette** — 16 entries × 12-bit RGB at `$FDA0-$FDBF`
+- **Audio** — 4 LFSR-based voices at `$FD20-$FD3F`. Configurable
+  feedback taps + period. Lower period = higher pitch.
+- **Timers** — 8 hardware timers; one drives the audio sample rate
+- **Joystick** — read via SWITCHES register at `$FCB0`. cc65 provides
+  `joy_read(JOY_1)` + `JOY_LEFT/RIGHT/UP/DOWN/BTN_1/BTN_2` macros.
+
+**Live debug:** `audioDebug({op:'inspect', chip:"mikey"})` decodes the 4 audio voices
+(volume, period→freq→note, LFSR state); `palette({source:'live'})` reads the 16-entry
+palette; `background({view:'renderState'})` shows DISPCTL + the display base address;
+`cpu({op:'read'})` reads the 65C02; `breakpoint({on:'write'})` is the write watchpoint. **Sprites
+are the exception** — the Lynx has no fixed OAM (sprites are SCB linked lists
+walked by Suzy), so `sprites({op:'inspect'})` returns the SCB list head ($FC10/$FC11) and
+you walk the chain over `system_ram`, rather than reading a sprite table.
+
+## Frame heartbeat (cc65 + tgi)
+
+```c
+#include <tgi.h>
+#include <joystick.h>
+#include <lynx.h>
+#include "lynx_sfx.h"
+
+void main(void) {
+    tgi_install(&lynx_160_102_16_tgi);
+    tgi_init();
+    joy_install(&lynx_stdjoy_joy);
+    sfx_init();
+
+    for (;;) {
+        tgi_clear();
+        /* draw via tgi_bar / tgi_setcolor / tgi_outtextxy */
+        tgi_updatedisplay();   /* blocks until vblank, flips buffers */
+        sfx_update();
+        /* read joy_read(JOY_1) + update state */
+    }
+}
+```
+
+`tgi_updatedisplay()` is the frame heartbeat — it ping-pongs the
+double-buffered display and waits for vblank.
+
+## Drawing many rectangles in one frame (game scaffold pattern)
+
+The minimal example above draws "one rect per frame." For an actual
+game with HUD + background + sprites you'll do many tgi_bar / tgi_setcolor
+pairs per frame. The pattern that works:
+
+```c
+for (;;) {
+    /* 1. Fill the entire framebuffer with the BG color FIRST. This
+     *    erases the previous frame on the back-page (Lynx TGI is
+     *    double-buffered — see below). */
+    tgi_setcolor(C_BG);
+    tgi_bar(0, 0, 159, 101);
+
+    /* 2. Draw EVERYTHING from scratch every frame: HUD, scoreboard,
+     *    sprites, text. The back-page was just blanked; whatever you
+     *    don't draw won't appear. */
+    draw_hud();
+    draw_scoreboard();
+    draw_basket();
+    for (i = 0; i < MAX_SPRITES; i++) draw_sprite(i);
+
+    /* 3. Swap pages — what you just drew becomes visible at next vblank. */
+    tgi_updatedisplay();
+
+    /* 4. Update game state for next frame. */
+    pad = joy_read(JOY_1);
+    update_world(pad);
+}
+```
+
+**Don't try to "persist" anything between frames** by drawing it once
+outside the loop — the back-page gets blanked every iteration. Every
+visible thing must be re-drawn every frame. This is unlike NES/SMS/GG
+where the BG nametable persists in VRAM.
+
+## Double-buffering
+
+cc65's Lynx TGI driver maintains TWO display pages and the vblank IRQ
+flips between them on `tgi_updatedisplay()`. While the user sees page
+A, your `tgi_bar` calls write to page B. After update, page B is
+shown and you start drawing on page A.
+
+Practical consequence: **`tgi_updatedisplay` is non-blocking** — it
+just sets a swap-request flag. The actual swap happens in the next
+vblank IRQ. If your loop iterates faster than vblank, you'll request
+swaps that get coalesced. That's fine for steady-state rendering, but
+it means there's no built-in 60 fps cap. If you want frame rate
+control, call `tgi_setframerate(60)` after `tgi_init()`.
+
+## Audio (lynx_sfx)
+
+The bundled `lynx_sfx.{h,c}` wraps Mikey's 4 audio voices with the
+cross-platform shape:
+
+- `sfx_init()`
+- `sfx_tone(channel, period, length_frames)` — channel 0-3
+- `sfx_noise(length_frames)` — voice 3, LFSR feedback for white noise
+- `sfx_update()` — call once per frame to tick auto-silence
+- `sfx_off()`
+
+period is the 8-bit timer reload — Hz ≈ 6 MHz / 16 / (period+1).
+Useful: 80 = ~6 kHz (high pew), 160 = ~3 kHz (mid blip), 200 = ~2 kHz
+(low thump).
+
+### cc65's lynx_snd music engine
+
+For streamed music (vs one-shot SFX) use cc65's bundled lynx_snd:
+
+```c
+lynx_snd_init();                       // installs 240Hz IRQ + voice reset
+lynx_snd_play(channel, demo_music);    // begin streaming on the channel
+lynx_snd_stop_channel(channel);        // stop ONE channel
+lynx_snd_stop();                       // stop ALL channels (no arg)
+```
+
+**Stop variants:** `lynx_snd_stop(void)` stops every channel.
+`lynx_snd_stop_channel(unsigned char ch)` stops one channel. Easy to
+type `lynx_snd_stop(1)` and get a compile error — use the right one.
+
+**Signature gotcha:** `lynx_snd_play`'s second arg is
+`unsigned char *music` — non-const. The bundled `demo_music[]` is
+declared non-const so it matches the cc65 signature without warning.
+If you build your own bytestream and want to mark it `const`, you'll
+need a `(unsigned char *)` cast at the call site.
+
+### Audio + TGI interaction (R29 diagnosed → R57 fixed)
+
+Earlier round-28/29 reports of "calling sfx_init / sfx_tone wedges
+TGI rendering" were a real bug, now resolved in `lynx_sfx.c`.
+
+**Root cause:** writing the MIKEY voice CTL register ($FD25 / $FD2D /
+$FD35 / $FD3D) with the ENABLE_COUNT bit set triggers handy's
+`gNextTimerEvent = gSystemCycleCount` (mikie.cpp:1676) — a SYNCHRONOUS
+timer-event sweep at the next CPU instruction. That sweep can preempt
+an in-flight Suzy blit operation and the partially-blitted sprite
+gets corrupted. Symptom: HUD + score render (Suzy was idle for those),
+playfield sprites missing (Suzy was mid-blit when the sweep landed).
+
+**Fix (R57):** `sfx_tone` and `sfx_noise` now stage their config in
+shadow RAM and DEFER the MIKEY writes until `sfx_update()` is called.
+The contract is: **`sfx_update()` MUST be called during vblank** —
+typically right after `tgi_updatedisplay()`. The timer-event sweep
+then lands during vblank where Suzy is idle.
+
+Canonical loop is unchanged in shape; just be sure `sfx_update` runs
+after the vblank wait:
+
+```c
+for (;;) {
+    tgi_setcolor(C_BG);
+    tgi_bar(0, 0, 159, 101);
+    draw_hud();
+    draw_basket();
+    // ... game logic, can call sfx_tone() / sfx_noise() freely ...
+    tgi_updatedisplay();   // vblank wait + page swap
+    sfx_update();          // ← MIKEY writes happen here, during vblank
+}
+```
+
+`lynx_snd_play` (cc65's full music engine) hasn't been re-verified
+against R57 yet — it installs a 240Hz IRQ that's a different
+mechanism. If you need music, the per-frame `sfx_tone()` melody
+pattern remains a known-safe alternative:
+
+```c
+static const uint8_t melody_periods[] = { 180, 140, 110, 140, 95, 110, 140, 110 };
+static uint8_t melody_idx, melody_timer;
+void update_music(void) {
+    if (melody_timer == 0) {
+        sfx_tone(2, melody_periods[melody_idx], 18);
+        melody_idx = (uint8_t)((melody_idx + 1) % 8);
+        melody_timer = 18;
+    } else { melody_timer--; }
+}
+```
+
+## Joystick
+
+The Lynx has a 4-direction d-pad + 2 face buttons (A, B) + 2
+"option" buttons (Opt1, Opt2). cc65 exposes them via `JOY_LEFT(joy)`
+etc. There's no second controller — Lynx had a ComLynx link cable
+for multi-Lynx multiplayer but no second controller on one unit.
+
+### Driving input over MCP
+
+handy maps `input({op:'set'})` button names **straight through** — verified live, no
+inversion: `{a}`→A (outer), `{b}`→B (inner). Spatial east→A, south→B; Opt1/Opt2
+map to `{start}`/`{select}`. So `input({op:'set', a: true})` presses Lynx A as
+expected. ⚠ Note: the Lynx hardware register `$FCB0` is **active-HIGH** (1 =
+pressed, opposite most platforms) — that only matters if you read the register
+directly; the `input({op:'set'})` names themselves are normal.
+
+## Color
+
+16-color palette per frame at `$FDA0` (BG) + `$FDB0` (intensity).
+cc65's tgi uses a sensible default palette (`COLOR_RED`, `COLOR_GREEN`,
+etc.) — see `tgi_setpalette()` if you want custom colors.
+
+## Cartridge format
+
+The ROM file format Handy expects is `.lnx` — a 64-byte header
+(magic + bank layout) followed by the raw ROM image. cc65's
+`lynx.cfg` produces a header-less raw image; some tools wrap it
+into `.lnx`. handy accepts both.
+
+## Differences from C64 (the other 6502-family platform)
+
+- 4 colors → 16. Per-frame palette.
+- Hardware sprite blitter (Suzy) vs VIC-II 8-sprite hardware.
+- 4-voice LFSR audio (Mikey) vs 3-voice SID. Mikey lacks SID's
+  filter + ADSR but is simpler.
+- Joystick is direct register read at `$FCB0`, not via CIA1.
+- One controller (handheld) — no port 2 fallback patterns.
+- 64 KB total RAM, mapped ROM. C64 has 64 KB RAM but most is shadowed
+  by ROM by default.

package/src/platforms/lynx/TROUBLESHOOTING.md

@@ -0,0 +1,105 @@
+# Atari Lynx — troubleshooting
+
+Read MENTAL_MODEL.md first (`platform({op:'doc', platform:"lynx",
+name:"mental_model"})`).
+
+## "ROM loads but screen is black / no display"
+
+You probably forgot `tgi_install` + `tgi_init`. cc65's TGI driver
+must be installed before any `tgi_*` call. The canonical opener:
+
+```c
+tgi_install(&lynx_160_102_16_tgi);
+tgi_init();
+```
+
+Without `tgi_init` the framebuffer pointer isn't set; without
+`tgi_install` the TGI dispatcher has no driver to call.
+
+## "Screen stays blank even though tgi_install/tgi_init ran + I'm drawing"
+
+The other blank-screen cause: a bad render-loop order. The reliable
+Lynx loop is a FULL REDRAW every frame in this exact order:
+
+```c
+for (;;) {
+    while (tgi_busy()) { }            /* 1. wait for the Suzy blitter to
+                                       *    finish the LAST frame — drawing
+                                       *    while it's busy loses the frame */
+    tgi_setcolor(COLOR_BLACK);
+    tgi_bar(0, 0, tgi_getmaxx(), tgi_getmaxy());  /* 2. full-screen clear */
+    /* 3. draw all your objects with tgi_bar / tgi_line ... */
+    tgi_updatedisplay();              /* 4. push the frame */
+}
+```
+
+Two things that trip agents up:
+- **`while (tgi_busy()) { }` is required** before drawing the next frame.
+  Skipping it is the #1 "Lynx is blank" trap.
+- **Don't rely on `tgi_clear()`** to blank the screen in this
+  toolchain/emulator path — use a full-screen `tgi_bar(0,0,maxx,maxy)`
+  in the background colour instead. The bundled `shmup` scaffold uses
+  this exact loop; copy it.
+
+## "tgi_outtextxy renders nothing"
+
+cc65's default TGI on Lynx ships without a font. Either:
+1. Load one: `tgi_load_vectorfont("lynx_a.fnt", ...)` — fontfiles
+   live in `$cc65_share/target/lynx/fonts/`.
+2. Draw your own glyphs with `tgi_bar`/`tgi_line`.
+
+The bundled scaffolds work around this by using simple rectangles
+for game content + only short text strings. For game UI text, embed
+a bitmap font directly in your code.
+
+## "Joystick reads return 0"
+
+`joy_install(&lynx_stdjoy_joy)` is required before `joy_read(JOY_1)`.
+The Lynx joystick driver maps the hardware switch register at $FCB0
+into cc65's JOY_* macros.
+
+## "MIKEY audio silent — sfx_init was called but I hear nothing"
+
+Three things to check:
+1. **Volume sign**: MIKEY's volume register is SIGNED 8-bit. 64 =
+   audible, 0 = silent, -1 (0xFF) = also audible but inverted phase.
+   sfx_init sets volume to 0 (silent) — you must call sfx_tone or
+   sfx_noise to get audio.
+2. **STEREO routing**: `$FD50` controls which voices output to which
+   speaker. Bits 0-3 *mute* left for voice 0-3; bits 4-7 mute right.
+   sfx_init sets it to 0 (all voices to both speakers). If you've
+   written non-zero values to $FD50, voices may be muted.
+3. **sfx_update**: without it, notes never silence. Probably not
+   "silent" but "the same note plays forever and gets ignored as
+   background noise."
+
+## "ROM works in handy emulator but not in mednafen/etc."
+
+Other Lynx emulators sometimes expect the 64-byte `.lnx` header that
+cc65's default config doesn't emit. Either:
+1. Stick with handy (romdev ships this).
+2. Wrap your ROM in a `.lnx` header — handy itself can produce one
+   via `lyxx -i raw.bin -o game.lnx`.
+
+## "cc65 complains about C99 features"
+
+cc65 is C89. No mixed declarations + code, no inline `for (uint8_t i
+= 0; ...)`, no compound literals, no // comments in some configs.
+Declare all variables at the top of each block.
+
+The bundled Lynx scaffolds are C89-clean — copy that pattern.
+
+## "Compile fails: no rule to make target lynx-bll.cfg"
+
+You probably tried passing `linkerConfig: "lynx-bll"` — that's the
+"bootloader-loaded" config for multi-image ROMs. For a single-image
+ROM let cc65 use the default `lynx.cfg`. Drop the linkerConfig arg.
+
+## "Game runs but at wrong speed"
+
+Lynx framerate is configurable via Mikey timer 0. cc65's tgi defaults
+to ~60 fps via `tgi_setframerate(60)`. Lower it to 30 for slow games:
+`tgi_setframerate(30);` after tgi_init.
+
+Don't bother adjusting if you're just iterating in the emulator —
+gpgx and handy both run at the rate the ROM requests.

package/src/platforms/lynx/UPSTREAM_SOURCES.md

@@ -0,0 +1,66 @@
+# Lynx — source you can read
+
+When the bundled examples + MENTAL_MODEL.md aren't enough and you
+need to grep around the actual implementation. Trust hierarchy:
+
+1. **Bundled examples** (`examples/lynx/templates/*.c`) — verified to
+   compile and (mostly) work. Start here.
+2. **Bundled runtime source** (`src/platforms/lynx/lib/`) — our thin
+   wrappers (lynx_sfx.c, lynx_music.c). Read these when an API call
+   isn't doing what you expect.
+3. **cc65 lynx libsrc** — shipped at `src/platforms/lynx/lib/cc65-src/`.
+   The complete cc65 Lynx target source: TGI graphics driver (`tgi/
+   lynx-160-102-16.s`), joystick driver, conio, header builder, sound
+   engine (`lynx-snd.s`), etc. Read this when "tgi_bar does X — why?".
+4. **Compiler + emulator GitHub** (links below) — for anything below
+   our thin wrappers and beyond cc65's source. We don't bundle these
+   because they're big and the agent can't rebuild them anyway, but
+   you can fetch them on demand when chasing a deep bug.
+5. **Found a real bug in romdev?** Open an issue at
+   https://github.com/monteslu/romdev/issues with repro details.
+
+## Local source paths (in your project after `npm install`)
+
+| What | Where |
+|---|---|
+| Our lynx_sfx wrapper | `src/platforms/lynx/lib/c/lynx_sfx.c` |
+| Our lynx_music wrapper | `src/platforms/lynx/lib/c/lynx_music.c` |
+| cc65 TGI driver | `src/platforms/lynx/lib/cc65-src/tgi/lynx-160-102-16.s` |
+| cc65 lynx_snd music engine | `src/platforms/lynx/lib/cc65-src/lynx-snd.s` |
+| cc65 joystick driver | `src/platforms/lynx/lib/cc65-src/joy/lynx-stdjoy.s` |
+| cc65 conio | `src/platforms/lynx/lib/cc65-src/conio.s` |
+| cc65 header builder | `src/platforms/lynx/lib/cc65-src/header.s` |
+
+When you grep, start in `cc65-src/` — it's the most likely place
+your "why doesn't tgi_X work?" question gets answered.
+
+## Upstream sources (NOT bundled — fetch on demand if needed)
+
+| What | Upstream | Why not bundled |
+|---|---|---|
+| cc65 compiler + libsrc | https://github.com/cc65/cc65 | We bundle the WASM compiler + lynx libsrc separately; full tree is ~50 MB |
+| handy libretro core | https://github.com/libretro/libretro-handy | C++ emulator source, ~5 MB. Read when MCP behavior diverges from real hardware. |
+| handy mikie/susie (deeper) | Same repo, `src/lynx/mikie.cpp` + `susie.cpp` | Contains the exact emulation of MIKEY timers + Suzy blitter. Where round-29's audio-vs-TGI bug was diagnosed. |
+
+## Lynx hardware docs
+
+| What | Where |
+|---|---|
+| Atari Lynx Programmer's Manual | https://atarihq.com/danb/files/Atari_Lynx_Programmer_s_Manual.pdf |
+| Lynx Bluebook (epyx engineer notes) | https://archive.org/details/lynx_bluebook |
+| Copetti architecture writeup | https://www.copetti.org/writings/consoles/atari-lynx/ |
+
+The Programmer's Manual is the canonical reference for everything
+MIKEY + Suzy. Read sections 5 (MIKEY) and 6 (Suzy) before
+attempting anything beyond `tgi_bar`.
+
+## When to use what
+
+- "How does `tgi_bar` work internally?" → `cc65-src/tgi/lynx-160-102-16.s`
+- "What does the MIKEY timer chain do?" → handy `mikie.cpp` + Programmer's Manual section 5
+- "Why does Suzy stop rendering after N frames?" → handy `susie.cpp`
+  `PaintSprites()` + check `mSUZYBUSEN` + `mSPRGO`
+- "What's the actual audio register layout?" → `cc65-src/lynx-snd.s`
+  + Programmer's Manual section 5.6
+- "Does the bundled lynx_sfx wrap MIKEY correctly?" → our
+  `lynx_sfx.c` source (it's tiny — 100 lines, fully readable)

package/src/platforms/lynx/lib/c/lynx_music.c

@@ -0,0 +1,63 @@
+/* lynx_music.c — hand-authored music bytestream for cc65's lynx_snd_play.
+ *
+ * cc65 ships a 4-channel music engine on the Atari Lynx (see
+ * build/cc65/src/libsrc/lynx/lynx-snd.s). Driver is started with:
+ *
+ *     lynx_snd_init();                       // 240Hz IRQ + voice reset
+ *     lynx_snd_play(channel, demo_music);    // begin streaming on channel
+ *
+ * Stream byte format (parsed in SndGetCmd):
+ *
+ *   byte < $80  → NOTE+LENGTH pair. byte0 is the note index (1..127),
+ *                 byte1 is the delay/length in 240Hz ticks. The driver
+ *                 looks up note -> prescaler + reload from internal
+ *                 tables (SndPrescaler / SndReload in lynx-snd.s). Note 0
+ *                 terminates the stream (SndStop). Notes roughly form a
+ *                 chromatic scale; ~12-13 = ~middle C, +12 per octave.
+ *                 Two bytes consumed.
+ *
+ *   byte $80..$ff → COMMAND. The low 7 bits index a function table:
+ *      $80 SndLoop           start loop (next byte = loop count)
+ *      $81 SndDo             end-of-loop marker (jumps back to $80)
+ *      $82 SndPause          rest for N ticks (next byte = N)
+ *      $83 SndNoteOff        release current note (envelope tail)
+ *      $84 SndSetInstr       set channel instrument (5 bytes follow)
+ *      $85 SndNewNote2       explicit reload+prescale note (3 bytes)
+ *      $86 SndCallPattern    call sub-pattern (2-byte addr)
+ *      $87 SndRetToSong      return from sub-pattern
+ *      $88..$8d envelope setup (define + select vol/frq/wave)
+ *      $8e SndSetStereo      stereo mute mask (1 byte)
+ *      $91 SndPlayerFreq     change tempo (2 bytes)
+ *      $92 SndReturnAll      end-of-track sentinel
+ *
+ *   Command's Y register on return tells the driver how many bytes to
+ *   advance past (low 7 bits of Y; high bit means "loop again same tick").
+ *
+ * The demo below plays a short C-major-arpeggio-like motif on one channel
+ * so you can audibly verify the driver is wired and the IRQ is firing.
+ * Each note is roughly an 8th-note at the default 240Hz player rate.
+ *
+ * NOTE numbers picked by ear from SndReload table — the driver doesn't
+ * publish a "midi number" mapping, so values 24/28/31/36 sit in a
+ * comfortable musical range and demonstrate distinct pitches. Adjust
+ * freely; values 1..127 are all valid.
+ */
+
+#include "lynx_music.h"
+
+/* Non-const because cc65's lynx_snd_play signature wants a writable
+ * pointer — see lynx_music.h. The bytes live in ROM (cc65 puts read-
+ * only globals there) so attempting to write through this would crash;
+ * the cc65 driver never writes, just reads. */
+unsigned char demo_music[] = {
+  /* note, length(ticks) — length 30 @ 240Hz ≈ 125 ms per note */
+  24, 30,   /* low  */
+  28, 30,
+  31, 30,
+  36, 30,   /* high */
+  31, 30,
+  28, 30,
+  24, 60,   /* longer trailing note */
+  0x82, 30, /* SndPause: rest 30 ticks before looping the engine restart */
+  0         /* SndStop — terminate stream */
+};