romdevtools 0.13.0

package/src/mcp/tools/input.js

@@ -0,0 +1,227 @@
+import { getHost } from "../state.js";
+import { jsonContent, safeTool } from "../util.js";
+import { getInputLayoutCore } from "./input-layout.js";
+
+// Resolve a platform-native button alias to the libretro button the host
+// understands. Genesis pads have A/B/C (+ X/Y/Z on 6-button) which libretro
+// maps onto a/b/y (+ x/.../z); the common confusion is Genesis `c`. SMS/GG
+// pads label their two buttons 1/2 → libretro a/b. Pass-through otherwise.
+// Exported so watchMemory/runUntilWrite's `pressDuring` resolves aliases the
+// same way the standalone pressButton tool does.
+export function resolveButtonAlias(button, platform) {
+  // Only the platform-NATIVE aliases (c / 1 / 2) are remapped here; raw
+  // libretro names (a/b/x/y) and spatial names (north/east/south/west) pass
+  // through unchanged so pressButton stays consistent with setInput.
+  //
+  // genesis_plus_gx maps the Genesis face buttons A/B/C onto libretro y/b/a
+  // respectively (verified empirically against the running core 2026-06-05),
+  // so the Genesis-native button C is libretro 'a'. (Earlier this mapped
+  // c→y, which actually pressed Genesis A — the inverted bug a feedback agent
+  // hit when SGDK BUTTON_A wouldn't fire. Genesis A/B are libretro y/b, reached
+  // via setInput({y/b}) or the spatial east/south/west names.)
+  if (platform === "genesis" || platform === "megadrive" || platform === "md") {
+    if (button === "c") return "a";   // Genesis C = libretro A
+  }
+  if (platform === "sms" || platform === "gg") {
+    // genesis_plus_gx maps SMS/GG button 1 (TL) → libretro 'b' and button 2 (TR)
+    // → libretro 'a' (verified empirically against the running gpgx core
+    // 2026-06-05 — same a↔primary inversion as the Genesis A/B/C → y/b/a map).
+    if (button === "1") return "b";   // button 1 (TL) = libretro B
+    if (button === "2") return "a";   // button 2 (TR) = libretro A
+  }
+  // If a native alias wasn't resolved for this platform, fall back to a sane
+  // default so the call doesn't silently press nothing. (Genesis C → libretro a;
+  // for non-gpgx platforms 1→a/2→b is the libretro-standard order.)
+  if (button === "c") return "a";
+  if (button === "1") return "a";
+  if (button === "2") return "b";
+  return button;
+}
+
+function buttonShape(z) {
+  return z
+    .object({
+      // D-pad
+      up: z.boolean().optional(),
+      down: z.boolean().optional(),
+      left: z.boolean().optional(),
+      right: z.boolean().optional(),
+      // Cross-platform face buttons (spatial — preferred for portability)
+      north: z.boolean().optional(),
+      east: z.boolean().optional(),
+      south: z.boolean().optional(),
+      west: z.boolean().optional(),
+      // Raw libretro names (also supported; spatial names are resolved to these per platform)
+      a: z.boolean().optional(),
+      b: z.boolean().optional(),
+      x: z.boolean().optional(),
+      y: z.boolean().optional(),
+      l: z.boolean().optional(),
+      r: z.boolean().optional(),
+      l2: z.boolean().optional(),
+      r2: z.boolean().optional(),
+      l3: z.boolean().optional(),
+      r3: z.boolean().optional(),
+      start: z.boolean().optional(),
+      select: z.boolean().optional(),
+    })
+    .describe(
+      "Per-port controller state. Prefer the spatial face-button names (north/east/south/west) for cross-platform code — they map to the physical button in that compass position on each platform's controller (e.g. on NES east=A, on SNES east=A, on Genesis east=C). Raw libretro names (a/b/x/y/l/r/...) also work if you need direct control. Omitted buttons are released.",
+    );
+}
+
+// ── *Core functions for the `input` tool ──
+
+/** op:'set' — set held controller state (persists until changed). */
+function inputSetCore({ ports }, sessionKey) {
+      getHost(sessionKey).setInput({ ports });
+      const requested = ports.map((p) => Object.keys(p).filter((k) => p[k] === true));
+      return { inputSet: true, requested };
+}
+
+/** op:'press' — press one named button N frames then release (port 0 default). */
+function inputPressCore({ button, frames = 2, port: p = 0 }, sessionKey) {
+      const host = getHost(sessionKey);
+      const resolved = resolveButtonAlias(button, host.status.platform);
+      const pressed = { ports: [{}, {}] };
+      pressed.ports[p][resolved] = true;
+      host.setInput(pressed);
+      host.stepFrames(frames);
+      host.setInput({ ports: [{}, {}] });
+      host.stepFrames(1);
+      return {
+        button,
+        ...(resolved !== button ? { resolvedTo: resolved } : {}),
+        frames,
+        releaseFrames: 1,
+        framesStepped: frames + 1,
+        frameCount: host.status.frameCount,
+      };
+}
+
+/** op:'sequence' — scripted frame-by-frame inputs (ports shape per step). */
+function inputSequenceCore({ steps }, sessionKey) {
+      const host = getHost(sessionKey);
+      let total = 0;
+      for (const step of steps) {
+        host.setInput(step.input);
+        host.stepFrames(step.frames);
+        total += step.frames;
+      }
+      return { stepsRun: steps.length, framesRun: total, frameCount: host.status.frameCount };
+}
+
+/** op:'navigate' — drive menus by advancing on SCREEN CHANGE; reports consumed per step. */
+function inputNavigateCore({ steps }, sessionKey) {
+      const host = getHost(sessionKey);
+      const platform = host.status.platform;
+      const results = [];
+      let totalFrames = 0;
+      for (const step of steps) {
+        const resolved = resolveButtonAlias(step.button, platform);
+        const before = host.framebufferHash();
+        const pressed = { ports: [{}, {}] };
+        pressed.ports[0][resolved] = true;
+        host.setInput(pressed);
+        host.stepFrames(step.holdFrames);
+        totalFrames += step.holdFrames;
+        host.setInput({ ports: [{}, {}] });
+        host.stepFrames(1);
+        totalFrames += 1;
+        let waited = 0, consumed = false;
+        for (let i = 0; i < step.maxWaitFrames; i++) {
+          host.stepFrames(1);
+          waited++; totalFrames++;
+          if (host.framebufferHash() !== before) { consumed = true; break; }
+        }
+        if (consumed && step.settleFrames) {
+          host.stepFrames(step.settleFrames);
+          totalFrames += step.settleFrames;
+        }
+        results.push({
+          button: step.button,
+          ...(resolved !== step.button ? { resolvedTo: resolved } : {}),
+          consumed,
+          framesWaited: waited,
+        });
+      }
+      const dropped = results.filter((r) => !r.consumed).length;
+      return {
+        steps: results,
+        framesRun: totalFrames,
+        frameCount: host.status.frameCount,
+        ...(dropped ? { droppedPresses: dropped, note: `${dropped} step(s) had consumed:false — the screen never changed after the press (wrong screen / press dropped / game polls input on a specific frame). Re-run those steps, increase holdFrames, or reach the screen via state save/load.` } : {}),
+      };
+}
+
+const BUTTON_ENUM = [
+  "up", "down", "left", "right",
+  "north", "east", "south", "west",
+  "a", "b", "x", "y",
+  "l", "r", "l2", "r2", "l3", "r3",
+  "start", "select",
+  "c", "1", "2",
+];
+
+export function registerInputTools(server, z, sessionKey) {
+  const port = buttonShape(z);
+  server.tool(
+    "input",
+    "Drive the controller. `op`: 'set' | 'press' | 'sequence' | 'navigate' | 'layout'.\n" +
+    "'set': hold controller state (persists until changed) via `ports:[{a:true,...},{...}]`.\n" +
+    "'press': press one named `button` for `frames` then release (port 0 default).\n" +
+    "'sequence': scripted frame-by-frame `steps:[{input:{ports}, frames}]` for replays/tests.\n" +
+    "'navigate': walk a menu by advancing on SCREEN CHANGE — `steps:[{button, holdFrames?, maxWaitFrames?, " +
+    "settleFrames?}]`; reports `consumed` per step (false = the screen never reacted: wrong screen / press dropped / " +
+    "game polls on a specific frame).\n" +
+    "'layout': the platform's input register format + which buttons physically exist (call BEFORE writing input " +
+    "code or choosing controls).\n" +
+    "FACE-BUTTON TRAP: raw libretro names (a/b/x/y) are NOT the printed labels — Genesis maps A/B/C onto libretro " +
+    "y/b/a, so set({a:true}) presses Genesis C and Genesis A is {y:true}. Prefer SPATIAL names (north/east/south/" +
+    "west) or press/navigate's native aliases (Genesis c→a internally, SMS/GG 1/2→b/a). layout.faceButtons has the " +
+    "exact map. NOTE on 'set': `requested` is what you SET, NOT proof the pad saw it — the game only reads input " +
+    "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."),
+      // 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."),
+      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, ...)."),
+    },
+    safeTool(async (args) => {
+      switch (args.op) {
+        case "set": {
+          if (!args.ports) throw new Error("input({op:'set'}): `ports` is required.");
+          return jsonContent(inputSetCore(args, sessionKey));
+        }
+        case "press": {
+          if (!args.button) throw new Error("input({op:'press'}): `button` is required.");
+          return jsonContent(inputPressCore(args, sessionKey));
+        }
+        case "sequence": {
+          if (!args.steps) throw new Error("input({op:'sequence'}): `steps` is required.");
+          return jsonContent(inputSequenceCore(args, sessionKey));
+        }
+        case "navigate": {
+          if (!args.steps) throw new Error("input({op:'navigate'}): `steps` is required.");
+          // Fill per-step defaults the old navigate schema provided.
+          const steps = args.steps.map((s) => ({ holdFrames: 2, maxWaitFrames: 120, settleFrames: 2, ...s }));
+          return jsonContent(inputNavigateCore({ steps }, sessionKey));
+        }
+        case "layout": {
+          if (!args.platform) throw new Error("input({op:'layout'}): `platform` is required.");
+          return jsonContent(getInputLayoutCore(args));
+        }
+        default: throw new Error(`input: unknown op '${args.op}'`);
+      }
+    }),
+  );
+}
+

