romdevtools 0.16.0 → 0.22.0

package/src/platforms/nes/MENTAL_MODEL.md

@@ -211,6 +211,21 @@ Build calls explicitly point at these files via `sourcesPaths` /
 `includePaths` + `linkerConfig: <contents of chr-ram-runtime.cfg>`. The
 project README shows the exact incantation.
 
+## Blank screen? Verify rendering before you guess (no vision needed)
+
+If the screen looks black/blank, don't iterate blind — call
+**`frame({op:'verify', frames:60})`**. One call fuses a framebuffer pixel scan
+with the live PPU registers and tells you `{verified:true|false|null, issues[]}`:
+- `renderDisabled` → PPUMASK has BG+sprites off (footgun, see below) — set
+  PPUMASK bits 3/4.
+- `blankScreen`/`nearlyBlank` but render IS enabled → the PPU is on but nothing's
+  in the nametable/OAM/palette: check the loop-order + OAM-DMA footguns below, and
+  read the raw regions (`memory({op:'read', region:'nes_nametables'/'nes_oam'/'nes_palette'})`).
+- `verified:null` (unsettled) → you haven't stepped a frame yet; step first.
+
+It won't false-fire on boot, and it costs zero image tokens. Use it as the first
+move whenever a change "did nothing" on screen.
+
 ## Five footguns to know before you start
 
 Read these BEFORE writing your game-loop. Each one cost a previous
@@ -304,14 +319,60 @@ incorrectly aligned."
     onChange:"reset", outputPath:...})` logs each note onset, or
     `recordSession({memorySamples:[{region:"nes_apu_regs",...}], sampleEvery:1,
     memoryOutputPath:...})` streams per-frame samples to disk.
-- Mapper support — only NROM-256 (32 KB PRG, no banks) is wired. For
-  MMC1/MMC3/UNROM you'll need a different linker config.
+- Mapper support — the homebrew presets target NROM (no PRG banking). For
+  MMC1/MMC3/UNROM you'll need a different linker config. (For *rebuilding* an
+  existing CHR-ROM NROM game byte-identical, see "Rebuilding a CHR-ROM NROM
+  image" below — `inesHeader` / the `chr-rom` preset / `disasm({target:'project'})`.)
 - IRQ — the IRQ vector returns. Most NES games use a custom IRQ
   handler for mid-frame scroll splits; you'll need to write that asm.
 - Multi-screen scrolling — the runtime sets one nametable; for big
   scrolling worlds you need to manage the nametable buffer + bank
   switching yourself.
 
+## Rebuilding a CHR-ROM NROM image (reverse-engineering)
+
+The homebrew presets above are CHR-**RAM** (the CPU uploads tiles at runtime).
+Most *commercial* games are CHR-**ROM**: an 8 KB (or more) bank of fixed tile
+data the PPU reads pattern tables from directly. When you rebuild a commercial
+game from its disassembly into a byte-identical `.nes`, you need the iNES
+header + the CHR-ROM blob + a linker config that concatenates HEADER + PRG +
+CHR. romdev has three ways to do this so you never hand-derive header bytes or
+write glue `.s`/`.cfg` files.
+
+**The iNES header** (16 bytes at the very start of a `.nes`): `4E 45 53 1A`
+("NES"+EOF), then byte 4 = PRG-ROM 16 KB bank count, byte 5 = CHR-ROM 8 KB bank
+count (**0 = CHR-RAM**), byte 6 = flags6 (bit0 mirroring 0=horizontal/1=vertical,
+bit1 battery, high nibble = mapper low nibble), byte 7 = flags7 (high nibble =
+mapper high nibble), bytes 8-15 = 0. NROM is mapper 0; NROM-128 = 1 PRG bank
+(maps at $C000, mirrored to $8000), NROM-256 = 2 PRG banks (maps at $8000).
+
+**1. `build({inesHeader:{...}})` — the parametric, no-glue path (recommended).**
+Pass `inesHeader: {prgBanks, chrBanks, mapper, mirroring}` and the build
+auto-emits the HEADER segment, wires your CHR blob (from `binaryIncludePaths`)
+into a CHARS segment, and uses a flat NROM `.cfg`. You supply only the PRG
+source(s) + the CHR blob:
+```
+build({ output:'rom', platform:'nes',
+        sourcesPaths:{ "prg.asm": "bank0.asm" },     // the PRG disassembly
+        binaryIncludePaths:{ "chr.bin": "chr.bin" }, // extracted CHR-ROM
+        inesHeader:{ prgBanks:2, chrBanks:1, mapper:0, mirroring:"vertical" } })
+```
+Mutually exclusive with `linkerConfig`. Works for any NROM (mapper 0, ≤2 PRG
+banks); for a banked mapper supply a linker `.cfg` that places each bank.
+
+**2. `linkerConfig:"chr-rom"` — for homebrew C that ships FIXED tile art.**
+A cc65-C preset (segment split + a CHARS segment in an 8 KB ROM2 bank). Put your
+tiles in `.segment "CHARS"` (`.incbin "tiles.chr"`) + pass the blob via
+`binaryIncludePaths`. It ships a companion crt0 with an 8 KB-CHR-ROM header. For
+other bank configs, prefer `inesHeader`.
+
+**3. `disasm({target:'project'})` — disassemble → rebuild, in two calls.**
+For NES it now extracts the CHR-ROM to `chr.bin`, writes a `rebuild.json` (the
+exact `build({inesHeader})` call, with absolute paths) and a `BUILD.md`. Feed
+`rebuild.json` straight back to `build` and you get a byte-identical ROM. This
+is the RE workhorse loop: `disasm({target:'project'})` → edit the `.asm` →
+rebuild → `diffRoms` to confirm your patch landed.
+
 ## When to drop to asm
 
 Game-loop in C is fine for ~80% of homebrew. Drop to asm when:

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/MENTAL_MODEL.md

@@ -12,10 +12,15 @@ romdev ships a **hardware helper library** (`src/platforms/pce/lib/c/`:
 `psg_tone()` instead of poking VDC/VCE registers by hand. cc65 has **no** sprite
 library, so this lib is how you get pixels on screen.
 
-The fastest way to a working game: **`scaffold({op:'project', platform: "pce", template:
-"sprite_move"})`** (also `music_sfx`, `catch_game`). It drops a complete,
-*building* project — a verified playable example + the helper lib + docs. Read
-the example's `main.c`, then change it. The examples live in `examples/pce/`.
+The fastest way to a working game: **`scaffold({op:'game', platform: "pce", genre:
+"shmup"})`** — or any of `platformer` / `puzzle` / `sports` / `racing`, the full
+genre set. For a smaller starting point use **`scaffold({op:'project', platform:
+"pce", template: "sprite_move"})`** (also `music_sfx`, `catch_game`). Either drops
+a complete, *building* project — a verified playable example + the helper lib +
+docs. Read the example's `main.c`, then change it. The examples live in
+`examples/pce/`. The genre scaffolds fill the BAT (32×32 virtual screen); the
+`platformer` smooth-scrolls the background via the VDC BXR (R7) register.
+**Gotcha:** `#include <stdint.h>` for int8/16/32_t — `pce.h` only typedefs u8/u16.
 
 ## CPU — HuC6280 (a 65C02 superset)
 

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/pce/lib/c/pce_video.c

