@plasius/gpu-demo-viewer 0.1.0

package/index.html

@@ -0,0 +1,160 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Plasius GPU Demo Viewer</title>
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <main class="app">
+      <header class="hero">
+        <div class="hero__copy">
+          <p class="eyebrow">Plasius GPU</p>
+          <h1>Demo Viewer</h1>
+          <p class="lead">
+            Launch, preview, and validate every <code>gpu-*</code> demo from one root URL.
+            Browser demos can be embedded directly here, including the shared 3D harbor scene
+            used by cloth, fluid, lighting, debug, and performance validation surfaces.
+          </p>
+        </div>
+        <section class="runtime-card" aria-live="polite">
+          <p id="runtimeBadge" class="runtime-badge">Checking runtime…</p>
+          <p id="runtimeDetails" class="runtime-details">
+            Browser-backed WebGPU demos require <code>localhost</code> or <code>HTTPS</code>.
+          </p>
+        </section>
+      </header>
+
+      <section class="toolbar">
+        <label class="search-field">
+          <span>Search demos</span>
+          <input
+            id="searchInput"
+            type="search"
+            placeholder="gpu-renderer, particles, world…"
+            autocomplete="off"
+          />
+        </label>
+        <div class="filters" role="toolbar" aria-label="Demo filters">
+          <button type="button" class="filter is-active" data-filter="all">All</button>
+          <button type="button" class="filter" data-filter="browser">Browser</button>
+          <button type="button" class="filter" data-filter="3d">3D Canvas</button>
+          <button type="button" class="filter" data-filter="integration">Integration</button>
+          <button type="button" class="filter" data-filter="example">Code Examples</button>
+        </div>
+      </section>
+
+      <section class="layout">
+        <aside class="catalog panel">
+          <div class="catalog__header">
+            <div>
+              <p class="section-eyebrow">Packages</p>
+              <h2>GPU Demo Catalog</h2>
+            </div>
+            <p id="catalogSummary" class="catalog__summary">Loading demo manifest…</p>
+          </div>
+          <div id="demoList" class="demo-list"></div>
+        </aside>
+
+        <section class="viewer panel">
+          <div class="viewer__header">
+            <div>
+              <p id="selectedMeta" class="section-eyebrow">@plasius/gpu-demo-viewer</p>
+              <h2 id="selectedTitle">integration-showcase</h2>
+              <p id="selectedDescription" class="viewer__description">
+                Unified 3D validation scene with GLTF ships, colliding rigid bodies, cloth, fluid
+                continuity, lighting bands, adaptive performance, and telemetry.
+              </p>
+            </div>
+            <div class="viewer__actions">
+              <a id="openDemo" class="action" href="./showcase/" target="_blank" rel="noreferrer">
+                Open showcase
+              </a>
+              <a
+                id="openSource"
+                class="action action--ghost"
+                href="./showcase/main.js"
+                target="_blank"
+                rel="noreferrer"
+              >
+                Source
+              </a>
+              <a
+                id="openDocs"
+                class="action action--ghost"
+                href="./README.md"
+                target="_blank"
+                rel="noreferrer"
+              >
+                Docs
+              </a>
+            </div>
+          </div>
+
+          <div class="details-grid">
+            <section class="detail-card">
+              <h3>Validation Summary</h3>
+              <dl class="detail-list">
+                <div>
+                  <dt>Mode</dt>
+                  <dd id="detailMode">Unified 3D integration showcase</dd>
+                </div>
+                <div>
+                  <dt>Runtime</dt>
+                  <dd id="detailRuntime">3D canvas + GLTF rigid bodies</dd>
+                </div>
+                <div>
+                  <dt>Launch</dt>
+                  <dd id="detailLaunch">showcase/</dd>
+                </div>
+              </dl>
+            </section>
+
+            <section class="detail-card">
+              <h3>Run Command</h3>
+              <pre id="detailCommand" class="command-block">cd gpu-demo-viewer && npm run demo</pre>
+            </section>
+
+            <section class="detail-card detail-card--wide">
+              <h3>Notes</h3>
+              <ul id="detailNotes" class="notes-list">
+                <li>This is the top-level cross-package validation surface.</li>
+                <li>The ships are loaded from GLTF and expose physics metadata used by the collision loop.</li>
+              </ul>
+            </section>
+          </div>
+
+          <section id="browserPane" class="preview-pane">
+            <div class="preview-pane__header">
+              <p class="preview-label">Embedded Preview</p>
+              <p id="previewHint" class="preview-hint">
+                Mounted canvas preview. Interact with the embedded demo directly.
+              </p>
+            </div>
+            <iframe
+              id="demoFrame"
+              class="demo-frame"
+              title="GPU demo preview"
+              loading="lazy"
+              src="./showcase/"
+            ></iframe>
+          </section>
+
+          <section id="examplePane" class="example-pane" hidden>
+            <div class="preview-pane__header">
+              <p class="preview-label">Code Example</p>
+              <p class="preview-hint">
+                This package does not mount a browser demo. Use the command and source entry
+                points below for validation.
+              </p>
+            </div>
+            <ul id="exampleFiles" class="example-files"></ul>
+          </section>
+        </section>
+      </section>
+    </main>
+
+    <script type="module" src="./main.js"></script>
+  </body>
+</html>

