@3driseai/3drise-viewer 0.1.7 → 0.1.8

package/dist/hooks/useCloudNoise.js

@@ -0,0 +1,128 @@
+import * as THREE from 'three';
+import { useMemo } from 'react';
+import { useThree } from '@react-three/fiber';
+import { bakeVertex, bakeBaseFrag, bakeDetailFrag, bakeWeatherFrag, bakeCurlFrag, } from '../shaders/glsl/noiseBake.glsl.js';
+/** Some three builds still export the pre-r137 name. */
+const Texture3D = THREE.Data3DTexture ?? THREE.DataTexture3D;
+const quad = new THREE.PlaneGeometry(2, 2);
+const bakeCamera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+function runBake(gl, fragmentShader, width, height, tiles, res) {
+    const target = new THREE.WebGLRenderTarget(width, height, {
+        minFilter: THREE.NearestFilter,
+        magFilter: THREE.NearestFilter,
+        format: THREE.RGBAFormat,
+        type: THREE.UnsignedByteType,
+        depthBuffer: false,
+        stencilBuffer: false,
+    });
+    const material = new THREE.ShaderMaterial({
+        uniforms: {
+            u_atlas: { value: new THREE.Vector2(width, height) },
+            u_tiles: { value: tiles },
+            u_res: { value: res },
+        },
+        vertexShader: bakeVertex,
+        fragmentShader,
+        glslVersion: THREE.GLSL3,
+        depthTest: false,
+        depthWrite: false,
+    });
+    const scene = new THREE.Scene();
+    scene.add(new THREE.Mesh(quad, material));
+    const prevTarget = gl.getRenderTarget();
+    const prevAutoClear = gl.autoClear;
+    gl.autoClear = true;
+    gl.setRenderTarget(target);
+    gl.render(scene, bakeCamera);
+    const buffer = new Uint8Array(new ArrayBuffer(width * height * 4));
+    gl.readRenderTargetPixels(target, 0, 0, width, height, buffer);
+    gl.setRenderTarget(prevTarget);
+    gl.autoClear = prevAutoClear;
+    target.dispose();
+    material.dispose();
+    return buffer;
+}
+/** Atlas of z-slices to a real 3D texture, so sampling gets hardware trilinear filtering. */
+function bakeVolume(gl, frag, res, tiles) {
+    const width = res * tiles;
+    const height = res * Math.ceil(res / tiles);
+    const atlas = runBake(gl, frag, width, height, tiles, res);
+    const data = new Uint8Array(new ArrayBuffer(res * res * res * 4));
+    for (let py = 0; py < height; py++) {
+        const ty = Math.floor(py / res);
+        const y = py - ty * res;
+        for (let px = 0; px < width; px++) {
+            const tx = Math.floor(px / res);
+            const x = px - tx * res;
+            const z = ty * tiles + tx;
+            if (z >= res)
+                continue;
+            const si = (py * width + px) * 4;
+            const di = ((z * res + y) * res + x) * 4;
+            data[di] = atlas[si];
+            data[di + 1] = atlas[si + 1];
+            data[di + 2] = atlas[si + 2];
+            data[di + 3] = atlas[si + 3];
+        }
+    }
+    const tex = new Texture3D(data, res, res, res);
+    tex.format = THREE.RGBAFormat;
+    tex.type = THREE.UnsignedByteType;
+    tex.minFilter = THREE.LinearFilter;
+    tex.magFilter = THREE.LinearFilter;
+    tex.wrapS = THREE.RepeatWrapping;
+    tex.wrapT = THREE.RepeatWrapping;
+    tex.wrapR = THREE.RepeatWrapping;
+    tex.unpackAlignment = 1;
+    tex.needsUpdate = true;
+    return tex;
+}
+function bakePlane(gl, frag, res) {
+    const buffer = runBake(gl, frag, res, res, 1, res);
+    const tex = new THREE.DataTexture(buffer, res, res, THREE.RGBAFormat, THREE.UnsignedByteType);
+    tex.minFilter = THREE.LinearFilter;
+    tex.magFilter = THREE.LinearFilter;
+    tex.wrapS = THREE.RepeatWrapping;
+    tex.wrapT = THREE.RepeatWrapping;
+    tex.unpackAlignment = 1;
+    tex.needsUpdate = true;
+    return tex;
+}
+const cache = new WeakMap();
+export function bakeCloudNoise(gl) {
+    const hit = cache.get(gl);
+    if (hit)
+        return hit;
+    // 3D textures are WebGL2 only. Returning null rather than throwing lets the
+    // renderer skip clouds on an unsupported context instead of killing the scene.
+    if (!gl.capabilities.isWebGL2) {
+        console.warn('[clouds] Volumetric clouds need WebGL2 (3D textures). Skipping.');
+        return null;
+    }
+    const noise = {
+        base: bakeVolume(gl, bakeBaseFrag, 128, 16),
+        detail: bakeVolume(gl, bakeDetailFrag, 64, 8),
+        weather: bakePlane(gl, bakeWeatherFrag, 512),
+        curl: bakePlane(gl, bakeCurlFrag, 128),
+        dispose() {
+            this.base.dispose();
+            this.detail.dispose();
+            this.weather.dispose();
+            this.curl.dispose();
+            cache.delete(gl);
+        },
+    };
+    cache.set(gl, noise);
+    return noise;
+}
+/**
+ * Null when the context cannot support the volumes. Callers should render nothing
+ * rather than treat that as an error.
+ */
+export function useCloudNoise() {
+    const gl = useThree((s) => s.gl);
+    // Not disposed on unmount: the cache is per-renderer, and a remount would
+    // otherwise pay the bake again. Call noise.dispose() when tearing a scene down.
+    return useMemo(() => bakeCloudNoise(gl), [gl]);
+}
+export default useCloudNoise;

