@triscope/core 0.4.0

package/src/three-webgpu-shim.d.ts

@@ -0,0 +1,130 @@
+// Minimal ambient declarations for `three` and `three/webgpu`.
+// Three.js does not ship .d.ts files for these entry points as of v0.176.x.
+// Class declarations below give us both value and type bindings for
+// `import * as THREE from 'three/webgpu'`. Members are typed `any` —
+// downstream user code should rely on its own three.js typings if it wants
+// stricter types.
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+declare module 'three/webgpu' {
+  export class WebGPURenderer {
+    constructor(opts?: any);
+    domElement: HTMLCanvasElement;
+    autoClear: boolean;
+    init(): Promise<void>;
+    setSize(w: number, h: number, updateStyle?: boolean): void;
+    setPixelRatio(value: number): void;
+    setClearColor(color: number, alpha?: number): void;
+    setViewport(x: number, y: number, w: number, h: number): void;
+    setScissor(x: number, y: number, w: number, h: number): void;
+    setScissorTest(enable: boolean): void;
+    clear(color?: boolean, depth?: boolean, stencil?: boolean): void;
+    render(scene: any, camera: any): void;
+    getPixelRatio(): number;
+    dispose(): void;
+    [key: string]: any;
+  }
+  export class Scene extends Object3D {
+    background: any;
+    environment: any;
+  }
+  export class PerspectiveCamera {
+    constructor(fov?: number, aspect?: number, near?: number, far?: number);
+    fov: number;
+    aspect: number;
+    near: number;
+    far: number;
+    position: Vector3;
+    quaternion: Quaternion;
+    lookAt(x: number | Vector3, y?: number, z?: number): void;
+    updateProjectionMatrix(): void;
+    [key: string]: any;
+  }
+  export class Object3D {
+    position: Vector3;
+    quaternion: Quaternion;
+    visible: boolean;
+    userData: Record<string, any>;
+    name: string;
+    parent: Object3D | null;
+    children: Object3D[];
+    add(...obj: Object3D[]): this;
+    remove(...obj: Object3D[]): this;
+    traverse(cb: (obj: Object3D) => void): void;
+    [key: string]: any;
+  }
+  export class Group extends Object3D {}
+  export class Vector3 {
+    constructor(x?: number, y?: number, z?: number);
+    x: number;
+    y: number;
+    z: number;
+    set(x: number, y: number, z: number): this;
+    copy(v: Vector3): this;
+    add(v: Vector3): this;
+    sub(v: Vector3): this;
+    clone(): Vector3;
+    length(): number;
+    normalize(): this;
+    multiplyScalar(s: number): this;
+    applyQuaternion(q: Quaternion): this;
+    toArray(): number[];
+  }
+  export class Quaternion {
+    [key: string]: any;
+  }
+  export class Vector2 {
+    constructor(x?: number, y?: number);
+    x: number;
+    y: number;
+    set(x: number, y: number): this;
+  }
+  export class Matrix4 {
+    copy(m: Matrix4): this;
+    [key: string]: any;
+  }
+  export class BufferGeometry {
+    type: string;
+    index: { count: number } | null;
+    attributes: any;
+    [key: string]: any;
+  }
+  export class Mesh extends Object3D {
+    constructor(geometry?: BufferGeometry, material?: any);
+    geometry: BufferGeometry;
+    material: any;
+    isMesh: boolean;
+    matrix: Matrix4;
+    matrixAutoUpdate: boolean;
+    matrixWorld: Matrix4;
+    renderOrder: number;
+    frustumCulled: boolean;
+    updateMatrixWorld(force?: boolean): void;
+    raycast: (raycaster: Raycaster, intersects: any[]) => void;
+  }
+  export class Raycaster {
+    setFromCamera(coords: Vector2, camera: any): void;
+    intersectObjects(objects: Object3D[], recursive?: boolean): Array<{
+      object: Object3D;
+      distance: number;
+      point: Vector3;
+    }>;
+  }
+  export class MeshBasicNodeMaterial {
+    constructor(opts?: any);
+  }
+  export const MOUSE: { ROTATE: any; PAN: any; DOLLY: any };
+  export const TOUCH: { ROTATE: any; PAN: any; DOLLY_PAN: any; DOLLY_ROTATE: any };
+  // Catch-all for everything else we don't enumerate.
+  const _: any;
+  export default _;
+}
+
+declare module 'three' {
+  export * from 'three/webgpu';
+}
+
+declare module 'three/tsl' {
+  const _: any;
+  export = _;
+}

