@3driseai/3drise-viewer 0.1.32 → 0.1.33

package/dist/components/CameraController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CameraController.d.ts","sourceRoot":"","sources":["../../src/components/CameraController.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAQ7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,UAAU,qBAAsB,SAAQ,gBAAgB;IACpD,QAAQ,EAAE,WAAW,CAAC;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;IAC1C,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;CAC/C;AAGD,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CA4H5D,CAAC;AACF,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"CameraController.d.ts","sourceRoot":"","sources":["../../src/components/CameraController.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAQ7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,UAAU,qBAAsB,SAAQ,gBAAgB;IACpD,QAAQ,EAAE,WAAW,CAAC;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;IAC1C,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;CAC/C;AAGD,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAqI5D,CAAC;AACF,eAAe,gBAAgB,CAAC"}

package/dist/components/CameraController.js

@@ -94,6 +94,15 @@ export const CameraController = ({ enableAutoAnimation = true, animationDuration
         orbitControls.maxDistance = controls.maxDistance;
         // Saved limits may be null (once ±Infinity): the full range then.
         Object.assign(orbitControls, orbitAngleLimits(controls));
+        // The authored limits, kept on the live instance: controllers drag them directly
+        // (setLive), the follow hook widens from them and clamps the height with them,
+        // and the limits helper draws them.
+        orbitControls.authoredLimits = {
+            minDistance: controls.minDistance, maxDistance: controls.maxDistance,
+            ...orbitAngleLimits(controls),
+            minHeight: typeof controls.minHeight === 'number' ? controls.minHeight : null,
+            maxHeight: typeof controls.maxHeight === 'number' ? controls.maxHeight : null,
+        };
     }, [controls]);
     // Look at a scene object (orbit target) and / or travel with one (follow).
     useOrbitTargetFollow(controlsRef, controls.targetObject, controls.followObject, () => isInAnimatedTransition.current || isAnimating() || isPathAnimating(), controls.enabled !== false, controls);

