@call-me-sensei/toonlab 0.2.0 → 0.3.0

package/src/shaders-tsl/water.js

@@ -45,9 +45,12 @@ import {
   mix,
   modelWorldMatrix,
   normalize,
+  pow,
   positionGeometry,
+  refract,
   screenUV,
   select,
+  sin,
   smoothstep,
   texture,
   uniform,
@@ -61,11 +64,16 @@ import { NodeMaterial } from 'three/webgpu';
 
 import { sampleEnvironmentSunShadow } from './chunks/environment-sun-shadow.js';
 import { stylizedCloudShadow } from './chunks/stylized-cloud-shadow.js';
-import { waterCombineNormal, waterFbm, waterRotate2d } from './chunks/water-common.js';
+import {
+  waterCombineNormal,
+  waterFbm,
+  waterRotate2d,
+} from './chunks/water-common.js';
 import { createWaterColorChunk } from './chunks/water-color.js';
 import { createWaterFoamChunk } from './chunks/water-foam.js';
 import { createWaterLightingChunk } from './chunks/water-lighting.js';
 import { createWaterRippleChunk } from './chunks/water-ripple.js';
+import { createWaterShoreStateChunk } from './chunks/water-shore-state.js';
 import { createWaterWavesChunk } from './chunks/water-waves.js';
 
 // Node-backend placeholders: same roles as waterMaterial.js's placeholders,
@@ -86,6 +94,7 @@ function getPlaceholders() {
       reflection: createLinearPlaceholder([126, 190, 218, 255]),
       ripple: createLinearPlaceholder([128, 128, 128, 255]),
       sceneColor: createLinearPlaceholder([80, 150, 190, 255]),
+      shoreState: createLinearPlaceholder([0, 0, 0, 0]),
     };
   }
   return placeholders;
