@wasm-gaming/rsdkv5-wasm 0.1.1 → 0.1.2

package/src/rsdkv5.sdk.ts

@@ -1,50 +1,138 @@
-// @wasm-gaming/rsdkv5-wasm — SDK entry point.
-
-// Conforms to the wasm-gaming engine contract (github.com/wasm-gaming/engine-specs):
-// exports `manifest` (declarative) and `load(config)` (imperative).
-
-// Sonic Mania is built as RSDKv5U (compiled statically into the engine — see
-// docs/wasm-build-approach-b-sdk-contract.md). The SDK surface is game-agnostic:
-// `Data.rsdk` and `Settings.ini` are mounted at runtime into the FS, then main()
-// is started via callMain(). NOTE the capital S: the v5 engine reads
-// "Settings.ini" (case-sensitive under the Emscripten FS), unlike v4's
-// settings.ini.
+/**
+ * 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,
+  type EngineInit,
+  type EngineSDKConstructor,
+  type EventsOf,
+  type PayloadKind,
+} from '@wasm-gaming/engine-specs';
+import {
+  RSDKV5_SPEC,
+  RSDKV5_VIDEO,
+  type Rsdkv5Asset,
+  type Rsdkv5Config,
+  type Rsdkv5Options,
+  type Rsdkv5Payloads,
+} from './rsdkv5.options.js';
+
+export type {
+  Rsdkv5Asset,
+  Rsdkv5Assets,
+  Rsdkv5Config,
+  Rsdkv5Events,
+  Rsdkv5Options,
+  Rsdkv5Payloads,
+  Rsdkv5Storage,
+} 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;
+
+/** The Emscripten module this build produces (`createRSDKv5` from rsdkv5.js). */
+interface Rsdkv5Module {
+  FS: {
+    mkdir(path: string): void;
+    writeFile(path: string, data: Uint8Array): void;
+    readFile(path: string): Uint8Array;
+    readdir(path: string): string[];
+    stat(path: string): { mode: number };
+    isFile(mode: number): boolean;
+    chdir(path: string): void;
+  };
+  callMain(args: string[]): void;
+  pauseMainLoop?: () => void;
+  web_devmenu_get_stage_list?: () => string;
+  web_devmenu_load_stage?: (category: number, stage: number) => void;
+  web_devmenu_set_paused?: (paused: boolean) => void;
+  SDL2?: { audioContext?: AudioContext };
+}
 
-import type { EngineConfig, EngineInstance, AssetData } from '@wasm-gaming/engine-specs';
-import { manifest } from './rsdkv5.manifest.js';
-import { DEFAULT_RSDKV5_OPTIONS, type Rsdkv5Options } from './rsdkv5.options.js';
+type Rsdkv5Factory = (overrides: Record<string, unknown>) => Promise<Rsdkv5Module>;
 
-export { manifest };
+/** The launcher's handle on RSDKv5's stage list, for drawing its own dev menu. */
+export interface RsdkDevMenuBridge {
+  getStageList(): Array<{ name: string; stages: Array<{ name: string }> }>;
+  loadStage(category: number, stage: number): void;
+}
 
-const WORK_ROOT = '/data';
-const DEFAULT_STORAGE_NAMESPACE = 'default';
+/**
+ * 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.
+ */
+export function storagePath(
+  engineId: string,
+  namespace: unknown,
+): { namespace: string; path: string; prefixed: boolean } {
+  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 };
+}
 
 /**
- * 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).
+ * 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.
  */
