@plasius/gpu-demo-viewer 0.1.4 → 0.1.6

package/model-library/controller.js

@@ -0,0 +1,45 @@
+export function reviewEnabled(href) {
+  const url = new URL(href);
+  return ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)
+    && url.searchParams.get('review') === 'first-twelve';
+}
+export function fixtureRequest(asset, base) {
+  const safe = path => typeof path === 'string' && /^[\w./-]+$/u.test(path)
+    && !path.startsWith('/') && !path.split('/').includes('..');
+  if (!safe(asset.key) || asset.key.includes('/') || !safe(asset.entry)
+      || !asset.files.every(file => safe(file.path))) throw new Error('Unsafe fixture path.');
+  const root = new URL(`assets/${asset.key}/`, base);
+  return { modelUrl: new URL(asset.entry, root).href,
+    integrity: Object.fromEntries(asset.files.map(f => [new URL(f.path, root).href, f.integrity])) };
+}
+export function createReviewController({ load, onState }) {
+  let abort, active, generation = 0, disposed = false, paused = false;
+  return {
+    async select(asset) {
+      if (disposed) return;
+      const id = ++generation;
+      abort?.abort(); active?.destroy(); active = undefined;
+      abort = new AbortController();
+      if (!asset.entry) { onState({kind:'missing', asset, message:'Download deferred. This model is not installed.'}); return; }
+      onState({kind:'loading',asset});
+      try {
+        const runtime = await load(asset, abort.signal);
+        if (disposed || id !== generation) { runtime.destroy(); return; }
+        active = runtime; active.setPaused?.(paused); onState({kind:'ready',asset,runtime});
+      } catch (error) {
+        if (!disposed && id === generation) onState({kind:'error',asset,message:error.message});
+      }
+    },
+    async setQuality(quality) {
+      const runtime=active;
+      try { await runtime?.setQuality(quality); }
+      catch(error) { if(!disposed && active===runtime) throw error; }
+    },
+    setPaused(value) { paused=value;active?.setPaused?.(value); },
+    reset() { active?.reset(); },
+    destroy() {
+      if (disposed) return;
+      disposed = true; generation++; abort?.abort(); active?.destroy(); active = undefined;
+    },
+  };
+}

package/model-library/index.html

