romdevtools 0.56.1 → 0.71.0

package/CHANGELOG.md

@@ -4,6 +4,344 @@ 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.71.0 — 2026-06-28
+
+### N64 / PS1 / Dreamcast reach full parity: cpuState + audioDebug + GPU-rendering helper libs + 5 examples each
+
+The three next-gen 3D platforms are now first-class alongside the original 14.
+
+**Live debugging (cpuState + audioDebug).** PS1 (beetle_psx_hw) and Dreamcast (flycast)
+gained the romdev debug-reader exports, so `cpu({op:'read'})` and
+`audioDebug({op:'inspect'})` light up (N64 already had them):
+- **PS1** — `cpu({op:'read'})` returns the live R3000A register file; `audioDebug({chip:'spu'})`
+  decodes the SPU's 24 voices + main volume (read from the raw register mirror, not the
+  sweep-quantized `SPU_Read`).
+- **Dreamcast** — `cpu({op:'read'})` returns the SH-4 registers (r0–r15, pc, pr, gbr, vbr,
+  sr + decoded flags, mac, fpul); `audioDebug({chip:'aica'})` decodes the AICA's 64
+  PCM/ADPCM channels + master volume. Full host plumbing + decoders added.
+- The capability manifest now reports cpuState/audioDebug `true` for all three (verified by
+  probing real core exports; `breakpoint`/`watch` remain pending on PS1/DC).
+
+**GPU-rendering helper libs (no software framebuffers).** Every 3D platform's helper now
+draws through the GPU — a software rasterizer would be black on the GL cores and <1fps:
+- **N64** — the `n64.h` helper was rewritten to emit a **GBI (F3DEX2) display list** that
+  glide64 HLEs onto the GPU (clear/rect as fill-rectangles, triangles scan-converted into
+  GPU fill-rect spans), instead of poking pixels into RDRAM (which rendered black on
+  glide64). No Nintendo microcode shipped — the OSTask CRC-bait trick selects F3DEX2.
+- **PS1** — already correct (GP0 GPU primitives on beetle_psx_hw).
+- **Dreamcast** — `dc.h` now sets **480i interlace** in `dc_video_init` (240p only showed
+  the top 240 of 480 lines), and added a Maple-DMA `dc_pad()` / `dc_pressed()`.
+- `#include "n64.h"` / `#include "psx.h"` now auto-bundle (parity with `dc.h`).
+
+**5 genre examples per platform.** N64, PS1, and Dreamcast each ship
+shmup / platformer / puzzle / racing / sports examples — all verified building + rendering
+on the GPU.
+
+**Docs.** MENTAL_MODEL + TROUBLESHOOTING for N64, PS1, and Dreamcast (the render model,
+boot story, debug surface, and what's N/A and why).
+
+### asar (SNES) build-tool fixes
+
+From real commercial-disassembly feedback:
+- **`build({output:'project'|'run'})` honors `options` + a new `defines` map** (e.g. asar
+  `--define`) — they were silently dropped.
+- **New `entry` param** so a project whose top file isn't `main.*` (e.g. an existing
+  `smw.asm` disassembly) builds without injecting glue.
+- **Subdirectory assets are staged recursively** (a flat `readdir` missed nested
+  `incbin`/`incsrc` targets).
+- **A clean asar error is no longer mislabeled** `[worker] Abort in WASM` (it exits errors
+  via a C++-exception path; the misleading heap-pointer line is stripped when real
+  diagnostics are present).
+- **The LoROM-header bankcross preflight no longer false-positives** on banks $01+ (the
+  header is only in bank $00) and honors `check bankcross off`.
+- **A readfile/filesize advisory** warns when a source reads many distinct files that way
+  (the asar-WASM resource limit), pointing at the pre-convert-to-`.bin` + `incbin`
+  workaround.
+
+### Toolchain
+
+- **sh-c (Dreamcast) defaults to `-O1`** — the sh-elf `cc1.wasm` has an `-O2`-only pass
+  that aborts on common control flow; `-O1` dodges it. A user-supplied `-O<level>` wins.
+
+## 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)

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 (;;) { }
+}

package/examples/dreamcast/platformer/main.c

