npm - @triscope/core - Versions diffs - 0.4.0 - Mend

@triscope/core 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (114) hide show

package/LICENSE +21 -0
package/README.md +39 -0
package/dist/compose.d.ts +11 -0
package/dist/compose.d.ts.map +1 -0
package/dist/compose.js +152 -0
package/dist/compose.js.map +1 -0
package/dist/editor.d.ts +14 -0
package/dist/editor.d.ts.map +1 -0
package/dist/editor.js +131 -0
package/dist/editor.js.map +1 -0
package/dist/harness.d.ts +199 -0
package/dist/harness.d.ts.map +1 -0
package/dist/harness.js +1027 -0
package/dist/harness.js.map +1 -0
package/dist/index.d.ts +32 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +20 -0
package/dist/index.js.map +1 -0
package/dist/inspect.d.ts +94 -0
package/dist/inspect.d.ts.map +1 -0
package/dist/inspect.js +434 -0
package/dist/inspect.js.map +1 -0
package/dist/knob-utils.d.ts +22 -0
package/dist/knob-utils.d.ts.map +1 -0
package/dist/knob-utils.js +51 -0
package/dist/knob-utils.js.map +1 -0
package/dist/lab/css.d.ts +11 -0
package/dist/lab/css.d.ts.map +1 -0
package/dist/lab/css.js +57 -0
package/dist/lab/css.js.map +1 -0
package/dist/lab/dom.d.ts +13 -0
package/dist/lab/dom.d.ts.map +1 -0
package/dist/lab/dom.js +76 -0
package/dist/lab/dom.js.map +1 -0
package/dist/motion-probe.d.ts +47 -0
package/dist/motion-probe.d.ts.map +1 -0
package/dist/motion-probe.js +122 -0
package/dist/motion-probe.js.map +1 -0
package/dist/probe-utils.d.ts +14 -0
package/dist/probe-utils.d.ts.map +1 -0
package/dist/probe-utils.js +18 -0
package/dist/probe-utils.js.map +1 -0
package/dist/scene-cameras.d.ts +6 -0
package/dist/scene-cameras.d.ts.map +1 -0
package/dist/scene-cameras.js +20 -0
package/dist/scene-cameras.js.map +1 -0
package/dist/scene-delta.d.ts +21 -0
package/dist/scene-delta.d.ts.map +1 -0
package/dist/scene-delta.js +57 -0
package/dist/scene-delta.js.map +1 -0
package/dist/scene-introspect.d.ts +78 -0
package/dist/scene-introspect.d.ts.map +1 -0
package/dist/scene-introspect.js +164 -0
package/dist/scene-introspect.js.map +1 -0
package/dist/scene-registry.d.ts +36 -0
package/dist/scene-registry.d.ts.map +1 -0
package/dist/scene-registry.js +64 -0
package/dist/scene-registry.js.map +1 -0
package/dist/scene-view.d.ts +52 -0
package/dist/scene-view.d.ts.map +1 -0
package/dist/scene-view.js +171 -0
package/dist/scene-view.js.map +1 -0
package/dist/source-tag.d.ts +34 -0
package/dist/source-tag.d.ts.map +1 -0
package/dist/source-tag.js +120 -0
package/dist/source-tag.js.map +1 -0
package/dist/telemetry.d.ts +53 -0
package/dist/telemetry.d.ts.map +1 -0
package/dist/telemetry.js +302 -0
package/dist/telemetry.js.map +1 -0
package/dist/types.d.ts +142 -0
package/dist/types.d.ts.map +1 -0
package/dist/types.js +9 -0
package/dist/types.js.map +1 -0
package/dist/uniform-access.d.ts +32 -0
package/dist/uniform-access.d.ts.map +1 -0
package/dist/uniform-access.js +144 -0
package/dist/uniform-access.js.map +1 -0
package/dist/validate.d.ts +2 -0
package/dist/validate.d.ts.map +1 -0
package/dist/validate.js +81 -0
package/dist/validate.js.map +1 -0
package/dist/vite.d.ts +3 -0
package/dist/vite.d.ts.map +1 -0
package/dist/vite.js +4 -0
package/dist/vite.js.map +1 -0
package/dist/warnings.d.ts +24 -0
package/dist/warnings.d.ts.map +1 -0
package/dist/warnings.js +26 -0
package/dist/warnings.js.map +1 -0
package/package.json +60 -0
package/src/compose.ts +164 -0
package/src/editor.ts +138 -0
package/src/harness.ts +1263 -0
package/src/index.ts +58 -0
package/src/inspect.ts +498 -0
package/src/knob-utils.ts +60 -0
package/src/lab/css.ts +56 -0
package/src/lab/dom.ts +88 -0
package/src/motion-probe.ts +135 -0
package/src/probe-utils.ts +17 -0
package/src/scene-cameras.ts +33 -0
package/src/scene-delta.ts +69 -0
package/src/scene-introspect.ts +230 -0
package/src/scene-registry.ts +103 -0
package/src/scene-view.ts +204 -0
package/src/source-tag.ts +139 -0
package/src/telemetry.ts +337 -0
package/src/three-webgpu-shim.d.ts +130 -0
package/src/types.ts +121 -0
package/src/uniform-access.ts +152 -0
package/src/validate.ts +82 -0
package/src/vite.ts +5 -0
package/src/warnings.ts +41 -0

