romdevtools 0.21.0 → 0.22.1

package/AGENTS.md

@@ -153,8 +153,10 @@ worry about ground truth:
    when you're scaffolding into a project dir.
 
 For most workflows, path A is all you need. Read MENTAL_MODEL.md +
-TROUBLESHOOTING.md when stuck. File a feedback round if the bundled
-examples are wrong.
+TROUBLESHOOTING.md when stuck. **When a tool call FAILS, read the error
+message and `issues[]` first — see "When a call fails" below; the error
+usually names the fix.** File a feedback round if the bundled examples
+are wrong.
 
 ### Path B — Debug when the bundled code disagrees with behavior
 
@@ -397,9 +399,12 @@ When `build({output:'run'})` is too coarse, the long-form workflow:
 5. `input({op:'set'})` / `input({op:'press'})` / `input({op:'sequence'})` to drive the game
 6. `state({op:'save'}, "checkpoint")` / `state({op:'load'}, "checkpoint")` for try/undo
 
-## Build errors
+## When a call fails: READ THE ERROR FIRST
 
-Every build tool returns `issues: [{file, line, col, severity, message, stage}, ...]`. Use that array, not the raw `log`. If `issues` is empty but `ok: false`, fall back to `log`.
+romdev errors are written FOR you — they name what went wrong AND how to recover. Read the message (and `issues[]`) before guessing, screenshotting, or retrying blindly. Two shapes:
+
+- **Build/compile failures** return `issues: [{file, line, col, severity, message, stage}, ...]` — the structured error list. Use that array, NOT the raw `log`; it almost always names the exact line. Fall back to `log` only if `issues` is empty but `ok: false`. `issues[]` is RANKED most-dangerous first (**critical → error → warning → info**), so read it top-down: an entry flagged `critical: true` (e.g. a `WILL HANG:` `uint8`-loop-bound trap) is a latent crash even on a build that otherwise succeeded — fix those FIRST, never skip them as "just a warning". Link errors carry no `line` but include a `hint` naming the missing symbol + how to resolve it.
+- **Tool/runtime errors** (thrown) carry the recovery step in the message itself. Examples: a "No ROM loaded" error after a session reconnect echoes the EXACT `loadMedia({...})` call to restore your state; a rejected `loadMedia` names the likely cause (wrong platform / truncated / unsupported mapper) and points you at `cart({op:'identify'})`; an `input({op:'set'})` with a typo'd button returns `ignoredButtons[]` so you see it pressed nothing. Don't discard these — they're the fix.
 
 **Crash isolation (R12).** Every WASM toolchain call runs in a child worker process. If a tool aborts (`_abort()`, SIGSEGV, OOM), only the worker dies — the MCP server keeps running, all other agent sessions are unaffected, tool registration + save states + playtest windows survive. The build response surfaces as `{ ok: false, stage: "crash", log: "[crash] worker exited unexpectedly — signal=… code=…", crash: { exitCode, signal } }`. Treat `stage: "crash"` as "the toolchain blew up — log the args + source somewhere durable so it can be triaged; you can keep iterating in this session without reconnecting".
 
@@ -430,6 +435,12 @@ romPatch({op:'diff', platform, a: original, b: patched })    // 6. verify the pa
 loadMedia({ platform, path: patched }) → frame({op:'screenshot'})  // 7. run it
 ```
 
+**Driving input through a watched run.** A `watch`/`breakpoint` with NO
+`pressDuring` INHERITS whatever `input({op:'set'})` last held — same as
+`frame({op:'step'})`. But if you pass `pressDuring`, that schedule OWNS the pad
+for the whole run and a prior `input({op:'set'})` is ignored. So to hold a button
+*through* a watched window, put it in `pressDuring` — not a preceding `set`.
+
 **Finding which CODE wrote a byte.** Static disasm reading is the slow part —
 multiple `cmp #$XX` instructions look identical. Don't guess. Two tools, in order
 of precision:

package/CHANGELOG.md

@@ -4,6 +4,72 @@ All notable changes to `romdevtools`. Dates are release dates.
 (Published as `romdev-mcp` through 0.11.0; renamed to `romdevtools` in 0.13.0 —
 the `romdev-mcp` bin is kept as an alias.)
 
