romdevtools 0.27.0 → 0.29.0

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

package/src/toolchains/cc65/presets/nes/chr-ram-runtime.cfg

@@ -19,13 +19,15 @@
 #   3. Write CHR data from C at runtime: PPUADDR = 0x00; PPUDATA = byte; etc.
 
 SYMBOLS {
-    # Stack is $0200 (512 B) so the top RAM page ($0700-$07FF) can be
-    # reserved below for a music driver's scratch RAM (FamiTone2 et al.),
-    # which needs a dedicated, page-aligned block that the C BSS/DATA
-    # region must NOT overlap. Tiny NROM scaffolds use far less than 512 B
-    # of stack, so this is safe; scaffolds with no music driver simply
-    # leave the reserved page unused.
-    __STACKSIZE__: type = weak, value = $0200;
+    # C parameter stack is ONE page ($0600-$06FF, grows down from $0700).
+    # NROM-sized C games use far less than 256 B of it (shallow call
+    # depth, mostly static data), and shrinking it frees $0500-$05FF as
+    # the USER SCRATCH PAGE: game code may place absolute-addressed
+    # arrays there (e.g. `#define BOARD ((unsigned char*)0x0500)`) when
+    # BSS ($0300-$04FF) is full — the puzzle example game does exactly
+    # this. The top page ($0700-$07FF) stays reserved for a music
+    # driver's scratch RAM (FamiTone2 et al.).
+    __STACKSIZE__: type = weak, value = $0100;
 }
 MEMORY {
     ZP:     file = "", start = $0002, size = $001A, type = rw, define = yes;
@@ -41,7 +43,10 @@ MEMORY {
 
     # NO ROM2 / CHARS — this is the whole point of the CHR-RAM preset.
 
-    SRAM:   file = "", start = $0500, size = __STACKSIZE__, define = yes;
+    # $0500-$05FF: user scratch page (see SYMBOLS note) — NOT a segment;
+    # game code addresses it absolutely so the linker never places
+    # anything here.
+    SRAM:   file = "", start = $0600, size = __STACKSIZE__, define = yes;
 
     # Reserved page for a sound-driver's RAM scratch ($0700-$07FF). The
     # bundled FamiTone2 engine (music_demo scaffold) pins FT_BASE_ADR here

package/src/toolchains/cc65/presets/nes/chr-ram-runtime.crt0.s

@@ -28,7 +28,12 @@
         .import         _main, zerobss, copydata
         .import         __RAM_START__, __RAM_SIZE__
         .import         __SRAM_START__, __SRAM_SIZE__
-        .import         _vram_queue_flush
+        .import         _vram_q_hi, _vram_q_lo, _vram_q_val
+        .import         _vram_queue_head, _vram_queue_len, _vram_queue_lock
+
+; Must match nes_runtime.c (QUEUE_MAX 32 ring buffer).
+QUEUE_MASK   = 31
+FLUSH_BUDGET = 16
         .import         _scroll_x, _scroll_y, _ppuctrl_value, _nmi_counter
         .importzp       c_sp
 
@@ -39,7 +44,12 @@
         .byte   $4e, $45, $53, $1a   ; "NES" + EOF
         .byte   2                    ; PRG-ROM banks (16K each) → 32K
         .byte   0                    ; CHR-ROM banks (8K each)  → 0 = CHR-RAM
-        .byte   %00000001            ; flags6 — vertical mirroring
+        .byte   %00000011            ; flags6 — vertical mirroring + BATTERY.
+                                     ; The battery bit maps persistent 8KB
+                                     ; PRG-RAM at $6000 (the save_ram region)
+                                     ; — hiscore_load/save in nes_runtime use
+                                     ; it. Benign when unused; without it,
+                                     ; $6000-$7FFF is OPEN BUS on NROM.
         .byte   %00000000            ; flags7 — mapper hi nybble
         .byte   0, 0, 0, 0, 0, 0, 0, 0
 
@@ -129,9 +139,46 @@ nmi:
         lda     #$02            ; high byte of $0200
         sta     $4014           ; PPU OAMDMA — kicks off the copy
 
-        ; Flush the VRAM queue (writes anything game code stashed via
-        ; vram_set / tile_set / tile_set_palette). PPU is unlocked here.
-        jsr     _vram_queue_flush
+        ; ── Drain the VRAM queue — IN ASSEMBLY, on purpose ──────────────
+        ; Vblank is ~2273 CPU cycles and the OAM DMA above just spent 513.
+        ; Compiled C costs 200+ cycles per queue entry, so a C flush blows
+        ; past the end of vblank — and PPUDATA writes during ACTIVE
+        ; RENDERING land at corrupted addresses (the PPU's internal v
+        ; register is busy fetching tiles; its coarse-X/fine-Y counters
+        ; shear every late write). This loop costs ~40 cycles per entry,
+        ; so FLUSH_BUDGET entries always finish safely inside vblank.
+        ; QUEUE_MASK/FLUSH_BUDGET must match nes_runtime.c's ring buffer.
+        lda     _vram_queue_lock
+        bne     @flush_done     ; a push is mid-flight — skip this vblank
+        lda     _vram_queue_len
+        beq     @flush_done
+        cmp     #FLUSH_BUDGET
+        bcc     @flush_n_ok
+        lda     #FLUSH_BUDGET
+@flush_n_ok:
+        sta     nmi_drain       ; loop counter
+        sta     nmi_drained     ; remembered for the length update
+        bit     $2002           ; reset the PPUADDR write latch
+        ldx     _vram_queue_head
+@flush_loop:
+        lda     _vram_q_hi,x
+        sta     $2006
+        lda     _vram_q_lo,x
+        sta     $2006
+        lda     _vram_q_val,x
+        sta     $2007
+        inx
+        txa
+        and     #QUEUE_MASK     ; ring wrap
+        tax
+        dec     nmi_drain
+        bne     @flush_loop
+        stx     _vram_queue_head
+        lda     _vram_queue_len
+        sec
+        sbc     nmi_drained
+        sta     _vram_queue_len
+@flush_done:
 
         ; Reset PPUADDR to $2000 (otherwise the queue's last $2006 write
         ; leaves it dangling and the PPU samples random VRAM as the BG).
@@ -172,6 +219,12 @@ irq:    rti
 _shadow_oam: .res 256
 
 ; ------------------------------------------------------------------------
+; NMI-private temporaries — deliberately NOT cc65's zp tmp1-4 (the NMI
+; would corrupt them under interrupted C code).
+.segment "BSS"
+nmi_drain:   .res 1
+nmi_drained: .res 1
+
 .segment "VECTORS"
         .word   nmi             ; $FFFA
         .word   start           ; $FFFC

package/src/toolchains/cc65/presets/nes/chr-rom.crt0.s

@@ -22,7 +22,12 @@
         .import         _main, zerobss, copydata
         .import         __RAM_START__, __RAM_SIZE__
         .import         __SRAM_START__, __SRAM_SIZE__
-        .import         _vram_queue_flush
+        .import         _vram_q_hi, _vram_q_lo, _vram_q_val
+        .import         _vram_queue_head, _vram_queue_len, _vram_queue_lock
+
+; Must match nes_runtime.c (QUEUE_MAX 32 ring buffer).
+QUEUE_MASK   = 31
+FLUSH_BUDGET = 16
         .import         _scroll_x, _scroll_y, _ppuctrl_value, _nmi_counter
         .importzp       c_sp
 
@@ -109,8 +114,46 @@ nmi:
         lda     #$02            ; high byte of $0200
         sta     $4014           ; PPU OAMDMA — kicks off the copy
 
-        ; Flush the VRAM queue (nametable/palette writes game code stashed).
-        jsr     _vram_queue_flush
+        ; ── Drain the VRAM queue — IN ASSEMBLY, on purpose ──────────────
+        ; Vblank is ~2273 CPU cycles and the OAM DMA above just spent 513.
+        ; Compiled C costs 200+ cycles per queue entry, so a C flush blows
+        ; past the end of vblank — and PPUDATA writes during ACTIVE
+        ; RENDERING land at corrupted addresses (the PPU's internal v
+        ; register is busy fetching tiles; its coarse-X/fine-Y counters
+        ; shear every late write). This loop costs ~40 cycles per entry,
+        ; so FLUSH_BUDGET entries always finish safely inside vblank.
+        ; QUEUE_MASK/FLUSH_BUDGET must match nes_runtime.c's ring buffer.
+        lda     _vram_queue_lock
+        bne     @flush_done     ; a push is mid-flight — skip this vblank
+        lda     _vram_queue_len
+        beq     @flush_done
+        cmp     #FLUSH_BUDGET
+        bcc     @flush_n_ok
+        lda     #FLUSH_BUDGET
+@flush_n_ok:
+        sta     nmi_drain       ; loop counter
+        sta     nmi_drained     ; remembered for the length update
+        bit     $2002           ; reset the PPUADDR write latch
+        ldx     _vram_queue_head
+@flush_loop:
+        lda     _vram_q_hi,x
+        sta     $2006
+        lda     _vram_q_lo,x
+        sta     $2006
+        lda     _vram_q_val,x
+        sta     $2007
+        inx
+        txa
+        and     #QUEUE_MASK     ; ring wrap
+        tax
+        dec     nmi_drain
+        bne     @flush_loop
+        stx     _vram_queue_head
+        lda     _vram_queue_len
+        sec
+        sbc     nmi_drained
+        sta     _vram_queue_len
+@flush_done:
 
         ; Reset PPUADDR to $2000 so the PPU doesn't sample random VRAM as BG.
         bit     $2002
@@ -147,6 +190,12 @@ irq:    rti
 _shadow_oam: .res 256
 
 ; ------------------------------------------------------------------------
+; NMI-private temporaries — deliberately NOT cc65's zp tmp1-4 (the NMI
+; would corrupt them under interrupted C code).
+.segment "BSS"
+nmi_drain:   .res 1
+nmi_drained: .res 1
+
 .segment "VECTORS"
         .word   nmi             ; $FFFA
         .word   start           ; $FFFC