@@ -83,7 +83,7 @@ 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_MWR, 0x0000);  /* 32x32 virtual map (SCREEN field=000); 256px BAT. (0x10 was 64x32 — its 64-wide stride left the bottom rows as uninitialized VRAM = vertical-stripe garbage.) */
     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           */

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/rom-id/identifier.js

@@ -107,6 +107,7 @@ function parseINes(b) {
   if (f6 & 0x04) notes.push("trainer present");
   if (f6 & 0x08) notes.push("four-screen VRAM");
 
+  const hasBattery = !!(f6 & 0x02);
   return {
     platform: "nes",
     format: ".nes",
@@ -117,6 +118,10 @@ function parseINes(b) {
       chr: chrBanks * 8192,
       total: b.length,
     },
+    // Battery-backed cartridge SAVE RAM: present iff the iNES battery flag is set
+    // (8 KB is the standard PRG-RAM window). Read/write live via
+    // memory({region:'save_ram'}); persist with state({op:'exportSram'/'importSram'}).
+    saveRam: { hasBattery, bytes: hasBattery ? 8192 : 0 },
     notes: [...notes, `mirroring: ${mirroring}`],
     confidence: 1,
   };
@@ -208,6 +213,13 @@ function parseGameBoy(b) {
     0x1E: "MBC5+RUMBLE+RAM+BATTERY", 0xFC: "Pocket Camera", 0xFE: "HuC3", 0xFF: "HuC1+RAM+BATTERY",
   };
 
+  // Battery save = cart type whose name carries BATTERY. MBC2 has 512×4 bits of
+  // internal RAM (ramSizeCode is 0 but it still saves), so treat it specially.
+  const typeName = cartTypeNames[cartType] ?? "";
+  const hasBattery = /BATTERY/.test(typeName);
+  const isMbc2 = cartType === 0x05 || cartType === 0x06;
+  const saveBytes = hasBattery ? (isMbc2 ? 512 : Math.max(ramSize, 0)) : 0;
+
   return {
     platform,
     format: isGbc ? ".gbc" : ".gb",
@@ -215,6 +227,9 @@ function parseGameBoy(b) {
     region,
     mapper: cartTypeNames[cartType] ?? `0x${cartType.toString(16)}`,
     sizes: { rom: romSize, ram: ramSize, total: b.length },
+    // Battery-backed cartridge SAVE RAM (the .sav). Read/write live via
+    // memory({region:'save_ram'}); persist with state({op:'exportSram'/'importSram'}).
+    saveRam: { hasBattery, bytes: saveBytes },
     notes: [
       isGbc ? "Game Boy Color cartridge" : "Original Game Boy cartridge",
       sgbFlag === 0x03 && "supports Super Game Boy enhancements",

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.

package/src/toolchains/assemble-snippet.js

@@ -25,11 +25,30 @@ import { runCa65, runLd65 } from "./cc65/cc65.js";
 import { runAsar } from "./asar/asar.js";
 import { runVasm68k } from "./vasm68k/vasm68k.js";
 import { runSdasz80, runSdld, ihxToBin } from "./sdcc/sdcc.js";
-import { runRgbasm, runRgblink, runRgbfix } from "./rgbds/rgbds.js";
+import { runRgbasm, runRgblink } from "./rgbds/rgbds.js";
+import { parseBuildLog } from "./parse-errors.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+// Build a transparent snippet-assembly error: lead with the FIRST structured
+// diagnostic (file:line: message) parsed out of the raw log — the same
+// issues[]-style surfacing build() does — instead of dumping the unparsed
+// assembler stdout and making the agent grep it. Full log still appended for
+// fallback. `where` is e.g. "ca65" / "ld65 link" / "asar".
+function asmError(where, 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(
+    `assembleSnippet[${where}] failed: ${headline}` +
+    (issues.length > 1 ? ` (+${issues.length - 1} more issue(s))` : "") +
+    `\nFix the source line above. Full assembler log:\n${log ?? ""}`,
+  );
+}
+
 /**
  * CPU dialect → assembler dispatch. Keys are also the public API.
  */
@@ -102,7 +121,7 @@ async function assembleCa65({ origin, code }, cpu = "6502") {
 
   const asm = await runCa65({ source });
   if (!asm.object) {
-    throw new Error(`assembleSnippet[ca65]: assembly failed.\nlog:\n${asm.log ?? ""}`);
+    throw asmError("ca65", asm.log);
   }
 
   // Minimal linker config: one MEMORY block at `origin`, one SEGMENT
@@ -116,7 +135,7 @@ SEGMENTS { CODE: load = OUT, type = ro; }
     linkerConfig: cfg,
   });
   if (!linked.binary) {
-    throw new Error(`assembleSnippet[ld65]: link failed.\nlog:\n${linked.log ?? ""}`);
+    throw asmError("ld65 link", linked.log);
   }
   return { bytes: linked.binary, log: (asm.log ?? "") + (linked.log ?? "") };
 }
@@ -137,7 +156,7 @@ async function assembleAsar({ origin, code }) {
   const source = `org ${hex24}\n${code}\n`;
   const r = await runAsar({ source, baseRom, symbols: false });
   if (!r.binary) {
-    throw new Error(`assembleSnippet[asar]: assembly failed.\nlog:\n${r.log ?? ""}`);
+    throw asmError("asar", r.log);
   }
   const bin = r.binary;
   // Find first non-sentinel byte (asar may have written anywhere depending
@@ -148,7 +167,7 @@ async function assembleAsar({ origin, code }) {
     if (bin[i] !== SENTINEL) { start = i; break; }
   }
   if (start < 0) {
-    throw new Error(`assembleSnippet[asar]: no bytes written (origin 0x${origin.toString(16)})\nlog:\n${r.log ?? ""}`);
+    throw new Error(`assembleSnippet[asar]: no bytes written (origin 0x${origin.toString(16)}) — the source assembled but emitted nothing at this origin. Check the org address and that the code actually emits bytes.\nFull log:\n${r.log ?? ""}`);
   }
   let end = start + 1;
   let sentinelRun = 0;
@@ -181,7 +200,7 @@ async function assembleVasm68k({ origin, code }) {
   const source = `\torg $${origin.toString(16).toUpperCase()}\n${indented}\n`;
   const r = await runVasm68k({ source, options: ["-Fbin"] });
   if (!r.binary || (r.exitCode != null && r.exitCode !== 0)) {
-    throw new Error(`assembleSnippet[vasm68k]: assembly failed.\nlog:\n${r.log ?? ""}`);
+    throw asmError("vasm68k", r.log);
   }
   return { bytes: r.binary, log: r.log ?? "" };
 }
@@ -199,7 +218,7 @@ async function assembleSdcc({ origin, code }) {
   const source = `\t.module snippet\n\t.area _CODE\n${indented}\n`;
   const asm = await runSdasz80({ source });
   if (!asm.rel) {
-    throw new Error(`assembleSnippet[sdasz80]: assembly failed.\nlog:\n${asm.log ?? ""}`);
+    throw asmError("sdasz80", asm.log);
   }
   // Minimal empty crt0 rel: just declares _HEADER0 (zero bytes) and is
   // enough for sdld to satisfy its hardcoded crt0.rel dependency.
@@ -212,7 +231,7 @@ async function assembleSdcc({ origin, code }) {
     libraries: [],
   });
   if (!linked.ihx) {
-    throw new Error(`assembleSnippet[sdld]: link failed.\nlog:\n${linked.log ?? ""}`);
+    throw asmError("sdld link", linked.log);
   }
   const padded = ihxToBin(linked.ihx, 0x10000, 0xFF);
   // Find first and last non-FF byte from origin onwards. The snippet bytes
@@ -232,19 +251,18 @@ async function assembleSdcc({ origin, code }) {
 async function assembleRgbds({ origin, code }) {
   // rgbasm needs SECTION declarations to place code at an address.
   const sectionAt = `$${origin.toString(16).toUpperCase()}`;
-  const source = `SECTION "snippet", ROMX[${sectionAt}], BANK[0]\n${code}\n`;
-  // Actually GB has no BANK[0] for fixed ROM — use ROM0 if origin < 0x4000.
+  // GB has no BANK[0] for fixed ROM — use ROM0 if origin < 0x4000, else ROMX BANK[1].
   const useRom0 = origin < 0x4000;
   const realSource = useRom0
     ? `SECTION "snippet", ROM0[${sectionAt}]\n${code}\n`
     : `SECTION "snippet", ROMX[${sectionAt}], BANK[1]\n${code}\n`;
   const asm = await runRgbasm({ source: realSource });
   if (!asm.object) {
-    throw new Error(`assembleSnippet[rgbasm]: assembly failed.\nlog:\n${asm.log ?? ""}`);
+    throw asmError("rgbasm", asm.log);
   }
   const linked = await runRgblink({ objects: { "snippet.o": asm.object }, padValue: 0x00 });
   if (!linked.binary) {
-    throw new Error(`assembleSnippet[rgblink]: link failed.\nlog:\n${linked.log ?? ""}`);
+    throw asmError("rgblink link", linked.log);
   }
   // Slice from origin, find last non-zero byte.
   const start = useRom0 ? origin : (origin - 0x4000 + 0x4000); // bank 1 lives at file 0x4000

package/src/toolchains/cc65/ines.js

@@ -0,0 +1,145 @@
+// iNES header + NROM linker-config synthesis for cc65/ca65 NES builds.
+//
+// The most common NES *reverse-engineering* build shape — rebuilding a
+// commercial NROM game from its disassembly (e.g. SMBDIS) into a byte-identical
+// `.nes` — needs three pieces of pure boilerplate that are identical for every
+// NROM CHR-ROM cart:
+//   1. the 16-byte iNES header (`.segment "HEADER"`),
+//   2. a CHARS segment fed from the extracted CHR-ROM blob (`.incbin`),
+//   3. a 3-region MEMORY/SEGMENTS .cfg concatenating HEADER + PRG + CHARS into
+//      one output file.
+//
+// `build({inesHeader:{prgBanks, chrBanks, mapper, mirroring}})` and
+// `disasm({target:'project'})` both use this so the agent never hand-derives
+// header bytes or writes glue `.s`/`.cfg` files. Proven byte-identical against
+// nestest.nes (NROM-128, 16K PRG + 8K CHR) and 32K-PRG NROM-256 carts.
+
+/**
+ * @typedef {Object} InesHeaderSpec
+ * @property {number} prgBanks  - 16KB PRG-ROM banks (1 = NROM-128, 2 = NROM-256).
+ * @property {number} [chrBanks] - 8KB CHR-ROM banks (0 = CHR-RAM, no CHARS). Default 0.
+ * @property {number} [mapper]   - iNES mapper number. Default 0 (NROM).
+ * @property {"horizontal"|"vertical"} [mirroring] - nametable mirroring. Default "horizontal".
+ * @property {boolean} [battery] - PRG-RAM battery (flags6 bit 1). Default false.
+ */
+
+/**
+ * Build the 16 raw iNES header bytes for a spec.
+ * @param {InesHeaderSpec} spec
+ * @returns {Uint8Array} exactly 16 bytes
+ */
+export function inesHeaderBytes(spec) {
+  const prg = spec.prgBanks;
+  const chr = spec.chrBanks ?? 0;
+  const mapper = spec.mapper ?? 0;
+  const mirroring = spec.mirroring ?? "horizontal";
+  if (!Number.isInteger(prg) || prg < 1 || prg > 255) {
+    throw new Error(`inesHeader.prgBanks must be an integer 1..255 (16KB each); got ${spec.prgBanks}`);
+  }
+  if (!Number.isInteger(chr) || chr < 0 || chr > 255) {
+    throw new Error(`inesHeader.chrBanks must be an integer 0..255 (8KB each; 0 = CHR-RAM); got ${spec.chrBanks}`);
+  }
+  if (!Number.isInteger(mapper) || mapper < 0 || mapper > 255) {
+    throw new Error(`inesHeader.mapper must be an integer 0..255; got ${spec.mapper}`);
+  }
+  if (mirroring !== "horizontal" && mirroring !== "vertical") {
+    throw new Error(`inesHeader.mirroring must be "horizontal" or "vertical"; got ${JSON.stringify(spec.mirroring)}`);
+  }
+  const flags6 = (mirroring === "vertical" ? 0x01 : 0x00) | (spec.battery ? 0x02 : 0x00) | ((mapper & 0x0f) << 4);
+  const flags7 = mapper & 0xf0;
+  const h = new Uint8Array(16);
+  h[0] = 0x4e; h[1] = 0x45; h[2] = 0x53; h[3] = 0x1a; // "NES\x1a"
+  h[4] = prg;
+  h[5] = chr;
+  h[6] = flags6;
+  h[7] = flags7;
+  // bytes 8..15 stay 0 (iNES 1.0 padding)
+  return h;
+}
+
+/**
+ * ca65 source that emits the iNES header as `.segment "HEADER"`.
+ * @param {InesHeaderSpec} spec
+ * @returns {string}
+ */
+export function inesHeaderSource(spec) {
+  const h = inesHeaderBytes(spec);
+  const prg = spec.prgBanks;
+  const chr = spec.chrBanks ?? 0;
+  const mapper = spec.mapper ?? 0;
+  const mirroring = spec.mirroring ?? "horizontal";
+  const hex = (b) => "$" + b.toString(16).padStart(2, "0").toUpperCase();
+  return [
+    "; iNES header — auto-generated by build({inesHeader:{...}}).",
+    `; prgBanks=${prg} (${prg * 16}KB)  chrBanks=${chr} (${chr * 8}KB${chr === 0 ? " = CHR-RAM" : ""})` +
+      `  mapper=${mapper}  mirroring=${mirroring}`,
+    '.segment "HEADER"',
+    `        .byte ${hex(h[0])},${hex(h[1])},${hex(h[2])},${hex(h[3])}   ; "NES"+EOF`,
+    `        .byte ${h[4]}                       ; PRG-ROM 16KB banks`,
+    `        .byte ${h[5]}                       ; CHR-ROM 8KB banks${chr === 0 ? " (0 = CHR-RAM)" : ""}`,
+    `        .byte ${hex(h[6])}                     ; flags6 (mapper lo nibble + mirroring${spec.battery ? " + battery" : ""})`,
+    `        .byte ${hex(h[7])}                     ; flags7 (mapper hi nibble)`,
+    "        .byte 0,0,0,0,0,0,0,0       ; padding (iNES 1.0)",
+    "",
+  ].join("\n");
+}
+
+/**
+ * ca65 source that pulls the CHR-ROM blob into the CHARS segment.
+ * @param {string} incbinName - the binaryInclude file name to `.incbin`.
+ * @returns {string}
+ */
+export function charsSource(incbinName) {
+  return [
+    "; CHR-ROM data — auto-generated by build({inesHeader:{...}}).",
+    '.segment "CHARS"',
+    `        .incbin "${incbinName}"`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * A flat NROM linker .cfg: HEADER(16B) + PRG + (optional) CHARS, all concatenated
+ * into one %O output file. "Flat" = one CODE segment carrying the whole PRG image
+ * with its OWN embedded reset/NMI/IRQ vectors (the shape a disassembly produces),
+ * NOT cc65's STARTUP/VECTORS/CONDES split. Use `chr-rom` (the named preset) for
+ * cc65-C-with-segments builds instead.
+ *
+ *  - prgBanks=1 (NROM-128): the 16KB image maps at $C000 (mirrored to $8000).
+ *  - prgBanks=2 (NROM-256): the 32KB image maps at $8000.
+ *
+ * @param {InesHeaderSpec} spec
+ * @returns {string} ld65 config text
+ */
+export function nromFlatCfg(spec) {
+  const prg = spec.prgBanks;
+  const chr = spec.chrBanks ?? 0;
+  const prgSize = prg * 0x4000;
+  // NROM-128's single 16KB bank lives in the upper half so $FFFA vectors land;
+  // anything larger fills from $8000 down.
+  const prgStart = prg === 1 ? 0xc000 : 0x10000 - prgSize;
+  const lines = [
+    "# Flat NROM linker config — auto-generated by build({inesHeader:{...}}).",
+    "# HEADER(16B) + PRG + " + (chr > 0 ? "CHARS(CHR-ROM)" : "(no CHARS — CHR-RAM)") +
+      ", concatenated into one .nes.",
+    "# 'Flat' CODE segment = the whole PRG image with its own embedded vectors",
+    "# (disassembly shape). For cc65-C with segment split, use linkerConfig:'chr-rom'.",
+    "MEMORY {",
+    "    HEADER: file = %O, start = $0000, size = $0010, fill = yes;",
+    `    PRG:    file = %O, start = $${prgStart.toString(16).toUpperCase()}, size = $${prgSize.toString(16).toUpperCase()}, fill = yes, fillval = $FF;`,
+  ];
+  if (chr > 0) {
+    lines.push(`    CHARS:  file = %O, start = $0000, size = $${(chr * 0x2000).toString(16).toUpperCase()}, fill = yes;`);
+  }
+  lines.push(
+    "}",
+    "SEGMENTS {",
+    "    HEADER: load = HEADER, type = ro;",
+    "    CODE:   load = PRG,    type = ro;",
+  );
+  if (chr > 0) {
+    lines.push("    CHARS:  load = CHARS,  type = ro;");
+  }
+  lines.push("}", "");
+  return lines.join("\n");
+}

package/src/toolchains/cc65/presets/nes/chr-ram-runtime.cfg

@@ -19,7 +19,13 @@
 #   3. Write CHR data from C at runtime: PPUADDR = 0x00; PPUDATA = byte; etc.
 
 SYMBOLS {
-    __STACKSIZE__: type = weak, value = $0300;
+    # Stack is $0200 (512 B) so the top RAM page ($0700-$07FF) can be
+    # reserved below for a music driver's scratch RAM (FamiTone2 et al.),
+    # which needs a dedicated, page-aligned block that the C BSS/DATA
+    # region must NOT overlap. Tiny NROM scaffolds use far less than 512 B
+    # of stack, so this is safe; scaffolds with no music driver simply
+    # leave the reserved page unused.
+    __STACKSIZE__: type = weak, value = $0200;
 }
 MEMORY {
     ZP:     file = "", start = $0002, size = $001A, type = rw, define = yes;
@@ -37,6 +43,13 @@ MEMORY {
 
     SRAM:   file = "", start = $0500, size = __STACKSIZE__, define = yes;
 
+    # Reserved page for a sound-driver's RAM scratch ($0700-$07FF). The
+    # bundled FamiTone2 engine (music_demo scaffold) pins FT_BASE_ADR here
+    # so its ~90 bytes of channel/envelope state can't collide with the C
+    # BSS/DATA at $0300-$04FF — that collision silently clobbers the NMI's
+    # cached PPUCTRL and stalls rendering. Unused by non-music scaffolds.
+    SNDRAM: file = "", start = $0700, size = $0100, define = yes;
+
     # BSS / DATA live in real RAM ($0300-$04FF, 512 bytes). NROM (mapper 0)
     # with no battery has $6000-$7FFF UNMAPPED — reads return open bus.
     # Putting BSS there means `int counter = 0;` reads garbage (intermittent