romdev-mcp 0.1.1

package/src/toolchains/cc65/presets/nes/chr-ram-runtime.crt0.s

@@ -0,0 +1,178 @@
+; Minimal crt0 for NES CHR-RAM mode + nes_runtime NMI handler.
+;
+; Replaces cc65's stock crt0 so we avoid the .forceimport NESfont
+; (which targets the CHARS segment that our chr-ram.cfg removes) AND
+; the ringbuf/ppubuf NMI machinery (which presumes the cc65 console
+; subsystem that game code rarely uses).
+;
+; The NMI handler here is the canonical sprite-engine sequence:
+;   1. preserve A/X/Y
+;   2. OAM DMA: write $02 → $4014 (copies shadow_oam[256] @ $0200 → PPU OAM)
+;   3. flush the VRAM queue (vram_queue_flush, exported by nes_runtime.c)
+;   4. write deferred palette ($3F00) updates if pending
+;   5. reset PPUADDR ($2006) to $2000 + PPUSCROLL ($2005) to (scroll_x, scroll_y)
+;   6. write PPUCTRL ($2000) with NMI enabled + base nametable bits
+;   7. increment nmi_counter so `ppu_wait_nmi()` can return
+;   8. restore A/X/Y, rti
+;
+; Loaded silently by the linkerConfig:"chr-ram" preset.
+
+        .export         _exit
+        .export         __STARTUP__ : absolute = 1
+        .export         start
+        .export         nmi
+        .export         irq
+        .export         _shadow_oam
+
+        .import         initlib, donelib, callmain
+        .import         _main, zerobss, copydata
+        .import         __RAM_START__, __RAM_SIZE__
+        .import         __SRAM_START__, __SRAM_SIZE__
+        .import         _vram_queue_flush
+        .import         _scroll_x, _scroll_y, _ppuctrl_value, _nmi_counter
+        .importzp       c_sp
+
+; ------------------------------------------------------------------------
+; 16-byte iNES header — CHR-RAM (byte 5 = 0).
+
+.segment "HEADER"
+        .byte   $4e, $45, $53, $1a   ; "NES" + EOF
+        .byte   2                    ; PRG-ROM banks (16K each) → 32K
+        .byte   0                    ; CHR-ROM banks (8K each)  → 0 = CHR-RAM
+        .byte   %00000001            ; flags6 — vertical mirroring
+        .byte   %00000000            ; flags7 — mapper hi nybble
+        .byte   0, 0, 0, 0, 0, 0, 0, 0
+
+; ------------------------------------------------------------------------
+.segment "STARTUP"
+
+start:
+        sei
+        cld
+        ldx     #$ff
+        txs
+
+        ; Disable everything that could fire during init.
+        lda     #0
+        sta     $2000           ; disable NMI
+        sta     $2001           ; disable rendering
+        sta     $4010           ; disable DMC IRQ
+        sta     $4015           ; disable APU channels
+        bit     $2002           ; clear vblank flag
+
+        ; Wait two VBlanks before touching the PPU (standard NES init).
+@vbl1:  bit     $2002
+        bpl     @vbl1
+@vbl2:  bit     $2002
+        bpl     @vbl2
+
+        ; Initialise shadow_oam to Y=$FF (off-screen) before anything else.
+        ldx     #0
+        lda     #$ff
+@oam:   sta     _shadow_oam,x   ; only Y bytes need to be $FF, but writing
+        inx                     ; all 256 bytes is faster than the modulo-4
+        bne     @oam            ; trick and BSS is already zero anyway.
+
+        ; Clear CHR-RAM ($0000-$1FFF on PPU bus) so tile 0 is blank.
+        ; Power-on CHR-RAM is uninitialised garbage — leaving it that way
+        ; means BG tile 0 renders as random nonsense even if the game
+        ; never wrote a nametable. 8 KB / 256 = 32 outer iterations.
+        lda     #0
+        sta     $2006           ; PPUADDR hi = $00
+        sta     $2006           ; PPUADDR lo = $00
+        ldx     #32             ; 32 × 256 = 8192 bytes
+        ldy     #0
+@chrclr_outer:
+@chrclr_inner:
+        sta     $2007
+        iny
+        bne     @chrclr_inner
+        dex
+        bne     @chrclr_outer
+        bit     $2002           ; reset PPUADDR latch
+        lda     #$3F
+        sta     $2006
+        lda     #$00
+        sta     $2006           ; PPUADDR back at $3F00 ready for caller
+
+        ; Clear BSS + copy DATA (cc65 conventions).
+        jsr     zerobss
+        jsr     copydata
+
+        ; Set up cc65's C parameter stack pointer.
+        lda     #<(__SRAM_START__ + __SRAM_SIZE__)
+        ldx     #>(__SRAM_START__ + __SRAM_SIZE__)
+        sta     c_sp
+        stx     c_sp+1
+
+        jsr     initlib
+        jsr     callmain
+
+_exit:  jsr     donelib
+        jmp     start
+
+; ------------------------------------------------------------------------
+; NMI handler — runs every vblank when ppuctrl bit 7 is set.
+
+.segment "STARTUP"
+
+nmi:
+        pha
+        txa
+        pha
+        tya
+        pha
+
+        ; OAM DMA: copy 256 bytes from $0200 to PPU OAM. Takes 513 cycles.
+        lda     #$00
+        sta     $2003           ; PPU OAMADDR = 0
+        lda     #$02            ; high byte of $0200
+        sta     $4014           ; PPU OAMDMA — kicks off the copy
+
+        ; Flush the VRAM queue (writes anything game code stashed via
+        ; vram_set / tile_set / tile_set_palette). PPU is unlocked here.
+        jsr     _vram_queue_flush
+
+        ; Reset PPUADDR to $2000 (otherwise the queue's last $2006 write
+        ; leaves it dangling and the PPU samples random VRAM as the BG).
+        bit     $2002
+        lda     #$20
+        sta     $2006
+        lda     #$00
+        sta     $2006
+
+        ; Set scroll. _scroll_x / _scroll_y are byte globals exported by
+        ; nes_runtime.c; ppu_scroll() writes them. PPUSCROLL takes two
+        ; writes (x then y).
+        lda     _scroll_x
+        sta     $2005
+        lda     _scroll_y
+        sta     $2005
+
+        ; Re-enable NMI + set base nametable + sprite/bg pattern table bits
+        ; via the runtime's cached PPUCTRL value.
+        lda     _ppuctrl_value
+        sta     $2000
+
+        ; Tick the frame counter so ppu_wait_nmi can return.
+        inc     _nmi_counter
+
+        pla
+        tay
+        pla
+        tax
+        pla
+        rti
+
+irq:    rti
+
+; ------------------------------------------------------------------------
+; Shadow OAM at $0200 — the NMI handler DMAs this to the PPU each frame.
+.segment "OAM"
+_shadow_oam: .res 256
+
+; ------------------------------------------------------------------------
+.segment "VECTORS"
+        .word   nmi             ; $FFFA
+        .word   start           ; $FFFC
+        .word   irq             ; $FFFE

