@driftengine/core 3.61.0

package/dist/render/shaders/tangentFrame.js

@@ -0,0 +1,70 @@
+/**
+ * Which way is along the texture, at a fragment.
+ *
+ * Two sources and a selection. The attribute frame is what `geometry/tangents.ts` generated,
+ * interpolated across the triangle and re-orthogonalised here; the derived frame is the standard
+ * cotangent construction from screen-space derivatives, for a mesh that never went through the
+ * generator — which is every mesh `meshBuilder` makes procedurally.
+ *
+ * **Both are computed and one is chosen, rather than one being computed under a branch.** The
+ * derivatives below are legal only under uniform control flow, and `hasTangents` arrives as a
+ * varying — flat, but a compiler cannot prove a varying uniform. The caller puts this inside its
+ * branch on `uNormalStrength`, which is a real uniform, and the selection here is a ternary rather
+ * than a branch. `main.ts` carries the same arrangement for `fwidth(vWorldPos)` and the long
+ * reason beside it; `AGENTS.md` 2026-08-07 is the rule, and WGSL refuses the module outright
+ * rather than leaving a derivative in non-uniform control flow undefined.
+ */
+export const TANGENT_FRAME_GLSL = `mat3 tangentFrame(vec3 n, vec3 worldPos, vec2 uv, vec4 tangent, int hasTangents) {
+  /*
+   * The derived frame: solve for the axis along u from how position and uv change together over
+   * the pixel. Exact where the surface is locally planar, approximate where it curves, which is
+   * the trade for working at all on geometry that carries no frame.
+   */
+  vec3 dp1 = dFdx(worldPos);
+  vec3 dp2 = dFdy(worldPos);
+  vec2 duv1 = dFdx(uv);
+  vec2 duv2 = dFdy(uv);
+  vec3 dp2perp = cross(dp2, n);
+  vec3 dp1perp = cross(n, dp1);
+  vec3 dt = dp2perp * duv1.x + dp1perp * duv2.x;
+  vec3 db = dp2perp * duv1.y + dp1perp * duv2.y;
+  /*
+   * **The determinant's sign, which magnitude-normalising throws away — and it is the difference
+   * between the two backends.**
+   *
+   * dFdy measures along *upward* window y in GLSL and along *downward* framebuffer y in WGSL, so
+   * dp2 and duv2 both arrive negated on WebGPU. The system this solves is invariant under that —
+   * both sides of its second equation flip — but the closed form above is not: dt and db each come
+   * out negated, and dividing by their *length* keeps the negation instead of cancelling it. The
+   * frame then points the other way on one backend, which reads as a surface lit from the wrong
+   * side and nothing else.
+   *
+   * The UV determinant flips with them, so folding its sign back in restores the invariance the
+   * solve always had. Measured before and after on demo/dev/normal.html: the derived panel stood
+   * 86 of 255 rms from the attribute panel on WebGPU and 8.8 on WebGL2; with this they agree.
+   */
+  float det = duv1.x * duv2.y - duv2.x * duv1.y;
+  float handed = det < 0.0 ? -1.0 : 1.0;
+  /* One scale for both axes, so a stretched UV layout does not shear the frame it produces. */
+  float invmax = inversesqrt(max(max(dot(dt, dt), dot(db, db)), 1e-12)) * handed;
+  vec3 derivedT = dt * invmax;
+  vec3 derivedB = db * invmax;
+
+  /*
+   * The attribute frame, re-orthogonalised. Interpolating a tangent across a triangle leaves it
+   * no longer square to the interpolated normal, and Gram-Schmidt is what puts it back —
+   * generateTangents does the same per vertex and says why: dropping it is a normal map that
+   * shears wherever the geometry curves.
+   */
+  vec3 attrT = normalize(tangent.xyz - n * dot(n, tangent.xyz));
+  /*
+   * The bitangent's sign, which is the whole reason w is stored. An artist mapping the left and
+   * right of a model onto one patch of texture gives one side a mirrored frame, and a bitangent
+   * computed without the sign lights that side inside out.
+   */
+  vec3 attrB = cross(n, attrT) * tangent.w;
+
+  vec3 t = hasTangents != 0 ? attrT : derivedT;
+  vec3 b = hasTangents != 0 ? attrB : derivedB;
+  return mat3(t, b, n);
+}`;

package/dist/render/shaders/temporalResolve.d.ts

@@ -0,0 +1 @@
+export declare const TEMPORAL_RESOLVE_FRAG: string;

package/dist/render/shaders/temporalResolve.js