package/src/toolchains/cc65/presets/pce/rom32k.cfg

@@ -0,0 +1,52 @@
+# PC Engine 32KB HuCard ld65 config (romdev 'rom32k' preset).
+#
+# WHY THIS EXISTS: cc65's stock pce.cfg defaults to an 8KB image, and its
+# documented 16K/32K option ($CARTSIZE) places STARTUP/VECTORS at the END of
+# the file — but a HuCard maps file offset 0 as bank 0, and the HuC6280 reset
+# maps MPR7 (=$E000-$FFFF, where the vectors live) to BANK 0. So a stock-cfg
+# 32K image boots to a black screen (verified on geargrafx). This config puts
+# bank 0 (STARTUP/VECTORS + hot code) FIRST in the file, at $E000, and the
+# remaining 24KB of banks 1-3 at $8000-$DFFF — exactly where cc65's pce crt0
+# TAMs them (MPR4=bank1, MPR5=bank2, MPR6=bank3) before calling main().
+SYMBOLS {
+    __CARTSIZE__:  type = weak, value = $8000; # crt0 compares >$8000 vs this
+    __STACKSIZE__: type = weak, value = $0300; # 3 pages stack
+}
+MEMORY {
+    ZP:   file = "", start = $0000, define = yes, size = $0100;
+    # RAM bank ($F8 at MPR1)
+    MAIN: file = "", start = $2200, define = yes, size = $1E00 - __STACKSIZE__;
+    # HuCard bank 0 — hardware maps it at $E000 (MPR7) at reset. File offset 0.
+    ROM0: file = %O, start = $E000, size = $2000, fill = yes, fillval = $FF;
+    # HuCard banks 1-3 — crt0 maps them at $8000/$A000/$C000 (MPR4/5/6).
+    ROM:  file = %O, start = $8000, size = $6000, fill = yes, fillval = $FF;
+}
+SEGMENTS {
+    ZEROPAGE: load = ZP,   type = zp;
+    EXTZP:    load = ZP,   type = zp, optional = yes;
+    APPZP:    load = ZP,   type = zp, optional = yes;
+    DATA:     load = ROM0, run = MAIN, type = rw,  define = yes;
+    INIT:     load = MAIN, type = bss, optional = yes;
+    BSS:      load = MAIN, type = bss,             define = yes;
+    LOWCODE:  load = ROM0, type = ro,  optional = yes;
+    ONCE:     load = ROM0, type = ro,  optional = yes;
+    CODE:     load = ROM,  type = ro;
+    RODATA:   load = ROM,  type = ro;
+    STARTUP:  load = ROM0, type = ro,  start = $FFF6 - $0066;
+    VECTORS:  load = ROM0, type = ro,  start = $FFF6;
+}
+FEATURES {
+    CONDES: type    = constructor,
+            label   = __CONSTRUCTOR_TABLE__,
+            count   = __CONSTRUCTOR_COUNT__,
+            segment = ONCE;
+    CONDES: type    = destructor,
+            label   = __DESTRUCTOR_TABLE__,
+            count   = __DESTRUCTOR_COUNT__,
+            segment = RODATA;
+    CONDES: type    = interruptor,
+            label   = __INTERRUPTOR_TABLE__,
+            count   = __INTERRUPTOR_COUNT__,
+            segment = RODATA,
+            import  = __CALLIRQ__;
+}

