romdevtools 0.44.0 → 0.70.0

package/src/host/LibretroHost.js

@@ -36,6 +36,17 @@ import {
  * to function headlessly (no menu = no user pick). Empty today — all
  * shipped cores load with their defaults.
  */
+// Core filename stem → platform, for the cores whose renderer (or other boot-time
+// behavior) is chosen from an option at retro_init. loadCore uses this to pre-seed
+// PLATFORM_CORE_OPTIONS before the core registers its variables, so the override
+// wins over the core's default (e.g. glide64-GL over angrylion-software for N64).
+const CORE_STEM_TO_PLATFORM = {
+  parallel_n64: "n64",
+  pcsx_rearmed: "ps1",
+  flycast: "dreamcast",
+  beetle_psx_hw: "ps1",
+};
+
 const PLATFORM_CORE_OPTIONS = {
   // blueMSX defaults its machine to "SEGA - SC-3000" (an SG-1000 clone, wrong for
   // MSX carts). Force the open MSX2+ C-BIOS machine — a superset that also runs
@@ -49,6 +60,30 @@ 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" },
+  // Flycast defaults to THREADED rendering — the render thread + the main thread's
+  // wait on it makes retro_run unwind under emscripten pthreads (yields to the event
+  // loop, incompatible with our synchronous frame-step). Disable it so render() runs
+  // synchronously on the calling thread (Emulator::render → run(), no cross-thread
+  // wait). Also keep per-frame sync (no auto frame-skip) so one retro_run = one frame.
+  // hle_bios (reios) MUST be on: it's flycast's HLE BIOS, and only the reios boot
+  // path loads a raw homebrew .elf (reios_loadElf copies PT_LOAD segments to their
+  // vaddr + jumps). With it off (the default), flycast wants a real dc_boot.bin we
+  // don't ship → the .elf never loads (RAM stays empty, CPU never runs our code).
+  // emulate_framebuffer scans out the DC framebuffer directly on every VBlank (the 2D
+  // path, no TA list) — so simple homebrew that writes RGB565 pixels to VRAM presents
+  // reliably without building a full PowerVR2 tile list. (Threaded rendering is also
+  // force-disabled in the core itself; the option here is belt-and-suspenders.)
+  dreamcast: {
+    flycast_threaded_rendering: "disabled",
+    flycast_hle_bios: "enabled",
+    flycast_emulate_framebuffer: "enabled",
+  },
   // 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 +190,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,12 +276,74 @@ 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) {
+  /** Infer the platform from a core's js filename stem (e.g.
+   *  ".../parallel_n64_libretro.js" → "n64"), so loadCore can pre-seed that
+   *  platform's option overrides without the caller threading the platform
+   *  through. Covers the cores whose boot-time renderer choice depends on an
+   *  option; returns null otherwise (the overrides are then a no-op anyway). */
+  _platformForCore(jsPath) {
+    const stem = (jsPath.split("/").pop() || "").replace(/_libretro\.js$/, "");
+    return CORE_STEM_TO_PLATFORM[stem] ?? null;
+  }
+
+  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 });
+
+    // Pre-seed per-platform core-option overrides BEFORE _retro_init. The core
+    // registers its variables (SET_VARIABLES) during retro_init and decides its
+    // renderer THEN — e.g. parallel_n64 reads `parallel-n64-gfxplugin` to pick
+    // glide64 (GL/HW-render) vs angrylion (software). Seeding the override here
+    // (not in loadMedia, which is too late) makes the SET_VARIABLES handler keep
+    // our value instead of the core's default, so HW render engages from boot.
+    const platform = opts.platform ?? this._platformForCore(jsPath);
+    if (platform) {
+      const overrides = PLATFORM_CORE_OPTIONS[platform];
+      if (overrides) {
+        for (const [key, value] of Object.entries(overrides)) {
+          this.state.coreVariables.set(key, { value });
+        }
+        this.state.variablesUpdated = true;
+      }
+    }
+
     mod._retro_init();
     this.status.corePath = jsPath;
   }
@@ -430,8 +527,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 +588,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 +629,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 +639,25 @@ 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;
+      // Crop the GL FBO to the core's reported active resolution (e.g. DC 640x480 in an
+      // 853x853 FBO) so screenshots don't carry the dead viewport border.
+      const frame = this.hwRender.readbackFrame(this.state.hwFrameW, this.state.hwFrameH);
+      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 +666,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 +951,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 +1523,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,21 @@ 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;
+      // Remember the core's reported active resolution (e.g. DC 640x480) so the
+      // readback can crop the (often larger, e.g. 853x853) GL FBO to just the
+      // rendered region instead of returning the whole viewport with dead borders.
+      if (w > 0 && h > 0) { state.hwFrameW = w; state.hwFrameH = h; }
+      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 +443,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);
@@ -33,12 +37,68 @@ export async function loadLibretroCore(args) {
 
   /** @type {Record<string, unknown>} */
   const opts = {
-    noInitialRun: true,
-    print: () => {},
-    printErr: () => {},
+    print: process.env.ROMDEV_CORE_LOG ? (s) => console.error("[core]", s) : () => {},
+    printErr: process.env.ROMDEV_CORE_LOG ? (s) => console.error("[core:err]", s) : () => {},
   };
-  if (wasmPath) {
+  // The cores are linked with INVOKE_RUN=0, so main() never auto-runs regardless.
+  // Do NOT set noInitialRun on GL (canvas) cores: it suppresses the Emscripten GL
+  // runtime init, so `Module.GL` (and thus the WebGL2/native-gles context the core's
+  // SET_HW_RENDER path needs) is never created. For non-GL cores it's harmless either
+  // way; we set it only there to keep their startup identical to before.
+  if (!glCanvas) opts.noInitialRun = true;
+
+  // 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 && !glCanvas) {
     opts.wasmBinary = await readFile(wasmPath);
+  } else if (wasmPath && glCanvas) {
+    // GL (canvas) cores: do NOT hand Emscripten a pre-read wasmBinary. Passing it
+    // routes instantiation through a path that skips the GL runtime init, so
+    // `Module.GL` (the WebGL2/native-gles context the SET_HW_RENDER path needs) is
+    // never created. Let Emscripten locate `<name>.wasm` next to the `.js` itself
+    // (via locateFile) — the same way retroemu loads parallel_n64/flycast.
+    const wasmDir = wasmPath.slice(0, wasmPath.lastIndexOf("/") + 1);
+    opts.locateFile = (file) => wasmDir + file;
   }
 
   const mod = await factory(opts);

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,
+  };
+}