package/src/lab/dom.ts ADDED Viewed

@@ -0,0 +1,88 @@
+/**
+ * Lab DOM scaffolding helper.
+ *
+ * Eliminates per-project boilerplate: instead of every lab HTML page
+ * declaring its own <canvas>, <div id="boot">, <div id="hud">, knob
+ * editor pane + the supporting CSS, consumers call
+ *
+ *   const dom = mountLabDom();
+ *   runLab({ element, ...dom });
+ *
+ * The helper:
+ *  - Injects `LAB_CSS` once into `<head>` (no-op on second call).
+ *  - Creates the standard ids `runLab()` / `mountEditor()` expect:
+ *    `boot`, `app`, `canvas`, `hud`, `lab-controls`.
+ *  - Returns the ref bundle in the shape `runLab()` accepts.
+ *
+ * Existing DOM nodes with matching ids are reused (no duplication).
+ * This means a project that wants custom CSS for one element can still
+ * hand-write the HTML and skip this helper — the contract is unchanged.
+ */
+import { LAB_CSS } from './css.js';
+export interface LabDomRefs {
+  canvas: HTMLCanvasElement;
+  hud: HTMLElement;
+  boot: HTMLElement;
+  labelContainer: HTMLElement;
+  editorContainer: HTMLElement;
+}
+const STYLE_ID = 'triscope-lab-css';
+function ensureStyleInjected(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById(STYLE_ID)) return;
+  const style = document.createElement('style');
+  style.id = STYLE_ID;
+  style.textContent = LAB_CSS;
+  document.head.appendChild(style);
+}
+function getOrCreate<T extends HTMLElement>(id: string, tag: string, parent: HTMLElement): T {
+  const existing = document.getElementById(id) as T | null;
+  if (existing) return existing;
+  const el = document.createElement(tag) as T;
+  el.id = id;
+  parent.appendChild(el);
+  return el;
+}
+/**
+ * Build (or reuse) the standard lab DOM and return the refs `runLab()`
+ * needs. Idempotent: calling twice does not duplicate nodes.
+ */
+export function mountLabDom(): LabDomRefs {
+  if (typeof document === 'undefined') {
+    throw new Error('mountLabDom() requires a browser DOM (document).');
+  }
+  ensureStyleInjected();
+  const body = document.body;
+  const boot = getOrCreate<HTMLDivElement>('boot', 'div', body);
+  if (!boot.textContent) boot.textContent = 'Initialising Triscope · WebGPU...';
+  const app = getOrCreate<HTMLDivElement>('app', 'div', body);
+  // Canvas lives inside `#app` so the label-overlay positioning math in
+  // `runLab` (which is relative to `#app`) lines up with the canvas pixels.
+  let canvas = document.getElementById('canvas') as HTMLCanvasElement | null;
+  if (!canvas) {
+    canvas = document.createElement('canvas');
+    canvas.id = 'canvas';
+    app.appendChild(canvas);
+  }
+  const hud = getOrCreate<HTMLDivElement>('hud', 'div', body);
+  if (!hud.textContent) hud.textContent = '- fps · WebGPU';
+  const editorContainer = getOrCreate<HTMLDivElement>('lab-controls', 'div', body);
+  return {
+    canvas,
+    hud,
+    boot,
+    labelContainer: app,
+    editorContainer,
+  };
+}

