romdevtools 0.71.1 → 0.84.1

package/AGENTS.md

@@ -4,7 +4,7 @@ This is romdev's GENERIC orientation — read it once. The platform-specific det
 
 ## What this server does
 
-Drives the full homebrew ROM dev loop for 14 retro game platforms (NES, SNES, Game Boy, Game Boy Color, Game Boy Advance, Genesis, Sega Master System, Game Gear, Atari 2600/7800, Atari Lynx, Commodore 64, PC Engine / TurboGrafx-16, and MSX / MSX2). Build → run → screenshot → inspect → patch → iterate. Also a strong reverse-engineering kit: disassemble existing ROMs into byte-exact rebuildable projects (`disasm({target:'project'})`/`disasm({target:'references'})` — the workhorse for any structural hack), find a value's address with the Cheat-Engine search loop (`memory({op:'search'})`/`memory({op:'searchNext'})`), find the EXACT instruction that wrote a RAM byte (`breakpoint({on:'write'})`, a core-level write watchpoint), confirm a patch is live in the running image (`memory({op:'readCart'})`), tell whether a "found table" is really ASCII (`memory({op:'classify'})`), trace where an on-screen graphic comes from (`watch({on:'copy'})` on all 14 — writer PC per VRAM write; `watch({on:'dma'})` for Genesis DMA sources), drive menus by screen-change (`navigate`), and look up cheats (`cheats({op:'lookup'})`/`cheats({op:'search'})`: a free, crowd-sourced labeled RAM/code map for known ROMs), apply + create cheats, convert assets, study patterns from real games. **Doing a romhack? Start with `platform({op:'doc', platform:'romhacking', name:'playbook'})`** — the decision tree that wires all of the above together. Bundled WASM toolchains and emulator cores — no system dependencies, no installs.
+Drives the full homebrew ROM dev loop for 18 retro game platforms (NES, SNES, Game Boy, Game Boy Color, Game Boy Advance, Genesis, Sega Master System, Game Gear, Atari 2600/7800, Atari Lynx, Commodore 64, PC Engine / TurboGrafx-16, and MSX / MSX2, plus the open-hardware GameTank — and the 3D consoles Nintendo 64, Sony PlayStation, and Sega Dreamcast). Build → run → screenshot → inspect → patch → iterate. Also a strong reverse-engineering kit: disassemble existing ROMs into byte-exact rebuildable projects (`disasm({target:'project'})`/`disasm({target:'references'})` — the workhorse for any structural hack), find a value's address with the Cheat-Engine search loop (`memory({op:'search'})`/`memory({op:'searchNext'})`), find the EXACT instruction that wrote a RAM byte (`breakpoint({on:'write'})`, a core-level write watchpoint), confirm a patch is live in the running image (`memory({op:'readCart'})`), tell whether a "found table" is really ASCII (`memory({op:'classify'})`), trace where an on-screen graphic comes from (`watch({on:'copy'})` on the 15 classic platforms — writer PC per VRAM write; `watch({on:'dma'})` for Genesis DMA sources), drive menus by screen-change (`navigate`), and look up cheats (`cheats({op:'lookup'})`/`cheats({op:'search'})`: a free, crowd-sourced labeled RAM/code map for known ROMs), apply + create cheats, convert assets, study patterns from real games. **Doing a romhack? Start with `platform({op:'doc', platform:'romhacking', name:'playbook'})`** — the decision tree that wires all of the above together. Bundled WASM toolchains and emulator cores — no system dependencies, no installs.
 
 You drive the work. The human is a director — they may want a game, a ROM disassembly, a tool-assisted reverse-engineering session, or anything else this server can do.
 
@@ -20,7 +20,7 @@ This rule is about **compilers and emulators only** — NOT about content tools.
 
 ## The second rule: READ YOUR TARGET PLATFORM'S DOCS BEFORE YOU WRITE CODE FOR IT
 
-This doc is deliberately GENERIC — it can't hold 14 platforms' worth of detail without bloating every session. The knowledge that actually saves you — the memory map, the input/control quirks, the render-enable order, the codegen traps, the SDK's footguns — lives in each platform's docs, read on demand:
+This doc is deliberately GENERIC — it can't hold 18 platforms' worth of detail without bloating every session. The knowledge that actually saves you — the memory map, the input/control quirks, the render-enable order, the codegen traps, the SDK's footguns — lives in each platform's docs, read on demand:
 
 - **`platform({op:'doc', platform, name:'mental_model'})`** — read this for EVERY system you're about to build or RE on, BEFORE you write code. It's a couple hundred tokens and most "why won't this work" dead-ends are a documented footgun you'd have seen there (a C64 game that needs a keyboard key to start; an SDCC WRAM-layout trap; a platform's render-enable order; gambatte exposing `gb_vram` not `video_ram`).
 - **`platform({op:'doc', platform, name:'troubleshooting'})`** — the symptom→fix list; read it the moment something's broken.
