@wasm-gaming/rsdkv3-wasm 0.1.2 → 0.1.5

package/src/rsdkv3.sdk.ts

@@ -1,258 +1,465 @@
-// @wasm-gaming/rsdkv3-wasm — SDK entry point.
-//
-// Conforms to the wasm-gaming engine contract (github.com/wasm-gaming/engine-specs):
-// exports `manifest` (declarative) and `load(config)` (imperative).
-//
-// The engine binary is game-agnostic for RSDKv3. Sonic CD is selected by
-// `Data.rsdk`, mounted at runtime into the Emscripten filesystem.
-
-import type { EngineConfig, EngineInstance, AssetData, InputPreset, KeyMap } from '@wasm-gaming/engine-specs';
-import { manifest } from './rsdkv3.manifest.js';
-import { DEFAULT_RSDKV3_OPTIONS, type Rsdkv3Options } from './rsdkv3.options.js';
+/**
+ * The engine package's entry point: an `EngineSDK` for RSDKv3 (Sonic CD).
+ *
+ * ```js
+ * import Rsdkv3SDK from '@wasm-gaming/rsdkv3-wasm';
+ *
+ * const play = await new Rsdkv3SDK({ config: { soundtrack: 1 } })
+ *   .assets({ data: () => readDataRsdk() })    // bytes, or a thunk
+ *   .storage({ namespace: 'sonic-cd' })        // → OPFS rsdkv3/sonic-cd/
+ *   .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 `rsdkv3.wasm`: `Data.rsdk` is written into the filesystem at
+ * runtime, never baked in. The working dir `/data/rsdkv3/<namespace>` is in memory;
+ * the SDK seeds `SData.bin` from OPFS `rsdkv3/<namespace>/` before boot and mirrors it
+ * back when it changes (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 {
+  RSDKV3_SPEC,
+  RSDKV3_VIDEO,
+  type Rsdkv3Asset,
+  type Rsdkv3Config,
+  type Rsdkv3Options,
+  type Rsdkv3Payloads,
+} from './rsdkv3.options.js';
 
-export { manifest };
+export type {
+  Rsdkv3Asset,
+  Rsdkv3Assets,
+  Rsdkv3Config,
+  Rsdkv3Events,
+  Rsdkv3Options,
+  Rsdkv3Payloads,
+  Rsdkv3Storage,
+} from './rsdkv3.options.js';
+export { RSDKV3_SPEC, RSDKV3_VIDEO } from './rsdkv3.options.js';
 
-const WORK_DIR = '/data';
+const ENGINE_ID = 'rsdkv3';
 const DEFAULT_STORAGE_NAMESPACE = 'default';
+const WORK_ROOT = '/data';
+const SAVE_FILE = 'SData.bin';
+const SAVE_INTERVAL_MS = 10_000;
+
+/** The Emscripten module this build produces (`createRSDKv3` from rsdkv3.js). */
+interface Rsdkv3Module {
+  FS: {
+    mkdir(path: string): void;
+    writeFile(path: string, data: Uint8Array): void;
+    readFile(path: string): Uint8Array;
+    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 };
+}
+
+type Rsdkv3Factory = (overrides: Record<string, unknown>) => Promise<Rsdkv3Module>;
+
+/** The launcher's handle on RSDKv3'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;
+}
+
+/**
+ * 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 RSDKv3's settings.ini format. */
-function buildSettingsIni(options: Rsdkv3Options = {}): string {
-  const o = { ...DEFAULT_RSDKV3_OPTIONS, ...options };
+/** Serialise the engine config into RSDKv3's settings.ini. */
+export function buildSettingsIni(config: Rsdkv3Config): string {
   return [
     '[Dev]',
-    `EngineDebugMode=${o.engineDebugMode ? 'true' : 'false'}`,
-    `DevMenu=${o.devMenu ? 'true' : 'false'}`,
+    `EngineDebugMode=${config.engineDebugMode ? 'true' : 'false'}`,
+    `DevMenu=${config.devMenu ? 'true' : 'false'}`,
     '',
     '[Game]',
-    `Language=${o.language | 0}`,
-    `DisableTouchControls=${o.disableTouchControls ? 'true' : 'false'}`,
+    `Language=${(config.language ?? 0) | 0}`,
+    `DisableTouchControls=${config.disableTouchControls === false ? 'false' : 'true'}`,
     '',
     '[Video]',
     'Windowed=true',
     'Borderless=false',
     'ExclusiveFS=false',
-    `VSync=${o.vsync ? 'true' : 'false'}`,
+    `VSync=${config.vsync ? 'true' : 'false'}`,
     'WindowScale=2',
-    'ScreenWidth=426',
-    'ScreenHeight=240',
+    `ScreenWidth=${RSDKV3_VIDEO.width}`,
+    `ScreenHeight=${RSDKV3_VIDEO.height}`,
     'RefreshRate=60',
     '',
     '[Audio]',
     'BGMVolume=1.000000',
     'SFXVolume=1.000000',
-    `Soundtrack=${o.soundtrack | 0}`,
+    `Soundtrack=${(config.soundtrack ?? 0) | 0}`,
     '',
   ].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: Rsdkv3Asset | 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('rsdkv3: 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: Rsdkv3Module, 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 */
     }
   }
 }
 
