@call-me-sensei/toonlab 0.1.1

package/src/water/waterSettings.js

@@ -0,0 +1,1138 @@
+import * as THREE from 'three';
+import {
+  createSettingsPresetDocument,
+  parsePresetDocument,
+  serializePresetDocument,
+  validateSettingsPresetDocument,
+} from '../core/presetDocuments.js';
+
+// Public settings for the stylized water system. Mirrors the toon/environment
+// settings conventions: normalized flat settings objects, named presets, and a
+// field schema that HUDs or editors can generate controls from.
+
+export const WATER_PRESET_NAMES = Object.freeze([
+  'mirror',
+  'calm',
+  'lake',
+  'river',
+  'coast',
+  'ocean',
+  'storm',
+]);
+
+export const WATER_QUALITY_LEVELS = Object.freeze(['low', 'medium', 'high']);
+
+// Named body-color palettes, independent of the wave presets: pick a mode
+// (lake/ocean/...) for motion and a tone for color. A non-'classic' tone
+// forces its palette over preset, environment, and per-key color overrides,
+// so switching tones always takes effect; 'classic' returns full control to
+// the preset/explicit colors.
+export const WATER_COLOR_TONES = Object.freeze({
+  // Preset/default palette untouched.
+  classic: Object.freeze({}),
+  // Matched against modern anime open-world reference shots (coastal scenes):
+  // bright milky pastel water. Pale luminous turquoise shallows so clear the
+  // bed reads through for meters, azure — never navy — mids and deeps, a high
+  // sky-tint floor, strong-but-soft reflections (clouds smear milky white),
+  // and pronounced caustic dappling on the bed.
+  anime: Object.freeze({
+    // Swim-depth reference water is a saturated green-leaning turquoise, not
+    // pale azure; the beach reference gets its blue from grazing-angle sky
+    // reflection, not from the body color.
+    shallowColor: [0.52, 0.94, 0.85],
+    midColor: [0.19, 0.72, 0.74],
+    deepColor: [0.07, 0.47, 0.55],
+    depthFadeDistance: 2.4,
+    deepFadeDistance: 5.5,
+    fresnelColor: [0.68, 0.93, 1.0],
+    // Low sky-tint floor: looking straight down while swimming, the reference shows
+    // nearly pure body color — sky/cloud reflections belong to grazing angles.
+    fresnelBias: 0.07,
+    reflectionStrength: 0.62,
+    reflectionSoftness: 0.7,
+    // Subtle: the long clarity distances above widen the caustic depth window
+    // considerably, and the reference dappling is a soft near-shore accent, not a
+    // surface web.
+    causticsStrength: 0.3,
+    // Glassier surface: the reference water carries long smooth undulations,
+    // not constant high-frequency wobble.
+    detailNormalStrength: 0.12,
+  }),
+  // Anime-style lake teal: green pulled above blue in the mid band, long
+  // glassy falloff before the deeps.
+  teal: Object.freeze({
+    shallowColor: [0.36, 0.87, 0.78],
+    midColor: [0.1, 0.63, 0.62],
+    deepColor: [0.03, 0.35, 0.44],
+    depthFadeDistance: 1.4,
+    deepFadeDistance: 3.0,
+    fresnelColor: [0.62, 0.92, 0.9],
+  }),
+  // Caribbean shelf: vivid turquoise shallows over white sand, emerald mid,
+  // deep water still saturated instead of navy.
+  caribbean: Object.freeze({
+    shallowColor: [0.38, 0.96, 0.85],
+    midColor: [0.04, 0.73, 0.71],
+    deepColor: [0.01, 0.4, 0.52],
+    depthFadeDistance: 1.9,
+    deepFadeDistance: 4.2,
+    fresnelColor: [0.6, 0.95, 0.95],
+  }),
+  // Emerald lagoon: green-dominant all the way down.
+  lagoon: Object.freeze({
+    shallowColor: [0.47, 0.93, 0.71],
+    midColor: [0.13, 0.68, 0.5],
+    deepColor: [0.03, 0.35, 0.32],
+    depthFadeDistance: 1.5,
+    deepFadeDistance: 3.2,
+    fresnelColor: [0.66, 0.93, 0.85],
+  }),
+  // Open-ocean indigo: short falloff into a saturated deep blue.
+  deepOcean: Object.freeze({
+    shallowColor: [0.3, 0.74, 0.86],
+    midColor: [0.08, 0.4, 0.7],
+    deepColor: [0.015, 0.15, 0.4],
+    depthFadeDistance: 0.9,
+    deepFadeDistance: 2.0,
+    fresnelColor: [0.6, 0.82, 1.0],
+  }),
+});
+
+export const WATER_COLOR_TONE_NAMES = Object.freeze(Object.keys(WATER_COLOR_TONES));
+
+export function resolveWaterColorToneName(requested) {
+  const name = String(requested ?? '').trim();
+  return WATER_COLOR_TONE_NAMES.includes(name) ? name : 'classic';
+}
+
+export const WATER_DEBUG_MODES = Object.freeze({
+  off: 0,
+  depth: 1,
+  foam: 2,
+  normal: 3,
+  ripple: 4,
+  reflection: 5,
+  caustics: 6,
+  specular: 7,
+  fresnel: 8,
+  crest: 9,
+});
+
+// The number of Gerstner components evaluated by the shader and the CPU
+// mirror. Fixed so buoyancy queries always match the rendered surface.
+export const WATER_GERSTNER_WAVE_COUNT = 8;
+
+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.
+  waveIntensity: 0.25,
+  waterLevel: 0.36,
+
+  // Gerstner wave spectrum.
+  waveAmplitude: 0.3,
+  waveLength: 7.5,
+  waveSteepness: 0.75,
+  waveSpeed: 1.0,
+  waveDirection: [1.0, 0.35],
+  waveDirectionSpread: 0.65,
+  // Water column depth (m) at which waves reach full amplitude. Shallower
+  // water shrinks the swell so crests never poke through a shore or island.
+  // Only active when the surface is given a bed height sampler.
+  shoalingDepth: 1.4,
+  // Fraction of wave height that survives into the shallows as rolling surf.
+  // Waves only die completely in the last few swash centimeters at the
+  // waterline; 0 restores the old flatten-to-nothing behavior.
+  shorelineWaves: 0.35,
+  // Swash run-up: how far incoming waves push a thin foamy film up the beach
+  // 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,
+
+  // Master switch for the breaker system: false removes the mesh and skips
+  // all rebuild work entirely (handy for A/B perf comparisons).
+  breakerEnabled: true,
+  // Dedicated plunging-breaker geometry along the break line (needs a bed
+  // height sampler). 0 disables the system entirely; above 0 curl shells
+  // spawn where the swell reaches its collapse depth and barrel with each
+  // arriving wave. Purely visual — height queries stay on the heightfield.
+  breakerAmount: 0,
+  // How far the lip curls over: 0 spills down the face, 1 wraps a tunnel.
+  breakerCurl: 0.8,
+  // Shell height multiplier over the physical breaking height (0.72 x depth).
+  breakerScale: 1.0,
+  // Along-crest peel rate; higher makes the barrel travel faster down the
+  // line (0 breaks the whole line at once wherever the swell hits square).
+  breakerPeel: 1.0,
+
+  // Wave sets: real swell arrives in groups — the big waves come minutes
+  // apart with lulls between, they don't repeat every period. The primary
+  // swell is split into a beat pair whose interference modulates its
+  // amplitude with this period (seconds between set peaks at a fixed point).
+  waveSetPeriod: 60,
+  // Modulation depth: 0 = constant swell every period, 1 = the swell dies
+  // completely between sets.
+  waveSetStrength: 0.5,
+
+  // Procedural detail ripple normals.
+  detailNormalStrength: 0.32,
+  detailScale: 1.15,
+  flowDirection: [0.72, -0.18],
+  flowSpeed: 0.3,
+
+  // Water body color and refraction. The palette is deliberately high-key
+  // saturated cyan (anime style): deep water reads as milky blue, not navy.
+  shallowColor: [0.42, 0.85, 0.88],
+  midColor: [0.2, 0.62, 0.8],
+  deepColor: [0.1, 0.38, 0.6],
+  depthFadeDistance: 1.0,
+  deepFadeDistance: 2.2,
+  opacity: 0.8,
+  refractionStrength: 0.35,
+  causticsStrength: 0.55,
+  causticsScale: 0.8,
+  causticsSpeed: 0.6,
+
+  // Foam.
+  foamColor: [0.94, 1.0, 0.99],
+  foamAmount: 1.0,
+  foamContactDistance: 0.4,
+  foamLineSpacing: 0.55,
+  foamNoiseScale: 0.6,
+  whitecapAmount: 0.05,
+  rippleFoamStrength: 0.8,
+
+  // Lighting.
+  sunDirection: [0.35, 0.8, 0.45],
+  sunColor: [1.0, 0.96, 0.86],
+  specularStrength: 0.8,
+  specularShininess: 150,
+  specularStretch: 0.35,
+  sparkleStrength: 0.5,
+  sparkleScale: 1.5,
+  sparkleSpeed: 1.0,
+  sunGlowStrength: 0.85,
+  // How strongly scene shadows (rocks, trees, the character) darken the
+  // surface and mute its sun glints/caustics.
+  sceneShadowStrength: 0.6,
+  fresnelStrength: 0.9,
+  fresnelPower: 4.5,
+  // Sky-tint floor: keeps the surface carrying reflected sky color even at
+  // steep viewing angles, which is what makes anime water read "blue".
+  fresnelBias: 0.16,
+  fresnelColor: [0.68, 0.9, 1.0],
+  skyZenithColor: [0.5, 0.74, 0.98],
+  skyHorizonColor: [0.86, 0.95, 1.0],
+  reflectionStrength: 0.62,
+  reflectionDistortion: 0.04,
+  // Blends the sharp planar reflection toward the soft procedural sky for the
+  // milky painterly reflections of stylized water (0 = mirror, 1 = fully soft).
+  reflectionSoftness: 0.55,
+
+  // Interactive ripple simulation.
+  rippleStrength: 1.0,
+  rippleDamping: 0.985,
+  ripplePropagation: 11.0,
+  rippleHeightScale: 1.0,
+  rippleFoamDecay: 0.94,
+  rippleFoamGain: 2.4,
+
+  // Splash particles (droplets, spray crown, expanding foam rings).
+  splashStrength: 1.0,
+  splashScale: 1.0,
+  splashDropletCount: 26,
+  splashRingCount: 2,
+  splashColor: [0.97, 1.0, 1.0],
+  splashShadeColor: [0.62, 0.86, 0.95],
+
+  quality: 'high',
+});
+
+const WATER_PRESETS = Object.freeze({
+  mirror: Object.freeze({
+    waveIntensity: 0.03,
+    waveAmplitude: 0.12,
+    waveSteepness: 0.4,
+    detailNormalStrength: 0.1,
+    flowSpeed: 0.12,
+    whitecapAmount: 0,
+    foamAmount: 0.7,
+    sparkleStrength: 0.35,
+    reflectionStrength: 0.85,
+    reflectionDistortion: 0.015,
+    reflectionSoftness: 0.3,
+  }),
+  calm: Object.freeze({
+    waveIntensity: 0.12,
+    waveAmplitude: 0.2,
+    waveSteepness: 0.55,
+    detailNormalStrength: 0.18,
+    flowSpeed: 0.2,
+    whitecapAmount: 0,
+    reflectionStrength: 0.7,
+    reflectionDistortion: 0.03,
+    reflectionSoftness: 0.6,
+    sparkleStrength: 0.45,
+  }),
+  lake: Object.freeze({}),
+  river: Object.freeze({
+    waveIntensity: 0.3,
+    waveLength: 4.2,
+    waveDirection: [1.0, -0.15],
+    waveDirectionSpread: 0.12,
+    waveSpeed: 1.25,
+    flowDirection: [1.0, -0.15],
+    flowSpeed: 1.15,
+    detailScale: 1.6,
+    foamAmount: 1.25,
+    foamLineSpacing: 0.4,
+    causticsStrength: 0.7,
+    sparkleStrength: 0.4,
+    whitecapAmount: 0.08,
+  }),
+  coast: Object.freeze({
+    waveIntensity: 0.5,
+    waveAmplitude: 0.42,
+    waveLength: 9.0,
+    // Onshore swell: surf only exists when waves travel toward the shallows.
+    waveDirection: [0.15, -1.0],
+    waveDirectionSpread: 0.5,
+    flowDirection: [0.15, -1.0],
+    flowSpeed: 0.45,
+    whitecapAmount: 0.22,
+    foamContactDistance: 0.6,
+    foamAmount: 1.3,
+    rippleFoamStrength: 0.9,
+    breakerAmount: 0.55,
+    waveSetPeriod: 50,
+    waveSetStrength: 0.6,
+  }),
+  ocean: Object.freeze({
+    waveIntensity: 0.7,
+    waveAmplitude: 0.55,
+    waveLength: 13.0,
+    waveSteepness: 0.95,
+    // Onshore swell with moderate spread so sets march at the beach and the
+    // break line actually breaks (surf needs shoreward wave travel).
+    waveDirection: [0.3, -1.0],
+    waveDirectionSpread: 0.55,
+    flowDirection: [0.3, -1.0],
+    waterLevel: 0.42,
+    shallowColor: [0.26, 0.7, 0.84],
+    midColor: [0.14, 0.5, 0.72],
+    deepColor: [0.06, 0.3, 0.52],
+    depthFadeDistance: 1.3,
+    deepFadeDistance: 3.0,
+    reflectionSoftness: 0.35,
+    whitecapAmount: 0.4,
+    foamAmount: 1.2,
+    specularStretch: 0.5,
+    sparkleStrength: 0.65,
+    reflectionStrength: 0.6,
+    flowSpeed: 0.5,
+    splashStrength: 1.2,
+    breakerAmount: 0.85,
+    breakerCurl: 0.85,
+    waveSetPeriod: 75,
+    waveSetStrength: 0.7,
+  }),
+  storm: Object.freeze({
+    waveIntensity: 1.0,
+    waveAmplitude: 0.5,
+    waveLength: 15.0,
+    waveSteepness: 1.05,
+    waveSpeed: 1.25,
+    waveDirection: [0.45, -1.0],
+    waveDirectionSpread: 0.8,
+    waterLevel: 0.42,
+    detailNormalStrength: 0.55,
+    flowSpeed: 0.55,
+    shallowColor: [0.2, 0.66, 0.78],
+    midColor: [0.1, 0.4, 0.56],
+    deepColor: [0.05, 0.22, 0.36],
+    depthFadeDistance: 1.4,
+    deepFadeDistance: 3.2,
+    fresnelBias: 0.1,
+    reflectionSoftness: 0.3,
+    causticsStrength: 0.08,
+    foamAmount: 1.25,
+    whitecapAmount: 0.55,
+    rippleFoamStrength: 1.0,
+    sunColor: [0.9, 0.88, 0.85],
+    sparkleStrength: 0.3,
+    specularStrength: 0.6,
+    fresnelStrength: 1.0,
+    skyZenithColor: [0.34, 0.46, 0.62],
+    skyHorizonColor: [0.62, 0.7, 0.78],
+    reflectionStrength: 0.42,
+    reflectionDistortion: 0.08,
+    sunGlowStrength: 0.4,
+    splashStrength: 1.45,
+    splashShadeColor: [0.55, 0.74, 0.82],
+    // Storm surf closes out: tall messy walls, less clean tunnel. The monster
+    // sets arrive minutes apart.
+    breakerAmount: 1.0,
+    breakerCurl: 0.6,
+    breakerPeel: 1.6,
+    waveSetPeriod: 150,
+    waveSetStrength: 0.85,
+  }),
+});
+
+const WATER_PRESET_ALIASES = Object.freeze({
+  '': 'lake',
+  default: 'lake',
+  pond: 'calm',
+  sea: 'ocean',
+  stormy: 'storm',
+});
+
+// Label + one-line description for each built-in preset, surfaced through
+// getWaterPresetOptions() so HUDs can build preset pickers.
+const BUILT_IN_WATER_PRESET_METADATA = Object.freeze({
+  mirror: Object.freeze({ label: 'Mirror', description: 'Glassy still water: near-perfect reflections and almost no swell.' }),
+  calm: Object.freeze({ label: 'Calm', description: 'Gentle pond ripples with soft reflections and no whitecaps.' }),
+  lake: Object.freeze({ label: 'Lake', description: 'Default balanced lake water: light swell and the anime-blue palette.' }),
+  river: Object.freeze({ label: 'River', description: 'Fast aligned current with fine chop, streaming foam lines, and strong caustics.' }),
+  coast: Object.freeze({ label: 'Coast', description: 'Onshore swell with rolling surf, wide contact foam, and moderate breakers.' }),
+  ocean: Object.freeze({ label: 'Ocean', description: 'Big open-water swell arriving in sets, with whitecaps and curling breakers.' }),
+  storm: Object.freeze({ label: 'Storm', description: 'Maximum swell under a grey sky: close-out surf, heavy foam, and spray.' }),
+});
+
+// Runtime preset registry: seeded with the built-ins and extended by
+// registerWaterPreset(). createWaterSettings resolves preset names through
+// this map, so user-registered presets behave exactly like built-ins.
+const waterPresetRegistry = new Map(
+  WATER_PRESET_NAMES.map((name) => [name, {
+    description: BUILT_IN_WATER_PRESET_METADATA[name].description,
+    label: BUILT_IN_WATER_PRESET_METADATA[name].label,
+    settings: WATER_PRESETS[name],
+  }]),
+);
+
+function normalizeWaterPresetId(value) {
+  return String(value ?? '')
+    .trim()
+    .replace(/[\s-]+/g, '_')
+    .toLowerCase();
+}
+
+// Old public keys accepted for compatibility with existing URLs and presets.
+const LEGACY_KEY_ALIASES = Object.freeze({
+  impulseStrength: 'rippleStrength',
+  intersectionFoamDistance: 'foamContactDistance',
+  normalStrength: 'detailNormalStrength',
+  simulationDamping: 'rippleDamping',
+  simulationSpeed: 'ripplePropagation',
+  vertexWaveAmount: 'rippleHeightScale',
+});
+
+export function resolveWaterPresetName(name) {
+  const requested = String(name ?? '').toLowerCase();
+  if (waterPresetRegistry.has(requested)) return requested;
+  const normalized = normalizeWaterPresetId(requested);
+  if (waterPresetRegistry.has(normalized)) return normalized;
+  return WATER_PRESET_ALIASES[requested] ?? 'lake';
+}
+
+function finiteNumber(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}
+
+function clampedNumber(value, fallback, min, max) {
+  return Math.min(max, Math.max(min, finiteNumber(value, fallback)));
+}
+
+function colorArray(value, fallback) {
+  if (value?.isColor) return [value.r, value.g, value.b];
+  if (Array.isArray(value) && value.length >= 3) {
+    const next = value.slice(0, 3).map(Number);
+    return next.every(Number.isFinite) ? next : fallback.slice();
+  }
+  if (typeof value === 'number' || typeof value === 'string') {
+    try {
+      const color = new THREE.Color(value);
+      return [color.r, color.g, color.b];
+    } catch {
+      return fallback.slice();
+    }
+  }
+  if (value && typeof value === 'object') {
+    const next = [value.r, value.g, value.b].map(Number);
+    return next.every(Number.isFinite) ? next : fallback.slice();
+  }
+  return fallback.slice();
+}
+
+function vector2Array(value, fallback) {
+  if (value?.isVector2) return [value.x, value.y];
+  if (Array.isArray(value) && value.length >= 2) {
+    const next = value.slice(0, 2).map(Number);
+    return next.every(Number.isFinite) ? next : fallback.slice();
+  }
+  if (value && typeof value === 'object') {
+    const next = [value.x, value.y].map(Number);
+    return next.every(Number.isFinite) ? next : fallback.slice();
+  }
+  return fallback.slice();
+}
+
+function vector3Array(value, fallback) {
+  if (value?.isVector3) return [value.x, value.y, value.z];
+  if (Array.isArray(value) && value.length >= 3) {
+    const next = value.slice(0, 3).map(Number);
+    return next.every(Number.isFinite) ? next : fallback.slice();
+  }
+  if (value && typeof value === 'object') {
+    const next = [value.x, value.y, value.z].map(Number);
+    return next.every(Number.isFinite) ? next : fallback.slice();
+  }
+  return fallback.slice();
+}
+
+function normalizeLegacyKeys(source) {
+  const normalized = { ...source };
+  for (const [legacyKey, canonicalKey] of Object.entries(LEGACY_KEY_ALIASES)) {
+    if (normalized[legacyKey] !== undefined && normalized[canonicalKey] === undefined) {
+      normalized[canonicalKey] = normalized[legacyKey];
+    }
+  }
+  // The old shader exposed waveStrength around 0.045..0.085; map it onto the
+  // 0..1 intensity dial so historical URLs keep a comparable feel.
+  if (normalized.waveStrength !== undefined && normalized.waveIntensity === undefined) {
+    const legacyStrength = Number(normalized.waveStrength);
+    if (Number.isFinite(legacyStrength)) {
+      normalized.waveIntensity = Math.min(1, Math.max(0, legacyStrength * 8));
+    }
+  }
+  return normalized;
+}
+
+export function createWaterSettings(options = {}) {
+  const rawSource = options && typeof options === 'object' ? options : {};
+  const source = normalizeLegacyKeys(rawSource);
+  const preset = resolveWaterPresetName(source.preset ?? source.mode);
+  const presetSettings = waterPresetRegistry.get(preset)?.settings ?? WATER_PRESETS[preset] ?? {};
+  const base = { ...DEFAULT_WATER_SETTINGS, ...presetSettings };
+  const colorTone = resolveWaterColorToneName(source.colorTone ?? base.colorTone);
+  // A chosen tone forces its palette (see WATER_COLOR_TONES).
+  const tone = WATER_COLOR_TONES[colorTone];
+
+  const quality = WATER_QUALITY_LEVELS.includes(String(source.quality).toLowerCase())
+    ? String(source.quality).toLowerCase()
+    : base.quality;
+
+  return {
+    preset,
+    mode: preset,
+    colorTone,
+    quality,
+
+    waveIntensity: clampedNumber(source.waveIntensity, base.waveIntensity, 0, 1),
+    waterLevel: finiteNumber(source.waterLevel, base.waterLevel),
+
+    // Up to 5 m amplitude = 10 m crest-to-trough wave height at full intensity.
+    waveAmplitude: clampedNumber(source.waveAmplitude, base.waveAmplitude, 0, 5),
+    waveLength: clampedNumber(source.waveLength, base.waveLength, 0.5, 200),
+    waveSteepness: clampedNumber(source.waveSteepness, base.waveSteepness, 0, 1.4),
+    waveSpeed: clampedNumber(source.waveSpeed, base.waveSpeed, 0, 8),
+    waveDirection: vector2Array(source.waveDirection, base.waveDirection),
+    waveDirectionSpread: clampedNumber(source.waveDirectionSpread, base.waveDirectionSpread, 0, 1),
+    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),
+    breakerEnabled: typeof source.breakerEnabled === 'boolean'
+      ? source.breakerEnabled
+      : base.breakerEnabled !== false,
+    breakerAmount: clampedNumber(source.breakerAmount, base.breakerAmount, 0, 1),
+    breakerCurl: clampedNumber(source.breakerCurl, base.breakerCurl, 0, 1),
+    breakerScale: clampedNumber(source.breakerScale, base.breakerScale, 0.25, 3),
+    breakerPeel: clampedNumber(source.breakerPeel, base.breakerPeel, 0, 4),
+    waveSetPeriod: clampedNumber(source.waveSetPeriod, base.waveSetPeriod, 8, 600),
+    waveSetStrength: clampedNumber(source.waveSetStrength, base.waveSetStrength, 0, 1),
+
+    detailNormalStrength: clampedNumber(tone.detailNormalStrength ?? source.detailNormalStrength, base.detailNormalStrength, 0, 2),
+    detailScale: clampedNumber(source.detailScale, base.detailScale, 0.05, 12),
+    flowDirection: vector2Array(source.flowDirection, base.flowDirection),
+    flowSpeed: clampedNumber(source.flowSpeed, base.flowSpeed, 0, 8),
+
+    shallowColor: colorArray(tone.shallowColor ?? source.shallowColor, base.shallowColor),
+    midColor: colorArray(tone.midColor ?? source.midColor, base.midColor),
+    deepColor: colorArray(tone.deepColor ?? source.deepColor, base.deepColor),
+    depthFadeDistance: clampedNumber(tone.depthFadeDistance ?? source.depthFadeDistance, base.depthFadeDistance, 0.01, 60),
+    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),
+    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),
+    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),
+    whitecapAmount: clampedNumber(source.whitecapAmount, base.whitecapAmount, 0, 1),
+    rippleFoamStrength: clampedNumber(source.rippleFoamStrength, base.rippleFoamStrength, 0, 4),
+
+    sunDirection: vector3Array(source.sunDirection, base.sunDirection),
+    sunColor: colorArray(source.sunColor, base.sunColor),
+    specularStrength: clampedNumber(source.specularStrength, base.specularStrength, 0, 4),
+    specularShininess: clampedNumber(source.specularShininess, base.specularShininess, 2, 4000),
+    specularStretch: clampedNumber(source.specularStretch, base.specularStretch, 0, 0.95),
+    sparkleStrength: clampedNumber(source.sparkleStrength, base.sparkleStrength, 0, 4),
+    sparkleScale: clampedNumber(source.sparkleScale, base.sparkleScale, 0.05, 24),
+    sparkleSpeed: clampedNumber(source.sparkleSpeed, base.sparkleSpeed, 0, 8),
+    sunGlowStrength: clampedNumber(source.sunGlowStrength, base.sunGlowStrength, 0, 4),
+    sceneShadowStrength: clampedNumber(source.sceneShadowStrength, base.sceneShadowStrength, 0, 1),
+    fresnelStrength: clampedNumber(source.fresnelStrength, base.fresnelStrength, 0, 2),
+    fresnelPower: clampedNumber(source.fresnelPower, base.fresnelPower, 0.5, 16),
+    fresnelBias: clampedNumber(tone.fresnelBias ?? source.fresnelBias, base.fresnelBias, 0, 0.6),
+    fresnelColor: colorArray(tone.fresnelColor ?? source.fresnelColor, base.fresnelColor),
+    skyZenithColor: colorArray(source.skyZenithColor, base.skyZenithColor),
+    skyHorizonColor: colorArray(source.skyHorizonColor, base.skyHorizonColor),
+    reflectionStrength: clampedNumber(tone.reflectionStrength ?? source.reflectionStrength, base.reflectionStrength, 0, 1.5),
+    reflectionDistortion: clampedNumber(source.reflectionDistortion, base.reflectionDistortion, 0, 0.5),
+    reflectionSoftness: clampedNumber(tone.reflectionSoftness ?? source.reflectionSoftness, base.reflectionSoftness, 0, 1),
+
+    rippleStrength: clampedNumber(source.rippleStrength, base.rippleStrength, 0, 8),
+    rippleDamping: clampedNumber(source.rippleDamping, base.rippleDamping, 0.8, 0.9995),
+    ripplePropagation: clampedNumber(source.ripplePropagation, base.ripplePropagation, 0.5, 80),
+    rippleHeightScale: clampedNumber(source.rippleHeightScale, base.rippleHeightScale, 0, 6),
+    rippleFoamDecay: clampedNumber(source.rippleFoamDecay, base.rippleFoamDecay, 0.5, 0.999),
+    rippleFoamGain: clampedNumber(source.rippleFoamGain, base.rippleFoamGain, 0, 20),
+
+    splashStrength: clampedNumber(source.splashStrength, base.splashStrength, 0, 4),
+    splashScale: clampedNumber(source.splashScale, base.splashScale, 0.1, 6),
+    splashDropletCount: Math.round(clampedNumber(source.splashDropletCount, base.splashDropletCount, 0, 160)),
+    splashRingCount: Math.round(clampedNumber(source.splashRingCount, base.splashRingCount, 0, 5)),
+    splashColor: colorArray(source.splashColor, base.splashColor),
+    splashShadeColor: colorArray(source.splashShadeColor, base.splashShadeColor),
+  };
+}
+
+// --- Gerstner wave spectrum -------------------------------------------------
+
+// Deterministic per-wave pseudo random values so the CPU mirror, the shader
+// uniforms, and reloads always agree.
+function waveRandom(index, salt) {
+  const value = Math.sin(index * 127.1 + salt * 311.7) * 43758.5453;
+  return value - Math.floor(value);
+}
+
+// Builds the Gerstner spectrum evaluated by both the shader and
+// sampleGerstnerHeight. Keep in sync with chunks/water-waves.glsl.
+export function buildGerstnerWaves(settings) {
+  const resolved = settings?.waveDirection ? settings : createWaterSettings(settings);
+  const mainAngle = Math.atan2(resolved.waveDirection[1], resolved.waveDirection[0]);
+  const intensity = Math.pow(resolved.waveIntensity, 1.35);
+  const baseAmplitude = resolved.waveAmplitude * intensity;
+  const spread = resolved.waveDirectionSpread * Math.PI * 0.85;
+
+  const waves = [];
+  for (let i = 0; i < WATER_GERSTNER_WAVE_COUNT; i += 1) {
+    const wavelength = Math.max(resolved.waveLength * Math.pow(0.68, i), 0.05);
+    let waveNumber = (2 * Math.PI) / wavelength;
+    const amplitude = baseAmplitude * Math.pow(wavelength / resolved.waveLength, 0.85);
+    // Deep-water waves are slope-limited: they break beyond ka ~ 0.44, so a
+    // big amplitude forces a proportionally longer wavelength — exactly like
+    // real swell (a 10 m sea is hundreds of meters long, not 13). Without
+    // this cap a big Height dial turns the surface into jagged spikes.
+    if (amplitude * waveNumber > 0.4) {
+      waveNumber = 0.4 / amplitude;
+    }
+    // The primary swell travels exactly along waveDirection; spread only
+    // scatters the secondary components. Keeps the dominant crest lines
+    // long and parallel (what breakers phase-lock to), like real swell.
+    const angle = i === 0 ? mainAngle : mainAngle + (waveRandom(i, 1.0) * 2 - 1) * spread;
+    const omega = Math.sqrt(9.81 * waveNumber) * resolved.waveSpeed;
+    waves.push({
+      dirX: Math.cos(angle),
+      dirZ: Math.sin(angle),
+      omega,
+      waveNumber,
+      amplitude,
+      phase: waveRandom(i, 7.0) * Math.PI * 2,
+      steepness: resolved.waveSteepness * (0.35 + 0.65 * resolved.waveIntensity),
+      crestWeight: Math.sqrt(wavelength / resolved.waveLength),
+    });
+  }
+
+  // Gerstner surfaces self-intersect when the summed steepness exceeds 1.
+  // Normalize so the whole stack stays stable at any dial position.
+  const steepnessSum = waves.reduce(
+    (sum, wave) => sum + wave.steepness * wave.waveNumber * wave.amplitude, 0);
+  if (steepnessSum > 0.9) {
+    const scale = 0.9 / steepnessSum;
+    for (const wave of waves) wave.steepness *= scale;
+  }
+
+  // Wave sets: real swell arrives in groups — the big waves come minutes
+  // apart, not every period. Splitting the primary component into a beat
+  // pair (slots 0 and 1: same direction, slightly different frequency) makes
+  // their interference modulate the swell amplitude with period
+  // waveSetPeriod. The pair is dispersion-consistent, so set envelopes march
+  // in from open water at group velocity instead of pulsing in place.
+  // Everything downstream — heightfield, CPU buoyancy mirror, breakers —
+  // inherits the grouping because it lives inside the same wave stack.
+  const setStrength = resolved.waveSetStrength;
+  if (setStrength > 0.001 && waves.length >= 2) {
+    const primary = waves[0];
+    const beatOmega = primary.omega + (2 * Math.PI) / Math.max(resolved.waveSetPeriod, 1);
+    const speedScale = Math.max(resolved.waveSpeed, 1e-3);
+    const beat = {
+      ...primary,
+      amplitude: primary.amplitude * setStrength * 0.5,
+      omega: beatOmega,
+      waveNumber: (beatOmega / speedScale) ** 2 / 9.81,
+      phase: primary.phase + 2.39,
+    };
+    primary.amplitude *= 1 - setStrength * 0.5;
+    waves.pop(); // drop the smallest tail component to keep the count fixed
+    waves.splice(1, 0, beat);
+  }
+  return waves;
+}
+
+// CPU mirror of the shader's vertical Gerstner displacement. Horizontal
+// choppiness is intentionally ignored, which keeps queries cheap and is
+// 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) {
+  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) -
+      wave.omega * time + wave.phase;
+    height += wave.amplitude * (i < 2 ? 1 : chopWeight) * Math.sin(theta);
+  }
+  return height;
+}
+
+// --- 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: '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).' },
+  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.' },
+  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.' },
+  breakerScale: { group: 'waves', label: 'Breaker Height', min: 0.25, max: 3, step: 0.05, description: 'Shell height multiplier over the physical breaking height (0.72x column depth).' },
+  breakerPeel: { group: 'waves', label: 'Breaker Peel', min: 0, max: 4, step: 0.05, description: 'How fast the barrel section travels sideways along the crest line.' },
+  waveLength: { group: 'waves', label: 'Wave Length', min: 1, max: 120, step: 0.1, description: 'Longest wavelength in meters; smaller waves are derived from it. Big swells need long wavelengths to stay stable.' },
+  waveSteepness: { group: 'waves', label: 'Wave Steepness', min: 0, max: 1.4, step: 0.01, description: 'Gerstner chop; higher values pinch crests sharper.' },
+  waveSpeed: { group: 'waves', label: 'Wave Speed', min: 0, max: 4, step: 0.01, description: 'Phase speed multiplier over the deep-water dispersion.' },
+  waveDirection: { group: 'waves', label: 'Wave Direction', type: 'vector2', description: 'Main travel direction of the swell in the XZ plane.' },
+  waveDirectionSpread: { group: 'waves', label: 'Direction Spread', min: 0, max: 1, step: 0.01, description: '0 keeps all waves aligned (river); 1 spreads them omnidirectionally (open sea). The primary swell always follows Wave Direction exactly.' },
+  waveSetPeriod: { group: 'waves', label: 'Set Period (s)', min: 8, max: 600, step: 1, description: 'Seconds between wave-set peaks at a fixed point; big waves arrive in groups, not every period.' },
+  waveSetStrength: { group: 'waves', label: 'Set Strength', min: 0, max: 1, step: 0.01, description: 'Depth of the set/lull cycle: 0 = constant swell, 1 = the swell dies completely between sets.' },
+  detailNormalStrength: { group: 'waves', label: 'Detail Normals', min: 0, max: 2, step: 0.01, description: 'Strength of the procedural micro-ripple normal detail.' },
+  detailScale: { group: 'waves', label: 'Detail Scale', min: 0.05, max: 8, step: 0.05, description: 'Spatial frequency of the micro-ripple detail.' },
+  flowDirection: { group: 'waves', label: 'Flow Direction', type: 'vector2', description: 'Scroll direction for detail ripples, foam noise, and sparkles.' },
+  flowSpeed: { group: 'waves', label: 'Flow Speed', min: 0, max: 4, step: 0.01, description: 'Scroll speed for surface detail; high values read as a river current.' },
+
+  colorTone: {
+    group: 'surface',
+    label: 'Color Tone',
+    type: 'select',
+    options: WATER_COLOR_TONE_NAMES,
+    optionLabels: Object.freeze({
+      caribbean: 'Caribbean',
+      classic: 'Classic',
+      deepOcean: 'Deep Ocean',
+      anime: 'Anime',
+      lagoon: 'Lagoon',
+      teal: 'Teal',
+    }),
+    description: 'Named body-color palette forced over the preset colors; classic returns control to the preset.',
+  },
+  shallowColor: { group: 'surface', label: 'Shallow Color', type: 'color', description: 'Water tint right at the shoreline.' },
+  midColor: { group: 'surface', label: 'Mid Color', type: 'color', description: 'Water tint at moderate depth.' },
+  deepColor: { group: 'surface', label: 'Deep Color', type: 'color', description: 'Water tint where the bottom is no longer visible.' },
+  depthFadeDistance: { group: 'surface', label: 'Depth Fade', min: 0.05, max: 12, step: 0.05, description: 'Water column depth where the shallow tint gives way to mid.' },
+  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.' },
+  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.' },
+  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.' },
+  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.' },
+  sparkleStrength: { group: 'lighting', label: 'Sparkles', min: 0, max: 3, step: 0.01, description: 'Twinkling star-glint intensity.' },
+  sparkleScale: { group: 'lighting', label: 'Sparkle Scale', min: 0.1, max: 16, step: 0.1, description: 'Density of the sparkle field.' },
+  sparkleSpeed: { group: 'lighting', label: 'Sparkle Speed', min: 0, max: 6, step: 0.05, description: 'How quickly sparkles twinkle in and out.' },
+  sunGlowStrength: { group: 'lighting', label: 'Sun Glow', min: 0, max: 3, step: 0.01, description: 'Sun disk glow in the procedural sky reflection.' },
+  sceneShadowStrength: { group: 'lighting', label: 'Scene Shadows', min: 0, max: 1, step: 0.01, description: 'How strongly cast shadows from rocks, trees, and the character darken the surface.' },
+  fresnelStrength: { group: 'lighting', label: 'Fresnel', min: 0, max: 2, step: 0.01, description: 'Grazing-angle reflectivity boost.' },
+  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.' },
+  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).' },
+
+  rippleStrength: { group: 'ripples', label: 'Ripple Strength', min: 0, max: 6, step: 0.05, description: 'Global multiplier for splash and wake impulses.' },
+  rippleDamping: { group: 'ripples', label: 'Ripple Damping', min: 0.9, max: 0.999, step: 0.001, description: 'Energy retained per frame; higher rings travel farther.' },
+  ripplePropagation: { group: 'ripples', label: 'Ripple Speed', min: 1, max: 40, step: 0.5, description: 'Travel speed of interactive rings across the surface.' },
+  rippleHeightScale: { group: 'ripples', label: 'Ripple Height', min: 0, max: 4, step: 0.05, description: 'Vertical displacement of the interactive ripples.' },
+  rippleFoamDecay: { group: 'ripples', label: 'Wake Foam Decay', min: 0.5, max: 0.999, step: 0.001, description: 'How long wake foam lingers.' },
+  rippleFoamGain: { group: 'ripples', label: 'Wake Foam Gain', min: 0, max: 12, step: 0.1, description: 'How quickly motion generates wake foam.' },
+
+  splashStrength: { group: 'splashes', label: 'Splash Strength', min: 0, max: 3, step: 0.05, description: 'Global multiplier for splash particle counts and energy.' },
+  splashScale: { group: 'splashes', label: 'Splash Scale', min: 0.1, max: 4, step: 0.05, description: 'Physical size multiplier for droplets, spray, and rings.' },
+  splashDropletCount: { group: 'splashes', label: 'Droplet Count', min: 0, max: 120, step: 1, description: 'Droplets emitted by a strength-1 splash.' },
+  splashRingCount: { group: 'splashes', label: 'Ring Count', min: 0, max: 4, step: 1, description: 'Expanding foam rings emitted per splash.' },
+  splashColor: { group: 'splashes', label: 'Splash Color', type: 'color', description: 'Bright tone of droplets and spray.' },
+  splashShadeColor: { group: 'splashes', label: 'Splash Shade', type: 'color', description: 'Shadow tone of the two-tone splash shading.' },
+
+  quality: {
+    group: 'quality',
+    label: 'Quality Tier',
+    type: 'select',
+    options: WATER_QUALITY_LEVELS,
+    optionLabels: Object.freeze({ high: 'High', low: 'Low', medium: 'Medium' }),
+    description: 'Named quality tier: low drops caustics and sparkles, high adds chromatic caustics and extra detail octaves.',
+  },
+};
+
+function inferFieldType(key, value) {
+  const metadata = FIELD_METADATA[key];
+  if (metadata?.type) return metadata.type;
+  if (Array.isArray(value)) return value.length === 2 ? 'vector2' : 'color';
+  return 'number';
+}
+
+export const WATER_SETTING_FIELD_SCHEMA = Object.freeze(
+  Object.fromEntries(
+    Object.entries(FIELD_METADATA).map(([key, metadata]) => {
+      const defaultValue = DEFAULT_WATER_SETTINGS[key];
+      const type = inferFieldType(key, defaultValue);
+      return [key, Object.freeze({
+        key,
+        id: `${metadata.group}.${key}`,
+        group: metadata.group,
+        label: metadata.label,
+        type,
+        min: metadata.min,
+        max: metadata.max,
+        step: metadata.step,
+        range: type === 'number'
+          ? Object.freeze({ min: metadata.min ?? 0, max: metadata.max ?? 1, step: metadata.step ?? 0.01 })
+          : null,
+        options: metadata.options ? Object.freeze([...metadata.options]) : null,
+        optionLabels: metadata.optionLabels ?? null,
+        description: metadata.description,
+        defaultValue,
+        serializable: true,
+      })];
+    }),
+  ),
+);
+
+/**
+ * WATER_SETTING_FIELD_SCHEMA regrouped by setting-group id so it plugs
+ * straight into the schema-driven debug panel, which looks fields up per
+ * group (mirrors the nested shape of TOON_SETTING_FIELD_SCHEMA):
+ *
+ *   createSettingsPanel({
+ *     groups: WATER_SETTING_GROUPS,
+ *     fieldSchema: WATER_SETTING_FIELD_SCHEMA_BY_GROUP,
+ *     ...
+ *   });
+ *
+ * Water settings are flat (no per-group nesting), so hosts read values with
+ * `settings[field.key]` rather than `settings[field.group][field.key]`.
+ */
+export const WATER_SETTING_FIELD_SCHEMA_BY_GROUP = Object.freeze(
+  Object.fromEntries(
+    WATER_SETTING_GROUPS.map((group) => [
+      group.id,
+      Object.freeze(
+        Object.fromEntries(
+          Object.entries(WATER_SETTING_FIELD_SCHEMA).filter(([, field]) => field.group === group.id),
+        ),
+      ),
+    ]),
+  ),
+);
+
+// --- Preset documents & registration -----------------------------------------
+//
+// Mirrors the toon preset document conventions: a preset document is a plain
+// JSON object { type, version, id, label, description, settings } that can be
+// saved to disk, shared, and re-registered on another machine.
+
+/** Document `type` discriminator for serialized water presets. */
+export const WATER_PRESET_DOCUMENT_TYPE = 'toonlab/water-preset';
+
+/** Current water preset document schema version. */
+export const WATER_PRESET_SCHEMA_VERSION = 1;
+
+function cleanObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function booleanFromValue(value, fallback) {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (['1', 'true', 'on', 'yes'].includes(normalized)) return true;
+    if (['0', 'false', 'off', 'no'].includes(normalized)) return false;
+  }
+  if (Number.isFinite(value)) return value !== 0;
+  return fallback;
+}
+
+function coerceWaterFieldValue(value, field) {
+  const fallback = field.defaultValue;
+  switch (field.type) {
+    case 'boolean':
+      return booleanFromValue(value, fallback);
+    case 'number':
+      return finiteNumber(value, fallback);
+    case 'select': {
+      const normalized = String(value ?? '').trim();
+      return field.options?.includes(normalized) ? normalized : fallback;
+    }
+    case 'color':
+      return colorArray(value, fallback);
+    case 'vector2':
+      return vector2Array(value, fallback);
+    case 'vector3':
+      return vector3Array(value, fallback);
+    default:
+      return String(value ?? fallback);
+  }
+}
+
+// Picks the known (schema-covered) setting keys out of a flat definition
+// object, resolving legacy key aliases first.
+function collectTopLevelWaterSettings(source) {
+  const normalized = normalizeLegacyKeys(cleanObject(source));
+  return Object.fromEntries(
+    Object.entries(normalized).filter(([key]) => WATER_SETTING_FIELD_SCHEMA[key]),
+  );
+}
+
+function collectUnknownWaterSettingKeys(settings = {}) {
+  const warnings = [];
+  for (const key of Object.keys(cleanObject(settings))) {
+    if (WATER_SETTING_FIELD_SCHEMA[key] || LEGACY_KEY_ALIASES[key] || key === 'waveStrength') continue;
+    // The preset/mode selection is carried by the document id, not settings.
+    if (key === 'preset' || key === 'mode') continue;
+    warnings.push(`Unknown water setting "${key}" was ignored.`);
+  }
+  return warnings;
+}
+
+/**
+ * Coerces a flat water settings object down to the serializable schema:
+ * numbers stay finite numbers, booleans/selects are validated, and colors and
+ * direction vectors are normalized to plain [r, g, b] / [x, y] / [x, y, z]
+ * arrays (THREE.Color / Vector inputs included). Unknown and runtime-only
+ * keys are dropped; legacy key aliases (e.g. `normalStrength`) are resolved
+ * to their canonical names first.
+ *
+ * Note: presets cannot change the Gerstner wave count —
+ * WATER_GERSTNER_WAVE_COUNT is baked into the shader and the CPU mirror.
+ *
+ * @param {object} [settings] Flat settings overrides keyed like DEFAULT_WATER_SETTINGS.
+ * @returns {object} Sanitized JSON-safe settings object.
+ */
+export function sanitizeWaterPresetSettings(settings = {}) {
+  const source = normalizeLegacyKeys(cleanObject(settings));
+  const sanitized = {};
+  for (const [key, value] of Object.entries(source)) {
+    const field = WATER_SETTING_FIELD_SCHEMA[key];
+    if (!field?.serializable || value === undefined) continue;
+    sanitized[key] = coerceWaterFieldValue(value, field);
+  }
+  return sanitized;
+}
+
+function migrateWaterPresetDocument(input) {
+  const source = cleanObject(input);
+  const version = Number.isFinite(source.version) ? Math.round(source.version) : 0;
+  const settings = cleanObject(source.settings);
+
+  if (version <= 1) {
+    return {
+      description: source.description ?? '',
+      id: source.id ?? source.name ?? source.preset ?? '',
+      label: source.label ?? source.title ?? source.name ?? source.id ?? '',
+      settings: Object.keys(settings).length > 0 ? settings : collectTopLevelWaterSettings(source),
+      type: source.type ?? WATER_PRESET_DOCUMENT_TYPE,
+      version: WATER_PRESET_SCHEMA_VERSION,
+    };
+  }
+
+  return source;
+}
+
+/**
+ * Validates (and migrates) a water preset document. Never throws.
+ *
+ * @param {object} input Parsed preset document (or a loose legacy shape).
+ * @returns {{ok: boolean, errors: string[], warnings: string[], value: object|null}}
+ *   `value` is the normalized document (sanitized settings, canonical type
+ *   and version) when `ok` is true, otherwise null.
+ */
+export function validateWaterPresetDocument(input) {
+  return validateSettingsPresetDocument(input, {
+    collectWarnings: collectUnknownWaterSettingKeys,
+    documentType: WATER_PRESET_DOCUMENT_TYPE,
+    migrateDocument: migrateWaterPresetDocument,
+    normalizeId: normalizeWaterPresetId,
+    sanitizeSettings: sanitizeWaterPresetSettings,
+    schemaVersion: WATER_PRESET_SCHEMA_VERSION,
+  });
+}
+
+/**
+ * Parses a JSON string (or already-parsed object) into a validated water
+ * preset document. Never throws; JSON errors are reported in `errors`.
+ *
+ * @param {string|object} input Preset JSON text or object.
+ * @returns {{ok: boolean, errors: string[], warnings: string[], value: object|null}}
+ */
+export function parseWaterPresetDocument(input) {
+  return parsePresetDocument(input, validateWaterPresetDocument);
+}
+
+/**
+ * Builds a normalized water preset document from a preset id and definition.
+ * The definition may carry a nested `settings` object or flat setting keys
+ * (e.g. `{ waveIntensity: 0.5 }`); either way the result is validated and
+ * sanitized. Throws when the document is invalid (e.g. missing id).
+ *
+ * @param {string} id Preset id (normalized to snake_case lowercase).
+ * @param {object} [definition] `{ label?, description?, settings? }` or flat settings.
+ * @returns {object} `{ type, version, id, label, description, settings }`.
+ */
+export function createWaterPresetDocument(id, definition = {}) {
+  return createSettingsPresetDocument(id, definition, {
+    collectSettings: (source) => source.settings ?? collectTopLevelWaterSettings(source),
+    documentType: WATER_PRESET_DOCUMENT_TYPE,
+    schemaVersion: WATER_PRESET_SCHEMA_VERSION,
+    validateDocument: validateWaterPresetDocument,
+  });
+}
+
+/**
+ * Serializes a water preset to a JSON string. Accepts either
+ * `serializeWaterPreset(id, definition)` or a single document-like object.
+ *
+ * @param {string|object} idOrDocument Preset id, or a document-like object.
+ * @param {object} [definition] Preset definition when the first argument is an id.
+ * @param {{pretty?: boolean}} [options] `pretty` (default true) pretty-prints the JSON.
+ * @returns {string} Preset document JSON.
+ */
+export function serializeWaterPreset(idOrDocument, definition = {}, { pretty = true } = {}) {
+  return serializePresetDocument(idOrDocument, definition, {
+    argumentCount: arguments.length,
+    createDocument: createWaterPresetDocument,
+    pretty,
+  });
+}
+
+/**
+ * Registers a named water preset so it resolves in createWaterSettings /
+ * createWaterMaterial exactly like the built-ins:
+ *
+ *   registerWaterPreset('bioluminescent_bay', {
+ *     label: 'Bioluminescent Bay',
+ *     waveIntensity: 0.1,
+ *     deepColor: [0.01, 0.09, 0.2],
+ *   });
+ *   const settings = createWaterSettings({ preset: 'bioluminescent_bay' });
+ *
+ * Settings are sanitized to serializable values (see
+ * sanitizeWaterPresetSettings). Presets cannot change the Gerstner wave
+ * count — WATER_GERSTNER_WAVE_COUNT is baked into the shader.
+ *
+ * @param {string} name Preset id (normalized to snake_case lowercase).
+ * @param {object} [preset] `{ label?, description?, settings? }` or flat settings.
+ * @param {{overwrite?: boolean}} [options] Set `overwrite: true` to replace an
+ *   existing preset (including built-ins); otherwise re-registering throws.
+ * @returns {{id: string, label: string, description: string}} Registered preset metadata.
+ */
+export function registerWaterPreset(name, preset = {}, { overwrite = false } = {}) {
+  const document = createWaterPresetDocument(name, preset);
+  const presetId = document.id;
+  if (!overwrite && waterPresetRegistry.has(presetId)) {
+    throw new Error(`Water preset "${presetId}" already exists.`);
+  }
+
+  waterPresetRegistry.set(presetId, {
+    description: document.description,
+    label: document.label,
+    settings: Object.freeze({ ...document.settings }),
+  });
+  return { description: document.description, id: presetId, label: document.label };
+}
+
+/**
+ * Registers a preset from serialized JSON (string or parsed document), as
+ * produced by serializeWaterPreset. Overwrites by default so re-importing a
+ * saved preset always takes effect. Throws when the document is invalid.
+ *
+ * @param {string|object} input Preset document JSON or object.
+ * @param {{overwrite?: boolean}} [options]
+ * @returns {{id: string, label: string, description: string}} Registered preset metadata.
+ */
+export function registerSerializedWaterPreset(input, options = {}) {
+  const result = parseWaterPresetDocument(input);
+  if (!result.ok) throw new Error(result.errors.join(' '));
+  return registerWaterPreset(result.value.id, result.value, { overwrite: options.overwrite ?? true });
+}
+
+/**
+ * Lists every registered water preset (built-ins first, then user-registered)
+ * as `{ id, label, description }` entries — ready for a preset picker.
+ *
+ * @returns {Array<{id: string, label: string, description: string}>}
+ */
+export function getWaterPresetOptions() {
+  return Array.from(waterPresetRegistry.entries()).map(([id, preset]) => ({
+    description: preset.description ?? '',
+    id,
+    label: preset.label ?? id,
+  }));
+}