romdev-mcp 0.1.1

package/src/mcp/tools/font-map.js

@@ -0,0 +1,353 @@
+// learnFontMap / encodeTextForRom / findEncodedText — text-hack workflow.
+//
+// Every retro game maps characters to tile-IDs differently (Excitebike:
+// A=$0A, B=$0B, ..., Z=$23; Mario: ASCII offset; FF: sparse table). The
+// agent currently reverse-engineers this by hand each session. These
+// three tools automate it:
+//
+//   1. learnFontMap   — from known {text, offset} hints, infer the map.
+//   2. encodeTextForRom — text + map → bytes (ready for patchFile).
+//   3. findEncodedText — text + map → list of file offsets + cpu addr +
+//                        context + likelySlotLength (catches length-byte
+//                        overruns).
+//
+// All three are platform-agnostic — the mapping is per-ROM, not per-
+// platform. The `platform` arg is only used for CPU-address translation
+// in findEncodedText (reuses mapNesAddress/mapSnesAddress from disasm).
+
+import { readFile, writeFile } from "node:fs/promises";
+import { jsonContent, safeTool } from "../util.js";
+import { mapNesAddress, mapSnesAddress } from "./disasm.js";
+
+// ─── learnFontMap ────────────────────────────────────────────────
+
+/**
+ * Infer the character → tile-ID map from known-text-at-known-offset hints.
+ * Solves the system of equations: for each {text, offset} pair, the byte
+ * at offset+i must equal map[text[i]].
+ *
+ * Conflicts: if two known strings disagree on a character, throw with
+ * both candidate values so the agent can investigate.
+ */
+async function learnFontMapCore({ romPath, knownStrings, alphabet }) {
+  const data = new Uint8Array(await readFile(romPath));
+  /** @type {Record<string, number>} */
+  const fontMap = {};
+  /** @type {Array<{text:string, offset:number, mappedChars:string}>} */
+  const inferredFrom = [];
+
+  for (const hint of knownStrings) {
+    const { text, offset } = hint;
+    let mapped = "";
+    for (let i = 0; i < text.length; i++) {
+      const ch = text[i];
+      const byte = data[offset + i];
+      if (byte === undefined) {
+        throw new Error(
+          `learnFontMap: hint {text: "${text}", offset: 0x${offset.toString(16).toUpperCase()}} ` +
+          `extends past EOF — char '${ch}' at position ${i} would read byte ${offset + i} but ROM is ${data.length} bytes.`
+        );
+      }
+      if (fontMap[ch] !== undefined && fontMap[ch] !== byte) {
+        throw new Error(
+          `learnFontMap: conflict on character '${ch}'. ` +
+          `Earlier hint mapped it to 0x${fontMap[ch].toString(16).toUpperCase()}; ` +
+          `this hint (text="${text}", offset=0x${offset.toString(16).toUpperCase()}, position=${i}) ` +
+          `says 0x${byte.toString(16).toUpperCase()}. Check that both hints' offsets are correct AND ` +
+          `the source bytes weren't already patched.`
+        );
+      }
+      fontMap[ch] = byte;
+      mapped += ch;
+    }
+    inferredFrom.push({ text, offset, mappedChars: mapped });
+  }
+
+  const alphabetSet = alphabet ?? "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 ©";
+  const unknownChars = [];
+  for (const ch of alphabetSet) {
+    if (fontMap[ch] === undefined) unknownChars.push(ch);
+  }
+
+  return {
+    romPath,
+    fontMap,
+    learnedChars: Object.keys(fontMap).sort().join(""),
+    unknownChars,
+    inferredFrom,
+  };
+}
+
+// ─── encodeTextForRom ────────────────────────────────────────────
+
+function hex2(n) {
+  return n.toString(16).toUpperCase().padStart(2, "0");
+}
+
+async function encodeTextForRomCore({ text, fontMap, fontMapPath, unknownChar }) {
+  let map = fontMap;
+  if (!map && fontMapPath) {
+    map = JSON.parse(await readFile(fontMapPath, "utf-8"));
+    // Accept both {fontMap:{...}} and a bare {ch:byte} shape.
+    if (map.fontMap) map = map.fontMap;
+  }
+  if (!map) {
+    throw new Error("encodeTextForRom: must pass either fontMap (inline) or fontMapPath.");
+  }
+  const fallback = unknownChar ?? 0xFC; // NES blank-tile convention
+  const bytes = [];
+  const unknownChars = [];
+  for (const ch of text) {
+    const b = map[ch];
+    if (b === undefined) {
+      bytes.push(fallback);
+      if (!unknownChars.includes(ch)) unknownChars.push(ch);
+    } else {
+      bytes.push(b & 0xFF);
+    }
+  }
+  return {
+    text,
+    bytes,
+    hex: bytes.map(hex2).join(" "),
+    base64: Buffer.from(bytes).toString("base64"),
+    length: bytes.length,
+    unknownChars,
+    fallbackUsed: unknownChars.length > 0 ? "0x" + hex2(fallback) : null,
+  };
+}
+
+// ─── findEncodedText ─────────────────────────────────────────────
+
+/**
+ * Build the reverse map (byte → char) from a forward map. For findEncodedText
+ * to render contextBefore/contextAfter as readable text.
+ */
+function reverseMap(fontMap) {
+  const rev = {};
+  for (const [ch, byte] of Object.entries(fontMap)) {
+    if (rev[byte] === undefined) rev[byte] = ch;
+  }
+  return rev;
+}
+
+/**
+ * Decode bytes around a match site to readable text using the reverse map.
+ * Unknown bytes are rendered as ·.
+ */
+function decodeContext(data, start, end, rev) {
+  let out = "";
+  for (let i = start; i < end; i++) {
+    if (i < 0 || i >= data.length) continue;
+    out += rev[data[i]] ?? "·";
+  }
+  return out;
+}
+
+/**
+ * Detect a plausible length-prefix byte preceding the match. Many ROMs
+ * store text with a leading "length" byte (PPU command, RLE marker, etc).
+ * If the byte at offset-1, offset-2, or offset-3 equals the match length
+ * (or length-1 / length+1), report it as a possible slot-length.
+ */
+function detectLengthByte(data, offset, matchLen) {
+  for (let probe = 1; probe <= 4; probe++) {
+    const at = offset - probe;
+    if (at < 0) continue;
+    const v = data[at];
+    if (v === matchLen || v === matchLen - 1 || v === matchLen + 1) {
+      return { atOffset: at, value: v, distance: probe };
+    }
+  }
+  return null;
+}
+
+async function findEncodedTextCore({ romPath, text, fontMap, fontMapPath, platform, maxResults = 16 }) {
+  let map = fontMap;
+  if (!map && fontMapPath) {
+    const parsed = JSON.parse(await readFile(fontMapPath, "utf-8"));
+    map = parsed.fontMap ?? parsed;
+  }
+  if (!map) {
+    throw new Error("findEncodedText: must pass either fontMap (inline) or fontMapPath.");
+  }
+  // Encode the search needle.
+  const needle = [];
+  const unknown = [];
+  for (const ch of text) {
+    const b = map[ch];
+    if (b === undefined) {
+      unknown.push(ch);
+      needle.push(null); // wildcard
+    } else {
+      needle.push(b & 0xFF);
+    }
+  }
+  if (unknown.length > 0) {
+    // Don't bail — wildcards still find partial matches.
+  }
+
+  const data = new Uint8Array(await readFile(romPath));
+  const rev = reverseMap(map);
+  const matches = [];
+
+  for (let i = 0; i + needle.length <= data.length; i++) {
+    let ok = true;
+    for (let j = 0; j < needle.length; j++) {
+      if (needle[j] !== null && data[i + j] !== needle[j]) {
+        ok = false;
+        break;
+      }
+    }
+    if (!ok) continue;
+
+    // Build context.
+    const ctxBefore = decodeContext(data, i - 8, i, rev);
+    const ctxAfter = decodeContext(data, i + needle.length, i + needle.length + 8, rev);
+    const surrStart = Math.max(0, i - 4);
+    const surrEnd = Math.min(data.length, i + needle.length + 4);
+    const surroundingHex = Array.from(data.slice(surrStart, surrEnd))
+      .map((b, k) => {
+        const absIdx = surrStart + k;
+        const inMatch = absIdx >= i && absIdx < i + needle.length;
+        return inMatch ? `[${hex2(b)}]` : hex2(b);
+      })
+      .join(" ");
+
+    const lengthByte = detectLengthByte(data, i, needle.length);
+
+    let cpuAddress = null;
+    if (platform) {
+      try {
+        // Reverse the mapper math: find CPU addr whose mapped fileOffset equals i.
+        // For NES NROM, file offset → CPU addr is: i - 16 (header) + ($C000 if NROM-128 else $8000).
+        if (platform === "nes") {
+          const prgStart = 16;
+          const prgSize = data[4] * 16384;
+          if (i >= prgStart && i < prgStart + prgSize) {
+            const offInPrg = i - prgStart;
+            if (prgSize === 16384) {
+              cpuAddress = "$" + (0xC000 + offInPrg).toString(16).toUpperCase();
+            } else {
+              cpuAddress = "$" + (0x8000 + offInPrg).toString(16).toUpperCase();
+            }
+          }
+        }
+      } catch {
+        // Outside ROM region — leave cpuAddress null.
+      }
+    }
+
+    // PRG-frame offset (NES: subtract the 16-byte iNES header). Useful
+    // because patchFile against `prg.bin` (from extractCart) needs the
+    // header-less offset, while patchFile against the .nes file uses the
+    // raw `fileOffset`. Emit BOTH to remove that footgun.
+    let prgFileOffset = null;
+    let prgFileOffsetDec = null;
+    if (platform === "nes" && i >= 16) {
+      const prgSize = data[4] * 16384;
+      if (i < 16 + prgSize) {
+        prgFileOffsetDec = i - 16;
+        prgFileOffset = "0x" + prgFileOffsetDec.toString(16).toUpperCase();
+      }
+    }
+
+    matches.push({
+      fileOffset: "0x" + i.toString(16).toUpperCase(),
+      fileOffsetDec: i,
+      prgFileOffset,
+      prgFileOffsetDec,
+      cpuAddress,
+      contextBefore: ctxBefore,
+      contextAfter: ctxAfter,
+      surroundingHex,
+      likelySlotLength: lengthByte
+        ? { atFileOffset: "0x" + lengthByte.atOffset.toString(16).toUpperCase(),
+            value: lengthByte.value,
+            distanceFromMatch: lengthByte.distance,
+            hint: `byte ${lengthByte.distance} before the match equals match length (${lengthByte.value} ≈ ${needle.length}); ` +
+              `looks like a length prefix. Don't write more than ${lengthByte.value} bytes at the match offset OR the next ` +
+              `tile-list command will start parsing your replacement bytes as commands.`,
+          }
+        : null,
+    });
+    if (matches.length >= maxResults) break;
+  }
+
+  return {
+    romPath,
+    text,
+    needleHex: needle.map((b) => b === null ? "??" : hex2(b)).join(" "),
+    wildcardChars: unknown,
+    matchesFound: matches.length,
+    matches,
+    truncated: matches.length === maxResults ? `Stopped at maxResults=${maxResults}. Raise to see more.` : undefined,
+  };
+}
+
+// ─── MCP registration ────────────────────────────────────────────
+
+export function registerFontMapTools(server, z) {
+  server.tool(
+    "learnFontMap",
+    "Use this to infer a ROM's custom character→tile-ID map (most retro games use their own font " +
+    "encoding) from known-text-at-known-offset hints, instead of reverse-engineering it by hand. Workflow: " +
+    "find a recognizable on-screen string, locate its bytes in the ROM, pass `{text, offset}` hints; " +
+    "returns `{fontMap, learnedChars, unknownChars}` — save it as JSON and pass `fontMapPath` to " +
+    "encodeTextForRom / findEncodedText. Throws on conflicting hints (usually a wrong offset). Per-ROM, " +
+    "not per-platform.",
+    {
+      romPath: z.string().describe("Absolute path to the ROM file."),
+      platform: z.string().optional().describe("Optional — purely informational here; reuses the same map regardless of platform."),
+      knownStrings: z.array(z.object({
+        text: z.string().describe("The string you can see rendered in-game."),
+        offset: z.number().int().min(0).describe("File offset where those bytes live in the ROM (find via findEncodedText hints or inspection)."),
+      })).min(1).describe("Hints. One or more is enough to start; more hints cover more of the alphabet."),
+      alphabet: z.string().optional().describe("Which characters to track in unknownChars[]. Default: A-Z, 0-9, space, ©."),
+    },
+    safeTool(async (args) => {
+      const r = await learnFontMapCore(args);
+      return jsonContent(r);
+    }),
+  );
+
+  server.tool(
+    "encodeTextForRom",
+    "Encode a text string to ROM bytes using a font map. Inverse of learnFontMap. Returns hex AND " +
+    "base64, ready to feed directly into patchFile.hex / patchFile.base64.\n\n" +
+    "Unknown characters fall back to `unknownChar` (default 0xFC = NES blank tile) and are listed " +
+    "in `unknownChars[]` so you can investigate. For non-NES platforms with a different blank " +
+    "convention, pass an explicit `unknownChar`.",
+    {
+      text: z.string().describe("The text to encode."),
+      fontMap: z.record(z.string(), z.number().int().min(0).max(255)).optional().describe("Inline char→byte map."),
+      fontMapPath: z.string().optional().describe("JSON file containing the font map (either {fontMap:{...}} or a bare {ch:byte} object)."),
+      unknownChar: z.number().int().min(0).max(255).optional().describe("Fallback byte for characters not in the map. Default 0xFC (NES blank-tile convention)."),
+    },
+    safeTool(async (args) => {
+      const r = await encodeTextForRomCore(args);
+      return jsonContent(r);
+    }),
+  );
+
+  server.tool(
+    "findEncodedText",
+    "Use this to locate a text string in a ROM via a font map (from learnFontMap) — decodes surrounding " +
+    "context bytes and flags a likely length-prefix byte before each match (catches the classic off-by-one " +
+    "where text has a leading length byte and overwriting past it corrupts the next command). Returns both " +
+    "`fileOffset` (raw .nes, for patching the .nes file) and `prgFileOffset` (header-stripped, for prg.bin " +
+    "from extractCart), plus NES mapper-aware `cpuAddress` for disassembleRom.",
+    {
+      romPath: z.string().describe("Absolute path to the ROM."),
+      text: z.string().describe("Text to search for."),
+      fontMap: z.record(z.string(), z.number().int().min(0).max(255)).optional(),
+      fontMapPath: z.string().optional(),
+      platform: z.enum(["nes", "snes", "genesis", "megadrive", "md", "gb", "gbc"]).optional().describe("Optional — enables CPU-address translation in the response."),
+      maxResults: z.number().int().min(1).max(256).default(16),
+    },
+    safeTool(async (args) => {
+      const r = await findEncodedTextCore(args);
+      return jsonContent(r);
+    }),
+  );
+}

