@wasm-gaming/rsdkv4-wasm 0.2.0 → 0.3.0

package/README.md

@@ -10,228 +10,170 @@ into the Emscripten filesystem *at runtime*, so the same `rsdkv4.wasm` runs both
 is what picks the game. (The old build baked `Data.rsdk` in with `--preload-file`
 and had to be recompiled per game; this doesn't.)
 
-## Contract surface
+## Install
 
-```js
-import { manifest, load } from '@wasm-gaming/rsdkv4-wasm';
-
-const engine = await load({
-  canvas,                       // an <canvas id="canvas">
-  assets: { data: dataRsdkBytes /*, settings: iniBytes */ },
-  storageNamespace: 'sonic1',   // carpeta por juego bajo /data (OPFS/WASMFS)
-  onEvent: (e) => { /* 'ready' | 'error' | 'exit' */ },
-  // Where the app placed the CI-built artifacts (defaults to package-relative):
-  // jsUrl, wasmUrl,
-});
-
-engine.pause();
-engine.resume();
-engine.setInput('rsdkv4');
-engine.purgeStorage();           // borra Data.rsdk/settings.ini de este namespace
-engine.destroy();
+```bash
+npm install @wasm-gaming/rsdkv4-wasm
 ```
 
-- `manifest` — declarative `EngineManifest` (see [src/rsdkv4.manifest.ts](src/rsdkv4.manifest.ts)):
-  required `data` asset (`/Data.rsdk`), optional `settings` asset (`/settings.ini`),
-  `input: "rsdkv4"` preset, 16:9 video, no save-states.
-- `load(config)` → `EngineInstance` (`start`/`pause`/`resume`/`reset`/`setInput`/`destroy`).
-  `reset()` is unsupported by RSDKv4 — `destroy()` and `load()` again.
+One dependency comes with it: `@wasm-gaming/engine-specs`, the engine contract. The
+built SDK carries the contract's runtime beside it (`dist/rsdkv4/engine-specs.js`) and
+imports it relatively, so the package loads from any static server — **no bundler and
+no import map needed**. Serve `dist/rsdkv4/` as is and import `rsdkv4.sdk.js`.
+
+## Contract surface
 
-### Dev menu — the launcher owns the UI
-The debug/stage-select **UI is the launcher's responsibility**, not the engine's.
-The engine only exposes the raw bridge as `instance.devMenu` (backed by the
-`web_devmenu_*` embind functions compiled into the WASM):
+The SDK implements the [wasm-gaming engine contract](https://github.com/wasm-gaming/engine-specs)
+1.0: a class with a static identity, configured by chaining, that opens a live session.
 
 ```js
-const engine = await load({ canvas, assets: { data } });
-engine.pause();                              // freeze while a menu is open
-const categories = engine.devMenu.getStageList();   // [{ name, stages: [{ name }] }]
-engine.devMenu.loadStage(0, 2);              // warp to category 0 / stage 2
-engine.resume();
+import Rsdkv4SDK from '@wasm-gaming/rsdkv4-wasm';
+
+Rsdkv4SDK.id;        // 'rsdkv4' — also this engine's folder in OPFS
+Rsdkv4SDK.version;   // '0.3.0'
+
+const play = await new Rsdkv4SDK()
+  .config({ startMenu: 'host' })               // engine: who draws the start screens
+  .assets({ data: () => fetchDataRsdk() })     // Data.rsdk — bytes, or a thunk called only on a miss
+  .storage({ namespace: 'sonic-1' })           // → OPFS rsdkv4/sonic-1/
+  .on('saves', ({ detail }) => paintSlots(detail))
+  .on('error', ({ detail }) => report(detail))
+  .mount(document.querySelector('#stage'))     // a <canvas> is used as is; anything else gets one inside
+  .start({ slot: 0, player: 1 });              // session: slot 0 as Tails
+
+await play.restart({ slot: 2 });
+await play.destroy();                          // stops audio, flushes the save, releases the canvas
 ```
 
-The launcher decides how Escape behaves and draws its own overlay. It should
-intercept Escape in the **capture phase** if it wants to repurpose it (the engine
-ships with `DevMenu=false`, so the native in-canvas menu stays suppressed).
-
-> ⚠️ A capture-phase listener on `window` that calls `stopPropagation()` also
-> stops the **bubble**-phase listener SDL registers there — i.e. it takes the
-> keyboard away from the game. Swallow only the keys you actually handle, and
-> only while your overlay is open. (This is exactly how the shared demo
-> template's pause menu used to kill the d-pad; see
-> [src/demo/components/esc-menu.html](src/demo/components/esc-menu.html).)
-
-### Start menu — the host can own that too
-`instance.game` exposes RSDKv4's Start Menu as data (the `web_*` embind functions
-in `WebGame.cpp`), so a host can draw its own save / character / options screens
-instead of the engine's in-canvas text menus. The logic mirrors
-`Debug.cpp` move for move — same globals, same `saveRAM`, same
-`InitStartingStage()` — so a game started this way lands in the state the native
-menu would have produced.
+The four payloads, each read with `await sdk.config()` (a descriptor per key: value,
+default, enum, description, `live`) and written with `sdk.config({ … })`:
 
-```js
-const engine = await load({ canvas, assets: { data },
-  options: { skipStartMenu: true },     // hide the engine's own screens
-});
-
-engine.game.type();          // 1 = Sonic 1, 2 = Sonic 2
-engine.game.players();       // ["SONIC", "TAILS", "KNUCKLES", "SONIC AND TAILS"]
-engine.game.saveSlots();     // [{ slot, empty, character, lives, score, emeralds, list, zone }]
-engine.game.start(0, 1);     // slot 0 as Tails — a slot with data resumes it
-engine.game.start(null, 0);  // no-save mode
-engine.game.deleteSave(2);
-
-engine.game.options();               // the engine's GAME OPTIONS screen, as data
-engine.game.setOption('spindash', 1); // written through to the game's save file
-```
+| payload | keys |
+| --- | --- |
+| `config` (engine) | `startMenu` (`'native'` \| `'host'`), `devMenu`, `engineDebugMode`, `vsync`, `jsUrl`, `wasmUrl` |
+| `options` (session) | `slot`, `player`, `stage`, `buttons` |
+| `assets` | `data` (Data.rsdk, required), `settings` (settings.ini, optional — generated from `config` otherwise) |
+| `storage` | `namespace`, `persist` (`'opfs'` \| `null`) |
 
-`load()` resolves only once `Engine::Init` has run, so all of the above is safe to
-call the moment it returns. The demo's [start-screens.ts](src/demo/start-screens.ts)
-is a worked example.
+Types: `Rsdkv4Config`, `Rsdkv4Options`, `Rsdkv4Assets`, `Rsdkv4Storage` and the full
+spec as data in `RSDKV4_SPEC` ([src/rsdkv4.options.ts](src/rsdkv4.options.ts)). CI holds
+the class to the contract with one line: `RSDKV4_ENGINE: EngineSDKConstructor<Rsdkv4Payloads>`.
 
-### Pausing has an owner
-`pause(owner?)` / `resume(owner?)` — the **first** caller to pause owns it, and only
-that owner's `resume()` lifts it. A pause overlay therefore can't resume a game a
-start screen (or the host) had already frozen:
+Events: the contract's `start`, `error`, `exit`, `pause`, `resume`, plus `saves`
+(the slots, emitted when `SData.bin` changed and was persisted).
+
+`jsUrl` / `wasmUrl` default to `rsdkv4.js` / `rsdkv4.wasm` next to `rsdkv4.sdk.js`; a
+host that serves them elsewhere sets them in `config`.
+
+### Start menu — the host can own it
+
+With `config({ startMenu: 'host' })` the engine's own save / character / options screens
+are skipped and `play.game` exposes them as data (the `web_*` embind functions in
+`WebGame.cpp`, mirroring `Debug.cpp` move for move, so a game started this way lands in
+the state the native menu would have produced):
 
 ```js
-engine.pause('menu');     // overlay opens
-engine.resume('menu');    // …closes: only resumes if 'menu' was the one that paused
+play.game.type();             // 1 = Sonic 1, 2 = Sonic 2
+play.game.players();          // ["SONIC", "TAILS", "KNUCKLES", "SONIC AND TAILS"]
+play.game.saveSlots();        // [{ slot, empty, character, lives, score, emeralds, list, zone }]
+play.game.start(0, 1);        // slot 0 as Tails — a slot with data resumes it
+play.game.start(null, 0);     // no-save mode
+play.game.deleteSave(2);
+play.game.options();          // the GAME OPTIONS screen, as data
+play.game.setOption('spindash', 1);
 ```
 
-Pausing stops the **audio** too: `masterPaused` only freezes the logic loop, so
-without that the music kept playing over the overlay — and `destroy()` kept
-playing it after the host returned to its launcher.
+`start()` resolves only once `Engine::Init` has run, so all of the above is safe to call
+the moment it does.
+
+### Dev menu — the host owns the UI
 
-### Options
-Engine-specific options are described in [src/rsdkv4.options.ts](src/rsdkv4.options.ts)
-(`Rsdkv4Options` type + `RSDKV4_OPTIONS_SCHEMA`, mirrored into
-[src/rsdkv4.manifest.ts](src/rsdkv4.manifest.ts)'s `options`). When the host doesn't pass an explicit
-`settings` asset, the SDK **generates `settings.ini` from `config.options`**
-(`devMenu`, `engineDebugMode`, `vsync`, `skipStartMenu`,
-`startingCategory/Scene/Player`).
+The stage-select **UI is the host's**; the engine exposes the bridge as `play.devMenu`
+(`getStageList()`, `loadStage(category, stage)`, `setPaused()`, `open()`). The engine
+ships with `devMenu: false`, so the native in-canvas menu stays suppressed.
 
-> `startingCategory/Scene/Player` default to **255 = unset**, which is what the
-> engine reads as "boot normally". Any other value — *including 0* — makes
-> `Engine::Init` skip the start-menu flow and force that stage.
+> ⚠️ A capture-phase listener on `window` that calls `stopPropagation()` also stops the
+> bubble-phase listener SDL registers there — i.e. it takes the keyboard away from the
+> game. Swallow only the keys you handle, and only while your overlay is open.
+
+### Pausing has an owner
+
+`play.pause(owner?)` / `play.resume(owner?)` — 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 had already frozen. Pausing stops the audio too.
+
+### Input
+
+`play.input.claim(buttons)` / `play.input.release()` (same as `options({ buttons })`)
+let a host drive the fourteen buttons instead of the engine reading the keyboard.
 
 ### Other niceties
-- **Canvas id guard** — forces `canvas.id = "canvas"` because Emscripten's SDL2
-  port locates the canvas via `querySelector('#canvas')`.
-- **Stale-engine self-heal** — `rsdkv4.js`/`.wasm` are big and most static hosts
-  send nothing but `Last-Modified`, so browsers keep a build for hours. Fresh SDK
-  against a cached engine is a miserable failure mode: the bridges it calls
-  aren't there and every getter quietly answers "empty" — no save slots, no
-  characters, an empty pause menu. So `load()` checks the module for the bridges
-  it needs and, if any are missing, refetches once with a cache-busting query and
-  says so in the console. A healthy build loads the engine exactly once.
-
-> Audio autoplay-unlock and the gamepad→keyboard translator are cross-cutting host
-> concerns (the app's shared input script); the SDK only exposes the `input`
-> preset name via the manifest and `setInput()`.
+
+- **Canvas id guard** — Emscripten's SDL2 port finds the canvas with
+  `querySelector('#canvas')`, so the SDK gives the canvas that id.
+- **Stale-engine self-heal** — fresh SDK against a browser-cached older wasm would make
+  every getter answer "empty". The SDK checks the module for the bridges it needs and,
+  if any are missing, refetches once past the HTTP cache and says so in the console.
 
 ## Filesystem (WASMFS / OPFS)
 
-Built with **`-sWASMFS`** — Emscripten's modern filesystem, replacing MEMFS. The
-game working dir `/data` is mounted on **OPFS** (persistent) via the `WebFS.cpp`
-`web_mount_opfs` helper when the page is **cross-origin isolated** *and* the wasm
-build can create the OPFS backend from the main thread (see the caveat below —
-today's build can't); otherwise it falls back to the WASMFS in-memory backend so
-the engine still boots. `Data.rsdk`
-and the generated `settings.ini` are written there and read via CWD (the engine
-is booted with the `UsingCWD` arg).
+Built with **`-sWASMFS`**. WASMFS `/data` is the OPFS root, mounted when the page is
+cross-origin isolated *and* the build can create the OPFS backend from the main thread;
+otherwise it falls back to the in-memory backend so the engine still boots.
+
+### Every file lives in the engine's own folder
+
+```
+OPFS root (= WASMFS /data)
+└── rsdkv4/              ← Rsdkv4SDK.id, added by the SDK
+    └── <namespace>/     ← storage({ namespace }), default "default"
+        ├── Data.rsdk
+        ├── settings.ini
+        └── SData.bin
+```
+
+The host picks the namespace; **the engine owns the root**. No namespace can reach
+another engine's files or climb out of `rsdkv4/`: segments are cleaned (`.` and `..`
+dropped, characters outside `[A-Za-z0-9._-]` → `_`), and anything unusable becomes
+`default`. `play.storagePath` gives the resolved path (`'rsdkv4/sonic-1'`), which is
+also the OPFS path a host walks with `navigator.storage.getDirectory()`:
+
+| host, from JS (OPFS API)        | engine, inside WASMFS              |
+| ------------------------------- | ---------------------------------- |
+| `rsdkv4/sonic-1/Data.rsdk`      | `/data/rsdkv4/sonic-1/Data.rsdk`   |
+
+So a launcher can **install** a game by writing `Data.rsdk` into
+`rsdkv4/<namespace>/` and later start it with `storage({ namespace })` and no
+`assets.data` at all — the SDK finds the persisted copy and skips the copy. One ~40 MB
+pack, not two, and the save lands next to it. `storagePath(engineId, namespace)` is
+exported for hosts that need the path before a session exists.
+
+**Upgrading from 0.2.x:** a namespace starting with `rsdkv4/` (the old convention,
+e.g. `'rsdkv4/Sonic1'`) has the prefix stripped once, with a console warning, so its
+files stay where they were — pass `'Sonic1'`. Files from the old top-level `default/`
+folder (`Data.rsdk`, `settings.ini`, `SData.bin`) are **copied** into
+`rsdkv4/default/` the first time the default namespace boots; the old folder is left
+untouched, since other engines used `default/` too.
+
+### Backend selection — `storage.persist`
 
-### Backend selection — `config.persist`
 - `undefined` (default) — **auto**: OPFS when cross-origin isolated *and* the build
   supports the mount, else in-memory.
-- `'opfs'` — **ask for** OPFS; warn + fall back to in-memory if unavailable. (It
-  can't be *forced*: a build that can't mount OPFS would abort the module, so the
-  SDK checks first and falls back rather than trying.)
-- `null` — **force the in-memory** WASMFS backend (the MEMFS-equivalent fallback;
-  non-persistent).
-
-(`'idbfs'` isn't supported under WASMFS and is treated as in-memory.)
-
-### Per-game storage namespace — `config.storageNamespace`
-- `undefined` (default) — uses `/data/default`.
-- `'sonic1'` / `'sonic2'` (recommended) — keeps each game in its own folder,
-  e.g. `/data/sonic1` and `/data/sonic2`.
-- Supports nested paths like `'sonic1/profile-a'`.
-
-This prevents cross-game reuse collisions and allows purging one game's files
-without touching the others.
-
-### `/data` *is* the OPFS root
-`web_mount_opfs` mounts the backend returned by `wasmfs_create_opfs_backend()`,
-whose root is `navigator.storage.getDirectory()`. So the WASM path `/data/<ns>/…`
-and the OPFS path `<ns>/…` a host reaches from JS are **the same file**:
-
-| host, from JS (OPFS API)     | engine, inside WASMFS         |
-| ---------------------------- | ----------------------------- |
-| `rsdkv4/Sonic1/Data.rsdk`    | `/data/rsdkv4/Sonic1/Data.rsdk` |
-
-A launcher can therefore write a player's `Data.rsdk` straight into the folder the
-engine will use as its working dir and then load with
-`storageNamespace: 'rsdkv4/Sonic1'` and **no `assets.data` at all** — the SDK finds
-the file already persisted and skips the copy. That is what this repo's demo does
-(see [Try it locally](#try-it-locally)); it keeps one copy of a ~40 MB pack instead
-of two, and the game's save data lands next to it in the same folder.
+- `'opfs'` — **ask for** OPFS; warn and fall back to in-memory if unavailable.
+- `null` — force in-memory, and switch off the save mirror: nothing is kept.
 
 ### Save data survives even without the mount
-The engine writes its save file (`SData.bin`) into the working dir, which is
-in-memory on every build that can't mount OPFS — so game saves would die with the
-page and every slot would read "NEW GAME" forever. The *host* side of OPFS has no
-such limitation (the plain async API works on any main thread), so the SDK
-mirrors that one file itself: it copies any stored `SData.bin` into the working
-dir before the engine boots, and copies it back out on pause, on `destroy()`, and
-every 10s in between. Saves therefore persist per `storageNamespace` even while
-the working dir does not. `persist: null` turns the mirror off with everything else.
 
-### Skip re-fetch when already persisted
-When the working dir is OPFS-backed, the SDK checks whether `/data/Data.rsdk`
-(and `settings.ini`) already exist and **reuses them instead of re-downloading**.
-Precedence for `Data.rsdk`: explicit `assets.data` → persisted OPFS copy → lazy
-`dataProvider()` (called only on a miss). So a host can pass a `dataProvider` that
-fetches the ROM and it will only run on first load / non-isolated pages:
-
-```js
-await load({
-  canvas,
-  assets: {},                                  // no eager 40 MB download
-  storageNamespace: 'sonic1',                  // namespace-specific cache
-  dataProvider: () => fetch('/Data.rsdk').then(r => r.arrayBuffer()),
-});
-```
+On every build that can't mount OPFS the working dir is in-memory, so `SData.bin` would
+die with the page. The host-side OPFS API has no such limitation, so the SDK mirrors that
+one file itself: in before boot, out on pause, on `destroy()`, when the page is hidden,
+and every 10 s — always to `rsdkv4/<namespace>/SData.bin`, and `saves` fires when it moved.
 
-To purge only one game's persisted files:
-
-```js
-const sonic2 = await load({
-  canvas,
-  assets: {},
-  storageNamespace: 'sonic2',
-  dataProvider: () => fetch('/sonic2/Data.rsdk').then(r => r.arrayBuffer()),
-});
-
-// Removes /data/sonic2/Data.rsdk and /data/sonic2/settings.ini only.
-const purged = sonic2.purgeStorage();
-console.log(purged); // { data: true|false, settings: true|false }
-```
+### Skip re-fetch when already persisted
 
-> Persistence doesn't engage with the current build (see the OPFS caveat below),
-> so the skip-fetch benefit isn't real yet — every load fetches.
-
-> ⚠️ **OPFS caveat:** OPFS sync-access handles only exist in Workers, so WASMFS's
-> OPFS backend spawns a proxy worker — and it **refuses to do that from the main
-> browser thread** unless the build has **`-sASYNCIFY`** or **`-sJSPI`**. It
-> doesn't fail softly either: `wasmfs_create_opfs_backend()` asserts, and the
-> failed assert `abort()`s the module, so there is nothing left to fall back with.
-> The SDK mounts by calling into the module from the page (main thread) and this
-> build has neither flag, so `web_opfs_supported()` (WebFS.cpp) reports 0 and the
-> SDK never attempts the mount — COOP/COEP alone changes nothing. Making it real
-> means either building with Asyncify/JSPI, or `-pthread` + performing the mount
-> from the engine thread; both interact with SDL2 + `emscripten_set_main_loop` and
-> must be validated with a real build.
+Precedence for `Data.rsdk`: explicit bytes in `assets.data` → a copy already in
+`rsdkv4/<namespace>/` → the `assets.data` thunk (called only on a miss). So a host can
+hand over a thunk that downloads the pack and it only runs the first time.
 
 ## Build
 
@@ -244,8 +186,9 @@ make build-sdk    # TypeScript only → dist/ (fast; no Docker)
 make build-wasm   # local: runs scripts/build.sh inside emscripten/emsdk (Docker)
 ```
 
-- `build-lib` compiles the SDK/options/manifest (`.js` + `.d.ts`) → `dist/rsdkv4/`.
-- `build-manifest` serializes the typed manifest to `dist/manifest.json`.
+- `build-lib` compiles the SDK and options (`.js` + `.d.ts`) → `dist/rsdkv4/`.
+- `build-specs` copies the contract's runtime to `dist/rsdkv4/engine-specs.js` and rewrites
+  the SDK's import to it (`scripts/localize-specs.mjs`), so the package is self-contained.
 - `build-demo` compiles `src/demo/{demo,library}.ts` → `dist/`, copies the shared
   demo template from `@wasm-gaming/engine-specs` → `dist/demo/`, overwrites its
   launcher with `src/demo/components/launcher.html` (the two-game one), copies
@@ -260,8 +203,9 @@ make build-wasm   # local: runs scripts/build.sh inside emscripten/emsdk (Docker
   `-sWASMFS -sINVOKE_RUN=0 -sMODULARIZE=1 -sEXPORT_ES6=1 -sEXPORT_NAME=createRSDKv4`
   + `FS`/`callMain`/`ccall` exported, **without** `--preload-file`.
 
-Contract types are resolved from the npm package `@wasm-gaming/engine-specs`
-(installed via this project's devDependencies).
+The contract is the one dependency: `@wasm-gaming/engine-specs` (types from the package,
+runtime copied into `dist/rsdkv4/`). `make test` type-checks the SDK and runs `tests/`
+against the built package.
 
 ### dist/ layout
 
@@ -272,8 +216,7 @@ dist/
 │   ├── rsdkv4.wasm
 │   ├── rsdkv4.sdk.js     (+ .d.ts)
 │   ├── rsdkv4.options.js (+ .d.ts)
-│   └── rsdkv4.manifest.js(+ .d.ts)
-├── manifest.json         # declarative manifest (artifacts → rsdkv4/rsdkv4.*)
+│   └── engine-specs.js   # the contract's runtime, imported relatively by the SDK
 ├── index.html            # demo shell (import map → ./rsdkv4/rsdkv4.sdk.js)
 ├── demo.js               # window.SDK + window.rsdkv4Library
 ├── library.js            # the two-game OPFS library (src/demo/library.ts)
@@ -310,8 +253,8 @@ OPFS root
     └── Sonic2/…
 ```
 
-Because [`/data` is the OPFS root](#data-is-the-opfs-root), that folder *is* the
-engine's working dir: launching loads with `storageNamespace: 'rsdkv4/Sonic1'` and
+Because [every file lives in the engine's own folder](#every-file-lives-in-the-engines-own-folder),
+that folder *is* the engine's working dir: launching starts with `storage({ namespace: 'Sonic1' })` and
 no assets, so nothing is copied or re-read. **Replace** swaps the pack; **Remove**
 deletes only `Data.rsdk`, leaving settings and saves for when it comes back.
 
@@ -370,31 +313,34 @@ What this project is, and the constraints that shape it.
 
 - **A contract implementation, not a game.** The deliverable is one game-agnostic
   `rsdkv4.wasm` plus an SDK conforming to
-  [@wasm-gaming/engine-specs](https://github.com/wasm-gaming/engine-specs) — `manifest`
-  (Layer A) and `load()` (Layer B). A host drives this engine exactly as it drives the
-  other eleven.
+  [@wasm-gaming/engine-specs](https://github.com/wasm-gaming/engine-specs) 1.0 —
+  `Rsdkv4SDK extends EngineSDKBase`. A host drives this engine exactly as it drives the
+  others.
+- **Works on its own.** Clone, `npm ci`, `make build-sdk test`: no other wasm-gaming
+  repo needed. engine-specs is the one dependency, and its runtime ships inside
+  `dist/rsdkv4/`, so the package needs no bundler or import map.
 - **Ships none of the game.** The player provides `Data.rsdk`; it never leaves the
   browser and is never committed. Which pack the host hands over is what selects Sonic 1
   or Sonic 2.
 - **The engine's own values are the SDK's only private vocabulary.** They live in
-  [src/rsdkv4.options.ts](src/rsdkv4.options.ts) — seven keys, mirrored as JSON Schema in
-  `manifest.options` — and in the extra fields of `Rsdkv4LoadConfig`. Everything else is
+  [src/rsdkv4.options.ts](src/rsdkv4.options.ts) — `RSDKV4_SPEC`, the four payloads as
+  data. Everything else is
   contract, documented once at the [contract
   reference](https://wasm-gaming.github.io/engine-specs/api-docs/).
-- **The host owns the files; the SDK owns its folder.** The SDK reads the pack and never
-  writes it. What it does write — save data, `settings.ini` — lives under the host-chosen
-  `storageNamespace`.
+- **The host owns the files; the SDK owns its folder.** Everything lives in
+  `rsdkv4/<namespace>/` (WASMFS and OPFS alike): the engine adds `rsdkv4/`, the host only
+  picks `<namespace>`. The SDK reads the pack and never writes it; what it does write —
+  save data, `settings.ini` — lands in the same folder.
 - **Persistence needs cross-origin isolation.** OPFS sync access exists only in workers,
   so the working dir falls back to in-memory WASMFS when the page isn't isolated (or when
   the build can't create the backend from the main thread — see the filesystem caveat).
 - **Everything builds from the Makefile**, `package.json` has no scripts. `dist/` is both
   the npm artifact and the Pages site: demo at the root, `/craft`, `/vanilla`, and the API
   reference at `/api-docs`.
-- **Sessions are the record.** Specs and decisions live in [SESSIONS/](SESSIONS/), append-only.
-- **Where it is going:** contract 1.0 replaces `{ manifest, load }` with `EngineSDK` /
-  `EnginePlay` classes. The six `docs/{SDK,PLAY}-*.md` documents describe that API for this
-  engine, and the migration plan is
-  [SESSIONS/2026-08-14_12h35.sdk-migration-to-contract-1.0.session.md](SESSIONS/2026-08-14_12h35.sdk-migration-to-contract-1.0.session.md).
+- **RECORD/ is the record.** Specs and decisions live in [RECORD/](RECORD/): `.WIP.md` append-only, `.completed.md` read-only.
+- **The reference engine.** The other wasm-gaming engines migrate to this layout, and the
+  [play.germade](https://github.com/jgermade/play.germade) launcher consumes it first — see
+  [RECORD/2026-11-12.standalone-package-and-wasmfs-engine-namespace.WIP.md](RECORD/2026-11-12.standalone-package-and-wasmfs-engine-namespace.WIP.md).
 
 ## Todos
 

package/dist/rsdkv4/app/app.css

@@ -0,0 +1,160 @@
+/* rsdkv4 app — the load-game screen (craft's slot cards) and the pause menu.
+   Tokens come from engine-specs (UI_TOKENS, `--wg-*`) when the host sets them; the
+   fallbacks are the same values, so the app looks right on a bare page too. */
+
+.rsdk-app {
+  --ring: var(--wg-focus-ring, 0 0 0 3px #fff);
+  --surface: var(--wg-surface, rgb(18 20 28 / 0.78));
+  --line: var(--wg-line, rgb(255 255 255 / 0.12));
+  --text: var(--wg-text, #f4f6fb);
+  --muted: var(--wg-muted, #8e97a9);
+  --danger: var(--wg-danger, #f87171);
+  --ui: var(--wg-font-ui, 'Inter Variable', 'Inter', system-ui, sans-serif);
+  --display: var(--wg-font-display, 'Unbounded Variable', 'Unbounded', system-ui, sans-serif);
+  --ease: var(--wg-ease, cubic-bezier(0.2, 0.8, 0.2, 1));
+  position: absolute;
+  inset: 0;
+  overflow: hidden;
+  background: #000;
+  color: var(--text);
+  font-family: var(--ui);
+  user-select: none;
+  -webkit-tap-highlight-color: transparent;
+}
+.rsdk-app * { box-sizing: border-box; }
+.rsdk-stage { position: absolute; inset: 0; display: grid; place-items: center; }
+.rsdk-stage canvas { outline: none; }
+.rsdk-overlay { position: absolute; inset: 0; display: grid; place-items: center; pointer-events: none; }
+.rsdk-overlay > * { pointer-events: auto; }
+.rsdk-app[data-screen='game'] .rsdk-overlay { display: none; }
+
+/* Everything but the game sits on a backdrop that keeps the game visible underneath. */
+.rsdk-app:not([data-screen='game']) .rsdk-overlay {
+  background:
+    radial-gradient(120% 80% at 50% 0%, color-mix(in srgb, var(--accent) 38%, transparent), transparent 70%),
+    rgb(4 6 12 / 0.72);
+  backdrop-filter: blur(14px) saturate(1.2);
+  -webkit-backdrop-filter: blur(14px) saturate(1.2);
+}
+.rsdk-app[data-screen='boot'] .rsdk-overlay,
+.rsdk-app[data-screen='slots'] .rsdk-overlay { background-color: rgb(4 6 12 / 0.9); }
+
+.kicker { margin: 0; font: 600 0.72rem var(--ui); letter-spacing: 0.22em; text-transform: uppercase; color: var(--muted); }
+.rsdk-app h2 { margin: 0; font: 700 clamp(1.4rem, 3vw, 2.1rem) var(--display); letter-spacing: -0.02em; }
+
+/* ---- boot ---- */
+.rsdk-boot { display: grid; justify-items: center; gap: 22px; }
+.rsdk-boot img { width: min(260px, 50vw); border-radius: 22px; box-shadow: 0 30px 80px -30px #000; animation: rsdk-breathe 2.4s var(--ease) infinite alternate; }
+.rsdk-boot p { margin: 0; color: var(--muted); font-weight: 500; }
+@keyframes rsdk-breathe { from { opacity: 0.55; transform: scale(0.98); } to { opacity: 1; transform: none; } }
+
+/* ---- load game: craft's slot cards (src/craft/views/GameLauncher.html) ---- */
+.rsdk-slots { width: min(1120px, 100%); padding: 0 clamp(16px, 4vw, 48px); display: grid; gap: clamp(22px, 4vh, 40px); }
+.rsdk-slots header { display: grid; gap: 6px; }
+.slot-cards {
+  --w: clamp(150px, 13vw, 190px);
+  display: flex; justify-content: center; align-items: flex-start; gap: clamp(12px, 1.6vw, 24px);
+}
+.slot-card {
+  flex: none; width: var(--w); height: calc(var(--w) * 220 / 170);
+  display: flex; flex-direction: column; justify-content: space-between; gap: 0.4rem;
+  padding: 0.75rem; border-radius: 0.5rem; border: 2px solid #000; background: #333; color: #fff;
+  font-family: system-ui, sans-serif;
+  transition: transform 0.2s var(--ease), box-shadow 0.2s var(--ease);
+}
+.slot-card.is-focused { box-shadow: var(--ring), 0 24px 50px -20px #000; transform: translateY(-4px); }
+.slot-card.is-nosave {
+  height: calc(var(--w) * 130 / 170); justify-content: center; align-items: center;
+  font-weight: 700; cursor: pointer;
+}
+.slot-card.is-nosave:hover:not(:active) { background: #222; }
+.slot-card img { display: block; }
+
+.slot-play {
+  all: unset; box-sizing: border-box; flex-shrink: 0; width: 100%; height: 34px; text-align: center;
+  border-radius: 4px; background: royalblue; color: #fff; font-weight: 700; text-shadow: 0 0 2px #000; cursor: pointer;
+}
+.slot-play:hover:not(:active), .slot-card.is-focused .slot-play { background: blue; }
+
+/* the character picker: white square, the character over two drifting colour bands */
+.player-choose {
+  all: unset; box-sizing: border-box; position: relative; width: 100%; aspect-ratio: 1; padding: 1rem 0.5rem 0;
+  display: flex; align-items: center; justify-content: center; overflow: hidden;
+  background: #fff; cursor: pointer; transition: padding 0.05s linear;
+}
+.player-choose::before, .player-choose::after { content: ''; position: absolute; inset: 0 1rem 0 3rem; background: rgb(180 180 180 / 0.2); }
+.player-choose[data-player='sonic']::after { background: rgb(13 122 233 / 0.2); left: 30%; right: 20%; }
+.player-choose[data-player='tails']::after { background: rgb(241 176 0 / 0.2); left: 40%; right: 10%; animation-delay: -5s; }
+.player-choose[data-player='knuckles']::after { background: rgb(255 20 0 / 0.2); left: 20%; right: 30%; animation-delay: -10s; }
+.player-choose[data-player='sonictails']::after { background: rgb(160 32 240 / 0.2); left: 20%; right: 70%; animation-delay: -15s; }
+.slot-card:hover .player-choose, .slot-card.is-focused .player-choose { padding: 0; }
+.player-choose:hover::before, .slot-card.is-focused .player-choose::before { animation: rsdk-player-bg 20s linear infinite; }
+.player-choose:hover::after, .slot-card.is-focused .player-choose::after { animation: rsdk-player-bg 30s linear reverse infinite; }
+.player-choose img { position: relative; z-index: 1; max-width: 100%; max-height: 100%; }
+@keyframes rsdk-player-bg {
+  0% { left: 30%; right: 20%; } 10% { left: 50%; right: 50%; } 20% { left: 10%; right: 20%; }
+  30% { left: 60%; right: 40%; } 40% { left: 70%; right: 10%; } 50% { left: 20%; right: 80%; }
+  60% { left: 0; right: 60%; } 70% { left: 40%; right: 10%; } 80% { left: 10%; right: 70%; }
+  90% { left: 80%; right: 0; } 100% { left: 30%; right: 20%; }
+}
+
+/* a saved slot */
+.slot-card.is-saved { gap: 0.25rem; }
+.stage-shot { position: relative; width: 100%; flex-shrink: 0; }
+.stage-badge {
+  width: 100%; aspect-ratio: 16 / 9; border-radius: 4px; overflow: hidden;
+  border: 1px solid rgb(255 255 255 / 0.2); background: linear-gradient(160deg, #1b2a4a, #080d1c);
+}
+.stage-badge img { width: 100%; height: 100%; object-fit: cover; filter: brightness(0.9); image-rendering: pixelated; }
+.zone-tag {
+  position: absolute; top: 4px; left: 4px; padding: 1px 4px; border-radius: 3px; background: rgb(0 0 0 / 0.72);
+  color: #fbbf24; font-size: 0.5rem; font-weight: 800; letter-spacing: 0.06em; line-height: 1.4;
+}
+.player-icon { position: absolute; right: 0; bottom: -1rem; pointer-events: none; }
+.player-icon img { height: calc(var(--w) * 64 / 170); width: auto; filter: drop-shadow(0 2px 4px rgb(0 0 0 / 0.85)); }
+.zone-title {
+  height: 2.3em; padding-right: 26%; font-weight: 800; font-size: 0.72rem; color: #fbbf24; text-transform: uppercase;
+  letter-spacing: 0.4px; text-shadow: 0 1px 3px rgb(0 0 0 / 0.9); line-height: 1.15;
+}
+.emeralds { display: flex; justify-content: center; gap: 3px; flex-shrink: 0; }
+.emeralds i { width: 11px; height: 11px; background: var(--gem); clip-path: polygon(50% 0, 100% 38%, 50% 100%, 0 38%); opacity: 0.2; }
+.emeralds i.on { opacity: 1; filter: drop-shadow(0 0 3px rgb(255 255 255 / 0.4)); }
+.stats-grid { display: flex; flex-wrap: wrap; justify-content: center; gap: 0.2rem 0.4rem; font-size: 0.68rem; color: #e2e8f0; }
+.stats-grid span {
+  display: inline-flex; align-items: center; gap: 0.25rem; padding: 0.1rem 0.3rem; border-radius: 3px;
+  background: rgb(0 0 0 / 0.4); border: 1px solid rgb(255 255 255 / 0.1); font-variant-numeric: tabular-nums;
+}
+.stats-grid svg { width: 10px; height: 10px; }
+
+/* ---- pause & confirm ---- */
+.rsdk-panel {
+  width: min(440px, 92vw); display: grid; gap: 10px; padding: 26px; border-radius: 28px;
+  background: rgb(20 22 31 / 0.9); border: 1px solid var(--line); box-shadow: 0 40px 100px -30px #000;
+}
+.rsdk-panel h2 { margin-bottom: 8px; }
+.rsdk-panel .text { margin: 0 0 8px; color: var(--muted); line-height: 1.5; }
+.item {
+  all: unset; box-sizing: border-box; display: grid; gap: 2px; padding: 13px 16px; border-radius: 14px;
+  background: rgb(255 255 255 / 0.05); font-weight: 600; cursor: pointer; transition: background 0.15s, box-shadow 0.15s;
+}
+.item small { font-weight: 500; font-size: 0.78rem; color: var(--muted); }
+.item.is-focused { background: #fff; color: #0b0d12; box-shadow: var(--ring); }
+.item.is-focused small { color: #4b5563; }
+.item.is-danger.is-focused { background: var(--danger); color: #1a0505; box-shadow: 0 0 0 3px var(--danger); }
+.rsdk-panel .row { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; }
+.rsdk-panel .row .item { text-align: center; }
+.rsdk-confirm { position: absolute; inset: 0; display: grid; place-items: center; background: rgb(0 0 0 / 0.55); }
+
+/* ---- hints ---- */
+.rsdk-hints { display: flex; flex-wrap: wrap; gap: 8px 18px; justify-content: center; color: var(--muted); font-size: 0.78rem; font-weight: 500; }
+.rsdk-hints span { display: inline-flex; align-items: center; gap: 7px; }
+.rsdk-hints kbd { display: inline-grid; place-items: center; min-width: 22px; height: 22px; padding: 0 6px; border-radius: 11px; background: rgb(255 255 255 / 0.12); color: var(--text); font: 700 0.68rem var(--ui); }
+.rsdk-panel .rsdk-hints { justify-content: flex-start; margin-top: 6px; }
+
+@media (max-width: 960px) {
+  .slot-cards { justify-content: flex-start; overflow-x: auto; padding: 16px 6px 18px; margin: 0 -6px; scrollbar-width: none; scroll-snap-type: x mandatory; }
+  .slot-card { scroll-snap-align: center; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .slot-card, .player-choose, .player-choose::before, .player-choose::after, .rsdk-boot img { transition: none; animation: none; }
+}