@3driseai/3drise-viewer 0.1.41 → 0.1.43

package/dist/hooks/useTimeLighting.js

@@ -0,0 +1,67 @@
+// =============================================================================
+// useTimeLighting — objects that answer the scene's time of day (TimeControls)
+// =============================================================================
+//
+// The one pattern for objects lit by the time of day with no real lights (urban roads with their
+// street lamps, buildings with their windows, sports courts with their floodlights…):
+//
+//   - the scene sun: useCloudSun follows the sky system (TimeControls -> setTimeSettings) or the
+//     rendered sky; every frame each uniform set that carries the sun block (uSunDir…) gets
+//     applySun with the object's `lighting` override (auto | day | night) — uNight follows the
+//     sun's height, and the shaders fade lamp pools, window glow and floodlight heads by it;
+//   - the lamp list (urbanCore's lampRegistry): an object's lamps register in WORLD space (the
+//     object's core keeps their positions current in its update). When the list changes or the
+//     object moves, each surface re-gathers the lamps that reach its bounds (gatherLamps into
+//     uLamps / uLampColors), or re-bakes its lamp field for a large merged surface — nothing
+//     recompiles.
+//
+// A component passes its instance (uniformSets, local bounds(), optional lampTargets()) and its
+// per-frame update, which runs between the sun and the lamp gathering (so lamps the core moved
+// this frame are gathered this frame). relight() forces a re-gather (after an apply / rebuild).
+//
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { useFrame } from '@react-three/fiber';
+import { useCloudSun } from './useCloudSun.js';
+import { applySun, gatherLamps, bakeLampField, lampRegistry } from '../components/urban/urbanCore.js';
+const _box = new THREE.Box3();
+export function useTimeLighting({ rootRef, instance, lighting, update }) {
+    const sun = useCloudSun();
+    const lampVersion = useRef(-1);
+    const lastWorld = useMemo(() => new THREE.Matrix4(), []);
+    const relight = useCallback(() => { lampVersion.current = -1; }, []);
+    useEffect(relight, [instance, relight]); // a new instance gathers on its first frame
+    useFrame((state, delta) => {
+        const dt = Math.min(delta, 0.1);
+        const s = sun.update();
+        const mode = lighting || 'auto';
+        const sets = instance.uniformSets ?? [];
+        for (const u of sets)
+            if (u.uSunDir)
+                applySun(u, s, mode);
+        update?.(dt, state);
+        const root = rootRef.current;
+        if (!root)
+            return;
+        root.updateMatrixWorld();
+        const moved = !lastWorld.equals(root.matrixWorld);
+        if (moved)
+            lastWorld.copy(root.matrixWorld);
+        if (lampVersion.current === lampRegistry.version && !moved)
+            return;
+        lampVersion.current = lampRegistry.version;
+        const targets = instance.lampTargets
+            ? instance.lampTargets()
+            : instance.bounds
+                ? sets.filter((u) => u.uLamps).map((u) => ({ u, bounds: instance.bounds() }))
+                : [];
+        for (const t of targets) {
+            _box.copy(t.bounds).applyMatrix4(root.matrixWorld);
+            if (t.field)
+                bakeLampField(t.field, _box);
+            else if (t.u)
+                gatherLamps(t.u, _box, null);
+        }
+    });
+    return { relight };
+}

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './types';
 export * from './components';
 export * from './hooks';
 export { createSceneHandle } from './api/sceneHandle';
+export { applyRenderValue, registerRenderEffect, registerRenderTargets, RENDER_LIVE_PATHS } from './render/renderLive';
 export { default as GalleryRuntime, GALLERY_ALL, GALLERY_IN_VIEW } from './galleryRuntime';
 export type { GalleryControls, GalleryInfo, GalleryChangeEvent } from './galleryRuntime';
 export * from './animationsV2';
@@ -18,6 +19,9 @@ export { cameraManager } from './utils/CameraSingleton';
 export { applyAnchorSettings, createCurves, createSunPosition, randomRange, } from './utils/utils3d';
 export { applyAnchorSettings as applyAnchorSettingsLegacy } from './utils/anchorUtils';
 export * from './utils/shapes';
+export { buildScriptGeometry, cachedScriptGeometry, clearScriptGeometryCache, ScriptGeometryError } from './utils/geometryScript';
+export type { ScriptBuild } from './utils/geometryScript';
+export { loadSvgAsset, svgAssetSync, svgAssetError } from './utils/svgAsset';
 export * from './utils/pickProxy';
 export { hasHoverAnimation } from './utils/hasHoverAnimation';
 export { findById } from './utils/sceneQuery';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -8,6 +8,8 @@ export * from './components/index.js';
 export * from './hooks/index.js';
 // External control of a loaded project (ProjectLoader ref / onSceneReady)
 export { createSceneHandle } from './api/sceneHandle.js';
+// The `render` target's per-frame writes (post-processing instances, exposure, HDR).
+export { applyRenderValue, registerRenderEffect, registerRenderTargets, RENDER_LIVE_PATHS } from './render/renderLive.js';
 // The live galleries and their navigation contract (next / prev / goTo), shared by SceneHandle.galleries, the 'gallery' trigger and the studio.
 export { default as GalleryRuntime, GALLERY_ALL, GALLERY_IN_VIEW } from './galleryRuntime.js';
 export * from './animationsV2/index.js';
@@ -22,6 +24,8 @@ export { cameraManager } from './utils/CameraSingleton.js';
 export { applyAnchorSettings, createCurves, createSunPosition, randomRange, } from './utils/utils3d.js';
 export { applyAnchorSettings as applyAnchorSettingsLegacy } from './utils/anchorUtils.js';
 export * from './utils/shapes.js';
+export { buildScriptGeometry, cachedScriptGeometry, clearScriptGeometryCache, ScriptGeometryError } from './utils/geometryScript.js';
+export { loadSvgAsset, svgAssetSync, svgAssetError } from './utils/svgAsset.js';
 export * from './utils/pickProxy.js';
 export { hasHoverAnimation } from './utils/hasHoverAnimation.js';
 export { findById } from './utils/sceneQuery.js';

package/dist/operations/catalogue/shaderLayers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shaderLayers.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/shaderLayers.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEhD,MAAM,WAAW,WAAW;IACxB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC7C,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gGAAgG;IAChG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kGAAkG;IAClG,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAmCD,+FAA+F;AAC/F,eAAO,MAAM,QAAQ,GAAI,KAAK,QAAQ,KAAG,OAEmE,CAAC;AAO7G;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAOhH;AA6BD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCvE;AA8CD,0FAA0F;AAC1F,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,iBAAiB,GAAG,uBAAuB,CAAC,CAKnG;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAM5D;AAED,mDAAmD;AACnD,eAAO,MAAM,SAAS,GAAI,KAAK,QAAQ,KAAG,OACiC,CAAC;AAE5E,eAAO,MAAM,QAAQ,GAAI,KAAK,QAAQ,EAAE,KAAK,MAAM,KAAG,OACgB,CAAC;AAEvE,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,KAAK,IAAI,QAMzF;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAYxD;AAED,iDAAiD;AACjD,eAAO,MAAM,UAAU,4rBAWtB,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,QAAQ,4XAUpB,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,WAAW,4rBAoBvB,CAAC"}
+{"version":3,"file":"shaderLayers.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/shaderLayers.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEhD,MAAM,WAAW,WAAW;IACxB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC7C,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gGAAgG;IAChG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kGAAkG;IAClG,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAmCD,+FAA+F;AAC/F,eAAO,MAAM,QAAQ,GAAI,KAAK,QAAQ,KAAG,OAEmE,CAAC;AAO7G;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAOhH;AA6BD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCvE;AAsED,0FAA0F;AAC1F,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,iBAAiB,GAAG,uBAAuB,CAAC,CAKnG;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAM5D;AAED,mDAAmD;AACnD,eAAO,MAAM,SAAS,GAAI,KAAK,QAAQ,KAAG,OACiC,CAAC;AAE5E,eAAO,MAAM,QAAQ,GAAI,KAAK,QAAQ,EAAE,KAAK,MAAM,KAAG,OACgB,CAAC;AAEvE,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,KAAK,IAAI,QAMzF;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAYxD;AAED,iDAAiD;AACjD,eAAO,MAAM,UAAU,4rBAWtB,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,QAAQ,4XAUpB,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,WAAW,4rBAoBvB,CAAC"}

package/dist/operations/catalogue/shaderLayers.js

@@ -176,6 +176,29 @@ export async function commitPendingLayers(root) {
         setTimeout(() => clones.forEach(c => c.dispose()), 1500);
     }
 }