package/src/mcp/tools/lifecycle.js

@@ -0,0 +1,132 @@
+import { resolveCore } from "../../cores/registry.js";
+import { defaultMediaKind } from "../../host/index.js";
+import { clearHost, getHost, getHostOrNull, resetHost } from "../state.js";
+import { jsonContent, safeTool, textContent } from "../util.js";
+import { resolveCheatCodeForApply } from "./cheats.js";
+
+const MEDIA_KINDS = ["cartridge", "disk", "tape", "program"];
+
+export function registerLifecycleTools(server, z, sessionKey) {
+  // Shared loader: accepts a file `path` OR base64 `bytes` (exactly one).
+  async function doLoadMedia({ platform, path, base64, mediaKind, virtualName, cheats }) {
+    const resolved = resolveCore(platform);
+    if (!resolved) throw new Error(`no core available for platform '${platform}'`);
+    if (!path && !base64) throw new Error("loadMedia: provide either `path` (file on disk) or `base64` (ROM bytes).");
+    if (path && base64) throw new Error("loadMedia: provide `path` OR `base64`, not both.");
+    const host = resetHost(sessionKey);
+    await host.loadCore(resolved.jsPath, resolved.wasmPath);
+    const bytes = base64 ? new Uint8Array(Buffer.from(base64, "base64")) : undefined;
+    await host.loadMedia({
+      platform,
+      ...(bytes ? { bytes, virtualName } : { path }),
+      mediaKind: mediaKind ?? defaultMediaKind(platform),
+    });
+
+    // Pre-seed cheats BEFORE the first frame — so a boot-time cheat (e.g. a Game
+    // Genie code that changes a value the reset code reads) is in effect from
+    // frame 0. Raw ROM codes are re-encoded to a read-intercept (same as
+    // applyCheat) so they don't silently no-op. Applied only if the core has the
+    // cheat interface; otherwise reported as skipped.
+    let appliedCheats;
+    if (cheats && cheats.length) {
+      appliedCheats = [];
+      const supported = host.cheatsSupported && host.cheatsSupported();
+      cheats.forEach((raw, i) => {
+        if (!supported) { appliedCheats.push({ code: raw, applied: false, reason: "core has no cheat interface" }); return; }
+        const { code, appliedAs, reencodedFrom } = resolveCheatCodeForApply(raw, platform);
+        try {
+          host.setCheat(i, code, true);
+          appliedCheats.push({ code, appliedAs, ...(reencodedFrom ? { reencodedFrom } : {}), applied: true });
+        } catch (e) {
+          appliedCheats.push({ code: raw, applied: false, reason: e?.message ?? String(e) });
+        }
+      });
+    }
+    // Framebuffer dimensions are NOT known until the core has run at least one
+    // frame — before that, fbWidth/fbHeight hold a pre-boot default (e.g.
+    // 256×192 on Genesis) that does NOT match the real output resolution
+    // (256×224 after booting). Reporting it here misleads any agent that routes
+    // on dimensions, so we omit it until a frame has been stepped and point the
+    // caller at stepFrames instead.
+    const framebufferKnown = host.status.frameCount > 0;
+    return jsonContent({
+      loaded: true,
+      platform,
+      core: resolved.coreName,
+      mediaKind: host.status.mediaKind,
+      ...(bytes ? { bytes: bytes.length } : { path: host.status.mediaPath }),
+      ...(framebufferKnown
+        ? { framebuffer: { width: host.status.fbWidth, height: host.status.fbHeight } }
+        : { framebufferNote: "Framebuffer dimensions are unknown until the core runs — call stepFrames first, then getStatus (the pre-boot default does not match the real output resolution)." }),
+      ...(appliedCheats ? { cheats: appliedCheats } : {}),
+    });
+  }
+
+  server.tool(
+    "loadMedia",
+    "Load a ROM/disk/tape/program into a fresh host — resolves the libretro core automatically. " +
+    "Pass `path` (file on disk) OR `base64` (ROM bytes — e.g. straight from buildSource, no disk write, " +
+    "for a fast iteration loop). `cheats` apply BEFORE the first frame (one call instead of loadMedia + " +
+    "applyCheat), so a boot-time code that changes a value the reset code reads is in effect from frame 0. " +
+    "NOTE: framebuffer dimensions are omitted until you stepFrames — the pre-boot default does not match the " +
+    "real output resolution.",
+    {
+      platform: z.string().describe("Platform id (e.g. 'nes', 'gb', 'c64'). Use listPlatforms() to discover."),
+      path: z.string().optional().describe("Absolute path to the media file. Provide this OR `base64`."),
+      base64: z.string().optional().describe("Base64-encoded media bytes. Provide this OR `path`."),
+      mediaKind: z.enum(MEDIA_KINDS).optional().describe("Default 'cartridge' for consoles, 'program' for C64."),
+      virtualName: z.string().optional().describe("With `base64`: virtual filename shown to cores that fopen() the path (default '/rom')."),
+      cheats: z.array(z.string()).max(64).optional().describe("Codes applied before the first frame (Game Genie / raw ADDR:VAL[:COMPARE] / native device codes). A raw ROM-address code is re-encoded to a read-intercept so it doesn't silently no-op. Returns a per-code `cheats:[{code, appliedAs, applied}]` report."),
+    },
+    safeTool(doLoadMedia),
+  );
+
+
+  server.tool(
+    "host",
+    "Emulator host lifecycle. `op`: 'unload' | 'shutdown' | 'reset' | 'pause' | 'resume'. " +
+    "(Loading media is the separate `loadMedia` tool.)\n" +
+    "'unload': drop the current media but keep the core hot (for a fast ROM swap). 'shutdown': tear the host down " +
+    "entirely (a later loadMedia makes a fresh one).\n" +
+    "'reset': DEFAULT is a SOFT reset (the RESET button — retro_reset; on most cores does NOT clear work RAM, so " +
+    "boot-seeded variables PERSIST). Pass `hard:true` for a TRUE power-cycle that reloads the ROM from scratch and " +
+    "clears RAM + re-seeds boot state — use it when re-testing boot-time behavior (a soft reset boots the PREVIOUS " +
+    "state).\n" +
+    "'pause': halt emulation (stepFrames returns 0 until resume). 'resume': continue.",
+    {
+      op: z.enum(["unload", "shutdown", "reset", "pause", "resume"]).describe("unload media; shutdown the host; reset (soft/hard); pause; resume."),
+      hard: z.boolean().default(false).describe("op=reset: true = full power-cycle (reload the ROM; clears work RAM + boot-seeded state). false (default) = soft RESET-button reset (RAM persists)."),
+    },
+    safeTool(async ({ op, hard }) => {
+      switch (op) {
+        case "unload": {
+          const host = getHostOrNull(sessionKey);
+          if (host) host.unloadMedia();
+          return textContent("unloaded");
+        }
+        case "shutdown":
+          clearHost(sessionKey);
+          return textContent("shutdown complete");
+        case "reset": {
+          const host = getHost(sessionKey);
+          if (hard) {
+            const reloaded = await host.hardReset();
+            return textContent(reloaded ? "reset (hard / power-cycle — RAM cleared)" : "reset (soft — no cached ROM to reload for a hard reset)");
+          }
+          host.reset();
+          return textContent("reset (soft — RESET button; work RAM persists, use hard:true to clear it)");
+        }
+        case "pause":
+          getHost(sessionKey).pause();
+          return textContent("paused");
+        case "resume":
+          getHost(sessionKey).resume();
+          return textContent("resumed");
+        default:
+          throw new Error(`host: unknown op '${op}'`);
+      }
+    }),
+  );
+
+  // getStatus folded into catalog({op:'status'}) (entry-tier, in index.js).
+}

