@triscope/core 0.4.0

package/dist/inspect.js

@@ -0,0 +1,434 @@
+/**
+ * Inspect mode: solo-view + OrbitControls + raycaster picking + hover
+ * highlight + click-to-select. Writes selection into
+ * window.__TRISCOPE__.lastSelection so MCP read_telemetry .selection
+ * surfaces the source frame for the picked mesh.
+ *
+ * Activation: URL `?inspect=<element>&camera=<name>` (camera optional, falls
+ * back to the first declared camera). When inactive the harness behaves
+ * exactly as before — the grid view.
+ *
+ * Highlight is a single shared wireframe Mesh that borrows the hovered
+ * object's geometry (no per-frame allocation). Click-selection persists
+ * the same overlay with a different color until the next click.
+ */
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import * as THREE from 'three/webgpu';
+export function buildParentChain(obj) {
+    const chain = [];
+    let cur = obj;
+    while (cur) {
+        chain.unshift(describeObj(cur));
+        cur = cur.parent ?? null;
+    }
+    return chain;
+}
+/**
+ * Compact human-readable description of an Object3D used in parentChain
+ * and clipboard formats. Prefers the author's `.name` (most specific);
+ * falls back to a self-describing shorthand like `Mesh<PlaneGeometry
+ * #e6dcc0>` so the user can still grep — even when no names are set on
+ * the scene tree.
+ */
+export function describeObj(obj) {
+    if (obj.name)
+        return obj.name;
+    const ctor = obj.constructor?.name ?? '?';
+    const mesh = obj;
+    const geom = mesh.geometry?.type;
+    let color;
+    try {
+        const mat = mesh.material;
+        if (mat?.color?.getHexString)
+            color = '#' + mat.color.getHexString();
+    }
+    catch {
+        /* color extraction is best-effort */
+    }
+    if (geom || color) {
+        const parts = [geom, color].filter(Boolean).join(' ');
+        return `${ctor}<${parts}>`;
+    }
+    return ctor;
+}
+/**
+ * Walk the scene tree and return the first Mesh whose source tag matches
+ * the given frame (same file + line). Used by inspect-mode persistence to
+ * restore the selection across full-reload — the Mesh object identity
+ * changes after reload but the source location is stable.
+ */
+export function findMeshBySource(scene, source) {
+    if (!source?.file)
+        return null;
+    let match = null;
+    scene.traverse?.((obj) => {
+        if (match)
+            return;
+        const tag = obj.userData?.__tris;
+        if (!tag?.source)
+            return;
+        if (tag.source.file === source.file && tag.source.line === source.line) {
+            match = obj;
+        }
+    });
+    return match;
+}
+/** Parse the URL for inspect activation. Returns null when off. */
+export function readInspectFromUrl(elementName) {
+    if (typeof window === 'undefined')
+        return null;
+    const params = new URLSearchParams(window.location.search);
+    const inspectParam = params.get('inspect');
+    if (inspectParam == null)
+        return null;
+    // `?inspect`, `?inspect=1`, `?inspect=<el>` all activate.
+    // `?inspect=<el>` activates only when the el matches our element.
+    if (inspectParam === '' || inspectParam === '1' || inspectParam === elementName) {
+        return { camera: params.get('camera') ?? undefined };
+    }
+    return null;
+}
+export function createInspectMode(init) {
+    const cameraName = init.cameraName ?? Object.keys(init.cameras)[0];
+    const camera = init.cameras[cameraName];
+    if (!camera) {
+        return {
+            active: false,
+            cameraName: null,
+            camera: null,
+            render: () => { },
+            state: () => ({ hover: null, selection: null, selections: [] }),
+            dispose: () => { },
+        };
+    }
+    // OrbitControls — right-button rotates per user request, left-button is
+    // reserved for picking (we wire click → raycast below). Scroll zooms.
+    const controls = new OrbitControls(camera, init.canvas);
+    controls.enablePan = true;
+    controls.enableDamping = true;
+    controls.dampingFactor = 0.08;
+    controls.mouseButtons = {
+        LEFT: null, // we handle left clicks for picking
+        MIDDLE: THREE.MOUSE.PAN,
+        RIGHT: THREE.MOUSE.ROTATE,
+    };
+    // OrbitControls' target defaults to (0,0,0); use the camera's declared target.
+    const t = camera.userData?.target;
+    if (Array.isArray(t) && t.length === 3)
+        controls.target.set(t[0], t[1], t[2]);
+    controls.update();
+    // Highlight overlay: one wireframe mesh whose geometry is swapped to
+    // match the hovered/selected mesh. Bright green for hover, bright cyan
+    // for the persistent click-selection. `raycast` is a no-op so the
+    // overlay never grabs subsequent picks.
+    const hoverMat = new THREE.MeshBasicNodeMaterial({
+        color: 0x66ff66,
+        wireframe: true,
+        transparent: true,
+        opacity: 0.9,
+        depthTest: false,
+    });
+    const selectMat = new THREE.MeshBasicNodeMaterial({
+        color: 0x00ffff,
+        wireframe: true,
+        transparent: true,
+        opacity: 0.95,
+        depthTest: false,
+    });
+    const overlay = new THREE.Mesh(new THREE.BufferGeometry(), hoverMat);
+    overlay.renderOrder = 999;
+    overlay.frustumCulled = false;
+    overlay.visible = false;
+    overlay.raycast = () => { }; // ignore in picking
+    init.scene.add(overlay);
+    const selectOverlay = new THREE.Mesh(new THREE.BufferGeometry(), selectMat);
+    selectOverlay.renderOrder = 1000;
+    selectOverlay.frustumCulled = false;
+    selectOverlay.visible = false;
+    selectOverlay.raycast = () => { };
+    init.scene.add(selectOverlay);
+    const raycaster = new THREE.Raycaster();
+    const ndc = new THREE.Vector2();
+    let hoverHit = null;
+    let selectionHit = null;
+    let hoveredObject = null;
+    let selectedObject = null;
+    // Pending restore-poller handle (a chain of setTimeouts) + a disposed guard so
+    // dispose() can cancel it — otherwise it keeps writing selection state (and an
+    // overlay borrowing now-freed geometry) for up to ~3s after teardown.
+    let restoreTimer = null;
+    let disposed = false;
+    // Multi-select state. selectionsByUuid maps uuid → selection. extraOverlays
+    // maps uuid → its wireframe overlay Mesh (the primary cyan overlay is
+    // reserved for the most-recently-clicked item, kept in sync with
+    // selectedObject). Built up via Shift+click; plain click resets.
+    const selectionsByUuid = new Map();
+    const extraOverlaysByUuid = new Map();
+    const extraOverlayMat = new THREE.MeshBasicNodeMaterial({
+        color: 0x00ccff,
+        wireframe: true,
+        transparent: true,
+        opacity: 0.75,
+        depthTest: false,
+    });
+    function eventToNdc(ev) {
+        const rect = init.canvas.getBoundingClientRect();
+        ndc.x = ((ev.clientX - rect.left) / rect.width) * 2 - 1;
+        ndc.y = -((ev.clientY - rect.top) / rect.height) * 2 + 1;
+    }
+    function pick() {
+        raycaster.setFromCamera(ndc, camera);
+        const hits = raycaster.intersectObjects(init.scene.children, true);
+        // Filter out overlays + lights + non-mesh helpers.
+        for (const h of hits) {
+            if (h.object === overlay || h.object === selectOverlay)
+                continue;
+            if (!h.object.isMesh)
+                continue;
+            return { obj: h.object, distance: h.distance, point: h.point };
+        }
+        return null;
+    }
+    function selectionFrom(hit) {
+        const tag = hit.obj.userData?.__tris ?? null;
+        return {
+            camera: cameraName,
+            point: [hit.point.x, hit.point.y, hit.point.z],
+            distance: +hit.distance.toFixed(3),
+            source: tag?.source ?? null,
+            stack: tag?.stack ?? [],
+            type: tag?.type ?? hit.obj.constructor.name,
+            geometry: tag?.geometry,
+            material: tag?.material,
+            name: tag?.name ?? hit.obj.name ?? undefined,
+            parentChain: buildParentChain(hit.obj),
+            uuid: hit.obj.uuid,
+        };
+    }
+    function syncOverlayTo(target, which) {
+        which.geometry = target.geometry;
+        target.updateMatrixWorld(true);
+        which.matrix.copy(target.matrixWorld);
+        which.matrixAutoUpdate = false;
+        which.visible = true;
+    }
+    // mousemove → hover (RAF-throttled so we don't raycast 1000x/s).
+    let pendingHover = false;
+    function onMouseMove(ev) {
+        eventToNdc(ev);
+        if (pendingHover)
+            return;
+        pendingHover = true;
+        requestAnimationFrame(() => {
+            pendingHover = false;
+            const hit = pick();
+            if (!hit) {
+                if (hoveredObject) {
+                    hoveredObject = null;
+                    hoverHit = null;
+                    overlay.visible = false;
+                }
+                return;
+            }
+            if (hit.obj === hoveredObject)
+                return;
+            hoveredObject = hit.obj;
+            hoverHit = selectionFrom(hit);
+            syncOverlayTo(hit.obj, overlay);
+        });
+    }
+    function clearMultiOverlays() {
+        for (const ov of extraOverlaysByUuid.values())
+            init.scene.remove(ov);
+        extraOverlaysByUuid.clear();
+        selectionsByUuid.clear();
+    }
+    function ensureMultiOverlay(uuid, target) {
+        if (extraOverlaysByUuid.has(uuid)) {
+            // Already overlaid; just re-sync transform in case the mesh moved.
+            syncOverlayTo(target, extraOverlaysByUuid.get(uuid));
+            return;
+        }
+        const ov = new THREE.Mesh(new THREE.BufferGeometry(), extraOverlayMat);
+        ov.renderOrder = 1000;
+        ov.frustumCulled = false;
+        ov.raycast = () => { };
+        init.scene.add(ov);
+        extraOverlaysByUuid.set(uuid, ov);
+        syncOverlayTo(target, ov);
+    }
+    /**
+     * Best-effort clipboard write — silently ignores rejections on browsers
+     * that gate navigator.clipboard behind a user-activation check (it's
+     * fine here because we're called from a click event handler).
+     *
+     * Format is rich enough to grep with when source.line drifts (which it
+     * does, because Error.stack in browsers reports positions in the
+     * vite-served file, not source-mapped originals). Example output:
+     *   PirateShipMesh.ts:1599 — Mesh<PlaneGeometry #e6dcc0> @ (4.2,8.1,0.3) chain=Scene>pirate.ship>mainmast>Mesh<PlaneGeometry #e6dcc0>
+     * The user can paste this into chat or `rg` and find the real call
+     * site even if the line number is off by 100 lines.
+     */
+    function copySelection(sel) {
+        const src = sel.source;
+        const fileLine = src ? `${src.file.split('/').slice(-1)[0]}:${src.line}` : `(uuid=${sel.uuid})`;
+        const desc = sel.name ?? `${sel.type}<${[sel.geometry, sel.material?.color].filter(Boolean).join(' ')}>`;
+        const pos = `(${sel.point.map((n) => n.toFixed(2)).join(',')})`;
+        const chain = sel.parentChain?.length ? ` chain=${sel.parentChain.join('>')}` : '';
+        const text = `${fileLine} — ${desc} @ ${pos}${chain}`;
+        try {
+            navigator.clipboard?.writeText(text);
+        }
+        catch { }
+    }
+    function onMouseDown(ev) {
+        if (ev.button !== 0)
+            return; // left only
+        eventToNdc(ev);
+        const hit = pick();
+        if (!hit) {
+            // Plain background click clears everything; Shift+background keeps
+            // the current multi-set so the user can de-target a stray click.
+            if (!ev.shiftKey) {
+                selectionHit = null;
+                selectedObject = null;
+                selectOverlay.visible = false;
+                clearMultiOverlays();
+                init.onSelectionChange(null, []);
+                try {
+                    window.localStorage.removeItem(STORAGE_KEY);
+                }
+                catch { }
+            }
+            return;
+        }
+        const sel = selectionFrom(hit);
+        if (!ev.shiftKey) {
+            // Plain click: replace set with this one item.
+            clearMultiOverlays();
+        }
+        else if (selectedObject && selectionHit) {
+            // Shift+click on a NEW mesh: the previous "primary" is about to lose
+            // the primary overlay (which will swap to the new mesh). Give the
+            // old primary its own multi-overlay so it stays visible. Without
+            // this the user sees only the latest pick, not the accumulated set.
+            ensureMultiOverlay(selectionHit.uuid, selectedObject);
+        }
+        selectedObject = hit.obj;
+        selectionHit = sel;
+        syncOverlayTo(hit.obj, selectOverlay);
+        selectionsByUuid.set(sel.uuid, sel);
+        init.onSelectionChange(sel, [...selectionsByUuid.values()]);
+        copySelection(sel);
+        try {
+            window.localStorage.setItem(STORAGE_KEY, JSON.stringify(sel));
+        }
+        catch { }
+    }
+    init.canvas.addEventListener('mousemove', onMouseMove);
+    init.canvas.addEventListener('mousedown', onMouseDown);
+    // Restore last selection across full-reload (vite force-reload on
+    // shader edits). Match by source frame (file:line) — the actual Mesh
+    // object is new after reload but the source location is stable.
+    //
+    // Element mounting may happen across many frames (TSL pipeline init,
+    // async texture loads, RAF-driven sub-mesh adds). Poll up to ~3 s
+    // looking for the stored source in the scene tree, so we don't give
+    // up before the element has finished assembling itself.
+    const STORAGE_KEY = `triscope:selection:${init.elementName}`;
+    try {
+        const raw = window.localStorage.getItem(STORAGE_KEY);
+        if (raw) {
+            const stored = JSON.parse(raw);
+            let attempts = 0;
+            const maxAttempts = 30; // 30 × 100ms ≈ 3s
+            const tryRestore = () => {
+                if (disposed)
+                    return;
+                attempts += 1;
+                try {
+                    const target = findMeshBySource(init.scene, stored.source);
+                    if (target) {
+                        selectedObject = target;
+                        selectionHit = selectionFrom({
+                            obj: target,
+                            distance: stored.distance,
+                            point: new THREE.Vector3(...stored.point),
+                        });
+                        syncOverlayTo(target, selectOverlay);
+                        selectionsByUuid.set(selectionHit.uuid, selectionHit);
+                        init.onSelectionChange(selectionHit, [...selectionsByUuid.values()]);
+                        return;
+                    }
+                }
+                catch {
+                    /* corrupt stored selection — drop it */
+                    try {
+                        window.localStorage.removeItem(STORAGE_KEY);
+                    }
+                    catch { }
+                    return;
+                }
+                if (attempts < maxAttempts)
+                    restoreTimer = setTimeout(tryRestore, 100);
+            };
+            restoreTimer = setTimeout(tryRestore, 100);
+        }
+    }
+    catch {
+        /* localStorage unavailable — silent */
+    }
+    function render() {
+        controls.update();
+        // Keep overlays glued to their target's current world matrix in case
+        // the underlying mesh moved (animation, knob change).
+        if (selectedObject && selectionHit) {
+            selectedObject.updateMatrixWorld(true);
+            selectOverlay.matrix.copy(selectedObject.matrixWorld);
+        }
+        if (hoveredObject) {
+            hoveredObject.updateMatrixWorld(true);
+            overlay.matrix.copy(hoveredObject.matrixWorld);
+        }
+        init.renderer.setScissorTest(false);
+        const w = init.renderer.domElement.width / init.renderer.getPixelRatio();
+        const h = init.renderer.domElement.height / init.renderer.getPixelRatio();
+        init.renderer.setViewport(0, 0, w, h);
+        camera.aspect = w / Math.max(h, 1);
+        camera.updateProjectionMatrix();
+        init.renderer.clear();
+        init.renderer.render(init.scene, camera);
+    }
+    function dispose() {
+        disposed = true;
+        if (restoreTimer) {
+            clearTimeout(restoreTimer);
+            restoreTimer = null;
+        }
+        init.canvas.removeEventListener('mousemove', onMouseMove);
+        init.canvas.removeEventListener('mousedown', onMouseDown);
+        // Remove every overlay from the shared scene + drop the borrowed geometry
+        // references so a disposed element's freed BufferGeometry can be GC'd.
+        init.scene.remove(overlay);
+        init.scene.remove(selectOverlay);
+        overlay.geometry = new THREE.BufferGeometry();
+        selectOverlay.geometry = new THREE.BufferGeometry();
+        clearMultiOverlays();
+        hoveredObject = null;
+        selectedObject = null;
+        controls.dispose();
+    }
+    return {
+        active: true,
+        cameraName,
+        camera,
+        render,
+        state: () => ({
+            hover: hoverHit,
+            selection: selectionHit,
+            selections: [...selectionsByUuid.values()],
+        }),
+        dispose,
+    };
+}
+//# sourceMappingURL=inspect.js.map

