@zephyr3d/scene 0.9.27 → 0.10.0

package/dist/material/water.js

@@ -1,14 +1,20 @@
 import { applyMaterialMixins, MeshMaterial } from './meshmaterial.js';
-import { MaterialVaryingFlags, LIGHT_TYPE_DIRECTIONAL } from '../values.js';
+import { InteractiveWaveGenerator } from '../render/water_interaction.js';
+import { ShoreWaveGenerator } from '../render/shore_wave_generator.js';
+import { WaterFoamField, FoamFieldWaveGenerator, WaveFoamSource } from '../render/water_foam.js';
+import { MaterialVaryingFlags, LIGHT_TYPE_RECT, LIGHT_TYPE_DIRECTIONAL } from '../values.js';
 import { ShaderHelper } from './shader/helper.js';
-import { Interpolator, DWeakRef, Vector4, Vector3, DRef } from '@zephyr3d/base';
+import { Vector4, Vector3, DRef } from '@zephyr3d/base';
 import { screenSpaceRayTracing_HiZ, screenSpaceRayTracing_Linear2D } from '../shaders/ssr.js';
 import { fetchSampler } from '../utility/misc.js';
+import { PHYSICAL_BAKE_EXPOSURE } from '../utility/physical.js';
 import { mixinLight } from './mixins/lit.js';
 import { fresnelSchlick, distributionGGX, visGGX } from '../shaders/pbr.js';
-import { valueNoise, interleavedGradientNoise } from '../shaders/noise.js';
 import { waterScatterPhase } from '../shaders/water_medium.js';
-import { getDevice } from '../app/api.js';
+import { evaluateLTCRectLightTerms } from '../shaders/ltc_rect.js';
+import { getLTCMatLUT, getLTCAmpLUT } from '../utility/textures/ltclut.js';
+import { sampleFoamTexture, foamTexelSize, getDefaultFoamTexture } from '../utility/textures/foam.js';
+import { RenderGraphExecutor } from '../render/rendergraph/executor.js';
 
 /** Label/value pairs for {@link WaterDebugOutput}, for editor enumerations. */ const WATER_DEBUG_OUTPUTS = [
     {
@@ -19,26 +25,10 @@ import { getDevice } from '../app/api.js';
         label: 'Normal',
         value: 'normal'
     },
-    {
-        label: 'Diffuse normal',
-        value: 'diffuseNormal'
-    },
-    {
-        label: 'View facing',
-        value: 'viewFacing'
-    },
-    {
-        label: 'Front facing',
-        value: 'frontFacing'
-    },
     {
         label: 'Foam',
         value: 'foam'
     },
-    {
-        label: 'Shore foam',
-        value: 'shoreFoam'
-    },
     {
         label: 'Water depth',
         value: 'waterDepth'
@@ -67,18 +57,6 @@ import { getDevice } from '../app/api.js';
         label: 'Sun scattering',
         value: 'sunScattering'
     },
-    {
-        label: 'Sun phase',
-        value: 'sunPhase'
-    },
-    {
-        label: 'Sun integral',
-        value: 'sunIntegral'
-    },
-    {
-        label: 'Sun NoL',
-        value: 'sunNoL'
-    },
     {
         label: 'Shadow',
         value: 'shadow'
@@ -87,6 +65,10 @@ import { getDevice } from '../app/api.js';
         label: 'Subsurface',
         value: 'subsurface'
     },
+    {
+        label: 'Subsurface thickness',
+        value: 'subsurfaceThickness'
+    },
     {
         label: 'Specular',
         value: 'specular'
@@ -96,221 +78,188 @@ import { getDevice } from '../app/api.js';
         value: 'depth'
     },
     {
-        label: 'Refract UV',
-        value: 'refractUV'
+        label: 'Interaction',
+        value: 'interaction'
+    },
+    {
+        label: 'Foam field',
+        value: 'foamField'
     },
     {
-        label: 'NaN',
-        value: 'nan'
+        label: 'Shore regions (geometry)',
+        value: 'shoreRegions'
+    },
+    {
+        label: 'Shore field levels',
+        value: 'shoreLevels'
+    },
+    {
+        label: 'Swash handover (RGB)',
+        value: 'swashHandover'
+    },
+    {
+        label: 'Swash foam sources (RGB)',
+        value: 'swashFoamSources'
+    },
+    {
+        label: 'Swash foam cuts (RGB)',
+        value: 'swashFoamCuts'
+    },
+    {
+        label: 'Swash visibility (RGB)',
+        value: 'swashVisibility'
+    },
+    {
+        label: 'Swash ground support (RGB)',
+        value: 'swashGroundSupport'
     }
 ];
-/** Fresnel reflectance of water at normal incidence, for n = 1.333. */ const WATER_F0 = 0.02;
-/** Specular roughness of water close enough that the waves are resolved. */ const WATER_BASE_ROUGHNESS = 0.04;
-/**
- * Specular roughness once the distance fade has flattened the waves away.
- * Widened by the same amount the slope was cut, so the remaining mirror does
- * not alias.
- */ const WATER_DISTANT_ROUGHNESS = 0.35;
-/** Index of refraction of water. Matches the caustics pass. */ const WATER_IOR = 1.333;
-/** Ratio for a ray entering the water from air, as `refract` wants it. */ const AIR_TO_WATER_ETA = 1 / WATER_IOR;
-/** Ratio for a ray leaving the water into air. */ const WATER_TO_AIR_ETA = WATER_IOR;
-/**
- * Cap on the refracted path length, as a multiple of the straight-line distance
- * to what is behind the water. A guard against nearly tangent rays; Snell bounds
- * the true ratio near 1.5 above water, so this leaves headroom.
- */ const REFRACT_MAX_PATH_RATIO = 4;
-/**
- * Number of steps the refracted-ray march takes over {@link REFRACT_MAX_PATH_RATIO}.
- *
- * Sets how finely a scene discontinuity is caught. Fixed count keeps the shader
- * uniform across backends; 24 steps resolve a crest-to-bed exchange to well
- * under a water pixel at typical camera distances.
- */ const REFRACT_MARCH_STEPS = 24;
-/** Depth tolerance, in meters, for the march to treat a step as a hit. */ const REFRACT_MARCH_THICKNESS = 0.05;
-/**
- * Fraction of the far plane an infinite water surface is pulled in to.
- *
- * Short of 1 so the result is never the vertex the hardware clips, and never
- * lands on the cleared depth value that `ShaderHelper.isFarthestDepth` tests for
- * by equality.
+/** Fresnel reflectance of water at normal incidence, n = 1.333. */ const WATER_F0 = 0.02;
+/** Specular roughness with the waves resolved. */ const WATER_BASE_ROUGHNESS = 0.04;
+/** Specular roughness once distance has flattened the wave normals. */ const WATER_DISTANT_ROUGHNESS = 0.35;
+/**
+ * Slope variance of a wind-driven sea for the mean Fresnel of the slopes
+ * distance flattens out of the normals, from the clean-surface fit of Cox &
+ * Munk, "Measurement of the roughness of the sea surface from photographs of
+ * the sun's glitter" (JOSA 44(11), 1954): upwind sigma_u^2 = 3.16e-3 U and
+ * crosswind sigma_c^2 = 0.003 + 1.92e-3 U, U the wind speed in m/s.
+ */ const COX_MUNK_UPWIND = 3.16e-3;
+const COX_MUNK_CROSSWIND_BASE = 0.003;
+const COX_MUNK_CROSSWIND = 1.92e-3;
+/**
+ * Roughness over which the sky reflection hands over from the sharp baked sky
+ * to the environment's GGX-prefiltered radiance map, as Crest picks its
+ * reflection mip by roughness.
+ */ const SKY_PREFILTER_START = 0.06;
+const SKY_PREFILTER_FULL = 0.15;
+/** Wrap of the foam's diffuse lighting, `(N.L + w) / (1 + w)`. At 0 a lee slope is unlit. */ const FOAM_LIGHT_WRAP = 0.5;
+/**
+ * Share of the edge fade width over which the foam on a thin sheet fades: the
+ * foam outlasts the water it floats on, down to the last centimetre or so.
+ */ const FOAM_EDGE_FADE_SHARE = 0.2;
+/** Index of refraction of water. Must match the caustics pass. */ const WATER_IOR = 1.333;
+const AIR_TO_WATER_ETA = 1 / WATER_IOR;
+const WATER_TO_AIR_ETA = WATER_IOR;
+/** Cap on the refracted path, as a multiple of the straight-line distance. */ const REFRACT_MAX_PATH_RATIO = 4;
+/** Steps of the refracted-ray march over {@link REFRACT_MAX_PATH_RATIO}. */ const REFRACT_MARCH_STEPS = 24;
+/** Depth tolerance, in meters, for a march step to count as a hit. */ const REFRACT_MARCH_THICKNESS = 0.05;
+/**
+ * Fraction of the far plane an infinite surface is pulled in to. Must stay
+ * below 1: the cleared depth value is tested for by equality.
  */ const INFINITE_DEPTH_PULLIN = 0.99;
-/**
- * Minimum reflection-direction y a water surface samples the sky bake with.
- *
- * The bake's lower hemisphere is near-black, so grazing reflections would read
- * the dark terminator. Re-normalised after the floor, so only the few pixels
- * near the horizon change.
- */ const HORIZON_REFLECT_BIAS = 0.08;
-/**
- * Width in UV of the band the refraction offset fades out over at the screen
- * border. Off-screen there is no scene colour to refract, and a clamped sample
- * smears the border pixel across the water.
- */ const REFRACT_EDGE_FADE = 0.06;
-/**
- * Normalized linear depth at or above which what is behind the water is taken to
- * be the sky, and the refraction can skip its march.
- */ const SCENE_SKY_DEPTH01 = 0.999;
-/**
- * How far the surface normal bends the transmitted direction in the subsurface
- * term. This is what lets the wave itself modulate the glow.
- */ const SSS_DISTORTION = 0.25;
-/** Falloff of the subsurface lobe. Higher keeps the glow closer to the sun. */ const SSS_POWER = 4;
-/**
- * Mean cosine of one scattering event in the water body.
- *
- * Real sea water measures near 0.9, but at that value almost nothing comes back
- * towards a camera looking down at the water. The default gives up some of that
- * peak for a term that reads from above; the multiple-scattering blend in
- * {@link WaterMaterial.waterSunScattering} restores the isotropy.
+/** Minimum reflection y for the sky bake lookup; its lower hemisphere is black. */ const HORIZON_REFLECT_BIAS = 0.08;
+/** UV width of the band the refraction offset fades over at the screen border. */ const REFRACT_EDGE_FADE = 0.06;
+/** Normalized depth at or above which the scene behind the water is sky. */ const SCENE_SKY_DEPTH01 = 0.999;
+/** Medium path, in meters, through water with only sky behind it: deep enough to absorb everything. */ const SKY_MEDIUM_PATH = 1e4;
+/** Floor on the subsurface term's sun-alignment factor. */ const SSS_SUN_ALIGN_FLOOR = 0.15;
+/** Floor on the subsurface term's grazing-view factor. */ const SSS_GRAZING_FLOOR = 0.1;
+/** Softplus width of the crest gate, as a fraction of the crest height. */ const SSS_HEIGHT_SOFTNESS = 0.6;
+/** Least crest height the gate is worked out over, in metres. See {@link WaterMaterial.subsurfaceCrestHeight}. */ const SSS_CREST_HEIGHT_MIN = 0.05;
+/** Floor on the crest gate's path length. */ const SSS_CREST_PATH_FLOOR = 0.2;
+/** Extinction multiplier of the crest gate over a unit path. */ const SSS_ABSORPTION_SCALE = 3;
+/**
+ * Mean cosine of one scattering event. Real sea water is near 0.9, at which
+ * almost nothing returns to a camera looking down.
  */ const DEFAULT_SCATTER_ANISOTROPY = 0.7;
-/**
- * Floor on how fast the refracted sun ray descends, used by the in-scattering
- * integral, so a sun on the horizon cannot make the term diverge. Snell refracts
- * even a grazing sun to about 41 degrees below the surface, so it is unreachable
- * for any sun actually above the horizon.
- */ const MIN_SUN_SLOPE = 0.05;
-/**
- * Blur per meter of path that even a non-scattering medium produces, in mip
- * widths. The wave normal varies across a texel's footprint, so the background
- * is slightly defocused by the geometry alone.
- */ const REFRACT_BLUR_GEOMETRIC = 0.02;
-/**
- * How strongly the scattering coefficient drives the refraction blur, mapping
- * 1/m onto mip widths per meter. Sized so sigma_s near 0.4 reaches the top of
- * the mip chain over a few meters while clear water stays sharp.
- */ const REFRACT_BLUR_DENSITY = 1.5;
-/**
- * Cap on the refraction blur LOD.
- *
- * Past this the sample stops being "what is behind the water" and becomes the
- * average of the frame. Six levels is a 64x footprint, already far wider than
- * any real forward-scattering kernel.
- */ const REFRACT_BLUR_MAX_LOD = 6;
-/**
- * Share of the shoreline ramp the foam pattern is allowed to eat into.
- *
- * The pattern raises the threshold the ramp has to clear, which breaks its outer
- * edge into clumps. Below 1 so the foam at the contact line survives it.
- */ const SHORE_FOAM_NOISE_BITE = 0.6;
-/** World-space drift of the foam pattern, m/s. Off-axis so it has no grain. */ const SHORE_FOAM_DRIFT_X = 0.11;
-/** @see SHORE_FOAM_DRIFT_X */ const SHORE_FOAM_DRIFT_Z = -0.07;
-/** Frequency ratio between octaves. Not 2, which would align the lattices. */ const SHORE_FOAM_OCTAVE_RATIO = 2.17;
-/**
- * Weight of each foam pattern octave, coarsest first. Three octaves span about
- * five times in feature size, so one authored clump size serves both a wide
- * shoreline and a narrow collar.
- */ const SHORE_FOAM_OCTAVE_WEIGHTS = [
-    0.5,
-    0.3,
-    0.2
-];
-/**
- * Width of the band's gradient, as a fraction of the distance it reaches,
- * running inward from the reach. 1 fades across the whole band, 0 makes it a
- * hard-edged slab. The pattern can only break up what is still in the gradient.
- */ const SHORE_FOAM_EDGE_SOFTNESS = 0.85;
-/**
- * Hi-Z cells the proximity query's window spreads over its radius, which sets
- * the pyramid level. Higher locates surfaces more precisely but stops covering
- * the whole footprint, and geometry in the uncovered corners is missed.
- */ const SHORE_QUERY_TAP_SPREAD = 1.5;
-/**
- * Softness of the proximity query's minimum, as a fraction of its radius. A hard
- * minimum leaves the band in cell-shaped squares; the trade is that the band
- * sits a little tighter than the authored reach.
- */ const SHORE_QUERY_SOFTMIN = 0.25;
-/**
- * Distance, in radii, that an empty neighbourhood resolves to. Distances are
- * clamped to it before the exponential, so nothing can underflow every term and
- * leave the logarithm with nothing to take.
- */ const SHORE_QUERY_MISS_REACH = 2;
-/** Advance of the dither's hash input per frame, for TAA to average over. */ const SHORE_QUERY_DITHER_STRIDE = 5.588238;
-/**
- * How thick a cell's frustum block may be, in multiples of its own width. A cell
- * spanning an object's edge would otherwise stretch down the view ray and grow
- * foam on water far behind the object.
- */ const SHORE_QUERY_CELL_DEPTH_SPAN = 2;
+/** Floor on the refracted sun ray's descent; only reached by a sun below the horizon. */ const MIN_SUN_SLOPE = 0.05;
+/** Refraction blur per meter of path from geometry alone, in mip widths. */ const REFRACT_BLUR_GEOMETRIC = 0.02;
+/** Maps the scattering coefficient (1/m) onto refraction blur mip widths per meter. */ const REFRACT_BLUR_DENSITY = 1.5;
+/** Cap on the refraction blur LOD. */ const REFRACT_BLUR_MAX_LOD = 6;
+/**
+ * The foam's look follows Crest's OceanFoam.hlsl (Wave Harmonic, MIT): a
+ * white foam layer cut from the foam texture by the foam density with a
+ * feathered black point, lit through a normal taken from the slope of that
+ * cut over a step of a quarter texel per metre of view depth, with a narrow
+ * glint; and beneath it bubbles, the same texture blurred three mips and
+ * shifted by parallax as if under the surface, tinted and lit by the sky.
+ * The texture drifts at FOAM_DRIFT metres per second along x and z, Crest's
+ * time / 10.
+ */ const FOAM_DRIFT = 0.1;
+const FOAM_BUBBLE_MIP_SCALE = 8;
+const FOAM_SPECULAR_POWER = 293;
+const FOAM_SPECULAR_BOOST = 0.15;
 class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
-    static FEATURE_MEDIUM_MODE = this.defineFeature();
     static FEATURE_REFRACTION_MODE = this.defineFeature();
     static FEATURE_INFINITE = this.defineFeature();
-    static FEATURE_SHORE_FOAM = this.defineFeature();
     static FEATURE_DEBUG_OUTPUT = this.defineFeature();
-    static _absorptionGrad = new Interpolator('linear', 'vec3', new Float32Array([
-        0,
-        0.082,
-        0.318,
-        0.665,
-        1
-    ]), new Float32Array([
-        1,
-        1,
-        1,
-        0.22,
-        0.87,
-        0.87,
-        0,
-        0.47,
-        0.49,
-        0,
-        0.275,
-        0.44,
-        0,
-        0,
-        0
-    ]));
-    static _scatterGrad = new Interpolator('linear', 'vec3', new Float32Array([
-        0,
-        0.15,
-        0.42,
-        1
-    ]), new Float32Array([
-        0,
-        0,
-        0,
-        0.08,
-        0.41,
-        0.34,
-        0.13,
-        0.4,
-        0.45,
-        0.21,
-        0.5,
-        0.6
-    ]));
-    static _defaultScatterRampTexture = new DWeakRef();
-    static _defaultAbsorptionRampTexture = new DWeakRef();
     static _waveUpdateState = new WeakMap();
+    static _interactionUpdateState = new WeakMap();
     _region;
     _refractionScale;
-    _depthMulti;
     _reflectionStrength;
-    _scatterRampTexture;
-    _absorptionRampTexture;
     _waveGenerator;
-    /**
-   * Per-bind-group wave uniform sync, keyed by the bind group object.
-   *
-   * The material owns one bind group per pass/render-variant hash, so a water
-   * surface drawn for two different cameras touches two distinct bind groups
-   * and each must upload once per wave generator version.
-   */ _waveVersionByBindGroup;
+    _interaction;
+    /**
+   * The generator the shaders and every other consumer of the surface use: the
+   * base generator wrapped with the interaction field while one is attached,
+   * the base generator itself otherwise.
+   */ _effectiveWaveGenerator;
+    /** Settings of the shore waves, shared by reference with their generator. */ _shoreWaves = {
+        height: 0,
+        wavelength: 8,
+        period: 6,
+        zone: 20,
+        sharpness: 0.7,
+        lean: 0.5,
+        irregularity: 0.6,
+        waveFoamStrength: 1,
+        waveFoamCoverage: 0.55,
+        shorelineFoamMaxDepth: 0.65,
+        shorelineFoamStrength: 2,
+        wallFoamStrength: 1,
+        wallFoamMinSpeed: 0.2,
+        wallFoamMaxSpeed: 1.5,
+        wallFoamDrift: 0.3,
+        surfFoamDuration: 1.5,
+        foamSettleDepth: 0.02,
+        foamDriftDepth: 0.3,
+        settledFoamFade: 0.25
+    };
+    /** The shore wave layer of the effective generator, while the waves are on. */ _shoreWaveGenerator = null;
+    /** Foam with memory, carried by the water; kept across rebuilds of the generators. */ _foamField = new WaterFoamField();
+    /** The foam field layered over the base generator, innermost in the effective generator. */ _foamFieldGenerator = null;
+    /**
+   * The interaction layer of the effective generator while a field is attached,
+   * wherever it sits in the chain (the shore waves wrap it when they are on).
+   */ _interactiveWaveGenerator = null;
+    /** What feeds the foam field: the shore waves while they are on, else the open water. */ _foamSource = null;
+    /** Frame the foam field was last stepped in. */ _foamFrameId = -1;
+    /** Frame of the last update. */ _frameId = 0;
+    _edgeFadeWidth = 0.05;
+    /**
+   * Thickness in metres over which a thin sheet of water fades in from the
+   * ground under it, so swash running up the sand shows the sand through it.
+   * 0 disables it.
+   */ get edgeFadeWidth() {
+        return this._edgeFadeWidth;
+    }
+    set edgeFadeWidth(val) {
+        val = Math.max(0, val);
+        if (val !== this._edgeFadeWidth) {
+            this._edgeFadeWidth = val;
+            this.uniformChanged();
+        }
+    }
+    /** Seconds of water clock at the last update, for the shore waves. */ _waveClock = 0;
+    /** Wave uniform version last written, per bind group. */ _waveVersionByBindGroup;
     _clipmapInfo;
     _clipmapGridInfo;
     _skirtDistance;
     _ssrParams;
-    /** Absorption coefficient sigma_a, per meter, per RGB channel. */ _absorption;
-    /** Scattering coefficient sigma_s, per meter, per RGB channel. */ _scattering;
-    /** sigma_a + sigma_s, recomputed whenever either coefficient changes. */ _extinction;
-    /** sigma_s / sigma_t, the single-scattering albedo. */ _scatterAlbedo;
-    /** Scale for the absorption coefficient. */ _absorptionScale;
-    /** Scale for the scattering coefficient. */ _scatteringScale;
+    /** (wind direction x, z, Cox-Munk upwind slope variance, crosswind slope variance) */ _unresolvedSlope;
+    /** sigma_a, 1/m, per RGB channel. */ _absorption;
+    /** sigma_s, 1/m, per RGB channel. */ _scattering;
+    /** sigma_t = sigma_a + sigma_s. */ _extinction;
+    /** sigma_s / sigma_t. */ _scatterAlbedo;
+    _absorptionScale;
+    _scatteringScale;
     _causticsEnabled;
     _causticsIntensity;
     _causticsDepth;
     _causticsRange;
     _causticsFadeDistance;
     _causticsWarp;
+    _causticsMinDepth;
     _causticsSceneDepth;
     _causticsDefocus;
     _causticsResolution;
@@ -325,7 +274,8 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
     _underwaterGodRayShadow;
     _underwaterHysteresis;
     _subsurfaceIntensity;
-    _subsurfaceSteepness;
+    _subsurfaceCrestHeight;
+    _subsurfaceTint;
     _subsurfaceParams;
     _sunScatteringIntensity;
     _scatterAnisotropy;
@@ -336,20 +286,17 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
     _foamFalloff;
     _foamColor;
     _foamParams;
