@wasm-gaming/engine-specs 0.2.1 → 0.2.3

package/demo/README.md

@@ -0,0 +1,102 @@
+# Themable Engine Demo Template
+
+This directory contains a standalone, themable web interface template for hosting interactive WASM gaming engine demos.
+
+## 🚀 How to use in another engine repository
+
+1. **Copy the `demo/` folder** into your engine repository.
+
+2. **Connect your engine SDK in `demo/sdk.js`**:
+   Open `demo/sdk.js` and point it to your engine SDK build:
+   ```javascript
+   import sdk from "../src/index.js"; // or "../dist/index.js"
+
+   export async function getSdk() {
+     return sdk;
+   }
+   ```
+   *Alternatively*, if embedding in HTML without modifying `sdk.js`, set `window.SDK = myEngineSdk;` before `demo.js` runs.
+
+3. **Serve the demo**:
+   Serve `demo/index.html` using any local development server (e.g. `npx serve demo` or Vite).
+
+---
+
+## 🎨 Customizing & Theming
+
+The demo visual design system is fully controlled via **CSS Custom Properties** defined in `demo.css`.
+
+### Overriding CSS Variables
+
+To apply your custom branding, override any of the `:root` variables in `demo.css` or in your own custom stylesheet:
+
+```css
+:root {
+  /* Brand colors */
+  --demo-bg-a: #1e1b4b;
+  --demo-bg-b: #0f172a;
+  --demo-text: #f8fafc;
+  --demo-muted: #94a3b8;
+
+  /* Accent highlights */
+  --demo-accent: #00ffcc;
+  --demo-accent-rgb: 0, 255, 204;
+  --demo-accent2: #38bdf8;
+  --demo-accent2-rgb: 56, 189, 248;
+
+  /* Glassmorphism panels */
+  --demo-panel-bg: rgba(15, 23, 42, 0.75);
+  --demo-panel-border: rgba(255, 255, 255, 0.1);
+  --demo-subpanel-bg: rgba(30, 41, 59, 0.6);
+  --demo-subpanel-border: rgba(255, 255, 255, 0.1);
+
+  /* Buttons & Dropzone */
+  --demo-drop-bg: rgba(30, 41, 59, 0.4);
+  --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;
+}
+```
+
+### Full Token Reference
+
+| Variable | Description | Default |
+|---|---|---|
+| `--demo-bg-a` | Gradient background stop 1 | `#d8b4fe` |
+| `--demo-bg-b` | Gradient background stop 2 | `#7dd3fc` |
+| `--demo-text` | Primary text color | `#0f172a` |
+| `--demo-muted` | Secondary/muted text color | `#475569` |
+| `--demo-accent` | Primary accent color | `#ff007f` |
+| `--demo-accent-rgb` | Primary accent RGB channels | `255, 0, 127` |
+| `--demo-accent2` | Secondary accent color | `#0284c7` |
+| `--demo-accent2-rgb` | Secondary accent RGB channels | `2, 132, 199` |
+| `--demo-panel-bg` | Main card/launcher background | `rgba(255, 255, 255, 0.25)` |
+| `--demo-panel-border` | Main card border color | `rgba(255, 255, 255, 0.4)` |
+| `--demo-panel-radius` | Main card corner rounding | `12px` |
+| `--demo-panel-blur` | Backdrop glass blur effect | `24px` |
+| `--demo-subpanel-bg` | Inner info section background | `rgba(255, 255, 255, 0.35)` |
+| `--demo-drop-bg` | Dropzone background | `rgba(255, 255, 255, 0.15)` |
+| `--demo-drop-active-bg` | Drag-over active background | `rgba(255, 255, 255, 0.4)` |
+| `--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` |
+
+---
+
+## 🛠 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`.
+- **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/checksums.js