package/dist/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","sourceRoot":"","sources":["../src/inspect.ts"],"names":[],"mappings":"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"}

package/dist/knob-utils.d.ts

@@ -0,0 +1,22 @@
+import type { Knob } from './types.js';
+/** Result of clamping a candidate knob value against its spec. */
+export interface ClampResult {
+    /** True when the final value differs from what the caller asked for. */
+    clamped: boolean;
+    /** The value actually safe to apply. */
+    final: number | string | boolean;
+}
+/**
+ * Coerce + clamp a candidate knob value to what its spec actually allows, so a
+ * stray `set_knob('windPressure', 9999)` can't silently corrupt the scene.
+ * Returns both the safe `final` value and whether it had to be changed, so the
+ * caller (harness / MCP) can tell the agent its input was out of range.
+ *
+ *   number  → coerce to finite, snap to `step` (if any), clamp to [min, max]
+ *   int     → coerce, round, clamp to [min, max]
+ *   color   → keep valid #rgb / #rrggbb, else fall back to the spec default
+ *   boolean → coerce truthiness
+ *   trigger → pass the pulse through untouched (no persisted value)
+ */
+export declare function clampKnob(spec: Knob, value: number | string | boolean): ClampResult;
+//# sourceMappingURL=knob-utils.d.ts.map

