@3driseai/3drise-viewer 0.1.7 → 0.1.9

package/dist/components/volumetricClouds/VolumetricCloudsPass.js

@@ -0,0 +1,298 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as THREE from 'three';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useFrame, useThree } from '@react-three/fiber';
+import { useFrameRenderer } from '../../hooks/useFrameRenderer.js';
+import { useObjectReady } from '../../hooks/useObjectReady.js';
+import { CLOUD_LIVE_KEY } from '../../hooks/useCloudLive.js';
+import { useCloudNoise } from '../../hooks/useCloudNoise.js';
+import { useCloudSun } from '../../hooks/useCloudSun.js';
+import { CloudVolumeMaterial } from '../../shaders/clouds/CloudVolumeMaterial.js';
+import { CirrusMaterial } from '../../shaders/clouds/CirrusMaterial.js';
+import { CloudResolveMaterial } from '../../shaders/clouds/CloudResolveMaterial.js';
+import { CloudCompositeMaterial } from '../../shaders/clouds/CloudCompositeMaterial.js';
+import { applyCameraUniforms, applyCirrusUniforms, applyDeckUniforms, applySunUniforms, } from '../../utils/cloudUniforms.js';
+import { applyCloudsKeyframeAnimations, applyCloudsMouseMove, resolveDeckConfig, } from '../../utils/handleCloudsAnimations.js';
+const quad = new THREE.PlaneGeometry(2, 2);
+const orthoCam = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+function passScene(material) {
+    const scene = new THREE.Scene();
+    scene.add(new THREE.Mesh(quad, material));
+    return scene;
+}
+/** rgb 0, alpha 1 — composites as "nothing here", so a disabled layer costs one texel. */
+function emptyTexture() {
+    const tex = new THREE.DataTexture(Uint8Array.from([0, 0, 0, 255]), 1, 1, THREE.RGBAFormat, THREE.UnsignedByteType);
+    tex.needsUpdate = true;
+    return tex;
+}
+const VolumetricCloudsPass = ({ id = '3drise-clouds', deck, cirrus, quality, skySettings, timeSettings, sunIntensity = 1, animations, mouseMove, onObjectReady, onObjectDispose, }) => {
+    const gl = useThree((s) => s.gl);
+    const scene = useThree((s) => s.scene);
+    const size = useThree((s) => s.size);
+    const dpr = useThree((s) => s.viewport.dpr);
+    const noise = useCloudNoise();
+    const { state: sun, update: updateSun } = useCloudSun({ skySettings, timeSettings });
+    const deckOn = !!deck?.enabled;
+    const cirrusOn = !!cirrus?.enabled;
+    const width = Math.max(2, Math.floor(size.width * dpr));
+    const height = Math.max(2, Math.floor(size.height * dpr));
+    const lowW = Math.max(2, Math.floor(width * quality.resolutionScale));
+    const lowH = Math.max(2, Math.floor(height * quality.resolutionScale));
+    const targets = useMemo(() => {
+        const makeSceneTarget = () => {
+            const depthTexture = new THREE.DepthTexture(width, height);
+            depthTexture.type = THREE.UnsignedIntType;
+            depthTexture.minFilter = THREE.NearestFilter;
+            depthTexture.magFilter = THREE.NearestFilter;
+            return new THREE.WebGLRenderTarget(width, height, {
+                minFilter: THREE.LinearFilter,
+                magFilter: THREE.LinearFilter,
+                type: THREE.HalfFloatType,
+                depthBuffer: true,
+                depthTexture,
+            });
+        };
+        const lowOpts = {
+            minFilter: THREE.LinearFilter,
+            magFilter: THREE.LinearFilter,
+            type: THREE.HalfFloatType,
+            depthBuffer: false,
+            stencilBuffer: false,
+        };
+        return {
+            // Ping-ponged so nothing ever samples the depth attachment it is writing.
+            sceneA: makeSceneTarget(),
+            sceneB: makeSceneTarget(),
+            deck: new THREE.WebGLRenderTarget(lowW, lowH, lowOpts),
+            cirrus: new THREE.WebGLRenderTarget(lowW, lowH, lowOpts),
+            histA: new THREE.WebGLRenderTarget(lowW, lowH, lowOpts),
+            histB: new THREE.WebGLRenderTarget(lowW, lowH, lowOpts),
+        };
+    }, [width, height, lowW, lowH]);
+    useEffect(() => () => { Object.values(targets).forEach((t) => t.dispose()); }, [targets]);
+    const passes = useMemo(() => {
+        const deckMat = new CloudVolumeMaterial();
+        const cirrusMat = new CirrusMaterial();
+        const resolveMat = new CloudResolveMaterial();
+        const compositeMat = new CloudCompositeMaterial();
+        for (const m of [deckMat, cirrusMat, resolveMat, compositeMat]) {
+            m.glslVersion = THREE.GLSL3;
+            m.depthTest = false;
+            m.depthWrite = false;
+        }
+        return {
+            deckMat, cirrusMat, resolveMat, compositeMat,
+            deckScene: passScene(deckMat),
+            cirrusScene: passScene(cirrusMat),
+            resolveScene: passScene(resolveMat),
+            compositeScene: passScene(compositeMat),
+        };
+    }, []);
+    useEffect(() => () => {
+        [passes.deckMat, passes.cirrusMat, passes.resolveMat, passes.compositeMat]
+            .forEach((m) => m.dispose());
+    }, [passes]);
+    const empty = useMemo(emptyTexture, []);
+    const prevViewProj = useRef(new THREE.Matrix4());
+    const jitProj = useRef(new THREE.Matrix4());
+    const jitInv = useRef(new THREE.Matrix4());
+    const frame = useRef(0);
+    const validHistory = useRef(0);
+    const time = useRef(0);
+    const histFlip = useRef(0);
+    const prevCamPos = useRef(new THREE.Vector3());
+    const prevCamQuat = useRef(new THREE.Quaternion());
+    // Animation scratch. Kept in refs so a keyframed coverage does not re-render the
+    // React tree sixty times a second.
+    const override = useRef({});
+    const startValues = useRef({});
+    // Live controller overrides. A slider drag writes here every pointer-move and the
+    // frame loop reads it on top of the config, so the deck responds without a Redux
+    // dispatch per frame. Cleared when the config identity changes, which is exactly
+    // slider-end committing the same value.
+    const liveDeck = useRef({});
+    const liveCirrus = useRef({});
+    const liveQuality = useRef({});
+    useEffect(() => { liveDeck.current = {}; }, [deck]);
+    useEffect(() => { liveCirrus.current = {}; }, [cirrus]);
+    useEffect(() => { liveQuality.current = {}; }, [quality]);
+    // The handle a controller reaches through findById(id).userData. Set in an effect,
+    // never as a userData JSX prop: R3F replaces the whole userData object on every
+    // render, which would drop the handle the moment anything above re-renders.
+    const rootRef = useRef(null);
+    const liveHandle = useMemo(() => ({
+        deck: (key, value) => { liveDeck.current[key] = value; },
+        cirrus: (key, value) => { liveCirrus.current[key] = value; },
+        quality: (key, value) => { liveQuality.current[key] = value; },
+    }), []);
+    useEffect(() => {
+        const root = rootRef.current;
+        if (!root)
+            return;
+        root.userData.id = id;
+        root.userData[CLOUD_LIVE_KEY] = liveHandle;
+        return () => {
+            delete root.userData[CLOUD_LIVE_KEY];
+        };
+    }, [id, liveHandle]);
+    // ObjectReadySource's union is widened by Record<string, any>, but spelling the
+    // cast out keeps the intent: this reports the layer's settings, not a mesh's.
+    useObjectReady(rootRef, { id, type: 'clouds', deck, cirrus, quality }, onObjectReady, onObjectDispose);
+    // Only a resolution change genuinely invalidates the history — the buffers are
+    // reallocated and nothing in them maps to the new grid.
+    //
+    // Config edits deliberately do NOT reset it. Dragging a slider dispatches a new
+    // config object every pointer-move, so resetting here would restart the temporal
+    // accumulation on every frame of the drag and the deck would boil while you tune
+    // it. The neighbourhood clamp in the resolve is exactly what absorbs a field that
+    // changes under the history.
+    useEffect(() => { validHistory.current = 0; }, [width, height, lowW, lowH]);
+    // The frame body, extracted so it can be driven from two places: the render loop,
+    // and an off-loop caller that needs a finished image (see useFrameRenderer). It is
+    // held in a ref rather than a useCallback because it closes over a dozen pieces of
+    // per-frame state, and a dependency array over all of them would be re-created
+    // every render anyway — which would re-register the frame renderer every render.
+    const drawFrame = (camera, pointer, delta) => {
+        if (!noise)
+            return;
+        frame.current += 1;
+        time.current += Math.min(delta, 0.05);
+        updateSun();
+        // ---- 1. scene ----
+        const sceneRT = (frame.current & 1) ? targets.sceneA : targets.sceneB;
+        const prevTarget = gl.getRenderTarget();
+        const prevAutoClear = gl.autoClear;
+        gl.autoClear = true;
+        gl.setRenderTarget(sceneRT);
+        // No sky pass. SkyController / Skybox already drew the background into this
+        // target; the clouds only borrow the atmosphere function for ambient and
+        // aerial perspective, so a second sky would just fight the first.
+        gl.render(scene, camera);
+        // Sub-pixel rotation, applied ONLY to the cloud ray basis. Jittering
+        // camera.projectionMatrix would shimmer the scene pass, which nothing resolves.
+        const jx = ((frame.current & 1) ? 0.5 : -0.5) / lowW;
+        const jy = ((frame.current & 2) ? 0.5 : -0.5) / lowH;
+        jitProj.current.copy(camera.projectionMatrix);
+        jitProj.current.elements[8] = jx * 2;
+        jitProj.current.elements[9] = jy * 2;
+        jitInv.current.copy(jitProj.current).invert();
+        const bindShared = (m) => {
+            applySunUniforms(m, sun, sunIntensity);
+            applyCameraUniforms(m, camera, jitInv.current, lowW, lowH);
+            m.uniforms.u_time.value = time.current;
+            if (m.uniforms.u_frame)
+                m.uniforms.u_frame.value = frame.current;
+            m.uniforms.u_depth.value = sceneRT.depthTexture;
+            m.uniforms.u_hasDepth.value = 1;
+            m.uniforms.u_screenSpace.value = 1;
+        };
+        // ---- 2 & 3. deck march, then temporal resolve ----
+        let deckTex = empty;
+        if (deckOn && deck) {
+            // Keyframes first, then pointer on top, so the two compose rather than
+            // the pointer snapping back to the stored config every frame.
+            for (const k in override.current)
+                delete override.current[k];
+            applyCloudsKeyframeAnimations(animations?.clouds?.animations, startValues.current, deck, override.current, time.current);
+            if (mouseMove?.enabled && mouseMove.clouds?.enabled) {
+                applyCloudsMouseMove(mouseMove.clouds.properties, deck, override.current, pointer);
+            }
+            // config -> keyframe/pointer domain -> live controller drag, in that order.
+            const animated = resolveDeckConfig(deck, override.current);
+            const live = resolveDeckConfig(animated, liveDeck.current);
+            const liveQual = { ...quality, ...liveQuality.current };
+            const m = passes.deckMat;
+            applyDeckUniforms(m, live, liveQual);
+            m.uniforms.u_base.value = noise.base;
+            m.uniforms.u_detail.value = noise.detail;
+            m.uniforms.u_weather.value = noise.weather;
+            m.uniforms.u_curl.value = noise.curl;
+            m.uniforms.u_host.value = 1;
+            bindShared(m);
+            gl.setRenderTarget(targets.deck);
+            gl.render(passes.deckScene, orthoCam);
+            const history = histFlip.current ? targets.histB : targets.histA;
+            const destination = histFlip.current ? targets.histA : targets.histB;
+            const r = passes.resolveMat.uniforms;
+            r.u_current.value = targets.deck.texture;
+            r.u_history.value = history.texture;
+            r.u_prevViewProj.value.copy(prevViewProj.current);
+            // UNJITTERED, deliberately. The march samples along jittered rays, but the
+            // reprojection maps pixel CENTRES between frames. Feeding it the jittered
+            // inverse offsets every history fetch by the current sub-pixel jitter, and
+            // since that cycles through four offsets the resolved image shifts about a
+            // full-res pixel every frame even with the camera locked. That reads as jitter.
+            r.u_invProj.value.copy(camera.projectionMatrixInverse);
+            r.u_camWorld.value.copy(camera.matrixWorld);
+            r.u_camPos.value.copy(camera.position);
+            r.u_texel.value.set(1 / lowW, 1 / lowH);
+            // Reprojection proxy: the deck's mid-height. Cheaper than storing
+            // per-pixel cloud depth and, for a layer far relative to per-frame
+            // camera motion, indistinguishable.
+            r.u_proxyHeight.value = (live.baseAltitude + live.topAltitude) * 0.5;
+            r.u_valid.value = validHistory.current > 1 ? 1 : 0;
+            // While the camera moves, the proxy-plane reprojection is only approximate
+            // and a high history weight smears. Ease off, and restore it once still.
+            const moved = camera.position.distanceToSquared(prevCamPos.current) > 1e-8
+                || Math.abs(camera.quaternion.dot(prevCamQuat.current)) < 0.9999995;
+            r.u_blend.value = moved ? Math.min(quality.temporalBlend, 0.7) : quality.temporalBlend;
+            gl.setRenderTarget(destination);
+            gl.render(passes.resolveScene, orthoCam);
+            histFlip.current ^= 1;
+            validHistory.current += 1;
+            deckTex = destination.texture;
+        }
+        else {
+            validHistory.current = 0;
+        }
+        // ---- 4. cirrus ----
+        let cirrusTex = empty;
+        if (cirrusOn && cirrus) {
+            const m = passes.cirrusMat;
+            applyCirrusUniforms(m, { ...cirrus, ...liveCirrus.current }, quality);
+            m.uniforms.u_weather.value = noise.weather;
+            bindShared(m);
+            gl.setRenderTarget(targets.cirrus);
+            gl.render(passes.cirrusScene, orthoCam);
+            cirrusTex = targets.cirrus.texture;
+        }
+        // ---- 5. composite ----
+        const c = passes.compositeMat.uniforms;
+        c.u_scene.value = sceneRT.texture;
+        c.u_clouds.value = deckTex;
+        c.u_cirrus.value = cirrusTex;
+        c.u_depth.value = sceneRT.depthTexture;
+        c.u_lowTexel.value.set(1 / lowW, 1 / lowH);
+        c.u_exposure.value = quality.exposure;
+        c.u_tonemap.value = quality.tonemap ? 1 : 0;
+        c.u_hasCirrus.value = cirrusOn ? 1 : 0;
+        gl.setRenderTarget(prevTarget);
+        gl.render(passes.compositeScene, orthoCam);
+        gl.autoClear = prevAutoClear;
+        prevViewProj.current.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+        prevCamPos.current.copy(camera.position);
+        prevCamQuat.current.copy(camera.quaternion);
+    };
+    // Keep the latest body and pointer reachable from the off-loop path without
+    // making either a dependency of the registration.
+    const drawRef = useRef(drawFrame);
+    drawRef.current = drawFrame;
+    const pointerRef = useRef(new THREE.Vector2());
+    useFrame((state, delta) => {
+        pointerRef.current.copy(state.pointer);
+        drawRef.current(state.camera, state.pointer, delta);
+    }, 1);
+    // This pass composites to the canvas itself, so gl.render(scene, camera) is not a
+    // complete frame while it is mounted — it draws the scene graph and drops the
+    // clouds, which is what made screenshots come back with everything but the sky.
+    // delta 0: an off-loop frame must not advance cloud time or the animation jumps.
+    const renderCompleteFrame = useCallback((camera) => {
+        drawRef.current(camera, pointerRef.current, 0);
+    }, []);
+    useFrameRenderer(renderCompleteFrame);
+    // An empty group, but a real one: it carries userData.id so findById() can reach
+    // this layer, and the live handle so a controller can drive it without Redux.
+    return _jsx("group", { ref: rootRef });
+};
+export default VolumetricCloudsPass;

