romdevtools 0.88.0 → 0.89.0

package/AGENTS.md

@@ -107,7 +107,13 @@ questions, and running both early is normal.** A good default:
 3. **Disassemble / trace** whenever the hack is about CODE or about data the
    cheats don't cover: `disasm({target:'project'})` for a rebuildable project
    (then edit a region `.asm` and `build({output:'reassemble', platform, path})` to
-   rebuild a byte-identical ROM in one call — the "cmp before commit" gate),
+   rebuild a byte-identical ROM in one call — the "cmp before commit" gate; a
+   `.gitignore` is written so the kept `original.rom` can't be committed. **Large
+   ROM (≥512KB, e.g. a 1MB SNES/Genesis cart)? Pass `background:true`** and poll
+   `disasm({target:'project', job, outputDir})` — the reassemble can take minutes
+   and would otherwise time the call out. A uniform-fill/padding bank reports
+   `fill:true` + `readablePercent:null`, so "low % = data bank" isn't fooled by a
+   $FF pad tail),
    `disasm({target:'references'})` for "what touches this address", `breakpoint({on:'write'})` for the exact
    instruction that wrote a byte, `watch({on:'mem'})`/`breakpoint({on:'write',precision:'sampled'})` to find an address
    empirically. For STRUCTURE — "what are the functions, how do they call each

package/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to `romdevtools`. Dates are release dates.
 (Published as `romdev-mcp` through 0.11.0; renamed to `romdevtools` in 0.13.0 —
 the `romdev-mcp` bin is kept as an alias.)
 
+## 0.89.0 — 2026-07-14
+
+Large-ROM `disasm({target:'project'})` no longer times out the tool call — the last of the
+findings from the 1 MB ActRaiser run. A multi-MB cart (32-bank SNES/Genesis) can take minutes to
+reassemble; that used to time the MCP call out mid-run even though the server finished writing every
+bank.
+
+- **Parallelized the per-bank reassembly.** The region loop was strictly sequential (one bank at a
+  time, one WASM worker). It now fires all regions concurrently and the worker pool caps real
+  parallelism at `ROM_DEV_WASM_POOL_SIZE` (default 2) — so a 32-bank cart runs pool-many banks at
+  once instead of serializing 32 heal loops. Order + byte-exactness preserved.
+- **`disasm({target:'project', background:true})` — the timeout-proof path.** For a large ROM, start
+  the disassembly in the background and get a `{jobId}` back IMMEDIATELY; the server keeps working
+  even if the call's client times out. Poll with `disasm({target:'project', job, outputDir})` — it
+  reports `regionsDone/regionsTotal` while running, then returns the exact same completion payload a
+  synchronous call would, once `status:'done'` (or the reason on `'error'`). Job state lives in a
+  `.romdev-job.json` in the output dir (stateless across calls; git-ignored). The sync path is
+  unchanged and remains the default for normal-size ROMs.
+
+## 0.88.2 — 2026-07-13
+
+Two fixes from a real-world `disasm({target:'project'})` + `build({output:'reassemble'})` run — a
+1 MB commercial SNES ROM (which rebuilt **byte-identical**, validating 0.88.0 on real hardware data).
+
+- **ROM data can't be committed by accident.** `disasm({target:'project'})` keeps a verbatim
+  `original.rom` (the reassemble splice template) in the project dir — copyrighted cartridge bytes.
+  It now also writes a `.gitignore` that excludes `original.rom` plus common ROM extensions, so a
+  scaffolded project can't check the ROM into git. If a `.gitignore` already exists, the rules are
+  appended (deduped), never clobbered. (No `*.md` in the list — it collides with Markdown / BUILD.md;
+  `original.rom` covers the template on every platform regardless.) The payload advertises
+  `romProtected: ".gitignore"`.
+- **`readablePercent` no longer lies about padding.** A uniform-fill bank (all `$FF` or `$00`)
+  disassembles into junk instructions (`sbc $FFFFFF,x` …) and used to report a bogus ~100% readable —
+  so the *emptiest* bank looked the "most readable," inverting the "low % = data bank" heuristic. Fill
+  regions are now detected (≥99.5% one byte, ≥256 bytes) and reported honestly: `readablePercent: null`
+  + `fill: true` + `fillByte`, excluded from the code-only `readablePercentAvg`, and labeled in the
+  region `.asm` header. The payload reports `fillRegions` count.
+
 ## 0.88.0 — 2026-07-12
 
 - **`build({output:'reassemble'})` — the UNIFORM byte-exact ROUND-TRIP.** `disasm({target:'project'})`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.88.0",
