romdevtools 0.16.0 → 0.22.0

package/src/mcp/tools/project.js

@@ -8,7 +8,6 @@
 // the project elsewhere and rebuild with cc65/sdcc directly, every byte
 // that compiles is in the directory.
 
-import { readFile, writeFile } from "node:fs/promises";
 import { jsonContent, safeTool } from "../util.js";
 import { starterSnippetsCore, copyStarterSnippetsCore } from "./snippets.js";
 
@@ -283,6 +282,11 @@ const TEMPLATES = {
       sprite_move: mk("sprite_move", "Joypad-controlled 16x16 sprite over a tiled background. d-pad moves the sprite; verified visible + responsive. Build up an action game from here."),
       music_sfx: mk("music_sfx", "HuC6280 PSG demo: a looping melody plus a button-fired SFX. Shows psg_tone/psg_off across the PSG's wavetable channels."),
       catch_game: mk("catch_game", "A complete tiny game: a paddle catches a falling object with the d-pad; full game loop with waitvsync(), two sprites, collision, scoring."),
+      shmup: mk("shmup", "Vertical shoot-'em-up for PC Engine. Player ship + bullet/enemy object pools, a wave spawner, AABB collisions, score HUD, scrolling-band starfield BG. d-pad flies, button I fires. The base for any action shooter."),
+      platformer: mk("platformer", "Side-scrolling platformer for PC Engine. Gravity + jump + land-on-top platform collision, a multi-screen world streamed via BG X-scroll (BXR), solid platform tiles, sub-pixel physics. d-pad moves, button I jumps."),
+      puzzle: mk("puzzle", "Match-3 / falling-block puzzle for PC Engine. A 6x12 well drawn with BG tiles, a 1x3 active piece you move/rotate/soft-drop/hard-drop, horizontal-triple clears, score. d-pad moves, I rotates, II hard-drops."),
+      sports: mk("sports", "Pong-style sports game for PC Engine. Two paddles + a bouncing ball on a netted court, score to 9, paddle-deflect physics; player 2 falls back to chase-AI when no input. d-pad moves P1."),
+      racing: mk("racing", "Top-down lane racer for PC Engine. Player car at the bottom, obstacle cars spawn from the top and slide down, LEFT/RIGHT switches lanes, speed grows with score, crash freeze + auto-reset. Scrolling road BG."),
     };
   })(),
 
@@ -299,6 +303,11 @@ const TEMPLATES = {
       sprite_move: mk("sprite_move", "Joystick-controlled sprite on a screen-2 background. d-pad moves the sprite; verified visible + responsive. The base for any action game."),
       music_sfx: mk("music_sfx", "AY-3-8910 PSG demo: a looping melody on channel A plus a trigger-fired SFX on channel C, with an on-screen indicator."),
       catch_game: mk("catch_game", "A complete tiny game: a paddle catches falling fruit with the joystick; full game loop with vblank sync, two sprites, collision, scoring."),
+      shmup: mk("shmup", "Vertical-shmup scaffold for MSX (screen 2). Player ship (sprite plane 0) + 4 bullet + 4 enemy object pools, a wave spawner, AABB collision, on-screen SCORE tiles, over a banded starfield filling the whole 32x24 name table. Joystick PORT 1 moves the ship (UP/DOWN/LEFT/RIGHT), trigger A (GTTRIG) fires; PSG blip on fire, noise-ish tone on a kill. Interrupt-free vsync via VDP status S#0. Extend with enemy fire, lives, scrolling stars."),
+      platformer: mk("platformer", "Side-scrolling platformer for MSX (screen 2). Subpixel gravity/jump/land-on-top collision against a table of platforms across a 512-px (64-cell) world, drawn by COLUMN STREAMING into the wrapping screen-2 name table as the camera follows the player; the player sprite draws in screen space. Joystick LEFT/RIGHT walks, trigger A jumps (only when grounded); PSG jump blip. Interrupt-free vsync. Extend with enemies, pickups, goal."),
+      puzzle: mk("puzzle", "Match-3 / falling-block puzzle for MSX (screen 2). A 6-wide x 12-tall well drawn with the BG tilemap (distinct R/G/B cell tiles + grey border + dim field interior so the playfield is always visible). A 1x3 active piece: joystick LEFT/RIGHT shifts, trigger A rotates the colour order, DOWN soft-drops, trigger B hard-drops; horizontal-triple clears score with a PSG chime. Interrupt-free vsync. Extend with vertical/diagonal matches, gravity-collapse, levels."),
+      sports: mk("sports", "Pong-style 2-player sports for MSX (screen 2). Court (green field + white sidelines + dashed centre net) fills the 32x24 name table; two paddles (stacked sprites) + a ball. Player 1 = joystick PORT 1 UP/DOWN; Player 2 = joystick PORT 2 UP/DOWN, falling back to chase-the-ball AI when no second pad is present so it is playable solo. Wall/paddle bounces + scoring with PSG bonks. Interrupt-free vsync. Extend with serve angles, score display, win condition."),
+      racing: mk("racing", "Top-down 3-lane racing for MSX (screen 2). Grey road + green-grass shoulders fill the name table; player car at the bottom, obstacle cars (object pool) spawn at the top and slide down. Joystick LEFT/RIGHT (edge-detected) switches lanes; obstacle speed grows with score; an AABB crash triggers a ~60-frame freeze then auto-reset, with a PSG crash tone. SCORE drawn as tiles. Interrupt-free vsync. Extend with pseudo-3D road, fuel, multiple cars."),
     };
   })(),
 };
