romdevtools 0.29.0 → 0.40.0

package/AGENTS.md

@@ -65,12 +65,12 @@ Skip playtest only when there's clearly no human in the loop: CI runs, automated
 - `run` — load ROMs, step frames, screenshot (works for existing ROMs you didn't compile)
 - `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:'readCart'})`** reads the loaded cart image to confirm a patch is live. **`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); **`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)
+- `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)
 - `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; `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), **`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.
 
@@ -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,6 +4,108 @@ 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 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
+  `searchNext({compare:'dec'|'inc'|'unchanged'|'changed'|'gt'|'lt'})`. Finds the
+  lives/timer/ammo address you can't see on the HUD (`op:'search'` needs a value;
+  this doesn't).
+- **`memory({op:'diff'})` predicate filters** — `changeDir:'dec'|'inc'`,
+  `deltaEq:N` (signed exact delta, e.g. −1 = "lost a life"), `beforeMin/Max` +
+  `afterMin/Max` (value-range gates). A 500-byte death-window diff returns the
+  ~3 rows you want in one call.
+- **`memory({op:'diff'})` honors `outputPath` + `echo:false`** (was a bug — diff
+  ignored `outputPath`; a big diff now routes to your path, not a harness path).
+- **`memory({op:'readCart', cpuAddress, bank})`** — read cart ROM by a BANKED CPU
+  address (NES/SNES), the inverse of the breakpoint result's bank/prgOffset; no
+  more hand-computed `cpuAddr−0x8000+bank*0x4000`.
+- **`breakpoint({on:'write', condition})`** — stop on the MEANINGFUL write, not
+  restoring churn: `condition:'increase'|'decrease'` (the stored byte actually
+  moved that way) or `'equals'` + `conditionValue` (became N, e.g. a $00→$01
+  re-arm). Reports `oldValueByte`→`valueByte`. Live on **all 14 platforms** (11
+  emulator cores rebuilt to capture the pre-write byte). Also clarified in the
+  tool note that `on:'write'` runs to end-of-frame and reports the LAST matching
+  write (`hits` = count).
+- **Tool-schema slim** — dropped the inlined ~62-value region enum from every
+  SECONDARY region sub-param (`watch` per-range `ranges[].region`, `recordSession`
+  `memorySamples[].region`, and both `runUntil` memory conditions); they're now
+  runtime-validated strings, trimming the deferred-load schema cost the feedback
+  flagged. The ONE primary discoverable enum (`watch` on:'mem' single-range
+  `region`, where the region IS the choice) is intentionally kept. **Bonus fix:**
+  the `runUntil` region was a STALE hardcoded 8-value list that silently
+  schema-rejected valid non-NES regions (`genesis_cram`, `c64_color_ram`,
+  `nes_apu_regs`, …) the handler actually supports — now accepted.
+
+### Core rebuilds
+11 emulator cores rebuilt for the value-conditioned write breakpoint (bump +
+republish each): fceumm, snes9x, genesis-plus-gx, gambatte, mgba, handy,
+geargrafx, prosystem, stella2014, bluemsx, vice. **Build fix (latent, was on
+main):** the bluemsx region patch carried a duplicate Makefile CFLAGS hunk
+identical to the build patch's; since `git apply` is atomic, that made the whole
+region patch silently fail to apply — the watchpoint/region exposure was being
+dropped from the build. Removed the duplicate hunk.
+
 ## 0.29.0 — 2026-06-11
 
 ### Examples — the complete-game library, finished & made honest
@@ -119,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
@@ -288,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`
@@ -362,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 —
@@ -373,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
@@ -402,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):
@@ -475,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
@@ -557,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)
@@ -975,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
@@ -1187,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:
@@ -1204,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
@@ -1282,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.
@@ -1521,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.29.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,19 +50,21 @@
     "fuse.js": "^7.4.1",
     "omggif": "^1.0.10",
     "pngjs": "^7.0.0",
-    "romdev-core-bluemsx": "0.5.0",
-    "romdev-core-fceumm": "0.9.0",
-    "romdev-core-gambatte": "0.8.0",
-    "romdev-core-geargrafx": "0.6.0",
-    "romdev-core-gpgx": "0.11.0",
-    "romdev-core-handy": "0.6.0",
-    "romdev-core-prosystem": "0.7.0",
-    "romdev-core-vice": "0.8.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",
+    "romdev-core-geargrafx": "0.7.0",
+    "romdev-core-gpgx": "0.12.0",
+    "romdev-core-handy": "0.7.0",
+    "romdev-core-prosystem": "0.8.0",
+    "romdev-core-vice": "0.9.0",
     "romdev-famitone": "0.1.0",
     "romdev-maxmod": "0.1.0",
-    "romdev-platform-atari2600": "0.7.0",
-    "romdev-platform-gba": "0.7.0",
-    "romdev-platform-snes": "0.7.0",
+    "romdev-platform-atari2600": "0.8.0",
+    "romdev-platform-gba": "0.8.0",
+    "romdev-platform-snes": "0.8.0",
     "romdev-toolchain-cc65": "0.1.1",
     "romdev-toolchain-m68k-gcc": "0.2.0",
     "romdev-toolchain-rgbds": "0.1.0",