romdevtools 0.40.2 → 0.41.0

package/AGENTS.md

@@ -66,11 +66,11 @@ Skip playtest only when there's clearly no human in the loop: CI runs, automated
 - `input` — drive controllers, look up hardware bit layouts. `navigate` walks menus by advancing on SCREEN CHANGE (not fixed frames) and reports whether each press was consumed — the fast, reliable way to script a UI.
 - `state` — savestates and forensic state inspection (`state({op:'save'})`, `state({op:'load'})`, `state({op:'export'})` a slot to disk without touching the live host, `state({op:'list'})`, `state({op:'dump'})`)
 - `memory` — read/write VRAM/OAM/CGRAM/ARAM and other regions (all 14 platforms). `memory({op:'read'})` takes `offsets:[…]` to batch scattered reads in one call. **`memory({op:'search'})`/`memory({op:'searchNext'})`** = the Cheat-Engine value-search loop ("find the address of X, narrow as X changes") — relative compares (`inc`/`dec`/`changed`) work as the FIRST narrow (baselines recorded at seed), and `as:'bcd'`/`as:'digits'` search packed-BCD scores and digit-per-byte HUD buffers (any constant tile base) when stored ≠ displayed. **`memory({op:'searchUnknown'})`** is the unknown-initial-value hunt — seed the whole region with no value, then narrow by `dec`/`inc`/`changed` across events (the value you can't read off the HUD). **`memory({op:'readCart'})`** reads the loaded cart image to confirm a patch is live (pass `{cpuAddress, bank}` to read a banked CPU address on NES/SNES). **`memory({op:'classify'})`** says whether bytes look like ASCII/code/tile-data (kills the "found table that's really a string" trap). `memory({op:'snapshot'})` + `memory({op:'diff'})` answer "which bytes changed across this event?" (diff defaults to a clustered summary with stride detection; small clusters carry before/after hex, `minDelta` filters churn, and predicate filters — `changeDir:'inc'|'dec'`, `deltaEq`, `beforeMin/Max`, `afterMin/Max` — keep only the bytes that moved the way you expect; `outputPath`+`echo:false` route the full list to disk); **`memory({op:'diffRuns', portsA, portsB?})`** answers "which byte does this INPUT drive?" in one call (same start state run twice under two inputs, only the divergent bytes return); `state({op:'diff'})` is the coarse whole-machine version. Reads routed to disk take `echo:false` to skip the inline hex.
-- `debug` — **`frame({op:'verify'})`** (NO-VISION render-health: one call answers "is the game actually rendering / alive?" on all 14 — fuses a framebuffer pixel scan with the per-platform render-enable/NMI decode; `{verified:true|false|null, issues[], pixels, render}`, frame-0-guarded so it never cries wolf on boot), `sprites({op:'inspect'})`, `palette({source:'live'})`, `cpu({op:'read'})` (all 14), `audioDebug({op:'inspect'})` (the 12 systems with a sound chip — all but Atari 2600/7800; pass `frames:N` to TRACE a per-channel note-timeline for headless melody asserts), `background({view:'renderState'})`, `breakpoint({on:'write'})` (write watchpoint, all 14; EVERY hit on EVERY platform carries `registersAtHit` — the register file frozen at the hit instant, the only honest read since live regs drift after a hit — and the CPU stays frozen until the hit is cleared), **`watch({on:'dma', precision:'sampled'})`** (Genesis: which ROM offset a VRAM graphic was DMA'd from), **`watch({on:'copy'})`** (ALL 14: every write landing in a VRAM window logged with the EXECUTING instruction's PC — the generic 'which routine uploads this graphic?'; port-based video memory hooked in-core incl. the SNES DMA path, CPU-mapped VRAM via the range log), **`disasm({target:'bytes'|'rom'|'references'|'project'})`** (ALL 14 — native binutils objdump per CPU, incl. GBA ARM7/Thumb; the byte-exact `disasm({target:'project'})` reassembles through native as/ld/objcopy; banked carts — NES mappers, SNES LoROM, GB MBC, Sega mapper, MSX megaROM, 2600 F8/F6/F4, 7800 SuperGame, >32KB HuCards — are split and reference-scanned PER BANK, refs tagged `prgBank`/`romBank`), plus the **Rizin/Ghidra RE engine** `disasm({target:'cfg'|'xrefs'|'functions'|'decompile'})` (ALL 14 — control-flow graphs, deep xrefs, auto-detected functions, and Ghidra C pseudocode; quality excellent on GBA/Genesis, rough on 6502) + `symbols({op:'analyze'})` (one-shot structural map), `symbols({op})` lookup, `background({view:'rendered'})`, plus **`cheats({op})`** (`cheats({op:'lookup'})` = a free labeled RAM/code map for known ROMs, `cheats({op:'search'})` to fuzzy-find a game by name, `cheats({op:'apply'})`/`cheats({op:'clear'})` non-destructively, `cheats({op:'make'})` to create codes)
+- `debug` — **`frame({op:'verify'})`** (NO-VISION render-health: one call answers "is the game actually rendering / alive?" on all 14 — fuses a framebuffer pixel scan with the per-platform render-enable/NMI decode; `{verified:true|false|null, issues[], pixels, render}`, frame-0-guarded so it never cries wolf on boot), `sprites({op:'inspect'})`, `palette({source:'live'})`, `cpu({op:'read'})` (all 14), `audioDebug({op:'inspect'})` (the 12 systems with a sound chip — all but Atari 2600/7800; pass `frames:N` to TRACE a per-channel note-timeline for headless melody asserts), `background({view:'renderState'})`, `breakpoint({on:'write'})` (write watchpoint, all 14; EVERY hit on EVERY platform carries `registersAtHit` — the register file frozen at the hit instant, the only honest read since live regs drift after a hit — and the CPU stays frozen until the hit is cleared), **`watch({on:'dma', precision:'sampled'})`** (Genesis: which ROM offset a VRAM graphic was DMA'd from), **`watch({on:'copy'})`** (ALL 14: every write landing in a VRAM window logged with the EXECUTING instruction's PC — the generic 'which routine uploads this graphic?'; port-based video memory hooked in-core incl. the SNES DMA path, CPU-mapped VRAM via the range log), **`disasm({target:'bytes'|'rom'|'references'|'project'})`** (ALL 14 — native binutils objdump per CPU, incl. GBA ARM7/Thumb; the byte-exact `disasm({target:'project'})` reassembles through native as/ld/objcopy; banked carts — NES mappers, SNES LoROM, GB MBC, Sega mapper, MSX megaROM, 2600 F8/F6/F4, 7800 SuperGame, >32KB HuCards — are split and reference-scanned PER BANK, refs tagged `prgBank`/`romBank`), plus the **Rizin/Ghidra RE engine** `disasm({target:'cfg'|'xrefs'|'functions'|'decompile'|'resolveJumptable'})` (ALL 14 — control-flow graphs, deep xrefs, auto-detected functions [sorted real-code-first, `looksLikeData` flagged], and Ghidra C pseudocode; quality excellent on GBA/Genesis, rough on 6502; decompile output NAMES hardware registers [`PPUMASK` not `*0x2001`] and on the 6502 family folds SLEIGH clutter to readable C99 [`uint8_t`, `zp_FD`]; `resolveJumptable` resolves computed dispatchers live via `breakpoint({on:'jumptable'})`) + `symbols({op:'analyze'})` (one-shot structural map), `symbols({op})` lookup, `background({view:'rendered'})`, plus **`cheats({op})`** (`cheats({op:'lookup'})` = a free labeled RAM/code map for known ROMs, `cheats({op:'search'})` to fuzzy-find a game by name, `cheats({op:'apply'})`/`cheats({op:'clear'})` non-destructively, `cheats({op:'make'})` to create codes)
 - `assets` — convert PNGs to tiles (`encodeArt`/`importArt`), WAVs to BRR, identify ROMs (`cart({op:'identify'})`), plus the hacking toolkit (`romPatch({op})` — write/writeMany/spliceCHR/relocate/makeStored/findFree/findPointer/diff, `assembleSnippet`, `cart({op:'extract'})`, `cart({op:'wrap'})`)
 - `project` — the example-game library (`examples`: list / fork / show, plus the legacy snippet ops)
 - `show` — `playtest({op})`: `op:'open'` opens the live SDL window for a human, `op:'stop'` closes it, `op:'status'` reports liveness, `op:'framebuffer'` captures exactly what the human's window shows
-- `advanced` — `runUntil`, **`watch({on:'mem'|'range'|'pc'})`** (LOG-ALL tracing; `range`/`pc` take **`fromState`**/`fromStatePath` to trace from a restored savestate moment), **`breakpoint({on:'write'})`** (the EXACT instruction that wrote a byte, via a core watchpoint — fixes the frame-sampled-PC problem; runs to END OF FRAME and reports the LAST matching write with `hits`=count; `condition:'increase'|'decrease'|'equals'`+`conditionValue` filters to the MEANINGFUL write — the score going UP, not the per-frame restore churn (core-level on all 14, `oldValueByte` reported); `precision:'sampled'` is the cheap frame-PC version; on a `pressDuring` run pass **`abortIf:[{region,offset,label}]`** to stop early if the driven scenario derails — a guard byte changing returns `{aborted, abortedBy, before, after}` instead of burning all `maxFrames` on a meaningless `found:false`), **`breakpoint({on:'pc'})`** (execution breakpoint — freeze the CPU AT an instruction and read its registers), **`breakpoint({on:'read'})`** (the EXACT instruction that read a byte), **`frame({op:'stepInstruction'})`** (CPU single-step) — all 14 platforms; input recording
+- `advanced` — `runUntil`, **`watch({on:'mem'|'range'|'pc'})`** (LOG-ALL tracing; `range`/`pc` take **`fromState`**/`fromStatePath` to trace from a restored savestate moment), **`breakpoint({on:'write'})`** (the EXACT instruction that wrote a byte, via a core watchpoint — fixes the frame-sampled-PC problem; runs to END OF FRAME and reports the LAST matching write with `hits`=count; `condition:'increase'|'decrease'|'equals'`+`conditionValue` filters to the MEANINGFUL write — the score going UP, not the per-frame restore churn (core-level on all 14, `oldValueByte` reported); `precision:'sampled'` is the cheap frame-PC version; on a `pressDuring` run pass **`abortIf:[{region,offset,label}]`** to stop early if the driven scenario derails — a guard byte changing returns `{aborted, abortedBy, before, after}` instead of burning all `maxFrames` on a meaningless `found:false`), **`breakpoint({on:'pc'})`** (execution breakpoint — freeze the CPU AT an instruction and read its registers), **`breakpoint({on:'read'})`** (the EXACT instruction that read a byte), **`breakpoint({on:'jumptable'})`** (RESOLVE a computed-jump dispatcher static analysis can't follow — `JMP (table,X)` / RTS-trick state machines, script/battle VMs: break at the dispatcher, single-step through the indirect transfer, record the COMPUTED targets live across frames/inputs; the varying arms are isolated from fixed trampolines; `disasm({target:'resolveJumptable'})` points here. No static-only tool can do this — it needs the live emulator), **`frame({op:'stepInstruction'})`** (CPU single-step) — all 14 platforms; input recording
 
 **"Disassemble this NES ROM"** is now just: `disasm({target:'rom', path, startAddress, length})`. No discovery step.
 

package/CHANGELOG.md

@@ -4,6 +4,80 @@ 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.41.0 — 2026-06-12
+
+### RE engine round — bank-aware decompile, live jumptable recovery, readable 6502 output
+
+A correctness + readability pass across the whole reverse-engineering engine,
+plus the differentiator no static tool has: **resolving computed jumps with the
+live emulator.** All 14 platforms; no `romdev-analysis*` package changes (the
+work is in the address-mapping JS, the decompile post-passes, and the live-debug
+tools).
+
+#### New — `breakpoint({on:'jumptable', address})`: live computed-jumptable recovery
+
+Static analysis follows direct addressing only, so a game's *hottest* routines —
+state machines, script / event VMs, battle engines that dispatch through
+`JMP (table,X)` or an RTS-trick — decompile to `(*_IRQ)()` + "Could not recover
+jumptable." romdev has a **live emulator**, so it resolves them dynamically: break
+at the dispatcher, single-step through the indirect transfer, and record the PC
+it actually lands on — accumulated across frames/inputs. Fixed trampolines (the
+compiler's pointer-call shim, return paths) are filtered out by what *doesn't*
+vary; the destinations that vary hit-to-hit are the real switch arms, ranked by
+hit count. Drive more game states (`pressDuring` / `fromState`) to surface rarer
+arms. **No standalone tool (IDA / Ghidra / Binary Ninja) can do this** — it needs
+an emulator in the loop. `disasm({target:'resolveJumptable', address})` is the
+static-side alias that redirects to it.
+
+#### New — `disasm({target:'decompile'})` reads cleaner
+
+- **Hardware registers are named.** MMIO refs Ghidra emits as raw addresses
+  (`*0x2001`, `uRAM400e`) become the register name (`PPUMASK`, `NOISE_LO`), with a
+  `/* hw registers: … */` legend — on the 9 platforms with a register map
+  (NES/SNES/Genesis/GB/GBC/SMS/GG/2600/7800/C64).
+- **6502 SLEIGH clutter folds to readable C** (NES/2600/7800/C64/Lynx/PCE). Width
+  types become C99 stdint (`uint1`→`uint8_t`, `uint2`→`uint16_t`), redundant
+  nested casts collapse (`(uint16_t)(uint8_t)x`→`(uint8_t)x`), and zero-page byte
+  refs are named (`cRAM00fd`→`zp_FD`), with a `/* 6502 fold: … */` legend. A real
+  banked NES function went from `*(xunknown1 *)(uint2)(uint1)(param_2 - 0xb)` to
+  `*(uint8_t *)(zp_FE - 0xb)` — same semantics, far more readable. (The
+  carry-flag-16-bit / BCD reconstruction is left to an LLM reading the output;
+  rewriting it textually would risk changing semantics.)
+
+#### Improved — bank-aware decompile + honest function ranking
+
+- **Banked NES `decompile` resolves the bank.** Rizin reports flat-PRG VAs, so a
+  flat decode was bank-blind (cross-bank `JSR`/`JMP` landed on the wrong bank).
+  `decompile` now lays a real 32 KB CPU window (selected bank @ `$8000` + fixed
+  top bank @ `$C000`) so in-bank *and* fixed-bank calls resolve; NROM falls
+  through to the flat path. On a real banked game this moved a top-12 function
+  list from ~1 readable / 11 garbage to ~10 readable / 2.
+- **`disasm({target:'functions'})` is ranked real-code-first** with a
+  `looksLikeData` flag (+ `dataCount`), so giant single-block data folds stop
+  crowding out the actual control-flow routines you want.
+
+#### Fixed / hardened
+
+- **SMD-interleaved Genesis dumps auto-deinterleave.** A `.bin` in the SMD copier
+  format (size = N·16 KB + 512, `0xAA 0xBB` magic) read flat decodes to pure
+  "bad instruction" garbage; analysis now detects + reverses the interleave and
+  warns, so a flat disasm isn't silently wrong.
+- **C64 `.prg` load-address header is stripped** before analysis (the 2-byte load
+  address was being analyzed as code), with the base applied so addresses line up.
+- **Worker-pool timeout + recycle.** A whole-ROM `aaa` on a multi-MB ROM that
+  never returns no longer wedges the shared WASM analysis pool — the call times
+  out, the worker is killed + respawned, and a clean `{ timedOut }` result comes
+  back (with a "use a scoped pass" hint) instead of every later `disasm` hanging
+  until a manual server restart.
+
+#### New op discovery
+
+- **`platform({op:'capabilities', platform?})`** — the per-platform op-support
+  matrix (CPU family, rendering kind, which introspection/debug ops each core
+  actually wires), so an agent can check support before calling instead of
+  catching a failure. Unsupported ops now throw a typed, structured error
+  (`{ unsupported, platform, op, reason, alternative }`) rather than a bare string.
+
 ## 0.40.2 — 2026-06-11
 
 ### Fixed — SNES `disasm({target:'decompile'})` treated the address as a raw file offset

package/README.md

@@ -11,7 +11,7 @@ npx romdevtools
 - **Build** — bundled per-platform toolchains (cc65, SDCC, RGBDS, asar, vasm, SGDK, PVSnesLib, libtonc, …) as WASM. Write source, compile, get a real ROM.
 - **Run + see + drive** — load the ROM into an emulated console (libretro cores as WASM), step frames, screenshot, script controller input.
 - **Inspect + romhack** — read CPU/video/save RAM, watch memory, write-breakpoints, the Cheat-Engine value-search loop, a bundled cheat database, mapper-aware disassembly, and a byte-exact rebuildable-project disassembler.
-- **Reverse-engineering analysis engine (all 14 platforms)** — control-flow graphs, deep cross-references, auto-detected functions, a one-shot structural map, and a Ghidra **decompiler** (C-like pseudocode): `disasm({target:'cfg'|'xrefs'|'functions'|'decompile'})` and `symbols({op:'analyze'})`. Understand *how* a routine works before you touch it — no $3,000 IDA license, no install.
+- **Reverse-engineering analysis engine (all 14 platforms)** — control-flow graphs, deep cross-references, auto-detected functions (ranked real-code-first), a one-shot structural map, and a Ghidra **decompiler** (C-like pseudocode, with hardware registers named and 6502 SLEIGH clutter folded to readable C): `disasm({target:'cfg'|'xrefs'|'functions'|'decompile'})` and `symbols({op:'analyze'})`. And the piece no static tool has: **live computed-jumptable recovery** — `breakpoint({on:'jumptable'})` runs the emulator to resolve the `JMP (table,X)` / RTS-trick dispatchers (state machines, script/battle VMs) that static analysis collapses to "could not recover." Understand *how* a routine works before you touch it — no $3,000 IDA license, no install.
 - **Convert assets** — PNG → platform tiles/tilemaps, quantize-to-palette, audio importers (BRR for SNES, XGM2 PCM for Genesis).
 
 Point any coding agent at it three ways:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.40.2",
+  "version": "0.41.0",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 14 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, ...) 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",

package/src/analysis/analyze.js

@@ -14,6 +14,110 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { runRizin, runRizinJson, RIZIN_ARCH } from "./rizin.js";
 import { decompileFunction, SLEIGH_LANGID } from "./decompile.js";
+import { registersForPlatform } from "../platforms/common/registers.js";
+
+/** B2: name hardware-register MMIO in decompiler output. Ghidra emits raw memory
+ * refs like `xRAM2001` / `uRAM400e` for $2001 / $400E; replace those whose
+ * address is a known platform register with the register NAME (a valid C
+ * identifier) so the C reads `PPUMASK = ...` instead of `xRAM2001 = ...`. Plus a
+ * one-line legend comment listing the substitutions made. */
+export function nameHardwareRegisters(code, platform) {
+  const regs = registersForPlatform(platform);
+  if (!regs || !Object.keys(regs).length) return code;
+  const used = new Map();
+  // Match Ghidra's mem-ref identifiers: a few lowercase type-prefix letters,
+  // then RAM, then the hex address. e.g. xRAM2001, uRAM400e, cRAM00ff.
+  const out = code.replace(/\b[a-z]{1,3}RAM([0-9a-fA-F]{2,6})\b/g, (m, hex) => {
+    const addr = parseInt(hex, 16);
+    const name = regs[addr];
+    if (!name) return m;
+    used.set(addr, name);
+    return name;
+  });
+  if (!used.size) return code;
+  const legend = "/* hw registers: " +
+    [...used.entries()].map(([a, n]) => `${n}=$${a.toString(16).toUpperCase()}`).join(", ") +
+    " */\n";
+  return legend + out;
+}
+
+/** The 6502-family platforms whose SLEIGH (Ghidra) output carries the
+ * characteristic 8-bit clutter the B1 fold cleans up. */
+const SIXTY_FIVE_OH_TWO = new Set(["nes", "atari2600", "atari7800", "c64", "lynx", "pce"]);
+
+/** B1: 6502 idiom-folding post-pass (deterministic half). The 6502's 8-bit ALU
+ * lowers to literal noise in SLEIGH output — awkward width types (`uint1`,
+ * `xunknown1`), redundant nested width casts (`(uint2)(uint1)x`), and raw
+ * zero-page byte refs (`cRAM00fd`). This pass folds the SAFE, mechanical ones
+ * into readable C99 so the remaining logic is what an LLM (or human) reads:
+ *   - SLEIGH width types → C99 stdint: uint1/int1/xunknown1 → uint8_t/int8_t,
+ *     uint2 → uint16_t, uint4 → uint32_t (Ghidra's `uintN`/`undefinedN` are
+ *     N-BYTE widths, not bit widths).
+ *   - redundant nested width casts `(uint16_t)(uint8_t)expr` → `(uint8_t)expr`
+ *     (the inner cast already narrows; the outer widen is noise).
+ *   - zero-page byte refs `cRAM00fd` / `uRAM0012` → `zp_FD` / `zp_12` (a stable
+ *     name for the ZP slot — the 6502's "fast RAM / pseudo-registers"). Only the
+ *     $00xx page; MMIO was already named by nameHardwareRegisters (run first).
+ * It does NOT attempt the carry-flag 16-bit add/sub or BCD reconstruction the
+ * plan also lists — Ghidra usually already folds those into `+`/`uint2`, and a
+ * textual rewrite of what survives risks changing semantics. Those are left to
+ * the LLM cleanup half (the decompile output is read by an agent). Emits a
+ * leading "6502 fold:" legend comment noting what was applied. */
+export function foldSixtyFiveOhTwoIdioms(code, platform) {
+  if (!SIXTY_FIVE_OH_TWO.has(platform)) return code;
+  const applied = [];
+  let out = code;
+
+  // 1) SLEIGH width types to C99 stdint. Each is a whole-word match. xunknown1
+  // and undefined1 are Ghidra's "1 byte, unknown signedness" - map to uint8_t.
+  const TYPES = [
+    [/\buint1\b/g, "uint8_t"], [/\bint1\b/g, "int8_t"],
+    [/\buint2\b/g, "uint16_t"], [/\bint2\b/g, "int16_t"],
+    [/\buint4\b/g, "uint32_t"], [/\bint4\b/g, "int32_t"],
+    [/\bxunknown1\b/g, "uint8_t"], [/\bundefined1\b/g, "uint8_t"],
+    [/\bxunknown2\b/g, "uint16_t"], [/\bundefined2\b/g, "uint16_t"],
+    [/\bxunknown4\b/g, "uint32_t"], [/\bundefined4\b/g, "uint32_t"],
+  ];
+  let typeFolds = 0;
+  for (const [re, to] of TYPES) {
+    out = out.replace(re, () => { typeFolds++; return to; });
+  }
+  if (typeFolds) applied.push("SLEIGH width types → stdint");
+
+  // 2) Redundant nested width casts: `(uint16_t)(uint8_t)X` → `(uint8_t)X`. The
+  // inner narrowing cast governs; the outer widen back is pure noise SLEIGH emits
+  // around zero-page index math. Run a couple of passes to collapse triples.
+  let castFolds = 0;
+  for (let i = 0; i < 3; i++) {
+    const before = out;
+    out = out.replace(/\((uint(?:8|16|32)_t)\)\((uint8_t)\)/g, (_m, _wide, narrow) => {
+      castFolds++; return `(${narrow})`;
+    });
+    if (out === before) break;
+  }
+  if (castFolds) applied.push("redundant width casts collapsed");
+
+  // 3) Zero-page byte refs → zp_XX. Only the $00 page (cRAM00fd etc.); the
+  // 2-hex-after-00 form. A bare 4-hex like RAM0312 is not ZP — leave it.
+  const zp = new Set();
+  out = out.replace(/\b[a-z]{1,3}RAM00([0-9a-fA-F]{2})\b/g, (_m, hex) => {
+    const name = "zp_" + hex.toUpperCase();
+    zp.add(name);
+    return name;
+  });
+  if (zp.size) applied.push(`${zp.size} zero-page slot${zp.size > 1 ? "s" : ""} named zp_XX`);
+
+  if (!applied.length) return code;
+  return `/* 6502 fold: ${applied.join("; ")} */\n` + out;
+}
+
+/** Readability post-passes applied to every decompiler C body, in order:
+ * B2 hardware-register naming first (so MMIO becomes PPUMASK etc. before B1's
+ * zero-page labeler could touch it), then B1 6502 idiom folding. Both are no-ops
+ * off their target platforms, so this is safe to call unconditionally. */
+export function prettyDecompile(code, platform) {
+  return foldSixtyFiveOhTwoIdioms(nameHardwareRegisters(code, platform), platform);
+}
 
 /** Sniff platform from a ROM extension (mirrors disasm.js). */
 export function sniffPlatform(p) {
@@ -53,12 +157,66 @@ async function loadContext(romPath, platformOverride) {
   if (arch == null) {
     throw new Error(`analyze: no Rizin arch mapping for platform '${platform}'`);
   }
-  const romBytes = new Uint8Array(await readFile(romPath));
+  let romBytes = new Uint8Array(await readFile(romPath));
   // PCE: rizin's 6502 plugin drives the loader + standard control flow for
   // function detection, but mis-decodes HuC6280 custom opcodes — CFG/xrefs are
   // approximate. Accurate HuC6280 decode is the decompiler's job (SLEIGH spec).
   const approx = platform === "pce";
-  return { platform, romBytes, arch, bits: BITS[arch], approx };
+
+  // Address-space prep (A2): some formats carry a header and load at a CPU base
+  // that isn't 0. Strip the header and report `loadBase` so rizin's functions
+  // (and the decompiler image) speak CPU addresses, not raw file offsets.
+  //   c64 .prg — 2-byte little-endian LOAD ADDRESS header, code at that address
+  //   (typically $0801 = BASIC start). Without this, rizin analyzes the header
+  //   bytes as code at offset 0 and every address is a file offset, not a CPU
+  //   address — functions→decompile round-trip lands on garbage.
+  let loadBase = 0;
+  if (platform === "c64" && romBytes.length >= 2) {
+    loadBase = romBytes[0] | (romBytes[1] << 8);
+    romBytes = romBytes.subarray(2);
+  }
+
+  // A6: container/format sniff. Some dumps are interleaved/headered such that a
+  // FLAT read scrambles every byte → fake "bad instruction" noise everywhere.
+  // Detect + auto-correct, and warn so a flat disasm isn't silently wrong.
+  const warnings = [];
+  if (platform === "genesis") {
+    const smd = deinterleaveSmd(romBytes);
+    if (smd) {
+      romBytes = smd;
+      warnings.push("Genesis ROM was SMD-INTERLEAVED (512-byte header + byte-swapped 16KB blocks) — " +
+        "auto-deinterleaved before analysis. A flat read of the original would scramble every instruction.");
+    }
+  }
+  return { platform, romBytes, arch, bits: BITS[arch], approx, loadBase, warnings };
+}
+
+/** Detect + reverse Sega Mega Drive SMD interleaving. An .smd dump is a 512-byte
+ * header followed by 16KB blocks where each block's first 8KB holds the ODD
+ * bytes and the second 8KB the EVEN bytes (interleaved). Returns the
+ * deinterleaved ROM, or null if the image isn't SMD-interleaved. */
+export function deinterleaveSmd(bytes) {
+  // SMD: (N * 16KB) + 512-byte header. The header's byte 8 = 0xAA, byte 9 = 0xBB
+  // is the classic SMD magic; also the body length must be a multiple of 16KB.
+  if (bytes.length < 512 + 0x4000) return null;
+  const bodyLen = bytes.length - 512;
+  if (bodyLen % 0x4000 !== 0) return null;
+  const isSmdMagic = bytes[8] === 0xaa && bytes[9] === 0xbb;
+  // A plain .bin that happens to be (N*16KB)+512 is unusual; require the magic to
+  // avoid false positives on legitimately-sized flat ROMs.
+  if (!isSmdMagic) return null;
+
+  const body = bytes.subarray(512);
+  const out = new Uint8Array(bodyLen);
+  const blocks = bodyLen / 0x4000;
+  for (let b = 0; b < blocks; b++) {
+    const base = b * 0x4000;
+    for (let i = 0; i < 0x2000; i++) {
+      out[base + i * 2 + 1] = body[base + i];           // odd bytes (first 8KB)
+      out[base + i * 2] = body[base + 0x2000 + i];       // even bytes (second 8KB)
+    }
+  }
+  return out;
 }
 
 /** Hex-format an address the way agents expect for the platform width. */
@@ -69,8 +227,8 @@ function hx(n) { return "0x" + (n >>> 0).toString(16); }
  * @returns {{platform, count, functions: Array<{address, name, size, nbbs, cc, callers, callees}>}}
  */
 export async function analyzeFunctions(romPath, platformOverride) {
-  const { platform, romBytes, arch, bits } = await loadContext(romPath, platformOverride);
-  const fns = await runRizinJson({ romBytes, arch, bits, commands: "aaa; aflj" });
+  const { platform, romBytes, arch, bits, loadBase, warnings } = await loadContext(romPath, platformOverride);
+  const fns = await runRizinJson({ romBytes, arch, bits, baddr: loadBase || undefined, commands: "aaa; aflj" });
   const functions = fns.map((f) => ({
     address: f.offset,
     addressHex: hx(f.offset),
@@ -80,8 +238,29 @@ export async function analyzeFunctions(romPath, platformOverride) {
     cc: f.cc,               // cyclomatic complexity
     callers: f.indegree ?? (f.codexrefs?.length ?? 0),
     callees: f.outdegree ?? 0,
+    // A3: rizin's flat sweep folds DATA regions into pseudo-functions with absurd
+    // `size` (megabyte "functions", phantoms exceeding the ROM). The honest
+    // signal is the BYTES-PER-BLOCK ratio, not raw size: real code averages tens
+    // of bytes per basic block; a "function" of thousands of bytes per block (or
+    // a single huge block with no control flow) is a data table / graphics blob
+    // mis-detected as a function. Flag it so agents don't waste a decompile on
+    // it. (A 16KB function with 35 blocks + cc 19 is a real big dispatcher — NOT
+    // flagged; size alone is the lie, the ratio isn't.)
+    looksLikeData:
+      (f.size ?? 0) > 0x400 &&
+      ((f.nbbs ?? 0) <= 1 || (f.size ?? 0) / Math.max(1, f.nbbs ?? 1) > 1024),
   }));
-  return { platform, arch, count: functions.length, functions };
+  // Real code first: highest nbbs/cc, then smaller size — so the actual routines
+  // surface above the data-fold noise without the agent having to learn the rule.
+  functions.sort((a, b) =>
+    (a.looksLikeData ? 1 : 0) - (b.looksLikeData ? 1 : 0) ||
+    (b.nbbs ?? 0) - (a.nbbs ?? 0) ||
+    (b.cc ?? 0) - (a.cc ?? 0) ||
+    (a.size ?? 0) - (b.size ?? 0)
+  );
+  const dataCount = functions.filter((f) => f.looksLikeData).length;
+  return { platform, arch, count: functions.length, dataCount, functions,
+    ...(warnings?.length ? { warnings } : {}) };
 }
 
 /**
@@ -90,13 +269,13 @@ export async function analyzeFunctions(romPath, platformOverride) {
  */
 export async function analyzeCfg(romPath, address, platformOverride) {
   if (address == null) throw new Error("analyze cfg: address required");
-  const { platform, romBytes, arch, bits } = await loadContext(romPath, platformOverride);
+  const { platform, romBytes, arch, bits, loadBase } = await loadContext(romPath, platformOverride);
   // afbj = basic blocks of the function as JSON: each block has addr/size/jump/
   // fail/ninstr. `jump` is the taken edge; `fail` (present only on conditional
   // blocks) is the fall-through. This is the structured CFG source — `agf json`
   // only gives a text body blob with untyped out_nodes.
   const blocks = await runRizinJson({
-    romBytes, arch, bits,
+    romBytes, arch, bits, baddr: loadBase || undefined,
     commands: `aaa; af @ ${hx(address)}; afbj @ ${hx(address)}`,
   });
   if (!Array.isArray(blocks) || blocks.length === 0) {
@@ -129,10 +308,10 @@ export async function analyzeCfg(romPath, address, platformOverride) {
  */
 export async function analyzeXrefs(romPath, address, platformOverride) {
   if (address == null) throw new Error("analyze xrefs: address required");
-  const { platform, romBytes, arch, bits } = await loadContext(romPath, platformOverride);
+  const { platform, romBytes, arch, bits, loadBase } = await loadContext(romPath, platformOverride);
   let refs;
   try {
-    refs = await runRizinJson({ romBytes, arch, bits, commands: `aaa; axtj @ ${hx(address)}` });
+    refs = await runRizinJson({ romBytes, arch, bits, baddr: loadBase || undefined, commands: `aaa; axtj @ ${hx(address)}` });
   } catch (e) {
     // axtj prints nothing (not even `[]`) when there are zero refs → our JSON
     // guard throws. Treat "no JSON" as "no refs".
@@ -154,11 +333,12 @@ export async function analyzeXrefs(romPath, address, platformOverride) {
  * analysis pass. The "give me the shape of this ROM" call.
  */
 export async function analyzeStructure(romPath, platformOverride) {
-  const { platform, romBytes, arch, bits } = await loadContext(romPath, platformOverride);
+  const { platform, romBytes, arch, bits, loadBase } = await loadContext(romPath, platformOverride);
+  const baddr = loadBase || undefined;
   const [fns, strings, entries] = await Promise.all([
-    runRizinJson({ romBytes, arch, bits, commands: "aaa; aflj" }).catch(() => []),
-    runRizinJson({ romBytes, arch, bits, commands: "aaa; izj" }).catch(() => []),
-    runRizinJson({ romBytes, arch, bits, commands: "aaa; iej" }).catch(() => []),
+    runRizinJson({ romBytes, arch, bits, baddr, commands: "aaa; aflj" }).catch(() => []),
+    runRizinJson({ romBytes, arch, bits, baddr, commands: "aaa; izj" }).catch(() => []),
+    runRizinJson({ romBytes, arch, bits, baddr, commands: "aaa; iej" }).catch(() => []),
   ]);
   return {
     platform, arch,
@@ -267,16 +447,65 @@ export function buildSnesCpuImage(romBytes, mapperHint) {
   return { image, isLo: false };
 }
 
+/** Bank-aware NES image for the decompiler (A1).
+ *
+ * Rizin maps an iNES PRG as ONE flat $8000-based segment, so a `functions`
+ * address is a FLAT-PRG VA ($8000 + flat offset) — bank 0 at $8000-$BFFF, bank 1
+ * at $C000-$FFFF, bank 2 at $10000+, etc. Decompiling that flat image is
+ * bank-blind: an in-code `JSR $9123` (a real CPU address) resolves to flat
+ * $9123 = bank 0, even when the calling code lives in bank 3 → halt_baddata /
+ * garbage (11/12 top functions on a banked cart, empirically).
+ *
+ * Fix: from the flat VA, recover which 16KB PRG bank the function is in, then
+ * build a real 32KB 6502 CPU image — that bank at $8000-$BFFF, the FIXED top
+ * bank at $C000-$FFFF — and decompile at the function's REAL CPU address. Now
+ * in-bank calls AND fixed-bank ($C000+) calls both resolve.
+ *
+ * @returns {{ image: Uint8Array, cpuAddr: number, bank: number } | null} null if
+ *   not a banked iNES (caller falls back to the flat path; NROM is fine flat).
+ */
+export function buildNesBankImage(romBytes, flatVa) {
+  if (romBytes[0] !== 0x4e || romBytes[1] !== 0x45 || romBytes[2] !== 0x53 || romBytes[3] !== 0x1a) {
+    return null; // not iNES
+  }
+  const prgBanks16k = romBytes[4];
+  const prgSize = prgBanks16k * 0x4000;
+  if (prgSize <= 0x8000) return null; // NROM-128/256 — flat is correct
+  const prgStart = 16;
+  const prg = romBytes.subarray(prgStart, prgStart + prgSize);
+
+  // rizin flat VA → flat PRG offset (segment based at $8000).
+  const flatOff = (flatVa >>> 0) - 0x8000;
+  if (flatOff < 0 || flatOff >= prgSize) return null;
+  const bank = Math.floor(flatOff / 0x4000);          // which 16KB bank
+  const inBank = flatOff % 0x4000;                     // offset within it
+  const topBank = prgBanks16k - 1;                     // fixed top bank
+
+  // 32KB CPU window: chosen bank at $8000, fixed top bank at $C000.
+  const image = new Uint8Array(0x10000);
+  image.set(prg.subarray(bank * 0x4000, bank * 0x4000 + 0x4000), 0x8000);
+  image.set(prg.subarray(topBank * 0x4000, topBank * 0x4000 + 0x4000), 0xC000);
+
+  // The function's real CPU address: if it's the fixed top bank, it's at
+  // $C000+inBank; otherwise it's the switchable slot at $8000+inBank.
+  const cpuAddr = bank === topBank ? 0xC000 + inBank : 0x8000 + inBank;
+  return { image, cpuAddr, bank };
+}
+
 /**
  * Decompile the function containing `address` to C pseudocode (Ghidra).
- * @returns {{platform, langid, address, code, warnings, qualityNote}}
+ * @returns {{platform, langid, address, code, warnings, qualityNote, bank?}}
  */
 export async function analyzeDecompile(romPath, address, platformOverride) {
   if (address == null) throw new Error("analyze decompile: address required");
   const platform = platformOverride ?? sniffPlatform(romPath);
   if (!platform) throw new Error(`analyze decompile: unknown platform for '${path.basename(romPath)}'`);
   if (!SLEIGH_LANGID[platform]) throw new Error(`analyze decompile: unsupported platform '${platform}'`);
-  const romBytes = new Uint8Array(await readFile(romPath));
+  let romBytes = new Uint8Array(await readFile(romPath));
+  // A6: deinterleave SMD Genesis dumps here too (analyzeDecompile reads the file
+  // directly, not via loadContext) — a flat read of an interleaved ROM decodes
+  // to pure garbage.
+  if (platform === "genesis") romBytes = deinterleaveSmd(romBytes) ?? romBytes;
 
   // SNES: banked 24-bit space. `address` is a LoROM/HiROM CPU address (what
   // target='functions'/'cfg' report). Lay the cart out by CPU address so BOTH
@@ -297,35 +526,50 @@ export async function analyzeDecompile(romPath, address, platformOverride) {
     return {
       platform, langid: rs.langid,
       address, addressHex: hx(address),
-      code: rs.code, warnings: rs.warnings,
+      code: prettyDecompile(rs.code, platform), warnings: rs.warnings,
       qualityNote: "medium (65816 variable register width)",
     };
   }
 
+  // NES banked carts (A1): rizin reports flat-PRG VAs ($8000-based); decompiling
+  // that flat image is bank-blind (cross-bank JSR/JMP land on the wrong bank).
+  // Build a real 32KB CPU window (this bank @ $8000 + fixed top bank @ $C000) so
+  // in-bank AND fixed-bank calls resolve. NROM falls through to the flat path.
+  if (platform === "nes") {
+    const banked = buildNesBankImage(romBytes, address);
+    if (banked) {
+      const rn = await decompileFunction({ platform, romBytes: banked.image, fileOffset: banked.cpuAddr });
+      return {
+        platform, langid: rn.langid,
+        address, addressHex: hx(address),
+        bank: banked.bank,
+        code: prettyDecompile(rn.code, platform), warnings: rn.warnings,
+        qualityNote: "rough (6502 architecture limit)",
+      };
+    }
+  }
+
   // Use rizin's loader mapping to turn the VA (what the user sees from
   // target='functions') into the file offset the raw decompiler image needs.
   // PCE uses the 6502 plugin only for the map/loader (HuC6280 decode is the
   // decompiler's job via SLEIGH) — its flat image bases at 0 either way.
   const arch = RIZIN_ARCH[platform] ?? "6502";
   const bits = { arm: 32, m68k: 32, snes: 16 }[arch];
-  const { paddr, vbase } = await vaMapping(romBytes, arch, bits, address, platform);
-  if (paddr < 0 || paddr >= romBytes.length) {
-    throw new Error(
-      `decompile: address ${hx(address)} maps to file offset ${paddr}, outside the ` +
-      `${romBytes.length}-byte image for ${platform}.`
-    );
-  }
-  // The raw decompiler loads byte 0 at VMA 0. Code that references absolute CPU
-  // addresses (typical 6502: JSR/JMP to $Fxxx) only resolves if the image sits
-  // at the right CPU base. Rizin's map gives `vbase` when it knows the base;
-  // some headerless carts (2600/7800) it loads at 0, so we supply the base from
-  // a per-platform table. Left-pad the image by the base so file offset == CPU
-  // address, then decompile at the function's CPU address. Capped at 64KB (the
-  // 6502 family's whole address space) so a large base never over-allocates.
-  // Atari 2600/7800 are headerless 6502 dumps rizin loads at 0; supply the real
-  // CPU base so absolute references ($8000/$C000/$F000) resolve. 7800's base is
-  // size-dependent (16KB→$C000, 32KB→$8000); 7800 carts may carry a 128-byte
-  // header before the body.
+
+  const QUALITY = {
+    gba: "excellent (ARM)", genesis: "excellent (M68K)",
+    gb: "good (SM83)", gbc: "good (SM83)", sms: "good (Z80)", gg: "good (Z80)", msx: "good (Z80)",
+    snes: "medium (65816 variable register width)", pce: "medium (HuC6280)",
+    nes: "rough (6502 architecture limit)", atari2600: "rough (6502)", atari7800: "rough (6502)",
+    c64: "rough (6502)", lynx: "rough (65C02)",
+  };
+
+  // FORCED-BASE platforms (headerless/load-header 6502 carts): rizin/our
+  // analysis bases these at a known CPU address, so `address` IS a CPU address
+  // and `functions` already reported it as such. Strip any header, left-pad the
+  // body so file offset == CPU address, and decompile at `address` directly.
+  //   2600 → $F000; 7800 → size-dependent $8000-$C000 (+128B header if "AT…");
+  //   c64 .prg → the 2-byte load-address header's value (e.g. $0801).
   let forcedBase = 0, bodyStart = 0;
   if (platform === "atari2600") {
     forcedBase = 0xf000;
@@ -335,28 +579,56 @@ export async function analyzeDecompile(romPath, address, platformOverride) {
     bodyStart = hasHdr ? 128 : 0;
     const body = romBytes.length - bodyStart;
     forcedBase = body <= 0x4000 ? 0xc000 : body <= 0x8000 ? 0x8000 : 0x4000;
+  } else if (platform === "c64" && romBytes.length >= 2) {
+    bodyStart = 2;
+    forcedBase = romBytes[0] | (romBytes[1] << 8);
+  }
+  if (forcedBase > 0 && forcedBase <= 0x10000) {
+    const body = romBytes.subarray(bodyStart);
+    // Accept `address` as EITHER a CPU address (≥ forcedBase, what functions
+    // reports once baddr is applied) OR a raw body file-offset (< forcedBase,
+    // legacy callers / direct offsets). Normalize to a CPU address.
+    const a = address >>> 0;
+    const cpuAddr = a >= forcedBase ? a : forcedBase + a;
+    if (cpuAddr < forcedBase || cpuAddr >= forcedBase + body.length) {
+      throw new Error(
+        `decompile: address ${hx(a)} is outside the ${platform} CPU image ` +
+        `($${forcedBase.toString(16)}-$${(forcedBase + body.length).toString(16)}).`
+      );
+    }
+    const padded = new Uint8Array(forcedBase + body.length);
+    padded.set(body, forcedBase);
+    const rf = await decompileFunction({ platform, romBytes: padded, fileOffset: cpuAddr });
+    return {
+      platform, langid: rf.langid, address, addressHex: hx(address),
+      code: prettyDecompile(rf.code, platform), warnings: rf.warnings, qualityNote: QUALITY[platform] ?? "unknown",
+    };
   }
-  const base = vbase > 0 ? vbase : forcedBase;
+
+  // Other platforms: use rizin's loader mapping to turn the CPU VA into the file
+  // offset the raw decompiler image needs. Rizin's map gives `vbase` when it
+  // knows the base; left-pad by it so file offset == CPU address for the cases
+  // where the code references absolute addresses.
+  const { paddr, vbase } = await vaMapping(romBytes, arch, bits, address, platform);
+  if (paddr < 0 || paddr >= romBytes.length) {
+    throw new Error(
+      `decompile: address ${hx(address)} maps to file offset ${paddr}, outside the ` +
+      `${romBytes.length}-byte image for ${platform}.`
+    );
+  }
+  const base = vbase;
   let image = romBytes, decompAddr = paddr;
   if (base > 0 && base <= 0x10000) {
-    const body = romBytes.subarray(bodyStart);
-    const padded = new Uint8Array(base + body.length);
-    padded.set(body, base);
+    const padded = new Uint8Array(base + romBytes.length);
+    padded.set(romBytes, base);
     image = padded;
-    decompAddr = base + (paddr - bodyStart); // CPU address of the function
+    decompAddr = base + paddr; // CPU address of the function
   }
   const r = await decompileFunction({ platform, romBytes: image, fileOffset: decompAddr });
-  const QUALITY = {
-    gba: "excellent (ARM)", genesis: "excellent (M68K)",
-    gb: "good (SM83)", gbc: "good (SM83)", sms: "good (Z80)", gg: "good (Z80)", msx: "good (Z80)",
-    snes: "medium (65816 variable register width)", pce: "medium (HuC6280)",
-    nes: "rough (6502 architecture limit)", atari2600: "rough (6502)", atari7800: "rough (6502)",
-    c64: "rough (6502)", lynx: "rough (65C02)",
-  };
   return {
     platform, langid: r.langid,
     address, addressHex: hx(address),
-    code: r.code,
+    code: prettyDecompile(r.code, platform),
     warnings: r.warnings,
     qualityNote: QUALITY[platform] ?? "unknown",
   };

package/src/analysis/rizin.js

@@ -77,7 +77,7 @@ export const RIZIN_ARCH = {
  * @returns {Promise<{exitCode:number, output:string, log:string, crash?:object}>}
  */
 export async function runRizin(opts) {
-  const { romPath, romBytes, commands, arch, bits, baddr, writeable } = opts;
+  const { romPath, romBytes, commands, arch, bits, baddr, writeable, timeoutMs } = opts;
   if (!commands) throw new Error("runRizin: commands required");
   const bytes = romBytes ?? new Uint8Array(await readFile(romPath));
 
@@ -102,6 +102,11 @@ export async function runRizin(opts) {
   const res = await runIsolated({
     gluePath: rizinGluePath(),
     argv,
+    // A5: per-call timeout so a hung analysis (whole-ROM `aaa` on a multi-MB ROM)
+    // can't wedge the shared worker pool — on timeout the worker is killed +
+    // recycled and this call returns a clean { timedOut, log } result. Default
+    // 60s; callers can override (a scoped `af @ addr` pass is near-instant).
+    timeoutMs: timeoutMs ?? 60000,
     inputFiles: [{
       vfsPath: "/work/rom.bin",
       encoding: "base64",
@@ -109,6 +114,13 @@ export async function runRizin(opts) {
     }],
     outputFiles: [{ vfsPath: OUT, encoding: "utf8" }],
   });
+  // Surface a timeout as a thrown error so JSON callers get a clear signal
+  // (runRizinJson already wraps crashes; this makes the timeout explicit).
+  if (res.timedOut) {
+    const e = new Error(res.log?.trim() || "rizin analysis timed out");
+    /** @type {any} */ (e).timedOut = true;
+    throw e;
+  }
   return { ...res, output: res.outputs?.[OUT] ?? "" };
 }