@leverege/tpi-viz 0.2.0

package/src/main.js

@@ -0,0 +1,2616 @@
+// tpi-viz scene viewer entry point — THIN BOOTSTRAP.
+//
+// Bundled by Vite into a single self-contained dist/index.html via
+// vite-plugin-singlefile. Python (tpi.viz.templates.bundle_html_template) reads
+// dist/index.html and substitutes the scene JSON into the SCENE_DATA placeholder.
+//
+// All THREE/WebGL rendering + kinematics live in @leverege/tpi-viz-renderer
+// (the SceneRenderer over the pure, Node-testable scene model). This file:
+//   - parses ?scene=<name>, sets <base>, fetches /scenes/<name>/scene.json
+//   - calls renderer.applyScene(data) to hydrate
+//   - wires the existing DOM UI (toggles, Views/Projection/POV controls,
+//     bookmarks, flow playback, image panel) to renderer methods.
+
+import './styles/viewer_common.css';
+import './styles/scene_viewer.css';
+
+import * as THREE from 'three';
+import { STLLoader } from 'three/addons/loaders/STLLoader.js';
+import { createSceneRenderer, AXIS_Q6135LE_SENSOR, computeKinematics } from '@leverege/tpi-viz-renderer';
+import { assembleShellScene, createHttpFetcher } from '@leverege/tpi-viz-renderer/loader';
+
+import { VIEWER_SKELETON } from './skeleton.js';
+
+// ═══════════════════════════════════════════════════════════════
+// State
+// ═══════════════════════════════════════════════════════════════
+
+let sceneData = null;
+let renderer = null;             // SceneRenderer instance
+let raycaster = null;
+let mouse = null;
+
+// Mount lifecycle (so the viewer can be embedded in a host app — e.g. a React
+// route — and torn down cleanly on unmount). `_alive` gates the self-perpetuating
+// rAF loops; `_teardown` collects window/document listener removers; `_opts`
+// replaces URL parsing as the scene source.
+let _alive = false;
+let _opts = {};
+let _container = null;
+const _teardown = [];
+// Register a window/document listener AND remember how to remove it on destroy.
+// (Element listeners inside the injected skeleton are freed when the container
+// is cleared, so only window/document ones need tracking.)
+function on( target, ev, fn, opts ) {
+    target.addEventListener( ev, fn, opts );
+    _teardown.push( () => target.removeEventListener( ev, fn, opts ) );
+}
+
+// Convenience getters proxying the renderer's pure model + THREE state. Keeping
+// these as functions (not cached) means UI code always reads live values after
+// a camera/flow mutation.
+const cam = () => renderer.camera;
+const controls = () => renderer.controls;
+const layerGroups = () => renderer.layerGroups;
+const cameraEntries = () => renderer.cameras;          // model camera descriptors
+const flowData = () => renderer.flowData;
+const flowsByUseCase = () => renderer.flowsByUseCase;
+const cameraColors = () => renderer.cameras.map(c => c.color);
+const cameraImagePlanes = () => renderer.cameraImagePlanes;
+const cameraFrustumGroups = () => renderer.cameraFrustumGroups;
+const defectEntries = () => renderer.defects;
+const projectionMode = () => renderer.projectionMode;
+
+let selectedCameraIdx = -1;
+let povCameraIdx = -1;          // which camera is in POV mode (-1 = none)
+let prevCameraState = null;     // saved camera state for restoring after POV
+let syncProjectionUI = null;    // set by buildPovControls: (mode) => highlight active button
+
+function switchProjection(mode) {
+    const result = renderer.switchProjection(mode);
+    return result;
+}
+
+// Flow state
+let activeFlowName = null;
+let activeFlowSteps = [];
+let currentStepIndex = 0;
+
+// Per-flow play state: flowName → { intervalId, stepIndex }
+const playingFlows = {};
+
+// Image state (for step images carousel)
+let currentImages = [];
+let currentLaserMasks = [];
+let currentProjectedContour = null;
+let currentAlignedContours = [];  // parallel to images
+let currentLaserScores = [];      // parallel to images
+let currentImageIdx = 0;
+let laserOverlayEnabled = false;
+let scoreOverlayEnabled = false;
+let projectedOverlayEnabled = false;
+let alignedOverlayEnabled = false;
+
+// Lightbox state
+let lightboxOpen = false;
+
+// PTZ slider references (so flow steps can update slider DOM)
+let activePTZSliders = null; // { pan: {input, valueSpan}, tilt: ..., zoom: ... }
+
+// ═══════════════════════════════════════════════════════════════
+// Init
+// ═══════════════════════════════════════════════════════════════
+
+async function loadSceneData() {
+    // Scene source comes from mount opts (set by mountViewer), not the URL —
+    // the standalone entry derives opts from the URL and passes them in.
+    // Live mode: build the scene DYNAMICALLY from a shell id, with no
+    // precomputed scene.json. assembleShellScene returns the exact
+    // {layers, flows, viewPresets} shape applyScene + the panels consume, so
+    // the rest of init() is unchanged. The http fetcher talks to same-origin
+    // Imaginarium proxy routes (CSP-safe); configId selects the Imagine system.
+    const shellId = _opts.shellId;
+    if (shellId) {
+        try {
+            const fetcher = createHttpFetcher({ configId: _opts.configId || null });
+            return await assembleShellScene({ shellId, fetcher, STLLoader });
+        } catch (err) {
+            document.getElementById('loading').textContent =
+                `Failed to build shell "${shellId}": ${err.message}`;
+            return null;
+        }
+    }
+    // Embedded mode: a host app (e.g. Imaginarium) passes an explicit, possibly
+    // authenticated scene URL. Fetch it directly with credentials; resolve flow
+    // images against the URL's parent path via <base>.
+    const sceneUrl = _opts.sceneUrl;
+    if (sceneUrl) {
+        try {
+            const resp = await fetch(sceneUrl, { credentials: 'include' });
+            if (!resp.ok) throw new Error(`HTTP ${resp.status} fetching ${sceneUrl}`);
+            const sb = document.getElementById('scene-base');
+            if (sb) sb.href = sceneUrl.replace(/[^/]*$/, '');
+            return await resp.json();
+        } catch (err) {
+            document.getElementById('loading').textContent =
+                `Failed to load scene: ${err.message}`;
+            return null;
+        }
+    }
+    const name = _opts.scene;
+    if (!name) {
+        document.getElementById('loading').classList.add('hidden');
+        document.getElementById('no-scene').classList.remove('hidden');
+        await populateAvailableScenes();
+        return null;
+    }
+    // Resolve relative paths in scene.json (images/foo.jpg, …) against the
+    // scene's directory by setting <base href>.
+    { const sb = document.getElementById('scene-base'); if (sb) sb.href = `/scenes/${name}/`; }
+    const url = `/scenes/${encodeURIComponent(name)}/scene.json`;
+    try {
+        const resp = await fetch(url);
+        if (!resp.ok) throw new Error(`HTTP ${resp.status} fetching ${url}`);
+        return await resp.json();
+    } catch (err) {
+        document.getElementById('loading').textContent =
+            `Failed to load scene "${name}": ${err.message}`;
+        return null;
+    }
+}
+
+async function populateAvailableScenes() {
+    // Dev server's /scenes endpoint returns a JSON array of scene names.
+    try {
+        const resp = await fetch('/scenes');
+        if (!resp.ok) return;
+        const names = await resp.json();
+        if (!Array.isArray(names) || !names.length) return;
+
+        // Visualizer scripts prefix scene names by type (shell-, flow-, plylayers-, …).
+        // Group by prefix and label so the list is browsable instead of a wall.
+        const GROUP_LABELS = {
+            shell: 'Shells',
+            flow: 'Flows',
+            plylayers: 'Ply layers',
+            defects: 'Defects',
+            calibration_observations: 'Calibration',
+            flow_data: 'Flow data',
+        };
+        // Type → accent color (CSS custom property name). Drives the left-bar
+        // tint on each row + the group-header pill.
+        const GROUP_ACCENT = {
+            shell: '--accent-blue',
+            flow: '--accent-orange',
+            plylayers: '--accent-green',
+            defects: '--accent-pink',
+            calibration_observations: '--accent-amber',
+            flow_data: '--accent-blue',
+            other: '--text-3',
+        };
+        const groups = new Map();   // label → { prefix, items }
+        for (const name of names.slice().sort()) {
+            const prefix = name.split('-', 1)[0];
+            const label = GROUP_LABELS[prefix] || 'Other';
+            const key = GROUP_LABELS[prefix] ? prefix : 'other';
+            if (!groups.has(label)) groups.set(label, { prefix: key, items: [] });
+            groups.get(label).items.push(name);
+        }
+
+        const container = document.getElementById('available-scenes');
+        container.innerHTML = '';
+        for (const [label, { prefix, items }] of groups) {
+            const accent = `var(${GROUP_ACCENT[prefix] || '--text-3'})`;
+            const group = document.createElement('div');
+            group.className = 'landing-scene-group';
+            group.style.setProperty('--group-accent', accent);
+
+            const head = document.createElement('div');
+            head.className = 'landing-group-label';
+            head.innerHTML = `<span class="landing-group-name">${label}</span>`
+                + `<span class="landing-group-count">${items.length}</span>`;
+            group.appendChild(head);
+
+            for (const name of items) {
+                // Strip the type prefix from the visible label (it's
+                // redundant — the row is already inside that group).
+                const dashIdx = name.indexOf('-');
+                const identifier = dashIdx >= 0 ? name.slice(dashIdx + 1) : name;
+
+                const a = document.createElement('a');
+                a.className = 'landing-scene-link';
+                a.href = `?scene=${encodeURIComponent(name)}`;
+                a.dataset.sceneName = name.toLowerCase();
+                a.innerHTML =
+                    `<span class="landing-scene-id">${identifier || name}</span>`
+                    + `<span class="landing-scene-arrow">→</span>`;
+                group.appendChild(a);
+            }
+            container.appendChild(group);
+        }
+
+        document.getElementById('scenes-count').textContent = `· ${names.length}`;
+
+        const filter = document.getElementById('scenes-filter');
+        filter.addEventListener('input', () => {
+            const q = filter.value.trim().toLowerCase();
+            for (const group of container.querySelectorAll('.landing-scene-group')) {
+                let visible = 0;
+                for (const link of group.querySelectorAll('.landing-scene-link')) {
+                    const match = !q || link.dataset.sceneName.includes(q);
+                    link.style.display = match ? '' : 'none';
+                    if (match) visible++;
+                }
+                group.style.display = visible ? '' : 'none';
+            }
+        });
+
+        document.getElementById('available-scenes-wrap').classList.remove('hidden');
+    } catch (e) {
+        // No listing available; that's fine.
+    }
+}
+
+async function init() {
+    sceneData = await loadSceneData();
+    if (!sceneData) return;
+
+    const canvas = document.getElementById('threeCanvas');
+    renderer = createSceneRenderer(canvas);
+
+    raycaster = new THREE.Raycaster();
+    mouse = new THREE.Vector2();
+
+    // Hydrate the whole scene through the renderer (the Python path). This
+    // parses cameras/flows/presets into the pure model and builds all THREE
+    // layers + projections.
+    renderer.applyScene(sceneData);
+
+    const layers = sceneData.layers || [];
+    buildLayerToggles(layers);
+    buildPovControls(renderer.viewPresets || {});
+    buildCameraTree();
+
+    // Update contour projections when any contour layer toggle changes
+    document.getElementById('layer-toggles').addEventListener('change', (e) => {
+        if (e.target.type === 'checkbox') {
+            requestAnimationFrame(() => {
+                renderer.updateContourProjections();
+                updateImagePanel();
+            });
+        }
+    });
+
+    // Apply default view preset to initialize camera at the right position
+    const defaultPreset = (renderer.viewPresets || {}).default;
+    if (defaultPreset) {
+        cam().position.set(...defaultPreset.position);
+        controls().target.set(...defaultPreset.target);
+        controls().update();
+    }
+
+    canvas.addEventListener('click', onCanvasClick);
+
+    on( document, 'keydown',(e) => {
+        if (e.target.tagName === 'INPUT') return;
+        if (!activeFlowName) return;
+        if (e.key === 'ArrowRight') { nextStep(); e.preventDefault(); }
+        if (e.key === 'ArrowLeft')  { prevStep(); e.preventDefault(); }
+        if (e.key === 'l' || e.key === 'L') { laserOverlayEnabled = !laserOverlayEnabled; updateImagePanel(); updateLightbox(); e.preventDefault(); }
+        if (e.key === 's' || e.key === 'S') { scoreOverlayEnabled = !scoreOverlayEnabled; updateImagePanel(); updateLightbox(); e.preventDefault(); }
+        if (e.key === 'p' || e.key === 'P') { projectedOverlayEnabled = !projectedOverlayEnabled; updateImagePanel(); updateLightbox(); e.preventDefault(); }
+        if (e.key === ';' || e.key === ':') { alignedOverlayEnabled = !alignedOverlayEnabled; updateImagePanel(); updateLightbox(); e.preventDefault(); }
+        if (e.key === ' ') { togglePlay(); e.preventDefault(); }
+    });
+
+    // ── Scene-derived scale: the default preset ships with camera and
+    //    target at sensible positions for the scene; their distance is a
+    //    natural unit for "how big this scene is." All nav speeds and the
+    //    gizmo size derive from it.
+    const SCENE_SCALE = controls().target.distanceTo(cam().position) || 30000;
+
+    // ── WASD / QE camera fly. W/S forward, A/D strafe, Q/E up/down.
+    //    Camera AND orbit target translate together so the gizmo (orbit
+    //    pivot) follows the camera at fixed offset.
+    const FLY = {
+        step:     SCENE_SCALE * 0.005,  // mm per frame, regardless of zoom
+        stepFast: SCENE_SCALE * 0.02,   // with shift held
+    };
+    const _flyKeys = new Set();
+    const _fwd = new THREE.Vector3();
+    const _right = new THREE.Vector3();
+    const _worldUp = new THREE.Vector3(0, 0, 1);
+    controls().enableZoom = false;
+    on( document, 'keydown',(e) => {
+        if (e.target.tagName === 'INPUT') return;
+        const k = e.key.toLowerCase();
+        if (['w','a','s','d','q','e'].includes(k)) {
+            if (k === 'a' && activeFlowName) { prevImage(); e.preventDefault(); return; }
+            if (k === 'd' && activeFlowName) { nextImage(); e.preventDefault(); return; }
+            _flyKeys.add(k);
+            e.preventDefault();
+        }
+    });
+    on( document, 'keyup', (e) => {
+        const k = e.key.toLowerCase();
+        if (['w','a','s','d','q','e'].includes(k)) _flyKeys.delete(k);
+    });
+    on( window, 'blur', () => _flyKeys.clear());
+
+    // Keep near/far in lock-step with orbit-distance so zooming in/out
+    //    doesn't clip the scene. Recomputed every frame via rAF.
+    function _updateClipPlanes() {
+        if (!_alive) return;
+        requestAnimationFrame(_updateClipPlanes);
+        const c = cam();
+        const dist = controls().target.distanceTo(c.position);
+        const near = Math.max(1, dist * 0.001);
+        const far  = Math.max(200000, dist * 100);
+        if (Math.abs(c.near - near) > 0.5 || Math.abs(c.far - far) > 1) {
+            c.near = near;
+            c.far  = far;
+            c.updateProjectionMatrix();
+        }
+    }
+    _updateClipPlanes();
+
+    function _translate(move) {
+        // Translate both camera and orbit target by the same vector so
+        //    the gizmo follows the camera as you fly.
+        cam().position.add(move);
+        controls().target.add(move);
+    }
+
+    function _flyTick() {
+        if (!_alive) return;
+        requestAnimationFrame(_flyTick);
+        if (_flyKeys.size === 0) return;
+        const step = _flyKeys.has('shift') ? FLY.stepFast : FLY.step;
+        cam().getWorldDirection(_fwd);
+        _right.crossVectors(_fwd, _worldUp);
+        if (_right.lengthSq() < 1e-9) _right.set(1, 0, 0); else _right.normalize();
+        const move = new THREE.Vector3();
+        if (_flyKeys.has('w')) move.addScaledVector(_fwd, step);
+        if (_flyKeys.has('s')) move.addScaledVector(_fwd, -step);
+        if (_flyKeys.has('d')) move.addScaledVector(_right, step);
+        if (_flyKeys.has('a')) move.addScaledVector(_right, -step);
+        if (_flyKeys.has('e')) move.addScaledVector(_worldUp, step);
+        if (_flyKeys.has('q')) move.addScaledVector(_worldUp, -step);
+        if (move.lengthSq() > 0) _translate(move);
+    }
+
+    // ── Orbit dolly + gizmo config. Two knobs for the gizmo: size +
+    //    opacity. Everything else (ring tube, spoke radius, arrow size,
+    //    hub size) is a fixed ratio of `size`.
+    const ORBIT = {
+        distMin: SCENE_SCALE * 0.005,
+        distMax: SCENE_SCALE * 1000,
+        factor:     1.07,              // exponential per wheel tick
+        factorFast: 1.25,              // with shift
+    };
+    const GIZMO = {
+        size:    SCENE_SCALE * 0.006,  // outer ring radius
+        opacity: 0.9,                  // peak opacity while interacting
+    };
+
+    function _buildGizmo({ size, opacity }) {
+        const group = new THREE.Group();
+        const mats  = [];
+        const _Y = new THREE.Vector3(0, 1, 0);
+        const _Z = new THREE.Vector3(0, 0, 1);
+        const flatMat = (color) => {
+            const m = new THREE.MeshBasicMaterial({ color, transparent: true, opacity: 0.0, depthTest: false });
+            mats.push(m);
+            return m;
+        };
+        const add = (mesh) => { mesh.renderOrder = 999; group.add(mesh); };
+
+        const ringGeo  = new THREE.TorusGeometry(size, size * 0.036, 10, 56);
+        const spokeGeo = new THREE.CylinderGeometry(size * 0.024, size * 0.024, size, 12);
+        const arrowGeo = new THREE.ConeGeometry(size * 0.072, size * 0.18, 16);
+        const hubGeo   = new THREE.SphereGeometry(size * 0.09, 16, 12);
+
+        const axes = [
+            { axis: [1, 0, 0], color: 0xff3366 },
+            { axis: [0, 1, 0], color: 0x33dd66 },
+            { axis: [0, 0, 1], color: 0x3399ff },
+        ];
+        for (const { axis, color } of axes) {
+            const a = new THREE.Vector3().fromArray(axis).normalize();
+            const qSpoke = new THREE.Quaternion().setFromUnitVectors(_Y, a);
+            const qRing  = new THREE.Quaternion().setFromUnitVectors(_Z, a);
+
+            const ring = new THREE.Mesh(ringGeo, flatMat(color));
+            ring.quaternion.copy(qRing);
+            add(ring);
+
+            const spoke = new THREE.Mesh(spokeGeo, flatMat(color));
+            spoke.position.copy(a).multiplyScalar(size / 2);
+            spoke.quaternion.copy(qSpoke);
+            add(spoke);
+
+            const arrow = new THREE.Mesh(arrowGeo, flatMat(color));
+            arrow.position.set(size, 0, 0).applyQuaternion(qRing);
+            arrow.quaternion.copy(qRing);
+            add(arrow);
+        }
+
+        add(new THREE.Mesh(hubGeo, flatMat(0xcccccc)));
+        return { group, mats, opacity };
+    }
+
+    const _gizmo = _buildGizmo(GIZMO);
+    renderer.scene.add(_gizmo.group);
+
+    // ── Visibility: full opacity while interacting, fades shortly after.
+    const GIZMO_HOLD_MS = 400;
+    const GIZMO_FADE_MS = 600;
+    let _gizmoFadeAt  = 0;
+    let _gizmoHolding = false;
+    function _pingGizmo() { _gizmoFadeAt = performance.now() + GIZMO_HOLD_MS; }
+    canvas.addEventListener('pointerdown', () => { _gizmoHolding = true;  _pingGizmo(); });
+    on( window, 'pointerup', () => { _gizmoHolding = false; _pingGizmo(); });
+
+    (function _gizmoTick() {
+        if (!_alive) return;
+        requestAnimationFrame(_gizmoTick);
+        // In POV the orbit controls are disabled — the pivot can't move, so the
+        // anchor gizmo is meaningless. Keep it fully hidden there.
+        if (povCameraIdx >= 0) {
+            if (_gizmo.group.visible) _gizmo.group.visible = false;
+            return;
+        }
+        _gizmo.group.position.copy(controls().target);
+        const now = performance.now();
+        let opacity;
+        if (_gizmoHolding || now <= _gizmoFadeAt) {
+            opacity = _gizmo.opacity;
+        } else {
+            const t = (now - _gizmoFadeAt) / GIZMO_FADE_MS;
+            opacity = Math.max(0, _gizmo.opacity * (1 - t));
+        }
+        for (const m of _gizmo.mats) m.opacity = opacity;
+        _gizmo.group.visible = opacity > 0.001;
+    })();
+
+    // ── Scroll = exponential dolly. Camera moves toward/away pivot;
+    //    pivot stays put.
+    canvas.addEventListener('wheel', (e) => {
+        e.preventDefault();
+        const factor = e.shiftKey ? ORBIT.factorFast : ORBIT.factor;
+        const c = cam();
+        const offset = c.position.clone().sub(controls().target);
+        let dist = Math.max(1, offset.length());
+        offset.divideScalar(dist);
+        dist = e.deltaY < 0 ? dist / factor : dist * factor;   // wheel up = dolly in
+        dist = Math.max(ORBIT.distMin, Math.min(ORBIT.distMax, dist));
+        c.position.copy(controls().target).addScaledVector(offset, dist);
+        _pingGizmo();
+    }, { passive: false });
+    on( document, 'keydown',(e) => { if (e.key === 'Shift') _flyKeys.add('shift'); });
+    on( document, 'keyup',   (e) => { if (e.key === 'Shift') _flyKeys.delete('shift'); });
+    _flyTick();
+
+    document.getElementById('close-right-panel').addEventListener('click', () => {
+        deselectFlow();
+        selectCamera(-1);
+    });
+
+    document.getElementById('btn-prev-step').addEventListener('click', () => { stopPlay(); prevStep(); });
+    document.getElementById('btn-next-step').addEventListener('click', () => { stopPlay(); nextStep(); });
+    document.getElementById('btn-play-stop').addEventListener('click', togglePlay);
+    document.getElementById('btn-prev-img').addEventListener('click', prevImage);
+    document.getElementById('btn-next-img').addEventListener('click', nextImage);
+
+    document.getElementById('step-image').addEventListener('click', toggleLightbox);
+    document.getElementById('step-image-canvas').addEventListener('click', toggleLightbox);
+    document.getElementById('btn-laser-overlay').addEventListener('click', () => {
+        laserOverlayEnabled = !laserOverlayEnabled;
+        updateImagePanel(); updateLightbox();
+    });
+    document.getElementById('btn-score-overlay').addEventListener('click', () => {
+        scoreOverlayEnabled = !scoreOverlayEnabled;
+        updateImagePanel(); updateLightbox();
+    });
+    document.getElementById('btn-projected-overlay').addEventListener('click', () => {
+        projectedOverlayEnabled = !projectedOverlayEnabled;
+        updateImagePanel(); updateLightbox();
+    });
+    document.getElementById('btn-aligned-overlay').addEventListener('click', () => {
+        alignedOverlayEnabled = !alignedOverlayEnabled;
+        updateImagePanel(); updateLightbox();
+    });
+    document.getElementById('close-lightbox').addEventListener('click', closeLightbox);
+    document.getElementById('lightbox-prev').addEventListener('click', prevImage);
+    document.getElementById('lightbox-next').addEventListener('click', nextImage);
+    setupLightboxResize();
+
+    document.getElementById('loading').classList.add('hidden');
+    document.getElementById('app').classList.remove('hidden');
+    renderer.resize();
+}
+
+// updateCameraVisuals — delegate the rebuild to the renderer, then re-apply
+// flow image + POV hide (this bootstrap owns flow + POV state).
+function updateCameraVisuals(idx) {
+    renderer.updateCameraVisuals(idx, {
+        afterRebuild: (camIdx, frustumGroup) => {
+            // Re-apply image to new plane if one is active for this camera.
+            const activeFlow = activeFlowName ? flowData()[activeFlowName] : null;
+            if (activeFlow && renderer.findCameraIdx(activeFlow.cameraId) === camIdx && currentImages.length > 0) {
+                setFrustumImage(camIdx, currentImages[currentImageIdx]);
+            }
+            // Keep POV in sync when PTZ changes. The frustum was rebuilt with all
+            // children visible — re-apply the POV hide (wireframe off, textured
+            // image plane on) or it flashes back into the POV view.
+            if (povCameraIdx === camIdx) {
+                applyPOV(camIdx);
+                frustumGroup?.children.forEach(child => {
+                    if (child.name === 'frustum_image_plane') renderer.refreshFrustumImageVisibility(child);
+                    else child.visible = false;
+                });
+            }
+        },
+    });
+}
+
+// ═══════════════════════════════════════════════════════════════
+// UI: Layer toggles
+// ═══════════════════════════════════════════════════════════════
+
+function buildLayerToggles(layers) {
+    const container = document.getElementById('layer-toggles');
+    container.innerHTML = '';
+
+    // Separate contour layers from other layers
+    const contourLayers = layers.filter(l => l.type.startsWith('contours'));
+    const otherLayers = layers.filter(l => !l.type.startsWith('contours'));
+
+    // Render non-contour, non-camera layers as simple toggles
+    for (const layer of otherLayers) {
+        if (layer.type === 'cameras') {
+            buildCameraLayerTree(container, layer);
+        } else {
+            container.appendChild(buildToggle(layer.type, layer.label, layer.visible, layer.data));
+        }
+    }
+
+    // Render contour layers as a collapsible tree
+    if (contourLayers.length > 0) {
+        buildContourTree(container, contourLayers);
+    }
+}
+
+function buildToggle(key, labelText, checked, data) {
+    const div = document.createElement('div');
+    div.className = 'layer-toggle';
+
+    const checkbox = document.createElement('input');
+    checkbox.type = 'checkbox';
+    checkbox.checked = checked;
+    checkbox.id = `layer-${key}`;
+
+    const label = document.createElement('label');
+    label.className = 'layer-label';
+    label.textContent = labelText;
+    label.htmlFor = checkbox.id;
+
+    const count = document.createElement('span');
+    count.className = 'layer-count';
+    if (Array.isArray(data)) count.textContent = data.length;
+
+    checkbox.addEventListener('change', () => {
+        const group = layerGroups()[key];
+        if (group) group.visible = checkbox.checked;
+    });
+
+    div.appendChild(checkbox);
+    div.appendChild(label);
+    div.appendChild(count);
+    return div;
+}
+
+function buildSubToggle(key, labelText, checked, opts = {}) {
+    const div = document.createElement('div');
+    div.className = 'layer-toggle layer-sub-toggle';
+
+    const cb = document.createElement('input');
+    cb.type = 'checkbox';
+    cb.className = 'vis-cb';
+    cb.checked = checked;
+    cb.id = `layer-${key}`;
+    cb.title = 'Show / hide';
+
+    cb.addEventListener('change', () => {
+        const group = layerGroups()[key];
+        if (group) group.visible = cb.checked;
+    });
+
+    div.appendChild(cb);
+
+    const lbl = document.createElement('label');
+    lbl.className = 'layer-label';
+    lbl.textContent = labelText;
+    lbl.htmlFor = cb.id;
+    div.appendChild(lbl);
+
+    // Colour toggle sits at the far right of the row (label flexes between it
+    // and the show-box), mirroring the flow tree's play button.
+    if (opts.withHighlight) {
+        const hl = document.createElement('input');
+        hl.type = 'checkbox';
+        hl.className = 'hl-cb';
+        hl.checked = opts.highlightChecked ?? true;
+        hl.id = `hl-${key}`;
+        hl.title = 'Bright colour / dim';
+        hl.addEventListener('change', () => {
+            if (opts.onHighlightChange) opts.onHighlightChange(hl.checked);
+        });
+        div.appendChild(hl);
+    }
+
+    return div;
+}
+
+function buildTreeParent(container, key, labelText, checked, children, onToggleAll, opts = {}) {
+    // Parent row with expand arrow + checkbox
+    const div = document.createElement('div');
+    div.className = 'layer-toggle';
+
+    const arrow = document.createElement('span');
+    arrow.className = 'tree-arrow';
+    arrow.textContent = '▶';
+
+    const checkbox = document.createElement('input');
+    checkbox.type = 'checkbox';
+    checkbox.className = 'vis-cb';
+    checkbox.checked = checked;
+    checkbox.id = `layer-${key}`;
+    checkbox.title = 'Show / hide all';
+
+    const label = document.createElement('label');
+    label.className = 'layer-label';
+    label.textContent = labelText;
+    label.htmlFor = checkbox.id;
+
+    const count = document.createElement('span');
+    count.className = 'layer-count';
+    count.textContent = children.length;
+
+    // Children container (hidden by default)
+    const childContainer = document.createElement('div');
+    childContainer.className = 'tree-children';
+    childContainer.style.display = 'none';
+
+    // Expand/collapse
+    arrow.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const open = childContainer.style.display !== 'none';
+        childContainer.style.display = open ? 'none' : 'block';
+        arrow.textContent = open ? '▶' : '▼';
+    });
+
+    // Visibility cascade — fires only on `.vis-cb` descendants so the
+    // sibling highlight cascade stays independent.
+    checkbox.addEventListener('change', () => {
+        childContainer.querySelectorAll('input.vis-cb').forEach(cb => {
+            cb.checked = checkbox.checked;
+            cb.dispatchEvent(new Event('change'));
+        });
+        if (onToggleAll) onToggleAll(checkbox.checked);
+    });
+
+    div.appendChild(arrow);
+    div.appendChild(checkbox);
+    div.appendChild(label);
+    div.appendChild(count);
+
+    // Colour toggle pinned to the far right of the row (after the count),
+    // matching the per-row swatch position in the children below.
+    if (opts.withHighlight) {
+        const hl = document.createElement('input');
+        hl.type = 'checkbox';
+        hl.className = 'hl-cb';
+        hl.checked = opts.highlightChecked ?? true;
+        hl.id = `hl-${key}`;
+        hl.title = 'Bright colour / dim all';
+        hl.addEventListener('change', () => {
+            childContainer.querySelectorAll('input.hl-cb').forEach(c => {
+                c.checked = hl.checked;
+                c.dispatchEvent(new Event('change'));
+            });
+            if (opts.onHighlightToggleAll) opts.onHighlightToggleAll(hl.checked);
+        });
+        div.appendChild(hl);
+    }
+
+    container.appendChild(div);
+    container.appendChild(childContainer);
+
+    return childContainer;
+}
+
+// Highlight = bright HSL hue baked in by renderContours; dim = dark gray.
+// Each contour line carries `userData.highlight` (default true). The tree
+// rows expose a second checkbox per row that cascades from parent → children
+// just like visibility, but you can flip an individual ply afterwards.
+const DIM_CONTOUR_COLOR = 0x3a3a3a;
+
+function paintContourLine(line) {
+    if (!line.material || typeof line.userData?.hue !== 'number') return;
+    const hue = line.userData.hue;
+    if (line.userData.highlight !== false) {
+        line.material.color.setHSL(hue, 0.8, 0.6);
+    } else {
+        line.material.color.setHex(DIM_CONTOUR_COLOR);
+    }
+}
+
+// Update every line whose (layerType, lpdLayer, group) matches the given
+// scope. ``null`` means "any" — so passing only layerType repaints the
+// whole drawing, etc. Mirrors the cascade direction of visibility events.
+function applyHighlightToScope(layerType, lpdLayer, group, highlight) {
+    const root = layerGroups()[layerType];
+    if (!root) return;
+    root.traverse((obj) => {
+        if (typeof obj.userData?.hue !== 'number') return;
+        if (lpdLayer != null && obj.userData.layer !== lpdLayer) return;
+        if (group != null && obj.userData.group !== group) return;
+        obj.userData.highlight = highlight;
+        paintContourLine(obj);
+    });
+}
+
+function buildContourTree(container, contourLayers) {
+    const anyVisible = contourLayers.some(l => l.visible);
+    const childContainer = buildTreeParent(
+        container, 'contours_all', 'Laser Projections', anyVisible, contourLayers,
+        undefined,
+        { withHighlight: true, highlightChecked: true },
+    );
+
+    for (const layer of contourLayers) {
+        const data = Array.isArray(layer.data) ? layer.data : [];
+        const lpdLayerNames = [...new Set(data.map(c => c.layer).filter(Boolean))];
+
+        if (lpdLayerNames.length <= 1 && new Set(data.map(c => c.group)).size <= 1) {
+            // Single layer, single group — simple toggle
+            childContainer.appendChild(
+                buildSubToggle(layer.type, layer.label, layer.visible, {
+                    withHighlight: true,
+                    onHighlightChange: (checked) =>
+                        applyHighlightToScope(layer.type, null, null, checked),
+                })
+            );
+            continue;
+        }
+
+        // Drawing with multiple layers/groups — expandable
+        const drawingChildren = buildTreeParent(
+            childContainer, layer.type, layer.label, layer.visible, lpdLayerNames,
+            (checked) => {
+                const grp = layerGroups()[layer.type];
+                if (grp) grp.visible = checked;
+            },
+            { withHighlight: true },
+        );
+
+        for (const lpdLayerName of lpdLayerNames) {
+            // Get groups within this layer
+            const layerContours = data.filter(c => c.layer === lpdLayerName);
+            const grpNames = [...new Set(layerContours.map(c => c.group).filter(Boolean))];
+
+            if (grpNames.length > 1) {
+                // Layer has multiple groups — expandable with group sub-toggles
+                const layerChildren = buildTreeParent(
+                    drawingChildren, `${layer.type}__${lpdLayerName}`, lpdLayerName, layer.visible, grpNames,
+                    (checked) => {
+                        const drawingGroup = layerGroups()[layer.type];
+                        if (!drawingGroup) return;
+                        const layerGrp = drawingGroup.userData?.layerSubGroups?.[lpdLayerName];
+                        if (layerGrp) layerGrp.visible = checked;
+                        if (checked) drawingGroup.visible = true;
+                    },
+                    { withHighlight: true },
+                );
+
+                for (const grpName of grpNames) {
+                    const grpKey = `${layer.type}__${lpdLayerName}__${grpName}`;
+                    const sub = buildSubToggle(grpKey, grpName, layer.visible, {
+                        withHighlight: true,
+                        onHighlightChange: (checked) =>
+                            applyHighlightToScope(layer.type, lpdLayerName, grpName, checked),
+                    });
+                    const cb = sub.querySelector('input.vis-cb');
+                    cb.addEventListener('change', () => {
+                        const drawingGroup = layerGroups()[layer.type];
+                        if (!drawingGroup) return;
+                        const layerGrp = drawingGroup.userData?.layerSubGroups?.[lpdLayerName];
+                        const grpGrp = layerGrp?.userData?.groupSubGroups?.[grpName];
+                        if (grpGrp) grpGrp.visible = cb.checked;
+                        if (cb.checked) {
+                            if (layerGrp) layerGrp.visible = true;
+                            drawingGroup.visible = true;
+                        }
+                    });
+                    layerChildren.appendChild(sub);
+                }
+            } else {
+                // Layer has one group — simple toggle
+                const subKey = `${layer.type}__${lpdLayerName}`;
+                const sub = buildSubToggle(subKey, lpdLayerName, layer.visible, {
+                    withHighlight: true,
+                    onHighlightChange: (checked) =>
+                        applyHighlightToScope(layer.type, lpdLayerName, null, checked),
+                });
+                const cb = sub.querySelector('input.vis-cb');
+                cb.addEventListener('change', () => {
+                    const drawingGroup = layerGroups()[layer.type];
+                    if (!drawingGroup) return;
+                    const layerGrp = drawingGroup.userData?.layerSubGroups?.[lpdLayerName];
+                    if (layerGrp) layerGrp.visible = cb.checked;
+                    if (cb.checked) drawingGroup.visible = true;
+                });
+                drawingChildren.appendChild(sub);
+            }
+        }
+    }
+}
+
+function buildCameraLayerTree(container, layer) {
+    const cameraData = Array.isArray(layer.data) ? layer.data : [];
+    const childContainer = buildTreeParent(
+        container, 'cameras', 'Cameras', layer.visible,
+        cameraData,
+        (checked) => {
+            const grp = layerGroups()['cameras'];
+            if (grp) grp.visible = checked;
+        },
+    );
+
+    // Per-camera expandable entries
+    cameraData.forEach((camData, idx) => {
+        const camLabel = camData.label || camData.id || 'Camera';
+        const camKey = `camera_${idx}`;
+
+        // Each camera is an expandable tree node
+        const camChildren = buildTreeParent(
+            childContainer, camKey, camLabel, true,
+            ['Shell', 'Internals', 'Frustums', 'Projections'],
+            (checked) => {
+                // Toggle the entire per-camera group
+                const camerasGroup = layerGroups()['cameras'];
+                const perCam = camerasGroup?.userData?.perCamera?.[idx];
+                if (perCam) perCam.camGroup.visible = checked;
+            },
+        );
+
+        // Sub-component toggles for this camera
+        const subItems = [
+            ['shell',      'Shell'],
+            ['internals',  'Internals'],
+            ['frustum',    'Frustums'],
+            ['projection', 'Projections'],
+            ['imagePlane', 'Image Projection'],
+        ];
+        for (const [subField, subText] of subItems) {
+            const subKey = `${camKey}_${subField}`;
+            const sub = buildSubToggle(subKey, subText, true);
+            const cb = sub.querySelector('input');
+            cb.addEventListener('change', () => {
+                if (subField === 'imagePlane') {
+                    const plane = cameraImagePlanes()[idx];
+                    if (plane) {
+                        // Record intent; actual visibility still requires a
+                        // loaded texture (no gray placeholder when imageless).
+                        plane.userData.projectionEnabled = cb.checked;
+                        renderer.refreshFrustumImageVisibility(plane);
+                    }
+                    return;
+                }
+                const camerasGroup = layerGroups()['cameras'];
+                const perCam = camerasGroup?.userData?.perCamera?.[idx];
+                if (perCam && perCam[subField]) perCam[subField].visible = cb.checked;
+            });
+            camChildren.appendChild(sub);
+        }
+    });
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Views + bookmarks: smooth camera transitions and saved scene states
+// ═══════════════════════════════════════════════════════════════
+
+let _viewFlyId = null;            // RAF id for an in-progress view transition
+let _flyDamping = null;           // orbit dampingFactor saved while a fly suppresses it
+let builtInPresets = {};          // from scene.json viewPresets (Default/Top/...)
+
+// Cleanly end any in-progress view fly: stop the RAF, restore orbit damping,
+// re-enable input. Idempotent — safe to call when no fly is running.
+function _endViewFly() {
+    if (_viewFlyId) { cancelAnimationFrame(_viewFlyId); _viewFlyId = null; }
+    if (_flyDamping !== null) { controls().dampingFactor = _flyDamping; _flyDamping = null; }
+    controls().enabled = true;
+}
+let bookmarks = [];               // user-saved {name, state} for this scene
+
+function _easeInOutCubic(p) {
+    return p < 0.5 ? 4 * p * p * p : 1 - Math.pow(-2 * p + 2, 3) / 2;
+}
+
+// Snapshot the current camera viewpoint (pose + projection-specific framing).
+function captureView() {
+    return renderer.captureView();
+}
+
+// Smoothly fly the camera to a target view. Eases position + orbit target (the
+// render loop's controls.update() enforces look-at-target, so interpolating the
+// target IS the orientation interpolation). Projection can't morph, so we switch
+// it instantly up front, then animate.
+function flyToView(view, { duration = 900 } = {}) {
+    _endViewFly();   // cancel + restore any prior fly's controls state first
+    if (view.projectionMode && view.projectionMode !== projectionMode()) {
+        switchProjection(view.projectionMode);
+    }
+    const camera = cam();
+    const ctrls = controls();
+    if (view.up) camera.up.fromArray(view.up);   // constant (0,0,1) in this scene; harmless
+
+    const startPos = camera.position.clone();
+    const endPos   = new THREE.Vector3().fromArray(view.position);
+    const startTgt = ctrls.target.clone();
+    const endTgt   = new THREE.Vector3().fromArray(view.target);
+    const startQuat = camera.quaternion.clone();
+
+    // Probe the EXACT orientation OrbitControls settles into at the destination,
+    // so the slerp lands precisely there with no end-snap — even at a pole.
+    camera.position.copy(endPos);
+    ctrls.target.copy(endTgt);
+    ctrls.update();
+    const endQuat = camera.quaternion.clone();
+    camera.position.copy(startPos);
+    ctrls.target.copy(startTgt);
+    camera.quaternion.copy(startQuat);
+
+    const isOrtho   = camera.isOrthographicCamera;
+    const startFov  = camera.isPerspectiveCamera ? camera.fov : null;
+    const endFov    = (camera.isPerspectiveCamera && view.fov != null) ? view.fov : startFov;
+    const startZoom = camera.zoom;
+    const endZoom   = (isOrtho && view.zoom != null) ? view.zoom : startZoom;
+    const haveBounds = isOrtho && view.left != null;
+    const sb = haveBounds ? { l: camera.left, r: camera.right, t: camera.top, b: camera.bottom } : null;
+    const eb = haveBounds ? { l: view.left, r: view.right, t: view.top, b: view.bottom } : null;
+
+    // Disable controls so the render loop won't force look-at-target and clobber
+    // the slerp; suppress damping so residual drag-inertia can't perturb it.
+    ctrls.enabled = false;
+    _flyDamping = ctrls.dampingFactor;
+    ctrls.dampingFactor = 0;
+    const t0 = performance.now();
+    function tick(now) {
+        const p = Math.min(1, (now - t0) / duration);
+        const k = _easeInOutCubic(p);
+        camera.position.lerpVectors(startPos, endPos, k);
+        ctrls.target.lerpVectors(startTgt, endTgt, k);   // end-state bookkeeping
+        camera.quaternion.copy(startQuat).slerp(endQuat, k);
+        if (isOrtho) {
+            camera.zoom = startZoom + (endZoom - startZoom) * k;
+            if (haveBounds) {
+                camera.left   = sb.l + (eb.l - sb.l) * k;
+                camera.right  = sb.r + (eb.r - sb.r) * k;
+                camera.top    = sb.t + (eb.t - sb.t) * k;
+                camera.bottom = sb.b + (eb.b - sb.b) * k;
+            }
+            camera.updateProjectionMatrix();
+        } else if (endFov != null) {
+            camera.fov = startFov + (endFov - startFov) * k;
+            camera.updateProjectionMatrix();
+        }
+        if (p < 1) {
+            _viewFlyId = requestAnimationFrame(tick);
+        } else {
+            _viewFlyId = null;
+            camera.position.copy(endPos);
+            ctrls.target.copy(endTgt);
+            camera.quaternion.copy(endQuat);
+            if (_flyDamping !== null) { ctrls.dampingFactor = _flyDamping; _flyDamping = null; }
+            ctrls.enabled = true;
+            ctrls.update();   // reproduces endQuat (we probed it), now live
+        }
+    }
+    _viewFlyId = requestAnimationFrame(tick);
+}
+
+// Capture / restore the toggle state of the whole layers panel (visibility +
+// bright/dim highlight, cameras' sub-toggles, etc.) by checkbox id. Restoring
+// dispatches change events so the existing handlers apply the 3D effect and the
+// UI stays in sync.
+function captureToggleState() {
+    const state = {};
+    document.querySelectorAll('#layer-toggles input[type="checkbox"]').forEach(cb => {
+        if (cb.id) state[cb.id] = cb.checked;
+    });
+    return state;
+}
+
+function applyToggleState(state) {
+    if (!state) return;
+    // DOM order = parents before children, so a parent's cascade is corrected
+    // when we reach each child and set it to its captured value.
+    document.querySelectorAll('#layer-toggles input[type="checkbox"]').forEach(cb => {
+        if (!cb.id || !(cb.id in state)) return;
+        if (cb.checked !== state[cb.id]) {
+            cb.checked = state[cb.id];
+            cb.dispatchEvent(new Event('change'));
+        }
+    });
+}
+
+function captureSceneState() {
+    return { view: captureView(), toggles: captureToggleState() };
+}
+
+function applySceneState(state, { animate = true } = {}) {
+    if (povCameraIdx >= 0) exitPOV();   // a view change leaves POV
+    if (state.toggles) applyToggleState(state.toggles);
+    if (!state.view) return;
+    // Restore projection on BOTH paths (flyToView also handles it, but the
+    // instant path must too).
+    if (state.view.projectionMode && state.view.projectionMode !== projectionMode()) {
+        switchProjection(state.view.projectionMode);
+    }
+    if (animate) flyToView(state.view);
+    else {
+        cam().position.fromArray(state.view.position);
+        controls().target.fromArray(state.view.target);
+        controls().update();
+    }
+}
+
+// ── Bookmark persistence (localStorage, keyed per scene) ──
+function _bookmarkKey() {
+    const scene = new URLSearchParams(location.search).get('scene') || '_';
+    return `tpiViz.bookmarks.${scene}`;
+}
+function loadBookmarks() {
+    try { return JSON.parse(localStorage.getItem(_bookmarkKey()) || '[]'); }
+    catch (e) { console.warn('[bookmarks] load failed:', e); return []; }
+}
+function persistBookmarks() {
+    try { localStorage.setItem(_bookmarkKey(), JSON.stringify(bookmarks)); }
+    catch (e) { console.warn('[bookmarks] save failed:', e); }
+}
+
+// In-app name prompt (not window.prompt). A small floating popup anchored under
+// `anchorEl` with a focused input + Save/Cancel. Resolves to the trimmed name,
+// or null on cancel/Escape/outside-click. Enter saves.
+function promptName(defaultValue, anchorEl) {
+    return new Promise((resolve) => {
+        const pop = document.createElement('div');
+        pop.className = 'name-popup';
+
+        const input = document.createElement('input');
+        input.type = 'text';
+        input.className = 'name-popup-input';
+        input.value = defaultValue;
+        input.placeholder = 'View name';
+        input.maxLength = 60;
+
+        const row = document.createElement('div');
+        row.className = 'name-popup-row';
+        const cancel = document.createElement('button');
+        cancel.className = 'btn';
+        cancel.textContent = 'Cancel';
+        const save = document.createElement('button');
+        save.className = 'btn btn-primary';
+        save.textContent = 'Save';
+        row.appendChild(cancel);
+        row.appendChild(save);
+
+        pop.appendChild(input);
+        pop.appendChild(row);
+        document.body.appendChild(pop);
+
+        // Anchor under the trigger, right-aligned to it.
+        const r = anchorEl.getBoundingClientRect();
+        pop.style.top = `${Math.round(r.bottom + 6)}px`;
+        pop.style.right = `${Math.round(window.innerWidth - r.right)}px`;
+
+        input.focus();
+        input.select();
+
+        let done = false;
+        function close(value) {
+            if (done) return;
+            done = true;
+            document.removeEventListener('mousedown', onOutside, true);
+            pop.remove();
+            resolve(value);
+        }
+        function commit() { close(input.value.trim() || null); }
+        function onOutside(e) { if (!pop.contains(e.target)) close(null); }
+
+        save.addEventListener('click', commit);
+        cancel.addEventListener('click', () => close(null));
+        input.addEventListener('keydown', (e) => {
+            if (e.key === 'Enter') { e.preventDefault(); commit(); }
+            else if (e.key === 'Escape') { e.preventDefault(); close(null); }
+        });
+        // Defer so the click that opened the popup doesn't immediately close it.
+        setTimeout(() => document.addEventListener('mousedown', onOutside, true), 0);
+    });
+}
+
+function buildPovControls(presets) {
+    const container = document.getElementById('pov-controls');
+    container.innerHTML = '';
+    builtInPresets = presets || {};
+    bookmarks = loadBookmarks();
+
+    // ── Views group: built-in presets + saved bookmarks + a "+" to save one ──
+    const viewsGroup = document.createElement('div');
+    viewsGroup.className = 'ctrl-group';
+    const viewsLabel = document.createElement('span');
+    viewsLabel.className = 'ctrl-label';
+    viewsLabel.textContent = 'Views';
+    viewsGroup.appendChild(viewsLabel);
+    const viewsRow = document.createElement('div');
+    viewsRow.className = 'ctrl-row';
+    viewsGroup.appendChild(viewsRow);
+    container.appendChild(viewsGroup);
+
+    function renderViews() {
+        viewsRow.innerHTML = '';
+        // Built-in presets (camera-only viewpoints from scene.json)
+        for (const name of Object.keys(builtInPresets)) {
+            const btn = document.createElement('button');
+            btn.className = 'btn';
+            btn.textContent = name.charAt(0).toUpperCase() + name.slice(1);
+            btn.addEventListener('click', () => {
+                if (povCameraIdx >= 0) exitPOV();
+                flyToView(builtInPresets[name]);
+            });
+            viewsRow.appendChild(btn);
+        }
+        // User bookmarks (full scene state). Chip with a delete ×.
+        bookmarks.forEach((bm, i) => {
+            const chip = document.createElement('span');
+            chip.className = 'bookmark-chip';
+            const go = document.createElement('button');
+            go.className = 'btn bookmark-btn';
+            go.textContent = bm.name;
+            go.title = 'Go to saved view (restores scene state)';
+            go.addEventListener('click', () => applySceneState(bm.state, { animate: true }));
+            const del = document.createElement('button');
+            del.className = 'bookmark-del';
+            del.innerHTML = '&times;';
+            del.title = 'Delete this bookmark';
+            del.addEventListener('click', (e) => {
+                e.stopPropagation();
+                bookmarks.splice(i, 1);
+                persistBookmarks();
+                renderViews();
+            });
+            chip.appendChild(go);
+            chip.appendChild(del);
+            viewsRow.appendChild(chip);
+        });
+        // "+" — save current view + scene state as a new bookmark
+        const add = document.createElement('button');
+        add.className = 'btn btn-add';
+        add.innerHTML = '&plus;';
+        add.title = 'Save current view + scene state as a bookmark';
+        add.addEventListener('click', async () => {
+            const name = await promptName(`View ${bookmarks.length + 1}`, add);
+            if (!name) return;
+            bookmarks.push({ name, state: captureSceneState() });
+            persistBookmarks();
+            renderViews();
+        });
+        viewsRow.appendChild(add);
+    }
+    renderViews();
+
+    // ── Projection group: separate from views; a segmented control with both
+    //    modes spelled out. The setupScene helper keeps both cameras in sync —
+    //    flipping rebinds OrbitControls + updates our cached camera. ──
+    if (renderer.threeSetup && typeof renderer.threeSetup.setProjection === 'function') {
+        const projGroup = document.createElement('div');
+        projGroup.className = 'ctrl-group';
+        const projLabel = document.createElement('span');
+        projLabel.className = 'ctrl-label';
+        projLabel.textContent = 'Projection';
+        projGroup.appendChild(projLabel);
+
+        const seg = document.createElement('div');
+        seg.className = 'segmented';
+        const modes = [['perspective', 'Perspective'], ['orthographic', 'Orthographic']];
+        const segBtns = {};
+        for (const [mode, text] of modes) {
+            const b = document.createElement('button');
+            b.className = 'seg-btn' + (projectionMode() === mode ? ' active' : '');
+            b.textContent = text;
+            b.addEventListener('click', () => {
+                if (mode === projectionMode()) return;
+                // Cancel any in-flight transition so it can't keep driving the
+                // (now rebound) camera after the projection switch.
+                if (povAnimationId) { cancelAnimationFrame(povAnimationId); povAnimationId = null; }
+                _endViewFly();
+                switchProjection(mode);
+                if (povCameraIdx >= 0) applyPOV(povCameraIdx);
+            });
+            segBtns[mode] = b;
+            seg.appendChild(b);
+        }
+        // Let switchProjection (incl. exitPOV's restore) highlight the active mode.
+        syncProjectionUI = (m) => {
+            for (const [mode, b] of Object.entries(segBtns)) b.classList.toggle('active', mode === m);
+        };
+        renderer.setProjectionUISync(syncProjectionUI);
+        projGroup.appendChild(seg);
+
+        // Projection lives top-LEFT (its own overlay), separate from the
+        // top-right Views overlay.
+        let leftControls = document.getElementById('projection-controls');
+        if (!leftControls) {
+            leftControls = document.createElement('div');
+            leftControls.id = 'projection-controls';
+            leftControls.className = 'controls controls-left';
+            container.parentElement.appendChild(leftControls);
+        }
+        leftControls.innerHTML = '';
+        leftControls.appendChild(projGroup);
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// UI: Camera tree (left sidebar) — cameras with nested flows
+// ═══════════════════════════════════════════════════════════════
+
+function buildCameraTree() {
+    const container = document.getElementById('camera-tree');
+    container.innerHTML = '';
+
+    const cams = cameraEntries();
+    if (cams.length === 0) {
+        document.getElementById('camera-tree-panel').classList.add('hidden');
+        return;
+    }
+
+    // Per camera, group its flows by useCase: { camId: { useCase: [flow, …] } }
+    const flowsByCamera = {};
+    for (const [name, flow] of Object.entries(flowData())) {
+        const camId = flow.cameraId;
+        const uc = flow.useCase || 'uncategorized';
+        if (!flowsByCamera[camId]) flowsByCamera[camId] = {};
+        if (!flowsByCamera[camId][uc]) flowsByCamera[camId][uc] = [];
+        flowsByCamera[camId][uc].push({ name, ...flow });
+    }
+    const totalForCam = (byUc) =>
+        Object.values(byUc || {}).reduce((n, arr) => n + arr.length, 0);
+
+    cams.forEach((camDesc, idx) => {
+        const item = mkEl('div', 'cam-tree-item');
+
+        // Camera header
+        const header = mkEl('div', 'cam-tree-header');
+        header.dataset.idx = idx;
+
+        const camFlowsByUc = flowsByCamera[camDesc.id] || {};
+        const camFlowCount = totalForCam(camFlowsByUc);
+
+        const arrow = mkEl('span', 'tree-arrow');
+        arrow.textContent = camFlowCount > 0 ? '▶' : ' ';
+
+        const dot = mkEl('span', 'cam-dot');
+        dot.style.background = `#${camDesc.color.toString(16).padStart(6, '0')}`;
+
+        const nameSpan = mkEl('span', 'cam-name');
+        nameSpan.textContent = camDesc.label || camDesc.id;
+
+        header.appendChild(arrow);
+        header.appendChild(dot);
+        header.appendChild(nameSpan);
+
+        if (camFlowCount > 0) {
+            const countSpan = mkEl('span', 'cam-flow-count');
+            countSpan.textContent = `${camFlowCount}`;
+            header.appendChild(countSpan);
+        }
+
+        header.addEventListener('click', () => selectCamera(idx));
+        item.appendChild(header);
+
+        // Camera → useCase → flows. Camera collapsed by default;
+        // useCase subgroups inside expand by default when the camera opens.
+        if (camFlowCount > 0) {
+            const ucContainer = mkEl('div', 'cam-tree-flows collapsed');
+
+            arrow.addEventListener('click', (e) => {
+                e.stopPropagation();
+                ucContainer.classList.toggle('collapsed');
+                arrow.textContent = ucContainer.classList.contains('collapsed') ? '▶' : '▼';
+            });
+
+            const useCases = Object.keys(camFlowsByUc).sort((a, b) => a.localeCompare(b));
+            for (const uc of useCases) {
+                const ucFlows = camFlowsByUc[uc];
+                ucFlows.sort((a, b) => a.name.localeCompare(b.name));
+
+                const ucGroup = mkEl('div', 'cam-tree-uc-group');
+
+                const ucHeader = mkEl('div', 'cam-tree-uc-header');
+                const ucArrow = mkEl('span', 'tree-arrow');
+                ucArrow.textContent = '▼';
+                const ucLabel = mkEl('span', 'uc-name');
+                ucLabel.textContent = uc;
+                const ucCount = mkEl('span', 'uc-flow-count');
+                ucCount.textContent = `${ucFlows.length}`;
+                ucHeader.appendChild(ucArrow);
+                ucHeader.appendChild(ucLabel);
+                ucHeader.appendChild(ucCount);
+
+                const flowList = mkEl('div', 'cam-tree-uc-flows');
+                ucHeader.addEventListener('click', (e) => {
+                    e.stopPropagation();
+                    flowList.classList.toggle('collapsed');
+                    ucArrow.textContent = flowList.classList.contains('collapsed') ? '▶' : '▼';
+                });
+
+                for (const flow of ucFlows) {
+                    const flowEl = mkEl('div', 'cam-tree-flow');
+                    flowEl.dataset.flowName = flow.name;
+
+                    const icon = mkEl('span', 'flow-icon');
+                    icon.textContent = '▶';
+
+                    const flowName = mkEl('span', 'flow-name');
+                    flowName.textContent = flow.name;
+
+                    const stepCount = mkEl('span', 'flow-step-count');
+                    stepCount.textContent = `${flow.steps.length}`;
+
+                    const playBtn = mkEl('button', 'flow-play-btn');
+                    playBtn.innerHTML = '&#9654;';
+                    playBtn.title = 'Play/Stop this flow';
+                    playBtn.addEventListener('click', (e) => {
+                        e.stopPropagation();
+                        toggleFlowPlay(flow.name, playBtn);
+                    });
+
+                    flowEl.appendChild(icon);
+                    flowEl.appendChild(flowName);
+                    flowEl.appendChild(stepCount);
+                    flowEl.appendChild(playBtn);
+
+                    flowEl.addEventListener('click', (e) => {
+                        e.stopPropagation();
+                        selectFlow(flow.name);
+                    });
+
+                    flowList.appendChild(flowEl);
+                }
+
+                ucGroup.appendChild(ucHeader);
+                ucGroup.appendChild(flowList);
+                ucContainer.appendChild(ucGroup);
+            }
+
+            item.appendChild(ucContainer);
+        }
+
+        container.appendChild(item);
+    });
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Camera POV mode
+// ═══════════════════════════════════════════════════════════════
+
+function applyPOV(idx) {
+    const desc = renderer.model.cameraAt(idx);
+    const params = desc.params;
+    const ptz    = desc.ptz;
+    // Compute kinematics via the shared pure model path.
+    const kinematics = computeKinematics(params, ptz.pan, ptz.tilt);
+    const R      = kinematics.R_full;
+    const camPos = kinematics.cam_pos;
+
+    // Vertical FOV from zoom + sensor geometry
+    const fw    = params.focal_wide_mm || 4.3;
+    const ft    = params.focal_tele_mm || 137.6;
+    const t     = Math.max(0, Math.min(1, (ptz.zoom - 1) / 9998));
+    const focal = fw + t * (ft - fw);
+    const sh    = AXIS_Q6135LE_SENSOR.height_mm;
+    const sw    = AXIS_Q6135LE_SENSOR.width_mm;
+    const vfovRad = 2 * Math.atan(sh / (2 * focal));
+    const aspect  = sw / sh;   // native PTZ camera aspect ratio
+
+    const camera = cam();
+    // Projection-aware: POV works in BOTH perspective and orthographic.
+    if (camera.isOrthographicCamera) {
+        const dist  = desc.frustumDistance || 8000;
+        const halfH = dist * Math.tan(vfovRad / 2);
+        const halfW = halfH * aspect;
+        camera.left   = -halfW;
+        camera.right  =  halfW;
+        camera.top    =  halfH;
+        camera.bottom = -halfH;
+        camera.zoom   = 1;
+        camera.near   = 10;
+    } else {
+        camera.fov    = vfovRad * 180 / Math.PI;
+        camera.aspect = aspect;
+        camera.near   = 10;
+    }
+    camera.updateProjectionMatrix();
+
+    // Set camera matrix directly from R_full — no lookAt().
+    // OpenCV: R columns = [right, down, forward]
+    // Three.js camera: columns = [right, up, -forward]  (looks down -Z)
+    const m = new THREE.Matrix4();
+    m.set(
+        R[0][0], -R[0][1], -R[0][2], camPos[0],
+        R[1][0], -R[1][1], -R[1][2], camPos[1],
+        R[2][0], -R[2][1], -R[2][2], camPos[2],
+        0, 0, 0, 1
+    );
+    camera.matrix.copy(m);
+    camera.matrixAutoUpdate = false;
+    camera.updateMatrixWorld(true);
+}
+
+let povAnimationId = null;  // requestAnimationFrame ID for POV transition
+let povVisibilitySnapshot = null;  // per-camera {shell,internals,frustum} visibility saved on POV enter
+
+function enterPOV(idx) {
+    const camera = cam();
+    prevCameraState = {
+        mode:     projectionMode(),          // restore the projection we came from
+        position: camera.position.clone(),
+        target:   controls().target.clone(),
+        up:       camera.up.clone(),
+        fov:      camera.fov,                // perspective only (undefined on ortho)
+        aspect:   camera.aspect,             // perspective only
+        zoom:     camera.zoom,               // orthographic (also exists on persp)
+        near:     camera.near,
+    };
+    // Orthographic scale is set by BOTH zoom AND the frustum bounds — applyPOV
+    // overwrites the bounds, so we must capture them to restore on exit.
+    if (camera.isOrthographicCamera) {
+        prevCameraState.left   = camera.left;
+        prevCameraState.right  = camera.right;
+        prevCameraState.top    = camera.top;
+        prevCameraState.bottom = camera.bottom;
+    }
+    povCameraIdx = idx;
+    controls().enabled = false;
+
+    // Looking through a camera, hide all camera hardware across every camera —
+    // only the POV camera's own textured image plane stays. Snapshot prior
+    // visibility so manual tree toggles are restored on exit.
+    const perCameras = renderer.perCamera();
+    const frustums = cameraFrustumGroups();
+    povVisibilitySnapshot = perCameras.map((pc, i) => ({
+        shell:     pc.shell.visible,
+        internals: pc.internals.visible,
+        frustum:   pc.frustum.visible,
+        frustumChildren: frustums[i]
+            ? frustums[i].children.map(c => c.visible) : null,
+    }));
+    perCameras.forEach((pc, i) => {
+        pc.shell.visible = false;
+        pc.internals.visible = false;
+        if (i === idx) {
+            pc.frustum.visible = true;
+            frustums[i]?.children.forEach(child => {
+                if (child.name === 'frustum_image_plane') renderer.refreshFrustumImageVisibility(child);
+                else child.visible = false;
+            });
+        } else {
+            pc.frustum.visible = false;
+        }
+    });
+
+    document.getElementById(`pov-btn-${idx}`)?.classList.add('active');
+    animateToPOV(idx);
+}
+
+function animateToPOV(idx) {
+    if (povAnimationId) { cancelAnimationFrame(povAnimationId); povAnimationId = null; }
+
+    const desc = renderer.model.cameraAt(idx);
+    const params = desc.params;
+    const ptz    = desc.ptz;
+    const kin    = computeKinematics(params, ptz.pan, ptz.tilt);
+    const targetPos = new THREE.Vector3(...kin.cam_pos);
+
+    const R = kin.R_full;
+    // Forward direction from R (OpenCV forward = column 2)
+    const fwd = new THREE.Vector3(R[0][2], R[1][2], R[2][2]);
+    const targetLookAt = targetPos.clone().add(fwd.multiplyScalar(1000));
+
+    // Target FOV / frustum extent
+    const fw    = params.focal_wide_mm || 4.3;
+    const ft    = params.focal_tele_mm || 137.6;
+    const t     = Math.max(0, Math.min(1, (ptz.zoom - 1) / 9998));
+    const focal = fw + t * (ft - fw);
+    const sh    = AXIS_Q6135LE_SENSOR.height_mm;
+    const sw    = AXIS_Q6135LE_SENSOR.width_mm;
+    const targetFov = 2 * Math.atan(sh / (2 * focal)) * 180 / Math.PI;
+
+    const camera = cam();
+    const isOrtho = camera.isOrthographicCamera;
+    const dist        = desc.frustumDistance || 8000;
+    const targetHalfH = dist * Math.tan((2 * Math.atan(sh / (2 * focal))) / 2);
+    const targetHalfW = targetHalfH * (sw / sh);
+
+    // Start state
+    const startPos = camera.position.clone();
+    const startTarget = controls().target.clone();
+    const startFov = camera.fov;
+    const startTop    = camera.top;
+    const startBottom = camera.bottom;
+    const startLeft   = camera.left;
+    const startRight  = camera.right;
+
+    const duration = 1200; // ms
+    const startTime = performance.now();
+
+    function tick(now) {
+        const elapsed = now - startTime;
+        const p = Math.min(1, elapsed / duration);
+        const ease = p < 0.5 ? 4 * p * p * p : 1 - Math.pow(-2 * p + 2, 3) / 2;
+
+        camera.position.lerpVectors(startPos, targetPos, ease);
+        controls().target.lerpVectors(startTarget, targetLookAt, ease);
+        if (isOrtho) {
+            camera.top    = startTop    + (targetHalfH - startTop)    * ease;
+            camera.bottom = startBottom + (-targetHalfH - startBottom) * ease;
+            camera.right  = startRight  + (targetHalfW - startRight)  * ease;
+            camera.left   = startLeft   + (-targetHalfW - startLeft)  * ease;
+        } else {
+            camera.fov = startFov + (targetFov - startFov) * ease;
+        }
+        camera.updateProjectionMatrix();
+        camera.lookAt(controls().target);
+
+        if (p < 1) {
+            povAnimationId = requestAnimationFrame(tick);
+        } else {
+            povAnimationId = null;
+            applyPOV(idx);
+        }
+    }
+    povAnimationId = requestAnimationFrame(tick);
+}
+
+function exitPOV() {
+    if (povAnimationId) { cancelAnimationFrame(povAnimationId); povAnimationId = null; }
+    if (prevCameraState) {
+        // First return to the projection we entered POV from.
+        if (prevCameraState.mode && prevCameraState.mode !== projectionMode()) {
+            switchProjection(prevCameraState.mode);
+        }
+        const camera = cam();
+        camera.matrixAutoUpdate = true;
+        camera.position.copy(prevCameraState.position);
+        controls().target.copy(prevCameraState.target);
+        camera.up.copy(prevCameraState.up);
+        camera.near = prevCameraState.near;
+        if (camera.isOrthographicCamera) {
+            if (prevCameraState.zoom !== undefined) camera.zoom = prevCameraState.zoom;
+            if (prevCameraState.left !== undefined) {
+                camera.left   = prevCameraState.left;
+                camera.right  = prevCameraState.right;
+                camera.top    = prevCameraState.top;
+                camera.bottom = prevCameraState.bottom;
+            }
+        } else {
+            if (prevCameraState.fov !== undefined) camera.fov = prevCameraState.fov;
+            if (prevCameraState.aspect !== undefined) camera.aspect = prevCameraState.aspect;
+        }
+        camera.updateProjectionMatrix();
+        prevCameraState = null;
+    } else {
+        cam().matrixAutoUpdate = true;
+    }
+    // Restore every camera's hardware visibility to the snapshot taken on enter.
+    const perCameras = renderer.perCamera();
+    const frustums = cameraFrustumGroups();
+    if (povVisibilitySnapshot) {
+        perCameras.forEach((pc, i) => {
+            const s = povVisibilitySnapshot[i];
+            if (!s) return;
+            pc.shell.visible = s.shell;
+            pc.internals.visible = s.internals;
+            pc.frustum.visible = s.frustum;
+            if (s.frustumChildren && frustums[i]) {
+                frustums[i].children.forEach((child, ci) => {
+                    if (s.frustumChildren[ci] !== undefined) child.visible = s.frustumChildren[ci];
+                });
+            }
+        });
+        povVisibilitySnapshot = null;
+    }
+    // The POV camera's image plane is governed by texture + intent, NOT the
+    // pre-POV snapshot — an image may have loaded during POV (flow playing).
+    if (povCameraIdx >= 0) renderer.refreshFrustumImageVisibility(cameraImagePlanes()[povCameraIdx]);
+    document.getElementById(`pov-btn-${povCameraIdx}`)?.classList.remove('active');
+    controls().enabled = true;
+    controls().update();
+    povCameraIdx = -1;
+}
+
+function selectCamera(idx) {
+    // Exit POV when switching cameras
+    if (povCameraIdx >= 0 && povCameraIdx !== idx) exitPOV();
+
+    selectedCameraIdx = idx;
+
+    // Update camera tree highlights
+    document.querySelectorAll('.cam-tree-header').forEach(el => {
+        el.classList.toggle('selected', parseInt(el.dataset.idx) === idx);
+    });
+
+    const rightSidebar = document.getElementById('right-sidebar');
+    const detail = document.getElementById('camera-detail');
+
+    const cams = cameraEntries();
+    if (idx < 0 || idx >= cams.length) {
+        rightSidebar.classList.add('hidden');
+        activePTZSliders = null;
+        setTimeout(() => window.dispatchEvent(new Event('resize')), 50);
+        return;
+    }
+
+    // Show right sidebar
+    rightSidebar.classList.remove('hidden');
+    document.getElementById('right-sidebar-title').textContent =
+        cams[idx].label || cams[idx].id;
+
+    // Build camera edit panel
+    detail.innerHTML = '';
+    buildCameraEditPanel(idx, detail);
+
+    // Trigger canvas resize after sidebar shows
+    setTimeout(() => window.dispatchEvent(new Event('resize')), 50);
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Camera edit panel (PTZ sliders + kinematic params)
+// ═══════════════════════════════════════════════════════════════
+
+function buildCameraEditPanel(idx, container) {
+    const desc = renderer.model.cameraAt(idx);
+    const params = desc.params;
+    const ptz = desc.ptz;
+
+    // POV toggle button
+    const povSection = mkEl('div', 'pov-section');
+    const povBtn = document.createElement('button');
+    povBtn.className = 'btn btn-pov' + (povCameraIdx === idx ? ' active' : '');
+    povBtn.id = `pov-btn-${idx}`;
+    povBtn.textContent = 'Camera POV';
+    povBtn.addEventListener('click', () => {
+        if (povCameraIdx === idx) {
+            exitPOV();
+        } else {
+            if (povCameraIdx >= 0) exitPOV();
+            enterPOV(idx);
+        }
+    });
+    povSection.appendChild(povBtn);
+    container.appendChild(povSection);
+
+    // PTZ sliders
+    const ptzSection = mkEl('div', 'ptz-edit-section');
+    const panSlider = createSlider('Pan', 'pan', ptz.pan, -180, 180, 0.5, '°', idx);
+    const tiltSlider = createSlider('Tilt', 'tilt', ptz.tilt, -90, 20, 0.5, '°', idx);
+    const zoomSlider = createSlider('Zoom', 'zoom', ptz.zoom, 1, 9999, 10, '', idx);
+    ptzSection.appendChild(panSlider);
+    ptzSection.appendChild(tiltSlider);
+    ptzSection.appendChild(zoomSlider);
+    container.appendChild(ptzSection);
+
+    // Store slider refs for flow step updates
+    activePTZSliders = {
+        pan: panSlider._sliderRef,
+        tilt: tiltSlider._sliderRef,
+        zoom: zoomSlider._sliderRef,
+    };
+
+    // Kinematic parameter edit sections (matches PTZCamera.to_dict wire format)
+    container.appendChild(paramEditSection('Mount (world)', 'Position (mm) [X, Y, Z]', 'mount_t', params.mount_t, 100, 0, idx));
+    container.appendChild(paramEditSection(null, 'Rotation (deg) [Rx, Ry, Rz]', 'mount_r', params.mount_r, 0.01, 3, idx));
+
+    container.appendChild(paramEditSection('T_mount_to_pan', 'Offset (mm) [X, Y, Z]', 'pan_t', params.pan_t, 10, 0, idx));
+    container.appendChild(paramEditSection(null, 'Rotation (deg) [Rx, Ry, Rz]', 'pan_r', params.pan_r, 0.01, 3, idx));
+
+    container.appendChild(paramEditSection('T_pan_to_tilt', 'Offset (mm) [X, Y, Z]', 'tilt_t', params.tilt_t, 10, 0, idx));
+    container.appendChild(paramEditSection(null, 'Rotation (deg) [Rx, Ry, Rz]', 'tilt_r', params.tilt_r, 0.01, 3, idx));
+
+    container.appendChild(paramEditSection('T_tilt_to_sensor', 'Offset (mm) [X, Y, Z]', 'sensor_t', params.sensor_t, 10, 0, idx));
+    container.appendChild(paramEditSection(null, 'Rotation (deg) [Rx, Ry, Rz]', 'sensor_r', params.sensor_r, 0.01, 3, idx));
+
+    // Lens offset
+    container.appendChild(paramEditSection('Lens Offset', 'CX, CY (mm)', 'lens',
+        [params.cx_offset_mm || 0, params.cy_offset_mm || 0], 0.001, 3, idx));
+
+    // Read-only optics
+    const opticsDiv = mkEl('div', 'param-section');
+    opticsDiv.innerHTML = `
+        <div class="param-section-title">Optics</div>
+        <div class="param-row"><span class="param-name">Focal Wide</span><span class="param-value">${fmtN(params.focal_wide_mm, 3)} mm</span></div>
+        <div class="param-row"><span class="param-name">Focal Tele</span><span class="param-value">${fmtN(params.focal_tele_mm, 3)} mm</span></div>
+        <div class="param-row"><span class="param-name">Image</span><span class="param-value">${params.image_width} × ${params.image_height} px</span></div>
+    `;
+    container.appendChild(opticsDiv);
+}
+
+function createSlider(label, key, value, min, max, step, unit, camIdx) {
+    const div = mkEl('div', 'slider-group');
+
+    const labelDiv = mkEl('div', 'slider-label');
+    const nameSpan = mkEl('span', 'name');
+    nameSpan.textContent = `${label}${unit ? ' (' + unit + ')' : ''}`;
+    const valueSpan = mkEl('span', 'value');
+    valueSpan.textContent = key === 'zoom' ? Math.round(value) : value.toFixed(1);
+    labelDiv.appendChild(nameSpan);
+    labelDiv.appendChild(valueSpan);
+
+    const input = document.createElement('input');
+    input.type = 'range';
+    input.min = min;
+    input.max = max;
+    input.step = step;
+    input.value = value;
+    input.addEventListener('input', () => {
+        const v = parseFloat(input.value);
+        renderer.model.cameraAt(camIdx).ptz[key] = v;
+        valueSpan.textContent = key === 'zoom' ? Math.round(v) : v.toFixed(1);
+        updateCameraVisuals(camIdx);
+    });
+
+    div.appendChild(labelDiv);
+    div.appendChild(input);
+
+    // Attach ref for external updates (flow step navigation)
+    div._sliderRef = { input, valueSpan };
+
+    return div;
+}
+
+function paramEditSection(title, label, paramKey, values, step, decimals, camIdx) {
+    const section = mkEl('div', 'param-section');
+    if (title) {
+        const titleDiv = mkEl('div', 'param-section-title');
+        titleDiv.textContent = title;
+        section.appendChild(titleDiv);
+    }
+
+    const row = mkEl('div', 'param-edit-row');
+    const labelEl = mkEl('label', 'param-label-small');
+    labelEl.textContent = label;
+    row.appendChild(labelEl);
+
+    const vecDiv = mkEl('div', 'vector-input');
+    values.forEach((v, i) => {
+        const input = document.createElement('input');
+        input.type = 'number';
+        input.step = step;
+        input.value = decimals > 0 ? v.toFixed(decimals) : Math.round(v);
+        input.addEventListener('input', () => {
+            const newVal = parseFloat(input.value) || 0;
+            const params = renderer.model.cameraAt(camIdx).params;
+            if (paramKey === 'lens') {
+                if (i === 0) params.cx_offset_mm = newVal;
+                else params.cy_offset_mm = newVal;
+            } else {
+                params[paramKey][i] = newVal;
+            }
+            updateCameraVisuals(camIdx);
+        });
+        vecDiv.appendChild(input);
+    });
+
+    row.appendChild(vecDiv);
+    section.appendChild(row);
+    return section;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Flows: select, deselect, step navigation
+// ═══════════════════════════════════════════════════════════════
+
+function findCameraIdx(cameraId) {
+    return renderer.findCameraIdx(cameraId);
+}
+
+function selectFlow(name) {
+    const flow = flowData()[name];
+    if (!flow) return;
+
+    // Toggle off if clicking same flow
+    if (activeFlowName === name) {
+        deselectFlow();
+        return;
+    }
+
+    activeFlowName = name;
+    activeFlowSteps = flow.steps;
+    currentStepIndex = 0;
+
+    // Highlight active flow in tree
+    document.querySelectorAll('.cam-tree-flow').forEach(el => {
+        el.classList.toggle('active', el.dataset.flowName === name);
+    });
+
+    // Select associated camera (opens right sidebar)
+    const camIdx = findCameraIdx(flow.cameraId);
+    if (camIdx >= 0 && camIdx !== selectedCameraIdx) {
+        selectCamera(camIdx);
+    }
+
+    // Update contour highlighting
+    updateContourHighlights();
+
+    // Show flow step nav
+    document.getElementById('flow-nav').classList.remove('hidden');
+    document.getElementById('flow-nav-title').textContent = name;
+
+    // Apply first step
+    applyFlowStep();
+}
+
+function deselectFlow() {
+    stopPlay();
+    activeFlowName = null;
+    activeFlowSteps = [];
+    currentStepIndex = 0;
+
+    // Update contour highlighting (may still have playing flows)
+    updateContourHighlights();
+
+    document.querySelectorAll('.cam-tree-flow').forEach(el => el.classList.remove('active'));
+    document.getElementById('flow-nav').classList.add('hidden');
+    currentImages = [];
+    document.getElementById('image-panel').classList.add('hidden');
+    cameraImagePlanes().forEach((_, idx) => clearFrustumImage(idx));
+    closeLightbox();
+}
+
+function applyFlowStep() {
+    const step = activeFlowSteps[currentStepIndex];
+    if (!step) return;
+
+    const flow = flowData()[activeFlowName];
+    if (!flow) return;
+
+    const camIdx = findCameraIdx(flow.cameraId);
+    if (camIdx < 0) return;
+
+    const desc = renderer.model.cameraAt(camIdx);
+    // Update camera PTZ state from flow step
+    if (step.pan != null)  desc.ptz.pan  = step.pan;
+    if (step.tilt != null) desc.ptz.tilt = step.tilt;
+    if (step.zoom != null) desc.ptz.zoom = step.zoom;
+
+    // Update frustum distance from step location if available
+    if (step.location && step.location.x != null) {
+        const params = desc.params;
+        const dx = step.location.x - params.mount_t[0];
+        const dy = step.location.y - params.mount_t[1];
+        const dz = step.location.z - params.mount_t[2];
+        desc.frustumDistance = Math.sqrt(dx * dx + dy * dy + dz * dz) * 0.95;
+    }
+
+    // Update 3D visuals
+    updateCameraVisuals(camIdx);
+    renderer.updateContourProjections();
+
+    // Update PTZ slider DOM if this camera's panel is open
+    if (camIdx === selectedCameraIdx && activePTZSliders) {
+        const ptz = desc.ptz;
+        for (const key of ['pan', 'tilt', 'zoom']) {
+            const slider = activePTZSliders[key];
+            if (slider) {
+                slider.input.value = ptz[key];
+                slider.valueSpan.textContent = key === 'zoom'
+                    ? Math.round(ptz[key])
+                    : ptz[key].toFixed(1);
+            }
+        }
+    }
+
+    // Update step counter and info
+    document.getElementById('step-counter').textContent =
+        `Step ${currentStepIndex + 1} / ${activeFlowSteps.length}`;
+    updateStepInfo();
+
+    // Update image panel
+    currentImages = step.images || [];
+    currentLaserMasks = step.laser_masks || [];
+    currentLaserScores = step.laser_scores || [];
+    currentProjectedContour = step.projected_contour || null;
+    currentAlignedContours = step.aligned_contours || [];
+    currentImageIdx = 0;
+    updateImagePanel();
+}
+
+// Load image as a safe (non-tainted) source for canvas/WebGL use.
+// On file://, XHR and fetch are blocked, so we fall back gracefully.
+const isFileProtocol = location.protocol === 'file:';
+
+function loadSafeImage(url, callback) {
+    // A missing overlay image shouldn't crash the viewer, but it must NOT be
+    // silent — every failure path warns so a 404 / decode error is diagnosable.
+    if (url.startsWith('data:') || url.startsWith('blob:')) {
+        const img = new Image();
+        img.onload = () => callback(img);
+        img.onerror = () => console.warn(`[image] failed to decode data/blob URL: ${url.slice(0, 64)}…`);
+        img.src = url;
+        return;
+    }
+    if (isFileProtocol) {
+        const img = new Image();
+        img.onload = () => callback(img);
+        img.onerror = () => console.warn(`[image] failed to load (file://, likely CORS-tainted): ${url}`);
+        img.src = url;
+        return;
+    }
+    const xhr = new XMLHttpRequest();
+    xhr.open('GET', url, true);
+    xhr.responseType = 'blob';
+    xhr.onload = () => {
+        if (xhr.status === 200) {
+            const img = new Image();
+            const objUrl = URL.createObjectURL(xhr.response);
+            img.onload = () => { URL.revokeObjectURL(objUrl); callback(img); };
+            img.onerror = () => { URL.revokeObjectURL(objUrl); console.warn(`[image] decoded-but-invalid blob for ${url}`); };
+            img.src = objUrl;
+        } else {
+            console.warn(`[image] HTTP ${xhr.status} fetching ${url}`);
+        }
+    };
+    xhr.onerror = () => console.warn(`[image] network error fetching ${url}`);
+    xhr.send();
+}
+
+// Set / clear the textured frustum image plane via the renderer (which owns the
+// THREE texture lifecycle). We load the image safely here, then hand the decoded
+// HTMLImageElement to the renderer.
+function setFrustumImage(camIdx, imageUrl) {
+    const plane = cameraImagePlanes()[camIdx];
+    if (!plane) return;
+    loadSafeImage(imageUrl, (img) => {
+        try {
+            renderer.setFrustumImage(camIdx, img);
+        } catch (e) {
+            // file:// tainted image — no usable texture, so keep it hidden.
+            plane.visible = false;
+        }
+    });
+}
+
+function clearFrustumImage(camIdx) {
+    renderer.clearFrustumImage(camIdx);
+}
+
+function updateImagePanel() {
+    const panel = document.getElementById('image-panel');
+    const img = document.getElementById('step-image');
+    const canvas = document.getElementById('step-image-canvas');
+    const counter = document.getElementById('image-counter');
+    const laserBtn = document.getElementById('btn-laser-overlay');
+    const scoreBtn = document.getElementById('btn-score-overlay');
+    const projBtn = document.getElementById('btn-projected-overlay');
+    const alignBtn = document.getElementById('btn-aligned-overlay');
+
+    if (currentImages.length === 0) {
+        panel.classList.add('hidden');
+        const flow = activeFlowName ? flowData()[activeFlowName] : null;
+        if (flow) clearFrustumImage(findCameraIdx(flow.cameraId));
+        return;
+    }
+    panel.classList.remove('hidden');
+
+    // Show/hide overlay buttons based on data availability
+    const hasLaserMask = currentLaserMasks.length > currentImageIdx && currentLaserMasks[currentImageIdx];
+    const hasLaserScore = currentLaserScores.length > currentImageIdx && currentLaserScores[currentImageIdx];
+    if (laserBtn) {
+        laserBtn.style.display = currentLaserMasks.length > 0 ? '' : 'none';
+        laserBtn.style.opacity = laserOverlayEnabled ? '1' : '0.5';
+    }
+    if (scoreBtn) {
+        scoreBtn.style.display = currentLaserScores.length > 0 ? '' : 'none';
+        scoreBtn.style.opacity = scoreOverlayEnabled ? '1' : '0.5';
+    }
+    if (projBtn) {
+        projBtn.style.display = currentProjectedContour ? '' : 'none';
+        projBtn.style.opacity = projectedOverlayEnabled ? '1' : '0.5';
+    }
+    if (alignBtn) {
+        alignBtn.style.display = currentAlignedContours[currentImageIdx] ? '' : 'none';
+        alignBtn.style.opacity = alignedOverlayEnabled ? '1' : '0.5';
+    }
+
+    // Check if any contour layers are visible (for projection overlay)
+    let hasVisibleContours = false;
+    for (const [key, grp] of Object.entries(layerGroups())) {
+        if (key.startsWith('contours') && grp.visible) { hasVisibleContours = true; break; }
+    }
+
+    // Determine if we need canvas compositing
+    const needsOverlay = (laserOverlayEnabled && hasLaserMask) ||
+                         (scoreOverlayEnabled && hasLaserScore) ||
+                         (projectedOverlayEnabled && currentProjectedContour) ||
+                         (alignedOverlayEnabled && currentAlignedContours[currentImageIdx]) ||
+                         hasVisibleContours;
+
+    if (needsOverlay) {
+        compositeOverlays(
+            currentImages[currentImageIdx],
+            laserOverlayEnabled ? (currentLaserMasks[currentImageIdx] || null) : null,
+            projectedOverlayEnabled ? currentProjectedContour : null,
+            alignedOverlayEnabled ? currentAlignedContours[currentImageIdx] : null,
+            canvas, img,
+            scoreOverlayEnabled ? (currentLaserScores[currentImageIdx] || null) : null,
+        );
+    } else {
+        canvas.style.display = 'none';
+        img.style.display = '';
+        img.src = currentImages[currentImageIdx];
+    }
+
+    counter.textContent = `${currentImageIdx + 1} / ${currentImages.length}`;
+    document.getElementById('btn-prev-img').disabled = currentImageIdx === 0;
+    document.getElementById('btn-next-img').disabled = currentImageIdx === currentImages.length - 1;
+
+    // Update frustum image plane
+    const flow = activeFlowName ? flowData()[activeFlowName] : null;
+    if (flow) setFrustumImage(findCameraIdx(flow.cameraId), currentImages[currentImageIdx]);
+
+    // Sync lightbox if open
+    updateLightbox();
+}
+
+// Monotonic token guarding compositeOverlays against out-of-order async loads.
+let _compositeSeq = 0;
+
+function compositeOverlays(baseUrl, laserMaskUrl, projUrl, alignUrl, canvas, imgEl, scoreUrl) {
+    const mySeq = ++_compositeSeq;
+
+    // Collect all URLs to load
+    const urls = { base: baseUrl };
+    if (laserMaskUrl) urls.laser = laserMaskUrl;
+    if (projUrl) urls.proj = projUrl;
+    if (alignUrl) urls.align = alignUrl;
+    if (scoreUrl) urls.score = scoreUrl;
+
+    const images = {};
+    const total = Object.keys(urls).length;
+    let loaded = 0;
+
+    function onAllLoaded() {
+        const base = images.base;
+        const w = base.naturalWidth;
+        const h = base.naturalHeight;
+        canvas.width = w;
+        canvas.height = h;
+        canvas.style.display = '';
+        canvas.style.width = '100%';
+        canvas.style.cursor = 'pointer';
+        imgEl.style.display = 'none';
+
+        const ctx = canvas.getContext('2d', { willReadFrequently: true });
+        ctx.drawImage(base, 0, 0, w, h);
+        const od = ctx.getImageData(0, 0, w, h);
+        const d = od.data;
+
+        // Helper: read overlay as grayscale
+        function readOverlay(img) {
+            const c = document.createElement('canvas');
+            c.width = w; c.height = h;
+            const cx = c.getContext('2d', { willReadFrequently: true });
+            cx.drawImage(img, 0, 0, w, h);
+            return cx.getImageData(0, 0, w, h).data;
+        }
+
+        // Laser mask: yellow tint
+        if (images.laser) {
+            const md = readOverlay(images.laser);
+            for (let i = 0; i < md.length; i += 4) {
+                const brightness = (md[i] + md[i+1] + md[i+2]) / 3;
+                if (brightness > 30) {
+                    const a = Math.min(brightness / 255, 0.7);
+                    d[i]     = Math.min(255, d[i]     + 200 * a | 0);
+                    d[i + 1] = Math.min(255, d[i + 1] + 200 * a | 0);
+                    d[i + 2] = Math.max(0,   d[i + 2] - 50  * a | 0);
+                }
+            }
+        }
+
+        // Laser score: cyan/magenta heatmap blend (proportional to brightness)
+        if (images.score) {
+            const sd = readOverlay(images.score);
+            for (let i = 0; i < sd.length; i += 4) {
+                const brightness = (sd[i] + sd[i+1] + sd[i+2]) / 3;
+                if (brightness > 30) {
+                    const a = Math.min(brightness / 255, 0.7);
+                    d[i]     = Math.max(0,   d[i]     - 50  * a | 0);
+                    d[i + 1] = Math.min(255, d[i + 1] + 150 * a | 0);
+                    d[i + 2] = Math.min(255, d[i + 2] + 200 * a | 0);
+                }
+            }
+        }
+
+        // Projected contour: red overlay
+        if (images.proj) {
+            const pd = readOverlay(images.proj);
+            for (let i = 0; i < pd.length; i += 4) {
+                if (pd[i] + pd[i+1] + pd[i+2] > 30) {
+                    d[i] = 255; d[i+1] = 50; d[i+2] = 50;
+                }
+            }
+        }
+
+        // Aligned contour: yellow, dilated 4x for thickness
+        if (images.align) {
+            const ad = readOverlay(images.align);
+            const radius = 4;
+            const contourPixels = [];
+            for (let y = 0; y < h; y++) {
+                for (let x = 0; x < w; x++) {
+                    const i = (y * w + x) * 4;
+                    if (ad[i] + ad[i+1] + ad[i+2] > 30) {
+                        contourPixels.push(x, y);
+                    }
+                }
+            }
+            for (let k = 0; k < contourPixels.length; k += 2) {
+                const cx = contourPixels[k], cy = contourPixels[k+1];
+                for (let dy = -radius; dy <= radius; dy++) {
+                    const py = cy + dy;
+                    if (py < 0 || py >= h) continue;
+                    for (let dx = -radius; dx <= radius; dx++) {
+                        const px = cx + dx;
+                        if (px < 0 || px >= w) continue;
+                        const i = (py * w + px) * 4;
+                        d[i] = 255; d[i+1] = 220; d[i+2] = 0;
+                    }
+                }
+            }
+        }
+
+        ctx.putImageData(od, 0, 0);
+
+        // Draw contour projections as 2D lines on top.
+        const flow = activeFlowName ? flowData()[activeFlowName] : null;
+        if (flow) {
+            const camIdx = findCameraIdx(flow.cameraId);
+            renderer.drawContourProjectionsOnCanvas(ctx, w, h, camIdx);
+        }
+    }
+
+    function tryComposite() {
+        if (mySeq !== _compositeSeq) return;
+        try { onAllLoaded(); } catch (e) {
+            canvas.style.display = 'none';
+            imgEl.style.display = '';
+            imgEl.src = baseUrl;
+        }
+    }
+
+    for (const [key, url] of Object.entries(urls)) {
+        loadSafeImage(url, (img) => {
+            images[key] = img;
+            if (++loaded === total) tryComposite();
+        });
+    }
+}
+
+function nextImage() {
+    if (currentImageIdx < currentImages.length - 1) {
+        currentImageIdx++;
+        updateImagePanel();
+    }
+}
+
+function prevImage() {
+    if (currentImageIdx > 0) {
+        currentImageIdx--;
+        updateImagePanel();
+    }
+}
+
+function nextStep() {
+    if (!activeFlowSteps.length) return;
+    currentStepIndex = (currentStepIndex + 1) % activeFlowSteps.length;
+    applyFlowStep();
+}
+
+function prevStep() {
+    if (!activeFlowSteps.length) return;
+    currentStepIndex = (currentStepIndex - 1 + activeFlowSteps.length) % activeFlowSteps.length;
+    applyFlowStep();
+}
+
+// Collect all laser groups that should be highlighted (playing + selected)
+// and update the contour display.
+function updateContourHighlights() {
+    const groups = new Set();
+    // Add groups from all playing flows
+    for (const flowName of Object.keys(playingFlows)) {
+        const lg = flowData()[flowName]?.laserGroup;
+        if (lg) groups.add(lg);
+    }
+    // Add group from selected flow
+    if (activeFlowName) {
+        const lg = flowData()[activeFlowName]?.laserGroup;
+        if (lg) groups.add(lg);
+    }
+    renderer.updateContourHighlights(groups);
+}
+
+// Apply a flow step for any flow (not just the active one).
+function applyFlowStepFor(flowName, stepIndex) {
+    const flow = flowData()[flowName];
+    if (!flow) return;
+    const step = flow.steps[stepIndex];
+    if (!step) return;
+
+    const camIdx = findCameraIdx(flow.cameraId);
+    if (camIdx < 0) return;
+
+    const desc = renderer.model.cameraAt(camIdx);
+    if (step.pan != null)  desc.ptz.pan  = step.pan;
+    if (step.tilt != null) desc.ptz.tilt = step.tilt;
+    if (step.zoom != null) desc.ptz.zoom = step.zoom;
+
+    if (step.location && step.location.x != null) {
+        const params = desc.params;
+        const dx = step.location.x - params.mount_t[0];
+        const dy = step.location.y - params.mount_t[1];
+        const dz = step.location.z - params.mount_t[2];
+        desc.frustumDistance = Math.sqrt(dx * dx + dy * dy + dz * dz) * 0.95;
+    }
+
+    updateCameraVisuals(camIdx);
+
+    // Always update frustum image for the playing flow's camera
+    const stepImages = step.images || [];
+    if (stepImages.length > 0) {
+        setFrustumImage(camIdx, stepImages[0]);
+    } else {
+        clearFrustumImage(camIdx);
+    }
+
+    // If this is also the active flow, update the UI panels
+    if (flowName === activeFlowName) {
+        currentStepIndex = stepIndex;
+        if (camIdx === selectedCameraIdx && activePTZSliders) {
+            const ptz = desc.ptz;
+            for (const key of ['pan', 'tilt', 'zoom']) {
+                const slider = activePTZSliders[key];
+                if (slider) {
+                    slider.input.value = ptz[key];
+                    slider.valueSpan.textContent = key === 'zoom'
+                        ? Math.round(ptz[key])
+                        : ptz[key].toFixed(1);
+                }
+            }
+        }
+        document.getElementById('step-counter').textContent =
+            `Step ${stepIndex + 1} / ${flow.steps.length}`;
+        updateStepInfo();
+        currentImages = stepImages;
+        currentLaserMasks = step.laser_masks || [];
+        currentLaserScores = step.laser_scores || [];
+        currentProjectedContour = step.projected_contour || null;
+        currentAlignedContours = step.aligned_contours || [];
+        currentImageIdx = 0;
+        updateImagePanel();
+    }
+}
+
+function toggleFlowPlay(flowName, btn) {
+    if (playingFlows[flowName]) {
+        clearInterval(playingFlows[flowName].intervalId);
+        delete playingFlows[flowName];
+        if (btn) btn.innerHTML = '&#9654;';
+        // Update global button if this is the active flow
+        if (flowName === activeFlowName) {
+            const gBtn = document.getElementById('btn-play-stop');
+            if (gBtn) gBtn.innerHTML = '&#9654; Play';
+        }
+    } else {
+        const flow = flowData()[flowName];
+        if (!flow || !flow.steps.length) return;
+        let stepIdx = flowName === activeFlowName ? currentStepIndex : 0;
+        playingFlows[flowName] = {
+            intervalId: setInterval(() => {
+                stepIdx = (stepIdx + 1) % flow.steps.length;
+                playingFlows[flowName].stepIndex = stepIdx;
+                applyFlowStepFor(flowName, stepIdx);
+            }, 500),
+            stepIndex: stepIdx,
+        };
+        if (btn) btn.innerHTML = '&#9632;';
+        if (flowName === activeFlowName) {
+            const gBtn = document.getElementById('btn-play-stop');
+            if (gBtn) gBtn.innerHTML = '&#9632; Stop';
+        }
+    }
+    updateContourHighlights();
+}
+
+function togglePlay() {
+    if (!activeFlowName) return;
+    const treeBtn = document.querySelector(`.cam-tree-flow[data-flow-name="${activeFlowName}"] .flow-play-btn`);
+    toggleFlowPlay(activeFlowName, treeBtn);
+}
+
+function stopPlay() {
+    if (!activeFlowName) return;
+    if (playingFlows[activeFlowName]) {
+        const treeBtn = document.querySelector(`.cam-tree-flow[data-flow-name="${activeFlowName}"] .flow-play-btn`);
+        toggleFlowPlay(activeFlowName, treeBtn);
+    }
+}
+
+function updateStepInfo() {
+    const container = document.getElementById('step-info');
+    const step = activeFlowSteps[currentStepIndex];
+    if (!step) { container.innerHTML = ''; return; }
+
+    let html = '<div class="step-info-grid">';
+    if (step.pan != null)  html += `<div class="si-row"><span class="si-label">Pan</span><span class="si-value">${step.pan.toFixed(2)}°</span></div>`;
+    if (step.tilt != null) html += `<div class="si-row"><span class="si-label">Tilt</span><span class="si-value">${step.tilt.toFixed(2)}°</span></div>`;
+    if (step.zoom != null) html += `<div class="si-row"><span class="si-label">Zoom</span><span class="si-value">${Math.round(step.zoom)}</span></div>`;
+
+    if (step.location && step.location.x != null) {
+        const l = step.location;
+        html += `<div class="si-row"><span class="si-label">Target</span><span class="si-value">${l.x.toFixed(0)}, ${l.y.toFixed(0)}, ${l.z.toFixed(0)}</span></div>`;
+    }
+
+    if (step.cornerInfo && step.cornerInfo.isCorner) {
+        html += `<div class="si-row"><span class="si-label">Corner</span><span class="si-value">${step.cornerInfo.cornerType || 'Yes'}</span></div>`;
+    }
+
+    html += '</div>';
+    container.innerHTML = html;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Defect info panel (right sidebar)
+// ═══════════════════════════════════════════════════════════════
+
+function showDefectInfo(defect) {
+    const rightSidebar = document.getElementById('right-sidebar');
+    const detail = document.getElementById('camera-detail');
+    const flowNav = document.getElementById('flow-nav');
+
+    selectedCameraIdx = -1;
+    document.querySelectorAll('.cam-tree-header').forEach(el => el.classList.remove('selected'));
+
+    rightSidebar.classList.remove('hidden');
+    document.getElementById('right-sidebar-title').textContent = defect.name || defect.id;
+    flowNav.classList.add('hidden');
+    activePTZSliders = null;
+
+    const sev = (defect.severity || 'unknown');
+    const SCOLORS = { critical: '#f44', high: '#f88', medium: '#fa4', low: '#ff4', unknown: '#888' };
+    const sevColor = SCOLORS[sev.toLowerCase()] || SCOLORS.unknown;
+
+    detail.innerHTML = `
+        <div class="param-section">
+            <div class="param-section-title">Defect</div>
+            <div class="param-row"><span class="param-name">Type</span><span class="param-value">${defect.type || '—'}</span></div>
+            <div class="param-row"><span class="param-name">Severity</span><span class="param-value" style="color:${sevColor};font-weight:600">${sev}</span></div>
+            ${defect.confidence != null ? `<div class="param-row"><span class="param-name">Confidence</span><span class="param-value">${(defect.confidence * 100).toFixed(1)}%</span></div>` : ''}
+            <div class="param-section-title" style="margin-top:8px">Position (mm)</div>
+            <div class="param-row"><span class="param-name">X</span><span class="param-value">${defect.x.toFixed(0)}</span></div>
+            <div class="param-row"><span class="param-name">Y</span><span class="param-value">${defect.y.toFixed(0)}</span></div>
+            <div class="param-row"><span class="param-name">Z</span><span class="param-value">${defect.z.toFixed(0)}</span></div>
+        </div>
+    `;
+
+    setTimeout(() => window.dispatchEvent(new Event('resize')), 50);
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Canvas click: camera + defect picking
+// ═══════════════════════════════════════════════════════════════
+
+function onCanvasClick(event) {
+    const canvas = event.target;
+    const rect = canvas.getBoundingClientRect();
+    mouse.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
+    mouse.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
+
+    raycaster.setFromCamera(mouse, cam());
+
+    // Check cameras — raycast shell + internals (avoids false hits on frustum/image plane)
+    const perCameraList = renderer.perCamera();
+    const rayTargets = [];
+    for (const pc of perCameraList) {
+        rayTargets.push(...pc.shell.children, ...pc.internals.children);
+    }
+    if (rayTargets.length > 0) {
+        const intersects = raycaster.intersectObjects(rayTargets, true);
+        if (intersects.length > 0) {
+            let obj = intersects[0].object;
+            while (obj && obj.userData.cameraIdx === undefined) obj = obj.parent;
+            if (obj && obj.userData.cameraIdx !== undefined) {
+                selectCamera(obj.userData.cameraIdx);
+                return;
+            }
+        }
+    }
+
+    // Check defects
+    const defectGroup = layerGroups()['defects'];
+    if (defectGroup) {
+        const intersects = raycaster.intersectObjects(defectGroup.children, false);
+        if (intersects.length > 0) {
+            const obj = intersects[0].object;
+            const idx = obj.userData.defectIdx;
+            if (idx !== undefined && defectEntries()[idx]) {
+                showDefectInfo(defectEntries()[idx]);
+            }
+        }
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Lightbox: larger bottom panel on image click
+// ═══════════════════════════════════════════════════════════════
+
+function toggleLightbox() {
+    if (currentImages.length === 0) return;
+    if (lightboxOpen) closeLightbox();
+    else openLightbox();
+}
+
+function openLightbox() {
+    lightboxOpen = true;
+    document.getElementById('image-lightbox').classList.remove('hidden');
+    updateLightbox();
+    window.dispatchEvent(new Event('resize'));
+}
+
+function closeLightbox() {
+    if (!lightboxOpen) return;
+    lightboxOpen = false;
+    document.getElementById('image-lightbox').classList.add('hidden');
+    window.dispatchEvent(new Event('resize'));
+}
+
+function updateLightbox() {
+    if (!lightboxOpen || currentImages.length === 0) return;
+    const lbImg = document.getElementById('lightbox-img');
+    const lbCanvas = document.getElementById('lightbox-canvas');
+    const hasLaserMask = currentLaserMasks.length > currentImageIdx && currentLaserMasks[currentImageIdx];
+    const hasLaserScore = currentLaserScores.length > currentImageIdx && currentLaserScores[currentImageIdx];
+
+    let hasVisibleContoursLb = false;
+    for (const [key, grp] of Object.entries(layerGroups())) {
+        if (key.startsWith('contours') && grp.visible) { hasVisibleContoursLb = true; break; }
+    }
+
+    const needsOverlay = (laserOverlayEnabled && hasLaserMask) ||
+                         (scoreOverlayEnabled && hasLaserScore) ||
+                         (projectedOverlayEnabled && currentProjectedContour) ||
+                         (alignedOverlayEnabled && currentAlignedContours[currentImageIdx]) ||
+                         hasVisibleContoursLb;
+
+    if (needsOverlay) {
+        compositeOverlays(
+            currentImages[currentImageIdx],
+            laserOverlayEnabled ? (currentLaserMasks[currentImageIdx] || null) : null,
+            projectedOverlayEnabled ? currentProjectedContour : null,
+            alignedOverlayEnabled ? currentAlignedContours[currentImageIdx] : null,
+            lbCanvas, lbImg,
+            scoreOverlayEnabled ? (currentLaserScores[currentImageIdx] || null) : null,
+        );
+        lbCanvas.style.objectFit = 'contain';
+        lbCanvas.style.maxWidth = '100%';
+        lbCanvas.style.maxHeight = '100%';
+    } else {
+        lbCanvas.style.display = 'none';
+        lbImg.style.display = '';
+        lbImg.src = currentImages[currentImageIdx];
+    }
+    document.getElementById('lightbox-counter').textContent =
+        `${currentImageIdx + 1} / ${currentImages.length}`;
+    document.getElementById('lightbox-prev').disabled = currentImageIdx === 0;
+    document.getElementById('lightbox-next').disabled = currentImageIdx === currentImages.length - 1;
+}
+
+function setupLightboxResize() {
+    const handle = document.getElementById('lightbox-resize-handle');
+    const lightbox = document.getElementById('image-lightbox');
+    let dragging = false, startY = 0, startH = 0;
+    handle.addEventListener('mousedown', (e) => {
+        dragging = true;
+        startY = e.clientY;
+        startH = lightbox.offsetHeight;
+        e.preventDefault();
+    });
+    on( document, 'mousemove', (e) => {
+        if (!dragging) return;
+        const delta = startY - e.clientY; // drag up = taller
+        lightbox.style.height = Math.max(120, Math.min(700, startH + delta)) + 'px';
+        window.dispatchEvent(new Event('resize'));
+    });
+    on( document, 'mouseup', () => { dragging = false; });
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Utility
+// ═══════════════════════════════════════════════════════════════
+
+function mkEl(tag, cls) {
+    const e = document.createElement(tag);
+    if (cls) e.className = cls;
+    return e;
+}
+
+function fmtN(v, d) {
+    if (v === null || v === undefined) return '—';
+    return Number(v).toFixed(d);
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Mount API (library entry)
+// ═══════════════════════════════════════════════════════════════
+//
+// The viewer is consumed two ways:
+//   - Standalone (/viz/, dev server, Python wheel): src/standalone.js reads the
+//     URL into opts and calls mountViewer(document.body, opts).
+//   - Embedded (Imaginarium React <ShellVisualizer>): the host calls
+//     mountViewer(divRef, { shellId, configId }) and destroy() on unmount.
+//
+// mountViewer injects the DOM skeleton into the container (so the existing
+// getElementById wiring works), runs init() against `_opts`, and returns a
+// handle. destroy() stops every loop/interval/listener and frees the GPU so a
+// React route can mount/unmount it repeatedly without leaks or double-handling.
+
+export async function mountViewer( container, opts = {} ) {
+    if ( _alive ) { destroy(); }               // idempotent re-mount
+    _container = container || document.body;
+    if ( !_container.querySelector( '#app' ) ) { _container.innerHTML = VIEWER_SKELETON; }
+    _opts = opts || {};
+    _alive = true;
+    try {
+        await init();
+    } catch ( err ) {
+        console.error( 'Viewer init failed:', err );
+        const el = document.getElementById( 'loading' );
+        if ( el ) { el.textContent = `Init failed: ${err.message}`; }
+        throw err;
+    }
+    return { destroy };
+}
+
+export function destroy() {
+    if ( !_alive && !renderer ) { return; }
+    _alive = false;                            // the rAF loops bail on their next tick
+    while ( _teardown.length ) { _teardown.pop()(); }   // remove window/document listeners
+    for ( const f of Object.keys( playingFlows ) ) {    // stop flow-playback intervals
+        clearInterval( playingFlows[f].intervalId );
+        delete playingFlows[f];
+    }
+    if ( povAnimationId ) { cancelAnimationFrame( povAnimationId ); povAnimationId = null; }
+    if ( _viewFlyId ) { cancelAnimationFrame( _viewFlyId ); _viewFlyId = null; }
+    if ( renderer ) { renderer.dispose(); }
+    renderer = null;
+    sceneData = null;
+    raycaster = null;
+    mouse = null;
+    selectedCameraIdx = -1;
+    povCameraIdx = -1;
+    activeFlowName = null;
+    if ( _container ) { _container.innerHTML = ''; _container = null; }
+}