@wasm-gaming/rsdkv4-wasm 0.1.5 → 0.2.1

package/dist/rsdkv4/rsdkv4.sdk.js

@@ -1,55 +1,113 @@
-// @wasm-gaming/rsdkv4-wasm — SDK entry point.
-//
-// Conforms to the wasm-gaming engine contract (github.com/wasm-gaming/engine-specs):
-// exports `manifest` (declarative) and `load(config)` (imperative).
-//
-// One game-agnostic rsdkv4.wasm runs both Sonic 1 and Sonic 2 — the difference is
-// only which Data.rsdk the host hands us in `config.assets.data`, written into the
-// filesystem at runtime (not baked with --preload-file).
-//
-// Filesystem: built with -sWASMFS (the modern Emscripten filesystem, not MEMFS).
-// The game working dir `/data` is mounted on **OPFS** for persistence when the
-// page is cross-origin isolated *and* the wasm build can create the OPFS backend
-// from the main thread (an Asyncify/JSPI build — today's is not, see WebFS.cpp);
-// otherwise it falls back to the WASMFS in-memory backend (transient, but the
-// engine still boots). The backend is selectable via
-// `config.persist` (see mountWorkingDir), and when the dir is OPFS-backed the SDK
-// reuses an already-persisted Data.rsdk/settings.ini instead of re-fetching.
-import { manifest } from './rsdkv4.manifest.js';
-import { DEFAULT_RSDKV4_OPTIONS } from './rsdkv4.options.js';
-export { manifest };
+/**
+ * The engine package's entry point: an `EngineSDK` for RSDKv4.
+ *
+ * ```ts
+ * import Rsdkv4SDK from '@wasm-gaming/rsdkv4-wasm';
+ *
+ * const play = await new Rsdkv4SDK()
+ *   .mount(document.querySelector('#stage'))
+ *   .assets({ data: () => library.readBytes('Sonic2') })
+ *   .storage({ namespace: 'rsdkv4/Sonic2' })
+ *   .config({ startMenu: 'host' })
+ *   .on('saves', ({ detail }) => paintSlots(detail))
+ *   .start({ slot: 0 });
+ * ```
+ *
+ * Everything a host drives is the contract's, and documented there: the four payloads
+ * with their descriptors, `mount`, `on`/`off`, `start`, `restart`, `destroy`. What is
+ * this engine's own lives in two places — {@link Rsdkv4Config} and friends, which say
+ * what the payloads accept *here*, and the extra members of {@link Rsdkv4Play} below:
+ * {@link Rsdkv4Play.game} and {@link Rsdkv4Play.devMenu}, for a host that draws
+ * RSDKv4's start screens itself, owner-aware {@link Rsdkv4Play.pause}, and
+ * {@link Rsdkv4Play.input}, for a host that would rather drive the buttons than let
+ * the engine read the keyboard.
+ *
+ * One game-agnostic `rsdkv4.wasm` runs both Sonic 1 and Sonic 2 — the difference is
+ * only which `Data.rsdk` the host hands over in `assets.data`, written into the
+ * filesystem at runtime (not baked with `--preload-file`).
+ *
+ * Filesystem: built with `-sWASMFS`. The working dir is mounted on **OPFS** when the
+ * page is cross-origin isolated *and* the build can create the OPFS backend from the
+ * main thread (an Asyncify/JSPI build — today's is not, see `WebFS.cpp`); otherwise it
+ * falls back to the WASMFS in-memory backend, which boots fine but forgets everything.
+ * That fallback is why the SDK mirrors `SData.bin` into OPFS itself: see
+ * {@link Rsdkv4Storage.persist}.
+ *
+ * @module
+ * @see [The engine contract](https://wasm-gaming.github.io/engine-specs/api-docs/)
+ */
+import { EnginePlayBase, EngineSDKBase, EventEmitter } from '@wasm-gaming/engine-specs';
+import { RSDKV4_BUTTONS, RSDKV4_SPEC, } from './rsdkv4.options.js';
+export { RSDKV4_BUTTONS, RSDKV4_INPUT, RSDKV4_SPEC } from './rsdkv4.options.js';
 const WORK_ROOT = '/data';
 const DEFAULT_STORAGE_NAMESPACE = 'default';
+/** RSDKv4's save file, written next to the game data in the working dir. */
+const SAVE_FILE = 'SData.bin';
 /**
  * Emscripten's SDL2 port locates the canvas via `document.querySelector('#canvas')`,
  * so the element the game draws into has to carry this id.
  */
 const CANVAS_ID = 'canvas';
 /**
- * Serialize engine options into RSDKv4's settings.ini format.
+ * The picture's native size, which is what the SDK scales to fit its mount.
  *
- * Note the Starting* trio defaults to 255 ("unset") — writing 0 is not neutral,
- * it tells the engine to skip its start-menu flow and force that stage. See
- * DEFAULT_RSDKV4_OPTIONS.
+ * A module constant rather than a manifest field: `EngineManifest` left the contract
+ * in 0.3.0, and this was one of only two things the SDK ever read back out of it.
  */