package/src/motion-probe.ts ADDED Viewed

@@ -0,0 +1,135 @@
+/**
+ * Ring-buffered numeric probe used by the lab harness to summarize animated
+ * Element state without ever leaving the CPU (no GPU readback). The buffer
+ * holds the last `capacity` (sample, time) pairs; `stats()` returns aggregates
+ * including a zero-crossing-based estimate of dominant frequency.
+ *
+ * Extracted from `runLab` so the math is unit-testable in isolation.
+ */
+export interface ProbeStats {
+  latest: number;
+  mean: number;
+  min: number;
+  max: number;
+  peakToPeak: number;
+  zeroCrossingsPerSec: number;
+  dominantFreqHz: number;
+  /** Last up-to-32 samples, in temporal order. */
+  samples: number[];
+}
+export class MotionProbeBuffer {
+  private readonly cap: number;
+  private readonly buf: Float32Array;
+  private readonly times: Float32Array;
+  private writeIdx = 0;
+  private count = 0;
+  constructor(capacity = 120) {
+    if (capacity <= 0) throw new Error('MotionProbeBuffer capacity must be > 0');
+    this.cap = capacity;
+    this.buf = new Float32Array(capacity);
+    this.times = new Float32Array(capacity);
+  }
+  push(value: number, time: number): void {
+    this.buf[this.writeIdx] = value;
+    this.times[this.writeIdx] = time;
+    this.writeIdx = (this.writeIdx + 1) % this.cap;
+    if (this.count < this.cap) this.count += 1;
+  }
+  get size(): number {
+    return this.count;
+  }
+  get capacity(): number {
+    return this.cap;
+  }
+  /** Returns (samples, times) in temporal order: oldest first, newest last. */
+  ordered(): { samples: number[]; times: number[] } {
+    const n = this.count;
+    const samples: number[] = new Array(n);
+    const times: number[] = new Array(n);
+    if (n < this.cap) {
+      for (let i = 0; i < n; i++) {
+        samples[i] = this.buf[i];
+        times[i] = this.times[i];
+      }
+    } else {
+      for (let i = 0; i < this.cap; i++) {
+        const j = (this.writeIdx + i) % this.cap;
+        samples[i] = this.buf[j];
+        times[i] = this.times[j];
+      }
+    }
+    return { samples, times };
+  }
+  stats(): ProbeStats | null {
+    if (this.count === 0) return null;
+    const { samples, times } = this.ordered();
+    return computeProbeStats(samples, times);
+  }
+}
+/**
+ * Pure stats kernel. `samples` and `times` must be the same length and in
+ * temporal order (oldest first). `times` is in seconds.
+ *
+ * Frequency estimate: count sign changes of (sample - mean); each full cycle
+ * has two zero-crossings, so divide by 2 to get cycles per duration, then by
+ * duration to get Hz. Robust for clean sinusoids; not a substitute for FFT on
+ * noisy / multi-frequency signals.
+ */
+export function computeProbeStats(samples: number[], times: number[]): ProbeStats | null {
+  const n = samples.length;
+  if (n === 0) return null;
+  if (times.length !== n) {
+    throw new Error(
+      `computeProbeStats: samples (${n}) and times (${times.length}) length mismatch`,
+    );
+  }
+  let min = samples[0];
+  let max = samples[0];
+  let sum = 0;
+  for (let i = 0; i < n; i++) {
+    const v = samples[i];
+    if (v < min) min = v;
+    if (v > max) max = v;
+    sum += v;
+  }
+  const mean = sum / n;
+  // Sign-based crossing counter. Samples sitting exactly on the mean (within
+  // ZERO_EPS) carry the previous sign forward instead of triggering a false
+  // crossing — important because sinusoids sampled at frame-aligned times
+  // routinely produce values like sin(π) ≈ 1.2e-16 that confuse a strict
+  // <=0 / >=0 comparator.
+  const ZERO_EPS = 1e-9;
+  let crossings = 0;
+  let prevSign = 0;
+  for (let i = 0; i < n; i++) {
+    const v = samples[i] - mean;
+    const s = Math.abs(v) < ZERO_EPS ? 0 : v > 0 ? 1 : -1;
+    if (s !== 0) {
+      if (prevSign !== 0 && s !== prevSign) crossings += 1;
+      prevSign = s;
+    }
+  }
+  const duration = Math.max(times[n - 1] - times[0], 1e-6);
+  const dominantFreqHz = crossings / 2 / duration;
+  const zeroCrossingsPerSec = crossings / duration;
+  const tail = samples.slice(Math.max(0, n - 32));
+  return {
+    latest: samples[n - 1],
+    mean: +mean.toFixed(4),
+    min: +min.toFixed(4),
+    max: +max.toFixed(4),
+    peakToPeak: +(max - min).toFixed(4),
+    zeroCrossingsPerSec: +zeroCrossingsPerSec.toFixed(2),
+    dominantFreqHz: +dominantFreqHz.toFixed(2),
+    samples: tail,
+  };
+}