package/src/toolchains/index.js

@@ -37,7 +37,7 @@ const CC65_TARGET = {
 const LANGUAGE_TOOLCHAIN = {
   atari2600: {
     asm:    { toolchain: "dasm",         available: true },
-    basic:  { toolchain: "batariBasic",  available: false, note: "BASIC for 2600 via batariBasic — not bundled. bB's transpiler is written in Perl, which we don't ship as WASM. A port to C or JS would be a multi-day project. For now, write 2600 games in 6507 asm via dasm — the bundled scaffolds (default, paddle, single_screen) show the canonical race-the-beam pattern, and an LLM agent writes 2600 asm fluently." },
+    basic:  { toolchain: "batariBasic",  available: false, note: "BASIC for 2600 via batariBasic — not bundled. bB's transpiler is written in Perl, which we don't ship as WASM. A port to C or JS would be a multi-day project. For now, write 2600 games in 6507 asm via dasm — the bundled example games (default, paddle, single_screen) show the canonical race-the-beam pattern, and an LLM agent writes 2600 asm fluently." },
   },
   nes: {
     asm: { toolchain: "cc65",  available: true },
@@ -65,11 +65,11 @@ const LANGUAGE_TOOLCHAIN = {
   },
   snes: {
     asm: { toolchain: "asar",       available: true },
-    c:   { toolchain: "tcc816+wladx", available: true, note: "C for SNES via tcc-65816 + wla-65816 + wlalink. The PVSnesLib runtime IS bundled (built from source) and auto-linked — #include <snes.h> gives you consoleDrawText, setMode, oamSet, WaitForVBlank, etc. out of the box. `createGame`/`createProject` scaffold a complete PVSnesLib C project. Pass options.pvsneslib:false for the bare-main minimum-viable path." },
+    c:   { toolchain: "tcc816+wladx", available: true, note: "C for SNES via tcc-65816 + wla-65816 + wlalink. The PVSnesLib runtime IS bundled (built from source) and auto-linked — #include <snes.h> gives you consoleDrawText, setMode, oamSet, WaitForVBlank, etc. out of the box. `examples({op:'fork'})` gives you a complete working PVSnesLib C project. Pass options.pvsneslib:false for the bare-main minimum-viable path." },
   },
   genesis: {
     asm: { toolchain: "vasm68k",      available: true },
-    c:   { toolchain: "m68k-elf-gcc", available: true, note: "C for Genesis via gcc 14.2.0 + binutils + newlib, all compiled to WASM. The SGDK runtime IS bundled (built from source) and auto-linked — sprite engine, VDP, controller, PSG/Z80 sound, resource helpers all work; #include <genesis.h>. `createGame`/`createProject` scaffold a complete SGDK C project (the recommended path). Pass options.sgdk:false for the bare-gcc minimum-viable path." },
+    c:   { toolchain: "m68k-elf-gcc", available: true, note: "C for Genesis via gcc 14.2.0 + binutils + newlib, all compiled to WASM. The SGDK runtime IS bundled (built from source) and auto-linked — sprite engine, VDP, controller, PSG/Z80 sound, resource helpers all work; #include <genesis.h>. `examples({op:'fork'})` gives you a complete working SGDK C project (the recommended path). Pass options.sgdk:false for the bare-gcc minimum-viable path." },
   },
   gba: {
     c: { toolchain: "arm-none-eabi-gcc", available: true, note: "C for GBA via gcc 14.2.0 + binutils + newlib + libtonc 1.4.5 (default) OR libgba 0.5.4 (opt-in via runtime:\"libgba\"), all compiled to WASM (R24 + R28). #include <tonc.h> + tte_write/tte_printf works out of the box — that's the canonical Tonc-tutorial API every published GBA C resource uses. Caveat: tte_iohook (libtonc) and console.c (libgba) — the libsysbase-backed iprintf bridges — are NOT bundled. Use tte_printf directly, which is what the Tonc tutorial actually does." },
@@ -91,7 +91,7 @@ const LANGUAGE_TOOLCHAIN = {
  * Default language per platform. The choice reflects what's fastest /
  * smallest / best-matched to LLM fluency. Every platform that has a bundled
  * C compiler + runtime defaults to C — that's the canonical, productive path
- * and what `createGame`/`createProject` scaffold (cc65 for NES/C64/Atari7800/
+ * and what `examples({op:'fork'})` projects use (cc65 for NES/C64/Atari7800/
  * Lynx, SDCC for GB/GBC/SMS/GG, gcc+SGDK for Genesis, tcc+PVSnesLib for SNES,
  * gcc+libtonc for GBA). Platforms whose only bundled toolchain is an assembler
  * default to asm (Atari 2600 → dasm; SNES/Genesis keep an asm option too, but
@@ -727,16 +727,25 @@ export async function buildForPlatform(args) {
     // the cartridge header + reset vectors which the custom crt0 provides.
     // MSX: _CODE goes at $4010 — a cartridge maps at $4000-$BFFF and the first
     // 16 bytes are the ROM header ("AB" + INIT vector) the crt0 emits.
-    const codeLoc = args.codeLoc ?? (args.platform === "msx" ? MSX_CODE_LOC : 0x0000);
+    // SMS/GG: _CODE goes at $0100 — $0000-$00FF belongs to the crt0's ABS
+    // _HEADER area (reset + RST/IRQ/NMI vectors + _boot). The old default of
+    // $0000 linked _CODE ON TOP of the vector table: makebin emitted gsinit
+    // at $0000 and the di/im 1/SP-init/ISR vectors were GONE — it booted in a
+    // BIOS-less emulator by accident (gsinit happened to sit at the reset
+    // vector) but had no working IRQ/NMI/pause handling and was one EI away
+    // from jumping into garbage on real hardware.
+    const codeLoc = args.codeLoc ?? (
+      args.platform === "msx" ? MSX_CODE_LOC
+      : (args.platform === "sms" || args.platform === "gg") ? 0x0100
+      : 0x0000);
     const romSize = SDCC_ROM_SIZE[args.platform] ?? 32 * 1024;
 
     // crt0 + headers + sources come straight from the caller. The build
     // pipeline does NOT auto-inject platform runtimes, custom crt0s,
     // or post-link header patches. Every byte that compiles is visible
-    // to the caller's repo. Use `createProject({platform, template})`
-    // to scaffold a self-contained project with the runtime files
-    // copied in, or call `getStarterSnippet` / `getAllStarterSnippets`
-    // to fetch individual pieces.
+    // to the caller's repo. Use `examples({op:'fork'})` to get a
+    // self-contained project with the runtime files copied in, or
+    // `examples({op:'snippets'/'copySnippets'})` to fetch individual pieces.
     const crt0 = args.crt0;
 
     // Pre-flight lint: scan the C sources for known SDCC C89 violations
@@ -777,10 +786,27 @@ export async function buildForPlatform(args) {
       // and RAM-size ($0149) bytes — without -m/-r, -v leaves them at the
       // linker's garbage pad (e.g. type $3C), and emulators/hardware reject
       // an unknown MBC type with "retro_load_game failed". -m 0x00 = ROM ONLY
-      // (no mapper), -r 0x00 = no cart RAM — correct for these 32KB scaffolds.
+      // (no mapper), -r 0x00 = no cart RAM — correct for plain 32KB builds.
+      //
+      // Battery-cart passthrough (0.29.0 examples): a crt0 may DECLARE the
+      // cart in the header window (the GB equivalent of the NES crt0's iNES
+      // BATTERY bit — see the gbc lib gb_crt0.s, which emits $0147=$03 /
+      // $0149=$02 for MBC1+RAM+BATTERY so hi-scores persist in SAVE_RAM).
+      // If the linked image carries a KNOWN battery-MBC type byte with a
+      // sane RAM size, pass those through to rgbfix instead of stomping
+      // them to ROM-only; anything unrecognized (linker pad garbage) still
+      // falls back to the safe ROM-only default, so crt0s that don't
+      // declare a cart behave exactly as before.
+      const BATTERY_CART_TYPES = new Set([0x03, 0x06, 0x0F, 0x10, 0x13, 0x1B, 0x1E]); // MBC1/2/3/5 +BATTERY variants
+      const declType = binary.length > 0x149 ? binary[0x147] : 0x00;
+      const declRam = binary.length > 0x149 ? binary[0x149] : 0x00;
+      const cartByte = BATTERY_CART_TYPES.has(declType) ? declType : 0x00;
+      const ramByte = cartByte !== 0x00 && declRam >= 0x01 && declRam <= 0x05 ? declRam : 0x00;
+      const mArg = "0x" + cartByte.toString(16).padStart(2, "0").toUpperCase();
+      const rArg = "0x" + ramByte.toString(16).padStart(2, "0").toUpperCase();
       const fixOpts = args.platform === "gbc"
-        ? ["-v", "-p", "0xFF", "-C", "-m", "0x00", "-r", "0x00"]
-        : ["-v", "-p", "0xFF", "-m", "0x00", "-r", "0x00"];
+        ? ["-v", "-p", "0xFF", "-C", "-m", mArg, "-r", rArg]
+        : ["-v", "-p", "0xFF", "-m", mArg, "-r", rArg];
       const fix = await runRgbfix({ rom: binary, options: fixOpts });
       if (fix.exitCode === 0 && fix.binary) {
         binary = fix.binary;
@@ -809,32 +835,51 @@ export async function buildForPlatform(args) {
     // rejected it. Checksum = sum of bytes $0000..$7FEF (everything before
     // the header), stored little-endian. GG BIOS doesn't check, but writing
     // it is harmless. Only touches ROMs that actually have the header.
-    if (binary && r.exitCode === 0 && (args.platform === "sms" || args.platform === "gg") && binary.length >= 0x8000) {
+    if (binary && r.exitCode === 0 && (args.platform === "sms" || args.platform === "gg")) {
+      // Pad to a full 32KB bank FIRST. sdld emits up to the highest used
+      // address, so a small program can come out under $8000 — which (a)
+      // skipped this whole header block before (the header guard required
+      // 32KB) and (b) odd-size ROMs misbehave on real mappers/flashcarts.
+      if (binary.length < 0x8000) {
+        const padded = new Uint8Array(0x8000);
+        padded.set(binary);
+        binary = padded;
+      }
       const hdr = 0x7FF0;
       const hasHeader = String.fromCharCode(...binary.slice(hdr, hdr + 8)) === "TMR SEGA";
+      // Region nibble is PLATFORM-SPECIFIC and load-bearing: 4 = SMS export,
+      // 7 = GG international. A .gg ROM stamped with an SMS region (3/4) makes
+      // Genesis Plus GX (RetroArch/RetroDECK's SMS+GG core) boot it in "GG
+      // running SMS software" COMPATIBILITY mode — wrong video mode + wrong
+      // CRAM format for a native-GG program → black/garbled screen on the
+      // user's device while our BIOS-less host looked fine. Size nibble $C =
+      // 32KB checksum range ($0000-$7FEF).
+      const regionSize = args.platform === "gg" ? 0x7C : 0x4C;
       if (!hasHeader) {
         // No header emitted by the crt0 → write a complete TMR SEGA header
         // into the last 16 bytes of bank 0 ($7FF0-$7FFF). Without this the
         // export (US/EU) SMS BIOS shows "SOFTWARE ERROR" and refuses to run.
         // $7FF0-$7FF7 "TMR SEGA"; $7FF8-$7FF9 reserved ($00); $7FFA-$7FFB
         // checksum (filled below); $7FFC-$7FFE product code/version (zeros
-        // ok for homebrew); $7FFF region+size = $4C (region 4 = export,
-        // size $C = 32KB, the checksum range that covers $0000-$7FEF).
+        // ok for homebrew); $7FFF region+size (see regionSize above).
         const TMR = [0x54,0x4D,0x52,0x20,0x53,0x45,0x47,0x41]; // "TMR SEGA"
         for (let i = 0; i < 8; i++) binary[hdr + i] = TMR[i];
         binary[hdr + 8] = 0x00; binary[hdr + 9] = 0x00;   // reserved
         binary[hdr + 12] = 0x00; binary[hdr + 13] = 0x00; // product code lo
         binary[hdr + 14] = 0x00;                          // product/version
-        binary[hdr + 15] = 0x4C;                          // region 4 (export) + size $C (32KB)
       }
+      // Always stamp the platform-correct region/size — a crt0-provided header
+      // with an SMS region on a .gg build has the same compat-mode problem.
+      binary[hdr + 15] = regionSize;
       // Checksum = sum of bytes $0000..$7FEF (everything before the header),
-      // stored little-endian at $7FFA. Region/size $4C declares the 32KB
-      // range, so the BIOS checksums $0000-$7FEF.
+      // stored little-endian at $7FFA. Size nibble $C declares the 32KB
+      // range, so the BIOS checksums $0000-$7FEF. (The GG BIOS doesn't
+      // checksum, but writing it is harmless and correct.)
       let sum = 0;
       for (let i = 0; i < 0x7FF0; i++) sum = (sum + binary[i]) & 0xFFFF;
       binary[0x7FFA] = sum & 0xFF;
       binary[0x7FFB] = (sum >> 8) & 0xFF;
-      r.log += `\n--- SMS header ${hasHeader ? "checksum fixed" : "written + checksummed"} ($7FFA=${sum.toString(16).toUpperCase().padStart(4,"0")}, region/size=$4C) ---`;
+      r.log += `\n--- ${args.platform.toUpperCase()} header ${hasHeader ? "checksum fixed" : "written + checksummed"} ($7FFA=${sum.toString(16).toUpperCase().padStart(4,"0")}, region/size=$${regionSize.toString(16).toUpperCase()}) ---`;
     }
     // MSX: the binary built with codeLoc=$4010 is a $4000-based page image.
     // SDCC/sdldz80 emit an ihx that, converted to bin, starts at the lowest