-function buildSettingsIni(options = {}) {
-    const o = { ...DEFAULT_RSDKV4_OPTIONS, ...options };
-    return [
-        '[Dev]',
-        `EngineDebugMode=${o.engineDebugMode ? 'true' : 'false'}`,
-        `DevMenu=${o.devMenu ? 'true' : 'false'}`,
-        `StartingCategory=${o.startingCategory | 0}`,
-        `StartingScene=${o.startingScene | 0}`,
-        `StartingPlayer=${o.startingPlayer | 0}`,
-        '',
-        '[Game]',
-        `SkipStartMenu=${o.skipStartMenu ? 'true' : 'false'}`,
-        '',
-        '[Window]',
-        `VSync=${o.vsync ? 'true' : 'false'}`,
-        '',
-    ].join('\n');
-}
+export const RSDKV4_VIDEO = { baseWidth: 424, baseHeight: 240, aspect: '16:9' };
+/**
+ * The embind bridges this SDK drives the engine through. All of them ship in the same
+ * rsdkv4.wasm, so a module missing any one of them is an artifact older than this SDK
+ * rather than a build variant.
+ */
+const ENGINE_BRIDGES = [
+    'web_engine_ready',
+    'web_game_type',
+    'web_get_players',
+    'web_get_save_slots',
+    'web_get_game_options',
+    'web_start_game',
+    'web_audio_stop',
+    'web_devmenu_get_stage_list',
+    'web_devmenu_open',
+    'web_input_set_source',
+];
+/**
+ * The name the engine's `web_input_pull()` looks the reader up under, on the module
+ * object itself rather than on a global: two engines on one page have two modules,
+ * and a global would have them fighting over one claim.
+ */
+const INPUT_PULL_HOOK = '__rsdkv4_input_pull';
+/** How often a pull that keeps throwing is allowed to say so. See {@link Rsdkv4Play}. */
+const INPUT_ERROR_INTERVAL_MS = 1000;
+/**
+ * Keys whose browser default action is swallowed while the canvas has focus — the
+ * arrows and Space scroll the page under the game, Tab takes the focus off the canvas
+ * and with it every key the engine was reading.
+ *
+ * Both `KeyboardEvent.code` and `.key` spellings are in here because the set is
+ * matched against each: `code` is the physical key (layout-independent, which is what
+ * the engine binds), `key` is what it produced, and a browser or a remapping tool that
+ * reports only one of the two still lands.
+ *
+ * WASD is included because this build's `ProcessInput()` reads those scancodes as a
+ * second set of directions. They have no default action to prevent today, so this
+ * costs nothing and stops mattering the day the page grows a shortcut on one of them.
+ */
+const ENGINE_KEYS = new Set([
+    'ArrowUp',
+    'ArrowDown',
+    'ArrowLeft',
+    'ArrowRight',
+    'KeyW',
+    'KeyA',
+    'KeyS',
+    'KeyD',
+    'Space',
+    ' ',
+    'Tab',
+]);
+// ---------------------------------------------------------------- small helpers
 function toUint8(x) {
     if (x == null)
         return null;
@@ -61,9 +119,15 @@ function toUint8(x) {
         return new Uint8Array(x);
     if (ArrayBuffer.isView(x))
         return new Uint8Array(x.buffer, x.byteOffset, x.byteLength);
-    throw new TypeError('asset must be Uint8Array | ArrayBuffer | string');
+    throw new TypeError('rsdkv4: an asset must be Uint8Array | ArrayBuffer | string');
+}
+/** Bytes for an asset, calling the thunk form only when we get this far. */
+async function resolveAsset(asset) {
+    if (asset == null)
+        return null;
+    return toUint8(typeof asset === 'function' ? await asset() : asset);
 }
-/** Normalize a user-provided storage namespace into a safe relative path. */
+/** Normalize a host-provided storage namespace into a safe relative path. */
 function normalizeStorageNamespace(namespace) {
     if (typeof namespace !== 'string' || !namespace.trim())
         return DEFAULT_STORAGE_NAMESPACE;
@@ -76,6 +140,51 @@ function normalizeStorageNamespace(namespace) {
         .join('/');
     return cleaned || DEFAULT_STORAGE_NAMESPACE;
 }
+/** The plain values behind a descriptor table — what the engine actually needs. */
+function valuesOf(described) {
+    const out = {};
+    for (const [key, property] of Object.entries(described)) {
+        out[key] = property.value;
+    }
+    return out;
+}
+/**
+ * Serialize {@link Rsdkv4Config} into RSDKv4's settings.ini format.
+ *
+ * The `Starting*` trio is written as 255 — the engine's "unset" — and never anything
+ * else. That is not a leftover: anything else there, **including 0**, makes
+ * `Engine::Init` skip its normal boot flow and force a stage (see Userdata.cpp). The
+ * session's own `stage` is applied after boot instead, through the engine's stage
+ * loader, which is why it survives a `restart()`.
+ */
+function buildSettingsIni(config) {
+    return [
+        '[Dev]',
+        `EngineDebugMode=${config.engineDebugMode ? 'true' : 'false'}`,
+        `DevMenu=${config.devMenu ? 'true' : 'false'}`,
+        'StartingCategory=255',
+        'StartingScene=255',
+        'StartingPlayer=255',
+        '',
+        '[Game]',
+        `SkipStartMenu=${config.startMenu === 'host' ? 'true' : 'false'}`,
+        '',
+        '[Window]',
+        `VSync=${config.vsync ? 'true' : 'false'}`,
+        '',
+    ].join('\n');
+}
+function sameBytes(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i += 1)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+// ---------------------------------------------------------------- the wasm filesystem
 /** Best-effort mkdir -p for the Emscripten FS layer. */
 function ensureDir(Module, path) {
     const parts = path.split('/').filter(Boolean);
@@ -90,15 +199,25 @@ function ensureDir(Module, path) {
         }
     }
 }
+/** True if `path` exists in the (mounted) filesystem. */
+function fileExists(Module, path) {
+    try {
+        Module.FS.stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Whether this build can mount OPFS at all, asked of the wasm itself.
  *
- * WASMFS's `wasmfs_create_opfs_backend()` spawns a proxy worker synchronously,
- * which it refuses to do on the main browser thread without Asyncify/JSPI — it
- * *asserts*, and a failed assert calls `abort()`, which tears the module down for
- * good. That is past the point where a try/catch around the call can save us, so
- * we have to know before calling. `web_opfs_supported` (WebFS.cpp) mirrors the
- * same condition; builds predating that helper simply answer "no".
+ * WASMFS's `wasmfs_create_opfs_backend()` spawns a proxy worker synchronously, which it
+ * refuses to do on the main browser thread without Asyncify/JSPI — it *asserts*, and a
+ * failed assert calls `abort()`, which tears the module down for good. That is past the
+ * point where a try/catch around the call can save us, so we have to know before
+ * calling. `web_opfs_supported` (WebFS.cpp) mirrors the same condition; builds predating
+ * that helper simply answer "no".
  */
 function opfsMountSupported(Module) {
     const probe = Module._web_opfs_supported;
@@ -112,16 +231,12 @@ function opfsMountSupported(Module) {
     }
 }
 /**
- * Mount the game working dir, honoring `persist`:
- *   'opfs'     → force an OPFS (persistent) mount; warn + fall back if unavailable.
- *   null       → force the in-memory WASMFS backend (the MEMFS-equivalent fallback).
- *   undefined  → auto: OPFS when the page is cross-origin isolated, else in-memory.
- * ('idbfs' isn't supported under WASMFS and is treated as in-memory.)
+ * Mount the game working dir, honouring {@link Rsdkv4Storage.persist}. Returns whether
+ * the resulting mount is persistent.
  *
- * Cross-origin isolation is necessary but not sufficient: the mount also needs a
- * build whose OPFS backend can run from where we call it (see opfsMountSupported),
- * so both gates apply before we touch `web_mount_opfs`.
- * Returns whether the resulting mount is persistent.
+ * Cross-origin isolation is necessary but not sufficient: the mount also needs a build
+ * whose OPFS backend can run from where we call it (see {@link opfsMountSupported}), so
+ * both gates apply before we touch `web_mount_opfs`.
  */
 function mountWorkingDir(Module, persist) {
     const isolated = typeof crossOriginIsolated !== 'undefined' && crossOriginIsolated;
@@ -142,20 +257,29 @@ function mountWorkingDir(Module, persist) {
     ensureDir(Module, WORK_ROOT);
     return { persistent: false };
 }
-/** True if `path` exists in the (mounted) filesystem. */
-function fileExists(Module, path) {
+/**
+ * OPFS handle for `<namespace>/`, reached with the plain (async) OPFS API from JS —
+ * which, unlike the WASM side's sync access handles, works on the main thread of any
+ * page. Returns null when OPFS isn't available at all.
+ */
+async function opfsNamespaceDir(namespace, create) {
+    if (typeof navigator === 'undefined' || !navigator.storage?.getDirectory)
+        return null;
     try {
-        Module.FS.stat(path);
-        return true;
+        let dir = await navigator.storage.getDirectory();
+        for (const segment of namespace.split('/').filter(Boolean)) {
+            dir = await dir.getDirectoryHandle(segment, { create });
+        }
+        return dir;
     }
     catch {
-        return false;
+        return null; // missing (create: false), or blocked
     }
 }
 /**
- * Wait for Engine::Init, which runs on the engine's first frame (main.cpp's
- * main_loop), not inside callMain. Gives up after ~4s rather than hanging the
- * host: everything still works, the first read just comes back empty.
+ * Wait for `Engine::Init`, which runs on the engine's first frame (main.cpp's
+ * main_loop), not inside `callMain`. Gives up after ~4s rather than hanging the host:
+ * everything still works, the first read just comes back empty.
  */
 async function waitForEngine(Module, timeoutMs = 4000) {
     if (typeof Module.web_engine_ready !== 'function')
@@ -169,416 +293,921 @@ async function waitForEngine(Module, timeoutMs = 4000) {
     console.warn('[rsdkv4] engine did not report ready within %dms', timeoutMs);
     return false;
 }
-/**
- * The embind bridges this SDK drives the engine through. All of them ship in the
- * same rsdkv4.wasm, so a module missing any one of them is an artifact older
- * than this SDK rather than a build variant.
- */
-const ENGINE_BRIDGES = [
-    'web_engine_ready',
-    'web_game_type',
-    'web_get_players',
-    'web_get_save_slots',
-    'web_get_game_options',
-    'web_start_game',
-    'web_audio_stop',
-    'web_devmenu_get_stage_list',
-];
 function engineBridgeComplete(Module) {
     return ENGINE_BRIDGES.every((name) => typeof Module?.[name] === 'function');
 }
-/** RSDKv4's save file, written next to the game data in the working dir. */
-const SAVE_FILE = 'SData.bin';
 /**
- * OPFS handle for `<namespace>/`, reached with the plain (async) OPFS API from
- * JS — which, unlike the WASM side's sync access handles, works on the main
- * thread of any page. Returns null when OPFS isn't available at all.
+ * The order `web_devmenu_open`'s first argument counts in — the index into this array
+ * is what crosses to C++, so it has to stay in step with WebDevMenu.cpp (written by
+ * scripts/build.sh). Names on this side, a number on the wire.
  */
-async function opfsNamespaceDir(namespace, create) {
-    if (typeof navigator === 'undefined' || !navigator.storage?.getDirectory)
-        return null;
-    try {
-        let dir = await navigator.storage.getDirectory();
-        for (const segment of namespace.split('/').filter(Boolean)) {
-            dir = await dir.getDirectoryHandle(segment, { create });
-        }
-        return dir;
-    }
-    catch {
-        return null; // missing (create: false), or blocked
-    }
-}
+const DEV_MENU_SCREENS = ['main', 'player', 'categories', 'stages'];
+// ---------------------------------------------------------------- the live engine
 /**
- * Mirror for the engine's save file.
+ * The running engine.
  *
- * The working dir is in-memory whenever the OPFS *mount* is unavailable (which
- * is every build without Asyncify/JSPI — see mountWorkingDir), so SData.bin
- * would die with the page and every save slot would read "NEW GAME" forever.
- * The host's own OPFS access has no such limitation, so the SDK copies the file
- * in before the engine boots and back out as it changes. Saves therefore
- * survive reloads even while the mounted working dir does not.
+ * Most of it is the contract's, inherited: the four getter/setter pairs, the cumulative
+ * merge, the chainable promise, the event channel, and `destroy()`. What this class
+ * adds is the four hooks the base leaves to an engine — {@link open}, {@link close},
+ * {@link mounted}, {@link patched} — plus the members below, which have no contract
+ * equivalent and exist because RSDKv4 has a start menu worth drawing from HTML.
  */
-async function restoreSaveData(Module, namespace, workDir) {
-    const dir = await opfsNamespaceDir(namespace, false);
-    if (!dir)
-        return;
-    try {
-        const file = await (await dir.getFileHandle(SAVE_FILE)).getFile();
-        if (file.size > 0) {
-            Module.FS.writeFile(`${workDir}/${SAVE_FILE}`, new Uint8Array(await file.arrayBuffer()));
+export class Rsdkv4Play extends EnginePlayBase {
+    #module = null;
+    /** In flight, so two concurrent `restart()`s do not boot two engines. */
+    #booting = null;
+    #destroyed = false;
+    #canvas = null;
+    /** False when the host handed us its own canvas: then we neither size nor remove it. */
+    #ownsCanvas = false;
+    /** The element the picture has to fit inside, in CSS pixels. */
+    #box = null;
+    #boxObserver = null;
+    #persistent = false;
+    #namespace = DEFAULT_STORAGE_NAMESPACE;
+    #workDir = `${WORK_ROOT}/${DEFAULT_STORAGE_NAMESPACE}`;
+    #mirrorSaves = true;
+    #saveTimer = null;
+    /** Last bytes mirrored out, so the `saves` event means "changed" and not "checked". */
+    #lastSave = null;
+    /**
+     * Pause state, with an owner.
+     *
+     * `masterPaused` only freezes the logic loop — the audio callback keeps mixing, so a
+     * paused engine went on playing its music behind whatever the host put on top.
+     * Pausing therefore has to stop the sound too.
+     *
+     * The owner matters because pause/resume has several callers: a pause overlay, a
+     * start screen, the host itself. Closing an overlay must not resume a game something
+     * else had already frozen, so the *first* pause claims ownership and only that
+     * owner's `resume()` lifts it.
+     */
+    #pauseOwner = null;
+    /**
+     * The host's button object while it holds a claim, by reference — read on the
+     * engine's callback, never copied.
+     */
+    #buttons = null;
+    /** The reader handed to the engine, kept so the same function can be uninstalled. */
+    #pull = null;
+    /** Throttle state for a pull that throws. See {@link Rsdkv4Play.#readButtons}. */
+    #pullErrorKey = null;
+    #pullErrorAt = 0;
+    #pullErrors = 0;
+    constructor(init, events) {
+        // The spec goes up rather than being declared as a field: a subclass field
+        // initialiser runs after `super()`, which would be too late for the base to seed
+        // state from it.
+        super(RSDKV4_SPEC, init, events);
+    }
+    // ---- The hooks the contract's base class leaves to an engine ----
+    /**
+     * Open or reopen a session. The first call brings the wasm up; every call after that
+     * reuses it, because RSDKv4 cannot power-cycle in process and does not need to — a
+     * session is a save slot, a character and a stage, and all three are reachable on a
+     * running engine.
+     */
+    async open(options) {
+        await this.#ensureBooted();
+        // Re-applied from the merged state rather than from a patch, which is what makes a
+        // claim survive `restart()`: the engine's own input source was just reset by the
+        // boot (or never set, on a reopen), and the host's object is still the one it was.
+        if (options.buttons !== undefined)
+            this.#applyButtons(options.buttons);
+        // Absence is "boot the way the engine normally would", so an empty options bag
+        // leaves the engine wherever it came up — its own start menu, usually.
+        if (options.player !== undefined || options.slot !== undefined) {
+            this.game.start(options.slot ?? null, this.#playerIndex(options.player));
+        }
+        if (options.stage) {
+            this.devMenu.loadStage(options.stage.category | 0, options.stage.scene | 0);
         }
     }
-    catch {
-        /* no save yet */
+    /**
+     * Stop and release. The base emits `exit` once this resolves.
+     *
+     * There is no coming back: RSDKv4 cannot be restarted in process, so a later
+     * `start()` on the same factory reports that rather than quietly doing nothing.
+     */
+    async close() {
+        this.#destroyed = true;
+        if (this.#saveTimer !== null) {
+            clearInterval(this.#saveTimer);
+            this.#saveTimer = null;
+        }
+        const Module = this.#module;
+        if (Module) {
+            // Before anything else: the engine is about to be pumped a few more times on its
+            // way down, and there is no reason for those ticks to reach into a host object
+            // whose owner has already been told the session is over.
+            this.#applyButtons(null);
+            // Last chance to keep whatever the player earned this session.
+            if (this.#mirrorSaves)
+                await this.#mirrorSaveData();
+            try {
+                Module.pauseMainLoop?.();
+            }
+            catch {
+                /* engine already down */
+            }
+            this.#applyPaused(true);
+            // Freezing the loop does not silence the audio callback — without this the music
+            // kept playing after the host went back to its launcher.
+            try {
+                Module.web_audio_stop?.();
+            }
+            catch {
+                /* engine already down */
+            }
+        }
+        this.#teardownCanvas();
+        this.#module = null;
+        this.#booting = null;
     }
-}
-async function persistSaveData(Module, namespace, workDir) {
-    let bytes;
-    try {
-        bytes = Module.FS.readFile(`${workDir}/${SAVE_FILE}`);
+    /**
+     * Where the picture goes. Called by the base before the first `open()`, which is what
+     * guarantees the canvas exists before Emscripten's SDL2 port goes looking for it.
+     *
+     * Hand over a `<canvas>` and it is used as-is, untouched apart from the id SDL needs;
+     * hand over any other element and the SDK creates a canvas inside it and keeps it
+     * scaled to fit. Reparenting a live engine is legal — the same canvas moves.
+     */
+    async mounted(target) {
+        if (this.#canvas) {
+            this.#reparent(target);
+            return;
+        }
+        const provided = target instanceof HTMLCanvasElement ? target : null;
+        const canvas = provided ?? document.createElement('canvas');
+        this.#ownsCanvas = provided === null;
+        this.#canvas = canvas;
+        this.#box = this.#ownsCanvas ? target : canvas;
+        // Emscripten's SDL2 port locates the canvas via document.querySelector('#canvas').
+        if (canvas.id !== CANVAS_ID) {
+            if (canvas.id) {
+                console.warn(`[rsdkv4] renaming the render target's id from "${canvas.id}" to "${CANVAS_ID}" — SDL looks the canvas up by that id.`);
+            }
+            canvas.id = CANVAS_ID;
+        }
+        if (this.#ownsCanvas) {
+            canvas.style.display = 'block';
+            canvas.style.maxWidth = '100%';
+            canvas.style.maxHeight = '100%';
+            canvas.style.height = 'auto';
+            canvas.classList.add('emscripten');
+            target.appendChild(canvas);
+        }
+        // A canvas is not in the tab order and `focus()` on one is a silent no-op until it
+        // has a tabindex. -1 makes it focusable without adding a tab stop.
+        if (!canvas.hasAttribute('tabindex'))
+            canvas.setAttribute('tabindex', '-1');
+        // …and the focus ring would draw a browser-blue box around the picture.
+        canvas.style.outline = 'none';
+        canvas.addEventListener('contextmenu', this.#swallowContextMenu);
+        canvas.addEventListener('pointerdown', this.#onPointerDown);
+        canvas.addEventListener('keydown', this.#onKeyDown);
+        window.addEventListener('resize', this.#onResize);
+        // Fullscreen transitions need a refit too.
+        document.addEventListener('fullscreenchange', this.#onFullscreenChange);
+        if (typeof ResizeObserver !== 'undefined' && this.#box) {
+            this.#boxObserver = new ResizeObserver(this.#onResize);
+            this.#boxObserver.observe(this.#box);
+        }
+        this.#fitPicture();
     }
-    catch {
-        return; // the engine hasn't written one
+    /**
+     * A payload changed on a running engine. Only the GAME OPTIONS rows are `live` here —
+     * `config` is `settings.ini`, read once at boot, and `player`/`slot`/`stage` are what
+     * a `restart()` is for.
+     */
+    async patched(kind, patch) {
+        if (kind !== 'options')
+            return;
+        // Ahead of the engine check, unlike everything below it: a claim written onto an
+        // engine that has not booted yet is still a claim, and a malformed one should be
+        // rejected by the call that made it rather than by the boot three lines later.
+        //
+        // `undefined` and `null` are not the same key here, and must not be collapsed:
+        // absence means "leave the claim as it is" — which is what keeps a later
+        // `options({ stage })` from dropping a claim on its way past — and only `null`
+        // releases.
+        const buttons = patch.buttons;
+        if (buttons !== undefined)
+            this.#applyButtons(buttons);
+        if (!this.#module)
+            return;
+        const rows = this.game.options();
+        for (const [key, value] of Object.entries(patch)) {
+            if (key === 'player' || key === 'slot' || key === 'stage' || key === 'buttons')
+                continue;
+            const row = rows.find((candidate) => candidate.key === key);
+            if (!row) {
+                console.warn(`[rsdkv4] "${key}" is not a game option this pack declares — ignoring. Read options() for the ones it does.`);
+                continue;
+            }
+            this.game.setOption(row.key, toEngineOption(row, value));
+        }
     }
-    const dir = await opfsNamespaceDir(namespace, true);
-    if (!dir)
-        return;
-    try {
-        const writable = await (await dir.getFileHandle(SAVE_FILE, { create: true })).createWritable();
-        await writable.write(bytes);
-        await writable.close();
+    options(patch) {
+        // `arguments.length`, not `patch === undefined`: `options(undefined)` is a write of
+        // nothing, not a read.
+        if (arguments.length === 0)
+            return this.#describeOptions();
+        return super.options(patch);
     }
-    catch (e) {
-        console.warn('[rsdkv4] could not persist save data', e);
+    async #describeOptions() {
+        const described = (await super.options());
+        // The claim never reads back, engine or no engine. The base would have written the
+        // host's live object into `value` here, and this getter is what a host serialises
+        // to save its settings and what it reads to paint a settings screen — neither of
+        // which fourteen booleans that change sixty times a second belong in.
+        // `play.input.claimed` is the honest question, and it is a different one.
+        described.buttons = { ...described.buttons, value: null };
+        if (!this.#module)
+            return described;
+        const out = { ...described };
+        const players = this.game.players();
+        if (players.length)
+            out.player = { ...out.player, enum: players };
+        const stages = flattenStages(this.devMenu.getStageList());
+        if (stages.length)
+            out.stage = { ...out.stage, enum: stages };
+        for (const row of this.game.options()) {
+            if (row.key === 'player' ||
+                row.key === 'slot' ||
+                row.key === 'stage' ||
+                row.key === 'buttons') {
+                console.warn(`[rsdkv4] the pack declares a game option named "${row.key}" — shadowed`);
+                continue;
+            }
+            out[row.key] = {
+                value: fromEngineOption(row),
+                description: row.label,
+                live: true,
+                enum: row.type === 'boolean' ? [false, true] : (row.values ?? []),
+            };
+        }
+        return out;
     }
-}
-/** Delete a file if present; returns true when something was removed. */
-function deleteFileIfExists(Module, path) {
-    if (!fileExists(Module, path))
-        return false;
-    try {
-        Module.FS.unlink(path);
-        return true;
+    restart(options) {
+        return super.restart(options);
     }
-    catch {
-        return false;
+    // ---- Members with no contract equivalent ----
+    /**
+     * Pause, on behalf of `owner`. The first caller to pause owns it and only that
+     * owner's `resume()` lifts it, so a pause overlay cannot resume a game a start
+     * screen — or the host — had already frozen. Audio stops with the engine.
+     *
+     * Emits the contract's `pause` event, whose detail carries the owner.
+     */
+    pause(owner = 'host') {
+        if (this.#pauseOwner !== null)
+            return; // whoever got there first keeps the claim
+        this.#pauseOwner = owner;
+        this.#applyPaused(true);
+        // A pause is a natural checkpoint for the save mirror.
+        if (this.#mirrorSaves)
+            void this.#mirrorSaveData();
+        this.emit('pause', { owner });
     }
-}
-/** Boot the RSDKv4 engine. */
-export async function load(config) {
-    const { assets, onEvent, attachTo } = config;
-    const options = config.options;
-    const emit = (event) => {
+    resume(owner = 'host') {
+        if (this.#pauseOwner !== owner)
+            return; // someone else's pause — leave it alone
+        this.#pauseOwner = null;
+        this.#applyPaused(false);
+        this.emit('resume', { owner });
+    }
+    /** Who is holding the engine paused, or null. */
+    get pausedBy() {
+        return this.#pauseOwner;
+    }
+    /** True when the working dir is OPFS-backed rather than in-memory. */
+    get persistent() {
+        return this.#persistent;
+    }
+    /** The normalised {@link Rsdkv4Storage.namespace} this session actually used. */
+    get namespace() {
+        return this.#namespace;
+    }
+    /**
+     * Input ownership, named. `play.input.claim(buttons)` and `play.input.release()`
+     * are exactly `options({ buttons })` and `options({ buttons: null })` — same state,
+     * same survival across `restart()`, same everything.
+     */
+    get input() {
+        // Captured, because `this` inside an object literal's getter is the literal. A
+        // host that holds on to `play.input` and asks later still gets today's answer.
+        const play = this;
+        return {
+            claim: (buttons) => this.options({ buttons }),
+            release: () => this.options({ buttons: null }),
+            get claimed() {
+                return play.#buttons !== null;
+            },
+            get mask() {
+                return play.#engineMask();
+            },
+            get held() {
+                const mask = play.#engineMask();
+                const held = {};
+                for (let bit = 0; bit < RSDKV4_BUTTONS.length; bit++) {
+                    held[RSDKV4_BUTTONS[bit]] = (mask & (1 << bit)) !== 0;
+                }
+                return held;
+            },
+        };
+    }
+    /**
+     * The engine's own `web_input_get_mask()`, or 0 when there is no engine to ask.
+     *
+     * Deliberately quiet about a module that does not have the bridge: unlike a claim,
+     * which silently does nothing and deserves the console error `#applyButtons` gives
+     * it, this is a read — a host polling it once a frame for an overlay would turn one
+     * old artifact into sixty messages a second.
+     */
+    #engineMask() {
+        const Module = this.#module;
+        if (!Module || typeof Module.web_input_get_mask !== 'function')
+            return 0;
+        return Module.web_input_get_mask() | 0;
+    }
+    // ---- Host-driven input ----
+    /**
+     * Claim or release, on the engine and here. The only writer of {@link #buttons}.
+     *
+     * Order matters in both directions: the reader is installed before the engine is
+     * told to use it, and the engine is told to stop before it is taken away — so there
+     * is never a tick where the engine is pulling at something that is not there.
+     */
+    #applyButtons(buttons) {
+        if (buttons !== null)
+            validateButtons(buttons);
+        const Module = this.#module;
+        this.#buttons = buttons;
+        // Before a boot there is nothing to tell; `open()` re-applies from the merged
+        // state once the engine is up, which is the same path a `restart()` takes.
+        if (!Module)
+            return;
+        if (typeof Module.web_input_set_source !== 'function') {
+            console.error('[rsdkv4] web_input_set_source is missing from this build of rsdkv4.wasm — host-driven input needs an engine built from this SDK\'s build.sh. Rebuild it (`make build-wasm`); the engine keeps polling the keyboard until then.');
+            return;
+        }
+        if (buttons === null) {
+            Module.web_input_set_source(0);
+            delete Module[INPUT_PULL_HOOK];
+            this.#pull = null;
+            this.#resetPullErrors();
+            return;
+        }
+        this.#pull ??= () => this.#readButtons();
+        Module[INPUT_PULL_HOOK] = this.#pull;
+        Module.web_input_set_source(1);
+    }
+    /**
+     * The per-tick read. Called from the engine, at the top of its input pass, through
+     * `web_input_pull()` — never from a timer and never from anywhere else.
+     *
+     * **Keep it on the engine's callback.** A read inside a reactive effect would make
+     * all fourteen buttons dependencies of that effect (jq79 attributes every read
+     * through a store's `get` trap to whichever effect is running), and every keypress
+     * would wake it. The call stack here is always rAF → wasm → EM_JS → this, where no
+     * effect can be running, and that is an invariant to preserve rather than a
+     * coincidence to rely on.
+     */
+    #readButtons() {
+        const buttons = this.#buttons;
+        if (!buttons)
+            return 0;
         try {
-            onEvent?.(event);
+            let mask = 0;
+            // Indexed, not `Object.entries`: the array's order is the engine's bit order,
+            // and a host object's key order is its own business.
+            for (let bit = 0; bit < RSDKV4_BUTTONS.length; bit++) {
+                if (buttons[RSDKV4_BUTTONS[bit]])
+                    mask |= 1 << bit;
+            }
+            this.#resetPullErrors();
+            return mask;
         }
-        catch {
-            // A host callback must not break the engine runtime.
+        catch (error) {
+            this.#reportPullError(error);
+            // Everything released, never the last good mask: a repeated mask with a
+            // direction held leaves the character running into a pit on its own.
+            return 0;
         }
-    };
-    // ----------------------------------------------------------------- render target
-    const providedCanvas = config.canvasEl ?? config.canvas ?? null;
-    if (!providedCanvas && !attachTo) {
-        throw new Error('rsdkv4: config.canvasEl or config.attachTo is required');
-    }
-    const ownsCanvas = providedCanvas === null;
-    const canvas = providedCanvas ?? document.createElement('canvas');
-    // Emscripten's SDL2 port locates the canvas via document.querySelector('#canvas').
-    if (canvas.id !== CANVAS_ID) {
-        if (canvas.id) {
-            console.warn(`rsdkv4: renaming the render target's id from "${canvas.id}" to "${CANVAS_ID}" — SDL looks the canvas up by that id.`);
-        }
-        canvas.id = CANVAS_ID;
-    }
-    if (ownsCanvas) {
-        canvas.style.display = 'block';
-        canvas.style.maxWidth = '100%';
-        canvas.style.maxHeight = '100%';
-        canvas.style.height = 'auto';
-        canvas.classList.add('emscripten');
-        attachTo?.appendChild(canvas);
-    }
-    // A canvas is not in the tab order and `focus()` on one is a silent no-op
-    // until it has a tabindex. -1 makes it focusable without adding a tab stop.
-    if (!canvas.hasAttribute('tabindex'))
-        canvas.setAttribute('tabindex', '-1');
-    // …and the focus ring would draw a browser-blue box around the picture.
-    canvas.style.outline = 'none';
-    const swallowContextMenu = (event) => event.preventDefault();
-    canvas.addEventListener('contextmenu', swallowContextMenu);
-    const focusCanvas = () => {
-        if (!document.hasFocus())
-            window.focus();
-        canvas.focus({ preventScroll: true });
-    };
-    const onPointerDown = () => focusCanvas();
-    canvas.addEventListener('pointerdown', onPointerDown);
-    // ----------------------------------------------------------------- sizing
-    /** The box the picture has to fit inside, in CSS pixels. */
-    const boxElement = ownsCanvas && attachTo ? attachTo : canvas;
-    const fitPicture = () => {
-        if (!ownsCanvas)
-            return;
-        const box = boxElement.getBoundingClientRect();
-        if (box.width < 1 || box.height < 1)
+    }
+    /**
+     * Announce a failing pull at most once a second, with a count.
+     *
+     * This runs sixty times a second, so an unthrottled `emit` would bury the page. It
+     * does **not** release the claim: a transient fault recovers on its own, whereas
+     * releasing would change input ownership behind the host's back.
+     *
+     * With a plain object nothing here can fire. It exists because the API accepts any
+     * object and a Proxy runs host code on every read — a store nulled by a component
+     * that unmounted without releasing, a revoked `Proxy.revocable`, a `get` trap whose
+     * effect scope has been torn down. Claim-time validation covers none of those: it
+     * validated once, over a reference that was live at the time.
+     */
+    #reportPullError(error) {
+        const key = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+        // performance.now() rather than a timer: nothing to schedule, nothing to clear,
+        // and the comparison is already in the hand.
+        const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+        this.#pullErrors++;
+        if (key !== this.#pullErrorKey || now - this.#pullErrorAt >= INPUT_ERROR_INTERVAL_MS) {
+            const windowMs = this.#pullErrorKey === null ? 0 : now - this.#pullErrorAt;
+            this.emit('error', Object.assign(new Error(`rsdkv4: reading the host's buttons failed (${this.#pullErrors}× in ${Math.round(windowMs)}ms) — input is dead until it recovers, and the claim is still held. Release it with options({ buttons: null }) if the host is gone. Cause: ${key}`), { cause: error }));
+            this.#pullErrorKey = key;
+            this.#pullErrorAt = now;
+            this.#pullErrors = 0;
+        }
+    }
+    /** Forget the streak, so a relapse announces itself immediately rather than in a second. */
+    #resetPullErrors() {
+        if (this.#pullErrorKey === null)
             return;
-        const bw = manifest.video.baseWidth;
-        const bh = manifest.video.baseHeight;
-        const scale = Math.min(box.width / bw, box.height / bh);
-        canvas.style.width = `${Math.round(bw * scale)}px`;
-        canvas.style.height = `${Math.round(bh * scale)}px`;
-    };
-    fitPicture();
-    const onResize = () => fitPicture();
-    window.addEventListener('resize', onResize);
-    const boxObserver = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(onResize);
-    boxObserver?.observe(boxElement);
-    // Fullscreen transitions need a refit too.
-    const onFullscreenChange = () => {
-        fitPicture();
-        requestAnimationFrame(fitPicture);
-    };
-    document.addEventListener('fullscreenchange', onFullscreenChange);
-    // ----------------------------------------------------------------- emscripten
-    const jsUrl = config.jsUrl ?? new URL('./rsdkv4.js', import.meta.url).href;
-    const wasmUrl = config.wasmUrl ?? new URL('./rsdkv4.wasm', import.meta.url).href;
-    // RSDKv4 keyboard bindings are the shared input script's default preset.
-    if (typeof window !== 'undefined')
-        window.__gamepadKeyMap = manifest.input;
-    const instantiate = async (bust) => {
-        const withBust = (url) => {
-            if (!bust)
-                return url;
-            const parsed = new URL(url, location.href);
-            parsed.searchParams.set('_', bust);
-            return parsed.href;
+        this.#pullErrorKey = null;
+        this.#pullErrorAt = 0;
+        this.#pullErrors = 0;
+    }
+    /** RSDKv4's Start Menu as data. Available once the engine is up. */
+    get game() {
+        const Module = this.#requireModule();
+        const parse = (fn, fallback, what) => parseJson(fn, fallback, what);
+        return {
+            type: () => (typeof Module.web_game_type === 'function' ? Module.web_game_type() : 0),
+            players: () => parse(Module.web_get_players, [], 'web_get_players'),
+            saveSlots: () => parse(Module.web_get_save_slots, [], 'web_get_save_slots'),
+            options: () => parse(Module.web_get_game_options, [], 'web_get_game_options'),
+            setOption: (key, value) => {
+                Module.web_set_game_option?.(String(key), value | 0);
+            },
+            deleteSave: (slot) => {
+                Module.web_delete_save?.(slot | 0);
+                if (this.#mirrorSaves)
+                    void this.#mirrorSaveData();
+            },
+            start: (slot, player = 0) => {
+                Module.web_start_game?.(slot == null ? -1 : slot | 0, player | 0);
+                // Whatever drove this is done with the engine — hand it back.
+                this.#pauseOwner = null;
+                this.#applyPaused(false);
+            },
         };
-        const mod = await import(/* @vite-ignore */ withBust(jsUrl));
-        return mod.default({
-            canvas,
-            noInitialRun: true, // built with -sINVOKE_RUN=0; we mount data before main()
-            locateFile: (path) => (path.endsWith('.wasm') ? withBust(wasmUrl) : path),
-            print: (...a) => console.log('[rsdkv4]', ...a),
-            printErr: (...a) => console.error('[rsdkv4]', ...a),
-            onAbort: (reason) => emit({ type: 'error', error: new Error(`rsdkv4 aborted: ${reason}`) }),
-        });
-    };
-    let Module = await instantiate();
-    // Self-heal a stale engine.
-    //
-    // rsdkv4.js/.wasm are big and served by most static hosts with nothing but
-    // Last-Modified, so a browser will happily keep a build for hours. The
-    // symptom is nasty: fresh SDK code against an old engine, where the bridges
-    // this SDK calls simply don't exist and every getter quietly answers "empty" —
-    // no save slots, no characters, an empty pause menu. Rather than leave that to
-    // the reader's cache hygiene, notice it and fetch once past the cache.
-    if (!engineBridgeComplete(Module)) {
-        console.warn('[rsdkv4] the engine that loaded is missing bridges this SDK needs — refetching past the HTTP cache');
-        Module = await instantiate(String(Date.now()));
-        if (!engineBridgeComplete(Module)) {
-            console.error('[rsdkv4] still missing engine bridges after a cache-busting reload — rsdkv4.wasm is genuinely older than this SDK; rebuild it (`make build-wasm`)');
-        }
-    }
-    // Mount the working dir first, so we can see what's already persisted (OPFS)
-    // before deciding whether to pull assets.
-    const { persistent } = mountWorkingDir(Module, config.persist);
-    const storageNamespace = normalizeStorageNamespace(config.storageNamespace);
-    const workDir = `${WORK_ROOT}/${storageNamespace}`;
-    ensureDir(Module, workDir);
-    const dataPath = `${workDir}/Data.rsdk`;
-    const settingsPath = `${workDir}/settings.ini`;
-    // Data.rsdk — precedence: explicit asset > already persisted (skip fetch) > lazy provider.
-    let dataBytes = toUint8(assets?.data);
-    if (!dataBytes) {
-        if (fileExists(Module, dataPath)) {
-            console.log(`[rsdkv4] Data.rsdk already in persistent storage (${storageNamespace}) — skipping fetch`);
-        }
-        else if (config.dataProvider) {
-            dataBytes = toUint8(await config.dataProvider());
-        }
     }
-    if (dataBytes) {
-        Module.FS.writeFile(dataPath, dataBytes);
+    /** The engine's stage list and loader. Available once the engine is up. */
+    get devMenu() {
+        const Module = this.#requireModule();
+        return {
+            getStageList: () => parseJson(Module.web_devmenu_get_stage_list, [], 'web_devmenu_get_stage_list'),
+            loadStage: (categoryIdx, stageIdx) => {
+                Module.web_devmenu_load_stage?.(categoryIdx | 0, stageIdx | 0);
+            },
+            setPaused: (paused) => {
+                if (paused)
+                    this.pause('host');
+                else
+                    this.resume(this.#pauseOwner ?? 'host');
+            },
+            canOpen: typeof Module.web_devmenu_open === 'function',
+            open: (screen = 'main', category = 0) => {
+                if (typeof Module.web_devmenu_open !== 'function') {
+                    console.warn('[rsdkv4] this rsdkv4.wasm has no web_devmenu_open — rebuild it (`make build-wasm`), or read devMenu.canOpen before offering the button');
+                    return false;
+                }
+                const index = DEV_MENU_SCREENS.indexOf(screen);
+                if (index < 0) {
+                    console.warn(`[rsdkv4] "${screen}" is not a dev menu screen — one of ${DEV_MENU_SCREENS.join(', ')}`);
+                    return false;
+                }
+                Module.web_devmenu_open(index, category | 0);
+                return true;
+            },
+        };
     }
-    else if (!fileExists(Module, dataPath)) {
-        throw new Error('rsdkv4: no Data.rsdk — provide assets.data, a dataProvider, or a persisted copy (OPFS)');
+    // ---- Bringing the engine up ----
+    #requireModule() {
+        if (!this.#module) {
+            throw new Error('rsdkv4: the engine is not running — await start() before reaching for it');
+        }
+        return this.#module;
     }
-    // settings.ini — explicit asset > persisted > lazy provider > generated from options.
-    let settingsBytes = toUint8(assets?.settings);
-    if (!settingsBytes && !fileExists(Module, settingsPath) && config.settingsProvider) {
-        settingsBytes = toUint8(await config.settingsProvider());
+    #ensureBooted() {
+        if (this.#destroyed) {
+            throw new Error('rsdkv4: this engine has been destroyed and cannot be restarted in process — build a new Rsdkv4SDK');
+        }
+        // A boot that failed must not poison the next attempt. The common failure is a
+        // host that started before handing over `assets.data` — it fixes that and calls
+        // `start()` again, and caching the rejection would tell it "no Data.rsdk" forever.
+        this.#booting ??= this.#boot().catch((error) => {
+            this.#booting = null;
+            this.#module = null;
+            throw error;
+        });
+        return this.#booting;
     }
-    if (settingsBytes) {
-        Module.FS.writeFile(settingsPath, settingsBytes);
+    async #boot() {
+        const canvas = this.#canvas;
+        if (!canvas) {
+            throw new Error('rsdkv4: mount(target) before start() — the engine draws into a canvas');
+        }
+        const config = valuesOf(await this.config());
+        const assets = valuesOf(await this.assets());
+        const storage = valuesOf(await this.storage());
+        const Module = await this.#instantiate(canvas, config);
+        this.#module = Module;
+        // Mount the working dir first, so we can see what is already persisted (OPFS)
+        // before deciding whether to pull assets.
+        this.#persistent = mountWorkingDir(Module, storage.persist).persistent;
+        this.#namespace = normalizeStorageNamespace(storage.namespace);
+        this.#workDir = `${WORK_ROOT}/${this.#namespace}`;
+        this.#mirrorSaves = storage.persist !== null;
+        ensureDir(Module, this.#workDir);
+        await this.#writeAssets(Module, assets, config);
+        // `persist: null` means the host wants nothing kept, so honour it; otherwise pull
+        // any previous SData.bin in before the engine reads it.
+        if (this.#mirrorSaves)
+            await this.#restoreSaveData(Module);
+        Module.FS.chdir(this.#workDir);
+        // Run main() from the working dir. simulate_infinite_loop schedules the rAF loop
+        // and returns via a benign unwind Emscripten swallows.
+        Module.callMain(['UsingCWD']);
+        // callMain only *schedules* the loop: Engine::Init runs on the first frame, and
+        // until it has, there is no game config, stage list or saveRAM to read. Waiting
+        // here means the bridges answer the moment start() resolves.
+        await waitForEngine(Module);
+        this.#focusCanvas();
+        // The engine writes SData.bin at its own pace (new game, checkpoint, options
+        // change), so copy it out on a slow timer as well as on the way down.
+        //
+        // The timer alone loses saves, and by a wide margin: `destroy()` is the only
+        // other flush, and a browser tab that is closed or reloaded never calls it. A
+        // player who finished an act and hit reload inside the next ten seconds had the
+        // save written by the engine, held in the wasm heap, and dropped on the floor —
+        // which reads as "my progress did not stick" and looks exactly like a save
+        // system that does not work.
+        //
+        // `visibilitychange` → hidden is the flush that actually fires: it covers the
+        // tab being switched away from, the window being minimised, the phone going to
+        // the home screen, and — unlike `beforeunload`, which browsers increasingly
+        // ignore — navigating away and closing. `pagehide` backs it up for the bfcache
+        // path. Cheap to over-fire: the mirror compares bytes and returns without
+        // touching OPFS when nothing moved.
+        if (this.#mirrorSaves) {
+            this.#saveTimer = setInterval(() => void this.#mirrorSaveData(), 10_000);
+            document.addEventListener('visibilitychange', this.#onVisibilityChange);
+            window.addEventListener('pagehide', this.#onPageHide);
+        }
+        return Module;
     }
-    else if (!fileExists(Module, settingsPath)) {
-        Module.FS.writeFile(settingsPath, new TextEncoder().encode(buildSettingsIni(options)));
+    async #instantiate(canvas, config) {
+        const jsUrl = config.jsUrl ?? new URL('./rsdkv4.js', import.meta.url).href;
+        const wasmUrl = config.wasmUrl ?? new URL('./rsdkv4.wasm', import.meta.url).href;
+        const load = async (bust) => {
+            const withBust = (url) => {
+                if (!bust)
+                    return url;
+                const parsed = new URL(url, location.href);
+                parsed.searchParams.set('_', bust);
+                return parsed.href;
+            };
+            const mod = await import(/* @vite-ignore */ withBust(jsUrl));
+            return mod.default({
+                canvas,
+                noInitialRun: true, // built with -sINVOKE_RUN=0; we mount data before main()
+                locateFile: (path) => (path.endsWith('.wasm') ? withBust(wasmUrl) : path),
+                print: (...a) => console.log('[rsdkv4]', ...a),
+                printErr: (...a) => console.error('[rsdkv4]', ...a),
+                onAbort: (reason) => {
+                    this.emit('error', new Error(`rsdkv4 aborted: ${reason}`));
+                },
+            });
+        };
+        let Module = await load();
+        // Self-heal a stale engine.
+        //
+        // rsdkv4.js/.wasm are big and served by most static hosts with nothing but
+        // Last-Modified, so a browser will happily keep a build for hours. The symptom is
+        // nasty: fresh SDK code against an old engine, where the bridges this SDK calls
+        // simply don't exist and every getter quietly answers "empty" — no save slots, no
+        // characters, an empty pause menu. Rather than leave that to the reader's cache
+        // hygiene, notice it and fetch once past the cache.
+        if (!engineBridgeComplete(Module)) {
+            console.warn('[rsdkv4] the engine that loaded is missing bridges this SDK needs — refetching past the HTTP cache');
+            Module = await load(String(Date.now()));
+            if (!engineBridgeComplete(Module)) {
+                console.error('[rsdkv4] still missing engine bridges after a cache-busting reload — rsdkv4.wasm is genuinely older than this SDK; rebuild it (`make build-wasm`)');
+            }
+        }
+        return Module;
     }
-    // else: keep the persisted settings.ini
-    // Save data. `persist: null` means the host wants nothing kept, so honour it;
-    // otherwise pull any previous SData.bin in before the engine reads it.
-    const mirrorSaves = config.persist !== null;
-    if (mirrorSaves)
-        await restoreSaveData(Module, storageNamespace, workDir);
-    Module.FS.chdir(workDir);
-    let pauseOwner = null;
-    const applyPaused = (paused) => {
-        if (typeof Module.web_devmenu_set_paused === 'function')
-            Module.web_devmenu_set_paused(paused);
-        if (typeof Module.web_audio_set_paused === 'function')
-            Module.web_audio_set_paused(paused);
-    };
-    const pauseWith = (owner) => {
-        if (pauseOwner !== null)
-            return; // already paused — whoever got there first keeps the claim
-        pauseOwner = owner;
-        applyPaused(true);
-        // A pause is a natural checkpoint for the save mirror.
-        if (mirrorSaves)
-            void persistSaveData(Module, storageNamespace, workDir);
-    };
-    const resumeFrom = (owner) => {
-        if (pauseOwner !== owner)
-            return; // someone else's pause — leave it alone
-        pauseOwner = null;
-        applyPaused(false);
-    };
-    /** Legacy shape kept for `devMenu.setPaused` — always acts as the host. */
-    const setPaused = (paused) => {
-        if (paused)
-            pauseWith('host');
-        else
-            resumeFrom(pauseOwner ?? 'host');
-    };
-    const stopAudio = () => {
+    /** Data.rsdk and settings.ini into the working dir. See {@link Rsdkv4Assets}. */
+    async #writeAssets(Module, assets, config) {
+        const dataPath = `${this.#workDir}/Data.rsdk`;
+        const settingsPath = `${this.#workDir}/settings.ini`;
+        // The pack — the expensive one, so a persisted copy short-circuits the thunk.
+        if (fileExists(Module, dataPath)) {
+            const explicit = typeof assets.data === 'function' ? null : await resolveAsset(assets.data);
+            if (explicit)
+                Module.FS.writeFile(dataPath, explicit);
+            else {
+                console.log(`[rsdkv4] Data.rsdk already in persistent storage (${this.#namespace}) — skipping fetch`);
+            }
+        }
+        else {
+            const bytes = await resolveAsset(assets.data);
+            if (!bytes) {
+                throw new Error('rsdkv4: no Data.rsdk — hand one over as assets.data (bytes or a thunk), or point storage.namespace at a persisted copy');
+            }
+            Module.FS.writeFile(dataPath, bytes);
+        }
+        // The settings — cheap, and regenerated every boot so `config` is never shadowed
+        // by a file an earlier session left behind. The engine never writes it back (its
+        // writeSettings() is #ifndef __EMSCRIPTEN__), so there is nothing to lose.
+        const settings = await resolveAsset(assets.settings);
+        Module.FS.writeFile(settingsPath, settings ?? new TextEncoder().encode(buildSettingsIni(config)));
+    }
+    // ---- The save mirror ----
+    /**
+     * Pull a previously mirrored SData.bin into the wasm before the engine reads it.
+     *
+     * The working dir is in-memory whenever the OPFS *mount* is unavailable (which is
+     * every build without Asyncify/JSPI — see {@link mountWorkingDir}), so SData.bin
+     * would die with the page and every slot would read "NEW GAME" forever. The host-side
+     * OPFS API has no such limitation, so the SDK copies the file in here and back out as
+     * it changes.
+     */
+    async #restoreSaveData(Module) {
+        const dir = await opfsNamespaceDir(this.#namespace, false);
+        if (!dir)
+            return;
         try {
-            Module.web_audio_stop?.();
+            const file = await (await dir.getFileHandle(SAVE_FILE)).getFile();
+            if (file.size > 0) {
+                const bytes = new Uint8Array(await file.arrayBuffer());
+                Module.FS.writeFile(`${this.#workDir}/${SAVE_FILE}`, bytes);
+                this.#lastSave = bytes;
+            }
         }
         catch {
-            /* engine already down */
+            /* no save yet */
         }
-    };
+    }
     /**
-     * Call a `web_*` embind getter and parse its JSON.
+     * Copy SData.bin out of the wasm into `<namespace>/`, and announce it if it moved.
      *
-     * A missing function means the loaded rsdkv4.wasm predates that bridge — the
-     * usual cause is a browser serving a cached build. Say so out loud: silently
-     * returning an empty list makes a stale artifact look like an empty save file
-     * or a game with no playable characters.
+     * The division of labour the session settled on: the SDK owns getting the bytes out
+     * of the wasm and into the namespace both sides already agree on; a host owns
+     * reading, parsing and painting them. `saves` is what tells it to look again — which
+     * is why it fires on a change and not on every check.
      */
-    const parseJson = (fn, fallback, what) => {
-        if (typeof fn !== 'function') {
-            console.error(`[rsdkv4] ${what} is missing from this build of rsdkv4.wasm — the page is probably running a cached copy. Hard-reload (or clear the site's storage) after rebuilding.`);
-            return fallback;
-        }
+    async #mirrorSaveData() {
+        const Module = this.#module;
+        if (!Module)
+            return;
+        // Explicitly over an ArrayBuffer, not the default ArrayBufferLike: OPFS's
+        // `write()` will not take a view that might be backed by a SharedArrayBuffer,
+        // and on a cross-origin isolated page that is not a hypothetical distinction.
+        let bytes;
         try {
-            return JSON.parse(fn());
+            bytes = Module.FS.readFile(`${this.#workDir}/${SAVE_FILE}`);
         }
-        catch (e) {
-            console.error(`[rsdkv4] ${what} failed`, e);
-            return fallback;
+        catch {
+            return; // the engine hasn't written one
         }
-    };
-    const game = {
-        type: () => (typeof Module.web_game_type === 'function' ? Module.web_game_type() : 0),
-        players: () => parseJson(Module.web_get_players, [], 'web_get_players'),
-        saveSlots: () => parseJson(Module.web_get_save_slots, [], 'web_get_save_slots'),
-        options: () => parseJson(Module.web_get_game_options, [], 'web_get_game_options'),
-        setOption(key, value) {
-            Module.web_set_game_option?.(String(key), value | 0);
-        },
-        deleteSave(slot) {
-            Module.web_delete_save?.(slot | 0);
-        },
-        start(slot, player = 0) {
-            Module.web_start_game?.(slot == null ? -1 : slot | 0, player | 0);
-            // The overlay that drove this is done with the engine — hand it back.
-            pauseOwner = null;
-            applyPaused(false);
-        },
-    };
-    const devMenu = {
-        getStageList() {
-            if (typeof Module.web_devmenu_get_stage_list !== 'function')
-                return [];
+        if (sameBytes(bytes, this.#lastSave))
+            return;
+        const dir = await opfsNamespaceDir(this.#namespace, true);
+        if (dir) {
             try {
-                return JSON.parse(Module.web_devmenu_get_stage_list());
+                const handle = await dir.getFileHandle(SAVE_FILE, { create: true });
+                const writable = await handle.createWritable();
+                await writable.write(bytes);
+                await writable.close();
             }
             catch (e) {
-                console.error('[rsdkv4] getStageList failed', e);
-                return [];
+                console.warn('[rsdkv4] could not persist save data', e);
+                return;
             }
-        },
-        loadStage(categoryIdx, stageIdx) {
-            if (typeof Module.web_devmenu_load_stage === 'function') {
-                Module.web_devmenu_load_stage(categoryIdx | 0, stageIdx | 0);
-            }
-        },
-        setPaused,
+        }
+        this.#lastSave = bytes;
+        this.emit('saves', this.game.saveSlots());
+    }
+    // ---- The render target ----
+    /**
+     * Flush the save when the page is being put away. See where these are registered
+     * for why the ten-second timer is not enough on its own.
+     */
+    #onVisibilityChange = () => {
+        if (document.visibilityState === 'hidden' && this.#mirrorSaves)
+            void this.#mirrorSaveData();
     };
-    // Run main() from the OPFS/WASMFS working dir. simulate_infinite_loop schedules
-    // the rAF loop and returns via a benign unwind Emscripten swallows.
-    Module.callMain(['UsingCWD']);
-    // callMain only *schedules* the loop: Engine::Init runs on the first frame, and
-    // until it has, there is no game config, stage list or saveRAM to read. Waiting
-    // here means a host can call devMenu/game getters the moment load() resolves.
-    await waitForEngine(Module);
-    focusCanvas();
-    // The engine writes SData.bin at its own pace (new game, checkpoint, options
-    // change), so copy it out on a slow timer as well as on the way down.
-    const saveTimer = mirrorSaves
-        ? setInterval(() => void persistSaveData(Module, storageNamespace, workDir), 10_000)
-        : null;
-    emit({ type: 'ready' });
-    return {
-        start() { },
-        /** `owner` lets a pause overlay avoid resuming a game something else paused. */
-        pause(owner = 'host') { pauseWith(owner); },
-        resume(owner = 'host') { resumeFrom(owner); },
-        reset() {
-            throw new Error('rsdkv4: reset() is not supported — destroy() and load() again');
-        },
-        setInput(preset) {
-            if (typeof window !== 'undefined') {
-                window.__gamepadKeyMap = preset ?? manifest.input;
-            }
-        },
-        destroy() {
-            if (saveTimer !== null)
-                clearInterval(saveTimer);
-            // Last chance to keep whatever the player earned this session.
-            if (mirrorSaves)
-                void persistSaveData(Module, storageNamespace, workDir);
-            try {
-                Module.pauseMainLoop?.();
-            }
-            catch { /* noop */ }
-            try {
-                setPaused(true);
-            }
-            catch { /* noop */ }
-            // Freezing the loop does not silence the audio callback — without this the
-            // music kept playing after the host went back to its launcher.
-            stopAudio();
-            canvas.removeEventListener('contextmenu', swallowContextMenu);
-            canvas.removeEventListener('pointerdown', onPointerDown);
-            document.removeEventListener('fullscreenchange', onFullscreenChange);
-            window.removeEventListener('resize', onResize);
-            boxObserver?.disconnect();
-            if (ownsCanvas)
-                canvas.remove();
-        },
-        devMenu,
-        game,
-        persistent,
-        storageNamespace,
-        purgeStorage() {
-            return {
-                data: deleteFileIfExists(Module, dataPath),
-                settings: deleteFileIfExists(Module, settingsPath),
-            };
-        },
+    #onPageHide = () => {
+        if (this.#mirrorSaves)
+            void this.#mirrorSaveData();
+    };
+    #swallowContextMenu = (event) => event.preventDefault();
+    #onPointerDown = () => this.#focusCanvas();
+    #onKeyDown = (event) => {
+        // Only the browser's own default action is suppressed — the arrows and Space
+        // scroll the page, Tab walks the focus out of the canvas. The event is left to
+        // propagate: SDL's own handler sits on `window` in the bubble phase, so calling
+        // stopPropagation() here would be the engine's whole keyboard.
+        if (ENGINE_KEYS.has(event.code) || ENGINE_KEYS.has(event.key))
+            event.preventDefault();
     };
+    #onResize = () => this.#fitPicture();
+    #onFullscreenChange = () => {
+        this.#fitPicture();
+        requestAnimationFrame(() => this.#fitPicture());
+    };
+    #focusCanvas() {
+        if (!this.#canvas)
+            return;
+        if (!document.hasFocus())
+            window.focus();
+        this.#canvas.focus({ preventScroll: true });
+    }
+    #fitPicture() {
+        if (!this.#ownsCanvas || !this.#canvas || !this.#box)
+            return;
+        const box = this.#box.getBoundingClientRect();
+        if (box.width < 1 || box.height < 1)
+            return;
+        const { baseWidth, baseHeight } = RSDKV4_VIDEO;
+        const scale = Math.min(box.width / baseWidth, box.height / baseHeight);
+        this.#canvas.style.width = `${Math.round(baseWidth * scale)}px`;
+        this.#canvas.style.height = `${Math.round(baseHeight * scale)}px`;
+    }
+    /**
+     * Move the picture we already have. SDL keeps its canvas; only the parent changes.
+     *
+     * Pointing a second `mount()` at a *different* `<canvas>` is the one case this
+     * refuses: SDL2 resolved `#canvas` once, at instantiation, so swapping the element
+     * would leave the engine drawing into an orphan while the host watched a blank one.
+     */
+    #reparent(target) {
+        const canvas = this.#canvas;
+        if (!canvas || target === canvas || canvas.parentElement === target)
+            return;
+        if (target instanceof HTMLCanvasElement) {
+            console.warn('[rsdkv4] the canvas SDL draws into cannot be swapped after mounting — ignoring this mount()');
+            return;
+        }
+        target.appendChild(canvas);
+        if (this.#box)
+            this.#boxObserver?.unobserve(this.#box);
+        this.#box = this.#ownsCanvas ? target : canvas;
+        if (this.#box)
+            this.#boxObserver?.observe(this.#box);
+        this.#fitPicture();
+    }
+    #teardownCanvas() {
+        const canvas = this.#canvas;
+        if (canvas) {
+            canvas.removeEventListener('contextmenu', this.#swallowContextMenu);
+            canvas.removeEventListener('pointerdown', this.#onPointerDown);
+            canvas.removeEventListener('keydown', this.#onKeyDown);
+            if (this.#ownsCanvas)
+                canvas.remove();
+        }
+        document.removeEventListener('fullscreenchange', this.#onFullscreenChange);
+        document.removeEventListener('visibilitychange', this.#onVisibilityChange);
+        window.removeEventListener('pagehide', this.#onPageHide);
+        window.removeEventListener('resize', this.#onResize);
+        this.#boxObserver?.disconnect();
+        this.#boxObserver = null;
+        this.#canvas = null;
+        this.#box = null;
+    }
+    // ---- Misc ----
+    #applyPaused(paused) {
+        const Module = this.#module;
+        if (!Module)
+            return;
+        if (typeof Module.web_devmenu_set_paused === 'function')
+            Module.web_devmenu_set_paused(paused);
+        if (typeof Module.web_audio_set_paused === 'function')
+            Module.web_audio_set_paused(paused);
+    }
+    /** A character name, as the pack spells it, to the index the engine wants. */
+    #playerIndex(player) {
+        if (player === undefined)
+            return 0;
+        const players = this.game.players();
+        const index = players.findIndex((name) => name.toLowerCase() === player.toLowerCase());
+        if (index < 0) {
+            throw new Error(`rsdkv4: "${player}" is not a playable character in this pack — try one of ${players.join(', ') || '(none reported)'}`);
+        }
+        return index;
+    }
+}
+// ---------------------------------------------------------------- the factory
+/**
+ * The factory a host imports: identity on the constructor, one live engine per
+ * instance, and a `start()` that brings the wasm up and opens a session.
+ *
+ * Everything on it is the contract's — see the module doc for the shape of a call.
+ */
+export class Rsdkv4SDK extends EngineSDKBase {
+    static id = 'rsdkv4';
+    /** Kept in step with package.json by `node scripts/sync-version.mjs`. */
+    static version = '0.2.1';
+    static name = 'Retro Software Development Kit v4';
+    static description = 'RSDKv4 compiled to WebAssembly via Emscripten. One game-agnostic WASM binary runs both Sonic 1 and Sonic 2 — the difference is only which Data.rsdk the host supplies at runtime. Ships none of the game: the player provides their own Data.rsdk, and it never leaves their browser.';
+    createPlay(init, events) {
+        return new Rsdkv4Play(init, events);
+    }
+    start(options) {
+        return super.start(options);
+    }
+}
+/**
+ * The line that puts the contract in CI: if this file stops satisfying
+ * `EngineSDKConstructor`, `make typecheck` says so.
+ */
+export const RSDKV4_ENGINE = Rsdkv4SDK;
+export default Rsdkv4SDK;
+// ---------------------------------------------------------------- module-private helpers
+/**
+ * Call a `web_*` embind getter and parse its JSON.
+ *
+ * A missing function means the loaded rsdkv4.wasm predates that bridge — the usual
+ * cause is a browser serving a cached build. Say so out loud: silently returning an
+ * empty list makes a stale artifact look like an empty save file or a game with no
+ * playable characters.
+ */
+function parseJson(fn, fallback, what) {
+    if (typeof fn !== 'function') {
+        console.error(`[rsdkv4] ${what} is missing from this build of rsdkv4.wasm — the page is probably running a cached copy. Hard-reload (or clear the site's storage) after rebuilding.`);
+        return fallback;
+    }
+    try {
+        return JSON.parse(fn());
+    }
+    catch (e) {
+        console.error(`[rsdkv4] ${what} failed`, e);
+        return fallback;
+    }
+}
+/**
+ * A claim, checked once — exactly the fourteen buttons, with missing and unknown both
+ * fatal.
+ *
+ * Strict because the two failure modes are silent and asymmetric. A **missing** key
+ * reads `false` on every tick: a dead button, no error anywhere, and easy to blame on
+ * the engine. An **unknown** key is a button the host writes to that nothing ever
+ * reads. The first sketch of this API lost `right` to a duplicated `up` — a duplicate
+ * key in an object literal is legal JavaScript and surfaces only as an absent one.
+ *
+ * `Object.keys`, not `in`: a reactive store's `has` trap can answer `true` for a key
+ * that has been deleted (jq79 does exactly that, deliberately, so a template
+ * expression reading a deleted name takes its else branch instead of dying), and
+ * `ownKeys` has no such licence.
+ */
+function validateButtons(buttons) {
+    if (typeof buttons !== 'object' || buttons === null) {
+        throw new Error(`rsdkv4: options({ buttons }) takes an object of the 14 buttons or null to release, not ${typeof buttons}`);
+    }
+    const keys = new Set(Object.keys(buttons));
+    const missing = RSDKV4_BUTTONS.filter((button) => !keys.has(button));
+    const unknown = [...keys].filter((key) => !RSDKV4_BUTTONS.includes(key));
+    if (missing.length || unknown.length) {
+        const faults = [
+            missing.length && `missing ${missing.join(', ')}`,
+            unknown.length && `unknown ${unknown.join(', ')}`,
+        ].filter(Boolean);
+        throw new Error(`rsdkv4: the buttons object must carry exactly the 14 buttons (${RSDKV4_BUTTONS.join(', ')}) — ${faults.join('; ')}. A missing button is dead, not neutral, so this is an error rather than a default.`);
+    }
+}
+/** The engine's two-level stage list as flat, writable {@link Rsdkv4Stage} values. */
+function flattenStages(categories) {
+    const out = [];
+    categories.forEach((category, categoryIdx) => {
+        category.stages.forEach((stage, sceneIdx) => {
+            out.push({ category: categoryIdx, scene: sceneIdx, name: `${category.name} · ${stage.name}` });
+        });
+    });
+    return out;
+}
+/** A GAME OPTIONS row as a host reads it: a boolean, or the label of the chosen entry. */
+function fromEngineOption(row) {
+    if (row.type === 'boolean')
+        return row.value !== 0;
+    return row.values?.[row.value] ?? row.value;
+}
+/** …and back to the number the engine stores. */
+function toEngineOption(row, value) {
+    if (typeof value === 'boolean')
+        return value ? 1 : 0;
+    if (typeof value === 'number')
+        return value | 0;
+    if (typeof value === 'string') {
+        const index = (row.values ?? []).findIndex((choice) => choice.toLowerCase() === value.toLowerCase());
+        if (index >= 0)
+            return index;
+    }
+    throw new Error(`rsdkv4: ${JSON.stringify(value)} is not a value "${row.key}" accepts — try one of ${row.type === 'boolean' ? 'true, false' : (row.values ?? []).join(', ')}`);
 }
-export default { manifest, load };
 //# sourceMappingURL=rsdkv4.sdk.js.map