@@ -0,0 +1,101 @@
+const CRC_TABLE = Uint32Array.from({ length: 256 }, (_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k += 1) {
+    c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  }
+  return c >>> 0;
+});
+
+const crc32 = (bytes) => {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+  }
+  return ((crc ^ 0xffffffff) >>> 0).toString(16).padStart(8, "0");
+};
+
+const toHex = (buffer) =>
+  Array.from(new Uint8Array(buffer), (byte) => byte.toString(16).padStart(2, "0")).join("");
+
+// RFC 1321. Hand-rolled because crypto.subtle does not offer MD5.
+const MD5_K = Uint32Array.from({ length: 64 }, (_, i) =>
+  Math.floor(Math.abs(Math.sin(i + 1)) * 2 ** 32));
+
+const MD5_S = [
+  7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22,
+  5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20,
+  4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23,
+  6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21,
+];
+
+const md5 = (bytes) => {
+  const paddedLength = (((bytes.length + 8) >> 6) + 1) << 6;
+  const padded = new Uint8Array(paddedLength);
+  padded.set(bytes);
+  padded[bytes.length] = 0x80;
+  const view = new DataView(padded.buffer);
+  view.setUint32(paddedLength - 8, (bytes.length * 8) >>> 0, true);
+  view.setUint32(paddedLength - 4, Math.floor(bytes.length / 0x20000000), true);
+
+  let [h0, h1, h2, h3] = [0x67452301, 0xefcdab89, 0x98badcfe, 0x10325476];
+  const words = new Uint32Array(16);
+
+  for (let offset = 0; offset < paddedLength; offset += 64) {
+    for (let j = 0; j < 16; j += 1) {
+      words[j] = view.getUint32(offset + j * 4, true);
+    }
+    let [a, b, c, d] = [h0, h1, h2, h3];
+    for (let i = 0; i < 64; i += 1) {
+      let f;
+      let g;
+      if (i < 16) {
+        f = (b & c) | (~b & d);
+        g = i;
+      } else if (i < 32) {
+        f = (d & b) | (~d & c);
+        g = (5 * i + 1) % 16;
+      } else if (i < 48) {
+        f = b ^ c ^ d;
+        g = (3 * i + 5) % 16;
+      } else {
+        f = c ^ (b | ~d);
+        g = (7 * i) % 16;
+      }
+      const sum = (a + f + MD5_K[i] + words[g]) >>> 0;
+      const rotated = (sum << MD5_S[i]) | (sum >>> (32 - MD5_S[i]));
+      [a, b, c, d] = [d, (b + rotated) >>> 0, b, c];
+    }
+    h0 = (h0 + a) >>> 0;
+    h1 = (h1 + b) >>> 0;
+    h2 = (h2 + c) >>> 0;
+    h3 = (h3 + d) >>> 0;
+  }
+
+  const digest = new DataView(new ArrayBuffer(16));
+  digest.setUint32(0, h0, true);
+  digest.setUint32(4, h1, true);
+  digest.setUint32(8, h2, true);
+  digest.setUint32(12, h3, true);
+  return toHex(digest.buffer);
+};
+
+const sha = async (algorithm, buffer) => {
+  // crypto.subtle only exists in secure contexts (https or localhost).
+  if (!globalThis.crypto?.subtle) {
+    return "unavailable (requires a secure context)";
+  }
+  return toHex(await crypto.subtle.digest(algorithm, buffer));
+};
+
+export const checksumAlgorithms = ["CRC32", "MD5", "SHA-1", "SHA-256"];
+
+export async function computeChecksums(buffer) {
+  const bytes = new Uint8Array(buffer);
+  const [sha1, sha256] = await Promise.all([sha("SHA-1", buffer), sha("SHA-256", buffer)]);
+  return [
+    { label: "CRC32", value: crc32(bytes) },
+    { label: "MD5", value: md5(bytes) },
+    { label: "SHA-1", value: sha1 },
+    { label: "SHA-256", value: sha256 },
+  ];
+}

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/file-info.html

