@wasm-gaming/engine-specs 0.3.1 → 0.4.0

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,104 @@ 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.
+
+## Menus: one usability scheme
+
+Engines also ship their own screens (start / load game, pause, options) as an **engine app**, and
+all of them — and the launcher — follow one scheme, described in [UX.md](UX.md). The package carries
+its runtime, so no engine needs another dependency:
+
+```js
+import { createInput, nextFocus, uiTokensCss } from '@wasm-gaming/engine-specs';
+
+const input = createInput();                 // keyboard + gamepads → actions, with repeat
+input.on((action) => {                       // 'up' | 'down' | … | 'accept' | 'back' | 'menu' | 'more'
+  if (action === 'down') focus(nextFocus(current, buttons, 'down'));
+});
+input.suspend();                             // the game has the controls now
+```
+
+An app implements `EngineApp` — `mount(target, host)` — and receives `game`, `storage`, `assets`,
+the shared `input` and `exit()` from the host.
+
 ## Closing the types
 
 One type parameter carries all four payloads, so there is no order to get wrong:
@@ -85,10 +184,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

@@ -4,7 +4,9 @@
   It drives the engine only through the contract, and every panel is painted from
   something the contract handed back:
 
-  - the header is the class's static identity, read before any engine exists;
+  - the toolbar is the reference's own, so the two pages are one site;
+  - the footer under it all is the class's static identity, read before any engine
+    exists — and the document title is the same reading;
   - the pickers get their file filter from each asset descriptor's `allowedTypes`;
   - the tables are `config()`, `options()`, `assets()` and `storage()` rendered as
     they arrive — one component, and not one key name written on this side.
@@ -13,22 +15,16 @@
   there is no mount bookkeeping here.
 -->
 
-<EngineHeader :name="name" :id="id" :version="version" :description="description" />
+<SiteToolbar :version="packageVersion" />
 
 <div class="layout">
   <aside>
-    <section>
+    <section class="panel">
       <h2>assets</h2>
       <AssetPicker :assets="assets" @select="onSelect" @remove="onRemove" />
     </section>
 
-    <section>
-      <h2>lifecycle</h2>
-      <LifecycleBar :running="running" @start="onStart" @restart="onRestart"
-        @pause="onPause" @resume="onResume" @destroy="onDestroy" />
-    </section>
-
-    <section>
+    <section class="panel">
       <h2>calls</h2>
       <CallLog :entries="calls" />
     </section>
@@ -37,11 +33,22 @@
   <div>
     <!-- The engine is handed this element and appends its own canvas to it. -->
     <div id="stage"></div>
+
+    <!-- Under the picture and as wide as it: the verbs act on what is above them. -->
+    <section class="panel">
+      <h2>lifecycle</h2>
+      <LifecycleBar :running="running" @start="onStart" @restart="onRestart"
+        @pause="onPause" @resume="onResume" @destroy="onDestroy" />
+    </section>
+
     <PropertyTable :tables="tables" />
   </div>
 </div>
 
+<EngineHeader :version="version" :description="description" />
+
 <script :setup="{}">
+  const SiteToolbar = await import('./components/site-toolbar.html');
   const EngineHeader = await import('./components/engine-header.html');
   const AssetPicker = await import('./components/asset-picker.html');
   const PropertyTable = await import('./components/property-table.html');
@@ -50,9 +57,19 @@
 
   const { DemoEngineSDK } = await import('./demo.sdk.js');
 
+  // The *package* version, for the toolbar — not the engine's. `make site` writes this
+  // file next to the demo from package.json, which is the same source TypeDoc reads, so
+  // the two bars cannot disagree. A bare `demo/` checkout has no such file, and the bar
+  // then shows the package name alone.
+  let packageVersion = '';
+  try {
+    ({ version: packageVersion } = await import('./package-version.js'));
+  } catch {
+    packageVersion = '';
+  }
+
   // Identity, off the class — no engine constructed to read it.
   const name = DemoEngineSDK.name;
-  const id = DemoEngineSDK.id;
   const version = DemoEngineSDK.version;
   const description = DemoEngineSDK.description;
   document.title = `${name} — engine-specs demo`;
@@ -71,6 +88,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 +130,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 +159,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 +177,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 +190,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();
   };
@@ -193,7 +232,8 @@
     }
   }
 