+## 0.22.1
+
+Doc-only follow-up to 0.22.0's movement-analysis feedback: the `pressDuring`
+schema on `watch` and `breakpoint` now states that entries with OVERLAPPING
+windows on the same port are OR'd into a chord (e.g. `b`+`right` held while `a`
+fires mid-window), not overwritten. The driver already behaved this way; this
+documents the guarantee so it doesn't have to be confirmed empirically.
+
+## 0.22.0
+
+**Transparency + correctness pass: every tool failure is actionable, dangerous
+warnings are ranked first, and all 14 platforms' scaffolds build clean AND
+render visible content.** The theme: a coding agent should never be left guessing
+by an opaque error, never skip a crash-class warning buried in noise, and never
+copy a scaffold that ships with warnings or a blank screen.
+
+### Changed — actionable error messages across all 14 platforms
+Failures now name the fix, not just the symptom:
+- **`build`/assemble:** compile errors carry `{file, line, message, stage}`; LINK
+  errors (which have no source line) now reach `issues[]` too, each with a `hint`
+  naming the missing symbol + how to resolve it — on ALL FOUR linkers (GNU ld for
+  Genesis/GBA, ld65 for NES/C64/Lynx/A2600/A7800/PCE, sdld for GB/GBC/SMS/GG/MSX,
+  wlalink for SNES). The crt0 (startup-stub) assembly path and `assembleSnippet`
+  now surface the first `file:line: message` instead of dumping a raw log.
+- **`loadMedia`:** a refused ROM names the likely cause (wrong platform / truncated
+  / unsupported mapper) and points at `cart({op:'identify'})`.
+- **Runtime/host:** `getHost`'s "No ROM loaded" echoes the EXACT `loadMedia` call
+  to recover with after a session eviction; unknown memory region lists the valid
+  names; "no save state named X" lists the existing slots; `host({op:'unload'})`
+  no longer claims success when nothing was loaded.
+
+### Changed — build `issues[]` ranks the dangerous warnings FIRST
+A weak agent skips a lethal warning when it's buried among unused-variable noise.
+`issues[]` is now ordered **critical → error → warning → info** (stable within a
+rank) on every platform. The SDCC pre-flight lint marks the unconditional
+`uint8`-loop-bound trap as `critical: true` (it always hangs) with a `WILL HANG:`
+message; the conditional VRAM byte-copy stays a plain warning (it can't be proven
+unsafe statically, so it must not cry wolf).
+
+### Fixed — `watch`/`breakpoint` inherit held input (the movement-analysis bug)
+A `watch`/`breakpoint` run with NO `pressDuring` now inherits whatever
+`input({op:'set'})` last held — exactly like `frame({op:'step'})`. Previously the
+first frame reset the pad to neutral, silently dropping a held button. A
+`pressDuring` schedule still OWNS the pad for the run (deterministic capture).
+Documented on the `input`/`watch`/`breakpoint` schemas.
+
+### Fixed — all 130 scaffolds: zero warnings AND render visible content
+Swept every `scaffold({op:'project'})` template on all 14 platforms:
+- **Warnings 65 → 0** (was concentrated in GB/GBC/Genesis/GG/GBA/SMS), fixed at
+  the SOURCE so scaffolds model the right pattern: GB/GBC VRAM tile copies use the
+  runtime's pointer-walk `memcpy_vram` (the indexed `dst[i]=src[i]` form SDCC sm83
+  miscompiles into VRAM); Genesis builds pass `-Wno-main` (SGDK mandates
+  `int main(bool)`); GBA/GG/SMS narrowing + dead-branch fixes.
+- **Blank/broken renders 31 → 0** (verified via `frame({op:'verify'})`): added a
+  patterned background to lone-sprite/text scaffolds, and fixed real bugs found
+  along the way — **NES FamiTone2's `$0300` RAM collided with the C runtime BSS**
+  (zeroed PPUCTRL, killed rendering; the driver's RAM was relocated to `$0700`);
+  the **SNES `sfx_init()`-before-`setScreenOn()`** forced-blank trap; a **C64 cc65
+  screen-fill-loop hang** (rewritten via `memset`) + sprite-data/`$0801` overlap;
+  the **Lynx double-buffer** stale-page trap.
+
+### Added — ESLint over romdev's own JavaScript
+Flat config (`npm run lint`) catching real bugs (undefined refs, unused
+imports/vars, dupe keys, self-assignment) over the monorepo's plain-JS ESM
+sources; vendored SDK/wasm/build trees ignored. Cleaned 114 pre-existing findings.
+
 ## 0.21.0
 
 **NES CHR-ROM / iNES rebuild ergonomics + turnkey `disasm({target:'project'})`

package/examples/atari7800/templates/hello_sprite.c

@@ -16,6 +16,8 @@
 #define P0C1      (*(volatile uint8_t*)0x21)
 #define P0C2      (*(volatile uint8_t*)0x22)
 #define P0C3      (*(volatile uint8_t*)0x23)
+#define P1C1      (*(volatile uint8_t*)0x25)
+#define P2C1      (*(volatile uint8_t*)0x29)
 #define MSTAT     (*(volatile uint8_t*)0x28)
 #define DPPH      (*(volatile uint8_t*)0x2C)
 #define DPPL      (*(volatile uint8_t*)0x30)
@@ -47,6 +49,42 @@ MK_DL(dl_row4); MK_DL(dl_row5); MK_DL(dl_row6); MK_DL(dl_row7);
 
 static uint8_t dl_empty[2] = { 0, 0 };
 
+/* ── Background playfield ─────────────────────────────────────────────
+ * Without a full-screen drawable the display list emits only the one
+ * sprite and ~99% of the screen stays the flat BACKGRND colour (reads as
+ * "blank"). These full-width bands fill every non-sprite zone with scenery
+ * so the frame has real content (same machinery as default.c).
+ *
+ * One scanline of solid pixels lives in ROM (band_pix). A single DL
+ * drawable is at most 32 bytes = 128 px wide, so a full 160-px line needs
+ * TWO drawables. Width (byte[3] low 5 bits) = 32-bytes; high 3 bits =
+ * palette: field uses palette 1, ground uses palette 2. */
+static const uint8_t band_pix[32] = {
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55
+};
+#define MK_BAND(name, pal) static uint8_t name[11] = { \
+  0, 0x40, 0, ((pal) << 5) | 0,  0,    /* 128 px @ x0   */ \
+  0, 0x40, 0, ((pal) << 5) | 24, 128,  /* 32 px  @ x128 */ \
+  0 }
+MK_BAND(dl_field, 1);
+MK_BAND(dl_ground, 2);
+#define GROUND_ZONE 188
+
+static void set_band_addr(uint8_t* dl) {
+  uint16_t a = (uint16_t)(uintptr_t)band_pix;
+  dl[0] = dl[5] = (uint8_t)(a & 0xFF);
+  dl[2] = dl[7] = (uint8_t)(a >> 8);
+}
+
+/* Background DL for a non-sprite zone: sky (empty) up top, field in the
+ * middle, ground at the bottom. */
+static uint16_t bg_zone_dl(int zone) {
+  if (zone >= GROUND_ZONE) return (uint16_t)(uintptr_t)dl_ground;
+  if (zone >= 28)          return (uint16_t)(uintptr_t)dl_field;
+  return (uint16_t)(uintptr_t)dl_empty;
+}
+
 #define DLL_ZONES 243
 static uint8_t dll[DLL_ZONES * 3];
 