@@ -0,0 +1,66 @@
+<h2>{{ fileName }}</h2>
+<dl>
+  <div class="row">
+    <dt>Size</dt>
+    <dd>{{ size }}</dd>
+  </div>
+  <div :each="checksum in checksums" class="row">
+    <dt>{{ checksum.label }}</dt>
+    <dd>{{ checksum.value }}</dd>
+  </div>
+</dl>
+
+<style>
+  :host {
+    position: absolute;
+    top: 4rem;
+    left: 2rem;
+    max-width: min(600px, calc(100vw - 2rem));
+    border: 1px solid var(--demo-file-info-border, rgba(255, 255, 255, 0.8));
+    border-radius: var(--demo-panel-radius, 12px);
+    background: var(--demo-file-info-bg, rgba(255, 255, 255, 0.7));
+    backdrop-filter: blur(var(--demo-file-info-blur, 10px));
+    padding: 1.2rem;
+    font-size: 0.9rem;
+  }
+
+  h2 {
+    margin: 0 0 0.8rem;
+    font-size: 1.1rem;
+    font-weight: 600;
+    word-break: break-all;
+    color: var(--demo-text, var(--text, #0f172a));
+    letter-spacing: 0.05em;
+    border-bottom: 1px solid var(--demo-panel-border, rgba(255, 255, 255, 0.6));
+    padding-bottom: 0.4rem;
+  }
+
+  dl {
+    margin: 0;
+    display: grid;
+    gap: 0.5rem;
+  }
+
+  .row {
+    display: grid;
+    grid-template-columns: 4.4rem 1fr;
+    gap: 0.8rem;
+    align-items: baseline;
+  }
+
+  dt {
+    color: var(--demo-text, var(--text, #0f172a));
+    opacity: 0.7;
+    font-size: 0.8rem;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+  }
+
+  dd {
+    margin: 0;
+    font-family: var(--demo-font-mono, var(--font-mono, monospace));
+    word-break: break-all;
+    user-select: all;
+    color: var(--demo-text, var(--text, #0f172a));
+  }
+</style>

package/demo/components/launcher.html

@@ -0,0 +1,198 @@
+<form class="launcher" @submit.prevent="onLaunch">
+  <section class="sdk">
+    <CSdkInfo ...sdkInfo />
+  </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,
+  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 romFile = initialRomFile;
+  let biosFile = initialBiosFile;
+
+  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' : ''})`;
+    }
+  };
+
+  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 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>
+
+<style>
+  form.launcher {
+    width: min(740px, 100%);
+    border: 1px solid var(--demo-panel-border, rgba(255, 255, 255, 0.4));
+    border-radius: var(--demo-panel-radius, 12px);
+    background: var(--demo-panel-bg, rgba(255, 255, 255, 0.25));
+    box-shadow: var(--demo-panel-shadow, inset 0 0 0 1px rgba(255, 255, 255, 0.5));
+    backdrop-filter: blur(var(--demo-panel-blur, 24px));
+    -webkit-backdrop-filter: blur(var(--demo-panel-blur, 24px));
+    padding: 1.5rem;
+    display: grid;
+    gap: 1.25rem;
+    position: relative;
+    overflow: hidden;
+  }
+
+  form.launcher::before {
+    content: "";
+    position: absolute;
+    top: 0;
+    right: 0;
+    width: 60px;
+    height: 60px;
+    background: linear-gradient(135deg, transparent 50%, var(--demo-accent, #ff007f) 50%);
+    opacity: 0.8;
+  }
+
+  .sdk {
+    border: 1px solid var(--demo-subpanel-border, rgba(255, 255, 255, 0.3));
+    border-radius: var(--demo-subpanel-radius, 8px);
+    padding: 1.25rem;
+    background: var(--demo-subpanel-bg, rgba(255, 255, 255, 0.35));
+    backdrop-filter: blur(var(--demo-subpanel-blur, 12px));
+    -webkit-backdrop-filter: blur(var(--demo-subpanel-blur, 12px));
+    box-shadow: var(--demo-subpanel-shadow, inset 0 0 0 1px rgba(255, 255, 255, 0.6));
+  }
+
+  .drop-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+    gap: 1rem;
+  }
+
+  .drop-grid.single {
+    grid-template-columns: 1fr;
+  }
+
+  .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.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);
+    cursor: pointer;
+    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);
+  }
+
+  .launch-btn:active:not(:disabled) {
+    transform: translateY(0);
+  }
+
+  .launch-btn:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+    box-shadow: none;
+    background: var(--demo-muted, #475569);
+  }
+
+  .status {
+    min-height: 1.2rem;
+    color: var(--demo-text, #0f172a);
+    font-family: var(--demo-font-mono, monospace);
+    font-size: 0.85rem;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    opacity: 0.8;
+  }
+</style>

package/demo/components/sdk-info.html

@@ -0,0 +1,42 @@
+<h1>{{ name }} ({{ id }})</h1>
+<p>{{ description }}</p>
+<div class="row">
+  <span class="pill">Version {{ version }}</span>
+  <span class="pill">{{ baseWidth }}x{{ baseHeight }}</span>
+  <span class="pill">Asset key: {{ assetKey }}</span>
+</div>
+
+<style>
+  h1 {
+    margin: 0 0 0.4rem;
+    font-size: 1.4rem;
+    font-weight: 800;
+    color: var(--demo-text, var(--text, #0f172a));
+    letter-spacing: 0.05em;
+  }
+
+  p {
+    margin: 0;
+    color: var(--demo-muted, var(--muted, #475569));
+    font-size: 0.95rem;
+  }
+
+  .row {
+    margin-top: 0.9rem;
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.6rem;
+  }
+
+  .pill {
+    border: 1px solid var(--demo-pill-border, var(--demo-accent, var(--accent, #ff007f)));
+    border-radius: 2px;
+    padding: 0.3rem 0.75rem;
+    font-family: var(--demo-font-mono, var(--font-mono, monospace));
+    font-size: 0.8rem;
+    color: var(--demo-pill-text, var(--demo-accent, var(--accent, #ff007f)));
+    background: var(--demo-pill-bg, rgba(255, 0, 127, 0.1));
+    box-shadow: var(--demo-pill-shadow, inset 0 0 5px rgba(255, 0, 127, 0.3));
+    text-transform: uppercase;
+  }
+</style>

package/demo/demo.css

@@ -0,0 +1,137 @@
+@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;600;800&family=Space+Mono:ital,wght@0,400;0,700;1,400&display=swap');
+
+:root {
+  /* Colors & Palette */
+  --demo-bg-a: #d8b4fe;
+  --demo-bg-b: #7dd3fc;
+  --demo-bg-gradient: linear-gradient(145deg, var(--demo-bg-a) 0%, var(--demo-bg-b) 100%);
+  --demo-bg-radial-1: rgba(255, 0, 127, 0.08);
+  --demo-bg-radial-2: rgba(2, 132, 199, 0.12);
+
+  --demo-text: #0f172a;
+  --demo-muted: #475569;
+
+  --demo-accent: #ff007f;
+  --demo-accent-rgb: 255, 0, 127;
+  --demo-accent-glow: 0 0 15px rgba(var(--demo-accent-rgb), 0.3), 0 0 30px rgba(var(--demo-accent-rgb), 0.15);
+
+  --demo-accent2: #0284c7;
+  --demo-accent2-rgb: 2, 132, 199;
+  --demo-accent2-glow: 0 0 15px rgba(var(--demo-accent2-rgb), 0.3), 0 0 30px rgba(var(--demo-accent2-rgb), 0.15);
+
+  /* Glassmorphism & Panel System */
+  --demo-panel-bg: rgba(255, 255, 255, 0.25);
+  --demo-panel-border: rgba(255, 255, 255, 0.4);
+  --demo-panel-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.5);
+  --demo-panel-blur: 24px;
+  --demo-panel-radius: 12px;
+
+  --demo-subpanel-bg: rgba(255, 255, 255, 0.35);
+  --demo-subpanel-border: rgba(255, 255, 255, 0.3);
+  --demo-subpanel-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.6);
+  --demo-subpanel-blur: 12px;
+  --demo-subpanel-radius: 8px;
+
+  /* Drop Zone */
+  --demo-drop-bg: rgba(255, 255, 255, 0.15);
+  --demo-drop-border: rgba(255, 255, 255, 0.6);
+  --demo-drop-active-bg: rgba(255, 255, 255, 0.4);
+  --demo-drop-active-border: var(--demo-accent2);
+  --demo-drop-active-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.8);
+
+  /* Button / File Picker */
+  --demo-picker-bg: rgba(255, 255, 255, 0.5);
+  --demo-picker-hover-bg: rgba(255, 255, 255, 0.8);
+  --demo-picker-border: rgba(255, 255, 255, 0.6);
+  --demo-picker-hover-border: rgba(255, 255, 255, 0.9);
+  --demo-picker-text: var(--demo-text);
+
+  /* Metadata Pills */
+  --demo-pill-bg: rgba(var(--demo-accent-rgb), 0.1);
+  --demo-pill-border: var(--demo-accent);
+  --demo-pill-text: var(--demo-accent);
+  --demo-pill-shadow: inset 0 0 5px rgba(var(--demo-accent-rgb), 0.3);
+
+  /* File Info Overlay */
+  --demo-file-info-bg: rgba(255, 255, 255, 0.7);
+  --demo-file-info-border: rgba(255, 255, 255, 0.8);
+  --demo-file-info-blur: 10px;
+
+  /* Typography & Fonts */
+  --demo-font-sans: "Outfit", system-ui, -apple-system, sans-serif;
+  --demo-font-mono: "Space Mono", monospace;
+
+  /* Legacy Aliases for Backward Compatibility */
+  --bg-a: var(--demo-bg-a);
+  --bg-b: var(--demo-bg-b);
+  --text: var(--demo-text);
+  --muted: var(--demo-muted);
+  --accent: var(--demo-accent);
+  --accent-glow: var(--demo-accent-glow);
+  --accent2: var(--demo-accent2);
+  --accent2-glow: var(--demo-accent2-glow);
+  --font-sans: var(--demo-font-sans);
+  --font-mono: var(--demo-font-mono);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  color: var(--demo-text);
+  background:
+    radial-gradient(circle at 15% 50%, var(--demo-bg-radial-1), transparent 45%),
+    radial-gradient(circle at 85% 30%, var(--demo-bg-radial-2), transparent 50%),
+    var(--demo-bg-gradient);
+  background-attachment: fixed;
+  font-family: var(--demo-font-sans);
+  letter-spacing: 0.02em;
+}
+
+body::after {
+  content: "";
+  position: fixed;
+  inset: 0;
+  background: linear-gradient(to bottom,
+      rgba(0, 0, 0, 0),
+      rgba(0, 0, 0, 0) 50%,
+      rgba(0, 0, 0, 0.02) 50%,
+      rgba(0, 0, 0, 0.02));
+  background-size: 100% 4px;
+  pointer-events: none;
+  z-index: 9999;
+}
+
+main {
+  min-height: 100vh;
+  min-height: 100dvh;
+  display: grid;
+  place-items: center;
+  padding: 2rem;
+  position: relative;
+  z-index: 1;
+}
+
+main.running {
+  padding: 0;
+  background: black;
+}
+
+.runtime {
+  position: relative;
+  aspect-ratio: 5 / 4;
+  overflow: hidden;
+}
+
+.runtime canvas {
+  aspect-ratio: 5 / 4;
+  width: min(100vw, calc(100vh * 5 / 4));
+  height: auto;
+  max-height: 100vh;
+  display: block;
+}

package/demo/demo.js

@@ -0,0 +1,149 @@
+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, 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"),
+]);
+
+const mainEl = $("main");
+if (!(mainEl instanceof HTMLElement)) {
+  throw new Error("Demo page boot failed: missing required elements.");
+}
+
+const sdk = await getSdk();
+
+if (sdk.manifest?.name) {
+  document.title = `${sdk.manifest.name} - Demo`;
+}
+
+// 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 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");
+
+  const fileInfoEl = $create("section", { className: "file-info" });
+  const runtimeEl = $create("div", {
+    className: "runtime",
+    children: [fileInfoEl],
+  });
+
+  mainEl.replaceChildren(runtimeEl);
+
+  const primaryFile = rom || bios;
+  const fileInfoProps = {
+    fileName: primaryFile.name,
+    size: `${primaryFile.size.toLocaleString()} bytes`,
+  };
+  const fileInfoPlaceholder = CFileInfo
+    .renderShadow({
+      ...fileInfoProps,
+      checksums: checksumAlgorithms.map((label) => ({ label, value: "computing…" })),
+    })
+    .mount(fileInfoEl);
+
+  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,
+    options: {
+      fileName: primaryFile.name,
+      byteLength: primaryFile.size,
+    },
+    onEvent(event) {
+      if (event.type === "error") {
+        console.error(event.error);
+      }
+    },
+  });
+
+  instance.start();
+
+  const checksums = await computeChecksums(romBytes || biosBytes);
+  fileInfoPlaceholder.destroy();
+
+  CFileInfo
+    .renderShadow({ ...fileInfoProps, checksums })
+    .mount(fileInfoEl);
+};
+
+CLauncher
+  .render({
+    CSdkInfo,
+    CDropArea,
+    sdkInfo: {
+      name: sdk.manifest.name,
+      id: sdk.manifest.id,
+      description: sdk.manifest.description,
+      version: sdk.manifest.version,
+      baseWidth: sdk.manifest.video?.baseWidth ?? 320,
+      baseHeight: sdk.manifest.video?.baseHeight ?? 240,
+      assetKey: romSpec?.key ?? "rom",
+    },
+    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

@@ -0,0 +1,208 @@
+export function createDummySdk() {
+	const manifest = {
+		id: "dummy-canvas-sdk",
+		version: "0.1.0-demo",
+		name: "Dummy Canvas Engine",
+		description: "A placeholder SDK that renders animated content on canvas.",
+		artifacts: {
+			wasm: "./dummy.wasm",
+			js: "./dummy.js",
+		},
+		assets: [
+			{
+				key: "rom",
+				mountPath: "/rom.bin",
+				required: true,
+				accept: [".rom", ".bin", ".zip", ".dat"],
+				description: "Any game ROM file works in this demo.",
+			},
+			{
+				key: "bios",
+				mountPath: "/bios.bin",
+				required: false,
+				accept: [".bin", ".rom", ".sys"],
+				description: "Optional system BIOS firmware file.",
+			},
+		],
+		input: "keyboard-default",
+		video: {
+			baseWidth: 320,
+			baseHeight: 256,
+			aspect: "5:4",
+		},
+		capabilities: {
+			saveStates: false,
+			sram: false,
+		},
+	};
+
+	return {
+		manifest,
+		async load(config) {
+			const ownsCanvas = !config.canvasEl;
+			const canvasEl = config.canvasEl ?? document.createElement("canvas");
+			if (ownsCanvas) {
+				config.attachTo.appendChild(canvasEl);
+			}
+
+			const ctx = canvasEl.getContext("2d");
+			if (!ctx) {
+				const error = new Error("Could not create 2D canvas context.");
+				config.onEvent?.({ type: "error", error });
+				throw error;
+			}
+
+			// Copy loaded ROM and BIOS assets to MEMFS (In-Memory Virtual File System)
+			const MEMFS = new Map();
+			if (config.assets) {
+				for (const assetSpec of manifest.assets) {
+					const data = config.assets[assetSpec.key];
+					if (data) {
+						const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+						MEMFS.set(assetSpec.mountPath, bytes);
+						console.log(`[MEMFS] Copied asset '${assetSpec.key}' (${bytes.byteLength} bytes) to ${assetSpec.mountPath}`);
+					}
+				}
+			}
+
+			let raf = 0;
+			let running = false;
+			let t0 = performance.now();
+			let lastFrame = t0;
+
+			const fontSize = 30;
+			let drops = [];
+
+			const fitCanvasToWindow = () => {
+				const dpr = window.devicePixelRatio || 1;
+				const rect = canvasEl.getBoundingClientRect();
+				const width = Math.max(1, Math.floor(rect.width * dpr));
+				const height = Math.max(1, Math.floor(rect.height * dpr));
+				canvasEl.width = width;
+				canvasEl.height = height;
+			};
+
+			const render = (time) => {
+				if (!running) {
+					return;
+				}
+
+				const width = canvasEl.width;
+				const height = canvasEl.height;
+				const dt = Math.min((time - lastFrame) / 1000, 0.1);
+				const fps = Math.max(1, 1000 / Math.max(1, time - lastFrame));
+				lastFrame = time;
+
+				const expectedColumns = Math.floor(width / fontSize);
+				const maxRows = Math.floor(height / fontSize) + 30;
+
+				if (drops.length !== expectedColumns) {
+					drops = [];
+					for (let x = 0; x < expectedColumns; x++) {
+						drops[x] = {
+							y: Math.random() * maxRows,
+							speed: Math.random() * 1.5 + 0.5,
+							opacity: Math.random() * 0.7 + 0.3,
+							length: Math.floor(Math.random() * 20 + 5),
+							chars: Array.from({ length: maxRows }, () => String.fromCharCode(0x30A0 + Math.random() * 96))
+						};
+					}
+				}
+
+				// Dark background inside the canvas to contrast with the light UI components
+				ctx.fillStyle = "#060910ff";
+				ctx.fillRect(0, 0, width, height);
+
+				ctx.font = "bold " + fontSize + "px 'Hiragino Sans', 'Hiragino Kaku Gothic ProN', 'Noto Sans CJK JP', sans-serif";
+				ctx.textAlign = "center";
+
+				for (let x = 0; x < drops.length; x++) {
+					let drop = drops[x];
+
+					if (Math.random() > 0.4) {
+						let randIdx = Math.floor(Math.random() * drop.chars.length);
+						drop.chars[randIdx] = String.fromCharCode(0x30A0 + Math.random() * 96);
+					}
+
+					drop.y += drop.speed * (dt * 12);
+
+					let startY = Math.floor(drop.y);
+
+					for (let i = 0; i < drop.length; i++) {
+						let charY = startY - i;
+						if (charY < 0 || charY >= maxRows) continue;
+
+						let text = drop.chars[charY];
+						let alpha = drop.opacity * (1 - (i / drop.length));
+
+						if (i === 0) {
+							ctx.fillStyle = `rgba(220, 255, 255, ${drop.opacity})`;
+						} else {
+							const hue = ((time / 15) + (x * 10)) % 360;
+							ctx.fillStyle = `hsla(${hue}, 80%, 65%, ${alpha})`;
+						}
+
+						ctx.fillText(text, x * fontSize + fontSize / 2, charY * fontSize);
+					}
+
+					if ((drop.y - drop.length) * fontSize > height) {
+						drop.y = 0;
+						drop.speed = Math.random() * 1.5 + 0.5;
+						drop.opacity = Math.random() * 0.7 + 0.3;
+						drop.length = Math.floor(Math.random() * 20 + 5);
+					}
+				}
+
+				ctx.fillStyle = "rgba(255,255,255,0.85)";
+				ctx.fillRect(width - 210, 20, 180, 64);
+				ctx.fillStyle = "#0f172a";
+				ctx.font = "600 36px 'Outfit', system-ui, sans-serif";
+				ctx.textAlign = "left";
+				ctx.fillText(`FPS ${fps.toFixed(0)}`, width - 182, 65);
+
+				config.onEvent?.({ type: "frame", fps });
+				raf = requestAnimationFrame(render);
+			};
+
+			fitCanvasToWindow();
+			window.addEventListener("resize", fitCanvasToWindow);
+			config.onEvent?.({ type: "ready" });
+
+			return {
+				start() {
+					if (running) {
+						return;
+					}
+					running = true;
+					raf = requestAnimationFrame(render);
+				},
+				pause() {
+					running = false;
+					cancelAnimationFrame(raf);
+				},
+				resume() {
+					if (running) {
+						return;
+					}
+					running = true;
+					raf = requestAnimationFrame(render);
+				},
+				reset() {
+					t0 = performance.now();
+					lastFrame = t0;
+				},
+				setInput() {
+					return;
+				},
+				destroy() {
+					running = false;
+					cancelAnimationFrame(raf);
+					window.removeEventListener("resize", fitCanvasToWindow);
+					if (ownsCanvas) {
+						canvasEl.remove();
+					}
+				},
+			};
+		},
+	};
+}

package/demo/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>WASM Gaming Engine Specs Demo</title>
+    <link rel="stylesheet" href="./demo.css" />
+  </head>
+  <body>
+    <main></main>
+
+    <script type="module" src="./demo.js"></script>
+  </body>
+</html>

package/demo/sdk.js

@@ -0,0 +1,19 @@
+import { createDummySdk } from "./demo.sdk.js";
+
+/**
+ * Resolves the Engine SDK to use for the demo.
+ *
+ * To use this template in another repository:
+ * 1. Modify this file to import your engine's SDK:
+ *    import sdk from "../src/index.js"; // or "../dist/index.js"
+ *    export async function getSdk() { return sdk; }
+ *
+ * 2. Or attach window.SDK before demo.js boots:
+ *    window.SDK = myEngineSdk;
+ */
+export async function getSdk() {
+  if (typeof window !== "undefined" && window.SDK) {
+    return window.SDK;
+  }
+  return createDummySdk();
+}

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.1",
+  "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",
@@ -13,6 +13,7 @@
   },
   "files": [
     "dist/",
+    "demo/",
     "src/",
     "schema/"
   ],