romdevtools 0.27.0 → 0.28.0

package/src/platforms/gg/lib/c/gg_crt0.s

@@ -37,10 +37,13 @@
 ;; ─── Reset vector at $0000 ────────────────────────────────────────
         .area _HEADER (ABS)
         .org    0x0000
+        ;; ONLY 8 BYTES fit before the RST $08 vector. The old block here
+        ;; (di/im 1/ld sp/jp = 9 bytes) overflowed into .org 0x0008, whose
+        ;; `ret` stomped the jp's high target byte -> boot jumped into
+        ;; garbage. di+im 1+jp = 6 bytes; SP setup moved to _boot below.
         di                          ; interrupts off until we're ready
         im      1                   ; mode 1 — IRQs jump to $0038
-        ld      sp, #0xDFF0         ; GG/SMS stack (top of WRAM minus 16)
-        jp      gsinit              ; skip the interrupt vector table
+        jp      _boot               ; continue past the vector table
 
 ;; ─── RST handlers (default = return) ──────────────────────────────
         .org    0x0008
@@ -80,6 +83,15 @@
         .org    0x0066
         retn
 
+;; ─── Boot continuation (right after the NMI vector) ───────────────
+;; SP first, then the C runtime init. Lives in the ABS header area so
+;; it exists at a known address regardless of where _CODE is linked
+;; (_CODE must start at >= $0100 so it can't overwrite this table).
+        .org    0x0068
+_boot:
+        ld      sp, #0xDFF0         ; stack at top of WRAM minus 16
+        jp      gsinit
+
 ;; ─── crt0 body ────────────────────────────────────────────────────
 ;; Standard SDCC pattern: jump to a code area, run initializers, then
 ;; call main. The initializer area is filled by sdcc when it sees

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

@@ -103,21 +103,57 @@ static void sfx_flush_pending(void) {
       POKE(VOICE_BASE(i) + 1, 0x80);     /* feedback off */
       POKE(VOICE_BASE(i) + 4, sfx_pending_period[i]);
       POKE(VOICE_BASE(i) + 5, 0x18);     /* RELOAD + COUNT + 16us clock */
-      POKE(VOICE_BASE(i) + 0, 64);       /* volume */
+      POKE(VOICE_BASE(i) + 0, 100);      /* volume (was 64 — read as near-silent on hardware) */
     } else if (sfx_pending_kind[i] == 2) {
       /* Noise on voice 3. */
       POKE(VOICE_BASE(i) + 7, 0x01);     /* 12-bit LFSR */
       POKE(VOICE_BASE(i) + 1, 0x95);     /* classic noise feedback */
       POKE(VOICE_BASE(i) + 4, 40);
       POKE(VOICE_BASE(i) + 5, 0x18);
-      POKE(VOICE_BASE(i) + 0, 64);
+      POKE(VOICE_BASE(i) + 0, 100);
     }
     sfx_pending_kind[i] = 0;
   }
 }
 
