@call-me-sensei/toonlab 0.2.0 → 0.3.0

package/src/water/waterSettings.js

@@ -116,6 +116,7 @@ export const WATER_DEBUG_MODES = Object.freeze({
   specular: 7,
   fresnel: 8,
   crest: 9,
+  shoreState: 10,
 });
 
 // The number of Gerstner components evaluated by the shader and the CPU
@@ -126,8 +127,9 @@ export const DEFAULT_WATER_SETTINGS = Object.freeze({
   preset: 'lake',
   colorTone: 'classic',
 
-  // Master dial: 0 = glassy mirror, 1 = storm swell. Scales wave amplitude,
-  // steepness, and phase speed before the per-wave spectrum is built.
+  // Authored baseline: 0 = glassy mirror, 1 = storm swell. Scales wave
+  // amplitude, steepness, and phase speed before the per-wave spectrum is
+  // built. Scene weather may transiently override it on WaterSurface.
   waveIntensity: 0.25,
   waterLevel: 0.36,
 
@@ -150,6 +152,10 @@ export const DEFAULT_WATER_SETTINGS = Object.freeze({
   // face above the rest waterline. Scales with total wave energy, so storms
   // reach visibly further up the sand. 0 pins the waterline in place.
   shorelineRunup: 0.6,
+  // Maximum horizontal run-up in meters. Individual wave-group events reach
+  // 80–100% of this bound, begin at the preceding rundown endpoint, and end
+  // at their own varied endpoint. 0 = automatic (energy-scaled run-up).
+  runupDistance: 0,
 
   // Master switch for the breaker system: false removes the mesh and skips
   // all rebuild work entirely (handy for A/B perf comparisons).
@@ -191,6 +197,11 @@ export const DEFAULT_WATER_SETTINGS = Object.freeze({
   deepFadeDistance: 2.2,
   opacity: 0.8,
   refractionStrength: 0.35,
+  // Physical anchor for the stylized underside. 1.333 produces the familiar
+  // water-to-air Snell window and total-internal-reflection cutoff.
+  indexOfRefraction: 1.333,
+  underwaterTransmission: 1.0,
+  underwaterTintStrength: 0.35,
   causticsStrength: 0.55,
   causticsScale: 0.8,
   causticsSpeed: 0.6,
@@ -198,13 +209,28 @@ export const DEFAULT_WATER_SETTINGS = Object.freeze({
   // Foam.
   foamColor: [0.94, 1.0, 0.99],
   foamAmount: 1.0,
+  // Independent gain for the foam carried by the beach swash. Keeping this
+  // separate prevents stronger run-up foam from turning offshore contact
+  // bands and whitecaps into solid paint.
+  swashFoamAmount: 1.15,
+  // Stateful beach foam remains aerated for a few seconds, then converts to
+  // thinner residue instead of disappearing when the procedural cycle resets.
+  swashFoamLifetime: 4.0,
+  swashFoamResidueLifetime: 10.0,
+  // Wet sand remembers inundation much longer than the visible surface film.
+  // The short sheen is intentionally derived separately by the shore-state
+  // simulation, so a beach can stay dark without looking permanently glazed.
+  wetSandDryTime: 120.0,
+  wetSandDarkening: 0.58,
+  wetSandSheen: 0.78,
   foamContactDistance: 0.4,
   foamLineSpacing: 0.55,
   foamNoiseScale: 0.6,
   whitecapAmount: 0.05,
   rippleFoamStrength: 0.8,
 
-  // Lighting.
+  // Authored lighting/reflection fallback. A scene rig may transiently replace
+  // the sun and sky fields on WaterSurface without editing this water asset.
   sunDirection: [0.35, 0.8, 0.45],
   sunColor: [1.0, 0.96, 0.86],
   specularStrength: 0.8,
@@ -304,6 +330,7 @@ const WATER_PRESETS = Object.freeze({
     whitecapAmount: 0.22,
     foamContactDistance: 0.6,
     foamAmount: 1.3,
+    swashFoamAmount: 1.35,
     rippleFoamStrength: 0.9,
     breakerAmount: 0.55,
     waveSetPeriod: 50,
@@ -328,6 +355,7 @@ const WATER_PRESETS = Object.freeze({
     reflectionSoftness: 0.35,
     whitecapAmount: 0.4,
     foamAmount: 1.2,
+    swashFoamAmount: 1.25,
     specularStretch: 0.5,
     sparkleStrength: 0.65,
     reflectionStrength: 0.6,
@@ -358,6 +386,7 @@ const WATER_PRESETS = Object.freeze({
     reflectionSoftness: 0.3,
     causticsStrength: 0.08,
     foamAmount: 1.25,
+    swashFoamAmount: 1.45,
     whitecapAmount: 0.55,
     rippleFoamStrength: 1.0,
     sunColor: [0.9, 0.88, 0.85],
@@ -544,6 +573,7 @@ export function createWaterSettings(options = {}) {
     shoalingDepth: clampedNumber(source.shoalingDepth, base.shoalingDepth, 0.05, 12),
     shorelineWaves: clampedNumber(source.shorelineWaves, base.shorelineWaves, 0, 1),
     shorelineRunup: clampedNumber(source.shorelineRunup, base.shorelineRunup, 0, 3),
+    runupDistance: clampedNumber(source.runupDistance, base.runupDistance, 0, 15),
     breakerEnabled: typeof source.breakerEnabled === 'boolean'
       ? source.breakerEnabled
       : base.breakerEnabled !== false,
@@ -566,12 +596,33 @@ export function createWaterSettings(options = {}) {
     deepFadeDistance: clampedNumber(tone.deepFadeDistance ?? source.deepFadeDistance, base.deepFadeDistance, 0.01, 120),
     opacity: clampedNumber(source.opacity, base.opacity, 0, 1),
     refractionStrength: clampedNumber(source.refractionStrength, base.refractionStrength, 0, 3),
+    indexOfRefraction: clampedNumber(
+      source.indexOfRefraction, base.indexOfRefraction, 1.0001, 1.8,
+    ),
+    underwaterTransmission: clampedNumber(
+      source.underwaterTransmission, base.underwaterTransmission, 0, 1,
+    ),
+    underwaterTintStrength: clampedNumber(
+      source.underwaterTintStrength, base.underwaterTintStrength, 0, 1,
+    ),
     causticsStrength: clampedNumber(tone.causticsStrength ?? source.causticsStrength, base.causticsStrength, 0, 4),
     causticsScale: clampedNumber(source.causticsScale, base.causticsScale, 0.02, 12),
     causticsSpeed: clampedNumber(source.causticsSpeed, base.causticsSpeed, 0, 8),
 
     foamColor: colorArray(source.foamColor, base.foamColor),
     foamAmount: clampedNumber(source.foamAmount, base.foamAmount, 0, 2),
+    swashFoamAmount: clampedNumber(source.swashFoamAmount, base.swashFoamAmount, 0, 2),
+    swashFoamLifetime: clampedNumber(
+      source.swashFoamLifetime, base.swashFoamLifetime, 0.25, 30,
+    ),
+    swashFoamResidueLifetime: clampedNumber(
+      source.swashFoamResidueLifetime, base.swashFoamResidueLifetime, 0.5, 60,
+    ),
+    wetSandDryTime: clampedNumber(source.wetSandDryTime, base.wetSandDryTime, 2, 600),
+    wetSandDarkening: clampedNumber(
+      source.wetSandDarkening, base.wetSandDarkening, 0, 1,
+    ),
+    wetSandSheen: clampedNumber(source.wetSandSheen, base.wetSandSheen, 0, 1),
     foamContactDistance: clampedNumber(source.foamContactDistance, base.foamContactDistance, 0.01, 8),
     foamLineSpacing: clampedNumber(source.foamLineSpacing, base.foamLineSpacing, 0.05, 8),
     foamNoiseScale: clampedNumber(source.foamNoiseScale, base.foamNoiseScale, 0.02, 12),
@@ -702,37 +753,289 @@ export function buildGerstnerWaves(settings) {
 // accurate enough for buoyancy and interaction tests. chopWeight mirrors the
 // shader's shallow-water spectrum filter: slots 0/1 (the dominant swell and
 // its set beat partner) always pass at full strength, shorter cross chop
-// fades toward the surf zone.
-export function sampleGerstnerHeight(waves, x, z, time, chopWeight = 1) {
+// fades toward the surf zone. The optional nearshore sample mirrors the
+// vertex shader's depth-blended q(x,z) phase coordinate for slot 0 and, when
+// the slot mask permits it, its authored same-direction beat partner in slot 1.
+export function sampleGerstnerHeight(
+  waves,
+  x,
+  z,
+  time,
+  chopWeight = 1,
+  nearshore = null,
+) {
+  const nearshoreBlend = THREE.MathUtils.clamp(Number(nearshore?.blend) || 0, 0, 1);
+  const nearshoreSlotMask = Number.isFinite(Number(nearshore?.slotMask))
+    ? THREE.MathUtils.clamp(Number(nearshore.slotMask), 0, 2)
+    : 2;
   let height = 0;
   for (let i = 0; i < waves.length; i += 1) {
     const wave = waves[i];
-    const theta = wave.waveNumber * (wave.dirX * x + wave.dirZ * z) -
+    const baseCoordinate = wave.dirX * x + wave.dirZ * z;
+    const slotWeight = i === 0
+      ? Math.min(nearshoreSlotMask, 1)
+      : i === 1
+        ? Math.max(nearshoreSlotMask - 1, 0)
+        : 0;
+    const slotBlend = nearshoreBlend * slotWeight;
+    const phaseCoordinate = slotBlend > 0
+      ? THREE.MathUtils.lerp(baseCoordinate, nearshore.phaseCoordinate, slotBlend)
+      : baseCoordinate;
+    const theta = wave.waveNumber * phaseCoordinate -
       wave.omega * time + wave.phase;
     height += wave.amplitude * (i < 2 ? 1 : chopWeight) * Math.sin(theta);
   }
   return height;
 }
 
+// CPU mirror of createWaterWavesChunk().gerstnerSwellHeight: only the two
+// long components that survive into the surf zone. Swash samples this at a
+// projected shoreline point to keep its edge connected across the beach.
+export function sampleGerstnerSwellHeight(waves, x, z, time, nearshore = null) {
+  const nearshoreBlend = THREE.MathUtils.clamp(Number(nearshore?.blend) || 0, 0, 1);
+  const nearshoreSlotMask = Number.isFinite(Number(nearshore?.slotMask))
+    ? THREE.MathUtils.clamp(Number(nearshore.slotMask), 0, 2)
+    : 2;
+  let height = 0;
+  for (let i = 0; i < Math.min(2, waves.length); i += 1) {
+    const wave = waves[i];
+    const baseCoordinate = wave.dirX * x + wave.dirZ * z;
+    const slotWeight = i === 0
+      ? Math.min(nearshoreSlotMask, 1)
+      : Math.max(nearshoreSlotMask - 1, 0);
+    const slotBlend = nearshoreBlend * slotWeight;
+    const phaseCoordinate = slotBlend > 0
+      ? THREE.MathUtils.lerp(baseCoordinate, nearshore.phaseCoordinate, slotBlend)
+      : baseCoordinate;
+    const theta = wave.waveNumber * phaseCoordinate -
+      wave.omega * time + wave.phase;
+    height += wave.amplitude * Math.sin(theta);
+  }
+  return height;
+}
+
+// 0..1 cycle of the primary crest at the rest shoreline. Zero is crest
+// arrival; the shader uses the same cycle for the connected swash event.
+export function samplePrimarySwellSequence(waves, time) {
+  const primary = waves?.[0];
+  if (!primary) return { cycle: 0, index: 0 };
+  const raw = (primary.omega * time - primary.phase + Math.PI * 0.5) / (Math.PI * 2);
+  const index = Math.floor(raw);
+  return { cycle: raw - index, index };
+}
+
+export function samplePrimarySwellCycle(waves, time) {
+  return samplePrimarySwellSequence(waves, time).cycle;
+}
+
+// One physical swash event: fast uprush, slower gravity-driven backwash.
+// Unlike a signed sine, this never drains the sea below the rest shoreline.
+export function shapeSwashProgress(cycle, uprushFraction = 0.34) {
+  const phase = ((Number(cycle) || 0) % 1 + 1) % 1;
+  const riseEnd = THREE.MathUtils.clamp(uprushFraction, 0.1, 0.8);
+  if (phase <= riseEnd) {
+    return Math.sin((phase / riseEnd) * Math.PI * 0.5);
+  }
+  const drain = (phase - riseEnd) / (1 - riseEnd);
+  return Math.sin((1 - drain) * Math.PI * 0.5);
+}
+
+function swashHash(value) {
+  let x = ((value * 0.1031) % 1 + 1) % 1;
+  x *= x + 33.33;
+  x *= x + x;
+  return ((x % 1) + 1) % 1;
+}
+
+// Low-frequency shoreline shape for one swash event. This is CPU-authored so
+// the visible water, persistent foam pass, and gameplay queries all receive
+// the same bounded tongue pattern without adding procedural noise to the
+// private-memory-heavy visible fragment shader.
+export function sampleSwashEventShape(cycleIndex) {
+  const index = Math.floor(Number(cycleIndex) || 0);
+  return {
+    phase: swashHash(index + 113.17) * Math.PI * 2,
+    frequency: THREE.MathUtils.lerp(0.085, 0.16, swashHash(index + 197.31)),
+    amplitude: THREE.MathUtils.lerp(0.55, 1.05, swashHash(index + 251.73)),
+  };
+}
+
+// Per-event forcing for an irregular swash train. A four-wave interpolated
+// group term supplies the observed low-frequency envelope; the individual
+// term keeps neighbouring bores from sharing one reach. Backwash strength is
+// correlated with the event energy but retains its own variability.
+function sampleSwashForcing(cycleIndex) {
+  const groupPosition = cycleIndex / 4;
+  const groupIndex = Math.floor(groupPosition);
+  const groupT = groupPosition - groupIndex;
+  const groupEase = groupT * groupT * (3 - 2 * groupT);
+  const group = THREE.MathUtils.lerp(
+    swashHash(groupIndex + 19.19),
+    swashHash(groupIndex + 20.19),
+    groupEase,
+  );
+  const individual = swashHash(cycleIndex + 7.73);
+  const baseRunupScale = 0.82 + group * 0.1 + individual * 0.08;
+  const normalizedRunup = THREE.MathUtils.clamp((baseRunupScale - 0.8) / 0.2, 0, 1);
+  const backwashStrength = THREE.MathUtils.clamp(
+    normalizedRunup * 0.62 + swashHash(cycleIndex + 71.37) * 0.38,
+    0,
+    1,
+  );
+  return { backwashStrength, baseRunupScale };
+}
+
+// Bounded stylized event statistics, informed by random-wave run-up and
+// swash-interaction measurements: ordinary peaks cover 80–100% of the user
+// reach, wave groups correlate several events, and a deep preceding rundown
+// can lend a small amount of momentum to the next bore. The carry is capped
+// at 2% of the authored reach (20 cm for the 10 m calibration beach), so it
+// never overwhelms the event's own forcing. `rundownOffset` is metres relative
+// to the still-water shoreline (negative = farther seaward).
+export function sampleSwashCycleVariation(cycleIndex) {
+  const index = Math.floor(Number(cycleIndex) || 0);
+  const current = sampleSwashForcing(index);
+  const previous = sampleSwashForcing(index - 1);
+  const backwashCarry = Math.max(previous.backwashStrength - 0.5, 0) * 0.04;
+  return {
+    backwashStrength: current.backwashStrength,
+    backwashCarry,
+    baseRunupScale: current.baseRunupScale,
+    rundownOffset: THREE.MathUtils.lerp(0.35, -0.9, current.backwashStrength),
+    runupScale: THREE.MathUtils.clamp(current.baseRunupScale + backwashCarry, 0.8, 1),
+  };
+}
+
+// Continuous centerline position of the swash edge in metres along the beach.
+// Event N begins exactly at event N-1's rundown endpoint, rises to its own
+// varying inland maximum, then drains to a new endpoint without a reset jump.
+export function sampleSwashDistance(waves, time, runupDistance, uprushFraction = 0.34) {
+  const sequence = samplePrimarySwellSequence(waves, time);
+  const current = sampleSwashCycleVariation(sequence.index);
+  const previous = sampleSwashCycleVariation(sequence.index - 1);
+  const progress = shapeSwashProgress(sequence.cycle, uprushFraction);
+  const peak = Math.max(Number(runupDistance) || 0, 0) * current.runupScale;
+  return sequence.cycle <= uprushFraction
+    ? THREE.MathUtils.lerp(previous.rundownOffset, peak, progress)
+    : THREE.MathUtils.lerp(current.rundownOffset, peak, progress);
+}
+
+// One CPU-authored frame shared by the visible swash and the persistent
+// shore-state pass. Keeping event identity, incidence, and derivatives here
+// prevents a foam/wetness texture from becoming a second animation with a
+// slightly different phase or direction.
+export function sampleSwashFrameState(
+  waves,
+  time,
+  runupDistance = 0,
+  uprushFraction = 0.34,
+) {
+  const sequence = samplePrimarySwellSequence(waves, time);
+  const current = sampleSwashCycleVariation(sequence.index);
+  const previous = sampleSwashCycleVariation(sequence.index - 1);
+  const edgeShape = sampleSwashEventShape(sequence.index);
+  const progress = shapeSwashProgress(sequence.cycle, uprushFraction);
+  const derivativeStep = 0.02;
+  const beforeSequence = samplePrimarySwellSequence(waves, time - derivativeStep);
+  const afterSequence = samplePrimarySwellSequence(waves, time + derivativeStep);
+  const progressSpeed = (
+    shapeSwashProgress(afterSequence.cycle, uprushFraction) -
+    shapeSwashProgress(beforeSequence.cycle, uprushFraction)
+  ) / (derivativeStep * 2);
+  const maximumDistance = Math.max(Number(runupDistance) || 0, 0);
+  const edgeDistance = maximumDistance > 0
+    ? sampleSwashDistance(waves, time, maximumDistance, uprushFraction)
+    : 0;
+  const edgeDistanceSpeed = maximumDistance > 0
+    ? (
+      sampleSwashDistance(waves, time + derivativeStep, maximumDistance, uprushFraction) -
+      sampleSwashDistance(waves, time - derivativeStep, maximumDistance, uprushFraction)
+    ) / (derivativeStep * 2)
+    : 0;
+  return {
+    cycle: sequence.cycle,
+    cycleSpeed: Math.max(Number(waves?.[0]?.omega) || 0, 0) / (Math.PI * 2),
+    edgeDistance,
+    edgeDistanceSpeed,
+    eventIndex: sequence.index,
+    isUprush: sequence.cycle < uprushFraction,
+    primaryDirectionX: waves?.[0]?.dirX ?? 0,
+    primaryDirectionZ: waves?.[0]?.dirZ ?? -1,
+    progress,
+    progressSpeed,
+    runupScale: current.runupScale,
+    startOffset: previous.rundownOffset,
+    endOffset: current.rundownOffset,
+    edgeShape,
+  };
+}
+
+// Connected oblique lip: the large term follows the incoming crest angle and
+// small traveling scallops prevent a ruler-straight shoreline. A residual
+// envelope at nominal rest/full reach represents the alongshore arrival lag;
+// the centerline remains the 0..runupDistance calibration reference.
+export function sampleSwashEdgeOffset(
+  x,
+  time,
+  progress,
+  waveDirectionX = 0,
+  cycle = 0,
+  edgeShape = null,
+) {
+  const p = THREE.MathUtils.clamp(Number(progress) || 0, 0, 1);
+  const envelope = THREE.MathUtils.lerp(0.18, 1, Math.sin(Math.PI * p));
+  // A literal infinite oblique line grows without bound across a wide water
+  // tile. The old implementation then hard-clamped that line to the event's
+  // run-up maximum, pinning tens of metres of shore to one ruler-straight
+  // endpoint before releasing it a mesh column at a time. Soft-sign retains
+  // the incidence angle around the camera while approaching a finite offset
+  // smoothly, so it never creates a saturated plateau.
+  const incidenceSlope = THREE.MathUtils.clamp(
+    Number(waveDirectionX) * 0.52,
+    -0.2,
+    0.2,
+  );
+  const rawTilt = -x * incidenceSlope;
+  const maximumTilt = 2.0;
+  const tilt = rawTilt / (1 + Math.abs(rawTilt) / maximumTilt);
+  const scallop = (
+    Math.sin(x * 0.32 - time * 0.35) - Math.sin(-time * 0.35) +
+    (Math.sin(x * 0.91 + time * 0.18) - Math.sin(time * 0.18)) * 0.35
+  ) * 0.4;
+  const shape = edgeShape ?? { phase: 0, frequency: 0.1, amplitude: 0 };
+  const phase = Number(shape.phase) || 0;
+  const frequency = THREE.MathUtils.clamp(Number(shape.frequency) || 0.1, 0.02, 0.5);
+  const amplitude = THREE.MathUtils.clamp(Number(shape.amplitude) || 0, 0, 2.5);
+  const secondaryPhase = phase * -0.71;
+  const macroBase = (
+    Math.sin(x * frequency + phase) - Math.sin(phase) +
+    (Math.sin(x * frequency * 2.35 + secondaryPhase) - Math.sin(secondaryPhase)) * 0.42
+  ) * amplitude;
+  const macroWave = Math.sin(THREE.MathUtils.clamp(Number(cycle) || 0, 0, 1) * Math.PI);
+  const macroEnvelope = macroWave * macroWave;
+  return (tilt + scallop) * envelope + macroBase * macroEnvelope;
+}
+
 // --- Field schema -----------------------------------------------------------
 
 export const WATER_SETTING_GROUPS = Object.freeze([
   Object.freeze({ id: 'waves', label: 'Waves', description: 'Gerstner swell and detail ripple shaping.' }),
   Object.freeze({ id: 'surface', label: 'Surface', description: 'Water body color, refraction, and caustics.' }),
   Object.freeze({ id: 'foam', label: 'Foam', description: 'Shoreline foam, whitecaps, and wake foam.' }),
-  Object.freeze({ id: 'lighting', label: 'Lighting', description: 'Sun glints, sparkles, fresnel, and reflections.' }),
+  Object.freeze({ id: 'lighting', label: 'Lighting', description: 'Authored fallback sun/sky plus water-specific glint, fresnel, and reflection response.' }),
   Object.freeze({ id: 'ripples', label: 'Ripples', description: 'Interactive ripple simulation response.' }),
   Object.freeze({ id: 'splashes', label: 'Splashes', description: 'Procedural splash droplets, spray, and rings.' }),
   Object.freeze({ id: 'quality', label: 'Quality', description: 'Shader quality tier gating caustics, sparkles, and noise octaves.' }),
 ]);
 
 const FIELD_METADATA = {
-  waveIntensity: { group: 'waves', label: 'Wave Intensity', min: 0, max: 1, step: 0.01, description: 'Master dial from glassy mirror (0) to storm swell (1).' },
+  waveIntensity: { group: 'waves', label: 'Wave Intensity', min: 0, max: 1, step: 0.01, description: 'Authored baseline from glassy mirror (0) to storm swell (1); scene weather can transiently modulate it without changing the preset.' },
   waterLevel: { group: 'waves', label: 'Water Level', min: 0, max: 4, step: 0.01, description: 'World-space rest height of the surface; waves and run-up displace around it.' },
   waveAmplitude: { group: 'waves', label: 'Wave Amplitude', min: 0, max: 5, step: 0.01, description: 'Largest wave amplitude in meters at full intensity; 5 gives a 10 m crest-to-trough swell.' },
   shoalingDepth: { group: 'waves', label: 'Shoaling Depth', min: 0.05, max: 12, step: 0.05, description: 'Column depth in meters at which waves reach full height; shallower water shrinks them (needs a bed height sampler).' },
   shorelineWaves: { group: 'waves', label: 'Shoreline Waves', min: 0, max: 1, step: 0.01, description: 'Fraction of wave height that keeps rolling through the shallows as surf before dying at the waterline.' },
   shorelineRunup: { group: 'waves', label: 'Shoreline Run-up', min: 0, max: 3, step: 0.05, description: 'How far incoming waves wash a thin foam film up the beach; reach scales with wave energy.' },
+  runupDistance: { group: 'waves', label: 'Max Run-up Distance', min: 0, max: 15, step: 0.5, description: 'Maximum horizontal reach in meters. Wave groups vary each event from 80–100%, and each backwash hands its endpoint into the next uprush. 0 lets wave energy decide.' },
   breakerEnabled: { group: 'waves', label: 'Breakers On', type: 'boolean', description: 'Master switch for the breaker system; off removes the mesh and skips all breaker work (for perf A/B).' },
   breakerAmount: { group: 'waves', label: 'Surf Breakers', min: 0, max: 1, step: 0.01, description: 'Dedicated curling breaker shells along the break line; 0 disables the system (needs a bed height sampler).' },
   breakerCurl: { group: 'waves', label: 'Breaker Curl', min: 0, max: 1, step: 0.01, description: 'Lip pitch: 0 spills down the face, 1 curls a full surfable tunnel.' },
@@ -772,20 +1075,29 @@ const FIELD_METADATA = {
   deepFadeDistance: { group: 'surface', label: 'Deep Fade', min: 0.05, max: 24, step: 0.05, description: 'Additional depth where mid fades to the deep tint.' },
   opacity: { group: 'surface', label: 'Opacity', min: 0, max: 1, step: 0.01, description: 'Base transparency when no scene color grab pass is bound.' },
   refractionStrength: { group: 'surface', label: 'Refraction', min: 0, max: 2, step: 0.01, description: 'Screen-space distortion of the underwater scene.' },
+  indexOfRefraction: { group: 'surface', label: 'Water IOR', min: 1.0001, max: 1.8, step: 0.001, description: 'Index of refraction used by the underwater Snell window and total internal reflection.' },
+  underwaterTransmission: { group: 'surface', label: 'Underwater View', min: 0, max: 1, step: 0.01, description: 'Visibility of the real above-water scene through the surface from below.' },
+  underwaterTintStrength: { group: 'surface', label: 'Underwater Tint', min: 0, max: 1, step: 0.01, description: 'Stylized water-color tint applied to the view through the surface.' },
   causticsStrength: { group: 'surface', label: 'Caustics', min: 0, max: 3, step: 0.01, description: 'Brightness of the procedural voronoi caustics on the bottom.' },
   causticsScale: { group: 'surface', label: 'Caustics Scale', min: 0.05, max: 8, step: 0.05, description: 'Spatial frequency of the caustic web.' },
   causticsSpeed: { group: 'surface', label: 'Caustics Speed', min: 0, max: 4, step: 0.01, description: 'Animation speed of the caustic web.' },
 
   foamColor: { group: 'foam', label: 'Foam Color', type: 'color', description: 'Color of all foam: shoreline, whitecaps, wakes, and splashes.' },
-  foamAmount: { group: 'foam', label: 'Foam Amount', min: 0, max: 2, step: 0.01, description: 'Global foam gain.' },
+  foamAmount: { group: 'foam', label: 'Foam Amount', min: 0, max: 2, step: 0.01, description: 'Offshore contact foam, whitecap, and wake gain.' },
+  swashFoamAmount: { group: 'foam', label: 'Swash Foam', min: 0, max: 2, step: 0.01, description: 'Independent gain for torn foam carried up and back down the beach.' },
+  swashFoamLifetime: { group: 'foam', label: 'Swash Foam Life (s)', min: 0.25, max: 30, step: 0.25, description: 'Seconds fresh aerated swash foam remains before thinning into residue.' },
+  swashFoamResidueLifetime: { group: 'foam', label: 'Foam Residue Life (s)', min: 0.5, max: 60, step: 0.5, description: 'Seconds fragmented beach foam persists and drifts after the active front passes.' },
+  wetSandDryTime: { group: 'foam', label: 'Wet Sand Drying (s)', min: 2, max: 600, step: 1, description: 'Seconds saturated sand takes to return to its dry color after the water retreats.' },
+  wetSandDarkening: { group: 'foam', label: 'Wet Sand Darkening', min: 0, max: 1, step: 0.01, description: 'How strongly remembered moisture darkens exposed sand.' },
+  wetSandSheen: { group: 'foam', label: 'Wet Sand Sheen', min: 0, max: 1, step: 0.01, description: 'Strength of the short-lived glossy water film left on freshly exposed sand.' },
   foamContactDistance: { group: 'foam', label: 'Contact Distance', min: 0.02, max: 4, step: 0.01, description: 'Depth difference covered by the solid contact foam band.' },
   foamLineSpacing: { group: 'foam', label: 'Line Spacing', min: 0.05, max: 4, step: 0.01, description: 'Spacing of the animated lapping foam lines off the shore.' },
   foamNoiseScale: { group: 'foam', label: 'Foam Noise Scale', min: 0.05, max: 8, step: 0.05, description: 'Breakup noise frequency for foam edges.' },
   whitecapAmount: { group: 'foam', label: 'Whitecaps', min: 0, max: 1, step: 0.01, description: 'Coverage of breaking crests on open water.' },
   rippleFoamStrength: { group: 'foam', label: 'Wake Foam', min: 0, max: 3, step: 0.01, description: 'Foam intensity left behind by interactive ripples and wakes.' },
 
-  sunDirection: { group: 'lighting', label: 'Sun Direction', type: 'vector3', description: 'World-space direction toward the sun.' },
-  sunColor: { group: 'lighting', label: 'Sun Color', type: 'color', description: 'Sun tint used by glints, sparkles, and caustics.' },
+  sunDirection: { group: 'lighting', label: 'Sun Direction', type: 'vector3', description: 'Authored fallback direction toward the sun when no live scene-light override is connected.' },
+  sunColor: { group: 'lighting', label: 'Sun Color', type: 'color', description: 'Authored fallback sun tint for glints, sparkles, and caustics; a live scene rig may replace it transiently.' },
   specularStrength: { group: 'lighting', label: 'Specular', min: 0, max: 3, step: 0.01, description: 'Toon sun-glint intensity.' },
   specularShininess: { group: 'lighting', label: 'Shininess', min: 4, max: 2000, step: 1, description: 'Glint tightness; higher is smaller and sharper.' },
   specularStretch: { group: 'lighting', label: 'Glint Stretch', min: 0, max: 0.95, step: 0.01, description: 'Elongates glints along the sun azimuth into a sparkling sun path.' },
@@ -798,8 +1110,8 @@ const FIELD_METADATA = {
   fresnelPower: { group: 'lighting', label: 'Fresnel Power', min: 0.5, max: 12, step: 0.1, description: 'Falloff of the fresnel band toward the horizon.' },
   fresnelBias: { group: 'lighting', label: 'Fresnel Bias', min: 0, max: 0.6, step: 0.01, description: 'Sky-tint floor at steep angles; higher reads more anime-blue.' },
   fresnelColor: { group: 'lighting', label: 'Fresnel Color', type: 'color', description: 'Additive rim tint at grazing angles.' },
-  skyZenithColor: { group: 'lighting', label: 'Sky Zenith', type: 'color', description: 'Procedural sky reflection color overhead.' },
-  skyHorizonColor: { group: 'lighting', label: 'Sky Horizon', type: 'color', description: 'Procedural sky reflection color at the horizon.' },
+  skyZenithColor: { group: 'lighting', label: 'Sky Zenith', type: 'color', description: 'Authored fallback procedural sky-reflection color overhead when no live scene sky is connected.' },
+  skyHorizonColor: { group: 'lighting', label: 'Sky Horizon', type: 'color', description: 'Authored fallback procedural sky-reflection color at the horizon when no live scene sky is connected.' },
   reflectionStrength: { group: 'lighting', label: 'Reflection', min: 0, max: 1.5, step: 0.01, description: 'Planar/sky reflection mix, weighted by fresnel.' },
   reflectionDistortion: { group: 'lighting', label: 'Reflection Ripple', min: 0, max: 0.3, step: 0.005, description: 'How much waves shatter the reflection.' },
   reflectionSoftness: { group: 'lighting', label: 'Reflection Softness', min: 0, max: 1, step: 0.01, description: 'Blends sharp planar reflections toward the soft procedural sky (milky anime look).' },