@wasm-gaming/engine-specs 0.3.1 → 0.3.2

package/README.md

@@ -4,8 +4,9 @@ The **engine contract** for the wasm-gaming ecosystem: one shared JS API that ev
 WASM game/emulator engine implements and every host drives. Define it once here,
 depend on it everywhere, and engines can't drift.
 
-TypeScript types and nothing else — [src/engine-specs.ts](src/engine-specs.ts) is the
-whole package. No runtime dependencies, because twelve engines depend on this.
+The types, plus the contract implemented once so twelve engines inherit it instead of
+re-deriving it — [src/engine-specs.ts](src/engine-specs.ts) is the whole package. No
+runtime dependencies, because twelve engines depend on this.
 
 ## The shape
 
@@ -55,6 +56,85 @@ without asking the engine anything, and without the host knowing a single key na
 `restart()`. The descriptor shape is never accepted on write: that asymmetry is what
 keeps a write unambiguous the day a value is itself an object.
 
+## Listening
+
+`on` and `off` are on the same fluent surface, so they chain wherever the setters do —
+and **registration is synchronous on every carrier**, including the promise `start()`
+returns. The chain is what the return value continues, never what the subscription
+waits for; otherwise `start().on('error', …)` would bind after the session opened and
+miss an error thrown while it was opening.
+
+A listener receives an **event**, not the payload: what it carries is `detail`, as
+`CustomEvent` does it. The envelope is what lets an event grow a field without every
+listener signature changing — and what survives `postMessage` intact when the engine
+lives in a worker, which is where this ecosystem is going.
+
+```js
+const play = await new Rsdkv4SDK({ on: { error: report } })   // in the constructor
+  .on('start', (event) => console.log('session', event.detail))
+  .assets({ pack })
+  .start();
+```
+
+It is deliberately **not** a DOM event: two members, frozen, no bubbling, no
+`preventDefault()`, no `target`. Half-implementing a familiar interface is worse than
+offering a different one.
+
+The factory and the engine it opens are **one channel**, so subscribing before there is
+an engine is the normal way to do it. Every engine emits `start`, `error`, `exit`,
+`pause` and `resume`; an engine that has more of its own declares them in its payload
+bundle and they type-check alongside the core set:
+
+```ts
+interface Rsdkv4Payloads extends EnginePayloads {
+  // …the four payloads
+  events: { levelLoaded: { zone: string } };   // optional; omit it for the core set alone
+}
+```
+
+`error` is emitted **and** the promise rejects — both, always — so a host that does not
+`await` is not left blind, and one that does is not forced to subscribe.
+
+## Writing an engine
+
+None of the above has to be implemented by hand. `EnginePlayBase` and `EngineSDKBase`
+carry the state, the descriptors, the cumulative merge, the chainable promise and the
+channel; an engine declares its properties as data and fills in what only it knows.
+
+```js
+import { EnginePlayBase, EngineSDKBase } from '@wasm-gaming/engine-specs';
+
+const spec = {
+  config: { region: { default: 'us', enum: ['us', 'eu', 'jp'], live: false } },
+  options: { slot: { default: 0, live: true } },
+  assets: { pack: { allowedTypes: ['.bin'], live: false } },
+  storage: { namespace: { default: 'rsdkv4', live: false } },
+};
+
+class Rsdkv4Play extends EnginePlayBase {
+  constructor(init, events) { super(spec, init, events); }
+  async open(options) { /* start or reopen a session */ }
+  async close() { /* stop and release */ }
+  mounted(target) { /* the picture goes here */ }
+}
+
+export class Rsdkv4SDK extends EngineSDKBase {
+  static id = 'rsdkv4';
+  static version = '1.0.0';
+  createPlay(init, events) { return new Rsdkv4Play(init, events); }
+}
+```
+
+`default` is declared in the spec and **nowhere else** — the base seeds its starting
+state from it, so the initial value and the advertised default cannot drift apart.
+`start`, `exit` and `error` are emitted for you, including the rule that a failing hook
+both rejects the chain and emits `error`; `this.emit(…)` is for the engine's own
+events.
+
+Adoption is optional: the contract is structural, so an engine with its own emitter and
+its own state satisfies `EngineSDK` without extending anything. `EventEmitter` and
+`hydratePlay` are exported for engines that want the pieces rather than the whole.
+
 ## Closing the types
 
 One type parameter carries all four payloads, so there is no order to get wrong:
