@wasm-gaming/rsdkv3-wasm 0.1.2

package/README.md

@@ -0,0 +1,89 @@
+# @wasm-gaming/rsdkv3-wasm
+
+RSDKv3 (Retro Software Development Kit v3, Sonic CD 2011 decompilation) compiled
+to WebAssembly, wrapped in a JS SDK conforming to the
+[wasm-gaming engine contract](https://github.com/wasm-gaming/engine-specs).
+
+The engine does not bake game data with `--preload-file`. Hosts provide
+`Data.rsdk` at runtime, so the same `rsdkv3.wasm` can be reused across installs.
+
+## Contract surface
+
+```js
+import { manifest, load } from '@wasm-gaming/rsdkv3-wasm';
+
+const engine = await load({
+  canvas,
+  assets: { data: dataRsdkBytes /*, settings: iniBytes */ },
+  onEvent: (e) => { /* 'ready' | 'error' */ },
+  // Optional override when artifacts are hosted externally:
+  // jsUrl, wasmUrl,
+});
+
+engine.pause();
+engine.resume();
+engine.setInput('rsdkv4');
+engine.destroy();
+```
+
+- `manifest` defines required `data` (`/data/Data.rsdk`) and optional `settings`
+  (`/data/settings.ini`) assets.
+- `load(config)` returns an `EngineInstance` and exposes `devMenu` bridge helpers:
+  `getStageList()`, `loadStage(category, stage)`, `setPaused(bool)`.
+
+## Options
+
+Engine-specific options are declared in
+[src/rsdkv3.options.ts](src/rsdkv3.options.ts) and mirrored into `manifest.options`:
+
+- `devMenu`
+- `engineDebugMode`
+- `vsync`
+- `soundtrack` (`0` JP/EU, `1` US)
+- `language`
+- `disableTouchControls`
+
+If `assets.settings` is omitted, the SDK generates `settings.ini` from these
+options.
+
+## Build
+
+All build logic is in [Makefile](Makefile):
+
+```bash
+make build        # SDK (TypeScript) + WASM
+make build-sdk    # SDK only
+make build-wasm   # WASM via Docker wrapper
+make preview      # serves dist/ at http://localhost:8080
+```
+
+- `scripts/build.sh` clones `Rubberduckycooly/Sonic-CD-11-Decompilation`, applies
+  known Emscripten patches, vendors `libtheora`, and outputs:
+  - `dist/rsdkv3/rsdkv3.js`
+  - `dist/rsdkv3/rsdkv3.wasm`
+- `scripts/emit-manifest.mjs` writes `dist/manifest.json` from typed manifest.
+- `scripts/seed-settings.mjs` seeds `dist/settings.ini` from
+  `src/settings.default.ini` when absent.
+
+## Try locally
+
+```bash
+make build
+cp /path/to/Data.rsdk dist/
+make preview
+# open http://localhost:8080/
+```
+
+The demo attempts `./Data.rsdk`; if missing, it shows a file picker and supports
+drag-and-drop.
+
+## Status
+
+- ✅ TypeScript SDK + manifest build
+- ✅ CI workflow scaffold for SDK/WASM/release/pages
+- ⏳ Browser runtime verification with a real `Data.rsdk`
+- ⏳ Full WASM build verification (`make build-wasm`) on this new subproject
+
+## License
+
+MIT for this wrapper. Upstream engine and game data keep their own licenses.

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"rsdkv3.manifest.d.ts","sourceRoot":"","sources":["../../src/rsdkv3.manifest.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGhE,eAAO,MAAM,QAAQ,EAAE,cAkCtB,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/dist/rsdkv3/rsdkv3.manifest.js

@@ -0,0 +1,39 @@
+// The rsdkv3 EngineManifest — typed against the contract, so a drift from
+// @wasm-gaming/engine-specs is a compile error here. `npm run build:manifest`
+// serializes this to dist/manifest.json (the artifact CI attaches to a Release).
+import { RSDKV3_OPTIONS_SCHEMA } from './rsdkv3.options.js';
+export const manifest = {
+    id: 'rsdkv3',
+    version: '0.1.0',
+    name: 'Retro Software Development Kit v3',
+    artifacts: {
+        // Relative to the manifest (dist/manifest.json); the engine files live in
+        // the dist/rsdkv3/ subfolder.
+        wasm: 'rsdkv3/rsdkv3.wasm',
+        js: 'rsdkv3/rsdkv3.js',
+    },
+    assets: [
+        {
+            key: 'data',
+            // Lives under the OPFS-backed (persistent) working dir; the engine reads it
+            // via CWD (booted with the UsingCWD arg).
+            mountPath: '/data/Data.rsdk',
+            required: true,
+            accept: ['.rsdk'],
+            description: 'Sonic CD 2011 game data pack (Data.rsdk).',
+        },
+        {
+            key: 'settings',
+            mountPath: '/data/settings.ini',
+            required: false,
+            accept: ['.ini'],
+            description: 'Engine settings. Omitted → the SDK generates one from config.options.',
+        },
+    ],
+    input: 'rsdkv4',
+    video: { baseWidth: 426, baseHeight: 240, aspect: '16:9' },
+    options: RSDKV3_OPTIONS_SCHEMA,
+    capabilities: { saveStates: false, sram: false, coreSelectable: false },
+};
+export default manifest;
+//# sourceMappingURL=rsdkv3.manifest.js.map

package/dist/rsdkv3/rsdkv3.manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsdkv3.manifest.js","sourceRoot":"","sources":["../../src/rsdkv3.manifest.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,8EAA8E;AAC9E,iFAAiF;AAGjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,CAAC,MAAM,QAAQ,GAAmB;IACtC,EAAE,EAAE,QAAQ;IACZ,OAAO,EAAE,OAAO;IAChB,IAAI,EAAE,mCAAmC;IACzC,SAAS,EAAE;QACT,0EAA0E;QAC1E,8BAA8B;QAC9B,IAAI,EAAE,oBAAoB;QAC1B,EAAE,EAAE,kBAAkB;KACvB;IACD,MAAM,EAAE;QACN;YACE,GAAG,EAAE,MAAM;YACX,4EAA4E;YAC5E,0CAA0C;YAC1C,SAAS,EAAE,iBAAiB;YAC5B,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE,CAAC,OAAO,CAAC;YACjB,WAAW,EACT,2CAA2C;SAC9C;QACD;YACE,GAAG,EAAE,UAAU;YACf,SAAS,EAAE,oBAAoB;YAC/B,QAAQ,EAAE,KAAK;YACf,MAAM,EAAE,CAAC,MAAM,CAAC;YAChB,WAAW,EACT,uEAAuE;SAC1E;KACF;IACD,KAAK,EAAE,QAAQ;IACf,KAAK,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE;IAC1D,OAAO,EAAE,qBAAqB;IAC9B,YAAY,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE;CACxE,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/dist/rsdkv3/rsdkv3.options.d.ts

@@ -0,0 +1,22 @@
+import type { JSONSchema } from '@wasm-gaming/engine-specs';
+export interface Rsdkv3Options {
+    /**
+     * RSDKv3's native in-canvas Dev Menu. Kept off by default: the launcher owns
+     * the debug/stage-select UI (via `instance.devMenu`), and leaving this on has
+     * historically produced a native menu-like screen at boot.
+     */
+    devMenu?: boolean;
+    /** RSDKv3 EngineDebugMode — enables the web devmenu embind bridge hooks. */
+    engineDebugMode?: boolean;
+    /** VSync setting in the generated settings.ini. */
+    vsync?: boolean;
+    /** 0 = JP/EU soundtrack, 1 = US soundtrack. */
+    soundtrack?: number;
+    /** 0 = English. Matches RSDKv3 language numeric value. */
+    language?: number;
+    /** Toggle touch controls in the generated settings.ini. */
+    disableTouchControls?: boolean;
+}
+export declare const DEFAULT_RSDKV3_OPTIONS: Required<Rsdkv3Options>;
+export declare const RSDKV3_OPTIONS_SCHEMA: JSONSchema;
+//# sourceMappingURL=rsdkv3.options.d.ts.map

package/dist/rsdkv3/rsdkv3.options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsdkv3.options.d.ts","sourceRoot":"","sources":["../../src/rsdkv3.options.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,mDAAmD;IACnD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,aAAa,CAO1D,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,UA0BnC,CAAC"}

package/dist/rsdkv3/rsdkv3.options.js

@@ -0,0 +1,45 @@
+// Engine-specific options for RSDKv3.
+//
+// This is the authoritative description of what `EngineConfig.options` accepts
+// for this engine. It provides both:
+//   - `Rsdkv3Options`          — compile-time type for TS hosts
+//   - `RSDKV3_OPTIONS_SCHEMA`  — JSON Schema mirrored into manifest.json
+//   - `DEFAULT_RSDKV3_OPTIONS` — defaults used when no settings.ini is supplied
+//
+// At runtime these options are serialized into Sonic CD's `settings.ini` format
+// when the host does not pass an explicit `settings` asset.
+export const DEFAULT_RSDKV3_OPTIONS = {
+    devMenu: false,
+    engineDebugMode: false,
+    vsync: false,
+    soundtrack: 0,
+    language: 0,
+    disableTouchControls: true,
+};
+export const RSDKV3_OPTIONS_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        devMenu: {
+            type: 'boolean',
+            default: false,
+            description: "RSDKv3's native in-canvas Dev Menu. The launcher provides its own overlay via instance.devMenu, so keep this off.",
+        },
+        engineDebugMode: {
+            type: 'boolean',
+            default: false,
+            description: 'Enables the web devmenu embind bridge (stage list / warp / pause).',
+        },
+        vsync: { type: 'boolean', default: false },
+        soundtrack: {
+            type: 'integer',
+            minimum: 0,
+            maximum: 1,
+            default: 0,
+            description: 'Sonic CD soundtrack selector: 0=JP/EU, 1=US.',
+        },
+        language: { type: 'integer', minimum: 0, default: 0 },
+        disableTouchControls: { type: 'boolean', default: true },
+    },
+};
+//# sourceMappingURL=rsdkv3.options.js.map