package/dist/hooks/useCloudSun.d.ts

@@ -0,0 +1,49 @@
+import * as THREE from 'three';
+import type { SkySettings, TimeSettings } from '@3driseai/3drise-core';
+/**
+ * The one place the cloud renderer decides where the sun is and what colour it is.
+ *
+ * Direction comes from whatever the scene already uses, in this order:
+ *   1. skySystemManager, when time-of-day is enabled — the same source SunLight,
+ *      Skybox and Lensflare read, so a time slider moves everything together.
+ *   2. SkySettings.elevation / azimuth, the static sun.
+ *   3. A fixed mid-morning direction, so a scene with no sky still lights.
+ *
+ * Colour comes from Kasten-Young air mass through the SAME four Preetham
+ * parameters SkyController draws with. That is what keeps the clouds inside the
+ * sky rather than pasted onto it: at low sun the beam reddens for the clouds and
+ * the background by the same optical depth, because it is the same number.
+ */
+export interface CloudSunState {
+    direction: THREE.Vector3;
+    color: THREE.Color;
+    /** Hemispheric fill from above — Rayleigh blue, scaled by how high the sun is. */
+    skyAmbient: THREE.Color;
+    /** Bounce from below, tinted by the reddened beam. */
+    groundAmbient: THREE.Color;
+    turbidity: number;
+    rayleigh: number;
+    mieCoefficient: number;
+    mieG: number;
+}
+/**
+ * Fill `out` from the sun direction and the sky parameters. Exported so a surface
+ * material that wants cloud shadows can agree with the clouds on the sun.
+ */
+export declare function computeCloudSun(direction: THREE.Vector3, sky: Partial<SkySettings> | undefined, out: CloudSunState): CloudSunState;
+export interface UseCloudSunOptions {
+    skySettings?: SkySettings;
+    timeSettings?: TimeSettings;
+    /** Override everything — a direction the caller already has. */
+    direction?: THREE.Vector3;
+}
+/**
+ * Returns a stable object mutated in place. Read it inside useFrame; do not put it
+ * in a dependency array — the whole point is that it changes without re-rendering.
+ */
+export declare function useCloudSun(options?: UseCloudSunOptions): {
+    state: CloudSunState;
+    update(): CloudSunState;
+};
+export default useCloudSun;
+//# sourceMappingURL=useCloudSun.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useCloudSun.d.ts","sourceRoot":"","sources":["../../src/hooks/useCloudSun.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAEvE;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,aAAa;IAC1B,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC;IACzB,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IACnB,kFAAkF;IAClF,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC;IACxB,sDAAsD;IACtD,aAAa,EAAE,KAAK,CAAC,KAAK,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CAChB;AAaD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,SAAS,EAAE,GAAG,EAAE,aAAa,GAAG,aAAa,CA2BlI;AAED,MAAM,WAAW,kBAAkB;IAC/B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,MAAM,IAAI,aAAa,CAAA;CAAE,CA2C/G;AAED,eAAe,WAAW,CAAC"}