@@ -1223,6 +1232,43 @@ TEMPLATES.atari2600 = {
     ext: ".a26",
     describe: "Gallery-shooter (Space-Invaders-shaped) done with the RIGHT TIA objects, not playfield 'barcode' bars: P0 = double-width cannon, P1 + NUSIZ1=%011 = a row of THREE hardware-replicated invaders (one GRP1 write draws all three), M0 = the player shot. Aliens march left/right and drop a step at the edges; fire with the joystick button. The honest 2600-idiomatic way to do this genre — extend by reusing P1 lower for shields or adding M1 as an alien bomb. Verified: marches + renders cannon/aliens/shot.",
   },
+  // ── Genre scaffolds ───────────────────────────────────────────────
+  // The 2600 maps cleanly onto only SOME of the five canonical genres.
+  // shmup + sports are the console's native idioms (Space Invaders /
+  // Pong); racing (top-down) and platformer (single-screen) are honest,
+  // period-correct fits. puzzle (match-3) is deliberately ABSENT — see
+  // the note after this block: a 6x12 multi-colour grid is not
+  // renderable on a tilemap-less, one-COLUPF-per-line, 2-player TIA, so
+  // shipping a "puzzle" key would mean shipping something that isn't a
+  // recognizable match-3. Genre id == template key (createGame maps 1:1).
+  shmup: {
+    main: "templates/shmup.asm",
+    runtime: [],
+    lang: "6507 assembly (dasm)",
+    ext: ".a26",
+    describe: "SHMUP — the 2600's flagship genre (Space Invaders / Galaxian / Demon Attack). Gallery shooter done with the RIGHT TIA objects: P0 = double-width cannon, P1 + NUSIZ1=%011 = a row of THREE hardware-replicated invaders (one GRP1 write draws all three), M0 = the player shot. Aliens march left/right and drop a step at the edges; fire with the joystick button. Same proven body as the `mini_invaders` template. Extend with M1 as an alien bomb or reuse P1 lower for shields.",
+  },
+  sports: {
+    main: "templates/sports.asm",
+    runtime: [],
+    lang: "6507 assembly (dasm)",
+    ext: ".a26",
+    describe: "SPORTS — Pong, the 2600's archetypal sport (Combat / Video Olympics). Two 8-px paddles (P0 left, P1 right), one 2-px ball (BL), top+bottom walls via reflected playfield. Joystick UP/DOWN drives the left paddle; the right paddle is AI (chases the ball's Y). Blip on wall bounce, chime on score. Same proven body as the `paddle` template. Demonstrates multi-object positioning (RESP0/RESP1/RESBL) + the 2-line kernel. Add a real P2 on the second port (SWCHA low nibble) to make it head-to-head.",
+  },
+  racing: {
+    main: "templates/racing.asm",
+    runtime: [],
+    lang: "6507 assembly (dasm)",
+    ext: ".a26",
+    describe: "RACING — top-down vertical-scroll lane racer, the honest 2600 racing idiom (Enduro-style; pseudo-3D road projection needs a per-line table the 4 KB/76-cycle starter budget can't spare). P0 = your car near the bottom (LEFT/RIGHT to weave), reflected playfield draws the two road rails + a dashed centre line that scrolls upward to convey speed, P1 + M0 = descending traffic/hazards you must dodge. Speed (and score) ramps the longer you survive; a TIA-collision crash flashes the screen red and resets your speed. Extend with M1 as a 3rd hazard or NUSIZ1 for two-abreast traffic.",
+  },
+  platformer: {
+    main: "templates/platformer.asm",
+    runtime: [],
+    lang: "6507 assembly (dasm)",
+    ext: ".a26",
+    describe: "PLATFORMER — SINGLE-SCREEN (Pitfall! / Montezuma / Kangaroo idiom). The 2600 has NO hardware scroll, no tilemap, 128 B RAM — a smooth side-scroller is not the honest fit (real games flip whole screens). This ships the genre CORE: fixed-point gravity + a jump arc (FIRE button), and land-on-top collision tested in CODE (not TIA collision, since you must know WHICH surface to stand on) against a 4-entry platform table drawn as horizontal playfield bars (the only TIA object wide enough to be a platform). Joystick walks L/R. Extend with ladders (UP/DOWN over a ladder x-span), an enemy on P1, a thrown rock on M0, or Pitfall-style screen-flipping at the edges. NOT a scroller — single screen by design.",
+  },
 };
 
 // R22: Atari 7800 promoted to multi-template platform. Each template is
