romdevtools 0.44.0 → 0.56.1

package/src/host/LibretroHost.js

@@ -49,6 +49,12 @@ const PLATFORM_CORE_OPTIONS = {
   // host's port-1 input to pad slot 2 — PCE 2P works (probed 2026-06-10
   // during the ZENITH BARRAGE gold round).
   pce: { geargrafx_turbotap: "Enabled" },
+  // parallel_n64 defaults to a software gfx plugin that never presents to our GL
+  // FBO. Force glide64 (the GL renderer) so HW render actually produces frames.
+  n64: { "parallel-n64-gfxplugin": "glide64" },
+  // beetle_psx_hw defaults to the software renderer; force hardware_gl so it
+  // renders through the GL context the host set up (otherwise no FBO frames).
+  ps1: { beetle_psx_hw_renderer: "hardware_gl" },
   // VICE mounts a .d64/.tap/.crt but, with autostart off, just sits at the BASIC
   // `READY.` prompt — the agent would see a blue boot screen, not the game. Force
   // autostart so a disk/tape image runs the first program automatically (same as
@@ -155,7 +161,7 @@ export const PLATFORM_VIRTUAL_EXT = {
   pce:        ".pce",
   msx:        ".rom",
 };
-import { RETRO_DEVICE_JOYPAD } from "./retroConstants.js";
+import { RETRO_DEVICE_JOYPAD, ROMDEV_PIXEL_FORMAT_RGBA8888 } from "./retroConstants.js";
 
 // C64 controller→keyboard map (the Batocera/RetroDeck model: a CONTROLLER alone
 // plays C64 — no physical keyboard needed — by mapping spare buttons/stick to
@@ -241,11 +247,45 @@ export class LibretroHost {
    * Load a libretro core module. Registers callbacks then runs retro_init.
    * @param {string} jsPath
    * @param {string} [wasmPath]
+   * @param {Object} [opts]
+   * @param {boolean} [opts.hwRender] this core HW-renders (GL) — n64/ps1. Loads the
+   *   optional native GL stack and creates a headless context BEFORE the core boots
+   *   (GL calls happen during init/load). The 14 software cores omit this.
    */
-  async loadCore(jsPath, wasmPath) {
+  async loadCore(jsPath, wasmPath, opts = {}) {
     if (this.mod) throw new Error("core already loaded; create a new host");
-    const mod = await loadLibretroCore({ jsPath, wasmPath });
+
+    let glCanvas = null;
+    if (opts.hwRender) {
+      // Set up the HW-render path: LibretroGL owns the FBO/readback; a webgl-node
+      // mock canvas backs the minified core's GLctx. Both pull the OPTIONAL native
+      // GL deps lazily (clear install hint if absent).
+      const { LibretroGL } = await import("./LibretroGL.js");
+      const { loadWebGl2Context } = await import("./glOptionalDep.js");
+      this.hwRender = new LibretroGL();
+      await this.hwRender.ensureGl();
+      const createWebGL2Context = await loadWebGl2Context();
+      const { canvas } = createWebGL2Context(640, 480);
+      // Skip Emscripten's Safari WebGL2 workaround (breaks instanceof) by
+      // pre-setting the flag it checks.
+      canvas.getContextSafariWebGL2Fixed = canvas.getContext;
+      glCanvas = canvas;
+      this._glContextCreated = true;
+      // The env callback routes SET_HW_RENDER to this handler.
+      this.state.hwRender = this.hwRender;
+    }
+
+    const mod = await loadLibretroCore({ jsPath, wasmPath, glCanvas });
     this.mod = mod;
+
+    // Canvas HW-render cores: initialize the Emscripten GL context so `GLctx` is
+    // set BEFORE any GL call (the core's context_reset / first getParameter). Must
+    // run before _retro_init.
+    if (glCanvas && mod.GL) {
+      const handle = mod.GL.createContext(glCanvas, { majorVersion: 2 });
+      if (handle > 0) mod.GL.makeContextCurrent(handle);
+    }
+
     registerCallbacks({ mod, state: this.state, log: this.log });
     mod._retro_init();
     this.status.corePath = jsPath;
@@ -430,8 +470,19 @@ export class LibretroHost {
       : this.status.fbWidth / this.status.fbHeight;
     // timing.sample_rate is at offset +32 (double).
     this.status.audioSampleRate = mod.getValue(avInfoPtr + 32, "double");
+    // max_width/max_height (+8/+12) bound the FBO for HW-render cores (the core may
+    // render larger than base, e.g. N64 hi-res or PS1 internal upscale).
+    const maxW = mod.getValue(avInfoPtr + 8, "i32") || this.status.fbWidth;
+    const maxH = mod.getValue(avInfoPtr + 12, "i32") || this.status.fbHeight;
     mod._free(avInfoPtr);
 
+    // HW render: now that AV info is known, create the FBO the core renders into.
+    // createContext() also fires the core's context_reset (via dynCall) so it
+    // (re)builds its GL resources. The EGL context was already created in loadCore.
+    if (this.hwRender?.active) {
+      this.hwRender.createContext(maxW, maxH, this._glContextCreated);
+    }
+
     // Configure controller port 0 as joypad (some cores default to NONE).
     mod._retro_set_controller_port_device(0, RETRO_DEVICE_JOYPAD);
     // Port 1 too — needed for 2P. The C64/VICE 2P path (two live control ports)
@@ -480,6 +531,7 @@ export class LibretroHost {
       let firstRefreshAt = -1;
       while (stepped < MAX_SETTLE) {
         mod._retro_run();
+        this._afterRun();
         stepped++;
         if (firstRefreshAt < 0 && this.state.lastFrame && this.state.lastFrame !== beforeRefreshSnapshot) {
           firstRefreshAt = stepped;
@@ -520,6 +572,7 @@ export class LibretroHost {
     if (this.status.paused) return 0;
     for (let i = 0; i < n; i++) {
       mod._retro_run();
+      this._afterRun();
       this.status.frameCount++;
     }
     if (this.state.lastFrame) {
@@ -529,6 +582,23 @@ export class LibretroHost {
     return n;
   }
 
+  /** Post-_retro_run hook: HW-render readback. The video callback set
+   *  state.hwFramePending during run; now (GL state stable) read back the FBO into
+   *  state.lastFrame as an RGBA frame. No-op for the 14 software cores. */
+  _afterRun() {
+    if (this.state.hwFramePending && this.hwRender?.active) {
+      this.state.hwFramePending = false;
+      const frame = this.hwRender.readbackFrame();
+      if (frame) {
+        this.state.lastFrame = {
+          width: frame.width, height: frame.height,
+          pitch: frame.width * 4, format: ROMDEV_PIXEL_FORMAT_RGBA8888,
+          pixels: frame.pixels, rgba: true,
+        };
+      }
+    }
+  }
+
   /** Run exactly ONE frame to refresh the framebuffer, even while paused — for a
    *  deterministic "restore → screenshot" without un-pausing (so the real-time
    *  playtest loop can't race). Advances the (monotonic) frame counter by 1.
@@ -537,6 +607,7 @@ export class LibretroHost {
     const mod = this._needMod();
     this._needMedia();
     mod._retro_run();
+    this._afterRun();
     this.status.frameCount++;
     if (this.state.lastFrame) {
       this.status.fbWidth = this.state.lastFrame.width;
@@ -821,6 +892,19 @@ export class LibretroHost {
 
   readMemory(region, offset, length) {
     const mod = this._needMod();
+    // PS1 GPU VRAM (1024×512×16bpp = 1MB) isn't on the RETRO_MEMORY interface; the
+    // rebuilt pcsx core exposes it via romdev_vram_get. Serve video_ram from there.
+    if (region === "video_ram" && typeof mod._romdev_vram_get === "function") {
+      const SIZE = 1024 * 512 * 2;
+      if (offset < 0 || offset + length > SIZE) {
+        throw new RangeError(`read out of bounds: offset=${offset} len=${length} size=${SIZE}`);
+      }
+      const p = mod._malloc(SIZE);
+      try {
+        mod._romdev_vram_get(p, SIZE / 2);
+        return new Uint8Array(mod.HEAPU8.buffer, p + offset, length).slice();
+      } finally { mod._free(p); }
+    }
     const id = MemoryRegionToRetro[region];
     if (id === undefined) throw new Error(this._unknownRegionError(region));
     const ptr = mod._retro_get_memory_data(id);
@@ -1380,6 +1464,63 @@ export class LibretroHost {
    * instruction (ARM: its pipeline PC, the same convention breakpoint
    * addresses use). Pass clear to reset the kind.
    */
+  /** True when the loaded MIPS core (n64/ps1) exposes the live R3000/R4300 register
+   *  snapshot (the cheat+regsnap-enabled romdev build). */
+  mipsRegsSupported() {
+    return !!(this.mod && typeof this.mod._romdev_mips_regs_get === "function");
+  }
+
+  /** Read the live MIPS register file: 32 GPRs + LO + HI + PC, as a Uint32Array(35).
+   *  null if the core doesn't expose it (older build). */
+  getMipsRegs() {
+    const mod = this.mod;
+    if (!mod || typeof mod._romdev_mips_regs_get !== "function") return null;
+    const ptr = mod._malloc(35 * 4);
+    try {
+      mod._romdev_mips_regs_get(ptr);
+      return new Uint32Array(mod.HEAPU8.buffer, ptr, 35).slice();
+    } finally {
+      mod._free(ptr);
+    }
+  }
+
+  /** True when the PS1 core exposes the SPU register block (getAudioState chip:'spu'). */
+  spuRegsSupported() {
+    return !!(this.mod && typeof this.mod._romdev_spu_get === "function");
+  }
+
+  /** True when the N64 core exposes the AI registers (getAudioState chip:'ai'). */
+  aiRegsSupported() {
+    return !!(this.mod && typeof this.mod._romdev_ai_get === "function");
+  }
+
+  /** Read the N64 AI registers + VI clock as a Uint32Array(7). null if absent. */
+  getAiRegs() {
+    const mod = this.mod;
+    if (!mod || typeof mod._romdev_ai_get !== "function") return null;
+    const ptr = mod._malloc(7 * 4);
+    try {
+      mod._romdev_ai_get(ptr);
+      return new Uint32Array(mod.HEAPU8.buffer, ptr, 7).slice();
+    } finally {
+      mod._free(ptr);
+    }
+  }
+
+  /** Read the PS1 SPU's 0x400-word register block as a Uint16Array(1024). null if
+   *  the core doesn't expose it. */
+  getSpuRegs() {
+    const mod = this.mod;
+    if (!mod || typeof mod._romdev_spu_get !== "function") return null;
+    const ptr = mod._malloc(0x400 * 2);
+    try {
+      mod._romdev_spu_get(ptr, 0x400);
+      return new Uint16Array(mod.HEAPU8.buffer, ptr, 0x400).slice();
+    } finally {
+      mod._free(ptr);
+    }
+  }
+
   getRegSnapshot(clear = false) {
     const mod = this.mod;
     if (!mod || typeof mod._romdev_regsnap_get !== "function") return null;

package/src/host/callbacks.js

@@ -164,7 +164,17 @@ export function registerCallbacks(args) {
   mod._retro_set_environment(envCb);
 
   const videoCb = mod.addFunction((dataPtr, w, h, pitch) => {
-    if (dataPtr === 0 || dataPtr === RETRO_HW_FRAME_BUFFER_VALID) return;
+    // HW-render path: dataPtr == RETRO_HW_FRAME_BUFFER_VALID means "the frame is in
+    // the GL framebuffer." The WASM passes the i32 as SIGNED -1; the constant is the
+    // UNSIGNED 0xFFFFFFFF — coerce with >>>0 so both match. DON'T read back here —
+    // GL state is only stable AFTER _retro_run returns. Flag it; stepFrames does the
+    // glReadPixels post-run.
+    const uPtr = dataPtr >>> 0;
+    if (uPtr === RETRO_HW_FRAME_BUFFER_VALID && state.hwRender?.active) {
+      state.hwFramePending = true;
+      return;
+    }
+    if (dataPtr === 0 || uPtr === RETRO_HW_FRAME_BUFFER_VALID) return;
     const bytes = h * pitch;
     const view = mod.HEAPU8.subarray(dataPtr, dataPtr + bytes);
     state.lastFrame = {
@@ -429,8 +439,14 @@ function handleEnv(mod, state, rawCmd, dataPtr, log) {
     case E.SET_PROC_ADDRESS_CALLBACK:
       return true;
 
+    // HW render (n64/ps1): if the host set up a GL handler (state.hwRender), let it
+    // claim the SET_HW_RENDER request + install its callbacks. Without it (the 14
+    // software cores, or no GL stack), reject so the core falls back to software.
+    case E.SET_HW_RENDER:
+      if (state.hwRender) return state.hwRender.setup(mod, dataPtr);
+      return false;
+
     // Things we can't or don't want to support — reject so core falls back.
-    case E.SET_HW_RENDER: // no GL in headless mode
     case E.GET_RUMBLE_INTERFACE:
     case E.GET_SENSOR_INTERFACE:
     case E.GET_CAMERA_INTERFACE:

package/src/host/coreLoader.js

@@ -14,6 +14,10 @@ import { RETRO_API_VERSION } from "./retroConstants.js";
  * @typedef {Object} LoadCoreArgs
  * @property {string} jsPath absolute path to the `_libretro.js` glue
  * @property {string} [wasmPath] absolute path to the `.wasm`; if omitted, Emscripten resolves next to the .js
+ * @property {object} [glCanvas] HW-render cores (n64/ps1): a webgl-node mock canvas the
+ *   minified Emscripten glue drives via `GLctx = canvas.getContext('webgl2')`.
+ * @property {object} [glBridge] HW-render cores with UNMINIFIED imports: a map of GL
+ *   function name → native-gles impl, patched directly into the WASM env imports.
  */
 
 /**
@@ -22,7 +26,7 @@ import { RETRO_API_VERSION } from "./retroConstants.js";
  * @param {LoadCoreArgs} args
  */
 export async function loadLibretroCore(args) {
-  const { jsPath, wasmPath } = args;
+  const { jsPath, wasmPath, glCanvas, glBridge } = args;
 
   const url = pathToFileURL(jsPath).href + "?t=" + Date.now();
   const ns = await import(url);
@@ -37,7 +41,50 @@ export async function loadLibretroCore(args) {
     print: () => {},
     printErr: () => {},
   };
-  if (wasmPath) {
+
+  // HW-render cores: minified glue uses GLctx = canvas.getContext('webgl2'), so we
+  // hand it a webgl-node mock canvas + install the WebGL2 globals Emscripten probes.
+  if (glCanvas) {
+    opts.canvas = glCanvas;
+    if (typeof globalThis.WebGL2RenderingContext === "undefined") {
+      const { WebGL2RenderingContext } = await import("webgl-node");
+      globalThis.WebGL2RenderingContext = WebGL2RenderingContext;
+      // CRITICAL: WebGLRenderingContext (WebGL1) must be a DISTINCT class from
+      // WebGL2RenderingContext. Emscripten's getContext shim does
+      //   return (ver=="webgl") == (gl instanceof WebGLRenderingContext) ? gl : null
+      // For ver="webgl2" that needs `gl instanceof WebGLRenderingContext` to be
+      // FALSE. If we aliased WebGLRenderingContext to the WebGL2 class, a webgl2
+      // context IS instanceof it → the shim returns null → GLctx never set → the
+      // core renders nothing. So WebGL1 gets its own empty marker class.
+      globalThis.WebGLRenderingContext = class WebGLRenderingContext {};
+    }
+  }
+
+  if (wasmPath && glBridge) {
+    // Unminified GL cores: patch GL function imports + no-op EGL (we own EGL via
+    // native-gles), and capture the instance memory for the bridge's marshaling.
+    const wasmBinary = await readFile(wasmPath);
+    opts.instantiateWasm = (info, receiveInstance) => {
+      for (const nsObj of Object.values(info)) {
+        if (typeof nsObj !== "object" || nsObj === null) continue;
+        for (const [name, fn] of Object.entries(glBridge)) {
+          if (name in nsObj) nsObj[name] = fn;
+        }
+        if ("eglGetDisplay" in nsObj) {
+          nsObj.eglGetDisplay = () => 62000;
+          nsObj.eglInitialize = () => 1;
+          nsObj.eglQueryString = () => 0;
+        }
+      }
+      WebAssembly.instantiate(wasmBinary, info).then((result) => {
+        if (glBridge._setMemory && result.instance.exports.memory) {
+          glBridge._setMemory(result.instance.exports.memory);
+        }
+        receiveInstance(result.instance, result.module);
+      });
+      return {};
+    };
+  } else if (wasmPath) {
     opts.wasmBinary = await readFile(wasmPath);
   }
 

package/src/host/cpu-state.js

@@ -139,6 +139,30 @@ function decodeSnes9xSPC(state) {
  * @param {Uint8Array} bytes 28-byte snapshot
  * @returns {ReturnType<typeof formatCpuState> | null}
  */
+/** MIPS R3000 (PS1) / R4300 (N64) register names, $0..$31. */
+const MIPS_GPR_NAMES = [
+  "zero", "at", "v0", "v1", "a0", "a1", "a2", "a3",
+  "t0", "t1", "t2", "t3", "t4", "t5", "t6", "t7",
+  "s0", "s1", "s2", "s3", "s4", "s5", "s6", "s7",
+  "t8", "t9", "k0", "k1", "gp", "sp", "fp", "ra",
+];
+
+/** Decode the romdev MIPS regsnap (Uint32Array(35): 32 GPRs + LO + HI + PC) into a
+ *  CPUState. Names follow the MIPS o32 ABI convention. */
+function decodeMips(regs) {
+  if (!regs || regs.length < 35) return null;
+  const hx = (v) => "$" + (v >>> 0).toString(16).toUpperCase().padStart(8, "0");
+  const named = {};
+  for (let i = 0; i < 32; i++) named[MIPS_GPR_NAMES[i]] = hx(regs[i]);
+  named.lo = hx(regs[32]);
+  named.hi = hx(regs[33]);
+  return {
+    pc: regs[34] >>> 0,
+    pcHex: hx(regs[34]),
+    registers: named,
+  };
+}
+
 function decode6502(bytes) {
   if (!bytes || bytes.length < 25) return null;
   const u16le = (o) => bytes[o] | (bytes[o + 1] << 8);
@@ -300,6 +324,9 @@ function decodeZ80(bytes) {
  * @returns {CPUState | null}
  */
 export function getCPUState(host, platform, cpu = "main") {
+  if (platform === "n64" || platform === "ps1") {
+    return decodeMips(host.getMipsRegs?.());
+  }
   if (platform === "nes") {
     const bytes = host.readMemory("nes_cpu_regs", 0, 28);
     return decode6502(bytes);

package/src/host/framebuffer.js

@@ -12,6 +12,7 @@ import {
   RETRO_PIXEL_FORMAT_0RGB1555,
   RETRO_PIXEL_FORMAT_RGB565,
   RETRO_PIXEL_FORMAT_XRGB8888,
+  ROMDEV_PIXEL_FORMAT_RGBA8888,
 } from "./retroConstants.js";
 
 /**
@@ -35,7 +36,19 @@ export function framebufferToRgba(width, height, src, pitch, format) {
 }
 
 function decodePixelsInto(dst, width, height, src, pitch, format) {
-  if (format === RETRO_PIXEL_FORMAT_XRGB8888) {
+  if (format === ROMDEV_PIXEL_FORMAT_RGBA8888) {
+    // HW-render readback: already RGBA. Copy RGB row-by-row but FORCE alpha=255 —
+    // the N64/PS1 GL framebuffer leaves alpha at 0 (it's the render target's unused
+    // channel), which would make every pixel transparent → composites to white.
+    for (let y = 0; y < height; y++) {
+      const sRow = y * pitch, dRow = y * width * 4;
+      for (let x = 0; x < width; x++) {
+        const s = sRow + x * 4, d = dRow + x * 4;
+        dst[d] = src[s]; dst[d + 1] = src[s + 1]; dst[d + 2] = src[s + 2];
+        dst[d + 3] = 0xff;
+      }
+    }
+  } else if (format === RETRO_PIXEL_FORMAT_XRGB8888) {
     for (let y = 0; y < height; y++) {
       const srcRow = y * pitch;
       const dstRow = y * width * 4;

package/src/host/glOptionalDep.js

@@ -0,0 +1,60 @@
+// glOptionalDep.js — lazy, optional loader for the native GL stack.
+//
+// The HW-render cores (N64 ParaLLEl, PS1 Beetle-PSX) need a real headless GL
+// context. romdev provides it through `native-gles` (EGL/GLES via a prebuilt
+// .node) and `webgl-node` (a WebGL2 context object for the minified Emscripten
+// cores). Both are OPTIONAL dependencies: the 14 software-rendered cores never
+// touch them, and a headless user who never boots N64/PS1 doesn't need them
+// installed. We load them lazily and, if absent, throw ONE clear, actionable
+// error instead of a cryptic module-not-found.
+
+let _gl = null;
+let _webgl = null;
+
+const INSTALL_HINT =
+  "N64/PS1 emulation needs the optional native GL module. Install it with:\n" +
+  "  npm install native-gles webgl-node\n" +
+  "(the other 14 platforms are software-rendered and don't require it).";
+
+/**
+ * Load the `native-gles` default export (the EGL/GLES binding). Cached.
+ * @returns {Promise<object>} the native-gles module
+ * @throws {Error} a clear install hint if the module isn't available
+ */
+export async function loadNativeGles() {
+  if (_gl) return _gl;
+  try {
+    _gl = (await import("native-gles")).default;
+  } catch (e) {
+    throw new Error(`${INSTALL_HINT}\n(underlying: ${e.message})`);
+  }
+  if (!_gl || typeof _gl.createContext !== "function") {
+    throw new Error(`native-gles loaded but has no createContext — ${INSTALL_HINT}`);
+  }
+  return _gl;
+}
+
+/**
+ * Load `webgl-node`'s createWebGL2Context (the canvas/context the minified
+ * Emscripten cores use via GLctx = canvas.getContext('webgl2')). Cached.
+ * @returns {Promise<Function>} createWebGL2Context(width, height) → { canvas, gl }
+ * @throws {Error} a clear install hint if the module isn't available
+ */
+export async function loadWebGl2Context() {
+  if (_webgl) return _webgl;
+  try {
+    const m = await import("webgl-node");
+    _webgl = m.createWebGL2Context;
+  } catch (e) {
+    throw new Error(`${INSTALL_HINT}\n(underlying: ${e.message})`);
+  }
+  if (typeof _webgl !== "function") {
+    throw new Error(`webgl-node loaded but has no createWebGL2Context — ${INSTALL_HINT}`);
+  }
+  return _webgl;
+}
+
+/** Best-effort probe: is the native GL stack importable? (for capability flags) */
+export async function glStackAvailable() {
+  try { await loadNativeGles(); return true; } catch { return false; }
+}

package/src/host/n64-ai-state.js

@@ -0,0 +1,43 @@
+// N64 AI (Audio Interface) decoder.
+//
+// Data source: the romdev_ai_get export (parallel_n64) — the 6 AI registers + the
+// VI clock. The N64 has no per-voice sound chip like the SNES DSP; audio is mixed
+// by the RSP (microcode-dependent) and streamed to the AI's DAC via DMA. So the
+// AI tells us the OUTPUT state: sample rate, whether audio is playing (a buffer is
+// queued), and the DMA source address — the actionable "is sound on, at what rate"
+// answer, not a per-channel breakdown (which lives in game-specific RSP audio lists).
+//
+// out layout: [DRAM_ADDR, LEN, CONTROL, STATUS, DACRATE, BITRATE, VI_CLOCK]
+
+/**
+ * @param {Uint32Array} a the 7-word AI snapshot (6 regs + VI clock)
+ * @returns {{ chip:"ai", playing:boolean, sampleRate:number, dmaAddress:number,
+ *   queuedBytes:number, dacRate:number, bitRate:number, control:number,
+ *   status:number, note:string }}
+ */
+export function decodeN64Ai(a) {
+  if (!a || a.length < 7) return { chip: "ai", playing: false, note: "no AI data" };
+  const dramAddr = a[0] >>> 0;
+  const len = a[1] >>> 0;
+  const control = a[2] >>> 0;
+  const status = a[3] >>> 0;
+  const dacRate = a[4] >>> 0;
+  const bitRate = a[5] >>> 0;
+  const viClock = a[6] >>> 0;
+  // DAC sample rate = VI clock / (dacrate + 1). dacrate 0 / no clock → unknown.
+  const sampleRate = dacRate && viClock ? Math.round(viClock / (dacRate + 1)) : 0;
+  // AI_LEN nonzero (a buffer is queued) AND DMA enabled (control bit0) = playing.
+  const playing = (len & 0x3ffff) > 0 && (control & 1) !== 0;
+  return {
+    chip: "ai",
+    playing,
+    sampleRate,
+    queuedBytes: len & 0x3ffff,
+    dmaAddress: "0x" + dramAddr.toString(16).toUpperCase(),
+    dacRate,
+    bitRate,
+    control,
+    status,
+    note: "N64 audio is RSP-mixed; the AI exposes the OUTPUT (sample rate + whether a buffer is playing + the DMA source), not per-channel voices. For per-channel, trace the game's RSP audio list in RDRAM.",
+  };
+}

package/src/host/ps1-spu-state.js

@@ -0,0 +1,65 @@
+// PS1 SPU (Sound Processing Unit) decoder.
+//
+// Data source: the SPU's 0x400-word register block ($1F801C00-based), exposed by
+// the romdev_spu_get export in the rebuilt pcsx_rearmed core. The block is indexed
+// as 16-bit words; per-voice registers occupy the first 24×8 words (16 bytes each),
+// then the global voice/control registers follow.
+//
+// The SPU has 24 ADPCM voices. Per voice (offset = voice*8 words):
+//   +0 VolumeLeft   +1 VolumeRight   +2 ADPCM SampleRate (pitch)
+//   +3 ADPCM StartAddr   +4 ADSR lo   +5 ADSR hi   +6 ADSR CurrentVol  +7 RepeatAddr
+// Global (word index):
+//   0xC0/0xC1 = main volume L/R, 0xCC/0xCD = KeyOn (24-bit across two words),
+//   0xCE/0xCF = KeyOff, 0xD6 = SPU control (SPUCNT).
+
+const NUM_VOICES = 24;
+
+/** SPU pitch → Hz: the 16-bit pitch is in units of 44100/4096 Hz per step
+ *  (4096 = "1.0" = 44100 Hz). */
+function pitchToHz(pitch) {
+  return Math.round((pitch / 4096) * 44100);
+}
+
+/**
+ * @param {Uint16Array} regs the 0x400-word SPU register block
+ * @returns {{ chip:"spu", mainVolumeLeft:number, mainVolumeRight:number,
+ *   control:number, voices:Array<object> }}
+ */
+export function decodePs1Spu(regs) {
+  if (!regs || regs.length < 0x200) return { chip: "spu", voices: [] };
+  // Key-on / key-off are 24-bit, split across two 16-bit words.
+  const keyOn = (regs[0xCC] | (regs[0xCD] << 16)) >>> 0;
+  const keyOff = (regs[0xCE] | (regs[0xCF] << 16)) >>> 0;
+
+  const voices = [];
+  for (let v = 0; v < NUM_VOICES; v++) {
+    const b = v * 8;
+    const volL = regs[b + 0];
+    const volR = regs[b + 1];
+    const pitch = regs[b + 2];
+    const adsr = (regs[b + 4] | (regs[b + 5] << 16)) >>> 0;
+    const curVol = regs[b + 6];
+    const on = !!(keyOn & (1 << v));
+    voices.push({
+      voice: v,
+      keyOn: on,
+      keyOff: !!(keyOff & (1 << v)),
+      // signed 15-bit volumes (top bit = sweep mode; report the magnitude)
+      volumeLeft: volL & 0x7fff,
+      volumeRight: volR & 0x7fff,
+      pitch,
+      hz: pitch ? pitchToHz(pitch) : 0,
+      adsr: "0x" + adsr.toString(16).padStart(8, "0").toUpperCase(),
+      currentVolume: curVol,
+      active: curVol > 0 || on,
+    });
+  }
+  return {
+    chip: "spu",
+    mainVolumeLeft: regs[0xC0] & 0x7fff,
+    mainVolumeRight: regs[0xC1] & 0x7fff,
+    control: regs[0xD6],
+    keyOnMask: "0x" + keyOn.toString(16).toUpperCase(),
+    voices,
+  };
+}

package/src/host/retroConstants.js

@@ -70,3 +70,17 @@ export const RETRO_LOG_ERROR = 3;
 // Sentinels
 /** Video refresh data pointer meaning "GL framebuffer is valid". */
 export const RETRO_HW_FRAME_BUFFER_VALID = -1 >>> 0; // unsigned -1
+
+// HW render context types (retro_hw_context_type) — the GL flavors the
+// HW-render cores (n64/ps1) request via RETRO_ENVIRONMENT_SET_HW_RENDER.
+export const RETRO_HW_CONTEXT_NONE = 0;
+export const RETRO_HW_CONTEXT_OPENGL = 1;        // OpenGL 2.x (compat)
+export const RETRO_HW_CONTEXT_OPENGLES2 = 2;     // GLES 2.0
+export const RETRO_HW_CONTEXT_OPENGL_CORE = 3;   // OpenGL 3+ core
+export const RETRO_HW_CONTEXT_OPENGLES3 = 4;     // GLES 3.0
+export const RETRO_HW_CONTEXT_OPENGLES_VERSION = 5; // GLES with explicit version
+
+// romdev-internal sentinel: a HW-render readback frame is already RGBA8888 (from
+// glReadPixels GL_RGBA), NOT the BGRA byte order libretro's XRGB8888 uses. The
+// framebuffer decoder special-cases this so R/B aren't swapped.
+export const ROMDEV_PIXEL_FORMAT_RGBA8888 = 0x52474241; // 'RGBA'

package/src/mcp/tools/disasm.js

@@ -1609,6 +1609,8 @@ function sniffPlatformFromPath(p) {
   if (/\.prg$/i.test(p)) return "c64";
   if (/\.(lnx|lyx)$/i.test(p)) return "lynx";
   if (/\.gba$/i.test(p)) return "gba";
+  if (/\.(z64|n64|v64)$/i.test(p)) return "n64";
+  if (/\.(psexe|psx)$/i.test(p)) return "ps1"; // .exe/.bin are ambiguous — pass platform explicitly
   if (/\.(gen|md|bin)$/i.test(p)) return "genesis";
   return null;
 }

package/src/mcp/tools/frame.js

@@ -389,10 +389,14 @@ export function registerFrameTools(server, z, sessionKey) {
   async function shootAscii({ cols, rows, symbols, colors, path: outPath, inline }) {
     const host = getHost(sessionKey);
     const { width, height, rgba } = host.screenshotRgba();
-    // Default each cell to "2 game tiles" (8×8 platforms) so the grid maps
-    // to tile coords: cell (c,r) covers tiles (c*2..c*2+1, r*2..r*2+1).
-    if (cols == null) cols = Math.max(4, Math.floor(width / 16));
-    if (rows == null) rows = Math.max(4, Math.floor(height / 16));
+    // Default to ONE cell per 8×8 tile (so a 256×224 NES frame → 32×28, legible
+    // game state). The old /16 default (16×14 for NES) was too coarse to read
+    // anything — feedback 0.44.0 #1. The terminal symbol's own subcell shape adds
+    // detail back, so this stays cheap.
+    if (cols == null) cols = Math.max(8, Math.floor(width / 8));
+    if (rows == null) rows = Math.max(8, Math.floor(height / 8));
+    // Warn when the caller forced a grid so coarse it can't show game state.
+    const tooCoarse = cols < Math.floor(width / 8) / 2 || rows < Math.floor(height / 8) / 2;
     const { renderRgbaToAnsi } = await import("../../host/chafa-render.js");
     const ansi = await renderRgbaToAnsi(rgba, width, height, { cols, rows, symbols, colors });
     // Livestream sidebands: the human sees BOTH the real PNG and the ANSI.
@@ -401,15 +405,20 @@ export function registerFrameTools(server, z, sessionKey) {
       _observerImages: [{ kind: "image", mimeType: "image/png", base64: shot.pngBase64 }],
       _observerAnsi: ansi,
     };
+    const coarseNote = tooCoarse
+      ? `NOTE: ${cols}x${rows} is too coarse to read game state from this ${width}x${height} frame. `
+        + `For a pass/fail check ("are we in gameplay?"), a memory({op:'read'}) byte assertion is cheaper and exact — `
+        + `ascii is for a rough visual, not state.`
+      : null;
     let result;
     if (!inline) {
       await writeFile(outPath, ansi, "utf-8");
-      result = jsonContent({ path: outPath, framebuffer: { width, height }, terminal: { cols, rows, symbols, colors }, ansiBytes: Buffer.byteLength(ansi, "utf-8") });
+      result = jsonContent({ path: outPath, framebuffer: { width, height }, terminal: { cols, rows, symbols, colors }, ansiBytes: Buffer.byteLength(ansi, "utf-8"), ...(coarseNote ? { note: coarseNote } : {}) });
     } else {
       result = {
         content: [
           { type: "text", text: ansi },
-          { type: "text", text: `framebuffer ${width}x${height} → terminal ${cols}x${rows} (${symbols}/${colors}, ${Buffer.byteLength(ansi, "utf-8")}B)` },
+          { type: "text", text: `framebuffer ${width}x${height} → terminal ${cols}x${rows} (${symbols}/${colors}, ${Buffer.byteLength(ansi, "utf-8")}B)` + (coarseNote ? `\n${coarseNote}` : "") },
         ],
       };
     }
@@ -857,10 +866,10 @@ export function registerFrameTools(server, z, sessionKey) {
       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(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. DEFAULT (unset/1) = NATIVE resolution — perfect pixels, the accurate representation; use this. 0<scale<1 DOWNscales (0.5 ≈ 75% fewer image tokens — useful for cheap 'did it change?' checks). integer scale≥2 UPscales by pixel-duplication (e.g. scale:4 → GB 160x144 → 640x576): it adds NO information (same pixels enlarged), costs MORE image tokens, and since VLM encoders resize to their own fixed resolution it may not change what the model sees and can slightly degrade it. Only for clients that render tiny images too small to use and can't zoom."),
-      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)."),
+      cols: z.number().int().min(4).max(640).optional().describe("op=screenshot ascii: terminal columns (default fb_width/8 — one cell per 8×8 tile, legible game state)."),
+      rows: z.number().int().min(4).max(480).optional().describe("op=screenshot ascii: terminal rows (default fb_height/8)."),
       symbols: z.enum(["ascii", "halfblock", "block", "quad", "sextant"]).default("ascii").describe("op=screenshot ascii: chafa symbol set."),
-      colors: z.enum(["true", "256", "16", "fgbg"]).default("true").describe("op=screenshot ascii: color depth."),
+      colors: z.enum(["true", "256", "16", "fgbg"]).default("256").describe("op=screenshot ascii: color depth. Default '256' (indexed) — far fewer ANSI escape bytes than 'true' (truecolor per cell) for a near-identical read. Use 'true' only when exact color matters."),
     },
     safeTool(async (args) => {
       switch (args.op) {

package/src/mcp/tools/lifecycle.js

@@ -21,7 +21,7 @@ export function registerLifecycleTools(server, z, sessionKey) {
     if (path && base64) throw new Error("loadMedia: provide `path` OR `base64`, not both.");
     const slotB = slot === "b";
     const host = slotB ? resetHostB(sessionKey) : resetHost(sessionKey);
-    await host.loadCore(resolved.jsPath, resolved.wasmPath);
+    await host.loadCore(resolved.jsPath, resolved.wasmPath, { hwRender: resolved.hwRender });
     const bytes = base64 ? new Uint8Array(Buffer.from(base64, "base64")) : undefined;
     await host.loadMedia({
       platform,