package/dist/hooks/useCloudSun.js

@@ -0,0 +1,84 @@
+import * as THREE from 'three';
+import { useMemo, useRef } from 'react';
+import { skySystemManager } from '@3driseai/3drise-core';
+const RAYLEIGH_BASE = [0.0487, 0.113, 0.278];
+const DEFAULT_DIRECTION = new THREE.Vector3(0.35, 0.42, 0.84).normalize();
+/** Kasten-Young relative air mass, clamped where the formula stops behaving. */
+function airMass(cosZenith) {
+    const cy = Math.max(cosZenith, -0.02);
+    const zenithDeg = (Math.acos(THREE.MathUtils.clamp(cy, -1, 1)) * 180) / Math.PI;
+    return Math.min(1 / (Math.max(cy, 0) + 0.15 * Math.pow(Math.max(93.885 - zenithDeg, 0.5), -1.253)), 40);
+}
+/**
+ * Fill `out` from the sun direction and the sky parameters. Exported so a surface
+ * material that wants cloud shadows can agree with the clouds on the sun.
+ */
+export function computeCloudSun(direction, sky, out) {
+    const turbidity = sky?.turbidity ?? 2;
+    const rayleigh = sky?.rayleigh ?? 1;
+    const mieCoefficient = sky?.mieCoefficient ?? 0.005;
+    const mieG = sky?.mieDirectionalG ?? 0.76;
+    out.direction.copy(direction);
+    out.turbidity = turbidity;
+    out.rayleigh = rayleigh;
+    out.mieCoefficient = mieCoefficient;
+    out.mieG = mieG;
+    const am = airMass(direction.y);
+    const mie = mieCoefficient * turbidity * 4.25;
+    const r = Math.exp(-(RAYLEIGH_BASE[0] * turbidity * rayleigh + mie) * am);
+    const g = Math.exp(-(RAYLEIGH_BASE[1] * turbidity * rayleigh + mie) * am);
+    const b = Math.exp(-(RAYLEIGH_BASE[2] * turbidity * rayleigh + mie) * am);
+    out.color.setRGB(r, g, b);
+    // Ambient is deliberately not a constant: a cloud's shadowed side is lit by the
+    // sky, and the sky goes dark and warm as the sun sets. Freezing it is what makes
+    // night clouds glow blue.
+    const day = THREE.MathUtils.clamp(direction.y * 2.2, 0.02, 1);
+    const k = (0.55 + 0.45 * day) * 1.85;
+    out.skyAmbient.setRGB(0.3 * day + 0.02, 0.46 * day + 0.02, 0.86 * day + 0.035).multiplyScalar(k);
+    out.groundAmbient.setRGB(0.26 * r, 0.24 * g, 0.21 * b).multiplyScalar(k);
+    return out;
+}
+/**
+ * Returns a stable object mutated in place. Read it inside useFrame; do not put it
+ * in a dependency array — the whole point is that it changes without re-rendering.
+ */
+export function useCloudSun(options = {}) {
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const state = useMemo(() => ({
+        direction: new THREE.Vector3().copy(DEFAULT_DIRECTION),
+        color: new THREE.Color(1, 1, 1),
+        skyAmbient: new THREE.Color(),
+        groundAmbient: new THREE.Color(),
+        turbidity: 2,
+        rayleigh: 1,
+        mieCoefficient: 0.005,
+        mieG: 0.76,
+    }), []);
+    const scratch = useMemo(() => new THREE.Vector3(), []);
+    const update = useMemo(() => () => {
+        const { skySettings, timeSettings, direction } = optionsRef.current;
+        let dir;
+        if (direction) {
+            dir = scratch.copy(direction).normalize();
+        }
+        else if (timeSettings?.enabled) {
+            // Same source SunLight reads, so the two can never disagree.
+            const sunDirection = skySystemManager.getState()?.sunDirection;
+            dir = sunDirection
+                ? scratch.copy(sunDirection).normalize()
+                : scratch.copy(DEFAULT_DIRECTION);
+        }
+        else if (skySettings) {
+            const el = THREE.MathUtils.degToRad(skySettings.elevation ?? 25);
+            const az = THREE.MathUtils.degToRad(skySettings.azimuth ?? 130);
+            dir = scratch.set(Math.cos(el) * Math.sin(az), Math.sin(el), Math.cos(el) * Math.cos(az)).normalize();
+        }
+        else {
+            dir = scratch.copy(DEFAULT_DIRECTION);
+        }
+        return computeCloudSun(dir, skySettings, state);
+    }, [scratch, state]);
+    return { state, update };
+}
+export default useCloudSun;