package/src/toolchains/cc65/presets/nes/chr-ram.cfg

@@ -0,0 +1,76 @@
+# NES CHR-RAM linker config preset for romdev.
+#
+# DIFFERENCE FROM DEFAULT nes.cfg:
+#   - HEADER's iNES byte 5 (CHR-ROM bank count) is set to 0 via the
+#     project's own HEADER segment (the project must supply HEADER).
+#     We don't ship HEADER bytes here because cc65's stock crt0.s emits
+#     them — and pulling in stock crt0 also pulls in NESfont (4KB CHARS).
+#     So this preset is meant to be used WITH a custom header source
+#     that defines .segment "HEADER" + provides chr=0 bytes.
+#   - ROM2 (8K CHR ROM bank) is REMOVED. Pattern tables live in CHR-RAM
+#     ($0000-$1FFF on the PPU bus) and are written by your game at
+#     runtime. There is no CHARS segment.
+#
+# To use this preset:
+#   1. linkerConfig: "chr-ram" on buildSource
+#   2. Supply your own crt0/header source that writes the 16-byte iNES
+#      header with byte 5 = 0. Easiest: paste the snippet
+#      getStarterSnippet({platform:"nes", name:"chr_ram_header", language:"asm"}).
+#   3. Write CHR data from C at runtime: PPUADDR = 0x00; PPUDATA = byte; etc.
+
+SYMBOLS {
+    __STACKSIZE__: type = weak, value = $0300;
+}
+MEMORY {
+    ZP:     file = "", start = $0002, size = $001A, type = rw, define = yes;
+
+    # INES Cartridge Header — provided by your project (HEADER segment).
+    HEADER: file = %O, start = $0000, size = $0010, fill = yes;
+
+    # PRG-ROM: 2 × 16K = 32K (NROM-256 style; covers most projects).
+    ROM0:   file = %O, start = $8000, size = $7FFA, fill = yes, define = yes;
+
+    # Hardware vectors at end of PRG.
+    ROMV:   file = %O, start = $FFFA, size = $0006, fill = yes;
+
+    # NO ROM2 / CHARS — this is the whole point of the CHR-RAM preset.
+
+    SRAM:   file = "", start = $0500, size = __STACKSIZE__, define = yes;
+
+    # BSS / DATA live in real RAM ($0300-$04FF, 512 bytes). NROM (mapper 0)
+    # with no battery has $6000-$7FFF UNMAPPED — reads return open bus.
+    # 512 bytes is plenty for tiny NROM carts; for more, use a mapper preset.
+    RAM:    file = "", start = $0300, size = $0200, define = yes;
+
+    # Shadow OAM at $0200 (page 2). Game code populates this, NMI handler
+    # DMAs it to PPU sprite RAM via $4014. 256 bytes = 64 sprites × 4.
+    OAM:    file = "", start = $0200, size = $0100;
+}
+SEGMENTS {
+    ZEROPAGE: load = ZP,              type = zp;
+    HEADER:   load = HEADER,          type = ro;
+    STARTUP:  load = ROM0,            type = ro,  define   = yes;
+    LOWCODE:  load = ROM0,            type = ro,  optional = yes;
+    ONCE:     load = ROM0,            type = ro,  optional = yes;
+    CODE:     load = ROM0,            type = ro,  define   = yes;
+    RODATA:   load = ROM0,            type = ro,  define   = yes;
+    DATA:     load = ROM0, run = RAM, type = rw,  define   = yes;
+    VECTORS:  load = ROMV,            type = rw;
+    BSS:      load = RAM,             type = bss, define   = yes;
+    OAM:      load = OAM,             type = bss, optional = yes;
+}
+FEATURES {
+    CONDES: type    = constructor,
+            label   = __CONSTRUCTOR_TABLE__,
+            count   = __CONSTRUCTOR_COUNT__,
+            segment = ONCE;
+    CONDES: type    = destructor,
+            label   = __DESTRUCTOR_TABLE__,
+            count   = __DESTRUCTOR_COUNT__,
+            segment = RODATA;
+    CONDES: type    = interruptor,
+            label   = __INTERRUPTOR_TABLE__,
+            count   = __INTERRUPTOR_COUNT__,
+            segment = RODATA,
+            import  = __CALLIRQ__;
+}

