romdevtools 0.14.0 → 0.16.0

package/src/mcp/tools/toolchain.js

@@ -68,6 +68,7 @@ const LOG_TAIL = 1200;
 // stays visible. Left intact on failure (timing can matter when diagnosing a
 // hang/OOM). The full untrimmed log is still written to logPath when spilled.
 export function denoiseSuccessLog(log) {
+  if (typeof log !== "string") return log ?? "";
   const lines = log.split("\n");
   const kept = [];
   let inTiming = false;
@@ -293,7 +294,7 @@ export function registerToolchainTools(server, z, sessionKey) {
         codeLoc,
         dataLoc,
       });
-      logBuildResult("buildSource", platform, result);
+      logBuildResult("build:rom", platform, result);
       // lint:"strict" — if any lint warning fired, fail the build with
       // stage:"lint" so the agent must fix patterns before iterating.
       // We mutate the result rather than re-running because the lint
@@ -396,11 +397,40 @@ export function registerToolchainTools(server, z, sessionKey) {
       return jsonContent(payload);
   }
 
-  async function runSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, runtime, maxmod, rebuildSdk, crt0, crt0Path, codeLoc, dataLoc, linkerConfig, frames = 60, holdInputs, screenshotPath, projectName }) {
+  async function runSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, runtime, maxmod, rebuildSdk, crt0, crt0Path, codeLoc, dataLoc, linkerConfig, path: projPath, frames = 60, holdInputs, screenshotPath, projectName }) {
       const { buildForPlatform } = await import("../../toolchains/index.js");
       const resolved = resolveCore(platform);
       if (!resolved) throw new Error(`no core available for platform '${platform}'`);
 
+      // PROJECT-DIR run: `build({output:'run', path})` with no explicit sources →
+      // read the scaffolded dir via the per-platform recipe (same as
+      // output:'project'), then run it. This is the documented "iterate on a dir"
+      // happy path; without it, output:'run' + path errored ("requires source").
+      const noExplicitSources = source == null && sourcePath == null && sources == null && sourcesPaths == null;
+      if (projPath && noExplicitSources) {
+        const r = await readProjectDir(projPath, platform);
+        includes = { ...(includes ?? {}), ...r.includes };
+        binaryIncludes = { ...(binaryIncludes ?? {}), ...r.binaryIncludes };
+        if (r.crt0 != null) crt0 = r.crt0;
+        if (r.codeLoc != null) codeLoc = r.codeLoc;
+        if (r.linkerConfig != null && linkerConfig == null) linkerConfig = r.linkerConfig;
+        if (r.runtime != null && runtime == null) runtime = r.runtime;
+        if (r.maxmod != null && maxmod == null) maxmod = r.maxmod;
+        // Single-source toolchains (dasm/atari2600, vasm/asm) need `source`, not
+        // a `sources` map. Collapse a lone source so those targets build via the
+        // dir path too. (resolveLinkerConfig support-sources, if any, force the
+        // map form below.)
+        const srcNames = Object.keys(r.sources);
+        if (srcNames.length === 1 && r.crt0 == null && r.linkerConfig == null) {
+          // Leave `source` null and set sourcePath — runSourceImpl reads it +
+          // derives sourceName (extension) for language inference. Single-source
+          // targets (dasm/vasm) require this form, not a `sources` map.
+          sourcePath = path.join(projPath, srcNames[0]);
+        } else {
+          sources = r.sources;
+        }
+      }
+
       if (source != null && sourcePath != null) {
         throw new Error("build({output:'run'}): pass either `source` OR `sourcePath`, not both.");
       }
@@ -474,7 +504,7 @@ export function registerToolchainTools(server, z, sessionKey) {
         codeLoc,
         dataLoc,
       });