package/dist/hooks/useCubeCamera.d.ts

@@ -1,18 +1,36 @@
 import * as THREE from 'three';
-import type { TimeSettings, HdrSettings } from '@3driseai/3drise-core';
+import { CubeCameraManager } from '@3driseai/3drise-core';
+/**
+ * Imperative handle onto the scene's single cube camera.
+ *
+ * The hook deliberately holds **no policy**. It attaches the shared
+ * CubeCameraManager to this Canvas's scene and renderer and hands back the four
+ * verbs; deciding *when* a cube camera should exist and how often it should
+ * refresh belongs to whoever knows about HDR backgrounds and sky visibility —
+ * that is EnvironmentManager, not this file.
+ *
+ * That split matters because the state the policy reads (hdr.visible, the sky
+ * toggles, timeSettings.autoAnimate) lives in the host app. A hook that took
+ * those as options would force every host to hand them over just to get a cube
+ * camera, which is how this ended up implemented twice in the first place.
+ *
+ * The manager is a singleton: one cube camera per app, whatever mounts this.
+ */
 export interface UseCubeCameraOptions {
-    hdrSettings: HdrSettings;
-    skyVisible: boolean;
-    sunSystemVisible: boolean;
-    timeSettings: TimeSettings;
+    /** Face size of the cube render target. 512 is the default everywhere. */
     resolution?: number;
+    /** Where the probe sits. Defaults to the manager's own (0, 50, 0). */
     position?: THREE.Vector3;
     onEnvironmentUpdate?: (texture: THREE.Texture) => void;
 }
-export declare const useCubeCamera: (options: UseCubeCameraOptions) => {
-    cubeCamera: THREE.CubeCamera | null;
-    updateEnvironment: () => THREE.Texture | null;
+export interface UseCubeCameraReturn {
+    manager: CubeCameraManager;
+    readonly cubeCamera: THREE.CubeCamera | null;
     initializeCubeCamera: () => THREE.CubeCamera | null;
+    updateEnvironment: () => THREE.Texture | null;
+    clear: () => void;
     dispose: () => void;
-};
+}
+export declare const useCubeCamera: (options?: UseCubeCameraOptions) => UseCubeCameraReturn;
+export default useCubeCamera;
 //# sourceMappingURL=useCubeCamera.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useCubeCamera.d.ts","sourceRoot":"","sources":["../../src/hooks/useCubeCamera.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACvE,MAAM,WAAW,oBAAoB;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC;IACpB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,YAAY,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,KAAK,IAAI,CAAC;CAC1D;AAED,eAAO,MAAM,aAAa,GAAI,SAAS,oBAAoB,KAAG;IACtD,UAAU,EAAE,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC;IACpC,iBAAiB,EAAE,MAAM,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;IAC9C,oBAAoB,EAAE,MAAM,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC;IACpD,OAAO,EAAE,MAAM,IAAI,CAAC;CAqE3B,CAAC"}