package/dist/knob-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knob-utils.d.ts","sourceRoot":"","sources":["../src/knob-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAClC;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,WAAW,CA+BnF"}

package/dist/knob-utils.js

@@ -0,0 +1,51 @@
+const HEX_COLOR = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+/**
+ * Coerce + clamp a candidate knob value to what its spec actually allows, so a
+ * stray `set_knob('windPressure', 9999)` can't silently corrupt the scene.
+ * Returns both the safe `final` value and whether it had to be changed, so the
+ * caller (harness / MCP) can tell the agent its input was out of range.
+ *
+ *   number  → coerce to finite, snap to `step` (if any), clamp to [min, max]
+ *   int     → coerce, round, clamp to [min, max]
+ *   color   → keep valid #rgb / #rrggbb, else fall back to the spec default
+ *   boolean → coerce truthiness
+ *   trigger → pass the pulse through untouched (no persisted value)
+ */
+export function clampKnob(spec, value) {
+    switch (spec.type) {
+        case 'number': {
+            const n = Number(value);
+            if (!Number.isFinite(n))
+                return { clamped: true, final: spec.default };
+            let next = n;
+            if (spec.step && spec.step > 0) {
+                next = spec.min + Math.round((next - spec.min) / spec.step) * spec.step;
+            }
+            next = Math.min(spec.max, Math.max(spec.min, next));
+            return { clamped: !nearlyEqual(next, n), final: next };
+        }
+        case 'int': {
+            const n = Number(value);
+            if (!Number.isFinite(n))
+                return { clamped: true, final: spec.default };
+            const next = Math.min(spec.max, Math.max(spec.min, Math.round(n)));
+            return { clamped: next !== n, final: next };
+        }
+        case 'color': {
+            if (typeof value === 'string' && HEX_COLOR.test(value)) {
+                return { clamped: false, final: value };
+            }
+            return { clamped: true, final: spec.default };
+        }
+        case 'boolean': {
+            const next = Boolean(value);
+            return { clamped: typeof value !== 'boolean', final: next };
+        }
+        case 'trigger':
+            return { clamped: false, final: value };
+    }
+}
+function nearlyEqual(a, b) {
+    return Math.abs(a - b) < 1e-9;
+}
+//# sourceMappingURL=knob-utils.js.map

