incanto 0.75.0 → 0.77.0

package/dist/{environment-presets-BP77Dl0K.js → environment-presets-e_9YCnGu.js}

@@ -5,10 +5,10 @@ import { t as Rng } from "./rng-CDOMybym.js";
 import { c as getNodeSchema, h as didYouMean, p as registerNode } from "./touch-CioTZB-y.js";
 import { t as createNoise2D } from "./noise-D3nPpmFg.js";
 import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimations, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-SQa5gIu2.js";
-import { $ as Water3D, Q as tolerateUnknownAction, V as effectRng, at as PhysicsBody3D, ct as Node3D, ft as colliderFootDrop, ht as findHealth, it as CharacterBody3D, nt as rejectScale, ot as RigidBody3D, rt as Area3D, st as StaticBody3D, tt as WaterCutout3D } from "./gameplay-D-JuGura.js";
+import { $ as Water3D, Q as tolerateUnknownAction, V as effectRng, at as PhysicsBody3D, ct as Node3D, ft as colliderFootDrop, ht as buildSeaSpectrum, it as CharacterBody3D, mt as seaFftSupported, nt as rejectScale, ot as RigidBody3D, pt as SeaFft, rt as Area3D, st as StaticBody3D, tt as WaterCutout3D, vt as findHealth } from "./gameplay-Bfff_beb.js";
 import { t as checkSheetGrid } from "./sheet-grid-Cea343VO.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-BYgD5Edk.js";
-import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, ClampToEdgeWrapping, Color, ConeGeometry, CylinderGeometry, DataTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, Group, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LinearMipmapLinearFilter, LoopOnce, LoopRepeat, MathUtils, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NoColorSpace, NormalBlending, PerspectiveCamera, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, SphereGeometry, SpotLight, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector3, Vector4, VectorKeyframeTrack } from "three";
+import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, ClampToEdgeWrapping, Color, ConeGeometry, CubeCamera, CylinderGeometry, DataTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, Group, HalfFloatType, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LinearMipmapLinearFilter, LoopOnce, LoopRepeat, MathUtils, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NoColorSpace, NormalBlending, PerspectiveCamera, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, SphereGeometry, SpotLight, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector3, Vector4, VectorKeyframeTrack, WebGLCubeRenderTarget } from "three";
 import { clone } from "three/addons/utils/SkeletonUtils.js";
 //#region src/3d/textures.ts
 /**
@@ -2979,6 +2979,40 @@ const MOVEMENT_STATES = [
 	"sneak",
 	"dash"
 ];
+/**
+* What to play when the scene's `animations` map has no clip for a state.
+*
+* A missing entry used to leave whatever was playing BEFORE, which is never
+* what anyone meant: a character swimming across a bay in a frozen jump pose,
+* because `swim` was unmapped and the last state was `airborne`. Every state
+* added after the original five had this — `dash`, `climb`, `sneak`, `crouch`
+* — and no scene in the repo mapped any of them.
+*
+* Each chain ends at `idle`, so any map with one clip in it animates.
+*/
+const CLIP_FALLBACK = {
+	idle: [],
+	walk: ["idle"],
+	run: ["walk", "idle"],
+	fastRun: [
+		"run",
+		"walk",
+		"idle"
+	],
+	airborne: ["idle"],
+	swim: ["walk", "idle"],
+	climb: ["walk", "idle"],
+	crouch: ["idle"],
+	sneak: ["walk", "idle"],
+	dash: [
+		"fastRun",
+		"run",
+		"walk",
+		"idle"
+	]
+};
+/** How much of a swimmer's head rides clear of the water (m) — see `swimDepth`. */
+const HEAD_ABOVE_WATER = .15;
 /** Air control stands down this long after a wall kick, so the kick lands. */
 const WALL_LOCKOUT_SECONDS = .18;
 const ACC_DELTA_TIME = 8;
