romdevtools 0.21.0 → 0.22.0

package/src/mcp/tools/toolchain.js

@@ -2,17 +2,36 @@ import { mkdir, mkdtemp, writeFile, readdir, readFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { TOOLCHAINS } from "../../toolchains/registry.js";
-import { buildForPlatform } from "../../toolchains/index.js";
+import { buildForPlatform, rankIssues } from "../../toolchains/index.js";
 import { resolveLinkerConfig } from "../../toolchains/cc65/preset-resolver.js";
+import { parseBuildLog } from "../../toolchains/parse-errors.js";
 import { inesHeaderSource, charsSource, nromFlatCfg } from "../../toolchains/cc65/ines.js";
 import { resolveCore } from "../../cores/registry.js";
 import { resetHost, getDisclosure } from "../state.js";
 import { PLATFORM_VIRTUAL_EXT } from "../../host/LibretroHost.js";
-import { imageContent, jsonContent, safeTool, textContent } from "../util.js";
+import { imageContent, jsonContent, safeTool } from "../util.js";
 import { isPlaytestRunning } from "./playtest.js";
 import { buildSourceWithDebugCore } from "./symbols.js";
 import { log as serverLog } from "../log.js";
 
+// crt0 (the per-platform startup stub) is assembled BEHIND the user's build.
+// When it fails the agent gets a raw assembler log — route it through the same
+// parser build() uses so the error leads with the first file:line: message
+// (the issues[]-style surfacing), full log appended for fallback.
+function crt0AssemblyError(log) {
+  const issues = parseBuildLog(log ?? "");
+  const first = issues.find((i) => i.severity === "error") ?? issues[0];
+  const headline = first
+    ? `${first.file ? first.file + ":" : ""}${first.line ? first.line + ": " : ""}${first.message}`
+    : "no structured diagnostic found";
+  return new Error(
+    `crt0 (startup stub) assembly failed: ${headline}` +
+    (issues.length > 1 ? ` (+${issues.length - 1} more)` : "") +
+    `\nThis is the bundled startup code, not your source — if it's the only error, ` +
+    `report it. Full assembler log:\n${log ?? ""}`,
+  );
+}
+
 // Record a build outcome into the /log ring buffer so a failed build's stage +
 // error tail are diagnosable later (the request was already traced; this adds
 // the RESULT). On failure we keep a chunk of the build log; on success just the
@@ -318,7 +337,7 @@ export function registerToolchainTools(server, z, sessionKey) {
         const { runSdasgb, runSdasz80 } = await import("../../toolchains/sdcc/sdcc.js");
         const asm = isSm83 ? await runSdasgb({ source: crt0 }) : await runSdasz80({ source: crt0 });
         if (!asm.rel) {
-          throw new Error(`crt0 assembly failed:\n${asm.log}`);
+          throw crt0AssemblyError(asm.log);
         }
         crt0Rel = asm.rel;
       }
@@ -400,7 +419,7 @@ export function registerToolchainTools(server, z, sessionKey) {
         ...(result.stage ? { stage: result.stage } : {}),
         ...(result.sdkEditIgnored ? { sdkEditIgnored: result.sdkEditIgnored } : {}),
         ...(await logField(result.log, inline, logSibling, result.ok)),
-        issues: result.issues ?? [],
+        issues: rankIssues(result.issues ?? []),
         ...(showHint ? { hint: showHint } : {}),
       };
       // When a build failed on a specific TU (multi-source SDCC build),
@@ -538,7 +557,7 @@ export function registerToolchainTools(server, z, sessionKey) {
         const { runSdasgb, runSdasz80 } = await import("../../toolchains/sdcc/sdcc.js");
         const asm = isSm83 ? await runSdasgb({ source: crt0 }) : await runSdasz80({ source: crt0 });
         if (!asm.rel) {
-          throw new Error(`crt0 assembly failed:\n${asm.log}`);
+          throw crt0AssemblyError(asm.log);
         }
         crt0Rel2 = asm.rel;
       }
@@ -569,7 +588,7 @@ export function registerToolchainTools(server, z, sessionKey) {
           toolchain: build.toolchain,
           exitCode: build.exitCode,
           ...(await logField(build.log, false, null)),
-          issues: build.issues ?? [],
+          issues: rankIssues(build.issues ?? []),
         });
       }
 
