@3driseai/3drise-viewer 0.1.32 → 0.1.34

package/dist/operations/catalogue/warmup.js

@@ -17,32 +17,125 @@
 //     and reuses it, no compile (see shaderLayers.commitPendingLayers);
 //   • effect helpers (particles, threads, rings, beams, instances): their
 //     materials start hidden (material.visible = false; three still compiles
-//     hidden materials) and are shown once their program is ready.
+//     hidden materials) and are shown once their program is ready — together with
+//     their shadow-pass program when they cast shadows (compileAsync never
+//     compiles the shadow pass).
 // Without a renderer / camera (SSR, tests) everything happens immediately.
 //
+// Every warm compile runs AS THE FRAME DRAWS THE SCENE (asInFrame): three bakes tone
+// mapping and the output colour space into a program by the render target bound when
+// it compiles — the screen (null) gets the renderer's tone mapping and sRGB, a render
+// target gets neither. Volumetric clouds and post-processing draw the scene into a
+// render target, so a warm-up compiled against the screen built the wrong program and
+// the first real frame compiled again, in the frame (every effect froze). The target
+// the scene is really drawn into is watched (scene.onBeforeRender) and bound for the
+// compile. Measured in claude/prebake-audit.md.
+//
 import { SceneStore } from '@3driseai/3drise-core';
-import { InstancedMesh, LineSegments, Mesh, Points } from 'three';
+import { Color, InstancedMesh, LineSegments, Mesh, MeshDepthMaterial, MeshDistanceMaterial, Points, RGBADepthPacking, VSMShadowMap, WebGLRenderTarget, } from 'three';
 import cameraManager from '../../utils/CameraSingleton.js';
 export function warmContext() {
     const gl = SceneStore.gl, scene = SceneStore.scene, cam = cameraManager.getCamera?.();
+    if (scene)
+        watchFrameTarget(scene);
     return gl && scene && cam && typeof gl.compileAsync === 'function' ? { gl, scene, cam } : null;
 }
+// ---------------------------------------------------------------- the frame's render target
+const FRAME_TARGET = '__fxFrameTarget';
+const UNSEEN = 'unseen';
+/** Note, every frame, the render target the scene is drawn into. Installed once per scene. */
+function watchFrameTarget(scene) {
+    if (scene.userData[FRAME_TARGET] !== undefined)
+        return;
+    scene.userData[FRAME_TARGET] = UNSEEN;
+    const own = scene.onBeforeRender;
+    scene.onBeforeRender = function (renderer, sc, camera, target) {
+        scene.userData[FRAME_TARGET] = target ?? null;
+        return own?.call(this, renderer, sc, camera, target);
+    };
+}
+/** Resolves once the scene has been drawn since the watch started (its target is known), or after a short wait. */
+function frameSeen(ctx) {
+    if (ctx.scene.userData[FRAME_TARGET] !== UNSEEN || typeof requestAnimationFrame !== 'function')
+        return Promise.resolve();
+    return new Promise(resolve => {
+        const t0 = performance.now();
+        const check = () => (ctx.scene.userData[FRAME_TARGET] !== UNSEEN || performance.now() - t0 > 500 ? resolve() : requestAnimationFrame(check));
+        requestAnimationFrame(check);
+    });
+}
+/** Run a compile with the render target the scene is drawn into bound (see the header). */
+export function asInFrame(ctx, fn) {
+    const seen = ctx.scene.userData?.[FRAME_TARGET];
+    const target = seen === UNSEEN || seen === undefined ? null : seen;
+    const prev = ctx.gl.getRenderTarget();
+    if (target === prev)
+        return fn();
+    ctx.gl.setRenderTarget(target);
+    try {
+        return fn();
+    }
+    finally {
+        ctx.gl.setRenderTarget(prev);
+    }
+}
 /** compileAsync with a safety timeout (a driver that never reports ready must not hang an effect). */
