@wasm-gaming/engine-specs 0.2.2 → 0.2.3

package/demo/README.md

@@ -55,6 +55,10 @@ To apply your custom branding, override any of the `:root` variables in `demo.cs
   --demo-picker-bg: rgba(255, 255, 255, 0.1);
   --demo-picker-hover-bg: rgba(255, 255, 255, 0.2);
   --demo-picker-text: #ffffff;
+
+  /* Launch button */
+  --demo-launch-bg: var(--demo-accent);
+  --demo-launch-text: #ffffff;
 }
 ```
 
@@ -80,6 +84,8 @@ To apply your custom branding, override any of the `:root` variables in `demo.cs
 | `--demo-picker-bg` | Pick File button background | `rgba(255, 255, 255, 0.5)` |
 | `--demo-pill-bg` | Metadata badge background | `rgba(var(--demo-accent-rgb), 0.1)` |
 | `--demo-file-info-bg` | Canvas overlay panel background | `rgba(255, 255, 255, 0.7)` |
+| `--demo-launch-bg` | Launch button background color | `var(--demo-accent)` |
+| `--demo-launch-text` | Launch button text color | `#ffffff` |
 | `--demo-font-sans` | Primary sans-serif font family | `"Outfit", system-ui, sans-serif` |
 | `--demo-font-mono` | Monospace code font family | `"Space Mono", monospace` |
 
