@wasm-gaming/fbneo-wasm 0.1.2 → 0.2.0

package/dist/fbneo/fbneo.sdk.js

@@ -1,199 +1,603 @@
-import { manifest } from './fbneo.manifest.js';
-import { DEFAULT_FBNEO_OPTIONS } from './fbneo.options.js';
-export { manifest };
-const scriptLoadCache = new Map();
-function loadClassicScriptOnce(src) {
-    const cached = scriptLoadCache.get(src);
-    if (cached)
-        return cached;
-    const p = new Promise((resolve, reject) => {
-        const script = document.createElement('script');
-        script.src = src;
-        script.async = true;
-        script.onload = () => resolve();
-        script.onerror = () => reject(new Error(`fbneo: failed to load script: ${src}`));
-        document.head.appendChild(script);
-    });
-    scriptLoadCache.set(src, p);
-    return p;
+/**
+ * The engine package's entry point: an `EngineSDK` for FBNeo (FinalBurn Neo), the
+ * arcade emulator.
+ *
+ * ```js
+ * import FbneoSDK from '@wasm-gaming/fbneo-wasm';
+ *
+ * const play = await new FbneoSDK()
+ *   .options({ driver: 'mslug' })                       // or romFileName: 'mslug.zip'
+ *   .assets({ rom: () => readZip(), bios: () => readBios() })
+ *   .storage({ namespace: 'mslug' })                    // → OPFS fbneo/mslug/
+ *   .mount(document.querySelector('#stage'))
+ *   .start();
+ *
+ * play.pause('menu'); play.resume('menu');
+ * await play.restart();                                  // soft reset
+ * await play.destroy();                                  // saves flushed, loop stopped
+ * ```
+ *
+ * Everything a host drives is the contract's (`@wasm-gaming/engine-specs`); what is
+ * this engine's own: {@link FbneoConfig} and friends, owner-aware
+ * {@link FbneoPlay.pause} / {@link FbneoPlay.resume}, {@link FbneoPlay.states},
+ * {@link FbneoPlay.storagePath} and the `saves` event.
+ *
+ * Saves: the build points FBNeo's NVRAM/EEPROM and hiscore paths at MEMFS `/save`.
+ * The SDK seeds it from OPFS `fbneo/<namespace>/` before boot and mirrors it back
+ * after asking FBNeo to write (`web_persist`): every 10 s, on pause, when the page is
+ * hidden and on destroy. Upstream only wrote at exit, which a web page never reaches.
+ */
+import { EnginePlayBase, EngineSDKBase, EventEmitter, } from './engine-specs.js';
+import { FBNEO_SPEC, FBNEO_VIDEO, } from './fbneo.options.js';
+export { FBNEO_SPEC, FBNEO_VIDEO } from './fbneo.options.js';
+const ENGINE_ID = 'fbneo';
+const DEFAULT_STORAGE_NAMESPACE = 'default';
+const SAVE_DIR = '/save';
+/**
+ * FBNeo's ROM search paths (src/burner/sdl/drv.cpp): the absolute one is always
+ * searched; `/roms` covers the cwd-relative `roms/` with the cwd at `/`.
+ */
+const ROM_DIRS = ['/usr/local/share/roms', '/roms'];
+const SAVE_INTERVAL_MS = 10_000;
+/** How long a ROM set may take to load before start() gives up. */
+const LOAD_TIMEOUT_MS = 30_000;
+/**
+ * Where an engine keeps one namespace: `<engineId>/<namespace>`, relative to the OPFS
+ * root. Identical to the other engines': segments cleaned, `.` and `..` dropped,
+ * anything outside `[A-Za-z0-9._-]` → `_`, nothing usable → `default`; a leading
+ * `<engineId>/` is stripped once.
+ */
+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 };
 }
-function toUint8(x) {
-    if (x == null)
+/**
+ * The FBNeo driver for a session: `driver` when given, else the ROM file name's stem
+ * (`mslug.zip`, `C:\roms\mslug.7z` → `mslug`). Empty when neither says.
+ */
+export function driverName(options) {
+    const explicit = options.driver?.trim();
+    if (explicit)
+        return explicit;
+    const base = (options.romFileName ?? '').replace(/^.*[\\/]/, '');
+    return base.replace(/\.(zip|7z)$/i, '').trim();
+}
+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('fbneo: 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;
+    }
 }
