romdevtools 0.13.0 → 0.14.0

package/src/mcp/tools/trace-vram-source.js

@@ -19,7 +19,7 @@ import { jsonContent } from "../util.js";
 import { decodeDMASource } from "../../platforms/genesis/vdp.js";
 import { makePressDriver } from "./watch-memory.js";
 
-// traceVramSource → dmaTrace({precision:'sampled'}) (router in watch-memory.js).
+// traceVramSource → watch({on:'dma', precision:'sampled'}) (router in watch-memory.js).
 // Exported core; the router passes its own sessionKey.
 export async function traceVramSourceCore({ frames = 120, pressDuring, romPreviewBytes = 16, minLengthBytes = 0, sessionKey }) {
       const host = getHost(sessionKey);
@@ -76,6 +76,6 @@ export async function traceVramSourceCore({ frames = 120, pressDuring, romPrevie
       });
 }
 
-// traceVramSource is registered as dmaTrace({precision:'sampled'}) by the
-// `dmaTrace` router in watch-memory.js (which imports traceVramSourceCore).
+// traceVramSource is reached via watch({on:'dma', precision:'sampled'}) by the
+// `watch` tool in watch-memory.js (which imports traceVramSourceCore).
 export function registerTraceVramSourceTools() {}

package/src/mcp/tools/watch-memory.js

@@ -881,10 +881,11 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     "Extras: `ranges:[{region,offset,length,label}]` watches MANY disjoint regions in ONE pass (identical frames); `onChange:'reset'|'increase'|'decrease'|'any'` edge filter (reset = counter-reload = the note-onset signal); `valueFilter:{min,max}`; `format:'series'` = compact columnar value-vs-frame curve (~10× smaller for a ramp); `sampleEvery`; `groupByPC` (collapse by sampled PC); `cheatLabels` (auto-name addresses from the cheat DB); `outputPath` streams all events as NDJSON; `stopOnFirst` exits on the first match. " +
     "**CAVEAT: frame-level, not instruction-level (last value per frame); the sampled `pc` is a frame-boundary sample — for ISR-driven writes use breakpoint({on:'write', precision:'exact'}) for the real writer.**\n" +
     "• on:'range' — DISCOVERY: log EVERY instruction that reads or writes ANYWHERE in [start,end]. The fix for 'I don't know which PC touches this'. Returns {pc,address,value}[] + the actionable distinctPCs. (Ring-buffered: `truncated:true` if it overflows.)\n" +