package/dist/knob-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knob-utils.js","sourceRoot":"","sources":["../src/knob-utils.ts"],"names":[],"mappings":"AAUA,MAAM,SAAS,GAAG,sCAAsC,CAAC;AAEzD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,IAAU,EAAE,KAAgC;IACpE,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;YACvE,IAAI,IAAI,GAAG,CAAC,CAAC;YACb,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;gBAC/B,IAAI,GAAG,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC;YAC1E,CAAC;YACD,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;YACpD,OAAO,EAAE,OAAO,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACzD,CAAC;QACD,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;YACvE,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACnE,OAAO,EAAE,OAAO,EAAE,IAAI,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAC9C,CAAC;QACD,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACvD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;YAC1C,CAAC;YACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QAChD,CAAC;QACD,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;YAC5B,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,KAAK,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAC9D,CAAC;QACD,KAAK,SAAS;YACZ,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC5C,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,CAAS,EAAE,CAAS;IACvC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC;AAChC,CAAC"}

package/dist/lab/css.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Lab UI CSS, exported as a template string so consumers can inject it
+ * once via `mountLabDom()` instead of duplicating it in every per-element
+ * lab HTML page.
+ *
+ * Covers: full-bleed canvas, camera-label tags, HUD strip, boot overlay,
+ * knob-editor pane. The selectors match the DOM that `mountLabDom()`
+ * creates and that `runLab()` / `mountEditor()` populate.
+ */
+export declare const LAB_CSS = "\nhtml, body { margin: 0; padding: 0; overflow: hidden; background: #000; color: #cfd6db; font-family: ui-monospace, monospace; }\n#app { position: fixed; inset: 0; }\ncanvas { display: block; width: 100%; height: 100%; }\n\n.triscope-label, .label {\n  position: absolute;\n  background: rgba(0,0,0,0.55);\n  color: #cfd6db;\n  padding: 4px 8px;\n  font-size: 11px;\n  font-weight: 600;\n  letter-spacing: 0.05em;\n  pointer-events: none;\n  border-radius: 3px;\n  z-index: 5;\n}\n\n#hud { position: fixed; bottom: 8px; left: 8px; z-index: 10; font-size: 11px; padding: 4px 8px; background: rgba(0,0,0,0.55); border-radius: 3px; }\n#boot { position: fixed; inset: 0; display: flex; align-items: center; justify-content: center; background: #0a1a20; color: #cfd6db; font-size: 14px; z-index: 50; }\n\n#lab-controls {\n  position: fixed;\n  right: 8px;\n  bottom: 8px;\n  z-index: 20;\n  width: min(320px, calc(100vw - 24px));\n  padding: 10px 12px;\n  background: rgba(5, 12, 16, 0.78);\n  border: 1px solid rgba(210, 230, 240, 0.16);\n  border-radius: 6px;\n  backdrop-filter: blur(8px);\n  box-sizing: border-box;\n}\n.triscope-editor__row {\n  display: grid;\n  grid-template-columns: 110px 1fr 56px;\n  align-items: center;\n  gap: 6px;\n  font-size: 11px;\n  color: #cfd6db;\n  margin: 4px 0;\n}\n.triscope-editor__row label { font-size: 10px; opacity: 0.85; }\n.triscope-editor__row input { width: 100%; accent-color: #8fc7d9; }\n.triscope-editor__row output { text-align: right; color: #f0f5f7; }\n";
+//# sourceMappingURL=css.d.ts.map

