romdevtools 0.30.0 → 0.40.0

package/AGENTS.md

@@ -66,7 +66,7 @@ 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`), `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'})` (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)
 - `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
@@ -108,8 +108,17 @@ questions, and running both early is normal.** A good default:
    cheats don't cover: `disasm({target:'project'})` for a rebuildable project,
    `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 a no-cheats game or a logic/text/graphics change, this is
-   where the real work is — start here, don't wait on a cheat lookup.
+   empirically. For STRUCTURE — "what are the functions, how do they call each
+   other, what's the control flow" — use the Rizin analysis ops: `symbols({op:'analyze'})`
+   for a one-shot map (functions + entrypoints), `disasm({target:'functions'})` for the
+   auto-detected function list, `disasm({target:'cfg', address})` for a function's basic-block
+   graph, `disasm({target:'xrefs', address})` for every cross-reference TO an address (deeper
+   than the da65 `references` scan — it follows the analysis graph). For C-like PSEUDOCODE,
+   `disasm({target:'decompile', address})` runs Ghidra's decompiler (carries the decompiler's
+   own WARNINGs; quality excellent on GBA/Genesis, good on GB/Z80, rough on 6502). All
+   Rizin/Ghidra analysis ops cover 14/14 platforms. For a no-cheats game or a
+   logic/text/graphics change, this is where the real work is — start here, don't wait on a
+   cheat lookup.
 4. **VERIFY before patching**: `memory({op:'write'})` the address live and watch the effect
    (cheat labels are *probable* — matched by name, not verified CRC; static
    "matches the pattern" ≠ "actually runs").

package/CHANGELOG.md

