romdev-mcp 0.1.1

package/src/platforms/gg/lib/c/gg_music.h

@@ -0,0 +1,89 @@
+/* gg_music.h — minimal Game Gear PSG music engine.
+ *
+ * Companion to gg_sfx (sfx wrapper). Where sfx_tone() plays a single
+ * fire-and-forget tone with a countdown, music_play() runs an entire
+ * hand-authored song on a dedicated PSG channel, advancing one note
+ * per call to music_update() (call once per frame, 60 Hz).
+ *
+ * Same SN76489 PSG chip + same I/O port ($7F) as SMS, so the protocol
+ * is identical — only difference vs the (parallel) SMS driver is the
+ * file name. We intentionally keep gg_music/sms_music independent (no
+ * shared common-z80 lib), matching the existing gg_sfx / sms_sfx /
+ * genesis_sfx split. If somebody later wants to consolidate they can
+ * lift the byte-identical bits into a common file.
+ *
+ * Song format — see gg_music.c for the full breakdown. TL;DR each row
+ * is a (note, duration_frames) pair stored as 10-bit PSG freq divider
+ * and an 8-bit frame count. Duration 0 = end-of-song sentinel; the
+ * engine then either stops (one-shot) or restarts the song (loop).
+ *
+ *   music_init();                  // silence music channel
+ *   music_play(0);                 // start song 0 on the music channel
+ *   for (;;) {
+ *     gg_vblank_wait();
+ *     music_update();              // advance one frame of music
+ *   }
+ *
+ * The engine uses PSG channel 2 by default (leaves ch 0/1 free for
+ * gg_sfx tones and ch 3 for noise). Change MUSIC_CHANNEL in gg_music.c
+ * if you want a different one.
+ *
+ * Frequencies are pre-baked SN76489 register values (0..1023), NOT Hz,
+ * so the note table is exactly what the chip latches. The header below
+ * exposes the standard NOTE_* defines so songs can read as music.
+ */
+
+#ifndef GG_MUSIC_H
+#define GG_MUSIC_H
+
+#include <stdint.h>
+
+/* One row of a song. Note 0 + dur 0 = end sentinel. */
+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;
+
+typedef struct {
+  const music_note_t *notes;
+  uint8_t loop;    /* 0 = one-shot, 1 = loop forever */
+} music_song_t;
+
+void music_init(void);
+void music_play(uint8_t song_idx);
+void music_stop(void);
+void music_update(void);
+
+/* Number of songs in the bundled bank (see gg_music.c). */
+extern const uint8_t music_song_count;
+
+/* ── SN76489 note table (10-bit freq dividers @ ~3.58 MHz) ────────
+ * Formula: divider = 3579545 / (32 * Hz). Higher divider = lower pitch.
+ * Octave indices roughly cover C3..C6 — comfortable handheld range.
+ */
+#define NOTE_REST 0
+
+#define NOTE_C3   855  /* 130.81 Hz */
+#define NOTE_D3   762
+#define NOTE_E3   679
+#define NOTE_F3   641
+#define NOTE_G3   571
+#define NOTE_A3   509
+#define NOTE_B3   453
+#define NOTE_C4   428  /* 261.63 Hz — middle C */
+#define NOTE_D4   381
+#define NOTE_E4   339
+#define NOTE_F4   320
+#define NOTE_G4   285
+#define NOTE_A4   254  /* 440 Hz concert A */
+#define NOTE_B4   226
+#define NOTE_C5   214
+#define NOTE_D5   190
+#define NOTE_E5   170
+#define NOTE_F5   160
+#define NOTE_G5   142
+#define NOTE_A5   127
+#define NOTE_B5   113
+#define NOTE_C6   107
+
+#endif

package/src/platforms/gg/lib/c/gg_sfx.c