package/dist/components/volumetricClouds/index.d.ts

@@ -0,0 +1,8 @@
+export type { CloudLayerProps } from './types';
+export type { VolumetricCloudsPassProps } from './VolumetricCloudsPass';
+export { default as VolumetricCloudsPass } from './VolumetricCloudsPass';
+export { default as Cumulus } from './Cumulus';
+export { default as Stratocumulus } from './Stratocumulus';
+export { default as Cumulonimbus } from './Cumulonimbus';
+export { default as Cirrus } from './Cirrus';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/volumetricClouds/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/volumetricClouds/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,YAAY,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AAExE,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC"}

package/dist/components/volumetricClouds/index.js

@@ -0,0 +1,7 @@
+// Volumetric cloud layers. Each renders the shared pipeline with the coercions its
+// type needs; exactly one is mounted at a time, by CloudsGenerator.
+export { default as VolumetricCloudsPass } from './VolumetricCloudsPass.js';
+export { default as Cumulus } from './Cumulus.js';
+export { default as Stratocumulus } from './Stratocumulus.js';
+export { default as Cumulonimbus } from './Cumulonimbus.js';
+export { default as Cirrus } from './Cirrus.js';

package/dist/components/volumetricClouds/types.d.ts

@@ -0,0 +1,17 @@
+import type { MouseMoveInteractions, ObjectAnimations, SkySettings, TimeSettings } from '@3driseai/3drise-core';
+import type { ObjectReadyProps } from '../../types/objectReady';
+import type { CirrusLayerConfig, CloudDeckConfig, CloudsQualityConfig } from '../../types/cloudConfigs';
+/** Shared by every layer component. The generator hands all four the same shape. */
+export interface CloudLayerProps extends ObjectReadyProps {
+    /** Scene id, so a controller can findById() the layer and drive it live. */
+    id?: string;
+    deck: CloudDeckConfig;
+    cirrus: CirrusLayerConfig | null;
+    quality: CloudsQualityConfig;
+    skySettings?: SkySettings;
+    timeSettings?: TimeSettings;
+    sunIntensity?: number;
+    animations?: ObjectAnimations;
+    mouseMove?: MouseMoveInteractions;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/components/volumetricClouds/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/volumetricClouds/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAChH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAExG,oFAAoF;AACpF,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACrD,4EAA4E;IAC5E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,SAAS,CAAC,EAAE,qBAAqB,CAAC;CACrC"}

package/dist/components/volumetricClouds/types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/water/Host.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import type { OceanLayerProps } from './types';
+/**
+ * Picks the container for a water type.
+ *
+ * Every type works on both hosts — a pool of storm water is a fair thing to
+ * want — so the host switch lives here, once, rather than in each of the four
+ * type wrappers.
+ */
+declare const Host: React.FC<OceanLayerProps>;
+export default Host;
+//# sourceMappingURL=Host.d.ts.map

package/dist/components/water/Host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Host.d.ts","sourceRoot":"","sources":["../../../src/components/water/Host.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;GAMG;AACH,QAAA,MAAM,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CACuD,CAAC;AAE5F,eAAe,IAAI,CAAC"}

package/dist/components/water/Host.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import OceanSurface from './OceanSurface.js';
+import WaterBody from './WaterBody.js';
+/**
+ * Picks the container for a water type.
+ *
+ * Every type works on both hosts — a pool of storm water is a fair thing to
+ * want — so the host switch lives here, once, rather than in each of the four
+ * type wrappers.
+ */
+const Host = (props) => props.config.host === 'object' ? _jsx(WaterBody, { ...props }) : _jsx(OceanSurface, { ...props });
+export default Host;

package/dist/components/water/Lake.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import type { OceanLayerProps } from './types';
+/**
+ * Inland water.
+ *
+ * Short fetch does all the work: a lake in a gale has small, short, steep waves,
+ * because there is no open water upwind for anything longer to build over. Get
+ * that wrong and a lake renders as a shrunken ocean, which is the single most
+ * common mistake in water rendering.
+ *
+ * Swell is clamped, and that one IS a coercion. Swell is energy that has
+ * travelled out of the weather that made it, over hundreds of kilometres; a lake
+ * cannot have any. Left free, the slider produces long, low, ocean-looking rollers
+ * on a pond, which is exactly the failure the type exists to prevent.
+ */
+declare const Lake: React.FC<OceanLayerProps>;
+export default Lake;
+//# sourceMappingURL=Lake.d.ts.map

package/dist/components/water/Lake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Lake.d.ts","sourceRoot":"","sources":["../../../src/components/water/Lake.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAkB,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;;;;;;;GAYG;AACH,QAAA,MAAM,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAGnC,CAAC;AAEF,eAAe,IAAI,CAAC"}

package/dist/components/water/Lake.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import Host from './Host.js';
+/**
+ * Inland water.
+ *
+ * Short fetch does all the work: a lake in a gale has small, short, steep waves,
+ * because there is no open water upwind for anything longer to build over. Get
+ * that wrong and a lake renders as a shrunken ocean, which is the single most
+ * common mistake in water rendering.
+ *
+ * Swell is clamped, and that one IS a coercion. Swell is energy that has
+ * travelled out of the weather that made it, over hundreds of kilometres; a lake
+ * cannot have any. Left free, the slider produces long, low, ocean-looking rollers
+ * on a pond, which is exactly the failure the type exists to prevent.
+ */
+const Lake = ({ config, ...rest }) => {
+    const resolved = useMemo(() => ({ ...config, swell: Math.min(config.swell, 0.15) }), [config]);
+    return _jsx(Host, { config: resolved, ...rest });
+};
+export default Lake;

package/dist/components/water/OceanSurface.d.ts

@@ -0,0 +1,27 @@
+import React from 'react';
+import type { OceanLayerProps } from './types';
+/**
+ * The world ocean: a geometry clipmap that follows the camera, displaced in the
+ * vertex shader by the wave field.
+ *
+ * One clipmap, one material, four water types — they differ by the spectrum the
+ * CPU uploads, not by having separate renderers, the same way the four landforms
+ * share one height field and three of the four cloud types share one marcher.
+ *
+ * Like the terrain and unlike the cloud pass, this does NOT take over the render
+ * loop. It is an ordinary mesh with an ordinary material, so it depth-sorts
+ * against scene objects, receives the sun's shadow map, takes scene fog, and the
+ * cloud pass composites over it correctly because it is simply in the scene when
+ * that pass renders.
+ *
+ * ## The clipmap follows the camera in XZ only
+ *
+ * Y is `config.seaLevel`, which is this body's own and has nothing to do with
+ * the terrain's. Sea level and ground level are independent by design: a scene
+ * may have water and no terrain, terrain and no water, or a lake at +40 m beside
+ * a sea at 0. What connects them is computed — the shoreline is where the ground
+ * crosses this surface — never configured.
+ */
+declare const OceanSurface: React.FC<OceanLayerProps>;
+export default OceanSurface;
+//# sourceMappingURL=OceanSurface.d.ts.map

package/dist/components/water/OceanSurface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OceanSurface.d.ts","sourceRoot":"","sources":["../../../src/components/water/OceanSurface.tsx"],"names":[],"mappings":"AACA,OAAO,KAAiB,MAAM,OAAO,CAAC;AAItC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,QAAA,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAuD3C,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/components/water/OceanSurface.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRef } from 'react';
+import { useObjectReady } from '../../hooks/useObjectReady.js';
+import { useClipmap } from '../../hooks/useClipmap.js';
+import { useOceanMaterial } from '../../hooks/useOceanMaterial.js';
+/**
+ * The world ocean: a geometry clipmap that follows the camera, displaced in the
+ * vertex shader by the wave field.
+ *
+ * One clipmap, one material, four water types — they differ by the spectrum the
+ * CPU uploads, not by having separate renderers, the same way the four landforms
+ * share one height field and three of the four cloud types share one marcher.
+ *
+ * Like the terrain and unlike the cloud pass, this does NOT take over the render
+ * loop. It is an ordinary mesh with an ordinary material, so it depth-sorts
+ * against scene objects, receives the sun's shadow map, takes scene fog, and the
+ * cloud pass composites over it correctly because it is simply in the scene when
+ * that pass renders.
+ *
+ * ## The clipmap follows the camera in XZ only
+ *
+ * Y is `config.seaLevel`, which is this body's own and has nothing to do with
+ * the terrain's. Sea level and ground level are independent by design: a scene
+ * may have water and no terrain, terrain and no water, or a lake at +40 m beside
+ * a sea at 0. What connects them is computed — the shoreline is where the ground
+ * crosses this surface — never configured.
+ */
+const OceanSurface = ({ id = '3drise-water', config, quality, skySettings, timeSettings, sunIntensity = 1, onObjectReady, onObjectDispose, }) => {
+    const clipmap = useClipmap(quality.levels, quality.segments, quality.cellSize);
+    const meshRefs = useRef([]);
+    const { material, rootRef } = useOceanMaterial({
+        id,
+        config,
+        quality,
+        skySettings,
+        timeSettings,
+        sunIntensity,
+        onFrame: (cfg, _qual, state) => {
+            // ONE origin for the whole pyramid, snapped to twice the finest cell.
+            //
+            // Snapping each ring to its own cell grid is the textbook clipmap and
+            // it is what tears the seams open: neighbouring rings then sit on
+            // origins up to a cell apart, and boundaries that match exactly in
+            // local space miss each other in the world by that offset.
+            const snap = clipmap.sharedSnap;
+            const ox = Math.round(state.camera.position.x / snap) * snap;
+            const oz = Math.round(state.camera.position.z / snap) * snap;
+            for (let i = 0; i < clipmap.levels.length; i++) {
+                meshRefs.current[i]?.position.set(ox, cfg.seaLevel, oz);
+            }
+        },
+    });
+    useObjectReady(rootRef, { id, type: 'ocean', config, quality }, onObjectReady, onObjectDispose);
+    return (_jsx("group", { ref: rootRef, children: clipmap.levels.map((ring, i) => (_jsx("mesh", { ref: (m) => { meshRefs.current[i] = m; }, geometry: ring.geometry, material: material, receiveShadow: quality.receiveShadows, 
+            // Displacement happens in the vertex shader, so the
+            // object-space bounds describe a flat plane. Culling against
+            // them hides the water the moment the camera tilts up.
+            frustumCulled: false }, ring.level))) }));
+};
+export default OceanSurface;

