romdevtools 0.13.0 → 0.15.0

package/src/platforms/gbc/MENTAL_MODEL.md

@@ -16,7 +16,7 @@ the same wall.
    `build({output:'rom'})` / `build({output:'run'})` do this for you at build time: every byte
    at $0134..$014C is filled, and on `platform:"gbc"` the CGB flag at
    $0143 is set to $80 (CGB-aware + DMG-compatible). You do **not** run
-   `patchGbHeader` on a freshly built ROM. Reach for `patchGbHeader` only
+   `romPatch({op:'gbHeader'})` on a freshly built ROM. Reach for `romPatch({op:'gbHeader'})` only
    to fix up an existing / externally built ROM whose header was never
    set, or to override a field — e.g. starting from a `.gb` ROM and
    wanting CGB color, pass `cgb: true` explicitly.
@@ -161,11 +161,11 @@ the only differences at build time are:
 
 - ROM extension: `.gbc` (vs `.gb`)
 - the build sets `$0143 = $80` to flip CGB mode on (automatic when you
-  build with `platform:"gbc"` — no manual `patchGbHeader` step)
+  build with `platform:"gbc"` — no manual `romPatch({op:'gbHeader'})` step)
 - gambatte core accepts both DMG + CGB-mode ROMs
 
 For new GBC code that wants to be CGB-only (no DMG fallback) set the
-CGB byte to `$C0` instead of `$80` — `patchGbHeader({path, cgb:true})`
+CGB byte to `$C0` instead of `$80` — `romPatch({op:'gbHeader', path, cgb:true})`
 on the built ROM can override it.
 
 ## Horizontal scrolling (for side-scrollers)

package/src/platforms/gbc/TROUBLESHOOTING.md

@@ -59,7 +59,7 @@ and falls back to DMG mode when it's `$00`.
 When you build with `platform:"gbc"`, `build({output:'rom'})` / `build({output:'run'})`
 **auto-fix the header** — Nintendo logo, header + global checksums,
 and `$0143 = $80` (CGB-enhanced) — so a freshly built `.gbc` already