-export function compileInBackground(root, timeoutMs = 8000) {
-    const ctx = warmContext();
+export function compileInBackground(root, timeoutMs = 8000, given) {
+    const ctx = given ?? warmContext();
     if (!ctx)
         return Promise.resolve();
     let timer;
-    return Promise.race([
-        Promise.resolve(ctx.gl.compileAsync(root, ctx.cam, ctx.scene)).then(() => undefined, () => undefined),
+    return frameSeen(ctx).then(() => Promise.race([
+        Promise.resolve(asInFrame(ctx, () => ctx.gl.compileAsync(root, ctx.cam, ctx.scene))).then(() => undefined, () => undefined),
         new Promise(r => { timer = setTimeout(r, timeoutMs); }),
-    ]).finally(() => clearTimeout(timer));
+    ])).finally(() => clearTimeout(timer));
+}
+/** The whole scene, as the frame draws it (the published scene's load: see triggers/readiness). */
+export function compileScene(three, timeoutMs = 8000) {
+    let ctx = warmContext();
+    if (!ctx && three?.gl?.compileAsync && three.scene && three.camera) {
+        watchFrameTarget(three.scene);
+        ctx = { gl: three.gl, scene: three.scene, cam: three.camera };
+    }
+    return ctx ? compileInBackground(ctx.scene, timeoutMs, ctx) : Promise.resolve();
+}
+/**
+ * Upload every texture of `root` to the GPU now. three uploads a texture the first time
+ * something using it is drawn — in that frame: an object hidden at load and shown later
+ * (a cue, an action, visibility) would stall the frame it appears in.
+ */
+export function uploadTextures(root) {
+    const ctx = warmContext();
+    if (!ctx || typeof ctx.gl.initTexture !== 'function')
+        return 0;
+    const seen = new Set();
+    (root ?? ctx.scene).traverse((c) => {
+        for (const m of materialsOf1(c)) {
+            for (const v of Object.values(m))
+                if (v?.isTexture && !v.isRenderTargetTexture)
+                    seen.add(v);
+            const u = m.uniforms;
+            if (u)
+                for (const x of Object.values(u)) {
+                    const t = x?.value;
+                    if (t?.isTexture && !t.isRenderTargetTexture)
+                        seen.add(t);
+                }
+        }
+    });
+    for (const t of seen) {
+        try {
+            ctx.gl.initTexture(t);
+        }
+        catch { /* not uploadable yet (image still loading) */ }
+    }
+    return seen.size;
 }
 const FLAG = '__opFxWarm';
+const materialsOf1 = (c) => (c.material ? (Array.isArray(c.material) ? c.material : [c.material]) : []);
 const materialsOf = (obj) => {
     const out = [];
-    obj.traverse((c) => { if (c.material)
-        out.push(...(Array.isArray(c.material) ? c.material : [c.material])); });
+    obj.traverse((c) => { out.push(...materialsOf1(c)); });
     return out;
 };
 /** Keep a freshly created helper off screen until its shaders are compiled (see warmHelpers). */
@@ -58,13 +151,105 @@ export function warmHelpers(root) {
     const waiting = [];
     root.traverse((c) => { if (c.userData?.[FLAG])
         waiting.push(c); });
-    return Promise.all(waiting.map(h => compileInBackground(h).then(() => {
+    return Promise.all(waiting.map(h => Promise.all([compileInBackground(h), warmShadowPass(h)]).then(() => {
         for (const m of materialsOf(h))
             m.visible = true;
         delete h.userData[FLAG];
         retainPrograms(h);
     }))).then(() => undefined);
 }
+// ---------------------------------------------------------------- the shadow pass
+let shadowTarget = null;
+// three's shadow pass draws a caster with ITS depth material turned to the caster's shadow side
+// (front faces → back, back → front, double stays) — the side is part of the program
+const SHADOW_SIDE = { 0: 1, 1: 0, 2: 2 };
+const depthMats = new Map();
+function depthFor(kind, side) {
+    const key = `${kind}|${side}`;
+    let m = depthMats.get(key);
+    if (!m) {
+        m = kind === 'depth' ? new MeshDepthMaterial({ depthPacking: RGBADepthPacking }) : new MeshDistanceMaterial();
+        m.side = side;
+        depthMats.set(key, m);
+    }
+    return m;
+}
+const shadowKept = [];
+const shadowKeys = new Set();
+/**
+ * The shadow pass draws a shadow caster with three's own depth material — a program
+ * compileAsync never builds, so a new kind of caster (an instanced helper) compiled it
+ * in the first frame that drew its shadow. Build it here: a stand-in of the same kind
+ * with an equivalent depth material, compiled into a render target as the shadow map is.
+ * The stand-ins are kept (never drawn) so the programs stay cached.
+ */
+export function warmShadowPass(root) {
+    try {
+        return shadowPass(root);
+    }
+    catch (e) {
+        console.warn('[3drise] shadow warm-up failed', e);
+        return Promise.resolve();
+    }
+}
+function shadowPass(root) {
+    const ctx = warmContext();
+    if (!ctx || !ctx.gl.shadowMap?.enabled || ctx.gl.shadowMap.type === VSMShadowMap)
+        return Promise.resolve();
+    let dirOrSpot = false, point = false;
+    ctx.scene.traverseVisible((o) => {
+        if (!o.isLight || !o.castShadow)
+            return;
+        if (o.isPointLight)
+            point = true;
+        else
+            dirOrSpot = true;
+    });
+    if (!dirOrSpot && !point)
+        return Promise.resolve();
+    const stands = [];
+    root.traverse((c) => {
+        if (!c.castShadow || !(c.isMesh || c.isPoints || c.isLine))
+            return;
+        const own = materialsOf1(c)[0];
+        const side = own?.shadowSide ?? SHADOW_SIDE[own?.side ?? 0] ?? 1;
+        for (const [use, kind] of [[dirOrSpot, 'depth'], [point, 'distance']]) {
+            if (!use)
+                continue;
+            const mat = depthFor(kind, side);
+            const key = `${kind}|${side}|${c.isInstancedMesh ? `inst${c.instanceColor ? 'C' : ''}` : c.isSkinnedMesh ? 'skin' : c.type}|${Object.keys(c.geometry?.morphAttributes ?? {}).join(',')}`;
+            if (shadowKeys.has(key))
+                continue;
+            shadowKeys.add(key);
+            let s;
+            if (c.isInstancedMesh) {
+                s = new InstancedMesh(c.geometry, mat, 1);
+                if (c.instanceColor)
+                    s.setColorAt(0, new Color(1, 1, 1));
+            }
+            else if (c.isMesh)
+                s = new Mesh(c.geometry, mat);
+            else
+                continue;
+            s.frustumCulled = false;
+            stands.push(s);
+        }
+    });
+    if (!stands.length)
+        return Promise.resolve();
+    shadowTarget ??= new WebGLRenderTarget(1, 1);
+    const prev = ctx.gl.getRenderTarget();
+    let res;
+    ctx.gl.setRenderTarget(shadowTarget);
+    try {
+        res = Promise.all(stands.map(s => Promise.resolve(ctx.gl.compileAsync(s, ctx.cam, ctx.scene)).catch(() => undefined)));
+    }
+    finally {
+        ctx.gl.setRenderTarget(prev);
+    }
+    shadowKept.push(...stands);
+    return Promise.race([res, new Promise(r => setTimeout(r, 8000))]).then(() => undefined);
+}
 /**
  * Warm-only runs (pre-warming): while this is on, an effect's runProgress compiles
  * everything it needs and then stops — nothing animates. See runtime.prewarmEffect.
@@ -84,7 +269,7 @@ export function retainPrograms(root) {
     root.traverse((c) => {
         const mats = c.material ? (Array.isArray(c.material) ? c.material : [c.material]) : [];
         for (const m of mats) {
-            const key = `${c.type}|${m.type}|${m.vertexShader?.length ?? ''}|${m.fragmentShader?.length ?? ''}|${m.customProgramCacheKey?.() ?? ''}`;
+            const key = `${c.type}${c.instanceColor ? '+color' : ''}|${m.type}|${m.vertexShader?.length ?? ''}|${m.fragmentShader?.length ?? ''}|${m.customProgramCacheKey?.() ?? ''}`;
             if (retainedKeys.has(key))
                 continue;
             retainedKeys.add(key);
@@ -96,8 +281,11 @@ export function retainPrograms(root) {
                 : c.isLineSegments ? new LineSegments(c.geometry, keep) : c.isMesh ? new Mesh(c.geometry, keep) : null;
             if (!stand)
                 continue;
+            // instance colours are part of the program: without them the kept program is another one
+            if (c.isInstancedMesh && c.instanceColor)
+                stand.setColorAt(0, new Color(1, 1, 1));
             try {
-                ctx.gl.compile(stand, ctx.cam, ctx.scene);
+                asInFrame(ctx, () => ctx.gl.compile(stand, ctx.cam, ctx.scene));
                 retained.push(keep);
             }
             catch { /* ignore */ }

package/dist/operations/index.d.ts

@@ -1,9 +1,11 @@
 export * from './types';
 export { OPERATIONS, getOperation, operationsFor, resolveParams, channelOf } from './registry';
 export { OPERATION_GROUPS, groupOperations, type OperationGroup } from './groups';
+export { bakeProject, collectBakeJobs, setBakeSource, type BakeSource, type BakeReport } from './bake';
+export { installStallLog, stallLogEnabled } from '../utils/stallLog';
 export { runEffect, runEffectClip, setEffectClipTemplates, getEffectClipTemplate, effectClipFromAsset, EFFECT_CLIP_ASSET, applyOperation, revertOperation, runOf, isOperationOn, resolveEffectTargets, runActionEffects, previewEffect, previewEffects, isPreviewing, prewarmEffect, areActionEffectsOn, subscribeActionEffects, registerOperationTools, } from './runtime';
 export { useOperationsRuntime } from './useOperationsRuntime';
-export { ObjectEffectsController, runningObjectEffects, objectEffectParams, isObjectOperation, surfaceSignature, playObjectEffect, playbackOf, clipFollowsVisibility, setObjectEffectsVisible, currentEffectStep } from './objectEffects';
+export { ObjectEffectsController, runningObjectEffects, objectEffectParams, isObjectOperation, surfaceSignature, playObjectEffect, setObjectEffectParam, playbackOf, clipFollowsVisibility, setObjectEffectsVisible, currentEffectStep } from './objectEffects';
 export { useObjectEffectLayers } from './useObjectEffectLayers';
 export { usePresentedVisibility } from './usePresentedVisibility';
 export { captureFrameImage } from './clipPreview';

package/dist/operations/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/operations/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAClF,OAAO,EACH,SAAS,EAAE,aAAa,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAC5L,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,sBAAsB,GACnJ,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,UAAU,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1O,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/operations/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAClF,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AACvG,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EACH,SAAS,EAAE,aAAa,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAC5L,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,sBAAsB,GACnJ,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,UAAU,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAChQ,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/operations/index.js

@@ -1,9 +1,11 @@
 export * from './types.js';
 export { OPERATIONS, getOperation, operationsFor, resolveParams, channelOf } from './registry.js';
 export { OPERATION_GROUPS, groupOperations } from './groups.js';
+export { bakeProject, collectBakeJobs, setBakeSource } from './bake.js';
+export { installStallLog, stallLogEnabled } from '../utils/stallLog.js';
 export { runEffect, runEffectClip, setEffectClipTemplates, getEffectClipTemplate, effectClipFromAsset, EFFECT_CLIP_ASSET, applyOperation, revertOperation, runOf, isOperationOn, resolveEffectTargets, runActionEffects, previewEffect, previewEffects, isPreviewing, prewarmEffect, areActionEffectsOn, subscribeActionEffects, registerOperationTools, } from './runtime.js';
 export { useOperationsRuntime } from './useOperationsRuntime.js';
-export { ObjectEffectsController, runningObjectEffects, objectEffectParams, isObjectOperation, surfaceSignature, playObjectEffect, playbackOf, clipFollowsVisibility, setObjectEffectsVisible, currentEffectStep } from './objectEffects.js';
+export { ObjectEffectsController, runningObjectEffects, objectEffectParams, isObjectOperation, surfaceSignature, playObjectEffect, setObjectEffectParam, playbackOf, clipFollowsVisibility, setObjectEffectsVisible, currentEffectStep } from './objectEffects.js';
 export { useObjectEffectLayers } from './useObjectEffectLayers.js';
 export { usePresentedVisibility } from './usePresentedVisibility.js';
 export { captureFrameImage } from './clipPreview.js';

package/dist/operations/objectEffects.d.ts

@@ -1,5 +1,5 @@
 import type { Object3D } from 'three';
-import type { EffectPlayback, EffectSpread, EffectStep, EffectSteps, ObjectEffect } from '@3driseai/3drise-core';
+import type { EffectPlayback, EffectSpread, EffectStep, EffectSteps, ObjectEffect, OperationParamValue } from '@3driseai/3drise-core';
 import type { OperationDefinition, OperationParams } from './types';
 /** An operation can be an object effect (one-shots too: they have no way back, and play with loop). */
 export declare const isObjectOperation: (def: OperationDefinition | undefined) => def is OperationDefinition;
@@ -17,6 +17,12 @@ export declare const objectEffectParams: (def: OperationDefinition, effect: Pick
 export declare const playbackOf: (effect: Pick<ObjectEffect, "playback">) => Required<EffectPlayback>;
 /** An object's effects controller; `create` makes one for an object that has no effects of its own yet. */
 export declare function objectEffectsControllerFor(root: Object3D, create?: boolean): ObjectEffectsController | undefined;
+/**
+ * A timeline track on one of an object's effects' params (`effects.<effectId>.<param>`): set it on
+ * the running effect (undefined = back to the effect's own). False when the object has no controller
+ * or no such effect yet (a model still loading).
+ */
+export declare function setObjectEffectParam(root: Object3D | null | undefined, effectId: string, key: string, value: OperationParamValue | undefined): boolean;
 /** The step of an object's effect steps that is on now (-1: none) — for the editor. */
 export declare function currentEffectStep(root: Object3D | null | undefined): number;
 /** An object's own effect clip follows its visibility (`visible`) and has an effect that is on. */
@@ -76,6 +82,8 @@ export declare class ObjectEffectsController {
     private spread;
     /** Added effects that follow visibility: a group's effects on this child, when the group's follow it. */
     private addedFollows;
+    /** Timeline-driven params (effect id → param → value), laid over the row's own while a clip drives them. */
+    private liveParams;
     constructor(root: Object3D);
     /** The object's targets for an effect: the object, or its named nodes. */
     private targetsOf;
@@ -176,6 +184,12 @@ export declare class ObjectEffectsController {
     /** Loop / yoyo / reverse, sequenced from apply (forward) and revert (backward). Reads r.params each pass. */
     private cycle;
     /** Play an effect out and leave it waiting (it stays in the list, ready to play again). */
+    /**
+     * A timeline track drives one of the effect's params: lay it over the row's own (undefined puts
+     * the row's own back). A running motion takes it at once (its `live` hook); anything else picks
+     * it up on its next pass — nothing replays.
+     */
+    setLiveParam(effectId: string, key: string, value: OperationParamValue | undefined): boolean;
     stop(effectId: string): boolean;
     /** Play an effect from its start (see playObjectEffect). */
     play(effectId: string): boolean;

package/dist/operations/objectEffects.d.ts.map

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

package/dist/operations/objectEffects.js

@@ -75,6 +75,14 @@ registerAddedEffects({
     removeClip: (root, key) => !!controllers.get(root)?.removeClip(key),
     hasClip: (root, key) => !!controllers.get(root)?.hasClip(key),
 });
+/**
+ * A timeline track on one of an object's effects' params (`effects.<effectId>.<param>`): set it on
+ * the running effect (undefined = back to the effect's own). False when the object has no controller
+ * or no such effect yet (a model still loading).
+ */
+export function setObjectEffectParam(root, effectId, key, value) {
+    return !!root && !!controllers.get(root)?.setLiveParam(effectId, key, value);
+}
 /** The step of an object's effect steps that is on now (-1: none) — for the editor. */
 export function currentEffectStep(root) {
     return (root && controllers.get(root)?.step) ?? -1;
@@ -150,6 +158,8 @@ export class ObjectEffectsController {
     spread = {};
     /** Added effects that follow visibility: a group's effects on this child, when the group's follow it. */
     addedFollows = new Set();
+    /** Timeline-driven params (effect id → param → value), laid over the row's own while a clip drives them. */
+    liveParams = new Map();
     constructor(root) {
         this.root = root;
         controllers.set(root, this);
@@ -562,7 +572,7 @@ export class ObjectEffectsController {
         for (const e of next) {
             const def = getOperation(e.operation);
             const [follows, inStep] = this.visOf(e.id);
-            const params = objectEffectParams(def, e, follows, inStep);
+            const params = { ...objectEffectParams(def, e, follows, inStep), ...(this.liveParams.get(e.id) ?? {}) };
             const paramsKey = JSON.stringify(params);
             const r = this.running.get(e.id);
             if (r && r.paramsKey === paramsKey)
@@ -1104,6 +1114,44 @@ export class ObjectEffectsController {
             r.cycle = undefined;
     }
     /** Play an effect out and leave it waiting (it stays in the list, ready to play again). */
+    /**
+     * A timeline track drives one of the effect's params: lay it over the row's own (undefined puts
+     * the row's own back). A running motion takes it at once (its `live` hook); anything else picks
+     * it up on its next pass — nothing replays.
+     */
+    setLiveParam(effectId, key, value) {
+        if (this.disposed)
+            return false;
+        const cur = { ...(this.liveParams.get(effectId) ?? {}) };
+        if (value === undefined)
+            delete cur[key];
+        else
+            cur[key] = value;
+        if (Object.keys(cur).length)
+            this.liveParams.set(effectId, cur);
+        else
+            this.liveParams.delete(effectId);
+        const e = this.effects.find(x => x?.id === effectId);
+        const r = this.running.get(effectId);
+        if (!e)
+            return false;
+        if (!r)
+            return true;
+        const def = getOperation(r.op);
+        if (!def)
+            return true;
+        const [follows, inStep] = this.visOf(effectId);
+        const params = { ...objectEffectParams(def, e, follows, inStep), ...cur };
+        const paramsKey = JSON.stringify(params);
+        if (paramsKey === r.paramsKey)
+            return true;
+        r.params = params;
+        r.paramsKey = paramsKey;
+        if (r.started && def.live)
+            for (const t of r.targets)
+                def.live(t, { ...params, __backward: !!r.cycle?.back });
+        return true;
+    }
     stop(effectId) {
         const r = this.running.get(effectId);
         const def = r && getOperation(r.op);

package/dist/operations/runtime.d.ts

@@ -88,19 +88,26 @@ export declare function previewEffect(effect: OperationEffect, self?: Object3D |
 /** Preview several effects together (an interaction's "Try it"). */
 export declare function previewEffects(effects: OperationEffect[], self?: Object3D | null): Promise<boolean>;
 export declare const isPreviewing: (effectId: string) => boolean;
+/** Whether a pre-warm can do anything for an operation (visual, undoable, with shaders). */
+export declare const isWarmable: (def: OperationDefinition | undefined) => def is OperationDefinition;
 /**
- * Compile an effect's shaders ahead of time, without showing anything, so its
- * first real play starts instantly. Visual effects only (the others have no
- * shaders). Runs one at a time, in the background; each (effect, target) once.
- * Used when an effect is picked in the editor and, for every effect a scene's
- * interactions and actions use, when the scene loads.
+ * Warm an operation on these targets: build and compile everything its first real play
+ * needs — shaders (in the background), and the CPU work it caches (surface samples,
+ * geometry) — showing nothing, then take it off again. Queued, one at a time; each
+ * (operation, target, its meshes, parameters) once. Targets with no meshes yet (a model
+ * still loading) are skipped and warmed when it has landed.
  */
-export declare function prewarmEffect(effect: OperationEffect, self?: Object3D | null): Promise<void>;
+export declare function warmEffectOn(def: OperationDefinition, targets: Object3D[], params: OperationParams, self?: Object3D | null): Promise<void>;
 /**
- * A warm-only apply: stages and compiles what the operation needs on the target and
- * animates nothing. It is left staged at its start — apply it for real next, or revert it.
- * Used to get an effect ready while its object is still hidden (see objectEffects, Visible).
+ * Compile an effect's shaders ahead of time, without showing anything, so its
+ * first real play starts instantly (see warmEffectOn). Used when an effect is picked
+ * in an editor; the project bake (bake.ts) warms everything a scene can play.
  */
+export declare function prewarmEffect(effect: OperationEffect, self?: Object3D | null): Promise<void>;
+/** Main-thread work an effect did, for the stall log (utils/stallLog). Cheap when it is off. */
+type WorkListener = (label: string, ms: number) => void;
+export declare const setWorkListener: (fn: WorkListener | null) => void;
+export declare function noteWork(label: string, ms: number): void;
 export declare function warmOperation(def: OperationDefinition, target: Object3D, params: OperationParams, self?: Object3D | null, opts?: {
     bare?: boolean;
 }): Promise<void>;
@@ -112,4 +119,5 @@ export declare function runActionEffects(action: ActionSequence, mode: 'apply' |
 export declare const areActionEffectsOn: (actionId: string) => boolean;
 /** Subscribe to action-effects on/off changes (studio badges). */
 export declare function subscribeActionEffects(fn: () => void): () => void;
+export {};
 //# sourceMappingURL=runtime.d.ts.map

package/dist/operations/runtime.d.ts.map

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

package/dist/operations/runtime.js

@@ -75,7 +75,10 @@ export function applyOperation(def, target, params, self, opts) {
         }
         slots.set(def.exclusive.group, key);
     }
-    runs.set(key, finished(def.apply(target, params, ctx), params));
+    const t0 = performance.now();
+    const res = def.apply(target, params, ctx);
+    noteWork(def.value, performance.now() - t0);
+    runs.set(key, finished(res, params));
     if (def.revert)
         active.set(key, { op: def.value, target, params });
     return true;
@@ -348,30 +351,69 @@ export const isPreviewing = (effectId) => previews.has(effectId);
 // ---------------------------------------------------------------- pre-warm
 /** Visual operations with no shaders of their own — nothing to warm (and a warm-only run would show). */
 const NO_SHADERS = new Set(['glow', 'fade', 'visibility', 'displayImage']);
+/** Whether a pre-warm can do anything for an operation (visual, undoable, with shaders). */
+export const isWarmable = (def) => !!def && def.channel === 'visual' && !!def.revert && !NO_SHADERS.has(def.value);
 const warmed = new Set();
 let warmQueue = Promise.resolve();
 /**
- * Compile an effect's shaders ahead of time, without showing anything, so its
- * first real play starts instantly. Visual effects only (the others have no
- * shaders). Runs one at a time, in the background; each (effect, target) once.
- * Used when an effect is picked in the editor and, for every effect a scene's
- * interactions and actions use, when the scene loads.
+ * What a warm-up covered on a target: its meshes as they are now. A model that lands
+ * after the warm-up (its object's group exists first) has other meshes — it is warmed again.
  */
-export function prewarmEffect(effect, self) {
-    const def = getOperation(effect.operation);
-    if (!def || def.channel !== 'visual' || !def.revert || NO_SHADERS.has(def.value))
+function meshSignature(t) {
+    let count = 0, h = 0;
+    t.traverse((c) => {
+        if (!c.isMesh || c.userData?.__opFxHelper)
+            return;
+        count++;
+        for (let i = 0; i < c.uuid.length; i++)
+            h = (h * 31 + c.uuid.charCodeAt(i)) | 0;
+    });
+    return { count, sig: `${count}:${h}` };
+}
+/**
+ * The objects a warm-up runs on for one target: the target itself — or, for a group, its
+ * member objects (a group never draws an effect itself: groupFanout hands them out).
+ */
+function warmRoots(t) {
+    if (t.userData?.objectType !== 'group')
+        return [t];
+    const out = [];
+    t.traverse((c) => {
+        if (c === t || !c.userData?.id || !c.userData.objectType || c.userData.objectType === 'group')
+            return;
+        if (c.userData.visualFx === false)
+            return;
+        out.push(c);
+    });
+    return out;
+}
+/**
+ * Warm an operation on these targets: build and compile everything its first real play
+ * needs — shaders (in the background), and the CPU work it caches (surface samples,
+ * geometry) — showing nothing, then take it off again. Queued, one at a time; each
+ * (operation, target, its meshes, parameters) once. Targets with no meshes yet (a model
+ * still loading) are skipped and warmed when it has landed.
+ */
+export function warmEffectOn(def, targets, params, self) {
+    if (!isWarmable(def))
         return Promise.resolve();
-    const params = resolveParams(def, effect.params);
+    const paramsKey = JSON.stringify(params);
     const job = async () => {
-        const ctx = context(self);
+        const ctx = context(self, true);
         if (!ctx)
             return;
-        const targets = resolveEffectTargets(effect, self);
-        for (const t of def.multi ? targets : targets.slice(0, 1)) {
-            const k = `${def.value}:${t.uuid}`;
+        const roots = targets.flatMap(warmRoots);
+        for (const t of def.multi ? roots : roots.slice(0, 1)) {
+            if (!t.parent)
+                continue; // left the scene meanwhile
+            const { count, sig } = meshSignature(t);
+            if (!count)
+                continue; // nothing to warm yet (a model still loading)
+            const k = `${def.value}:${t.uuid}:${sig}:${paramsKey}`;
             if (warmed.has(k) || isOperationOn(def.value, t))
                 continue;
             warmed.add(k);
+            const t0 = performance.now();
             // a warm-only run: stages and compiles everything, animates nothing…
             warmMode.on = true;
             let res;
@@ -381,8 +423,9 @@ export function prewarmEffect(effect, self) {
             finally {
                 warmMode.on = false;
             }
+            noteWork(`warm ${def.value}`, performance.now() - t0);
             await finished(res, { duration: 0 });
-            // …then quietly take it off again, unless the user started it meanwhile
+            // …then quietly take it off again, unless something started it meanwhile
             if (!isOperationOn(def.value, t))
                 await finished(def.revert(t, { ...params, duration: 0.001 }, ctx), { duration: 0 });
         }
@@ -391,10 +434,20 @@ export function prewarmEffect(effect, self) {
     return warmQueue;
 }
 /**
- * A warm-only apply: stages and compiles what the operation needs on the target and
- * animates nothing. It is left staged at its start — apply it for real next, or revert it.
- * Used to get an effect ready while its object is still hidden (see objectEffects, Visible).
+ * Compile an effect's shaders ahead of time, without showing anything, so its
+ * first real play starts instantly (see warmEffectOn). Used when an effect is picked
+ * in an editor; the project bake (bake.ts) warms everything a scene can play.
  */
+export function prewarmEffect(effect, self) {
+    const def = getOperation(effect.operation);
+    if (!isWarmable(def))
+        return Promise.resolve();
+    return warmEffectOn(def, resolveEffectTargets(effect, self), resolveParams(def, effect.params), self);
+}
+let workListener = null;
+export const setWorkListener = (fn) => { workListener = fn; };
+export function noteWork(label, ms) { if (workListener && ms >= 4)
+    workListener(label, ms); }
 export function warmOperation(def, target, params, self, opts) {
     if (def.channel !== 'visual' || !def.revert || NO_SHADERS.has(def.value))
         return Promise.resolve();