romdevtools 0.27.0 → 0.28.0

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

@@ -30,17 +30,19 @@
 // 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`:
+// IMPORTANT — which platforms get a one-call build() and why:
 //   `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.
+//   what round-trips it byte-exact. A one-call build() rebuild exists exactly
+//   where build()'s asm toolchain IS cc65/ca65: NES (NROM and banked mappers),
+//   C64, Atari 7800 (flat and SuperGame banked), Lynx, and PCE (flat and
+//   banked HuCards). The rest differ: 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` (per-bank for banked carts; 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
@@ -90,7 +92,7 @@ const PLANNERS = {
   // 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) {
+  nes(data, regions) {
     const prgBanks = data[4];
     const chrBanks = data[5];
     const mapper = (data[6] >> 4) | (data[7] & 0xf0);
@@ -103,30 +105,93 @@ const PLANNERS = {
       blobs["chr.bin"] = data.slice(prgEnd, prgEnd + chrBanks * 0x2000);
       binaryIncludePaths["chr.bin"] = "chr.bin";
     }
-    const verifiable = mapper === 0 && prgBanks <= 2;
+    const flat = mapper === 0 && prgBanks <= 2;
+    if (flat) {
+      // NROM: the inesHeader one-call path (PROVEN byte-identical). Unchanged.
+      return {
+        blobs,
+        build: {
+          output: "rom",
+          platform: "nes",
+          sourcesPaths: { "prg.asm": "bank0.asm" },
+          ...(Object.keys(binaryIncludePaths).length ? { binaryIncludePaths } : {}),
+          inesHeader: {
+            prgBanks,
+            ...(chrBanks ? { chrBanks } : {}),
+            mirroring,
+            ...(battery ? { battery: true } : {}),
+          },
+        },
+        verifiable: true,
+        notes: `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.`,
+      };
+    }
+    // BANKED mapper (>0 or >2 PRG banks): emit COMPLETE working glue — the old
+    // recipe pointed at bank0 only with the flat NROM cfg, which cannot rebuild
+    // a banked ROM and cost a real RE session an hour of hand-written segments
+    // + cfg (0.27.0 feedback #1). Components:
+    //   nes_header.asm    — HEADER segment with the ORIGINAL 16 iNES bytes
+    //   bankN_seg.asm     — `.segment "PRGn"` wrapper that includes bankN.asm
+    //   nes_chars.asm     — CHARS segment .incbin of chr.bin (when CHR-ROM)
+    //   nes_rebuild.cfg   — HEADER + one 16KB area per bank (+ CHR), in file order
+    // and a rebuild.json build() call wired to ALL of it (linkerConfigPath keeps
+    // the cfg out of context).
+    const hdrBytes = Array.from(data.slice(0, 16))
+      .map((b) => "$" + b.toString(16).toUpperCase().padStart(2, "0")).join(", ");
+    blobs["nes_header.asm"] = enc(
+      `; iNES header — the ORIGINAL 16 bytes, for a byte-exact rebuild.\n` +
+      `.segment "HEADER"\n        .byte ${hdrBytes}\n`
+    );
+    const nBanks = regions.length;
+    const memLines = [
+      `    HEADER: start = $0000, size = $0010, type = ro, file = %O, fill = yes;`,
+    ];
+    const segLines = [
+      `    HEADER: load = HEADER, type = ro;`,
+    ];
+    const sourcesPaths = { "nes_header.s": "nes_header.asm" };
+    const includePaths = {};
+    for (let i = 0; i < nBanks; i++) {
+      const reg = regions[i];
+      blobs[`bank${i}_seg.asm`] = enc(
+        `; PRG bank ${i} wrapper (${reg.label}) — auto-generated by disasm({target:'project'}).\n` +
+        `.segment "PRG${i}"\n.include "bank${i}.asm"\n`
+      );
+      memLines.push(`    PRG${i}: start = $${reg.startAddress.toString(16).toUpperCase()}, size = $4000, type = ro, file = %O, fill = yes, fillval = $FF;`);
+      segLines.push(`    PRG${i}: load = PRG${i}, type = ro;`);
+      sourcesPaths[`bank${i}_seg.s`] = `bank${i}_seg.asm`;
+      includePaths[`bank${i}.asm`] = `bank${i}.asm`;
+    }
+    if (chrBanks > 0) {
+      blobs["nes_chars.asm"] = enc(`; CHR-ROM data.\n.segment "CHARS"\n        .incbin "chr.bin"\n`);
+      memLines.push(`    CHR: start = $0000, size = $${(chrBanks * 0x2000).toString(16).toUpperCase()}, type = ro, file = %O, fill = yes;`);
+      segLines.push(`    CHARS: load = CHR, type = ro;`);
+      sourcesPaths["nes_chars.s"] = "nes_chars.asm";
+    }
+    blobs["nes_rebuild.cfg"] = enc(
+      `# Banked NES rebuild .cfg — auto-generated by disasm({target:'project'}).\n` +
+      `# mapper ${mapper}, ${nBanks} x 16KB PRG banks (last bank at $C000)${chrBanks ? ", " + chrBanks + " x 8KB CHR" : ""}.\n` +
+      `# MEMORY order = file order: header, banks 0..${nBanks - 1}${chrBanks ? ", CHR" : ""}.\n` +
+      "MEMORY {\n" + memLines.join("\n") + "\n}\n" +
+      "SEGMENTS {\n" + segLines.join("\n") + "\n}\n"
+    );
     return {
       blobs,
       build: {
         output: "rom",
         platform: "nes",
-        sourcesPaths: { "prg.asm": "bank0.asm" },
+        sourcesPaths,
+        includePaths,
         ...(Object.keys(binaryIncludePaths).length ? { binaryIncludePaths } : {}),
-        inesHeader: {
-          prgBanks,
-          ...(chrBanks ? { chrBanks } : {}),
-          ...(mapper ? { mapper } : {}),
-          mirroring,
-          ...(battery ? { battery: true } : {}),
-        },
+        linkerConfigPath: "nes_rebuild.cfg",
       },
-      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.`,
+      verifiable: true,
+      notes:
+        `Banked NES (mapper ${mapper}, ${nBanks} x 16KB PRG): per-bank PRGn segment wrappers + ` +
+        `nes_header.asm (original 16 bytes) + nes_rebuild.cfg are all emitted and wired into ` +
+        `rebuild.json — a one-call byte-exact build() rebuild (linkerConfigPath keeps the cfg ` +
+        `out of context). Switchable banks land at $8000, the fixed top bank at $C000.`,
     };
   },
 
@@ -172,11 +237,75 @@ const PLANNERS = {
     };
   },
 
-  // ───────────────────────────────────────────── 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) {
+  // ───────────────────────────────────────────── Atari 7800 (.a78)
+  // build({platform:'atari7800'}) IS cc65/ca65 — one-call build() rebuilds, both
+  // shapes:
+  //   flat (≤48KB cart): planRegions keeps the 128-byte .a78 header inside
+  //     rom.asm; a single flat cc65 build reproduces the whole .a78. PROVEN.
+  //   SuperGame banked (>48KB cart): planRegions splits the header into its own
+  //     data region + one 16KB bank region per bank (last fixed @ $C000). Emit
+  //     NES-style glue: a78_header_seg.asm (HEADER segment, original 128 bytes),
+  //     bankN_seg.asm wrappers, multi-bank .cfg via linkerConfigPath.
+  atari7800(data, regions) {
+    const bankRegions = regions.filter((r) => r.name.startsWith("bank"));
+    if (bankRegions.length) {
+      const hasA78 = regions.some((r) => r.name === "a78_header");
+      const blobs = {};
+      const memLines = [];
+      const segLines = [];
+      const sourcesPaths = {};
+      const includePaths = {};
+      if (hasA78) {
+        const hdrBytes = Array.from(data.slice(0, 128))
+          .map((b) => "$" + b.toString(16).toUpperCase().padStart(2, "0")).join(", ");
+        // 128 bytes won't fit one .byte line cleanly — wrap at 16/line.
+        const rows = [];
+        for (let i = 0; i < 128; i += 16) {
+          rows.push("        .byte " + hdrBytes.split(", ").slice(i, i + 16).join(", "));
+        }
+        blobs["a78_header_seg.asm"] = enc(
+          `; .a78 header — the ORIGINAL 128 bytes, for a byte-exact rebuild.\n` +
+          `.segment "HEADER"\n${rows.join("\n")}\n`
+        );
+        memLines.push(`    HEADER: start = $0000, size = $0080, type = ro, file = %O, fill = yes;`);
+        segLines.push(`    HEADER: load = HEADER, type = ro;`);
+        sourcesPaths["a78_header_seg.s"] = "a78_header_seg.asm";
+      }
+      for (let i = 0; i < bankRegions.length; i++) {
+        const reg = bankRegions[i];
+        blobs[`bank${i}_seg.asm`] = enc(
+          `; SuperGame bank ${i} wrapper (${reg.label}) — auto-generated by disasm({target:'project'}).\n` +
+          `.segment "BANK${i}"\n.include "bank${i}.asm"\n`
+        );
+        memLines.push(`    BANK${i}: start = $${reg.startAddress.toString(16).toUpperCase()}, size = $4000, type = ro, file = %O, fill = yes, fillval = $FF;`);
+        segLines.push(`    BANK${i}: load = BANK${i}, type = ro;`);
+        sourcesPaths[`bank${i}_seg.s`] = `bank${i}_seg.asm`;
+        includePaths[`bank${i}.asm`] = `bank${i}.asm`;
+      }
+      blobs["a78_rebuild.cfg"] = enc(
+        `# Banked Atari 7800 (.a78 SuperGame) rebuild .cfg — auto-generated by disasm({target:'project'}).\n` +
+        `# MEMORY order = file order: ${hasA78 ? "header, " : ""}banks 0..${bankRegions.length - 1} (last bank fixed at $C000).\n` +
+        "MEMORY {\n" + memLines.join("\n") + "\n}\n" +
+        "SEGMENTS {\n" + segLines.join("\n") + "\n}\n"
+      );
+      return {
+        blobs,
+        build: {
+          output: "rom",
+          platform: "atari7800",
+          language: "asm",
+          sourcesPaths,
+          includePaths,
+          linkerConfigPath: "a78_rebuild.cfg",
+        },
+        verifiable: true,
+        notes:
+          `Banked Atari 7800 SuperGame (${bankRegions.length} x 16KB banks${hasA78 ? " + 128-byte .a78 header" : ""}): ` +
+          `per-bank BANKn segment wrappers${hasA78 ? " + a78_header_seg.asm (original 128 bytes)" : ""} + ` +
+          `a78_rebuild.cfg are emitted and wired into rebuild.json — a one-call byte-exact build() ` +
+          `rebuild. Switchable banks land at $8000, the fixed top bank at $C000.`,
+      };
+    }
     const org = (0x10000 - data.length) & 0xffff;
     const cfg =
       "# Atari 7800 .a78 rebuild .cfg — auto-generated by disasm({target:'project'}).\n" +
@@ -206,12 +335,43 @@ const PLANNERS = {
     };
   },
 