@@ -0,0 +1,31 @@
+/* Dreamcast PLATFORMER demo — a side-scrolling scene: a hero hops across platforms
+ * while the camera scrolls. Self-animating (no input). Renders on the PowerVR2 via
+ * the framebuffer path. */
+#include "dc.h"
+
+void main(void){
+    int frame = 0;
+    dc_video_init();
+    for (;;){
+        int scroll = (frame * 2) % (DC_W);
+        int t = frame % 90;
+        int jump = t < 45 ? t : (90 - t);              /* 0..45..0 hop */
+        int hy = DC_H - 140 - jump * 2;
+        int hx = DC_W/2 - 16;
+
+        dc_clear(dc_rgb(80, 150, 230));                /* sky */
+        /* parallax hills */
+        { int i; for (i = -1; i < 6; i++){ int x = i*140 - (scroll/2); dc_rect(x, DC_H-200, 120, 200, dc_rgb(60, 170, 90)); } }
+        /* ground */
+        dc_rect(0, DC_H-60, DC_W, 60, dc_rgb(120, 80, 40));
+        /* floating platforms (scrolling) */
+        { int i; for (i = -1; i < 6; i++){ int x = i*180 - (scroll % 180); dc_rect(x, DC_H-160, 90, 18, dc_rgb(150, 110, 60)); } }
+        /* hero (head + body) */
+        dc_rect(hx, hy, 32, 32, dc_rgb(240, 90, 70));
+        dc_rect(hx+6, hy+6, 6, 6, dc_rgb(255,255,255)); /* eye */
+        dc_rect(hx, hy+32, 32, 20, dc_rgb(40, 60, 200)); /* legs */
+        /* a coin that bobs */
+        dc_rect(DC_W/2 + 120 - (scroll%240), DC_H-220 + (jump), 18, 18, dc_rgb(255, 220, 60));
+        frame++;
+    }
+}

package/examples/dreamcast/puzzle/main.c

@@ -0,0 +1,44 @@
+/* Dreamcast PUZZLE demo — a falling-block (Tetris-like) board that fills + clears
+ * rows on a loop. Self-animating (no input). Renders on the PowerVR2 framebuffer. */
+#include "dc.h"
+
+#define COLS 10
+#define ROWS 16
+#define CELL 24
+
+static unsigned char board[ROWS][COLS];
+static unsigned int rng = 0xACE1u;
+static unsigned int rnd(void){ rng ^= rng << 7; rng ^= rng >> 9; rng ^= rng << 8; return rng; }
+
+static const u16 PAL[7] = { 0, 0xF800, 0x07E0, 0x001F, 0xFFE0, 0xF81F, 0x07FF };
+
+void main(void){
+    int frame = 0, px = COLS/2, py = 0, col = 1, i, r, c;
+    dc_video_init();
+    for (;;){
+        int ox = (DC_W - COLS*CELL)/2, oy = (DC_H - ROWS*CELL)/2;
+
+        if ((frame % 8) == 0){
+            /* drop the active block one row; lock + respawn at the bottom */
+            if (py+1 >= ROWS || board[py+1][px]){
+                board[py][px] = col;
+                /* clear full-ish rows occasionally to keep it moving */
+                for (r = 0; r < ROWS; r++){ int full=1; for (c=0;c<COLS;c++) if(!board[r][c]) full=0;
+                    if (full){ for(c=0;c<COLS;c++) board[r][c]=0; } }
+                py = 0; px = rnd()%COLS; col = 1 + rnd()%6;
+                if (board[0][px]){ for(r=0;r<ROWS;r++)for(c=0;c<COLS;c++) board[r][c]=0; } /* reset if buried */
+            } else py++;
+        }
+        dc_clear(dc_rgb(18, 18, 30));
+        /* board frame */
+        dc_rect(ox-4, oy-4, COLS*CELL+8, ROWS*CELL+8, dc_rgb(90,90,120));
+        dc_rect(ox, oy, COLS*CELL, ROWS*CELL, dc_rgb(10,10,18));
+        /* settled cells */
+        for (r = 0; r < ROWS; r++) for (c = 0; c < COLS; c++) if (board[r][c])
+            dc_rect(ox + c*CELL+1, oy + r*CELL+1, CELL-2, CELL-2, PAL[board[r][c]]);
+        /* active block */
+        dc_rect(ox + px*CELL+1, oy + py*CELL+1, CELL-2, CELL-2, PAL[col]);
+        frame++;
+        (void)i;
+    }
+}

package/examples/dreamcast/racing/main.c