package/dist/rsdkv3/rsdkv3.options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsdkv3.options.js","sourceRoot":"","sources":["../../src/rsdkv3.options.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,+EAA+E;AAC/E,qCAAqC;AACrC,gEAAgE;AAChE,yEAAyE;AACzE,gFAAgF;AAChF,EAAE;AACF,gFAAgF;AAChF,4DAA4D;AAuB5D,MAAM,CAAC,MAAM,sBAAsB,GAA4B;IAC7D,OAAO,EAAE,KAAK;IACd,eAAe,EAAE,KAAK;IACtB,KAAK,EAAE,KAAK;IACZ,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,CAAC;IACX,oBAAoB,EAAE,IAAI;CAC3B,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAe;IAC/C,IAAI,EAAE,QAAQ;IACd,oBAAoB,EAAE,KAAK;IAC3B,UAAU,EAAE;QACV,OAAO,EAAE;YACP,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,KAAK;YACd,WAAW,EACT,mHAAmH;SACtH;QACD,eAAe,EAAE;YACf,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,KAAK;YACd,WAAW,EAAE,oEAAoE;SAClF;QACD,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;QAC1C,UAAU,EAAE;YACV,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,CAAC;YACV,WAAW,EAAE,8CAA8C;SAC5D;QACD,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;QACrD,oBAAoB,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;KACzD;CACF,CAAC"}