package/src/toolchains/cc65/presets/nes/chr-ram.crt0.s

@@ -0,0 +1,106 @@
+; Minimal crt0 for NES CHR-RAM mode — replaces cc65's stock crt0 so we
+; avoid the .forceimport NESfont (which targets the CHARS segment that
+; our chr-ram.cfg removes) AND the ringbuf/ppubuf NMI machinery (which
+; presumes the cc65 console subsystem that game code rarely uses).
+;
+; This is the BARE preset — you write your own NMI handler and OAM
+; shadow buffer. For a turnkey runtime that does that for you (and
+; matches the nes_runtime.h C API), the build pipeline switches to
+; the `chr-ram-runtime` preset automatically when your source
+; `#include`s `nes_runtime.h`.
+;
+; Loaded by linkerConfig:"chr-ram".
+
+        .export         _exit
+        .export         __STARTUP__ : absolute = 1
+
+        .import         initlib, donelib, callmain
+        .import         _main, zerobss, copydata
+        .import         __RAM_START__, __RAM_SIZE__
+        .import         __SRAM_START__, __SRAM_SIZE__
+
+; ------------------------------------------------------------------------
+; 16-byte iNES header — CHR-RAM (byte 5 = 0).
+; If your project supplies its own HEADER segment, delete or override
+; these bytes; ld65 lets multiple .segment "HEADER" contributors coexist
+; only if their bytes don't overlap, so the project must not also emit
+; the 16-byte header.
+
+.segment "HEADER"
+        .byte   $4e, $45, $53, $1a   ; "NES" + EOF
+        .byte   2                    ; PRG-ROM banks (16K each) → 32K
+        .byte   0                    ; CHR-ROM banks (8K each)  → 0 = CHR-RAM
+        .byte   %00000001            ; flags6 — vertical mirroring
+        .byte   %00000000            ; flags7 — mapper hi nybble
+        .byte   0, 0, 0, 0, 0, 0, 0, 0
+
+; ------------------------------------------------------------------------
+.segment "STARTUP"
+
+start:
+        sei
+        cld
+        ldx     #$ff
+        txs
+
+        ; Wait two VBlanks before touching the PPU (standard NES init).
+        lda     #0
+        sta     $2000           ; disable NMI
+        sta     $2001           ; disable rendering
+        sta     $4010           ; disable DMC IRQ
+        bit     $2002           ; clear vblank flag
+
+@vbl1:  bit     $2002
+        bpl     @vbl1
+@vbl2:  bit     $2002
+        bpl     @vbl2
+
+        ; Clear BSS + copy DATA (cc65 conventions).
+        jsr     zerobss
+        jsr     copydata
+
+        ; Set up cc65's C parameter stack pointer.
+        lda     #<(__SRAM_START__ + __SRAM_SIZE__)
+        ldx     #>(__SRAM_START__ + __SRAM_SIZE__)
+        sta     c_sp
+        stx     c_sp+1
+
+        jsr     initlib
+        jsr     callmain
+
+_exit:  jsr     donelib
+        jmp     start
+
+; ------------------------------------------------------------------------
+; Default NMI / IRQ — do nothing. To override with your own handler:
+;   ; in your own .s file:
+;   .export nmi
+;   .import _my_c_handler
+;   nmi:
+;       pha
+;       txa
+;       pha
+;       tya
+;       pha
+;       jsr _my_c_handler       ; void __fastcall__ my_c_handler(void)
+;       pla
+;       tay
+;       pla
+;       tax
+;       pla
+;       rti
+;
+;   ; then DELETE the `nmi: rti` line below from this crt0 (or load a
+;   ; modified crt0 via your own buildSource sources entry).
+
+.segment "STARTUP"
+
+nmi:    rti
+irq:    rti
+
+        .importzp       c_sp
+
+.segment "VECTORS"
+        .word   nmi             ; $FFFA
+        .word   start           ; $FFFC
+        .word   irq             ; $FFFE

