@wasm-gaming/rsdkv3-wasm 0.1.2 → 0.1.5

package/README.md

@@ -1,89 +1,82 @@
 # @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).
+RSDKv3 (Retro Software Development Kit v3, the Sonic CD 2011 decompilation) compiled to
+WebAssembly, wrapped in a self-contained SDK that implements the
+[wasm-gaming engine contract](https://github.com/wasm-gaming/engine-specs) 1.0.
 
-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.
+The engine bakes no game data: the host hands over `Data.rsdk` at runtime, so one `rsdkv3.wasm`
+serves any install.
 
-## Contract surface
+## Install
 
-```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();
+```bash
+npm install @wasm-gaming/rsdkv3-wasm
 ```
 
-- `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)`.
+The SDK carries the contract's runtime beside it (`dist/rsdkv3/engine-specs.js`) and imports it
+relatively: it loads from any static server, with no bundler and no import map. The wasm and its
+glue are built in CI and shipped in the GitHub Release (`rsdkv3.tar.gz`, layout `rsdkv3/rsdkv3/…`).
 
-## Options
+## Use
 
-Engine-specific options are declared in
-[src/rsdkv3.options.ts](src/rsdkv3.options.ts) and mirrored into `manifest.options`:
+```js
+import Rsdkv3SDK from './rsdkv3/rsdkv3.sdk.js';
+
+const play = await new Rsdkv3SDK({ config: { soundtrack: 1 } })   // US soundtrack
+  .assets({ data: () => readDataRsdk() })      // bytes, or a thunk
+  .storage({ namespace: 'sonic-cd' })          // → OPFS rsdkv3/sonic-cd/
+  .on('saves', ({ detail }) => console.log('saved', detail.files))
+  .mount(document.querySelector('#stage'))
+  .start();
+
+play.pause('menu');  play.resume('menu');      // owner-aware; sound stops too
+play.devMenu.getStageList();                   // draw your own stage select…
+play.devMenu.loadStage(0, 2);                  // …and warp
+await play.destroy();                          // save flushed, loop stopped, audio closed
+```
 
-- `devMenu`
-- `engineDebugMode`
-- `vsync`
-- `soundtrack` (`0` JP/EU, `1` US)
-- `language`
-- `disableTouchControls`
+| payload | keys |
+| --- | --- |
+| `config` | `devMenu`, `engineDebugMode`, `vsync`, `soundtrack` (0 JP/EU, 1 US), `language`, `disableTouchControls` (→ generated `settings.ini`), `jsUrl`, `wasmUrl` |
+| `options` | — |
+| `assets` | `data` (`Data.rsdk`, required), `settings` (`settings.ini`, optional) |
+| `storage` | `namespace` (default `default`), `persist` (`'opfs'` \| `null`) |
 
-If `assets.settings` is omitted, the SDK generates `settings.ini` from these
-options.
+Events: the contract's `start`, `error`, `exit`, `pause`, `resume`, plus `saves`.
+RSDKv3 cannot restart in process: after `destroy()`, a new session needs a new page (or iframe).
 
-## Build
+## Saves live in the engine's own folder
 
-All build logic is in [Makefile](Makefile):
+The working dir is `/data/rsdkv3/<namespace>` (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, when
+the page is hidden and on `destroy()` — so saves survive reloads. `play.storagePath` gives the
+folder; `storagePath(engineId, namespace)` is exported.
+
+## Build
 
 ```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
+make build-sdk      # TypeScript → dist/rsdkv3/ (fast, no Docker)
+make test           # type-check + tests against the built package
+make build-wasm     # RSDKv3 → WebAssembly in emscripten/emsdk:6.0.2 (Docker)
+make demo           # dist/index.html: a no-build demo (pick or drop Data.rsdk)
+make preview        # serve dist/ on :8023
 ```
 
-- `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
+The upstream decompilation is pinned (`d1bbec59`, 2026-07-04) together with its submodules, and so
+is the emsdk image, because the build's source patches are written against that exact revision.
 
-```bash
-make build
-cp /path/to/Data.rsdk dist/
-make preview
-# open http://localhost:8080/
-```
+## Project Specs
 
-The demo attempts `./Data.rsdk`; if missing, it shows a file picker and supports
-drag-and-drop.
+- Contract 1.0 class (`Rsdkv3SDK` / `Rsdkv3Play`), self-contained ESM, engine-specs as the one
+  dependency; conformance line `RSDKV3_ENGINE` checked by `make test`.
+- Engine-owned storage `rsdkv3/<namespace>/` with an `SData.bin` mirror.
+- Records of decisions in [RECORD/](RECORD/).
 
-## Status
+## Todos
 
-- ✅ 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
+- [ ] Make the build's source patches assert that they applied.
+- [ ] Verify with a real `Data.rsdk` (save written by the game → mirrored → restored).
 
 ## License
 
