@driftengine/core 3.61.0

package/src/render/shaders/ssrResolve.ts

@@ -0,0 +1,28 @@
+/**
+ * The screen-space reflection resolve: what the trace found, composited over the scene.
+ *
+ * **One fetch, because the compositing is the blend state.** The trace writes premultiplied colour
+ * and coverage into a target of its own — it has to, since it samples the scene and a pass that
+ * read the colour it was writing would be a feedback loop — and this hands those texels to a
+ * `(one, one-minus-src-alpha)` blend, which is `over`. So the resolve never samples the target it
+ * is compositing onto, which is the arrangement `oitResolve.ts` reaches by the same argument.
+ *
+ * Premultiplied is what makes several reflective surfaces overlapping accumulate the way two
+ * blended layers do rather than the way two independent guesses do.
+ *
+ * The vertex stage is `FULLSCREEN_VERT`, shared with the occlusion pass, its blur and the rush.
+ */
+export const SSR_RESOLVE_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+/** Premultiplied reflection in rgb, coverage in a. Cleared to zero: nothing found is nothing. */
+uniform sampler2D uSsrReflection;
+
+out vec4 fragColor;
+
+void main() {
+  fragColor = textureLod(uSsrReflection, vUv, 0.0);
+}
+`;

package/src/render/shaders/ssrTrace.ts

@@ -0,0 +1,233 @@
+/**
+ * The screen-space reflection trace: a reflected ray marched against the frame's own depth.
+ *
+ * **This mirrors `traceScreenSpaceRay` line for line**, and that is the point of writing it twice.
+ * When a crossing counts as a hit, how far behind a surface it may land, what happens at the edge
+ * of the frame and what happens over a gap in the geometry are each a defect that draws a
+ * *plausible* picture rather than failing — and each of them is settled by arithmetic that needs no
+ * GPU. The TypeScript beside this file is the specification and its tests are where those cases are
+ * pinned; this is the same walk, in the language that can sample a depth buffer.
+ *
+ * **It writes into a target of its own rather than onto the scene**, because it samples the scene:
+ * a pass that read the colour it was writing would be a feedback loop, reported once per draw on
+ * WebGL2 and rejected outright on WebGPU. `ssrPass.ts` composites the result afterwards, which is
+ * the arrangement `oitPass.ts` already uses and for the same reason.
+ *
+ * **The derivatives come first and the march comes second.** The surface normal is the cross
+ * product of the reconstructed position's screen derivatives — there being no normal buffer to read
+ * one from — and a derivative taken inside non-uniform control flow is undefined. So everything
+ * that could branch happens after them, and every fetch inside the march takes an explicit level
+ * for the same rule read the other way.
+ */
+
+import { glslIsFarDepth } from '../depthConvention.ts';
+
+/**
+ * The most samples the march may take. `uSsrSteps` breaks out early.
+ *
+ * A constant bound because a loop the compiler cannot bound is one it cannot unroll or budget, and
+ * because thirty-two two-metre steps is sixty-four metres — further than a screen-space method can
+ * usefully see, since a ray that long has almost certainly left the frame.
+ */
+const MAX_STEPS = 32;
+/** How many times a bracketed crossing is halved. Matches `REFINE_STEPS` in the TypeScript. */
+const REFINE_STEPS = 6;
+
+export const SSR_TRACE_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+/**
+ * The depth the frame drew, as a copy.
+ *
+ * \`highp\` because a sampler's default precision is lowp whatever \`precision highp float\` says,
+ * and every world position below is reconstructed by dividing through it.
+ */
+uniform highp sampler2D uSsrDepth;
+/** The finished scene colour — what a ray finds is a pixel of this. */
+uniform sampler2D uSsrScene;
+/** Screen position and stored depth back to the world. See \`DEPTH_01_TO_CLIP\`. */
+uniform mat4 uSsrDepthToWorld;
+/**
+ * World back to a screen position, with the framebuffer's own Y sense already in it.
+ *
+ * **The flip is in the matrix rather than in a branch here**, so the shader is one expression on
+ * both backends and the convention lives in one place — the lesson \`DEPTH_01_TO_CLIP_Y_DOWN\`
+ * records at length, arriving through the other door.
+ */
+uniform mat4 uSsrViewProj;
+/** World into the reflective box, \`[-1, 1]\` on each axis. */
+uniform mat4 uWorldToSurface;
+uniform vec3 uSsrEye;
+/** The box's own axis. A surface reflects when it faces back along this. */
+uniform vec3 uSsrAxis;
+uniform vec3 uSsrTint;
+uniform float uSsrStrength;
+uniform float uSsrFacingCos;
+uniform float uSsrReach;
+uniform float uSsrThickness;
+uniform float uSsrSteps;
+/** How much of the frame each side is fade, as a fraction. */
+uniform float uSsrEdgeFade;
+
+out vec4 fragColor;
+
+/** What the frame drew at a screen position, as a world point. */
+vec3 worldAt(vec2 uv, float stored) {
+  vec4 world = uSsrDepthToWorld * vec4(uv * 2.0 - 1.0, stored, 1.0);
+  return world.xyz / world.w;
+}
+
+/**
+ * How far the eye is from whatever the frame drew there, and a huge number where it drew nothing.
+ *
+ * The sky is not a surface. A march that treated an untouched depth as one would reflect the whole
+ * world in the horizon, which is the failure that looks like a working effect from one angle.
+ */
+float sceneDistanceAt(vec2 uv) {
+  float stored = textureLod(uSsrDepth, uv, 0.0).r;
+  if (${glslIsFarDepth('stored')}) return 1.0e9;
+  return length(worldAt(uv, stored) - uSsrEye);
+}
+
+/** A world point to a screen position. False where it is behind the eye or outside the frame. */
+bool projectPoint(vec3 point, out vec2 uv) {
+  vec4 clip = uSsrViewProj * vec4(point, 1.0);
+  if (clip.w <= 0.0) return false;
+  uv = (clip.xy / clip.w) * 0.5 + 0.5;
+  return uv.x >= 0.0 && uv.x <= 1.0 && uv.y >= 0.0 && uv.y <= 1.0;
+}
+
+void main() {
+  float stored = textureLod(uSsrDepth, vUv, 0.0).r;
+  vec3 point = worldAt(vUv, stored);
+
+  /*
+   * **The normal from the reconstruction's own derivatives, turned to face the eye.**
+   *
+   * There is no normal buffer here and adding one is a second colour attachment written by every
+   * draw path in the engine. Two neighbouring pixels of the same surface span its plane, so their
+   * cross product is its normal — noisy along a silhouette and exact everywhere else. Which way
+   * that cross product points depends on which way the framebuffer's rows run, and the two
+   * backends disagree about that; a visible surface faces the eye by definition, which is what
+   * fixes the sign. \`decalProject.ts\` carries the same pair of facts.
+   *
+   * Taken here, before anything branches, because a derivative in non-uniform control flow is
+   * undefined and the whole of the march below is a branch.
+   */
+  vec3 plane = cross(dFdx(point), dFdy(point));
+  float span = length(plane);
+  vec3 normal = span > 0.0 ? plane / span : -uSsrAxis;
+  vec3 toEye = uSsrEye - point;
+  normal *= sign(dot(toEye, normal));
+
+  vec3 box = (uWorldToSurface * vec4(point, 1.0)).xyz;
+  vec3 inside = step(abs(box), vec3(1.0));
+  float mask = inside.x * inside.y * inside.z;
+
+  /* A surface turned away from the box's axis is not the one the caller called reflective — a wall
+     inside the volume of a wet floor is still a wall. Faded rather than cut, so the edge of the
+     rule is not an edge in the picture. */
+  float facing = dot(normal, -uSsrAxis);
+  mask *= smoothstep(uSsrFacingCos, min(1.0, uSsrFacingCos + 0.25), facing);
+  /* Nothing was drawn here, so there is no surface to reflect in. */
+  mask *= ${glslIsFarDepth('stored')} ? 0.0 : 1.0;
+  mask *= uSsrStrength;
+
+  vec3 found = vec3(0.0);
+  float weight = 0.0;
+
+  if (mask > 0.0) {
+    vec3 view = normalize(point - uSsrEye);
+    vec3 ray = reflect(view, normal);
+
+    float steps = max(1.0, uSsrSteps);
+    /*
+     * Zero to begin with, because the ray starts on the surface it is reflecting off. A crossing
+     * needs the previous sample strictly in front, so the first step cannot form one on its own —
+     * which is the self-intersection guard, and without it every pixel of a reflective floor takes
+     * the comparison on rounding at once.
+     */
+    float behind = 0.0;
+    float previous = 0.0;
+    vec2 hitUv = vec2(0.0);
+    float hitDistance = 0.0;
+    bool found_hit = false;
+
+    for (int i = 1; i <= ${MAX_STEPS}; i++) {
+      if (float(i) > steps) break;
+      /* Quadratic rather than even: a first step of centimetres, where the contact seam is, and a
+         last step of nearly a metre, out where a reflection is faint and about to leave the frame.
+         \`marchDistance\` in the TypeScript is the same expression and the reason is written there. */
+      float at = float(i) / steps;
+      float t = uSsrReach * at * at;
+      vec3 sample_point = point + ray * t;
+      vec2 uv;
+      if (!projectPoint(sample_point, uv)) break;
+
+      float scene = sceneDistanceAt(uv);
+      float gap = length(sample_point - uSsrEye) - scene;
+
+      if (behind < 0.0 && gap >= 0.0) {
+        /* A crossing, bracketed. Halved rather than reported: the coarse answer is a whole step
+           out, which puts a reflection visibly beside the thing reflected. */
+        float near = previous;
+        float far = t;
+        vec2 refinedUv = uv;
+        float refinedGap = gap;
+        for (int refine = 0; refine < ${REFINE_STEPS}; refine++) {
+          float mid = (near + far) * 0.5;
+          vec3 midPoint = point + ray * mid;
+          vec2 midUv;
+          if (!projectPoint(midPoint, midUv)) break;
+          float midScene = sceneDistanceAt(midUv);
+          float midGap = length(midPoint - uSsrEye) - midScene;
+          if (midGap >= 0.0) {
+            far = mid;
+            refinedUv = midUv;
+            refinedGap = midGap;
+          } else {
+            near = mid;
+          }
+        }
+
+        /* Believed only if the refined crossing landed within the thickness. A depth buffer says
+           nothing about how thick the thing at a pixel is, so without this a ray that slides onto
+           a foreground object pastes that object into the reflection. */
+        if (refinedGap <= uSsrThickness) {
+          found_hit = true;
+          hitUv = refinedUv;
+          hitDistance = far;
+        }
+        break;
+      }
+
+      behind = gap;
+      previous = t;
+    }
+
+    if (found_hit) {
+      /*
+       * Three fades, and they are most of what keeps this from looking wrong.
+       *
+       * A hit near the edge of the frame is about to leave it, so it leaves gradually rather than
+       * along a line. A ray pointing back toward the eye can only find what is between the surface
+       * and the camera, which is usually nothing and occasionally the viewer's own geometry. And a
+       * hit at the far end of the reach is the least reliable one the march can report, since it
+       * had the most chances to slide onto something.
+       */
+      float edge = clamp(min(min(hitUv.x, 1.0 - hitUv.x), min(hitUv.y, 1.0 - hitUv.y)) /
+        max(uSsrEdgeFade, 1.0e-4), 0.0, 1.0);
+      float away = clamp((dot(normalize(ray), view) + 1.0) * 0.5, 0.0, 1.0);
+      float reach = 1.0 - clamp(hitDistance / max(uSsrReach, 1.0e-4), 0.0, 1.0);
+      weight = mask * edge * away * reach;
+      found = textureLod(uSsrScene, hitUv, 0.0).rgb * uSsrTint;
+    }
+  }
+
+  /* Premultiplied, so the pass composites with (one, one-minus-src-alpha) and several reflective
+     surfaces overlapping accumulate the way two blended layers do. */
+  fragColor = vec4(found * weight, weight);
+}
+`;

package/src/render/shaders/tangentFrame.ts

@@ -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/src/render/shaders/temporalResolve.ts

@@ -0,0 +1,151 @@
+/**
+ * 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.ts';
+
+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/src/render/shaders/text.ts

@@ -0,0 +1,156 @@
+/**
+ * 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);
+}`;