-  // ───────────────────────────────────────────── Atari 2600 (flat, dasm — no build() route)
+  // ───────────────────────────────────────────── Atari 2600 (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.)
+  // rebuild IS byte-exact via the native ca65/ld65 chain — flat carts via a flat
+  // fill .cfg; banked carts (F8/F6/F4 — every 4KB bank pages into $F000) via
+  // per-bank BANKn segment wrappers + a multi-area .cfg. Recipe in notes.
   atari2600(data, regions) {
+    if (regions.length > 1) {
+      const blobs = {};
+      const memLines = [];
+      const segLines = [];
+      for (let i = 0; i < regions.length; i++) {
+        blobs[`bank${i}_seg.asm`] = enc(
+          `; 2600 banked-cart bank ${i} wrapper — auto-generated by disasm({target:'project'}).\n` +
+          `.segment "BANK${i}"\n.include "bank${i}.asm"\n`
+        );
+        memLines.push(`    BANK${i}: start = $F000, size = $1000, type = ro, file = %O, fill = yes, fillval = $FF;`);
+        segLines.push(`    BANK${i}: load = BANK${i}, type = ro;`);
+      }
+      blobs["atari2600_rebuild.cfg"] = enc(
+        "# Atari 2600 banked-cart rebuild .cfg — auto-generated by disasm({target:'project'}).\n" +
+        `# ${regions.length} x 4KB banks, each at $F000, concatenated in file order.\n` +
+        "MEMORY {\n" + memLines.join("\n") + "\n}\n" +
+        "SEGMENTS {\n" + segLines.join("\n") + "\n}\n"
+      );
+      return {
+        blobs,
+        build: null,
+        verifiable: true,
+        notes:
+          `Atari 2600 banked cart (${regions.length} x 4KB banks @ $F000 — F8/F6/F4-style). 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):\n` +
+          `  ca65 bank0_seg.asm -o b0.o && … && ld65 -C atari2600_rebuild.cfg -o game.bin b0.o..b${regions.length - 1}.o\n` +
+          `(Wrappers + atari2600_rebuild.cfg are shipped as blobs.)`,
+      };
+    }
     const reg = regions[0];
     const cfg =
       "# Atari 2600 flat-cart rebuild .cfg — auto-generated by disasm({target:'project'}).\n" +
@@ -319,37 +479,76 @@ const PLANNERS = {
     };
   },
 
