@wasm-gaming/rsdkv4-wasm 0.1.5 → 0.2.0

package/dist/rsdkv4/rsdkv4.options.js

@@ -1,67 +1,179 @@
-// Engine-specific options for RSDKv4.
-//
-// This is the authoritative description of what `EngineConfig.options` accepts
-// for this engine. It provides both:
-//   - `Rsdkv4Options`         — the compile-time type (for TS hosts/launchers)
-//   - `RSDKV4_OPTIONS_SCHEMA` — the JSON Schema mirrored into manifest.json's
-//                               `options` (for runtime host UI + validation)
-//   - `DEFAULT_RSDKV4_OPTIONS` — defaults the SDK falls back to.
-//
-// At runtime these options are serialized into RSDKv4's `settings.ini` (see the
-// SDK's settings serializer) when the host does not pass an explicit `settings`
-// asset.
 /**
- * RSDKv4 reads 255 as "not set" for the starting stage/player (see Userdata.cpp:
- * anything else — **including 0** — makes Engine::Init skip the start-menu flow
- * and force InitStartingStage). So "boot normally" has to be 255, not 0.
+ * What this engine's four payloads accept, and the {@link RSDKV4_SPEC} that describes
+ * them to a host.
+ *
+ * ```ts
+ * import type { Rsdkv4Config, Rsdkv4Options } from '@wasm-gaming/rsdkv4-wasm/options';
+ * ```
+ *
+ * The contract's own module documents *how* the four payloads behave — they read as
+ * descriptors and write as patches, and `live` says whether a key reaches a running
+ * engine. This module is only the part that is RSDKv4's: which keys exist, what they
+ * mean here, and what the engine does with them.
+ *
+ * The split between the first two is the whole design:
+ *
+ * - {@link Rsdkv4Config} is **the engine**. It is serialized into RSDKv4's
+ *   `settings.ini` and read once, at boot — so none of it is `live`.
+ * - {@link Rsdkv4Options} is **the session**: which character, which save slot, which
+ *   stage. That is what a `restart()` reopens. It also carries the engine's own GAME
+ *   OPTIONS rows, which *are* `live` — and which are not declared here at all, because
+ *   they differ between Sonic 1 and Sonic 2 and are only knowable once the pack is
+ *   loaded.
+ *
+ * @module
  */