-boots in color. You do **not** call `patchGbHeader` for that.
+boots in color. You do **not** call `romPatch({op:'gbHeader'})` for that.
 
 ```js
 build({ output: 'run', platform: "gbc", language: "c", ... });  /* header auto-fixed */
@@ -67,7 +67,7 @@ build({ output: 'run', platform: "gbc", language: "c", ... });  /* header auto-f
 
 If you instead see green-shade DMG mode, the ROM was almost certainly
 built with `platform:"gb"` (so the CGB flag stayed `$00`). Rebuild with
-`platform:"gbc"`. Reach for `patchGbHeader` only to fix up an existing /
+`platform:"gbc"`. Reach for `romPatch({op:'gbHeader'})` only to fix up an existing /
 externally built `.gbc` whose header was never set, or to override a
 header field (e.g. force `cgb:false`).
 
@@ -106,12 +106,12 @@ Without the attribute writes, every BG tile defaults to palette 0.
 ## "Game ran on Game Boy emulator but not on Game Boy Color emulator"
 
 `loadMedia({platform:"gbc", path})` expects gambatte in CGB mode. If
-your ROM was built with `platform:"gb"` (no patchGbHeader) the file
+your ROM was built with `platform:"gb"` (no gbHeader patch) the file
 extension is `.gb` and the header CGB byte is $00, so gambatte starts
 in DMG mode. To switch a DMG ROM to CGB:
 
 1. Rename / re-extension to `.gbc`
-2. Run `patchGbHeader({path:"out.gbc"})` — also fixes the global
+2. Run `romPatch({op:'gbHeader', path:"out.gbc"})` — also fixes the global
    checksum that the boot ROM checks
 
 ## "Sound is the same as DMG"
@@ -125,7 +125,7 @@ sound channels or extra waveforms.
 The bundled GBC scaffolds all fit in 32 KB (single bank, no MBC).
 For larger projects use an MBC (memory bank controller). MBC1 / MBC3
 work in gambatte; set the `$0147` cartridge type byte accordingly.
-patchGbHeader doesn't set this — you write it from your asm/C.
+romPatch({op:'gbHeader'}) doesn't set this — you write it from your asm/C.
 
 ## "Frame heartbeat feels janky / slow"
 

package/src/platforms/gbc/UPSTREAM_SOURCES.md

@@ -7,7 +7,7 @@ the color-aware scaffolds; everything below is in lockstep with
 the GB tree.
 
 CGB-specific:
-- `patchGbHeader({cgb: true})` sets $0143 = $80 → gambatte boots
+- `romPatch({op:'gbHeader', cgb: true})` sets $0143 = $80 → gambatte boots
   in CGB mode with color palette RAM active
 - VRAM bank 1 (selected via VBK = $FF4F) holds per-tile attribute
   bytes (palette index, H/V flip, BG-OAM priority)
@@ -53,7 +53,7 @@ upstream README. Songs are exported from hUGETracker
 - "OAM DMA wedges sprites" → see `MENTAL_MODEL.md` § R26 footguns +
   `gb_runtime.c` `oam_dma_copy` implementation
 - "BGP write does nothing" → check $0143 (CGB flag) via
-  `patchGbHeader` + Pan Docs § "The Cartridge Header"
+  `romPatch({op:'gbHeader'})` + Pan Docs § "The Cartridge Header"
 - "How does hUGEDriver process a song row?" → `hUGEDriver.c`
   `hUGE_dosound` body — fully readable
 - "Why is gambatte refusing my ROM?" → check the header, then

package/src/platforms/gbc/lib/c/README.md

@@ -23,12 +23,12 @@ run rgbfix on the linked GB/GBC ROM — valid Nintendo logo at $0104,
 header checksum at $014D, global checksum at $014E, cartridge-type /
 RAM-size bytes, and the CGB flag at $0143 ($80/$C0 for `.gbc`, $00 for
 `.gb`). A freshly built ROM boots on hardware and strict cores with **no
-extra step** — you do not call `patchGbHeader` after a normal build.
+extra step** — you do not call `romPatch({op:'gbHeader'})` after a normal build.
 
 Reach for header tooling only when working with a ROM the build pipeline
 didn't produce, or to override a field:
 
-- `patchGbHeader({path: "out.gb"})` — MCP tool.
+- `romPatch({op:'gbHeader', path: "out.gb"})` — romdev tool.
   Fixes up / overrides the header of an existing ROM on disk (title, cart
   type, ROM/RAM size, CGB flag, etc.).
 - `node patch-header.js out.gb` — standalone Node script, copied into

package/src/platforms/gbc/lib/c/SDCC_GOTCHAS.md

@@ -110,7 +110,7 @@ If you need to write a custom VRAM block-copy:
 
 This is independent of the R26 OAM-alignment fix (`shadow_oam __at
 (0xC100)`) and the header CGB-flag fix (now applied automatically by
-`build({output:'rom'})` / `build({output:'run'})`, not a manual `patchGbHeader` step). All
+`build({output:'rom'})` / `build({output:'run'})`, not a manual `romPatch({op:'gbHeader'})` step). All
 three are silent-failure bugs that look like "did my changes even
 land?" and need different fixes.
 

package/src/platforms/gg/MENTAL_MODEL.md

@@ -73,19 +73,20 @@ check the live OAM Y bytes for $D0 in a slot before them. That's
 still the diagnosis; the runtime just doesn't create the problem
 on its own anymore.
 
-### R6 sprite-tile-base default: $0000, NOT $2000
-
-`gg_vdp_init()` sets R6 = 0xFB. R6 bit 2 is the SA13 select for
-sprite tile data — and bit 2 is **CLEAR** in 0xFB. That means
-sprite tiles read from `$0000-$1FFF`, **sharing the bank with BG
-tiles**. Many references (including the older comments we just
-fixed in `vdp_init.c` and `load_tiles.c`) say "R6=0xFB → sprite
-tiles at $2000" — that's wrong.
-
-If you want sprite tiles in their own bank at $2000, set
-`vdp_write_reg(6, 0xFF)` AND upload tiles to VRAM $2000. Otherwise
-upload sprite tiles to $0000 alongside BG tiles (just make sure
-they don't collide).
+### R6 sprite-tile-base: default is $2000 (0xFF)
+
+`gg_vdp_init()` sets R6 = 0xFF. R6 bit 2 is the SA13 select for
+sprite tile data — bit 2 is **SET** in 0xFF, so sprite tiles read
+from `$2000-$3FFF`, in their **own bank** separate from BG tiles at
+$0000. This is the baseline because every bundled scaffold uploads
+its sprite tiles to `$2000` (`gg_load_tiles(0x2000, …)`) — the
+default and the scaffolds match, so sprites Just Show Up.
+
+Watch the bit: 0xFB has SA13 **CLEAR** = sprite tiles at $0000
+(sharing the BG bank). If you ever set R6=0xFB you MUST also upload
+your sprite tiles to $0000, or the VDP reads the empty/BG bank and
+every sprite is invisible — the classic GG/SMS "my sprites don't
+show up" trap.
 
 The `sprites({op:'inspect'})` tool's `spriteTileDataBase` field reports the
 address the VDP is actually reading from — trust that over any

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

@@ -3,15 +3,17 @@
  * 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
+ *   at $2000 (R6=0xFF → SA13 set → tiles read from $2000-$3FFF). 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
- * sprites({op:'inspect'}) tool's spriteTileDataBase field will show you the
- * real address the VDP is reading from.
+ * Sprite-tile base: R6 bit 2 (SA13) selects $0000 (clear) vs $2000 (set).
+ * We default to R6=0xFF ($2000) because EVERY bundled scaffold uploads its
+ * sprite tiles to $2000 (gg_load_tiles(0x2000, ...)) — so the baseline must
+ * match what consumers do, or sprites read from the empty/BG bank and render
+ * invisible. (Many SMS/GG references say "R6=0xFB → $2000", which is backwards:
+ * 0xFB has SA13 CLEAR = $0000.) If you instead keep sprite tiles in the BG
+ * bank at $0000, set R6=0xFB. sprites({op:'inspect'}) → spriteTileDataBase
+ * shows the address the VDP is actually reading from.
  *
  * After loading assets, enable display by re-writing R1 with bit 6 set:
  *   gg_vdp_display_on();
@@ -33,7 +35,7 @@ void gg_vdp_init(void) {
     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) */
+    0xFF,  /* R6:  sprite tile data at $2000 (SA13 set; scaffolds upload here) */
     0x00,  /* R7:  border = sprite palette entry 0 */
     0x00,  /* R8:  BG X scroll */
     0x00,  /* R9:  BG Y scroll */

package/src/platforms/msx/MENTAL_MODEL.md

@@ -106,7 +106,7 @@ exactly this.
 - `palette({source:'live'})` — V9938 9-bit GRB (or TMS9918 fixed) 16 entries.
 - `sprites({op:'inspect'})` — VRAM sprite-attribute table, up to 32 sprites.
 - `symbols({op:'map', map})` — pass the sdld `.map` (the `symbols` field from
-  buildSourceWithDebug) to see where SDCC placed your variables/code, grouped by
+  build({output:'romWithDebug'})) to see where SDCC placed your variables/code, grouped by
   region (bios / cart_rom / work_ram).
 - `audioDebug({op:'inspect', chip: "ay8910"})` — the AY-3-8910 PSG: 3 square-wave
   channels (tone period→Hz, amplitude, tone/noise enable) + a shared noise

package/src/platforms/nes/TROUBLESHOOTING.md

@@ -140,7 +140,7 @@ Overflow it and there's no error — your globals quietly collide with
 the stack or shadow OAM → corrupted state, sprites that flicker to
 garbage, random crashes.
 
-**Check the `ramUsage` field in the buildSource/runSource response** —
+**Check the `ramUsage` field in the build response** —
 it lists your BSS / DATA / ZEROPAGE segment sizes from the linker map.
 If BSS+DATA is approaching the config's RAM region, shrink your state:
 prefer `uint8_t` over `int`, bit-pack flags, use small fixed arrays,

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

@@ -56,6 +56,7 @@ volatile uint8_t nmi_counter = 0;
  * (so OAM segment placement at $0200 is linker-enforced). oam_index
  * tracks the next free slot for oam_spr(). */
 static uint8_t oam_index = 0;
+static void oam_hide_unused(void);  /* fwd decl — used by ppu_wait_nmi (NES-1) */
 
 /* ── VRAM write queue ─────────────────────────────────────────────
  * Each entry is { hi, lo, byte }. NMI walks the queue, writes
@@ -130,7 +131,12 @@ void ppu_wait_vblank(void) {
 }
 
 void ppu_wait_nmi(void) {
-  uint8_t target = (uint8_t)(nmi_counter + 1);
+  uint8_t target;
+  /* Hide last frame's now-unused sprite slots BEFORE waiting, so the buffer
+   * the NMI's OAM-DMA copies is fully staged (live slots written by oam_spr,
+   * stale slots parked off-screen) — never a half-cleared buffer (NES-1). */
+  oam_hide_unused();
+  target = (uint8_t)(nmi_counter + 1);
   while (nmi_counter != target) { /* spin */ }
 }
 
@@ -159,15 +165,31 @@ void palette_load(const uint8_t *pal32) {
 
 /* ── OAM ──────────────────────────────────────────────────────── */
 
+/* High-water mark: the largest oam_index reached last frame. Lets us blank
+ * ONLY the slots a frame stopped using, instead of the whole 256-byte buffer
+ * every frame. */
+static uint8_t oam_high = 0;
+
 void oam_clear(void) {
+  /* NES-1 FIX: do NOT blank the whole shadow buffer here. The old full clear
+   * wrote slot 0's Y=$FF FIRST and took ~hundreds of cycles; if the NMI's
+   * OAM-DMA fired mid-clear it copied a HALF-CLEARED buffer → the live sprite
+   * vanished every other frame (the classic "sprite flickers to black"
+   * sprite-light scaffold bug). Instead we just reset the staging index here;
+   * ppu_wait_nmi() hides the slots this frame stopped using, so the DMA only
+   * ever sees a fully-staged buffer. */
+  oam_index = 0;
+}
+
+/* Hide slots [oam_index .. oam_high] (the ones used last frame but not this
+ * frame) by parking their Y off-screen. Called from ppu_wait_nmi AFTER the
+ * game has staged its live sprites, so live slots are never blanked. */
+static void oam_hide_unused(void) {
   uint16_t i;
-  for (i = 0; i < 256; i += 4) {
+  for (i = oam_index; i < (uint16_t)oam_high + 4 && i < 256; i += 4) {
     shadow_oam[i] = 0xFF;             /* Y off-screen */
-    shadow_oam[i + 1] = 0;            /* tile */
-    shadow_oam[i + 2] = 0;            /* attr */
-    shadow_oam[i + 3] = 0;            /* X */
   }
-  oam_index = 0;
+  oam_high = oam_index;
 }
 
 void oam_spr(uint8_t x, uint8_t y, uint8_t tile, uint8_t attr) {

package/src/platforms/pce/MENTAL_MODEL.md

@@ -90,7 +90,7 @@ screen. Keep at least one (2+ byte) global. See TROUBLESHOOTING.md.
 - `background({view:'renderState'})` — VDC R5 screen-enable, BG scroll, SATB source.
 - `palette({source:'live'})` — VCE 512-entry 9-bit GRB (area:'bg'|'sprite').
 - `sprites({op:'inspect'})` — SATB 64 sprites (x/y/tile/palette/size/flip).
-- `symbols({op:'map'})` — where cc65 placed your variables (after buildSourceWithDebug).
+- `symbols({op:'map'})` — where cc65 placed your variables (after build({output:'romWithDebug'})).
 - `audioDebug({op:'inspect', chip: "pce"})` — the HuC6280 PSG: 6 wavetable channels
   (per-channel freq/volume/wave; channels 4-5 can also do noise) + main amplitude
   + LFO.

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

@@ -96,6 +96,7 @@ void vdc_set_reg(u8 reg, u16 val);              /* select reg, write 16-bit valu
 void vram_set_write_addr(u16 addr);             /* point MAWR + arm VWR streaming */
 void vram_write(u16 addr, const u16 *data, u16 n); /* upload n words to VRAM[addr] */
 void vce_set_color(u16 idx, u16 grb);           /* set VCE palette entry (0..511) */
+void vdc_init(void);      /* program VDC display timing (256x224 NTSC); auto-run by *_enable */
 void bg_enable(void);     /* VDC R5: background on + VBlank IRQ (so waitvsync works) */
 void spr_enable(void);    /* VDC R5: sprites on    + VBlank IRQ                      */
 void disp_enable(void);   /* VDC R5: BG + SPR + VBlank IRQ on at once                */

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

@@ -70,17 +70,43 @@ void vblank_irq_enable(void) {
     vdc_set_reg(VDC_CR, _pce_cr);
 }
 
+/* Program the VDC display-timing registers for a standard NTSC 256x224 (H32)
+ * screen. WITHOUT this the geargrafx core falls back to power-on register
+ * defaults that composite the 32-row BAT into the display DOUBLED (the scene
+ * drawn twice, top + bottom halves, with a black right margin) — the PCE-1
+ * "doubled picture" bug. Values match cc65's pce.lib / standard PCE homebrew:
+ *   MWR  R9  = 32x32 virtual screen, 256px-wide BAT
+ *   HSR  R10 / HDR R11 = 256px (32 char) horizontal display
+ *   VPR  R12 / VDW R13 / VCR R14 = 224-line vertical window
+ * Called automatically the first time the display is enabled (idempotent). */
+static u8 _pce_vdc_inited = 0;
+void vdc_init(void) {
+    if (_pce_vdc_inited) return;
+    _pce_vdc_inited = 1;
+    vdc_set_reg(VDC_MWR, 0x0010);  /* 32x32 virtual map, 256px BAT          */
+    vdc_set_reg(VDC_BXR, 0x0000);  /* BG X scroll = 0                       */
+    vdc_set_reg(VDC_BYR, 0x0000);  /* BG Y scroll = 0                       */
+    vdc_set_reg(VDC_HSR, 0x0202);  /* horizontal sync width/start           */
+    vdc_set_reg(VDC_HDR, 0x031F);  /* horizontal display = 32 chars (256px) */
+    vdc_set_reg(VDC_VPR, 0x0F02);  /* vertical sync                         */
+    vdc_set_reg(VDC_VDW, 0x00DF);  /* vertical display = 224 lines           */
+    vdc_set_reg(VDC_VCR, 0x00EE);  /* vertical display end                  */
+}
+
 void bg_enable(void) {
+    vdc_init();
     _pce_cr |= (VDC_CR_BG_ON | VDC_CR_VBLANK_IRQ);
     vdc_set_reg(VDC_CR, _pce_cr);
 }
 
 void spr_enable(void) {
+    vdc_init();
     _pce_cr |= (VDC_CR_SPR_ON | VDC_CR_VBLANK_IRQ);
     vdc_set_reg(VDC_CR, _pce_cr);
 }
 
 void disp_enable(void) {
+    vdc_init();
     _pce_cr |= (VDC_CR_BG_ON | VDC_CR_SPR_ON | VDC_CR_VBLANK_IRQ);
     vdc_set_reg(VDC_CR, _pce_cr);
 }

package/src/platforms/sms/MENTAL_MODEL.md

@@ -78,7 +78,7 @@ R1 = 0x80   display OFF, vblank IRQ off, 192-line
 R2 = 0xFF   name table at $3800
 R4 = 0xFF   BG tile data at $0000
 R5 = 0xFF   sprite attr table at $3F00
-R6 = 0xFB   sprite tile data at $0000 (NOT $2000 — see footgun below)
+R6 = 0xFF   sprite tile data at $2000 (own bank; scaffolds upload here)
 R7 = 0x00   border colour
 ```
 
