romdevtools 0.16.0 → 0.21.0

package/src/platforms/c64/d64.js

@@ -0,0 +1,281 @@
+// C64 1541 disk image (.d64) codec — pure JS, no external tools.
+//
+// Why this exists: romdev builds C64 homebrew as a bare `.prg` (cc65's output),
+// but the real C64 world — the new Commodore 64 Ultimate / C64C Ultimate FPGA
+// hardware and the entire homebrew/demo scene — loads games as `.d64` disk
+// images (and saves by writing files back INTO the disk). A `.prg` with no
+// drive can't save and isn't how anything ships. This module is the bridge:
+//
+//   prgToD64(prg, {name})        — pack a .prg into a fresh, autostart-able .d64
+//   readDirectory(d64)           — list the files on a disk image
+//   extractFile(d64, name)       — pull a file's bytes back out (post-save read)
+//
+// Format reference: the standard 35-track 1541 image (174848 bytes). 256-byte
+// sectors, variable sectors per track. Track 18 holds the BAM (sector 0) and
+// the directory (sectors 1+). Files are PETSCII-named, stored as linked sector
+// chains where each sector's first two bytes are (nextTrack, nextSector) — or
+// (0x00, lastByteIndex) on the final sector. This is the well-documented "D64"
+// layout used by VICE's c1541 and every C64 emulator.
+
+const SECTOR_SIZE = 256;
+const NUM_TRACKS = 35;
+const DIR_TRACK = 18;
+const BAM_SECTOR = 0;
+const DIR_START_SECTOR = 1;
+
+// Sectors per track for a 35-track 1541 disk (zones 1-4).
+// Tracks 1-17: 21, 18-24: 19, 25-30: 18, 31-35: 17.
+const SECTORS_PER_TRACK = (() => {
+  const a = new Array(NUM_TRACKS + 1).fill(0); // 1-indexed
+  for (let t = 1; t <= NUM_TRACKS; t++) {
+    if (t <= 17) a[t] = 21;
+    else if (t <= 24) a[t] = 19;
+    else if (t <= 30) a[t] = 18;
+    else a[t] = 17;
+  }
+  return a;
+})();
+
+const TOTAL_SECTORS = (() => {
+  let n = 0;
+  for (let t = 1; t <= NUM_TRACKS; t++) n += SECTORS_PER_TRACK[t];
+  return n; // 683
+})();
+
+const IMAGE_SIZE = TOTAL_SECTORS * SECTOR_SIZE; // 174848
+
+/** Byte offset of (track, sector) within the flat image. track is 1-indexed. */
+function offsetOf(track, sector) {
+  let off = 0;
+  for (let t = 1; t < track; t++) off += SECTORS_PER_TRACK[t] * SECTOR_SIZE;
+  return off + sector * SECTOR_SIZE;
+}
+
+/** Convert an ASCII string to PETSCII-ish bytes, padded/truncated to `len` with 0xA0 (shifted space). */
+function petsciiName(name, len = 16) {
+  const out = new Uint8Array(len).fill(0xa0);
+  const s = String(name || "").toUpperCase();
+  for (let i = 0; i < len && i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    // ASCII A-Z, 0-9, space, and common punctuation map ~1:1 to PETSCII for
+    // these ranges; anything exotic falls back to a space.
+    out[i] = c >= 0x20 && c <= 0x5f ? c : 0x20;
+  }
+  return out;
+}
+
+/**
+ * Convert a PETSCII directory name (as stored on disk) back to a trimmed ASCII
+ * string. Filenames written by the C64 KERNAL SAVE use the DEFAULT uppercase
+ * charset, where letters A–Z are 0xC1–0xDA (high bit set), not 0x41–0x5A — so we
+ * must translate that range, otherwise an emulator-written "SCORE" reads as
+ * empty. (Our own prgToD64 writes plain 0x41–0x5A; both must decode.)
+ */
+function asciiFromPetscii(bytes) {
+  let s = "";
+  for (const b of bytes) {
+    if (b === 0xa0 || b === 0x00) break; // shifted-space pad / terminator
+    if (b >= 0xc1 && b <= 0xda) {
+      s += String.fromCharCode(b - 0x80);          // PETSCII upper A–Z (0xC1..) → ASCII
+    } else if (b >= 0x20 && b <= 0x5f) {
+      s += String.fromCharCode(b);                 // plain ASCII / digits / punctuation
+    } else if (b >= 0x61 && b <= 0x7a) {
+      s += String.fromCharCode(b - 0x20);          // PETSCII lower-as-upper → ASCII upper
+    }
+    // anything else (graphics chars etc.) is dropped from the readable name
+  }
+  return s.trim();
+}
+
+/**
+ * Pack a `.prg` (2-byte little-endian load address + body) into a fresh,
+ * autostart-able 1541 `.d64` image. The file is written as a single PRG-type
+ * directory entry named `name` (default "GAME"). The disk is otherwise empty.
+ *
+ * @param {Uint8Array|Buffer} prg  the raw .prg bytes (load addr + program)
+ * @param {object} [opts]
+ * @param {string} [opts.name]      file name (PETSCII, ≤16 chars) — default "GAME"
+ * @param {string} [opts.diskName]  disk label (≤16 chars) — default = name
+ * @param {string} [opts.diskId]    2-char disk id — default "RD"
+ * @returns {Uint8Array} a 174848-byte .d64 image
+ */
+export function prgToD64(prg, opts = {}) {
+  const body = prg instanceof Uint8Array ? prg : new Uint8Array(prg);
+  if (body.length < 2) throw new Error("prgToD64: .prg too small (need ≥2 bytes load address)");
+  const fileName = opts.name || "GAME";
+  const diskName = opts.diskName || fileName;
+  const diskId = (opts.diskId || "RD").slice(0, 2).padEnd(2, " ");
+
+  const img = new Uint8Array(IMAGE_SIZE);
+
+  // ---- Lay the file out as a linked sector chain ----------------------------
+  // Files conventionally start on track 1; we walk forward, skipping the
+  // directory track (18). 254 data bytes per sector (2 bytes are the link).
+  const dataPerSector = SECTOR_SIZE - 2;
+  const numSectors = Math.ceil(body.length / dataPerSector) || 1;
+
+  // Pick a sector list (track, sector) for the file, skipping the dir track.
+  const chain = [];
+  let track = 1;
+  let sector = 0;
+  for (let i = 0; i < numSectors; i++) {
+    // advance to a free (track,sector), skipping the directory track
+    while (track === DIR_TRACK || sector >= SECTORS_PER_TRACK[track]) {
+      if (sector >= SECTORS_PER_TRACK[track]) { track++; sector = 0; }
+      if (track === DIR_TRACK) { track++; sector = 0; }
+      if (track > NUM_TRACKS) throw new Error("prgToD64: file too large for a 35-track disk");
+    }
+    chain.push([track, sector]);
+    sector++;
+  }
+
+  // Write the chain.
+  for (let i = 0; i < chain.length; i++) {
+    const [t, s] = chain[i];
+    const base = offsetOf(t, s);
+    const isLast = i === chain.length - 1;
+    const sliceStart = i * dataPerSector;
+    const sliceEnd = Math.min(sliceStart + dataPerSector, body.length);
+    const chunk = body.subarray(sliceStart, sliceEnd);
+    if (isLast) {
+      img[base] = 0x00;                 // next track = 0 → end of file
+      img[base + 1] = chunk.length + 1; // bytes-used-in-this-sector index
+    } else {
+      const [nt, ns] = chain[i + 1];
+      img[base] = nt;
+      img[base + 1] = ns;
+    }
+    img.set(chunk, base + 2);
+  }
+
+  const fileBlocks = chain.length;
+
+  // ---- BAM (track 18, sector 0) --------------------------------------------
+  const bam = offsetOf(DIR_TRACK, BAM_SECTOR);
+  img[bam + 0] = DIR_TRACK;        // first directory track
+  img[bam + 1] = DIR_START_SECTOR; // first directory sector
+  img[bam + 2] = 0x41;             // 'A' = 1541 disk format
+  img[bam + 3] = 0x00;
+
+  // Per-track free-sector bitmap: 4 bytes each for tracks 1..35 at +4.
+  // byte0 = free count, bytes1-3 = bitmap (bit set = sector free).
+  for (let t = 1; t <= NUM_TRACKS; t++) {
+    const e = bam + 4 + (t - 1) * 4;
+    const spt = SECTORS_PER_TRACK[t];
+    let freeMask = 0;
+    for (let s = 0; s < spt; s++) freeMask |= (1 << s);
+    // mark used: any sector in our file chain, plus track 18 sectors 0 & 1
+    let used = new Set();
+    if (t === DIR_TRACK) { used.add(BAM_SECTOR); used.add(DIR_START_SECTOR); }
+    for (const [ct, cs] of chain) if (ct === t) used.add(cs);
+    for (const s of used) freeMask &= ~(1 << s);
+    let freeCount = 0;
+    for (let s = 0; s < spt; s++) if (freeMask & (1 << s)) freeCount++;
+    img[e + 0] = freeCount;
+    img[e + 1] = freeMask & 0xff;
+    img[e + 2] = (freeMask >> 8) & 0xff;
+    img[e + 3] = (freeMask >> 16) & 0xff;
+  }
+
+  // Disk name (+0x90, 16 bytes, 0xA0 padded), then id + dos type.
+  img.set(petsciiName(diskName, 16), bam + 0x90);
+  img[bam + 0xa0] = 0xa0;
+  img[bam + 0xa1] = 0xa0;
+  img[bam + 0xa2] = diskId.charCodeAt(0);
+  img[bam + 0xa3] = diskId.charCodeAt(1);
+  img[bam + 0xa4] = 0xa0;
+  img[bam + 0xa5] = 0x32; // '2'  DOS version
+  img[bam + 0xa6] = 0x41; // 'A'
+  for (let i = 0xa7; i <= 0xaa; i++) img[bam + i] = 0xa0;
+
+  // ---- Directory entry (track 18, sector 1, first slot) --------------------
+  const dir = offsetOf(DIR_TRACK, DIR_START_SECTOR);
+  img[dir + 0] = 0x00; // next dir track = 0 (only one dir sector)
+  img[dir + 1] = 0xff; // next dir sector = 0xff (last in chain)
+  // entry: file type (0x82 = closed PRG), then first (track,sector)
+  img[dir + 2] = 0x82;
+  img[dir + 3] = chain[0][0];
+  img[dir + 4] = chain[0][1];
+  img.set(petsciiName(fileName, 16), dir + 5);
+  // bytes 0x15-0x1d: REL side info / unused for PRG → 0
+  img[dir + 0x1e] = fileBlocks & 0xff;        // block count low
+  img[dir + 0x1f] = (fileBlocks >> 8) & 0xff; // block count high
+
+  return img;
+}
+
+/**
+ * Read the directory of a `.d64` image.
+ * @param {Uint8Array|Buffer} d64
+ * @returns {Array<{name:string, type:string, track:number, sector:number, blocks:number}>}
+ */
+export function readDirectory(d64) {
+  const img = d64 instanceof Uint8Array ? d64 : new Uint8Array(d64);
+  const TYPES = ["DEL", "SEQ", "PRG", "USR", "REL"];
+  const out = [];
+  let t = DIR_TRACK, s = DIR_START_SECTOR;
+  const seen = new Set();
+  while (t !== 0 && !seen.has(`${t},${s}`)) {
+    seen.add(`${t},${s}`);
+    const base = offsetOf(t, s);
+    const nextT = img[base + 0];
+    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
+      const ft = img[entryBase + 0];
+      const ftrack = img[entryBase + 1];
+      const fsector = img[entryBase + 2];
+      const nameBytes = img.subarray(entryBase + 3, entryBase + 3 + 16);
+      const name = asciiFromPetscii(nameBytes);
+      if (!name) continue;
+      const blocks = img[entryBase + 0x1c] | (img[entryBase + 0x1d] << 8);
+      out.push({ name, type: TYPES[ft & 0x07] || "DEL", track: ftrack, sector: fsector, blocks });
+    }
+    t = nextT; s = nextS;
+  }
+  return out;
+}
+
+/**
+ * Extract a file's raw bytes (including its 2-byte load address for PRG) from a
+ * `.d64`, by following its sector chain. If `name` is omitted, the first file
+ * is returned.
+ * @param {Uint8Array|Buffer} d64
+ * @param {string} [name]
+ * @returns {Uint8Array|null} file bytes, or null if not found
+ */
+export function extractFile(d64, name) {
+  const img = d64 instanceof Uint8Array ? d64 : new Uint8Array(d64);
+  const dir = readDirectory(img);
+  const entry = name
+    ? dir.find((d) => d.name.toUpperCase() === String(name).toUpperCase())
+    : dir[0];
+  if (!entry) return null;
+
+  const bytes = [];
+  let t = entry.track, s = entry.sector;
+  const seen = new Set();
+  while (t !== 0 && !seen.has(`${t},${s}`)) {
+    seen.add(`${t},${s}`);
+    const base = offsetOf(t, s);
+    const nextT = img[base + 0];
+    const nextS = img[base + 1];
+    if (nextT === 0) {
+      // last sector: nextS is the index of the last valid byte (+1 over data)
+      const used = nextS; // bytes 2..used hold data
+      for (let i = 2; i <= used && base + i < img.length; i++) bytes.push(img[base + i]);
+      break;
+    } else {
+      for (let i = 2; i < SECTOR_SIZE; i++) bytes.push(img[base + i]);
+    }
+    t = nextT; s = nextS;
+  }
+  return new Uint8Array(bytes);
+}
+
+export const D64_IMAGE_SIZE = IMAGE_SIZE;
+export const D64_DISK_EXTENSIONS = [".d64", ".d71", ".d81", ".g64", ".t64", ".tap", ".crt", ".p00"];