package/src/mcp/tools/lospec.js

@@ -0,0 +1,187 @@
+// lospec.js — R17 helper to fetch a CC0 retro palette from lospec.com
+// by id, with optional snap to a target platform's master palette via
+// nearest-neighbour. Feeds straight into quantizePngForPlatform's
+// per-palette overrides.
+
+import { jsonContent, safeTool } from "../util.js";
+import { resolveIntent } from "../../platforms/common/intent.js";
+import { inspectPaletteCore, getPlatformMasterPaletteCore } from "./platform-tools.js";
+
+/** lospec.com hosts each palette at https://lospec.com/palette-list/<id>.json. */
+const LOSPEC_URL_BASE = "https://lospec.com/palette-list";
+
+/**
+ * Fetch a lospec palette by id (the URL slug, e.g. "kirokaze-gameboy").
+ * @param {string} id
+ * @returns {Promise<{name:string, colors:number[][], author?:string, url:string}>}
+ */
+async function fetchLospecPalette(id) {
+  if (!/^[a-z0-9-]+$/.test(id)) {
+    throw new Error(
+      `getLospecPalette: id '${id}' looks malformed. Use the URL slug as it appears on lospec.com — ` +
+      `lowercase letters, digits, and hyphens only (e.g. 'kirokaze-gameboy', 'pico-8', 'sweetie-16').`
+    );
+  }
+  const url = `${LOSPEC_URL_BASE}/${id}.json`;
+  let res;
+  try {
+    res = await fetch(url);
+  } catch (e) {
+    throw new Error(`getLospecPalette: network fetch failed for ${url}: ${e.message}`);
+  }
+  if (res.status === 404) {
+    throw new Error(
+      `getLospecPalette: no palette named '${id}' found on lospec.com. ` +
+      `Check the URL slug from the palette's page (https://lospec.com/palette-list/${id}).`
+    );
+  }
+  if (!res.ok) {
+    throw new Error(`getLospecPalette: lospec returned HTTP ${res.status} for ${url}.`);
+  }
+  const data = await res.json();
+  // lospec JSON shape: { name, author, colors: [["RRGGBB", ...], ...] } — colors are hex strings.
+  /** @type {string[]} */
+  const rawColors = data.colors ?? [];
+  const colors = rawColors.map((hex) => {
+    const clean = String(hex).replace(/^#/, "");
+    if (!/^[0-9a-fA-F]{6}$/.test(clean)) {
+      throw new Error(`getLospecPalette: lospec '${id}' returned malformed color '${hex}'.`);
+    }
+    return [
+      parseInt(clean.slice(0, 2), 16),
+      parseInt(clean.slice(2, 4), 16),
+      parseInt(clean.slice(4, 6), 16),
+    ];
+  });
+  return {
+    name: data.name ?? id,
+    author: data.author,
+    colors,
+    url: `https://lospec.com/palette-list/${id}`,
+  };
+}
+
+/**
+ * Snap each color in `palette` to the nearest entry in `master`.
+ * Used when the caller wants a lospec palette but the platform has a
+ * fixed hardware palette (NES 2C02 master, etc.).
+ */
+function snapToMaster(palette, master) {
+  return palette.map(([r, g, b]) => {
+    let best = master[0];
+    let bestD = Infinity;
+    for (const [mr, mg, mb] of master) {
+      const dr = r - mr, dg = g - mg, db = b - mb;
+      const d = dr * dr + dg * dg + db * db;
+      if (d < bestD) { bestD = d; best = [mr, mg, mb]; }
+    }
+    return best;
+  });
+}
+
+/**
+ * Programmatic equivalent of the MCP tool. Exported for tests.
+ *
+ * @param {{id:string, asPlatform?:string}} args
+ */
+export async function getLospecPaletteImpl({ id, asPlatform }) {
+  const fetched = await fetchLospecPalette(id);
+  if (!asPlatform) {
+    return {
+      id,
+      name: fetched.name,
+      author: fetched.author,
+      url: fetched.url,
+      colors: fetched.colors,
+      snappedToMaster: false,
+    };
+  }
+  // Snap to platform master where one exists. Today: NES only — other
+  // platforms have full 24-bit color and don't need snapping. The
+  // platform-specific snap functions are kept private to their tool
+  // files; for NES we mirror the NES_MASTER table inline so this module
+  // stays self-contained.
+  if (asPlatform === "nes") {
+    // Re-export the table by re-importing — keeps sprite-pipeline.js the
+    // single source of truth for the NES master palette.
+    const { snapToNesMasterPublic } = await getNesMasterSnap();
+    const snapped = fetched.colors.map(([r, g, b]) => snapToNesMasterPublic(r, g, b));
+    return {
+      id,
+      name: fetched.name,
+      author: fetched.author,
+      url: fetched.url,
+      colors: snapped,
+      sourceColors: fetched.colors,
+      snappedToMaster: true,
+      asPlatform,
+    };
+  }
+  // Other platforms don't have a hardware master to snap to (or we
+  // haven't tabulated one). Return colors verbatim with a note.
+  return {
+    id,
+    name: fetched.name,
+    author: fetched.author,
+    url: fetched.url,
+    colors: fetched.colors,
+    snappedToMaster: false,
+    asPlatform,
+    note: `Platform '${asPlatform}' has no hardware master palette to snap to (or none tabulated yet). Returning lospec colors verbatim.`,
+  };
+}
+
+// Lazy import of the NES master snap to avoid pulling in sprite-pipeline.js's
+// full module surface at load time.
+async function getNesMasterSnap() {
+  const mod = await import("./sprite-pipeline.js");
+  if (typeof mod.snapToNesMasterPublic === "function") return mod;
+  // Fallback: re-export under a private name. Implementation reuses
+  // the master table that already lives in sprite-pipeline.js.
+  throw new Error("getLospecPalette: internal — snapToNesMasterPublic not exported from sprite-pipeline.js");
+}
+
+export function registerLospecTools(server, z, sessionKey) {
+  server.tool(
+    "palette",
+    "Color palettes — read the running ROM's live palette, get a platform's master palette, or fetch a Lospec " +
+    "palette. `source`: 'live' | 'platformMaster' | 'lospec'.\n" +
+    "'live': the loaded ROM's ACTIVE palette as a normalized {index,r,g,b}[] list + a PNG swatch sheet. NES (32: " +
+    "16 BG + 16 sprite; `area`/`subPalette` filters), SNES (256, BGR555), Genesis (64 = 4 sub-palettes×16, grouped), " +
+    "GB/GBC, SMS/GG, Atari 2600 (4 active, beam-raced snapshot), 7800, C64 (16 fixed), GBA (256 BG + 256 OBJ; `area` " +
+    "picks the bank), Lynx (16, Mikey), PCE (512 = 256 BG + 256 SPR; `area` picks the bank), MSX (16, V9938 or fixed " +
+    "TMS9918). The color list is ALWAYS returned; the swatch PNG is path-or-inline.\n" +
+    "'platformMaster': the platform's full hardware master palette as `png` (default — the ImageMagick -remap " +
+    "target), `lospec` JSON (LibreSprite), or `hex` text. `outputPath` writes to disk.\n" +
+    "'lospec': a CC0 palette from lospec.com by `id` slug (e.g. 'kirokaze-gameboy', 'pico-8'); `asPlatform` snaps " +
+    "each color to that platform's master (NES today). Feeds quantize.",
+    {
+      source: z.enum(["live", "platformMaster", "lospec"]).describe("live = running ROM's palette; platformMaster = hardware master; lospec = a lospec.com palette."),
+      platform: z.string().optional().describe("source=live: override platform (else loaded host). source=platformMaster: REQUIRED."),
+      // live
+      area: z.enum(["bg", "sprite", "all"]).default("all").describe("source=live NES: 'bg' (0-15), 'sprite' (16-31), 'all' (default). GBA: bg/sprite banks."),
+      subPalette: z.number().int().min(0).max(3).optional().describe("source=live NES: one 4-entry sub-palette within `area`."),
+      outputPath: z.string().optional().describe("source=live: write the swatch PNG here (or inline:true). source=platformMaster: write output here."),
+      inline: z.boolean().default(false).describe("source=live: return the swatch image inline instead of writing to disk."),
+      // platformMaster
+      format: z.enum(["png", "lospec", "hex"]).default("png").describe("source=platformMaster: 'png' (swatch, default) / 'lospec' (JSON) / 'hex' (one #RRGGBB per line)."),
+      // lospec
+      id: z.string().optional().describe("source=lospec: the palette slug (lowercase/digits/hyphens) from its lospec.com URL."),
+      asPlatform: z.string().optional().describe("source=lospec: snap each color to this platform's master (NES today)."),
+    },
+    safeTool(async (args) => {
+      switch (args.source) {
+        case "live":           return await inspectPaletteCore(args, sessionKey);
+        case "platformMaster": {
+          if (!args.platform) throw new Error("palette({source:'platformMaster'}): `platform` is required.");
+          return await getPlatformMasterPaletteCore(args);
+        }
+        case "lospec": {
+          if (!args.id) throw new Error("palette({source:'lospec'}): `id` (the slug) is required.");
+          return jsonContent(await getLospecPaletteImpl(args));
+        }
+        default: throw new Error(`palette: unknown source '${args.source}'`);
+      }
+    }),
+  );
+}