+/* ── background music: 16-step melody loop on voice 1 ───────────────
+ * Ticked from sfx_update() through the SAME staged-write path (R57),
+ * so every scaffold that already calls sfx_init() + sfx_update() gets
+ * continuous music for free — "no sound at all" was the Lynx playtest
+ * verdict. sfx_music(0) turns it off. SFX use voice 0 (+ noise on 3).
+ * MIKEY period at the 16us clock: freq ~= 31250 / period. */
+static const uint8_t music_period[16] = {
+    119, 95, 80, 60, 80, 95, 119, 0,    /* C4 E4 G4 C5 G4 E4 C4 -  */
+    142, 119, 95, 71, 95, 119, 142, 0,  /* A3 C4 E4 A4 E4 C4 A3 -  */
+};
+static uint8_t music_enabled = 1;
+static uint8_t music_step, music_timer;
+
+void sfx_music(uint8_t on) {
+  music_enabled = on;
+  music_step = 0;
+  music_timer = 0;
+}
+
+static void music_tick(void) {
+  uint8_t p;
+  if (!music_enabled) return;
+  if (music_timer == 0) {
+    p = music_period[music_step & 15];
+    if (p) {
+      sfx_pending_kind[1] = 1;          /* staged like any tone (R57-safe) */
+      sfx_pending_period[1] = p;
+      sfx_remaining[1] = 8;             /* hold 8 of 9 frames — articulated */
+    }
+    music_step++;
+  }
+  music_timer++;
+  if (music_timer >= 9) music_timer = 0;
+}
+
 void sfx_update(void) {
   uint8_t i;
+  music_tick();
   /* R57: flush any sfx_tone/sfx_noise requests from THIS frame. The
    * caller is expected to have just returned from tgi_updatedisplay
    * (or wait_vblank), so the synchronous timer-event sweep that handy

package/src/platforms/lynx/lib/c/lynx_sfx.h

@@ -54,6 +54,7 @@ void sfx_init(void);
 void sfx_tone(uint8_t channel, uint8_t period, uint8_t length_frames);
 void sfx_noise(uint8_t length_frames);
 void sfx_update(void);
+void sfx_music(uint8_t on);  /* background melody on voice 1 — ON by default; 0 = off */
 void sfx_off(void);
 
 #endif

package/src/platforms/msx/MENTAL_MODEL.md

@@ -117,6 +117,12 @@ exactly this.
   generator + the envelope (period + shape bits).
 - `memory({op:'read'})` regions: `msx_vram`, `msx_vdp_regs`, `msx_vdp_status`,
   `msx_palette`, `msx_cpu_regs`, `msx_psg_regs`, plus `system_ram` (work RAM).
+- `disasm({target:'rom'|'references'|'project'})` — native binutils z80
+  `objdump`. MegaROMs (>32 KB) are handled per 16 KB bank: `references` scans
+  bank 0 at `$4000` (after the "AB" header) and banks 1+ at `$8000` (an
+  assumed ASCII16-style window), refs tagged `romBank`;
+  `disasm({target:'project'})` splits the header into its own data region and
+  emits a bank-by-bank native rebuild recipe in `BUILD.md`.
 
 ## MCP debug & inspection tooling
 

package/src/platforms/msx/TROUBLESHOOTING.md

@@ -66,3 +66,24 @@ fixed hardware colors — you choose indices, not RGB.
 The build worker pool can transiently fail. Re-run the build. If it fails
 consistently, read the `log` — SDCC's C89 parser errors are terse; common causes
 are `//` comments, mid-block declarations, or file-scope inline asm (see above).
+
+
+## PSG writes get eaten — sound code "runs" but the chip stays silent
+
+The BIOS KEYINT interrupt fires every frame and reads PSG register 14 (the
+joystick row) — and it CLOBBERS the PSGADDR latch. If an interrupt lands
+between your `PSGADDR = n` and the matching `PSGWRITE`, your byte goes into
+R14 instead of the register you selected. Symptom: the mixer looks right but
+periods/volumes stay 0 — total silence even though your code clearly ran.
+
+**Rule: wrap every PSGADDR/PSGWRITE sequence in `__asm__("di")` /
+`__asm__("ei")`.** The bundled `msx_psg_tone`/`msx_psg_off` (and the music
+ticker) already do this; copy the pattern for any direct PSG access you write.
+
+## A `static x = 5;` boots as 0 (historical — fixed in the bundled crt0)
+
+The old `msx_crt0.s` placed the SDCC `_INITIALIZER` area in RAM, so the boot
+copy duplicated uninitialised RAM onto itself: every value-initialised static
+read 0 and BSS was never zeroed. The bundled crt0 has been fixed (ROM-placed
+`_INITIALIZER` + a BSS-zero loop). If a project scaffolded before 2026-06-09
+shows ghost zeros, refresh its `msx_crt0.s` from a new scaffold.

package/src/platforms/msx/lib/c/msx_crt0.s

@@ -27,6 +27,8 @@
         .globl  _main
         .globl  l__INITIALIZER
         .globl  s__INITIALIZER
+        .globl  s__DATA
+        .globl  l__DATA
         .globl  s__INITIALIZED
 
 ;; ─── Cartridge ROM header at $4000 ────────────────────────────────
@@ -44,7 +46,15 @@
 ;; ─── crt0 body ────────────────────────────────────────────────────
 ;; Standard SDCC area order so the linker fills _GSINIT with the global
 ;; initializer fragments sdcc emits, then _GSFINAL.
+        ;; AREA ORDERING IS LOAD-BEARING (same bug class fixed in the SMS/GG
+        ;; crt0s 2026-06-08): `_INITIALIZER` (the ROM image of every value-
+        ;; initialised static) MUST be declared in the ROM group — otherwise
+        ;; sdld places it in RAM after `_INITIALIZED` and the init copy below
+        ;; copies uninitialised RAM onto itself, so every `static x = N;`
+        ;; boots as 0. On MSX that silenced ALL scaffold audio (the PSG
+        ;; music/sfx state booted zeroed) among other ghosts.
         .area   _HOME
+        .area   _INITIALIZER
         .area   _CODE
         .area   _GSINIT
         .area   _GSFINAL
@@ -59,6 +69,23 @@
 
 ;; INIT entry — the BIOS CALLs here with interrupts on and a valid stack.
 init:
+        ;; ── Zero the BSS segment (`_DATA`) ── every uninitialised static
+        ;; must read back 0 at boot (power-on RAM is garbage).
+        ld      bc, #l__DATA
+        ld      a, b
+        or      a, c
+        jr      Z, bss_done
+        ld      hl, #s__DATA
+        ld      (hl), #0x00
+        ld      d, h
+        ld      e, l
+        inc     de
+        dec     bc
+        ld      a, b
+        or      a, c
+        jr      Z, bss_done
+        ldir
+bss_done:
         ;; Copy initialized-data image from ROM to RAM (SDCC global inits).
         ld      bc, #l__INITIALIZER
         ld      a, b

package/src/platforms/msx/lib/c/msx_hw.h

@@ -87,6 +87,8 @@ void    msx_clear_sprites(void);
 void    msx_vblank_wait(void);
 uint8_t msx_read_joystick(uint8_t stick);
 void    msx_psg_tone(uint8_t chan, uint16_t period, uint8_t vol);
+void    msx_music(uint8_t on);   /* background melody on channel C — ON by default; 0 = off */
+void    msx_music_tick(void);    /* call once per frame (scaffolds do) */
 void    msx_psg_off(uint8_t chan);
 
 #endif /* MSX_HW_H */

package/src/platforms/msx/lib/c/msx_vdp.c

@@ -121,6 +121,13 @@ void msx_psg_tone(uint8_t chan, uint16_t period, uint8_t vol) {
     uint8_t fine = (uint8_t)(period & 0xFF);
     uint8_t coarse = (uint8_t)((period >> 8) & 0x0F);
 
+    /* DI around the whole register sequence: the BIOS KEYINT ISR reads
+     * PSG R14 (joystick row) every frame, and it CLOBBERS the PSGADDR
+     * latch — an IRQ between our PSGADDR and PSGWRITE sent the period/
+     * volume bytes into R14 instead. Symptom: mixer set, period 0,
+     * amplitude 0 → every MSX scaffold was silent. */
+    __asm__("di");
+
     /* tone period: regs 0/1 (A), 2/3 (B), 4/5 (C) */
     PSGADDR = (uint8_t)(chan << 1);       PSGWRITE = fine;
     PSGADDR = (uint8_t)((chan << 1) + 1); PSGWRITE = coarse;
@@ -136,15 +143,53 @@ void msx_psg_tone(uint8_t chan, uint16_t period, uint8_t vol) {
     mixer &= (uint8_t)~(1 << chan);        /* tone ON for this channel       */
     PSGADDR = 7;
     PSGWRITE = mixer;
+    __asm__("ei");
 }
 
 /* Silence a PSG channel: zero its volume and re-disable its tone bit. */
 void msx_psg_off(uint8_t chan) {
     uint8_t mixer;
+    __asm__("di");                                /* same KEYINT race as above */
     PSGADDR = (uint8_t)(8 + chan); PSGWRITE = 0;  /* volume 0 */
     PSGADDR = 7;
     mixer = PSGREAD;
     mixer |= (uint8_t)(1 << chan);                /* tone OFF for this channel */
     PSGADDR = 7;
     PSGWRITE = mixer;
+    __asm__("ei");
+}
+
+/* ── background music: 16-step melody loop on PSG channel C (2) ─────
+ * Call msx_music_tick() once per frame (the scaffolds wire it in after
+ * their vsync wait); msx_music(0) turns it off. SFX use channels A/B,
+ * so effects always cut through. AY period = 1789773 / (16 * freq). */
+static const uint16_t _msx_music_per[16] = {
+    427, 339, 285, 214, 285, 339, 427, 0,    /* C4 E4 G4 C5 G4 E4 C4 -  */
+    508, 427, 339, 254, 339, 427, 508, 0,    /* A3 C4 E4 A4 E4 C4 A3 -  */
+};
+static uint8_t _msx_music_on = 1;
+static uint8_t _msx_music_step;
+static uint8_t _msx_music_timer;
+
+void msx_music(uint8_t on) {
+    _msx_music_on = on;
+    _msx_music_step = 0;
+    _msx_music_timer = 0;
+    if (!on) msx_psg_off(2);
+}
+
+void msx_music_tick(void) {
+    uint16_t p;
+    if (!_msx_music_on) return;
+    if (_msx_music_timer == 0) {
+        p = _msx_music_per[_msx_music_step & 15];
+        if (p) {
+            msx_psg_tone(2, p, 12);            /* AY volume is ~logarithmic — 9 was a whisper */
+        } else {
+            msx_psg_off(2);                    /* rest */
+        }
+        ++_msx_music_step;
+    }
+    ++_msx_music_timer;
+    if (_msx_music_timer >= 9) _msx_music_timer = 0;
 }

package/src/platforms/nes/MENTAL_MODEL.md

@@ -393,7 +393,11 @@ build({ output:'rom', platform:'nes',
         inesHeader:{ prgBanks:2, chrBanks:1, mapper:0, mirroring:"vertical" } })
 ```
 Mutually exclusive with `linkerConfig`. Works for any NROM (mapper 0, ≤2 PRG
-banks); for a banked mapper supply a linker `.cfg` that places each bank.
+banks). For a BANKED mapper you don't hand-write the glue anymore:
+`disasm({target:'project'})` emits a HEADER segment (the original 16 iNES
+bytes), a `.segment "PRGn"` wrapper per bank, and a multi-bank `nes_rebuild.cfg`
+(switchable banks at $8000, fixed top bank at $C000), all wired into
+`rebuild.json` via `linkerConfigPath` — a one-call byte-exact rebuild.
 
 **2. `linkerConfig:"chr-rom"` — for homebrew C that ships FIXED tile art.**
 A cc65-C preset (segment split + a CHARS segment in an 8 KB ROM2 bank). Put your
@@ -402,8 +406,11 @@ tiles in `.segment "CHARS"` (`.incbin "tiles.chr"`) + pass the blob via
 other bank configs, prefer `inesHeader`.
 
 **3. `disasm({target:'project'})` — disassemble → rebuild, in two calls.**
-For NES it now extracts the CHR-ROM to `chr.bin`, writes a `rebuild.json` (the
-exact `build({inesHeader})` call, with absolute paths) and a `BUILD.md`. Feed
+For NES it extracts the CHR-ROM to `chr.bin`, writes a `rebuild.json` (the
+exact `build({...})` call, with absolute paths) and a `BUILD.md`. NROM gets the
+`inesHeader` one-call form; BANKED mappers (UxROM/MMC1/MMC3…) get per-bank
+`PRGn` segment wrappers + the original-bytes HEADER segment + a generated
+multi-bank `.cfg` referenced via `linkerConfigPath`. Either way: feed
 `rebuild.json` straight back to `build` and you get a byte-identical ROM. This
 is the RE workhorse loop: `disasm({target:'project'})` → edit the `.asm` →
 rebuild → `diffRoms` to confirm your patch landed.

package/src/platforms/nes/lib/c/nes_runtime.c

@@ -330,6 +330,47 @@ void sound_init(void) {
   APUFRAMECTR = 0x40;      /* 4-step frame counter, disable frame IRQ */
 }
 
+/* ── background music: 16-step melody on the TRIANGLE channel ───────
+ * The pulse channels + noise stay free for sound_play_tone/noise SFX.
+ * Call sound_music_tick() once per frame (after ppu_wait_nmi); the
+ * scaffolds wire it in. sound_music(0) silences it. ("No sound" was
+ * the dominant NES playtest complaint — a rare 6-frame blip isn't
+ * enough; continuous triangle gives every scaffold a musical floor.)
+ * NTSC triangle period for note f ≈ 1789773/(32*f) - 1. */
+static const uint16_t music_period_tbl[16] = {
+    213, 168, 141, 106, 141, 168, 213, 0,   /* C4 E4 G4 C5 G4 E4 C4 -  */
+    253, 213, 168, 126, 168, 213, 253, 0,   /* A3 C4 E4 A4 E4 C4 A3 -  */
+};
+static uint8_t music_enabled = 1;
+static uint8_t music_step;
+static uint8_t music_timer;
+
+void sound_music(uint8_t on) {
+  music_enabled = on;
+  music_step = 0;
+  music_timer = 0;
+  if (!on) { TRI_LINEAR = 0x00; TRI_HI = 0x08; }   /* reload 0 linear → silent */
+}
+
+void sound_music_tick(void) {
+  uint16_t p;
+  if (!music_enabled) return;
+  if (music_timer == 0) {
+    p = music_period_tbl[music_step & 15];
+    if (p) {
+      TRI_LINEAR = 0xFF;                       /* halt flag + max linear: sustain */
+      TRI_LO     = (uint8_t)(p & 0xFF);
+      TRI_HI     = (uint8_t)((p >> 8) & 0x07); /* also reloads the linear counter */
+    } else {
+      TRI_LINEAR = 0x00;                       /* rest */
+      TRI_HI     = 0x08;
+    }
+    ++music_step;
+  }
+  ++music_timer;
+  if (music_timer >= 9) music_timer = 0;
+}
+
 void sound_play_tone(uint8_t channel, uint16_t period, uint8_t vol_4bit, uint8_t length_frames) {
   uint8_t len5 = length_frames & 0x1F;
   uint8_t v = vol_4bit & 0x0F;

package/src/platforms/nes/lib/c/nes_runtime.h

@@ -145,6 +145,8 @@ void sound_init(void);
 void sound_play_tone(uint8_t channel, uint16_t period, uint8_t vol_4bit, uint8_t length_frames);
 void sound_play_noise(uint8_t period_4bit, uint8_t vol_4bit, uint8_t length_frames);
 void sound_off(void);
+void sound_music(uint8_t on);      /* background triangle melody — ON by default; 0 = off */
+void sound_music_tick(void);       /* call once per frame (scaffolds do) */
 
 /* ── Globals ──────────────────────────────────────────────────── */
 extern uint8_t shadow_oam[256];       /* at $0200, DMA'd by NMI */

package/src/platforms/pce/MENTAL_MODEL.md

@@ -101,3 +101,12 @@ screen. Keep at least one (2+ byte) global. See TROUBLESHOOTING.md.
   + LFO.
 - `memory({op:'read'})` regions: `pce_vdc_vram`, `pce_vdc_satb`, `pce_vdc_regs`,
   `pce_vce_palette`, `pce_cpu_regs`, `pce_psg_regs`.
+- `disasm({target:'rom'|'references'|'project'})` — da65's native `huc6280`
+  CPU mode. HuCards >32 KB are handled per 8 KB page (page 0 at `$E000`,
+  where MPR7 maps it at reset — the vectors live there; pages 1+ at `$8000`,
+  an assumed window since the game's MPR writes decide at runtime).
+  `references` tags refs with `romBank`; `disasm({target:'project'})` emits
+  per-page regions + segment wrappers + a generated `.cfg`, and — because the
+  PCE asm toolchain IS cc65/ca65 — a **one-call byte-identical `build()`
+  rebuild** via `rebuild.json` (flat and banked; a 512-byte copier header is
+  split out and re-emitted as a HEADER segment).

package/src/platforms/pce/TROUBLESHOOTING.md

@@ -58,3 +58,12 @@ you likely hit a BRK or an unhandled IRQ — check that you didn't enable a VDC
 `clrscr()` must run before `cputs()` (it inits the font + VDC). Also confirm
 `.bss` is non-empty (see the first entry) — a broken crt0 means conio's font
 upload never happened.
+
+
+## PSG tone plays but is nearly inaudible
+
+The 5-bit channel volume (`PSG_CHAN_CTRL` low bits, 0-31) is roughly an
+ATTENUATOR: each step below 31 costs ~1.5 dB. A "middle" value like 13 is
+about -27 dB — effectively silence on real hardware and most cores. Use
+**29-31 for SFX/music** and treat anything under ~20 as a deliberate whisper.
+(The bundled `psg_tone` scaffold helper and the music ticker default loud.)

package/src/platforms/pce/lib/c/pce_hw.h

@@ -126,6 +126,7 @@ u8   pce_joy_read(void);   /* read pad 1 -> clean bitmask (PCE_JOY_* below)  */
 
 /* ---- sound helpers (pce_sound.c) ----------------------------------------- */
 void psg_tone(u8 chan, u16 freq, u8 vol); /* play a wavetable tone (vol 0..31) */
-void psg_off(u8 chan);                    /* silence + disable a channel        */
+void psg_off(u8 chan);
+void psg_music_tick(void);    /* call once per frame (scaffolds do) */                    /* silence + disable a channel        */
 
 #endif /* PCE_HW_H */

package/src/platforms/pce/lib/c/pce_sound.c

@@ -51,3 +51,25 @@ void psg_off(u8 chan) {
     PSG_CHAN_SELECT = chan;
     PSG_CHAN_CTRL   = 0x00;   /* bit7 clear = channel off, volume 0 */
 }
+
+/* ── background music: 8-step melody loop on channel 5 ─────────────
+ * Call psg_music_tick() once per frame (the scaffolds wire it in after
+ * their vsync wait). Deliberately MINIMAL — the PCE boot bank is 8KB
+ * and the puzzle scaffold sits within ~100 bytes of the ceiling, so
+ * there's no on/off toggle and no rests (re-trigger every note).
+ * SFX use channels 0-3; the melody never fights an effect.
+ * PCE freq is a DIVIDER: pitch ~= 3.58MHz / (32 * freq). */
+static const u16 _music_div[8] = {
+    427, 339, 285, 214, 508, 427, 339, 254,  /* C4 E4 G4 C5 A3 C4 E4 A4 */
+};
+static u8 _music_step;
+static u8 _music_timer;
+
+void psg_music_tick(void) {
+    if (_music_timer == 0) {
+        psg_tone(5, _music_div[_music_step & 7], 29);  /* PCE vol is ~-1.5dB/step from 31 — 13 was -27dB, inaudible */
+        ++_music_step;
+    }
+    ++_music_timer;
+    if (_music_timer >= 9) _music_timer = 0;
+}

package/src/platforms/sms/MENTAL_MODEL.md

@@ -318,6 +318,11 @@ CB/ED/DD/FD/DDCB/FDCB — and feeds the same auto-label, register-annotation,
 file-offset, and `untilReturn` pipeline used by the NES and SNES
 disassemblers.
 
+Sega-mapper banked carts (>48 KB) are handled per-bank: `references` scans
+every 16 KB bank (bank 0 @ `$0000`, bank 1 @ `$4000`, banks 2+ @ their slot-2
+window `$8000`), refs tagged `romBank`; `disasm({target:'project'})` emits one
+region per bank with a bank-by-bank native rebuild recipe in `BUILD.md`.
+
 ## Horizontal scrolling (for side-scrollers)
 
 The `platformer` scaffold is single-screen. To make it a side-scroller:

package/src/platforms/sms/TROUBLESHOOTING.md

@@ -118,6 +118,12 @@ If you ported an SMS ROM straight to `.gg` it'll boot and run, but
 the colours will be very dark (2-bit values reinterpreted as 4-bit)
 and the visible area is in the top-left corner.
 
+Also check the header region byte at `$7FFF` (high nibble = region,
+low nibble = size): romdev stamps `$7C` (GG international) on `.gg`
+builds, but an SMS nibble there (`$4x`) makes gpgx boot the file in
+SMS compatibility mode — wrong resolution and palette depth no matter
+what your code does.
+
 ## "ROM > 32 KB doesn't run"
 
 The default template is single-bank (32 KB). To use the Sega

package/src/platforms/sms/lib/c/sms_crt0.s

@@ -28,10 +28,13 @@
 ;; ─── Reset vector at $0000 ────────────────────────────────────────
         .area _HEADER (ABS)
         .org    0x0000
+        ;; ONLY 8 BYTES fit before the RST $08 vector. The old block here
+        ;; (di/im 1/ld sp/jp = 9 bytes) overflowed into .org 0x0008, whose
+        ;; `ret` stomped the jp's high target byte -> boot jumped into
+        ;; garbage. di+im 1+jp = 6 bytes; SP setup moved to _boot below.
         di                          ; interrupts off until we're ready
         im      1                   ; mode 1 — IRQs jump to $0038
-        ld      sp, #0xDFF0         ; SMS stack (top of WRAM minus 16)
-        jp      gsinit              ; skip the interrupt vector table
+        jp      _boot               ; continue past the vector table
 
 ;; ─── RST handlers (default = return) ──────────────────────────────
         .org    0x0008
@@ -69,6 +72,15 @@
         .org    0x0066
         retn
 
+;; ─── Boot continuation (right after the NMI vector) ───────────────
+;; SP first, then the C runtime init. Lives in the ABS header area so
+;; it exists at a known address regardless of where _CODE is linked
+;; (_CODE must start at >= $0100 so it can't overwrite this table).
+        .org    0x0068
+_boot:
+        ld      sp, #0xDFF0         ; stack at top of WRAM minus 16
+        jp      gsinit
+
 ;; ─── crt0 body ────────────────────────────────────────────────────
 ;; Standard SDCC pattern: jump to a code area, run initializers, then
 ;; call main. The initializer area is filled by sdcc when it sees

package/src/platforms/snes/MENTAL_MODEL.md

@@ -222,6 +222,11 @@ video are fully readable, so you assert live state instead of guessing:
   cpu:'spc700'})` for the sound CPU.
 - **Audio:** the S-DSP is fully decodable — full per-voice state plus the
   master mixer (see "Debugging sound" above for `audioDebug`).
+- **`disasm({target:'references'})`** scans EVERY 32 KB LoROM bank (refs
+  tagged `romBank`) — a hit in bank 12 of a 1 MB cart shows up, not just
+  bank 0. `disasm({target:'project'})` likewise splits per-bank with a
+  native ca65/ld65 rebuild recipe (build() is asar, which can't consume
+  the disasm's ca65 output).
 - **Memory regions:** `memory({op:'read'})` exposes OAM, CGRAM, ARAM (SPC700
   audio RAM), and **FillRAM**. Note the FillRAM quirk: snes9x mirrors the
   PPU registers $2100-$213F (OBSEL/BGMODE/TM/TS/color-math, etc.) into

package/src/playtest/playtest.js

@@ -323,6 +323,43 @@ export function letterbox(winW, winH, targetAspect) {
   };
 }
 
+// How recently (in window ticks ≈ frames at 60fps real time) the human must
+// have pressed something for the session to count as "human input active".
+// 120 ticks ≈ 2 s — long enough to span the natural gaps WITHIN active play
+// (between taps), short enough that an agent isn't warned off long after the
+// human set the pad down.
+export const HUMAN_INPUT_ACTIVE_FRAMES = 120;
+
+/**
+ * Any button held in a built input-port object? The C64 virtual keys
+ * (c64_f1 …) count too — any truthy value is a press.
+ * @param {Record<string, boolean>} port
+ */
+export function anyButtonHeld(port) {
+  for (const k in port) if (port[k]) return true;
+  return false;
+}
+
+/**
+ * Pure "when did the human last actually press something" tracker behind the
+ * co-drive detection. The tick loop calls note() every unpaused frame; the
+ * session handle (and through it catalog/frame/input warnings) asks active()/
+ * framesSince(). Pure + exported so the activity contract is unit-testable
+ * without an SDL window.
+ * @param {number} [activeWindow] ticks within which a press counts as active
+ */
+export function createHumanInputTracker(activeWindow = HUMAN_INPUT_ACTIVE_FRAMES) {
+  let lastTick = null;
+  return {
+    /** @param {boolean} pressing @param {number} tick */
+    note(pressing, tick) { if (pressing) lastTick = tick; },
+    /** @param {number} tick @returns {number | null} null = never pressed */
+    framesSince(tick) { return lastTick == null ? null : Math.max(0, tick - lastTick); },
+    /** @param {number} tick */
+    active(tick) { return lastTick != null && tick - lastTick <= activeWindow; },
+  };
+}
+
 function tvAspectFor(platform, displayAspect) {
   switch (platform) {
     case "nes":
@@ -505,6 +542,15 @@ export async function playtest(args) {
   let closeResolver = null;
   const closedPromise = new Promise((r) => { closeResolver = r; });
 
+  // Human co-drive detection. tickCount advances every tick (even paused /
+  // mid-rebuild) so "frames since the human pressed" tracks wall time at
+  // ~60fps. humanInputDirty = the host's input state currently holds buttons
+  // WE wrote for the human — it buys exactly one release write after they let
+  // go, after which an idle window leaves the agent's setInput alone.
+  let tickCount = 0;
+  const humanInput = createHumanInputTracker();
+  let humanInputDirty = false;
+
   // Track pixel-size from resize events instead of polling window.width every
   // tick — that's the retroemu pattern. window.pixelWidth/height is the real
   // backing-store size (which is what dstRect cares about); on HiDPI it
@@ -581,6 +627,7 @@ export async function playtest(args) {
 
   function tick() {
     if (!running || window.destroyed) { stop(); return; }
+    tickCount++;
     // Resolve the session's CURRENT host this frame. A `runSource`/`loadMedia`
     // rebuild swapped it; we follow it so the window shows the latest build.
     // If there's transiently no host or no media loaded (mid-swap), skip this
@@ -601,8 +648,9 @@ export async function playtest(args) {
     const paused = !!h.status.paused || !!h._renderTickSuspended;
     // Read controller state for each slot independently. Slot 0 = port 0
     // (player 1), slot 1 = port 1 (player 2). Each slot's input is built
-    // into its own port object; the agent's setInput is overwritten each
-    // tick (matching prior behavior). Select+Start on any controller quits.
+    // into its own port object. The agent's setInput is only overwritten
+    // while the human is ACTUALLY pressing (see the write below) — an idle
+    // window leaves it alone. Select+Start on any controller quits.
     let quit = false;
     const isC64 = h.status?.platform === "c64";
     function readControllerInto(port, inst) {
@@ -667,7 +715,12 @@ export async function playtest(args) {
           if (heldKeys.has(keyName)) port0[vbtn] = true;
         }
       }
+      // Did the human actually press anything this tick (pad or keyboard,
+      // either port)? Rewind-scrubbing counts as activity too — the human is
+      // actively manipulating emulator state even though R maps to no button.
+      const humanPressing = anyButtonHeld(port0) || anyButtonHeld(port1);
       const isRewinding = heldKeys.has("r") && rewindBuffer.length > 0;
+      humanInput.note(humanPressing || isRewinding, tickCount);
       if (isRewinding) {
         // Restore the previous snapshot and run one frame to produce its visual.
         const snap = rewindBuffer.pop();
@@ -687,7 +740,16 @@ export async function playtest(args) {
             if (rewindBuffer.length > MAX_REWIND_FRAMES) rewindBuffer.shift();
           } catch {}
         }
-        h.setInput({ ports: [port0, port1] });
+        // Write input ONLY while the human is actually pressing, plus ONE
+        // release write after they let go (humanInputDirty). The old behavior
+        // wrote all-zeros EVERY tick, which silently clobbered the agent's
+        // input({op:'set'}) even when nobody was touching the pad. An idle
+        // window now leaves the host's input state alone; the human still
+        // wins the instant they press.
+        if (humanPressing || humanInputDirty) {
+          h.setInput({ ports: [port0, port1] });
+          humanInputDirty = humanPressing;
+        }
         let stepped = 0;
         try {
           stepped = h.stepFrames(1);
@@ -817,6 +879,14 @@ export async function playtest(args) {
     // hot-plug), so a caller can decide whether to surface the keyboard help.
     // 0 → the user has no pad and is on the keyboard fallback.
     get controllerCount() { return controllers.filter(Boolean).length; },
+    // Human co-drive detection: has the human pressed anything (pad, keyboard,
+    // or rewind-scrub) within the last ~2 s of window ticks? Drives the
+    // catalog({op:'status'}) flags and the frame/input co-drive warnings so an
+    // agent KNOWS when a human is driving the same emulator.
+    humanInputActive() { return humanInput.active(tickCount); },
+    // Ticks (≈ frames at 60fps real time) since the last human press; null if
+    // the human hasn't touched anything since the window opened.
+    framesSinceHumanInput() { return humanInput.framesSince(tickCount); },
     // The emulator host the window is CURRENTLY rendering. The window follows
     // the session's live host (a `runSource`/`loadMedia` rebuild updates it in
     // place), so this is whatever the human is looking at right now. Exposed so