package/src/toolchains/common/ar.js

@@ -0,0 +1,121 @@
+// ar.js — pure-JS writer for the GNU `ar` static-library format, WITH the
+// ranlib symbol index. We compile SDK libraries (libtonc/libgba/maxmod/...)
+// FROM SOURCE into loose .o objects, then pack them into a real .a so the
+// linker pulls only referenced members — exactly like a prebuilt .a, and
+// without "multiple definition" collisions from mutually-exclusive members.
+//
+// GNU ld requires the archive symbol index ("archive has no index; run
+// ranlib"), so we parse each ELF object's symbol table and emit the leading
+// "/" index member ourselves. No binutils `ar`/`ranlib` wasm needed.
+//
+// Archive layout:
+//   "!<arch>\n"
+//   "/"  member  → symbol index: u32be count, count×u32be member-header
+//                  offsets, then NUL-terminated symbol names
+//   per object member: 60-byte ASCII header + data (padded to even length)
+
+const MAGIC = "!<arch>\n";
+const HEADER_SIZE = 60;
+
+function arHeader(name, size) {
+  const f = (s, w) => { s = String(s); if (s.length > w) throw new Error(`ar field "${s}" > ${w}`); return s + " ".repeat(w - s.length); };
+  return Buffer.from(
+    f(name, 16) + f("0", 12) + f("0", 6) + f("0", 6) + f("644", 8) + f(size, 10) + "`\n",
+    "ascii",
+  );
+}
+
+// ── Minimal ELF32 little-endian symbol extractor ─────────────────────────
+// Returns the names of GLOBAL/WEAK symbols that this object DEFINES (st_shndx
+// != SHN_UNDEF). These are what the linker indexes to decide which members to
+// pull. (32-bit LE only — our ARM and m68k targets are both ELF32; m68k is
+// big-endian data, handled via the byteorder flag.)
+function definedGlobals(obj) {
+  const le = obj[5] === 1; // EI_DATA: 1 = LE, 2 = BE
+  const dv = new DataView(obj.buffer, obj.byteOffset, obj.byteLength);
+  const u16 = (o) => dv.getUint16(o, le);
+  const u32 = (o) => dv.getUint32(o, le);
+  if (obj[0] !== 0x7f || obj[1] !== 0x45) return []; // not ELF
+  const e_shoff = u32(0x20), e_shentsize = u16(0x2e), e_shnum = u16(0x30);
+
+  // Find .symtab (type 2) and its linked .strtab.
+  let symOff = 0, symSize = 0, symEnt = 0, strSecIdx = 0;
+  for (let i = 0; i < e_shnum; i++) {
+    const sh = e_shoff + i * e_shentsize;
+    if (u32(sh + 4) === 2 /* SHT_SYMTAB */) {
+      symOff = u32(sh + 16); symSize = u32(sh + 20);
+      strSecIdx = u32(sh + 24); symEnt = u32(sh + 36) || 16;
+      break;
+    }
+  }
+  if (!symOff) return [];
+  const strSh = e_shoff + strSecIdx * e_shentsize;
+  const strOff = u32(strSh + 16);
+
+  const names = [];
+  const count = Math.floor(symSize / symEnt);
+  for (let i = 0; i < count; i++) {
+    const s = symOff + i * symEnt;
+    const st_name = u32(s + 0);
+    const st_info = obj[s + 12];
+    const st_shndx = u16(s + 14);
+    const bind = st_info >> 4;           // 1=GLOBAL, 2=WEAK
+    if ((bind === 1 || bind === 2) && st_shndx !== 0 /* SHN_UNDEF */ && st_name !== 0) {
+      // read NUL-terminated name from strtab
+      let p = strOff + st_name, end = p;
+      while (obj[end] !== 0) end++;
+      names.push(Buffer.from(obj.buffer, obj.byteOffset + p, end - p).toString("ascii"));
+    }
+  }
+  return names;
+}
+
+/**
+ * Pack named objects into a GNU ar archive WITH a symbol index.
+ * @param {Record<string, Uint8Array>} members  objName → object bytes
+ * @returns {Uint8Array}
+ */
+export function packAr(members) {
+  const entries = Object.entries(members).map(([rawName, bytes]) => {
+    const name = (rawName.endsWith("/") ? rawName : rawName + "/");
+    if (name.length > 16) throw new Error(`ar member name too long: "${rawName}"`);
+    const data = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    return { name, data, syms: definedGlobals(bytes) };
+  });
+
+  // Build the symbol index payload to learn its size (offsets depend on it).
+  const symList = [];
+  for (let i = 0; i < entries.length; i++) {
+    for (const s of entries[i].syms) symList.push({ sym: s, member: i });
+  }
+  const nameBlob = Buffer.from(symList.map((e) => e.sym).join("\0") + (symList.length ? "\0" : ""), "ascii");
+  let indexBody = 4 + symList.length * 4 + nameBlob.length;
+  if (indexBody % 2 === 1) indexBody++; // padded to even
+  const indexMemberTotal = HEADER_SIZE + indexBody;
+
+  // Compute each member's header offset (after magic + index member).
+  let pos = MAGIC.length + indexMemberTotal;
+  const memberOffset = [];
+  for (const e of entries) {
+    memberOffset.push(pos);
+    let dataLen = e.data.length;
+    if (dataLen % 2 === 1) dataLen++;
+    pos += HEADER_SIZE + dataLen;
+  }
+
+  // Serialize the index body: u32be count, u32be offsets, name blob, pad.
+  const idx = Buffer.alloc(indexBody);
+  idx.writeUInt32BE(symList.length, 0);
+  for (let i = 0; i < symList.length; i++) {
+    idx.writeUInt32BE(memberOffset[symList[i].member], 4 + i * 4);
+  }
+  nameBlob.copy(idx, 4 + symList.length * 4);
+
+  // Assemble.
+  const chunks = [Buffer.from(MAGIC, "ascii"), arHeader("/", indexBody), idx];
+  for (const e of entries) {
+    chunks.push(arHeader(e.name, e.data.length), e.data);
+    if (e.data.length % 2 === 1) chunks.push(Buffer.from("\n", "ascii"));
+  }
+  return new Uint8Array(Buffer.concat(chunks));
+}

