@3driseai/3drise-viewer 0.1.28 → 0.1.29

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

package/dist/components/SkyStars.js

@@ -0,0 +1,187 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { useFrame } from '@react-three/fiber';
+import { nightAmount, skySystemManager, normalizeSkyStars } from '@3driseai/3drise-core';
+import { useCloudSun } from '../hooks/useCloudSun.js';
+/**
+ * The night sky's stars, built into the sky for either renderer.
+ *
+ * A star dome centred on the camera just inside the far plane (the sky is drawn
+ * at the far plane, so stars sit in front of it and terrain occludes them).
+ * Brightness follows a magnitude-like distribution — a few bright stars, many
+ * faint ones — with a slight colour temperature spread and a gentle twinkle.
+ *
+ * With the clock on they appear with the night (nightAmount: by the SUN'S HEIGHT,
+ * the same phase keys as the atmosphere), fade toward the horizon where real air
+ * extinguishes them, and turn about the celestial pole with the clock: rising in
+ * the same quarter the sun rises, setting where it sets. With the clock off they
+ * are a stand-alone layer: on whenever `stars.visible` is, at full strength.
+ */
+/** Height of the celestial pole above the horizon = observer latitude. */
+const LATITUDE_DEG = 40;
+/** North is opposite the noon sun. The noon sun is toward +X in core's
+ *  convention, so the pole leans toward −X. */
+const POLE = new THREE.Vector3(-Math.cos(THREE.MathUtils.degToRad(LATITUDE_DEG)), Math.sin(THREE.MathUtils.degToRad(LATITUDE_DEG)), 0).normalize();
+/** Sidereal day, hours: the sky turns once in this much clock time. */
+const SIDEREAL_HOURS = 23.934;
+const vertexShader = /* glsl */ `
+attribute float aMag;
+attribute float aPhase;
+attribute vec3 aTint;
+uniform float uTime;
+uniform float uNight;
+uniform float uPixelRatio;
+uniform float uBrightness;
+uniform float uSize;
+uniform float uTwinkle;
+uniform float uWarmth;
+varying vec3 vColor;
+varying float vAlpha;
+void main() {
+    vec4 world = modelMatrix * vec4(position, 1.0);
+    // direction from the camera: stars live on a camera-centred dome
+    vec3 dir = normalize(world.xyz - cameraPosition);
+    float horizon = smoothstep(-0.02, 0.18, dir.y);          // extinction near the horizon
+    // twinkle depth: 0 = steady, 1 = the full 36% flicker
+    float twinkle = 1.0 - 0.36 * uTwinkle * (0.5 + 0.5 * sin(uTime * (1.3 + aPhase * 2.1) + aPhase * 37.0));
+    float b = aMag * twinkle * horizon * uNight * uBrightness;
+    // aTint holds the full-temperature colour; uWarmth blends it toward white
+    vColor = mix(vec3(1.0), aTint, uWarmth);
+    vAlpha = b;
+    gl_PointSize = (1.0 + 2.6 * aMag) * uPixelRatio * uSize;
+    gl_Position = projectionMatrix * viewMatrix * world;
+}
+`;
+const fragmentShader = /* glsl */ `
+varying vec3 vColor;
+varying float vAlpha;
+void main() {
+    vec2 d = gl_PointCoord * 2.0 - 1.0;
+    float r2 = dot(d, d);
+    if (r2 > 1.0 || vAlpha < 0.003) discard;
+    float core = exp(-r2 * 4.0);
+    gl_FragColor = vec4(vColor * core * vAlpha, 1.0);
+}
+`;
+/** Great-circle normal of the Milky Way band: tilted ~60° from the celestial pole
+ *  (the real galactic plane is ~63° off), so the band arches across the sky
+ *  rather than circling the pole. */
+const BAND_NORMAL = new THREE.Vector3(0.5, 0.55, 0.67).normalize();
+const BAND_U = new THREE.Vector3().crossVectors(BAND_NORMAL, new THREE.Vector3(0, 1, 0)).normalize();
+const BAND_V = new THREE.Vector3().crossVectors(BAND_NORMAL, BAND_U).normalize();
+/** Box–Muller normal deviate. */
+const gauss = () => Math.sqrt(-2 * Math.log(1 - Math.random())) * Math.cos(Math.random() * Math.PI * 2);
+/**
+ * Builds the dome. `milkyWay` (0..1) moves that fraction (× 0.7) of the stars into a
+ * dense band of faint stars along a great circle, with a wider, sparser halo — the
+ * unresolved glow reads as the band even though every point is still a star. The
+ * full colour-temperature tint is baked per star; the shader scales it by warmth.
+ */
+function buildStars(count, milkyWay) {
+    const pos = new Float32Array(count * 3);
+    const mag = new Float32Array(count);
+    const phase = new Float32Array(count);
+    const tint = new Float32Array(count * 3);
+    const inBand = Math.round(count * 0.7 * THREE.MathUtils.clamp(milkyWay, 0, 1));
+    const p = new THREE.Vector3();
+    for (let i = 0; i < count; i++) {
+        if (i < inBand) {
+            // along the band: uniform angle; across it: gaussian, 60% in a tight core, 40% in a halo
+            const a = Math.random() * Math.PI * 2;
+            const sigma = Math.random() < 0.6 ? 0.07 : 0.22;
+            const lat = THREE.MathUtils.clamp(gauss() * sigma, -1.2, 1.2);
+            p.copy(BAND_U).multiplyScalar(Math.cos(a) * Math.cos(lat))
+                .addScaledVector(BAND_V, Math.sin(a) * Math.cos(lat))
+                .addScaledVector(BAND_NORMAL, Math.sin(lat));
+            // the band is dust: many faint stars, rarely a bright one
+            mag[i] = 0.06 + 0.3 * Math.pow(Math.random(), 3);
+        }
+        else {
+            // uniform on the sphere
+            const u = Math.random() * 2 - 1;
+            const th = Math.random() * Math.PI * 2;
+            const sr = Math.sqrt(1 - u * u);
+            p.set(sr * Math.cos(th), u, sr * Math.sin(th));
+            // many faint, few bright
+            mag[i] = 0.12 + 0.88 * Math.pow(Math.random(), 6);
+        }
+        pos[i * 3] = p.x;
+        pos[i * 3 + 1] = p.y;
+        pos[i * 3 + 2] = p.z;
+        phase[i] = Math.random();
+        const t = Math.random();
+        // full temperature spread (warmth 1): blue giants, orange dwarfs, the rest near white
+        const c = t < 0.12 ? [0.62, 0.74, 1.0] : t < 0.25 ? [1.0, 0.8, 0.55] : [1.0, 0.97, 0.92];
+        tint.set(c, i * 3);
+    }
+    const g = new THREE.BufferGeometry();
+    g.setAttribute('position', new THREE.BufferAttribute(pos, 3));
+    g.setAttribute('aMag', new THREE.BufferAttribute(mag, 1));
+    g.setAttribute('aPhase', new THREE.BufferAttribute(phase, 1));
+    g.setAttribute('aTint', new THREE.BufferAttribute(tint, 3));
+    return g;
+}
+const SkyStars = ({ timeSettings, skySettings, stars }) => {
+    const pointsRef = useRef(null);
+    const { update } = useCloudSun({ skySettings, timeSettings });
+    const { count, milkyWay, brightness, size, twinkle, warmth } = normalizeSkyStars(stars);
+    // Structural: a new dome only when count or the band changes.
+    const geometry = useMemo(() => buildStars(count, milkyWay), [count, milkyWay]);
+    const material = useMemo(() => new THREE.ShaderMaterial({
+        uniforms: {
+            uTime: { value: 0 },
+            uNight: { value: 0 },
+            uPixelRatio: { value: 1 },
+            uBrightness: { value: 1 },
+            uSize: { value: 1 },
+            uTwinkle: { value: 0.5 },
+            uWarmth: { value: 0.5 },
+        },
+        vertexShader,
+        fragmentShader,
+        transparent: true,
+        depthWrite: false,
+        depthTest: true,
+        blending: THREE.AdditiveBlending,
+        fog: false,
+        toneMapped: false,
+    }), []);
+    useEffect(() => () => geometry.dispose(), [geometry]);
+    useEffect(() => () => material.dispose(), [material]);
+    const spin = useMemo(() => new THREE.Quaternion(), []);
+    useFrame(({ camera, gl, clock }) => {
+        const points = pointsRef.current;
+        if (!points)
+            return;
+        // With the clock on, the stars belong to the day cycle: they come out as the sun
+        // sets (nightAmount). With the clock off they stand alone — the user adds them
+        // whenever they want, at full strength, whatever the sun's elevation.
+        let night = 1;
+        if (timeSettings?.enabled) {
+            const sunDir = update().direction;
+            const sunElevation = THREE.MathUtils.radToDeg(Math.asin(THREE.MathUtils.clamp(sunDir.y, -1, 1)));
+            night = nightAmount(sunElevation);
+        }
+        if (night <= 0.001) {
+            points.visible = false;
+            return;
+        }
+        points.visible = true;
+        const far = camera.far ?? 1000;
+        points.position.copy(camera.position);
+        points.scale.setScalar(far * 0.85);
+        // Turn with the clock about the pole, same sense as the sun (rises −Z, sets +Z).
+        const hours = timeSettings?.enabled ? skySystemManager.getTimeInHours() : 0;
+        points.quaternion.copy(spin.setFromAxisAngle(POLE, -(hours / SIDEREAL_HOURS) * Math.PI * 2));
+        material.uniforms.uTime.value = clock.elapsedTime;
+        material.uniforms.uNight.value = night;
+        material.uniforms.uPixelRatio.value = gl.getPixelRatio();
+        material.uniforms.uBrightness.value = brightness;
+        material.uniforms.uSize.value = size;
+        material.uniforms.uTwinkle.value = twinkle;
+        material.uniforms.uWarmth.value = warmth;
+    });
+    return _jsx("points", { ref: pointsRef, geometry: geometry, material: material, frustumCulled: false, renderOrder: -2 });
+};
+export default SkyStars;