+{"version":3,"file":"useCubeCamera.d.ts","sourceRoot":"","sources":["../../src/hooks/useCubeCamera.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,oBAAoB;IACjC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,KAAK,IAAI,CAAC;CAC1D;AAED,MAAM,WAAW,mBAAmB;IAChC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC;IAC7C,oBAAoB,EAAE,MAAM,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC;IACpD,iBAAiB,EAAE,MAAM,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;IAC9C,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,OAAO,EAAE,MAAM,IAAI,CAAC;CACvB;AAED,eAAO,MAAM,aAAa,GAAI,UAAS,oBAAyB,KAAG,mBAgClE,CAAC;AAEF,eAAe,aAAa,CAAC"}

package/dist/hooks/useCubeCamera.js

@@ -1,73 +1,31 @@
-import { useRef, useCallback, useEffect } from 'react';
-import { useThree, useFrame } from '@react-three/fiber';
-import * as THREE from 'three';
-import { createCubeCamera, updateCubeCamera, disposeCubeCamera, setSceneEnvironment, clearSceneEnvironment, } from '@3driseai/3drise-core';
-export const useCubeCamera = (options) => {
-    const { hdrSettings, skyVisible, sunSystemVisible, timeSettings, resolution = 512, position = new THREE.Vector3(0, 50, 0), onEnvironmentUpdate } = options;
+import { useEffect, useMemo } from 'react';
+import { useThree } from '@react-three/fiber';
+import { CubeCameraManager } from '@3driseai/3drise-core';
+export const useCubeCamera = (options = {}) => {
     const { scene, gl: renderer } = useThree();
-    const cubeCameraRef = useRef(null);
-    const isUpdatingRef = useRef(false);
-    const hdrActive = hdrSettings.visible && (hdrSettings.name || (hdrSettings.urls && hdrSettings.urls.length > 0)) ? true : false;
-    const initializeCubeCamera = useCallback(() => {
-        if (!renderer || !scene)
-            return null;
-        if (cubeCameraRef.current)
-            disposeCubeCamera(cubeCameraRef.current, scene);
-        cubeCameraRef.current = createCubeCamera(scene, resolution, position);
-        return cubeCameraRef.current;
-    }, [scene, renderer, resolution, position]);
-    const updateEnvironment = useCallback(() => {
-        if (!cubeCameraRef.current || !renderer || !scene)
-            return null;
-        if (isUpdatingRef.current)
-            return null;
-        try {
-            isUpdatingRef.current = true;
-            const texture = updateCubeCamera(cubeCameraRef.current, renderer, scene);
-            setSceneEnvironment(scene, texture);
-            onEnvironmentUpdate?.(texture);
-            return texture;
-        }
-        catch {
-            return null;
-        }
-        finally {
-            isUpdatingRef.current = false;
-        }
-    }, [scene, renderer, onEnvironmentUpdate]);
-    const dispose = useCallback(() => {
-        if (cubeCameraRef.current && scene) {
-            disposeCubeCamera(cubeCameraRef.current, scene);
-            cubeCameraRef.current = null;
-        }
-    }, [scene]);
-    // Create or dispose cube camera based on active sky / HDR state
+    const manager = CubeCameraManager.getInstance();
+    const { resolution = 512, position, onEnvironmentUpdate } = options;
     useEffect(() => {
-        if (hdrActive) {
-            dispose();
-            return;
-        }
-        if (skyVisible || sunSystemVisible) {
-            initializeCubeCamera();
-            updateEnvironment();
-        }
-        else {
-            dispose();
-            clearSceneEnvironment(scene);
-        }
-    }, [hdrActive, skyVisible, sunSystemVisible]);
-    // Live update when auto-animating (sky moves, environment changes)
-    const UPDATE_INTERVAL_MS = 300;
-    useFrame((state) => {
-        if (hdrActive || !(skyVisible || sunSystemVisible))
-            return;
-        if (!timeSettings.autoAnimate)
-            return;
-        if (state.clock.getElapsedTime() * 1000 > UPDATE_INTERVAL_MS) {
-            updateEnvironment();
-        }
-    });
-    // Cleanup on unmount
-    useEffect(() => () => dispose(), [dispose]);
-    return { cubeCamera: cubeCameraRef.current, updateEnvironment, initializeCubeCamera, dispose };
+        manager.attach(scene, renderer);
+        return () => {
+            manager.detach();
+        };
+    }, [manager, scene, renderer]);
+    useEffect(() => {
+        manager.setOnUpdate(onEnvironmentUpdate ?? null);
+        return () => {
+            manager.setOnUpdate(null);
+        };
+    }, [manager, onEnvironmentUpdate]);
+    return useMemo(() => ({
+        manager,
+        get cubeCamera() {
+            return manager.getCubeCamera();
+        },
+        initializeCubeCamera: () => manager.initCubeCamera(resolution, position),
+        updateEnvironment: () => manager.updateEnvironment(),
+        clear: () => manager.clear(),
+        dispose: () => manager.dispose(),
+    }), [manager, resolution, position]);
 };
