romdevtools 0.56.1 → 0.71.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
@@ -55,6 +66,24 @@ const PLATFORM_CORE_OPTIONS = {
   // 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
@@ -135,6 +164,29 @@ function mirrorDirToFS(FS, hostDir, fsDir) {
   }
 }
 
+/** Mirror a host dir into a PROXIED core's APP-THREAD MEMFS (a per-thread JS heap, invisible to
+ *  the main-thread FS). Each file's bytes go through shared WASM memory; romdev_app_fs_write does
+ *  the FS.writeFile on the app thread, where the core's fopen runs. */
+function mirrorDirToAppFS(mod, hostDir, fsDir) {
+  for (const name of readdirSync(hostDir)) {
+    const hostPath = path.join(hostDir, name);
+    const fsPath = fsDir + "/" + name;
+    const st = statSync(hostPath);
+    if (st.isDirectory()) {
+      mirrorDirToAppFS(mod, hostPath, fsPath);
+    } else if (st.isFile()) {
+      const bytes = readFileSync(hostPath);
+      const dataPtr = mod._malloc(bytes.length || 1);
+      mod.HEAPU8.set(bytes, dataPtr);
+      const pb = Buffer.from(fsPath + "\0", "utf-8");
+      const pathPtr = mod._malloc(pb.length);
+      mod.HEAPU8.set(pb, pathPtr);
+      try { mod._romdev_app_fs_write(pathPtr, dataPtr, bytes.length); } catch { /* skip */ }
+      mod._free(dataPtr); mod._free(pathPtr);
+    }
+  }
+}
+
 /**
  * When loadMedia is called with `bytes:` and no `virtualName`, this is
  * the extension we tack onto "/rom" so the core knows which platform
@@ -252,11 +304,29 @@ export class LibretroHost {
    *   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.
    */