package/src/mcp/tools/frame.js

@@ -0,0 +1,249 @@
+import { writeFile } from "node:fs/promises";
+import { PNG } from "pngjs";
+import { getHost } from "../state.js";
+import { imageContent, jsonContent, safeTool } from "../util.js";
+import { decodeOAM, decodePpuRegs, ppuRegsPopulated } from "../../platforms/snes/ppu.js";
+
+// Get the platform's visible sprites in the generic shape, or null if
+// not supported. Drives the screenshot overlay AND any future agents
+// that want a one-call "what sprites are on screen right now."
+function visibleSpritesFor(host, platform) {
+  if (platform === "snes") {
+    try {
+      const oam = host.readMemory("snes_oam", 0, 544);
+      const fillram = host.readMemory("snes_fillram", 0, 0x8000);
+      const ppu = ppuRegsPopulated(fillram) ? decodePpuRegs(fillram) : null;
+      const sprites = decodeOAM(oam, ppu ? {
+        smallSize: ppu.objSize.small, largeSize: ppu.objSize.large,
+        objNameBaseByte: ppu.objNameBaseByte, objGapByte: ppu.objGapByte,
+      } : {});
+      // Overlay only the truly renderable sprites — not every populated OAM
+      // slot. Off-screen/hidden slots would clutter the screenshot with boxes
+      // for sprites that aren't actually drawn.
+      return sprites.filter((s) => s.renderable);
+    } catch { return null; }
+  }
+  if (platform === "nes") {
+    try {
+      const oam = host.readMemory("nes_oam", 0, 256);
+      const out = [];
+      for (let i = 0; i < 64; i++) {
+        const o = i * 4;
+        const y = oam[o + 0];
+        if (y >= 0xEF) continue; // NES "off-screen" Y
+        out.push({
+          slot: i, x: oam[o + 3], y, tile: oam[o + 1],
+          size: { w: 8, h: 8 },
+        });
+      }
+      return out;
+    } catch { return null; }
+  }
+  return null;
+}
+
+/**
+ * Decode a PNG, draw a colored 1-pixel rectangle for each sprite, and
+ * re-encode. Sprite color is derived from slot so two sprites at the same
+ * coords get distinguishable boxes. NES Y values are pre-incremented by
+ * 1 (the convention from the hardware); we follow each platform's reading.
+ */
+function overlaySpriteBoxes(pngBase64, sprites, platform) {
+  const buf = Buffer.from(pngBase64, "base64");
+  const img = PNG.sync.read(buf);
+  const W = img.width, H = img.height;
+  // NES: Y in OAM is "actual Y - 1" — most modern emulators expose the
+  // raw OAM byte. Add 1 to display the screen-pixel coord.
+  const yShift = platform === "nes" ? 1 : 0;
+  for (const s of sprites) {
+    const x = s.x | 0;
+    const y = (s.y | 0) + yShift;
+    const w = s.size?.w ?? 8;
+    const h = s.size?.h ?? 8;
+    if (x >= W || y >= H || x + w <= 0 || y + h <= 0) continue;
+    // Pick a distinguishable color per slot. HSV-ish via slot * 47 mod 360.
+    const hue = (s.slot * 47) % 360;
+    const [r, g, b] = hsvToRgb(hue / 360, 1, 1);
+    drawRect(img.data, W, H, x, y, w, h, r, g, b);
+  }
+  return PNG.sync.write(img);
+}
+
+function drawRect(data, W, H, x, y, w, h, r, g, b) {
+  const set = (px, py) => {
+    if (px < 0 || px >= W || py < 0 || py >= H) return;
+    const o = (py * W + px) * 4;
+    data[o] = r; data[o + 1] = g; data[o + 2] = b; data[o + 3] = 0xFF;
+  };
+  for (let dx = 0; dx < w; dx++) {
+    set(x + dx, y);
+    set(x + dx, y + h - 1);
+  }
+  for (let dy = 0; dy < h; dy++) {
+    set(x, y + dy);
+    set(x + w - 1, y + dy);
+  }
+}
+
+function hsvToRgb(h, s, v) {
+  const i = Math.floor(h * 6);
+  const f = h * 6 - i;
+  const p = v * (1 - s);
+  const q = v * (1 - f * s);
+  const t = v * (1 - (1 - f) * s);
+  let r = 0, g = 0, b = 0;
+  switch (i % 6) {
+    case 0: r = v; g = t; b = p; break;
+    case 1: r = q; g = v; b = p; break;
+    case 2: r = p; g = v; b = t; break;
+    case 3: r = p; g = q; b = v; break;
+    case 4: r = t; g = p; b = v; break;
+    case 5: r = v; g = p; b = q; break;
+  }
+  return [Math.round(r * 255), Math.round(g * 255), Math.round(b * 255)];
+}
+
+export function registerFrameTools(server, z, sessionKey) {
+  server.tool(
+    "stepFrames",
+    "Advance emulation by N frames as fast as possible — NO real-time pacing, NO audio sync, NO vsync. Cores run at WASM speed: NES ~6-15k fps, SNES/Genesis ~2-5k fps, GB ~10k+ fps. That means stepFrames(3600) = 1 minute of game time in ~5-30ms (cheaper than a screenshot). Don't be timid: skip past title screens with stepFrames(300), advance through a level with stepFrames(7200) = 2 minutes, etc. Prefer ONE big call over many small ones. Returns the new frame count and framebuffer dimensions. Default 1 frame.",
+    {
+      frames: z.number().int().min(1).max(1_000_000).default(1).describe("Number of frames to step (1-1,000,000). Don't be conservative — 36000 frames (10 min) typically completes in <1s."),
+    },
+    safeTool(async ({ frames }) => {
+      const host = getHost(sessionKey);
+      const n = host.stepFrames(frames);
+      return jsonContent({
+        framesRun: n,
+        frameCount: host.status.frameCount,
+        framebuffer: { width: host.status.fbWidth, height: host.status.fbHeight },
+      });
+    }),
+  );
+
+  // Contract: an image goes to disk (path) OR comes back inline (inline:true).
+  // No path + not inline → error. Keeps PNGs out of context unless asked for.
+  function requireImageTarget(outPath, inline, tool) {
+    if (!outPath && !inline) {
+      throw new Error(`${tool}: pass path (write the image to disk, returns {path}) or inline:true (return the image in the response).`);
+    }
+  }
+
+  // PNG capture. Writes to outPath, or returns inline when `inline`.
+  async function shootPng({ path: outPath, inline, overlayBoxes }) {
+    const host = getHost(sessionKey);
+    const shot = host.screenshot();
+    let pngBase64 = shot.pngBase64;
+    let overlayInfo = null;
+    if (overlayBoxes) {
+      const platform = host.status.platform;
+      const sprites = visibleSpritesFor(host, platform);
+      if (sprites) {
+        const overlaid = overlaySpriteBoxes(pngBase64, sprites, platform);
+        pngBase64 = overlaid.toString("base64");
+        overlayInfo = { platform, spritesDrawn: sprites.length };
+      } else {
+        overlayInfo = { platform, spritesDrawn: 0, note: `overlay not yet supported for '${platform}'` };
+      }
+    }
+    if (!inline) {
+      await writeFile(outPath, Buffer.from(pngBase64, "base64"));
+      const json = jsonContent({ path: outPath, width: shot.width, height: shot.height, overlay: overlayInfo });
+      json._observerImages = [{ kind: "image", mimeType: "image/png", base64: pngBase64 }];
+      return json;
+    }
+    return {
+      content: [
+        imageContent(pngBase64),
+        { type: "text", text: `framebuffer ${shot.width}x${shot.height}${overlayInfo ? ` (overlay: ${overlayInfo.spritesDrawn} sprites)` : ""}` },
+      ],
+    };
+  }
+
+  // ASCII/ANSI capture.
+  async function shootAscii({ cols, rows, symbols, colors, path: outPath, inline }) {
+    const host = getHost(sessionKey);
+    const { width, height, rgba } = host.screenshotRgba();
+    // Default each cell to "2 game tiles" (8×8 platforms) so the grid maps
+    // to tile coords: cell (c,r) covers tiles (c*2..c*2+1, r*2..r*2+1).
+    if (cols == null) cols = Math.max(4, Math.floor(width / 16));
+    if (rows == null) rows = Math.max(4, Math.floor(height / 16));
+    const { renderRgbaToAnsi } = await import("../../host/chafa-render.js");
+    const ansi = await renderRgbaToAnsi(rgba, width, height, { cols, rows, symbols, colors });
+    // Livestream sidebands: the human sees BOTH the real PNG and the ANSI.
+    const shot = host.screenshot();
+    const observerSidebands = {
+      _observerImages: [{ kind: "image", mimeType: "image/png", base64: shot.pngBase64 }],
+      _observerAnsi: ansi,
+    };
+    let result;
+    if (!inline) {
+      await writeFile(outPath, ansi, "utf-8");
+      result = jsonContent({ path: outPath, framebuffer: { width, height }, terminal: { cols, rows, symbols, colors }, ansiBytes: Buffer.byteLength(ansi, "utf-8") });
+    } else {
+      result = {
+        content: [
+          { type: "text", text: ansi },
+          { type: "text", text: `framebuffer ${width}x${height} → terminal ${cols}x${rows} (${symbols}/${colors}, ${Buffer.byteLength(ansi, "utf-8")}B)` },
+        ],
+      };
+    }
+    Object.assign(result, observerSidebands);
+    return result;
+  }
+
+  server.tool(
+    "screenshot",
+    "Use this to capture the latest frame. DEFAULT writes the image to `path` and returns `{path}` — pass " +
+    "`inline:true` to get the image in the response instead (you MUST pass one or the other). `format:'png'` " +
+    "(default) = real frame, exact colors; `format:'ascii'` = lossy chafa text render for agents that can't " +
+    "view images. `overlayBoxes:true` (png) draws a colored box around each visible sprite (SNES+NES). ASCII " +
+    "grid/symbol/color knobs are in the param hints.",
+    {
+      format: z.enum(["png", "ascii"]).default("png").describe("'png' (default) = real image. 'ascii' = lossy text render for environments that can't show images."),
+      path: z.string().optional().describe("Absolute path to write to (PNG bytes or ANSI text per format). Required unless inline:true."),
+      inline: z.boolean().default(false).describe("If true, return the image/ANSI in the response instead of writing to disk. Default false — then `path` is required."),
+      overlayBoxes: z.boolean().default(false).describe("png only: draw colored sprite-bounding-box overlays (SNES + NES; ignored elsewhere)."),
+      cols: z.number().int().min(4).max(640).optional().describe("ascii only: terminal columns. Default framebuffer_width/16 (1 char ≈ 2 game tiles)."),
+      rows: z.number().int().min(4).max(480).optional().describe("ascii only: terminal rows. Default framebuffer_height/16."),
+      symbols: z.enum(["ascii", "halfblock", "block", "quad", "sextant"]).default("ascii").describe("ascii only: chafa symbol set. 'ascii' (default) = pure ASCII; 'halfblock'/'quad'/'sextant' = denser, need Unicode."),
+      colors: z.enum(["true", "256", "16", "fgbg"]).default("true").describe("ascii only: color depth. 'true' = 24-bit; '256'/'16' = palettes; 'fgbg' = mono shape."),
+    },
+    safeTool(async ({ format, path: outPath, inline, overlayBoxes, cols, rows, symbols, colors }) => {
+      requireImageTarget(outPath, inline, "screenshot");
+      if (format === "ascii") return shootAscii({ cols, rows, symbols, colors, path: outPath, inline });
+      return shootPng({ path: outPath, inline, overlayBoxes });
+    }),
+  );
+
+
+  server.tool(
+    "stepAndScreenshot",
+    "Step N frames, then capture a screenshot — one round-trip instead of two. Same output contract as " +
+    "screenshot: DEFAULT writes the PNG to `path` and returns `{path}`; pass `inline:true` to get the image " +
+    "in the response (you MUST pass one or the other).",
+    {
+      frames: z.number().int().min(1).max(1_000_000).default(1),
+      path: z.string().optional().describe("Absolute path to write the PNG to. Required unless inline:true."),
+      inline: z.boolean().default(false).describe("If true, return the image in the response instead of writing to disk. Default false — then `path` is required."),
+    },
+    safeTool(async ({ frames, path: outPath, inline }) => {
+      requireImageTarget(outPath, inline, "stepAndScreenshot");
+      const host = getHost(sessionKey);
+      host.stepFrames(frames);
+      const shot = host.screenshot();
+      if (!inline) {
+        await writeFile(outPath, Buffer.from(shot.pngBase64, "base64"));
+        const json = jsonContent({ path: outPath, frameCount: host.status.frameCount, width: shot.width, height: shot.height });
+        json._observerImages = [{ kind: "image", mimeType: "image/png", base64: shot.pngBase64 }];
+        return json;
+      }
+      return {
+        content: [
+          imageContent(shot.pngBase64),
+          { type: "text", text: `stepped ${frames} → frame ${host.status.frameCount} (${shot.width}x${shot.height})` },
+        ],
+      };
+    }),
+  );
+}