romdevtools 0.56.1 → 0.70.0

package/CHANGELOG.md

@@ -4,6 +4,285 @@ 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)

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/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.70.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.0",
     "romdev-core-parallel-n64": "0.1.0",
-    "romdev-core-pcsx-rearmed": "0.1.0",
+    "romdev-core-beetle-psx-hw": "0.1.0",
     "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",

package/src/analysis/analyze.js

@@ -135,13 +135,14 @@ export function sniffPlatform(p) {
   if (/\.pce$/i.test(p)) return "pce";
   if (/\.(z64|n64|v64)$/i.test(p)) return "n64";
   if (/\.(psexe|psx)$/i.test(p)) return "ps1"; // .exe/.bin ambiguous — pass platform explicitly
+  if (/\.(cdi|gdi)$/i.test(p)) return "dreamcast"; // DC disc images; .elf is cross-platform — pass platform explicitly
   if (/\.(gen|md|bin)$/i.test(p)) return "genesis";
   return null;
 }
 
 /** rizin asm.bits per arch (analysis defaults; rizin's loader usually sets
  * these for recognized formats, but raw blobs need a hint). */
-const BITS = { arm: 32, m68k: 32, snes: 16, mips: 32 };
+const BITS = { arm: 32, m68k: 32, snes: 16, mips: 32, sh: 32 };
 
 /**
  * The rizin analysis-SEED command for a context. For the 8/16-bit platforms
@@ -154,7 +155,10 @@ const BITS = { arm: 32, m68k: 32, snes: 16, mips: 32 };
  * @returns {string} the seed command (no trailing semicolon)
  */
 function analysisSeed({ arch, codeStart }) {
-  if (arch === "mips") {
+  // MIPS (N64/PS1) and SH-4 (Dreamcast) are raw code images with no rizin-recognized
+  // entry, so `aaa` finds nothing — seed a function at the code start + recursively
+  // analyze its call graph (`af` + `aac`). The 8/16-bit bin formats self-seed via aaa.
+  if (arch === "mips" || arch === "sh") {
     const at = "0x" + (codeStart || 0).toString(16);
     return `af @ ${at}; aac @ ${at}`;
   }
@@ -167,8 +171,12 @@ function analysisSeed({ arch, codeStart }) {
  *  `rebase` so callers get real VAs that round-trip through the decompile
  *  VA→fileOffset math. N64 (.z64) keeps its absolute VAs baked into the code and is
  *  analyzed flat from codeStart, so no rebase. */
-function mipsAnalysisBase({ arch, platform, loadBase, codeStart }) {
-  const rebase = (arch === "mips" && platform === "ps1" && loadBase) ? (loadBase & 0xfff00000) >>> 0 : 0;
+function mipsAnalysisBase({ platform, loadBase, codeStart }) {
+  // PS1 (left-padded to the VA's low 20 bits) and Dreamcast (same, loadBase
+  // 0x8c010000) need the VA's HIGH bits added back so addresses round-trip. N64 runs
+  // flat with VAs already baked in (no rebase).
+  const padded = (platform === "ps1" || platform === "dreamcast") && loadBase;
+  const rebase = padded ? (loadBase & 0xfff00000) >>> 0 : 0;
   return { baddr: undefined, seedAt: codeStart, rebase };
 }
 
@@ -276,6 +284,39 @@ async function loadContext(romPath, platformOverride) {
       romBytes = text;
     }
   }
+  // Dreamcast SH-4: KOS produces an ELF (load base 0x8c010000) or a stripped flat
+  // binary. For an ELF, strip to the first PT_LOAD segment's bytes + take its vaddr
+  // as loadBase. Like PS1, SH-4 uses PC-relative + absolute addressing, so left-pad
+  // so flat offset == the VA's low bits and add the high bits back as rebase.
+  if (platform === "dreamcast") {
+    let text = romBytes, loadVa = 0x8c010000;
+    if (romBytes.length >= 0x34 && romBytes[0] === 0x7f && romBytes[1] === 0x45 &&
+        romBytes[2] === 0x4c && romBytes[3] === 0x46) { // "\x7fELF"
+      // ELF32 LE: e_phoff @0x1c, e_phentsize @0x2a, e_phnum @0x2c. Find first PT_LOAD.
+      const u32 = (o) => (romBytes[o] | (romBytes[o + 1] << 8) | (romBytes[o + 2] << 16) | (romBytes[o + 3] << 24)) >>> 0;
+      const u16 = (o) => romBytes[o] | (romBytes[o + 1] << 8);
+      const phoff = u32(0x1c), phentsize = u16(0x2a), phnum = u16(0x2c);
+      for (let i = 0; i < phnum; i++) {
+        const ph = phoff + i * phentsize;
+        if (u32(ph) === 1) { // PT_LOAD
+          const p_offset = u32(ph + 4), p_vaddr = u32(ph + 8), p_filesz = u32(ph + 16);
+          loadVa = p_vaddr >>> 0;
+          text = romBytes.subarray(p_offset, p_offset + p_filesz);
+          break;
+        }
+      }
+    }
+    loadBase = loadVa >>> 0;
+    const lowPad = loadBase & 0x000fffff;
+    if (lowPad > 0 && lowPad <= 0x200000) {
+      const padded = new Uint8Array(lowPad + text.length);
+      padded.set(text, lowPad);
+      romBytes = padded;
+      codeStart = lowPad;
+    } else {
+      romBytes = text;
+    }
+  }
 
   // A6: container/format sniff. Some dumps are interleaved/headered such that a
   // FLAT read scrambles every byte → fake "bad instruction" noise everywhere.
@@ -623,12 +664,26 @@ export async function analyzeDecompile(romPath, address, platformOverride) {
   // offset and decompile via the MIPS SLEIGH spec (MIPS:BE:32 for N64, MIPS:LE:32
   // for PS1). N64: normalize byte order, fileOff = vaddr - entryVaddr + 0x1000 (post
   // IPL3). PS1: strip PS-EXE, fileOff = vaddr - loadAddr.
-  if (platform === "n64" || platform === "ps1") {
+  if (platform === "n64" || platform === "ps1" || platform === "dreamcast") {
     let fileOff;
     if (platform === "n64") {
       romBytes = normalizeN64ByteOrder(romBytes).bytes;
       const entry = ((romBytes[0x08] << 24) | (romBytes[0x09] << 16) | (romBytes[0x0a] << 8) | romBytes[0x0b]) >>> 0;
       fileOff = ((address >>> 0) - entry + 0x1000) >>> 0;
+    } else if (platform === "dreamcast") {
+      // SH-4: strip the ELF to its first PT_LOAD segment (vaddr = loadBase), or treat
+      // a raw image as flat at 0x8c010000. fileOff = address - segment vaddr.
+      let loadVa = 0x8c010000;
+      if (romBytes.length >= 0x34 && romBytes[0] === 0x7f && romBytes[1] === 0x45 && romBytes[2] === 0x4c && romBytes[3] === 0x46) {
+        const u32 = (o) => (romBytes[o] | (romBytes[o + 1] << 8) | (romBytes[o + 2] << 16) | (romBytes[o + 3] << 24)) >>> 0;
+        const u16 = (o) => romBytes[o] | (romBytes[o + 1] << 8);
+        const phoff = u32(0x1c), phentsize = u16(0x2a), phnum = u16(0x2c);
+        for (let i = 0; i < phnum; i++) {
+          const ph = phoff + i * phentsize;
+          if (u32(ph) === 1) { loadVa = u32(ph + 8) >>> 0; romBytes = romBytes.subarray(u32(ph + 4), u32(ph + 4) + u32(ph + 16)); break; }
+        }
+      }
+      fileOff = ((address >>> 0) - loadVa) >>> 0;
     } else {
       let loadAddr = 0;
       if (romBytes.length >= 0x800 && romBytes[0] === 0x50 && romBytes[1] === 0x53 && romBytes[2] === 0x2d && romBytes[3] === 0x58) {

package/src/analysis/decompile.js

@@ -51,6 +51,9 @@ export const SLEIGH_LANGID = {
   // 32-bit MIPS III code). Ghidra ships both MIPS variants in its stock SLEIGH.
   ps1: "MIPS:LE:32:default",
   n64: "MIPS:BE:32:default",
+  // Dreamcast = SH-4 (SuperH), little-endian. Ghidra ships SuperH4 in its stock
+  // SLEIGH; we compile SuperH4_le.sla (see scripts/build-decompiler.sh).
+  dreamcast: "SuperH4:LE:32:default",
 };
 
 /**

package/src/analysis/rizin.js

@@ -59,14 +59,16 @@ export const RIZIN_ARCH = {
   // below — same arch, different byte order.
   ps1: "mips",
   n64: "mips",
+  dreamcast: "sh", // SH-4 (SuperH) — rizin's `sh` plugin covers it
 };
 
 /** Byte order per platform, for shared-arch families that ship both (MIPS). Only
  *  platforms NOT matching their arch default need an entry; absent → use the
- *  loader/arch default. PS1 is little, N64 is big. */
+ *  loader/arch default. PS1 is little, N64 is big. Dreamcast SH-4 is little. */
 export const RIZIN_ENDIAN = {
   ps1: "little",
   n64: "big",
+  dreamcast: "little",
 };
 
 /**

package/src/cores/capabilities.js

@@ -219,15 +219,19 @@ export const CAPABILITIES = {
     cpus: { main: "r3000", secondary: ["gte"] },
     audioChips: ["spu"],
     memoryRegions: [...GENERIC_REGIONS],
-    renderingKind: "framebuffer", introspection: "shallow",
+    renderingKind: "3d", introspection: "shallow",
     ops: {
-      // pcsx_rearmed: software render + HLE BIOS (no firmware, no GL). run/screenshot
-      // + cpuState (R3000 regsnap) + cheats live; disasm + decompile work (MIPS
-      // Capstone + the MIPS:LE:32 SLEIGH spec). build needs a PS1 toolchain
-      // (PSn00bSDK, not yet). The framebuffer renderer has no tile/sprite inspectors.
+      // beetle_psx_hw: the GPU renders on the REAL GPU via the GLES3/WebGL2 hardware
+      // renderer through native-gles (like glide64-N64 + Flycast-DC), with OpenBIOS
+      // EMBEDDED (PCSX-Redux, MIT, region-free) — no Sony firmware to ship, no BIOS file.
+      // run/screenshot + cheats live; disasm + decompile work (MIPS Capstone + the
+      // MIPS:LE:32 SLEIGH spec). cpuState/audioDebug are OFF: those need beetle-side
+      // romdev_mips_regs_get/romdev_spu_get exports (a future core patch — the old
+      // pcsx_rearmed-software build had them, but it has no WebGL2 GPU path). build needs
+      // a PS1 toolchain (PSn00bSDK, not yet).
       build: true, run: true, screenshot: true,
       inspectSprites: false, inspectPalette: false, inspectBackground: false,
-      renderingContext: false, cpuState: true, audioDebug: true,
+      renderingContext: false, cpuState: false, audioDebug: false,
       cart: false, disasm: true, decompile: true,
     },
   },
@@ -248,6 +252,26 @@ export const CAPABILITIES = {
       cart: false, disasm: true, decompile: true,
     },
   },
+
+  dreamcast: {
+    cpuFamily: "sh", decompileQuality: "good", tier: "sh",
+    cpus: { main: "sh4", secondary: ["arm7"] }, // SH-4 main + ARM7 AICA sound CPU
+    audioChips: ["aica"],
+    memoryRegions: [...GENERIC_REGIONS],
+    renderingKind: "3d", introspection: "shallow",
+    ops: {
+      // Flycast WASM boots + RUNS homebrew .elf (reios HLE): the SH-4 executes guest
+      // code (run + memory introspection), and the PowerVR2 present-path works — flycast
+      // renders to the GL FBO and the host reads it back (verified: a framebuffer-writing
+      // program shows ~727k captured pixels). `build` lands with the sh-elf-gcc WASM
+      // toolchain. The 3D renderer has no tile/sprite inspectors (N/A by hw).
+      // disasm/decompile = SH-4 analysis slice (rizin `sh` + Ghidra SuperH4 SLEIGH).
+      build: true, run: true, screenshot: true,
+      inspectSprites: false, inspectPalette: false, inspectBackground: false,
+      renderingContext: false, cpuState: false, audioDebug: false,
+      cart: false, disasm: true, decompile: true,
+    },
+  },
 };
 
 /** The 32-bit MIPS tier (PS1/N64) — marked `tier:"mips"`. A PARTIAL tier: they
@@ -259,14 +283,22 @@ export const MIPS_TIER_PLATFORMS = Object.entries(CAPABILITIES)
   .filter(([, c]) => c.tier === "mips")
   .map(([p]) => p);
 
+/** The next-gen tiers (32-bit CPU families added after the canonical 14): MIPS
+ *  (PS1/N64) + SH (Dreamcast) + future. Any platform carrying a CPU-family `tier`
+ *  is held to its OWN conformance, not the "all 14" cross-checks; a new platform
+ *  starts here (analysis-first) and graduates as run/build/etc. land. */
+export const NEXTGEN_TIER_PLATFORMS = Object.entries(CAPABILITIES)
+  .filter(([, c]) => c.tier === "mips" || c.tier === "sh")
+  .map(([p]) => p);
+
 /** Back-compat: the analysis-only set is now empty (PS1/N64 gained run/screenshot
  *  in the run-side wiring). Kept so the name still resolves for older imports. */
 export const ANALYSIS_ONLY_PLATFORMS = [];
 
 /** The canonical tier-1 platforms (the 14): full op surface, universal build/run/
- *  screenshot. Excludes the partial MIPS tier above. */
+ *  screenshot. Excludes the partial next-gen tiers above. */
 export const CONTRACT_PLATFORMS = Object.keys(CAPABILITIES)
-  .filter((p) => !MIPS_TIER_PLATFORMS.includes(p));
+  .filter((p) => !NEXTGEN_TIER_PLATFORMS.includes(p));
 
 /** Does `platform` support `op`? Unknown platform/op → false. */
 export function supports(platform, op) {

package/src/cores/registry.js

@@ -57,14 +57,19 @@ export const CORES = {
   // webgl-node bridge only when one of these boots (hwRender:true). The other 14 are
   // software-rendered and never touch GL, so a headless user without the GPU module
   // is unaffected.
-  // parallel_n64 built headless-angrylion (software RDP + VI scanout, no GL) so raw
-  // CPU-rendered homebrew framebuffers display — the clean no-GL-dependency N64 path,
-  // like pcsx_rearmed for PS1. (The GL/glide64 build only presents RDP display-lists.)
-  n64: { platform: "n64", coreName: "parallel_n64", pkg: "romdev-core-parallel-n64", displayName: "Nintendo 64 (ParaLLEl N64, software)", hwRender: false },
-  // pcsx_rearmed = SOFTWARE renderer + built-in HLE BIOS (no firmware to ship, no
-  // GL dependency) — the clean no-dependency PS1 path, like the other 14. The GL
-  // beetle_psx_hw (+ real BIOS) stays available as a higher-fidelity alternative.
-  ps1: { platform: "ps1", coreName: "pcsx_rearmed", pkg: "romdev-core-pcsx-rearmed", displayName: "Sony PlayStation (PCSX-ReARMed, HLE)", aka: "psx,playstation" },
+  // parallel_n64 renders the RDP on the REAL GPU through glide64 (GL HLE) → native-gles
+  // (the host's WebGL2 bridge), same path as Flycast. The host forces the glide64 plugin
+  // via a core option. NOT software RDP (angrylion) — that was the old headless build.
+  n64: { platform: "n64", coreName: "parallel_n64", pkg: "romdev-core-parallel-n64", displayName: "Nintendo 64 (ParaLLEl N64, glide64 GL)", hwRender: true },
+  // beetle_psx_hw = mednafen PSX with the GLES3/WebGL2 HARDWARE renderer → rendered on
+  // the real GPU through native-gles (like glide64-N64 + Flycast-DC). 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 — the GPU PS1 path with an open BIOS.
+  ps1: { platform: "ps1", coreName: "beetle_psx_hw", pkg: "romdev-core-beetle-psx-hw", displayName: "Sony PlayStation (Beetle PSX HW, OpenBIOS)", aka: "psx,playstation", hwRender: true },
+  // Flycast = full Dreamcast emulator, GLES3/WebGL2 HW-render (PowerVR2 is GPU-first,
+  // no software framebuffer path) → driven through the native-gles/webgl-node bridge
+  // like the GL N64 build. HLE BIOS (reios) on by default — no firmware to ship.
+  dreamcast: { platform: "dreamcast", coreName: "flycast", pkg: "romdev-core-flycast", displayName: "Sega Dreamcast (Flycast)", aka: "dc", hwRender: true },
 };
 
 /** Try to get {jsPath,wasmPath} for a core from its binary package. */