package/dist/rsdkv3/rsdkv3.sdk.d.ts

@@ -0,0 +1,45 @@
+import type { EngineConfig, EngineInstance, AssetData } from '@wasm-gaming/engine-specs';
+import { manifest } from './rsdkv3.manifest.js';
+export { manifest };
+/** 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;
+}
+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;
+    };
+};
+/**
+ * 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 declare function load(config: Rsdkv3LoadConfig): Promise<Rsdkv3Instance>;
+declare const _default: {
+    manifest: import("@wasm-gaming/engine-specs").EngineManifest;
+    load: typeof load;
+};
+export default _default;
+//# sourceMappingURL=rsdkv3.sdk.d.ts.map

package/dist/rsdkv3/rsdkv3.sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsdkv3.sdk.d.ts","sourceRoot":"","sources":["../../src/rsdkv3.sdk.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAuB,MAAM,2BAA2B,CAAC;AAC9G,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGhD,OAAO,EAAE,QAAQ,EAAE,CAAC;AA0FpB,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,YAAY,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IACzE,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACvD,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG;IAC5C,OAAO,EAAE,iBAAiB,CAAC;IAC3B,uEAAuE;IACvE,UAAU,EAAE,OAAO,CAAC;IACpB,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,YAAY,IAAI;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;CACtD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG;IAC5C,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC;IACpD,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC;IACxD,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,8BAA8B;AAC9B,wBAAsB,IAAI,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CA2H5E;;;;;AAED,wBAAkC"}

package/dist/rsdkv3/rsdkv3.sdk.js

@@ -0,0 +1,226 @@
+// @wasm-gaming/engine-rsdkv3 — 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 { manifest } from './rsdkv3.manifest.js';
+import { DEFAULT_RSDKV3_OPTIONS } from './rsdkv3.options.js';
+export { manifest };
+const WORK_DIR = '/data';
+const DEFAULT_STORAGE_NAMESPACE = 'default';
+/** Serialize engine options into RSDKv3's settings.ini format. */
+function buildSettingsIni(options = {}) {
+    const o = { ...DEFAULT_RSDKV3_OPTIONS, ...options };
+    return [
+        '[Dev]',
+        `EngineDebugMode=${o.engineDebugMode ? 'true' : 'false'}`,
+        `DevMenu=${o.devMenu ? 'true' : 'false'}`,
+        '',
+        '[Game]',
+        `Language=${o.language | 0}`,
+        `DisableTouchControls=${o.disableTouchControls ? 'true' : 'false'}`,
+        '',
+        '[Video]',
+        'Windowed=true',
+        'Borderless=false',
+        'ExclusiveFS=false',
+        `VSync=${o.vsync ? 'true' : 'false'}`,
+        'WindowScale=2',
+        'ScreenWidth=426',
+        'ScreenHeight=240',
+        'RefreshRate=60',
+        '',
+        '[Audio]',
+        'BGMVolume=1.000000',
+        'SFXVolume=1.000000',
+        `Soundtrack=${o.soundtrack | 0}`,
+        '',
+    ].join('\n');
+}
+function toUint8(x) {
+    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');
+}
+/** 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;
+}
+/** Best-effort mkdir -p for the Emscripten FS layer. */
+function ensureDir(Module, path) {
+    const parts = path.split('/').filter(Boolean);
+    let current = '';
+    for (const part of parts) {
+        current += `/${part}`;
+        try {
+            Module.FS.mkdir(current);
+        }
+        catch {
+            /* already exists */
+        }
+    }
+}
+/** Ensure the game working directory exists in the in-memory filesystem. */
+function mountWorkingDir(Module, storageNamespace) {
+    const workDir = `${WORK_DIR}/${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;
+    }
+    catch {
+        return false;
+    }
+}
+/** Boot the RSDKv3 engine. */
+export async function load(config) {
+    const { canvas, assets, onEvent } = config;
+    const options = config.options;
+    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) => {
+        try {
+            onEvent?.(e);
+        }
+        catch { /* host handler must not break us */ }
+    };
+    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.__gamepadKeyMap = manifest.input;
+    const mod = await import(/* @vite-ignore */ jsUrl);
+    const createRSDKv3 = mod.default;
+    const Module = await createRSDKv3({
+        canvas,
+        noInitialRun: true, // built with -sINVOKE_RUN=0; we mount data before main()
+        locateFile: (path) => (path.endsWith('.wasm') ? wasmUrl : path),
+        print: (...a) => console.log('[rsdkv3]', ...a),
+        printErr: (...a) => console.error('[rsdkv3]', ...a),
+        onAbort: (reason) => 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());
+    }
+    if (dataBytes) {
+        Module.FS.writeFile(dataPath, dataBytes);
+    }
+    else if (!fileExists(Module, dataPath)) {
+        throw new Error('rsdkv3: 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)));
+    }
+    // else: keep existing settings.ini in memory FS
+    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 [];
+            try {
+                return JSON.parse(Module.web_devmenu_get_stage_list());
+            }
+            catch (e) {
+                console.error('[rsdkv3] getStageList failed', e);
+                return [];
+            }
+        },
+        loadStage(categoryIdx, stageIdx) {
+            if (typeof Module.web_devmenu_load_stage === 'function') {
+                Module.web_devmenu_load_stage(categoryIdx | 0, stageIdx | 0);
+            }
+        },
+        setPaused,
+    };
+    // 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) {
+            if (typeof window !== 'undefined') {
+                window.__gamepadKeyMap = map;
+            }
+        },
+        destroy() {
+            try {
+                Module.pauseMainLoop?.();
+            }
+            catch { /* noop */ }
+            try {
+                setPaused(true);
+            }
+            catch { /* noop */ }
+        },
+        devMenu,
+        persistent,
+        storageNamespace,
+        purgeStorage() {
+            const deleteFileIfExists = (path) => {
+                try {
+                    Module.FS.unlink(path);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            };
+            return {
+                data: deleteFileIfExists(dataPath),
+                settings: deleteFileIfExists(settingsPath),
+            };
+        },
+    };
+}
+export default { manifest, load };
+//# sourceMappingURL=rsdkv3.sdk.js.map

package/dist/rsdkv3/rsdkv3.sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsdkv3.sdk.js","sourceRoot":"","sources":["../../src/rsdkv3.sdk.ts"],"names":[],"mappings":"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"}

package/dist/rsdkv3/wasm-specs.d.ts

@@ -0,0 +1,71 @@
+export type AssetData = Uint8Array | ArrayBuffer | string;
+export interface EngineEventError {
+    message?: string;
+}
+export type EngineEvent = {
+    type: 'ready';
+} | {
+    type: 'error';
+    error: Error;
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+export interface EngineConfig {
+    canvas?: HTMLCanvasElement;
+    assets?: {
+        data?: AssetData;
+        settings?: AssetData;
+    };
+    options?: unknown;
+    onEvent?: (event: EngineEvent) => void;
+    jsUrl?: string;
+    wasmUrl?: string;
+    persist?: 'opfs' | 'idbfs' | null;
+}
+export interface EngineInstance {
+    start(): void;
+    pause(): void;
+    resume(): void;
+    reset(): void;
+    setInput(preset?: string): void;
+    destroy(): void;
+}
+export interface JSONSchema {
+    type?: string;
+    additionalProperties?: boolean;
+    properties?: Record<string, unknown>;
+}
+export interface EngineArtifacts {
+    wasm: string;
+    js: string;
+}
+export interface AssetSpec {
+    key: string;
+    mountPath: string;
+    required: boolean;
+    accept: string[];
+    description?: string;
+}
+export interface VideoSpec {
+    baseWidth: number;
+    baseHeight: number;
+    aspect: string;
+}
+export interface EngineCapabilities {
+    saveStates: boolean;
+    sram: boolean;
+    coreSelectable: boolean;
+}
+export interface EngineManifest {
+    id: string;
+    version: string;
+    name: string;
+    artifacts: EngineArtifacts;
+    assets: AssetSpec[];
+    input: string;
+    video: VideoSpec;
+    options: JSONSchema;
+    capabilities: EngineCapabilities;
+}
+//# sourceMappingURL=wasm-specs.d.ts.map

package/dist/rsdkv3/wasm-specs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-specs.d.ts","sourceRoot":"","sources":["../../src/wasm-specs.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAE7C,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,SAAS,CAAC;QAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;KAAE,CAAC;IACpD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,IAAI,IAAI,CAAC;IACd,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;IACd,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,UAAU,CAAC;IACpB,YAAY,EAAE,kBAAkB,CAAC;CAClC"}

package/dist/rsdkv3/wasm-specs.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=wasm-specs.js.map

package/dist/rsdkv3/wasm-specs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-specs.js","sourceRoot":"","sources":["../../src/wasm-specs.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@wasm-gaming/rsdkv3-wasm",
+  "version": "0.1.2",
+  "description": "RSDKv3 (Retro Software Development Kit v3) compiled to WebAssembly, with a JS SDK conforming to the wasm-gaming engine contract. Runs Sonic CD by loading Data.rsdk at runtime.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wasm-gaming/rsdkv3-wasm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wasm-gaming/rsdkv3-wasm/issues"
+  },
+  "homepage": "https://github.com/wasm-gaming/rsdkv3-wasm#readme",
+  "type": "module",
+  "main": "./dist/rsdkv3/rsdkv3.sdk.js",
+  "types": "./dist/rsdkv3/rsdkv3.sdk.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/rsdkv3/rsdkv3.sdk.d.ts",
+      "import": "./dist/rsdkv3/rsdkv3.sdk.js"
+    },
+    "./options": {
+      "types": "./dist/rsdkv3/rsdkv3.options.d.ts",
+      "import": "./dist/rsdkv3/rsdkv3.options.js"
+    },
+    "./manifest": "./dist/manifest.json"
+  },
+  "files": [
+    "dist/rsdkv3/",
+    "dist/manifest.json",
+    "src/rsdkv3.manifest.ts",
+    "src/rsdkv3.options.ts",
+    "src/rsdkv3.sdk.ts",
+    "src/wasm-specs.ts",
+    "README.md"
+  ],
+  "comment:scripts": "Build logic lives in the Makefile, not here (make build / build-sdk / build-wasm / preview).",
+  "scripts": {},
+  "peerDependencies": {
+    "@wasm-gaming/engine-specs": "*"
+  },
+  "peerDependenciesMeta": {
+    "@wasm-gaming/engine-specs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@wasm-gaming/engine-specs": "^0.1.0",
+    "typescript": "^5.5.0"
+  },
+  "engineContract": "https://github.com/wasm-gaming/engine-specs",
+  "license": "MIT"
+}

package/src/rsdkv3.manifest.ts

@@ -0,0 +1,44 @@
+// The rsdkv3 EngineManifest — typed against the contract, so a drift from
+// @wasm-gaming/engine-specs is a compile error here. `npm run build:manifest`
+// serializes this to dist/manifest.json (the artifact CI attaches to a Release).
+
+import type { EngineManifest } from '@wasm-gaming/engine-specs';
+import { RSDKV3_OPTIONS_SCHEMA } from './rsdkv3.options.js';
+
+export const manifest: EngineManifest = {
+  id: 'rsdkv3',
+  version: '0.1.0',
+  name: 'Retro Software Development Kit v3',
+  artifacts: {
+    // Relative to the manifest (dist/manifest.json); the engine files live in
+    // the dist/rsdkv3/ subfolder.
+    wasm: 'rsdkv3/rsdkv3.wasm',
+    js: 'rsdkv3/rsdkv3.js',
+  },
+  assets: [
+    {
+      key: 'data',
+      // Lives under the OPFS-backed (persistent) working dir; the engine reads it
+      // via CWD (booted with the UsingCWD arg).
+      mountPath: '/data/Data.rsdk',
+      required: true,
+      accept: ['.rsdk'],
+      description:
+        'Sonic CD 2011 game data pack (Data.rsdk).',
+    },
+    {
+      key: 'settings',
+      mountPath: '/data/settings.ini',
+      required: false,
+      accept: ['.ini'],
+      description:
+        'Engine settings. Omitted → the SDK generates one from config.options.',
+    },
+  ],
+  input: 'rsdkv4',
+  video: { baseWidth: 426, baseHeight: 240, aspect: '16:9' },
+  options: RSDKV3_OPTIONS_SCHEMA,
+  capabilities: { saveStates: false, sram: false, coreSelectable: false },
+};
+
+export default manifest;

package/src/rsdkv3.options.ts

@@ -0,0 +1,68 @@
+// Engine-specific options for RSDKv3.
+//
+// This is the authoritative description of what `EngineConfig.options` accepts
+// for this engine. It provides both:
+//   - `Rsdkv3Options`          — compile-time type for TS hosts
+//   - `RSDKV3_OPTIONS_SCHEMA`  — JSON Schema mirrored into manifest.json
+//   - `DEFAULT_RSDKV3_OPTIONS` — defaults used when no settings.ini is supplied
+//
+// At runtime these options are serialized into Sonic CD's `settings.ini` format
+// when the host does not pass an explicit `settings` asset.
+
+import type { JSONSchema } from '@wasm-gaming/engine-specs';
+
+export interface Rsdkv3Options {
+  /**
+   * RSDKv3's native in-canvas Dev Menu. Kept off by default: the launcher owns
+   * the debug/stage-select UI (via `instance.devMenu`), and leaving this on has
+   * historically produced a native menu-like screen at boot.
+   */
+  devMenu?: boolean;
+  /** RSDKv3 EngineDebugMode — enables the web devmenu embind bridge hooks. */
+  engineDebugMode?: boolean;
+  /** VSync setting in the generated settings.ini. */
+  vsync?: boolean;
+  /** 0 = JP/EU soundtrack, 1 = US soundtrack. */
+  soundtrack?: number;
+  /** 0 = English. Matches RSDKv3 language numeric value. */
+  language?: number;
+  /** Toggle touch controls in the generated settings.ini. */
+  disableTouchControls?: boolean;
+}
+
+export const DEFAULT_RSDKV3_OPTIONS: Required<Rsdkv3Options> = {
+  devMenu: false,
+  engineDebugMode: false,
+  vsync: false,
+  soundtrack: 0,
+  language: 0,
+  disableTouchControls: true,
+};
+
+export const RSDKV3_OPTIONS_SCHEMA: JSONSchema = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    devMenu: {
+      type: 'boolean',
+      default: false,
+      description:
+        "RSDKv3's native in-canvas Dev Menu. The launcher provides its own overlay via instance.devMenu, so keep this off.",
+    },
+    engineDebugMode: {
+      type: 'boolean',
+      default: false,
+      description: 'Enables the web devmenu embind bridge (stage list / warp / pause).',
+    },
+    vsync: { type: 'boolean', default: false },
+    soundtrack: {
+      type: 'integer',
+      minimum: 0,
+      maximum: 1,
+      default: 0,
+      description: 'Sonic CD soundtrack selector: 0=JP/EU, 1=US.',
+    },
+    language: { type: 'integer', minimum: 0, default: 0 },
+    disableTouchControls: { type: 'boolean', default: true },
+  },
+};

package/src/rsdkv3.sdk.ts

@@ -0,0 +1,258 @@
+// @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';
+
+export { manifest };
+
+const WORK_DIR = '/data';
+const DEFAULT_STORAGE_NAMESPACE = 'default';
+
+/** Serialize engine options into RSDKv3's settings.ini format. */
+function buildSettingsIni(options: Rsdkv3Options = {}): string {
+  const o = { ...DEFAULT_RSDKV3_OPTIONS, ...options };
+  return [
+    '[Dev]',
+    `EngineDebugMode=${o.engineDebugMode ? 'true' : 'false'}`,
+    `DevMenu=${o.devMenu ? 'true' : 'false'}`,
+    '',
+    '[Game]',
+    `Language=${o.language | 0}`,
+    `DisableTouchControls=${o.disableTouchControls ? 'true' : 'false'}`,
+    '',
+    '[Video]',
+    'Windowed=true',
+    'Borderless=false',
+    'ExclusiveFS=false',
+    `VSync=${o.vsync ? 'true' : 'false'}`,
+    'WindowScale=2',
+    'ScreenWidth=426',
+    'ScreenHeight=240',
+    'RefreshRate=60',
+    '',
+    '[Audio]',
+    'BGMVolume=1.000000',
+    'SFXVolume=1.000000',
+    `Soundtrack=${o.soundtrack | 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');
+}
+
+/** 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('/');
+
+  return cleaned || DEFAULT_STORAGE_NAMESPACE;
+}
+
+/** Best-effort mkdir -p for the Emscripten FS layer. */
+function ensureDir(Module: any, path: string): void {
+  const parts = path.split('/').filter(Boolean);
+  let current = '';
+  for (const part of parts) {
+    current += `/${part}`;
+    try {
+      Module.FS.mkdir(current);
+    } catch {
+      /* already 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 };
+}
+
+/** 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;
+  }
+}
+
+/** 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;
+}
+
+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 };
+};
+
+/**
+ * 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 */ }
+  };
+
+  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());
+  }
+  if (dataBytes) {
+    Module.FS.writeFile(dataPath, dataBytes);
+  } else if (!fileExists(Module, dataPath)) {
+    throw new Error('rsdkv3: 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)));
+  }
+  // else: keep existing settings.ini in memory FS
+
+  Module.FS.chdir(workDir);
+
+  const setPaused = (paused: boolean) => {
+    if (typeof Module.web_devmenu_set_paused === 'function') Module.web_devmenu_set_paused(paused);
+  };
+
+  const devMenu: RsdkDevMenuBridge = {
+    getStageList() {
+      if (typeof Module.web_devmenu_get_stage_list !== 'function') return [];
+      try {
+        return JSON.parse(Module.web_devmenu_get_stage_list());
+      } catch (e) {
+        console.error('[rsdkv3] getStageList failed', e);
+        return [];
+      }
+    },
+    loadStage(categoryIdx, stageIdx) {
+      if (typeof Module.web_devmenu_load_stage === 'function') {
+        Module.web_devmenu_load_stage(categoryIdx | 0, stageIdx | 0);
+      }
+    },
+    setPaused,
+  };
+
+  // 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;
+        }
+      };
+
+      return {
+        data: deleteFileIfExists(dataPath),
+        settings: deleteFileIfExists(settingsPath),
+      };
+    },
+  };
+}
+
+export default { manifest, load };