@@ -0,0 +1,39 @@
+/* Dreamcast RACING demo — a pseudo-3D road that curves + scrolls toward a horizon,
+ * with a car at the bottom that drifts side to side. Self-animating (no input).
+ * Renders on the PowerVR2 framebuffer. */
+#include "dc.h"
+
+/* tiny fixed sine via a 16-entry quarter table */
+static const int SIN16[17] = {0,49,97,142,181,213,236,251,256,251,236,213,181,142,97,49,0};
+static int isin(int a){ a &= 63; if(a<16) return SIN16[a]; if(a<32) return SIN16[32-a]; if(a<48) return -SIN16[a-32]; return -SIN16[64-a]; }
+
+void main(void){
+    int frame = 0, y;
+    dc_video_init();
+    for (;;){
+        int horizon = DC_H/3;
+        dc_clear(dc_rgb(60, 140, 230));               /* sky */
+        dc_rect(0, horizon, DC_W, DC_H-horizon, dc_rgb(40, 120, 50)); /* grass */
+
+        /* road: for each scanline below the horizon, a trapezoid widening to the
+           bottom, shifted by a curve that scrolls. */
+        for (y = horizon; y < DC_H; y++){
+            int depth = y - horizon;
+            int half = depth * (DC_W/2 - 20) / (DC_H - horizon) + 12;
+            int curve = isin((frame/2 + depth/4)) * depth / 256;
+            int cx = DC_W/2 + curve;
+            /* road stripe alternation for motion */
+            u16 rc = (((depth + frame) / 12) & 1) ? dc_rgb(70,70,75) : dc_rgb(90,90,95);
+            dc_rect(cx - half, y, half*2, 1, rc);
+            /* center dashes */
+            if ((((depth + frame*2)/16) & 1)) dc_rect(cx-2, y, 4, 1, dc_rgb(240,240,120));
+        }
+        /* the car (drifts L/R) */
+        { int carx = DC_W/2 + isin(frame/3) * 60 / 256 - 24;
+          dc_rect(carx, DC_H-70, 48, 40, dc_rgb(220, 40, 40));
+          dc_rect(carx+6, DC_H-64, 36, 14, dc_rgb(40,40,60));     /* windshield */
+          dc_rect(carx-4, DC_H-44, 10, 18, dc_rgb(20,20,20));     /* wheels */
+          dc_rect(carx+42, DC_H-44, 10, 18, dc_rgb(20,20,20)); }
+        frame++;
+    }
+}

package/examples/dreamcast/shmup/main.c

@@ -0,0 +1,50 @@
+/* Dreamcast SHMUP demo — a vertical shooter scene rendered on the PowerVR2 via the
+ * framebuffer path. The ship weaves, bullets stream up, enemies descend + recycle.
+ * Self-animating (no input) — proves program-controlled graphics render on the GPU.
+ * (DC input via dc_pad() reads the resting controller state; full press wiring is a
+ * follow-up — see dc.h.) */
+#include "dc.h"
+
+#define NB 12
+#define NE 6
+
+static int frame;
+static unsigned int rng = 0x1234567u;
+static unsigned int rnd(void){ rng ^= rng << 13; rng ^= rng >> 17; rng ^= rng << 5; return rng; }
+
+static int bx[NB], by[NB], ba[NB];
+static int ex[NE], ey[NE];
+
+void main(void){
+    int i;
+    dc_video_init();
+    for (i = 0; i < NE; i++){ ex[i] = 60 + i*90; ey[i] = -(int)(rnd()%300); }
+    for (;;){
+        int shipx = DC_W/2 + (int)(80.0 * ((frame % 120) < 60 ? (frame%60) : (60-(frame%60))) / 60.0 - 40);
+        int shipy = DC_H - 80;
+
+        /* spawn a bullet every 8 frames */
+        if ((frame & 7) == 0){
+            for (i = 0; i < NB; i++) if (!ba[i]){ ba[i]=1; bx[i]=shipx; by[i]=shipy; break; }
+        }
+        dc_clear(dc_rgb(8, 10, 28));
+        /* starfield */
+        for (i = 0; i < 24; i++){
+            int sx = (int)((rnd()%DC_W));
+            int sy = (int)((frame*2 + i*53) % DC_H);
+            dc_rect(sx, sy, 2, 2, dc_rgb(120,120,160));
+        }
+        /* enemies */
+        for (i = 0; i < NE; i++){
+            ey[i] += 2;
+            if (ey[i] > DC_H){ ey[i] = -(int)(rnd()%200); ex[i] = (int)(rnd()%(DC_W-40)); }
+            if (ey[i] >= 0) dc_rect(ex[i], ey[i], 36, 28, dc_rgb(220, 60, 60));
+        }
+        /* bullets */
+        for (i = 0; i < NB; i++) if (ba[i]){ by[i] -= 8; if (by[i] < 0) ba[i]=0; else dc_rect(bx[i]-2, by[i], 4, 12, dc_rgb(255,240,80)); }
+        /* player ship (a little arrow of rects) */
+        dc_rect(shipx-4, shipy, 8, 24, dc_rgb(80, 200, 255));
+        dc_rect(shipx-16, shipy+14, 32, 8, dc_rgb(60, 160, 230));
+        frame++;
+    }
+}

