romdevtools 0.22.1 → 0.23.0

package/src/mcp/tools/project.js

@@ -923,7 +923,15 @@ TEMPLATES.genesis = {
     runtimeDirs: SGDK_RUNTIME_DIRS,
     lang: SGDK_LANG,
     ext: ".bin",
-    describe: "SIDE-SCROLLING platformer for Genesis. Subpixel gravity + jump + land-on-top collision against a static platform list spread across a 512-px world. Camera follows the player; Plane A scrolls with the world via VDP_setHorizontalScroll, Plane B scrolls at half-rate for parallax. A=jump, d-pad=move. The world here is one 64-cell plane wide (no streaming) — for a wider world, stream the column entering view each 8-px camera step (see Genesis MENTAL_MODEL.md 'Horizontal scrolling'). Extend with enemies, goals, pickups.",
+    describe: "SIDE-SCROLLING platformer for Genesis. Subpixel gravity + jump + land-on-top collision against a static platform list spread across a 512-px world. Camera follows the player; Plane A scrolls with the world via VDP_setHorizontalScroll, Plane B scrolls at half-rate for parallax. A=jump, d-pad=move. The world here is one 64-cell plane wide (no streaming) — for a wider world, stream the column entering view each 8-px camera step (see Genesis MENTAL_MODEL.md 'How Sonic-style large maps REALLY work'). NOTE: it redraws nothing per frame (scroll is hardware) — for a from-scratch smooth-scroll/parallax starting point with ZERO loop-time tilemap writes, see template:'two_plane_parallax'. Extend with enemies, goals, pickups.",
+  },
+  two_plane_parallax: {
+    main: "templates/two_plane_parallax.c",
+    runtime: SGDK_RUNTIME,
+    runtimeDirs: SGDK_RUNTIME_DIRS,
+    lang: SGDK_LANG,
+    ext: ".bin",
+    describe: "Two-plane parallax SCROLLING scaffold — the smooth-feel starting point for a Uridium/Sonic-style side-scroller. Plane A = a painted foreground world (ground + platform blocks), Plane B = a repeated starfield, one player sprite. The frame loop does HARDWARE SCROLL ONLY (two VDP_setHorizontalScroll writes + one VDP_updateSprites) — ZERO tilemap writes per frame, which is what keeps movement smooth (rewriting a plane each frame is the #1 'choppy horizontal movement' bug). Plane B scrolls at 1/4 speed for depth. Exposes volatile g_player_x / g_cam_x so you can motion-trace it headlessly (symbols->memory->recordSession). Extend by streaming one offscreen column per 8-px camera step for worlds wider than 512 px — see Genesis MENTAL_MODEL.md 'Scrolling, parallax & the feel trap'.",
   },
   puzzle: {
     main: "templates/puzzle.c",

package/src/mcp/tools/rendering-context.js

@@ -823,7 +823,7 @@ export function registerRenderingContextTools(server, z, sessionKey) {
     },
     safeTool(async (args) => {
       switch (args.view) {
-        case "map":         return await inspectBackgroundMapCore(args);
+        case "map":         return await inspectBackgroundMapCore(args, sessionKey);
         case "renderState": {
           // Pass sessionKey through so getRenderingContextCore can resolve the
           // per-session host (round 26 fix; was `sessionKey is not defined`).

package/src/mcp/tools/symbols.js

@@ -8,6 +8,7 @@
 // caching for v1.
 
 import { writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { jsonContent, safeTool, writeOutput } from "../util.js";
 import { addressToSymbolCore } from "./address-to-symbol.js";
 
@@ -34,7 +35,7 @@ function siblings(romPath) {
 
 // build({output:'romWithDebug'}) — the cc65 .dbg / sdld .map / m68k ELF-map
 // build. Exported core; the `build` router (toolchain.js) calls it.
-export async function buildSourceWithDebugCore({ platform, source, sources, includes, linkerConfig, crt0, codeLoc, outputPath, inline = false }) {
+export async function buildSourceWithDebugCore({ platform, source, sources, includes, linkerConfig, crt0, codeLoc, outputPath, inline = false, resolveSymbols }) {
       const CC65_TARGETS = ["nes", "c64", "atari7800", "lynx"];
       const SDCC_TARGETS = ["gb", "gbc", "sms", "gg"];
       const M68K_TARGETS = ["genesis"];
@@ -42,6 +43,22 @@ export async function buildSourceWithDebugCore({ platform, source, sources, incl
         throw new Error("buildSourceWithDebug: pass outputPath (where to save the ROM; .dbg/.map/log land alongside it) or inline:true to get everything in the response.");
       }
       const sib = outputPath ? siblings(outputPath) : null;
+      // resolveSymbols:[...] — resolve just these names off the freshly-produced
+      // debug source and fold {symbols:{name:{address,hex,region?,ramOffset?}}}
+      // into the response, so the agent gets the addresses it asked for WITHOUT
+      // the 30-60KB map being dumped (or even written) anywhere it must re-read.
+      const wantResolve = Array.isArray(resolveSymbols) && resolveSymbols.length > 0;
+      const foldResolved = async (out, { dbg, map }) => {
+        if (!wantResolve) return out;
+        try {
+          const r = await resolveSymbolsBatchCore({ dbg, map, names: resolveSymbols, platform });
+          out.resolvedSymbols = r.symbols;
+          if (r.missing) out.unresolvedSymbols = r.missing;
+        } catch (e) {
+          out.resolveSymbolsError = String(e?.message ?? e);
+        }
+        return out;
+      };
 
       if (CC65_TARGETS.includes(platform)) {
         const { buildC, buildAsm } = await import("../../toolchains/cc65/cc65.js");
@@ -78,6 +95,7 @@ export async function buildSourceWithDebugCore({ platform, source, sources, incl
           if (inline) out.dbg = r.dbg;
           else out.dbgPath = writeOutput(r.dbg, { outputPath: sib.dbg, what: ".dbg" }).path;
         }
+        await foldResolved(out, { dbg: r.dbg });
         return jsonContent(out);
       }
 
@@ -116,6 +134,7 @@ export async function buildSourceWithDebugCore({ platform, source, sources, incl
           if (inline) out.mapText = r.symbols;
           else out.mapPath = writeOutput(r.symbols, { outputPath: sib.map, what: ".map" }).path;
         }
+        await foldResolved(out, { map: r.symbols });
         return jsonContent(out);
       }
 
@@ -152,6 +171,7 @@ export async function buildSourceWithDebugCore({ platform, source, sources, incl
         } else {
           out.mapNote = "No linker map produced (link likely failed — check exitCode/log).";
         }
+        await foldResolved(out, { map: r.symbols });
         return jsonContent(out);
       }
 
@@ -169,6 +189,49 @@ export function registerSymbolTools(server, z) {
 
 // ── *Core functions for the `symbols` tool ──
 
+/**
+ * Resolve the on-disk `dbgPath`/`mapPath` convenience args into the inline
+ * `dbg`/`map` TEXT the core functions consume. The whole point: an agent can
+ * point at the .dbg/.map that build({output:'romWithDebug'}) wrote to disk and
+ * get back JUST the address — the 30-60KB map never enters the agent's context.
+ * Inline `dbg`/`map` always win if both are passed.
+ * @param {{dbg?:string, map?:string, dbgPath?:string, mapPath?:string}} args
+ * @returns {Promise<{dbg?:string, map?:string}>} the same args with paths read into text
+ */
+export async function loadDebugSource(args) {
+  const out = { ...args };
+  if (out.dbg == null && out.dbgPath) out.dbg = await readFile(out.dbgPath, "utf-8");
+  if (out.map == null && out.mapPath) out.map = await readFile(out.mapPath, "utf-8");
+  return out;
+}
+
+/**
+ * Resolve a list of symbol NAMES against an already-loaded debug source (cc65
+ * .dbg or sdld/GNU ld .map TEXT). Returns {name:{address,hex,region?,ramOffset?}}
+ * for each that resolves, and a `missing` list for any that don't. Powers
+ * build({resolveSymbols:[...]}) — resolve just the names you care about off the
+ * freshly-produced map WITHOUT dumping the whole map into the response.
+ * @param {{dbg?:string, map?:string, names:string[], platform?:string}} args
+ */
+export async function resolveSymbolsBatchCore({ dbg, map, names, platform }) {
+  /** @type {Record<string, {address:number, hex:string, region?:string, ramOffset?:number}>} */
+  const symbols = {};
+  /** @type {string[]} */
+  const missing = [];
+  for (const name of names) {
+    try {
+      const r = await resolveSymbolCore({ dbg, map, name, platform });
+      const entry = { address: r.address, hex: r.hex };
+      if (r.region) entry.region = r.region;
+      if (r.ramOffset != null) entry.ramOffset = r.ramOffset;
+      symbols[name] = entry;
+    } catch {
+      missing.push(name);
+    }
+  }
+  return { symbols, ...(missing.length ? { missing } : {}) };
+}
+
 /**
  * Load a normalized symbol list from whichever debug format the caller passed:
  * cc65 `.dbg`, SDCC sdld `.map`, OR GNU ld `.map` (Genesis/m68k). Auto-detects
@@ -218,8 +281,14 @@ function ramReadHint(sym) {
   };
 }
 
+/** Tag a resolve result with the CPU memory region the address falls in (when platform known). */
+function regionField(platform, addr) {
+  const region = platform ? regionForAddress(platform, addr) : null;
+  return region ? { region } : {};
+}
+
 /** op:'resolve' — symbol name → address. cc65 .dbg, sdld .map, OR GNU ld .map (Genesis). */
-export async function resolveSymbolCore({ dbg, map, name }) {
+export async function resolveSymbolCore({ dbg, map, name, platform }) {
       // cc65 .dbg keeps its bespoke index (it understands the '_name' C alias).
       if (dbg && !map) {
         const { parseDbg, DbgIndex } = await import("../../toolchains/cc65/dbgparse.js");
@@ -233,6 +302,7 @@ export async function resolveSymbolCore({ dbg, map, name }) {
         if (addr === null) throw new Error(`no symbol named '${name}' in this .dbg`);
         return {
           name: resolvedName, address: addr, hex: hexAddr(addr),
+          ...regionField(platform, addr),
           ...(resolvedName !== name ? { note: `Resolved as cc65 C symbol '${resolvedName}' (you asked for '${name}').` } : {}),
         };
       }
@@ -242,7 +312,7 @@ export async function resolveSymbolCore({ dbg, map, name }) {
       // SDCC strips the leading underscore on load; a caller passing '_score' still matches.
       if (!hit && name.startsWith("_")) hit = symbols.find((s) => s.name === name.slice(1));
       if (!hit) throw new Error(`no symbol named '${name}' in this ${format}.`);
-      return { name: hit.name, address: hit.addr, hex: hexAddr(hit.addr), format, ...ramReadHint(hit) };
+      return { name: hit.name, address: hit.addr, hex: hexAddr(hit.addr), format, ...regionField(platform, hit.addr), ...ramReadHint(hit) };
 }
 
 /** op:'lookup' — address → the symbol whose value is closest at-or-below it. cc65 .dbg, sdld/GNU .map. */
@@ -270,35 +340,46 @@ export async function lookupAddressCore({ dbg, map, address }) {
       };
 }
 
+// Per-platform region boundaries (CPU memory map). cc65 6502 targets + the
+// Z80 family (SDCC) — both keyed the same way. Single source of truth shared by
+// op:'map' (getMemoryMapCore) and the build({resolveSymbols}) region tagging.
+const REGIONS_BY_PLATFORM = {
+  nes:       [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x200,hi:0x7ff},{name:"ppu_regs",lo:0x2000,hi:0x2007},{name:"apu_input",lo:0x4000,hi:0x401f},{name:"sram",lo:0x6000,hi:0x7fff},{name:"prg_rom",lo:0x8000,hi:0xffff}],
+  c64:       [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x200,hi:0x9fff},{name:"basic_rom",lo:0xa000,hi:0xbfff},{name:"io",lo:0xd000,hi:0xdfff},{name:"kernal",lo:0xe000,hi:0xffff}],
+  atari7800: [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x1800,hi:0x27ff},{name:"cart_rom",lo:0x4000,hi:0xffff}],
+  lynx:      [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x200,hi:0xfbff},{name:"hw_regs",lo:0xfc00,hi:0xffff}],
+  // PC Engine (cc65 pce target): ZP + 8KB work RAM at $2200 (the pce.cfg
+  // MAIN segment), HuCard ROM mapped high. The HuC6280 stack lives in the
+  // $21xx page via the MPR mapping.
+  pce:       [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x2100,hi:0x21ff},{name:"system_ram",lo:0x2200,hi:0x3fff},{name:"hucard_rom",lo:0xe000,hi:0xffff}],
+  // Z80 family (SDCC + sdld .map). Cartridge ROM in the low half, work RAM high.
+  gb:        [{name:"rom",lo:0,hi:0x7fff},{name:"vram",lo:0x8000,hi:0x9fff},{name:"cart_ram",lo:0xa000,hi:0xbfff},{name:"work_ram",lo:0xc000,hi:0xdfff},{name:"oam",lo:0xfe00,hi:0xfe9f},{name:"io_hram",lo:0xff00,hi:0xffff}],
+  gbc:       [{name:"rom",lo:0,hi:0x7fff},{name:"vram",lo:0x8000,hi:0x9fff},{name:"cart_ram",lo:0xa000,hi:0xbfff},{name:"work_ram",lo:0xc000,hi:0xdfff},{name:"oam",lo:0xfe00,hi:0xfe9f},{name:"io_hram",lo:0xff00,hi:0xffff}],
+  sms:       [{name:"rom",lo:0,hi:0xbfff},{name:"work_ram",lo:0xc000,hi:0xdfff},{name:"ram_mirror",lo:0xe000,hi:0xffff}],
+  gg:        [{name:"rom",lo:0,hi:0xbfff},{name:"work_ram",lo:0xc000,hi:0xdfff},{name:"ram_mirror",lo:0xe000,hi:0xffff}],
+  // MSX cartridge: BIOS low, cart at $4000-$BFFF, work RAM $C000-$FFFF.
+  msx:       [{name:"bios",lo:0,hi:0x3fff},{name:"cart_rom",lo:0x4000,hi:0xbfff},{name:"work_ram",lo:0xc000,hi:0xffff}],
+  // Genesis (m68k-elf GNU ld map): ROM low, work-RAM mirror at $E0FF0000
+  // (= the emulator's `system_ram`, offset = low 16 bits of the symbol addr).
+  genesis:   [{name:"rom",lo:0,hi:0x3fffff},{name:"work_ram_mirror",lo:0xe0ff0000,hi:0xe0ffffff}],
+};
+
+/** Region NAME an address falls in for a platform, or null if unknown/out-of-range. */
+function regionForAddress(platform, addr) {
+  const regions = REGIONS_BY_PLATFORM[platform];
+  if (!regions) return null;
+  for (const r of regions) {
+    if (addr >= r.lo && addr <= r.hi) return r.name;
+  }
+  return null;
+}
+
 /** op:'map' — categorized layout of where the linker placed code+vars (cc65 .dbg OR sdld .map). */
 export async function getMemoryMapCore({ dbg, map, platform }) {
-      // Per-platform region boundaries (CPU memory map). cc65 6502 targets +
-      // the Z80 family (SDCC) — both keyed the same way.
-      const regionsByPlatform = {
-        nes:       [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x200,hi:0x7ff},{name:"ppu_regs",lo:0x2000,hi:0x2007},{name:"apu_input",lo:0x4000,hi:0x401f},{name:"sram",lo:0x6000,hi:0x7fff},{name:"prg_rom",lo:0x8000,hi:0xffff}],
-        c64:       [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x200,hi:0x9fff},{name:"basic_rom",lo:0xa000,hi:0xbfff},{name:"io",lo:0xd000,hi:0xdfff},{name:"kernal",lo:0xe000,hi:0xffff}],
-        atari7800: [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x1800,hi:0x27ff},{name:"cart_rom",lo:0x4000,hi:0xffff}],
-        lynx:      [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x200,hi:0xfbff},{name:"hw_regs",lo:0xfc00,hi:0xffff}],
-        // PC Engine (cc65 pce target): ZP + 8KB work RAM at $2200 (the pce.cfg
-        // MAIN segment), HuCard ROM mapped high. The HuC6280 stack lives in the
-        // $21xx page via the MPR mapping.
-        pce:       [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x2100,hi:0x21ff},{name:"system_ram",lo:0x2200,hi:0x3fff},{name:"hucard_rom",lo:0xe000,hi:0xffff}],
-        // Z80 family (SDCC + sdld .map). Cartridge ROM in the low half, work RAM high.
-        gb:        [{name:"rom",lo:0,hi:0x7fff},{name:"vram",lo:0x8000,hi:0x9fff},{name:"cart_ram",lo:0xa000,hi:0xbfff},{name:"work_ram",lo:0xc000,hi:0xdfff},{name:"oam",lo:0xfe00,hi:0xfe9f},{name:"io_hram",lo:0xff00,hi:0xffff}],
-        gbc:       [{name:"rom",lo:0,hi:0x7fff},{name:"vram",lo:0x8000,hi:0x9fff},{name:"cart_ram",lo:0xa000,hi:0xbfff},{name:"work_ram",lo:0xc000,hi:0xdfff},{name:"oam",lo:0xfe00,hi:0xfe9f},{name:"io_hram",lo:0xff00,hi:0xffff}],
-        sms:       [{name:"rom",lo:0,hi:0xbfff},{name:"work_ram",lo:0xc000,hi:0xdfff},{name:"ram_mirror",lo:0xe000,hi:0xffff}],
-        gg:        [{name:"rom",lo:0,hi:0xbfff},{name:"work_ram",lo:0xc000,hi:0xdfff},{name:"ram_mirror",lo:0xe000,hi:0xffff}],
-        // MSX cartridge: BIOS low, cart at $4000-$BFFF, work RAM $C000-$FFFF.
-        msx:       [{name:"bios",lo:0,hi:0x3fff},{name:"cart_rom",lo:0x4000,hi:0xbfff},{name:"work_ram",lo:0xc000,hi:0xffff}],
-        // Genesis (m68k-elf GNU ld map): ROM low, work-RAM mirror at $E0FF0000
-        // (= the emulator's `system_ram`, offset = low 16 bits of the symbol addr).
-        genesis:   [{name:"rom",lo:0,hi:0x3fffff},{name:"work_ram_mirror",lo:0xe0ff0000,hi:0xe0ffffff}],
-      };
-
       // Parse symbols from whichever format was supplied (auto-detects sdld vs GNU ld).
       const { format, symbols: all } = await loadSymbolList({ dbg, map });
 
-      const regions = (platform && regionsByPlatform[platform]) || [];
+      const regions = (platform && REGIONS_BY_PLATFORM[platform]) || [];
       const labelFor = (addr) => {
         for (const r of regions) {
           if (addr >= r.lo && addr <= r.hi) return r.name;
@@ -358,8 +439,12 @@ function registerSymbolsTool(server, z) {
     "(GB/GBC/SMS/GG/MSX) vs GNU ld `.map` (Genesis/m68k, the `mapText`/`symbols` field). So resolve/lookup/map/list " +
     "cover 11 platforms (those listed). The 'addr' op is broader — it parses ANY sdld/ld65-VICE/GNU-ld map text, so it " +
     "also reaches dasm (Atari 2600) and GBA/ARM.\n" +
-    "OP CHEAT-SHEET: resolve {dbg|map, name}; lookup {dbg|map, address}; map {dbg|map, platform?}; list {dbg|map, max?}; " +
-    "addr {pc, symbolsText|symbolsPath}.\n" +
+    "**CHEAP PATH (no map in context): pass `dbgPath`/`mapPath` — an absolute path to the .dbg/.map that " +
+    "build({output:'romWithDebug'}) wrote (the `dbgPath`/`mapPath` it returned). The SERVER reads it; you get back " +
+    "JUST {address,hex,region?,ramOffset?} without the 30-60KB map ever entering your context.** (Or skip this tool " +
+    "entirely: build({resolveSymbols:[...]}) resolves names off the fresh map in one round trip.)\n" +
+    "OP CHEAT-SHEET: resolve {dbg|map|dbgPath|mapPath, name, platform?}; lookup {dbg|map|dbgPath|mapPath, address}; " +
+    "map {dbg|map|dbgPath|mapPath, platform?}; list {dbg|map|dbgPath|mapPath, max?}; addr {pc, symbolsText|symbolsPath}.\n" +
     "'resolve' (name→address): resolve a C global, then memory({op:'read'}) it for headless assertions. " +
     "**GENESIS: a work-RAM symbol comes back with `ramOffset` (the low 16 bits) + a `readHint` — read it via " +
     "memory({op:'read', region:'system_ram', offset:ramOffset}).** cc65 C symbols become '_score' in the .dbg (the " +
@@ -375,25 +460,31 @@ function registerSymbolsTool(server, z) {
     "(`al XXXX .name`, cc65/dasm).",
     {
       op: z.enum(["resolve", "lookup", "map", "list", "addr"]).describe("resolve name→addr; lookup addr→sym; map = layout by region; list all; addr = PC→nearest symbol."),
-      dbg: z.string().optional().describe("op=resolve/lookup/list/map: cc65 .dbg text from build({output:'romWithDebug'}) (NES/C64/Atari7800/Lynx/PCE). Pass this OR `map`."),
-      map: z.string().optional().describe("op=resolve/lookup/list/map: .map text (build's `mapText`/`symbols`) — auto-detects sdld (GB/GBC/SMS/GG/MSX) vs GNU ld (Genesis/m68k). Pass this OR `dbg`."),
+      dbg: z.string().optional().describe("op=resolve/lookup/list/map: cc65 .dbg text from build({output:'romWithDebug'}) (NES/C64/Atari7800/Lynx/PCE). Pass this OR `map`/`dbgPath`/`mapPath`."),
+      map: z.string().optional().describe("op=resolve/lookup/list/map: .map text (build's `mapText`/`symbols`) — auto-detects sdld (GB/GBC/SMS/GG/MSX) vs GNU ld (Genesis/m68k). Pass this OR `dbg`/`dbgPath`/`mapPath`."),
+      dbgPath: z.string().optional().describe("op=resolve/lookup/list/map: ABSOLUTE path to a cc65 .dbg on disk (the `dbgPath` build({output:'romWithDebug'}) returned). Server reads it — the map never enters your context. Inline `dbg` wins if both passed."),
+      mapPath: z.string().optional().describe("op=resolve/lookup/list/map: ABSOLUTE path to a .map on disk (the `mapPath` build({output:'romWithDebug'}) returned; sdld or GNU ld, auto-detected). Server reads it — the map never enters your context. Inline `map` wins if both passed."),
       name: z.string().optional().describe("op=resolve: symbol name (C name; no leading underscore needed — both spellings tried)."),
       address: z.number().int().min(0).optional().describe("op=lookup: address whose enclosing symbol to find."),
       max: z.number().int().min(1).max(10000).default(200).describe("op=list: max symbols to return (default 200)."),
-      platform: z.string().optional().describe("op=map: platform id — adds per-platform region labels (incl. genesis work-RAM mirror)."),
+      platform: z.string().optional().describe("op=map (region labels) / op=resolve (adds a `region` field to the result) — platform id (incl. genesis work-RAM mirror)."),
       // addr
       pc: z.number().int().min(0).max(0xFFFFFF).optional().describe("op=addr: CPU address to look up (e.g. 0x01A7)."),
       symbolsText: z.string().optional().describe("op=addr: inline .map/.sym text (build's `symbols`). Takes precedence over symbolsPath."),
       symbolsPath: z.string().optional().describe("op=addr: path to a .map/.sym file (used only if symbolsText absent)."),
     },
     safeTool(async (args) => {
-      switch (args.op) {
-        case "resolve": return jsonContent(await resolveSymbolCore(args));
-        case "lookup":  return jsonContent(await lookupAddressCore(args));
-        case "map":     return jsonContent(await getMemoryMapCore(args));
-        case "list":    return jsonContent(await listSymbolsCore(args));
-        case "addr":    return jsonContent(await addressToSymbolCore(args));
-        default: throw new Error(`symbols: unknown op '${args.op}'`);
+      // dbgPath/mapPath → read the .dbg/.map TEXT off disk so resolve/lookup/map/
+      // list work without the agent ever loading the map into context. (addr has
+      // its own symbolsPath handling.)
+      const a = args.op === "addr" ? args : { ...args, ...(await loadDebugSource(args)) };
+      switch (a.op) {
+        case "resolve": return jsonContent(await resolveSymbolCore(a));
+        case "lookup":  return jsonContent(await lookupAddressCore(a));
+        case "map":     return jsonContent(await getMemoryMapCore(a));
+        case "list":    return jsonContent(await listSymbolsCore(a));
+        case "addr":    return jsonContent(await addressToSymbolCore(a));
+        default: throw new Error(`symbols: unknown op '${a.op}'`);
       }
     }),
   );

package/src/mcp/tools/tile-inspect.js

@@ -277,7 +277,7 @@ export function registerTileInspectTools(server, z, sessionKey) {
             if (!args.platform) throw new Error("tiles({op:'png'}) with `path`: `platform` is required for file extraction.");
             return await extractSpriteSheetCore({ ...args, count: args.count || 256 }, sessionKey);
           }
-          return await inspectPatternTilesCore(args);
+          return await inspectPatternTilesCore(args, sessionKey);
         }
         case "preview": {
           const r = await previewTileArtCore({ ...args, sessionKey });

package/src/mcp/tools/toolchain.js

@@ -691,9 +691,9 @@ export function registerToolchainTools(server, z, sessionKey) {
     "Compile/assemble source for a target platform; one tool keyed by `output`.\n" +
     "ON FAILURE (ok:false): READ `issues[]` FIRST — it's the structured error list ({file,line,col,severity,message,stage}) and usually names the exact line to fix. Only fall back to the raw `log` if `issues[]` is empty. Don't guess or rebuild blindly before reading it.\n" +
     "• output:'rom' (default) — assemble or compile `source` (single) / `sources` ({name:contents}) / `sourcePath` / `sourcesPaths`. Returns the ROM (path by default; `inline:true` for binaryBase64) + build log. **`binaryIncludes`/`binaryIncludePaths` (base64/path CHR-ROM, music blobs for `.incbin`) — WITHOUT them no game with external assets builds.** `includes`/`includePaths` for `.include`d text. `linkerConfig` (cc65; NES preset 'chr-ram-runtime' RECOMMENDED). `crt0`/`crt0Path`/`codeLoc`/`dataLoc` (SDCC). `runtime`/`maxmod`/`rebuildSdk` (GBA/Genesis SDK). **`lint:'strict'` fails the build (stage:'lint', no binary) if the pre-flight SDCC crash-pattern scan flags anything (e.g. the uint8 loop-bound trap); 'advisory' (default) just lists hits in issues[].** **`includeSymbols:true` returns the .map text inline on a PLAIN rom build — distinct from output:'romWithDebug' which writes .dbg/.map FILES.** Language is inferred from extension/content — usually OMIT `language`.\n" +
-    "• output:'romWithDebug' — like 'rom' but also emits linker debug info for the `symbols` tool: cc65 → `.dbg`, SDCC → sdld `.map`, Genesis m68k → GNU ld map (find where a RAM var landed). DEFAULT writes ROM + debug file + log to disk (`outputPath` required unless `inline:true`).\n" +
+    "• output:'romWithDebug' — like 'rom' but also emits linker debug info for the `symbols` tool: cc65 → `.dbg`, SDCC → sdld `.map`, Genesis m68k → GNU ld map (find where a RAM var landed). DEFAULT writes ROM + debug file + log to disk (`outputPath` required unless `inline:true`). **`resolveSymbols:['grid','score']` folds those names' addresses ({resolvedSymbols:{grid:{address,hex,region?,ramOffset?}}}) straight into the result — the cheap way to a WRAM variable's address without loading the whole map (or round-tripping it through `symbols`).**\n" +
     "• output:'run' — BUILD + LOAD + RUN + SCREENSHOT in one round trip — the fastest iteration loop. Same build args; runs `frames` frames and returns the screenshot INLINE. `holdInputs` holds controller state; `screenshotPath` writes the PNG to disk instead; `projectName` titles the playtest window.\n" +
-    "• output:'project' — build a project DIRECTORY (`path`) without re-passing the file manifest each call. Entry point is `main.c` (C/SGDK Genesis, GBA, cc65/SDCC C) OR `main.s`/`main.asm` (asm). Every `.c`/`.s`/`.asm` in the dir is a translation unit (linked together), every `.h`/`.inc` an include, and `.bin/.chr/.pcm/.brr/.vgm/...` become binaryIncludes (for `.incbin`). Iterate an on-disk project by re-calling with just `{path, platform}`.",
+    "• output:'project' — build a project DIRECTORY (`path`) without re-passing the file manifest each call. Entry point is `main.c` (C/SGDK Genesis, GBA, cc65/SDCC C) OR `main.s`/`main.asm` (asm). Every `.c`/`.s`/`.asm` in the dir is a translation unit (linked together), every `.h`/`.inc` an include, and `.bin/.chr/.pcm/.brr/.vgm/...` become binaryIncludes (for `.incbin`). Iterate an on-disk project by re-calling with just `{path, platform}`. **This is the no-boilerplate path for a scaffold({op:'project'}) dir: the per-platform recipe auto-supplies the crt0 + load address — GB/GBC default `gb_crt0.s` + `codeLoc:0x150` (don't hand-pass them!), MSX routes `msx_crt0.s` + `codeLoc:0x4010`, SMS/GG auto-inject their bundled crt0, NES applies the chr-ram-runtime preset. PREFER this over re-passing `crt0Path`/`codeLoc` to output:'rom' for a scaffolded project.**",
     {
       output: z.enum(["rom", "romWithDebug", "run", "project"])
         .describe("rom=produce a ROM (default); romWithDebug=ROM + .dbg/.map debug files; run=build+load+run+screenshot; project=build a project directory."),
@@ -727,6 +727,7 @@ export function registerToolchainTools(server, z, sessionKey) {
       rebuildSdk: z.boolean().optional().describe("GBA + Genesis — rebuild the bundled SDK (libtonc/libgba/maxmod/SGDK) from vendored source instead of the prebuilt seed (~20-40s). Only if you edited SDK source (else an `sdkEditIgnored` warning fires)."),
       lint: z.enum(["advisory", "strict"]).default("advisory").describe("output:'rom' SDCC — 'advisory' (default, warnings in issues[]) or 'strict' (any lint warning fails the build with stage:'lint' before the compiler runs — the SDCC crash-pattern guard)."),
       includeSymbols: z.boolean().default(false).describe("output:'rom' — return the toolchain's symbol/map text inline (sdld .map / cc65 .sym). False = only symbolsBytes (call symbols/addressToSymbol to look up a PC). Maps can be 30+ KB."),
+      resolveSymbols: z.array(z.string()).optional().describe("output:'romWithDebug' — resolve just these symbol NAMES (e.g. ['grid','score']) off the freshly-produced .dbg/.map and fold {resolvedSymbols:{grid:{address,hex,region?,ramOffset?}}} into the result. The CHEAP path to a WRAM variable's address: you get the addresses you asked for WITHOUT the 30-60KB map entering your context. Genesis work-RAM symbols come back with `ramOffset` for memory({region:'system_ram', offset}). Names that don't resolve are listed in `unresolvedSymbols`."),
       // run-only
       frames: z.number().int().min(1).max(100000).default(60).describe("output:'run' — frames to run before the screenshot (default 60)."),
       holdInputs: z.array(holdInputShape).max(2).optional().describe("output:'run' — per-port input state to hold during the run (index 0 = port 0)."),

package/src/mcp/tools/watch-memory.js

@@ -913,7 +913,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     },
     safeTool(async (args) => {
       switch (args.op) {
-        case "read":     return await getCPUStateCore(args);
+        case "read":     return await getCPUStateCore(args, sessionKey);
         case "setReg": {
           if (args.regId == null || args.value == null) throw new Error("cpu({op:'setReg'}): `regId` and `value` are required.");
           return await cpuSetReg(args);
@@ -1001,7 +1001,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     "**CAVEAT: frame-level, not instruction-level (last value per frame); the sampled `pc` is a frame-boundary sample — for ISR-driven writes use breakpoint({on:'write', precision:'exact'}) for the real writer.**\n" +
     "• on:'range' — DISCOVERY: log EVERY instruction that reads or writes ANYWHERE in [start,end]. The fix for 'I don't know which PC touches this'. Returns {pc,address,value}[] + the actionable distinctPCs. (Ring-buffered: `truncated:true` if it overflows.) `fromState`/`fromStatePath` restores a savestate FIRST so the trace runs from a known moment (jump to the boss, then see what writes HP) — deterministic + repeatable.\n" +
     "• on:'pc' — DISCOVERY (coverage trace): record every DISTINCT PC executed within [start,end] — 'what code runs here?'. Log execution in the bank where you suspect the renderer lives during the moment it draws, then disassemble the PCs. Also takes `fromState`/`fromStatePath` to trace from a restored moment.\n" +
-    "• on:'dma' — GENESIS ONLY: trace mem→VDP DMAs (the answer to 'this name/portrait/logo is a pre-rendered bitmap DMA'd into VRAM — WHERE in ROM?', which on:'write' can't catch). `precision:'exact'` (default) logs every mem→VDP DMA with its VRAM DESTINATION + ROM SOURCE + length (filter by `vramDest`±`destWindow`; `dedupe` collapses the per-frame refresh; `sourceFilter:'rom-only'` drops RAM→VRAM noise; catches a same-frame second DMA). `precision:'sampled'` is the cheap frame-sampled source-register read (may miss two DMAs in one frame, dest-agnostic). On non-Genesis cores returns `notSupported`.",
+    "• on:'dma' — GENESIS ONLY: trace mem→VDP DMAs (the answer to 'this name/portrait/logo is a pre-rendered bitmap DMA'd into VRAM — WHERE in ROM?', which on:'write' can't catch). `precision:'exact'` (default) logs every mem→VDP DMA with its VRAM DESTINATION + ROM SOURCE + length (filter by `vramDest`±`destWindow`; `dedupe` collapses the per-frame refresh; `sourceFilter:'rom-only'` drops RAM→VRAM noise; catches a same-frame second DMA). `precision:'sampled'` is the cheap frame-sampled source-register read (may miss two DMAs in one frame, dest-agnostic). `perFrame:true` switches to FEEL/PERF MODE: a per-frame timeline of VDP-DMA WORK ({frame,dmas,bytes,romBytes,ramBytes} + peakFrame + `spikes`) — the cheap 'why does horizontal movement feel choppy?' diagnostic (a per-frame byte spike = too much VDP work in the loop, e.g. a tilemap rewrite). On non-Genesis cores returns `notSupported`.",
     {
       on: z.enum(["mem", "range", "pc", "dma"])
         .describe("mem=watch a RAM byte/ranges for value changes over frames (the power tool); range=log every read/write PC in [start,end]; pc=coverage trace of distinct PCs executed in [start,end]; dma=Genesis-only mem→VDP DMA source/dest trace."),
@@ -1028,7 +1028,8 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       limit: z.number().int().min(1).max(4000).default(200).describe("on:'range'/'pc' — max events/PCs returned (default 200; full count is in `total`)."),
       outputPath: z.string().optional().describe("on:'mem' — stream every filter-passing event to this path as NDJSON + return a compact summary. Use for long watches so the full log never enters your context."),
       // on:'dma' (Genesis VDP DMA trace)
-      precision: z.enum(["exact", "sampled"]).default("exact").describe("on:'dma' — exact=per-DMA core log with VRAM dest + ROM source (catches same-frame DMAs); sampled=frame-sampled source-register read (cheaper, may miss two DMAs in one frame, dest-agnostic)."),
+      perFrame: z.boolean().default(false).describe("on:'dma' — FEEL/PERF MODE: instead of one aggregated source/dest log, return a PER-FRAME timeline of VDP-DMA WORK [{frame, dmas, bytes, romBytes, ramBytes}] + peakFrame/peakBytes. This is the cheap 'why does horizontal movement feel choppy?' answer — a frame whose DMA bytes spike (esp. romBytes, an asset re-upload) is doing too much VDP work in the loop (the classic 'I rewrote a tilemap every frame' bug). A smooth hardware-scroll loop shows a low, flat curve. Combine with `pressDuring` to correlate the spike with input (hold RIGHT, see which frames burst). No core rebuild — re-arms the DMA counter each frame."),
+      precision: z.enum(["exact", "sampled"]).default("exact").describe("on:'dma' — exact=per-DMA core log with VRAM dest + ROM source (catches same-frame DMAs); sampled=frame-sampled source-register read (cheaper, may miss two DMAs in one frame, dest-agnostic). Ignored when perFrame:true."),
       vramDest: z.number().int().min(0).optional().describe("on:'dma' precision:'exact' — keep only DMAs whose VRAM destination is within ±`destWindow` of this address."),
       destWindow: z.number().int().min(0).default(0x40).describe("on:'dma' precision:'exact' — match window around vramDest (default 64 bytes ≈ 1 tile)."),
       dedupe: z.boolean().default(true).describe("on:'dma' precision:'exact' — collapse identical DMAs (same dest+source+length+code) to one entry with an `occurrences` count (default on)."),
@@ -1057,6 +1058,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         }
         case "dma": {
           const a = { ...args, frames: args.frames ?? 120, limit: args.limit ?? 200 };
+          if (a.perFrame) return await dmaPerFrame(a);
           if (a.precision === "sampled") {
             return await traceVramSourceCore({ ...a, romPreviewBytes: a.romPreviewBytes || 16, sessionKey });
           }
@@ -1132,7 +1134,57 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
           (totalDistinct > limit ? `Showing ${out.length}/${totalDistinct} distinct — raise limit or narrow vramDest.` : ""),
       }), host);
   }
-  // dmaExact + traceVramSourceCore are reached via watch({on:'dma'}) above —
-  // dmaTrace was folded into `watch` (it's a log-all VDP-DMA trace, same family
-  // as on:'mem'/'range'/'pc'), so there's no separate top-level tool.
+
+  // watch({on:'dma', perFrame:true}) — FEEL/PERF timeline. Steps frame-by-frame,
+  // re-arming the DMA counter each frame (the core resets on arm), and reports
+  // VDP-DMA WORK per frame. The cheap, no-core-rebuild "why is movement choppy?"
+  // diagnostic: a frame whose bytes (esp. romBytes — an asset re-upload) spike is
+  // doing too much VDP work in the loop. Optionally driven by `pressDuring` so the
+  // spike correlates with input. See genesis MENTAL_MODEL "feel trap".
+  async function dmaPerFrame({ frames = 120, pressDuring, maxFrames = 600 }) {
+    const host = getHost(sessionKey);
+    if (!host.dmaWatchSupported || !host.dmaWatchSupported()) {
+      return jsonContent({ notSupported: true, frames: [],
+        note: "watch({on:'dma', perFrame}) is Genesis-only (VDP DMA). On other cores there's no VDP DMA to count." });
+    }
+    const n = Math.min(frames, maxFrames);
+    const presses = (pressDuring ?? []).slice().sort((a, b) => a.frame - b.frame);
+    const pressDriver = makePressDriver(host, presses);
+    const r = host.watchDmaPerFrame(n, (i) => pressDriver.applyForFrame(i));
+    pressDriver.finish();
+    const tl = r.frames;
+    // Compact: only KEEP frames that did any DMA, plus always the peak. A flat
+    // hardware-scroll loop is mostly the steady SAT refresh — summarise it.
+    const nonZero = tl.filter((f) => f.bytes > 0);
+    const avgBytes = tl.length ? Math.round(r.totalBytes / tl.length) : 0;
+    const peak = tl[r.peakFrame] || null;
+    // A spike heuristic: a frame whose bytes are >3x the average AND carries ROM
+    // source bytes (an asset upload, not the steady RAM refresh) is the smell.
+    const spikes = tl.filter((f) => avgBytes > 0 && f.bytes > avgBytes * 3 && f.romBytes > 0)
+                     .map((f) => ({ frame: f.frame, bytes: f.bytes, romBytes: f.romBytes, dmas: f.dmas }));
+    // Cap the returned per-frame rows so a long run doesn't flood context.
+    const rows = nonZero.slice(0, 240);
+    return attachObserverFrame(jsonContent({
+      perFrame: true,
+      framesRun: n,
+      totalDmas: r.totalDmas,
+      totalBytes: r.totalBytes,
+      avgBytesPerFrame: avgBytes,
+      peakFrame: r.peakFrame,
+      peakBytes: r.peakBytes,
+      ...(peak ? { peakDetail: peak } : {}),
+      framesWithDma: nonZero.length,
+      ...(spikes.length ? { spikes } : {}),
+      ...(presses.length ? { pressesApplied: pressDriver.applied() } : {}),
+      timeline: rows,
+      ...(nonZero.length > rows.length ? { timelineTruncated: nonZero.length } : {}),
+      note: "Per-frame VDP-DMA WORK. `bytes` = VRAM/CRAM/VSRAM bytes DMA'd that frame; `romBytes` = bytes copied FROM cart ROM (an asset upload), `ramBytes` = the steady RAM→VRAM sprite/scroll refresh. " +
+        "A smooth hardware-scroll loop shows a low, flat curve (mostly ramBytes ≈ the SAT refresh). " +
+        "A `spikes` entry (bytes >3x avg WITH romBytes) 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 instead. " +
+        "Hold input with `pressDuring` to see which input bursts. CEILING: this counts DMA bytes; CPU writes to the VDP data port (VDP_setTileMapXY without DMA) are NOT DMA and aren't counted here — those need a core-side VDP-write hook (future).",
+    }), host);
+  }
+  // dmaExact + dmaPerFrame + traceVramSourceCore are reached via watch({on:'dma'})
+  // above — dmaTrace was folded into `watch` (it's a log-all VDP-DMA trace, same
+  // family as on:'mem'/'range'/'pc'), so there's no separate top-level tool.
 }

package/src/platforms/gb/MENTAL_MODEL.md

@@ -72,6 +72,21 @@ check these first. All five have shipped fixes in the bundled runtime
    If you use the bundled `gb_crt0.s` you're good; if you bring your
    own, make sure gsinit zeros `_DATA`.
 
+6. **Don't poke a hardcoded `$C0xx` WRAM pointer for game state — it
+   overlaps your statics.** SDCC links the C runtime's data + BSS (every
+   `static` global: your PRNG seed, your grids, your scores) at the BOTTOM
+   of WRAM starting `$C000`. A `volatile uint8_t *board = (uint8_t*)0xC000;`
+   then scribbles right over `static uint32_t rng = ...;` et al. Symptom
+   looks exactly like an SDCC *codegen* bug — e.g. a 32-bit xorshift PRNG
+   that "degenerates" so every roll is identical (it's not miscompiling;
+   its seed is being clobbered). **Use a `static` array and let the linker
+   place it** (`static uint8_t board[78]; board[i]=p;`), or, if you must
+   hardcode, put scratch at `$C200`+ and confirm with the linker map
+   (`build({includeSymbols:true})` → check `s__DATA`/`s__BSS`; your scratch
+   must start above the end of `_BSS`). Full write-up + the
+   "is-it-really-a-miscompile" repro in
+   `lib/c/SDCC_GOTCHAS.md` § "sm83 codegen traps in plain game logic".
+
 ## Memory map you actually care about
 
 ```
@@ -81,6 +96,9 @@ $8000-$97FF  VRAM tile data — 384 tiles × 16 bytes (CGB: dual-banked, 768 tot
 $9800-$9FFF  VRAM BG maps + CGB attribute map (in bank 1)
 $A000-$BFFF  Cart RAM (mappers only; not present in 32 KB ROM-only carts)
 $C000-$DFFF  WRAM (8 KB) — your variables, your stack
+             ⚠ statics start at $C000 (rng/grids/scores live here): NEVER
+               hardcode a $C0xx pointer for game state — use a `static`
+               array; for fixed scratch use $C200+ (see footgun #6).
 $FE00-$FE9F  OAM (40 sprites × 4 bytes) — written via DMA
 $FF00       JOYP — joypad I/O
 $FF40-$FF4B I/O registers — LCDC, BGP, OBP0, OBP1, SCY, SCX, etc.

package/src/platforms/gb/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/gbc/MENTAL_MODEL.md

@@ -47,6 +47,19 @@ the same wall.
    `s__DATA` for `l__DATA` bytes; bring-your-own crt0 should do the
    same.
 
+6. **Don't poke a hardcoded `$C0xx` WRAM pointer for game state — it
+   overlaps your statics.** SDCC links the C runtime's data + BSS (every
+   `static` global: your PRNG seed, your grids, your scores) at the BOTTOM
+   of WRAM starting `$C000`. A `volatile uint8_t *board = (uint8_t*)0xC000;`
+   then scribbles right over `static uint32_t rng = ...;` et al. Symptom
+   looks exactly like an SDCC *codegen* bug — e.g. a 32-bit xorshift PRNG
+   that "degenerates" so every roll is identical (its seed is being
+   clobbered, not miscompiled). **Use a `static` array and let the linker
+   place it** (`static uint8_t board[78]; board[i]=p;`), or hardcode at
+   `$C200`+ and confirm with the linker map (`build({includeSymbols:true})`
+   → check `s__DATA`/`s__BSS`). Full write-up + repro in
+   `lib/c/SDCC_GOTCHAS.md` § "sm83 codegen traps in plain game logic".
+
 - **Two VRAM banks** (switched via VBK at $FF4F) — bank 0 holds tile
   pattern data, bank 1 holds per-tile BG attributes (palette index,
   H/V flip, priority, tile bank).