package/src/types.ts

@@ -0,0 +1,121 @@
+import type * as THREE from 'three/webgpu';
+
+/** A position+target camera preset for one pane of the lab grid. */
+export interface CameraSpec {
+  position: [number, number, number];
+  target: [number, number, number];
+  /** Vertical FOV in degrees. Default 45. */
+  fov?: number;
+  /** If true, auto-fit element bounds into the camera frame. */
+  fit?: boolean;
+  /** Near clip. Default 0.1. */
+  near?: number;
+  /** Far clip. Default 2000. */
+  far?: number;
+}
+
+/** A tunable knob exposed to the slider editor and the MCP `set_knob` tool. */
+export type Knob =
+  | { type: 'number'; min: number; max: number; step?: number; default: number; label?: string }
+  | { type: 'int'; min: number; max: number; default: number; label?: string }
+  | { type: 'color'; default: string; label?: string }
+  | { type: 'boolean'; default: boolean; label?: string }
+  /**
+   * Action knob — fires `onKnob(handle, key, true)` each time it's set, but
+   * does NOT persist a value across reloads and does NOT auto-fire on mount.
+   * Use for one-shot triggers (fire cannon, load weapon, request screenshot)
+   * where the act of setting is the signal and there is no "current value".
+   */
+  | { type: 'trigger'; label?: string };
+
+/** Context passed to `Element.mount`. */
+export interface MountContext {
+  renderer: THREE.WebGPURenderer;
+  scene: THREE.Scene;
+  /** Shared time uniform (seconds). Updated each frame by the harness. */
+  time: { value: number };
+  /** dt in seconds, last frame. */
+  dt: { value: number };
+}
+
+/** The handle returned by `Element.mount`. */
+export interface MountHandle {
+  /** The root Object3D the element added to the scene. */
+  root: THREE.Object3D;
+  /** Tear-down hook. Must remove the element from the scene and free GPU resources. */
+  dispose: () => void;
+  /** Element-specific data the telemetry/onKnob callbacks may need. */
+  userData?: Record<string, unknown>;
+}
+
+/**
+ * A self-describing 3D element. The triscope lab harness consumes this
+ * to render a multi-camera grid, drive a tunables UI, post telemetry,
+ * and run the smoke test. Composition is just an element whose `mount`
+ * mounts other elements.
+ */
+export interface Element {
+  name: string;
+  mount: (args: { parent: THREE.Object3D; ctx: MountContext }) => MountHandle;
+  /**
+   * Optional override for the lab page URL. Either a path relative to the
+   * dev server (`/triscope-ship.html`) or a full URL. When set, the harness
+   * publishes it on the manifest so the MCP/CLI can route `capture_views`
+   * and `run_smoke` to the right page without hardcoding `/labs/<name>.html`.
+   */
+  labUrl?: string;
+  /** Local-space bounding box. Used for auto-fitting cameras and the scene framing. */
+  bounds?: { min: [number, number, number]; max: [number, number, number] };
+  /**
+   * Named camera presets — each becomes one pane in the lab grid. Pass the
+   * literal `'auto'` to have the harness synthesize 4 fitted presets
+   * (front/side/top/three-quarter) from `bounds` (see scene-cameras.ts), so an
+   * element doesn't have to hand-author cameras.
+   */
+  cameras: Record<string, CameraSpec> | 'auto';
+  /** Tunable knobs. Rendered as sliders + exposed to MCP `set_knob`. */
+  knobs?: Record<string, Knob>;
+  /** Live-update hook. Called when a knob changes; must apply the change without rebuilding pipelines. */
+  onKnob?: (handle: MountHandle, key: string, value: number | string | boolean) => void;
+  /** Per-frame state to publish via the telemetry sink. Return JSON-serializable values. */
+  telemetry?: (handle: MountHandle, ctx: MountContext) => Record<string, unknown>;
+  /**
+   * Named per-frame numeric probes for animated state. The harness samples each
+   * every frame, keeps a ring buffer (~2 s at 60 fps), and exposes summary stats
+   * under `telemetry.elements.<name>.motion.<probeKey>`:
+   *   { latest, mean, min, max, peakToPeak, samples: lastN }
+   * Use for amplitude (vertex displacement), oscillation rate, particle counts —
+   * anything dynamic the Element wants to quantify.
+   */
+  motionProbes?: Record<string, (handle: MountHandle, ctx: MountContext) => number>;
+  /**
+   * Per-frame discrete-event drain. The harness calls this every frame; the
+   * element returns events that occurred since the last call (typically by
+   * draining an internal queue). The harness appends them to a ring buffer
+   * (cap 128) and exposes them via `telemetry.events`. Use for one-shot
+   * signals like collisions, weapon fires, state transitions — anything the
+   * test script needs to verify a posteriori with `read_telemetry .events`.
+   *
+   * Implementation MUST drain (return + clear) each call: events returned
+   * twice will appear twice in the buffer.
+   */
+  events?: (handle: MountHandle, ctx: MountContext) => TriscopeEvent[];
+}
+
+/** Discrete event emitted by an Element. */
+export interface TriscopeEvent {
+  /** Timestamp in seconds. Should reuse `ctx.time.value` for sim-consistent ordering. */
+  timestamp: number;
+  /** Discriminator — caller-defined (e.g. 'fire' | 'splash' | 'impact'). */
+  type: string;
+  /** Optional opaque payload — anything JSON-serializable. */
+  payload?: Record<string, unknown>;
+}
+
+/** Default value extracted from a knob spec. Trigger knobs have no
+ * default — they are pure action signals; this returns `false` only as a
+ * placeholder so callers iterating knob values get a defined entry. */
+export function knobDefault(k: Knob): number | string | boolean {
+  if (k.type === 'trigger') return false;
+  return k.default;
+}

