romdevtools 0.27.0 → 0.28.0

package/src/mcp/tools/project.js

@@ -92,7 +92,7 @@ const TEMPLATES = {
       linkerConfig: { presetSrc: "presets/nes/chr-ram-runtime.cfg", dst: "chr-ram-runtime.cfg" },
       lang: "C (cc65)",
       ext: ".nes",
-      describe: "Match-3 falling-block puzzle. 6×12 grid, 1×3 active piece (3 colors), rotate via A, soft-drop on DOWN, horizontal-triple clear.",
+      describe: "Match-3 falling-block puzzle. 6×12 grid, 1×3 active piece (3 colors), rotate via A, soft-drop on DOWN, 3+-in-a-row clears in all 4 directions (H/V/diagonals) with gravity + cascade chains.",
     },
     sports: {
       main: "templates/sports.c",
@@ -214,7 +214,7 @@ const TEMPLATES = {
       ],
       lang: "C (SDCC sm83)",
       ext: ".gb",
-      describe: "Match-3 falling-block puzzle scaffold for GB. 6×12 grid rendered via BG tilemap, 1×3 active piece (3 colours via 3 BG tile shapes), rotate via A, hard-drop on START, horizontal-triple clear.",
+      describe: "Match-3 falling-block puzzle scaffold for GB. 6×12 grid rendered via BG tilemap, 1×3 active piece (3 colours via 3 BG tile shapes), rotate via A, hard-drop on START, 3+-in-a-row clears in all 4 directions (H/V/diagonals) with gravity + cascade chains.",
     },
     sports: {
       main: "templates/sports.c",
@@ -284,7 +284,7 @@ const TEMPLATES = {
       catch_game: mk("catch_game", "A complete tiny game: a paddle catches a falling object with the d-pad; full game loop with waitvsync(), two sprites, collision, scoring."),
       shmup: mk("shmup", "Vertical shoot-'em-up for PC Engine. Player ship + bullet/enemy object pools, a wave spawner, AABB collisions, score HUD, scrolling-band starfield BG. d-pad flies, button I fires. The base for any action shooter."),
       platformer: mk("platformer", "Side-scrolling platformer for PC Engine. Gravity + jump + land-on-top platform collision, a multi-screen world streamed via BG X-scroll (BXR), solid platform tiles, sub-pixel physics. d-pad moves, button I jumps."),
-      puzzle: mk("puzzle", "Match-3 / falling-block puzzle for PC Engine. A 6x12 well drawn with BG tiles, a 1x3 active piece you move/rotate/soft-drop/hard-drop, horizontal-triple clears, score. d-pad moves, I rotates, II hard-drops."),
+      puzzle: mk("puzzle", "Match-3 / falling-block puzzle for PC Engine. A 6x12 well drawn with BG tiles, a 1x3 active piece you move/rotate/soft-drop/hard-drop, 3+-in-a-row clears (H+V) with gravity + cascade chains, score. d-pad moves, I rotates, II hard-drops."),
       sports: mk("sports", "Pong-style sports game for PC Engine. Two paddles + a bouncing ball on a netted court, score to 9, paddle-deflect physics; player 2 falls back to chase-AI when no input. d-pad moves P1."),
       racing: mk("racing", "Top-down lane racer for PC Engine. Player car at the bottom, obstacle cars spawn from the top and slide down, LEFT/RIGHT switches lanes, speed grows with score, crash freeze + auto-reset. Scrolling road BG."),
     };
@@ -305,7 +305,7 @@ const TEMPLATES = {
       catch_game: mk("catch_game", "A complete tiny game: a paddle catches falling fruit with the joystick; full game loop with vblank sync, two sprites, collision, scoring."),
       shmup: mk("shmup", "Vertical-shmup scaffold for MSX (screen 2). Player ship (sprite plane 0) + 4 bullet + 4 enemy object pools, a wave spawner, AABB collision, on-screen SCORE tiles, over a banded starfield filling the whole 32x24 name table. Joystick PORT 1 moves the ship (UP/DOWN/LEFT/RIGHT), trigger A (GTTRIG) fires; PSG blip on fire, noise-ish tone on a kill. Interrupt-free vsync via VDP status S#0. Extend with enemy fire, lives, scrolling stars."),
       platformer: mk("platformer", "Side-scrolling platformer for MSX (screen 2). Subpixel gravity/jump/land-on-top collision against a table of platforms across a 512-px (64-cell) world, drawn by COLUMN STREAMING into the wrapping screen-2 name table as the camera follows the player; the player sprite draws in screen space. Joystick LEFT/RIGHT walks, trigger A jumps (only when grounded); PSG jump blip. Interrupt-free vsync. Extend with enemies, pickups, goal."),
-      puzzle: mk("puzzle", "Match-3 / falling-block puzzle for MSX (screen 2). A 6-wide x 12-tall well drawn with the BG tilemap (distinct R/G/B cell tiles + grey border + dim field interior so the playfield is always visible). A 1x3 active piece: joystick LEFT/RIGHT shifts, trigger A rotates the colour order, DOWN soft-drops, trigger B hard-drops; horizontal-triple clears score with a PSG chime. Interrupt-free vsync. Extend with vertical/diagonal matches, gravity-collapse, levels."),
+      puzzle: mk("puzzle", "Match-3 / falling-block puzzle for MSX (screen 2). A 6-wide x 12-tall well drawn with the BG tilemap (distinct R/G/B cell tiles + grey border + dim field interior so the playfield is always visible). A 1x3 active piece: joystick LEFT/RIGHT shifts, trigger A rotates the colour order, DOWN soft-drops, trigger B hard-drops; 3+-in-a-row clears in all 4 directions with gravity + cascade chains; PSG chime per clear. Interrupt-free vsync. Extend with levels/next-piece preview."),
       sports: mk("sports", "Pong-style 2-player sports for MSX (screen 2). Court (green field + white sidelines + dashed centre net) fills the 32x24 name table; two paddles (stacked sprites) + a ball. Player 1 = joystick PORT 1 UP/DOWN; Player 2 = joystick PORT 2 UP/DOWN, falling back to chase-the-ball AI when no second pad is present so it is playable solo. Wall/paddle bounces + scoring with PSG bonks. Interrupt-free vsync. Extend with serve angles, score display, win condition."),
       racing: mk("racing", "Top-down 3-lane racing for MSX (screen 2). Grey road + green-grass shoulders fill the name table; player car at the bottom, obstacle cars (object pool) spawn at the top and slide down. Joystick LEFT/RIGHT (edge-detected) switches lanes; obstacle speed grows with score; an AABB crash triggers a ~60-frame freeze then auto-reset, with a PSG crash tone. SCORE drawn as tiles. Interrupt-free vsync. Extend with pseudo-3D road, fuel, multiple cars."),
     };
@@ -351,9 +351,19 @@ TEMPLATES.gbc = {
     describe: "SIDE-SCROLLING platformer for GBC. Full CGB color palette (BG + sprite via BCPS/OCPS) over the GB side-scroller core: subpixel gravity + jump + land-on-top collision against platforms across a 256-px world (the wrapping BG map). The camera follows the player and scrolls the BG via SCX; the player sprite draws in screen space. A=jump, d-pad=move. One BG map wide (no streaming) — for a wider world, stream a new BG-map column on each 8px camera step (window for a fixed HUD). See the GBC MENTAL_MODEL.md 'Horizontal scrolling'. Extend with enemies, goals, pickups.",
   },
   puzzle: {
-    main: "templates/puzzle.c", runtime: GBC_RUNTIME,
+    main: "templates/puzzle.c",
+    runtime: [
+      ...GBC_RUNTIME,
+      { src: "lib/c/font.h", dst: "font.h" },  /* digits+A-Z 2bpp glyphs for the HUD */
+    ],
     lang: GBC_LANG, ext: ".gbc",
-    describe: "Match-3 puzzle for GBC. Three colored cells (BG palette via BCPS/BCPD), rotate + soft-drop + hard-drop + triple-clear chime.",
+    describe: "Falling-jewel matcher for GBC (the polished reference puzzle). 8x17 well, 6 jewel colors with " +
+      "real CGB palettes, matches in all 4 directions (H/V/both diagonals), gravity + cascade chains, magic " +
+      "jewel every 18th piece, level speedup, 6-digit score, title + game-over screens, SFX + toggleable " +
+      "music. Rendering: falling column + NEXT preview are OAM sprites; the locked well is BG tiles via a " +
+      "COLLECT/FLUSH vblank queue with an idle scrub (writes outside vblank silently drop on this core — " +
+      "never bypass the queue). Statics need dataLoc 0xC200 (above shadow_oam at $C100) — the project build " +
+      "recipe sets that automatically.",
   },
   sports: {
     main: "templates/sports.c", runtime: GBC_RUNTIME,
@@ -398,6 +408,11 @@ TEMPLATES.gbc = {
 // against. Factored to a constant so adding a new template is a one-line
 // change at the bottom.
 const SMS_RUNTIME = [
+  // The crt0 ships IN the project (like GG/MSX) so the dir is genuinely
+  // self-contained: build({output:'project'}) routes it via the crt0 channel
+  // (projectBuildRecipe), and an external stock-SDCC rebuild has the real
+  // boot stub on disk instead of silently linking SDCC's non-booting one.
+  { src: "lib/c/sms_crt0.s",      dst: "sms_crt0.s" },
   { src: "lib/c/sms_hw.h",        dst: "sms_hw.h" },
   { src: "lib/c/vdp_init.c",      dst: "vdp_init.c" },
   { src: "lib/c/load_palette.c",  dst: "load_palette.c" },
@@ -764,7 +779,7 @@ TEMPLATES.snes = {
     runtimeDirs: SNES_PVSNESLIB_VENDOR_DIRS,
     lang: "C (tcc-65816 + PVSnesLib)",
     ext: ".sfc",
-    describe: "Match-3 falling-block puzzle for SNES. 6×12 grid (text mode), rotate/soft-drop/hard-drop, horizontal-triple clear. Rotate click + clear chime via bundled SPC700 sfx.",
+    describe: "Match-3 falling-block puzzle for SNES. 6×12 grid (text mode), rotate/soft-drop/hard-drop, 3+-in-a-row clears in all 4 directions with gravity + cascade chains. Rotate click + clear chime via bundled SPC700 sfx.",
   },
   sports: {
     main: "templates/sports.c",
@@ -939,7 +954,7 @@ TEMPLATES.genesis = {
     runtimeDirs: SGDK_RUNTIME_DIRS,
     lang: SGDK_LANG,
     ext: ".bin",
-    describe: "Match-3 falling-block puzzle genre scaffold. 6×12 grid, 1×3 active piece (3 colours), rotate via A, soft-drop on DOWN, hard-drop on START, horizontal-triple clear. xorshift RNG so cell colours actually vary.",
+    describe: "Match-3 falling-block puzzle genre scaffold. 6×12 grid, 1×3 active piece (3 colours), rotate via A, soft-drop on DOWN, hard-drop on START, 3+-in-a-row clears in all 4 directions with gravity + cascade chains. xorshift RNG so cell colours actually vary.",
   },
   sports: {
     main: "templates/sports.c",
@@ -1757,7 +1772,18 @@ Compiles **C89**, not C99/C11. Stick to:
   let filesSection = `## Files\n\n- \`${mainFilename}\` — your game's entry point.\n`;
   if (tmpl?.runtime) {
     for (const { dst } of tmpl.runtime) {
-      filesSection += `- \`${dst}\` — runtime helper. **You own this** — edit or replace at will.\n`;
+      if (dst === "patch-header.js") {
+        // NOT game code — calling it a "runtime helper" implied it compiles
+        // into the ROM and confused readers. It's a standalone sidecar tool.
+        filesSection += `- \`${dst}\` — sidecar TOOL, not game code (never compiled into the ROM). ` +
+          `Stamps the Nintendo logo + header/global checksums a GB ROM needs to boot ` +
+          `(\`node patch-header.js game.gb\`) — a zero-install stand-in for RGBDS's rgbfix when you ` +
+          `rebuild OUTSIDE romdev with stock SDCC. romdev's own builds fix the header automatically.\n`;
+      } else if (dst.endsWith("_crt0.s")) {
+        filesSection += `- \`${dst}\` — startup assembly (reset/interrupt vectors, RAM init; routed as the crt0 by the project build). **You own this.**\n`;
+      } else {
+        filesSection += `- \`${dst}\` — runtime helper. **You own this** — edit or replace at will.\n`;
+      }
     }
   }
   if (tmpl?.crt0) {

package/src/mcp/tools/toolchain.js

@@ -266,7 +266,7 @@ export function installToolchainCore({ id }) {
 }
 
 export function registerToolchainTools(server, z, sessionKey) {
-  async function buildSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, crt0, crt0Path, codeLoc, dataLoc, options, linkerConfig, inesHeader, outputPath, inline = false, includeSymbols = false, lint = "advisory", runtime, maxmod, rebuildSdk }) {
+  async function buildSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, crt0, crt0Path, codeLoc, dataLoc, options, linkerConfig, linkerConfigPath, inesHeader, outputPath, inline = false, includeSymbols = false, lint = "advisory", runtime, maxmod, rebuildSdk }) {
       // Reject conflicting inline vs path args — fail loud, not silent.
       if (source != null && sourcePath != null) {
         throw new Error("build({output:'rom'}): pass either `source` OR `sourcePath`, not both.");
@@ -281,6 +281,12 @@ export function registerToolchainTools(server, z, sessionKey) {
       if (crt0Path) {
         crt0 = await readFile(crt0Path, "utf-8");
       }
+      // linkerConfigPath: read the .cfg from disk so a large multi-bank
+      // config (e.g. a disasm'd mapper-2 rebuild) isn't re-streamed through
+      // context on every build (0.27.0 feedback #2).
+      if (linkerConfigPath && linkerConfig == null) {
+        linkerConfig = await readFile(linkerConfigPath, "utf-8");
+      }
       // Auto-inject the bundled crt0 for SMS/GG when caller didn't pass
       // one. Stock SDCC crt0 doesn't boot these targets; without this,
       // user main() is never called → black screen. See AUTO_CRT0_PLATFORMS.
@@ -464,7 +470,7 @@ 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, 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, path: projPath, frames = 60, holdInputs, screenshotPath, projectName }) {
       const { buildForPlatform } = await import("../../toolchains/index.js");
       const resolved = resolveCore(platform);
       if (!resolved) throw new Error(`no core available for platform '${platform}'`);
@@ -480,6 +486,7 @@ export function registerToolchainTools(server, z, sessionKey) {
         binaryIncludes = { ...(binaryIncludes ?? {}), ...r.binaryIncludes };
         if (r.crt0 != null) crt0 = r.crt0;
         if (r.codeLoc != null) codeLoc = r.codeLoc;
+        if (r.dataLoc != null && dataLoc == null) dataLoc = r.dataLoc;
         if (r.linkerConfig != null && linkerConfig == null) linkerConfig = r.linkerConfig;
         if (r.runtime != null && runtime == null) runtime = r.runtime;
         if (r.maxmod != null && maxmod == null) maxmod = r.maxmod;
@@ -510,6 +517,9 @@ export function registerToolchainTools(server, z, sessionKey) {
       if (crt0Path) {
         crt0 = await readFile(crt0Path, "utf-8");
       }
+      if (linkerConfigPath && linkerConfig == null) {
+        linkerConfig = await readFile(linkerConfigPath, "utf-8");
+      }
       // Auto-inject bundled crt0 for SMS/GG when caller didn't pass one
       // (stock SDCC crt0 doesn't boot these targets — see buildSource).
       if (crt0 == null) {
@@ -714,6 +724,7 @@ export function registerToolchainTools(server, z, sessionKey) {
       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."),
       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({
         prgBanks: z.coerce.number().int().min(1).max(255).describe("16KB PRG-ROM banks (1 = NROM-128, 2 = NROM-256)."),
         chrBanks: z.coerce.number().int().min(0).max(255).optional().describe("8KB CHR-ROM banks (0 = CHR-RAM, no CHARS segment). Default 0."),
@@ -785,8 +796,8 @@ export function registerToolchainTools(server, z, sessionKey) {
  */
 export function projectBuildRecipe(platform, names) {
   const has = (n) => names.includes(n);
-  /** @type {{crt0File:string|null, codeLoc:number|undefined, linkerConfig:string|undefined, runtime:string|undefined, maxmod:boolean|undefined, skip:Set<string>, includeAsC:Set<string>}} */
-  const r = { crt0File: null, codeLoc: undefined, linkerConfig: undefined, runtime: undefined, maxmod: undefined, skip: new Set(), includeAsC: new Set() };
+  /** @type {{crt0File:string|null, codeLoc:number|undefined, dataLoc:number|undefined, linkerConfig:string|undefined, runtime:string|undefined, maxmod:boolean|undefined, skip:Set<string>, includeAsC:Set<string>}} */
+  const r = { crt0File: null, codeLoc: undefined, dataLoc: undefined, linkerConfig: undefined, runtime: undefined, maxmod: undefined, skip: new Set(), includeAsC: new Set() };
 
   // Reference/upstream sources ship for grepping, not compiling (e.g. GB
   // music_demo's hUGEDriver.upstream.asm — the .c port is what builds). Skip
@@ -796,7 +807,11 @@ export function projectBuildRecipe(platform, names) {
   if (platform === "gb" || platform === "gbc") {
     // GB/GBC ship gb_crt0.s — it MUST go via crt0+codeLoc:0x150, never as a
     // source (SDCC emits its own gsinit → "Multiple definition of gsinit").
-    if (has("gb_crt0.s")) { r.crt0File = "gb_crt0.s"; r.codeLoc = 0x150; }
+    // dataLoc 0xC200: statics start ABOVE shadow_oam ($C100-$C19F, fixed by
+    // the runtime). The sdld default of $C000 let any project with >256 bytes
+    // of statics silently overlap the OAM shadow — oam_clear() then zeroed
+    // game state (grid/RNG seed). 512 bytes of 8KB WRAM is cheap insurance.
+    if (has("gb_crt0.s")) { r.crt0File = "gb_crt0.s"; r.codeLoc = 0x150; r.dataLoc = 0xC200; }
   } else if (platform === "nes") {
     // A SCAFFOLDED NES project ships nes_runtime.c + a crt0 + a .cfg and needs
     // the chr-ram-runtime preset (it defines the OAM/CHARS segments + a NMI with
@@ -824,9 +839,17 @@ export function projectBuildRecipe(platform, names) {
     // msx_crt0.s through crt0 makes ITS header + init the cartridge entry.
     if (has("msx_crt0.s")) { r.crt0File = "msx_crt0.s"; r.codeLoc = 0x4010; }
   } else if (platform === "sms" || platform === "gg") {
-    // SMS/GG auto-inject their bundled crt0 inside buildForPlatform — so the
-    // scaffold's own *_crt0.s would be a DUPLICATE. Skip it.
-    for (const n of names) if (/_crt0\.s$/i.test(n)) r.skip.add(n);
+    // SMS/GG: route the project's *_crt0.s through the crt0 channel (like
+    // GB/MSX), NOT as a plain source TU. The OLD recipe skipped it on the
+    // belief that "buildForPlatform auto-injects the bundled crt0" — IT DOES
+    // NOT (only the output:'rom'/'run' MCP handlers auto-inject). So every
+    // output:'project' SMS/GG build linked SDCC's STOCK z80 crt0, whose boot
+    // is `ld a,#2 / rst $08 / halt` — main() never ran and every scaffold
+    // booted to a BLACK SCREEN (the RetroDECK "all broken" report; our
+    // output:'run' verifications were false-green via the other path).
+    // readProjectDir falls back to the bundled crt0 when the dir has none.
+    const crt0Name = names.find((n) => /_crt0\.s$/i.test(n));
+    if (crt0Name) r.crt0File = crt0Name;
   } else if (platform === "genesis" || platform === "megadrive" || platform === "md") {
     // SGDK supplies sega startup + rom header. The scaffold dir may contain
     // generated intermediates (sega.s, sega.preprocessed.s, rom_header.*, and an
@@ -919,6 +942,15 @@ export async function readProjectDir(projPath, platform) {
     }
   }
 
+  // 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
+  // screen at boot). The SMS scaffold historically shipped without a crt0
+  // file, so this fallback is load-bearing for existing project dirs.
+  if (crt0 == null && (platform === "sms" || platform === "gg")) {
+    crt0 = await resolveAutoCrt0(platform);
+  }
+
   // GBA runtime refinement: libgba if the entry includes <gba.h>, else the
   // libtonc default the recipe set.
   let runtime = recipe.runtime;
@@ -926,11 +958,11 @@ export async function readProjectDir(projPath, platform) {
     runtime = "libgba";
   }
 
-  return { sources, includes, binaryIncludes, crt0, codeLoc: recipe.codeLoc, linkerConfig: recipe.linkerConfig, runtime, maxmod: recipe.maxmod };
+  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, linkerConfig, runtime, maxmod } = await readProjectDir(projPath, platform);
+  const { sources, includes, binaryIncludes, crt0, codeLoc, dataLoc, linkerConfig, runtime, maxmod } = await readProjectDir(projPath, platform);
 
   // 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
@@ -968,6 +1000,7 @@ export async function buildProjectCore({ path: projPath, platform, outputPath })
     linkerConfig: resolvedLinkerConfig,
     crt0: crt0Rel,
     codeLoc,
+    dataLoc,
   });
   if (outputPath && result.binary) {
     await mkdir(path.dirname(outputPath), { recursive: true });

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

@@ -189,7 +189,7 @@ function noHitNote(sessionKey) {
     "(2) this region is rebuilt as a BLOCK rather than written field-by-field — sprite/OAM shadow tables, " +
     "display lists, and VRAM are typically bulk-copied (memcpy/loop) or DMA'd from a SOURCE struct elsewhere, " +
     "so no single instruction writes this exact byte. In that case the address you want is the SOURCE: watch " +
-    "the struct the copy reads from (find it with searchValue on the live value), or for graphics trace the " +
+    "the struct the copy reads from (find it with memory({op:'search'}) on the live value), or for graphics trace the " +
     "DMA/copy source (Genesis VRAM DMA source is in VDP regs). 'Address is wrong' is usually case (2), not a bad address.";
 }
 
@@ -452,7 +452,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         stoppedEarly,
         truncated,
         note: totalMatched === 0
-          ? "No matching changes in the watched window. Try (a) onChange:'any' to confirm the byte moves at all, (b) longer `frames`, (c) `pressDuring` to drive the game past the event, (d) a different region/offset. If the byte never moves even with onChange:'any', this region may be REBUILT as a block (sprite/OAM shadow, display list, VRAM) rather than written in place — watch the SOURCE struct the copy/DMA reads from instead (find it with searchValue)."
+          ? "No matching changes in the watched window. Try (a) onChange:'any' to confirm the byte moves at all, (b) longer `frames`, (c) `pressDuring` to drive the game past the event, (d) a different region/offset. If the byte never moves even with onChange:'any', this region may be REBUILT as a block (sprite/OAM shadow, display list, VRAM) rather than written in place — watch the SOURCE struct the copy/DMA reads from instead (find it with memory({op:'search'}))."
           : (tryGetPC(host) == null ? "PC not available for this platform (getCPUState returned no pc field)." : undefined),
       };
 
@@ -569,17 +569,29 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       const bankInfo = (prgOffset != null)
         ? { prgOffset: "0x" + prgOffset.toString(16).toUpperCase(), bank: Math.floor(prgOffset / 0x4000) }
         : null;
+      // The core snapshots the FULL register file inside the write hook (kind 3,
+      // all 14 platforms) — the break-instant truth; the live regs keep moving
+      // after the hit.
+      const wpSnap = host.getRegSnapshot ? host.getRegSnapshot(true) : null;
+      const wpRegs = (wpSnap && wpSnap.kind === 3) ? wpSnap.named : null;
       return attachObserverFrame(jsonContent({
         found: true,
         address: "$" + address.toString(16).toUpperCase(),
         pc: result.lastPC != null ? "$" + result.lastPC.toString(16).toUpperCase() : null,
         pcRaw: result.lastPC,
-        value: "0x" + result.lastValue.toString(16).toUpperCase().padStart(2, "0"),
+        // valueByte, not value: this is the ONE BYTE that landed on the watched
+        // address — a word/long store shows only its byte here, not the operand
+        // (a real session read 0x00 as "the move.l wrote zero").
+        valueByte: "0x" + result.lastValue.toString(16).toUpperCase().padStart(2, "0"),
         hits: result.hits,
         framesStepped: result.framesStepped,
+        ...(wpRegs ? { registersAtHit: wpRegs } : {}),
         ...(bankInfo ? bankInfo : {}),
         ...(presses.length ? { pressesScheduled: presses.length, pressesApplied: pressDriver.applied() } : {}),
         note: "pc is the EXACT writing instruction (captured in the CPU write path), not a frame sample. " +
+          "valueByte is the single byte written to the watched address (a 16/32-bit store shows only its byte here). " +
+          "hits counts watched-byte writes during the hit frame — the same instruction looping twice in one frame is hits:2, one event. " +
+          (wpRegs ? "registersAtHit is the register file frozen AT the write (the live regs drift for the rest of the frame — don't cpu({op:'read'}) instead). " : "") +
           (bankInfo
             ? `pc is in PRG bank ${bankInfo.bank} (prg offset ${bankInfo.prgOffset}) — disassembleRom({ startAddress: ${result.lastPC != null ? "0x" + result.lastPC.toString(16) : "pc"}, bank: ${bankInfo.bank} }) targets the exact bank (no fixed-bank $FF padding).`
             : `disassembleRom({ startAddress: ${result.lastPC != null ? "0x" + result.lastPC.toString(16) : "pc"} }) to see it. On a banked mapper a $8000-$BFFF pc may be in a switchable bank — pass the right \`bank\`.`),
@@ -659,16 +671,36 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         host.setPCBreak(0, false, false); // disarm
       }
       if (!hit) {
+        // Diagnostics on a miss (0.27.0 feedback #8): a bare "drive it with
+        // pressDuring" is useless when the caller DID supply input. Report
+        // where the CPU actually is, and tailor the advice.
+        const pcNow = tryGetPC(host);
+        const drove = presses.length > 0;
         return attachObserverFrame(jsonContent({
           hit: false, address: "$" + address.toString(16).toUpperCase(), framesRun,
           ...(presses.length ? { pressesScheduled: presses.length, pressesApplied: pressDriver.applied() } : {}),
-          note: "PC never reached that address within maxFrames. Either the code path didn't execute (drive it with pressDuring " +
-            "to reach the right game state), or the address isn't an instruction boundary (a mid-instruction address never matches REG_PC).",
+          ...(pcNow != null ? { pcNow: "$" + pcNow.toString(16).toUpperCase() } : {}),
+          note: (drove
+            ? "PC never reached that address within maxFrames EVEN WITH the scheduled input — so this is " +
+              "likely the WRONG ADDRESS for the path that actually ran (a different routine handles it), " +
+              "or the address isn't an instruction boundary (mid-instruction never matches REG_PC). "
+            : "PC never reached that address within maxFrames. Either the code path didn't execute (drive " +
+              "it with pressDuring to reach the right game state), or the address isn't an instruction " +
+              "boundary (mid-instruction never matches REG_PC). ") +
+            (pcNow != null ? "pcNow is the frame-boundary PC (usually the idle loop). " : "") +
+            "To find which code DID run, coverage-trace the suspect range: watch({on:'pc', start, end, frames}) " +
+            "returns every distinct PC executed there; or anchor on a RAM effect with breakpoint({on:'write'}).",
         }), host);
       }
       // Snapshot the registers AT the hit BEFORE clearing (last already holds the
-      // hit state; read it without clearing so registersAtHit survives).
-      const atHit = last.registersAtHit ?? host.getPCBreak(false).registersAtHit ?? null;
+      // hit state; read it without clearing so registersAtHit survives). Two
+      // snapshot transports: the fceumm-style inline pcbreak slots (A/X/Y/P/S)
+      // and the gpgx regsnap export (full m68k/z80 file — kind 1=pc-break,
+      // 2=watchdog).
+      const snapAtHit = host.getRegSnapshot ? host.getRegSnapshot(false) : null;
+      const atHit = last.registersAtHit
+        ?? host.getPCBreak(false).registersAtHit
+        ?? ((snapAtHit && (snapAtHit.kind === 1 || snapAtHit.kind === 2)) ? snapAtHit.named : null);
       // captureMemory: read the requested regions AT the hit (before we clear/step),
       // returned inline so break→read RAM collapses into ONE call. NOTE: registers
       // are the true break instant (core snapshot); these RAM reads are taken now —
@@ -700,8 +732,9 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       // end-of-frame state. Prefer registersAtHit; only fall back to a live read on
       // cores that don't snapshot.
       const frozenNote = atHit
-        ? "registersAtHit holds the register file CAPTURED AT this instruction (A/X/Y/P/S) — use THESE, not a follow-up cpu({op:'read'}), which on NES/fceumm returns end-of-frame state, not the break instant. For RAM at the hit, pass captureMemory:[{region,offset,length}] to get it inline (capturedMemory) in THIS call instead of a follow-up read. frame({op:'stepInstruction'}) to single-step from here."
+        ? "registersAtHit holds the register file CAPTURED AT the break instant — use THESE, not a follow-up cpu({op:'read'}), which returns end-of-frame state (the CPU/frame machinery keeps running after the hit). For RAM at the hit, pass captureMemory:[{region,offset,length}] to get it inline (capturedMemory) in THIS call instead of a follow-up read. frame({op:'stepInstruction'}) to single-step from here."
         : "This core does not snapshot registers at the hit. cpu({op:'read'}) reflects the CPU state now; on cores that run-to-frame-end (fceumm) that is NOT the break instant — prefer the RAM side effects (memory({op:'read'})) over the live register file.";
+      if (host.getRegSnapshot) host.getRegSnapshot(true); // consume the snapshot so a later bp can't read a stale one
       return attachObserverFrame(jsonContent({
         hit: true,
         address: "$" + address.toString(16).toUpperCase(),
@@ -711,7 +744,9 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         ...(capturedMemory ? { capturedMemory } : {}),
         frame: host.status.frameCount,
         framesRun,
-        hits: fin.hits,
+        // The core's hits counter doesn't tick on a watchdog stop — normalize so
+        // hit:true never reports hits:0 (a real session read that as contradictory).
+        hits: fin.hits || 1,
         ...(presses.length ? { pressesScheduled: presses.length, pressesApplied: pressDriver.applied() } : {}),
         note: frozenNote,
       }), host);
@@ -749,17 +784,21 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         });
       }
       const fin = host.getReadWatch(true);
+      const rdSnap = host.getRegSnapshot ? host.getRegSnapshot(true) : null;
+      const rdRegs = (rdSnap && rdSnap.kind === 4) ? rdSnap.named : null;
       return attachObserverFrame(jsonContent({
         hit: true,
         address: "$" + address.toString(16).toUpperCase(),
         pc: last.lastPC != null ? "$" + last.lastPC.toString(16).toUpperCase() : null,
         pcRaw: last.lastPC,
-        value: "0x" + (last.lastValue & 0xFF).toString(16).toUpperCase().padStart(2, "0"),
+        valueByte: "0x" + (last.lastValue & 0xFF).toString(16).toUpperCase().padStart(2, "0"),
         frame: host.status.frameCount,
         framesRun,
-        hits: fin.hits,
+        hits: fin.hits || 1,
+        ...(rdRegs ? { registersAtHit: rdRegs } : {}),
         ...(presses.length ? { pressesScheduled: presses.length, pressesApplied: pressDriver.applied() } : {}),
-        note: "pc is the EXACT instruction that read this address. disasm({ target:'rom', startAddress: pc }) to see it.",
+        note: "pc is the EXACT instruction that read this address. disasm({ target:'rom', startAddress: pc }) to see it." +
+          (rdRegs ? " registersAtHit is the register file frozen AT the read (the live regs drift for the rest of the frame)." : ""),
       }), host);
   }
 
@@ -782,10 +821,11 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     "use it, NOT a follow-up cpu({op:'read'}). On some cores (notably NES/fceumm) the core drains the cycle budget on hit but the frame still finishes, " +
     "so a live cpu read afterward returns END-OF-FRAME registers, not the break instant. `registersAtHit` sidesteps that. The break PC is reported as `pc`/`pcRaw`; " +
     "the RAM side effects are also reliable via memory({op:'read'}). frame({op:'stepInstruction'}) to single-step from the break. (on:'read'/'write' finish the frame.)\n" +
-    "All supported on every CPU core; `registersAtHit` is present on cores that snapshot regs (NES today); out-of-date core packages return notSupported.",
+    "All supported on every CPU core. **Every hit carries `registersAtHit` — the FULL register file frozen by the core AT the hit instant, on ALL 14 platforms and all three `on` kinds.** Use it instead of a follow-up cpu({op:'read'}): the live registers keep moving after a hit (per-scanline CPU scheduling / frame completion), so a post-hit read drifts — chasing pointer registers read that way burned a real session for hours. The hit `pc` is the EXECUTING instruction's first byte (mid-instruction hooks no longer report the operand-advanced PC). Out-of-date core packages return notSupported.\n" +
+    "MENU-SCREEN INPUT TRICK: if a pressDuring schedule never registers (some menu screens poll input in a way scheduled taps miss), HOLD the button instead: input({op:'set', buttons:{...}}) BEFORE this call and OMIT pressDuring — the run inherits the held state, the menu sees the edge, and the breakpoint catches the event.",
     {
       on: z.enum(["write", "read", "pc"])
-        .describe("write=break on a write to address (precision:exact=true writer PC / sampled=frame PC, a lie under IRQ); read=break on a read (exact PC, who consumes it); pc=break when PC reaches address — the hit returns `registersAtHit` (the break-instant A/X/Y/P/S on NES) + the break PC; use registersAtHit, not a follow-up cpu read (which is end-of-frame state on fceumm)."),
+        .describe("write=break on a write to address (precision:exact=true writer PC / sampled=frame PC, a lie under IRQ); read=break on a read (exact PC, who consumes it); pc=break when PC reaches address — the hit returns `registersAtHit` (the break-instant register file, all 14 platforms) + the break PC; use registersAtHit, not a follow-up cpu read (end-of-frame state)."),
       precision: z.enum(["exact", "sampled"]).default("exact")
         .describe("on:'write' ONLY. exact=core watchpoint, the real writing instruction PC even under interrupts (uses `address`). sampled=cheap frame-boundary PC (uses region/offset/length) — NOT the writer under IRQ. Ignored for on:read/pc (always exact)."),
       address: z.number().int().min(0).optional().describe("on:'write' exact / on:'read' / on:'pc' — CPU address to break on (write target, read target, or instruction boundary). Required for those."),
@@ -857,7 +897,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       return jsonContent({ regId, value: "0x" + (now >>> 0).toString(16).toUpperCase(), valueRaw: now });
   }
 
-  async function cpuCall({ pc, regs, sentinelPC = 0, stopAtPC, presetMemory, maxFrames = 600, maxInstructions, sandbox = false }) {
+  async function cpuCall({ pc, regs, sentinelPC = 0, stopAtPC, presetMemory, maxFrames = 600, maxInstructions, sandbox = false, pure = false }) {
       const host = getHost(sessionKey);
       if (!host.setRegSupported || !host.setRegSupported()) {
         return jsonContent({ returned: false, notSupported: true,
@@ -868,17 +908,28 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       const r = host.callSubroutine({
         pc, regs: numRegs, sentinelPC, stopAtPC,
         presetMemory: (presetMemory ?? []).map((m) => ({ addr: m.addr, hex: m.hex })),
-        maxFrames, ...(maxInstructions ? { maxInstructions } : {}), sandbox,
+        maxFrames, ...(maxInstructions ? { maxInstructions } : {}), sandbox, pure,
       });
-      const note = r.returned
+      // The poisoned-call caveat (a real session lost hours to this): when the
+      // call spanned FRAMES of emulation, the game's own per-frame logic (VBlank
+      // handlers via RAM vectors, music drivers) ran CONCURRENTLY and may have
+      // written over the routine's output buffer. Loud, up front, with the fix.
+      const frameLogicCaveat = (!pure && r.framesRun > 0 && (host.pureCallSupported ? host.pureCallSupported() : false))
+        ? ` ⚠ framesRun:${r.framesRun} — the game's own frame logic (VBlank handler, music driver) ran DURING this call and may have modified RAM the routine wrote; treat the output buffer as suspect. Re-run with pure:true to step ONLY the CPU (no frame machinery).`
+        : (!pure && r.framesRun > 0)
+          ? ` ⚠ framesRun:${r.framesRun} — the game's own frame logic ran DURING this call and may have modified RAM the routine wrote; treat the output buffer as suspect (verify visually or against a known-good slice).`
+          : "";
+      const note = (r.returned
         ? "Routine RETURNED. readMemory the buffer it wrote (e.g. the decompressor's A1 dest) now — sandbox:false leaves it live. (regs by reg-id: m68k 8=A0,9=A1,0=D0.)"
         : r.watchdog
           ? "WATCHDOG tripped (ran the instruction budget without returning) — almost always a wrong entry setup, not a long routine. Check finalPC (where it's spinning) + finalRegs (is A0 where you set it, or did it walk off?). Common fixes: correct A0 to the real block start (with its length header), add a presetMemory the codec reads, or pass a WRAPPER entryPC that sets up dest. Raise maxInstructions only if you're sure it's legitimately huge."
           : r.stoppedAtPC
             ? `Stopped at ${r.stoppedAtPC} (your stopAtPC) with PARTIAL output — readMemory the dst to see what's been written so far.`
-            : "Did not return within maxFrames AND the watchdog didn't trip — this usually means the entry FELL BACK INTO THE GAME (a wrapper PC with a wrong source, so it never reaches the sentinel) and the game is just free-running. finalPC is inside the main loop, not your routine. Re-check the entry PC (use the routine body, not a wrapper) and the source regs; or lower maxInstructions to fail fast while probing. Bump maxFrames/maxInstructions only if you're sure it's a legitimately huge decompress.";
+            : "Did not return within maxFrames AND the watchdog didn't trip — this usually means the entry FELL BACK INTO THE GAME (a wrapper PC with a wrong source, so it never reaches the sentinel) and the game is just free-running. finalPC is inside the main loop, not your routine. Re-check the entry PC (use the routine body, not a wrapper) and the source regs; or lower maxInstructions to fail fast while probing. Bump maxFrames/maxInstructions only if you're sure it's a legitimately huge decompress.")
+        + frameLogicCaveat;
       return jsonContent({
         returned: r.returned, framesRun: r.framesRun, sandbox,
+        ...(r.pure ? { pure: true, pureMode: r.pureMode } : {}),
         ...(r.watchdog ? { watchdog: true, reason: r.reason } : {}),
         ...(r.stoppedAtPC ? { stoppedAtPC: r.stoppedAtPC } : {}),
         ...(r.finalPC ? { finalPC: r.finalPC } : {}),
@@ -911,7 +962,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     "OP CHEAT-SHEET (the params each op uses): " +
     "read → {cpu?, platform?}; " +
     "setReg → {regId, value}; " +
-    "call → {pc, regs?, sandbox?, maxInstructions?, sentinelPC?, stopAtPC?, presetMemory?, maxFrames?}; " +
+    "call → {pc, regs?, pure?, sandbox?, maxInstructions?, sentinelPC?, stopAtPC?, presetMemory?, maxFrames?}; " +
     "decompress → {entryPC, sourceAddress, destAddress?, maxFrames?}.\n" +
     "• op:'read' — read a CPU's {pc, registers, flags, sp}. Main CPU wired for all 14 tier-1 systems (nes, snes, " +
     "genesis, sms, gg, gb, gbc, atari2600, atari7800, c64, lynx, gba (ARM7TDMI: 16 gprs + cpsr/spsr + execPc for " +
@@ -924,7 +975,13 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     "buffer it wrote stays live for memory({op:'read'}).** Classic use: drive a decompressor (A0=source, A1=dest) then read " +
     "the dst. **NEVER HANGS: an instruction WATCHDOG (`maxInstructions`) force-stops a runaway and returns PROGRESS — " +
     "finalPC + finalRegs + watchdog:true — so you can tell 'wrong A0' from 'needs a preset' from 'legitimately long'.** " +
-    "`stopAtPC` halts mid-routine for partial output; `presetMemory` for codecs that read a global from RAM first.\n" +
+    "`stopAtPC` halts mid-routine for partial output; `presetMemory` for codecs that read a global from RAM first. " +
+    "**`pure:true` (ALL 14 platforms): the game's own VBlank/IRQ logic CANNOT run during the call and stomp the routine's " +
+    "output buffer.** Mechanism per platform (reported as `pureMode`): Genesis/SMS/GG step ONLY the CPU ('cpu-only'); every " +
+    "other core suppresses interrupt DELIVERY for the duration ('irq-blocked' — video/timers advance harmlessly, no game " +
+    "handler executes); the 2600 has no interrupts at all ('no-interrupts'). Without pure, a call that spans frames runs " +
+    "the game's frame logic alongside your routine (the result carries a ⚠ caveat) — a real session spent " +
+    "hours diffing a CORRECT codec against that poisoned output. Prefer pure for every decompressor/codec call.\n" +
     "• op:'decompress' — convenience wrapper over op:'call' for the common decompressor shape: call `entryPC` with " +
     "A0=`sourceAddress` (and optionally A1=`destAddress`), run until it returns, then read `destAddress`. For the " +
     "NBA-Jam-style 'name + portrait are LZ-compressed' wall: point it at the game's own decompressor.",
@@ -949,6 +1006,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       maxFrames: z.number().int().min(1).max(100000).default(600).describe("op:call/decompress — frame cap (the outer bound)."),
       maxInstructions: z.number().int().min(1000).optional().describe("op:call — instruction watchdog budget (the REAL cap; default ~maxFrames*500k). Raise for a huge decompress; lower to fail fast while probing the right A0."),
       sandbox: z.boolean().default(false).describe("op:call — snapshot+restore core state around the call (default FALSE — you want the dst buffer left live to read). True leaves the live game untouched."),
+      pure: z.boolean().default(false).describe("op:call — guarantee the game's own frame logic CANNOT run during the call and stomp the routine's output (ALL 14 platforms; `pureMode` in the result says how: 'cpu-only' on Genesis/SMS/GG, 'irq-blocked' elsewhere, 'no-interrupts' on 2600). Prefer this for any decompressor/codec call."),
       // decompress
       entryPC: z.number().int().min(0).optional().describe("op:decompress — decompressor entry PC."),
       sourceAddress: z.number().int().min(0).optional().describe("op:decompress — compressed-source address → A0 (reg-id 8 on m68k)."),
@@ -1044,10 +1102,11 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     "**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.) `fromState`/`fromStatePath` restores a savestate FIRST so the trace runs from a known moment (jump to the boss, then see what writes HP) — deterministic + repeatable.\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. Also takes `fromState`/`fromStatePath` to trace from a restored moment.\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). `perFrame:true` switches to FEEL/PERF MODE: a per-frame timeline of VDP-DMA WORK ({frame,dmas,bytes,romBytes,ramBytes} + peakFrame + `spikes`) — the cheap 'why does horizontal movement feel choppy?' diagnostic (a per-frame byte spike = too much VDP work in the loop, e.g. a tilemap rewrite). On non-Genesis cores returns `notSupported`.",
+    "• 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). `perFrame:true` switches to FEEL/PERF MODE: a per-frame timeline of VDP-DMA WORK ({frame,dmas,bytes,romBytes,ramBytes} + peakFrame + `spikes`) — the cheap 'why does horizontal movement feel choppy?' diagnostic (a per-frame byte spike = too much VDP work in the loop, e.g. a tilemap rewrite). On non-Genesis cores returns `notSupported`.\n" +
+    "• on:'copy' — ALL 14 PLATFORMS: log every write landing in a VRAM/dest address window [start,end] with the EXECUTING instruction's PC — the generic answer to 'this tile/nametable/portrait on screen: which routine uploads it?'. Port-based video memory (NES $2007, SNES $2118/19 — incl. the DMA path, PCE VWR, MSX/SMS/GG VDP data port, Genesis data port) is hooked INSIDE the core, so `start`/`end` are VRAM addresses (NES PPU $0000-$3FFF; SNES VRAM byte addr; PCE VRAM word addr; MSX/SMS/GG VRAM addr). Direct-mapped platforms (GB/GBC $8000-$9FFF, GBA 0x06000000+, C64/Lynx/7800 RAM framebuffers) route through the CPU-address range log automatically — pass CPU addresses there. Follow up with breakpoint({on:'pc', address: pc}) to get registersAtHit at the uploader.",
     {
-      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: z.enum(["mem", "range", "pc", "dma", "copy"])
+        .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; copy=log every write landing in a VRAM address window with the EXECUTING instruction's PC (all 14 platforms — the generic 'where does this graphic come from?')."),
       // 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."),
@@ -1084,7 +1143,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         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, or uploads the graphic for on:'dma'). If OMITTED, this run inherits whatever input({op:'set'}) last held — same as frame({op:'step'}). If GIVEN, the schedule OWNS the pad for the whole run (a prior input({op:'set'}) is ignored). Entries with OVERLAPPING windows on the same port are OR'd into a chord (e.g. b+right held while a fires mid-window), not overwritten."),
+      })).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'). If OMITTED, this run inherits whatever input({op:'set'}) last held — same as frame({op:'step'}). If GIVEN, the schedule OWNS the pad for the whole run (a prior input({op:'set'}) is ignored). Entries with OVERLAPPING windows on the same port are OR'd into a chord (e.g. b+right held while a fires mid-window), not overwritten. MENU SCREENS: if a schedule never registers (some menus poll input in a way scheduled taps miss), hold the button via input({op:'set'}) and OMIT pressDuring — the run inherits the held state and the menu sees the edge."),
       fromState: z.string().optional().describe("on:'range'/'pc' — restore an in-memory savestate SLOT (from state({op:'save', name})) BEFORE tracing, so the log runs from a known moment (jump to the boss fight, then see what writes HP). Deterministic + repeatable."),
       fromStatePath: z.string().optional().describe("on:'range'/'pc' — like fromState but restore from a savestate FILE on disk (state({op:'save', path})). Relative path resolves against the loaded ROM's dir."),
     },
@@ -1107,11 +1166,69 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
           }
           return await dmaExact(a);
         }
+        case "copy": {
+          if (args.start == null || args.end == null) throw new Error("watch({on:'copy'}): `start` and `end` are required (the VRAM/dest address window).");
+          return await wCopy({ ...args, frames: args.frames ?? 120, limit: args.limit ?? 200 });
+        }
         default: throw new Error(`watch: unknown on '${args.on}'`);
       }
     }),
   );
 
+  // ── watch({on:'copy'}) — the generic graphics source-trace ─────────────────
+  async function wCopy({ start, end, frames = 120, limit = 200, pressDuring }) {
+      const host = getHost(sessionKey);
+      const presses = (pressDuring ?? []).slice().sort((a, b) => a.frame - b.frame);
+      const pressDriver = makePressDriver(host, presses);
+      if (host.vramWatchSupported && host.vramWatchSupported()) {
+        // Port-based video memory: the core hook logs {vramAddr, pc, value}
+        // with the EXECUTING instruction's PC (DMA-initiating instruction on
+        // SNES). start/end are VRAM addresses.
+        let i = 0;
+        const r = host.watchVram(start, end, frames, () => { pressDriver.applyForFrame(i++); return false; });
+        pressDriver.finish();
+        const events = r.events.slice(0, limit).map((e) => ({
+          vramAddr: "$" + e.vramAddr.toString(16).toUpperCase(),
+          pc: "$" + e.pc.toString(16).toUpperCase(),
+          pcRaw: e.pc,
+          value: "0x" + e.value.toString(16).toUpperCase().padStart(2, "0"),
+        }));
+        const distinct = [...new Set(r.events.map((e) => e.pc))].slice(0, 32)
+          .map((p) => "$" + p.toString(16).toUpperCase());
+        return jsonContent({
+          on: "copy", mode: "vram-port",
+          window: { start: "$" + start.toString(16).toUpperCase(), end: "$" + end.toString(16).toUpperCase() },
+          framesRun: frames,
+          total: r.total, stored: r.stored, truncated: r.truncated,
+          distinctPCs: distinct,
+          events,
+          note: "pc is the EXECUTING instruction that performed the upload (on SNES the instruction that " +
+            "triggered the DMA). Addresses are VRAM-space. Next: breakpoint({on:'pc', address: <pc>}) to stop " +
+            "there with registersAtHit (source pointer in the index/address regs), then disasm({target:'rom', " +
+            "startAddress: <pc>}) to read the routine." +
+            (r.truncated ? " Ring overflowed — narrow the window or lower frames." : ""),
+        });
+      }
+      // Direct-mapped video memory (GB/GBC/GBA/C64/Lynx/7800): the same
+      // question routes through the CPU-address range log — start/end are CPU
+      // addresses (e.g. GB VRAM $8000-$9FFF).
+      pressDriver.finish();
+      const out = await wRange({ start, end, frames, limit, kind: "write", pressDuring });
+      try {
+        const parsed = JSON.parse(out.content.find((c) => c.type === "text").text);
+        parsed.on = "copy";
+        parsed.mode = "cpu-mapped";
+        parsed.note = (parsed.note ? parsed.note + " " : "") +
+          "This platform's video memory is CPU-mapped, so the copy trace IS the write-range log: " +
+          "start/end are CPU addresses (GB/GBC VRAM $8000-$9FFF; GBA 0x06000000+; C64/Lynx/7800 use the " +
+          "framebuffer/display-list RAM range). pc is the executing instruction; follow up with " +
+          "breakpoint({on:'pc', address: pc}) for registersAtHit.";
+        return jsonContent(parsed);
+      } catch {
+        return out;
+      }
+  }
+
   // ── watch({on:'dma'}) helpers (Genesis only) ────────────────────────────────
   // precision:exact = dmaExact (watchDma, per-DMA core log), precision:sampled =
   // traceVramSourceCore (frame-sampled, dest-agnostic). Routed by the `watch`