romdevtools 0.16.0 → 0.22.0

package/src/mcp/tools/cart-parts.js

@@ -11,6 +11,66 @@ import { readFile, writeFile, mkdir } from "node:fs/promises";
 import path from "node:path";
 import { jsonContent, safeTool } from "../util.js";
 import { identifyRomCore } from "./rom-id.js";
+import { prgToD64, readDirectory as readD64Dir, extractFile as extractD64File } from "../../platforms/c64/d64.js";
+
+// ─── C64 .d64 disk image ──────────────────────────────────────────
+//
+// The C64 world ships and loads games as .d64 disk images (the new Commodore 64
+// Ultimate FPGA hardware + the homebrew/demo scene), not as bare .prg files. A
+// cc65 build emits a .prg; packDisk wraps it into a distributable, autostart-able
+// .d64. Extract on a .d64 lists/pulls its files back out.
+
+/**
+ * Pack a built .prg into a .d64 disk image (the distribution format).
+ * @param {{prgPath?:string, bodyPath?:string, romPath?:string, base64?:string,
+ *          outputPath?:string, name?:string, diskName?:string, inline?:boolean}} args
+ */
+export async function packDiskCore(args) {
+  const src = args.prgPath || args.bodyPath || args.romPath;
+  let prg;
+  if (args.base64) prg = new Uint8Array(Buffer.from(args.base64, "base64"));
+  else if (src) prg = new Uint8Array(await readFile(src));
+  else throw new Error("cart({op:'packDisk'}): provide `prgPath` (the built .prg) or `base64`.");
+
+  const name = (args.name || (src ? path.basename(src).replace(/\.[^.]+$/, "") : "GAME"))
+    .toUpperCase().replace(/[^A-Z0-9 ]/g, "").slice(0, 16) || "GAME";
+  const d64 = prgToD64(prg, { name, diskName: args.diskName || name });
+
+  if (args.inline) {
+    return { packed: true, format: "d64", name, bytes: d64.length, base64: Buffer.from(d64).toString("base64") };
+  }
+  const out = args.outputPath
+    || (src ? src.replace(/\.[^.]+$/, "") + ".d64" : null);
+  if (!out) throw new Error("cart({op:'packDisk'}): `outputPath` required (or pass `prgPath` to derive it, or inline:true).");
+  await writeFile(out, Buffer.from(d64));
+  return {
+    packed: true, format: "d64", name, bytes: d64.length, path: out,
+    note: "Autostart-able 1541 disk image. Load it with loadMedia({platform:'c64', path}) — it boots the program automatically. This is the format the Commodore 64 Ultimate hardware and the homebrew scene load.",
+  };
+}
+
+/** Read a .d64's directory + (optionally) extract a file. */
+export async function extractDiskCore(args) {
+  const data = new Uint8Array(await readFile(args.path));
+  const dir = readD64Dir(data);
+  const result = { format: "d64", path: args.path, files: dir };
+  // If a specific file was named, also return its bytes.
+  const which = args.name;
+  if (which != null) {
+    const bytes = extractD64File(data, which);
+    if (!bytes) throw new Error(`cart({op:'extract'}) .d64: no file '${which}' on the disk (have: ${dir.map((d) => d.name).join(", ") || "none"}).`);
+    if (args.inline) result.file = { name: which, bytes: bytes.length, base64: Buffer.from(bytes).toString("base64") };
+    else {
+      const out = args.outputDir
+        ? path.join(args.outputDir, which.replace(/[^A-Za-z0-9._-]/g, "_") + ".prg")
+        : args.path.replace(/\.d64$/i, "") + "." + which.replace(/[^A-Za-z0-9._-]/g, "_") + ".prg";
+      if (args.outputDir) await mkdir(args.outputDir, { recursive: true });
+      await writeFile(out, Buffer.from(bytes));
+      result.file = { name: which, bytes: bytes.length, path: out };
+    }
+  }
+  return result;
+}
 
 // ─── extractCart ──────────────────────────────────────────────────
 