package/dist/lab/css.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"css.d.ts","sourceRoot":"","sources":["../../src/lab/css.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,s+CA8CnB,CAAC"}

package/dist/lab/css.js

@@ -0,0 +1,57 @@
+/**
+ * Lab UI CSS, exported as a template string so consumers can inject it
+ * once via `mountLabDom()` instead of duplicating it in every per-element
+ * lab HTML page.
+ *
+ * Covers: full-bleed canvas, camera-label tags, HUD strip, boot overlay,
+ * knob-editor pane. The selectors match the DOM that `mountLabDom()`
+ * creates and that `runLab()` / `mountEditor()` populate.
+ */
+export const LAB_CSS = `
+html, body { margin: 0; padding: 0; overflow: hidden; background: #000; color: #cfd6db; font-family: ui-monospace, monospace; }
+#app { position: fixed; inset: 0; }
+canvas { display: block; width: 100%; height: 100%; }
+
+.triscope-label, .label {
+  position: absolute;
+  background: rgba(0,0,0,0.55);
+  color: #cfd6db;
+  padding: 4px 8px;
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.05em;
+  pointer-events: none;
+  border-radius: 3px;
+  z-index: 5;
+}
+
+#hud { position: fixed; bottom: 8px; left: 8px; z-index: 10; font-size: 11px; padding: 4px 8px; background: rgba(0,0,0,0.55); border-radius: 3px; }
+#boot { position: fixed; inset: 0; display: flex; align-items: center; justify-content: center; background: #0a1a20; color: #cfd6db; font-size: 14px; z-index: 50; }
+
+#lab-controls {
+  position: fixed;
+  right: 8px;
+  bottom: 8px;
+  z-index: 20;
+  width: min(320px, calc(100vw - 24px));
+  padding: 10px 12px;
+  background: rgba(5, 12, 16, 0.78);
+  border: 1px solid rgba(210, 230, 240, 0.16);
+  border-radius: 6px;
+  backdrop-filter: blur(8px);
+  box-sizing: border-box;
+}
+.triscope-editor__row {
+  display: grid;
+  grid-template-columns: 110px 1fr 56px;
+  align-items: center;
+  gap: 6px;
+  font-size: 11px;
+  color: #cfd6db;
+  margin: 4px 0;
+}
+.triscope-editor__row label { font-size: 10px; opacity: 0.85; }
+.triscope-editor__row input { width: 100%; accent-color: #8fc7d9; }
+.triscope-editor__row output { text-align: right; color: #f0f5f7; }
+`;
+//# sourceMappingURL=css.js.map

package/dist/lab/css.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"css.js","sourceRoot":"","sources":["../../src/lab/css.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CtB,CAAC"}

package/dist/lab/dom.d.ts

@@ -0,0 +1,13 @@
+export interface LabDomRefs {
+    canvas: HTMLCanvasElement;
+    hud: HTMLElement;
+    boot: HTMLElement;
+    labelContainer: HTMLElement;
+    editorContainer: HTMLElement;
+}
+/**
+ * Build (or reuse) the standard lab DOM and return the refs `runLab()`
+ * needs. Idempotent: calling twice does not duplicate nodes.
+ */
+export declare function mountLabDom(): LabDomRefs;
+//# sourceMappingURL=dom.d.ts.map

package/dist/lab/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/lab/dom.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,GAAG,EAAE,WAAW,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,cAAc,EAAE,WAAW,CAAC;IAC5B,eAAe,EAAE,WAAW,CAAC;CAC9B;AAsBD;;;GAGG;AACH,wBAAgB,WAAW,IAAI,UAAU,CAiCxC"}