-      logBuildResult("runSource", platform, build);
+      logBuildResult("build:run", platform, build);
       if (!build.ok || !build.binary) {
         // runSource builds in-memory (no ROM path), so a large failure log
         // has nowhere to land — gate it to a tail + size rather than dumping
@@ -521,10 +551,10 @@ export function registerToolchainTools(server, z, sessionKey) {
       if (!isPlaytestRunning(sessionKey) && !playtestHintGiven.has(sessionKey)) {
         playtestHintGiven.add(sessionKey);
         hint = "No playtest window is open. If a human is watching, consider " +
-               "`loadCategory({category:\"show\"})` then `playtest()` so they can " +
-               "play this ROM live while you keep iterating with runSource " +
-               "(rebuilds update the live game in place). Skip if this session " +
-               "is headless (CI / batch / automated).";
+               "`playtest({op:\"open\"})` so they can play this ROM live while you " +
+               "keep iterating with build({output:\"run\"}) (rebuilds update the " +
+               "live game in place). Skip if this session is headless " +
+               "(CI / batch / automated).";
       }
 
       const summary = {
@@ -628,7 +658,18 @@ export function registerToolchainTools(server, z, sessionKey) {
     },
     safeTool(async (args) => {
       switch (args.output) {
-        case "rom":          return await buildSourceImpl(args);
+        case "rom": {
+          // `build({output:'rom', path})` (a project dir, no explicit sources) is
+          // the natural "build my scaffolded dir to a ROM file" call. Route it to
+          // the dir builder (same recipe as output:'project'/'run') — otherwise it
+          // fell into buildSourceImpl with no source and crashed on an undefined
+          // log. With path AND explicit sources, the sources win (manual build).
+          if (args.path && args.source == null && args.sources == null &&
+              args.sourcePath == null && args.sourcesPaths == null) {
+            return await buildProjectImpl(args);
+          }
+          return await buildSourceImpl(args);
+        }
         case "run":          return await runSourceImpl(args);
         case "project": {
           if (!args.path) throw new Error("build({output:'project'}): `path` (the project directory) is required.");
@@ -648,13 +689,107 @@ export function registerToolchainTools(server, z, sessionKey) {
  * a jsonContent payload (the router calls it via safeTool, which turns a throw —
  * e.g. no entry point — into an {isError:true} result).
  */
-export async function buildProjectCore({ path: projPath, platform, outputPath }) {
+/**
+ * Per-platform recipe for building a SCAFFOLDED project directory. Given the
+ * platform + the list of filenames present, decide which file (if any) is a crt0
+ * that must be routed via `crt0`/`codeLoc` (not linked as a plain TU), which
+ * linker preset to apply, which SDK runtime to select, and which files to SKIP
+ * (preset-supplied crt0s, SDK intermediates). This is the single source of truth
+ * that makes `build({output:'project'|'run', path})` match what the scaffold
+ * README's hand-written build call does.
+ * @param {string} platform
+ * @param {string[]} names  filenames present in the project dir
+ */
+export function projectBuildRecipe(platform, names) {
+  const has = (n) => names.includes(n);
+  /** @type {{crt0File:string|null, codeLoc:number|undefined, linkerConfig:string|undefined, runtime:string|undefined, maxmod:boolean|undefined, skip:Set<string>, includeAsC:Set<string>}} */
+  const r = { crt0File: null, codeLoc: undefined, linkerConfig: undefined, runtime: undefined, maxmod: undefined, skip: new Set(), includeAsC: new Set() };
+
+  // Reference/upstream sources ship for grepping, not compiling (e.g. GB
+  // music_demo's hUGEDriver.upstream.asm — the .c port is what builds). Skip
+  // any *.upstream.* on every platform.
+  for (const n of names) if (/\.upstream\./i.test(n)) r.skip.add(n);
+
+  if (platform === "gb" || platform === "gbc") {
+    // GB/GBC ship gb_crt0.s — it MUST go via crt0+codeLoc:0x150, never as a
+    // source (SDCC emits its own gsinit → "Multiple definition of gsinit").
+    if (has("gb_crt0.s")) { r.crt0File = "gb_crt0.s"; r.codeLoc = 0x150; }
+  } else if (platform === "nes") {
+    // A SCAFFOLDED NES project ships nes_runtime.c + a crt0 + a .cfg and needs
+    // the chr-ram-runtime preset (it defines the OAM/CHARS segments + a NMI with
+    // OAM-DMA; without it: "Missing memory area 'OAM'"). The preset SUPPLIES its
+    // own crt0 + expects nes_runtime.c, so skip the scaffold's crt0/.cfg (the
+    // preset replaces them). A BARE hand-rolled NES dir (no scaffold crt0/.cfg)
+    // is left alone — forcing the preset there would demand runtime symbols it
+    // doesn't have. Detect "scaffolded" by the presence of a crt0 or .cfg.
+    const looksScaffolded = names.some((n) => /crt0.*\.s$/i.test(n) || /\.cfg$/i.test(n));
+    if (looksScaffolded) {
+      r.linkerConfig = "chr-ram-runtime";
+      for (const n of names) {
+        if (/crt0.*\.s$/i.test(n) || /\.cfg$/i.test(n)) r.skip.add(n);
+      }
+    }
+  } else if (platform === "sms" || platform === "gg") {
+    // SMS/GG auto-inject their bundled crt0 inside buildForPlatform — so the
+    // scaffold's own *_crt0.s would be a DUPLICATE. Skip it.
+    for (const n of names) if (/_crt0\.s$/i.test(n)) r.skip.add(n);
+  } else if (platform === "genesis" || platform === "megadrive" || platform === "md") {
+    // SGDK supplies sega startup + rom header. The scaffold dir may contain
+    // generated intermediates (sega.s, sega.preprocessed.s, rom_header.*, and an
+    // out/ build dir) that must NOT be recompiled — sega.preprocessed.s refs a
+    // missing out/rom_header.bin and aborts the build.
+    for (const n of names) {
+      if (/^sega(\.preprocessed)?\.s$/i.test(n) || /^rom_header\./i.test(n) || /\.preprocessed\.s$/i.test(n)) r.skip.add(n);
+    }
+  } else if (platform === "snes") {
+    const asmEntry = has("main.asm") && !has("main.c"); // asar asm template
+    if (asmEntry) {
+      // SNES asar asm template: main.asm `.include`s its siblings
+      // (lorom_header/reset_init/cgram_upload.asm). asar takes ONE source +
+      // resolves .include from the includes mount — so route non-main .asm as
+      // includes, leaving main.asm the single source.
+      for (const n of names) {
+        if (/\.asm$/i.test(n) && n !== "main.asm") r.includeAsC.add(n);
+      }
+    } else {
+      // SNES (PVSnesLib/tcc) C scaffolds combine C via `#include "snes_sfx.c"`
+      // from main.c — a single TU. A non-main .c is an INCLUDE (tcc must find it
+      // for the #include), NOT a separate source TU (which would double-define).
+      // (data.asm / snes_sfx_data.asm stay real wla sources, compiled + linked.)
+      for (const n of names) {
+        if (/\.c$/i.test(n) && n !== "main.c") r.includeAsC.add(n);
+      }
+    }
+    // The SPC700 audio driver sources (spc_driver.asm, apu_blob.asm) are 65816-
+    // INCOMPATIBLE SPC700 asm used OFFLINE to regenerate apu_blob.bin — the
+    // scaffold already ships the built .bin (incbin'd by snes_sfx_data.asm).
+    // Compiling them as 65816 sources fails ("Cannot process spc700"). Skip them.
+    for (const n of names) {
+      if (n === "spc_driver.asm" || n === "apu_blob.asm") r.skip.add(n);
+    }
+  } else if (platform === "gba") {
+    // GBA: default runtime is libtonc; a soundbank.bin means the maxmod path.
+    // The libgba-vs-libtonc choice needs the source CONTENT (which header it
+    // includes), so buildProjectCore refines r.runtime after reading main.c.
+    r.runtime = "libtonc";
+    if (has("soundbank.bin")) r.maxmod = true;
+  }
+  return r;
+}
+
+/**
+ * Read a scaffolded project DIRECTORY into the build inputs, applying the
+ * per-platform recipe (crt0 routing, linker preset, runtime, skip-list) and
+ * the GBA runtime content-sniff. The SINGLE source of truth shared by
+ * build({output:'project'}) and build({output:'run', path}) — so the two paths
+ * can never drift. Returns crt0 as RAW source text (callers assemble it).
+ * @param {string} projPath
+ * @param {string} platform
+ */
+export async function readProjectDir(projPath, platform) {
   const entries = await readdir(projPath, { withFileTypes: true });
   const files = entries.filter((e) => e.isFile());
 
-  // Entry point: a C project uses main.c (SGDK/Genesis, GBA, cc65/SDCC C); an
-  // asm project uses main.s / main.asm. Pick whichever exists — so the SAME
-  // dir-build works for C/SGDK Genesis projects, not just asm/cc65.
   const hasC = files.some((f) => f.name === "main.c");
   const hasAsm = files.some((f) => f.name === "main.s" || f.name === "main.asm");
   if (!hasC && !hasAsm) {
@@ -664,40 +799,81 @@ export async function buildProjectCore({ path: projPath, platform, outputPath })
     );
   }
 
-  // Every .c/.s/.asm is its own translation unit (linked together — cc65 routes
-  // .c→cc65 + .s→ca65; SDCC/SGDK/GBA compile every .c). Every .h/.inc is an
-  // include (NOT a TU). Binary assets become binaryIncludes so .incbin survives.
+  // Per-platform PROJECT RECIPE — see projectBuildRecipe. Globbing every file as
+  // a source is what broke GB (gsinit double-def), NES (no OAM/CHARS), Genesis
+  // (sega.preprocessed.s). The recipe routes crt0 / preset / runtime / skips so
+  // the dir build matches the hand-written build({output:'run'}) call.
+  const recipe = projectBuildRecipe(platform, files.map((f) => f.name));
+
   /** @type {Record<string,string>} */ const sources = {};
   /** @type {Record<string,string>} */ const includes = {};
   /** @type {Record<string,string>} */ const binaryIncludes = {};
+  let crt0 = null;
   for (const f of files) {
     const n = f.name;
+    if (recipe.skip.has(n)) continue;
+    if (recipe.crt0File === n) { crt0 = await readFile(path.join(projPath, n), "utf-8"); continue; }
+    // includeAsC: a .c that's `#include`d by another TU (e.g. SNES main.c
+    // includes snes_sfx.c) — make it an include, NOT a separate source TU.
+    if (recipe.includeAsC.has(n)) { includes[n] = await readFile(path.join(projPath, n), "utf-8"); continue; }
     if (/\.(c|s|asm)$/i.test(n))    sources[n] = await readFile(path.join(projPath, n), "utf-8");
     else if (/\.(h|inc)$/i.test(n)) includes[n] = await readFile(path.join(projPath, n), "utf-8");
-    else if (/\.(bin|chr|pcm|brr|vgm|xgm|nsf|raw|pal)$/i.test(n)) {
+    else if (/\.(bin|chr|pcm|brr|vgm|vgz|xgm|xgc|xgm2|esf|tfi|eif|nsf|raw|pal|map|tmx|spc|wav|gbs)$/i.test(n)) {
+      // Any binary asset an .incbin might reference. (.xgc = compiled XGM2 blob,
+      // .vgz/.esf/etc = music driver inputs.) Missing one = "file not found: X".
       binaryIncludes[n] = (await readFile(path.join(projPath, n))).toString("base64");
     }
   }
 
-  // Route through resolveLinkerConfig like build({output:'rom'}) so cc65 presets
-  // + support sources still apply for a dir-built cc65 project.
-  const { cfg: resolvedLinkerConfig, supportSources } = await resolveLinkerConfig(platform, undefined);
+  // GBA runtime refinement: libgba if the entry includes <gba.h>, else the
+  // libtonc default the recipe set.
+  let runtime = recipe.runtime;
+  if (platform === "gba" && sources["main.c"] && /#\s*include\s*[<"]gba\.h[>"]/.test(sources["main.c"])) {
+    runtime = "libgba";
+  }
+
+  return { sources, includes, binaryIncludes, crt0, codeLoc: recipe.codeLoc, linkerConfig: recipe.linkerConfig, runtime, maxmod: recipe.maxmod };
+}
+
+export async function buildProjectCore({ path: projPath, platform, outputPath }) {
+  const { sources, includes, binaryIncludes, crt0, codeLoc, linkerConfig, runtime, maxmod } = await readProjectDir(projPath, platform);
+
+  // Linker preset: the recipe names it (e.g. NES 'chr-ram-runtime', which ships
+  // the OAM/CHARS segments + its own crt0). resolveLinkerConfig also returns any
+  // preset support sources (the preset crt0) — those merge into the sources.
+  const { cfg: resolvedLinkerConfig, supportSources } = await resolveLinkerConfig(platform, linkerConfig);
   const mergedSources = Object.keys(supportSources).length ? { ...supportSources, ...sources } : sources;
 
+  // Assemble a routed crt0 (SDCC sm83/z80) into a .rel, exactly like the
+  // output:'rom'/'run' path — passing it as `crt0` (NOT a source TU) is what
+  // avoids the gsinit double-definition on GB/GBC.
+  let crt0Rel;
+  if (crt0) {
+    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}`);
+    crt0Rel = asm.rel;
+  }
+
   // Single-source toolchains (dasm/atari2600, vasm/asm) take `source`, not the
   // multi-TU `sources` map. When the dir has exactly one source file and no
   // preset support sources, pass it as `source` so those targets still build
   // (the original asm-only buildProject behavior).
   const srcNames = Object.keys(sources);
-  const singleSource = srcNames.length === 1 && Object.keys(supportSources).length === 0;
+  const singleSource = srcNames.length === 1 && Object.keys(supportSources).length === 0 && !crt0Rel;
   const result = await buildForPlatform({
     platform,
+    runtime,
+    maxmod,
     ...(singleSource
       ? { source: sources[srcNames[0]], sourceName: srcNames[0] }
       : { sources: mergedSources }),
     includes: Object.keys(includes).length ? includes : undefined,
     binaryIncludes: Object.keys(binaryIncludes).length ? binaryIncludes : undefined,
     linkerConfig: resolvedLinkerConfig,
+    crt0: crt0Rel,
+    codeLoc,
   });
   if (outputPath && result.binary) {
     await mkdir(path.dirname(outputPath), { recursive: true });

package/src/observer/livestream.html

@@ -28,6 +28,11 @@
   #status { font-size: 11px; color: #888; margin-left: auto; }
   #status.connected { color: #4caf50; }
   #status.disconnected { color: #f44336; }
+  #log-session {
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: 12px; color: #6cb6ff; padding: 2px 0 8px;
+    word-break: break-all;
+  }
   #tabs {
     display: flex; flex-wrap: wrap; gap: 4px;
     padding: 6px 12px; background: #111; border-bottom: 1px solid #333;
@@ -189,6 +194,7 @@
   </div>
   <div id="log-pane">
     <h2>Activity log</h2>
+    <div id="log-session"></div>
     <div id="log-list"></div>
   </div>
 </div>
@@ -201,6 +207,7 @@
   const tabsEl = document.getElementById("tabs");
   const imageListEl = document.getElementById("image-list");
   const logListEl = document.getElementById("log-list");
+  const logSessionEl = document.getElementById("log-session");
   const emptyEl = document.getElementById("empty");
 
   // Per-session state.
@@ -351,10 +358,22 @@
       tab.className = "tab" + (k === activeSessionKey ? " active" : "")
         + (!s.connected ? " disconnected" : "");
       tab.onclick = () => selectTab(k);
-      tab.innerHTML = `<span>${k.slice(0, 8)}</span>`
-        + (s.unseen > 0 && k !== activeSessionKey
-            ? ` <span class="badge">${s.unseen}</span>` : "");
-      if (!s.connected) tab.title = "session closed";
+      // Show the FULL session id — agents pick descriptive ids (e.g.
+      // "scaffold-nes-platformer") and truncating to 8 chars collapsed distinct
+      // tasks into identical-looking tabs ("scaffold" × N). Cap very long ids in
+      // the middle so the meaningful head+tail both show; full id in the tooltip.
+      const label = k.length > 28 ? k.slice(0, 18) + "…" + k.slice(-8) : k;
+      const labelSpan = document.createElement("span");
+      labelSpan.textContent = label;
+      tab.appendChild(labelSpan);
+      if (s.unseen > 0 && k !== activeSessionKey) {
+        const badge = document.createElement("span");
+        badge.className = "badge";
+        badge.textContent = String(s.unseen);
+        tab.appendChild(document.createTextNode(" "));
+        tab.appendChild(badge);
+      }
+      tab.title = s.connected ? k : `${k} (session closed)`;
       tabsEl.appendChild(tab);
     }
   }
@@ -504,6 +523,17 @@
 
   function renderLog() {
     logListEl.innerHTML = "";
+    // Full session id above the log — the tab label can be middle-truncated, so
+    // this is the one place that always shows the EXACT id you're looking at.
+    if (logSessionEl) {
+      if (activeSessionKey) {
+        logSessionEl.textContent = "session: " + activeSessionKey;
+        logSessionEl.style.display = "";
+      } else {
+        logSessionEl.textContent = "";
+        logSessionEl.style.display = "none";
+      }
+    }
     if (!activeSessionKey) return;
     const s = sessions.get(activeSessionKey);
     // Newest first — easier to scan when working live.

package/src/platforms/gg/MENTAL_MODEL.md

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

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

@@ -3,15 +3,17 @@
  * Writes the 11 mode-4 registers to a sane baseline:
  *   display OFF, vblank IRQ off, 192-line mode 4, name table at $3800,
  *   BG tile data at $0000, sprite attr table at $3F00, sprite tile data
- *   at $0000 (R6=0xFB → SA13 clear → tiles read from $0000-$1FFF). Call
+ *   at $2000 (R6=0xFF → SA13 set → tiles read from $2000-$3FFF). Call
  *   once after reset before uploading palette/tiles/map.
  *
- * Footgun: many SMS/GG references say "R6=0xFB → sprite tiles at $2000"
- * which is BACKWARDS. R6 bit 2 (the SA13 select) is CLEAR in 0xFB, so
- * sprite tiles read from $0000 (sharing the bank with BG tiles). To
- * separate sprite tiles to $2000, set R6 = 0xFF instead. The
- * sprites({op:'inspect'}) tool's spriteTileDataBase field will show you the
- * real address the VDP is reading from.
+ * Sprite-tile base: R6 bit 2 (SA13) selects $0000 (clear) vs $2000 (set).
+ * We default to R6=0xFF ($2000) because EVERY bundled scaffold uploads its
+ * sprite tiles to $2000 (gg_load_tiles(0x2000, ...)) — so the baseline must
+ * match what consumers do, or sprites read from the empty/BG bank and render
+ * invisible. (Many SMS/GG references say "R6=0xFB → $2000", which is backwards:
+ * 0xFB has SA13 CLEAR = $0000.) If you instead keep sprite tiles in the BG
+ * bank at $0000, set R6=0xFB. sprites({op:'inspect'}) → spriteTileDataBase
+ * shows the address the VDP is actually reading from.
  *
  * After loading assets, enable display by re-writing R1 with bit 6 set:
  *   gg_vdp_display_on();
@@ -33,7 +35,7 @@ void gg_vdp_init(void) {
     0xFF,  /* R3:  color table (ignored in M4) */
     0xFF,  /* R4:  BG tile data at $0000 */
     0xFF,  /* R5:  sprite attr table at $3F00 */
-    0xFB,  /* R6:  sprite tile data at $0000 (set 0xFF for $2000) */
+    0xFF,  /* R6:  sprite tile data at $2000 (SA13 set; scaffolds upload here) */
     0x00,  /* R7:  border = sprite palette entry 0 */
     0x00,  /* R8:  BG X scroll */
     0x00,  /* R9:  BG Y scroll */

package/src/platforms/msx/MENTAL_MODEL.md

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

package/src/platforms/nes/TROUBLESHOOTING.md

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

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

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

package/src/platforms/pce/MENTAL_MODEL.md

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

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

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

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

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

package/src/platforms/sms/MENTAL_MODEL.md

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