-/** Ensure the game working directory exists in the in-memory filesystem. */
-function mountWorkingDir(Module: any, storageNamespace: string): { persistent: boolean; workDir: string } {
-  const workDir = `${WORK_DIR}/${storageNamespace}`;
-  ensureDir(Module, workDir);
-  return { persistent: false, workDir };
-}
+/** The live engine: one booted RSDKv3 and its session. */
+export class Rsdkv3Play extends EnginePlayBase<Rsdkv3Payloads> {
+  #module: Rsdkv3Module | null = null;
+  #destroyed = false;
+  #pauseOwner: string | null = null;
 
-/** 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;
+  #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;
+  #lastSave: Uint8Array | null = null;
+  #flushing: Promise<void> | null = null;
+  #onHidden = (): void => {
+    if (document.visibilityState === 'hidden') void this.flushSaves();
+  };
+
+  constructor(init?: EngineInit<Rsdkv3Payloads>, events?: EventEmitter<EventsOf<Rsdkv3Payloads>>) {
+    super(RSDKV3_SPEC, init, events);
   }
-}
 
-/** RSDKv3-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;
-}
+  get namespace(): string {
+    return this.#namespace;
+  }
 
-export type Rsdkv3Instance = EngineInstance & {
-  devMenu: RsdkDevMenuBridge;
-  /** Always false in the current rsdkv3 build (in-memory FS backend). */
-  persistent: boolean;
-  /** Relative storage namespace used under /data (e.g. "sonic-cd"). */
-  storageNamespace: string;
-  /** Remove files for this namespace only. */
-  purgeStorage(): { data: boolean; settings: boolean };
-};
+  /** Where this session's files live, relative to the OPFS root: `rsdkv3/<namespace>`. */
+  get storagePath(): string {
+    return this.#storagePath;
+  }
 
-/**
- * Extra (engine-specific) config on top of the contract's EngineConfig: lazy asset
- * providers, invoked only on a cache miss — e.g. to skip a large Data.rsdk fetch
- * when it's already persisted in OPFS.
- */
-export type Rsdkv3LoadConfig = EngineConfig & {
-  dataProvider?: () => Promise<AssetData> | AssetData;
-  settingsProvider?: () => Promise<AssetData> | AssetData;
-  /** Per-game storage folder under /data used for the in-memory filesystem. */
-  storageNamespace?: string;
-};
-
-/** Boot the RSDKv3 engine. */
-export async function load(config: Rsdkv3LoadConfig): Promise<Rsdkv3Instance> {
-  const { canvas, assets, onEvent } = config;
-  const options = config.options as Rsdkv3Options | undefined;
-  if (!canvas) throw new Error('rsdkv3: 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 */ }
-  };
+  get pausedBy(): string | null {
+    return this.#pauseOwner;
+  }
 
-  const jsUrl = config.jsUrl ?? new URL('./rsdkv3.js', import.meta.url).href;
-  const wasmUrl = config.wasmUrl ?? new URL('./rsdkv3.wasm', import.meta.url).href;
-
-  // RSDKv3 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 createRSDKv3 = mod.default;
-
-  const Module: any = await createRSDKv3({
-    canvas,
-    noInitialRun: true, // built with -sINVOKE_RUN=0; we mount data before main()
-    locateFile: (path: string) => (path.endsWith('.wasm') ? wasmUrl : path),
-    print: (...a: unknown[]) => console.log('[rsdkv3]', ...a),
-    printErr: (...a: unknown[]) => console.error('[rsdkv3]', ...a),
-    onAbort: (reason: unknown) =>
-      emit({ type: 'error', error: new Error(`rsdkv3 aborted: ${reason}`) }),
-  });
-
-  const storageNamespace = normalizeStorageNamespace(config.storageNamespace);
-  const { persistent, workDir } = mountWorkingDir(Module, storageNamespace);
-  const dataPath = `${workDir}/Data.rsdk`;
-  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());
+  /** RSDKv3's stage list, for a host that draws its own stage select. */
+  get devMenu(): RsdkDevMenuBridge {
+    const Module = (): Rsdkv3Module | 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);
+      },
+    };
   }