@@ -142,19 +142,19 @@ buffer in WRAM and uploads it to the SAT each vblank.
 `sprites({op:'inspect'})` shows the live OAM bytes + reports
 `spriteTileDataBase` — trust it over comments when sprites misbehave.
 
-### R6 sprite-tile-base default: $0000, NOT $2000
+### R6 sprite-tile-base: default is $2000 (0xFF)
 
-`sms_vdp_init()` sets R6 = 0xFB. R6 bit 2 is the SA13 select for
-sprite tile data — and bit 2 is **CLEAR** in 0xFB. That means
-sprite tiles read from `$0000-$1FFF`, **sharing the bank with BG
-tiles**. Many references (including older comments in our own
-`vdp_init.c` and `load_tiles.c`, since fixed) say "R6=0xFB → sprite
-tiles at $2000" — that's wrong.
+`sms_vdp_init()` sets R6 = 0xFF. R6 bit 2 is the SA13 select for
+sprite tile data — bit 2 is **SET** in 0xFF, so sprite tiles read
+from `$2000-$3FFF`, their **own bank** separate from BG tiles at
+$0000. This matches every bundled scaffold, which uploads sprite
+tiles to `$2000` (`sms_load_tiles(0x2000, …)`) — default and
+scaffolds agree, so sprites render.
 
