@3driseai/3drise-viewer 0.1.6 → 0.1.8

package/dist/hooks/useClipmap.d.ts

@@ -0,0 +1,71 @@
+import * as THREE from 'three';
+/**
+ * Geometry clipmap rings. Shared by the terrain and the ocean.
+ *
+ * A surface that reaches the horizon cannot be one grid: at 4 m cells, 25 km is
+ * 39 million quads. A clipmap spends its vertices where they are visible instead
+ * — level 0 is a dense square centred on the camera, and every level above it is
+ * a hollow ring of the SAME vertex count at twice the cell size, so each ring
+ * covers four times the area for the same cost. Seven levels of 96 segments at
+ * 4 m reach roughly 24 km for about 65k vertices.
+ *
+ * This hook knows nothing about what displaces it. It was written for terrain
+ * (`useTerrainClipmap`, now a shim over this) and the ocean uses it unchanged;
+ * the height field, the LOD rule and the material are the caller's business.
+ *
+ * Two details make it work, and both are baked into the attributes here rather
+ * than solved at runtime:
+ *
+ * **`aMorph`** ramps 0 to 1 across the outer band of every ring. In the vertex
+ * shader it slides odd-indexed vertices onto their even neighbours, so by the
+ * ring's outer edge the polyline is exactly the next ring's coarser polyline.
+ * That closes the T-junction cracks between levels — and because it is a
+ * continuous slide rather than a swap, it also removes the pop.
+ *
+ * **`aCoarse`** is the offset to that even neighbour, and it is zero on even
+ * indices. The ring boundaries are all at even indices (which is why `segments`
+ * must be a multiple of 8), so a boundary vertex only ever moves ALONG the
+ * boundary, never off it. A morph that displaced the edge inward would trade the
+ * crack for a gap.
+ *
+ * **`aCell`** is the ring's world cell size, so one material can serve every
+ * ring. Both consumers pair it with the same morph rule —
+ * `cellLod = aCell * (1.0 + aMorph)` — which makes a ring's outer edge sample the
+ * field at exactly the next ring's cell size. Terrain uses it to drop octaves;
+ * the ocean uses it to fade out waves shorter than the cell can carry. In both
+ * cases the two sides of a seam then agree on the surface, which the geomorph
+ * alone does not guarantee.
+ *
+ * And one thing that is NOT here, because getting it wrong is the classic way to
+ * open the seams: every ring shares ONE snapped origin, exposed as `sharedSnap`.
+ * Snapping each ring to its own cell grid — which is what a clipmap tutorial will
+ * tell you to do — puts neighbouring rings on origins up to a cell apart, and the
+ * boundaries that line up perfectly in local space then miss each other in world
+ * space by that offset. The published fix for that is Asirvatham & Hoppe's
+ * L-shaped trim piece in four rotations; sharing the origin avoids needing one.
+ * The price is that coarse rings re-tessellate in sub-cell steps as the camera
+ * moves rather than snapping cleanly, and at their cell sizes the octave cut-off
+ * has already smoothed away everything that would show it.
+ */
+export interface ClipmapLevel {
+    geometry: THREE.BufferGeometry;
+    /** World size of one cell at this level. */
+    cell: number;
+    level: number;
+}
+export interface Clipmap {
+    levels: ClipmapLevel[];
+    /** The grid every ring is snapped to: twice the finest cell. Twice, so index
+     *  parity — and with it the geomorph — never flips as the camera crosses a
+     *  cell boundary. Snapping to one cell inverts the morph every step and the
+     *  whole surface shimmers. */
+    sharedSnap: number;
+}
+/**
+ * `segments` is rounded to a multiple of 8: the ring boundaries sit at
+ * `segments/4` and `segments/2`, and both must land on even indices or the morph
+ * pulls boundary vertices off their own edge.
+ */
+export declare function useClipmap(levels: number, segments: number, cellSize: number): Clipmap;
+export default useClipmap;
+//# sourceMappingURL=useClipmap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useClipmap.d.ts","sourceRoot":"","sources":["../../src/hooks/useClipmap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,MAAM,WAAW,YAAY;IACzB,QAAQ,EAAE,KAAK,CAAC,cAAc,CAAC;IAC/B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,OAAO;IACpB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB;;;kCAG8B;IAC9B,UAAU,EAAE,MAAM,CAAC;CACtB;AA4ED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAgBtF;AAED,eAAe,UAAU,CAAC"}

package/dist/hooks/useClipmap.js

