@wasm-gaming/engine-specs 0.2.6 → 0.3.0

package/demo/storage.js

@@ -1,88 +0,0 @@
-/**
- * OPFS Asset Storage Helper for Engine Demo
- * Persists ROM and BIOS files in the Origin Private File System (OPFS) across page reloads.
- */
-
-const DIR_NAME = "wasm-gaming-demo";
-
-async function getStorageDir() {
-  if (typeof navigator === "undefined" || !navigator.storage?.getDirectory) {
-    return null;
-  }
-  try {
-    const root = await navigator.storage.getDirectory();
-    return await root.getDirectoryHandle(DIR_NAME, { create: true });
-  } catch (err) {
-    console.warn("OPFS storage not accessible:", err);
-    return null;
-  }
-}
-
-/**
- * Save an asset File into OPFS.
- */
-export async function saveStoredAsset(key, file) {
-  const dir = await getStorageDir();
-  if (!dir || !file) return;
-  try {
-    const fileHandle = await dir.getFileHandle(`${key}.bin`, { create: true });
-    const writable = await fileHandle.createWritable();
-    const bytes = await file.arrayBuffer();
-    await writable.write(bytes);
-    await writable.close();
-
-    // Store file metadata
-    const metaHandle = await dir.getFileHandle(`${key}.json`, { create: true });
-    const metaWritable = await metaHandle.createWritable();
-    await metaWritable.write(
-      JSON.stringify({
-        name: file.name,
-        size: file.size || bytes.byteLength,
-        type: file.type || "application/octet-stream",
-        lastModified: file.lastModified || Date.now(),
-      })
-    );
-    await metaWritable.close();
-  } catch (err) {
-    console.warn(`Failed to save ${key} in OPFS:`, err);
-  }
-}
-
-/**
- * Retrieve a stored asset File from OPFS.
- */
-export async function loadStoredAsset(key) {
-  const dir = await getStorageDir();
-  if (!dir) return null;
-  try {
-    const fileHandle = await dir.getFileHandle(`${key}.bin`);
-    const metaHandle = await dir.getFileHandle(`${key}.json`);
-
-    const fileObj = await fileHandle.getFile();
-    const metaText = await (await metaHandle.getFile()).text();
-    const meta = JSON.parse(metaText);
-
-    const bytes = await fileObj.arrayBuffer();
-    return new File([bytes], meta.name, {
-      type: meta.type,
-      lastModified: meta.lastModified,
-    });
-  } catch {
-    // File or meta doesn't exist yet
-    return null;
-  }
-}
-
-/**
- * Clear a stored asset from OPFS.
- */
-export async function clearStoredAsset(key) {
-  const dir = await getStorageDir();
-  if (!dir) return;
-  try {
-    await dir.removeEntry(`${key}.bin`);
-  } catch {}
-  try {
-    await dir.removeEntry(`${key}.json`);
-  } catch {}
-}

package/dist/engine.d.ts

@@ -1,78 +0,0 @@
-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;
-type EngineConfigBase = {
-    /** 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 EngineConfig = EngineConfigBase & ({
-    /** Render target. The SDK is responsible for the `#canvas` id if the engine needs it. */
-    canvasEl: HTMLCanvasElement;
-    /** Optional container element for SDK-owned DOM when a canvas element is present. */
-    attachTo?: HTMLElement;
-} | {
-    /** Optional render target when the SDK primarily mounts into a container element. */
-    canvasEl?: HTMLCanvasElement;
-    /** Container element the SDK can use to mount engine-owned DOM. */
-    attachTo: HTMLElement;
-});
-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>;
-}
-export {};
-//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -1 +0,0 @@
-{"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,KAAK,gBAAgB,GAAG;IACtB,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,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,gBAAgB,GACzC,CACI;IACE,yFAAyF;IACzF,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,qFAAqF;IACrF,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB,GACD;IACE,qFAAqF;IACrF,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,EAAE,WAAW,CAAC;CACvB,CACJ,CAAC;AAEJ,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

@@ -1,8 +0,0 @@
-// 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

@@ -1 +0,0 @@
-{"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

@@ -1,7 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,9 +0,0 @@
-// @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

@@ -1 +0,0 @@
-{"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

@@ -1,69 +0,0 @@
-/** 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

@@ -1 +0,0 @@
-{"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

@@ -1,8 +0,0 @@
-// 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

@@ -1 +0,0 @@
-{"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

@@ -1,10 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,79 +0,0 @@
-// 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

@@ -1 +0,0 @@
-{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/schema/engine-manifest.schema.json

@@ -1,74 +0,0 @@
-{
-  "$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

@@ -1,88 +0,0 @@
-// 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;
-
-type EngineConfigBase = {
-  /** 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 EngineConfig = EngineConfigBase &
-  (
-    | {
-        /** Render target. The SDK is responsible for the `#canvas` id if the engine needs it. */
-        canvasEl: HTMLCanvasElement;
-        /** Optional container element for SDK-owned DOM when a canvas element is present. */
-        attachTo?: HTMLElement;
-      }
-    | {
-        /** Optional render target when the SDK primarily mounts into a container element. */
-        canvasEl?: HTMLCanvasElement;
-        /** Container element the SDK can use to mount engine-owned DOM. */
-        attachTo: HTMLElement;
-      }
-  );
-
-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

@@ -1,32 +0,0 @@
-// @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';