romdevtools 0.23.0 → 0.25.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,167 @@ 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) };
+  }
+
+  /**
+   * Press a C64 key like pressC64Key, but sample the machine-visible input
+   * state (CIA1 $DC00/$DC01 — the keyboard/joystick scan ports) BEFORE,
+   * DURING (key held), and AFTER (released). Lets an RE agent tell apart
+   * "my key never reached VICE" from "VICE saw it but the game didn't scan
+   * it this frame". No core change — reads the already-exposed c64_cia1_regs
+   * region ($DC00..$DC0F).
+   * @param {string} key
+   * @param {number} frames  frames to hold (sampled at the midpoint)
+   * @returns {object} matrix coords + held flag + per-phase CIA snapshots
+   */
+  pressC64KeyVerify(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;
+    const held = Math.max(1, frames | 0);
+    // $DC00 = CIA1 PRA (port A — joystick 2 + keyboard col select),
+    // $DC01 = CIA1 PRB (port B — joystick 1 + keyboard row read).
+    const cia = () => {
+      try {
+        const r = this.readMemory("c64_cia1_regs", 0, 2);
+        return { DC00: r[0], DC01: r[1] };
+      } catch { return null; }
+    };
+    const before = cia();
+    mod._romdev_key_matrix(row, col, 1);          // press
+    this.stepFrames(Math.ceil(held / 2));
+    const during = cia();                          // key still held
+    this.stepFrames(Math.max(1, held - Math.ceil(held / 2)));
+    mod._romdev_key_matrix(row, col, 0);          // release
+    this.stepFrames(1);
+    const after = cia();
+    return {
+      key: String(key).toLowerCase(),
+      row, col,
+      frames: held,
+      joyport: this.getC64JoyPort?.() ?? null,
+      autoReleased: true,
+      cia1: { before, during, after },
+      note: "CIA1 $DC00 (port A) / $DC01 (port B) are the keyboard/joystick scan ports the KERNAL reads. `during` is sampled with the key held; if before==during the key never moved the matrix line (didn't reach VICE); if they differ but the game didn't react, it scanned a different key/port or that screen ignores it.",
+    };
+  }
+
+  /**
+   * Set the SET of C64 keyboard keys held down (for scripted timelines like
+   * recordSession). Diffs against the currently-held set: presses newly-added
+   * keys' matrix lines, releases removed ones. Pass [] to release all. Does NOT
+   * step frames — the caller's loop owns stepping. Unknown keys throw.
+   * @param {string[]} keys
+   * @returns {{held: string[], matrix: Array<[number,number]>}}
+   */
+  setC64HeldKeys(keys) {
+    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 want = new Set((keys ?? []).map((k) => String(k).toLowerCase()));
+    for (const k of want) {
+      if (!C64_KEY_MATRIX[k]) {
+        throw new Error(`unknown C64 key '${k}'. Known: ${Object.keys(C64_KEY_MATRIX).join(", ")}.`);
+      }
+    }
+    const have = this._c64HeldKeys ?? (this._c64HeldKeys = new Set());
+    // release keys no longer wanted
+    for (const k of have) {
+      if (!want.has(k)) { const [r, c] = C64_KEY_MATRIX[k]; mod._romdev_key_matrix(r, c, 0); have.delete(k); }
+    }
+    // press newly-added keys
+    for (const k of want) {
+      if (!have.has(k)) { const [r, c] = C64_KEY_MATRIX[k]; mod._romdev_key_matrix(r, c, 1); have.add(k); }
+    }
+    return { held: [...have], matrix: [...have].map((k) => C64_KEY_MATRIX[k]) };
+  }
+
+  /**
+   * 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();

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/index.js

@@ -58,13 +58,11 @@ import { registerCheatTools } from "./cheats.js";
 import { createDisclosure } from "../disclosure.js";
 import { jsonContent, safeTool, withClearToolErrors } from "../util.js";
 import { getHostOrNull, setDisclosure } from "../state.js";
-import { MERGE_MAP } from "../tool-manifest.js";
-import { readFile } from "node:fs/promises";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 
-// Package version — surfaced by catalog({op:'status'|'whatsNew'}) so an agent can
+// Package version — surfaced by catalog({op:'status'}) so an agent can
 // check the running romdev version with a plain TOOL CALL (works over MCP AND the
 // HTTP/skill surface), e.g. to detect a saved skill is stale. (GET /healthz also
 // reports it for non-tool HTTP clients.)
@@ -76,42 +74,6 @@ const PKG_VERSION = (() => {
   }
 })();
 
-// catalog({op:'whatsNew'}): the recent CHANGELOG + an old→new RENAME TABLE
-// derived from MERGE_MAP (the single source of truth for the consolidation), so
-// an agent resuming a handoff written against an older server can re-map every
-// renamed tool in ONE read. Pre-1.0 the surface is consolidated freely with NO
-// deprecated aliases (see the consolidation), which is exactly why this exists.
-async function buildWhatsNew() {
-  // old name → "newTool({axis:'oldOpName'})". The op value is best-effort: most
-  // absorbed tools become an op whose name is a shortened form, so we surface the
-  // axis + the new tool and let the tool's own description give the exact op enum.
-  const renames = {};
-  for (const [newTool, entry] of Object.entries(MERGE_MAP)) {
-    if (entry.unchanged) continue;
-    for (const old of entry.absorbs ?? []) {
-      renames[old] = { nowOn: newTool, axis: entry.axis };
-    }
-  }
-  // Recent CHANGELOG entries (top of the file = newest). Best-effort: if the file
-  // isn't packaged in some install, return the rename table alone.
-  let changelog = null;
-  try {
-    const here = dirname(fileURLToPath(import.meta.url));
-    // src/mcp/tools/ → package root is three up.
-    const text = await readFile(join(here, "..", "..", "..", "CHANGELOG.md"), "utf8");
-    // Keep the two most recent version sections.
-    const sections = text.split(/^## /m);
-    changelog = sections.slice(0, 3).join("## ").trim();
-  } catch { /* changelog not present in this install */ }
-  return {
-    romdevVersion: PKG_VERSION,
-    note: "Pre-1.0 the tool surface is consolidated freely with NO deprecated aliases. If a tool name from an older handoff is missing, it's almost certainly now an `op` (or other axis) on a domain tool — find it below, then read that tool's description for the exact op enum and params.",
-    renameTable: renames,
-    axisLegend: "Every domain tool is keyed by ONE axis: op (most), output (build), on (breakpoint), target (disasm), view (background), source (palette), stage (encodeArt), from (importArt). The value names the operation, e.g. romPatch({op:'findPointer'}).",
-    ...(changelog ? { changelog } : { changelogNote: "CHANGELOG.md not bundled in this install." }),
-  };
-}
-
 /**
  * Categories for progressive disclosure. Each entry's `register` is the
  * existing per-module registration function — we don't rewrite the
@@ -225,16 +187,12 @@ export function registerTools(server, z, sessionKey) {
     "catalog",
     "Orient yourself, keyed by `op`.\n" +
     "• op:'categories' (default) — the catalog of tool categories, each {name, description, useWhen[], loaded}. This server registers EVERY tool at session start, so this is just a map grouped by purpose for orientation, NOT a gate — you do NOT need to load anything before calling a tool.\n" +
-    "• op:'status' — a snapshot of the current session: which platform's core/ROM is in the running host (if any), current frame count, last-loaded media, loaded categories. Call this when you've lost context across many tool calls and want to re-ground.\n" +
-    "• op:'whatsNew' — the recent CHANGELOG + an OLD→NEW tool RENAME TABLE. Call this FIRST if you're resuming work from a handoff written against an older server: pre-1.0 the surface is consolidated freely (no deprecated aliases), so a name you remember may now be an `op` on a domain tool. This maps them in one read instead of probing each tool.",
+    "• op:'status' — a snapshot of the current session: which platform's core/ROM is in the running host (if any), current frame count, last-loaded media, loaded categories. Call this when you've lost context across many tool calls and want to re-ground.",
     {
-      op: z.enum(["categories", "status", "whatsNew"]).default("categories")
-        .describe("categories=tool-category catalog; status=live session snapshot (romdevVersion + host/platform/frameCount/media — call this to check the running version, e.g. is a saved skill stale); whatsNew=recent CHANGELOG + old→new tool rename table."),
+      op: z.enum(["categories", "status"]).default("categories")
+        .describe("categories=tool-category catalog; status=live session snapshot (romdevVersion + host/platform/frameCount/media — call this to check the running version, e.g. is a saved skill stale)."),
     },
     safeTool(async ({ op = "categories" }) => {
-      if (op === "whatsNew") {
-        return jsonContent(await buildWhatsNew());
-      }
       if (op === "status") {
         const host = getHostOrNull(sessionKey);
         const cats = disclosure.listCategories();

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,22 @@ 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)."),
+      verify: z.boolean().default(false).describe("op=pressKey (C64): also sample CIA1 $DC00/$DC01 (the keyboard/joystick scan ports the KERNAL reads) BEFORE / DURING (key held) / AFTER, plus matrix coords + active joyport. Use to tell apart 'my key never reached VICE' (before==during) from 'VICE saw it but the game ignored it' (they differ but no reaction) when a C64 game doesn't respond to a key."),
     },
     safeTool(async (args) => {
       switch (args.op) {
@@ -249,6 +254,30 @@ 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);
+          if (args.verify) {
+            const v = host.pressC64KeyVerify(args.key, args.frames ?? 4);
+            return jsonContent({ pressedKey: v.key, matrix: [v.row, v.col], frames: v.frames, joyport: v.joyport, autoReleased: v.autoReleased, cia1: v.cia1, frameCount: host.status.frameCount, note: v.note });
+          }
+          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/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:

package/src/mcp/tools/project.js

@@ -1422,7 +1422,7 @@ async function copyDirRecursive(fs, path, srcDir, dstDir, writtenFiles, dstPrefi
  *   handler returns: {path, platform, template, files, sourceFile,
  *   toolchain, nextStep}.
  */
