@wasm-gaming/rsdkv5-wasm 0.1.1 → 0.2.0

package/dist/rsdkv5/rsdkv5.sdk.js

@@ -1,35 +1,120 @@
-// @wasm-gaming/rsdkv5-wasm — SDK entry point.
-import { manifest } from './rsdkv5.manifest.js';
-import { DEFAULT_RSDKV5_OPTIONS } from './rsdkv5.options.js';
-export { manifest };
-const WORK_ROOT = '/data';
+/**
+ * The engine package's entry point: an `EngineSDK` for RSDKv5 (Sonic Mania).
+ *
+ * ```js
+ * import Rsdkv5SDK from '@wasm-gaming/rsdkv5-wasm';
+ *
+ * const play = await new Rsdkv5SDK()
+ *   .assets({ data: () => readDataRsdk() })    // bytes, or a thunk
+ *   .storage({ namespace: 'sonic-mania' })        // → OPFS rsdkv5/sonic-mania/
+ *   .mount(document.querySelector('#stage'))
+ *   .start();
+ *
+ * play.pause('menu'); play.resume('menu');
+ * play.devMenu.getStageList();               // the host draws its own stage select
+ * await play.destroy();                      // save flushed, loop stopped, audio closed
+ * ```
+ *
+ * One game-agnostic `rsdkv5.wasm`: `Data.rsdk` is written into the filesystem at
+ * runtime, never baked in. The working dir `/data/rsdkv5/<namespace>` is in memory;
+ * Sonic Mania writes its user files there (`SaveData.bin`, `TimeAttackDB.bin`,
+ * `ReplayDB.bin`, `Replay_*.bin`). The SDK seeds them from OPFS `rsdkv5/<namespace>/`
+ * before boot and mirrors back whatever changed (every 10 s, on pause, on page hide
+ * and on destroy).
+ */
+import { EnginePlayBase, EngineSDKBase, EventEmitter, } from './engine-specs.js';
+import { RSDKV5_SPEC, RSDKV5_VIDEO, } from './rsdkv5.options.js';
+export { RSDKV5_SPEC, RSDKV5_VIDEO } from './rsdkv5.options.js';
+const ENGINE_ID = 'rsdkv5';
 const DEFAULT_STORAGE_NAMESPACE = 'default';
+const WORK_ROOT = '/data';
+/** Inputs the SDK writes itself; everything else in the working dir is the game's. */
+const NOT_SAVES = new Set(['Data.rsdk', 'Settings.ini', 'log.txt']);
+const SAVE_INTERVAL_MS = 10_000;
+/** Mania's characters, by the `characterID` its save slots store. */
+export const MANIA_CHARACTERS = ['Sonic & Tails', 'Sonic', 'Tails', 'Knuckles', 'Mighty', 'Ray'];
+/** Mania Mode's zones, by the `zoneID` its save slots store. */
+export const MANIA_ZONES = [
+    'Green Hill', 'Chemical Plant', 'Studiopolis', 'Flying Battery', 'Press Garden', 'Stardust Speedway',
+    'Hydrocity', 'Mirage Saloon', 'Oil Ocean', 'Lava Reef', 'Metallic Madness', 'Titanic Monarch', 'Egg Reverie',
+];
+/** Mania Plus's eight regular save slots in `SaveData.bin` (Encore slots are elsewhere). */
+export const MANIA_SAVE_SLOTS = 8;
+const SLOT_BYTES = 0x400;
+const SLOT_FIELDS = 0x58; // SaveRAM: the entity header Mania keeps before the fields
+/**
+ * Mania Mode's save slots from `SaveData.bin` (`globals->saveRAM`, int32 LE): slot `s`
+ * is the 0x400-byte block at `0x400 * s`, fields from +0x58. A missing or short file
+ * reads as empty slots.
+ */
+export function parseManiaSaves(bytes) {
+    const view = bytes ? new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength) : null;
+    return Array.from({ length: MANIA_SAVE_SLOTS }, (_, slot) => {
+        const base = slot * SLOT_BYTES + SLOT_FIELDS;
+        const field = (i) => (view && base + i * 4 + 4 <= view.byteLength ? view.getInt32(base + i * 4, true) : 0);
+        const state = field(0) === 1 ? 'progress' : field(0) === 2 ? 'complete' : 'empty';
+        const character = Math.max(0, Math.min(MANIA_CHARACTERS.length - 1, field(1)));
+        const zone = field(2);
+        let emeralds = 0;
+        for (let mask = field(6) & 0x7f; mask; mask >>= 1)
+            emeralds += mask & 1;
+        return {
+            slot,
+            state,
+            character: state === 'empty' ? 0 : character,
+            zone: state === 'empty' ? 0 : zone,
+            zoneName: state === 'complete' ? 'Complete' : state === 'empty' ? '' : (MANIA_ZONES[zone] ?? 'Unknown zone'),
+            lives: state === 'empty' ? 3 : field(3),
+            score: state === 'empty' ? 0 : field(4),
+            emeralds: state === 'empty' ? 0 : emeralds,
+            continues: state === 'empty' ? 0 : field(7),
+        };
+    });
+}
 /**
- * Serialize engine options into RSDKv5U's Settings.ini format. This is the v5
- * dialect (lowercase keys, 0/1 booleans, `dataFile=` in [Game]) — matching the
- * exact file the proven build preloaded — NOT v4's [Dev]/CamelCase format.
- * `dataFile=Data.rsdk` is load-bearing: it names the pack the engine opens,
- * relative to CWD (the SDK chdir()s into the working dir before callMain).
+ * Where an engine keeps one namespace: `<engineId>/<namespace>`, relative to the OPFS
+ * root. Identical in every wasm-gaming engine, written to move verbatim into
+ * engine-specs: segments cleaned, `.` and `..` dropped, anything outside
+ * `[A-Za-z0-9._-]` → `_`, nothing usable → `default`; a leading `<engineId>/` is
+ * stripped once.
  */