@@ -0,0 +1,35 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Plasius · Model studies</title><link rel="icon" href="data:,"><link rel="stylesheet" href="./styles.css">
+<script type="importmap">
+{
+  "imports": {
+    "@plasius/gpu-shared/model-inspection": "../node_modules/@plasius/gpu-shared/dist/model-inspection.js",
+    "@plasius/gpu-shared/feedback-diagnostics": "../node_modules/@plasius/gpu-shared/dist/feedback-diagnostics.js",
+    "@plasius/gpu-renderer": "../node_modules/@plasius/gpu-renderer/dist/index.js",
+    "@plasius/gpu-camera": "../node_modules/@plasius/gpu-camera/dist/index.js",
+    "@plasius/gpu-camera-controls": "../node_modules/@plasius/gpu-camera-controls/dist/index.js",
+    "@plasius/gpu-camera-controls/browser": "../node_modules/@plasius/gpu-camera-controls/dist/browser.js",
+    "@plasius/schema/feedback-diagnostics-vocabulary": "../node_modules/@plasius/schema/dist/feedback-diagnostics-vocabulary.js"
+  }
+}
+</script></head>
+<body><header><a href="https://plasius.co.uk/" target="_blank" rel="noopener">PLASIUS</a><span>Renderer workshop · Local review</span></header>
+<main><div class="intro"><p class="eyebrow">From source to scene</p><h1>Model studies</h1><p>Eleven assets. One renderer. Explore the surfaces, silhouettes and details that will shape our next improvements.</p></div>
+<div class="workspace"><aside><label for="model">Choose a model</label><select id="model" disabled></select><p id="category" class="muted"></p><h2 id="name"></h2><p id="target"></p><p id="note"></p><div id="metrics" class="metrics"></div>
+<details><summary>Source and licence</summary><p id="credits"></p><p><a id="source" target="_blank" rel="noopener">Original model</a> · <a id="licence" target="_blank" rel="noopener"></a></p><p>Original files retained. Framing is normalized for inspection. Powered by Poly Haven for its asset metadata.</p></details>
+<details><summary>Camera help</summary><p id="help">Drag to orbit. Shift-drag or right-drag to truck. Alt-drag to pan. Scroll to move closer; Shift-scroll changes the lens. Touch: one finger orbits; two fingers move and pinch. Keyboard: arrows orbit, Shift-arrows truck, + / − move closer or further, Home resets. Keys 1–5 choose orbit, truck, pan, dolly or zoom. Press ? for a brief reminder.</p></details>
+<details open><summary>Review focus</summary><p id="review"></p><p>This is an inspection pass, not a visual-quality approval. Source animations are retained on disk; this view displays static geometry.</p></details></aside>
+<section class="stage" aria-label="Model inspection">
+<fieldset id="quality" class="quality" disabled><legend>Render quality</legend>
+<div><label for="samples">Sample target</label><select id="samples" aria-describedby="quality-help"><option>1</option><option>8</option><option>16</option><option>32</option><option selected>64</option><option>128</option><option>256</option></select></div>
+<div><label for="bounces">Light bounces</label><select id="bounces"><option>2</option><option>4</option><option selected>6</option><option>8</option><option>10</option><option>12</option></select></div>
+<div><label for="resolution">Render size</label><select id="resolution"><option value="480">480 px · Quick</option><option value="800" selected>800 px · Balanced</option><option value="1280">1280 px · Detailed</option><option value="1920x1080">1920 × 1080 · Full HD</option><option value="2560x1440">2560 × 1440 · QHD</option><option value="3840x2160">3840 × 2160 · 4K UHD</option></select></div>
+<label class="toggle" for="denoise"><input id="denoise" type="checkbox" checked> Denoising</label>
+<p id="quality-help">Hold the camera still to refine. Higher targets reduce noise; more bounces reveal indirect light. HD, QHD and 4K trace at the selected size, even in a smaller window. Higher resolution costs more GPU time; use one sample for a quick inspection.</p>
+</fieldset>
+<div class="refinement"><label id="refinement" for="sample-progress">Waiting for a model…</label><progress id="sample-progress" max="64" value="0"></progress></div>
+<div class="canvas-wrap"><canvas id="canvas" width="800" height="600" tabindex="0" aria-label="Interactive Plasius model view" aria-describedby="help"></canvas><p id="hint" hidden>Drag to orbit · Shift-drag to move · Scroll to approach<br>Touch: drag or pinch · Keyboard: arrows, + / −, Home</p></div><p id="status" role="status" aria-live="polite">Preparing the review…</p></section></div>
+<p class="footnote">Gem is deferred pending its Sketchfab download. No replacement models are shown.</p></main>
+<script type="module">import { mountLibrary } from './main.js'; mountLibrary().catch(error => { document.querySelector('#status').textContent = `Unable to open review: ${error.message}`; });</script>
+</body></html>

package/model-library/main.js

