@triscope/core 0.4.0

package/dist/harness.js

@@ -0,0 +1,1027 @@
+import * as THREE from 'three/webgpu';
+import { mountEditor } from './editor.js';
+import { createInspectMode, readInspectFromUrl, } from './inspect.js';
+import { clampKnob } from './knob-utils.js';
+import { MotionProbeBuffer } from './motion-probe.js';
+import { isBlackFrame } from './probe-utils.js';
+import { autoCameras } from './scene-cameras.js';
+import { applyCameraDelta, applyElementToggle } from './scene-delta.js';
+import { serializeScene } from './scene-introspect.js';
+import { nsKey } from './scene-registry.js';
+import { installSourceTagPatch } from './source-tag.js';
+import { knobDefault } from './types.js';
+import { readUniformValue, writeUniformValue, } from './uniform-access.js';
+import { validateElement } from './validate.js';
+import { createWarningRing } from './warnings.js';
+// Patched once at module load — every Object3D.add() across any element in
+// any lab gets the auto source-tag. Idempotent across multiple runLab().
+installSourceTagPatch();
+/**
+ * Boot a multi-camera lab page for a single Element.
+ * One WebGPURenderer, one scene, one Element, N scissored viewports.
+ *
+ * Thin wrapper over {@link runSceneCore}: a one-entry, non-namespaced registry.
+ * The single-element path is behaviorally identical to before this was
+ * generalized — bare camera/knob names, `elements: { [name]: … }`,
+ * `project: name`.
+ */
+export async function runLab(opts) {
+    return runSceneCore(opts, {
+        entries: [{ name: opts.element.name, element: opts.element }],
+        namespaced: false,
+        initialMounted: [opts.element.name],
+    });
+}
+/**
+ * Boot a multi-camera lab page for a SCENE of N Elements, with runtime
+ * mount/unmount via the returned handle's addElement/removeElement (and the
+ * MCP add_element/remove_element tools). Camera + knob keys are namespaced
+ * `<element>.<key>` so two elements that both declare `top`/`speed` never
+ * collide. Shares one renderer/scene with runLab through {@link runSceneCore}.
+ */
+export async function runSceneLab(opts) {
+    const entries = opts.elements.map((e) => ({ name: e.name, element: e }));
+    return runSceneCore(opts, {
+        entries,
+        namespaced: true,
+        initialMounted: opts.mounted ?? entries.map((e) => e.name),
+    });
+}
+async function runSceneCore(opts, registry) {
+    const { entries, namespaced, initialMounted } = registry;
+    const { canvas, editorContainer = null, labelContainer = null, hud = null, bootOverlay = null, telemetryIntervalMs = 500, knobPollMs = 100, clearColor = 0x0a1a20, } = opts;
+    if (!('gpu' in navigator)) {
+        throw new Error('navigator.gpu is unavailable — open this page in Chrome/Edge with WebGPU enabled.');
+    }
+    const renderer = new THREE.WebGPURenderer({ canvas, antialias: true });
+    await renderer.init();
+    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+    renderer.setClearColor(clearColor, 1);
+    renderer.autoClear = false;
+    const scene = new THREE.Scene();
+    const time = { value: 0 };
+    const dt = { value: 0 };
+    const ctx = { renderer, scene, time, dt };
+    // Ring of swallowed non-fatal failures, surfaced via telemetry .warnings so
+    // an agent can diagnose "why is telemetry stale / the knob not applying /
+    // this pane black?" instead of guessing. Created before mount so contract
+    // problems and a mount throw are both recorded.
+    const warnings = createWarningRing(32);
+    const slots = [];
+    const cameras = {};
+    const cameraOrder = [];
+    const cameraElement = {}; // display camera name → slot name
+    const knobs = {}; // display key → spec
+    const knobValues = {};
+    const knobBinding = {}; // display key → routing
+    // Persisted knob values (previous session, before a full reload) keyed by
+    // element name → local key; override spec defaults so user tuning survives
+    // shader edits. Fetched once; mountSlot reads the per-element slice.
+    let persistedKnobs = {};
+    try {
+        const r = await fetch('/__knob/current');
+        if (r.ok)
+            persistedKnobs = (await r.json());
+    }
+    catch {
+        /* dev server transient — fall through to defaults */
+    }
+    // Validate the Element contract + run mount() inside an error boundary, so a
+    // bad element surfaces a precise error (boot overlay + __TRISCOPE_MOUNT_ERROR__,
+    // which the MCP browser pool reads) instead of a blind "harness not mounted"
+    // timeout. We deliberately do NOT set window.__TRISCOPE__ on failure — its
+    // absence stays the "not mounted" signal. Registers the element's namespaced
+    // cameras + knobs (with persisted-value restore + clamp + initial onKnob).
+    // Returns null if `name` is already mounted (so addElement is idempotent).
+    function mountSlot(name, el) {
+        if (slots.some((s) => s.name === name))
+            return null;
+        const contractProblems = validateElement(el);
+        for (const p of contractProblems)
+            warnings.push('validate', namespaced ? `${name}: ${p}` : p);
+        let handle;
+        try {
+            handle = el.mount({ parent: scene, ctx });
+            if (!handle || typeof handle.dispose !== 'function') {
+                throw new Error('mount() did not return a { root, dispose } handle');
+            }
+        }
+        catch (err) {
+            const msg = errDetail(err);
+            if (typeof window !== 'undefined') {
+                window.__TRISCOPE_MOUNT_ERROR__ = {
+                    element: name,
+                    message: msg,
+                    problems: contractProblems,
+                };
+            }
+            if (bootOverlay)
+                bootOverlay.textContent = `mount failed: ${msg}`;
+            throw new Error(`triscope: element "${name}" failed to mount: ${msg}`);
+        }
+        const probeKeys = Object.keys(el.motionProbes ?? {});
+        const probeBuffers = {};
+        for (const k of probeKeys)
+            probeBuffers[k] = new MotionProbeBuffer(120);
+        const slot = { name, element: el, handle, probeKeys, probeBuffers };
+        slots.push(slot);
+        // PerspectiveCamera per named CameraSpec (namespaced display key).
+        // `cameras: 'auto'` → synthesize 4 fitted presets from bounds.
+        const camSpecs = el.cameras === 'auto' ? autoCameras(el.bounds) : (el.cameras ?? {});
+        for (const [local, spec] of Object.entries(camSpecs)) {
+            const disp = nsKey(name, local, namespaced);
+            // Guard the pathological case where a dotted element name collides with
+            // another element's name+key (both → the same display key).
+            if (cameraElement[disp] && cameraElement[disp] !== name) {
+                warnings.push('ns-collision', `camera key "${disp}" collides across elements`);
+            }
+            cameras[disp] = makeCamera(spec, el.bounds);
+            cameraElement[disp] = name;
+            if (!cameraOrder.includes(disp))
+                cameraOrder.push(disp);
+        }
+        // Knob state with restore + clamp + initial onKnob.
+        const persisted = persistedKnobs?.[name] ?? {};
+        for (const [local, spec] of Object.entries(el.knobs ?? {})) {
+            const disp = nsKey(name, local, namespaced);
+            if (knobBinding[disp] && knobBinding[disp].slot !== slot) {
+                warnings.push('ns-collision', `knob key "${disp}" collides across elements`);
+            }
+            knobs[disp] = spec;
+            knobBinding[disp] = { slot, local };
+            // Trigger knobs have no persistent value and must not fire on mount —
+            // they are pure action signals; onKnob only when set_knob is called.
+            if (spec.type === 'trigger') {
+                knobValues[disp] = false;
+                continue;
+            }
+            // Persisted store is keyed element→<whatever key was POSTed>. set_knob
+            // POSTs the manifest's advertised name, which is the DISPLAY key (`disp`)
+            // in a namespaced scene, so read `disp` and fall back to the bare local
+            // key (single-element labs + legacy stores). Without the `disp` fallback,
+            // namespaced scenes silently lose all tuning on every reload.
+            const saved = persisted[disp] !== undefined ? persisted[disp] : persisted[local];
+            const candidate = (saved !== undefined ? saved : knobDefault(spec));
+            // Clamp restored/default values too — a persisted out-of-range value (or a
+            // spec whose range shrank since it was saved) must not reach the element.
+            knobValues[disp] = clampKnob(spec, candidate).final;
+            // Guard the initial onKnob like telemetry/events/probes: a throwing
+            // element must degrade to a warning, not abort the (multi-element) boot.
+            if (el.onKnob) {
+                try {
+                    el.onKnob(handle, local, knobValues[disp]);
+                }
+                catch (e) {
+                    warnings.push('onKnob', `${name}.${local} onKnob threw on mount`, errDetail(e));
+                }
+            }
+        }
+        return slot;
+    }
+    // Dispose a mounted slot + drop its cameras/knobs/probes. Returns false if it
+    // wasn't mounted. Does NOT rebuild labels/editor/viewports — addElement/
+    // removeElement do that once after the mutation completes.
+    function unmountSlot(name) {
+        const idx = slots.findIndex((s) => s.name === name);
+        if (idx < 0)
+            return false;
+        const slot = slots[idx];
+        for (const disp of Object.keys(cameraElement)) {
+            if (cameraElement[disp] !== name)
+                continue;
+            delete cameras[disp];
+            delete cameraElement[disp];
+            const oi = cameraOrder.indexOf(disp);
+            if (oi >= 0)
+                cameraOrder.splice(oi, 1);
+        }
+        for (const [disp, b] of Object.entries(knobBinding)) {
+            if (b.slot !== slot)
+                continue;
+            delete knobBinding[disp];
+            delete knobs[disp];
+            delete knobValues[disp];
+        }
+        slots.splice(idx, 1);
+        try {
+            slot.handle.dispose();
+        }
+        catch (e) {
+            warnings.push('unmount', `dispose of "${name}" threw`, errDetail(e));
+        }
+        return true;
+    }
+    // Initial mount (registry declaration order, filtered to the mounted set).
+    // A mount throw here propagates out of runSceneCore exactly as before.
+    for (const e of entries) {
+        if (initialMounted.includes(e.name))
+            mountSlot(e.name, e.element);
+    }
+    // Editor — rebuilt on add/remove so newly mounted knobs appear and removed
+    // ones vanish. For the single-element path this builds the identical editor.
+    let editor = null;
+    function rebuildEditor() {
+        if (!editorContainer)
+            return;
+        editorContainer.replaceChildren();
+        editor = null;
+        if (Object.keys(knobs).length > 0) {
+            editor = mountEditor(editorContainer, knobs, knobValues, (key, value) => applyKnob(key, value, false));
+        }
+    }
+    rebuildEditor();
+    function applyKnob(key, value, fromExternal) {
+        const spec = knobs[key];
+        const bind = knobBinding[key];
+        if (spec?.type === 'trigger') {
+            // Trigger: don't persist value, always pass `true` to onKnob regardless
+            // of what the caller passed. The value is purely a pulse signal. Routed
+            // to the owning element's onKnob with the element-local key.
+            bind?.slot.element.onKnob?.(bind.slot.handle, bind.local, true);
+            if (fromExternal && editor)
+                editor.setValue(key, true);
+            return;
+        }
+        // Clamp/validate against the spec so a stray value (e.g. windPressure=9999)
+        // can't silently corrupt the scene; record a warning the agent can read.
+        let next = value;
+        if (spec) {
+            const c = clampKnob(spec, value);
+            next = c.final;
+            if (c.clamped) {
+                warnings.push('knob-clamp', `${key}=${JSON.stringify(value)} out of range → ${JSON.stringify(next)}`);
+            }
+        }
+        knobValues[key] = next;
+        bind?.slot.element.onKnob?.(bind.slot.handle, bind.local, next);
+        if (fromExternal && editor)
+            editor.setValue(key, next);
+    }
+    // Camera labels (HTML overlays) — positioned dynamically each frame; rebuilt
+    // when slots change so labels track the current camera grid.
+    const labelEls = {};
+    function rebuildLabels() {
+        if (!labelContainer)
+            return;
+        for (const el of Object.values(labelEls))
+            el.remove();
+        for (const k of Object.keys(labelEls))
+            delete labelEls[k];
+        for (const name of cameraOrder) {
+            const el = document.createElement('div');
+            el.className = 'triscope-label';
+            el.textContent = name.toUpperCase();
+            el.style.position = 'absolute';
+            el.style.pointerEvents = 'none';
+            el.style.zIndex = '5';
+            labelContainer.appendChild(el);
+            labelEls[name] = el;
+        }
+    }
+    rebuildLabels();
+    // Post one manifest entry per mounted element so MCP can discover them. For a
+    // scene each element resolves to this page's labUrl; camera + knob names are
+    // the element's namespaced display keys. Re-posted on add (addElement).
+    function postManifestFor(slot) {
+        const specs = slot.element.cameras === 'auto'
+            ? autoCameras(slot.element.bounds)
+            : (slot.element.cameras ?? {});
+        const cams = Object.entries(specs).map(([local, c]) => ({
+            name: nsKey(slot.name, local, namespaced),
+            ...c,
+        }));
+        const ks = Object.entries(knobBinding)
+            .filter(([, b]) => b.slot === slot)
+            .map(([disp]) => ({ name: disp, ...knobs[disp], current: knobValues[disp] }));
+        postManifest({
+            element: slot.name,
+            labUrl: slot.element.labUrl ??
+                (typeof window !== 'undefined' ? window.location.pathname : undefined),
+            cameras: cams,
+            knobs: ks,
+        }).catch((e) => warnings.push('postManifest', 'POST /__manifest failed', errDetail(e)));
+    }
+    for (const slot of slots)
+        postManifestFor(slot);
+    // FPS + frame loop state.
+    let frames = 0;
+    let fpsWindowMs = 0;
+    let fps = 0;
+    // Monotonic count of rendered frames since boot. Unlike `fps` (recomputed only
+    // every ~500ms, so it reads 0 for the first half-second even while rendering),
+    // this is true on the very first RAF after mount — the MCP browser pool gates
+    // captures on it so a fresh navigate never captures a black/pre-render frame.
+    let framesRendered = 0;
+    let lastT = performance.now();
+    let lastTelemetryT = 0;
+    let lastKnobPollT = 0;
+    let running = true;
+    // Motion-probe ring buffers are per slot (see Slot.probeBuffers) — 120
+    // samples ≈ 2 s at 60 fps; telemetry exposes summary stats per element.
+    // Discrete-event ring buffer (cap 128). The harness drains element.events()
+    // each frame and appends to this buffer; sampleTelemetry surfaces it as
+    // `telemetry.events` so MCP read_telemetry .events can verify post-fact.
+    const EVENT_BUFFER_CAP = 128;
+    const eventBuffer = [];
+    function resize() {
+        const w = canvas.clientWidth || window.innerWidth;
+        const h = canvas.clientHeight || window.innerHeight;
+        renderer.setSize(w, h, false);
+        // Update aspect for all cameras.
+        const n = cameraOrder.length;
+        const cols = Math.ceil(Math.sqrt(n));
+        const rows = Math.ceil(n / cols);
+        const paneW = w / cols;
+        const paneH = h / rows;
+        for (const name of cameraOrder) {
+            cameras[name].aspect = paneW / Math.max(paneH, 1);
+            cameras[name].updateProjectionMatrix();
+        }
+        if (labelContainer) {
+            cameraOrder.forEach((name, i) => {
+                const col = i % cols;
+                const row = Math.floor(i / cols);
+                const el = labelEls[name];
+                if (!el)
+                    return;
+                el.style.left = `${col * paneW + 8}px`;
+                el.style.top = `${row * paneH + 8}px`;
+            });
+        }
+    }
+    window.addEventListener('resize', resize);
+    resize();
+    // Inspect mode (URL ?inspect=<el>&camera=<name>): solo full-canvas view
+    // with OrbitControls, click-picking, hover highlight. Falls back to the
+    // grid view when the URL param is absent or targets a different element.
+    let inspectMode = null;
+    let currentSelection = null;
+    let currentSelections = [];
+    // (Re)build inspect mode against the CURRENT slots. Called at boot and after
+    // every add/remove: disposing the prior instance frees its overlays + the
+    // geometry they borrowed (otherwise removing the inspected element leaves a
+    // ghost wireframe pinned to freed GPU geometry), and re-matching the URL means
+    // inspect follows a re-added element / falls back to the grid when its target
+    // is gone. Match ?inspect= against any mounted element (single-element labs
+    // reduce to readInspectFromUrl(element.name)).
+    function setupInspect() {
+        if (inspectMode) {
+            inspectMode.dispose();
+            inspectMode = null;
+        }
+        let inspectCfg = null;
+        let inspectName = slots[0]?.name ?? '';
+        for (const s of slots) {
+            const cfg = readInspectFromUrl(s.name);
+            if (cfg) {
+                inspectCfg = cfg;
+                inspectName = s.name;
+                break;
+            }
+        }
+        if (!inspectCfg)
+            return;
+        inspectMode = createInspectMode({
+            renderer,
+            scene,
+            cameras,
+            elementName: inspectName,
+            canvas,
+            cameraName: inspectCfg.camera,
+            onSelectionChange: (sel, all) => {
+                currentSelection = sel;
+                currentSelections = all ?? [];
+                if (typeof window !== 'undefined' && window.__TRISCOPE__) {
+                    window.__TRISCOPE__.lastSelection = sel;
+                    window.__TRISCOPE__.selections = currentSelections;
+                }
+            },
+        });
+    }
+    setupInspect();
+    function renderAll() {
+        const n = cameraOrder.length;
+        const cols = Math.ceil(Math.sqrt(n));
+        const rows = Math.ceil(n / cols);
+        const w = renderer.domElement.width / renderer.getPixelRatio();
+        const h = renderer.domElement.height / renderer.getPixelRatio();
+        const paneW = w / cols;
+        const paneH = h / rows;
+        renderer.setScissorTest(false);
+        renderer.clear();
+        renderer.setScissorTest(true);
+        cameraOrder.forEach((name, i) => {
+            const col = i % cols;
+            const row = Math.floor(i / cols);
+            const x = col * paneW;
+            // Three.js viewport origin is bottom-left; flip rows.
+            const y = (rows - 1 - row) * paneH;
+            renderer.setViewport(x, y, paneW, paneH);
+            renderer.setScissor(x, y, paneW, paneH);
+            renderer.render(scene, cameras[name]);
+        });
+        renderer.setScissorTest(false);
+    }
+    function tick() {
+        if (!running)
+            return;
+        const now = performance.now();
+        const delta = (now - lastT) / 1000;
+        lastT = now;
+        time.value += delta;
+        dt.value = delta;
+        fpsWindowMs += delta * 1000;
+        frames += 1;
+        if (fpsWindowMs > 500) {
+            fps = (frames * 1000) / fpsWindowMs;
+            frames = 0;
+            fpsWindowMs = 0;
+            if (hud)
+                hud.textContent = `${fps.toFixed(0)} fps · WebGPU · ${labLabel()}`;
+        }
+        // Sample motion probes before render so they see the just-advanced time.
+        // Per slot: probe keys are element-local, buffered on the owning slot.
+        for (const slot of slots) {
+            if (slot.probeKeys.length === 0 || !slot.element.motionProbes)
+                continue;
+            for (const k of slot.probeKeys) {
+                try {
+                    const v = slot.element.motionProbes[k](slot.handle, ctx);
+                    if (Number.isFinite(v))
+                        slot.probeBuffers[k].push(v, time.value);
+                }
+                catch (e) {
+                    // probe failures must not break the loop — but the agent should know
+                    warnings.push('motion-probe', `probe "${slot.name}.${k}" threw`, errDetail(e));
+                }
+            }
+        }
+        // Drain discrete events (cannon fires, collisions, etc.) into ring buffer.
+        for (const slot of slots) {
+            if (!slot.element.events)
+                continue;
+            try {
+                const drained = slot.element.events(slot.handle, ctx) ?? [];
+                for (const ev of drained) {
+                    eventBuffer.push(ev);
+                    if (eventBuffer.length > EVENT_BUFFER_CAP)
+                        eventBuffer.shift();
+                }
+            }
+            catch (e) {
+                warnings.push('event-drain', `events() of "${slot.name}" threw`, errDetail(e));
+            }
+        }
+        if (inspectMode?.active)
+            inspectMode.render();
+        else
+            renderAll();
+        framesRendered += 1;
+        if (now - lastTelemetryT > telemetryIntervalMs) {
+            lastTelemetryT = now;
+            postState(buildState()).catch((e) => warnings.push('postState', 'POST /__state failed', errDetail(e)));
+        }
+        if (now - lastKnobPollT > knobPollMs) {
+            lastKnobPollT = now;
+            pollKnobs().catch((e) => warnings.push('pollKnobs', 'GET /__knob failed', errDetail(e)));
+            // Same cadence as knob polling (no extra timer): drain SDL scene deltas.
+            pollScene().catch((e) => warnings.push('pollScene', 'GET /__scene failed', errDetail(e)));
+        }
+        requestAnimationFrame(tick);
+    }
+    // Display label for the lab (hud + telemetry .project): the single element's
+    // name for runLab, or `a+b+…` of mounted elements for a scene.
+    function labLabel() {
+        return namespaced ? slots.map((s) => s.name).join('+') || 'scene' : (slots[0]?.name ?? '');
+    }
+    function buildState() {
+        const elements = {};
+        for (const slot of slots) {
+            let tel = {};
+            if (slot.element.telemetry) {
+                try {
+                    tel = slot.element.telemetry(slot.handle, ctx);
+                }
+                catch (e) {
+                    warnings.push('telemetry-fn', `telemetry() of "${slot.name}" threw`, errDetail(e));
+                }
+            }
+            if (slot.probeKeys.length > 0) {
+                const motion = {};
+                for (const k of slot.probeKeys)
+                    motion[k] = slot.probeBuffers[k].stats();
+                elements[slot.name] = { ...tel, motion };
+            }
+            else {
+                elements[slot.name] = tel;
+            }
+        }
+        return {
+            project: labLabel(),
+            // Wall-clock of this snapshot so a reader (MCP read_telemetry) can compute
+            // staleness — telemetry on disk / served by the dev server may be seconds
+            // old if the lab tab was backgrounded or closed.
+            postedAt: Date.now(),
+            perf: { fps, dpr: renderer.getPixelRatio() },
+            time: time.value,
+            knobs: { ...knobValues },
+            cameras: Object.fromEntries(cameraOrder.map((n) => [
+                n,
+                {
+                    position: cameras[n].position.toArray(),
+                    target: targetOf(cameras[n]),
+                    fov: cameras[n].fov,
+                },
+            ])),
+            elements,
+            // Event ring buffer (cap 128). Drained per-frame via element.events();
+            // shallow-copied here so downstream consumers see a stable snapshot.
+            events: eventBuffer.slice(),
+            // Last clicked mesh in inspect mode (?inspect=<el>) — null when not
+            // in inspect mode or nothing was clicked. Read via MCP
+            // `read_telemetry .selection` so the model knows which file:line to
+            // edit when the user says "fix this".
+            selection: currentSelection,
+            selections: currentSelections,
+            inspectActive: !!inspectMode?.active,
+            // Swallowed non-fatal failures since boot (cap 32). Read via
+            // `read_telemetry .warnings` to diagnose stale telemetry / clamped
+            // knobs / black frames without guessing.
+            warnings: warnings.list(),
+            // Per-element on/off state (SDL show/hide) so get_scene / read_telemetry
+            // can observe which elements are currently visible.
+            sceneElements: sceneElementStates(),
+        };
+    }
+    async function pollKnobs() {
+        try {
+            const res = await fetch('/__knob');
+            if (!res.ok)
+                return;
+            const drained = (await res.json());
+            if (!Array.isArray(drained) || drained.length === 0)
+                return;
+            for (const entry of drained) {
+                if (typeof entry.key !== 'string')
+                    continue;
+                // Resolve the posted (element, key) to one of our display keys, owned by
+                // that element. Accepts either an element-local key (the namespaced form
+                // the manifest advertises) or an already-namespaced key posted directly.
+                // For a single non-namespaced lab this reduces to the bare key, still
+                // filtered to the lab's element.
+                let disp = null;
+                if (entry.element) {
+                    const ns = nsKey(entry.element, entry.key, namespaced);
+                    if (knobBinding[ns]?.slot.name === entry.element)
+                        disp = ns;
+                }
+                if (!disp) {
+                    const b = knobBinding[entry.key];
+                    if (b && (!entry.element || b.slot.name === entry.element))
+                        disp = entry.key;
+                }
+                if (!disp)
+                    continue;
+                applyKnob(disp, entry.value, true);
+            }
+        }
+        catch (e) {
+            warnings.push('pollKnobs', 'knob poll failed', errDetail(e));
+        }
+    }
+    async function captureMotionFrames(cameraName, motionOpts = {}) {
+        const { frames: N = 6, dt: step = 0.25, mode = 'time' } = motionOpts;
+        const cam = cameras[cameraName];
+        if (!cam)
+            throw new Error(`unknown camera: ${cameraName}`);
+        // If captureSize is set, snap the canvas to that fixed size for the
+        // capture (and restore at the end) so framing is deterministic across
+        // page reloads / window resizes.
+        const liveW = renderer.domElement.width / renderer.getPixelRatio();
+        const liveH = renderer.domElement.height / renderer.getPixelRatio();
+        const w = opts.captureSize?.[0] ?? liveW;
+        const h = opts.captureSize?.[1] ?? liveH;
+        if (opts.captureSize)
+            renderer.setSize(w, h, false);
+        renderer.setScissorTest(false);
+        cam.aspect = w / Math.max(h, 1);
+        cam.updateProjectionMatrix();
+        const out = [];
+        if (mode === 'time') {
+            // Deterministic: pause the RAF, step time.value forward, render.
+            // CRITICAL: Three.js TSL's `time` node is `uniform(0).onRenderUpdate(
+            // (frame) => frame.time)` — it overwrites itself from renderer.nodeFrame
+            // on every render. So we must also override nodeFrame.time before each
+            // render or any shader using three/tsl's `time` will appear frozen.
+            const wasRunning = running;
+            running = false;
+            // Fully deterministic: always start the captured sequence at t=0 so
+            // two captures of the same element+shader produce byte-identical
+            // frames (no dependency on when captureMotionFrames was invoked).
+            const baseT = 0;
+            const baseDt = dt.value;
+            const liveTime = time.value;
+            const rendererAny = renderer;
+            const nf = rendererAny.nodeFrame ?? rendererAny._nodes?.nodeFrame ?? null;
+            const baseFrameT = nf?.time ?? 0;
+            const baseFrameDt = nf?.deltaTime ?? 0;
+            try {
+                for (let i = 0; i < N; i++) {
+                    const wantedT = baseT + i * step;
+                    time.value = wantedT;
+                    dt.value = step;
+                    if (nf) {
+                        nf.time = wantedT;
+                        nf.deltaTime = step;
+                    }
+                    renderer.setViewport(0, 0, w, h);
+                    renderer.clear();
+                    renderer.render(scene, cam);
+                    out.push(renderer.domElement.toDataURL('image/png'));
+                }
+            }
+            finally {
+                time.value = liveTime; // restore the live RAF-accumulated time
+                dt.value = baseDt;
+                if (nf) {
+                    nf.time = baseFrameT;
+                    nf.deltaTime = baseFrameDt;
+                }
+                running = wasRunning;
+                if (running) {
+                    lastT = performance.now();
+                    requestAnimationFrame(tick);
+                }
+            }
+        }
+        else {
+            // Real-time: keep RAF running, sample at wall-clock intervals.
+            const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+            for (let i = 0; i < N; i++) {
+                renderer.setViewport(0, 0, w, h);
+                renderer.setScissorTest(false);
+                renderer.clear();
+                renderer.render(scene, cam);
+                out.push(renderer.domElement.toDataURL('image/png'));
+                if (i < N - 1)
+                    await sleep(step * 1000);
+            }
+        }
+        resize();
+        return out;
+    }
+    async function captureViews() {
+        // Capture each camera as a separate full-canvas render to a base64 PNG.
+        // Side effect: per-camera built-in GPU probe stats (luminance, dynamic
+        // range) are computed by decoding the just-written canvas via 2D context
+        // and saved into `__TRISCOPE__.lastGpuProbes` so MCP can read them.
+        const out = {};
+        const probeStats = {};
+        const liveW = renderer.domElement.width / renderer.getPixelRatio();
+        const liveH = renderer.domElement.height / renderer.getPixelRatio();
+        const w = opts.captureSize?.[0] ?? liveW;
+        const h = opts.captureSize?.[1] ?? liveH;
+        if (opts.captureSize)
+            renderer.setSize(w, h, false);
+        for (const name of cameraOrder) {
+            renderer.setScissorTest(false);
+            renderer.setViewport(0, 0, w, h);
+            renderer.clear();
+            cameras[name].aspect = w / Math.max(h, 1);
+            cameras[name].updateProjectionMatrix();
+            renderer.render(scene, cameras[name]);
+            // The canvas now holds this camera's view. Read as data URL.
+            out[name] = renderer.domElement.toDataURL('image/png');
+            // Compute GPU probe stats from the same render. We sample 64×36 px
+            // (≈2300 samples) — enough for stable luminance percentiles without
+            // making toBlob+getImageData a per-camera bottleneck.
+            probeStats[name] = sampleGpuProbes(renderer.domElement);
+            // Flag panes the GPU drew black so a single dead camera surfaces as a
+            // warning + a per-camera flag instead of silently shipping a black PNG.
+            if (isBlackFrame(probeStats[name].luminance)) {
+                probeStats[name].blackFrame = true;
+                warnings.push('black-frame', `camera "${name}" rendered black (luminance ${probeStats[name].luminance})`);
+            }
+        }
+        if (typeof window !== 'undefined') {
+            window.__TRISCOPE__.lastGpuProbes = probeStats;
+        }
+        // Restore live canvas dimensions + per-camera aspect ratios.
+        resize();
+        return out;
+    }
+    function queryScene(maxNodes = 500) {
+        return serializeScene(scene, {
+            maxNodes,
+            getWorldPosition: (o) => {
+                try {
+                    const v = new THREE.Vector3();
+                    o.getWorldPosition(v);
+                    return [v.x, v.y, v.z];
+                }
+                catch {
+                    return [o.position?.x ?? 0, o.position?.y ?? 0, o.position?.z ?? 0];
+                }
+            },
+        });
+    }
+    function readUniform(path) {
+        return readUniformValue(scene, path);
+    }
+    function setUniform(path, value) {
+        return writeUniformValue(scene, path, value);
+    }
+    // ---- SDL: live scene mutation (camera repoint + knob override) ----------
+    function applySceneDelta(delta) {
+        if (delta?.cameras) {
+            for (const [name, cd] of Object.entries(delta.cameras))
+                applyCameraDelta(cameras[name], cd);
+        }
+        if (delta?.knobs) {
+            for (const [key, value] of Object.entries(delta.knobs)) {
+                applyKnob(key, value, true);
+            }
+        }
+        if (delta?.elements) {
+            for (const [name, e] of Object.entries(delta.elements)) {
+                if (typeof e?.enabled !== 'boolean')
+                    continue;
+                // Toggle whichever slot owns `name` — either a slot whose element name
+                // matches, or a composeElements child within a single-element lab.
+                for (const slot of slots) {
+                    if (applyElementToggle(slot.handle, { name: slot.name }, name, e.enabled))
+                        break;
+                }
+            }
+        }
+    }
+    function sceneElementStates() {
+        const out = {};
+        for (const slot of slots) {
+            const childMap = slot.handle.userData
+                ?.childrenByName;
+            if (childMap && Object.keys(childMap).length > 0) {
+                // Composed element: report its children (the D4 show/hide slice).
+                for (const [n, h] of Object.entries(childMap)) {
+                    out[n] = { enabled: h.root?.visible !== false };
+                }
+            }
+            else {
+                out[slot.name] = { enabled: slot.handle.root?.visible !== false };
+            }
+        }
+        return out;
+    }
+    function getScene() {
+        return {
+            cameras: Object.fromEntries(cameraOrder.map((n) => [
+                n,
+                {
+                    position: cameras[n].position.toArray(),
+                    target: targetOf(cameras[n]),
+                    fov: cameras[n].fov,
+                },
+            ])),
+            knobs: { ...knobValues },
+            elements: sceneElementStates(),
+        };
+    }
+    function setSceneParam(delta) {
+        applySceneDelta(delta);
+        // Persist so the delta survives a full reload (like knobs do).
+        postScene(delta).catch((e) => warnings.push('postScene', 'POST /__scene failed', errDetail(e)));
+        return getScene();
+    }
+    async function pollScene() {
+        try {
+            const res = await fetch('/__scene');
+            if (!res.ok)
+                return;
+            const drained = (await res.json());
+            if (!Array.isArray(drained) || drained.length === 0)
+                return;
+            for (const delta of drained)
+                applySceneDelta(delta);
+        }
+        catch (e) {
+            warnings.push('pollScene', 'scene poll failed', errDetail(e));
+        }
+    }
+    // Re-hydrate any persisted scene deltas from a previous session.
+    try {
+        const r = await fetch('/__scene/current');
+        if (r.ok)
+            applySceneDelta(await r.json());
+    }
+    catch {
+        /* dev server transient — fall through */
+    }
+    // ---- Runtime element add/remove (runSceneLab) ---------------------------
+    // Mount a registered-but-unmounted element live: instantiate it, register its
+    // namespaced cameras/knobs, then rebuild the grid (labels + editor + aspect)
+    // and re-advertise it via the manifest. No-op (returns false) if it's already
+    // mounted or not in the registry; a mount throw is contained as a warning.
+    function addElement(name) {
+        const entry = entries.find((e) => e.name === name);
+        if (!entry) {
+            warnings.push('add-element', `unknown element "${name}" (not in scene registry)`);
+            return false;
+        }
+        let slot;
+        try {
+            slot = mountSlot(entry.name, entry.element);
+            if (!slot)
+                return false; // already mounted
+            // Rebuild the grid + inspect for the new slot. Wrapped with mountSlot so a
+            // throw anywhere rolls the slot back rather than leaving a half-integrated
+            // (rendered-but-unlabelled) zombie in cameraOrder.
+            rebuildLabels();
+            rebuildEditor();
+            resize();
+            setupInspect();
+            postManifestFor(slot);
+        }
+        catch (e) {
+            warnings.push('add-element', `add of "${name}" failed`, errDetail(e));
+            if (slots.some((s) => s.name === name))
+                unmountSlot(name); // roll back
+            return false;
+        }
+        return true;
+    }
+    // Dispose a mounted element live + rebuild the grid. Returns false if it
+    // wasn't mounted. The element stays in the registry and can be re-added.
+    // Guard: never empty a single-element runLab — removing the only element of a
+    // non-namespaced lab is almost certainly a mistargeted call, so it's a no-op.
+    function removeElement(name) {
+        if (!namespaced && slots.length <= 1)
+            return false;
+        if (!unmountSlot(name))
+            return false;
+        rebuildLabels();
+        rebuildEditor();
+        resize();
+        setupInspect();
+        return true;
+    }
+    if (bootOverlay)
+        bootOverlay.remove();
+    window.__TRISCOPE__ = {
+        // Primary slot, kept live as slots change — back-compat for single-element
+        // consumers (the MCP pool reads `.element?.name`).
+        get element() {
+            return slots[0]?.element;
+        },
+        get handle() {
+            return slots[0]?.handle;
+        },
+        renderer,
+        scene,
+        cameras,
+        knobValues,
+        setKnob: (k, v) => applyKnob(k, v, true),
+        sampleTelemetry: buildState,
+        captureViews,
+        captureMotionFrames,
+        queryScene,
+        readUniform,
+        setUniform,
+        setSceneParam,
+        getScene,
+        addElement,
+        removeElement,
+        availableElements: () => entries.map((e) => e.name),
+        mountedElements: () => slots.map((s) => s.name),
+        // Monotonic rendered-frame count — the MCP pool polls this to wait for a
+        // real rendered frame before capturing (avoids black/pre-render captures).
+        framesRendered: () => framesRendered,
+    };
+    // Live view of the warning ring (snapshot per access) for in-page scripts.
+    Object.defineProperty(window.__TRISCOPE__, 'warnings', {
+        get: () => warnings.list(),
+        enumerable: true,
+        configurable: true,
+    });
+    requestAnimationFrame(tick);
+    return {
+        get element() {
+            return slots[0]?.element;
+        },
+        setKnob: (k, v) => applyKnob(k, v, true),
+        captureViews,
+        addElement,
+        removeElement,
+        availableElements: () => entries.map((e) => e.name),
+        mountedElements: () => slots.map((s) => s.name),
+        stop: () => {
+            running = false;
+            window.removeEventListener('resize', resize);
+            for (const slot of slots) {
+                try {
+                    slot.handle.dispose();
+                }
+                catch {
+                    /* best-effort teardown */
+                }
+            }
+            renderer.dispose();
+        },
+    };
+}
+const PROBE_SAMPLE_W = 64;
+const PROBE_SAMPLE_H = 36;
+let probeSampler = null;
+function sampleGpuProbes(srcCanvas) {
+    // Reuse a single 64×36 2D scratch canvas so we don't allocate per frame.
+    if (!probeSampler) {
+        const c = document.createElement('canvas');
+        c.width = PROBE_SAMPLE_W;
+        c.height = PROBE_SAMPLE_H;
+        probeSampler = { canvas: c, ctx: c.getContext('2d', { willReadFrequently: true }) };
+    }
+    const { canvas: sc, ctx } = probeSampler;
+    ctx.clearRect(0, 0, sc.width, sc.height);
+    // drawImage scales the WebGPU canvas down to our sample size in one call.
+    ctx.drawImage(srcCanvas, 0, 0, sc.width, sc.height);
+    const data = ctx.getImageData(0, 0, sc.width, sc.height).data;
+    const n = sc.width * sc.height;
+    const lums = new Float32Array(n);
+    let sum = 0;
+    for (let i = 0; i < n; i++) {
+        const r = data[i * 4] / 255;
+        const g = data[i * 4 + 1] / 255;
+        const b = data[i * 4 + 2] / 255;
+        // Rec.709 luminance.
+        const lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+        lums[i] = lum;
+        sum += lum;
+    }
+    const sorted = Array.from(lums).sort((a, b) => a - b);
+    const p5 = sorted[Math.floor(n * 0.05)];
+    const p95 = sorted[Math.floor(n * 0.95)];
+    const luminance = sum / n;
+    const dynamicRange = p95 / Math.max(p5, 1 / 255);
+    return {
+        luminance: +luminance.toFixed(4),
+        p5: +p5.toFixed(4),
+        p95: +p95.toFixed(4),
+        dynamicRange: +dynamicRange.toFixed(2),
+        samples: n,
+    };
+}
+export function makeCamera(spec, bounds) {
+    const cam = new THREE.PerspectiveCamera(spec.fov ?? 45, 1, spec.near ?? 0.1, spec.far ?? 2000);
+    cam.position.set(...spec.position);
+    cam.lookAt(...spec.target);
+    cam.userData.target = [...spec.target];
+    if (spec.fit && bounds) {
+        fitCameraToBounds(cam, spec, bounds);
+    }
+    return cam;
+}
+export function fitCameraToBounds(cam, spec, bounds) {
+    const min = new THREE.Vector3(...bounds.min);
+    const max = new THREE.Vector3(...bounds.max);
+    const center = min.clone().add(max).multiplyScalar(0.5);
+    const size = max.clone().sub(min).length();
+    const target = new THREE.Vector3(...spec.target);
+    const fovRad = (cam.fov * Math.PI) / 180;
+    const distance = size / (2 * Math.tan(fovRad / 2));
+    const dir = cam.position.clone().sub(target).normalize();
+    cam.position.copy(center.clone().add(dir.multiplyScalar(distance * 1.2)));
+    cam.lookAt(center);
+    cam.userData.target = [center.x, center.y, center.z];
+}
+function targetOf(cam) {
+    const t = cam.userData?.target;
+    if (Array.isArray(t) && t.length === 3)
+        return [t[0], t[1], t[2]];
+    const fallback = new THREE.Vector3(0, 0, -1).applyQuaternion(cam.quaternion).add(cam.position);
+    return [fallback.x, fallback.y, fallback.z];
+}
+async function postState(payload) {
+    await fetch('/__state', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(payload),
+    });
+}
+async function postManifest(payload) {
+    await fetch('/__manifest', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(payload),
+    });
+}
+async function postScene(payload) {
+    await fetch('/__scene', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(payload),
+    });
+}
+function errDetail(e) {
+    const msg = e?.message ?? e;
+    return String(msg).slice(0, 300);
+}
+//# sourceMappingURL=harness.js.map