-    "• on:'pc' — DISCOVERY (coverage trace): record every DISTINCT PC executed within [start,end] — 'what code runs here?'. Log execution in the bank where you suspect the renderer lives during the moment it draws, then disassemble the PCs.",
+    "• on:'pc' — DISCOVERY (coverage trace): record every DISTINCT PC executed within [start,end] — 'what code runs here?'. Log execution in the bank where you suspect the renderer lives during the moment it draws, then disassemble the PCs.\n" +
+    "• on:'dma' — GENESIS ONLY: trace mem→VDP DMAs (the answer to 'this name/portrait/logo is a pre-rendered bitmap DMA'd into VRAM — WHERE in ROM?', which on:'write' can't catch). `precision:'exact'` (default) logs every mem→VDP DMA with its VRAM DESTINATION + ROM SOURCE + length (filter by `vramDest`±`destWindow`; `dedupe` collapses the per-frame refresh; `sourceFilter:'rom-only'` drops RAM→VRAM noise; catches a same-frame second DMA). `precision:'sampled'` is the cheap frame-sampled source-register read (may miss two DMAs in one frame, dest-agnostic). On non-Genesis cores returns `notSupported`.",
     {
-      on: z.enum(["mem", "range", "pc"])
-        .describe("mem=watch a RAM byte/ranges for value changes over frames (the power tool); range=log every read/write PC in [start,end]; pc=coverage trace of distinct PCs executed in [start,end]."),
+      on: z.enum(["mem", "range", "pc", "dma"])
+        .describe("mem=watch a RAM byte/ranges for value changes over frames (the power tool); range=log every read/write PC in [start,end]; pc=coverage trace of distinct PCs executed in [start,end]; dma=Genesis-only mem→VDP DMA source/dest trace."),
       // on:'mem'
       region: z.enum(MEMORY_REGIONS).optional().describe("on:'mem' single-range — the region to watch (same canonical set memory uses, incl. nes_apu_regs, genesis_ym2612, c64_sid_regs). Omit when using `ranges`."),
       offset: z.number().int().min(0).default(0).describe("on:'mem' single-range — first byte of the watched range."),
@@ -907,12 +908,20 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       frames: z.number().int().min(1).max(1_000_000).default(600).describe("Frames to run while logging (default 600). on:'range'/'pc' windows are usually short (~120) — pass a smaller value to keep the ring buffer from overflowing."),
       limit: z.number().int().min(1).max(4000).default(200).describe("on:'range'/'pc' — max events/PCs returned (default 200; full count is in `total`)."),
       outputPath: z.string().optional().describe("on:'mem' — stream every filter-passing event to this path as NDJSON + return a compact summary. Use for long watches so the full log never enters your context."),
+      // on:'dma' (Genesis VDP DMA trace)
+      precision: z.enum(["exact", "sampled"]).default("exact").describe("on:'dma' — exact=per-DMA core log with VRAM dest + ROM source (catches same-frame DMAs); sampled=frame-sampled source-register read (cheaper, may miss two DMAs in one frame, dest-agnostic)."),
+      vramDest: z.number().int().min(0).optional().describe("on:'dma' precision:'exact' — keep only DMAs whose VRAM destination is within ±`destWindow` of this address."),
+      destWindow: z.number().int().min(0).default(0x40).describe("on:'dma' precision:'exact' — match window around vramDest (default 64 bytes ≈ 1 tile)."),
+      dedupe: z.boolean().default(true).describe("on:'dma' precision:'exact' — collapse identical DMAs (same dest+source+length+code) to one entry with an `occurrences` count (default on)."),
+      sourceFilter: z.enum(["all", "rom-only", "ram-only"]).default("all").describe("on:'dma' precision:'exact' — 'rom-only' drops the RAM→VRAM per-frame refresh noise; 'ram-only' keeps only it."),
+      romPreviewBytes: z.number().int().min(0).max(64).default(0).describe("on:'dma' — bytes of the ROM source to preview per DMA (exact default 0; sampled default 16)."),
+      minLengthBytes: z.number().int().min(0).max(65536).default(0).describe("on:'dma' precision:'sampled' — ignore DMAs shorter than this many bytes (filters tiny scroll/sprite updates so graphic uploads stand out)."),
       pressDuring: z.array(z.object({
         frame: z.number().int().min(0),
         button: z.string(),
         port: z.number().int().min(0).max(3).default(0),
         holdFrames: z.number().int().min(1).default(2),
-      })).optional().describe("Schedule input while watching (drive the game to the state that touches the watched bytes/range)."),
+      })).optional().describe("Schedule input while watching (drive the game to the state that touches the watched bytes/range, or uploads the graphic for on:'dma')."),
     },
     safeTool(async (args) => {
       switch (args.on) {
@@ -925,19 +934,27 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
           if (args.start == null || args.end == null) throw new Error("watch({on:'pc'}): `start` and `end` are required.");
           return await wLogPC({ ...args, frames: args.frames ?? 120, limit: args.limit ?? 512 });
         }
+        case "dma": {
+          const a = { ...args, frames: args.frames ?? 120, limit: args.limit ?? 200 };
+          if (a.precision === "sampled") {
+            return await traceVramSourceCore({ ...a, romPreviewBytes: a.romPreviewBytes || 16, sessionKey });
+          }
+          return await dmaExact(a);
+        }
         default: throw new Error(`watch: unknown on '${args.on}'`);
       }
     }),
   );
 