-  if (dataBytes) {
-    Module.FS.writeFile(dataPath, dataBytes);
-  } else if (!fileExists(Module, dataPath)) {
-    throw new Error('rsdkv3: no Data.rsdk — provide assets.data or 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 });
   }
 
-  // settings.ini — explicit asset > lazy provider > generated from options.
-  let settingsBytes = toUint8(assets?.settings);
-  if (!settingsBytes && config.settingsProvider) {
-    settingsBytes = toUint8(await config.settingsProvider());
+  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 });
   }
-  if (settingsBytes) {
-    Module.FS.writeFile(settingsPath, settingsBytes);
-  } else if (!fileExists(Module, settingsPath)) {
-    Module.FS.writeFile(settingsPath, new TextEncoder().encode(buildSettingsIni(options)));
+
+  /** Copy `SData.bin` to OPFS `rsdkv3/<namespace>/` if it changed; emits `saves`. */
+  flushSaves(): Promise<void> {
+    this.#flushing ??= this.#flush().finally(() => {
+      this.#flushing = null;
+    });
+    return this.#flushing;
   }
-  // else: keep existing settings.ini in memory FS
 
-  Module.FS.chdir(workDir);
+  // ---- Contract hooks ----
 
-  const setPaused = (paused: boolean) => {
-    if (typeof Module.web_devmenu_set_paused === 'function') Module.web_devmenu_set_paused(paused);
-  };
+  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);
+    }
+  }
 