-    _shoreFoamAmount;
-    _shoreFoamDepth;
-    _shoreFoamFalloff;
-    _shoreFoamScale;
-    _shoreFoamWashAmount;
-    _shoreFoamWashSpeed;
-    _shoreFoamWashScale;
-    _shoreFoamParams;
-    _shoreFoamWashParams;
+    _foamFeather;
+    _foamNormalStrength;
+    _foamBubbleColor;
+    _foamBubbleCoverage;
+    _foamBubbleDepth;
+    _foamLookParams;
+    _foamTexture;
+    _foamTextureSize = 4;
     constructor(){
         super();
         this._region = new Vector4(-99999, -99999, 99999, 99999);
-        // Fitted to the legacy absorption ramp at depthMulti = 0.1, so switching the
-        // medium to physical does not change the out-of-box look much.
         this._absorption = new Vector3(1.0, 0.25, 0.15);
         this._scattering = new Vector3(0.05, 0.12, 0.18);
         this._extinction = new Vector3();
@@ -361,12 +308,12 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
         this._clipmapGridInfo = new Vector4();
         this._skirtDistance = 0;
         this._waveGenerator = new DRef();
+        this._interaction = new DRef();
+        this._effectiveWaveGenerator = null;
         this._waveVersionByBindGroup = new WeakMap();
         this._ssrParams = new Vector4(1000, 160, 0.5, 2);
-        this._scatterRampTexture = new DRef();
-        this._absorptionRampTexture = new DRef();
+        this._unresolvedSlope = new Vector4();
         this._refractionScale = 1;
-        this._depthMulti = 0.1;
         this._reflectionStrength = 1;
         this._causticsEnabled = true;
         this._causticsIntensity = 1;
@@ -374,6 +321,7 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
         this._causticsRange = 60;
         this._causticsFadeDistance = 0;
         this._causticsWarp = 1.5;
+        this._causticsMinDepth = 0.15;
         this._causticsSceneDepth = true;
         this._causticsDefocus = 0.12;
         this._causticsResolution = 1024;
@@ -385,76 +333,47 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
         this._underwaterGodRays = true;
         this._underwaterGodRayIntensity = 1;
         this._underwaterGodRaySteps = 24;
-        // Off by default: it is a shadow map lookup per march step on top of the
-        // caustic lookup already there, which roughly doubles the cost of the
-        // shafts. Worth turning on for a scene with something large standing in the
-        // water, where a shaft running through it unbroken is the obvious artefact.
         this._underwaterGodRayShadow = false;
-        // A few centimetres. Wide enough that floating-point noise on the camera
-        // height cannot flip the state, narrow enough that the transition still
-        // happens where the eye expects it.
         this._underwaterHysteresis = 0.05;
-        // Sized so a fully lit crest contributes about as much as the ambient
-        // scattering term already does.
-        this._subsurfaceIntensity = 1.5;
-        // At 4 the wave flanks carry the glow and the troughs stay dark; 20 turns
-        // the whole sea into a lamp.
-        this._subsurfaceSteepness = 4;
+        this._subsurfaceIntensity = 0.5;
+        this._subsurfaceCrestHeight = 1.5;
+        this._subsurfaceTint = new Vector3(0.86, 0.98, 0.71);
         this._subsurfaceParams = new Vector4();
-        // The integral is derived, not fitted, so 1 is what the medium coefficients
-        // already imply.
         this._sunScatteringIntensity = 1;
         this._scatterAnisotropy = DEFAULT_SCATTER_ANISOTROPY;
         this._sunScatterParams = new Vector4();
         this._refractionBlur = 1;
-        // A shallow-pool depth: the offset stays plausible on thin water and cannot
-        // reach across a large object's silhouette.
         this._cheapRefractionDepth = 1;
-        // Coverage from the generator is a folded-surface measure, not an area
-        // fraction; these map it onto one. The falloff above 1 keeps light folding
-        // from reading as foam.
         this._foamAmount = 1;
         this._foamFalloff = 1.5;
-        // Slightly off-white and slightly blue: sea foam is water and air, and a
-        // pure white one reads as snow.
         this._foamColor = new Vector3(0.92, 0.95, 0.97);
         this._foamParams = new Vector4();
-        // Off by default. The shoreline estimate is a property of whatever happens
-        // to be behind the surface, so it would grow a white rim around every
-        // submerged object in a scene authored without it.
-        this._shoreFoamAmount = 0;
-        // A waterline band of a foot or two: a wave over a gently shelving bed moves
-        // it visibly, but it stays a band and not a white lagoon.
-        this._shoreFoamDepth = 0.5;
-        // Above 1, so coverage falls off towards the outer edge rather than filling
-        // the whole band.
-        this._shoreFoamFalloff = 1.5;
-        // A couple of clumps across the band's width, whatever that width is.
-        this._shoreFoamScale = 2.5;
-        // Half the band's depth, so the waterline visibly advances and retreats
-        // without the band ever closing completely.
-        this._shoreFoamWashAmount = 0.5;
-        // One wash every eight seconds or so - the band is what a set of waves does,
-        // not what one wave does.
-        this._shoreFoamWashSpeed = 0.12;
-        // Wash phase decorrelates over ~30 m, so a long shoreline breaks in sections
-        // instead of pulsing as one.
-        this._shoreFoamWashScale = 0.03;
-        this._shoreFoamParams = new Vector4();
-        this._shoreFoamWashParams = new Vector4();
+        // Crest's defaults
+        this._foamFeather = 0.4;
+        this._foamNormalStrength = 3.5;
+        this._foamBubbleColor = new Vector3(0.64, 0.83, 0.82);
+        this._foamBubbleCoverage = 1.68;
+        this._foamBubbleDepth = 0.14;
+        this._foamLookParams = new Vector4();
+        this._foamTexture = new DRef();
         this.cullMode = 'none';
-        this.useFeature(WaterMaterial.FEATURE_MEDIUM_MODE, 'physical');
         this.useFeature(WaterMaterial.FEATURE_REFRACTION_MODE, 'march');
         this.useFeature(WaterMaterial.FEATURE_INFINITE, false);
-        this.useFeature(WaterMaterial.FEATURE_SHORE_FOAM, false);
         this.useFeature(WaterMaterial.FEATURE_DEBUG_OUTPUT, 'none');
-    //this.TAADisabled = true;
     }
     /** {@inheritDoc Material.onDispose} */ onDispose() {
         super.onDispose();
         this._waveGenerator.dispose();
-        this._scatterRampTexture.dispose();
-        this._absorptionRampTexture.dispose();
+        this._interaction.dispose();
+        this._shoreWaveGenerator?.dispose();
+        this._shoreWaveGenerator = null;
+        this._foamFieldGenerator?.dispose();
+        this._foamFieldGenerator = null;
+        this._foamSource = null;
+        this._interactiveWaveGenerator = null;
+        this._foamField.dispose();
+        this._effectiveWaveGenerator = null;
+        this._foamTexture.dispose();
     }
     /** @internal */ get region() {
         return this._region;
@@ -465,58 +384,86 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             this.uniformChanged();
         }
     }