@@ -0,0 +1,82 @@
+/* sms_sfx.c — SN76489 PSG driver for SMS / Game Gear.
+ *
+ * SN76489 latch protocol (write-only via port $7F):
+ *   Latch byte (bit 7 = 1):
+ *     bit 7    = 1 (latch)
+ *     bits 6-5 = channel (00=ch0, 01=ch1, 10=ch2, 11=ch3-noise)
+ *     bit 4    = 0 (frequency) | 1 (volume/attenuation)
+ *     bits 3-0 = low 4 bits of frequency, OR 4-bit attenuation (0=loud, 15=silent)
+ *   Data byte (bit 7 = 0):
+ *     bits 5-0 = high 6 bits of frequency
+ *
+ * To play a tone:
+ *   1. Latch: $80|chan<<5|0|(freq & 0x0F)
+ *   2. Data:  (freq >> 4) & 0x3F
+ *   3. Latch volume: $90|chan<<5|attenuation
+ *
+ * Noise uses a different latch (low 3 bits select shift rate / source):
+ *   $E0 | (mode_bit << 2) | rate
+ *   rate 0=clock/512, 1=clock/1024, 2=clock/2048, 3=use ch2 freq
+ *
+ * Attenuation is in 2 dB steps: 0=loudest, 15=off.
+ *
+ * Per-channel "frames-left" countdown drives auto-silence. sfx_update
+ * runs once per frame and silences a channel whose counter hits 0.
+ */
+
+#include "gg_sfx.h"
+#include "gg_hw.h"
+
+static uint8_t sfx_remaining[4];
+
+static void psg_write(uint8_t b) {
+  PORT_H_COUNTER = b;            /* port $7F is the PSG write port */
+}
+
+void sfx_init(void) {
+  uint8_t i;
+  for (i = 0; i < 4; i++) {
+    sfx_remaining[i] = 0;
+    /* Silence channel i (latch volume = 0xF = off). */
+    psg_write(0x90 | (i << 5) | 0x0F);
+  }
+}
+
+void sfx_tone(uint8_t channel, uint16_t freq, uint8_t length_frames) {
+  if (channel > 2) return;
+  /* Latch + data byte for frequency. */
+  psg_write(0x80 | (channel << 5) | (freq & 0x0F));
+  psg_write((freq >> 4) & 0x3F);
+  /* Volume at max (attenuation 0). */
+  psg_write(0x90 | (channel << 5) | 0x00);
+  sfx_remaining[channel] = length_frames;
+}
+
+void sfx_noise(uint8_t length_frames) {
+  /* White noise, rate = clock/1024 (mid frequency). */
+  psg_write(0xE0 | 0x04 | 0x01);
+  /* Volume at max (channel 3 attenuation = 0). */
+  psg_write(0xF0);
+  sfx_remaining[3] = length_frames;
+}
+
+void sfx_update(void) {
+  uint8_t i;
+  for (i = 0; i < 4; i++) {
+    if (sfx_remaining[i] > 0) {
+      sfx_remaining[i]--;
+      if (sfx_remaining[i] == 0) {
+        /* Silence channel i. */
+        psg_write(0x90 | (i << 5) | 0x0F);
+      }
+    }
+  }
+}
+
+void sfx_off(void) {
+  uint8_t i;
+  for (i = 0; i < 4; i++) {
+    psg_write(0x90 | (i << 5) | 0x0F);
+    sfx_remaining[i] = 0;
+  }
+}

package/src/platforms/gg/lib/c/gg_sfx.h