@@ -0,0 +1,150 @@
+/**
+ * The temporal resolve: this frame blended into where the last one was.
+ *
+ * **Antialiasing by moving the camera instead of by multiplying the fill rate.** The projection is
+ * shifted a fraction of a pixel each frame, so an edge that fell one side of a pixel centre falls
+ * the other side next frame; blending the two puts the edge where it actually is. What MSAA buys
+ * inside a frame this buys across frames, for one extra texture and one extra fullscreen pass —
+ * which is the trade a browser target wants, where MSAA on a float target is not free and on
+ * WebGL2 is not always available at all.
+ *
+ * **The motion is the camera's, and that is a stated limit rather than an oversight.** The
+ * reprojection matrix carries a pixel back through the previous view, which is exact for a static
+ * world under a moving camera and wrong for a moving object under a still one. A velocity buffer
+ * would fix the second, and it means a second colour attachment on the scene pass and every draw
+ * path writing into it — the README carries that as its own gap. What stands in for it here is the
+ * neighbourhood clip below, which rejects a history that no longer resembles what is around it;
+ * that covers a moving object crossing a background of a different colour, and does not cover one
+ * crossing a background of its own.
+ *
+ * The vertex stage is `FULLSCREEN_VERT`, shared with the occlusion pass, its blur and the rush.
+ */
+import { glslSceneDepthToNdc } from '../depthConvention.js';
+export const TEMPORAL_RESOLVE_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+/** This frame, rasterised with the projection jittered by \`jitterOffset\`. */
+uniform sampler2D uScene;
+/** What this pass wrote last frame: resolved, and conceptually unjittered. */
+uniform sampler2D uHistory;
+/**
+ * The frame's depth.
+ *
+ * **highp, and it is not decoration.** GLSL ES gives a fragment shader's samplers a default
+ * precision of *lowp* whatever \`precision highp float\` says at the top of the file — that line
+ * sets the default for float and not for a sampler. A lowp sampler may hand back eight bits, and
+ * a depth buffer read at eight bits reprojects to visibly the wrong place. \`rush.ts\` carries the
+ * same note for the same reason.
+ */
+uniform highp sampler2D uDepth;
+/**
+ * The previous view-projection times the inverse of this frame's, so one multiply carries a point
+ * from this frame's clip space to the last one's.
+ *
+ * **Built from the unjittered matrices**, which is why the jitter is applied to a copy used only
+ * for rasterising and never to the \`viewProj\` the renderer keeps. The history holds a resolved
+ * picture that stands for the unjittered scene, so reprojecting into it through a jittered matrix
+ * would look the sample up half a pixel from where it is and undo the accumulation it is trying to
+ * build. Camera motion blur reads this same matrix and has a test on it.
+ */
+uniform mat4 uReprojection;
+/** One texel of the target, for walking the neighbourhood. */
+uniform vec2 uTexel;
+/**
+ * How much of the clipped history to keep, 0 to 1.
+ *
+ * **Zero is the whole switch.** The first frame, the frame after a resize and the frame after a
+ * cut have nothing to sample, and they pass this as zero; so does a renderer with the effect off.
+ * The branch on it is the first thing in \`main\`, so an untouched frame costs one compare and the
+ * pass is not run at all when the effect is off.
+ */
+uniform float uHistoryBlend;
+
+out vec4 fragColor;
+
+/**
+ * The colours actually present around this pixel this frame, as a box.
+ *
+ * Nine taps rather than five: the diagonals are what catch a thin edge running corner to corner,
+ * which is exactly the geometry temporal antialiasing exists for, and a cross-shaped
+ * neighbourhood lets a history through along it.
+ *
+ * **Every fetch is an explicit level.** An implicit derivative under a branch that is not provably
+ * uniform fails to compile in WGSL, which invalidates the pipeline and the command buffer while
+ * the frame still presents — a failure this repository has paid for more than once, and the reason
+ * \`film.ts\` carries the same note.
+ */
+void neighbourhood(out vec3 lo, out vec3 hi) {
+  lo = vec3(1e9);
+  hi = vec3(-1e9);
+  for (int y = -1; y <= 1; y++) {
+    for (int x = -1; x <= 1; x++) {
+      vec3 c = textureLod(uScene, vUv + vec2(float(x), float(y)) * uTexel, 0.0).rgb;
+      lo = min(lo, c);
+      hi = max(hi, c);
+    }
+  }
+}
+
+/**
+ * \`history\` pulled into the box, along the line towards its centre.
+ *
+ * Clipped towards the centre rather than clamped per channel: a clamp moves each channel on its
+ * own, so a history merely brighter than its surroundings lands on a corner of the box and comes
+ * back a different hue, which reads as coloured fringing along every moving edge. Shortening the
+ * whole offset by one ratio keeps the direction and changes only the length.
+ *
+ * The same arithmetic is \`clipToNeighbourhood\` in \`temporalAa.ts\`, which is where it is asserted
+ * against numbers; the test beside this file asserts the shader still spells it this way.
+ */
+vec3 clipToNeighbourhood(vec3 history, vec3 lo, vec3 hi) {
+  vec3 centre = (lo + hi) * 0.5;
+  vec3 extent = (hi - lo) * 0.5;
+  vec3 offset = history - centre;
+  /* A channel with no extent cannot bound anything; the max below then answers for the others. */
+  vec3 ratios = abs(offset) / max(extent, vec3(1e-7));
+  float ratio = max(ratios.x, max(ratios.y, ratios.z));
+  if (ratio <= 1.0) return history;
+  return centre + offset / ratio;
+}
+
+void main() {
+  vec3 current = textureLod(uScene, vUv, 0.0).rgb;
+
+  /* Nothing to blend towards: the first frame, a resize, a cut, or the effect switched off. */
+  if (uHistoryBlend <= 0.0) {
+    fragColor = vec4(current, 1.0);
+    return;
+  }
+
+  float depth = textureLod(uDepth, vUv, 0.0).r;
+  vec4 clip = vec4(vUv * 2.0 - 1.0, ${glslSceneDepthToNdc('depth')}, 1.0);
+  vec4 previous = uReprojection * clip;
+  /* Behind the previous eye: there is no last-frame position to sample. */
+  if (previous.w <= 0.0) {
+    fragColor = vec4(current, 1.0);
+    return;
+  }
+
+  vec2 wasUv = (previous.xy / previous.w) * 0.5 + 0.5;
+  /*
+   * **Off the edge of the last frame is a disocclusion**, and the honest answer is this frame's
+   * colour rather than a clamped sample of the border, which would drag one row of pixels inward
+   * as a smear for as long as the camera kept turning.
+   */
+  if (wasUv.x < 0.0 || wasUv.x > 1.0 || wasUv.y < 0.0 || wasUv.y > 1.0) {
+    fragColor = vec4(current, 1.0);
+    return;
+  }
+
+  vec3 lo;
+  vec3 hi;
+  neighbourhood(lo, hi);
+  vec3 history = textureLod(uHistory, wasUv, 0.0).rgb;
+  vec3 bounded = clipToNeighbourhood(history, lo, hi);
+
+  fragColor = vec4(mix(current, bounded, uHistoryBlend), 1.0);
+}
+`;

package/dist/render/shaders/text.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Screen-space 3D text.
+ *
+ * Every lit cell of every glyph is one instanced cube. That sounds extravagant
+ * and is not: a fifteen-character message is a few hundred boxes, one draw
+ * call, and it buys real geometry — text that catches light, casts its own
+ * shading, and can rotate in depth. Drawing it as a textured quad would put a
+ * flat sticker over a flat-shaded world, which is exactly the "HTML on top"
+ * look this exists to get rid of.
+ *
+ * The projection is built here rather than taken from the scene camera. Text is
+ * laid out in pixels and must land where the UI says it lands, whatever the
+ * gameplay camera is doing — but it still wants perspective, or a rotating
+ * letter shears instead of turning.
+ */
+export declare const TEXT_VERT = "#version 300 es\nprecision highp float;\n\nlayout(location = 0) in vec3 aCorner;\nlayout(location = 1) in vec3 aNormal;\n/** Cell position in pixels, relative to the string's origin. */\nlayout(location = 2) in vec2 aCell;\n/** Which character this cell belongs to, for staggered animation. */\nlayout(location = 3) in float aCharIndex;\n\nuniform vec2 uViewport;\n/** Where the string's baseline-left sits, in pixels from the top left. */\nuniform vec2 uOrigin;\nuniform float uCellSize;\n/** Distance from the virtual camera; larger flattens the perspective. */\nuniform float uDepth;\n\n/** 0 before a character has arrived, 1 once it has settled. */\nuniform float uReveal;\n/** How many characters the stagger spans \u2014 the whole line, not this piece. */\nuniform float uCharCount;\n/**\n * Where this piece starts within that line.\n *\n * A line drawn in several pieces \u2014 words around a keycap \u2014 must stagger as one\n * sentence. Without this each piece restarts at zero, so the second word begins\n * arriving before the first has finished and they sit at different heights\n * through the whole animation.\n */\nuniform float uCharOffset;\n/** Radians of entry rotation, decaying to zero as a character settles. */\nuniform float uSpin;\n/** Extra scale at the moment of arrival \u2014 the overshoot. */\nuniform float uPunch;\n/** Vertical bob amplitude in pixels, and its phase. */\nuniform float uBob;\nuniform float uTime;\n/**\n * Clip space, as the backend drawing this defines it. Identity on WebGL2.\n *\n * This draw builds its own clip position from pixels and never multiplies by a camera, so\n * the correction every other draw carries in its view-projection cannot reach it \u2014 the same\n * gap that left the sky unprojecting through the wrong space. Two things are wrong without\n * it on WebGPU, and only one of them is visible: the generated vertex shader negates Y, so\n * the message renders upside down; and z here is a narrow slice about zero, which is inside\n * OpenGL's [-1, 1] and *outside* WebGPU's [0, 1], so half of every glyph is clipped away.\n */\nuniform mat4 uClipCorrection;\n\nout vec3 vNormal;\nout float vDepth;\nout float vChar;\n\n/**\n * Spring settle: overshoots once and comes back.\n *\n * A character that eases into place reads as an element appearing; one that\n * overshoots and settles reads as an object arriving. That difference is most\n * of what makes text feel like part of a game rather than part of a page.\n */\nfloat settle(float t) {\n  if (t <= 0.0) return 0.0;\n  if (t >= 1.0) return 1.0;\n  float d = 1.0 - t;\n  return 1.0 - d * d * cos(t * 12.0) ;\n}\n\nmat2 rot(float a) {\n  float s = sin(a);\n  float c = cos(a);\n  return mat2(c, -s, s, c);\n}\n\nvoid main() {\n  // Stagger: each character starts a fraction of the reveal later than the\n  // one before it, so the message assembles left to right.\n  float span = max(uCharCount, 1.0);\n  float start = ((aCharIndex + uCharOffset) / span) * 0.55;\n  float local = clamp((uReveal - start) / max(0.45, 1.0 - start), 0.0, 1.0);\n  float eased = settle(local);\n\n  // Arrives spinning about its own horizontal axis and dropping into place.\n  float spin = uSpin * (1.0 - eased);\n  float rise = (1.0 - eased) * uCellSize * 6.0;\n  float punch = 1.0 + uPunch * (1.0 - abs(eased * 2.0 - 1.0));\n\n  vec3 local3 = aCorner * uCellSize * 0.5 * punch;\n  local3.yz = rot(spin) * local3.yz;\n\n  vec2 cell = aCell * uCellSize;\n  float bob = sin(uTime * 3.1 + aCharIndex * 0.7) * uBob;\n\n  // Pixels, y down from the top-left corner of the viewport.\n  vec2 screen = uOrigin + vec2(cell.x, -cell.y) + vec2(0.0, rise - bob);\n  vec3 view = vec3(screen + local3.xy, -uDepth + local3.z);\n\n  // A hand-built perspective divide. The near plane is the viewport itself, so\n  // a cell at depth uDepth is exactly its pixel size on screen.\n  float invDepth = uDepth / max(0.001, -view.z);\n  vec2 ndc = ((view.xy * invDepth) / uViewport) * 2.0 - 1.0;\n  // Depth from the cube's own extrusion, mapped into a narrow slice of the\n  // range so a message sorts against itself without ever reaching the scene.\n  float depth = clamp(-local3.z / max(1.0, uCellSize * 2.0), -1.0, 1.0) * 0.4;\n  gl_Position = uClipCorrection * vec4(ndc.x, -ndc.y, depth, 1.0);\n\n  vec3 n = aNormal;\n  n.yz = rot(spin) * n.yz;\n  vNormal = n;\n  vDepth = local3.z;\n  vChar = eased;\n}";
+export declare const TEXT_FRAG = "#version 300 es\nprecision highp float;\n\nin vec3 vNormal;\nin float vDepth;\nin float vChar;\n\nuniform vec3 uColor;\n/** Self-illumination on top of the shaded colour. */\nuniform float uGlow;\nuniform float uAlpha;\n\nout vec4 fragColor;\n\nvoid main() {\n  /*\n   * A fixed key light rather than the world's. Text has to stay legible at\n   * midnight and at noon, and lighting it with the scene would make a\n   * notification unreadable on exactly the night runs where it matters most.\n   * The light only exists to give the cubes an edge.\n   */\n  vec3 key = normalize(vec3(-0.35, 0.7, 0.6));\n  float lambert = 0.55 + 0.45 * max(dot(normalize(vNormal), key), 0.0);\n\n  vec3 lit = uColor * lambert;\n  // The glow rides the arrival: brightest as a character lands, settling after.\n  vec3 emissive = uColor * uGlow * (0.45 + 0.55 * vChar);\n  fragColor = vec4(lit + emissive, uAlpha);\n}";

package/dist/render/shaders/text.js

@@ -0,0 +1,155 @@
+/**
+ * Screen-space 3D text.
+ *
+ * Every lit cell of every glyph is one instanced cube. That sounds extravagant
+ * and is not: a fifteen-character message is a few hundred boxes, one draw
+ * call, and it buys real geometry — text that catches light, casts its own
+ * shading, and can rotate in depth. Drawing it as a textured quad would put a
+ * flat sticker over a flat-shaded world, which is exactly the "HTML on top"
+ * look this exists to get rid of.
+ *
+ * The projection is built here rather than taken from the scene camera. Text is
+ * laid out in pixels and must land where the UI says it lands, whatever the
+ * gameplay camera is doing — but it still wants perspective, or a rotating
+ * letter shears instead of turning.
+ */
+export const TEXT_VERT = `#version 300 es
+precision highp float;
+
+layout(location = 0) in vec3 aCorner;
+layout(location = 1) in vec3 aNormal;
+/** Cell position in pixels, relative to the string's origin. */
+layout(location = 2) in vec2 aCell;
+/** Which character this cell belongs to, for staggered animation. */
+layout(location = 3) in float aCharIndex;
+
+uniform vec2 uViewport;
+/** Where the string's baseline-left sits, in pixels from the top left. */
+uniform vec2 uOrigin;
+uniform float uCellSize;
+/** Distance from the virtual camera; larger flattens the perspective. */
+uniform float uDepth;
+
+/** 0 before a character has arrived, 1 once it has settled. */
+uniform float uReveal;
+/** How many characters the stagger spans — the whole line, not this piece. */
+uniform float uCharCount;
+/**
+ * Where this piece starts within that line.
+ *
+ * A line drawn in several pieces — words around a keycap — must stagger as one
+ * sentence. Without this each piece restarts at zero, so the second word begins
+ * arriving before the first has finished and they sit at different heights
+ * through the whole animation.
+ */
+uniform float uCharOffset;
+/** Radians of entry rotation, decaying to zero as a character settles. */
+uniform float uSpin;
+/** Extra scale at the moment of arrival — the overshoot. */
+uniform float uPunch;
+/** Vertical bob amplitude in pixels, and its phase. */
+uniform float uBob;
+uniform float uTime;
+/**
+ * Clip space, as the backend drawing this defines it. Identity on WebGL2.
+ *
+ * This draw builds its own clip position from pixels and never multiplies by a camera, so
+ * the correction every other draw carries in its view-projection cannot reach it — the same
+ * gap that left the sky unprojecting through the wrong space. Two things are wrong without
+ * it on WebGPU, and only one of them is visible: the generated vertex shader negates Y, so
+ * the message renders upside down; and z here is a narrow slice about zero, which is inside
+ * OpenGL's [-1, 1] and *outside* WebGPU's [0, 1], so half of every glyph is clipped away.
+ */
+uniform mat4 uClipCorrection;
+
+out vec3 vNormal;
+out float vDepth;
+out float vChar;
+
+/**
+ * Spring settle: overshoots once and comes back.
+ *
+ * A character that eases into place reads as an element appearing; one that
+ * overshoots and settles reads as an object arriving. That difference is most
+ * of what makes text feel like part of a game rather than part of a page.
+ */
+float settle(float t) {
+  if (t <= 0.0) return 0.0;
+  if (t >= 1.0) return 1.0;
+  float d = 1.0 - t;
+  return 1.0 - d * d * cos(t * 12.0) ;
+}
+
+mat2 rot(float a) {
+  float s = sin(a);
+  float c = cos(a);
+  return mat2(c, -s, s, c);
+}
+
+void main() {
+  // Stagger: each character starts a fraction of the reveal later than the
+  // one before it, so the message assembles left to right.
+  float span = max(uCharCount, 1.0);
+  float start = ((aCharIndex + uCharOffset) / span) * 0.55;
+  float local = clamp((uReveal - start) / max(0.45, 1.0 - start), 0.0, 1.0);
+  float eased = settle(local);
+
+  // Arrives spinning about its own horizontal axis and dropping into place.
+  float spin = uSpin * (1.0 - eased);
+  float rise = (1.0 - eased) * uCellSize * 6.0;
+  float punch = 1.0 + uPunch * (1.0 - abs(eased * 2.0 - 1.0));
+
+  vec3 local3 = aCorner * uCellSize * 0.5 * punch;
+  local3.yz = rot(spin) * local3.yz;
+
+  vec2 cell = aCell * uCellSize;
+  float bob = sin(uTime * 3.1 + aCharIndex * 0.7) * uBob;
+
+  // Pixels, y down from the top-left corner of the viewport.
+  vec2 screen = uOrigin + vec2(cell.x, -cell.y) + vec2(0.0, rise - bob);
+  vec3 view = vec3(screen + local3.xy, -uDepth + local3.z);
+
+  // A hand-built perspective divide. The near plane is the viewport itself, so
+  // a cell at depth uDepth is exactly its pixel size on screen.
+  float invDepth = uDepth / max(0.001, -view.z);
+  vec2 ndc = ((view.xy * invDepth) / uViewport) * 2.0 - 1.0;
+  // Depth from the cube's own extrusion, mapped into a narrow slice of the
+  // range so a message sorts against itself without ever reaching the scene.
+  float depth = clamp(-local3.z / max(1.0, uCellSize * 2.0), -1.0, 1.0) * 0.4;
+  gl_Position = uClipCorrection * vec4(ndc.x, -ndc.y, depth, 1.0);
+
+  vec3 n = aNormal;
+  n.yz = rot(spin) * n.yz;
+  vNormal = n;
+  vDepth = local3.z;
+  vChar = eased;
+}`;
+export const TEXT_FRAG = `#version 300 es
+precision highp float;
+
+in vec3 vNormal;
+in float vDepth;
+in float vChar;
+
+uniform vec3 uColor;
+/** Self-illumination on top of the shaded colour. */
+uniform float uGlow;
+uniform float uAlpha;
+
+out vec4 fragColor;
+
+void main() {
+  /*
+   * A fixed key light rather than the world's. Text has to stay legible at
+   * midnight and at noon, and lighting it with the scene would make a
+   * notification unreadable on exactly the night runs where it matters most.
+   * The light only exists to give the cubes an edge.
+   */
+  vec3 key = normalize(vec3(-0.35, 0.7, 0.6));
+  float lambert = 0.55 + 0.45 * max(dot(normalize(vNormal), key), 0.0);
+
+  vec3 lit = uColor * lambert;
+  // The glow rides the arrival: brightest as a character lands, settling after.
+  vec3 emissive = uColor * uGlow * (0.45 + 0.55 * vChar);
+  fragColor = vec4(lit + emissive, uAlpha);
+}`;

package/dist/render/shaders/vertexChannel.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The per-vertex channel's declaration and its wind displacement, authored once for two programs.
+ *
+ * **Shared source rather than two copies, for the reason `scatter.ts` gives about its own.** The
+ * colour pass and the depth pass have to agree *exactly*: a canopy that bends in one and stands
+ * still in the other slides its whole shade off the ground it belongs to, and the drift follows
+ * the gust, so it never reads as a constant offset anybody could find by looking. One expression,
+ * two callers.
+ *
+ * The lanes are `MeshData.channel`: `.x` sway, `.y` skyDirect, `.z` alpha, `.w` reserved. Only
+ * `.x` is read here; the other two are varyings the fragment stage consumes.
+ */
+/**
+ * The attribute, and the wind the bend below reads.
+ *
+ * Declared unconditionally in every vertex variant. **No lane is a permutation**: the fragment
+ * stage already carries sixteen of those at 282.2 KB gzipped, where the whole vertex stage is
+ * 4.1 KB across five, so a `#if` here would buy nothing measurable and cost a variant axis.
+ */
+export declare const CHANNEL_ATTRIBUTE = "\nlayout(location = 13) in vec4 aChannel;\n\n/*\n * The frame's wind, already converted by `resolveScatterDeform` \u2014 a normalised direction, metres\n * of bend, a gust amplitude and a scaled clock.\n *\n * **The same numbers the scatter batch reads, and that is the rule rather than an economy.** A\n * second conversion here would be a second wind however identical its inputs, and the failure is\n * not localised: it shows up as a scene that does not cohere, a canopy leaning one way while the\n * grass beneath it leans another, with no single element looking wrong. See \"One wind, sampled\n * once\" in AGENTS.md.\n */\nuniform vec2 uWindDirection;\nuniform float uWindSpeed;\nuniform float uWindGust;\nuniform float uWindTime;\n/* Spatial frequency of the travelling gust, per metre. */\nuniform vec2 uWindSpatialPhase;\n";
+/**
+ * Where the wind puts a vertex, given how much of it that vertex takes.
+ *
+ * Phase comes from world position, so neighbouring geometry is never in lockstep and a gust
+ * visibly travels across a canopy instead of the whole canopy pulsing at once. That is the scatter
+ * shader's reasoning and it transfers without change.
+ *
+ * **The lane scales the bend once, where `scatter.ts` squares its own falloff.** That file derives
+ * its falloff from height, and a linear response there slides a whole plant sideways and reads as
+ * the ground moving, so it squares to keep the base planted. Here the falloff is *authored* — 0 on
+ * a trunk, 1 at a leaf tip — and squaring it would silently overrule a curve somebody had already
+ * shaped. What that costs is that a lane filled linearly up a trunk gives a tree that slides at
+ * its base; the fix is the curve the author meant, not a square in the shader.
+ *
+ * The early return is not an optimisation. Geometry that never said it bends must reach exactly
+ * the position it reached before this existed, and `sin` of a phase multiplied by zero is not
+ * bit-identical to not moving at all.
+ */
+export declare const CHANNEL_BEND = "\nvec3 channelBend(vec3 worldPos, float sway) {\n  if (sway <= 0.0) return worldPos;\n  float phase = dot(worldPos.xz, uWindSpatialPhase) + uWindTime;\n  float bend = (uWindSpeed + uWindGust) * sin(phase) * sway;\n  return vec3(\n    worldPos.x + uWindDirection.x * bend,\n    worldPos.y,\n    worldPos.z + uWindDirection.y * bend\n  );\n}\n";

