@wasm-gaming/engine-specs 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# @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.
+
+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.
+
+## Two layers
+
+**Layer A — declarative ([src/manifest.ts](src/manifest.ts))**
+`EngineManifest` describes what an engine ships and needs: artifacts (`wasm`/`js`),
+runtime `assets` (each with a VFS `mountPath` + optional `validate`), the `input`
+preset, `video` geometry, engine-specific `options` (a JSON Schema), and
+`capabilities`. Everything that differs between engines lives here as data.
+
+**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`
+(`start`/`pause`/`resume`/`reset`/`setInput`/`destroy`, plus capability-gated
+`saveState`/`loadState`/`screenshot`).
+
+`EngineConfig.storageNamespace` is an optional host hint for per-game storage
+segregation (for example OPFS folders like `sonic1` and `sonic2`).
+`EngineInstance.purgeStorage()` is an optional method for engines that can remove
+persisted runtime files for the active namespace only.
+
+The host drives all engines identically.
+
+## Usage
+
+An engine implements the contract:
+
+```ts
+import type { EngineSDK, EngineManifest } from '@wasm-gaming/engine-specs';
+
+export const manifest: EngineManifest = { /* ... */ };
+export async function load(config) { /* ... */ }
+
+// Compile-time conformance:
+const _sdk: EngineSDK = { manifest, load };
+```
+
+CI (or the host) validates a manifest at runtime:
+
+```ts
+import { validateManifest, assertManifest } from '@wasm-gaming/engine-specs';
+
+const { valid, errors } = validateManifest(json);
+// or: assertManifest(json)  // throws with a readable error list
+```
+
+## Build
+
+```bash
+npm install
+make build         # tsc → dist/ (.js + .d.ts)
+make typecheck     # no emit
+make test          # build + node test runner
+make publish-dry-run
+make publish
+```
+
+## 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
+
+`CONTRACT_VERSION` tracks the shape of the interfaces. Breaking changes bump the
+major; engines declare which contract version they target via their own SemVer.
+
+## License
+
+MIT.

package/dist/engine.d.ts

@@ -0,0 +1,68 @@
+import type { EngineManifest, KeyMap, InputPreset } from './manifest.js';
+/** Binary asset payload accepted by `load()`. */
+export type AssetData = Uint8Array | ArrayBuffer | string;
+/** Where an engine may persist saves/SRAM. */
+export type PersistMode = 'idbfs' | 'opfs' | null;
+export interface EngineConfig {
+    /** Render target. The SDK is responsible for the `#canvas` id if the engine needs it. */
+    canvas: HTMLCanvasElement;
+    /** Runtime files keyed by `AssetSpec.key`. Required specs must be present. */
+    assets: Record<string, AssetData>;
+    /** Engine-specific settings, validated against `manifest.options`. */
+    options?: Record<string, unknown>;
+    /** Persistence backend for saves, when the engine supports it. */
+    persist?: PersistMode;
+    /**
+     * Optional storage namespace under the engine's working dir.
+     * Hosts can use this to isolate per-game persisted assets (e.g. sonic1/sonic2).
+     */
+    storageNamespace?: string;
+    /** Lifecycle/telemetry sink. Handlers must not throw. */
+    onEvent?: (e: EngineEvent) => void;
+    /** Override artifact locations (e.g. host-fetched Release assets). */
+    jsUrl?: string;
+    wasmUrl?: string;
+}
+export type EngineEvent = {
+    type: 'ready';
+} | {
+    type: 'error';
+    error: Error;
+} | {
+    type: 'exit';
+} | {
+    type: 'frame';
+    fps: number;
+};
+export interface EngineInstance {
+    /** Begin running. `load()` may auto-start; then this is a no-op. */
+    start(): void;
+    pause(): void;
+    resume(): void;
+    /** Reset to power-on. May throw if the engine cannot reset in-process. */
+    reset(): void;
+    /** Swap the active input preset/map at runtime. */
+    setInput(map: InputPreset | KeyMap): void;
+    saveState?(): Promise<Uint8Array>;
+    loadState?(data: Uint8Array): Promise<void>;
+    screenshot?(): Promise<Blob>;
+    /**
+     * Optional targeted purge of persisted runtime files for the active namespace.
+     * Engines that do not persist assets can omit this method.
+     */
+    purgeStorage?(): {
+        data: boolean;
+        settings: boolean;
+    } | Promise<{
+        data: boolean;
+        settings: boolean;
+    }>;
+    /** Tear down: stop the loop, release listeners/DOM, free the instance. */
+    destroy(): void;
+}
+/** The default export shape every engine package must provide. */
+export interface EngineSDK {
+    manifest: EngineManifest;
+    load(config: EngineConfig): Promise<EngineInstance>;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEzE,iDAAiD;AACjD,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,MAAM,CAAC;AAE1D,8CAA8C;AAC9C,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;AAElD,MAAM,WAAW,YAAY;IAC3B,yFAAyF;IACzF,MAAM,EAAE,iBAAiB,CAAC;IAC1B,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAClC,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,kEAAkE;IAClE,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,CAAC;IACnC,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,KAAK,IAAI,IAAI,CAAC;IACd,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;IACf,0EAA0E;IAC1E,KAAK,IAAI,IAAI,CAAC;IACd,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC;IAG1C,SAAS,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAClC,SAAS,CAAC,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;;;OAGG;IACH,YAAY,CAAC,IACT;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,GACpC,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAElD,0EAA0E;IAC1E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,cAAc,CAAC;IACzB,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACrD"}

package/dist/engine.js

@@ -0,0 +1,8 @@
+// Layer B — the imperative contract.
+//
+// Every engine subproject's SDK exposes `{ manifest, load }` (an `EngineSDK`).
+// `load()` boots the engine and returns an `EngineInstance` the host controls.
+// The interface is identical across engines; per-engine differences are absorbed
+// by `manifest` (Layer A) and the `assets`/`options` payloads.
+export {};
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,iFAAiF;AACjF,+DAA+D"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { EngineManifest, EngineArtifacts, AssetSpec, AssetValidation, VideoSpec, EngineCapabilities, KeyMap, InputPreset, JSONSchema, } from './manifest.js';
+export type { EngineSDK, EngineInstance, EngineConfig, EngineEvent, AssetData, PersistMode, } from './engine.js';
+export { validateManifest, assertManifest } from './validate.js';
+export type { ValidationResult } from './validate.js';
+/** The contract version. Bump on breaking changes to the shapes above. */
+export declare const CONTRACT_VERSION = "0.1.1";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,YAAY,EACV,cAAc,EACd,eAAe,EACf,SAAS,EACT,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,MAAM,EACN,WAAW,EACX,UAAU,GACX,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,SAAS,EACT,cAAc,EACd,YAAY,EACZ,WAAW,EACX,SAAS,EACT,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACjE,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+// @wasm-gaming/engine-specs — the engine contract.
+//
+// Layer A (declarative): EngineManifest & friends — what an engine ships/needs.
+// Layer B (imperative):  EngineSDK / EngineInstance — how the host drives it.
+// Plus a runtime validator for the manifest.
+export { validateManifest, assertManifest } from './validate.js';
+/** The contract version. Bump on breaking changes to the shapes above. */
+export const CONTRACT_VERSION = '0.1.1';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,EAAE;AACF,gFAAgF;AAChF,8EAA8E;AAC9E,6CAA6C;AAuB7C,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGjE,0EAA0E;AAC1E,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,69 @@
+/** A loose JSON Schema object (Draft 2020-12 subset). Kept dependency-free. */
+export type JSONSchema = Record<string, unknown>;
+/** A gamepad→keyboard key map, or the name of a built-in preset (e.g. "rsdkv4"). */
+export type KeyMap = Record<string, string>;
+export type InputPreset = string;
+/** How the host validates a user-provided asset before mounting it. */
+export interface AssetValidation {
+    /** Exact byte length, if the asset has a fixed size (e.g. a known ROM dump). */
+    bytes?: number;
+    /** Lowercase hex SHA-1 the asset must match. */
+    sha1?: string;
+}
+/** A file the host must supply at runtime, mounted into the engine's VFS. */
+export interface AssetSpec {
+    /** Stable key the host uses in `EngineConfig.assets` (e.g. "data", "rom", "bios"). */
+    key: string;
+    /** Absolute VFS path the engine reads from (e.g. "/Data.rsdk", "/roms/neogeo.zip"). */
+    mountPath: string;
+    /** If true, `load()` must reject when the asset is absent. */
+    required: boolean;
+    /** Suggested file extensions for a host file picker (e.g. [".rsdk"]). */
+    accept?: string[];
+    /** Integrity/shape constraints the host may enforce before mounting. */
+    validate?: AssetValidation;
+    /** Human-readable note shown in host UI. */
+    description?: string;
+}
+/** Where the CI-built artifacts live (relative paths or URLs; host resolves them). */
+export interface EngineArtifacts {
+    /** The `.wasm` binary. */
+    wasm: string;
+    /** The JS glue/loader (an ES module factory). */
+    js: string;
+    /** Optional preloaded Emscripten `.data` package (engines that bundle assets). */
+    data?: string;
+}
+/** Native render surface geometry. */
+export interface VideoSpec {
+    baseWidth: number;
+    baseHeight: number;
+    /** Display aspect ratio, e.g. "16:9" or "4:3". Defaults to baseWidth:baseHeight. */
+    aspect?: string;
+}
+/** Optional features an engine may or may not implement. Gate calls on these. */
+export interface EngineCapabilities {
+    saveStates?: boolean;
+    sram?: boolean;
+    /** Part of a swappable set of cores for one platform (e.g. Megadrive: JGenesis/BlastEm). */
+    coreSelectable?: boolean;
+}
+export interface EngineManifest {
+    /** Stable engine id, e.g. "rsdkv4" | "fbneo" | "blastem" | "jgenesis" | "smw". */
+    id: string;
+    /** SemVer of this engine build/contract implementation. */
+    version: string;
+    /** Human-readable name. */
+    name?: string;
+    description?: string;
+    artifacts: EngineArtifacts;
+    /** Files supplied at runtime. May be empty (e.g. engines with baked-in assets). */
+    assets: AssetSpec[];
+    /** Input preset name or an explicit key map. */
+    input: InputPreset | KeyMap;
+    video: VideoSpec;
+    /** JSON Schema for engine-specific `EngineConfig.options`. */
+    options?: JSONSchema;
+    capabilities: EngineCapabilities;
+}
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAOA,+EAA+E;AAC/E,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,oFAAoF;AACpF,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAC5C,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AAEjC,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,6EAA6E;AAC7E,MAAM,WAAW,SAAS;IACxB,sFAAsF;IACtF,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC9B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,sCAAsC;AACtC,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4FAA4F;IAC5F,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,eAAe,CAAC;IAC3B,mFAAmF;IACnF,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,gDAAgD;IAChD,KAAK,EAAE,WAAW,GAAG,MAAM,CAAC;IAC5B,KAAK,EAAE,SAAS,CAAC;IACjB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,YAAY,EAAE,kBAAkB,CAAC;CAClC"}

package/dist/manifest.js

@@ -0,0 +1,8 @@
+// Layer A — the declarative contract.
+//
+// An EngineManifest describes what an engine subproject ships and needs. It drives
+// the host's launcher UI, asset pickers and validation. Everything that differs
+// between engines (Data.rsdk vs a ROM zip + BIOS vs baked-in assets) is expressed
+// as *data* here, so the imperative interface (Layer B) can stay identical.
+export {};
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,mFAAmF;AACnF,gFAAgF;AAChF,kFAAkF;AAClF,4EAA4E"}

package/dist/validate.d.ts

@@ -0,0 +1,10 @@
+import type { EngineManifest } from './manifest.js';
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/** Validate an unknown value as an EngineManifest. Never throws. */
+export declare function validateManifest(input: unknown): ValidationResult;
+/** Validate and throw on failure. Returns the value narrowed to EngineManifest. */
+export declare function assertManifest(input: unknown): EngineManifest;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAgED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAMjE;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAO7D"}

package/dist/validate.js

@@ -0,0 +1,79 @@
+// Runtime validation of an EngineManifest against the contract.
+// Engine CIs can run this to fail a build that drifts from the spec; hosts can run
+// it on manifests fetched from Releases before trusting them.
+import { z } from 'zod';
+const AssetValidationSchema = z.object({
+    bytes: z.int().nonnegative().optional(),
+    sha1: z.string().optional(),
+}).strict();
+const AssetSpecSchema = z.object({
+    key: z.string().min(1),
+    mountPath: z.string().regex(/^\//),
+    required: z.boolean(),
+    accept: z.array(z.string()).optional(),
+    validate: AssetValidationSchema.optional(),
+    description: z.string().optional(),
+}).strict();
+const InputSchema = z.union([
+    z.string(),
+    z.record(z.string(), z.string()),
+]);
+const VideoSpecSchema = z.object({
+    baseWidth: z.int().positive(),
+    baseHeight: z.int().positive(),
+    aspect: z.string().optional(),
+}).strict();
+const EngineArtifactsSchema = z.object({
+    wasm: z.string(),
+    js: z.string(),
+    data: z.string().optional(),
+}).strict();
+const EngineCapabilitiesSchema = z.object({
+    saveStates: z.boolean().optional(),
+    sram: z.boolean().optional(),
+    coreSelectable: z.boolean().optional(),
+}).strict();
+const EngineManifestSchema = z.object({
+    id: z.string().min(1),
+    version: z.string().min(1),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    artifacts: EngineArtifactsSchema,
+    assets: z.array(AssetSpecSchema),
+    input: InputSchema,
+    video: VideoSpecSchema,
+    options: z.record(z.string(), z.unknown()).optional(),
+    capabilities: EngineCapabilitiesSchema,
+}).strict();
+function formatIssuePath(path) {
+    if (path.length === 0)
+        return 'manifest';
+    let out = 'manifest';
+    for (const part of path) {
+        if (typeof part === 'number')
+            out += `[${part}]`;
+        else if (typeof part === 'string')
+            out += `.${part}`;
+        else
+            out += '.[symbol]';
+    }
+    return out;
+}
+/** Validate an unknown value as an EngineManifest. Never throws. */
+export function validateManifest(input) {
+    const result = EngineManifestSchema.safeParse(input);
+    if (result.success)
+        return { valid: true, errors: [] };
+    const errors = result.error.issues.map((issue) => `${formatIssuePath(issue.path)}: ${issue.message}`);
+    return { valid: false, errors };
+}
+/** Validate and throw on failure. Returns the value narrowed to EngineManifest. */
+export function assertManifest(input) {
+    const result = EngineManifestSchema.safeParse(input);
+    if (!result.success) {
+        const errors = result.error.issues.map((issue) => `${formatIssuePath(issue.path)}: ${issue.message}`);
+        throw new Error(`Invalid EngineManifest:\n- ${errors.join('\n- ')}`);
+    }
+    return result.data;
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,mFAAmF;AACnF,8DAA8D;AAE9D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,KAAK,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IACvC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC;IAClC,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;IACrB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACtC,QAAQ,EAAE,qBAAqB,CAAC,QAAQ,EAAE;IAC1C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC;IAC1B,CAAC,CAAC,MAAM,EAAE;IACV,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;CACjC,CAAC,CAAC;AAEH,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,SAAS,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAC7B,UAAU,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAC9B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAClC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC5B,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,SAAS,EAAE,qBAAqB;IAChC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC;IAChC,KAAK,EAAE,WAAW;IAClB,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IACrD,YAAY,EAAE,wBAAwB;CACvC,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,SAAS,eAAe,CAAC,IAAmB;IAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC;IAEzC,IAAI,GAAG,GAAG,UAAU,CAAC;IACrB,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,GAAG,IAAI,IAAI,IAAI,GAAG,CAAC;aAC5C,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;;YAChD,GAAG,IAAI,WAAW,CAAC;IAC1B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACrD,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAEvD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IACtG,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAClC,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACrD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACtG,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,MAAM,CAAC,IAAsB,CAAC;AACvC,CAAC"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@wasm-gaming/engine-specs",
+  "version": "0.1.0",
+  "description": "The wasm-gaming engine contract: the single shared interface every WASM game/emulator engine and the host app conform to. TypeScript types + JSON Schema + a Zod runtime validator.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schema/engine-manifest.json": "./schema/engine-manifest.schema.json"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "schema/"
+  ],
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wasm-gaming/engine-specs"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  }
+}

package/schema/engine-manifest.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/wasm-gaming/engine-specs/schema/engine-manifest.json",
+  "title": "EngineManifest",
+  "description": "The declarative contract an engine subproject ships (mirror of src/manifest.ts).",
+  "type": "object",
+  "required": ["id", "version", "artifacts", "assets", "input", "video", "capabilities"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "version": { "type": "string", "minLength": 1 },
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "artifacts": {
+      "type": "object",
+      "required": ["wasm", "js"],
+      "additionalProperties": false,
+      "properties": {
+        "wasm": { "type": "string" },
+        "js": { "type": "string" },
+        "data": { "type": "string" }
+      }
+    },
+    "assets": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["key", "mountPath", "required"],
+        "additionalProperties": false,
+        "properties": {
+          "key": { "type": "string", "minLength": 1 },
+          "mountPath": { "type": "string", "pattern": "^/" },
+          "required": { "type": "boolean" },
+          "accept": { "type": "array", "items": { "type": "string" } },
+          "validate": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "bytes": { "type": "integer", "minimum": 0 },
+              "sha1": { "type": "string" }
+            }
+          },
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "input": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "object", "additionalProperties": { "type": "string" } }
+      ]
+    },
+    "video": {
+      "type": "object",
+      "required": ["baseWidth", "baseHeight"],
+      "additionalProperties": false,
+      "properties": {
+        "baseWidth": { "type": "integer", "exclusiveMinimum": 0 },
+        "baseHeight": { "type": "integer", "exclusiveMinimum": 0 },
+        "aspect": { "type": "string" }
+      }
+    },
+    "options": { "type": "object" },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "saveStates": { "type": "boolean" },
+        "sram": { "type": "boolean" },
+        "coreSelectable": { "type": "boolean" }
+      }
+    }
+  }
+}