-export const RSDKV4_UNSET = 255;
-export const DEFAULT_RSDKV4_OPTIONS = {
-    devMenu: false,
-    engineDebugMode: true,
-    vsync: true,
-    skipStartMenu: false,
-    startingCategory: RSDKV4_UNSET,
-    startingScene: RSDKV4_UNSET,
-    startingPlayer: RSDKV4_UNSET,
+/**
+ * RSDKv4's fourteen buttons, in the engine's own `InputButtons` order.
+ *
+ * The order is not cosmetic: it is the bit order of the mask the SDK hands the
+ * engine once per tick, so this array is the wire format and not merely a list.
+ *
+ * Sonic 1 and Sonic 2 read only the four directions, A, B, C and start. The other
+ * six exist in the engine and are free for a host to do as it likes with.
+ */
+export const RSDKV4_BUTTONS = [
+    'up',
+    'down',
+    'left',
+    'right',
+    'a',
+    'b',
+    'c',
+    'x',
+    'y',
+    'z',
+    'l',
+    'r',
+    'start',
+    'select',
+];
+/**
+ * The engine's own default bindings. See {@link Rsdkv4InputDefaults}.
+ *
+ * This replaces the old `RSDKV4_KEYMAP`, which nothing read and which was wrong in
+ * three ways for want of ever being checked against the engine: it listed 9 of the
+ * 14 buttons, and bound `select` to `ShiftLeft` where the engine's default is `Tab`.
+ */
+export const RSDKV4_INPUT = {
+    keyboard: {
+        up: 'ArrowUp',
+        down: 'ArrowDown',
+        left: 'ArrowLeft',
+        right: 'ArrowRight',
+        a: 'KeyZ',
+        b: 'KeyX',
+        c: 'KeyC',
+        x: 'KeyA',
+        y: 'KeyS',
+        z: 'KeyD',
+        l: 'KeyQ',
+        r: 'KeyE',
+        start: 'Enter',
+        select: 'Tab',
+    },
+    gamepad: {
+        up: 12,
+        down: 13,
+        left: 14,
+        right: 15,
+        a: 0,
+        b: 1,
+        c: 2,
+        x: 3,
+        y: 6,
+        z: 7,
+        l: 4,
+        r: 5,
+        start: 9,
+        select: null,
+    },
 };
-export const RSDKV4_OPTIONS_SCHEMA = {
-    type: 'object',
-    additionalProperties: false,
-    properties: {
+/**
+ * Everything the engine declares about its own properties, as data.
+ *
+ * `default` appears here and nowhere else: the contract's base class seeds the
+ * starting state from it, so there is no second table of defaults to drift out of
+ * agreement with this one — which is exactly what the old
+ * `DEFAULT_RSDKV4_OPTIONS`-alongside-a-JSON-Schema pair did.
+ *
+ * What is missing from `options` is deliberate: `player` and `stage` get their `enum`
+ * filled in from the loaded pack, and the GAME OPTIONS rows are added outright, when a
+ * running engine is asked to describe itself.
+ */
+export const RSDKV4_SPEC = {
+    config: {
+        vsync: { default: true, live: false, description: 'VSync the engine window.' },
         devMenu: {
-            type: 'boolean',
             default: false,
-            description: "RSDKv4's native in-canvas Dev Menu. The launcher provides its own overlay via instance.devMenu, so keep this off.",
+            live: false,
+            description: "RSDKv4's native in-canvas Dev Menu. Hosts draw their own from play.devMenu.",
         },
         engineDebugMode: {
-            type: 'boolean',
             default: true,
-            description: 'Enables the web devmenu embind bridge (stage list / warp / pause).',
+            live: false,
+            description: "Gates the engine's log output. The embind bridges are installed either way.",
         },
-        vsync: { type: 'boolean', default: true },
-        skipStartMenu: {
-            type: 'boolean',
-            default: false,
-            description: "Skip the engine's own save/character/options screens — set it when the host renders them from instance.game.",
+        startMenu: {
+            default: 'native',
+            enum: ['native', 'host'],
+            live: false,
+            description: "Who draws save/character/options: the engine's own menu, or the host from play.game.",
         },
-        startingCategory: {
-            type: 'integer',
-            minimum: 0,
-            default: RSDKV4_UNSET,
-            description: '0-based stage-list category; 255 = unset (normal boot flow).',
+        jsUrl: { live: false, description: 'Emscripten glue URL. Defaults to ./rsdkv4.js.' },
+        wasmUrl: { live: false, description: 'WASM URL. Defaults to ./rsdkv4.wasm.' },
+    },
+    options: {
+        // No `default` on any of the three: absence is what "boot normally" means here,
+        // and a default would take that away.
+        player: {
+            live: false,
+            description: 'Character for a new game, by name. Choices arrive once the pack is loaded.',
+        },
+        slot: {
+            enum: [null, 0, 1, 2, 3],
+            live: false,
+            description: 'Save slot 0-3, or null to play without saving.',
+        },
+        stage: {
+            live: false,
+            description: 'Jump straight to a stage. Choices arrive once the pack is loaded.',
+        },
+        // No `default`, for the same reason as the three above: absence is what "the
+        // engine polls SDL as usual" means, and only `null` is a release.
+        //
+        // `live` because it is the one option that reaches a running engine directly
+        // rather than through a restart — and the description says the rest out loud,
+        // because the contract has no flag for "transient, do not paint, do not
+        // persist" and a host reading descriptors to build a settings screen would
+        // otherwise put fourteen booleans on it.
+        buttons: {
+            live: true,
+            description: 'Host-driven input: a live object of 14 booleans the engine reads once per tick, or null to hand input back. Transient — not a settings row, not persistable, and it always reads back as null.',
         },
-        startingScene: {
-            type: 'integer',
-            minimum: 0,
-            default: RSDKV4_UNSET,
-            description: '0-based scene in the category; 255 = unset (normal boot flow).',
+    },
+    assets: {
+        data: {
+            allowedTypes: ['.rsdk'],
+            live: false,
+            description: 'The RSDKv4 game data pack. Selects the game; required to start.',
+        },
+        settings: {
+            allowedTypes: ['.ini'],
+            live: false,
+            description: 'A ready-made settings.ini. Omitted, one is generated from config.',
+        },
+    },
+    storage: {
+        namespace: {
+            default: 'default',
+            live: false,
+            description: "Folder for this game's pack, settings and save file.",
         },
-        startingPlayer: {
-            type: 'integer',
-            minimum: 0,
-            default: RSDKV4_UNSET,
-            description: 'Player/character index; 255 = unset (normal boot flow).',
+        persist: {
+            enum: ['opfs', null],
+            live: false,
+            description: "'opfs' forces persistence, null keeps nothing, absent auto-detects.",
         },
     },
 };

package/dist/rsdkv4/rsdkv4.options.js.map

@@ -1 +1 @@
-{"version":3,"file":"rsdkv4.options.js","sourceRoot":"","sources":["../../src/rsdkv4.options.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,+EAA+E;AAC/E,qCAAqC;AACrC,+EAA+E;AAC/E,8EAA8E;AAC9E,6EAA6E;AAC7E,iEAAiE;AACjE,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,SAAS;AA6BT;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC;AAEhC,MAAM,CAAC,MAAM,sBAAsB,GAA4B;IAC7D,OAAO,EAAE,KAAK;IACd,eAAe,EAAE,IAAI;IACrB,KAAK,EAAE,IAAI;IACX,aAAa,EAAE,KAAK;IACpB,gBAAgB,EAAE,YAAY;IAC9B,aAAa,EAAE,YAAY;IAC3B,cAAc,EAAE,YAAY;CAC7B,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,IAAI;YACb,WAAW,EAAE,oEAAoE;SAClF;QACD,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;QACzC,aAAa,EAAE;YACb,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,KAAK;YACd,WAAW,EACT,8GAA8G;SACjH;QACD,gBAAgB,EAAE;YAChB,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,YAAY;YACrB,WAAW,EAAE,8DAA8D;SAC5E;QACD,aAAa,EAAE;YACb,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,YAAY;YACrB,WAAW,EAAE,gEAAgE;SAC9E;QACD,cAAc,EAAE;YACd,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,YAAY;YACrB,WAAW,EAAE,yDAAyD;SACvE;KACF;CACF,CAAC"}
+{"version":3,"file":"rsdkv4.options.js","sourceRoot":"","sources":["../../src/rsdkv4.options.ts"],"names":[],"mappings":"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"}

package/dist/rsdkv4/rsdkv4.sdk.d.ts

@@ -1,7 +1,60 @@
-import type { EngineConfig, EngineInstance, AssetData } from '@wasm-gaming/engine-specs';
-import { manifest } from './rsdkv4.manifest.js';
-export { manifest };
-/** RSDKv4-specific bridge for the launcher's debug/stage-select UI. */
+/**
+ * The engine package's entry point: an `EngineSDK` for RSDKv4.
+ *
+ * ```ts
+ * import Rsdkv4SDK from '@wasm-gaming/rsdkv4-wasm';
+ *
+ * const play = await new Rsdkv4SDK()
+ *   .mount(document.querySelector('#stage'))
+ *   .assets({ data: () => library.readBytes('Sonic2') })
+ *   .storage({ namespace: 'rsdkv4/Sonic2' })
+ *   .config({ startMenu: 'host' })
+ *   .on('saves', ({ detail }) => paintSlots(detail))
+ *   .start({ slot: 0 });
+ * ```
+ *
+ * Everything a host drives is the contract's, and documented there: the four payloads
+ * with their descriptors, `mount`, `on`/`off`, `start`, `restart`, `destroy`. What is
+ * this engine's own lives in two places — {@link Rsdkv4Config} and friends, which say
+ * what the payloads accept *here*, and the extra members of {@link Rsdkv4Play} below:
+ * {@link Rsdkv4Play.game} and {@link Rsdkv4Play.devMenu}, for a host that draws
+ * RSDKv4's start screens itself, owner-aware {@link Rsdkv4Play.pause}, and
+ * {@link Rsdkv4Play.input}, for a host that would rather drive the buttons than let
+ * the engine read the keyboard.
+ *
+ * One game-agnostic `rsdkv4.wasm` runs both Sonic 1 and Sonic 2 — the difference is
+ * only which `Data.rsdk` the host hands over in `assets.data`, written into the
+ * filesystem at runtime (not baked with `--preload-file`).
+ *
+ * Filesystem: built with `-sWASMFS`. The working dir is mounted on **OPFS** when the
+ * page is cross-origin isolated *and* the build can create the OPFS backend from the
+ * main thread (an Asyncify/JSPI build — today's is not, see `WebFS.cpp`); otherwise it
+ * falls back to the WASMFS in-memory backend, which boots fine but forgets everything.
+ * That fallback is why the SDK mirrors `SData.bin` into OPFS itself: see
+ * {@link Rsdkv4Storage.persist}.
+ *
+ * @module
+ * @see [The engine contract](https://wasm-gaming.github.io/engine-specs/api-docs/)
+ */
+import { EnginePlayBase, EngineSDKBase, EventEmitter } from '@wasm-gaming/engine-specs';
+import type { EngineInit, EngineSDKConstructor, EventsOf, PayloadKind, PromisePlay, PropertiesDefinition } from '@wasm-gaming/engine-specs';
+import { type Rsdkv4Buttons, type Rsdkv4Options, type Rsdkv4Payloads, type RsdkSaveSlot } from './rsdkv4.options.js';
+export type { Rsdkv4Asset, Rsdkv4AssetData, Rsdkv4Assets, Rsdkv4Button, Rsdkv4Buttons, Rsdkv4Config, Rsdkv4Events, Rsdkv4InputDefaults, Rsdkv4Options, Rsdkv4Payloads, Rsdkv4Stage, Rsdkv4Storage, RsdkSaveSlot, } from './rsdkv4.options.js';
+export { RSDKV4_BUTTONS, RSDKV4_INPUT, RSDKV4_SPEC } from './rsdkv4.options.js';
+/** The core events unioned with this engine's own — what `on`/`off` accept. */
+export type Rsdkv4Events_ = EventsOf<Rsdkv4Payloads>;
+/**
+ * The picture's native size, which is what the SDK scales to fit its mount.
+ *
+ * A module constant rather than a manifest field: `EngineManifest` left the contract
+ * in 0.3.0, and this was one of only two things the SDK ever read back out of it.
+ */
+export declare const RSDKV4_VIDEO: {
+    readonly baseWidth: 424;
+    readonly baseHeight: 240;
+    readonly aspect: "16:9";
+};
+/** RSDKv4-specific bridge for a host's debug/stage-select UI. */
 export interface RsdkDevMenuBridge {
     getStageList(): Array<{
         name: string;
@@ -12,23 +65,14 @@ export interface RsdkDevMenuBridge {
     loadStage(categoryIdx: number, stageIdx: number): void;
     setPaused(paused: boolean): void;
 }
-/** One of RSDKv4's four save slots, as the engine's own save-select screen sees it. */
-export interface RsdkSaveSlot {
-    /** 0-3. */
-    slot: number;
-    /** No game stored here — starting it means picking a character first. */
-    empty: boolean;
-    /** Character index into `players()`: 0 Sonic, 1 Tails, 2 Knuckles, 3 Sonic & Tails. */
-    character: number;
-    lives: number;
-    score: number;
-    emeralds: number;
-    /** Stage list the save resumes into (1 regular, 3 special), or -1 when empty. */
-    list: number;
-    /** 0-based scene within `list` — index it against `devMenu.getStageList()`. */
-    zone: number;
-}
-/** A row of the engine's GAME OPTIONS screen (differs between Sonic 1 and 2). */
+/**
+ * A row of the engine's GAME OPTIONS screen (differs between Sonic 1 and 2), as the
+ * engine reports it — with `value` as the raw number it stores.
+ *
+ * The same rows also come back through `play.options()` as descriptors, where a
+ * boolean row reads as a boolean and an enum row as one of its choice labels. This is
+ * the untranslated view, for a host that wants it.
+ */
 export interface RsdkGameOption {
     key: string;
     label: string;
@@ -39,8 +83,8 @@ export interface RsdkGameOption {
 }
 /**
  * The engine's Start Menu as data, so a host can render save-slot / character /
- * game-option screens itself. Everything here mirrors what RSDKv4's own in-canvas
- * menu does — see WebGame.cpp.
+ * game-option screens itself. Everything here mirrors what RSDKv4's own in-canvas menu
+ * does — see WebGame.cpp.
  */
 export interface RsdkGameBridge {
     /** 1 = Sonic 1, 2 = Sonic 2, 0 = unrecognised pack. */
@@ -49,9 +93,12 @@ export interface RsdkGameBridge {
     players(): string[];
     saveSlots(): RsdkSaveSlot[];
     /**
-     * Start a game the way the native menu would: a slot with data continues it,
-     * an empty slot starts a new game as `player`, and `slot: null` plays without
-     * saving. Resumes the engine if the SDK had it paused.
+     * Start a game the way the native menu would: a slot with data continues it, an
+     * empty slot starts a new game as `player`, and `slot: null` plays without saving.
+     * Resumes the engine if the SDK had it paused.
+     *
+     * This is the index-taking form. `play.restart({ slot, player })` is the same thing
+     * through the contract, with the character named rather than numbered.
      */
     start(slot: number | null, player?: number): void;
     /** Wipe a slot back to "NEW GAME". */
@@ -60,48 +107,138 @@ export interface RsdkGameBridge {
     /** Set an option; written through to the engine and its save file, as the engine does. */
     setOption(key: string, value: number): void;
 }
-export type Rsdkv4Instance = Omit<EngineInstance, 'pause' | 'resume'> & {
+/**
+ * Input ownership, named — the same thing as `options({ buttons })` and
+ * `options({ buttons: null })`, for a host that would rather say what it means.
+ *
+ * See {@link Rsdkv4Options.buttons} for what a claim costs the host: keyup on focus
+ * loss, the gamepad, and remembering to release.
+ */
+export interface RsdkInputBridge {
     /**
-     * Pause, on behalf of `owner` (default 'host'). The first caller to pause owns
-     * it and only that owner's `resume()` lifts it, so a pause overlay can't
-     * resume a game a start screen — or the host — had already frozen. Audio stops
-     * with the engine.
+     * Take input over. The object is kept by reference and read once per tick — write
+     * to it, do not replace it.
+     *
+     * All fourteen keys of {@link Rsdkv4Buttons} must be present and nothing else may
+     * be: a missing key would read `false` for ever, and a misspelled one would be
+     * written to and never read. Both throw here instead.
      */
-    pause(owner?: string): void;
-    resume(owner?: string): void;
-    devMenu: RsdkDevMenuBridge;
-    game: RsdkGameBridge;
-    /** True when the working dir is OPFS-backed (persistent) rather than in-memory. */
-    persistent: boolean;
-    /** Relative storage namespace used under /data (e.g. "sonic1", "sonic2"). */
-    storageNamespace: string;
-    /** Remove persisted game files for this namespace only. */
-    purgeStorage(): {
-        data: boolean;
-        settings: boolean;
-    };
-};
+    claim(buttons: Rsdkv4Buttons): PromisePlay<Rsdkv4Payloads>;
+    /** Hand input back; the engine polls SDL again from the next tick. */
+    release(): PromisePlay<Rsdkv4Payloads>;
+    /** Whether a claim is held. The `options()` descriptor deliberately will not say. */
+    readonly claimed: boolean;
+}
+/**
+ * What `start()` and `restart()` hand back: the contract's chainable promise, narrowed
+ * so that awaiting it gives this engine's {@link Rsdkv4Play} rather than the contract's
+ * `EnginePlay` — which is what puts {@link Rsdkv4Play.game} within reach without a cast.
+ *
+ * Chaining (`.mount(…)`, `.options(…)`) returns the contract's own `PromisePlay`, so
+ * put the `await` at the end of the chain to keep the narrowing.
+ */
+export interface Rsdkv4Session extends PromisePlay<Rsdkv4Payloads> {
+    then<TResult1 = Rsdkv4Play, TResult2 = never>(onfulfilled?: ((value: Rsdkv4Play) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}
 /**
- * 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.
+ * The running engine.
+ *
+ * Most of it is the contract's, inherited: the four getter/setter pairs, the cumulative
+ * merge, the chainable promise, the event channel, and `destroy()`. What this class
+ * adds is the four hooks the base leaves to an engine — {@link open}, {@link close},
+ * {@link mounted}, {@link patched} — plus the members below, which have no contract
+ * equivalent and exist because RSDKv4 has a start menu worth drawing from HTML.
  */
-export type Rsdkv4LoadConfig = EngineConfig & {
-    dataProvider?: () => Promise<AssetData> | AssetData;
-    settingsProvider?: () => Promise<AssetData> | AssetData;
+export declare class Rsdkv4Play extends EnginePlayBase<Rsdkv4Payloads> {
+    #private;
+    constructor(init?: EngineInit<Rsdkv4Payloads>, events?: EventEmitter<Rsdkv4Events_>);
     /**
-     * Per-game storage folder under /data used for OPFS/WASMFS files.
-     * Examples: "sonic1", "sonic2", "my-pack/v1".
+     * Open or reopen a session. The first call brings the wasm up; every call after that
+     * reuses it, because RSDKv4 cannot power-cycle in process and does not need to — a
+     * session is a save slot, a character and a stage, and all three are reachable on a
+     * running engine.
      */
-    storageNamespace?: string;
-    /** Deprecated alias for `canvasEl`, kept for hosts written against 0.0.x. */
-    canvas?: HTMLCanvasElement;
-};
-/** Boot the RSDKv4 engine. */
-export declare function load(config: Rsdkv4LoadConfig): Promise<Rsdkv4Instance>;
-declare const _default: {
-    manifest: import("@wasm-gaming/engine-specs").EngineManifest;
-    load: typeof load;
-};
-export default _default;
+    protected open(options: Rsdkv4Options): Promise<void>;
+    /**
+     * Stop and release. The base emits `exit` once this resolves.
+     *
+     * There is no coming back: RSDKv4 cannot be restarted in process, so a later
+     * `start()` on the same factory reports that rather than quietly doing nothing.
+     */
+    protected close(): Promise<void>;
+    /**
+     * Where the picture goes. Called by the base before the first `open()`, which is what
+     * guarantees the canvas exists before Emscripten's SDL2 port goes looking for it.
+     *
+     * Hand over a `<canvas>` and it is used as-is, untouched apart from the id SDL needs;
+     * hand over any other element and the SDK creates a canvas inside it and keeps it
+     * scaled to fit. Reparenting a live engine is legal — the same canvas moves.
+     */
+    protected mounted(target: HTMLElement): Promise<void>;
+    /**
+     * A payload changed on a running engine. Only the GAME OPTIONS rows are `live` here —
+     * `config` is `settings.ini`, read once at boot, and `player`/`slot`/`stage` are what
+     * a `restart()` is for.
+     */
+    protected patched(kind: PayloadKind, patch: object): Promise<void>;
+    /**
+     * The session's descriptors, enriched with what only a loaded pack can say: the
+     * playable characters, the stage list, and the engine's own GAME OPTIONS rows.
+     *
+     * The base builds descriptors from a spec fixed at construction, which is right for
+     * every other payload and cannot work for this one — Sonic 1 and Sonic 2 do not offer
+     * the same characters or the same options, and neither is knowable before
+     * `Data.rsdk` is read. Before the engine is up this answers the static spec, which is
+     * still enough for a host to know the keys exist.
+     */
+    options(): Promise<PropertiesDefinition<Rsdkv4Options>>;
+    options(patch: Partial<Rsdkv4Options>): PromisePlay<Rsdkv4Payloads>;
+    restart(options?: Partial<Rsdkv4Options>): Rsdkv4Session;
+    /**
+     * Pause, on behalf of `owner`. The first caller to pause owns it and only that
+     * owner's `resume()` lifts it, so a pause overlay cannot resume a game a start
+     * screen — or the host — had already frozen. Audio stops with the engine.
+     *
+     * Emits the contract's `pause` event, whose detail carries the owner.
+     */
+    pause(owner?: string): void;
+    resume(owner?: string): void;
+    /** Who is holding the engine paused, or null. */
+    get pausedBy(): string | null;
+    /** True when the working dir is OPFS-backed rather than in-memory. */
+    get persistent(): boolean;
+    /** The normalised {@link Rsdkv4Storage.namespace} this session actually used. */
+    get namespace(): string;
+    /**
+     * Input ownership, named. `play.input.claim(buttons)` and `play.input.release()`
+     * are exactly `options({ buttons })` and `options({ buttons: null })` — same state,
+     * same survival across `restart()`, same everything.
+     */
+    get input(): RsdkInputBridge;
+    /** RSDKv4's Start Menu as data. Available once the engine is up. */
+    get game(): RsdkGameBridge;
+    /** The engine's stage list and loader. Available once the engine is up. */
+    get devMenu(): RsdkDevMenuBridge;
+}
+/**
+ * The factory a host imports: identity on the constructor, one live engine per
+ * instance, and a `start()` that brings the wasm up and opens a session.
+ *
+ * Everything on it is the contract's — see the module doc for the shape of a call.
+ */
+export declare class Rsdkv4SDK extends EngineSDKBase<Rsdkv4Payloads> {
+    static readonly id = "rsdkv4";
+    /** Kept in step with package.json by `node scripts/sync-version.mjs`. */
+    static readonly version = "0.2.0";
+    static readonly name = "Retro Software Development Kit v4";
+    static readonly description = "RSDKv4 compiled to WebAssembly via Emscripten. One game-agnostic WASM binary runs both Sonic 1 and Sonic 2 \u2014 the difference is only which Data.rsdk the host supplies at runtime. Ships none of the game: the player provides their own Data.rsdk, and it never leaves their browser.";
+    protected createPlay(init: EngineInit<Rsdkv4Payloads>, events: EventEmitter<Rsdkv4Events_>): Rsdkv4Play;
+    start(options?: Partial<Rsdkv4Options>): Rsdkv4Session;
+}
+/**
+ * The line that puts the contract in CI: if this file stops satisfying
+ * `EngineSDKConstructor`, `make typecheck` says so.
+ */
+export declare const RSDKV4_ENGINE: EngineSDKConstructor<Rsdkv4Payloads>;
+export default Rsdkv4SDK;
 //# sourceMappingURL=rsdkv4.sdk.d.ts.map

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

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