package/src/uniform-access.ts

@@ -0,0 +1,152 @@
+/**
+ * Pure live-uniform read/write by path — the data layer behind read_uniform /
+ * set_uniform. Lets an agent probe or nudge ANY material uniform / material
+ * property / object property (e.g. a shader uniform that was never declared as
+ * a knob, or `sun.intensity`) without a source edit + reload. Duck-typed (no
+ * `three` import) so it's unit-testable; the harness passes the live scene.
+ *
+ * Path format: "<objectName|uuid>.<key>" — split on the LAST dot, so dotted
+ * object names still work and the trailing segment is the uniform/property key.
+ * Writes are TRANSIENT (live only, not persisted via /__knob).
+ */
+
+export interface UniformReadResult {
+  kind: 'uniform' | 'material-property' | 'object-property' | 'not-found';
+  path: string;
+  value?: unknown;
+  error?: string;
+}
+
+export interface UniformWriteResult {
+  ok: boolean;
+  kind: 'uniform' | 'material-property' | 'object-property' | 'not-found';
+  path: string;
+  previous?: unknown;
+  current?: unknown;
+  error?: string;
+}
+
+export function parseUniformPath(path: string): { objectId: string; key: string } {
+  const i = path.lastIndexOf('.');
+  if (i < 0) return { objectId: path, key: '' };
+  return { objectId: path.slice(0, i), key: path.slice(i + 1) };
+}
+
+function findObject(root: any, id: string): any {
+  if (!root) return null;
+  const stack = [root];
+  let guard = 0;
+  while (stack.length && guard++ < 100000) {
+    const o = stack.pop();
+    if (o?.name === id || o?.uuid === id) return o;
+    const kids = o?.children;
+    if (Array.isArray(kids)) for (let i = kids.length - 1; i >= 0; i--) stack.push(kids[i]);
+  }
+  return null;
+}
+
+/** Locate where a key's value lives: a legacy uniform slot, a material prop, or an object prop. */
+function locateSlot(
+  obj: any,
+  key: string,
+): {
+  kind: 'uniform' | 'material-property' | 'object-property';
+  container: any;
+  prop: string;
+} | null {
+  if (!key) return null;
+  const mat = Array.isArray(obj?.material) ? obj.material[0] : obj?.material;
+  try {
+    if (mat?.uniforms && typeof mat.uniforms === 'object' && mat.uniforms[key] !== undefined) {
+      return { kind: 'uniform', container: mat.uniforms[key], prop: 'value' };
+    }
+  } catch {
+    /* fall through */
+  }
+  if (mat && key in mat) return { kind: 'material-property', container: mat, prop: key };
+  if (obj && key in obj) return { kind: 'object-property', container: obj, prop: key };
+  return null;
+}
+
+/** Bound, JSON-safe serialization of a slot value (Color→hex, Vector→array, texture→tag). */
+function serializeVal(v: any): unknown {
+  if (v === null || v === undefined) return null;
+  const t = typeof v;
+  if (t === 'number' || t === 'string' || t === 'boolean') return v;
+  try {
+    if (v.isTexture || v.image || v.source) return '[texture]';
+    if (typeof v.getHexString === 'function') return `#${v.getHexString()}`;
+    if (typeof v.x === 'number' && typeof v.y === 'number') {
+      const out = [v.x, v.y];
+      if (typeof v.z === 'number') out.push(v.z);
+      if (typeof v.w === 'number') out.push(v.w);
+      return out;
+    }
+  } catch {
+    /* exotic value — fall through */
+  }
+  return '[object]';
+}
+
+export function readUniformValue(root: any, path: string): UniformReadResult {
+  const { objectId, key } = parseUniformPath(path);
+  const obj = findObject(root, objectId);
+  if (!obj) return { kind: 'not-found', path, error: `no object named/uuid "${objectId}"` };
+  const slot = locateSlot(obj, key);
+  if (!slot)
+    return { kind: 'not-found', path, error: `no uniform/property "${key}" on "${objectId}"` };
+  return { kind: slot.kind, path, value: serializeVal(slot.container[slot.prop]) };
+}
+
+export function writeUniformValue(root: any, path: string, value: unknown): UniformWriteResult {
+  const { objectId, key } = parseUniformPath(path);
+  const obj = findObject(root, objectId);
+  if (!obj)
+    return { ok: false, kind: 'not-found', path, error: `no object named/uuid "${objectId}"` };
+  const slot = locateSlot(obj, key);
+  if (!slot)
+    return {
+      ok: false,
+      kind: 'not-found',
+      path,
+      error: `no uniform/property "${key}" on "${objectId}"`,
+    };
+  const previous = serializeVal(slot.container[slot.prop]);
+  try {
+    const cur = slot.container[slot.prop];
+    if (cur && typeof cur.getHexString === 'function' && typeof cur.set === 'function') {
+      cur.set(value as string | number); // THREE.Color — accepts '#hex' or number
+    } else if (
+      cur &&
+      typeof cur.set === 'function' &&
+      typeof cur.x === 'number' &&
+      Array.isArray(value)
+    ) {
+      cur.set(...(value as number[])); // THREE.Vector*
+    } else if (typeof cur === 'number') {
+      // Coerce to the slot's existing type so a "6.0" from a loosely-typed tool
+      // call doesn't silently store a STRING (it would work by accident in
+      // arithmetic but read back as the wrong type and break strict consumers).
+      slot.container[slot.prop] = Number(value);
+    } else if (typeof cur === 'boolean') {
+      slot.container[slot.prop] = value === true || value === 'true';
+    } else {
+      slot.container[slot.prop] = value;
+    }
+  } catch (e) {
+    return {
+      ok: false,
+      kind: slot.kind,
+      path,
+      previous,
+      error: String((e as { message?: unknown })?.message ?? e),
+    };
+  }
+  return {
+    ok: true,
+    kind: slot.kind,
+    path,
+    previous,
+    current: serializeVal(slot.container[slot.prop]),
+  };
+}