package/src/probe-utils.ts ADDED Viewed

@@ -0,0 +1,17 @@
+/**
+ * Mean Rec.709 luminance below which a rendered pane is considered "black" —
+ * i.e. the GPU drew nothing. Matches the literal the ocean-galleon smoke has
+ * used (smoke.mjs ~line 367); kept here as the single source of truth so the
+ * harness, the MCP server fallback, and the smoke all agree.
+ */
+export const BLACK_FRAME_LUMINANCE = 0.004;
+/**
+ * True when a camera's mean luminance indicates it rendered black. A non-finite
+ * luminance (probe unavailable) returns false — we only assert "black" on real
+ * evidence, never on a missing measurement, so it can't manufacture CI failures.
+ */
+export function isBlackFrame(luminance: number, threshold = BLACK_FRAME_LUMINANCE): boolean {
+  if (!Number.isFinite(luminance)) return false;
+  return luminance < threshold;
+}

package/src/scene-cameras.ts ADDED Viewed

@@ -0,0 +1,33 @@
+// Pure camera-fitting: synthesize 4 fitted CameraSpecs around a bounding box.
+// No `three`, no harness import — so BOTH the harness (for `cameras: 'auto'`)
+// and scene-view (runSceneView) can use it without a circular dependency. The
+// presets mirror the gltf scaffolder's `camerasFor` (front/side/top/3-quarter,
+// 1.8× size standoff, fit:true so the harness frames them to the bounds).
+import type { CameraSpec, Element } from './types.js';
+export type Bounds = NonNullable<Element['bounds']>;
+export const UNIT_BOUNDS: Bounds = { min: [-1, -1, -1], max: [1, 1, 1] };
+/** 4 fitted CameraSpecs (front/side/top/three-quarter) around `bounds`. */
+export function autoCameras(bounds?: Bounds): Record<string, CameraSpec> {
+  const b = bounds ?? UNIT_BOUNDS;
+  const c: [number, number, number] = [0, 1, 2].map((k) => (b.min[k] + b.max[k]) / 2) as [
+    number,
+    number,
+    number,
+  ];
+  const size = Math.max(b.max[0] - b.min[0], b.max[1] - b.min[1], b.max[2] - b.min[2], 1);
+  const d = size * 1.8;
+  const target: [number, number, number] = [c[0], c[1], c[2]];
+  return {
+    front: { position: [c[0], c[1], c[2] + d], target, fit: true },
+    side: { position: [c[0] + d, c[1], c[2]], target, fit: true },
+    top: { position: [c[0], c[1] + d, c[2]], target, fit: true },
+    'three-quarter': {
+      position: [c[0] + d * 0.7, c[1] + d * 0.5, c[2] + d * 0.7],
+      target,
+      fit: true,
+    },
+  };
+}