-function buildSettingsIni(options = {}) {
-    const o = { ...DEFAULT_RSDKV5_OPTIONS, ...options };
+export function storagePath(engineId, namespace) {
+    const segments = typeof namespace === 'string'
+        ? namespace
+            .split('/')
+            .map((segment) => segment.trim())
+            .filter((segment) => segment && segment !== '.' && segment !== '..')
+            .map((segment) => segment.replace(/[^A-Za-z0-9._-]/g, '_'))
+        : [];
+    const prefixed = segments.length > 1 && segments[0] === engineId;
+    if (prefixed)
+        segments.shift();
+    const cleaned = segments.join('/') || DEFAULT_STORAGE_NAMESPACE;
+    return { namespace: cleaned, path: `${engineId}/${cleaned}`, prefixed };
+}
+/**
+ * Serialise the engine config into RSDKv5U's `Settings.ini` (capital S — the engine
+ * opens exactly that name, and the Emscripten FS is case-sensitive). The v5 dialect:
+ * lowercase keys, 0/1 booleans, `dataFile=` naming the pack relative to the working dir.
+ */
+export function buildSettingsIni(config) {
     const b = (v) => (v ? '1' : '0');
     return [
         '[Game]',
         'dataFile=Data.rsdk',
-        `devMenu=${b(o.devMenu)}`,
-        `language=${o.language | 0}`,
-        `region=${o.region | 0}`,
+        `devMenu=${b(config.devMenu)}`,
+        `language=${(config.language ?? 0) | 0}`,
+        `region=${(config.region ?? -1) | 0}`,
         '',
         '[Video]',
         'windowed=1',
         'border=1',
         'exclusiveFS=0',
-        `vsync=${b(o.vsync)}`,
+        `vsync=${b(config.vsync ?? true)}`,
         'tripleBuffering=0',
-        'pixWidth=424',
-        'winWidth=424',
-        'winHeight=240',
+        `pixWidth=${RSDKV5_VIDEO.width}`,
+        `winWidth=${RSDKV5_VIDEO.width}`,
+        `winHeight=${RSDKV5_VIDEO.height}`,
         'fsWidth=0',
         'fsHeight=0',
         'refreshRate=60',
@@ -43,192 +128,400 @@ function buildSettingsIni(options = {}) {
         '',
     ].join('\n');
 }
-function toUint8(x) {
-    if (x == null)
+async function opfsDir(path, create) {
+    if (typeof navigator === 'undefined' || !navigator.storage?.getDirectory)
         return null;
-    if (typeof x === 'string')
-        return new TextEncoder().encode(x);
-    if (x instanceof Uint8Array)
-        return x;
-    if (x instanceof ArrayBuffer)
-        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');
+    try {
+        let dir = await navigator.storage.getDirectory();
+        for (const segment of path.split('/').filter(Boolean)) {
+            dir = await dir.getDirectoryHandle(segment, { create });
+        }
+        return dir;
+    }
+    catch {
+        return null;
+    }
 }
-/** Normalize a user-provided storage namespace into a safe relative path. */
-function normalizeStorageNamespace(namespace) {
-    if (typeof namespace !== 'string' || !namespace.trim())
-        return DEFAULT_STORAGE_NAMESPACE;
-    const cleaned = namespace
-        .split('/')
-        .map((segment) => segment.trim())
-        .filter(Boolean)
-        .map((segment) => segment.replace(/[^A-Za-z0-9._-]/g, '_'))
-        .filter(Boolean)
-        .join('/');
-    return cleaned || DEFAULT_STORAGE_NAMESPACE;
+async function resolveAsset(asset) {
+    const value = typeof asset === 'function' ? await asset() : asset;
+    if (value == null)
+        return null;
+    if (value instanceof Uint8Array)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    throw new TypeError('rsdkv5: an asset must be a Uint8Array, an ArrayBuffer or a thunk returning one');
 }
-/** Best-effort mkdir -p for the Emscripten FS layer. */
-function ensureDir(Module, path) {
-    const parts = path.split('/').filter(Boolean);
+function sameBytes(a, b) {
+    if (!a || a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+function mkdirp(Module, path) {
     let current = '';
-    for (const part of parts) {
+    for (const part of path.split('/').filter(Boolean)) {
         current += `/${part}`;
         try {
             Module.FS.mkdir(current);
         }
         catch {
-            /* already exists */
+            /* exists */
         }
     }
 }
-/** Mount the game working directory. */
-function mountWorkingDir(Module, storageNamespace) {
-    const workDir = `${WORK_ROOT}/${storageNamespace}`;
-    ensureDir(Module, workDir);
-    return { persistent: false, workDir };
-}
-/** True if `path` exists in the (mounted) filesystem. */
-function fileExists(Module, path) {
-    try {
-        Module.FS.stat(path);
-        return true;
+/** The live engine: one booted RSDKv5 and its session. */
+export class Rsdkv5Play extends EnginePlayBase {
+    #module = null;
+    #destroyed = false;
+    #pauseOwner = null;
+    #muted = false;
+    #canvas = null;
+    #ownsCanvas = false;
+    #box = null;
+    #boxObserver = null;
+    #namespace = DEFAULT_STORAGE_NAMESPACE;
+    #storagePath = `${ENGINE_ID}/${DEFAULT_STORAGE_NAMESPACE}`;
+    #workDir = `${WORK_ROOT}/${ENGINE_ID}/${DEFAULT_STORAGE_NAMESPACE}`;
+    #persist = true;
+    #saveTimer = null;
+    #lastSaved = new Map();
+    #flushing = null;
+    #onHidden = () => {
+        if (document.visibilityState === 'hidden')
+            void this.flushSaves();
+    };
+    constructor(init, events) {
+        super(RSDKV5_SPEC, init, events);
     }
-    catch {
-        return false;
+    get namespace() {
+        return this.#namespace;
     }
-}
-/** 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;
+    /** Where this session's files live, relative to the OPFS root: `rsdkv5/<namespace>`. */
+    get storagePath() {
+        return this.#storagePath;
     }
-    catch {
-        return false;
+    get pausedBy() {
+        return this.#pauseOwner;
     }
-}
-/** Boot the RSDKv5 engine. */
-export async function load(config) {
-    const { canvas, assets, onEvent } = config;
-    const options = config.options;
-    if (!canvas)
-        throw new Error('rsdkv5: config.canvas is required');
-    // Emscripten's SDL2 port locates the canvas via document.querySelector('#canvas').
-    if (canvas.id !== 'canvas')
-        canvas.id = 'canvas';
-    const emit = (e) => {
-        try {
-            onEvent?.(e);
+    /** Mania Mode's save slots — see {@link ManiaSaves}. */
+    get saves() {
+        const Module = this.#module;
+        const workDir = this.#workDir;
+        const available = !!Module?._web_mania_save_status && !!Module._web_mania_start_slot;
+        return {
+            available,
+            characters: available && Module?._web_mania_characters ? Module._web_mania_characters() : 4,
+            list: () => {
+                let bytes = null;
+                try {
+                    bytes = Module ? new Uint8Array(Module.FS.readFile(`${workDir}/SaveData.bin`)) : null;
+                }
+                catch {
+                    bytes = null; // no save file yet: eight empty slots
+                }
+                return parseManiaSaves(bytes);
+            },
+            ready: async (timeoutMs = 5000) => {
+                if (!available || !Module)
+                    return false;
+                const deadline = performance.now() + timeoutMs;
+                for (;;) {
+                    const status = Module._web_mania_save_status();
+                    if (status === 200)
+                        return true;
+                    if ((status !== 0 && status !== 100) || performance.now() > deadline)
+                        return false;
+                    await new Promise((resolve) => setTimeout(resolve, 50));
+                }
+            },
+            start: (slot, character = 0) => {
+                if (!available || !Module)
+                    return false;
+                if (!Module._web_mania_start_slot(slot | 0, character | 0))
+                    return false;
+                // Whatever drove this is done with the engine: hand it back running.
+                if (this.#pauseOwner)
+                    this.resume(this.#pauseOwner);
+                return true;
+            },
+        };
+    }
+    /** RSDKv5's stage list, for a host that draws its own stage select. */
+    get devMenu() {
+        const Module = () => this.#module;
+        return {
+            getStageList() {
+                try {
+                    return JSON.parse(Module()?.web_devmenu_get_stage_list?.() ?? '[]');
+                }
+                catch {
+                    return [];
+                }
+            },
+            loadStage(category, stage) {
+                Module()?.web_devmenu_load_stage?.(category | 0, stage | 0);
+            },
+        };
+    }
+    /**
+     * Freeze the game and its sound. The first caller owns the pause; only that
+     * owner's {@link resume} lifts it. The save is flushed.
+     */
+    pause(owner = 'host') {
+        const Module = this.#module;
+        if (!Module || this.#pauseOwner)
+            return;
+        this.#pauseOwner = owner;
+        Module.web_devmenu_set_paused?.(true);
+        // This build has no native pause hook (web_devmenu_* are not compiled in), so the
+        // game is frozen by stopping emscripten's main loop: no frame runs until resume().
+        Module.pauseMainLoop?.();
+        void Module.SDL2?.audioContext?.suspend();
+        void this.flushSaves();
+        this.emit('pause', { owner });
+    }
+    resume(owner = 'host') {
+        const Module = this.#module;
+        if (!Module || this.#pauseOwner !== owner)
+            return;
+        this.#pauseOwner = null;
+        if (!this.#muted)
+            void Module.SDL2?.audioContext?.resume();
+        Module.web_devmenu_set_paused?.(false);
+        Module.resumeMainLoop?.();
+        this.emit('resume', { owner });
+    }
+    /**
+     * Silence the game without stopping it (the frames keep running). A host uses it to
+     * let Mania get somewhere — load its save file — behind its own screen. Independent
+     * of {@link pause}: a paused game stays silent either way.
+     */
+    mute(muted = true) {
+        this.#muted = muted;
+        const context = this.#module?.SDL2?.audioContext;
+        if (muted)
+            void context?.suspend();
+        else if (!this.#pauseOwner)
+            void context?.resume();
+    }
+    get muted() {
+        return this.#muted;
+    }
+    /** Copy the game's changed user files to OPFS `rsdkv5/<namespace>/`; emits `saves`. */
+    flushSaves() {
+        this.#flushing ??= this.#flush().finally(() => {
+            this.#flushing = null;
+        });
+        return this.#flushing;
+    }
+    // ---- Contract hooks ----
+    mounted(target) {
+        if (target instanceof HTMLCanvasElement) {
+            this.#canvas = target;
+            this.#ownsCanvas = false;
+            this.#box = target.parentElement;
         }
-        catch { /* host handler must not break us */ }
-    };
-    const jsUrl = config.jsUrl ?? new URL('./rsdkv5.js', import.meta.url).href;
-    const wasmUrl = config.wasmUrl ?? new URL('./rsdkv5.wasm', import.meta.url).href;
-    // RSDKv5 uses the same key map preset used by the shared launcher script.
-    if (typeof window !== 'undefined')
-        window.__gamepadKeyMap = manifest.input;
-    const mod = await import(/* @vite-ignore */ jsUrl);
-    const createRSDKv5 = mod.default;
-    const Module = await createRSDKv5({
-        canvas,
-        noInitialRun: true,
-        locateFile: (path) => (path.endsWith('.wasm') ? wasmUrl : path),
-        print: (...a) => console.log('[rsdkv5]', ...a),
-        printErr: (...a) => console.error('[rsdkv5]', ...a),
-        onAbort: (reason) => emit({ type: 'error', error: new Error(`rsdkv5 aborted: ${reason}`) }),
-    });
-    const storageNamespace = normalizeStorageNamespace(config.storageNamespace);
-    const { persistent, workDir } = mountWorkingDir(Module, storageNamespace);
-    const dataPath = `${workDir}/Data.rsdk`;
-    // Capital S: RSDKv5U opens "Settings.ini" and the Emscripten FS is
-    // case-sensitive (v4 used lowercase settings.ini — do not copy that here).
-    const settingsPath = `${workDir}/Settings.ini`;
-    // Data.rsdk — precedence: explicit asset > lazy provider > existing file.
-    let dataBytes = toUint8(assets?.data);
-    if (!dataBytes && config.dataProvider) {
-        dataBytes = toUint8(await config.dataProvider());
-    }
-    if (dataBytes) {
-        Module.FS.writeFile(dataPath, dataBytes);
-    }
-    else if (!fileExists(Module, dataPath)) {
-        throw new Error('rsdkv5: no Data.rsdk — provide assets.data or dataProvider');
-    }
-    // settings.ini — explicit asset > lazy provider > generated from options.
-    let settingsBytes = toUint8(assets?.settings);
-    if (!settingsBytes && config.settingsProvider) {
-        settingsBytes = toUint8(await config.settingsProvider());
-    }
-    if (settingsBytes) {
-        Module.FS.writeFile(settingsPath, settingsBytes);
-    }
-    else if (!fileExists(Module, settingsPath)) {
-        Module.FS.writeFile(settingsPath, new TextEncoder().encode(buildSettingsIni(options)));
-    }
-    Module.FS.chdir(workDir);
-    const setPaused = (paused) => {
-        if (typeof Module.web_devmenu_set_paused === 'function')
-            Module.web_devmenu_set_paused(paused);
-    };
-    const devMenu = {
-        getStageList() {
-            if (typeof Module.web_devmenu_get_stage_list !== 'function')
-                return [];
+        else {
+            this.#canvas = document.createElement('canvas');
+            this.#ownsCanvas = true;
+            this.#box = target;
+            target.appendChild(this.#canvas);
+        }
+        // Emscripten's SDL2 port finds its window with querySelector('#canvas').
+        this.#canvas.id = 'canvas';
+        this.#canvas.tabIndex = 0;
+        this.#canvas.style.display = 'block';
+        this.#canvas.style.imageRendering = 'pixelated';
+        this.#canvas.addEventListener('contextmenu', (event) => event.preventDefault());
+        if (this.#ownsCanvas && this.#box) {
+            this.#boxObserver?.disconnect();
+            this.#boxObserver = new ResizeObserver(() => this.#fit());
+            this.#boxObserver.observe(this.#box);
+        }
+    }
+    async open(_options) {
+        if (this.#destroyed || this.#module) {
+            // RSDKv5 cannot restart in process: main() runs once and owns the loop.
+            throw new Error('rsdkv5: the engine cannot be restarted in process — destroy() and start a new page (or iframe)');
+        }
+        await this.#boot();
+    }
+    patched(_kind, _patch) {
+        // Nothing in RSDKV5_SPEC is live: Settings.ini is read once, at boot.
+    }
+    async close() {
+        if (this.#saveTimer)
+            clearInterval(this.#saveTimer);
+        this.#saveTimer = null;
+        document.removeEventListener('visibilitychange', this.#onHidden);
+        window.removeEventListener('pagehide', this.#onHidden);
+        const Module = this.#module;
+        if (Module) {
+            await this.flushSaves();
             try {
-                return JSON.parse(Module.web_devmenu_get_stage_list());
+                Module.web_devmenu_set_paused?.(true);
+                Module.pauseMainLoop?.();
             }
-            catch (e) {
-                console.error('[rsdkv5] getStageList failed', e);
-                return [];
+            catch {
+                /* already stopped */
             }
-        },
-        loadStage(categoryIdx, stageIdx) {
-            if (typeof Module.web_devmenu_load_stage === 'function') {
-                Module.web_devmenu_load_stage(categoryIdx | 0, stageIdx | 0);
+            try {
+                await Module.SDL2?.audioContext?.close();
             }
-        },
-        setPaused,
-    };
-    // No 'UsingCWD' argv — that's a v4-ism; v5U's main() doesn't parse it. The
-    // engine resolves Settings.ini/dataFile relative to the FS CWD set above.
-    Module.callMain([]);
-    emit({ type: 'ready' });
-    return {
-        start() { },
-        pause() { setPaused(true); },
-        resume() { setPaused(false); },
-        reset() {
-            throw new Error('rsdkv5: reset() is not supported — destroy() and load() again');
-        },
-        setInput(preset) {
-            if (typeof window !== 'undefined') {
-                window.__gamepadKeyMap = preset ?? manifest.input;
+            catch {
+                /* already closed */
             }
-        },
-        destroy() {
+        }
+        this.#boxObserver?.disconnect();
+        this.#boxObserver = null;
+        if (this.#ownsCanvas)
+            this.#canvas?.remove();
+        this.#canvas = null;
+        this.#module = null;
+        this.#pauseOwner = null;
+        this.#destroyed = true;
+    }
+    // ---- Boot ----
+    async #boot() {
+        const config = await this.#values('config');
+        const assets = await this.#values('assets');
+        const storage = await this.#values('storage');
+        if (!this.#canvas)
+            throw new Error('rsdkv5: mount() an element (or a canvas) before start()');
+        const data = await resolveAsset(assets.data);
+        if (!data)
+            throw new Error('rsdkv5: no Data.rsdk — hand one over as assets.data (bytes or a thunk)');
+        const settings = await resolveAsset(assets.settings);
+        const resolved = storagePath(ENGINE_ID, storage.namespace);
+        if (resolved.prefixed) {
+            console.warn(`[rsdkv5] storage.namespace no longer needs the "${ENGINE_ID}/" prefix. Pass "${resolved.namespace}".`);
+        }
+        this.#namespace = resolved.namespace;
+        this.#storagePath = resolved.path;
+        this.#workDir = `${WORK_ROOT}/${resolved.path}`;
+        this.#persist = storage.persist !== null;
+        const jsUrl = config.jsUrl ?? new URL('./rsdkv5.js', import.meta.url).href;
+        const wasmUrl = config.wasmUrl ?? new URL('./rsdkv5.wasm', import.meta.url).href;
+        const { default: createRSDKv5 } = (await import(/* @vite-ignore */ jsUrl));
+        let failed = null;
+        const Module = await createRSDKv5({
+            canvas: this.#canvas,
+            noInitialRun: true,
+            locateFile: (path) => (path.endsWith('.wasm') ? wasmUrl : new URL(path, jsUrl).href),
+            print: (text) => console.log('[rsdkv5]', text),
+            printErr: (text) => console.warn('[rsdkv5]', text),
+            onAbort: (what) => failed?.(new Error(`rsdkv5: aborted — ${String(what)}`)),
+        });
+        this.#module = Module;
+        failed = (error) => this.emit('error', error);
+        mkdirp(Module, this.#workDir);
+        Module.FS.writeFile(`${this.#workDir}/Data.rsdk`, data);
+        Module.FS.writeFile(`${this.#workDir}/Settings.ini`, settings ?? new TextEncoder().encode(buildSettingsIni(config)));
+        if (this.#persist)
+            await this.#restoreSave();
+        Module.FS.chdir(this.#workDir);
+        // RSDKv5U resolves Settings.ini and dataFile relative to the CWD set above.
+        Module.callMain([]);
+        if (this.#persist) {
+            this.#saveTimer = setInterval(() => void this.flushSaves(), SAVE_INTERVAL_MS);
+            document.addEventListener('visibilitychange', this.#onHidden);
+            window.addEventListener('pagehide', this.#onHidden);
+        }
+        this.#fit();
+    }
+    async #values(kind) {
+        const described = (await this[kind]());
+        const out = {};
+        for (const [key, property] of Object.entries(described))
+            out[key] = property.value;
+        return out;
+    }
+    // ---- Save mirror ----
+    async #restoreSave() {
+        const dir = await opfsDir(this.#storagePath, false);
+        if (!dir || !this.#module)
+            return;
+        const iterable = dir;
+        for await (const [name, handle] of iterable.entries()) {
+            if (handle.kind !== 'file' || NOT_SAVES.has(name))
+                continue;
+            const bytes = new Uint8Array(await (await handle.getFile()).arrayBuffer());
+            this.#module.FS.writeFile(`${this.#workDir}/${name}`, bytes);
+            this.#lastSaved.set(name, bytes);
+        }
+    }
+    async #flush() {
+        const Module = this.#module;
+        if (!Module || !this.#persist)
+            return;
+        const changed = [];
+        let names;
+        try {
+            names = Module.FS.readdir(this.#workDir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (name === '.' || name === '..' || NOT_SAVES.has(name))
+                continue;
+            const path = `${this.#workDir}/${name}`;
+            if (!Module.FS.isFile(Module.FS.stat(path).mode))
+                continue;
+            const bytes = new Uint8Array(Module.FS.readFile(path));
+            if (!sameBytes(this.#lastSaved.get(name) ?? null, bytes))
+                changed.push([name, bytes]);
+        }
+        if (changed.length === 0)
+            return;
+        const dir = await opfsDir(this.#storagePath, true);
+        if (!dir)
+            return;
+        const written = [];
+        for (const [name, bytes] of changed) {
             try {
-                Module.pauseMainLoop?.();
+                const writable = await (await dir.getFileHandle(name, { create: true })).createWritable();
+                await writable.write(bytes);
+                await writable.close();
+                this.#lastSaved.set(name, bytes);
+                written.push(name);
             }
-            catch { /* noop */ }
-            try {
-                setPaused(true);
+            catch (e) {
+                console.warn(`[rsdkv5] could not persist ${name}`, e);
             }
-            catch { /* noop */ }
-        },
-        devMenu,
-        persistent,
-        storageNamespace,
-        purgeStorage() {
-            return {
-                data: deleteFileIfExists(Module, dataPath),
-                settings: deleteFileIfExists(Module, settingsPath),
-            };
-        },
-    };
+        }
+        if (written.length)
+            this.emit('saves', { files: written });
+    }
+    // ---- Picture ----
+    #fit() {
+        const canvas = this.#canvas;
+        const box = this.#box;
+        if (!canvas || !box || !this.#ownsCanvas)
+            return;
+        const { width, height } = box.getBoundingClientRect();
+        if (!width || !height)
+            return;
+        const scale = Math.min(width / RSDKV5_VIDEO.width, height / RSDKV5_VIDEO.height);
+        canvas.style.width = `${Math.floor(RSDKV5_VIDEO.width * scale)}px`;
+        canvas.style.height = `${Math.floor(RSDKV5_VIDEO.height * scale)}px`;
+    }
+}
+/** The factory a host constructs: static identity, the configuration chain, `start()`. */
+export class Rsdkv5SDK extends EngineSDKBase {
+    static id = ENGINE_ID;
+    /** Kept in step with package.json by `node scripts/sync-version.mjs`. */
+    static version = '0.2.0';
+    static name = 'Retro Software Development Kit v3';
+    static description = 'RSDKv5U (Sonic Mania decompilation) compiled to WebAssembly. Ships none of the game: the player provides Data.rsdk, and it never leaves their browser.';
+    createPlay(init, events) {
+        return new Rsdkv5Play(init, events);
+    }
 }
-export default { manifest, load };
+/** CI's conformance line: if this class stops satisfying the contract, `make test` fails. */
+export const RSDKV5_ENGINE = Rsdkv5SDK;
+export default Rsdkv5SDK;
 //# sourceMappingURL=rsdkv5.sdk.js.map