-  // ── dmaTrace (item 3, Genesis only) ─────────────────────────────────────────
+  // ── watch({on:'dma'}) helpers (Genesis only) ────────────────────────────────
   // precision:exact = dmaExact (watchDma, per-DMA core log), precision:sampled =
-  // traceVramSourceCore (frame-sampled, dest-agnostic).
+  // traceVramSourceCore (frame-sampled, dest-agnostic). Routed by the `watch`
+  // tool's switch (case 'dma'); folded in from the old standalone dmaTrace tool.
   async function dmaExact({ frames = 120, vramDest, destWindow = 0x40, dedupe = true, sourceFilter = "all", pressDuring, romPreviewBytes = 0, limit = 200 }) {
       const host = getHost(sessionKey);
       if (!host.dmaWatchSupported || !host.dmaWatchSupported()) {
         return jsonContent({ notSupported: true, dmas: [],
-          note: "dmaTrace is Genesis-only (VDP DMA). On other platforms use breakpoint({on:'write'}) (CPU writes) or the platform's source tracer." });
+          note: "watch({on:'dma'}) is Genesis-only (VDP DMA). On other platforms use breakpoint({on:'write'}) (CPU writes) or the platform's source tracer." });
       }
       const presses = (pressDuring ?? []).slice().sort((a, b) => a.frame - b.frame);
       const pressDriver = makePressDriver(host, presses);
@@ -994,43 +1011,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
           (totalDistinct > limit ? `Showing ${out.length}/${totalDistinct} distinct — raise limit or narrow vramDest.` : ""),
       }), host);
   }
-
-  server.tool(
-    "dmaTrace",
-    "GENESIS ONLY — trace mem→VDP DMAs (the answer to 'this name/portrait/logo is a pre-rendered bitmap DMA'd into VRAM — " +
-    "WHERE in ROM?', which breakpoint({on:'write'}) can't catch). Keyed by `precision`.\n" +
-    "• precision:'exact' (default) — log every mem→VDP DMA with its VRAM DESTINATION, ROM SOURCE, length, and code. " +
-    "Filter by `vramDest` (±`destWindow`) to find the exact source of a specific tile. `dedupe` collapses the per-frame " +
-    "refresh (7000 events → a handful); `sourceFilter:'rom-only'` drops the RAM→VRAM sprite/scroll noise. " +
-    "**Catches a second DMA in the same frame that the sampled mode misses.**\n" +
-    "• precision:'sampled' — the cheap frame-sampled tracer: reads the VDP DMA source registers ($15-$17) once per frame " +
-    "and logs each DISTINCT mem→VRAM source as a ROM byte offset. **HONEST LIMIT: two DMAs in the SAME frame may show only " +
-    "one source — narrow the window around when the graphic appears. dest-agnostic (no vramDest filter).**",
-    {
-      precision: z.enum(["exact", "sampled"]).default("exact")
-        .describe("exact=per-DMA core log with VRAM dest + ROM source (catches same-frame DMAs); sampled=frame-sampled source-register read (cheaper, may miss two DMAs in one frame, dest-agnostic)."),
-      frames: z.number().int().min(1).max(6000).default(120).describe("Frames to step while tracing (default 120 ≈ 2s)."),
-      pressDuring: z.array(z.object({
-        frame: z.number().int().min(0),
-        button: z.string(),
-        port: z.number().int().min(0).max(3).default(0),
-        holdFrames: z.number().int().min(1).default(2),
-      })).optional().describe("Drive input to the screen that uploads the graphic."),
-      romPreviewBytes: z.number().int().min(0).max(64).default(0).describe("Bytes of the ROM source to preview per DMA (exact default 0; sampled default 16)."),
-      // precision:'exact' only
-      vramDest: z.number().int().min(0).optional().describe("precision:'exact' — keep only DMAs whose VRAM destination is within ±`destWindow` of this address."),
-      destWindow: z.number().int().min(0).default(0x40).describe("precision:'exact' — match window around vramDest (default 64 bytes ≈ 1 tile)."),
-      dedupe: z.boolean().default(true).describe("precision:'exact' — collapse identical DMAs (same dest+source+length+code) to one entry with an `occurrences` count (default on)."),
-      sourceFilter: z.enum(["all", "rom-only", "ram-only"]).default("all").describe("precision:'exact' — 'rom-only' drops the RAM→VRAM per-frame refresh noise; 'ram-only' keeps only it."),
-      limit: z.number().int().min(1).max(2000).default(200).describe("precision:'exact' — max DMA entries to return (after dedupe/filter)."),
-      // precision:'sampled' only
-      minLengthBytes: z.number().int().min(0).max(65536).default(0).describe("precision:'sampled' — ignore DMAs shorter than this many bytes (filters tiny scroll/sprite updates so graphic uploads stand out)."),
-    },
-    safeTool(async (args) => {
-      if (args.precision === "sampled") {
-        return await traceVramSourceCore({ ...args, romPreviewBytes: args.romPreviewBytes || 16, sessionKey });
-      }
-      return await dmaExact(args);
-    }),
-  );
+  // dmaExact + traceVramSourceCore are reached via watch({on:'dma'}) above —
+  // dmaTrace was folded into `watch` (it's a log-all VDP-DMA trace, same family
+  // as on:'mem'/'range'/'pc'), so there's no separate top-level tool.
 }

