@triscope/core 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 triscope contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @triscope/core
+
+The triscope lab runtime. Wraps a Three.js + WebGPU scene in a small **Element**
+contract and boots a deterministic, machine-inspectable "lab" page that the
+[`@triscope/mcp`](https://www.npmjs.com/package/@triscope/mcp) tools (and a human)
+can observe and tune live.
+
+```ts
+import { runLab, runSceneLab, runSceneView } from '@triscope/core';
+
+// Single element:
+runLab(myElement);
+
+// A scene of N namespaced elements (runtime add/remove):
+runSceneLab({ elements: [ship, sea, sky] });
+
+// Zero-boilerplate: wrap any existing THREE.Object3D (auto cameras + autoKnobs):
+runSceneView(myGroup, { autoKnobs: true });
+```
+
+## What's in here
+
+- **`runLab` / `runSceneLab` / `runSceneView`** — the lab entry points.
+- **`Element`** — `{ name, cameras | 'auto', mount() → { root, dispose }, knobs?, telemetry?, motionProbes?, … }`.
+- **`autoCameras(bounds)`** — four fitted camera presets from an AABB.
+- The Vite telemetry plugin: `import { triscopeTelemetryPlugin } from '@triscope/core/vite'`
+  (serves `/__state`, `/__knob`, `/__manifest`, `/__scene`).
+
+A single-element `runLab` page uses **bare** camera/knob names; a `runSceneLab`
+scene namespaces them `<element>.<key>`.
+
+## Scaffold a project
+
+```sh
+npm init triscope my-app      # greenfield
+npx triscope adopt            # retrofit an existing Vite + Three project
+```
+
+Part of the [triscope](https://github.com/tedin7/triscope) monorepo. MIT.

package/dist/compose.d.ts

@@ -0,0 +1,11 @@
+import type { Element } from './types.js';
+export interface ComposeOptions {
+    /** Name of the composite element. Used for the state file + manifest. Default: 'composite'. */
+    name?: string;
+    /** Override the auto-computed bounds (union of children's). */
+    bounds?: Element['bounds'];
+    /** Override the lab URL (otherwise inherits the first child's). */
+    labUrl?: string;
+}
+export declare function composeElements(elements: Element[], opts?: ComposeOptions): Element;
+//# sourceMappingURL=compose.d.ts.map

package/dist/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAc,OAAO,EAA4C,MAAM,YAAY,CAAC;AAEhG,MAAM,WAAW,cAAc;IAC7B,+FAA+F;IAC/F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3B,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAwGvF"}

package/dist/compose.js

@@ -0,0 +1,152 @@
+/**
+ * composeElements — fold multiple Elements into one composite Element.
+ *
+ * The Element contract is already enough for composition (the README has
+ * said "composition is just an element that mounts other elements" from
+ * day one) but writing the boilerplate by hand is tedious. This helper
+ * does the bookkeeping: it merges cameras, knobs, motionProbes, events,
+ * and telemetry under a `<elementName>.<key>` namespace so two elements
+ * declaring a camera both named "top" don't collide.
+ *
+ * Pass the result to runLab(). Inspect mode keeps working — each
+ * underlying element's meshes still get their own auto source-tags
+ * (the patch is global, not per-element).
+ *
+ * Knob routing: when the harness calls onKnob('ship.windPressure', x),
+ * we split on the first dot, find the matching element, and forward to
+ * its onKnob with the un-prefixed key ('windPressure').
+ */
+import { autoCameras } from './scene-cameras.js';
+export function composeElements(elements, opts = {}) {
+    if (!Array.isArray(elements) || elements.length === 0) {
+        throw new Error('composeElements: pass a non-empty array of Element');
+    }
+    const name = opts.name ?? 'composite';
+    const labUrl = opts.labUrl ?? elements[0]?.labUrl;
+    const bounds = opts.bounds ?? unionBounds(elements);
+    // Pre-build the merged camera/knob/motionProbe maps so the Element shape
+    // is correct before mount runs. onKnob/telemetry/motionProbes/events
+    // close over `elements` (static) and reach into handle.userData.handles
+    // (the live MountHandle list) for per-element lookups.
+    const cameras = {};
+    const knobs = {};
+    const motionProbes = {};
+    for (let i = 0; i < elements.length; i++) {
+        const el = elements[i];
+        const camSpecs = el.cameras === 'auto' ? autoCameras(el.bounds) : (el.cameras ?? {});
+        for (const [cn, c] of Object.entries(camSpecs)) {
+            cameras[nsKey(el.name, cn)] = c;
+        }
+        for (const [kn, k] of Object.entries(el.knobs ?? {})) {
+            knobs[nsKey(el.name, kn)] = k;
+        }
+        for (const [pn, p] of Object.entries(el.motionProbes ?? {})) {
+            const idx = i; // capture
+            motionProbes[nsKey(el.name, pn)] = (handle, ctx) => {
+                const childHandle = handle.userData?.handles?.[idx];
+                return childHandle ? p(childHandle, ctx) : 0;
+            };
+        }
+    }
+    return {
+        name,
+        labUrl,
+        bounds,
+        cameras,
+        knobs,
+        mount: ({ parent, ctx }) => {
+            const handles = elements.map((el) => el.mount({ parent, ctx }));
+            // name → child handle, so the SDL can show/hide a child at runtime
+            // (applyElementToggle) without dispose/remount.
+            const childrenByName = {};
+            elements.forEach((el, i) => {
+                childrenByName[el.name] = handles[i];
+            });
+            return {
+                root: parent,
+                userData: { handles, childrenByName },
+                dispose: () => {
+                    for (const h of handles) {
+                        try {
+                            h.dispose();
+                        }
+                        catch {
+                            /* keep tearing down the rest */
+                        }
+                    }
+                },
+            };
+        },
+        onKnob: (handle, key, value) => {
+            const [elName, knobKey] = splitNs(key);
+            if (!elName || !knobKey)
+                return;
+            const idx = elements.findIndex((e) => e.name === elName);
+            if (idx < 0)
+                return;
+            const childHandle = handle.userData?.handles?.[idx];
+            if (!childHandle)
+                return;
+            elements[idx].onKnob?.(childHandle, knobKey, value);
+        },
+        telemetry: (handle, ctx) => {
+            const out = {};
+            const childHandles = handle.userData?.handles ?? [];
+            for (let i = 0; i < elements.length; i++) {
+                const el = elements[i];
+                const h = childHandles[i];
+                out[el.name] = h && el.telemetry ? el.telemetry(h, ctx) : {};
+            }
+            return out;
+        },
+        motionProbes,
+        events: (handle, ctx) => {
+            const out = [];
+            const childHandles = handle.userData?.handles ?? [];
+            for (let i = 0; i < elements.length; i++) {
+                const el = elements[i];
+                const h = childHandles[i];
+                if (!el.events || !h)
+                    continue;
+                try {
+                    for (const ev of el.events(h, ctx) ?? []) {
+                        // Namespace event types so a `collision` from ship and water
+                        // are distinguishable downstream.
+                        out.push({ ...ev, type: nsKey(el.name, ev.type) });
+                    }
+                }
+                catch {
+                    /* ignore element-level failures */
+                }
+            }
+            return out;
+        },
+    };
+}
+function unionBounds(elements) {
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    let any = false;
+    for (const el of elements) {
+        if (!el.bounds)
+            continue;
+        any = true;
+        for (let i = 0; i < 3; i++) {
+            if (el.bounds.min[i] < min[i])
+                min[i] = el.bounds.min[i];
+            if (el.bounds.max[i] > max[i])
+                max[i] = el.bounds.max[i];
+        }
+    }
+    return any ? { min, max } : undefined;
+}
+function nsKey(elementName, key) {
+    return `${elementName}.${key}`;
+}
+function splitNs(key) {
+    const dot = key.indexOf('.');
+    if (dot < 0)
+        return ['', key];
+    return [key.slice(0, dot), key.slice(dot + 1)];
+}
+//# sourceMappingURL=compose.js.map

package/dist/compose.js.map

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

package/dist/editor.d.ts

@@ -0,0 +1,14 @@
+import type { Knob } from './types.js';
+type KnobChange = (key: string, value: number | string | boolean) => void;
+/**
+ * Render a minimal slider/color/checkbox editor for the element's knobs into the given DOM container.
+ * Returns a `setValue(key, value)` function so external sources (MCP) can keep the UI in sync.
+ *
+ * Stays deliberately bare-bones — the styling is the host page's job.
+ */
+export declare function mountEditor(container: HTMLElement, knobs: Record<string, Knob>, initial: Record<string, number | string | boolean>, onChange: KnobChange): {
+    setValue: (key: string, value: number | string | boolean) => void;
+    destroy: () => void;
+};
+export {};
+//# sourceMappingURL=editor.d.ts.map

package/dist/editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor.d.ts","sourceRoot":"","sources":["../src/editor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC,KAAK,UAAU,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,KAAK,IAAI,CAAC;AAE1E;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,EAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAClD,QAAQ,EAAE,UAAU,GACnB;IAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,KAAK,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAmH5F"}

package/dist/editor.js

@@ -0,0 +1,131 @@
+/**
+ * Render a minimal slider/color/checkbox editor for the element's knobs into the given DOM container.
+ * Returns a `setValue(key, value)` function so external sources (MCP) can keep the UI in sync.
+ *
+ * Stays deliberately bare-bones — the styling is the host page's job.
+ */
+export function mountEditor(container, knobs, initial, onChange) {
+    container.replaceChildren();
+    container.classList.add('triscope-editor');
+    const inputs = new Map();
+    const values = new Map();
+    for (const [key, spec] of Object.entries(knobs)) {
+        const row = document.createElement('div');
+        row.className = 'triscope-editor__row';
+        row.dataset.knobKey = key;
+        const label = document.createElement('label');
+        label.textContent = spec.label ?? key;
+        label.title = key;
+        row.appendChild(label);
+        const input = document.createElement('input');
+        input.dataset.knobKey = key;
+        const out = document.createElement('output');
+        if (spec.type === 'number' || spec.type === 'int') {
+            input.type = 'range';
+            input.min = String(spec.min);
+            input.max = String(spec.max);
+            input.step = String(spec.type === 'int' ? 1 : (spec.step ?? (spec.max - spec.min) / 200));
+            const v = typeof initial[key] === 'number' ? Number(initial[key]) : spec.default;
+            input.value = String(v);
+            out.textContent = formatNumber(v, spec.type);
+            input.oninput = () => {
+                const num = spec.type === 'int' ? parseInt(input.value, 10) : parseFloat(input.value);
+                out.textContent = formatNumber(num, spec.type);
+                onChange(key, num);
+            };
+        }
+        else if (spec.type === 'color') {
+            input.type = 'color';
+            const v = typeof initial[key] === 'string' ? String(initial[key]) : spec.default;
+            input.value = v;
+            out.textContent = v;
+            input.oninput = () => {
+                out.textContent = input.value;
+                onChange(key, input.value);
+            };
+        }
+        else if (spec.type === 'boolean') {
+            input.type = 'checkbox';
+            const v = typeof initial[key] === 'boolean' ? Boolean(initial[key]) : spec.default;
+            input.checked = v;
+            out.textContent = v ? 'on' : 'off';
+            input.onchange = () => {
+                out.textContent = input.checked ? 'on' : 'off';
+                onChange(key, input.checked);
+            };
+        }
+        else if (spec.type === 'trigger') {
+            // Trigger renders as a button. Each click fires onChange(true) — the
+            // value carries no state, the act itself is the signal.
+            const btn = document.createElement('button');
+            btn.type = 'button';
+            btn.textContent = spec.label ?? key;
+            btn.dataset.knobKey = key;
+            btn.onclick = () => {
+                out.textContent = 'fired';
+                onChange(key, true);
+                setTimeout(() => {
+                    out.textContent = '–';
+                }, 400);
+            };
+            out.textContent = '–';
+            row.appendChild(btn);
+            row.appendChild(out);
+            container.appendChild(row);
+            values.set(key, out);
+            // No persistent input element — leave inputs.set unset; setValue from
+            // external pulse will still flash the output.
+            continue;
+        }
+        row.appendChild(input);
+        row.appendChild(out);
+        container.appendChild(row);
+        inputs.set(key, input);
+        values.set(key, out);
+    }
+    return {
+        setValue(key, value) {
+            const out = values.get(key);
+            const spec = knobs[key];
+            if (!out || !spec)
+                return;
+            if (spec.type === 'trigger') {
+                // External pulse — flash the output to confirm receipt; no input
+                // element to sync because trigger has no persistent state.
+                out.textContent = 'fired';
+                setTimeout(() => {
+                    out.textContent = '–';
+                }, 400);
+                return;
+            }
+            const inp = inputs.get(key);
+            if (!inp)
+                return;
+            if (spec.type === 'number' || spec.type === 'int') {
+                inp.value = String(value);
+                out.textContent = formatNumber(Number(value), spec.type);
+            }
+            else if (spec.type === 'color') {
+                inp.value = String(value);
+                out.textContent = String(value);
+            }
+            else if (spec.type === 'boolean') {
+                inp.checked = Boolean(value);
+                out.textContent = inp.checked ? 'on' : 'off';
+            }
+        },
+        destroy() {
+            container.replaceChildren();
+        },
+    };
+}
+function formatNumber(v, type) {
+    if (type === 'int')
+        return String(Math.round(v));
+    if (Math.abs(v) >= 100)
+        return v.toFixed(1);
+    if (Math.abs(v) >= 1)
+        return v.toFixed(2);
+    return v.toFixed(3);
+}
+//# sourceMappingURL=editor.js.map

package/dist/editor.js.map

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

package/dist/harness.d.ts

@@ -0,0 +1,199 @@
+import * as THREE from 'three/webgpu';
+import { type InspectSelection } from './inspect.js';
+import { type CameraDelta } from './scene-delta.js';
+import { type LightNode, type SceneNode } from './scene-introspect.js';
+import type { CameraSpec, Element, MountHandle } from './types.js';
+import { type UniformReadResult, type UniformWriteResult } from './uniform-access.js';
+import { type WarningEntry } from './warnings.js';
+declare global {
+    interface Window {
+        __TRISCOPE__?: TriscopeGlobal;
+        /** Set when element.mount() throws or the contract is invalid; read by the
+         *  MCP browser pool to report the real cause instead of a mount timeout. */
+        __TRISCOPE_MOUNT_ERROR__?: {
+            element?: string;
+            message: string;
+            problems: string[];
+        };
+    }
+}
+interface TriscopeGlobal {
+    element: Element;
+    handle: MountHandle;
+    renderer: THREE.WebGPURenderer;
+    scene: THREE.Scene;
+    cameras: Record<string, THREE.PerspectiveCamera>;
+    knobValues: Record<string, number | string | boolean>;
+    setKnob: (key: string, value: number | string | boolean) => void;
+    sampleTelemetry: () => Record<string, unknown>;
+    /** Inspect-mode selection — set by clicking a mesh in `?inspect=` mode. */
+    lastSelection?: InspectSelection | null;
+    /** Capture one frame per named camera; returns base64 PNGs keyed by camera. */
+    captureViews: () => Promise<Record<string, string>>;
+    /**
+     * Capture N frames of a single camera spaced by dt seconds. In `mode: 'time'`
+     * (default), the RAF loop is paused and `time.value` is stepped forward
+     * deterministically — works for shader-driven motion. In `mode: 'real'`, the
+     * RAF keeps running and frames are sampled at wall-clock intervals — needed
+     * for CPU-integrated state (springs, particles).
+     */
+    captureMotionFrames: (camera: string, opts?: {
+        frames?: number;
+        dt?: number;
+        mode?: 'time' | 'real';
+    }) => Promise<string[]>;
+    /** Per-camera GPU probe stats from the most recent captureViews() call. */
+    lastGpuProbes?: Record<string, GpuProbeStats>;
+    /** Recent non-fatal failures the harness swallowed (telemetry/knob/probe). */
+    warnings?: WarningEntry[];
+    /**
+     * Snapshot the live scene graph: meshes/lights/groups with triangle counts,
+     * world positions, material kind/color, uniform names, and the file:line
+     * source tag. One call replaces a flurry of capture probes when an agent
+     * needs to know what's actually in the scene.
+     */
+    queryScene: (maxNodes?: number) => {
+        nodes: SceneNode[];
+        lights: LightNode[];
+        total: number;
+        truncated: boolean;
+    };
+    /** Read any material uniform / material property / object property by
+     *  "objectName|uuid.key" path — even undeclared ones. */
+    readUniform: (path: string) => UniformReadResult;
+    /** Write the same, live and transient (not persisted). Returns previous/current. */
+    setUniform: (path: string, value: unknown) => UniformWriteResult;
+    /**
+     * SDL: apply a scene delta live (repoint cameras, override knobs) WITHOUT a
+     * reload, and persist it via /__scene so it survives one. Returns the live
+     * scene state after applying.
+     */
+    setSceneParam: (delta: {
+        cameras?: Record<string, CameraDelta>;
+        knobs?: Record<string, unknown>;
+        elements?: Record<string, {
+            enabled?: boolean;
+        }>;
+    }) => {
+        cameras: Record<string, {
+            position: number[];
+            target: number[];
+            fov: number;
+        }>;
+        knobs: Record<string, number | string | boolean>;
+        elements: Record<string, {
+            enabled: boolean;
+        }>;
+    };
+    /** Current live camera positions/targets/fov + knob values + element on/off. */
+    getScene: () => {
+        cameras: Record<string, {
+            position: number[];
+            target: number[];
+            fov: number;
+        }>;
+        knobs: Record<string, number | string | boolean>;
+        elements: Record<string, {
+            enabled: boolean;
+        }>;
+    };
+    /**
+     * Mount a registered-but-unmounted element live (runSceneLab scenes). Adds
+     * its namespaced cameras/knobs and rebuilds the grid. Returns false if the
+     * name is unknown or already mounted. A single-element runLab has nothing
+     * else to add, so this is a no-op there.
+     */
+    addElement: (name: string) => boolean;
+    /** Dispose a mounted element live + rebuild the grid. False if not mounted. */
+    removeElement: (name: string) => boolean;
+    /** All element names in the scene registry (mounted or not). */
+    availableElements: () => string[];
+    /** Currently mounted element names, in registry order. */
+    mountedElements: () => string[];
+    /** Monotonic count of rendered frames since boot (gates capture readiness). */
+    framesRendered: () => number;
+}
+export interface CommonLabOptions {
+    canvas: HTMLCanvasElement;
+    editorContainer?: HTMLElement | null;
+    labelContainer?: HTMLElement | null;
+    hud?: HTMLElement | null;
+    bootOverlay?: HTMLElement | null;
+    telemetryIntervalMs?: number;
+    knobPollMs?: number;
+    /** Optional clear color for the scene before each frame. Default `#0a1a20`. */
+    clearColor?: number;
+    /**
+     * Fixed [width, height] in CSS pixels to which the canvas is resized for
+     * every captureViews / captureMotionFrames call, then restored. Use this
+     * when you need reproducible framing across page reloads (otherwise the
+     * canvas tracks clientWidth/clientHeight which can drift). Off by default.
+     */
+    captureSize?: [number, number];
+}
+export interface LabOptions extends CommonLabOptions {
+    element: Element;
+}
+export interface SceneLabOptions extends CommonLabOptions {
+    /** Registry of element types the scene can mount/unmount at runtime. */
+    elements: Element[];
+    /** Names initially mounted (defaults to every registered element). */
+    mounted?: string[];
+}
+export interface LabHandle {
+    /** The primary mounted element (first slot); undefined-safe as slots change. */
+    element: Element;
+    setKnob: (key: string, value: number | string | boolean) => void;
+    captureViews: () => Promise<Record<string, string>>;
+    /** Mount a registered element live (runSceneLab). No-op for single-element labs. */
+    addElement: (name: string) => boolean;
+    /** Dispose a mounted element live (runSceneLab). */
+    removeElement: (name: string) => boolean;
+    /** All element names in the scene registry. */
+    availableElements: () => string[];
+    /** Currently mounted element names. */
+    mountedElements: () => string[];
+    stop: () => void;
+}
+/**
+ * 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 declare function runLab(opts: LabOptions): Promise<LabHandle>;
+/**
+ * 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 declare function runSceneLab(opts: SceneLabOptions): Promise<LabHandle>;
+/**
+ * Aggregated brightness/contrast scalars computed from a rendered canvas.
+ * Probes are run by the harness during `captureViews()` — they validate
+ * that the GPU actually drew something (luminance > 0 means the frame is
+ * not black; p95/p5 ratio > 1 means there's contrast).
+ */
+export interface GpuProbeStats {
+    /** Mean perceptual luminance (Rec.709) in [0, 1]. */
+    luminance: number;
+    /** 5th percentile luminance. */
+    p5: number;
+    /** 95th percentile luminance. */
+    p95: number;
+    /** p95 / max(p5, 1/255) — dynamic range proxy. */
+    dynamicRange: number;
+    /** Number of pixels sampled (typically 64×36 = 2304). */
+    samples: number;
+    /** Set true when this camera's mean luminance indicates a black render. */
+    blackFrame?: boolean;
+}
+export declare function makeCamera(spec: CameraSpec, bounds?: Element['bounds']): THREE.PerspectiveCamera;
+export declare function fitCameraToBounds(cam: THREE.PerspectiveCamera, spec: CameraSpec, bounds: NonNullable<Element['bounds']>): void;
+export {};
+//# sourceMappingURL=harness.d.ts.map

package/dist/harness.d.ts.map

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