@@ -87,8 +93,10 @@ To apply your custom branding, override any of the `:root` variables in `demo.cs
 
 ## 🛠 Features
 
+- **OPFS Asset Persistence**: Automatically stores selected ROM and BIOS files in the Origin Private File System (`navigator.storage.getDirectory()`), restoring them automatically across page reloads.
+- **Split Asset Drop Zones**: Independent drop/picker areas for optional **BIOS** firmware and game **ROM** assets.
+- **Dedicated Launch Trigger**: Prominent launch button that activates once required game assets are selected.
 - **Automated Manifest Integration**: Page title, SDK info, asset key mapping, and file type (`accept`) filters are automatically loaded from `sdk.manifest`.
-- **ROM Drag & Drop**: Interactive drop zone with file picker fallback.
 - **Checksum Calculation**: Computes MD5, SHA-1, and SHA-256 hashes of loaded files asynchronously in the background.
 - **Shadow DOM Isolation**: UI components are isolated using Shadow DOM to prevent style leakage.
 - **Subpath Hosting Ready**: Uses `import.meta.url` for component templates to work seamlessly on subpaths (e.g. GitHub Pages).

package/demo/components/drop-area.html

@@ -0,0 +1,124 @@
+<section class="drop" :class.active="dragging" :class.selected="selectedName"
+    @dragover.prevent="dragging = true"
+    @dragleave="dragging = false"
+    @drop.prevent="onDrop">
+    <strong>{{ prompt }}</strong>
+    <p :class.file-selected="selectedName">{{ selectedName ? 'Selected: ' + selectedName : assetHint }}</p>
+    <label class="picker">
+        {{ selectedName ? 'Change File' : buttonText }}
+        <input type="file" :accept="accept" @change="onPick" />
+    </label>
+</section>
+
+<script :setup="{
+  prompt,
+  assetHint = 'or choose one from your computer',
+  accept,
+  buttonText = 'Pick file',
+  fileName = '',
+}">
+  let dragging = false;
+  let selectedName = fileName || "";
+
+  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 emitFile = (file) => {
+    if (!file) return;
+    selectedName = file.name;
+    $emit("select", file);
+  };
+
+  const onDrop = (event) => {
+    dragging = false;
+    const file = extractFile(event);
+    if (file) emitFile(file);
+  };
+
+  const onPick = (event) => {
+    const file = extractFile(event);
+    if (file) emitFile(file);
+  };
+</script>
+
+<style>
+    .drop {
+        border: 2px dashed var(--demo-drop-border, rgba(255, 255, 255, 0.6));
+        border-radius: var(--demo-subpanel-radius, 8px);
+        padding: 2rem 1.25rem;
+        text-align: center;
+        transition: all 250ms ease;
+        background: var(--demo-drop-bg, rgba(255, 255, 255, 0.15));
+        backdrop-filter: blur(var(--demo-subpanel-blur, 12px));
+        -webkit-backdrop-filter: blur(var(--demo-subpanel-blur, 12px));
+    }
+
+    .drop.active {
+        border-color: var(--demo-drop-active-border, var(--demo-accent2, #0284c7));
+        background: var(--demo-drop-active-bg, rgba(255, 255, 255, 0.4));
+        box-shadow: var(--demo-drop-active-shadow, inset 0 0 0 1px rgba(255, 255, 255, 0.8));
+    }
+
+    .drop.selected {
+        border-style: solid;
+        border-color: var(--demo-accent2, #0284c7);
+        background: var(--demo-subpanel-bg, rgba(255, 255, 255, 0.35));
+    }
+
+    .drop strong {
+        display: block;
+        margin-bottom: 0.5rem;
+        font-size: 1.1rem;
+        font-weight: 600;
+        text-transform: uppercase;
+        letter-spacing: 0.05em;
+        color: var(--demo-text, #0f172a);
+    }
+
+    .drop p {
+        margin: 0.2rem 0;
+        color: var(--demo-muted, #475569);
+        font-family: var(--demo-font-mono, monospace);
+        font-size: 0.85rem;
+        word-break: break-all;
+    }
+
+    .drop p.file-selected {
+        color: var(--demo-text, #0f172a);
+        font-weight: 600;
+    }
+
+    .picker {
+        display: inline-flex;
+        margin-top: 1rem;
+        background: var(--demo-picker-bg, rgba(255, 255, 255, 0.5));
+        color: var(--demo-picker-text, var(--demo-text, #0f172a));
+        border: 1px solid var(--demo-picker-border, rgba(255, 255, 255, 0.6));
+        border-radius: var(--demo-subpanel-radius, 8px);
+        padding: 0.5rem 1rem;
+        cursor: pointer;
+        text-transform: uppercase;
+        font-weight: 600;
+        font-size: 0.85rem;
+        letter-spacing: 0.05em;
+        transition: all 0.2s;
+        backdrop-filter: blur(var(--demo-subpanel-blur, 12px));
+        -webkit-backdrop-filter: blur(var(--demo-subpanel-blur, 12px));
+    }
+
+    .picker:hover {
+        background: var(--demo-picker-hover-bg, rgba(255, 255, 255, 0.8));
+        border-color: var(--demo-picker-hover-border, rgba(255, 255, 255, 0.9));
+        box-shadow: 0 4px 15px rgba(0, 0, 0, 0.05);
+    }
+
+    .picker input {
+        display: none;
+    }
+</style>

package/demo/components/launcher.html

@@ -1,53 +1,107 @@
-<form class="launcher">
+<form class="launcher" @submit.prevent="onLaunch">
   <section class="sdk">
     <CSdkInfo ...sdkInfo />
   </section>
-  <section class="drop" :class.active="dragging" @dragover.prevent="dragging = true" @dragleave="dragging = false"
-    @drop.prevent="onDrop">
-    <strong>Drop your ROM/asset file here</strong>
-    <p>{{ assetHint }}</p>
-    <label class="picker">
-      Pick file
-      <input type="file" :accept="accept" @change="onPick" />
-    </label>
-  </section>
+
+  <div class="drop-grid" :class.single="!showBIOS">
+    <CDropArea
+      :if="showBIOS"
+      :prompt="requiresBIOS ? 'Drop BIOS File (Required)' : 'Drop BIOS File (Optional)'"
+      :asset-hint="biosAssetHint"
+      :accept="biosAccept"
+      :button-text="'Pick BIOS'"
+      :file-name="biosFile?.name"
+      @select="onBiosSelect"
+    />
+    <CDropArea
+      :prompt="'Drop ROM File'"
+      :asset-hint="romAssetHint"
+      :accept="romAccept"
+      :button-text="'Pick ROM'"
+      :file-name="romFile?.name"
+      @select="onRomSelect"
+    />
+  </div>
+
+  <button type="submit" class="launch-btn" :disabled="!canLaunch">
+    Launch Engine
+  </button>
+
   <div class="status">{{ status }}</div>
 </form>
 
 <script :setup="{
   CSdkInfo,
+  CDropArea,
   sdkInfo,
-  onFile,
-  accept,
-  assetHint = 'or choose one from your computer',
+  onLaunchFiles,
+  onSaveBios,
+  onSaveRom,
+  initialRomFile = null,
+  initialBiosFile = null,
+  romAccept,
+  romAssetHint = 'or choose ROM file from computer',
+  biosAccept,
+  biosAssetHint = 'optional BIOS firmware file',
+  requiresBIOS = false,
+  showBIOS = true,
 }">
-  let status = "Ready";
-  let dragging = false;
+  let romFile = initialRomFile;
+  let biosFile = initialBiosFile;
 
-  const onFileList = async (files) => {
-    const file = files.item(0);
-    if (!file) {
-      return;
-    }
-    try {
-      status = `Loading ${file.name}...`;
-      await onFile(file);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      status = `Failed to load file: ${message}`;
+  let canLaunch = Boolean(romFile && (!requiresBIOS || biosFile));
+  let status = "";
+
+  const updateStatus = () => {
+    canLaunch = Boolean(romFile && (!requiresBIOS || biosFile));
+    if (requiresBIOS && !biosFile && !romFile) {
+      status = "Ready - Please select ROM and BIOS files to launch.";
+    } else if (requiresBIOS && !biosFile) {
+      status = "BIOS file is required to launch.";
+    } else if (!romFile) {
+      status = "Ready - Please select a ROM file to launch.";
+    } else {
+      status = `Ready to launch! (${romFile.name}${biosFile ? ' + BIOS' : ''})`;
     }
   };
 
-  const onDrop = async (event) => {
-    dragging = false;
-    if (event.dataTransfer?.files) {
-      await onFileList(event.dataTransfer.files);
-    }
+  updateStatus();
+
+  const extractFile = (arg) => {
+    if (!arg) return null;
+    if (arg instanceof File) return arg;
+    if (arg.detail instanceof File) return arg.detail;
+    if (arg.detail) return extractFile(arg.detail);
+    return null;
   };
 
-  const onPick = async (event) => {
-    if (event.target.files) {
-      await onFileList(event.target.files);
+  const onRomSelect = (arg) => {
+    const file = extractFile(arg);
+    if (!file) return;
+    romFile = file;
+    updateStatus();
+    onSaveRom?.(file);
+  };
+
+  const onBiosSelect = (arg) => {
+    const file = extractFile(arg);
+    if (!file) return;
+    biosFile = file;
+    updateStatus();
+    onSaveBios?.(file);
+  };
+
+  const onLaunch = async () => {
+    if (!canLaunch) {
+      updateStatus();
+      return;
+    }
+    try {
+      status = `Launching with ${romFile.name}...`;
+      await onLaunchFiles({ rom: romFile, bios: biosFile });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      status = `Failed to load engine: ${message}`;
     }
   };
 </script>
@@ -89,66 +143,47 @@
     box-shadow: var(--demo-subpanel-shadow, inset 0 0 0 1px rgba(255, 255, 255, 0.6));
   }
 
-  .drop {
-    border: 2px dashed var(--demo-drop-border, rgba(255, 255, 255, 0.6));
-    border-radius: var(--demo-subpanel-radius, 8px);
-    padding: 2.5rem 1.5rem;
-    text-align: center;
-    transition: all 250ms ease;
-    background: var(--demo-drop-bg, rgba(255, 255, 255, 0.15));
-    backdrop-filter: blur(var(--demo-subpanel-blur, 12px));
-    -webkit-backdrop-filter: blur(var(--demo-subpanel-blur, 12px));
+  .drop-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+    gap: 1rem;
   }
 
-  .drop.active {
-    border-color: var(--demo-drop-active-border, var(--demo-accent2, #0284c7));
-    background: var(--demo-drop-active-bg, rgba(255, 255, 255, 0.4));
-    box-shadow: var(--demo-drop-active-shadow, inset 0 0 0 1px rgba(255, 255, 255, 0.8));
+  .drop-grid.single {
+    grid-template-columns: 1fr;
   }
 
-  .drop strong {
-    display: block;
-    margin-bottom: 0.5rem;
-    font-size: 1.2rem;
-    font-weight: 600;
+  .launch-btn {
+    width: 100%;
+    padding: 0.9rem 1.5rem;
+    font-size: 1.1rem;
+    font-weight: 700;
+    font-family: var(--demo-font-sans, sans-serif);
     text-transform: uppercase;
-    letter-spacing: 0.05em;
-    color: var(--demo-text, #0f172a);
-  }
-
-  .drop p {
-    margin: 0.2rem 0;
-    color: var(--demo-muted, #475569);
-    font-family: var(--demo-font-mono, monospace);
-    font-size: 0.9rem;
-  }
-
-  .picker {
-    display: inline-flex;
-    margin-top: 1.2rem;
-    background: var(--demo-picker-bg, rgba(255, 255, 255, 0.5));
-    color: var(--demo-picker-text, var(--demo-text, #0f172a));
-    border: 1px solid var(--demo-picker-border, rgba(255, 255, 255, 0.6));
+    letter-spacing: 0.08em;
+    color: var(--demo-launch-text, #ffffff);
+    background: var(--demo-launch-bg, var(--demo-accent, #ff007f));
+    border: none;
     border-radius: var(--demo-subpanel-radius, 8px);
-    padding: 0.6rem 1.2rem;
     cursor: pointer;
-    text-transform: uppercase;
-    font-weight: 600;
-    font-size: 0.9rem;
-    letter-spacing: 0.05em;
-    transition: all 0.2s;
-    backdrop-filter: blur(var(--demo-subpanel-blur, 12px));
-    -webkit-backdrop-filter: blur(var(--demo-subpanel-blur, 12px));
+    transition: all 0.2s ease;
+    box-shadow: var(--demo-accent-glow, 0 0 15px rgba(255, 0, 127, 0.3));
+  }
+
+  .launch-btn:hover:not(:disabled) {
+    filter: brightness(1.1);
+    transform: translateY(-1px);
   }
 
-  .picker:hover {
-    background: var(--demo-picker-hover-bg, rgba(255, 255, 255, 0.8));
-    border-color: var(--demo-picker-hover-border, rgba(255, 255, 255, 0.9));
-    box-shadow: 0 4px 15px rgba(0, 0, 0, 0.05);
+  .launch-btn:active:not(:disabled) {
+    transform: translateY(0);
   }
 
-  .picker input {
-    display: none;
+  .launch-btn:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+    box-shadow: none;
+    background: var(--demo-muted, #475569);
   }
 
   .status {

package/demo/demo.js

@@ -1,13 +1,20 @@
 import { getSdk } from "./sdk.js";
 import { checksumAlgorithms, computeChecksums } from "./checksums.js";
+import { loadStoredAsset, saveStoredAsset } from "./storage.js";
 import { $, $create, Component79 } from "https://jgermade.github.io/jq79/jq79.js";
 
+// Safe URL parameter resolution from script URL & page URL
+const pageUrl = new URL(location.href);
+const scriptUrl = new URL(import.meta.url, location.href);
+const biosParam = scriptUrl.searchParams.get("bios") ?? pageUrl.searchParams.get("bios");
+
 // Fetch component HTML templates using import.meta.url for resilient subpath resolution
 const fetchComponent = (path) => Component79.fetch(new URL(path, import.meta.url).href);
 
 // Fetch all components at once to leverage http2 request multiplexing.
-const [CLauncher, CSdkInfo, CFileInfo] = await Promise.all([
+const [CLauncher, CDropArea, CSdkInfo, CFileInfo] = await Promise.all([
   fetchComponent("./components/launcher.html"),
+  fetchComponent("./components/drop-area.html"),
   fetchComponent("./components/sdk-info.html"),
   fetchComponent("./components/file-info.html"),
 ]);
@@ -23,15 +30,39 @@ if (sdk.manifest?.name) {
   document.title = `${sdk.manifest.name} - Demo`;
 }
 
-// Compute asset accept filter and hint text from manifest
-const acceptedExts = sdk.manifest?.assets?.flatMap((a) => a.accept ?? []) ?? [];
-const acceptAttr = acceptedExts.length > 0 ? acceptedExts.join(",") : undefined;
-const assetHint = acceptedExts.length > 0
-  ? `Supported files: ${acceptedExts.join(", ")}`
-  : "or choose one from your computer";
+// Compute asset accept filters and hints from manifest
+const romSpec = sdk.manifest?.assets?.find((a) => a.key === "rom") ?? sdk.manifest?.assets?.[0];
+const biosSpec = sdk.manifest?.assets?.find((a) => a.key === "bios") ?? sdk.manifest?.assets?.[1];
+
+// Determine BIOS visibility and requirement rules
+const hasBiosSpec = Boolean(biosSpec);
+const showBIOS = biosParam !== "false" && (hasBiosSpec || biosParam === "required" || biosParam === "true" || biosParam === "optional");
+const requiresBIOS = biosParam === "required" || (biosParam !== "optional" && Boolean(biosSpec?.required));
+
+// Load previously stored ROM & BIOS from OPFS if available
+const [storedRom, storedBios] = await Promise.all([
+  loadStoredAsset("rom"),
+  showBIOS ? loadStoredAsset("bios") : null,
+]);
+
+const romAccept = romSpec?.accept?.join(",");
+const romAssetHint = romSpec?.accept ? `Supported: ${romSpec.accept.join(", ")}` : "or choose ROM file from computer";
 
-const bootWithFile = async (file) => {
-  const bytes = await file.arrayBuffer();
+const biosAccept = biosSpec?.accept?.join(",");
+const biosAssetHint = biosSpec?.description ?? (biosSpec?.accept ? `Supported: ${biosSpec.accept.join(", ")}` : (requiresBIOS ? "required BIOS firmware file" : "optional BIOS firmware file"));
+
+async function toArrayBuffer(input) {
+  if (!input) return null;
+  if (input instanceof ArrayBuffer) return input;
+  if (ArrayBuffer.isView(input)) return input.buffer;
+  if (typeof input.arrayBuffer === "function") return await input.arrayBuffer();
+  if (input.detail) return await toArrayBuffer(input.detail);
+  throw new TypeError("Provided input is not a File, Blob, or ArrayBuffer.");
+}
+
+const bootWithFiles = async ({ rom, bios }) => {
+  const romBytes = await toArrayBuffer(rom);
+  const biosBytes = await toArrayBuffer(bios);
 
   mainEl.classList.add("running");
 
@@ -43,9 +74,10 @@ const bootWithFile = async (file) => {
 
   mainEl.replaceChildren(runtimeEl);
 
+  const primaryFile = rom || bios;
   const fileInfoProps = {
-    fileName: file.name,
-    size: `${bytes.byteLength.toLocaleString()} bytes`,
+    fileName: primaryFile.name,
+    size: `${primaryFile.size.toLocaleString()} bytes`,
   };
   const fileInfoPlaceholder = CFileInfo
     .renderShadow({
@@ -54,15 +86,23 @@ const bootWithFile = async (file) => {
     })
     .mount(fileInfoEl);
 
-  const assetKey = sdk.manifest?.assets?.[0]?.key ?? "rom";
+  const assets = {};
+  if (romBytes && romSpec) {
+    assets[romSpec.key] = romBytes;
+  }
+  if (biosBytes && biosSpec) {
+    assets[biosSpec.key] = biosBytes;
+  }
+  if (Object.keys(assets).length === 0 && romBytes) {
+    assets.rom = romBytes;
+  }
+
   const instance = await sdk.load({
     attachTo: runtimeEl,
-    assets: {
-      [assetKey]: bytes,
-    },
+    assets,
     options: {
-      fileName: file.name,
-      byteLength: bytes.byteLength,
+      fileName: primaryFile.name,
+      byteLength: primaryFile.size,
     },
     onEvent(event) {
       if (event.type === "error") {
@@ -73,7 +113,7 @@ const bootWithFile = async (file) => {
 
   instance.start();
 
-  const checksums = await computeChecksums(bytes);
+  const checksums = await computeChecksums(romBytes || biosBytes);
   fileInfoPlaceholder.destroy();
 
   CFileInfo
@@ -84,6 +124,7 @@ const bootWithFile = async (file) => {
 CLauncher
   .render({
     CSdkInfo,
+    CDropArea,
     sdkInfo: {
       name: sdk.manifest.name,
       id: sdk.manifest.id,
@@ -91,10 +132,18 @@ CLauncher
       version: sdk.manifest.version,
       baseWidth: sdk.manifest.video?.baseWidth ?? 320,
       baseHeight: sdk.manifest.video?.baseHeight ?? 240,
-      assetKey: sdk.manifest.assets?.[0]?.key ?? "rom",
+      assetKey: romSpec?.key ?? "rom",
     },
-    onFile: bootWithFile,
-    accept: acceptAttr,
-    assetHint,
+    initialRomFile: storedRom,
+    initialBiosFile: storedBios,
+    onSaveRom: (file) => saveStoredAsset("rom", file),
+    onSaveBios: (file) => saveStoredAsset("bios", file),
+    onLaunchFiles: bootWithFiles,
+    romAccept,
+    romAssetHint,
+    biosAccept,
+    biosAssetHint,
+    requiresBIOS,
+    showBIOS,
   })
   .mount(mainEl);

package/demo/demo.sdk.js

@@ -14,7 +14,14 @@ export function createDummySdk() {
 				mountPath: "/rom.bin",
 				required: true,
 				accept: [".rom", ".bin", ".zip", ".dat"],
-				description: "Any file works in this demo; data is not executed.",
+				description: "Any game ROM file works in this demo.",
+			},
+			{
+				key: "bios",
+				mountPath: "/bios.bin",
+				required: false,
+				accept: [".bin", ".rom", ".sys"],
+				description: "Optional system BIOS firmware file.",
 			},
 		],
 		input: "keyboard-default",
@@ -45,6 +52,19 @@ export function createDummySdk() {
 				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();
@@ -90,7 +110,6 @@ export function createDummySdk() {
 				}
 
 				// Dark background inside the canvas to contrast with the light UI components
-				// ctx.fillStyle = "#0f172a";
 				ctx.fillStyle = "#060910ff";
 				ctx.fillRect(0, 0, width, height);
 
@@ -100,18 +119,15 @@ export function createDummySdk() {
 				for (let x = 0; x < drops.length; x++) {
 					let drop = drops[x];
 
-					// Change characters dynamically
 					if (Math.random() > 0.4) {
 						let randIdx = Math.floor(Math.random() * drop.chars.length);
 						drop.chars[randIdx] = String.fromCharCode(0x30A0 + Math.random() * 96);
 					}
 
-					// Move the drop (slower)
 					drop.y += drop.speed * (dt * 12);
 
 					let startY = Math.floor(drop.y);
 
-					// Draw the column
 					for (let i = 0; i < drop.length; i++) {
 						let charY = startY - i;
 						if (charY < 0 || charY >= maxRows) continue;
@@ -120,10 +136,8 @@ export function createDummySdk() {
 						let alpha = drop.opacity * (1 - (i / drop.length));
 
 						if (i === 0) {
-							// Head of the drop (bright cyan-white)
 							ctx.fillStyle = `rgba(220, 255, 255, ${drop.opacity})`;
 						} else {
-							// Tail of the drop (bright colors for dark background)
 							const hue = ((time / 15) + (x * 10)) % 360;
 							ctx.fillStyle = `hsla(${hue}, 80%, 65%, ${alpha})`;
 						}
@@ -131,7 +145,6 @@ export function createDummySdk() {
 						ctx.fillText(text, x * fontSize + fontSize / 2, charY * fontSize);
 					}
 
-					// Reset drop when fully off-screen
 					if ((drop.y - drop.length) * fontSize > height) {
 						drop.y = 0;
 						drop.speed = Math.random() * 1.5 + 0.5;

package/demo/storage.js

@@ -0,0 +1,88 @@
+/**
+ * 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/package.json

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