@@ -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:'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'|'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)
+- `memory` — read/write VRAM/OAM/CGRAM/ARAM and other regions (all 18 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 15 classic platforms — 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 18), `audioDebug({op:'inspect'})` (the 13 systems with a sound chip — all but Atari 2600/7800; incl. GameTank's ACP coprocessor via `chip:'acp'`; pass `frames:N` to TRACE a per-channel note-timeline for headless melody asserts), `background({view:'renderState'})`, `breakpoint({on:'write'})` (write watchpoint, all 18; 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'})`** (the 15 classic platforms: 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'})`** (`bytes`/`rom`/`references` on all 18, `project` byte-exact reassembly on the 15 classic platforms (incl. GameTank, cc65/6502) — 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 18, incl. the 3D consoles' MIPS R3000/R4300 + SH-4 — 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), **`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
+- `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 18, `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 18 platforms; input recording
 
 **"Disassemble this NES ROM"** is now just: `disasm({target:'rom', path, startAddress, length})`. No discovery step.
 
@@ -116,7 +116,7 @@ questions, and running both early is normal.** A good default:
    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
+   Rizin/Ghidra analysis ops cover 18/18 platforms (incl. the 3D consoles' MIPS/SH-4). 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
@@ -311,10 +311,10 @@ For maintainers: the platform / core / patch / region-ID matrix and the recipe f
 
 ## Deep debug tooling status per platform
 
-Different platforms have different levels of MCP-exposed debugging — different hardware needs different tools, and we've patched the cores where it's been worth it. The generic shapes — `cpu({op:'read'})`, `breakpoint({on:'write'})`, `disasm({target:'rom'})`/`disasm({target:'references'})`/`disasm({target:'project'})`, `memory({op:'search'})`/`memory({op:'readCart'})`/`memory({op:'classify'})`, cheats — work on **all 14 platforms** (disassembly via native binutils `objdump` compiled to WASM, one per CPU family — incl. GBA ARM7/Thumb). The deep per-platform inspectors (`sprites({op:'inspect'})`, `palette({source:'live'})`, `background({view:'renderState'})`, `audioDebug({op:'inspect'})`) are detailed for **12 systems** below; **PC Engine and MSX** currently have the generic shapes + their core's native regions but not yet the full custom-inspector treatment (extend by patching their cores per the snes9x/gpgx pattern). `audioDebug({op:'inspect'})` covers the **12 with a sound chip** (all but Atari 2600/7800). A few are honest hardware-shaped exceptions, noted inline below (the Lynx has no fixed OAM so `sprites({op:'inspect'})` returns the SCB list head). Coverage detail per platform:
+Different platforms have different levels of MCP-exposed debugging — different hardware needs different tools, and we've patched the cores where it's been worth it. The generic shapes — `cpu({op:'read'})`, `breakpoint({on:'write'})`, `disasm({target:'rom'})`/`disasm({target:'references'})`, `memory({op:'search'})`/`memory({op:'readCart'})`/`memory({op:'classify'})`, cheats — work on **all 18 platforms** (disassembly via native binutils `objdump` compiled to WASM, one per CPU family — incl. GBA ARM7/Thumb and the 3D consoles' MIPS/SH-4); byte-exact `disasm({target:'project'})` reassembly is the **15 classic platforms** (incl. GameTank, cc65/6502). The deep per-platform inspectors (`sprites({op:'inspect'})`, `palette({source:'live'})`, `background({view:'renderState'})`, `audioDebug({op:'inspect'})`) are detailed for **12 systems** below; **PC Engine and MSX** currently have the generic shapes + their core's native regions but not yet the full custom-inspector treatment (extend by patching their cores per the snes9x/gpgx pattern). `audioDebug({op:'inspect'})` covers the **13 with a sound chip** (all but Atari 2600/7800; incl. GameTank's ACP coprocessor). A few are honest hardware-shaped exceptions, noted inline below (the Lynx has no fixed OAM so `sprites({op:'inspect'})` returns the SCB list head; GameTank is a blitter framebuffer with no sprite OAM / no tilemap, so `sprites({op:'inspect'})`/`background` are N/A). Coverage detail per platform:
 
-> **Universal across ALL 14 platforms:** `breakpoint({on:'write'})` (the core-level
-> instruction write watchpoint — the exact PC that wrote a RAM byte, all 14 CPU
+> **Universal across the 15 classic platforms:** `breakpoint({on:'write'})` (the core-level
+> instruction write watchpoint — the exact PC that wrote a RAM byte, all 15 classic CPU
 > families), **`breakpoint({on:'pc'})`** (execution breakpoint — freeze the CPU AT an
 > instruction and read its registers), **`breakpoint({on:'read'})`** (the exact PC that read
 > a byte — read-side mirror of `breakpoint({on:'write'})`), **`frame({op:'stepInstruction'})`** (CPU single-step),
@@ -332,7 +332,7 @@ Different platforms have different levels of MCP-exposed debugging — different
 > pass **`fromState`**/`fromStatePath` to restore a savestate FIRST so the trace runs from a
 > known, repeatable moment — jump to the boss, then see what writes HP),
 > **`watch({on:'pc'})`** (coverage trace — distinct PCs executed in a window; also takes `fromState`),
-> **the RE-INJECT trio** (put an edited asset BACK, all 14): **`romPatch({op:'findPointer'})`**
+> **the RE-INJECT trio** (put an edited asset BACK, all 15 classic platforms): **`romPatch({op:'findPointer'})`**
 > (find every pointer to a ROM offset — Genesis 32-bit BE, SNES LoROM/HiROM, GBA
 > 0x08000000+offset incl. literal pools, banked 8-bit 16-bit-LE aliases),
 > **`romPatch({op:'makeStored'})`** (wrap raw bytes so the game's OWN decompressor expands them
@@ -342,11 +342,11 @@ Different platforms have different levels of MCP-exposed debugging — different
 > `cheats({op:'lookup'})`/`cheats({op:'search'})`/`cheats({op:'apply'})`/`cheats({op:'make'})` (cheat
 > lookup/apply/create), `cpu({op:'read'})`, `memory({op:'search'})`/`memory({op:'searchNext'})`/`memory({op:'readCart'})`/`memory({op:'classify'})`,
 > `memory({op:'snapshot'})`/`memory({op:'diff'})`/`state({op:'diff'})`, `watch({on:'mem'})`/`breakpoint({on:'write',precision:'sampled'})`.
-> `audioDebug({op:'inspect'})` covers the 12 systems with a sound chip (all but Atari 2600/7800).
+> `audioDebug({op:'inspect'})` covers the 13 systems with a sound chip (all but Atari 2600/7800; incl. GameTank's ACP coprocessor).
 > **`watch({on:'dma', precision:'exact'})`** (which DMA wrote a VRAM tile, and from where) is **Genesis-only**
 > (VDP DMA) — elsewhere use `breakpoint({on:'write'})`/`watch({on:'range'})`. All other RE tools above
-> work on every platform that has the register-write/watch core hooks (all 14).
-> `disasm({target:'rom'})` + `disasm({target:'references'})` + `disasm({target:'project'})` cover **all 14** — every
+> work on every platform that has the register-write/watch core hooks (the 15 classic platforms).
+> `disasm({target:'rom'})` + `disasm({target:'references'})` cover **all 18** (incl. the 3D consoles' MIPS/SH-4), and `disasm({target:'project'})` byte-exact reassembly the **15 classic platforms** (incl. GameTank) — every
 > CPU family disassembles through a native binutils `objdump` (WASM), and
 > `disasm({target:'project'})` reassembles byte-exact through the matching native
 > `as`/`ld`/`objcopy`. The per-platform notes below cover the platform-SPECIFIC
@@ -365,6 +365,7 @@ The deep per-platform inspectors + the exact memory-region names, core quirks, a
 - **Atari Lynx** — `sprites({op:'inspect'})` returns an SCB list head (no fixed OAM), or you need the Mikey palette/audio, 65C02 regs, or the `lynx_hw_regs` $FC00-$FDFF window.
 - **MSX** — VDP/PSG inspection or AY8910 `audioDebug`. (ColecoVision is bring-up-only: standard `system_ram`/`save_ram`/`video_ram`, no custom inspectors — extend by patching its core per the snes9x/gpgx pattern.)
 - **PC Engine** — generic shapes + the core's native regions only so far (no custom-inspector treatment yet).
+- **GameTank** — Clyde Shaffer's open-hardware W65C02S console (cc65 toolchain, ext `.gtr`). Full classic-style Tier-1: `cpu({op:'read'})` (65c02 regsnap), `audioDebug({op:'inspect', chip:'acp'})` (the ACP audio coprocessor), `breakpoint({on:'write'|'read'|'pc'})` + watchdog + coverage, `disasm` (`bytes`/`rom`/`references` + the 6502 Rizin/Ghidra cfg/xrefs/functions/decompile path), `cart({op:'extract'|'wrap'})`, and the 6502 re-inject path (`romPatch`) same as NES/C64/Lynx. **No `sprites({op:'inspect'})`/`background`** — it's a blitter framebuffer with no sprite OAM / no tilemap (like the Dreamcast). No genre example games yet (brand-new platform).
 
 Starter snippets per platform live under `src/platforms/<platform>/lib/`. Discover via `examples({op:'snippets', platform})` (default `mode:'list'`), fetch one via `examples({op:'snippets', platform, mode:'get', snippetName})`. SNES + NES + Genesis + SMS + Game Boy + Atari 2600 + Atari 7800 have substantial snippet libraries; others are minimal.
 
@@ -483,7 +484,7 @@ to avoid), plus the per-asset round-trips (text, compressed assets, graphics) an
 Quick-reference table. Don't reconstruct the flow from this summary — it's only here so
 you know the capability exists and where the detail lives.
 
-Key primitives (all bundled, all 14 tier-1 systems unless noted; full detail in the
+Key primitives (all bundled, all 15 classic tier-1 systems unless noted; full detail in the
 playbook):
 
 - **Find a value's RAM address** — the Cheat-Engine loop `memory({op:'search'})` →
@@ -523,7 +524,9 @@ breakpoint trio (`pc`/`read`/`stepInstruction`) is in `advanced`.
 
 ## Disassembler
 
-`disasm({target:'rom'|'references'|'project'})` covers **all 14 platforms** — every CPU
+`disasm({target:'rom'|'references'})` covers **all 18 platforms** (incl. the 3D consoles'
+MIPS R3000/R4300 + SH-4); byte-exact `disasm({target:'project'})` reassembly is the **15
+classic platforms** (incl. GameTank, cc65/6502). Every CPU
 family disassembles through a native binutils disassembler compiled to WASM (no
 hand-rolled JS decoders): 6502/65816 via cc65's `da65`, Z80 (SMS/GG/MSX) + SM83
 (GB/GBC) via one z80-elf `objdump` (`-m z80` / `-m gbz80`), m68k (Genesis) via
@@ -706,7 +709,7 @@ Two tools that save real time and frustration:
 
 `input({op:'set'})` accepts an Xbox-shaped controller: D-pad, 4 face buttons (use `north/east/south/west` for portable code — they translate per platform), shoulders (`l/r`), triggers (`l2/r2`), sticks (`l3/r3`), plus `start`/`select`. Older platforms are subsets — `input({op:'layout'})` tells you which buttons are real. Pressing a non-existent button is a silent no-op.
 
-⚠ **The raw libretro names `a`/`b`/`x`/`y` are NOT the platform's printed button labels — and on the three genesis_plus_gx platforms (Genesis, SMS, Game Gear) they're INVERTED.** Verified live across all 14 platforms:
+⚠ **The raw libretro names `a`/`b`/`x`/`y` are NOT the platform's printed button labels — and on the three genesis_plus_gx platforms (Genesis, SMS, Game Gear) they're INVERTED.** Verified live across all 14 classic platforms:
 - **Genesis**: gpgx maps Genesis A/B/C onto libretro **y/b/a** — so `input({op:'set', a:true})` presses Genesis **C**, and Genesis A (SGDK `BUTTON_A`) is `{y:true}` / `{west:true}`.
 - **SMS / Game Gear**: button 1 (TL, main fire) is libretro **b**, button 2 (TR) is libretro **a** — so `{a:true}` presses button 2, not 1.
 - **Every other core maps straight through** (`{a}`→A, `{b}`→B): NES, GB/GBC, SNES (incl. x/y/l/r), GBA, PC Engine (a=I, b=II), MSX (a=trig 1), Lynx (a=A). C64 + Atari 2600 are single-fire — fire is `{b}`/`{south}`, `{a}` is a no-op. Atari 7800 boots in 1-button mode (both fires read INPT4) until you enable 2-button mode.

package/CHANGELOG.md

@@ -4,6 +4,190 @@ 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.84.1 — 2026-06-30
+
+- **New package `romdev-audio-resampler`** — the WASM+SIMD linear audio resampler (interleaved
+  S16LE stereo, any src→dst rate) is carved out of `src/playtest/resampler/` into its own
+  standalone, zero-dep npm package so other projects can consume it (retroemu's terminal audio
+  path needs it to resample fractional-rate cores like the GameTank ACP's ~13983 Hz up to a
+  fixed device rate — the way a libretro frontend does). romdevtools now depends on it; the
+  playtest audio sink imports it instead of the in-tree copy. No behavior change here.
+
+## 0.84.0 — 2026-06-30
+
+**The 3D GL cores are now PLAYABLE in the SDL playtest window — N64 + PS1 at full speed.**
+Until now the hardware-rendered cores (n64/ps1/dreamcast, all `hwRender:true`) rendered
+headlessly but couldn't be driven interactively. Verified end-to-end: **Mario Kart 64
+(N64)** and **Crash Bandicoot (PS1)** play in the window at full speed with sound and a
+standard controller. Five fixes, all in `src/playtest/playtest.js` + `src/host/`:
+- **Software-blit window for hwRender cores.** An `accelerated:true` SDL window makes a GLX
+  context that collides with native-gles's EGL context → `X_GLXMakeCurrent BadAccess` server
+  crash. hwRender cores now open `accelerated:false` (they only present CPU readback pixels).
+- **RGBA8888 in the window's pixel converter** — the hwRender readback format was unhandled →
+  black window. Added (with the alpha=255 force the GL FBO needs).
+- **Audio-paced stepping, wall-clock budgeted.** Step extra frames per tick to keep SDL's
+  buffer full, but cap the burst by WALL-CLOCK (≤1.5 ticks), not a frame count. A frame-count
+  cap froze the event loop on slow cores (8 frames × 60ms = 480ms) → stutter death-spiral;
+  the time budget keeps the window responsive and the audio steady. (Fixes the N64 choppy
+  audio too — parallel-n64 emits ~91 frames of audio per real second, not 60.)
+- **N64 analog stick + full pad map.** `inputStateCb` handles `RETRO_DEVICE_ANALOG` (synthesize
+  ±32767 from the d-pad); N64-specific pad map (Z = a free face button, C-buttons = right
+  stick — the analog triggers idle half-pressed and aren't used by N64).
+- **No per-frame serialize on hwRender.** The rewind buffer AND the auto-checkpoint both call
+  `serializeState()` — fine for 8/16-bit (KB) but brutal on a 16MB N64/DC state (~18ms/call).
+  Skipped entirely when `host.hwRender`.
+
+**Dreamcast: boots commercial GD-ROM games, but EXPERIMENTAL / not yet playable.** flycast now
+loads + renders real discs (Sonic Adventure, Crazy Taxi) — a first — via two fixes: the
+**GLES (WebGL2) renderer** (`-DUSE_GLES=ON`; the desktop-GL path called `glClearDepth` which
+WebGL lacks → a frame-58 crash), and **NODERAWFS disc streaming** (`-s NODERAWFS=1` + a host
+`noderawfs` path) so libchdr seeks the disc off Node's real fs instead of loading the whole
+CHD into the WASM heap (an 872MB Sonic CHD OOM'd a 1GB heap). BUT on the interpreter core DC
+runs at ~5 fps — **unplayable.** It ships on the correct interpreter; the WASM SH-4 JIT (78fps,
+integrated behind `ROMDEV_FLYCAST_JIT=1`) has native-emit bugs that hang Sonic's boot and is a
+documented next step (internal). DC is labeled experimental, not a playable platform.
+
+## 0.83.0 — 2026-06-30
+
+**GameTank examples: 5 genre games reworked into shippable, hardware-tested shape.**
+The GameTank example set (`examples/gametank/templates/`) went from thin scaffolds
+to five complete, play-tested games (verified on real RetroDeck hardware): `shmup`,
+`platformer`, `puzzle`, `sports`, `racing`. Along the way several real GameTank
+blitter/SDK footguns were isolated and are now documented in the shared headers so
+future games dodge them:
+- **A box of width OR height exactly 128 is silently DROPPED** by the blitter (a
+  full-screen-dimension fill never draws). Clamp to 127. (Hit as a "vanishing
+  ground" / "no road" bug.) Documented in `gt_draw.h`.
+- **Box top-edge scanlines flicker between the two double-buffer pages** — only the
+  border-clear path paints the screen's edge rows cleanly. Frames that draw near the
+  top finish with `queue_clear_border(topColor)` (drawn LAST; HUD text that must sit
+  in rows 0-6 goes AFTER it). Documented in `gt_draw.h`.
+- **The SDK `rnd()` corrupts game state on the single-bank build** — use the inline
+  `rnd8()` xorshift in `gt_draw.h` instead. (Broke enemy spawning until found.)
+- **GRAM sprite blits are the per-frame cost** — too many overrun the vblank window
+  and the draw queue drops rects (platforms flicker/vanish). Keep sprites few (the
+  platformer blits only the hero; coins are cheap rects).
+- New shared helpers: `gt_hud.h` gained a 3×5 A–Z text font (`hud_text`); `gt_draw.h`
+  exposes `rnd8()`. `gt_sound.h` SFX wired into sports (wall/paddle/score) and racing
+  (crash). `puzzle` is now a faithful Columns-style 3-jewel matcher (CHROMA WELL):
+  3-tile falling column, A/B color-cycle, horizontal/vertical/diagonal matching with
+  gravity chains. Platformer gained a 3-frame walk cycle, signed/clamped jump physics
+  (no more unsigned-wrap fall-death), swept platform-landing (no tunneling), and a
+  coin pickup chime. `examples/README.md` gained the GameTank row.
+
+## 0.82.0 — 2026-06-29
+
+**New platform: GameTank — the 18th system, a full Tier-1.** Clyde Shaffer's
+open-hardware [GameTank](https://gametank.zone/) (a W65C02S console: 128×128
+hardware-blitter framebuffer + a second 65C02 audio coprocessor) is now a
+first-class romdev platform, held to the SAME Tier-1 contract as the 14 classic
+2D systems — not the partial 3D-console tier.
+- **Build** via cc65 (`--cpu 65c02`, `-t none`) + a bundled single-bank 32 KB
+  preset (linker cfg + crt0 + vectors + `gametank.h`). Output is a flat `.gtr`
+  (EEPROM32K, size-keyed mapper). The cc65 dispatch gained a per-platform CPU
+  override (the `-t none` path needs an explicit `--cpu`) + preset-bundled
+  headers; both reusable by future cc65 platforms.
+- **Run + render** through `monteslu/gametank-libretro` (built to WASM).
+- **Full debug surface** — the core is patched with the shared romdev_debug
+  hooks: `cpuState` (live 65C02 regs), write/read **watchpoints**, **pc-break**,
+  **watchdog**, **coverage**, `setReg`/`getReg`. Same machinery every other
+  instrumented core links.
+- **audioDebug** (`chip:'acp'`) — the ACP audio coprocessor's state (DAC output,
+  IRQ/sample rate, run/mute, the audio-CPU PC).
+- **cart** extract/wrap — split a `.gtr` into body + the `$FFFA` vector table
+  (size-keyed mapper detect), and re-wrap for the extract→patch→rebuild cycle.
+- **disasm/decompile** — the existing 6502 Rizin/Ghidra path covers it.
+- N/A by hardware (like Dreamcast): `inspectSprites` (blitter, no OAM),
+  `inspectBackground` (framebuffer, no tilemap). No genre scaffolds yet.
+
+New packages: `romdev-core-gametank`. The capability conformance test holds
+GameTank to the full Tier-1 contract (13/13).
+
+## 0.81.0 — 2026-06-29
+
+**Shared toolchain layers.** The same de-duplication pass the debug ABI got, applied
+to `src/toolchains/` — three small shared modules under `common/` collapse what every
+wrapper and C-SDK builder re-implemented. Pure de-duplication: every argv, `/work`
+path, output encoding, log header, stage name, and return shape is byte-for-byte
+unchanged — no behavior change.
+- **`common/wasm-tool.js`** — the glue-resolution dance (`import.meta.resolve(pkg)` →
+  local `src/` fallback → throw install hint) that ~15 wrappers each duplicated, plus
+  the `runIsolated` input-file marshalling. `makeGlueResolver` / `resolveGlueFile`
+  (file-glue: asar, wladx, rgbds, dasm, vasm68k, sjasm, tcc816, z80/sdas, da65) +
+  `resolveToolBaseDir` (base-dir: cc65, sdcc).
+- **`common/gcc-toolchain.js`** — `makeGccToolchain(config)`. The arm/m68k/mips/sh GCC
+  wrappers were ~73% identical (cc1→as→ld→objcopy); each is now a ~67-line config object
+  + thin named re-exports (callers keep `runM68kAs` etc). MIPS endian (N64 big / PS1
+  little) handled via per-stage flag functions. ~210 → 67 lines each.
+- **`common/c-build.js`** — `CBuild` stage-runner + `BuildError`. The 5 GCC/tcc C-SDK
+  builders (gba/genesis/mips/sh/snes-c) plus cc65 repeated the
+  `run → log += → if (fail) return {ok:false,…,stage,…crash}` dance ~73×; it's now
+  `cb.stage(name, run, pick)` (throws `BuildError`) + a single try/catch that maps back
+  to the exact result via `e.toResult(extra)`. `BuildError.fields()` serves the cc65
+  shape (no `ok` field — index.js adds it). All 17 systems' C compilers now run through
+  the shared layers; sdcc is a documented partial fit (shares the log accumulator, keeps
+  its bespoke per-TU failure context). Full suite 1084/1084.
+
+## 0.80.0 — 2026-06-29
+
+**Shared debug ABI library.** The per-core debug instrumentation (watchpoints,
+read-watch, range-watch, PC coverage, PC breakpoints, the instruction watchdog,
+and the at-hit register snapshot) was ~700 lines of nearly-identical C inlined
+into every core's patch. It's now ONE shared library — `scripts/romdev-debug/
+romdev_debug.{h,c}` — that every migrated core links against. Each core keeps only
+a small hook shim (bus taps + dispatch hook + its CPU-specific register snapshot);
+the machinery and every host-probed `romdev_*` export live in exactly one place.
+
+This is purely internal — **no tool or ABI behavior changes** for callers. The
+payoff: the host ↔ core debug contract can no longer drift per core, adding the
+debug surface to a new core drops from ~700 lines to ~80, and a new conformance
+test makes any drift a hard failure.
+
+- **Shared lib + ABI contract** (`romdev_debug.h`): the ~16 host-probed exports +
+  the core-hook interface (`romdev_on_write/on_read/on_dispatch` returning hit/freeze
+  signals; `romdev_is_frozen`/`romdev_pc_hit_kind`/`romdev_wp_wants_old`/`romdev_any_armed`
+  accessors).
+- **10 cores migrated**, spanning every CPU family in the project: gambatte (sm83),
+  fceumm (6502), genesis-plus-gx (m68k **and** z80 — both CPUs now feed the SAME shared
+  debug state, replacing the old "m68kcpu.c defines, z80.c externs" split), snes9x
+  (65816), vice (6510/C64), prosystem (6502/7800), stella2014 (6507/2600), geargrafx
+  (HuC6280/PCE), bluemsx (z80/MSX), and mgba (ARM7TDMI/GBA — the lone 32-bit RISC core).
+  Each per-core patch shrank substantially (e.g. fceumm 869→421, snes9x 814→449,
+  genesis 1249→738, mgba 934→437 lines).
+- **handy (Lynx 65C02) migrated too — the last inline holdout.** A first attempt regressed
+  CPU execution; the root cause turned out to be the read hook. The Lynx's `CPU_PEEK`
+  reads memory OR a hardware I/O register (`mSystem.Peek_CPU` at $FC00+), and reading an
+  I/O register has SIDE EFFECTS (clears a status bit / advances a FIFO). The first migrated
+  read macro was an expression (comma-operator) form that re-evaluated the underlying read
+  2-3× → the I/O register got read multiple times per access → corrupted hardware state →
+  the CPU never reached its main loop (looked like a "freeze"). Fixed by reading the source
+  EXACTLY ONCE into a temp via a GCC statement-expression before calling `romdev_on_read`.
+  Patch shrank 640→251 lines. With this, **all 13 instrumented cores share the lib** — no
+  inline holdouts remain. (Also fixed the libretro.cpp frame-loop guard, which referenced
+  the now-private `romdev_pc_hit` symbol directly → switched to the `romdev_is_frozen()`
+  accessor like every other migrated core.)
+- **The newer cores too — and ONE PS1 core now.** N64 (parallel-n64, MIPS R4300) had its
+  own divergent debug snippet (a second copy of the machinery with a 2-arg pcbreak_set that
+  silently dropped the host's step arg → single-step was BROKEN); it now uses the shared lib
+  via a thin shim (R4300 snapshot + RDRAM canon + call-site adapters), single-step fixed.
+  **PS1 was split across TWO cores** — beetle-psx-hw (the GPU/GL renderer, but read-only
+  state) and pcsx-rearmed (full debug, but software-render + not even wired into the
+  registry). That split was useless — you couldn't get GPU *and* debugging in one core. So
+  the full debug surface (watchpoints, pc-break, single-step, range, coverage) was added
+  DIRECTLY to **beetle-psx-hw** (shared lib + a shim hooking mednafen's WriteMemory/
+  ReadMemory + the CPU_RunReal interpreter loop), and **pcsx-rearmed was deleted entirely**
+  (package, build script, snippets, version pin). PS1 is now ONE core that GPU-renders AND
+  fully debugs. Dreamcast (flycast, SH-4) has no debug machinery — only read-only SH-4/AICA
+  state accessors (irreducibly per-core), nothing to migrate. **all 13 instrumented cores share the lib** (Lynx included — see below). Also fixed a missing package-stage step in the
+  beetle build (rebuilds appeared to "do nothing" since the registry loads the package copy).
+- **`test/romdev-debug-abi.test.js`**: loads each migrated core's wasm and asserts the
+  full shared ABI is exported — drift fails the suite (now guards all 13, incl N64 + beetle PS1 + Lynx). 
+  **`test/romdev-debug-lib.test.js`** compiles the lib natively and checks its logic.
+- Build wiring: each migrated `build-<core>.sh` stages + includes (`INCFLAGS_PLATFORM`)
+  + compiles/archives `romdev_debug.c`. Author guide for the shim-only flow is in
+  `BUILDING.md`. (CRLF cores — gpgx z80, vice, prosystem — generate the patch against an
+  LF-normalized baseline so `git diff` doesn't explode.)
+
 ## 0.71.1 — 2026-06-29
 
 Feedback from the first run against the `pret/pokeruby` GBA decompilation.

package/README.md

@@ -1,6 +1,6 @@
 # romdev
 
-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, PC Engine, MSX — and the 3D consoles N64, PlayStation, and Dreamcast) with one command — drive it yourself or let a coding assistant do it.
+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, PC Engine, MSX, GameTank — and the 3D consoles N64, PlayStation, and Dreamcast) with one command — drive it yourself or let a coding assistant do it.
 
 ```bash
 npx romdevtools
@@ -9,9 +9,9 @@ npx romdevtools
 **What you get:**
 
 - **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. The 2D consoles render in software; the 3D consoles (N64 via glide64, PlayStation via Beetle PSX HW, Dreamcast via Flycast) render on the **real GPU** through [`native-gles`](https://github.com/monteslu/native-gles) — headless OpenGL/EGL, no browser. PlayStation ships [OpenBIOS](https://github.com/grumpycoders/pcsx-redux) (MIT) embedded, so there's no proprietary firmware to supply.
+- **Run + see + drive** — load the ROM into an emulated console (libretro cores as WASM), step frames, screenshot, script controller input. The 2D consoles render in software; the 3D consoles (N64 via glide64, PlayStation via Beetle PSX HW, Dreamcast via Flycast) render on the **real GPU** through [`native-gles`](https://github.com/monteslu/native-gles) — headless OpenGL/EGL, no browser. PlayStation ships [OpenBIOS](https://github.com/grumpycoders/pcsx-redux) (MIT) embedded, so there's no proprietary firmware to supply. **Dreamcast is EXPERIMENTAL** — it boots and renders, but the WASM build runs the SH-4 (+ AICA) as interpreters, so it's currently too slow to be playable; treat it as analysis/RE-only for now.
 - **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 (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.
+- **Reverse-engineering analysis engine (all 18 platforms — incl. the 3D consoles' MIPS R3000/R4300 + SH-4)** — 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:
@@ -36,12 +36,12 @@ This package contains all the JavaScript — the tool surface, the WASM emulator
 
 `romdevtools` depends on the binary/data packages it needs (exact-pinned), so a single install gets a matched, tested set:
 
-- 2D cores: `romdev-core-{fceumm,gambatte,gpgx,vice,handy,prosystem,geargrafx,bluemsx}`
+- 2D cores: `romdev-core-{fceumm,gambatte,gpgx,vice,handy,prosystem,geargrafx,bluemsx,gametank}`
 - 3D / GPU cores (rendered through `native-gles`): `romdev-core-{parallel-n64,beetle-psx-hw,flycast}`
 - Platforms (core + dedicated toolchain bundled): `romdev-platform-{snes,gba,atari2600}`
 - Toolchains: `romdev-toolchain-{cc65,sdcc,m68k-gcc,vasm,rgbds,mips-gcc,sh-gcc}` (mips-gcc = N64/PS1 C; sh-gcc = Dreamcast C)
 - GPU deps (OPTIONAL — only the 3D cores need them; the 2D cores never touch GL): `native-gles` + `webgl-node`. A headless user without a GPU stack can still run all the 2D platforms.
-- 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.
+- 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 18 CPUs, incl. MIPS R3000/R4300 + SH-4). 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/README.md

@@ -26,6 +26,7 @@ Each example fits the convention:
 | gba          | `gba/templates/*.c`  | arm-none-eabi-gcc | Default runtime = **libtonc** (`#include <tonc.h>`). 9 examples incl. `tonc_hello`, `tonc_hello_sprite`, the 5 genre games, and `maxmod_demo` (music). Pass `runtime:"libgba"` for the devkitPro API, `runtime:"none"` for bare newlib. **Always call `irq_init(NULL); irq_add(II_VBLANK, NULL);` before `VBlankIntrWait()`** — otherwise the BIOS halts forever. |
 | pce          | `pce/<template>/main.c` | cc65 (HuC6280) | HuCard homebrew, no BIOS. Ships a direct-register VDC/PSG helper lib (`pce.h` + `pce.lib`) — cc65 has no PCE sprite/sound library. Examples: `sprite_move`, `catch_game`, `music_sfx`, plus the 5 genre games (shmup/platformer/puzzle/sports/racing). **`#include <stdint.h>`** for int8/16/32_t — `pce.h` only typedefs u8/u16. The genre games fill the BAT (32×32 virtual screen); the platformer smooth-scrolls via the VDC BXR register. |
 | msx          | `msx/<template>/main.c` | sdcc (z80) | Boots cartridge homebrew on the open C-BIOS (no proprietary ROM). Ships an AY-3-8910 + TMS9918/V9938 VDP helper lib (`msx_hw.h` + `msx_vdp.c`). Examples: `sprite_move`, `catch_game`, `music_sfx`, plus the 5 genre games. The bundled `msx_crt0.s` (applied by the dir-build recipe automatically) emits the `"AB"` cartridge header at $4000 + INIT pointer — **C-BIOS shows its logo for ~2-3 s, then CALLs INIT**, so run ≥240 frames before screenshotting. The platformer column-streams the SCREEN 2 name table for a tile-by-tile scroll. |
+| gametank     | `gametank/templates/*.c` | cc65 (W65C02S) | Build with `linkerConfig:"sdk"` + the bundled SDK runtime (`src/platforms/gametank/lib/gt/*`). FIVE complete genre games, fully reworked and play-tested on real hardware (RetroDeck): `shmup`, `platformer`, `puzzle` (CHROMA WELL — a Columns-style 3-jewel matcher), `sports` (2-player paddle), `racing`. The GameTank is a **framebuffer + blitter** machine — NO tilemap/nametable: every frame is redrawn from scratch via the SDK **draw QUEUE** (`gt_draw.h`), the only correct way to drive the blitter (synchronous blits corrupt the FB + tank the framerate). Shared helper headers the games fork: `gt_draw.h` (queue wrappers + `rnd8`), `gt_palette.h` (VERIFIED color indices), `gt_sprites.h` (GRAM sprite load/blit), `gt_hud.h` (box-font digits + 3×5 A–Z text), `gt_sound.h` (one-shot ACP SFX). **HARD-WON GOTCHAS (all documented in `gt_draw.h`): (1) a box of width OR height 128 is silently DROPPED — clamp to 127; (2) box top-edge scanlines flicker between the double-buffer pages — finish a frame that draws near the top with `queue_clear_border(topColor)`; (3) use `rnd8()`, NOT the SDK `rnd()`, which corrupts state on this single-bank build.** Per-frame GRAM **sprite** blits are the expensive part — too many overrun vblank and the queue drops draws (flicker), so keep sprites few (e.g. the platformer blits only the hero; coins are rects). |
 
 ## Guides
 

package/examples/gametank/templates/gt_draw.h

@@ -0,0 +1,91 @@
+/* ── gt_draw.h — GameTank drawing for the romdev examples (SDK draw-queue) ─────
+ *
+ * Thin wrappers over the GameTank SDK's draw QUEUE — the ONLY correct way to drive
+ * the blitter. You enqueue rects (queue_draw_box); the blit-done IRQ pulls them off
+ * the queue one at a time and triggers each blit when the previous one finishes
+ * (interrupt.s _irq_int → next_draw_queue). await_draw_queue() blocks until the
+ * queue has fully drained, then you wait one VBLANK and flip the double buffer.
+ *
+ * WHY NOT fire blits synchronously: a blit takes WIDTH*HEIGHT CPU cycles to run
+ * (the core schedules its done-IRQ that many cycles ahead; instant_mode is off).
+ * Triggering the next blit before the current one finishes calls ClearIRQ and
+ * reschedules — stomping the in-flight blit. Firing ~30 rects back-to-back that
+ * way both corrupts the framebuffer (static) and piles scheduled cycles against
+ * await_vsync (≈2 fps). The queue exists precisely to serialize blits correctly;
+ * use it.
+ *
+ * Frame pattern:
+ *   gt_clear(bg);  ...gt_rect(...) for everything... ;  gt_present();
+ * where gt_present() = await_draw_queue() + await_vsync(1) + flip_pages().
+ *
+ * ── TWO BLITTER FOOTGUNS (cost many hours each — heed them) ──
+ *  1. A box whose WIDTH or HEIGHT is exactly 128 (the full screen dimension) is
+ *     SILENTLY DROPPED — it never draws. A full-width ground/background/HUD slab at
+ *     width 128 just vanishes, leaving whatever was under it. ALWAYS clamp to 127.
+ *     (The bottom row / right column is TV overscan anyway, so 127 loses nothing.)
+ *  2. A box's TOP scanline flickers between the two double-buffer pages — only
+ *     gt_clear's border-clear path can paint the screen's edge rows (0-6 top, the
+ *     bottom overscan, the side columns) cleanly. If your frame draws sprites or
+ *     full-height rects near the top, finish it with `queue_clear_border(topColor)`
+ *     as the LAST draw so the border scanlines stay solid (no stray flickering line).
+ *     If you also want HUD text up at the very top (rows 0-6), draw it AFTER the
+ *     border-clear (the clear would otherwise erase it).
+ *
+ * Colors are palette indices — see gt_palette.h for VERIFIED vibrant ones.
+ * Audio (gt_sound.h) runs on the ACP independently. Random: use rnd8() (below), NOT
+ * the SDK rnd() — rnd() corrupts game state on this single-bank build.
+ */
+#ifndef GT_DRAW_H
+#define GT_DRAW_H
+#include "gametank.h"
+#include "draw_queue.h"   /* queue_draw_box, queue_clear_screen, queue_clear_border, await_draw_queue */
+#include "gfx_sys.h"      /* await_vsync, flip_pages, init_graphics */
+
+#define SCREEN_W 128
+#define SCREEN_H 128
+
+/* Tiny xorshift byte PRNG. USE THIS, NOT the SDK's rnd() — rnd() (feature/random/
+ * random.c) corrupts game state on the EEPROM32K single-bank build (it broke enemy
+ * spawning in the shooter for a long time). rnd8() needs no init and never zero-locks. */
+static unsigned char gt_rng_state = 0x5A;
+static unsigned char rnd8(void) {
+  gt_rng_state ^= (unsigned char)(gt_rng_state << 1);
+  gt_rng_state ^= (unsigned char)(gt_rng_state >> 1);
+  gt_rng_state ^= (unsigned char)(gt_rng_state << 2);
+  return gt_rng_state;
+}
+
+/* enqueue one filled rectangle (drawn by the blit-done IRQ, in order). */
+#define gt_rect(x, y, w, h, color) queue_draw_box((x), (y), (w), (h), (color))
+
+/* clear the whole frame: fill the play area + the border (queue_clear_screen
+ * leaves a border uncleared — without queue_clear_border it shows VRAM static). */
+static void gt_clear(unsigned char color) {
+  queue_clear_screen(color);
+  queue_clear_border(color);
+}
+
+/* present the frame: drain the draw queue (wait for every enqueued blit to
+ * finish), wait one VBLANK, then flip the double buffer. Once per frame, after
+ * all your gt_rect()s. This is the SDK's canonical end-of-frame sequence. */
+static void gt_present(void) {
+  await_draw_queue();
+  await_vsync(1);
+  flip_pages();
+}
+
+/* "press to start" gate. Returns 1 once the START or A button has been HELD for a
+ * couple of frames. A short settle counter at the top of each title screen ignores
+ * the first few frames (so a button still held from the previous screen / boot can't
+ * auto-skip), then any held press starts. Level-triggered → can't miss a tap, and
+ * doesn't depend on ever reading a clean all-zero input frame. Call once per
+ * title-loop iteration AFTER update_inputs(). (Needs <input.h>.) */
+static unsigned char gt_start_settle;
+#define GT_START_MASK (INPUT_MASK_START | INPUT_MASK_A)
+static void gt_start_reset(void) { gt_start_settle = 0; }   /* call before each title loop */
+static unsigned char gt_start_pressed(void) {
+  if (gt_start_settle < 12) { gt_start_settle++; return 0; }  /* ignore first ~12 frames */
+  return (player1_buttons & GT_START_MASK) ? 1 : 0;
+}
+
+#endif /* GT_DRAW_H */

package/examples/gametank/templates/gt_hud.h

@@ -0,0 +1,89 @@
+/* ── gt_hud.h — box-drawn HUD digits for the romdev GameTank examples ─────────
+ *
+ * The SDK's text_print_string() draws a FONT that's baked by the Node asset
+ * pipeline (a .bmp loaded into GRAM) — not available on romdev's bare single-bank
+ * path. So these examples render score/lives digits as small `gt_rect`
+ * segments (a 7-seg-style 3x5 cell). Pure SDK draw-queue API, no assets.
+ *
+ * Each digit is a 3-wide x 5-tall grid of `px`-sized boxes; we draw one box per
+ * lit cell. Cheap for short HUD numbers (score, lives, level).
+ */
+#ifndef GT_HUD_H
+#define GT_HUD_H
+#include "gametank.h"
+#include "gt_draw.h"
+
+/* 3x5 bitmaps for 0-9, row-major, bit 2 = leftmost of the 3 columns. */
+static const unsigned char GT_DIG[10][5] = {
+  {0x7,0x5,0x5,0x5,0x7}, {0x2,0x6,0x2,0x2,0x7}, {0x7,0x1,0x7,0x4,0x7},
+  {0x7,0x1,0x3,0x1,0x7}, {0x5,0x5,0x7,0x1,0x1}, {0x7,0x4,0x7,0x1,0x7},
+  {0x7,0x4,0x7,0x5,0x7}, {0x7,0x1,0x2,0x2,0x2}, {0x7,0x5,0x7,0x5,0x7},
+  {0x7,0x5,0x7,0x1,0x7},
+};
+
+/* draw one digit (0-9) at (x,y), box size px, in color c. */
+static void hud_digit(unsigned char d, unsigned char x, unsigned char y,
+                      unsigned char px, unsigned char c) {
+  unsigned char r, col;
+  for (r = 0; r < 5; r++) {
+    unsigned char bits = GT_DIG[d % 10][r];
+    for (col = 0; col < 3; col++)
+      if (bits & (0x4 >> col))
+        gt_rect(x + col * px, y + r * px, px, px, c);
+  }
+}
+
+/* draw a number right-aligned with its UNITS digit's left edge at x. */
+static void hud_number(unsigned int n, unsigned char x, unsigned char y,
+                       unsigned char px, unsigned char c) {
+  unsigned char cx = x;
+  do {
+    hud_digit((unsigned char)(n % 10), cx, y, px, c);
+    n /= 10;
+    cx -= 4 * px;
+  } while (n);
+}
+
+/* a row of `n` small pips (lives/ammo) starting at x, gap-spaced. */
+static void hud_pips(unsigned char n, unsigned char x, unsigned char y,
+                     unsigned char size, unsigned char c) {
+  unsigned char i;
+  for (i = 0; i < n; i++)
+    gt_rect(x + i * (size + 2), y, size, size, c);
+}
+
+/* ── 3x5 box-letter font (A-Z + space) so titles can show real WORDS without the
+ * asset-pipeline font. Same row-major bit format as GT_DIG (bit2 = leftmost). */
+static const unsigned char GT_LET[27][5] = {
+  {0x2,0x5,0x7,0x5,0x5}, /*A*/ {0x6,0x5,0x6,0x5,0x6}, /*B*/ {0x3,0x4,0x4,0x4,0x3}, /*C*/
+  {0x6,0x5,0x5,0x5,0x6}, /*D*/ {0x7,0x4,0x6,0x4,0x7}, /*E*/ {0x7,0x4,0x6,0x4,0x4}, /*F*/
+  {0x3,0x4,0x5,0x5,0x3}, /*G*/ {0x5,0x5,0x7,0x5,0x5}, /*H*/ {0x7,0x2,0x2,0x2,0x7}, /*I*/
+  {0x1,0x1,0x1,0x5,0x2}, /*J*/ {0x5,0x6,0x4,0x6,0x5}, /*K*/ {0x4,0x4,0x4,0x4,0x7}, /*L*/
+  {0x5,0x7,0x7,0x5,0x5}, /*M*/ {0x5,0x7,0x7,0x7,0x5}, /*N*/ {0x2,0x5,0x5,0x5,0x2}, /*O*/
+  {0x6,0x5,0x6,0x4,0x4}, /*P*/ {0x2,0x5,0x5,0x6,0x3}, /*Q*/ {0x6,0x5,0x6,0x5,0x5}, /*R*/
+  {0x3,0x4,0x2,0x1,0x6}, /*S*/ {0x7,0x2,0x2,0x2,0x2}, /*T*/ {0x5,0x5,0x5,0x5,0x7}, /*U*/
+  {0x5,0x5,0x5,0x5,0x2}, /*V*/ {0x5,0x5,0x7,0x7,0x5}, /*W*/ {0x5,0x5,0x2,0x5,0x5}, /*X*/
+  {0x5,0x5,0x2,0x2,0x2}, /*Y*/ {0x7,0x1,0x2,0x4,0x7}, /*Z*/ {0x0,0x0,0x0,0x0,0x0}, /*space*/
+};
+
+/* draw one 3x5 char (A-Z, space) at (x,y), box size px, color c. */
+static void hud_char(char ch, unsigned char x, unsigned char y,
+                     unsigned char px, unsigned char c) {
+  unsigned char r, col, idx;
+  if (ch >= 'A' && ch <= 'Z') idx = ch - 'A';
+  else if (ch >= 'a' && ch <= 'z') idx = ch - 'a';
+  else idx = 26; /* space / unknown */
+  for (r = 0; r < 5; r++) {
+    unsigned char bits = GT_LET[idx][r];
+    for (col = 0; col < 3; col++)
+      if (bits & (0x4 >> col)) gt_rect(x + col * px, y + r * px, px, px, c);
+  }
+}
+
+/* draw a string (A-Z + spaces) starting at (x,y); 4*px per char advance. */
+static void hud_text(const char *s, unsigned char x, unsigned char y,
+                     unsigned char px, unsigned char c) {
+  while (*s) { hud_char(*s, x, y, px, c); x += 4 * px; s++; }
+}
+
+#endif /* GT_HUD_H */