@@ -625,7 +644,7 @@ export function registerToolchainTools(server, z, sessionKey) {
         // Surface lint/build issues even on successful runs so agents see
         // linter warnings BEFORE the next iteration (was: runSource silently
         // ran with warnings, agent missed them, hit the crash 100 functions later).
-        ...((build.issues ?? []).length > 0 ? { issues: build.issues } : {}),
+        ...((build.issues ?? []).length > 0 ? { issues: rankIssues(build.issues) } : {}),
         ...(hint ? { hint } : {}),
       };
 
@@ -670,6 +689,7 @@ export function registerToolchainTools(server, z, sessionKey) {
   server.tool(
     "build",
     "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:'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" +
@@ -925,7 +945,7 @@ export async function buildProjectCore({ path: projPath, platform, outputPath })
     const isSm83 = platform === "gb" || platform === "gbc";
     const { runSdasgb, runSdasz80 } = await import("../../toolchains/sdcc/sdcc.js");
     const asm = isSm83 ? await runSdasgb({ source: crt0 }) : await runSdasz80({ source: crt0 });
-    if (!asm.rel) throw new Error(`crt0 assembly failed:\n${asm.log}`);
+    if (!asm.rel) throw crt0AssemblyError(asm.log);
     crt0Rel = asm.rel;
   }
 
@@ -964,6 +984,6 @@ export async function buildProjectCore({ path: projPath, platform, outputPath })
     romLayout: describeRomLayout(platform, result.binary),
     ...(result.stage ? { stage: result.stage } : {}),
     ...(await logField(result.log, false, logSibling, result.ok)),
-    issues: result.issues ?? [],
+    issues: rankIssues(result.issues ?? []),
   });
 }

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

@@ -97,9 +97,18 @@ export function makePressDriver(host, presses) {
   let applied = 0;          // how many scheduled presses actually got a frame
   let lastSet = null;       // last setInput payload we pushed (to avoid churn)
   const platform = host.status?.platform;
+  // When NO pressDuring schedule is given, the driver must NOT touch input at
+  // all — it leaves whatever persistent state input({op:'set'}) established in
+  // place, so a watch/breakpoint inherits the held pad exactly like
+  // frame({op:'step'}) does. (Previously applyForFrame(0) pushed an empty
+  // [{},{}] payload on the first frame, silently neutralizing a held Right+A —
+  // the v0.16.0 movement-analysis bug.) A non-empty schedule still OWNS the
+  // pad (deterministic capture): it drives the buttons and releases on finish.
+  const driven = presses.length > 0;
   return {
     applied: () => applied,
     applyForFrame(i) {
+      if (!driven) return;   // inherit persistent input({op:'set'}) state
       // Buttons whose [frame, frame+holdFrames) window covers frame i.
       const held = presses.filter((p) => i >= p.frame && i < p.frame + (p.holdFrames ?? 2));
       // Build a 2-port setInput payload from the held buttons.
@@ -114,6 +123,7 @@ export function makePressDriver(host, presses) {
       for (const p of held) { if (p.frame === i) applied++; }
     },
     finish() {
+      if (!driven) return;   // we never touched input; leave it as the caller set it
       if (lastSet !== null && lastSet !== "[{},{}]") host.setInput({ ports: [{}, {}] });
     },
   };
@@ -134,7 +144,7 @@ const MEMORY_REGIONS = /** @type {[string, ...string[]]} */ (Object.keys(MemoryR
 // with WHY, instead of burning all maxFrames on a meaningless miss.
 function makeAbortGuard(host, abortIf) {
   const specs = Array.isArray(abortIf) ? abortIf : [];
-  const watched = specs.map((s, i) => {
+  const watched = specs.map((s, _i) => {
     const region = s.region ?? "system_ram";
     const offset = s.offset ?? 0;
     let before;
@@ -751,7 +761,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         button: z.string(),
         port: z.number().int().min(0).max(3).default(0),
         holdFrames: z.number().int().min(1).default(2),
-      })).optional().describe("Schedule input while waiting (drive the game to the state that triggers the condition)."),
+      })).optional().describe("Schedule input while waiting (drive the game to the state that triggers the condition). If OMITTED, this run inherits whatever input({op:'set'}) last held — same as frame({op:'step'}). If GIVEN, the schedule OWNS the pad for the whole run (a prior input({op:'set'}) is ignored); use it to drive the watched window itself."),
       abortIf: z.array(z.object({
         region: z.enum(MEMORY_REGIONS).optional().describe("memory region (default system_ram)"),
         offset: z.number().int().min(0).describe("byte offset within the region"),
@@ -1030,7 +1040,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         button: z.string(),
         port: z.number().int().min(0).max(3).default(0),
         holdFrames: z.number().int().min(1).default(2),
-      })).optional().describe("Schedule input while watching (drive the game to the state that touches the watched bytes/range, or uploads the graphic for on:'dma')."),
+      })).optional().describe("Schedule input while watching (drive the game to the state that touches the watched bytes/range, or uploads the graphic for on:'dma'). If OMITTED, this run inherits whatever input({op:'set'}) last held — same as frame({op:'step'}). If GIVEN, the schedule OWNS the pad for the whole run (a prior input({op:'set'}) is ignored)."),
       fromState: z.string().optional().describe("on:'range'/'pc' — restore an in-memory savestate SLOT (from state({op:'save', name})) BEFORE tracing, so the log runs from a known moment (jump to the boss fight, then see what writes HP). Deterministic + repeatable."),
       fromStatePath: z.string().optional().describe("on:'range'/'pc' — like fromState but restore from a savestate FILE on disk (state({op:'save', path})). Relative path resolves against the loaded ROM's dir."),
     },