@@ -0,0 +1,40 @@
+/* sms_sfx.h — minimal SMS PSG sound-effects wrapper.
+ *
+ * SMS audio = SN76489 PSG (same chip as Genesis PSG, 4 channels):
+ *   ch 0, 1, 2 = square-wave tones
+ *   ch 3       = noise
+ *
+ * Accessed via I/O port $7F (write-only — reads return the H-counter).
+ *
+ * Same shape as nes_runtime / gb_runtime / gba_sfx / genesis_sfx:
+ *
+ *   sfx_init()
+ *   sfx_tone(channel, freq, length_frames)
+ *   sfx_noise(length_frames)
+ *   sfx_update()    // call once per frame to tick auto-silence
+ *   sfx_off()
+ *
+ * Game Gear shares the SAME chip + the same port $7F write path,
+ * so this wrapper works unchanged on GG. (GG adds a stereo register
+ * at port $06 that's optional — we don't touch it.)
+ *
+ * The PSG has NO automatic envelope. We hand-decrement a per-channel
+ * counter and silence on zero — that's what sfx_update does. Forget
+ * to call it once per frame and notes ring forever.
+ *
+ * Frequency on SMS is 10-bit (0..1023). Hz = 3579545 / 32 / freq.
+ * Useful values: 200 = high pew, 400 = mid blip, 800 = low thump.
+ */
+
+#ifndef SMS_SFX_H
+#define SMS_SFX_H
+
+#include <stdint.h>
+
+void sfx_init(void);
+void sfx_tone(uint8_t channel, uint16_t freq, uint8_t length_frames);
+void sfx_noise(uint8_t length_frames);
+void sfx_update(void);
+void sfx_off(void);
+
+#endif

package/src/platforms/gg/lib/c/joypad_read.c

@@ -0,0 +1,22 @@
+/* GG joypad read — port $DC (D-pad + B1/B2) plus port $00 bit 7 for START.
+ *
+ * Active LOW on the hardware, we invert so pressed = 1. Returned byte
+ * layout matches the SMS layout PLUS bit 7 for START:
+ *
+ *   bit 0  UP
+ *   bit 1  DOWN
+ *   bit 2  LEFT
+ *   bit 3  RIGHT
+ *   bit 4  B1
+ *   bit 5  B2
+ *   bit 7  START   (read from GG-specific port $00 bit 7)
+ *
+ * Use the JOY_* and JOY_START masks from gg_hw.h.
+ */
+#include "gg_hw.h"
+
+uint8_t gg_joypad_read(void) {
+  uint8_t a = ~PORT_JOY_A;        /* D-pad + B1 + B2 (active low) */
+  uint8_t start = ~PORT_GG_INPUT; /* GG-specific port bit 7 = START */
+  return (uint8_t)((a & 0x3F) | (start & 0x80));
+}

package/src/platforms/gg/lib/c/load_palette.c

@@ -0,0 +1,20 @@
+/* GG palette loader — uploads 64-byte palette (32 entries × 2 bytes) to CRAM.
+ *
+ * GG CRAM: 32 entries × 2 bytes (4-4-4 BGR LE), 64 bytes total.
+ *   Entry layout: low byte = $GR (G=high nibble, R=low), high byte = $0B.
+ *   Pack with: low = (g << 4) | r, high = b.
+ *
+ *     extern const uint8_t my_palette[64];
+ *     gg_load_palette(my_palette);
+ *
+ * Entries 0-15 = BG palette, 16-31 = sprite palette.
+ */
+#include "gg_hw.h"
+
+extern void gg_vdp_set_addr(uint16_t addr, uint8_t prefix);
+
+void gg_load_palette(const uint8_t *palette) {
+  uint16_t i;
+  gg_vdp_set_addr(0, VDP_CRAM_WRITE);
+  for (i = 0; i < 64; i++) PORT_VDP_DATA = palette[i];
+}

package/src/platforms/gg/lib/c/load_tiles.c

