romdevtools 0.70.0 → 0.71.0

package/src/mcp/tools/platform-tools.js

@@ -42,6 +42,7 @@ import { decodeLynxMikey, decodeLynxPalette } from "../../host/lynx-mikey-state.
 import { getPcePsgState } from "../../host/pce-psg-state.js";
 import { decodePs1Spu } from "../../host/ps1-spu-state.js";
 import { decodeN64Ai } from "../../host/n64-ai-state.js";
+import { decodeAica } from "../../host/dc-aica-state.js";
 import { getMsxAyState } from "../../host/msx-ay-state.js";
 import { decodeGbaSprites, decodeGbaPalette } from "../../host/gba-video-state.js";
 
@@ -440,7 +441,14 @@ export function registerPlatformTools(server, z, sessionKey) {
       if (!regs) throw new Error("getAudioState chip:'ai' — no AI region (load an N64 ROM into the rebuilt parallel_n64 core).");
       return { platform: "n64", ...decodeN64Ai(regs) };
     }
-    throw new Error(`getAudioState: unknown chip '${chip}'. Use 'nes' (NES 2A03), 'gb' (Game Boy/GBC), 'gba' (GBA), 'dsp' (SNES), 'psg' (Genesis/SMS/GG SN76489), 'ym2612' (Genesis FM), 'sid' (C64), 'mikey' (Lynx), 'pce', 'ay8910' (MSX), or 'spu' (PS1).`);
+    if (chip === "aica") {
+      // Dreamcast AICA — 64 PCM/ADPCM channels (key-on/volume/pitch/loop) + master
+      // volume, from the rebuilt flycast core's romdev_aica_get register window.
+      const regs = host.getAicaRegs?.();
+      if (!regs) throw new Error("getAudioState chip:'aica' — no AICA region (load a Dreamcast program into the rebuilt flycast core).");
+      return { platform: "dreamcast", ...decodeAica(regs) };
+    }
+    throw new Error(`getAudioState: unknown chip '${chip}'. Use 'nes' (NES 2A03), 'gb' (Game Boy/GBC), 'gba' (GBA), 'dsp' (SNES), 'psg' (Genesis/SMS/GG SN76489), 'ym2612' (Genesis FM), 'sid' (C64), 'mikey' (Lynx), 'pce', 'ay8910' (MSX), 'spu' (PS1), or 'aica' (Dreamcast).`);
   }
 
   getAudioStateCore = async ({ chip }, callerSessionKey) => jsonContent(readAudioChip(chip, callerSessionKey));

package/src/mcp/tools/toolchain.js

@@ -470,8 +470,16 @@ export function registerToolchainTools(server, z, sessionKey) {
       return jsonContent(payload);
   }
 