-    get waveGenerator() {
-        return this._waveGenerator.get();
+    /**
+   * The wave generator the surface is evaluated with.
+   *
+   * While an {@link interaction} is attached this is a wrapper that layers the
+   * interaction field over {@link baseWaveGenerator}; every consumer of the
+   * surface (the shaders, the surface-point query, the caustics) goes through
+   * it and sees one displaced surface. Setting it sets the base generator.
+   */ get waveGenerator() {
+        return this._effectiveWaveGenerator;
     }
     set waveGenerator(waveGenerator) {
         if (this._waveGenerator.get() !== waveGenerator) {
             this._waveGenerator.set(waveGenerator);
-            // Bind groups are pooled and reused across frames, so an old entry must
-            // not suppress the upload for a new generator.
-            this._waveVersionByBindGroup = new WeakMap();
-            this.optionChanged(true);
+            this._rebuildEffectiveWaveGenerator();
         }
     }
-    get scatterRampTexture() {
-        const tex = this._getScatterRampTexture(getDevice());
-        return tex === WaterMaterial._defaultScatterRampTexture.get() ? null : tex;
+    /** The generator supplying the ambient surface, without any interaction field. */ get baseWaveGenerator() {
+        return this._waveGenerator.get();
     }
-    set scatterRampTexture(tex) {
-        if (tex !== this.scatterRampTexture) {
-            this._scatterRampTexture.set(tex);
-            this.uniformChanged();
+    /**
+   * Dynamic height field layered over the surface, or null for none. See
+   * {@link WaterInteraction}.
+   *
+   * Ignored, with the base generator used on its own, on a device that cannot
+   * host the field.
+   */ get interaction() {
+        return this._interaction.get();
+    }
+    set interaction(val) {
+        if (this._interaction.get() !== val) {
+            this._interaction.set(val);
+            this._rebuildEffectiveWaveGenerator();
         }
     }
-    get absorptionRampTexture() {
-        const tex = this._getAbsorptionRampTexture(getDevice());
-        return tex === WaterMaterial._defaultAbsorptionRampTexture.get() ? null : tex;
-    }
-    set absorptionRampTexture(tex) {
-        if (tex !== this.absorptionRampTexture) {
-            this._absorptionRampTexture.set(tex);
-            this.uniformChanged();
+    /** @internal */ _rebuildEffectiveWaveGenerator() {
+        const base = this._waveGenerator.get();
+        const interaction = this._interaction.get();
+        this._shoreWaveGenerator?.dispose();
+        this._shoreWaveGenerator = null;
+        this._foamFieldGenerator?.dispose();
+        this._foamFieldGenerator = null;
+        this._foamSource = null;
+        // A field left behind must not hold on to the generators disposed here
+        this._interactiveWaveGenerator?.interaction.setAmbientSurface(null);
+        this._interactiveWaveGenerator = null;
+        let effective = null;
+        if (base) {
+            // Innermost the foam field, whose foam the shore waves and the
+            // interaction field compose theirs over
+            const that = this;
+            this._foamFieldGenerator = new FoamFieldWaveGenerator(base, this._foamField, {
+                getFoamTexture: ()=>that.foamTexture,
+                getFoamTextureSize: ()=>that._foamTextureSize
+            });
+            effective = this._foamFieldGenerator;
+            this._foamSource = new WaveFoamSource(base, this._foamField);
         }
-    }
-    /**
-   * How the medium turns a path length into transmittance and in-scattering.
-   *
-   * Defaults to `physical`. `ramp` restores the legacy ramp-texture lookup for
-   * scenes that were tuned against it.
-   */ get mediumMode() {
-        return this.featureUsed(WaterMaterial.FEATURE_MEDIUM_MODE) ?? 'physical';
-    }
-    set mediumMode(val) {
-        if (val !== this.mediumMode) {
-            this.useFeature(WaterMaterial.FEATURE_MEDIUM_MODE, val);
+        if (effective && this._shoreWaves.height > 0) {
+            this._shoreWaveGenerator = new ShoreWaveGenerator(effective, this._shoreWaves, this._foamSource);
+            this._foamFieldGenerator.flowSource = this._shoreWaveGenerator;
+            this._foamSource = this._shoreWaveGenerator;
+            effective = this._shoreWaveGenerator;
         }
+        // Outermost the interaction field: its ripples ride the shore waves rather
+        // than being faded with the open water's chop near the shore, and a query
+        // of the surface without the disturbers finds it on top to rebuild
+        if (effective && interaction && interaction.isOk()) {
+            // The field reads the surface beneath it under each disturber, so a hull
+            // riding the waves is measured against the water it floats on
+            interaction.setAmbientSurface(effective);
+            effective = new InteractiveWaveGenerator(effective, interaction);
+            this._interactiveWaveGenerator = effective;
+            interaction.ensureResources();
+        }
+        this._effectiveWaveGenerator = effective;
+        // Bind groups are pooled; a stale version must not suppress the upload.
+        this._waveVersionByBindGroup = new WeakMap();
+        this.optionChanged(true);
     }
-    /**
-   * How the refracted view sample is located. Defaults to `march`.
-   *
-   * Set `offset` on hardware that cannot afford the depth-buffer search - the
-   * water still refracts, it just refracts to the wrong place. A compile-time
-   * feature, so the cheap variant carries no trace of the march.
-   */ get refractionMode() {
+    /** How the refracted view sample is located. Defaults to `march`. Compile-time feature. */ get refractionMode() {
         return this.featureUsed(WaterMaterial.FEATURE_REFRACTION_MODE) ?? 'march';
     }
     set refractionMode(val) {
@@ -524,9 +471,9 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             this.useFeature(WaterMaterial.FEATURE_REFRACTION_MODE, val);
         }
     }
-    /**
-   * Which intermediate shading term to display instead of the final colour.
-   * Defaults to `none`. See {@link WaterDebugOutput}.
+    /**
+   * Which intermediate shading term to display instead of the final colour.
+   * Defaults to `none`. See {@link WaterDebugOutput}.
    */ get debugOutput() {
         return this.featureUsed(WaterMaterial.FEATURE_DEBUG_OUTPUT) ?? 'none';
     }
@@ -535,13 +482,9 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             this.useFeature(WaterMaterial.FEATURE_DEBUG_OUTPUT, val);
         }
     }
-    /**
-   * Whether the surface reads as unbounded, reaching the horizon rather than
-   * ending at {@link region}. Off by default.
-   *
-   * The region test is not emitted at all, so the surface has no edge, and the
-   * clipmap's outermost ring becomes a horizon skirt that survives clipping past
-   * the camera's far plane. Use it for an ocean, not for a pond or a pool.
+    /**
+   * Whether the surface reaches the horizon rather than ending at {@link region}.
+   * Off by default. The clipmap's outermost ring becomes a horizon skirt.
    */ get infinite() {
         return this.featureUsed(WaterMaterial.FEATURE_INFINITE) ?? false;
     }
@@ -590,50 +533,30 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             this.uniformChanged();
         }
     }
-    /**
-   * Extinction coefficient sigma_t = sigma_a + sigma_s in 1/m.
-   *
-   * Read by the caustics pass so the light attenuated along the refracted path
-   * uses the same medium as the surface shading. Do not mutate the result.
-   */ get extinction() {
+    /** sigma_t = sigma_a + sigma_s in 1/m. Shared with the caustics pass. Do not mutate. */ get extinction() {
         return this._extinction;
     }
-    /** Single-scattering albedo sigma_s / sigma_t. Do not mutate the result. */ get scatterAlbedo() {
+    /** Single-scattering albedo sigma_s / sigma_t. Do not mutate. */ get scatterAlbedo() {
         return this._scatterAlbedo;
     }
-    /**
-   * Whether a camera inside this body of water sees the water from the inside:
-   * the medium applied to the whole scene, the sky replaced by water, and the
-   * surface read from below.
-   *
-   * The medium coefficients are the ones the surface already uses
-   * ({@link WaterMaterial.absorption}, {@link WaterMaterial.scattering} and
-   * their scales), so the volume and the surface never disagree.
+    /**
+   * Whether a camera inside this body of water sees the medium applied to the
+   * whole scene. Uses the same coefficients as the surface shading.
    */ get underwaterEnabled() {
         return this._underwaterEnabled;
     }
     set underwaterEnabled(val) {
         this._underwaterEnabled = !!val;
     }
-    /**
-   * Scale on the downwelling sky radiance that lights the water column from
-   * inside, 1 for the value the sky implies.
-   *
-   * This is what the water fades to in the distance, so it is also what decides
-   * how bright the underwater "fog" reads.
-   */ get underwaterAmbientIntensity() {
+    /** Scale on the downwelling sky radiance lighting the column from inside, 1 for physical. */ get underwaterAmbientIntensity() {
         return this._underwaterAmbientIntensity;
     }
     set underwaterAmbientIntensity(val) {
         this._underwaterAmbientIntensity = Math.max(0, val);
     }
-    /**
-   * Whether shafts of sunlight are marched through the water column.
-   *
-   * Reads the caustic map as the surface's transmittance, so the shafts carry
-   * the same focusing pattern that lands on the sea bed. Switches itself off
-   * wherever the caustic map is unavailable - WebGL1, no shadow-casting
-   * directional light, or a sun too close to the horizon.
+    /**
+   * Whether sunlight shafts are marched through the water column. Reads the
+   * caustic map, so it is off wherever that is unavailable.
    */ get underwaterGodRays() {
         return this._underwaterGodRays;
     }
@@ -646,50 +569,33 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
     set underwaterGodRayIntensity(val) {
         this._underwaterGodRayIntensity = Math.max(0, val);
     }
-    /**
-   * Samples taken along each view ray for the light shafts.
-   *
-   * The march is dithered, so a low count reads as noise rather than as banding;
-   * below about 8 the noise stops resolving into shafts at all.
-   */ get underwaterGodRaySteps() {
+    /** Samples per view ray for the light shafts. Dithered; below about 8 reads as noise. */ get underwaterGodRaySteps() {
         return this._underwaterGodRaySteps;
     }
     set underwaterGodRaySteps(val) {
         this._underwaterGodRaySteps = Math.max(1, Math.floor(val));
     }
-    /**
-   * Whether geometry standing in the water breaks the light shafts.
-   *
-   * Off by default. The shafts are built from the caustic map, which knows what
-   * the *surface* did to the sunlight and nothing about what is under it, so
-   * without this a shaft runs straight through a piling or a hull. Turning it on
-   * samples the sun's shadow map once per march step, which roughly doubles what
-   * the shafts cost; the sea bed's own shadows are unaffected either way, since
-   * those come from the ordinary lighting path.
-   *
-   * Needs the caustic light to be casting shadows, which it already must be for
-   * the caustics themselves to exist.
+    /**
+   * Whether geometry in the water breaks the light shafts. Off by default; one
+   * shadow map lookup per march step, roughly doubling the shafts' cost.
    */ get underwaterGodRayShadow() {
         return this._underwaterGodRayShadow;
     }
     set underwaterGodRayShadow(val) {
         this._underwaterGodRayShadow = !!val;
     }
-    /**
-   * Half-width in meters of the dead band around the surface the submerged test
-   * uses, so a camera sitting exactly at water level does not flip state every
-   * frame. The test is against the rest plane, not the displaced surface.
+    /**
+   * Half-width in meters of the dead band the submerged test uses around the
+   * rest plane, so a camera at water level does not flip state every frame.
    */ get underwaterHysteresis() {
         return this._underwaterHysteresis;
     }
     set underwaterHysteresis(val) {
         this._underwaterHysteresis = Math.max(0, val);
     }
-    /**
-   * Whether this water projects caustics onto the geometry below it.
-   *
-   * Requires a shadow-casting directional light and a non-WebGL1 device; the
-   * caustics pass disables itself when either is missing.
+    /**
+   * Whether this water projects caustics onto the geometry below it. Requires a
+   * shadow-casting directional light.
    */ get causticsEnabled() {
         return this._causticsEnabled;
     }
@@ -702,79 +608,56 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
     set causticsIntensity(val) {
         this._causticsIntensity = val;
     }
-    /**
-   * Depth in meters below the surface where the caustics are in focus.
-   *
-   * Receivers away from this depth are progressively defocused rather than
-   * displaced, so set it near the depth of the sea bed that should show the
-   * sharpest pattern.
-   */ get causticsDepth() {
+    /** Depth in meters below the surface where the caustics are in focus. */ get causticsDepth() {
         return this._causticsDepth;
     }
     set causticsDepth(val) {
         this._causticsDepth = Math.max(0.01, val);
     }
-    /**
-   * Furthest distance in meters from the camera the caustic map reaches.
-   *
-   * A cap rather than a fixed extent: the map is fitted to the part of the water
-   * within this distance. Raise it to light more of the scene, at the cost of
-   * resolution wherever the water is large enough to fill it.
-   */ get causticsRange() {
+    /** Furthest distance in meters from the camera the caustic map reaches. */ get causticsRange() {
         return this._causticsRange;
     }
     set causticsRange(val) {
         this._causticsRange = Math.max(1, val);
     }
-    /**
-   * Width in meters of the band the pattern fades out over at the edge of the
-   * map, or 0 to derive it from {@link causticsRange}.
-   *
-   * Too narrow a band makes the map boundary read as a hard line across the sea
-   * bed. Auto scales with the range but puts a floor under it in meters. Capped
-   * at 90% of the range, so a core of the map always survives.
+    /**
+   * Width in meters of the fade band at the edge of the caustic map, or 0 to
+   * derive it from {@link causticsRange}. Capped at 90% of the range.
    */ get causticsFadeDistance() {
         return this._causticsFadeDistance;
     }
     set causticsFadeDistance(val) {
         this._causticsFadeDistance = Math.max(0, val);
     }
-    /**
-   * Whether photons land on the scene instead of on a plane at
-   * {@link causticsDepth}.
-   *
-   * On by default. The plane displaces the pattern sideways on any receiver not
-   * at that depth, which is badly wrong under a low sun and on a sea bed with
-   * relief. Resolving the real depth reuses the sun's shadow cascade, so it
-   * costs no extra geometry pass, and falls back to the plane wherever that
-   * cascade has nothing to say.
-   *
-   * {@link causticsDepth} still sets where the iteration starts and what the
-   * defocus is measured against.
+    /**
+   * Whether photons land on the scene (via the sun's shadow cascade) instead of
+   * on a plane at {@link causticsDepth}. On by default.
    */ get causticsSceneDepth() {
         return this._causticsSceneDepth;
     }
     set causticsSceneDepth(val) {
         this._causticsSceneDepth = !!val;
     }
-    /**
-   * How strongly caustic map texels are concentrated near the camera, 0 to
-   * spread them evenly.
-   *
-   * Texel density is `1 + causticsWarp` times uniform at the centre and
-   * `1 / (1 + causticsWarp)` times it at the border. Raise it when a
-   * {@link causticsRange} large enough to light the scene is too coarse to
-   * resolve a caustic cell.
-   *
-   * Ignored while the map already fits the water within range, which is the case
-   * a bounded pool inside {@link causticsRange} always lands in.
+    /**
+   * How strongly caustic map texels are concentrated near the camera, 0 for
+   * uniform. Density is `1 + warp` times uniform at the centre and
+   * `1 / (1 + warp)` at the border. Ignored while the map fits the water.
    */ get causticsWarp() {
         return this._causticsWarp;
     }
     set causticsWarp(val) {
         this._causticsWarp = Math.max(0, Math.min(8, val));
     }
-    /** How fast the caustic contrast falls off per meter away from {@link causticsDepth}. */ get causticsDefocus() {
+    /**
+   * Water depth in metres below which no caustics show, faded in over half
+   * of it either side; 0 shows them right up to the water's edge.
+   */ get causticsMinDepth() {
+        return this._causticsMinDepth;
+    }
+    set causticsMinDepth(val) {
+        this._causticsMinDepth = Math.max(0, val);
+    }
+    /** Caustic contrast falloff per meter away from {@link causticsDepth}. */ get causticsDefocus() {
         return this._causticsDefocus;
     }
     set causticsDefocus(val) {
@@ -786,51 +669,29 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
     set causticsResolution(val) {
         this._causticsResolution = Math.max(16, Math.min(2048, val | 0));
     }
-    /**
-   * Edge length of the photon grid, or 0 to size it from the map.
-   *
-   * Auto solves for photons per map texel, which is the density that governs
-   * quality; a fixed grid over-spends on a small pool and under-spends on open
-   * water. Set a value to pin the grid explicitly; the cost is the square of it.
-   */ get causticsPhotonResolution() {
+    /** Edge length of the photon grid, or 0 to size it from the map. Cost is quadratic. */ get causticsPhotonResolution() {
         return this._causticsPhotonResolution;
     }
     set causticsPhotonResolution(val) {
         const n = val | 0;
         this._causticsPhotonResolution = n <= 0 ? 0 : Math.max(16, Math.min(4096, n));
     }
-    /**
-   * Number of 2x2 blur iterations applied to the accumulated map. Rounded up to
-   * an even count.
-   */ get causticsBlurPasses() {
+    /** Number of 2x2 blur iterations on the caustic map. Rounded up to even. */ get causticsBlurPasses() {
         return this._causticsBlurPasses;
     }
     set causticsBlurPasses(val) {
         const clamped = Math.max(0, Math.min(4, val | 0));
         this._causticsBlurPasses = clamped + (clamped & 1);
     }
-    /**
-   * Weight the previous frame's caustic map keeps in the current one, 0 to
-   * disable.
-   *
-   * Averages away the scintillation a moving photon lattice produces, in effect
-   * multiplying the photon count for free. The resolve clamps the reprojected
-   * value to its own 3x3 neighbourhood, so still regions accumulate while moving
-   * ones fall back to the current frame. Raising this past the default buys
-   * diminishing stability and starts to smear the animation.
-   */ get causticsTemporalStrength() {
+    /** Weight of the previous frame's caustic map in the current one, 0 to disable. */ get causticsTemporalStrength() {
         return this._causticsTemporalStrength;
     }
     set causticsTemporalStrength(val) {
         this._causticsTemporalStrength = Math.max(0, Math.min(0.95, val));
     }
-    /**
-   * Strength of the sunlight scattered forward through a wave crest, 0 to
-   * disable.
-   *
-   * This is the term that makes a backlit crest glow. Authored rather than
-   * derived; the medium's albedo supplies the colour, so raising this brightens
-   * the glow without shifting its hue.
+    /**
+   * Strength of the glow of a backlit wave crest, 0 to disable. Authored, not
+   * scaled by the light's intensity; {@link subsurfaceTint} supplies the hue.
    */ get subsurfaceIntensity() {
         return this._subsurfaceIntensity;
     }
@@ -840,31 +701,34 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             this.uniformChanged();
         }
     }
-    /**
-   * How sharply surface tilt gates the subsurface glow.
-   *
-   * The glow is scaled by `(1 - normal.y) * subsurfaceSteepness`, clamped to 1,
-   * so this is the reciprocal of the tilt at which it saturates. Unitless, and
-   * larger than it looks like it should be: an ocean surface is nearly flat in
-   * these terms.
-   */ get subsurfaceSteepness() {
-        return this._subsurfaceSteepness;
-    }
-    set subsurfaceSteepness(val) {
-        if (val !== this._subsurfaceSteepness) {
-            this._subsurfaceSteepness = Math.max(0, val);
+    /**
+   * Height above the still-water level, in meters, over which the lit wall of
+   * a crest thins by a factor of `e`. Lower for a calm sea, higher so only the
+   * tallest crests glow.
+   */ get subsurfaceCrestHeight() {
+        return this._subsurfaceCrestHeight;
+    }
+    set subsurfaceCrestHeight(val) {
+        // The gate softens over SSS_HEIGHT_SOFTNESS of this; too small a height
+        // makes it a hard step at the still-water level.
+        const clamped = Math.max(SSS_CREST_HEIGHT_MIN, val);
+        if (clamped !== this._subsurfaceCrestHeight) {
+            this._subsurfaceCrestHeight = clamped;
             this.uniformChanged();
         }
     }
-    /**
-   * Strength of the sunlight scattered out of the water column towards the eye,
-   * 1 for the value the medium coefficients imply. 0 disables the term.
-   *
-   * This is what gives the water body a direction-dependent colour: a shadow
-   * falling on the water darkens the water itself, and a low sun tints the
-   * column. Unlike {@link subsurfaceIntensity} this is not an authored
-   * magnitude - 1 is the physical answer and anything else is a deliberate
-   * exaggeration.
+    /** Colour of the crest glow, before the crest gate tints it with the medium's extinction. */ get subsurfaceTint() {
+        return this._subsurfaceTint;
+    }
+    set subsurfaceTint(val) {
+        if (!val.equalsTo(this._subsurfaceTint)) {
+            this._subsurfaceTint.set(val);
+            this.uniformChanged();
+        }
+    }
+    /**
+   * Strength of the sunlight scattered out of the water column towards the eye,
+   * 1 for the physical value. 0 disables the term.
    */ get sunScatteringIntensity() {
         return this._sunScatteringIntensity;
     }
@@ -875,14 +739,10 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             this.uniformChanged();
         }
     }
-    /**
-   * Depth in meters the cheap refraction mode assumes the water is, in
-   * {@link refractionMode} `offset`. Ignored by `march`.
-   *
-   * Sets how strong the distortion looks: raise it for water that should read as
-   * deep, lower it for a shallow film. A constant rather than the measured scene
-   * distance, which would double every submerged object across its silhouette;
-   * the price is that shallow and deep water distort equally.
+    /**
+   * Fixed depth in meters the `offset` refraction mode steps along the refracted
+   * ray. Ignored by `march`. Deliberately not the scene distance, which would
+   * double submerged objects across their silhouette.
    */ get cheapRefractionDepth() {
         return this._cheapRefractionDepth;
     }
@@ -893,14 +753,7 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             this.uniformChanged();
         }
     }
-    /**
-   * Scale on how much the medium blurs what is seen through it. 0 keeps the
-   * background perfectly sharp at any depth, 1 is what the medium implies.
-   *
-   * The width is derived from the scattering coefficient and the path length, so
-   * this is a stylisation knob rather than the magnitude itself. Costs nothing -
-   * it selects a mip of a chain that is generated regardless.
-   */ get refractionBlur() {
+    /** Scale on the medium's refraction blur. 0 is sharp, 1 is what the medium implies. */ get refractionBlur() {
         return this._refractionBlur;
     }
     set refractionBlur(val) {
@@ -910,15 +763,7 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             this.uniformChanged();
         }
     }
-    /**
-   * Mean cosine of a single scattering event, in `[0, 0.95]`.
-   *
-   * 0 scatters equally in all directions; higher values push light forward, so
-   * the water brightens when looking towards the sun through it and darkens
-   * when looking away. The term blends towards isotropic as the column gets
-   * optically thick, so the visible anisotropy is always less than this number
-   * alone suggests.
-   */ get scatterAnisotropy() {
+    /** Mean cosine of a single scattering event, in `[0, 0.95]`. 0 is isotropic. */ get scatterAnisotropy() {
         return this._scatterAnisotropy;
     }
     set scatterAnisotropy(val) {
@@ -928,10 +773,7 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             this.uniformChanged();
         }
     }
-    /**
-   * How much of a folded texel reads as foam, 0 to disable. Scales the wave
-   * generator's fold measure into a coverage fraction.
-   */ get foamAmount() {
+    /** Scale from the generator's fold measure to foam coverage, 0 to disable. */ get foamAmount() {
         return this._foamAmount;
     }
     set foamAmount(val) {
@@ -940,11 +782,7 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             this.uniformChanged();
         }
     }
-    /**
-   * Falloff applied to foam coverage before it is scaled. Above 1 only a crest
-   * that has genuinely broken shows any foam, which keeps a windy sea from
-   * turning uniformly white.
-   */ get foamFalloff() {
+    /** Power applied to foam coverage before scaling. Above 1 restricts foam to broken crests. */ get foamFalloff() {
         return this._foamFalloff;
     }
     set foamFalloff(val) {
@@ -962,172 +800,88 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             this.uniformChanged();
         }
     }
-    /**
-   * Coverage of the foam that collects where the water meets a surface, 0 to disable.
-   *
-   * A second foam source independent of the crest foam, keyed on how far the
-   * surface is from the nearest solid around it - the depth of water over a bed,
-   * the horizontal distance to a hull or a piling. One band covers both the
-   * shoreline and the contact line around anything standing in the water.
-   *
-   * Estimated in screen space, with the limits that implies: geometry that is
-   * off screen, hidden behind something else, or thinner than a few pixels
-   * produces no foam. Requires the Hi-Z pyramid, so it is unavailable on WebGL1.
-   *
-   * Drawn with {@link foamColor} and folded into the same coverage the crest foam
-   * feeds, so it suppresses the specular lobe and the water body underneath it
-   * exactly as that one does.
-   */ get shoreFoamAmount() {
-        return this._shoreFoamAmount;
-    }
-    set shoreFoamAmount(val) {
-        const clamped = Math.max(0, val);
-        if (clamped !== this._shoreFoamAmount) {
-            // A compile-time feature, so crossing zero rebuilds the shader while
-            // changing the value either side of it does not. Forced off on WebGL1,
-            // which has no Hi-Z pyramid for the query to read.
-            const wasEnabled = this._shoreFoamAmount > 0;
-            this._shoreFoamAmount = clamped;
-            if (wasEnabled !== clamped > 0) {
-                this.useFeature(WaterMaterial.FEATURE_SHORE_FOAM, clamped > 0 && getDevice().type !== 'webgl');
-            } else {
-                this.uniformChanged();
-            }
+    /**
+   * How gradually the white foam fades out at its edges, from a crisp cut
+   * (near 0) to a soft blend into the bubbles beneath (1).
+   */ get foamFeather() {
+        return this._foamFeather;
+    }
+    set foamFeather(val) {
+        const clamped = Math.min(Math.max(val, 0.001), 1);
+        if (clamped !== this._foamFeather) {
+            this._foamFeather = clamped;
+            this.uniformChanged();
         }
     }
-    /**
-   * How far, in meters, the foam band reaches from the surface behind it.
-   *
-   * Over a bed this is a depth of water; against anything vertical it is a
-   * horizontal distance, and the same value serves both. Coverage is solid
-   * against the contact itself and fades to nothing by this distance, so it is
-   * the outer edge of the band rather than its midpoint. What it means on screen
-   * depends on the geometry: on a steep drop-off the band is a thin line however
-   * large this is, and on a flat shelf a small value already covers a wide
-   * stretch.
-   */ get shoreFoamDepth() {
-        return this._shoreFoamDepth;
-    }
-    set shoreFoamDepth(val) {
-        const clamped = Math.max(0.001, val);
-        if (clamped !== this._shoreFoamDepth) {
-            this._shoreFoamDepth = clamped;
+    /** How much the white foam is lit as a lumpy relief rather than a flat sheet, 0 for flat. */ get foamNormalStrength() {
+        return this._foamNormalStrength;
+    }
+    set foamNormalStrength(val) {
+        const clamped = Math.max(0, val);
+        if (clamped !== this._foamNormalStrength) {
+            this._foamNormalStrength = clamped;
             this.uniformChanged();
         }
     }
-    /**
-   * Falloff applied across the band before it is scaled. Above 1 the coverage is
-   * pushed towards the near end, keeping the outer edge thin and broken instead
-   * of washing evenly over the whole range.
-   */ get shoreFoamFalloff() {
-        return this._shoreFoamFalloff;
+    /** Tint of the bubbles under the white foam, lit by the sky. */ get foamBubbleColor() {
+        return this._foamBubbleColor;
     }
-    set shoreFoamFalloff(val) {
-        const clamped = Math.max(0.01, val);
-        if (clamped !== this._shoreFoamFalloff) {
-            this._shoreFoamFalloff = clamped;
+    set foamBubbleColor(val) {
+        if (!val.equalsTo(this._foamBubbleColor)) {
+            this._foamBubbleColor.set(val);
             this.uniformChanged();
         }
     }
-    /**
-   * Size of the clumps the band's edge breaks into, as cycles across the band.
-   *
-   * Relative to {@link shoreFoamDepth} rather than an absolute frequency, so one
-   * setting serves both a shoreline metres across and a collar around a piling,
-   * and widening the band widens its clumps with it.
-   *
-   * Evaluated in world space, so the pattern stays put as the camera moves.
-   */ get shoreFoamScale() {
-        return this._shoreFoamScale;
-    }
-    set shoreFoamScale(val) {
+    /** How far the bubbles spread around the white foam and how strongly they show, 0 for none. */ get foamBubbleCoverage() {
+        return this._foamBubbleCoverage;
+    }
+    set foamBubbleCoverage(val) {
         const clamped = Math.max(0, val);
-        if (clamped !== this._shoreFoamScale) {
-            this._shoreFoamScale = clamped;
+        if (clamped !== this._foamBubbleCoverage) {
+            this._foamBubbleCoverage = clamped;
             this.uniformChanged();
         }
     }
-    /**
-   * How far the band's edge runs back and forth, as a fraction of
-   * {@link shoreFoamDepth}.
-   *
-   * This is what makes the band read as surf rather than as a painted rim. 0
-   * leaves a static band. Above 1 the band closes completely at the bottom of
-   * the cycle, which looks like the foam blinking out rather than retreating.
-   */ get shoreFoamWashAmount() {
-        return this._shoreFoamWashAmount;
-    }
-    set shoreFoamWashAmount(val) {
-        const clamped = Math.max(0, val);
-        if (clamped !== this._shoreFoamWashAmount) {
-            this._shoreFoamWashAmount = clamped;
+    /**
+   * Texture the foam is cut from, its value in the red channel: the foam
+   * density uncovers it from its brightest parts down, so bright clumps show
+   * first and dark holes last. Null for the built-in bubble pattern (see
+   * getDefaultFoamTexture), which reads as a texture of one's own would.
+   * Tiles every {@link foamTextureSize} metres.
+   */ get foamTexture() {
+        return this._foamTexture.get() ?? null;
+    }
+    set foamTexture(tex) {
+        if (tex !== this.foamTexture) {
+            this._foamTexture.set(tex);
             this.uniformChanged();
         }
     }
-    /** Run-up cycles per second. Swell rather than wind waves, so well under 1. */ get shoreFoamWashSpeed() {
-        return this._shoreFoamWashSpeed;
+    /** Metres of water one repeat of the {@link foamTexture} covers. */ get foamTextureSize() {
+        return this._foamTextureSize;
     }
-    set shoreFoamWashSpeed(val) {
-        const clamped = Math.max(0, val);
-        if (clamped !== this._shoreFoamWashSpeed) {
-            this._shoreFoamWashSpeed = clamped;
+    set foamTextureSize(val) {
+        const clamped = Math.max(0.01, val);
+        if (clamped !== this._foamTextureSize) {
+            this._foamTextureSize = clamped;
             this.uniformChanged();
         }
     }
-    /**
-   * Spatial frequency of the run-up phase, in cycles per meter.
-   *
-   * Decorrelates the wash along the shore: at 0 the entire waterline advances
-   * and retreats in lockstep, which reads as the water level itself rising and
-   * falling; a cycle every few tens of meters breaks a long shoreline into
-   * sections that run up out of step with one another.
-   */ get shoreFoamWashScale() {
-        return this._shoreFoamWashScale;
-    }
-    set shoreFoamWashScale(val) {
+    /** How deep under the surface the bubbles seem to float, in metres; they shift against the foam as the view moves. */ get foamBubbleDepth() {
+        return this._foamBubbleDepth;
+    }
+    set foamBubbleDepth(val) {
         const clamped = Math.max(0, val);
-        if (clamped !== this._shoreFoamWashScale) {
-            this._shoreFoamWashScale = clamped;
+        if (clamped !== this._foamBubbleDepth) {
+            this._foamBubbleDepth = clamped;
             this.uniformChanged();
         }
     }
-    /** Whether the shoreline foam contributes at all. @internal */ get _shoreFoamEnabled() {
-        return this.featureUsed(WaterMaterial.FEATURE_SHORE_FOAM) ?? false;
-    }
-    /**
-   * Whether this shader build can run the band: the feature is on *and* the
-   * pyramid it queries is bound for this pass.
-   *
-   * A pass outside the main graph can shade water with no Hi-Z pass having run
-   * for it, and compiling a fetch against an unbound texture is a build failure.
-   * @internal
-   */ _shoreFoamAvailable(scope) {
-        return this._shoreFoamEnabled && !!ShaderHelper.getHiZDepthTexture(scope);
-    }
     /** @internal */ _updateMediumCoefficients() {
         this._extinction.setXYZ(this._absorption.x * this._absorptionScale + this._scattering.x * this._scatteringScale, this._absorption.y * this._absorptionScale + this._scattering.y * this._scatteringScale, this._absorption.z * this._absorptionScale + this._scattering.z * this._scatteringScale);
-        // A channel with no interaction at all transmits fully and scatters nothing;
-        // its albedo is arbitrary, so pick 0 rather than divide.
         this._scatterAlbedo.setXYZ(this._extinction.x > 0 ? this._scattering.x * this._scatteringScale / this._extinction.x : 0, this._extinction.y > 0 ? this._scattering.y * this._scatteringScale / this._extinction.y : 0, this._extinction.z > 0 ? this._scattering.z * this._scatteringScale / this._extinction.z : 0);
     }
-    get depthMulti() {
-        return this._depthMulti;
-    }
-    set depthMulti(val) {
-        if (val !== this._depthMulti) {
-            this._depthMulti = val;
-            this.uniformChanged();
-        }
-    }
-    /**
-   * Artistic scale on the refracted view offset. 1 is physical, 0 disables it.
-   *
-   * The offset is already derived from Snell's law and accounts for the
-   * incidence angle, the receiver depth and the perspective foreshortening, so
-   * this exists only to dial the result back for a stylised look. Values above 1
-   * exaggerate; the surface stays continuous, but the sample can wander far
-   * enough that the medium tint stops matching what is visible through it.
-   */ get refractionScale() {
+    /** Artistic scale on the refracted view offset. 1 is physical, 0 disables it. */ get refractionScale() {
         return this._refractionScale;
     }
     set refractionScale(val) {
@@ -1137,14 +891,7 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             this.uniformChanged();
         }
     }
-    /**
-   * Scale on the Fresnel reflectance, 1 for the physical value.
-   *
-   * Below 1 the surface reflects less than it should and shows more of what is
-   * beneath it - useful when a physically correct grazing reflection buries a
-   * sea bed the shot is about. The F0 floor is scaled with it, so 0 gives a
-   * surface with no specular response at all.
-   */ get reflectionStrength() {
+    /** Scale on the Fresnel reflectance, 1 for physical. Scales F0 too, so 0 kills specular. */ get reflectionStrength() {
         return this._reflectionStrength;
     }
     set reflectionStrength(val) {
@@ -1160,12 +907,6 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
     needSceneDepth() {
         return true;
     }
-    /**
-   * The shoreline foam reads the Hi-Z pyramid's nearest-depth channel. WebGL1
-   * has no pyramid at all.
-   */ needHiZNearest() {
-        return this._shoreFoamEnabled && getDevice().type !== 'webgl';
-    }
     _createHash() {
         return `${super._createHash()}:${this.waveGenerator?.getHash() ?? ''}`;
     }
@@ -1173,16 +914,16 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
         this._clipmapInfo.setXYZW(rotation, scale, offsetX, offsetY);
         this.uniformChanged();
     }
-    setClipmapGridInfo(gridScale, gridOffsetX, gridOffsetY) {
-        if (this._clipmapGridInfo.x !== gridScale || this._clipmapGridInfo.y !== gridOffsetX || this._clipmapGridInfo.z !== gridOffsetY) {
-            this._clipmapGridInfo.setXYZW(gridScale, gridOffsetX, gridOffsetY, 0);
+    /**
+   * @param tileResolution - Cells along a clipmap tile, for the spacing of the
+   *   mesh vertices the wave generator band-limits to; 0 for no limit.
+   */ setClipmapGridInfo(gridScale, gridOffsetX, gridOffsetY, tileResolution = 0) {
+        if (this._clipmapGridInfo.x !== gridScale || this._clipmapGridInfo.y !== gridOffsetX || this._clipmapGridInfo.z !== gridOffsetY || this._clipmapGridInfo.w !== tileResolution) {
+            this._clipmapGridInfo.setXYZW(gridScale, gridOffsetX, gridOffsetY, tileResolution);
             this.uniformChanged();
         }
     }
-    /**
-   * How far from the camera the horizon skirt's outer edge is placed, in world
-   * units. Only read while {@link infinite} is on.
-   */ setSkirtDistance(distance) {
+    /** Distance from the camera to the horizon skirt's outer edge. Only read while {@link infinite}. */ setSkirtDistance(distance) {
         if (this._skirtDistance !== distance) {
             this._skirtDistance = distance;
             this.uniformChanged();
@@ -1194,14 +935,11 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
     supportLighting() {
         return true;
     }
-    /**
-   * {@inheritDoc IMixinLight.receivesWaterCaustics}
-   *
-   * Always false. Caustics belong on whatever the water is above: the submersion
-   * test compares a fragment's height against the surface height sampled on its
-   * sun ray, so unless the sun is overhead every water fragment has some other
-   * part of the same surface up-sun of it and reads as submerged wherever that
-   * part rides a crest.
+    /**
+   * {@inheritDoc IMixinLight.receivesWaterCaustics}
+   *
+   * Always false: the submersion test would read a water fragment as submerged
+   * wherever the surface up-sun of it rides a crest.
    */ receivesWaterCaustics() {
         return false;
     }
@@ -1220,54 +958,41 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
         scope.$l.scale2 = pb.mul(scope.$inputs.clipmapInfo.y, scope.clipmapGridInfo.x);
         scope.$l.clipmapMatrix = pb.mat4(pb.mul(scope.c, scope.scale2), pb.mul(scope.s, scope.scale2), 0, 0, pb.neg(pb.mul(scope.s, scope.scale2)), pb.mul(scope.c, scope.scale2), 0, 0, 0, 0, 1, 0, pb.sub(pb.mul(scope.$inputs.clipmapInfo.z, scope.clipmapGridInfo.x), scope.clipmapGridInfo.y), pb.sub(pb.mul(scope.$inputs.clipmapInfo.w, scope.clipmapGridInfo.x), scope.clipmapGridInfo.z), 0, 1);
         scope.$l.clipmapPos = pb.mul(scope.clipmapMatrix, pb.vec4(scope.$inputs.position, 1)).xy;
-        //scope.$l.level = pb.mul(ShaderHelper.getWorldMatrix(scope), pb.vec4(0, 0, 0, 1)).y;
-        scope.clipmapWorldPos = pb.mul(ShaderHelper.getWorldMatrix(scope), pb.vec4(scope.clipmapPos.x, 0, scope.clipmapPos.y, 1)).xyz; // pb.vec3(scope.clipmapPos.x, scope.level, scope.clipmapPos.y);
+        scope.clipmapWorldPos = pb.mul(ShaderHelper.getWorldMatrix(scope), pb.vec4(scope.clipmapPos.x, 0, scope.clipmapPos.y, 1)).xyz;
         scope.worldNormal = pb.vec3(0, 1, 0);
         scope.worldPos = scope.clipmapWorldPos;
+        // Mesh vertex spacing: clipmap level L spans Chebyshev distances T 2^L to
+        // 2T 2^L cells with cells 2^L across, so distance / T bounds it. Taken from
+        // the distance, not the level, so both sides of a seam agree.
+        scope.$l.camOffset = pb.abs(pb.sub(scope.clipmapWorldPos.xz, ShaderHelper.getCameraPosition(scope).xz));
+        scope.$l.vertexSpacing = pb.mul(pb.max(scope.clipmapGridInfo.x, pb.div(pb.max(scope.camOffset.x, scope.camOffset.y), pb.max(scope.clipmapGridInfo.w, 1))), pb.step(0.5, scope.clipmapGridInfo.w));
         if (this.infinite) {
             const that = this;
-            // The clipmap meshes all leave position.z at 0; the skirt ring sets it to
-            // 1 on its outer edge. Its inner edge is welded to the outermost tiles and
-            // is displaced with them, so the join stays closed.
+            // position.z is 1 on the skirt ring's outer edge, 0 everywhere else.
             scope.$l.skirt = pb.step(0.5, scope.$inputs.position.z);
             scope.$if(pb.greaterThan(scope.skirt, 0), function() {
-                // Radially outwards from the camera rather than from the clipmap
-                // origin: the ring has to read as a horizon from where it is being
-                // looked at, and the clipmap is snapped to a grid the camera wanders
-                // within.
+                // Pushed radially out from the camera, undisplaced, at the still-water level.
                 this.$l.camXZ = ShaderHelper.getCameraPosition(this).xz;
                 this.$l.outDir = pb.normalize(pb.sub(this.clipmapWorldPos.xz, this.camXZ));
                 this.$l.outXZ = pb.add(this.camXZ, pb.mul(this.outDir, this.skirtDistance));
-                // Flat, at the still-water level. A displaced vertex out here would be
-                // several kilometres from its neighbours, so any wave it sampled would
-                // read as a jagged silhouette rather than a swell.
                 this.worldPos = pb.vec3(this.outXZ.x, this.clipmapWorldPos.y, this.outXZ.y);
             }).$else(function() {
-                that.waveGenerator?.calcVertexPositionAndNormal(this, this.clipmapWorldPos, this.worldPos, this.worldNormal);
+                that.waveGenerator?.calcVertexPositionAndNormal(this, this.clipmapWorldPos, this.worldPos, this.worldNormal, this.vertexSpacing);
             });
             scope.$outputs.skirt = scope.skirt;
         } else {
-            this.waveGenerator?.calcVertexPositionAndNormal(scope, scope.clipmapWorldPos, scope.worldPos, scope.worldNormal);
+            this.waveGenerator?.calcVertexPositionAndNormal(scope, scope.clipmapWorldPos, scope.worldPos, scope.worldNormal, scope.vertexSpacing);
         }
         scope.$outputs.worldPos = scope.worldPos;
         scope.$outputs.clipmapPos = scope.clipmapWorldPos;
         scope.$outputs.worldNormal = scope.worldNormal;
         if (this.infinite) {
-            // Pulled in along the view ray rather than depth-clamped.
-            //
-            // The surface has to reach past the far plane, but the depth buffer cannot
-            // encode anything past it. A perspective projection is invariant under
-            // scaling about the eye, so moving a vertex along its own view ray leaves
-            // its screen position untouched while bringing its depth back inside the
-            // frustum - every vertex stays unclipped, so there is no seam to tear.
-            //
-            // Shading keeps the true world position, so only the written depth is
-            // affected, and only past the far plane.
+            // Vertices past the far plane are pulled in along their own view ray:
+            // screen position is unchanged, only the written depth moves. Shading
+            // keeps the true world position.
             scope.$l.camPos = ShaderHelper.getCameraPosition(scope).xyz;
             scope.$l.viewVec = pb.sub(scope.$outputs.worldPos, scope.camPos);
             scope.$l.viewDist = pb.max(pb.length(scope.viewVec), 1e-6);
-            // Just inside the far plane, so the vertex is never the one the hardware
-            // decides to clip and never lands on the cleared depth value.
             scope.$l.maxDist = pb.mul(ShaderHelper.getCameraParams(scope).y, INFINITE_DEPTH_PULLIN);
             scope.$l.pullIn = pb.min(pb.div(scope.maxDist, scope.viewDist), 1);
             scope.$l.projPos = pb.add(scope.camPos, pb.mul(scope.viewVec, scope.pullIn));
@@ -1275,7 +1000,18 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
         } else {
             ShaderHelper.setClipSpacePosition(scope, pb.mul(ShaderHelper.getViewProjectionMatrix(scope), pb.vec4(scope.$outputs.worldPos, 1)));
         }
-        ShaderHelper.resolveMotionVector(scope, scope.$outputs.worldPos, scope.$outputs.worldPos);
+        const gen = this.waveGenerator;
+        if (gen?.calcPrevVertexPosition && ShaderHelper.getPrevUnjitteredViewProjectionMatrix(scope)) {
+            scope.$l.prevWorldPos = pb.vec3();
+            gen.calcPrevVertexPosition(scope, scope.clipmapWorldPos, scope.prevWorldPos, scope.vertexSpacing);
+            if (this.infinite) {
+                // The skirt does not move
+                scope.prevWorldPos = pb.mix(scope.prevWorldPos, scope.$outputs.worldPos, scope.skirt);
+            }
+            ShaderHelper.resolveMotionVector(scope, scope.$outputs.worldPos, scope.prevWorldPos);
+        } else {
+            ShaderHelper.resolveMotionVector(scope, scope.$outputs.worldPos, scope.$outputs.worldPos);
+        }
     }
     fragmentShader(scope) {
         super.fragmentShader(scope);
@@ -1287,129 +1023,292 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
         if (this.needFragmentColor()) {
             scope.refractionScale = pb.float().uniform(2);
             if (this.refractionMode === 'offset') {
-                // Only the cheap path has a fixed depth scale to step along; the march
-                // derives its own from the scene.
                 scope.cheapRefractionDepth = pb.float().uniform(2);
             }
             scope.reflectionStrength = pb.float().uniform(2);
+            // (wind direction x, z, upwind slope variance, crosswind slope variance)
+            scope.unresolvedSlope = pb.vec4().uniform(2);
+            // Sky bake to the live pre-exposed space, as the visible sky is drawn
+            scope.skyReflectScale = pb.float().uniform(2);
             scope.ssrParams = pb.vec4().uniform(2);
-            // (intensity, 1 / full-scatter crest height, 0, 0)
+            // Eye vs. rest plane from the CPU submersion test: 1 above, -1 below,
+            // 0 unknown (compare in the shader).
+            scope.eyeSide = pb.float().uniform(2);
+            // (intensity, crest absorption height in m, 0, 0)
             scope.subsurfaceParams = pb.vec4().uniform(2);
+            scope.subsurfaceTint = pb.vec3().uniform(2);
             // (coverage scale, coverage falloff, 0, 0)
             scope.foamShadingParams = pb.vec4().uniform(2);
             scope.foamColor = pb.vec3().uniform(2);
-            if (this._shoreFoamAvailable(scope)) {
-                // (coverage scale, band depth in m, coverage falloff, pattern cycles/m)
-                scope.shoreFoamParams = pb.vec4().uniform(2);
-                // (run-up amount, run-up cycles/s, run-up cycles/m, query radius in m)
-                scope.shoreFoamWashParams = pb.vec4().uniform(2);
-            }
+            // (white foam feather, foam normal strength, bubble coverage, bubble depth in m)
+            scope.foamLookParams = pb.vec4().uniform(2);
+            scope.foamBubbleColor = pb.vec3().uniform(2);
+            scope.foamTex = pb.tex2D().uniform(2);
+            // uv of the foam texture per metre
+            scope.foamUVScale = pb.float().uniform(2);
+            // Thickness in metres a sheet of water fades in over, 0 for none
+            scope.edgeFadeWidth = pb.float().uniform(2);
             // (intensity, anisotropy, 0, 0)
             scope.sunScatterParams = pb.vec4().uniform(2);
-            // Mip widths per meter of path the medium's scattering contributes to the
-            // refraction blur. Resolved on the CPU from the per-channel scattering
-            // coefficient, since the blur is one LOD for all three.
+            // Mip widths per meter of path; one scalar LOD for all three channels.
             scope.refractBlurDensity = pb.float().uniform(2);
-            // Declared in both medium modes: the ramp only replaces the depth-driven
-            // absorption and scattering, while the subsurface and sun-scattering terms
-            // need the medium's hue and thickness regardless.
             scope.mediumAlbedo = pb.vec3().uniform(2);
             scope.mediumExtinction = pb.vec3().uniform(2);
-            if (this.mediumMode === 'ramp') {
-                scope.depthMulti = pb.float().uniform(2);
-                scope.scatterRampTex = pb.tex2D().uniform(2);
-                scope.absorptionRampTex = pb.tex2D().uniform(2);
-            }
+            // Rect light specular (evaluateLTCRectLightTerms).
+            scope.zLTCMatLut = pb.tex2D().uniform(2);
+            scope.zLTCAmpLut = pb.tex2D().uniform(2);
         }
-        // An unbounded surface has no edge to clip against.
         if (!this.infinite) {
             scope.$l.discardable = pb.or(pb.any(pb.lessThan(scope.$inputs.worldPos.xz, scope.region.xy)), pb.any(pb.greaterThan(scope.$inputs.worldPos.xz, scope.region.zw)));
             scope.$if(scope.discardable, function() {
                 pb.discard();
             });
         }
+        if (this.debugOutput === 'shoreRegions' || this.debugOutput === 'shoreLevels') {
+            // Show the actual displaced carrier in every pass. Wet-edge discard and
+            // ground-depth projection would otherwise conceal its geometry or create
+            // an apparent boundary unrelated to rasterized mesh coverage.
+            if (this.needFragmentColor()) {
+                if (this.debugOutput === 'shoreLevels') {
+                    scope.$l.outColor = pb.vec4(this._shoreWaveGenerator ? this._shoreWaveGenerator.calcDebugLevels(scope, scope.$inputs.clipmapPos.xz) : pb.vec3(0.1), 1);
+                } else {
+                    scope.$l.shoreRegion = this._shoreWaveGenerator ? this._shoreWaveGenerator.calcDebugRegion(scope, scope.$inputs.clipmapPos.xz) : pb.vec3(0, 0, 1);
+                    scope.$l.shoreColor = scope.$choice(pb.greaterThan(scope.shoreRegion.y, 0.5), scope.$choice(pb.greaterThan(scope.shoreRegion.z, 1e-3), pb.vec3(1, 0.3, 0.02), pb.vec3(0.85, 0.02, 0.8)), pb.vec3(0, 0.85, 1));
+                    scope.$l.outColor = pb.vec4(pb.mix(pb.vec3(0.02, 0.12, 0.9), scope.shoreColor, scope.shoreRegion.x), 1);
+                }
+                if (this.drawContext.materialFlags & (MaterialVaryingFlags.SCENE_STORE_ROUGHNESS | MaterialVaryingFlags.SCENE_STORE_NORMAL)) {
+                    this.outputFragmentColor(scope, scope.$inputs.worldPos, scope.outColor, pb.vec4(0), scope.outColor);
+                } else {
+                    this.outputFragmentColor(scope, scope.$inputs.worldPos, scope.outColor);
+                }
+            } else {
+                this.outputFragmentColor(scope, scope.$inputs.worldPos, null);
+            }
+            return;
+        }
         if (this.needFragmentColor()) {
-            scope.$l.normal = this.waveGenerator ? this.waveGenerator.calcFragmentNormalAndFoam(scope, scope.$inputs.clipmapPos.xz, scope.$inputs.worldNormal) : pb.vec4(scope.$inputs.worldNormal, 0);
+            // Screen derivatives of the undisplaced position, taken here in uniform
+            // control flow; the foam textures are sampled with them under branches.
+            scope.$l.restXZGrad = pb.vec4(pb.dpdx(scope.$inputs.clipmapPos.xz), pb.dpdy(scope.$inputs.clipmapPos.xz));
+            // The foam texture here, drifting; a generator carrying foam of its own
+            // blends in where its foam is
+            scope.$l.foamSample = sampleFoamTexture(scope, scope.foamTex, pb.mul(pb.add(scope.$inputs.clipmapPos.xz, pb.vec2(pb.mul(ShaderHelper.getElapsedTime(scope), FOAM_DRIFT))), scope.foamUVScale), scope.restXZGrad, scope.foamUVScale);
+            scope.$l.normal = this.waveGenerator ? this.waveGenerator.calcFragmentNormalAndFoam(scope, scope.$inputs.clipmapPos.xz, scope.$inputs.worldNormal, scope.foamSample, this.waveGenerator.calcUnresolvedSlopeVariance ? scope.restXZGrad : undefined) : pb.vec4(scope.$inputs.worldNormal, 0);
             if (this.infinite) {
-                // Flat and foamless across the horizon band. The skirt's world position
-                // was never displaced, so evaluating waves from it would paint detail
-                // the geometry does not have - and at kilometres per pixel that detail
-                // is under-sampled into crawling speckle. The screen-space fog pass is
-                // what should be visible here.
+                // Flat and foamless on the skirt: waves evaluated at kilometres per
+                // pixel alias into speckle.
                 scope.normal = pb.mix(scope.normal, pb.vec4(0, 1, 0, 0), scope.$inputs.skirt);
             }
-            scope.$l.outColor = pb.vec4(this.waterShading(scope, scope.$inputs.worldPos, scope.normal.xyz, scope.normal.w), 1);
+            // Vertical wave displacement, interpolated from the vertices. Zero on the skirt.
+            scope.$l.crestHeight = pb.sub(scope.$inputs.worldPos.y, scope.$inputs.clipmapPos.y);
+            const surfaceCoverage = this.waveGenerator?.calcSurfaceCoverage;
+            scope.$l.surfaceCoverage = surfaceCoverage ? surfaceCoverage.call(this.waveGenerator, scope, scope.$inputs.clipmapPos.xz) : pb.float(1);
+            const sheetThickness = this.waveGenerator?.calcSheetThickness;
+            scope.$l.sheetThickness = sheetThickness ? sheetThickness.call(this.waveGenerator, scope, scope.$inputs.clipmapPos.xz) : pb.float(-1);
+            if (this._shoreWaveGenerator) {
+                // Near the shore the foam is at least the near-shore density, joining
+                // the breaking waves' foam to the beach's (see nearShore).
+                scope.normal.w = this._shoreWaveGenerator.calcNearShoreFoam(scope, scope.$inputs.clipmapPos.xz, scope.normal.w);
+            }
+            // Reconstruct the opaque surface before the swash's discard. Deposited
+            // foam is projected onto this ground, independently of the raised mesh.
+            scope.$l.scenePos = ShaderHelper.samplePositionFromDepth(scope, ShaderHelper.getLinearDepthTexture(scope), pb.div(scope.$builtins.fragCoord.xy, ShaderHelper.getRenderSize(scope)), ShaderHelper.getJitteredInvVPMatrix(scope), ShaderHelper.getCameraParams(scope).xy);
+            scope.$l.groundFoamDensity = pb.float(0);
+            scope.$l.groundFoamSample = pb.vec3(0);
+            scope.$l.groundFoamWeight = pb.float(0);
+            scope.$l.groundNormal = pb.vec3(0, 1, 0);
+            if (this.debugOutput === 'swashVisibility') {
+                scope.$l.visibilityDepthFail = pb.float(0);
+            }
+            if (this.debugOutput === 'swashGroundSupport') {
+                scope.$l.groundFieldCoverage = pb.float(0);
+                scope.$l.groundWetCoverage = pb.float(0);
+            } else if (this.debugOutput === 'swashHandover') {
+                scope.$l.groundWetCoverage = pb.float(0);
+            } else if (this.debugOutput === 'swashFoamSources') {
+                scope.$l.groundFieldDensity = pb.float(0);
+                scope.$l.groundSurfDensity = pb.float(0);
+            }
+            if (this._shoreWaveGenerator && this._foamFieldGenerator) {
+                // Derivatives precede all coverage branches; pattern coordinates stay
+                // fixed to the sand even while the water and camera move.
+                scope.$l.groundGrad = pb.vec4(pb.dpdx(scope.scenePos.xz), pb.dpdy(scope.scenePos.xz));
+                scope.$l.groundCross = pb.cross(pb.dpdx(scope.scenePos.xyz), pb.dpdy(scope.scenePos.xyz));
+                scope.groundNormal = pb.normalize(pb.add(pb.mul(scope.groundCross, pb.sign(scope.groundCross.y)), pb.vec3(0, 1e-8, 0)));
+                scope.$l.groundMask = this._shoreWaveGenerator.calcFoamGroundMask(scope, scope.scenePos.xyz);
+                const field = this._foamField;
+                const shore = this._shoreWaveGenerator;
+                const debugOutput = this.debugOutput;
+                scope.$if(pb.and(pb.lessThan(scope.scenePos.w, SCENE_SKY_DEPTH01), pb.greaterThan(scope.groundMask, 0)), function() {
+                    // The field's foam at the actual ground position: on a thin sheet and
+                    // on the sand it drained from alike, the field holding it there
+                    // (FOAM_SETTLE of the shore waves)
+                    this.$l.groundMobile = field.sample(this, this.scenePos.xz);
+                    this.$l.groundWet = shore.calcSurfaceCoverage(this, this.scenePos.xz);
+                    this.$l.groundThickness = shore.calcSheetThickness(this, this.scenePos.xz);
+                    // Coverage and handover describe the same carrier point. Using the
+                    // ground point's thickness here leaves a gap at grazing angles:
+                    // the carrier can be dry while its projected ground is still wet.
+                    this.$l.groundHandoverThickness = this.$choice(pb.greaterThanEqual(this.sheetThickness, 0), this.sheetThickness, this.groundThickness);
+                    if (debugOutput === 'swashGroundSupport') {
+                        this.groundWetCoverage = this.groundWet;
+                        this.groundFieldCoverage = this.groundMobile.y;
+                    } else if (debugOutput === 'swashHandover') {
+                        this.groundWetCoverage = this.groundWet;
+                    } else if (debugOutput === 'swashFoamSources') {
+                        this.groundFieldDensity = this.groundMobile.x;
+                        this.groundSurfDensity = pb.mul(shore.calcNearShoreFoam(this, this.scenePos.xz, pb.float(0)), this.groundWet);
+                    }
+                    this.groundFoamWeight = pb.mul(this.groundMask, this.groundMobile.y, // Unknown thickness must retain the water surface. In particular,
+                    // a valid sand bed outside the shore-wave zone is not a dry sheet.
+                    this.$choice(pb.greaterThanEqual(this.groundHandoverThickness, 0), pb.sub(1, pb.smoothStep(0.01, 0.06, this.groundHandoverThickness)), pb.float(0)));
+                    // The surf's foam only where the sheet now is; the field's wherever it holds it
+                    this.groundFoamDensity = pb.clamp(pb.max(this.groundMobile.x, pb.mul(shore.calcNearShoreFoam(this, this.scenePos.xz, pb.float(0)), this.groundWet)), 0, 1);
+                    this.$if(pb.greaterThan(this.groundFoamDensity, 1e-3), function() {
+                        // The water's foam pattern at the ground: it stands still near
+                        // the shore (see nearShore), so the beach's foam and the water's
+                        // are one pattern through the handover.
+                        this.groundFoamSample = WaterFoamField.flowPattern(this, this.ffFoamTex, this.ffFoamUVScale, this.ffClock.x, this.scenePos.xz, this.groundGrad, shore.calcFoamFlow(this, this.scenePos.xz, this.ffDrift));
+                    });
+                });
+                // The thin-film foam and its depth use the same ground transition.
+                // Otherwise a wet carrier can still clip the projected foam against
+                // the terrain right where the two layers meet.
+                scope.$builtins.fragDepth = pb.mix(scope.$builtins.fragCoord.z, ShaderHelper.linearNormalizedToNonLinearDepth(scope, pb.max(pb.sub(scope.scenePos.w, pb.div(0.001, ShaderHelper.getCameraParams(scope).y)), 0), ShaderHelper.getCameraParams(scope).xy), scope.$choice(pb.lessThanEqual(scope.surfaceCoverage, 1e-3), pb.float(1), scope.groundFoamWeight));
+            }
+            const revealSwash = this.debugOutput === 'foamField' || this.debugOutput === 'swashVisibility' || this.debugOutput === 'swashGroundSupport';
+            if (revealSwash && this._shoreWaveGenerator && this._foamFieldGenerator) {
+                if (this.debugOutput === 'swashVisibility') {
+                    scope.visibilityDepthFail = scope.$choice(pb.greaterThan(pb.mul(pb.sub(ShaderHelper.nonLinearDepthToLinearNormalized(scope, scope.$builtins.fragDepth), scope.scenePos.w), ShaderHelper.getCameraParams(scope).y), 0.0001), pb.float(1), pb.float(0));
+                }
+                scope.$if(pb.and(pb.lessThan(scope.scenePos.w, SCENE_SKY_DEPTH01), pb.greaterThan(scope.groundMask, 0)), function() {
+                    this.$builtins.fragDepth = ShaderHelper.linearNormalizedToNonLinearDepth(this, pb.max(pb.sub(this.scenePos.w, pb.div(0.001, ShaderHelper.getCameraParams(this).y)), 0), ShaderHelper.getCameraParams(this).xy);
+                });
+            }
+            scope.$l.swashDiscard = pb.and(pb.lessThanEqual(scope.surfaceCoverage, 1e-3), pb.lessThanEqual(pb.mul(scope.groundFoamDensity, scope.groundFoamWeight), 1e-3));
+            // Past the wet edge, only the foam actually left on the ground draws.
+            if (surfaceCoverage && !revealSwash) {
+                scope.$if(scope.swashDiscard, function() {
+                    pb.discard();
+                });
+            }
+            if (this.debugOutput === 'swashGroundSupport') {
+                scope.$l.outColor = pb.vec4(this._shoreWaveGenerator && this._foamFieldGenerator ? scope.groundMask : pb.float(0), scope.groundFieldCoverage, scope.groundWetCoverage, 1);
+            } else if (this.debugOutput === 'swashVisibility') {
+                scope.$l.outColor = pb.vec4(scope.$choice(scope.swashDiscard, pb.float(1), pb.float(0)), scope.visibilityDepthFail, scope.groundFoamDensity, 1);
+            } else if (this.debugOutput === 'swashHandover') {
+                scope.$l.outColor = pb.vec4(scope.surfaceCoverage, scope.groundWetCoverage, scope.groundFoamWeight, 1);
+            } else if (this.debugOutput === 'swashFoamSources') {
+                scope.$l.outColor = pb.vec4(scope.normal.w, scope.groundFieldDensity, scope.groundSurfDensity, 1);
+            } else if (this.debugOutput === 'interaction') {
+                // The field on its own, grey at rest, scaled so its amplitude clamp
+                // reaches black and white; dimmed outside the window so its reach shows.
+                if (this._interactiveWaveGenerator) {
+                    const interaction = this._interactiveWaveGenerator.interaction;
+                    scope.$l.wiDebugHeight = pb.div(interaction.sampleHeight(scope, scope.$inputs.clipmapPos.xz), scope.wiParams2.y);
+                    scope.$l.wiDebugMask = pb.mix(pb.float(0.55), pb.float(1), interaction.windowMask(scope, scope.$inputs.clipmapPos.xz));
+                } else {
+                    scope.$l.wiDebugHeight = pb.float(0);
+                    scope.$l.wiDebugMask = pb.float(1);
+                }
+                scope.$l.outColor = pb.vec4(pb.vec3(pb.mul(pb.add(0.5, pb.mul(scope.wiDebugHeight, 0.5)), scope.wiDebugMask)), 1);
+            } else if (this.debugOutput === 'foamField') {
+                // The field's density; mid grey off the field, where coverage is 0
+                if (this._foamFieldGenerator) {
+                    scope.$l.ffDebug = this._foamField.sample(scope, scope.$inputs.clipmapPos.xz);
+                } else {
+                    scope.$l.ffDebug = pb.vec3(0);
+                }
+                scope.$l.outColor = pb.vec4(pb.vec3(pb.mix(pb.float(0.5), pb.max(scope.ffDebug.x, scope.ffDebug.z), scope.ffDebug.y)), 1);
+            } else {
+                // The foam field's wall foam layer, see FOAM_WALL
+                scope.$l.wallFoam = this._foamFieldGenerator ? pb.mul(this._foamField.sample(scope, scope.$inputs.clipmapPos.xz).z, this.infinite ? pb.sub(1, scope.$inputs.skirt) : pb.float(1)) : pb.float(0);
+                scope.$l.outColor = pb.vec4(this.waterShading(scope, scope.$inputs.worldPos, scope.normal.xyz, scope.normal.w, scope.crestHeight, scope.$inputs.clipmapPos.xz, scope.restXZGrad, scope.foamSample, scope.surfaceCoverage, scope.sheetThickness, scope.wallFoam, scope.scenePos, scope.groundFoamDensity, scope.groundFoamSample, scope.groundNormal, scope.groundFoamWeight), 1);
+            }
             if (this.drawContext.materialFlags & (MaterialVaryingFlags.SCENE_STORE_ROUGHNESS | MaterialVaryingFlags.SCENE_STORE_NORMAL)) {
-                // The real roughness, not a constant 1, so SSR on another surface does
-                // not treat a near-mirror sea as fully diffuse.
-                scope.$l.outRoughness = pb.vec4(pb.vec3(this.waterRoughness(scope, scope.$inputs.worldPos)), 0);
+                scope.$l.outRoughness = pb.vec4(pb.vec3(this.waterRoughness(scope, scope.$inputs.worldPos, scope.restXZGrad)), 0);
                 this.outputFragmentColor(scope, scope.$inputs.worldPos, scope.outColor, scope.outRoughness, scope.outColor);
             } else {
                 this.outputFragmentColor(scope, scope.$inputs.worldPos, scope.outColor);
             }
         } else {
+            // The support mesh over dry sand is only a carrier for the colour pass.
+            // It must not replace terrain depth or its motion vectors in other passes.
+            const coverage = this.waveGenerator?.calcSurfaceCoverage;
+            if (coverage) {
+                scope.$l.surfaceCoverage = coverage.call(this.waveGenerator, scope, scope.$inputs.clipmapPos.xz);
+                scope.$if(pb.lessThanEqual(scope.surfaceCoverage, 1e-3), function() {
+                    pb.discard();
+                });
+            }
             this.outputFragmentColor(scope, scope.$inputs.worldPos, null);
         }
     }
-    /**
-   * Specular roughness of the surface at a world position.
-   *
-   * Distance fades the wave normals flat, and this hands that lost slope to the
-   * specular lobe instead of dropping it. Shared with the scene roughness buffer
-   * so a surface reflecting the water sees the same value.
-   */ waterRoughness(scope, worldPos) {
+    /**
+   * Covariance (x, z, xz) of the wave slopes the shading normal no longer shows
+   * at this pixel, or null when the wave generator cannot tell.
+   */ unresolvedSlopeVariance(scope, restXZGrad) {
+        const gen = this.waveGenerator;
+        return gen?.calcUnresolvedSlopeVariance ? gen.calcUnresolvedSlopeVariance(scope, restXZGrad) : null;
+    }
+    /**
+   * Specular roughness at a world position. The slopes too fine for the pixel
+   * leave the normal and are handed to the lobe, GGX alpha^2 taking their
+   * variance (Beckmann m^2 = 2 sigma^2 per axis). Without the generator's
+   * account of them, distance flattens the normals and the lobe widens with it.
+   * Also written to the scene roughness buffer.
+   */ waterRoughness(scope, worldPos, restXZGrad) {
         const pb = scope.$builder;
+        const that = this;
         pb.func('waterRoughness', [
-            pb.vec3('worldPos')
+            pb.vec3('worldPos'),
+            pb.vec4('restXZGrad')
         ], function() {
-            this.$l.dist = pb.length(pb.sub(this.worldPos, ShaderHelper.getCameraPosition(this)));
-            this.$l.normalScale = pb.clamp(pb.div(100, this.dist), 0, 1);
-            this.$return(pb.mix(WATER_DISTANT_ROUGHNESS, WATER_BASE_ROUGHNESS, this.normalScale));
+            const slopeVar = that.unresolvedSlopeVariance(this, this.restXZGrad);
+            if (slopeVar) {
+                this.$l.slopeVar = slopeVar;
+                this.$l.alpha2 = pb.add(WATER_BASE_ROUGHNESS ** 4, pb.max(pb.add(this.slopeVar.x, this.slopeVar.y), 0));
+                this.$return(pb.sqrt(pb.sqrt(this.alpha2)));
+            } else {
+                this.$l.dist = pb.length(pb.sub(this.worldPos, ShaderHelper.getCameraPosition(this)));
+                this.$l.normalScale = pb.clamp(pb.div(100, this.dist), 0, 1);
+                this.$return(pb.mix(WATER_DISTANT_ROUGHNESS, WATER_BASE_ROUGHNESS, this.normalScale));
+            }
         });
-        return scope.waterRoughness(worldPos);
-    }
-    /**
-   * Where to sample the scene behind the water, and how far the light travelled
-   * through the medium to get there.
-   *
-   * Refracts the view ray by Snell's law, then marches that ray against the scene
-   * depth: at each step it projects the current point back to the screen, reads
-   * the depth there, and stops at the first point where the ray has passed into
-   * the geometry that pixel shows. The incidence angle, the depth of the receiver
-   * and the perspective foreshortening all fall out of that.
-   *
-   * Independent of the engine's depth convention: the projection only ever reads
-   * `clip.xy / clip.w`, every depth comparison happens in view space, and
-   * decoding the depth texture lives behind {@link ShaderHelper.sampleLinearDepth}.
-   *
-   * @param scope - Current shader scope
-   * @param worldPos - Surface point being shaded
-   * @param normal - Wave normal at that point, pointing up out of the water
-   * @param eyeVecNorm - Normalized direction from the camera to the surface
-   * @param screenUV - Screen UV of the surface point
-   * @param surfaceViewZ - View-space z of the surface point
-   * @param straightDepth01 - Normalized linear depth of the scene behind it
-   * @param straightWorldPos - Unrefracted scene world position behind the surface
-   * @param straightDist - Straight-line distance from the surface to that scene
-   * @returns `vec3(uv, pathLength)` - where to sample, and the medium path in meters
-   */ waterRefraction(scope, worldPos, normal, eyeVecNorm, screenUV, surfaceViewZ, straightDepth01, straightWorldPos, straightDist) {
+        return scope.waterRoughness(worldPos, restXZGrad);
+    }
+    /**
+   * Where to sample the scene behind the water, and the medium path length to it.
+   *
+   * Refracts the view ray by Snell's law and marches it against the scene depth.
+   * Depth-convention independent: projection only reads `clip.xy / clip.w` and
+   * all depth comparisons are in view space.
+   *
+   * @param scope - Current shader scope
+   * @param worldPos - Surface point being shaded
+   * @param normal - Wave normal at that point, pointing up out of the water
+   * @param eyeVecNorm - Normalized direction from the camera to the surface
+   * @param screenUV - Screen UV of the surface point
+   * @param surfaceViewZ - View-space z of the surface point
+   * @param straightDepth01 - Normalized linear depth of the scene behind it
+   * @param straightWorldPos - Unrefracted scene world position behind the surface
+   * @param straightDist - Straight-line distance from the surface to that scene
+   * @param underwater - Whether the eye is below the surface
+   * @returns `vec3(uv, pathLength)` - where to sample, and the medium path in meters,
+   * {@link BOTTOMLESS_PATH} with only sky behind the surface
+   */ waterRefraction(scope, worldPos, normal, eyeVecNorm, screenUV, surfaceViewZ, straightDepth01, straightWorldPos, straightDist, underwater) {
         const pb = scope.$builder;
         const march = this.refractionMode === 'march';
-        // Screen UV of a world position, through the same matrix the surface itself
-        // was rasterised with.
-        //
-        // Only ever used as a difference of two such UVs, which is what makes the
-        // offset independent of the conventions baked into that matrix: the TAA
-        // jitter and the clip-space Y orientation cancel between the two ends. The
-        // 0.5/0.5 mapping is the inverse of ShaderHelper.samplePositionFromDepth's.
+        // Only ever used as a difference of two UVs, so TAA jitter and clip-space Y
+        // orientation cancel. Inverse of ShaderHelper.samplePositionFromDepth's mapping.
         pb.func('waterRefractProjectUV', [
             pb.vec3('worldPos')
         ], function() {
             this.$l.h = pb.mul(ShaderHelper.getViewProjectionMatrix(this), pb.vec4(this.worldPos, 1));
             this.$return(pb.add(pb.mul(pb.div(this.h.xy, pb.max(this.h.w, 1e-6)), 0.5), pb.vec2(0.5)));
         });
-        // Where to sample the scene colour for a refracted ray that ended at
-        // `hitPos`, faded back to the straight-through sample at the screen border.
+        // Sample UV for a refracted ray ending at `hitPos`, faded to the straight
+        // sample at the screen border.
         pb.func('waterRefractUV', [
             pb.vec2('screenUV'),
             pb.vec2('uvBase'),
@@ -1417,22 +1316,14 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             pb.float('scale')
         ], function() {
             this.$l.uv = pb.add(this.screenUV, pb.mul(pb.sub(this.waterRefractProjectUV(this.hitPos), this.uvBase), this.scale));
-            // Off screen there is no scene colour to refract, and a clamped sample
-            // would smear one border pixel along the whole edge of the water.
             this.$l.edge = pb.min(pb.min(this.uv.x, pb.sub(1, this.uv.x)), pb.min(this.uv.y, pb.sub(1, this.uv.y)));
             this.$return(pb.mix(this.screenUV, this.uv, pb.clamp(pb.div(this.edge, REFRACT_EDGE_FADE), 0, 1)));
         });
-        // One step of the refracted-ray march.
-        //
-        // Projects the point `t` meters along the refracted ray to the screen, reads
-        // the depth there, and reports the signed gap between the ray and that pixel
-        // along the view axis: positive means the ray is still in front of the scene,
-        // negative that it has passed through it. The hit test itself belongs to the
-        // march.
-        //
         // Declared only in `march` mode: a dead function still forces the depth
-        // texture and the projection matrices into the bind group.
+        // texture and projection matrices into the bind group.
         if (march) {
+            // Returns (uv, rayViewZ - sceneViewZ) at `t` meters along the ray.
+            // Positive: ray still in front of the scene. Negative: passed through it.
             pb.func('waterRefractStep', [
                 pb.vec3('worldPos'),
                 pb.vec3('refractDir'),
@@ -1444,22 +1335,12 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             ], function() {
                 this.$l.uv = this.waterRefractUV(this.screenUV, this.uvBase, pb.add(this.worldPos, pb.mul(this.refractDir, this.t)), this.refractionScale);
                 this.$l.linearDepth = ShaderHelper.sampleLinearDepth(this, ShaderHelper.getLinearDepthTexture(this), this.uv, 0);
-                // View-space z of whatever that pixel shows. The comparison below is in
-                // view space, which the depth convention does not touch.
                 this.$l.sceneViewZ = pb.mul(pb.neg(this.linearDepth), this.cameraFar);
-                // Ray depth minus scene depth. Sky sits at the far plane, so over empty
-                // water the gap stays large and positive and the march simply runs on.
                 this.$return(pb.vec3(this.uv, pb.sub(this.rayViewZ, this.sceneViewZ)));
             });
-            // March the refracted ray and take the first crossing with the depth buffer.
-            //
-            // A hit is a step that lands inside a thickness band around the surface -
-            // the ray is neither clearly in front of the scene nor already out the far
-            // side. That two-sided test is what lets something poking out of the water
-            // fall through: its depth is *nearest* the camera, so the gap is negative
-            // from the first step and never enters the band. Stopping at the *first*
-            // hit keeps a submerged object solid; a later one belongs to whatever is
-            // behind it.
+            // First crossing of the refracted ray with the depth buffer. A hit is a
+            // step inside the thickness band or a sign change of the gap; an object
+            // poking out of the water is negative from the first step and never hits.
             pb.func('waterRefractMarch', [
                 pb.vec3('worldPos'),
                 pb.vec3('refractDir'),
@@ -1482,9 +1363,7 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
                     this.$l.s = this.waterRefractStep(this.worldPos, this.refractDir, this.screenUV, this.uvBase, this.rayViewZ, this.cameraFar, this.t);
                     this.$l.gap = this.s.z;
                     this.$if(pb.or(pb.lessThan(pb.abs(this.gap), REFRACT_MARCH_THICKNESS), pb.lessThan(pb.mul(this.gapPrev, this.gap), 0)), function() {
-                        // Within the band, or the gap flipped sign this step: the ray is at
-                        // the surface. Interpolate down to the exact crossing so the sample
-                        // sits on the object instead of a step behind it.
+                        // Interpolate to the exact crossing.
                         this.$l.k = pb.div(this.gapPrev, pb.sub(this.gapPrev, this.gap));
                         this.hitUV = this.s.xy;
                         this.hitPath = pb.mix(this.tPrev, this.t, this.k);
@@ -1494,8 +1373,6 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
                         this.gapPrev = this.gap;
                     });
                 });
-                // No hit on any step leaves the straight-through sample at the
-                // straight-line path, which is what a ray over empty water should show.
                 this.$return(pb.vec3(this.hitUV, this.hitPath));
             });
         }
@@ -1507,44 +1384,30 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             pb.float('surfaceViewZ'),
             pb.float('straightDepth01'),
             pb.vec3('straightWorldPos'),
-            pb.float('straightDist')
+            pb.float('straightDist'),
+            pb.bool('underwater')
         ], function() {
-            // Both faces are handled: looking down at the water the ray enters the
-            // medium, looking up from inside it the ray leaves. The surface is drawn
-            // with cullMode 'none' and the wave normal always points up, so the
-            // normal is faced back towards the eye and the ratio picked to match.
-            // Taken from `frontFacing`, since a flipped wave normal cannot tell an
-            // underside from an eye below the surface.
-            this.$l.underwater = pb.not(this.$builtins.frontFacing);
             this.$l.faceNormal = this.$choice(this.underwater, pb.neg(this.normal), this.normal);
             this.$l.eta = this.$choice(this.underwater, pb.float(WATER_TO_AIR_ETA), pb.float(AIR_TO_WATER_ETA));
-            // The unrefracted hit: the view line through the surface to whatever is
-            // behind it, which is what keeps the sample tracking the object rather
-            // than wandering across a silhouette.
             this.$l.uvBase = this.waterRefractProjectUV(this.worldPos);
-            // Sky behind the water (depth at the far plane) has no surface to refract
-            // towards, so the unrefracted sample is the correct one.
+            // Sky behind the water has no bottom. Its point lies on the far plane,
+            // so the straight distance falls to 0 where the surface crosses that
+            // plane and the water there would show the sky unabsorbed.
             this.$if(pb.greaterThanEqual(this.straightDepth01, SCENE_SKY_DEPTH01), function() {
-                this.$return(pb.vec3(this.screenUV, this.straightDist));
+                this.$return(pb.vec3(this.screenUV, SKY_MEDIUM_PATH));
             });
             this.$l.waterCrossDir = pb.normalize(pb.sub(this.straightWorldPos, this.worldPos));
-            // Refract the view ray twice - once through the wave normal, once through
-            // a flat surface of the same facing - and use only the difference, added
-            // to the view line. The result is the view line plus a wave-normal
-            // perturbation, so on calm water the sample stays put and only the wave
-            // tilt moves it. The flat normal carries the same facing flip as the wave
-            // one so the two cancel exactly on calm water from either side.
+            // refractDir = view line + (refract by wave normal - refract by flat
+            // normal), so calm water samples exactly the straight hit. The flat
+            // normal carries the same facing flip so the two cancel from either side.
             this.$l.refractWave = pb.refract(this.eyeVecNorm, this.faceNormal, this.eta);
             this.$l.refractFlatNormal = pb.vec3(0, pb.sign(this.faceNormal.y), 0);
             this.$l.refractFlat = pb.refract(this.eyeVecNorm, this.refractFlatNormal, this.eta);
-            // Total internal reflection - only reachable from under the surface -
-            // leaves refract returning zero, so degenerate to the view line.
+            // Total internal reflection makes refract return zero.
             this.$l.refractDir = pb.add(this.waterCrossDir, pb.sub(this.refractWave, this.refractFlat));
             this.$if(pb.lessThan(pb.length(pb.sub(this.refractWave, this.refractFlat)), 1e-4), function() {
                 this.refractDir = this.waterCrossDir;
             });
-            // A degenerate view line would push the direction below; clamp it to stay
-            // on the line if the difference vanished.
             this.$if(pb.lessThan(pb.dot(this.refractDir, this.refractDir), 1e-6), function() {
                 this.refractDir = this.waterCrossDir;
             });
@@ -1552,39 +1415,20 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             this.$l.refractUV = this.screenUV;
             this.$l.refractPath = this.straightDist;
             if (!march) {
-                // Cheap mode: step a fixed distance along the refracted direction and
-                // sample where that projects, with no search. `refractDir` is the view
-                // line plus a wave-normal perturbation, so with no waves this lands on
-                // the point behind the surface.
-                //
-                // The step length is a *fixed* depth scale, deliberately not the
-                // distance to what is behind the water: that distance jumps across an
-                // object's silhouette, and the larger offset outside the outline lands
-                // back on the object and paints a second copy of it. The price is that
-                // shallow and deep water refract by the same amount.
-                //
-                // The edge fade inside waterRefractUV still applies, so the sample
-                // cannot walk off screen.
+                // Fixed step, not the scene distance: that jumps across silhouettes
+                // and paints a second copy of the object.
                 this.refractUV = this.waterRefractUV(this.screenUV, this.uvBase, pb.add(this.worldPos, pb.mul(this.refractDir, this.cheapRefractionDepth)), this.refractionScale);
                 this.$return(pb.vec3(this.refractUV, this.refractPath));
             } else {
                 this.$l.refractDirView = pb.mul(ShaderHelper.getViewMatrix(this), pb.vec4(this.refractDir, 0)).xyz;
-                // Away from the camera the ray must travel, so a tangent one is clamped
-                // rather than allowed to shoot off, and the straight-line distance bounds
-                // the refracted path to a sane multiple of itself.
                 this.$l.refractStepZ = pb.min(this.refractDirView.z, -1e-4);
                 this.$l.maxPath = pb.mul(this.straightDist, REFRACT_MAX_PATH_RATIO);
                 this.$l.marchResult = this.waterRefractMarch(this.worldPos, this.refractDir, this.screenUV, this.uvBase, this.surfaceViewZ, this.refractStepZ, ShaderHelper.getCameraParams(this).y, this.maxPath, this.straightDist);
                 this.refractUV = this.marchResult.xy;
                 this.refractPath = pb.clamp(this.marchResult.z, 0, this.maxPath);
-                // Something sticking out of the water may occlude the refracted sample
-                // even though the march kept going. Reconstruct the scene point at the
-                // refracted UV and, if it sits above the surface, drop back to the
-                // straight-through sample rather than refracting the object.
-                this.$l.sceneHit = ShaderHelper.samplePositionFromDepth(this, ShaderHelper.getLinearDepthTexture(this), this.refractUV, ShaderHelper.getInvViewProjectionMatrix(this), ShaderHelper.getCameraParams(this).xy);
-                // Only a *finite* scene point above the surface is an object poking
-                // through - the sky's reconstructed point also sits high, but there is
-                // nothing to reject then.
+                // A finite scene point above the surface at the refracted UV is an
+                // object poking through: fall back to the straight sample.
+                this.$l.sceneHit = ShaderHelper.samplePositionFromDepth(this, ShaderHelper.getLinearDepthTexture(this), this.refractUV, ShaderHelper.getJitteredInvVPMatrix(this), ShaderHelper.getCameraParams(this).xy);
                 this.$if(pb.and(pb.lessThan(this.sceneHit.w, 0.999), pb.greaterThan(this.sceneHit.y, this.worldPos.y)), function() {
                     this.refractUV = this.screenUV;
                     this.refractPath = this.straightDist;
@@ -1592,46 +1436,32 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
                 this.$return(pb.vec3(this.refractUV, this.refractPath));
             }
         });
-        return scope.waterRefraction(worldPos, normal, eyeVecNorm, screenUV, surfaceViewZ, straightDepth01, straightWorldPos, straightDist);
-    }
-    /**
-   * Sunlight scattered out of the water column towards the eye.
-   *
-   * Closed-form single scattering, not a ray march. The medium is homogeneous
-   * and the two paths through it are straight lines of fixed slope, so the
-   * integral along the view ray has an elementary solution and costs one `exp`.
-   *
-   * Take `t` as distance along the refracted view ray from the surface, `d` as
-   * its total length in the water, and `vy`/`sy` as how fast the view and sun
-   * rays descend. A scattering event at `t` sits `t * vy` below the surface, so
-   * the sun reached it over `t * vy / sy` and the scattered light returns over
-   * `t`. Writing `r = vy / sy`:
-   *
-   * ```
-   * S = integral(0..d) sigma_s * p * E * exp(-sigma_t * t * (1 + r)) dt
-   *   = albedo * p * E * (1 - exp(-sigma_t * (1 + r) * d)) / (1 + r)
-   * ```
-   *
-   * `sigma_t` cancels out of everything but the exponent, which leaves the
-   * result finite for an unbounded column: looking straight down at deep water
-   * under an overhead sun gives `albedo * p * E / 2`, the textbook value.
-   *
-   * `E` is the sun's irradiance perpendicular to its own beam; there is no `NoL`
-   * here, because the geometry the cosine would describe is already in `r`. Both
-   * directions are refracted through a flat surface first.
-   *
-   * Only the entry Fresnel is applied here. The exit transmission is common to
-   * every term leaving the medium and is applied once by the caller.
-   *
-   * Assumes the eye is above the surface; the caller gates on that.
-   *
-   * @param scope - Current shader scope.
-   * @param lightEnergy - Sun irradiance perpendicular to the beam, after shadowing.
-   * @param lightDir - Unit vector from the surface towards the light.
-   * @param eyeVecNorm - Unit vector from the camera towards the surface.
-   * @param NoL - Cosine of the sun's incidence on the wave normal.
-   * @param depth - Refracted path length through the medium, in meters.
-   * @returns Radiance scattered towards the eye, before the exit Fresnel.
+        return scope.waterRefraction(worldPos, normal, eyeVecNorm, screenUV, surfaceViewZ, straightDepth01, straightWorldPos, straightDist, underwater);
+    }
+    /**
+   * Sunlight scattered out of the water column towards the eye. Closed-form
+   * single scattering in a homogeneous medium.
+   *
+   * With `t` the distance along the refracted view ray, `d` its length in the
+   * water, `vy`/`sy` the descent rates of the view and sun rays, and
+   * `r = vy / sy`:
+   *
+   * ```
+   * S = integral(0..d) sigma_s * p * E * exp(-sigma_t * t * (1 + r)) dt
+   *   = albedo * p * E * (1 - exp(-sigma_t * (1 + r) * d)) / (1 + r)
+   * ```
+   *
+   * No `NoL` factor: that geometry is already in `r`. Only the entry Fresnel is
+   * applied; the exit transmission is applied once by the caller. Assumes the
+   * eye is above the surface.
+   *
+   * @param scope - Current shader scope.
+   * @param lightEnergy - Sun irradiance perpendicular to the beam, after shadowing.
+   * @param lightDir - Unit vector from the surface towards the light.
+   * @param eyeVecNorm - Unit vector from the camera towards the surface.
+   * @param NoL - Cosine of the sun's incidence on the wave normal.
+   * @param depth - Refracted path length through the medium, in meters.
+   * @returns Radiance scattered towards the eye, before the exit Fresnel.
    */ waterSunScattering(scope, lightEnergy, lightDir, eyeVecNorm, NoL, depth, foam) {
         const pb = scope.$builder;
         pb.func('waterSunScattering', [
@@ -1643,117 +1473,85 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             pb.float('foam')
         ], function() {
             this.$l.up = pb.vec3(0, 1, 0);
-            // Both directions as they travel inside the water. The sun's incident
-            // direction is where it travels to, the opposite of `lightDir`.
+            // Directions inside the water. The sun travels opposite to `lightDir`.
             this.$l.Lw = pb.refract(pb.neg(this.lightDir), this.up, AIR_TO_WATER_ETA);
             this.$l.Vw = pb.refract(this.eyeVecNorm, this.up, AIR_TO_WATER_ETA);
-            // How fast each descends. The sun is floored rather than allowed to
-            // reach zero: a sun on the horizon lights the column over an unbounded
-            // path, which single scattering cannot represent.
             this.$l.sy = pb.max(pb.neg(this.Lw.y), MIN_SUN_SLOPE);
             this.$l.vy = pb.max(pb.neg(this.Vw.y), 1e-3);
             this.$l.r = pb.div(this.vy, this.sy);
             this.$l.rr = pb.add(1, this.r);
-            // Angle between the sun's travel and the direction the light has to
-            // leave in to reach the eye, which is back along the view ray.
             this.$l.cosTheta = pb.neg(pb.dot(this.Lw, this.Vw));
             this.$l.hg = waterScatterPhase(this, this.cosTheta, this.sunScatterParams.y);
-            // Multiple scattering washes the lobe out: an optically thick column has
-            // scattered the light enough times that the direction it entered by no
-            // longer matters. Weighted on luminance and shared across channels,
-            // because the phase does not depend on wavelength - only how far the
-            // light got does.
+            // Blend towards isotropic with optical thickness (multiple scattering).
+            // Luminance-weighted: the phase is wavelength independent.
             this.$l.lumWeights = pb.vec3(0.2126, 0.7152, 0.0722);
             this.$l.extLum = pb.dot(this.mediumExtinction, this.lumWeights);
             this.$l.albedoLum = pb.dot(this.mediumAlbedo, this.lumWeights);
             this.$l.thickness = pb.mul(this.albedoLum, pb.sub(1, pb.exp(pb.neg(pb.mul(this.extLum, this.depth)))));
             this.$l.phase = pb.mix(this.hg, 1 / (4 * Math.PI), pb.smoothStep(0, 0.5, pb.clamp(this.thickness, 0, 1)));
-            // The integral itself. Per channel, since sigma_t is.
             this.$l.k = pb.mul(this.mediumExtinction, this.rr);
             this.$l.integral = pb.div(pb.sub(pb.vec3(1), pb.exp(pb.neg(pb.mul(this.k, this.depth)))), this.rr);
-            // Entry Fresnel: what the surface let through on the way in. This is
-            // also what keeps the term off a backlit crest - at NoL <= 0 no light
-            // enters the top face at all, and the subsurface term owns that case.
+            // Entry Fresnel. Zero at NoL <= 0, where the subsurface term takes over.
+            // Foam is a mass of bubbles, not a mirror, so it blends towards full
+            // transmission.
             this.$l.entry = pb.sub(1, pb.add(WATER_F0, pb.mul(1 - WATER_F0, pb.pow(pb.sub(1, this.NoL), 5))));
-            // The flat-interface Fresnel goes to zero at grazing incidence, which is
-            // right for smooth water and wrong for a fold - a mass of bubbles, not a
-            // mirror. Blended towards full transmission by the foam coverage, so a
-            // breaking crest lights its own column. Weighted, not replaced: a thin
-            // scattering layer still attenuates.
             this.$l.entry = pb.mix(this.entry, pb.float(1), this.foam);
             this.$return(pb.mul(this.mediumAlbedo, this.lightEnergy, this.integral, pb.mul(this.phase, this.entry, this.sunScatterParams.x)));
         });
         return scope.waterSunScattering(lightEnergy, lightDir, eyeVecNorm, NoL, depth, foam);
     }
-    waterShading(scope, worldPos, worldNormal, foamFactor) {
+    waterShading(scope, worldPos, worldNormal, foamFactor, crestHeight, restXZ, restXZGrad, foamSample, coverage, sheetThickness, wallFoam, scenePos, groundFoamDensity, groundFoamSample, groundNormal, groundFoamWeight) {
         const pb = scope.$builder;
         const that = this;
-        const ramp = this.mediumMode === 'ramp';
-        const shoreFoam = this._shoreFoamAvailable(scope);
         const debugOutput = this.debugOutput;
-        // Transmittance of the medium over `depth` meters of path.
+        const hasGroundFoam = !!(this._shoreWaveGenerator && this._foamFieldGenerator);
+        // The environment's prefiltered radiance, for the distant sky reflection
+        const envLight = this.needCalculateEnvLight() ? this.drawContext.env?.light.envLight ?? null : null;
+        // Transmittance over `depth` meters of path.
         pb.func('getAbsorption', [
             pb.float('depth')
         ], function() {
-            if (ramp) {
-                this.$l.c = pb.textureSampleLevel(this.absorptionRampTex, pb.vec2(pb.mul(this.depth, this.depthMulti), 0.5), 0).rgb;
-                this.$return(pb.mul(this.c, this.c));
-            } else {
-                this.$return(pb.exp(pb.neg(pb.mul(this.mediumExtinction, this.depth))));
-            }
+            this.$return(pb.exp(pb.neg(pb.mul(this.mediumExtinction, this.depth))));
         });
-        // Radiance scattered back out of the medium over `depth` meters of path,
-        // as a fraction of the incident irradiance.
+        // Fraction of incident irradiance scattered back over `depth` meters of path.
         pb.func('getScattering', [
             pb.float('depth')
         ], function() {
-            if (ramp) {
-                this.$l.c = pb.textureSampleLevel(this.scatterRampTex, pb.vec2(pb.mul(this.depth, this.depthMulti), 0.5), 0).rgb;
-                this.$return(pb.mul(this.c, this.c));
-            } else {
-                // Single-scattering: the albedo weighs how much of the extinguished
-                // energy comes back rather than being absorbed.
-                this.$return(pb.mul(this.mediumAlbedo, pb.sub(pb.vec3(1), pb.exp(pb.neg(pb.mul(this.mediumExtinction, this.depth))))));
-            }
+            this.$return(pb.mul(this.mediumAlbedo, pb.sub(pb.vec3(1), pb.exp(pb.neg(pb.mul(this.mediumExtinction, this.depth))))));
+        });
+        // Mean Fresnel over a Gaussian distribution of unresolved slopes of standard
+        // deviation `sigmaV` along the view direction, Bruneton, Neyret & Holzschuch,
+        // "Real-time Realistic Ocean Lighting using Seamless Transitions from Geometry
+        // to BRDF" (Eurographics 2010), as their ocean demo fits it:
+        // (1 - cos)^(5 exp(-2.69 sigma)) / (1 + 22.7 sigma^1.5), Schlick at sigma = 0.
+        pb.func('meanFresnel', [
+            pb.float('cosThetaV'),
+            pb.float('sigmaV')
+        ], function() {
+            this.$return(pb.div(pb.pow(pb.sub(1, this.cosThetaV), pb.mul(5, pb.exp(pb.mul(-2.69, this.sigmaV)))), pb.add(1, pb.mul(22.7, pb.pow(this.sigmaV, 1.5)))));
         });
         pb.func('fresnel', [
             pb.vec3('normal'),
             pb.vec3('eyeVec'),
-            pb.bool('underwater')
+            pb.bool('underwater'),
+            pb.float('sigmaV')
         ], function() {
-            // The magnitude of the cosine: it changes sign when the view direction
-            // crosses the normal, which a folded crest makes happen inside a single
-            // wave. Clamping at zero instead drops the reflectance to F0 exactly where
-            // the geometry is at its most grazing, giving a black band across the
-            // crest.
+            // abs, not clamp: a folded crest flips the sign inside one wave, and a
+            // clamp would drop to F0 exactly at the most grazing geometry.
             this.$l.NoV = pb.clamp(pb.abs(pb.dot(this.normal, this.eyeVec)), 0, 1);
-            // Looking up at the underside, the interface behaves quite differently.
-            // Past the critical angle - about 48.6 degrees off vertical for n = 1.333 -
-            // Snell's law has no solution and nothing gets out at all: the surface is
-            // a perfect mirror there, and the circle of sky inside that angle is the
-            // Snell window.
             this.$if(this.underwater, function() {
                 this.$l.sinT2 = pb.mul(WATER_TO_AIR_ETA * WATER_TO_AIR_ETA, pb.sub(1, pb.mul(this.NoV, this.NoV)));
-                // Total internal reflection, and deliberately not scaled by
-                // reflectionStrength. That knob exists to trade an above-water
-                // reflection away for a view of the sea bed beneath it; from below there
-                // is no transmitted ray to reveal, and dialling the mirror down there
-                // just bleeds the straight-through sample - the world above the water -
-                // across the whole surface outside the window, where physically nothing
-                // is visible at all.
+                // Total internal reflection outside the Snell window. Not scaled by
+                // reflectionStrength: there is no transmitted ray to reveal.
                 this.$l.f = pb.float(1);
                 this.$if(pb.lessThan(this.sinT2, 1), function() {
-                    // Schlick is written against the angle on the less dense side of the
-                    // interface, so the transmitted cosine is what goes in rather than the
-                    // incident one. F0 itself is unchanged: ((n1-n2)/(n1+n2))^2 is
-                    // symmetric in the two media.
+                    // Schlick takes the cosine on the less dense side. F0 is symmetric.
                     this.$l.cosT = pb.sqrt(pb.max(pb.sub(1, this.sinT2), 0));
                     this.f = pb.clamp(pb.mul(pb.add(WATER_F0, pb.mul(1 - WATER_F0, pb.pow(pb.sub(1, this.cosT), 5))), this.reflectionStrength), 0, 1);
                 });
                 this.$return(this.f);
             });
-            this.$l.f = pb.add(WATER_F0, pb.mul(1 - WATER_F0, pb.pow(pb.sub(1, this.NoV), 5)));
-            // Scaling keeps the term in [0,1] for any authored reflectionStrength.
+            this.$l.f = pb.add(WATER_F0, pb.mul(1 - WATER_F0, this.meanFresnel(this.NoV, this.sigmaV)));
             this.$return(pb.clamp(pb.mul(this.f, this.reflectionStrength), 0, 1));
         });
         pb.func('lightSpecular', [
@@ -1782,252 +1580,79 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             });
             this.$return(this.specular);
         });
-        if (shoreFoam) {
-            // Three octaves of value noise over the world XZ plane, drifting slowly.
-            // World space rather than screen or surface space, so the pattern does not
-            // slide over the band as the camera moves.
-            pb.func('waterShoreFoamPattern', [
-                pb.vec2('xz'),
-                pb.float('time')
-            ], function() {
-                // Drift applied in meters before the frequency, so changing the clump
-                // size does not change how fast they travel.
-                this.$l.p = pb.mul(pb.add(this.xz, pb.mul(pb.vec2(SHORE_FOAM_DRIFT_X, SHORE_FOAM_DRIFT_Z), this.time)), this.shoreFoamParams.w);
-                this.$return(pb.add(pb.mul(valueNoise(this, this.p), SHORE_FOAM_OCTAVE_WEIGHTS[0]), // Offset as well as scaled: octaves sharing a lattice line their
-                // features up at the cell corners.
-                pb.mul(valueNoise(this, pb.add(pb.mul(this.p, SHORE_FOAM_OCTAVE_RATIO), pb.vec2(13.7, 7.3))), SHORE_FOAM_OCTAVE_WEIGHTS[1]), pb.mul(valueNoise(this, pb.add(pb.mul(this.p, SHORE_FOAM_OCTAVE_RATIO * SHORE_FOAM_OCTAVE_RATIO), pb.vec2(5.1, 29.3))), SHORE_FOAM_OCTAVE_WEIGHTS[2])));
-            });
-            // Distance from the water surface to the nearest opaque surface anywhere
-            // around it, through the Hi-Z pyramid's nearest-depth channel.
-            //
-            // A *neighbourhood* query rather than a lookup along the view ray. Beside
-            // a piling the ray hits its side just under the waterline, so a pixel far
-            // from the piling reads as touching it while the closer pixels to its left
-            // and right see past it entirely - the geometry those pixels need is not
-            // on their ray at all.
-            //
-            // The pyramid is what makes the neighbourhood affordable: one cell at the
-            // right level summarises the whole footprint, so the sample count does not
-            // grow with the radius, and the nearest-depth reduction means a cell the
-            // query covers cannot hide geometry from it.
-            //
-            // Reports a distance past the band's reach when the neighbourhood is
-            // empty, so the caller's ramp reads it as "outside the band" without a
-            // separate miss flag.
-            pb.func('waterShoreProximity', [
-                pb.vec3('viewPos'),
-                pb.vec2('screenUV'),
-                pb.float('radius')
-            ], function() {
-                this.$l.renderSize = ShaderHelper.getRenderSize(this);
-                this.$l.projMatrix = ShaderHelper.getProjectionMatrix(this);
-                // Screen radius, in pixels, of a sphere of `radius` metres at this
-                // depth. proj[0].x is the horizontal projection scale, and the NDC
-                // half-extent maps onto half the render width.
-                this.$l.viewDist = pb.max(pb.neg(this.viewPos.z), 1e-4);
-                this.$l.pixelRadius = pb.mul(pb.div(pb.mul(this.radius, this.projMatrix[0].x), this.viewDist), 0.5, this.renderSize.x);
-                // Level whose texel spans the query footprint divided by the tap
-                // spread, so the 3x3 grid covers roughly the whole sphere. Floored to
-                // an integer: the pyramid is sampled with a nearest mip filter, and a
-                // fractional level would show up as a seam across the band.
-                this.$l.level = pb.clamp(pb.floor(pb.log2(pb.max(pb.div(this.pixelRadius, SHORE_QUERY_TAP_SPREAD), 1))), 0, pb.sub(pb.float(ShaderHelper.getHiZDepthTextureMipLevelCount(this)), 1));
-                this.$l.mipSize = pb.max(pb.floor(pb.div(this.renderSize, pb.exp2(this.level))), pb.vec2(1));
-                this.$l.texelStep = pb.div(pb.vec2(1), this.mipSize);
-                // Every cell in a 4x4 window contributes, weighted by a tent reaching
-                // zero at the window's edge, and each is read as a point dithered
-                // somewhere inside it.
-                //
-                // The tent makes the window's own stepping invisible: the column of
-                // cells leaving and the one arriving both have zero weight there. The
-                // pyramid is bound with a nearest sampler - SSR's traversal needs exact
-                // cell values - so this smoothing has to happen here.
-                //
-                // The dither keeps the contours round. A cell is a box, and the
-                // distance to a box has square contours; at these levels a cell is most
-                // of the radius across, so what is left is a grid of squares. Picking a
-                // point inside the cell is what the cell's own statement licenses.
-                //
-                // Hashed from the pixel *and* the frame counter, and applied to the
-                // interpretation of the samples rather than to which samples are
-                // taken: the fetches stay identical frame to frame while the guess
-                // moves, which is what lets TAA average the residual grain away.
-                this.$l.dither = pb.mul(pb.float(ShaderHelper.getFramestamp(this)), SHORE_QUERY_DITHER_STRIDE);
-                this.$l.gridCoord = pb.sub(pb.mul(this.screenUV, this.mipSize), pb.vec2(0.5));
-                this.$l.gridBase = pb.floor(this.gridCoord);
-                this.$l.gridFrac = pb.sub(this.gridCoord, this.gridBase);
-                // Softness of the minimum below, and the distance a neighbourhood with
-                // nothing in it resolves to. Both scale with the radius, so the query
-                // behaves the same whatever the band is set to.
-                this.$l.softK = pb.mul(this.radius, SHORE_QUERY_SOFTMIN);
-                this.$l.dMax = pb.mul(this.radius, SHORE_QUERY_MISS_REACH);
-                this.$l.esum = pb.float(0);
-                this.$l.wsum = pb.float(0);
-                for(let gy = 0; gy < 4; gy++){
-                    for(let gx = 0; gx < 4; gx++){
-                        this.$l[`uv${gx}${gy}`] = pb.mul(pb.add(this.gridBase, pb.vec2(gx - 1 + 0.5, gy - 1 + 0.5)), this.texelStep);
-                        this.$l[`hiz${gx}${gy}`] = pb.textureSampleLevel(ShaderHelper.getHiZDepthTexture(this), this[`uv${gx}${gy}`], this.level);
-                        this.$l[`z${gx}${gy}`] = ShaderHelper.nonLinearDepthToLinear(this, this[`hiz${gx}${gy}`].g);
-                        this.$l[`zFar${gx}${gy}`] = ShaderHelper.nonLinearDepthToLinear(this, this[`hiz${gx}${gy}`].r);
-                        // A cell says "some surface lies inside this screen rectangle, at
-                        // a depth between near and far" - a frustum block. Collapsing that
-                        // to the point on the centre ray at the near depth puts a cell
-                        // straddling a silhouette beside the object in empty space, nearer
-                        // to the water than the object itself.
-                        //
-                        // Laterally the point is dithered across the cell instead, which
-                        // invents nothing: any spot in the cell is somewhere the surface
-                        // could be. In depth it is clamped, because the reduction
-                        // guarantees a surface on the near face, and the span is clipped by
-                        // SHORE_QUERY_CELL_DEPTH_SPAN.
-                        this.$l[`cellW${gx}${gy}`] = pb.max(pb.div(pb.mul(this.texelStep.x, 2, this[`z${gx}${gy}`]), this.projMatrix[0].x), 1e-6);
-                        this.$l[`zBack${gx}${gy}`] = pb.min(this[`zFar${gx}${gy}`], pb.add(this[`z${gx}${gy}`], pb.mul(this[`cellW${gx}${gy}`], SHORE_QUERY_CELL_DEPTH_SPAN)));
-                        // How far outside the block's depth range the water pixel sits.
-                        // Zero while it is between the two faces.
-                        this.$l[`zClamp${gx}${gy}`] = pb.clamp(pb.neg(this.viewPos.z), this[`z${gx}${gy}`], this[`zBack${gx}${gy}`]);
-                        this.$l[`dz${gx}${gy}`] = pb.add(this.viewPos.z, this[`zClamp${gx}${gy}`]);
-                        // Seeded per cell as well as per pixel: one offset shared by all
-                        // sixteen would move the whole set together.
-                        this.$l[`jit${gx}${gy}`] = pb.sub(pb.vec2(interleavedGradientNoise(this, pb.add(this.$builtins.fragCoord.xy, pb.vec2(pb.add(this.dither, gx * 7.13 + 0.5), pb.add(this.dither, gy * 3.71 + 0.5)))), interleavedGradientNoise(this, pb.add(this.$builtins.fragCoord.xy, pb.vec2(pb.add(this.dither, gy * 3.71 + 37), pb.add(this.dither, gx * 7.13 + 17))))), pb.vec2(0.5));
-                        this.$l[`guessNDC${gx}${gy}`] = pb.sub(pb.mul(pb.add(this[`uv${gx}${gy}`], pb.mul(this[`jit${gx}${gy}`], this.texelStep)), 2), pb.vec2(1));
-                        this.$l[`guess${gx}${gy}`] = pb.div(pb.mul(this[`guessNDC${gx}${gy}`], this[`zClamp${gx}${gy}`]), pb.vec2(this.projMatrix[0].x, this.projMatrix[1].y));
-                        this.$l[`dxy${gx}${gy}`] = pb.sub(this.viewPos.xy, this[`guess${gx}${gy}`]);
-                        this.$l[`d${gx}${gy}`] = pb.length(pb.vec3(this[`dxy${gx}${gy}`], this[`dz${gx}${gy}`]));
-                        // Tent weight, from the cell's offset to the pixel in cell units.
-                        // Zero at two cells out, which is the edge of the 4x4 window, so a
-                        // cell entering or leaving the window does so from nothing.
-                        this.$l[`w${gx}${gy}`] = pb.mul(pb.max(pb.sub(1, pb.abs(pb.div(pb.sub(pb.float(gx - 1), this.gridFrac.x), 2))), 0), pb.max(pb.sub(1, pb.abs(pb.div(pb.sub(pb.float(gy - 1), this.gridFrac.y), 2))), 0));
-                        this.wsum = pb.add(this.wsum, this[`w${gx}${gy}`]);
-                        this.esum = pb.add(this.esum, pb.mul(this[`w${gx}${gy}`], pb.exp(pb.neg(pb.div(pb.min(this[`d${gx}${gy}`], this.dMax), this.softK)))));
-                    }
-                }
-                // Weighted soft minimum, not a hard one. A hard `min` lets one cell
-                // decide the answer outright, so the band comes out in squares that
-                // step on cell boundaries. Averaging lets a cell losing its claim cost
-                // only its share and lets the dither average down. It still reads as a
-                // distance: below a few times `softK` it tracks the true minimum
-                // closely.
-                this.$return(pb.mul(pb.neg(this.softK), pb.log(pb.div(this.esum, this.wsum))));
-            });
-            // Coverage of the foam that collects where the water meets a surface, and
-            // how far that surface is, as (coverage, distance).
-            pb.func('waterShoreFoam', [
-                pb.vec3('worldPos'),
-                pb.vec3('viewPos'),
-                pb.vec2('screenUV')
-            ], function() {
-                this.$l.time = ShaderHelper.getElapsedTime(this);
-                // Queried at the band's widest reach rather than its current one, so the
-                // run-up below moves the edge without moving the mip level under it -
-                // which would step the whole band's resolution once a cycle.
-                this.$l.surfaceDist = this.waterShoreProximity(this.viewPos, this.screenUV, this.shoreFoamWashParams.w);
-                // Where the band currently reaches out to, modulated over time by the
-                // run-up. The phase offset comes from a noise field over the world plane
-                // rather than from a direction: the query does not know where the shore
-                // runs, and a guessed axis reads as a diagonal swell crossing the beach.
-                this.$l.washOffset = valueNoise(this, pb.mul(this.worldPos.xz, this.shoreFoamWashParams.z));
-                this.$l.wash = pb.sin(pb.mul(pb.add(pb.mul(this.time, this.shoreFoamWashParams.y), this.washOffset), 2 * Math.PI));
-                this.$l.edge = pb.max(pb.mul(this.shoreFoamParams.y, pb.add(1, pb.mul(this.shoreFoamWashParams.x, this.wash))), 0);
-                this.$l.soft = pb.max(pb.mul(this.edge, SHORE_FOAM_EDGE_SOFTNESS), 1e-4);
-                // The gradient runs *up to* the reach, not across it: `edge` is where the
-                // band ends, so coverage must be zero there. Straddling `edge` would put
-                // a total miss at the middle of the ramp, which is half coverage over the
-                // entire open sea.
-                this.$l.ramp = pb.sub(1, pb.smoothStep(pb.sub(this.edge, this.soft), this.edge, this.surfaceDist));
-                // Open water, which is almost every water pixel in almost every frame,
-                // is done here and does not pay for the pattern.
-                this.$if(pb.lessThanEqual(this.ramp, 0), function() {
-                    this.$return(pb.vec2(0, this.surfaceDist));
-                });
-                this.$l.pattern = this.waterShoreFoamPattern(this.worldPos.xz, this.time);
-                this.$l.coverage = pb.clamp(pb.div(pb.sub(this.ramp, pb.mul(this.pattern, SHORE_FOAM_NOISE_BITE)), 1 - SHORE_FOAM_NOISE_BITE), 0, 1);
-                this.$return(pb.vec2(pb.clamp(pb.mul(pb.pow(this.coverage, this.shoreFoamParams.z), this.shoreFoamParams.x), 0, 1), this.surfaceDist));
-            });
-        }
+        // White foam revealed from a foam texture sample (value, slopes along x
+        // and z) by a density, Crest's feathered black point; as (white foam, its
+        // slope along x, along z).
+        pb.func('waterWhiteFoam', [
+            pb.float('density'),
+            pb.vec3('tex'),
+            pb.float('feather')
+        ], function() {
+            this.$l.t = pb.clamp(pb.div(pb.sub(this.tex.x, pb.sub(1, pb.clamp(this.density, 0, 1))), this.feather), 0, 1);
+            this.$return(pb.vec3(pb.mul(this.t, this.t, pb.sub(3, pb.mul(this.t, 2))), pb.mul(this.tex.yz, pb.div(pb.mul(6, this.t, pb.sub(1, this.t)), this.feather))));
+        });
         pb.func('waterShading', [
             pb.vec3('worldPos'),
             pb.vec3('worldNormal'),
-            pb.float('foamFactor')
+            pb.float('foamFactor'),
+            pb.float('crestHeight'),
+            pb.vec2('restXZ'),
+            pb.vec4('restXZGrad'),
+            pb.vec3('foamSample'),
+            pb.float('coverage'),
+            pb.float('sheetThickness'),
+            pb.float('wallFoam'),
+            pb.vec4('scenePos'),
+            pb.float('groundFoamDensity'),
+            pb.vec3('groundFoamSample'),
+            pb.vec3('groundNormal'),
+            pb.float('groundFoamWeight')
         ], function() {
             this.$l.screenUV = pb.div(pb.vec2(this.$builtins.fragCoord.xy), ShaderHelper.getRenderSize(this));
             this.$l.dist = pb.length(pb.sub(this.worldPos, ShaderHelper.getCameraPosition(this)));
-            this.$l.normalScale = pb.clamp(pb.div(100, this.dist), 0, 1);
-            this.$l.normal = pb.normalize(pb.mul(this.worldNormal, pb.vec3(this.normalScale, 1, this.normalScale)));
-            this.$l.roughness = that.waterRoughness(this, this.worldPos);
-            this.$l.wPos = ShaderHelper.samplePositionFromDepth(this, ShaderHelper.getLinearDepthTexture(this), this.screenUV, ShaderHelper.getInvViewProjectionMatrix(this), ShaderHelper.getCameraParams(this).xy);
+            const slopeVar = that.unresolvedSlopeVariance(this, this.restXZGrad);
+            if (slopeVar) {
+                // The generator has already faded the slopes too fine for the pixel
+                this.$l.slopeVar = slopeVar;
+                this.$l.normal = pb.normalize(this.worldNormal);
+            } else {
+                this.$l.normalScale = pb.clamp(pb.div(100, this.dist), 0, 1);
+                this.$l.normal = pb.normalize(pb.mul(this.worldNormal, pb.vec3(this.normalScale, 1, this.normalScale)));
+            }
+            this.$l.roughness = that.waterRoughness(this, this.worldPos, this.restXZGrad);
+            this.$l.wPos = this.scenePos;
             this.$l.eyeVec = pb.sub(this.worldPos.xyz, ShaderHelper.getCameraPosition(this));
             this.$l.eyeVecNorm = pb.normalize(this.eyeVec);
-            // The normal the mirror-like terms use - Fresnel, the reflection vector,
-            // the specular lobe - turned towards the eye where the surface has
-            // folded far enough to show its underside.
-            //
-            // Flipped on the sign of the cosine against the view direction, not on
-            // `frontFacing`: the rasteriser's answer changes discontinuously along
-            // the triangle edge where the fold happens, so the flipped normal jumps
-            // by 2*N there and every term built on it steps with it. The cosine
-            // crosses zero continuously.
-            //
-            // `eyeVecNorm` runs from the camera to the surface, so a face turned
-            // towards the eye has a *negative* dot against it and the flip is the
-            // positive case.
+            // Mirror-term normal, turned towards the eye on a folded underside.
+            // Flipped on the cosine, not on `frontFacing`, which is discontinuous
+            // along the fold's triangle edge. `eyeVecNorm` points camera -> surface,
+            // so the flip case is the positive dot.
             this.$l.shadingNormal = this.$choice(pb.greaterThan(pb.dot(this.normal, this.eyeVecNorm), 0), pb.neg(this.normal), this.normal);
-            // The normal the diffuse terms use, which is not the wave normal.
-            //
-            // Where a choppy displacement folds the surface the cross-product normal
-            // is genuinely close to horizontal. That is the right normal for the
-            // mirror - the specular lobe and the refraction go by the face's true
-            // orientation - and the wrong one for anything lit diffusely: the sun is
-            // nearly perpendicular to a folded wall, so a diffuse term built on it
-            // loses the sun completely.
-            //
-            // Built on the eye-facing normal and then mixed towards up, so the two
-            // corrections compose. The weight rises with |normal.y|: at |y| = 1 the
-            // wave normal is kept exactly, and as the face tips over the up vector
-            // takes it back. A smoothstep rather than |normal.y| itself, which would
-            // stay dominated by the wall normal exactly where it is least wanted.
-            this.$l.diffuseWeight = pb.smoothStep(0, 0.5, pb.abs(this.normal.y));
-            this.$l.diffuseNormal = pb.normalize(pb.mix(pb.vec3(0, 1, 0), this.shadingNormal, this.diffuseWeight));
-            // Which face of the surface the camera is on. Taken from the rasteriser,
-            // not from the wave normal: the choppy displacement folds the sheet, so
-            // the pixels showing its underside also carry an upward normal, and a
-            // test built on the normal would put every term on the wrong side of the
-            // interface there.
-            this.$l.frontFace = this.$builtins.frontFacing;
-            this.$l.backFace = pb.not(this.frontFace);
-            this.$l.underwaterEye = this.backFace;
+            // Diffuse-term normal, from the unflipped wave normal (the eye-facing
+            // flip would point it into the lower hemisphere on any steep back
+            // slope), mixed towards up as normal.y falls.
+            this.$l.diffuseWeight = pb.smoothStep(0, 0.5, this.normal.y);
+            this.$l.diffuseNormal = pb.normalize(pb.mix(pb.vec3(0, 1, 0), this.normal, this.diffuseWeight));
+            // Eye below the rest plane, not `!frontFacing`: a choppy fold (J < 0)
+            // flips the winding and would read as seen from below.
+            this.$l.restLevel = pb.sub(this.worldPos.y, this.crestHeight);
+            this.$l.underwaterEye = pb.or(pb.lessThan(this.eyeSide, 0), pb.and(pb.equal(this.eyeSide, 0), pb.lessThan(ShaderHelper.getCameraPosition(this).y, this.restLevel)));
             this.$l.depth = pb.length(pb.sub(this.wPos.xyz, this.worldPos));
             this.$l.viewPos = pb.mul(ShaderHelper.getViewMatrix(this), pb.vec4(this.worldPos, 1)).xyz;
             this.incidentVec = pb.normalize(pb.sub(this.worldPos, ShaderHelper.getCameraPosition(this)));
             this.reflectVecW = pb.reflect(this.incidentVec, this.shadingNormal);
             this.$l.reflectance = pb.vec3();
             this.$l.hitInfo = pb.vec4(0);
-            // Which way a reflection has to go to have anything to hit. From above
-            // that is upwards, off the surface into the sky; from below it is
-            // downwards, back into the water. Testing for "up" regardless meant a
-            // submerged pixel never traced at all and fell through to the sky bake,
-            // which is the one thing that cannot be behind a surface seen from
-            // underneath.
+            // Trace only rays leaving the surface: up from above, down from below.
             this.$if(this.$choice(this.underwaterEye, pb.lessThan(this.reflectVecW.y, 0), pb.greaterThan(this.reflectVecW.y, 0)), function() {
                 this.reflectVec = pb.mul(ShaderHelper.getViewMatrix(this), pb.vec4(this.reflectVecW, 0)).xyz;
                 this.hitInfo = ShaderHelper.getHiZDepthTexture(this) ? screenSpaceRayTracing_HiZ(this, this.viewPos, this.reflectVec, ShaderHelper.getViewMatrix(this), ShaderHelper.getProjectionMatrix(this), ShaderHelper.getInvProjectionMatrix(this), ShaderHelper.getCameraParams(this).xy, pb.int(ShaderHelper.getHiZDepthTextureMipLevelCount(this)), this.ssrParams.y, this.ssrParams.x, this.ssrParams.z, pb.vec4(ShaderHelper.getRenderSize(this), ShaderHelper.getHiZDepthTextureSize(this)), ShaderHelper.getHiZDepthTexture(this)) : screenSpaceRayTracing_Linear2D(this, this.viewPos, this.reflectVec, ShaderHelper.getViewMatrix(this), ShaderHelper.getProjectionMatrix(this), ShaderHelper.getInvProjectionMatrix(this), ShaderHelper.getCameraParams(this).xy, this.ssrParams.x, this.ssrParams.y, this.ssrParams.z, this.ssrParams.w, pb.vec4(ShaderHelper.getRenderSize(this), ShaderHelper.getLinearDepthTextureSize(this)), ShaderHelper.getLinearDepthTexture(this));
             });
             this.$l.refl = pb.reflect(pb.normalize(pb.sub(this.worldPos, ShaderHelper.getCameraPosition(this))), this.shadingNormal);
-            // What the mirror shows where the screen-space trace found nothing.
-            //
-            // From above that is the sky. Rays reflecting downwards, and grazing
-            // ones, land on the bake's lower hemisphere, which the atmosphere
-            // renders nearly black, so the far ocean reads as a dark band. Flooring
-            // the y and re-normalising pins those directions just above the horizon,
-            // which is roughly what a grazing reflection does see; a reflection
-            // already pointing into the sky is untouched. A floor rather than a soft
-            // lift, so only the degenerate directions are nudged.
-            //
-            // From below there is no sky in that direction at all - the ray is
-            // heading back down into the water - and what it eventually reaches is
-            // the water itself. That is the medium's asymptotic colour, the same
-            // limit the underwater pass converges to as the path length grows:
-            // albedo * (1 - exp(-sigma_t * d)) * ambient with the exponential gone.
-            // Sampling the sky bake there instead put a bright sky outside the Snell
-            // window, which is exactly where nothing above the surface is visible.
+            // Fallback where the trace misses. From above: the sky, with the
+            // reflection y floored so grazing rays do not read the bake's black
+            // lower hemisphere. From below: the medium's asymptotic colour
+            // albedo * ambient, the d -> inf limit of the underwater pass.
             this.$l.reflMiss = pb.vec3();
             this.$if(this.underwaterEye, function() {
                 this.$l.downwelling = ShaderHelper.sampleBakedSkyPreExposed(this, pb.vec3(0, 1, 0));
@@ -2035,177 +1660,258 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             }).$else(function() {
                 this.refl.y = pb.max(this.refl.y, HORIZON_REFLECT_BIAS);
                 this.refl = pb.normalize(this.refl);
-                // Blended against the pre-exposed scene color, so the exposure-independent sky bake has
-                // to be lifted into the same space.
-                this.reflMiss = ShaderHelper.sampleBakedSkyPreExposed(this, this.refl);
+                // The mirror image of the visible sky, at its on-screen scale: the bake
+                // brought to the live exposure without the environment light's
+                // strength, which dims the IBL and not the sky itself.
+                this.reflMiss = pb.mul(pb.textureSampleLevel(ShaderHelper.getBakedSkyTexture(this), this.refl, 0).rgb, this.skyReflectScale);
+                if (envLight?.hasRadiance()) {
+                    // Blurred as the distant normals are: the prefiltered radiance at
+                    // the surface's roughness, in the same pre-exposed space
+                    this.$l.skyBlur = pb.smoothStep(SKY_PREFILTER_START, SKY_PREFILTER_FULL, this.roughness);
+                    this.$if(pb.greaterThan(this.skyBlur, 0), function() {
+                        this.reflMiss = pb.mix(this.reflMiss, pb.mul(envLight.getRadiance(this, this.refl, this.roughness).rgb, this.skyReflectScale), this.skyBlur);
+                    });
+                }
             });
-            this.reflectance = pb.mix(this.reflMiss, pb.textureSampleLevel(ShaderHelper.getSceneColorTexture(this), this.hitInfo.xy, 0).rgb, this.hitInfo.w);
-            this.$l.refractInfo = that.waterRefraction(this, this.worldPos, this.normal, this.eyeVecNorm, this.screenUV, this.viewPos.z, this.wPos.w, this.wPos.xyz, this.depth);
+            // The traced reflection blurred by roughness as Uludag's cone-traced
+            // reflections blur it ("Hi-Z Screen-Space Cone-Traced Reflections",
+            // GPU Pro 5, 2014): the lobe as a cone of half angle
+            // acos(0.244^(1 / (n + 1))) for a Phong power n, here
+            // n = 2 / alpha^2 - 2 for the GGX alpha (Walter et al., "Microfacet
+            // Models for Refraction through Rough Surfaces", EGSR 2007); its
+            // footprint where the ray hits the radius of the circle inscribed in
+            // the isosceles triangle of the cone over the screen-space ray, in
+            // pixels; and the scene colour read at the level of that radius
+            this.$l.alpha = pb.mul(this.roughness, this.roughness);
+            this.$l.phongPower = pb.max(pb.sub(pb.div(2, pb.max(pb.mul(this.alpha, this.alpha), 1e-6)), 2), 0);
+            this.$l.coneCos = pb.pow(0.244, pb.div(1, pb.add(this.phongPower, 1)));
+            this.$l.coneTan = pb.div(pb.sqrt(pb.max(pb.sub(1, pb.mul(this.coneCos, this.coneCos)), 0)), pb.max(this.coneCos, 1e-4));
+            this.$l.coneBase = pb.mul(2, this.coneTan, this.hitInfo.z);
+            this.$l.coneRadius = pb.div(pb.mul(this.coneBase, pb.sub(pb.sqrt(pb.add(pb.mul(this.coneBase, this.coneBase), pb.mul(4, this.hitInfo.z, this.hitInfo.z))), this.coneBase)), pb.max(pb.mul(4, this.hitInfo.z), 1e-4));
+            this.$l.reflectLod = pb.clamp(pb.log2(pb.max(this.coneRadius, 1)), 0, REFRACT_BLUR_MAX_LOD);
+            this.reflectance = pb.mix(this.reflMiss, pb.textureSampleLevel(ShaderHelper.getSceneColorTexture(this), this.hitInfo.xy, this.reflectLod).rgb, this.hitInfo.w);
+            this.$l.refractInfo = that.waterRefraction(this, this.worldPos, this.normal, this.eyeVecNorm, this.screenUV, this.viewPos.z, this.wPos.w, this.wPos.xyz, this.depth, this.underwaterEye);
             this.$l.refractUV = this.refractInfo.xy;
-            // The medium is walked along the refracted path, not along the straight
-            // line to the bed. A refracted ray reaches the same depth over a shorter
-            // distance, and at a grazing view the two differ by a lot.
+            // Medium path is the refracted length, not the straight line.
             this.depth = this.refractInfo.z;
-            // How blurred what is behind the water reads. Scattering in the column
-            // deflects the transmitted ray at every event, so the image arriving at
-            // the surface is a convolution whose width grows with the optical depth;
-            // sampling a coarser mip is the cheap stand-in for that.
-            //
-            // Log in the path length because each mip is a doubling of the filter
-            // width, and driven by the *scattering* coefficient rather than the
-            // extinction: absorption removes light without redirecting it, so it
-            // darkens the background without blurring it.
-            //
-            // Zero from below. The ray leaving the underside travels through air to
-            // whatever it reaches, so there is no medium along it to blur or absorb
-            // with - what the eye already looked through to get here is the volume
-            // the Underwater pass owns, and charging the same column twice turned
-            // the world seen through the Snell window into a dark smear.
+            // Zero from below: the column the eye is inside belongs to the
+            // Underwater pass, and charging it twice smears the Snell window.
             this.$l.mediumPath = this.$choice(this.underwaterEye, pb.float(0), this.depth);
+            // Blur LOD: log2 in path length (each mip doubles the width), driven by
+            // scattering rather than extinction (absorption darkens without blurring).
             this.$l.refractBlur = pb.log2(pb.add(1, pb.mul(this.mediumPath, pb.add(REFRACT_BLUR_GEOMETRIC, this.refractBlurDensity))));
             this.$l.refraction = pb.textureSampleLevel(ShaderHelper.getSceneColorTexture(this), this.refractUV, pb.clamp(this.refractBlur, 0, REFRACT_BLUR_MAX_LOD)).rgb;
             this.$l.refractionRaw = this.refraction;
             this.$l.absorption = this.getAbsorption(this.mediumPath);
             this.refraction = pb.mul(this.refraction, this.absorption);
-            this.$l.fresnelTerm = this.fresnel(this.shadingNormal, pb.neg(this.eyeVecNorm), this.underwaterEye);
-            // Foam coverage. The generator reports where the surface has folded over
-            // on itself; the ramp turns that into how much of the texel is covered.
-            this.$l.crestFoam = pb.clamp(pb.mul(pb.pow(pb.clamp(this.foamFactor, 0, 1), this.foamShadingParams.y), this.foamShadingParams.x), 0, 1);
-            // (coverage, distance to the nearest surface around the pixel). The
-            // distance is carried out for the debug view; the shading only wants x.
-            this.$l.shoreFoamInfo = shoreFoam ? this.waterShoreFoam(this.worldPos, this.viewPos, this.screenUV) : pb.vec2(0, 0);
-            this.$l.shoreFoam = this.shoreFoamInfo.x;
-            // Two independent coverages of the same texel, so they compose as
-            // overlapping area: `max` would ignore the smaller source entirely and
-            // adding would run past 1.
-            this.$l.foam = pb.sub(1, pb.mul(pb.sub(1, this.crestFoam), pb.sub(1, this.shoreFoam)));
-            // Foam suppresses the specular lobe rather than adding to it: where it is
-            // thick the mirror underneath stops being visible at all.
-            this.fresnelTerm = pb.mul(this.fresnelTerm, pb.sub(1, this.foam));
-            this.$l.finalColor = pb.mix(this.refraction, this.reflectance, this.fresnelTerm);
-            // Per-term accumulators for the debug views. Dead in the `none` variant.
-            this.$l.dbgSpecular = pb.vec3(0);
-            this.$l.dbgNoL = pb.float(0);
-            this.$l.dbgShadow = pb.vec3(1);
+            this.$l.viewXZ = pb.neg(this.eyeVecNorm.xz);
+            if (slopeVar) {
+                // Variance of the slopes the normal no longer shows along the view
+                // direction, as Bruneton's MeanFresnel takes it
+                this.$l.sigmaV = pb.sqrt(pb.max(pb.div(pb.add(pb.mul(this.viewXZ.x, this.viewXZ.x, this.slopeVar.x), pb.mul(this.viewXZ.y, this.viewXZ.y, this.slopeVar.y), pb.mul(this.viewXZ.x, this.viewXZ.y, this.slopeVar.z, 2)), pb.max(pb.dot(this.viewXZ, this.viewXZ), 1e-6)), 0));
+            } else {
+                // Variance of the slopes the flattened normal no longer shows, (1 - k^2)
+                // of the sea's for a slope scaled by k, along the view direction in wind
+                // space as Bruneton's MeanFresnel takes it
+                this.$l.viewWind = pb.vec2(pb.dot(this.viewXZ, this.unresolvedSlope.xy), pb.dot(this.viewXZ, pb.vec2(pb.neg(this.unresolvedSlope.y), this.unresolvedSlope.x)));
+                this.$l.viewWindT = pb.div(pb.mul(this.viewWind, this.viewWind), pb.max(pb.dot(this.viewXZ, this.viewXZ), 1e-6));
+                this.$l.sigmaV = pb.sqrt(pb.mul(pb.dot(this.viewWindT, this.unresolvedSlope.zw), pb.sub(1, pb.mul(this.normalScale, this.normalScale))));
+            }
+            this.$l.fresnelTerm = this.fresnel(this.shadingNormal, pb.neg(this.eyeVecNorm), this.underwaterEye, this.sigmaV);
+            // Foam density from the wave generator: crests, wakes, breaking shore waves
+            this.$l.crestDensity = pb.clamp(pb.mul(pb.pow(pb.clamp(this.foamFactor, 0, 1), this.foamShadingParams.y), this.foamShadingParams.x), 0, 1);
+            this.$l.crestWhite = this.waterWhiteFoam(this.crestDensity, this.foamSample, this.foamLookParams.x);
+            // Wall foam, cut from the same texture by its own density: whole against
+            // the wall, fraying as it thins. Its strength scales opacity after the cut.
+            this.$l.wallDensity = pb.clamp(this.wallFoam, 0, 1);
+            this.$l.wallCut = this.waterWhiteFoam(this.wallDensity, this.foamSample, this.foamLookParams.x);
+            this.$l.wallWhite = pb.mul(this.wallCut.x, this.foamShadingParams.z);
+            // The two layers combine as independent covers.
+            this.$l.foam = pb.sub(1, pb.mul(pb.sub(1, this.crestWhite.x), pb.sub(1, this.wallWhite)));
+            this.$l.foamGrad = pb.add(pb.mul(this.crestWhite.yz, pb.sub(1, this.wallWhite)), pb.mul(this.wallCut.yz, this.foamShadingParams.z, pb.sub(1, this.crestWhite.x)));
+            this.$l.bubbleDensity = pb.sub(1, pb.mul(pb.sub(1, this.crestDensity), pb.sub(1, pb.mul(this.wallDensity, this.foamShadingParams.z))));
+            // Normal of the white foam's relief: Crest differences the cut over a
+            // quarter texel per metre of view depth, which keeps the relief at a
+            // distance; the slope times that step here
+            this.$l.foamStep = pb.mul(this.dist, 0.25, foamTexelSize(this, this.foamTex, this.foamUVScale));
+            this.$l.foamNormal = pb.normalize(pb.add(this.diffuseNormal, pb.mul(pb.vec3(pb.neg(this.foamGrad.x), 0, pb.neg(this.foamGrad.y)), this.foamLookParams.y, this.foamStep)));
+            // The white foam covers the water, its mirror and what is seen through
+            // it alike, as Crest lays it over the finished water colour
+            // (lerp(col, whiteFoam, a)): both only on the share without foam.
+            // `bodyWeight`, the exit transmission on that share, weighs the
+            // refraction and every body term below.
+            this.$l.waterShare = pb.sub(1, this.foam);
+            this.$l.bodyWeight = pb.mul(pb.sub(1, this.fresnelTerm), this.waterShare);
+            this.fresnelTerm = pb.mul(this.fresnelTerm, this.waterShare);
+            this.$l.finalColor = pb.add(pb.mul(this.refraction, this.bodyWeight), pb.mul(this.reflectance, this.fresnelTerm));
+            // Prefer the wave generator's own ground for the thickness of thin swash.
+            this.$l.edgeThickness = this.$choice(pb.greaterThanEqual(this.sheetThickness, 0), this.sheetThickness, // Sky reconstructs to the far plane, which can lie above an infinite
+            // surface. With no bottom there, keep the water and foam fully visible.
+            this.$choice(pb.greaterThanEqual(this.wPos.w, SCENE_SKY_DEPTH01), pb.max(this.edgeFadeWidth, 1e-4), pb.sub(this.worldPos.y, this.wPos.y)));
+            this.$l.foamFade = pb.mul(this.$choice(pb.greaterThanEqual(this.sheetThickness, 0), pb.float(1), this.$choice(pb.greaterThan(this.edgeFadeWidth, 0), pb.smoothStep(0, pb.max(pb.mul(this.edgeFadeWidth, FOAM_EDGE_FADE_SHARE), 1e-4), this.edgeThickness), pb.float(1))), this.coverage);
+            // Light the foam sends back, kept apart so the edge fade below can keep
+            // the foam on a sheet too thin to show the water
+            this.$l.foamRadiance = pb.vec3(0);
+            this.$l.groundFoamOpacity = pb.float(0);
+            this.$l.groundFoamRadiance = pb.vec3(0);
+            if (hasGroundFoam) {
+                this.$if(pb.greaterThan(this.groundFoamDensity, 1e-3), function() {
+                    this.$l.groundFoamWhite = this.waterWhiteFoam(pb.clamp(pb.mul(pb.pow(this.groundFoamDensity, this.foamShadingParams.y), this.foamShadingParams.x), 0, 1), this.groundFoamSample, this.foamLookParams.x);
+                    this.groundFoamOpacity = this.groundFoamWhite.x;
+                });
+                // The carrier P can still foam while its projected ground Q is dry.
+                // Keep that visible cover through the handoff; once P drains, only
+                // the ground foam remains. Set opacity before lighting both covers.
+                this.groundFoamOpacity = pb.max(this.groundFoamOpacity, pb.mul(this.foam, this.foamFade));
+            }
+            // Debug accumulators. Dead in the `none` variant.
             this.$l.dbgSubsurface = pb.vec3(0);
             this.$l.dbgSunScatter = pb.vec3(0);
-            this.$l.dbgScatter = pb.vec3(0);
-            // What anything leaving the water body keeps on its way out, and the
-            // share of the surface that is water rather than foam. The refraction
-            // above already carries the first factor via the `mix`; every scattering
-            // term below has to carry it too.
-            this.$l.bodyWeight = pb.mul(pb.sub(1, this.fresnelTerm), pb.sub(1, this.foam));
-            // The sun-scattering debug views below rebuild that term's factors, and
-            // the light direction is only known inside this loop. Initialised so the
-            // views are well defined even with no directional light in the scene.
+            this.$l.dbgShadow = pb.vec3(1);
+            this.$l.dbgSpecular = pb.vec3(0);
+            // Subsurface crest gate, after Ceto: the lit wall thins with height,
+            // path = max(floor, exp(-softplus(h / H))), gate = exp(-sigma_t *
+            // scale * path). On the vertex displacement, not the normal tilt,
+            // which is zero at the crest and carries every ripple.
+            this.$l.sssT = pb.div(this.crestHeight, this.subsurfaceParams.y);
+            // softplus in the overflow-safe form max(t,0) + w*log(1+exp(-|t|/w)).
+            this.$l.sssRise = pb.add(pb.max(this.sssT, 0), pb.mul(SSS_HEIGHT_SOFTNESS, pb.log(pb.add(1, pb.exp(pb.div(pb.neg(pb.abs(this.sssT)), SSS_HEIGHT_SOFTNESS))))));
+            this.$l.sssPath = pb.max(pb.exp(pb.neg(this.sssRise)), SSS_CREST_PATH_FLOOR);
+            this.$l.sssThickness = pb.exp(pb.neg(pb.mul(this.mediumExtinction, pb.mul(this.sssPath, SSS_ABSORPTION_SCALE))));
+            // For the debug views that rebuild the sun terms outside the loop.
             this.dbgLightDir = pb.vec3(0, 1, 0);
             that.forEachLight(this, function(type, posRange, dirCutoff, colorIntensity, extra, shadow) {
                 this.$l.lightAtten = that.calculateLightAttenuation(this, type, this.worldPos, posRange, dirCutoff, extra);
-                this.$l.lightDir = that.calculateLightDirection(this, type, this.worldPos, posRange, dirCutoff);
-                // Left behind for the sun-scattering debug views, which rebuild that
-                // term's factors outside this loop.
+                this.$l.lightDir = that.calculateLightDirection(this, type, this.worldPos, posRange, dirCutoff, extra);
                 this.dbgLightDir = this.lightDir;
                 this.$l.NoL = pb.clamp(pb.dot(this.normal, this.lightDir), 0, 1);
-                // Diffuse incidence, off the diffuse normal. Used by the foam and the
-                // sun in-scattering below; NoL keeps the wave face for the mirror.
                 this.$l.NoLdiffuse = pb.clamp(pb.dot(this.diffuseNormal, this.lightDir), 0, 1);
-                this.dbgNoL = this.NoLdiffuse;
+                // From the raw cosine, so a lee slope below zero still wraps up.
+                this.$l.NoLfoam = pb.clamp(pb.div(pb.add(pb.dot(this.foamNormal, this.lightDir), FOAM_LIGHT_WRAP), 1 + FOAM_LIGHT_WRAP), 0, 1);
                 this.$l.lightEnergy = pb.mul(colorIntensity.rgb, colorIntensity.a, this.lightAtten);
-                this.$l.specularTerm = this.lightSpecular(this.lightDir, this.eyeVecNorm, this.shadingNormal, this.lightEnergy, this.roughness);
+                this.$l.specularTerm = pb.vec3(0);
+                // A rect light's mirror image is the rect itself: integrate the GGX
+                // lobe over it with LTC, as the PBR materials do. One direction would
+                // shrink it to a point highlight on a surface this smooth.
+                this.$if(pb.equal(type, LIGHT_TYPE_RECT), function() {
+                    this.$l.rectTerms = evaluateLTCRectLightTerms(this, this.worldPos, this.shadingNormal, pb.neg(this.eyeVecNorm), this.roughness, posRange, dirCutoff.xyz, extra.xyz);
+                    this.specularTerm = pb.mul(colorIntensity.rgb, colorIntensity.a, this.rectTerms.x, pb.add(pb.mul(this.rectTerms.y, WATER_F0), pb.mul(this.rectTerms.z, 1 - WATER_F0)));
+                }).$else(function() {
+                    this.specularTerm = this.lightSpecular(this.lightDir, this.eyeVecNorm, this.shadingNormal, this.lightEnergy, this.roughness);
+                });
                 this.$l.lightContrib = this.specularTerm;
-                // Sunlight that entered the far side of a wave and scattered back out
-                // towards the eye - what makes a backlit crest glow. It has to come
-                // from the light loop: the ambient scattering term below is built from
-                // the environment irradiance, which has no direction.
-                //
-                // Standard translucency approximation - the transmitted direction is
-                // the light continuing through the surface, bent by the normal, and
-                // the term peaks when the eye looks back along it.
-                this.$l.sssDir = pb.normalize(pb.add(pb.neg(this.lightDir), pb.mul(this.diffuseNormal, SSS_DISTORTION)));
-                this.$l.sssFacing = pb.pow(pb.clamp(pb.dot(pb.neg(this.eyeVecNorm), this.sssDir), 0, 1), SSS_POWER);
-                // Crests glow and troughs do not: height above the undisplaced surface
-                // stands in for how much lit water the ray passed through. The medium's
-                // albedo carries the hue; the magnitude is authored.
-                this.$l.sssThickness = pb.clamp(pb.mul(pb.sub(1, this.diffuseNormal.y), this.subsurfaceParams.y), 0, 1);
-                this.$l.subsurfaceTerm = pb.mul(this.lightEnergy, this.mediumAlbedo, pb.mul(this.sssFacing, this.sssThickness, this.subsurfaceParams.x));
-                this.lightContrib = pb.add(this.lightContrib, this.subsurfaceTerm);
-                // Sunlight scattered back out of the water column, which is what gives
-                // the body a direction-dependent colour at all.
-                //
-                // Directional only, and only with the eye above the surface. The
-                // integral assumes a parallel beam of fixed slope; a point light's
-                // falloff along the column and the underwater geometry both need a
-                // different solution. The refraction and the ambient scattering still
-                // carry the water colour in those cases.
+                // Backlit-crest subsurface, after Ceto: grazing^2 * (view ray mirrored
+                // in the rest plane, against the sun)^4 * sun-above-horizon fade.
+                // Both cosines are floored.
+                this.$l.sssToEye = pb.neg(this.eyeVecNorm);
+                this.$l.sssGrazing = pb.sub(1, pb.clamp(this.sssToEye.y, 0, 1));
+                this.sssGrazing = pb.mix(SSS_GRAZING_FLOOR, 1, pb.mul(this.sssGrazing, this.sssGrazing));
+                this.$l.sssMirror = pb.reflect(this.sssToEye, pb.vec3(0, 1, 0));
+                this.$l.sssAlign = pb.clamp(pb.dot(pb.neg(this.sssMirror), this.lightDir), 0, 1);
+                this.sssAlign = pb.mul(this.sssAlign, this.sssAlign);
+                this.sssAlign = pb.mix(SSS_SUN_ALIGN_FLOOR, 1, pb.mul(this.sssAlign, this.sssAlign));
+                this.$l.sssSunUp = pb.smoothStep(0, 0.1, this.lightDir.y);
+                this.$l.sssFacing = pb.mul(this.sssGrazing, this.sssAlign, this.sssSunUp);
+                // Scaled by the light colour as in Crest, and by 1 / pi like the other
+                // diffuse terms. Directional lights only; carries `bodyWeight`.
+                this.$l.subsurfaceTerm = pb.vec3(0);
+                this.$if(pb.equal(type, LIGHT_TYPE_DIRECTIONAL), function() {
+                    this.subsurfaceTerm = pb.mul(this.subsurfaceTint, this.lightEnergy, pb.mul(this.sssFacing, this.sssThickness, this.subsurfaceParams.x, 1 / Math.PI), this.bodyWeight);
+                    this.lightContrib = pb.add(this.lightContrib, this.subsurfaceTerm);
+                });
+                // Directional only (the integral assumes a parallel beam) and from
+                // above only.
                 this.$l.sunScatterTerm = pb.vec3(0);
                 this.$if(pb.and(pb.equal(type, LIGHT_TYPE_DIRECTIONAL), pb.not(this.underwaterEye)), function() {
-                    // Weighted by what the surface transmits on the way out and by how
-                    // much of it is still water rather than foam, like every other
-                    // term that comes from inside the body.
                     this.sunScatterTerm = pb.mul(that.waterSunScattering(this, this.lightEnergy, this.lightDir, this.eyeVecNorm, this.NoLdiffuse, this.depth, this.foam), this.bodyWeight);
                     this.lightContrib = pb.add(this.lightContrib, this.sunScatterTerm);
                 });
-                // Foam is a rough dielectric layer, so it takes the light the way any
-                // matte surface does.
-                this.lightContrib = pb.add(this.lightContrib, pb.mul(this.lightEnergy, this.foamColor, this.foam, this.NoLdiffuse, 1 / Math.PI));
+                // Foam as a matte layer, with Crest's narrow glint off its relief.
+                this.$l.foamGlint = pb.mul(pb.pow(pb.max(pb.dot(pb.reflect(this.eyeVecNorm, this.foamNormal), this.lightDir), 0), FOAM_SPECULAR_POWER), FOAM_SPECULAR_BOOST);
+                this.$l.foamLight = pb.mul(this.lightEnergy, this.foam, pb.add(pb.mul(this.foamColor, this.NoLfoam, 1 / Math.PI), pb.vec3(this.foamGlint)));
+                this.lightContrib = pb.add(this.lightContrib, this.foamLight);
                 this.$l.shadow = pb.vec3(1);
                 if (shadow) {
-                    // Water is a horizontal clipmap, so +Y is the geometric normal. The
-                    // wave normal would jitter the shadow lookup per-pixel.
+                    // +Y, not the wave normal, which would jitter the lookup per pixel.
                     this.shadow = pb.vec3(that.calculateShadow(this, this.worldPos, pb.vec3(0, 1, 0), this.NoL));
-                    this.dbgShadow = this.shadow;
                     this.lightContrib = pb.mul(this.lightContrib, this.shadow);
                 }
+                this.foamRadiance = pb.add(this.foamRadiance, pb.mul(this.foamLight, this.shadow));
+                if (hasGroundFoam) {
+                    this.$if(pb.greaterThan(this.groundFoamOpacity, 0), function() {
+                        this.$l.groundNoL = pb.clamp(pb.div(pb.add(pb.dot(this.groundNormal, this.lightDir), FOAM_LIGHT_WRAP), 1 + FOAM_LIGHT_WRAP), 0, 1);
+                        this.$l.groundShadow = pb.vec3(1);
+                        if (shadow) {
+                            this.groundShadow = pb.vec3(that.calculateShadow(this, this.wPos.xyz, this.groundNormal, this.groundNoL));
+                        }
+                        this.groundFoamRadiance = pb.add(this.groundFoamRadiance, pb.mul(this.lightEnergy, this.foamColor, this.groundNoL, this.groundShadow, this.groundFoamOpacity, 1 / Math.PI));
+                    });
+                }
                 this.finalColor = pb.add(this.finalColor, this.lightContrib);
-                this.dbgSpecular = pb.add(this.dbgSpecular, pb.mul(this.specularTerm, this.shadow));
                 this.dbgSubsurface = pb.add(this.dbgSubsurface, pb.mul(this.subsurfaceTerm, this.shadow));
                 this.dbgSunScatter = pb.add(this.dbgSunScatter, pb.mul(this.sunScatterTerm, this.shadow));
+                this.dbgShadow = pb.min(this.dbgShadow, this.shadow);
+                this.dbgSpecular = pb.add(this.dbgSpecular, pb.mul(this.specularTerm, this.shadow));
             });
             if (that.needCalculateEnvLight()) {
                 this.$l.irradiance = that.getEnvLightIrradiance(this, this.diffuseNormal);
-                // Scattering from the water body itself, and from the foam sitting on
-                // it. `bodyWeight` is what the surface transmits on the way out times
-                // the share of it that is still water.
-                //
-                // On the same path length the absorption uses, so this vanishes from
-                // below: the column the eye is already inside belongs to the
-                // Underwater pass, and adding the surface's own estimate of it on top
-                // paints the water colour twice. The foam term below is unconditional
-                // - a crest that has broken is white from underneath too.
+                // On `mediumPath`, so zero from below. The foam term is unconditional.
                 this.$l.sss = pb.mul(this.getScattering(this.mediumPath), this.irradiance, this.bodyWeight, 1 / Math.PI);
                 this.finalColor = pb.add(this.finalColor, this.sss);
-                this.dbgScatter = this.sss;
-                this.finalColor = pb.add(this.finalColor, pb.mul(this.irradiance, this.foamColor, this.foam, 1 / Math.PI));
+                this.$l.foamAmbient = pb.mul(this.irradiance, this.foamColor, this.foam, 1 / Math.PI);
+                this.finalColor = pb.add(this.finalColor, this.foamAmbient);
+                this.foamRadiance = pb.add(this.foamRadiance, this.foamAmbient);
+                if (hasGroundFoam) {
+                    this.groundFoamRadiance = pb.add(this.groundFoamRadiance, pb.mul(that.getEnvLightIrradiance(this, this.groundNormal), this.foamColor, this.groundFoamOpacity, 1 / Math.PI));
+                }
+                // Bubbles under the white foam, part of the water body as in Crest,
+                // so under the white foam and the mirror: the foam texture blurred and
+                // shifted by parallax, as seen at a depth under the surface
+                this.$if(pb.greaterThan(this.bubbleDensity, 0), function() {
+                    this.$l.toEye = pb.neg(this.eyeVecNorm);
+                    this.$l.bubbleShift = pb.div(pb.mul(this.toEye.xz, pb.neg(this.foamLookParams.w)), pb.max(pb.dot(this.diffuseNormal, this.toEye), 0.1));
+                    this.$l.bubbleTex = sampleFoamTexture(this, this.foamTex, pb.mul(pb.add(this.restXZ, this.bubbleShift, pb.vec2(pb.mul(ShaderHelper.getElapsedTime(this), FOAM_DRIFT))), this.foamUVScale), this.restXZGrad, this.foamUVScale, FOAM_BUBBLE_MIP_SCALE, false).x;
+                    this.finalColor = pb.add(this.finalColor, pb.mul(this.irradiance, this.foamBubbleColor, this.bubbleTex, pb.clamp(pb.mul(this.bubbleDensity, this.foamLookParams.z), 0, 1), this.bodyWeight, 1 / Math.PI));
+                });
             }
+            // A thin sheet fades into the scene behind it. Where the generator
+            // knows the wet edge, its coverage keeps foam visible on even a
+            // millimetre-thick sheet; elsewhere foam fades by the measured depth.
+            this.$if(pb.not(this.underwaterEye), function() {
+                this.$l.edgeFade = pb.mul(this.$choice(pb.greaterThan(this.edgeFadeWidth, 0), pb.smoothStep(0, pb.max(this.edgeFadeWidth, 1e-4), this.edgeThickness), pb.float(1)), this.coverage);
+                this.$if(pb.lessThan(this.edgeFade, 1), function() {
+                    this.$l.behind = pb.textureSampleLevel(ShaderHelper.getSceneColorTexture(this), this.screenUV, 0).rgb;
+                    // finalColor = water (on the share without foam) + foam light: the
+                    // water fades into what is behind, under the foam
+                    this.finalColor = pb.add(pb.mix(pb.mul(this.behind, pb.sub(1, pb.mul(this.foam, this.foamFade))), pb.sub(this.finalColor, this.foamRadiance), this.edgeFade), pb.mul(this.foamRadiance, this.foamFade));
+                });
+                if (hasGroundFoam) {
+                    this.$if(pb.greaterThan(this.groundFoamWeight, 0), function() {
+                        this.$l.groundBehind = pb.textureSampleLevel(ShaderHelper.getSceneColorTexture(this), this.screenUV, 0).rgb;
+                        // One crossfade between complete covers. Attenuating the mobile
+                        // foam before overlaying ground foam applies this weight twice
+                        // and exposes sand in the middle even if both covers are white.
+                        this.$l.groundColor = pb.add(pb.mul(this.groundBehind, pb.sub(1, this.groundFoamOpacity)), this.groundFoamRadiance);
+                        this.finalColor = pb.mix(this.finalColor, this.groundColor, this.groundFoamWeight);
+                    });
+                }
+            });
             switch(debugOutput){
                 case 'normal':
-                    this.$return(pb.add(pb.mul(this.normal, 0.5), pb.vec3(0.5)));
-                    break;
-                case 'diffuseNormal':
-                    this.$return(pb.add(pb.mul(this.diffuseNormal, 0.5), pb.vec3(0.5)));
-                    break;
-                case 'frontFacing':
-                    this.$return(this.$choice(this.$builtins.frontFacing, pb.vec3(1), pb.vec3(0)));
+                    this.$if(pb.lessThan(this.diffuseNormal.y, 0.01), function() {
+                        this.$return(pb.vec3(1, 0, 0));
+                    }).$else(function() {
+                        this.$return(pb.add(pb.mul(this.diffuseNormal, 0.5), pb.vec3(0.5)));
+                    });
                     break;
-                case 'viewFacing':
-                    {
-                        // Raw, not clamped: a negative value means the wave normal faces
-                        // away from the eye at that pixel.
-                        this.$l.viewFacing = pb.dot(this.normal, pb.neg(this.eyeVecNorm));
-                        this.$return(pb.vec3(this.viewFacing));
-                        break;
-                    }
                 case 'foam':
-                    this.$return(pb.vec3(this.foam));
+                    this.$return(pb.vec3(pb.mix(this.foam, this.groundFoamOpacity, this.groundFoamWeight)));
                     break;
-                case 'shoreFoam':
-                    this.$return(pb.vec3(this.shoreFoam));
+                case 'swashFoamCuts':
+                    this.$return(pb.vec3(this.foam, this.groundFoamOpacity, this.groundFoamWeight));
                     break;
                 case 'waterDepth':
-                    // Distance from the surface to whatever is behind it, metres / 10.
-                    // With the band switched off there is no such estimate, so the plain
-                    // height difference stands in.
-                    this.$return(pb.vec3(pb.mul(shoreFoam ? this.shoreFoamInfo.y : pb.max(pb.sub(this.worldPos.y, this.wPos.y), 0), 0.1)));
+                    this.$return(pb.vec3(pb.mul(pb.max(pb.sub(this.worldPos.y, this.wPos.y), 0), 0.1)));
                     break;
                 case 'fresnel':
                     this.$return(pb.vec3(this.fresnelTerm));
@@ -2220,76 +1926,36 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
                     this.$return(this.absorption);
                     break;
                 case 'scattering':
-                    this.$return(this.dbgScatter);
+                    this.$return(this.sss);
                     break;
                 case 'sunScattering':
                     this.$return(this.dbgSunScatter);
                     break;
-                case 'sunNoL':
-                    this.$return(pb.vec3(pb.clamp(this.dbgNoL, 0, 1)));
+                case 'subsurface':
+                    this.$return(this.dbgSubsurface);
+                    break;
+                case 'subsurfaceThickness':
+                    this.$return(pb.vec3(this.sssThickness));
                     break;
                 case 'shadow':
                     this.$return(this.dbgShadow);
                     break;
-                case 'sunPhase':
-                    {
-                        // Recomputed from the same inputs rather than read back out of
-                        // waterSunScattering: the value belongs to that function's scope, and
-                        // the variant that wants it is the one that never calls it. Keep the
-                        // two expressions in step.
-                        this.$l.dbgLw = pb.refract(pb.neg(this.dbgLightDir), pb.vec3(0, 1, 0), 1 / 1.333);
-                        this.$l.dbgVw = pb.refract(this.eyeVecNorm, pb.vec3(0, 1, 0), 1 / 1.333);
-                        this.$l.dbgCosTheta = pb.neg(pb.dot(this.dbgLw, this.dbgVw));
-                        this.$l.dbgHg = waterScatterPhase(this, this.dbgCosTheta, this.sunScatterParams.y);
-                        this.$l.dbgLumWeights = pb.vec3(0.2126, 0.7152, 0.0722);
-                        this.$l.dbgThickness = pb.mul(pb.dot(this.mediumAlbedo, this.dbgLumWeights), pb.sub(1, pb.exp(pb.neg(pb.mul(pb.dot(this.mediumExtinction, this.dbgLumWeights), this.depth)))));
-                        this.$return(pb.vec3(pb.clamp(pb.mix(this.dbgHg, 1 / (4 * Math.PI), pb.smoothStep(0, 0.5, pb.clamp(this.dbgThickness, 0, 1))), 0, 1)));
-                        break;
-                    }
-                case 'sunIntegral':
-                    {
-                        this.$l.dbgVy = pb.max(pb.neg(pb.refract(this.eyeVecNorm, pb.vec3(0, 1, 0), 1 / 1.333).y), 1e-3);
-                        this.$l.dbgSy = pb.max(pb.neg(pb.refract(pb.neg(this.dbgLightDir), pb.vec3(0, 1, 0), 1 / 1.333).y), 0.05);
-                        this.$l.dbgRr = pb.add(1, pb.div(this.dbgVy, this.dbgSy));
-                        this.$l.dbgIntegral = pb.div(pb.sub(pb.vec3(1), pb.exp(pb.neg(pb.mul(pb.mul(this.mediumExtinction, this.dbgRr), this.depth)))), this.dbgRr);
-                        this.$return(pb.vec3(pb.clamp(pb.length(this.dbgIntegral), 0, 1)));
-                        break;
-                    }
-                case 'subsurface':
-                    this.$return(this.dbgSubsurface);
-                    break;
                 case 'specular':
                     this.$return(this.dbgSpecular);
                     break;
                 case 'depth':
                     this.$return(pb.vec3(pb.mul(this.depth, 0.1)));
                     break;
-                case 'refractUV':
-                    this.$return(pb.vec3(pb.add(pb.mul(pb.sub(this.refractUV, this.screenUV), 4), pb.vec2(0.5)), 0.5));
-                    break;
-                case 'nan':
-                    {
-                        // NaN is the only value that fails x == x. The normal is checked
-                        // separately from the colour so a NaN that a clamp downstream
-                        // swallowed still shows.
-                        this.$l.sum = pb.add(pb.dot(this.finalColor, pb.vec3(1)), pb.dot(this.normal, pb.vec3(1)));
-                        this.$l.bad = pb.or(pb.notEqual(this.sum, this.sum), pb.greaterThan(pb.abs(this.sum), 1e30));
-                        this.$return(this.$choice(this.bad, pb.vec3(1, 0, 0), pb.vec3(0)));
-                        break;
-                    }
                 default:
                     this.$return(this.finalColor);
             }
         });
-        return scope.waterShading(worldPos, worldNormal, foamFactor);
+        return scope.waterShading(worldPos, worldNormal, foamFactor, crestHeight, restXZ, restXZGrad, foamSample, coverage, sheetThickness, wallFoam, scenePos, groundFoamDensity, groundFoamSample, groundNormal, groundFoamWeight);
     }
     applyUniforms(bindGroup, ctx, needUpdate, pass) {
         super.applyUniforms(bindGroup, ctx, needUpdate, pass);
-        const waveGenerator = this._waveGenerator.get();
-        // Synced per bind group, not per material: the material owns one bind group
-        // per pass/render-variant hash, so drawing for a second camera reuses a
-        // different group whose wave uniforms were never written. WeakMap so a
-        // released group is garbage collected with its entry.
+        const waveGenerator = this._effectiveWaveGenerator;
+        // Per bind group: the material owns one per pass/variant hash.
         const lastWritten = this._waveVersionByBindGroup.get(bindGroup) ?? -1;
         if (waveGenerator && lastWritten !== waveGenerator.version) {
             waveGenerator.applyWaterBindGroup(bindGroup);
@@ -2305,98 +1971,255 @@ class WaterMaterial extends applyMaterialMixins(MeshMaterial, mixinLight) {
             bindGroup.setValue('region', this._region);
         }
         if (this.needFragmentColor(ctx)) {
-            // Dimensionless: the offset is derived in world space and projected, so
-            // there is nothing here for the render size to scale.
             bindGroup.setValue('refractionScale', this._refractionScale);
             if (this.refractionMode === 'offset') {
                 bindGroup.setValue('cheapRefractionDepth', this._cheapRefractionDepth);
             }
             bindGroup.setValue('reflectionStrength', this._reflectionStrength);
+            const wind = this._waveGenerator.get()?.wind;
+            const windSpeed = wind ? Math.hypot(wind.x, wind.y) : 0;
+            this._unresolvedSlope.setXYZW(windSpeed > 0 ? wind.x / windSpeed : 1, windSpeed > 0 ? wind.y / windSpeed : 0, COX_MUNK_UPWIND * windSpeed, COX_MUNK_CROSSWIND_BASE + COX_MUNK_CROSSWIND * windSpeed);
+            bindGroup.setValue('unresolvedSlope', this._unresolvedSlope);
+            bindGroup.setValue('skyReflectScale', ctx.scene.lightingMode === 'physical' ? ShaderHelper.getPreExposure(ctx) / PHYSICAL_BAKE_EXPOSURE : 1);
             bindGroup.setValue('ssrParams', this._ssrParams);
-            this._subsurfaceParams.setXYZW(this._subsurfaceIntensity, this._subsurfaceSteepness, 0, 0);
+            const eyeUnder = ctx.underwater;
+            bindGroup.setValue('eyeSide', eyeUnder ? eyeUnder.material === this ? -1 : 0 : 1);
+            this._subsurfaceParams.setXYZW(this._subsurfaceIntensity, this._subsurfaceCrestHeight, 0, 0);
             bindGroup.setValue('subsurfaceParams', this._subsurfaceParams);
-            this._foamParams.setXYZW(this._foamAmount, this._foamFalloff, 0, 0);
+            bindGroup.setValue('subsurfaceTint', this._subsurfaceTint);
+            this._foamParams.setXYZW(this._foamAmount, this._foamFalloff, this._shoreWaves.height > 0 ? this._shoreWaves.wallFoamStrength : 0, 0);
             bindGroup.setValue('foamShadingParams', this._foamParams);
             bindGroup.setValue('foamColor', this._foamColor);
-            if (this._shoreFoamEnabled) {
-                this._shoreFoamParams.setXYZW(this._shoreFoamAmount, this._shoreFoamDepth, this._shoreFoamFalloff, // Cycles per metre, resolved from cycles per band width.
-                this._shoreFoamScale / this._shoreFoamDepth);
-                bindGroup.setValue('shoreFoamParams', this._shoreFoamParams);
-                this._shoreFoamWashParams.setXYZW(this._shoreFoamWashAmount, this._shoreFoamWashSpeed, this._shoreFoamWashScale, // Query radius: the band's widest reach over the run-up cycle. Fixed
-                // over the cycle because it sets the pyramid level the query samples,
-                // and a level moving with the wash would step the band's resolution.
-                this._shoreFoamDepth * (1 + this._shoreFoamWashAmount));
-                bindGroup.setValue('shoreFoamWashParams', this._shoreFoamWashParams);
-            }
+            this._foamLookParams.setXYZW(this._foamFeather, this._foamNormalStrength, this._foamBubbleCoverage, this._foamBubbleDepth);
+            bindGroup.setValue('foamLookParams', this._foamLookParams);
+            bindGroup.setValue('foamBubbleColor', this._foamBubbleColor);
+            bindGroup.setTexture('foamTex', this.foamTexture ?? getDefaultFoamTexture(), fetchSampler('repeat_linear'));
+            bindGroup.setValue('foamUVScale', 1 / this._foamTextureSize);
+            bindGroup.setValue('edgeFadeWidth', this._edgeFadeWidth);
             bindGroup.setValue('mediumAlbedo', this._scatterAlbedo);
-            // Needed in both medium modes: the sun-scattering integral is always
-            // physical, even where the ramp overrides the depth-driven absorption.
             bindGroup.setValue('mediumExtinction', this._extinction);
+            bindGroup.setTexture('zLTCMatLut', getLTCMatLUT());
+            bindGroup.setTexture('zLTCAmpLut', getLTCAmpLUT());
             this._sunScatterParams.setXYZW(this._sunScatteringIntensity, this._scatterAnisotropy, 0, 0);
             bindGroup.setValue('sunScatterParams', this._sunScatterParams);
-            // One LOD serves all three channels, so the per-channel scattering has to
-            // collapse to a scalar. Luminance-weighted rather than a plain mean: the
-            // blur is a perceptual effect and green carries most of what is seen.
+            // Luminance-weighted scalar: one blur LOD serves all three channels.
             bindGroup.setValue('refractBlurDensity', (0.2126 * this._scattering.x + 0.7152 * this._scattering.y + 0.0722 * this._scattering.z) * this._scatteringScale * REFRACT_BLUR_DENSITY * this._refractionBlur);
-            if (this.mediumMode === 'ramp') {
-                bindGroup.setValue('depthMulti', this._depthMulti);
-                bindGroup.setTexture('scatterRampTex', this._getScatterRampTexture(ctx.device), fetchSampler('clamp_linear_nomip'));
-                bindGroup.setTexture('absorptionRampTex', this._getAbsorptionRampTexture(ctx.device), fetchSampler('clamp_linear_nomip'));
-            }
         }
         if (this.waveGenerator) {
             this.waveGenerator.applyWaterBindGroup(bindGroup);
         }
     }
     needUpdate() {
-        return !!this._waveGenerator.get()?.needUpdate();
+        return !!this._waveGenerator.get()?.needUpdate() || !!this._interaction.get() || !!this._shoreWaveGenerator;
+    }
+    /**
+   * Crest to trough height in metres of the waves rolling in to the shore and
+   * running up the beach, 0 for none. See {@link ShoreWaveGenerator}. Needs
+   * the scene signed distance field (WebGPU); without it the waves are off.
+   */ get shoreWaveHeight() {
+        return this._shoreWaves.height;
+    }
+    set shoreWaveHeight(val) {
+        val = Math.max(0, val);
+        const wasOn = this._shoreWaves.height > 0;
+        this._shoreWaves.height = val;
+        if (wasOn !== val > 0) {
+            this._rebuildEffectiveWaveGenerator();
+        }
+    }
+    /** Distance in metres between shore wave crests at the outer edge of their zone; they bunch up towards the shore. */ get shoreWaveLength() {
+        return this._shoreWaves.wavelength;
+    }
+    set shoreWaveLength(val) {
+        this._shoreWaves.wavelength = Math.max(0.5, val);
+    }
+    /** Seconds between successive shore waves. */ get shoreWavePeriod() {
+        return this._shoreWaves.period;
+    }
+    set shoreWavePeriod(val) {
+        this._shoreWaves.period = Math.max(0.5, val);
+    }
+    /** How far out from the waterline the shore waves rise, in metres. */ get shoreWaveZone() {
+        return this._shoreWaves.zone;
+    }
+    set shoreWaveZone(val) {
+        this._shoreWaves.zone = Math.max(1, val);
+    }
+    /** How sharp the shore wave crests become at the shore, 0 for a sine and towards 1 for a cusp. */ get shoreWaveSharpness() {
+        return this._shoreWaves.sharpness;
+    }
+    set shoreWaveSharpness(val) {
+        this._shoreWaves.sharpness = Math.min(Math.max(val, 0), 0.95);
+    }
+    /** How far the shore wave crests lean towards the shore there, 0 for upright, 1 for a steep front face. */ get shoreWaveLean() {
+        return this._shoreWaves.lean;
+    }
+    set shoreWaveLean(val) {
+        this._shoreWaves.lean = Math.min(Math.max(val, 0), 1);
+    }
+    /** How irregular the shore waves are, 0..1: 0 for parallel crests a fixed wavelength apart, higher for each wave with a period and a bend of its own. */ get shoreWaveIrregularity() {
+        return this._shoreWaves.irregularity;
+    }
+    set shoreWaveIrregularity(val) {
+        this._shoreWaves.irregularity = Math.min(Math.max(val, 0), 1);
+    }
+    /** How fast the foam fades, per second (Crest's Foam Fade Rate): lower leaves longer trails behind breaking waves. */ get foamFadeRate() {
+        return this._foamField.fadeRate;
+    }
+    set foamFadeRate(val) {
+        this._foamField.fadeRate = val;
+    }
+    /** How much foam the open water's breaking crests leave behind to drift and fade; 0 keeps foam only while a crest breaks. */ get foamTrailStrength() {
+        return this._foamField.baseStrength;
+    }
+    set foamTrailStrength(val) {
+        this._foamField.baseStrength = val;
+    }
+    /** Share of the wind speed the foam drifts at, about 0.03 in nature. */ get foamDrift() {
+        return this._foamField.drift;
+    }
+    set foamDrift(val) {
+        this._foamField.drift = val;
+    }
+    /** Side in metres of the finest square of water around the view whose foam lingers, in the most detail; coarser squares reach eight times as far, beyond which foam shows only while crests break. */ get foamFieldSize() {
+        return this._foamField.size;
+    }
+    set foamFieldSize(val) {
+        this._foamField.size = val;
+    }
+    /** How much foam the breaking shore waves make (Crest's Wave Foam Strength). */ get shoreWaveFoamStrength() {
+        return this._shoreWaves.waveFoamStrength;
+    }
+    set shoreWaveFoamStrength(val) {
+        this._shoreWaves.waveFoamStrength = Math.max(0, val);
+    }
+    /** How much of the shore waves makes foam, 0..1, higher for more (Crest's Wave Foam Coverage). */ get shoreWaveFoamCoverage() {
+        return this._shoreWaves.waveFoamCoverage;
+    }
+    set shoreWaveFoamCoverage(val) {
+        this._shoreWaves.waveFoamCoverage = Math.min(Math.max(val, 0), 1);
+    }
+    /** Water shallower than this many metres makes foam (Crest's Shoreline Foam Max Depth). */ get shoreWaveShallowFoamDepth() {
+        return this._shoreWaves.shorelineFoamMaxDepth;
+    }
+    set shoreWaveShallowFoamDepth(val) {
+        this._shoreWaves.shorelineFoamMaxDepth = Math.max(0.01, val);
+    }
+    /** How much foam shallow water makes (Crest's Shoreline Foam Strength). */ get shoreWaveShallowFoamStrength() {
+        return this._shoreWaves.shorelineFoamStrength;
+    }
+    set shoreWaveShallowFoamStrength(val) {
+        this._shoreWaves.shorelineFoamStrength = Math.max(0, val);
+    }
+    /** How opaque the foam is that the water makes against walls, rocks and piers standing in it, 0..1; it always rings them whole. */ get wallFoamStrength() {
+        return this._shoreWaves.wallFoamStrength;
+    }
+    set wallFoamStrength(val) {
+        this._shoreWaves.wallFoamStrength = Math.min(Math.max(val, 0), 1);
+        this.uniformChanged();
+    }
+    /** Speed in metres per second the water has to hit a wall at before it makes any foam there. */ get wallFoamMinSpeed() {
+        return this._shoreWaves.wallFoamMinSpeed;
+    }
+    set wallFoamMinSpeed(val) {
+        this._shoreWaves.wallFoamMinSpeed = Math.max(0, val);
+    }
+    /** Speed in metres per second at which water hitting a wall makes the most foam. */ get wallFoamMaxSpeed() {
+        return this._shoreWaves.wallFoamMaxSpeed;
+    }
+    set wallFoamMaxSpeed(val) {
+        this._shoreWaves.wallFoamMaxSpeed = Math.max(0.01, val);
+    }
+    /** Speed in metres per second the foam drifts out from walls, rocks and piers at: higher for a wider ring of foam around them. */ get wallFoamDrift() {
+        return this._shoreWaves.wallFoamDrift;
+    }
+    set wallFoamDrift(val) {
+        this._shoreWaves.wallFoamDrift = Math.max(0, val);
+    }
+    /**
+   * Seconds the foam each breaking wave brings in lasts: higher for longer
+   * white trails behind the crests and foam that stays on the swash all the
+   * way up the beach, lower for brief flashes of white at the crests.
+   */ get surfFoamDuration() {
+        return this._shoreWaves.surfFoamDuration;
+    }
+    set surfFoamDuration(val) {
+        this._shoreWaves.surfFoamDuration = Math.max(0.05, val);
+    }
+    /**
+   * Water depth in metres at and below which foam stops drifting and stays
+   * where it is: higher to leave foam lying over a wider band of the shallows
+   * and the beach, lower to let it drift until the water is almost gone.
+   */ get foamSettleDepth() {
+        return this._shoreWaves.foamSettleDepth;
+    }
+    set foamSettleDepth(val) {
+        this._shoreWaves.foamSettleDepth = Math.max(0, val);
+    }
+    /**
+   * Water depth in metres at and beyond which foam drifts freely: higher to
+   * slow the foam over a wider band of shallow water, lower to keep it moving
+   * until close in.
+   */ get foamDriftDepth() {
+        return this._shoreWaves.foamDriftDepth;
+    }
+    set foamDriftDepth(val) {
+        this._shoreWaves.foamDriftDepth = Math.max(0, val);
+    }
+    /**
+   * How fast foam that has settled in shallow water and on the sand fades, as
+   * a share of the foam's fade: lower to leave it lying on the beach longer
+   * after the wave has drained, 1 to fade it as fast as foam on open water.
+   */ get settledFoamFade() {
+        return this._shoreWaves.settledFoamFade;
+    }
+    set settledFoamFade(val) {
+        this._shoreWaves.settledFoamFade = Math.min(Math.max(val, 0.01), 1);
+    }
+    /**
+   * Hands the shore waves this frame's waterline fields: the shore field in
+   * levels, null when there is none, which turns them off; and the wall field,
+   * null for no foam against walls. Called by the water every frame.
+   * @internal
+   */ setShoreWaveFrame(shore, shoreRegions, wall, wallRegion, level) {
+        this._shoreWaveGenerator?.setFrame(shore, shoreRegions, wall, wallRegion, level, this._waveClock);
+    }
+    /**
+   * Steps the foam field around the water the view looks at, once a frame
+   * however many views there are. Called by the water after
+   * {@link setShoreWaveFrame}, which its sources read.
+   * @param focusX - World x the field is centred on.
+   * @param focusZ - World z the field is centred on.
+   * @internal
+   */ updateFoamField(focusX, focusZ) {
+        if (!this._foamSource || this._foamFrameId === this._frameId) {
+            return;
+        }
+        this._foamFrameId = this._frameId;
+        this._foamField.stepAround(focusX, focusZ, this._waveClock, this._waveGenerator.get()?.wind ?? null, this._foamSource);
     }
     update(frameId, elapsed) {
+        this._frameId = frameId;
+        this._waveClock = elapsed;
+        // The base generator and the field are stepped separately, each guarded by
+        // its own per-frame mark, so a generator shared between two bodies of water
+        // is still stepped once even when each body wraps it with its own field.
         const waveGenerator = this._waveGenerator.get();
         if (waveGenerator) {
             const updateFrameId = WaterMaterial._waveUpdateState.get(waveGenerator);
             if (updateFrameId !== frameId) {
-                waveGenerator.update(elapsed);
+                RenderGraphExecutor.profileScope('WaterWaves', ()=>waveGenerator.update(elapsed));
                 WaterMaterial._waveUpdateState.set(waveGenerator, frameId);
             }
         }
-    }
-    _getRampTexture(device, grad) {
-        const width = 128;
-        const height = 1;
-        const texture = device.createTexture2D('rgba8unorm', width, height, {
-            mipmapping: false
-        });
-        const numTexels = width * height;
-        const data = new Uint8Array(numTexels * 4);
-        const tmpcolor = new Vector3();
-        for(let i = 0; i < numTexels; i++){
-            grad.interpolate(i % width / width, tmpcolor);
-            data[i * 4 + 0] = tmpcolor.x * 255 >> 0;
-            data[i * 4 + 1] = tmpcolor.y * 255 >> 0;
-            data[i * 4 + 2] = tmpcolor.z * 255 >> 0;
-            data[i * 4 + 3] = 255;
-        }
-        texture.update(data, 0, 0, width, height);
-        return texture;
-    }
-    _getScatterRampTexture(device) {
-        if (!this._scatterRampTexture.get()) {
-            if (!WaterMaterial._defaultScatterRampTexture.get()) {
-                WaterMaterial._defaultScatterRampTexture.set(this._getRampTexture(device, WaterMaterial._scatterGrad));
-            }
-            this._scatterRampTexture.set(WaterMaterial._defaultScatterRampTexture.get());
-        }
-        return this._scatterRampTexture.get();
-    }
-    _getAbsorptionRampTexture(device) {
-        if (!this._absorptionRampTexture.get()) {
-            if (!WaterMaterial._defaultAbsorptionRampTexture.get()) {
-                WaterMaterial._defaultAbsorptionRampTexture.set(this._getRampTexture(device, WaterMaterial._absorptionGrad));
+        const interaction = this._interaction.get();
+        if (interaction && this._interactiveWaveGenerator) {
+            const updateFrameId = WaterMaterial._interactionUpdateState.get(interaction);
+            if (updateFrameId !== frameId) {
+                RenderGraphExecutor.profileScope('WaterInteraction', ()=>interaction.update(elapsed));
+                WaterMaterial._interactionUpdateState.set(interaction, frameId);
             }
-            this._absorptionRampTexture.set(WaterMaterial._defaultAbsorptionRampTexture.get());
         }
-        return this._absorptionRampTexture.get();
     }
 }