romdevtools 0.56.1 → 0.71.0

package/src/host/dc-aica-state.js

@@ -0,0 +1,67 @@
+// Dreamcast AICA sound-chip decode — the "what is each of the 64 PCM channels
+// doing this frame?" view that getAudioState gives the other platforms' chips.
+// Input is the raw AICA register window (Uint8Array) from host.getAicaRegs():
+// 64 channels × 0x80 bytes starting at 0x000, plus CommonData at 0x2800.
+//
+// The AICA is a 64-channel PCM/ADPCM sampler. Canonical per-channel register map
+// (offset within the channel's 0x80 block), little-endian 16-bit registers:
+//   0x00 : KYONEX(15) KYONB(14) ... LPCTL(9) PCMS(8..7) SA-high(6..0)
+//   0x04 : SA-low (sample start address, low 16)
+//   0x08 : LSA (loop start)            0x0C : LEA (loop end)
+//   0x10 : D2R/D1R/AR (attack/decay)   0x14 : RR/DL/KRS/LS (release/sustain)
+//   0x18 : LPSLNK / OCT / FNS (pitch: OCT bits 14..11 signed, FNS bits 9..0)
+//   0x24 : DISDL (direct send level, bits 11..8) / DIPAN (pan, bits 4..0)
+// CommonData (0x2800): 0x00 MVOL (master volume, bits 3..0) + MONO/MEM8MB/etc.
+
+const CH_STRIDE = 0x80;
+const NUM_CH = 64;
+const COMMON = 0x2800;
+
+/**
+ * @param {Uint8Array|null} reg  the AICA register window from getAicaRegs()
+ * @returns {{ chip:"aica", masterVolume:number, voices:Array<object>,
+ *   activeVoices:number } | null}
+ */
+export function decodeAica(reg) {
+  if (!reg || reg.length < COMMON + 2) return null;
+  const u16 = (o) => (reg[o] | (reg[o + 1] << 8)) & 0xffff;
+
+  const voices = [];
+  let active = 0;
+  for (let c = 0; c < NUM_CH; c++) {
+    const base = c * CH_STRIDE;
+    if (base + 0x28 > reg.length) break;
+    const play = u16(base + 0x00);
+    const keyOn = !!(play & 0x4000);       // KYONB
+    const loop = !!(play & 0x0200);        // LPCTL
+    const pcms = (play >> 7) & 0x3;         // 0/1 = 16/8-bit PCM, 2 = ADPCM
+    const saHi = play & 0x7f;
+    const saLo = u16(base + 0x04);
+    const sampleAddr = ((saHi << 16) | saLo) >>> 0;
+    const lsa = u16(base + 0x08);
+    const lea = u16(base + 0x0c);
+    const pitch = u16(base + 0x18);
+    const oct = (pitch >> 11) & 0xf;        // signed 4-bit
+    const fns = pitch & 0x3ff;
+    const env = u16(base + 0x24);
+    const disdl = (env >> 8) & 0xf;         // direct send level (volume)
+    const dipan = env & 0x1f;               // pan
+    if (keyOn && disdl > 0) active++;
+    voices.push({
+      ch: c,
+      keyOn,
+      loop,
+      format: pcms === 2 ? "ADPCM" : (pcms === 1 ? "PCM8" : "PCM16"),
+      sampleAddr: "$" + sampleAddr.toString(16).toUpperCase(),
+      loopStart: lsa,
+      loopEnd: lea,
+      octave: oct >= 8 ? oct - 16 : oct,    // 4-bit signed
+      fns,
+      volume: disdl,                         // 0..15 direct send level
+      pan: dipan,
+    });
+  }
+
+  const mvol = u16(COMMON + 0x00) & 0xf;
+  return { chip: "aica", masterVolume: mvol, activeVoices: active, voices };
+}

package/src/mcp/tools/audio.js

