# Tidewater changelog

## v1.1 — 2026-06-15

Free v1.x update. Adds physically-grounded optics, weather and motion off
the hull, scene masking, deterministic multiplayer, and a unified API.

### Surface & optics

- **Physical dielectric Fresnel** — replaced the Schlick approximation
  (above water) and the hand-tuned Snell-window smoothstep (below) with one
  unpolarised dielectric curve parameterised by the water's index of
  refraction (`ior` ≈ 1.333). Above water it's the air→water curve; below,
  the same equations yield total internal reflection past the ~48.6°
  critical angle, so the Snell window's bright disc and dark rim fall out of
  the physics. Applied to `OceanNode` and `OceanFFT`; live `setIor` dial.
- **Persistent wave-crest foam** with a dissolve mask, and a reworked,
  translucent boat wake (no more solid "milk" slab behind the hull).

### Motion & weather

- **Bow spray emitter** — pooled GPU particles throw sheets off the moving
  bow and fire a burst on every wave slam via a hull-impact probe.
- **Rain** — slanted streaks in a camera-anchored column plus live dimples
  poked into the ripple height-field. Per-preset intensity, gated above water.
- **Waterline meniscus** — a refractive rim overlay for the half-submerged
  "camera at the waterline" shot, tracking the projected water plane.

### Scene & multiplayer

- **Water masking** (`WaterMask`) — a screen-space stencil that clips the
  ocean out of registered proxy geometry (hull interiors, pool walls). The
  Pool preset ships with it on.
- **Deterministic multiplayer** — the surface is a closed-form function of
  an integer tick. `seed` + fixed-step `advance(dt)` + `syncToTick(n)` for
  byte-identical waves across clients.

### API

- **`WaterSystem` façade** — one object over every subsystem (`waves`,
  `foam`, `sss`, `ssr`, `wake`, `buoyancy`, `spray`, `rain`, `masking`,
  `floor`, `lighting`, `fog`, `underwater`, `waterline`) with chainable
  setters, `loadPreset(string | object)`, `printSettings()` authoring, and
  `getDebugData()`. Exposed as `window.Tidewater`; fully typed in `types/`.
- Demo gains a **Debug** panel — buoyancy/wake/spray probes + a live
  WebGPU↔WebGL switch (`?renderer=webgl`).

## v1.0 — 2026-05-21

First release. Eight weeks of work across surface, sky, sea floor, and
the underwater scene, plus the sales site, docs and TypeScript types.

### Surface

- **Cascaded FFT ocean** with three Tessendorf spectra at 256 m / 64 m /
  16 m bands. CPU `Spectrum` mirror exposes `sampleHeight(x, z)` so
  buoyancy is frame-perfect with no GPU readback latency.
- **GPU FFT path** — `GPUFFTCascade.js` runs the per-cascade iFFT in TSL
  fragment passes (works on WebGPU + WebGL2 from the same graph). 27 passes
  per cascade per frame at N=64. CPU and GPU adopt the same h₀(k) so the
  rendered surface and the buoyant boat agree.
- **Gerstner swell layer** — analytical band table on top of (or instead
  of) the FFT. Used on Low tier and as the swell mix for the FFT path.
- **Cascaded foam Jacobian** — `1 − J` packed into the spectrum's `.a`
  channel via finite differences. Crests gate on real surface compression
  instead of a noise hack.
- **Physically-based shading** — Fresnel, depth-graded absorption
  (analytical, not screen-space depth), dual-lobe sun glint, normal-map
  cascade, planar reflector + SSR composite (Med+ tier).
- **Real subsurface scattering** — Crytek-style fake-SSS, sun bent toward
  the wave normal, thickness proxy from height + slope, mode-tuneable
  `sssColor / sssAmbient / sssPower / sssDistortion`.
- **Persistent wake field** — world-locked 512² canvas the boat stamps
  into every frame. Sampled in vertex + fragment for displacement and
  foam. The wake is the integral of the path.

### Sky + Atmosphere

- **Dynamic Preetham sky** — `TidewaterSky` wraps three.js `SkyMesh` and
  bakes a PMREM cube each frame (throttled to ~4 Hz with a sun-delta
  epsilon so the time-of-day slider doesn't thrash).
- **Volumetric cloud layer** — built-in TSL fbm cumulus on the same dome.
  Per-mode coverage, density, elevation, scale, speed.
- **Time-of-day dial** — single 0–1 slider drives sun elevation +
  azimuth, repaints the sky, rebakes IBL, rebalances fog, swings the
  god-ray anchor, re-tints water. Each mode has a canonical hour; the
  dial scrubs around it while preserving mode character.

### Sea floor

- **Procedural seabed** — Worley caustic-field on mottled sand, depth-
  tinted, fogged. Caustics shadow under overhanging geometry.
- **Caustic projection on submerged props** — `createCausticProjector()`
  walks the scene graph and splices the same caustic field into every
  submerged material's `emissiveNode`. Per-mesh material clone so shared
  GLTF materials are not mutated in place (fixed a WebGPU bind-group
  crash that appeared after dives).
- **Reef life** — bundled kelp, coral and reef-fish props for the Reef
  preset, hidden in other modes.

### Underwater scene

- **Snell's window** above the camera; total-internal reflection past 49°.
- **Directional Beer–Lambert fog** — looking horizontal hazes fast,
  looking up keeps the Snell window bright. Eye-depth gradient from
  shallow tint near the surface to deep tint past ~40 m.
- **Screen-space god rays** — Postprocess radial-blur, anchored on the
  surface-above-camera projection when underwater. Luma threshold drops
  to ~0.18 so the dimmer Snell-window glow drives the shafts.
- **Twinkling marine snow** — per-particle phase + speed, vertex-colour
  modulated for sun-catch dwell.

### Buoyancy

- **`Buoyancy` class** — reusable, multi-point sampling for genuine
  pitch + roll. Single-point mode for buoys / debris.
- **Three procedural boats** — runabout (primitive geometry), yacht and
  trawler (CC0 GLBs). All wave-coupled.
- **Click-to-splash ripples** — Müller height-field on top of the FFT.
  River mode adds a flow direction so ripples drift downstream.

### Quality + integration

- **Four quality tiers** — Low / Med / High / Ultra, auto-detected from
  backend + UA + pixel budget + hardware concurrency. URL override via
  `?quality=`. Tiers shape ocean segments, FFT N + cascade count, max
  DPR, anisotropy ceiling, reflector resolution, cloud-layer compile.
- **Zero build step** — plain ES modules with an import map. No Vite,
  no webpack.
- **`<water-canvas>` web component** — drop-in custom element for non-
  Three.js sites. Visibility-aware autoplay, ResizeObserver, optional
  OrbitControls, mode + time attributes.
- **TypeScript declarations** — hand-authored `.d.ts` covering every
  public module. Source stays JS.
- **Hand-rolled docs site** at `/docs/`. No static-site generator.
- **Sales site** at `/site/`. Coastal-marine palette, oceanographic-
  chart visual reference, 12-feature long-scroll.

### Modes

10 sea-state presets + 3 water-body presets:

- Reef · Tropical · Offshore · Huge Swell · Sunset · Tranquil · Moonlit
  · Foggy · Arctic · Hurricane
- Lake · River · Pool

Each preset swaps waves, foam, sky, fog, water tint, sea-floor look,
bundled props, and ambient audio mix.