romdevtools 0.13.0

package/src/mcp/tools/index.js

@@ -0,0 +1,339 @@
+// Register MCP tools on the server.
+//
+// The surface is ~34 consolidated domain tools (memory({op}), build({output}),
+// breakpoint({on}), …) and EVERY one registers at session init. There is no
+// progressive-disclosure / lean mode anymore: the dynamic loadCategory dance
+// never propagated reliably to clients (they don't re-read tools/list after a
+// list_changed notification), and the consolidated surface is small enough that
+// loading it all up front is simply correct. `catalog({op:'categories'})` still
+// exposes the category map for orientation — it's a guide, not a gate.
+//
+// The CATEGORIES array below still groups tools by purpose (used by catalog and
+// by the internal one-shot "build succeeded → consider playtest" hint), and
+// `disclosure.loadCategory("all")` is the internal "register every category"
+// helper — NOT a user-facing tool.
+//
+// Design principle "narrow at entry, deep once in": categories don't
+// gate access; they organize discoverability. Once loaded, primitives
+// are fully usable.
+
+import { randomUUID } from "node:crypto";
+import { registerLifecycleTools } from "./lifecycle.js";
+import { registerFrameTools } from "./frame.js";
+import { registerInputTools } from "./input.js";
+import { registerStateTools } from "./state.js";
+import { registerMemoryTools } from "./memory.js";
+import { registerToolchainTools } from "./toolchain.js";
+import { registerPlaytestTools } from "./playtest.js";
+import { registerPlatformTools as registerPlatformSpecificTools } from "./platform-tools.js";
+import { registerPlatformTools } from "./platforms.js";
+import { registerSymbolTools } from "./symbols.js";
+import { registerRomIdTools } from "./rom-id.js";
+import { registerDiffRomsTools } from "./diff-roms.js";
+import { registerFreeSpaceTools } from "./free-space.js";
+import { registerReinjectTools } from "./reinject.js";
+import { registerSpliceChrTools } from "./splice-chr.js";
+import { registerCartPartsTools } from "./cart-parts.js";
+import { registerFontMapTools } from "./font-map.js";
+import { registerDisasmTools } from "./disasm.js";
+import { registerFindReferencesTools } from "./find-references.js";
+import { registerRenderingContextTools } from "./rendering-context.js";
+import { registerTraceVramSourceTools } from "./trace-vram-source.js";
+import { registerRunUntilTools } from "./run-until.js";
+import { registerWatchMemoryTools } from "./watch-memory.js";
+import { registerAddressToSymbolTools } from "./address-to-symbol.js";
+import { registerRecordTools } from "./record.js";
+import { registerTileInspectTools } from "./tile-inspect.js";
+import { registerAssetTools } from "./assets.js";
+import { registerArtLoaderTools } from "./art-loaders.js";
+import { registerSpritePipelineTools } from "./sprite-pipeline.js";
+import { registerLospecTools } from "./lospec.js";
+import { registerMetaSpriteTools } from "./metasprite-tools.js";
+import { registerProjectTools } from "./project.js";
+import { registerInputLayoutTools } from "./input-layout.js";
+import { registerSnippetTools } from "./snippets.js";
+import { registerPlatformDocsTools } from "./platform-docs.js";
+import { registerAudioTools } from "./audio.js";
+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 { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+// 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 {
+    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
+ * tools themselves, just defer when they're added to the server.
+ *
+ * `sessionKey` is threaded into every register fn so handlers can scope
+ * `getHost(sessionKey)` etc. per MCP session. Toolchain/asset registers
+ * that don't touch host accept the extra arg harmlessly.
+ */
+const CATEGORIES = [
+  {
+    name: "platforms",
+    description: "Discover supported platforms, their cores, toolchains, and language matrices.",
+    useWhen: ["scaffolding a new project", "checking which platforms are available", "looking up a platform's default language"],
+    register: (s, z, k) => registerPlatformTools(s, z, k), // listPlatforms, resolvePlatform
+  },
+  {
+    name: "run",
+    description: "Load ROMs, step frames, take screenshots (PNG or ANSI/chafa for text-only agents), query host status.",
+    useWhen: ["just built a ROM and want to run it", "stepping frames to verify behavior", "capturing screenshots", "text-only LLM that needs to 'see' the frame — use screenshot({format:'ascii'})"],
+    register: (s, z, k) => { registerLifecycleTools(s, z, k); registerFrameTools(s, z, k); },
+  },
+  {
+    name: "input",
+    description: "Drive controllers, press buttons, learn each platform's hardware bit layout.",
+    useWhen: ["scripting button presses to reach a game state", "writing input-reading asm and need the register format"],
+    register: (s, z, k) => { registerInputTools(s, z, k); registerInputLayoutTools(s, z, k); },
+  },
+  {
+    name: "state",
+    description: "Save/load emulator snapshots, dump raw savestates for forensic inspection.",
+    useWhen: ["want to repro a bug from a specific frame", "comparing two emulator moments", "investigating an opaque core"],
+    register: (s, z, k) => registerStateTools(s, z, k),
+  },
+  {
+    name: "memory",
+    description: "Read/write platform memory regions: system_ram, save_ram, VRAM, plus platform extras (NES OAM, SNES CGRAM/ARAM/FillRAM).",
+    useWhen: ["inspecting variable values during play", "verifying that an upload landed in VRAM/ARAM", "patching memory live"],
+    register: (s, z, k) => registerMemoryTools(s, z, k),
+  },
+  {
+    name: "debug",
+    description: "Cross-platform debugging primitives: inspectSprites, inspectPalette, getCPUState (main/spc700/z80), getAudioState (dsp/psg/ym2612), disassemble, symbol lookup.",
+    useWhen: ["sprites rendering wrong", "audio silent or distorted", "CPU stuck in unknown state", "need to read what existing ROM bytes do"],
+    register: (s, z, k) => {
+      registerPlatformSpecificTools(s, z, k); // inspectSprites/Palette, getCPUState, getDspState, ...
+      registerSymbolTools(s, z, k);            // buildSourceWithDebug, resolveSymbol, lookupAddress, ...
+      registerDisasmTools(s, z, k);            // disassemble, disassembleRom
+      registerFindReferencesTools(s, z, k);    // findReferences
+      registerRenderingContextTools(s, z, k);  // background{view} (map/renderState/rendered)
+      registerTraceVramSourceTools(s, z, k);   // traceVramSource (Genesis VRAM-DMA source)
+      registerTileInspectTools(s, z, k);       // tiles{op} (png/pixels/fingerprints/ascii/preview)
+      registerAddressToSymbolTools(s, z, k);   // addressToSymbol — PC → C function name
+      registerCheatTools(s, z, k);             // gameCheats (labeled RAM/code map), applyCheat, clearCheats
+    },
+  },
+  {
+    name: "assets",
+    description: "Convert PNGs to platform tile formats, encode WAVs to BRR, scan ROMs to identify them.",
+    useWhen: ["importing graphics or audio assets", "checking what a ROM file is"],
+    register: (s, z, k) => { registerAssetTools(s, z, k); registerAudioTools(s, z, k); registerRomIdTools(s, z, k); registerDiffRomsTools(s, z, k); registerFreeSpaceTools(s, z, k); registerReinjectTools(s, z, k); registerSpliceChrTools(s, z, k); registerCartPartsTools(s, z, k); registerFontMapTools(s, z, k); registerArtLoaderTools(s, z, k); registerSpritePipelineTools(s, z, k); registerLospecTools(s, z, k); registerMetaSpriteTools(s, z, k); },
+  },
+  {
+    name: "project",
+    description: "Project scaffolding + starter snippets per platform.",
+    useWhen: ["starting a new game from scratch", "looking up canonical patterns like NMI handler, OAM DMA, joypad read"],
+    register: (s, z, k) => { registerProjectTools(s, z, k); registerSnippetTools(s, z, k); registerPlatformDocsTools(s, z); },
+  },
+  {
+    name: "show",
+    description: "Show the game to a human: playtest opens a native SDL window where your user can watch and play. The emulator stays live — every other tool (screenshot, readMemory, saveState, pause, stepFrames, ...) keeps working against the SAME running ROM. Call this category early so your human can see progress instead of waiting for build logs.",
+    useWhen: ["agent just got a build working and wants the user to see it", "showing the user a feature mid-development", "letting the user play-test what was built", "any time the user would benefit from watching the game live"],
+    register: (s, z, k) => { registerPlaytestTools(s, z, k); },
+  },
+  {
+    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"],
+    register: (s, z, k) => { registerRunUntilTools(s, z, k); registerWatchMemoryTools(s, z, k); registerRecordTools(s, z, k); },
+  },
+];
+
+/**
+ * @param {import("@modelcontextprotocol/sdk/server/mcp.js").McpServer} server
+ * @param {any} z zod (passed in to avoid duplicate-package issues)
+ * @param {string} sessionKey opaque per-McpServer identifier used to scope
+ *   host state — each MCP session gets its own LibretroHost so two agents
+ *   pointed at the same server can't clobber each other's loaded ROM /
+ *   screenshots / memory reads.
+ */
+export function registerTools(server, z, sessionKey) {
+  // Tests and other in-process callers may omit sessionKey — mint one so
+  // host state is still isolated per registerTools() call.
+  if (!sessionKey) sessionKey = randomUUID();
+  // Clear validation errors for EVERY tool registered below: turns the SDK's
+  // raw JSON validation dump into a plain sentence and catches unknown/misspelled
+  // params (which the SDK otherwise drops silently). One wrap, all 34 tools.
+  // This is what lets the param descriptions stay terse — the guidance lives in
+  // the error (paid only on a bad call), not in every agent's initial context.
+  server = withClearToolErrors(server, z);
+  // ---- entry-tier disclosure manager ----
+  const disclosure = createDisclosure(server, z, CATEGORIES, sessionKey);
+  // Share with tool handlers outside this module (toolchain.js etc.) so
+  // they can emit one-shot session hints (e.g. nudge to playtest after
+  // the first successful build).
+  setDisclosure(disclosure);
+
+  // ---- ALWAYS-LOADED ENTRY TIER ----
+  // catalog: what categories exist + the live session snapshot.
+  server.tool(
+    "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: z.enum(["categories", "status", "whatsNew"]).default("categories")
+        .describe("categories=tool-category catalog; status=live session snapshot (host/platform/frameCount/media); whatsNew=recent CHANGELOG + old→new tool rename table."),
+    },
+    safeTool(async ({ op = "categories" }) => {
+      if (op === "whatsNew") {
+        return jsonContent(await buildWhatsNew());
+      }
+      if (op === "status") {
+        const host = getHostOrNull(sessionKey);
+        const cats = disclosure.listCategories();
+        const base = host
+          ? { ...host.getStatus() }
+          : { loaded: false, hint: "no host yet; call loadMedia (in category 'run') to load a ROM" };
+        return jsonContent({
+          ...base,
+          loadedCategories: cats.filter((c) => c.loaded).map((c) => c.name),
+          unloadedCategories: cats.filter((c) => !c.loaded).map((c) => c.name),
+        });
+      }
+      const categories = disclosure.listCategories();
+      return jsonContent({
+        categories,
+        note: "Every tool registers at session init — this catalog is just a map grouped by purpose, NOT a gate. Call any tool by name directly.",
+        humanInTheLoopHint: "Iterate INTERNALLY on screenshots first (build({output:'run'}) returns one inline; frame({op:'screenshot'/'stepAndShot'}) re-shoots the live host) — don't open a window to debug. Once the game actually boots and shows the feature you're working on, call playtest({}) so your human can watch and play it live. Opening a window on a black screen or a crash just wastes the human's attention — show them something that works.",
+      });
+    }),
+  );
+
+  // loadCategory + describeTool DELETED with the progressive-disclosure path:
+  // the whole surface is ~34 tools now and every one registers at session init,
+  // so the dynamic lean-mode dance (which never worked reliably — clients don't
+  // re-read tools/list after list_changed) has no reason to exist. `catalog`
+  // still exposes the category map for orientation. (See the consolidation.)
+
+  // getStatus is now catalog({op:'status'}).
+
+  // build is the universal build verb. Almost every workflow
+  // starts with "build my ROM," so we register it at entry tier
+  // unconditionally — but the rest of the toolchain category stays
+  // deferred (runSource, listToolchains, etc.).
+  registerToolchainTools(server, z, sessionKey);
+
+  // playtest is ALSO entry-tier. The whole point of the server is getting
+  // games in front of people — so the "open a native window the human can
+  // watch/play" tool must be callable the instant there's a ROM, with no
+  // loadCategory dance. Two separate agents got stuck because playtest sat
+  // behind the 'show' category. It's still LISTED under 'show' for
+  // discovery, but registered here so it's live from session start.
+  // (registerCategorySafely skips the duplicate when 'show' loads.)
+  registerPlaytestTools(server, z, sessionKey);
+
+  // ---- AUTO-ARM THE FULL TOOL SURFACE ----
+  // Progressive disclosure was causing more harm than good: agents needed
+  // 4-5 serial loadCategory round-trips to arm a normal game-dev workflow
+  // (run + assets + debug + memory + ...), discovered each missing category
+  // only when a call failed, and re-called loadCategory in a loop — made far
+  // worse when a session reconnects (re-arm cost). The full surface is ~36K
+  // tokens; for a coding agent that's an acceptable one-time cost, and it
+  // removes the thrash + the "I can't see the tool" confusion entirely.
+  //
+  // So by default we register EVERY category at session init. listCategories
+  // / loadCategory still exist (idempotent, harmless) for clients that probe
+  // Register EVERY category now — there is no lean/deferred mode anymore. The
+  // surface is small enough (~34 tools) that loading it all up front is the
+  // right call (the dynamic loadCategory dance never propagated reliably to
+  // clients). `disclosure.loadCategory("all")` is just the internal "register
+  // all categories" helper here, not a user-facing tool.
+  try {
+    disclosure.loadCategory("all");
+  } catch (e) {
+    console.error("[mcp] category registration failed:", e?.message ?? e);
+  }
+}
+
+// ---- helper: which category owns a tool name? ----
+// Used so describeTool's error message can name the category to load.
+// Maintained by hand for now; if categories explode we can derive this
+// by registering each category into a dummy server and comparing diffs.
+const TOOL_OWNER = {
+  // platforms category
+  platform: "platforms",
+  // run category
+  loadMedia: "run", host: "run",
+  frame: "run",
+  // input category
+  input: "input",
+  // state category
+  state: "state",
+  // memory category
+  memory: "memory",
+  // debug category
+  tiles: "debug", sprites: "debug",
+  background: "debug", encodeArt: "assets",
+  cpu: "debug", audioDebug: "debug",
+  symbols: "debug",
+  disasm: "debug",
+  cheats: "debug",
+  inspectTile: "debug",
+  // assets category
+  encodeAudio: "assets",
+  cart: "assets",
+  listRoms: "assets", romPatch: "assets", validateRom: "assets",
+  assembleSnippet: "assets",
+
+  text: "assets",
+  importArt: "assets",
+  palette: "debug",
+  // project category
+  scaffold: "project",
+  // show category (was: advanced)
+  playtest: "show",
+  // advanced category
+  runUntil: "advanced",
+  watch: "advanced", breakpoint: "advanced", dmaTrace: "advanced",
+  recordSession: "advanced",
+  // entry tier itself
+  catalog: "entry",
+  build: "entry", listRunnableFormats: "entry",
+};
+
+function ownerCategoryOf(name) {
+  return TOOL_OWNER[name] ?? null;
+}

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