-export async function createProjectImpl({ platform, name, path: projPath, title, template, overwrite = false, withSnippets = false }) {
+export async function createProjectImpl({ platform, name, path: projPath, title, template, overwrite = false, withSnippets = false, verbose = false }) {
   const fs = await import("node:fs/promises");
   const path = await import("node:path");
   const { fileURLToPath } = await import("node:url");
@@ -1768,7 +1768,12 @@ Compiles **C89**, not C99/C11. Stick to:
   }
   filesSection += `\nEvery byte that compiles into your ROM is in this directory. If you move the repo somewhere else, you don't need to install anything from romdev to rebuild it — the compiler binaries are the only external dependency.\n\n`;
 
-  const readme = `# ${title ?? name}\n\nA ${lang} project for ${platform}, scaffolded by romdev.\n\n${tmpl?.describe ? tmpl.describe + "\n\n" : ""}${filesSection}${c89Note}## Build + run with romdev\n\n${buildBlock}\n\n## Iterating\n\n- Edit \`${mainFilename}\` (or any of the runtime / crt0 / cfg files — they're yours).\n- Call \`build({output:"run", ...})\` to see your changes. It builds + loads + runs + screenshots in one round trip.\n- Inspect at byte level: \`memory({op:"read"})\`, \`sprites({op:"inspect"})\`, \`palette({source:"live"})\`, \`background({view:"rendered"})\`.\n- Open a playtest window for human eyes: \`playtest({op:"open"})\` — returns immediately, the window follows your rebuilds, and the emulator stays live for every other tool.\n`;
+  // Lead with the project-dir build — ONE call, no manifest. The verbose
+  // output:'run' + sourcesPaths form (buildBlock) is the "editing loose
+  // source" variant, shown second.
+  const projectBuildBlock =
+    "```js\nbuild({\n  output: \"project\",\n  platform: \"" + platform + "\",\n  path: \"" + projPath + "\",\n  outputPath: \"" + name + romExt + "\",\n})\n```";
+  const readme = `# ${title ?? name}\n\nA ${lang} project for ${platform}, scaffolded by romdev.\n\n${tmpl?.describe ? tmpl.describe + "\n\n" : ""}${filesSection}${c89Note}## Build + run with romdev\n\nThe whole project directory builds in ONE call — romdev infers the toolchain, crt0, and linker from the directory, so you don't pass a file manifest:\n\n${projectBuildBlock}\n\nAdd \`output:"run"\` instead of \`"project"\` to also load + run + screenshot in the same round trip. Re-run the exact same call after every edit.\n\n<details>\n<summary>Alternative: build from a hand-specified source manifest (when compiling edited loose source, not a project dir)</summary>\n\n${buildBlock}\n</details>\n\n## Iterating\n\n- Edit \`${mainFilename}\` (or any of the runtime / crt0 / cfg files — they're yours).\n- Re-run the \`build({output:"project"|"run", path})\` call above to see your changes — it builds + (for run) loads + runs + screenshots in one round trip.\n- Inspect at byte level: \`memory({op:"read"})\`, \`sprites({op:"inspect"})\`, \`palette({source:"live"})\`, \`background({view:"rendered"})\`.\n- Open a playtest window for human eyes: \`playtest({op:"open"})\` — returns immediately, the window follows your rebuilds, and the emulator stays live for every other tool.\n`;
   await fs.writeFile(path.join(projPath, "README.md"), readme, "utf-8");
   writtenFiles.push("README.md");
 
@@ -1828,19 +1833,46 @@ Compiles **C89**, not C99/C11. Stick to:
     }
   }
 