package/src/scene-delta.ts ADDED Viewed

@@ -0,0 +1,69 @@
+// Pure Scene-Description-Layer (SDL) camera mutation — the data behind
+// set_scene_param. Lets an agent repoint a camera (position/target/fov) live,
+// without a .ts edit + reload. Duck-typed (no three import) so it's
+// unit-testable; the harness passes the live PerspectiveCamera.
+//
+// CRITICAL: a target change must also update `userData.target`, which the
+// harness's targetOf() reads for telemetry — otherwise the camera moves but
+// `read_telemetry .cameras.<name>.target` keeps reporting the stale value.
+export interface CameraDelta {
+  position?: [number, number, number];
+  target?: [number, number, number];
+  fov?: number;
+}
+function isVec3(v: unknown): v is [number, number, number] {
+  return (
+    Array.isArray(v) &&
+    v.length === 3 &&
+    v.every((n) => typeof n === 'number' && Number.isFinite(n))
+  );
+}
+/** Apply a camera delta in place. Returns false only if `cam` is missing. */
+export function applyCameraDelta(cam: any, delta: CameraDelta): boolean {
+  if (!cam) return false;
+  let changed = false;
+  // Position first, so the subsequent lookAt() computes orientation from the
+  // new position.
+  if (isVec3(delta.position)) {
+    cam.position.set(delta.position[0], delta.position[1], delta.position[2]);
+    changed = true;
+  }
+  if (isVec3(delta.target)) {
+    cam.lookAt(delta.target[0], delta.target[1], delta.target[2]);
+    cam.userData = cam.userData ?? {};
+    cam.userData.target = [delta.target[0], delta.target[1], delta.target[2]];
+    changed = true;
+  }
+  if (typeof delta.fov === 'number' && Number.isFinite(delta.fov)) {
+    cam.fov = delta.fov;
+    changed = true;
+  }
+  if (changed && typeof cam.updateProjectionMatrix === 'function') cam.updateProjectionMatrix();
+  return true;
+}
+/**
+ * Show/hide an element in the live scene by toggling its root's `visible` flag
+ * — the design-doc "solo a track" model of runtime add/remove, with zero
+ * dispose/remount risk. For a composed scene the children are looked up by name
+ * via `handle.userData.childrenByName` (populated by composeElements); for a
+ * single-element lab the mounted element itself matches. Returns false if the
+ * name doesn't resolve. NOTE: only the element's `root` subtree toggles — an
+ * element that adds lights directly to the scene (not under root) should parent
+ * them under root to hide cleanly.
+ */
+export function applyElementToggle(
+  handle: any,
+  mountedElement: { name?: string } | undefined,
+  name: string,
+  enabled: boolean,
+): boolean {
+  const child = handle?.userData?.childrenByName?.[name];
+  const target = child ?? (mountedElement?.name === name ? handle : null);
+  if (!target?.root) return false;
+  target.root.visible = enabled;
+  return true;
+}

package/src/scene-introspect.ts ADDED Viewed

