romdevtools 0.44.0 → 0.70.0

package/CHANGELOG.md

@@ -4,6 +4,578 @@ 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.70.0 — 2026-06-26
+
+### Dreamcast is ship-ready: verified build → run → screenshot, with a renderable example
+
+The Dreamcast platform is now verified end-to-end and release-ready:
+
+- **build → run → screenshot proven + regression-tested.** A C homebrew compiles via
+  sh-elf-gcc, boots DIRECTLY on Flycast's reios HLE BIOS (no GD-ROM image, no firmware),
+  and renders on the real GPU through native-gles at 640×480 — confirmed by the new
+  `test/dreamcast-runside.test.js`.
+- **dc.h is now auto-bundled.** The PowerVR2 framebuffer helper (640×480 RGB565 bring-up:
+  FB_R_CTRL/SIZE/SOF1 + SPG) ships in the sh-c toolchain lib and is injected automatically,
+  so `#include "dc.h"` just works — a DC program is a single `main.c` with no glue. A
+  caller-supplied `dc.h` still overrides the bundled one.
+- **A renderable example** — `examples/dreamcast/hello` (DCHELLO): the canonical starter
+  that paints a test pattern through the GPU pipeline. Registered with createProject /
+  scaffold like the other platforms.
+
+(The 640×480 screenshot path was already correct — the GL FBO is sized to Flycast's
+upscale bound and the host crops the readback to the core's reported geometry; a raw
+readback without crop args was the only thing that looked oversized.)
+
+## 0.69.0 — 2026-06-26
+
+### PS1 renders on the REAL GPU via native-gles (Beetle PSX HW + OpenBIOS)
+
+The PS1 core is now **Beetle PSX HW** (mednafen) with its GLES3/WebGL2 hardware renderer,
+rendering the PS1 GPU on the real GPU through native-gles — the same path as glide64-N64
+and Flycast-DC. It ships with **OpenBIOS embedded** (PCSX-Redux, MIT-licensed, region-free),
+so there's NO copyrighted Sony firmware to ship and no BIOS file to supply. (Verified:
+mod.GL exposed, SET_HW_RENDER fires, hwActive=true, the OpenBIOS 3D-cube boot animation
+renders in shaded perspective through native-gles.)
+
+- New package romdev-core-beetle-psx-hw (replaces romdev-core-pcsx-rearmed as the PS1
+  core); build-beetle-psx-hw.sh reuses the N64 GL recipe (all-.o link, -lGL +
+  GL_ENABLE_GET_PROC_ADDRESS + GL in EXPORTED_RUNTIME_METHODS, the libretro-common EXTRAS).
+- Registry: ps1 → beetle_psx_hw, hwRender:true. Manifest: renderingKind 3d, run+screenshot
+  +disasm+decompile+build true; cpuState/audioDebug now false (beetle lacks the romdev
+  MIPS/SPU debug exports the old pcsx_rearmed-software build had — a future core patch;
+  pcsx had no WebGL2 GPU path).
+
+NOTE (both MIPS platforms): the GL cores render RDP/GPU display lists, NOT raw CPU-written
+framebuffers — so the romdev software-3D example libs (which rasterize into a framebuffer)
+render black on them; REAL games with GPU geometry render correctly. SDK-based examples
+(libdragon rdpq / PSn00bSDK GTE) are the renderable path. Suite 1059/1059.
+
+## 0.68.0 — 2026-06-26
+
+### N64 renders on the REAL GPU via native-gles (glide64), not software
+
+parallel_n64 now renders the RDP through **glide64 → GLES2/WebGL2 → native-gles** (the
+real GPU, headless EGL pbuffer), replacing the angrylion software-RDP build. SET_HW_RENDER
+fires, the host's LibretroGL drives native-gles, and frames read back via glReadPixels —
+the same GPU path as Flycast/Dreamcast. (Verified: hwActive=true, the GL context engages
+from boot.)
+
+The build + host fixes that made it work (every one was a real wall):
+- **Link all .o directly**, not via a .bc/.a archive — the archive route drops the
+  GLSM/context_reset/glide64 objects (no externally-referenced symbol), so the core never
+  calls SET_HW_RENDER. (build-parallel-n64.sh)
+- **`-lGL` + `GL_ENABLE_GET_PROC_ADDRESS=1` + `"GL"` in EXPORTED_RUNTIME_METHODS** — these
+  make Emscripten emit `Module["GL"]=GL`, so the returned module actually exposes the GL
+  context object the host needs. Without them, `mod.GL` is undefined and HW render never
+  initializes.
+- **coreLoader: don't set `noInitialRun`/`wasmBinary` for GL (canvas) cores** — both
+  suppress the Emscripten GL runtime init; use `locateFile` so the .wasm loads the normal way.
+- **Pre-seed PLATFORM_CORE_OPTIONS before `_retro_init`** (loadCore now infers the platform
+  from the core filename): the core picks its renderer (glide64 vs angrylion) from
+  `parallel-n64-gfxplugin` during retro_init, so the override must be set before then.
+- Registry: n64 is now `hwRender:true` (glide64 GL).
+
+## 0.67.0 — 2026-06-26
+
+### Dreamcast examples + sh-c -O level fix
+
+Four DC example programs (rom-games/dreamcast/): dchello (test card), bounce (animation),
+starfield (shmup background), grid (puzzle/board) — all build via the WASM toolchain and
+render distinct content through Flycast, exercising the dc.h helper (no-KOS PowerVR2
+framebuffer + 2D primitives).
+
+sh-c driver: a user-supplied `-O<level>` now wins over the default `-O2` (gcc honors the
+LAST -O, so a default appended after the user's would clobber it — only add -O2 if absent).
+This matters because the WASM cc1 hangs at -O2 on some sources (the interprocedural-
+optimization phase; native sh-elf-gcc compiles them in <1s), and -O1 is the workaround.
+Suite 1059/1059.
+
+## 0.66.0 — 2026-06-26
+
+### Dreamcast: build() works — full WASM toolchain + packaging
+
+`build({platform:"dreamcast"})` now compiles SH-4 C to a bootable ELF entirely in WASM,
+and the result boots + renders through Flycast — the complete zero-install pipeline
+(build → run → screenshot), verified end-to-end via the public `buildForPlatform`.
+
+- **sh-elf-gcc WASM toolchain** (cc1 + as + ld + objcopy + objdump): gcc 14.2.0 +
+  binutils 2.42 + newlib 4.4.0 for sh-elf (little-endian SH-4, m4-single-only). The cc1
+  build needed CC_FOR_BUILD forced native (emconfigure makes $(CC)=emcc, which would
+  build the gen tools as WASM) + the host-side libcpp/libiberty configured first.
+- **sh-c build driver** + lib (dc-crt0.s zeroes .bss + calls main; dc.ld links at
+  0x8c010000; newlib libc/libm/libgcc). The ELF IS the deliverable — reios boots it.
+- **Packages:** romdev-core-flycast (the DC core) + romdev-toolchain-sh-gcc (the WASM
+  compiler), both added as romdevtools deps; the registry resolves the DC core from the
+  package. Manifest `dreamcast.build` is now true.
+
+Dreamcast core parity reached: disasm + decompile + build + run + screenshot. Suite
+1059/1059.
+
+## 0.65.0 — 2026-06-26
+
+### Dreamcast: homebrew renders correct graphics + HW-frame crop-to-native
+
+A minimal DC homebrew (no KallistiOS — a dependency-free `dc.h` helper that programs the
+PowerVR2 FB_R_CTRL/FB_R_SIZE/FB_R_SOF1 + SPG for a 640x480 RGB565 framebuffer) builds with
+the native sh-elf toolchain, boots via reios HLE, runs, and renders a test pattern that the
+host captures **pixel-exact** (verified: dark-blue background + equal red/green/blue bars +
+white frame, the program's exact colors). This closes the DC render-fidelity loop.
+
+Host change (helps any HW-render core): the video_refresh callback now records the core's
+reported active resolution, and the GL readback crops the FBO to it — so a 640x480 DC frame
+no longer comes back as the full 853x853 GL viewport with a dead border. `readbackFrame`
+takes optional (cropW, cropH); `_afterRun` passes the core's w/h. Suite 1059/1059.
+
+## 0.64.0 — 2026-06-26
+
+### Dreamcast: present-path verified — screenshot works
+
+Flycast renders to the GL FBO and the host reads it back: a framebuffer-writing homebrew
+program shows ~727k captured pixels through the host's normal frame path (hwFramePending →
+readbackFrame). Manifest `dreamcast.screenshot` is now true. With the CPU executing
+(0.63.0), the direct-framebuffer present path lights up.
+
+Added `flycast_emulate_framebuffer: enabled` to the host's DC options — it scans the DC
+framebuffer out on every VBlank (the 2D path, no PowerVR2 tile list), so simple homebrew
+that writes RGB565 to VRAM presents reliably without authoring a full TA list. (Full
+TA/3D fidelity + correct framebuffer addressing come with the KOS helper lib; the pipeline
+itself — boot → run → render → host capture — is proven end-to-end.) Suite 1059/1059.
+
+## 0.63.0 — 2026-06-26
+
+### Dreamcast: HOMEBREW EXECUTES — run + memory introspection live
+
+Custom Flycast core patches make the SH-4 actually execute guest code. A homebrew .elf
+boots via reios HLE, the SH-4 runs it, and the guest's RAM writes are visible through the
+host (verified: a 0xDC0DC0DC marker the test program writes appears in DC RAM). Manifest
+`dreamcast.run` is now true.
+
+Root cause (3 stacked bugs): (1) worker-thread aborts — fixed by single-thread +
+`--wrap pthread_create` no-op (0.62.0); (2) HLE BIOS off — only the reios path loads a raw
+.elf, and the option is latched at retro_init, so default `UseReios=true` in source for
+emscripten; (3) THE BIG ONE — `ThreadedRendering` defaulted ON, which runs the CPU on a
+`std::async` worker that our pthread no-op kills → the SH-4 never steps (PC stuck at the
+reset vector, reios_boot never fires, RAM stays zero). Fixed by unconditionally
+`config::ThreadedRendering.override(false)` for emscripten in update_variables.
+
+`screenshot` stays false until the PowerVR2 present-path is verified with a TA-driving
+program (the KOS helper lib — next phase). All patches reproducible in build-flycast.sh.
+Suite 1059/1059.
+
+## 0.62.0 — 2026-06-26
+
+### Dreamcast run-side BREAKTHROUGH: Flycast boots + runs DC ELFs
+
+The threading wall is solved. Flycast (the full DC emulator) now **boots a homebrew
+.elf via reios HLE and runs frames** through the romdev host — `retro_init` /
+`retro_load_game` / `retro_run` all succeed, av_info reports 640×480, and video_refresh
+fires every frame. No abort, no `unwind`.
+
+The fix (after trying PROXY_TO_PTHREAD + ASYNCIFY, which deadlocks in Node on the
+GL↔proxy-thread dependency): build single-threaded and **`--wrap` pthread_create to a
+no-op** (`scripts/patches/romdev-snippets/flycast-pthread-noop.c`). pthread_create
+returns success but spawns nothing; join/detach are no-ops. So flycast's worker threads
+(achievements/http/network/audio-async) never run, `std::thread`'s ctor doesn't abort
+(no "thread constructor failed"), and — crucially — the main thread never blocks on a
+worker, so there's no emscripten `unwind`. Emulation runs synchronously on retro_run
+(ThreadedRendering defaulted false). This is far cleaner than stubbing thread sites
+one-by-one (there were 4+ wrapper classes plus raw std::thread/std::async).
+
+Also: the GL `get_proc_address` bridge fix (0.59.0) is what got context_reset past the
+signature mismatch; the 512MB-mmap fallback (posix_vmem) got init past the trap.
+
+NEXT: a DC program that actually renders via PowerVR2 (the KOS helper lib) to verify the
+present path end-to-end, then flip run/screenshot true. Captured in build-flycast.sh.
+Suite green.
+
+## 0.60.0 — 2026-06-26
+
+### Dreamcast: SuperH4 SLEIGH metadata shipped + Flycast threading progress
+
+- **SuperH4 SLEIGH metadata committed** (`.ldefs`/`.pspec`/`.cspec`) — these ship
+  alongside the gitignored `.sla` (like every other CPU); without them the decompiler
+  couldn't load the SuperH4 spec at runtime. (0.57.0 shipped the wiring but missed the
+  metadata files. Now complete.)
+- Flycast run-side threading: the single-threaded WASM build needs worker-thread
+  creation stubbed (emscripten can't spawn them without -pthread; with -pthread the
+  main thread can't block → unwind). Captured the patches in `build-flycast.sh`
+  (`cThread::Start` / `VPeriodicThread::start` no-op, `ThreadedRendering` defaults
+  false on emscripten) + the `flycast_threaded_rendering: disabled` host option.
+
+KNOWN-OPEN: Flycast's load still aborts on a not-yet-located worker thread (no-pthread)
+or unwinds (pthread). The thread/main-loop model integration is the remaining run-side
+fight — see N64_PS1_LESSONS_FOR_DREAMCAST.md. DC analysis (disasm+decompile) is fully
+shipped + tested. Suite 1059/1059.
+
+## 0.59.0 — 2026-06-26
+
+### Dreamcast run-side: Flycast loads ELFs + GL bridge fix (general)
+
+Flycast WASM now boots a homebrew `.elf` (reios HLE — no BIOS/disc) and requests GL:
+- threads: `-pthread -sPTHREAD_POOL_SIZE=8` (Flycast spawns std::threads; without
+  pthreads the ctor aborts). The pthread build bakes the module filename into the
+  worker bootstrap, so it MUST link with the final `flycast_libretro.js` name.
+- **GL proc-address (general bridge fix in LibretroGL.js):** emscripten-WebGL cores
+  (Flycast) resolve GL via libretro `get_proc_address`. The bridge previously returned
+  a no-op 0-arg stub → the core called multi-arg GL fns through it → "null function or
+  function signature mismatch" in context_reset. Now the bridge returns the real
+  `emscripten_GetProcAddress` table pointer (built with `-sGL_ENABLE_GET_PROC_ADDRESS=1
+  -lGL`); the native-gles stub path stays as the glide64-N64 fallback. This fix helps
+  ANY future emscripten-WebGL core.
+- `ROMDEV_CORE_LOG=1` env gates core stdout/stderr (was always suppressed) — found the
+  thread + mmap aborts with it.
+
+KNOWN-OPEN: `retro_run` throws emscripten's `unwind` (Flycast yields via
+emscripten_set_main_loop / Asyncify, incompatible with the host's synchronous
+frame-step). That main-loop integration is the next run-side step. Suite 1059/1059.
+
+## 0.58.0 — 2026-06-26
+
+### Dreamcast run-side: Flycast WASM core builds + inits; sh-elf toolchain built
+
+The two heaviest Dreamcast pieces, both landed (build infrastructure; host present-path
+integration is the next step):
+
+- **sh-elf-gcc toolchain** (SH-4): binutils 2.42 + gcc 14.2.0 + newlib 4.4.0, built
+  for `sh-elf` (m4-single-only, little-endian — the DC ABI). Compiles SH-4 C end to
+  end. `scripts/build-sh-toolchain.sh` (adapted from the mips one; SH-4 is single-
+  endian so no be/el split).
+- **Flycast → WASM**: the full Dreamcast emulator (785 C++ files, GLES3/WebGL2)
+  compiled to a 5.9MB WASM module that instantiates with all libretro entry points
+  and `retro_init` succeeds. Flycast has no upstream emscripten build, so
+  `scripts/build-flycast.sh` applies the romdev WASM patches discovered here:
+  - a `CPU_GENERIC` host (no JIT) → the SH-4/ARM/DSP interpreters (`TARGET_NO_REC`);
+    CMake `DetectArchitecture` + `build.h` + the FPU-control / JIT-segfault-recovery
+    arch branches all get a generic no-op path.
+  - asio single-threaded (`ASIO_DISABLE_THREADS`) so it doesn't need POSIX
+    signal_blocker/tss_ptr (emscripten without -pthread isn't detected as POSIX).
+  - Vulkan OFF (WASM uses WebGL); networking/UPnP stubbed.
+  - **the key boot fix:** emscripten can't `mmap` a 512MB contiguous reservation (it
+    traps), so `posix_vmem::init` declines fast-vmem on emscripten → Flycast's
+    malloc-based memory fallback engages and `retro_init` succeeds.
+- `dreamcast` registry entry (Flycast, hwRender — PowerVR2 is GPU-first, no software
+  framebuffer; HLE reios BIOS, no firmware to ship).
+
+Suite 1059/1059. Next: the GL present-path (load_game + run + frame through the host's
+WebGL2 bridge), then the helper lib + 5 example games + packaging.
+
+## 0.57.0 — 2026-06-26
+
+### Dreamcast (SH-4) analysis slice — disasm + decompile
+
+First slice of Dreamcast support: the SH-4 (SuperH) reverse-engineering path, on the
+same pattern as the PS1/N64 analysis slice.
+
+- rizin's `sh` plugin (already in rizin.wasm) wired for disasm/cfg/xrefs/functions
+  (arch=sh, little-endian).
+- Ghidra's **SuperH4** SLEIGH spec compiled (`SuperH4_le.sla`) + shipped in
+  romdev-analysis-decompiler → `decompile` produces real C (langid
+  `SuperH4:LE:32:default`). Verified: SH-4 bytes → disasm + decompiled C.
+- analyze.js handles DC binaries: strips an ELF to its first PT_LOAD segment (vaddr =
+  loadBase 0x8c010000) or treats a raw image as flat; left-pads so flat offset ==
+  the VA's low bits + rebases the high bits (same trick PS1 needed for absolute-
+  addressed calls — SH-4's PC-relative + absolute addressing needs it too).
+- `dreamcast` added to the capability manifest as the new `sh` tier (analysis-first;
+  run/build/etc. land in later phases). The 3D (PowerVR2) renderer's tile/sprite
+  inspectors are N/A by hardware with a stated reason. Excluded from the all-14
+  contract via the generalized NEXTGEN_TIER (mips + sh).
+
+Suite 1059/1059. Run-side (Flycast WASM), build (sh-elf-gcc), the helper lib, and the
+5 example games are the next phases.
+
+## 0.56.1 — 2026-06-26
+
+### ascii screenshot: legible default grid + lighter default color (0.44.0 feedback #1)
+
+`frame({op:'screenshot', format:'ascii'})` defaulted to a `fb/16` grid (16×14 for a
+256×224 NES frame — too coarse to read any game state) AND truecolor (`38;2;r;g;b`
+per cell, ~7.9KB of escapes). So the "cheap text screenshot" was both expensive and
+useless for an "are we in gameplay?" check.
+
+- default grid is now `fb/8` (one cell per 8×8 tile → 32×28 for NES, legible).
+- default `colors` is now `'256'` (indexed) instead of `'true'` — near-identical read,
+  far fewer escape bytes. Net for the NES case: 4× more cells AND ~55% smaller
+  (7876B → 3551B).
+- when a caller forces a grid too coarse to show state, the result carries a `note`
+  pointing at `memory({op:'read'})` as the cheaper exact path for a pass/fail check.
+
+## 0.56.0 — 2026-06-26
+
+### N64 + PS1 are now SHIPPABLE: core packages + toolchain wired for publish
+
+The functionality was done, but the artifacts weren't distributable — the cores lived
+only in the gitignored dev-staging dir, with no npm package to publish. Fixed:
+
+- **New `romdev-core-pcsx-rearmed`** (PS1) and **`romdev-core-parallel-n64`** (N64,
+  headless-angrylion software) packages, mirroring the 14's structure (package.json
+  + index.js + README + gitignored `wasm/` shipped via the `files` allowlist +
+  verify-wasm prepublish guard). These are CUSTOM romdev builds (the romdev debug
+  exports + IPL3) — documented in each README + built by scripts/build-*.sh.
+- **`romdev-toolchain-mips-gcc`** moved to required `dependencies` (build needs it);
+  the two cores added to `dependencies` (always installed, like the 14). lockfile
+  regenerated — `npm ci` passes.
+- publish-all.mjs now discovers all 3 (26 packages total).
+
+### A real shipping bug the npm-pack smoke test caught
+
+The cores' Emscripten glue had a DEV SCRATCH wasm name baked in (`pcsx_vram.wasm`,
+`pn64_sw.wasm` from `-o $SCRATCH/...`) instead of the published `*_libretro.wasm`.
+The host always passes `wasmBinary` so it worked in dev — but any consumer loading
+the factory directly got ENOENT. Re-linked both glues with the correct `-o` name (the
+build scripts already used it; only my hand-links were wrong). A clean-install smoke
+test (npm pack → install into a bare dir → resolve + instantiate + check exports) +
+a packaging contract test now pin this so it can't silently regress.
+
+Verified: clean-install smoke test passes, full build→load-from-package→run→render
+pipeline works for both, npm ci + lint + 1054/1054 tests green. Ready for `npm publish`.
+
+## 0.55.0 — 2026-06-26
+
+### System manifests now call out the features a platform CAN'T have (and why)
+
+A bare `inspectSprites: false` in the capability manifest is ambiguous — an agent
+can't tell "N/A by hardware, permanent" from "a decoder we haven't built." For the
+14 tile-based systems this never bit (they support those ops); for the framebuffer
+(PS1) / 3D (N64) systems, FOUR ops are false with no stated reason.
+
+- New `naReason(platform, op)` in the capability manifest returns a HARDWARE-grounded
+  explanation, keyed on `renderingKind`: a framebuffer/3D renderer has no tile/
+  sprite-attribute/nametable/palette tables for the tile-era inspectors to read —
+  those ops are *meaningless on the hardware*, not merely absent. (PS1 `cart` →
+  "disc-based, no cartridge ROM".)
+- `platform({op:'capabilities', platform})` now includes a `naReasons` map alongside
+  `ops`, so the manifest itself states what each platform can't do + why.
+- The `unsupported()` signal from inspectSprites/inspectPalette/inspectBackground/
+  renderingContext now carries that hardware reason instead of a generic "no decoder
+  for this platform" — an agent gets "this is a 3D renderer, there are no sprite
+  tables" and won't retry or request a decoder that can't exist.
+- Conformance test pins it: every false introspection op on ps1/n64 must carry a
+  hardware-grounded N/A reason. Suite 1054/1054.
+
+## 0.54.0 — 2026-06-26
+
+### Audit: two real N64/PS1 parity gaps found + fixed
+
+A full per-tool audit (all 32 tools, live-probed on both platforms) surfaced two
+genuine gaps where the platform was CAPABLE but the tool didn't deliver:
+
+1. **PS1 reverse-engineering returned bogus addresses.** `disasm`/`cfg`/`xrefs`/
+   `functions`/`decompile` on a PS1 PS-EXE found a single fake `fcn.00000000` at
+   file offset 0 (not the real 0x80010000+ VA), and `decompile` then threw "address
+   maps outside the image." Root cause: rizin ignores `-B` on a raw buffer, so the
+   stripped .text was analyzed flat from 0, and PS1's ABSOLUTE jal targets dangled →
+   no cross-function discovery. Fix: left-pad the .text so flat offset == the VA's
+   low 20 bits (jal-following now works) and add the high bits back as a rebase, so
+   every reported address is a real VA that round-trips. PS1 now finds all functions
+   (16 vs 1) at correct VAs, CFG/xrefs/decompile all resolve. (N64 was already fine.)
+
+2. **PS1 `video_ram` was claimed but empty.** The manifest lists `video_ram` for
+   every platform, but pcsx_rearmed never exposed the GPU VRAM. Added a
+   `romdev_vram_get` export (1024×512×16bpp) wired into `memory({region:'video_ram'})`
+   — PS1 GPU VRAM is now readable (verified: rendered pixels show up).
+
+Everything else in the audit was already at parity or genuinely N/A-by-hardware
+(the tile/sprite/nametable/palette inspectors need tables a framebuffer/3D renderer
+doesn't have; `cart` is for cartridge ROMs). save/loadState, runUntil, frame-verify,
+romPatch, and the agnostic art/snippet tools all work on both. Suite 1053/1053.
+
+## 0.53.0 — 2026-06-26
+
+### N64 + PS1 reach EXAMPLE parity: 5 full genre games each
+
+Both new platforms now ship the same caliber of bundled, playable examples as the
+other 14 (parity = "5 decent full games"), registered in project.js and forkable +
+buildable through the normal createProject/build tool flow.
+
+**PS1** (4 × 3D + 1 × 2D, on a software 3D engine + the GPU): shmup STARFALL,
+racing POLE BENDER (a real receding 3D road), platformer BLOCK HOP, sports
+SLAM COURT (3D pong/air-hockey), puzzle DROP GRID (2D — the right idiom for a grid).
+
+**N64** (all 5 × 3D — the N64 was a 3D-first machine, so even the puzzle is a 3D
+well of cubes): STARFALL 64 / POLE BENDER 64 / BLOCK HOP 64 / SLAM COURT 64 /
+DROP GRID 64, on the same software-3D lib with a framebuffer backend the
+headless-angrylion core scans out.
+
+Every example builds + boots + renders, verified on the actual cores (frames
+inspected). The N64 path required the three earlier breakthroughs (self-booting
+.z64 via a clean IPL3, a headless-angrylion GL-free core, and the VI-scanout
+software rasterizer). Suite 1052/1052.
+
+**This completes N64 + PS1 parity** — every tool the other 14 have works, and both
+ship 5 full idiomatic examples.
+
+## 0.51.0 — 2026-06-26
+
+### N64 audioDebug — FULL parity (zero functional gaps)
+
+- **`getAudioState({chip:'ai'})`** decodes the N64 Audio Interface: sample rate
+  (from DACRATE + the VI clock), whether audio is playing (a buffer is DMA-queued),
+  the DMA source address. (N64 audio is RSP-mixed, so the AI is the OUTPUT state, not
+  per-voice — that lives in game-specific RSP audio lists in RDRAM.) Verified: a real
+  ROM reports `playing:true, sampleRate:32006`. From a `romdev_ai_get` export added
+  to parallel_n64. n64 `audioChips:['ai']`, `audioDebug:true`.
+
+**This closes the last functional gap.** A programmatic audit confirms N64/PS1 now
+match the canonical 14 on every applicable op — build, run, screenshot, memory,
+cpuState, audioDebug, disasm, decompile, cheats, breakpoint, watch. The only manifest
+differences are N/A BY HARDWARE: the tile/sprite/nametable/palette inspectors
+(framebuffer/3D renderers have no such tables) and `cart` (disc-based). Suite 1052/1052.
+
+## 0.50.0 — 2026-06-26
+
+### PS1 SPU audioDebug
+
+- **`getAudioState({chip:'spu'})`** decodes the PS1 SPU's 24 ADPCM voices (per-voice
+  volume L/R, pitch→Hz, ADSR, key-on/off + main volume + control), from a
+  `romdev_spu_get` export added to pcsx_rearmed (copies the SPU regArea). Verified:
+  a toolchain-built program's SPU register writes read back correctly.
+- ps1 `audioDebug:true` in the manifest.
+
+**Parity status (N64/PS1 vs the canonical 14):** at parity on build, run, screenshot,
+memory, cpuState, disasm, decompile, cheats, breakpoint, watch (+ PS1 audioDebug).
+Genuinely N/A by hardware: the tile/sprite/nametable/palette inspectors (framebuffer/3D
+renderers have no such tables) and `cart` (disc-based). **Remaining real TODO:** N64
+audioDebug (the RSP/AI audio path — a deeper decode than the PS1 SPU register block).
+
+## 0.49.0 — 2026-06-26
+
+### N64 + PS1 live-debug — breakpoint + watch now work
+
+The remaining big parity gap: the live-debugging RE tools. parallel_n64 (R4300) and
+pcsx_rearmed (R3000) are rebuilt with romdev's CPU instrumentation, so:
+
+- **`breakpoint({on:'pc'|'write'|'read'})`** + **`watch({on:'range'|'mem'})`** work on
+  both MIPS platforms — verified live: a C program (built by the romdev toolchain)
+  writing to a known address is caught by a write watchpoint with the writing PC, and
+  a range watch captures the write stream during emulation.
+- A `romdev_debug.c` instrumentation unit (per core) hooks the memory write/read paths
+  (write/read watch + range watch + coverage) and the interpreter step (PC break +
+  single-step). Exports the full `romdev_watchpoint`/`readwatch`/`pcbreak`/`range`/`cov`/
+  `regsnap`/`watchdog` set the host already expects — so the host needed ZERO changes
+  (its debug methods were already generic).
+- Reproducible via the updated build-pcsx-rearmed.sh / build-parallel-n64.sh
+  (patch the source + hooks + exports).
+
+**Remaining honest gap:** `audioDebug` (PS1 SPU / N64 audio chip decoders) is still
+TODO. The tile/sprite/nametable inspectors stay N/A by hardware (framebuffer/3D
+renderers have no such tables). Everything else is at parity. Suite 1050/1050.
+
+## 0.48.0 — 2026-06-25
+
+### N64 + PS1 `build` op — full feature parity
+
+The last missing op. N64 and PS1 now **build** C from source, completing parity
+with the 14 (every op: build, run, screenshot, memory, disasm, decompile, cheats,
+cpuState).
+
+- **A from-scratch `mips-elf` GCC toolchain compiled to WASM** — binutils 2.42 +
+  gcc 14.2.0 + newlib 4.4.0, the same two-stage pipeline as the Genesis m68k
+  toolchain. STAGE 1 builds it natively; STAGE 2 re-compiles cc1/as/ld/objcopy/
+  objdump to WASM. One toolchain serves both endiannesses (cc1 `-mel`/`-meb`,
+  as/ld `-EL`/`-EB`).
+- **`buildSource({platform:'ps1'|'n64', language:'c'})`** — cc1 → as → ld → objcopy,
+  links a minimal crt0 + libc/libm/libgcc. PS1 wraps the image in a PS-EXE the HLE
+  BIOS loads; N64 emits a big-endian flat image. **Verified end-to-end:** a C program
+  compiled by the toolchain boots and renders on the PS1 core (GPU fill executed).
+- Four GCC-15/emscripten build incompatibilities fixed along the way (all in the
+  build scripts): binutils `static_assert`-as-identifier (`-std=gnu11`), newlib
+  libgloss pre-C23 idioms (permissive target CFLAGS), libiberty `psignal` conflict
+  (source patch, both gcc + binutils copies), and the `all-gcc`/`all` aux-tool
+  targets pulling in ftw/gprofng (build the specific `cc1`/`as`/`ld` targets).
+- New `romdev-toolchain-mips-gcc` package (the WASM tools); pinned + reproducible
+  via `build-mips-toolchain.sh` + `build-mips-wasm-tools.sh`.
+
+**Caveats:** the bare build path has no SDK yet — PS1 is "drive the GPU/SPU
+registers yourself" (PSn00bSDK forthcoming); N64 compiles+links but a self-booting
+cart needs IPL3 + a libdragon header (libdragon forthcoming). Both are logic/RE-
+complete and the foundation for the SDKs. The framebuffer/3D renderers have no
+tile/sprite inspectors by nature.
+
+## 0.47.0 — 2026-06-25
+
+### N64 + PS1 reach feature parity (cheats + cpuState + decompile)
+
+The MIPS tier now matches the 14 on everything except `build`:
+
+- **MIPS decompile** — `disasm({platform:'n64'|'ps1', target:'decompile'})` produces
+  real Ghidra C pseudocode. **No Python**: the stock Ghidra MIPS SLEIGH spec is
+  compiled to `.sla` (MIPS:BE:32 for N64, MIPS:LE:32 for PS1) by the same
+  `sleigh_opt` that builds the other 8 CPU tables. (m2c/Pyodide was rejected — it
+  would drag a CPython runtime into the tool.)
+- **cpuState** — `cpu({op:'read'})` decodes the live R4300 (N64) / R3000 (PS1)
+  register file: 32 GPRs by o32 ABI name + lo/hi + PC. Backed by a tiny
+  `romdev_mips_regs_get` appended to each core's `libretro.c` (the new
+  `build-parallel-n64.sh` / `build-pcsx-rearmed.sh` recipes).
+- **cheats** — `_retro_cheat_set`/`_retro_cheat_reset` are now exported from the
+  rebuilt cores (they were in the upstream C, just unexported).
+- The cores are reproducible: pinned in `versions.json`, built by the new recipes
+  (clone → append the regsnap → emcc with the cheat+regsnap exports; the regsnap is
+  `EMSCRIPTEN_KEEPALIVE` so LTO doesn't strip it).
+
+**Parity scorecard** — N64 & PS1 now have: run, screenshot, memory r/w, disasm
+(cfg/xrefs/functions), decompile, cheats, cpuState. The one remaining op is
+**build** (a MIPS GCC→WASM toolchain — PSn00bSDK/libdragon — the largest separate
+piece). The framebuffer/3D renderers have no tile/sprite/nametable inspectors by
+nature.
+
+## 0.46.0 — 2026-06-25
+
+### N64 + PS1 run-side: boot, run, render (the MIPS tier goes live)
+
+Past analysis-only — N64 and PS1 now **boot, run, and present real frames** through
+the host. The 32-bit MIPS tier is a new partial tier (`tier:"mips"`), distinct from
+the canonical 14.
+
+- **N64** (ParaLLEl-N64, HW 3D render) — `run` + `frame({op:'screenshot'})` produce
+  real 3D frames headlessly via a GL framebuffer readback. Rendering goes through a
+  ported GL bridge (`LibretroGL`/`LibretroGLBridge`) backed by `native-gles` +
+  `webgl-node`, which are **optionalDependencies**: lazy-loaded only when an N64/PS1
+  core boots, so the 14 software platforms and headless installs without the GPU
+  module are completely unaffected (clear install hint if absent).
+- **PS1** (PCSX-ReARMed, software + **built-in HLE BIOS**) — `run` + screenshot with
+  zero firmware to ship, no GL dependency. Loads PS-EXE (and disc images).
+- **Memory** works for both: `readMemory`/`writeMemory` on `system_ram` (N64 = 8MB
+  RDRAM, PS1 = 2MB main RAM) — poke values directly.
+- **Static RE** (from 0.45.0) still works: `disasm({platform:'n64'|'ps1',
+  target:'rom'|'functions'|'cfg'|'xrefs'})`.
+- N64 `.v64`/`.n64` byte orders auto-normalize to `.z64`; PS-EXE headers are stripped.
+
+Three GL-binding bugs fixed to get frames on screen: the Emscripten `getContext`
+shim's `instanceof WebGLRenderingContext` check (needs WebGL1 to be a distinct
+class), the signed-vs-unsigned `RETRO_HW_FRAME_BUFFER_VALID` compare, and the
+all-transparent FBO alpha (forced opaque in a new RGBA decode path).
+
+**Still pending** for full parity (honestly off in the manifest): `build` (needs a
+MIPS toolchain — PSn00bSDK/libdragon), `decompile` (needs a MIPS SLEIGH spec in the
+decompiler — slaspec sources exist, a decompiler-package rebuild), `getCPUState` +
+`cheats` (need a core rebuild exposing those exports). The framebuffer/3D renderers
+have no tile/sprite/nametable inspectors by nature.
+
+## 0.45.0 — 2026-06-25
+
+### PS1 + N64 analysis-first (the 32-bit MIPS tier)
+
+The first step past the GBA-era line: static RE for PlayStation (R3000) and
+Nintendo 64 (R4300), via the MIPS plugin already in the shipped `rizin.wasm` — no
+new core, no toolchain, no GPU bridge in this slice.
+
+- **`disasm({platform:'ps1'|'n64', target:'functions'|'cfg'|'xrefs'|'rom'})`** —
+  works on real ROMs. Verified: a libdragon N64 homebrew (`FlappyBird.z64`)
+  recovers 251 functions with control-flow graphs and cross-references. The raw
+  N64 ROM has no entry `aaa` recognizes, so MIPS analysis is seeded at the
+  post-IPL3 code start (`af` + `aac`) — `aaa` finds 0, the seed finds the tree.
+- **Endianness is wired right:** PS1 is little-endian, N64 is big-endian (same
+  `mips` arch). N64 `.v64`/`.n64` dumps are auto-normalized to `.z64` byte order;
+  PS1 PS-EXE headers are stripped to the load address.
+- **Capability manifest:** `ps1` (framebuffer) / `n64` (3d) are an analysis-only
+  tier — `disasm` true; run-side ops (build/run/screenshot/the tile/sprite
+  inspectors) and `decompile` false. The tile/nametable inspectors are meaningless
+  on a framebuffer/3D renderer, so an agent gets the clean `unsupported()` signal.
+- **`decompile` (C pseudocode) is NOT available yet** for MIPS — the rz-ghidra
+  decompiler ships no MIPS SLEIGH spec (adding `MIPS.sla` is a later
+  `romdev-analysis-decompiler` rebuild). It returns a clear steer to the working
+  disasm targets, not a cryptic failure.
+
 ## 0.44.0 — 2026-06-25
 
 ### v0.41.0 feedback (part 2) — RE-session ergonomics

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, and more) 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 — 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,7 +9,7 @@ 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.
+- **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.
 - **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.
 - **Convert assets** — PNG → platform tiles/tilemaps, quantize-to-palette, audio importers (BRR for SNES, XGM2 PCM for Genesis).