package/dist/components/SkySystem.d.ts

@@ -26,9 +26,9 @@ export interface SkySystemRef {
 export interface SkySystemProps extends ObjectReadyProps {
     timeSettings: TimeSettings;
     visible?: boolean;
-    /** True mounts the physical sun rig (skybox + lensflare + directional light);
-     *  false mounts the analytic Preetham sky instead. They are alternatives, not
-     *  layers — the sun rig draws its own background. */
+    /** True mounts the sun rig background (skybox + lensflare); false mounts the
+     *  analytic Preetham sky instead. The key light (SunLight) is the same in both
+     *  and is mounted whenever either sky is active. */
     sunSystemVisible?: boolean;
     sunSize?: number;
     moonSize?: number;

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

@@ -1 +1 @@
-{"version":3,"file":"SkySystem.d.ts","sourceRoot":"","sources":["../../src/components/SkySystem.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAOtE,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,KAAK,CAAC,OAAO,CAAC;CACxC;AAED,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACpD,YAAY,EAAE,YAAY,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;yDAEqD;IACrD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC;IAC/B;;;uBAGmB;IACnB,cAAc,CAAC,EAAE,wBAAwB,CAAC;IAC1C,qBAAqB,CAAC,EAAE,WAAW,CAAC;IACpC;wDACoD;IACpD,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IACrE,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C;;;;;;;;;;gFAU4E;IAC5E,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,QAAA,MAAM,SAAS,qFAwJb,CAAC;AAGH,eAAe,SAAS,CAAC"}
+{"version":3,"file":"SkySystem.d.ts","sourceRoot":"","sources":["../../src/components/SkySystem.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAStE,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,KAAK,CAAC,OAAO,CAAC;CACxC;AAED,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACpD,YAAY,EAAE,YAAY,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;wDAEoD;IACpD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC;IAC/B;;;uBAGmB;IACnB,cAAc,CAAC,EAAE,wBAAwB,CAAC;IAC1C,qBAAqB,CAAC,EAAE,WAAW,CAAC;IACpC;wDACoD;IACpD,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IACrE,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C;;;;;;;;;;gFAU4E;IAC5E,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,QAAA,MAAM,SAAS,qFAmLb,CAAC;AAGH,eAAe,SAAS,CAAC"}