package/src/engine.ts

@@ -0,0 +1,74 @@
+// Layer B — the imperative contract.
+//
+// Every engine subproject's SDK exposes `{ manifest, load }` (an `EngineSDK`).
+// `load()` boots the engine and returns an `EngineInstance` the host controls.
+// The interface is identical across engines; per-engine differences are absorbed
+// by `manifest` (Layer A) and the `assets`/`options` payloads.
+
+import type { EngineManifest, KeyMap, InputPreset } from './manifest.js';
+
+/** Binary asset payload accepted by `load()`. */
+export type AssetData = Uint8Array | ArrayBuffer | string;
+
+/** Where an engine may persist saves/SRAM. */
+export type PersistMode = 'idbfs' | 'opfs' | null;
+
+export interface EngineConfig {
+  /** Render target. The SDK is responsible for the `#canvas` id if the engine needs it. */
+  canvas: HTMLCanvasElement;
+  /** Runtime files keyed by `AssetSpec.key`. Required specs must be present. */
+  assets: Record<string, AssetData>;
+  /** Engine-specific settings, validated against `manifest.options`. */
+  options?: Record<string, unknown>;
+  /** Persistence backend for saves, when the engine supports it. */
+  persist?: PersistMode;
+  /**
+   * Optional storage namespace under the engine's working dir.
+   * Hosts can use this to isolate per-game persisted assets (e.g. sonic1/sonic2).
+   */
+  storageNamespace?: string;
+  /** Lifecycle/telemetry sink. Handlers must not throw. */
+  onEvent?: (e: EngineEvent) => void;
+  /** Override artifact locations (e.g. host-fetched Release assets). */
+  jsUrl?: string;
+  wasmUrl?: string;
+}
+
+export type EngineEvent =
+  | { type: 'ready' }
+  | { type: 'error'; error: Error }
+  | { type: 'exit' }
+  | { type: 'frame'; fps: number };
+
+export interface EngineInstance {
+  /** Begin running. `load()` may auto-start; then this is a no-op. */
+  start(): void;
+  pause(): void;
+  resume(): void;
+  /** Reset to power-on. May throw if the engine cannot reset in-process. */
+  reset(): void;
+  /** Swap the active input preset/map at runtime. */
+  setInput(map: InputPreset | KeyMap): void;
+
+  // Capability-gated (see manifest.capabilities). Present only when supported.
+  saveState?(): Promise<Uint8Array>;
+  loadState?(data: Uint8Array): Promise<void>;
+  screenshot?(): Promise<Blob>;
+
+  /**
+   * Optional targeted purge of persisted runtime files for the active namespace.
+   * Engines that do not persist assets can omit this method.
+   */
+  purgeStorage?():
+    | { data: boolean; settings: boolean }
+    | Promise<{ data: boolean; settings: boolean }>;
+
+  /** Tear down: stop the loop, release listeners/DOM, free the instance. */
+  destroy(): void;
+}
+
+/** The default export shape every engine package must provide. */
+export interface EngineSDK {
+  manifest: EngineManifest;
+  load(config: EngineConfig): Promise<EngineInstance>;
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+// @wasm-gaming/engine-specs — the engine contract.
+//
+// Layer A (declarative): EngineManifest & friends — what an engine ships/needs.
+// Layer B (imperative):  EngineSDK / EngineInstance — how the host drives it.
+// Plus a runtime validator for the manifest.
+
+export type {
+  EngineManifest,
+  EngineArtifacts,
+  AssetSpec,
+  AssetValidation,
+  VideoSpec,
+  EngineCapabilities,
+  KeyMap,
+  InputPreset,
+  JSONSchema,
+} from './manifest.js';
+
+export type {
+  EngineSDK,
+  EngineInstance,
+  EngineConfig,
+  EngineEvent,
+  AssetData,
+  PersistMode,
+} from './engine.js';
+
+export { validateManifest, assertManifest } from './validate.js';
+export type { ValidationResult } from './validate.js';
+
+/** The contract version. Bump on breaking changes to the shapes above. */
+export const CONTRACT_VERSION = '0.1.1';

package/src/manifest.ts

@@ -0,0 +1,82 @@
+// Layer A — the declarative contract.
+//
+// An EngineManifest describes what an engine subproject ships and needs. It drives
+// the host's launcher UI, asset pickers and validation. Everything that differs
+// between engines (Data.rsdk vs a ROM zip + BIOS vs baked-in assets) is expressed
+// as *data* here, so the imperative interface (Layer B) can stay identical.
+
+/** A loose JSON Schema object (Draft 2020-12 subset). Kept dependency-free. */
+export type JSONSchema = Record<string, unknown>;
+
+/** A gamepad→keyboard key map, or the name of a built-in preset (e.g. "rsdkv4"). */
+export type KeyMap = Record<string, string>;
+export type InputPreset = string;
+
+/** How the host validates a user-provided asset before mounting it. */
+export interface AssetValidation {
+  /** Exact byte length, if the asset has a fixed size (e.g. a known ROM dump). */
+  bytes?: number;
+  /** Lowercase hex SHA-1 the asset must match. */
+  sha1?: string;
+}
+
+/** A file the host must supply at runtime, mounted into the engine's VFS. */
+export interface AssetSpec {
+  /** Stable key the host uses in `EngineConfig.assets` (e.g. "data", "rom", "bios"). */
+  key: string;
+  /** Absolute VFS path the engine reads from (e.g. "/Data.rsdk", "/roms/neogeo.zip"). */
+  mountPath: string;
+  /** If true, `load()` must reject when the asset is absent. */
+  required: boolean;
+  /** Suggested file extensions for a host file picker (e.g. [".rsdk"]). */
+  accept?: string[];
+  /** Integrity/shape constraints the host may enforce before mounting. */
+  validate?: AssetValidation;
+  /** Human-readable note shown in host UI. */
+  description?: string;
+}
+
+/** Where the CI-built artifacts live (relative paths or URLs; host resolves them). */
+export interface EngineArtifacts {
+  /** The `.wasm` binary. */
+  wasm: string;
+  /** The JS glue/loader (an ES module factory). */
+  js: string;
+  /** Optional preloaded Emscripten `.data` package (engines that bundle assets). */
+  data?: string;
+}
+
+/** Native render surface geometry. */
+export interface VideoSpec {
+  baseWidth: number;
+  baseHeight: number;
+  /** Display aspect ratio, e.g. "16:9" or "4:3". Defaults to baseWidth:baseHeight. */
+  aspect?: string;
+}
+
+/** Optional features an engine may or may not implement. Gate calls on these. */
+export interface EngineCapabilities {
+  saveStates?: boolean;
+  sram?: boolean;
+  /** Part of a swappable set of cores for one platform (e.g. Megadrive: JGenesis/BlastEm). */
+  coreSelectable?: boolean;
+}
+
+export interface EngineManifest {
+  /** Stable engine id, e.g. "rsdkv4" | "fbneo" | "blastem" | "jgenesis" | "smw". */
+  id: string;
+  /** SemVer of this engine build/contract implementation. */
+  version: string;
+  /** Human-readable name. */
+  name?: string;
+  description?: string;
+  artifacts: EngineArtifacts;
+  /** Files supplied at runtime. May be empty (e.g. engines with baked-in assets). */
+  assets: AssetSpec[];
+  /** Input preset name or an explicit key map. */
+  input: InputPreset | KeyMap;
+  video: VideoSpec;
+  /** JSON Schema for engine-specific `EngineConfig.options`. */
+  options?: JSONSchema;
+  capabilities: EngineCapabilities;
+}

package/src/validate.ts

@@ -0,0 +1,92 @@
+// Runtime validation of an EngineManifest against the contract.
+// Engine CIs can run this to fail a build that drifts from the spec; hosts can run
+// it on manifests fetched from Releases before trusting them.
+
+import { z } from 'zod';
+import type { EngineManifest } from './manifest.js';
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+const AssetValidationSchema = z.object({
+  bytes: z.int().nonnegative().optional(),
+  sha1: z.string().optional(),
+}).strict();
+
+const AssetSpecSchema = z.object({
+  key: z.string().min(1),
+  mountPath: z.string().regex(/^\//),
+  required: z.boolean(),
+  accept: z.array(z.string()).optional(),
+  validate: AssetValidationSchema.optional(),
+  description: z.string().optional(),
+}).strict();
+
+const InputSchema = z.union([
+  z.string(),
+  z.record(z.string(), z.string()),
+]);
+
+const VideoSpecSchema = z.object({
+  baseWidth: z.int().positive(),
+  baseHeight: z.int().positive(),
+  aspect: z.string().optional(),
+}).strict();
+
+const EngineArtifactsSchema = z.object({
+  wasm: z.string(),
+  js: z.string(),
+  data: z.string().optional(),
+}).strict();
+
+const EngineCapabilitiesSchema = z.object({
+  saveStates: z.boolean().optional(),
+  sram: z.boolean().optional(),
+  coreSelectable: z.boolean().optional(),
+}).strict();
+
+const EngineManifestSchema = z.object({
+  id: z.string().min(1),
+  version: z.string().min(1),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  artifacts: EngineArtifactsSchema,
+  assets: z.array(AssetSpecSchema),
+  input: InputSchema,
+  video: VideoSpecSchema,
+  options: z.record(z.string(), z.unknown()).optional(),
+  capabilities: EngineCapabilitiesSchema,
+}).strict();
+
+function formatIssuePath(path: PropertyKey[]): string {
+  if (path.length === 0) return 'manifest';
+
+  let out = 'manifest';
+  for (const part of path) {
+    if (typeof part === 'number') out += `[${part}]`;
+    else if (typeof part === 'string') out += `.${part}`;
+    else out += '.[symbol]';
+  }
+  return out;
+}
+
+/** Validate an unknown value as an EngineManifest. Never throws. */
+export function validateManifest(input: unknown): ValidationResult {
+  const result = EngineManifestSchema.safeParse(input);
+  if (result.success) return { valid: true, errors: [] };
+
+  const errors = result.error.issues.map((issue) => `${formatIssuePath(issue.path)}: ${issue.message}`);
+  return { valid: false, errors };
+}
+
+/** Validate and throw on failure. Returns the value narrowed to EngineManifest. */
+export function assertManifest(input: unknown): EngineManifest {
+  const result = EngineManifestSchema.safeParse(input);
+  if (!result.success) {
+    const errors = result.error.issues.map((issue) => `${formatIssuePath(issue.path)}: ${issue.message}`);
+    throw new Error(`Invalid EngineManifest:\n- ${errors.join('\n- ')}`);
+  }
+  return result.data as EngineManifest;
+}