package/examples/dreamcast/sports/main.c

@@ -0,0 +1,39 @@
+/* Dreamcast SPORTS demo — a top-down pong/air-hockey rally: two paddles track a
+ * bouncing ball with a scoreboard. Self-animating (the CPU "AI" plays both sides).
+ * Renders on the PowerVR2 framebuffer. */
+#include "dc.h"
+
+void main(void){
+    int frame = 0;
+    int bx = DC_W/2, by = DC_H/2, vx = 5, vy = 3;
+    int p0 = DC_H/2, p1 = DC_H/2;          /* paddle centers (y) */
+    int s0 = 0, s1 = 0, i;
+    dc_video_init();
+    for (;;){
+        /* ball physics */
+        bx += vx; by += vy;
+        if (by < 12 || by > DC_H-12) vy = -vy;
+        /* paddles track the ball (simple AI) */
+        if (p0 < by) p0 += 4; else p0 -= 4;
+        if (p1 < by) p1 += 4; else p1 -= 4;
+        /* bounce off paddles / score */
+        if (bx < 40){ if (by > p0-50 && by < p0+50) vx = -vx; else { s1++; bx=DC_W/2; by=DC_H/2; vx=5; } }
+        if (bx > DC_W-40){ if (by > p1-50 && by < p1+50) vx = -vx; else { s0++; bx=DC_W/2; by=DC_H/2; vx=-5; } }
+
+        dc_clear(dc_rgb(15, 60, 30));                  /* court green */
+        /* center line (dashed) */
+        for (i = 0; i < DC_H; i += 32) dc_rect(DC_W/2-2, i+8, 4, 16, dc_rgb(200,200,200));
+        /* top/bottom rails */
+        dc_rect(0, 0, DC_W, 8, dc_rgb(220,220,220));
+        dc_rect(0, DC_H-8, DC_W, 8, dc_rgb(220,220,220));
+        /* paddles */
+        dc_rect(24, p0-50, 14, 100, dc_rgb(80, 160, 255));
+        dc_rect(DC_W-38, p1-50, 14, 100, dc_rgb(255, 160, 80));
+        /* ball */
+        dc_rect(bx-8, by-8, 16, 16, dc_rgb(255, 240, 80));
+        /* scoreboard (score as stacked pips) */
+        for (i = 0; i < s0 && i < 9; i++) dc_rect(DC_W/2 - 60 - i*10, 16, 8, 8, dc_rgb(80,160,255));
+        for (i = 0; i < s1 && i < 9; i++) dc_rect(DC_W/2 + 56 + i*10, 16, 8, 8, dc_rgb(255,160,80));
+        frame++; (void)frame;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "romdevtools",
-  "version": "0.56.1",
-  "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 16 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, PlayStation, N64, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
+  "version": "0.71.0",
+  "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 17 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, PlayStation, N64, Dreamcast, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
   "type": "module",
   "main": "src/mcp/server.js",
   "bin": {
@@ -58,8 +58,9 @@
     "romdev-core-geargrafx": "0.7.0",
     "romdev-core-gpgx": "0.12.0",
     "romdev-core-handy": "0.7.0",
+    "romdev-core-flycast": "0.1.1",
     "romdev-core-parallel-n64": "0.1.0",
-    "romdev-core-pcsx-rearmed": "0.1.0",
+    "romdev-core-beetle-psx-hw": "0.1.1",
     "romdev-core-prosystem": "0.8.0",
     "romdev-core-vice": "0.9.0",
     "romdev-famitone": "0.1.0",
@@ -72,6 +73,7 @@
     "romdev-toolchain-mips-gcc": "0.1.0",
     "romdev-toolchain-rgbds": "0.1.0",
     "romdev-toolchain-sdcc": "0.2.0",
+    "romdev-toolchain-sh-gcc": "0.1.0",
     "romdev-toolchain-vasm": "0.1.0",
     "romdev-xgm2": "0.1.0",
     "romdev_game_codes": "0.1.0",