@@ -0,0 +1,230 @@
+/**
+ * Pure scene-graph serializer — the data behind `inspect_scene`.
+ *
+ * Gives an AI agent a single machine-readable view of "what is in this scene"
+ * (meshes/lights/groups, triangle counts, world positions, materials, and the
+ * file:line source tag) so it can diagnose a render bug in one call instead of
+ * issuing 10-30 screenshot probes. Operates on duck-typed Object3D-like nodes
+ * so it has no `three` dependency and is unit-testable in node; the harness
+ * passes a `three`-based `getWorldPosition`.
+ */
+import type { SourceTag } from './source-tag.js';
+export interface SceneNode {
+  uuid: string;
+  name: string;
+  type: string;
+  visible: boolean;
+  /** World-space position, rounded to 3 decimals. */
+  worldPosition: [number, number, number];
+  triangleCount: number;
+  materialKind?: string;
+  materialColor?: string;
+  uniformNames?: string[];
+  /** file:line where this object was added to the scene (from the source-tag patch). */
+  source?: SourceTag['source'];
+  /** Ancestor names, root-first (root itself excluded). */
+  parentChain: string[];
+}
+export interface LightNode {
+  uuid: string;
+  name: string;
+  /**
+   * Concrete light class, e.g. "DirectionalLight" / "HemisphereLight". Exposed
+   * as both `type` (consistent with SceneNode.type) and `lightType` (explicit).
+   */
+  type: string;
+  lightType: string;
+  visible: boolean;
+  worldPosition: [number, number, number];
+  intensity?: number;
+  /** Light color as #rrggbb. */
+  color?: string;
+  /** Hemisphere ground color, when applicable. */
+  groundColor?: string;
+  /** Point/spot falloff distance + decay; spot cone angle (radians). */
+  distance?: number;
+  decay?: number;
+  angle?: number;
+  source?: SourceTag['source'];
+  parentChain: string[];
+}
+export interface SerializeSceneResult {
+  nodes: SceneNode[];
+  /**
+   * Every light in the scene, ALWAYS included regardless of the `nodes` cap.
+   * Lights have 0 triangles, so the triangle-count sort + maxNodes truncation
+   * would otherwise drop them — yet they're a prime tuning target (a named
+   * light is read/writable via read_uniform/set_uniform "name.intensity").
+   */
+  lights: LightNode[];
+  /** Total nodes found (before maxNodes truncation). */
+  total: number;
+  truncated: boolean;
+}
+export interface SerializeSceneOptions {
+  /**
+   * Cap on returned nodes (default 120) to bound the payload — nodes are sorted
+   * by triangle count, so the default surfaces the heaviest/most-significant
+   * geometry first; `truncated`+`total` flag the rest (raise maxNodes to see it).
+   * A full 500-node dump of a busy scene was ~160 KB and blew the agent's token
+   * budget; 120 keeps the common "what's in this scene" answer compact.
+   */
+  maxNodes?: number;
+  /** Harness supplies a three-based world-position getter; defaults to local position. */
+  getWorldPosition?: (o: any) => [number, number, number];
+}
+export function serializeScene(root: any, opts: SerializeSceneOptions = {}): SerializeSceneResult {
+  const maxNodes = opts.maxNodes ?? 120;
+  const getWP = opts.getWorldPosition ?? localPosition;
+  const all: any[] = [];
+  collectObjects(root, all);
+  const nodes: SceneNode[] = [];
+  const lights: LightNode[] = [];
+  const MAX_LIGHTS = 64;
+  for (const o of all) {
+    if (o === root) continue; // the scene root itself isn't interesting
+    // Lights go into their own array BEFORE the triangle sort/truncate so they
+    // are never dropped (they have 0 triangles). Duck-typed `isLight` flag —
+    // three sets it on every Light subclass; fakes can set it in tests.
+    if (o?.isLight === true && lights.length < MAX_LIGHTS) {
+      lights.push(describeLight(o, getWP, root));
+    }
+    nodes.push(describeNode(o, getWP, root));
+  }
+  nodes.sort((a, b) => b.triangleCount - a.triangleCount);
+  const total = nodes.length;
+  const truncated = total > maxNodes;
+  return { nodes: truncated ? nodes.slice(0, maxNodes) : nodes, lights, total, truncated };
+}
+function collectObjects(root: any, out: any[]): void {
+  if (!root) return;
+  // Real three exposes traverse(self + descendants); fakes use children DFS.
+  if (typeof root.traverse === 'function') {
+    root.traverse((o: any) => out.push(o));
+    return;
+  }
+  const stack = [root];
+  let guard = 0;
+  while (stack.length && guard++ < 100000) {
+    const o = stack.pop();
+    out.push(o);
+    const kids = o?.children;
+    if (Array.isArray(kids)) for (let i = kids.length - 1; i >= 0; i--) stack.push(kids[i]);
+  }
+}
+function describeNode(o: any, getWP: (o: any) => [number, number, number], root: any): SceneNode {
+  const tag = o?.userData?.__tris as SourceTag | undefined;
+  const node: SceneNode = {
+    uuid: String(o?.uuid ?? ''),
+    name: o?.name ?? '',
+    type: o?.type ?? o?.constructor?.name ?? 'Object3D',
+    visible: o?.visible !== false,
+    worldPosition: round3(getWP(o)),
+    triangleCount: triangleCount(o),
+    parentChain: parentChain(o, root),
+  };
+  const mat = Array.isArray(o?.material) ? o.material[0] : o?.material;
+  if (mat) {
+    node.materialKind = mat.type ?? mat.constructor?.name;
+    const color = materialColor(mat);
+    if (color) node.materialColor = color;
+    const names = uniformNames(mat);
+    if (names.length) node.uniformNames = names;
+  }
+  if (tag?.source) node.source = tag.source;
+  return node;
+}
+function describeLight(o: any, getWP: (o: any) => [number, number, number], root: any): LightNode {
+  const tag = o?.userData?.__tris as SourceTag | undefined;
+  const klass = o?.type ?? o?.constructor?.name ?? 'Light';
+  const light: LightNode = {
+    uuid: String(o?.uuid ?? ''),
+    name: o?.name ?? '',
+    type: klass,
+    lightType: klass,
+    visible: o?.visible !== false,
+    worldPosition: round3(getWP(o)),
+    parentChain: parentChain(o, root),
+  };
+  if (typeof o?.intensity === 'number') light.intensity = +o.intensity.toFixed(3);
+  const color = hexColor(o?.color);
+  if (color) light.color = color;
+  const ground = hexColor(o?.groundColor); // HemisphereLight
+  if (ground) light.groundColor = ground;
+  if (typeof o?.distance === 'number') light.distance = o.distance;
+  if (typeof o?.decay === 'number') light.decay = o.decay;
+  if (typeof o?.angle === 'number') light.angle = +o.angle.toFixed(4); // SpotLight cone
+  if (tag?.source) light.source = tag.source;
+  return light;
+}
+export function triangleCount(o: any): number {
+  const geo = o?.geometry;
+  if (!geo) return 0;
+  try {
+    if (geo.index?.count) return Math.floor(geo.index.count / 3);
+    const pos = geo.attributes?.position;
+    if (pos?.count) return Math.floor(pos.count / 3);
+  } catch {
+    /* exotic geometry — report 0 rather than throw */
+  }
+  return 0;
+}
+function materialColor(mat: any): string | undefined {
+  return hexColor(mat?.color);
+}
+/** A THREE.Color → "#rrggbb", guarded (color access can throw on node materials). */
+function hexColor(c: any): string | undefined {
+  try {
+    if (typeof c?.getHexString === 'function') return `#${c.getHexString()}`;
+  } catch {
+    /* never throw out of introspection */
+  }
+  return undefined;
+}
+function uniformNames(mat: any): string[] {
+  // Legacy materials expose `.uniforms`; TSL node materials keep params in a
+  // private node graph (no stable public surface) — return nothing rather than
+  // reach into internals that change across three versions. Skip textures.
+  try {
+    if (mat?.uniforms && typeof mat.uniforms === 'object') {
+      return Object.keys(mat.uniforms).filter((k) => !mat.uniforms[k]?.value?.isTexture);
+    }
+  } catch {
+    /* never throw out of introspection */
+  }
+  return [];
+}
+function parentChain(o: any, root: any): string[] {
+  const chain: string[] = [];
+  let p = o?.parent;
+  let guard = 0;
+  while (p && p !== root && guard++ < 64) {
+    chain.push(p.name || p.type || p.constructor?.name || 'Object3D');
+    p = p.parent;
+  }
+  return chain.reverse();
+}
+function localPosition(o: any): [number, number, number] {
+  const p = o?.position;
+  if (Array.isArray(p)) return [p[0] ?? 0, p[1] ?? 0, p[2] ?? 0];
+  if (p && typeof p === 'object') return [+(p.x ?? 0), +(p.y ?? 0), +(p.z ?? 0)];
+  return [0, 0, 0];
+}
+function round3(v: [number, number, number]): [number, number, number] {
+  return [+v[0].toFixed(3), +v[1].toFixed(3), +v[2].toFixed(3)];
+}

