@wasm-gaming/engine-specs 0.2.7 → 0.3.0

package/README.md

@@ -1,84 +1,93 @@
 # @wasm-gaming/engine-specs
 
-The **engine contract** for the wasm-gaming ecosystem: the single shared interface
-that every WASM game/emulator engine and the host app conform to. Define it once
-here, depend on it everywhere, and engines can't drift.
+The **engine contract** for the wasm-gaming ecosystem: one shared JS API that every
+WASM game/emulator engine implements and every host drives. Define it once here,
+depend on it everywhere, and engines can't drift.
 
-TypeScript is the source of truth ([src/](src/)); a JSON Schema
-([schema/engine-manifest.schema.json](schema/engine-manifest.schema.json)) mirrors
-the manifest for non-TS consumers; a Zod-based validator lets any CI fail on
-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.
 
-## Documentation
+## The shape
 
-**[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).
+An engine exports a class. Its **identity is static**, so a launcher can list engines
+without constructing one:
 
-The [demo](https://wasm-gaming.github.io/engine-specs/) runs a dummy engine through the
-same contract.
+```ts
+import type { EngineSDKConstructor, EnginePayloads } from '@wasm-gaming/engine-specs';
 
-## Two layers
+interface Rsdkv4Payloads extends EnginePayloads {
+  config: { region: 'us' | 'eu' | 'jp' };
+  options: { player: 'sonic' | 'tails'; slot: number };
+  assets: { pack: Uint8Array };
+  storage: { namespace: string };
+}
 
-**Layer A — declarative ([src/manifest.ts](src/manifest.ts))**
-`EngineManifest` is what an engine declares about itself before anything boots.
-Everything that differs between engines lives here as data.
+// The one line that belongs in an engine's CI: does the class satisfy the contract?
+const _contract: EngineSDKConstructor<Rsdkv4Payloads> = Rsdkv4SDK;
+```
 
-**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` the host drives —
-identically for every engine.
+A host configures by chaining, and gets the live engine back:
 
-## Usage
+```js
+const play = await new Rsdkv4SDK({ config: { region: 'eu' } })
+  .assets({ pack })
+  .mount(document.querySelector('#stage'))
+  .start({ player: 'tails', slot: 0 });
 
-An engine implements the contract:
+await play.restart({ slot: 3 });
+await play.destroy();
+```
 
-```ts
-import type { EngineSDK, EngineManifest } from '@wasm-gaming/engine-specs';
+## Read and write are different shapes
 
-export const manifest: EngineManifest = { /* ... */ };
-export async function load(config) { /* ... */ }
+`config`, `options`, `assets` and `storage` are each one method with two overloads.
+Called with a patch it writes and keeps the chain; called with nothing it reads:
 
-// Compile-time conformance:
-const _sdk: EngineSDK = { manifest, load };
+```js
+sdk.config({ region: 'eu' })        // writes, chains
+await sdk.config()                  // reads
+// → { region: { value: 'eu', default: 'us', enum: [...], description: '…', live: false } }
 ```
 
-CI (or the host) validates a manifest at runtime:
+The getter returns a **descriptor per key** — enough to paint a settings screen
+without asking the engine anything, and without the host knowing a single key name.
+`live` says whether a property can be changed on a running engine or needs a
+`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.
 
-```ts
-import { validateManifest, assertManifest } from '@wasm-gaming/engine-specs';
+## Closing the types
 
-const { valid, errors } = validateManifest(json);
-// or: assertManifest(json)  // throws with a readable error list
+One type parameter carries all four payloads, so there is no order to get wrong:
+
+```ts
+type Sdk = EngineSDK<Rsdkv4Payloads>;
 ```
 
+Leave it off and the payloads stay open (`Record<string, unknown>`), which compiles
+but gives up the checking that is the point.
+
 ## Build
 
 ```bash
 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
+make build            # tsc → dist/ (cleans first)
+make typecheck        # the contract
+make typecheck-tests  # the compile-time conformance suite
+make typecheck-demo   # the demo engine, held to the same contract
+make test             # all of the above + the package integrity tests
+make docs             # typedoc → site/
+make site             # reference at /, demo at /demo/
+make preview          # serve site/ on :8020 (PORT= to change it)
 ```
 
-## Consuming
-
-Depend on it by version (published npm) or by git ref. Engines list it as a
-(dev/peer) dependency and import only `type`s at compile time — the SDK itself
-carries no runtime dependency on this package.
-
-## Versioning
+## Conformance
 
-`CONTRACT_VERSION` tracks the shape of the interfaces. Breaking changes bump the
-major; engines declare which contract version they target via their own SemVer.
+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
+[tests/types.test-d.ts](tests/types.test-d.ts), guarded by `@ts-expect-error` — which
+fails if a rejection ever stops happening.
 
 ## License
 

package/demo/app.html

@@ -0,0 +1,227 @@
+<!--
+  The demo, as one root component.
+
+  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 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.
+
+  State lives in the `let`s below: reassigning one repaints what depends on it, so
+  there is no mount bookkeeping here.
+-->
+
+<EngineHeader :name="name" :id="id" :version="version" :description="description" />
+
+<div class="layout">
+  <aside>
+    <section>
+      <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>
+      <h2>calls</h2>
+      <CallLog :entries="calls" />
+    </section>
+  </aside>
+
+  <div>
+    <!-- The engine is handed this element and appends its own canvas to it. -->
+    <div id="stage"></div>
+    <PropertyTable :tables="tables" />
+  </div>
+</div>
+
+<script :setup="{}">
+  const EngineHeader = await import('./components/engine-header.html');
+  const AssetPicker = await import('./components/asset-picker.html');
+  const PropertyTable = await import('./components/property-table.html');
+  const LifecycleBar = await import('./components/lifecycle-bar.html');
+  const CallLog = await import('./components/call-log.html');
+
+  const { DemoEngineSDK } = await import('./demo.sdk.js');
+
+  // 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`;
+
+  let sdk;
+  let play;
+  let running = false;
+  let assets = [];
+  let tables = [];
+  let calls = [];
+
+  /** File names by asset key, for the pickers. The bytes live in the engine. */
+  const picked = {};
+
+  const say = (line) => {
+    calls = [line, ...calls].slice(0, 40);
+  };
+
+  const show = (value) => {
+    if (value === undefined) return 'unset';
+    if (value instanceof Uint8Array) return `${value.byteLength} bytes`;
+    return String(value);
+  };
+
+  /** One getter's return value, flattened for the table component. */
+  const toRows = (properties) =>
+    Object.entries(properties).map(([key, property]) => ({
+      key,
+      value: show(property.value),
+      unset: property.value === undefined,
+      description: property.description ?? '',
+      default: property.default === undefined ? '' : show(property.default),
+      enum: property.enum ? property.enum.join(' | ') : '',
+      allowedTypes: property.allowedTypes ? property.allowedTypes.join(' ') : '',
+      live: Boolean(property.live),
+    }));
+
+  /** Reads the live engine — or the factory, when there is not one yet. */
+  const refresh = async () => {
+    const source = play ?? (sdk ??= new DemoEngineSDK());
+    const [config, options, assetProps, storage] = await Promise.all([
+      source.config(),
+      source.options(),
+      source.assets(),
+      source.storage(),
+    ]);
+
+    assets = Object.entries(assetProps).map(([key, property]) => ({
+      key,
+      description: property.description ?? '',
+      accept: (property.allowedTypes ?? []).join(','),
+      accepts: property.allowedTypes ? `accepts ${property.allowedTypes.join(' ')}` : 'any file',
+      fileName: picked[key] ?? '',
+    }));
+
+    tables = [
+      { title: 'config', rows: toRows(config) },
+      { title: 'options', rows: toRows(options) },
+      { title: 'assets', rows: toRows(assetProps) },
+      { title: 'storage', rows: toRows(storage) },
+    ];
+
+    running = Boolean(play);
+  };
+
+  const onSelect = async ({ key, file }) => {
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    picked[key] = file.name;
+    sdk ??= new DemoEngineSDK();
+    say(`sdk.assets({ ${key}: Uint8Array(${bytes.byteLength}) })`);
+    sdk.assets({ [key]: bytes });
+    if (key === 'rom') {
+      say(`sdk.options({ fileName: '${file.name}', byteLength: ${file.size} })`);
+      sdk.options({ fileName: file.name, byteLength: file.size });
+    }
+    await refresh();
+  };
+
+  const onRemove = async ({ key }) => {
+    delete picked[key];
+    say(`sdk.assets({ ${key}: undefined })`);
+    sdk?.assets({ [key]: undefined });
+    await refresh();
+  };
+
+  const onStart = async () => {
+    sdk ??= new DemoEngineSDK();
+    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();
+    await refresh();
+  };
+
+  const onRestart = async () => {
+    say('await play.restart()');
+    await play.restart();
+    await refresh();
+  };
+
+  // `pause` and `resume` are this engine's own members, not the contract's.
+  const onPause = async () => {
+    say('play.pause()   // engine-specific, not in the contract');
+    play.pause();
+    await refresh();
+  };
+
+  const onResume = async () => {
+    say('play.resume()  // engine-specific, not in the contract');
+    play.resume();
+    await refresh();
+  };
+
+  const onDestroy = async () => {
+    say('await play.destroy()');
+    await play.destroy();
+    play = undefined;
+    sdk = undefined;
+    for (const key of Object.keys(picked)) delete picked[key];
+    await refresh();
+  };
+
+  say('ready — identity read from the class, no engine constructed yet');
+  await refresh();
+</script>
+
+<style>
+  .layout {
+    display: grid;
+    grid-template-columns: minmax(280px, 340px) 1fr;
+    gap: 1.5rem;
+    padding: 1.5rem;
+    align-items: start;
+  }
+
+  @media (max-width: 900px) {
+    .layout {
+      grid-template-columns: 1fr;
+    }
+  }
+
+  aside section {
+    background: var(--panel, #fff);
+    border: 1px solid var(--border, #e2e8f0);
+    border-radius: 4px;
+    padding: 1rem;
+    margin-bottom: 1rem;
+  }
+
+  aside h2 {
+    margin: 0 0 0.75rem;
+    font-size: 0.78rem;
+    font-family: var(--mono, monospace);
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--muted, #64748b);
+  }
+
+  #stage {
+    height: 380px;
+    border: 1px solid var(--border, #e2e8f0);
+    border-radius: 4px;
+    overflow: hidden;
+    background: #060910;
+    margin-bottom: 1rem;
+  }
+
+  #stage canvas {
+    display: block;
+    width: 100%;
+    height: 100%;
+  }
+</style>

package/demo/canvas-renderer.js

@@ -0,0 +1,153 @@
+/**
+ * The demo's picture, and nothing else.
+ *
+ * Isolated from the SDK on purpose: it knows about a canvas and a frame callback,
+ * not about manifests, assets or the engine contract. Whatever shape the demo SDK
+ * takes next, this keeps working untouched — it is the part that was never about
+ * the contract.
+ *
+ * @param {HTMLCanvasElement} canvasEl
+ * @param {{ onFrame?: (fps: number) => void }} [options]
+ */
+export function createCanvasRenderer(canvasEl, { onFrame } = {}) {
+	const ctx = canvasEl.getContext("2d");
+	if (!ctx) {
+		throw new Error("Could not create 2D canvas context.");
+	}
+
+	let raf = 0;
+	let running = false;
+	let lastFrame = performance.now();
+
+	const fontSize = 30;
+	/** @typedef {{ y: number, speed: number, opacity: number, length: number, chars: string[] }} Drop */
+	/** @type {Drop[]} */
+	let drops = [];
+
+	const fitCanvasToWindow = () => {
+		const dpr = window.devicePixelRatio || 1;
+		const rect = canvasEl.getBoundingClientRect();
+		canvasEl.width = Math.max(1, Math.floor(rect.width * dpr));
+		canvasEl.height = Math.max(1, Math.floor(rect.height * dpr));
+	};
+
+	/** @param {number} time */
+	const render = (time) => {
+		if (!running) {
+			return;
+		}
+
+		const width = canvasEl.width;
+		const height = canvasEl.height;
+		const dt = Math.min((time - lastFrame) / 1000, 0.1);
+		const fps = Math.max(1, 1000 / Math.max(1, time - lastFrame));
+		lastFrame = time;
+
+		const expectedColumns = Math.floor(width / fontSize);
+		const maxRows = Math.floor(height / fontSize) + 30;
+
+		if (drops.length !== expectedColumns) {
+			drops = [];
+			for (let x = 0; x < expectedColumns; x++) {
+				drops[x] = {
+					y: Math.random() * maxRows,
+					speed: Math.random() * 1.5 + 0.5,
+					opacity: Math.random() * 0.7 + 0.3,
+					length: Math.floor(Math.random() * 20 + 5),
+					chars: Array.from({ length: maxRows }, () => String.fromCharCode(0x30A0 + Math.random() * 96)),
+				};
+			}
+		}
+
+		// Dark background inside the canvas to contrast with the light UI components
+		ctx.fillStyle = "#060910ff";
+		ctx.fillRect(0, 0, width, height);
+
+		ctx.font = "bold " + fontSize + "px 'Hiragino Sans', 'Hiragino Kaku Gothic ProN', 'Noto Sans CJK JP', sans-serif";
+		ctx.textAlign = "center";
+
+		for (const [x, drop] of drops.entries()) {
+			if (Math.random() > 0.4) {
+				let randIdx = Math.floor(Math.random() * drop.chars.length);
+				drop.chars[randIdx] = String.fromCharCode(0x30A0 + Math.random() * 96);
+			}
+
+			drop.y += drop.speed * (dt * 12);
+
+			let startY = Math.floor(drop.y);
+
+			for (let i = 0; i < drop.length; i++) {
+				let charY = startY - i;
+				if (charY < 0 || charY >= maxRows) continue;
+
+				const text = drop.chars[charY];
+				if (text === undefined) continue;
+				let alpha = drop.opacity * (1 - (i / drop.length));
+
+				if (i === 0) {
+					ctx.fillStyle = `rgba(220, 255, 255, ${drop.opacity})`;
+				} else {
+					const hue = ((time / 15) + (x * 10)) % 360;
+					ctx.fillStyle = `hsla(${hue}, 80%, 65%, ${alpha})`;
+				}
+
+				ctx.fillText(text, x * fontSize + fontSize / 2, charY * fontSize);
+			}
+
+			if ((drop.y - drop.length) * fontSize > height) {
+				drop.y = 0;
+				drop.speed = Math.random() * 1.5 + 0.5;
+				drop.opacity = Math.random() * 0.7 + 0.3;
+				drop.length = Math.floor(Math.random() * 20 + 5);
+			}
+		}
+
+		ctx.fillStyle = "rgba(255,255,255,0.85)";
+		ctx.fillRect(width - 210, 20, 180, 64);
+		ctx.fillStyle = "#0f172a";
+		ctx.font = "600 36px 'Outfit', system-ui, sans-serif";
+		ctx.textAlign = "left";
+		ctx.fillText(`FPS ${fps.toFixed(0)}`, width - 182, 65);
+
+		onFrame?.(fps);
+		raf = requestAnimationFrame(render);
+	};
+
+	fitCanvasToWindow();
+	window.addEventListener("resize", fitCanvasToWindow);
+
+	return {
+		get running() {
+			return running;
+		},
+		start() {
+			if (running) {
+				return;
+			}
+			running = true;
+			lastFrame = performance.now();
+			raf = requestAnimationFrame(render);
+		},
+		pause() {
+			running = false;
+			cancelAnimationFrame(raf);
+		},
+		resume() {
+			if (running) {
+				return;
+			}
+			running = true;
+			lastFrame = performance.now();
+			raf = requestAnimationFrame(render);
+		},
+		reset() {
+			lastFrame = performance.now();
+			drops = [];
+		},
+		destroy() {
+			running = false;
+			cancelAnimationFrame(raf);
+			window.removeEventListener("resize", fitCanvasToWindow);
+		},
+	};
+}

package/demo/components/asset-picker.html

@@ -0,0 +1,137 @@
+<!--
+  The engine's assets, each driven by its own descriptor.
+
+  Everything shown comes from what `assets()` returned: the hint is the descriptor's
+  `description`, and the file dialog's filter is its `allowedTypes`. The page
+  hardcodes nothing about any asset — add a third one to the engine and it appears
+  here on its own.
+-->
+<div class="pickers">
+  <section class="drop" :each="(asset, index) in assets"
+      :class.selected="asset.fileName"
+      @dragover.prevent="dragging = asset.key"
+      @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="picker-actions">
+      <label class="picker">
+        {{ asset.fileName ? 'Change' : 'Pick file' }}
+        <input type="file" :accept="asset.accept" @change="onPick($event, asset)" />
+      </label>
+      <button type="button" :if="asset.fileName" class="remove-btn" @click.stop="$emit('remove', asset)">Remove</button>
+    </div>
+  </section>
+</div>
+
+<script :setup="{
+  assets = [],
+}">
+  let dragging = null;
+
+  const extractFile = (arg) => {
+    if (!arg) return null;
+    if (arg instanceof File) return arg;
+    if (arg.detail instanceof File) return arg.detail;
+    if (arg.target?.files?.item(0)) return arg.target.files.item(0);
+    if (arg.dataTransfer?.files?.item(0)) return arg.dataTransfer.files.item(0);
+    return null;
+  };
+
+  const onDrop = (event, asset) => {
+    dragging = null;
+    const file = extractFile(event);
+    if (file) $emit('select', { key: asset.key, file });
+  };
+
+  const onPick = (event, asset) => {
+    const file = extractFile(event);
+    if (file) $emit('select', { key: asset.key, file });
+  };
+</script>
+
+<style>
+  .pickers {
+    display: grid;
+    gap: 0.6rem;
+  }
+
+  .drop {
+    border: 1px dashed var(--border, #e2e8f0);
+    border-radius: 4px;
+    padding: 1rem;
+    text-align: center;
+    transition: border-color 200ms ease, background 200ms ease;
+  }
+
+  .drop.active {
+    border-color: var(--accent, #ff007f);
+    background: rgb(255 0 127 / 0.06);
+  }
+
+  .drop.selected {
+    border-style: solid;
+    border-color: var(--accent, #ff007f);
+  }
+
+  .drop strong {
+    display: block;
+    font-family: var(--mono, monospace);
+    font-size: 0.9rem;
+    font-weight: 600;
+    color: var(--text, #0f172a);
+  }
+
+  .drop p {
+    margin: 0.35rem 0 0;
+    color: var(--muted, #64748b);
+    font-size: 0.78rem;
+    word-break: break-all;
+  }
+
+  .drop p.hint {
+    font-size: 0.8rem;
+  }
+
+  .drop p.file-selected {
+    color: var(--accent, #ff007f);
+    font-family: var(--mono, monospace);
+    font-weight: 600;
+  }
+
+  .picker-actions {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    margin-top: 0.75rem;
+  }
+
+  .picker,
+  .remove-btn {
+    display: inline-flex;
+    font-family: var(--mono, monospace);
+    font-size: 0.75rem;
+    padding: 0.35rem 0.7rem;
+    border: 1px solid var(--border, #e2e8f0);
+    border-radius: 3px;
+    background: transparent;
+    color: var(--text, #0f172a);
+    cursor: pointer;
+  }
+
+  .picker:hover {
+    border-color: var(--accent, #ff007f);
+    color: var(--accent, #ff007f);
+  }
+
+  .picker input {
+    display: none;
+  }
+
+  .remove-btn:hover {
+    border-color: #ef4444;
+    color: #ef4444;
+  }
+</style>