package/dist/components/water/Sea.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import type { OceanLayerProps } from './types';
+/**
+ * Open ocean.
+ *
+ * The reference case for the wave field, because everything in the spectrum is
+ * visible at once: long swell running under a shorter wind sea, whitecaps where
+ * the two coincide and steepen a crest past folding, and a horizon that only
+ * looks right because of the curvature term.
+ *
+ * Nothing is coerced here. The four types differ in the spectrum the CPU
+ * uploads, not in what the shader is allowed to do — unlike the terrain, where
+ * canyon-only shaping had to be forced off on the other landforms because the
+ * shader branches on the type. Nothing in the water shader branches on it.
+ */
+declare const Sea: React.FC<OceanLayerProps>;
+export default Sea;
+//# sourceMappingURL=Sea.d.ts.map

package/dist/components/water/Sea.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sea.d.ts","sourceRoot":"","sources":["../../../src/components/water/Sea.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;;;;;;;GAYG;AACH,QAAA,MAAM,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAAkC,CAAC;AAEtE,eAAe,GAAG,CAAC"}

package/dist/components/water/Sea.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import Host from './Host.js';
+/**
+ * Open ocean.
+ *
+ * The reference case for the wave field, because everything in the spectrum is
+ * visible at once: long swell running under a shorter wind sea, whitecaps where
+ * the two coincide and steepen a crest past folding, and a horizon that only
+ * looks right because of the curvature term.
+ *
+ * Nothing is coerced here. The four types differ in the spectrum the CPU
+ * uploads, not in what the shader is allowed to do — unlike the terrain, where
+ * canyon-only shaping had to be forced off on the other landforms because the
+ * shader branches on the type. Nothing in the water shader branches on it.
+ */
+const Sea = (props) => _jsx(Host, { ...props });
+export default Sea;

