romdevtools 0.26.0 → 0.28.0

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

package/src/toolchains/index.js

@@ -727,7 +727,17 @@ 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
@@ -809,32 +819,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