+/**
+ * Instanced meshes (object layouts — InstancedLayout) share the master's material, so
+ * one layer reaches every copy. Layer GLSL reads the object's place with
+ * `modelMatrix * vec4(transformed, 1.0)`, which on an InstancedMesh is the
+ * layout root, not the copy: every copy would see the effect in the master's frame
+ * (a sweep running on all of them at once instead of across the layout). In the
+ * layer's vertex code `modelMatrix` / `modelViewMatrix` therefore become the
+ * per-instance matrices under USE_INSTANCING (and stay as they are otherwise).
+ */
+const FX_INSTANCED_MATRICES = /* glsl */ `
+#ifndef FX_INSTANCED_MATRICES
+#define FX_INSTANCED_MATRICES
+#ifdef USE_INSTANCING
+#define FX_MODEL_MATRIX (modelMatrix * instanceMatrix)
+#define FX_MODEL_VIEW_MATRIX (modelViewMatrix * instanceMatrix)
+#else
+#define FX_MODEL_MATRIX modelMatrix
+#define FX_MODEL_VIEW_MATRIX modelViewMatrix
+#endif
+#endif`;
+const instanced = (glsl) => (glsl ?? '')
+    .replace(/\bmodelMatrix\b(?!\s*\*\s*instanceMatrix)/g, 'FX_MODEL_MATRIX')
+    .replace(/\bmodelViewMatrix\b(?!\s*\*\s*instanceMatrix)/g, 'FX_MODEL_VIEW_MATRIX');
 function commitLayer(mat, key, layer) {
     if (!canLayer(mat))
         return false;
@@ -196,9 +219,9 @@ function commitLayer(mat, key, layer) {
             for (const l of own.layers.values()) {
                 const decl = Object.keys(l.uniforms).map(n => uniformDecl(n, l.uniforms[n].value)).join('\n');
                 shader.vertexShader = shader.vertexShader
-                    .replace('#include <common>', `#include <common>\n${decl}\n${l.common ?? ''}\n${l.vertexPars ?? ''}`)
-                    .replace(N_ANCHOR, `${N_ANCHOR}\n${l.normal ?? ''}`)
-                    .replace(V_ANCHOR, `${V_ANCHOR}\n${l.vertex ?? ''}`);
+                    .replace('#include <common>', `#include <common>\n${FX_INSTANCED_MATRICES}\n${decl}\n${l.common ?? ''}\n${instanced(l.vertexPars)}`)
+                    .replace(N_ANCHOR, `${N_ANCHOR}\n${instanced(l.normal)}`)
+                    .replace(V_ANCHOR, `${V_ANCHOR}\n${instanced(l.vertex)}`);
                 shader.fragmentShader = shader.fragmentShader
                     .replace('#include <common>', `#include <common>\n${decl}\n${l.common ?? ''}\n${l.fragmentPars ?? ''}`)
                     .replace(D_ANCHOR, `${D_ANCHOR}\n${l.diffuse ?? ''}`)

package/dist/render/renderLive.d.ts

@@ -0,0 +1,11 @@
+import type { RenderEffectKey } from '@3driseai/3drise-core';
+type Any = any;
+/** RenderEffects: an effect instance mounted (or null when it unmounts). */
+export declare function registerRenderEffect(slot: RenderEffectKey | 'gradingHue', instance: Any | null): void;
+/** The canvas's renderer and scene (exposure, HDR intensity / rotation). */
+export declare function registerRenderTargets(renderer: Any, s: Any): void;
+/** Every path the `render` target writes live. */
+export declare const RENDER_LIVE_PATHS: readonly ["exposure", "ssao.intensity", "ssao.radius", "bloom.intensity", "bloom.threshold", "grading.brightness", "grading.contrast", "grading.saturation", "grading.hue", "dof.focusDistance", "dof.bokehScale", "vignette.offset", "vignette.darkness", "hdr.intensity", "hdr.rotation", "hdr.backgroundIntensity", "hdr.backgroundBlur"];
+export declare function applyRenderValue(path: string, value: unknown): boolean;
+export {};
+//# sourceMappingURL=renderLive.d.ts.map

package/dist/render/renderLive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderLive.d.ts","sourceRoot":"","sources":["../../src/render/renderLive.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,KAAK,GAAG,GAAG,GAAG,CAAC;AAMf,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,eAAe,GAAG,YAAY,EAAE,QAAQ,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,CAGrG;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,IAAI,CAGjE;AAID,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,8UAQpB,CAAC;AAEX,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CA2BtE"}

package/dist/render/renderLive.js

@@ -0,0 +1,57 @@
+const effects = new Map();
+let gl = null;
+let scene = null;
+/** RenderEffects: an effect instance mounted (or null when it unmounts). */
+export function registerRenderEffect(slot, instance) {
+    if (instance)
+        effects.set(slot, instance);
+    else
+        effects.delete(slot);
+}
+/** The canvas's renderer and scene (exposure, HDR intensity / rotation). */
+export function registerRenderTargets(renderer, s) {
+    gl = renderer;
+    scene = s;
+}
+const set = (o, k, v) => { if (!o)
+    return false; o[k] = v; return true; };
+/** Every path the `render` target writes live. */
+export const RENDER_LIVE_PATHS = [
+    'exposure',
+    'ssao.intensity', 'ssao.radius',
+    'bloom.intensity', 'bloom.threshold',
+    'grading.brightness', 'grading.contrast', 'grading.saturation', 'grading.hue',
+    'dof.focusDistance', 'dof.bokehScale',
+    'vignette.offset', 'vignette.darkness',
+    'hdr.intensity', 'hdr.rotation', 'hdr.backgroundIntensity', 'hdr.backgroundBlur',
+];
+export function applyRenderValue(path, value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return false;
+    switch (path) {
+        case 'exposure': return set(gl, 'toneMappingExposure', value);
+        case 'ssao.intensity': return set(effects.get('ssao'), 'intensity', value);
+        case 'ssao.radius': return set(effects.get('ssao'), 'radius', value);
+        case 'bloom.intensity': return set(effects.get('bloom'), 'intensity', value);
+        case 'bloom.threshold': return set(effects.get('bloom')?.luminanceMaterial, 'threshold', value);
+        case 'grading.brightness': return set(effects.get('grading'), 'brightness', value);
+        case 'grading.contrast': return set(effects.get('grading'), 'contrast', value);
+        case 'grading.saturation': return set(effects.get('gradingHue'), 'saturation', value);
+        case 'grading.hue': return set(effects.get('gradingHue'), 'hue', value);
+        case 'dof.focusDistance': return set(effects.get('dof')?.cocMaterial, 'focusDistance', value);
+        case 'dof.bokehScale': return set(effects.get('dof'), 'bokehScale', value);
+        case 'vignette.offset': return set(effects.get('vignette'), 'offset', value);
+        case 'vignette.darkness': return set(effects.get('vignette'), 'darkness', value);
+        case 'hdr.intensity': return set(scene, 'environmentIntensity', value);
+        case 'hdr.rotation': {
+            if (!scene)
+                return false;
+            scene.environmentRotation?.set?.(0, value, 0);
+            scene.backgroundRotation?.set?.(0, value, 0);
+            return true;
+        }
+        case 'hdr.backgroundIntensity': return set(scene, 'backgroundIntensity', value);
+        case 'hdr.backgroundBlur': return set(scene, 'backgroundBlurriness', value);
+        default: return false;
+    }
+}

package/dist/shaders/glsl/oceanCore.glsl.d.ts

@@ -42,9 +42,9 @@
 /** Hard cap on the wave table. The loop is bounded by it because GLSL ES 1.00
  *  requires a constant bound; `u_waveCount` breaks out early. */
 export declare const MAX_WAVES = 32;
-export declare const oceanUniforms = "\n#define MAX_WAVES 32\n\n// Per component: (dirX, dirZ, amplitude, wavenumber k).\nuniform vec4  u_waveA[MAX_WAVES];\n// Per component: (angular frequency w, phase, steepness Q, wavelength).\nuniform vec4  u_waveB[MAX_WAVES];\nuniform float u_waveCount;\n\nuniform float u_time;\nuniform float u_waterLevel;\nuniform float u_choppiness;\nuniform float u_amplitudeScale;\n\n// Half-extent of a placed body, and the width of its rim taper. Both zero on the\n// world host, which is what switches the taper off - a sea has no rim.\nuniform vec2  u_bodyHalf;\nuniform float u_edgeFade;\n\nuniform vec3  u_deepColor;\nuniform vec3  u_shallowColor;\nuniform vec3  u_foamColor;\nuniform vec3  u_sssColor;\nuniform float u_absorption;\nuniform float u_clarity;\nuniform float u_roughness;\nuniform float u_specular;\nuniform float u_sssStrength;\nuniform float u_detailStrength;\nuniform float u_detailScale;      // 1 / detailSize\nuniform float u_detailFade;       // 1 / detailFadeDistance\n// World size of one pixel at one unit of distance: 2*tan(fov/2) / viewportHeight.\n// What turns a distance into a screen-space footprint, which is the only thing\n// that decides whether a ripple is a shape or a shimmer.\nuniform float u_pixelScale;\nuniform float u_foamAmount;\nuniform float u_foamDecay;\nuniform float u_foamScale;        // 1 / foamSize\nuniform float u_ambientScale;\nuniform float u_fogDensity;\nuniform float u_exposure;\nuniform float u_curvature;\nuniform float u_receiveShadows;\n\n// Filled by applySunUniforms and applyTerrainAmbient, exactly as on the terrain\n// material - one atmosphere for the sky, the clouds, the ground and the water.\nuniform vec3  u_skyAmbient;\nuniform vec3  u_groundAmbient;\n\n// Moonlight (useOceanMaterial, from the same moon as the key light and the\n// moon disc). u_moonColor already carries strength: black by day, so the moon\n// terms below cost two dot products and add nothing.\nuniform vec3  u_moonDir;\nuniform vec3  u_moonColor;\n";
+export declare const oceanUniforms = "\n#define MAX_WAVES 32\n\n// Per component: (dirX, dirZ, amplitude, wavenumber k).\nuniform vec4  u_waveA[MAX_WAVES];\n// Per component: (angular frequency w, phase, steepness Q, wavelength).\nuniform vec4  u_waveB[MAX_WAVES];\nuniform float u_waveCount;\n\nuniform float u_time;\n// The current (config flowSpeed / flowDirection). Offsets are the distance the\n// water has carried the field so far, integrated on the CPU (offset += v * dt),\n// never speed * time: animating the speed must not make the pattern jump.\n// u_flowOffset is in the field's own frame (a body's local metres, the world on\n// the world host); u_flowOffsetW and u_flowDirW are in world XZ for the\n// per-fragment ripple. All zero for still water.\nuniform vec2  u_flowOffset;\nuniform vec2  u_flowOffsetW;\nuniform vec2  u_flowDirW;\nuniform float u_flowStretch;\nuniform float u_waterLevel;\nuniform float u_choppiness;\nuniform float u_amplitudeScale;\n\n// Half-extent of a placed body, and the width of its rim taper. Both zero on the\n// world host, which is what switches the taper off - a sea has no rim.\nuniform vec2  u_bodyHalf;\nuniform float u_edgeFade;\n\nuniform vec3  u_deepColor;\nuniform vec3  u_shallowColor;\nuniform vec3  u_foamColor;\nuniform vec3  u_sssColor;\nuniform float u_absorption;\nuniform float u_clarity;\nuniform float u_roughness;\nuniform float u_specular;\nuniform float u_sssStrength;\nuniform float u_detailStrength;\nuniform float u_detailScale;      // 1 / detailSize\nuniform float u_detailFade;       // 1 / detailFadeDistance\n// World size of one pixel at one unit of distance: 2*tan(fov/2) / viewportHeight.\n// What turns a distance into a screen-space footprint, which is the only thing\n// that decides whether a ripple is a shape or a shimmer.\nuniform float u_pixelScale;\nuniform float u_foamAmount;\nuniform float u_foamDecay;\nuniform float u_foamScale;        // 1 / foamSize\nuniform float u_ambientScale;\nuniform float u_fogDensity;\nuniform float u_exposure;\nuniform float u_curvature;\nuniform float u_receiveShadows;\n\n// Filled by applySunUniforms and applyTerrainAmbient, exactly as on the terrain\n// material - one atmosphere for the sky, the clouds, the ground and the water.\nuniform vec3  u_skyAmbient;\n/** How bright the sky dome is drawn (skyBrightnessForSunElevation): 1 by day,\n *  0.08 at night. The analytic skyRadiance never goes dark on its own (Preetham's\n *  Rayleigh term lights a sun-less sky in full daylight blue), so every place\n *  the water reads the sky scales by this - or a pool glows blue at midnight. */\nuniform float u_skyBrightness;\nuniform vec3  u_groundAmbient;\n\n// Moonlight (useOceanMaterial, from the same moon as the key light and the\n// moon disc). u_moonColor already carries strength: black by day, so the moon\n// terms below cost two dot products and add nothing.\nuniform vec3  u_moonDir;\nuniform vec3  u_moonColor;\n";
 export declare const oceanWaves = "\n/**\n * One trochoidal component, accumulated.\n *\n * Gerstner displaces along the direction of travel as well as vertically:\n *\n *   x' = x + d * Q * A * sin(theta)\n *   y  =     A * cos(theta)\n *   theta = k * dot(d, x) + w * t + phase\n *\n * Q is what peaks the crests and flattens the troughs. It also compresses the\n * horizontal map near a crest, and where that compression turns the map\n * degenerate the wave is breaking - which is where the foam is. That falls out\n * of the same derivatives, for free, so foam here is measured rather than faked.\n *\n * Everything is differentiated in closed form. A central difference would need\n * four more evaluations of the whole sum for the normal alone; this is the same\n * decision, and the same 13x, that the terrain height field made.\n */\nvoid oceanWaveSum(\n  vec2 p, float cellLod, float amp,\n  out vec3 disp,        // displacement from the flat plane, world units\n  out vec3 nrm,         // analytic surface normal\n  out float jacobian,   // det of the horizontal map. < 1 compresses, < 0 folds\n  out float relHeight   // vertical displacement in standard deviations of the surface\n){\n  disp = vec3(0.0);\n  jacobian = 0.0;\n  relHeight = 0.0;\n\n  // Horizontal derivatives of the horizontal displacement, and of the height.\n  float dXdx = 0.0, dXdz = 0.0, dZdx = 0.0, dZdz = 0.0;\n  float dYdx = 0.0, dYdz = 0.0;\n  float totalSq = 0.0;\n\n  for (int i = 0; i < MAX_WAVES; i++) {\n    if (float(i) >= u_waveCount) break;\n\n    vec4 a = u_waveA[i];\n    vec4 b = u_waveB[i];\n    vec2 d = a.xy;\n    float A = a.z * amp;\n    float k = a.w;\n    float w = b.x;\n    float phase = b.y;\n    float Q = b.z;\n    float wl = b.w;\n\n    // Per-ring wave LOD. A component of wavelength L cannot be represented on a\n    // cell coarser than about L/4 - sampled there it aliases into crawling\n    // noise, which is what a naive clipmap ocean looks like at the horizon. So\n    // it fades out as the cell approaches its wavelength.\n    //\n    // cellLod is aCell * (1 + aMorph), the same morphing LOD the terrain uses,\n    // which is what makes the two sides of a ring seam agree: the outer edge of\n    // ring l evaluates at exactly ring l+1's cell size, so both sides fade the\n    // same components by the same amount and the surface is continuous across\n    // the boundary.\n    float lod = 1.0 - smoothstep(wl * 0.25, wl * 0.75, cellLod);\n    A *= lod;\n\n    float theta = k * dot(d, p) + w * u_time + phase;\n    float S = sin(theta);\n    float C = cos(theta);\n\n    float QA = Q * A;\n\n    disp.x += d.x * QA * S;\n    disp.z += d.y * QA * S;\n    disp.y += A * C;\n    totalSq += A * A;\n\n    float kQA = k * QA;\n    dXdx += d.x * d.x * kQA * C;\n    dXdz += d.x * d.y * kQA * C;\n    dZdx += d.y * d.x * kQA * C;\n    dZdz += d.y * d.y * kQA * C;\n\n    float kA = k * A;\n    dYdx -= d.x * kA * S;\n    dYdz -= d.y * kA * S;\n  }\n\n  // Tangent frame of the displaced surface. Taking the cross product rather than\n  // the usual closed-form shortcut costs three multiplies and stays correct when\n  // choppiness is high, where the shortcut - which assumes the horizontal map is\n  // near-identity - visibly tilts the crests the wrong way.\n  vec3 tx = vec3(1.0 + dXdx, dYdx, dZdx);\n  vec3 tz = vec3(dXdz, dYdz, 1.0 + dZdz);\n  nrm = normalize(cross(tz, tx));\n\n  jacobian = (1.0 + dXdx) * (1.0 + dZdz) - dXdz * dZdx;\n\n  // Height in standard deviations of the surface, NOT as a fraction of the\n  // summed amplitudes. Dividing by the sum is the obvious thing and it is wrong\n  // by a factor of sqrt(2N): random-phase components almost never align, so the\n  // surface only ever reaches a fraction of that sum, and everything keyed on\n  // relative height - the foam's crest gate, the subsurface term - was being\n  // multiplied by ~0.15 and silently doing nothing. A storm with whitecaps\n  // turned up had no foam at all, which is how this was found.\n  //\n  // sigma is the RMS surface elevation, so this is roughly -3..3 with the usual\n  // excursion at +-1, and a threshold expressed in it means what it looks like.\n  relHeight = disp.y / max(sqrt(totalSq * 0.5), 1e-4);\n}\n\n/** Rim taper for a placed body: displacement to zero at the edge, so the\n *  boundary is still water rather than a sawn-off cliff of it. Returns 1 on the\n *  world host, where u_bodyHalf is zero. */\nfloat oceanEdgeMask(vec2 local){\n  if (u_bodyHalf.x <= 0.0) return 1.0;\n  vec2 t = abs(local) / max(u_bodyHalf, vec2(1e-3));\n  float e = max(t.x, t.y);\n  float band = max(u_edgeFade, 1e-3);\n  return 1.0 - smoothstep(1.0 - band, 1.0, e);\n}\n";
-export declare const oceanShade = "\n/** Arithmetic hash. Never the fract(sin(dot())) one: four hashes per octave of\n *  two sines each was most of the terrain frame budget before it was replaced,\n *  and every noise tutorial online still teaches the expensive version. */\nvec2 oHash(vec2 p){\n  vec3 p3 = fract(vec3(p.xyx) * vec3(0.1031, 0.1030, 0.0973));\n  p3 += dot(p3, p3.yzx + 33.33);\n  return fract((p3.xx + p3.yz) * p3.zy) * 2.0 - 1.0;\n}\n\n/** Gradient noise with its derivative, so a detail normal costs one evaluation\n *  instead of three. */\nvec3 oNoised(vec2 x){\n  vec2 i = floor(x);\n  vec2 f = fract(x);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  vec2 du = 6.0 * f * (1.0 - f);\n\n  vec2 ga = oHash(i + vec2(0.0, 0.0));\n  vec2 gb = oHash(i + vec2(1.0, 0.0));\n  vec2 gc = oHash(i + vec2(0.0, 1.0));\n  vec2 gd = oHash(i + vec2(1.0, 1.0));\n\n  float va = dot(ga, f - vec2(0.0, 0.0));\n  float vb = dot(gb, f - vec2(1.0, 0.0));\n  float vc = dot(gc, f - vec2(0.0, 1.0));\n  float vd = dot(gd, f - vec2(1.0, 1.0));\n\n  float v = va + u.x * (vb - va) + u.y * (vc - va) + u.x * u.y * (va - vb - vc + vd);\n  vec2 g = ga + u.x * (gb - ga) + u.y * (gc - ga) + u.x * u.y * (ga - gb - gc + gd)\n         + du * (u.yx * (va - vb - vc + vd) + vec2(vb, vc) - va);\n  return vec3(v, g);\n}\n\n/**\n * Ripple below the mesh.\n *\n * This is not decoration: the per-ring LOD in oceanWaveSum deletes every\n * component shorter than the cell, and near the camera that is most of the\n * high-frequency energy in the sea. Putting it back as a normal perturbation is\n * cheaper than carrying it in geometry and, past a few metres, indistinguishable\n * - a ripple two pixels across is a normal, not a shape.\n *\n * Two octaves drifting in opposite directions, because one drifting field reads\n * as a texture being dragged across the water.\n */\nfloat oceanDetailFade(float dist){\n  // Two fades, and the second is the one that matters. Distance alone is not\n  // what makes a ripple alias - a screen-space footprint is. A two-metre ripple\n  // is a shape at fifty metres and sub-pixel noise at two thousand, and which of\n  // those it is depends on the field of view and the resolution, not on the\n  // distance. Fading on the footprint means the same water looks right in a\n  // wide shot and a telephoto one.\n  float footprint = dist * u_pixelScale;\n  float size = 1.0 / max(u_detailScale, 1e-4);\n  float screen = 1.0 - smoothstep(size * 0.35, size * 1.4, footprint);\n  return exp(-dist * u_detailFade) * screen;\n}\n\nvec3 oceanDetailNormal(vec3 n, vec3 wp, float fade){\n  float amt = u_detailStrength * fade;\n  if (amt <= 0.001) return n;\n\n  vec2 p = wp.xz * u_detailScale;\n  vec2 drift = vec2(u_time * 0.06, u_time * 0.043);\n\n  vec3 a = oNoised(p + drift);\n  vec3 b = oNoised(p * 2.17 - drift * 1.6);\n  vec2 g = a.yz + b.yz * 0.5;\n\n  // Perturb in the surface plane, so a steep wave face keeps its own orientation\n  // and only gains texture.\n  vec3 t = normalize(cross(vec3(0.0, 1.0, 0.0), n) + vec3(1e-5, 0.0, 0.0));\n  vec3 bt = cross(n, t);\n  // 0.12, not 0.4. The gradient of the noise is order 1, so the constant IS the\n  // maximum slope the ripple adds: at 0.4 the default strength tilts the normal\n  // by twelve degrees, and at grazing angles - which is most of an ocean - a\n  // twelve degree tilt swings the Fresnel term between reflecting the sky and\n  // not. The whole surface then boils with white speckle, which is exactly what\n  // it did. Sub-metre ripple on open water is a few degrees of slope.\n  return normalize(n - (t * g.x + bt * g.y) * amt * 0.12);\n}\n\n/**\n * Whitecaps, from the Jacobian of the horizontal map.\n *\n * Where the determinant falls toward zero the surface is folding into itself,\n * which is physically what a breaking crest is. It is the same quantity an FFT\n * ocean reads off its displacement cascade, and a Gerstner sum hands it over for\n * nothing, so foam is measured here rather than paint over the crests.\n *\n * u_foamDecay is a stand-in for a real accumulation buffer: it widens the\n * threshold on the trailing side, so foam persists behind the crest instead of\n * flickering on and off with it. The honest version writes into a persistent\n * target and advects it - deferred with the FFT phase.\n */\nfloat oceanFoam(float jacobian, float relHeight, vec3 wp){\n  float compress = saturate(1.0 - jacobian);\n\n  // Thresholds are calibrated against the compression the wave table actually\n  // produces, which is a much narrower range than it looks: at the defaults the\n  // Jacobian sits just above zero at the sharpest crest and near 1 everywhere\n  // else. A threshold picked by eye either foams the whole sea or none of it.\n  float thr = mix(0.85, 0.15, saturate(u_foamAmount * 0.6));\n  float sharp = smoothstep(thr, thr + 0.15, compress);\n  float trail = smoothstep(thr * 0.55, thr + 0.4, compress);\n  float f = mix(sharp, max(sharp, trail), saturate(u_foamDecay));\n\n  // Foam belongs on and just behind the crest, never in the trough.\n  f *= smoothstep(-0.15, 0.45, relHeight);\n\n  // Break it up, or it reads as a decal following the wave.\n  vec2 q = wp.xz * u_foamScale;\n  float n = oNoised(q + vec2(u_time * 0.05, -u_time * 0.03)).x * 0.5 + 0.5;\n  n = mix(n, 1.0, 0.35);\n  return saturate(f * n * u_foamAmount);\n}\n\n/**\n * The water shading.\n *\n * Reflection is the whole story above a few degrees of grazing - most of what\n * you see looking at the sea is the sky - so the Fresnel split, the sky radiance\n * and the aerial perspective all have to come from the same atmosphere the sky\n * itself is drawn with, or the water is obviously pasted onto the scene. That is\n * skyRadiance from cloudCore, driven by applySunUniforms off the same\n * useCloudSun state as the clouds and the terrain.\n */\nvec3 oceanLight(\n  vec3 wp, vec3 n, vec3 viewDir,   // viewDir points FROM the camera TO the surface\n  float foam, float relHeight, float shadow, float depthFactor,\n  float roughnessBoost,            // specular antialiasing, see the caller\n  vec3 reflectionColor\n){\n  vec3 V = -viewDir;\n  vec3 L = normalize(u_sunDir);\n  float NdotL = max(dot(n, L), 0.0);\n  vec3 sun = u_sunColor * u_sunIntensity * shadow;\n\n  // Reflection. Bending the reflected ray back above the horizon is a cheat, and\n  // the alternative is worse: at grazing angles a wave face routinely reflects\n  // just below the horizon, and sampling the sky's ground term there puts a band\n  // of dirt across the brightest part of the water.\n  vec3 R = reflect(viewDir, n);\n  R.y = max(R.y, 0.015);\n  vec3 sky = length(reflectionColor) > 0.0 ? reflectionColor : skyRadiance(R);\n\n  // Prefilter the reflection by the same roughness the specular lobe uses.\n  // Without this the specular is filtered and the reflection is not, and on\n  // water that is the wrong half: reflection is most of what you see, and a\n  // mirror sampled through a noisy normal aliases exactly as hard as a highlight\n  // does. u_skyAmbient is already the hemispheric average of this sky, so it is\n  // the infinitely-rough end of the same lobe and costs nothing to mix toward.\n  float rough = clamp(u_roughness + roughnessBoost, 0.01, 1.0);\n  sky = mix(sky, u_skyAmbient * 0.6, saturate(rough * 2.2));\n\n  float fres = 0.02 + 0.98 * pow(1.0 - saturate(dot(V, n)), 5.0);\n\n  // Body colour. depthFactor is 1 in open water and ramps to 0 as the bottom\n  // comes up; until the refraction grab exists it is 1 everywhere.\n  vec3 body = mix(u_shallowColor, u_deepColor, saturate(depthFactor));\n  body = mix(body, u_shallowColor, u_clarity * 0.35);\n  vec3 bodyLit = body * (u_skyAmbient * u_ambientScale * 0.22 + sun * (0.25 + 0.55 * NdotL));\n\n  // Subsurface. A wave lit from behind glows through its own crest, and the\n  // effect is strongest where the surface is steep and thin - so it keys off the\n  // wave's own height rather than off thickness we do not have.\n  float back = pow(saturate(dot(V, -L) * 0.5 + 0.5), 3.0);\n  float thin = saturate(relHeight * 1.4);\n  vec3 sss = u_sssColor * u_sssStrength * back * thin * u_sunColor * u_sunIntensity * (0.35 + 0.65 * shadow);\n\n  // GGX. The glitter path from the horizon to the camera is most of what says\n  // \"water\" at distance, and it is a specular lobe on a normal that is moving -\n  // which is why the detail normal matters as much as the mesh does.\n  // Water is nearly smooth, which is exactly what makes it alias: a specular\n  // lobe this tight flips between nothing and a blown-out highlight across one\n  // pixel, and a sea of them boils. The fix is not a softer sea - it is to widen\n  // the lobe by however much the normal varies inside the pixel, so the energy\n  // is kept and the flicker is not. roughnessBoost carries that in, and the\n  // reflection above is filtered by the same number.\n  float a = max(rough * rough, 2e-4);\n  vec3 h = normalize(L + V);\n  float ndh = max(dot(n, h), 0.0);\n  float denom = ndh * ndh * (a * a - 1.0) + 1.0;\n  float ggx = (a * a) / (PI * denom * denom);\n  vec3 spec = sun * ggx * u_specular * fres;\n\n  // The moon: its own glitter path down the water toward the camera, and a\n  // little light on the body. Same lobe, same filtering, so the path breaks up\n  // on the waves exactly as the sun's does. Below the horizon u_moonColor is 0.\n  vec3 Lm = normalize(u_moonDir);\n  vec3 hm = normalize(Lm + V);\n  float ndhm = max(dot(n, hm), 0.0);\n  float denomM = ndhm * ndhm * (a * a - 1.0) + 1.0;\n  float ggxM = (a * a) / (PI * denomM * denomM);\n  spec += u_moonColor * ggxM * u_specular * fres;\n  bodyLit += body * u_moonColor * (0.25 + 0.55 * max(dot(n, Lm), 0.0));\n\n  vec3 col = mix(bodyLit + sss, sky, fres) + spec;\n\n  // Foam is a rough dielectric, so it takes the sky and the sun diffusely and\n  // kills the reflection under it.\n  vec3 foamLit = u_foamColor * (u_skyAmbient * u_ambientScale * 0.5 + sun * (0.3 + 0.7 * NdotL));\n  col = mix(col, foamLit, saturate(foam));\n\n  return col;\n}\n\n/** Fade into the sky the water is seen through. Same term as the terrain's,\n *  and it needs to be stronger here: an ocean runs to the horizon in every\n *  direction, so it is the only thing stopping the far field reading as a\n *  painted plane. */\nvec3 oceanAerial(vec3 col, vec3 rd, float dist){\n  float f = 1.0 - exp(-u_fogDensity * dist);\n  if (f < 0.002) return col;\n  return mix(col, skyRadiance(rd), f);\n}\n";
+export declare const oceanShade = "\n/** Arithmetic hash. Never the fract(sin(dot())) one: four hashes per octave of\n *  two sines each was most of the terrain frame budget before it was replaced,\n *  and every noise tutorial online still teaches the expensive version. */\nvec2 oHash(vec2 p){\n  vec3 p3 = fract(vec3(p.xyx) * vec3(0.1031, 0.1030, 0.0973));\n  p3 += dot(p3, p3.yzx + 33.33);\n  return fract((p3.xx + p3.yz) * p3.zy) * 2.0 - 1.0;\n}\n\n/** Gradient noise with its derivative, so a detail normal costs one evaluation\n *  instead of three. */\nvec3 oNoised(vec2 x){\n  vec2 i = floor(x);\n  vec2 f = fract(x);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  vec2 du = 6.0 * f * (1.0 - f);\n\n  vec2 ga = oHash(i + vec2(0.0, 0.0));\n  vec2 gb = oHash(i + vec2(1.0, 0.0));\n  vec2 gc = oHash(i + vec2(0.0, 1.0));\n  vec2 gd = oHash(i + vec2(1.0, 1.0));\n\n  float va = dot(ga, f - vec2(0.0, 0.0));\n  float vb = dot(gb, f - vec2(1.0, 0.0));\n  float vc = dot(gc, f - vec2(0.0, 1.0));\n  float vd = dot(gd, f - vec2(1.0, 1.0));\n\n  float v = va + u.x * (vb - va) + u.y * (vc - va) + u.x * u.y * (va - vb - vc + vd);\n  vec2 g = ga + u.x * (gb - ga) + u.y * (gc - ga) + u.x * u.y * (ga - gb - gc + gd)\n         + du * (u.yx * (va - vb - vc + vd) + vec2(vb, vc) - va);\n  return vec3(v, g);\n}\n\n/**\n * Ripple below the mesh.\n *\n * This is not decoration: the per-ring LOD in oceanWaveSum deletes every\n * component shorter than the cell, and near the camera that is most of the\n * high-frequency energy in the sea. Putting it back as a normal perturbation is\n * cheaper than carrying it in geometry and, past a few metres, indistinguishable\n * - a ripple two pixels across is a normal, not a shape.\n *\n * Two octaves drifting in opposite directions, because one drifting field reads\n * as a texture being dragged across the water.\n */\nfloat oceanDetailFade(float dist){\n  // Two fades, and the second is the one that matters. Distance alone is not\n  // what makes a ripple alias - a screen-space footprint is. A two-metre ripple\n  // is a shape at fifty metres and sub-pixel noise at two thousand, and which of\n  // those it is depends on the field of view and the resolution, not on the\n  // distance. Fading on the footprint means the same water looks right in a\n  // wide shot and a telephoto one.\n  float footprint = dist * u_pixelScale;\n  float size = 1.0 / max(u_detailScale, 1e-4);\n  float screen = 1.0 - smoothstep(size * 0.35, size * 1.4, footprint);\n  return exp(-dist * u_detailFade) * screen;\n}\n\nvec3 oceanDetailNormal(vec3 n, vec3 wp, float fade){\n  float amt = u_detailStrength * fade;\n  if (amt <= 0.001) return n;\n\n  // Running water: the ripple is carried downstream with the current and\n  // stretched along it, into the streaks that say \"flowing\" rather than\n  // \"wind-blown\". Sampled in the flow's frame (along, across) with the along axis\n  // compressed; the gradient is mapped back with the transpose (chain rule), so\n  // the perturbation stays in world XZ. Still water skips it (uniform branch).\n  vec2 xz = wp.xz - u_flowOffsetW;\n  float along = 1.0 / (1.0 + u_flowStretch);\n  vec2 fd = u_flowDirW;\n  vec2 fn = vec2(-fd.y, fd.x);\n  bool flowing = u_flowStretch > 0.0;\n  vec2 q = flowing ? vec2(dot(xz, fd) * along, dot(xz, fn)) : xz;\n\n  vec2 p = q * u_detailScale;\n  vec2 drift = vec2(u_time * 0.06, u_time * 0.043);\n\n  vec3 a = oNoised(p + drift);\n  vec3 b = oNoised(p * 2.17 - drift * 1.6);\n  vec2 g = a.yz + b.yz * 0.5;\n  if (flowing) g = fd * (g.x * along) + fn * g.y;\n\n  // Perturb in the surface plane, so a steep wave face keeps its own orientation\n  // and only gains texture.\n  vec3 t = normalize(cross(vec3(0.0, 1.0, 0.0), n) + vec3(1e-5, 0.0, 0.0));\n  vec3 bt = cross(n, t);\n  // 0.12, not 0.4. The gradient of the noise is order 1, so the constant IS the\n  // maximum slope the ripple adds: at 0.4 the default strength tilts the normal\n  // by twelve degrees, and at grazing angles - which is most of an ocean - a\n  // twelve degree tilt swings the Fresnel term between reflecting the sky and\n  // not. The whole surface then boils with white speckle, which is exactly what\n  // it did. Sub-metre ripple on open water is a few degrees of slope.\n  return normalize(n - (t * g.x + bt * g.y) * amt * 0.12);\n}\n\n/**\n * Whitecaps, from the Jacobian of the horizontal map.\n *\n * Where the determinant falls toward zero the surface is folding into itself,\n * which is physically what a breaking crest is. It is the same quantity an FFT\n * ocean reads off its displacement cascade, and a Gerstner sum hands it over for\n * nothing, so foam is measured here rather than paint over the crests.\n *\n * u_foamDecay is a stand-in for a real accumulation buffer: it widens the\n * threshold on the trailing side, so foam persists behind the crest instead of\n * flickering on and off with it. The honest version writes into a persistent\n * target and advects it - deferred with the FFT phase.\n */\nfloat oceanFoam(float jacobian, float relHeight, vec3 wp){\n  float compress = saturate(1.0 - jacobian);\n\n  // Thresholds are calibrated against the compression the wave table actually\n  // produces, which is a much narrower range than it looks: at the defaults the\n  // Jacobian sits just above zero at the sharpest crest and near 1 everywhere\n  // else. A threshold picked by eye either foams the whole sea or none of it.\n  float thr = mix(0.85, 0.15, saturate(u_foamAmount * 0.6));\n  float sharp = smoothstep(thr, thr + 0.15, compress);\n  float trail = smoothstep(thr * 0.55, thr + 0.4, compress);\n  float f = mix(sharp, max(sharp, trail), saturate(u_foamDecay));\n\n  // Foam belongs on and just behind the crest, never in the trough.\n  f *= smoothstep(-0.15, 0.45, relHeight);\n\n  // Break it up, or it reads as a decal following the wave.\n  vec2 q = wp.xz * u_foamScale;\n  float n = oNoised(q + vec2(u_time * 0.05, -u_time * 0.03)).x * 0.5 + 0.5;\n  n = mix(n, 1.0, 0.35);\n  return saturate(f * n * u_foamAmount);\n}\n\n/**\n * The water shading.\n *\n * Reflection is the whole story above a few degrees of grazing - most of what\n * you see looking at the sea is the sky - so the Fresnel split, the sky radiance\n * and the aerial perspective all have to come from the same atmosphere the sky\n * itself is drawn with, or the water is obviously pasted onto the scene. That is\n * skyRadiance from cloudCore, driven by applySunUniforms off the same\n * useCloudSun state as the clouds and the terrain.\n */\nvec3 oceanLight(\n  vec3 wp, vec3 n, vec3 viewDir,   // viewDir points FROM the camera TO the surface\n  float foam, float relHeight, float shadow, float depthFactor,\n  float roughnessBoost,            // specular antialiasing, see the caller\n  vec3 reflectionColor             // 0: the sky; negative: no reflection (off)\n){\n  vec3 V = -viewDir;\n  vec3 L = normalize(u_sunDir);\n  float NdotL = max(dot(n, L), 0.0);\n  vec3 sun = u_sunColor * u_sunIntensity * shadow;\n\n  // Reflection. Bending the reflected ray back above the horizon is a cheat, and\n  // the alternative is worse: at grazing angles a wave face routinely reflects\n  // just below the horizon, and sampling the sky's ground term there puts a band\n  // of dirt across the brightest part of the water.\n  vec3 R = reflect(viewDir, n);\n  R.y = max(R.y, 0.015);\n  vec3 sky = length(reflectionColor) > 0.0 ? reflectionColor : skyRadiance(R) * u_skyBrightness;\n\n  // Prefilter the reflection by the same roughness the specular lobe uses.\n  // Without this the specular is filtered and the reflection is not, and on\n  // water that is the wrong half: reflection is most of what you see, and a\n  // mirror sampled through a noisy normal aliases exactly as hard as a highlight\n  // does. u_skyAmbient is already the hemispheric average of this sky, so it is\n  // the infinitely-rough end of the same lobe and costs nothing to mix toward.\n  float rough = clamp(u_roughness + roughnessBoost, 0.01, 1.0);\n  sky = mix(sky, u_skyAmbient * 0.6, saturate(rough * 2.2));\n\n  float fres = 0.02 + 0.98 * pow(1.0 - saturate(dot(V, n)), 5.0);\n\n  // Body colour. depthFactor is 1 in open water and ramps to 0 as the bottom\n  // comes up; until the refraction grab exists it is 1 everywhere.\n  vec3 body = mix(u_shallowColor, u_deepColor, saturate(depthFactor));\n  body = mix(body, u_shallowColor, u_clarity * 0.35);\n  vec3 bodyLit = body * (u_skyAmbient * u_ambientScale * 0.22 + sun * (0.25 + 0.55 * NdotL));\n\n  // Subsurface. A wave lit from behind glows through its own crest, and the\n  // effect is strongest where the surface is steep and thin - so it keys off the\n  // wave's own height rather than off thickness we do not have.\n  float back = pow(saturate(dot(V, -L) * 0.5 + 0.5), 3.0);\n  float thin = saturate(relHeight * 1.4);\n  vec3 sss = u_sssColor * u_sssStrength * back * thin * u_sunColor * u_sunIntensity * (0.35 + 0.65 * shadow);\n\n  // GGX. The glitter path from the horizon to the camera is most of what says\n  // \"water\" at distance, and it is a specular lobe on a normal that is moving -\n  // which is why the detail normal matters as much as the mesh does.\n  // Water is nearly smooth, which is exactly what makes it alias: a specular\n  // lobe this tight flips between nothing and a blown-out highlight across one\n  // pixel, and a sea of them boils. The fix is not a softer sea - it is to widen\n  // the lobe by however much the normal varies inside the pixel, so the energy\n  // is kept and the flicker is not. roughnessBoost carries that in, and the\n  // reflection above is filtered by the same number.\n  float a = max(rough * rough, 2e-4);\n  vec3 h = normalize(L + V);\n  float ndh = max(dot(n, h), 0.0);\n  float denom = ndh * ndh * (a * a - 1.0) + 1.0;\n  float ggx = (a * a) / (PI * denom * denom);\n  vec3 spec = sun * ggx * u_specular * fres;\n\n  // The moon: its own glitter path down the water toward the camera, and a\n  // little light on the body. Same lobe, same filtering, so the path breaks up\n  // on the waves exactly as the sun's does. Below the horizon u_moonColor is 0.\n  vec3 Lm = normalize(u_moonDir);\n  vec3 hm = normalize(Lm + V);\n  float ndhm = max(dot(n, hm), 0.0);\n  float denomM = ndhm * ndhm * (a * a - 1.0) + 1.0;\n  float ggxM = (a * a) / (PI * denomM * denomM);\n  spec += u_moonColor * ggxM * u_specular * fres;\n  bodyLit += body * u_moonColor * (0.25 + 0.55 * max(dot(n, Lm), 0.0));\n\n  // Reflection off: the water shows only its own colour (and the sun's glint),\n  // never the sky \u2014 not even the roughness fill above.\n  vec3 col = (reflectionColor.x < 0.0 ? bodyLit + sss : mix(bodyLit + sss, sky, fres)) + spec;\n\n  // Foam is a rough dielectric, so it takes the sky and the sun diffusely and\n  // kills the reflection under it.\n  vec3 foamLit = u_foamColor * (u_skyAmbient * u_ambientScale * 0.5 + sun * (0.3 + 0.7 * NdotL));\n  col = mix(col, foamLit, saturate(foam));\n\n  return col;\n}\n\n/** Fade into the sky the water is seen through. Same term as the terrain's,\n *  and it needs to be stronger here: an ocean runs to the horizon in every\n *  direction, so it is the only thing stopping the far field reading as a\n *  painted plane. */\nvec3 oceanAerial(vec3 col, vec3 rd, float dist){\n  float f = 1.0 - exp(-u_fogDensity * dist);\n  if (f < 0.002) return col;\n  return mix(col, skyRadiance(rd) * u_skyBrightness, f);\n}\n";
 /** Height field only — what a vertex stage needs. */
 export declare const oceanField: string;
 /** The whole model. */

package/dist/shaders/glsl/oceanCore.glsl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oceanCore.glsl.d.ts","sourceRoot":"","sources":["../../../src/shaders/glsl/oceanCore.glsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;iEACiE;AACjE,eAAO,MAAM,SAAS,KAAK,CAAC;AAE5B,eAAO,MAAM,aAAa,28DAsDzB,CAAC;AAEF,eAAO,MAAM,UAAU,gjJAoHtB,CAAC;AAEF,eAAO,MAAM,UAAU,ssUAyNtB,CAAC;AAEF,qDAAqD;AACrD,eAAO,MAAM,UAAU,QAAyC,CAAC;AAEjE,uBAAuB;AACvB,eAAO,MAAM,SAAS,QAAqD,CAAC"}
+{"version":3,"file":"oceanCore.glsl.d.ts","sourceRoot":"","sources":["../../../src/shaders/glsl/oceanCore.glsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;iEACiE;AACjE,eAAO,MAAM,SAAS,KAAK,CAAC;AAE5B,eAAO,MAAM,aAAa,o2FAqEzB,CAAC;AAEF,eAAO,MAAM,UAAU,gjJAoHtB,CAAC;AAEF,eAAO,MAAM,UAAU,opWAwOtB,CAAC;AAEF,qDAAqD;AACrD,eAAO,MAAM,UAAU,QAAyC,CAAC;AAEjE,uBAAuB;AACvB,eAAO,MAAM,SAAS,QAAqD,CAAC"}

package/dist/shaders/glsl/oceanCore.glsl.js

@@ -52,6 +52,16 @@ uniform vec4  u_waveB[MAX_WAVES];
 uniform float u_waveCount;
 
 uniform float u_time;
+// The current (config flowSpeed / flowDirection). Offsets are the distance the
+// water has carried the field so far, integrated on the CPU (offset += v * dt),
+// never speed * time: animating the speed must not make the pattern jump.
+// u_flowOffset is in the field's own frame (a body's local metres, the world on
+// the world host); u_flowOffsetW and u_flowDirW are in world XZ for the
+// per-fragment ripple. All zero for still water.
+uniform vec2  u_flowOffset;
+uniform vec2  u_flowOffsetW;
+uniform vec2  u_flowDirW;
+uniform float u_flowStretch;
 uniform float u_waterLevel;
 uniform float u_choppiness;
 uniform float u_amplitudeScale;
@@ -89,6 +99,11 @@ uniform float u_receiveShadows;
 // Filled by applySunUniforms and applyTerrainAmbient, exactly as on the terrain
 // material - one atmosphere for the sky, the clouds, the ground and the water.
 uniform vec3  u_skyAmbient;
+/** How bright the sky dome is drawn (skyBrightnessForSunElevation): 1 by day,
+ *  0.08 at night. The analytic skyRadiance never goes dark on its own (Preetham's
+ *  Rayleigh term lights a sun-less sky in full daylight blue), so every place
+ *  the water reads the sky scales by this - or a pool glows blue at midnight. */
+uniform float u_skyBrightness;
 uniform vec3  u_groundAmbient;
 
 // Moonlight (useOceanMaterial, from the same moon as the key light and the
@@ -277,12 +292,25 @@ vec3 oceanDetailNormal(vec3 n, vec3 wp, float fade){
   float amt = u_detailStrength * fade;
   if (amt <= 0.001) return n;
 
-  vec2 p = wp.xz * u_detailScale;
+  // Running water: the ripple is carried downstream with the current and
+  // stretched along it, into the streaks that say "flowing" rather than
+  // "wind-blown". Sampled in the flow's frame (along, across) with the along axis
+  // compressed; the gradient is mapped back with the transpose (chain rule), so
+  // the perturbation stays in world XZ. Still water skips it (uniform branch).
+  vec2 xz = wp.xz - u_flowOffsetW;
+  float along = 1.0 / (1.0 + u_flowStretch);
+  vec2 fd = u_flowDirW;
+  vec2 fn = vec2(-fd.y, fd.x);
+  bool flowing = u_flowStretch > 0.0;
+  vec2 q = flowing ? vec2(dot(xz, fd) * along, dot(xz, fn)) : xz;
+
+  vec2 p = q * u_detailScale;
   vec2 drift = vec2(u_time * 0.06, u_time * 0.043);
 
   vec3 a = oNoised(p + drift);
   vec3 b = oNoised(p * 2.17 - drift * 1.6);
   vec2 g = a.yz + b.yz * 0.5;
+  if (flowing) g = fd * (g.x * along) + fn * g.y;
 
   // Perturb in the surface plane, so a steep wave face keeps its own orientation
   // and only gains texture.
@@ -346,7 +374,7 @@ vec3 oceanLight(
   vec3 wp, vec3 n, vec3 viewDir,   // viewDir points FROM the camera TO the surface
   float foam, float relHeight, float shadow, float depthFactor,
   float roughnessBoost,            // specular antialiasing, see the caller
-  vec3 reflectionColor
+  vec3 reflectionColor             // 0: the sky; negative: no reflection (off)
 ){
   vec3 V = -viewDir;
   vec3 L = normalize(u_sunDir);
@@ -359,7 +387,7 @@ vec3 oceanLight(
   // of dirt across the brightest part of the water.
   vec3 R = reflect(viewDir, n);
   R.y = max(R.y, 0.015);
-  vec3 sky = length(reflectionColor) > 0.0 ? reflectionColor : skyRadiance(R);
+  vec3 sky = length(reflectionColor) > 0.0 ? reflectionColor : skyRadiance(R) * u_skyBrightness;
 
   // Prefilter the reflection by the same roughness the specular lobe uses.
   // Without this the specular is filtered and the reflection is not, and on
@@ -412,7 +440,9 @@ vec3 oceanLight(
   spec += u_moonColor * ggxM * u_specular * fres;
   bodyLit += body * u_moonColor * (0.25 + 0.55 * max(dot(n, Lm), 0.0));
 
-  vec3 col = mix(bodyLit + sss, sky, fres) + spec;
+  // Reflection off: the water shows only its own colour (and the sun's glint),
+  // never the sky — not even the roughness fill above.
+  vec3 col = (reflectionColor.x < 0.0 ? bodyLit + sss : mix(bodyLit + sss, sky, fres)) + spec;
 
   // Foam is a rough dielectric, so it takes the sky and the sun diffusely and
   // kills the reflection under it.
@@ -429,7 +459,7 @@ vec3 oceanLight(
 vec3 oceanAerial(vec3 col, vec3 rd, float dist){
   float f = 1.0 - exp(-u_fogDensity * dist);
   if (f < 0.002) return col;
-  return mix(col, skyRadiance(rd), f);
+  return mix(col, skyRadiance(rd) * u_skyBrightness, f);
 }
 `;
 /** Height field only — what a vertex stage needs. */

package/dist/shaders/ocean/OceanSurfaceMaterial.d.ts

@@ -11,6 +11,7 @@ export declare const oceanMaterialDefaults: {
     u_skyAmbient: THREE.Color;
     u_groundAmbient: THREE.Color;
     u_sunIntensity: number;
+    u_skyBrightness: number;
     u_moonDir: THREE.Vector3;
     u_moonColor: THREE.Color;
     u_turbidity: number;
@@ -44,11 +45,22 @@ export declare const oceanMaterialDefaults: {
     u_waveB: THREE.Vector4[];
     u_waveCount: number;
     u_time: number;
+    u_flowOffset: THREE.Vector2;
+    u_flowOffsetW: THREE.Vector2;
+    u_flowDirW: THREE.Vector2;
+    u_flowStretch: number;
     u_waterLevel: number;
     u_choppiness: number;
     u_amplitudeScale: number;
     u_bodyHalf: THREE.Vector2;
     u_edgeFade: number;
+    u_bodyScale: THREE.Vector3;
+    u_reflectionMode: number;
+    u_reflectionMap: THREE.Texture | null;
+    u_reflectionMatrix: THREE.Matrix4;
+    u_reflectionCube: THREE.Texture | null;
+    u_probePos: THREE.Vector3;
+    u_probeRadius: number;
     u_deepColor: THREE.Color;
     u_shallowColor: THREE.Color;
     u_foamColor: THREE.Color;

package/dist/shaders/ocean/OceanSurfaceMaterial.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OceanSurfaceMaterial.d.ts","sourceRoot":"","sources":["../../../src/shaders/ocean/OceanSurfaceMaterial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AA0R9D,MAAM,WAAW,qBAAqB;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAA;CAChC;AAMD;yEACyE;AACzE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDjC,CAAA;AAgBD,qBAAa,oBAAqB,SAAQ,KAAK,CAAC,cAAc;;CAa7D;AAID,OAAO,QAAQ,oBAAoB,CAAC;IAChC,UAAU,aAAa;QACnB,oBAAoB,EAAE,YAAY,CAAC,OAAO,oBAAoB,CAAC,CAAA;KAClE;CACJ"}
+{"version":3,"file":"OceanSurfaceMaterial.d.ts","sourceRoot":"","sources":["../../../src/shaders/ocean/OceanSurfaceMaterial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AA6T9D,MAAM,WAAW,qBAAqB;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAA;CAChC;AAMD;yEACyE;AACzE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAoBL,KAAK,CAAC,OAAO,GAAG,IAAI;;sBAEnB,KAAK,CAAC,OAAO,GAAG,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;CA+CjD,CAAA;AAgBD,qBAAa,oBAAqB,SAAQ,KAAK,CAAC,cAAc;;CAa7D;AAID,OAAO,QAAQ,oBAAoB,CAAC;IAChC,UAAU,aAAa;QACnB,oBAAoB,EAAE,YAAY,CAAC,OAAO,oBAAoB,CAAC,CAAA;KAClE;CACJ"}

package/dist/shaders/ocean/OceanSurfaceMaterial.js

@@ -3,6 +3,7 @@ import { extend } from '@react-three/fiber';
 import { skyLib } from '../glsl/cloudCore.glsl.js';
 import { oceanFull, MAX_WAVES } from '../glsl/oceanCore.glsl.js';
 import { terrainFieldOnly } from '../glsl/terrainCore.glsl.js';
+import { waterReflectionGlsl } from '../../utils/waterReflection.js';
 /**
  * The water surface material. Used by both hosts — the world clipmap and a
  * placed body — and by all four water types, which differ in the spectrum the
@@ -54,6 +55,12 @@ ${oceanFull}
 ${terrainFieldOnly}
 #endif
 uniform float u_shoreDepth;
+/** World scale of a placed body's transform. The body is a unit-ish grid sized
+ *  by its transform, but the waves are metres: the field is evaluated in local
+ *  x scale (world metres), and the displacement divided back out, so a pool
+ *  scaled x8 gets the same ripples as a pool built 8 m wide. (1,1,1) on the
+ *  world host. */
+uniform vec3 u_bodyScale;
 
 /** World size of this vertex's cell. Per-vertex so one material serves every
  *  clipmap ring, and a placed body sets it from its own grid. */
@@ -87,7 +94,16 @@ void main(){
   // The LOD cell morphs with the vertex, so a ring's outer edge samples at
   // exactly the next ring's cell size and both sides of the seam fade the same
   // components by the same amount.
-  float cellLod = aCell * (1.0 + aMorph);
+  bool isBody = u_bodyHalf.x > 0.0;
+  float bodyCell = isBody ? max(u_bodyScale.x, u_bodyScale.z) : 1.0;
+  float cellLod = aCell * bodyCell * (1.0 + aMorph);
+  // ...and by what the SCREEN can carry. The grid LOD keeps every wave the mesh
+  // can draw, but from far away (or high above) a 4 m wave on a 1 m grid is two
+  // pixels wide: its crests land on different pixels every frame and the water
+  // shimmers in bright dashes. Treat the pixel footprint (x2) as a cell size, so
+  // components fade out as they approach ~3 px and distant water reads calm.
+  // The per-fragment ripple already fades the same way (oceanDetailFade).
+  cellLod = max(cellLod, distance(worldFlat.xyz, cameraPosition) * u_pixelScale * 2.0);
 
   float edge = oceanEdgeMask(local);
 
@@ -95,8 +111,7 @@ void main(){
   // because its clipmap slides under a camera that moves through the world and
   // the sea must not slide with it. A placed body is evaluated in its OWN space,
   // so its waves rotate with it and stay inside its rim.
-  bool isBody = u_bodyHalf.x > 0.0;
-  vec2 fieldXZ = isBody ? local : wxz;
+  vec2 fieldXZ = isBody ? local * u_bodyScale.xz : wxz;
 
   // Water depth from the terrain height field under this vertex.
   //
@@ -123,10 +138,16 @@ void main(){
   }
   #endif
 
+  // The current carries the whole wave field (and its foam) downstream: sample it
+  // where this water was u_flowOffset metres ago. Zero for still water.
+  vec2 fieldP = fieldXZ - u_flowOffset;
+
   vec3 disp; vec3 nrm; float jac; float rel;
-  oceanWaveSum(fieldXZ, cellLod, u_amplitudeScale * edge * shoal, disp, nrm, jac, rel);
+  oceanWaveSum(fieldP, cellLod, u_amplitudeScale * edge * shoal, disp, nrm, jac, rel);
 
-  vFoam = oceanFoam(jac, rel, vec3(fieldXZ.x, 0.0, fieldXZ.y));
+  vFoam = oceanFoam(jac, rel, vec3(fieldP.x, 0.0, fieldP.y));
+  // Metres back into the body's local units (the transform scales them up again).
+  if (isBody) disp /= u_bodyScale;
   vRelHeight = rel;
 
   // 1 in open water, ramping to 0 as the bottom comes up (shallow colour). Open
@@ -150,7 +171,11 @@ void main(){
   }
 
   vec3 world = (modelMatrix * vec4(transformed, 1.0)).xyz;
-  vNormal_ = normalize(mat3(modelMatrix) * normalize(mix(vec3(0.0, 1.0, 0.0), nrm, edge)));
+  // The wave normal is already in metres; on a scaled body only the transform's
+  // rotation may touch it (M = R*S, so M * (n / S) = R * n).
+  vec3 nLocal = normalize(mix(vec3(0.0, 1.0, 0.0), nrm, edge));
+  if (isBody) nLocal /= u_bodyScale;
+  vNormal_ = normalize(mat3(modelMatrix) * nLocal);
 
   vWorld = world;
   vDist = distance(world, cameraPosition);
@@ -193,6 +218,8 @@ varying float vTerrainShadow;
 uniform float u_shoreDepth;
 uniform float u_shoreFoam;
 
+${waterReflectionGlsl}
+
 void main(){
   vec3 viewDir = normalize(vWorld - cameraPosition);
 
@@ -235,7 +262,15 @@ void main(){
     foam = max(foam, saturate(band * (0.45 + 0.55 * wash) * u_shoreFoam));
   }
 
-  vec3 col = oceanLight(vWorld, n, viewDir, foam, vRelHeight, sceneShadow, vDepthFactor, roughAA, vec3(0.0));
+  // What the surface reflects: the one planar pass when this surface won it
+  // this frame, the sky it is drawn under otherwise, a flat fill when off. See
+  // utils/waterReflection.ts. The detail normal bends the planar lookup, which
+  // is what makes a mirrored building wobble with the ripples.
+  vec3 reflectionColor = vec3(0.0);
+  if (u_reflectionMode == 2) reflectionColor = max(waterPlanarReflection(vWorld, n, 0.045), vec3(1e-4));
+  else if (u_reflectionMode == 3) reflectionColor = max(waterProbeReflection(vWorld, viewDir, n, 0.15), vec3(1e-4));
+  else if (u_reflectionMode == 0) reflectionColor = vec3(-1.0);   // off: no reflection at all (oceanLight)
+  vec3 col = oceanLight(vWorld, n, viewDir, foam, vRelHeight, sceneShadow, vDepthFactor, roughAA, reflectionColor);
   col = oceanAerial(col, viewDir, vDist);
   col *= u_exposure;
 
@@ -286,11 +321,23 @@ export const oceanMaterialDefaults = {
     u_waveB: emptyWaveTable(),
     u_waveCount: 0,
     u_time: 0,
+    u_flowOffset: new THREE.Vector2(0, 0),
+    u_flowOffsetW: new THREE.Vector2(0, 0),
+    u_flowDirW: new THREE.Vector2(1, 0),
+    u_flowStretch: 0,
     u_waterLevel: 0,
     u_choppiness: 0.85,
     u_amplitudeScale: 1,
     u_bodyHalf: new THREE.Vector2(0, 0),
     u_edgeFade: 0.15,
+    u_bodyScale: new THREE.Vector3(1, 1, 1),
+    // Reflection (utils/waterReflection.ts): 1 = the sky until a pass is handed over.
+    u_reflectionMode: 1,
+    u_reflectionMap: null,
+    u_reflectionMatrix: new THREE.Matrix4(),
+    u_reflectionCube: null,
+    u_probePos: new THREE.Vector3(),
+    u_probeRadius: 0,
     u_deepColor: new THREE.Color('#052539'),
     u_shallowColor: new THREE.Color('#1b7f8c'),
     u_foamColor: new THREE.Color('#eef6f8'),
@@ -324,6 +371,7 @@ export const oceanMaterialDefaults = {
     u_skyAmbient: new THREE.Color(0.6, 0.9, 1.6),
     u_groundAmbient: new THREE.Color(0.45, 0.42, 0.37),
     u_sunIntensity: 1,
+    u_skyBrightness: 1,
     // Moonlight, set by useOceanMaterial; black = no moon.
     u_moonDir: new THREE.Vector3(0, 1, 0),
     u_moonColor: new THREE.Color(0, 0, 0),

package/dist/shaders/terrain/TerrainMaterial.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TerrainMaterial.d.ts","sourceRoot":"","sources":["../../../src/shaders/terrain/TerrainMaterial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAiR9D,MAAM,WAAW,uBAAuB;IACpC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAA;CAChC;AAED;yEACyE;AACzE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAqDd,KAAK,CAAC,gBAAgB,GAAG,IAAI;eAC5B,KAAK,CAAC,gBAAgB,GAAG,IAAI;YAChC,KAAK,CAAC,gBAAgB,GAAG,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BhD,CAAA;AAqBD;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,KAAK,CAAC,cAAc;;CAWxD;AAID,OAAO,QAAQ,oBAAoB,CAAC;IAChC,UAAU,aAAa;QACnB,eAAe,EAAE,YAAY,CAAC,OAAO,eAAe,CAAC,CAAA;KACxD;CACJ"}
+{"version":3,"file":"TerrainMaterial.d.ts","sourceRoot":"","sources":["../../../src/shaders/terrain/TerrainMaterial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AA6S9D,MAAM,WAAW,uBAAuB;IACpC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAA;CAChC;AAED;yEACyE;AACzE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAqDd,KAAK,CAAC,gBAAgB,GAAG,IAAI;eAC5B,KAAK,CAAC,gBAAgB,GAAG,IAAI;YAChC,KAAK,CAAC,gBAAgB,GAAG,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BhD,CAAA;AAqBD;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,KAAK,CAAC,cAAc;;CAWxD;AAID,OAAO,QAAQ,oBAAoB,CAAC;IAChC,UAAU,aAAa;QACnB,eAAe,EAAE,YAAY,CAAC,OAAO,eAAe,CAAC,CAAA;KACxD;CACJ"}