-/** Strip a directory and extension from a zip filename to get the FBNeo driver name. */
-function driverFromFileName(fileName) {
-    const base = fileName.replace(/^.*[\\/]/, '');
-    return base.replace(/\.(zip|7z)$/i, '');
+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('fbneo: an asset must be a Uint8Array, an ArrayBuffer or a thunk returning one');
 }
-/**
- * Resolve the render canvas from the contract's `EngineConfig`.
- * The contract is a union: hosts pass either `canvasEl` (a render target) or
- * `attachTo` (a container the SDK mounts its own canvas into). Legacy `canvas`
- * is still accepted as a defensive fallback for hosts built against 0.1.x.
- */
-function resolveCanvas(config) {
-    const c = config.canvasEl ??
-        config.canvas;
-    if (c)
-        return c;
-    const attachTo = config.attachTo;
-    if (attachTo) {
-        const existing = attachTo.querySelector('canvas');
-        if (existing)
-            return existing;
-        const created = document.createElement('canvas');
-        attachTo.appendChild(created);
-        return created;
-    }
-    throw new Error('fbneo: config.canvasEl or config.attachTo is required');
+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;
 }
+/** The player's save-state slots: 0-3. */
+export const STATE_SLOTS = 4;
 /**
- * Ensure the canvas used by FBNeo has `id="canvas"`.
- * Emscripten SDL2 queries `document.querySelector('#canvas')` to locate its render target.
+ * The *unsaved* suspend point: written when the player leaves, offered when they come
+ * back, and saved into a numbered slot only when they ask.
  */