@@ -71,7 +131,6 @@ function extractNes(data) {
  */
 function extractSnes(data) {
   const copierOff = (data.length % 0x8000 === 0x200) ? 0x200 : 0;
-  const loMapper = data[copierOff + 0x7FC0 + 0x15];
   const hiMapper = data[copierOff + 0xFFC0 + 0x15];
   const isLo = !(hiMapper === 0x21 || hiMapper === 0x31);
   const internalHeaderBase = copierOff + (isLo ? 0x7FC0 : 0xFFC0);
@@ -590,7 +649,7 @@ function wrapC64({ loadAddress, bodyPath, romPath }) {
 export function registerCartPartsTools(server, z) {
   server.tool(
     "cart",
-    "Cartridge container ops — identify / split / reassemble a ROM file. `op`: 'identify' | 'extract' | 'wrap'.\n" +
+    "Cartridge container ops — identify / split / reassemble a ROM file. `op`: 'identify' | 'extract' | 'wrap' | 'packDisk'.\n" +
     "'identify': sniff an unknown ROM/zip's platform (which core to load). Handles zip-wrapped ROMs; `path` OR " +
     "`base64` (+`hint` ext for headerless). Returns {platform, format, title, mapper, region, sizes, confidence}. " +
     "RE next steps: cheats({op:'lookup'}) is a free labeled memory/code map; disasm is how you change behavior.\n" +
@@ -601,9 +660,13 @@ export function registerCartPartsTools(server, z) {
     "Round-trips with 'wrap' (extract → romPatch a part → wrap → build).\n" +
     "'wrap': generate a build-ready wrapper source (+ NES linker config; null for other platforms) that reassembles " +
     "parts back into a cart. NES auto-generates the iNES header from mapper+mirror (chrPath:null for CHR-RAM; only " +
-    "prgBanks 1/2 = NROM-128/256). Per-platform part paths in the param hints (pass `romPath` for a one-shot whole-body incbin).",
+    "prgBanks 1/2 = NROM-128/256). Per-platform part paths in the param hints (pass `romPath` for a one-shot whole-body incbin).\n" +
+    "'packDisk' (C64): wrap a built `.prg` (`prgPath` or `base64`) into a distributable, autostart-able `.d64` disk " +
+    "image — the format the new Commodore 64 Ultimate hardware and the homebrew/demo scene actually load. " +
+    "Writes `<prg>.d64` (or `outputPath`/`inline`). loadMedia({platform:'c64', path:<.d64>}) boots it directly. " +
+    "(extract on a `.d64` lists its directory; pass `name` to pull one file off the disk.)",
     {
-      op: z.enum(["identify", "extract", "wrap"]).describe("identify the ROM's platform; extract into parts; wrap parts back into a cart."),
+      op: z.enum(["identify", "extract", "wrap", "packDisk"]).describe("identify the ROM's platform; extract into parts (or list/pull files from a C64 .d64); wrap parts back into a cart; packDisk wraps a C64 .prg into a distributable .d64 disk image."),
       // identify
       path: z.string().optional().describe("op=identify/extract: absolute path to the ROM file."),
       base64: z.string().optional().describe("op=identify: base64 ROM bytes (OR path)."),
@@ -631,18 +694,26 @@ export function registerCartPartsTools(server, z) {
       a78HeaderPath: z.string().optional().describe("op=wrap Atari 7800: the 128-byte A78 header (if present)."),
       bodyBytes: z.number().int().min(1).optional().describe("op=wrap Atari 7800: size of the 6502 image body (computes the cart origin; default 0xC000)."),
       loadAddress: z.number().int().min(0).max(0xFFFF).optional().describe("op=wrap C64: load address (default 0x0801)."),
+      // packDisk (C64 .d64)
+      name: z.string().optional().describe("op=packDisk: disk file name (PETSCII, ≤16 chars; default from prgPath). op=extract .d64: a file to pull off the disk."),
+      diskName: z.string().optional().describe("op=packDisk: disk label (≤16 chars; default = name)."),
+      outputPath: z.string().optional().describe("op=extract: dir for parts (+ manifest.json). op=packDisk: .d64 output path (default: prgPath with a .d64 extension). Required unless inline:true."),
     },
     safeTool(async (args) => {
       switch (args.op) {
         case "identify": return await identifyRomCore(args);
         case "extract": {
           if (!args.path) throw new Error("cart({op:'extract'}): `path` is required.");
+          // A .d64 is a disk image (a container of files), not a flat cart —
+          // route it to the disk reader so extract lists/pulls its contents.
+          if (/\.d64$/i.test(args.path)) return jsonContent(await extractDiskCore(args));
           return jsonContent(await extractCartCore(args));
         }
         case "wrap": {
           if (!args.platform) throw new Error("cart({op:'wrap'}): `platform` is required.");
           return jsonContent(await wrapRomFromPartsCore(args));
         }
+        case "packDisk": return jsonContent(await packDiskCore(args));
         default: throw new Error(`cart: unknown op '${args.op}'`);
       }
     }),

package/src/mcp/tools/classify-region.js

@@ -51,7 +51,7 @@ function zeroRatio(bytes) {
  * @param {boolean} [opts.bigEndian] platform endianness (for pointer-table guess)
  * @returns {{ looksLike: string, printableRatio:number, entropy:number, zeroRatio:number, longestAsciiRun:number, asciiPreview:string|null, confidence:string, note:string }}
  */
-export function classifyBytes(bytes, opts = {}) {
+export function classifyBytes(bytes, _opts = {}) {
   const pr = printableRatio(bytes);
   const ent = entropy(bytes);
   const zr = zeroRatio(bytes);

package/src/mcp/tools/diff-roms.js

@@ -49,7 +49,7 @@ function regionMapForRom(platform, data) {
  * live anywhere the developer wants. We tag the header so diffs there
  * are obvious.
  */
-function regionMapSms(data, platform) {
+function regionMapSms(data, _platform) {
   const regions = [];
   // Header lives at $7FF0 IF the file is at least 32 KB. Some homebrew
   // skips the header entirely (just runs from $0000) — flag with kind

package/src/mcp/tools/disasm-rebuild.js

@@ -0,0 +1,507 @@
+// Rebuild planning for `disasm({target:'project'})`.
+//
+// `disasm({target:'project'})` splits a ROM into byte-exact `.asm` region files.
+// But region files alone don't REBUILD the ROM — every console also needs its
+// own "rebuild glue": the cartridge header (iNES for NES, the in-image $100
+// header for Genesis, the LNX header for Lynx, the "AB" header for MSX…), any
+// non-code DATA blobs (NES CHR-ROM), and a recipe that reassembles + concatenates
+// everything back into a byte-identical image.
+//
+// This module turns a disassembled project into a TURNKEY one: for each platform
+// it returns the extra data blobs to write plus the recipe that reproduces the
+// original ROM. `disassembleProjectCore` writes the blobs, a machine-readable
+// `rebuild.json` (when there's a one-call build() recipe), and a human/agent
+// readable `BUILD.md`.
+//
+// Contract — planRebuild(platform, data, regions) returns:
+//   {
+//     blobs:      { [filename]: Uint8Array },   // extra files to write (CHR, headers)
+//     build:      { ... } | null,               // the build({...}) args that reproduce
+//                                                //   the ROM, or null if no one-call
+//                                                //   build() route exists (see below)
+//     verifiable: boolean,                       // true = the recipe (build() OR the
+//                                                //   native recipe in `notes`) is proven
+//                                                //   to reproduce the ROM byte-identically
+//     notes:      string,                        // what the rebuilder must know
+//   }
+//
+// `build.sourcesPaths` / `build.binaryIncludePaths` use BARE filenames (relative
+// to the project dir); the emitter rewrites them to absolute paths in rebuild.json
+// and BUILD.md. `build.linkerConfig`, when present, is INLINE .cfg text (not a
+// path) — the emitter does not rewrite it.
+//
+// IMPORTANT — why most platforms have `build: null`:
+//   `disasm` emits each region in the syntax of the NATIVE reassembler for that
+//   CPU family (ca65 for 6502/65816; GNU `as` for z80/sm83/m68k/arm), which is
+//   what round-trips it byte-exact. But `build()`'s shipping toolchains differ:
+//   NES=cc65 (ca65 — MATCHES, so NES is a one-call build() rebuild), but
+//   SNES=asar, Atari2600=dasm, SMS/GG/MSX/GB/GBC=SDCC, Genesis=vasm/SGDK,
+//   GBA=arm-gcc(C-only) — none of which consume the disasm's syntax. For those,
+//   the byte-exact rebuild is the NATIVE recipe documented in `notes` (and the
+//   blobs are still written), so the project is rebuildable even though there's
+//   no single build() call. `verifiable` reflects whether that recipe is proven
+//   byte-identical, regardless of build()-vs-native.
+
+/**
+ * @param {string} platform
+ * @param {Uint8Array} data       full ROM bytes
+ * @param {Array<{name:string,file:string,kind?:string,fileOffset:number,bytes:Uint8Array,startAddress:number}>} regions
+ * @returns {{ blobs: Record<string, Uint8Array>, build: object|null, verifiable: boolean, notes: string }}
+ */
+export function planRebuild(platform, data, regions) {
+  const fn = PLANNERS[platform];
+  if (fn) return fn(data, regions);
+  return {
+    blobs: {},
+    build: regions.length ? { output: "rom", platform, sourcesPaths: srcMap(regions) } : null,
+    verifiable: false,
+    notes:
+      `No platform-specific rebuild recipe for '${platform}' yet — the .asm region(s) ` +
+      `reassemble, but you may need a linker config to concatenate them + re-add any ` +
+      `cartridge header. See the platform's MENTAL_MODEL.md.`,
+  };
+}
+
+/** {regionFile: regionFile} for sourcesPaths (bare names; emitter absolutizes). */
+function srcMap(regions) {
+  const m = {};
+  for (const r of regions) m[r.file] = r.file;
+  return m;
+}
+
+/** UTF-8 encode a synthesized text source so it can ship as a blob. */
+function enc(s) {
+  return new TextEncoder().encode(s);
+}
+
+/** The size + repeated byte of a region's stripped trailing pad, if uniform. */
+function trailingPad(data, tailStart) {
+  const count = data.length - tailStart;
+  if (count <= 0) return { count: 0, byte: 0x00, uniform: true };
+  const byte = data[tailStart];
+  for (let i = tailStart + 1; i < data.length; i++) {
+    if (data[i] !== byte) return { count, byte, uniform: false };
+  }
+  return { count, byte, uniform: true };
+}
+
+const PLANNERS = {
+  // ───────────────────────────────────────────── NES (iNES + CHR-ROM)
+  // The ONE platform with a one-call build() rebuild: disasm emits ca65, and the
+  // NES build() toolchain IS cc65/ca65. inesHeader synthesizes the 16B header +
+  // the CHARS segment wiring + the flat NROM .cfg. PROVEN byte-identical.
+  nes(data) {
+    const prgBanks = data[4];
+    const chrBanks = data[5];
+    const mapper = (data[6] >> 4) | (data[7] & 0xf0);
+    const mirroring = data[6] & 1 ? "vertical" : "horizontal";
+    const battery = !!(data[6] & 2);
+    const prgEnd = 16 + prgBanks * 0x4000;
+    const blobs = {};
+    const binaryIncludePaths = {};
+    if (chrBanks > 0) {
+      blobs["chr.bin"] = data.slice(prgEnd, prgEnd + chrBanks * 0x2000);
+      binaryIncludePaths["chr.bin"] = "chr.bin";
+    }
+    const verifiable = mapper === 0 && prgBanks <= 2;
+    return {
+      blobs,
+      build: {
+        output: "rom",
+        platform: "nes",
+        sourcesPaths: { "prg.asm": "bank0.asm" },
+        ...(Object.keys(binaryIncludePaths).length ? { binaryIncludePaths } : {}),
+        inesHeader: {
+          prgBanks,
+          ...(chrBanks ? { chrBanks } : {}),
+          ...(mapper ? { mapper } : {}),
+          mirroring,
+          ...(battery ? { battery: true } : {}),
+        },
+      },
+      verifiable,
+      notes: verifiable
+        ? `NROM rebuild: inesHeader auto-emits the 16B header + wires chr.bin into the ` +
+          `CHARS segment; bank0.asm is the PRG. One-call build() rebuild, byte-identical.`
+        : `mapper ${mapper}, ${prgBanks} PRG bank(s): inesHeader's flat .cfg covers NROM ` +
+          `(mapper 0, ≤2 PRG banks). For a banked mapper you'll need a linker .cfg that ` +
+          `places each bank — the per-bank .asm files + chr.bin are ready; see the NES ` +
+          `MENTAL_MODEL.md "CHR-ROM / banked rebuilds" note.`,
+    };
+  },
+
+  // ───────────────────────────────────────────── C64 (PRG: 2-byte load addr + body)
+  // build({platform:'c64'}) IS cc65/ca65 (matches the disasm syntax), so this is
+  // a one-call build() rebuild. planRegions strips the 2-byte load address
+  // (fileOffset 2); we re-emit it via a synthesized LOADADDR segment + a custom
+  // 2-area .cfg (LOADADDR then the body). PROVEN byte-identical via build().
+  c64(data, _regions) {
+    const loadAddr = data[0] | (data[1] << 8);
+    const bodyLen = data.length - 2;
+    const loadaddrSrc =
+      "; C64 PRG load-address word — auto-generated by disasm({target:'project'}).\n" +
+      '.setcpu "6502"\n' +
+      '.segment "LOADADDR"\n' +
+      `        .word $${loadAddr.toString(16).toUpperCase().padStart(4, "0")}   ; .prg load address\n`;
+    const cfg =
+      "# C64 .prg rebuild .cfg — auto-generated by disasm({target:'project'}).\n" +
+      "# LOADADDR(2 B little-endian) + MAIN(program image), concatenated into one .prg.\n" +
+      "MEMORY {\n" +
+      `    LOADADDR: start = $${(loadAddr - 2).toString(16).toUpperCase()}, size = $0002, type = ro, file = %O, fill = yes;\n` +
+      `    MAIN:     start = $${loadAddr.toString(16).toUpperCase()}, size = $${bodyLen.toString(16).toUpperCase()}, type = ro, file = %O, fill = yes, fillval = $FF;\n` +
+      "}\n" +
+      "SEGMENTS {\n" +
+      "    LOADADDR: load = LOADADDR, type = ro;\n" +
+      "    CODE:     load = MAIN,     type = ro;\n" +
+      "}\n";
+    return {
+      blobs: { "loadaddr.asm": enc(loadaddrSrc) },
+      build: {
+        output: "rom",
+        platform: "c64",
+        language: "asm",
+        sourcesPaths: { "loadaddr.asm": "loadaddr.asm", "prg.asm": "prg.asm" },
+        linkerConfig: cfg,
+      },
+      verifiable: true,
+      notes:
+        `C64 .prg rebuild: the 2-byte load address ($${loadAddr.toString(16).toUpperCase()}) is re-emitted by the ` +
+        `synthesized loadaddr.asm (LOADADDR segment); prg.asm carries the program image. The ` +
+        `custom .cfg concatenates LOADADDR(2 B) + CODE(${bodyLen} B). One-call build() rebuild, ` +
+        `byte-identical.`,
+    };
+  },
+
+  // ───────────────────────────────────────────── Atari 7800 (.a78: header IN the region)
+  // build({platform:'atari7800'}) IS cc65/ca65, and planRegions keeps the 128-byte
+  // .a78 header inside rom.asm — so a single flat cc65 build reproduces the whole
+  // .a78. One-call build() rebuild, PROVEN byte-identical.
+  atari7800(data) {
+    const org = (0x10000 - data.length) & 0xffff;
+    const cfg =
+      "# Atari 7800 .a78 rebuild .cfg — auto-generated by disasm({target:'project'}).\n" +
+      "# One flat CODE segment carrying the .a78 header + cart image (planRegions keeps\n" +
+      "# the 128-byte header inside rom.asm).\n" +
+      "MEMORY {\n" +
+      `    M: start = $${org.toString(16).toUpperCase()}, size = $${data.length.toString(16).toUpperCase()}, type = ro, file = %O, fill = yes, fillval = $FF;\n` +
+      "}\n" +
+      "SEGMENTS {\n" +
+      "    CODE: load = M, type = ro;\n" +
+      "}\n";
+    return {
+      blobs: {},
+      build: {
+        output: "rom",
+        platform: "atari7800",
+        language: "asm",
+        sourcesPaths: { "rom.asm": "rom.asm" },
+        linkerConfig: cfg,
+      },
+      verifiable: true,
+      notes:
+        `Atari 7800 .a78 rebuild: planRegions keeps the 128-byte .a78 header inside rom.asm ` +
+        `(org $${org.toString(16).toUpperCase()}), so this single flat cc65 build reproduces the whole .a78 ` +
+        `(header + cart). One-call build() rebuild, byte-identical. (If planRegions ever ` +
+        `strips the .a78 header, ship it as a blob + re-prepend instead.)`,
+    };
+  },
+
+  // ───────────────────────────────────────────── Atari 2600 (flat, dasm — no build() route)
+  // The 2600 disasm emits ca65 syntax, but build({platform:'atari2600'}) is DASM,
+  // which can't consume ca65 (.setcpu etc.). So no one-call build() route. The
+  // rebuild IS byte-exact via the native ca65/ld65 chain (a flat fill .cfg) — that
+  // recipe is in notes. (cc65 handles 6502; ld65 links it byte-exact.)
+  atari2600(data, regions) {
+    const reg = regions[0];
+    const cfg =
+      "# Atari 2600 flat-cart rebuild .cfg — auto-generated by disasm({target:'project'}).\n" +
+      "MEMORY {\n" +
+      `    M: start = $${reg.startAddress.toString(16).toUpperCase()}, size = $${reg.bytes.length.toString(16).toUpperCase()}, type = ro, file = %O, fill = yes, fillval = $FF;\n` +
+      "}\n" +
+      "SEGMENTS {\n    CODE: load = M, type = ro;\n}\n";
+    return {
+      blobs: { "atari2600_rebuild.cfg": enc(cfg) },
+      build: null,
+      verifiable: true,
+      notes:
+        `Atari 2600 flat ${reg.bytes.length}-byte cart @ $${reg.startAddress.toString(16).toUpperCase()}. The disasm emits ca65 ` +
+        `syntax, but build({platform:'atari2600'}) is DASM — it can't reassemble ca65. ` +
+        `Rebuild with the bundled native ca65/ld65 (byte-identical proven):\n` +
+        `  ca65 rom.asm -o rom.o && ld65 -C atari2600_rebuild.cfg -o game.bin rom.o\n` +
+        `(atari2600_rebuild.cfg is shipped as a blob.)`,
+    };
+  },
+
+  // ───────────────────────────────────────────── Atari Lynx (.lnx: 64-byte header stripped)
+  // build({platform:'lynx'}) IS cc65/ca65 and reproduces the HEADERLESS cart image
+  // byte-exact (one-call). The 64-byte LNX header is stripped by planRegions; we
+  // ship it as a blob (lnx_header.bin) — but build() can't prepend it, so the full
+  // .lnx needs a final `cat lnx_header.bin + image`. verifiable reflects the full
+  // .lnx recipe (header blob + built image), which is byte-identical.
+  lynx(data, regions) {
+    const hasLnxHeader =
+      data.length >= 64 && data[0] === 0x4c && data[1] === 0x59 && data[2] === 0x4e && data[3] === 0x58;
+    const reg = regions[0];
+    const bodyLen = reg.bytes.length;
+    const org = reg.startAddress;
+    const base = hasLnxHeader ? 64 : 0;
+    const pad = trailingPad(data, base + bodyLen);
+    const cfg =
+      "# Atari Lynx headerless cart-image rebuild .cfg — auto-generated by disasm.\n" +
+      "MEMORY {\n" +
+      `    M: start = $${org.toString(16).toUpperCase()}, size = $${bodyLen.toString(16).toUpperCase()}, type = ro, file = %O, fill = yes, fillval = $FF;\n` +
+      "}\n" +
+      "SEGMENTS {\n    CODE: load = M, type = ro;\n}\n";
+    const blobs = {};
+    if (hasLnxHeader) blobs["lnx_header.bin"] = data.slice(0, 64);
+    return {
+      blobs,
+      build: {
+        output: "rom",
+        platform: "lynx",
+        language: "asm",
+        sourcesPaths: { "cart.asm": "cart.asm" },
+        linkerConfig: cfg,
+      },
+      verifiable: pad.uniform && pad.count === 0,
+      notes: !pad.uniform
+        ? `Lynx: disasm's trailing-pad trim dropped a non-uniform run; the cart image can't ` +
+          `be reproduced byte-exact from cart.asm. Re-disassemble without trailing-pad trimming.`
+        : pad.count > 0
+          ? `Lynx: disasm trimmed ${pad.count} trailing 0x${pad.byte.toString(16).padStart(2, "0")} pad byte(s) — re-pad the ` +
+            `built image to ${data.length - base} bytes, then prepend lnx_header.bin for the full .lnx.`
+          : `Lynx .lnx rebuild: build() of cart.asm reproduces the HEADERLESS cart image ` +
+            `byte-identical. build() can't prepend the 64-byte LNX header, so for the original ` +
+            `.lnx, concatenate the shipped lnx_header.bin (exact original header) + the built ` +
+            `image. The headerless image alone runs on cores that accept an unheadered Lynx ROM. ` +
+            `(Load org $${org.toString(16).toUpperCase()} is the disasm's byte-exact assumption.)`,
+    };
+  },
+
+  // ───────────────────────────────────────────── SNES (LoROM, ca65 — no build() route)
+  // build({platform:'snes'}) is ASAR (or tcc816 for C), neither of which assembles
+  // ca65. No one-call build() route. The rebuild IS byte-exact via native ca65/
+  // ld65: each bankN.asm wrapped in its own segment + an N-area .cfg. Recipe in
+  // notes; wrappers + .cfg shipped as blobs.
+  snes(data, regions) {
+    const hasHeader = data.length % 1024 === 512;
+    const nBanks = regions.length;
+    const blobs = {};
+    if (hasHeader) blobs["copier_header.bin"] = data.slice(0, 512);
+    const memLines = [];
+    const segLines = [];
+    for (let i = 0; i < nBanks; i++) {
+      blobs[`bank${i}_seg.asm`] = enc(
+        `; SNES LoROM bank ${i} wrapper — auto-generated by disasm({target:'project'}).\n` +
+        `.segment "BANK${i}"\n.include "bank${i}.asm"\n`
+      );
+      memLines.push(`    BANK${i}: start = $8000, size = $8000, type = ro, file = %O, fill = yes, fillval = $FF;`);
+      segLines.push(`    BANK${i}: load = BANK${i}, type = ro;`);
+    }
+    const cfg =
+      "# SNES LoROM rebuild .cfg — auto-generated by disasm({target:'project'}).\n" +
+      `# ${nBanks} x 32KB banks at $8000, concatenated in order into one .sfc.\n` +
+      "MEMORY {\n" + memLines.join("\n") + "\n}\n" +
+      "SEGMENTS {\n" + segLines.join("\n") + "\n}\n";
+    blobs["snes_rebuild.cfg"] = enc(cfg);
+    return {
+      blobs,
+      build: null,
+      verifiable: true,
+      notes:
+        `SNES LoROM (${nBanks} x 32KB bank(s)${hasHeader ? ", 512-byte copier header stripped → copier_header.bin" : ""}). ` +
+        `The disasm emits ca65/65816 syntax, but build({platform:'snes'}) is asar/tcc816 — no ` +
+        `build() route. Rebuild with the bundled native ca65/ld65 (byte-identical proven): for ` +
+        `each bank, ca65 --cpu 65816 -o bankN.o bankN_seg.asm; then ld65 -C snes_rebuild.cfg ` +
+        `-o game.sfc bank0.o..bank${nBanks - 1}.o` +
+        (hasHeader ? ` (prepend copier_header.bin for the .smc with its 512-byte header).` : `.`) +
+        ` (Wrappers + snes_rebuild.cfg shipped as blobs.)`,
+    };
+  },
+
+  // ───────────────────────────────────────────── PC Engine (HuCard — disasm region is LOSSY)
+  // PCE is the one honestly-NOT-verifiable case: planRegions trims real trailing
+  // $FF padding AND doesn't strip a 512-byte copier header, so the region is a
+  // lossy view of the .pce. We still emit a best-effort build call; the note is
+  // explicit that an exact rebuild needs a planRegions fix.
+  pce(data, regions) {
+    const reg = regions[0];
+    const bodyLen = reg.bytes.length;
+    const hasCopierHeader = data.length % 1024 === 512;
+    const trimmedPad = data.length - (hasCopierHeader ? 512 : 0) - bodyLen;
+    const cfg =
+      "# PC Engine HuCard rebuild .cfg — auto-generated by disasm({target:'project'}).\n" +
+      "# NOTE: see BUILD.md — the region is a LOSSY view of this .pce.\n" +
+      "MEMORY {\n" +
+      `    M: start = $${reg.startAddress.toString(16).toUpperCase()}, size = $${bodyLen.toString(16).toUpperCase()}, type = ro, file = %O, fill = yes, fillval = $FF;\n` +
+      "}\n" +
+      "SEGMENTS {\n    CODE: load = M, type = ro;\n}\n";
+    return {
+      blobs: { "pce_rebuild.cfg": enc(cfg) },
+      build: null,
+      verifiable: false,
+      notes:
+        `PC Engine: NOT byte-identical from this disassembly. The region (${bodyLen} B) is shorter ` +
+        `than the original (${data.length} B): planRegions trimmed ${trimmedPad > 0 ? trimmedPad : 0} byte(s) of REAL ` +
+        `HuCard $FF padding` +
+        (hasCopierHeader ? `, AND a 512-byte copier header was not stripped (its bytes are the first bytes of rom.asm at a bogus org)` : ``) +
+        `. To rebuild faithfully, re-disassemble after fixing planRegions to (a) strip a ` +
+        `512-byte copier header when len%1024==512 and (b) not trailing-pad-trim HuCard images ` +
+        `(or trim only to an 8KB-bank boundary). Also: the disasm emits ca65 but ` +
+        `build({platform:'pce'}) is cc65 — the native ca65/ld65 chain with pce_rebuild.cfg is ` +
+        `the rebuild path once the region is faithful.`,
+    };
+  },
+
+  // ───────────────────────────────────────────── SMS / GG (flat Z80, no header)
+  sms(data, regions) { return planSegaFlat("sms", data, regions); },
+  gg(data, regions) { return planSegaFlat("gg", data, regions); },
+
+  // ───────────────────────────────────────────── MSX ("AB" cart header + Z80)
+  // build({platform:'msx'}) is SDCC (sdasz80) — can't reassemble the GNU-`as`
+  // rom.asm the disasm emits. No build() route. The 16-byte "AB" header is
+  // stripped by planRegions (region starts at $4010); shipped as msx_header.bin
+  // + re-prepended. With the reassemble.js .org-floor fix, rom.asm now round-trips
+  // (the region is at $4010), so the native recipe is byte-exact.
+  msx(data, regions) {
+    const reg = regions.find((r) => r.file === "rom.asm") ?? regions[0];
+    const hasHeader = data.length >= 2 && data[0] === 0x41 && data[1] === 0x42; // "AB"
+    const blobs = {};
+    if (hasHeader) blobs["msx_header.bin"] = data.slice(0, 16);
+    const bodyStart = hasHeader ? 16 : 0;
+    const bodyLen = reg ? reg.bytes.length : data.length - bodyStart;
+    const pad = trailingPad(data, bodyStart + bodyLen);
+    return {
+      blobs,
+      build: null,
+      verifiable: pad.uniform,
+      notes:
+        `MSX cartridge = 16-byte "AB" header at $4000 + Z80 image; the disasm strips the header ` +
+        `(rom.asm starts at $4010)` +
+        (hasHeader ? `. The 16 header bytes are shipped as msx_header.bin.` : ` (no "AB" header in this ROM).`) +
+        ` build({platform:'msx'}) is SDCC — it can't reassemble the GNU-\`as\` rom.asm. Rebuild ` +
+        `natively (bundled z80 binutils): z80-elf-as -march=z80 rom.asm -o rom.o; ` +
+        `z80-elf-objcopy -O binary rom.o body.bin; take body.bin[0x4010 : 0x4010+${bodyLen}]; ` +
+        `cat msx_header.bin + that body` +
+        (pad.count > 0 ? `; pad with 0x${pad.byte.toString(16).padStart(2, "0")} up to ${data.length} bytes.` : `.`) +
+        (pad.uniform ? ` Byte-identical (with the reassemble .org-floor fix).` : ` WARNING: trailing pad is non-uniform — capture the tail separately.`),
+    };
+  },
+
+  // ───────────────────────────────────────────── Game Boy / GBC (sm83)
+  gb(data, regions) { return planGb(data, regions); },
+  gbc(data, regions) { return planGb(data, regions); },
+
+  // ───────────────────────────────────────── Genesis / Mega Drive (m68k, flat)
+  // build({platform:'genesis'}) is vasm68k (Motorola syntax) or SGDK C, and it
+  // re-pads + rewrites the $18E checksum — no build() route. The header+vectors
+  // ($000000..resetPC) are not in any region → shipped as header.bin + prepended;
+  // trailing pad re-added. Native recipe byte-identical proven.
+  genesis(data, regions) {
+    const reg = regions.find((r) => r.file === "rom.asm") || regions[0];
+    const start = reg.startAddress;
+    const regionLen = reg.bytes.length;
+    const header = data.slice(0, start);
+    const pad = trailingPad(data, start + regionLen);
+    return {
+      blobs: { "header.bin": header },
+      build: null,
+      verifiable: pad.uniform,
+      notes:
+        `Genesis rebuild = header.bin (${header.length} B: 68k vectors + Sega header, up to the reset ` +
+        `PC $${start.toString(16)}) + rom.asm region + ${pad.count} byte(s) of 0x${pad.byte.toString(16).padStart(2, "0")} trailing pad, ` +
+        `concatenated in file order. build({platform:'genesis'}) is vasm68k/SGDK and rewrites the ` +
+        `$18E checksum — no build() route. Rebuild natively: reassembleForPlatform({platform:'genesis', ` +
+        `bytes:<rom.asm region bytes>, startAddress:0x${start.toString(16)}}) (or m68k-elf-as → ld → ` +
+        `objcopy; the LINKED objcopy output starts at offset 0 — take bin.slice(0, ${regionLen})), then ` +
+        `header.bin ++ region ++ pad. The $18E checksum is inside header.bin (re-added verbatim). ` +
+        (pad.uniform ? `Byte-identical proven.` : `WARNING: trailing pad is non-uniform — capture the tail separately.`),
+    };
+  },
+
+  // ───────────────────────────────────────────── Game Boy Advance (ARM7TDMI)
+  // build({platform:'gba'}) is C-only (asm path not wired) — no build() route. The
+  // 192-byte header is a data region; shipped as header.bin (blob) and prepended
+  // verbatim (reproduces the 0xBD checksum, no recompute). code.asm reassembles
+  // natively (Thumb-as-ARM falls to the byte-exact .byte floor). Native recipe
+  // byte-identical proven.
+  gba(data, regions) {
+    const codeReg = regions.find((r) => r.file === "code.asm") || regions[regions.length - 1];
+    const codeStart = codeReg.startAddress;
+    const codeLen = codeReg.bytes.length;
+    const header = data.slice(0, 0xc0);
+    const pad = trailingPad(data, 0xc0 + codeLen);
+    return {
+      blobs: { "header.bin": header },
+      build: null,
+      verifiable: pad.uniform,
+      notes:
+        `GBA rebuild = header.bin (192 B) + code.asm region + ${pad.count} byte(s) of ` +
+        `0x${pad.byte.toString(16).padStart(2, "0")} trailing pad, concatenated in file order. ` +
+        `build({platform:'gba'}) is C-only (asm path not wired) — no build() route. Rebuild ` +
+        `natively: reassembleForPlatform({platform:'gba', bytes:<code.asm region bytes>, ` +
+        `startAddress:0x${codeStart.toString(16)}}) (or arm-none-eabi-as → ld → objcopy; take ` +
+        `bin.slice(0, ${codeLen})), then header.bin ++ code ++ pad. Use header.bin (this blob) for the ` +
+        `concat — the 0xBD header checksum is inside it (reproduced verbatim, no recompute). ` +
+        (pad.uniform ? `Byte-identical proven.` : `WARNING: trailing pad is non-uniform — capture the tail separately.`),
+    };
+  },
+};
+
+/**
+ * Shared SMS/GG flat-ROM planner. The region is the whole image at $0000 with a
+ * uniform trailing pad stripped by trimTrailingPad — recover the cart size + pad
+ * byte so the rebuilder re-pads exactly. build:null (SDCC can't reassemble the
+ * GNU-`as` rom.asm); native recipe in notes, byte-identical proven.
+ */
+function planSegaFlat(platform, data, regions) {
+  const reg = regions.find((r) => r.file === "rom.asm") ?? regions[0];
+  const trimmedLen = reg ? reg.bytes.length : data.length;
+  const pad = trailingPad(data, trimmedLen);
+  const name = platform === "sms" ? "Master System" : "Game Gear";
+  return {
+    blobs: {},
+    build: null,
+    verifiable: pad.uniform,
+    notes:
+      `${name} ROM is a FLAT Z80 image at $0000 with no external cartridge header (the "TMR ` +
+      `SEGA" signature at $7FF0 is in-image). disasm emits one rom.asm at $0000; trimTrailingPad ` +
+      `stripped ${pad.count} trailing 0x${pad.byte.toString(16).padStart(2, "0")} byte(s) (uniform run; original cart ${data.length} B). ` +
+      `build({platform:'${platform}'}) is SDCC — it can't reassemble the GNU-\`as\` rom.asm. Rebuild ` +
+      `natively (bundled z80 binutils, byte-identical proven): z80-elf-as -march=z80 rom.asm -o ` +
+      `rom.o; z80-elf-objcopy -O binary rom.o body.bin (region at $0000 — no lead-in to strip); ` +
+      (pad.count > 0 ? `pad body.bin with 0x${pad.byte.toString(16).padStart(2, "0")} up to ${data.length} bytes.` : `that's the cart image.`) +
+      (pad.uniform ? `` : ` WARNING: trailing pad is non-uniform — capture the tail separately.`),
+  };
+}
+
+/**
+ * Game Boy / GBC rebuild planner. Flat 16KB banks; header in-image at
+ * $0104-$014F inside bank 0 (reproduced as `.byte` data — no patchGbHeader/rgbfix
+ * needed). build({platform:'gb'}) is RGBDS/SDCC — can't reassemble the GNU-`as`
+ * bankN.asm. Native recipe byte-identical proven (with the .org-floor fix that
+ * makes bank1 @ $4000 round-trip).
+ */
+function planGb(data, regions) {
+  const banks = regions.length;
+  return {
+    blobs: {},
+    build: null,
+    verifiable: true,
+    notes:
+      `Game Boy${banks > 1 ? ` (${banks} × 16KB banks)` : ""}: the disasm emits GNU-\`as\` (gbz80) syntax ` +
+      `that build() can't reassemble — rgbasm rejects it and rgbfix would rewrite the checksums — so ` +
+      `no build() route. The header ($0104-$014F incl. the $014D header + $014E-$014F global ` +
+      `checksums) is \`.byte\` data in bank0.asm and reproduces exactly: do NOT run rgbfix; ` +
+      `patchGbHeader is NOT needed. Rebuild natively (bundled binutils, byte-identical proven), ` +
+      `assembling each bank and concatenating:\n` +
+      regions
+        .map(
+          (r) =>
+            `  z80-elf-as -march=gbz80 ${r.file} -o ${r.name}.o && z80-elf-objcopy -O binary ${r.name}.o ${r.name}.full && ` +
+            `dd if=${r.name}.full of=${r.name}.bin bs=1 skip=$((0x${r.startAddress.toString(16)})) count=16384`
+        )
+        .join("\n") +
+      `\n  cat ${regions.map((r) => r.name + ".bin").join(" ")} > rebuilt.gb`,
+  };
+}