@@ -20,7 +20,7 @@ Point any coding agent at it three ways:
 - **Agent Skill** — `GET /skills/romdev/SKILL.md` (the [Agent Skills](https://agentskills.io) standard; save it to your skills dir as `skills/romdev/SKILL.md`; ~100 tokens until invoked).
 - **MCP** — it's also a [Model Context Protocol](https://modelcontextprotocol.io/) server at `/mcp` for clients that want it.
 
-This package contains all the JavaScript — the tool surface, the WASM emulator host, the per-platform example games, runtime/library source, and debug helpers — but **no emulator or compiler WASM itself.** Those ship in the `romdev-*` binary packages it depends on, loaded on demand the first time you build or run a given platform.
+This package contains all the JavaScript — the tool surface, the WASM emulator host, the per-platform example games, runtime/library source, and debug helpers — but **no emulator or compiler WASM itself.** Those ship in the `romdev-*` binary packages it depends on; each platform's core/toolchain WASM is resolved (`import.meta.resolve`) and instantiated only the first time you build or run that platform, so memory stays proportional to what you actually use.
 
 > For the full project — what romdev is, the supported-platform matrix, how the pieces fit together, and how to develop on it — see the [repository README](https://github.com/monteslu/romdev#readme).
 
@@ -34,11 +34,13 @@ This package contains all the JavaScript — the tool surface, the WASM emulator
 
 ## Dependencies
 
-`romdevtools` hard-depends (exact-pinned) on the binary/data packages it needs, so a single install gets a matched, tested set:
+`romdevtools` depends on the binary/data packages it needs (exact-pinned), so a single install gets a matched, tested set:
 
-- 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}`
+- 2D cores: `romdev-core-{fceumm,gambatte,gpgx,vice,handy,prosystem,geargrafx,bluemsx}`
+- 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.
 - 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.
 

package/examples/dreamcast/hello/main.c

@@ -0,0 +1,24 @@
+/* dchello — a minimal Dreamcast homebrew that draws a recognizable test pattern,
+ * proving the romdev DC pipeline renders program-controlled graphics end-to-end. */
+#include "dc.h"
+
+void main(void) {
+    dc_video_init();
+
+    /* Clear to a dark blue background. */
+    dc_clear(dc_rgb(16, 24, 64));
+
+    /* Three solid bars (red, green, blue) — distinct, easy to verify in a screenshot. */
+    dc_rect(64, 80, 160, 320, dc_rgb(220, 40, 40));    /* red   */
+    dc_rect(240, 80, 160, 320, dc_rgb(40, 200, 60));   /* green */
+    dc_rect(416, 80, 160, 320, dc_rgb(50, 90, 230));   /* blue  */
+
+    /* A white frame around the screen. */
+    dc_rect(0, 0, DC_W, 4, dc_rgb(255, 255, 255));
+    dc_rect(0, DC_H - 4, DC_W, 4, dc_rgb(255, 255, 255));
+    dc_rect(0, 0, 4, DC_H, dc_rgb(255, 255, 255));
+    dc_rect(DC_W - 4, 0, 4, DC_H, dc_rgb(255, 255, 255));
+
+    /* Hold the frame. */
+    for (;;) { }
+}