@@ -4,10 +4,67 @@ 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.40.0 — 2026-06-11
+
+### Reverse-engineering analysis engine — control-flow graphs, deep xrefs, function detection, and a decompiler
+
+A full open-source RE analysis layer, covering **all 14 platforms** with zero
+proprietary dependencies. Two new binary packages carry the WebAssembly; the
+main package gains four `disasm` targets and one `symbols` op that drive them.
+
+- **`disasm({target:'functions'})`** — auto-detected function list
+  (`{address, size, nbbs, cc, callers, callees}`): the structural map of an
+  unknown ROM, the carve step before you label anything live.
+- **`disasm({target:'cfg', address})`** — basic-block control-flow graph of the
+  function at `address` (nodes + typed edges: jump / branch_true / branch_false).
+- **`disasm({target:'xrefs', address})`** — every cross-reference TO `address`,
+  following the analysis graph. Deeper than the flat `target:'references'` da65
+  operand scan — prefer `xrefs` once a function pass has run, `references` for a
+  quick header-less sweep.
+- **`disasm({target:'decompile', address})`** — Ghidra C-like **pseudocode** for
+  the function at `address`, with the decompiler's own warnings and a per-CPU
+  `qualityNote`. Altitude rule: decompile is for UNDERSTANDING (and as a port
+  spec when retargeting to a bigger machine) — `target:'project'` stays the
+  byte-exact rebuildable edit path. Quality is excellent on ARM (GBA) and M68K
+  (Genesis), good on SM83 (GB/GBC) and Z80 (SMS/GG/MSX), medium on 65816 (SNES)
+  and HuC6280 (PC Engine), and rough on the 6502 family (an architecture limit —
+  every tool is rough on 6502).
+- **`symbols({op:'analyze'})`** — one-shot structural map of a ROM
+  (auto-detected functions + strings + entrypoints), no `.dbg`/`.map` needed.
+
+Built from pinned upstreams, fetch-on-demand, never vendored — only the compiled
+artifacts ship (see `scripts/build-rizin.sh`, `scripts/build-decompiler.sh`,
+`scripts/versions.json`):
+- **`romdev-analysis`** — Rizin compiled to WASM (the CFG / xrefs / functions
+  engine). LGPL-3.0.
+- **`romdev-analysis-decompiler`** — Ghidra's C++ decompiler compiled to WASM
+  (no JVM, no rizin) plus SLEIGH processor tables for all 14 CPUs. Apache-2.0,
+  with full per-component attribution in the package NOTICE (Ghidra/NSA, and the
+  community SM83 / 65816 / HuC6280 SLEIGH specs).
+
+### Documentation: no commercial game titles in shipped source
+
+Swept every shipped tool description, doc, README, mental-model guide, and the
+ROM-hacking playbook for commercial game/franchise names and replaced them with
+generic platform + hardware + mechanic descriptions ("a banked NES racer", "a
+top-down dungeon-crawler shape"). Console and chip names are unchanged — they're
+not anyone's IP. The bundled cheat database (third-party crowd-sourced data) is
+unaffected.
+
+### Tests build their own ROMs (no external fixtures)
+
+Tests that needed a real ROM now build one from our **own example sources** at
+runtime instead of depending on a ROM file on disk — so the whole suite runs
+with no external/commercial ROM anywhere. Every previously-skipped fixture-gated
+test now runs: **918 tests, 918 pass, 0 fail, 0 skipped**. (This also surfaced a
+latent fidelity bug the silent skips had hidden: `wrapRomFromParts` dropped the
+iNES battery-SRAM flag on round-trip — now preserved via a new `hasBattery`
+field, and exposed on the `wrapRomFromParts` tool.)
+
 ## 0.30.0 — 2026-06-11
 
 ### RE-tooling round — the Cheat-Engine "locate a value + find its writer" workflow
-From a Zanac (NES) reverse-engineering feedback batch. Six additions to the
+From an NES reverse-engineering feedback batch. Six additions to the
 memory/breakpoint primitives:
 - **`memory({op:'searchUnknown'})`** — the unknown-initial-value hunt: seed the
   WHOLE region with no value, then narrow across in-game events with
@@ -164,7 +221,7 @@ three guarantees now hold across the whole platform matrix:
 - `test/regsnap-all-cores.test.js`: live single-step snapshot + freeze proof
   on 10 platforms (plus the existing gpgx suite for Genesis/SMS/GG).
 
-### Fixed/Added — gpgx core round (the NBA-Jam-both-consoles feedback): break-instant truth on Genesis/SMS/GG
+### Fixed/Added — gpgx core round (a both-consoles sports-title feedback): break-instant truth on Genesis/SMS/GG
 The first core rebuild in this release (gpgx only; pins unchanged, patch extended).
 - **`registersAtHit` on Genesis/SMS/GG** — `breakpoint({on:'pc'|'write'|'read'})`
   hits now carry the FULL register file (m68k d0-d7/a0-a7/pc/sr/sp; z80
@@ -333,7 +390,7 @@ of repeated logic errors. The big ones:
   respond to input, and each platform's audio was captured and RMS-checked.
   (Atari 2600 has no puzzle genre by design.)
 
-### Fixed/Added — the 0.27.0 Zanac RE feedback round (banked-NES rebuilds, A/B diff, token cuts)
+### Fixed/Added — the 0.27.0 NES RE feedback round (banked-NES rebuilds, A/B diff, token cuts)
 - **Banked NES `disasm({target:'project'})` now emits COMPLETE, working rebuild
   glue** (the headline ask): a `HEADER` segment with the original 16 iNES bytes,
   a per-bank `PRGn` segment wrapper for every bank, a multi-bank `nes_rebuild.cfg`
@@ -407,7 +464,7 @@ defaulted to native; this is the docs telling the truth about it.)
 ## 0.27.0
 
 ### Added — `breakpoint(on:'pc', captureMemory:[…])` reads named RAM at the hit
-Completes item 2 of the NES Rygar report. 0.26.0 shipped `registersAtHit` (the
+Completes item 2 of an NES action-game RE report. 0.26.0 shipped `registersAtHit` (the
 break-instant register file) but not the memory half. Now `breakpoint(on:'pc')`
 takes `captureMemory:[{region,offset,length,label}]` and returns those reads inline
 as `capturedMemory`, so register + RAM inspection at a PC collapses into ONE call —
@@ -418,7 +475,7 @@ hit frame (stable + what RE needs), documented as such.
 ## 0.26.0
 
 ### Fixed — NES `breakpoint(on:'pc')` now returns reliable break-instant registers
-An agent RE'ing NES Rygar found that after a `pc` breakpoint hit, a follow-up
+An agent RE'ing an NES action game found that after a `pc` breakpoint hit, a follow-up
 `cpu({op:'read'})` returned the **idle-loop PC**, not the breakpoint instruction —
 the documented "break, then read the live register file" workflow gave end-of-frame
 state. Root cause: fceumm drains the cycle budget on hit but `retro_run` still
@@ -447,7 +504,7 @@ own frame correctly. Null until a ROM is loaded.
 ## 0.25.0
 
 ### Added — C64 input scripting + verification (RE startup-flow telemetry)
-Follow-up to the 0.24.0 C64 keyboard work: an agent RE'ing C64 Uridium could now
+Follow-up to the 0.24.0 C64 keyboard work: an agent RE'ing a C64 shoot-'em-up could now
 press keys, but couldn't (a) script a keyboard+joystick startup TIMELINE in one
 call, or (b) tell whether a non-responsive key reached VICE at all. Both added — no
 core rebuild (the `c64_cia1_regs` region + key matrix already existed):
@@ -520,7 +577,7 @@ or the tool list); full release notes remain in CHANGELOG.md for humans.
 ## 0.24.0
 
 ### Added — C64 keyboard + joyport input (VICE core patch)
-An agent RE'ing C64 Uridium could reach the intro via joystick but couldn't ENTER
+An agent RE'ing a C64 shoot-'em-up could reach the intro via joystick but couldn't ENTER
 gameplay — the game needs **F1** (1 player) + fire on **port 2**, and romdev's
 input was joypad-mask-only. Many C64 games gate gameplay behind KEYBOARD setup
 screens that joystick can't reach. The VICE core now exports
@@ -602,7 +659,7 @@ training agents to ignore lint. Now: provably-VRAM dest → warning, plain RAM a
   repeated starfield + player sprite, hardware scroll only, zero loop-time tilemap
   writes. Builds clean, renders, scrolls (verified).
 - Genesis MENTAL_MODEL/TROUBLESHOOTING: "do NOT rewrite tilemaps in the frame
-  loop", logical-vs-hardware plane size, the correct parallax loop, Sonic-style
+  loop", logical-vs-hardware plane size, the correct parallax loop, large-scroller-style
   column streaming, and a "why does movement feel choppy?" recipe.
 
 ### Changed — discoverability (the recurring root cause)
@@ -1020,7 +1077,7 @@ savestate) is now fully supported, with NO new top-level tool:
 - **Honest "no save":** empty `save_ram` now says *why* — "this cart has no battery
   save" / "Atari 2600/7800 & Lynx never had cartridge saves" / "C64 has no battery SRAM (disk/.prg)" — instead of a generic "core didn't expose it." (Confirmed via research +
   core source: no core patches were needed; earlier "broken" readings were
