@call-me-sensei/toonlab 0.1.1

package/src/shaders-tsl/chunks/water-color.js

@@ -0,0 +1,190 @@
+// TSL port of src/shaders/chunks/water-fragment-color.glsl — water body
+// color: scene depth reads, refraction, absorption gradient, and procedural
+// caustics. All uniforms come from the water material (`u` map, GLSL names).
+//
+// Scene depth on the node backends is a float COLOR texture holding linear
+// [0,1] window depth (docs/tsl-conventions.md #5 — depth textures type
+// differently per builder), written by the water grab pass's depth-color
+// render. perspectiveDepthToViewZ works unchanged on both backends; world
+// reconstruction happens through uInvViewProjMatrix, which the CPU composes
+// with the backend's NDC adjustment (see updateWaterMaterialCamera).
+//
+// GLSL early returns become var + If; texture reads sample at .level(0).
+
+import {
+  abs,
+  clamp,
+  exp,
+  float,
+  If,
+  length,
+  max,
+  min,
+  mix,
+  perspectiveDepthToViewZ,
+  pow,
+  sign,
+  smoothstep,
+  vec2,
+  vec3,
+  vec4,
+} from 'three/tsl';
+
+import { waterRotate2d, waterVoronoi2 } from './water-common.js';
+
+export function createWaterColorChunk({ u, flags }) {
+  const sceneRawDepth = (screenUv) => {
+    const raw = float(1.0).toVar();
+    If(u.uUseSceneDepth.greaterThanEqual(0.5), () => {
+      raw.assign(u.uSceneDepth.sample(screenUv).level(0).r);
+    });
+    return raw;
+  };
+
+  const viewDistanceFromDepth = (rawDepth) => {
+    // perspectiveDepthToViewZ is an Fn() in r185 — keep it out of select()
+    // operands (docs/tsl-conventions.md #2), hence the If shape.
+    const distance = float(u.uCameraFar).toVar();
+    If(rawDepth.lessThan(0.99999), () => {
+      distance.assign(perspectiveDepthToViewZ(rawDepth, u.uCameraNear, u.uCameraFar).negate());
+    });
+    return distance;
+  };
+
+  const worldFromDepth = (screenUv, rawDepth) => {
+    const clipPosition = vec4(vec3(screenUv, rawDepth).mul(2.0).sub(1.0), 1.0);
+    const worldPosition = u.uInvViewProjMatrix.mul(clipPosition).toVar();
+    return worldPosition.xyz.div(max(abs(worldPosition.w), 1e-6)).mul(sign(worldPosition.w));
+  };
+
+  // Screen-space refraction with a validity check: if the refracted sample
+  // lands on geometry in front of the water surface, fall back to the
+  // unrefracted uv so above-water objects never smear into the water.
+  const refractedUv = (screenUv, surfaceNormal, waterViewDistance, viewDepthDiff) => {
+    const result = vec2(screenUv).toVar();
+    If(u.uUseSceneColor.greaterThanEqual(0.5).and(u.uUseSceneDepth.greaterThanEqual(0.5)), () => {
+      const offset = surfaceNormal.xz.mul(u.uRefractionStrength)
+        .mul(clamp(viewDepthDiff, 0.0, 2.0))
+        .div(max(waterViewDistance.mul(0.35), 1.0))
+        .toVar();
+      // Cap the displacement in screen space: large offsets re-sample
+      // submerged objects from far away, drawing them twice as an animated
+      // ghost copy. A few-pixel cap keeps the shimmer without the double image.
+      const offsetLength = length(offset).toVar();
+      offset.mulAssign(min(offsetLength, 0.018).div(max(offsetLength, 1e-5)));
+      const candidate = clamp(screenUv.add(offset), vec2(0.001), vec2(0.999)).toVar();
+      const refractedDistance = viewDistanceFromDepth(sceneRawDepth(candidate));
+      If(refractedDistance.greaterThanEqual(waterViewDistance.sub(0.02)), () => {
+        result.assign(candidate);
+      });
+    });
+    return result;
+  };
+
+  const pierceSample = (sampleUv, surfaceHeight) => {
+    const pierce = float(0.0).toVar();
+    const rawDepth = sceneRawDepth(sampleUv).toVar();
+    If(rawDepth.lessThan(0.99999), () => { // sky — nothing pierces here
+      const neighborWorld = worldFromDepth(sampleUv, rawDepth);
+      pierce.assign(smoothstep(0.01, 0.05, neighborWorld.y.sub(surfaceHeight)));
+    });
+    return pierce;
+  };
+
+  // Detects geometry piercing the water surface within a small world-space
+  // radius of this pixel: shoreline sand, rocks, a wading character.
+  const pierceProximity = (screenUv, waterViewDistance, surfaceHeight) => {
+    const pierce = float(1.0).toVar();
+    If(u.uUseSceneDepth.greaterThanEqual(0.5), () => {
+      // ~0.4 m probe radius projected to screen space (approximate focal scale).
+      const radiusUv = clamp(float(0.4).div(max(waterViewDistance, 1.0)), 0.004, 0.05);
+      const radius = radiusUv.mul(vec2(u.uResolution.y.div(u.uResolution.x), 1.0)).toVar();
+      const lo = vec2(0.001);
+      const hi = vec2(0.999);
+      const accumulated = pierceSample(clamp(screenUv.add(vec2(radius.x, 0.0)), lo, hi), surfaceHeight).toVar();
+      accumulated.assign(max(accumulated, pierceSample(clamp(screenUv.sub(vec2(radius.x, 0.0)), lo, hi), surfaceHeight)));
+      accumulated.assign(max(accumulated, pierceSample(clamp(screenUv.add(vec2(0.0, radius.y)), lo, hi), surfaceHeight)));
+      accumulated.assign(max(accumulated, pierceSample(clamp(screenUv.sub(vec2(0.0, radius.y)), lo, hi), surfaceHeight)));
+      pierce.assign(accumulated);
+    });
+    return pierce;
+  };
+
+  // Three-stop absorption gradient: bright shallow teal -> mid blue -> deep
+  // blue. GLSL `out float absorb` → returned alongside the tint.
+  const absorptionTint = (effectiveDepth) => {
+    const absorb = exp(effectiveDepth.div(max(u.uDepthFadeDistance, 1e-3)).negate()).oneMinus().toVar();
+    const deepMix = exp(
+      max(effectiveDepth.sub(u.uDepthFadeDistance.mul(0.5)), 0.0)
+        .div(max(u.uDeepFadeDistance, 1e-3)).negate(),
+    ).oneMinus();
+    const tint = mix(u.uShallowColor, u.uMidColor, clamp(absorb.mul(1.25), 0.0, 1.0));
+    return { absorb, tint: mix(tint, u.uDeepColor, deepMix).toVar() };
+  };
+
+  // Stylized voronoi-web caustics anchored to the reconstructed underwater
+  // ground position, offset along the sun direction so they feel projected.
+  // flags.chromaticCaustics = the GLSL WATER_QUALITY >= 2 chroma-shift path.
+  const caustics = (groundWorld, columnDepth, time) => {
+    const result = vec3(0.0).toVar();
+    If(u.uCausticsStrength.greaterThan(0.001), () => {
+      const anchor = groundWorld.xz.sub(
+        u.uSunDirection.xz.div(max(u.uSunDirection.y, 0.35)).mul(columnDepth).mul(0.55),
+      ).toVar();
+      const causticUv1 = anchor.mul(u.uCausticsScale)
+        .add(vec2(0.131, 0.207).mul(time).mul(u.uCausticsSpeed)).toVar();
+      const causticUv2 = waterRotate2d(0.72).mul(anchor).mul(u.uCausticsScale.mul(1.29))
+        .sub(vec2(0.173, 0.114).mul(time).mul(u.uCausticsSpeed)).toVar();
+
+      // Caustic reach is capped independently of the clarity distances: the
+      // dappling belongs to the sub-2m shallows.
+      const causticReach = min(u.uDepthFadeDistance, 1.5).toVar();
+      const mask = smoothstep(0.015, 0.12, columnDepth)
+        .mul(smoothstep(
+          causticReach.mul(0.9),
+          causticReach.mul(1.6).add(min(u.uDeepFadeDistance, 2.5)),
+          columnDepth,
+        ).oneMinus())
+        .toVar();
+      If(mask.greaterThan(0.002), () => {
+        const strands = vec3(0.0).toVar();
+        if (flags.chromaticCaustics) {
+          // Kept subtle: wide shifts read as oil-slick rainbows instead of
+          // light dispersion, especially on top-down camera angles.
+          const chromaShift = vec2(0.011, 0.007);
+          const voroRed = waterVoronoi2(causticUv1.sub(chromaShift)).toVar();
+          const voroGreen = waterVoronoi2(causticUv1).toVar();
+          const voroBlue = waterVoronoi2(causticUv1.add(chromaShift)).toVar();
+          const voroLayer = waterVoronoi2(causticUv2).toVar();
+          const layer = smoothstep(0.0, 0.22, voroLayer.y.sub(voroLayer.x)).oneMinus();
+          const web = vec3(
+            smoothstep(0.0, 0.16, voroRed.y.sub(voroRed.x)).oneMinus(),
+            smoothstep(0.0, 0.16, voroGreen.y.sub(voroGreen.x)).oneMinus(),
+            smoothstep(0.0, 0.16, voroBlue.y.sub(voroBlue.x)).oneMinus(),
+          );
+          strands.assign(web.mul(mix(0.45, 1.0, layer)));
+        } else {
+          const voroGreen = waterVoronoi2(causticUv1).toVar();
+          const voroLayer = waterVoronoi2(causticUv2).toVar();
+          const layer = smoothstep(0.0, 0.22, voroLayer.y.sub(voroLayer.x)).oneMinus();
+          strands.assign(vec3(
+            smoothstep(0.0, 0.16, voroGreen.y.sub(voroGreen.x)).oneMinus().mul(mix(0.45, 1.0, layer)),
+          ));
+        }
+        strands.assign(pow(strands, vec3(1.6)));
+        result.assign(u.uSunColor.mul(u.uCausticsStrength).mul(strands).mul(mask));
+      });
+    });
+    return result;
+  };
+
+  return {
+    absorptionTint,
+    caustics,
+    pierceProximity,
+    refractedUv,
+    sceneRawDepth,
+    viewDistanceFromDepth,
+    worldFromDepth,
+  };
+}

package/src/shaders-tsl/chunks/water-common.js

@@ -0,0 +1,124 @@
+// TSL port of src/shaders/chunks/water-common.glsl — shared procedural
+// helpers for the stylized shaders (hashes, value noise, fbm, voronoi, toon
+// step). Everything is generated in-shader so the systems ship with zero
+// texture assets.
+//
+// Convention (docs/tsl-conventions.md): leaf helpers that map node→node are
+// `Fn()` exports (compiled as real shader functions); helpers with
+// compile-time-constant parameters (loop counts) are plain JS composition
+// functions and unroll at node-build time.
+
+import {
+  dot,
+  float,
+  floor,
+  Fn,
+  fract,
+  If,
+  mat2,
+  mix,
+  normalize,
+  smoothstep,
+  sqrt,
+  vec2,
+  vec3,
+  vec4,
+} from 'three/tsl';
+
+export const waterHash11 = /*@__PURE__*/ Fn(([p]) => {
+  const x = fract(p.mul(0.1031)).toVar();
+  x.mulAssign(x.add(33.33));
+  x.mulAssign(x.add(x));
+  return fract(x);
+});
+
+export const waterHash12 = /*@__PURE__*/ Fn(([p]) => {
+  const p3 = fract(vec3(p.x, p.y, p.x).mul(0.1031)).toVar();
+  p3.addAssign(dot(p3, p3.yzx.add(33.33)));
+  return fract(p3.x.add(p3.y).mul(p3.z));
+});
+
+export const waterHash22 = /*@__PURE__*/ Fn(([p]) => {
+  const p3 = fract(vec3(p.x, p.y, p.x).mul(vec3(0.1031, 0.103, 0.0973))).toVar();
+  p3.addAssign(dot(p3, p3.yzx.add(33.33)));
+  return fract(p3.xx.add(p3.yz).mul(p3.zy));
+});
+
+export const waterValueNoise = /*@__PURE__*/ Fn(([p]) => {
+  const i = floor(p);
+  const f = fract(p);
+  const u = f.mul(f).mul(f.mul(-2).add(3));
+  const a = waterHash12(i);
+  const b = waterHash12(i.add(vec2(1, 0)));
+  const c = waterHash12(i.add(vec2(0, 1)));
+  const d = waterHash12(i.add(vec2(1, 1)));
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+});
+
+// GLSL: waterFbm(vec2 p, int octaves) — every call site passes a literal, so
+// the octave count is a JS number here and the loop unrolls at build time.
+export function waterFbm(p, octaves) {
+  const count = Math.min(Math.max(Math.trunc(octaves), 0), 5);
+  let value = float(0);
+  let amplitude = 0.5;
+  let total = 0;
+  let q = vec2(p);
+  for (let i = 0; i < count; i += 1) {
+    value = value.add(waterValueNoise(q).mul(amplitude));
+    total += amplitude;
+    // GLSL: p = mat2(0.8, 0.6, -0.6, 0.8) * p * 2.02 + vec2(17.13, 9.77),
+    // written out component-wise (columns (0.8, 0.6) and (-0.6, 0.8)).
+    q = vec2(
+      q.x.mul(0.8).add(q.y.mul(-0.6)),
+      q.x.mul(0.6).add(q.y.mul(0.8)),
+    ).mul(2.02).add(vec2(17.13, 9.77));
+    amplitude *= 0.5;
+  }
+  return value.div(Math.max(total, 1e-4));
+}
+
+// Voronoi F1/F2 distances plus the owning cell id: vec4(F1, F2, cellId.xy).
+// The 3×3 neighbourhood walk unrolls at build time (matches the GLSL loop).
+export const waterVoronoi2 = /*@__PURE__*/ Fn(([p]) => {
+  const cell = floor(p).toVar();
+  const local = fract(p).toVar();
+  const f1 = float(8).toVar();
+  const f2 = float(8).toVar();
+  const bestId = vec2(0).toVar();
+  for (let y = -1; y <= 1; y += 1) {
+    for (let x = -1; x <= 1; x += 1) {
+      const offset = vec2(x, y);
+      const feature = waterHash22(cell.add(offset));
+      const delta = offset.add(feature).sub(local);
+      const distanceSq = dot(delta, delta).toVar();
+      If(distanceSq.lessThan(f1), () => {
+        f2.assign(f1);
+        f1.assign(distanceSq);
+        bestId.assign(cell.add(offset));
+      }).ElseIf(distanceSq.lessThan(f2), () => {
+        f2.assign(distanceSq);
+      });
+    }
+  }
+  return vec4(sqrt(f1), sqrt(f2), bestId);
+});
+
+// GLSL: mat2 waterRotate2d(angle) = mat2(c, -s, s, c) (column-major scalars).
+// TSL's mat2() takes three.js ROW-major scalar order — the transpose of the
+// GLSL constructor — so the argument order here is deliberately swapped.
+// Verified vs WebGL cloud-pattern parity (docs/tsl-conventions.md).
+export function waterRotate2d(angle) {
+  const s = float(angle).sin();
+  const c = float(angle).cos();
+  return mat2(c, s, s.negate(), c);
+}
+
+// Crisp two-tone step with a controllable soft edge; the core toon primitive.
+export const waterToonStep = /*@__PURE__*/ Fn(([edge, softness, value]) => {
+  return smoothstep(edge.sub(softness), edge.add(softness), value);
+});
+
+// Tilts a surface normal by a heightfield gradient (dh/dx, dh/dz).
+export const waterCombineNormal = /*@__PURE__*/ Fn(([baseNormal, gradient]) => {
+  return normalize(vec3(baseNormal.x.sub(gradient.x), baseNormal.y, baseNormal.z.sub(gradient.y)));
+});

package/src/shaders-tsl/chunks/water-foam.js

@@ -0,0 +1,93 @@
+// TSL port of src/shaders/chunks/water-fragment-foam.glsl — shoreline contact
+// foam, offset lapping foam lines, open-water whitecaps, and the shared toon
+// shaping that gives foam its crisp dissolve-dot edge.
+//
+// foamOctaves is the GLSL WATER_FOAM_OCTAVES define (compile-time; the fbm
+// loop unrolls at graph-build time). GLSL early returns become var + If.
+
+import {
+  clamp,
+  float,
+  fract,
+  If,
+  max,
+  min,
+  mix,
+  smoothstep,
+} from 'three/tsl';
+
+import { waterFbm, waterToonStep, waterValueNoise } from './water-common.js';
+
+export function createWaterFoamChunk({ u, foamOctaves }) {
+  // Raw shoreline foam mask. The shoreline bands are driven by the vertical
+  // water-column depth so they hug the shore identically from any camera
+  // angle; a tight view-space silhouette band handles objects standing in the
+  // water. `pierce` gates the contact bands to true waterline contacts.
+  const shoreFoam = (columnDepth, viewDepthDiff, restXZ, time, pierce) => {
+    const result = float(0.0).toVar();
+    If(u.uUseSceneDepth.greaterThanEqual(0.5), () => {
+      const flowOffset = u.uFlowDirection.mul(time).mul(u.uFlowSpeed).mul(0.35).toVar();
+      const breakup = waterFbm(restXZ.mul(u.uFoamNoiseScale).add(flowOffset), foamOctaves).toVar();
+
+      // A tight ungated core keeps a crisp waterline rim on any contact.
+      const contactTight = smoothstep(0.0, min(u.uFoamContactDistance.mul(0.5), 0.07), columnDepth).oneMinus();
+      const contactCore = max(
+        smoothstep(0.0, u.uFoamContactDistance.mul(0.5), columnDepth).oneMinus().mul(pierce),
+        contactTight,
+      ).toVar();
+      const contactHalo = smoothstep(0.0, u.uFoamContactDistance.mul(1.2), columnDepth).oneMinus()
+        .mul(smoothstep(0.34, 0.66, breakup)).mul(0.4).mul(pierce).toVar();
+      // The silhouette band additionally requires deep water below this pixel
+      // so a floating body is not painted solid white from above.
+      const silhouette = smoothstep(0.0, u.uFoamContactDistance.mul(0.4), viewDepthDiff).oneMinus()
+        .mul(pierce)
+        .mul(smoothstep(u.uFoamContactDistance.mul(0.6), u.uFoamContactDistance.mul(1.3), columnDepth))
+        .toVar();
+
+      // Lapping lines march toward the shore and dissolve into dashes.
+      const lineDistance = columnDepth.div(max(u.uFoamLineSpacing, 1e-3))
+        .add(breakup.sub(0.5).mul(0.7)).sub(time.mul(0.32));
+      const lineBand = fract(lineDistance).toVar();
+      const line = smoothstep(0.8, 0.93, lineBand)
+        .mul(smoothstep(0.93, 1.0, lineBand).oneMinus()).toVar();
+      const lineFalloff = smoothstep(1.3, 2.4, columnDepth.div(max(u.uFoamLineSpacing, 1e-3))).oneMinus();
+      const dashes = waterValueNoise(restXZ.mul(u.uFoamNoiseScale).mul(2.6).add(flowOffset.mul(1.7)));
+      line.mulAssign(lineFalloff.mul(smoothstep(0.36, 0.6, breakup)).mul(smoothstep(0.3, 0.55, dashes)));
+
+      result.assign(clamp(
+        contactCore.mul(1.3).add(silhouette.mul(1.2)).add(contactHalo).add(line),
+        0.0,
+        1.0,
+      ));
+    });
+    return result;
+  };
+
+  // Whitecaps on open water crests: driven by the Gerstner crest factor and
+  // surface steepness, broken into patches, scaled by the storminess amount.
+  const whitecaps = (crest, gerstnerNormalY, restXZ, time) => {
+    const result = float(0.0).toVar();
+    If(u.uWhitecapAmount.greaterThan(0.002), () => {
+      const drift = u.uFlowDirection.mul(time).mul(u.uFlowSpeed.mul(0.4).add(0.35));
+      const patches = waterFbm(restXZ.mul(u.uFoamNoiseScale).mul(0.6).add(drift), foamOctaves).toVar();
+      const steepness = clamp(gerstnerNormalY.oneMinus().mul(9.0), 0.0, 1.0);
+      const energy = crest.mul(steepness.mul(0.45).add(0.55)).mul(patches.mul(0.85).add(0.45)).toVar();
+      const threshold = mix(float(0.985), float(0.32), clamp(u.uWhitecapAmount, 0.0, 1.0)).toVar();
+      result.assign(smoothstep(threshold, threshold.add(0.22), energy));
+    });
+    return result;
+  };
+
+  // Shared toon shaping: a solid band plus a sparse dissolve-dot fringe so
+  // foam edges read as hand-drawn dots rather than a soft alpha gradient.
+  const foamShape = (rawMask, restXZ, time) => {
+    const dotNoise = waterValueNoise(
+      restXZ.mul(u.uFoamNoiseScale).mul(5.2).add(u.uFlowDirection.mul(time).mul(u.uFlowSpeed).mul(0.6)),
+    );
+    const solid = waterToonStep(0.56, 0.12, rawMask);
+    const dots = waterToonStep(0.74, 0.06, rawMask.mul(dotNoise.mul(0.75).add(0.35)));
+    return clamp(max(solid, dots), 0.0, 1.0);
+  };
+
+  return { foamShape, shoreFoam, whitecaps };
+}

package/src/shaders-tsl/chunks/water-lighting.js

@@ -0,0 +1,116 @@
+// TSL port of src/shaders/chunks/water-fragment-lighting.glsl — stylized
+// fresnel, toon-banded sun glints, twinkling sparkles, and reflections
+// (planar render target with a procedural sky fallback).
+//
+// The reflection map is a render-target texture (.level(0) samples); the
+// projective uReflectionMatrix is CPU-composed with the node backends' RT
+// y-flip (docs/tsl-conventions.md #6 — see WaterScenePasses), so the shader
+// math stays the literal GLSL port. GLSL early returns become var + If, which
+// also keeps the uniform-dependent divisions guarded (conventions #8).
+
+import {
+  clamp,
+  dot,
+  If,
+  fract,
+  max,
+  mix,
+  normalize,
+  pow,
+  reflect,
+  smoothstep,
+  step,
+  vec2,
+  vec3,
+  vec4,
+} from 'three/tsl';
+
+import { waterHash12, waterToonStep, waterVoronoi2 } from './water-common.js';
+
+export function createWaterLightingChunk({ u }) {
+  // Schlick-style fresnel with a stylized floor: uFresnelBias keeps some sky
+  // reflection alive even looking straight down.
+  const fresnelFactor = (viewDir, surfaceNormal) => {
+    const facing = clamp(dot(viewDir, surfaceNormal), 0.0, 1.0);
+    return clamp(
+      u.uFresnelBias.add(pow(facing.oneMinus(), u.uFresnelPower).mul(u.uFresnelStrength)),
+      0.0,
+      1.0,
+    );
+  };
+
+  // Toon-banded Blinn-Phong glint. The normal is anisotropically squashed
+  // along the sun azimuth so low sun angles draw the long sparkling sun path.
+  const specular = (viewDir, surfaceNormal, shadowFactor) => {
+    const sunAzimuth = normalize(u.uSunDirection.xz.add(vec2(1e-5, 0.0))).toVar();
+    const sunPerp = vec2(sunAzimuth.y.negate(), sunAzimuth.x).toVar();
+    const stretched = sunAzimuth.mul(dot(surfaceNormal.xz, sunAzimuth))
+      .add(sunPerp.mul(dot(surfaceNormal.xz, sunPerp)).mul(clamp(u.uSpecularStretch, 0.0, 0.95).oneMinus()))
+      .toVar();
+    const glintNormal = normalize(vec3(stretched.x, surfaceNormal.y, stretched.y));
+    const halfDir = normalize(viewDir.add(u.uSunDirection));
+    const alignment = pow(max(dot(glintNormal, halfDir), 0.0), u.uSpecularShininess).toVar();
+    const core = waterToonStep(0.5, 0.1, alignment);
+    const halo = waterToonStep(0.18, 0.16, alignment).mul(0.3);
+    return u.uSunColor.mul(u.uSpecularStrength).mul(core.add(halo)).mul(shadowFactor);
+  };
+
+  // Twinkling star glints: sparse voronoi feature points with per-cell phase.
+  const sparkles = (restXZ, surfaceNormal, viewDir, viewDistance, time) => {
+    const result = vec3(0.0).toVar();
+    If(u.uSparkleStrength.greaterThan(0.001), () => {
+      const sparkleUv = restXZ.mul(u.uSparkleScale)
+        .add(u.uFlowDirection.mul(time).mul(u.uFlowSpeed).mul(0.4));
+      const voro = waterVoronoi2(sparkleUv).toVar();
+      const cellRandom = waterHash12(voro.zw).toVar();
+      const activeCell = step(0.5, cellRandom);
+      const twinklePhase = fract(
+        cellRandom.mul(7.13).add(time.mul(u.uSparkleSpeed).mul(cellRandom.mul(0.3).add(0.16))),
+      ).toVar();
+      const twinkle = smoothstep(0.88, 0.965, twinklePhase)
+        .mul(smoothstep(0.965, 1.0, twinklePhase).oneMinus());
+      const point = smoothstep(0.02, 0.12, voro.x).oneMinus();
+      const halfDir = normalize(viewDir.add(u.uSunDirection));
+      const alignment = smoothstep(0.4, 0.92, dot(surfaceNormal, halfDir));
+      const distanceFade = smoothstep(18.0, 55.0, viewDistance).oneMinus();
+      result.assign(
+        u.uSunColor.mul(u.uSparkleStrength).mul(point).mul(twinkle).mul(activeCell)
+          .mul(alignment).mul(distanceFade).mul(3.2),
+      );
+    });
+    return result;
+  };
+
+  // Procedural sky used when no planar reflection target is bound: a vertical
+  // gradient plus a soft sun glow, cheap and asset-free.
+  const proceduralSky = (reflectDir) => {
+    const horizon = pow(clamp(reflectDir.y, 0.0, 1.0), 0.55);
+    const sky = mix(u.uSkyHorizonColor, u.uSkyZenithColor, horizon);
+    const sunGlow = pow(max(dot(reflectDir, u.uSunDirection), 0.0), 180.0);
+    return sky.add(u.uSunColor.mul(sunGlow).mul(u.uSunGlowStrength));
+  };
+
+  const reflectionColor = (worldPosition, surfaceNormal, viewDir) => {
+    const reflectDir = reflect(viewDir.negate(), surfaceNormal).toVar();
+    const fallback = proceduralSky(reflectDir).toVar();
+    const result = vec3(fallback).toVar();
+    If(u.uUseReflectionMap.greaterThanEqual(0.5), () => {
+      const projected = u.uReflectionMatrix.mul(vec4(worldPosition, 1.0)).toVar();
+      If(projected.w.greaterThan(0.0), () => {
+        const reflectionUv = projected.xy.div(projected.w)
+          .add(surfaceNormal.xz.mul(u.uReflectionDistortion)).toVar();
+        const inRange = reflectionUv.x.greaterThanEqual(0.0).and(reflectionUv.x.lessThanEqual(1.0))
+          .and(reflectionUv.y.greaterThanEqual(0.0)).and(reflectionUv.y.lessThanEqual(1.0));
+        If(inRange, () => {
+          const planar = u.uReflectionMap.sample(reflectionUv).level(0).rgb;
+          // Milky painterly reflections: soften the mirror image toward the
+          // smooth procedural sky instead of showing a sharp flipped scene.
+          result.assign(mix(planar, fallback, clamp(u.uReflectionSoftness, 0.0, 1.0)));
+        });
+      });
+    });
+    return result;
+  };
+
+  return { fresnelFactor, proceduralSky, reflectionColor, sparkles, specular };
+}