@@ -0,0 +1,76 @@
+import { createReviewController, fixtureRequest, reviewEnabled } from './controller.js';
+
+export async function mountLibrary({document:doc=globalThis.document,window:win=globalThis.window,
+  fetch:request=globalThis.fetch,importRuntime=()=>import('@plasius/gpu-shared/model-inspection')}={}) {
+  const el=id=>doc.getElementById(id),status=el('status');
+  if (!reviewEnabled(win.location.href)) {
+    status.textContent='Local review is disabled. Open this page on localhost with ?review=first-twelve.';
+    return;
+  }
+  const response=await request(new URL('./catalogue.json',win.location.href));
+  if (!response.ok) throw new Error('Model catalogue could not be loaded.');
+  const {assets}=await response.json();
+  for(const asset of assets) {
+    const option=doc.createElement('option');option.value=asset.key;
+    option.textContent=asset.name+(asset.entry?'':' — deferred');el('model').append(option);
+  }
+  const {createModelInspection}=await importRuntime();
+  el('samples').value='64';el('bounces').value='6';el('resolution').value='800';el('denoise').checked=true;
+  const quality=()=>{
+    const [width,fixedHeight]=el('resolution').value.split('x').map(Number);
+    return {samplesPerPixel:Number(el('samples').value),maxDepth:Number(el('bounces').value),denoise:el('denoise').checked,
+      width,height:fixedHeight??Math.max(1,Math.min(1440,Math.round(width*el('canvas').clientHeight/el('canvas').clientWidth)))};
+  };
+  const refinement=p=>{
+    el('sample-progress').max=p.target;el('sample-progress').value=p.samples;
+    const phase={complete:'Complete',paused:'Paused',rendering:'Rendering',refining:'Refining'}[p.phase];
+    el('refinement').textContent=`${phase} · ${p.samples} / ${p.target} samples · ${p.width} × ${p.height}`;
+  };
+  const controller=createReviewController({
+    load:async(asset,signal)=>{
+      const request=fixtureRequest(asset,new URL('./',win.location.href));
+      el('canvas').hidden=false;
+      return createModelInspection({canvas:el('canvas'),...request,signal,enabled:true,
+        ...quality(),quality:quality(),
+        onProgress:p=>{if(!signal.aborted)refinement(p);},
+        onHintChange:visible=>{el('hint').hidden=!visible;},
+        onError:error=>{if(signal.aborted)return;status.textContent=`Render failed: ${error.message}`;el('refinement').textContent='Refinement stopped';el('quality').disabled=true;}});
+    },
+    onState:state=>{
+      el('hint').hidden=true;el('quality').disabled=state.kind!=='ready';
+      if(state.kind==='loading'){el('sample-progress').value=0;el('refinement').textContent='Waiting for the first sample…';}
+      if(state.kind==='loading')status.textContent=`Loading ${state.asset.name} and checking its files…`;
+      else if(state.kind==='ready') {
+        status.textContent=`${state.asset.review_status==='needs-fix'?'Rendered — visual defect recorded':'Ready'} · ${state.asset.name} · ${state.runtime.triangleCount.toLocaleString()} triangles · ${state.runtime.primitiveCount} mesh primitives`;
+        el('metrics').textContent=`${state.runtime.triangleCount.toLocaleString()} triangles · ${state.asset.inspection.materials} source materials`;
+      } else {status.textContent=state.message;el('canvas').hidden=true;el('refinement').textContent='Refinement unavailable';}
+    },
+  });
+  const change=()=>{
+    const asset=assets.find(a=>a.key===el('model').value);
+    el('category').textContent=asset.category;el('name').textContent=asset.name;
+    el('target').textContent=asset.renderer_target;el('review').textContent=asset.observed_issue??asset.preparation;
+    el('credits').textContent=asset.authors;el('source').href=asset.source_url;
+    el('licence').href=asset.licence_url;el('licence').textContent=asset.licence;
+    el('metrics').textContent=asset.entry?`${(asset.files.reduce((n,f)=>n+f.bytes,0)/1048576).toFixed(1)} MiB on disk`:'';
+    const clips=asset.inspection?.animations??[];
+    el('note').textContent=clips.length?`Static pose only. ${clips.length} source clips are present: ${clips.join(', ')}. Animation playback needs importer work.`:
+      asset.inspection?.extensions.length?`Material features to inspect: ${asset.inspection.extensions.join(', ')}.`:'Source materials under the same inspection lighting.';
+    return controller.select(asset);
+  };
+  el('model').value=assets.find(a=>a.entry).key;
+  el('model').addEventListener('change',change);
+  el('model').disabled=false;
+  const qualityChange=async()=>{
+    try{await controller.setQuality(quality());}catch(error){status.textContent=`Render failed: ${error.message}`;}
+  };
+  for(const id of ['samples','bounces','resolution','denoise'])el(id).addEventListener('change',qualityChange);
+  const visibility=()=>controller.setPaused(doc.hidden===true);
+  doc.addEventListener('visibilitychange',visibility);visibility();
+  let resizeTimer;
+  const resize=()=>{clearTimeout(resizeTimer);resizeTimer=setTimeout(qualityChange,250);};
+  win.addEventListener('resize',resize);
+  const destroy=()=>{for(const id of ['samples','bounces','resolution','denoise'])el(id).removeEventListener('change',qualityChange);doc.removeEventListener('visibilitychange',visibility);clearTimeout(resizeTimer);controller.destroy();el('model').removeEventListener('change',change);win.removeEventListener('pagehide',destroy);win.removeEventListener('resize',resize);};
+  win.addEventListener('pagehide',destroy);
+  await change();return {destroy};
+}

package/model-library/styles.css

