@call-me-sensei/toonlab 0.1.1

package/src/shaders-tsl/tree-leaf.js

@@ -0,0 +1,264 @@
+// TSL port of src/shaders/treeLeaf.vert.glsl + treeLeaf.frag.glsl (+ the
+// treeLeafDepth cutout depth variant) — world-anchored leaf-cluster cards
+// with the canopy-volume shading normal.
+//
+// The color material exposes userData.createDepthColorVariant() so the sun
+// shadow pass can render leafy cutout shadows with the exact same card
+// vertex placement (the classic path uses mesh.customDepthMaterial instead).
+
+import * as THREE from 'three';
+import {
+  abs,
+  attribute,
+  cameraFar,
+  cameraNear,
+  cameraPosition,
+  cameraProjectionMatrix,
+  cameraViewMatrix,
+  clamp,
+  cos,
+  cross,
+  Discard,
+  dot,
+  float,
+  Fn,
+  fract,
+  mat2,
+  mix,
+  modelWorldMatrix,
+  mat3,
+  normalize,
+  positionLocal,
+  pow,
+  select,
+  sin,
+  smoothstep,
+  texture,
+  uniform,
+  uv,
+  varying,
+  vec2,
+  vec3,
+  vec4,
+  viewZToOrthographicDepth,
+  viewZToPerspectiveDepth,
+} from 'three/tsl';
+import { NodeMaterial } from 'three/webgpu';
+
+import { sampleEnvironmentSunShadow } from './chunks/environment-sun-shadow.js';
+import { stylizedCloudShadow } from './chunks/stylized-cloud-shadow.js';
+import { applyFoliageFog, createFoliageFogUniforms } from './chunks/foliage-fog.js';
+
+// Shared card-placement vertex logic (color + depth variants). Returns the
+// clip position; assigns the provided varyings when given.
+function buildLeafVertexNode(u, { vUv, vWorldNormal, vWorldPosition, vTint, vHeightT, vViewZ }) {
+  return Fn(() => {
+    const aCorner = attribute('aCorner', 'vec2');
+    const aShadeNormal = attribute('aShadeNormal', 'vec3');
+    const aInfo = attribute('aInfo', 'vec4');
+
+    vUv.assign(uv());
+    if (vTint) vTint.assign(aInfo.z);
+    if (vHeightT) vHeightT.assign(aInfo.w);
+    if (vWorldNormal) vWorldNormal.assign(normalize(mat3(modelWorldMatrix).mul(aShadeNormal)));
+
+    const worldCenter = modelWorldMatrix.mul(vec4(positionLocal, 1.0)).toVar();
+
+    // Coherent canopy sway, stronger toward the crown.
+    const phase = u.uTime.mul(u.uWindSpeed).add(worldCenter.x.mul(0.6)).add(worldCenter.z.mul(0.5));
+    const sway = sin(phase).mul(0.6).add(sin(phase.mul(1.7).add(1.3)).mul(0.4));
+    worldCenter.xz.addAssign(
+      normalize(u.uWindDirection.add(vec2(1e-4, 0.0)))
+        .mul(sway).mul(u.uWindStrength).mul(aInfo.w.mul(0.75).add(0.25)),
+    );
+    if (vWorldPosition) vWorldPosition.assign(worldCenter.xyz);
+
+    // Static random roll per card + light flutter.
+    const roll = aInfo.y.mul(6.2831).add(
+      sin(u.uTime.mul(fract(aInfo.y.mul(7.31)).add(1.1)).mul(u.uWindSpeed).add(aInfo.y.mul(37.0))).mul(0.09),
+    );
+    const rollCos = cos(roll);
+    const rollSin = sin(roll);
+    // GLSL mat2(c, s, -s, c) is column-major; TSL matN() scalars are
+    // row-major — transposed argument order (docs/tsl-conventions.md).
+    const corner = mat2(rollCos, rollSin.negate(), rollSin, rollCos).mul(aCorner).mul(aInfo.x);
+
+    // World-anchored cylindrical billboard (cameraPosition is the light
+    // during the shadow pass, matching the classic depth-pass behavior).
+    const toCamera = cameraPosition.sub(worldCenter.xyz);
+    const facing = normalize(mix(
+      vec3(toCamera.x, 0.0, toCamera.z).add(vec3(1e-4, 0.0, 0.0)),
+      toCamera,
+      0.35,
+    ));
+    const cardRight = normalize(cross(vec3(0.0, 1.0, 0.0), facing));
+    const cardUp = normalize(cross(facing, cardRight));
+    worldCenter.xyz.addAssign(cardRight.mul(corner.x).add(cardUp.mul(corner.y)));
+
+    const viewPosition = cameraViewMatrix.mul(worldCenter).toVar();
+    if (vViewZ) vViewZ.assign(viewPosition.z);
+    return cameraProjectionMatrix.mul(viewPosition);
+  })();
+}
+
+export function createTreeLeafNodeMaterial(settings) {
+  const u = {
+    uAlphaCutoff: uniform(settings.alphaCutoff ?? 0.5),
+    uBacklitStrength: uniform(settings.backlitStrength ?? 0),
+    uCloudShadowCoverage: uniform(settings.cloudShadowCoverage ?? 0),
+    uCloudShadowScale: uniform(settings.cloudShadowScale ?? 1),
+    uCloudShadowStrength: uniform(settings.cloudShadowStrength ?? 0),
+    uCloudShadowVelocity: uniform(new THREE.Vector2(...(settings.cloudShadowVelocity ?? [0, 0]))),
+    uCrownColor: uniform(new THREE.Color()),
+    uLeafMap: texture(settings.leafMap),
+    uLitColor: uniform(new THREE.Color()),
+    uSceneShadowStrength: uniform(settings.sceneShadowStrength ?? 0),
+    uShadowColor: uniform(new THREE.Color()),
+    uSkyColor: uniform(new THREE.Color()),
+    uSunColor: uniform(new THREE.Color()),
+    uSunDirection: uniform(new THREE.Vector3(0.35, 0.75, 0.5).normalize()),
+    uTime: uniform(0),
+    uWindDirection: uniform(new THREE.Vector2(...(settings.windDirection ?? [1, 0.4]))),
+    uWindSpeed: uniform(settings.windSpeed ?? 1),
+    uWindStrength: uniform(settings.windStrength ?? 0.06),
+    ...createFoliageFogUniforms(),
+  };
+
+  const material = new NodeMaterial();
+  material.name = 'StylizedTreeFoliage';
+  // Manual fog (see chunks/foliage-fog.js): the custom billboard vertexNode
+  // makes three's built-in node fog read the wrong view depth.
+  material.fog = false;
+
+  const vUv = varying(vec2(), 'vLeafUv');
+  const vWorldNormal = varying(vec3(), 'vLeafWorldNormal');
+  const vWorldPosition = varying(vec3(), 'vLeafWorldPosition');
+  const vTint = varying(float(), 'vLeafTint');
+  const vHeightT = varying(float(), 'vLeafHeightT');
+  const vViewZ = varying(float(), 'vLeafViewZ');
+
+  material.vertexNode = buildLeafVertexNode(u, { vHeightT, vTint, vUv, vViewZ, vWorldNormal, vWorldPosition });
+
+  material.fragmentNode = Fn(() => {
+    const sprite = u.uLeafMap.sample(vUv).toVar();
+    Discard(sprite.a.lessThan(u.uAlphaCutoff));
+
+    const normal = normalize(vWorldNormal).toVar();
+    const sunDirection = normalize(u.uSunDirection);
+    const wrap = dot(normal, sunDirection).mul(0.5).add(0.5).toVar();
+    const cloudShadow = stylizedCloudShadow(
+      vWorldPosition.xz, u.uTime,
+      u.uCloudShadowStrength, u.uCloudShadowCoverage, u.uCloudShadowScale, u.uCloudShadowVelocity,
+    );
+    const sceneShadow = mix(1.0, sampleEnvironmentSunShadow(vWorldPosition), u.uSceneShadowStrength).toVar();
+    const sunVisibility = cloudShadow.mul(sceneShadow).toVar();
+
+    const litBand = smoothstep(0.38, 0.56, wrap).mul(sunVisibility).toVar();
+    const crestBand = smoothstep(0.66, 0.78, wrap).mul(sunVisibility)
+      .mul(smoothstep(0.3, 0.8, vHeightT.mul(normal.y.mul(0.5).add(0.5).mul(0.3).add(0.7))));
+
+    const color = mix(u.uShadowColor, u.uLitColor, litBand).toVar();
+    color.assign(mix(color, u.uCrownColor, crestBand));
+    color.mulAssign(mix(vec3(1.0), u.uSunColor, litBand.mul(0.35)));
+
+    // Baked per-leaf luminance + per-card jitter.
+    color.mulAssign(sprite.r.mul(0.36).add(0.78));
+    color.mulAssign(vTint.mul(0.16).add(0.92));
+
+    // Sky fill + silhouette rim.
+    color.addAssign(u.uSkyColor.mul(normal.y.mul(0.5).add(0.5)).mul(litBand.oneMinus()).mul(0.10));
+    const viewDirection = normalize(cameraPosition.sub(vWorldPosition));
+    const rim = pow(abs(dot(normal, viewDirection)).oneMinus(), 3.0);
+    color.addAssign(u.uSkyColor.mul(rim).mul(0.12).mul(vHeightT.mul(0.6).add(0.4)));
+
+    // Backlit translucency.
+    const backlit = pow(clamp(dot(viewDirection, sunDirection.negate()), 0.0, 1.0), 4.0);
+    color.addAssign(
+      u.uSunColor.mul(backlit).mul(u.uBacklitStrength)
+        .mul(sprite.r.mul(0.7).add(0.3))
+        .mul(sunVisibility.mul(0.65).add(0.35)),
+    );
+
+    // Occluded crowns read clearly darker.
+    color.mulAssign(mix(0.8, 1.0, sceneShadow));
+
+    // Manual linear scene fog on the true billboarded depth (see foliage-fog).
+    color.assign(applyFoliageFog(color, vViewZ, u));
+
+    return vec4(color, 1.0);
+  })();
+
+  material.uniforms = u;
+
+  // Native node-renderer shadow casting (tree/rock labs keep three's shadow
+  // system — no MMD skeletons there): the shadow pass takes a LOCAL-space
+  // position override plus a cutout mask. cameraPosition binds to the light
+  // during that pass, matching the classic depth-pass card facing; the world
+  // card placement is pulled back to local via the inverse model matrix.
+  material.castShadowPositionNode = (() => {
+    return Fn(() => {
+      const aCorner = attribute('aCorner', 'vec2');
+      const aInfo = attribute('aInfo', 'vec4');
+      const worldCenter = modelWorldMatrix.mul(vec4(positionLocal, 1.0)).toVar();
+      const phase = u.uTime.mul(u.uWindSpeed).add(worldCenter.x.mul(0.6)).add(worldCenter.z.mul(0.5));
+      const sway = sin(phase).mul(0.6).add(sin(phase.mul(1.7).add(1.3)).mul(0.4));
+      worldCenter.xz.addAssign(
+        normalize(u.uWindDirection.add(vec2(1e-4, 0.0)))
+          .mul(sway).mul(u.uWindStrength).mul(aInfo.w.mul(0.75).add(0.25)),
+      );
+      const roll = aInfo.y.mul(6.2831).add(
+        sin(u.uTime.mul(fract(aInfo.y.mul(7.31)).add(1.1)).mul(u.uWindSpeed).add(aInfo.y.mul(37.0))).mul(0.09),
+      );
+      const rollCos = cos(roll);
+      const rollSin = sin(roll);
+      const corner = mat2(rollCos, rollSin.negate(), rollSin, rollCos).mul(aCorner).mul(aInfo.x);
+      const toCamera = cameraPosition.sub(worldCenter.xyz);
+      const facing = normalize(mix(
+        vec3(toCamera.x, 0.0, toCamera.z).add(vec3(1e-4, 0.0, 0.0)),
+        toCamera,
+        0.35,
+      ));
+      const cardRight = normalize(cross(vec3(0.0, 1.0, 0.0), facing));
+      const cardUp = normalize(cross(facing, cardRight));
+      worldCenter.xyz.addAssign(cardRight.mul(corner.x).add(cardUp.mul(corner.y)));
+      return modelWorldMatrix.inverse().mul(worldCenter).xyz;
+    })();
+  })();
+  // Cutout in the shadow pass only (the custom fragmentNode bypasses
+  // maskNode in the main render).
+  material.maskNode = u.uLeafMap.sample(uv()).a.greaterThanEqual(u.uAlphaCutoff);
+
+  // Leafy cutout depth variant for the Water Lab's custom sun-shadow pass.
+  // Native WebGPU shadows consume castShadowPositionNode/maskNode from the
+  // source material, but Water Lab swaps in this material and renders a color
+  // depth target. Make it self-contained with the same full billboard vertex
+  // path, so it does not depend on native-shadow-only override hooks.
+  material.userData.createDepthColorVariant = () => {
+    const depthMaterial = new NodeMaterial();
+    depthMaterial.name = 'StylizedTreeFoliageDepth';
+    depthMaterial.side = THREE.DoubleSide;
+    depthMaterial.fog = false;
+    depthMaterial.isShadowPassMaterial = true;
+
+    const vDepthUv = varying(vec2(), 'vLeafDepthUv');
+    const vDepthViewZ = varying(float(), 'vLeafDepthViewZ');
+    depthMaterial.vertexNode = buildLeafVertexNode(u, {
+      vUv: vDepthUv,
+      vViewZ: vDepthViewZ,
+    });
+    depthMaterial.fragmentNode = Fn(() => {
+      const sprite = u.uLeafMap.sample(vDepthUv).toVar();
+      Discard(sprite.a.lessThan(u.uAlphaCutoff));
+      const orthographic = cameraProjectionMatrix.element(3).w.equal(1.0);
+      const depth01 = select(
+        orthographic,
+        viewZToOrthographicDepth(vDepthViewZ, cameraNear, cameraFar),
+        viewZToPerspectiveDepth(vDepthViewZ, cameraNear, cameraFar),
+      ).toVar();
+      return vec4(vec3(depth01), 1.0);
+    })();
+    return depthMaterial;
+  };
+
+  return material;
+}

