romdevtools 0.22.1 → 0.24.0

package/src/host/LibretroHost.js

@@ -138,6 +138,51 @@ export const PLATFORM_VIRTUAL_EXT = {
 };
 import { RETRO_DEVICE_JOYPAD } from "./retroConstants.js";
 
+// C64 controller→keyboard map (the Batocera/RetroDeck model: a CONTROLLER alone
+// plays C64 — no physical keyboard needed — by mapping spare buttons/stick to
+// the C64 keyboard keys games need at setup screens). Keyed by the button NAME
+// setInput receives (libretro + spatial names + the playtest right-stick virtual
+// buttons c64_f1..f7). The joystick itself (d-pad + Fire) is NOT here — those
+// stay a real joypad. Everything here is routed to the key matrix instead.
+//   B / south = Fire        → joystick (handled as joypad, not a key)
+//   X / west  = Space        L2 = Run/Stop   R2 / start = Return
+//   R-stick   = F1/F3/F5/F7  (playtest emits c64_f1..f7 from the right stick)
+const C64_BUTTON_KEYS = {
+  west: "space", y: "space",
+  l2: "run/stop",
+  r2: "return", start: "return",
+  c64_f1: "f1", c64_f3: "f3", c64_f5: "f5", c64_f7: "f7",
+  north: "f1", x: "f1",   // also expose F1 on the top face (1-player select is the #1 need)
+};
+// The buttons that ARE the C64 joystick (pass through to the joypad mask):
+const C64_JOY_BUTTONS = new Set(["up", "down", "left", "right", "b", "south", "a", "east"]);
+
+// C64 keyboard matrix: key name (lowercase) → [row, col] in the 8×8 matrix the
+// KERNAL scans via CIA1. Drives romdev_key_matrix() in the VICE core. Values
+// taken from VICE's own C64 positional keymap (data/C64/sdl_pos_uk.vkm).
+// Covers the keys RE/startup flows need; extend as needed.
+const C64_KEY_MATRIX = {
+  // function keys (the common "1 player / start" selectors)
+  f1: [0, 4], f3: [0, 5], f5: [0, 6], f7: [0, 3],
+  // editing / control
+  return: [0, 1], enter: [0, 1], space: [7, 4], del: [0, 0], backspace: [0, 0],
+  "run/stop": [7, 7], runstop: [7, 7], stop: [7, 7],
+  ctrl: [7, 2], cbm: [7, 5], commodore: [7, 5],
+  lshift: [1, 7], rshift: [6, 4], home: [6, 3], clr: [6, 3],
+  // cursor keys (C64 has DOWN + RIGHT; UP/LEFT are the shifted forms — use
+  // shift+down / shift+right for those)
+  "crsr-down": [0, 7], "crsr-right": [0, 2], down: [0, 7], right: [0, 2],
+  // digits
+  "0": [4, 3], "1": [7, 0], "2": [7, 3], "3": [1, 0], "4": [1, 3],
+  "5": [2, 0], "6": [2, 3], "7": [3, 0], "8": [3, 3], "9": [4, 0],
+  // letters
+  a: [1, 2], b: [3, 4], c: [2, 4], d: [2, 2], e: [1, 6], f: [2, 5],
+  g: [3, 2], h: [3, 5], i: [4, 1], j: [4, 2], k: [4, 5], l: [5, 2],
+  m: [4, 4], n: [4, 7], o: [4, 6], p: [5, 1], q: [7, 6], r: [2, 1],
+  s: [1, 5], t: [2, 6], u: [3, 6], v: [3, 7], w: [1, 1], x: [2, 7],
+  y: [3, 1], z: [1, 4],
+};
+
 export class LibretroHost {
   /**
    * @param {Object} [opts]
@@ -570,12 +615,55 @@ export class LibretroHost {
   /** @param {import("./types.js").FrameInput} input */
   setInput(input) {
     const platform = this.status.platform ?? undefined;
+    // C64: route the keyboard-mapped controller buttons (Space/Run-Stop/Return/
+    // F1-F7) to the key matrix so a CONTROLLER alone can play — the
+    // Batocera/RetroDeck model. The joystick bits (d-pad + Fire) still flow to
+    // the joypad mask below. Applies to BOTH playtest and the agent's setInput.
+    if (platform === "c64" && this.mod && typeof this.mod._romdev_key_matrix === "function") {
+      this._applyC64ButtonKeys(input.ports[0] || {});
+    }
     for (let port = 0; port < this.state.inputPorts.length; port++) {
-      const portInput = input.ports[port];
+      const portInput = this._c64StripKeyButtons(input.ports[port], platform);
       this.state.inputPorts[port][0] = portInputToMask(portInput, platform);
     }
   }
 
+  /** C64: press/release matrix keys for the held keyboard-mapped buttons on a
+   *  port, edge-tracked so a key releases when its button is no longer held. */
+  _applyC64ButtonKeys(portInput) {
+    const held = this._c64HeldKeys || (this._c64HeldKeys = new Set());
+    const want = new Set();
+    for (const [btn, key] of Object.entries(C64_BUTTON_KEYS)) {
+      if (portInput[btn] === true) want.add(key);
+    }
+    // press newly-wanted, release no-longer-wanted
+    for (const key of want) {
+      if (!held.has(key)) {
+        const pos = C64_KEY_MATRIX[key];
+        if (pos) this.mod._romdev_key_matrix(pos[0], pos[1], 1);
+        held.add(key);
+      }
+    }
+    for (const key of [...held]) {
+      if (!want.has(key)) {
+        const pos = C64_KEY_MATRIX[key];
+        if (pos) this.mod._romdev_key_matrix(pos[0], pos[1], 0);
+        held.delete(key);
+      }
+    }
+  }
+
+  /** Strip the C64 keyboard-mapped buttons out of a port so they don't ALSO
+   *  press a joystick direction/fire (only the real joystick bits remain). */
+  _c64StripKeyButtons(portInput, platform) {
+    if (platform !== "c64" || !portInput) return portInput;
+    const out = {};
+    for (const k of Object.keys(portInput)) {
+      if (C64_JOY_BUTTONS.has(k)) out[k] = portInput[k];
+    }
+    return out;
+  }
+
   /** @param {string} name */
   saveState(name) {
     const snapshot = this.serializeState();
@@ -802,6 +890,87 @@ export class LibretroHost {
     }
   }
 
+  // ── C64 keyboard + joyport (VICE core only) ──────────────────────────
+  // C64 games need KEYBOARD input (F1 = 1 player, RUN/STOP, SPACE/RETURN at
+  // setup screens) before joystick gameplay — joystick alone can't pass them.
+  // The VICE core exports romdev_key_matrix / romdev_kbdbuf_feed /
+  // romdev_joyport_* (see scripts/patches/vice-romdev-memory-regions.patch).
+
+  /** True if the loaded core exposes C64 keyboard injection (VICE only). */
+  keyboardSupported() {
+    const mod = this.mod;
+    return !!(mod && typeof mod._romdev_key_matrix === "function");
+  }
+
+  /**
+   * Press (and optionally auto-release) a single C64 key by name. Drives the
+   * C64 8×8 key matrix directly via the core. Held for `frames` then released.
+   * @param {string} key  a name from C64_KEY_MATRIX (case-insensitive)
+   * @param {number} [frames] frames to hold before release (default 4)
+   * @returns {{key:string, row:number, col:number, frames:number}}
+   */
+  pressC64Key(key, frames = 4) {
+    const mod = this._needMod();
+    if (typeof mod._romdev_key_matrix !== "function") {
+      throw new Error("this core build does not expose C64 keyboard input (C64/VICE only).");
+    }
+    const pos = C64_KEY_MATRIX[String(key).toLowerCase()];
+    if (!pos) {
+      throw new Error(
+        `unknown C64 key '${key}'. Known: ${Object.keys(C64_KEY_MATRIX).join(", ")}.`,
+      );
+    }
+    const [row, col] = pos;
+    mod._romdev_key_matrix(row, col, 1);    // press
+    this.stepFrames(Math.max(1, frames | 0));
+    mod._romdev_key_matrix(row, col, 0);    // release
+    this.stepFrames(1);
+    return { key: String(key).toLowerCase(), row, col, frames: Math.max(1, frames | 0) };
+  }
+
+  /**
+   * Feed a PETSCII string into the C64 kernal keyboard buffer (for typing
+   * LOAD/RUN/filenames). `\r` (or `\n`) becomes RETURN. Non-blocking — the
+   * kernal drains it as the screen editor runs, so step frames after.
+   * @param {string} text
+   * @returns {number} kbdbuf_feed's result (>=0 ok)
+   */
+  typeC64Text(text) {
+    const mod = this._needMod();
+    if (typeof mod._romdev_kbdbuf_feed !== "function") {
+      throw new Error("this core build does not expose C64 text input (C64/VICE only).");
+    }
+    const s = String(text).replace(/\n/g, "\r");
+    const bytes = Buffer.from(s + "\0", "latin1");
+    const ptr = mod._malloc(bytes.length);
+    try {
+      mod.HEAPU8.set(bytes, ptr);
+      return mod._romdev_kbdbuf_feed(ptr) | 0;
+    } finally {
+      mod._free(ptr);
+    }
+  }
+
+  /** Get the active C64 joystick port (1 or 2) the RetroPad drives. */
+  getC64JoyPort() {
+    const mod = this._needMod();
+    if (typeof mod._romdev_joyport_get !== "function") {
+      throw new Error("this core build does not expose C64 joyport (C64/VICE only).");
+    }
+    return mod._romdev_joyport_get() | 0;
+  }
+
+  /** Set the active C64 joystick port (1 or 2). Default is 2 (most games). */
+  setC64JoyPort(port) {
+    const mod = this._needMod();
+    if (typeof mod._romdev_joyport_set !== "function") {
+      throw new Error("this core build does not expose C64 joyport (C64/VICE only).");
+    }
+    if (port !== 1 && port !== 2) throw new Error("C64 joyport must be 1 or 2.");
+    mod._romdev_joyport_set(port | 0);
+    return port | 0;
+  }
+
   reset() {
     const mod = this._needMod();
     mod._retro_reset();
@@ -1545,6 +1714,60 @@ export class LibretroHost {
     }
   }
 
+  /**
+   * Per-frame VDP-DMA timeline. Steps `frames` frames ONE AT A TIME, and for
+   * each frame reports how many mem→VDP DMAs fired + how many VRAM/CRAM/VSRAM
+   * bytes they moved. The core's `romdev_dmawatch_set(1)` RESETS its counters
+   * (see the patch), so re-arming before each single-frame step gives a clean
+   * per-frame bucket with no core rebuild — the cheap derivation of "VDP/DMA
+   * work per frame" the feel-diagnostics workflow needs.
+   *
+   * `onFrame(i)` is called at the top of each frame (before the step) so the
+   * caller can drive scheduled input. Genesis-only.
+   *
+   * Returns { frames:[{frame, dmas, words, bytes, romBytes, ramBytes}], ... }.
+   * `romBytes`/`ramBytes` split the moved bytes by source bus (ROM asset upload
+   * vs the RAM→VRAM sprite/scroll refresh) so a per-frame asset-DMA spike — the
+   * "I redrew a tilemap in the loop" smell — stands out from the steady refresh.
+   */
+  watchDmaPerFrame(frames, onFrame) {
+    const mod = this._needMod();
+    this._needMedia();
+    if (!this.dmaWatchSupported()) throw new Error("VDP-DMA watch not supported by this core (Genesis only).");
+    const CAP = 1024;
+    const outPtr = mod._malloc(CAP * 4 * 4);
+    const out2Ptr = mod._malloc(8);
+    const isRam = (src) => (src >>> 0) >= 0xE00000;
+    const out = [];
+    let peakBytes = 0, peakFrame = -1, totalBytes = 0, totalDmas = 0;
+    try {
+      for (let i = 0; i < frames; i++) {
+        if (onFrame) onFrame(i);
+        mod._romdev_dmawatch_set(1);          // arm + RESET counters for this frame
+        this._runFramesExclusive(() => false, 1);
+        const n = mod._romdev_dmawatch_get(outPtr, CAP, out2Ptr);
+        const out2 = new Uint32Array(mod.HEAPU8.buffer, out2Ptr, 2);
+        const total = out2[0];                // total DMAs this frame (>= stored)
+        const u = new Uint32Array(mod.HEAPU8.buffer, outPtr, n * 4);
+        let words = 0, romBytes = 0, ramBytes = 0;
+        for (let k = 0; k < n; k++) {
+          const src = u[k * 4 + 1], len = u[k * 4 + 2];
+          words += len;
+          if (isRam(src)) ramBytes += len * 2; else romBytes += len * 2;
+        }
+        const bytes = words * 2;
+        out.push({ frame: i, dmas: total, words, bytes, romBytes, ramBytes,
+          ...(total > n ? { coreBufferTruncated: true } : {}) });
+        totalBytes += bytes; totalDmas += total;
+        if (bytes > peakBytes) { peakBytes = bytes; peakFrame = i; }
+      }
+      mod._romdev_dmawatch_set(0);            // disarm
+      return { frames: out, totalBytes, totalDmas, peakBytes, peakFrame };
+    } finally {
+      mod._free(outPtr); mod._free(out2Ptr);
+    }
+  }
+
   pause() {
     this.status.paused = true;
   }
@@ -1630,7 +1853,7 @@ export class LibretroHost {
       sms:   { video_ram: "sms_vram (or sms_cram for palette, sms_vdp_regs for VDP regs)" },
       gg:    { video_ram: "gg_vram (or gg_cram for the 64-byte 12-bit palette, sms_vdp_regs for VDP regs)" },
       snes:  { video_ram: "snes_oam (sprite OAM), snes_cgram (palette), snes_aram (SPC700), or snes_fillram (PPU/DMA reg shadow). The libretro generic 'video_ram' id isn't wired in snes9x." },
-      genesis: { video_ram: "genesis_cram / genesis_vsram / genesis_vdp_regs — the generic 'video_ram' id isn't wired in gpgx for Genesis. VRAM itself isn't exposed; use inspectPatternTiles / inspectBackgroundMap / getRenderingContext instead." },
+      genesis: { video_ram: "Genesis VRAM IS exposed via 'video_ram' (gpgx) once a ROM is loaded and a frame has run — if it reads empty, step a frame first (the SAT/sprites need the game to have written VRAM). Palette/scroll/VDP regs are genesis_cram / genesis_vsram / genesis_vdp_regs. For decoded views use inspectSprites / inspectPatternTiles / inspectBackgroundMap / getRenderingContext." },
       c64:   { video_ram: "c64_color_ram (1 KB) / c64_vic_regs / c64_sid_regs / c64_cia1_regs / c64_cia2_regs. The C64 has no separate VRAM — the VIC-II reads from main system_ram." },
     };
     const hint = suggestions[plat] && suggestions[plat][region];

package/src/host/framebuffer.js

@@ -113,3 +113,40 @@ export function framebufferToScreenshot(width, height, src, pitch, format) {
   const buf = framebufferToPng(width, height, src, pitch, format);
   return { width, height, pngBase64: buf.toString("base64") };
 }
+
+/**
+ * Nearest-neighbor resample of a base64 PNG by `scale`. Works BOTH directions:
+ *   scale<1  → downscale (e.g. 0.5 = half size; ~75% fewer image tokens for a
+ *              routine "did it change?" sanity check).
+ *   scale>=2 → integer up-scale (e.g. 4 = 4x size) so tiny handheld targets
+ *              (GB/GG 160x144, etc.) are legible inline without ImageMagick.
+ *
+ * Nearest-neighbor (not averaging/smoothing) is deliberate in both directions:
+ * it keeps pixel-art edges crisp and palette colors exact, so a scaled shot
+ * still reads accurately. The PNG is fully decoded already (it's a tiny
+ * framebuffer), so this is cheap. Platform-agnostic — same pixel scaling for
+ * every core.
+ *
+ * @param {string} pngBase64 source PNG, base64-encoded
+ * @param {number} scale resample factor (>0)
+ * @returns {{ base64: string, width: number, height: number }}
+ */
+export function resamplePng(pngBase64, scale) {
+  const src = PNG.sync.read(Buffer.from(pngBase64, "base64"));
+  const dw = Math.max(1, Math.round(src.width * scale));
+  const dh = Math.max(1, Math.round(src.height * scale));
+  const dst = new PNG({ width: dw, height: dh });
+  for (let y = 0; y < dh; y++) {
+    const sy = Math.min(src.height - 1, Math.floor(y / scale));
+    for (let x = 0; x < dw; x++) {
+      const sx = Math.min(src.width - 1, Math.floor(x / scale));
+      const si = (sy * src.width + sx) * 4;
+      const di = (y * dw + x) * 4;
+      dst.data[di] = src.data[si];
+      dst.data[di + 1] = src.data[si + 1];
+      dst.data[di + 2] = src.data[si + 2];
+      dst.data[di + 3] = src.data[si + 3];
+    }
+  }
+  return { base64: PNG.sync.write(dst).toString("base64"), width: dw, height: dh };
+}

package/src/http/skill-doc.js

@@ -112,7 +112,7 @@ export function sanitizeForSkillChannel(text) {
     // there's no session-id header / reconnect / "connect your agent" step here;
     // the skillPreamble already gives the skill-appropriate intro + prereq).
     if (/Mcp-Session-Id|re-?initialize|session not found|MCP client|MCP connection|MCP sessions/i.test(line)) continue;
-    if (/you are reading this because romdev is connected|connect your (agent|coding agent)|restart its MCP connection|restart your MCP|your MCP client should/i.test(line)) continue;
+    if (/connect your (agent|coding agent)|restart its MCP connection|restart your MCP|your MCP client should/i.test(line)) continue;
 
     let l = line
       // section header that frames romdev as "a server you connect to"

package/src/mcp/tools/audio.js

@@ -380,7 +380,7 @@ export function registerAudioTools(server, z, sessionKey) {
         if (args.frames != null && args.frames > 0) {
           return await traceAudioChip(sessionKey, args);
         }
-        return await getAudioStateCore(args);
+        return await getAudioStateCore(args, sessionKey);
       }
       if (args.op !== "record") throw new Error(`audioDebug: unknown op '${args.op}'`);
       if (!args.path) throw new Error("audioDebug({op:'record'}): `path` is required.");
@@ -485,7 +485,7 @@ async function traceAudioChip(sessionKey, { chip, platform, frames, sampleEvery
 
   // getAudioStateCore returns jsonContent({...}); pull the structured object.
   const decode = async () => {
-    const r = await getAudioStateCore({ chip, platform });
+    const r = await getAudioStateCore({ chip, platform }, sessionKey);
     const txt = r.content?.find?.((c) => c.type === "text")?.text;
     return txt ? JSON.parse(txt) : {};
   };

package/src/mcp/tools/frame.js

@@ -2,6 +2,7 @@ import { writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { PNG } from "pngjs";
+import { resamplePng } from "../../host/framebuffer.js";
 import { getHost } from "../state.js";
 import { imageContent, jsonContent, safeTool } from "../util.js";
 import { decodeOAM, decodePpuRegs, ppuRegsPopulated } from "../../platforms/snes/ppu.js";
@@ -258,30 +259,6 @@ export function registerFrameTools(server, z, sessionKey) {
     }
   }
 
-  // Nearest-neighbor downscale of a PNG by an integer divisor. Nearest-neighbor
-  // (not averaging) is deliberate: it keeps pixel-art edges crisp and palette
-  // colors exact, so a half-size sanity-check shot still reads accurately. The
-  // PNG is fully decoded already (it's a tiny framebuffer), so this is cheap.
-  function downscalePng(pngBase64, scale) {
-    const src = PNG.sync.read(Buffer.from(pngBase64, "base64"));
-    const dw = Math.max(1, Math.round(src.width * scale));
-    const dh = Math.max(1, Math.round(src.height * scale));
-    const dst = new PNG({ width: dw, height: dh });
-    for (let y = 0; y < dh; y++) {
-      const sy = Math.min(src.height - 1, Math.floor(y / scale));
-      for (let x = 0; x < dw; x++) {
-        const sx = Math.min(src.width - 1, Math.floor(x / scale));
-        const si = (sy * src.width + sx) * 4;
-        const di = (y * dw + x) * 4;
-        dst.data[di] = src.data[si];
-        dst.data[di + 1] = src.data[si + 1];
-        dst.data[di + 2] = src.data[si + 2];
-        dst.data[di + 3] = src.data[si + 3];
-      }
-    }
-    return { base64: PNG.sync.write(dst).toString("base64"), width: dw, height: dh };
-  }
-
   // PNG capture. Writes to outPath, or returns inline when `inline`.
   async function shootPng({ path: outPath, inline, overlayBoxes, scale }) {
     const host = getHost(sessionKey);
@@ -300,16 +277,18 @@ export function registerFrameTools(server, z, sessionKey) {
         overlayInfo = { platform, spritesDrawn: 0, note: `overlay not yet supported for '${platform}'` };
       }
     }
-    // Downscale AFTER overlay so the boxes scale with the image. scale=1 (or
-    // unset) is the full-resolution default; a quarter-size shot is ~75%
-    // fewer image tokens for routine "did it change?" sanity checks.
-    if (scale && scale < 1) {
-      const small = downscalePng(pngBase64, scale);
-      pngBase64 = small.base64; width = small.width; height = small.height;
+    // Resample AFTER overlay so the boxes scale with the image. scale=1 (or
+    // unset) is the native-resolution default; scale<1 is a downscaled shot
+    // (~75% fewer image tokens for routine "did it change?" sanity checks),
+    // scale>=2 is an integer up-scale so tiny handheld targets read legibly.
+    const scaled = scale && scale !== 1;
+    if (scaled) {
+      const r = resamplePng(pngBase64, scale);
+      pngBase64 = r.base64; width = r.width; height = r.height;
     }
     if (!inline) {
       await writeFile(outPath, Buffer.from(pngBase64, "base64"));
-      const json = jsonContent({ path: outPath, width, height, ...(scale && scale < 1 ? { scale, fullWidth: shot.width, fullHeight: shot.height } : {}), overlay: overlayInfo });
+      const json = jsonContent({ path: outPath, width, height, ...(scaled ? { scale, fullWidth: shot.width, fullHeight: shot.height } : {}), overlay: overlayInfo });
       json._observerImages = [{ kind: "image", mimeType: "image/png", base64: pngBase64 }];
       return json;
     }
@@ -321,7 +300,7 @@ export function registerFrameTools(server, z, sessionKey) {
     return {
       content: [
         imageContent(pngBase64),
-        { type: "text", text: `framebuffer ${shot.width}x${shot.height}${scale && scale < 1 ? ` (scaled to ${width}x${height})` : ""}${overlayInfo ? ` (overlay: ${overlayInfo.spritesDrawn} sprites)` : ""} — also written to ${tempPath} (use this path for ImageMagick/crops; pass outputPath for a permanent location).` },
+        { type: "text", text: `framebuffer ${shot.width}x${shot.height}${scaled ? ` (scaled ${scale}x to ${width}x${height})` : ""}${overlayInfo ? ` (overlay: ${overlayInfo.spritesDrawn} sprites)` : ""} — also written to ${tempPath} (use this path for ImageMagick/crops; pass outputPath for a permanent location).` },
       ],
     };
   }
@@ -414,7 +393,7 @@ export function registerFrameTools(server, z, sessionKey) {
     "level with 7200; prefer ONE big call.\n" +
     "'screenshot': capture the latest frame. `format:'png'` (default, exact colors) or `'ascii'` (lossy chafa text " +
     "render for agents that can't view images). `overlayBoxes` (png) draws a box per visible sprite (SNES+NES only); " +
-    "`scale` (0<≤1) downscales (~75% fewer image tokens at 0.5); ascii cols/rows/symbols/colors knobs in the param hints. " +
+    "`scale` (png) resamples nearest-neighbor BOTH ways: 0<scale<1 DOWNscales (~75% fewer image tokens at 0.5), integer scale≥2 UPscales so tiny handheld targets read inline (e.g. scale:4 → GB 160x144 becomes 640x576); ascii cols/rows/symbols/colors knobs in the param hints. " +
     "**CHEAP VERIFY: for a binary pass/fail check (theme changed? sprite present? HUD ticked?) prefer scale:0.5 or " +
     "format:'ascii' — BETTER, read the byte directly: symbols({op:'resolve', name}) → memory({op:'read'}) is a 1-byte " +
     "assertion that costs zero image tokens.**\n" +
@@ -438,7 +417,7 @@ export function registerFrameTools(server, z, sessionKey) {
       path: z.string().optional().describe("op=screenshot/stepAndShot: absolute path to write to (required unless inline:true)."),
       inline: z.boolean().default(false).describe("op=screenshot/stepAndShot: return the image in the response instead of writing to disk."),
       overlayBoxes: z.boolean().default(false).describe("op=screenshot png: draw a colored bounding box per visible sprite (SNES+NES only)."),
-      scale: z.number().gt(0).max(1).optional().describe("op=screenshot png: downscale factor (0<scale≤1, nearest-neighbor). 0.5 ≈ 75% fewer image tokens."),
+      scale: z.number().gt(0).max(16).refine((s) => s <= 1 || Number.isInteger(s), { message: "scale must be 0<scale≤1 (downscale) or an integer ≥2 (upscale)" }).optional().describe("op=screenshot png: nearest-neighbor resample factor. 0<scale<1 DOWNscales (0.5 ≈ 75% fewer image tokens for cheap 'did it change?' checks); scale≥2 (integer) UPscales (nearest-neighbor — keeps pixel-art crisp) so tiny handheld targets are legible inline, e.g. scale:4 makes a GB 160x144 shot 640x576. scale=1/unset = native resolution."),
       cols: z.number().int().min(4).max(640).optional().describe("op=screenshot ascii: terminal columns (default fb_width/16)."),
       rows: z.number().int().min(4).max(480).optional().describe("op=screenshot ascii: terminal rows (default fb_height/16)."),
       symbols: z.enum(["ascii", "halfblock", "block", "quad", "sextant"]).default("ascii").describe("op=screenshot ascii: chafa symbol set."),

package/src/mcp/tools/index.js

@@ -188,8 +188,8 @@ const CATEGORIES = [
   },
   {
     name: "advanced",
-    description: "Less common automation: runUntil (drive a ROM headlessly until a condition), watchMemory (cross-platform memory-write trace — see what code touched a RAM byte), runUntilWrite (step until target byte is written, return the PC), record (capture inputs for replay).",
-    useWhen: ["want to automate reaching a specific game state", "tracking down which code writes a specific RAM byte (gameplay variable hunting)", "recording an input macro for regression testing"],
+    description: "Less common automation + MOTION/TELEMETRY tracing: runUntil (drive a ROM headlessly until a condition), watch({on:'mem', format:'series'}) (a compact value-vs-frame CURVE per byte — the primitive for velocity/scroll/sprite-position over time), runUntilWrite (step until target byte is written, return the PC), recordSession (hold/script input over N frames while sampling memory + screenshots into an analyzable timeline — use it to diagnose game-FEEL issues: choppy movement, scroll jumps, camera-vs-sprite desync, NOT just input macros).",
+    useWhen: ["want to automate reaching a specific game state", "tracking down which code writes a specific RAM byte (gameplay variable hunting)", "diagnosing why movement/scrolling feels choppy or wrong — sample sprite X + scroll regs over frames with recordSession or watch series", "recording an input macro for regression testing"],
     register: (s, z, k) => { registerRunUntilTools(s, z, k); registerWatchMemoryTools(s, z, k); registerRecordTools(s, z, k); },
   },
 ];

package/src/mcp/tools/input-layout.js

@@ -74,6 +74,16 @@ const HARDWARE_LAYOUTS = {
     readSequence: "Bits 0-4 are Up/Down/Left/Right/Fire, active-low.",
     bitOrder: ["Up", "Down", "Left", "Right", "Fire"],
     faceButtons: FACE_BUTTON_MAP.c64,
+    // The C64 needs more than joystick: many games use KEYBOARD setup screens
+    // (F1=1 player, RUN/STOP, SPACE/RETURN) before joystick gameplay starts.
+    keyboard: {
+      note: "C64 games often need keyboard input to START (F1 to pick 1 player, fire/RETURN to begin). Joystick alone can't pass these. Use input({op:'pressKey', key}) for a single key, input({op:'typeText', text}) to type a string (LOAD/RUN/filenames).",
+      keys: ["f1", "f3", "f5", "f7", "return", "space", "run/stop", "ctrl", "cbm", "home", "down", "right", "lshift", "rshift", "0-9", "a-z"],
+    },
+    joyport: {
+      note: "The RetroPad drives ONE C64 joystick port at a time. Default is port 2 (most games). Use input({op:'joyport'}) to read it, input({op:'joyport', joyport:1|2}) to switch.",
+      default: 2,
+    },
   },
   sms: {
     register: "I/O port $DC (controllers, read via `in a,($DC)`) and $DD (port 2 high bits + reset)",

package/src/mcp/tools/input.js

@@ -213,17 +213,21 @@ export function registerInputTools(server, z, sessionKey) {
     "when ITS code polls; re-apply immediately before the consuming stepFrames and verify via the held-buttons RAM " +
     "byte, not this echo.",
     {
-      op: z.enum(["set", "press", "sequence", "navigate", "layout"]).describe("set/hold buttons; press one button; run a sequence; navigate a menu; or get the input layout."),
+      op: z.enum(["set", "press", "sequence", "navigate", "layout", "pressKey", "typeText", "joyport"]).describe("set/hold buttons; press one button; run a sequence; navigate a menu; get the input layout. C64-ONLY: pressKey (press a C64 KEYBOARD key — F1/Return/Space/Run-Stop — many C64 games need these to start, joystick alone can't); typeText (feed a string into the C64 keyboard buffer — LOAD/RUN/filenames); joyport (get/set which C64 joystick port the pad drives, 1 or 2; default 2)."),
       // set
       ports: z.array(port).min(1).max(2).optional().describe("op=set: per-port input. [{a:true,right:true}] holds A+Right on port 0."),
       // press
       button: z.enum(BUTTON_ENUM).optional().describe("op=press: button to press (native aliases + spatial names accepted)."),
-      frames: z.number().int().min(1).max(600).default(2).describe("op=press: frames to hold the button."),
+      frames: z.number().int().min(1).max(600).default(2).describe("op=press: frames to hold the button. op=pressKey: frames to hold the C64 key (default 4)."),
       port: z.number().int().min(0).max(1).default(0).describe("op=press: which port (default 0)."),
       // sequence
       steps: z.array(z.any()).optional().describe("op=sequence: [{input:{ports:[...]}, frames}]. op=navigate: [{button, holdFrames?, maxWaitFrames?, settleFrames?}]. (Two distinct step shapes by op.)"),
       // layout
       platform: z.string().optional().describe("op=layout: platform id (nes, gb, snes, genesis, ...)."),
+      // C64 keyboard
+      key: z.string().optional().describe("op=pressKey (C64): key name — f1/f3/f5/f7, return, space, run/stop, a-z, 0-9, ctrl, cbm, home, down, right, lshift, rshift."),
+      text: z.string().optional().describe("op=typeText (C64): string fed into the keyboard buffer; \\r / \\n become RETURN. e.g. 'LOAD\"*\",8,1\\rRUN\\r'."),
+      joyport: z.number().int().min(1).max(2).optional().describe("op=joyport (C64): set the active joystick port (1 or 2). Omit to just GET the current port. Default is 2 (most C64 games)."),
     },
     safeTool(async (args) => {
       switch (args.op) {
@@ -249,6 +253,26 @@ export function registerInputTools(server, z, sessionKey) {
           if (!args.platform) throw new Error("input({op:'layout'}): `platform` is required.");
           return jsonContent(getInputLayoutCore(args));
         }
+        case "pressKey": {
+          if (!args.key) throw new Error("input({op:'pressKey'}): `key` is required (C64 keyboard key, e.g. 'f1', 'return', 'run/stop').");
+          const host = getHost(sessionKey);
+          const r = host.pressC64Key(args.key, args.frames ?? 4);
+          return jsonContent({ pressedKey: r.key, matrix: [r.row, r.col], frames: r.frames, frameCount: host.status.frameCount });
+        }
+        case "typeText": {
+          if (typeof args.text !== "string") throw new Error("input({op:'typeText'}): `text` is required (string fed into the C64 keyboard buffer).");
+          const host = getHost(sessionKey);
+          const rc = host.typeC64Text(args.text);
+          return jsonContent({ typed: args.text, fedResult: rc, note: "Queued into the C64 keyboard buffer — step frames so the screen editor drains it." });
+        }
+        case "joyport": {
+          const host = getHost(sessionKey);
+          if (args.joyport === undefined) {
+            return jsonContent({ joyport: host.getC64JoyPort(), note: "Active C64 joystick port. Most C64 games use port 2 (the default). Pass `joyport:1` or `joyport:2` to change it." });
+          }
+          const set = host.setC64JoyPort(args.joyport);
+          return jsonContent({ joyport: set, set: true });
+        }
         default: throw new Error(`input: unknown op '${args.op}'`);
       }
     }),

package/src/mcp/tools/metasprite-tools.js

@@ -221,7 +221,7 @@ export function registerMetaSpriteTools(server, z, sessionKey) {
     },
     safeTool(async (args) => {
       switch (args.op) {
-        case "inspect":           return await inspectSpritesCore(args);
+        case "inspect":           return await inspectSpritesCore(args, sessionKey);
         case "group":             return await spritesGroup(sessionKey, args);
         case "preview":           return await spritesPreview(sessionKey, args);
         case "capture":           return await spritesCapture(sessionKey, { ...args, name: args.name ?? "metasprite" });

package/src/mcp/tools/platform-tools.js

@@ -53,7 +53,7 @@ export function registerPlatformTools(server, z, sessionKey) {
   // inspectPatternTiles lives in the `tiles` tool (tiles({op:'png'}), in
   // tile-inspect.js) now — extracted here as a live-binding core. Reads the
   // running emulator's pattern tables / VRAM (or an iNES file via `path`).
-  inspectPatternTilesCore = async ({ platform, path: romPath, bpp = 4, tileBaseByte = 0, paletteBase = 0, paletteIndex = 0, tileCount = 0, scale = 1, outputPath, inline }) => {
+  inspectPatternTilesCore = async ({ platform, path: romPath, bpp = 4, tileBaseByte = 0, paletteBase = 0, paletteIndex = 0, tileCount = 0, scale = 1, outputPath, inline }, callerSessionKey) => {
       requireImageTarget(outputPath, inline, "inspectPatternTiles");
       // Integer nearest-neighbor upscale of a PNG — keeps pixel-art tiles crisp
       // while making a small tile strip actually readable inline.
@@ -102,7 +102,7 @@ export function registerPlatformTools(server, z, sessionKey) {
         if (!hasChr) throw new Error(`'${romPath}' is a CHR-RAM cart — no graphics in the ROM file. Load it and call inspectPatternTiles without path.`);
         return emit(png, { platform: p, source: "file", sourcePath: romPath, width, height });
       }
-      const host = getHost(sessionKey);
+      const host = getHost(callerSessionKey ?? sessionKey);
       const p = resolvePlatform(host, platform);
       if (p === "nes") {
         const { snapshotPatternTables } = await import("../../platforms/nes/ppu.js");
@@ -342,8 +342,8 @@ export function registerPlatformTools(server, z, sessionKey) {
   };
 
   // getCPUState → cpu({op:'read'}) (router in watch-memory.js). Live-binding core.
-  getCPUStateCore = async ({ platform, cpu = "main" }) => {
-      const host = getHost(sessionKey);
+  getCPUStateCore = async ({ platform, cpu = "main" }, callerSessionKey) => {
+      const host = getHost(callerSessionKey ?? sessionKey);
       const p = resolvePlatform(host, platform);
       const state = getCPUState(host, p, cpu);
       if (!state) {
@@ -357,8 +357,8 @@ export function registerPlatformTools(server, z, sessionKey) {
   // Subsumes the old getDspState / getPsgState / getYm2612State, which
   // remain as thin deprecated aliases below for back-compat.
   /** Run the chip decoder for one chip; returns the structured JSON object. */
-  function readAudioChip(chip) {
-    const host = getHost(sessionKey);
+  function readAudioChip(chip, callerSessionKey) {
+    const host = getHost(callerSessionKey ?? sessionKey);
     if (chip === "dsp") {
       const p = resolvePlatform(host, "snes");
       const dsp = getDspState(host, p);
@@ -421,13 +421,20 @@ export function registerPlatformTools(server, z, sessionKey) {
     throw new Error(`getAudioState: unknown chip '${chip}'. Use 'nes' (NES 2A03), 'gb' (Game Boy/GBC), 'gba' (GBA), 'dsp' (SNES), 'psg' (Genesis/SMS/GG SN76489), 'ym2612' (Genesis FM), 'sid' (C64), or 'mikey' (Lynx).`);
   }
 
-  getAudioStateCore = async ({ chip }) => jsonContent(readAudioChip(chip));
+  getAudioStateCore = async ({ chip }, callerSessionKey) => jsonContent(readAudioChip(chip, callerSessionKey));
 
   // inspectSprites lives in the `sprites` tool (metasprite-tools.js) now —
   // extracted here as a live-binding core so the router can call it without
   // disturbing the other handlers registerPlatformTools owns.
-  inspectSpritesCore = async ({ platform, maxSlots, slots, outputPath, inline }) => {
-      const host = getHost(sessionKey);
+  inspectSpritesCore = async ({ platform, maxSlots, slots, outputPath, inline }, callerSessionKey) => {
+      // sessionKey MUST come from the live call, not the closure: these *Core
+      // functions are module-level `export let` bindings reassigned on every
+      // registerPlatformTools() run, so the closure's `sessionKey` is whatever
+      // session registered LAST — not the caller's. Threading it through the
+      // call args keeps each session reading its OWN host. (Same fix shape as
+      // inspectPaletteCore.) Falls back to the registration key for any caller
+      // that still invokes the old 1-arg form.
+      const host = getHost(callerSessionKey ?? sessionKey);
       const p = resolvePlatform(host, platform);
       // Generic slot filter, applied by each platform branch before returning.
       // `slots` (explicit index list) wins over `maxSlots` (first N); the
@@ -693,8 +700,8 @@ export function registerPlatformTools(server, z, sessionKey) {
   // inspectBackgroundMap lives in the `background` tool (rendering-context.js)
   // now — extracted here as a live-binding core so the router can call it
   // without disturbing the other handlers registerPlatformTools owns.
-  inspectBackgroundMapCore = async ({ platform, render, region, attributesOnly, tilesOnly, which, window, plane, tilemapBaseByte, tileBaseByte, bpp, mapWidth, mapHeight, outputPath, inline }) => {
-      const host = getHost(sessionKey);
+  inspectBackgroundMapCore = async ({ platform, render, region, attributesOnly, tilesOnly, which, window, plane, tilemapBaseByte, tileBaseByte, bpp, mapWidth, mapHeight, outputPath, inline }, callerSessionKey) => {
+      const host = getHost(callerSessionKey ?? sessionKey);
       const p = resolvePlatform(host, platform);
       if (attributesOnly && tilesOnly) {
         throw new Error("inspectBackgroundMap: attributesOnly and tilesOnly are mutually exclusive — omit both to get tiles + subPaletteGrid together.");

package/src/mcp/tools/playtest.js

@@ -126,7 +126,7 @@ export function registerPlaytestTools(server, z, sessionKey) {
         });
       }
 
-      const { playtest, KEYBOARD_BINDINGS_HELP } = await import("../../playtest/playtest.js");
+      const { playtest, KEYBOARD_BINDINGS_HELP, C64_BINDINGS_HELP } = await import("../../playtest/playtest.js");
       let session;
       try {
         // Pass a live-host accessor so the window FOLLOWS rebuilds: runSource/
@@ -214,6 +214,7 @@ export function registerPlaytestTools(server, z, sessionKey) {
       // isn't left guessing which keys drive the game. (A pad hot-plugged later
       // is picked up automatically — this is just the at-open state.)
       const noController = session.controllerCount === 0;
+      const isC64 = host.status?.platform === "c64";
       return jsonContent({
         opened: true,
         reusedExistingWindow: false,
@@ -222,7 +223,21 @@ export function registerPlaytestTools(server, z, sessionKey) {
         scale,
         aspect,
         controllerCount: session.controllerCount,
-        ...(noController
+        // C64 input is non-obvious (games need keyboard keys to START), so ALWAYS
+        // relay the controls — a controller alone IS enough (spare buttons/stick
+        // map to F1/Run-Stop/Space/Return), and the keyboard fallback covers the
+        // no-controller case. This is the Batocera/RetroDeck model.
+        ...(isC64
+          ? {
+              c64Controls: C64_BINDINGS_HELP,
+              tellUser:
+                "C64 game: RELAY `c64Controls` to the user. A CONTROLLER ALONE is " +
+                "enough — they do NOT need a keyboard. Most C64 games need a " +
+                "keyboard key to START (e.g. F1 for 1 player); the pad's spare " +
+                "buttons/right-stick map to those (F1/F3/F5/F7, Space, Run/Stop, " +
+                "Return). Default joystick port is 2; change with input({op:'joyport'}).",
+            }
+          : noController
           ? {
               keyboardControls: KEYBOARD_BINDINGS_HELP,
               tellUser: