incanto 0.19.0 → 0.21.0

package/dist/{register-Cv5GNiVo.js → register-BC55Ez6I.js}

@@ -5,7 +5,7 @@ import { t as Rng } from "./rng-DP-SR7eg.js";
 import { i as getNodeSchema, l as registerNode } from "./registry-BVJ2HbCn.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.js";
 import { i as applyParticlePreset, o as effectiveOrder, r as PARTICLE_PRESET_NAMES, t as ParticleSim } from "./particle-sim-CyUU7HVU.js";
-import { n as splatWeights, t as buildHeightmap } from "./heightmap-DgX-Opav.js";
+import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
 import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, Color, ConeGeometry, CubeCamera, CylinderGeometry, DataTexture, DepthTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, FloatType, Frustum, Group, HalfFloatType, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LinearMipmapLinearFilter, LoopOnce, LoopRepeat, MathUtils, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NormalBlending, Object3D, PerspectiveCamera, Plane, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, Sphere, SphereGeometry, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector2, Vector3, Vector4, VectorKeyframeTrack, WebGLCubeRenderTarget, WebGLRenderTarget } from "three";
 import { clone } from "three/addons/utils/SkeletonUtils.js";
 //#region src/3d/camera-rig.ts
@@ -1211,6 +1211,7 @@ var Terrain3D = class extends Node3D {
 		layers: { default: [] },
 		textureBase: { default: DEFAULT_TERRAIN_TEXTURE_BASE },
 		basins: { default: [] },
+		channels: { default: [] },
 		wetline: { default: null }
 	};
 	/** [width, depth] extent in meters, centered on the node. */
@@ -1239,6 +1240,10 @@ var Terrain3D = class extends Node3D {
 	* collider + heightAt + dressing all see (place a Water3D in each).
 	* NEGATIVE depth raises a smooth dome MOUND instead (a hill, an islet). */
 	basins = [];
+	/** River/road trenches carved along polylines — `[{ path, width, depth,
+	* taper? }]`. The line counterpart of `basins`: what gives running water a
+	* bed to sit in, and the collider/heightAt/drape all see it. */
+	channels = [];
 	/**
 	* WET SAND band: `{ y, band? }` darkens + glosses the splat in a noisy,
 	* breathing band just above height `y` (a waterline) — the trace of the
@@ -1282,6 +1287,11 @@ var Terrain3D = class extends Node3D {
 		t.basins.forEach((b, i) => {
 			if (!b || typeof b !== "object" || !Number.isFinite(b.x) || !Number.isFinite(b.z) || !(b.radius > 0) || !Number.isFinite(b.depth) || b.depth === 0) throw new IncantoError("BAD_FORMAT", `Terrain3D '${node.name}' basins[${i}] needs finite x, z, positive radius and nonzero depth (negative = mound), got ${JSON.stringify(b)}.`, { prop: "basins" });
 		});
+		if (!Array.isArray(t.channels)) throw new IncantoError("BAD_FORMAT", `Terrain3D '${node.name}' channels must be an array of { path, width, depth, taper? }, got ${JSON.stringify(t.channels)}.`, { prop: "channels" });
+		t.channels.forEach((c, i) => {
+			const path = c.path;
+			if (!(c && typeof c === "object" && Array.isArray(path) && path.length >= 2 && path.every((p) => Array.isArray(p) && Number.isFinite(p[0]) && Number.isFinite(p[1])) && c.width > 0 && c.depth > 0 && (c.taper === void 0 || c.taper > 0))) throw new IncantoError("BAD_FORMAT", `Terrain3D '${node.name}' channels[${i}] needs a path of 2+ [x, z] points plus positive width and depth, got ${JSON.stringify(c)}.`, { prop: "channels" });
+		});
 		if (t.theme === "custom") {
 			if (!Array.isArray(t.layers) || t.layers.length < 1 || t.layers.length > 4) throw new IncantoError("BAD_FORMAT", `Terrain3D '${node.name}' theme 'custom' needs 1–4 layers, got ${Array.isArray(t.layers) ? t.layers.length : typeof t.layers}.`, { prop: "layers" });
 			t.layers.forEach((layer, i) => {
@@ -1326,7 +1336,8 @@ var Terrain3D = class extends Node3D {
 			this.detail,
 			this.flatThreshold,
 			this.effectiveIslandEdge(),
-			this.basins
+			this.basins,
+			this.channels
 		]);
 		if (!this.heightmap || key !== this.heightmapKey) {
 			this.heightmap = buildHeightmap({
@@ -1340,7 +1351,8 @@ var Terrain3D = class extends Node3D {
 				detail: this.detail,
 				flatThreshold: this.flatThreshold,
 				islandEdge: this.effectiveIslandEdge(),
-				basins: this.basins
+				basins: this.basins,
+				channels: this.channels
 			});
 			this.heightmapKey = key;
 		}
@@ -5697,7 +5709,7 @@ function validateSections(sections, name) {
 	}
 }
 /** Endpoint-clamped Catmull-Rom through scalar samples. */
-function catmullRom(p0, p1, p2, p3, t) {
+function catmullRom$1(p0, p1, p2, p3, t) {
 	const t2 = t * t;
 	const t3 = t2 * t;
 	return .5 * (2 * p1 + (p2 - p0) * t + (2 * p0 - 5 * p1 + 4 * p2 - p3) * t2 + (-p0 + 3 * p1 - 3 * p2 + p3) * t3);
@@ -5724,11 +5736,11 @@ function sampleRings(sections, smooth) {
 		for (let s = 0; s < steps; s++) {
 			const t = s / smooth;
 			rings.push({
-				z: catmullRom(a.z, b.z, c.z, d.z, t),
-				width: Math.max(1e-4, catmullRom(a.width, b.width, c.width, d.width, t)),
-				height: Math.max(1e-4, catmullRom(a.height, b.height, c.height, d.height, t)),
-				y: catmullRom(a.y, b.y, c.y, d.y, t),
-				corner: Math.min(1, Math.max(0, catmullRom(a.corner, b.corner, c.corner, d.corner, t)))
+				z: catmullRom$1(a.z, b.z, c.z, d.z, t),
+				width: Math.max(1e-4, catmullRom$1(a.width, b.width, c.width, d.width, t)),
+				height: Math.max(1e-4, catmullRom$1(a.height, b.height, c.height, d.height, t)),
+				y: catmullRom$1(a.y, b.y, c.y, d.y, t),
+				corner: Math.min(1, Math.max(0, catmullRom$1(a.corner, b.corner, c.corner, d.corner, t)))
 			});
 		}
 	}
@@ -6672,6 +6684,1289 @@ function softSprite() {
 	return tex;
 }
 //#endregion
+//#region src/3d/water/interaction.ts
+/**
+* Water3D character interaction — pure functions, no three, node-env testable.
+*
+* The node samples physics bodies each update, detects waterline crossings
+* (`detectCrossings`), and converts them into ripple impulses in a FIXED-SIZE
+* ring buffer that mirrors the shader's `uRipples[8]` uniform array
+* (`pushRipple` / `ageRipples`). `rippleHeight` is the exact ring-wave shape
+* the vertex shader evaluates — `quality: 'simple'` runs it on the CPU.
+*/
+/** Ring-buffer capacity — MUST match `uRipples[8]` in the water shaders. */
+const WATER_MAX_RIPPLES = 8;
+/**
+* Distance from a body's ORIGIN down to its collider's lowest point. Water
+* interaction adds this to the waterline so a body counts as touching the water
+* when its FEET dip below the surface — not only when its centre does (a wading
+* character whose origin rides ~1 m above its feet would otherwise never splash).
+* 0 for a missing/empty/unsized collider (origin == feet).
+*/
+function colliderFootDrop(collider) {
+	if (!collider || typeof collider !== "object") return 0;
+	switch (collider.shape) {
+		case "capsule": return (collider.height ?? 0) / 2 + (collider.radius ?? 0);
+		case "sphere": return collider.radius ?? 0;
+		case "box": return (collider.size?.[1] ?? 0) / 2;
+		default: return 0;
+	}
+}
+/**
+* Foam strength (0..1) for a body ENTERING the water, from its DOWNWARD speed:
+* a gentle wade-in froths a little; a hard plunge froths fully. Clamped at
+* `FOAM_FULL_SPEED`.
+*/
+function entryFoam(fallSpeed) {
+	return .55 + .45 * (Math.min(Math.max(fallSpeed, 0), 12) / 12);
+}
+/**
+* Diff body positions against the waterline. A body enters when `y` drops
+* below its waterline and exits when it rises above `waterline + hysteresis`
+* (the band stops surface-bobbing bodies from flickering entered/exited).
+* Bodies missing from `samples` (despawned mid-water) are dropped WITHOUT an
+* `exited` event — their splash position no longer exists.
+*/
+function detectCrossings(prev, samples, hysteresis = 0) {
+	const entered = [];
+	const exited = [];
+	const inWater = /* @__PURE__ */ new Set();
+	for (const s of samples) {
+		const wasIn = prev.has(s.id);
+		if (wasIn ? s.y <= s.waterline + hysteresis : s.y < s.waterline) {
+			inWater.add(s.id);
+			if (!wasIn) entered.push(s);
+		} else if (wasIn) exited.push(s);
+	}
+	return {
+		entered,
+		exited,
+		inWater
+	};
+}
+/** Append a ripple at age 0; when the buffer is full, evict the OLDEST.
+* `foam` (0..1) tags how much surface froth the shaders paint around it. */
+function pushRipple(ripples, x, z, amp, foam = 0, max = 8) {
+	if (ripples.length >= max) {
+		let oldest = 0;
+		for (let i = 1; i < ripples.length; i++) if (ripples[i].age > ripples[oldest].age) oldest = i;
+		ripples.splice(oldest, 1);
+	}
+	ripples.push({
+		x,
+		z,
+		age: 0,
+		amp,
+		foam
+	});
+}
+/** Advance ages by `dt` and drop ripples decayed past `maxAge` (in place). */
+function ageRipples(ripples, dt, maxAge = 3) {
+	for (let i = ripples.length - 1; i >= 0; i--) {
+		const r = ripples[i];
+		r.age += dt;
+		if (r.age >= maxAge) ripples.splice(i, 1);
+	}
+}
+/** The ring-wave height contribution of one ripple at world (x, z). */
+function rippleHeight(x, z, ripple) {
+	const dx = x - ripple.x;
+	const dz = z - ripple.z;
+	const r = Math.sqrt(dx * dx + dz * dz);
+	return ripple.amp * Math.sin(6 * r - 8 * ripple.age) * Math.exp(-1.1 * ripple.age) * Math.exp(-.15 * r * r);
+}
+/** Sum of every live ripple's height at world (x, z) — the CPU water path. */
+function ripplesHeightAt(x, z, ripples) {
+	let h = 0;
+	for (const r of ripples) h += rippleHeight(x, z, r);
+	return h;
+}
+/**
+* Accumulate per-body bob timers for bodies floating IN water; returns the
+* ids due for a gentle bob impulse this update (timer wraps, cadence keeps).
+* Timers of bodies that left the water are forgotten.
+*/
+function stepBobTimers(timers, inWater, dt, interval) {
+	const due = [];
+	for (const id of timers.keys()) if (!inWater.has(id)) timers.delete(id);
+	for (const id of inWater) {
+		const t = (timers.get(id) ?? 0) + dt;
+		if (t >= interval) {
+			due.push(id);
+			timers.set(id, t - interval);
+		} else timers.set(id, t);
+	}
+	return due;
+}
+//#endregion
+//#region src/3d/water/river.ts
+/** Dense Catmull-Rom taps per control segment before arc-length resampling. */
+const SPLINE_TAPS = 24;
+/** Box-filter half-window (samples) that irons kinks out of the bed profile. */
+const PROFILE_SMOOTH = 3;
+/** Grade → current gain: a 1:10 chute runs ~1.4× the reference speed. */
+const SLOPE_GAIN = 4;
+const SPEED_MIN = .05;
+const SPEED_MAX = 12;
+/**
+* Smooth the control path and walk it at even arc-length steps. The step is
+* nudged so the last sample lands exactly on the mouth — an odd short segment
+* at the end would pinch the ribbon's final quad.
+*/
+function resamplePath(path, step) {
+	const pts = path.map((p) => ({
+		x: p[0] ?? 0,
+		z: p[1] ?? 0
+	})).filter((p, i, all) => i === 0 || Math.hypot(p.x - (all[i - 1]?.x ?? 0), p.z - (all[i - 1]?.z ?? 0)) > 1e-6);
+	if (pts.length < 2 || step <= 0) return [];
+	const dense = [];
+	let acc = 0;
+	for (let i = 0; i < pts.length - 1; i++) {
+		const p0 = pts[Math.max(0, i - 1)];
+		const p1 = pts[i];
+		const p2 = pts[i + 1];
+		const p3 = pts[Math.min(pts.length - 1, i + 2)];
+		for (let s = 0; s < SPLINE_TAPS; s++) {
+			const t = s / SPLINE_TAPS;
+			const x = catmullRom(p0.x, p1.x, p2.x, p3.x, t);
+			const z = catmullRom(p0.z, p1.z, p2.z, p3.z, t);
+			const prev = dense[dense.length - 1];
+			if (prev) acc += Math.hypot(x - prev.x, z - prev.z);
+			dense.push({
+				x,
+				z,
+				along: acc
+			});
+		}
+	}
+	const tail = pts[pts.length - 1];
+	const prev = dense[dense.length - 1];
+	if (prev) acc += Math.hypot(tail.x - prev.x, tail.z - prev.z);
+	dense.push({
+		x: tail.x,
+		z: tail.z,
+		along: acc
+	});
+	const total = acc;
+	if (total < 1e-6) return [];
+	const spans = Math.max(1, Math.round(total / step));
+	const even = total / spans;
+	const out = [];
+	let cursor = 0;
+	for (let i = 0; i <= spans; i++) {
+		const target = Math.min(i * even, total);
+		while (cursor < dense.length - 2 && dense[cursor + 1].along < target) cursor++;
+		const a = dense[cursor];
+		const b = dense[Math.min(cursor + 1, dense.length - 1)];
+		const span = b.along - a.along;
+		const t = span > 1e-9 ? (target - a.along) / span : 0;
+		out.push({
+			x: a.x + (b.x - a.x) * t,
+			z: a.z + (b.z - a.z) * t,
+			tx: 1,
+			tz: 0,
+			along: target
+		});
+	}
+	for (let i = 0; i < out.length; i++) {
+		const a = out[Math.max(0, i - 1)];
+		const b = out[Math.min(out.length - 1, i + 1)];
+		const dx = b.x - a.x;
+		const dz = b.z - a.z;
+		const len = Math.hypot(dx, dz) || 1;
+		const cur = out[i];
+		cur.tx = dx / len;
+		cur.tz = dz / len;
+	}
+	return out;
+}
+/** Width profile lookup at normalized distance `t` ∈ [0, 1] down the river. */
+function widthAlong(widths, t) {
+	if (widths.length === 0) return 0;
+	if (widths.length === 1) return widths[0];
+	const pos = Math.min(Math.max(t, 0), 1) * (widths.length - 1);
+	const i = Math.min(Math.floor(pos), widths.length - 2);
+	const f = pos - i;
+	const a = widths[i];
+	return a + (widths[i + 1] - a) * f;
+}
+/**
+* Stations along the river: surface height, grade and current.
+*
+* The surface profile is the bed's DESCENDING envelope (a running minimum),
+* box-smoothed and re-clamped — water can pour over a lip but never climb one,
+* and the smoothing keeps a noisy bed from shattering the surface into steps.
+* Bed bumps that poke above the resulting surface simply lose their water
+* column: the shader drops them out as riffle rocks.
+*/
+function buildRiverRings(opts) {
+	const samples = resamplePath(opts.path, opts.step);
+	if (samples.length === 0) return [];
+	const total = samples[samples.length - 1].along || 1;
+	const halfWidths = samples.map((s) => Math.max(widthAlong(opts.widths, s.along / total), .05) / 2);
+	const bed = samples.map((s) => opts.bedAt(s.x, s.z));
+	const descending = new Array(bed.length);
+	for (let i = 0; i < bed.length; i++) {
+		const raw = bed[i];
+		descending[i] = i === 0 ? raw : Math.min(raw, descending[i - 1]);
+	}
+	const keep = Math.max(.5, opts.depth * 1.5);
+	const smoothed = descending.map((center, i) => {
+		let sum = 0;
+		let n = 0;
+		for (let k = -3; k <= PROFILE_SMOOTH; k++) {
+			const h = descending[Math.min(Math.max(i + k, 0), descending.length - 1)];
+			if (Math.abs(h - center) > keep) continue;
+			sum += h;
+			n++;
+		}
+		return n > 0 ? sum / n : center;
+	});
+	const profile = new Array(smoothed.length);
+	for (let i = 0; i < smoothed.length; i++) {
+		const s = smoothed[i];
+		profile[i] = i === 0 ? s : Math.min(s, profile[i - 1]);
+	}
+	const meanHalf = halfWidths.reduce((a, b) => a + b, 0) / halfWidths.length || 1;
+	return samples.map((s, i) => {
+		const surfaceY = profile[i] + opts.depth;
+		const prev = Math.max(0, i - 1);
+		const next = Math.min(samples.length - 1, i + 1);
+		const run = samples[next].along - samples[prev].along;
+		const drop = (profile[prev] + opts.depth - (profile[next] + opts.depth)) / (run || 1);
+		const slope = Math.max(0, drop);
+		const halfWidth = halfWidths[i];
+		const speed = Math.min(Math.max(opts.flowSpeed * Math.sqrt(meanHalf / halfWidth) * (1 + SLOPE_GAIN * slope), SPEED_MIN), SPEED_MAX);
+		return {
+			...s,
+			halfWidth,
+			surfaceY,
+			slope,
+			speed
+		};
+	});
+}
+/** Ribbon mesh for the stations — flat across, draped along, attribute-rich. */
+function buildRiverGeometry(rings, opts) {
+	const across = Math.max(1, Math.round(opts.acrossSegments));
+	const perRing = across + 1;
+	const count = rings.length * perRing;
+	const positions = new Float32Array(count * 3);
+	const normals = new Float32Array(count * 3);
+	const uvs = new Float32Array(count * 2);
+	const flow = new Float32Array(count * 2);
+	const river = new Float32Array(count * 4);
+	const quads = Math.max(0, rings.length - 1) * across;
+	const indices = new Uint32Array(quads * 6);
+	for (let r = 0; r < rings.length; r++) {
+		const ring = rings[r];
+		const px = -ring.tz;
+		const pz = ring.tx;
+		const nLen = Math.hypot(ring.slope, 1);
+		const nx = ring.tx * ring.slope / nLen;
+		const ny = 1 / nLen;
+		const nz = ring.tz * ring.slope / nLen;
+		for (let c = 0; c <= across; c++) {
+			const t = c / across * 2 - 1;
+			const offset = t * ring.halfWidth * opts.bankOvershoot;
+			const x = ring.x + px * offset;
+			const z = ring.z + pz * offset;
+			const i = r * perRing + c;
+			positions[i * 3] = x;
+			positions[i * 3 + 1] = ring.surfaceY;
+			positions[i * 3 + 2] = z;
+			normals[i * 3] = nx;
+			normals[i * 3 + 1] = ny;
+			normals[i * 3 + 2] = nz;
+			uvs[i * 2] = ring.along;
+			uvs[i * 2 + 1] = offset;
+			flow[i * 2] = ring.tx;
+			flow[i * 2 + 1] = ring.tz;
+			river[i * 4] = ring.speed;
+			river[i * 4 + 1] = Math.max(0, ring.surfaceY - sampleBed(opts, x, z));
+			river[i * 4 + 2] = ring.slope;
+			river[i * 4 + 3] = t * opts.bankOvershoot;
+		}
+	}
+	let w = 0;
+	for (let r = 0; r + 1 < rings.length; r++) for (let c = 0; c < across; c++) {
+		const a = r * perRing + c;
+		const b = a + 1;
+		const d = a + perRing;
+		const e = d + 1;
+		indices[w++] = a;
+		indices[w++] = b;
+		indices[w++] = d;
+		indices[w++] = b;
+		indices[w++] = e;
+		indices[w++] = d;
+	}
+	return {
+		positions,
+		normals,
+		uvs,
+		flow,
+		river,
+		indices
+	};
+}
+/**
+* Where a world point sits in the channel — the query gameplay runs against
+* (drift a boat, sweep a swimmer, splash a footstep). Projects onto the two
+* segments neighbouring the closest station and keeps the better one.
+*/
+/** Bed height under a vertex, averaged over `bedBlur` (0 = a single tap). */
+function sampleBed(opts, x, z) {
+	const r = opts.bedBlur ?? 0;
+	if (r <= 0) return opts.bedAt(x, z);
+	return (opts.bedAt(x, z) + opts.bedAt(x + r, z) + opts.bedAt(x - r, z) + opts.bedAt(x, z + r) + opts.bedAt(x, z - r)) / 5;
+}
+function projectToRiver(rings, x, z) {
+	if (rings.length === 0) return null;
+	let best = 0;
+	let bestD = Number.POSITIVE_INFINITY;
+	for (let i = 0; i < rings.length; i++) {
+		const r = rings[i];
+		const d = (r.x - x) ** 2 + (r.z - z) ** 2;
+		if (d < bestD) {
+			bestD = d;
+			best = i;
+		}
+	}
+	if (rings.length === 1) {
+		const only = rings[0];
+		return hitFrom(only, only, 0, x, z, false);
+	}
+	let hit = null;
+	let hitD = Number.POSITIVE_INFINITY;
+	for (const start of [best - 1, best]) {
+		if (start < 0 || start + 1 >= rings.length) continue;
+		const a = rings[start];
+		const b = rings[start + 1];
+		const dx = b.x - a.x;
+		const dz = b.z - a.z;
+		const len2 = dx * dx + dz * dz;
+		const raw = len2 > 1e-9 ? ((x - a.x) * dx + (z - a.z) * dz) / len2 : 0;
+		const t = Math.min(Math.max(raw, 0), 1);
+		const capped = start === 0 && raw < 0 || start + 2 === rings.length && raw > 1;
+		const px = a.x + dx * t;
+		const pz = a.z + dz * t;
+		const d = (px - x) ** 2 + (pz - z) ** 2;
+		if (d < hitD) {
+			hitD = d;
+			hit = hitFrom(a, b, t, x, z, capped);
+		}
+	}
+	return hit;
+}
+function hitFrom(a, b, t, x, z, capped) {
+	const cx = a.x + (b.x - a.x) * t;
+	const cz = a.z + (b.z - a.z) * t;
+	let tx = a.tx + (b.tx - a.tx) * t;
+	let tz = a.tz + (b.tz - a.tz) * t;
+	const tl = Math.hypot(tx, tz) || 1;
+	tx /= tl;
+	tz /= tl;
+	const halfWidth = a.halfWidth + (b.halfWidth - a.halfWidth) * t;
+	const across = ((x - cx) * -tz + (z - cz) * tx) / (halfWidth || 1);
+	return {
+		inside: !capped && Math.abs(across) <= 1,
+		across,
+		along: a.along + (b.along - a.along) * t,
+		surfaceY: a.surfaceY + (b.surfaceY - a.surfaceY) * t,
+		dirX: tx,
+		dirZ: tz,
+		speed: a.speed + (b.speed - a.speed) * t,
+		halfWidth
+	};
+}
+/**
+* Find the waterfalls in a course: maximal runs of steep stations, reported at
+* the station where the water lands. Callers hang spray on these, and the
+* shader aerates the curtain from the same grade the detector reads — one
+* source of truth for "this is falling, not flowing".
+*/
+function detectFalls(rings, opts = {}) {
+	const minGrade = opts.minGrade ?? .45;
+	const minDrop = opts.minDrop ?? 1.2;
+	const out = [];
+	let start = -1;
+	for (let i = 0; i <= rings.length; i++) {
+		const steep = i < rings.length && rings[i].slope >= minGrade;
+		if (steep && start < 0) start = i;
+		if (steep || start < 0) continue;
+		const lip = rings[Math.max(0, start - 1)];
+		const base = rings[Math.min(rings.length - 1, i)];
+		const drop = lip.surfaceY - base.surfaceY;
+		if (drop >= minDrop) out.push({
+			x: base.x,
+			z: base.z,
+			topY: lip.surfaceY,
+			baseY: base.surfaceY,
+			drop,
+			halfWidth: base.halfWidth,
+			dirX: base.tx,
+			dirZ: base.tz,
+			speed: base.speed
+		});
+		start = -1;
+	}
+	return out;
+}
+/**
+* Trace where water would actually run from a point: repeated steepest descent
+* with momentum, so the line follows a valley floor instead of rattling between
+* its walls. Ends when the ground goes flat (a pool), the trace leaves the play
+* area, or `maxPoints` is reached.
+*
+* Feed the result straight into a {@link River3D} `path` — the terrain then
+* picks its own river, which is how a generated map gets water that belongs.
+*/
+function traceDownhillPath(bedAt, opts) {
+	const step = Math.max(opts.step, .001);
+	const maxPoints = Math.max(2, opts.maxPoints ?? 200);
+	const minDrop = opts.minDrop ?? step * .01;
+	const bounds = opts.bounds ?? Number.POSITIVE_INFINITY;
+	let x = opts.x;
+	let z = opts.z;
+	let dirX = 0;
+	let dirZ = 0;
+	let stalls = 0;
+	const out = [[x, z]];
+	for (let i = 1; i < maxPoints; i++) {
+		const gx = (bedAt(x + step, z) - bedAt(x - step, z)) / (2 * step);
+		const gz = (bedAt(x, z + step) - bedAt(x, z - step)) / (2 * step);
+		const grad = Math.hypot(gx, gz);
+		let nx = grad > 1e-9 ? -gx / grad : dirX;
+		let nz = grad > 1e-9 ? -gz / grad : dirZ;
+		nx = nx * .6 + dirX * .4;
+		nz = nz * .6 + dirZ * .4;
+		const len = Math.hypot(nx, nz);
+		if (len < 1e-6) break;
+		dirX = nx / len;
+		dirZ = nz / len;
+		let px = x + dirX * step;
+		let pz = z + dirZ * step;
+		let bestOff = 0;
+		let bestY = bedAt(px, pz);
+		for (const off of [
+			-.8,
+			-.4,
+			.4,
+			.8
+		]) {
+			const y = bedAt(px - dirZ * off * step, pz + dirX * off * step);
+			if (y < bestY - 1e-4) {
+				bestY = y;
+				bestOff = off;
+			}
+		}
+		if (bestOff !== 0) {
+			px -= dirZ * bestOff * step;
+			pz += dirX * bestOff * step;
+		}
+		if (Math.abs(px) > bounds || Math.abs(pz) > bounds) break;
+		if (bedAt(x, z) - bedAt(px, pz) < minDrop) {
+			if (++stalls >= 3) break;
+		} else stalls = 0;
+		x = px;
+		z = pz;
+		out.push([x, z]);
+	}
+	return out.length >= 2 ? out : [];
+}
+function catmullRom(p0, p1, p2, p3, t) {
+	const t2 = t * t;
+	const t3 = t2 * t;
+	return .5 * (2 * p1 + (-p0 + p2) * t + (2 * p0 - 5 * p1 + 4 * p2 - p3) * t2 + (-p0 + 3 * p1 - 3 * p2 + p3) * t3);
+}
+//#endregion
+//#region src/3d/water/river-shaders.ts
+/**
+* River surface shader — running water, as distinct from the standing water of
+* {@link WATER_FRAG}.
+*
+* The whole look hangs off four per-vertex facts the CPU derives from the path
+* and the ground (see river.ts): the downstream direction, the current speed,
+* the water column and the grade. From those:
+*
+* - **the current is a frame, not a scroll.** Every pattern lives in the
+*   ribbon's (downstream, across) meters, so a bend carries its ripples around
+*   the corner instead of dragging a world-locked texture sideways.
+* - **speed varies along a river, and that shears any scrolling field apart.**
+*   Two copies of every advected pattern run half a period out of step and
+*   cross-fade on a triangle wave, so each is reset while the other carries the
+*   image — the surface never accumulates smear.
+* - **whitewater is derived, never painted.** Grade × speed makes rapids, the
+*   bank shear line makes edge froth, a thinning column makes riffles over
+*   rock. Foam then rides downstream as stretched streaks.
+* - **standing waves stand.** In a chute the humps are world-locked (phase on
+*   the downstream coordinate, no scroll) while the water tears through them —
+*   the signature of a hydraulic jump, and the thing that reads as "fast".
+*/
+const RIVER_NOISE = `
+float riverHash(vec2 p) {
+  p = fract(p * vec2(127.31, 311.7));
+  p += dot(p, p + 34.23);
+  return fract(p.x * p.y);
+}
+
+float riverNoise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  float a = riverHash(i);
+  float b = riverHash(i + vec2(1.0, 0.0));
+  float c = riverHash(i + vec2(0.0, 1.0));
+  float d = riverHash(i + vec2(1.0, 1.0));
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+}
+`;
+const RIVER_VERT = `
+precision highp float;
+
+#include <fog_pars_vertex>
+
+uniform float uTime;
+uniform float uStandingAmp;
+uniform float uGlideAmp;
+
+// (downstream m, across m) — the flow frame every pattern lives in
+attribute vec2 aFlowUv;
+// unit downstream direction in XZ
+attribute vec2 aFlow;
+// (speed m/s, water column m, grade, across ∈ [-overshoot, +overshoot])
+attribute vec4 aRiver;
+
+varying vec3 vWorldPosition;
+varying vec3 vSurfaceNormal;
+varying vec2 vFlowUv;
+varying vec2 vFlow;
+varying vec4 vRiver;
+
+void main() {
+  vFlowUv = aFlowUv;
+  vFlow = aFlow;
+  vRiver = aRiver;
+
+  float column = aRiver.y;
+  float speed = aRiver.x;
+  float grade = aRiver.z;
+  float across = aRiver.w;
+
+  // displace only where there IS water: a bank vertex whose column has run out
+  // must stay welded to the ground or the ribbon lifts off the shore
+  float body = smoothstep(0.0, 0.3, column) * (1.0 - smoothstep(0.7, 1.0, abs(across)));
+
+  // hydraulic jump: in a chute the wave train stands still in the world (phase
+  // on the downstream coordinate, NEVER scrolled) and only breathes in time
+  // standing waves belong to a RAPID: past ~20° the water has left the bed and
+  // a wave train on a falling curtain reads as a rippling flag
+  float chute = smoothstep(0.035, 0.16, grade) * smoothstep(0.6, 2.4, speed) *
+                (1.0 - smoothstep(0.35, 0.7, grade));
+  float standing =
+    sin(aFlowUv.x * 1.9 + sin(uTime * 0.7) * 0.35) * 0.6 +
+    sin(aFlowUv.x * 3.6 + sin(uTime * 0.9) * 0.5) * 0.4;
+  // calm reach: one long low undulation gliding downstream with the current
+  float glide = sin(aFlowUv.x * 0.5 - uTime * speed * 0.5 + aFlowUv.y * 0.3);
+
+  vec3 displaced = position;
+  displaced.y += body * (standing * chute * uStandingAmp + glide * uGlideAmp * (1.0 - chute));
+
+  vec4 world = modelMatrix * vec4(displaced, 1.0);
+  vWorldPosition = world.xyz;
+  vSurfaceNormal = normalize(mat3(modelMatrix) * normal);
+  // three's fog chunk reads mvPosition — the built-in materials get it from
+  // the project_vertex chunk, which a hand-written vertex stage stands in for
+  vec4 mvPosition = viewMatrix * world;
+  gl_Position = projectionMatrix * mvPosition;
+
+  #include <fog_vertex>
+}
+`;
+const RIVER_FRAG = `
+precision highp float;
+
+#include <fog_pars_fragment>
+
+uniform float uTime;
+uniform vec3 uShallowColor;
+uniform vec3 uDeepColor;
+uniform vec3 uFoamColor;
+uniform vec3 uSkyColor;
+uniform vec3 uHorizonColor;
+uniform vec3 uBankColor;
+uniform vec3 uSunDirection;
+uniform vec3 uSunColor;
+uniform float uSunIntensity;
+uniform float uMaxDepth;
+uniform float uAbsorption;
+uniform float uOpacity;
+uniform float uFoam;
+uniform float uRippleScale;
+uniform float uRippleStrength;
+uniform float uFlowRate;
+uniform float uSparkle;
+uniform float uFresnelScale;
+
+varying vec3 vWorldPosition;
+varying vec3 vSurfaceNormal;
+varying vec2 vFlowUv;
+varying vec2 vFlow;
+varying vec4 vRiver;
+
+${RIVER_NOISE}
+
+/**
+ * Ripple field in flow space: (height, d/d-downstream, d/d-across).
+ *
+ * Anisotropic on purpose — the downstream axis is squeezed so crests run
+ * ACROSS the channel, which is what wavelets on running water actually do.
+ */
+vec3 riverRipple(vec2 p) {
+  vec2 q = vec2(p.x * 1.7, p.y * 0.55);
+  float h = riverNoise(q) * 0.62 + riverNoise(q * 2.4 + 13.1) * 0.38;
+  float e = 0.35;
+  vec2 qa = vec2((p.x + e) * 1.7, p.y * 0.55);
+  vec2 qb = vec2(p.x * 1.7, (p.y + e) * 0.55);
+  float ha = riverNoise(qa) * 0.62 + riverNoise(qa * 2.4 + 13.1) * 0.38;
+  float hb = riverNoise(qb) * 0.62 + riverNoise(qb * 2.4 + 13.1) * 0.38;
+  return vec3(h, (ha - h) / e, (hb - h) / e);
+}
+
+/** Foam streaks: stretched downstream, so froth reads as trails, but broken
+ * enough across the channel that it never becomes a painted stripe. */
+float riverStreak(vec2 p) {
+  vec2 q = vec2(p.x * 0.5, p.y * 2.0);
+  return riverNoise(q) * 0.5 + riverNoise(q * 3.3 + 7.3) * 0.5;
+}
+
+void main() {
+  float speed = vRiver.x;
+  float column = vRiver.y;
+  float grade = vRiver.z;
+  float across = vRiver.w;
+
+  vec2 dir = normalize(vFlow + vec2(1e-5, 0.0));
+  vec3 dir3 = vec3(dir.x, 0.0, dir.y);
+  vec3 perp3 = vec3(-dir.y, 0.0, dir.x);
+
+  // ── dual-phase advection ────────────────────────────────────────────────
+  // A field scrolled at a speed that varies along the river stretches a little
+  // more every frame until it smears. Run two copies half a period apart and
+  // cross-fade with a triangle wave: whichever copy is near its wrap is the one
+  // being faded out, so the reset never shows.
+  float phase = uTime * uFlowRate;
+  float pA = fract(phase);
+  float pB = fract(phase + 0.5);
+  float blend = abs(pA - 0.5) * 2.0;
+  vec2 base = vFlowUv * uRippleScale;
+  float travel = speed * uRippleScale / max(uFlowRate, 0.001);
+
+  vec3 ripA = riverRipple(base - vec2(travel * pA, 0.0));
+  vec3 ripB = riverRipple(base - vec2(travel * pB, 0.0));
+  vec3 ripple = mix(ripA, ripB, blend);
+
+  // on a curtain the pattern stretches into strands: the same field, sampled
+  // with the downstream axis squeezed hard, is what reads as falling water
+  float streakScale = mix(0.55, 0.16, smoothstep(0.35, 0.9, grade));
+  float streakA = riverStreak(base * streakScale - vec2(travel * pA * streakScale, 0.0));
+  float streakB = riverStreak(base * streakScale - vec2(travel * pB * streakScale, 0.0));
+  float streak = mix(streakA, streakB, blend);
+
+  // ripples flatten out where the water thins to a film over the bed
+  float lively = smoothstep(0.02, 0.22, column) * (0.45 + 0.55 * smoothstep(0.1, 1.6, speed));
+  // the gradient is a NOISE slope, not a water slope: clamp it before it tilts
+  // the normal past a real wavelet (an over-driven normal throws fresnel to its
+  // maximum everywhere and the river turns into a sheet of white sky)
+  vec2 slopeXY = clamp(ripple.yz * uRippleStrength * lively, vec2(-0.5), vec2(0.5));
+  vec3 normal = normalize(vSurfaceNormal - dir3 * slopeXY.x - perp3 * slopeXY.y);
+
+  vec3 viewDir = normalize(cameraPosition - vWorldPosition);
+
+  // ── whitewater ──────────────────────────────────────────────────────────
+  // three independent births, all physical: a steep fast reach breaks into
+  // rapids, the shear line along a bank froths, and a column thin enough to
+  // scrape the bed riffles over it
+  float rapids = smoothstep(0.07, 0.22, grade) * smoothstep(1.2, 3.0, speed);
+  // bank froth comes and goes along a shear line — a continuous white hem
+  // around the whole river reads as a drawn outline, never as water
+  float bankPatch = smoothstep(0.35, 0.75, riverStreak(base * 0.22 - vec2(travel * 0.12, 0.0)));
+  float bankShear =
+    smoothstep(0.74, 1.0, abs(across)) * smoothstep(0.8, 2.4, speed) * (0.35 + 0.65 * bankPatch);
+  // shallow is RELATIVE to this river: a hand's depth is a riffle in a brook
+  // and nothing at all in a millrace, so the thresholds ride uMaxDepth
+  float shallowT = column / max(uMaxDepth, 0.05);
+  // a riffle needs water to break OVER something — a centimetres-thin film on
+  // a drying bar is a wet rock, and painting it white is what turns the tail of
+  // a creek into a bright sheet
+  float riffle =
+    smoothstep(0.04, 0.13, column) *
+    (1.0 - smoothstep(0.12, 0.42, shallowT)) *
+    smoothstep(0.7, 2.2, speed);
+  // FALLING, not flowing: past ~20° the sheet leaves the bed, shatters and
+  // aerates. Aerated water is a white DIFFUSE body — it stops mirroring the
+  // sky (that is the tell that separates a waterfall from a steep chute).
+  float fall = smoothstep(0.35, 0.9, grade);
+  float drive = clamp(rapids * 1.0 + bankShear * 0.35 + riffle * 0.5 + fall * 1.6, 0.0, 2.0) * uFoam;
+  // COVERAGE is the thing to be strict about: whitewater is where the surface
+  // has actually broken, and a river that fizzes everywhere reads as milk
+  float foam = smoothstep(0.74 - 0.45 * drive, 1.02 - 0.24 * drive, streak) * min(drive, 1.0);
+  // crest froth: the tops of standing waves in a real rapid always carry white
+  foam = max(foam, smoothstep(0.68, 0.96, ripple.x) * smoothstep(0.4, 1.0, rapids) * uFoam * 0.5);
+  // froth can never be more present than the water carrying it
+  foam = clamp(foam, 0.0, 1.0) * smoothstep(0.02, 0.14, column);
+
+  // ── body ────────────────────────────────────────────────────────────────
+  float depthT = clamp(column / max(uMaxDepth, 0.01), 0.0, 1.0);
+  // THREE bands, because a two-stop ramp lies about thin water. A film over the
+  // bank does not lighten the ground, it DARKENS it — soaked stone, soaked
+  // gravel — and only once there is a real column does the water start showing
+  // its own colour. Skipping the wet band is what makes shallow game water look
+  // like a sheet of cellophane laid over the terrain.
+  vec3 wet = uDeepColor * 0.45;
+  vec3 body = mix(wet, uShallowColor, smoothstep(0.0, 0.3, depthT));
+  body = mix(body, uDeepColor, smoothstep(0.28, 0.78, depthT));
+  // sunlight focused by the ripples dances on the bed of a shallow reach
+  float dapple = smoothstep(0.55, 0.95, ripple.x) * (1.0 - smoothstep(0.15, 0.8, depthT));
+  body += uSunColor * dapple * 0.14 * uSunIntensity;
+
+  // Beer's law decides how much of the bed the water still lets through — this
+  // surface composites over the terrain, so absorption IS the alpha curve
+  float hide = 1.0 - exp(-uAbsorption * column * 3.2);
+
+  // ── sky + sun ───────────────────────────────────────────────────────────
+  // What a river actually mirrors depends on how far up the reflected ray
+  // goes: almost every fragment of a stream is seen at a grazing angle, and
+  // those rays leave nearly horizontal — into the far BANK (dark trees, wet
+  // rock), not the zenith. Reflecting sky everywhere is what turns game water
+  // into a sheet of white plastic.
+  vec3 reflectDir = reflect(-viewDir, normal);
+  // the far bank fills a surprising slice of the reflected hemisphere when the
+  // eye is near the water — hold its dark tone well past the horizon line
+  vec3 sky = mix(uBankColor, uHorizonColor, smoothstep(0.05, 0.34, reflectDir.y));
+  sky = mix(sky, uSkyColor, smoothstep(0.34, 0.85, reflectDir.y));
+  float fresnel = clamp(
+    uFresnelScale * pow(1.0 - clamp(dot(normal, viewDir), 0.0, 1.0), 5.0),
+    0.0,
+    0.82
+  );
+
+  vec3 sunDir = normalize(uSunDirection);
+  vec3 halfVec = normalize(sunDir + viewDir);
+  float ndh = max(dot(normal, halfVec), 0.0);
+  // two lobes: a tight glitter spark plus a broad sheen. The sheen is what
+  // makes a river READ as a moving surface from across the valley, where the
+  // sparkle is smaller than a pixel.
+  float spec = (pow(ndh, 96.0) + pow(ndh, 18.0) * 0.22) * uSunIntensity;
+  // glitter: the same advected field gates the highlight so it breaks into
+  // travelling sparks instead of one smooth sheen
+  float glint = smoothstep(0.55, 0.95, ripple.x);
+  spec *= 0.45 + 0.55 * glint * uSparkle;
+  spec *= 1.0 - foam * 0.85; // froth is rough — it kills the mirror
+
+  fresnel *= 1.0 - 0.85 * fall; // froth scatters; it does not reflect
+  vec3 color = mix(body, sky, fresnel);
+  color += uSunColor * spec * 1.6;
+  color = mix(color, uFoamColor, foam * 0.88);
+
+  // the LIP reads glassy-dark for a moment before the sheet breaks — the
+  // contrast against the white curtain below is most of the drop's drama
+  float lip = smoothstep(0.12, 0.32, grade) * (1.0 - smoothstep(0.32, 0.55, grade));
+  color = mix(color, color * 0.72, lip * 0.6);
+
+  // ── edges ───────────────────────────────────────────────────────────────
+  // the ribbon is built wider than the channel; what makes its outline is the
+  // water running out, so bars and boulders cut it exactly like the ground does
+  float edge = smoothstep(0.0, 0.06, column) * (1.0 - smoothstep(0.84, 1.0, abs(across)));
+  float alpha = clamp(max(hide * uOpacity, fresnel * 0.85), 0.0, 1.0);
+  alpha = clamp(max(alpha, foam * 0.95) * edge, 0.0, 1.0);
+
+  gl_FragColor = vec4(color, alpha);
+
+  #include <tonemapping_fragment>
+  #include <colorspace_fragment>
+  #include <fog_fragment>
+}
+`;
+//#endregion
+//#region src/3d/nodes/river-3d.ts
+/** Ribbon half-width as a multiple of the channel's — the water column fades
+* out inside the overshoot, so the bank is drawn by the ground, not by an edge. */
+const BANK_OVERSHOOT = 1.25;
+/** Centerline station spacing, derived from the narrowest reach. */
+const STEP_MIN = .6;
+const STEP_MAX = 2.5;
+const STEP_PER_WIDTH = .45;
+/** Quads across the channel — enough for the bank fade to read as a gradient. */
+const ACROSS_MIN = 4;
+const ACROSS_MAX = 12;
+const METERS_PER_ACROSS_SEGMENT = 1.5;
+/** Water-column averaging radius — small enough that a boulder still thins the
+* flow over it, wide enough that terrain grain does not fizz the whole river. */
+const COLUMN_BLUR_PER_HALF_WIDTH = .35;
+const COLUMN_BLUR_MAX = 1.2;
+/** How hard the current drags a body toward the water's own velocity (1/s at
+* `flowForce: 1`). Drag, not thrust: nothing ever outruns the river. Tuned
+* against CharacterController3D, whose stand-still damping fights it — at this
+* rate a person planted in a 2 m/s creek slides, which is what a 2 m/s creek
+* does to a person, while a free-floating raft still converges on the current. */
+const CURRENT_DRAG = 6;
+/** A body counts as in the current while its feet are under the surface and it
+* has not sunk more than this far below the bed. */
+const CURRENT_SURFACE_SLACK = .05;
+const CURRENT_UNDER_SLACK = 1.5;
+const DEFAULT_COLORS = {
+	shallow: "#74b2a2",
+	deep: "#123f4b",
+	sky: "#8ab6d8",
+	horizon: "#9fb6c2",
+	bank: "#465447"
+};
+const FOAM_COLOR = "#e9f2ef";
+/** Fixed look constants — the props stay intent-level, these carry the craft. */
+const LOOK = {
+	/** Pattern units per meter of flow space. */
+	rippleScale: .85,
+	/** Ripple normal SLOPE (wavelets are centimetres — a big value reads as
+	* churning glass, not water). */
+	rippleStrength: .09,
+	/** Advection phase periods per second (the dual-phase crossfade rate). */
+	flowRate: .42,
+	fresnelScale: .95,
+	/** Standing-wave height in a chute, meters. */
+	standingAmp: .11,
+	/** Long glide undulation on a calm reach, meters. */
+	glideAmp: .025
+};
+/**
+* A river: running water that finds its own shape.
+*
+* A scene declares a centerline `path`, a `width` (constant or a profile) and a
+* `depth`; the node samples the Terrain3D underneath and derives everything
+* else — a surface that descends with the ground and never climbs, a current
+* that speeds up where the channel pinches or tips, whitewater wherever those
+* two make it, and banks cut by the ground itself (each vertex carries its own
+* water column, and the shader stops drawing where that runs out).
+*
+* Unlike {@link Water3D} it costs no extra render passes — a river is a ribbon
+* with one draw call, so a map can carry a dozen of them.
+*
+* ```json
+* { "type": "River3D", "props": {
+*     "path": [[-80, -30], [-20, 5], [30, 10], [90, -10]],
+*     "widths": [3, 6, 11], "depth": 0.9, "flowSpeed": 1.8 } }
+* ```
+*/
+var River3D = class River3D extends Node3D {
+	static typeName = "River3D";
+	static props = {
+		path: { default: [] },
+		width: { default: 6 },
+		widths: { default: [] },
+		depth: { default: .8 },
+		flowSpeed: { default: 1.6 },
+		colors: { default: {} },
+		absorption: { default: .5 },
+		opacity: { default: .85 },
+		foam: { default: 1 },
+		ripples: { default: 1 },
+		sunDirection: { default: [
+			.5,
+			.8,
+			.3
+		] },
+		sunColor: { default: "#fff6e0" },
+		sunIntensity: { default: 1 },
+		terrain: { default: "" },
+		flowForce: { default: 1 },
+		spray: { default: 1 }
+	};
+	/** Centerline control points `[[x, z], …]` in the node's local frame. */
+	path = [];
+	/** Channel width in meters (constant unless `widths` overrides it). */
+	width = 6;
+	/** Width profile lerped source→mouth, e.g. `[2, 5, 9]` for a stream growing
+	* into a river. Empty = the constant `width`. */
+	widths = [];
+	/** Water column at the centerline, in meters. */
+	depth = .8;
+	/** Reference current in m/s (the mean; reaches speed up and slow down). */
+	flowSpeed = 1.6;
+	/** `{ shallow, deep, sky, horizon, bank }` — the body ramp plus what the
+	* surface mirrors (a grazing river mostly mirrors its BANK, not the sky). */
+	colors = {};
+	/** Beer's-law density: how fast the water hides its bed. */
+	absorption = .5;
+	/** Upper bound on the body's opacity (1 = the deep reach goes solid). */
+	opacity = .85;
+	/** Whitewater dial: 0 = a glassy canal, 1 = default, 2 = raging. */
+	foam = 1;
+	/** Surface-detail dial: ripple relief and glitter. */
+	ripples = 1;
+	/** Glint direction (the sky's sun overrides while this is at its default). */
+	sunDirection = [
+		.5,
+		.8,
+		.3
+	];
+	sunColor = "#fff6e0";
+	sunIntensity = 1;
+	/** Drape target path; empty = auto-find the first Terrain3D in the tree. */
+	terrain = "";
+	/** How hard the current sweeps bodies downstream (0 = visual only). */
+	flowForce = 1;
+	/**
+	* Mist at the foot of every waterfall the course contains: the node finds
+	* the drops itself (see {@link detectFalls}) and hangs a Particles3D plume
+	* on each, sized by how far the water falls. 0 = off.
+	*/
+	spray = 1;
+	renderOrder = 1;
+	time = 0;
+	rings = [];
+	falls = [];
+	sprayKey = "";
+	courseKey = "";
+	bedAt = null;
+	world = [
+		0,
+		0,
+		0
+	];
+	_bodies = [];
+	/** Loader hook: a malformed river fails at LOAD, not as an invisible ribbon. */
+	static validateJson(node) {
+		const r = node;
+		if (!Array.isArray(r.path)) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' path must be an array of [x, z] points, got ${JSON.stringify(r.path)}.`, { prop: "path" });
+		if (r.path.length > 0 && r.path.length < 2) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' path needs at least 2 points (source → mouth), got ${r.path.length}.`, { prop: "path" });
+		r.path.forEach((p, i) => {
+			if (!Array.isArray(p) || p.length < 2 || !Number.isFinite(p[0]) || !Number.isFinite(p[1])) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' path[${i}] must be [x, z] with finite numbers, got ${JSON.stringify(p)}.`, { prop: "path" });
+		});
+		if (!(typeof r.width === "number" && r.width > 0)) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' width must be a positive number of meters, got ${JSON.stringify(r.width)}.`, { prop: "width" });
+		if (!Array.isArray(r.widths) || r.widths.some((w) => !(typeof w === "number" && w > 0))) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' widths must be a list of positive meters (source→mouth), got ${JSON.stringify(r.widths)}.`, { prop: "widths" });
+		if (!(r.depth > 0)) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' depth must be > 0 meters, got ${JSON.stringify(r.depth)}.`, { prop: "depth" });
+		if (!(r.flowSpeed >= 0)) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' flowSpeed must be >= 0 m/s, got ${JSON.stringify(r.flowSpeed)}.`, { prop: "flowSpeed" });
+		for (const key of [
+			"absorption",
+			"foam",
+			"ripples",
+			"flowForce",
+			"spray",
+			"sunIntensity"
+		]) {
+			const v = r[key];
+			if (!(typeof v === "number" && v >= 0)) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' ${key} must be a number >= 0, got ${JSON.stringify(v)}.`, { prop: key });
+		}
+		if (!(r.opacity >= 0 && r.opacity <= 1)) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' opacity must be within [0, 1], got ${JSON.stringify(r.opacity)}.`, { prop: "opacity" });
+		const colors = r.colors;
+		if (typeof colors !== "object" || colors === null || Array.isArray(colors)) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' colors must be an object of { shallow, deep, sky, horizon, bank } hex strings.`, { prop: "colors" });
+		for (const key of Object.keys(colors)) {
+			if (!(key in DEFAULT_COLORS)) throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' colors has unknown key '${key}' — expected shallow, deep, sky, horizon or bank.`, { prop: "colors" });
+			if (typeof colors[key] !== "string") throw new IncantoError("BAD_FORMAT", `River3D '${node.name}' colors.${key} must be a hex string, got ${JSON.stringify(colors[key])}.`, { prop: "colors" });
+		}
+	}
+	_createObject3D() {
+		return new Mesh(new BufferGeometry(), this.buildMaterial());
+	}
+	update(dt) {
+		this.time += dt;
+		this.ensureCourse();
+		this.syncSpray();
+		if (this.flowForce > 0 && this.rings.length > 1) this.sweepBodies(dt);
+	}
+	_syncObject3D() {
+		super._syncObject3D();
+		const mesh = this._ensureObject3D();
+		this.rebuildIfNeeded(mesh);
+		this.syncUniforms(mesh);
+	}
+	/**
+	* Where a WORLD point sits in the channel — the query gameplay scripts run
+	* (steer a raft, drown a torch, decide a ford is too fast to cross). `null`
+	* until the river has been built.
+	*/
+	sampleAt(x, z) {
+		this.ensureCourse();
+		if (this.rings.length === 0) return null;
+		const [wx, wy, wz] = this.world;
+		const hit = projectToRiver(this.rings, x - wx, z - wz);
+		return hit ? {
+			...hit,
+			surfaceY: hit.surfaceY + wy
+		} : null;
+	}
+	/**
+	* The waterfalls on this course — where the water stops flowing and starts
+	* falling, with the drop height and the plunge point in WORLD coordinates.
+	* Hang your own effects (sound, a rainbow, a hidden cave) on these.
+	*/
+	fallsAt() {
+		this.ensureCourse();
+		const [wx, wy, wz] = this.world;
+		return this.falls.map((f) => ({
+			...f,
+			worldX: f.x + wx,
+			worldY: f.baseY + wy,
+			worldZ: f.z + wz
+		}));
+	}
+	/** @internal The derived centerline stations (surface, grade, current). */
+	_rings() {
+		return this.rings;
+	}
+	/**
+	* @internal Environment-sky sun hand-off (see {@link SunConsumer3D}): only
+	* while `sunDirection` sits at its schema default — an authored glint wins.
+	*/
+	_applySunDirection(dir) {
+		const def = River3D.props.sunDirection?.default;
+		if (!this.sunDirection.every((v, i) => v === def[i])) return;
+		(this._ensureObject3D().material.uniforms?.uSunDirection?.value)?.set(dir[0], dir[1], dir[2]);
+	}
+	free() {
+		const mesh = this._ensureObject3D();
+		mesh.geometry?.dispose();
+		mesh.material?.dispose?.();
+		super.free();
+	}
+	widthProfile() {
+		return this.widths.length > 0 ? this.widths : [this.width];
+	}
+	/** Resolve the drape terrain; an explicit path that misses is a hard error. */
+	resolveTerrain() {
+		const terrain = findDrapeTerrain(this, this.terrain);
+		if (!terrain && this.terrain !== "") throw new IncantoError("NODE_NOT_FOUND", `River3D '${this.name}' terrain '${this.terrain}' is not a Terrain3D in the tree.`, { prop: "terrain" });
+		return terrain;
+	}
+	/**
+	* Derive the course (stations + water column) when a shaping prop changed.
+	* Pure CPU work — no three objects — so gameplay can call it any time.
+	*/
+	ensureCourse() {
+		const terrain = this.resolveTerrain();
+		const world = worldXZY(this);
+		const key = JSON.stringify([
+			this.path,
+			this.width,
+			this.widths,
+			this.depth,
+			this.flowSpeed,
+			terrain ? terrain.name : "",
+			world
+		]);
+		if (key === this.courseKey) return false;
+		this.courseKey = key;
+		this.world = world;
+		this.bedAt = null;
+		if (this.path.length < 2) {
+			this.rings = [];
+			this.falls = [];
+			return true;
+		}
+		const [wx, wy, wz] = world;
+		this.bedAt = terrain ? (lx, lz) => terrain.heightAt(lx + wx, lz + wz) - wy : () => -this.depth;
+		const widths = this.widthProfile();
+		const narrow = Math.min(...widths);
+		this.rings = buildRiverRings({
+			path: this.path,
+			widths,
+			depth: this.depth,
+			flowSpeed: this.flowSpeed,
+			step: Math.min(Math.max(narrow * STEP_PER_WIDTH, STEP_MIN), STEP_MAX),
+			bedAt: this.bedAt
+		});
+		this.falls = detectFalls(this.rings);
+		return true;
+	}
+	rebuildIfNeeded(mesh) {
+		if (!this.ensureCourse() && mesh.geometry.getAttribute("position")) return;
+		if (this.rings.length === 0 || !this.bedAt) {
+			mesh.geometry.dispose();
+			const empty = new BufferGeometry();
+			empty.setAttribute("position", new BufferAttribute(new Float32Array(0), 3));
+			mesh.geometry = empty;
+			return;
+		}
+		const widths = this.widthProfile();
+		const narrow = Math.min(...widths);
+		const wide = Math.max(...widths);
+		const data = buildRiverGeometry(this.rings, {
+			acrossSegments: Math.min(ACROSS_MAX, Math.max(ACROSS_MIN, Math.round(wide / METERS_PER_ACROSS_SEGMENT))),
+			bankOvershoot: BANK_OVERSHOOT,
+			bedBlur: Math.min(narrow / 2 * COLUMN_BLUR_PER_HALF_WIDTH, COLUMN_BLUR_MAX),
+			bedAt: this.bedAt
+		});
+		const geometry = new BufferGeometry();
+		geometry.setAttribute("position", new BufferAttribute(data.positions, 3));
+		geometry.setAttribute("normal", new BufferAttribute(data.normals, 3));
+		geometry.setAttribute("aFlowUv", new BufferAttribute(data.uvs, 2));
+		geometry.setAttribute("aFlow", new BufferAttribute(data.flow, 2));
+		geometry.setAttribute("aRiver", new BufferAttribute(data.river, 4));
+		geometry.setIndex(new BufferAttribute(data.indices, 1));
+		geometry.computeBoundingSphere();
+		mesh.geometry.dispose();
+		mesh.geometry = geometry;
+	}
+	buildMaterial() {
+		return new ShaderMaterial({
+			vertexShader: RIVER_VERT,
+			fragmentShader: RIVER_FRAG,
+			fog: true,
+			uniforms: {
+				fogColor: { value: new Color("#ffffff") },
+				fogNear: { value: 1 },
+				fogFar: { value: 1e3 },
+				fogDensity: { value: 25e-5 },
+				uTime: { value: 0 },
+				uShallowColor: { value: new Color(DEFAULT_COLORS.shallow) },
+				uDeepColor: { value: new Color(DEFAULT_COLORS.deep) },
+				uFoamColor: { value: new Color(FOAM_COLOR) },
+				uSkyColor: { value: new Color(DEFAULT_COLORS.sky) },
+				uHorizonColor: { value: new Color(DEFAULT_COLORS.horizon) },
+				uBankColor: { value: new Color(DEFAULT_COLORS.bank) },
+				uSunDirection: { value: new Vector3(.5, .8, .3) },
+				uSunColor: { value: new Color(this.sunColor) },
+				uSunIntensity: { value: this.sunIntensity },
+				uMaxDepth: { value: this.depth },
+				uAbsorption: { value: this.absorption },
+				uOpacity: { value: this.opacity },
+				uFoam: { value: this.foam },
+				uRippleScale: { value: LOOK.rippleScale },
+				uRippleStrength: { value: LOOK.rippleStrength * this.ripples },
+				uFlowRate: { value: LOOK.flowRate },
+				uSparkle: { value: this.ripples },
+				uFresnelScale: { value: LOOK.fresnelScale },
+				uStandingAmp: { value: LOOK.standingAmp },
+				uGlideAmp: { value: LOOK.glideAmp }
+			},
+			transparent: true,
+			depthTest: true,
+			depthWrite: false,
+			polygonOffset: true,
+			polygonOffsetFactor: -2,
+			polygonOffsetUnits: -4,
+			side: DoubleSide
+		});
+	}
+	syncUniforms(mesh) {
+		const u = mesh.material.uniforms;
+		const set = (key, value) => {
+			const slot = u[key];
+			if (slot) slot.value = value;
+		};
+		const tint = (key, hex) => {
+			(u[key]?.value)?.set(hex);
+		};
+		const colors = this.colors;
+		set("uTime", this.time);
+		tint("uShallowColor", colors.shallow ?? DEFAULT_COLORS.shallow);
+		tint("uDeepColor", colors.deep ?? DEFAULT_COLORS.deep);
+		tint("uSkyColor", colors.sky ?? DEFAULT_COLORS.sky);
+		tint("uHorizonColor", colors.horizon ?? DEFAULT_COLORS.horizon);
+		tint("uBankColor", colors.bank ?? DEFAULT_COLORS.bank);
+		tint("uSunColor", this.sunColor);
+		(u.uSunDirection?.value)?.set(this.sunDirection[0] ?? .5, this.sunDirection[1] ?? .8, this.sunDirection[2] ?? .3);
+		set("uSunIntensity", this.sunIntensity);
+		set("uMaxDepth", this.depth);
+		set("uAbsorption", this.absorption);
+		set("uOpacity", this.opacity);
+		set("uFoam", this.foam);
+		set("uRippleStrength", LOOK.rippleStrength * this.ripples);
+		set("uSparkle", this.ripples);
+	}
+	/**
+	* Hang a mist plume on every fall. Runtime children (`__spray*`), rebuilt
+	* only when the course or the dial changes — a plume is a Particles3D, so it
+	* carries its own budget, culling and editor visibility for free.
+	*/
+	syncSpray() {
+		const key = this.spray > 0 ? `${this.spray}|${JSON.stringify(this.falls)}` : "";
+		if (key === this.sprayKey) return;
+		this.sprayKey = key;
+		for (const child of [...this.children]) if (child.name.startsWith("__spray")) child.free();
+		if (this.spray <= 0) return;
+		this.falls.forEach((fall, i) => {
+			const plume = new Particles3D(`__spray${i}`);
+			plume.position = [
+				fall.x + fall.dirX * .6,
+				fall.baseY + .15,
+				fall.z + fall.dirZ * .6
+			];
+			const power = Math.min(1.6, .4 + fall.drop * .12) * this.spray;
+			plume.rate = Math.round(Math.min(46, 10 + fall.drop * 3) * this.spray);
+			plume.maxParticles = 160;
+			plume.lifetime = [1, 2.1];
+			plume.speed = [55 * power, 170 * power];
+			plume.directionDeg = -90;
+			plume.spreadDeg = 58;
+			plume.gravity = [
+				0,
+				-240,
+				0
+			];
+			plume.drag = 1.2;
+			plume.sizeStart = 16 * power;
+			plume.sizeEnd = 80 * power;
+			plume.colorStart = "#ffffff";
+			plume.colorEnd = "#dfe9ec";
+			plume.alphaStart = .2;
+			plume.alphaEnd = 0;
+			plume.blend = "normal";
+			plume.depthTest = true;
+			this.addChild(plume);
+		});
+	}
+	/**
+	* Drag every body floating in the channel toward the water's own velocity.
+	* Drag rather than thrust: a raft accelerates until it matches the current
+	* and then coasts, and a swimmer can still fight across a slow ford.
+	*/
+	sweepBodies(dt) {
+		let top = this;
+		while (top.parent) top = top.parent;
+		const bodies = this._bodies;
+		bodies.length = 0;
+		collectBodies$1(top, bodies);
+		if (bodies.length === 0) return;
+		const [wx, wy, wz] = this.world;
+		for (const body of bodies) {
+			const p = worldXZY(body);
+			const hit = projectToRiver(this.rings, p[0] - wx, p[2] - wz);
+			if (!hit?.inside) continue;
+			const surfaceY = hit.surfaceY + wy;
+			const feet = p[1] - colliderFootDrop(body.collider);
+			if (feet > surfaceY + CURRENT_SURFACE_SLACK) continue;
+			if (feet < surfaceY - this.depth - CURRENT_UNDER_SLACK) continue;
+			const vel = bodyVelocity$1(body);
+			if (!vel) continue;
+			const gain = Math.min(1, this.flowForce * CURRENT_DRAG * dt);
+			const dvx = (hit.dirX * hit.speed - (vel[0] ?? 0)) * gain;
+			const dvz = (hit.dirZ * hit.speed - (vel[2] ?? 0)) * gain;
+			if (body instanceof RigidBody3D) {
+				const mass = body.mass || 1;
+				body.applyImpulse([
+					dvx * mass,
+					0,
+					dvz * mass
+				]);
+			} else {
+				vel[0] = (vel[0] ?? 0) + dvx;
+				vel[2] = (vel[2] ?? 0) + dvz;
+			}
+		}
+	}
+};
+/** Bodies a current can carry: kinematic characters and dynamic rigid bodies. */
+function collectBodies$1(node, out) {
+	if (node instanceof CharacterBody3D || node instanceof RigidBody3D) out.push(node);
+	for (const child of node.children) collectBodies$1(child, out);
+}
+/** A body's velocity vector — kinematic `velocity` or dynamic `linearVelocity`. */
+function bodyVelocity$1(body) {
+	return body.velocity ?? body.linearVelocity;
+}
+//#endregion
 //#region src/3d/nodes/trail-3d.ts
 const MAX_POINTS = 128;
 /**
@@ -9948,121 +11243,6 @@ function sphereInCameraFrustum(camera, center, radius) {
 	return scratchFrustum.intersectsSphere(scratchSphere);
 }
 //#endregion
-//#region src/3d/water/interaction.ts
-/**
-* Water3D character interaction — pure functions, no three, node-env testable.
-*
-* The node samples physics bodies each update, detects waterline crossings
-* (`detectCrossings`), and converts them into ripple impulses in a FIXED-SIZE
-* ring buffer that mirrors the shader's `uRipples[8]` uniform array
-* (`pushRipple` / `ageRipples`). `rippleHeight` is the exact ring-wave shape
-* the vertex shader evaluates — `quality: 'simple'` runs it on the CPU.
-*/
-/** Ring-buffer capacity — MUST match `uRipples[8]` in the water shaders. */
-const WATER_MAX_RIPPLES = 8;
-/**
-* Distance from a body's ORIGIN down to its collider's lowest point. Water
-* interaction adds this to the waterline so a body counts as touching the water
-* when its FEET dip below the surface — not only when its centre does (a wading
-* character whose origin rides ~1 m above its feet would otherwise never splash).
-* 0 for a missing/empty/unsized collider (origin == feet).
-*/
-function colliderFootDrop(collider) {
-	if (!collider || typeof collider !== "object") return 0;
-	switch (collider.shape) {
-		case "capsule": return (collider.height ?? 0) / 2 + (collider.radius ?? 0);
-		case "sphere": return collider.radius ?? 0;
-		case "box": return (collider.size?.[1] ?? 0) / 2;
-		default: return 0;
-	}
-}
-/**
-* Foam strength (0..1) for a body ENTERING the water, from its DOWNWARD speed:
-* a gentle wade-in froths a little; a hard plunge froths fully. Clamped at
-* `FOAM_FULL_SPEED`.
-*/
-function entryFoam(fallSpeed) {
-	return .55 + .45 * (Math.min(Math.max(fallSpeed, 0), 12) / 12);
-}
-/**
-* Diff body positions against the waterline. A body enters when `y` drops
-* below its waterline and exits when it rises above `waterline + hysteresis`
-* (the band stops surface-bobbing bodies from flickering entered/exited).
-* Bodies missing from `samples` (despawned mid-water) are dropped WITHOUT an
-* `exited` event — their splash position no longer exists.
-*/
-function detectCrossings(prev, samples, hysteresis = 0) {
-	const entered = [];
-	const exited = [];
-	const inWater = /* @__PURE__ */ new Set();
-	for (const s of samples) {
-		const wasIn = prev.has(s.id);
-		if (wasIn ? s.y <= s.waterline + hysteresis : s.y < s.waterline) {
-			inWater.add(s.id);
-			if (!wasIn) entered.push(s);
-		} else if (wasIn) exited.push(s);
-	}
-	return {
-		entered,
-		exited,
-		inWater
-	};
-}
-/** Append a ripple at age 0; when the buffer is full, evict the OLDEST.
-* `foam` (0..1) tags how much surface froth the shaders paint around it. */
-function pushRipple(ripples, x, z, amp, foam = 0, max = 8) {
-	if (ripples.length >= max) {
-		let oldest = 0;
-		for (let i = 1; i < ripples.length; i++) if (ripples[i].age > ripples[oldest].age) oldest = i;
-		ripples.splice(oldest, 1);
-	}
-	ripples.push({
-		x,
-		z,
-		age: 0,
-		amp,
-		foam
-	});
-}
-/** Advance ages by `dt` and drop ripples decayed past `maxAge` (in place). */
-function ageRipples(ripples, dt, maxAge = 3) {
-	for (let i = ripples.length - 1; i >= 0; i--) {
-		const r = ripples[i];
-		r.age += dt;
-		if (r.age >= maxAge) ripples.splice(i, 1);
-	}
-}
-/** The ring-wave height contribution of one ripple at world (x, z). */
-function rippleHeight(x, z, ripple) {
-	const dx = x - ripple.x;
-	const dz = z - ripple.z;
-	const r = Math.sqrt(dx * dx + dz * dz);
-	return ripple.amp * Math.sin(6 * r - 8 * ripple.age) * Math.exp(-1.1 * ripple.age) * Math.exp(-.15 * r * r);
-}
-/** Sum of every live ripple's height at world (x, z) — the CPU water path. */
-function ripplesHeightAt(x, z, ripples) {
-	let h = 0;
-	for (const r of ripples) h += rippleHeight(x, z, r);
-	return h;
-}
-/**
-* Accumulate per-body bob timers for bodies floating IN water; returns the
-* ids due for a gentle bob impulse this update (timer wraps, cadence keeps).
-* Timers of bodies that left the water are forgotten.
-*/
-function stepBobTimers(timers, inWater, dt, interval) {
-	const due = [];
-	for (const id of timers.keys()) if (!inWater.has(id)) timers.delete(id);
-	for (const id of inWater) {
-		const t = (timers.get(id) ?? 0) + dt;
-		if (t >= interval) {
-			due.push(id);
-			timers.set(id, t - interval);
-		} else timers.set(id, t);
-	}
-	return due;
-}
-//#endregion
 //#region src/3d/water/lake.ts
 /**
 * The Water3D 'simple' quality lake shader — the CHEAP good-looking path.
@@ -10517,6 +11697,9 @@ uniform vec4 uRipples[8];
 uniform float uSwellAmplitude;
 uniform vec2 uSwellDir;
 uniform float uSwellWavelength;
+// incanto GERSTNER: 0 = the legacy height-only swell, 1 = maximum trochoid
+// pinch (crests narrow to a peak). Physical steepness, capped per train.
+uniform float uSwellSteepness;
 // incanto shore: the SWASH SURGE shares the shore-waves dial — a very long
 // slow bulge marching shoreward; ±9 cm of water height walks the waterline
 // meters up and down a gentle beach (the lapping runup).
@@ -10529,6 +11712,8 @@ uniform float uEdgeFadeOn;
 varying vec3 vNormal;
 varying vec3 vWorldPosition;
 varying vec4 vScreenPosition;
+// incanto GERSTNER: how far the surface has folded here (whitecap seed)
+varying float vFold;
 
 //	Simplex 3D Noise
 //	by Ian McEwan, Stefan Gustavson (https://github.com/stegu/webgl-noise)
@@ -10631,6 +11816,43 @@ float getSwell(vec2 p) {
        + swellWave(p, d3, uSwellWavelength * 0.31, uSwellAmplitude * 0.16, 1.8);
 }
 
+// incanto GERSTNER: the horizontal half of a swell. A height field can only
+// raise and lower water; a real wave train also DRAGS it toward the crest,
+// which is what makes crests narrow and troughs broad — the single strongest
+// tell of open ocean. The same derivatives give the JACOBIAN of the surface
+// map, and where that collapses the water is folding over itself: whitecaps
+// belong exactly there, not wherever the height happens to be high.
+//
+// Returns (pinch.x, pinch.z, fold) — fold is 1 where the surface folds.
+vec3 getSwellPinch(vec2 p) {
+  if (uSwellAmplitude <= 0.0 || uSwellSteepness <= 0.0) return vec3(0.0);
+  vec2 d1 = uSwellDir;
+  vec2 d2 = normalize(vec2(d1.x * 0.906 - d1.y * 0.423, d1.x * 0.423 + d1.y * 0.906));
+  vec2 d3 = normalize(vec2(d1.x * 0.946 + d1.y * 0.326, -d1.x * 0.326 + d1.y * 0.946));
+  vec2 pinch = vec2(0.0);
+  float jxx = 1.0;
+  float jzz = 1.0;
+  float jxz = 0.0;
+  // (direction, wavelength, amplitude) — the same three trains as getSwell
+  for (int i = 0; i < 3; i++) {
+    vec2 d = i == 0 ? d1 : (i == 1 ? d2 : d3);
+    float lambda = uSwellWavelength * (i == 0 ? 1.0 : (i == 1 ? 0.53 : 0.31));
+    float amp = uSwellAmplitude * (i == 0 ? 0.60 : (i == 1 ? 0.27 : 0.16));
+    float k = 6.2831853 / max(lambda, 1.0);
+    float c = sqrt(9.8 / k);
+    float phase = dot(p, d) * k - uTime * c * k;
+    // steepness per train, capped so the trochoid never loops back on itself
+    float q = min(uSwellSteepness / max(k * amp * 3.0, 1e-4), 1.0);
+    pinch -= d * (q * amp * cos(phase));
+    float f = q * amp * k * sin(phase);
+    jxx -= d.x * d.x * f;
+    jzz -= d.y * d.y * f;
+    jxz -= d.x * d.y * f;
+  }
+  float jacobian = jxx * jzz - jxz * jxz;
+  return vec3(pinch, 1.0 - smoothstep(0.15, 0.75, jacobian));
+}
+
 // incanto: waves + swell + ripples — used for displacement AND the normal
 // samples so every layer catches the light like real waves.
 // incanto shore: two incommensurate long surges — the waterline breathes in
@@ -10652,6 +11874,13 @@ void main() {
 
   float elevation = getHeight(modelPosition.x, modelPosition.z);
   modelPosition.y += elevation;
+  // Gerstner pinch: the height field is sampled at the UNDISPLACED position
+  // (so the analytic finite-difference normals below stay consistent), then
+  // the surface is dragged horizontally toward its crests. At the steepness
+  // this ships the normal error is far under the detail-normal layers.
+  vec3 pinch = getSwellPinch(modelPosition.xz);
+  modelPosition.xz += pinch.xy;
+  vFold = pinch.z;
 
   // Height adjustment to smooth water edges
   // Lower water height as it approaches scale boundaries
@@ -10784,8 +12013,20 @@ uniform float uEdgeWidth;
 varying vec3 vNormal;
 varying vec3 vWorldPosition;
 varying vec4 vScreenPosition;
+// incanto GERSTNER: how far the surface has folded here (whitecap seed)
+varying float vFold;
 
 uniform samplerCube uEnvironmentMap;
+// incanto MIRROR: a planar reflection rendered from the camera mirrored across
+// the water plane. A water-centered cube map can only carry DISTANT content —
+// the shoreline trees, the boat, the player standing at the edge are exactly
+// what a still lake is supposed to show, and only a planar pass has them.
+// uMirrorMatrix projects a world position into that render's UV, so the sample
+// is self-consistent no matter where the fragment sits on the surface.
+uniform sampler2D uMirrorMap;
+uniform mat4 uMirrorMatrix;
+uniform float uUseMirror;
+uniform float uMirrorDistort;
 
 // Noise function (for foam patterns)
 float hash(vec2 p) {
@@ -11160,6 +12401,27 @@ void main() {
   vec4 reflectionColor = textureCube(uEnvironmentMap, reflectedDirection);
   reflectionColor.rgb = min(reflectionColor.rgb, vec3(2.5));
 
+  // incanto MIRROR: where the planar pass has data it REPLACES the cube — it
+  // is the same sky plus everything the cube map is blind to. Rays that leave
+  // the screen have no mirror sample, so the border fade hands those back to
+  // the cube instead of clamping a stretched edge texel across the surface.
+  if (uUseMirror > 0.5) {
+    vec4 mirrorClip = uMirrorMatrix * vec4(vWorldPosition, 1.0);
+    vec2 mirrorUv = mirrorClip.xy / max(mirrorClip.w, 1e-4);
+    // the ripple tilt bends the reflected ray: offset the sample by how far
+    // the wavelet normal leans off flat, damped with distance so the far field
+    // (many wavelets per pixel) stays a clean mirror instead of a jitter field
+    vec2 lean = (fresnelNormal.xz - geoNormal.xz) * uMirrorDistort;
+    mirrorUv += lean * (1.0 - smoothstep(20.0, 90.0, camDist));
+    vec2 edge = smoothstep(vec2(0.0), vec2(0.06), mirrorUv) *
+                (1.0 - smoothstep(vec2(0.94), vec2(1.0), mirrorUv));
+    float valid = edge.x * edge.y * step(0.0, mirrorClip.w);
+    if (valid > 0.0) {
+      vec3 mirrored = min(texture2D(uMirrorMap, mirrorUv).rgb, vec3(2.5));
+      reflectionColor.rgb = mix(reflectionColor.rgb, mirrored, valid);
+    }
+  }
+
   // Calculate fresnel effect
   // incanto: the source dotted the camera→surface direction against the
   // up-facing normal — NEGATIVE at every above-water angle, so the clamp
@@ -11410,6 +12672,10 @@ void main() {
     float capNoise = noise(capUV * 2.2 + uTime * vec2(0.10, 0.06)) * 0.65
                    + noise(capUV * 6.5 - uTime * vec2(0.05, 0.14)) * 0.35;
     float capFade = 1.0 - smoothstep(220.0, 640.0, camDist);
+    // height says WHERE the crest is; the Jacobian says where it is actually
+    // breaking. Taking the max keeps the tuned height-based caps and adds the
+    // ones physics insists on — the pinched crest faces about to spill.
+    cap = max(cap, vFold);
     float whitecap = uWhitecaps * cap * smoothstep(0.42, 0.78, capNoise) * capFade;
     foamAmount = max(foamAmount, whitecap);
   }
@@ -11836,6 +13102,10 @@ const WAVE_WORLD_REF = 128;
 const AMPLITUDE_PER_WAVE_HEIGHT = REFERENCE_AMPLITUDE / REFERENCE_WAVE_HEIGHT;
 /** Cube-map reflection resolution (source: reflectionQuality = 256). */
 const REFLECTION_RESOLUTION = 256;
+/** Planar-mirror target size cap (per side) — half the drawing buffer, clamped. */
+const MIRROR_PASS_MAX = 1024;
+/** How far a wavelet's tilt slides the mirror sample, in UV per unit of normal lean. */
+const MIRROR_DISTORT = .06;
 /** Scene pre-pass (depth for absorption/foam + color grab for refraction):
 * half the drawing buffer, clamped — ONE extra scene render per frame. */
 const SCENE_PASS_MAX = 1024;
@@ -11921,6 +13191,8 @@ var Water3D = class Water3D extends Node3D {
 		colors: { default: {} },
 		reflection: { default: true },
 		reflectionInterval: { default: 1e3 },
+		mirror: { default: false },
+		swellSteepness: { default: .35 },
 		foam: { default: true },
 		interaction: { default: true },
 		splash: { default: true },
@@ -11963,6 +13235,14 @@ var Water3D = class Water3D extends Node3D {
 	colors = {};
 	/** CubeCamera reflections (fancy only; needs a live renderer). */
 	reflection = true;
+	/**
+	* TRUE planar reflection: the scene re-rendered from the camera mirrored
+	* across this surface, sampled per fragment. A cube map can only carry
+	* distant content — the shoreline trees, the moored boat, the player at the
+	* water's edge only appear in the water with this on. Costs one extra scene
+	* render per frame, so it is off by default; a still lake earns it.
+	*/
+	mirror = false;
 	/** ms between reflection (and foam depth) re-renders. */
 	reflectionInterval = 1e3;
 	/** Depth-texture shoreline foam — rides the always-on fancy scene pass. */
@@ -12011,6 +13291,13 @@ var Water3D = class Water3D extends Node3D {
 	swellDirectionDeg = 0;
 	/** Primary swell wavelength in meters (the two crossing trains derive). */
 	swellWavelength = 30;
+	/**
+	* GERSTNER pinch on the swell: 0 keeps the legacy height-only trains, 1 is
+	* maximum trochoid (crests narrow to a peak, troughs go broad). It also
+	* decides where whitecaps break — the surface's Jacobian collapses on a
+	* folding crest, and that is where foam belongs.
+	*/
+	swellSteepness = .35;
 	/** Open-water whitecap foam on the tallest crests, 0–1 (fancy only). Works
 	* best with `swell` — the caps ride the swell's crest lines. */
 	whitecaps = 0;
@@ -12122,6 +13409,9 @@ var Water3D = class Water3D extends Node3D {
 	lastReflectionAt = 0;
 	/** Per-frame scene pre-pass: depth (absorption/foam) + color grab (refraction). */
 	scenePassTarget = null;
+	mirrorTarget = null;
+	mirrorCamera = new PerspectiveCamera();
+	mirrorMatrix = new Matrix4();
 	_createObject3D() {
 		return new Mesh();
 	}
@@ -12154,6 +13444,7 @@ var Water3D = class Water3D extends Node3D {
 				const u = material.uniforms;
 				if (u.uUseSceneDepth) u.uUseSceneDepth.value = 0;
 				if (u.uUseRefraction) u.uUseRefraction.value = 0;
+				if (u.uUseMirror) u.uUseMirror.value = 0;
 			}
 			return;
 		}
@@ -12189,6 +13480,57 @@ var Water3D = class Water3D extends Node3D {
 				u.uUseEnvironmentMap.value = 1;
 			}
 		}
+		if (this.mirror && u.uMirrorMap && u.uMirrorMatrix && u.uUseMirror) {
+			ctx.gl.getDrawingBufferSize(drawingBufferScratch);
+			const mirrorW = Math.max(1, Math.min(Math.round(drawingBufferScratch.x / 2), MIRROR_PASS_MAX));
+			const mirrorH = Math.max(1, Math.min(Math.round(drawingBufferScratch.y / 2), MIRROR_PASS_MAX));
+			if (this.mirrorTarget && (this.mirrorTarget.width !== mirrorW || this.mirrorTarget.height !== mirrorH)) {
+				this.mirrorTarget.dispose();
+				this.mirrorTarget = null;
+			}
+			if (!this.mirrorTarget) this.mirrorTarget = new WebGLRenderTarget(mirrorW, mirrorH, {
+				depthBuffer: true,
+				stencilBuffer: false,
+				type: HalfFloatType
+			});
+			const surfaceY = worldTranslationOf(this).y;
+			const cam = ctx.camera;
+			cam.getWorldPosition(mirrorEyeScratch);
+			cam.getWorldQuaternion(mirrorQuatScratch);
+			mirrorTargetScratch.set(0, 0, -1).applyQuaternion(mirrorQuatScratch).add(mirrorEyeScratch);
+			mirrorUpScratch.set(0, 1, 0).applyQuaternion(mirrorQuatScratch);
+			mirrorEyeScratch.y = 2 * surfaceY - mirrorEyeScratch.y;
+			mirrorTargetScratch.y = 2 * surfaceY - mirrorTargetScratch.y;
+			mirrorUpScratch.y = -mirrorUpScratch.y;
+			const mirrorCam = this.mirrorCamera;
+			mirrorCam.fov = cam.fov ?? 50;
+			mirrorCam.aspect = cam.aspect ?? mirrorW / mirrorH;
+			mirrorCam.near = cam.near ?? .1;
+			mirrorCam.far = cam.far ?? 1e3;
+			mirrorCam.position.copy(mirrorEyeScratch);
+			mirrorCam.up.copy(mirrorUpScratch);
+			mirrorCam.lookAt(mirrorTargetScratch);
+			mirrorCam.updateMatrixWorld(true);
+			mirrorCam.updateProjectionMatrix();
+			this.mirrorMatrix.set(.5, 0, 0, .5, 0, .5, 0, .5, 0, 0, .5, .5, 0, 0, 0, 1);
+			this.mirrorMatrix.multiply(mirrorCam.projectionMatrix);
+			this.mirrorMatrix.multiply(mirrorCam.matrixWorldInverse);
+			const prevMirrorTarget = ctx.gl.getRenderTarget();
+			const prevMirrorClip = ctx.gl.clippingPlanes;
+			const wasMirrorVisible = mesh.visible;
+			mesh.visible = false;
+			mirrorClipPlane.constant = -(surfaceY - WATERLINE_CLIP_SLACK);
+			ctx.gl.clippingPlanes = mirrorClipPlanes;
+			ctx.gl.setRenderTarget(this.mirrorTarget);
+			ctx.gl.clear(true, true, false);
+			ctx.gl.render(ctx.scene, mirrorCam);
+			ctx.gl.setRenderTarget(prevMirrorTarget);
+			ctx.gl.clippingPlanes = prevMirrorClip;
+			mesh.visible = wasMirrorVisible;
+			u.uMirrorMap.value = this.mirrorTarget.texture;
+			u.uMirrorMatrix.value.copy(this.mirrorMatrix);
+			u.uUseMirror.value = 1;
+		} else if (u.uUseMirror) u.uUseMirror.value = 0;
 		ctx.gl.getDrawingBufferSize(drawingBufferScratch);
 		const passW = Math.max(1, Math.min(Math.round(drawingBufferScratch.x / 2), SCENE_PASS_MAX));
 		const passH = Math.max(1, Math.min(Math.round(drawingBufferScratch.y / 2), SCENE_PASS_MAX));
@@ -12277,6 +13619,8 @@ var Water3D = class Water3D extends Node3D {
 		this.scenePassTarget?.depthTexture?.dispose();
 		this.scenePassTarget?.dispose();
 		this.scenePassTarget = null;
+		this.mirrorTarget?.dispose();
+		this.mirrorTarget = null;
 		super.free();
 	}
 	/** Swap geometry+material only when a surface-shaping prop changed. */
@@ -12310,6 +13654,10 @@ var Water3D = class Water3D extends Node3D {
 				uOpacity: { value: this.rp("opacity") },
 				uEnvironmentMap: { value: null },
 				uUseEnvironmentMap: { value: 0 },
+				uMirrorMap: { value: null },
+				uMirrorMatrix: { value: new Matrix4() },
+				uUseMirror: { value: 0 },
+				uMirrorDistort: { value: MIRROR_DISTORT },
 				uWavesAmplitude: { value: this.rp("waveHeight") * AMPLITUDE_PER_WAVE_HEIGHT },
 				uWavesSpeed: { value: FANCY_WAVE.speed },
 				uWavesFrequency: { value: FANCY_WAVE.frequency },
@@ -12352,6 +13700,7 @@ var Water3D = class Water3D extends Node3D {
 				uSwellAmplitude: { value: this.rp("swell") },
 				uSwellDir: { value: new Vector2(0, 1) },
 				uSwellWavelength: { value: this.rp("swellWavelength") },
+				uSwellSteepness: { value: this.rp("swellSteepness") },
 				uWhitecaps: { value: this.rp("whitecaps") },
 				uWaveEnvelope: { value: 0 },
 				uCausticsAbove: { value: this.rp("causticsAbove") },
@@ -12421,6 +13770,7 @@ var Water3D = class Water3D extends Node3D {
 		if (u.uAbsorption) u.uAbsorption.value = this.rp("absorption");
 		if (u.uSwellAmplitude) u.uSwellAmplitude.value = this.rp("swell");
 		if (u.uSwellWavelength) u.uSwellWavelength.value = this.rp("swellWavelength");
+		if (u.uSwellSteepness) u.uSwellSteepness.value = this.rp("swellSteepness");
 		if (u.uWhitecaps) u.uWhitecaps.value = this.rp("whitecaps");
 		if (u.uCausticsAbove) u.uCausticsAbove.value = this.rp("causticsAbove");
 		if (u.uShoreWaves) u.uShoreWaves.value = this.rp("shoreWaves");
@@ -12664,6 +14014,13 @@ const underwaterCamScratch = new Vector3();
 const UNDERWATER_MARGIN = 3;
 /** Keep-below clip plane for the scene pre-pass (constant set per render):
 * normal (0,−1,0) keeps y < constant — see the grab-clip note in _onRender3D. */
+const mirrorEyeScratch = new Vector3();
+const mirrorTargetScratch = new Vector3();
+const mirrorUpScratch = new Vector3();
+const mirrorQuatScratch = new Quaternion();
+/** Mirror pass: keep only what is ABOVE the waterline. */
+const mirrorClipPlane = new Plane(new Vector3(0, 1, 0), 0);
+const mirrorClipPlanes = [mirrorClipPlane];
 const grabClipPlane = new Plane(new Vector3(0, -1, 0), 0);
 const grabClipPlanes = [grabClipPlane];
 /** Keep-above twin for the depth-completion pass: normal (0,1,0) keeps
@@ -12695,6 +14052,7 @@ function registerNodes3D() {
 	registerNode(BoneAttachment3D);
 	registerNode(BoneLookAt3D);
 	registerNode(InstancedMesh3D);
+	registerNode(River3D);
 	registerNode(Terrain3D);
 	registerNode(Water3D);
 	registerNode(Foliage3D);
@@ -12710,4 +14068,4 @@ function registerNodes3D() {
 	registerNode(CharacterBody3D);
 }
 //#endregion
-export { Joint3D as A, keyboardIntensity as B, BoneLookAt3D as C, DEFAULT_TERRAIN_TEXTURE_BASE as D, Terrain3D as E, StaticBody3D as F, rigPose as H, Node3D as I, validateCollider3D as L, CharacterBody3D as M, PhysicsBody3D as N, TERRAIN_THEMES as O, RigidBody3D as P, QUARTER_PITCH as R, Camera3D as S, Billboard3D as T, movementState as V, DENSITY_PRESETS as _, VOXEL_PALETTE as a, FLOWER_VARIETIES as b, Trail3D as c, LoftMesh3D as d, DirectionalLight3D as f, Foliage3D as g, MeshInstance3D as h, WATER_MAX_RIPPLES as i, Area3D as j, terrainThemeLayers as k, Particles3D as l, InstancedMesh3D as m, Water3D as n, VoxelGrid3D as o, OmniLight3D as p, createCausticsQuad as r, Tree3D as s, registerNodes3D as t, ModelInstance3D as u, Flowers3D as v, BoneAttachment3D as w, CharacterController3D as x, resolveFlowerDensity as y, cameraRelative as z };
+export { TERRAIN_THEMES as A, QUARTER_PITCH as B, CharacterController3D as C, Billboard3D as D, BoneAttachment3D as E, PhysicsBody3D as F, keyboardIntensity as H, RigidBody3D as I, StaticBody3D as L, Joint3D as M, Area3D as N, Terrain3D as O, CharacterBody3D as P, Node3D as R, FLOWER_VARIETIES as S, BoneLookAt3D as T, movementState as U, cameraRelative as V, rigPose as W, MeshInstance3D as _, VoxelGrid3D as a, Flowers3D as b, River3D as c, Particles3D as d, ModelInstance3D as f, InstancedMesh3D as g, OmniLight3D as h, VOXEL_PALETTE as i, terrainThemeLayers as j, DEFAULT_TERRAIN_TEXTURE_BASE as k, traceDownhillPath as l, DirectionalLight3D as m, Water3D as n, Tree3D as o, LoftMesh3D as p, createCausticsQuad as r, Trail3D as s, registerNodes3D as t, WATER_MAX_RIPPLES as u, Foliage3D as v, Camera3D as w, resolveFlowerDensity as x, DENSITY_PRESETS as y, validateCollider3D as z };