@wasm-gaming/engine-specs 0.2.0 → 0.2.2

package/demo/README.md

@@ -0,0 +1,94 @@
+# 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;
+}
+```
+
+### 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-font-sans` | Primary sans-serif font family | `"Outfit", system-ui, sans-serif` |
+| `--demo-font-mono` | Monospace code font family | `"Space Mono", monospace` |
+
+---
+
+## 🛠 Features
+
+- **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/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/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,163 @@
+<form class="launcher">
+  <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="status">{{ status }}</div>
+</form>
+
+<script :setup="{
+  CSdkInfo,
+  sdkInfo,
+  onFile,
+  accept,
+  assetHint = 'or choose one from your computer',
+}">
+  let status = "Ready";
+  let dragging = false;
+
+  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}`;
+    }
+  };
+
+  const onDrop = async (event) => {
+    dragging = false;
+    if (event.dataTransfer?.files) {
+      await onFileList(event.dataTransfer.files);
+    }
+  };
+
+  const onPick = async (event) => {
+    if (event.target.files) {
+      await onFileList(event.target.files);
+    }
+  };
+</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 {
+    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.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 strong {
+    display: block;
+    margin-bottom: 0.5rem;
+    font-size: 1.2rem;
+    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.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));
+    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));
+  }
+
+  .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;
+  }
+
+  .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,100 @@
+import { getSdk } from "./sdk.js";
+import { checksumAlgorithms, computeChecksums } from "./checksums.js";
+import { $, $create, Component79 } from "https://jgermade.github.io/jq79/jq79.js";
+
+// 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([
+  fetchComponent("./components/launcher.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 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";
+
+const bootWithFile = async (file) => {
+  const bytes = await file.arrayBuffer();
+
+  mainEl.classList.add("running");
+
+  const fileInfoEl = $create("section", { className: "file-info" });
+  const runtimeEl = $create("div", {
+    className: "runtime",
+    children: [fileInfoEl],
+  });
+
+  mainEl.replaceChildren(runtimeEl);
+
+  const fileInfoProps = {
+    fileName: file.name,
+    size: `${bytes.byteLength.toLocaleString()} bytes`,
+  };
+  const fileInfoPlaceholder = CFileInfo
+    .renderShadow({
+      ...fileInfoProps,
+      checksums: checksumAlgorithms.map((label) => ({ label, value: "computing…" })),
+    })
+    .mount(fileInfoEl);
+
+  const assetKey = sdk.manifest?.assets?.[0]?.key ?? "rom";
+  const instance = await sdk.load({
+    attachTo: runtimeEl,
+    assets: {
+      [assetKey]: bytes,
+    },
+    options: {
+      fileName: file.name,
+      byteLength: bytes.byteLength,
+    },
+    onEvent(event) {
+      if (event.type === "error") {
+        console.error(event.error);
+      }
+    },
+  });
+
+  instance.start();
+
+  const checksums = await computeChecksums(bytes);
+  fileInfoPlaceholder.destroy();
+
+  CFileInfo
+    .renderShadow({ ...fileInfoProps, checksums })
+    .mount(fileInfoEl);
+};
+
+CLauncher
+  .render({
+    CSdkInfo,
+    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: sdk.manifest.assets?.[0]?.key ?? "rom",
+    },
+    onFile: bootWithFile,
+    accept: acceptAttr,
+    assetHint,
+  })
+  .mount(mainEl);

package/demo/demo.sdk.js

@@ -0,0 +1,195 @@
+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 file works in this demo; data is not executed.",
+			},
+		],
+		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;
+			}
+
+			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 = "#0f172a";
+				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];
+
+					// 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;
+
+						let text = drop.chars[charY];
+						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})`;
+						}
+
+						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;
+						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/package.json

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