package/dist/components/water/Shore.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import type { OceanLayerProps } from './types';
+/**
+ * Coastal water.
+ *
+ * Narrow directional spread, because waves refract into alignment with the beach
+ * as they shoal, and a stronger shoreline than the other types: this is the one
+ * that is defined by meeting the ground rather than by the wind over it.
+ *
+ * The shoreline itself — depth-ramped colour, the foam line and the wash — needs
+ * the refraction depth grab and the terrain height field, so today this type is
+ * a coastal spectrum with the shore parameters standing ready. That is phase 4.
+ */
+declare const Shore: React.FC<OceanLayerProps>;
+export default Shore;
+//# sourceMappingURL=Shore.d.ts.map

package/dist/components/water/Shore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Shore.d.ts","sourceRoot":"","sources":["../../../src/components/water/Shore.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,QAAA,MAAM,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAAkC,CAAC;AAExE,eAAe,KAAK,CAAC"}

package/dist/components/water/Shore.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import Host from './Host.js';
+/**
+ * Coastal water.
+ *
+ * Narrow directional spread, because waves refract into alignment with the beach
+ * as they shoal, and a stronger shoreline than the other types: this is the one
+ * that is defined by meeting the ground rather than by the wind over it.
+ *
+ * The shoreline itself — depth-ramped colour, the foam line and the wash — needs
+ * the refraction depth grab and the terrain height field, so today this type is
+ * a coastal spectrum with the shore parameters standing ready. That is phase 4.
+ */
+const Shore = (props) => _jsx(Host, { ...props });
+export default Shore;