package/src/platforms/_guides/ROMHACKING_PLAYBOOK.md

@@ -218,6 +218,40 @@ whole attract sequence each time. `input({op:'set'})`'s `requested` echo is what
 not proof the pad saw it — verify via the held-buttons RAM byte or a state
 transition.
 
+## 6b. Iterative measurement — boot to gameplay ONCE, reload per run
+
+When you run many measurements on the same starting state (frame-by-frame
+velocity tables, per-input timing, A/B trials), do NOT replay the
+`loadMedia → step to title → press start → step into the level` preamble every
+time — that intro is often hundreds of frames and 4+ calls, and you pay it on
+every iteration. Boot once, snapshot, and reload the snapshot per run:
+
+```
+loadMedia({platform, path, cheats})         // cheats survive the save state
+frame({op:'step', frames:180})              // title renders
+input({op:'press', button:'start'})
+frame({op:'step', frames:300})              // into gameplay
+state({op:'save', name:'ready'})            // <-- the reusable starting point
+
+// then per measurement:
+state({op:'load', name:'ready'})            // 1 call instead of the whole boot
+... drive + watch ...
+```
+
+A save state captures applied cheats and the exact RAM/PPU state, so every run
+starts byte-identical — *more* repeatable than re-booting, not just cheaper. A
+named slot (`name`) lives in memory for the session; a `path` persists to disk
+across sessions. If a task says "restart before each run", a state reload
+satisfies that intent far cheaper than a fresh `loadMedia`.
+
+**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`. (This is the documented contract; the schemas of `watch`/`breakpoint`
+and `input({op:'set'})` state it too.)
+
 ---
 
 ## Quick reference

package/src/platforms/atari2600/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # Atari 2600 / VCS — troubleshooting
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 When something's broken. Read MENTAL_MODEL.md first
 (via `platform({op:'doc', platform:"atari2600", name:"mental_model"})`).
 

package/src/platforms/atari7800/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # Atari 7800 — troubleshooting
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 When something's broken. Read MENTAL_MODEL.md first
 (via `platform({op:'doc', platform:"atari7800", name:"mental_model"})`)
 for the "what's going on" version — the 7800 is the architectural outlier

package/src/platforms/c64/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # Commodore 64 — troubleshooting
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 When something's broken. Read MENTAL_MODEL.md first
 (via `platform({op:'doc', platform:"c64", name:"mental_model"})`).
 

package/src/platforms/c64/d64.js

@@ -222,7 +222,6 @@ export function readDirectory(d64) {
     const nextS = img[base + 1];
     // 8 entries per sector, 32 bytes each, first entry at +2 then every +32.
     for (let e = 0; e < 8; e++) {
-      const eb = base + 2 + e * 32 - (e === 0 ? 0 : 0);
       const entryBase = base + (e === 0 ? 2 : 2 + e * 32);
       const typeByte = img[entryBase + 0];
       if ((typeByte & 0x0f) === 0 && typeByte === 0) continue; // empty slot

package/src/platforms/c64/sid.js

@@ -29,8 +29,6 @@
 //   $D41B     voice 3 OSC3 readback
 //   $D41C     voice 3 ENV3 readback
 
-const WAVEFORMS = ["none", "triangle", "sawtooth", "tri+saw", "pulse", "tri+pulse", "saw+pulse", "tri+saw+pulse", "noise"];
-
 function decodeControl(byte) {
   // Decode the waveform field (top 4 bits) as a name where possible.
   const wfBits = (byte >> 4) & 0x0F;

package/src/platforms/common/metasprite-adapters.js

@@ -203,7 +203,7 @@ export async function gbAdapter(host, platform) {
 //  palette line (CRAM entries 16-31). Tile data base from VDP reg 6.
 // =====================================================================
 export async function smsAdapter(host, platform) {
-  const { decodeSmsTile, decodeSmsVdpRegs, decodeSmsCram, decodeGgCram, snapshotPalette } = await import("../sms/vdp.js");
+  const { decodeSmsTile, decodeSmsVdpRegs, snapshotPalette } = await import("../sms/vdp.js");
   const vramRegion = platform === "gg" ? "gg_vram" : "sms_vram";
   const vram = host.readMemory(vramRegion, 0, 0x4000);
   const regs = host.readMemory("sms_vdp_regs", 0, 16);

package/src/platforms/common/metasprite-codegen.js

@@ -75,7 +75,7 @@ static u16 ${v}_draw(u16 firstSlot, s16 x, s16 y, u16 baseTile) {
 }
 
 // ---- SNES (PVSnesLib oamSet-style) ----
-function emitSnes(v, layout, tiles, palette) {
+function emitSnes(v, layout, tiles, _palette) {
   const pieces = layout.pieces.map((p) => {
     // PVSnesLib oamSet: size 0=8x8/16x16 small/large per OBSEL — we expose
     // wPx/hPx and let the user pick the OBSEL pair; flip bits in attr.
@@ -99,7 +99,7 @@ const unsigned short ${v}_piece_count = ${layout.pieces.length};
 }
 
 // ---- NES (shadow-OAM bytes) ----
-function emitNes(v, layout, tiles, palette) {
+function emitNes(v, layout, tiles, _palette) {
   // NES draw = write 4 OAM bytes per cell (y, tile, attr, x). We emit pieces
   // as (x,y,tile,attr) so the user copies them into shadow OAM at their base.
   const cells = [];
@@ -127,7 +127,7 @@ const unsigned char ${v}_cell_count = ${cells.length};
 }
 
 // ---- GB/GBC (shadow-OAM bytes) ----
-function emitGb(v, layout, tiles, palette) {
+function emitGb(v, layout, tiles, _palette) {
   const cells = [];
   for (const p of layout.pieces) {
     for (let r = 0; r < p.hTiles; r++) {

package/src/platforms/common/registers.js

@@ -235,14 +235,16 @@ export const ATARI7800_REGISTERS = {
   0x2E: "P3C1",      0x2F: "P3C2",      0x30: "P3C3",
   0x32: "P4C1",      0x33: "P4C2",      0x34: "P4C3",
   0x36: "P5C1",      0x37: "P5C2",      0x38: "P5C3",
-  0x3A: "P6C1",      0x3B: "P6C2",      0x3C: "P6C3",
+  0x3A: "P6C1",      0x3B: "P6C2",
+  // $3C is BOTH the MARIA control reg (CTRL) and P6C3 depending on the
+  // reference's naming convention — a JS object holds one value per key, so
+  // name it for both rather than silently dropping one.
+  0x3C: "CTRL/P6C3",
   0x3E: "P7C1",      0x3F: "P7C2",      // P7C3 lives at $40 in some refs
   // DPP (display-list pointer) lives at $84/$85
   0x84: "DPPH",      0x85: "DPPL",
   0x87: "CHARBASE",
   0x88: "OFFSET",
-  // MARIA control reg
-  0x3C: "CTRL",      // overlaps with P6C3 — convention varies; tag both
   // RIOT (6532) regs at $280
   0x0280: "SWCHA",   0x0281: "SWACNT",  0x0282: "SWCHB",   0x0283: "SWBCNT",
   0x0284: "INTIM",

package/src/platforms/gb/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # Game Boy / Game Boy Color — symptom → fix
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 Stuck? Find your symptom below; each entry has the 1-line diagnosis and
 the MCP tool call that confirms it. **Run the diagnosis BEFORE you start
 bisecting the C source** — most "GB doesn't render" bugs are one of these

package/src/platforms/gb/lib/c/gb_runtime.c

@@ -127,10 +127,10 @@ void oam_dma_init_hram(void) {
     0x20, 0xFD,             /* jr nz, -3    ─┘  spin while a != 0 */
     0xC9,                   /* ret */
   };
-  uint8_t i;
-  for (i = 0; i < sizeof(stub); i++) {
-    HRAM_DMA_STUB[i] = stub[i];
-  }
+  /* Use the pointer-walk memcpy_vram (not an indexed dst[i]=src[i] loop):
+   * SDCC sm83 miscompiles the indexed form into a high-pointer like
+   * HRAM_DMA_STUB ($FF80). memcpy_vram does *d++=*s++, which is safe. */
+  memcpy_vram(HRAM_DMA_STUB, stub, sizeof(stub));
 }
 
 /* OAM DMA — copy 160 bytes from `src` to OAM ($FE00-$FE9F) via the

package/src/platforms/gba/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # Game Boy Advance — troubleshooting
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 When something's broken. Read MENTAL_MODEL.md first
 (via `platform({op:'doc', platform:"gba", name:"mental_model"})`).
 

package/src/platforms/gbc/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # Game Boy Color — troubleshooting
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 Read MENTAL_MODEL.md first (`platform({op:'doc', platform:"gbc",
 name:"mental_model"})`). Most DMG-era troubleshooting from GB applies
 unchanged — including the **two SDCC sm83 codegen footguns below**, which are

package/src/platforms/gbc/lib/c/gb_runtime.c

@@ -127,10 +127,10 @@ void oam_dma_init_hram(void) {
     0x20, 0xFD,             /* jr nz, -3    ─┘  spin while a != 0 */
     0xC9,                   /* ret */
   };
-  uint8_t i;
-  for (i = 0; i < sizeof(stub); i++) {
-    HRAM_DMA_STUB[i] = stub[i];
-  }
+  /* Use the pointer-walk memcpy_vram (not an indexed dst[i]=src[i] loop):
+   * SDCC sm83 miscompiles the indexed form into a high-pointer like
+   * HRAM_DMA_STUB ($FF80). memcpy_vram does *d++=*s++, which is safe. */
+  memcpy_vram(HRAM_DMA_STUB, stub, sizeof(stub));
 }
 
 /* OAM DMA — copy 160 bytes from `src` to OAM ($FE00-$FE9F) via the

package/src/platforms/genesis/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # Sega Genesis / Mega Drive — troubleshooting
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 When something's broken. Read MENTAL_MODEL.md first for the "what's
 going on" version (via `platform({op:'doc', platform:"genesis", name:"mental_model"})`).
 

package/src/platforms/gg/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # Game Gear — troubleshooting
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 When something's broken. Read MENTAL_MODEL.md first
 (`platform({op:'doc', platform:"gg", name:"mental_model"})`).
 

package/src/platforms/lynx/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # Atari Lynx — troubleshooting
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 Read MENTAL_MODEL.md first (`platform({op:'doc', platform:"lynx",
 name:"mental_model"})`).
 

package/src/platforms/msx/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # MSX — troubleshooting (symptom → cause → fix)
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 Read this when something's broken. For the "how it works" overview, read
 MENTAL_MODEL.md first.
 

package/src/platforms/nes/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # NES — symptom → fix
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 Find your symptom below; each entry has the 1-line diagnosis + the
 MCP tool call that confirms it. Run these BEFORE you start bisecting
 your C source.

package/src/platforms/nes/image-to-tilemap.js

@@ -275,6 +275,9 @@ export function nesImageToTilemap(args) {
   // unique 8×8 patterns exist naturally. Returning the unmerged result
   // gives the caller a chance to retry; just be aware nametable indices
   // > 255 will wrap on hardware.
+  // Permanently disabled (see note above) but kept as documentation of the
+  // rejected greedy-merge approach.
+  // eslint-disable-next-line no-constant-condition, no-constant-binary-expression
   if (false && dedup && tileList.length > maxTiles) {
     const tileDist = (a, b) => {
       let d = 0;

package/src/platforms/nes/lib/asm/famitone2.s

@@ -8,7 +8,11 @@
 
 ;settings, uncomment or put them into your main program; the latter makes possible updates easier
 
-FT_BASE_ADR		= $0300	;page in the RAM used for FT2 variables, should be $xx00
+FT_BASE_ADR		= $0700	;page in the RAM used for FT2 variables, should be $xx00
+				;romdev: pinned to $0700 (the SNDRAM page reserved in
+				;chr-ram-runtime.cfg). $0300 — the cc65 default — overlaps
+				;the C BSS/DATA region, so FT2's per-frame writes would
+				;clobber _ppuctrl_value / NMI state and stall rendering.
 FT_TEMP			= $fd	;3 bytes in zeropage used by the library as a scratchpad
 FT_DPCM_OFF		= $fc00	;$c000..$ffc0, 64-byte steps
 FT_SFX_STREAMS	= 1		;number of sound effects played at once, 1..4

package/src/platforms/pce/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # PC Engine — troubleshooting (symptom → cause → fix)
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 Read this when something's broken. For the "how it works" overview, read
 MENTAL_MODEL.md first.
 

package/src/platforms/sms/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # Sega Master System / Game Gear — troubleshooting
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 When something's broken. Read MENTAL_MODEL.md first for the
 "what's going on" version (via `platform({op:'doc', platform:"sms", name:"mental_model"})`).
 

package/src/platforms/snes/TROUBLESHOOTING.md

@@ -1,5 +1,11 @@
 # Super Nintendo / Super Famicom — troubleshooting
 
+> **A build failed? Read `issues[]` FIRST.** Every build/compile call returns
+> `issues: [{file, line, col, severity, message, stage}]` — the structured error
+> list. It almost always names the exact line to fix. Read that before matching a
+> symptom below or touching your source. Fall back to the raw `log` only if
+> `issues[]` is empty but `ok:false`.
+
 When something's broken. Read MENTAL_MODEL.md first for the "what's
 going on" version (via `platform({op:'doc', platform:"snes", name:"mental_model"})`).
 

package/src/platforms/snes/brr.js

@@ -23,8 +23,6 @@
 // lowest error and use that. The first block of any sample MUST use
 // filter 0 (no other choice has valid p1/p2 history).
 
-const BRR_BUF_DECODE = 16;  // samples per block
-
 /** snes9x CLAMP16: saturate to int16. */
 function clamp16(io) {
   // The macro: if int16(io) != io, io = (io >> 31) ^ 0x7FFF

package/src/playtest/playtest.js

@@ -17,9 +17,6 @@ import { createRequire } from "node:module";
 const execFileAsync = promisify(execFile);
 const require = createRequire(import.meta.url);
 
-// One-pixel solid-black RGBA buffer; we stretch it across the letterbox
-// bars each frame so they don't smear with leftover pixels.
-const BLACK_PIXEL = Buffer.from([0, 0, 0, 0xFF]);
 
 /**
  * Choose a default window title from the loaded host. Prefers the loaded
@@ -796,10 +793,6 @@ export async function playtest(args) {
   };
 }
 
-function sleep(ms) {
-  return new Promise((r) => setTimeout(r, ms));
-}
-
 function bitToName(bit) {
   return ({
     0: "b", 1: "y", 2: "select", 3: "start",

package/src/toolchains/asar/asar.js

@@ -260,15 +260,6 @@ function lorom(fileStart, fileEnd) {
   return `${fmt(bankStart, offStart)}..${fmt(bankEnd, offEnd)} (spans banks)`;
 }
 
-function ensureDir(FS, dir) {
-  const parts = dir.split("/").filter(Boolean);
-  let cur = "";
-  for (const p of parts) {
-    cur += "/" + p;
-    try { FS.mkdir(cur); } catch {}
-  }
-}
-
 // Static analyzer for known asar landmines. Runs before the WASM call so
 // we can return a helpful error instead of letting asar abort silently.
 // Returns null when source looks clean, or a string with the diagnostic.