-MIT for this wrapper. Upstream engine and game data keep their own licenses.
+MIT for this wrapper. The upstream engine and the game data keep their own licenses.

package/dist/rsdkv3/engine-specs.js

@@ -0,0 +1,382 @@
+// ---- Introspectable property definitions ----
+/**
+ * The listener bookkeeping, shipped rather than described — the one piece of runtime
+ * code in this package.
+ *
+ * It is a **convenience, not a requirement**: the contract stays structural, so an
+ * engine that already owns an emitter satisfies {@link EngineSurface} without this.
+ * What it saves is the part everyone gets subtly wrong — iterating a copy, so a
+ * listener that unsubscribes mid-emit does not corrupt the loop; de-duplicating a
+ * listener registered twice; and keeping one throwing listener from silencing the
+ * rest.
+ *
+ * Hold it **privately** and hand the same instance to every carrier. That is what
+ * makes `sdk.on(…)` and `play.on(…)` one channel rather than two, lets a host
+ * subscribe before the engine exists, and keeps `emit` out of the public API — a host
+ * must not be able to forge an engine event.
+ */
+export class EventEmitter {
+    #listeners = new Map();
+    /** @param listeners Registered immediately — what `EngineInit.on` carries. */
+    constructor(listeners) {
+        for (const type of Object.keys(listeners ?? {})) {
+            const listener = listeners?.[type];
+            if (listener)
+                this.on(type, listener);
+        }
+    }
+    /** Registering the same listener twice registers it once, as `EventTarget` does. */
+    on(type, listener) {
+        let set = this.#listeners.get(type);
+        if (!set)
+            this.#listeners.set(type, (set = new Set()));
+        set.add(listener);
+        return this;
+    }
+    /**
+     * The listener is required, as in `EventTarget`. A convenience `off(type)` dropping
+     * every listener for a type is a footgun on a page where two components subscribed
+     * independently: one unsubscribing would silence the other.
+     */
+    off(type, listener) {
+        const set = this.#listeners.get(type);
+        if (set?.delete(listener) && set.size === 0) {
+            this.#listeners.delete(type);
+        }
+        return this;
+    }
+    /**
+     * Takes the **detail**, and wraps it. The rest tuple is what lets an event with no
+     * detail be emitted as `emit('exit')` while still checking the ones that have one.
+     */
+    emit(type, ...[detail]) {
+        const set = this.#listeners.get(type);
+        if (!set)
+            return;
+        // Built once and frozen: every listener gets this same object, so a mutable one
+        // would let the first rewrite what the rest read.
+        const event = Object.freeze({ type, detail: detail });
+        // A copy: a listener may call `off()` — on itself or another — while this runs.
+        for (const listener of [...set]) {
+            try {
+                listener(event);
+            }
+            catch (thrown) {
+                // One bad listener must neither silence the rest nor vanish. Rethrowing on a
+                // fresh task puts it in front of `window.onerror` with its stack intact.
+                queueMicrotask(() => {
+                    throw thrown;
+                });
+            }
+        }
+    }
+}
+/**
+ * Wrap a promise of a live engine in the chainable surface.
+ *
+ * Exported because it is the single most duplicated function in an engine, and an
+ * engine that does not extend {@link EnginePlayBase} still needs exactly this.
+ *
+ * `on` and `off` do **not** go through the chain: they reach the channel now, so a
+ * listener is live before the promise settles. Routing them through it would bind
+ * after the session opened and lose whatever was emitted while it was opening.
+ */
+export function hydratePlay(inner, events) {
+    const chain = (step) => hydratePlay(inner.then(async (play) => {
+        await step(play);
+        return play;
+    }), events);
+    const hydrated = {
+        then: (onfulfilled, onrejected) => inner.then(onfulfilled, onrejected),
+        catch: (onrejected) => inner.catch(onrejected),
+        finally: (onfinally) => inner.finally(onfinally),
+        [Symbol.toStringTag]: 'PromisePlay',
+        config: ((patch) => patch === undefined
+            ? inner.then((play) => play.config())
+            : chain((play) => play.config(patch))),
+        options: ((patch) => patch === undefined
+            ? inner.then((play) => play.options())
+            : chain((play) => play.options(patch))),
+        assets: ((patch) => patch === undefined
+            ? inner.then((play) => play.assets())
+            : chain((play) => play.assets(patch))),
+        storage: ((patch) => patch === undefined
+            ? inner.then((play) => play.storage())
+            : chain((play) => play.storage(patch))),
+        mount: (target) => chain((play) => play.mount(target)),
+        on: (type, listener) => {
+            events.on(type, listener);
+            return hydrated;
+        },
+        off: (type, listener) => {
+            events.off(type, listener);
+            return hydrated;
+        },
+        restart: (options) => chain((play) => play.restart(options)),
+        destroy: () => inner.then((play) => play.destroy()),
+    };
+    return hydrated;
+}
+/**
+ * The live engine, with everything the contract prescribes already written: state,
+ * the cumulative merge, the descriptors, the chainable promise, and the channel.
+ *
+ * A subclass supplies what only it can know — {@link EnginePlayBase.open} and
+ * {@link EnginePlayBase.close}, optionally {@link EnginePlayBase.mounted} and
+ * {@link EnginePlayBase.patched} — and its properties as an {@link EngineSpec}.
+ *
+ * The spec arrives as a **constructor argument**, not an abstract field, and that is
+ * not a style choice: a subclass field initialiser runs *after* `super()`, so a
+ * `protected abstract spec` would still be `undefined` while this constructor seeded
+ * state from it. Passing it up makes the ordering trap impossible rather than merely
+ * avoided.
+ */
+export class EnginePlayBase {
+    #spec;
+    #state;
+    #events;
+    #target;
+    /** The target {@link EnginePlayBase.mounted} has already been told about. */
+    #attached;
+    /**
+     * @param events The factory's channel. Omitted only when a play is built on its
+     * own; the factory always passes its own, which is what makes `sdk.on(…)` and
+     * `play.on(…)` one channel rather than two.
+     */
+    constructor(spec, init, events) {
+        this.#spec = spec;
+        this.#events = events ?? new EventEmitter(init?.on);
+        this.#state = {
+            config: seed(spec.config, init?.config),
+            options: seed(spec.options, init?.options),
+            assets: seed(spec.assets, init?.assets),
+            storage: seed(spec.storage, init?.storage),
+        };
+        // Recorded, not applied. `mounted()` is overridable, and a subclass's own fields
+        // are still uninitialised while this constructor runs — so the hook is deferred to
+        // the first `restart()`, by which point the subclass is whole.
+        this.#target = init?.mount;
+    }
+    /** The element is already recorded when this runs. */
+    mounted(target) {
+        void target;
+    }
+    /** A payload changed on a running engine — apply what is `live`, ignore the rest. */
+    patched(kind, patch) {
+        void kind;
+        void patch;
+    }
+    /**
+     * Emit one of this engine's own events.
+     *
+     * `protected`, so a typed host cannot forge an engine event — but be exact about
+     * what that buys: TypeScript erases `protected`, so this is a compile-time guard,
+     * not a capability boundary. Plain JavaScript can still reach it. Only the `#`
+     * fields below — the channel and the state — are unreachable at runtime.
+     */
+    emit(type, ...detail) {
+        this.#events.emit(type, ...detail);
+    }
+    /** Where the picture is, for a subclass that needs the element after `mounted()`. */
+    get target() {
+        return this.#target;
+    }
+    config(patch) {
+        // `arguments.length`, not `patch === undefined`: `config(undefined)` is a write of
+        // nothing, not a read.
+        if (arguments.length === 0)
+            return Promise.resolve(this.#describe('config'));
+        return this.#patch('config', patch);
+    }
+    options(patch) {
+        if (arguments.length === 0)
+            return Promise.resolve(this.#describe('options'));
+        return this.#patch('options', patch);
+    }
+    assets(patch) {
+        if (arguments.length === 0)
+            return Promise.resolve(this.#describe('assets'));
+        return this.#patch('assets', patch);
+    }
+    storage(patch) {
+        if (arguments.length === 0)
+            return Promise.resolve(this.#describe('storage'));
+        return this.#patch('storage', patch);
+    }
+    mount(target) {
+        this.#target = target;
+        return this.#run(() => this.#attach());
+    }
+    on(type, listener) {
+        this.#events.on(type, listener);
+        return hydratePlay(Promise.resolve(this), this.#events);
+    }
+    off(type, listener) {
+        this.#events.off(type, listener);
+        return hydratePlay(Promise.resolve(this), this.#events);
+    }
+    restart(options) {
+        return this.#run(async () => {
+            if (options)
+                Object.assign(this.#state.options, options);
+            // A target supplied to the constructor lands here, which is what makes
+            // `new Sdk({ mount: el }).start()` and `new Sdk().mount(el).start()` the same
+            // call — the rule the contract states for everything on the surface.
+            await this.#attach();
+            const opened = { ...this.#state.options };
+            await this.open(opened);
+            this.#emitCore('start', opened);
+        });
+    }
+    async destroy() {
+        await this.#guard(async () => {
+            await this.close();
+            this.#target = undefined;
+            this.#attached = undefined;
+            this.#emitCore('exit', undefined);
+        });
+    }
+    /** Tell the engine where it is, once per distinct target. Reparenting is legal. */
+    async #attach() {
+        if (!this.#target || this.#target === this.#attached)
+            return;
+        this.#attached = this.#target;
+        await this.mounted(this.#target);
+    }
+    // ---- Shared machinery ----
+    /** One getter's answer: the spec, with the current value written into each entry. */
+    #describe(kind) {
+        const spec = this.#spec[kind];
+        const state = this.#state[kind];
+        const out = {};
+        for (const key of Object.keys(spec)) {
+            out[key] = { ...spec[key], value: state[key] };
+        }
+        return out;
+    }
+    /** Cumulative, merged flat, one level — `undefined` is a value, not "leave alone". */
+    #patch(kind, patch) {
+        Object.assign(this.#state[kind], patch);
+        return this.#run(async () => {
+            await this.patched(kind, patch ?? {});
+        });
+    }
+    /** A step, as a link in the chain — and as an `error` event if it throws. */
+    #run(step) {
+        return hydratePlay(this.#guard(step), this.#events);
+    }
+    /**
+     * The rule that errors reach a host **both ways**: the promise rejects *and*
+     * `error` is emitted. Written once here rather than at every throw site.
+     */
+    async #guard(step) {
+        try {
+            await step();
+            return this;
+        }
+        catch (thrown) {
+            const error = thrown instanceof Error ? thrown : new Error(String(thrown));
+            this.#emitCore('error', error);
+            throw error;
+        }
+    }
+    /**
+     * The core events, emitted from here rather than by a subclass.
+     *
+     * The cast is the one thing TypeScript will not check here: `emit` takes a rest
+     * tuple that is conditional on the detail type, and that conditional stays
+     * unresolved while `P` is still a type parameter. It is sound — `EventsOf<P>`
+     * always contains `CoreEvents<P>` by construction — and confining it to this one
+     * method is why the three call sites above read plainly.
+     */
+    #emitCore(type, detail) {
+        // Cast the channel, not the method: pulling `emit` out into a variable would call
+        // it unbound, and it reads its listeners off `this`.
+        const events = this.#events;
+        events.emit(type, detail);
+    }
+}
+/** Starting state: every `default` the spec declares, then whatever `init` overrides. */
+function seed(spec, patch) {
+    const state = {};
+    for (const [key, property] of Object.entries(spec)) {
+        if (property.default !== undefined)
+            state[key] = property.default;
+    }
+    return Object.assign(state, patch);
+}
+/**
+ * The factory, with everything the contract prescribes already written: the
+ * cumulative init, the synchronous chain, the channel that outlives every session,
+ * and one live engine per factory.
+ *
+ * A subclass supplies its static identity and {@link EngineSDKBase.createPlay}.
+ */
+export class EngineSDKBase {
+    #init;
+    #play;
+    /**
+     * Created before any engine exists and handed to every carrier downstream. That is
+     * what lets a host subscribe to an error thrown while the first session opens.
+     */
+    events;
+    constructor(init) {
+        this.#init = { ...init };
+        this.events = new EventEmitter(init?.on);
+    }
+    config(patch) {
+        if (arguments.length === 0)
+            return this.#pending().config();
+        return this.#patch('config', patch);
+    }
+    options(patch) {
+        if (arguments.length === 0)
+            return this.#pending().options();
+        return this.#patch('options', patch);
+    }
+    assets(patch) {
+        if (arguments.length === 0)
+            return this.#pending().assets();
+        return this.#patch('assets', patch);
+    }
+    storage(patch) {
+        if (arguments.length === 0)
+            return this.#pending().storage();
+        return this.#patch('storage', patch);
+    }
+    /** Recorded now, applied when the engine exists — same call as `new Sdk({ mount })`. */
+    mount(target) {
+        this.#init.mount = target;
+        this.#play?.mount(target);
+        return this;
+    }
+    on(type, listener) {
+        this.events.on(type, listener);
+        return this;
+    }
+    off(type, listener) {
+        this.events.off(type, listener);
+        return this;
+    }
+    /**
+     * The only way in. On a live engine it reopens the session rather than building a
+     * second one: a factory governs at most one engine.
+     */
+    start(options) {
+        this.#play ??= this.createPlay(this.#init, this.events);
+        return this.#play.restart(options);
+    }
+    /** Answers a read before there is an engine: the settings the next one will use. */
+    #pending() {
+        return this.#play ?? this.createPlay(this.#init, this.events);
+    }
+    #patch(kind, patch) {
+        this.#init[kind] = { ...this.#init[kind], ...patch };
+        // A live engine gets it too, so the factory does not silently describe a state
+        // the engine is not in.
+        if (this.#play && patch)
+            this.#play[kind](patch);
+        return this;
+    }
+}
+//# sourceMappingURL=engine-specs.js.map