-  // ───────────────────────────────────────────── 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.
+  // ───────────────────────────────────────────── PC Engine (HuCard, ca65 — one-call)
+  // planRegions is now FAITHFUL (copier header split into its own region, NO
+  // trailing-pad trim), and build({platform:'pce', language:'asm'}) is cc65/ca65
+  // — the same match that makes NES a one-call rebuild. Both shapes:
+  //   flat (≤32KB): one CODE area at the top-of-space org.
+  //   banked (>32KB): one 8KB PAGE area per page (page 0 @ $E000 with the
+  //     vectors, pages 1+ @ $8000) via NES-style segment wrappers + .cfg.
+  // A copier header, when present, is re-emitted as a HEADER segment so the
+  // single output file is the complete original .pce.
   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";
+    const hasCopier = regions.some((r) => r.name === "copier_header");
+    const codeRegions = regions.filter((r) => r.kind !== "data");
+    const blobs = {};
+    const memLines = [];
+    const segLines = [];
+    const sourcesPaths = {};
+    const includePaths = {};
+    if (hasCopier) {
+      const rows = [];
+      for (let i = 0; i < 512; i += 16) {
+        rows.push("        .byte " + Array.from(data.slice(i, i + 16))
+          .map((b) => "$" + b.toString(16).toUpperCase().padStart(2, "0")).join(", "));
+      }
+      blobs["copier_header_seg.asm"] = enc(
+        `; 512-byte copier header — the ORIGINAL bytes, for a byte-exact rebuild.\n` +
+        `.segment "HEADER"\n${rows.join("\n")}\n`
+      );
+      memLines.push(`    HEADER: start = $0000, size = $0200, type = ro, file = %O, fill = yes;`);
+      segLines.push(`    HEADER: load = HEADER, type = ro;`);
+      sourcesPaths["copier_header_seg.s"] = "copier_header_seg.asm";
+    }
+    const banked = codeRegions.length > 1;
+    for (let i = 0; i < codeRegions.length; i++) {
+      const reg = codeRegions[i];
+      const segName = banked ? `PAGE${i}` : "CODE";
+      blobs[`${reg.name}_seg.asm`] = enc(
+        `; ${reg.label} wrapper — auto-generated by disasm({target:'project'}).\n` +
+        `.segment "${segName}"\n.include "${reg.file}"\n`
+      );
+      memLines.push(`    ${segName}: start = $${reg.startAddress.toString(16).toUpperCase()}, size = $${reg.bytes.length.toString(16).toUpperCase()}, type = ro, file = %O, fill = yes, fillval = $FF;`);
+      segLines.push(`    ${segName}: load = ${segName}, type = ro;`);
+      sourcesPaths[`${reg.name}_seg.s`] = `${reg.name}_seg.asm`;
+      includePaths[reg.file] = reg.file;
+    }
+    blobs["pce_rebuild.cfg"] = enc(
+      `# PC Engine HuCard rebuild .cfg — auto-generated by disasm({target:'project'}).\n` +
+      `# MEMORY order = file order: ${hasCopier ? "copier header, " : ""}` +
+      (banked ? `pages 0..${codeRegions.length - 1} (8KB each; page 0 holds the vectors).\n` : `the flat HuCard image.\n`) +
+      "MEMORY {\n" + memLines.join("\n") + "\n}\n" +
+      "SEGMENTS {\n" + segLines.join("\n") + "\n}\n"
+    );
     return {
-      blobs: { "pce_rebuild.cfg": enc(cfg) },
-      build: null,
-      verifiable: false,
+      blobs,
+      build: {
+        output: "rom",
+        platform: "pce",
+        language: "asm",
+        sourcesPaths,
+        includePaths,
+        linkerConfigPath: "pce_rebuild.cfg",
+      },
+      verifiable: true,
       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.`,
+        `PC Engine HuCard (${banked ? codeRegions.length + " x 8KB pages" : "flat " + codeRegions[0].bytes.length + " B"}` +
+        `${hasCopier ? " + 512-byte copier header (re-emitted as a HEADER segment)" : ""}): ` +
+        `segment wrappers + pce_rebuild.cfg are emitted and wired into rebuild.json — a one-call ` +
+        `byte-exact build() rebuild (the pce asm toolchain IS cc65/ca65, same as NES). ` +
+        (banked ? `Page 0 lands at $E000 (reset MPR7 mapping — vectors live there); pages 1+ at $8000 ` +
+          `(an ASSUMED window — the game's MPR writes decide at runtime; only branch-label cosmetics ` +
+          `depend on it, the bytes are exact regardless).` : ``),
     };
   },
 