+export default useCubeCamera;

package/dist/hooks/useEnvironmentProbe.d.ts

@@ -0,0 +1,32 @@
+/**
+ * When the scene's cube-camera probe should exist, and how often it refreshes.
+ *
+ * This is the *policy* half of the cube camera; useCubeCamera is the imperative
+ * half. It lives in a hook rather than inside EnvironmentManager because two
+ * hosts need it — the composed EnvironmentManager used by published scenes, and
+ * the editor's HDR connector, which subscribes to Redux and composes the leaf
+ * components itself. Duplicating a rule this fiddly is how the two paths drifted
+ * apart last time.
+ *
+ * The rule itself:
+ *  - An HDR background provides its own IBL, so the probe is disposed.
+ *  - Otherwise, if there is any sky, the probe exists and captures it.
+ *  - Otherwise there is nothing to capture, so dispose and clear the environment.
+ *
+ * The refresh accumulates delta and resets. The obvious-looking
+ * `clock.getElapsedTime() * 1000 > interval` is true on *every* frame after the
+ * first 0.3 s, which re-renders all six cube faces per frame.
+ */
+export interface UseEnvironmentProbeOptions {
+    /** An HDR background or playlist is supplying the environment map. */
+    hdrActive: boolean;
+    /** Analytic sky or the sun rig is visible — something worth capturing. */
+    skyActive: boolean;
+    /** Time of day is animating, so the capture goes stale and needs refreshing. */
+    autoAnimate: boolean;
+    resolution?: number;
+    intervalMs?: number;
+}
+export declare function useEnvironmentProbe({ hdrActive, skyActive, autoAnimate, resolution, intervalMs, }: UseEnvironmentProbeOptions): void;
+export default useEnvironmentProbe;
+//# sourceMappingURL=useEnvironmentProbe.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useEnvironmentProbe.d.ts","sourceRoot":"","sources":["../../src/hooks/useEnvironmentProbe.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,0BAA0B;IACvC,sEAAsE;IACtE,SAAS,EAAE,OAAO,CAAC;IACnB,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,mBAAmB,CAAC,EAChC,SAAS,EACT,SAAS,EACT,WAAW,EACX,UAAgB,EAChB,UAAgB,GACnB,EAAE,0BAA0B,GAAG,IAAI,CA6BnC;AAED,eAAe,mBAAmB,CAAC"}

package/dist/hooks/useEnvironmentProbe.js

@@ -0,0 +1,35 @@
+import { useEffect, useRef } from 'react';
+import { useFrame } from '@react-three/fiber';
+import { useCubeCamera } from './useCubeCamera.js';
+export function useEnvironmentProbe({ hdrActive, skyActive, autoAnimate, resolution = 512, intervalMs = 300, }) {
+    const { manager, initializeCubeCamera, updateEnvironment, dispose, clear } = useCubeCamera({
+        resolution,
+    });
+    useEffect(() => {
+        if (hdrActive) {
+            dispose();
+            return;
+        }
+        if (skyActive) {
+            initializeCubeCamera();
+            updateEnvironment();
+        }
+        else {
+            dispose();
+            clear();
+        }
+    }, [hdrActive, skyActive, initializeCubeCamera, updateEnvironment, dispose, clear]);
+    const elapsedMsRef = useRef(0);
+    useFrame((_, delta) => {
+        if (hdrActive || !skyActive || !autoAnimate)
+            return;
+        if (!manager.hasCubeCamera())
+            return;
+        elapsedMsRef.current += delta * 1000;
+        if (elapsedMsRef.current >= intervalMs) {
+            elapsedMsRef.current = 0;
+            updateEnvironment();
+        }
+    });
+}
+export default useEnvironmentProbe;

package/dist/hooks/useFrameRenderer.d.ts

