romdevtools 0.22.0 → 0.23.0

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

@@ -188,3 +188,94 @@ build({
   },
 })
 ```
+
+## sm83 codegen traps in plain game logic (WRAM integer/array code)
+
+Every footgun above is about VRAM / OAM-DMA / the cart header — the stuff
+that makes sprites vanish. This section is the opposite: **plain WRAM game
+logic** — PRNGs, collision grids, score math. Two such "miscompiles" were
+reported from a real GBC Columns build session and chased to ground here.
+**Verdict: neither was an sm83 codegen bug.** They are documented so you
+don't burn hours blaming the compiler for what is actually a memory-layout
+or static-init trap.
+
+### NOT a bug: 32-bit math / `uint32_t` shifts ≥ 16
+
+Reported: *"`static uint32_t rng=0x1357; rng ^= rng<<13; rng ^= rng>>17;
+rng ^= rng<<5;` degenerates — every `1+xorshift()%6` roll comes out the
+same (near-monochrome)."*
+
+**Reproduced on sm83: it does NOT degenerate.** A ROM that seeds the PRNG,
+calls `xorshift()` 20×, and writes `1 + (result % 6)` to WRAM reads back a
+fully-varied `5,5,5,1,5,5,4,1,3,2,1,...` — the exact sequence a reference
+implementation produces. Full 32-bit fidelity was confirmed byte-for-byte
+across several seeds (`0xDEADBEEF`, `0x00000001`, …). The `<<13` / `>>17` /
+`<<5` shifts (including the ≥16-bit right shift) and `% 6` are all correct.
+**Do not rewrite a working 32-bit xorshift into 16-bit to "dodge" this.**
+32-bit ops are bigger/slower than 16-bit on an 8-bit CPU, so prefer 16-bit
+PRNGs for *speed* — but not for correctness; both are correct.
+
+### The REAL trap behind "monochrome RNG": writing game state to a fixed
+`0xC0xx` WRAM address that overlaps your statics
+
+This is what actually produces the reported symptom. SDCC links the C
+runtime's `_DATA` / `_INITIALIZED` segment (every value-initialised
+`static`, e.g. `static uint32_t rng = 0x1357;`) **at the very bottom of
+WRAM, starting `$C000`**, with `_BSS` (zero-init statics like
+`static uint8_t grid[78];`) right after it. If your code also pokes a
+**hardcoded** `$C000`-area pointer for game state —
+
+```c
+volatile uint8_t *board = (volatile uint8_t *)0xC000;   /* DON'T */
+board[i] = piece;                 /* clobbers `rng` and friends! */
+```
+
+— you are scribbling directly over your own statics. Then `xorshift()`
+reads a trashed `rng`, the PRNG collapses, and every roll looks the same.
+It presents *exactly* like a compiler bug; it is not.
+
+**Fixes (any one):**
+- **Best — let the linker place it.** Use a `static` array and take its
+  address; never hardcode a WRAM pointer:
+  `static uint8_t board[6*13]; ... board[i] = piece;`
+- If you *must* use a fixed address, put it well clear of the runtime data:
+  `$C200`+ is safe for small projects (statics here end far below `$C100`;
+  `shadow_oam` is pinned at `$C100`). Confirm with the linker map — build
+  with `includeSymbols:true` and look at `s__DATA` / `s__BSS` (e.g.
+  `s__DATA = $C000`, `s__BSS = $C006`): your scratch RAM must start ABOVE
+  the end of `_BSS`.
+- **Diagnose it in seconds:** read `system_ram` offset 0 right after boot
+  and compare against your initialised statics' expected bytes. If a
+  `static uint32_t x = 0x1357;` doesn't read back `57 13 00 00` at its map
+  address, something is overwriting it.
+
+### NOT a bug: short `for` loop with an indexed `static` array read
+
+Reported: *"`for(i=0;i<3;i++){ if(grid[r*6+col]) return 1; }` reads the
+wrong cells (pieces lock mid-air / floating gaps); unrolling the 3
+iterations fixed it."*
+
+**Reproduced on sm83: the looped form reads the CORRECT cells.** A ROM that
+seeds `grid[]` with a sparse occupied/empty pattern and runs `collides()`
+both looped and hand-unrolled, for 8 straddling `(col,topy)` inputs, gets
+**identical, correct** results from both forms (`1,0,1,0,1,1,1,1`). The
+`grid[r*6+col]` index math and the 3-iteration loop are fine. If your real
+collision check "floats," look first at the WRAM-collision trap above (a
+clobbered `grid[]`), at off-by-one row/col limits, or at signed/unsigned
+mix-ups — not at loop codegen. **Don't pre-emptively unroll loops as a
+compiler workaround; with the stack-overflow fix in place, sm83 loops with
+indexed array reads are reliable.**
+
+### z80 (SMS/GG) ONLY — fixed: value-initialised statics booted as 0
+
+Investigating the above on the **z80** port (SMS/GG share the SDCC family)
+surfaced a real bug — but a **crt0** bug, not codegen. The bundled
+`sms_crt0.s` / `gg_crt0.s` placed `_INITIALIZER` (the ROM image of
+value-initialised statics) *after* the `_DATA` RAM block in the area list,
+so sdld put it in RAM; the gsinit `ldir` then copied uninitialised RAM onto
+itself and **every `static uint8_t x = 5;` booted as 0** (and BSS wasn't
+zeroed either). On z80 *this* is what made the xorshift PRNG monochrome
+(seed `rng` booted 0 → stayed 0). Fixed 2026-06-08 by ROM-placing
+`_INITIALIZER` + adding a `_DATA` zero loop, mirroring this sm83 crt0 (which
+was already correct — hence sm83 was never affected). If you bring your own
+z80 crt0, model gsinit on `gb_crt0.s`.

package/src/platforms/genesis/MENTAL_MODEL.md

@@ -161,6 +161,167 @@ while (1) {
 your sprite updates never appear on screen. It's the single most
 important call in any SGDK game loop.
 
+## Scrolling, parallax & the feel trap ⭐
+
+This is the section to read before you build a side-scroller. The #1
+"my horizontal movement feels choppy/juddery" bug on Genesis is a
+software mistake, not a hardware limit:
+
+> ### ⚠️ DO NOT rewrite full tilemaps in the frame loop.
+> The Genesis scrolls in HARDWARE. Moving the world is **two register
+> writes** (`VDP_setHorizontalScroll`), which are free. If instead you
+> redraw the plane each frame (a big `VDP_setTileMapXY`/`VDP_loadTileMap`
+> burst or a per-frame DMA), you overrun vblank, drop frames, and the
+> scroll judders. **Paint the planes ONCE at setup; the loop only nudges
+> scroll registers and re-stages sprites.** Use the
+> `template:"two_plane_parallax"` scaffold as the known-good shape.
+
+### Hardware scroll, the whole loop
+
+A two-plane parallax scroller's *entire* per-frame render cost is:
+
+```c
+VDP_setHorizontalScroll(BG_A, -camX);        // foreground: 1:1 with world
+VDP_setHorizontalScroll(BG_B, -(camX >> 4)); // background: 1/16 speed = far depth
+/* ...stage sprites in SCREEN space... */
+VDP_setSprite(0, playerScreenX, playerY, SPRITE_SIZE(2,2), attr);
+VDP_updateSprites(1, DMA);                    // flush the SAT
+SYS_doVBlankProcess();                        // flush DMA queue, sync vblank
+```
+
+No `VDP_setTileMapXY` / `VDP_fillTileMapRect` / `VDP_loadTileMap` in the
+loop. Those are SETUP calls (and tiny one-off updates — a coin that
+vanishes, a door that opens). They are NOT for whole-plane runtime
+redraws. Positive `camX` scrolls the plane LEFT, so you write the
+NEGATIVE camera offset. `VDP_setVerticalScroll` is the vertical twin
+(it writes VSRAM — see `genesis_vsram`).
+
+### Logical plane size vs HARDWARE plane size
+
+A common confusion: **the Genesis has ONE shared plane-size setting for
+BOTH planes A and B** (VDP regs 16). You pick 32×32 / 64×32 / 32×64 /
+64×64 *cells* once; you do NOT get an independent size per plane. So a
+"32-cell-wide level" still lives inside a 64-cell **physical** plane if
+that's the hardware size you set — the extra cells are just offscreen
+buffer. The scroll value wraps within the physical plane
+(64 cells = 512 px), which is exactly what makes a fully-painted plane
+tile forever with no redraw. Don't fight this: pick a hardware plane
+size and treat your logical world coords separately.
+
+| Plane size (cells) | Pixels   | Use                                  |
+|--------------------|----------|--------------------------------------|
+| 32×32              | 256×256  | single-screen / small wrap           |
+| **64×32** (default)| 512×256  | horizontal scroller (one plane wide) |
+| 32×64              | 256×512  | vertical scroller                    |
+| 64×64              | 512×512  | uses the most VRAM for name tables   |
+
+### How Sonic-style large maps REALLY work (wider than one plane)
+
+You do NOT make the plane "as wide as the level," and you do NOT redraw
+the plane. The 64-cell hardware plane is a **circular buffer**: as the
+camera advances, the column scrolling OFF the left re-appears on the
+right (the scroll wraps mod 512 px). You keep the visible window full by
+updating exactly **ONE offscreen column** each time the camera crosses
+an 8-px tile boundary:
+
+```c
+// camX in pixels; world is an array wider than 512 px.
+s16 newTileCol = camX >> 3;
+if (newTileCol != lastTileCol) {
+    // the column about to enter view on the right edge:
+    s16 worldCol  = (camX + SCREEN_W) >> 3;
+    s16 planeCol  = worldCol & 63;          // wrap into the 64-cell plane
+    drawWorldColumn(planeCol, worldCol);    // ONE column, ~28 cells — tiny
+    lastTileCol = newTileCol;
+}
+```
+
+That's ~28 tile writes per 8 px of travel, not a 1792-cell plane redraw.
+The `template:"platformer"` scaffold scrolls within one plane (no
+streaming); add the column-stream above to go wider. (Real Sonic also
+splits the screen with H-blank raster effects for independent strips —
+that's an IRQ/raster topic, see the `asm` template.)
+
+## Why does horizontal movement feel choppy? — motion-trace it headlessly ⭐
+
+When movement feels off, don't trial-and-error with screenshots. Sample
+the player's world-X, the camera scroll, and the actual VDP scroll
+values over ~180 frames while holding a direction, and read the curve.
+Two signatures to look for:
+
+1. **Camera scroll changes while the sprite's screen-X barely moves**
+   (or vice-versa) → your camera-follow math is off; the world slides
+   under a frozen-looking player, or the player slides on a frozen world.
+2. **Scroll JUMPS** (non-monotone, big steps) → you're scrolling by a
+   non-constant amount per frame (variable-rate camera, or you only
+   update scroll on a tile boundary instead of every frame).
+
+The exact call — hold RIGHT, sample player-X + both planes' HSCROLL +
+VSRAM over 180 frames. Expose the player/camera vars as `volatile`
+globals so they resolve (see "Reading your C globals headlessly"); the
+HSCROLL table lives in VRAM (`video_ram`), default base **$F000**
+(`frame({op:'verify'})`'s render summary prints "H-scroll table: $Fxxx"):
+
+```js
+b   = build({output:'romWithDebug', platform:'genesis', source, inline:true,
+             resolveSymbols:['g_player_x','g_cam_x']})
+// → resolvedSymbols.g_player_x.ramOffset (system_ram offset)
+recordSession({
+  frames:180, sampleEvery:10, includeScreenshots:false,
+  holdInputs:[{right:true}],
+  memorySamples:[
+    {label:'player_x', region:'system_ram', offset: PLAYER_X_OFF, length:2},
+    {label:'cam_x',    region:'system_ram', offset: CAM_X_OFF,    length:2},
+    {label:'hscrollA', region:'video_ram',  offset:0xF000,        length:2},
+    {label:'hscrollB', region:'video_ram',  offset:0xF002,        length:2},
+    {label:'vsram',    region:'genesis_vsram', offset:0,          length:4},
+  ],
+})
+```
+
+Read the columns: `player_x` should ramp smoothly; `hscrollA` should
+move 1:1 with the camera and `hscrollB` at the parallax ratio; both
+should be **monotone** (no jumps) while RIGHT is held. ⚠ Genesis WRAM +
+VRAM read **word-byte-swapped** in gpgx (a 16-bit `0x00F0` reads as
+bytes `F0 00`) — account for the swap, or read single bytes. For a
+compact value-vs-frame curve of just the HSCROLL table use
+`watch({on:'mem', region:'video_ram', offset:0xF000, length:4,
+format:'series', pressDuring:[{frame:0, button:'right', holdFrames:180}]})`.
+
+## Is the loop doing too much VDP work? — per-frame DMA budget ⭐
+
+The render-side cause of choppy scroll is **too many VDP/DMA bytes per
+frame** (a tilemap rewrite, an asset re-upload). Measure it directly,
+no core rebuild:
+
+```js
+watch({on:'dma', perFrame:true, frames:120,
+       pressDuring:[{frame:0, button:'right', holdFrames:120}]})
+```
+
+returns a per-frame timeline `[{frame, dmas, bytes, romBytes, ramBytes}]`
+plus `avgBytesPerFrame`, `peakFrame`/`peakBytes`, and `spikes`.
+
+- A **smooth hardware-scroll loop** shows a LOW, FLAT curve — after boot
+  it's mostly the steady SAT/scroll refresh (`ramBytes`, single/low
+  double digits per frame).
+- A **`spikes` entry** (bytes ≫ average, especially `romBytes` — an
+  asset upload FROM cart ROM) is the "I rewrote a tilemap / re-uploaded
+  tiles in the frame loop" smell. Move that work to setup, or stream
+  ONE column per 8-px scroll step (above).
+
+**CEILING / what this does NOT catch:** this counts mem→VDP **DMA**
+bytes (the dominant cost). Plain CPU writes to the VDP data port —
+`VDP_setTileMapXY` without DMA, single-cell pokes — are not DMA and are
+NOT counted; catching *those* would need a core-side VDP-data-port write
+hook (a gpgx patch, not shipped). In practice the expensive per-frame
+mistakes (whole-plane fills, `VDP_loadTileMap`, big `DMA_*` transfers)
+ALL go through DMA and DO show up here, so the budget is a reliable
+choppiness diagnostic today. There is no exposed per-frame
+"vblank-cycles-used / overrun" counter either — infer overrun from the
+byte budget (DMA bandwidth in vblank is finite: ~7.6 KB to VRAM in PAL
+vblank, less in NTSC; a frame moving multiple KB to VRAM is at risk).
+
 ## Input
 
 `u16 pad = JOY_readJoypad(JOY_1)` returns a packed bitmask. The

package/src/platforms/genesis/TROUBLESHOOTING.md

@@ -230,3 +230,35 @@ pixels per byte). The shipped `hello_sprite`, `tile_engine`, `shmup`,
 `platformer`, `puzzle` templates use this approach. **But never
 hand-encode a full-screen image this way** — that's the red/choppy
 failure above.
+
+## "Horizontal movement / scrolling feels choppy or judders"
+
+Almost always: **you're rewriting the tilemap in the frame loop.** The
+Genesis scrolls in HARDWARE — moving the world is two register writes
+(`VDP_setHorizontalScroll`), which cost nothing. If you instead redraw a
+plane every frame (a `VDP_fillTileMapRect` / `VDP_loadTileMap` / big
+`DMA_*` each frame), you overrun the vblank DMA budget and drop frames →
+judder. Fix: paint the planes ONCE at setup; the loop only nudges scroll
+registers + re-stages sprites. The `template:"two_plane_parallax"`
+scaffold is the known-good shape.
+
+Diagnose it without guessing (no core rebuild):
+
+- **Per-frame VDP work:** `watch({on:'dma', perFrame:true, frames:120,
+  pressDuring:[{frame:0, button:'right', holdFrames:120}]})` → a per-frame
+  `[{frame, bytes, romBytes, ramBytes}]` timeline + `spikes`. A smooth
+  loop is a LOW, FLAT curve (just the SAT/scroll refresh). A `spikes`
+  entry (bytes ≫ avg, esp. `romBytes`) IS the per-frame asset-upload /
+  tilemap-rewrite mistake. (Counts DMA bytes only — non-DMA single-cell
+  `VDP_setTileMapXY` pokes aren't counted; the expensive whole-plane work
+  always uses DMA and does show.)
+- **Motion curve:** sample the player-X + both planes' HSCROLL ($F000 in
+  `video_ram`) over 180 frames while holding a direction — see
+  MENTAL_MODEL.md "Why does horizontal movement feel choppy?". Look for
+  scroll that jumps (non-constant per-frame delta) or a camera that moves
+  while the sprite's screen-X is frozen.
+
+For a world WIDER than one 512-px plane, don't make the plane bigger and
+don't redraw it — stream ONE offscreen column per 8-px camera step
+(circular-buffer the 64-cell plane). See MENTAL_MODEL.md "How Sonic-style
+large maps REALLY work".

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

@@ -31,6 +31,8 @@
         .globl  l__INITIALIZER
         .globl  s__INITIALIZER
         .globl  s__INITIALIZED
+        .globl  s__DATA
+        .globl  l__DATA
 
 ;; ─── Reset vector at $0000 ────────────────────────────────────────
         .area _HEADER (ABS)
@@ -83,7 +85,15 @@
 ;; call main. The initializer area is filled by sdcc when it sees
 ;; global initializations.
 
+        ;; AREA ORDERING IS LOad-BEARING. `_INITIALIZER` (the ROM image of
+        ;; every value-initialised `static` global) MUST be declared in the
+        ;; ROM group here — BEFORE the `_DATA` RAM block. If it isn't, sdld
+        ;; places `_INITIALIZER` in RAM right after `_INITIALIZED`, so the
+        ;; gsinit copy below copies uninitialised RAM onto itself and every
+        ;; `static uint8_t x = 5;` boots as 0. (Bug found 2026-06-08; see the
+        ;; matching note in sms_crt0.s — both z80 crt0s were missing this.)
         .area   _HOME
+        .area   _INITIALIZER
         .area   _CODE
         .area   _GSINIT
         .area   _GSFINAL
@@ -97,6 +107,26 @@
         .area   _CODE
 
 gsinit:
+        ;; ── Zero the BSS segment (`_DATA`). ──────────────────────────
+        ;; Every uninitialised `static` global lands in `_DATA` and MUST
+        ;; read back 0 at boot. Mirrors the sm83 GB crt0's gsinit_data loop.
+        ld      bc, #l__DATA
+        ld      a, b
+        or      a, c
+        jr      Z, gsinit_bss_done
+        ld      hl, #s__DATA
+        ld      (hl), #0x00
+        ld      d, h
+        ld      e, l
+        inc     de
+        dec     bc
+        ld      a, b
+        or      a, c
+        jr      Z, gsinit_bss_done
+        ldir                            ; propagate the 0 across _DATA
+gsinit_bss_done:
+
+        ;; ── Copy `_INITIALIZER` (ROM) → `_INITIALIZED` (RAM). ────────
         ld      bc, #l__INITIALIZER
         ld      a, b
         or      a, c

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

@@ -22,6 +22,8 @@
         .globl  l__INITIALIZER
         .globl  s__INITIALIZER
         .globl  s__INITIALIZED
+        .globl  s__DATA
+        .globl  l__DATA
 
 ;; ─── Reset vector at $0000 ────────────────────────────────────────
         .area _HEADER (ABS)
@@ -72,7 +74,19 @@
 ;; call main. The initializer area is filled by sdcc when it sees
 ;; global initializations.
 
+        ;; AREA ORDERING IS LOad-BEARING. `_INITIALIZER` (the ROM image of
+        ;; every value-initialised `static` global) MUST be declared in the
+        ;; ROM group here — BEFORE the `_DATA` RAM block. If it isn't, sdld
+        ;; places `_INITIALIZER` in RAM right after `_INITIALIZED`, so the
+        ;; gsinit copy below copies uninitialised RAM onto itself and every
+        ;; `static uint8_t x = 5;` boots as 0. (Bug found 2026-06-08: a GBC
+        ;; Columns agent's `static uint32_t rng = 0x1357;` booted as 0, so
+        ;; the xorshift PRNG stayed 0 and every "random" roll came out the
+        ;; same — a "monochrome RNG" that looked like an SDCC codegen bug
+        ;; but was really this missing ROM placement. The sm83 GB crt0 has
+        ;; always placed _INITIALIZER in ROM; the z80 crt0s never did.)
         .area   _HOME
+        .area   _INITIALIZER
         .area   _CODE
         .area   _GSINIT
         .area   _GSFINAL
@@ -86,6 +100,32 @@
         .area   _CODE
 
 gsinit:
+        ;; ── Zero the BSS segment (`_DATA`). ──────────────────────────
+        ;; Every uninitialised `static` global lands in `_DATA` and MUST
+        ;; read back 0 at boot. Without this, `static uint8_t flag;` boots
+        ;; with whatever power-on WRAM byte was there (gambatte/gpgx leave
+        ;; garbage), and `if (flag)` spuriously fires. Mirrors the sm83 GB
+        ;; crt0's gsinit_data loop.
+        ld      bc, #l__DATA
+        ld      a, b
+        or      a, c
+        jr      Z, gsinit_bss_done
+        ld      hl, #s__DATA
+        ld      (hl), #0x00
+        ld      d, h
+        ld      e, l
+        inc     de
+        dec     bc
+        ld      a, b
+        or      a, c
+        jr      Z, gsinit_bss_done
+        ldir                            ; propagate the 0 across _DATA
+gsinit_bss_done:
+
+        ;; ── Copy `_INITIALIZER` (ROM) → `_INITIALIZED` (RAM). ────────
+        ;; The value-initialised-statics path: `static uint8_t lives = 3;`
+        ;; lives in _INITIALIZED at runtime; its initial value sits in
+        ;; _INITIALIZER in ROM (now correctly ROM-placed, see above).
         ld      bc, #l__INITIALIZER
         ld      a, b
         or      a, c

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

@@ -152,12 +152,29 @@ export function lintSdccSource(source, file = "main.c", opts = {}) {
   }
 
   // ─── __xdata / VRAM byte-copy miscompile ────────────────────────
-  // SDCC sm83 miscompiles `for (i...) dst[i] = src[i];` when dst is an
+  // SDCC sm83 miscompiles `for (i...) dst[i] = src[i];` ONLY when dst is an
   // __xdata pointer (e.g. into VRAM $8000) — it writes through the return
-  // address and crashes the CPU. Hard to prove the pointer target
-  // statically, so flag the SHAPE (an array-index copy `a[i] = b[i];`
-  // inside a for-loop) as ADVISORY, pointing at memcpy_vram. Conservative:
-  // require a for-loop on the line/just above + an indexed-to-indexed copy.
+  // address and crashes the CPU. A plain WRAM array copy (`static uint8_t
+  // rb[78]; ... rb[i]=grid[i];`) is perfectly fine. The old lint flagged the
+  // SHAPE unconditionally as a "warning" — every WRAM copy in every genre
+  // scaffold cried wolf, training agents to distrust the linter. We now
+  // classify the DESTINATION identifier before deciding the severity:
+  //
+  //   • PROVABLY VRAM/__xdata  → "warning" (the real crash-class footgun)
+  //       - dst is declared as a POINTER (`type *dst`) — only pointers can
+  //         alias __xdata; an indexed write through one is the bug.
+  //       - dst is a known-VRAM name (vram*, VRAM, *vram*, bgmap, _VRAM*).
+  //       - dst is assigned from a cast/literal in $8000-$9FFF anywhere in
+  //         the source (e.g. `dst = (uint8_t*)0x9800;`).
+  //   • PLAIN RAM ARRAY        → SUPPRESS (declared `type dst[N];` here).
+  //   • UNKNOWN (bare ident,   → "info" — visible, not scary. Better to
+  //     no decl in this TU)      occasionally downgrade a real VRAM case to
+  //                              info than to keep crying wolf on WRAM.
+  //
+  // The crash cases that MATTER (the documented memcpy_vram footgun) are
+  // pointer-to-VRAM, which the "provably VRAM" path still catches as a
+  // warning.
+  const dstClass = classifyCopyDest(lines);
   for (let i = 0; i < lines.length; i++) {
     const code = lines[i].replace(/\/\/.*$/, "").replace(/\/\*.*?\*\//g, "");
     // indexed-to-indexed copy: ident[idx] = ident[idx];  (same index token)
@@ -168,17 +185,72 @@ export function lintSdccSource(source, file = "main.c", opts = {}) {
     // Require a for-loop driving this copy (this line or the 2 above).
     const ctx = (lines[i] + "\n" + (lines[i - 1] || "") + "\n" + (lines[i - 2] || ""));
     if (!/\bfor\s*\(/.test(ctx)) continue;
+    const dst = cp[1];
+    // A VRAM-suggestive NAME promotes an otherwise-unknown dest to VRAM even
+    // with no decl in this TU (e.g. `vram_buf[i] = tiles[i];`). A declared
+    // plain array still wins as "array" (suppress) — names rarely collide.
+    const klass = dstClass.get(dst) || (isVramName(dst) ? "vram" : "unknown");
+    if (klass === "array") continue; // plain WRAM array — provably safe, suppress
+    const isVram = klass === "vram";
     issues.push({
-      severity: "warning",
+      // Provably-VRAM → warning (the crash-class footgun). Unknown bare
+      // pointer → info (visible, not "your code is broken"). Never critical:
+      // even the VRAM case only miscompiles, it isn't an unconditional hang.
+      severity: isVram ? "warning" : "info",
       file,
       line: i + 1,
       stage: "lint",
-      message: `byte-copy loop \`${cp[1]}[${idx1}] = ${cp[3]}[${idx2}]\` — miscompiles if the destination is VRAM/__xdata`,
-      details: `${portLabel} miscompiles this pattern when '${cp[1]}' points into VRAM ($8000-$9FFF) or another __xdata region — it writes through the return address and crashes the CPU (PC near $002B, sprites/tiles never show). If '${cp[1]}' is a VRAM/__xdata pointer, use \`memcpy_vram(${cp[1]}, ${cp[3]}, n)\` (in gb_runtime.c) instead. Ignore if '${cp[1]}' is plain WRAM/an array. See GB TROUBLESHOOTING § the #1 SDCC footgun.`,
+      message: isVram
+        ? `byte-copy loop \`${dst}[${idx1}] = ${cp[3]}[${idx2}]\` into VRAM/__xdata — ${portLabel} miscompiles this`
+        : `byte-copy loop \`${dst}[${idx1}] = ${cp[3]}[${idx2}]\` — safe for WRAM arrays, but miscompiles if '${dst}' points into VRAM/__xdata`,
+      details: isVram
+        ? `${portLabel} miscompiles this pattern when '${dst}' points into VRAM ($8000-$9FFF) or another __xdata region — it writes through the return address and crashes the CPU (PC near $002B, sprites/tiles never show). Use \`memcpy_vram(${dst}, ${cp[3]}, n)\` (in gb_runtime.c) instead. See GB TROUBLESHOOTING § the #1 SDCC footgun.`
+        : `If '${dst}' is a plain WRAM array (\`type ${dst}[N];\`) this is FINE — ignore. ${portLabel} only miscompiles it when '${dst}' is a pointer into VRAM ($8000-$9FFF)/__xdata, where it writes through the return address and crashes the CPU. If '${dst}' is a VRAM pointer, use \`memcpy_vram(${dst}, ${cp[3]}, n)\` instead. See GB TROUBLESHOOTING § the #1 SDCC footgun.`,
       ref: "xdata-copy-miscompile",
     });
   }
 
+  // ─── hardcoded $C000-area WRAM pointer overlaps the C statics ───
+  // SDCC links `_DATA`/`_INITIALIZED` (value-init statics) + `_BSS` (zero-init
+  // statics) at the BOTTOM of WRAM starting $C000. A program that ALSO pokes a
+  // hardcoded pointer into that low range (e.g. `(uint8_t*)0xC000`) scribbles
+  // over its own statics — the seed of a PRNG, a collision grid, the score —
+  // and the symptom looks EXACTLY like an SDCC codegen bug (a 32-bit xorshift
+  // that "degenerates" because its seed got clobbered, never a real
+  // miscompile). This was the real root cause behind a GBC Columns agent's
+  // "monochrome RNG" report (2026-06-08); the math itself compiles correctly.
+  //
+  // ONLY for the sm83/z80 GB/SMS-family, whose WRAM base is $C000. Flag the
+  // low 256 bytes ($C000-$C0FF) where _DATA/_INITIALIZED live (small projects'
+  // statics sit here; $C100 is shadow_oam; $C200+ is the documented-safe
+  // scratch floor). INFO severity — visible, not "your code is broken": a
+  // hardcoded low pointer is occasionally legitimate (e.g. you've checked the
+  // map). NEVER critical.
+  if (port === "sm83" || port === "z80") {
+    // pointer cast/decl/assignment to a $C0xx literal: `(uint8_t*)0xC000`,
+    // `uint8_t *p = (uint8_t*)0xc010;`, `p = 0xC0FF;`
+    const ptrLit = /\(\s*(?:volatile\s+|const\s+|unsigned\s+|signed\s+)*[A-Za-z_]\w*\s*\*+\s*\)\s*0x(C0[0-9a-fA-F]{2})\b/;
+    const seen = new Set();
+    for (let i = 0; i < lines.length; i++) {
+      const code = lines[i].replace(/\/\/.*$/, "").replace(/\/\*.*?\*\//g, "");
+      const m = code.match(ptrLit);
+      if (!m) continue;
+      const addr = parseInt(m[1], 16); // already the full $C0xx address
+      const key = i + ":" + addr;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      issues.push({
+        severity: "info",
+        file,
+        line: i + 1,
+        stage: "lint",
+        message: `hardcoded WRAM pointer $${addr.toString(16).toUpperCase()} overlaps the C static-data segment ($C000-)`,
+        details: `${portLabel} links your value- and zero-initialised \`static\` globals (PRNG seeds, grids, scores) at the BOTTOM of WRAM from $C000. A hardcoded pointer into $C000-$C0FF can scribble over them — the classic symptom is a PRNG/array that looks "miscompiled" (e.g. an xorshift whose seed got clobbered so every roll is identical) when the math is actually fine. Prefer a \`static\` array and let the linker place it; if you must hardcode, use $C200+ and verify with the linker map (build with includeSymbols:true → check s__DATA/s__BSS). $C100 is shadow_oam. See ${port === "sm83" ? "GB/GBC" : "SMS/GG"} SDCC_GOTCHAS.md § "sm83 codegen traps in plain game logic".`,
+        ref: "wram-static-overlap",
+      });
+    }
+  }
+
   // Mid-block declarations (rough heuristic — flags any `type name [=...] ;`
   // that appears after a non-decl, non-blank statement at deeper indent
   // than the function opening brace).
@@ -206,6 +278,90 @@ export function lintSources(sources, opts = {}) {
 
 // ─── helpers ───────────────────────────────────────────────────────
 
+/**
+ * Known-VRAM symbol names (GB/GBC/SMS conventions). Case-insensitive;
+ * substring "vram" matches vram_ptr / pVRAM / VRAMbase, plus the common
+ * GB BG-map / tile-data symbols. A dest with such a name is treated as a
+ * VRAM pointer even with no visible declaration.
+ * @param {string} n
+ * @returns {boolean}
+ */
+function isVramName(n) {
+  return /vram/i.test(n) || /^(?:bgmap|tilemap|tiledata|chrram|_VRAM)/i.test(n);
+}
+
+/**
+ * Classify each identifier that is the destination of a copy loop into one
+ * of: "vram" (provably a VRAM/__xdata pointer → real crash-class footgun),
+ * "array" (declared as a plain `type name[N];` RAM array → provably safe,
+ * suppress the warning), or absent (unknown — caller treats as "info").
+ *
+ * This is a whole-TU pass: a name is classified by scanning the ENTIRE
+ * source, so a `uint8_t *dst;` decl far above the loop, or a later
+ * `dst = (uint8_t*)0x9800;` assignment, still classifies it as VRAM.
+ *
+ * Precedence: VRAM wins over array (a name that is BOTH a pointer and,
+ * say, shadowed by an array elsewhere should still be treated as the
+ * dangerous case — but in practice a single name is one or the other).
+ *
+ * @param {string[]} lines  source split into lines
+ * @returns {Map<string,"vram"|"array">}
+ */
+function classifyCopyDest(lines) {
+  /** @type {Map<string,"vram"|"array">} */
+  const klass = new Map();
+  const setVram  = (n) => { klass.set(n, "vram"); };
+  const setArray = (n) => { if (klass.get(n) !== "vram") klass.set(n, "array"); };
+
+  // A literal/cast value lands in VRAM if it's 0x8000–0x9FFF.
+  const inVramRange = (hexOrDec) => {
+    const v = /^0x/i.test(hexOrDec) ? parseInt(hexOrDec, 16) : parseInt(hexOrDec, 10);
+    return Number.isFinite(v) && v >= 0x8000 && v <= 0x9fff;
+  };
+  // Type keywords that introduce a declaration (subset is fine — we only
+  // need to tell "pointer decl" from "array decl").
+  const TYPE = "(?:unsigned\\s+|signed\\s+)?(?:char|short|int|long|void|u?int(?:8|16|32|64)_t|u8|u16|u32|u64|uint8|uint16|uint32|uint64|int8|int16|int32|int64|size_t|[A-Z][A-Za-z0-9_]*_t)";
+  const QUAL = "(?:static\\s+|const\\s+|register\\s+|volatile\\s+|extern\\s+|auto\\s+|__xdata\\s+|__at\\s*\\([^)]*\\)\\s*)*";
+  // Pointer declaration: `<quals> <type> * name`  (one or more `*`).
+  const ptrDeclRe   = new RegExp(`\\b${QUAL}${TYPE}\\s*\\*+\\s*([A-Za-z_]\\w*)`, "g");
+  // Array declaration:   `<quals> <type> name[ ... ]`  (NOT a pointer).
+  const arrDeclRe   = new RegExp(`\\b${QUAL}${TYPE}\\s+([A-Za-z_]\\w*)\\s*\\[`, "g");
+  // Pointer assigned a VRAM literal/cast:  name = (cast?) 0x8xxx/0x9xxx
+  // e.g.  dst = (uint8_t*)0x9800;   p = (void*)0x8000;   q = 0x8800;
+  const vramAssignRe = /\b([A-Za-z_]\w*)\s*=\s*(?:\([^)]*\)\s*)?(0x[0-9a-fA-F]+|\d{4,})\b/g;
+  // Pointer DECL with an inline VRAM initializer:
+  //   uint8_t *dst = (uint8_t*)0x8000;
+  const ptrInitVramRe = new RegExp(`\\b${QUAL}${TYPE}\\s*\\*+\\s*([A-Za-z_]\\w*)\\s*=\\s*(?:\\([^)]*\\)\\s*)?(0x[0-9a-fA-F]+|\\d{4,})`, "g");
+
+  for (let i = 0; i < lines.length; i++) {
+    const code = lines[i].replace(/\/\/.*$/, "").replace(/\/\*.*?\*\//g, "");
+
+    // 1) pointer decl with a VRAM-range initializer → VRAM (strongest).
+    ptrInitVramRe.lastIndex = 0;
+    for (let m; (m = ptrInitVramRe.exec(code)); ) {
+      if (inVramRange(m[2])) setVram(m[1]);
+    }
+    // 2) any name assigned a VRAM-range literal/cast → VRAM.
+    vramAssignRe.lastIndex = 0;
+    for (let m; (m = vramAssignRe.exec(code)); ) {
+      if (inVramRange(m[2])) setVram(m[1]);
+    }
+    // 3) pointer declarations → VRAM-candidate (only pointers can alias
+    //    __xdata; an indexed write through one is the documented bug).
+    ptrDeclRe.lastIndex = 0;
+    for (let m; (m = ptrDeclRe.exec(code)); ) setVram(m[1]);
+    // 4) plain array declarations → safe RAM array (unless already VRAM).
+    arrDeclRe.lastIndex = 0;
+    for (let m; (m = arrDeclRe.exec(code)); ) setArray(m[1]);
+  }
+
+  // 5) name-based VRAM override: any dest named like VRAM is VRAM even if
+  //    it was (mis)classified as an array by a same-named decl elsewhere.
+  for (const n of klass.keys()) if (isVramName(n)) setVram(n);
+
+  return klass;
+}
+
 /**
  * Detect mid-block variable declarations (C89 violation). Simple state
  * machine: track block depth + whether we've seen a non-decl statement