@wasm-gaming/engine-specs 0.2.7 → 0.3.1

package/demo/demo.sdk.js

@@ -1,211 +1,413 @@
-export function createDummySdk() {
-	const manifest = {
-		id: "dummy-canvas-sdk",
-		version: "0.1.0-demo",
-		name: "Dummy Canvas Engine",
-		description: "A placeholder SDK that renders animated content on canvas.",
-		artifacts: {
-			wasm: "./dummy.wasm",
-			js: "./dummy.js",
-		},
-		assets: [
-			{
-				key: "rom",
-				mountPath: "/rom.bin",
-				required: true,
-				accept: [".rom", ".bin", ".zip", ".dat"],
-				description: "Any game ROM file works in this demo.",
-			},
-			{
-				key: "bios",
-				mountPath: "/bios.bin",
-				required: false,
-				accept: [".bin", ".rom", ".sys"],
-				description: "System BIOS firmware file.",
-			},
-		],
-		input: "keyboard-default",
-		video: {
-			baseWidth: 320,
-			baseHeight: 256,
-			aspect: "5:4",
-		},
-		capabilities: {
-			saveStates: false,
-			sram: false,
-		},
-	};
-
-	return {
-		manifest,
-		async load(config) {
-			const ownsCanvas = !config.canvasEl;
-			const canvasEl = config.canvasEl ?? document.createElement("canvas");
-			if (ownsCanvas) {
-				config.attachTo.appendChild(canvasEl);
-			}
-
-			const ctx = canvasEl.getContext("2d");
-			if (!ctx) {
-				const error = new Error("Could not create 2D canvas context.");
-				config.onEvent?.({ type: "error", error });
-				throw error;
-			}
-
-			// Copy loaded ROM and BIOS assets to MEMFS (In-Memory Virtual File System)
-			const MEMFS = new Map();
-			if (config.assets) {
-				for (const assetSpec of manifest.assets) {
-					const data = config.assets[assetSpec.key];
-					if (data) {
-						const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
-						MEMFS.set(assetSpec.mountPath, bytes);
-						console.log(`[MEMFS] Copied asset '${assetSpec.key}' (${bytes.byteLength} bytes) to ${assetSpec.mountPath}`);
-					}
-				}
-			}
-
-			let raf = 0;
-			let running = false;
-			let t0 = performance.now();
-			let lastFrame = t0;
-
-			const fontSize = 30;
-			let drops = [];
-
-			const fitCanvasToWindow = () => {
-				const dpr = window.devicePixelRatio || 1;
-				const rect = canvasEl.getBoundingClientRect();
-				const width = Math.max(1, Math.floor(rect.width * dpr));
-				const height = Math.max(1, Math.floor(rect.height * dpr));
-				canvasEl.width = width;
-				canvasEl.height = height;
-			};
-
-			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 (let x = 0; x < drops.length; x++) {
-					let drop = drops[x];
-
-					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;
-
-						let text = drop.chars[charY];
-						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);
-
-				config.onEvent?.({ type: "frame", fps });
-				raf = requestAnimationFrame(render);
-			};
-
-			fitCanvasToWindow();
-			window.addEventListener("resize", fitCanvasToWindow);
-			config.onEvent?.({ type: "ready" });
-
-			return {
-				start() {
-					if (running) {
-						return;
-					}
-					running = true;
-					raf = requestAnimationFrame(render);
+// @ts-check
+/**
+ * The demo engine, written against the contract in `src/engine-specs.ts`.
+ *
+ * It is a real implementation, not a mock: the four payloads are closed with named
+ * types, every getter returns descriptors, every setter chains, and a factory
+ * governs at most one live engine. `demo/tsconfig.json` checks it against the
+ * contract, so "the demo conforms" is verified rather than claimed.
+ *
+ * What used to live in a manifest lives here now:
+ * `id`/`version`/`name`/`description` are static on the class, the video geometry is
+ * `config`, and what an asset accepts is its descriptor's `allowedTypes`.
+ */
+
+import { createCanvasRenderer } from './canvas-renderer.js'
+
+/**
+ * @typedef {{ baseWidth: number, baseHeight: number }} DemoConfig
+ * @typedef {{ fileName?: string, byteLength?: number }} DemoOptions
+ * @typedef {{ rom?: Uint8Array, bios?: Uint8Array }} DemoAssets
+ * @typedef {{ namespace: string }} DemoStorage
+ * @typedef {{ config: DemoConfig, options: DemoOptions, assets: DemoAssets, storage: DemoStorage }} DemoPayloads
+ *
+ * @typedef {import('../src/engine-specs.js').EngineInit<DemoPayloads>} DemoInit
+ * @typedef {import('../src/engine-specs.js').EnginePlay<DemoPayloads>} DemoPlayContract
+ * @typedef {import('../src/engine-specs.js').PromisePlay<DemoPayloads>} DemoPromisePlay
+ * @typedef {import('../src/engine-specs.js').EngineSDK<DemoPayloads>} DemoSDKContract
+ * @typedef {import('../src/engine-specs.js').EngineSDKConstructor<DemoPayloads>} DemoSDKConstructor
+ */
+
+/** @template T @typedef {import('../src/engine-specs.js').PropertiesDefinition<T>} Props */
+
+/**
+ * The live engine.
+ *
+ * `pause()` and `resume()` are **not** part of the contract — they are this engine's
+ * own additions, which the demo's ESC menu drives. Anything the contract declares is
+ * below them.
+ *
+ * @implements {DemoPlayContract}
+ */
+class DemoPlay {
+	/** @type {DemoConfig} */
+	#config = { baseWidth: 320, baseHeight: 256 }
+	/** @type {DemoOptions} */
+	#options = {}
+	/** @type {DemoAssets} */
+	#assets = {}
+	/** @type {DemoStorage} */
+	#storage = { namespace: 'engine-specs/demo' }
+	/** @type {HTMLElement | undefined} */
+	#mount
+	/** @type {HTMLCanvasElement | undefined} */
+	#canvas
+	/** @type {ReturnType<typeof createCanvasRenderer> | undefined} */
+	#renderer
+	/** The engine's own file system, keyed by mount path. */
+	#memfs = new Map()
+
+	/** @param {DemoInit} [init] */
+	constructor(init) {
+		if (init?.config) Object.assign(this.#config, init.config)
+		if (init?.options) Object.assign(this.#options, init.options)
+		if (init?.assets) Object.assign(this.#assets, init.assets)
+		if (init?.storage) Object.assign(this.#storage, init.storage)
+		if (init?.mount) this.mount(init.mount)
+		this.#copyAssetsToMemfs()
+	}
+
+	#copyAssetsToMemfs() {
+		for (const [key, data] of Object.entries(this.#assets)) {
+			if (!data) continue
+			const bytes = data instanceof Uint8Array ? data : new Uint8Array(data)
+			this.#memfs.set(`/${key}.bin`, bytes)
+			console.log(`[MEMFS] ${key} → /${key}.bin (${bytes.byteLength} bytes)`)
+		}
+	}
+
+	/**
+	 * @overload
+	 * @returns {Promise<Props<DemoConfig>>}
+	 * @overload
+	 * @param {Partial<DemoConfig>} patch
+	 * @returns {DemoPromisePlay}
+	 * @param {Partial<DemoConfig>} [patch]
+	 * @returns {any}
+	 */
+	config(patch) {
+		if (arguments.length === 0) {
+			return Promise.resolve({
+				baseWidth: {
+					value: this.#config.baseWidth,
+					default: 320,
+					description: 'Native render width, in pixels.',
+					live: false,
 				},
-				pause() {
-					running = false;
-					cancelAnimationFrame(raf);
+				baseHeight: {
+					value: this.#config.baseHeight,
+					default: 256,
+					description: 'Native render height, in pixels.',
+					live: false,
+				},
+			})
+		}
+		Object.assign(this.#config, patch)
+		return hydrate(Promise.resolve(this))
+	}
+
+	/**
+	 * @overload
+	 * @returns {Promise<Props<DemoOptions>>}
+	 * @overload
+	 * @param {Partial<DemoOptions>} patch
+	 * @returns {DemoPromisePlay}
+	 * @param {Partial<DemoOptions>} [patch]
+	 * @returns {any}
+	 */
+	options(patch) {
+		if (arguments.length === 0) {
+			return Promise.resolve({
+				fileName: {
+					value: this.#options.fileName,
+					description: 'Name of the loaded ROM.',
+					live: true,
 				},
-				resume() {
-					if (running) {
-						return;
-					}
-					running = true;
-					raf = requestAnimationFrame(render);
+				byteLength: {
+					value: this.#options.byteLength,
+					description: 'Size of the loaded ROM, in bytes.',
+					live: true,
 				},
-				reset() {
-					t0 = performance.now();
-					lastFrame = t0;
+			})
+		}
+		Object.assign(this.#options, patch)
+		return hydrate(Promise.resolve(this))
+	}
+
+	/**
+	 * `allowedTypes` is what a host file picker needs: it replaces the manifest's
+	 * `AssetSpec.accept`, and now travels with the value it describes.
+	 *
+	 * @overload
+	 * @returns {Promise<Props<DemoAssets>>}
+	 * @overload
+	 * @param {Partial<DemoAssets>} patch
+	 * @returns {DemoPromisePlay}
+	 * @param {Partial<DemoAssets>} [patch]
+	 * @returns {any}
+	 */
+	assets(patch) {
+		if (arguments.length === 0) {
+			return Promise.resolve({
+				rom: {
+					value: this.#assets.rom,
+					description: 'Any game ROM file works in this demo.',
+					allowedTypes: ['.rom', '.bin', '.zip', '.dat'],
+					live: false,
 				},
-				setInput() {
-					return;
+				bios: {
+					value: this.#assets.bios,
+					description: 'System BIOS firmware file.',
+					allowedTypes: ['.bin', '.rom', '.sys'],
+					live: false,
 				},
-				destroy() {
-					running = false;
-					cancelAnimationFrame(raf);
-					window.removeEventListener("resize", fitCanvasToWindow);
-					if (ownsCanvas) {
-						canvasEl.remove();
-					}
+			})
+		}
+		Object.assign(this.#assets, patch)
+		this.#copyAssetsToMemfs()
+		return hydrate(Promise.resolve(this))
+	}
+
+	/**
+	 * @overload
+	 * @returns {Promise<Props<DemoStorage>>}
+	 * @overload
+	 * @param {Partial<DemoStorage>} patch
+	 * @returns {DemoPromisePlay}
+	 * @param {Partial<DemoStorage>} [patch]
+	 * @returns {any}
+	 */
+	storage(patch) {
+		if (arguments.length === 0) {
+			return Promise.resolve({
+				namespace: {
+					value: this.#storage.namespace,
+					description: 'Folder the engine owns.',
+					live: false,
 				},
-			};
-		},
-	};
+			})
+		}
+		Object.assign(this.#storage, patch)
+		return hydrate(Promise.resolve(this))
+	}
+
+	/**
+	 * Where the picture goes. The engine owns the canvas; the host owns the container.
+	 * @param {HTMLElement} target
+	 * @returns {DemoPromisePlay}
+	 */
+	mount(target) {
+		this.#mount = target
+		if (!this.#canvas) {
+			this.#canvas = document.createElement('canvas')
+		}
+		target.appendChild(this.#canvas)
+		this.#renderer ??= createCanvasRenderer(this.#canvas)
+		return hydrate(Promise.resolve(this))
+	}
+
+	/**
+	 * Opens or reopens a session. The payload is cumulative, merged flat, one level.
+	 * @param {Partial<DemoOptions>} [options]
+	 * @returns {DemoPromisePlay}
+	 */
+	restart(options) {
+		if (options) Object.assign(this.#options, options)
+		this.#renderer?.reset()
+		this.#renderer?.start()
+		return hydrate(Promise.resolve(this))
+	}
+
+	async destroy() {
+		this.#renderer?.destroy()
+		this.#renderer = undefined
+		this.#canvas?.remove()
+		this.#canvas = undefined
+		this.#mount = undefined
+		this.#memfs.clear()
+	}
+
+	// ---- Beyond the contract: this engine's own members ----
+
+	pause() {
+		this.#renderer?.pause()
+	}
+
+	resume() {
+		this.#renderer?.resume()
+	}
 }
 
-export const sdk = createDummySdk();
-export default sdk;
+/**
+ * Wraps a promise of the engine in the chainable surface.
+ *
+ * Structural, as the contract allows: not a `Promise` subclass, a delegation to one
+ * — plus `[Symbol.toStringTag]`, which is easy to forget and required.
+ *
+ * @param {Promise<DemoPlay>} inner
+ * @returns {DemoPromisePlay}
+ */
+function hydrate(inner) {
+	/** @param {(play: DemoPlay) => unknown} step */
+	const chain = (step) => hydrate(inner.then(async (play) => { await step(play); return play }))
+
+	/** @type {any} */
+	const hydrated = {
+		/** @param {any} onfulfilled @param {any} onrejected */
+		then: (onfulfilled, onrejected) => inner.then(onfulfilled, onrejected),
+		/** @param {any} onrejected */
+		catch: (onrejected) => inner.catch(onrejected),
+		/** @param {any} onfinally */
+		finally: (onfinally) => inner.finally(onfinally),
+		[Symbol.toStringTag]: 'PromisePlay',
+
+		/** @param {Partial<DemoConfig>} [patch] */
+		config: (patch) =>
+			patch === undefined ? inner.then((p) => p.config()) : chain((p) => p.config(patch)),
+		/** @param {Partial<DemoOptions>} [patch] */
+		options: (patch) =>
+			patch === undefined ? inner.then((p) => p.options()) : chain((p) => p.options(patch)),
+		/** @param {Partial<DemoAssets>} [patch] */
+		assets: (patch) =>
+			patch === undefined ? inner.then((p) => p.assets()) : chain((p) => p.assets(patch)),
+		/** @param {Partial<DemoStorage>} [patch] */
+		storage: (patch) =>
+			patch === undefined ? inner.then((p) => p.storage()) : chain((p) => p.storage(patch)),
+
+		/** @param {HTMLElement} target */
+		mount: (target) => chain((p) => p.mount(target)),
+		/** @param {Partial<DemoOptions>} [options] */
+		restart: (options) => chain((p) => p.restart(options)),
+		destroy: () => inner.then((p) => p.destroy()),
+	}
+	return hydrated
+}
+
+/**
+ * The factory. Identity is static, so a launcher can list engines without
+ * constructing one.
+ *
+ * @implements {DemoSDKContract}
+ */
+export class DemoEngineSDK {
+	static id = 'dummy-canvas-sdk'
+	static version = '0.1.0-demo'
+	static name = 'Dummy Canvas Engine'
+	static description = 'A placeholder engine that renders animated content on canvas.'
+
+	/** @type {DemoInit} */
+	#init = {}
+	/** @type {DemoPlay | undefined} */
+	#play
+
+	/** @param {DemoInit} [init] */
+	constructor(init) {
+		if (init) this.#init = { ...init }
+	}
+
+	/** Answers a read before there is an engine: the settings the next one will use. */
+	#pending() {
+		return this.#play ?? new DemoPlay(this.#init)
+	}
+
+	/**
+	 * @overload
+	 * @returns {Promise<Props<DemoConfig>>}
+	 * @overload
+	 * @param {Partial<DemoConfig>} patch
+	 * @returns {this}
+	 * @param {Partial<DemoConfig>} [patch]
+	 * @returns {any}
+	 */
+	config(patch) {
+		if (arguments.length === 0) return this.#pending().config()
+		this.#init.config = { ...this.#init.config, ...patch }
+		if (this.#play && patch) this.#play.config(patch)
+		return this
+	}
+
+	/**
+	 * @overload
+	 * @returns {Promise<Props<DemoOptions>>}
+	 * @overload
+	 * @param {Partial<DemoOptions>} patch
+	 * @returns {this}
+	 * @param {Partial<DemoOptions>} [patch]
+	 * @returns {any}
+	 */
+	options(patch) {
+		if (arguments.length === 0) return this.#pending().options()
+		this.#init.options = { ...this.#init.options, ...patch }
+		if (this.#play && patch) this.#play.options(patch)
+		return this
+	}
+
+	/**
+	 * @overload
+	 * @returns {Promise<Props<DemoAssets>>}
+	 * @overload
+	 * @param {Partial<DemoAssets>} patch
+	 * @returns {this}
+	 * @param {Partial<DemoAssets>} [patch]
+	 * @returns {any}
+	 */
+	assets(patch) {
+		if (arguments.length === 0) return this.#pending().assets()
+		this.#init.assets = { ...this.#init.assets, ...patch }
+		if (this.#play && patch) this.#play.assets(patch)
+		return this
+	}
+
+	/**
+	 * @overload
+	 * @returns {Promise<Props<DemoStorage>>}
+	 * @overload
+	 * @param {Partial<DemoStorage>} patch
+	 * @returns {this}
+	 * @param {Partial<DemoStorage>} [patch]
+	 * @returns {any}
+	 */
+	storage(patch) {
+		if (arguments.length === 0) return this.#pending().storage()
+		this.#init.storage = { ...this.#init.storage, ...patch }
+		if (this.#play && patch) this.#play.storage(patch)
+		return this
+	}
+
+	/**
+	 * Recorded now, applied when the engine exists — same as `new SDK({ mount })`.
+	 * @param {HTMLElement} target
+	 * @returns {this}
+	 */
+	mount(target) {
+		this.#init.mount = target
+		if (this.#play) this.#play.mount(target)
+		return this
+	}
+
+	/**
+	 * Bringing the engine up is this engine's own business, not a step the contract
+	 * exposes — so it stays private. A factory governs at most one live engine.
+	 * @returns {DemoPlay}
+	 */
+	#boot() {
+		this.#play ??= new DemoPlay(this.#init)
+		return this.#play
+	}
+
+	/**
+	 * The only way in. On a live engine it reopens the session rather than
+	 * rebuilding one.
+	 * @param {Partial<DemoOptions>} [options]
+	 * @returns {DemoPromisePlay}
+	 */
+	start(options) {
+		return hydrate(Promise.resolve(this.#boot())).restart(options)
+	}
+}
+
+/** Conformance, checked by the compiler: does the class satisfy the contract? */
+/** @type {DemoSDKConstructor} */
+export const DemoEngine = DemoEngineSDK
+
+export default DemoEngine

package/demo/index.html

@@ -3,69 +3,20 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>WASM Gaming Engine Specs Demo</title>
+    <title>engine-specs demo</title>
     <link rel="stylesheet" href="./demo.css" />
   </head>
   <body>
     <main></main>
 
     <script type="module">
-      import demo from './demo.js'
-      import sdk from './demo.sdk.js'
+      import { C79 } from 'https://jgermade.github.io/jq79/jq79.js'
 
-      demo
-        .init({
-          messages: {
-            title: 'WASM Gaming Engine Demo',
-            dropRomPrompt: 'Drop ROM File',
-            launchButton: 'Launch Engine',
-            escMenuTitle: 'Settings',
-            escMenuResume: 'Resume',
-            escMenuReset: 'Reset game',
-            escMenuRestoreDefaults: 'Restore defaults',
-            escMenuExit: 'Exit to Launcher',
-          },
-          bios: false, // 'required' | 'optional' | false
-          escMenu: {
-            enabled: true,
-          },
-        })
-        .on('rom:save', ({ file }) => {
-          console.log('[Demo] ROM loaded:', file?.name)
-        })
-        .on('bios:save', ({ file }) => {
-          console.log('[Demo] BIOS loaded:', file?.name)
-        })
-        .on('launch', async (e) => {
-          const assets = {}
-
-          // if rom loaded
-          if (demo.hasFile('rom')) {
-            assets.rom = await demo.loadToMEMFS('rom')
-          }
-
-          // if bios required and loaded
-          if (demo.hasFile('bios')) {
-            assets.bios = await demo.loadToMEMFS('bios')
-          }
-
-          const instance = await sdk.load({
-            attachTo: e.attachTo,
-            assets,
-            options: {
-              fileName: e.fileName,
-              byteLength: e.byteLength,
-            },
-            onEvent(event) {
-              if (event.type === 'error') {
-                console.error(event.error)
-              }
-            },
-          })
-
-          instance.start()
-          return instance
+      C79.fetch('./app.html')
+        .mount('body > main')
+        .catch(err => {
+          console.error('Failed to load app.html:', err)
         })
     </script>
   </body>
-</html>
+</html>