@@ -0,0 +1,15 @@
+import { type FrameRenderer } from '../utils/frameRenderer';
+/**
+ * Declare that this component produces the finished frame.
+ *
+ * For a full-screen pass that runs at `useFrame(…, 1)` and composites to the canvas
+ * itself. Everything that needs a complete image — screenshots, thumbnails — asks
+ * through `renderFrame()` rather than calling `gl.render(scene, camera)`, which would
+ * draw the scene graph and silently drop whatever the pass adds.
+ *
+ * Pass a stable callback (a ref-held function or useCallback); it is registered on
+ * mount and released on unmount, so plain rendering resumes when the pass goes away.
+ */
+export declare function useFrameRenderer(render: FrameRenderer | null | undefined): void;
+export default useFrameRenderer;
+//# sourceMappingURL=useFrameRenderer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useFrameRenderer.d.ts","sourceRoot":"","sources":["../../src/hooks/useFrameRenderer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEnF;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAM/E;AAED,eAAe,gBAAgB,CAAC"}

package/dist/hooks/useFrameRenderer.js

@@ -0,0 +1,23 @@
+import { useEffect } from 'react';
+import { useThree } from '@react-three/fiber';
+import { registerFrameRenderer } from '../utils/frameRenderer.js';
+/**
+ * Declare that this component produces the finished frame.
+ *
+ * For a full-screen pass that runs at `useFrame(…, 1)` and composites to the canvas
+ * itself. Everything that needs a complete image — screenshots, thumbnails — asks
+ * through `renderFrame()` rather than calling `gl.render(scene, camera)`, which would
+ * draw the scene graph and silently drop whatever the pass adds.
+ *
+ * Pass a stable callback (a ref-held function or useCallback); it is registered on
+ * mount and released on unmount, so plain rendering resumes when the pass goes away.
+ */
+export function useFrameRenderer(render) {
+    const gl = useThree((s) => s.gl);
+    useEffect(() => {
+        if (!render)
+            return;
+        return registerFrameRenderer(gl, render);
+    }, [gl, render]);
+}
+export default useFrameRenderer;

package/dist/hooks/useLandscapeLive.d.ts

@@ -0,0 +1,29 @@
+import type { Object3D } from 'three';
+/**
+ * Live landscape editing, the counterpart to `useTerrainLive` and `useOceanLive`.
+ *
+ * The rule is the same — a slider drag writes straight into the renderer and
+ * Redux only hears about it on slider end — but the stakes are higher here.
+ * `meshError` re-runs RTIN, `chunks` rebuilds every index buffer,
+ * `arrayResolution` repacks the texture arrays and `surfaceSamples` recompiles
+ * the shader. Those are commit-on-release; everything else is a uniform and goes
+ * through this, and the renderer's handle enforces the split from
+ * `LANDSCAPE_LIVE_*_KEYS` so a controller cannot half-apply a rebuild key by
+ * passing it here.
+ *
+ * Pass the ID, not a resolved Object3D: the panel is routinely open before the
+ * landscape exists, and a findById() memoised in the controller resolves to null
+ * exactly once and stays null for the session.
+ */
+export declare const LANDSCAPE_LIVE_KEY = "__landscapeLive";
+export interface LandscapeLiveHandle {
+    config(key: string, value: number | boolean | string): void;
+    quality(key: string, value: number | boolean | string): void;
+    /** One field of one surface, by index. The surface list drives this. */
+    surface(index: number, key: string, value: number | boolean | string): void;
+    /** One field of the generated-splat block. Every one of them is a uniform. */
+    autoSplat(key: string, value: number | boolean | string): void;
+}
+export declare function useLandscapeLive(target?: Object3D | string | null): LandscapeLiveHandle;
+export default useLandscapeLive;
+//# sourceMappingURL=useLandscapeLive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useLandscapeLive.d.ts","sourceRoot":"","sources":["../../src/hooks/useLandscapeLive.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAGrC;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,kBAAkB,oBAAoB,CAAA;AAEnD,MAAM,WAAW,mBAAmB;IAChC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAA;IAC3D,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAA;IAC5D,wEAAwE;IACxE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAA;IAC3E,8EAA8E;IAC9E,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAA;CACjE;AASD,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,GAAG,mBAAmB,CAcvF;AAED,eAAe,gBAAgB,CAAA"}

package/dist/hooks/useLandscapeLive.js