package/src/toolchains/common/sdk-cache.js

@@ -0,0 +1,116 @@
+// sdk-cache.js — "prebuilt seed + opt-in rebuild" for SDK libraries.
+//
+// Compiling a whole SDK (libtonc, SGDK, pvsneslib) from source on every build
+// is slow on the FIRST build of a process (GBA ~42s, Genesis ~18s). But linking
+// a prebuilt black-box .a is the trust problem we removed. The compromise:
+//
+//   - Ship a prebuilt SEED .a derived from the vendored source (fast default).
+//   - Let the caller pass `rebuildSdk:true` to compile the SDK from source
+//     instead (slow once, then disk-cached by source hash).
+//   - The seed is reproducible from the shipped source — nobody is forced to
+//     trust it; they can rebuild and byte-compare.
+//   - If the vendored source no longer matches the seed (the agent edited it)
+//     AND they didn't ask for a rebuild, we still use the fast seed but return
+//     a loud `sdkEditIgnored` warning naming the changed file — so an edit is
+//     never SILENTLY dropped (the trap we eliminated stays eliminated).
+//
+// This module is platform-agnostic: each toolchain passes in how to hash its
+// source, where its seed lives, and how to compile from source.
+
+import { readFile, writeFile, mkdir, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import os from "node:os";
+
+/** Stable hash of a {name: text|bytes} source map (order-independent). */
+export function hashSources(srcMap) {
+  const h = createHash("sha256");
+  for (const name of Object.keys(srcMap).sort()) {
+    const v = srcMap[name];
+    h.update(name);
+    h.update("\0");
+    h.update(typeof v === "string" ? v : Buffer.from(v));
+    h.update("\0");
+  }
+  return h.digest("hex");
+}
+
+// On-disk cache for rebuilt-from-source archives, so a `rebuildSdk` result is
+// reused across processes/sessions (not just within one). Keyed by source hash.
+function cacheDir() {
+  return path.join(os.tmpdir(), "romdev-sdk-cache");
+}
+async function readDiskCache(key) {
+  try { return new Uint8Array(await readFile(path.join(cacheDir(), key + ".a"))); }
+  catch { return null; }
+}
+async function writeDiskCache(key, bytes) {
+  try {
+    await mkdir(cacheDir(), { recursive: true });
+    await writeFile(path.join(cacheDir(), key + ".a"), bytes);
+  } catch { /* cache is best-effort */ }
+}
+
+/**
+ * Resolve an SDK archive for a build, honoring the seed/rebuild policy.
+ *
+ * @param {Object} a
+ * @param {string} a.name          SDK name (for messages), e.g. "libtonc"
+ * @param {Record<string,string>} a.sources  the vendored SDK source map (for hashing)
+ * @param {string} a.seedPath       absolute path to the prebuilt seed .a
+ * @param {string} a.seedHashPath   absolute path to the seed's source-hash file
+ * @param {boolean} a.rebuild       caller asked to compile from source
+ * @param {() => Promise<{ok:boolean, archive?:Uint8Array, stage?:string, log?:string}>} a.compileFromSource
+ * @returns {Promise<{ok:boolean, archive?:Uint8Array, fromSource:boolean,
+ *   sdkEditIgnored?:{sdk:string, message:string}, stage?:string, log?:string}>}
+ */
+export async function resolveSdkArchive(a) {
+  const srcHash = hashSources(a.sources);
+
+  // Explicit rebuild → compile from source (disk-cached by hash).
+  if (a.rebuild) {
+    // When writeSeed is set (the seed generator), always recompile + persist
+    // the seed; don't short-circuit on the disk cache.
+    if (!a.writeSeed) {
+      const cached = await readDiskCache(srcHash);
+      if (cached) return { ok: true, archive: cached, fromSource: true };
+    }
+    const r = await a.compileFromSource();
+    if (!r.ok) return { ok: false, fromSource: true, stage: r.stage, log: r.log };
+    await writeDiskCache(srcHash, r.archive);
+    if (a.writeSeed && a.seedPath) {
+      await writeFile(a.seedPath, r.archive);
+      await writeFile(a.seedHashPath, srcHash + "\n");
+    }
+    return { ok: true, archive: r.archive, fromSource: true };
+  }
+
+  // Default → use the prebuilt seed.
+  let seed = null;
+  try { seed = new Uint8Array(await readFile(a.seedPath)); } catch { /* no seed */ }
+
+  // Compare the seed's source-hash to the current vendored source.
+  let seedHash = null;
+  try { seedHash = (await readFile(a.seedHashPath, "utf-8")).trim(); } catch { /* no hash */ }
+
+  if (seed) {
+    const edited = seedHash && seedHash !== srcHash;
+    const result = { ok: true, archive: seed, fromSource: false };
+    if (edited) {
+      result.sdkEditIgnored = {
+        sdk: a.name,
+        message:
+          `Your changes to the bundled ${a.name} source were NOT compiled into ` +
+          `this build — it linked the prebuilt ${a.name} cache. To build your ` +
+          `edits, pass rebuildSdk:true.`,
+      };
+    }
+    return result;
+  }
+
+  // No seed shipped (dev / first build before seeding) → compile from source.
+  const r = await a.compileFromSource();
+  if (!r.ok) return { ok: false, fromSource: true, stage: r.stage, log: r.log };
+  await writeDiskCache(srcHash, r.archive);
+  return { ok: true, archive: r.archive, fromSource: true };
+}