romdevtools 0.70.0 → 0.71.1

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

@@ -93,9 +93,17 @@ const PLATFORM_QUIRKS = {
 };
 
 /** op:'list' — every platform with core/toolchains/languages/quirks. */
-export function listPlatformsCore() {
+export function listPlatformsCore({ platform, slim } = {}) {
       const available = new Set(listAvailableCores());
-      const platforms = Object.entries(CORES).map(([id, info]) => {
+      let ids = Object.keys(CORES);
+      if (platform) {
+        if (!CORES[platform]) {
+          throw new Error(`platform({op:'list'}): unknown platform '${platform}'. Known: ${ids.join(", ")}.`);
+        }
+        ids = [platform]; // per-platform filter — the big token-sink fix (v0.71.0 fb)
+      }
+      const platforms = ids.map((id) => {
+        const info = CORES[id];
         const toolchains = Object.values(TOOLCHAINS)
           .filter((t) => t.platforms.includes(id))
           .map((t) => ({ id: t.id, displayName: t.displayName, tier: t.tier }));
@@ -107,18 +115,45 @@ export function listPlatformsCore() {
           toolchains,
         };
         const langs = getLanguageOptions(id);
-        if (langs) entry.languages = langs;
-        if (PLATFORM_QUIRKS[id]) entry.quirks = PLATFORM_QUIRKS[id];
+        if (langs) {
+          // `slim` drops the heavy per-language `note` + `quirks` prose (the big
+          // token sink when you only need "which platforms/toolchains/languages
+          // exist"). Detail stays behind platform({op:'doc'}) + op:'capabilities'.
+          entry.languages = slim
+            ? { defaultLanguage: langs.defaultLanguage,
+                languages: (langs.languages || []).map((l) => ({ language: l.language, toolchain: l.toolchain, available: l.available })) }
+            : langs;
+        }
+        if (!slim && PLATFORM_QUIRKS[id]) entry.quirks = PLATFORM_QUIRKS[id];
         return entry;
       });
-      return { platforms };
+      // A single-platform query returns just that row (not wrapped in `platforms[]`).
+      return platform ? platforms[0] : { platforms };
 }
 
-/** op:'resolve' — resolved core paths for a platform (debugging aid). */
+/** op:'resolve' — resolved core paths + the toolchain summary for a platform. */
 export function resolvePlatformCore({ platform }) {
       const r = resolveCore(platform);
       if (!r) throw new Error(`no core available for platform '${platform}'`);
-      return r;
+      // Also surface the toolchain(s) — resolve used to report only the emulator
+      // core, so agents had to spelunk node_modules to learn the build path (v0.71.0
+      // fb #3). We do NOT hand out the WASM/.mjs artifact paths: those tools run ONLY
+      // inside romdev's `build` worker harness (virtual FS), so a node_modules path
+      // invites the wrong mental model (shimming them into an external Makefile —
+      // which does NOT work). The `note` states that plainly (fb #4/#5).
+      const toolchains = Object.values(TOOLCHAINS)
+        .filter((t) => t.platforms.includes(platform))
+        .map((t) => ({ id: t.id, displayName: t.displayName, tier: t.tier }));
+      return {
+        ...r,
+        toolchains,
+        toolchainNote:
+          "Build via the `build` tool (it compiles a source set into one ROM). The toolchain " +
+          "binaries are WASM, run ONLY inside romdev's build worker (virtual FS) — they are NOT " +
+          "host-callable and CANNOT back an external project's Makefile. For an existing decomp/" +
+          "romhack that needs its own legacy compiler (e.g. agbcc) + Makefile, build it on the host " +
+          "and use romdev to run/inspect/debug the resulting ROM.",
+      };
 }
 
 export function registerPlatformTools(server, z) {
@@ -142,14 +177,15 @@ export function registerPlatformTools(server, z) {
     "troubleshooting / upstream_sources; `platform:'romhacking'` + `name:'playbook'` for the RE decision tree). " +
     "Read MENTAL_MODEL before writing code, and the romhacking playbook before a hack.",
     {
-      op: z.enum(["list", "capabilities", "resolve", "toolchains", "docs", "doc"]).describe("list=platforms; capabilities=per-platform op support matrix; resolve=core paths; toolchains; docs=a platform's doc names; doc=read one doc."),
-      platform: z.string().optional().describe("op=resolve/docs/doc: platform id (e.g. nes, gb, genesis; 'romhacking' for the RE playbook)."),
+      op: z.enum(["list", "capabilities", "resolve", "toolchains", "docs", "doc"]).describe("list=platforms (pass `platform` to get just ONE, `slim:true` to drop the verbose notes); capabilities=per-platform op support matrix; resolve=core + toolchain artifact paths; toolchains; docs=a platform's doc names; doc=read one doc."),
+      platform: z.string().optional().describe("op=list/resolve/docs/doc/capabilities: platform id (e.g. nes, gb, genesis; 'romhacking' for the RE playbook). On op=list it filters to that ONE platform's row instead of the whole matrix (big token saver)."),
+      slim: z.boolean().optional().describe("op=list: drop the heavy per-language `note` + `quirks` prose; return just {platform, toolchains[], languages{defaultLanguage,…}}. Detail stays behind op:'doc' / op:'capabilities'."),
       id: z.string().optional().describe("op=toolchains: a specific toolchain's install status (e.g. 'cc65')."),
       name: z.string().optional().describe("op=doc: which doc — mental_model | troubleshooting | upstream_sources | playbook."),
     },
     safeTool(async (args) => {
       switch (args.op) {
-        case "list":    return jsonContent(listPlatformsCore());
+        case "list":    return jsonContent(listPlatformsCore({ platform: args.platform, slim: args.slim }));
         case "capabilities": {
           if (args.platform) {
             const cap = capabilitiesFor(args.platform);

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,57 @@ 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) OR is nested (e.g. src/main.c — common for decomps/SDK projects).
+  // Accept a project-relative path or a bare name; it becomes the single entry
+  // source. Resolve against BOTH the top-level files AND the recursively staged
+  // subdir set, with POSIX slashes (`path.normalize` may emit `\` on Windows).
+  const entryName = opts.entry
+    ? path.normalize(opts.entry).replace(/\\/g, "/").replace(/^[./]+/, "")
+    : null;
+  // The resolved {rel, abs} for the entry when it's nested in a subdirectory.
+  let entrySubAsset = null;
+  if (entryName) {
+    const topMatch = files.some((f) => f.name === entryName);
+    entrySubAsset = subAssets.find((a) => a.rel === entryName) || null;
+    // Bare-filename fallback: `entry:'main.c'` matches `src/main.c` if unique.
+    if (!topMatch && !entrySubAsset && !entryName.includes("/")) {
+      const byBase = subAssets.filter((a) => a.rel.split("/").pop() === entryName);
+      if (byBase.length === 1) entrySubAsset = byBase[0];
+    }
+    if (!topMatch && !entrySubAsset) {
+      const nearby = subAssets
+        .filter((a) => a.rel.split("/").pop() === entryName.split("/").pop())
+        .map((a) => a.rel).slice(0, 8);
+      throw new Error(
+        `entry '${entryName}' not found in ${projPath}. ` +
+        (nearby.length
+          ? `Did you mean: ${nearby.join(", ")}? (entry is project-relative — e.g. 'src/main.c'.)`
+          : `Top-level: ${files.map((f) => f.name).join(", ") || "(none)"}. ` +
+            `entry is project-relative — pass the path under the repo root (e.g. 'src/main.c').`)
+      );
+    }
+  }
+
   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 +1023,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 ASM 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 +1052,27 @@ 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 === entrySubAsset?.rel) 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");
+    }
+  }
+
+  // A NESTED entry (e.g. src/main.c) is read here as the entry SOURCE — the
+  // top-level loop above only sees root files, so a subdir entry would otherwise
+  // never compile. Keyed by its relative path so #include/.include resolution
+  // from the same subdir works.
+  if (entrySubAsset) {
+    sources[entrySubAsset.rel] = (await readFile(entrySubAsset.abs)).toString("utf-8");
+  }
+
   // 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 +1092,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 +1141,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/gba/MENTAL_MODEL.md

@@ -248,6 +248,11 @@ Loadable via mGBA (`loadMedia`).
 
 ## What's NOT bundled
 
+- **`agbcc` (the legacy GBA compiler).** romdev's GBA C path is **modern
+  `arm-none-eabi-gcc` 14.2.0** only. The byte-exact decompilations + romhacks
+  (pokeruby / pokeemerald / pokefirered, etc.) build with agbcc + a custom
+  `ld_script.txt`, so romdev **cannot reproduce a matching retail ROM** for those.
+  That's a hard limit, not a missing feature — see "romdev's build model" below.
 - **libgba's `console.c`** (iprintf-style stdio output). Pulls in
   devkitPro's libsysbase header chain — not yet ported. See
   TROUBLESHOOTING.md for the trade-off rationale and workarounds.
@@ -256,7 +261,23 @@ Loadable via mGBA (`loadMedia`).
 - **devkitARM's `bin2s`** (binary → assembly converter for asset
   pipelines). Not bundled; ship binary assets as C arrays for now.
 
-Everything else from a stock devkitARM install works.
+Everything else from a stock devkitARM install (homebrew-style) works.
+
+## romdev's build model (read this before driving an existing project)
+
+`build` is a **single-shot "compile these sources → one ROM" tool**, NOT an arbitrary
+build-system backend. The toolchain binaries are **WASM, run only inside romdev's build
+worker (virtual FS)** — they are **not host-callable** and **cannot back an external
+project's `Makefile`** as `$(TOOLCHAIN)/bin`. (The `.mjs` wrappers under `node_modules`
+export a worker factory, not a CLI `main` — invoking one directly exits 0 and writes
+nothing.)
+
+So for an **existing decomp/romhack** (agbcc-era or any project with its own Makefile):
+build it **on the host** with its own toolchain, then point romdev at the resulting
+`.gba` for the run / inspect / debug / decompile loop. Confirmed host recipe for the
+Pokémon Gen-III decomps: `brew install arm-none-eabi-gcc arm-none-eabi-binutils`, clone
+`pret/agbcc` → `./build.sh` → `./install.sh <repo>`, then `make <target>` (yields a
+byte-matching ROM). romdev's value here is everything AFTER the build, not the build.
 
 ## Horizontal scrolling (for side-scrollers)