@@ -179,9 +188,26 @@ export function createWaterNodeMaterial({
     uRippleTexel: uniform(new THREE.Vector2(1 / 256, 1 / 256)),
     uRippleHeightScale: uniform(1),
 
+    uShoreStateMap: texture(holders.shoreState),
+    uUseShoreState: uniform(0),
+    uShoreStateRegion: uniform(new THREE.Vector4(0, 0, 1, 1)),
+
     uShoalingDepth: uniform(1.4),
     uShorelineWaves: uniform(0.35),
     uShorelineRunup: uniform(0.6),
+    uRunupDistance: uniform(0),
+    // Runtime event envelope supplied by WaterSurface. Keeping the irregular
+    // sequence on the CPU avoids expanding the already-dense WebGPU graph.
+    uSwashRunupScale: uniform(1),
+    uSwashStartOffset: uniform(0),
+    uSwashEndOffset: uniform(0),
+    uSwashCycle: uniform(0),
+    uSwashProgress: uniform(0),
+    uSwashIncidenceX: uniform(0),
+    // (phase radians, alongshore frequency rad/m, amplitude metres).
+    uSwashEdgeShape: uniform(new THREE.Vector3(0, 0.1, 0)),
+    uBreakerEnabled: uniform(1),
+    uBreakerAmount: uniform(0.5),
     uWaveEnergy: uniform(0.3),
 
     uWavesA: waterArrayUniformEntry(wavesANode),
@@ -199,12 +225,16 @@ export function createWaterNodeMaterial({
     uDeepFadeDistance: uniform(3),
     uOpacity: uniform(0.9),
     uRefractionStrength: uniform(0.6),
+    uIndexOfRefraction: uniform(1.333),
+    uUnderwaterTransmission: uniform(1.0),
+    uUnderwaterTintStrength: uniform(0.35),
     uCausticsStrength: uniform(0.6),
     uCausticsScale: uniform(1),
     uCausticsSpeed: uniform(1),
 
     uFoamColor: uniform(new THREE.Color()),
     uFoamAmount: uniform(1),
+    uSwashFoamAmount: uniform(1.15),
     uFoamContactDistance: uniform(1),
     uFoamLineSpacing: uniform(1.4),
     uFoamNoiseScale: uniform(0.6),
@@ -240,6 +270,7 @@ export function createWaterNodeMaterial({
 
   const waves = createWaterWavesChunk({ wavesA: wavesANode, wavesB: wavesBNode, waveCount });
   const ripple = createWaterRippleChunk({ u });
+  const shoreState = createWaterShoreStateChunk({ u });
   const color = createWaterColorChunk({ u, flags });
   const foam = createWaterFoamChunk({ u, foamOctaves });
   const lighting = createWaterLightingChunk({ u });
@@ -257,10 +288,17 @@ export function createWaterNodeMaterial({
   const vWorldPosition = varying(vec3(), 'vWaterWorldPosition');
   const vRestWorldXZ = varying(vec2(), 'vWaterRestWorldXZ');
   const vCrest = varying(float(), 'vWaterCrest');
+  const vGerstnerNormal = varying(vec3(), 'vWaterGerstnerNormal');
   const vShoal = varying(float(), 'vWaterShoal');
   const vBreaker = varying(float(), 'vWaterBreaker');
-  const vSwash = varying(float(), 'vWaterSwash');
-  const vChop = varying(float(), 'vWaterChop');
+  // The connected wet/dry geometry is evaluated per vertex, but foam noise
+  // is evaluated per fragment. Passing only these smooth physical inputs
+  // avoids exposing the water grid as large triangular white patches.
+  const vSwashFoamData = varying(vec2(), 'vWaterSwashFoamData');
+  // Small shore-normal foam drift. This never displaces geometry: amplifying
+  // Gerstner's horizontal orbit folded the near-shore grid into white wedges.
+  const vSwashSurge = varying(vec2(), 'vWaterSwashSurge');
+  const vSwashZone = varying(float(), 'vWaterSwashZone');
   // Rest-pose column depth (waterline − bed). Deeply negative = the surface
   // is under dry land; the fragment shader discards those fragments so
   // triangles spanning a cliff face can't poke through the terrain.
@@ -277,9 +315,9 @@ export function createWaterNodeMaterial({
     const shoal = float(1.0).toVar();
     const rippleShoal = float(1.0).toVar();
     const breakFoam = float(0.0).toVar();
-    const swash = float(0.0).toVar();
 
     let rawWave;
+    let nearshore = null;
     const waveDisplacement = vec3(0.0).toVar();
     if (flags.shoaling) {
       const aBedHeight = attribute('aBedHeight', 'float');
@@ -289,7 +327,30 @@ export function createWaterNodeMaterial({
       const shoalRange = max(max(u.uShoalingDepth, u.uWaveEnergy.mul(2.2)), 1e-3).toVar();
       chopWeight.assign(mix(0.15, 1.0, smoothstep(shoalRange.mul(0.3), shoalRange.mul(1.4), restDepth)));
 
-      rawWave = waves.gerstnerDisplacementFiltered(restXZ, u.uTime, chopWeight).toVar();
+      // Packed CPU-baked mild-slope field: q, dq/dx, dq/dz, slot mask. It is fully
+      // active through the breaker/swash handoff, fades back to the original
+      // plane phase over a broad deep-water band, and only affects the two
+      // dominant swell slots. The attribute is a plane-wave fallback on
+      // stages where the nearshore solve is disabled or invalid.
+      const aNearshorePhase = attribute('aNearshorePhase', 'vec4').toVar();
+      const nearshoreBlend = smoothstep(
+        shoalRange.mul(0.8),
+        shoalRange.mul(1.8),
+        restDepth,
+      ).oneMinus().toVar();
+      nearshore = {
+        phaseCoordinate: aNearshorePhase.x,
+        waveVector: aNearshorePhase.yz,
+        blend: nearshoreBlend,
+        slotMask: aNearshorePhase.w,
+      };
+
+      rawWave = waves.gerstnerDisplacementFiltered(
+        restXZ,
+        u.uTime,
+        chopWeight,
+        nearshore,
+      ).toVar();
 
       // Stylized breaking-wave shoaling (see water.vert.glsl for the model).
       const deepFactor = smoothstep(0.0, shoalRange, restDepth);
@@ -305,12 +366,99 @@ export function createWaterNodeMaterial({
       const brokenY = min(targetY, capY).add(capExcess.mul(0.1)).toVar();
       // A trough can never dip below the seabed.
       brokenY.assign(max(brokenY, max(restDepth, 0.0).negate().add(0.04)));
-      breakFoam.assign(clamp(capExcess.mul(0.9).div(max(u.uWaveEnergy.mul(0.3), 1e-3)), 0.0, 1.0));
+      breakFoam.assign(
+        clamp(capExcess.mul(0.9).div(max(u.uWaveEnergy.mul(0.3), 1e-3)), 0.0, 1.0)
+          .mul(u.uBreakerAmount)
+          .mul(u.uBreakerEnabled),
+      );
 
-      const wavePhase = clamp(rawWave.y.div(max(u.uWaveEnergy, 1e-3)), -1.0, 1.0).toVar();
-      const runup = u.uShorelineRunup.mul(u.uWaveEnergy).mul(max(wavePhase, 0.0));
-      // Dry land tucks the film 20cm under the terrain.
-      const film = clamp(restDepth.add(runup), -0.2, 0.05).toVar();
+      // The surf hands into one connected swash event. The dominant crest's
+      // shoreline arrival starts a quick uprush; gravity then owns the longer
+      // drain. Offshore Gerstner phase still sets the visible incidence angle,
+      // while the wet/dry edge remains one inequality instead of many islands.
+      const aBedSlope = attribute('aBedSlope', 'float');
+      const aBedGradient = attribute('aBedGradient', 'vec2').toVar();
+      const bedSlope = max(aBedSlope, 0.005).toVar();
+      const shoreDirection = aBedGradient.div(max(length(aBedGradient), 0.005)).toVar();
+      const alongDirection = vec2(shoreDirection.y, shoreDirection.x.negate()).toVar();
+      const alongCoordinate = dot(restXZ, alongDirection).toVar();
+      // WaterSurface computes this frame once on the CPU and shares it with
+      // the persistent foam/wetness pass. That keeps the visible lip, foam
+      // injection, and wet-sand history on the exact same event and removes a
+      // duplicate phase/easing stack from this already-large shader.
+      const swashCycle = u.uSwashCycle.toVar();
+      const swashProgress = u.uSwashProgress.toVar();
+
+      // The user setting is the maximum horizontal reach. Runtime event
+      // uniforms vary ordinary peaks over 80–100%, carry the previous rundown
+      // endpoint into the next uprush, and let each backwash stop at a slightly
+      // different point around the still-water shoreline.
+      const explicitRunup = u.uRunupDistance.greaterThan(0.01);
+      const maximumHorizontalReach = select(
+        explicitRunup,
+        u.uRunupDistance,
+        u.uShorelineRunup.mul(u.uWaveEnergy).div(bedSlope),
+      ).toVar();
+      const runupDistance = maximumHorizontalReach
+        .mul(select(explicitRunup, u.uSwashRunupScale, 1.0)).toVar();
+      const startOffset = select(explicitRunup, u.uSwashStartOffset, 0.0).toVar();
+      const endOffset = select(explicitRunup, u.uSwashEndOffset, 0.0).toVar();
+      const edgeDistance = select(
+        swashCycle.lessThan(0.34),
+        mix(startOffset, runupDistance, swashProgress),
+        mix(endOffset, runupDistance, swashProgress),
+      ).toVar();
+      const maximumSwashReach = maximumHorizontalReach.mul(bedSlope).toVar();
+      // Match the incoming oblique crest instead of marching the whole beach
+      // forward like a ruler. A broad tilt supplies the incidence angle; two
+      // small traveling scallops break up the lip without splitting it.
+      // Retain a modest angle even at nominal rest/full reach: an oblique
+      // crest reaches one end of a real beach first. Forcing every X column
+      // onto the same endpoint created the conspicuous horizontal ruler line.
+      const edgeEnvelope = mix(0.18, 1.0, sin(swashProgress.mul(Math.PI))).toVar();
+      const incidenceSlope = clamp(u.uSwashIncidenceX.mul(0.52), -0.2, 0.2).toVar();
+      const rawEdgeTilt = alongCoordinate.mul(incidenceSlope).negate().toVar();
+      // Bounded soft-sign: preserves the local crest angle without ever
+      // reaching a flat clamp. The former unbounded x*slope term reached
+      // ±22 m across this lab and pinned whole shoreline blocks to one cap.
+      const edgeTilt = rawEdgeTilt.div(abs(rawEdgeTilt).div(2.0).add(1.0)).toVar();
+      const edgeScallop = sin(alongCoordinate.mul(0.32).sub(u.uTime.mul(0.35)))
+        .sub(sin(u.uTime.mul(-0.35)))
+        .add(
+          sin(alongCoordinate.mul(0.91).add(u.uTime.mul(0.18)))
+            .sub(sin(u.uTime.mul(0.18)))
+            .mul(0.35),
+        )
+        .mul(0.4);
+      // Broad per-event tongues make the actual water silhouette irregular,
+      // not merely the foam painted behind it. The squared cycle envelope is
+      // zero with zero velocity at event boundaries, so shape seeds may vary
+      // each wave without a shoreline pop. Subtracting the x=0 samples keeps
+      // the calibrated 8-10 m centerline reach unchanged.
+      const macroWave = sin(swashCycle.mul(Math.PI)).toVar();
+      const secondaryPhase = u.uSwashEdgeShape.x.mul(-0.71).toVar();
+      const edgeMacro = sin(
+        alongCoordinate.mul(u.uSwashEdgeShape.y).add(u.uSwashEdgeShape.x),
+      ).sub(sin(u.uSwashEdgeShape.x))
+        .add(
+          sin(
+            alongCoordinate.mul(u.uSwashEdgeShape.y).mul(2.35).add(secondaryPhase),
+          ).sub(sin(secondaryPhase)).mul(0.42),
+        )
+        .mul(u.uSwashEdgeShape.z)
+        .mul(macroWave.mul(macroWave))
+        .toVar();
+      const edgeHead = edgeDistance.mul(bedSlope)
+        .add(
+          edgeTilt.add(edgeScallop).mul(edgeEnvelope)
+            .add(edgeMacro)
+            .mul(bedSlope),
+        ).toVar();
+      const filmHead = restDepth.add(edgeHead).toVar();
+      // Behind the edge the sheet is centimetres deep, not a second full-body
+      // water plane. Dry vertices remain conformal just above the bed; the
+      // fragment-space signed head owns visibility, avoiding lifting rows.
+      const film = clamp(filmHead.mul(0.45).add(0.008), 0.003, 0.045).toVar();
       // Cap the drape: the film follows the bed up the beach, but a steep
       // bank (terraced shore, cliff base) puts a whole cliff step inside one
       // mesh cell — the dry vertex would ride 10m+ up the slope and drag
@@ -318,18 +466,37 @@ export function createWaterNodeMaterial({
       // wedges at distant shorelines). Real swash never climbs above ~½m
       // over the rest waterline, so clamp the geometry there and let the
       // vRestDepth fragment discard own the rest.
-      const filmY = min(aBedHeight.sub(worldPosition.y).add(film), 0.5);
-      const beach = smoothstep(-0.02, 0.06, restDepth).oneMinus().toVar();
-
-      rippleShoal.assign(smoothstep(0.0, 0.12, restDepth));
-      swash.assign(beach.mul(smoothstep(0.004, 0.02, film)).mul(wavePhase.mul(0.45).add(0.55)));
+      const filmY = min(
+        aBedHeight.sub(worldPosition.y).add(film),
+        max(0.5, maximumSwashReach.mul(1.1)),
+      );
+      // Hand off over the last ~4 m of the 1:20 profile. Deeper water stays
+      // the Gerstner surface, preventing the visible "three stacked systems"
+      // boundary that a reach-sized blend band created.
+      const beach = smoothstep(0.06, 0.22, restDepth).oneMinus().toVar();
+      vSwashZone.assign(beach);
+
+      rippleShoal.assign(smoothstep(0.0, 0.18, restDepth));
+      const foamWidth = max(bedSlope.mul(0.68), 0.018).toVar();
+      vSwashFoamData.assign(vec2(filmHead, foamWidth));
+      breakFoam.mulAssign(beach.oneMinus());
       shoal.mulAssign(beach.oneMinus());
+      // Foam moves metres with the sheet, not a token 24 cm texture wobble.
+      // Continuous alongshore drift plus the non-resetting animation clock
+      // prevents successive drains retracing the exact same texture path.
+      const surgeDistance = min(runupDistance.mul(0.32), 3.2).toVar();
+      const swashDrift = shoreDirection.mul(swashProgress).mul(surgeDistance)
+        .add(alongDirection.mul(sin(u.uTime.mul(0.37))).mul(swashProgress).mul(0.55));
+      vSwashSurge.assign(swashDrift.mul(beach));
       waveDisplacement.assign(vec3(
         rawWave.x.mul(shoal),
         mix(brokenY, filmY, beach),
         rawWave.z.mul(shoal),
       ));
     } else {
+      vSwashSurge.assign(vec2(0.0));
+      vSwashZone.assign(float(0.0));
+      vSwashFoamData.assign(vec2(-1.0, 0.018));
       vRestDepth.assign(float(1000.0));
       rawWave = waves.gerstnerDisplacementFiltered(restXZ, u.uTime, chopWeight).toVar();
       waveDisplacement.assign(rawWave);
@@ -341,12 +508,21 @@ export function createWaterNodeMaterial({
     worldPosition.xyz.addAssign(waveDisplacement);
     worldPosition.y.addAssign(rippleHeight);
 
-    const { crest } = waves.gerstnerNormalFiltered(restXZ, u.uTime, chopWeight);
-    vCrest.assign(crest.mul(clamp(shoal, 0.0, 1.0)));
-    vChop.assign(chopWeight);
+    // Evaluate the analytic long-wave frame once per vertex. The former
+    // per-fragment eight-wave loop was the largest source of WebGPU private
+    // address-space pressure; interpolating this macro normal leaves the
+    // fragment stage's high-frequency detail and ripple normals intact.
+    const gerstner = waves.gerstnerNormalFiltered(
+      restXZ,
+      u.uTime,
+      chopWeight,
+      nearshore,
+    );
+    const shoalBlend = clamp(shoal, 0.0, 1.0).toVar();
+    vGerstnerNormal.assign(normalize(mix(vec3(0.0, 1.0, 0.0), gerstner.normal, shoalBlend)));
+    vCrest.assign(gerstner.crest);
     vShoal.assign(shoal);
     vBreaker.assign(breakFoam);
-    vSwash.assign(swash);
     vWorldPosition.assign(worldPosition.xyz);
 
     return cameraProjectionMatrix.mul(cameraViewMatrix).mul(vec4(worldPosition.xyz, 1.0));
@@ -354,28 +530,37 @@ export function createWaterNodeMaterial({
 
   // ---- Fragment stage (water.frag.glsl) ----
   material.fragmentNode = Fn(() => {
-    // Surface sections tucked under dry land (see vRestDepth) never shade:
-    // without this, water triangles spanning steep banks slice through the
-    // terrain as visible shards.
+    // Apply the nonlinear wet threshold after the signed film head has been
+    // interpolated. Evaluating smoothstep at sparse vertices first exposed
+    // individual triangle rows as the water advanced at a grazing angle.
     if (flags.shoaling) {
-      Discard(vRestDepth.lessThan(-0.35));
+      const fragmentWet = mix(
+        1.0,
+        smoothstep(-0.004, 0.012, vSwashFoamData.x),
+        clamp(vSwashZone, 0.0, 1.0),
+      );
+      Discard(fragmentWet.lessThan(0.015));
     }
     const screenUv = screenUV.toVar();
     const toCamera = cameraPosition.sub(vWorldPosition).toVar();
     const viewDir = normalize(toCamera).toVar();
     const viewDistance = length(toCamera).toVar();
 
-    // --- surface normal: Gerstner (analytic, per-pixel) + fbm detail + ripples ---
-    const gerstner = waves.gerstnerNormalFiltered(vRestWorldXZ, u.uTime, vChop);
-    const gerstnerNormal = vec3(gerstner.normal).toVar();
-    const crest = float(gerstner.crest).toVar();
+    // --- surface normal: interpolated Gerstner frame + fbm detail + ripples ---
+    const gerstnerNormal = normalize(vGerstnerNormal).toVar();
+    const crest = float(vCrest).toVar();
     const shoalBlend = clamp(vShoal, 0.0, 1.0).toVar();
-    gerstnerNormal.assign(normalize(mix(vec3(0.0, 1.0, 0.0), gerstnerNormal, shoalBlend)));
     crest.assign(clamp(crest.mul(shoalBlend).add(vBreaker.mul(crest.mul(0.55).add(0.45))), 0.0, 1.0));
     const gerstnerNormalY = gerstnerNormal.y.toVar();
 
     const detailFade = smoothstep(16.0, 60.0, viewDistance).oneMinus();
-    const detailStrength = u.uDetailNormalStrength.mul(mix(0.2, 1.0, detailFade)).toVar();
+    const swashOptics = clamp(vSwashZone, 0.0, 1.0).toVar();
+    // A centimetres-thin film is optically smooth at this camera scale. Full
+    // open-water normal detail turned every texel into a bright grazing-angle
+    // mirror and made the swash look like an opaque sheet of snow.
+    const detailStrength = u.uDetailNormalStrength
+      .mul(mix(0.2, 1.0, detailFade))
+      .mul(mix(1.0, 0.18, swashOptics)).toVar();
     const flowOffset = u.uFlowDirection.mul(u.uTime).mul(u.uFlowSpeed).toVar();
     const detailUv1 = vRestWorldXZ.mul(u.uDetailScale).add(flowOffset.mul(0.55));
     const detailUv2 = waterRotate2d(1.9).mul(vRestWorldXZ).mul(u.uDetailScale.mul(1.63)).sub(flowOffset.mul(0.34));
@@ -398,18 +583,122 @@ export function createWaterNodeMaterial({
     const output = vec4(0.0).toVar();
     If(u.uCameraBelow.greaterThan(0.5), () => {
       // --- underside: camera below the surface looking up ---
-      // A stylized Snell-window: bright sky punches through overhead, the
-      // surface darkens to the deep tint toward grazing angles.
-      const throughDir = normalize(
-        viewDir.negate().add(vec3(surfaceNormal.x, 0.0, surfaceNormal.z).mul(0.7)),
+      // Trace the view ray from water into air. The grab pass uses a clipped
+      // same-pose camera while submerged, so this lookup contains the actual
+      // sky, clouds, and above-water silhouettes rather than a sky-color
+      // approximation. The physical critical angle anchors the composition;
+      // color and edge shaping stay deliberately stylized.
+      const incident = viewDir.negate().toVar();
+      const eta = clamp(u.uIndexOfRefraction, 1.0001, 1.8).toVar();
+      const cosIncident = clamp(dot(incident, surfaceNormal), 0.0, 1.0).toVar();
+      const criticalCos = max(
+        float(1.0).sub(float(1.0).div(eta.mul(eta))),
+        0.0,
+      ).sqrt().toVar();
+      const snellWindow = smoothstep(
+        criticalCos.sub(0.04),
+        criticalCos.add(0.045),
+        cosIncident,
+      ).toVar();
+      const refractedDirection = refract(
+        incident,
+        surfaceNormal.negate(),
+        eta,
+      ).toVar();
+      // refract() returns zero under total internal reflection. Blend toward
+      // the incident ray there to keep the projection numerically stable;
+      // snellWindow prevents that fallback ray from becoming transmission.
+      const transmissionDirection = normalize(mix(
+        incident,
+        refractedDirection,
+        max(snellWindow, 0.001),
+      )).toVar();
+      const transmissionWorld = vWorldPosition.add(
+        transmissionDirection.mul(min(u.uCameraFar.mul(0.75), 400.0)),
+      );
+      const transmissionClip = cameraProjectionMatrix
+        .mul(cameraViewMatrix)
+        .mul(vec4(transmissionWorld, 1.0)).toVar();
+      const transmissionUv = transmissionClip.xy
+        .div(max(abs(transmissionClip.w), 1e-5))
+        .mul(vec2(0.5, -0.5))
+        .add(0.5)
+        .add(refractionNormal.xz.mul(u.uRefractionStrength).mul(0.012))
+        .toVar();
+      const insideCapture = smoothstep(-0.01, 0.01, transmissionUv.x)
+        .mul(smoothstep(0.99, 1.01, transmissionUv.x).oneMinus())
+        .mul(smoothstep(-0.01, 0.01, transmissionUv.y))
+        .mul(smoothstep(0.99, 1.01, transmissionUv.y).oneMinus())
+        .mul(smoothstep(0.001, 0.03, transmissionClip.w));
+      const capturedAir = u.uSceneColor
+        .sample(clamp(transmissionUv, vec2(0.0), vec2(1.0)))
+        .level(0).rgb;
+      const transmitted = mix(
+        lighting.proceduralSky(transmissionDirection),
+        capturedAir,
+        clamp(insideCapture.mul(u.uUseSceneColor), 0.0, 1.0),
+      ).toVar();
+
+      // Compact Beer-Lambert-inspired attenuation through the camera's water
+      // column. This uses ToonLab's authored palette, keeping the result
+      // graphic and readable instead of pursuing the reference's realism.
+      const cameraDepth = max(vWorldPosition.y.sub(cameraPosition.y), 0.0).toVar();
+      const volumeAbsorb = exp(
+        cameraDepth.div(max(
+          u.uDepthFadeDistance.add(u.uDeepFadeDistance.mul(0.5)),
+          0.1,
+        )).negate(),
+      ).oneMinus().toVar();
+      const waterTint = mix(
+        u.uShallowColor,
+        u.uMidColor,
+        clamp(volumeAbsorb.mul(1.35), 0.0, 1.0),
+      ).toVar();
+      transmitted.mulAssign(mix(
+        vec3(1.0),
+        waterTint.mul(1.12),
+        volumeAbsorb.mul(0.3),
+      ));
+      transmitted.assign(mix(
+        transmitted,
+        waterTint,
+        volumeAbsorb.mul(u.uUnderwaterTintStrength),
+      ));
+
+      const f0 = eta.sub(1.0).div(eta.add(1.0)).pow2().toVar();
+      const fresnel = f0.add(
+        f0.oneMinus().mul(pow(cosIncident.oneMinus(), 5.0)),
+      ).toVar();
+      const transmissionWeight = fresnel.oneMinus()
+        .mul(snellWindow)
+        .mul(u.uUnderwaterTransmission)
+        .toVar();
+      const tirColor = mix(
+        u.uDeepColor.mul(0.48),
+        u.uMidColor.mul(0.72),
+        cosIncident.mul(0.3),
+      );
+      const underColor = mix(
+        tirColor,
+        transmitted,
+        clamp(transmissionWeight, 0.0, 1.0),
       ).toVar();
-      const skyThrough = lighting.proceduralSky(throughDir);
-      const window = smoothstep(0.15, 0.8, throughDir.y).toVar();
-      const underColor = mix(u.uDeepColor.mul(0.55), skyThrough.mul(1.15), window).toVar();
+      const criticalRim = smoothstep(
+        criticalCos.sub(0.085),
+        criticalCos,
+        cosIncident,
+      ).mul(smoothstep(
+        criticalCos,
+        criticalCos.add(0.1),
+        cosIncident,
+      ).oneMinus());
+      underColor.addAssign(u.uFresnelColor.mul(criticalRim).mul(0.12));
       underColor.addAssign(
         lighting.sparkles(vRestWorldXZ, surfaceNormal, viewDir, viewDistance, u.uTime).mul(0.5),
       );
-      output.assign(vec4(underColor, mix(0.95, 0.62, window)));
+      // The captured air-side scene is already composited; render the
+      // underside opaque to avoid double-blending the main scene behind it.
+      output.assign(vec4(underColor, 1.0));
     }).Else(() => {
       // --- scene depth, refraction, and the water body color ---
       const waterViewDistance = cameraViewMatrix.mul(vec4(vWorldPosition, 1.0)).z.negate().toVar();
@@ -440,6 +729,14 @@ export function createWaterNodeMaterial({
         bodyColor.assign(absorptionTint);
         alpha.assign(clamp(u.uOpacity.add(absorb.mul(0.3)), 0.0, 1.0));
       });
+      // A thin film still has a readable water body. Preserve enough of the
+      // sand for a wet-ground cue, but keep the shallow tint and sky sheen so
+      // the run-up remains visibly connected to the sea.
+      const clearScene = u.uSceneColor.sample(screenUv).level(0).rgb;
+      const wetScene = clearScene.mul(0.85);
+      const clearSceneWeight = select(u.uUseSceneColor.greaterThan(0.5), 0.48, 0.0);
+      bodyColor.assign(mix(bodyColor, wetScene, swashOptics.mul(clearSceneWeight)));
+      bodyColor.assign(mix(bodyColor, u.uShallowColor, swashOptics.mul(0.18)));
 
       // Steep wave faces act like windows, not lenses: drop caustics there,
       // and fade the dappling with view distance (WATER_QUALITY >= 1).
@@ -451,17 +748,77 @@ export function createWaterNodeMaterial({
         : vec3(0.0);
 
       // --- foam ---
+      // Foam pattern follows the swash sheet's orbital surge (zero offshore),
+      // so the drain visibly pulls the foam seaward instead of the pattern
+      // staying glued to rest space while only the envelope moves.
+      const foamXZ = vRestWorldXZ.sub(vSwashSurge).toVar();
       const pierce = color.pierceProximity(screenUv, waterViewDistance, vWorldPosition.y).toVar();
-      const shoreFoam = foam.shoreFoam(columnDepth, viewDepthDiff, vRestWorldXZ, u.uTime, pierce).toVar();
-      const whitecaps = foam.whitecaps(crest, gerstnerNormalY, vRestWorldXZ, u.uTime).toVar();
+      const shoreFoam = foam.shoreFoam(columnDepth, viewDepthDiff, foamXZ, u.uTime, pierce)
+        // The legacy contact mask assumes a water body deeper than the foam
+        // distance. On a centimetre-thin swash film it is almost 1 everywhere,
+        // so keep its familiar offshore/rock character but let the dedicated
+        // turbulent edge above own the beach foam.
+        .mul(mix(1.0, 0.05, clamp(vSwashZone, 0.0, 1.0))).toVar();
+      const whitecaps = foam.whitecaps(crest, gerstnerNormalY, foamXZ, u.uTime).toVar();
       const rippleFoamRaw = clamp(
         rippleState.b.mul(u.uRippleFoamStrength).add(abs(rippleState.r).mul(u.uRippleFoamStrength).mul(4.0)),
         0.0,
         1.0,
       );
-      const foamRaw = clamp(shoreFoam.add(whitecaps).add(rippleFoamRaw).add(vSwash), 0.0, 1.0)
-        .mul(clamp(u.uFoamAmount, 0.0, 2.0));
-      const foamValue = foam.foamShape(foamRaw, vRestWorldXZ, u.uTime).toVar();
+      const swashFoamRaw = float(0.0).toVar();
+      const persistentShoreState = flags.shoaling
+        ? shoreState.shoreStateSample(vRestWorldXZ)
+        : vec4(0.0);
+      if (flags.shoaling) {
+        // The temporal shore field owns transport, decay, breakup, and
+        // event-to-event variation. Keep this main material deliberately
+        // small: duplicating procedural noise here can exceed WebGPU's hard
+        // 8 KiB private-variable budget for StylizedWater.
+        If(vSwashZone.greaterThan(0.001), () => {
+          const filmHead = vSwashFoamData.x.toVar();
+          const foamWidth = max(vSwashFoamData.y, 0.018).toVar();
+          const fallbackBand = smoothstep(-0.006, 0.004, filmHead)
+            .mul(smoothstep(foamWidth.mul(0.7), foamWidth.mul(1.25), filmHead).oneMinus());
+          const storedFoam = clamp(
+            // The state pass deliberately stores low-energy values so its
+            // advection remains stable. Remap those values into the original
+            // foamShape range here: the former 0.16..0.58 / 0.82 mapping
+            // required active state B ~= 0.34 before a single solid pixel
+            // could appear, and residue A could never reach the shape's
+            // onset at all. Active foam gets the lower presentation onset;
+            // residue stays a quiet modifier so old events cannot rebuild a
+            // continuous bright shoreline. This does not add a coverage
+            // floor or refill the source's true gaps.
+            smoothstep(0.12, 0.48, persistentShoreState.b).mul(0.9)
+              .add(smoothstep(0.25, 0.7, persistentShoreState.a).mul(0.18)),
+            0.0,
+            1.0,
+          );
+          swashFoamRaw.assign(
+            max(
+              storedFoam,
+              fallbackBand.mul(u.uUseShoreState.oneMinus()),
+            ).mul(vSwashZone),
+          );
+        });
+      }
+      const foamAmount = clamp(u.uFoamAmount, 0.0, 2.0).toVar();
+      const baseFoamRaw = clamp(
+        shoreFoam.add(whitecaps).add(vBreaker.mul(0.85)).add(rippleFoamRaw),
+        0.0,
+        1.0,
+      ).mul(foamAmount).toVar();
+      const swashFoamValue = clamp(
+        swashFoamRaw.mul(clamp(u.uSwashFoamAmount, 0.0, 2.0)),
+        0.0,
+        1.0,
+      ).toVar();
+      // The pre-session foam looked better because every source shared this
+      // crisp solid-core + dissolve-fringe shaping. Shape stored swash foam
+      // together with offshore/contact foam; never max an unshaped milky mask
+      // over the final result.
+      const foamRaw = max(baseFoamRaw, swashFoamValue).toVar();
+      const foamValue = foam.foamShape(foamRaw, foamXZ, u.uTime).toVar();
 
       // Drifting cloud shadows plus scene shadows (shared sun-shadow pass).
       const cloudShadow = stylizedCloudShadow(
@@ -470,19 +827,35 @@ export function createWaterNodeMaterial({
       );
       const sceneShadow = mix(1.0, sampleEnvironmentSunShadow(vWorldPosition), u.uSceneShadowStrength);
       const sunVisibility = cloudShadow.mul(sceneShadow).toVar();
+      // Keep one caustic field across the offshore body and the running sheet.
+      // The caustics chunk already fades from the sampled scene depth; applying
+      // an additional swash-zone multiplier here exposed the implementation
+      // handoff as a hard, visibly separate rendering system.
       bodyColor.addAssign(caustics.mul(foamValue.oneMinus()).mul(sunVisibility));
 
       // --- reflection, fresnel, glints ---
       const fresnel = lighting.fresnelFactor(viewDir, surfaceNormal).toVar();
       const reflection = lighting.reflectionColor(vWorldPosition, surfaceNormal, viewDir).toVar();
-      const reflectionMix = clamp(fresnel.mul(u.uReflectionStrength), 0.0, 0.92).toVar();
+      // Thin swash still catches the sky at its lip, but the interior should
+      // mostly reveal wet sand. Attenuate (rather than remove) its Fresnel,
+      // reflection and glints while keeping offshore water unchanged.
+      const swashLight = mix(1.0, 0.36, swashOptics).toVar();
+      const surfaceFresnel = fresnel.mul(swashLight).toVar();
+      const reflectionMix = clamp(
+        surfaceFresnel.mul(u.uReflectionStrength), 0.0, 0.92,
+      ).toVar();
       const litColor = mix(bodyColor, reflection, reflectionMix).toVar();
-      litColor.addAssign(u.uFresnelColor.mul(fresnel).mul(fresnel).mul(0.35));
-      litColor.addAssign(lighting.specular(viewDir, surfaceNormal, foamValue.mul(0.75).oneMinus()).mul(sunVisibility));
+      litColor.addAssign(
+        u.uFresnelColor.mul(surfaceFresnel).mul(surfaceFresnel).mul(0.35),
+      );
+      litColor.addAssign(
+        lighting.specular(viewDir, surfaceNormal, foamValue.mul(0.75).oneMinus())
+          .mul(sunVisibility).mul(swashLight),
+      );
       if (flags.sparkles) {
         litColor.addAssign(
           lighting.sparkles(vRestWorldXZ, surfaceNormal, viewDir, viewDistance, u.uTime)
-            .mul(foamValue.oneMinus()).mul(sunVisibility),
+            .mul(foamValue.oneMinus()).mul(sunVisibility).mul(swashLight),
         );
       }
       litColor.mulAssign(mix(vec3(0.8, 0.85, 0.94), vec3(1.0), sunVisibility));
@@ -490,11 +863,22 @@ export function createWaterNodeMaterial({
       // --- foam overlay, slightly shaded by the sun for a two-tone toon read ---
       const foamLight = clamp(dot(surfaceNormal, u.uSunDirection), 0.0, 1.0).mul(0.18).add(0.82)
         .mul(sunVisibility.mul(0.18).add(0.82));
-      litColor.assign(mix(litColor, u.uFoamColor.mul(foamLight), foamValue));
+      // Preserve the original bright foam, with just enough shallow-water
+      // shade at its porous fringe to show volume instead of flat white paint.
+      const foamShade = mix(u.uShallowColor, u.uFoamColor, 0.8).toVar();
+      const foamTint = mix(
+        foamShade,
+        u.uFoamColor.mul(foamLight),
+        smoothstep(0.5, 0.82, foamRaw),
+      ).toVar();
+      litColor.assign(mix(litColor, foamTint, foamValue));
       alpha.assign(max(alpha, foamValue.mul(0.92)));
       // The swash film is only centimeters deep; give it body.
-      alpha.assign(max(alpha, vSwash.mul(0.55)));
-      alpha.assign(max(alpha, clamp(reflectionMix.add(fresnel.mul(0.4)), 0.0, 1.0).mul(0.85)));
+      alpha.assign(max(alpha, swashFoamValue.mul(0.55)));
+      alpha.assign(max(
+        alpha,
+        clamp(reflectionMix.add(surfaceFresnel.mul(0.4)), 0.0, 1.0).mul(0.85),
+      ));
 
       // Fog last: foam, sparkles, and shorelines haze out with the rest of
       // the world. Exponential term mirrors the environment height fog;
@@ -530,6 +914,12 @@ export function createWaterNodeMaterial({
         )],
         [8, vec4(vec3(fresnel), 1.0)],
         [9, vec4(crest, vCrest, whitecaps, 1.0)],
+        [10, vec4(
+          persistentShoreState.r,
+          persistentShoreState.g,
+          max(persistentShoreState.b, persistentShoreState.a),
+          1.0,
+        )],
       ];
       let debugMask = float(0.0);
       let debugSum = vec4(0.0);