@triscope/core 0.4.0

package/src/harness.ts

@@ -0,0 +1,1263 @@
+import * as THREE from 'three/webgpu';
+import { mountEditor } from './editor.js';
+import {
+  createInspectMode,
+  type InspectMode,
+  type InspectSelection,
+  readInspectFromUrl,
+} from './inspect.js';
+import { clampKnob } from './knob-utils.js';
+import { MotionProbeBuffer, type ProbeStats } from './motion-probe.js';
+import { isBlackFrame } from './probe-utils.js';
+import { autoCameras } from './scene-cameras.js';
+import { applyCameraDelta, applyElementToggle, type CameraDelta } from './scene-delta.js';
+import { type LightNode, type SceneNode, serializeScene } from './scene-introspect.js';
+import { nsKey, type RegistryEntry } from './scene-registry.js';
+import { installSourceTagPatch } from './source-tag.js';
+import type {
+  CameraSpec,
+  Element,
+  Knob,
+  MountContext,
+  MountHandle,
+  TriscopeEvent,
+} from './types.js';
+import { knobDefault } from './types.js';
+import {
+  readUniformValue,
+  type UniformReadResult,
+  type UniformWriteResult,
+  writeUniformValue,
+} from './uniform-access.js';
+import { validateElement } from './validate.js';
+import { createWarningRing, type WarningEntry } 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();
+
+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 async function runLab(opts: LabOptions): Promise<LabHandle> {
+  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: SceneLabOptions): Promise<LabHandle> {
+  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: CommonLabOptions,
+  registry: { entries: RegistryEntry[]; namespaced: boolean; initialMounted: string[] },
+): Promise<LabHandle> {
+  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: MountContext = { 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);
+
+  // ---- Multi-element registry -------------------------------------------
+  // runLab → one entry, namespaced=false (bare camera/knob names, identical to
+  // before this was generalized). runSceneLab → N entries, namespaced=true
+  // (`<element>.<key>` keys so two elements declaring `top`/`speed` don't
+  // collide), with runtime mountSlot/unmountSlot driving addElement/
+  // removeElement. A "slot" is one mounted element + its handle + probes.
+  interface Slot {
+    name: string;
+    element: Element;
+    handle: MountHandle;
+    probeKeys: string[];
+    probeBuffers: Record<string, MotionProbeBuffer>;
+  }
+  const slots: Slot[] = [];
+  const cameras: Record<string, THREE.PerspectiveCamera> = {};
+  const cameraOrder: string[] = [];
+  const cameraElement: Record<string, string> = {}; // display camera name → slot name
+  const knobs: Record<string, Knob> = {}; // display key → spec
+  const knobValues: Record<string, number | string | boolean> = {};
+  const knobBinding: Record<string, { slot: Slot; local: string }> = {}; // 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: Record<string, Record<string, unknown>> = {};
+  try {
+    const r = await fetch('/__knob/current');
+    if (r.ok) persistedKnobs = (await r.json()) as Record<string, Record<string, unknown>>;
+  } 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: string, el: Element): Slot | null {
+    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: MountHandle;
+    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: Record<string, MotionProbeBuffer> = {};
+    for (const k of probeKeys) probeBuffers[k] = new MotionProbeBuffer(120);
+    const slot: 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)) as
+        | number
+        | string
+        | boolean;
+      // 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: string): boolean {
+    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: ReturnType<typeof mountEditor> | null = null;
+  function rebuildEditor(): void {
+    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: string, value: number | string | boolean, fromExternal: boolean): void {
+    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: Record<string, HTMLDivElement> = {};
+  function rebuildLabels(): void {
+    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: Slot): void {
+    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: TriscopeEvent[] = [];
+
+  function resize(): void {
+    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: InspectMode | null = null;
+  let currentSelection: InspectSelection | null = null;
+  let currentSelections: InspectSelection[] = [];
+  // (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(): void {
+    if (inspectMode) {
+      inspectMode.dispose();
+      inspectMode = null;
+    }
+    let inspectCfg: ReturnType<typeof readInspectFromUrl> = 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__ as any).lastSelection = sel;
+          (window.__TRISCOPE__ as any).selections = currentSelections;
+        }
+      },
+    });
+  }
+  setupInspect();
+
+  function renderAll(): void {
+    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(): void {
+    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(): string {
+    return namespaced ? slots.map((s) => s.name).join('+') || 'scene' : (slots[0]?.name ?? '');
+  }
+
+  function buildState(): Record<string, unknown> {
+    const elements: Record<string, unknown> = {};
+    for (const slot of slots) {
+      let tel: Record<string, unknown> = {};
+      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: Record<string, ProbeStats | null> = {};
+        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(): Promise<void> {
+    try {
+      const res = await fetch('/__knob');
+      if (!res.ok) return;
+      const drained = (await res.json()) as Array<{
+        element?: string;
+        key: string;
+        value: unknown;
+      }>;
+      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: string | null = 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 as number | string | boolean, true);
+      }
+    } catch (e) {
+      warnings.push('pollKnobs', 'knob poll failed', errDetail(e));
+    }
+  }
+
+  async function captureMotionFrames(
+    cameraName: string,
+    motionOpts: { frames?: number; dt?: number; mode?: 'time' | 'real' } = {},
+  ): Promise<string[]> {
+    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: string[] = [];
+    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 as unknown as {
+        nodeFrame?: { time: number; deltaTime: number };
+        _nodes?: { nodeFrame?: { time: number; deltaTime: number } };
+      };
+      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: number) => 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(): Promise<Record<string, string>> {
+    // 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: Record<string, string> = {};
+    const probeStats: Record<string, GpuProbeStats> = {};
+    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__ as any).lastGpuProbes = probeStats;
+    }
+    // Restore live canvas dimensions + per-camera aspect ratios.
+    resize();
+    return out;
+  }
+
+  function queryScene(maxNodes = 500) {
+    return serializeScene(scene, {
+      maxNodes,
+      getWorldPosition: (o: THREE.Object3D) => {
+        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: string): UniformReadResult {
+    return readUniformValue(scene, path);
+  }
+  function setUniform(path: string, value: unknown): UniformWriteResult {
+    return writeUniformValue(scene, path, value);
+  }
+
+  // ---- SDL: live scene mutation (camera repoint + knob override) ----------
+  function applySceneDelta(delta: {
+    cameras?: Record<string, CameraDelta>;
+    knobs?: Record<string, unknown>;
+    elements?: Record<string, { enabled?: boolean }>;
+  }): void {
+    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 as number | string | boolean, 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(): Record<string, { enabled: boolean }> {
+    const out: Record<string, { enabled: boolean }> = {};
+    for (const slot of slots) {
+      const childMap = (slot.handle.userData as { childrenByName?: Record<string, MountHandle> })
+        ?.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: {
+    cameras?: Record<string, CameraDelta>;
+    knobs?: Record<string, unknown>;
+    elements?: Record<string, { enabled?: boolean }>;
+  }) {
+    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(): Promise<void> {
+    try {
+      const res = await fetch('/__scene');
+      if (!res.ok) return;
+      const drained = (await res.json()) as Array<{
+        cameras?: Record<string, CameraDelta>;
+        knobs?: Record<string, unknown>;
+      }>;
+      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: string): boolean {
+    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: Slot | null;
+    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: string): boolean {
+    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 as Element;
+    },
+    get handle() {
+      return slots[0]?.handle as MountHandle;
+    },
+    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 as 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();
+    },
+  };
+}
+
+/**
+ * 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;
+}
+
+const PROBE_SAMPLE_W = 64;
+const PROBE_SAMPLE_H = 36;
+let probeSampler: { canvas: HTMLCanvasElement; ctx: CanvasRenderingContext2D } | null = null;
+
+function sampleGpuProbes(srcCanvas: HTMLCanvasElement): GpuProbeStats {
+  // 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: CameraSpec, bounds?: Element['bounds']): THREE.PerspectiveCamera {
+  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] as [number, number, number];
+  if (spec.fit && bounds) {
+    fitCameraToBounds(cam, spec, bounds);
+  }
+  return cam;
+}
+
+export function fitCameraToBounds(
+  cam: THREE.PerspectiveCamera,
+  spec: CameraSpec,
+  bounds: NonNullable<Element['bounds']>,
+): void {
+  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: THREE.PerspectiveCamera): [number, number, number] {
+  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: Record<string, unknown>): Promise<void> {
+  await fetch('/__state', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+}
+
+async function postManifest(payload: Record<string, unknown>): Promise<void> {
+  await fetch('/__manifest', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+}
+
+async function postScene(payload: Record<string, unknown>): Promise<void> {
+  await fetch('/__scene', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+}
+
+function errDetail(e: unknown): string {
+  const msg = (e as { message?: unknown })?.message ?? e;
+  return String(msg).slice(0, 300);
+}