@@ -3082,10 +3116,20 @@ var CharacterController3D = class extends Node3D {
 		fallGravity: { default: 2.5 },
 		floatHeight: { default: .01 },
 		stepHeight: { default: .35 },
+		slopeLimitDeg: {
+			default: 55,
+			range: {
+				min: 0,
+				max: 90
+			}
+		},
 		/** Swimming pace (m/s) in water too deep to stand in; 0 = no swimming (the body sinks). */
 		swimSpeed: { default: 1.6 },
 		/** How far the body's origin rides BELOW the surface while swimming (m). */
-		swimDepth: { default: .35 },
+		swimDepth: {
+			default: null,
+			kinds: ["null", "number"]
+		},
 		/** Held: swim DOWN at `swimSpeed`. Absent from the input map = no diving. */
 		diveAction: { default: "dive" },
 		/** Ladder pace (m/s): push UP into an Area3D in `ladderGroup` and the body climbs it; 0 = no ladders. */
@@ -3246,8 +3290,18 @@ var CharacterController3D = class extends Node3D {
 	* is what a drowning pit wants and what every scene got before this.
 	*/
 	swimSpeed = 1.6;
-	/** Where the body's origin rides below the surface while swimming (m). */
-	swimDepth = .35;
+	/**
+	* How far the body's ORIGIN rides below the surface while swimming (m), or
+	* `null` (the default) to take it from the body: deep enough that the head
+	* rides 15 cm clear and the rest is in the water, which is what treading
+	* water looks like.
+	*
+	* The origin is the middle of the capsule, so a fixed number is only ever
+	* right for one character size. The 0.35 m this used to default to left the
+	* head of a standard 1.68 m rig 0.46 m clear of the surface — a person
+	* floating like a boat, chest and shoulders in the air.
+	*/
+	swimDepth = null;
 	/** Held: swim down at `swimSpeed`. Missing from the input map is fine. */
 	diveAction = "dive";
 	/**
@@ -3303,6 +3357,20 @@ var CharacterController3D = class extends Node3D {
 	* 200 kg character does not move a seesaw a 70 kg crate tips.
 	*/
 	stepHeight = .35;
+	/**
+	* The steepest ground this character STANDS on, in degrees (0-90).
+	*
+	* At or under it the ground is ground: the character holds its place with no
+	* slide at all, however long you leave it there. Over it the ground stops
+	* counting as ground — no hover spring, no `grounded`, no jump reset — and
+	* the body slips off the face, which is what a slope limit means in every
+	* engine that has one.
+	*
+	* 55° is a person. A mountain goat is 80; something on wheels is 25. `90`
+	* turns the limit off — which is what this controller did before it had one,
+	* and why it slid down a 7° hillside.
+	*/
+	slopeLimitDeg = 55;
 	mouseLook = true;
 	zoomMin = 0;
 	zoomMax = 0;
@@ -3499,6 +3567,10 @@ var CharacterController3D = class extends Node3D {
 	/** idle | walk | run | fastRun | airborne | swim — drive animations from this. */
 	state = "idle";
 	grounded = false;
+	/** Slope of the ground under the character, degrees — 0 when there is none. */
+	groundSlopeDeg = 0;
+	/** Its outward normal, or null. `[0, 1, 0]` is flat ground. */
+	groundNormal = null;
 	/** In water too deep to stand in — held at the surface by the swim spring. */
 	swimming = false;
 	/** The head is under the surface (diving, or a wave over it). */
@@ -3528,6 +3600,12 @@ var CharacterController3D = class extends Node3D {
 	jumping = false;
 	/** Seconds of air control still suppressed after a wall kick. */
 	wallLockout = 0;
+	/** What the anti-slide has learned it must keep paying to hold a slope. */
+	slideHold = 0;
+	/** Where the body stood last step, for the anti-slide's position error. */
+	slideFrom = null;
+	/** Seconds since the player last asked this character to move. */
+	stillFor = 0;
 	/** The outward normal of the wall being pressed into this step, if any. */
 	wallNormal = null;
 	get body() {
@@ -3572,6 +3650,8 @@ var CharacterController3D = class extends Node3D {
 		let toi = null;
 		/** What the probe landed on — the platform, when there is one. */
 		let ground = null;
+		/** …and which way its surface faces, for the slope limit and the spring. */
+		let normal = null;
 		for (const [ox, oz] of [
 			[0, 0],
 			[radius, 0],
@@ -3593,20 +3673,42 @@ var CharacterController3D = class extends Node3D {
 				if (toi === null || d < toi) {
 					toi = d;
 					ground = hit.node;
+					const n = hit.normal;
+					normal = n ? [
+						n[0] ?? 0,
+						n[1] ?? 1,
+						n[2] ?? 0
+					] : null;
 				}
 				if (ox === 0 && oz === 0) break;
 			}
 		}
-		this.grounded = toi !== null && toi < floatingDis * 2;
-		const carry = this.groundCarry(ground, dt);
-		const footed = toi !== null && toi < floatingDis * 1.3 && (vel[1] ?? 0) <= .5;
+		const upDot = normal ? Math.max(-1, Math.min(1, normal[1] ?? 1)) : 1;
+		const slopeDeg = toi === null ? 0 : Math.acos(Math.max(upDot, 0)) * 180 / Math.PI;
+		this.groundSlopeDeg = slopeDeg;
+		this.groundNormal = toi === null ? null : normal ?? [
+			0,
+			1,
+			0
+		];
+		const standable = slopeDeg <= this.slopeLimitDeg;
+		/** The spring's target: `floatHeight` of clearance PERPENDICULAR to the ground. */
+		const holdDis = floatingDis / Math.max(upDot, .35);
+		this.grounded = toi !== null && toi < holdDis * 2 && standable;
+		if (!this.grounded) {
+			this.slideHold = 0;
+			this.slideFrom = null;
+		}
+		const carry = this.groundCarry(standable ? ground : null, dt);
+		const footed = toi !== null && toi < holdDis * 1.3 && standable && (vel[1] ?? 0) <= .5;
 		const water = this.swimSpeed > 0 ? this.surfaceAt(pos[0], pos[2]) : null;
 		const surface = water === null ? null : water[0];
-		const waterline = surface === null ? null : surface - this.swimDepth;
+		const swimDepth = this.swimDepth ?? Math.max(halfHeight + radius - HEAD_ABOVE_WATER, .05);
+		const waterline = surface === null ? null : surface - swimDepth;
 		const standY = toi === null ? null : originY - toi + floatingDis + halfHeight;
 		const swimming = waterline !== null && surface !== null && surface > pos[1] - halfHeight && waterline !== null && (standY === null || waterline > standY) && !(this.jumping && (vel[1] ?? 0) > .5);
 		this.swimming = swimming;
-		this.submerged = surface !== null && surface > pos[1] + halfHeight;
+		this.submerged = surface !== null && surface > pos[1] + halfHeight + radius;
 		if (swimming) {
 			this.jumping = false;
 			this.rising = false;
@@ -3757,6 +3859,33 @@ var CharacterController3D = class extends Node3D {
 			0,
 			-(vel[2] - carry[1]) * DRAG_DAMPING * mass
 		]);
+		this.stillFor = moving ? 0 : this.stillFor + dt;
+		if (this.grounded && !swimming && !climbing && !onLadder && !this.jumping) {
+			const n = this.groundNormal;
+			const nx = n?.[0] ?? 0;
+			const nz = n?.[2] ?? 0;
+			const sinSlope = Math.hypot(nx, nz);
+			if (sinSlope > .001) {
+				const ux = nx / sinSlope;
+				const uz = nz / sinSlope;
+				const drift = (vel[0] - carry[0]) * ux + (vel[2] - carry[1]) * uz;
+				if (this.stillFor < .1) {
+					this.slideHold = 0;
+					this.slideFrom = null;
+				} else {
+					const from = this.slideFrom;
+					const moved = from === null ? 0 : (pos[0] - from[0]) * ux + (pos[2] - from[1]) * uz;
+					this.slideFrom = [pos[0], pos[2]];
+					this.slideHold = Math.max(-2, Math.min(2, this.slideHold + moved / dt * .5));
+					const hold = drift + this.slideHold;
+					if (hold !== 0) body.applyImpulse([
+						-hold * ux * mass,
+						0,
+						-hold * uz * mass
+					]);
+				}
+			}
+		}
 		let springToi = toi;
 		if (this.stepHeight > 0 && moving && toi !== null && !this.jumping && !swimming && !climbing && (vel[1] ?? 0) <= .5) {
 			const ahead = radius + .12;
@@ -3776,7 +3905,7 @@ var CharacterController3D = class extends Node3D {
 			}
 		}
 		if (springToi !== null && springToi < floatingDis * 2 && (!this.jumping || mantling) && !swimming && !climbing && !onLadder && (vel[1] ?? 0) < 2) {
-			const spring = SPRING_K * (floatingDis - springToi) - vel[1] * SPRING_DAMPING;
+			const spring = SPRING_K * (holdDis - springToi) - vel[1] * SPRING_DAMPING;
 			body.applyImpulse([
 				0,
 				spring * mass,
@@ -3889,7 +4018,7 @@ var CharacterController3D = class extends Node3D {
 			this.wallLockout = WALL_LOCKOUT_SECONDS;
 			this.emit("wallJumped", wall);
 		} else if (wantsJump && !onLadder && !(swimming && this.submerged) && (footed || swimming || this.coyoteLeft > 0 || this.jumpsUsed < this.maxJumps)) {
-			const hopVel = swimming ? Math.max(this.jumpVelocity, Math.sqrt(2 * this.sceneGravity() * (this.swimDepth + halfHeight + this.stepHeight + .05))) : 0;
+			const hopVel = swimming ? Math.max(this.jumpVelocity, Math.sqrt(2 * this.sceneGravity() * (this.effectiveSwimDepth() + halfHeight + this.stepHeight + .05))) : 0;
 			const jumpVel = swimming ? hopVel : this.jumpVelocity * (1 + (this.sprintJumpMultiplier - 1) * intensity);
 			if (swimming) this.swimHop = true;
 			body.linearVelocity = [
@@ -3954,7 +4083,14 @@ var CharacterController3D = class extends Node3D {
 		const next = dashing && !swimming ? "dash" : swimming ? "swim" : this.onLadder || climbing ? "climb" : this.crouching && !airborne ? moving ? "sneak" : "crouch" : movementState(!airborne, moving ? intensity : 0);
 		if (next !== this.state) {
 			this.state = next;
-			const clip = this.animations[next];
+			let clip = this.animations[next];
+			if (!clip) for (const alt of CLIP_FALLBACK[next]) {
+				const c = this.animations[alt];
+				if (c) {
+					clip = c;
+					break;
+				}
+			}
 			if (clip && this.skinPath !== "") {
 				const skin = this.getNodeOrNull(this.skinPath);
 				if (skin && "animation" in skin) skin.animation = clip;
@@ -4036,6 +4172,14 @@ var CharacterController3D = class extends Node3D {
 		const g = this.tree?.engine?.scene?.physics?.gravity;
 		return Math.abs(g?.[1] ?? STANDARD_G) || STANDARD_G;
 	}
+	/** `swimDepth`, or what it is derived to be for this body (see the prop). */
+	effectiveSwimDepth() {
+		if (this.swimDepth !== null) return this.swimDepth;
+		const body = this.parent;
+		const radius = body?.collider?.radius ?? .32;
+		const halfHeight = (body?.collider?.height ?? 1) / 2;
+		return Math.max(halfHeight + radius - HEAD_ABOVE_WATER, .05);
+	}
 	surfaceAt(x, z) {
 		if (this.waterScanIn <= 0) {
 			this.waters.length = 0;
@@ -10385,6 +10529,15 @@ uniform float uRippleStrength;
 uniform float uFlowRate;
 uniform float uSparkle;
 uniform float uFresnelScale;
+// the river's own sky cube (river-3d.ts): what the surface mirrors instead of
+// the painted three-colour gradient, which stays as the headless fallback
+uniform samplerCube uEnvironmentMap;
+uniform float uUseEnvironmentMap;
+// the live ripple layer (fft-gpu.ts), a 6 m patch in the ribbon's own frame
+uniform float uRippleOn;
+uniform sampler2D uRippleNormal;
+uniform float uRipplePatch;
+uniform float uRippleGain;
 /**
  * Rocks standing in the current: xz = centre, z = radius, w = how much of the
  * water they break (0 = drowned and quiet, 1 = the crest stands proud).
@@ -10427,6 +10580,32 @@ float riverStreak(vec2 p) {
   return riverNoise(q) * 0.5 + riverNoise(q * 3.3 + 7.3) * 0.5;
 }
 
+/** water-that-reads-as-water: the FINE wavelets — the two ripple octaves are
+ * a hand-span and up, so at the range a player actually stands from a creek
+ * the surface tilted in soft blobs and nothing on it could ever face the sun
+ * (the gel read). A third, much shorter field, differenced at its own step
+ * (the ripple's 0.35 step is wider than these wavelets), gives the normal the
+ * facets that glitter and that shatter the reflection; it fades out where a
+ * pixel would integrate it into speckle. Squeezed downstream like the rest. */
+// Karis' split-sum fit: what a ROUGH surface reflects at this angle — see the
+// sea-state fresnel note in shaders.ts. A river at a grazing view is a field
+// of wavelets, not a mirror, and the flat-Schlick sheet of sky it used to wear
+// is the plastic look this replaces.
+vec2 envBRDFApprox(float roughness, float NoV) {
+  const vec4 c0 = vec4(-1.0, -0.0275, -0.572, 0.022);
+  const vec4 c1 = vec4(1.0, 0.0425, 1.04, -0.04);
+  vec4 r = roughness * c0 + c1;
+  float a004 = min(r.x * r.x, exp2(-9.28 * NoV)) * r.x + r.y;
+  return vec2(-1.04, 1.04) * a004 + r.zw;
+}
+
+vec2 riverFineSlope(vec2 p) {
+  vec2 q = vec2(p.x * 10.7, p.y * 3.6) + 5.7;
+  const float e = 0.08;
+  float h = riverNoise(q);
+  return vec2(riverNoise(q + vec2(e, 0.0)) - h, riverNoise(q + vec2(0.0, e)) - h) / e;
+}
+
 void main() {
   float speed = vRiver.x;
   float column = vRiver.y;
@@ -10500,7 +10679,26 @@ void main() {
   // 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));
+  float camDist = length(cameraPosition - vWorldPosition);
+  float fineFade = (1.0 - smoothstep(6.0, 34.0, camDist)) * lively;
+  vec2 fine = vec2(0.0);
+  if (fineFade > 0.01) {
+    vec2 fineA = riverFineSlope(base - vec2(travel * pA, 0.0));
+    vec2 fineB = riverFineSlope(base - vec2(travel * pB, 0.0));
+    // under the ripple FFT the noise keeps only the sub-pixel flash
+    fine = mix(fineA, fineB, blend) *
+      (0.028 * fineFade * (0.5 + 0.5 * uSparkle) * (uRippleOn > 0.5 ? 0.45 : 1.0));
+  }
+  // the ripple FFT, carried downstream in the ribbon's metres with the same
+  // dual-phase crossfade the noise uses (a field scrolled at a speed that
+  // varies along the river smears; two half-period copies do not)
+  if (uRippleOn > 0.5) {
+    float travelM = speed / max(uFlowRate, 0.001);
+    vec2 rA = texture2D(uRippleNormal, (vFlowUv - vec2(travelM * pA, 0.0)) / uRipplePatch, -1.0).xy;
+    vec2 rB = texture2D(uRippleNormal, (vFlowUv - vec2(travelM * pB, 0.0)) / uRipplePatch, -1.0).xy;
+    fine += mix(rA, rB, blend) * (uRippleGain * lively);
+  }
+  vec2 slopeXY = clamp(ripple.yz * uRippleStrength * lively + fine, vec2(-0.5), vec2(0.5));
   vec3 normal = normalize(vSurfaceNormal - dir3 * slopeXY.x - perp3 * slopeXY.y);
 
   vec3 viewDir = normalize(cameraPosition - vWorldPosition);
@@ -10604,31 +10802,53 @@ void main() {
   // 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
-  );
+  if (uUseEnvironmentMap > 0.5) {
+    // the REAL sky, from the river's own cube — near-clipped, so the lowest
+    // rays (which meet the bank a few metres off) keep the bank tone
+    vec3 lifted = vec3(reflectDir.x, max(reflectDir.y, 0.06), reflectDir.z);
+    vec3 cube = min(textureCube(uEnvironmentMap, lifted).rgb, vec3(2.5));
+    sky = mix(uBankColor, cube, smoothstep(0.02, 0.2, reflectDir.y));
+  }
+  float rough = clamp(0.045 + 0.28 * smoothstep(8.0, 140.0, camDist), 0.04, 0.35);
+  float NoVf = clamp(dot(normal, viewDir), 0.0, 1.0);
+  float fresnel = uFresnelScale * (0.02 + 0.98 * pow(1.0 - NoVf, 5.0));
+  {
+    vec2 fRough = envBRDFApprox(rough, NoVf);
+    vec2 fSmooth = envBRDFApprox(0.02, NoVf);
+    fresnel *= clamp((0.02 * fRough.x + fRough.y) / max(0.02 * fSmooth.x + fSmooth.y, 1e-3), 0.0, 1.35);
+  }
+  fresnel = clamp(fresnel, 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 whisper of broad sheen so the
-  // river still READS as a moving surface from across the valley, where the
-  // sparkle is smaller than a pixel.
-  //
-  // The broad lobe is the dangerous one. At exponent 18 it stays near 1 across
-  // a huge stretch of a near-flat surface, and at 0.22 · 1.6 that is a third of
-  // full white ADDED to every one of those fragments — a sheet of white lying
-  // over the water that reads as fog and swallows the bed, the foam and the
-  // rocks alike. Narrow it and cut its weight; the sparkle carries the sun.
-  float spec = (pow(ndh, 160.0) + pow(ndh, 34.0) * 0.07) * 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;
+  // ── the sun as a microfacet highlight ──────────────────────────────────
+  // water-that-reads-as-water: the two Blinn-Phong lobes (160 + a whisper of
+  // 34) were a hand-shaped sheen gated by the ripple field, capped at 1.2 —
+  // a running creek under a 40°-high sun showed no sun at all. One GGX lobe
+  // over the wavelet normal: resolved facets near the eye flash (the glitter
+  // a riffle throws), and with distance the roughness grows so the same lobe
+  // widens into the soft sheen a river shows from across the valley. HDR by
+  // design — the sun's reflection is the brightest thing on the water and
+  // the bloom pass reads it. RIVER_SUN_RADIANCE scales the sun against the
+  // unit-ish sky gradient this shader mirrors.
+  const float RIVER_SUN_RADIANCE = 30.0;
+  float NoL = clamp(dot(normal, sunDir), 0.0, 1.0);
+  float NoV = max(dot(normal, viewDir), 1e-3);
+  float NoH = clamp(dot(normal, halfVec), 0.0, 1.0);
+  float LoH = clamp(dot(sunDir, halfVec), 0.0, 1.0);
+  float a2 = rough * rough;
+  float dD = NoH * NoH * (a2 - 1.0) + 1.0;
+  float D = a2 / (3.14159265 * dD * dD);
+  float gV = NoL * sqrt(NoV * NoV * (1.0 - a2) + a2);
+  float gL = NoV * sqrt(NoL * NoL * (1.0 - a2) + a2);
+  float Vis = 0.5 / max(gV + gL, 1e-4);
+  float Fh = 0.02 + 0.98 * pow(1.0 - LoH, 5.0);
+  float spec = D * Vis * Fh * NoL * RIVER_SUN_RADIANCE * uSunIntensity;
+  spec *= 0.5 + 0.5 * uSparkle; // the ripples dial still tunes how much sun the water throws
   spec *= 1.0 - foam * 0.85; // froth is rough — it kills the mirror
-  spec = min(spec, 1.2); // a highlight, never a white-out
+  // a facet under a pixel aliases into a lone flash: the roughness ramp
+  // widens the lobe out there, the cap catches the last isolated ones
+  spec = min(spec, mix(5.0, 1.2, smoothstep(30.0, 200.0, camDist)));
 
   fresnel *= 1.0 - 0.85 * fall; // froth scatters; it does not reflect
   vec3 color = mix(body, sky, fresnel);
@@ -10728,6 +10948,21 @@ const FOAM_COLOR = "#e9f2ef";
 /** Per-frame scratch (no allocation in the render path). */
 const rockCamScratch = new Vector3();
 /** Fixed look constants — the props stay intent-level, these carry the craft. */
+/** The river's own sky: a slow cube of the world beyond its banks (the sky,
+* the far hills), refreshed every couple of seconds — what the surface
+* mirrors instead of a painted three-colour gradient. Near-clipped so the
+* banks themselves, metres away, never smear across it. */
+const RIVER_SKY_RESOLUTION = 128;
+const RIVER_SKY_INTERVAL = 2e3;
+const RIVER_SKY_NEAR = 60;
+/** The live ripple layer (see Water3D): a 6 m spectrum patch advected with
+* the current in the ribbon's own frame. */
+const RIVER_RIPPLE_SIZE = 128;
+const RIVER_RIPPLE_PATCH = 6;
+const RIVER_RIPPLE_FETCH = 150;
+const RIVER_RIPPLE_SEED = 4242;
+/** Ripple rms slope per unit of `ripples`. */
+const RIVER_RIPPLE_SLOPE = .07;
 const LOOK = {
 	/** Pattern units per meter of flow space. */
 	rippleScale: .85,
@@ -10870,6 +11105,12 @@ var River3D = class River3D extends Node3D {
 		0
 	];
 	_bodies = [];
+	cubeTarget = null;
+	cubeCamera = null;
+	lastSkyAt = 0;
+	rippleFft = null;
+	rippleSpectrum = null;
+	fftUnsupported = false;
 	/** Loader hook: a malformed river fails at LOAD, not as an invisible ribbon. */
 	static validateJson(node) {
 		rejectScale(node, "the flow query and its collider both");
@@ -10936,8 +11177,68 @@ var River3D = class River3D extends Node3D {
 			this.rockScanAt = this.time;
 			this.scanRocks();
 		}
-		const u = this._ensureObject3D().material.uniforms;
+		const mesh = this._ensureObject3D();
+		const u = mesh.material.uniforms;
 		this.syncRocks(u, ctx.camera.getWorldPosition(rockCamScratch));
+		if (typeof ctx.gl?.extensions?.has === "function") {
+			this.syncSky(ctx, mesh, u);
+			this.syncRipple(ctx, u);
+		}
+	}
+	/** The sky cube: the world beyond the banks, from above the channel's middle. */
+	syncSky(ctx, mesh, u) {
+		if (!this.cubeTarget) {
+			this.cubeTarget = new WebGLCubeRenderTarget(RIVER_SKY_RESOLUTION, {
+				generateMipmaps: true,
+				minFilter: LinearMipmapLinearFilter,
+				type: HalfFloatType
+			});
+			this.cubeCamera = new CubeCamera(RIVER_SKY_NEAR, 4e3, this.cubeTarget);
+			this.lastSkyAt = 0;
+		}
+		const now = Date.now();
+		if (this.lastSkyAt === 0 || now - this.lastSkyAt >= RIVER_SKY_INTERVAL) {
+			this.lastSkyAt = now;
+			const b = this.ringBounds();
+			const [wx, wy, wz] = this.world;
+			const cam = this.cubeCamera;
+			cam.position.set(wx + (b.minX + b.maxX) / 2, wy + 3, wz + (b.minZ + b.maxZ) / 2);
+			const wasVisible = mesh.visible;
+			mesh.visible = false;
+			cam.update(ctx.gl, ctx.scene);
+			mesh.visible = wasVisible;
+		}
+		if (u.uEnvironmentMap) u.uEnvironmentMap.value = this.cubeTarget.texture;
+		if (u.uUseEnvironmentMap) u.uUseEnvironmentMap.value = 1;
+	}
+	/** The ripple FFT, advected by the fragment in the ribbon's own frame. */
+	syncRipple(ctx, u) {
+		if (this.fftUnsupported) return;
+		if (!this.rippleFft) {
+			if (!seaFftSupported(ctx.gl)) {
+				this.fftUnsupported = true;
+				return;
+			}
+			this.rippleFft = new SeaFft(RIVER_RIPPLE_SIZE, RIVER_RIPPLE_PATCH);
+			this.rippleSpectrum = buildSeaSpectrum({
+				size: RIVER_RIPPLE_SIZE,
+				patch: RIVER_RIPPLE_PATCH,
+				wind: 3,
+				windDirectionDeg: 90,
+				seed: RIVER_RIPPLE_SEED,
+				choppiness: .3,
+				fetch: RIVER_RIPPLE_FETCH,
+				modes: 0
+			});
+			this.rippleFft.setSpectrum(this.rippleSpectrum);
+		}
+		this.rippleFft.update(ctx.gl, this.time);
+		if (u.uRippleNormal) u.uRippleNormal.value = this.rippleFft.normal;
+		if (u.uRippleOn) u.uRippleOn.value = 1;
+		if (u.uRippleGain && this.rippleSpectrum) {
+			const rms = this.rippleSpectrum.rmsSlope;
+			u.uRippleGain.value = rms > 0 ? RIVER_RIPPLE_SLOPE * this.ripples / rms : 0;
+		}
 	}
 	/**
 	* @internal Water surface height over a world point, or null where this
@@ -11026,6 +11327,11 @@ var River3D = class River3D extends Node3D {
 		const mesh = this._ensureObject3D();
 		mesh.geometry?.dispose();
 		mesh.material?.dispose?.();
+		this.cubeTarget?.dispose();
+		this.cubeTarget = null;
+		this.cubeCamera = null;
+		this.rippleFft?.dispose();
+		this.rippleFft = null;
 		super.free();
 	}
 	widthProfile() {
@@ -11185,6 +11491,12 @@ var River3D = class River3D extends Node3D {
 				uRockCount: { value: 0 },
 				uRocks: { value: Array.from({ length: ROCK_SLOTS }, () => new Vector4()) },
 				uFresnelScale: { value: LOOK.fresnelScale },
+				uEnvironmentMap: { value: null },
+				uUseEnvironmentMap: { value: 0 },
+				uRippleOn: { value: 0 },
+				uRippleNormal: { value: null },
+				uRipplePatch: { value: RIVER_RIPPLE_PATCH },
+				uRippleGain: { value: 0 },
 				uStandingAmp: { value: LOOK.standingAmp },
 				uGlideAmp: { value: LOOK.glideAmp }
 			},