← Commit history

v0.9.0: layer intro previews (#8)

Colby Knox ·dd6702a672 · ·parent 6d3efb4
6 files changed +188−7
SKILL.md+20
@@ -46,3 +46,23 @@ Full API (loadModel, frameModel, toggleAxes, layers toolbar, laser etch, BABYLON namespace re-export) is documented in the README on this page. Source lives on the Files tab; `adom-wiki repo clone adom/adom-3d-viewer` gets you a working checkout.++## What a GLB can declare (0.9.0)++The viewer reads its behaviour from the GLB itself, in glTF `extras` and node+names; the one page that lists it all is the `wiki-hero-glb` skill in+adom/adom-wiki-skillpack, with the full detail in this package's+`docs/CONTENT-CONVENTIONS.md`. The short form:++- `extras.adomLayer { key, label, group, hidden }`: a Layers-panel toggle;+  nearest declaring ancestor wins; two layers (or one declared) make a panel.+  API `getLayers()`, `setLayerVisible(key, on)`.+- `extras.adomLayer.intro { fadeInAt, fadeOutAt, highlightButton, fadeMs }`+  on a hidden layer: after load it fades in, holds, fades out, with its+  toggle pressed and pulsing meanwhile; a click during the intro keeps it+  on. API `getIntros()`, `replayIntros()`, `stopIntros()`;+  `init(host, { intros: false })` never plays them.+- `extras.tooltip`: hover text; `extras.adomRole` or an `Adom.<Name>` node:+  a switchable group (a lens skin and its `KHR_lights_punctual` light switch+  together). API `getStateGroups()`, `setStateGroupEnabled()`,+  `getContentLights()`, `setLightBudget()`.
VERSION+1−1
@@ -1 +1 @@-0.8.0+0.9.0
docs/CONTENT-CONVENTIONS.md+31
@@ -68,6 +68,37 @@ Notes that matter in practice:   follow in the order they appear in the file. - Fewer than two layers means no panel. One layer is not a choice. +### Intro preview of a hidden layer (adom/adom-3d-viewer#8)++A hidden layer can introduce itself once after the model loads: it fades in,+holds, fades out, and while it shows its toggle in the Layers panel reads as+pressed and pulses, so the reader learns the switch exists. Afterwards the+layer rests hidden and the toggle rests off. Declare it on the same+`adomLayer`:++```json+{ "name": "Adom.FOV",+  "extras": { "adomLayer": { "key": "fov", "label": "Field of view", "group": "Optics", "hidden": true,+                             "intro": { "fadeInAt": 1.5, "fadeOutAt": 6.5, "highlightButton": true } } } }+```++| Field | Default | Meaning |+|-------|---------|---------|+| `fadeInAt` | 1.5 | Seconds after load when the fade-in starts (0 to 120). |+| `fadeOutAt` | `fadeInAt` + 5 | Seconds after load when the fade-out starts; a value at or before `fadeInAt` falls back to the default. |+| `highlightButton` | true | Render the panel toggle as pressed and pulsing while the layer shows. |+| `fadeMs` | 700 | Length of each fade (100 to 5000 ms). |++Rules: an `intro` is honoured only on a `hidden: true` layer (a visible layer+has nothing to introduce). The fade is the meshes' `visibility`, so it works on+any material; translucent artwork (alphaMode BLEND) fades as you would expect.+A click on the toggle during the intro keeps the layer on: the reader asked for+it. `setLayerVisible()` cancels a running intro on that layer. The panel gains+a "Replay intro" button whenever a layer declares one; the API is+`getIntros()`, `replayIntros()`, `stopIntros()`, and `init(..., { intros: false })`+never plays them (the wiki passes that for `?animate=0`). A new model or+`clearScene()` cancels everything.+ ## Hover tooltips (adom/wiki #35)  - Put a `tooltip` string in the glTF `extras` of the node or mesh:
package.json+1−1
@@ -1,6 +1,6 @@ {   "name": "adom-3d-viewer-babylon9",-  "version": "0.8.0",+  "version": "0.9.0",   "description": "The Babylon 9.5 engine behind every component page's 3D tab on wiki.adom.inc. Versioned ESM bundle with GLB loading, view cube, layers toolbar, ground shadows, and Z-up CAD framing.",   "type": "app",   "main": "./dist/index.js",
src/ThreeDViewer.svelte+122−5
@@ -346,11 +346,23 @@     const STATE_PREF = (key: string) => `a3d.state.${key}`;      /** A declared layer, from glTF extras or the built-in vocabulary. */-    type LayerSpec = { key: string; label?: string; group?: string; hidden?: boolean };+    type LayerSpec = { key: string; label?: string; group?: string; hidden?: boolean; intro?: LayerIntro };+    /**+     * Intro preview of a HIDDEN layer (adom/adom-3d-viewer#8): after the+     * model loads, fade the layer in at `fadeInAt` seconds, hold it, fade it+     * out by `fadeOutAt`, and while it shows render its panel toggle as+     * pressed and pulsing, so the reader learns the switch exists. Afterwards+     * the layer rests hidden and the toggle rests off. A click on the toggle+     * during the intro keeps the layer on (the reader asked for it).+     */+    type LayerIntro = { fadeInAt: number; fadeOutAt: number; highlightButton: boolean; fadeMs: number };     type DetectedLayer = {         name: string; label: string; group: string | null;         visible: boolean; meshes: AbstractMesh[]; declared: boolean;+        intro: LayerIntro | null; introActive: boolean;     };+    /** Play declared layer intros after load (the page passes false with animate=0). */+    export let intros: boolean = true;      /** Sanitize a declared spec: content is untrusted and ends up in the DOM. */     function normalizeSpec(raw: any): LayerSpec | null {@@ -359,7 +371,19 @@         if (!key || key.length > 64) return null;         const label = typeof raw.label === 'string' && raw.label.trim() ? raw.label.trim().slice(0, 64) : undefined;         const group = typeof raw.group === 'string' && raw.group.trim() ? raw.group.trim().slice(0, 64) : undefined;-        return { key: key.slice(0, 64), label, group, hidden: raw.hidden === true };+        return { key: key.slice(0, 64), label, group, hidden: raw.hidden === true, intro: raw.hidden === true ? normalizeIntro(raw.intro) : undefined };+    }+    /** An intro only makes sense on a hidden layer; bad numbers fall back. */+    function normalizeIntro(raw: any): LayerIntro | undefined {+        if (!raw || typeof raw !== 'object') return undefined;+        const num = (v: any, d: number, lo: number, hi: number) => { const n = Number(v); return Number.isFinite(n) ? Math.min(hi, Math.max(lo, n)) : d; };+        const fadeInAt = num(raw.fadeInAt, 1.5, 0, 120);+        // A fade-out at or before the fade-in is nonsense: fall back to the+        // default hold rather than clamp it into a blink.+        const outRaw = Number(raw.fadeOutAt);+        const fadeOutAt = Number.isFinite(outRaw) && outRaw > fadeInAt ? Math.min(600, outRaw) : fadeInAt + 5;+        const fadeMs = num(raw.fadeMs, 700, 100, 5000);+        return { fadeInAt, fadeOutAt, highlightButton: raw.highlightButton !== false, fadeMs };     }      /**@@ -429,6 +453,7 @@                     group: spec.group || null,                     visible, meshes,                     declared: !BUILTIN_BY_KEY.has(name),+                    intro: spec.intro || null, introActive: false,                 };             });         // A lone NAME-matched layer is suppressed (a model that is entirely@@ -462,6 +487,7 @@     export function setLayerVisible(name: string, visible: boolean): boolean {         const layer = layers.find(l => l.name === name);         if (!layer) return false;+        if (introRuns.has(name) || layer.introActive) cancelIntro(layer);         layer.visible = visible;         layer.meshes.forEach(m => { m.isVisible = visible; });         layers = layers; // trigger svelte reactivity@@ -471,7 +497,88 @@      function toggleLayerRow(name: string): void {         const layer = layers.find(l => l.name === name);-        if (layer) setLayerVisible(name, !layer.visible);+        if (!layer) return;+        // Pressed during its intro: the reader wants the layer, keep it on.+        if (layer.introActive) { cancelIntro(layer); setLayerVisible(name, true); return; }+        setLayerVisible(name, !layer.visible);+    }++    // ---- Layer intros (adom/adom-3d-viewer#8) ------------------------------+    // Timers and a per-frame observer per layer; everything cancels on a+    // user toggle, a replay, a new model or clearScene.+    type IntroRun = { timers: number[]; observer: any; layer: DetectedLayer };+    const introRuns = new Map<string, IntroRun>();+    let introsScheduled = false;++    function setLayerAlpha(layer: DetectedLayer, alpha: number): void {+        layer.meshes.forEach(m => { m.visibility = alpha; });+    }+    function rampLayer(run: IntroRun, from: number, to: number, ms: number, done: () => void): void {+        const scene = AdomStatics.scene;+        if (!scene) { setLayerAlpha(run.layer, to); done(); return; }+        const t0 = performance.now();+        if (run.observer) { scene.onBeforeRenderObservable.remove(run.observer); run.observer = null; }+        run.observer = scene.onBeforeRenderObservable.add(() => {+            const k = Math.min(1, (performance.now() - t0) / ms);+            const eased = k < 0.5 ? 2 * k * k : 1 - Math.pow(-2 * k + 2, 2) / 2;+            setLayerAlpha(run.layer, from + (to - from) * eased);+            if (k >= 1) { scene.onBeforeRenderObservable.remove(run.observer); run.observer = null; done(); }+        });+    }+    function cancelIntro(layer: DetectedLayer): void {+        const run = introRuns.get(layer.name);+        if (run) {+            run.timers.forEach(t => clearTimeout(t));+            if (run.observer && AdomStatics.scene) AdomStatics.scene.onBeforeRenderObservable.remove(run.observer);+            introRuns.delete(layer.name);+        }+        setLayerAlpha(layer, 1);+        if (layer.introActive) { layer.introActive = false; layer.meshes.forEach(m => { m.isVisible = layer.visible; }); layers = layers; }+    }+    function scheduleIntros(): void {+        stopIntros();+        if (!intros) return;+        for (const layer of layers) {+            if (!layer.intro || layer.visible) continue;+            const it = layer.intro;+            const run: IntroRun = { timers: [], observer: null, layer };+            introRuns.set(layer.name, run);+            run.timers.push(window.setTimeout(() => {+                if (layer.visible) { introRuns.delete(layer.name); return; }+                layer.introActive = true; layers = layers;+                setLayerAlpha(layer, 0);+                layer.meshes.forEach(m => { m.isVisible = true; });+                AdomStatics.refreshShadows();+                rampLayer(run, 0, 1, it.fadeMs, () => {});+            }, it.fadeInAt * 1000));+            run.timers.push(window.setTimeout(() => {+                if (!layer.introActive) return;+                rampLayer(run, 1, 0, it.fadeMs, () => {+                    layer.meshes.forEach(m => { m.isVisible = false; m.visibility = 1; });+                    layer.introActive = false; layers = layers;+                    introRuns.delete(layer.name);+                    AdomStatics.refreshShadows();+                });+            }, it.fadeOutAt * 1000));+        }+        introsScheduled = introRuns.size > 0;+    }+    /** Cancel every running or pending intro; layers rest at their own state. */+    export function stopIntros(): void {+        for (const layer of [...introRuns.values()].map(r => r.layer)) cancelIntro(layer);+        introRuns.clear();+        introsScheduled = false;+    }+    /** Replay the declared intros from the start (the reader's replay control). */+    export function replayIntros(): boolean {+        if (!layers.some(l => l.intro)) return false;+        const saved = intros; intros = true;+        scheduleIntros();+        intros = saved;+        return true;+    }+    export function getIntros(): { name: string; fadeInAt: number; fadeOutAt: number; highlightButton: boolean; active: boolean; pending: boolean }[] {+        return layers.filter(l => l.intro).map(l => ({ name: l.name, fadeInAt: l.intro!.fadeInAt, fadeOutAt: l.intro!.fadeOutAt, highlightButton: l.intro!.highlightButton, active: l.introActive, pending: introRuns.has(l.name) && !l.introActive }));     }      /** "Adom.LED.State" -> "LED State"; "mpn-marking" -> "Mpn marking". */@@ -832,6 +939,7 @@             detectStateGroups();             mitigateCoplanarFighting(result.meshes);             frameModel();+            scheduleIntros();         }     } @@ -935,6 +1043,7 @@     export function clearScene(): void {         // Content lights hang off transform nodes, not meshes, so disposing the         // mesh roots can leave them lighting the NEXT model. Dispose them here.+        stopIntros();         contentLights?.clear();         loadedRootNodes.forEach((node) => node.dispose());         for (const g of stateGroups) for (const r of g.roots) { try { r.dispose?.(false, true); } catch { /* already gone */ } }@@ -1492,6 +1601,9 @@             </button>             {#if layersPanelOpen}                 <div class="layers-panel">+                    {#if layers.some(l => l.intro)}+                        <button type="button" class="layers-replay" title="Play the layer intro again" on:click={() => replayIntros()}>Replay intro</button>+                    {/if}                     {#if stateGroups.length > 0}                         <div class="layers-group">Parts</div>                         {#each stateGroups as group (group.key)}@@ -1510,10 +1622,10 @@                             <div class="layers-group">{section.group}</div>                         {/if}                         {#each section.items as layer (layer.name)}-                            <label class="layers-row">+                            <label class="layers-row" class:intro={layer.introActive && layer.intro?.highlightButton !== false}>                                 <input                                     type="checkbox"-                                    checked={layer.visible}+                                    checked={layer.visible || layer.introActive}                                     on:change={() => toggleLayerRow(layer.name)}                                 />                                 <span>{layer.label}</span>@@ -1658,6 +1770,11 @@         user-select: none;     }     .layers-row:hover { background: rgba(255, 255, 255, 0.08); }+    .layers-row.intro { background: rgba(0, 184, 176, 0.18); animation: a3d-intro-pulse 1.2s ease-in-out infinite; }+    .layers-row.intro input { box-shadow: 0 0 0 2px rgba(0, 230, 220, 0.6); border-radius: 3px; }+    @keyframes a3d-intro-pulse { 0%, 100% { background: rgba(0, 184, 176, 0.12); } 50% { background: rgba(0, 184, 176, 0.3); } }+    .layers-replay { display: block; width: 100%; margin: 0 0 6px; padding: 4px 8px; border: 1px solid rgba(0, 184, 176, 0.35); border-radius: 6px; background: rgba(0, 184, 176, 0.1); color: #e6edf3; font: inherit; font-size: 12px; cursor: pointer; }+    .layers-replay:hover { background: rgba(0, 184, 176, 0.2); }     .layers-row input { accent-color: #00b8b0; cursor: pointer; }      /* Orbit-center chip — live indicator while shift+alt is held, and the
standalone.ts+13
@@ -77,6 +77,13 @@ interface ViewerInstance {    *  content asked for the layer rather than matching the built-in names. */   getLayers: () => { name: string; label: string; group: string | null; visible: boolean; declared: boolean }[];   setLayerVisible: (name: string, visible: boolean) => boolean;+  /** Intro previews declared on hidden layers (extras.adomLayer.intro,+   *  adom/adom-3d-viewer#8): what is declared and whether it is playing. */+  getIntros: () => { name: string; fadeInAt: number; fadeOutAt: number; highlightButton: boolean; active: boolean; pending: boolean }[];+  /** Play the declared intros again from the start; false when none declared. */+  replayIntros: () => boolean;+  /** Cancel every running or pending intro. */+  stopIntros: () => void;   /** Switchable groups the GLB declares (extras.adomRole, or an Adom.<Name>    *  node): Adom.LED.State carries the lens skin AND its light, so switching    *  the group off turns both off. One entry per role, every placement behind@@ -130,6 +137,8 @@ function init(container: HTMLElement, options?: {    *  (default 4). A board with forty lit LEDs keeps the nearest and brightest    *  this many; the rest stay emissive-only. 0 leaves them all off. */   lightBudget?: number;+  /** Play layer intros declared in the GLB (extras.adomLayer.intro); default true. */+  intros?: boolean; }): ViewerInstance {   const opts = options || {}; @@ -148,6 +157,7 @@ function init(container: HTMLElement, options?: {       onMeshHover: opts.onMeshHover,       onGroundCreated: opts.onGroundCreated,       lightBudget: opts.lightBudget !== undefined ? opts.lightBudget : 4,+      intros: opts.intros !== false,     },   }); @@ -184,6 +194,9 @@ function init(container: HTMLElement, options?: {     captureScreenshot: (o?: { width?: number; height?: number }) => component.captureScreenshot(o),     getLayers: () => component.getLayers(),     setLayerVisible: (name: string, visible: boolean) => component.setLayerVisible(name, visible),+    getIntros: () => component.getIntros(),+    replayIntros: () => component.replayIntros(),+    stopIntros: () => component.stopIntros(),     getStateGroups: () => component.getStateGroups(),     setStateGroupEnabled: (key: string, enabled: boolean) => component.setStateGroupEnabled(key, enabled),     setStateInstanceEnabled: (key: string, index: number, enabled: boolean) => component.setStateInstanceEnabled(key, index, enabled),