@@ -0,0 +1,81 @@
+import * as THREE from 'three';
+import { useEffect, useMemo } from 'react';
+/** Fraction of the ring's half-extent over which the morph runs. */
+const MORPH_BAND = 0.25;
+function buildLevel(segments, cell, hollow, level) {
+    const side = segments + 1;
+    const half = segments / 2;
+    const count = side * side;
+    const positions = new Float32Array(count * 3);
+    const aCell = new Float32Array(count);
+    const aMorph = new Float32Array(count);
+    const aCoarse = new Float32Array(count * 2);
+    for (let j = 0; j < side; j++) {
+        for (let i = 0; i < side; i++) {
+            const v = j * side + i;
+            const x = (i - half) * cell;
+            const z = (j - half) * cell;
+            positions[v * 3] = x;
+            positions[v * 3 + 1] = 0;
+            positions[v * 3 + 2] = z;
+            aCell[v] = cell;
+            // Chebyshev distance from the centre, normalised to the half-extent.
+            // Square rings need a square metric, or the morph band bulges at the
+            // corners and the seam opens there.
+            const u = Math.max(Math.abs(i - half), Math.abs(j - half)) / half;
+            const t = (u - (1 - MORPH_BAND)) / MORPH_BAND;
+            aMorph[v] = Math.min(Math.max(t, 0), 1);
+            aCoarse[v * 2] = -(i % 2) * cell;
+            aCoarse[v * 2 + 1] = -(j % 2) * cell;
+        }
+    }
+    // The hole spans the middle half in each axis, which is exactly the extent of
+    // the level below — the two meet edge to edge with nothing between them.
+    const holeLo = segments / 4;
+    const holeHi = segments - segments / 4;
+    const indices = [];
+    for (let j = 0; j < segments; j++) {
+        for (let i = 0; i < segments; i++) {
+            if (hollow && i >= holeLo && i < holeHi && j >= holeLo && j < holeHi)
+                continue;
+            const a = j * side + i;
+            const b = a + 1;
+            const c = a + side;
+            const d = c + 1;
+            indices.push(a, c, b, b, c, d);
+        }
+    }
+    const geometry = new THREE.BufferGeometry();
+    geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+    geometry.setAttribute('aCell', new THREE.BufferAttribute(aCell, 1));
+    geometry.setAttribute('aMorph', new THREE.BufferAttribute(aMorph, 1));
+    geometry.setAttribute('aCoarse', new THREE.BufferAttribute(aCoarse, 2));
+    geometry.setIndex(indices);
+    // The mesh is flat in object space and displaced in the vertex shader, so a
+    // computed bounding volume describes a plane and the ring is frustum-culled
+    // the moment the camera looks up. Infinite sphere, culling handled by the
+    // clipmap itself: it only ever exists around the camera.
+    geometry.boundingSphere = new THREE.Sphere(new THREE.Vector3(), Infinity);
+    geometry.boundingBox = new THREE.Box3(new THREE.Vector3(-Infinity, -Infinity, -Infinity), new THREE.Vector3(Infinity, Infinity, Infinity));
+    return { geometry, cell, level };
+}
+/**
+ * `segments` is rounded to a multiple of 8: the ring boundaries sit at
+ * `segments/4` and `segments/2`, and both must land on even indices or the morph
+ * pulls boundary vertices off their own edge.
+ */
+export function useClipmap(levels, segments, cellSize) {
+    const safeLevels = Math.max(1, Math.min(Math.round(levels), 14));
+    const safeSegments = Math.max(16, Math.round(segments / 8) * 8);
+    const safeCell = Math.max(0.05, cellSize);
+    const clipmap = useMemo(() => {
+        const out = [];
+        for (let l = 0; l < safeLevels; l++) {
+            out.push(buildLevel(safeSegments, safeCell * Math.pow(2, l), l > 0, l));
+        }
+        return { levels: out, sharedSnap: safeCell * 2 };
+    }, [safeLevels, safeSegments, safeCell]);
+    useEffect(() => () => { clipmap.levels.forEach((r) => r.geometry.dispose()); }, [clipmap]);
+    return clipmap;
+}
+export default useClipmap;

package/dist/hooks/useCloudLive.d.ts

@@ -0,0 +1,29 @@
+import type { Object3D } from 'three';
+/**
+ * Live cloud editing, the counterpart to useMaterialUniforms.
+ *
+ * A slider drag fires on every pointer-move. Routing that through Redux would
+ * dispatch and re-render the tree sixty times a second, and — because the cloud
+ * pass keys its temporal history off the config — would also restart the
+ * accumulation on every one of those frames, so the deck would boil while you tune
+ * it. Instead the controller finds the layer with findById(id) and writes straight
+ * into the renderer here; Redux only hears about it on slider end.
+ *
+ *   const live = useCloudLive(settings.id);
+ *   <BaseControllerUi onLiveChange={live.deck} onSettingsChange={dispatchToRedux} ... />
+ */
+/** Where VolumetricCloudsPass stashes its handle on the root object's userData. */
+export declare const CLOUD_LIVE_KEY = "__cloudLive";
+export interface CloudLiveHandle {
+    deck(key: string, value: number | boolean): void;
+    cirrus(key: string, value: number | boolean): void;
+    quality(key: string, value: number | boolean): void;
+}
+/**
+ * Safe before the layer mounts and after it unmounts: the handle is resolved at call
+ * time, not at hook time, so a controller opened before the scene is ready still works
+ * once it is — and a stale object reference degrades to a no-op instead of throwing.
+ */
+export declare function useCloudLive(target?: Object3D | string | null): CloudLiveHandle;
+export default useCloudLive;
+//# sourceMappingURL=useCloudLive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useCloudLive.d.ts","sourceRoot":"","sources":["../../src/hooks/useCloudLive.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGtC;;;;;;;;;;;;GAYG;AAEH,mFAAmF;AACnF,eAAO,MAAM,cAAc,gBAAgB,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC5B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IACjD,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IACnD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CACvD;AAID;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,GAAG,eAAe,CAkB/E;AAED,eAAe,YAAY,CAAC"}