+  "version": "0.89.0",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 17 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, PlayStation, N64, Dreamcast, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
   "type": "module",
   "main": "src/mcp/server.js",
@@ -59,7 +59,7 @@
     "romdev-core-fceumm": "0.11.0",
     "romdev-core-flycast": "0.2.0",
     "romdev-core-gambatte": "0.10.0",
-    "romdev-core-gametank": "0.2.0",
+    "romdev-core-gametank": "0.3.0",
     "romdev-core-geargrafx": "0.8.0",
     "romdev-core-gpgx": "0.13.0",
     "romdev-core-handy": "0.8.0",

package/src/mcp/tools/disasm.js

@@ -1043,40 +1043,147 @@ async function disassembleRomCore(args) {
       return jsonContent({ ...baseResult, ok: true, asm });
 }
 
-export async function disassembleProjectCore({ path: romPath, outputDir, platform }) {
+// The job-status file dropped in the output dir so a background disassembly's
+// progress survives across MCP calls (no in-memory registry — poll reads the
+// file). Presence + `status` is the source of truth.
+const JOB_FILE = ".romdev-job.json";
+
+/**
+ * disasm({target:'project'}) orchestrator. Three modes:
+ *   - default (sync): run to completion, return the full payload.
+ *   - background:true → START the work detached, return {jobId} immediately (for
+ *     multi-MB ROMs whose reassemble would time out the tool call).
+ *   - job:'<id>' → POLL: read the status file; return progress, or the final
+ *     payload once done, or the error if it failed.
+ */
+export async function disassembleProjectCore(args) {
+  const { path: romPath, outputDir, platform, background, job } = args;
+
+  // ── POLL an existing background job ────────────────────────────────────────
+  if (job) {
+    if (!outputDir) throw new Error("disasm({target:'project', job}): outputDir is required to locate the job status file.");
+    let st;
+    try { st = JSON.parse(await readFile(nodePath.join(outputDir, JOB_FILE), "utf8")); }
+    catch { throw new Error(`disasm({target:'project', job:'${job}'}): no job found in '${outputDir}' (missing ${JOB_FILE}). Start one with background:true first.`); }
+    if (st.jobId !== job) throw new Error(`disasm({target:'project'}): job '${job}' doesn't match the job in '${outputDir}' ('${st.jobId}'). Poll the outputDir you started.`);
+    if (st.status === "running") {
+      return jsonContent({
+        ok: null, status: "running", jobId: job, platform: st.platform, outputDir,
+        regionsDone: st.regionsDone ?? 0, regionsTotal: st.regionsTotal ?? null,
+        note: `Still disassembling — ${st.regionsDone ?? 0}/${st.regionsTotal ?? "?"} regions done. Poll again: disasm({target:'project', job:'${job}', outputDir:'${outputDir}'}).`,
+      });
+    }
+    if (st.status === "error") {
+      return jsonContent({ ok: false, status: "error", jobId: job, platform: st.platform, outputDir, error: st.error, note: `Background disassembly FAILED: ${st.error}` });
+    }
+    // done → hand back the stored final payload verbatim.
+    return jsonContent(st.result);
+  }
+
+  // ── START a background job ─────────────────────────────────────────────────
+  if (background) {
+    if (!outputDir) throw new Error("disasm({target:'project', background:true}): outputDir is required (the job writes its status + output there).");
+    const resolved = platform ?? sniffPlatformFromPath(romPath);
+    if (!resolved) throw new Error(`disassembleProject: could not detect platform from '${romPath}'. Pass platform explicitly.`);
+    await mkdir(outputDir, { recursive: true });
+    // A deterministic-but-unique id (no Date.now/random in scripts; here we're in
+    // the server, so a monotonic counter + the dir is fine and readable).
+    const jobId = `job-${resolved}-${(bgJobCounter++).toString(36)}`;
+    const statusPath = nodePath.join(outputDir, JOB_FILE);
+    await writeFile(statusPath, JSON.stringify({ jobId, status: "running", platform: resolved, regionsDone: 0, regionsTotal: null }, null, 2));
+    // Fire-and-forget: run the work, updating the status file as it goes. Errors
+    // are caught and recorded in the status file (the poll surfaces them) — an
+    // unhandled rejection here must never crash the server.
+    runProjectDisassembly(args, resolved, { statusPath, jobId }).then(
+      async (payload) => { await writeFile(statusPath, JSON.stringify({ jobId, status: "done", platform: resolved, result: payload }, null, 2)); },
+      async (err) => { await writeFile(statusPath, JSON.stringify({ jobId, status: "error", platform: resolved, error: String(err?.message ?? err) }, null, 2)).catch(() => {}); },
+    );
+    return jsonContent({
+      ok: null, status: "running", jobId, platform: resolved, outputDir,
+      note: `Disassembly started in the BACKGROUND (large ROM). Poll for completion: disasm({target:'project', job:'${jobId}', outputDir:'${outputDir}'}). ` +
+        `The server keeps working even if this call's client times out; the poll returns the full result when done.`,
+    });
+  }
+
+  // ── SYNC (default) ─────────────────────────────────────────────────────────
+  const resolved = platform ?? sniffPlatformFromPath(romPath);
+  if (!resolved) throw new Error(`disassembleProject: could not detect platform from '${romPath}'. Pass platform explicitly.`);
+  await mkdir(outputDir, { recursive: true });
+  return jsonContent(await runProjectDisassembly(args, resolved, null));
+}
+
+let bgJobCounter = 1;
+
+/**
+ * The actual disassemble-project work. Returns the payload OBJECT (not wrapped in
+ * jsonContent — the caller wraps, so the same object can also be stored in the job
+ * status file). `progress` (or null) receives {statusPath, jobId} to checkpoint
+ * per-region completion for the poll surface.
+ */
+async function runProjectDisassembly({ path: romPath, outputDir }, resolved, progress) {
       const { reassembleForPlatform, CPU_FAMILY } = await import("../../toolchains/common/reassemble.js");
       const data = new Uint8Array(await readFile(romPath));
-      const resolved = platform ?? sniffPlatformFromPath(romPath);
-      if (!resolved) throw new Error(`disassembleProject: could not detect platform from '${romPath}'. Pass platform explicitly.`);
       await mkdir(outputDir, { recursive: true });
 
       // Plan the regions to disassemble for this platform (per-bank for banked
       // ROMs; one region for flat ROMs). Each region → its own byte-exact .asm.
       const regions = planRegions(resolved, data);
       if (!regions.length) throw new Error(`disassembleProject: no regions planned for '${resolved}' (unsupported or empty ROM).`);
+      if (progress) {
+        await writeFile(nodePath.join(outputDir, JOB_FILE),
+          JSON.stringify({ jobId: progress.jobId, status: "running", platform: resolved, regionsDone: 0, regionsTotal: regions.length }, null, 2)).catch(() => {});
+      }
 
-      const out = [];
-      for (const reg of regions) {
+      // Reassemble every region CONCURRENTLY. Each region is independent (its own
+      // WASM worker job + its own file write), and the worker pool caps real
+      // parallelism at ROM_DEV_WASM_POOL_SIZE — so firing all banks at once runs
+      // pool-many at a time and cuts wall-time by that factor on multi-bank ROMs
+      // (a 32-bank SNES cart no longer serializes 32 heal loops). Order is
+      // preserved by mapping over indices. (For very large ROMs the async-job
+      // path below still applies so the client never times out mid-run.)
+      let regionsDone = 0;
+      const out = await Promise.all(regions.map(async (reg) => {
         // Known-data regions (e.g. the GBA cartridge header) are emitted as a
         // clean `.byte` dump — byte-exact by construction, NOT a failed disasm.
         const r = reg.kind === "data"
           ? { ok: true, readablePercent: 0, source: dataRegionSource(reg.bytes, reg.startAddress, CPU_FAMILY[resolved]), note: "data region (not code)" }
           : await reassembleForPlatform({ platform: resolved, bytes: reg.bytes, startAddress: reg.startAddress });
+        // A uniform-FILL region ($FF/$00 padding) disassembles into junk that
+        // reports a high readablePercent — a trap (the emptiest bank looks the
+        // "most readable"). Detect it and report readability HONESTLY as null +
+        // a `fill` flag, so `readablePercent` never lies about padding.
+        const fillByte = uniformFillByte(reg.bytes);
+        const isFill = fillByte != null && reg.kind !== "data";
+        const readablePercent = isFill ? null : r.readablePercent;
         const header = `; ${reg.label} — ${reg.bytes.length} bytes @ $${reg.startAddress.toString(16).toUpperCase()} ` +
           `(file 0x${reg.fileOffset.toString(16).toUpperCase()}), ${resolved}\n` +
-          `; round-trip: ${r.ok ? "BYTE-EXACT" : "FAILED"} · readable ${r.readablePercent}%` +
+          `; round-trip: ${r.ok ? "BYTE-EXACT" : "FAILED"} · ` +
+          (isFill ? `FILL region (all $${fillByte.toString(16).toUpperCase().padStart(2, "0")}) — readability N/A`
+                  : `readable ${r.readablePercent}%`) +
           (r.note ? ` · ${r.note}` : "") + "\n\n";
         await writeFile(nodePath.join(outputDir, reg.file), header + r.source);
-        out.push({
+        // Checkpoint progress for the poll surface (background jobs only).
+        regionsDone++;
+        if (progress) {
+          await writeFile(nodePath.join(outputDir, JOB_FILE),
+            JSON.stringify({ jobId: progress.jobId, status: "running", platform: resolved, regionsDone, regionsTotal: regions.length }, null, 2)).catch(() => {});
+        }
+        return {
           region: reg.name, file: reg.file, startAddress: "$" + reg.startAddress.toString(16).toUpperCase(),
-          bytes: reg.bytes.length, roundTripOk: r.ok, readablePercent: r.readablePercent,
+          bytes: reg.bytes.length, roundTripOk: r.ok, readablePercent,
           ...(reg.kind === "data" ? { kind: "data" } : {}),
+          ...(isFill ? { fill: true, fillByte: "$" + fillByte.toString(16).toUpperCase().padStart(2, "0") } : {}),
           ...(r.note ? { note: r.note } : {}),
-        });
-      }
+        };
+      }));
 
       const allOk = out.every((r) => r.roundTripOk);
-      const avgReadable = Math.round(out.reduce((s, r) => s + r.readablePercent, 0) / out.length);
+      // Average readability over CODE regions only — fill regions have no
+      // meaningful percent (readablePercent:null) and would skew the average.
+      const codeRegions = out.filter((r) => r.readablePercent != null);
+      const avgReadable = codeRegions.length
+        ? Math.round(codeRegions.reduce((s, r) => s + r.readablePercent, 0) / codeRegions.length)
+        : 0;
 
       // Make the project TURNKEY: write the rebuild glue (data blobs, the exact
       // build() call, and human-readable instructions) so it rebuilds without
@@ -1110,6 +1217,22 @@ export async function disassembleProjectCore({ path: romPath, outputDir, platfor
       // ORIGINAL rom (kept as original.rom) at its file offset, so the header,
       // inter-region gaps, and trailing pad come back verbatim. See toolchain.js.
       await writeFile(nodePath.join(outputDir, "original.rom"), data);
+      // original.rom is a verbatim copy of the source ROM (the reassemble splice
+      // template) — copyrighted cartridge data that must NEVER be committed. Emit
+      // a .gitignore that excludes it plus common ROM extensions so a scaffolded
+      // project can't accidentally check the ROM into git. Append (deduped) if a
+      // .gitignore already exists so we don't clobber the user's rules.
+      // NOTE: no `*.md` — Genesis ROMs share that extension with Markdown, and
+      // ignoring it would exclude BUILD.md. `original.rom` covers the template on
+      // every platform regardless; the extension list is a belt-and-suspenders
+      // for any raw ROM a user drops in the dir.
+      await ensureGitignore(outputDir, [
+        "# romdev: never commit ROM data (original.rom is the reassemble template)",
+        "original.rom",
+        "*.rom", "*.nes", "*.sfc", "*.smc", "*.gb", "*.gbc", "*.gba",
+        "*.gen", "*.sms", "*.gg", "*.a26", "*.a78", "*.lnx", "*.pce", "*.gtr",
+        ".romdev-job.json",
+      ]);
       const reassembleManifest = {
         platform: resolved,
         romTemplate: "original.rom",  // relative to the project dir
@@ -1127,13 +1250,17 @@ export async function disassembleProjectCore({ path: romPath, outputDir, platfor
         JSON.stringify(reassembleManifest, null, 2) + "\n"
       );
 
-      return jsonContent({
+      // Return the raw payload OBJECT (the orchestrator wraps it in jsonContent
+      // for the sync path, or stores it in the job status file for background).
+      return {
         ok: allOk,
         path: romPath,
         platform: resolved,
         regions: out,
         roundTrip: { regions: out.length, allByteExact: allOk, failed: out.filter((r) => !r.roundTripOk).map((r) => r.region) },
-        readablePercentAvg: avgReadable,
+        readablePercentAvg: avgReadable,   // over CODE regions only; fill/padding excluded
+        fillRegions: out.filter((r) => r.fill).length,  // padding banks flagged (readablePercent:null), NOT counted as readable
+        romProtected: ".gitignore",        // original.rom + ROM extensions git-ignored so the ROM can't be committed
         rebuild: {
           blobs: writtenBlobs,
           buildCall: absBuild,        // the exact build({...}) args to reproduce the ROM
@@ -1151,7 +1278,45 @@ export async function disassembleProjectCore({ path: romPath, outputDir, platfor
               ? ` (build() one-call rebuild also available via rebuild.json.)`
               : ``)
           : `Some regions did NOT round-trip byte-exact — see regions[].note. build({output:'reassemble', platform:'${resolved}', path:'${outputDir}'}) still rebuilds the original bytes (edited regions must reassemble to their length).`,
-      });
+      };
+}
+
+/**
+ * If a region is (near-)uniform fill — one byte value repeated — return that
+ * byte; else null. Padding banks ($FF/$00) disassemble into junk that reports a
+ * bogus-high readablePercent, so we flag them and exclude them from readability.
+ * Threshold: ≥99.5% one value AND ≥256 bytes (small regions aren't "padding"),
+ * so a real code bank with incidental repeats is never misflagged.
+ */
+function uniformFillByte(bytes) {
+  if (!bytes || bytes.length < 256) return null;
+  const first = bytes[0];
+  let same = 0;
+  for (let i = 0; i < bytes.length; i++) if (bytes[i] === first) same++;
+  return same / bytes.length >= 0.995 ? first : null;
+}
+
+/**
+ * Ensure a project dir's .gitignore contains each of `entries`, without
+ * clobbering an existing one. Creates the file if absent; otherwise appends only
+ * the lines not already present (whitespace-trimmed match), preserving the user's
+ * existing rules and order. Blank/comment lines are appended verbatim only if the
+ * whole block is new (we don't dedupe comments against existing text).
+ */
+async function ensureGitignore(outputDir, entries) {
+  const gi = nodePath.join(outputDir, ".gitignore");
+  let existing = "";
+  try { existing = await readFile(gi, "utf8"); } catch { /* no .gitignore yet */ }
+  const have = new Set(existing.split(/\r?\n/).map((l) => l.trim()).filter(Boolean));
+  const toAdd = entries.filter((e) => {
+    const t = e.trim();
+    if (!t) return false;
+    if (t.startsWith("#")) return existing === "" || !existing.includes(t); // keep the header once
+    return !have.has(t);
+  });
+  if (!toAdd.length) return;
+  const prefix = existing === "" ? "" : (existing.endsWith("\n") ? "" : "\n");
+  await writeFile(gi, existing + prefix + toAdd.join("\n") + "\n");
 }
 
 /** Rewrite a planRebuild build()'s bare *Paths filenames to absolute paths. */
@@ -1178,8 +1343,9 @@ function renderBuildMd({ platform, romPath, outputDir, regions, blobs, build, ve
     lines.push(`- \`${r.file}\` — ${r.region}${r.kind === "data" ? " (data)" : ""}, byte-exact${r.roundTripOk === false ? " ⚠ round-trip FAILED" : ""}.`);
   }
   for (const b of blobs) lines.push(`- \`${b.file}\` — ${b.bytes} bytes of binary data (extracted from the ROM; do not hand-edit).`);
-  lines.push("- `original.rom` — a verbatim copy of the source ROM (the rebuild template; do not edit).");
+  lines.push("- `original.rom` — a verbatim copy of the source ROM (the rebuild template; do not edit). **Copyrighted ROM data — never commit it. A `.gitignore` excluding it (and ROM extensions) is written for you.**");
   lines.push("- `reassemble.json` — the region→offset manifest the one-call rebuild reads.");
+  lines.push("- `.gitignore` — keeps `original.rom` + raw ROM files out of git (appended if you already had one).");
   if (build) lines.push("- `rebuild.json` — the alternate cc65-native `build()` args below.");
   lines.push("");
 
@@ -1547,7 +1713,11 @@ export function registerDisasmTools(server, z) {
     "'project' = turn a ROM into a complete re-buildable disassembly in one call across all systems; splits into " +
     "regions (PER-BANK on every banked format: NES mappers, SNES LoROM, GB MBC, Sega-mapper SMS/GG, MSX megaROM, " +
     "2600 F8/F6/F4, 7800 SuperGame, >32KB HuCards), REASSEMBLES each and verifies BYTE-EXACT (`roundTripOk`); " +
-    "non-faithful lines fall back to `.byte` so it ALWAYS rebuilds; `readablePercent` reports instruction-vs-data. " +
+    "non-faithful lines fall back to `.byte` so it ALWAYS rebuilds; `readablePercent` reports instruction-vs-data (a uniform-FILL " +
+    "bank — all $FF/$00 padding — reports `readablePercent:null` + `fill:true`, NOT a bogus 100%). Also writes a `.gitignore` " +
+    "so the kept `original.rom` (copyrighted ROM data) can't be committed. **LARGE ROM (≥512KB, e.g. a 1MB SNES cart)? Pass " +
+    "`background:true`** — the reassemble can take minutes and would time out the call; you get a `{jobId}` immediately, then poll " +
+    "`disasm({target:'project', job, outputDir})` (reports `regionsDone/regionsTotal`, then the full result when `status:'done'`). " +
     "REBUILD (one call, ALL 15 classic platforms): `build({output:'reassemble', platform, path})` turns the project " +
     "dir back into a BYTE-IDENTICAL ROM — it assembles each region + splices them into the kept `original.rom` " +
     "(header/gaps/pad verbatim). Edit a region `.asm` first for a change: a same-length edit rebuilds a modified " +
@@ -1613,6 +1783,8 @@ export function registerDisasmTools(server, z) {
       annotateFileOffsets: z.boolean().default(true).describe("target=rom: append `; @0xNNNN` file offset to every line (for romPatch)."),
       // project
       outputDir: z.string().optional().describe("target=project: directory to write the project into (one .asm per region). target=recompile: directory to write main.asm + nes_seam.asm for build({platform:'snes'})."),
+      background: z.boolean().default(false).describe("target=project: run the disassembly in the BACKGROUND and return IMMEDIATELY with a {jobId} instead of blocking. Use this for LARGE ROMs (≥512KB — a multi-bank SNES/Genesis cart) where the full reassemble can take minutes and would otherwise time out the tool call. Poll with disasm({target:'project', job:'<jobId>', outputDir}) until status is 'done' (or 'error'); the final poll returns the same payload the synchronous call would have. Small ROMs don't need this — they finish well within the call."),
+      job: z.string().optional().describe("target=project: poll a background job started with background:true. Pass the jobId you got back (and the same outputDir). Returns {status:'running', regionsDone, regionsTotal} while working, or the full completion payload once status is 'done'. On 'error' the failure reason is included."),
       targetPlatform: z.string().optional().describe("target=recompile: the platform to EMIT (default 'snes'). The engine is generic (lift source→IR→emit target): 'snes' = 1:1 emulation-mode port with the PPU render layers (withShim/withRuntime); 'genesis' = real 6502→68000 LOGIC translation (presentation stubbed, verify with frame({op:'compareRam'})). Source `platform` is 'nes' today; more source lifters land as built."),
       withShim: z.boolean().default(false).describe("target=recompile: phase-1 STATIC render (default off). Emit the NES-PPU-on-SNES shim — boots the original ROM, converts its tiles/nametable/palette to SNES VRAM/CGRAM data + a 65816 upload routine that draws the original's STATIC boot screen on SNES (verified on snes9x). Draws the first screen only; sprites don't animate. For a LIVE port use withRuntime instead."),
       withRuntime: z.boolean().default(false).describe("target=recompile: phase-2 LIVE render (default off). Implies withShim (BG) and adds the per-frame runtime: each vblank it flushes the game's shadow OAM to SNES sprites and runs the game's own NMI handler, so SPRITES ANIMATE and the game's per-frame logic runs — the port plays, not just boots to a screenshot. Background is static from the shim; live nametable/scroll streaming is phase 3. Verified on snes9x."),