+  // Split the manifest: project-OWNED files (main.c, runtime helpers, crt0,
+  // cfg, README…) are the only ones an agent touches; the rest are internal
+  // toolchain copies on disk that never enter a decision. Echoing all of
+  // them — 35/44 on NES (vendor/cc65/libsrc/*), 173/264 on GBA (libtonc
+  // include/+sysinclude/), ~270 on SGDK Genesis — was pure context noise
+  // across a matrix run. Default to a compact receipt (owned list + a
+  // not-owned COUNT); `verbose:true` restores the full flat list.
+  //
+  // Classify NON-owned by what it actually is, NOT just a `vendor/` prefix:
+  // the cc65 path lands under vendor/, but the GBA/Genesis SDKs drop their
+  // header trees at include/ + sysinclude/ (no vendor/ prefix) and prebuilt
+  // crt objects/archives at the root — none of which an agent edits. (R: the
+  // original `!startsWith('vendor/')` denylist missed exactly these two SDK
+  // platforms — same bug class as the original fix, second location.)
+  const isVendored = (f) =>
+    f.startsWith("vendor/") ||                    // cc65 libsrc, pvsneslib, sgdk src
+    f.startsWith("include/") ||                   // SDK header trees (libtonc/libgba/SGDK/maxmod)
+    f.startsWith("sysinclude/") ||                // libgba/libtonc system headers
+    /^crt[a-z0-9]*\.o$/i.test(f) ||               // prebuilt crt objects (crti/crtn/crtbegin/crtend)
+    /\.(a|lib)$/i.test(f);                         // prebuilt static archives
+  const ownedFiles = writtenFiles.filter((f) => !isVendored(f));
+  const vendorFileCount = writtenFiles.length - ownedFiles.length;
   return {
     path: projPath,
     platform,
     template: hasTemplates ? (template ?? "default") : null,
-    files: writtenFiles,
+    // The files you actually edit. Vendored toolchain copies are summarized,
+    // not listed — they're on disk under vendor/ if you ever need them.
+    files: ownedFiles,
+    fileCount: writtenFiles.length,
+    vendorFileCount,
+    ...(verbose ? { allFiles: writtenFiles } : {}),
     snippetsCopied: withSnippets ? snippetFiles : null,
     sourceFile: path.join(projPath, mainFilename),
     toolchain: lang,
-    nextStep: `Edit ${path.join(projPath, mainFilename)} and call build({output:"run", ...}) with sourcesPaths/includePaths pointing at the project's files (see the README's "Build + run" block for the exact call). Everything you need is in the directory — nothing is hidden.`,
+    nextStep: `Build the scaffold AS-IS in one call: build({output:"project", platform:"${platform}", path:"${projPath}", outputPath:"<game>.<ext>"}) — it infers the toolchain/crt0/linker from the directory, no sourcesPaths/includePaths/linkerConfig needed. Then edit ${mainFilename} and re-run the same call. (build({output:"run", ...}) with a hand-specified sourcesPaths manifest is the alternative when you're compiling edited loose source instead of a project dir.)`,
   };
 }
 