-If you want sprite tiles in their own bank at $2000, set
-`vdp_write_reg(6, 0xFF)` AND upload tiles to VRAM $2000. Otherwise
-upload sprite tiles to $0000 alongside BG tiles (just make sure
-they don't collide).
+Watch the bit: 0xFB has SA13 **CLEAR** = sprite tiles at $0000
+(shared with the BG bank). If you set R6=0xFB you MUST upload your
+sprite tiles to $0000 too, or the VDP reads the empty/BG bank and
+every sprite is invisible.
 
 ## Palette (CRAM)
 

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

@@ -3,15 +3,17 @@
  * 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
+ *   at $2000 (R6=0xFF → SA13 set → tiles read from $2000-$3FFF). Call
  *   once after reset before uploading palette/tiles/map.
  *
- * Footgun: many SMS 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
- * sprites({op:'inspect'}) tool's spriteTileDataBase field will show you the
- * real address the VDP is reading from.
+ * Sprite-tile base: R6 bit 2 (SA13) selects $0000 (clear) vs $2000 (set).
+ * We default to R6=0xFF ($2000) because EVERY bundled scaffold uploads its
+ * sprite tiles to $2000 (sms_load_tiles(0x2000, ...)) — so the baseline must
+ * match what consumers do, or sprites read from the empty/BG bank and render
+ * invisible. (Many SMS references say "R6=0xFB → $2000", which is backwards:
+ * 0xFB has SA13 CLEAR = $0000.) If you instead keep sprite tiles in the BG
+ * bank at $0000, set R6=0xFB. sprites({op:'inspect'}) → spriteTileDataBase
+ * shows the address the VDP is actually reading from.
  *
  * After loading assets, enable display by re-writing R1 with bit 6 set:
  *   sms_vdp_display_on();
@@ -33,7 +35,7 @@ void sms_vdp_init(void) {
     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) */
+    0xFF,  /* R6:  sprite tile data at $2000 (SA13 set; scaffolds upload here) */
     0x00,  /* R7:  border = sprite palette entry 0 */
     0x00,  /* R8:  BG X scroll */
     0x00,  /* R9:  BG Y scroll */

package/src/platforms/sms/lib/vdp_init.s

@@ -40,7 +40,7 @@ _vdp_init_regs:
         .db $FF                  ; R3: color table — M4 ignores
         .db $FF                  ; R4: BG tile data — M4: bit 2 selects $0000 vs $2000
         .db $FF                  ; R5: sprite attr table base ($3F00 = $7E << 7)
-        .db $FB                  ; R6: sprite tile data — bit 2 selects bank ($2000 here)
+        .db $FF                  ; R6: sprite tile data at $2000 (SA13 set; scaffolds upload here)
         .db $00                  ; R7: border color = sprite palette entry 0
         .db $00                  ; R8: BG X scroll
         .db $00                  ; R9: BG Y scroll

package/src/playtest/playtest.js

@@ -148,8 +148,33 @@ async function getSdl() {
   try {
     const ns = await import("@kmamal/sdl");
     _sdlModule = ns.default || ns;
+    // GROUND-TRUTH visibility check (cross-platform, NOT env-var guessing):
+    // SDL picks a video driver at init. With no presentable surface (no desktop
+    // session, no Xvfb, headless box) it falls back to "offscreen"/"dummy" —
+    // createWindow then SUCCEEDS and audio plays, but nothing appears on any
+    // physical screen. That's the silent "agent says the window's up, user sees
+    // nothing (but hears sound)" failure. We catch it HERE by asking SDL which
+    // driver it actually selected — works the same on Linux/macOS/Windows, and
+    // correctly ALLOWS a real offscreen X server (Xvfb reports "x11", not
+    // "offscreen"). Headless rendering (screenshot/runSource) never calls this,
+    // so offscreen stays perfectly fine for everything except opening a window
+    // for a human.
+    const driver = _sdlModule?.info?.drivers?.video?.current;
+    if (driver === "offscreen" || driver === "dummy") {
+      throw tag(new Error(
+        `SDL selected the "${driver}" video driver — there is no presentable display, ` +
+        "so a playtest window would render but never appear on a physical screen " +
+        "(you'd hear audio but see nothing). The server must run where it has a real " +
+        "display: start it from a terminal INSIDE your logged-in desktop session " +
+        "(`npx romdevtools`), then point your agent at that server. (A server spawned " +
+        "by your agent host, over plain SSH, or from a tty/headless box has no display. " +
+        "A virtual display like Xvfb works too — it reports as the real driver, not " +
+        "\"offscreen\".)",
+      ), "no-display");
+    }
     return _sdlModule;
   } catch (e) {
+    if (e?.sdlKind) throw e; // already-tagged (e.g. the offscreen check above)
     const isModuleErr = e?.code === "ERR_MODULE_NOT_FOUND" ||
       /sdl\.node|dist[\\/]/.test(e?.message || "");
     throw tag(new Error(e?.message ?? String(e)),

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

@@ -12,7 +12,7 @@
 #     runtime. There is no CHARS segment.
 #
 # To use this preset:
-#   1. linkerConfig: "chr-ram" on buildSource
+#   1. linkerConfig: "chr-ram" on build({output:'rom'})
 #   2. Supply your own crt0/header source that writes the 16-byte iNES
 #      header with byte 5 = 0. Easiest: paste the snippet
 #      getStarterSnippet({platform:"nes", name:"chr_ram_header", language:"asm"}).

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

@@ -12,7 +12,7 @@
 #     runtime. There is no CHARS segment.
 #
 # To use this preset:
-#   1. linkerConfig: "chr-ram" on buildSource
+#   1. linkerConfig: "chr-ram" on build({output:'rom'})
 #   2. Supply your own crt0/header source that writes the 16-byte iNES
 #      header with byte 5 = 0. Easiest: paste the snippet
 #      getStarterSnippet({platform:"nes", name:"chr_ram_header", language:"asm"}).

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

@@ -91,7 +91,7 @@ _exit:  jsr     donelib
 ;       rti
 ;
 ;   ; then DELETE the `nmi: rti` line below from this crt0 (or load a
-;   ; modified crt0 via your own buildSource sources entry).
+;   ; modified crt0 via your own build({output:'rom'}) sources entry).
 
 .segment "STARTUP"
 

package/src/toolchains/genesis-c/README.md

@@ -23,7 +23,7 @@ once the WASM artifacts ship. Pipeline shape:
 - **WASM port of cc1/as/ld (stage 2)**: pending.
 - **SGDK native build against the cross-toolchain (stage 3)**: pending.
 - **JS driver `buildGenesisC()`**: pending.
-- **buildSource wiring**: pending.
+- **build({output:'rom'}) wiring**: pending.
 
 ## Why a 3-stage build
 

package/src/toolchains/sdcc/preflight-lint.js

@@ -68,13 +68,53 @@ export function lintSdccSource(source, file = "main.c", opts = {}) {
   // CONSERVATIVE: only flag when we can SEE the counter declared u8 and
   // the bound is a constant we can evaluate — never guess.
   {
-    // Collect names declared as 8-bit ints anywhere in the file.
-    const u8re = /\b(?:unsigned\s+char|char|u8|uint8_t|uint8|int8_t|int8|signed\s+char)\s+([A-Za-z_]\w*(?:\s*,\s*[A-Za-z_]\w*)*)\s*;/g;
-    const u8names = new Set();
-    let dm;
-    while ((dm = u8re.exec(source))) {
-      for (const n of dm[1].split(",")) u8names.add(n.trim());
+    // Build a SCOPE-AWARE map of where each name is declared and at what
+    // width. A name like `i` is commonly re-declared in several functions
+    // — some as uint8_t, some as uint16_t. A flat "is this name ever u8"
+    // set wrongly flags the uint16_t loop just because a DIFFERENT
+    // function declared its own `i` as uint8_t (the SMS/GG default
+    // scaffold false-positive). Instead we record EVERY declaration's
+    // line + width, then for each loop consult the nearest declaration of
+    // the counter that appears ABOVE the loop — i.e. the one actually in
+    // scope — and only flag it when that declaration is 8-bit.
+    //
+    // decls: Map<name, Array<{line:number, u8:boolean}>>  (line is 1-based)
+    const decls = new Map();
+    const addDecl = (names, line, u8) => {
+      for (const raw of names.split(",")) {
+        const n = raw.trim();
+        if (!n) continue;
+        if (!decls.has(n)) decls.set(n, []);
+        decls.get(n).push({ line, u8 });
+      }
+    };
+    const u8re   = /\b(?:unsigned\s+char|char|u8|uint8_t|uint8|int8_t|int8|signed\s+char)\s+([A-Za-z_]\w*(?:\s*,\s*[A-Za-z_]\w*)*)\s*;/;
+    // 16-bit-or-wider integer declarations (and float/double, which also
+    // can't overflow at 255). Anything not 8-bit is "wide" for our purpose.
+    const wideRe = /\b(?:unsigned\s+(?:short|int|long)|signed\s+(?:short|int|long)|short|int|long|u16|u32|u64|uint16_t|uint16|int16_t|int16|uint32_t|uint32|int32_t|int32|uint64_t|uint64|int64_t|int64|size_t|ptrdiff_t)\s+([A-Za-z_]\w*(?:\s*,\s*[A-Za-z_]\w*)*)\s*;/;
+    for (let i = 0; i < lines.length; i++) {
+      const code = lines[i].replace(/\/\/.*$/, "").replace(/\/\*.*?\*\//g, "");
+      const m8 = code.match(u8re);
+      if (m8) { addDecl(m8[1], i + 1, true); continue; }
+      const mw = code.match(wideRe);
+      if (mw) addDecl(mw[1], i + 1, false);
     }
+    // Is the counter declared 8-bit in the scope visible at `loopLine`?
+    // Use the NEAREST declaration above the loop. If the nearest visible
+    // declaration is wide (uint16_t etc.), the loop is fine.
+    const counterIsU8AtLine = (counter, loopLine) => {
+      const ds = decls.get(counter);
+      if (!ds) return false;
+      let best = null;
+      for (const d of ds) {
+        if (d.line <= loopLine && (best === null || d.line > best.line)) best = d;
+      }
+      // No declaration above the loop (e.g. param/global declared after, or
+      // out-of-order) — fall back to "flag only if EVERY decl is u8" so we
+      // never wolf-cry on a name that is also declared wide somewhere.
+      if (best === null) return ds.every((d) => d.u8);
+      return best.u8;
+    };
     const evalConst = (expr) => {
       // Only literals and pure `A * B [* C]` products of decimal/hex ints.
       const t = expr.trim();
@@ -91,7 +131,7 @@ export function lintSdccSource(source, file = "main.c", opts = {}) {
       const m = code.match(/\bfor\s*\([^;]*;\s*([A-Za-z_]\w*)\s*<\s*([^;]+?)\s*;/);
       if (!m) continue;
       const [, counter, boundExpr] = m;
-      if (!u8names.has(counter)) continue;
+      if (!counterIsU8AtLine(counter, i + 1)) continue;
       const bound = evalConst(boundExpr);
       if (bound !== null && bound > 255) {
         issues.push({

package/src/toolchains/snes-c/snes-c.js

@@ -148,13 +148,9 @@ function normalizeSnesSources(args) {
     if (cFiles.length === 0) {
       throw new Error("buildSnesC: `sources` must include at least one .c file.");
     }
-    if (cFiles.length > 1) {
-      throw new Error(
-        `buildSnesC: multiple .c files in sources (${cFiles.join(", ")}). ` +
-        `Today only one .c file is supported per build — combine via #include or wait for ` +
-        `multi-TU support. .asm/.s siblings work fine.`,
-      );
-    }
+    // Multiple .c files ARE supported: buildWithPvSnesLib compiles each to its
+    // own .obj (tcc→wla) and links them all (Stage 1 + Stage 3). The genre
+    // scaffolds ship main.c + snes_sfx.c and rely on this.
     return args.sources;
   }
   if (typeof args.source === "string") {