@3driseai/3drise-viewer 0.1.27 → 0.1.29

package/dist/components/SceneBuilder.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useImperativeHandle, useMemo, useRef, useState } from "react";
+import { forwardRef, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { EFFECT_CLIP_ASSET, effectClipFromAsset, setEffectClipTemplates } from "../operations/runtime.js";
 import { createSceneHandle } from "../api/sceneHandle.js";
 import { Canvas } from "@react-three/fiber";
 import { LIGHTING_PRESETS, SceneStore } from "@3driseai/3drise-core";
@@ -13,7 +14,10 @@ import ClipPlayer from "../animationsV2/ClipPlayer.js";
 import { normalizeClip, normalizeSequence } from "../animationsV2/normalize.js";
 import { resolveElementSettings } from "../animationsV2/elementSettings.js";
 import { Physics } from "@react-three/rapier";
-const SceneBuilder = forwardRef(({ project, width = "100%", height = "100vh", style = {}, className = "", onSceneInitialized, onSceneReady, onUiElementClick, onObjectClick, onObjectReady, onObjectDispose, }, ref) => {
+import UiLayers from "../ui/UiLayers.js";
+import { sceneReadiness, useSceneReady } from "../triggers/readiness.js";
+import UiAnchorUpdater from "../ui/UiAnchorUpdater.js";
+const SceneBuilder = forwardRef(({ project, width = "100%", height = "100vh", style = {}, className = "", onSceneInitialized, onSceneReady, loadingIndicator, ui = true, uiLayers, uiStyles, onObjectClick, onObjectReady, onObjectDispose, }, ref) => {
     const sceneSettings = (project.sceneSettingsData || {});
     // const meshController = useMeshController();
     const [isThreeJsMounted, setIsThreeJsMounted] = useState(false);
@@ -50,14 +54,42 @@ const SceneBuilder = forwardRef(({ project, width = "100%", height = "100vh", st
     const animationClips = useMemo(() => (rawClips || []).map(normalizeClip), [rawClips]);
     const animationSequences = useMemo(() => (rawSequences || []).map(normalizeSequence), [rawSequences]);
     const actionSequences = project.actionSequences || [];
+    // Effect clip templates the project links (its interactions and actions point at them).
+    const rawAssets = project.assets;
+    useEffect(() => {
+        setEffectClipTemplates((rawAssets ?? []).filter(a => a?.type === EFFECT_CLIP_ASSET).map(a => effectClipFromAsset(a)).filter(Boolean), 'project');
+    }, [rawAssets]);
     const clipAutoplay = useMemo(() => ({ sequences: animationSequences, clips: animationClips }), [animationSequences, animationClips]);
     // The external control handle (see api/sceneHandle). Built once; reads the
     // current project lists through a ref, so it never goes stale.
     const handleSource = useRef({ actions: actionSequences, clips: animationClips, sequences: animationSequences });
-    handleSource.current = { actions: actionSequences, clips: animationClips, sequences: animationSequences };
+    handleSource.current = { actions: actionSequences, clips: animationClips, sequences: animationSequences, objects: project.sceneObjects || sceneSettings.scene?.objectSettings || [] };
     const sceneHandle = useMemo(() => createSceneHandle(() => handleSource.current), []);
     useImperativeHandle(ref, () => sceneHandle, [sceneHandle]);
     const sceneObjects = project.sceneObjects || sceneSettings.scene?.objectSettings || [];
+    // Readiness: nothing runs (autoplay, object effects, onSceneReady) and the cover stays on until
+    // the canvas exists, every model has loaded or failed, shaders are compiled and a frame rendered.
+    const ready = useSceneReady();
+    const threeRef = useRef(null);
+    const onSceneReadyRef = useRef(onSceneReady);
+    onSceneReadyRef.current = onSceneReady;
+    const modelKey = sceneObjects.filter(o => o?.type === 'model').map(o => o.id).join(',');
+    // A layout effect: the gate must close before the canvas renders its children (R3F renders
+    // them after it has measured itself), or their effects would start ungated.
+    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();
+            },
+        });
+        if (threeRef.current)
+            sceneReadiness.report(CANVAS_READY); // remount with the canvas already there
+        const cancel = sceneReadiness.whenReady(() => onSceneReadyRef.current?.(sceneHandle));
+        setStarted(true);
+        return () => { cancel(); sceneReadiness.reset(); };
+    }, [modelKey, sceneHandle]);
     const modelObjects = sceneObjects.filter((obj) => obj.type === "model");
     const meshObjects = sceneObjects.filter((obj) => obj.type === "mesh");
     const sceneCanvas = sceneSettings.canvas || sceneSettings.scene?.canvas || {};
@@ -121,41 +153,39 @@ const SceneBuilder = forwardRef(({ project, width = "100%", height = "100vh", st
     //   };
     //   initializeSceneAssets();
     // }, [meshController, modelObjects, meshObjects]);
-    const handleElementClick = (element) => {
-        if (element && onUiElementClick) {
-            onUiElementClick(element);
-        }
-    };
-    return (_jsx("div", { className: className, style: containerStyle, children: _jsx(Canvas, { style: {
-                backgroundColor: backgroundColor,
-            }, shadows: shadows, dpr: dpr, gl: {
-                antialias,
-                alpha: true,
-                powerPreference: "high-performance",
-                ...gl,
-            }, camera: {
-                fov,
-                near,
-                far,
-                position: [position[0], position[1], position[2]],
-                rotation: [orientation[0], orientation[1], orientation[2]],
-            }, onCreated: (state) => {
-                state.gl.toneMapping = NoToneMapping;
-                setIsThreeJsMounted(true);
-                SceneStore.scene = state.scene;
-                SceneStore.gl = state.gl;
-                if (onSceneInitialized) {
-                    onSceneInitialized();
-                }
-                onSceneReady?.(sceneHandle);
-            }, children: _jsxs(Physics, { gravity: physicsSettings.gravity, paused: !physicsSettings.enabled, debug: physicsSettings.debug, children: [_jsx(LightsManager, { config: lighting[0], onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }), environment && _jsx(EnvironmentManager, { environment: environment, timeSettings: timeSettings, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }), _jsx(CameraController, { settings: camera, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }), _jsx(ObjectsRenderer, { cameraSettings: camera, generalObjectSettings: generalObjectSettings, createdObjects: sceneObjects, onObjectsReady: undefined, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose, sequences: animationSequences, clips: animationClips, actionSequences: actionSequences, handleObjectClick: onObjectClick ? (object, ref, event) => onObjectClick(object, ref, event) : undefined }), _jsx(ClipPlayer, { autoplay: clipAutoplay, getAction: (id) => actionSequences?.find((a) => a.id === id), getSettings: (state) => resolveElementSettings(state, {
-                            objects: sceneObjects,
-                            camera,
-                            sky: environment?.sky,
-                            clouds: environment?.clouds,
-                            ocean: environment?.ocean,
-                            terrain: environment?.terrain,
-                        }) }), _jsx(CursorController, { effects: project.cursor?.effects, clickActions: project.cursor?.clickActions, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose })] }) }) }));
+    return (_jsxs("div", { className: className, style: containerStyle, children: [_jsx(Canvas, { style: {
+                    backgroundColor: backgroundColor,
+                }, shadows: shadows, dpr: dpr, gl: {
+                    antialias,
+                    alpha: true,
+                    powerPreference: "high-performance",
+                    ...gl,
+                }, camera: {
+                    fov,
+                    near,
+                    far,
+                    position: [position[0], position[1], position[2]],
+                    rotation: [orientation[0], orientation[1], orientation[2]],
+                }, onCreated: (state) => {
+                    state.gl.toneMapping = NoToneMapping;
+                    setIsThreeJsMounted(true);
+                    SceneStore.scene = state.scene;
+                    SceneStore.gl = state.gl;
+                    if (onSceneInitialized) {
+                        onSceneInitialized();
+                    }
+                    threeRef.current = { gl: state.gl, scene: state.scene, camera: state.camera };
+                    sceneReadiness.report(CANVAS_READY);
+                }, children: _jsxs(Physics, { gravity: physicsSettings.gravity, paused: !physicsSettings.enabled, debug: physicsSettings.debug, children: [_jsx(LightsManager, { config: lighting[0], onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }), environment && _jsx(EnvironmentManager, { environment: environment, timeSettings: timeSettings, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }), _jsx(CameraController, { settings: camera, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }), _jsx(ObjectsRenderer, { cameraSettings: camera, generalObjectSettings: generalObjectSettings, createdObjects: sceneObjects, onObjectsReady: undefined, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose, sequences: animationSequences, clips: animationClips, actionSequences: actionSequences, handleObjectClick: onObjectClick ? (object, ref, event) => onObjectClick(object, ref, event) : undefined }), _jsx(ClipPlayer, { autoplay: clipAutoplay, getAction: (id) => actionSequences?.find((a) => a.id === id), getSettings: (state) => resolveElementSettings(state, {
+                                objects: sceneObjects,
+                                camera,
+                                sky: environment?.sky,
+                                clouds: environment?.clouds,
+                                ocean: environment?.ocean,
+                                terrain: environment?.terrain,
+                            }) }), _jsx(CursorController, { effects: project.cursor?.effects, clickActions: project.cursor?.clickActions, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }), _jsx(UiAnchorUpdater, {})] }) }), ui && _jsx(UiLayers, { layers: uiLayers ?? project.uiLayers, scene: sceneHandle, extraCss: uiStyles }), (!started || !ready) && (_jsx("div", { style: { position: 'absolute', inset: 0, zIndex: 1000, backgroundColor, display: 'flex', alignItems: 'center', justifyContent: 'center' }, children: loadingIndicator }))] }));
 });
 SceneBuilder.displayName = 'SceneBuilder';
+/** Readiness entry for "the canvas exists" (its renderer is what compiles the shaders). */
+const CANVAS_READY = '__canvas__';
 export default SceneBuilder;

package/dist/components/SkyController.d.ts

@@ -4,8 +4,32 @@ export interface SkyControllerProps extends ObjectReadyProps {
     settings: SkySettings;
     timeSettings: TimeSettings;
     scale?: number;
+    /** Unused since time of day stopped writing its values back into the
+     *  settings (they are the day look now, not a mirror of the clock). Kept so
+     *  existing hosts still type-check. */
     onSettingsChange?: (settings: SkySettings) => void;
 }
-declare function SkyController({ settings, timeSettings, scale, onSettingsChange, onObjectReady, onObjectDispose, }: SkyControllerProps): any;
+/**
+ * The analytic (Preetham) sky.
+ *
+ * What it draws, each frame, in order:
+ *   1. the stored settings — or, while time of day is enabled, the time-driven
+ *      sun and atmosphere (time owns all six knobs then);
+ *   2. the `sky` keyframe domain        (settings.animations.sky)
+ *   3. the `sky` pointer domain on top  (settings.mouseMove.sky)
+ *   4. a controller's live drag         (SKY_LIVE_KEY handle on the mesh)
+ * With time of day on, the clock owns the sun's position (elevation/azimuth), and
+ * 1–4 above are the DAY look: atmosphereForSunElevation blends them into golden
+ * hour, twilight and night by the sun's height. Sliders, keyframes and pointer
+ * bindings on the atmosphere keep working with the clock running.
+ *
+ * Whatever it draws is published per scene (renderedSky) so the key light, the
+ * clouds, the water and the terrain are lit by the same sun and atmosphere.
+ *
+ * It draws only. The sun LIGHT is SkySystem's SunLight, which reads what this
+ * publishes; a second light here used to double the sun (always white, always
+ * on, lit from below the ground at night).
+ */
+declare function SkyController({ settings, timeSettings, scale, onObjectReady, onObjectDispose }: SkyControllerProps): import("react").JSX.Element;
 export default SkyController;
 //# sourceMappingURL=SkyController.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"SkyController.d.ts","sourceRoot":"","sources":["../../src/components/SkyController.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAQ7D,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAEvE,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IACxD,QAAQ,EAAE,WAAW,CAAC;IACtB,YAAY,EAAE,YAAY,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;CACtD;AAED,iBAAS,aAAa,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,eAAe,GAAG,EAAE,kBAAkB,GA+I8H,GAAG,CACtQ;AA6BD,eAAe,aAAa,CAAC"}
+{"version":3,"file":"SkyController.d.ts","sourceRoot":"","sources":["../../src/components/SkyController.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAiB7D,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGvE,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IACxD,QAAQ,EAAE,WAAW,CAAC;IACtB,YAAY,EAAE,YAAY,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;2CAEuC;IACvC,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;CACtD;AAsBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,iBAAS,aAAa,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAY,EAAE,aAAa,EAAE,eAAe,EAAE,EAAE,kBAAkB,+BAyMlH;AAED,eAAe,aAAa,CAAC"}

package/dist/components/SkyController.js

@@ -1,91 +1,116 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { useObjectReady } from '../hooks/useObjectReady.js';
-import { useRef, useEffect, useCallback } from 'react';
-import { useFrame } from '@react-three/fiber';
-import { useSkyUniforms } from '../hooks/useSkyUniforms.js';
-import { useSkyAnimation } from '../hooks/useSkyAnimation.js';
-import { useSkySystem } from '../hooks/useSkySystem.js';
-import { findById } from '../utils/sceneQuery.js';
-import { cubeCameraManager } from '@3driseai/3drise-core';
+import { useRef, useEffect, useCallback, useMemo } from 'react';
+import { useFrame, useThree } from '@react-three/fiber';
+import { SKY_LIVE_KEY } from '../hooks/useSkyLive.js';
+import { createSunPosition } from '../utils/utils3d.js';
+import { applyConfigKeyframeAnimations, applyConfigMouseMove, hasConfigOverrides, resolveConfig, } from '../utils/configAnimations.js';
+import { publishRenderedSky, clearRenderedSky } from '../utils/renderedSky.js';
+import { cubeCameraManager, getAnimatableProperties, skySystemManager, atmosphereForSunElevation, skyBrightnessForSunElevation, nightAmount } from '@3driseai/3drise-core';
 import SkyMesh from './SkyMesh.js';
-function SkyController({ settings, timeSettings, scale = 1000, onSettingsChange, onObjectReady, onObjectDispose, }) {
+/** The sky's animatable knobs, from the property registry — the same list the
+ *  Animation and MouseMove panels offer, so a binding can never target a knob
+ *  this loop does not push. */
+const SKY_ANIMATABLE = new Set(getAnimatableProperties({ type: 'sky' }, 'sky').map(p => p.value));
+/** While the sky is being driven, refresh the environment probe at most this often.
+ *  Six cube faces per frame is the one thing an animated sky must never do. */
+const ENV_REFRESH_MS = 500;
+const renderedOf = (s) => ({
+    turbidity: s.turbidity ?? 2,
+    rayleigh: s.rayleigh ?? 1,
+    mieCoefficient: s.mieCoefficient ?? 0.005,
+    mieDirectionalG: s.mieDirectionalG ?? 0.7,
+    elevation: s.elevation ?? 0,
+    azimuth: s.azimuth ?? 0,
+});
+/**
+ * The analytic (Preetham) sky.
+ *
+ * What it draws, each frame, in order:
+ *   1. the stored settings — or, while time of day is enabled, the time-driven
+ *      sun and atmosphere (time owns all six knobs then);
+ *   2. the `sky` keyframe domain        (settings.animations.sky)
+ *   3. the `sky` pointer domain on top  (settings.mouseMove.sky)
+ *   4. a controller's live drag         (SKY_LIVE_KEY handle on the mesh)
+ * With time of day on, the clock owns the sun's position (elevation/azimuth), and
+ * 1–4 above are the DAY look: atmosphereForSunElevation blends them into golden
+ * hour, twilight and night by the sun's height. Sliders, keyframes and pointer
+ * bindings on the atmosphere keep working with the clock running.
+ *
+ * Whatever it draws is published per scene (renderedSky) so the key light, the
+ * clouds, the water and the terrain are lit by the same sun and atmosphere.
+ *
+ * It draws only. The sun LIGHT is SkySystem's SunLight, which reads what this
+ * publishes; a second light here used to double the sun (always white, always
+ * on, lit from below the ground at night).
+ */
+function SkyController({ settings, timeSettings, scale = 1000, onObjectReady, onObjectDispose }) {
     const skyRef = useRef(null);
     const rootRef = useRef(null);
     useObjectReady(rootRef, settings, onObjectReady, onObjectDispose);
-    const sunLightRef = useRef(null);
-    const isAnimatingRef = useRef(false);
     const previousSettings = useRef(null);
-    // const cubeCameraManager = CubeCameraManager.getInstance();
-    const { updateUniforms, getCurrentValues } = useSkyUniforms();
-    const { animateSkyTransition } = useSkyAnimation();
+    const scene = useThree(s => s.scene);
+    const timeOwns = !!(settings.visible && timeSettings?.enabled);
+    // Frame scratch, kept in refs so a keyframed turbidity does not re-render React.
+    const override = useRef({});
+    const startValues = useRef({});
+    const liveRef = useRef({});
+    const animStart = useRef(0);
+    const driving = useRef(false);
+    const lastEnvRefresh = useRef(0);
+    const envDirty = useRef(false);
+    const timeAtmos = useRef({ turbidity: 0, rayleigh: 0, mieCoefficient: 0, mieDirectionalG: 0 });
+    const timeApplied = useRef(null);
+    // Restart the keyframes from their beginning whenever they are edited.
     useEffect(() => {
-        return () => {
-            sunLightRef.current?.shadow?.map?.dispose();
-        };
-    }, []);
+        animStart.current = performance.now();
+        startValues.current = {};
+    }, [settings.animations]);
+    // A slider end commits the dragged value, which arrives here as new settings.
+    useEffect(() => { liveRef.current = {}; }, [settings]);
     useEffect(() => {
-        handleSettings(settings);
-    }, [settings]);
-    const handleTimeUpdate = useCallback((state) => {
-        const { sunAzimuth, sunElevation, timeInHours } = state;
-        const atmosphericParams = calculateSkyParamsForTime(timeInHours);
-        const newSettings = {
-            ...settings,
-            elevation: sunElevation,
-            azimuth: sunAzimuth,
-            ...atmosphericParams,
+        return () => {
+            clearRenderedSky(scene);
         };
-        // While time is advancing, the environment probe is already re-capturing
-        // the cube map on its own timer. Letting handleSettings capture as well
-        // meant six faces rendered from two independent schedulers for the same
-        // moving sun.
-        const applied = handleSettings(newSettings, state.advancing);
-        // Only on a real change, and only when time is not running: this runs
-        // every frame now, and an unconditional call would dispatch a settings
-        // write per frame in a host that supplies this callback.
-        if (applied && !state.advancing) {
-            onSettingsChange?.(newSettings);
+    }, [scene]);
+    /** Push the six knobs into the sky shader. Writes this mesh, never a findById
+     *  result, so a second canvas cannot drive the editor's sky. */
+    const applyUniforms = useCallback((values) => {
+        const uniforms = skyRef.current?.material?.uniforms;
+        if (!uniforms)
+            return;
+        if (values.turbidity !== undefined)
+            uniforms.turbidity.value = values.turbidity;
+        if (values.rayleigh !== undefined)
+            uniforms.rayleigh.value = values.rayleigh;
+        if (values.mieCoefficient !== undefined)
+            uniforms.mieCoefficient.value = values.mieCoefficient;
+        if (values.mieDirectionalG !== undefined)
+            uniforms.mieDirectionalG.value = values.mieDirectionalG;
+        if (values.elevation !== undefined && values.azimuth !== undefined && uniforms.sunPosition) {
+            uniforms.sunPosition.value.copy(createSunPosition(values.elevation, values.azimuth));
         }
-    }, [settings, onSettingsChange]);
-    useSkySystem({
-        timeSettings,
-        onTimeUpdate: handleTimeUpdate,
-        enabled: settings.visible && timeSettings.enabled,
-    });
-    const handleSkyMeshReady = useCallback((object, mesh) => {
-        skyRef.current = mesh;
-        updateUniforms(settings);
-        previousSettings.current = { ...settings };
-        onObjectReady && onObjectReady(object, mesh);
-    }, [settings, updateUniforms, onObjectReady]);
+        // Darken the dome after sunset (see SkyMesh addNightDarkening). By the
+        // sun's height, so a hand-set sun below the horizon gets night too.
+        if (values.elevation !== undefined && uniforms.uSkyBrightness) {
+            uniforms.uSkyBrightness.value = skyBrightnessForSunElevation(values.elevation);
+            const n = nightAmount(values.elevation);
+            uniforms.uNightTint.value.set(0.0006 * n, 0.0016 * n, 0.0045 * n);
+        }
+    }, []);
     const toggleSky = useCallback((show) => {
         if (!skyRef.current)
             return;
         skyRef.current.visible = show;
-        if (sunLightRef.current)
-            sunLightRef.current.visible = show;
         if (!show) {
             cubeCameraManager.dispose();
+            clearRenderedSky(scene);
         }
         else {
             cubeCameraManager.updateEnvironment();
         }
-    }, []);
-    const updateSun = useCallback(() => {
-        if (!skyRef.current?.material || !sunLightRef.current)
-            return;
-        const uniforms = skyRef.current.material.uniforms;
-        if (!uniforms?.sunPosition)
-            return;
-        const distance = 100;
-        const sp = uniforms.sunPosition.value;
-        sunLightRef.current.position.set(sp.x * distance, sp.y * distance, sp.z * distance);
-        sunLightRef.current.shadow.camera.updateProjectionMatrix();
-        const moon = findById('3drise-moon');
-        if (moon)
-            moon.position.set(sp.x * scale, sp.y * scale, sp.z * scale);
-    }, [scale]);
-    const hasActualChanges = useCallback((next, prev) => {
+    }, [scene]);
+    const hasActualChanges = (next, prev) => {
         if (!prev)
             return true;
         return (next.visible !== prev.visible ||
@@ -95,16 +120,12 @@ function SkyController({ settings, timeSettings, scale = 1000, onSettingsChange,
             Math.abs(next.mieDirectionalG - prev.mieDirectionalG) > 0.001 ||
             Math.abs(next.elevation - prev.elevation) > 0.1 ||
             Math.abs(next.azimuth - prev.azimuth) > 0.1);
-    }, []);
-    const handleCompletedUniforms = (_finalValues) => {
-        isAnimatingRef.current = false;
-        cubeCameraManager.updateEnvironment();
     };
-    /** Returns whether the settings were actually applied, so callers can tell a
-     *  real change from a no-op. `skipEnvUpdate` leaves the cube-camera capture
-     *  to whoever else is already scheduling it. */
+    /** Applies a settings object (stored or time-driven). Returns whether anything
+     *  changed. `skipEnvUpdate` leaves the cube capture to whoever already
+     *  schedules it (the probe re-captures on its own timer while time advances). */
     const handleSettings = (newSettings, skipEnvUpdate = false) => {
-        if (!skyRef.current || isAnimatingRef.current || !newSettings)
+        if (!skyRef.current || !newSettings)
             return false;
         if (!hasActualChanges(newSettings, previousSettings.current))
             return false;
@@ -115,68 +136,106 @@ function SkyController({ settings, timeSettings, scale = 1000, onSettingsChange,
             previousSettings.current = { ...newSettings };
             return false;
         }
-        updateUniforms(newSettings);
-        updateSun();
-        if (!skipEnvUpdate) {
+        applyUniforms(newSettings);
+        publishRenderedSky(scene, renderedOf(newSettings));
+        if (!skipEnvUpdate)
             cubeCameraManager.updateEnvironment();
-        }
         previousSettings.current = { ...newSettings };
         return true;
     };
-    const handleMouseMove = (mouse) => {
-        const handlers = settings.handlers;
-        if (!handlers || isAnimatingRef.current || !skyRef.current)
+    // With the clock on, the frame loop draws; applying stored elevation here would
+    // flash the authored sun for a frame. Re-runs when the clock is switched off so
+    // the stored sky comes back.
+    useEffect(() => {
+        if (timeOwns)
             return;
-        if (!handlers.onMouseMove?.enabled)
+        handleSettings(settings);
+    }, [settings, timeOwns]);
+    const liveHandle = useMemo(() => ({
+        set: (key, value) => { liveRef.current[key] = value; },
+    }), []);
+    const attachLive = (mesh) => {
+        if (mesh)
+            mesh.userData[SKY_LIVE_KEY] = liveHandle;
+    };
+    useEffect(() => {
+        const mesh = skyRef.current;
+        attachLive(mesh);
+        return () => { if (mesh)
+            delete mesh.userData[SKY_LIVE_KEY]; };
+    }, [liveHandle]);
+    const handleSkyMeshReady = useCallback((object, mesh) => {
+        skyRef.current = mesh;
+        attachLive(mesh);
+        applyUniforms(settings);
+        if (settings.visible)
+            publishRenderedSky(scene, renderedOf(settings));
+        previousSettings.current = { ...settings };
+        onObjectReady && onObjectReady(object, mesh);
+    }, [settings, applyUniforms, onObjectReady, scene]);
+    /** Clock on: the clock's sun, the day look blended by the sun's height. Pushes
+     *  only on a visible change, and leaves the cube capture to the probe while
+     *  time is advancing (it refreshes on sun movement); a manual seek or a slider
+     *  re-captures here, trailing-throttled so a scrub ends on a fresh capture. */
+    const drawTimeOfDay = (day) => {
+        const sky = skyRef.current;
+        if (!sky)
             return;
-        let updated = { ...settings };
-        handlers.onMouseMove.properties.forEach((propConfig) => {
-            const { property } = propConfig;
-            const { sensitivity, min: minVal, max: maxVal, axis } = propConfig.propertySettings;
-            let movement = axis === 'x' ? mouse.x * sensitivity
-                : axis === 'y' ? mouse.y * sensitivity
-                    : (mouse.x + mouse.y) * 0.5 * sensitivity;
-            if (movement !== 0) {
-                let newVal = updated[property] + movement;
-                if (typeof minVal === 'number')
-                    newVal = Math.max(newVal, minVal);
-                if (typeof maxVal === 'number')
-                    newVal = Math.min(newVal, maxVal);
-                updated[property] = newVal;
-            }
-        });
-        handleSettings(updated);
+        if (!sky.visible)
+            toggleSky(true);
+        const t = skySystemManager.getState();
+        const atmos = atmosphereForSunElevation(t.sunElevation, day, timeAtmos.current);
+        const next = { ...day, ...atmos, visible: true, elevation: t.sunElevation, azimuth: t.sunAzimuth };
+        if (hasActualChanges(next, timeApplied.current)) {
+            applyUniforms(next);
+            publishRenderedSky(scene, renderedOf(next));
+            timeApplied.current = next;
+            previousSettings.current = next;
+            if (!t.advancing)
+                envDirty.current = true;
+        }
+        const now = performance.now();
+        if (envDirty.current && now - lastEnvRefresh.current > ENV_REFRESH_MS) {
+            envDirty.current = false;
+            lastEnvRefresh.current = now;
+            cubeCameraManager.updateEnvironment();
+        }
     };
     useFrame((state) => {
-        handleMouseMove({ x: state.pointer.x, y: state.pointer.y });
-    });
-    return (_jsxs("group", { ref: rootRef, children: [_jsx(SkyMesh, { ref: skyRef, settings: settings, scale: scale, onObjectReady: handleSkyMeshReady, onObjectDispose: onObjectDispose }), settings.visible && (_jsx("directionalLight", { ref: sunLightRef, color: "#ffffff", intensity: 1, castShadow: true }))] }));
-}
-function calculateSkyParamsForTime(timeInHours) {
-    const nightParams = { turbidity: 0.5, rayleigh: 0.1, mieCoefficient: 0.001, mieDirectionalG: 0.8 };
-    const sunriseParams = { turbidity: 4, rayleigh: 3, mieCoefficient: 0.01, mieDirectionalG: 0.9 };
-    const dayParams = { turbidity: 0.7, rayleigh: 0.54, mieCoefficient: 0.005, mieDirectionalG: 0.7 };
-    const sunsetParams = { turbidity: 4.5, rayleigh: 3.5, mieCoefficient: 0.012, mieDirectionalG: 0.92 };
-    const lerp = (a, b, t) => a + (b - a) * Math.max(0, Math.min(1, t));
-    const ss = (t) => t * t * (3 - 2 * t);
-    const lerpP = (from, to, t) => ({
-        turbidity: lerp(from.turbidity, to.turbidity, ss(t)),
-        rayleigh: lerp(from.rayleigh, to.rayleigh, ss(t)),
-        mieCoefficient: lerp(from.mieCoefficient, to.mieCoefficient, ss(t)),
-        mieDirectionalG: lerp(from.mieDirectionalG, to.mieDirectionalG, ss(t)),
+        if (!skyRef.current || !settings.visible)
+            return;
+        const o = override.current;
+        const base = settings;
+        applyConfigKeyframeAnimations(settings.animations?.sky?.animations, startValues.current, base, o, performance.now() - animStart.current, SKY_ANIMATABLE);
+        const mm = settings.mouseMove;
+        if (mm?.enabled && mm.sky?.enabled) {
+            applyConfigMouseMove(mm.sky.properties, base, o, state.pointer, SKY_ANIMATABLE);
+        }
+        if (timeOwns) {
+            drawTimeOfDay(resolveConfig(settings, o, liveRef.current));
+            return;
+        }
+        timeApplied.current = null;
+        if (hasConfigOverrides(o) || hasConfigOverrides(liveRef.current)) {
+            const resolved = resolveConfig(settings, o, liveRef.current);
+            applyUniforms(resolved);
+            publishRenderedSky(scene, renderedOf(resolved));
+            driving.current = true;
+            const now = performance.now();
+            if (now - lastEnvRefresh.current > ENV_REFRESH_MS) {
+                lastEnvRefresh.current = now;
+                cubeCameraManager.updateEnvironment();
+            }
+        }
+        else if (driving.current) {
+            // A binding was removed or the pointer stopped mattering: go back to the
+            // stored sky once, including the probe.
+            driving.current = false;
+            applyUniforms(settings);
+            publishRenderedSky(scene, renderedOf(settings));
+            cubeCameraManager.updateEnvironment();
+        }
     });
-    if (timeInHours < 5)
-        return nightParams;
-    if (timeInHours < 6.5)
-        return lerpP(nightParams, sunriseParams, (timeInHours - 5) / 1.5);
-    if (timeInHours < 8)
-        return lerpP(sunriseParams, dayParams, (timeInHours - 6.5) / 1.5);
-    if (timeInHours < 17)
-        return dayParams;
-    if (timeInHours < 19)
-        return lerpP(dayParams, sunsetParams, (timeInHours - 17) / 2);
-    if (timeInHours < 21)
-        return lerpP(sunsetParams, nightParams, (timeInHours - 19) / 2);
-    return nightParams;
+    return (_jsx("group", { ref: rootRef, children: _jsx(SkyMesh, { ref: skyRef, settings: settings, scale: scale, onObjectReady: handleSkyMeshReady, onObjectDispose: onObjectDispose }) }));
 }
 export default SkyController;

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

@@ -1 +1 @@
-{"version":3,"file":"SkyMesh.d.ts","sourceRoot":"","sources":["../../src/components/SkyMesh.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAI7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IAClD,QAAQ,EAAE,WAAW,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAGD,QAAA,MAAM,OAAO,EA2BP,GAAI,CAAC;AAEX,eAAe,OAAO,CAAC"}
+{"version":3,"file":"SkyMesh.d.ts","sourceRoot":"","sources":["../../src/components/SkyMesh.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAK7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IAClD,QAAQ,EAAE,WAAW,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAqBD,QAAA,MAAM,OAAO,EAgCP,GAAI,CAAC;AAEX,eAAe,OAAO,CAAC"}

package/dist/components/SkyMesh.js

@@ -2,12 +2,37 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useObjectReady } from '../hooks/useObjectReady.js';
 import React, { useRef, useMemo, useEffect } from 'react';
 import { Sky } from 'three/examples/jsm/objects/Sky.js';
+import { Vector3 } from "three";
+import { SKY_ID } from "@3driseai/3drise-core";
+/**
+ * Lets SkyController darken the dome after sunset. Preetham alone bottoms out at
+ * a flat grey (its constant 0.1 base term), which reads as overcast dusk, not
+ * night. `uSkyBrightness` scales the output (1 by day, core
+ * skyBrightnessForSunElevation), `uNightTint` adds a faint blue so the dark sky
+ * is not neutral grey. Patched by string: if a three upgrade changes the line,
+ * the sky simply stays undarkened rather than breaking.
+ */
+const SKY_OUT = 'gl_FragColor = vec4( retColor, 1.0 );';
+function addNightDarkening(material) {
+    material.uniforms.uSkyBrightness = { value: 1 };
+    material.uniforms.uNightTint = { value: new Vector3(0, 0, 0) };
+    if (!material.fragmentShader.includes(SKY_OUT))
+        return;
+    material.fragmentShader = material.fragmentShader
+        .replace('void main() {', 'uniform float uSkyBrightness;\nuniform vec3 uNightTint;\nvoid main() {')
+        .replace(SKY_OUT, 'gl_FragColor = vec4( retColor * uSkyBrightness + uNightTint, 1.0 );');
+}
 const SkyMesh = React.forwardRef(({ settings, scale = 1000, onObjectReady, onObjectDispose }, ref) => {
     const meshRef = useRef(null);
     useObjectReady(meshRef, settings, onObjectReady, onObjectDispose);
     const skyObject = useMemo(() => {
         const sky = new Sky();
+        addNightDarkening(sky.material);
         sky.scale.setScalar(scale);
+        // Set once on the object, never as a userData JSX prop: R3F replaces the
+        // whole userData object on every render, which would drop the live handle
+        // SkyController hangs here.
+        sky.userData.id = SKY_ID;
         return sky;
     }, [scale]);
     useEffect(() => {
@@ -28,7 +53,7 @@ const SkyMesh = React.forwardRef(({ settings, scale = 1000, onObjectReady, onObj
         else if (ref)
             ref.current = node;
     };
-    return (_jsx("primitive", { ref: combinedRef, object: skyObject, visible: settings.visible, scale: scale, userData: { id: '3drise-sky' } }));
+    return (_jsx("primitive", { ref: combinedRef, object: skyObject, visible: settings.visible, scale: scale }));
 });
 SkyMesh.displayName = 'SkyMesh';
 export default SkyMesh;

package/dist/components/SkyStars.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import type { SkySettings, SkyStarsSettings, TimeSettings } from '@3driseai/3drise-core';
+export interface SkyStarsProps {
+    timeSettings: TimeSettings;
+    skySettings?: SkySettings;
+    /** The stars block of SkySettings; missing fields fill in from SKY_STARS_DEFAULTS. */
+    stars?: SkyStarsSettings | null;
+}
+declare const SkyStars: React.FC<SkyStarsProps>;
+export default SkyStars;
+//# sourceMappingURL=SkyStars.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SkyStars.d.ts","sourceRoot":"","sources":["../../src/components/SkyStars.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAqC,MAAM,OAAO,CAAC;AAI1D,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGzF,MAAM,WAAW,aAAa;IAC1B,YAAY,EAAE,YAAY,CAAC;IAC3B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,sFAAsF;IACtF,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACnC;AA4HD,QAAA,MAAM,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC,aAAa,CA8DrC,CAAC;AAEF,eAAe,QAAQ,CAAC"}