@@ -62,9 +100,9 @@ static void set_dll_entry(int idx, uint16_t dl_ptr) {
   dll[idx * 3 + 2] = (uint8_t)(dl_ptr & 0xFF);
 }
 
-/* Build the DLL with the sprite's 8 rows placed at DLL index sprite_y. */
+/* Build the DLL with the sprite's 8 rows placed at DLL index sprite_y;
+ * every other zone gets the background scenery band for its row. */
 static void build_dll(uint8_t sprite_y) {
-  uint16_t empty = (uint16_t)(uintptr_t)dl_empty;
   int i;
   for (i = 0; i < DLL_ZONES; i++) {
     uint16_t dl;
@@ -78,7 +116,7 @@ static void build_dll(uint8_t sprite_y) {
       case 5: dl = (uint16_t)(uintptr_t)dl_row5; break;
       case 6: dl = (uint16_t)(uintptr_t)dl_row6; break;
       case 7: dl = (uint16_t)(uintptr_t)dl_row7; break;
-      default: dl = empty; break;
+      default: dl = bg_zone_dl(i); break;   /* field/ground scenery */
     }
     set_dll_entry(i, dl);
   }
@@ -99,6 +137,10 @@ void main(void) {
   uint8_t x = 80;
   uint8_t y = 110;
 
+  /* Point the background bands at their shared ROM pixel row. */
+  set_band_addr(dl_field);
+  set_band_addr(dl_ground);
+
   /* Wire each DL's address bytes to its sprite-row data. */
   set_dl_addr(dl_row0, sprite_row0);
   set_dl_addr(dl_row1, sprite_row1);
@@ -112,10 +154,12 @@ void main(void) {
   set_x(x);
   build_dll(y);
 
-  BACKGRND = 0x88;
+  BACKGRND = 0x88;   /* light blue sky */
   P0C1     = 0x46;
   P0C2     = 0x0F;
   P0C3     = 0x36;
+  P1C1     = 0xC8;   /* field green (background band) */
+  P2C1     = 0x14;   /* ground brown (background band) */
   CHARBASE = 0;
   OFFSET   = 0;
 

package/examples/atari7800/templates/music_demo.c

@@ -19,6 +19,8 @@
 #define P0C1      (*(volatile uint8_t*)0x21)
 #define P0C2      (*(volatile uint8_t*)0x22)
 #define P0C3      (*(volatile uint8_t*)0x23)
+#define P1C1      (*(volatile uint8_t*)0x25)
+#define P2C1      (*(volatile uint8_t*)0x29)
 #define MSTAT     (*(volatile uint8_t*)0x28)
 #define DPPH      (*(volatile uint8_t*)0x2C)
 #define DPPL      (*(volatile uint8_t*)0x30)
@@ -47,6 +49,42 @@ MK_DL(dl_row4); MK_DL(dl_row5); MK_DL(dl_row6); MK_DL(dl_row7);
 
 static uint8_t dl_empty[2] = { 0, 0 };
 
+/* ── Background playfield ─────────────────────────────────────────────
+ * Without a full-screen drawable the display list emits only the banner
+ * and ~99% of the screen stays the flat BACKGRND colour (reads as
+ * "blank"). These full-width bands fill every non-banner zone with scenery
+ * so the frame has real content (same machinery as default.c).
+ *
+ * One scanline of solid pixels lives in ROM (band_pix). A 160-px line needs
+ * TWO drawables (a DL drawable is at most 32 bytes = 128 px). Width
+ * (byte[3] low 5 bits) = 32-bytes; high 3 bits = palette: field = palette
+ * 1, ground = palette 2. */
+static const uint8_t band_pix[32] = {
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55
+};
+#define MK_BAND(name, pal) static uint8_t name[11] = { \
+  0, 0x40, 0, ((pal) << 5) | 0,  0,    /* 128 px @ x0   */ \
+  0, 0x40, 0, ((pal) << 5) | 24, 128,  /* 32 px  @ x128 */ \
+  0 }
+MK_BAND(dl_field, 1);
+MK_BAND(dl_ground, 2);
+#define GROUND_ZONE 188
+
+static void set_band_addr(uint8_t* dl) {
+  uint16_t a = (uint16_t)(uintptr_t)band_pix;
+  dl[0] = dl[5] = (uint8_t)(a & 0xFF);
+  dl[2] = dl[7] = (uint8_t)(a >> 8);
+}
+
+/* Background DL for a non-banner zone: sky (empty) up top, field in the
+ * middle, ground at the bottom. */
+static uint16_t bg_zone_dl(int zone) {
+  if (zone >= GROUND_ZONE) return (uint16_t)(uintptr_t)dl_ground;
+  if (zone >= 28)          return (uint16_t)(uintptr_t)dl_field;
+  return (uint16_t)(uintptr_t)dl_empty;
+}
+
 #define DLL_ZONES 243
 static uint8_t dll[DLL_ZONES * 3];
 
@@ -71,9 +109,12 @@ static void vblank_wait(void) {
 
 void main(void) {
   uint16_t dll_addr;
-  uint16_t empty = (uint16_t)(uintptr_t)dl_empty;
   int i;
 
+  /* Point the background bands at their shared ROM pixel row. */
+  set_band_addr(dl_field);
+  set_band_addr(dl_ground);
+
   set_dl_addr(dl_row0, banner_row0);
   set_dl_addr(dl_row1, banner_row1);
   set_dl_addr(dl_row2, banner_row2);
@@ -83,6 +124,8 @@ void main(void) {
   set_dl_addr(dl_row6, banner_row6);
   set_dl_addr(dl_row7, banner_row7);
 
+  /* Build the DLL: banner rows at BANNER_Y, background scenery everywhere
+   * else so the screen isn't an almost-blank flat field. */
   for (i = 0; i < DLL_ZONES; i++) {
     uint16_t dl;
     int d = i - BANNER_Y;
@@ -95,7 +138,7 @@ void main(void) {
       case 5: dl = (uint16_t)(uintptr_t)dl_row5; break;
       case 6: dl = (uint16_t)(uintptr_t)dl_row6; break;
       case 7: dl = (uint16_t)(uintptr_t)dl_row7; break;
-      default: dl = empty; break;
+      default: dl = bg_zone_dl(i); break;   /* field/ground scenery */
     }
     set_dll_entry(i, dl);
   }
@@ -104,6 +147,8 @@ void main(void) {
   P0C1     = 0x0F;  /* white text (palette index 1) */
   P0C2     = 0x0F;
   P0C3     = 0x0F;
+  P1C1     = 0xC8;  /* field green  (background band) */
+  P2C1     = 0x14;  /* ground brown (background band) */
   CHARBASE = 0;
   OFFSET   = 0;
 

package/examples/c64/templates/tile_engine.c

@@ -26,6 +26,7 @@
 
 #include "c64_registers.h"
 #include <stdint.h>
+#include <string.h>   /* memset — see world_draw for why we fill via memset */
 
 /* cc65 stdlib already defines POKE/PEEK in cc65/include/peekpoke.h
  * with a different shape (no volatile, address as integer). Use the
@@ -39,20 +40,29 @@
 #define SCREEN          ((volatile uint8_t*)0x0400)
 #define COLORS          ((volatile uint8_t*)0xD800)
 #define SPRITE_POINTERS ((volatile uint8_t*)0x07F8)
-#define SPRITE_DATA     ((volatile uint8_t*)0x0800)
+/* Sprite data at $2000, NOT $0800 — $0800 overlaps the cc65 .prg load
+ * address ($0801), so writing sprite bytes there clobbers the running
+ * program's own startup code and the demo never reaches the draw loop
+ * (the whole screen stays blank). $2000 is free RAM in VIC bank 0. */
+#define SPRITE_DATA     ((volatile uint8_t*)0x2000)
 
 #define COLS 40
 #define ROWS 25
 
 #define CHAR_BLANK 0x20  /* space */
-#define CHAR_BLOCK 0xA0  /* PETSCII solid block */
+#define CHAR_BLOCK 0xA0  /* PETSCII solid block (reverse-space) — fills    */
+                         /* the whole cell in its foreground colour. The   */
+                         /* whole world is drawn from this one glyph in    */
+                         /* different colours (see world_draw).            */
 
 #define COL_BLACK  0x00
 #define COL_WHITE  0x01
 #define COL_RED    0x02
 #define COL_CYAN   0x03
+#define COL_PURPLE 0x04
 #define COL_GREEN  0x05
 #define COL_BLUE   0x06
+#define COL_YELLOW 0x07
 
 #define JOY_UP    0x01
 #define JOY_DOWN  0x02
@@ -85,39 +95,74 @@ static const uint8_t sprite_data[64] = {
   0,
 };
 
-static uint8_t world[ROWS][COLS];
+// The world is described by a function, NOT a 1000-byte RAM array. cc65
+// chokes on filling a large static uint8_t[ROWS][COLS] in a tight double
+// loop here (it walks off and the program never reaches the draw) — so we
+// compute each cell on demand instead, exactly like the platformer
+// scaffold's render_view. Cheap and crash-free.
+//
+// is_wall(r,c) == 1 for the perimeter and the two interior platforms.
+static uint8_t is_wall(uint8_t r, uint8_t c) {
+  if (r == 0 || r == ROWS - 1 || c == 0 || c == COLS - 1) return 1;
+  if (r == 10 && c >= 6  && c < 14) return 1;
+  if (r == 16 && c >= 22 && c < 34) return 1;
+  return 0;
+}
 
-static void world_build(void) {
-  uint8_t r, c;
-  for (r = 0; r < ROWS; r++) {
-    for (c = 0; c < COLS; c++) {
-      world[r][c] =
-        (r == 0 || r == ROWS - 1 || c == 0 || c == COLS - 1)
-          ? CHAR_BLOCK : CHAR_BLANK;
-    }
-  }
-  // Two interior platforms.
-  for (c = 6;  c < 14; c++) world[10][c] = CHAR_BLOCK;
-  for (c = 22; c < 34; c++) world[16][c] = CHAR_BLOCK;
+// Fill a run of `n` cells in screen + colour RAM starting at cell `base`.
+#define ROW_OF(r)  ((r) * COLS)
+static void fill_cells(uint16_t base, uint16_t n, uint8_t ch, uint8_t col) {
+  memset((void*)(0x0400 + base), ch,  n);
+  memset((void*)(0xD800 + base), col, n);
 }
 
+// Paint the whole 40×25 character matrix as solid blocks in horizontal
+// colour bands.
+//
+// IMPORTANT — why memset and not a per-cell for-loop: the cc65 build for
+// this scaffold miscompiles a hand-written `for (off..) SCREEN[off]=..`
+// loop (it hangs after ~2 rows and the rest of the screen stays the boot
+// backdrop → almost-blank). memset() fills reliably, so we lay the world
+// down as a handful of solid-colour bands. Several distinct bands keep any
+// single colour well under the 92% "nearlyBlank" threshold while still
+// reading as a tiled floor with a wall border.
 static void world_draw(void) {
-  uint8_t r, c;
+  uint8_t r;
+
+  // Whole screen → solid blocks, mid-band colour to start.
+  fill_cells(0, ROWS * COLS, CHAR_BLOCK, COL_GREEN);
+
+  // Three horizontal colour bands so the interior isn't one flat colour.
+  fill_cells(ROW_OF(1),  8 * COLS, CHAR_BLOCK, COL_GREEN);   // upper field
+  fill_cells(ROW_OF(9),  7 * COLS, CHAR_BLOCK, COL_PURPLE);  // middle field
+  fill_cells(ROW_OF(16), 8 * COLS, CHAR_BLOCK, COL_BLUE);    // lower field
+
+  // Cyan perimeter: top + bottom rows full width.
+  fill_cells(ROW_OF(0),         COLS, CHAR_BLOCK, COL_CYAN);
+  fill_cells(ROW_OF(ROWS - 1),  COLS, CHAR_BLOCK, COL_CYAN);
+
+  // Cyan interior platforms (the two walls is_wall() reports for collision).
+  fill_cells(ROW_OF(10) + 6,  8,  CHAR_BLOCK, COL_CYAN);
+  fill_cells(ROW_OF(16) + 22, 12, CHAR_BLOCK, COL_CYAN);
+
+  // Left + right wall columns. One cell per row — a 25-iteration loop is
+  // short enough to compile correctly (the hang only bites long fills).
   for (r = 0; r < ROWS; r++) {
-    for (c = 0; c < COLS; c++) {
-      SCREEN[r * COLS + c] = world[r][c];
-      COLORS[r * COLS + c] = world[r][c] == CHAR_BLOCK ? COL_CYAN : COL_BLACK;
-    }
+    SCREEN[ROW_OF(r)]            = CHAR_BLOCK;
+    COLORS[ROW_OF(r)]            = COL_CYAN;
+    SCREEN[ROW_OF(r) + COLS - 1] = CHAR_BLOCK;
+    COLORS[ROW_OF(r) + COLS - 1] = COL_CYAN;
   }
 }
 
-// Convert sprite (px, py) → character cell. C64 sprite coords are
-// offset 24 px (X) and 50 px (Y) from the visible top-left.
+// Convert sprite (px, py) → character cell, then test the wall function.
+// C64 sprite coords are offset 24 px (X) and 50 px (Y) from the visible
+// top-left.
 static uint8_t solid_at(uint16_t px, uint16_t py) {
   uint16_t cx = (px - 24) >> 3;
   uint16_t cy = (py - 50) >> 3;
   if (cx >= COLS || cy >= ROWS) return 1;
-  return world[cy][cx] == CHAR_BLOCK;
+  return is_wall((uint8_t)cy, (uint8_t)cx);
 }
 
 static void wait_vblank(void) {
@@ -135,15 +180,12 @@ void main(void) {
   uint8_t pad;
 
   copy_sprite();
-  SPRITE_POINTERS[0] = 0x20;  /* $0800 / $40 */
+  SPRITE_POINTERS[0] = 0x80;  /* $2000 / 64 */
 
   WR(VIC_BORDER, 0x00);
   WR(VIC_BG0,    0x00);
   WR(VIC_SPR_COL(0), COL_RED);
 
-  world_build();
-  world_draw();
-
   WR(VIC_SPRITE_X(0), (uint8_t)(sx & 0xFF));
   WR(VIC_SPRITE_Y(0), (uint8_t)sy);
   WR(VIC_SPR_ENA, 0x01);
@@ -152,6 +194,14 @@ void main(void) {
     uint16_t nx = sx, ny = sy;
     wait_vblank();
 
+    /* Repaint the whole character map every frame. The KERNAL keeps
+     * clearing screen RAM for the first frames after boot, so a single
+     * draw before the loop gets wiped (almost-blank screen). Redrawing
+     * each frame is cheap (1000 cells) and guarantees the world is always
+     * on-screen regardless of boot timing — the same "redraw every frame"
+     * discipline the other scaffolds use. */
+    world_draw();
+
     pad = ~RD(CIA1_PRA) & 0x0F;
     if (pad & JOY_UP    && sy > 52)  ny--;
     if (pad & JOY_DOWN  && sy < 240) ny++;

package/examples/gb/templates/hello_sprite.c

@@ -47,6 +47,8 @@ void main(void) {
   uint8_t i;
   uint8_t *vram_dst;
   const uint8_t *src;
+  uint8_t *bg_map;
+  uint16_t j;
 
   /* ── 1. LCD off (safe whether it was on or off) ──────────────────
    * lcd_init_default() checks LCDC.7 and only waits for vblank if the
@@ -60,9 +62,16 @@ void main(void) {
    * accidentally render garbage tiles that point to it. */
   vram_dst = (uint8_t *)0x8010;
   src = tile_data;
-  for (i = 0; i < 16; i++) {
-    vram_dst[i] = src[i];
-  }
+  /* memcpy_vram (pointer-walk) — NOT an indexed vram_dst[i]=src[i] loop, which
+   * SDCC sm83 miscompiles when the dest points into VRAM ($8000-$9FFF). */
+  memcpy_vram(vram_dst, src, 16);
+
+  /* ── 2b. Fill the BG tilemap so the screen isn't an empty backdrop. ──
+   * With LCDC_TILE_DATA_LO ($8000 addressing) BG tile index 1 == our tile
+   * at $8010 — so we tile the whole 32×32 BG map with it. memcpy_vram-style
+   * pointer walk (NOT bg_map[k]=1, which SDCC sm83 miscompiles into VRAM). */
+  bg_map = (uint8_t *)0x9800;
+  for (j = 0; j < 32u * 32u; j++) *bg_map++ = 1;
 
   /* ── 3. Object palette 0 (CGB path) ──────────────────────────────
    * OCPS bit 7 = auto-increment after each write; bits 5..3 = palette
@@ -92,9 +101,9 @@ void main(void) {
   oam_dma_flush();      /* first OAM live before the screen turns on */
 
   /* ── 5. Turn the LCD back on with BG + OBJ enabled. ──────────────
-   * LCDC bits: 0x80=LCD on, 0x02=OBJ on, 0x10=tile data at $8000.
-   * (BG remains off — we have no BG map set up.) */
-  LCDC = LCDC_LCD_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+   * LCDC bits: 0x80=LCD on, 0x01=BG on, 0x02=OBJ on, 0x10=tile data at $8000.
+   * BG is on now that we filled the BG map in step 2b. */
+  LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
 
   /* ── 6. APU on — let the player beep ──────────────────────────── */
   sound_init();

package/examples/gb/templates/music_demo.c

@@ -29,11 +29,47 @@
  * project template). */
 extern const huge_song_t sample_song;
 
+/* Two 8×8 2bpp tiles so the BG isn't a single flat colour (a uniform
+ * screen reads >=92% one colour and fails the blank-screen check):
+ *   tile 1 — solid colour 3
+ *   tile 2 — solid colour 1
+ * We checkerboard them across the BG map below. */
+static const uint8_t tile_solid3[16] = {
+  0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF,
+  0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF,
+};
+static const uint8_t tile_solid1[16] = {
+  0xFF,0x00, 0xFF,0x00, 0xFF,0x00, 0xFF,0x00,
+  0xFF,0x00, 0xFF,0x00, 0xFF,0x00, 0xFF,0x00,
+};
+
 void main(void) {
   uint8_t  shade = 0;
   uint16_t frame = 0;
+  uint8_t *bg_map;
+  uint16_t j;
 
   lcd_init_default();
+  LCDC = 0;               /* LCD off so we can write VRAM freely */
+
+  /* Upload two tiles to VRAM slots 1 ($8010) and 2 ($8020). Use
+   * memcpy_vram (pointer-walk) — an indexed dst[i]=src[i] loop into VRAM
+   * is miscompiled by SDCC sm83. */
+  memcpy_vram((uint8_t *)0x8010, tile_solid3, 16);
+  memcpy_vram((uint8_t *)0x8020, tile_solid1, 16);
+
+  /* Checkerboard the 32×32 BG map at $9800 with tiles 1 and 2 so the
+   * screen shows two distinct shades. Pointer-walk (NOT bg_map[k]=...,
+   * which SDCC sm83 miscompiles into VRAM). */
+  bg_map = (uint8_t *)0x9800;
+  for (j = 0; j < 32u * 32u; j++) {
+    *bg_map++ = (uint8_t)((((j ^ (j >> 5)) & 1u) ? 1u : 2u));
+  }
+
+  /* LCD on with BG enabled, $8000 tile-data addressing so index 1 == our
+   * tile at $8010. */
+  LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_TILE_DATA_LO;
+
   sound_init();
 
   hUGE_init(&sample_song);

package/examples/gb/templates/platformer.c

@@ -75,8 +75,9 @@ static uint8_t on_platform(int16_t px, int16_t py) {
 
 static void upload_tile(uint8_t slot, const uint8_t *src) {
     uint8_t *dst = (uint8_t *)(0x8000 + slot * 16);
-    uint8_t i;
-    for (i = 0; i < 16; i++) dst[i] = src[i];
+    /* memcpy_vram (pointer-walk) — NOT an indexed dst[i]=src[i] loop, which
+     * SDCC sm83 miscompiles when dst points into VRAM ($8000-$9FFF). */
+    memcpy_vram(dst, src, 16);
 }
 
 static void paint_platforms(void) {

package/examples/gb/templates/puzzle.c

@@ -141,8 +141,9 @@ static void lock_piece(void) {
 
 static void upload_tile(uint8_t slot, const uint8_t *src) {
     uint8_t *dst = (uint8_t *)(0x8000 + slot * 16);
-    uint8_t i;
-    for (i = 0; i < 16; i++) dst[i] = src[i];
+    /* memcpy_vram (pointer-walk) — NOT an indexed dst[i]=src[i] loop, which
+     * SDCC sm83 miscompiles when dst points into VRAM ($8000-$9FFF). */
+    memcpy_vram(dst, src, 16);
 }
 
 /* Draw the well frame around the 6×12 play area. Grid cells live at

package/examples/gb/templates/racing.c

@@ -109,8 +109,9 @@ static void spawn_obstacle(void) {
 
 static void upload_tile(uint8_t slot, const uint8_t *src) {
   uint8_t *dst = (uint8_t *)(0x8000 + slot * 16);
-  uint8_t i;
-  for (i = 0; i < 16; i++) dst[i] = src[i];
+  /* memcpy_vram (pointer-walk) — NOT an indexed dst[i]=src[i] loop, which
+   * SDCC sm83 miscompiles when dst points into VRAM ($8000-$9FFF). */
+  memcpy_vram(dst, src, 16);
 }
 
 /* Paint the road into BG map 0 ($9800). 20×18 visible cells:

package/examples/gb/templates/shmup.c

@@ -100,8 +100,9 @@ static void spawn(void) {
 
 static void upload_tile(uint8_t slot, const uint8_t *src) {
     uint8_t *dst = (uint8_t *)(0x8000 + slot * 16);
-    uint8_t i;
-    for (i = 0; i < 16; i++) dst[i] = src[i];
+    /* memcpy_vram (pointer-walk) — NOT an indexed dst[i]=src[i] loop, which
+     * SDCC sm83 miscompiles when dst points into VRAM ($8000-$9FFF). */
+    memcpy_vram(dst, src, 16);
 }
 
 /* Paint a starfield into BG map 0 ($9800): fill the visible 20×18 with the

package/examples/gb/templates/sports.c

@@ -77,8 +77,9 @@ static void reset_match(void) {
 
 static void upload_tile(uint8_t slot, const uint8_t *src) {
   uint8_t *dst = (uint8_t *)(0x8000 + slot * 16);
-  uint8_t i;
-  for (i = 0; i < 16; i++) dst[i] = src[i];
+  /* memcpy_vram (pointer-walk) — NOT an indexed dst[i]=src[i] loop, which
+   * SDCC sm83 miscompiles when dst points into VRAM ($8000-$9FFF). */
+  memcpy_vram(dst, src, 16);
 }
 
 /* Paint the Pong court into BG map 0 ($9800): dithered turf everywhere,

package/examples/gb/templates/tile_engine.c

@@ -143,8 +143,9 @@ static const uint8_t rooms[ROOMS][ROWS * COLS] = {
 
 /* ── Helpers ────────────────────────────────────────────────────── */
 static void copy_to_vram(uint8_t *dst, const uint8_t *src, uint16_t n) {
-  uint16_t i;
-  for (i = 0; i < n; i++) dst[i] = src[i];
+  /* Delegate to the runtime's pointer-walk copy — an indexed dst[i]=src[i]
+   * loop into VRAM is miscompiled by SDCC sm83. */
+  memcpy_vram(dst, src, n);
 }
 
 static void load_bg_palette(void) {