@@ -1729,7 +1775,6 @@ Compiles **C89**, not C99/C11. Stick to:
   // runtime tmpl.runtime list typically includes them) are skipped.
   const snippetFiles = [];
   if (withSnippets) {
-    const { listSnippetsForPlatform } = await import("./snippets.js").catch(() => ({}));
     // Inline minimal duplicate of listSnippetsForPlatform since snippets.js
     // doesn't export it. Keep this in sync with snippets.js.
     const LIB_DIR = path.join(PLATFORM_LIB_DIR, "lib");
@@ -1810,15 +1855,13 @@ async function createGameCore({ platform, genre, name, path: projPath, title, ov
         ? CANONICAL_GENRES.filter((g) => platformTemplates[g])
         : [];
       if (availableGenres.length === 0) {
-        // Point at the real, working project templates each genre-less
-        // platform actually ships, so the agent has a concrete next step
-        // instead of a bare "default".
-        const PROJECT_TEMPLATE_HINTS = {
-          msx: "default, sprite_move, music_sfx, catch_game",
-          pce: "default, sprite_move, music_sfx, catch_game",
-          atari2600: "default, single_screen, paddle, mini_invaders, music_demo",
-        };
-        const hint = PROJECT_TEMPLATE_HINTS[platform];
+        // Reached only by a platform that ships NO canonical genre yet (every
+        // tier-1 platform now ships at least one — atari2600 ships 4, the rest
+        // ship all 5 — so in practice this is the bring-up / non-genre tier).
+        // List that platform's real project templates so the agent has a
+        // concrete next step instead of a bare "default".
+        const projTemplates = platformTemplates ? Object.keys(platformTemplates) : [];
+        const hint = projTemplates.length ? projTemplates.join(", ") : null;
         throw new Error(
           `createGame: no genre scaffolds for platform '${platform}' yet. ` +
           `Supported platforms: ${genrePlatforms.join(", ") || "(none)"}. ` +

package/src/mcp/tools/reinject.js

@@ -16,7 +16,6 @@
 // dev wiki (citations inline).
 
 import { readFile, writeFile } from "node:fs/promises";
-import { jsonContent, safeTool } from "../util.js";
 
 // ───────────────────────────────────────────────────────────────────────────
 // Pointer encoding per platform.

package/src/mcp/tools/rom-id.js

@@ -1,5 +1,5 @@
 import { imageContent, jsonContent, safeTool } from "../util.js";
-import { intentZod, resolveIntent } from "../../platforms/common/intent.js";
+import { resolveIntent } from "../../platforms/common/intent.js";
 import { getDefaultPalette, DEFAULT_PALETTES } from "../../platforms/common/default-palette.js";
 import { spliceChrCore } from "./splice-chr.js";
 import { relocateBlockCore, makeStoredBlockCore, findPointerToCore, PLATFORM_REGISTRY } from "./reinject.js";
@@ -65,7 +65,7 @@ export async function gbHeaderCore({ path: inPath, outputPath, cgb, title, cartT
   };
 }
 
-export function registerRomIdTools(server, z, sessionKey) {
+export function registerRomIdTools(server, z, _sessionKey) {
   // identifyRom folded into `cart`; patchFile/patchRom/spliceCHR/relocate/etc.
   // folded into the `romPatch` tool (router below).
   const PLATFORMS = Object.keys(PLATFORM_REGISTRY);

package/src/mcp/tools/snippets.js

@@ -13,7 +13,7 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { readdir, readFile, stat, mkdir, writeFile } from "node:fs/promises";
 
-import { jsonContent, safeTool, textContent, writeOutput } from "../util.js";
+import { jsonContent, textContent, writeOutput } from "../util.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -87,7 +87,7 @@ async function listSnippetsForPlatform(platform) {
   return out;
 }
 
-export function registerSnippetTools(server, z) {
+export function registerSnippetTools(_server, _z) {
   // ── Shared implementations for the three snippet modes ──────────
   async function snippetsList(platform, language) {
     const all = await listSnippetsForPlatform(platform);

package/src/mcp/tools/sprite-pipeline.js

@@ -15,7 +15,6 @@ import { readFile, writeFile } from "node:fs/promises";
 import { PNG } from "pngjs";
 import { jsonContent, safeTool } from "../util.js";
 import { intentZod, resolveIntent, intentError } from "../../platforms/common/intent.js";
-import { getDefaultPalette } from "../../platforms/common/default-palette.js";
 import { convertImageToTilesCore, imageToTilemapCore } from "./platform-tools.js";
 import { validateGenesisTilesCore } from "./metasprite-tools.js";
 
@@ -542,7 +541,7 @@ async function crossPlatformSpriteImportImpl(args) {
 
 // ── Register all three tools ─────────────────────────────────────────
 
-export function registerSpritePipelineTools(server, z, sessionKey) {
+export function registerSpritePipelineTools(server, z, _sessionKey) {
   server.tool(
     "encodeArt",
     "Encode a PNG into a platform's native art format, one tool keyed by `stage` — the PNG→tiles pipeline. " +

package/src/mcp/tools/state.js

@@ -3,6 +3,21 @@ import path from "node:path";
 import { getHost } from "../state.js";
 import { jsonContent, safeTool } from "../util.js";
 
+// Resolve a state-file `path`. An ABSOLUTE path is used as-is. A RELATIVE path
+// is resolved against the LOADED ROM's directory (the agent's mental model is
+// "save states live next to my ROM") — NOT the server's CWD, which is opaque to
+// the caller and was a silent ENOENT footgun (v0.15.0 feedback #1). Falls back
+// to CWD only when no ROM path is known (e.g. ROM loaded from base64).
+export function resolveStatePath(p, host) {
+  if (!p || path.isAbsolute(p)) return p;
+  const media = host?.status?.mediaPath;
+  // mediaPath is "<memory…>" for base64 loads — not a real dir; skip those.
+  if (media && !media.startsWith("<") && path.isAbsolute(media)) {
+    return path.resolve(path.dirname(media), p);
+  }
+  return path.resolve(p);
+}
+
 // Per-session state-diff baselines (op:'diff'). Module-local; keyed by sessionKey.
 const _stateDiffSnaps = new Map();
 function stateDiffSnapshots(key) {
@@ -19,16 +34,17 @@ async function saveStateCore({ name, path: outPath }, sessionKey) {
       const host = getHost(sessionKey);
       const done = [];
       if (name) { host.saveState(name); done.push(`slot '${name}'`); }
-      if (outPath) {
+      const resolvedOut = outPath ? resolveStatePath(outPath, host) : null;
+      if (resolvedOut) {
         const blob = host.serializeState();
-        await mkdir(path.dirname(outPath), { recursive: true });
-        await writeFile(outPath, blob);
-        done.push(`${blob.length} bytes → ${outPath}`);
+        await mkdir(path.dirname(resolvedOut), { recursive: true });
+        await writeFile(resolvedOut, blob);
+        done.push(`${blob.length} bytes → ${resolvedOut}`);
       }
       return {
         saved: true,
         ...(name ? { name } : {}),
-        ...(outPath ? { path: outPath } : {}),
+        ...(resolvedOut ? { path: resolvedOut, ...(resolvedOut !== outPath ? { resolvedPath: resolvedOut } : {}) } : {}),
         platform: host.status.platform,
         note: `Saved ${done.join(" + ")}.` + (outPath ? " Restore across sessions with state({op:'load', path}) after loading the same ROM." : ""),
       };
@@ -38,12 +54,14 @@ async function saveStateCore({ name, path: outPath }, sessionKey) {
 async function exportStateCore({ fromSlot, path: outPath }, sessionKey) {
       const host = getHost(sessionKey);
       const blob = host.getStateBlob(fromSlot); // throws if the slot is missing — no host disturbance
-      await mkdir(path.dirname(outPath), { recursive: true });
-      await writeFile(outPath, blob);
+      const resolvedOut = resolveStatePath(outPath, host);
+      await mkdir(path.dirname(resolvedOut), { recursive: true });
+      await writeFile(resolvedOut, blob);
       return {
         exported: true,
         fromSlot,
-        path: outPath,
+        path: resolvedOut,
+        ...(resolvedOut !== outPath ? { resolvedPath: resolvedOut } : {}),
         bytes: blob.length,
         platform: host.status.platform,
         note: "Copied the slot to disk; the live host was not touched (no pause/resume needed).",
@@ -56,8 +74,9 @@ async function loadStateCore({ name, path: inPath, render = true }, sessionKey)
       if (name && inPath) throw new Error("state({op:'load'}): provide `name` OR `path`, not both.");
       const host = getHost(sessionKey);
       let cheatsCleared = 0;
-      if (inPath) {
-        const blob = new Uint8Array(await readFile(inPath));
+      const resolvedIn = inPath ? resolveStatePath(inPath, host) : null;
+      if (resolvedIn) {
+        const blob = new Uint8Array(await readFile(resolvedIn));
         cheatsCleared = host.unserializeState(blob) || 0;
       } else {
         cheatsCleared = host.loadState(name) || 0;
@@ -66,7 +85,7 @@ async function loadStateCore({ name, path: inPath, render = true }, sessionKey)
       if (render) { host.renderOneFrame(); rendered = true; }
       return {
         loaded: true,
-        ...(inPath ? { path: inPath } : { name }),
+        ...(resolvedIn ? { path: resolvedIn, ...(resolvedIn !== inPath ? { resolvedPath: resolvedIn } : {}) } : { name }),
         platform: host.status.platform,
         rendered,
         ...(host.status.paused && rendered ? { renderedWhilePaused: true } : {}),
@@ -79,6 +98,153 @@ function listStatesCore(_args, sessionKey) {
   return { states: getHost(sessionKey).listStates() };
 }
 
+// SRAM presence: the battery-backed cartridge save RAM size for the loaded ROM
+// (0 = this cart/system has no battery save). Used by exportSram/importSram and
+// surfaced so an agent knows whether a save file even exists.
+function sramSize(host) {
+  try { return host.regionSize("save_ram"); } catch { return 0; }
+}
+
+/** op:'exportSram' — write the cartridge's battery SAVE RAM to a .sav file.
+ * This is the actual save-game file (distinct from a whole-machine savestate):
+ * the bytes a real cart keeps on its battery. Empty on a no-battery cart. */
+async function exportSramCore({ path: outPath }, sessionKey) {
+  const host = getHost(sessionKey);
+  const size = sramSize(host);
+  if (!size) {
+    throw new Error(
+      `state({op:'exportSram'}): the loaded ROM has no battery save RAM ` +
+      `(platform '${host.status.platform}', size 0). Either this cart has no battery ` +
+      `save, or this system never had cartridge saves (Atari 2600/7800, Lynx; C64 saves ` +
+      `are disk-based). Use state({op:'save', path}) for a full-machine savestate instead.`);
+  }
+  const blob = host.readMemory("save_ram", 0, size);
+  const resolved = resolveStatePath(outPath, host);
+  await mkdir(path.dirname(resolved), { recursive: true });
+  await writeFile(resolved, Buffer.from(blob));
+  return {
+    exportedSram: true,
+    path: resolved,
+    ...(resolved !== outPath ? { resolvedPath: resolved } : {}),
+    bytes: size,
+    platform: host.status.platform,
+    note: "Wrote the cartridge's battery SAVE RAM (the .sav save-game file). Restore with " +
+      "state({op:'importSram', path}) after loading the same ROM. This is the SAVE FILE, " +
+      "not a savestate — edit it offline (it's raw SRAM) or inject one a player made elsewhere.",
+  };
+}
+
+/** op:'importSram' — load a .sav file back into the cartridge's battery SAVE RAM. */
+async function importSramCore({ path: inPath }, sessionKey) {
+  const host = getHost(sessionKey);
+  const size = sramSize(host);
+  if (!size) {
+    throw new Error(
+      `state({op:'importSram'}): the loaded ROM has no battery save RAM ` +
+      `(platform '${host.status.platform}', size 0) — nowhere to load a .sav into.`);
+  }
+  const resolved = resolveStatePath(inPath, host);
+  const blob = new Uint8Array(await readFile(resolved));
+  if (blob.length !== size) {
+    // Size mismatch is the classic wrong-game/wrong-region footgun — surface it,
+    // but allow a smaller blob (zero-pad) since some dumps trim trailing zeros.
+    if (blob.length > size) {
+      throw new Error(
+        `state({op:'importSram'}): .sav is ${blob.length} bytes but this cart's SAVE RAM is ${size} ` +
+        `— too large (wrong game/region?). Refusing to truncate.`);
+    }
+  }
+  host.writeMemory("save_ram", 0, blob);
+  return {
+    importedSram: true,
+    path: resolved,
+    ...(resolved !== inPath ? { resolvedPath: resolved } : {}),
+    bytes: blob.length,
+    sramSize: size,
+    ...(blob.length < size ? { zeroPadded: size - blob.length } : {}),
+    platform: host.status.platform,
+    note: "Loaded the .sav into the cartridge's battery SAVE RAM. The running game sees it " +
+      "on its next save-RAM read (some games re-read only on a load/menu). " +
+      (blob.length < size ? `Blob was smaller than SRAM (${blob.length}<${size}); the tail kept its prior bytes.` : ""),
+  };
+}
+
+/** op:'exportDisk' — write the LIVE mounted C64 .d64 disk image to a file.
+ * The C64 analogue of exportSram: a game saves by writing files to its disk, and
+ * this snapshots the whole disk (incl. any saves the game wrote). C64/VICE only. */
+async function exportDiskCore({ path: outPath, unit = 8 }, sessionKey) {
+  const host = getHost(sessionKey);
+  if (!host.diskImageSupported || !host.diskImageSupported()) {
+    throw new Error("state({op:'exportDisk'}): disk images are a C64 feature (VICE). " +
+      `The loaded platform is '${host.status.platform}'.`);
+  }
+  const blob = host.exportDiskImage(unit); // throws if no .d64 mounted
+  const resolved = resolveStatePath(outPath, host);
+  await mkdir(path.dirname(resolved), { recursive: true });
+  await writeFile(resolved, Buffer.from(blob));
+  return {
+    exportedDisk: true,
+    path: resolved,
+    ...(resolved !== outPath ? { resolvedPath: resolved } : {}),
+    bytes: blob.length,
+    unit,
+    note: "Wrote the LIVE 1541 disk image (.d64) — the C64 save medium. Re-load it later " +
+      "with loadMedia({platform:'c64', path}) (it autostarts), or push it back into a " +
+      "running session with state({op:'importDisk', path}). This captures any files the " +
+      "game wrote to disk.",
+  };
+}
+
+/** op:'importDisk' — write a .d64 file back into the LIVE mounted C64 disk image. */
+async function importDiskCore({ path: inPath, unit = 8 }, sessionKey) {
+  const host = getHost(sessionKey);
+  if (!host.diskImageSupported || !host.diskImageSupported()) {
+    throw new Error("state({op:'importDisk'}): disk images are a C64 feature (VICE). " +
+      `The loaded platform is '${host.status.platform}'.`);
+  }
+  const resolved = resolveStatePath(inPath, host);
+  const blob = new Uint8Array(await readFile(resolved));
+  if (blob.length !== 174848) {
+    throw new Error(`state({op:'importDisk'}): '${resolved}' is ${blob.length} bytes — not a ` +
+      `standard 174848-byte 35-track .d64. Only that format round-trips through the live drive.`);
+  }
+  const n = host.importDiskImage(blob, unit);
+  return {
+    importedDisk: true,
+    path: resolved,
+    ...(resolved !== inPath ? { resolvedPath: resolved } : {}),
+    bytes: n,
+    unit,
+    note: "Wrote the .d64 into the running C64's mounted disk. The game sees it on its next " +
+      "disk access (a load/menu). Use this to inject a save disk a player made elsewhere.",
+  };
+}
+
+/** op:'putDiskFile' — write ONE PRG file into the LIVE mounted C64 disk (inject a save). */
+async function putDiskFileCore({ path: inPath, name, unit = 8 }, sessionKey) {
+  const host = getHost(sessionKey);
+  if (!host.diskImageSupported || !host.diskImageSupported()) {
+    throw new Error("state({op:'putDiskFile'}): disk files are a C64 feature (VICE). " +
+      `The loaded platform is '${host.status.platform}'.`);
+  }
+  if (!inPath) throw new Error("state({op:'putDiskFile'}): `path` (the file to write) is required.");
+  const resolved = resolveStatePath(inPath, host);
+  const blob = new Uint8Array(await readFile(resolved));
+  // file name on disk: explicit `name`, else the source basename (sans extension), uppercased
+  const fname = (name || path.basename(resolved).replace(/\.[^.]+$/, ""))
+    .toUpperCase().replace(/[^A-Z0-9 ]/g, "").slice(0, 16) || "FILE";
+  host.putDiskFile(fname, blob, unit);
+  return {
+    wroteDiskFile: true,
+    name: fname,
+    path: resolved,
+    bytes: blob.length,
+    unit,
+    note: "Wrote one PRG file into the running C64's mounted disk via the drive. Read the " +
+      "whole disk back with state({op:'exportDisk', path}) or cart({op:'extract'}).",
+  };
+}
+
 /** op:'dump' — raw libretro blob to disk for forensic inspection (+ optional findHex). */
 async function dumpStateCore({ path: outPath, findHex, maxMatches = 32 }, sessionKey) {
       const host = getHost(sessionKey);
@@ -159,9 +325,10 @@ export function registerStateTools(server, z, sessionKey) {
     "'list': named in-memory slots. 'diff': whole-machine 'did ANYTHING change?' (coarser than memory diff) — " +
     "snapOrDiff:'snapshot' captures, 'diff' compares.",
     {
-      op: z.enum(["save", "load", "list", "export", "dump", "diff"]).describe("save/load a state; list slots; export a slot to disk; dump the raw blob; diff the whole machine."),
-      name: z.string().min(1).optional().describe("op=save/load: in-memory slot name. op=diff: snapshot label (default 'default')."),
-      path: z.string().optional().describe("op=save: also write the blob here (survives restarts). op=load: restore from this disk blob. op=export/dump: write the blob here (required)."),
+      op: z.enum(["save", "load", "list", "export", "dump", "diff", "exportSram", "importSram", "exportDisk", "importDisk", "putDiskFile"]).describe("save/load a savestate (whole machine); list slots; export a slot to disk; dump the raw blob; diff the whole machine. SRAM (the cartridge BATTERY SAVE FILE, distinct from a savestate): exportSram writes the .sav, importSram loads one back. C64 DISK (VICE; the C64 save medium is a floppy, not battery SRAM): exportDisk writes the live .d64, importDisk pushes a .d64 back into the running drive, putDiskFile injects one PRG file into the live disk."),
+      name: z.string().min(1).optional().describe("op=save/load: in-memory slot name. op=diff: snapshot label (default 'default'). op=putDiskFile: file name on the disk (≤16 chars; default = source basename)."),
+      unit: z.number().int().min(8).max(11).default(8).describe("op=exportDisk/importDisk/putDiskFile (C64): drive unit (default 8)."),
+      path: z.string().optional().describe("op=save: also write the blob here (survives restarts). op=load: restore from this disk blob. op=export/dump: write the blob here (required). A RELATIVE path resolves against the loaded ROM's directory (NOT the server CWD); an absolute path is used as-is. The result echoes `resolvedPath` when they differ."),
       // load
       render: z.boolean().default(true).describe("op=load: step one frame after restoring so the framebuffer reflects it (fixes the stale-screenshot footgun). false = stay at the exact restored instant."),
       // export
@@ -190,6 +357,26 @@ export function registerStateTools(server, z, sessionKey) {
           if (!args.snapOrDiff) throw new Error("state({op:'diff'}): `snapOrDiff` ('snapshot' or 'diff') is required.");
           return jsonContent(diffStateCore(args, sessionKey));
         }
+        case "exportSram": {
+          if (!args.path) throw new Error("state({op:'exportSram'}): `path` (where to write the .sav) is required.");
+          return jsonContent(await exportSramCore(args, sessionKey));
+        }
+        case "importSram": {
+          if (!args.path) throw new Error("state({op:'importSram'}): `path` (the .sav to load) is required.");
+          return jsonContent(await importSramCore(args, sessionKey));
+        }
+        case "exportDisk": {
+          if (!args.path) throw new Error("state({op:'exportDisk'}): `path` (where to write the .d64) is required.");
+          return jsonContent(await exportDiskCore(args, sessionKey));
+        }
+        case "importDisk": {
+          if (!args.path) throw new Error("state({op:'importDisk'}): `path` (the .d64 to load) is required.");
+          return jsonContent(await importDiskCore(args, sessionKey));
+        }
+        case "putDiskFile": {
+          if (!args.path) throw new Error("state({op:'putDiskFile'}): `path` (the PRG file to inject) is required.");
+          return jsonContent(await putDiskFileCore(args, sessionKey));
+        }
         default: throw new Error(`state: unknown op '${args.op}'`);
       }
     }),

package/src/mcp/tools/tile-inspect.js

@@ -8,7 +8,7 @@
 // always reports `source: "file" | "emulator"` so the caller knows which.
 
 import { readFile } from "node:fs/promises";
-import { getHostOrNull, getHost } from "../state.js";
+import { getHost } from "../state.js";
 import { jsonContent, imageContent, textContent, safeTool } from "../util.js";
 import { inspectPatternTilesCore } from "./platform-tools.js";
 import { extractSpriteSheetCore } from "./rom-id.js";