@triscope/core 0.4.0

package/dist/source-tag.js

@@ -0,0 +1,120 @@
+/**
+ * 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';
+/**
+ * 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() {
+    if (patched)
+        return false;
+    patched = true;
+    const origAdd = THREE.Object3D.prototype.add;
+    THREE.Object3D.prototype.add = function (...children) {
+        let stack = [];
+        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;
+            if (prior && prior.source)
+                continue;
+            const tag = {
+                source,
+                stack,
+                type: child.constructor.name,
+            };
+            const asMesh = child;
+            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.__tris = tag;
+        }
+        return origAdd.apply(this, children);
+    };
+    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, max = 8) {
+    const out = [];
+    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) {
+    return u.replace(/[?#].*$/, '');
+}
+export function extractMaterialHint(material) {
+    const m = material;
+    const hint = {};
+    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;
+}
+//# sourceMappingURL=source-tag.js.map

package/dist/source-tag.js.map

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

package/dist/telemetry.d.ts

@@ -0,0 +1,53 @@
+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 declare function readRequestBody(req: {
+    on: (event: string, cb: (arg: never) => void) => void;
+    socket?: {
+        destroy?: () => void;
+    };
+}, timeoutMs?: number): Promise<string>;
+/**
+ * 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 declare function triscopeTelemetryPlugin(opts?: TelemetryOptions): Plugin;
+export interface TelemetryPaths {
+    project: string;
+    statePath: string;
+    logPath: string;
+}
+export declare function resolveTelemetryPaths(cwd?: string): TelemetryPaths;
+export {};
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,UAAU,gBAAgB;IACxB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE;IACH,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,KAAK,IAAI,CAAC;IACtD,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;CACnC,EACD,SAAS,GAAE,MAAkE,GAC5E,OAAO,CAAC,MAAM,CAAC,CAgCjB;AAgCD;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,gBAAqB,GAAG,MAAM,CAyM3E;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,MAAsB,GAAG,cAAc,CAOjF"}

package/dist/telemetry.js

@@ -0,0 +1,302 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+/**
+ * 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, timeoutMs = Number(process.env.TRISCOPE_READBODY_TIMEOUT_MS ?? 10000)) {
+    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.unref?.();
+        req.on('data', (c) => {
+            body += c;
+        });
+        req.on('end', () => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve(body);
+        });
+        req.on('error', (e) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+}
+function readProjectLabs(cwd) {
+    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 = {};
+            for (const [k, v] of Object.entries(labs)) {
+                if (typeof v === 'string')
+                    out[k] = v;
+            }
+            return out;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+function readPackageName(cwd) {
+    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 = {}) {
+    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 = [];
+    // 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 = {};
+    // 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 = [];
+    const lastSceneState = {
+        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 = {};
+    // 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) => 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 = 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?.toFixed?.(0) ?? '?';
+                        const cam = payload?.activeCamera ?? '?';
+                        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.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);
+                        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);
+                        // 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], ...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);
+                        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 function resolveTelemetryPaths(cwd = process.cwd()) {
+    const project = readPackageName(cwd);
+    return {
+        project,
+        statePath: join(tmpdir(), `${project}-state.json`),
+        logPath: join(tmpdir(), `${project}-state.log`),
+    };
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,142 @@
+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 declare function knobDefault(k: Knob): number | string | boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,9 @@
+/** 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) {
+    if (k.type === 'trigger')
+        return false;
+    return k.default;
+}
+//# sourceMappingURL=types.js.map