package/src/validate.ts

@@ -0,0 +1,82 @@
+// Pure Element-contract validation. The harness runs this before mount so a
+// malformed element surfaces a precise, actionable error in telemetry warnings
+// + the boot overlay, instead of a cryptic "harness not mounted within 10s".
+
+const KNOB_TYPES = new Set(['number', 'int', 'color', 'boolean', 'trigger']);
+
+export function validateElement(el: any): string[] {
+  const problems: string[] = [];
+  if (!el || typeof el !== 'object') {
+    return ['element is not an object'];
+  }
+  if (typeof el.name !== 'string' || el.name.length === 0) {
+    problems.push('element.name must be a non-empty string');
+  }
+  if (typeof el.mount !== 'function') {
+    problems.push('element.mount must be a function');
+  }
+  // `cameras: 'auto'` is valid — the harness synthesizes fitted presets from
+  // bounds (runSceneView's default), so it must NOT trip the "declare a camera"
+  // warning (which would pollute read_telemetry .warnings on every boot).
+  if (el.cameras === 'auto') {
+    /* ok */
+  } else if (
+    !el.cameras ||
+    typeof el.cameras !== 'object' ||
+    Object.keys(el.cameras).length === 0
+  ) {
+    problems.push("element.cameras must declare at least one named camera (or 'auto')");
+  } else {
+    for (const [name, spec] of Object.entries(el.cameras as Record<string, any>)) {
+      if (!isVec3(spec?.position) || !isVec3(spec?.target)) {
+        problems.push(`camera "${name}" needs position[3] and target[3]`);
+      }
+    }
+  }
+  if (el.knobs !== undefined) {
+    if (typeof el.knobs !== 'object' || el.knobs === null) {
+      problems.push('element.knobs must be an object');
+    } else {
+      for (const [key, k] of Object.entries(el.knobs as Record<string, any>)) {
+        if (!k || !KNOB_TYPES.has(k.type)) {
+          problems.push(`knob "${key}" has an unknown type "${k?.type}"`);
+          continue;
+        }
+        if (
+          (k.type === 'number' || k.type === 'int') &&
+          (typeof k.min !== 'number' || typeof k.max !== 'number')
+        ) {
+          problems.push(`knob "${key}" (${k.type}) needs numeric min and max`);
+        }
+        if ((k.type === 'number' || k.type === 'int') && typeof k.default !== 'number') {
+          problems.push(`knob "${key}" (${k.type}) needs a numeric default`);
+        }
+        if (k.type === 'color' && typeof k.default !== 'string') {
+          problems.push(`knob "${key}" (color) needs a string default`);
+        }
+        if (k.type === 'boolean' && typeof k.default !== 'boolean') {
+          problems.push(`knob "${key}" (boolean) needs a boolean default`);
+        }
+      }
+    }
+  }
+  for (const hook of ['onKnob', 'telemetry', 'events'] as const) {
+    if (el[hook] !== undefined && typeof el[hook] !== 'function') {
+      problems.push(`element.${hook} must be a function if present`);
+    }
+  }
+  if (el.motionProbes !== undefined) {
+    if (typeof el.motionProbes !== 'object' || el.motionProbes === null) {
+      problems.push('element.motionProbes must be an object of functions');
+    } else {
+      for (const [key, fn] of Object.entries(el.motionProbes as Record<string, any>)) {
+        if (typeof fn !== 'function') problems.push(`motionProbe "${key}" must be a function`);
+      }
+    }
+  }
+  return problems;
+}
+
+function isVec3(v: unknown): boolean {
+  return Array.isArray(v) && v.length === 3 && v.every((n) => typeof n === 'number');
+}