package/src/scene-registry.ts ADDED Viewed

@@ -0,0 +1,103 @@
+// Pure bookkeeping for a multi-element scene with runtime mount/unmount — the
+// data layer behind runSceneLab + add_element/remove_element. No `three` or DOM
+// here; the harness drives the actual mount/dispose and grid rebuild. Camera +
+// knob keys are namespaced as `<element>.<key>` for multi-element scenes (so two
+// elements declaring `top` don't collide) and left bare for a single
+// non-namespaced lab (backward-compatible with runLab).
+import { autoCameras } from './scene-cameras.js';
+import type { CameraSpec, Element, Knob } from './types.js';
+export interface RegistryEntry {
+  name: string;
+  element: Element;
+}
+export function nsKey(elementName: string, key: string, namespaced: boolean): string {
+  return namespaced ? `${elementName}.${key}` : key;
+}
+export function splitNs(
+  key: string,
+  namespaced: boolean,
+): { element: string | null; local: string } {
+  if (!namespaced) return { element: null, local: key };
+  const i = key.indexOf('.');
+  if (i < 0) return { element: null, local: key };
+  return { element: key.slice(0, i), local: key.slice(i + 1) };
+}
+export interface CameraBinding {
+  spec: CameraSpec;
+  element: string;
+  local: string;
+}
+export interface KnobBinding {
+  spec: Knob;
+  element: string;
+  local: string;
+}
+export function buildCameraMap(
+  active: RegistryEntry[],
+  namespaced: boolean,
+): Record<string, CameraBinding> {
+  const out: Record<string, CameraBinding> = {};
+  for (const { name, element } of active) {
+    const specs =
+      element.cameras === 'auto' ? autoCameras(element.bounds) : (element.cameras ?? {});
+    for (const [local, spec] of Object.entries(specs)) {
+      out[nsKey(name, local, namespaced)] = { spec, element: name, local };
+    }
+  }
+  return out;
+}
+export function buildKnobMap(
+  active: RegistryEntry[],
+  namespaced: boolean,
+): Record<string, KnobBinding> {
+  const out: Record<string, KnobBinding> = {};
+  for (const { name, element } of active) {
+    for (const [local, spec] of Object.entries(element.knobs ?? {})) {
+      out[nsKey(name, local, namespaced)] = { spec, element: name, local };
+    }
+  }
+  return out;
+}
+export interface SceneRegistry {
+  available: () => string[];
+  mounted: () => string[];
+  isMounted: (name: string) => boolean;
+  /** Mark a registered element mounted; returns its entry, or null if unknown/already mounted. */
+  mount: (name: string) => RegistryEntry | null;
+  /** Mark a mounted element unmounted; returns false if it wasn't mounted. */
+  unmount: (name: string) => boolean;
+  /** Mounted entries, in registry declaration order. */
+  activeEntries: () => RegistryEntry[];
+  entry: (name: string) => RegistryEntry | undefined;
+}
+export function createSceneRegistry(entries: RegistryEntry[], initial?: string[]): SceneRegistry {
+  const byName = new Map<string, RegistryEntry>();
+  for (const e of entries) byName.set(e.name, e);
+  const order = entries.map((e) => e.name);
+  const mountedSet = new Set<string>((initial ?? order).filter((n) => byName.has(n)));
+  return {
+    available: () => [...byName.keys()],
+    mounted: () => order.filter((n) => mountedSet.has(n)),
+    isMounted: (name) => mountedSet.has(name),
+    mount: (name) => {
+      if (!byName.has(name) || mountedSet.has(name)) return null;
+      mountedSet.add(name);
+      return byName.get(name) ?? null;
+    },
+    unmount: (name) => {
+      if (!mountedSet.has(name)) return false;
+      mountedSet.delete(name);
+      return true;
+    },
+    activeEntries: () => order.filter((n) => mountedSet.has(n)).map((n) => byName.get(n)!),
+    entry: (name) => byName.get(name),
+  };
+}