@triscope/core 0.4.0

package/src/scene-view.ts

@@ -0,0 +1,204 @@
+// runSceneView — the near-zero-boilerplate adoption entry. Wrap ANY existing
+// THREE.Object3D (or a builder, or a {root,dispose} handle) into the triscope
+// harness so the MCP tools (capture_views/inspect_scene/read_uniform/set_uniform
+// + knobs) work, WITHOUT hand-authoring an Element. Cameras auto-fit from the
+// object's bounds; optionally auto-derive knobs from its materials/lights.
+//
+//   import { runSceneView } from '@triscope/core';
+//   runSceneView(myGroup);                 // read-only observability, ~1 line
+//   runSceneView(buildScene, { autoKnobs: true });
+import * as THREE from 'three/webgpu';
+import { type CommonLabOptions, type LabHandle, runLab } from './harness.js';
+import { mountLabDom } from './lab/dom.js';
+import { autoCameras, type Bounds, UNIT_BOUNDS } from './scene-cameras.js';
+import type { CameraSpec, Element, Knob, MountHandle } from './types.js';
+import { writeUniformValue } from './uniform-access.js';
+
+/** A target the harness can render: an object, a builder, or a mounted handle. */
+export type SceneViewTarget =
+  | THREE.Object3D
+  | (() => THREE.Object3D | { root: THREE.Object3D; dispose?: () => void })
+  | { root: THREE.Object3D; dispose?: () => void };
+
+export interface SceneViewOptions extends Partial<CommonLabOptions> {
+  /** Element name (telemetry `project`). Defaults to the object's `.name` or "scene". */
+  name?: string;
+  /** Camera presets, or 'auto' (default) to fit 4 presets from the object's bounds. */
+  cameras?: Record<string, CameraSpec> | 'auto';
+  /** Explicit knobs (merged over autoKnobs when both are present). */
+  knobs?: Record<string, Knob>;
+  /** Knob handler. Defaults to the autoKnobs router when autoKnobs is on. */
+  onKnob?: Element['onKnob'];
+  /**
+   * Reflect named meshes' material props (roughness/metalness/opacity/color/
+   * emissive) and named lights' intensity/color into knobs, routed live via the
+   * same path as set_uniform. NOTE: only NAMED objects; TSL node-material params
+   * aren't reflectable (use set_uniform for those). Off by default.
+   */
+  autoKnobs?: boolean;
+}
+
+/**
+ * World-space AABB of an object tree → {min,max}; unit box if empty/non-finite.
+ * Computed manually (8 corners of each child geometry's bounding box × its world
+ * matrix) to avoid depending on Box3, which three/webgpu's .d.ts doesn't surface.
+ */
+export function computeObjectBounds(obj: THREE.Object3D): Bounds {
+  try {
+    obj.updateWorldMatrix(true, true);
+    const min = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
+    const max = [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY];
+    let found = false;
+    const v = new THREE.Vector3();
+    obj.traverse((o: any) => {
+      const geo = o?.geometry;
+      if (!geo) return;
+      if (!geo.boundingBox && typeof geo.computeBoundingBox === 'function')
+        geo.computeBoundingBox();
+      const bb = geo.boundingBox;
+      if (!bb) return;
+      for (let i = 0; i < 8; i++) {
+        v.set(
+          i & 1 ? bb.max.x : bb.min.x,
+          i & 2 ? bb.max.y : bb.min.y,
+          i & 4 ? bb.max.z : bb.min.z,
+        );
+        // applyMatrix4 is missing from three/webgpu's partial .d.ts (runtime ok).
+        // biome-ignore lint/suspicious/noExplicitAny: three/webgpu .d.ts gap
+        (v as any).applyMatrix4(o.matrixWorld);
+        if (!Number.isFinite(v.x) || !Number.isFinite(v.y) || !Number.isFinite(v.z)) continue;
+        min[0] = Math.min(min[0], v.x);
+        min[1] = Math.min(min[1], v.y);
+        min[2] = Math.min(min[2], v.z);
+        max[0] = Math.max(max[0], v.x);
+        max[1] = Math.max(max[1], v.y);
+        max[2] = Math.max(max[2], v.z);
+        found = true;
+      }
+    });
+    if (!found) return UNIT_BOUNDS;
+    return { min: [min[0], min[1], min[2]], max: [max[0], max[1], max[2]] };
+  } catch {
+    return UNIT_BOUNDS;
+  }
+}
+
+/**
+ * Derive knobs by reflecting an object tree's NAMED materials + lights. Returns
+ * the knob specs + an onKnob that applies them live via writeUniformValue (the
+ * exact path set_uniform uses, so "name.prop" addressing matches).
+ * NOTE: an `opacity` knob has no visible effect on a material without
+ * `transparent: true` (Three.js ignores opacity on opaque materials).
+ */
+export function autoKnobsFromObject(root: THREE.Object3D): {
+  knobs: Record<string, Knob>;
+  onKnob: (handle: MountHandle, key: string, value: number | string | boolean) => void;
+} {
+  const knobs: Record<string, Knob> = {};
+  const hex = (c: any): string | undefined => {
+    try {
+      return typeof c?.getHexString === 'function' ? `#${c.getHexString()}` : undefined;
+    } catch {
+      return undefined;
+    }
+  };
+  root.traverse((o: any) => {
+    const name = o?.name;
+    if (!name || typeof name !== 'string') return; // only addressable (named) objects
+    if (o.isLight) {
+      if (typeof o.intensity === 'number') {
+        knobs[`${name}.intensity`] = {
+          type: 'number',
+          min: 0,
+          max: Math.max(o.intensity * 3, 5),
+          step: 0.01,
+          default: o.intensity,
+        };
+      }
+      const lc = hex(o.color);
+      if (lc) knobs[`${name}.color`] = { type: 'color', default: lc };
+      return;
+    }
+    const mat = Array.isArray(o.material) ? o.material[0] : o.material;
+    if (!mat) return;
+    for (const p of ['roughness', 'metalness', 'opacity'] as const) {
+      if (typeof mat[p] === 'number') {
+        knobs[`${name}.${p}`] = { type: 'number', min: 0, max: 1, step: 0.01, default: mat[p] };
+      }
+    }
+    for (const p of ['color', 'emissive'] as const) {
+      const mc = hex(mat[p]);
+      if (mc) knobs[`${name}.${p}`] = { type: 'color', default: mc };
+    }
+  });
+  const onKnob = (handle: MountHandle, key: string, value: number | string | boolean): void => {
+    if (handle?.root) writeUniformValue(handle.root, key, value);
+  };
+  return { knobs, onKnob };
+}
+
+function resolveTarget(target: SceneViewTarget): {
+  obj: THREE.Object3D;
+  dispose?: () => void;
+} {
+  const t = typeof target === 'function' ? target() : target;
+  if (t && (t as any).isObject3D) return { obj: t as THREE.Object3D };
+  if (t && (t as any).root?.isObject3D) {
+    return { obj: (t as any).root, dispose: (t as any).dispose };
+  }
+  throw new Error(
+    'runSceneView: target must be a THREE.Object3D, a () => Object3D, or a { root, dispose } handle',
+  );
+}
+
+/**
+ * Boot a triscope lab around an existing object with (near) zero boilerplate.
+ * Returns the same LabHandle as runLab.
+ */
+export async function runSceneView(
+  target: SceneViewTarget,
+  opts: SceneViewOptions = {},
+): Promise<LabHandle> {
+  const { obj, dispose: targetDispose } = resolveTarget(target);
+  // Build the DOM if no canvas was supplied (a bare <body> + script is enough).
+  const dom = opts.canvas ? null : mountLabDom();
+  const canvas = opts.canvas ?? dom?.canvas;
+  if (!canvas) throw new Error('runSceneView: no canvas (and DOM creation unavailable)');
+
+  const auto = opts.autoKnobs
+    ? autoKnobsFromObject(obj)
+    : { knobs: {} as Record<string, Knob>, onKnob: undefined };
+  const knobs = { ...auto.knobs, ...(opts.knobs ?? {}) };
+
+  const element: Element = {
+    name: opts.name ?? obj.name ?? 'scene',
+    bounds: computeObjectBounds(obj),
+    cameras: opts.cameras ?? 'auto',
+    knobs: Object.keys(knobs).length ? knobs : undefined,
+    onKnob: opts.onKnob ?? auto.onKnob,
+    mount: ({ parent }) => {
+      parent.add(obj);
+      return {
+        root: obj,
+        dispose: () => {
+          parent.remove(obj);
+          targetDispose?.();
+        },
+        userData: {},
+      };
+    },
+  };
+
+  return runLab({
+    element,
+    canvas,
+    hud: dom?.hud ?? opts.hud ?? null,
+    labelContainer: dom?.labelContainer ?? opts.labelContainer ?? null,
+    editorContainer: dom?.editorContainer ?? opts.editorContainer ?? null,
+    bootOverlay: dom?.boot ?? opts.bootOverlay ?? null,
+    clearColor: opts.clearColor,
+    captureSize: opts.captureSize,
+    telemetryIntervalMs: opts.telemetryIntervalMs,
+    knobPollMs: opts.knobPollMs,
+  });
+}