@@ -0,0 +1,9 @@
+:root{color-scheme:dark;font-family:system-ui,sans-serif;background:#10151c;color:#f2eee5;font-size:16px}*{box-sizing:border-box}body{margin:0}header{display:flex;justify-content:space-between;gap:1rem;padding:1.4rem 4vw;border-bottom:1px solid #39444d}header>a{letter-spacing:.22em;font-family:Georgia,serif;text-decoration:none}header span,.muted,.footnote{color:#b8c4cc}a{color:#dfc88d}main{max-width:1560px;margin:auto;padding:2rem 4vw}h1,h2{font-family:Georgia,serif;font-weight:400}h1{font-size:clamp(2rem,4vw,3rem);margin:.3rem 0}.intro>p:last-child{max-width:720px;color:#c1cbd1;line-height:1.6}.eyebrow{text-transform:uppercase;letter-spacing:.18em;color:#dfc88d;font-size:.75rem}.workspace{display:grid;grid-template-columns:minmax(240px,300px) minmax(0,1fr);gap:2rem;margin-top:2rem}aside{line-height:1.6}label{display:block;margin-bottom:.4rem}select{width:100%;padding:.8rem;background:#222d37;color:#fff;border:1px solid #64747f;border-radius:.35rem;font-size:1rem}h2{font-size:1.8rem;margin:1rem 0}.stage{min-width:0}.canvas-wrap{position:relative;background:#202e3c;border:1px solid #596775;border-radius:.75rem;overflow:hidden}canvas{display:block;width:100%;height:auto;aspect-ratio:4/3;touch-action:none;cursor:grab}canvas:active{cursor:grabbing}canvas:focus-visible{outline:3px solid #edd7a1;outline-offset:-5px}a:focus-visible,summary:focus-visible,select:focus-visible{outline:3px solid #edd7a1;outline-offset:3px}#hint{position:absolute;bottom:1rem;left:1rem;right:1rem;text-align:center;background:#10151cef;color:#f4ecdb;padding:1rem;border:1px solid #9d916d;border-radius:.5rem;pointer-events:none;font-size:.9rem}#status{padding:1rem;background:#1c2630;border-radius:.4rem;line-height:1.5;min-height:4rem;margin-top:1rem}.metrics{color:#dfc88d;margin:1rem 0}details{border-top:1px solid #3a4651;padding:.8rem 0}summary{cursor:pointer;min-height:28px}details p{font-size:.88rem;color:#c7d0d7;overflow-wrap:anywhere}.footnote{font-size:.86rem;line-height:1.5;margin-top:2rem}@media(max-width:780px){header{flex-wrap:wrap}.workspace{display:flex;flex-direction:column}.stage{order:-1}main{padding:1.3rem 5vw}h1{font-size:2.2rem}}@media(prefers-reduced-motion:reduce){*{scroll-behavior:auto}}
+
+@media(min-width:781px){.intro{display:grid;grid-template-columns:auto 1fr;column-gap:2rem;align-items:end}.intro .eyebrow{grid-column:1/-1;margin:0}.intro>p:last-child{max-width:660px;margin:.3rem 0}.workspace{margin-top:1.4rem}.canvas-wrap{height:clamp(320px,calc(100dvh - 285px),760px)}canvas{width:100%;height:100%;aspect-ratio:auto}}
+
+.quality{display:grid;grid-template-columns:1fr 1fr 1.5fr auto;gap:.8rem;align-items:center;margin:0 0 1rem;padding:1rem;border:1px solid #596775;border-radius:.6rem;min-width:0}
+.quality legend{padding:0 .5rem;color:#dfc88d}.quality label{font-size:.9rem}.quality select{min-width:0;padding:.6rem}.quality>div{min-width:0}.quality .toggle{display:flex;align-items:center;gap:.5rem;margin-top:1.2rem;min-height:44px;cursor:pointer}.toggle input{width:1.2rem;height:1.2rem;accent-color:#dfc88d}.quality p{grid-column:1/-1;font-size:.8rem;line-height:1.5;color:#c1cbd1;margin:.3rem 0 0}input:focus-visible{outline:3px solid #edd7a1;outline-offset:3px}.refinement{display:flex;align-items:center;justify-content:space-between;gap:1rem;margin-bottom:.8rem;font-size:.85rem;color:#dfc88d}.refinement label{margin:0}progress{width:120px;max-width:30%;height:8px;accent-color:#dfc88d}.quality:disabled{opacity:.65}@media(max-width:1100px){.quality{grid-template-columns:1fr 1fr}.quality .toggle{margin-top:1rem}}@media(min-width:781px){.canvas-wrap{height:clamp(300px,calc(100dvh - 505px),760px)}}
+
+/* Preserve the traced camera aspect when fixed-size frames fit the viewport. */
+canvas{object-fit:contain}

package/model-library/vite.config.js

@@ -0,0 +1,12 @@
+import { isAbsolute } from 'node:path';
+const source=process.env.PLASIUS_SHARED_INSPECTION_SOURCE;
+const renderer=process.env.PLASIUS_RENDERER_SOURCE;
+if(renderer && !isAbsolute(renderer))throw new Error('Renderer source override must be an absolute development path.');
+if(source && !isAbsolute(source))throw new Error('Inspection source override must be an absolute development path.');
+export default {
+  root: new URL('.', import.meta.url).pathname,
+  cacheDir: '../node_modules/.vite-model-library',
+  resolve: { alias: {...(source ? { '@plasius/gpu-shared/model-inspection':source } : {}),...(renderer ? {'@plasius/gpu-renderer':renderer} : {})} },
+  server: { host: '127.0.0.1', port: 5291, strictPort: true, watch: { usePolling: true },
+    fs:{allow:[new URL('..',import.meta.url).pathname,...(source?[source.replace(/\/src\/model-inspection\.js$/,'')]:[]),...(renderer?[renderer.replace(/\/(src|dist)\/index\.js$/,'')]:[])]} },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/gpu-demo-viewer",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "Root validation viewer for Plasius gpu-* demos.",
   "license": "Apache-2.0",
@@ -33,7 +33,8 @@
     "index.js",
     "main.js",
     "styles.css",
-    "viewer-manifest.js"
+    "viewer-manifest.js",
+    "model-library/"
   ],
   "engines": {
     "node": ">=24"
@@ -45,11 +46,18 @@
     "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"
+    "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 && node --check model-library/main.js && node --check model-library/controller.js && node --check model-library/acquire.js",
+    "test": "node --test",
+    "models:download": "node scripts/acquire-model-library.mjs",
+    "models:dev": "vite --config model-library/vite.config.js",
+    "test:coverage": "c8 --reporter=lcov --reporter=text node --test"
   },
   "dependencies": {
-    "@plasius/gpu-renderer": "^0.2.23",
-    "@plasius/gpu-shared": "^1.0.2"
+    "@plasius/gpu-renderer": "^0.2.49",
+    "@plasius/gpu-shared": "^1.1.7"
+  },
+  "devDependencies": {
+    "c8": "^11.0.0",
+    "vite": "^8.1.4"
   }
 }

package/scripts/acquire-model-library.mjs

@@ -0,0 +1,8 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { acquireFixtures } from '../model-library/acquire.js';
+export async function run(acquire=acquireFixtures) {
+  const {assets}=JSON.parse(await readFile(new URL('../model-library/catalogue.json',import.meta.url),'utf8'));
+  return acquire({assets,root:fileURLToPath(new URL('../model-library/assets/',import.meta.url))});
+}
+if(process.argv[1]===fileURLToPath(import.meta.url))console.log(await run());

package/viewer-manifest.js

@@ -1,4 +1,19 @@
 export const demos = [
+  {
+    id: "model-library",
+    packageName: "@plasius/gpu-demo-viewer",
+    type: "browser",
+    mode: "Reviewed model inspection",
+    runtime: "Shared WebGPU model inspection",
+    launchLabel: "Open model studies",
+    launchPath: "./model-library/?review=first-twelve",
+    sourcePath: "./model-library/main.js",
+    docsPath: "./docs/model-library-review.md",
+    command: "npm run models:download && npm run models:dev",
+    summary: "Inspect eleven acquired models with original materials, source credits and explicit rendering findings.",
+    notes: ["Requires the released shared model-inspection entrypoint, or the documented local source override.", "Gem remains deferred. Fox is static; amber has a recorded material defect."],
+    tags: ["browser", "3d", "experimental"]
+  },
   {
     id: "integration-showcase",
     packageName: "@plasius/gpu-demo-viewer",