-async function createGameCore({ platform, genre, name, path: projPath, title, overwrite }) {
+async function createGameCore({ platform, genre, name, path: projPath, title, overwrite, verbose = false }) {
       // The five canonical genres. A genre is available on a platform iff
       // TEMPLATES[platform] has a matching template entry — we DERIVE
       // availability from TEMPLATES rather than maintain a parallel table,
@@ -1887,7 +1919,7 @@ async function createGameCore({ platform, genre, name, path: projPath, title, ov
       // Genre id IS the template id (they're 1:1 by construction).
       const templateId = genre;
       const result = await createProjectImpl({
-        platform, template: templateId, name, path: projPath, title, overwrite,
+        platform, template: templateId, name, path: projPath, title, overwrite, verbose,
       });
       return { ...result, genre, template: templateId };
 }
@@ -1917,6 +1949,7 @@ export function registerProjectTools(server, z) {
       // project
       template: z.string().optional().describe("op=project: template id ('default' | 'hello_sprite' | 'tile_engine' on NES/GB/GBC; 'default' elsewhere)."),
       withSnippets: z.boolean().default(false).describe("op=project: also drop every vetted snippet alongside main (= scaffold copySnippets after)."),
+      verbose: z.boolean().default(false).describe("op=project/game: echo the FULL flat file manifest (incl. vendor/** toolchain copies) as `allFiles`. Default false — the response lists only project-OWNED files you edit (`files`) plus a `vendorFileCount`, since the vendored toolchain copies are on disk and never need echoing (they're 35 of 44 entries on NES, ~270 on SGDK Genesis). Set true only if you specifically need every path in the response."),
       // game
       genre: z.string().optional().describe("op=game: 'shmup' | 'platformer' | 'puzzle' | 'sports' | 'racing'."),
       // snippets

package/src/mcp/tools/record.js

@@ -44,11 +44,12 @@ export function registerRecordTools(server, z, sessionKey) {
         .array(
           z.object({
             atFrame: z.number().int().min(0),
-            ports: z.array(inputShape).max(2),
+            ports: z.array(inputShape).max(2).optional(),
+            keys: z.array(z.string()).optional().describe("C64-ONLY: C64 keyboard keys held from this frame until the next entry (f1/f3/f5/f7, return, space, run/stop, a-z, 0-9, …). [] releases all held keys. Unknown keys are rejected with a clear error. Lets you script a keyboard+joystick startup timeline (e.g. {atFrame:0,keys:['f1']},{atFrame:30,ports:[{b:true}]},{atFrame:90,keys:['run/stop']}) in one call."),
           }),
         )
         .optional()
-        .describe("Per-frame input changes. Each entry sets the input at `atFrame` and holds it until the next entry."),
+        .describe("Per-frame input changes. Each entry sets the input at `atFrame` (joystick `ports` and/or C64 `keys`) and holds it until the next entry. Either field is optional — a step may set just keys, just ports, or both."),
       memorySamples: z
         .array(
           z.object({
@@ -99,7 +100,12 @@ export function registerRecordTools(server, z, sessionKey) {
       while (elapsed < frames) {
         // Apply any scripted inputs whose atFrame ≤ current frame.
         while (scriptIdx < script.length && script[scriptIdx].atFrame <= elapsed) {
-          host.setInput({ ports: script[scriptIdx].ports });
+          const entry = script[scriptIdx];
+          if (entry.ports) host.setInput({ ports: entry.ports });
+          // C64 keyboard keys held from this entry until the next. Pass [] to
+          // release all. Only valid on a C64/VICE host (setC64HeldKeys throws
+          // otherwise — surfaced as a clear error, not a silent no-op).
+          if (entry.keys !== undefined) host.setC64HeldKeys(entry.keys);
           scriptIdx++;
         }
         const batch = Math.min(sampleEvery, frames - elapsed);