@@ -0,0 +1,231 @@
+// getInputLayout — return per-platform input register/protocol info plus
+// the libretro→hardware id mapping. Lets agents writing asm input handlers
+// know exactly what each bit/id means.
+
+import { FACE_BUTTON_MAP } from "../../host/types.js";
+import { jsonContent, safeTool } from "../util.js";
+
+const HARDWARE_LAYOUTS = {
+  nes: {
+    register: "$4016 (port 1), $4017 (port 2)",
+    protocol: "strobe-and-shift",
+    strobe: "Write 1 then 0 to $4016 to latch button state.",
+    readSequence: "Each read of $4016 returns the next button in bit 0. Read 8 times.",
+    bitOrder: ["A", "B", "Select", "Start", "Up", "Down", "Left", "Right"],
+    note: "Bit 0 of each read is the button state. After 8 reads with `lsr ; rol keydown`, keydown holds A in bit 7 ... Right in bit 0.",
+    faceButtons: FACE_BUTTON_MAP.nes,
+  },
+  gb: {
+    register: "$FF00 (P1/JOYP)",
+    protocol: "row-select",
+    strobe: "Write bit 5 low to select directions, bit 4 low to select buttons.",
+    readSequence: "Bits 0-3 read low when the corresponding button in the selected row is pressed.",
+    bitOrder: [
+      "Right/A (bit 0)",
+      "Left/B (bit 1)",
+      "Up/Select (bit 2)",
+      "Down/Start (bit 3)",
+    ],
+    note: "Active-low. Bit 0 with directions selected = Right; with buttons selected = A.",
+    faceButtons: FACE_BUTTON_MAP.gb,
+  },
+  gbc: {
+    register: "$FF00 (P1/JOYP)",
+    protocol: "row-select",
+    strobe: "Same as Game Boy. CGB adds nothing here.",
+    readSequence: "Same as Game Boy.",
+    bitOrder: ["Right/A", "Left/B", "Up/Select", "Down/Start"],
+    faceButtons: FACE_BUTTON_MAP.gbc,
+  },
+  snes: {
+    register: "$4016 (port 1), $4017 (port 2)",
+    protocol: "strobe-and-shift",
+    strobe: "Write 1 then 0 to $4016. Same protocol as NES, 16 reads.",
+    readSequence: "16 reads per port — first 12 are buttons, last 4 are device-id padding.",
+    bitOrder: [
+      "B", "Y", "Select", "Start",
+      "Up", "Down", "Left", "Right",
+      "A", "X", "L", "R",
+      "(0)", "(0)", "(0)", "(1)",
+    ],
+    faceButtons: FACE_BUTTON_MAP.snes,
+  },
+  genesis: {
+    register: "$A10003 (port 1), $A10005 (port 2)",
+    protocol: "select-line",
+    strobe: "TH bit (bit 6) of CTRL register selects which set of buttons is read.",
+    readSequence: "TH=0: read Up/Down/0/0/A/Start. TH=1: read Up/Down/Left/Right/B/C. 6-button pad uses extra TH transitions.",
+    bitOrder: ["Up", "Down", "Left/0", "Right/0", "B/A", "C/Start"],
+    note: "Bit positions vary by TH state. genesis_plus_gx maps the Genesis face buttons A/B/C onto libretro Y/B/A respectively — so to PRESS a Genesis button via setInput: Genesis A → setInput({y:true}) (or spatial {west:true}), Genesis B → {b:true} (spatial {south:true}), Genesis C → {a:true} (spatial {east:true}). NOTE the inversion: libretro 'a' is Genesis C, NOT Genesis A. (libretro 'C' doesn't exist; the 6-button pad's X/Y/Z map to libretro x/north/l.) Use pressButton({button:'c'}) for the Genesis-native alias, or getInputLayout's faceButtons. Verified empirically against genesis_plus_gx 2026-06-05.",
+    faceButtons: FACE_BUTTON_MAP.genesis,
+  },
+  atari2600: {
+    register: "SWCHA ($280), INPT4/INPT5 (fire buttons)",
+    protocol: "direct-read",
+    strobe: "None — bits are wired directly.",
+    readSequence: "SWCHA: high nibble = player 1 directions (active-low). INPT4 bit 7 = player 1 fire (active-low).",
+    bitOrder: ["P1 Right", "P1 Left", "P1 Down", "P1 Up", "P2 Right", "P2 Left", "P2 Down", "P2 Up"],
+    note: "One fire button per player. Active-low everywhere.",
+    faceButtons: FACE_BUTTON_MAP.atari2600,
+  },
+  c64: {
+    register: "$DC00 (CIA1 PRA, port 2) and $DC01 (PRB, port 1)",
+    protocol: "direct-read",
+    strobe: "None.",
+    readSequence: "Bits 0-4 are Up/Down/Left/Right/Fire, active-low.",
+    bitOrder: ["Up", "Down", "Left", "Right", "Fire"],
+    faceButtons: FACE_BUTTON_MAP.c64,
+  },
+  sms: {
+    register: "I/O port $DC (controllers, read via `in a,($DC)`) and $DD (port 2 high bits + reset)",
+    protocol: "direct-read",
+    strobe: "None — the SMS reads controller bits directly from the Z80 I/O port.",
+    readSequence: "$DC: bit0 P1 Up, bit1 P1 Down, bit2 P1 Left, bit3 P1 Right, bit4 P1 button 1 (TL), bit5 P1 button 2 (TR), bits6-7 P2 Up/Down. $DD: bits0-3 P2 Left/Right/TL/TR, bit6 reset. ALL ACTIVE-LOW (0 = pressed).",
+    bitOrder: ["P1 Up", "P1 Down", "P1 Left", "P1 Right", "P1 Button1", "P1 Button2", "P2 Up", "P2 Down"],
+    note: "Active-low: a pressed button reads 0. Two face buttons per pad (1=TL, 2=TR); no Start on the SMS pad (the console has a physical Pause button wired to the Z80 NMI). genesis_plus_gx maps button 1 (TL) → libretro 'b' and button 2 (TR) → libretro 'a' (NOTE the inversion: setInput({a:true}) presses button 2, not button 1). Spatial names are correct: west→button 1, east→button 2. pressButton({button:'1'|'2'}) takes the printed labels. Verified vs gpgx 2026-06-05.",
+    faceButtons: FACE_BUTTON_MAP.sms,
+  },
+  gg: {
+    register: "I/O port $DC (D-pad + buttons 1/2) and $00 (START button, bit 7)",
+    protocol: "direct-read",
+    strobe: "None — same VDP/controller chip as the SMS, read directly from Z80 I/O.",
+    readSequence: "$DC: bit0 Up, bit1 Down, bit2 Left, bit3 Right, bit4 button 1, bit5 button 2 — all active-low. The Game Gear's extra START button is bit 7 of port $00 (also active-low).",
+    bitOrder: ["Up", "Down", "Left", "Right", "Button1", "Button2"],
+    note: "Active-low. Handheld single controller. START is at port $00 bit 7, NOT in $DC. genesis_plus_gx maps button 1 → libretro 'b' and button 2 → libretro 'a' (same inversion as SMS — setInput({a:true}) presses button 2), START → 'start'. Spatial names are correct: west→button 1, east→button 2. Verified vs gpgx 2026-06-05.",
+    faceButtons: FACE_BUTTON_MAP.gg,
+  },
+  atari7800: {
+    register: "SWCHA ($0280, RIOT — directions), INPT0/INPT1 (2-button ProLine fire) OR INPT4/INPT5 (1-button/2600-compat fire), CTLSWA/CTLSWB ($0281/$0283) to select mode",
+    protocol: "direct-read",
+    strobe: "None for directions. ⚠ The fire-button read DEPENDS on controller mode: a 2-button ProLine pad reads fire via INPT0 (right/button 2/libretro 'a') + INPT1 (left/button 1/libretro 'b') when the port is driven; a 1-button or 2600-style joystick reads fire via INPT4/INPT5. Set the CTLSWx mode bits accordingly before reading. (Default boot is 1-BUTTON mode — both 'a' and 'b' collapse onto INPT4 until you enable 2-button mode by driving CTLSWB bit2.)",
+    readSequence: "SWCHA: high nibble = player 1 directions (active-low: bit7 Right, bit6 Left, bit5 Down, bit4 Up). ProLine fire: INPT0/INPT1 bit 7 (the polarity flips with the port-drive state — verify against the emulator with readMemory). 2600-compat fire: INPT4/INPT5 bit 7 (active-low).",
+    bitOrder: ["P1 Right", "P1 Left", "P1 Down", "P1 Up", "P2 Right", "P2 Left", "P2 Down", "P2 Up"],
+    note: "The 2-button-vs-1-button fire path is the #1 7800 input footgun — if fire 'doesn't register', you're likely reading the wrong register for the pad mode. Directions are the SAME as the 2600 (shared RIOT SWCHA). libretro maps the two ProLine buttons onto JOYPAD 'a' → INPT0 (right/button 2) and 'b' → INPT1 (left/button 1), active-HIGH bit7 (confirmed empirically vs prosystem 2026-06-05 + Riot.c). NOTE: default boot is 1-BUTTON mode (SWCHB bit2 set) where BOTH 'a' and 'b' read via INPT4 (active-low) and INPT0/1 stay dead — enable 2-button mode (CTLSWB bit2 = output, SWCHB bit2 = 0) to split them. Verify empirically: drive holdInputs and readMemory the INPT register to confirm which bit moved.",
+    faceButtons: FACE_BUTTON_MAP.atari7800,
+  },
+  lynx: {
+    register: "Mikey JOYSTICK ($FCB0) — D-pad + A/B/Opt1/Opt2; SWITCHES ($FCB1) — Pause (bit 0)",
+    protocol: "direct-read",
+    strobe: "None — read the memory-mapped Mikey registers directly.",
+    readSequence: "JOYSTICK ($FCB0): bit7 Up, bit6 Down, bit5 Left, bit4 Right, bit3 Opt1, bit2 Opt2, bit1 B (inner), bit0 A (outer). ACTIVE-HIGH (1 = pressed) — unlike most retro pads. SWITCHES ($FCB1) bit0 = Pause.",
+    bitOrder: ["A", "B", "Opt2", "Opt1", "Right", "Left", "Down", "Up"],
+    note: "⚠ Two gotchas: (1) buttons are ACTIVE-HIGH on the Lynx (1=pressed), opposite the active-low convention almost everywhere else. (2) The D-pad's physical Up/Down/Left/Right is RELATIVE TO SCREEN ROTATION — Mikey flips the direction bits when the screen is set to the flipped/left-handed orientation, so 'Up' in code may be physical-down on a rotated game. cc65's lynx target + the bundled lynx lib expose these via joy_read-style helpers. libretro maps A→'a', B→'b', Opt1/Opt2→'start'/'select', Pause→'select' (verify with holdInputs + readMemory $FCB0).",
+    faceButtons: FACE_BUTTON_MAP.lynx,
+  },
+  pce: {
+    register: "Joypad port — strobe via the I/O port; the BIOS reads it for you",
+    protocol: "strobe-and-scan",
+    strobe: "The standard PCE pad is a 2-button pad (I and II) + Run + Select. A SEL/CLR strobe to the joyport latches the directions then the buttons; the cc65 pce target's joystick driver and the BIOS handle this.",
+    readSequence: "After strobe: a nibble for D-pad (Up/Right/Down/Left) then a nibble for buttons (I, II, Select, Run). Active-low.",
+    bitOrder: ["I", "II", "Select", "Run", "Up", "Right", "Down", "Left"],
+    note: "libretro maps button I → 'a' (east), II → 'b' (west), Run → 'start', Select → 'select'. The cc65 `pce` target exposes JOY_BTN_1_MASK/JOY_BTN_2_MASK + direction masks in pce.h. 6-button Avenue Pad exists but the standard pad is 2-button.",
+    faceButtons: FACE_BUTTON_MAP.pce,
+  },
+  msx: {
+    register: "PSG (AY-3-8910) port A/B via the PPI — read via BIOS GTSTCK ($00D5) + GTTRIG ($00D8)",
+    protocol: "bios-call",
+    strobe: "None for the common path — call the BIOS: GTSTCK(n) returns the joystick/cursor direction (0-8), GTTRIG(n) returns the trigger state. Direct PSG reads are possible but the BIOS is the portable way.",
+    readSequence: "GTSTCK: 0=center, 1-8 = the 8 compass directions (1=up, clockwise). GTTRIG: bit 7 set = trigger pressed. Trigger 1 = button 'a', trigger 2 = button 'b'.",
+    bitOrder: ["Trigger1", "Trigger2", "Up", "Down", "Left", "Right"],
+    note: "libretro maps trigger 1 → 'a' (east), trigger 2 → 'b' (west). The keyboard is also an input source on MSX (BIOS CHGET $009F / read the key matrix), but for games the joystick via GTSTCK/GTTRIG is the standard path. Port 0 = keyboard cursor + space; ports 1/2 = the joystick ports.",
+    faceButtons: FACE_BUTTON_MAP.msx,
+  },
+};
+
+const LIBRETRO_JOYPAD_IDS = {
+  b: 0, y: 1, select: 2, start: 3,
+  up: 4, down: 5, left: 6, right: 7,
+  a: 8, x: 9, l: 10, r: 11,
+  l2: 12, r2: 13, l3: 14, r3: 15,
+};
+
+// Per-platform mapping from button name → hardware register bit position
+// (as it appears in the ROM-readable joypad register, NOT libretro's id).
+// SNES read of $4218 returns a 16-bit value: button = (val & bit) != 0.
+// NES read of $4016 returns 8 sequential bits: each `lda $4016 ; lsr a ;
+// rol keydown` extracts one — bit-position here = byte position in that
+// keydown register after 8 shifts.
+//
+// These are the bits a ROM ACTUALLY reads. The libretro JOYPAD ids above
+// are protocol ids for setInput, NOT hardware bit positions. (Confusing
+// the two is a classic footgun.)
+const HARDWARE_BITS = {
+  nes: { // 8-bit shift register; bit positions in the 8-bit keydown byte
+    a: 0x80, b: 0x40, select: 0x20, start: 0x10,
+    up: 0x08, down: 0x04, left: 0x02, right: 0x01,
+  },
+  snes: { // 16-bit auto-read at $4218
+    b: 0x8000, y: 0x4000, select: 0x2000, start: 0x1000,
+    up: 0x0800, down: 0x0400, left: 0x0200, right: 0x0100,
+    a: 0x0080, x: 0x0040, l: 0x0020, r: 0x0010,
+  },
+  gb: { // $FF00 P1 register, active-low — bits 0-3
+    // Note: row-select dependent. These are the bits READ when each row is selected.
+    a: 0x01, b: 0x02, select: 0x04, start: 0x08,        // buttons row (bit 5 low)
+    right: 0x01, left: 0x02, up: 0x04, down: 0x08,      // directions row (bit 4 low)
+  },
+  gbc: { // Same as gb
+    a: 0x01, b: 0x02, select: 0x04, start: 0x08,
+    right: 0x01, left: 0x02, up: 0x04, down: 0x08,
+  },
+  genesis: { // $A10003 — bit positions depend on TH state
+    // TH=1 reads: bit 0=Up, 1=Down, 2=Left, 3=Right, 4=B, 5=C
+    up: 0x01, down: 0x02, left: 0x04, right: 0x08, b: 0x10, c: 0x20,
+    // TH=0 reads: bit 4=A, 5=Start
+    a: 0x10, start: 0x20,
+  },
+  c64: { // CIA1 PRB ($DC01), active-low — bits 0-4
+    up: 0x01, down: 0x02, left: 0x04, right: 0x08, fire: 0x10,
+  },
+  atari2600: { // SWCHA ($280) high nibble = P1; INPT4 ($28C) bit 7 = P1 fire
+    up: 0x10, down: 0x20, left: 0x40, right: 0x80, // SWCHA bits
+    fire: 0x80, // INPT4 bit 7
+  },
+};
+
+// Which physical buttons each platform actually has. The setInput surface
+// accepts the full Xbox-shaped set, but pressing buttons that aren't wired
+// on a platform is a silent no-op. This map lets the agent ask "what's real
+// here" instead of probing.
+const PHYSICAL_BUTTONS = {
+  // dpad and start/select are universal on platforms that have any input at all
+  nes:       ["up", "down", "left", "right", "east", "west", "start", "select"],
+  gb:        ["up", "down", "left", "right", "east", "west", "start", "select"],
+  gbc:       ["up", "down", "left", "right", "east", "west", "start", "select"],
+  sms:       ["up", "down", "left", "right", "east", "west", "start"],
+  gg:        ["up", "down", "left", "right", "east", "west", "start"],
+  snes:      ["up", "down", "left", "right", "north", "east", "south", "west", "l", "r", "start", "select"],
+  genesis:   ["up", "down", "left", "right", "east", "south", "west", "start"], // 3-button; 6-button adds north + l/r-like Z/X
+  gba:       ["up", "down", "left", "right", "east", "south", "l", "r", "start", "select"],
+  atari2600: ["up", "down", "left", "right", "south"],
+  atari7800: ["up", "down", "left", "right", "east", "south", "start", "select"],
+  lynx:      ["up", "down", "left", "right", "east", "south", "start"],
+  c64:       ["up", "down", "left", "right", "south"],
+  pce:       ["up", "down", "left", "right", "east", "west", "start", "select"], // pad I/II + Run/Select
+  msx:       ["up", "down", "left", "right", "east", "west"],                      // joystick + 2 triggers
+};
+
+/** op:'layout' on the `input` tool — platform input register format + physical buttons. */
+export function getInputLayoutCore({ platform }) {
+      const layout = HARDWARE_LAYOUTS[platform];
+      if (!layout) {
+        throw new Error(`no input layout documented for platform '${platform}'. Supported: ${Object.keys(HARDWARE_LAYOUTS).join(", ")}`);
+      }
+      return {
+        platform,
+        ...layout,
+        physicalButtons: PHYSICAL_BUTTONS[platform] ?? [],
+        controllerModel: "romdev uses an Xbox-shaped baseline for input: dpad + 4 face buttons (north/east/south/west) + l/r/l2/r2 + l3/r3 sticks + start/select. Older platforms are subsets — physicalButtons lists what's actually wired. Pressing a button not in that list is a silent no-op.",
+        libretroJoypadIds: LIBRETRO_JOYPAD_IDS,
+        hardwareBits: HARDWARE_BITS[platform] ?? null,
+        hardwareBitsCaveat:
+          "libretroJoypadIds are PROTOCOL ids for the input tool; they are NOT the bit positions a ROM reads from the hardware register. " +
+          "hardwareBits gives the actual register bits a ROM tests (e.g. SNES: `lda $4218 ; bit #$1000` for start). " +
+          "Confusing the two silently breaks input handling — verified by the rom-games agent's 30-min bisection that prompted this field.",
+        note2: "Names from libretroJoypadIds work universally. Spatial face-button names (north/east/south/west) translate to the right physical button per platform — east is A on NES/SNES, C on Genesis. Prefer spatial names in cross-platform code.",
+      };
+}
+
+// getInputLayout folded into the `input` tool as input({op:'layout'}).
+export function registerInputLayoutTools() { /* folded into `input` */
+}