-  const devMenu: RsdkDevMenuBridge = {
-    getStageList() {
-      if (typeof Module.web_devmenu_get_stage_list !== 'function') return [];
+  protected override async open(_options: Rsdkv3Options): Promise<void> {
+    if (this.#destroyed || this.#module) {
+      // RSDKv3 cannot restart in process: main() runs once and owns the loop.
+      throw new Error('rsdkv3: the engine cannot be restarted in process — destroy() and start a new page (or iframe)');
+    }
+    await this.#boot();
+  }
+
+  protected override patched(_kind: PayloadKind, _patch: object): void {
+    // Nothing in RSDKV3_SPEC is live: settings.ini is read once, at boot.
+  }
+
+  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('[rsdkv3] 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;
+  }
 
-  // Run main() from the mounted working dir. simulate_infinite_loop schedules
-  // the rAF loop and returns via a benign unwind Emscripten swallows.
-  Module.callMain(['UsingCWD']);
-  emit({ type: 'ready' });
-
-  return {
-    start() {},
-    pause() { setPaused(true); },
-    resume() { setPaused(false); },
-    reset() {
-      throw new Error('rsdkv3: reset() is not supported — destroy() and load() again');
-    },
-    setInput(map: InputPreset | KeyMap) {
-      if (typeof window !== 'undefined') {
-        (window as any).__gamepadKeyMap = map;
-      }
-    },
-    destroy() {
-      try { Module.pauseMainLoop?.(); } catch { /* noop */ }
-      try { setPaused(true); } catch { /* noop */ }
-    },
-    devMenu,
-    persistent,
-    storageNamespace,
-    purgeStorage() {
-      const deleteFileIfExists = (path: string): boolean => {
-        try {
-          Module.FS.unlink(path);
-          return true;
-        } catch {
-          return false;
-        }
-      };
+  // ---- Boot ----
 
-      return {
-        data: deleteFileIfExists(dataPath),
-        settings: deleteFileIfExists(settingsPath),
-      };
-    },
-  };
+  async #boot(): Promise<void> {
+    const config = await this.#values<Rsdkv3Config>('config');
+    const assets = await this.#values<{ data?: Rsdkv3Asset; settings?: Rsdkv3Asset }>('assets');
+    const storage = await this.#values<{ namespace?: string; persist?: 'opfs' | null }>('storage');
+    if (!this.#canvas) throw new Error('rsdkv3: mount() an element (or a canvas) before start()');
+
+    const data = await resolveAsset(assets.data);
+    if (!data) throw new Error('rsdkv3: 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(`[rsdkv3] 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('./rsdkv3.js', import.meta.url).href;
+    const wasmUrl = config.wasmUrl ?? new URL('./rsdkv3.wasm', import.meta.url).href;
+    const { default: createRSDKv3 } = (await import(/* @vite-ignore */ jsUrl)) as { default: Rsdkv3Factory };
+
+    let failed: ((error: Error) => void) | null = null;
+    const Module = await createRSDKv3({
+      canvas: this.#canvas,
+      noInitialRun: true,
+      locateFile: (path: string) => (path.endsWith('.wasm') ? wasmUrl : new URL(path, jsUrl).href),
+      print: (text: string) => console.log('[rsdkv3]', text),
+      printErr: (text: string) => console.warn('[rsdkv3]', text),
+      onAbort: (what: unknown) => failed?.(new Error(`rsdkv3: 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);
+    Module.callMain(['UsingCWD']);
+
+    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;
+    try {
+      const file = await (await dir.getFileHandle(SAVE_FILE)).getFile();
+      if (file.size === 0) return;
+      const bytes = new Uint8Array(await file.arrayBuffer());
+      this.#module.FS.writeFile(`${this.#workDir}/${SAVE_FILE}`, bytes);
+      this.#lastSave = bytes;
+    } catch {
+      /* no save yet */
+    }
+  }
+
+  async #flush(): Promise<void> {
+    const Module = this.#module;
+    if (!Module || !this.#persist) return;
+    let bytes: Uint8Array<ArrayBuffer>;
+    try {
+      bytes = new Uint8Array(Module.FS.readFile(`${this.#workDir}/${SAVE_FILE}`));
+    } catch {
+      return; // the game has not saved yet
+    }
+    if (sameBytes(this.#lastSave, bytes)) return;
+    const dir = await opfsDir(this.#storagePath, true);
+    if (!dir) return;
+    try {
+      const writable = await (await dir.getFileHandle(SAVE_FILE, { create: true })).createWritable();
+      await writable.write(bytes);
+      await writable.close();
+      this.#lastSave = bytes;
+      this.emit('saves', { files: [SAVE_FILE] });
+    } catch (e) {
+      console.warn('[rsdkv3] could not persist the save', e);
+    }
+  }
+
+  // ---- 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 / RSDKV3_VIDEO.width, height / RSDKV3_VIDEO.height);
+    canvas.style.width = `${Math.floor(RSDKV3_VIDEO.width * scale)}px`;
+    canvas.style.height = `${Math.floor(RSDKV3_VIDEO.height * scale)}px`;
+  }
 }
 
-export default { manifest, load };
+/** The factory a host constructs: static identity, the configuration chain, `start()`. */
+export class Rsdkv3SDK extends EngineSDKBase<Rsdkv3Payloads> {
+  static readonly id = ENGINE_ID;
+  /** Kept in step with package.json by `node scripts/sync-version.mjs`. */
+  static readonly version = '0.1.5';
+  static readonly name = 'Retro Software Development Kit v3';
+  static readonly description =
+    'RSDKv3 (Sonic CD 2011 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<Rsdkv3Payloads>,
+    events: EventEmitter<EventsOf<Rsdkv3Payloads>>,
+  ): Rsdkv3Play {
+    return new Rsdkv3Play(init, events);
+  }
+}
+
+/** CI's conformance line: if this class stops satisfying the contract, `make test` fails. */
+export const RSDKV3_ENGINE: EngineSDKConstructor<Rsdkv3Payloads> = Rsdkv3SDK;
+
+export default Rsdkv3SDK;

package/dist/rsdkv3/rsdkv3.manifest.d.ts

@@ -1,4 +0,0 @@
-import type { EngineManifest } from '@wasm-gaming/engine-specs';
-export declare const manifest: EngineManifest;
-export default manifest;
-//# sourceMappingURL=rsdkv3.manifest.d.ts.map