package/src/observer/livestream.html

@@ -20,7 +20,12 @@
   }
   header h1 { margin: 0; font-size: 14px; font-weight: 600; }
   #version { font-size: 11px; font-weight: 400; color: #888; }
-  #status { font-size: 11px; color: #888; }
+  header a.doclink {
+    font-size: 11px; color: #6cb6ff; text-decoration: none;
+    border: 1px solid #2a3f55; border-radius: 3px; padding: 2px 7px;
+  }
+  header a.doclink:hover { background: #14202e; text-decoration: underline; }
+  #status { font-size: 11px; color: #888; margin-left: auto; }
   #status.connected { color: #4caf50; }
   #status.disconnected { color: #f44336; }
   #tabs {
@@ -172,6 +177,7 @@
 <body>
 <header>
   <h1>romdev /livestream <span id="version">__ROMDEV_VERSION__</span></h1>
+  <a class="doclink" href="/documentation" target="_blank" rel="noopener">API docs ↗</a>
   <span id="status" class="disconnected">disconnected</span>
 </header>
 <div id="tabs"></div>

package/src/platforms/_guides/ROMHACKING_PLAYBOOK.md

@@ -56,7 +56,7 @@ font-rendered from an ASCII string. Patching the ASCII string then does nothing.
    string. Do not patch any ASCII string you found; it isn't the source.
 2. If it IS font-rendered, find the string with `text({op:'find'})` /
    `text({op:'encode'})` and patch that.
-3. To find where a graphic/text was sourced from: on **Genesis**, `dmaTrace({precision:'sampled'})`
+3. To find where a graphic/text was sourced from: on **Genesis**, `watch({on:'dma', precision:'sampled'})`
    — drive to the screen that shows the graphic, and it reports the ROM offset(s)
    the tiles were DMA'd from (decoded from the VDP DMA registers). Edit the tile
    bitmaps at that offset, not any string. (Elsewhere: if `breakpoint({on:'write'})` on the VRAM
@@ -198,8 +198,8 @@ Breakpoints are great once you KNOW the address. To FIND it:
 - **`watch({on:'pc', start, end, frames})`** — coverage trace: every DISTINCT PC that
   EXECUTED in an address window. "What code runs in this bank during the scoreboard
   draw?" → `disasm({target:'rom'})` the PCs it returns.
-- **`dmaTrace({precision:'exact', vramDest})`** (Genesis) — which DMA wrote the tile at a VRAM dest,
-  and the ROM SOURCE it came from. The targeted version of `dmaTrace({precision:'sampled'})`; the
+- **`watch({on:'dma', precision:'exact', vramDest})`** (Genesis) — which DMA wrote the tile at a VRAM dest,
+  and the ROM SOURCE it came from. The targeted version of `watch({on:'dma', precision:'sampled'})`; the
   way to catch a DMA'd (not CPU-written) name/portrait bitmap `breakpoint({on:'write'})` can't see.
 
 ---
@@ -238,8 +238,8 @@ transition.
 | Re-inject edited bytes the game accepts | `romPatch({op:'makeStored'})` (verbatim-expand block) → `romPatch({op:'findFree'})` → `romPatch({op:'relocate'})` |
 | Find the pointer that loads an asset | `romPatch({op:'findPointer', romOffset})` |
 | FIND the unknown routine touching X | `watch({on:'range', start,end})` (all hits) / `watch({on:'pc'})` (coverage) |
-| Which DMA wrote a VRAM tile + its source (Genesis) | `dmaTrace({precision:'exact', vramDest})` |
-| Where did a VRAM graphic come from (Genesis) | `dmaTrace({precision:'sampled'})` (ROM offset of the DMA source) |
+| Which DMA wrote a VRAM tile + its source (Genesis) | `watch({on:'dma', precision:'exact', vramDest})` |
+| Where did a VRAM graphic come from (Genesis) | `watch({on:'dma', precision:'sampled'})` (ROM offset of the DMA source) |
 | Drive a menu fast | `input({op:'navigate'})` (advances on screen change) |
 | Free RAM map for a known game | `cheats({op:'lookup'})` / `cheats({op:'search'})` |
 | Safe patch | `romPatch({op:'write'})`/`romPatch({op:'writeMany'})` with `expect` |

package/src/platforms/gb/MENTAL_MODEL.md

@@ -20,7 +20,7 @@ check these first. All five have shipped fixes in the bundled runtime
    classic white-screen: a stray $FF pad there trips CGB mode on a DMG
    ROM so BGP/OBP* writes are ignored. Because the build sets it from the
    platform you chose, a freshly built ROM is correct with **no manual
-   step**. Call `patchGbHeader` only to fix up an existing/external ROM
+   step**. Call `romPatch({op:'gbHeader'})` only to fix up an existing/external ROM
    or override a field (title, cart type, ROM/RAM size, CGB flag).
 
 2. **OAM shadow buffer must be page-aligned.** OAM DMA copies 160 bytes
@@ -122,7 +122,7 @@ running a CGB-aware ROM, the DMG registers are ignored.
 You normally don't touch this byte by hand: `build({output:'rom'})` / `build({output:'run'})`
 set it from the platform you build for ($00 for `platform:"gb"`, $80/$C0
 for `platform:"gbc"`). To force a value, set it in your `gb_crt0.s`
-header section, or call `patchGbHeader({path, cgb:true})` on the built
+header section, or call `romPatch({op:'gbHeader', path, cgb:true})` on the built
 ROM (it auto-detects the `.gbc` extension; the standalone
 `patch-header.js` script does the same).
 
@@ -201,7 +201,7 @@ Build calls explicitly reference these files via `sourcesPaths` /
 `includePaths` / `crt0Path` + `codeLoc: 0x150`. `build({output:'rom'})` /
 `build({output:'run'})` then fix up the cart header automatically (logo, checksums,
 CGB flag), so the ROM loads under gambatte with no extra step. Use
-`patchGbHeader({path})` (MCP tool) or `node patch-header.js <rom>` (CLI)
+`romPatch({op:'gbHeader', path})` (romdev tool) or `node patch-header.js <rom>` (CLI)
 only on a ROM the build pipeline didn't produce. See your project's
 README for the exact incantation.
 

package/src/platforms/gb/TROUBLESHOOTING.md

@@ -92,7 +92,7 @@ the cross-platform note: [[sdcc-uint8-loop-bound-trap]].
    `platform:"gb"` and it stays $00 (DMG). So if colors are wrong, first
    check you didn't build this as a `.gb` ROM — rebuild with
    `platform:"gbc"`. (To force a value on an existing ROM: set it in your
-   `gb_crt0.s` header section, run `patchGbHeader({path:"out.gbc"})`, or
+   `gb_crt0.s` header section, run `romPatch({op:'gbHeader', path:"out.gbc"})`, or
    run `node patch-header.js out.gbc`.) Verify:
    ```sh
    xxd -s 0x143 -l 1 out.gbc      # expect: 80

package/src/platforms/gb/UPSTREAM_SOURCES.md

@@ -36,7 +36,7 @@ upstream README. Songs are exported from hUGETracker
 - "OAM DMA wedges sprites" → see `MENTAL_MODEL.md` § R26 footguns +
   `gb_runtime.c` `oam_dma_copy` implementation
 - "BGP write does nothing" → check $0143 (CGB flag) via
-  `patchGbHeader` + Pan Docs § "The Cartridge Header"
+  `romPatch({op:'gbHeader'})` + Pan Docs § "The Cartridge Header"
 - "How does hUGEDriver process a song row?" → `hUGEDriver.c`
   `hUGE_dosound` body — fully readable
 - "Why is gambatte refusing my ROM?" → check the header, then

package/src/platforms/gb/lib/c/README.md

@@ -23,12 +23,12 @@ run rgbfix on the linked GB/GBC ROM — valid Nintendo logo at $0104,
 header checksum at $014D, global checksum at $014E, cartridge-type /
 RAM-size bytes, and the CGB flag at $0143 ($00 for `.gb`, $80/$C0 for
 `.gbc`). A freshly built ROM boots on hardware and strict cores with
-**no extra step** — you do not call `patchGbHeader` after a normal build.
+**no extra step** — you do not call `romPatch({op:'gbHeader'})` after a normal build.
 
 Reach for header tooling only when working with a ROM the build pipeline
 didn't produce, or to override a field:
 
-- `patchGbHeader({path: "out.gb"})` — MCP tool.
+- `romPatch({op:'gbHeader', path: "out.gb"})` — romdev tool.
   Fixes up / overrides the header of an existing ROM on disk (title, cart
   type, ROM/RAM size, CGB flag, etc.).
 - `node patch-header.js out.gb` — standalone Node script, copied into

package/src/platforms/gb/lib/c/SDCC_GOTCHAS.md

@@ -110,7 +110,7 @@ If you need to write a custom VRAM block-copy:
 
 This is independent of the R26 OAM-alignment fix (`shadow_oam __at
 (0xC100)`) and the header CGB-flag fix (now applied automatically by
-`build({output:'rom'})` / `build({output:'run'})`, not a manual `patchGbHeader` step). All
+`build({output:'rom'})` / `build({output:'run'})`, not a manual `romPatch({op:'gbHeader'})` step). All
 three are silent-failure bugs that look like "did my changes even
 land?" and need different fixes.
 

package/src/platforms/gbc/MENTAL_MODEL.md

@@ -16,7 +16,7 @@ the same wall.
    `build({output:'rom'})` / `build({output:'run'})` do this for you at build time: every byte
    at $0134..$014C is filled, and on `platform:"gbc"` the CGB flag at
    $0143 is set to $80 (CGB-aware + DMG-compatible). You do **not** run
-   `patchGbHeader` on a freshly built ROM. Reach for `patchGbHeader` only
+   `romPatch({op:'gbHeader'})` on a freshly built ROM. Reach for `romPatch({op:'gbHeader'})` only
    to fix up an existing / externally built ROM whose header was never
    set, or to override a field — e.g. starting from a `.gb` ROM and
    wanting CGB color, pass `cgb: true` explicitly.
@@ -161,11 +161,11 @@ the only differences at build time are:
 
 - ROM extension: `.gbc` (vs `.gb`)
 - the build sets `$0143 = $80` to flip CGB mode on (automatic when you
-  build with `platform:"gbc"` — no manual `patchGbHeader` step)
+  build with `platform:"gbc"` — no manual `romPatch({op:'gbHeader'})` step)
 - gambatte core accepts both DMG + CGB-mode ROMs
 
 For new GBC code that wants to be CGB-only (no DMG fallback) set the
-CGB byte to `$C0` instead of `$80` — `patchGbHeader({path, cgb:true})`
+CGB byte to `$C0` instead of `$80` — `romPatch({op:'gbHeader', path, cgb:true})`
 on the built ROM can override it.
 
 ## Horizontal scrolling (for side-scrollers)

package/src/platforms/gbc/TROUBLESHOOTING.md

@@ -59,7 +59,7 @@ and falls back to DMG mode when it's `$00`.
 When you build with `platform:"gbc"`, `build({output:'rom'})` / `build({output:'run'})`
 **auto-fix the header** — Nintendo logo, header + global checksums,
 and `$0143 = $80` (CGB-enhanced) — so a freshly built `.gbc` already
-boots in color. You do **not** call `patchGbHeader` for that.
+boots in color. You do **not** call `romPatch({op:'gbHeader'})` for that.
 
 ```js
 build({ output: 'run', platform: "gbc", language: "c", ... });  /* header auto-fixed */
@@ -67,7 +67,7 @@ build({ output: 'run', platform: "gbc", language: "c", ... });  /* header auto-f
 
 If you instead see green-shade DMG mode, the ROM was almost certainly
 built with `platform:"gb"` (so the CGB flag stayed `$00`). Rebuild with
-`platform:"gbc"`. Reach for `patchGbHeader` only to fix up an existing /
+`platform:"gbc"`. Reach for `romPatch({op:'gbHeader'})` only to fix up an existing /
 externally built `.gbc` whose header was never set, or to override a
 header field (e.g. force `cgb:false`).
 
@@ -106,12 +106,12 @@ Without the attribute writes, every BG tile defaults to palette 0.
 ## "Game ran on Game Boy emulator but not on Game Boy Color emulator"
 
 `loadMedia({platform:"gbc", path})` expects gambatte in CGB mode. If
-your ROM was built with `platform:"gb"` (no patchGbHeader) the file
+your ROM was built with `platform:"gb"` (no gbHeader patch) the file
 extension is `.gb` and the header CGB byte is $00, so gambatte starts
 in DMG mode. To switch a DMG ROM to CGB:
 
 1. Rename / re-extension to `.gbc`
-2. Run `patchGbHeader({path:"out.gbc"})` — also fixes the global
+2. Run `romPatch({op:'gbHeader', path:"out.gbc"})` — also fixes the global
    checksum that the boot ROM checks
 
 ## "Sound is the same as DMG"
@@ -125,7 +125,7 @@ sound channels or extra waveforms.
 The bundled GBC scaffolds all fit in 32 KB (single bank, no MBC).
 For larger projects use an MBC (memory bank controller). MBC1 / MBC3
 work in gambatte; set the `$0147` cartridge type byte accordingly.
-patchGbHeader doesn't set this — you write it from your asm/C.
+romPatch({op:'gbHeader'}) doesn't set this — you write it from your asm/C.
 
 ## "Frame heartbeat feels janky / slow"
 

package/src/platforms/gbc/UPSTREAM_SOURCES.md

@@ -7,7 +7,7 @@ the color-aware scaffolds; everything below is in lockstep with
 the GB tree.
 
 CGB-specific:
-- `patchGbHeader({cgb: true})` sets $0143 = $80 → gambatte boots
+- `romPatch({op:'gbHeader', cgb: true})` sets $0143 = $80 → gambatte boots
   in CGB mode with color palette RAM active
 - VRAM bank 1 (selected via VBK = $FF4F) holds per-tile attribute
   bytes (palette index, H/V flip, BG-OAM priority)
@@ -53,7 +53,7 @@ upstream README. Songs are exported from hUGETracker
 - "OAM DMA wedges sprites" → see `MENTAL_MODEL.md` § R26 footguns +
   `gb_runtime.c` `oam_dma_copy` implementation
 - "BGP write does nothing" → check $0143 (CGB flag) via
-  `patchGbHeader` + Pan Docs § "The Cartridge Header"
+  `romPatch({op:'gbHeader'})` + Pan Docs § "The Cartridge Header"
 - "How does hUGEDriver process a song row?" → `hUGEDriver.c`
   `hUGE_dosound` body — fully readable
 - "Why is gambatte refusing my ROM?" → check the header, then

package/src/platforms/gbc/lib/c/README.md

@@ -23,12 +23,12 @@ run rgbfix on the linked GB/GBC ROM — valid Nintendo logo at $0104,
 header checksum at $014D, global checksum at $014E, cartridge-type /
 RAM-size bytes, and the CGB flag at $0143 ($80/$C0 for `.gbc`, $00 for
 `.gb`). A freshly built ROM boots on hardware and strict cores with **no
-extra step** — you do not call `patchGbHeader` after a normal build.
+extra step** — you do not call `romPatch({op:'gbHeader'})` after a normal build.
 
 Reach for header tooling only when working with a ROM the build pipeline
 didn't produce, or to override a field:
 
-- `patchGbHeader({path: "out.gb"})` — MCP tool.
+- `romPatch({op:'gbHeader', path: "out.gb"})` — romdev tool.
   Fixes up / overrides the header of an existing ROM on disk (title, cart
   type, ROM/RAM size, CGB flag, etc.).
 - `node patch-header.js out.gb` — standalone Node script, copied into

package/src/platforms/gbc/lib/c/SDCC_GOTCHAS.md

@@ -110,7 +110,7 @@ If you need to write a custom VRAM block-copy:
 
 This is independent of the R26 OAM-alignment fix (`shadow_oam __at
 (0xC100)`) and the header CGB-flag fix (now applied automatically by
-`build({output:'rom'})` / `build({output:'run'})`, not a manual `patchGbHeader` step). All
+`build({output:'rom'})` / `build({output:'run'})`, not a manual `romPatch({op:'gbHeader'})` step). All
 three are silent-failure bugs that look like "did my changes even
 land?" and need different fixes.
 

package/src/playtest/playtest.js

@@ -148,8 +148,33 @@ async function getSdl() {
   try {
     const ns = await import("@kmamal/sdl");
     _sdlModule = ns.default || ns;
+    // GROUND-TRUTH visibility check (cross-platform, NOT env-var guessing):
+    // SDL picks a video driver at init. With no presentable surface (no desktop
+    // session, no Xvfb, headless box) it falls back to "offscreen"/"dummy" —
+    // createWindow then SUCCEEDS and audio plays, but nothing appears on any
+    // physical screen. That's the silent "agent says the window's up, user sees
+    // nothing (but hears sound)" failure. We catch it HERE by asking SDL which
+    // driver it actually selected — works the same on Linux/macOS/Windows, and
+    // correctly ALLOWS a real offscreen X server (Xvfb reports "x11", not
+    // "offscreen"). Headless rendering (screenshot/runSource) never calls this,
+    // so offscreen stays perfectly fine for everything except opening a window
+    // for a human.
+    const driver = _sdlModule?.info?.drivers?.video?.current;
+    if (driver === "offscreen" || driver === "dummy") {
+      throw tag(new Error(
+        `SDL selected the "${driver}" video driver — there is no presentable display, ` +
+        "so a playtest window would render but never appear on a physical screen " +
+        "(you'd hear audio but see nothing). The server must run where it has a real " +
+        "display: start it from a terminal INSIDE your logged-in desktop session " +
+        "(`npx romdevtools`), then point your agent at that server. (A server spawned " +
+        "by your agent host, over plain SSH, or from a tty/headless box has no display. " +
+        "A virtual display like Xvfb works too — it reports as the real driver, not " +
+        "\"offscreen\".)",
+      ), "no-display");
+    }
     return _sdlModule;
   } catch (e) {
+    if (e?.sdlKind) throw e; // already-tagged (e.g. the offscreen check above)
     const isModuleErr = e?.code === "ERR_MODULE_NOT_FOUND" ||
       /sdl\.node|dist[\\/]/.test(e?.message || "");
     throw tag(new Error(e?.message ?? String(e)),