+  /** 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");
 
+    // Proxied (multi-threaded) cores — e.g. PPSSPP/PSP — run on a dedicated "app thread" so the
+    // JS main thread never blocks while the core's worker threads proxy back to it (which would
+    // deadlock the synchronous frame-stepping). They own the ENTIRE GL stack on the app thread
+    // (native-gles + webgl-node loaded + context created + readback all there). The registry
+    // marks them; the single-threaded GL cores keep the main-thread GL path below.
+    this._proxied = !!opts.proxied;
+    this.state.proxied = this._proxied;
+
     let glCanvas = null;
-    if (opts.hwRender) {
+    if (opts.hwRender && !this._proxied) {
       // 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).
@@ -278,16 +348,83 @@ export class LibretroHost {
     const mod = await loadLibretroCore({ jsPath, wasmPath, glCanvas });
     this.mod = mod;
 
-    // Canvas HW-render cores: initialize the Emscripten GL context so `GLctx` is
+    if (this._proxied) {
+      // Spawn the app thread, then build the whole GL stack on it (native-gles + webgl-node +
+      // the Emscripten GL context). 480x272 is PSP native; the readback crops per-frame.
+      if (typeof mod._romdev_proxy_init !== "function") {
+        throw new Error("core marked proxied but missing _romdev_proxy_init export");
+      }
+      mod._romdev_proxy_init();
+      // Confirm the app thread's event loop is actually SERVICING its proxy queue before driving
+      // it — app_ready is set by a proxied ping (ping_on_app), which only runs once the queue is
+      // live. Setting it eagerly would race: a proxied call issued before the loop pumps would sit
+      // unprocessed and a proxy_sync would hang main. Pump + yield so the async ping is delivered.
+      mod._romdev_app_ping();
+      while (mod._romdev_app_ready() !== 1) {
+        mod._romdev_pump_main_queue();
+        await new Promise((r) => setTimeout(r, 0));
+      }
+      if (opts.hwRender) {
+        // Async GL setup: the app thread imports native-gles/webgl-node + creates the context,
+        // which needs the main JS event loop. So kick it async + poll while yielding (a blocking
+        // proxy_sync would freeze the event loop the import() depends on → deadlock).
+        mod._romdev_proxied_gl_setup_start(480, 272);
+        while (mod._romdev_gl_setup_phase() !== 2) {
+          await new Promise((r) => setTimeout(r, 0));
+        }
+        if (mod._romdev_gl_setup_result() !== 1) {
+          throw new Error("proxied GL setup failed on the app thread");
+        }
+      }
+    }
+
+    // Canvas HW-render cores (non-proxied): 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);
+      {
+        const handle = mod.GL.createContext(glCanvas, { majorVersion: 2 });
+        if (handle > 0) mod.GL.makeContextCurrent(handle);
+      }
+    }
+
+    if (this._proxied) {
+      // Proxied cores: install the JS callback impls on Module (the C trampolines proxy each
+      // callback from the app thread back to main to run these). Register the trampolines on
+      // MAIN — they're plain C function pointers the app thread can call, and retro_init/
+      // pthread_create must run on main (Worker allocation proxies to main; it'd deadlock if
+      // main were blocked proxying init to the app thread). Only load_game/run proxy to app.
+      const { registerProxiedCallbacks } = await import("./callbacks.js");
+      registerProxiedCallbacks({ mod, state: this.state, log: this.log });
+      mod._romdev_register_callbacks();
+    } else {
+      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;
+      }
     }
 
-    registerCallbacks({ mod, state: this.state, log: this.log });
-    mod._retro_init();
+    // retro_init runs on MAIN even for proxied cores (it spawns the threadManager workers via
+    // pthread_create, which needs the main thread free — not blocked proxying init to app).
+    // EXCEPT proxied cores defer it to loadMedia: PPSSPP's retro_init touches the system dir
+    // (fonts/flash0), which for proxied cores is only mirrored into the app-thread FS during
+    // loadMedia — calling retro_init before the mount makes the loader hang on missing assets.
+    if (!this._proxied) mod._retro_init();
+    else this._retroInitPending = true;
     this.status.corePath = jsPath;
   }
 
@@ -307,6 +444,10 @@ export class LibretroHost {
   async loadMedia(args) {
     const mod = this._needMod();
     const { platform } = args;
+    // Allow the systemDir to be supplied per-load (not just via the constructor) — proxied cores
+    // (PSP) need it to mirror BIOS/font assets into the app-thread FS, and callers commonly pass
+    // it to loadMedia rather than at construction.
+    if (args.systemDir && !this.systemDir) this.systemDir = args.systemDir;
     // Derive the kind from the file/virtual extension when the caller didn't say
     // — so a C64 .d64 reports mediaKind:"disk" (writable save target) vs a .prg
     // "program". For an in-memory load, the virtualName carries the ext.
@@ -340,7 +481,13 @@ export class LibretroHost {
     if (this.systemDir && !this._systemDirMounted && mod.FS) {
       try {
         const FS_SYS = "/system";
-        mirrorDirToFS(mod.FS, this.systemDir, FS_SYS);
+        // Proxied cores read the system dir on the app thread (separate per-thread MEMFS); mirror
+        // ONLY there. Non-proxied cores read main's FS. (Mirroring to both is wasted work.)
+        if (this._proxied) {
+          mirrorDirToAppFS(mod, this.systemDir, FS_SYS);
+        } else {
+          mirrorDirToFS(mod.FS, this.systemDir, FS_SYS);
+        }
         // Redirect the core's reported system dir to the in-FS copy.
         if (this.state) this.state.systemDir = FS_SYS;
         this._systemDirMounted = true;
@@ -373,7 +520,10 @@ export class LibretroHost {
       throw new Error("loadMedia requires either `path` or `bytes`");
     }
     const vfsPath = "/rom" + ext;
-    if (mod.FS) {
+    // For proxied cores the core fopen's on the app thread, so the ROM goes to the app-thread
+    // MEMFS below (romdev_app_fs_write) — writing it to the main-thread FS too is wasted work
+    // (and for a 60MB ISO, a needless copy). Non-proxied cores read main's FS directly.
+    if (mod.FS && !this._proxied) {
       try {
         mod.FS.writeFile(vfsPath, data);
       } catch (e) {
@@ -391,6 +541,14 @@ export class LibretroHost {
     const pathPtr = mod._malloc(pathBytes.length);
     mod.HEAPU8.set(pathBytes, pathPtr);
 
+    // Proxied cores run on the app thread, whose MEMFS is a SEPARATE (per-thread) JS heap — the
+    // main-thread FS.writeFile above is invisible there. PPSSPP fopen's the path on the app
+    // thread, so write the ROM into the app thread's MEMFS too (the bytes are already in shared
+    // WASM memory at dataPtr).
+    if (this._proxied) {
+      mod._romdev_app_fs_write(pathPtr, dataPtr, data.length);
+    }
+
     // retro_game_info struct (16 bytes on wasm32).
     const infoPtr = mod._malloc(16);
     mod.setValue(infoPtr + 0, pathPtr, "i32");
@@ -398,7 +556,38 @@ export class LibretroHost {
     mod.setValue(infoPtr + 8, data.length, "i32");
     mod.setValue(infoPtr + 12, 0, "i32"); // meta = null
 
-    const ok = mod._retro_load_game(infoPtr);
+    // Proxied cores: run retro_load_game on the app thread ASYNCHRONOUSLY (it creates the GL
+    // context + spawns the core's worker threads there). We kick it async then poll the done
+    // flag while YIELDING to the JS event loop — the event loop must keep turning so emscripten
+    // can service the app-thread's pooled-Worker grabs / postMessage wakeups. A blocking call
+    // would freeze the event loop → the core's threads can't be scheduled → deadlock.
+    let ok;
+    if (this._proxied) {
+      // Deferred retro_init (see loadCore): now that the system dir is mirrored into the app-thread
+      // FS, the core can init (fonts/flash0 present) without hanging.
+      if (this._retroInitPending) {
+        mod._retro_init();
+        this._retroInitPending = false;
+      }
+      mod._romdev_proxied_load_game_start(infoPtr);
+      while (mod._romdev_proxied_load_state() === 0) {
+        mod._romdev_pump_main_queue();         // run callbacks the app thread proxied to main
+        await new Promise((r) => setTimeout(r, 0)); // yield → emscripten services worker ops
+      }
+      ok = mod._romdev_proxied_load_state() === 1;
+      // NOTE: PPSSPP's ContextReset (creates DrawContext + GPU) must run for rendering — without it
+      // gpu/draw are null and EmuFrame renders nothing (the blank-frame root cause). Firing it here
+      // currently heap-corrupts inside the GL render-manager construction (under investigation), so
+      // it's disabled for now; the core loads + runs stably without it (CPU/audio work, no video).
+      // ContextReset (creates GPU/DrawContext) survives intermittently after the webgl-node
+      // MAX_UNIFORM_BLOCK_SIZE fix but still hits a non-deterministic native-heap corruption in
+      // PPSSPP's GL init — disabled until that's pinned (ASAN). Core loads + runs without it.
+      if (ok && this.state.proxiedContextResetPtr) {
+        mod._romdev_proxied_fire_context_reset(this.state.proxiedContextResetPtr);
+      }
+    } else {
+      ok = mod._retro_load_game(infoPtr);
+    }
 
     // Free the struct itself. Don't free pathPtr or dataPtr — the core may
     // retain pointers into them for the life of the loaded game.
@@ -455,7 +644,10 @@ export class LibretroHost {
     //   };
     // };
     const avInfoPtr = mod._malloc(64);
-    mod._retro_get_system_av_info(avInfoPtr);
+    // Proxied cores keep core state on the app thread; retro_get_system_av_info reads it, so it
+    // must run there (a direct main-thread call reads garbage / can wedge). Proxy it.
+    if (this._proxied) mod._romdev_proxied_av_info(avInfoPtr);
+    else mod._retro_get_system_av_info(avInfoPtr);
     this.status.fbWidth = mod.getValue(avInfoPtr + 0, "i32");
     this.status.fbHeight = mod.getValue(avInfoPtr + 4, "i32");
     // aspect_ratio (+16) is the intended DISPLAY aspect (what a CRT would
@@ -483,11 +675,17 @@ export class LibretroHost {
       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)
-    // only reads RetroPad port 1 when it's registered as a joypad device.
-    mod._retro_set_controller_port_device(1, RETRO_DEVICE_JOYPAD);
+    // Configure controller port 0 as joypad (some cores default to NONE). Proxied cores touch
+    // core state on the app thread, so proxy it there.
+    if (this._proxied) {
+      mod._romdev_proxied_set_controller(0, RETRO_DEVICE_JOYPAD);
+      mod._romdev_proxied_set_controller(1, RETRO_DEVICE_JOYPAD);
+    } else {
+      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)
+      // only reads RetroPad port 1 when it's registered as a joypad device.
+      mod._retro_set_controller_port_device(1, RETRO_DEVICE_JOYPAD);
+    }
 
     // ---- Settle the framebuffer to the ROM's chosen geometry ----
     //
@@ -510,7 +708,10 @@ export class LibretroHost {
     // VDP in 1-3 frames; SNES in 1; NES in 1-2. The cost is ~5-30 ms
     // on loadMedia, paid once. Skip when loaded paused (caller is
     // already in control).
-    if (!this.status.paused) {
+    // Proxied cores (PSP) drive frames through the async run path (run_start + poll); the
+    // synchronous settle loop below uses the blocking sync run, so skip it. PSP geometry is the
+    // fixed 480×272 av_info already read, so there's no pre-init default to settle past.
+    if (!this.status.paused && !this._proxied) {
       // Settle frames are core warm-up, not agent-visible gameplay
       // frames — don't increment frameCount. From the agent's POV the
       // first stepFrames(N) should advance the count by exactly N.
@@ -530,7 +731,7 @@ export class LibretroHost {
       let stepped = 0;
       let firstRefreshAt = -1;
       while (stepped < MAX_SETTLE) {
-        mod._retro_run();
+        this._runCore();
         this._afterRun();
         stepped++;
         if (firstRefreshAt < 0 && this.state.lastFrame && this.state.lastFrame !== beforeRefreshSnapshot) {
@@ -567,11 +768,11 @@ export class LibretroHost {
    * @returns {number} frames actually run
    */
   stepFrames(n) {
-    const mod = this._needMod();
+    this._needMod();
     this._needMedia();
     if (this.status.paused) return 0;
     for (let i = 0; i < n; i++) {
-      mod._retro_run();
+      this._runCore();
       this._afterRun();
       this.status.frameCount++;
     }
@@ -582,13 +783,49 @@ export class LibretroHost {
     return n;
   }
 
+  /** Run one frame. Proxied cores route retro_run onto the app thread (so the JS main thread
+   *  stays free to service the core's worker-thread proxy calls); others call directly. */
+  _runCore() {
+    if (this._proxied) this.mod._romdev_proxied_run();
+    else this.mod._retro_run();
+  }
+
   /** 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._proxied) {
+      // Proxied cores own GL on the app thread; read the frame back THERE into a WASM buffer,
+      // then copy it out here. The core reports its size via video_refresh (hwFrameW/H).
+      if (this.state.hwFramePending) {
+        this.state.hwFramePending = false;
+        const w = this.state.hwFrameW || 480, h = this.state.hwFrameH || 272;
+        const mod = this.mod;
+        const n = w * h * 4;
+        if (!this._pxBuf || this._pxBufN !== n) {
+          if (this._pxBuf) mod._free(this._pxBuf);
+          this._pxBuf = mod._malloc(n); this._pxBufN = n;
+        }
+        mod._romdev_proxied_readback(w, h, this._pxBuf);
+        // native-gles is bottom-left origin → flip vertically into lastFrame.
+        const src = mod.HEAPU8.subarray(this._pxBuf, this._pxBuf + n);
+        const pixels = new Uint8Array(n);
+        const rowBytes = w * 4;
+        for (let y = 0; y < h; y++) {
+          pixels.set(src.subarray((h - 1 - y) * rowBytes, (h - y) * rowBytes), y * rowBytes);
+        }
+        this.state.lastFrame = {
+          width: w, height: h, pitch: rowBytes,
+          format: ROMDEV_PIXEL_FORMAT_RGBA8888, pixels, rgba: true,
+        };
+      }
+      return;
+    }
     if (this.state.hwFramePending && this.hwRender?.active) {
       this.state.hwFramePending = false;
-      const frame = this.hwRender.readbackFrame();
+      // 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,
@@ -604,9 +841,9 @@ export class LibretroHost {
    *  playtest loop can't race). Advances the (monotonic) frame counter by 1.
    *  Returns the frame count after. */
   renderOneFrame() {
-    const mod = this._needMod();
+    this._needMod();
     this._needMedia();
-    mod._retro_run();
+    this._runCore();
     this._afterRun();
     this.status.frameCount++;
     if (this.state.lastFrame) {
@@ -1484,6 +1721,47 @@ export class LibretroHost {
     }
   }
 
+  /** True when the Dreamcast core (flycast) exposes the live SH-4 register block. */
+  sh4RegsSupported() {
+    return !!(this.mod && typeof this.mod._romdev_sh4_regs_get === "function");
+  }
+
+  /** Read the live SH-4 register block as a Uint32Array(24):
+   *  [0..15]=r0..r15, 16=pc, 17=pr, 18=gbr, 19=vbr, 20=sr, 21=mac.l, 22=mac.h, 23=fpul.
+   *  null if the core doesn't expose it. */
+  getSh4Regs() {
+    const mod = this.mod;
+    if (!mod || typeof mod._romdev_sh4_regs_get !== "function") return null;
+    const ptr = mod._malloc(24 * 4);
+    try {
+      mod._romdev_sh4_regs_get(ptr);
+      return new Uint32Array(mod.HEAPU8.buffer, ptr, 24).slice();
+    } finally {
+      mod._free(ptr);
+    }
+  }
+
+  /** True when the Dreamcast core exposes the AICA register file
+   *  (getAudioState chip:'aica'). */
+  aicaRegsSupported() {
+    return !!(this.mod && typeof this.mod._romdev_aica_get === "function");
+  }
+
+  /** Read the AICA register window (channels + CommonData) as a Uint8Array.
+   *  Default 0x3000 bytes (64 SGC channel blocks @ 0x80 each + CommonData @ 0x2800).
+   *  null if the core doesn't expose it. */
+  getAicaRegs(bytes = 0x3000) {
+    const mod = this.mod;
+    if (!mod || typeof mod._romdev_aica_get !== "function") return null;
+    const ptr = mod._malloc(bytes);
+    try {
+      mod._romdev_aica_get(ptr, bytes);
+      return new Uint8Array(mod.HEAPU8.buffer, ptr, bytes).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");
@@ -1711,7 +1989,7 @@ export class LibretroHost {
    * @returns {number} frames actually run
    */
   _runFramesExclusive(body, maxFrames) {
-    const mod = this._needMod();
+    this._needMod();
     // Suspend ONLY the playtest window's render-tick stepping for the duration —
     // not `status.paused` (the agent's pause is a separate concept, and the core
     // run must be identical whether or not the user paused). The playtest tick
@@ -1722,7 +2000,7 @@ export class LibretroHost {
     let framesRun = 0;
     try {
       for (let i = 0; i < maxFrames; i++) {
-        mod._retro_run();
+        this._runCore();
         this.status.frameCount++;
         framesRun++;
         if (body(i)) break;

package/src/host/callbacks.js

@@ -170,8 +170,12 @@ export function registerCallbacks(args) {
     // 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) {
+    if (uPtr === RETRO_HW_FRAME_BUFFER_VALID && (state.hwRender?.active || state.proxied)) {
       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;
@@ -224,6 +228,49 @@ export function registerCallbacks(args) {
   mod._retro_set_input_state(inputStateCb);
 }
 
+/**
+ * Proxied (app-thread) cores: the C shim registers C trampolines with the core that proxy each
+ * callback back to the MAIN thread to run these JS impls. So instead of addFunction (which binds
+ * a closure to the calling thread and can't be invoked from the app thread), we install the JS
+ * impls as Module fns the trampolines call via EM_ASM. Same bodies as registerCallbacks, minus
+ * the addFunction/retro_set_* (the shim does those on the app thread).
+ */
+export function registerProxiedCallbacks(args) {
+  const { mod, state, log } = args;
+
+  mod.romdev_envCb = (cmd, dataPtr) => (handleEnv(mod, state, cmd, dataPtr, log) ? 1 : 0);
+
+  mod.romdev_videoCb = (dataPtr, w, h, pitch) => {
+    const uPtr = dataPtr >>> 0;
+    if (uPtr === RETRO_HW_FRAME_BUFFER_VALID && (state.hwRender?.active || state.proxied)) {
+      state.hwFramePending = true;
+      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 = { width: w, height: h, pitch, format: state.pixelFormat, pixels: new Uint8Array(view) };
+  };
+
+  mod.romdev_audioBatchCb = (dataPtr, frames) => {
+    if (dataPtr === 0 || frames === 0) return frames;
+    const byteLen = frames * 2 * 2;
+    const samples = new Int16Array(mod.HEAPU8.buffer, dataPtr, byteLen / 2).slice();
+    state.audioRing.push(samples);
+    return frames;
+  };
+
+  mod.romdev_inputCb = (port, device, _idx, id) => {
+    if (device === 3) return state.keysDown.has(id) ? 1 : 0;
+    const portBits = state.inputPorts[port];
+    if (!portBits) return 0;
+    const bits = portBits[0];
+    if (id === 256) return bits;
+    return bits & (1 << id) ? 1 : 0;
+  };
+}
+
 function allocString(mod, state, str) {
   const bytes = Buffer.from(str + "\0", "utf-8");
   const ptr = mod._malloc(bytes.length);
@@ -296,6 +343,19 @@ function handleEnv(mod, state, rawCmd, dataPtr, log) {
       // already a useful diagnostic — most cores pass a fully-formed message
       // (no varargs substitution needed) or a message + N args we can't decode.
       // Read the fmt as-is so log output is actually readable.
+      // Proxied cores call the log callback from the app thread, so it must be a C function
+      // pointer (a main-thread addFunction is a bad table index there). The shim's romdev_log_cb
+      // routes to Module.romdev_logCb (installed below).
+      if (state.proxied) {
+        mod.romdev_logCb = (level, fmtPtr) => {
+          if (!log) return;
+          let msg = "<unreadable>";
+          try { msg = mod.UTF8ToString(fmtPtr); } catch { /* */ }
+          log(level, msg);
+        };
+        mod.setValue(dataPtr, mod._romdev_log_cb_ptr(), "i32");
+        return true;
+      }
       if (!state._logCbPtr) {
         state._logCbPtr = mod.addFunction((level, fmtPtr, _vaPtr) => {
           if (!log) return;
@@ -444,6 +504,17 @@ function handleEnv(mod, state, rawCmd, dataPtr, log) {
     // 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);
+      // Proxied cores own GL on the app thread. Fill the retro_hw_render_callback struct with
+      // C function pointers (valid on the app thread, unlike main-thread addFunction): the core
+      // reads context_reset (+4) itself; we write get_current_framebuffer (+8) + get_proc_address
+      // (+12) from the shim. bottom_left_origin (+18) is true for GL.
+      if (state.proxied) {
+        state.proxiedContextResetPtr = mod.getValue(dataPtr + 4, "i32");
+        mod.setValue(dataPtr + 8, mod._romdev_hw_get_fb_ptr(), "i32");
+        mod.setValue(dataPtr + 12, mod._romdev_hw_get_proc_ptr(), "i32");
+        state.proxiedBottomLeft = !!mod.HEAPU8[dataPtr + 18];
+        return true;
+      }
       return false;
 
     // Things we can't or don't want to support — reject so core falls back.

package/src/host/coreLoader.js

@@ -37,10 +37,15 @@ 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) : () => {},
   };
+  // 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.
@@ -84,8 +89,16 @@ export async function loadLibretroCore(args) {
       });
       return {};
     };
-  } else if (wasmPath) {
+  } 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

@@ -163,6 +163,35 @@ function decodeMips(regs) {
   };
 }
 
+/** Decode the SH-4 register block (Dreamcast) from getSh4Regs():
+ *  [0..15]=r0..r15, 16=pc, 17=pr, 18=gbr, 19=vbr, 20=sr, 21=mac.l, 22=mac.h, 23=fpul. */
+function decodeSh4(regs) {
+  if (!regs || regs.length < 24) return null;
+  const hx = (v) => "$" + (v >>> 0).toString(16).toUpperCase().padStart(8, "0");
+  const named = {};
+  for (let i = 0; i < 16; i++) named["r" + i] = hx(regs[i]);
+  named.pr = hx(regs[17]);
+  named.gbr = hx(regs[18]);
+  named.vbr = hx(regs[19]);
+  named.sr = hx(regs[20]);
+  named.macl = hx(regs[21]);
+  named.mach = hx(regs[22]);
+  named.fpul = hx(regs[23]);
+  // SR flags: T(0) S(1) Q(8) M(9) BL(28) RB(29) MD(30)
+  const sr = regs[20] >>> 0;
+  return {
+    pc: regs[16] >>> 0,
+    pcHex: hx(regs[16]),
+    registers: named,
+    flags: {
+      T: !!(sr & 0x1), S: !!(sr & 0x2),
+      Q: !!(sr & 0x100), M: !!(sr & 0x200),
+      BL: !!(sr & 0x10000000), RB: !!(sr & 0x20000000), MD: !!(sr & 0x40000000),
+      raw: hx(sr),
+    },
+  };
+}
+
 function decode6502(bytes) {
   if (!bytes || bytes.length < 25) return null;
   const u16le = (o) => bytes[o] | (bytes[o + 1] << 8);
@@ -327,6 +356,9 @@ export function getCPUState(host, platform, cpu = "main") {
   if (platform === "n64" || platform === "ps1") {
     return decodeMips(host.getMipsRegs?.());
   }
+  if (platform === "dreamcast") {
+    return decodeSh4(host.getSh4Regs?.());
+  }
   if (platform === "nes") {
     const bytes = host.readMemory("nes_cpu_regs", 0, 28);
     return decode6502(bytes);