package/index.js

@@ -0,0 +1 @@
+import "./main.js";

package/main.js

@@ -0,0 +1,262 @@
+import { demos } from "./viewer-manifest.js";
+
+const state = {
+  filter: "all",
+  search: "",
+  selectedId: "integration-showcase"
+};
+
+const demoListEl = document.getElementById("demoList");
+const catalogSummaryEl = document.getElementById("catalogSummary");
+const searchInputEl = document.getElementById("searchInput");
+const filterButtons = Array.from(document.querySelectorAll(".filter"));
+const runtimeBadgeEl = document.getElementById("runtimeBadge");
+const runtimeDetailsEl = document.getElementById("runtimeDetails");
+
+const selectedMetaEl = document.getElementById("selectedMeta");
+const selectedTitleEl = document.getElementById("selectedTitle");
+const selectedDescriptionEl = document.getElementById("selectedDescription");
+const detailModeEl = document.getElementById("detailMode");
+const detailRuntimeEl = document.getElementById("detailRuntime");
+const detailLaunchEl = document.getElementById("detailLaunch");
+const detailCommandEl = document.getElementById("detailCommand");
+const detailNotesEl = document.getElementById("detailNotes");
+const openDemoEl = document.getElementById("openDemo");
+const openSourceEl = document.getElementById("openSource");
+const openDocsEl = document.getElementById("openDocs");
+const browserPaneEl = document.getElementById("browserPane");
+const examplePaneEl = document.getElementById("examplePane");
+const demoFrameEl = document.getElementById("demoFrame");
+const previewHintEl = document.getElementById("previewHint");
+const exampleFilesEl = document.getElementById("exampleFiles");
+
+function setRuntimeStatus() {
+  const onLocalhost = ["localhost", "127.0.0.1", "[::1]"].includes(window.location.hostname);
+  const secure = window.isSecureContext || onLocalhost;
+  if (secure) {
+    runtimeBadgeEl.textContent = "Secure context ready";
+    runtimeBadgeEl.dataset.tone = "success";
+    runtimeDetailsEl.innerHTML =
+      'Browser-backed WebGPU demos can initialize here. Open this viewer from <code>localhost</code> or <code>HTTPS</code> for consistent results.';
+    return;
+  }
+
+  runtimeBadgeEl.textContent = "Secure context missing";
+  runtimeBadgeEl.dataset.tone = "error";
+  runtimeDetailsEl.innerHTML =
+    'This host is not running in a secure context. Browser-backed WebGPU demos may report <code>navigator.gpu</code> as unavailable until you serve the workspace from <code>localhost</code> or <code>HTTPS</code>.';
+}
+
+function matchesFilter(demo) {
+  if (state.filter === "all") {
+    return true;
+  }
+  if (state.filter === "browser") {
+    return demo.type === "browser";
+  }
+  if (state.filter === "example") {
+    return demo.type === "example";
+  }
+  if (state.filter === "3d") {
+    return demo.tags.includes("3d");
+  }
+  if (state.filter === "integration") {
+    return demo.tags.includes("integration");
+  }
+  return true;
+}
+
+function matchesSearch(demo) {
+  const term = state.search.trim().toLowerCase();
+  if (!term) {
+    return true;
+  }
+  return [
+    demo.id,
+    demo.packageName,
+    demo.mode,
+    demo.runtime,
+    demo.summary,
+    ...demo.notes
+  ]
+    .join(" ")
+    .toLowerCase()
+    .includes(term);
+}
+
+function getVisibleDemos() {
+  return demos.filter((demo) => matchesFilter(demo) && matchesSearch(demo));
+}
+
+function getSelectedDemo(visibleDemos) {
+  if (state.selectedId) {
+    const selected = visibleDemos.find((demo) => demo.id === state.selectedId);
+    if (selected) {
+      return selected;
+    }
+  }
+  const hashId = window.location.hash.replace(/^#/, "");
+  if (hashId) {
+    const selected = visibleDemos.find((demo) => demo.id === hashId);
+    if (selected) {
+      return selected;
+    }
+  }
+  return visibleDemos[0] ?? null;
+}
+
+function renderCatalog() {
+  const visibleDemos = getVisibleDemos();
+  const selectedDemo = getSelectedDemo(visibleDemos);
+  state.selectedId = selectedDemo?.id ?? null;
+
+  catalogSummaryEl.textContent =
+    visibleDemos.length === demos.length
+      ? `${visibleDemos.length} demos available`
+      : `${visibleDemos.length} of ${demos.length} demos shown`;
+
+  if (visibleDemos.length === 0) {
+    demoListEl.innerHTML =
+      '<div class="empty-state">No demos match the current search and filter combination.</div>';
+    renderSelection(null);
+    return;
+  }
+
+  demoListEl.innerHTML = "";
+
+  for (const demo of visibleDemos) {
+    const card = document.createElement("button");
+    card.type = "button";
+    card.className = `demo-card${demo.id === state.selectedId ? " is-selected" : ""}`;
+    card.dataset.id = demo.id;
+    card.innerHTML = `
+      <div class="demo-card__top">
+        <div>
+          <p class="section-eyebrow">${demo.packageName}</p>
+          <h3 class="demo-card__name">${demo.id}</h3>
+        </div>
+        <span class="tag tag--${demo.type}">${demo.type}</span>
+      </div>
+      <p class="demo-card__summary">${demo.summary}</p>
+      <div class="demo-card__tags">
+        ${demo.tags.map((tag) => `<span class="tag">${tag}</span>`).join("")}
+      </div>
+    `;
+    card.addEventListener("click", () => {
+      state.selectedId = demo.id;
+      window.location.hash = demo.id;
+      renderCatalog();
+    });
+    demoListEl.appendChild(card);
+  }
+
+  renderSelection(selectedDemo);
+}
+
+function renderNotes(notes) {
+  detailNotesEl.innerHTML = "";
+  for (const note of notes) {
+    const item = document.createElement("li");
+    item.textContent = note;
+    detailNotesEl.appendChild(item);
+  }
+}
+
+function renderExampleFiles(demo) {
+  exampleFilesEl.innerHTML = "";
+  const files = [
+    { label: "Primary entry", href: demo.sourcePath },
+    demo.docsPath ? { label: "Package docs", href: demo.docsPath } : null
+  ].filter(Boolean);
+
+  for (const file of files) {
+    const item = document.createElement("li");
+    const link = document.createElement("a");
+    link.href = file.href;
+    link.target = "_blank";
+    link.rel = "noreferrer";
+    link.textContent = `${file.label}: ${file.href.replace(/^\.\//, "")}`;
+    item.appendChild(link);
+    exampleFilesEl.appendChild(item);
+  }
+}
+
+function renderSelection(demo) {
+  if (!demo) {
+    selectedMetaEl.textContent = "No demo selected";
+    selectedTitleEl.textContent = "Choose a package";
+    selectedDescriptionEl.textContent =
+      "Adjust the filters or search term to find a demo entry.";
+    detailModeEl.textContent = "-";
+    detailRuntimeEl.textContent = "-";
+    detailLaunchEl.textContent = "-";
+    detailCommandEl.textContent = "Select a demo to see its command.";
+    detailNotesEl.innerHTML = "<li>No notes available.</li>";
+    browserPaneEl.hidden = true;
+    examplePaneEl.hidden = true;
+    openDemoEl.hidden = true;
+    openSourceEl.hidden = true;
+    openDocsEl.hidden = true;
+    demoFrameEl.removeAttribute("src");
+    return;
+  }
+
+  selectedMetaEl.textContent = demo.packageName;
+  selectedTitleEl.textContent = demo.id;
+  selectedDescriptionEl.textContent = demo.summary;
+  detailModeEl.textContent = demo.mode;
+  detailRuntimeEl.textContent = demo.runtime;
+  detailLaunchEl.textContent = demo.launchPath.replace(/^\.\//, "");
+  detailCommandEl.textContent = demo.command;
+  renderNotes(demo.notes);
+
+  openDemoEl.hidden = false;
+  openDemoEl.textContent = demo.launchLabel;
+  openDemoEl.href = demo.launchPath;
+  openSourceEl.hidden = false;
+  openSourceEl.href = demo.sourcePath;
+  openDocsEl.hidden = !demo.docsPath;
+  if (demo.docsPath) {
+    openDocsEl.href = demo.docsPath;
+  }
+
+  if (demo.type === "browser") {
+    browserPaneEl.hidden = false;
+    examplePaneEl.hidden = true;
+    previewHintEl.textContent = demo.tags.includes("integration")
+      ? "Integrated cross-package harbor preview. Use this to validate the full family together."
+      : "Mounted 3D preview. Interact with the embedded demo directly.";
+    demoFrameEl.src = demo.launchPath;
+  } else {
+    browserPaneEl.hidden = true;
+    examplePaneEl.hidden = false;
+    demoFrameEl.removeAttribute("src");
+    renderExampleFiles(demo);
+  }
+}
+
+function bindEvents() {
+  searchInputEl.addEventListener("input", (event) => {
+    state.search = event.target.value;
+    renderCatalog();
+  });
+
+  for (const button of filterButtons) {
+    button.addEventListener("click", () => {
+      state.filter = button.dataset.filter ?? "all";
+      for (const sibling of filterButtons) {
+        sibling.classList.toggle("is-active", sibling === button);
+      }
+      renderCatalog();
+    });
+  }
+
+  window.addEventListener("hashchange", () => {
+    state.selectedId = window.location.hash.replace(/^#/, "") || null;
+    renderCatalog();
+  });
+}
+
+setRuntimeStatus();
+bindEvents();
+renderCatalog();

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@plasius/gpu-demo-viewer",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Root validation viewer for Plasius gpu-* demos.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Plasius-LTD/gpu-demo-viewer.git"
+  },
+  "homepage": "https://github.com/Plasius-LTD/gpu-demo-viewer#readme",
+  "bugs": {
+    "url": "https://github.com/Plasius-LTD/gpu-demo-viewer/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./viewer-manifest.js",
+    "./viewer-manifest": "./viewer-manifest.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "assets/",
+    "docs/",
+    "scripts/",
+    "showcase/",
+    "wavefront/",
+    "CHANGELOG.md",
+    "NFR.md",
+    "README.md",
+    "index.html",
+    "index.js",
+    "main.js",
+    "styles.css",
+    "viewer-manifest.js"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "audit:npm": "npm audit --audit-level=high --omit=dev",
+    "build": "node scripts/verify-static-viewer-contract.cjs",
+    "demo": "python3 -m http.server --directory ..",
+    "lint": "npm run typecheck",
+    "pack:check": "node scripts/verify-public-package.cjs",
+    "prepublishOnly": "npm run build && npm run pack:check",
+    "typecheck": "node --check index.js && node --check main.js && node --check viewer-manifest.js && node --check showcase/index.js && node --check showcase/main.js && node --check wavefront/main.js",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@plasius/gpu-renderer": "^0.2.3",
+    "@plasius/gpu-shared": "^0.1.16"
+  }
+}

package/scripts/verify-public-package.cjs

@@ -0,0 +1,90 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const repoRoot = path.resolve(__dirname, "..");
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+function readJson(relativePath) {
+  return JSON.parse(fs.readFileSync(path.join(repoRoot, relativePath), "utf8"));
+}
+
+function packDryRunFiles() {
+  const result = spawnSync("npm", ["pack", "--dry-run", "--json"], {
+    cwd: repoRoot,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      npm_config_cache:
+        process.env.PLASIUS_PACK_CHECK_NPM_CACHE ||
+        path.join(os.tmpdir(), "plasius-gpu-demo-viewer-npm-cache")
+    },
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+
+  assert(
+    result.status === 0,
+    `npm pack --dry-run failed:\n${result.stdout}\n${result.stderr}`
+  );
+
+  const [packInfo] = JSON.parse(result.stdout);
+  assert(packInfo && Array.isArray(packInfo.files), "npm pack output did not include file metadata");
+  return packInfo.files.map((file) => file.path).sort();
+}
+
+function main() {
+  const packageJson = readJson("package.json");
+
+  assert(packageJson.name === "@plasius/gpu-demo-viewer", "package name must remain scoped");
+  assert(packageJson.private !== true, "public package must not set private=true");
+  assert(
+    packageJson.publishConfig?.access === "public",
+    "public package must publish with public npm access"
+  );
+  assert(packageJson.license === "Apache-2.0", "package license is required");
+  assert(packageJson.repository?.url?.includes("Plasius-LTD/gpu-demo-viewer"), "repository metadata is required");
+  assert(packageJson.exports?.["."] === "./viewer-manifest.js", "viewer manifest must be the package root export");
+
+  const files = packDryRunFiles();
+  const fileSet = new Set(files);
+  const requiredFiles = [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "assets/brigantine.gltf",
+    "docs/adrs/index.md",
+    "index.html",
+    "main.js",
+    "package.json",
+    "showcase/index.html",
+    "viewer-manifest.js",
+    "wavefront/index.html",
+    "wavefront/main.js"
+  ];
+
+  for (const requiredFile of requiredFiles) {
+    assert(fileSet.has(requiredFile), `package tarball must include ${requiredFile}`);
+  }
+
+  for (const file of files) {
+    assert(!file.startsWith("node_modules/"), `package tarball must not include ${file}`);
+    assert(!file.startsWith("tests/"), `package tarball must not include ${file}`);
+    assert(!file.startsWith(".git/"), `package tarball must not include ${file}`);
+    assert(!file.startsWith(".tmp"), `package tarball must not include ${file}`);
+  }
+
+  process.stdout.write("Public package contract verified.\n");
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}

package/scripts/verify-static-viewer-contract.cjs

@@ -0,0 +1,64 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { pathToFileURL } = require("node:url");
+
+const repoRoot = path.resolve(__dirname, "..");
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+function requirePath(relativePath, label) {
+  const fullPath = path.join(repoRoot, relativePath);
+  assert(fs.existsSync(fullPath), `${label} is missing: ${relativePath}`);
+  return fullPath;
+}
+
+function staticPathFromUrl(relativePath) {
+  return relativePath.split(/[?#]/, 1)[0];
+}
+
+async function main() {
+  requirePath("README.md", "README");
+  requirePath("CHANGELOG.md", "CHANGELOG");
+  requirePath("NFR.md", "NFR");
+  requirePath("docs/adrs/index.md", "ADR index");
+  requirePath(
+    "docs/adrs/adr-0001-gpu-demo-viewer-governance-baseline.md",
+    "Baseline ADR"
+  );
+  requirePath("index.html", "Root viewer entry");
+  requirePath("main.js", "Root viewer runtime");
+  requirePath("showcase/index.html", "Showcase entry");
+  requirePath("showcase/main.js", "Showcase runtime");
+
+  const { demos } = await import(pathToFileURL(requirePath("viewer-manifest.js", "Viewer manifest")).href);
+  assert(Array.isArray(demos) && demos.length > 0, "viewer-manifest must export demos");
+
+  for (const demo of demos) {
+    assert(typeof demo.id === "string" && demo.id.length > 0, "demo.id is required");
+    assert(typeof demo.launchPath === "string", `${demo.id} launchPath is required`);
+    assert(typeof demo.sourcePath === "string", `${demo.id} sourcePath is required`);
+
+    if (demo.launchPath.startsWith("./")) {
+      requirePath(staticPathFromUrl(demo.launchPath.slice(2)), `${demo.id} launchPath`);
+    }
+
+    if (demo.sourcePath.startsWith("./")) {
+      requirePath(staticPathFromUrl(demo.sourcePath.slice(2)), `${demo.id} sourcePath`);
+    }
+
+    if (typeof demo.docsPath === "string" && demo.docsPath.startsWith("./")) {
+      requirePath(staticPathFromUrl(demo.docsPath.slice(2)), `${demo.id} docsPath`);
+    }
+  }
+
+  process.stdout.write("Static viewer contract verified.\n");
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+});

package/showcase/index.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Plasius GPU Integration Showcase</title>
+    <script type="importmap">
+      {
+        "imports": {
+          "@plasius/gpu-shared": "../node_modules/@plasius/gpu-shared/dist/index.js"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./main.js"></script>
+  </body>
+</html>

package/showcase/index.js

@@ -0,0 +1 @@
+import "./main.js";

package/showcase/main.js

@@ -0,0 +1,14 @@
+import { mountGpuShowcase } from "@plasius/gpu-shared";
+
+const focus = new URLSearchParams(window.location.search).get("focus") ?? "integrated";
+
+await mountGpuShowcase({
+  root: document.getElementById("app"),
+  focus,
+  packageName: "@plasius/gpu-demo-viewer",
+  title: focus === "physics" ? "Flag by the Sea: Physics Focus" : "Flag by the Sea",
+  subtitle:
+    focus === "physics"
+      ? "Stable-world-snapshot validation scene with moonlit GLTF ships, mass-aware collisions, lantern reflections, downstream cloth and fluid continuity, and ray-traced lighting bands."
+      : "Unified moonlit 3D validation scene with GLTF ships, lantern-lit collisions, cloth, fluid continuity, lighting bands, adaptive performance, and telemetry.",
+});