package/src/shaders-tsl/chunks/water-ripple.js

@@ -0,0 +1,64 @@
+// TSL port of src/shaders/chunks/water-ripple.glsl — interactive ripple
+// heightfield sampling, shared by the water vertex and fragment stages.
+// The simulation texture stores: R = height, G = velocity, B = foam energy.
+// uRippleRegion = (centerX, centerZ, halfSizeX, halfSizeZ) in world space.
+//
+// The ripple map is a render-target texture, so every sample is `.level(0)`
+// (docs/tsl-conventions.md: RT-fed textures have no mips and WGSL forbids
+// implicit-derivative sampling in non-uniform control flow). The GLSL early
+// returns become var + If — the mask guard keeps the texture reads out of
+// the disabled path exactly like the GLSL branch.
+
+import {
+  float,
+  If,
+  max,
+  smoothstep,
+  vec2,
+  vec3,
+} from 'three/tsl';
+
+export function createWaterRippleChunk({ u }) {
+  const rippleUv = (restXZ) =>
+    restXZ.sub(u.uRippleRegion.xy).div(u.uRippleRegion.zw.mul(2.0)).add(0.5);
+
+  // Smoothly fades ripple influence to zero at the simulation region border so
+  // a moving region never shows a hard seam on large water bodies.
+  const rippleMask = (uv) => {
+    const border = smoothstep(vec2(0.0), vec2(0.06), uv)
+      .mul(smoothstep(vec2(0.94), vec2(1.0), uv).oneMinus());
+    return border.x.mul(border.y).mul(u.uUseRippleMap);
+  };
+
+  const rippleSample = (restXZ) => {
+    const result = vec3(0.0).toVar();
+    const uv = rippleUv(restXZ).toVar();
+    const mask = rippleMask(uv).toVar();
+    If(mask.greaterThan(0.0), () => {
+      const state = u.uRippleMap.sample(uv).level(0).rgb;
+      result.assign(state.mul(mask));
+    });
+    return result;
+  };
+
+  // Central-difference normal contribution from the ripple heightfield.
+  const rippleGradient = (restXZ) => {
+    const result = vec2(0.0).toVar();
+    const uv = rippleUv(restXZ).toVar();
+    const mask = rippleMask(uv).toVar();
+    If(mask.greaterThan(0.0), () => {
+      const left = u.uRippleMap.sample(uv.sub(vec2(u.uRippleTexel.x, 0.0))).level(0).r;
+      const right = u.uRippleMap.sample(uv.add(vec2(u.uRippleTexel.x, 0.0))).level(0).r;
+      const down = u.uRippleMap.sample(uv.sub(vec2(0.0, u.uRippleTexel.y))).level(0).r;
+      const up = u.uRippleMap.sample(uv.add(vec2(0.0, u.uRippleTexel.y))).level(0).r;
+      const worldStep = u.uRippleTexel.mul(2.0).mul(u.uRippleRegion.zw.mul(2.0)).toVar();
+      result.assign(vec2(
+        right.sub(left).div(max(worldStep.x, 1e-5)),
+        up.sub(down).div(max(worldStep.y, 1e-5)),
+      ).mul(u.uRippleHeightScale).mul(mask));
+    });
+    return result;
+  };
+
+  return { rippleGradient, rippleMask, rippleSample, rippleUv };
+}