package/dist/render/shaders/vertexChannel.js

@@ -0,0 +1,69 @@
+/**
+ * The per-vertex channel's declaration and its wind displacement, authored once for two programs.
+ *
+ * **Shared source rather than two copies, for the reason `scatter.ts` gives about its own.** The
+ * colour pass and the depth pass have to agree *exactly*: a canopy that bends in one and stands
+ * still in the other slides its whole shade off the ground it belongs to, and the drift follows
+ * the gust, so it never reads as a constant offset anybody could find by looking. One expression,
+ * two callers.
+ *
+ * The lanes are `MeshData.channel`: `.x` sway, `.y` skyDirect, `.z` alpha, `.w` reserved. Only
+ * `.x` is read here; the other two are varyings the fragment stage consumes.
+ */
+/**
+ * The attribute, and the wind the bend below reads.
+ *
+ * Declared unconditionally in every vertex variant. **No lane is a permutation**: the fragment
+ * stage already carries sixteen of those at 282.2 KB gzipped, where the whole vertex stage is
+ * 4.1 KB across five, so a `#if` here would buy nothing measurable and cost a variant axis.
+ */
+export const CHANNEL_ATTRIBUTE = `
+layout(location = 13) in vec4 aChannel;
+
+/*
+ * The frame's wind, already converted by \`resolveScatterDeform\` — a normalised direction, metres
+ * of bend, a gust amplitude and a scaled clock.
+ *
+ * **The same numbers the scatter batch reads, and that is the rule rather than an economy.** A
+ * second conversion here would be a second wind however identical its inputs, and the failure is
+ * not localised: it shows up as a scene that does not cohere, a canopy leaning one way while the
+ * grass beneath it leans another, with no single element looking wrong. See "One wind, sampled
+ * once" in AGENTS.md.
+ */
+uniform vec2 uWindDirection;
+uniform float uWindSpeed;
+uniform float uWindGust;
+uniform float uWindTime;
+/* Spatial frequency of the travelling gust, per metre. */
+uniform vec2 uWindSpatialPhase;
+`;
+/**
+ * Where the wind puts a vertex, given how much of it that vertex takes.
+ *
+ * Phase comes from world position, so neighbouring geometry is never in lockstep and a gust
+ * visibly travels across a canopy instead of the whole canopy pulsing at once. That is the scatter
+ * shader's reasoning and it transfers without change.
+ *
+ * **The lane scales the bend once, where `scatter.ts` squares its own falloff.** That file derives
+ * its falloff from height, and a linear response there slides a whole plant sideways and reads as
+ * the ground moving, so it squares to keep the base planted. Here the falloff is *authored* — 0 on
+ * a trunk, 1 at a leaf tip — and squaring it would silently overrule a curve somebody had already
+ * shaped. What that costs is that a lane filled linearly up a trunk gives a tree that slides at
+ * its base; the fix is the curve the author meant, not a square in the shader.
+ *
+ * The early return is not an optimisation. Geometry that never said it bends must reach exactly
+ * the position it reached before this existed, and `sin` of a phase multiplied by zero is not
+ * bit-identical to not moving at all.
+ */
+export const CHANNEL_BEND = `
+vec3 channelBend(vec3 worldPos, float sway) {
+  if (sway <= 0.0) return worldPos;
+  float phase = dot(worldPos.xz, uWindSpatialPhase) + uWindTime;
+  float bend = (uWindSpeed + uWindGust) * sin(phase) * sway;
+  return vec3(
+    worldPos.x + uWindDirection.x * bend,
+    worldPos.y,
+    worldPos.z + uWindDirection.y * bend
+  );
+}
+`;

