@wasm-gaming/engine-specs 0.2.5 → 0.2.7

package/README.md

@@ -9,35 +9,31 @@ TypeScript is the source of truth ([src/](src/)); a JSON Schema
 the manifest for non-TS consumers; a Zod-based validator lets any CI fail on
 drift.
 
+## Documentation
+
+**[API reference](https://wasm-gaming.github.io/engine-specs/api-docs/)** — every type,
+generated from the source. It also carries the [contract
+map](https://wasm-gaming.github.io/engine-specs/api-docs/documents/Contract_map.html)
+(how the types fit together) and the [usage
+guide](https://wasm-gaming.github.io/engine-specs/api-docs/documents/Usage.html)
+(host-side wiring, from validating a manifest to forwarding input).
+
+The [demo](https://wasm-gaming.github.io/engine-specs/) runs a dummy engine through the
+same contract.
+
 ## Two layers
 
 **Layer A — declarative ([src/manifest.ts](src/manifest.ts))**
-`EngineManifest` describes what an engine ships and needs: artifacts (`wasm`/`js`),
-runtime `assets` (each with a VFS `mountPath` + optional `validate`), the `input`
-preset, `video` geometry, engine-specific `options` (a JSON Schema), and
-`capabilities`. Everything that differs between engines lives here as data.
+`EngineManifest` is what an engine declares about itself before anything boots.
+Everything that differs between engines lives here as data.
 
 **Layer B — imperative ([src/engine.ts](src/engine.ts))**
 Every engine package default-exports an `EngineSDK` = `{ manifest, load }`.
-`load(config)` boots the engine and returns an `EngineInstance`
-(`start`/`pause`/`resume`/`reset`/`setInput`/`destroy`, plus capability-gated
-`saveState`/`loadState`/`screenshot`).
-
-`EngineConfig` requires at least one render mount target: `canvasEl`, `attachTo`,
-or both. `attachTo` is the host container element where an SDK can mount
-engine-owned DOM.
-
-`EngineConfig.storageNamespace` is an optional host hint for per-game storage
-segregation (for example OPFS folders like `sonic1` and `sonic2`).
-`EngineInstance.purgeStorage()` is an optional method for engines that can remove
-persisted runtime files for the active namespace only.
-
-The host drives all engines identically.
+`load(config)` boots the engine and returns an `EngineInstance` the host drives —
+identically for every engine.
 
 ## Usage
 
-For frontend integration examples and host-side wiring, see [USAGE.md](USAGE.md).
-
 An engine implements the contract:
 
 ```ts
@@ -66,6 +62,9 @@ npm install
 make build         # tsc → dist/ (.js + .d.ts)
 make typecheck     # no emit
 make test          # build + node test runner
+make docs          # typedoc → site/api-docs
+make site          # the Pages site: demo at the root, reference under /api-docs/
+make preview       # serve site/ on :8020
 make publish-dry-run
 make publish
 ```

package/demo/demo.js

@@ -307,7 +307,11 @@ const demo = {
         assetKey: "rom",
       });
 
-      const handleSaveRom = (file) => {
+      // Handlers bound to a jq79 mount are called as (event, payload) — the
+      // DOM CustomEvent first, the emitted value second. `demo.on()` below is
+      // a different emitter that passes the payload alone, so the two must not
+      // be read the same way.
+      const handleSaveRom = (_event, file) => {
         loadedFiles.rom = file;
         saveStoredAsset("rom", file);
         const payload = { file, key: "rom", type: "rom", action: "save" };
@@ -327,7 +331,7 @@ const demo = {
         demo.emit("file", payload);
       };
 
-      const handleSaveBios = (file) => {
+      const handleSaveBios = (_event, file) => {
         loadedFiles.bios = file;
         saveStoredAsset("bios", file);
         const payload = { file, key: "bios", type: "bios", action: "save" };
@@ -377,7 +381,7 @@ const demo = {
           .on("remove:rom", handleRemoveRom)
           .on("save:bios", handleSaveBios)
           .on("remove:bios", handleRemoveBios)
-          .on("launch", (payload) => bootWithFiles(payload))
+          .on("launch", (_event, payload) => bootWithFiles(payload))
           .mount(mainEl);
       };
 
@@ -468,6 +472,17 @@ const demo = {
                 customItems: escMenuConfig.items || [],
                 messages,
               })
+              .mount(escContainer);
+          };
+
+          // Bound once, not per render. The $emit channel lives on the
+          // Component79 instance and deliberately survives destroy() — that is
+          // what lets it work while detached — so re-registering these inside
+          // updateEscMenu() stacked a fresh set of listeners on every open,
+          // close and restore-defaults. After N re-renders a single click
+          // reached the handler N times, growing without bound.
+          const bindEscMenuEvents = () => {
+            CEscMenu
               .on("close", () => closeMenu())
               .on("reset", () => {
                 closeMenu();
@@ -499,7 +514,7 @@ const demo = {
                   escMenuConfig.onRestoreDefaults(currentInstance);
                 }
               })
-              .on("option-change", ({ key, value, option }) => {
+              .on("option-change", (_event, { key, value, option }) => {
                 if (currentInstance && typeof currentInstance.setOption === "function") {
                   currentInstance.setOption(key, value);
                 }
@@ -533,14 +548,13 @@ const demo = {
                 }
                 exitToLauncher();
               })
-              .on("custom-action", (item) => {
+              .on("custom-action", (_event, item) => {
                 closeMenu();
                 demo.emit("customAction", { item, instance: currentInstance });
                 if (typeof item?.action === "function") {
                   item.action(currentInstance);
                 }
-              })
-              .mount(escContainer);
+              });
           };
 
           const openMenu = () => {
@@ -581,6 +595,7 @@ const demo = {
           if (typeof window !== "undefined") {
             window.addEventListener("keydown", handleKeyDown);
           }
+          bindEscMenuEvents();
           updateEscMenu();
         }
       };

package/dist/engine.d.ts

@@ -1,78 +1,427 @@
 import type { EngineManifest, KeyMap, InputPreset } from './manifest.js';
-/** Binary asset payload accepted by `load()`. */
-export type AssetData = Uint8Array | ArrayBuffer | string;
-/** Where an engine may persist saves/SRAM. */
-export type PersistMode = 'idbfs' | 'opfs' | null;
-type EngineConfigBase = {
-    /** Runtime files keyed by `AssetSpec.key`. Required specs must be present. */
-    assets: Record<string, AssetData>;
-    /** Engine-specific settings, validated against `manifest.options`. */
-    options?: Record<string, unknown>;
-    /** Persistence backend for saves, when the engine supports it. */
-    persist?: PersistMode;
-    /**
-     * Optional storage namespace under the engine's working dir.
-     * Hosts can use this to isolate per-game persisted assets (e.g. sonic1/sonic2).
-     */
-    storageNamespace?: string;
-    /** Lifecycle/telemetry sink. Handlers must not throw. */
-    onEvent?: (e: EngineEvent) => void;
-    /** Override artifact locations (e.g. host-fetched Release assets). */
-    jsUrl?: string;
-    wasmUrl?: string;
+/**
+ * Where a runtime asset comes from.
+ *
+ * The host owns its files; the SDK only ever reads them. The SDK picks the
+ * strategy: an OPFS handle can be read on demand, a `showOpenFilePicker()` handle
+ * has no sync access and gets copied. The host does not need to know which.
+ *
+ * A thunk is resolved by `boot()`, and only if the asset is actually needed.
+ *
+ * @category Setup
+ */
+export type AssetSource = Uint8Array | ArrayBuffer | Blob
+/** A door to a file, read on demand. */
+ | FileSystemFileHandle
+/** A URL the SDK downloads. The only source that makes the SDK touch the network. */
+ | string
+/** Resolved lazily, by `boot()`, and only if the asset is needed. */
+ | (() => AssetSource | Promise<AssetSource>);
+/**
+ * The SDK's own folder: saved games, plus whatever internal state the engine
+ * persists. Never assets, never player preferences.
+ *
+ * There is no `required` flag: if the engine needs persistence and cannot have it,
+ * boot fails on its own with a typed {@link EngineError} that says *what* went
+ * wrong. Without `storage()` nothing is persisted at all.
+ *
+ * @category Setup
+ */
+export interface StorageSetup {
+    /** Folder the SDK owns, e.g. `"rsdkv4/sonic-1"`. Chosen by the host. */
+    namespace: string;
+}
+/** Live storage state, once the engine is up. @category Setup */
+export interface StorageInfo extends StorageSetup {
+    /** `false` when the browser granted only best-effort storage — warn the player. */
+    persistent: boolean;
+}
+/**
+ * The JSON-safe half of {@link EngineSetup}.
+ *
+ * `structuredClone` (and therefore IndexedDB) round-trips the full setup, but
+ * `JSON.stringify` silently turns a `FileSystemFileHandle`, an `ArrayBuffer` or a
+ * `Blob` into `{}` and drops functions. Only this half survives JSON.
+ *
+ * @category Setup
+ */
+export interface EngineSetupData<Config, Options> {
+    /** Engine settings, applied at boot. */
+    config?: Partial<Config>;
+    /** Default session payload — see {@link EngineSDK.options}. */
+    options?: Partial<Options>;
+    storage?: StorageSetup;
+}
+/**
+ * Everything the factory can be configured with, in one object.
+ *
+ * Accepted by the constructor, which is what makes "restore the last session"
+ * a single call. Anything settable here is settable by chaining, and vice versa.
+ *
+ * @category Setup
+ */
+export interface EngineSetup<Config, Options> extends EngineSetupData<Config, Options> {
+    /** Runtime files keyed by `AssetSpec.key`. */
+    assets?: Record<string, AssetSource>;
+    /** Where the engine is seen. A container is scaled by the SDK; a canvas is yours. */
+    mount?: HTMLElement;
+    on?: Partial<EngineEventHandlers>;
+}
+/**
+ * One setting, resolved: what is in effect, plus the JSON Schema vocabulary the
+ * manifest declared for it. Enough to paint a settings screen without asking the
+ * engine anything.
+ *
+ * There is no `source` field: the method you called *is* the source —
+ * {@link EngineSDK.config} are engine keys, {@link EngineSDK.options} are session keys.
+ *
+ * @category Config & options
+ */
+export interface ResolvedProperty<Value = unknown> {
+    /** What is in effect — or what will be used, if there is no engine yet. */
+    value: Value;
+    /** What the manifest declares, when it declares it. */
+    default?: Value;
+    /**
+     * Changing this needs a restart. It does **not** mean immutable: `player` is
+     * `readOnly` in `options()` and changes fine through {@link EnginePlay.restart}.
+     * A settings screen can grey it out instead of hiding it.
+     */
+    readOnly?: true;
+    type?: string;
+    enum?: readonly unknown[];
+    enumNames?: readonly string[];
+    minimum?: number;
+    maximum?: number;
+    title?: string;
+    description?: string;
+}
+/** Every key of `T`, resolved. The return shape of all four getters. @category Config & options */
+export type ResolvedProperties<T> = {
+    [K in keyof T]-?: ResolvedProperty<T[K]>;
 };
-export type EngineConfig = EngineConfigBase & ({
-    /** Render target. The SDK is responsible for the `#canvas` id if the engine needs it. */
-    canvasEl: HTMLCanvasElement;
-    /** Optional container element for SDK-owned DOM when a canvas element is present. */
-    attachTo?: HTMLElement;
-} | {
-    /** Optional render target when the SDK primarily mounts into a container element. */
-    canvasEl?: HTMLCanvasElement;
-    /** Container element the SDK can use to mount engine-owned DOM. */
-    attachTo: HTMLElement;
-});
-export type EngineEvent = {
-    type: 'ready';
-} | {
-    type: 'error';
-    error: Error;
-} | {
-    type: 'exit';
-} | {
-    type: 'frame';
-    fps: number;
+/**
+ * `ready` fires when `boot()` completes, `start` when a session opens. A
+ * `sdk.start()` emits both, in that order; a `restart()` does not re-emit `ready`.
+ *
+ * @category Events
+ */
+export interface EngineEventMap {
+    /** Engine up, no session. */
+    ready: void;
+    /** A session opened, with the payload it opened with. */
+    start: {
+        payload: unknown;
+    };
+    /** `total` may be absent — guard before dividing. */
+    progress: {
+        key: string;
+        loaded: number;
+        total?: number;
+    };
+    frame: {
+        fps: number;
+    };
+    pause: {
+        owner: string;
+    };
+    resume: {
+        owner: string;
+    };
+    error: {
+        error: EngineError;
+    };
+    exit: void;
+}
+/** @category Events */
+export type EngineEventHandlers = {
+    [K in keyof EngineEventMap]: (event: EngineEventMap[K]) => void;
 };
-export interface EngineInstance {
-    /** Begin running. `load()` may auto-start; then this is a no-op. */
-    start(): void;
-    pause(): void;
-    resume(): void;
-    /** Reset to power-on. May throw if the engine cannot reset in-process. */
-    reset(): void;
-    /** Swap the active input preset/map at runtime. */
-    setInput(map: InputPreset | KeyMap): void;
-    saveState?(): Promise<Uint8Array>;
-    loadState?(data: Uint8Array): Promise<void>;
-    screenshot?(): Promise<Blob>;
-    /**
-     * Optional targeted purge of persisted runtime files for the active namespace.
-     * Engines that do not persist assets can omit this method.
-     */
-    purgeStorage?(): {
-        data: boolean;
-        settings: boolean;
-    } | Promise<{
-        data: boolean;
-        settings: boolean;
-    }>;
-    /** Tear down: stop the loop, release listeners/DOM, free the instance. */
-    destroy(): void;
+/**
+ * Why boot or a call failed.
+ *
+ * Storage checks (OPFS availability, `crossOriginIsolated`, sync access, quota) run
+ * *before* the wasm is instantiated, so the failure arrives as a typed exception and
+ * not as a console warning halfway through loading.
+ *
+ * @category Errors
+ */
+export type EngineErrorCode = 
+/** No storage backend at all. */
+'storage-unavailable'
+/** The page needs COOP/COEP. */
+ | 'not-isolated'
+/** Another tab holds the namespace. */
+ | 'storage-locked' | 'quota-exceeded'
+/** A `required` asset was never handed over — see {@link EngineSDK.missingAssets}. */
+ | 'asset-missing'
+/** The engine could not parse the file. Integrity checks against a catalogue are the host's job. */
+ | 'asset-invalid' | 'unsupported-browser'
+/** A `readOnly` key was written on the live engine — use {@link EnginePlay.restart}. */
+ | 'read-only'
+/** A setup method was called while an instance was alive. */
+ | 'frozen'
+/** A method was called on a torn-down {@link EnginePlay}. */
+ | 'destroyed';
+/**
+ * Errors reach the host **both ways**: the promise rejects *and* `error` is
+ * emitted, so a host that does not `await` is not left blind.
+ *
+ * @category Errors
+ */
+export interface EngineError extends Error {
+    code: EngineErrorCode;
+}
+/** One save slot, as a launcher would paint it. @category Saves */
+export interface SaveSlot {
+    id: number;
+    empty: boolean;
+    /** Ready to show, e.g. `"Zone 1 · A · 3 lives"`. */
+    label: string;
+    /** Engine-specific extras the host may render. */
+    meta: Record<string, unknown>;
+}
+/**
+ * A promise of the live engine, hydrated with the engine's own methods.
+ *
+ * Every method of {@link EnginePlay} already returns a promise, so hydrating is
+ * enough: the actions come back as another `PlayPromise` and keep chaining, the
+ * queries come back as a plain promise and close.
+ *
+ * ```js
+ * await play.pause(OWNER.menu).options({ spindash: true }).resume(OWNER.menu)
+ * const slots = await play.pause(OWNER.menu).saves()   // closes
+ * ```
+ *
+ * Two normative rules:
+ *
+ * - A rejection aborts the rest of the chain — nothing downstream runs.
+ * - It is a `Promise` subclass whose `Symbol.species` is `Promise`, so `then()`,
+ *   `catch()` and `finally()` return a **plain** promise. Calling `then()` closes
+ *   the chain, like a getter does.
+ *
+ * @category Lifecycle
+ */
+export type PlayPromise<Play> = Promise<Play> & Play;
+/**
+ * The live engine. Handed to the host by {@link EngineSDK.boot} or
+ * {@link EngineSDK.start}; never constructed by the host.
+ *
+ * Sessions come and go on the same live engine: `boot()` gives you one with no
+ * session at all, and each {@link EnginePlay.restart} opens another.
+ *
+ * The capability-gated members exist **if and only if** `manifest.capabilities`
+ * says so, so `if (play.saveState)` and reading the manifest always agree.
+ *
+ * @category Lifecycle
+ */
+export declare abstract class EnginePlay<Options = Record<string, unknown>, Config = Record<string, unknown>> {
+    /**
+     * Open a session, or reopen it.
+     *
+     * The payload is cumulative: there is one current payload, it starts as the
+     * factory's, and every `start()`/`restart()` merges its own on top (flat merge,
+     * one level). So `restart({ slot: 3 })` keeps the `player` you opened with, and
+     * `restart()` with no argument is a power cycle that repeats the current payload.
+     *
+     * `null` is an explicit value, not "leave unchanged".
+     */
+    abstract restart(options?: Partial<Options>): PlayPromise<this>;
+    /**
+     * Freeze, on behalf of `owner`. Only the owner can resume, so an overlay cannot
+     * resume what another one froze.
+     */
+    abstract pause(owner: string): PlayPromise<this>;
+    /** Resume. Ignored when the pause belongs to somebody else. */
+    abstract resume(owner: string): PlayPromise<this>;
+    /**
+     * Move the picture — reparents and refits. Throws on a different canvas: the GL
+     * context was bound to a surface at boot.
+     */
+    abstract mount(target: HTMLElement): PlayPromise<this>;
+    abstract setInput(map: InputPreset | KeyMap): PlayPromise<this>;
+    /** Read the live engine settings: same keys as `sdk.config()`, current values. */
+    abstract config(): Promise<ResolvedProperties<Config>>;
+    /**
+     * Apply engine settings to *this session only*. Never persisted — where
+     * preferences live is the UI's call. Throws `read-only` on a `readOnly` key.
+     */
+    abstract config(values: Partial<Config>): PlayPromise<this>;
+    /** Read the session options. Runtime discovery: their keys come from the loaded content. */
+    abstract options(): Promise<ResolvedProperties<Options>>;
+    /**
+     * Write session options, as flat values. Throws `read-only` on a `readOnly` key —
+     * those change through {@link EnginePlay.restart}.
+     *
+     * The getter shape (`{ volume: { value: 0.8 } }`) is not accepted: it would be
+     * ambiguous the day a property is itself an object.
+     */
+    abstract options(values: Partial<Options>): PlayPromise<this>;
+    /** Where saves are going, and whether the browser will really keep them. */
+    abstract storage(): Promise<StorageInfo>;
+    abstract on<K extends keyof EngineEventMap>(type: K, handler: (event: EngineEventMap[K]) => void): PlayPromise<this>;
+    abstract off<K extends keyof EngineEventMap>(type: K, handler: (event: EngineEventMap[K]) => void): PlayPromise<this>;
+    /**
+     * Stop the loop, silence the audio, flush saves, release the canvas.
+     *
+     * **Closes the chain** — the factory stays frozen until this settles, which is
+     * what stops a host from repointing `storage()` while the old engine is still
+     * flushing into the old namespace.
+     *
+     * Idempotent: calling it again resolves and does nothing. The freeze is released
+     * when it *settles*, not when it fulfils — a failed flush must not brick the
+     * factory. Afterwards every method here throws `destroyed`, in-flight chains
+     * included.
+     */
+    abstract destroy(): Promise<void>;
+    /** Present when `capabilities.saves !== false`. */
+    abstract saves?(): Promise<SaveSlot[]>;
+    /** Present when `capabilities.saves !== false`. */
+    abstract deleteSave?(id: number): PlayPromise<this>;
+    /** Present when `capabilities.saveStates`. */
+    abstract saveState?(): Promise<Uint8Array>;
+    /** Present when `capabilities.saveStates`. */
+    abstract loadState?(data: Uint8Array): PlayPromise<this>;
+    /** Present when `capabilities.screenshots`. */
+    abstract screenshot?(): Promise<Blob>;
+}
+/**
+ * The factory every engine package exports a subclass of.
+ *
+ * Configured by chaining — all of it synchronous, because none of it crosses to
+ * the engine; these methods record, they do not resolve. Then `boot()` or
+ * `start()` produce the live {@link EnginePlay}.
+ *
+ * ```js
+ * const play = await new MotorSDK()
+ *   .assets({ data: packHandle })
+ *   .config({ language: 4 })
+ *   .storage({ namespace: 'motor/game-1' })
+ *   .on('error', report)
+ *   .mount(document.querySelector('#stage'))
+ *   .start({ slot: 0, player: 1 })
+ * ```
+ *
+ * Anything settable by chaining is settable in the constructor, and vice versa.
+ *
+ * Three boot verbs, two of them sugar for the third — and the equivalence is
+ * literal, it is how the base class implements them:
+ *
+ * | | what it does | equals |
+ * | --- | --- | --- |
+ * | `boot()` | engine alive, no session | — |
+ * | `play.restart(p)` | opens or reopens a session | — |
+ * | `start(p)` | engine alive **and** session running | `boot().restart(p)` |
+ *
+ * `boot()` is idempotent, so a factory governs at most one live engine, and
+ * `start(p)` on a live one is just `restart(p)`. Neither throws.
+ *
+ * @typeParam Config - the engine's own settings. Close it per engine; an open
+ * `Record<string, unknown>` gives up the compile-time check that is the point.
+ * @typeParam Options - the session payload, i.e. the writable keys of
+ * {@link EnginePlay.options}.
+ * @typeParam Play - the engine's own {@link EnginePlay} subclass, when it adds methods.
+ *
+ * @category Factory
+ */
+export declare abstract class EngineSDK<Config = Record<string, unknown>, Options = Record<string, unknown>, Play extends EnginePlay<Options, Config> = EnginePlay<Options, Config>> {
+    /**
+     * Accepts the whole setup at once, which is what makes "restore the last session"
+     * a single call. Only {@link EngineSetupData} survives `JSON` — use
+     * `structuredClone`/IndexedDB for the rest.
+     */
+    constructor(setup?: EngineSetup<Config, Options>);
+    /**
+     * Register asset sources. **Always synchronous** — it records sources, it does
+     * not resolve them, which is why a value may be a thunk.
+     *
+     * Throws `frozen` while an engine is alive.
+     */
+    abstract assets(sources: Record<string, AssetSource>): this;
+    /**
+     * Read the boot settings, without booting anything — enough to paint a
+     * preferences screen. Synchronous: there is no engine to ask, only
+     * `manifest.config` and whatever the chain put on top.
+     *
+     * With a live engine this still reads *what it booted with*;
+     * {@link EnginePlay.config} reads how it is now. Both are correct at once.
+     */
+    abstract config(): ResolvedProperties<Config>;
+    /** Set the boot settings. Throws `frozen` while an engine is alive. */
+    abstract config(values: Partial<Config>): this;
+    /**
+     * Read the current session payload. Synchronous, and thinner than the other
+     * getters — session keys are declared by the loaded content, so with no engine
+     * there is no `enum` or `title` to give, only `value`.
+     */
+    abstract options(): ResolvedProperties<Options>;
+    /**
+     * Set the payload the next session will open with. Exactly the same as passing it
+     * to `start()`.
+     *
+     * Unlike `assets()`, `config()` and `storage()` this does **not** freeze with a
+     * live engine: it does not describe the engine, it describes the next session,
+     * and opening another session is legal at any time. It changes nothing hot —
+     * that is {@link EnginePlay.options}.
+     */
+    abstract options(payload: Partial<Options>): this;
+    /** Point the SDK at its folder. Throws `frozen` while an engine is alive. */
+    abstract storage(setup: StorageSetup): this;
+    /**
+     * Where the engine will be seen. A container is scaled by the SDK; pass your own
+     * canvas and the scaling is yours — and only before booting.
+     */
+    abstract mount(target: HTMLElement): this;
+    abstract on<K extends keyof EngineEventMap>(type: K, handler: (event: EngineEventMap[K]) => void): this;
+    abstract off<K extends keyof EngineEventMap>(type: K, handler: (event: EngineEventMap[K]) => void): this;
+    /**
+     * The `required` manifest keys that have not been handed over, **or whose value
+     * is not a valid {@link AssetSource}** — a `{}` left by a lost JSON round-trip
+     * counts as absent, not as present.
+     *
+     * Synchronous: it reads the chain, not the disk. Whether the file exists in the
+     * host's library is the host's question.
+     */
+    abstract missingAssets(): string[];
+    /**
+     * Engine alive, no session — where a launcher reads the saves and paints its
+     * cards before committing to a game.
+     *
+     * Idempotent: with a live engine it returns *that* engine.
+     */
+    abstract boot(): PlayPromise<Play>;
+    /** `boot()` and open a session. Literally `boot().restart(payload)`. */
+    abstract start(payload?: Partial<Options>): PlayPromise<Play>;
+    /**
+     * Read the saves without a session.
+     *
+     * Present when `capabilities.saves !== false`. With `'storage'` it reads the
+     * store in JS and does **not** boot; with `'engine'` it is sugar for
+     * `boot().saves()` and does boot. Same rows either way.
+     *
+     * Every factory method that needs a live engine is sugar for
+     * `boot().<method>()`; the capability only says whether that boot can be skipped.
+     */
+    abstract saves?(): Promise<SaveSlot[]>;
+    /**
+     * The only thing a concrete engine implements. Everything above is written once,
+     * in the base class.
+     */
+    protected abstract create(setup: EngineSetup<Config, Options>): Promise<Play>;
 }
-/** The default export shape every engine package must provide. */
-export interface EngineSDK {
-    manifest: EngineManifest;
-    load(config: EngineConfig): Promise<EngineInstance>;
+/**
+ * The static side of an engine package's export — the half `implements` cannot
+ * check, since TypeScript has no abstract statics.
+ *
+ * ```ts
+ * const _contract: EngineSDKClass<MotorConfig, MotorOptions, MotorPlay> = MotorSDK
+ * ```
+ *
+ * @category Factory
+ */
+export interface EngineSDKClass<Config = Record<string, unknown>, Options = Record<string, unknown>, Play extends EnginePlay<Options, Config> = EnginePlay<Options, Config>> {
+    new (setup?: EngineSetup<Config, Options>): EngineSDK<Config, Options, Play>;
+    /** What the engine knows about itself, with nothing instantiated. */
+    readonly manifest: EngineManifest;
 }
-export {};
 //# sourceMappingURL=engine.d.ts.map