package/src/source-tag.ts

@@ -0,0 +1,139 @@
+/**
+ * Auto source-tag for the scene graph.
+ *
+ * Monkey-patches THREE.Object3D.prototype.add exactly once so every object
+ * added to a scene gets a userData.__tris record containing the user
+ * source frame (file:line + fn name from V8 stack), the object class, the
+ * geometry class, and a material hint.
+ *
+ * Element authors do not call anything. The tag appears on every mesh
+ * added via .add(), Three's standard pattern. The picker in inspect.ts
+ * reads this back when the user clicks, so we map "this pixel on screen"
+ * to "this exact line in your code" without grep.
+ *
+ * Stack parsing skips any frame inside three/, @triscope/, or
+ * node_modules/. In vite dev mode the stack is already source-mapped,
+ * resolving to original .ts source files. Production minified builds
+ * lose the precision but triscope is dev-only.
+ */
+import * as THREE from 'three/webgpu';
+
+export interface SourceFrame {
+  file: string;
+  line: number;
+  col: number;
+  fn?: string;
+}
+
+export interface SourceTag {
+  source: SourceFrame | null;
+  stack: SourceFrame[];
+  type: string;
+  geometry?: string;
+  material?: { color?: string; map?: string | null };
+  name?: string;
+  /**
+   * Names of ancestor objects in the scene tree, root-first. Populated
+   * lazily when the picker reads the tag (parents may change after
+   * .add() if the user re-parents). Useful as a tie-breaker when the
+   * source-line attribution drifts (see note below).
+   */
+  parentChain?: string[];
+}
+
+/**
+ * Note on line accuracy: in browser dev mode, `new Error().stack` returns
+ * positions in the file as vite served it (after esbuild's TS-to-JS
+ * transform). Vite tries to preserve line counts but TSL `Fn(([uv]) => …)`
+ * blocks and other complex constructions can drift by tens of lines.
+ * The captured line is therefore "approximate" — close enough for
+ * `code --goto` to land in the right neighborhood, but verify visually
+ * (or use `parentChain` + `geometry` + `material.color` as cross-checks)
+ * before assuming it's exact.
+ */
+
+let patched = false;
+
+export function installSourceTagPatch(): boolean {
+  if (patched) return false;
+  patched = true;
+  const origAdd = THREE.Object3D.prototype.add;
+  THREE.Object3D.prototype.add = function (...children: THREE.Object3D[]) {
+    let stack: SourceFrame[] = [];
+    try {
+      const raw = new Error().stack ?? '';
+      stack = parseUserStack(raw);
+    } catch {
+      /* stack capture is best-effort */
+    }
+    const source = stack[0] ?? null;
+    for (const child of children) {
+      if (!child) continue;
+      const prior = child.userData?.__tris as SourceTag | undefined;
+      if (prior && prior.source) continue;
+      const tag: SourceTag = {
+        source,
+        stack,
+        type: child.constructor.name,
+      };
+      const asMesh = child as THREE.Mesh;
+      if (asMesh.geometry) tag.geometry = asMesh.geometry.type;
+      if (asMesh.material) tag.material = extractMaterialHint(asMesh.material);
+      if (child.name) tag.name = child.name;
+      child.userData = child.userData ?? {};
+      (child.userData as Record<string, unknown>).__tris = tag;
+    }
+    return origAdd.apply(this, children);
+  } as typeof origAdd;
+  return true;
+}
+
+export const FRAME_RE = /at (?:(?<fn>[^(]+?) \()?(?<url>[^()]+?):(?<line>\d+):(?<col>\d+)\)?$/;
+
+export const SKIP_PATTERNS = [
+  /\/node_modules\//,
+  /\/three\//,
+  /\/@triscope\//,
+  /\/triscope\/packages\//,
+  /\/(harness|source-tag|inspect|editor|telemetry)\.[jt]sx?/,
+  /^node:/,
+  /^(?:webpack|vite):/,
+];
+
+export function parseUserStack(raw: string, max = 8): SourceFrame[] {
+  const out: SourceFrame[] = [];
+  for (const lineStr of raw.split('\n')) {
+    const m = FRAME_RE.exec(lineStr.trim());
+    if (!m?.groups) continue;
+    const url = stripUrl(m.groups.url);
+    if (SKIP_PATTERNS.some((p) => p.test(url))) continue;
+    out.push({
+      file: url,
+      line: Number(m.groups.line),
+      col: Number(m.groups.col),
+      fn: m.groups.fn || undefined,
+    });
+    if (out.length >= max) break;
+  }
+  return out;
+}
+
+export function stripUrl(u: string): string {
+  return u.replace(/[?#].*$/, '');
+}
+
+export function extractMaterialHint(material: unknown): { color?: string; map?: string | null } {
+  const m = material as {
+    color?: { getHexString?: () => string };
+    map?: { name?: string; source?: { data?: { src?: string } } };
+  };
+  const hint: { color?: string; map?: string | null } = {};
+  try {
+    if (m?.color?.getHexString) hint.color = '#' + m.color.getHexString();
+  } catch {}
+  try {
+    const tex = m?.map;
+    if (tex) hint.map = tex.name || tex.source?.data?.src || null;
+  } catch {}
+  return hint;
+}

package/src/telemetry.ts

@@ -0,0 +1,337 @@
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import type { Plugin } from 'vite';
+
+interface TelemetryOptions {
+  /**
+   * Project name used to namespace state files in /tmp.
+   * Defaults to the name in package.json (sanitized).
+   */
+  project?: string;
+  /** Override state file path. */
+  statePath?: string;
+  /** Override log file path. */
+  logPath?: string;
+  /**
+   * Regex matching files that need a full-reload (instead of HMR) when they
+   * change. Default catches TSL material / mesh / element / shader sources,
+   * because vite HMR cannot remount a THREE.Material already in the scene.
+   * Pass `null` to disable.
+   */
+  forceReloadOn?: RegExp | null;
+}
+
+/**
+ * Read a request body to a string with a hard timeout. A broken/slow client
+ * could otherwise hold a Vite middleware slot open indefinitely (the original
+ * readBody had data/end/error listeners but no timeout). On timeout we destroy
+ * the socket so the slot is freed, and reject so the route returns 400.
+ * Override the budget with TRISCOPE_READBODY_TIMEOUT_MS.
+ */
+export function readRequestBody(
+  req: {
+    on: (event: string, cb: (arg: never) => void) => void;
+    socket?: { destroy?: () => void };
+  },
+  timeoutMs: number = Number(process.env.TRISCOPE_READBODY_TIMEOUT_MS ?? 10000),
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    let done = false;
+    const timer = setTimeout(() => {
+      if (done) return;
+      done = true;
+      try {
+        req.socket?.destroy?.();
+      } catch {
+        /* best-effort */
+      }
+      reject(new Error(`request body read timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    // Don't let a pending read keep the process alive.
+    (timer as { unref?: () => void }).unref?.();
+    req.on('data', (c: never) => {
+      body += c;
+    });
+    req.on('end', () => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve(body);
+    });
+    req.on('error', (e: never) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      reject(e as unknown as Error);
+    });
+  });
+}
+
+function readProjectLabs(cwd: string): Record<string, string> {
+  try {
+    const p = join(cwd, 'package.json');
+    if (!existsSync(p)) return {};
+    const pkg = JSON.parse(readFileSync(p, 'utf8'));
+    const labs = pkg?.triscope?.labs;
+    if (labs && typeof labs === 'object') {
+      const out: Record<string, string> = {};
+      for (const [k, v] of Object.entries(labs)) {
+        if (typeof v === 'string') out[k] = v;
+      }
+      return out;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+function readPackageName(cwd: string): string {
+  try {
+    const p = join(cwd, 'package.json');
+    if (!existsSync(p)) return 'triscope-project';
+    const pkg = JSON.parse(readFileSync(p, 'utf8'));
+    return String(pkg.name ?? 'triscope-project').replace(/[^A-Za-z0-9._-]/g, '-');
+  } catch {
+    return 'triscope-project';
+  }
+}
+
+/**
+ * Vite plugin that wires the telemetry sink:
+ *
+ *   POST /__state    → writes /tmp/<project>-state.json + appends to /tmp/<project>-state.log
+ *   GET  /__state    → returns the latest snapshot
+ *   POST /__knob     → stores a pending knob change for the harness to consume
+ *   GET  /__knob     → returns and CLEARS the pending knob queue (polled by harness)
+ *   GET  /__manifest → returns the registered element manifest (POSTed by harness on boot)
+ *   POST /__manifest → harness pushes the live manifest (elements/cameras/knobs)
+ *
+ * The names start with __ so they cannot collide with user routes.
+ */
+export function triscopeTelemetryPlugin(opts: TelemetryOptions = {}): Plugin {
+  const project = opts.project ?? readPackageName(process.cwd());
+  const statePath = opts.statePath ?? join(tmpdir(), `${project}-state.json`);
+  const logPath = opts.logPath ?? join(tmpdir(), `${project}-state.log`);
+
+  // In-memory pending knob queue. Harness polls and drains.
+  const pendingKnobs: Array<{ element: string; key: string; value: unknown }> = [];
+  // Persisted knob state per element. Survives the harness's full-reload so
+  // the harness can re-hydrate to the last user-applied values instead of
+  // snapping back to spec defaults. Updated on every POST /__knob, read by
+  // the harness via GET /__knob/current on boot.
+  const lastKnobValues: Record<string, Record<string, unknown>> = {};
+  // SDL (set_scene_param): pending camera/knob deltas the harness drains via
+  // GET /__scene, plus the merged persisted scene state for re-hydration on
+  // reload (GET /__scene/current). Mirrors the /__knob pattern.
+  const pendingScene: Array<Record<string, unknown>> = [];
+  const lastSceneState: { cameras: Record<string, unknown>; knobs: Record<string, unknown> } = {
+    cameras: {},
+    knobs: {},
+  };
+  // Manifest is a map keyed by element name so multiple labs can co-exist —
+  // each harness POSTs its own entry on boot.
+  const manifestByElement: Record<string, unknown> = {};
+  // Pre-seed with package.json#triscope.labs so MCP capture_views works on
+  // the very first call (before any browser tab loads a lab).
+  for (const [name, labUrl] of Object.entries(readProjectLabs(process.cwd()))) {
+    manifestByElement[name] = { element: name, labUrl };
+  }
+  const forceReloadOn =
+    opts.forceReloadOn === null
+      ? null
+      : (opts.forceReloadOn ?? /(\.tsl|Element|Mesh|Material|Shader)\.(ts|tsx|js|mjs)$/i);
+
+  return {
+    name: 'triscope-telemetry',
+    configureServer(server) {
+      mkdirSync(dirname(statePath), { recursive: true });
+      // Clear last session's telemetry on dev-server boot so a previously-open
+      // lab's elements don't linger as phantoms (the POST /__state merge is for
+      // multiple tabs in the SAME session — it has no cross-session expiry).
+      // The harness re-POSTs on mount, so a live tab repopulates immediately.
+      try {
+        rmSync(statePath, { force: true });
+      } catch {
+        /* best-effort — a stale file just merges as before */
+      }
+
+      const readBody = (req: any): Promise<string> => readRequestBody(req);
+
+      server.middlewares.use('/__state', async (req, res, next) => {
+        if (!req.method) return next();
+        try {
+          if (req.method === 'POST') {
+            const body = await readBody(req);
+            const payload = JSON.parse(body);
+            // Merge the elements map across labs so two tabs on different
+            // lab pages don't clobber each other's telemetry. Top-level
+            // fields (perf/time/cameras) still reflect the last writer
+            // since they're per-tab — that's expected when read_telemetry
+            // is project-scoped, not lab-scoped.
+            let merged: any = payload;
+            try {
+              if (existsSync(statePath)) {
+                const existing = JSON.parse(readFileSync(statePath, 'utf8'));
+                merged = {
+                  ...payload,
+                  elements: { ...(existing?.elements ?? {}), ...(payload?.elements ?? {}) },
+                };
+              }
+            } catch {
+              /* corrupt file — overwrite with the new payload */
+            }
+            writeFileSync(statePath, JSON.stringify(merged, null, 2));
+            const ts = new Date().toISOString();
+            const fps = (payload?.perf?.fps as number | undefined)?.toFixed?.(0) ?? '?';
+            const cam = (payload?.activeCamera as string | undefined) ?? '?';
+            appendFileSync(logPath, `${ts} fps=${fps} cam=${cam}\n`);
+            res.statusCode = 200;
+            return res.end('ok');
+          }
+          if (req.method === 'GET') {
+            res.setHeader('content-type', 'application/json');
+            return res.end(existsSync(statePath) ? readFileSync(statePath) : '{}');
+          }
+        } catch (err) {
+          res.statusCode = 400;
+          return res.end(String(err));
+        }
+        return next();
+      });
+
+      server.middlewares.use('/__knob', async (req, res, next) => {
+        if (!req.method) return next();
+        try {
+          // GET /__knob/current → persisted state (sub-path on the same prefix).
+          if (req.method === 'GET' && (req.url ?? '').startsWith('/current')) {
+            res.setHeader('content-type', 'application/json');
+            return res.end(JSON.stringify(lastKnobValues));
+          }
+          if (req.method === 'POST') {
+            const body = await readBody(req);
+            const payload = JSON.parse(body);
+            const updates: Array<{ element?: string; key?: string; value?: unknown }> =
+              Array.isArray(payload) ? payload : [payload];
+            for (const u of updates) {
+              if (typeof u?.element === 'string' && typeof u?.key === 'string') {
+                lastKnobValues[u.element] ??= {};
+                lastKnobValues[u.element][u.key] = u.value;
+              }
+            }
+            pendingKnobs.push(...(updates as typeof pendingKnobs));
+            res.statusCode = 200;
+            return res.end('ok');
+          }
+          if (req.method === 'GET') {
+            res.setHeader('content-type', 'application/json');
+            const drained = pendingKnobs.splice(0, pendingKnobs.length);
+            return res.end(JSON.stringify(drained));
+          }
+        } catch (err) {
+          res.statusCode = 400;
+          return res.end(String(err));
+        }
+        return next();
+      });
+
+      server.middlewares.use('/__scene', async (req, res, next) => {
+        if (!req.method) return next();
+        try {
+          // GET /__scene/current → merged persisted scene state (re-hydration).
+          if (req.method === 'GET' && (req.url ?? '').startsWith('/current')) {
+            res.setHeader('content-type', 'application/json');
+            return res.end(JSON.stringify(lastSceneState));
+          }
+          if (req.method === 'POST') {
+            const body = await readBody(req);
+            const delta = JSON.parse(body) as {
+              cameras?: Record<string, Record<string, unknown>>;
+              knobs?: Record<string, unknown>;
+            };
+            // Merge into the persisted state so a reload re-applies it.
+            if (delta?.cameras && typeof delta.cameras === 'object') {
+              for (const [n, c] of Object.entries(delta.cameras)) {
+                lastSceneState.cameras[n] = { ...(lastSceneState.cameras[n] as object), ...c };
+              }
+            }
+            if (delta?.knobs && typeof delta.knobs === 'object') {
+              for (const [k, v] of Object.entries(delta.knobs)) lastSceneState.knobs[k] = v;
+            }
+            pendingScene.push(delta);
+            res.statusCode = 200;
+            return res.end('ok');
+          }
+          if (req.method === 'GET') {
+            res.setHeader('content-type', 'application/json');
+            const drained = pendingScene.splice(0, pendingScene.length);
+            return res.end(JSON.stringify(drained));
+          }
+        } catch (err) {
+          res.statusCode = 400;
+          return res.end(String(err));
+        }
+        return next();
+      });
+
+      server.middlewares.use('/__manifest', async (req, res, next) => {
+        if (!req.method) return next();
+        try {
+          if (req.method === 'POST') {
+            const body = await readBody(req);
+            const payload = JSON.parse(body) as { element?: string } & Record<string, unknown>;
+            if (payload?.element && typeof payload.element === 'string') {
+              manifestByElement[payload.element] = payload;
+            }
+            res.statusCode = 200;
+            return res.end('ok');
+          }
+          if (req.method === 'GET') {
+            res.setHeader('content-type', 'application/json');
+            return res.end(JSON.stringify({ elements: manifestByElement }));
+          }
+        } catch (err) {
+          res.statusCode = 400;
+          return res.end(String(err));
+        }
+        return next();
+      });
+    },
+    handleHotUpdate({ file, server }) {
+      // TSL materials (and any code that ends up baked into the renderer
+      // node graph) cannot be remounted via vite HMR because the THREE
+      // Material instance is already in the scene. Force full-reload so
+      // edits to shader/element/mesh files reach the renderer. All other
+      // files (plain ts/css/etc.) continue to HMR normally.
+      if (forceReloadOn && forceReloadOn.test(file)) {
+        server.ws.send({ type: 'full-reload' });
+        return [];
+      }
+      return undefined;
+    },
+  };
+}
+
+export interface TelemetryPaths {
+  project: string;
+  statePath: string;
+  logPath: string;
+}
+
+export function resolveTelemetryPaths(cwd: string = process.cwd()): TelemetryPaths {
+  const project = readPackageName(cwd);
+  return {
+    project,
+    statePath: join(tmpdir(), `${project}-state.json`),
+    logPath: join(tmpdir(), `${project}-state.log`),
+  };
+}