@@ -0,0 +1,32 @@
+/* SMS tile loader — upload bytes to VRAM at any destination.
+ *
+ * SMS tiles are 32 bytes each (4bpp interleaved). VRAM is 16 KB at
+ * $0000-$3FFF. Tile N lives at VRAM offset (N * 32).
+ *
+ *     extern const uint8_t my_tiles[];
+ *     gg_load_tiles(0x0000, my_tiles, sizeof(my_tiles));  // sprite bank
+ *
+ * Default R6=0xFB → sprite tiles read from $0000 (shared with BG tiles).
+ * If you want sprite tiles in their own bank at $2000, set R6=0xFF AND
+ * upload to $2000. Don't pick the address without checking R6.
+ */
+#include "gg_hw.h"
+
+extern void gg_vdp_set_addr(uint16_t addr, uint8_t prefix);
+
+void gg_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count) {
+  uint16_t i;
+  gg_vdp_set_addr(vram_dest, VDP_VRAM_WRITE);
+  for (i = 0; i < byte_count; i++) PORT_VDP_DATA = src[i];
+}
+
+/* Write a single name-table cell. Default name table at $3800.
+ *   tile_idx: 0..511 (low 9 bits)
+ *   attr:     hflip = bit 1, vflip = bit 2, palette = bit 3, priority = bit 4
+ */
+void gg_set_tilemap_cell(uint8_t row, uint8_t col, uint8_t tile_idx, uint8_t attr) {
+  uint16_t addr = 0x3800 + ((uint16_t)row * 32 + col) * 2;
+  gg_vdp_set_addr(addr, VDP_VRAM_WRITE);
+  PORT_VDP_DATA = tile_idx;
+  PORT_VDP_DATA = attr;
+}

package/src/platforms/gg/lib/c/sprite_table.c

@@ -0,0 +1,60 @@
+/* GG sprite attribute table — shadow OAM in WRAM, DMA'd to SAT once
+ * per frame. GG VDP is SMS-compatible so the SAT layout is identical.
+ *
+ * SAT VRAM layout ($3F00):
+ *   $00-$3F:  64 Y bytes ($D0 in any slot = HARD TERMINATOR — see below)
+ *   $80-$FF:  64 (X, tile) pairs
+ *
+ * The $D0 terminator footgun:
+ *   The VDP stops scanning further sprite slots the moment it sees Y=$D0
+ *   in ANY OAM byte. If you populate slots 0..5 and slot 6 still has
+ *   $D0, slot 5 is the last sprite you'll ever see. Earlier rounds of
+ *   this runtime initialised every slot to $D0 — "hidden at boot" — but
+ *   that meant the FIRST gap in your sprite allocation killed the
+ *   renderer for everything past it. We now initialise unused slots to
+ *   $E0 instead: still off-screen but NOT the terminator. Slots you
+ *   don't touch stay invisible; slots you do touch render. Set a slot's
+ *   Y to $D0 yourself if you ACTUALLY want the renderer to stop there.
+ *
+ * Workflow:
+ *   gg_sprite_init();             // once
+ *   gg_sprite_set(0, x, y, 4);    // game logic
+ *   ...
+ *   gg_sat_upload();              // once per vblank
+ */
+#include "gg_hw.h"
+
+extern void gg_vdp_set_addr(uint16_t addr, uint8_t prefix);
+
+/* Shadow OAM: matches the VDP's expected SAT layout. */
+uint8_t shadow_oam[256];
+
+/* Y value for "hidden but not terminator." 192-line mode is visible
+ * Y=0..191; $E0 (224) is below the visible area and won't render.
+ * Also below the GG visible viewport (hw-coord y∈[24,167]). */
+#define OAM_Y_HIDDEN  0xE0
+
+void gg_sprite_init(void) {
+  uint8_t i;
+  /* Park every slot off-screen with a non-terminator Y. The renderer
+   * keeps scanning past these (so any slot you later populate will
+   * actually draw); they just don't render themselves. */
+  for (i = 0; i < 64; i++) shadow_oam[i] = OAM_Y_HIDDEN;
+  for (i = 0; i < 128; i++) shadow_oam[0x80 + i] = 0;
+}
+
+void gg_sprite_set(uint8_t slot, uint8_t x, uint8_t y, uint8_t tile) {
+  shadow_oam[slot] = y;
+  shadow_oam[0x80 + (uint16_t)slot * 2] = x;
+  shadow_oam[0x80 + (uint16_t)slot * 2 + 1] = tile;
+}
+
+void gg_sat_upload(void) {
+  uint8_t i;
+  /* Y bytes → VRAM $3F00. */
+  gg_vdp_set_addr(0x3F00, VDP_VRAM_WRITE);
+  for (i = 0; i < 64; i++) PORT_VDP_DATA = shadow_oam[i];
+  /* (X, tile) pairs → VRAM $3F80. */
+  gg_vdp_set_addr(0x3F80, VDP_VRAM_WRITE);
+  for (i = 0; i < 128; i++) PORT_VDP_DATA = shadow_oam[0x80 + i];
+}