-function buildSettingsIni(options: Rsdkv5Options = {}): string {
-  const o = { ...DEFAULT_RSDKV5_OPTIONS, ...options };
-  const b = (v: boolean) => (v ? '1' : '0');
+export function buildSettingsIni(config: Rsdkv5Config): string {
+  const b = (v: boolean | undefined) => (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',
@@ -59,216 +147,344 @@ function buildSettingsIni(options: Rsdkv5Options = {}): string {
   ].join('\n');
 }
 
-function toUint8(x: unknown): Uint8Array | null {
-  if (x == null) 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');
+async function opfsDir(path: string, create: boolean): Promise<FileSystemDirectoryHandle | null> {
+  if (typeof navigator === 'undefined' || !navigator.storage?.getDirectory) return null;
+  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: unknown): string {
-  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('/');
+async function resolveAsset(asset: Rsdkv5Asset | undefined): Promise<Uint8Array | null> {
+  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');
+}
 
-  return cleaned || DEFAULT_STORAGE_NAMESPACE;
+function sameBytes(a: Uint8Array | null, b: Uint8Array): boolean {
+  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;
 }
 
-/** Best-effort mkdir -p for the Emscripten FS layer. */
-function ensureDir(Module: any, path: string): void {
-  const parts = path.split('/').filter(Boolean);
+function mkdirp(Module: Rsdkv5Module, path: string): void {
   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: any, storageNamespace: string): { persistent: boolean; workDir: string } {
-  const workDir = `${WORK_ROOT}/${storageNamespace}`;
-  ensureDir(Module, workDir);
-  return { persistent: false, workDir };
-}
+/** The live engine: one booted RSDKv5 and its session. */
+export class Rsdkv5Play extends EnginePlayBase<Rsdkv5Payloads> {
+  #module: Rsdkv5Module | null = null;
+  #destroyed = false;
+  #pauseOwner: string | null = null;
+
+  #canvas: HTMLCanvasElement | null = null;
+  #ownsCanvas = false;
+  #box: HTMLElement | null = null;
+  #boxObserver: ResizeObserver | null = null;
+
+  #namespace = DEFAULT_STORAGE_NAMESPACE;
+  #storagePath = `${ENGINE_ID}/${DEFAULT_STORAGE_NAMESPACE}`;
+  #workDir = `${WORK_ROOT}/${ENGINE_ID}/${DEFAULT_STORAGE_NAMESPACE}`;
+  #persist = true;
+  #saveTimer: ReturnType<typeof setInterval> | null = null;
+  #lastSaved = new Map<string, Uint8Array>();
+  #flushing: Promise<void> | null = null;
+  #onHidden = (): void => {
+    if (document.visibilityState === 'hidden') void this.flushSaves();
+  };
 
-/** True if `path` exists in the (mounted) filesystem. */
-function fileExists(Module: any, path: string): boolean {
-  try {
-    Module.FS.stat(path);
-    return true;
-  } catch {
-    return false;
+  constructor(init?: EngineInit<Rsdkv5Payloads>, events?: EventEmitter<EventsOf<Rsdkv5Payloads>>) {
+    super(RSDKV5_SPEC, init, events);
   }
-}
 
-/** Delete a file if present; returns true when something was removed. */
-function deleteFileIfExists(Module: any, path: string): boolean {
-  if (!fileExists(Module, path)) return false;
-  try {
-    Module.FS.unlink(path);
-    return true;
-  } catch {
-    return false;
+  get namespace(): string {
+    return this.#namespace;
   }
-}
 
-/** RSDKv5-specific bridge for the launcher's debug/stage-select UI. */
-export interface RsdkDevMenuBridge {
-  getStageList(): Array<{ name: string; stages: Array<{ name: string }> }>;
-  loadStage(categoryIdx: number, stageIdx: number): void;
-  setPaused(paused: boolean): void;
-}
+  /** Where this session's files live, relative to the OPFS root: `rsdkv5/<namespace>`. */
+  get storagePath(): string {
+    return this.#storagePath;
+  }
 
-export type Rsdkv5Instance = EngineInstance & {
-  devMenu: RsdkDevMenuBridge;
-  /** True when the working dir is OPFS-backed (persistent) rather than in-memory. */
-  persistent: boolean;
-  /** Relative storage namespace used under /data (e.g. "sonic-mania"). */
-  storageNamespace: string;
-  /** Remove persisted game files for this namespace only. */
-  purgeStorage(): { data: boolean; settings: boolean };
-};
+  get pausedBy(): string | null {
+    return this.#pauseOwner;
+  }
 
-/**
- * Extra (engine-specific) config on top of the contract's EngineConfig: lazy asset
- * providers, invoked only on a cache miss.
- */
-export type Rsdkv5LoadConfig = EngineConfig & {
-  dataProvider?: () => Promise<AssetData> | AssetData;
-  settingsProvider?: () => Promise<AssetData> | AssetData;
-  /** Per-game storage folder under /data used for OPFS/WASMFS files. */
-  storageNamespace?: string;
-};
-
-/** Boot the RSDKv5 engine. */
-export async function load(config: Rsdkv5LoadConfig): Promise<Rsdkv5Instance> {
-  const { canvas, assets, onEvent } = config;
-  const options = config.options as Rsdkv5Options | undefined;
-  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: Parameters<NonNullable<EngineConfig['onEvent']>>[0]) => {
-    try { onEvent?.(e); } catch { /* host handler must not break us */ }
-  };
+  /** RSDKv5's stage list, for a host that draws its own stage select. */
+  get devMenu(): RsdkDevMenuBridge {
+    const Module = (): Rsdkv5Module | null => this.#module;
+    return {
+      getStageList() {
+        try {
+          return JSON.parse(Module()?.web_devmenu_get_stage_list?.() ?? '[]');
+        } catch {
+          return [];
+        }
+      },
+      loadStage(category: number, stage: number) {
+        Module()?.web_devmenu_load_stage?.(category | 0, stage | 0);
+      },
+    };
+  }
 
-  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 as any).__gamepadKeyMap = manifest.input;
-
-  const mod: any = await import(/* @vite-ignore */ jsUrl);
-  const createRSDKv5 = mod.default;
-
-  const Module: any = await createRSDKv5({
-    canvas,
-    noInitialRun: true,
-    locateFile: (path: string) => (path.endsWith('.wasm') ? wasmUrl : path),
-    print: (...a: unknown[]) => console.log('[rsdkv5]', ...a),
-    printErr: (...a: unknown[]) => console.error('[rsdkv5]', ...a),
-    onAbort: (reason: unknown) =>
-      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());
+  /**
+   * 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'): void {
+    const Module = this.#module;
+    if (!Module || this.#pauseOwner) return;
+    this.#pauseOwner = owner;
+    Module.web_devmenu_set_paused?.(true);
+    void Module.SDL2?.audioContext?.suspend();
+    void this.flushSaves();
+    this.emit('pause', { owner });
   }
-  if (dataBytes) {
-    Module.FS.writeFile(dataPath, dataBytes);
-  } else if (!fileExists(Module, dataPath)) {
-    throw new Error('rsdkv5: no Data.rsdk — provide assets.data or dataProvider');
+
+  resume(owner = 'host'): void {
+    const Module = this.#module;
+    if (!Module || this.#pauseOwner !== owner) return;
+    this.#pauseOwner = null;
+    void Module.SDL2?.audioContext?.resume();
+    Module.web_devmenu_set_paused?.(false);
+    this.emit('resume', { owner });
   }
 
-  // settings.ini — explicit asset > lazy provider > generated from options.
-  let settingsBytes = toUint8(assets?.settings);
-  if (!settingsBytes && config.settingsProvider) {
-    settingsBytes = toUint8(await config.settingsProvider());
+  /** Copy the game's changed user files to OPFS `rsdkv5/<namespace>/`; emits `saves`. */
+  flushSaves(): Promise<void> {
+    this.#flushing ??= this.#flush().finally(() => {
+      this.#flushing = null;
+    });
+    return this.#flushing;
   }
-  if (settingsBytes) {
-    Module.FS.writeFile(settingsPath, settingsBytes);
-  } else if (!fileExists(Module, settingsPath)) {
-    Module.FS.writeFile(settingsPath, new TextEncoder().encode(buildSettingsIni(options)));
+
+  // ---- Contract hooks ----
+
+  protected override mounted(target: HTMLElement): void {
+    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);
+    }
+    // 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);
+    }
   }
 
-  Module.FS.chdir(workDir);
+  protected override async open(_options: Rsdkv5Options): Promise<void> {
+    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();
+  }
 
-  const setPaused = (paused: boolean) => {
-    if (typeof Module.web_devmenu_set_paused === 'function') Module.web_devmenu_set_paused(paused);
-  };
+  protected override patched(_kind: PayloadKind, _patch: object): void {
+    // Nothing in RSDKV5_SPEC is live: Settings.ini is read once, at boot.
+  }
 
-  const devMenu: RsdkDevMenuBridge = {
-    getStageList() {
-      if (typeof Module.web_devmenu_get_stage_list !== 'function') return [];
+  protected override async close(): Promise<void> {
+    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());
-      } catch (e) {
-        console.error('[rsdkv5] getStageList failed', e);
-        return [];
+        Module.web_devmenu_set_paused?.(true);
+        Module.pauseMainLoop?.();
+      } 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();
+      } catch {
+        /* already closed */
       }
-    },
-    setPaused,
-  };
+    }
+    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(): Promise<void> {
+    const config = await this.#values<Rsdkv5Config>('config');
+    const assets = await this.#values<{ data?: Rsdkv5Asset; settings?: Rsdkv5Asset }>('assets');
+    const storage = await this.#values<{ namespace?: string; persist?: 'opfs' | null }>('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);
 
-  // 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 as any).__gamepadKeyMap = preset ?? manifest.input;
+    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)) as { default: Rsdkv5Factory };
+
+    let failed: ((error: Error) => void) | null = null;
+    const Module = await createRSDKv5({
+      canvas: this.#canvas,
+      noInitialRun: true,
+      locateFile: (path: string) => (path.endsWith('.wasm') ? wasmUrl : new URL(path, jsUrl).href),
+      print: (text: string) => console.log('[rsdkv5]', text),
+      printErr: (text: string) => console.warn('[rsdkv5]', text),
+      onAbort: (what: unknown) => 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<T>(kind: 'config' | 'assets' | 'storage'): Promise<T> {
+    const described = (await this[kind]()) as Record<string, { value: unknown }>;
+    const out: Record<string, unknown> = {};
+    for (const [key, property] of Object.entries(described)) out[key] = property.value;
+    return out as T;
+  }
+
+  // ---- Save mirror ----
+
+  async #restoreSave(): Promise<void> {
+    const dir = await opfsDir(this.#storagePath, false);
+    if (!dir || !this.#module) return;
+    const iterable = dir as unknown as { entries(): AsyncIterable<[string, FileSystemHandle]> };
+    for await (const [name, handle] of iterable.entries()) {
+      if (handle.kind !== 'file' || NOT_SAVES.has(name)) continue;
+      const bytes = new Uint8Array(await (await (handle as FileSystemFileHandle).getFile()).arrayBuffer());
+      this.#module.FS.writeFile(`${this.#workDir}/${name}`, bytes);
+      this.#lastSaved.set(name, bytes);
+    }
+  }
+
+  async #flush(): Promise<void> {
+    const Module = this.#module;
+    if (!Module || !this.#persist) return;
+    const changed: Array<[string, Uint8Array<ArrayBuffer>]> = [];
+    let names: string[];
+    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: string[] = [];
+    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(`[rsdkv5] could not persist ${name}`, e);
       }
-    },
-    destroy() {
-      try { Module.pauseMainLoop?.(); } catch { /* noop */ }
-      try { setPaused(true); } 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(): void {
+    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`;
+  }
 }
 
-export default { manifest, load };
+/** The factory a host constructs: static identity, the configuration chain, `start()`. */
+export class Rsdkv5SDK extends EngineSDKBase<Rsdkv5Payloads> {
+  static readonly id = ENGINE_ID;
+  /** Kept in step with package.json by `node scripts/sync-version.mjs`. */
+  static readonly version = '0.1.2';
+  static readonly name = 'Retro Software Development Kit v3';
+  static readonly description =
+    'RSDKv5U (Sonic Mania decompilation) compiled to WebAssembly. Ships none of the game: the player provides Data.rsdk, and it never leaves their browser.';
+
+  protected override createPlay(
+    init: EngineInit<Rsdkv5Payloads>,
+    events: EventEmitter<EventsOf<Rsdkv5Payloads>>,
+  ): Rsdkv5Play {
+    return new Rsdkv5Play(init, events);
+  }
+}
+
+/** CI's conformance line: if this class stops satisfying the contract, `make test` fails. */
+export const RSDKV5_ENGINE: EngineSDKConstructor<Rsdkv5Payloads> = Rsdkv5SDK;
+
+export default Rsdkv5SDK;