package/src/shaders-tsl/water-breaker.js

@@ -0,0 +1,423 @@
+// TSL port of src/shaders/waterBreaker.vert.glsl + waterBreaker.frag.glsl —
+// the dedicated plunging-breaker shells that ride the dominant Gerstner crest.
+//
+// The shell must read as the SAME water as the open sea, so the fragment runs
+// the surface's shading stack through the shared water chunks, and the
+// factory can adopt the surface material's uniform NODES for the shared
+// lighting/wave uniforms (`shared` option). Sharing node objects across
+// materials is the TSL equivalent of the classic uniforms-by-reference wiring
+// in WaterBreakerSystem.attachWaveUniforms — swapping entries in `.uniforms`
+// after the graph is built would NOT rewire it, so attachWaveUniforms rebuilds
+// the material through this factory instead (before first render).
+//
+// TODO(tsl Phase 7): fog ordering — GLSL fogs after colorspace; scene fog is
+// disabled here until the fog phase resolves the ordering.
+
+import * as THREE from 'three';
+import {
+  clamp,
+  cos,
+  cross,
+  Discard,
+  dot,
+  float,
+  Fn,
+  If,
+  length,
+  max,
+  min,
+  mix,
+  modelWorldMatrix,
+  normalize,
+  positionGeometry,
+  select,
+  sin,
+  smoothstep,
+  sqrt,
+  step,
+  texture,
+  uniform,
+  uniformArray,
+  varying,
+  vec2,
+  vec3,
+  vec4,
+  attribute,
+  cameraPosition,
+  cameraProjectionMatrix,
+  cameraViewMatrix,
+} from 'three/tsl';
+import { NodeMaterial } from 'three/webgpu';
+
+import { waterCombineNormal, waterFbm } from './chunks/water-common.js';
+import { createWaterFoamChunk } from './chunks/water-foam.js';
+import { createWaterLightingChunk } from './chunks/water-lighting.js';
+import { createWaterWavesChunk } from './chunks/water-waves.js';
+import { resolveWaterArrayUniformNode, waterArrayUniformEntry } from './water.js';
+
+const PI = Math.PI;
+const PI2 = Math.PI * 2;
+
+let placeholderReflection = null;
+function getPlaceholderReflection() {
+  if (!placeholderReflection) {
+    placeholderReflection = new THREE.DataTexture(
+      new Uint8Array([126, 190, 218, 255]), 1, 1, THREE.RGBAFormat);
+    placeholderReflection.needsUpdate = true;
+  }
+  return placeholderReflection;
+}
+
+// Uniform names adopted from the owning surface material when `shared` is
+// given — must stay in sync with SHARED_SURFACE_UNIFORMS in
+// waterBreakerSystem.js (which drives the classic by-reference sharing).
+const SHARABLE = [
+  'uWavesA', 'uWavesB',
+  'uShallowColor', 'uMidColor', 'uDeepColor', 'uFoamColor', 'uFoamNoiseScale',
+  'uFoamContactDistance', 'uFoamLineSpacing', 'uWhitecapAmount',
+  'uSunDirection', 'uSunColor',
+  'uFlowDirection', 'uFlowSpeed', 'uDetailScale', 'uDetailNormalStrength',
+  'uSpecularStrength', 'uSpecularShininess', 'uSpecularStretch',
+  'uSparkleStrength', 'uSparkleScale', 'uSparkleSpeed', 'uSunGlowStrength',
+  'uFresnelStrength', 'uFresnelPower', 'uFresnelBias', 'uFresnelColor',
+  'uSkyZenithColor', 'uSkyHorizonColor',
+  'uReflectionMap', 'uReflectionMatrix', 'uUseReflectionMap',
+  'uReflectionStrength', 'uReflectionDistortion', 'uReflectionSoftness',
+];
+
+/**
+ * options.waveCount    WATER_WAVE_COUNT (must match the shared wave arrays)
+ * options.foamOctaves  WATER_FOAM_OCTAVES
+ * options.shared       uniform-node map of the owning surface material; the
+ *                      SHARABLE subset is adopted by reference.
+ * options.previous     uniform-node map of a previous breaker material; own
+ *                      (non-shared) uniforms are reused so values persist
+ *                      across the attachWaveUniforms rebuild.
+ */
+export function createWaterBreakerNodeMaterial({
+  waveCount,
+  foamOctaves = 3,
+  shared = null,
+  previous = null,
+} = {}) {
+  const own = {
+    uTime: uniform(0),
+    uBreakerAmount: uniform(0),
+    uBreakerCurl: uniform(0.8),
+    uBreakerScale: uniform(1),
+    uBreakerPeel: uniform(1),
+    uShoalingDepth: uniform(1.4),
+    uShorelineWaves: uniform(0.35),
+    uWaveEnergy: uniform(0.3),
+    uSetPair: uniform(0),
+    uShallowColor: uniform(new THREE.Color()),
+    uMidColor: uniform(new THREE.Color()),
+    uDeepColor: uniform(new THREE.Color()),
+    uFoamColor: uniform(new THREE.Color()),
+    uSunDirection: uniform(new THREE.Vector3(0, 1, 0)),
+    uSunColor: uniform(new THREE.Color()),
+    uFoamNoiseScale: uniform(0.6),
+    // The shared foam chunk needs these declared; scene depth is never
+    // available on the shell, so the shoreline-foam path stays off.
+    uUseSceneDepth: uniform(0),
+    uFoamContactDistance: uniform(1),
+    uFoamLineSpacing: uniform(1.4),
+    uWhitecapAmount: uniform(0.3),
+    uFlowDirection: uniform(new THREE.Vector2(1, 0)),
+    uFlowSpeed: uniform(0.35),
+    uDetailScale: uniform(0.5),
+    uDetailNormalStrength: uniform(0.5),
+    uSpecularStrength: uniform(0.8),
+    uSpecularShininess: uniform(120),
+    uSpecularStretch: uniform(0.5),
+    uSparkleStrength: uniform(0.5),
+    uSparkleScale: uniform(1.2),
+    uSparkleSpeed: uniform(1),
+    uSunGlowStrength: uniform(0.6),
+    uFresnelStrength: uniform(0.6),
+    uFresnelPower: uniform(3),
+    uFresnelBias: uniform(0.12),
+    uFresnelColor: uniform(new THREE.Color(1, 1, 1)),
+    uSkyZenithColor: uniform(new THREE.Color(0.35, 0.58, 0.85)),
+    uSkyHorizonColor: uniform(new THREE.Color(0.85, 0.92, 1.0)),
+    uReflectionMap: texture(getPlaceholderReflection()),
+    uReflectionMatrix: uniform(new THREE.Matrix4()),
+    uUseReflectionMap: uniform(0),
+    uReflectionStrength: uniform(0.55),
+    uReflectionDistortion: uniform(0.04),
+    uReflectionSoftness: uniform(0.4),
+    uWavesA: waterArrayUniformEntry(
+      uniformArray(Array.from({ length: waveCount }, () => new THREE.Vector4()), 'vec4'),
+    ),
+    uWavesB: waterArrayUniformEntry(
+      uniformArray(Array.from({ length: waveCount }, () => new THREE.Vector4()), 'vec4'),
+    ),
+  };
+  if (previous) {
+    for (const name of Object.keys(own)) {
+      if (previous[name]) own[name] = previous[name];
+    }
+  }
+  const u = { ...own };
+  if (shared) {
+    for (const name of SHARABLE) {
+      if (shared[name]) u[name] = shared[name];
+    }
+  }
+
+  const wavesANode = resolveWaterArrayUniformNode(u.uWavesA);
+  const wavesBNode = resolveWaterArrayUniformNode(u.uWavesB);
+  const waves = createWaterWavesChunk({ wavesA: wavesANode, wavesB: wavesBNode, waveCount });
+  const foam = createWaterFoamChunk({ u, foamOctaves });
+  const lighting = createWaterLightingChunk({ u });
+
+  const material = new NodeMaterial();
+  material.name = 'WaterBreakers';
+  material.lights = false;
+  // TODO(tsl Phase 7): fog ordering (see module header).
+  material.fog = false;
+  material.transparent = true;
+  material.depthWrite = true;
+  material.side = THREE.DoubleSide;
+
+  // ---- Varyings ----
+  const vWorldPosition = varying(vec3(), 'vBreakerWorldPosition');
+  const vNormal = varying(vec3(), 'vBreakerNormal');
+  const vRestXZ = varying(vec2(), 'vBreakerRestXZ');
+  const vSteep = varying(float(), 'vBreakerSteep');
+  const vChop = varying(float(), 'vBreakerChop');
+  const vProfile = varying(float(), 'vBreakerProfile');
+  const vAlong = varying(float(), 'vBreakerAlong');
+  const vPulse = varying(float(), 'vBreakerPulse');
+  const vPost = varying(float(), 'vBreakerPost');
+  const vCurl = varying(float(), 'vBreakerCurl');
+  const vFade = varying(float(), 'vBreakerFade');
+  const vFaceHeight = varying(float(), 'vBreakerFaceHeight');
+
+  // ---- Vertex stage (waterBreaker.vert.glsl) ----
+  material.vertexNode = Fn(() => {
+    const aDir = attribute('aDir', 'vec2');
+    const aInfo = attribute('aInfo', 'vec4');
+    const aSlope = attribute('aSlope', 'float');
+
+    const baseWorld = modelWorldMatrix.mul(vec4(positionGeometry, 1.0)).toVar();
+    const along = aInfo.x.toVar();
+    const t = aInfo.y.toVar();
+    // Depth at the break line, where the collapse criterion is met.
+    const lineDepth = max(aInfo.z, 0.05).toVar();
+    const endFade = aInfo.w.toVar();
+
+    const up = vec3(0.0, 1.0, 0.0);
+    const dir = normalize(vec3(aDir.x, 1e-5, aDir.y).mul(vec3(1.0, 0.0, 1.0))).toVar();
+
+    // --- Ride the dominant crest -------------------------------------------
+    const wave0A = wavesANode.element(0).toVar();
+    const wave0B = wavesBNode.element(0).toVar();
+    const k0 = max(wave0A.w, 1e-4).toVar();
+    const waveLen = float(PI2).div(k0).toVar();
+    const theta = k0.mul(dot(wave0A.xy, baseWorld.xz)).sub(wave0A.z.mul(u.uTime))
+      .add(wave0B.y).sub(u.uBreakerPeel.mul(0.4).mul(k0).mul(along)).toVar();
+
+    // delta: signed progress (in wave cycles, -0.5..0.5) of the nearest
+    // dominant crest relative to the break line.
+    const delta = float(PI * 0.5).sub(theta).div(PI2).add(0.5).fract().sub(0.5).toVar();
+    const facing = clamp(dot(wave0A.xy, dir.xz), 0.3, 1.0).toVar();
+    const ride = delta.mul(waveLen).div(facing).toVar();
+    const crestBase = baseWorld.xyz.add(dir.mul(ride)).toVar();
+    // Water depth under the ridden crest: deeper offshore, shoaling inshore.
+    const localDepth = clamp(lineDepth.sub(aSlope.mul(ride)), 0.05, lineDepth.mul(3.0)).toVar();
+
+    // Set envelope: interference of the beat pair in slots 0/1.
+    const wave1A = wavesANode.element(1).toVar();
+    const wave1B = wavesBNode.element(1).toVar();
+    const thetaBeat = wave1A.w.mul(dot(wave1A.xy, crestBase.xz))
+      .sub(wave1A.z.mul(u.uTime)).add(wave1B.y).toVar();
+    const pairA = wave0B.x.toVar();
+    const pairB = wave1B.x.toVar();
+    const interference = sqrt(max(
+      pairA.mul(pairA).add(pairB.mul(pairB))
+        .add(pairA.mul(pairB).mul(2.0).mul(cos(float(PI * 0.5).sub(thetaBeat)))),
+      0.0,
+    )).div(max(pairA.add(pairB), 1e-4)).toVar();
+    const setEnvelope = mix(1.0, interference, u.uSetPair).toVar();
+    const setGate = smoothstep(0.5, 0.78, setEnvelope).toVar();
+
+    // --- Lifecycle, keyed to WHERE the ridden crest is ----------------------
+    const approach = smoothstep(-0.3, -0.03, delta);
+    const pulse = approach.mul(smoothstep(0.03, 0.3, delta).oneMinus()).mul(setGate).toVar();
+    const curl = u.uBreakerCurl.mul(endFade).mul(setGate)
+      .mul(smoothstep(-0.14, -0.02, delta))
+      .mul(smoothstep(0.05, 0.16, delta).oneMinus()).toVar();
+    const post = smoothstep(0.02, 0.12, delta)
+      .mul(smoothstep(0.28, 0.46, delta).oneMinus()).mul(setGate).toVar();
+    // Hide the wrap seam where the shell jumps back out to the next crest.
+    const travelFade = smoothstep(-0.48, -0.4, delta)
+      .mul(smoothstep(0.38, 0.47, delta).oneMinus()).toVar();
+
+    // --- Shell shaping ----------------------------------------------------
+    const amount = clamp(u.uBreakerAmount, 0.0, 1.0).toVar();
+    const capDepth = min(lineDepth, localDepth);
+    const breakHeight = capDepth.mul(0.9).mul(u.uBreakerScale).mul(amount).mul(endFade).mul(setEnvelope).toVar();
+    const H = breakHeight.mul(mix(0.12, 1.0, pulse)).mul(post.mul(0.55).oneMinus()).toVar();
+    const R = H.mul(0.52).toVar();
+
+    // The crest leans shoreward as it steepens and the bore noses forward.
+    const crestTop = crestBase.add(up.mul(H)).add(dir.mul(H.mul(pulse.mul(0.3).add(post.mul(0.45))))).toVar();
+    const barrelCenter = crestTop.sub(up.mul(R)).toVar();
+    const backFoot = crestBase.sub(dir.mul(H.mul(2.1).add(0.35))).toVar();
+
+    // Shell profile as a pure function of t so the shading normal can come
+    // from an exact profile tangent (screen-space derivatives facet the shell).
+    const shellPoint = (tParam) => {
+      const backT = clamp(tParam.div(0.42), 0.0, 1.0);
+      const backEase = backT.mul(backT).mul(backT.mul(-2.0).add(3.0));
+      const facePos = mix(backFoot, crestTop, backEase);
+      const spiralT = clamp(tParam.sub(0.42).div(0.58), 0.0, 1.0);
+      const ang = spiralT.mul(PI).mul(curl.mul(1.18).add(0.5));
+      const rad = R.mul(spiralT.mul(0.4).mul(curl).oneMinus());
+      const spiralPos = barrelCenter
+        .add(up.mul(rad.mul(cos(ang))))
+        .add(dir.mul(rad.mul(sin(ang))))
+        .add(dir.mul(spiralT.mul(H).mul(0.22).mul(pulse)));
+      return mix(facePos, spiralPos, step(0.42, tParam));
+    };
+
+    const shellPos = shellPoint(t).toVar();
+
+    // Smooth analytic normal: profile tangent x along-crest direction.
+    const profileTangent = shellPoint(min(t.add(0.02), 1.0)).sub(shellPoint(max(t.sub(0.02), 0.0))).toVar();
+    const side = normalize(cross(up, dir));
+    const shellNormal = cross(profileTangent, side).toVar();
+    vNormal.assign(select(length(shellNormal).greaterThan(1e-6), normalize(shellNormal), up));
+    vSteep.assign(smoothstep(0.15, 0.55, pulse.add(post)).mul(smoothstep(0.0, 0.22, t)));
+
+    // --- Blend into the heightfield ----------------------------------------
+    // Same shoaling/cap displacement the water surface applies at the ridden
+    // position — including its shallow-water chop filter.
+    const range = max(max(u.uShoalingDepth, u.uWaveEnergy.mul(2.2)), 1e-3).toVar();
+    const chopWeight = mix(0.15, 1.0, smoothstep(range.mul(0.3), range.mul(1.4), localDepth)).toVar();
+    const raw = waves.gerstnerDisplacementFiltered(crestBase.xz, u.uTime, chopWeight).y.toVar();
+    const deepFactor = smoothstep(0.0, range, localDepth);
+    const rearUp = smoothstep(range.mul(0.45), range.mul(1.5), localDepth).oneMinus()
+      .mul(smoothstep(0.05, 0.35, localDepth));
+    const shoal = mix(u.uShorelineWaves, 1.0, deepFactor).mul(rearUp.mul(0.3).add(1.0)).toVar();
+    const skirtTarget = raw.mul(shoal).toVar();
+    const skirtCap = localDepth.mul(0.72).toVar();
+    const surfaceY = baseWorld.y.add(max(
+      min(skirtTarget, skirtCap).add(max(skirtTarget.sub(skirtCap), 0.0).mul(0.1)),
+      localDepth.negate().add(0.04),
+    )).toVar();
+
+    // At full pulse the shell IS the crest, so it anchors at the rest level;
+    // while still swelling it rides on top of the rendered crest instead.
+    const skirt = smoothstep(0.0, 0.3, t).oneMinus().toVar();
+    shellPos.y.addAssign(surfaceY.sub(baseWorld.y).mul(pulse.mul(0.85).oneMinus()).mul(skirt.oneMinus()));
+    shellPos.y.assign(mix(shellPos.y, surfaceY, skirt));
+
+    vProfile.assign(t);
+    vAlong.assign(along);
+    vPulse.assign(pulse);
+    vPost.assign(post);
+    vCurl.assign(curl);
+    // Appear only once the face has genuinely developed.
+    vFade.assign(amount.mul(endFade).mul(travelFade).mul(setGate)
+      .mul(smoothstep(0.12, 0.35, pulse.add(post)))
+      .mul(smoothstep(0.05, 0.15, H)));
+    vFaceHeight.assign(clamp(shellPos.y.sub(surfaceY).div(max(breakHeight, 1e-3)).add(0.15), 0.0, 1.0));
+    vWorldPosition.assign(shellPos);
+    vRestXZ.assign(crestBase.xz);
+    vChop.assign(chopWeight);
+
+    return cameraProjectionMatrix.mul(cameraViewMatrix).mul(vec4(shellPos, 1.0));
+  })();
+
+  // ---- Fragment stage (waterBreaker.frag.glsl) ----
+  material.fragmentNode = Fn(() => {
+    Discard(vFade.lessThan(0.01));
+
+    const toCamera = cameraPosition.sub(vWorldPosition).toVar();
+    const viewDir = normalize(toCamera).toVar();
+    const viewDistance = length(toCamera).toVar();
+
+    // Cross-fade from the sea's own per-pixel Gerstner normal to the smooth
+    // analytic shell normal by vSteep, so there is no lighting seam.
+    const sea = waves.gerstnerNormalFiltered(vRestXZ, u.uTime, vChop);
+    const seaNormal = vec3(sea.normal).toVar();
+    const crest = float(sea.crest).toVar();
+    const normal = normalize(mix(seaNormal, normalize(vNormal), clamp(vSteep, 0.0, 1.0))).toVar();
+    // Flip camera-ward so the tunnel interior lights too (DoubleSide mesh).
+    If(dot(normal, viewDir).lessThan(0.0), () => {
+      normal.assign(normal.negate());
+    });
+
+    // Same fbm micro-ripple detail as the open surface, same flow drift.
+    const detailFade = smoothstep(16.0, 60.0, viewDistance).oneMinus();
+    const detailStrength = u.uDetailNormalStrength.mul(mix(0.2, 1.0, detailFade)).toVar();
+    const flowOffset = u.uFlowDirection.mul(u.uTime).mul(u.uFlowSpeed);
+    const detailUv = vWorldPosition.xz.mul(u.uDetailScale).add(flowOffset.mul(0.55)).toVar();
+    const detailCenter = waterFbm(detailUv, 3).toVar();
+    const detailGradient = vec2(
+      waterFbm(detailUv.add(vec2(0.11, 0.0)), 3).sub(detailCenter),
+      waterFbm(detailUv.add(vec2(0.0, 0.11)), 3).sub(detailCenter),
+    ).div(0.11).mul(detailStrength).toVar();
+    const surfaceNormal = waterCombineNormal(normal, detailGradient).toVar();
+
+    // Body: a breaking face is a thick massed column of water — it reads
+    // DARKER than the flat sea, not lighter.
+    const faceH = clamp(vFaceHeight, 0.0, 1.0).toVar();
+    const bodyColor = mix(u.uDeepColor, u.uMidColor, smoothstep(0.1, 0.9, faceH).mul(0.65)).toVar();
+    bodyColor.mulAssign(mix(1.0, 0.78, vSteep));
+    // Sun-through tint only when the camera actually looks at the lip against
+    // the sun; squared so a side-lit lip stays in the water palette.
+    const lip = smoothstep(0.72, 0.95, vProfile).toVar();
+    const backlit = clamp(dot(viewDir.negate(), u.uSunDirection).mul(0.5).add(0.5), 0.0, 1.0).toVar();
+    bodyColor.assign(mix(bodyColor, u.uShallowColor, lip.mul(vCurl).mul(backlit).mul(backlit).mul(0.3)));
+
+    // Identical reflection/fresnel treatment to the open water.
+    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);
+    const color = mix(bodyColor, reflection, reflectionMix).toVar();
+    color.addAssign(u.uFresnelColor.mul(fresnel).mul(fresnel).mul(0.35));
+
+    // Foam layers: tumbling lip edge, face streaks, whitewater, apron, plus
+    // the sea's own whitecaps while the shell still lies flat.
+    const noiseScale = max(u.uFoamNoiseScale, 0.05).toVar();
+    const faceNoise = waterFbm(
+      vec2(vAlong.mul(1.7), vProfile.mul(4.0).sub(u.uTime.mul(1.6))).mul(noiseScale), 3,
+    ).toVar();
+    const lipFoam = smoothstep(faceNoise.mul(-0.12).add(0.68), 0.9, vProfile.add(faceNoise.mul(0.08)))
+      .mul(vPulse).mul(1.4).toVar();
+    const streaks = smoothstep(0.62, 0.85, faceNoise)
+      .mul(smoothstep(0.3, 0.7, vProfile)).mul(vPulse).mul(0.7);
+    const whitewater = vPost.mul(
+      waterFbm(vec2(vAlong.mul(2.3), vProfile.mul(3.0).add(u.uTime.mul(2.2))), 3).mul(0.6).add(0.7),
+    );
+    const apron = smoothstep(0.88, 0.98, vProfile).mul(faceNoise.mul(0.5).add(0.5)).mul(vPulse);
+    const ambientCaps = foam.whitecaps(crest, seaNormal.y, vRestXZ, u.uTime).mul(vSteep.oneMinus());
+    const foamRaw = clamp(lipFoam.add(streaks).add(whitewater).add(apron).add(ambientCaps), 0.0, 1.0);
+    const foamValue = foam.foamShape(foamRaw, vWorldPosition.xz, u.uTime).toVar();
+
+    // Same toon glints and sparkles as the open water.
+    color.addAssign(lighting.specular(viewDir, surfaceNormal, foamValue.mul(0.75).oneMinus()));
+    color.addAssign(
+      lighting.sparkles(vWorldPosition.xz, surfaceNormal, viewDir, viewDistance, u.uTime)
+        .mul(foamValue.oneMinus()),
+    );
+
+    // Foam overlay, sun-shaded two-tone like the surface foam.
+    const foamLight = clamp(dot(surfaceNormal, u.uSunDirection), 0.0, 1.0).mul(0.18).add(0.82);
+    color.assign(mix(color, u.uFoamColor.mul(foamLight), foamValue));
+
+    // Solid water, not glass: only the trailing skirt dissolves into the
+    // heightfield it sits on.
+    const alpha = vFade.mul(mix(0.97, 1.0, foamValue)).mul(smoothstep(0.02, 0.16, vProfile));
+
+    return vec4(color, alpha);
+  })();
+
+  material.uniforms = u;
+  material.defines = { WATER_WAVE_COUNT: waveCount, WATER_FOAM_OCTAVES: foamOctaves };
+  material.userData.isToonNodeMaterial = true;
+  return material;
+}