package/src/wasm-specs.ts

@@ -0,0 +1,72 @@
+export type AssetData = Uint8Array | ArrayBuffer | string;
+
+export interface EngineEventError {
+  message?: string;
+}
+
+export type EngineEvent =
+  | { type: 'ready' }
+  | { type: 'error'; error: Error }
+  | { type: string; [key: string]: unknown };
+
+export interface EngineConfig {
+  canvas?: HTMLCanvasElement;
+  assets?: { data?: AssetData; settings?: AssetData };
+  options?: unknown;
+  onEvent?: (event: EngineEvent) => void;
+  jsUrl?: string;
+  wasmUrl?: string;
+  persist?: 'opfs' | 'idbfs' | null;
+}
+
+export interface EngineInstance {
+  start(): void;
+  pause(): void;
+  resume(): void;
+  reset(): void;
+  setInput(preset?: string): void;
+  destroy(): void;
+}
+
+export interface JSONSchema {
+  type?: string;
+  additionalProperties?: boolean;
+  properties?: Record<string, unknown>;
+}
+
+export interface EngineArtifacts {
+  wasm: string;
+  js: string;
+}
+
+export interface AssetSpec {
+  key: string;
+  mountPath: string;
+  required: boolean;
+  accept: string[];
+  description?: string;
+}
+
+export interface VideoSpec {
+  baseWidth: number;
+  baseHeight: number;
+  aspect: string;
+}
+
+export interface EngineCapabilities {
+  saveStates: boolean;
+  sram: boolean;
+  coreSelectable: boolean;
+}
+
+export interface EngineManifest {
+  id: string;
+  version: string;
+  name: string;
+  artifacts: EngineArtifacts;
+  assets: AssetSpec[];
+  input: string;
+  video: VideoSpec;
+  options: JSONSchema;
+  capabilities: EngineCapabilities;
+}