@triscope/core 0.4.0

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAkHA;;uEAEuE;AACvE,MAAM,UAAU,WAAW,CAAC,CAAO;IACjC,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACvC,OAAO,CAAC,CAAC,OAAO,CAAC;AACnB,CAAC"}

package/dist/uniform-access.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 declare function parseUniformPath(path: string): {
+    objectId: string;
+    key: string;
+};
+export declare function readUniformValue(root: any, path: string): UniformReadResult;
+export declare function writeUniformValue(root: any, path: string, value: unknown): UniformWriteResult;
+//# sourceMappingURL=uniform-access.d.ts.map

package/dist/uniform-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniform-access.d.ts","sourceRoot":"","sources":["../src/uniform-access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,SAAS,GAAG,mBAAmB,GAAG,iBAAiB,GAAG,WAAW,CAAC;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,SAAS,GAAG,mBAAmB,GAAG,iBAAiB,GAAG,WAAW,CAAC;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAIhF;AA0DD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAQ3E;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAmD7F"}

package/dist/uniform-access.js

@@ -0,0 +1,144 @@
+/**
+ * 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 function parseUniformPath(path) {
+    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, id) {
+    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, key) {
+    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) {
+    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, path) {
+    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, path, value) {
+    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); // THREE.Color — accepts '#hex' or number
+        }
+        else if (cur &&
+            typeof cur.set === 'function' &&
+            typeof cur.x === 'number' &&
+            Array.isArray(value)) {
+            cur.set(...value); // 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?.message ?? e),
+        };
+    }
+    return {
+        ok: true,
+        kind: slot.kind,
+        path,
+        previous,
+        current: serializeVal(slot.container[slot.prop]),
+    };
+}
+//# sourceMappingURL=uniform-access.js.map

package/dist/uniform-access.js.map

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

package/dist/validate.d.ts

@@ -0,0 +1,2 @@
+export declare function validateElement(el: any): string[];
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAMA,wBAAgB,eAAe,CAAC,EAAE,EAAE,GAAG,GAAG,MAAM,EAAE,CAuEjD"}

package/dist/validate.js

@@ -0,0 +1,81 @@
+// 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) {
+    const problems = [];
+    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)) {
+            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)) {
+                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']) {
+        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)) {
+                if (typeof fn !== 'function')
+                    problems.push(`motionProbe "${key}" must be a function`);
+            }
+        }
+    }
+    return problems;
+}
+function isVec3(v) {
+    return Array.isArray(v) && v.length === 3 && v.every((n) => typeof n === 'number');
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,+EAA+E;AAC/E,6EAA6E;AAE7E,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;AAE7E,MAAM,UAAU,eAAe,CAAC,EAAO;IACrC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,CAAC,EAAE,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC;QAClC,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,OAAO,EAAE,CAAC,IAAI,KAAK,QAAQ,IAAI,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxD,QAAQ,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,OAAO,EAAE,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QACnC,QAAQ,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;IACpD,CAAC;IACD,2EAA2E;IAC3E,8EAA8E;IAC9E,wEAAwE;IACxE,IAAI,EAAE,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;QAC1B,QAAQ;IACV,CAAC;SAAM,IACL,CAAC,EAAE,CAAC,OAAO;QACX,OAAO,EAAE,CAAC,OAAO,KAAK,QAAQ;QAC9B,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,EACpC,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,oEAAoE,CAAC,CAAC;IACtF,CAAC;SAAM,CAAC;QACN,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,OAA8B,CAAC,EAAE,CAAC;YAC7E,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;gBACrD,QAAQ,CAAC,IAAI,CAAC,WAAW,IAAI,mCAAmC,CAAC,CAAC;YACpE,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,EAAE,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,OAAO,EAAE,CAAC,KAAK,KAAK,QAAQ,IAAI,EAAE,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACtD,QAAQ,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;QACnD,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,KAA4B,CAAC,EAAE,CAAC;gBACvE,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;oBAClC,QAAQ,CAAC,IAAI,CAAC,SAAS,GAAG,0BAA0B,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC;oBAChE,SAAS;gBACX,CAAC;gBACD,IACE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC;oBACzC,CAAC,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ,CAAC,EACxD,CAAC;oBACD,QAAQ,CAAC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC,IAAI,6BAA6B,CAAC,CAAC;gBACvE,CAAC;gBACD,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;oBAC/E,QAAQ,CAAC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC,IAAI,2BAA2B,CAAC,CAAC;gBACrE,CAAC;gBACD,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;oBACxD,QAAQ,CAAC,IAAI,CAAC,SAAS,GAAG,kCAAkC,CAAC,CAAC;gBAChE,CAAC;gBACD,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;oBAC3D,QAAQ,CAAC,IAAI,CAAC,SAAS,GAAG,qCAAqC,CAAC,CAAC;gBACnE,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAU,EAAE,CAAC;QAC9D,IAAI,EAAE,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,OAAO,EAAE,CAAC,IAAI,CAAC,KAAK,UAAU,EAAE,CAAC;YAC7D,QAAQ,CAAC,IAAI,CAAC,WAAW,IAAI,gCAAgC,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;IACD,IAAI,EAAE,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QAClC,IAAI,OAAO,EAAE,CAAC,YAAY,KAAK,QAAQ,IAAI,EAAE,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;YACpE,QAAQ,CAAC,IAAI,CAAC,qDAAqD,CAAC,CAAC;QACvE,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,YAAmC,CAAC,EAAE,CAAC;gBAC/E,IAAI,OAAO,EAAE,KAAK,UAAU;oBAAE,QAAQ,CAAC,IAAI,CAAC,gBAAgB,GAAG,sBAAsB,CAAC,CAAC;YACzF,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,MAAM,CAAC,CAAU;IACxB,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;AACrF,CAAC"}

package/dist/vite.d.ts

@@ -0,0 +1,3 @@
+export type { TelemetryPaths } from './telemetry.js';
+export { resolveTelemetryPaths, triscopeTelemetryPlugin } from './telemetry.js';
+//# sourceMappingURL=vite.d.ts.map

package/dist/vite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/vite.js

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

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.js","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,wEAAwE;AAGxE,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/warnings.d.ts

@@ -0,0 +1,24 @@
+/** 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 declare function createWarningRing(cap?: number, now?: () => number): WarningRing;
+//# sourceMappingURL=warnings.d.ts.map

package/dist/warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warnings.d.ts","sourceRoot":"","sources":["../src/warnings.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,0JAA0J;IAC1J,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACjE,IAAI,EAAE,MAAM,YAAY,EAAE,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,SAAK,EAAE,GAAG,GAAE,MAAM,MAAyB,GAAG,WAAW,CAgB7F"}

package/dist/warnings.js

@@ -0,0 +1,26 @@
+/**
+ * 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 = () => Date.now()) {
+    const buf = [];
+    return {
+        push(source, message, detail) {
+            const entry = { ts: now(), source, message };
+            if (detail !== undefined)
+                entry.detail = detail;
+            buf.push(entry);
+            if (buf.length > cap)
+                buf.shift();
+        },
+        list() {
+            return buf.slice();
+        },
+        get size() {
+            return buf.length;
+        },
+    };
+}
+//# sourceMappingURL=warnings.js.map

package/dist/warnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warnings.js","sourceRoot":"","sources":["../src/warnings.ts"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAG,GAAG,EAAE,EAAE,MAAoB,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;IAC9E,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,OAAO;QACL,IAAI,CAAC,MAAc,EAAE,OAAe,EAAE,MAAe;YACnD,MAAM,KAAK,GAAiB,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;YAC3D,IAAI,MAAM,KAAK,SAAS;gBAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;YAChD,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAChB,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG;gBAAE,GAAG,CAAC,KAAK,EAAE,CAAC;QACpC,CAAC;QACD,IAAI;YACF,OAAO,GAAG,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;QACD,IAAI,IAAI;YACN,OAAO,GAAG,CAAC,MAAM,CAAC;QACpB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@triscope/core",
+  "version": "0.4.0",
+  "description": "Triscope runtime: Element contract, multi-camera lab harness, Vite telemetry plugin.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js",
+      "default": "./dist/vite.js"
+    },
+    "./src/*": "./src/*"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "three": ">=0.170.0",
+    "vite": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^2.1.9",
+    "jsdom": "^25.0.0",
+    "three": "^0.176.0",
+    "typescript": "^5.6.0",
+    "vite": "^5.4.0",
+    "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text --coverage.reporter=html"
+  },
+  "keywords": [
+    "three.js",
+    "webgpu",
+    "tsl",
+    "ai-tools",
+    "claude-code",
+    "shader-tuning",
+    "3d",
+    "lab"
+  ]
+}

package/src/compose.ts

@@ -0,0 +1,164 @@
+/**
+ * composeElements — fold multiple Elements into one composite Element.
+ *
+ * The Element contract is already enough for composition (the README has
+ * said "composition is just an element that mounts other elements" from
+ * day one) but writing the boilerplate by hand is tedious. This helper
+ * does the bookkeeping: it merges cameras, knobs, motionProbes, events,
+ * and telemetry under a `<elementName>.<key>` namespace so two elements
+ * declaring a camera both named "top" don't collide.
+ *
+ * Pass the result to runLab(). Inspect mode keeps working — each
+ * underlying element's meshes still get their own auto source-tags
+ * (the patch is global, not per-element).
+ *
+ * Knob routing: when the harness calls onKnob('ship.windPressure', x),
+ * we split on the first dot, find the matching element, and forward to
+ * its onKnob with the un-prefixed key ('windPressure').
+ */
+import { autoCameras } from './scene-cameras.js';
+import type { CameraSpec, Element, MountContext, MountHandle, TriscopeEvent } from './types.js';
+
+export interface ComposeOptions {
+  /** Name of the composite element. Used for the state file + manifest. Default: 'composite'. */
+  name?: string;
+  /** Override the auto-computed bounds (union of children's). */
+  bounds?: Element['bounds'];
+  /** Override the lab URL (otherwise inherits the first child's). */
+  labUrl?: string;
+}
+
+interface ChildHandles {
+  handles: MountHandle[];
+}
+
+export function composeElements(elements: Element[], opts: ComposeOptions = {}): Element {
+  if (!Array.isArray(elements) || elements.length === 0) {
+    throw new Error('composeElements: pass a non-empty array of Element');
+  }
+  const name = opts.name ?? 'composite';
+  const labUrl = opts.labUrl ?? elements[0]?.labUrl;
+  const bounds = opts.bounds ?? unionBounds(elements);
+
+  // Pre-build the merged camera/knob/motionProbe maps so the Element shape
+  // is correct before mount runs. onKnob/telemetry/motionProbes/events
+  // close over `elements` (static) and reach into handle.userData.handles
+  // (the live MountHandle list) for per-element lookups.
+  const cameras: Element['cameras'] = {};
+  const knobs: Element['knobs'] = {};
+  const motionProbes: Element['motionProbes'] = {};
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i];
+    const camSpecs = el.cameras === 'auto' ? autoCameras(el.bounds) : (el.cameras ?? {});
+    for (const [cn, c] of Object.entries(camSpecs)) {
+      (cameras as Record<string, CameraSpec>)[nsKey(el.name, cn)] = c;
+    }
+    for (const [kn, k] of Object.entries(el.knobs ?? {})) {
+      (knobs as Record<string, any>)[nsKey(el.name, kn)] = k;
+    }
+    for (const [pn, p] of Object.entries(el.motionProbes ?? {})) {
+      const idx = i; // capture
+      (motionProbes as Record<string, any>)[nsKey(el.name, pn)] = (
+        handle: MountHandle,
+        ctx: MountContext,
+      ) => {
+        const childHandle = (handle.userData as unknown as ChildHandles)?.handles?.[idx];
+        return childHandle ? p(childHandle, ctx) : 0;
+      };
+    }
+  }
+
+  return {
+    name,
+    labUrl,
+    bounds,
+    cameras,
+    knobs,
+    mount: ({ parent, ctx }) => {
+      const handles: MountHandle[] = elements.map((el) => el.mount({ parent, ctx }));
+      // name → child handle, so the SDL can show/hide a child at runtime
+      // (applyElementToggle) without dispose/remount.
+      const childrenByName: Record<string, MountHandle> = {};
+      elements.forEach((el, i) => {
+        childrenByName[el.name] = handles[i];
+      });
+      return {
+        root: parent,
+        userData: { handles, childrenByName } as unknown as Record<string, unknown>,
+        dispose: () => {
+          for (const h of handles) {
+            try {
+              h.dispose();
+            } catch {
+              /* keep tearing down the rest */
+            }
+          }
+        },
+      };
+    },
+    onKnob: (handle, key, value) => {
+      const [elName, knobKey] = splitNs(key);
+      if (!elName || !knobKey) return;
+      const idx = elements.findIndex((e) => e.name === elName);
+      if (idx < 0) return;
+      const childHandle = (handle.userData as unknown as ChildHandles)?.handles?.[idx];
+      if (!childHandle) return;
+      elements[idx].onKnob?.(childHandle, knobKey, value);
+    },
+    telemetry: (handle, ctx) => {
+      const out: Record<string, unknown> = {};
+      const childHandles = (handle.userData as unknown as ChildHandles)?.handles ?? [];
+      for (let i = 0; i < elements.length; i++) {
+        const el = elements[i];
+        const h = childHandles[i];
+        out[el.name] = h && el.telemetry ? el.telemetry(h, ctx) : {};
+      }
+      return out;
+    },
+    motionProbes,
+    events: (handle, ctx) => {
+      const out: TriscopeEvent[] = [];
+      const childHandles = (handle.userData as unknown as ChildHandles)?.handles ?? [];
+      for (let i = 0; i < elements.length; i++) {
+        const el = elements[i];
+        const h = childHandles[i];
+        if (!el.events || !h) continue;
+        try {
+          for (const ev of el.events(h, ctx) ?? []) {
+            // Namespace event types so a `collision` from ship and water
+            // are distinguishable downstream.
+            out.push({ ...ev, type: nsKey(el.name, ev.type) });
+          }
+        } catch {
+          /* ignore element-level failures */
+        }
+      }
+      return out;
+    },
+  };
+}
+
+function unionBounds(elements: Element[]): Element['bounds'] {
+  const min: [number, number, number] = [Infinity, Infinity, Infinity];
+  const max: [number, number, number] = [-Infinity, -Infinity, -Infinity];
+  let any = false;
+  for (const el of elements) {
+    if (!el.bounds) continue;
+    any = true;
+    for (let i = 0; i < 3; i++) {
+      if (el.bounds.min[i] < min[i]) min[i] = el.bounds.min[i];
+      if (el.bounds.max[i] > max[i]) max[i] = el.bounds.max[i];
+    }
+  }
+  return any ? { min, max } : undefined;
+}
+
+function nsKey(elementName: string, key: string): string {
+  return `${elementName}.${key}`;
+}
+
+function splitNs(key: string): [string, string] {
+  const dot = key.indexOf('.');
+  if (dot < 0) return ['', key];
+  return [key.slice(0, dot), key.slice(dot + 1)];
+}