@@ -85,10 +165,15 @@ make preview          # serve site/ on :8020 (PORT= to change it)
 Two engines implement the contract in this repo, and both are type-checked in CI:
 [tests/engine.conformance.ts](tests/engine.conformance.ts), the reference engine, and
 [demo/demo.sdk.js](demo/demo.sdk.js), which drives the [demo
-page](https://wasm-gaming.github.io/engine-specs/demo/). The negative cases live in
+page](https://wasm-gaming.github.io/engine-specs/demo/). Between them they cover both
+branches of the event map — the reference engine declares one of its own, the demo
+omits `events` and gets the core set alone. The negative cases live in
 [tests/types.test-d.ts](tests/types.test-d.ts), guarded by `@ts-expect-error` — which
 fails if a rejection ever stops happening.
 
+The emitter is the one part with behaviour to run rather than compile, so it has
+tests that run: [tests/event-emitter.test.mjs](tests/event-emitter.test.mjs).
+
 ## License
 
 MIT.

package/demo/app.html

@@ -71,6 +71,27 @@
     calls = [line, ...calls].slice(0, 40);
   };
 
+  /**
+   * The only place the factory is built, so the page subscribes exactly once — and
+   * does it in the constructor, which is the same call as `.on(type, listener)`.
+   *
+   * The handlers outlive every engine this factory opens: `start` fires again on each
+   * `restart()`, `exit` on `destroy()`, and `pause`/`resume` come from methods the
+   * contract does not know about. Nothing below re-subscribes.
+   *
+   * Each one receives an event, not the payload: what it carries is `detail`.
+   */
+  const engine = () =>
+    (sdk ??= new DemoEngineSDK({
+      on: {
+        start: ({ detail }) => say(`▸ start   fileName: ${detail.fileName ?? 'unset'}`),
+        pause: ({ detail }) => say(`▸ pause   owner: ${detail.owner}`),
+        resume: ({ detail }) => say(`▸ resume  owner: ${detail.owner}`),
+        error: ({ detail }) => say(`▸ error   ${detail.message}`),
+        exit: ({ type }) => say(`▸ ${type}`),
+      },
+    }));
+
   const show = (value) => {
     if (value === undefined) return 'unset';
     if (value instanceof Uint8Array) return `${value.byteLength} bytes`;
@@ -92,7 +113,7 @@
 
   /** Reads the live engine — or the factory, when there is not one yet. */
   const refresh = async () => {
-    const source = play ?? (sdk ??= new DemoEngineSDK());
+    const source = play ?? engine();
     const [config, options, assetProps, storage] = await Promise.all([
       source.config(),
       source.options(),
@@ -121,7 +142,7 @@
   const onSelect = async ({ key, file }) => {
     const bytes = new Uint8Array(await file.arrayBuffer());
     picked[key] = file.name;
-    sdk ??= new DemoEngineSDK();
+    engine();
     say(`sdk.assets({ ${key}: Uint8Array(${bytes.byteLength}) })`);
     sdk.assets({ [key]: bytes });
     if (key === 'rom') {
@@ -139,7 +160,7 @@
   };
 
   const onStart = async () => {
-    sdk ??= new DemoEngineSDK();
+    engine();
     say('play = await sdk.mount(stage).start()');
     // The whole chain in one expression, exactly as the contract advertises it.
     play = await sdk.mount(document.querySelector('#stage')).start();
@@ -152,15 +173,16 @@
     await refresh();
   };
 
-  // `pause` and `resume` are this engine's own members, not the contract's.
+  // The methods are this engine's own; the `pause`/`resume` they emit are the
+  // contract's — which is why the log shows a ▸ line the page never wrote here.
   const onPause = async () => {
-    say('play.pause()   // engine-specific, not in the contract');
+    say('play.pause()   // engine-specific method, contract event');
     play.pause();
     await refresh();
   };
 
   const onResume = async () => {
-    say('play.resume()  // engine-specific, not in the contract');
+    say('play.resume()  // engine-specific method, contract event');
     play.resume();
     await refresh();
   };