romdevtools 0.41.0 → 0.42.0

package/src/mcp/tools/disasm.js

@@ -7,6 +7,8 @@ import { parseSymbols, buildSymbolMap } from "../../toolchains/common/symbols.js
 import { registersForPlatform } from "../../platforms/common/registers.js";
 import { findReferencesCore } from "./find-references.js";
 import { analyzeCfg, analyzeXrefs, analyzeFunctions, analyzeDecompile } from "../../analysis/analyze.js";
+import { recompileNesToSnes, sliceFirstRoutine } from "../../analysis/recompile-65816.js";
+import { decodePointerTable, reverseLookup } from "../../analysis/pointer-table.js";
 
 /** cfg/xrefs/functions all operate on a ROM file. Reuse the `path` arg. */
 function requireRomPath(args) {
@@ -14,6 +16,42 @@ function requireRomPath(args) {
   return args.path;
 }
 
+/**
+ * CPU address → file offset for a platform's ROM image, dispatching to the
+ * per-platform mapper. Returns the offset or null (out of range / unmapped /
+ * unsupported platform). The single home for "where in the file is CPU address
+ * X" — used by file-offset annotation AND target=pointerTable.
+ * @param {string} platform
+ * @param {Uint8Array} data   full ROM image
+ * @param {number} cpuAddr
+ * @param {{bank?:number, snesMapper?:number}} [opts]
+ */
+function cpuAddrToFileOffset(platform, data, cpuAddr, opts = {}) {
+  try {
+    switch (platform) {
+      case "snes": return mapSnesAddress(data, cpuAddr, 1, opts.snesMapper).fileOffset;
+      case "sms": case "gg": return mapSmsAddress(data, cpuAddr, 1).fileOffset;
+      case "gb": case "gbc": return mapGbAddress(data, cpuAddr, 1, opts.bank).fileOffset;
+      case "atari2600": return mapAtari2600Address(data, cpuAddr, 1, opts.bank ?? 0).fileOffset;
+      case "atari7800": return mapAtari7800Address(data, cpuAddr, 1, opts.bank ?? 0).fileOffset;
+      case "c64": return mapC64Address(data, cpuAddr, 1, opts.bank ?? 0).fileOffset;
+      case "genesis": case "megadrive": case "md": return mapGenesisAddress(data, cpuAddr, 1).fileOffset;
+      case "nes": return mapNesAddress(data, cpuAddr, 1, opts.bank).fileOffset;
+      default: return null; // msx/pce/lynx/gba: no static address mapper here
+    }
+  } catch {
+    return null;
+  }
+}
+
+/** Platforms target=pointerTable can map a CPU address for (has a mapper above).
+ *  Their default jump-table word order: 6502/Z80/65816 are little-endian; the
+ *  m68k (Genesis) stores words BIG-endian, so a Genesis `dc.w` table is BE. */
+const POINTER_TABLE_PLATFORMS = new Set([
+  "nes", "snes", "sms", "gg", "gb", "gbc", "atari2600", "atari7800", "c64", "genesis", "megadrive", "md",
+]);
+const BIG_ENDIAN_TABLE_PLATFORMS = new Set(["genesis", "megadrive", "md"]);
+
 // ── Per-platform CPU-address → file-offset mappers ────────────────
 // Each returns { bytes, fileOffset, cpu, notes } given the full ROM
 // bytes and a desired CPU address. Throws with a clear message if the
@@ -905,25 +943,12 @@ async function disassembleRomCore(args) {
         exitCode = r.exitCode;
       }
 
-      // File-offset annotation: per-line cpu→file translator.
+      // File-offset annotation: per-line cpu→file translator (shared mapper).
+      // `args.bank` maps $8000-$BFFF to the chosen switchable bank; mapNesAddress
+      // ignores it for $C000+ (fixed top bank), so each line points at the right
+      // PRG offset.
       if (annotateFileOffsetsFlag) {
-        const cpuToFile = (cpuAddr) => {
-          try {
-            if (resolved === "snes") return mapSnesAddress(data, cpuAddr, 1, mapper).fileOffset;
-            if (resolved === "sms" || resolved === "gg") return mapSmsAddress(data, cpuAddr, 1).fileOffset;
-            if (resolved === "gb" || resolved === "gbc") return mapGbAddress(data, cpuAddr, 1, args.bank).fileOffset;
-            if (resolved === "atari2600") return mapAtari2600Address(data, cpuAddr, 1, args.bank ?? 0).fileOffset;
-            if (resolved === "atari7800") return mapAtari7800Address(data, cpuAddr, 1, args.bank ?? 0).fileOffset;
-            if (resolved === "c64") return mapC64Address(data, cpuAddr, 1, args.bank ?? 0).fileOffset;
-            if (resolved === "genesis") return mapGenesisAddress(data, cpuAddr, 1).fileOffset;
-            // `args.bank` maps $8000-$BFFF to the chosen switchable bank;
-            // mapNesAddress ignores it for $C000+ (fixed top bank), so each
-            // annotated line points at the correct PRG offset.
-            return mapNesAddress(data, cpuAddr, 1, args.bank).fileOffset;
-          } catch {
-            return null;
-          }
-        };
+        const cpuToFile = (cpuAddr) => cpuAddrToFileOffset(resolved, data, cpuAddr, { bank: args.bank, snesMapper: mapper });
         // Secondary translator for NES — also report the header-stripped
         // PRG offset, since patchFile against `prg.bin` (from extractCart)
         // needs the header-less frame.
@@ -1144,6 +1169,256 @@ function renderBuildMd({ platform, romPath, regions, blobs, build, verifiable, n
   return lines.join("\n") + "\n";
 }
 
+/**
+ * target:'recompile' — NES (6502) → SNES (65816) static recompile (emit backend
+ * phase 1). Reads the NES ROM's PRG, disassembles the reset routine with da65,
+ * translates it to asar-ready 65816 (the 6502 logic runs in EMULATION mode), and
+ * returns the main.asm + seam include + a residue report. Optionally writes the
+ * sources to `outputDir`. Build the result with build({platform:'snes'}) and
+ * verify it with frame({op:'sideBySide'}) against the original.
+ *
+ * v1 scope: NROM, documented 6502, the reset/boot routine. The PPU/APU seam is
+ * stubbed (no real NES-PPU-on-SNES runtime yet) so the port boots + runs the
+ * logic but renders blank — the runtime shim is a separate task.
+ */
+/**
+ * target=pointerTable — STATIC decode of a jump/pointer table into an
+ * index→handler map (+ optional reverse lookup). The static complement to the
+ * LIVE resolveJumptable. Handles contiguous LE/BE tables, SPLIT lo/hi arrays at
+ * two bases, and the 6502 RTS-trick (+1). Works on every platform with an address
+ * mapper (nes/snes/sms/gg/gb/gbc/2600/7800/c64/genesis); banked carts honor `bank`.
+ * The default endian follows the CPU (Genesis/m68k → BE; everything else → LE),
+ * overridable via `endian`.
+ */
+async function pointerTableCore(args) {
+  const { platform, loBase, hiBase, count, convention = "direct", reverseHandler, bank } = args;
+  if (loBase == null) throw new Error("disasm({target:'pointerTable'}): loBase (the table / low-byte base) is required.");
+  if (count == null) throw new Error("disasm({target:'pointerTable'}): count (number of entries) is required.");
+  const romPath = requireRomPath(args);
+  const data = new Uint8Array(await readFile(romPath));
+  const resolved = platform ?? (/\.nes$/i.test(romPath) ? "nes" : /\.(sfc|smc)$/i.test(romPath) ? "snes" : /\.gb$/i.test(romPath) ? "gb" : /\.sms$/i.test(romPath) ? "sms" : /\.(gen|md|bin)$/i.test(romPath) ? "genesis" : null);
+  if (!resolved || !POINTER_TABLE_PLATFORMS.has(resolved)) {
+    throw new Error(`disasm({target:'pointerTable'}): platform '${resolved ?? "unknown"}' has no static address mapper. Supported: ${[...POINTER_TABLE_PLATFORMS].join(", ")}. (msx/pce/lynx/gba: locate the table live with breakpoint({on:'jumptable'}).)`);
+  }
+  // CPU address → file offset via the platform mapper (banked-cart aware).
+  const toOffset = (cpuAddr) => cpuAddrToFileOffset(resolved, data, cpuAddr, { bank });
+  // Default endian follows the CPU's word order unless the caller overrides it.
+  const endian = args.endian ?? (BIG_ENDIAN_TABLE_PLATFORMS.has(resolved) ? "BE" : "LE");
+  const { entries, form } = decodePointerTable({ data, toOffset, count, loBase, hiBase, convention, endian });
+  const fmt = (n) => "$" + (n & 0xffff).toString(16).toUpperCase().padStart(4, "0");
+  const out = {
+    platform: resolved,
+    form,
+    count,
+    entries: entries.map((e) => ({ index: e.index, handler: fmt(e.handler), storedWord: fmt(e.storedWord) })),
+  };
+  if (reverseHandler != null) {
+    const indices = reverseLookup(entries, reverseHandler);
+    out.reverse = {
+      handler: fmt(reverseHandler),
+      indices,
+      note: indices.length
+        ? `dispatch index/indices ${indices.join(", ")} land on ${fmt(reverseHandler)}.`
+        : `no table index reaches ${fmt(reverseHandler)} (check loBase/hiBase/count/convention, or it's reached another way).`,
+    };
+  }
+  out.note = "index→handler decoded statically. For a SPLIT table pass loBase (low array) + hiBase (high array); for a contiguous `dw` table pass only loBase. convention:'rts+1' adds 1 (6502 RTS trick). reverseHandler answers 'which state triggers this routine?'. (For a COMPUTED dispatcher whose table you can't locate statically, use the live breakpoint({on:'jumptable'}).)";
+  return out;
+}
+
+async function recompileCore(args) {
+  const { platform, targetPlatform } = args;
+  if (platform && platform !== "nes") {
+    throw new Error(`disasm({target:'recompile'}): only NES source is supported in phase 1 (got '${platform}').`);
+  }
+  if (targetPlatform && targetPlatform !== "snes") {
+    throw new Error(`disasm({target:'recompile'}): only SNES target is supported in phase 1 (got '${targetPlatform}').`);
+  }
+  const romPath = requireRomPath(args);
+  const rom = new Uint8Array(await readFile(romPath));
+  // iNES validation: "NES\x1a" magic, then a 16-byte header, then PRG. v1 handles
+  // NROM (mapper 0, 16KB or 32KB PRG). Give size vs mapper their OWN errors so the
+  // message is never misleading (a 24KB mapper-0 ROM isn't a "mapped cart").
+  const hasInes = rom.length >= 16 && rom[0] === 0x4e && rom[1] === 0x45 && rom[2] === 0x53 && rom[3] === 0x1a;
+  if (!hasInes) {
+    throw new Error("disasm({target:'recompile'}): not an iNES file (missing 'NES\\x1a' magic). Phase 1 takes a raw .nes ROM.");
+  }
+  const mapper = (rom[6] >> 4) | (rom[7] & 0xf0);
+  if (mapper !== 0) {
+    throw new Error(`disasm({target:'recompile'}): mapper ${mapper} is not supported in phase 1 — only NROM (mapper 0). Bank-switched carts need the per-bank recompile path (not yet built).`);
+  }
+  const prgSize = rom.length - 16;
+  if (prgSize !== 0x4000 && prgSize !== 0x8000) {
+    throw new Error(`disasm({target:'recompile'}): expected an NROM PRG of 16KB or 32KB; got ${prgSize} bytes. Phase 1 handles only those two sizes.`);
+  }
+  const prg = rom.subarray(16, 16 + prgSize);
+  const prgBase = prgSize === 0x4000 ? 0xC000 : 0x8000; // 16KB mirrors into $C000
+
+  // Disassemble from the REAL reset vector, not blindly from the PRG base. The
+  // reset routine lives wherever $FFFC/$FFFD point — often deep in PRG, with data
+  // or padding ($00 = brk) at the base. Starting at the base translated that
+  // padding as 6 garbage `brk`s; starting at the reset vector yields the actual
+  // boot routine (robotfindskitten: 6-instr-garbage → 70-instr clean, 0 residue).
+  const resetVec = prg[prg.length - 4] | (prg[prg.length - 3] << 8);
+  const resetOff = resetVec - prgBase;
+  if (resetOff < 0 || resetOff >= prg.length) {
+    throw new Error(`disasm({target:'recompile'}): reset vector $${resetVec.toString(16)} is outside the PRG window ($${prgBase.toString(16)}-$FFFF). Corrupt ROM or unexpected layout.`);
+  }
+  // Slice the PRG at the reset vector so da65 starts decoding real code there.
+  const codeBytes = prg.subarray(resetOff);
+  const { runDa65 } = await import("../../toolchains/cc65/da65.js");
+  const da = await runDa65({ bytes: codeBytes, cpu: "6502", startAddress: resetVec, options: ["--comments", "4"] });
+  const da65Full = da.asm ?? "";
+  // Slice the first routine (the reset path) — a flat disasm renders data tables
+  // after it as bogus code. Phase 1 = the boot routine.
+  const da65Asm = sliceFirstRoutine(da65Full);
+
+  // Optional NES-PPU-on-SNES shim: boot the original ROM, read its PPU state,
+  // convert tiles/nametable/palette to SNES formats, and emit a shim that draws
+  // that static boot picture.
+  //
+  // STATUS (WORKING, default OFF): the JS-side conversion (NES 2bpp→SNES 4bpp
+  // tiles, NES palette→BGR555 CGRAM, nametable→tilemap) is correct and
+  // unit-tested, and the emitted 65816 UPLOAD routine now DMAs all three to SNES
+  // VRAM/CGRAM and turns the screen on — verified end-to-end on snes9x
+  // (test/recompile-shim-render.test.js). It is still OFF by default because
+  // phase 1 only draws the STATIC first screen: after the shim, the recompiled
+  // NES logic runs against a STUBBED PPU seam, so animation/scroll/sprites are
+  // not maintained (the next layer). Opt in with withShim:true for the static
+  // boot picture. (frame compareRender/findDiverge are the oracles to debug it.)
+  // The phase-2 runtime (withRuntime) implies the shim (it needs the BG + tiles
+  // the shim uploads); enabling it turns the static port into a LIVE one (sprites
+  // animate each vblank, the game's NMI runs). withShim alone is the static path.
+  const wantRuntime = args.withRuntime === true;
+  const wantShim = args.withShim === true || wantRuntime;
+  let shimAsm = null;
+  let shimInfo = null;
+  if (wantShim) {
+    try {
+      shimInfo = await buildNesPpuShim(rom);
+      shimAsm = shimInfo.asm;
+    } catch (e) {
+      shimInfo = { error: e.message };
+    }
+  }
+
+  // Phase-2 runtime: disassemble the NES NMI handler ($FFFA) so the runtime's
+  // vblank handler can call the game's own per-frame logic, and emit the runtime.
+  let runtimeAsm = null;
+  let nmiDa65Asm = null;
+  let nmiInfo = null;
+  if (wantRuntime) {
+    try {
+      const nmiVec = prg[prg.length - 6] | (prg[prg.length - 5] << 8);
+      const nmiOff = nmiVec - prgBase;
+      let nesNmiLabel = null;
+      if (nmiOff >= 0 && nmiOff < prg.length && nmiVec !== resetVec) {
+        const nmiDa = await runDa65({ bytes: prg.subarray(nmiOff), cpu: "6502", startAddress: nmiVec, options: ["--comments", "4"] });
+        nmiDa65Asm = sliceFirstRoutine(nmiDa.asm ?? "");
+        // The translated NMI's entry label (derive it the same way the recompiler
+        // will) so the runtime calls the right routine.
+        const { entry: ne } = recompileNesToSnes(nmiDa65Asm, { stubUndefined: false });
+        nesNmiLabel = ne === "RECOMPILE_ENTRY" ? "RECOMPILE_NMI_ENTRY" : ne;
+      }
+      const { emitPpuRuntime } = await import("../../analysis/nes-ppu-runtime.js");
+      runtimeAsm = emitPpuRuntime({ nesNmiLabel });
+      nmiInfo = { nmiVector: "$" + nmiVec.toString(16).toUpperCase().padStart(4, "0"), gameNmi: nesNmiLabel };
+    } catch (e) {
+      nmiInfo = { error: e.message };
+    }
+  }
+
+  const { mainAsm, seamAsm, residue, entry, nmiEntry, instrCount, seamCount, stubbed } =
+    recompileNesToSnes(da65Asm, {
+      withShim: !!shimAsm,
+      withRuntime: !!runtimeAsm,
+      nmiDa65Asm,
+    });
+
+  const runtimeOn = !!runtimeAsm;
+  let written = null;
+  if (args.outputDir) {
+    await mkdir(args.outputDir, { recursive: true });
+    const mainPath = nodePath.join(args.outputDir, "main.asm");
+    await writeFile(mainPath, mainAsm);
+    written = { mainAsm: mainPath };
+    // The phase-2 runtime supplies its own seam; the phase-1 path uses nes_seam.
+    if (runtimeOn) {
+      const rtPath = nodePath.join(args.outputDir, "nes_ppu_runtime.asm");
+      await writeFile(rtPath, runtimeAsm);
+      written.runtimeAsm = rtPath;
+    } else {
+      const seamPath = nodePath.join(args.outputDir, "nes_seam.asm");
+      await writeFile(seamPath, seamAsm);
+      written.seamAsm = seamPath;
+    }
+    if (shimAsm) {
+      const shimPath = nodePath.join(args.outputDir, "nes_ppu_shim.asm");
+      await writeFile(shimPath, shimAsm);
+      written.shimAsm = shimPath;
+    }
+  }
+
+  const shimDrawn = !!shimAsm;
+  return jsonContent({
+    ok: true,
+    source: "nes", target: "snes",
+    resetVector: "$" + resetVec.toString(16).toUpperCase().padStart(4, "0"),
+    entry,
+    ...(runtimeOn ? { nmiEntry, nmi: nmiInfo } : {}),
+    instrCount, seamCount,
+    stubbedCallees: stubbed,
+    residue,
+    shim: shimDrawn
+      ? { applied: true, phase: runtimeOn ? "live-background" : "static-boot-picture", tiles: shimInfo.tileCount, note: "Emitted the NES-PPU-on-SNES shim (converted tiles/nametable/palette → VRAM/CGRAM, BG1 on). It draws the original ROM's boot screen background." }
+      : { applied: false, reason: shimInfo?.error || "withShim not set (default off)", note: "No PPU shim — the port runs the logic but renders blank. Pass withShim:true (static) or withRuntime:true (live) to draw the original ROM's picture on SNES." },
+    runtime: runtimeOn
+      ? { applied: true, phase: "live-sprites", gameNmi: nmiInfo?.gameNmi || null, note: "PHASE 2: the per-frame runtime is wired — each vblank it flushes the game's shadow OAM to SNES sprites and runs the game's NMI handler, so sprites ANIMATE (not a static screenshot). Background is from the shim; live nametable streaming is phase 3. Build all emitted files together with build({platform:'snes'})." }
+      : { applied: false, note: "Static port (no per-frame runtime). Pass withRuntime:true to animate sprites + run the game's NMI each vblank." },
+    note:
+      `Recompiled the NES reset${runtimeOn ? " + NMI" : ""} routine(s) to 65816 (asar). ${instrCount} instrs, ${seamCount} PPU/APU seam calls, ` +
+      `${stubbed.length} callee(s) stubbed (isolation), ${residue.length} residue line(s). ` +
+      (runtimeOn
+        ? "PHASE 2: the 6502 logic runs in emulation mode; the runtime flushes sprites + runs the game NMI every vblank, and the shim draws the BG — so the port is LIVE (sprites move). "
+        : shimDrawn
+          ? `The 6502 logic runs in 65816 EMULATION mode; the shim draws the converted static boot picture (${shimInfo.tileCount} tiles). `
+          : "The 6502 logic runs in 65816 EMULATION mode; the hardware seam is STUBBED so the port renders blank. ") +
+      (written
+        ? `Wrote ${Object.values(written).join(" + ")}. Build all of them together with build({platform:'snes'}); then loadMedia + frame({op:'sideBySide'}) vs the NES original.`
+        : `Pass outputDir to write the .asm files to disk for build({platform:'snes'}).`),
+    ...(written ? { written } : { mainAsm, ...(runtimeOn ? { runtimeAsm } : { seamAsm }), ...(shimAsm ? { shimAsm } : {}) }),
+  });
+}
+
+/**
+ * Boot a NES ROM in a throwaway host, read its PPU state after boot, and build
+ * the NES-PPU-on-SNES shim (converted tiles/nametable/palette + the DMA
+ * routine). Returns { asm, tileCount }. Throws if the core/regions are
+ * unavailable.
+ * @param {Uint8Array} romBytes  full iNES file
+ */
+async function buildNesPpuShim(romBytes) {
+  const { resolveCore } = await import("../../cores/registry.js");
+  const { LibretroHost } = await import("../../host/index.js");
+  const { buildSnesAssets, emitPpuShim } = await import("../../analysis/nes-ppu-shim.js");
+  const core = resolveCore("nes");
+  if (!core) throw new Error("NES core unavailable for shim boot");
+  const host = new LibretroHost();
+  try {
+    await host.loadCore(core.jsPath, core.wasmPath);
+    await host.loadMedia({ platform: "nes", bytes: romBytes, virtualName: "/rom.nes" });
+    // Boot long enough for the game to finish its initial PPU upload.
+    host.stepFrames(120);
+    const chr = host.readMemory("nes_chr", 0, Math.min(0x2000, host.regionSize("nes_chr") || 0x2000));
+    const nt = host.readMemory("nes_nametables", 0, 0x400); // first nametable: 960 tiles + 64 attr
+    const pal = host.readMemory("nes_palette", 0, 32);
+    const assets = buildSnesAssets({ chr, nametable: nt, palette: pal });
+    return { asm: emitPpuShim(assets), tileCount: assets.tileCount };
+  } finally {
+    try { host.unloadMedia(); } catch { /* best-effort */ }
+  }
+}
+
 export function registerDisasmTools(server, z) {
   server.tool(
     "disasm",
@@ -1190,7 +1465,7 @@ export function registerDisasmTools(server, z) {
     "LLM folds it. `address` for all four comes from target:'functions' (a CPU/virtual address; the file-offset " +
     "mapping is handled for you).",
     {
-      target: z.enum(["bytes", "rom", "project", "references", "cfg", "xrefs", "functions", "decompile", "resolveJumptable"]).describe("bytes = raw chunk; rom = mapper-aware ROM; project = full rebuildable disasm; references = flat da65 operand-refs to an address; functions/cfg/xrefs = Rizin RE engine (function list / control-flow graph / deep graph xrefs); decompile = Ghidra C pseudocode; resolveJumptable = recover a computed-jump dispatcher's targets (LIVE — redirects to breakpoint({on:'jumptable'}), which runs the emulator and records the real switch arms a static decompiler can't follow). See the tool description for the RE loop + the decompile altitude rule + per-CPU quality (all 14 platforms)."),
+      target: z.enum(["bytes", "rom", "project", "references", "cfg", "xrefs", "functions", "decompile", "resolveJumptable", "pointerTable", "recompile"]).describe("bytes = raw chunk; rom = mapper-aware ROM; project = full rebuildable disasm; references = flat da65 operand-refs to an address; functions/cfg/xrefs = Rizin RE engine (function list / control-flow graph / deep graph xrefs); decompile = Ghidra C pseudocode; resolveJumptable = recover a computed-jump dispatcher's targets (LIVE — redirects to breakpoint({on:'jumptable'}), which runs the emulator and records the real switch arms a static decompiler can't follow); recompile = EMIT backend — statically recompile a NES ROM's reset routine to SNES 65816 asar source that builds + boots (phase 1: NROM, 6502→65816 emulation mode, PPU/APU seam STUBBED). See the tool description for the RE loop + the decompile altitude rule + per-CPU quality (all 14 platforms)."),
       // shared
       path: z.string().optional().describe("target=bytes: raw binary path. target=rom/project/references: ROM file path."),
       base64: z.string().optional().describe("target=bytes: base64 of the bytes (OR `path`)."),
@@ -1206,7 +1481,7 @@ export function registerDisasmTools(server, z) {
       symbolsText: z.string().optional().describe("target=bytes: inline symbol-file text."),
       symbolsFormat: z.enum(["wla", "cc65-lbl"]).optional().describe("target=bytes: explicit symbol-file format override."),
       // rom
-      bank: z.number().int().min(0).max(255).optional().describe("target=rom: switchable ROM bank to map into the windowed slot (NES mapper>0 $8000 / GB $4000; also 2600/7800/c64)."),
+      bank: z.number().int().min(0).max(255).optional().describe("target=rom / pointerTable: switchable ROM bank to map into the windowed slot (NES mapper>0 $8000 / GB $4000; also 2600/7800/c64)."),
       thumb: z.boolean().default(false).describe("target=rom: GBA — disassemble as THUMB (16-bit) instead of ARM."),
       endAddress: z.number().int().min(0).max(0xffffff).optional().describe("target=rom: CPU end address (inclusive); alternative to length."),
       untilReturn: z.boolean().default(false).describe("target=rom: stop at the first return/unconditional-jump (rts/rti/rtl/jmp, or ret/reti/jp per CPU) — grab one routine."),
@@ -1219,10 +1494,21 @@ export function registerDisasmTools(server, z) {
       annotateRegisters: z.boolean().default(true).describe("target=rom: append `; PPUMASK` etc. to operands hitting a known hardware register."),
       annotateFileOffsets: z.boolean().default(true).describe("target=rom: append `; @0xNNNN` file offset to every line (for romPatch)."),
       // project
-      outputDir: z.string().optional().describe("target=project: directory to write the project into (one .asm per region)."),
+      outputDir: z.string().optional().describe("target=project: directory to write the project into (one .asm per region). target=recompile: directory to write main.asm + nes_seam.asm for build({platform:'snes'})."),
+      targetPlatform: z.string().optional().describe("target=recompile: the platform to emit (phase 1: only 'snes'). The source platform is `platform` (phase 1: only 'nes')."),
+      withShim: z.boolean().default(false).describe("target=recompile: phase-1 STATIC render (default off). Emit the NES-PPU-on-SNES shim — boots the original ROM, converts its tiles/nametable/palette to SNES VRAM/CGRAM data + a 65816 upload routine that draws the original's STATIC boot screen on SNES (verified on snes9x). Draws the first screen only; sprites don't animate. For a LIVE port use withRuntime instead."),
+      withRuntime: z.boolean().default(false).describe("target=recompile: phase-2 LIVE render (default off). Implies withShim (BG) and adds the per-frame runtime: each vblank it flushes the game's shadow OAM to SNES sprites and runs the game's own NMI handler, so SPRITES ANIMATE and the game's per-frame logic runs — the port plays, not just boots to a screenshot. Background is static from the shim; live nametable/scroll streaming is phase 3. Verified on snes9x."),
       // references / cfg / xrefs
       address: z.number().int().min(0).max(0xFFFFFFFF).optional().describe("target=references: CPU address to find references TO. target=cfg: address inside the function to graph. target=xrefs: address to find cross-references TO. target=decompile: address of the function to decompile (use an address from target='functions')."),
       maxRefsReturned: z.number().int().min(1).max(2048).default(256).describe("target=references: cap the references returned."),
+      includeTableHits: z.boolean().default(false).describe("target=references: also scan the raw ROM for the address as a 16-bit POINTER (LE/BE, + the 6502 RTS-trick addr-1) — finds inline jump-table / trampoline call sites that no jsr/jmp/branch names. Auto-on when no direct refs are found; set true to get tableHits alongside direct refs too."),
+      // target=pointerTable
+      loBase: z.number().int().min(0).max(0xFFFFFF).optional().describe("target=pointerTable: CPU address of the table (contiguous form) OR the LOW-byte array (split form). Required."),
+      hiBase: z.number().int().min(0).max(0xFFFFFF).optional().describe("target=pointerTable: CPU address of the HIGH-byte array (SPLIT lo/hi form). Omit for a contiguous `dw` table (hi byte follows each lo byte)."),
+      count: z.number().int().min(1).max(4096).optional().describe("target=pointerTable: number of entries to decode."),
+      convention: z.enum(["direct", "rts+1"]).default("direct").describe("target=pointerTable: 'direct' = the stored word IS the handler; 'rts+1' = the 6502 RTS-trick (table holds handler-1; +1 is applied)."),
+      endian: z.enum(["LE", "BE"]).optional().describe("target=pointerTable: byte order of the CONTIGUOUS form (split lo/hi ignores this). Default follows the CPU — Genesis/m68k is BE, everything else LE; override only if a table is stored against type."),
+      reverseHandler: z.number().int().min(0).max(0xFFFF).optional().describe("target=pointerTable: also report which dispatch INDEX/indices land on this handler address (reverse lookup — 'what state triggers this routine?')."),
     },
     safeTool(async (args) => {
       switch (args.target) {
@@ -1234,6 +1520,8 @@ export function registerDisasmTools(server, z) {
         case "xrefs":      return jsonContent(await analyzeXrefs(requireRomPath(args), args.address, args.platform));
         case "functions":  return jsonContent(await analyzeFunctions(requireRomPath(args), args.platform));
         case "decompile":  return jsonContent(await analyzeDecompile(requireRomPath(args), args.address, args.platform));
+        case "recompile":  return await recompileCore(args);
+        case "pointerTable": return jsonContent(await pointerTableCore(args));
         case "resolveJumptable":
           // A4: jumptable recovery is fundamentally a LIVE operation (it needs a
           // running emulator to observe the computed targets) — disasm is static

package/src/mcp/tools/find-references.js

@@ -213,7 +213,71 @@ function nesVectorRefs(data, targetAddr) {
   return refs;
 }
 
-export async function findReferencesCore({ path, platform, address, mapper, maxRefsReturned = 256 }) {
+/**
+ * Scan the raw ROM bytes for the target address encoded as a 16-bit POINTER —
+ * the inline-jump-table / trampoline case that a control-flow operand scan can't
+ * see. A dispatcher reads a word table and jumps to (or rts-tricks into) the
+ * entry, so the handler is reached with NO jsr/jmp/branch ever naming it; da65
+ * also mis-decodes the table bytes as instructions, hiding them from `references`.
+ * We surface every byte position whose LE or BE 16-bit word equals the target —
+ * and ALSO target-1, the 6502 "RTS trick" (push addr-1, rts → jumps to addr).
+ *
+ * @param {Uint8Array} data       full ROM image (incl. any header)
+ * @param {number} targetAddr     CPU address of the handler
+ * @param {number} headerSkip     bytes of file header before the code image
+ * @param {boolean} [rtsTrick=true]  also look for target-1 (the 6502 RTS trick).
+ *   Only meaningful on 6502-family ROMs; off elsewhere to avoid spurious hits.
+ * @returns {Array<{fileOffset:string, word:string, endian:"LE"|"BE", convention:"direct"|"rts+1"}>}
+ */
+function scanPointerTableHits(data, targetAddr, headerSkip = 0, rtsTrick = true) {
+  const hits = [];
+  const t16 = targetAddr & 0xffff;
+  const want = [{ value: t16, convention: "direct" }];
+  if (rtsTrick) want.push({ value: (t16 - 1) & 0xffff, convention: "rts+1" }); // 6502 RTS-trick: table holds addr-1
+  for (let i = headerSkip; i + 1 < data.length; i++) {
+    const le = data[i] | (data[i + 1] << 8);
+    const be = (data[i] << 8) | data[i + 1];
+    for (const w of want) {
+      if (le === w.value) {
+        hits.push({ fileOffset: "0x" + i.toString(16).toUpperCase(), word: "$" + w.value.toString(16).toUpperCase().padStart(4, "0"), endian: "LE", convention: w.convention });
+      } else if (be === w.value) {
+        hits.push({ fileOffset: "0x" + i.toString(16).toUpperCase(), word: "$" + w.value.toString(16).toUpperCase().padStart(4, "0"), endian: "BE", convention: w.convention });
+      }
+    }
+  }
+  return hits;
+}
+
+/**
+ * Bytes of file header before the code image, per platform — so the pointer-table
+ * scan reports a fileOffset into the actual code, and (more importantly) doesn't
+ * skip real data. Most platforms are headerless; the exceptions: NES (16-byte
+ * iNES), SNES (512-byte copier header iff size%1024==512), Atari 7800 (.a78 has a
+ * 128-byte header when the "ATARI7800" magic is present), Lynx (64-byte "LYNX").
+ * @param {string} platform
+ * @param {Uint8Array} data
+ */
+function romHeaderSkip(platform, data) {
+  switch (platform) {
+    case "nes":
+      return (data.length >= 4 && data[0] === 0x4e && data[1] === 0x45 && data[2] === 0x53 && data[3] === 0x1a) ? 16 : 0;
+    case "snes":
+      return (data.length % 1024) === 512 ? 512 : 0;
+    case "atari7800": {
+      // .a78 v2/v3 header is 128 bytes, magic "ATARI7800" at offset 1.
+      const magic = "ATARI7800";
+      let ok = data.length > 128;
+      for (let i = 0; ok && i < magic.length; i++) if (data[1 + i] !== magic.charCodeAt(i)) ok = false;
+      return ok ? 128 : 0;
+    }
+    case "lynx":
+      return (data.length >= 4 && data[0] === 0x4c && data[1] === 0x59 && data[2] === 0x4e && data[3] === 0x58) ? 64 : 0; // "LYNX"
+    default:
+      return 0; // gb/gbc/sms/gg/genesis/c64/2600/pce/msx: headerless code image
+  }
+}
+
+export async function findReferencesCore({ path, platform, address, mapper: _mapper, includeTableHits = false, maxRefsReturned = 256 }) {
   const data = new Uint8Array(await readFile(path));
   const resolved = platform ?? (
     /\.nes$/i.test(path) ? "nes" :
@@ -514,6 +578,21 @@ export async function findReferencesCore({ path, platform, address, mapper, maxR
     refs.push(...atariVectorRefs(data, address));
   }
 
+  // Pointer-table / trampoline scan. The operand scan above only finds DIRECT
+  // control-flow (jsr/jmp/branch naming the address). When a handler is reached
+  // ONLY through an inline word table (computed jump / RTS-trick dispatcher), no
+  // instruction names it — so when the direct scan comes up empty (or the caller
+  // asks), scan the raw bytes for the address as a 16-bit pointer (LE/BE, direct
+  // and the RTS-trick addr-1 form). This is the case the v0.41.0 feedback hit
+  // where the only "ref" was an inline `B5 8E` table entry da65 mis-decoded.
+  const headerSkip = romHeaderSkip(resolved, data);
+  // The RTS-trick (table holds addr-1) is a 6502 idiom; only scan for it on the
+  // 6502 family so we don't surface spurious addr-1 matches on Z80/m68k/etc.
+  const SIXTYFIVE_OH_TWO = new Set(["nes", "atari2600", "atari7800", "c64", "lynx", "pce"]);
+  const rtsTrick = SIXTYFIVE_OH_TWO.has(resolved);
+  const wantTableHits = includeTableHits || refs.length === 0;
+  const tableHits = wantTableHits ? scanPointerTableHits(data, address, headerSkip, rtsTrick) : null;
+
   return {
     path,
     platform: resolved,
@@ -523,9 +602,21 @@ export async function findReferencesCore({ path, platform, address, mapper, maxR
     truncated: refs.length > maxRefsReturned
       ? `${refs.length - maxRefsReturned} additional references not returned (raise maxRefsReturned).`
       : undefined,
+    ...(tableHits && tableHits.length
+      ? {
+          tableHits: tableHits.slice(0, maxRefsReturned),
+          tableHitsFound: tableHits.length,
+        }
+      : {}),
     notes: [
       refs.length === 0
-        ? `No references found. Address $${address.toString(16).toUpperCase()} may be unreached, or an indirect/computed jump target.`
+        ? `No DIRECT control-flow references (jsr/jmp/branch naming $${address.toString(16).toUpperCase()}).` +
+          (tableHits && tableHits.length
+            ? ` BUT ${tableHits.length} pointer-table hit(s) — the address appears as a 16-bit word in the ROM (an inline jump-table / trampoline reaches it via a computed jump). See tableHits: fileOffset is where the pointer sits; convention 'rts+1' is the 6502 RTS-trick (table holds addr-1).`
+            : ` No pointer-table hits either — likely unreached, or a register/computed target this scan can't resolve.`)
+        : null,
+      refs.length > 0 && tableHits && tableHits.length
+        ? `Also ${tableHits.length} pointer-table hit(s) (the address also appears as a raw 16-bit pointer — see tableHits).`
         : null,
       segmentsCapped > 0
         ? `Scan covered the first ${SEGMENT_CAP} banks only — ${segmentsCapped} additional bank(s) were NOT scanned (very large cart).`