package/dist/components/water/Storm.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import type { OceanLayerProps } from './types';
+/**
+ * Storm sea.
+ *
+ * Same model as `Sea` with the wind at the top of its range, which is where the
+ * Jacobian foam earns its place: past about 15 m/s the crests fold on their own
+ * and the whitecaps appear because the surface is genuinely breaking, not
+ * because a threshold was lowered. Turn choppiness down and the storm loses its
+ * foam — that is the model being honest, not a bug.
+ */
+declare const Storm: React.FC<OceanLayerProps>;
+export default Storm;
+//# sourceMappingURL=Storm.d.ts.map

package/dist/components/water/Storm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Storm.d.ts","sourceRoot":"","sources":["../../../src/components/water/Storm.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;;;GAQG;AACH,QAAA,MAAM,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAAkC,CAAC;AAExE,eAAe,KAAK,CAAC"}

package/dist/components/water/Storm.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import Host from './Host.js';
+/**
+ * Storm sea.
+ *
+ * Same model as `Sea` with the wind at the top of its range, which is where the
+ * Jacobian foam earns its place: past about 15 m/s the crests fold on their own
+ * and the whitecaps appear because the surface is genuinely breaking, not
+ * because a threshold was lowered. Turn choppiness down and the storm loses its
+ * foam — that is the model being honest, not a bug.
+ */
+const Storm = (props) => _jsx(Host, { ...props });
+export default Storm;