@@ -364,8 +563,36 @@ const PLANNERS = {
   // + 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 bankRegions = regions.filter((r) => r.name.startsWith("bank"));
+    if (bankRegions.length) {
+      // megaROM (>32KB, ASCII16-style 16KB banks). Bank 0's region starts at
+      // $4010 (header split out); banks 1+ are full 16KB at $8000. Native
+      // per-bank recipe: assemble, extract at each org, concatenate after the
+      // header bytes.
+      const blobs = {};
+      if (hasHeader) blobs["msx_header.bin"] = data.slice(0, 16);
+      return {
+        blobs,
+        build: null,
+        verifiable: true,
+        notes:
+          `MSX megaROM (${bankRegions.length} x 16KB banks: bank 0 @ $4010 after the "AB" header` +
+          `${hasHeader ? " — shipped as msx_header.bin" : ""}, banks 1+ @ $8000, an ASSUMED ASCII16-style ` +
+          `window — only branch-label cosmetics depend on it, the bytes are exact regardless). ` +
+          `build({platform:'msx'}) is SDCC — it can't reassemble the GNU-\`as\` bankN.asm. Rebuild ` +
+          `natively (bundled z80 binutils, byte-identical), assembling each bank and concatenating:\n` +
+          bankRegions
+            .map(
+              (r) =>
+                `  z80-elf-as -march=z80 ${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=${r.bytes.length}`
+            )
+            .join("\n") +
+          `\n  cat ${hasHeader ? "msx_header.bin " : ""}${bankRegions.map((r) => r.name + ".bin").join(" ")} > rebuilt.rom`,
+      };
+    }
+    const reg = regions.find((r) => r.file === "rom.asm") ?? regions[0];
     const blobs = {};
     if (hasHeader) blobs["msx_header.bin"] = data.slice(0, 16);
     const bodyStart = hasHeader ? 16 : 0;
@@ -455,10 +682,33 @@ const PLANNERS = {
  * GNU-`as` rom.asm); native recipe in notes, byte-identical proven.
  */
 function planSegaFlat(platform, data, regions) {
+  const name = platform === "sms" ? "Master System" : "Game Gear";
+  if (regions.length > 1) {
+    // Sega-mapper banked cart: one full 16KB region per bank (no pad trim) —
+    // assemble each at its window org, extract, concatenate. Same per-bank
+    // native recipe shape as Game Boy.
+    return {
+      blobs: {},
+      build: null,
+      verifiable: true,
+      notes:
+        `${name} Sega-mapper banked cart (${regions.length} x 16KB banks: bank 0 @ $0000, bank 1 @ $4000, ` +
+        `banks 2+ @ $8000 — their slot-2 window). build({platform:'${platform}'}) is SDCC — it can't ` +
+        `reassemble the GNU-\`as\` bankN.asm. Rebuild natively (bundled z80 binutils, byte-identical), ` +
+        `assembling each bank and concatenating:\n` +
+        regions
+          .map(
+            (r) =>
+              `  z80-elf-as -march=z80 ${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=${r.bytes.length}`
+          )
+          .join("\n") +
+        `\n  cat ${regions.map((r) => r.name + ".bin").join(" ")} > rebuilt.${platform === "sms" ? "sms" : "gg"}`,
+    };
+  }
   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,