-  password-game test carts like Metroid, which correctly have no battery.)
+  password-based NES carts, which correctly have no battery.)
 
 ### Fixed / Added — v0.15.0 session feedback
 - **`state` file `path` resolution.** A RELATIVE `path` (save/load/export) used to
@@ -1232,7 +1289,7 @@ discoverable rename table).
   searches only the widest form. The suppression matches on offset-overlap AND
   pointer-value (so two coincidentally co-located but distinct pointers are never
   falsely merged). The other 12 platforms emit a single width, so this is a
-  verified no-op there. (NBA-Jam-TE agent nit: 20 hits → the 10 distinct
+  verified no-op there. (sports-title agent nit: 20 hits → the 10 distinct
   relocation handles, no hand-dedupe.)
 - **`cpu({op:'call'})` watchdog now trips on a wrong-entry free-run, not just a
   tight loop — on EVERY CPU.** Two cross-system gaps fixed:
@@ -1249,7 +1306,7 @@ discoverable rename table).
     just `m68k_run`** — so it actually fires on **SMS/GG** (where the Z80 is the
     active CPU). Before, `callSubroutine` armed a watchdog that could never trip
     on SMS/GG (the counter only incremented on the m68k), so a Z80 free-run fell
-    to `maxFrames`. Requires the rebuilt `romdev-core-gpgx` WASM. (NBA-Jam-TE
+    to `maxFrames`. Requires the rebuilt `romdev-core-gpgx` WASM. (sports-title
     agent nit, generalized to all 14 platforms.)
 
 ## 0.10.0
@@ -1327,7 +1384,7 @@ Requires the bumped core packages.
 
 ## 0.7.0
 
-Reverse-engineering follow-ups from the NBA Jam (Genesis) agent's decompress
+Reverse-engineering follow-ups from a Genesis sports-title agent's decompress
 feedback. Genesis reference for the hang-fix (the watchdog is a core hook — it
 fans out to every core in 0.8.0); the JS-layer fixes (watchDma, previewTileArt)
 are all-platform.
@@ -1566,7 +1623,7 @@ sprite-inspection bug fix.
 ## 0.3.0
 
 The reverse-engineering / romhacking release — a full RE toolkit driven by a real
-NBA Jam Tournament Edition (Genesis) session, plus PC Engine + MSX cheat coverage
+a Genesis sports-title session, plus PC Engine + MSX cheat coverage
 and a cleaner package split.
 
 ### Added — RE / romhacking toolkit

package/README.md

@@ -1,6 +1,6 @@
 # romdev
 
-The entry point for **romdev** — vibe-code real retro games. Lets a coding agent build, run, and inspect actual homebrew ROMs (NES, SNES, Game Boy, Genesis, Atari, C64, GBA, and more) with one command.
+The entry point for **romdev** — vibe-code real retro games. Build, run, inspect, and reverse-engineer actual homebrew ROMs (NES, SNES, Game Boy, Genesis, Atari, C64, GBA, and more) with one command — drive it yourself or let a coding assistant do it.
 
 ```bash
 npx romdevtools
@@ -31,6 +31,7 @@ This package contains all the JavaScript — the tool surface, the WASM emulator
 - Cores: `romdev-core-{fceumm,gambatte,gpgx,vice,handy,prosystem,geargrafx,bluemsx}`
 - Platforms: `romdev-platform-{snes,gba,atari2600}`
 - Toolchains: `romdev-toolchain-{cc65,sdcc,m68k-gcc,vasm,rgbds}`
+- Analysis: `romdev-analysis` (Rizin → WASM: control-flow graphs, cross-references, function detection) and `romdev-analysis-decompiler` (Ghidra's C++ decompiler → WASM + SLEIGH processor specs for all 14 CPUs). Power `disasm({target:'cfg'|'xrefs'|'functions'|'decompile'})` and `symbols({op:'analyze'})`. Lazy-loaded on first use.
 - Data: `romdev_game_codes` — the bundled game-code / cheat database (a free labeled RAM/code map for thousands of known ROMs), split out so it can grow independently. Lazy-loaded one platform at a time.
 
 `@kmamal/sdl` is used only by `playtest()` / `romdevtools-cli play` (the live window). It ships its native binary via its own install script, which npm skips when romdev is a transitive dep (e.g. under `npx`) — so romdev's `postinstall` fetches it, and `playtest()` also self-heals at runtime if the binary is still missing (downloading the prebuilt before the first window open). Either way, if the binary can't be fetched (offline/locked-down network), the headless server is unaffected — only the live window degrades, and the error tells you the one command to fix it.

package/examples/gb/templates/tile_engine.c

@@ -1,6 +1,6 @@
 /* ── tile_engine.c — GBC starter with a tile map + multiple rooms ──
  *
- * Single-screen-per-room layout (Adventure / Zelda-1 / Sokoban shape).
+ * Single-screen-per-room layout (top-down dungeon-crawler / room-puzzle shape).
  *   - 20×18 BG map rendered from a `room[]` array
  *   - Walk a sprite around with the d-pad
  *   - Crossing the screen edge transitions to the next room

package/examples/gbc/templates/tile_engine.c

@@ -1,6 +1,6 @@
 /* ── tile_engine.c — GBC starter with a tile map + multiple rooms ──
  *
- * Single-screen-per-room layout (Adventure / Zelda-1 / Sokoban shape).
+ * Single-screen-per-room layout (top-down dungeon-crawler / room-puzzle shape).
  *   - 20×18 BG map rendered from a `room[]` array
  *   - Walk a sprite around with the d-pad
  *   - Crossing the screen edge transitions to the next room

package/examples/genesis/templates/two_plane_parallax.c

@@ -1,6 +1,6 @@
 /* ── two_plane_parallax.c — Genesis SGDK two-plane parallax scaffold ──
  *
- * The "Uridium / Sonic-feel" starting point: a side-scrolling world that
+ * A smooth-scrolling side-scroller starting point: a side-scrolling world that
  * moves SMOOTHLY because the frame loop does HARDWARE SCROLL ONLY. There
  * are ZERO tilemap writes inside the loop — the two planes are painted
  * ONCE at setup, and every frame we just nudge two scroll registers and
@@ -30,11 +30,11 @@
  * plane — you don't get an independent per-plane size. See the Genesis
  * MENTAL_MODEL.md "Scrolling, parallax & the feel trap".
  *
- * To go WIDER than 512 px (a true Sonic-size level) you keep this exact
+ * To go WIDER than 512 px (a large multi-screen level) you keep this exact
  * loop and add ONE thing: stream the single offscreen column that's about
  * to scroll into view each time the camera crosses an 8-px tile boundary
  * (a circular buffer in the 64-cell plane) — NOT a whole-plane redraw.
- * See MENTAL_MODEL.md "How Sonic-style large maps really work".
+ * See MENTAL_MODEL.md "How large scrolling maps REALLY work".
  */
 
 #include <genesis.h>
@@ -94,7 +94,7 @@ int main(bool hard) {
     (void)hard;
 
     /* Palettes (BGR, 3 bits/chan). PAL0 = sprite, PAL1 = planes. */
-    PAL_setColor(0 +  5, 0x008E);  /* player orange (Uridium-ish) */
+    PAL_setColor(0 +  5, 0x008E);  /* player orange */
     PAL_setColor(16 + 1, 0x0A86);  /* ground top   (light)  */
     PAL_setColor(16 + 2, 0x0530);  /* ground body  (dark)   */
     PAL_setColor(16 + 3, 0x0CCC);  /* block edge   (white)  */

package/examples/nes/templates/tile_engine.c

@@ -1,6 +1,6 @@
 /* ── tile_engine.c — NES starter with a tile map + multiple rooms ──
  *
- * Single-screen-per-room layout (Adventure / Zelda-1 / Sokoban shape).
+ * Single-screen-per-room layout (top-down dungeon-crawler / room-puzzle shape).
  *   - 32×30 BG nametable rendered from a `room[]` array
  *   - Walk a sprite around with the d-pad
  *   - Crossing the screen edge transitions to the next room

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.30.0",
+  "version": "0.40.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",
@@ -50,6 +50,8 @@
     "fuse.js": "^7.4.1",
     "omggif": "^1.0.10",
     "pngjs": "^7.0.0",
+    "romdev-analysis": "0.1.0",
+    "romdev-analysis-decompiler": "0.1.0",
     "romdev-core-bluemsx": "0.6.0",
     "romdev-core-fceumm": "0.10.0",
     "romdev-core-gambatte": "0.9.0",

package/src/analysis/analyze.js

@@ -0,0 +1,263 @@
+// analyze.js — MCP-facing RE analysis ops built on the Rizin WASM engine:
+// control-flow graphs, deep cross-references, auto-detected functions, and a
+// one-shot structural map. Complements disasm.js (da65/native, rebuildable
+// output) — rizin gives the GRAPH structure da65 can't.
+//
+// Address model: rizin's own bin-loader sets the load address for formats it
+// recognizes (iNES → 0x8000, GBA → 0x08000000, raw → 0). For platforms whose
+// flat file maps 1:1 to the CPU bus (Genesis, plain binaries) the file offset
+// IS the CPU address. We pass an explicit base only where it helps; the
+// reported addresses are rizin virtual addresses, which match the CPU view for
+// the common (unbanked / first-bank) case. Banked carts: a bank's window is
+// resolved by the existing disasm mappers — analysis here is whole-file.
+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";
+
+/** Sniff platform from a ROM extension (mirrors disasm.js). */
+export function sniffPlatform(p) {
+  if (/\.nes$/i.test(p)) return "nes";
+  if (/\.(sfc|smc)$/i.test(p)) return "snes";
+  if (/\.gbc$/i.test(p)) return "gbc";
+  if (/\.gb$/i.test(p)) return "gb";
+  if (/\.sms$/i.test(p)) return "sms";
+  if (/\.gg$/i.test(p)) return "gg";
+  if (/\.a26$/i.test(p)) return "atari2600";
+  if (/\.a78$/i.test(p)) return "atari7800";
+  if (/\.prg$/i.test(p)) return "c64";
+  if (/\.(lnx|lyx)$/i.test(p)) return "lynx";
+  if (/\.gba$/i.test(p)) return "gba";
+  if (/\.pce$/i.test(p)) return "pce";
+  if (/\.(gen|md|bin)$/i.test(p)) return "genesis";
+  return null;
+}
+
+/** rizin asm.bits per arch (analysis defaults; rizin's loader usually sets
+ * these for recognized formats, but raw blobs need a hint). */
+const BITS = { arm: 32, m68k: 32, snes: 16 };
+
+/** Build the common rizin invocation context for a ROM + platform. Returns
+ * { romBytes, arch, bits, note } — arch null means let rizin sniff. */
+async function loadContext(romPath, platformOverride) {
+  const platform = platformOverride ?? sniffPlatform(romPath);
+  if (!platform) {
+    throw new Error(
+      `analyze: could not determine platform from '${path.basename(romPath)}' — pass platform explicitly`
+    );
+  }
+  if (!(platform in RIZIN_ARCH)) {
+    throw new Error(`analyze: unsupported platform '${platform}'`);
+  }
+  const arch = RIZIN_ARCH[platform];
+  if (arch == null) {
+    throw new Error(`analyze: no Rizin arch mapping for platform '${platform}'`);
+  }
+  const 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 };
+}
+
+/** Hex-format an address the way agents expect for the platform width. */
+function hx(n) { return "0x" + (n >>> 0).toString(16); }
+
+/**
+ * Auto-detected function list for a ROM.
+ * @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 functions = fns.map((f) => ({
+    address: f.offset,
+    addressHex: hx(f.offset),
+    name: f.name,
+    size: f.size,
+    nbbs: f.nbbs,           // basic-block count
+    cc: f.cc,               // cyclomatic complexity
+    callers: f.indegree ?? (f.codexrefs?.length ?? 0),
+    callees: f.outdegree ?? 0,
+  }));
+  return { platform, arch, count: functions.length, functions };
+}
+
+/**
+ * Control-flow graph for the function containing `address`.
+ * @returns {{platform, address, nodes: Array<{id,address,size,instructions,jump,fail,out}>, edges}}
+ */
+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);
+  // 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,
+    commands: `aaa; af @ ${hx(address)}; afbj @ ${hx(address)}`,
+  });
+  if (!Array.isArray(blocks) || blocks.length === 0) {
+    return { platform, arch, address, addressHex: hx(address), nodes: [], edges: [], note: "no function/blocks at address" };
+  }
+  const nodes = blocks.map((b) => ({
+    id: b.addr,
+    address: b.addr,
+    addressHex: hx(b.addr),
+    size: b.size,
+    ninstr: b.ninstr,
+  }));
+  const edges = [];
+  for (const b of blocks) {
+    const conditional = b.fail != null;
+    if (b.jump != null) edges.push({ from: b.addr, to: b.jump, type: conditional ? "branch_true" : "jump_or_fall" });
+    if (b.fail != null) edges.push({ from: b.addr, to: b.fail, type: "branch_false" });
+  }
+  return {
+    platform, arch,
+    address, addressHex: hx(address),
+    blockCount: nodes.length,
+    nodes, edges,
+  };
+}
+
+/**
+ * All cross-references TO `address` across the ROM.
+ * @returns {{platform, address, count, refs: Array<{from, to, type}>}}
+ */
+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);
+  let refs;
+  try {
+    refs = await runRizinJson({ romBytes, arch, bits, 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".
+    if (/no JSON/.test(e.message)) refs = [];
+    else throw e;
+  }
+  const out = (refs ?? []).map((r) => ({
+    from: r.from,
+    fromHex: hx(r.from),
+    to: r.to,
+    type: (r.type || "").toLowerCase(), // CALL / CODE / DATA / STRING
+    opcode: r.opcode,
+  }));
+  return { platform, arch, address, addressHex: hx(address), count: out.length, refs: out };
+}
+
+/**
+ * One-shot structural map: functions + strings + entrypoints from a full
+ * 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 [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(() => []),
+  ]);
+  return {
+    platform, arch,
+    functionCount: Array.isArray(fns) ? fns.length : 0,
+    stringCount: Array.isArray(strings) ? strings.length : 0,
+    entrypoints: (Array.isArray(entries) ? entries : []).map((e) => ({ address: e.vaddr, addressHex: hx(e.vaddr) })),
+    functions: (Array.isArray(fns) ? fns : []).slice(0, 512).map((f) => ({
+      address: f.offset, addressHex: hx(f.offset), name: f.name, size: f.size, callers: f.indegree ?? 0,
+    })),
+    strings: (Array.isArray(strings) ? strings : []).slice(0, 256).map((s) => ({
+      address: s.vaddr, addressHex: hx(s.vaddr), value: s.string,
+    })),
+  };
+}
+
+/** Look up rizin's IO map (omlj) for the segment containing `vaddr`. Each map
+ * entry carries {from (vaddr base), delta (vaddr-paddr), to}. Returns
+ * { paddr, vbase } where paddr = vaddr-delta is the raw-file offset and vbase
+ * (= delta) is the address byte 0 of the file maps to on the CPU bus. */
+async function vaMapping(romBytes, arch, bits, vaddr) {
+  let maps;
+  try {
+    maps = await runRizinJson({ romBytes, arch, bits, commands: "omlj" });
+  } catch { maps = []; }
+  for (const m of (Array.isArray(maps) ? maps : [])) {
+    const from = m.from ?? m.vaddr ?? 0;
+    const to = m.to ?? (from + (m.size ?? 0));
+    if (vaddr >= from && vaddr < to) return { paddr: vaddr - (m.delta ?? 0), vbase: m.delta ?? 0 };
+  }
+  return { paddr: vaddr, vbase: 0 };
+}
+
+/**
+ * Decompile the function containing `address` to C pseudocode (Ghidra).
+ * @returns {{platform, langid, address, code, warnings, qualityNote}}
+ */
+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));
+
+  // 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);
+  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.
+  let forcedBase = 0, bodyStart = 0;
+  if (platform === "atari2600") {
+    forcedBase = 0xf000;
+  } else if (platform === "atari7800") {
+    const hasHdr = romBytes.length > 128 &&
+      romBytes[1] === 0x41 && romBytes[2] === 0x54; // "AT"
+    bodyStart = hasHdr ? 128 : 0;
+    const body = romBytes.length - bodyStart;
+    forcedBase = body <= 0x4000 ? 0xc000 : body <= 0x8000 ? 0x8000 : 0x4000;
+  }
+  const base = vbase > 0 ? vbase : forcedBase;
+  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);
+    image = padded;
+    decompAddr = base + (paddr - bodyStart); // 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,
+    warnings: r.warnings,
+    qualityNote: QUALITY[platform] ?? "unknown",
+  };
+}