@@ -367,7 +367,7 @@ export function registerAudioTools(server, z, sessionKey) {
     "sampled SFX fire' on Genesis is still record-and-FFT.",
     {
       op: z.enum(["inspect", "record"]).describe("inspect a sound chip's live state (single-frame, or a frames trace); or record audio to a WAV."),
-      chip: z.enum(["nes", "gb", "gba", "dsp", "psg", "ym2612", "sid", "mikey", "pce", "ay8910"]).optional().describe("op=inspect: which sound chip to decode (all 14 systems mapped)."),
+      chip: z.enum(["nes", "gb", "gba", "dsp", "psg", "ym2612", "sid", "mikey", "pce", "ay8910", "spu", "ai", "aica"]).optional().describe("op=inspect: which sound chip to decode. Tile systems: nes/gb/gba/dsp(SNES)/psg(SN76489)/ym2612(Genesis FM)/sid(C64)/mikey(Lynx)/pce/ay8910(MSX). 3D systems: spu (PS1, 24 ADPCM voices), ai (N64 AI output), aica (Dreamcast, 64 PCM/ADPCM channels)."),
       frames: z.number().int().min(1).max(60000).optional().describe("op=record: emulator frames to capture (default 180 = 3s NTSC). op=inspect: if set, TRACE the chip over N frames into a per-channel timeline; OMIT for a single-frame snapshot."),
       sampleEvery: z.number().int().min(1).default(1).describe("op=inspect trace: sample the chip only every Nth frame (thins a long trace; the last frame is always sampled). Changes on skipped frames surface at the next sampled frame, so >1 loses fine timing — keep at 1 to catch every transition."),
       path: z.string().optional().describe("op=record: absolute path to write the WAV (required for record)."),

package/src/mcp/tools/disasm.js

@@ -1461,7 +1461,7 @@ export function registerDisasmTools(server, z) {
     "read/write); also walks the vector table. Banked carts are scanned PER BANK (all of the formats above) — " +
     "refs carry `prgBank` (NES) / `romBank` (everything else). LIMITATION: direct addressing only " +
     "(indirect/computed jumps are missed).\n" +
-    "── RE ENGINE (Rizin + Ghidra, all 14 platforms) ──\n" +
+    "── RE ENGINE (Rizin + Ghidra, all platforms incl. the 3D CPUs: MIPS R3000/R4300 + SH-4) ──\n" +
     "'functions' = Rizin auto-detected function list {address,size,nbbs,cc,callers,callees,looksLikeData}; the " +
     "structural map of an unknown ROM. Sorted REAL CODE FIRST (by nbbs/cc) — don't rank by `size`, which is a lie " +
     "(rizin folds data tables into giant pseudo-functions). `looksLikeData:true` (and the top-level `dataCount`) flags " +

package/src/mcp/tools/index.js

@@ -155,7 +155,7 @@ const CATEGORIES = [
   },
   {
     name: "debug",
-    description: "Cross-platform debugging + reverse-engineering: inspectSprites, inspectPalette, getCPUState (main/spc700/z80), getAudioState (dsp/psg/ym2612), and the disasm/RE engine — disassemble (raw/ROM/rebuildable-project), plus the Rizin/Ghidra ops disasm({target:'cfg'|'xrefs'|'functions'|'decompile'}) (control-flow graphs, deep xrefs, auto-detected functions, and C pseudocode — all 14 platforms) and symbols({op:'analyze'}) (one-shot structural map).",
+    description: "Cross-platform debugging + reverse-engineering: inspectSprites, inspectPalette, getCPUState (main/spc700/z80, plus the 3D CPUs: MIPS R3000/R4300, SH-4), getAudioState (dsp/psg/ym2612/… + spu/ai/aica for PS1/N64/Dreamcast), and the disasm/RE engine — disassemble (raw/ROM/rebuildable-project), plus the Rizin/Ghidra ops disasm({target:'cfg'|'xrefs'|'functions'|'decompile'}) (control-flow graphs, deep xrefs, auto-detected functions, and C pseudocode) and symbols({op:'analyze'}) (one-shot structural map).",
     useWhen: ["sprites rendering wrong", "audio silent or distorted", "CPU stuck in unknown state", "need to read what existing ROM bytes do", "reverse-engineering an unknown ROM — carve its functions/structure before labeling them live", "want C-like pseudocode to understand a routine"],
     register: (s, z, k) => {
       registerPlatformSpecificTools(s, z, k); // inspectSprites/Palette, getCPUState, getDspState, ...

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

@@ -70,7 +70,7 @@ export async function listPlatformDocsCore({ platform }) {
         docs,
         note: docs.length === 0
           ? `No docs shipped for '${platform}' yet. Try a different platform, or fork an example game (examples({op:'fork'})) for boilerplate. (For RE/patching workflow, see platform({op:'doc', platform:'romhacking', name:'playbook'}).)`
-          : `Call platform({op:'doc', platform, name}) to read one. 'name' is 'mental_model' or 'troubleshooting'. For RE/patching workflow across platforms, see platform({op:'doc', platform:'romhacking', name:'playbook'}).`,
+          : `Call platform({op:'doc', platform, name}) to read one. 'name' is 'mental_model', 'troubleshooting', or 'upstream_sources' (whichever this platform ships — see the docs[] list above). For RE/patching workflow across platforms, see platform({op:'doc', platform:'romhacking', name:'playbook'}).`,
       };
 }
 

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/project.js

@@ -646,6 +646,22 @@ const TEMPLATES = {
       },
     };
   })(),
+
+  // ── Sega Dreamcast (sh-elf-gcc SH-4) — bare PowerVR2 framebuffer via the bundled
+  // dc.h helper; the output ELF boots DIRECTLY on Flycast's reios HLE BIOS (no GD-ROM
+  // image, no firmware) and renders on the real GPU through native-gles. dc.h is
+  // auto-bundled by the toolchain, so the example is a single main.c. No KallistiOS
+  // and no genre scaffolds yet — `hello` is the verified renderable starting point. ──
+  dreamcast: {
+    default: { main: "hello/main.c", runtime: [], lang: "C (sh-elf-gcc)", ext: ".elf",
+      describe: "DCHELLO — the canonical Dreamcast starter: bring up the PowerVR2 640x480 RGB565 framebuffer (via the auto-bundled dc.h: FB_R_CTRL/SIZE/SOF1 + SPG) and paint a test pattern (dark-blue field, red/green/blue bars, white frame). Proves the SH-4 build → Flycast reios HLE boot → native-gles GPU render pipeline end-to-end. The base to grow your own DC graphics from. Same as 'hello'." },
+    hello: { main: "hello/main.c", runtime: [], lang: "C (sh-elf-gcc)", ext: ".elf",
+      describe: "DCHELLO — a minimal Dreamcast homebrew. dc_video_init() programs the PowerVR2 framebuffer registers for 640x480 RGB565 at VRAM 0xA5000000; then dc_clear/dc_rect paint a recognizable pattern. Boots directly on Flycast's reios HLE BIOS (no firmware) and presents through native-gles with flycast_emulate_framebuffer — no TA display list needed.",
+      players: "1 (Dreamcast has 4 controller ports; the bare path doesn't wire the Maple bus yet)",
+      sram: "none in this starter — DC saves go to the VMU via the Maple bus; not wired in the bare path.",
+      mechanics: ["direct framebuffer paint (clear + solid rects)", "recognizable test pattern"],
+      techniques: ["PowerVR2 framebuffer bring-up (FB_R_CTRL/FB_R_SIZE/FB_R_SOF1 + SPG)", "640x480 RGB565 at VRAM 0xA5000000", "SH-4 bare crt0 (stack + .bss + main)", "boots on Flycast reios HLE — no firmware"] },
+  },
 };
 // R37: GBC has its own scaffold tree at examples/gbc/templates/ +
 // src/platforms/gbc/lib/c/. Same runtime files as GB (the APU + Z80 +

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/`.