package/src/platforms/gb/MENTAL_MODEL.md

@@ -4,6 +4,16 @@ One page. Read once before you write your first game. The
 TROUBLESHOOTING.md alongside this file is for when something's broken;
 this is the "what's going on" version.
 
+## Blank screen? Verify rendering first (no vision needed)
+
+Compiles clean but nothing on screen? Call **`frame({op:'verify', frames:60})`** —
+one call fuses a framebuffer pixel scan with the live LCDC and returns
+`{verified:true|false|null, issues[]}`. `renderDisabled` = LCD off (LCDC.7 clear);
+`blankScreen`/`nearlyBlank` with LCD on = nothing in the BG map / OAM / palette
+(check the footguns below + read `memory({op:'read', region:'gb_vram'})`);
+`verified:null` = step a frame first. Zero image tokens, frame-0-guarded — use it
+as the first move when a change "did nothing."
+
 ## Five silent-failure footguns to know before you start (R26 + R27)
 
 If your ROM compiles cleanly but doesn't render — or sprites land in

package/src/platforms/msx/MENTAL_MODEL.md

@@ -12,12 +12,16 @@ romdev ships a **hardware helper library** (`src/platforms/msx/lib/c/`:
 `msx_psg_tone()` in plain C. It uses DIRECT Z80 I/O ports (the reliable path —
 NOT fragile inline-asm BIOS wrappers).
 
-The fastest way to a working game: **`scaffold({op:'project', platform: "msx", template:
-"sprite_move"})`** (also `music_sfx`, `catch_game`). It drops a complete,
-*building* project — a verified playable example + the helper lib + the cart
-crt0 + docs. Read the example's `main.c`, then change it. Examples live in
-`examples/msx/`. **Gotcha:** read joystick **port 1** (`msx_read_joystick(1)`) —
-port 0 is the keyboard, which an emulator's gamepad doesn't drive.
+The fastest way to a working game: **`scaffold({op:'game', platform: "msx", genre:
+"shmup"})`** — or any of `platformer` / `puzzle` / `sports` / `racing`, the full
+genre set. For a smaller starting point use **`scaffold({op:'project', platform:
+"msx", template: "sprite_move"})`** (also `music_sfx`, `catch_game`). Either drops
+a complete, *building* project — a verified playable example + the helper lib +
+the cart crt0 + docs. Read the example's `main.c`, then change it. Examples live in
+`examples/msx/`. The `platformer` scaffold column-streams the SCREEN 2 name table
+for a tile-by-tile side-scroll. **Gotcha:** read joystick **port 1**
+(`msx_read_joystick(1)`) — port 0 is the keyboard, which an emulator's gamepad
+doesn't drive.
 
 ## CPU — Z80 (16-bit address space, paged in 16 KB slots)
 

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/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/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/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/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");
+}