package/src/vite.ts

@@ -0,0 +1,5 @@
+// Node-only entry. Vite plugin + helpers that touch the filesystem.
+// Import this from your `vite.config.{js,ts}`, never from browser code.
+
+export type { TelemetryPaths } from './telemetry.js';
+export { resolveTelemetryPaths, triscopeTelemetryPlugin } from './telemetry.js';

package/src/warnings.ts

@@ -0,0 +1,41 @@
+/** One non-fatal failure the harness swallowed but wants the agent to see. */
+export interface WarningEntry {
+  /** Wall-clock ms when recorded. */
+  ts: number;
+  /** Where it came from: 'postState' | 'postManifest' | 'pollKnobs' | 'telemetry-fn' | 'motion-probe' | 'event-drain' | 'black-frame' | 'knob-clamp' | … */
+  source: string;
+  /** Short human-readable summary. */
+  message: string;
+  /** Optional extra context (stack tail, value, …). */
+  detail?: string;
+}
+
+export interface WarningRing {
+  push: (source: string, message: string, detail?: string) => void;
+  list: () => WarningEntry[];
+  readonly size: number;
+}
+
+/**
+ * Bounded ring of recent swallowed failures, surfaced via telemetry `.warnings`
+ * so an agent can answer "why is telemetry stale / the knob not applying / this
+ * pane black?" with a `read_telemetry .warnings` call instead of guessing. The
+ * harness wires this into the `.catch(()=>{})` sites that used to fail silently.
+ */
+export function createWarningRing(cap = 32, now: () => number = () => Date.now()): WarningRing {
+  const buf: WarningEntry[] = [];
+  return {
+    push(source: string, message: string, detail?: string): void {
+      const entry: WarningEntry = { ts: now(), source, message };
+      if (detail !== undefined) entry.detail = detail;
+      buf.push(entry);
+      if (buf.length > cap) buf.shift();
+    },
+    list(): WarningEntry[] {
+      return buf.slice();
+    },
+    get size(): number {
+      return buf.length;
+    },
+  };
+}