package/src/platforms/gg/lib/c/vblank_wait.c

@@ -0,0 +1,10 @@
+/* SMS vblank wait — polls VDP_CTRL bit 7.
+ *
+ * Reading $BF returns the status byte and CLEARS bit 7. Spin until set;
+ * the act of reading clears the flag for the next iteration.
+ */
+#include "gg_hw.h"
+
+void gg_vblank_wait(void) {
+  while ((PORT_VDP_CTRL & 0x80) == 0) { }
+}

package/src/platforms/gg/lib/c/vdp_init.c

@@ -0,0 +1,58 @@
+/* SMS VDP — minimum viable initialization (C).
+ *
+ * Writes the 11 mode-4 registers to a sane baseline:
+ *   display OFF, vblank IRQ off, 192-line mode 4, name table at $3800,
+ *   BG tile data at $0000, sprite attr table at $3F00, sprite tile data
+ *   at $0000 (R6=0xFB → SA13 clear → tiles read from $0000-$1FFF). Call
+ *   once after reset before uploading palette/tiles/map.
+ *
+ * Footgun: many SMS/GG references say "R6=0xFB → sprite tiles at $2000"
+ * which is BACKWARDS. R6 bit 2 (the SA13 select) is CLEAR in 0xFB, so
+ * sprite tiles read from $0000 (sharing the bank with BG tiles). To
+ * separate sprite tiles to $2000, set R6 = 0xFF instead. The
+ * inspectSprites tool's spriteTileDataBase field will show you the
+ * real address the VDP is reading from.
+ *
+ * After loading assets, enable display by re-writing R1 with bit 6 set:
+ *   gg_vdp_display_on();
+ */
+#include "gg_hw.h"
+
+/* Write a value to a VDP register. SMS convention: data first, then
+ * (0x80 | reg). */
+void gg_vdp_write_reg(uint8_t reg, uint8_t value) {
+  PORT_VDP_CTRL = value;
+  PORT_VDP_CTRL = VDP_REG_WRITE | reg;
+}
+
+void gg_vdp_init(void) {
+  static const uint8_t regs[11] = {
+    0x36,  /* R0:  Mode 4 */
+    0x80,  /* R1:  display OFF, vblank IRQ off */
+    0xFF,  /* R2:  name table at $3800 */
+    0xFF,  /* R3:  color table (ignored in M4) */
+    0xFF,  /* R4:  BG tile data at $0000 */
+    0xFF,  /* R5:  sprite attr table at $3F00 */
+    0xFB,  /* R6:  sprite tile data at $0000 (set 0xFF for $2000) */
+    0x00,  /* R7:  border = sprite palette entry 0 */
+    0x00,  /* R8:  BG X scroll */
+    0x00,  /* R9:  BG Y scroll */
+    0xFF,  /* R10: line IRQ counter disabled */
+  };
+  uint8_t i;
+  for (i = 0; i < 11; i++) gg_vdp_write_reg(i, regs[i]);
+}
+
+void gg_vdp_display_on(void) {
+  gg_vdp_write_reg(1, 0xE0);  /* display on, vblank IRQ on, 192-line */
+}
+
+void gg_vdp_display_off(void) {
+  gg_vdp_write_reg(1, 0x80);
+}
+
+/* Set the VDP destination address (for the next data-port writes). */
+void gg_vdp_set_addr(uint16_t addr, uint8_t prefix) {
+  PORT_VDP_CTRL = (uint8_t)(addr & 0xFF);
+  PORT_VDP_CTRL = (uint8_t)((addr >> 8) & 0x3F) | prefix;
+}

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,231 @@
+# 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.
+
+## 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.
+
+## 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.