romdevtools 0.22.0 → 0.23.0

package/AGENTS.md

@@ -399,6 +399,36 @@ When `build({output:'run'})` is too coarse, the long-form workflow:
 5. `input({op:'set'})` / `input({op:'press'})` / `input({op:'sequence'})` to drive the game
 6. `state({op:'save'}, "checkpoint")` / `state({op:'load'}, "checkpoint")` for try/undo
 
+## Diagnosing behavior over time (game-feel, not just "is it alive")
+
+`frame({op:'verify'})` answers "is it rendering / alive". When the screen looks
+plausible but the game is WRONG — choppy movement, a value that's off, a piece
+that locks mid-air — STOP eyeballing screenshots and trace the state. These tools
+already exist; reach for them by symptom:
+
+- **"Movement/scrolling feels choppy / camera desyncs / scroll jumps."**
+  `recordSession({frames:180, holdInputs:[{right:true}], includeScreenshots:false,
+  memorySamples:[{region, offset, length, label}]})` — holds input over N frames and
+  returns an analyzable timeline. Sample the player's screen-X + the scroll
+  registers (Genesis: `genesis_vsram` + the HSCROLL table in `video_ram`; per
+  platform varies) and look for camera scroll changing while the sprite barely
+  moves, or non-monotone deltas. `watch({on:'mem', format:'series', ranges:[...]})`
+  gives the same idea as a compact value-vs-frame CURVE per byte. (Genesis: see
+  its MENTAL_MODEL "Why does horizontal movement feel choppy?" — the usual cause
+  is rewriting tilemaps in the frame loop; `watch({on:'dma', perFrame:true})`
+  shows the per-frame DMA bytes that spike when you do.)
+- **"A computed value is wrong but the build is clean."** Don't re-read your C.
+  Resolve the variable's address and read it: `build({output:'romWithDebug',
+  resolveSymbols:["grid","score"]})` (or `symbols({op:'resolve', mapPath|dbgPath,
+  name})`) → `memory({op:'read', region, offset})`. Cheap, zero image tokens, and
+  it tells you whether the bug is your logic or your data. (sm83/z80: a "wrong
+  value" is far more often a WRAM layout collision than a miscompile — see the
+  GB/GBC SDCC_GOTCHAS "codegen traps in plain game logic".)
+- **"I can't tell what's on the background."** `background({view:'map'})` decodes
+  the BG tilemap (grid of tile indices, or a rendered PNG) — don't hand-compute
+  nametable offsets. Small handheld too tiny to read inline? `frame({op:'screenshot',
+  scale:4})` up-scales (nearest-neighbor).
+
 ## When a call fails: READ THE ERROR FIRST
 
 romdev errors are written FOR you — they name what went wrong AND how to recover. Read the message (and `issues[]`) before guessing, screenshotting, or retrying blindly. Two shapes:

package/CHANGELOG.md

@@ -4,6 +4,79 @@ All notable changes to `romdevtools`. Dates are release dates.
 (Published as `romdev-mcp` through 0.11.0; renamed to `romdevtools` in 0.13.0 —
 the `romdev-mcp` bin is kept as an alias.)
 
+## 0.23.0
+
+Response to two real build-session feedback reports (a GBC Columns clone + a
+Genesis Uridium POC). Theme: bugs found, false alarms removed, and — the recurring
+finding — **tools that already existed but agents couldn't find them**.
+
+### Fixed — multi-tenant host cross-talk (a whole class of bugs)
+`sprites({op:'inspect', platform:'genesis'})` returned a *GBC*-flavored error while
+Genesis was loaded. Root cause: `inspectSpritesCore` / `getCPUStateCore` /
+`getAudioStateCore` / `inspectBackgroundMapCore` / `inspectPatternTilesCore` were
+module-global `export let` bindings reassigned per session, each closing over THAT
+registration's `sessionKey` — so the last session to register stole the host for
+everyone. Now the caller's `sessionKey` is threaded through. Verified on all 7
+tile-based sprite platforms with sessions live simultaneously.
+
+### Fixed — SMS/GG C crt0: `static x = N;` initializers booted to 0
+Investigating two reported "silent sm83 miscompiles" (32-bit xorshift, indexed
+loop): NEITHER reproduces on GB/GBC — both produce byte-exact output. The real bug
+was a genuine **z80 crt0 defect**: `sms_crt0.s`/`gg_crt0.s` placed `_INITIALIZER`
+in RAM not ROM, so the gsinit `ldir` copied RAM onto itself → every value-static
+booted 0 and BSS wasn't zeroed. Fixed both (mirrors the correct `gb_crt0.s`).
+Re-verified all SMS/GG scaffolds still build clean + render.
+
+### Changed — lint stops crying wolf on WRAM copies
+The SDCC `xdata-copy-miscompile` warning fired on EVERY `dst[i]=src[i]` loop,
+including plain WRAM arrays (the message even said "ignore if plain WRAM") —
+training agents to ignore lint. Now: provably-VRAM dest → warning, plain RAM array
+→ suppressed, unknown → info. (Deliberately did NOT add the requested 32-bit-shift
+/ short-loop lint heuristics — they'd be false positives for non-bugs.)
+
+### Added — feedback ergonomics
+- **`frame({op:'screenshot', scale})` up-scales** (integer ≥2, nearest-neighbor)
+  for legible handheld shots (GB 160×144 → 640×576 at `scale:4`), plus the
+  existing `0<scale<1` downscale. All platforms.
+- **Cheap symbol→address:** `symbols({op:'resolve', dbgPath|mapPath, name})` reads
+  the map FILE on disk (no 63 KB round-trip through context); `build({output:
+  'romWithDebug', resolveSymbols:[...]})` folds just those addresses into the
+  result. cc65 `.dbg` / sdld `.map` / GNU ld `.map`.
+
+### Added — Genesis feel/perf diagnostics
+- **`watch({on:'dma', perFrame:true})`** — per-frame DMA-bytes timeline + spike
+  detection (catches "rewriting tilemaps in the frame loop", the #1 Genesis feel
+  bug). A hardware-scroll scaffold settles to a flat ~8 bytes/frame.
+- **`scaffold` template `two_plane_parallax`** — plane-A foreground + plane-B
+  repeated starfield + player sprite, hardware scroll only, zero loop-time tilemap
+  writes. Builds clean, renders, scrolls (verified).
+- Genesis MENTAL_MODEL/TROUBLESHOOTING: "do NOT rewrite tilemaps in the frame
+  loop", logical-vs-hardware plane size, the correct parallax loop, Sonic-style
+  column streaming, and a "why does movement feel choppy?" recipe.
+
+### Changed — discoverability (the recurring root cause)
+Several feedback "feature asks" were tools that already existed. `recordSession`
+(motion/telemetry timeline) was mislabeled in the catalog as "capture inputs for
+replay"; relabeled. New AGENTS.md "Diagnosing behavior over time (game-feel)"
+section maps symptom → existing tool (choppy movement → `recordSession`/`watch`
+series on scroll+sprite; wrong-but-clean value → `resolveSymbols` + `memory` read;
+can't-read-the-BG → `background({view:'map'})` + `screenshot scale:4`).
+
+### Other
+- `build({output:'project', path})` already defaults the gb/gbc/sms/gg/msx crt0 +
+  codeLoc — documented (the GBC agent was hand-passing them to `output:'rom'`).
+- P4 doc + a new info-level `wram-static-overlap` lint advisory (hardcoded
+  `$C000–$C0FF` pointer overlapping SDCC's static-data segment — the actual cause
+  of the reporter's "monochrome RNG").
+
+## 0.22.1
+
+Doc-only follow-up to 0.22.0's movement-analysis feedback: the `pressDuring`
+schema on `watch` and `breakpoint` now states that entries with OVERLAPPING
+windows on the same port are OR'd into a chord (e.g. `b`+`right` held while `a`
+fires mid-window), not overwritten. The driver already behaved this way; this
+documents the guarantee so it doesn't have to be confirmed empirically.
+
 ## 0.22.0
 
 **Transparency + correctness pass: every tool failure is actionable, dangerous

package/examples/genesis/templates/platformer.c

@@ -13,7 +13,11 @@
  * level fits in the scroll plane and plain VDP_setHorizontalScroll moves
  * it — a real working scroller with no streaming. For a world WIDER than
  * 512 px you additionally stream the column entering view each time camX
- * crosses an 8-px boundary (see MENTAL_MODEL.md "Horizontal scrolling").
+ * crosses an 8-px boundary (see MENTAL_MODEL.md "How Sonic-style large
+ * maps REALLY work"). For a from-scratch smooth-scroll + parallax
+ * starting point with NO per-frame tilemap writes, see the
+ * two_plane_parallax template + MENTAL_MODEL.md "Scrolling, parallax &
+ * the feel trap".
  */
 
 #include <genesis.h>

package/examples/genesis/templates/two_plane_parallax.c

@@ -0,0 +1,166 @@
+/* ── two_plane_parallax.c — Genesis SGDK two-plane parallax scaffold ──
+ *
+ * The "Uridium / Sonic-feel" starting point: a side-scrolling world that
+ * moves SMOOTHLY because the frame loop does HARDWARE SCROLL ONLY. There
+ * are ZERO tilemap writes inside the loop — the two planes are painted
+ * ONCE at setup, and every frame we just nudge two scroll registers and
+ * re-stage one sprite. This is the single most important thing to copy:
+ *
+ *     ★ Do NOT rewrite tilemaps in the frame loop. ★
+ *
+ * Rewriting a plane each frame is a big VDP/DMA burst that overruns
+ * vblank and makes movement feel choppy/juddery. Hardware scroll is free.
+ *
+ * Layout:
+ *   - Plane A (foreground): a painted "world" — a ground strip + scattered
+ *     platform blocks across a 512-px (64-cell) plane. Scrolls 1:1 with
+ *     the camera.
+ *   - Plane B (background): a repeated starfield filling the whole plane.
+ *     Scrolls at 1/4 the camera speed for parallax depth (far things
+ *     move slower). Because Plane B is filled edge-to-edge and the VDP
+ *     scroll wraps within the plane, it tiles forever with no redraw.
+ *   - One hardware sprite = the player, drawn in SCREEN space.
+ *
+ * Drive it: D-pad LEFT/RIGHT scrolls the camera (the player walks within
+ * the world). The camera clamps to the world edges.
+ *
+ * IMPORTANT (logical vs hardware plane size): the Genesis has ONE shared
+ * plane-size setting for BOTH planes. We use the default 64x32 cells
+ * (512x256 px). A "32-wide level" still lives inside a 64-wide PHYSICAL
+ * plane — you don't get an independent per-plane size. See the Genesis
+ * MENTAL_MODEL.md "Scrolling, parallax & the feel trap".
+ *
+ * To go WIDER than 512 px (a true Sonic-size level) you keep this exact
+ * loop and add ONE thing: stream the single offscreen column that's about
+ * to scroll into view each time the camera crosses an 8-px tile boundary
+ * (a circular buffer in the 64-cell plane) — NOT a whole-plane redraw.
+ * See MENTAL_MODEL.md "How Sonic-style large maps really work".
+ */
+
+#include <genesis.h>
+
+/* ── Tiles (4bpp, 8 rows x 4 bytes). Indices live at/above TILE_USER_INDEX
+ *    so they don't clobber SGDK's font + system tiles below it. ── */
+#define T_BLANK   (TILE_USER_INDEX + 0)
+#define T_GROUND  (TILE_USER_INDEX + 1)
+#define T_BLOCK   (TILE_USER_INDEX + 2)
+#define T_PLAYER  (TILE_USER_INDEX + 3)
+#define T_STAR    (TILE_USER_INDEX + 4)
+
+static const u32 tile_blank[8]  = { 0,0,0,0,0,0,0,0 };
+/* Solid ground: lit top edge, darker body. */
+static const u32 tile_ground[8] = {
+    0x11111111, 0x12222221, 0x12222221, 0x12222221,
+    0x12222221, 0x12222221, 0x12222221, 0x12222221,
+};
+/* A floating platform block. */
+static const u32 tile_block[8]  = {
+    0x33333333, 0x34444443, 0x34444443, 0x34444443,
+    0x34444443, 0x34444443, 0x34444443, 0x33333333,
+};
+/* Player: a chunky diamond so it reads on screen. */
+static const u32 tile_player[8] = {
+    0x00055000, 0x00555500, 0x05555550, 0x55555555,
+    0x55555555, 0x05555550, 0x00555500, 0x00055000,
+};
+/* A single off-center star pixel on a dark field (background twinkle). */
+static const u32 tile_star[8]   = {
+    0x00000000, 0x00060000, 0x00000000, 0x00000600,
+    0x00000000, 0x06000000, 0x00000000, 0x00000060,
+};
+
+#define PLANE_W_CELLS 64          /* default plane is 64x32 cells       */
+#define WORLD_W       512         /* = 64 cells * 8 px (one plane wide)  */
+#define SCREEN_W      320         /* H40                                  */
+#define GROUND_Y      192         /* px — top of the ground strip         */
+
+/* Static foreground platforms in WORLD PIXEL coords. Painted ONCE. */
+typedef struct { s16 x, y, wcells; } Block;
+static const Block blocks[] = {
+    {  48, 152, 5 }, { 160, 128, 4 }, { 256, 160, 6 },
+    { 352, 112, 4 }, { 432, 144, 5 },
+};
+#define N_BLOCKS (sizeof(blocks) / sizeof(blocks[0]))
+
+/* Player WORLD x exposed for headless motion-trace inspection:
+ *   symbols({op:'resolve', name:'g_player_x'}) → read it over frames while
+ *   holding RIGHT and compare against the camera scroll (see MENTAL_MODEL
+ *   "Why does horizontal movement feel choppy?"). `volatile` keeps it from
+ *   being optimised into a register so the read resolves. */
+volatile s16 g_player_x = 32;     /* world px */
+volatile s16 g_cam_x    = 0;      /* camera scroll (world px) */
+
+int main(bool hard) {
+    (void)hard;
+
+    /* Palettes (BGR, 3 bits/chan). PAL0 = sprite, PAL1 = planes. */
+    PAL_setColor(0 +  5, 0x008E);  /* player orange (Uridium-ish) */
+    PAL_setColor(16 + 1, 0x0A86);  /* ground top   (light)  */
+    PAL_setColor(16 + 2, 0x0530);  /* ground body  (dark)   */
+    PAL_setColor(16 + 3, 0x0CCC);  /* block edge   (white)  */
+    PAL_setColor(16 + 4, 0x0844);  /* block body   (steel)  */
+    PAL_setColor(16 + 6, 0x0EEE);  /* star         (white)  */
+
+    /* Upload all tiles once. */
+    VDP_loadTileData(tile_blank,  T_BLANK,  1, DMA);
+    VDP_loadTileData(tile_ground, T_GROUND, 1, DMA);
+    VDP_loadTileData(tile_block,  T_BLOCK,  1, DMA);
+    VDP_loadTileData(tile_player, T_PLAYER, 1, DMA);
+    VDP_loadTileData(tile_star,   T_STAR,   1, DMA);
+
+    /* ── PAINT PLANE B (starfield) ONCE — fills the whole 64x32 plane so
+     *    it tiles forever as the scroll wraps. NEVER touched again. ── */
+    VDP_fillTileMapRect(BG_B, TILE_ATTR_FULL(PAL1, 0, 0, 0, T_STAR),
+                        0, 0, PLANE_W_CELLS, 32);
+
+    /* ── PAINT PLANE A (foreground world) ONCE. ──
+     * Ground strip across the whole world width, then the platform blocks
+     * on top. After this, the loop does NOT write the tilemap again. */
+    VDP_fillTileMapRect(BG_A, TILE_ATTR_FULL(PAL1, 0, 0, 0, T_GROUND),
+                        0, GROUND_Y >> 3, PLANE_W_CELLS, (256 - GROUND_Y) >> 3);
+    for (u16 i = 0; i < N_BLOCKS; i++) {
+        const Block* b = &blocks[i];
+        VDP_fillTileMapRect(BG_A, TILE_ATTR_FULL(PAL1, 0, 0, 0, T_BLOCK),
+                            b->x >> 3, b->y >> 3, b->wcells, 1);
+    }
+
+    VDP_drawText("PARALLAX  D-PAD = SCROLL", 7, 1);
+
+    const s16 PLAYER_SPEED = 2;
+    s16 player_screen_x = SCREEN_W / 2 - 4;  /* player stays mid-screen */
+
+    while (TRUE) {
+        u16 pad = JOY_readJoypad(JOY_1);
+
+        /* Move the player through the WORLD. */
+        if (pad & BUTTON_LEFT)  g_player_x -= PLAYER_SPEED;
+        if (pad & BUTTON_RIGHT) g_player_x += PLAYER_SPEED;
+        if (g_player_x < 0)            g_player_x = 0;
+        if (g_player_x > WORLD_W - 8)  g_player_x = WORLD_W - 8;
+
+        /* Camera centers on the player, clamped to the world edges. */
+        s16 cam = g_player_x - (SCREEN_W / 2 - 4);
+        if (cam < 0)                    cam = 0;
+        if (cam > WORLD_W - SCREEN_W)   cam = WORLD_W - SCREEN_W;
+        g_cam_x = cam;
+
+        /* When the camera is hard against an edge, let the player walk to
+         * the screen edge instead of staying pinned to the centre. */
+        player_screen_x = g_player_x - cam;
+
+        /* ★ THE ENTIRE PER-FRAME RENDER COST: two scroll-register writes.
+         * Positive cam scrolls the plane LEFT, so we write the negative.
+         * Plane A: 1:1 with the world. Plane B: 1/4 speed = parallax. */
+        VDP_setHorizontalScroll(BG_A, -cam);
+        VDP_setHorizontalScroll(BG_B, -(cam >> 2));
+
+        /* Re-stage the one player sprite (screen space) + flush the SAT.
+         * SPRITE_SIZE(1,1) = 8x8. */
+        VDP_setSprite(0, player_screen_x, GROUND_Y - 8, SPRITE_SIZE(1, 1),
+                      TILE_ATTR_FULL(PAL0, 1, 0, 0, T_PLAYER));
+        VDP_updateSprites(1, DMA);
+
+        SYS_doVBlankProcess();
+    }
+    return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 14 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
   "type": "module",
   "main": "src/mcp/server.js",

package/src/host/LibretroHost.js

@@ -1545,6 +1545,60 @@ export class LibretroHost {
     }
   }
 
+  /**
+   * Per-frame VDP-DMA timeline. Steps `frames` frames ONE AT A TIME, and for
+   * each frame reports how many mem→VDP DMAs fired + how many VRAM/CRAM/VSRAM
+   * bytes they moved. The core's `romdev_dmawatch_set(1)` RESETS its counters
+   * (see the patch), so re-arming before each single-frame step gives a clean
+   * per-frame bucket with no core rebuild — the cheap derivation of "VDP/DMA
+   * work per frame" the feel-diagnostics workflow needs.
+   *
+   * `onFrame(i)` is called at the top of each frame (before the step) so the
+   * caller can drive scheduled input. Genesis-only.
+   *
+   * Returns { frames:[{frame, dmas, words, bytes, romBytes, ramBytes}], ... }.
+   * `romBytes`/`ramBytes` split the moved bytes by source bus (ROM asset upload
+   * vs the RAM→VRAM sprite/scroll refresh) so a per-frame asset-DMA spike — the
+   * "I redrew a tilemap in the loop" smell — stands out from the steady refresh.
+   */
+  watchDmaPerFrame(frames, onFrame) {
+    const mod = this._needMod();
+    this._needMedia();
+    if (!this.dmaWatchSupported()) throw new Error("VDP-DMA watch not supported by this core (Genesis only).");
+    const CAP = 1024;
+    const outPtr = mod._malloc(CAP * 4 * 4);
+    const out2Ptr = mod._malloc(8);
+    const isRam = (src) => (src >>> 0) >= 0xE00000;
+    const out = [];
+    let peakBytes = 0, peakFrame = -1, totalBytes = 0, totalDmas = 0;
+    try {
+      for (let i = 0; i < frames; i++) {
+        if (onFrame) onFrame(i);
+        mod._romdev_dmawatch_set(1);          // arm + RESET counters for this frame
+        this._runFramesExclusive(() => false, 1);
+        const n = mod._romdev_dmawatch_get(outPtr, CAP, out2Ptr);
+        const out2 = new Uint32Array(mod.HEAPU8.buffer, out2Ptr, 2);
+        const total = out2[0];                // total DMAs this frame (>= stored)
+        const u = new Uint32Array(mod.HEAPU8.buffer, outPtr, n * 4);
+        let words = 0, romBytes = 0, ramBytes = 0;
+        for (let k = 0; k < n; k++) {
+          const src = u[k * 4 + 1], len = u[k * 4 + 2];
+          words += len;
+          if (isRam(src)) ramBytes += len * 2; else romBytes += len * 2;
+        }
+        const bytes = words * 2;
+        out.push({ frame: i, dmas: total, words, bytes, romBytes, ramBytes,
+          ...(total > n ? { coreBufferTruncated: true } : {}) });
+        totalBytes += bytes; totalDmas += total;
+        if (bytes > peakBytes) { peakBytes = bytes; peakFrame = i; }
+      }
+      mod._romdev_dmawatch_set(0);            // disarm
+      return { frames: out, totalBytes, totalDmas, peakBytes, peakFrame };
+    } finally {
+      mod._free(outPtr); mod._free(out2Ptr);
+    }
+  }
+
   pause() {
     this.status.paused = true;
   }
@@ -1630,7 +1684,7 @@ export class LibretroHost {
       sms:   { video_ram: "sms_vram (or sms_cram for palette, sms_vdp_regs for VDP regs)" },
       gg:    { video_ram: "gg_vram (or gg_cram for the 64-byte 12-bit palette, sms_vdp_regs for VDP regs)" },
       snes:  { video_ram: "snes_oam (sprite OAM), snes_cgram (palette), snes_aram (SPC700), or snes_fillram (PPU/DMA reg shadow). The libretro generic 'video_ram' id isn't wired in snes9x." },
-      genesis: { video_ram: "genesis_cram / genesis_vsram / genesis_vdp_regs — the generic 'video_ram' id isn't wired in gpgx for Genesis. VRAM itself isn't exposed; use inspectPatternTiles / inspectBackgroundMap / getRenderingContext instead." },
+      genesis: { video_ram: "Genesis VRAM IS exposed via 'video_ram' (gpgx) once a ROM is loaded and a frame has run — if it reads empty, step a frame first (the SAT/sprites need the game to have written VRAM). Palette/scroll/VDP regs are genesis_cram / genesis_vsram / genesis_vdp_regs. For decoded views use inspectSprites / inspectPatternTiles / inspectBackgroundMap / getRenderingContext." },
       c64:   { video_ram: "c64_color_ram (1 KB) / c64_vic_regs / c64_sid_regs / c64_cia1_regs / c64_cia2_regs. The C64 has no separate VRAM — the VIC-II reads from main system_ram." },
     };
     const hint = suggestions[plat] && suggestions[plat][region];

package/src/host/framebuffer.js

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

package/src/mcp/tools/audio.js

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

package/src/mcp/tools/frame.js

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

package/src/mcp/tools/index.js

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

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

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

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

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