@wasm-gaming/engine-specs 0.1.9 → 0.2.1

package/README.md

@@ -23,6 +23,10 @@ Every engine package default-exports an `EngineSDK` = `{ manifest, load }`.
 (`start`/`pause`/`resume`/`reset`/`setInput`/`destroy`, plus capability-gated
 `saveState`/`loadState`/`screenshot`).
 
+`EngineConfig` requires at least one render mount target: `canvasEl`, `attachTo`,
+or both. `attachTo` is the host container element where an SDK can mount
+engine-owned DOM.
+
 `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

package/dist/engine.d.ts

@@ -3,9 +3,7 @@ import type { EngineManifest, KeyMap, InputPreset } from './manifest.js';
 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;
+type EngineConfigBase = {
     /** Runtime files keyed by `AssetSpec.key`. Required specs must be present. */
     assets: Record<string, AssetData>;
     /** Engine-specific settings, validated against `manifest.options`. */
@@ -22,7 +20,18 @@ export interface EngineConfig {
     /** 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';
 } | {
@@ -65,4 +74,5 @@ export interface EngineSDK {
     manifest: EngineManifest;
     load(config: EngineConfig): Promise<EngineInstance>;
 }
+export {};
 //# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -1 +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"}
+{"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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wasm-gaming/engine-specs",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "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",

package/src/engine.ts

@@ -13,9 +13,7 @@ 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;
+type EngineConfigBase = {
   /** Runtime files keyed by `AssetSpec.key`. Required specs must be present. */
   assets: Record<string, AssetData>;
   /** Engine-specific settings, validated against `manifest.options`. */
@@ -32,7 +30,23 @@ export interface EngineConfig {
   /** 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' }