package/dist/hooks/useCloudLive.js

@@ -0,0 +1,43 @@
+import { useMemo } from 'react';
+import { findById } from '../utils/sceneQuery.js';
+/**
+ * Live cloud editing, the counterpart to useMaterialUniforms.
+ *
+ * A slider drag fires on every pointer-move. Routing that through Redux would
+ * dispatch and re-render the tree sixty times a second, and — because the cloud
+ * pass keys its temporal history off the config — would also restart the
+ * accumulation on every one of those frames, so the deck would boil while you tune
+ * it. Instead the controller finds the layer with findById(id) and writes straight
+ * into the renderer here; Redux only hears about it on slider end.
+ *
+ *   const live = useCloudLive(settings.id);
+ *   <BaseControllerUi onLiveChange={live.deck} onSettingsChange={dispatchToRedux} ... />
+ */
+/** Where VolumetricCloudsPass stashes its handle on the root object's userData. */
+export const CLOUD_LIVE_KEY = '__cloudLive';
+const NOOP = { deck: () => { }, cirrus: () => { }, quality: () => { } };
+/**
+ * Safe before the layer mounts and after it unmounts: the handle is resolved at call
+ * time, not at hook time, so a controller opened before the scene is ready still works
+ * once it is — and a stale object reference degrades to a no-op instead of throwing.
+ */
+export function useCloudLive(target) {
+    return useMemo(() => {
+        const resolve = () => {
+            // Resolved per call, never cached. A findById() memoised in the
+            // controller resolves once — and if the layer is not mounted yet, which
+            // it is not while the layer is switched off, it resolves to null and
+            // stays null until the controller remounts. Every slider then silently
+            // does nothing.
+            const object = typeof target === 'string' ? findById(target) : target;
+            const handle = object?.userData?.[CLOUD_LIVE_KEY];
+            return handle ?? NOOP;
+        };
+        return {
+            deck: (key, value) => resolve().deck(key, value),
+            cirrus: (key, value) => resolve().cirrus(key, value),
+            quality: (key, value) => resolve().quality(key, value),
+        };
+    }, [target]);
+}
+export default useCloudLive;

package/dist/hooks/useCloudNoise.d.ts

@@ -0,0 +1,28 @@
+import * as THREE from 'three';
+/**
+ * Bakes the four cloud noise textures once and shares them across the scene.
+ *
+ * A hook rather than a provider: the cache is keyed on the renderer, so every
+ * caller in a Canvas gets the same volumes with no wrapper component to remember.
+ * Two decks and four placed clouds should not mean six 128-cubed volumes — the
+ * base texture alone is 8 MB, and the field is identical for all of them. What
+ * differs per cloud is how it samples it.
+ *
+ * The bake is a handful of GPU draws plus one readback, a few hundred ms on
+ * integrated graphics, paid once per renderer for the life of the page.
+ */
+export interface CloudNoise {
+    base: THREE.Data3DTexture;
+    detail: THREE.Data3DTexture;
+    weather: THREE.Texture;
+    curl: THREE.Texture;
+    dispose(): void;
+}
+export declare function bakeCloudNoise(gl: THREE.WebGLRenderer): CloudNoise | null;
+/**
+ * Null when the context cannot support the volumes. Callers should render nothing
+ * rather than treat that as an error.
+ */
+export declare function useCloudNoise(): CloudNoise | null;
+export default useCloudNoise;
+//# sourceMappingURL=useCloudNoise.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useCloudNoise.d.ts","sourceRoot":"","sources":["../../src/hooks/useCloudNoise.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,UAAU;IACvB,IAAI,EAAE,KAAK,CAAC,aAAa,CAAC;IAC1B,MAAM,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC;IACvB,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC;IACpB,OAAO,IAAI,IAAI,CAAC;CACnB;AAoGD,wBAAgB,cAAc,CAAC,EAAE,EAAE,KAAK,CAAC,aAAa,GAAG,UAAU,GAAG,IAAI,CAwBzE;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAKjD;AAED,eAAe,aAAa,CAAC"}

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