-function prepareCanvas(canvas, renderFilter) {
-    if (canvas.id !== 'canvas')
+export const AUTO_STATE_SLOT = 9;
+const nextFrame = () => new Promise((resolve) => requestAnimationFrame(() => resolve()));
+const mtimeOf = (value) => value instanceof Date ? value.getTime() : typeof value === 'number' ? value : 0;
+/** The live engine: one booted FBNeo and its session. */
+export class FbneoPlay extends EnginePlayBase {
+    #module = null;
+    #destroyed = false;
+    #pauseOwner = null;
+    #driver = '';
+    #canvas = null;
+    #ownsCanvas = false;
+    #box = null;
+    #boxObserver = null;
+    #canvasObserver = null;
+    #namespace = DEFAULT_STORAGE_NAMESPACE;
+    #storagePath = `${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(FBNEO_SPEC, init, events);
+    }
+    /** The normalised namespace this session uses. */
+    get namespace() {
+        return this.#namespace;
+    }
+    /** Where this session's saves live, relative to the OPFS root: `fbneo/<namespace>`. */
+    get storagePath() {
+        return this.#storagePath;
+    }
+    /** The driver (ROM-set short name) this session booted. */
+    get driver() {
+        return this.#driver;
+    }
+    /** Who holds the pause, or null while running. */
+    get pausedBy() {
+        return this.#pauseOwner;
+    }
+    /**
+     * The current frame as a PNG (also while paused: the picture is kept). Null when
+     * there is nothing to read.
+     */
+    async snapshot() {
+        const canvas = this.#canvas;
+        if (!canvas || !this.#module)
+            return null;
+        await nextFrame();
+        const copy = document.createElement('canvas');
+        copy.width = canvas.width || FBNEO_VIDEO.width;
+        copy.height = canvas.height || FBNEO_VIDEO.height;
+        copy.getContext('2d')?.drawImage(canvas, 0, 0, copy.width, copy.height);
+        return new Promise((resolve) => copy.toBlob((blob) => resolve(blob), 'image/png'));
+    }
+    /** Save states — see {@link FbneoStates}. */
+    get states() {
+        const Module = this.#requireModule();
+        const { FS } = Module;
+        const file = (name) => `${SAVE_DIR}/${name}`;
+        const exists = (name) => {
+            try {
+                FS.stat(file(name));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        const stateName = (slot) => `slot_${slot}.fs`;
+        const mtime = (name) => {
+            try {
+                return mtimeOf(FS.stat(file(name)).mtime);
+            }
+            catch {
+                return null;
+            }
+        };
+        const checkSlot = (slot) => {
+            if (slot === AUTO_STATE_SLOT || (Number.isInteger(slot) && slot >= 0 && slot < STATE_SLOTS))
+                return slot;
+            throw new RangeError(`fbneo: a state slot is 0-${STATE_SLOTS - 1} or ${AUTO_STATE_SLOT}, not ${slot}`);
+        };
+        const isLocked = (slot) => exists(`slot_${slot}.lock`);
+        const refuseLocked = (slot) => {
+            if (isLocked(slot))
+                throw new Error(`fbneo: state slot ${slot} is locked`);
+        };
+        // Removed files have to leave OPFS too: the mirror only ever writes.
+        const forget = async (names) => {
+            for (const name of names) {
+                try {
+                    FS.unlink(file(name));
+                }
+                catch {
+                    /* not there */
+                }
+                this.#lastSaved.delete(name);
+            }
+            const dir = this.#persist ? await opfsDir(this.#storagePath, false) : null;
+            for (const name of names)
+                await dir?.removeEntry(name).catch(() => { });
+        };
+        const get = (slot) => {
+            checkSlot(slot);
+            const savedAt = mtime(stateName(slot));
+            let thumbnail = null;
+            if (savedAt !== null && exists(`slot_${slot}.png`)) {
+                thumbnail = new Blob([new Uint8Array(FS.readFile(file(`slot_${slot}.png`)))], { type: 'image/png' });
+            }
+            return { slot, savedAt: savedAt === null ? null : new Date(savedAt), thumbnail, locked: isLocked(slot) };
+        };
+        return {
+            list: () => Array.from({ length: STATE_SLOTS }, (_, slot) => get(slot)),
+            get,
+            save: async (slot, options = {}) => {
+                checkSlot(slot);
+                refuseLocked(slot);
+                // FBNeo writes the state at once (between frames: JS only runs while its loop sleeps).
+                if (!Module._web_save_state(slot))
+                    throw new Error('fbneo: the state could not be saved (no game running?)');
+                if (options.thumbnail) {
+                    FS.writeFile(file(`slot_${slot}.png`), new Uint8Array(await options.thumbnail.arrayBuffer()));
+                }
+                else
+                    await forget([`slot_${slot}.png`]);
+                await this.flushSaves();
+            },
+            load: (slot) => {
+                checkSlot(slot);
+                if (mtime(stateName(slot)) === null)
+                    return false;
+                return Module._web_load_state(slot) !== 0;
+            },
+            copy: async (from, to) => {
+                checkSlot(from);
+                checkSlot(to);
+                refuseLocked(to);
+                if (mtime(stateName(from)) === null)
+                    throw new Error(`fbneo: state slot ${from} is empty`);
+                await forget([stateName(to), `slot_${to}.png`]);
+                FS.writeFile(file(stateName(to)), new Uint8Array(FS.readFile(file(stateName(from)))));
+                if (exists(`slot_${from}.png`)) {
+                    FS.writeFile(file(`slot_${to}.png`), new Uint8Array(FS.readFile(file(`slot_${from}.png`))));
+                }
+                await this.flushSaves();
+            },
+            lock: async (slot, locked) => {
+                checkSlot(slot);
+                if (locked) {
+                    if (mtime(stateName(slot)) === null)
+                        throw new Error(`fbneo: state slot ${slot} is empty`);
+                    FS.writeFile(file(`slot_${slot}.lock`), new Uint8Array([1]));
+                    await this.flushSaves();
+                }
+                else {
+                    await forget([`slot_${slot}.lock`]);
+                    this.emit('saves', { files: [`slot_${slot}.lock`] });
+                }
+            },
+            remove: async (slot) => {
+                checkSlot(slot);
+                refuseLocked(slot);
+                const names = [stateName(slot), `slot_${slot}.png`];
+                await forget(names);
+                this.emit('saves', { files: names });
+            },
+        };
+    }
+    #requireModule() {
+        if (!this.#module)
+            throw new Error('fbneo: the engine is not running — start() it first');
+        return this.#module;
+    }
+    /**
+     * Freeze emulation and sound. The first caller owns the pause, and only that
+     * owner's {@link resume} lifts it, so an overlay cannot resume a game the host had
+     * already frozen. Saves are flushed, since a paused game is often a closed one.
+     */
+    pause(owner = 'host') {
+        const Module = this.#module;
+        if (!Module || this.#pauseOwner)
+            return;
+        this.#pauseOwner = owner;
+        Module._web_set_paused(1);
+        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;
+        void Module.SDL2?.audioContext?.resume();
+        Module._web_set_paused(0);
+        this.emit('resume', { owner });
+    }
+    /**
+     * Ask FBNeo to write its NVRAM, then copy whatever changed in `/save` to OPFS
+     * `fbneo/<namespace>/`. Emits `saves` with the files that moved. Safe to call any
+     * time; overlapping calls share one flush.
+     */
+    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;
+        }
+        else {
+            this.#canvas = document.createElement('canvas');
+            this.#ownsCanvas = true;
+            this.#box = target;
+            target.appendChild(this.#canvas);
+        }
+        const canvas = this.#canvas;
+        // Emscripten's SDL2 finds its window by id, and measures the element: no border or
+        // padding on the canvas itself, or SDL creates a tiny window.
         canvas.id = 'canvas';
-    if (!canvas.width)
-        canvas.width = manifest.video.baseWidth;
-    if (!canvas.height)
-        canvas.height = manifest.video.baseHeight;
-    // SDL2's Emscripten backend measures getBoundingClientRect() (borders/padding
-    // included) to detect external CSS sizing; decoration on the canvas itself
-    // makes it create a tiny window. Host pages should decorate a wrapper instead.
-    canvas.style.border = '0';
-    canvas.style.padding = '0';
-    canvas.style.imageRendering = renderFilter === 'pixelated' ? 'pixelated' : 'auto';
-    return canvas;
-}
-export async function load(config) {
-    const { assets, onEvent } = config;
-    const emit = (e) => {
+        if (!canvas.width)
+            canvas.width = FBNEO_VIDEO.width;
+        if (!canvas.height)
+            canvas.height = FBNEO_VIDEO.height;
+        canvas.tabIndex = 0;
+        canvas.style.border = '0';
+        canvas.style.padding = '0';
+        canvas.style.display = 'block';
+        canvas.addEventListener('contextmenu', (event) => event.preventDefault());
+        void this.#applyFilter();
+        if (this.#box && this.#ownsCanvas) {
+            this.#boxObserver?.disconnect();
+            this.#boxObserver = new ResizeObserver(() => this.#fit());
+            this.#boxObserver.observe(this.#box);
+            // FBNeo sizes the canvas to each game's picture (vertical games too): refit then.
+            this.#canvasObserver?.disconnect();
+            this.#canvasObserver = new MutationObserver(() => this.#fit());
+            this.#canvasObserver.observe(canvas, { attributes: true, attributeFilter: ['width', 'height'] });
+            this.#fit();
+        }
+    }
+    async open(_options) {
+        if (this.#destroyed) {
+            throw new Error('fbneo: this engine has been destroyed and cannot be started again in this page — build a new FbneoSDK in a new page');
+        }
+        if (this.#module) {
+            // Already running: a restart is the machine's soft reset.
+            if (this.#pauseOwner)
+                this.resume(this.#pauseOwner);
+            this.#module._web_reset();
+            return;
+        }
+        await this.#boot();
+    }
+    patched(kind, patch) {
+        if (kind === 'config' && 'renderFilter' in patch)
+            void this.#applyFilter();
+    }
+    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();
+            const context = Module.SDL2?.audioContext;
+            try {
+                Module._web_set_paused(1);
+                // Ends FBNeo's loop: it exits the game its own way (NVRAM written, sound closed).
+                Module._web_quit();
+            }
+            catch {
+                /* already gone */
+            }
+            // FBNeo's exit closes the AudioContext on the loop's next turn; close it here only
+            // if it didn't (closing it first makes FBNeo's own close throw).
+            const deadline = performance.now() + 1000;
+            while (context && context.state !== 'closed' && performance.now() < deadline) {
+                await new Promise((resolve) => setTimeout(resolve, 50));
+            }
+            if (context && context.state !== 'closed')
+                await context.close().catch(() => { });
+        }
+        this.#boxObserver?.disconnect();
+        this.#boxObserver = null;
+        this.#canvasObserver?.disconnect();
+        this.#canvasObserver = 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 options = await this.#values('options');
+        const assets = await this.#values('assets');
+        const storage = await this.#values('storage');
+        if (!this.#canvas) {
+            throw new Error('fbneo: mount() an element (or a canvas) before start()');
+        }
+        const driver = driverName(options);
+        if (!driver) {
+            throw new Error('fbneo: which game is it? Pass options.driver (the FBNeo short name, e.g. "mslug") ' +
+                'or options.romFileName named after it (mslug.zip).');
+        }
+        const rom = await resolveAsset(assets.rom);
+        if (!rom)
+            throw new Error('fbneo: no ROM set — hand one over as assets.rom (bytes or a thunk)');
+        const bios = await resolveAsset(assets.bios);
+        this.#driver = driver;
+        const resolved = storagePath(ENGINE_ID, storage.namespace);
+        this.#namespace = resolved.namespace;
+        this.#storagePath = resolved.path;
+        this.#persist = storage.persist !== null;
+        const jsUrl = config.jsUrl ?? new URL('./fbneo.js', import.meta.url).href;
+        const wasmUrl = config.wasmUrl ?? new URL('./fbneo.wasm', import.meta.url).href;
+        const { default: createFbneoModule } = (await import(/* @vite-ignore */ jsUrl));
+        // The context SDL will use, made first so it keeps its picture between frames:
+        // FBNeo draws from timers, not animation frames, so without this snapshot() (the
+        // app's suspend-point frames) reads a cleared buffer. SDL gets this one back.
+        this.#canvas.getContext('webgl', { preserveDrawingBuffer: true, antialias: false });
+        let failed = null;
+        // FBNeo reports a set it could not load only on stdout (then main() returns).
+        let refused = null;
+        const Module = await createFbneoModule({
+            canvas: this.#canvas,
+            noInitialRun: true,
+            locateFile: (path) => (path.endsWith('.wasm') ? wasmUrl : new URL(path, jsUrl).href),
+            print: (text) => {
+                if (/error loading your selected game/i.test(text))
+                    refused = text;
+                console.log('[fbneo]', text);
+            },
+            printErr: (text) => console.warn('[fbneo]', text),
+            onAbort: (what) => failed?.(new Error(`fbneo: aborted — ${String(what)}`)),
+        });
+        this.#module = Module;
+        failed = (error) => this.emit('error', error);
+        const { FS } = Module;
+        // FBNeo finds a game by `<driver>.zip` in its ROM paths, and matches the files
+        // inside by name/CRC: whatever the player named the file, it lands as that.
+        for (const dir of ROM_DIRS) {
+            FS.mkdirTree(dir);
+            FS.writeFile(`${dir}/${driver}.zip`, rom);
+            if (bios)
+                FS.writeFile(`${dir}/neogeo.zip`, bios);
+        }
+        FS.mkdirTree(SAVE_DIR);
+        if (this.#persist)
+            await this.#restoreSaves();
+        // callMain() returns at FBNeo's first yield, before the set is loaded: wait for
+        // the game to run, or for FBNeo to say it refused the set, so a bad set is an
+        // error here and not a black screen.
+        Module.callMain([driver]);
+        const deadline = performance.now() + LOAD_TIMEOUT_MS;
+        while (!Module._web_running() && !refused && performance.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        if (!Module._web_running()) {
+            throw new Error(refused
+                ? `fbneo: FBNeo could not load "${driver}" — the ROM set is incomplete, is not that driver, or needs a BIOS (neogeo.zip for Neo Geo)`
+                : `fbneo: "${driver}" did not start within ${LOAD_TIMEOUT_MS / 1000} s`);
+        }
+        if (this.#persist) {
+            this.#saveTimer = setInterval(() => void this.flushSaves(), SAVE_INTERVAL_MS);
+            document.addEventListener('visibilitychange', this.#onHidden);
+            window.addEventListener('pagehide', this.#onHidden);
+        }
+        this.#fit();
+    }
+    /** The plain values behind one payload's descriptors. */
+    async #values(kind) {
+        const described = (await this[kind]());
+        const out = {};
+        for (const [key, property] of Object.entries(described))
+            out[key] = property.value;
+        return out;
+    }
+    // ---- Saves ----
+    async #restoreSaves() {
+        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')
+                continue;
+            const bytes = new Uint8Array(await (await handle.getFile()).arrayBuffer());
+            this.#module.FS.writeFile(`${SAVE_DIR}/${name}`, bytes);
+            this.#lastSaved.set(name, bytes);
+        }
+    }
+    async #flush() {
+        const Module = this.#module;
+        if (!Module || !this.#persist)
+            return;
         try {
-            onEvent?.(e);
+            Module._web_persist();
         }
-        catch {
-            // host callback must not break the engine runtime
+        catch (e) {
+            console.warn('[fbneo] persist failed', e);
+            return;
         }
-    };
-    // Generic hosts (e.g. the engine-specs demo shell) pass the picked file's name
-    // as `options.fileName`; treat it as an alias for `romFileName` so the driver
-    // can be inferred from the ROM's filename without a FBNeo-specific option.
-    const rawOptions = config.options;
-    const opts = {
-        ...DEFAULT_FBNEO_OPTIONS,
-        ...rawOptions,
-        romFileName: rawOptions?.romFileName ??
-            rawOptions?.fileName ??
-            DEFAULT_FBNEO_OPTIONS.romFileName,
-    };
-    const romBytes = toUint8(assets?.rom ?? assets?.data);
-    if (!romBytes) {
-        throw new Error('fbneo: no ROM bytes provided — pass assets.rom (an arcade ROM zip)');
-    }
-    const biosBytes = toUint8(assets?.bios);
-    const canvas = prepareCanvas(resolveCanvas(config), opts.renderFilter);
-    // FBNeo boots a game by its ROM-set short name ("driver", e.g. "mslug") and
-    // searches its ROM paths for a matching `<driver>.zip`. Prefer an explicit
-    // `options.driver`; otherwise derive it from the ROM filename (stripping the
-    // extension). Whatever the source, the zip is mounted as `<driver>.zip` so the
-    // name FBNeo looks up and the name on disk always agree.
-    const driver = (opts.driver || driverFromFileName(opts.romFileName)).trim();
-    if (!driver || driver === 'game') {
-        throw new Error('fbneo: could not determine the ROM-set name. Pass options.driver (the FBNeo ' +
-            'short name, e.g. "mslug") or name the ROM file after it (e.g. mslug.zip).');
-    }
-    const romFileName = `${driver}.zip`;
-    const jsUrl = config.jsUrl ?? new URL('./fbneo.js', import.meta.url).href;
-    const wasmUrl = config.wasmUrl ?? new URL('./fbneo.wasm', jsUrl).href;
-    let modRef = null;
-    let readyResolve = () => { };
-    const readyPromise = new Promise((resolve) => {
-        readyResolve = resolve;
-    });
-    // FBNeo's default ROM search paths (src/burner/sdl/drv.cpp) are the absolute
-    // "/usr/local/share/roms/" and the cwd-relative "roms/". Under Emscripten the
-    // cwd is not guaranteed to be "/", so write to the absolute path (always
-    // searched) as well as "/roms/". FBNeo matches ROM files inside each zip by
-    // name/CRC, so the zip must be named after the driver.
-    const romDirs = ['/usr/local/share/roms', '/roms'];
-    const writeRoms = (mod) => {
-        for (const dir of romDirs) {
-            mod.FS.mkdirTree(dir);
-            mod.FS.writeFile(`${dir}/${romFileName}`, romBytes);
-            if (biosBytes)
-                mod.FS.writeFile(`${dir}/neogeo.zip`, biosBytes);
+        const changed = [];
+        for (const name of Module.FS.readdir(SAVE_DIR)) {
+            if (name === '.' || name === '..')
+                continue;
+            const path = `${SAVE_DIR}/${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), bytes))
+                changed.push([name, bytes]);
         }
-    };
-    const moduleOverrides = {
-        canvas,
-        noInitialRun: true,
-        locateFile(path) {
-            if (path.endsWith('.wasm'))
-                return wasmUrl;
-            return new URL(path, jsUrl).href;
-        },
-    };
-    await loadClassicScriptOnce(jsUrl);
-    const g = globalThis;
-    // Our build is a MODULARIZE factory (createFbneoModule). The factory promise
-    // resolves *after* the runtime is initialized and FS is available, so this is
-    // the correct point to populate MEMFS — write the ROMs before callMain().
-    if (typeof g.createFbneoModule === 'function') {
-        modRef = await g.createFbneoModule(moduleOverrides);
-    }
-    else if (g.Module) {
-        modRef = g.Module;
-    }
-    else {
-        throw new Error('fbneo: unable to initialize runtime module from fbneo.js');
-    }
-    writeRoms(modRef);
-    readyResolve();
-    await readyPromise;
-    let running = false;
-    const boot = () => {
-        if (running)
+        if (changed.length === 0)
             return;
-        running = true;
-        // FBNeo SDL takes the ROM set short name and searches its rom paths for it.
-        modRef.callMain([driver]);
-        emit({ type: 'ready' });
-    };
-    const setInput = (_map) => {
-        // Input is handled by the Emscripten SDL2 event loop; no external override yet.
-    };
-    return {
-        start() {
-            boot();
-        },
-        pause() {
-            modRef?.pauseMainLoop?.();
-        },
-        resume() {
-            modRef?.resumeMainLoop?.();
-        },
-        reset() {
-            // FBNeo does not expose a soft-reset hook through this WASM build.
-            throw new Error('fbneo: reset is not supported by this build');
-        },
-        setInput,
-        destroy() {
-            modRef?.pauseMainLoop?.();
-            running = false;
-            emit({ type: 'exit' });
-        },
-    };
+        const dir = await opfsDir(this.#storagePath, true);
+        if (!dir)
+            return;
+        const written = [];
+        for (const [name, bytes] of changed) {
+            try {
+                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 (e) {
+                console.warn(`[fbneo] could not persist ${name}`, e);
+            }
+        }
+        if (written.length)
+            this.emit('saves', { files: written });
+    }
+    // ---- Picture ----
+    /** Scale the canvas to fit its box, keeping the picture's own proportions. */
+    #fit() {
+        const canvas = this.#canvas;
+        const box = this.#box;
+        if (!canvas || !box || !this.#ownsCanvas)
+            return;
+        const { width, height } = box.getBoundingClientRect();
+        const w = canvas.width || FBNEO_VIDEO.width;
+        const h = canvas.height || FBNEO_VIDEO.height;
+        if (!width || !height)
+            return;
+        const scale = Math.min(width / w, height / h);
+        canvas.style.width = `${Math.floor(w * scale)}px`;
+        canvas.style.height = `${Math.floor(h * scale)}px`;
+    }
+    async #applyFilter() {
+        const canvas = this.#canvas;
+        if (!canvas)
+            return;
+        const { renderFilter } = await this.#values('config');
+        canvas.style.imageRendering = renderFilter === 'smooth' ? 'auto' : 'pixelated';
+    }
+}
+/**
+ * The factory a host constructs: static identity, the configuration chain, and a
+ * `start()` that boots FBNeo and opens a session.
+ */
+export class FbneoSDK 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 = 'FinalBurn Neo';
+    static description = 'FBNeo, the arcade emulator (Capcom CPS-1/2/3, SNK Neo Geo, Sega System 16 and more), compiled to WebAssembly. Ships no games: the player provides the ROM sets, and they never leave their browser.';
+    createPlay(init, events) {
+        return new FbneoPlay(init, events);
+    }
 }
-export default { manifest, load };
+/** CI's conformance line: if this class stops satisfying the contract, `make test` fails. */
+export const FBNEO_ENGINE = FbneoSDK;
+export default FbneoSDK;
 //# sourceMappingURL=fbneo.sdk.js.map