-  async function runSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, runtime, maxmod, rebuildSdk, crt0, crt0Path, codeLoc, dataLoc, linkerConfig, linkerConfigPath, inesHeader, path: projPath, frames = 60, holdInputs, screenshotPath, projectName }) {
+  async function runSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, runtime, maxmod, rebuildSdk, crt0, crt0Path, codeLoc, dataLoc, linkerConfig, linkerConfigPath, inesHeader, options, defines, entry, path: projPath, frames = 60, holdInputs, screenshotPath, projectName }) {
       const { buildForPlatform } = await import("../../toolchains/index.js");
+      // Merge `defines` ({_VER:1}) into `options` (--define) just like the project/rom paths,
+      // so a project-dir RUN honors them too.
+      const mergedOptions = [
+        ...(Array.isArray(options) ? options : []),
+        ...(defines && typeof defines === "object"
+          ? Object.entries(defines).flatMap(([k, v]) => ["--define", `${k}=${v}`])
+          : []),
+      ];
       const resolved = resolveCore(platform);
       if (!resolved) throw new Error(`no core available for platform '${platform}'`);
 
@@ -481,7 +489,7 @@ export function registerToolchainTools(server, z, sessionKey) {
       // happy path; without it, output:'run' + path errored ("requires source").
       const noExplicitSources = source == null && sourcePath == null && sources == null && sourcesPaths == null;
       if (projPath && noExplicitSources) {
-        const r = await readProjectDir(projPath, platform);
+        const r = await readProjectDir(projPath, platform, { entry });
         includes = { ...(includes ?? {}), ...r.includes };
         binaryIncludes = { ...(binaryIncludes ?? {}), ...r.binaryIncludes };
         if (r.crt0 != null) crt0 = r.crt0;
@@ -586,6 +594,7 @@ export function registerToolchainTools(server, z, sessionKey) {
         crt0: crt0Rel2,
         codeLoc,
         dataLoc,
+        options: mergedOptions.length ? mergedOptions : undefined,
       });
       logBuildResult("build:run", platform, build);
       if (!build.ok || !build.binary) {
@@ -703,7 +712,7 @@ export function registerToolchainTools(server, z, sessionKey) {
     "• output:'rom' (default) — assemble or compile `source` (single) / `sources` ({name:contents}) / `sourcePath` / `sourcesPaths`. Returns the ROM (path by default; `inline:true` for binaryBase64) + build log. **`binaryIncludes`/`binaryIncludePaths` (base64/path CHR-ROM, music blobs for `.incbin`) — WITHOUT them no game with external assets builds.** `includes`/`includePaths` for `.include`d text. `linkerConfig` (cc65; NES preset 'chr-ram-runtime' RECOMMENDED). `crt0`/`crt0Path`/`codeLoc`/`dataLoc` (SDCC). `runtime`/`maxmod`/`rebuildSdk` (GBA/Genesis SDK). **`lint:'strict'` fails the build (stage:'lint', no binary) if the pre-flight SDCC crash-pattern scan flags anything (e.g. the uint8 loop-bound trap); 'advisory' (default) just lists hits in issues[].** **`includeSymbols:true` returns the .map text inline on a PLAIN rom build — distinct from output:'romWithDebug' which writes .dbg/.map FILES.** Language is inferred from extension/content — usually OMIT `language`.\n" +
     "• output:'romWithDebug' — like 'rom' but also emits linker debug info for the `symbols` tool: cc65 → `.dbg`, SDCC → sdld `.map`, Genesis m68k → GNU ld map (find where a RAM var landed). DEFAULT writes ROM + debug file + log to disk (`outputPath` required unless `inline:true`). **`resolveSymbols:['grid','score']` folds those names' addresses ({resolvedSymbols:{grid:{address,hex,region?,ramOffset?}}}) straight into the result — the cheap way to a WRAM variable's address without loading the whole map (or round-tripping it through `symbols`).**\n" +
     "• output:'run' — BUILD + LOAD + RUN + SCREENSHOT in one round trip — the fastest iteration loop. Same build args; runs `frames` frames and returns the screenshot INLINE. `holdInputs` holds controller state; `screenshotPath` writes the PNG to disk instead; `projectName` titles the playtest window.\n" +
-    "• output:'project' — build a project DIRECTORY (`path`) without re-passing the file manifest each call. Entry point is `main.c` (C/SGDK Genesis, GBA, cc65/SDCC C) OR `main.s`/`main.asm` (asm). Every `.c`/`.s`/`.asm` in the dir is a translation unit (linked together), every `.h`/`.inc` an include, and `.bin/.chr/.pcm/.brr/.vgm/...` become binaryIncludes (for `.incbin`). Iterate an on-disk project by re-calling with just `{path, platform}`. **This is the no-boilerplate path for an examples({op:'fork'}) dir: the per-platform recipe auto-supplies the crt0 + load address — GB/GBC default `gb_crt0.s` + `codeLoc:0x150` (don't hand-pass them!), MSX routes `msx_crt0.s` + `codeLoc:0x4010`, SMS/GG auto-inject their bundled crt0, NES applies the chr-ram-runtime preset. PREFER this over re-passing `crt0Path`/`codeLoc` to output:'rom' for a forked project.**",
+    "• output:'project' — build a project DIRECTORY (`path`) without re-passing the file manifest each call. Entry point auto-detects `main.c` (C/SGDK Genesis, GBA, cc65/SDCC C) OR `main.s`/`main.asm` (asm); pass `entry:'smw.asm'` to point at a differently-named top-level file (e.g. an existing disassembly). Every `.c`/`.s`/`.asm` in the dir is a translation unit (linked together), every `.h`/`.inc` an include, and `.bin/.chr/.pcm/.brr/.vgm/...` (recursively, including subdirectories) become binaryIncludes (for `.incbin`). `options` (e.g. asar `--define _VER=1`) and `defines` are honored here too. Iterate an on-disk project by re-calling with just `{path, platform}`. **This is the no-boilerplate path for an examples({op:'fork'}) dir: the per-platform recipe auto-supplies the crt0 + load address — GB/GBC default `gb_crt0.s` + `codeLoc:0x150` (don't hand-pass them!), MSX routes `msx_crt0.s` + `codeLoc:0x4010`, SMS/GG auto-inject their bundled crt0, NES applies the chr-ram-runtime preset. PREFER this over re-passing `crt0Path`/`codeLoc` to output:'rom' for a forked project.**",
     {
       output: z.enum(["rom", "romWithDebug", "run", "project"])
         .describe("rom=produce a ROM (default); romWithDebug=ROM + .dbg/.map debug files; run=build+load+run+screenshot; project=build a project directory."),
@@ -722,7 +731,8 @@ export function registerToolchainTools(server, z, sessionKey) {
       crt0Path: z.string().optional().describe("Path-based `crt0`. NOT read by output:'romWithDebug' — pass `crt0` there."),
       codeLoc: z.coerce.number().int().optional().describe("SDCC — _CODE load address (default $0000; GB/GBC bundled crt0 wants 0x150)."),
       dataLoc: z.coerce.number().int().optional().describe("SDCC — _DATA (WRAM) load address (default $C000 on Z80). NOT read by output:'romWithDebug'."),
-      options: z.array(z.string()).optional().describe("output:'rom' — extra toolchain CLI options."),
+      options: z.array(z.string()).optional().describe("Extra toolchain CLI options. Honored by output:'rom' AND output:'project' (e.g. asar `--define _VER=1`, `--fix-checksum=off`, `-wno…`)."),
+      defines: z.record(z.string(), z.union([z.string(), z.number()])).optional().describe("Assembler defines as a map ({_VER:1}) — convenience for asar's `--define NAME=VALUE`. Merged into `options` for output:'rom'/'project'. (Equivalent to passing `--define _VER=1` yourself.)"),
       linkerConfig: z.string().optional().describe("ld65 linker config (cc65). NES presets: 'chr-ram-runtime' (RECOMMENDED for homebrew C — full crt0 + iNES header + NMI w/ OAM DMA + `_shadow_oam` at $0200), 'chr-ram' (bare nmi:rti stub), 'chr-rom' (cc65-C with FIXED CHR-ROM art — segment split + CHARS segment; supply CHR via binaryIncludePaths into a CHARS source + the header via `inesHeader`). Or full .cfg contents. Preset NAMES only resolve on output:'rom'/'run'; output:'romWithDebug' takes raw .cfg contents only. **For rebuilding a commercial NROM game from its disassembly, prefer `inesHeader` over a raw .cfg.**"),
       linkerConfigPath: z.string().optional().describe("Path-based `linkerConfig`: absolute path to a .cfg file on disk (the server reads it — the cfg never enters your context; e.g. the multi-bank cfg a banked-NES disasm project ships). Ignored when `linkerConfig` is passed inline."),
       inesHeader: z.object({
@@ -746,6 +756,7 @@ export function registerToolchainTools(server, z, sessionKey) {
       projectName: z.string().optional().describe("output:'run' — playtest window title (no effect on the ROM)."),
       // project-only
       path: z.string().optional().describe("output:'project' — absolute path to the project directory."),
+      entry: z.string().optional().describe("output:'project' — name of the top-level source file when it isn't main.c/main.s/main.asm (e.g. 'smw.asm' for an existing disassembly). Project-relative or a bare filename. Default: auto-detect main.c / main.s / main.asm."),
       // shared output
       outputPath: z.string().optional().describe("output:'rom'/'romWithDebug'/'project' — absolute path to write the ROM (romWithDebug writes .dbg/.map/.log alongside; REQUIRED for romWithDebug unless inline:true). output:'rom' omitted → temp-file path returned (or inline:true for base64)."),
       inline: z.boolean().default(false).describe("output:'rom'/'romWithDebug' — return binaryBase64 (+ debug text for romWithDebug) in the response instead of writing to disk."),
@@ -905,6 +916,45 @@ export function projectBuildRecipe(platform, names) {
   return r;
 }
 
+/**
+ * Recursively collect files in SUBDIRECTORIES of a project (top-level files are
+ * handled by the recipe). Returns {rel, abs} with `rel` POSIX-relative to root
+ * (e.g. "col/misc/x.pal"), so the asar/incbin mount resolves the same path the
+ * source references. Skips dot-dirs and common build/VCS dirs to avoid hauling
+ * in junk. Caps total files to keep a pathological tree from blowing up.
+ * @param {string} root
+ * @returns {Promise<Array<{rel:string, abs:string}>>}
+ */
+async function walkSubdirAssets(root) {
+  /** @type {Array<{rel:string, abs:string}>} */
+  const out = [];
+  const SKIP_DIR = new Set([".git", ".svn", "node_modules", "out", "build", "obj", ".vscode"]);
+  const MAX = 5000;
+  async function walk(dir, rel) {
+    let ents;
+    try { ents = await readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (out.length >= MAX) return;
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (e.name.startsWith(".") || SKIP_DIR.has(e.name)) continue;
+        await walk(path.join(dir, e.name), childRel);
+      } else if (e.isFile()) {
+        out.push({ rel: childRel, abs: path.join(dir, e.name) });
+      }
+    }
+  }
+  // Only descend into subdirectories (top-level handled by the flat loop/recipe).
+  let top;
+  try { top = await readdir(root, { withFileTypes: true }); } catch { return out; }
+  for (const e of top) {
+    if (e.isDirectory() && !e.name.startsWith(".") && !SKIP_DIR.has(e.name)) {
+      await walk(path.join(root, e.name), e.name);
+    }
+  }
+  return out;
+}
+
 /**
  * Read a scaffolded project DIRECTORY into the build inputs, applying the
  * per-platform recipe (crt0 routing, linker preset, runtime, skip-list) and
@@ -913,17 +963,40 @@ export function projectBuildRecipe(platform, names) {
  * can never drift. Returns crt0 as RAW source text (callers assemble it).
  * @param {string} projPath
  * @param {string} platform
+ * @param {{entry?: string}} [opts]  entry: name of the top-level source when it isn't main.*
  */
-export async function readProjectDir(projPath, platform) {
+export async function readProjectDir(projPath, platform, opts = {}) {
   const entries = await readdir(projPath, { withFileTypes: true });
   const files = entries.filter((e) => e.isFile());
 
+  // Subdirectory assets — a real disassembly keeps palettes/gfx in nested dirs
+  // (e.g. col/misc/back_area.pal) and `.incbin`s them by relative path. The old
+  // flat readdir never saw them → "file not found". Walk recursively and add any
+  // binary asset (regardless of extension/double-extension) keyed by its path
+  // RELATIVE to the project root, so the asar/incbin mount resolves it.
+  const subAssets = await walkSubdirAssets(projPath);
+
+  // Entry override: an existing project whose top file isn't main.* (e.g.
+  // smw.asm). Accept a project-relative or bare name; it becomes the single
+  // entry source. Without it, auto-detect main.c / main.s / main.asm.
+  const entryName = opts.entry ? path.normalize(opts.entry).replace(/^[./]+/, "") : null;
+  if (entryName) {
+    const exists = files.some((f) => f.name === entryName) ||
+      subAssets.some((a) => a.rel === entryName);
+    if (!exists) {
+      throw new Error(
+        `entry '${entryName}' not found in ${projPath}. Found top-level: ` +
+        `${files.map((f) => f.name).join(", ") || "(none)"}.`
+      );
+    }
+  }
+
   const hasC = files.some((f) => f.name === "main.c");
   const hasAsm = files.some((f) => f.name === "main.s" || f.name === "main.asm");
-  if (!hasC && !hasAsm) {
+  if (!entryName && !hasC && !hasAsm) {
     throw new Error(
-      `no entry point in ${projPath}: expected main.c (C/SGDK/GBA/cc65 project) or main.s / main.asm (asm project). ` +
-      `Found: ${files.map((f) => f.name).join(", ") || "(empty)"}.`
+      `no entry point in ${projPath}: expected main.c (C/SGDK/GBA/cc65 project) or main.s / main.asm (asm project), ` +
+      `or pass entry:'<top-file>'. Found: ${files.map((f) => f.name).join(", ") || "(empty)"}.`
     );
   }
 
@@ -933,6 +1006,15 @@ export async function readProjectDir(projPath, platform) {
   // the dir build matches the hand-written build({output:'run'}) call.
   const recipe = projectBuildRecipe(platform, files.map((f) => f.name));
 
+  // With a custom entry, the entry is the ONE source; every OTHER top-level
+  // .asm/.s/.c routes as an include (asar/wla resolve `.include`/`#include`
+  // from the includes mount), matching the single-source asm model.
+  if (entryName && /\.(asm|s)$/i.test(entryName)) {
+    for (const f of files) {
+      if (/\.(c|s|asm)$/i.test(f.name) && f.name !== entryName) recipe.includeAsC.add(f.name);
+    }
+  }
+
   /** @type {Record<string,string>} */ const sources = {};
   /** @type {Record<string,string>} */ const includes = {};
   /** @type {Record<string,string>} */ const binaryIncludes = {};
@@ -953,6 +1035,19 @@ export async function readProjectDir(projPath, platform) {
     }
   }
 
+  // Stage subdirectory assets (any extension) keyed by their path relative to the
+  // project root, so `incbin "col/misc/X.pal"` / `.incbin "gfx/a.bin"` resolve in
+  // the mount. Text-ish includes (.asm/.s/.h/.inc) found in subdirs go to includes
+  // (so `incsrc "lib/foo.asm"` works); everything else is a binary asset.
+  for (const a of subAssets) {
+    if (recipe.skip.has(a.rel) || a.rel === entryName) continue;
+    if (/\.(h|inc|asm|s)$/i.test(a.rel)) {
+      includes[a.rel] = (await readFile(a.abs)).toString("utf-8");
+    } else {
+      binaryIncludes[a.rel] = (await readFile(a.abs)).toString("base64");
+    }
+  }
+
   // SMS/GG with no crt0 file in the dir → fall back to the bundled crt0,
   // exactly like the output:'rom'/'run' handlers do. Without this the link
   // silently uses SDCC's stock z80 crt0, which never calls main() (black
@@ -972,8 +1067,17 @@ export async function readProjectDir(projPath, platform) {
   return { sources, includes, binaryIncludes, crt0, codeLoc: recipe.codeLoc, dataLoc: recipe.dataLoc, linkerConfig: recipe.linkerConfig, runtime, maxmod: recipe.maxmod };
 }
 
-export async function buildProjectCore({ path: projPath, platform, outputPath }) {
-  const { sources, includes, binaryIncludes, crt0, codeLoc, dataLoc, linkerConfig, runtime, maxmod } = await readProjectDir(projPath, platform);
+export async function buildProjectCore({ path: projPath, platform, outputPath, options, defines, entry }) {
+  const { sources, includes, binaryIncludes, crt0, codeLoc, dataLoc, linkerConfig, runtime, maxmod } = await readProjectDir(projPath, platform, { entry });
+
+  // Thread `options` (e.g. asar `--define _VER=1`, `--fix-checksum=off`) + the `defines`
+  // convenience map through to the toolchain — project mode used to silently drop them.
+  const mergedOptions = [
+    ...(Array.isArray(options) ? options : []),
+    ...(defines && typeof defines === "object"
+      ? Object.entries(defines).flatMap(([k, v]) => ["--define", `${k}=${v}`])
+      : []),
+  ];
 
   // Linker preset: the recipe names it (e.g. NES 'chr-ram-runtime', which ships
   // the OAM/CHARS segments + its own crt0). resolveLinkerConfig also returns any
@@ -1012,6 +1116,7 @@ export async function buildProjectCore({ path: projPath, platform, outputPath })
     crt0: crt0Rel,
     codeLoc,
     dataLoc,
+    options: mergedOptions.length ? mergedOptions : undefined,
   });
   if (outputPath && result.binary) {
     await mkdir(path.dirname(outputPath), { recursive: true });

package/src/platforms/dreamcast/MENTAL_MODEL.md

@@ -0,0 +1,87 @@
+# Sega Dreamcast — mental model
+
+The Dreamcast is a **3D machine**: a 200 MHz Hitachi SH-4 CPU (with an on-die FPU/
+vector unit) + the PowerVR2 (CLX2) **tile-based deferred renderer** drawing into
+8 MB VRAM, plus the AICA sound system (an ARM7 CPU + DSP). romdev runs it on
+**Flycast** built to WASM, presenting through the **native-gles / WebGL2 hardware
+GPU**, with the **reios HLE BIOS** so you don't ship a real `dc_boot.bin`.
+
+## The one thing to know about rendering
+
+Flycast is **GPU-first**: the PowerVR2 is a Tile Accelerator (TA) — homebrew normally
+submits TA display lists (polygon/vertex lists) that the GPU rasterizes. romdev runs
+Flycast `hwRender: true` (the real GPU via WebGL2). **BUT** the core is configured
+with `flycast_emulate_framebuffer: enabled`, which gives a working **direct-framebuffer
+scanout** path — a program that writes the DC framebuffer displays (verified: a
+framebuffer-writing program captured ~727k pixels). So both routes work:
+
+- **Direct framebuffer** (simplest for 2D / first pixels): write VRAM and let the
+  emulated-framebuffer path scan it out. The starting point for "just show something."
+- **TA / GPU** (the real path for 3D): submit PowerVR2 TA lists. The native SDK,
+  **KallistiOS (KOS)**, wraps the TA and ships an OpenGL port — lean on KOS rather than
+  hand-rolling the TA command encoding.
+
+Decide which your homebrew uses; the bundled helper lib targets the framebuffer path
+first (like a software front end) and grows toward TA.
+
+## CPU / memory map (SH-4, 32-bit, little-endian)
+
+| Region | Address | Notes |
+|--------|---------|-------|
+| System RAM | `0x8C00_0000`+ | 16 MB main RAM (KOS links code here) |
+| VRAM | `0xA500_0000`+ | 8 MB texture/framebuffer RAM |
+| Hardware regs | `0xA05F_xxxx` | PowerVR2 (TA/CORE), Holly, GD-ROM, AICA, Maple |
+| AICA RAM | `0x00800000` (AICA bus) | ARM7 sound RAM |
+
+Addresses are **little-endian**. SH-4 uses **PC-relative loads** for constants/
+addresses (`mov.l @(disp,PC)`) heavily — relevant for RE base-address alignment.
+`memory({op:'read', region:'system_ram'})` reads main RAM.
+
+## Booting — KOS ELF + reios HLE (no disc needed for the dev loop)
+
+A real Dreamcast boots from a GD-ROM with an `IP.BIN` bootstrap (a CDI/CHD disc image).
+For homebrew, that's heavy. romdev uses Flycast's **reios HLE BIOS** (`flycast_hle_bios:
+enabled`), and KallistiOS produces a ready-to-boot **ELF** — Flycast loads the raw KOS
+ELF directly, so you skip the disc-image dance. (Build a disc image only if a specific
+title demands it.) `build({platform:'dreamcast'})` produces the loadable image.
+
+## Input
+
+Homebrew reads controllers over the **Maple bus** (`0xA05F_6C00`+) — the DC's
+peripheral protocol. KOS abstracts this (`maple_enum_*`, controller state). The host's
+`setInput`/`run` holdInputs drive the emulated controller; the game polls Maple.
+
+## Sound
+
+The **AICA** = an ARM7 CPU + DSP with its own RAM. The SH-4 uploads a sound program +
+samples to AICA RAM and triggers channels. KOS ships an AICA sound driver
+(`snd_stream`). `audioChips` lists `aica`.
+
+## MCP debug & inspection tooling — current state
+
+- **`run` / `screenshot` / `frame({op:'verify'})`** — boots + presents + render-health.
+  ✅ (reios HLE; the framebuffer path captures pixels.)
+- **`memory({op:'read', region:'system_ram'})`** — SH-4 main RAM. ✅
+- **`disasm` / `decompile`** — SH-4 via rizin (`sh`) + Ghidra (SuperH4 SLEIGH). ✅
+  (Good decompile quality; SH-4 is a clean 32-bit RISC.)
+- **`build`** — sh-elf-gcc → WASM toolchain. ✅
+- **`cpu({op:'read'})`** — live SH-4 register file (`romdev_sh4_regs_get`: r0..r15, pc,
+  pr, gbr, vbr, sr, mac, fpul + decoded SR flags). ✅
+- **`audioDebug({op:'inspect', chip:'aica'})`** — the AICA's 64 PCM/ADPCM channels
+  (key-on / volume / pitch / loop / format) + master volume (`romdev_aica_get`). ✅
+- **`breakpoint` / `watch`** — not yet (need interpreter-step + memory-path hooks in
+  flycast; cpuState/audioDebug are plain reads and ARE wired).
+- **`renderingContext`** is **N/A** — 3D TA machine, no 2D tile VDP to decode.
+
+## Build pipeline
+
+`build({platform:'dreamcast'})` cross-compiles with an **sh-elf-gcc → WASM** toolchain
+(adapted from KOS's `dc-chain`; SH-4 is single-endian little, so no be/el split). Link
+against KallistiOS for libc + the TA/AICA/Maple drivers. `#include` the bundled
+`dc.h` helper for the framebuffer front end + input/audio helpers.
+
+## What's NOT bundled / hardware limits
+
+- No GD-ROM/CDDA streaming or VMU save emulation in the dev loop.
+- `breakpoint`/`watch` not yet (need interpreter-step hooks; cpuState/audioDebug ARE wired).
+- `renderingContext` is N/A (3D TA, no tile VDP).

package/src/platforms/dreamcast/TROUBLESHOOTING.md

@@ -0,0 +1,55 @@
+# Sega Dreamcast — troubleshooting
+
+Read `platform({op:'doc', platform:'dreamcast', name:'mental_model'})` first — DC runs
+on Flycast (hardware GPU + reios HLE BIOS), with a working emulated-framebuffer path.
+
+## "ROM/ELF builds but won't boot"
+
+1. **reios HLE must be on.** Flycast only boots a raw homebrew ELF via the **reios HLE
+   BIOS** (`flycast_hle_bios: enabled`) — it parses the ELF + jumps. With it off,
+   Flycast wants a real `dc_boot.bin` you don't ship. romdev's DC core config already
+   enables reios; if you swapped the core/config, re-enable it.
+2. **You built a flat binary, not a KOS ELF.** Flycast loads the KallistiOS ELF
+   (linked at `0x8C00_0000`). Use `build({platform:'dreamcast'})` — it links against
+   KOS and emits the loadable image. A bare `.bin` with no ELF/entry won't boot.
+
+## "Boots but the screen is BLACK"
+
+1. **Nothing was drawn to the framebuffer OR submitted to the TA.** DC has two render
+   routes (see mental model). For the simple path, write the DC framebuffer (the
+   `flycast_emulate_framebuffer: enabled` path scans it out — a framebuffer-writing
+   program shows pixels). For 3D, submit PowerVR2 **TA** lists via KOS. A blank screen
+   = neither happened. Confirm with `frame({op:'verify'})` (nearlyBlank).
+2. **No display/render init.** The PowerVR2 needs its video mode + render target set
+   up (KOS `vid_set_mode` / `pvr_init`). Without it there's no scanout. Call the KOS
+   init (or the helper lib's init) before drawing.
+3. **You expected raw VRAM writes to a TA-only setup to show.** With the framebuffer-
+   emulation path enabled they do; if you disabled it and use pure TA, only submitted
+   TA geometry renders.
+
+## "Geometry/3D is wrong or missing (TA path)"
+
+PowerVR2 is a **tile-based DEFERRED** renderer — opaque, punch-through, and translucent
+lists are submitted + sorted per tile. Submitting polys to the wrong list type, or not
+finalizing the list, drops them. Use KOS's `pvr_*` list API (it orders this correctly)
+rather than hand-encoding TA commands.
+
+## "disasm/decompile returns junk addresses on a multi-function program"
+
+SH-4 decompiles well, but it uses **PC-relative loads** (`mov.l @(disp,PC)`) heavily,
+so the analysis buffer's flat offsets must line up with the binary's load VA or
+constant/address resolution breaks. Build a **multi-function** test program to verify
+`functions` returns real VAs that round-trip — a single-instruction smoke test hides
+base-address misalignment. (Same class of trap as the PS1 rebase issue.)
+
+## "breakpoint / watch return N/A"
+
+`cpu({op:'read'})` and `audioDebug({op:'inspect', chip:'aica'})` ARE wired on DC (the
+flycast core exports `romdev_sh4_regs_get` + `romdev_aica_get`). `breakpoint`/`watch`
+are not yet — those need interpreter-step + memory-path hooks in flycast (cpuState/
+audioDebug are plain register reads). Use `cpu`/`audioDebug` + `memory` +
+`disasm`/`decompile` meanwhile.
+
+## "renderingContext returns N/A"
+
+Correct — DC is a 3D TA machine with no 2D tile/sprite VDP for that op. Not a bug.

package/src/platforms/dreamcast/UPSTREAM_SOURCES.md

@@ -0,0 +1,57 @@
+# Sega Dreamcast — source you can read
+
+Trust hierarchy (try in order before filing a feedback round):
+
+1. **Bundled examples** (`examples/dreamcast/{hello,shmup,platformer,puzzle,racing,sports}/main.c`)
+   — verified building + rendering on the GPU (full 480-line frame). Start here.
+2. **Bundled helper lib source** (`src/toolchains/sh-c/lib/dc.h`) — the PowerVR2
+   framebuffer bring-up + drawing + input. Read this when something doesn't render or input
+   doesn't read: it shows `dc_video_init` (FB_R_CTRL/SIZE/SOF1 + SPG, **480i interlace** —
+   240p only shows the top 240 lines), `dc_clear`/`dc_rect`, and the Maple-DMA `dc_pad()`.
+3. **The core source** (NOT bundled — fetch on demand):
+
+   | What | Upstream |
+   |---|---|
+   | Flycast (libretro core, PowerVR2 + reios HLE BIOS) | https://github.com/flyinghead/flycast |
+   | SH-4 / PowerVR2 / AICA / Maple internals | (in the flycast tree: `core/hw/sh4/`, `core/hw/pvr/`, `core/hw/aica/`, `core/hw/maple/`) |
+
+   The cpuState/audioDebug exports we patch in (`romdev_sh4_regs_get`, `romdev_aica_get`)
+   live in `scripts/patches/romdev-snippets/flycast-debug.c`.
+
+4. **The toolchain** — a from-scratch `sh-elf-gcc` cross-compiler (little-endian SH-4,
+   m4-single-only FP) built to WASM (`scripts/build-sh-toolchain.sh` +
+   `build-sh-wasm-tools.sh`). NOTE: cc1 defaults to **-O1** (the sh-elf cc1.wasm has an
+   -O2-only crash on common control flow):
+
+   | Component | Upstream |
+   |---|---|
+   | binutils | https://ftp.gnu.org/gnu/binutils/ |
+   | gcc | https://ftp.gnu.org/gnu/gcc/ |
+   | newlib | https://sourceware.org/pub/newlib/ |
+
+5. **Reverse engineering** — Rizin + Ghidra SH-4 (SuperH4 SLEIGH):
+
+   | What | Upstream |
+   |---|---|
+   | Rizin | https://github.com/rizinorg/rizin |
+   | rz-ghidra | https://github.com/rizinorg/rz-ghidra |
+
+## Dreamcast hardware docs
+
+- **KallistiOS (KOS)** — the canonical open DC SDK; read its PowerVR2 TA, AICA, and Maple
+  drivers for the standard register sequences: https://github.com/KallistiOS/KallistiOS
+- **Mc Spankled / DCEmulation docs + the Sega Dreamcast Hardware Specification** (PVR2/Holly
+  register maps): cross-check against flycast's `core/hw/pvr/pvr_regs.h` enum.
+- **SH-4 ISA / SH7750 manual** (Renesas) for the CPU.
+
+## When to use what
+
+- "Boots but the screen is BLACK / only the top half draws" → MENTAL_MODEL +
+  TROUBLESHOOTING (it's the framebuffer path + the 480i-interlace requirement).
+- "How does the helper set up the PowerVR2 framebuffer?" → `dc.h` `dc_video_init` +
+  flycast `core/hw/pvr/pvr_regs.h` (SPG_CONTROL interlace bit).
+- "dc_pad doesn't reflect button presses" → `dc.h` `dc_pad()` (Maple Get-Condition DMA) +
+  flycast `core/hw/maple/maple_devs.cpp` (the controller response framing). Reads the
+  resting state; press mapping is a known follow-up.
+- "Which AICA register holds channel key-on/volume?" → `dc-aica-state.js` decode +
+  flycast `core/hw/aica/`.

package/src/platforms/n64/MENTAL_MODEL.md

@@ -0,0 +1,84 @@
+# Nintendo 64 — mental model
+
+The N64 is a **3D machine**: a 93.75 MHz MIPS R4300i CPU + the RCP (Reality
+Co-Processor = RSP vector unit + RDP rasterizer) drawing into RDRAM, scanned out
+by the VI (Video Interface). romdev runs it on **parallel_n64** (libretro) built to
+WASM, rendering through the **glide64 GL HLE plugin** on the real GPU via romdev's
+native-gles / WebGL2 bridge (`hwRender: true`).
+
+## The one thing to know about rendering
+
+The N64 core renders through **glide64** — a GL HLE plugin that interprets the game's
+**GBI display lists** and rasterizes them on the real GPU. So romdev N64 homebrew draws
+by building a **GBI (F3DEX2) display list** each frame and kicking the RSP, the way a
+real game does; glide64 HLEs it onto the GPU. A software framebuffer (poking pixels
+into RDRAM) shows **black** on glide64 and would be <1fps — so don't do that.
+
+**Use the bundled `n64.c` helper** — it does the GPU path for you: `n64_clear`/`n64_rect`
+emit GPU **fill rectangles**, `n64_tri2d`/`n64_tri3d`/`n64_quad3d` scan-convert into
+GPU fill-rect spans (still GPU-rasterized, not CPU pixels), and `n64_flip` ships the
+display list as a GFX OSTask. `#include "n64.h"` and it just works (auto-bundled). How
+it gets glide64 to accept the list without shipping Nintendo microcode: the RSP-HLE
+treats an OSTask with `type==1` as graphics, and glide64 picks its command table by
+CRC-summing the task's "ucode" region — so the helper embeds a 3072-byte blob that
+*sums* to a real F3DEX2 CRC (the bytes are never executed under HLE).
+
+If the screen is black, the usual cause is software-framebuffer drawing instead of the
+helper's display-list path — see TROUBLESHOOTING. Confirm with `frame({op:'verify'})`.
+
+## CPU / memory map (R4300i, MIPS III, 64-bit, big-endian)
+
+| Region | KSEG | Address (virtual) | Notes |
+|--------|------|-------------------|-------|
+| RDRAM (cached)   | kseg0 | `0x8000_0000`+ | main RAM, 4 MB (8 MB with Expansion Pak) |
+| RDRAM (uncached) | kseg1 | `0xA000_0000`+ | same RAM, bypasses cache — use for the framebuffer |
+| Cart / PIF / RCP MMIO | kseg1 | `0xA300_0000`+ | SP/DP/VI/AI/PI/SI registers |
+
+Addresses are **big-endian**. `memory({op:'read', region:'system_ram'})` reads RDRAM.
+
+## Booting — header + IPL3
+
+A flat code image is not a bootable ROM. parallel_n64 HLEs the PIF boot: it copies
+ROM `0x40..0xFFF` into RSP DMEM and **executes it as the IPL3**. romdev's
+`build`/`cart` wrap a valid 64-byte header (magic `0x8037_1240`) + a minimal
+clean-room IPL3 (PI-DMA the game cart→RDRAM, jump to entry) + the game image. You
+don't write the header/IPL3 — the toolchain does (`wrapN64Rom`).
+
+## Input
+
+Homebrew reads controllers from **hardware** (the PIF/JoyBus), not via injection. The
+host's `setInput`/`run` holdInputs drive the emulated pad; the game polls JoyBus and
+sees them. The helper lib exposes a `pad_read()`.
+
+## Sound
+
+The AI (Audio Interface) DMAs a sample buffer from RDRAM to the DAC. `audioDebug`
+decodes the AI register block (`romdev_ai_get`). The helper lib has a minimal audio
+push path.
+
+## MCP debug & inspection tooling
+
+N64 is at **full parity** with the tile systems wherever the hardware allows:
+
+- **`cpu({op:'read'})`** — live R4300i register file (`romdev_mips_regs_get`).
+- **`breakpoint` / `watch`** — PC breakpoints + memory watchpoints, hooked into the
+  interpreter step + memory R/W paths.
+- **`audioDebug({op:'inspect'})`** — AI registers.
+- **`memory({op:'read', region:'system_ram'})`** — RDRAM.
+- **`disasm` / `decompile`** — MIPS via rizin/Ghidra (R4300 is well-supported).
+- **`frame({op:'verify'})`** — render-health (nearlyBlank guard) for no-vision agents.
+- **`renderingContext`** is **N/A** (false) — that decodes 2D tile/sprite VDP state,
+  which a 3D framebuffer machine doesn't have. Not a missing feature.
+
+## Build pipeline
+
+`build({platform:'n64'})` cross-compiles with a from-scratch **mips-elf-gcc → WASM**
+toolchain (cc1 → as → ld → objcopy orchestrated from JS, like the m68k path), big-
+endian libs, then `wrapN64Rom` produces the bootable image. `#include` the bundled
+`n64.h` for the 3D helpers (display-list build + VI setup + pad/audio).
+
+## What's NOT bundled / hardware limits
+
+- No custom RSP microcode path (glide64 HLEs the standard F3DEX-style display lists).
+- No real-hardware Expansion Pak detection beyond the standard 4/8 MB split.
+- `renderingContext` is N/A (3D, no tile VDP).

package/src/platforms/n64/TROUBLESHOOTING.md

@@ -0,0 +1,60 @@
+# Nintendo 64 — troubleshooting
+
+Read `platform({op:'doc', platform:'n64', name:'mental_model'})` first — the shipping
+N64 renders through the **glide64 GL HLE plugin** (it rasterizes GBI display lists on
+the real GPU), not a software framebuffer.
+
+## "ROM builds + boots but the screen is BLACK"
+
+The #1 N64 bug — almost always **software-framebuffer drawing instead of the GPU path**:
+
+1. **You poked pixels into an RDRAM framebuffer yourself.** glide64 only presents GBI
+   **display lists** — it never scans out a CPU-written framebuffer. A software
+   rasterizer renders black here (and would be <1fps anyway). **Use the bundled `n64.c`
+   helper** (`n64_clear`/`n64_rect`/`n64_tri*`/`n64_quad3d` + `n64_flip`): it emits a
+   GBI display list glide64 HLEs onto the GPU. `#include "n64.h"` (auto-bundled).
+2. **You hand-built a display list with the wrong OSTask.** The RSP-HLE only routes a
+   task to glide64 when the OSTask `type` (DMEM 0xFC0) == 1, and glide64 only accepts
+   it if the task's ucode region CRC-matches a known ucode. The helper sets both (a
+   3072-byte blob summing to an F3DEX2 CRC); if you roll your own, match that.
+3. **You forgot `n64_flip()`** — the display list isn't submitted to the RSP until
+   flip kicks the task. Confirm with `frame({op:'verify'})` (nearlyBlank).
+
+## "frame({op:'verify'}) says nearlyBlank"
+
+No GBI list reached glide64 — it's a display-list / OSTask problem (causes 1-2), not a
+toolchain problem. The build is fine; the render path is the issue. The helper handles
+all of this — diff your code against it.
+
+## "Geometry is wrong / triangles inside-out / nothing where expected"
+
+3D pipeline math (the helper transforms + projects to screen space, then scan-converts
+triangles into GPU fill-rect spans). Check: 16.16 fixed-point throughout, back-face
+winding matches your vertex order, perspective divide before the viewport map, and the
+vertices land on-screen. Diff against the helper's draw order.
+
+## "Build fails: 'relocation truncated to fit'"
+
+Statics landed in `.sdata`/`.sbss` and the 16-bit GP-relative relocs overflowed. The
+toolchain passes `-G0` to **both** cc1 and the assembler to force everything into
+`.data`/`.bss`. If you're building outside `build()` with custom flags, add `-G0`
+everywhere.
+
+## "cpu({op:'read'}) / breakpoint / watch returns nothing"
+
+These read core exports (`romdev_mips_regs_get`, `romdev_*break/watch`). On N64 they
+ARE present (full parity). If they're missing, you're on a stale core — re-resolve via
+`platform({op:'resolve', platform:'n64'})` and confirm the bundled core, don't debug
+the tool.
+
+## "disasm/decompile of a multi-function program returns junk addresses"
+
+The MIPS RE works, but for absolute-addressed `jal` targets the analysis buffer's flat
+offsets must line up with the VAs' low bits (rizin ignores `-B` on a raw buffer). N64
+usually lands fine from codeStart=0x1000 post-IPL3; if a fixed-VA image misbehaves, see
+the PS1 troubleshooting note on the rebase trick — same principle.
+
+## "renderingContext returns N/A"
+
+Correct — N64 is a 3D framebuffer machine with no 2D tile/sprite VDP for that op to
+decode. Not a bug. Use `frame`/screenshot + `memory` to inspect the framebuffer.

package/src/platforms/n64/UPSTREAM_SOURCES.md

@@ -0,0 +1,52 @@
+# Nintendo 64 — source you can read
+
+Trust hierarchy (try in order before filing a feedback round):
+
+1. **Bundled examples** (`examples/n64/{shmup,platformer,puzzle,racing,sports}/main.c`) —
+   verified building + rendering on the GPU. Start here for "how do I draw / animate / use
+   the 3D helpers."
+2. **Bundled helper lib source** (`src/platforms/n64/lib/c/n64.c` + `n64.h`) — the GPU
+   drawing backend. Read this when a draw call doesn't render the way you expect: it shows
+   exactly how `n64_clear`/`n64_rect`/`n64_tri*`/`n64_flip` build a **GBI (F3DEX2) display
+   list** + the OSTask kick (NOT a software framebuffer — see MENTAL_MODEL).
+3. **The core source** (NOT bundled — fetch on demand):
+
+   | What | Upstream |
+   |---|---|
+   | parallel_n64 (libretro core + glide64 GL HLE) | https://github.com/libretro/parallel-n64 |
+   | Reality co-processor / RSP-HLE + glide64 internals | (in the parallel_n64 tree: `mupen64plus-rsp-hle/`, `glide2gl/src/Glide64/`) |
+
+4. **The toolchain** — a from-scratch `mips-elf-gcc` cross-compiler (big-endian) built to
+   WASM (`scripts/build-mips-toolchain.sh` + `build-mips-wasm-tools.sh`):
+
+   | Component | Upstream |
+   |---|---|
+   | binutils | https://ftp.gnu.org/gnu/binutils/ |
+   | gcc | https://ftp.gnu.org/gnu/gcc/ |
+   | newlib | https://sourceware.org/pub/newlib/ |
+
+5. **Reverse engineering** — `disasm`/`decompile` go through Rizin + Ghidra's MIPS
+   (R4300) support:
+
+   | What | Upstream |
+   |---|---|
+   | Rizin | https://github.com/rizinorg/rizin |
+   | rz-ghidra (decompiler) | https://github.com/rizinorg/rz-ghidra |
+
+## N64 hardware docs
+
+- **n64brew wiki** (the canonical modern reference): https://n64brew.dev/wiki/
+- **RCP / RDP / RSP** + the VI/AI/PI/SI register maps: n64brew + the parallel_n64
+  `vi_controller.h` / `rsp_core.c` enums in the core tree.
+- **libdragon** (a real open N64 SDK — read its GBI/display-list code for the standard
+  command encodings): https://github.com/DragonMinded/libdragon
+
+## When to use what
+
+- "Why is my homebrew BLACK on screen?" → MENTAL_MODEL + TROUBLESHOOTING (it's almost
+  always software-framebuffer drawing instead of the GBI display-list path).
+- "How does the helper build a display list / kick the RSP?" → `n64.c`
+  (`dl_begin`/`dl_end_and_run`) + the n64brew RDP/RSP pages.
+- "Which VI register sets 16bpp / scaling?" → the core's `vi_controller.h` enum.
+- "disasm returns junk addresses on a multi-function program" → TROUBLESHOOTING (the
+  absolute-`jal` base-alignment note).