@@ -0,0 +1,41 @@
+import { useMemo } from 'react';
+import { findById } from '../utils/sceneQuery.js';
+/**
+ * Live landscape editing, the counterpart to `useTerrainLive` and `useOceanLive`.
+ *
+ * The rule is the same — a slider drag writes straight into the renderer and
+ * Redux only hears about it on slider end — but the stakes are higher here.
+ * `meshError` re-runs RTIN, `chunks` rebuilds every index buffer,
+ * `arrayResolution` repacks the texture arrays and `surfaceSamples` recompiles
+ * the shader. Those are commit-on-release; everything else is a uniform and goes
+ * through this, and the renderer's handle enforces the split from
+ * `LANDSCAPE_LIVE_*_KEYS` so a controller cannot half-apply a rebuild key by
+ * passing it here.
+ *
+ * Pass the ID, not a resolved Object3D: the panel is routinely open before the
+ * landscape exists, and a findById() memoised in the controller resolves to null
+ * exactly once and stays null for the session.
+ */
+export const LANDSCAPE_LIVE_KEY = '__landscapeLive';
+const NOOP = {
+    config: () => { },
+    quality: () => { },
+    surface: () => { },
+    autoSplat: () => { },
+};
+export function useLandscapeLive(target) {
+    return useMemo(() => {
+        const resolve = () => {
+            const object = typeof target === 'string' ? findById(target) : target;
+            const handle = object?.userData?.[LANDSCAPE_LIVE_KEY];
+            return handle ?? NOOP;
+        };
+        return {
+            config: (key, value) => resolve().config(key, value),
+            quality: (key, value) => resolve().quality(key, value),
+            surface: (index, key, value) => resolve().surface(index, key, value),
+            autoSplat: (key, value) => resolve().autoSplat(key, value),
+        };
+    }, [target]);
+}
+export default useLandscapeLive;

package/dist/hooks/useLandscapeMaps.d.ts

@@ -0,0 +1,32 @@
+import { type DecodedHeightmap } from '../utils/landscapeTextures';
+import type { LandscapeConfig, LandscapeQualityConfig } from '../types/landscapeConfigs';
+import type { LandscapeMapUniforms } from '../utils/landscapeUniforms';
+/**
+ * Every image a landscape needs, loaded and packed.
+ *
+ * The surfaces go into two `DataArrayTexture`s rather than sixteen samplers:
+ * one binding, one integer layer index, no branch tree. Every layer must be the
+ * same size and user uploads never are, so each image is redrawn at
+ * `arrayResolution` on the way in.
+ *
+ * **The height maps ride in the normal array's alpha channel.** A tangent-space
+ * normal map only needs RGB, so the surface's own height — the thing that makes
+ * a transition read as material rather than as a cross-fade — costs nothing but
+ * the channel that was already there. A third array would have been another
+ * 100 MB at 1024.
+ *
+ * Loading is one effect with a cancellation flag, and the previous set is
+ * disposed only after the new one is ready, so a change of preset does not blink
+ * the ground away.
+ */
+export interface LandscapeMapsState extends LandscapeMapUniforms {
+    /** The decoded heightmap, for RTIN and for CPU height queries. */
+    heightField: DecodedHeightmap | null;
+    ready: boolean;
+    error: string | null;
+    /** Surfaces that actually contributed a layer, in order. */
+    layerCount: number;
+}
+export declare function useLandscapeMaps(config: LandscapeConfig, quality: LandscapeQualityConfig): LandscapeMapsState;
+export default useLandscapeMaps;
+//# sourceMappingURL=useLandscapeMaps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useLandscapeMaps.d.ts","sourceRoot":"","sources":["../../src/hooks/useLandscapeMaps.ts"],"names":[],"mappings":"AAEA,OAAO,EAOH,KAAK,gBAAgB,EACxB,MAAM,4BAA4B,CAAA;AACnC,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAA;AACxF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AAEtE;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,kBAAmB,SAAQ,oBAAoB;IAC5D,kEAAkE;IAClE,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAAA;IACpC,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAA;CACrB;AA4CD,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,sBAAsB,GAChC,kBAAkB,CAmHpB;AAED,eAAe,gBAAgB,CAAA"}