package/dist/components/ObjectsRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ObjectsRenderer.d.ts","sourceRoot":"","sources":["../../src/components/ObjectsRenderer.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACvH,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAQ9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,UAAU,oBAAqB,SAAQ,gBAAgB;IACnD,cAAc,EAAE,WAAW,CAAC;IAC5B,qBAAqB,EAAE,qBAAqB,CAAC;IAC7C,cAAc,EAAE,qBAAqB,EAAE,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;IAC1G,mEAAmE;IACnE,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAChC,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;CACtC;AAGD,QAAA,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,oBAAoB,CAwFlD,CAAC;AAEH,eAAe,eAAe,CAAC"}
+{"version":3,"file":"ObjectsRenderer.d.ts","sourceRoot":"","sources":["../../src/components/ObjectsRenderer.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACvH,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAU9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,UAAU,oBAAqB,SAAQ,gBAAgB;IACnD,cAAc,EAAE,WAAW,CAAC;IAC5B,qBAAqB,EAAE,qBAAqB,CAAC;IAC7C,cAAc,EAAE,qBAAqB,EAAE,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;IAC1G,mEAAmE;IACnE,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAChC,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;CACtC;AAGD,QAAA,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,oBAAoB,CAgGlD,CAAC;AAEH,eAAe,eAAe,CAAC"}

package/dist/components/ObjectsRenderer.js

@@ -1,17 +1,20 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { memo, useRef, useCallback, useMemo, useEffect } from 'react';
-import { buildObjectTree } from '@3driseai/3drise-core';
+import { memo, useRef, useCallback, useMemo, useEffect, useState } from 'react';
+import { buildObjectTree, SceneStore } from '@3driseai/3drise-core';
 import ObjectNode from './ObjectNode.js';
 import useInteraction from '../hooks/useInteraction.js';
 import { ObjectHoverContext, setEffectPrewarmer, setEffectPreviewer, setInteractionRunner } from '../interactions/runner.js';
 import { prewarmEffect, previewEffect, previewEffects } from '../operations/runtime.js';
+import { bakeProject, setBakeSource } from '../operations/bake.js';
+import { installStallLog } from '../utils/stallLog.js';
 import { findById } from '../utils/sceneQuery.js';
-import { actionEffectsOf, commandsOf, effectsOf } from '../triggers/index.js';
+import { commandsOf, sceneReadiness } from '../triggers/index.js';
 import { useObjectReady } from '../hooks/useObjectReady.js';
 const ObjectsRenderer = memo(({ cameraSettings, createdObjects, generalObjectSettings, onObjectsReady, onObjectReady, onObjectDispose, handleObjectClick, sequences = [], clips = [], actionSequences = [], }) => {
     const groupRef = useRef(null);
     const objectsTree = useMemo(() => buildObjectTree(createdObjects), [createdObjects]);
     const readyObjectsCount = useRef(0);
+    const bumpBakeRef = useRef(() => { });
     // Count for the aggregate onObjectsReady signal, then forward the event up.
     // Previously this callback counted and dropped the (object, ref) pair, which
     // is why nothing above ObjectsRenderer ever received an object ref.
@@ -21,6 +24,7 @@ const ObjectsRenderer = memo(({ cameraSettings, createdObjects, generalObjectSet
             onObjectsReady && onObjectsReady();
         }
         onObjectReady && onObjectReady(object, ref);
+        bumpBakeRef.current();
     }, [objectsTree.length, onObjectsReady, onObjectReady]);
     const handleObjectDispose = useCallback((object, ref) => {
         readyObjectsCount.current = Math.max(0, readyObjectsCount.current - 1);
@@ -72,24 +76,27 @@ const ObjectsRenderer = memo(({ cameraSettings, createdObjects, generalObjectSet
         const ref = findById(objectId);
         return ref ? prewarmEffect(effect, ref) : Promise.resolve();
     }), []);
-    // Compile, in the background, the shaders of every effect this scene's interactions
-    // and actions use, so a visitor's first click never stalls. Each (effect, object) once.
+    // Bake everything this project can play (operations/bake.ts): every effect of its interactions,
+    // actions, clip / sequence cues, effect clips and objects' own Effects tabs is compiled and
+    // prepared ahead of time, so no first play stalls. A published scene bakes inside its readiness,
+    // under the loading cover; here it re-bakes in the background when the lists change or an object
+    // reports ready (a model landed — only what is new is warmed).
+    const [bakeTick, setBakeTick] = useState(0);
     useEffect(() => {
-        const t = setTimeout(() => {
-            for (const o of objectsRef.current ?? []) {
-                const ref = findById(o.id);
-                if (!ref)
-                    continue;
-                for (const ix of (o.actions ?? []))
-                    for (const e of effectsOf(ix))
-                        void prewarmEffect(e, ref);
-            }
-            for (const a of actionSequences ?? [])
-                for (const e of actionEffectsOf(a))
-                    void prewarmEffect(e, null);
-        }, 1500);
+        setBakeSource({ objects: createdObjects, actions: actionSequences, clips, sequences });
+        if (!sceneReadiness.isReady())
+            return; // the readiness bake does it
+        const t = setTimeout(() => { void bakeProject(); }, 400);
         return () => clearTimeout(t);
-    }, [createdObjects, actionSequences]);
+    }, [createdObjects, actionSequences, clips, sequences, bakeTick]);
+    const bumpBake = useCallback(() => setBakeTick(n => n + 1), []);
+    bumpBakeRef.current = bumpBake;
+    // dev: log frames that stall and why (localStorage '3drise:stalls' = '1' — utils/stallLog)
+    useEffect(() => {
+        const t = setTimeout(() => { const gl = SceneStore.gl; if (gl)
+            installStallLog(gl); }, 500);
+        return () => clearTimeout(t);
+    }, []);
     const handleObjectClickHandler = (createdObject, ref, event) => {
         const clickInteractions = filterInteractionsByEvent(createdObject.actions, "click");
         clickInteractions.forEach((interaction) => {

package/dist/components/SceneBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SceneBuilder.d.ts","sourceRoot":"","sources":["../../src/components/SceneBuilder.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAqB,KAAK,WAAW,EAA0B,MAAM,oBAAoB,CAAC;AAGjG,OAAO,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAWxE,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAM7D,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,gBAAgB,GAAG;IACzE;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IAC5C,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACnC,oEAAoE;IACpE,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,qFAAqF;IACrF,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,QAAA,MAAM,YAAY;IAfd;;;OAGG;mBACY,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI;IAC3C,mFAAmF;uBAChE,KAAK,CAAC,SAAS;IAClC,oEAAoE;SAC/D,OAAO;IACZ,qFAAqF;eAC1E,OAAO,EAAE;IACpB,2EAA2E;eAChE,MAAM;qCA4LnB,CAAC;AAIH,eAAe,YAAY,CAAC"}
+{"version":3,"file":"SceneBuilder.d.ts","sourceRoot":"","sources":["../../src/components/SceneBuilder.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAqB,KAAK,WAAW,EAA0B,MAAM,oBAAoB,CAAC;AAGjG,OAAO,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAWxE,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAM7D,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,gBAAgB,GAAG;IACzE;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IAC5C,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACnC,oEAAoE;IACpE,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,qFAAqF;IACrF,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,QAAA,MAAM,YAAY;IAfd;;;OAGG;mBACY,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI;IAC3C,mFAAmF;uBAChE,KAAK,CAAC,SAAS;IAClC,oEAAoE;SAC/D,OAAO;IACZ,qFAAqF;eAC1E,OAAO,EAAE;IACpB,2EAA2E;eAChE,MAAM;qCA6LnB,CAAC;AAIH,eAAe,YAAY,CAAC"}

package/dist/components/SceneBuilder.js

@@ -2,6 +2,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import AdaptiveResolution from './AdaptiveResolution.js';
 import { forwardRef, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { EFFECT_CLIP_ASSET, effectClipFromAsset, setEffectClipTemplates } from "../operations/runtime.js";
+import { compileScene, uploadTextures } from "../operations/catalogue/warmup.js";
+import { bakeProject } from "../operations/bake.js";
 import { createSceneHandle } from "../api/sceneHandle.js";
 import { Canvas } from "@react-three/fiber";
 import { LIGHTING_PRESETS, SceneStore } from "@3driseai/3drise-core";
@@ -81,10 +83,11 @@ const SceneBuilder = forwardRef(({ project, width = "100%", height = "100vh", st
     const [started, setStarted] = useState(false);
     useLayoutEffect(() => {
         sceneReadiness.begin([CANVAS_READY, ...(modelKey ? modelKey.split(',') : [])], {
-            compile: () => {
-                const t = threeRef.current;
-                return t?.gl?.compileAsync ? t.gl.compileAsync(t.scene, t.camera) : Promise.resolve();
-            },
+            // as the frame draws it (render target included — see warmup), then every texture uploaded
+            // (objects hidden at load would upload theirs in the frame they appear in)
+            compile: () => compileScene(threeRef.current).then(() => { uploadTextures(); }),
+            // every effect the project can play, compiled and prepared (operations/bake)
+            bake: () => bakeProject(),
         });
         if (threeRef.current)
             sceneReadiness.report(CANVAS_READY); // remount with the canvas already there

package/dist/components/land/LandPatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LandPatch.d.ts","sourceRoot":"","sources":["../../../src/components/land/LandPatch.tsx"],"names":[],"mappings":"AACA,OAAO,KAAmE,MAAM,OAAO,CAAC;AAExF,OAAO,EAGH,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AA4ChE,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACpD,MAAM,EAAE,gBAAgB,CAAC;IACzB,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,8DAA8D;IAC9D,SAAS,CAAC,EAAE,eAAe,CAAC;CAC/B;AASD,QAAA,MAAM,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,cAAc,CAyIvC,CAAC;AAEF,eAAe,SAAS,CAAC"}
+{"version":3,"file":"LandPatch.d.ts","sourceRoot":"","sources":["../../../src/components/land/LandPatch.tsx"],"names":[],"mappings":"AACA,OAAO,KAAmE,MAAM,OAAO,CAAC;AAExF,OAAO,EAGH,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAoDhE,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACpD,MAAM,EAAE,gBAAgB,CAAC;IACzB,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,8DAA8D;IAC9D,SAAS,CAAC,EAAE,eAAe,CAAC;CAC/B;AASD,QAAA,MAAM,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,cAAc,CAgJvC,CAAC;AAEF,eAAe,SAAS,CAAC"}

package/dist/components/land/LandPatch.js

@@ -11,6 +11,13 @@ import { TerrainMaterial } from '../../shaders/terrain/TerrainMaterial.js';
 import { applySunUniforms } from '../../utils/cloudUniforms.js';
 import { applyTerrainAmbient, applyTerrainTextures, applyTerrainUniforms } from '../../utils/terrainUniforms.js';
 import { withConfigDefaults } from '../../utils/configAnimations.js';
+import { isMobileDevice } from '../../utils/deviceTier.js';
+/**
+ * Phone / tablet tier, at render time only — the saved object keeps its numbers.
+ * The same caps as the environment terrain (TerrainSurface), plus the low grid:
+ * per-pixel cost (octaves, texture distance) is what dominates, measured on desktop.
+ */
+const MOBILE = { quality: 'low', maxOctaves: 5, maxTextureDistance: 400 };
 import { resolveTerrainTextureSets, useTerrainTextureResolverVersion } from '../../utils/terrainTextureResolver.js';
 import { LAND_SEGMENTS, applyLandPatchUniforms, landFrame, landHeightAt, landQuality, landToTerrainConfig, } from '../../utils/landPatch.js';
 // =============================================================================
@@ -47,7 +54,8 @@ const LandPatch = ({ config, id, keyframes, mouseMove, onObjectReady, onObjectDi
     const type = DEFAULT_LAND_OBJECTS[config.type] ? config.type : 'hills';
     const base = useMemo(() => withConfigDefaults(DEFAULT_LAND_OBJECTS[type], config), [config, type]);
     const allowed = useMemo(() => new Set(LAND_OBJECTS_ANIMATABLE[type].map((p) => p.value)), [type]);
-    const segments = LAND_SEGMENTS[base.quality] ?? 256;
+    const mobile = isMobileDevice();
+    const segments = LAND_SEGMENTS[mobile ? MOBILE.quality : base.quality] ?? 256;
     const geometry = useMemo(() => {
         const g = new THREE.PlaneGeometry(1, 1, segments, segments);
         g.rotateX(-Math.PI / 2);
@@ -78,6 +86,12 @@ const LandPatch = ({ config, id, keyframes, mouseMove, onObjectReady, onObjectDi
         if (!mesh)
             return;
         const cfg = { ...current.current, textures: current.current.textures ?? base.textures };
+        if (mobile) {
+            // quality must match the grid built above: the shader's cell size comes from it.
+            cfg.quality = MOBILE.quality;
+            cfg.octaves = Math.min(cfg.octaves, MOBILE.maxOctaves);
+            cfg.textureDistance = Math.min(cfg.textureDistance ?? 4000, MOBILE.maxTextureDistance);
+        }
         const t = landToTerrainConfig(cfg);
         const s = sun.update();
         const m = material;

package/dist/hooks/useContinuousEffects.js

@@ -97,7 +97,7 @@ objectSettings, options = {}, objectSource) => {
                 object,
                 meshSettings: objectSettings.meshSettings || {},
                 pathIsActive,
-            }, activeTransformAnimations, currentTime, hovered);
+            }, activeTransformAnimations, currentTime, hovered, delta);
         }
         if (hasEdgesAnimations) {
             handleEdgesAnimations({ object, startValuesCache: edgesStartValuesRef.current }, edgesAnimations, currentTime, hovered);

package/dist/hooks/useOrbitTargetFollow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOrbitTargetFollow.d.ts","sourceRoot":"","sources":["../../src/hooks/useOrbitTargetFollow.ts"],"names":[],"mappings":"AA+CA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAsE/E,wBAAgB,oBAAoB,CAChC,WAAW,EAAE,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,EACxC,YAAY,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,EAClD,YAAY,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS;AAClD,+EAA+E;AAC/E,YAAY,EAAE,MAAM,OAAO;AAC3B,4FAA4F;AAC5F,QAAQ,EAAE,OAAO;AACjB,gFAAgF;AAChF,QAAQ,EAAE,cAAc,QAqE3B;AAED,eAAe,oBAAoB,CAAC"}
+{"version":3,"file":"useOrbitTargetFollow.d.ts","sourceRoot":"","sources":["../../src/hooks/useOrbitTargetFollow.ts"],"names":[],"mappings":"AAgDA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAsE/E,wBAAgB,oBAAoB,CAChC,WAAW,EAAE,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,EACxC,YAAY,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,EAClD,YAAY,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS;AAClD,+EAA+E;AAC/E,YAAY,EAAE,MAAM,OAAO;AAC3B,4FAA4F;AAC5F,QAAQ,EAAE,OAAO;AACjB,gFAAgF;AAChF,QAAQ,EAAE,cAAc,QAsE3B;AAED,eAAe,oBAAoB,CAAC"}

package/dist/hooks/useOrbitTargetFollow.js

@@ -34,7 +34,8 @@
 // So while looking at an object, the limits are widened each frame just enough to hold
 // where the camera is now: the object can take the view outside the authored range,
 // the user still can't rotate / zoom further out of it, and moving back in tightens
-// them to the authored values again. The authored values come from `controls`.
+// them to the authored values again. The authored values are `controls.authoredLimits` on
+// the live instance (CameraController sets them, controllers drag them), else the config.
 //
 // Height limits (controls.minHeight / maxHeight) are world Y, not relative to the target,
 // and are applied after everything else in the frame.
@@ -173,8 +174,9 @@ authored) {
             }
             // HEIGHT LIMITS (world Y): last, so nothing — user, target, follow, a clip — ends
             // the frame under the floor or over the ceiling. The camera keeps facing the target.
-            const minH = typeof auth.minHeight === 'number' ? auth.minHeight : -Infinity;
-            const maxH = typeof auth.maxHeight === 'number' ? auth.maxHeight : Infinity;
+            const lim = controls?.authoredLimits ?? auth;
+            const minH = typeof lim.minHeight === 'number' ? lim.minHeight : -Infinity;
+            const maxH = typeof lim.maxHeight === 'number' ? lim.maxHeight : Infinity;
             const y = Math.min(maxH, Math.max(minH, camera.position.y));
             if (y !== camera.position.y) {
                 camera.position.y = y;
@@ -186,7 +188,7 @@ authored) {
                 camera.updateMatrixWorld();
             // Limits hold the camera where the moving target left it (see the header).
             if (tObj && controls && a.locked)
-                widenLimits(controls, camera.position, auth);
+                widenLimits(controls, camera.position, controls.authoredLimits ?? auth);
         };
         return () => { scene.onBeforeRender = prev; };
     }, [scene, camera, controlsRef]);

package/dist/operations/bake.d.ts

@@ -0,0 +1,36 @@
+import type { ActionSequence, SceneCommand } from '@3driseai/3drise-core';
+import type { OperationParams } from './types';
+/** What a project holds (the lists SceneBuilder / the studio render with). */
+export interface BakeSource {
+    objects?: ReadonlyArray<any>;
+    actions?: ReadonlyArray<ActionSequence>;
+    clips?: ReadonlyArray<{
+        cues?: ReadonlyArray<{
+            command?: SceneCommand | null;
+        }>;
+    }>;
+    sequences?: ReadonlyArray<{
+        cues?: ReadonlyArray<{
+            command?: SceneCommand | null;
+        }>;
+    }>;
+}
+/** One thing to warm: an operation with its parameters on target ids ('self' already resolved). */
+interface BakeJob {
+    op: string;
+    params: OperationParams;
+    targets: string[];
+    meshNames?: Record<string, string[]>;
+}
+/** Every warm job of a project. */
+export declare function collectBakeJobs(src: BakeSource): BakeJob[];
+/** The project the scene renders (ObjectsRenderer keeps it current). */
+export declare const setBakeSource: (src: BakeSource) => void;
+export interface BakeReport {
+    jobs: number;
+    ms: number;
+}
+/** Bake the current project now (queued behind a bake that is running). Resolves when done. */
+export declare function bakeProject(src?: BakeSource): Promise<BakeReport>;
+export {};
+//# sourceMappingURL=bake.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bake.d.ts","sourceRoot":"","sources":["../../src/operations/bake.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,cAAc,EAA6C,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAKrH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACvB,OAAO,CAAC,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,CAAC,EAAE,aAAa,CAAC;YAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IACnF,SAAS,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,CAAC,EAAE,aAAa,CAAC;YAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAC;CAC1F;AAED,mGAAmG;AACnG,UAAU,OAAO;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACxC;AASD,mCAAmC;AACnC,wBAAgB,eAAe,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,EAAE,CAyC1D;AAiBD,wEAAwE;AACxE,eAAO,MAAM,aAAa,GAAI,KAAK,UAAU,SAAsB,CAAC;AAIpE,MAAM,WAAW,UAAU;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE;AAExD,+FAA+F;AAC/F,wBAAgB,WAAW,CAAC,GAAG,GAAE,UAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CAkBzE"}

package/dist/operations/bake.js

@@ -0,0 +1,113 @@
+import { findNodesByName, objectEffectClipOf } from '@3driseai/3drise-core';
+import { findById } from '../utils/sceneQuery.js';
+import { getOperation, resolveParams } from './registry.js';
+import { getEffectClipTemplate, isWarmable, warmEffectOn } from './runtime.js';
+import { objectEffectParams } from './objectEffects.js';
+const commandsOfInteraction = (ix) => (Array.isArray(ix?.commands) ? ix.commands : []);
+const commandsOfAction = (a) => (Array.isArray(a?.commands) ? a.commands : []);
+/** The effects of an effect clip (template or an object's own): Base and every step. */
+const clipEffects = (clip) => [...(clip?.effects ?? []), ...(clip?.steps ?? []).flatMap(s => s?.effects ?? [])].filter(e => e && typeof e.operation === 'string');
+/** Every warm job of a project. */
+export function collectBakeJobs(src) {
+    const jobs = new Map();
+    const add = (op, params, targets, meshNames) => {
+        if (!targets.length)
+            return;
+        const k = JSON.stringify([op, params, targets, meshNames ?? null]);
+        if (!jobs.has(k))
+            jobs.set(k, { op, params, targets, ...(meshNames ? { meshNames } : {}) });
+    };
+    const objectRow = (e, targets, meshNames) => {
+        const def = getOperation(e.operation);
+        if (!isWarmable(def))
+            return;
+        add(def.value, objectEffectParams(def, e), targets, meshNames);
+    };
+    const fromCommand = (c, selfId) => {
+        if (!c)
+            return;
+        const ids = (list) => (list ?? []).map(t => (t === 'self' ? selfId : t)).filter((t) => !!t);
+        if (c.kind === 'effect') {
+            const e = c.effect;
+            if (!e || e.enabled === false)
+                return;
+            const def = getOperation(e.operation);
+            if (!isWarmable(def))
+                return;
+            add(def.value, resolveParams(def, e.params), ids(e.targets), e.meshNames);
+        }
+        else if (c.kind === 'effectClip') {
+            const use = c.use;
+            const clip = use && getEffectClipTemplate(use.clip);
+            if (!clip)
+                return;
+            for (const e of clipEffects(clip))
+                objectRow(e, ids(use.targets), use.meshNames);
+        }
+    };
+    for (const o of src.objects ?? []) {
+        if (!o?.id)
+            continue;
+        for (const ix of (Array.isArray(o.actions) ? o.actions : [])) {
+            if (ix?.enabled === false)
+                continue;
+            for (const c of commandsOfInteraction(ix))
+                fromCommand(c, o.id);
+        }
+        const own = objectEffectClipOf(o);
+        const parts = own.parts?.length ? { [o.id]: own.parts } : undefined;
+        for (const e of clipEffects(own))
+            objectRow(e, [o.id], parts);
+    }
+    for (const a of src.actions ?? [])
+        for (const c of commandsOfAction(a))
+            fromCommand(c, null);
+    for (const t of [...(src.clips ?? []), ...(src.sequences ?? [])])
+        for (const cue of t?.cues ?? [])
+            fromCommand(cue?.command, null);
+    return [...jobs.values()];
+}
+function targetsOf(job) {
+    const out = [];
+    for (const id of job.targets) {
+        const root = findById(id);
+        if (!root)
+            continue;
+        const names = job.meshNames?.[id];
+        if (names?.length)
+            for (const n of names)
+                out.push(...findNodesByName(root, n).filter((x) => x !== root));
+        else
+            out.push(root);
+    }
+    return out;
+}
+// ---------------------------------------------------------------- running it
+let source = {};
+/** The project the scene renders (ObjectsRenderer keeps it current). */
+export const setBakeSource = (src) => { source = src; };
+let running = null;
+/** Bake the current project now (queued behind a bake that is running). Resolves when done. */
+export function bakeProject(src = source) {
+    if (running)
+        return running.then(() => bakeProject(src));
+    const run = (async () => {
+        const t0 = performance.now();
+        const jobs = collectBakeJobs(src);
+        for (const job of jobs) {
+            const def = getOperation(job.op);
+            if (!def)
+                continue;
+            const targets = targetsOf(job);
+            if (targets.length)
+                await warmEffectOn(def, targets, job.params);
+            // let a frame through between jobs (the studio is live while it bakes)
+            await new Promise(r => setTimeout(r, 0));
+        }
+        return { jobs: jobs.length, ms: Math.round(performance.now() - t0) };
+    })();
+    running = run;
+    void run.finally(() => { if (running === run)
+        running = null; });
+    return run;
+}

package/dist/operations/catalogue/shaderLayers.js

@@ -34,7 +34,7 @@
 // three keeps covers every cached program.
 //
 import { Color, Group, InstancedMesh, Material as ThreeMaterial, Mesh, SkinnedMesh } from 'three';
-import { compileInBackground, warmContext } from './warmup.js';
+import { asInFrame, compileInBackground, warmContext } from './warmup.js';
 /** material → uniform name → the live uniform object of the current layer */
 const liveUniforms = new WeakMap();
 /** material → uniform name → the stable proxy handed to the compiled program */
@@ -170,7 +170,7 @@ export async function commitPendingLayers(root) {
     if (ctx) {
         // let the live materials take the cached programs before the clones let go of them
         try {
-            ctx.gl.compile(root, ctx.cam, ctx.scene);
+            asInFrame(ctx, () => ctx.gl.compile(root, ctx.cam, ctx.scene));
         }
         catch { /* next frame will */ }
         setTimeout(() => clones.forEach(c => c.dispose()), 1500);

package/dist/operations/catalogue/warmup.d.ts

@@ -5,12 +5,34 @@ export interface WarmContext {
     cam: any;
 }
 export declare function warmContext(): WarmContext | null;
+/** Run a compile with the render target the scene is drawn into bound (see the header). */
+export declare function asInFrame<T>(ctx: WarmContext, fn: () => T): T;
 /** compileAsync with a safety timeout (a driver that never reports ready must not hang an effect). */
-export declare function compileInBackground(root: Object3D, timeoutMs?: number): Promise<void>;
+export declare function compileInBackground(root: Object3D, timeoutMs?: number, given?: WarmContext | null): Promise<void>;
+/** The whole scene, as the frame draws it (the published scene's load: see triggers/readiness). */
+export declare function compileScene(three?: {
+    gl: any;
+    scene: any;
+    camera: any;
+} | null, timeoutMs?: number): Promise<void>;
+/**
+ * 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 declare function uploadTextures(root?: Object3D): number;
 /** Keep a freshly created helper off screen until its shaders are compiled (see warmHelpers). */
 export declare function hideUntilWarm(obj: Object3D): void;
 /** Compile every helper under `root` that is waiting, in the background, then show it. */
 export declare function warmHelpers(root: Object3D): Promise<void>;
+/**
+ * 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 declare function warmShadowPass(root: Object3D): Promise<void>;
 /**
  * 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.

package/dist/operations/catalogue/warmup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"warmup.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/warmup.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAY,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGhD,MAAM,WAAW,WAAW;IAAG,EAAE,EAAE,GAAG,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC;IAAC,GAAG,EAAE,GAAG,CAAA;CAAE;AAE9D,wBAAgB,WAAW,IAAI,WAAW,GAAG,IAAI,CAGhD;AAED,sGAAsG;AACtG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAQnF;AAUD,iGAAiG;AACjG,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,QAI1C;AAED,0FAA0F;AAC1F,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzD;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ;;CAAgB,CAAC;AAStC,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,QAmB5C"}
+{"version":3,"file":"warmup.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/warmup.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAY,QAAQ,EAAW,MAAM,OAAO,CAAC;AAGzD,MAAM,WAAW,WAAW;IAAG,EAAE,EAAE,GAAG,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC;IAAC,GAAG,EAAE,GAAG,CAAA;CAAE;AAE9D,wBAAgB,WAAW,IAAI,WAAW,GAAG,IAAI,CAIhD;AA4BD,2FAA2F;AAC3F,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAO7D;AAED,sGAAsG;AACtG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,SAAO,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ/G;AAED,mGAAmG;AACnG,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE;IAAE,EAAE,EAAE,GAAG,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,GAAG,IAAI,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAOjH;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,CAatD;AAWD,iGAAiG;AACjG,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,QAI1C;AAED,0FAA0F;AAC1F,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzD;AAsBD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAK5D;AAyCD;;;GAGG;AACH,eAAO,MAAM,QAAQ;;CAAgB,CAAC;AAStC,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,QAqB5C"}

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,6 +1,8 @@
 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';

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,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"}

package/dist/operations/index.js

@@ -1,6 +1,8 @@
 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';

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();

package/dist/triggers/readiness.d.ts

@@ -6,6 +6,7 @@ declare class SceneReadiness {
     private loaded;
     private failed;
     private compile;
+    private bake;
     private waiters;
     private listeners;
     private timer;
@@ -18,6 +19,7 @@ declare class SceneReadiness {
     /** A published scene starts: wait for these models, then compile, then one frame. */
     begin(modelIds: string[], opts?: {
         compile?: () => Promise<unknown>;
+        bake?: () => Promise<unknown>;
     }): void;
     /** A model's Object3D is in the scene. */
     report(id: string): void;

package/dist/triggers/readiness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../src/triggers/readiness.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAMhE,cAAM,cAAc;IAChB,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,QAAQ,CAAqB;IACrC,oFAAoF;IACpF,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAK;IAEvB,SAAS,IAAI,oBAAoB;IACjC,kEAAkE;IAClE,OAAO,IAAI,OAAO;IAElB,qFAAqF;IACrF,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;KAAO,GAAG,IAAI;IAmBhF,0CAA0C;IAC1C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMxB,wEAAwE;IACxE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAOxC,wEAAwE;IACxE,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAMrC,SAAS,GAAI,UAAU,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAG9C;IAEF,6DAA6D;IAC7D,KAAK,IAAI,IAAI;IAab,OAAO,CAAC,KAAK;YAMC,MAAM;IA2BpB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,IAAI;CAGf;AAED,eAAO,MAAM,cAAc,gBAAuB,CAAC;AAEnD,kGAAkG;AAClG,wBAAgB,aAAa,IAAI,OAAO,CAEvC"}
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../src/triggers/readiness.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAOhE,cAAM,cAAc;IAChB,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,QAAQ,CAAqB;IACrC,oFAAoF;IACpF,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,IAAI,CAAyC;IACrD,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAK;IAEvB,SAAS,IAAI,oBAAoB;IACjC,kEAAkE;IAClE,OAAO,IAAI,OAAO;IAElB,qFAAqF;IACrF,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;KAAO,GAAG,IAAI;IAoB/G,0CAA0C;IAC1C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMxB,wEAAwE;IACxE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAOxC,wEAAwE;IACxE,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAMrC,SAAS,GAAI,UAAU,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAG9C;IAEF,6DAA6D;IAC7D,KAAK,IAAI,IAAI;IAcb,OAAO,CAAC,KAAK;YAMC,MAAM;IAwCpB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,IAAI;CAGf;AAED,eAAO,MAAM,cAAc,gBAAuB,CAAC;AAEnD,kGAAkG;AAClG,wBAAgB,aAAa,IAAI,OAAO,CAEvC"}

package/dist/triggers/readiness.js

@@ -4,8 +4,11 @@
 //
 // A published scene (SceneBuilder) is READY when:
 //   1. every model it holds has loaded (ModelPrimitive reports it) or failed (ModelBoundary), and
-//   2. the scene's shaders are compiled (renderer.compileAsync), and
-//   3. one frame has rendered.
+//   2. the scene's shaders are compiled (renderer.compileAsync, as the frame draws it) and its
+//      textures uploaded,
+//   3. the project is baked — every effect it can play compiled and prepared (operations/bake),
+//      so no first play stalls — and
+//   4. one frame has rendered.
 // Only then do autoplay sequences start, object effects start, onSceneReady fires and the
 // loading cover lifts. A model that never reports doesn't hold the scene forever: after
 // TIMEOUT_MS it goes ready anyway and the missing ids are logged.
@@ -21,6 +24,7 @@
 import { useSyncExternalStore } from 'react';
 const TIMEOUT_MS = 15000;
 const COMPILE_TIMEOUT_MS = 5000;
+const BAKE_TIMEOUT_MS = 20000;
 const log = (...a) => console.info('[3drise] scene', ...a);
 class SceneReadiness {
     status = 'idle';
@@ -29,6 +33,7 @@ class SceneReadiness {
     loaded = new Set();
     failed = new Set();
     compile = null;
+    bake = null;
     waiters = [];
     listeners = new Set();
     timer = null;
@@ -46,6 +51,7 @@ class SceneReadiness {
         this.finishing = false;
         this.expected = new Set(modelIds.filter(Boolean));
         this.compile = opts.compile ?? null;
+        this.bake = opts.bake ?? null;
         this.startedAt = performance.now();
         this.emit();
         const gen = this.generation;
@@ -96,6 +102,7 @@ class SceneReadiness {
         this.loaded.clear();
         this.failed.clear();
         this.compile = null;
+        this.bake = null;
         this.waiters = [];
         this.emit();
     }
@@ -122,13 +129,31 @@ class SceneReadiness {
                 console.warn('[3drise] scene: shader compile failed, going on', e);
             }
         }
+        const bakeAt = performance.now();
+        if (this.bake && gen === this.generation) {
+            let timer;
+            try {
+                const timedOut = await Promise.race([
+                    this.bake().then(() => false),
+                    new Promise(r => { timer = setTimeout(() => r(true), BAKE_TIMEOUT_MS); }),
+                ]);
+                if (timedOut)
+                    console.warn(`[3drise] scene: baking effects took over ${BAKE_TIMEOUT_MS / 1000}s — going ready, the rest bakes on`);
+            }
+            catch (e) {
+                console.warn('[3drise] scene: baking effects failed, going on', e);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
         // one rendered frame, so what is shown is what runs
         await new Promise(r => requestAnimationFrame(() => requestAnimationFrame(() => r())));
         if (gen !== this.generation)
             return; // reset / begun again meanwhile
         this.status = 'ready';
         const t = (n) => `${Math.round(n - this.startedAt)}ms`;
-        log(`ready in ${t(performance.now())} (models ${t(modelsAt)}, ${[...this.expected].filter(id => this.loaded.has(id)).length}/${this.expected.size} loaded${this.failed.size ? `, ${this.failed.size} failed` : ''})`);
+        log(`ready in ${t(performance.now())} (models ${t(modelsAt)}, compile ${Math.round(bakeAt - modelsAt)}ms, bake ${Math.round(performance.now() - bakeAt)}ms, ${[...this.expected].filter(id => this.loaded.has(id)).length}/${this.expected.size} loaded${this.failed.size ? `, ${this.failed.size} failed` : ''})`);
         this.emit();
         const run = this.waiters;
         this.waiters = [];

package/dist/utils/stallLog.d.ts

@@ -0,0 +1,4 @@
+export declare function stallLogEnabled(): boolean;
+/** Install on the scene's renderer, when the dev flag is on. Idempotent. */
+export declare function installStallLog(renderer: any): void;
+//# sourceMappingURL=stallLog.d.ts.map

package/dist/utils/stallLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stallLog.d.ts","sourceRoot":"","sources":["../../src/utils/stallLog.ts"],"names":[],"mappings":"AAuBA,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,QAAQ,EAAE,GAAG,GAAG,IAAI,CAgDnD"}

package/dist/utils/stallLog.js

@@ -0,0 +1,88 @@
+// =============================================================================
+// Stall log (dev) — which frames froze, and why.
+// =============================================================================
+//
+// Switch it on in the browser console:  localStorage.setItem('3drise:stalls', '1')  (reload)
+// Off:                                  localStorage.removeItem('3drise:stalls')
+//
+// Every frame slower than STALL_MS is logged with what happened in it:
+//   compiles   shader programs linked INSIDE the frame (three compiling on the spot —
+//              what the warm-ups exist to prevent; the material names say whose)
+//   uploads    textures uploaded inside the frame (an object drawn for the first time)
+//   work       effect applies / warm-ups that ran on the main thread since the last
+//              frame, with their milliseconds (runtime.noteWork)
+// Background compiles (warm-ups) are counted too, so a stall with none of the above is
+// the GPU / driver itself.
+//
+import { setWorkListener } from '../operations/runtime.js';
+const STALL_MS = 50;
+const FLAG = '3drise:stalls';
+let installed = false;
+export function stallLogEnabled() {
+    try {
+        return typeof window !== 'undefined' && window.localStorage?.getItem(FLAG) === '1';
+    }
+    catch {
+        return false;
+    }
+}
+/** Install on the scene's renderer, when the dev flag is on. Idempotent. */
+export function installStallLog(renderer) {
+    if (installed || !renderer || !stallLogEnabled())
+        return;
+    const gl = renderer.getContext?.();
+    if (!gl)
+        return;
+    installed = true;
+    let inFrame = false;
+    let frame = { compiles: 0, uploads: 0, bgCompiles: 0, work: [], programs: new Set() };
+    const reset = () => { frame = { compiles: 0, uploads: 0, bgCompiles: 0, work: [], programs: new Set() }; };
+    const link = gl.linkProgram.bind(gl);
+    gl.linkProgram = (p) => { if (inFrame)
+        frame.compiles++;
+    else
+        frame.bgCompiles++; return link(p); };
+    for (const fn of ['texImage2D', 'texSubImage2D', 'texStorage2D', 'compressedTexImage2D']) {
+        const o = gl[fn]?.bind(gl);
+        if (o)
+            gl[fn] = (...a) => { if (inFrame)
+                frame.uploads++; return o(...a); };
+    }
+    // whose programs: three names a program after its material (name / type) when it builds it
+    const render = renderer.render.bind(renderer);
+    renderer.render = (scene, camera) => {
+        const outer = !inFrame;
+        inFrame = true;
+        const before = renderer.info?.programs?.length ?? 0;
+        try {
+            return render(scene, camera);
+        }
+        finally {
+            const after = renderer.info?.programs ?? [];
+            for (let i = before; i < after.length; i++)
+                frame.programs.add(String(after[i]?.name ?? '?'));
+            if (outer)
+                inFrame = false;
+        }
+    };
+    setWorkListener((label, ms) => { frame.work.push(`${label} ${Math.round(ms)}ms`); });
+    let last = performance.now();
+    const tick = () => {
+        const now = performance.now();
+        const dt = now - last;
+        last = now;
+        if (dt > STALL_MS) {
+            const parts = [
+                frame.compiles ? `${frame.compiles} compile(s) in the frame${frame.programs.size ? ` [${[...frame.programs].join(', ')}]` : ''}` : '',
+                frame.uploads ? `${frame.uploads} texture upload(s) in the frame` : '',
+                frame.work.length ? `work: ${frame.work.join(', ')}` : '',
+                frame.bgCompiles ? `${frame.bgCompiles} background compile(s)` : '',
+            ].filter(Boolean);
+            console.warn(`[3drise] stall ${Math.round(dt)}ms — ${parts.length ? parts.join(' · ') : 'nothing recorded (GPU / driver, GC, or other main-thread work)'}`);
+        }
+        reset();
+        requestAnimationFrame(tick);
+    };
+    requestAnimationFrame(tick);
+    console.info('[3drise] stall log on (frames over %dms) — localStorage.removeItem(\'3drise:stalls\') to switch it off', STALL_MS);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3driseai/3drise-viewer",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -39,6 +39,6 @@
   },
   "dependencies": {
     "@3driseai/3drise-common": "^1.0.1",
-    "@3driseai/3drise-core": "^1.0.24"
+    "@3driseai/3drise-core": "^1.0.25"
   }
 }