package/dist/render/shaders/water.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The sky-ocean, as an actual wave simulation rather than a tinted plane.
+ *
+ * Four summed Gerstner waves: unlike a sine heightfield, Gerstner displaces
+ * vertices *horizontally* toward crests as well as vertically, which is what
+ * produces sharp peaks and broad troughs instead of a rolling blanket. Normals
+ * come analytically from the same sum, so lighting matches the geometry exactly
+ * and needs no derivative tricks.
+ *
+ * The wave field itself lives in `gerstner.ts` because it is shared: the caustics
+ * in `caustics.ts` are the light *this* surface throws onto what covers it, and
+ * they must be the same water, not a lookalike animated separately.
+ *
+ * The grid follows the camera and is snapped to whole cells, giving an endless
+ * ocean from a fixed vertex budget without the surface sliding underfoot.
+ */
+export declare const WATER_VERT = "#version 300 es\nlayout(location = 0) in vec2 aGrid;\n\nuniform mat4 uViewProj;\nuniform mat4 uReflectionViewProj;\nuniform vec3 uCameraPos;\nuniform float uTime;\n/**\n * Where the sheet is laid, in world XZ.\n *\n * The ocean passes its own camera position snapped to whole cells, which is what\n * gives an endless sea from a fixed vertex budget without the surface sliding\n * underfoot. A *bounded* sheet \u2014 a pool in a courtyard \u2014 passes the middle of the\n * thing it is filling instead, and is world-fixed by construction.\n *\n * Snapped on the CPU rather than here so that one number is the only difference\n * between an ocean and a basin, and the shader has no idea which it is drawing.\n */\nuniform vec2 uGridOrigin;\n/**\n * Metres per unit of the sheet's own grid, along each of the body's own axes.\n *\n * One and one for the ocean, whose grid is authored in metres and is two meshes wide.\n * A bounded body \u2014 a pool, a tank, a puddle, a channel \u2014 is drawn from a unit sheet\n * and scaled by its own half-extents, which is what lets one mesh and one material\n * serve every body of water in the world.\n *\n * **Two numbers and not one since 2026-08-28.** A single span makes every bounded\n * body square, and a square that contains a channel floods the ground either side\n * of it. The ocean passes the same number twice and is bit-identical to what it was.\n */\nuniform vec2 uGridSpan;\nuniform vec2 uGridHalf;\nuniform vec2 uNearHalf;\n/**\n * The body's own +z, in world XZ, unit length. (0, 1) leaves the sheet unturned.\n *\n * A direction rather than an angle, so nothing here needs a trig call and a consumer\n * bounding a channel can hand over the direction its run already takes. The across\n * axis is world up crossed with this, `(fz, -fx)`, which is the basis\n * `MeshBuilder.addOrientedBox` builds from a forward vector \u2014 one convention for an\n * oriented thing, so a reader who has met one has met both.\n */\nuniform vec2 uGridForward;\n/** Prevailing wind bearing, normalised. Waves are steered toward it. */\nuniform vec2 uWindDir;\n/** Multiplier on authored steepness \u2014 how built-up the sea is. */\nuniform float uWaveGain;\nuniform float uWaterLevel;\n\nout vec3 vWorldPos;\nout vec3 vNormal;\nout float vCrest;\nout vec4 vReflectionClip;\n/** Grid-local offset, so the sheet can fade out its own boundary. */\nout vec2 vGrid;\n\n\nconst int GERSTNER_COUNT = 4;\n/*\n * direction.xy, steepness, wavelength. Amplitude is steepness/k, so these sum to\n * roughly a 1m swell \u2014 enough to read as a living surface, low enough that crests\n * never wash over an island whose deck sits ~1.8m above sea level.\n */\nconst vec4 GERSTNER_WAVES[4] = vec4[4](\n  vec4( 1.0,  0.0,  0.115, 34.0),\n  vec4( 0.6,  0.8,  0.100, 18.0),\n  vec4(-0.7,  0.7,  0.080,  9.0),\n  vec4( 0.2, -0.98, 0.060,  5.0)\n);\n\n/*\n * Steer each wave toward the wind, but only partway. A real sea is a dominant\n * swell plus cross-chop; rotating all four onto one bearing gives corduroy,\n * which reads as a material rather than as water.\n */\nvec2 gerstnerDirection(int i, vec2 windDir) {\n  return normalize(mix(normalize(GERSTNER_WAVES[i].xy), windDir, 0.62));\n}\n\nfloat gerstnerWavenumber(int i) {\n  return 6.28318530718 / GERSTNER_WAVES[i].w;\n}\n\n/** Deep-water phase in radians at a point on the resting plane. */\nfloat gerstnerPhase(float k, vec2 dir, vec2 p, float time) {\n  float c = sqrt(9.81 / k);              // deep-water phase speed\n  return k * (dot(dir, p) - c * time);\n}\n\nstruct GerstnerSurface {\n  /** Displacement from the resting plane \u2014 horizontal as well as vertical. */\n  vec3 offset;\n  vec3 normal;\n  /** Height in units of steepness; positive near a crest. */\n  float crest;\n};\n\nGerstnerSurface gerstnerSurface(vec2 p, float time, vec2 windDir, float gain) {\n  GerstnerSurface s;\n  s.offset = vec3(0.0);\n  s.normal = vec3(0.0, 1.0, 0.0);\n  s.crest = 0.0;\n  for (int i = 0; i < GERSTNER_COUNT; i++) {\n    vec2 dir = gerstnerDirection(i, windDir);\n    float steepness = GERSTNER_WAVES[i].z * gain;\n    float k = gerstnerWavenumber(i);\n    float f = gerstnerPhase(k, dir, p, time);\n    float a = steepness / k;             // amplitude from steepness\n\n    s.offset.x += dir.x * a * cos(f);\n    s.offset.y += a * sin(f);\n    s.offset.z += dir.y * a * cos(f);\n\n    // Analytic normal: the partial derivatives of the displacement above.\n    s.normal.x -= dir.x * steepness * cos(f);\n    s.normal.z -= dir.y * steepness * cos(f);\n    s.normal.y -= steepness * sin(f);\n\n    s.crest += sin(f) * steepness;\n  }\n  return s;\n}\n\n/**\n * Second derivatives of the height field: (d2h/dx2, d2h/dz2, d2h/dxdz).\n *\n * How the surface *bends*, which is what decides where reflected light\n * converges. Analytic from the same sum, so it cannot disagree with the shape\n * the vertex stage displaced.\n */\nvec3 gerstnerCurvature(vec2 p, float time, vec2 windDir, float gain) {\n  vec3 h = vec3(0.0);\n  for (int i = 0; i < GERSTNER_COUNT; i++) {\n    vec2 dir = gerstnerDirection(i, windDir);\n    float steepness = GERSTNER_WAVES[i].z * gain;\n    float k = gerstnerWavenumber(i);\n    float f = gerstnerPhase(k, dir, p, time);\n    // Second derivative of (steepness/k)*sin(f) along the wave's own bearing.\n    float second = -steepness * k * sin(f);\n    h.x += second * dir.x * dir.x;\n    h.y += second * dir.y * dir.y;\n    h.z += second * dir.x * dir.y;\n  }\n  return h;\n}\n\n\nvoid main() {\n  /*\n   * Waves must reach nothing by the near sheet's edge, because beyond it lies\n   * the flat skirt. A displaced rim meeting an undisplaced skirt would tear the\n   * surface open along a visible seam; fading first makes the two meshes agree\n   * exactly where they meet. Chebyshev distance, so the fade band follows the\n   * rectangular boundary rather than cutting an ellipse inside it.\n   *\n   * **Measured as a fraction of each axis' own extent**, which is what lets a\n   * channel three metres across and twenty-one long fade evenly at both its ends\n   * and both its sides. Against one shared extent the narrow axis would be inside\n   * the fade band along its whole length and the water would never reach its own\n   * bank. For the ocean, whose two extents are equal, this is the same arithmetic\n   * with the division moved one step earlier.\n   *\n   * It is also the honest thing to draw. At a few hundred metres a 1 m swell is\n   * well under a pixel, and out on the skirt a float32 phase argument has lost\n   * most of its meaningful bits \u2014 a calm horizon is what an ocean actually looks\n   * like from that far away.\n   */\n  vec2 grid = aGrid * uGridSpan;\n  /* The same offset the fragment stage fades the rim on, so the two cannot disagree. */\n  vGrid = grid;\n  vec2 rimFraction = abs(grid) / max(uNearHalf, vec2(1e-4));\n  float rimDistance = max(rimFraction.x, rimFraction.y);\n  float waveFade = 1.0 - smoothstep(0.35, 0.97, rimDistance);\n\n  /*\n   * Into the world: across the body, then along it. `right = up x forward` is\n   * `(fz, -fx)`, and getting that pair the wrong way round is a sheet mirrored\n   * about its own axis, which on a square is invisible and on a channel is a\n   * channel across the road instead of along it.\n   */\n  vec2 laid = vec2(uGridForward.y, -uGridForward.x) * grid.x + uGridForward * grid.y;\n\n  vec3 base = vec3(uGridOrigin.x + laid.x, uWaterLevel, uGridOrigin.y + laid.y);\n\n  GerstnerSurface sea = gerstnerSurface(base.xz, uTime, uWindDir, waveFade * uWaveGain);\n  vec3 pos = base + sea.offset;\n\n  vWorldPos = pos;\n  vNormal = normalize(sea.normal);\n  vCrest = sea.crest;\n  vReflectionClip = uReflectionViewProj * vec4(pos, 1.0);\n  gl_Position = uViewProj * vec4(pos, 1.0);\n}\n";
+export declare const WATER_FRAG = "#version 300 es\nprecision highp float;\n\nin vec3 vWorldPos;\nin vec3 vNormal;\nin float vCrest;\nin vec4 vReflectionClip;\nin vec2 vGrid;\n\nuniform vec2 uGridHalf;\nuniform float uFoamGain;\n/**\n * How much of what is beneath it a body of water hides, looked straight down.\n *\n * The *density* of the water rather than a rendering trick: a sea hides its own\n * floor, a fountain shows the tiles at the bottom of it, and a puddle is nearly\n * clear. Only the nadir end is configurable \u2014 at a grazing angle every water\n * surface goes reflective, which is Fresnel and not a property of the liquid.\n */\nuniform float uNadirOpacity;\n/** The whole surface's visibility, 0 to 1. Zero draws nothing at all. */\nuniform float uVisibility;\n/**\n * How much this body mirrors regardless of the angle it is seen at, 0 to 1.\n *\n * Zero is physics: reflection is Fresnel alone, which is right for an ocean seen\n * across its own surface and which means *almost nothing* when you stand over a\n * basin and look down into it \u2014 the angle is steep, the Fresnel term is a few\n * percent, and a reflection nobody can see is the same as no reflection: the\n * character's reflection is technically present and far too faint to perceive.\n *\n * So a body may declare itself more mirror than water. It is a lie about optics\n * and an honest one about what a small pool is *for*: you look into it to see\n * something. The sea keeps zero and behaves exactly as it always has.\n */\nuniform float uMirror;\nuniform vec3 uDeepColor;\nuniform vec3 uShallowColor;\nuniform vec3 uDirectionalDir;\nuniform vec3 uDirectionalColor;\nuniform vec3 uAmbient;\n/**\n * The scene's point lights, which water is entitled to as much as stone is.\n *\n * The surface used to answer to the sun alone, on the reasonable assumption that water\n * is a thing that sits under the sky. It is not: a flooded corridor, a cistern, an\n * indoor pool and a harbour at night are all water lit entirely by lamps, and under\n * those this shaded to flat ambient \u2014 a coloured plane, with the specular glitter that\n * is the single strongest cue that a surface *is* water switched off because no\n * directional source existed to make it. A lantern on a jetty threw nothing.\n *\n * Same slots, same weights and the same two falloff shapes as the surface shader, so a\n * lamp behaves the same way over water as it does over the ground beside it.\n */\n#define MAX_LIGHTS 16\nuniform int uLightCount;\nuniform vec3 uLightPos[MAX_LIGHTS];\nuniform vec3 uLightColor[MAX_LIGHTS];\nuniform float uLightRadius[MAX_LIGHTS];\nuniform float uLightWeight[MAX_LIGHTS];\nuniform int uLightFalloff;\n\nuniform vec3 uFogColor;\n/** Extinction per metre **at the camera's own height**, not at the base. */\nuniform float uFogDensity;\n/** Reciprocal scale height of the haze, per metre. 0 is a uniform medium. */\nuniform float uFogHeightFalloff;\n/** The camera's height, so a fragment's own height is one subtraction away. */\nuniform float uFogEyeY;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFogDensity;\nuniform float uUnderwaterFactor;\n/** 0 integrates a medium (Beer-Lambert); 1 ramps linearly between near and far. */\nuniform int uFogMode;\n/** Linear mode only: where haze begins, and where it is total. */\nuniform float uFogNear;\nuniform float uFogFar;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogMode == 1) {\n    float span = max(uFogFar - uFogNear, 1e-4);\n    float ramp = clamp((dist - uFogNear) / span, 0.0, 1.0);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uUnderwaterFogDensity * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(t) < 1e-4 ? 1e-4 : t;\n  float air = 1.0 - exp(-uFogDensity * dist * (1.0 - exp(-denom)) / denom);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uUnderwaterFogDensity * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\nuniform vec3 uCameraPos;\nuniform sampler2D uReflectionMap;\nuniform int uReflectionEnabled;\nuniform vec2 uReflectionTexelSize;\nuniform int uReflectionFilterTaps;\n\nconst vec2 REFLECTION_FILTER[9] = vec2[9](\n  vec2( 0.00,  0.00), vec2(-0.62, -0.31), vec2( 0.54,  0.43),\n  vec2(-0.34,  0.76), vec2( 0.78, -0.57), vec2(-0.88,  0.28),\n  vec2( 0.22, -0.91), vec2( 0.91,  0.08), vec2(-0.18,  0.94)\n);\n// Preserve small moving silhouettes such as a character while still spreading\n// the surrounding taps enough to make the target read as rough water.\nconst float REFLECTION_FILTER_WEIGHT[9] = float[9](\n  0.28, 0.09, 0.09, 0.09, 0.09, 0.09, 0.09, 0.09, 0.09\n);\n\nout vec4 outColor;\n\nvoid main() {\n  vec3 n = normalize(vNormal);\n  vec3 view = normalize(uCameraPos - vWorldPos);\n\n  // Fresnel: water is nearly a mirror at grazing angles and clear straight down.\n  // abs keeps the underside physically continuous with the top instead of\n  // turning the entire surface into an opaque mirror below the waterline.\n  float facing = clamp(abs(dot(n, view)), 0.0, 1.0);\n  float fresnel = 0.02 + 0.98 * pow(1.0 - facing, 5.0);\n\n  vec3 atmosphereColor = mediumColor();\n\n  vec3 col = mix(uDeepColor, uShallowColor, clamp(vCrest * 1.4 + 0.4, 0.0, 1.0));\n  vec3 incident = uAmbient +\n    uDirectionalColor * max(dot(n, uDirectionalDir), 0.0) * 0.6;\n\n  // Specular glitter along the crests \u2014 the strongest single cue that a surface\n  // is water rather than a coloured plane.\n  vec3 halfVec = normalize(uDirectionalDir + view);\n  float spec = pow(max(dot(n, halfVec), 0.0), 220.0);\n  vec3 highlight = uDirectionalColor * spec * 1.6;\n\n  /*\n   * And the same from every lamp in range: a light over water lights it, and glitters\n   * on it. Indoors this is the whole of the surface's lighting.\n   *\n   * The exponent is the sun's, so a crest picks a lamp out as tightly as it picks out\n   * the sky \u2014 which is what makes a strip light read as a *streak* across a pool rather\n   * than a broad sheen. Weighted by presence like every other consumer of these slots,\n   * so a light entering the set fades in instead of appearing.\n   */\n  for (int i = 0; i < MAX_LIGHTS; i++) {\n    if (i >= uLightCount) break;\n    vec3 toLight = uLightPos[i] - vWorldPos;\n    float lightDist = length(toLight);\n    float falloff;\n    if (uLightFalloff == 1) {\n      float window = clamp(1.0 - pow(lightDist / max(uLightRadius[i], 1e-4), 4.0), 0.0, 1.0);\n      falloff = window * window / max(lightDist * lightDist, 0.01);\n    } else {\n      falloff = clamp(1.0 - lightDist / max(uLightRadius[i], 1e-4), 0.0, 1.0);\n    }\n    if (falloff <= 0.0) continue;\n    vec3 lightDir = toLight / max(lightDist, 1e-4);\n    float shaped = falloff * uLightWeight[i];\n    incident += uLightColor[i] * max(dot(n, lightDir), 0.0) * shaped * 0.6;\n    vec3 lampHalf = normalize(lightDir + view);\n    highlight += uLightColor[i] * pow(max(dot(n, lampHalf), 0.0), 220.0) * shaped * 1.6;\n  }\n\n  col *= incident;\n  col += highlight;\n\n  // Foam where crests peak \u2014 and only when the wind is actually breaking them.\n  float foam = smoothstep(0.55, 0.85, vCrest) * uFoamGain;\n  col = mix(col, vec3(0.92, 0.96, 1.0), foam * 0.5);\n\n  float dist = distance(vWorldPos, uCameraPos);\n  float fog = mediumFog(dist, vWorldPos.y);\n  col = mix(col, atmosphereColor, fog);\n\n  // Transparency is angle-dependent, like real water: looking down you see\n  // straight through to the seabed, at grazing angles it turns reflective.\n  // This is computed before reflection because straight-alpha compositing must\n  // not attenuate reflected radiance a second time below.\n  float airOpacity = mix(uNadirOpacity, 0.96, fresnel);\n  float underwaterOpacity = mix(uNadirOpacity * 0.55, 0.88, fresnel);\n  float opacity = mix(airOpacity, underwaterOpacity, uUnderwaterFactor);\n  opacity = mix(opacity, 0.96, foam * 0.7);\n\n  // Project the displaced surface into the mirrored camera. The Gerstner\n  // displacement supplies broad distortion; the analytic normal adds the\n  // smaller ripples that make reflected silhouettes move with each crest.\n  vec3 reflected = atmosphereColor;\n  float reflectionValid = 0.0;\n  if (uReflectionEnabled != 0 && vReflectionClip.w > 0.0) {\n    vec2 reflectionUv = vReflectionClip.xy / vReflectionClip.w * 0.5 + 0.5;\n    reflectionUv += n.xz * mix(0.008, 0.022, fresnel);\n    vec2 border = min(reflectionUv, 1.0 - reflectionUv);\n    reflectionValid = smoothstep(0.0, 0.025, min(border.x, border.y));\n    // A planar target is optically sharp, which is correct for a mirror but\n    // wrong for a moving water surface. Broaden it over a Poisson footprint\n    // that grows gently with viewing distance; normal displacement above\n    // still makes every crest steer that softened image independently.\n    float blurPixels = 1.35 + min(dist * 0.022, 3.5);\n    vec3 sceneReflection = vec3(0.0);\n    float filterWeight = 0.0;\n    for (int i = 0; i < 9; i++) {\n      if (i >= uReflectionFilterTaps) break;\n      vec2 sampleUv = reflectionUv +\n        REFLECTION_FILTER[i] * uReflectionTexelSize * blurPixels;\n      float weight = REFLECTION_FILTER_WEIGHT[i];\n      /*\n       * `textureLod` rather than `texture`, by the rule `AGENTS.md` records on 2026-08-07:\n       * this loop is reached through a branch on `vReflectionClip`, which is not uniform, and\n       * an implicit derivative there is undefined. **WGSL does not merely leave it undefined,\n       * it refuses to compile the module**: *\"'textureSample' must only be called from uniform\n       * control flow\"*, with the note that reading `vReflectionClip` may be non-uniform.\n       *\n       * Bit-identical on WebGL2: `planarReflection.ts` allocates one level and filters\n       * `LINEAR`, so there is no mip to select and level zero is the only thing `texture`\n       * could have read.\n       */\n      sceneReflection +=\n        textureLod(uReflectionMap, clamp(sampleUv, 0.0, 1.0), 0.0).rgb * weight;\n      filterWeight += weight;\n    }\n    sceneReflection /= max(filterWeight, 0.001);\n    reflected = mix(atmosphereColor, sceneReflection, reflectionValid);\n  }\n  // The atmosphere-colour fallback preserves the old sky reflection when a\n  // quality profile disables the extra scene pass. Foam scatters rather than\n  // mirroring, so it masks the reflection at breaking crests.\n  float sceneWeight = float(uReflectionEnabled) * reflectionValid;\n  float reflectionGain = mix(0.75, 0.94, sceneWeight);\n  // Angle-honest by default, and a mirror where a body says so. See uMirror above.\n  float reflectivity = mix(fresnel, 1.0, uMirror);\n  float reflectedRadiance = min(\n    reflectivity * reflectionGain * (1.0 - foam * 0.8),\n    opacity\n  );\n  // With SRC_ALPHA blending, mixing by Fresnel directly would multiply the\n  // reflection by opacity again. Divide it out here so the framebuffer gets\n  // the intended reflected fraction while the remainder stays transmissive.\n  float reflectionWeight = reflectedRadiance / max(opacity, 0.001);\n  col = mix(col, reflected, reflectionWeight);\n\n  /*\n   * Dissolve the sheet at its own boundary.\n   *\n   * Fading on fog alone made the horizon a function of the daily palette: a\n   * clear day never reached the threshold, so the grid's rim \u2014 corner and all \u2014\n   * became the skyline. Fading on the grid coordinate cannot fail that way,\n   * because alpha reaches zero at the last row of vertices by construction.\n   * Chebyshev distance because the sheet is a rectangle, so the fade band\n   * follows its four edges instead of cutting an ellipse out of it \u2014 and it is\n   * measured per axis, or a channel's narrow sides would be one continuous fade\n   * and it would have no visible edge at all.\n   */\n  vec2 rimFraction = abs(vGrid) / max(uGridHalf, vec2(0.001));\n  float rimT = max(rimFraction.x, rimFraction.y);\n  float rim = 1.0 - smoothstep(0.9, 1.0, rimT);\n  // Fog still helps where it is thick, it just is no longer load-bearing.\n  float edge = 1.0 - smoothstep(0.82, 1.0, fog);\n  outColor = vec4(col, opacity * edge * rim * uVisibility);\n}\n";