-  aside section {
+  /* A class, not `aside section`: the lifecycle panel lives in the other column now. */
+  .panel {
     background: var(--panel, #fff);
     border: 1px solid var(--border, #e2e8f0);
     border-radius: 4px;
@@ -201,7 +241,7 @@
     margin-bottom: 1rem;
   }
 
-  aside h2 {
+  .panel h2 {
     margin: 0 0 0.75rem;
     font-size: 0.78rem;
     font-family: var(--mono, monospace);

package/demo/components/asset-picker.html

@@ -13,9 +13,11 @@
       @dragleave="dragging = null"
       @drop.prevent="onDrop($event, asset)"
       :class.active="dragging === asset.key">
-    <strong>{{ asset.key }}</strong>
-    <p class="hint">{{ asset.description }}</p>
-    <p :class.file-selected="asset.fileName">{{ asset.fileName || asset.accepts }}</p>
+    <div class="meta">
+      <strong>{{ asset.key }}</strong>
+      <p class="hint">{{ asset.description }}</p>
+      <p :class.file-selected="asset.fileName">{{ asset.fileName || asset.accepts }}</p>
+    </div>
     <div class="picker-actions">
       <label class="picker">
         {{ asset.fileName ? 'Change' : 'Pick file' }}
@@ -24,6 +26,7 @@
       <button type="button" :if="asset.fileName" class="remove-btn" @click.stop="$emit('remove', asset)">Remove</button>
     </div>
   </section>
+
 </div>
 
 <script :setup="{
@@ -58,14 +61,26 @@
     gap: 0.6rem;
   }
 
+  /*
+    A row, not a card: the key and its hints on the left, the actions on the right. The
+    whole box is still the drop target — it is only shorter, so two assets and the call
+    log fit the column without scrolling.
+  */
   .drop {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto;
+    align-items: center;
+    gap: 0.6rem;
     border: 1px dashed var(--border, #e2e8f0);
     border-radius: 4px;
-    padding: 1rem;
-    text-align: center;
+    padding: 0.6rem 0.75rem;
     transition: border-color 200ms ease, background 200ms ease;
   }
 
+  .meta {
+    min-width: 0;
+  }
+
   .drop.active {
     border-color: var(--accent, #ff007f);
     background: rgb(255 0 127 / 0.06);
@@ -85,14 +100,16 @@
   }
 
   .drop p {
-    margin: 0.35rem 0 0;
+    margin: 0.15rem 0 0;
     color: var(--muted, #64748b);
-    font-size: 0.78rem;
-    word-break: break-all;
+    font-size: 0.75rem;
+    line-height: 1.35;
+    /* `anywhere`, not `break-all`: a long file name still breaks, prose does not. */
+    overflow-wrap: anywhere;
   }
 
   .drop p.hint {
-    font-size: 0.8rem;
+    font-size: 0.78rem;
   }
 
   .drop p.file-selected {
@@ -102,18 +119,20 @@
   }
 
   .picker-actions {
-    display: inline-flex;
-    align-items: center;
-    gap: 0.4rem;
-    margin-top: 0.75rem;
+    display: flex;
+    flex-direction: column;
+    align-items: stretch;
+    gap: 0.3rem;
   }
 
   .picker,
   .remove-btn {
     display: inline-flex;
+    justify-content: center;
+    white-space: nowrap;
     font-family: var(--mono, monospace);
     font-size: 0.75rem;
-    padding: 0.35rem 0.7rem;
+    padding: 0.3rem 0.6rem;
     border: 1px solid var(--border, #e2e8f0);
     border-radius: 3px;
     background: transparent;

package/demo/components/engine-header.html

@@ -4,58 +4,51 @@
   This is what replaced the manifest: `id`, `version`, `name` and `description` are
   static members of the SDK constructor, so a launcher can list engines without
   booting one.
+
+  It sits at the foot of the page and says nothing about the site: the toolbar above
+  carries that, which is why neither the link back to the reference nor a page-titling
+  `h1` is here any more. The name still reaches the reader — as the document title,
+  written from the same static member.
 -->
-<header>
+<footer class="engine-header">
   <div>
-    <h1>{{ name }} <code>{{ id }}</code></h1>
     <p>{{ description }}</p>
   </div>
   <div class="right">
     <span class="pill">v{{ version }}</span>
-    <a class="pill link" :href="referenceHref">API reference</a>
   </div>
-</header>
+</footer>
 
 <script :setup="{
-  name,
-  id,
   version,
   description = '',
-  referenceHref = '../',
 }">
 </script>
 
 <style>
-  header {
+  /*
+    Scoped to a class, not to the element. A component's styles land in the page's own
+    <style>, unscoped — so a bare `header {}` here reached the site toolbar above and
+    made a flex container of it, which centred the whole bar. Class selectors keep a
+    component's look to the component.
+  */
+  .engine-header {
     display: flex;
     flex-wrap: wrap;
     gap: 1rem;
     align-items: center;
     justify-content: space-between;
     padding: 1.25rem 1.5rem;
-    border-bottom: 1px solid var(--border, #e2e8f0);
+    border-top: 1px solid var(--border, #e2e8f0);
     background: var(--panel, #fff);
   }
 
-  h1 {
+  .engine-header p {
     margin: 0;
-    font-size: 1.25rem;
-    letter-spacing: 0.02em;
-    color: var(--text, #0f172a);
-  }
-
-  code {
-    font-family: var(--mono, monospace);
-    font-size: 0.75em;
     color: var(--muted, #64748b);
   }
 
-  p {
-    margin: 0.25rem 0 0;
-    color: var(--muted, #64748b);
-  }
-
-  .right {
+  .engine-header .right {
     display: flex;
     gap: 0.5rem;
   }
@@ -71,8 +64,4 @@
     text-transform: uppercase;
     white-space: nowrap;
   }
-
-  .link {
-    text-decoration: none;
-  }
 </style>

package/demo/components/site-toolbar.html

@@ -0,0 +1,31 @@
+<!--
+  The reference's own toolbar, reused rather than imitated: the class names are
+  TypeDoc's and so is the stylesheet that paints them, which index.html loads from
+  `../assets/style.css`. Two pages, one bar, and nothing here to keep in sync by hand.
+
+  What is missing is `button#tsd-search-trigger`. This page carries no search index and
+  does not load TypeDoc's `main.js`, so the button would open nothing — and a control
+  that does nothing is worse than a control that isn't there.
+
+  The version is *given* to this component, never written into it: TypeDoc reads it from
+  package.json, and a copy hard-coded here would drift the first time it changed. With
+  nothing to show — a bare `demo/` checkout — the bar shows the name alone rather than a
+  wrong number.
+-->
+<header class="tsd-page-toolbar">
+  <div class="tsd-toolbar-contents container">
+    <a class="title" :href="referenceHref">{{ title }}<span :if="version"> - v{{ version }}</span></a>
+    <div id="tsd-toolbar-links">
+      <a :href="referenceHref">Reference</a>
+      <a :href="repositoryHref">GitHub</a>
+    </div>
+  </div>
+</header>
+
+<script :setup="{
+  title = '@wasm-gaming/engine-specs',
+  version = '',
+  referenceHref = '../',
+  repositoryHref = 'https://github.com/wasm-gaming/engine-specs',
+}">
+</script>

package/demo/demo.css

@@ -7,22 +7,32 @@
 */
 
 :root {
-  --bg: #f8fafc;
-  --panel: #ffffff;
-  --border: #e2e8f0;
-  --text: #0f172a;
-  --muted: #64748b;
+  /*
+    The reference's palette, read off the variables TypeDoc defines, so the theme
+    switch in the docs sidebar drives this page too — there is no second switch here
+    to disagree with it, and no `prefers-color-scheme` block either: TypeDoc's `os`
+    theme already means "follow the system".
+
+    `--accent` stays the demo's own. It marks what the page does, not what the site
+    is, and the reference has no equivalent to borrow.
+  */
+  --bg: var(--color-background);
+  --panel: var(--color-background-secondary);
+  --border: var(--color-accent);
+  --text: var(--color-text);
+  --muted: var(--color-text-aside);
   --accent: #ff007f;
   --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
 }
 
-@media (prefers-color-scheme: dark) {
-  :root {
-    --bg: #060910;
-    --panel: #0f172a;
-    --border: #1e293b;
-    --text: #e2e8f0;
-    --muted: #94a3b8;
+/*
+  TypeDoc hides the toolbar links below 769px because its menu trigger takes over
+  there. This page has no menu, so hiding them would leave no way back to the
+  reference. Unlayered, so it wins.
+*/
+@media (max-width: 769px) {
+  #tsd-toolbar-links {
+    display: flex;
   }
 }