# Build: A/B Layer Ping-Pong

A double buffer for DOM content. Incoming content is written into whichever of two absolutely-positioned layers is currently invisible, then the two swap opacity. Because the outgoing content is still on screen, every change is a real crossfade rather than a swap with a fade bolted on — and running two of these at different durations is how a hover preview gets its lag between thumbnail and full-bleed background.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Two stacked layers alternate so any change crossfades, however fast you move between rows.

- Category: transition
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. Two absolutely positioned layers share a stacking context. A `front` slot (`"a"` or `"b"`) records which one is currently visible; the other is always at opacity 0.
2. When `contentKey` changes, the new children are written into the BACK slot and `front` flips. The back layer is already transparent, so the new content mounts invisibly — writing into the front layer instead would replace the outgoing content before it had faded.
3. `gsap.killTweensOf([inEl, outEl])` runs before every transition. Moving across a list faster than the duration otherwise leaves an unfinished fade-out driving the same node a fade-in is now driving up, and the layers flicker.
4. Two symmetric tweens — `opacity: 1` on the incoming layer, `opacity: 0` on the outgoing — with `power2.inOut`, which keeps the midpoint of the fade at roughly equal luminance instead of dipping through a visible trough.
5. The first commit is a `gsap.set`, not a tween, so the initial content is simply present; only subsequent key changes animate.
6. The last `contentKey` acted on is held in a ref, so a parent re-rendering with the same key (new inline children, a hover on the row that is already active) does not restart the fade.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `duration (background) = 1`
  Seconds. A full-bleed area needs a long fade or the whole frame appears to jump brightness; at 0.5s a large gradient change reads as a cut.
- `duration (thumbnail) = 0.6`
  The small element under the cursor answers first. Both at 1s and the interface feels unresponsive; both at 0.6s and the background flickers on fast passes. The 0.4s difference is the effect.
- `ease = 'power2.inOut'`
  Symmetric ease on both halves keeps their crossover near 50/50. With `power2.out` on the way in and `power2.in` on the way out, both layers are dim at the midpoint and the panel visibly darkens mid-fade.

## API

```ts
function ABLayerCrossfade(props: { contentKey: string; children: ReactNode; duration?: number; ease?: string; className?: string }): JSX.Element
```

- `contentKey: string`
  Identity of the current content. A change starts a crossfade.
- `children: ReactNode`
  Content for the current key. Captured into a layer at the moment the key changes.
- `duration: number` — default `1`
  Crossfade length in seconds. Use a shorter one for the smaller element in a pair.
- `ease: string` — default `'power2.inOut'`
  GSAP ease applied to both halves.
- `className: string`
  Merged onto the positioned wrapper. Give it a size — the layers are absolute.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function ABLayerCrossfade({
  contentKey,
  children,
  duration = 1,
  ease = 'power2.inOut',
  className,
}: ABLayerCrossfadeProps) {
  const aRef = useRef<HTMLDivElement>(null);
  const bRef = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();

  const [front, setFront] = useState<Slot>('a');
  const [layers, setLayers] = useState<{ a: ReactNode; b: ReactNode }>({
    a: children,
    b: null,
  });

  const shownKey = useRef(contentKey);
  const frontRef = useRef<Slot>('a');
  const first = useRef(true);

  // Write into the BACK layer, then flip. The back layer is already at
  // opacity 0, so the new content mounts invisibly — no flash of it at full
  // strength before the tween starts.
  useEffect(() => {
    if (shownKey.current === contentKey) return;
    shownKey.current = contentKey;
    const next: Slot = frontRef.current === 'a' ? 'b' : 'a';
    frontRef.current = next;
    setLayers((l) => ({ ...l, [next]: children }));
    setFront(next);
  }, [contentKey, children]);

  useEffect(() => {
    const inEl = front === 'a' ? aRef.current : bRef.current;
    const outEl = front === 'a' ? bRef.current : aRef.current;
    if (!inEl || !outEl) return;

    if (first.current) {
      first.current = false;
      gsap.set(inEl, { opacity: 1 });
      gsap.set(outEl, { opacity: 0 });
      return;
    }

    // Kill first, always. Two rapid changes otherwise leave an old fade-out
    // running on the layer the new fade-in is driving up.
    gsap.killTweensOf([inEl, outEl]);

    if (reduced) {
      gsap.set(inEl, { opacity: 1 });
      gsap.set(outEl, { opacity: 0 });
      return;
    }

    gsap.to(inEl, { opacity: 1, duration, ease });
    gsap.to(outEl, { opacity: 0, duration, ease });
  }, [front, duration, ease, reduced]);

  useEffect(
    () => () => {
      gsap.killTweensOf([aRef.current, bRef.current]);
    },
    [],
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** An unmount effect calls `gsap.killTweensOf` on both layer elements, so an in-flight fade cannot write opacity to a detached node after React has removed it.

**Reduced motion.** The layers still ping-pong, but the swap is a `gsap.set` rather than a tween: content changes instantly with no fade. The double-buffer structure is unchanged, so nothing else in the component behaves differently.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Crossfading one element by swapping its content at opacity 0. There is nothing to fade out of, so it reads as a blink; the two-layer buffer is the whole point.
- Writing incoming content into the front layer. The old content is replaced before it has faded, which is a hard cut with a pointless fade on top.
- Skipping `killTweensOf`. Hovering four rows in a second stacks eight opacity tweens across two nodes, and the layers end up at whatever the last-finishing pair leaves behind — usually both partly transparent.
- Giving both layers the same duration in a paired preview. The lag between the small element and the full-bleed one is what makes the interaction feel like it is answering you; without it the whole frame changes at once and reads as a page change.
- Restarting the fade when the parent re-renders. Any inline `children` array is a new object every render, so the effect must compare `contentKey`, not identity, or a hover crossfades continuously.
- Leaving tweens running past unmount. They keep writing opacity onto detached nodes; the unmount cleanup kills both layers.

## Notes

- Layers hold whatever you give them — a gradient, a canvas, a `<video>`, an image. Nothing here is image-specific.
- Content is captured per key, so if the same key needs to show new children you must change the key. That is deliberate: it is the only way to know when a transition is warranted.
- App Router wiring: pass `contentKey={usePathname()}` and render the route content as children for a whole-page crossfade with no layout thrash.

## Definition of done

Move down a list at a normal pace and each change is a smooth blend with no dip in brightness at the midpoint. Sweep the cursor across every row as fast as you can and the layers never flicker or settle half-faded. In a paired setup, the small preview visibly finishes before the background does.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Analytic Disc Picking

A slow ring of camera-facing discs that answers "what is under the pointer" without a raycaster. Because every disc is parallel to the image plane, the pick reduces to intersecting the pointer ray with one plane per disc and comparing the hit against the radius — four arithmetic operations, no traversal, no allocation, and exact rather than approximate. It is also the only correct answer here: the billboard happens in the vertex shader, so `Raycaster` intersects a square that is not on screen.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Hit-test camera-facing discs by intersecting the pointer ray with their plane. Exact, allocation-free, and correct for shader billboards.

- Category: primitive
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. The vertex shader billboards in view space: `vec4 mv = modelViewMatrix * vec4(0.0, 0.0, 0.0, 1.0); mv.xy += position.xy * uScale;` takes only the translation out of the model-view matrix and adds the quad offset afterwards. The mesh's rotation and scale never reach a vertex, so the disc is always exactly parallel to the image plane and its view-space radius is exactly `uRadius * uScale`.
2. Because the disc is parallel to the image plane, its plane normal is the camera's view direction for every disc in the scene. `camera.getWorldDirection(viewDir)` is called once per frame and `plane.setFromNormalAndCoplanarPoint(viewDir, disc.position)` then differs only in its constant.
3. `raycaster.setFromCamera(ndc, camera)` builds the pointer ray and nothing else is used from the Raycaster — `intersectObjects` is never called. Constructing the ray is the cheap half of raycasting; the traversal, the per-object matrix inverse, and the per-triangle intersection are the half being skipped.
4. `ray.intersectPlane(plane, hit)` returns `Vector3 | null`, and the null case is a free depth rejection: `Ray.distanceToPlane` returns null for `t < 0`, so anything behind the camera drops out before any distance work.
5. The winner is the nearest hit along the ray whose distance from the disc centre is within the radius, both compared squared. Depth is tested FIRST — `if (along >= bestAlong) continue;` — so a disc that cannot beat the incumbent never runs its own radius test.
6. The pick radius is `uRadius * uScale`, the same two numbers the vertex shader multiplies. Hover eases `uScale` from 1 to 1.14, and the pick reads the eased value in the same frame, so a disc is never clickable over area it has not grown into and never stops being clickable over area it still occupies.
7. Every scratch object — ray, plane, hit vector, view direction, NDC vector — is allocated once into the stage object and reused. A pick loop that allocates a `Vector3` per disc per frame produces 780 garbage vectors a second at 60 Hz on a ring of thirteen.
8. Rendering is gated on a dirty flag. The flag is set by the spin, by pointer movement, by a hover easing that is still in flight, and by resize. Under `prefers-reduced-motion` the spin never sets it, so the renderer idles at zero draw calls until the pointer moves.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `FOV = 42`
  Camera vertical field of view in degrees. Wide enough that the near discs are visibly larger than the far ones — which is what makes an analytic test worth having — and narrow enough that the ring does not distort into an oval at preview aspect ratios.
- `CAM_Z / ringRadius = 5.6 / 2.15`
  A ratio of about 2.6. Closer and the front disc overruns the frame at preview width; further and the perspective flattens until a cheap screen-space approximation would have been good enough, which defeats the demonstration.
- `discRadius = 0.46`
  World units, and simultaneously the pick radius. A single source for both is the entire point: two constants that mean "how big is this disc" is how a hit region drifts away from the pixels it is supposed to cover.
- `WAVE = 0.34`
  Vertical amplitude of the sin(2a) offset. Enough that the ring reads as a ribbon rather than a flat carousel; past ~0.6 the discs at the crossings overlap and the nearest-along-the-ray tie-break starts doing visible work the user has no way to predict.
- `HOVER_SMOOTHING = 0.0006`
  Fraction of the hover gap remaining after one second, as `damp` defines it — about 12% of the gap per frame at 60 Hz, settling in roughly 0.2 s. A per-frame constant instead would converge twice as fast on a 120 Hz display and the growth would feel like a different component.
- `HOVER_GROWTH = 0.14`
  A hovered disc grows 14%. Large enough to read at the back of the ring where a disc is a third of its front size, small enough that the grown disc does not swallow its neighbours and make the pick ambiguous.
- `FEATHER = 0.035`
  Rim gradient width in units of the radius — roughly 1.5 px at preview scale. This is why the renderer is built with `antialias: false`: MSAA would pay for an entire extra sample buffer to solve a problem one smoothstep already solved.

## API

```ts
function AnalyticDiscPicking(props: { count?: number; period?: number; discRadius?: number; ringRadius?: number; color?: string; accent?: string; seed?: number | string; compare?: boolean; onPick?: (index: number) => void; className?: string }): JSX.Element
```

- `count: number` — default `13`
  Discs around the ring.
- `period: number` — default `30`
  Seconds for one revolution.
- `discRadius: number` — default `0.46`
  Disc radius in world units. Also the pick radius — the two cannot drift apart.
- `ringRadius: number` — default `2.15`
  Ring radius in world units.
- `color: string` — default `'#7d848e'`
  Base plate colour. Any value `THREE.Color` accepts.
- `accent: string` — default `'#e8e4dc'`
  Colour of the picked disc.
- `seed: number | string` — default `'analytic-disc-picking'`
  Seeds the per-disc plate pattern. Same seed, same ring every reload.
- `compare: boolean` — default `false`
  Also run a real `Raycaster` each frame and report what it thinks was hit.
- `onPick: (index: number) => void`
  Fired when a disc is clicked, with its index.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
useRaf((dt) => {
  const s = stage.current;
  if (!s) return;

  // The ring phase is integrated from dt, not read from a wall clock, so
  // freezing it for reduced motion is a matter of not adding anything.
  if (!reduced) {
    spin.current = (spin.current + (TAU / period) * dt) % TAU;
    dirty.current = true;
  }

  // -- place the discs -----------------------------------------------------
  for (const disc of s.discs) {
    const a = disc.phase + spin.current;
    disc.mesh.position.set(
      Math.sin(a) * ringRadius,
      Math.sin(a * 2) * WAVE,
      Math.cos(a) * ringRadius,
    );
    // `cos(a)` is +1 at the front of the ring and -1 at the back. Remapped
    // to 0..1 it is the depth fade, and it costs nothing extra here.
    disc.uniforms.uDepth.value = Math.cos(a) * 0.5 + 0.5;
  }
  // No `updateMatrixWorld` here on purpose. The discs are direct children of
  // the scene at identity, so `mesh.position` IS the world position, and the
  // camera's matrix was made current in `resize`. The only consumer of the
  // full matrix graph is `render`, which updates it itself.

  // -- the analytic pick ---------------------------------------------------
  let best = -1;
  const p = pointer.current;
  if (p) {
    s.ndc.set(p.x, p.y);
    // The Raycaster is used for its RAY and nothing else. Building an
    // NDC-to-world ray by hand means duplicating `unproject`; the expensive
    // half of raycasting is `intersectObjects`, which is never called.
    s.raycaster.setFromCamera(s.ndc, s.camera);
    const ray = s.raycaster.ray;
    // Every disc is parallel to the image plane, so they all share one
    // normal — the camera's view direction, already unit length. Only the
    // plane's constant differs from disc to disc.
    s.camera.getWorldDirection(s.viewDir);

    let bestAlong = Infinity;
    for (let i = 0; i < s.discs.length; i += 1) {
      const disc = s.discs[i];
      if (!disc) continue;

      s.plane.setFromNormalAndCoplanarPoint(s.viewDir, disc.mesh.position);
      // `intersectPlane` returns null when the plane is behind the ray
      // origin, which rejects anything behind the camera for free. Note that
      // `Ray.distanceToPlane` returns null too but is TYPED `number` in
      // @types/three — the honest signature is on this method.
      if (ray.intersectPlane(s.plane, s.hit) === null) continue;

      // Nearest along the ray wins. Checked first so a disc that cannot
      // beat the incumbent skips its own radius test.
      const along = s.hit.distanceToSquared(ray.origin);
      if (along >= bestAlong) continue;

      // The drawn radius, hover growth included. `uScale` was eased last
      // frame and is applied by the vertex shader this frame, so the region
      // tested is the region rasterised.
      const r = disc.uniforms.uRadius.value * disc.uniforms.uScale.value;
      if (s.hit.distanceToSquared(disc.mesh.position) > r * r) continue;

      bestAlong = along;
      best = i;
    }
  }

  // -- ease the hover, which the next frame's pick will read ---------------
  for (let i = 0; i < s.discs.length; i += 1) {
    const disc = s.discs[i];
    if (!disc) continue;
    const target = i === best ? 1 : 0;
    const next = damp(disc.hover, target, HOVER_SMOOTHING, dt);
    if (Math.abs(next - disc.hover) > 0.0005) dirty.current = true;
    disc.hover = next;
    disc.uniforms.uHover.value = next;
    disc.uniforms.uScale.value = 1 + HOVER_GROWTH * next;
    disc.uniforms.uPicked.value = i === pickedRef.current ? 1 : 0;
  }

  if (best !== hovered.current) {
    hovered.current = best;
    setHover(best);
    dirty.current = true;
  }

  // -- what a real raycaster would have said -------------------------------
  if (compare) {
    let g = -1;
    if (p) {
      // The raycaster reads `matrixWorld`, which `render` would not refresh
      // until the end of this frame. The analytic path needed no such call —
      // it reads `position` directly — so this traversal is a cost the
      // comparison introduces, not one it inherits.
      s.scene.updateMatrixWorld();
      // Reused array, cleared by hand: `intersectObjects` pushes into the
      // target and sorts it, but never empties it.
      s.intersects.length = 0;
      s.raycaster.intersectObjects(s.meshes, false, s.intersects);
      const first = s.intersects[0];
      if (first) g = s.meshes.indexOf(first.object as THREE.Mesh);
    }
    if (g !== ghost) setGhost(g);
  }

  if (dirty.current) {
    dirty.current = false;
    s.renderer.render(s.scene, s.camera);
  }
}, ready && !unsupported);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The effect removes every disc from the scene and disposes its `ShaderMaterial`, disposes the one shared `PlaneGeometry`, then calls `disposeRenderer` — which stops the animation loop, disposes the renderer, calls `forceContextLoss()`, and zeroes the drawing buffer — and finally removes the canvas it appended. The canvas is created by the renderer inside the effect and never handed to React, so a StrictMode double-invoke rebuilds a fresh context rather than reusing a killed one. The frame loop unsubscribes with `useRaf`; the shared rAF parks once nothing is subscribed. The `ResizeObserver` unobserves with its hook.

**Reduced motion.** The ring holds still: the phase is integrated from delta time, so freezing it is a matter of adding nothing. The dirty flag is then only set by the pointer, which means the renderer draws zero frames until the pointer moves. Picking, hover growth and selection are unaffected — the technique is about where things are, not about them moving.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Reaching for `THREE.Raycaster` against a shader billboard. The vertex shader runs on the GPU; the `BufferGeometry` in main memory is an unrotated square lying in world XY. The raycast intersects that square and reports hits on a shape nobody can see — turn on `compare` and the two readouts disagree the moment the camera is not staring down the world Z axis.
- Using `Ray.distanceToPlane` and testing its result for null. It does return null at runtime for a plane behind the ray origin, but `@types/three` declares it as `number`, so the null check is a type error and removing the null check is a crash. `intersectPlane` has the honest `Vector3 | null` signature; use it.
- Approximating the disc as a screen-space circle whose NDC radius is `halfDiagonal / (tanHalfFov * camDist)`. That is only correct for a sphere. For a flat disc it over-reports near the edges of frame, where perspective stretches the footprint, so the hover boundary is visibly not the disc boundary. The plane intersection is exact for the same cost.
- Deriving the pick radius from a second constant. Hover growth then applies to the pixels but not the hit region, and the disc becomes clickable on a ring of its own body it has already grown past.
- Leaving `frustumCulled` on. The culler tests the geometry bounding sphere at the mesh transform, but the vertices are moved by the shader, so a disc vanishes the instant the untransformed square leaves the frustum.
- Allocating in the pick loop. `new THREE.Vector3()` per disc per frame is invisible in a profile and unmistakable in a GC trace; reuse a scratch object on the stage.
- Enabling depth test on the discs. They are square quads with the corners discarded, so the depth buffer records the quad, not the disc, and neighbouring rims punch holes in each other. Painter's-algorithm sorting is correct here because the billboard leaves the object position — the key three sorts on — untouched.
- Handing three's renderer a React-rendered `<canvas ref>`. StrictMode double-invokes the effect, the first cleanup calls `forceContextLoss()`, and the second run is given the same permanently dead element. Let the renderer make its own canvas inside the effect and remove it in cleanup.

## Notes

- The same reduction works for any primitive with a closed-form ray test: a sphere is `ray.intersectSphere`, an axis-aligned card is `ray.intersectBox`, a ground plane is one `intersectPlane`. Raycasting against triangles is the fallback for arbitrary meshes, not the default for known shapes.
- A square quad plus `discard` beats a `CircleGeometry` fan on both counts — two triangles instead of thirty-two, and a rim anti-aliased by a smoothstep instead of a polygon approximated by segments.
- The `compare` prop exists to be switched on once. Leave it on in production and you pay for the traversal you set out to avoid, plus an `intersectObjects` call whose result you throw away.

## Definition of done

Hover a disc at the front of the ring and it brightens and grows, and the readout says `plane hit NN`. Follow one disc as it travels to the back: it stays pickable over exactly its drawn silhouette, smaller but never offset. Set `compare` and hover a disc anywhere off the centre of frame — the `raycast` readout says something different, usually nothing, because it is testing an unrotated square in world XY. Click and the disc under the pointer takes the accent colour. With reduced motion the ring is static and every one of those behaviours still works.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Anti-Aliased Point Discs

A point sprite is a square; this is the pair of shader tricks that makes it a dot. The fragment shader carves a disc with one smoothstep across the outer few percent of the sprite and discards everything below a visibility threshold, and the vertex shader clamps the point size to the hardware floor and then divides the alpha by the area that clamp invented. The field is laid out as a phyllotaxis spiral with a size ramp so both ends of the problem — sub-pixel dots and twenty-pixel dots — are on screen at once.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A phyllotaxis field of dots that stay the same weight at every pixel ratio, with no MSAA and no texture.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. Dots are placed by golden-angle phyllotaxis: `t = sqrt((i + 0.5) / count)` for the normalised radius and `i * 137.507°` for the angle, so spacing is even rather than crowded at the centre. A seeded jitter of ±0.06 rad is added to break the moiré a pure spiral shows at small radii.
2. The vertex shader rotates differentially — `angle + uElapsed * uSpin * (0.6 + t)` — so the rim turns 1.6x faster than the core and the arms shear instead of the field spinning rigidly.
3. Point size ramps as `mix(uMinRadius, uMaxRadius, t * t)`, quadratic so most of the field stays small and the large discs are confined to the rim where the anti-aliasing is easiest to inspect.
4. The size is then clamped: `clamped = max(2.0, radius * 2.0 * uPixelRatio)` against `unclamped = max(1.0, …)`, and `vAlphaScale = unclamped² / clamped²` is passed to the fragment shader. A dot the driver forced to be twice as wide comes out four times fainter, so total emitted light is unchanged.
5. The fragment shader computes `d = length(gl_PointCoord - 0.5)` and `disc = 1.0 - smoothstep(uEdgeInner, 0.5, d)` where `uEdgeInner = 0.5 - softness`, so the falloff always ends exactly at the sprite edge and the disc stays inscribed in its square.
6. Anything whose final alpha lands below 0.003 is discarded rather than blended, which removes a framebuffer read-modify-write per pixel across the sparse outer field.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `GOLDEN_ANGLE = Math.PI * (3 - Math.sqrt(5)) ≈ 2.39996 rad`
  The only angle whose successive multiples never repeat a rational fraction of a turn. Any nearby value produces visible spokes within a few hundred points.
- `softness = 0.07`
  Anti-aliased band as a fraction of the sprite radius, giving `smoothstep(0.43, 0.5, d)`. Below ~0.05 a 2px dot aliases back into a square; above ~0.15 every dot reads as blurred rather than small.
- `MIN_POINT_SIZE = 2.0`
  Hardware floor in device pixels. Below roughly 1px most GPUs rasterise nothing, so the smallest dots would be absent on some machines and present on others.
- `ALPHA_EPSILON = 0.003`
  Discard threshold, just under 1/255. Anything fainter cannot be shown by an 8-bit framebuffer, so blending it is pure fill cost.
- `radius ramp exponent = t * t`
  Quadratic rather than linear. Linear puts mid-size discs everywhere and the field turns into a solid disc; quadratic keeps the interesting large sprites at the rim.
- `count = 4000`
  One buffer, one draw call, and about 4000 sprites of up to 20px — roughly the point where fill rate rather than vertex count starts to dominate on integrated graphics.
- `differential spin factor = (0.6 + 1.0 * t)`
  Rim-to-core angular speed ratio of 1.6. At 1.0 the field spins rigidly and reads as a rotating image; past ~2.5 the arms wind into a solid ring within a minute.

## API

```ts
function AntialiasedDiscFragment(props: { count?: number; minRadius?: number; maxRadius?: number; fieldRadius?: number; spin?: number; softness?: number; opacity?: number; colorInner?: string; colorOuter?: string; seed?: number | string; className?: string }): JSX.Element
```

- `count: number` — default `4000`
  Number of discs. One draw call regardless.
- `minRadius: number` — default `0.5`
  Disc radius in CSS pixels at the centre — deliberately sub-pixel at DPR 1.
- `maxRadius: number` — default `10`
  Disc radius in CSS pixels at the rim.
- `fieldRadius: number` — default `0.92`
  Field diameter as a fraction of the container short side.
- `spin: number` — default `0.08`
  Base angular speed in radians per second; the rim runs 1.6x faster.
- `softness: number` — default `0.07`
  Anti-aliased band width as a fraction of the sprite radius.
- `opacity: number` — default `1`
  Multiplier applied before the area compensation.
- `colorInner: string` — default `'#ffffff'`
  Tint at the centre of the field.
- `colorOuter: string` — default `'#6f7680'`
  Tint at the rim.
- `seed: number | string` — default `'antialiased-disc-fragment'`
  Seeds the angular jitter so the layout is stable across reloads and matches on the server.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function AntialiasedDiscFragment({
  count = 4000,
  minRadius = 0.5,
  maxRadius = 10,
  fieldRadius = 0.92,
  spin = 0.08,
  softness = 0.07,
  opacity = 1,
  colorInner = '#ffffff',
  colorOuter = '#6f7680',
  seed = 'antialiased-disc-fragment',
  className,
}: AntialiasedDiscFragmentProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  const { width, height } = useResizeObserver(host);
  const size = useRef({ width, height });
  size.current = { width, height };

  const reduced = useReducedMotion();
  const ready = width > 0 && height > 0;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    if (!hasWebGL()) {
      setUnsupported(true);
      return;
    }

    const renderer = new THREE.WebGLRenderer({ antialias: false, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setClearAlpha(0);

    const scene = new THREE.Scene();
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
    camera.position.z = 1;

    const rng = createRng(seed);
    const positions = new Float32Array(count * 3); // all zeros; the shader places them
    const disc = new Float32Array(count * 2);

    for (let i = 0; i < count; i += 1) {
      // sqrt spacing, not linear: linear spacing crowds the centre, which is
      // exactly where the sub-pixel dots are and where crowding is least
      // forgiving.
      const t = Math.sqrt((i + 0.5) / count);
      // A little seeded angular jitter breaks the moiré that a pure golden
      // spiral shows at small radii on a low-DPR screen.
      disc[i * 2] = t;
      disc[i * 2 + 1] = i * GOLDEN_ANGLE + (rng() - 0.5) * 0.12;
    }

    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
    geometry.setAttribute('aDisc', new THREE.BufferAttribute(disc, 2));

    const uniforms: Uniforms = {
      uElapsed: { value: 0 },
      uExtent: { value: 1 },
      uPixelRatio: { value: renderer.getPixelRatio() },
      uSpin: { value: spin },
      uFieldRadius: { value: fieldRadius },
      uMinRadius: { value: minRadius },
      uMaxRadius: { value: maxRadius },
      uOpacity: { value: opacity },
      uColorInner: { value: new THREE.Color(colorInner) },
      uColorOuter: { value: new THREE.Color(colorOuter) },
      // The band always ENDS at 0.5 — the sprite's own edge. Softening inward
      // keeps the disc inscribed in the sprite; softening outward would clip
      // the falloff square at the corners.
      uEdgeInner: { value: 0.5 - softness },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: ANTIALIASED_DISC_VERT,
      fragmentShader: ANTIALIASED_DISC_FRAG,
      uniforms,
      transparent: true,
      depthTest: false,
      depthWrite: false,
      // Additive would blow the overlapping core to white. Normal blending
      // with a discard keeps the density readable where the dots overlap.
      blending: THREE.NormalBlending,
    });

    const points = new THREE.Points(geometry, material);
    points.frustumCulled = false;
    scene.add(points);

    el.appendChild(renderer.domElement);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';

    const resize = (w: number, h: number) => {
      renderer.setSize(w, h, false);
      camera.left = -w / 2;
      camera.right = w / 2;
      camera.top = h / 2;
      camera.bottom = -h / 2;
      camera.updateProjectionMatrix();
      uniforms.uExtent.value = Math.min(w, h);
      // Re-read rather than assume: moving a window between a retina and a
      // non-retina display changes devicePixelRatio without changing the
      // canvas size, and a stale value breaks the whole compensation.
      uniforms.uPixelRatio.value = renderer.getPixelRatio();
    };

    const draw = (elapsed: number) => {
      uniforms.uElapsed.value = elapsed;
      renderer.render(scene, camera);
    };

    resize(size.current.width, size.current.height);
    stage.current = { resize, draw };
    draw(STATIC_ELAPSED);

    return () => {
      stage.current = null;
      disposeObject(scene);
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
  }, [
    ready,
    count,
    minRadius,
    maxRadius,
    fieldRadius,
    spin,
    softness,
    opacity,
    colorInner,
    colorOuter,
    seed,
  ]);

  useEffect(() => {
    stage.current?.resize(width, height);
    if (reduced) stage.current?.draw(STATIC_ELAPSED);
  }, [width, height, reduced]);

  useRaf((_dt, elapsed) => stage.current?.draw(elapsed), ready && !reduced && !unsupported);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nulls the stage ref, disposes the geometry and material via `disposeObject` plus an explicit `material.dispose()`, calls `disposeRenderer` for `dispose` + `forceContextLoss` + a zeroed drawing buffer, then removes the canvas. `useRaf` releases the frame subscription itself.

**Reduced motion.** No rAF subscription is opened. A single frame is drawn at `uElapsed = 6`, which is far enough into the rotation that the arms are already sheared, so the composition is the interesting one rather than the unrotated starting pose. The field is fully visible; only the spin stops.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Softening the disc outward from 0.5 instead of inward to it. The sprite has no pixels past 0.5, so the outer half of the falloff is clipped by the sprite boundary and the dot shows four square corners.
- Clamping `gl_PointSize` and leaving the alpha alone. The clamp does nothing at DPR 3 and doubles the covered area at DPR 1, so the identical component looks twice as heavy on a non-retina monitor — a bug that is invisible on the machine most people develop on.
- Caching the pixel ratio at construction. Dragging the window from a retina to a non-retina display changes `devicePixelRatio` without changing the canvas size, so the compensation silently goes stale; it is re-read on every resize.
- Reaching for `antialias: true` when the dots look jagged. MSAA allocates a multisample buffer the size of the canvas and does not help a point sprite whose edge is defined by alpha — the smoothstep is the fix.
- Blending fully transparent fragments instead of discarding them. At 4000 sprites with a 20px radius the outer field is mostly empty pixels, and each one still costs a read-modify-write of the framebuffer.
- Linear radial spacing instead of `sqrt`. It crowds the centre, which is precisely where the sub-pixel dots live, and the core turns into an undifferentiated smear.

## Notes

- The camera is orthographic and 1:1 with CSS pixels, so `uMinRadius` and `uMaxRadius` are literal pixel radii rather than scene units.
- The same two tricks apply to any `THREE.Points` material. The spiral is only a way to show the whole size range at once.

## Definition of done

A spiral of dots that grows from barely-visible at the centre to clearly round discs at the rim, with soft edges and no square corners at any size. Zoom the browser between 100% and 200% and the field keeps the same apparent weight instead of getting denser or lighter. Nothing shimmers along the arms as they turn. With reduced motion the spiral renders in full and holds still.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Asymmetric In/Out Staggers

A list whose entrance and exit are deliberately different animations. In: 24px up, 0.5s each, 0.06s apart, after a 0.25s hold that lets the outgoing view clear. Out: 16px up, 0.3s each, 0.03s apart, running from the last item back to the first. The exit is roughly half the total time of the entrance, which is what makes a view swap feel responsive without making the arrival feel rushed.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A list that arrives item by item after a hold and leaves twice as fast, from the last row backwards.

- Category: transition
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. Every direct child is wrapped in a `[data-stagger-item]` div, so the caller writes ordinary list markup and the component owns the animated node — no cloneElement, no required ref forwarding.
2. Entering runs `gsap.fromTo(items, { autoAlpha: 0, y: 24 }, { autoAlpha: 1, y: 0, duration: 0.5, ease: "power2.out", stagger: 0.06, delay: 0.25 })`. The delay is not decoration: it is the window in which whatever this list replaces finishes leaving.
3. Leaving runs `gsap.to(items, { autoAlpha: 0, y: -16, duration: 0.3, ease: "power2.in", stagger: { each: 0.03, from: "end" } })`. Halving the stagger and reversing its origin is what stops the exit from reading as the entrance rewound.
4. `autoAlpha` rather than `opacity`: at zero it also writes `visibility: hidden`, so a faded row cannot swallow a click aimed at the view underneath it.
5. Both tweens carry `overwrite: "auto"`, and the whole thing lives in a `useGsap` context keyed on `show`, so toggling twice in quick succession cancels the in-flight direction instead of layering two opposing tweens on the same nodes.
6. A layout effect hides the items before first paint when the component mounts closed, and an internal `hasShown` flag makes sure `onExited` can only fire after a real entrance.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `inStagger = 0.06`
  Seconds between arriving items. Below ~0.04 a five-item list reads as one block; above ~0.1 the last row lands well after the eye has moved on and the list feels slow to load.
- `outStagger = 0.03`
  Half the entrance value. Exits are acknowledgement, not presentation — the wave still reads as a direction, but the whole list is gone in under 200ms.
- `inDelay = 0.25`
  Seconds of hold before the first item arrives. Sized to the outgoing view's own fade (~0.3-0.4s) so the two never overlap; at 0 both views are half-opaque at the same time and the frame looks like a rendering bug.
- `inDuration / outDuration = 0.5 / 0.3`
  Per-item. The exit is shorter for the same reason its stagger is: nobody is reading rows that are leaving.
- `inDistance / outDistance = 24 / 16`
  Pixels. The entrance comes up from below (from where the content is arriving); the exit continues upward and travels less, because a long exit path is time spent watching nothing.
- `stagger.from = 'end'`
  Reverses the exit wave. Same-direction staggers make the exit look like a backwards entrance; from the end it looks like the list is being pulled off the screen.

## API

```ts
function AsymmetricStagger(props: { children: ReactNode; show: boolean; inStagger?: number; outStagger?: number; inDelay?: number; inDuration?: number; outDuration?: number; inDistance?: number; outDistance?: number; onExited?: () => void; className?: string; itemClassName?: string }): JSX.Element
```

- `children: ReactNode`
  List items. Each direct child is wrapped and animated on its own.
- `show: boolean`
  True enters, false exits. The component stays mounted through both.
- `inStagger: number` — default `0.06`
  Seconds between entering items.
- `outStagger: number` — default `0.03`
  Seconds between leaving items.
- `inDelay: number` — default `0.25`
  Hold before the entrance, sized to the outgoing view.
- `inDuration: number` — default `0.5`
  Per-item entrance length in seconds.
- `outDuration: number` — default `0.3`
  Per-item exit length in seconds.
- `inDistance: number` — default `24`
  Pixels travelled on the way in.
- `outDistance: number` — default `16`
  Pixels travelled on the way out.
- `onExited: () => void`
  Called once the last item has left. Safe place to unmount the data.
- `className: string`
  Merged onto the flex column wrapper.
- `itemClassName: string`
  Merged onto every generated item wrapper.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function AsymmetricStagger({
  children,
  show,
  inStagger = 0.06,
  outStagger = 0.03,
  inDelay = 0.25,
  inDuration = 0.5,
  outDuration = 0.3,
  inDistance = 24,
  outDistance = 16,
  onExited,
  className,
  itemClassName,
}: AsymmetricStaggerProps) {
  const root = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();

  const exited = useRef(onExited);
  exited.current = onExited;

  const startedHidden = useRef(!show);
  /* An exit only makes sense after an entrance. Without this, mounting with
     `show={false}` plays an invisible exit and fires `onExited` — and under
     StrictMode the double-invoked effect fires it a second time. */
  const hasShown = useRef(show);

  // Before paint, not after. A passive effect can land on the far side of the
  // first frame, so a list that starts closed would flash its items once.
  useLayoutEffect(() => {
    const el = root.current;
    if (!el || !startedHidden.current) return;
    gsap.set(el.querySelectorAll('[data-stagger-item]'), { autoAlpha: 0 });
  }, []);

  useGsap(
    gsap,
    () => {
      const el = root.current;
      if (!el) return;
      const items = Array.from(el.querySelectorAll<HTMLElement>('[data-stagger-item]'));
      if (items.length === 0) return;

      if (!show && !hasShown.current) return;

      if (reduced) {
        // No travel and no stagger, but the state change still has to happen
        // or the list is stuck in whichever position it was left in.
        gsap.set(items, { autoAlpha: show ? 1 : 0, y: 0 });
        if (show) hasShown.current = true;
        else exited.current?.();
        return;
      }

      if (show) {
        hasShown.current = true;
        // autoAlpha, not opacity: at 0 it also sets visibility:hidden, so a
        // faded-out row cannot still swallow a click meant for what is
        // underneath it.
        gsap.fromTo(
          items,
          { autoAlpha: 0, y: inDistance },
          {
            autoAlpha: 1,
            y: 0,
            duration: inDuration,
            ease: 'power2.out',
            stagger: inStagger,
            delay: inDelay,
            overwrite: 'auto',
          },
        );
        return;
      }

      gsap.to(items, {
        autoAlpha: 0,
        y: -outDistance,
        duration: outDuration,
        ease: 'power2.in',
        // `from: 'end'` reverses the wave. Same-direction staggers on the way
        // out read as the list re-entering backwards.
        stagger: { each: outStagger, from: 'end' },
        overwrite: 'auto',
        onComplete: () => exited.current?.(),
      });
    },
    root,
    [show, reduced],
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useGsap` reverts the context on unmount and on every `show` change, killing both tweens and restoring the inline styles GSAP wrote. `onExited` is held in a ref so a completion callback cannot reach a stale closure after the parent has re-rendered.

**Reduced motion.** No travel and no stagger. Items are set to their visible or hidden state in one `gsap.set`, and `onExited` still fires, so the surrounding state machine behaves identically — only the choreography is dropped.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Reusing the entrance timeline with `reverse()`. That gives you power2.out played backwards (so it decelerates into nothing), the entrance delay stranded at the end, and the same stagger direction — three separate reasons the exit feels heavy.
- Unmounting the list when `show` flips false. React removes the nodes on the same frame, so the exit never runs; the component stays mounted and reports completion through `onExited`.
- Animating `opacity` alone. A finished row sits at opacity 0 with full hit area and eats clicks intended for the view underneath. `autoAlpha` writes `visibility: hidden` at zero.
- Omitting `overwrite: "auto"`. Toggling twice inside 300ms leaves the entrance tween running under the exit tween, and the rows settle at whatever opacity the two happen to agree on.
- Setting the initial hidden state in a passive effect. Mounting with `show={false}` paints the list once, then hides it — a visible flash of content that was never meant to be seen. It is set in `useLayoutEffect` instead.
- Firing `onExited` on mount. With `show={false}` at mount there is nothing to exit, and under StrictMode the double-invoked effect would call it twice; a `hasShown` flag gates it.

## Notes

- The same numbers apply outside lists — modals, drawers, route content. Any pair of entrance/exit values that are equal is worth questioning.
- App Router wiring: drive `show` from a pathname comparison in a layout, and do the actual `router.push` from `onExited` if you want the route to change only once the list has gone.

## Definition of done

Switch to the list: the previous view fades, a quarter-second of nothing, then rows arrive top to bottom. Switch back: the bottom row leaves first and the whole list is gone in about half the time it took to arrive. Toggle rapidly and rows never settle at a partial opacity.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Asymmetric Typewriter

A phrase erases itself and a new one is typed in its place, cycling forever. Deleting runs at exactly half the interval of typing, because backspacing is a held key with a mechanical auto-repeat while typing is composition — give both phases the same interval and the result reads as a ticker tape rather than as somebody at a keyboard. A quarter-second pause at the empty string turns the turnaround from a dropped frame into a decision.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Rotating phrases that delete at twice the speed they type, with a beat of nothing at the empty string.

- Category: text
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. Timing is a chain of `setTimeout` calls, not a `setInterval`: the four phases (type, hold, delete, empty) each have their own interval, and the boundaries between them are pauses that a fixed interval cannot express without a counter and a modulo.
2. The state machine is four closures over a `text` local — `type` slices one more character off the target and reschedules at `typeMs`; on reaching full length it schedules `beginErase` at `holdMs`. `erase` slices one character off and reschedules at `deleteMs`; at length zero it schedules `advance` at `emptyMs`. `advance` moves the phrase index modulo the list length and re-enters `type`.
3. Typing slices the *target* string (`target.slice(0, text.length + 1)`) rather than concatenating a looked-up character. Under `noUncheckedIndexedAccess` an index read is `string | undefined`, and slicing also means the visible text can never desync from the source phrase.
4. A single `timer` ref holds the one outstanding timeout id, so cleanup is a single `clearTimeout` regardless of which phase was in flight.
5. The effect is keyed on `phrases.join("\u0000")` rather than on the array itself. An array prop is a fresh reference every parent render, which would tear the machine down and restart it, pinning the typewriter to its first character forever. NUL is the delimiter because real phrases contain spaces and commas.
6. The caret is the `step-end-caret` component, driven with `paused={busy}`: while characters are being added or removed the caret holds solid, and it resumes blinking only during the hold and empty beats.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `TYPE_MS = 70`
  Milliseconds per character while typing. Around 14 characters a second — brisk human typing. Below ~45ms the reader cannot follow the word forming; above ~110ms the phrase takes longer to appear than anyone will wait for.
- `DELETE_MS = 35`
  Exactly half of `TYPE_MS`. This ratio is the whole component: deleting is a held key on auto-repeat, typing is composition. Equal intervals make both directions read as machine output.
- `HOLD_MS = 1500`
  How long a completed phrase stays up. It has to exceed the time to read four or five words. Under ~900ms the phrase is gone before it has been parsed and the component reads as flickering.
- `EMPTY_MS = 250`
  The beat at zero characters. Without it the string bottoms out and immediately rebounds, which the eye reads as a dropped frame rather than as a turnaround.
- `START_DELAY_MS = 1500`
  Longer than a normal hold, so the first phrase is legible while the rest of the page is still settling. Starting the erase immediately makes the component look like it is correcting a mistake.

## API

```ts
function AsymmetricTypewriter(props: { phrases: string[]; typeMs?: number; deleteMs?: number; holdMs?: number; emptyMs?: number; startDelayMs?: number; caret?: boolean; className?: string }): JSX.Element
```

- `phrases: string[]`
  Cycled in order, forever. Index 0 is also the server-rendered string.
- `typeMs: number` — default `70`
  Milliseconds between characters while typing.
- `deleteMs: number` — default `35`
  Milliseconds between characters while deleting.
- `holdMs: number` — default `1500`
  Milliseconds a completed phrase is held.
- `emptyMs: number` — default `250`
  Milliseconds held at the empty string.
- `startDelayMs: number` — default `1500`
  Milliseconds before the very first deletion.
- `caret: boolean` — default `true`
  Render the blinking caret after the text.
- `className: string`
  Merged onto the outer span via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const TYPE_MS = 70;
const DELETE_MS = 35;
const HOLD_MS = 1500;
const EMPTY_MS = 250;
const START_DELAY_MS = 1500;

export function AsymmetricTypewriter({
  phrases,
  typeMs = TYPE_MS,
  deleteMs = DELETE_MS,
  holdMs = HOLD_MS,
  emptyMs = EMPTY_MS,
  startDelayMs = START_DELAY_MS,
  caret = true,
  className,
}: AsymmetricTypewriterProps) {
  const reduced = useReducedMotion();

  // An array prop is a fresh reference on every parent render. Keying on the
  // joined string is what stops the effect tearing down and restarting each
  // time — which would pin the typewriter to its first character forever.
  // NUL is the delimiter because real phrases contain spaces and commas, and
  // a separator that occurs in the data silently splits one phrase into two.
  const key = phrases.join('\u0000');
  const list = useMemo(() => key.split('\u0000'), [key]);

  const [shown, setShown] = useState(() => list[0] ?? '');
  const [busy, setBusy] = useState(false);
  const timer = useRef(0);

  useEffect(() => {
    const first = list[0] ?? '';
    if (reduced || list.length < 2) {
      setShown(first);
      setBusy(false);
      return;
    }

    let index = 0;
    let text = first;
    setShown(text);

    const at = (fn: () => void, ms: number) => {
      timer.current = window.setTimeout(fn, ms);
    };

    const erase = () => {
      if (text.length === 0) {
        // The beat. Caret goes back to blinking because nothing is happening.
        setBusy(false);
        at(advance, emptyMs);
        return;
      }
      text = text.slice(0, -1);
      setShown(text);
      at(erase, deleteMs);
    };

    const advance = () => {
      index = (index + 1) % list.length;
      setBusy(true);
      at(type, typeMs);
    };

    const type = () => {
      const target = list[index] ?? '';
      if (text.length >= target.length) {
        setBusy(false);
        at(beginErase, holdMs);
        return;
      }
      // Slice the target rather than concatenating a looked-up character:
      // `target[i]` is `string | undefined` and the slice cannot desync from
      // the source string if the phrase list changes underneath.
      text = target.slice(0, text.length + 1);
      setShown(text);
      at(type, typeMs);
    };

    const beginErase = () => {
      setBusy(true);
      erase();
    };

    at(beginErase, startDelayMs);

    return () => {
      window.clearTimeout(timer.current);
    };
  }, [list, reduced, typeMs, deleteMs, holdMs, emptyMs, startDelayMs]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** A single `window.clearTimeout(timer.current)` in the effect teardown. Only one timeout is ever outstanding, so no phase can survive unmount and call `setState` on a dead component.

**Reduced motion.** The machine never starts. The first phrase is rendered in full and stays — the final text state, immediately, rather than an empty slot or a sped-up cycle. The caret is still rendered but its own reduced-motion rule holds it solid.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Driving the whole cycle from one `setInterval`. Hold and empty pauses then have to be faked with a frame counter, and every change to a phase length becomes an arithmetic edit rather than a constant.
- Depending on the `phrases` array identity in the effect. Every parent render gives a new array, the effect restarts, and the typewriter is stuck showing the first character of the first phrase.
- Joining phrases with a comma or a pipe as the effect key. Both occur in real copy, so one phrase silently becomes two.
- Letting the element size itself from the current string. It grows and shrinks by tens of pixels several times a second and drags every neighbouring element with it — a transparent copy of the longest phrase reserves the box instead.
- Using normal whitespace collapsing. A phrase erased back to "Product " loses its trailing space, so the caret jumps one character left and then right again on the next tick.
- Blinking the caret while characters are being typed. Real cursors hold solid during input; a caret blinking mid-word makes the text look like it is being deleted by something else.

## Notes

- No text-splitting library is involved: the component owns a single string in React state and never mutates the DOM. Adding a split dependency here would buy nothing, since there are no per-character targets to animate.
- React state at ~14 updates a second is a deliberate tradeoff. The subtree is one span, and holding the string in state is what keeps the server-rendered first phrase and the client in agreement.
- A list of fewer than two phrases renders the first one statically and never starts the machine.

## Definition of done

Watch one full cycle: the phrase erases visibly faster than the next one types — time it and the ratio is 2:1. At the empty string there is a perceptible pause before the next phrase starts. The caret holds solid while characters move and blinks while the phrase is held. Nothing to the right of the component moves at any point during the cycle. With reduced motion enabled the first phrase is present on first paint and never changes.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Auto-Advance Filmstrip

Panels are a fixed number of container-width units wide and the whole track is one `translateX`. The active panel sits centred, its neighbours are dimmed and scaled down, and the strip steps every few seconds until you touch it. All motion is a CSS transition on a value React already recomputes when the index changes — there is no tween and no animation loop.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A centred strip that steps one panel every few seconds, neighbours dimmed and shrunk, on one CSS transition.

- Category: layout
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. Every panel is `W` container-width units wide (`width: 46cqw`) and the track is translated to `(100 - W) / 2 - W * index` of the same unit. The first term centres one panel — `(100 - 46) / 2 = 27` — and the second steps exactly one panel per index. It is one expression with no measurement and no resize handler, because both terms are already relative to the container.
2. `cqw` rather than `vw`: the strip is sized against its own container, so it stays centred inside a card, a modal or a split layout instead of only when it happens to be full-bleed. The root sets `container-type: inline-size` to establish that container.
3. The transition is `transform 500ms cubic-bezier(0.22, 1, 0.36, 1)` on the track. For a component where React already re-renders on index change, a CSS transition is fewer moving parts than a tween and it interpolates on the compositor.
4. Inactive panels get `opacity: 0.35` **and** `scale(0.8)`, transitioning on the same curve and duration as the track so the three properties land together.
5. Auto-advance is `setTimeout` re-armed on every index change, not `setInterval`. Manual navigation therefore restarts the dwell rather than inheriting whatever was left of the current tick.
6. The timer is gated on four conditions — `autoPlay`, not reduced-motion, `document.visibilityState === "visible"`, and not currently hovered or focused within — so it never advances behind the user's back or in a background tab.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `panelWidth = 46`
  Panel width in `cqw`. Under 50 means two neighbours are partly visible, which is what makes it a filmstrip rather than a slideshow. At 46 the centred panel leaves 27 units of peek on each side — enough to read the neighbour as a real panel, not a sliver.
- `interval = 3000`
  Milliseconds per panel. Below ~2500 a caption cannot be read before it leaves; above ~5000 the strip looks broken rather than paced on a page where nothing else is moving.
- `duration = 500`
  Slide transition. Roughly a sixth of the dwell, which keeps the strip reading as a series of held frames with a transition between them rather than as continuous motion.
- `EASE = cubic-bezier(0.22, 1, 0.36, 1)`
  Expo-out. It covers about 80% of the distance in the first 30% of the duration, so the strip appears to arrive early and settle — the same reason it is the default curve for interface movement that should feel decided rather than mechanical.
- `inactiveOpacity / inactiveScale = 0.35 / 0.8`
  Both, together. 0.35 alone reads as a loading state; 0.8 alone reads as a layout bug. Applied together they read as depth, which is the only interpretation a viewer will land on.

## API

```ts
function AutoAdvanceFilmstrip(props: { children: ReactNode; panelWidth?: number; interval?: number; duration?: number; autoPlay?: boolean; inactiveOpacity?: number; inactiveScale?: number; className?: string; panelClassName?: string; 'aria-label'?: string }): JSX.Element
```

- `children: ReactNode`
  One panel per child.
- `panelWidth: number` — default `46`
  Panel width in container-width units (`cqw`).
- `interval: number` — default `3000`
  Milliseconds a panel is held before the strip advances.
- `duration: number` — default `500`
  Slide transition duration in milliseconds.
- `autoPlay: boolean` — default `true`
  Whether the strip advances on its own.
- `inactiveOpacity: number` — default `0.35`
  Opacity applied to every panel that is not active.
- `inactiveScale: number` — default `0.8`
  Scale applied to every panel that is not active.
- `className: string`
  Merged onto the root, which is also the query container.
- `panelClassName: string`
  Merged onto each panel cell.
- `aria-label: string` — default `'Filmstrip'`
  Label for the carousel group.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
// (100 - W) / 2 centres a panel of width W; W * index steps one panel per
// index. Both terms are in the same unit as the panel width, so the strip
// stays centred at every container size with no measurement at all.
const offset = (100 - panelWidth) / 2 - panelWidth * index;

const running = autoPlay && !reduced && visible && !held && count > 1;

useEffect(() => {
  if (!running) return;
  // setTimeout keyed on `index`, not setInterval: any manual navigation
  // re-arms a full dwell. With an interval, tapping "next" one tick before
  // it fires advances twice in a row.
  const id = window.setTimeout(() => {
    setIndex((current) => wrapIndex(current + 1, count));
  }, interval);
  return () => window.clearTimeout(id);
}, [running, index, interval, count]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The pending `setTimeout` is cleared by the effect's own teardown, which also runs on every index change and whenever the strip pauses. `useVisibility` and `useReducedMotion` unsubscribe their listeners. There is nothing else to release: all motion is CSS on nodes React owns.

**Reduced motion.** Auto-advance never starts, so nothing moves unless the user presses a control. When they do, `transition` is set to `none` on both the track and the panels, so the strip cuts to the new panel in one frame instead of sliding. The dot pager and arrows behave identically; only the interpolation is gone.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Using a percentage in the track's `translateX`. Percentages on `transform` resolve against the *element's own* width, and the track is as wide as all its panels — so `translateX(-46%)` moves it by 46% of the whole strip, not of one panel. The arithmetic only works in a unit that refers to the container: `cqw` here, `vw` if the strip is genuinely full-bleed.
- Using `setInterval` for the auto-advance. Tap "next" a hundred milliseconds before the tick fires and the strip advances twice; the second jump has no cause the user can see. A `setTimeout` keyed on the index gives every panel a full dwell.
- Leaving the timer running while the tab is hidden. The user comes back to a strip that has silently walked eleven panels forward, and every intervening transition ran on a throttled timer.
- Not pausing on hover or focus. A pointer resting on a panel and a keyboard user tabbing into a control both mean "I am reading this"; advancing underneath either one is the single most common complaint about auto-advancing carousels.
- Only setting `containerType` on an ancestor that has no definite inline size. `cqw` then resolves against the viewport-sized fallback and the arithmetic silently reverts to the `vw` behaviour it was meant to replace.
- Fading inactive panels to `opacity: 0`. They are still in the layout and still hit-testable, so a click intended for the active panel can land on an invisible neighbour that happens to be under the cursor.

## Notes

- Cheapest of the three carousels here and the right default when the set is short and each panel needs a moment on screen. Unlike `wrapping-drum-carousel` it does not wrap continuously — it jumps from the last index back to the first, and that jump is a full-width slide, which is visible. Keep the set small enough that the loop point is rare.
- Every panel stays mounted and in the layout at all times. For twenty panels that is twenty subtrees painting; virtualise or switch technique past roughly a dozen.

## Definition of done

The strip steps one panel roughly every three seconds with the neighbours visible, dimmed and smaller on both sides. Hovering anywhere over it stops the advance and moving away resumes it with a full dwell. Switch tabs for ten seconds and come back: it is on the panel it was on, not ten further along. Resize the container from 320 px to full width and the active panel stays exactly centred.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Banded Scrollspy Rail

A section rail that never flickers, because only one section can be "active" at a time by construction. The IntersectionObserver root is shrunk to a 7%-tall band across the middle of the scroller, so a section registers only while it crosses that line. The active tick grows from 16 to 32 pixels — a size change, legible in peripheral vision, rather than a tint change that is not. No animation library: one observer, one CSS width transition.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A tick rail whose active mark widens as a section crosses a 7% band through the middle of the screen.

- Category: scroll
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. One IntersectionObserver watches every `[data-scrollspy]` element with `rootMargin: "-38% 0px -55% 0px"`. Trimming 38% off the top and 55% off the bottom leaves a 7%-tall detection band (100 − 38 − 55), positioned just below centre so a section becomes active while you are reading it rather than while it is still arriving.
2. Entries maintain a `Set` of ids currently inside the band. The active id is resolved by scanning the authored `sections` order for the first member of that set — not by reading `entries[0]`, whose order depends on how the observer batched the callback and therefore on scroll direction.
3. When the set is empty — a gap between sections, or a header taller than the band — the previous answer is held rather than cleared, so the rail never blanks between sections.
4. A second observer watches the element named by `endId` with `rootMargin: "0px 0px -25% 0px"`, which makes "intersecting" mean exactly "its top has climbed above 75% of the root". That retires the whole rail, so it is not hovering over a footer with nothing left to navigate.
5. The indicator itself is a `<span>` whose inline `width` flips between 16 and 32 px with a 260 ms CSS transition. The only JavaScript per scroll event is a `Set` mutation and at most one `setState`.
6. Section elements are collected into an id → element `Map` by walking the attribute once, rather than running a `[data-scrollspy="id"]` selector per section — that form needs escaping for any id containing punctuation and silently matches nothing when the escaping is wrong.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `bandTop / bandBottom = 38 / 55`
  Leaves a 7% band. Widen it and two sections are inside at once on a tall screen, which is the flicker this design exists to remove. Narrow it below about 4% and a fast flick can jump the band entirely between two observer callbacks, leaving the rail on the previous section. The asymmetry (38 vs 55) puts the band below centre, where the eye is while reading.
- `ACTIVE_WIDTH / IDLE_WIDTH = 32 / 16`
  A 2x length change is detectable without looking directly at it. Equal widths with only a colour change is invisible in peripheral vision, which defeats the point of a rail you are not supposed to be looking at.
- `TRANSITION_MS = 260`
  Long enough that the width change reads as movement and draws the eye, short enough that it has finished before the next section can reach the band during normal scrolling.
- `hideAt = 0.75`
  Fraction of the root the end marker must pass before the rail retires. At 1.0 the rail is still on screen while the footer is being read; below about 0.6 it disappears while the last section is still active.

## API

```ts
function BandedScrollspyRail(props: { sections: { id: string; label: string }[]; rootRef?: RefObject<HTMLElement | null>; bandTop?: number; bandBottom?: number; endId?: string; hideAt?: number; attribute?: string; onActiveChange?: (id: string | null) => void; className?: string }): JSX.Element
```

- `sections: { id: string; label: string }[]`
  Ordered list. Each `id` must match a `data-scrollspy` attribute inside the root.
- `rootRef: RefObject<HTMLElement | null>`
  The scroll container holding the sections. Omit for the document.
- `bandTop: number` — default `38`
  Percent of the root trimmed from the top to form the band.
- `bandBottom: number` — default `55`
  Percent trimmed from the bottom. The two must sum to under 100.
- `endId: string`
  Section after which the rail retires. Usually the footer.
- `hideAt: number` — default `0.75`
  Fraction down the root the end marker must pass before the rail hides.
- `attribute: string` — default `'data-scrollspy'`
  Attribute used to find sections inside the root.
- `onActiveChange: (id: string | null) => void`
  Fires once per active-section change. Held in a ref, so it needs no memo.
- `className: string`
  Merged onto the nav element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const ACTIVE_WIDTH = 32;
const IDLE_WIDTH = 16;
const TRANSITION_MS = 260;

export function BandedScrollspyRail({
  sections,
  rootRef,
  bandTop = 38,
  bandBottom = 55,
  endId,
  hideAt = 0.75,
  attribute = 'data-scrollspy',
  onActiveChange,
  className,
}: BandedScrollspyRailProps) {
  const [active, setActive] = useState<string | null>(null);
  const [retired, setRetired] = useState(false);
  const [expanded, setExpanded] = useState(false);
  const reduced = useReducedMotion();

  // Held in refs so a new array literal or a fresh callback on every parent
  // render does not tear down and rebuild the observers.
  const sectionsRef = useRef(sections);
  sectionsRef.current = sections;
  const notify = useRef(onActiveChange);
  notify.current = onActiveChange;

  const order = sections.map((s) => s.id).join('|');

  useEffect(() => {
    const root = rootRef?.current ?? null;
    const scope: ParentNode = root ?? document;

    // Build id -> element by walking the attribute once, rather than running a
    // `[attr="id"]` selector per section: that needs escaping for any id with
    // punctuation in it, and silently matches nothing when the escaping is
    // wrong.
    const elements = new Map<string, Element>();
    for (const el of Array.from(scope.querySelectorAll(`[${attribute}]`))) {
      const id = el.getAttribute(attribute);
      if (id) elements.set(id, el);
    }
    if (elements.size === 0) return;

    const inBand = new Set<string>();

    const observer = new IntersectionObserver(
      (entries) => {
        for (const entry of entries) {
          const id = entry.target.getAttribute(attribute);
          if (!id) continue;
          if (entry.isIntersecting) inBand.add(id);
          else inBand.delete(id);
        }

        // Resolve in authored order, not entry order: callbacks arrive in
        // whatever order the observer batched them, so picking `entries[0]`
        // makes the active section depend on scroll direction.
        const next = sectionsRef.current.find((s) => inBand.has(s.id))?.id;

        // Nothing in the band — a gap between sections, or a header taller
        // than the band. Hold the last answer instead of blanking the rail,
        // which would read as the nav breaking.
        if (next === undefined) return;

        setActive((prev) => {
          if (prev === next) return prev;
          notify.current?.(next);
          return next;
        });
      },
      {
        root,
        // The band. 100 - bandTop - bandBottom percent of the root's height,
        // centred low enough that a section is "active" while you are reading
        // it rather than while it is still arriving.
        rootMargin: `-${bandTop}% 0px -${bandBottom}% 0px`,
        threshold: 0,
      },
    );

    for (const el of elements.values()) observer.observe(el);

    // Second observer: retire the rail once the end marker has climbed past
    // `hideAt`, so it is not hovering over a footer with nothing left to
    // navigate. Shrinking the bottom margin by (1 - hideAt) makes
    // "intersecting" mean exactly "its top is above hideAt of the root".
    let endObserver: IntersectionObserver | null = null;
    const endEl = endId === undefined ? undefined : elements.get(endId);
    if (endEl) {
      endObserver = new IntersectionObserver(
        (entries) => {
          const entry = entries[entries.length - 1];
          if (entry) setRetired(entry.isIntersecting);
        },
        { root, rootMargin: `0px 0px -${Math.round((1 - hideAt) * 100)}% 0px`, threshold: 0 },
      );
      endObserver.observe(endEl);
    }

    return () => {
      observer.disconnect();
      endObserver?.disconnect();
    };
  }, [rootRef, attribute, bandTop, bandBottom, endId, hideAt, order]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Both IntersectionObservers are disconnected on unmount and on any option change. An observer holds a strong reference to every element it watches, so skipping this pins the unmounted section tree in memory and keeps firing `setState` on a dead component.

**Reduced motion.** The rail still tracks the active section and still changes width — that is state, not decoration. Every `transition` is set to `none`, so the tick snaps between widths and the labels appear instantly, and click-to-navigate uses `behavior: "auto"` rather than a smooth scroll.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Observing with the default full-height root. Three sections intersect at once on a tall screen and the active tick flickers between them on every callback. Debouncing hides the symptom and adds lag; shrinking the root removes the ambiguity.
- Taking the active section from `entries[0]`. The callback batches entries in an order that depends on which boundaries were crossed, so the same scroll direction can yield a different winner between two frames. Resolve against the authored order instead.
- Clearing the active state when nothing is intersecting. Any gap taller than the band — a spacer, a full-bleed image, a header — blanks the rail mid-scroll and it reads as broken.
- Signalling the active section with colour only. On a hairline tick in the corner of the eye a tint change is imperceptible; a width change is not, and it also survives a monochrome or high-contrast rendering.
- Rebuilding the observers on every render. `sections` is usually a fresh array literal from the parent, so keying the effect on it disconnects and reconnects two observers on every keystroke elsewhere in the page. Key on the joined id list and read the array from a ref.
- Forgetting `observer.disconnect()`. IntersectionObserver keeps a strong reference to every observed element, so an undisconnected observer pins the whole unmounted section tree in memory and keeps calling `setState` on a dead component.
- Scrolling with `window.scrollTo` on click when the sections live in a container. `scrollIntoView` walks up and scrolls whichever ancestor actually holds the overflow, which is the only version that works in both cases.

## Notes

- No GSAP and no ScrollTrigger: the whole component is two IntersectionObservers and a CSS transition, which is why it is classed `css` cost and can be used dozens of times on a page.
- The labels are always in the DOM at `opacity: 0` and reveal on hover or keyboard focus, so the rail is operable and readable without a pointer.

## Definition of done

Scroll slowly: the active tick changes exactly once as each section crosses the middle of the screen, with no flicker at the boundary and no blank state in the gaps. The active tick is visibly twice as long as the others. Scroll to the end and the whole rail fades out. Hover it and the labels appear; tab into it and they appear too. With reduced motion on, the tick still moves but snaps rather than eases.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Batched Blur Reveal

A page-wide entrance that reveals elements in groups rather than one at a time. Everything that crosses the start line inside the same 100 ms window is handed to one tween, so a real stagger runs across a row of cards that entered simultaneously. Opacity, rise, scale and blur move together, which reads as the content focusing rather than sliding.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Cards that enter together focus in as one staggered group instead of arriving as a slab.

- Category: scroll
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. On mount, every `[data-reveal]` descendant of the container — queried from the container element, never from `document` — is set to `{ opacity: 0, y: 90, scale: 0.94, filter: "blur(12px)" }` plus a `will-change` hint for transform, filter and opacity.
2. `ScrollTrigger.batch(targets, { start: "top 88%", interval: 0.1, batchMax: 6 })` replaces the usual one-trigger-per-element loop. Elements that cross the start line within `interval` seconds of each other are collected and delivered to `onEnter` as a single array.
3. That array is animated by one `gsap.to` with `stagger: 0.14`, so the offset is computed across the whole group. Individual triggers cannot do this: each one starts at its own t=0 and knows nothing about its neighbours.
4. The tween carries `overwrite: true` so a fast flick that re-enters an element mid-reveal restarts it cleanly instead of interpolating from a half-finished state.
5. `onComplete` calls `gsap.set(batch, { clearProps: "filter,willChange" })`. A `filter` that survives the animation keeps the node on its own composited layer for the life of the page, which is exactly the cost the reveal was supposed to pay once.
6. Under `prefers-reduced-motion`, no trigger is created at all: the targets are `gsap.set` to their final values and the content is already correct on first paint.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `start = 'top 88%'`
  The element begins revealing when its top reaches 88% down the scroller — a sliver above the fold. At `top bottom` the reveal happens off-screen and the user sees nothing; below about 80% the element is already well into view before it starts, which reads as a late load.
- `BATCH_INTERVAL = 0.1`
  Seconds of grace before a batch is flushed. Too small and a row of three cards splits into three batches with no stagger between them — the exact failure this component exists to avoid. Too large and the first element visibly waits before anything moves.
- `batchMax = 6`
  Cap on group size. With `stagger: 0.14`, a batch of 20 puts 2.7 s between the first and last element, so the tail is still blurred long after the user has read the head. Six keeps the whole group inside roughly a second.
- `stagger = 0.14`
  Offset within a batch. Below ~0.08 the group reads as simultaneous and the batching is invisible; above ~0.2 it reads as a queue rather than a wave.
- `blur = 12`
  Starting blur in pixels. This is the expensive property — it forces a full repaint of the layer every frame — and it is what turns a slide into a focus-pull. Past ~20px the text is unreadable for long enough that the reveal feels broken.
- `distance = 90`
  Pixels of rise. Paired with `scale: 0.94` it reads as depth. Much more and the element travels further than its own height, which looks like a layout jump rather than an entrance.
- `duration = 1.1`
  Long for an entrance, and deliberately so: the blur needs time to resolve or the focus-pull reads as a flicker.

## API

```ts
function BatchedBlurReveal(props: { children: ReactNode; selector?: string; start?: string; distance?: number; blur?: number; scale?: number; duration?: number; stagger?: number; once?: boolean; batchMax?: number; scrollerRef?: RefObject<HTMLElement | null>; className?: string }): JSX.Element
```

- `children: ReactNode`
  Section content. Anything matching `selector` inside it is revealed.
- `selector: string` — default `'[data-reveal]'`
  Which descendants reveal. Queried against the container, not the document.
- `start: string` — default `'top 88%'`
  ScrollTrigger start position for every batched element.
- `distance: number` — default `90`
  Pixels the element rises through.
- `blur: number` — default `12`
  Starting blur radius. Set 0 to drop the focus-pull and keep the rise.
- `scale: number` — default `0.94`
  Starting scale.
- `duration: number` — default `1.1`
  Seconds per element.
- `stagger: number` — default `0.14`
  Seconds between elements within one batch.
- `once: boolean` — default `true`
  Reveal once and never replay.
- `batchMax: number` — default `6`
  Largest group a single callback may receive.
- `scrollerRef: RefObject<HTMLElement | null>`
  The scroll container that owns the scroll position. Omit for the document.
- `className: string`
  Merged onto the container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const BATCH_INTERVAL = 0.1;

export function BatchedBlurReveal({
  children,
  selector = '[data-reveal]',
  start = 'top 88%',
  distance = 90,
  blur = 12,
  scale = 0.94,
  duration = 1.1,
  stagger = 0.14,
  once = true,
  batchMax = 6,
  scrollerRef,
  className,
}: BatchedBlurRevealProps) {
  const root = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();

  useGsap(
    gsap,
    () => {
      const el = root.current;
      if (!el) return;

      // Query from the container, never `document`. Two instances of this
      // component on one page would otherwise each claim the other's targets
      // and fight over the same tweens.
      const targets = Array.from(el.querySelectorAll<HTMLElement>(selector));
      if (targets.length === 0) return;

      if (reduced) {
        // Not "duration 0" — no trigger at all. The content is simply already
        // in its final state on first paint.
        gsap.set(targets, { opacity: 1, y: 0, scale: 1, filter: 'none' });
        return;
      }

      gsap.set(targets, {
        opacity: 0,
        y: distance,
        scale,
        filter: `blur(${blur}px)`,
        // Promoting up front matters more than usual here: an animated
        // `filter` repaints the layer every frame, and without the hint the
        // first two or three frames of every batch are the browser deciding
        // whether to promote at all.
        willChange: 'transform, filter, opacity',
      });

      ScrollTrigger.batch(targets, {
        start,
        once,
        batchMax,
        interval: BATCH_INTERVAL,
        scroller: scrollerRef?.current ?? undefined,
        onEnter: (batch) => {
          gsap.to(batch, {
            opacity: 1,
            y: 0,
            scale: 1,
            filter: 'blur(0px)',
            duration,
            ease: 'power3.out',
            stagger,
            // A fast flick can re-enter an element while its own reveal is
            // still running. Without overwrite the second tween interpolates
            // from wherever the first had got to and the two fight.
            overwrite: true,
            onComplete: () => {
              // A permanent `filter` keeps the element on its own composited
              // layer for the life of the page. Drop both hints once settled.
              gsap.set(batch, { clearProps: 'filter,willChange' });
            },
          });
        },
      });
    },
    root,
    [selector, start, distance, blur, scale, duration, stagger, once, batchMax, reduced],
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useGsap` runs the whole setup inside a `gsap.context` and calls `ctx.revert()` on unmount and on any prop change. That kills every batched ScrollTrigger and every in-flight tween, and restores the inline styles the initial `gsap.set` wrote, so an unmount mid-reveal leaves no opacity or blur behind on a node React may reuse.

**Reduced motion.** No ScrollTrigger is created. The targets are set to their final state — full opacity, no offset, no blur — during the first effect, so the section renders as finished content and never moves.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Creating one ScrollTrigger per element. Sixty targets means sixty sets of start/end calculations on every refresh, and — the visible part — two cards entering in the same frame both begin at t=0, so the row lands flat. `stagger` cannot cross independent triggers.
- Querying targets with `document.querySelectorAll`. Two instances of the component on one page each claim the other's elements, so both apply the initial state and both tween it, and elements reveal twice at different speeds.
- Leaving `filter` on the node after the reveal. A non-`none` filter keeps the element on its own composited layer permanently; on a page with sixty of them the compositor memory cost outlives the animation by the whole session. Clear it in `onComplete`.
- Omitting `overwrite: true`. Flick-scrolling re-enters an element while its reveal is running and the second tween starts from the partial state, so opacity and blur end up somewhere between the two.
- Animating `filter: blur()` without a `will-change` hint. The first frames go to the browser deciding whether to promote the layer, so every reveal starts with a visible hitch.
- Registering ScrollTrigger inside the component body. It runs on every render and touches `document`, which throws during server rendering. Register once at module scope behind a `typeof window` guard.

## Notes

- Pass `scrollerRef` when the content scrolls inside a container rather than the document — ScrollTrigger measures against the window by default and every start position will be wrong.
- `once: true` is the default because these are entrances, not a narrative. Set it false when the section is something the user is expected to scroll back through.

## Definition of done

Scroll a grid of cards into view: the cards in the same row lift and focus one after another with a visible offset, not all at once. Scroll back up and they stay revealed. Inspect a settled card and it has no `filter` or `will-change` left in its inline style. With reduced motion enabled the section is fully visible before any scrolling happens.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Bayer-Quantised Plasma

A full-screen plasma built from sixteen passes of iterated domain warping, then reduced to eleven grey levels through an 8x8 ordered dither matrix. The quantisation is the whole point: a smooth plasma is a screensaver, and the same plasma printed in eleven tones is a texture that type can sit on. The pointer displaces the plasma's own coordinate space so the field leans into the cursor rather than growing a highlight under it.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

An iterated domain-warped plasma crushed to eleven grey levels, so the hero reads as a dot-matrix proof.

- Category: webgl
- Runtime cost: webgl
- Dependencies: none beyond React

## How it works

1. Each of the `iterations` passes rotates the sample point by `rotate` radians, then folds it: `p += warp * sin(p.yx * 1.31 + t + i*0.7) / (1 + i*0.35)`. The `p.yx` swap is what couples the two axes into marbling — with `p.xy` the same code produces stripes.
2. Each pass also accumulates `amp * sin(p.x + p.y + t*0.6)` with `amp` decaying by 0.86, and the sum is divided by the amplitude actually accumulated rather than by a constant, so lowering `iterations` for a weak GPU changes the detail without changing the exposure.
3. The result is remapped to 0..1, pushed through `clamp((lum - 0.5) * contrast + 0.5, 0, 1)`, then multiplied by an elliptical vignette centred at `(0.5, 0.4)` — the optical centre, not the geometric one; at 0.5 a hero reads bottom-heavy.
4. Quantisation happens on a gamma-spaced ramp: `encode = pow(lum, 1/gamma)`, add the dither offset, `round` to one of `levels-1` steps, `decode = pow(q, gamma)`. The reference implementation carried an eleven-entry grey table and found the nearest entry with a branchless ladder of ten mix/step pairs; a monotone ramp collapses that search into encode, round, decode.
5. The dither offset `(bayer8(fragCoord / cell) - 0.5) / (levels - 1)` is added in the ENCODED space. Applied after decoding it would be the wrong physical size in the shadows, where the ramp is compressed, and the dark half of the frame would band anyway.
6. `iterations` is a uniform read against a constant `MAX_ITERATIONS = 48` loop bound with a `break`, so quality can be lowered at runtime without relinking a program or triggering a driver recompile.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `MAX_ITERATIONS = 48`
  Compile-time loop ceiling. A fully dynamic bound is legal in ES 3.00 but stops the compiler bounding register pressure, and some mobile drivers recompile the shader when the uniform changes — a visible hitch at exactly the moment you were trying to avoid one.
- `iterations = 16`
  Runtime pass count. Below about 6 the field is a plain ripple with no interference; past about 24 each extra pass adds detail finer than one dither cell, so it is thrown away by the quantiser and costs a full sin/rot per fragment for nothing.
- `warp = 1.5`
  How far each pass folds the coordinate. Under ~0.5 the passes barely disturb each other and the plasma is concentric; over ~2.5 the folding self-intersects and produces hard creases that survive quantisation as jagged black shapes.
- `amplitude decay = 0.86`
  Per-pass amplitude falloff. At 1.0 the late passes carry as much weight as the first and the field turns to grey mush; below ~0.6 only the first three passes contribute and the iteration count stops mattering.
- `phase offset = float(i) * 0.7`
  Decorrelates the passes. Without it every pass warps in lockstep and sixteen iterations look identical to one.
- `levels = 11`
  Grey steps. Eleven is the count that still reads as print: enough to hold the shape of the plasma, few enough that every transition is visibly dots rather than a ramp. Past ~20 the dither becomes invisible and you have paid for it anyway.
- `gamma = 1.49`
  Exponent the levels are spaced on. At 1.0 the steps are uniform in code and non-uniform to the eye, so the shadows show obvious banding while the highlights look smooth.
- `vignette centre = (0.5, 0.4)`
  The optical centre. Vignetting around the geometric centre makes a hero read as bottom-heavy, because the eye already places the middle of a frame slightly above halfway.
- `cellSize = 2`
  CSS pixels per dither cell, so the 8x8 tile is 16 CSS px. Indexing the matrix by device pixels instead makes the texture twice as coarse on a 1x monitor as on a 2x one.

## API

```ts
function BayerPlasmaHero(props: { iterations?: number; warp?: number; frequency?: number; rotate?: number; contrast?: number; gamma?: number; levels?: number; cellSize?: number; vignette?: number; ink?: readonly [number, number, number]; paper?: readonly [number, number, number]; speed?: number; maxDpr?: number; className?: string }): JSX.Element
```

- `iterations: number` — default `16`
  Plasma warp passes. Clamped to 1..48, the shader's compiled ceiling.
- `warp: number` — default `1.5`
  How far each pass folds the coordinate through its own sine.
- `frequency: number` — default `2.2`
  Base spatial frequency of the plasma.
- `rotate: number` — default `-0.1`
  Radians of rotation applied to the coordinate each pass.
- `contrast: number` — default `1.35`
  Contrast pivoted on mid grey, applied before quantisation.
- `gamma: number` — default `1.49`
  Exponent the output levels are spaced on.
- `levels: number` — default `11`
  Output grey levels, both ends included.
- `cellSize: number` — default `2`
  CSS pixels per dither cell. Multiplied by DPR internally.
- `vignette: number` — default `0.55`
  Strength of the elliptical vignette at the optical centre.
- `ink: readonly [number, number, number]` — default `[0.03, 0.032, 0.038]`
  Darkest output colour, linear 0..1 RGB.
- `paper: readonly [number, number, number]` — default `[0.88, 0.92, 0.9]`
  Lightest output colour, linear 0..1 RGB.
- `speed: number` — default `1`
  Multiplier on plasma evolution.
- `maxDpr: number` — default `2`
  Upper bound on device pixel ratio.
- `className: string`
  Merged onto the host element.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const TRIANGLE = new Float32Array([-1, -1, 3, -1, -1, 3]);
const MAX_ITERATIONS = 48;
const ITERATIONS = 16;
const WARP = 1.5;
const FREQUENCY = 2.2;
const ROTATE = -0.1;
const CONTRAST = 1.35;
const GAMMA = 1.49;
const LEVELS = 11;
const CELL_SIZE = 2;
const VIGNETTE = 0.55;
const INK: readonly [number, number, number] = [0.03, 0.032, 0.038];
const PAPER: readonly [number, number, number] = [0.88, 0.92, 0.9];

interface Gpu {
  gl: WebGL2RenderingContext;
  program: WebGLProgram;
  vao: WebGLVertexArrayObject;
  buffer: WebGLBuffer;
  locations: Map<string, WebGLUniformLocation | null>;
}

function build(gl: WebGL2RenderingContext): Gpu | null {
  const compile = (type: number, src: string): WebGLShader | null => {
    const shader = gl.createShader(type);
    if (!shader) return null;
    gl.shaderSource(shader, src);
    gl.compileShader(shader);
    if (gl.getShaderParameter(shader, gl.COMPILE_STATUS)) return shader;
    console.error('[bayer-plasma-hero]', gl.getShaderInfoLog(shader));
    gl.deleteShader(shader);
    return null;
  };

  const vert = compile(gl.VERTEX_SHADER, BAYER_PLASMA_VERT);
  const frag = compile(gl.FRAGMENT_SHADER, BAYER_PLASMA_FRAG);
  const program = gl.createProgram();
  const vao = gl.createVertexArray();
  const buffer = gl.createBuffer();
  if (!vert || !frag || !program || !vao || !buffer) return null;

  gl.attachShader(program, vert);
  gl.attachShader(program, frag);
  gl.linkProgram(program);
  gl.deleteShader(vert);
  gl.deleteShader(frag);
  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
    console.error('[bayer-plasma-hero]', gl.getProgramInfoLog(program));
    gl.deleteProgram(program);
    return null;
  }

  gl.bindVertexArray(vao);
  gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
  gl.bufferData(gl.ARRAY_BUFFER, TRIANGLE, gl.STATIC_DRAW);
  const attrib = gl.getAttribLocation(program, 'a_pos');
  if (attrib >= 0) {
    gl.enableVertexAttribArray(attrib);
    gl.vertexAttribPointer(attrib, 2, gl.FLOAT, false, 0, 0);
  }
  gl.bindVertexArray(null);

  return { gl, program, vao, buffer, locations: new Map() };
}

function loc(gpu: Gpu, name: string): WebGLUniformLocation | null {
  const cached = gpu.locations.get(name);
  if (cached !== undefined) return cached;
  const found = gpu.gl.getUniformLocation(gpu.program, name);
  gpu.locations.set(name, found);
  return found;
}

export function BayerPlasmaHero({
  iterations = ITERATIONS,
  warp = WARP,
  frequency = FREQUENCY,
  rotate = ROTATE,
  contrast = CONTRAST,
  gamma = GAMMA,
  levels = LEVELS,
  cellSize = CELL_SIZE,
  vignette = VIGNETTE,
  ink = INK,
  paper = PAPER,
  speed = 1,
  maxDpr = 2,
  className,
}: BayerPlasmaHeroProps) {
  const host = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const gpuRef = useRef<Gpu | null>(null);
  const dprRef = useRef(1);

  const { width, height } = useResizeObserver(host);
  const reduced = useReducedMotion();
  const visible = useVisibility();
  const pointer = useSmoothPointer({ target: host, smoothing: 0.03 });
  const [supported, setSupported] = useState(true);

  const paramsRef = useRef({
    iterations, warp, frequency, rotate, contrast, gamma,
    levels, cellSize, vignette, ink, paper, speed,
  });
  paramsRef.current = {
    iterations, warp, frequency, rotate, contrast, gamma,
    levels, cellSize, vignette, ink, paper, speed,
  };

  const drawRef = useRef<(elapsed: number) => void>(() => {});
  drawRef.current = (elapsed: number) => {
    const gpu = gpuRef.current;
    if (!gpu) return;
    const { gl } = gpu;
    const q = paramsRef.current;
    const p = pointer.current;

    gl.useProgram(gpu.program);
    gl.uniform2f(loc(gpu, 'u_resolution'), gl.drawingBufferWidth, gl.drawingBufferHeight);
    gl.uniform1f(loc(gpu, 'u_time'), elapsed * q.speed);
    gl.uniform2f(loc(gpu, 'u_pointer'), p.nx, 1 - p.ny);
    // Clamped to the shader's compiled ceiling: a value above MAX_ITERATIONS
    // would silently do nothing, which is worse than being clamped.
    gl.uniform1i(
      loc(gpu, 'u_iterations'),
      Math.max(1, Math.min(MAX_ITERATIONS, Math.round(q.iterations))),
    );
    gl.uniform1f(loc(gpu, 'u_warp'), q.warp);
    gl.uniform1f(loc(gpu, 'u_freq'), q.frequency);
    gl.uniform1f(loc(gpu, 'u_rotate'), q.rotate);
    gl.uniform1f(loc(gpu, 'u_contrast'), q.contrast);
    gl.uniform1f(loc(gpu, 'u_gamma'), Math.max(0.05, q.gamma));
    gl.uniform1f(loc(gpu, 'u_levels'), Math.max(2, Math.round(q.levels)));
    gl.uniform1f(loc(gpu, 'u_cell'), Math.max(1, q.cellSize * dprRef.current));
    gl.uniform1f(loc(gpu, 'u_vignette'), q.vignette);
    gl.uniform3f(loc(gpu, 'u_ink'), q.ink[0], q.ink[1], q.ink[2]);
    gl.uniform3f(loc(gpu, 'u_paper'), q.paper[0], q.paper[1], q.paper[2]);

    gl.bindVertexArray(gpu.vao);
    gl.drawArrays(gl.TRIANGLES, 0, 3);
    gl.bindVertexArray(null);
  };

  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;
    if (!hasWebGL()) {
      setSupported(false);
      return;
    }

    const gl = canvas.getContext('webgl2', {
      antialias: false,
      alpha: false,
      depth: false,
      stencil: false,
      powerPreference: 'high-performance',
    });
    if (!gl) {
      setSupported(false);
      return;
    }

    const gpu = build(gl);
    if (!gpu) {
      loseContext(gl);
      setSupported(false);
      return;
    }
    gpuRef.current = gpu;
    setSupported(true);

    return () => {
      gpuRef.current = null;
      gl.deleteVertexArray(gpu.vao);
      gl.deleteBuffer(gpu.buffer);
      gl.deleteProgram(gpu.program);
      loseContext(gl);
    };
  }, []);

  useEffect(() => {
    const canvas = canvasRef.current;
    const gpu = gpuRef.current;
    if (!canvas || !gpu || width === 0 || height === 0) return;

    const dpr = pixelRatio(maxDpr);
    dprRef.current = dpr;
    const w = Math.max(1, Math.round(width * dpr));
    const h = Math.max(1, Math.round(height * dpr));
    if (canvas.width !== w || canvas.height !== h) {
      canvas.width = w;
      canvas.height = h;
    }
    gpu.gl.viewport(0, 0, w, h);
    // At t = 0 every sine in the warp chain is in phase and the plasma is a
    // near-flat field, so the still frame is taken from a developed moment.
    drawRef.current(reduced ? 7.5 : 0);
  }, [width, height, maxDpr, supported, reduced]);

  const running = supported && visible && !reduced && width > 0 && height > 0;
  useRaf((_dt, elapsed) => drawRef.current(elapsed), running);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Deletes the VAO, vertex buffer and program, then `loseContext(gl)` to hand the context back. The rAF subscription and the pointer listener unsubscribe with their hooks.

**Reduced motion.** No rAF subscription. A single frame is drawn at a fixed `u_time` of 7.5 seconds and redrawn on resize — not at t=0, where every sine in the warp chain is still in phase and the plasma is a nearly flat field. The dithered texture, the vignette and the level structure are all fully present; only the evolution stops.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Dividing the plasma sum by a hard-coded normaliser. Drop from 16 iterations to 8 on a weak GPU and the whole image gets darker, so the low-quality path looks like a different component rather than the same one with less detail.
- Applying the dither offset after decoding the gamma ramp. In the shadows the ramp is compressed, so a fixed offset spans much less than one output step there and the dark half of the frame bands exactly as if there were no dither at all.
- Writing `sin(p.xy * ...)` instead of `sin(p.yx * ...)`. The axes stop being coupled, every pass warps x by a function of x, and the marbling degenerates into diagonal stripes.
- Making the iteration count a `const int`. Every quality level then needs its own compiled program, and switching between them stalls the pipeline; a uniform plus a constant loop bound with `break` costs one comparison per pass.
- Centring the vignette at (0.5, 0.5). It is subtle and it is real — the frame reads as sagging, and the usual reaction is to reduce the vignette strength instead of moving it.
- Rendering at native DPR. This shader is 16 iterations of transcendentals per fragment; at DPR 3 that is 2.25x the fragments of DPR 2 for no perceptible gain, and it is the difference between 60fps and 25 on a phone.
- Leaving the context alive on unmount. Raw GL has no `dispose()` — the VAO, buffer and program are deleted explicitly and `loseContext(gl)` returns the context, or the page starts blanking its oldest canvases after roughly sixteen mounts.

## Notes

- The 8x8 matrix is derived from `gl_FragCoord` with six integer operations rather than sampled from a texture. The derivation is documented in full in `bayer8-ordered-dither`; the function is duplicated here so this component installs standalone.
- The entire look is data: `iterations`, `warp`, `frequency`, `contrast`, `gamma` and `levels` are the only things separating newsprint from oil-slick.

## Definition of done

Every tonal transition is made of visible ordered dots — put your eye close and there is no smooth ramp anywhere in the frame. Set `iterations={6}` and the field simplifies without getting darker. Move the cursor and the plasma shears toward it rather than a bright spot appearing under it. The frame is darkest at the corners and brightest slightly above the middle.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Bit-Math Bayer8 Dither

Ordered dithering with the threshold matrix computed from the fragment coordinate instead of sampled from a texture. Six integer operations reproduce the classic 8x8 Bayer matrix exactly, which turns a banding-prone gradient into a stable newsprint texture that holds at any zoom and costs less than the texture fetch it replaces.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A smooth gradient crushed to five levels through an 8x8 ordered matrix derived from six integer ops.

- Category: webgl
- Runtime cost: webgl
- Dependencies: none beyond React

## How it works

1. The Bayer matrix is defined recursively as `M2 = [[0,2],[3,1]]` and `M2n(x,y) = 4*Mn(x mod n, y mod n) + M2(x div n, y div n)`. Writing M2 in binary (0=00, 2=10, 3=11, 1=01) collapses it to the closed form `M2(a,b) = 2*(a^b) + b`.
2. Unrolling that recursion three times gives `M8(x,y) = 16*M2(x0,y0) + 4*M2(x1,y1) + M2(x2,y2)` where xN is bit N of x, and substituting the closed form yields the whole matrix as one expression: `32*(x0^y0) + 16*y0 + 8*(x1^y1) + 4*y1 + 2*(x2^y2) + y2`.
3. Read as bits that is the low three bits of `x ^ y` and of `y`, interleaved and reversed — the LEAST significant coordinate bit drives the MOST significant threshold bit, which is precisely what makes the pattern maximally dispersed instead of clustered. In GLSL it is `int x = c.x & 7; int y = c.y & 7;` followed by those six terms, divided by 64.
4. `gl_FragCoord.xy` is divided by `cellSize * dpr` before the matrix lookup, so the dither cell is a fixed physical size and the texture does not get four times finer on a retina display.
5. Quantisation is `floor(clamp(c + (threshold - 0.5) / steps, 0, 1) * steps + 0.5) / steps` with `steps = levels - 1`. Centring the threshold on zero and scaling it to exactly one output step is what makes the perturbation cancel out on average.
6. A `pow(g, 1.35)` gamma is applied before quantisation, because the output levels are evenly spaced in the encoded value while the eye is not — quantising the linear value alone dumps all the visible banding into the shadows.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `divisor = 64.0`
  The matrix holds 0..63, so dividing by 64 keeps the thresholds in [0, 1). Dividing by 63 puts the top cell at exactly 1.0, which pushes one cell in every 8x8 tile a full step brighter and stamps a visible dot grid across flat areas.
- `levels = 5`
  Output steps per channel. At 2 it is a pure 1-bit print and the gradient becomes texture only. Above about 12 the eye can no longer see the individual steps and the dither is doing nothing but adding noise — use it to fix banding, not as a look.
- `cellSize = 2`
  CSS pixels per dither cell, so the 8x8 tile is 16 CSS px. At 1 the pattern is at the Nyquist limit of most displays and shimmers when the page scrolls; above about 6 it stops reading as print texture and starts reading as a deliberate checkerboard.
- `threshold scale = (t - 0.5) / (levels - 1)`
  The perturbation must span exactly one output step. Larger and the dither adds contrast of its own — flat areas visibly sparkle. Smaller and it cannot push a value across a level boundary, so the bands survive untouched.
- `gamma = 1.35`
  Applied before quantisation. Without it the evenly spaced levels bunch perceptually in the highlights and spread in the shadows, so the dark half of the frame shows obvious steps while the bright half looks smooth.

## API

```ts
function Bayer8OrderedDither(props: { levels?: number; cellSize?: number; speed?: number; dark?: readonly [number, number, number]; light?: readonly [number, number, number]; maxDpr?: number; className?: string }): JSX.Element
```

- `levels: number` — default `5`
  Output steps per channel, both ends included. 2 is pure 1-bit.
- `cellSize: number` — default `2`
  CSS pixels per dither cell. Multiplied by DPR internally.
- `speed: number` — default `1`
  Multiplier on the sweep that animates the underlying gradient.
- `dark: readonly [number, number, number]` — default `[0.035, 0.038, 0.045]`
  Darkest output colour, linear 0..1 RGB.
- `light: readonly [number, number, number]` — default `[0.9, 0.94, 0.92]`
  Lightest output colour, linear 0..1 RGB.
- `maxDpr: number` — default `2`
  Upper bound on device pixel ratio.
- `className: string`
  Merged onto the host element.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const TRIANGLE = new Float32Array([-1, -1, 3, -1, -1, 3]);
const LEVELS = 5;
const CELL_SIZE = 2;
const DARK: readonly [number, number, number] = [0.035, 0.038, 0.045];
const LIGHT: readonly [number, number, number] = [0.9, 0.94, 0.92];

interface Gpu {
  gl: WebGL2RenderingContext;
  program: WebGLProgram;
  vao: WebGLVertexArrayObject;
  buffer: WebGLBuffer;
  locations: Map<string, WebGLUniformLocation | null>;
}

function build(gl: WebGL2RenderingContext): Gpu | null {
  const compile = (type: number, src: string): WebGLShader | null => {
    const shader = gl.createShader(type);
    if (!shader) return null;
    gl.shaderSource(shader, src);
    gl.compileShader(shader);
    if (gl.getShaderParameter(shader, gl.COMPILE_STATUS)) return shader;
    console.error('[bayer8-ordered-dither]', gl.getShaderInfoLog(shader));
    gl.deleteShader(shader);
    return null;
  };

  const vert = compile(gl.VERTEX_SHADER, BAYER8_DITHER_VERT);
  const frag = compile(gl.FRAGMENT_SHADER, BAYER8_DITHER_FRAG);
  const program = gl.createProgram();
  const vao = gl.createVertexArray();
  const buffer = gl.createBuffer();
  if (!vert || !frag || !program || !vao || !buffer) return null;

  gl.attachShader(program, vert);
  gl.attachShader(program, frag);
  gl.linkProgram(program);
  gl.deleteShader(vert);
  gl.deleteShader(frag);
  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
    console.error('[bayer8-ordered-dither]', gl.getProgramInfoLog(program));
    gl.deleteProgram(program);
    return null;
  }

  gl.bindVertexArray(vao);
  gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
  gl.bufferData(gl.ARRAY_BUFFER, TRIANGLE, gl.STATIC_DRAW);
  const attrib = gl.getAttribLocation(program, 'a_pos');
  if (attrib >= 0) {
    gl.enableVertexAttribArray(attrib);
    gl.vertexAttribPointer(attrib, 2, gl.FLOAT, false, 0, 0);
  }
  gl.bindVertexArray(null);

  return { gl, program, vao, buffer, locations: new Map() };
}

function loc(gpu: Gpu, name: string): WebGLUniformLocation | null {
  const cached = gpu.locations.get(name);
  if (cached !== undefined) return cached;
  const found = gpu.gl.getUniformLocation(gpu.program, name);
  gpu.locations.set(name, found);
  return found;
}

export function Bayer8OrderedDither({
  levels = LEVELS,
  cellSize = CELL_SIZE,
  speed = 1,
  dark = DARK,
  light = LIGHT,
  maxDpr = 2,
  className,
}: Bayer8OrderedDitherProps) {
  const host = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const gpuRef = useRef<Gpu | null>(null);
  const dprRef = useRef(1);

  const { width, height } = useResizeObserver(host);
  const reduced = useReducedMotion();
  const visible = useVisibility();
  const pointer = useSmoothPointer({ target: host, smoothing: 0.004 });
  const [supported, setSupported] = useState(true);

  const paramsRef = useRef({ levels, cellSize, speed, dark, light });
  paramsRef.current = { levels, cellSize, speed, dark, light };

  const drawRef = useRef<(elapsed: number) => void>(() => {});
  drawRef.current = (elapsed: number) => {
    const gpu = gpuRef.current;
    if (!gpu) return;
    const { gl } = gpu;
    const params = paramsRef.current;
    const p = pointer.current;

    gl.useProgram(gpu.program);
    gl.uniform2f(loc(gpu, 'u_resolution'), gl.drawingBufferWidth, gl.drawingBufferHeight);
    gl.uniform1f(loc(gpu, 'u_time'), elapsed * params.speed);
    gl.uniform2f(loc(gpu, 'u_pointer'), p.nx, 1 - p.ny);
    gl.uniform1f(loc(gpu, 'u_levels'), Math.max(2, Math.round(params.levels)));
    // Cell size is authored in CSS pixels and converted here, so the dither
    // grain is the same physical size on a 1x monitor and a 3x phone.
    gl.uniform1f(loc(gpu, 'u_cell'), Math.max(1, params.cellSize * dprRef.current));
    gl.uniform3f(loc(gpu, 'u_dark'), params.dark[0], params.dark[1], params.dark[2]);
    gl.uniform3f(loc(gpu, 'u_light'), params.light[0], params.light[1], params.light[2]);

    gl.bindVertexArray(gpu.vao);
    gl.drawArrays(gl.TRIANGLES, 0, 3);
    gl.bindVertexArray(null);
  };

  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;
    if (!hasWebGL()) {
      setSupported(false);
      return;
    }

    const gl = canvas.getContext('webgl2', {
      antialias: false,
      alpha: false,
      depth: false,
      stencil: false,
      powerPreference: 'high-performance',
    });
    if (!gl) {
      setSupported(false);
      return;
    }

    const gpu = build(gl);
    if (!gpu) {
      loseContext(gl);
      setSupported(false);
      return;
    }
    gpuRef.current = gpu;
    setSupported(true);

    return () => {
      gpuRef.current = null;
      gl.deleteVertexArray(gpu.vao);
      gl.deleteBuffer(gpu.buffer);
      gl.deleteProgram(gpu.program);
      loseContext(gl);
    };
  }, []);

  useEffect(() => {
    const canvas = canvasRef.current;
    const gpu = gpuRef.current;
    if (!canvas || !gpu || width === 0 || height === 0) return;

    const dpr = pixelRatio(maxDpr);
    dprRef.current = dpr;
    const w = Math.max(1, Math.round(width * dpr));
    const h = Math.max(1, Math.round(height * dpr));
    if (canvas.width !== w || canvas.height !== h) {
      canvas.width = w;
      canvas.height = h;
    }
    gpu.gl.viewport(0, 0, w, h);
    drawRef.current(0);
  }, [width, height, maxDpr, supported, reduced]);

  const running = supported && visible && !reduced && width > 0 && height > 0;
  useRaf((_dt, elapsed) => drawRef.current(elapsed), running);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Deletes the VAO, vertex buffer and program, then `loseContext(gl)`. The rAF subscription and pointer listener are removed by their hooks.

**Reduced motion.** The rAF loop never subscribes; the sweep is frozen at t=0 and the pointer light sits at its seeded centre. One frame is drawn on mount and on every resize, so the dithered gradient is fully rendered — the texture is the point, and it is static.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Uploading the matrix as an 8x8 texture. It needs a texture unit, a sampler uniform, GL_NEAREST filtering and CLAMP wrapping set correctly on a non-power-of-two-safe path, and a resource to dispose — all to replace six integer instructions that are cheaper than the fetch.
- Dividing the matrix by 63 instead of 64. The top cell lands on exactly 1.0, that one cell per tile is pushed a full level brighter than its neighbours, and flat regions grow a faint regular dot grid that only shows up on a real screen.
- Comparing against the raw matrix value with `step(0.0, x)`. The matrix contains a genuine zero cell, so the comparison passes there even when it should not, and every 8x8 tile gets one stuck pixel. Bias the comparison by about 0.001 if you use a threshold form rather than the quantise form here.
- Indexing the matrix with `gl_FragCoord` directly. The cell then measures one device pixel, so the same component looks twice as coarse on a 1x monitor as on a 2x one. Divide by `cellSize * dpr` and the texture is stable.
- Quantising the linear value with no gamma. The steps are uniform in code and non-uniform to the eye, so the shadows band visibly while the highlights look fine and the fix gets misdiagnosed as "not enough levels".
- Leaving the raw GL objects behind on unmount. There is no `dispose()` here — the VAO, buffer and program are deleted by hand and `loseContext(gl)` returns the context, without which a page that mounts this repeatedly starts blanking its oldest canvases.

## Notes

- The alternative implementation, a nested `mix`/`step` ladder, is branchless and works on WebGL1. This one needs WebGL2 for integer bit operators but is roughly half the instruction count.
- The same six lines dither any signal — swap the gradient in `main` for a scene texture and this becomes a post-process.

## Definition of done

The gradient shows no smooth ramp anywhere — every transition is a field of ordered dots resolving between five flat levels. Zoom the browser to 200% and the dot pitch doubles with the page instead of staying at one device pixel. Screenshot two consecutive frames with the pointer still: the dot pattern is byte-identical, because the matrix depends only on position.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Blend-Difference Cursor

A white circle replaces the pointer and inverts everything under it via `mix-blend-mode: difference`, so it is legible over any background without a single contrast rule. It has three sizes — 16px idle, 44px over a link, 150px over a `data-cursor="view"` target, the last carrying a text label — and the size change is CSS while the position is GSAP, deliberately kept on different properties.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A white dot in difference blend mode inverts whatever it crosses, growing 16 to 44 to 150px on hover.

- Category: cursor
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. Difference blending subtracts the backdrop from the source per channel. A pure white source therefore outputs `1 - backdrop`: black over white, white over black, the complement over any colour. That is the entire contrast strategy — no theme awareness, no luminance sampling, no per-section overrides.
2. Position is two `gsap.quickTo` setters created once, each backed by a single tween whose end value is mutated per event. At 0.32s with `power3` the dot trails the pointer by a few frames — enough to read as a physical object, short enough that clicking still feels direct.
3. `xPercent: -50, yPercent: -50` centres the dot on its own box once at mount, so the handler can pass raw pointer coordinates and, critically, the centring survives the width and height changing from 16px to 150px. A pixel offset would have to be recomputed for every size.
4. Size transitions list `width`, `height` and `background-color` explicitly. `transform` is excluded because GSAP writes it every frame; a CSS transition on the same property would interpolate toward a value GSAP has already replaced, and the result is a cursor that lags by a constant distance no tween duration accounts for.
5. Hover state is resolved by hit-testing `e.target.closest(...)` on each move rather than binding listeners to interactive children. React can add, remove and reorder those children freely and the cursor keeps working, with no subscription bookkeeping.
6. The dot is `display: none` in markup and only switched to `flex` after the `(pointer: fine)` check passes, so nothing renders before JS confirms there is a cursor to replace — no stray blob flashes during hydration on a phone.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `SIZE_IDLE / SIZE_HOVER / SIZE_VIEW = 16 / 44 / 150`
  16px reads as a cursor rather than a dot of dust. 44px is roughly the tap-target minimum and clearly signals "this is interactive" without hiding the word underneath. 150px is enormous on purpose: it has to hold a 15px label with breathing room, and at that size the inverted region becomes a design element rather than a pointer.
- `FOLLOW_DURATION = 0.32`
  Seconds of catch-up. Below ~0.15 the dot is welded to the pointer and the blend looks like a rendering artefact; above ~0.5 clicking feels disconnected because the visual lands after the press.
- `ease: 'power3' = power3 (in-out)`
  In-out rather than `.out`. quickTo remutates the end value continuously, so the tween is always restarting mid-flight; the symmetric curve absorbs direction changes instead of snapping into a fresh outward ramp on every event.
- `size transition timing = 0.4s cubic-bezier(0.22, 1, 0.36, 1)`
  A strong ease-out. The dot reaches most of its new size in the first ~120ms so the hover feels instant, then settles. Linear at this scale looks mechanical; a longer duration means the dot is still growing when the pointer has left the target.
- `label scale = 0.5 -> 1`
  The label grows with the dot rather than fading in at full size, so at the halfway point of the transition the text is proportionate to the circle around it instead of overflowing it.

## API

```ts
function BlendDifferenceCursor(props: { children?: ReactNode; label?: string; className?: string }): JSX.Element
```

- `children: ReactNode`
  Content the cursor inverts. Mark targets with `data-cursor="view"` or use plain `a`/`button`.
- `label: string` — default `'View'`
  Text shown inside the 150px state. Must fit at 15px inside the circle.
- `className: string`
  Merged onto the root container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** The three states. Diameters in px, not scales — see the note above. */
const SIZE_IDLE = 16;
const SIZE_HOVER = 44;
const SIZE_VIEW = 150;

const FOLLOW_DURATION = 0.32;

export function BlendDifferenceCursor({
  children,
  label = 'View',
  className,
}: BlendDifferenceCursorProps) {
  const root = useRef<HTMLDivElement>(null);
  const dot = useRef<HTMLDivElement>(null);
  const text = useRef<HTMLSpanElement>(null);

  useEffect(() => {
    const el = root.current;
    const node = dot.current;
    const caption = text.current;
    if (!el || !node || !caption) return;

    // Never on touch: there is no hover state to grow into, and `pointermove`
    // only fires mid-drag, so the dot would appear under the finger already
    // covering it and then be stranded on lift.
    if (!window.matchMedia('(pointer: fine)').matches) return;
    const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

    /* The dot is `display: none` until JS confirms a fine pointer, so nothing
       renders before this line — no stray blob flashes during hydration. */
    node.style.display = 'flex';
    /* Hiding the native cursor from JS, not CSS, for the same reason: a
       stylesheet rule would blank the cursor on touch devices too, where this
       component draws nothing to replace it. */
    const previousCursor = el.style.cursor;
    el.style.cursor = 'none';

    gsap.set(node, { xPercent: -50, yPercent: -50, autoAlpha: 0 });

    const duration = reduced ? 0 : FOLLOW_DURATION;
    // Two tweens for the lifetime of the component, end values mutated in
    // place. `gsap.to` per event would allocate ~120 tweens a second, each one
    // overwriting a tween that had not finished.
    const xTo = gsap.quickTo(node, 'x', { duration, ease: 'power3' });
    const yTo = gsap.quickTo(node, 'y', { duration, ease: 'power3' });

    let entered = false;
    let state: 'idle' | 'hover' | 'view' = 'idle';

    const apply = (next: typeof state) => {
      if (next === state) return;
      state = next;
      const size = next === 'view' ? SIZE_VIEW : next === 'hover' ? SIZE_HOVER : SIZE_IDLE;
      // Width and height only. `transform` is GSAP's.
      node.style.width = `${size}px`;
      node.style.height = `${size}px`;
      caption.style.opacity = next === 'view' ? '1' : '0';
      caption.style.transform = next === 'view' ? 'scale(1)' : 'scale(0.5)';
    };

    const onMove = (e: PointerEvent) => {
      const rect = el.getBoundingClientRect();
      const x = e.clientX - rect.left;
      const y = e.clientY - rect.top;

      if (!entered) {
        entered = true;
        // Second argument is quickTo's START value: this teleports instead of
        // easing, so the dot does not sail across the panel on every entry.
        xTo(x, x);
        yTo(y, y);
        gsap.to(node, { autoAlpha: 1, duration: reduced ? 0 : 0.2, overwrite: 'auto' });
      } else {
        xTo(x);
        yTo(y);
      }

      // Hit-testing the event target beats a listener per interactive child:
      // it survives children being added, removed or re-rendered by React.
      const target = e.target instanceof Element ? e.target : null;
      if (target?.closest('[data-cursor="view"]')) apply('view');
      else if (target?.closest('a, button, [data-cursor="hover"]')) apply('hover');
      else apply('idle');
    };

    const onLeave = () => {
      entered = false;
      apply('idle');
      gsap.to(node, { autoAlpha: 0, duration: reduced ? 0 : 0.2, overwrite: 'auto' });
    };

    /* Listening on the container, not the dot. A listener on the dot would see
       its own `pointerleave` as it slides out from under the pointer and chase
       itself. `pointer-events: none` on the dot is the other half of that. */
    el.addEventListener('pointermove', onMove, { passive: true });
    el.addEventListener('pointerleave', onLeave);

    return () => {
      el.removeEventListener('pointermove', onMove);
      el.removeEventListener('pointerleave', onLeave);
      el.style.cursor = previousCursor;
      node.style.display = '';
      gsap.killTweensOf(node);
      gsap.set(node, { clearProps: 'all' });
    };
  }, []);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes both container listeners, restores the container's original inline `cursor` value, resets the dot to `display: none`, then `gsap.killTweensOf` and `clearProps: "all"` to drop the two quickTo tweens and the centring transform. Nothing is left on the element for a remount to inherit.

**Reduced motion.** The cursor still appears, still inverts and still changes size — those are affordances, not motion. Both quickTo durations drop to 0 so the dot is welded to the pointer, and the fade in and out is instant. The CSS size transition is left in place; it is a 400ms state change, not continuous movement.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- An ancestor that creates a stacking context. A `transform`, `filter`, `opacity` below 1, `will-change`, `isolation: isolate`, `contain: paint`, a `position: fixed` parent or a `backdrop-filter` anywhere between the intended blend root and the dot silently confines the blend to that subtree — the dot inverts its immediate parent and nothing else. This is the single most common reason this effect "does not work", and it produces no error, no warning and no console output.
- Transitioning `all` on the dot. It catches `transform`, which GSAP is writing at 60-120fps, and CSS interpolates toward values that are already stale. The cursor then trails the pointer by a fixed distance that changing the tween duration does not fix, because the tween is not the thing lagging.
- Scaling instead of resizing. `scale()` is a transform, so it collides with the follow tween AND it scales the label's stroke weight and letter-spacing along with the circle. Animating `width`/`height` keeps typography at its designed size.
- Listening for `pointermove` on the dot itself. It sits under the pointer, so it receives its own `pointerleave` as it slides, and the cursor chases itself out of the panel. Listen on the container and keep `pointer-events: none` on the dot.
- Hiding the native cursor from CSS. A `cursor: none` rule applies on touch devices too, where this component renders nothing to replace it, so links become untappable-looking with no visible affordance. Set it from JS after the `(pointer: fine)` check and restore it on cleanup.
- Centring with a negative margin instead of `xPercent`/`yPercent`. The margin is a fixed pixel value and the dot changes size by a factor of nine, so it visibly slides off the pointer as it grows.
- Leaving the effect on over navigation. A 150px inverted blob over link text is genuinely worse than an arrow; a real deployment needs an escape hatch that restores the native cursor over the nav.
- Using a theme token for the dot colour. Difference blending only produces a clean inversion from pure white; a near-white token yields a muddy tint over mid-greys.

## Notes

- Gated on `(pointer: fine)`. On touch nothing mounts, the native cursor is never hidden, and the markup stays `display: none` — there is no hover to grow into and `pointermove` only exists mid-drag, which would put the dot under the finger already covering it.
- Scoped to its own container with `position: absolute` inside a `relative isolate` root rather than `position: fixed`. A production site-level cursor is `fixed` at the document root; the isolate here is what makes the blend stop at the component edge instead of inverting the whole page.
- Reduced motion keeps the cursor but sets every duration to 0, so the affordance and the inversion survive while the drift does not.
- The label is `#000` and the dot `#fff` as raw literals, not tokens. Difference blending is defined on the actual channel values; a token would break the inversion the moment the theme shifted.

## Definition of done

Move across the panel and a white dot follows a few frames behind, inverting the text and background under it — dark text goes light where the dot crosses it. Hover a link and it grows to 44px; hover a `data-cursor="view"` target and it grows to 150px with a label that scales up inside it. During the growth the dot stays centred on the pointer and never lags further behind than it did at rest. Leave the panel and it fades out. On touch there is no dot at all and the native cursor is untouched.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Browser Chrome Frame

A title bar plus a content well, drawn entirely in CSS, wrapped around anything you want to present as a live site rather than a picture of one. The address pill copies the URL and confirms with a checkmark that draws along its own path and holds for 1600 ms. Every state change happens inside a fixed-width pill, so nothing in the bar ever reflows.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A macOS window frame with hover-revealed traffic lights and an address pill whose check draws itself on copy.

- Category: primitive
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. The frame is a flex column: a `shrink-0` title bar and a `min-h-0 flex-1` content well. `min-h-0` is what lets the well actually shrink inside a flex parent — without it a tall child pushes the frame past its container and the rounded bottom corners leave the viewport.
2. The three window buttons are `11px` circles filled with the real macOS values (`#ff5f57`, `#febc2e`, `#28c840`) holding a `7px` SVG glyph at `opacity: 0`. The cluster is one Tailwind `group`, so hovering anywhere in the title bar fades all three glyphs in together — which is how the system chrome behaves, and hovering one button to reveal only that button is the tell of a reimplementation.
3. Copying goes through `navigator.clipboard?.writeText?.(url)`. That returns `undefined` outside a secure context and a rejecting promise when the document is not focused, so both branches resolve to an explicit `failed` state rather than a swallowed catch. A pill that silently does nothing reads as a broken button.
4. The confirmation checkmark carries `pathLength="1"` and `strokeDasharray="1"`, so `strokeDashoffset` moves between exactly `1` and `0` regardless of the path coordinates, and a single 320 ms `cubic-bezier(0.22, 1, 0.36, 1)` transition draws it. The link icon it replaces crossfades over 180 ms in an absolutely-positioned 12 px box, so the icon slot never changes size.
5. Both text labels — the URL and the confirmation — sit in the same CSS grid cell (`col-start-1 row-start-1`) and swap by opacity. The pill therefore cannot resize between states, so the URL never shifts sideways under the cursor that just clicked it.
6. A single `setTimeout` ref holds the return to idle. Every entry point clears it first, so clicking the pill three times in a row extends one confirmation rather than queuing three overlapping ones.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `COPIED_MS = 1600`
  How long the confirmed state holds. Deliberately long: at the 600-800 ms most implementations use, a user who looks back at the pill after moving their eyes to the clipboard target has already missed it, and clicks again. 1600 ms survives a glance away and back.
- `DRAW_MS = 320`
  Stroke-draw duration for the check. Below ~200 ms the draw is indistinguishable from a hard appear, which throws away the only cue that says "this just happened now"; past ~450 ms the confirmation is still arriving after the user has moved on.
- `FADE_MS = 180`
  Crossfade for the icon and label swap, and the traffic-light glyph reveal. Shorter than the draw on purpose — the check should finish last, so the eye lands on the completed mark rather than on a half-drawn one under settled text.
- `traffic light fills = #ff5f57 / #febc2e / #28c840`
  The actual macOS window-button values. This component reproduces a specific piece of system chrome, so these are content, not theme: recolouring them to the site palette turns the frame from "a browser" into "a diagram of a browser" and the recognition is gone.
- `dot size = 11px`
  Matches the system button diameter at 1x. At 8px the glyphs are unreadable; past ~14px the bar starts to read as a toy illustration rather than chrome.

## API

```ts
function BrowserChromeFrame(props: { url: string; children: ReactNode; label?: string; onCopy?: (url: string) => void; copiedDurationMs?: number; className?: string; bodyClassName?: string }): JSX.Element
```

- `url: string`
  Shown in the address pill and written to the clipboard on click.
- `children: ReactNode`
  The framed content. Sized by the frame, not by itself.
- `label: string`
  Display text for the pill. Defaults to `url` with the scheme stripped, which is what a browser shows.
- `onCopy: (url: string) => void`
  Fires after a successful clipboard write, never on failure.
- `copiedDurationMs: number` — default `1600`
  How long the confirmed state holds before returning to idle.
- `className: string`
  Merged onto the outer frame.
- `bodyClassName: string`
  Merged onto the content well below the title bar.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const COPIED_MS = 1600;
const DRAW_MS = 320;
const FADE_MS = 180;

type CopyState = 'idle' | 'copied' | 'failed';

export function BrowserChromeFrame({
  url,
  children,
  label,
  onCopy,
  copiedDurationMs = COPIED_MS,
  className,
  bodyClassName,
}: BrowserChromeFrameProps) {
  const [state, setState] = useState<CopyState>('idle');
  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
  const reduced = useReducedMotion();

  const notify = useRef(onCopy);
  notify.current = onCopy;

  const reset = useCallback(() => {
    if (timer.current !== null) {
      clearTimeout(timer.current);
      timer.current = null;
    }
  }, []);

  // A pending timer outlives the component unless it is cleared. Left alone it
  // calls setState on an unmounted tree — React 19 no longer warns about that,
  // which makes it quieter, not less of a leak.
  useEffect(() => reset, [reset]);

  const copy = useCallback(() => {
    // `navigator.clipboard` is undefined outside a secure context and its
    // promise rejects when the document is not focused. Both are ordinary, so
    // the failure has a state of its own rather than a swallowed catch: a pill
    // that silently does nothing reads as a broken button.
    const write = navigator.clipboard?.writeText?.(url);
    if (!write) {
      reset();
      setState('failed');
      timer.current = setTimeout(() => setState('idle'), copiedDurationMs);
      return;
    }

    void write.then(
      () => {
        reset();
        setState('copied');
        notify.current?.(url);
        timer.current = setTimeout(() => setState('idle'), copiedDurationMs);
      },
      () => {
        reset();
        setState('failed');
        timer.current = setTimeout(() => setState('idle'), copiedDurationMs);
      },
    );
  }, [url, copiedDurationMs, reset]);

  const copied = state === 'copied';
  const failed = state === 'failed';

  // Reduced motion keeps the state change and drops only the tweening: the
  // check is already fully drawn on the frame it appears, and the two labels
  // hard-swap instead of crossfading. The confirmation is still legible for
  // the same 1600 ms — the information was never the animation.
  const drawMs = reduced ? 0 : DRAW_MS;
  const fadeMs = reduced ? 0 : FADE_MS;
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** One `clearTimeout` on the single pending reset timer, via an effect that returns the same `reset` callback every entry point already uses. There are no listeners, no rAF and no tweens — all motion is CSS transitions on mounted nodes, which the browser discards with the node.

**Reduced motion.** The state machine is untouched: clicking still copies, the check still replaces the link icon, and the confirmation still holds for the full 1600 ms. What goes to zero is `DRAW_MS` and `FADE_MS`, so the check appears already fully drawn and the labels hard-swap instead of crossfading. The traffic-light glyphs still reveal on hover, without the fade.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Swapping the icon element instead of stacking both. Replacing a link icon with a check changes the rendered width by a pixel or two, the flex row re-solves, and the URL text jumps sideways at the exact moment the user is reading the confirmation.
- Letting the label change the pill width. If the URL and "Copied" are the same node with different text, the pill resizes and the whole title bar reflows. Stacking them in one grid cell keeps the width pinned to the longer of the two, permanently.
- Hard-coding the measured path length for the dash animation. The first time anyone nudges a coordinate in the checkmark, the offset no longer matches the path and the stroke either starts partly drawn or never completes. `pathLength="1"` renormalises so the animation is coordinate-independent.
- Assuming `navigator.clipboard` exists. On `http://` origins and inside some embedded webviews it is `undefined`, and calling it throws a TypeError that takes the click handler down with it. On a secure origin it still rejects if the document is not focused — a case that happens constantly in dev tools.
- Not clearing the reset timer before starting a new one. Rapid clicks queue several timeouts and the confirmation flickers off at the first one's deadline rather than the last one's, so the state disappears while the user is still clicking.
- Leaving the timer pending on unmount. It fires into a disposed tree; React 19 no longer warns, which makes it quieter, not less of a leak.
- Reading the reduced-motion state and disabling the confirmation itself. The check is information, not decoration. Only the tweening is dropped.

## Notes

- The `group-hover` glyph reveal has no touch equivalent, and correctly so: there is no hover on touch, and firing the reveal on press would light up three buttons the user cannot click.
- The content well sets `overflow-hidden` and `bg-bg`, which is what gives the embed its edge. Framing exists as much to bound the content as to decorate it.

## Definition of done

Hover the title bar and all three glyphs fade in together. Click the pill: the link icon fades out, a checkmark draws itself left to right, "Copied" replaces the URL, the pill does not change width by a single pixel, and the state returns to the URL 1600 ms later. Click three times quickly and you get one confirmation that ends 1600 ms after the last click. On an `http://` origin the pill shows "Press to copy" instead of a silent no-op. With reduced motion the check is fully drawn on the first frame it appears.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Chord-Synced Particle Burst

A burst is N notes a fixed interval apart, each with a visual flare that has to appear on the same beat as its note. Audio is scheduled on `AudioContext.currentTime`, which is sample-accurate; the flares are driven by a rAF loop, which is not. This hook schedules both from one set of offsets and converts the audio times into wall-clock times via `getOutputTimestamp()`, so a flare is never more than one frame from its note however long the burst runs.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Fires an arpeggio and its visual flares off one schedule, so each flash lands on its own note.

- Category: primitive
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. Notes are scheduled ahead of time on the audio clock: for step `i`, `at = ctx.currentTime + LEAD + step * i`, then `gain.setValueAtTime(peak, at)` and `gain.exponentialRampToValueAtTime(0.001, at + decay)`. Nothing is timed by `setTimeout`, so a busy main thread cannot skew a note.
2. `audibleAt(ctx, at)` converts that audio time into a `performance.now()` millisecond value. `ctx.getOutputTimestamp()` returns a matched pair — the sample frame currently leaving the output device and the wall-clock instant it left — so the mapping is `ts.performanceTime + (at - ts.contextTime) * 1000`. Hardware output latency is already inside that pair; adding `outputLatency` on top double-counts it.
3. When `getOutputTimestamp` is unavailable, or has not rendered a frame yet and returns `contextTime: 0`, the fallback is `performance.now() + (at - ctx.currentTime) * 1000 + min(outputLatency, 0.05) * 1000`. `currentTime` is the write head, not the speaker, so the latency has to be added back in this branch only.
4. Each step is pushed onto a queue sorted by wall-clock time, and a rAF loop pops every entry whose time has passed and calls `onStep(index, total)`. Overlapping bursts merge into one sorted queue rather than one loop per burst.
5. The loop is subscribed only while the queue is non-empty — `useRaf(tick, running)` — and unsubscribes itself on the frame it drains the last step, so an idle instrument holds no animation frame.
6. The `AudioContext` is constructed inside `fire()`, which the caller invokes from a click handler, and `resume()` is called if the browser still hands it back suspended. Constructing it at mount produces a suspended context whose scheduled notes are silently discarded.
7. `fire(steps)` caps at `chord.length` and returns the count actually scheduled, so a caller that has fewer flares available than the chord has notes hears exactly as many notes as it shows.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `step = 0.46`
  Seconds between notes, and the same number the visuals use. Around 130 bpm in eighths — fast enough to read as one gesture rather than four separate events, slow enough that each flare is individually visible. Below ~0.2s the flares smear into one flash; above ~0.7s the burst stops sounding like a chord and starts sounding like four taps.
- `gain = 0.15`
  Peak amplitude of a single sine. Four notes overlapping at 1.0 would sum past full scale and hard-clip the destination; 0.15 leaves headroom for the tails of earlier notes still decaying under later ones.
- `SILENCE = 0.001`
  -60 dB, the ramp target. `exponentialRampToValueAtTime` is mathematically undefined at 0 and throws; ramping to a literal 0 is the single most common Web Audio error. -60 dB is inaudible.
- `decay = 0.4`
  Seconds from peak to silence. Slightly shorter than the 0.46s step so a note has essentially finished before the next arrives — overlap past about 0.6s turns the arpeggio into a chord and the individual attacks stop being audible.
- `TAIL = 0.1`
  Extra seconds before `osc.stop()`. Stopping an oscillator exactly at the end of its ramp truncates the last samples and can produce a faint click; 0.1s of -60 dB signal costs nothing and guarantees the stop is inaudible.
- `LEAD = 0.02`
  Seconds of lead before the first note. One render quantum at 44.1 kHz is 128 samples, about 2.9 ms; 20 ms covers several quanta plus the jitter in getting from the click to the scheduling call. Scheduling at exactly `currentTime` means the first note is already partly in the past and its attack is clipped.
- `MAX_LATENCY = 0.05`
  Ceiling on the fallback latency compensation, in seconds. Bluetooth output can report 150-300 ms; delaying the visual by that much to match makes the click itself feel broken. Capping trades exact sync on pathological hardware for a UI that still responds.

## API

```ts
function useBurstAudioSync(options?: { chord?: readonly number[]; step?: number; gain?: number; decay?: number; onStep?: (index: number, total: number) => void; muted?: boolean }): { fire: (steps?: number) => number; unlocked: boolean }
```

- `chord: readonly number[]` — default `[261.63, 329.63, 392, 523.25]`
  One frequency in Hz per step. Caps how many notes a single `fire` can schedule.
- `step: number` — default `0.46`
  Seconds between steps. Shared by the audio schedule and the visual queue.
- `gain: number` — default `0.15`
  Peak gain of one note. Divided by the note count when the stagger collapses.
- `decay: number` — default `0.4`
  Seconds for the exponential ramp from `gain` down to -60 dB.
- `onStep: (index: number, total: number) => void`
  Called on the frame nearest each note. `index` is the position in the chord.
- `muted: boolean` — default `false`
  Skips audio entirely. Visual steps still fire on the same schedule, so the UI is unchanged.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** `exponentialRampToValueAtTime` is undefined at 0, so silence is -60 dB. */
const SILENCE = 0.001;
/** Seconds of dead air after the ramp before the oscillator is stopped. */
const TAIL = 0.1;
/** Seconds of lead before the first note. Absorbs one graph render quantum. */
const LEAD = 0.02;
/** Ceiling on latency compensation, in seconds. */
const MAX_LATENCY = 0.05;

/**
 * Wall-clock time at which a sample scheduled at `contextTime` is heard.
 *
 * The `getOutputTimestamp()` pair is measured *at the output device*, so the
 * hardware latency is already folded into it — adding `outputLatency` on top
 * would double-count it and push every flare late.
 */
function audibleAt(ctx: AudioContext, contextTime: number): number {
  if (typeof ctx.getOutputTimestamp === 'function') {
    const ts = ctx.getOutputTimestamp();
    // Before the graph has rendered anything both fields are 0. Trusting that
    // pair maps every future note to wall-clock zero, and the whole burst
    // flashes at once on the very next frame.
    if (
      ts.contextTime !== undefined &&
      ts.performanceTime !== undefined &&
      ts.contextTime > 0
    ) {
      return ts.performanceTime + (contextTime - ts.contextTime) * 1000;
    }
  }
  // Fallback. `currentTime` is the time of the sample being *written*, which
  // runs ahead of the speaker by roughly the output latency, so add it back.
  const reported = Number.isFinite(ctx.outputLatency)
    ? ctx.outputLatency
    : ctx.baseLatency;
  const latency = Number.isFinite(reported) ? Math.min(reported, MAX_LATENCY) : 0;
  return performance.now() + (contextTime - ctx.currentTime) * 1000 + latency * 1000;
}

export function useBurstAudioSync(options: UseBurstAudioSyncOptions = {}): BurstAudioSync {
  const { chord = C_MAJOR, step = 0.46, gain = 0.15, decay = 0.4 } = options;
  const reduced = useReducedMotion();

  const [unlocked, setUnlocked] = useState(false);
  const [running, setRunning] = useState(false);

  const ctxRef = useRef<AudioContext | null>(null);
  const queue = useRef<QueuedStep[]>([]);

  // Everything `fire` reads lives in one ref, so `fire` keeps a stable
  // identity and can be handed to a memoised child without re-binding it on
  // every render.
  const config = useRef({ chord, step, gain, decay, reduced, options });
  config.current = { chord, step, gain, decay, reduced, options };

  const fire = useCallback((steps?: number): number => {
    const cfg = config.current;
    const wanted = steps ?? cfg.chord.length;
    const total = Math.min(Math.max(Math.trunc(wanted), 0), cfg.chord.length);
    if (total === 0) return 0;

    // Reduced motion collapses the arpeggio into a single chord: the feedback
    // survives — it was asked for by a click, so it is not decoration — but
    // nothing travels across the screen.
    const stagger = cfg.reduced ? 0 : cfg.step;

    let ctx: AudioContext | null = null;
    if (!cfg.options.muted) {
      ctx = ctxRef.current;
      if (!ctx) {
        // Constructed here and only here: we are inside the gesture handler
        // that called `fire`, which is the one moment the autoplay policy
        // lets a context start.
        ctx = new AudioContext();
        ctxRef.current = ctx;
        setUnlocked(true);
      }
      if (ctx.state === 'suspended') void ctx.resume();
    }

    let baseMs = performance.now();

    if (ctx) {
      const start = ctx.currentTime + LEAD;
      // Four sines at full gain sum to 4x the peak and clip the destination.
      // They only ever overlap when the stagger is gone, so divide then.
      const peak = stagger === 0 ? cfg.gain / total : cfg.gain;

      for (let i = 0; i < total; i++) {
        const freq = cfg.chord[i];
        if (freq === undefined) continue;
        const at = start + stagger * i;

        const osc = ctx.createOscillator();
        const env = ctx.createGain();
        osc.type = 'sine';
        osc.frequency.value = freq;
        env.gain.setValueAtTime(peak, at);
        env.gain.exponentialRampToValueAtTime(SILENCE, at + decay);
        osc.connect(env);
        env.connect(ctx.destination);
        osc.start(at);
        osc.stop(at + decay + TAIL);
        // Without this every burst leaves two live nodes attached to the
        // destination. A few hundred bursts and the graph audibly degrades.
        osc.onended = () => {
          osc.disconnect();
          env.disconnect();
        };
      }

      baseMs = audibleAt(ctx, start);
    }

    const q = queue.current;
    for (let i = 0; i < total; i++) {
      q.push({ at: baseMs + stagger * i * 1000, index: i, total });
    }
    // Two bursts can overlap; the drain below assumes the head is the
    // earliest step, so keep the queue sorted rather than scanning it.
    q.sort((a, b) => a.at - b.at);
    setRunning(true);

    return total;
  }, []);

  // The loop only exists while something is queued. An always-on rAF for a
  // widget that fires twice a minute keeps the browser's animation frame
  // pipeline alive for nothing.
  useRaf(() => {
    const q = queue.current;
    const now = performance.now();
    while (q.length > 0) {
      const head = q[0];
      if (head === undefined || head.at > now) break;
      q.shift();
      config.current.options.onStep?.(head.index, head.total);
    }
    if (q.length === 0) setRunning(false);
  }, running);

  useEffect(
    () => () => {
      queue.current.length = 0;
      const ctx = ctxRef.current;
      ctxRef.current = null;
      // close() stops every scheduled note and releases the hardware. Chrome
      // caps a document at ~6 live contexts and throws on the seventh.
      if (ctx && ctx.state !== 'closed') void ctx.close();
    },
    [],
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The unmount cleanup empties the pending-step queue and calls `ctx.close()`, which cancels every note still scheduled in the future and releases the hardware. The rAF subscription is owned by `useRaf` and released when `running` goes false or the component unmounts. Each oscillator disconnects itself and its gain node in `onended`.

**Reduced motion.** The stagger collapses to zero: all notes are scheduled at the same audio time and every `onStep` fires on one frame, so the burst is a chord rather than a sequence travelling across the screen. Audio is not muted — it is direct feedback for a click, not ambient motion — but the per-note gain is divided by the note count because the notes now overlap.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Constructing the `AudioContext` at mount. Outside a user gesture the browser hands back a `suspended` context; `osc.start(at)` on it neither throws nor plays, so the bug presents as "audio just does not work" with a clean console.
- Ramping the gain to 0. `exponentialRampToValueAtTime(0, t)` throws a `RangeError` — the target must be strictly positive. Ramp to 0.001 instead.
- Using `setTimeout` for the notes so audio and visuals share a timer. Both then inherit the main thread's jitter, and on a frame that takes 80 ms the note lands 80 ms late while the sample-accurate alternative would not have moved.
- Adding `outputLatency` on top of a `getOutputTimestamp()` mapping. That pair is measured at the output device and already contains the latency, so adding it again pushes every flare a full hardware buffer behind its note — the exact defect the conversion exists to prevent.
- Trusting `getOutputTimestamp()` immediately after construction. Before the graph has rendered a quantum both fields read 0, which maps every future note to wall-clock zero and dumps the entire burst onto the next frame.
- Never disconnecting the oscillator and gain. Both stay attached to the destination after the note ends; a few hundred bursts in one session and the graph is carrying hundreds of dead nodes, which shows up as rising CPU and eventually distortion.
- Keeping a rAF loop running so the flare queue can be polled. The queue is empty almost all the time — subscribe on `fire`, unsubscribe on the frame the last step drains.
- Letting the notes overlap at full gain when reduced motion collapses the stagger. Four sines at 0.15 sum to 0.6 and the summed peak clips; the per-note gain has to be divided by the note count in the collapsed case.
- Forgetting `ctx.close()` on unmount. Chrome allows roughly six live `AudioContext` objects per document and throws on the next one, so a page that mounts this in a list silently stops producing sound after the sixth item.

## Notes

- The hook deliberately exposes no `play()` that can be called from an effect. `fire` is the only entry point and its contract is "call me from a gesture handler" — encoding the autoplay policy in the API rather than in a comment.
- Two clocks, two policies. Reduced motion collapses the stagger but does not mute anything: the sound is feedback for a click the user made, not ambient decoration, and silencing it removes information.
- `chord` is any frequency list. A minor triad is `[261.63, 311.13, 392]`; a single frequency makes it a one-shot tick with the same scheduling guarantees.

## Definition of done

Click a string: four flares appear 0.46s apart and each one coincides with a note — watch the fourth flare and hear the fourth note land together, not a beat apart. Click a string at either end and only one flare appears and only one note sounds. Nothing plays before the first click. Toggle sound off and the flares keep exactly the same timing. With reduced motion on, all four strings light in the same frame and you hear a chord. Unmount mid-burst and the remaining notes do not play.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Canvas Handoff Transition

The usual way to put a shader on more than one page is to mount it on each of them, and the price is a new context, a new compile and a new first frame every time the route changes. No easing hides that: a field restarting from t = 0 is visibly a different object. Here one canvas is created imperatively, outside React's ownership, and moved into the destination page with `appendChild` during the layout phase — no paint happens in between, so the context never blinks. What the viewer sees is the surface they were already looking at, travelling from one rectangle to another.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

The live WebGL canvas is handed to the next page and flies to its new slot, instead of being destroyed and rebuilt.

- Category: transition
- Runtime cost: webgl
- Dependencies: three@^0.185.1, gsap@^3.15.0

## How it works

1. Four steps in a fixed order. MEASURE first, inside the click handler, because one `setState` later the outgoing rectangle no longer exists. FLUSH one frame, so the pixels about to travel are current. MOVE in a `useLayoutEffect`, which shares its task with React's DOM mutations and therefore straddles no paint. RESIZE last, on the tween's completion.
2. The move is a plain `target.appendChild(canvas)`. `appendChild` on a node that already has a parent relocates it rather than copying it, and a WebGL context belongs to the canvas element, not to its position in the document — so the context, the compiled program and the drawing buffer all survive being detached and re-attached.
3. The flight is FLIP: `scaleX = first.width / last.width`, `scaleY = first.height / last.height`, and the translation is the difference between the two centre points. Scale, never `width`/`height` — a width tween is 0.72 s of continuous reflow, and writing the canvas's width attribute would reallocate the drawing buffer on every frame of it.
4. The buffer resize is deferred to `onComplete` and the `ResizeObserver` is muted for the duration by a `flying` flag. Assigning `canvas.width` is what reallocates and CLEARS the backing store; do it while the element is mid-flight and the object being animated goes black for a frame. During the flight the old buffer is simply scaled by CSS, which is slightly soft and completely invisible at this duration.
5. Measuring inside the handler also makes interruption correct for free. If a flight is already running, `getBoundingClientRect()` returns the TRANSFORMED rect — where the canvas visually is, mid-air — so a second click continues from that point instead of snapping back to the slot it was heading for.
6. The destination slot has its `overflow` forced to `visible` inline for the length of the flight and restored afterwards. Inline, because the clipping usually comes from a utility class on the consumer's own markup that a rule in our stylesheet would lose to.
7. A `uHandoff` uniform is tweened 0 to 1 and back on the same timeline, shearing the field's sampling coordinate. It disturbs the picture rather than fading it: a fade would hide precisely the frames that prove the surface is the same one.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `HANDOFF_DURATION = 0.72`
  Seconds for the flight. It is long for a page transition, deliberately — the whole point is that you can watch a specific fold of the field travel and see that it never restarts. Under about 0.45 s the eye cannot track it and the effect degrades to a cut; over about 1 s the route change starts to feel withheld.
- `HANDOFF_EASE = 'power3.inOut'`
  Symmetric, because the two rectangles are equally important — the canvas is not leaving somewhere for somewhere, it is the same object being re-placed. An `out` ease would put the acceleration at the origin and imply the old page was the one that mattered.
- `SURGE_EASE = 'sine.inOut'`
  The `uHandoff` shear runs half the flight forward and half back (`yoyo: true, repeat: 1`). Sine, because it is the only common ease with zero slope at both ends, so the disturbance grows out of stillness and returns to it with no visible corner at the turnaround.
- `LEVELS = 6`
  Tones the field is crushed to. Low enough that the quantisation edges are hard and locked to the drawing buffer, which is what makes the mid-flight scaling legible as "these are the pixels that were already there". Above about ten the picture is a smooth gradient again and the proof is lost.
- `CELL = 2`
  Dither cell size in DRAWING-BUFFER pixels, so on a 2x display the pattern is one CSS pixel per cell — fine enough to read as tone, coarse enough to survive the scaling. Measured in buffer pixels rather than CSS pixels on purpose: it is the buffer that stretches during the flight.
- `MAX_DPR = 2`
  Device pixel ratio ceiling. Above 2 the visual gain on a quantised field is nil and the fill-rate cost is quadratic — and this surface is on screen on every page rather than on one hero, so its cost is paid continuously.
- `INK / PAPER = [0.42, 0.65, 1] / [0.035, 0.037, 0.045]`
  The two ends of the quantisation ramp, as raw 0..1 RGB. Passed as `THREE.Vector3` rather than `THREE.Color` because three applies working-colour-space conversion to a Color and none to a Vector3, and a `ShaderMaterial` emits `gl_FragColor` without the output-encoding chunk — Vector3 is the only pairing where the numbers written in the source are the numbers that reach the screen.

## API

```ts
function CanvasHandoffTransition(props: { controller: CanvasHandoff; children: ReactNode; duration?: number; ease?: string; ink?: readonly [number, number, number]; paper?: readonly [number, number, number]; levels?: number; cell?: number; maxDpr?: number; className?: string }): JSX.Element
function CanvasHandoffSlot(props: { controller: CanvasHandoff; id: string; className?: string }): JSX.Element
function useCanvasHandoff(initialId: string): { active: string; fallback: boolean; handoff: (id: string, commit?: () => void) => void }
```

- `controller: CanvasHandoff`
  From `useCanvasHandoff(initialSlotId)`. Shared by the host and every slot.
- `children: ReactNode`
  The pages. Each renders one `CanvasHandoffSlot` for its own landing place.
- `duration: number` — default `0.72`
  Seconds for the flight. `0` moves the canvas instantly with no tween.
- `ease: string` — default `'power3.inOut'`
  Easing for the flight.
- `ink: readonly [number, number, number]` — default `[0.42, 0.65, 1]`
  Bright end of the quantisation ramp, raw 0..1 RGB.
- `paper: readonly [number, number, number]` — default `[0.035, 0.037, 0.045]`
  Dark end of the quantisation ramp, raw 0..1 RGB.
- `levels: number` — default `6`
  How many tones the field is crushed to.
- `cell: number` — default `2`
  Dither cell size in drawing-buffer pixels.
- `maxDpr: number` — default `2`
  Device pixel ratio ceiling.
- `className: string`
  Merged onto the host root via `cn`.
- `id: string`
  `CanvasHandoffSlot` only. Stable identity for this landing place, unique within one controller.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/* ------------------------------------------------------------------------
   BUILD. Depends on the motion preference and the DPR ceiling and nothing
   else — emphatically not on the active slot, or a route change would tear
   down the very context the component exists to preserve.
   ------------------------------------------------------------------------ */
useEffect(() => {
  const rootEl = root.current;
  if (!rootEl) return;

  /* Probed in an effect, never during render: `hasWebGL()` needs `document`,
     and branching the markup on it would be a hydration mismatch rather than
     a graceful degradation. */
  if (!hasWebGL()) {
    setFallback(true);
    return;
  }
  setFallback(false);

  const renderer = new THREE.WebGLRenderer({
    antialias: false,
    alpha: false,
    powerPreference: 'low-power',
  });
  renderer.setPixelRatio(pixelRatio(maxDpr));

  /* three constructs the canvas; React never sees it. This is the whole
     strict-mode story: the second invocation gets a brand new element and a
     brand new context, because the first invocation's cleanup removed and
     released its own. */
  const canvas = renderer.domElement;
  canvas.className = 'kx-handoff-canvas';
  canvas.setAttribute('aria-hidden', 'true');

  const l = look.current;
  const uniforms: HandoffUniforms = {
    uResolution: { value: new THREE.Vector2(1, 1) },
    uTime: { value: 0 },
    uHandoff: { value: 0 },
    uLevels: { value: l.levels },
    uCell: { value: l.cell },
    /* Vector3, not Color: three applies working-colour-space conversion to a
       Color and none to a Vector3, and a `ShaderMaterial` emits `gl_FragColor`
       without the output-encoding chunk. Vector3 is the only pair of ends
       where the numbers written here are the numbers that reach the screen. */
    uInk: { value: new THREE.Vector3(l.ink0, l.ink1, l.ink2) },
    uPaper: { value: new THREE.Vector3(l.paper0, l.paper1, l.paper2) },
  };

  const material = new THREE.ShaderMaterial({
    vertexShader: canvasHandoffVertexShader,
    fragmentShader: canvasHandoffFragmentShader,
    uniforms,
  });
  // A 2x2 plane under an identity ortho camera is a full-screen quad with no
  // projection maths and no camera to keep in sync on resize.
  const geometry = new THREE.PlaneGeometry(2, 2);
  const scene = new THREE.Scene();
  scene.add(new THREE.Mesh(geometry, material));
  const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);

  const render = () => renderer.render(scene, camera);

  const resize = () => {
    const host = canvas.parentElement;
    if (!host) return;
    const w = host.clientWidth;
    const h = host.clientHeight;
    if (w === 0 || h === 0) return;
    // `false` leaves the CSS size alone; the stylesheet's 100%/100% is what
    // keeps the canvas glued to whichever slot currently owns it.
    renderer.setSize(w, h, false);
    uniforms.uResolution.value.set(w, h);
    render();
  };

  // Whatever slot is active right now. `rootEl` is the safety net for a
  // controller whose slots have not registered — the canvas is visible and
  // full-bleed rather than orphaned.
  const home = slots.current.get(activeRef.current) ?? rootEl;
  home.appendChild(canvas);
  resize();

  /* Observed on the CANVAS, not the slot: the observation follows the node
     across the handoff, so one observer covers every slot it will ever live
     in. `setSize(..., false)` never writes the CSS box, so this cannot feed
     back on itself. */
  const observer = new ResizeObserver(() => {
    // The flight deliberately runs at the OLD buffer size, scaled. Honouring
    // the resize here is the black frame the deferral exists to prevent.
    if (engine.current?.flying) return;
    resize();
  });
  observer.observe(canvas);

  if (reduced) {
    // One frame, then nothing. A field that drifts forever is motion, and
    // motion is what was asked not to happen.
    render();
  } else {
    // The timestamp is absolute, so elapsed time survives the handoff with
    // no accumulator to carry across and nothing to reset.
    renderer.setAnimationLoop((time) => {
      uniforms.uTime.value = time / 1000;
      render();
    });
  }

  engine.current = { canvas, uniforms, render, resize, flying: false };

  return () => {
    observer.disconnect();
    gsap.killTweensOf(canvas);
    gsap.killTweensOf(uniforms.uHandoff);
    // Stops the loop before releasing the context; a queued frame rendering
    // into a lost context throws out of the cleanup.
    disposeRenderer(renderer);
    material.dispose();
    geometry.dispose();
    // The effect appended it, the effect removes it. React has no idea this
    // node was ever here and will not try to reconcile it.
    canvas.remove();
    engine.current = null;
  };
}, [reduced, maxDpr, slots, engine, activeRef, setFallback]);

/* ------------------------------------------------------------------------
   HAND OVER. A LAYOUT effect, because React's mutations and its layout
   effects share one task: the canvas leaves the old parent and arrives at
   the new one with no paint in between. The same code in `useEffect` shows a
   frame with a hole where the canvas used to be.
   ------------------------------------------------------------------------ */
useLayoutEffect(() => {
  const e = engine.current;
  const target = slots.current.get(active);
  if (!e || !target) return;

  const from = first.current;
  first.current = null;

  // First run after the build already parked it correctly.
  if (e.canvas.parentElement === target) return;

  // `appendChild` on a node that already has a parent MOVES it. No clone, no
  // re-creation, and the WebGL context rides along untouched.
  target.appendChild(e.canvas);

  /* An interrupted flight leaves an inline transform behind. Clear it before
     measuring or Last is read through the previous flight's scale, and the
     inversion comes out compounded — the canvas leaps somewhere neither slot
     has ever been. `clearProps` rather than a set to identity so the instant
     paths below leave the element genuinely untouched. */
  gsap.killTweensOf(e.canvas);
  gsap.set(e.canvas, { clearProps: 'transform' });

  if (!from || reduced || duration <= 0) {
    e.resize();
    return;
  }

  const to = e.canvas.getBoundingClientRect();
  if (to.width === 0 || to.height === 0) {
    e.resize();
    return;
  }

  // FLIP: invert the measured difference, then animate the inversion away.
  // Scale rather than width/height — width is a layout property and a layout
  // property tweened for 0.7 s is 0.7 s of reflow.
  const scaleX = from.width / to.width;
  const scaleY = from.height / to.height;
  const x = from.left + from.width / 2 - (to.left + to.width / 2);
  const y = from.top + from.height / 2 - (to.top + to.height / 2);

  /* For the length of the flight the canvas is bigger than, and outside, the
     slot it now lives in — so the slot must not clip. Written INLINE and
     restored afterwards, because the thing being overridden is usually a
     utility class on the consumer's own markup, and a rule in our stylesheet
     would lose to it. Skip this and the transition is invisible: the canvas
     is cropped to its destination rectangle from the first frame, which
     looks exactly like no transition at all. */
  const clipped = target.style.overflow;
  target.style.overflow = 'visible';
  const unclip = () => {
    target.style.overflow = clipped;
  };

  e.flying = true;
  const tl = gsap.timeline({
    onComplete: () => {
      e.flying = false;
      unclip();
      gsap.set(e.canvas, { clearProps: 'transform' });
      // The ONE buffer resize, now that nothing is moving.
      e.resize();
    },
  });

  tl.fromTo(
    e.canvas,
    { x, y, scaleX, scaleY, transformOrigin: '50% 50%' },
    { x: 0, y: 0, scaleX: 1, scaleY: 1, duration, ease },
    0,
  ).fromTo(
    e.uniforms.uHandoff,
    { value: 0 },
    { value: 1, duration: duration / 2, ease: SURGE_EASE, yoyo: true, repeat: 1 },
    0,
  );

  return () => {
    tl.kill();
    unclip();
    e.flying = false;
  };
}, [active, duration, ease, reduced, engine, slots, first]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `disposeRenderer` stops the animation loop before releasing the context, so a queued frame cannot render into a lost one and throw out of the cleanup; it then calls `dispose()`, `forceContextLoss()` and zeroes the canvas dimensions to release the backing store immediately. The `ResizeObserver` is disconnected, both the canvas transform tweens and the `uHandoff` tween are killed, the material and geometry are disposed, and the canvas element is removed by the same effect that appended it. The flight effect's own cleanup kills its timeline and restores the destination slot's original `overflow`, so an unmount mid-flight cannot leave a slot permanently unclipped.

**Reduced motion.** No animation loop is started: one frame is drawn when the context is built, and one more after each move and each resize, so the field is a still image rather than a drifting one. The handoff still moves the canvas — that is a DOM relocation, not motion — but the FLIP tween and the `uHandoff` surge are both skipped, and the drawing buffer is resized immediately instead of on a completion that will never fire. `prefers-reduced-motion` is read by the component through `useReducedMotion`, never inferred from the page.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Rendering the canvas from JSX. React unmounts the outgoing page's subtree on a route change, and a `<canvas ref>` inside it is destroyed with it — context, program, buffer and all. That is the exact failure this component exists to avoid, and it cannot be worked around from inside the page: the canvas has to be created by the effect and owned by nobody React can see.
- A React-owned canvas under `reactStrictMode`. The strict-mode remount reuses the SAME element across both effect invocations, so the first cleanup's `forceContextLoss()` hands the second invocation a dead context and the component renders permanently blank — in development only, which is a genuinely expensive way to lose an afternoon. Creating the element inside the effect gives the second run a clean one.
- Doing the move in `useEffect` instead of `useLayoutEffect`. Passive effects run after the browser has painted, so there is one composited frame in which the outgoing page is gone and the canvas has not arrived. It reads as a flash of empty box at exactly the moment the component is supposed to be proving continuity.
- Measuring First inside the layout effect. By then React has already removed the outgoing subtree, so there is nothing left to measure and the FLIP either animates from the wrong rectangle or is skipped. The measurement has to happen in the handler, before `setState`.
- Calling `renderer.setSize()` during the flight. Writing the canvas's width or height reallocates and clears the drawing buffer, so the object mid-animation flashes black for a frame. The `ResizeObserver` fires exactly then, because moving into a differently sized slot changes the border box — which is why it is muted by a `flying` flag rather than trusted.
- A destination slot that clips. `overflow: hidden` on the slot crops the inbound canvas to its final rectangle from the first frame, so the flight is invisible and the result looks identical to no transition. Forcing `overflow: visible` inline for the duration is the only override that reliably beats a utility class.
- Cloning instead of moving. `cloneNode(true)` on a canvas copies the element and NOT its bitmap or its context; `outerHTML` round-trips have the same effect. The clone is blank and the original is gone, so the page shows an empty box with no error anywhere.
- Tweening `width` and `height` instead of `scale`. Besides reflowing on every frame, they are the two properties that reset the drawing buffer, so the animation would clear the surface sixty times a second.
- Mounting the host inside the routed subtree. If the host unmounts on navigation the context goes with it and there is nothing left to hand over — the component silently degrades to the mount-a-new-one behaviour it replaces. It belongs in the layout, above the router outlet.
- Assuming the canvas paints where you expect. It is `position: absolute; z-index: 1` so it can lift over static page content on the way past, which means anything meant to sit ON TOP of the field needs its own stacking context. Text without `relative z-10` disappears under the canvas for the length of the flight.
- Letting the shader carry any state that could reset. Everything visible is a function of the absolute `setAnimationLoop` timestamp, so there is no accumulator to hand over. Drive the field from a per-frame increment instead and it will still restart on the handoff — the exact artefact the component was built to eliminate, hidden one layer deeper.

## Notes

- In Next.js App Router: mount `CanvasHandoffTransition` in `app/layout.tsx`, put a `CanvasHandoffSlot` in each page with an id of its own, and replace `<Link>` with a button calling `handoff(slotId, () => router.push(href))`. The component imports nothing from `next/navigation` — the route change is a callback, so the same host works under React Router or, as in the preview, plain `useState`.
- The slot renders no children while WebGL is live. That is not cosmetic: React only reconciles children it created, so an empty child list is the guarantee that it will never touch the canvas sitting inside. Content that belongs over the field goes in a sibling, not inside the slot.
- One context for the whole site is the real prize. Chromium allows roughly sixteen live WebGL contexts per renderer process and evicts the oldest without warning when you exceed it — a per-page canvas on a site with a persistent background is how an unrelated component three routes away turns black.
- The field is deliberately slow, about eight seconds per visible cycle. Anything faster and the eye cannot hold a specific fold across the transition, which is the only direct evidence the viewer gets that the surface was not rebuilt.
- Under reduced motion there is no animation loop at all — a single frame is drawn on build and again after each move — so the component costs nothing per frame for the people most likely to be on the weakest hardware.

## Definition of done

Watch one bright fold of the field and click a nav item: the same fold is still there when the canvas lands, offset only by the time the flight took. Nothing blanks, blinks, or restarts. The canvas visibly changes proportion in flight — wide banner to tall column — with the dither cells stretching along with it, then snapping to square at the end when the buffer is finally resized. Click twice in quick succession and the second flight starts from wherever the canvas is in the air rather than jumping to the first destination. In React DevTools the canvas element has no owner. Under `reactStrictMode` in development the preview renders on first load, not blank. With reduced motion the field is a still image and the canvas relocates without a flight.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Capture-Phase Click Swallow

Throw a drag carousel and let go over a card, and the browser dispatches a `click` on it — `mousedown` and `mouseup` landed in the same subtree, so that is exactly what the spec asks for. The result is that flinging the track navigates somewhere. One listener on the drag surface in the capture phase, which runs before any descendant handler, calls `stopPropagation` and `preventDefault` and the click is gone. The work is in the two edges: it has to swallow exactly one, and it has to let keyboard activation through, because Enter and Space fire a click with no pointer sequence behind it.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Cancels the single click a finished drag would fire, in the capture phase, without eating the next real click or keyboard activation.

- Category: primitive
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. The listener is registered with `addEventListener('click', handler, true)` on the drag surface. The third argument is the technique: capture runs root-down, so this handler sees the click before the card's own `onClick` and before a router's link interception. In the bubble phase the navigation has already happened.
2. It calls both `stopPropagation()` and `preventDefault()`. They do different jobs and neither covers the other: propagation stops listeners deeper in the path, while the default action — following an `<a href>`, submitting a form, toggling a `<label>` — is not a listener and is only cancelled by `preventDefault`. A swallow with only `stopPropagation` still navigates.
3. `arm()` is called by the gesture when it ends *having moved*, which `drag-deadzone-capture` reports as `onDragEnd(state, { moved })`. Arming on a stationary press is how the click a user actually meant gets eaten.
4. The arm is consumed inside the handler before the event is cancelled, so exactly one click is swallowed. A flag that stays set is the bug this replaces: the drag is suppressed, and so is the deliberate click that follows it.
5. Two independent stand-downs cover the drag that produces no click at all — one that ends over empty space, or that the browser cancelled. A `pointerdown` on the surface disarms, because a fresh press means the awaited click never came; and a 250 ms timer disarms as a backstop, since the click that follows a `pointerup` is dispatched in the same turn and anything later is not it.
6. `event.detail` is the keyboard test. For a pointer click it is the click count, 1 or more; for Enter, Space, and `element.click()` it is 0. Those return early and pass through untouched, so the widget stays operable from the keyboard.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `TIMEOUT_MS = 250`
  How long an arm survives with no click. The click after a `pointerup` arrives in the same turn, so one frame would do for a mouse; the margin is for the delayed synthetic click some touch browsers still emit. The ceiling is the time a person needs to press and release again — go much past ~400 ms and the arm can outlive its own gesture and reach into the next one, which is exactly the bug the expiry exists to prevent.
- `event.detail threshold = 0`
  Not a tuned number but a specified one: `UIEvent.detail` is the click count for a pointer-driven click and exactly 0 for a keyboard-driven or scripted one. Testing `detail === 0` is the only cross-browser tell available on the click event itself — `pointerId === -1` is only present where `click` is a `PointerEvent`, and the `screenX === 0 && screenY === 0` heuristic misfires on a genuine click in the top-left corner of the screen.

## API

```ts
function useClickSwallow(ref: RefObject<HTMLElement | null>, options?: { timeoutMs?: number; enabled?: boolean; onSwallow?: (event: MouseEvent) => void }): { arm: () => void; disarm: () => void; armed: RefObject<boolean>; swallowed: RefObject<number> }
```

- `timeoutMs: number` — default `250`
  How long an arm survives with no click arriving. Backstop for a drag that ends over nothing clickable.
- `enabled: boolean` — default `true`
  Detach the listeners and stand down when false.
- `onSwallow: (event: MouseEvent) => void`
  The click that was cancelled. Already stopped and prevented by the time this runs.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * Milliseconds an arm survives if no click follows. The click that follows a
 * `pointerup` is dispatched in the same turn, so anything over one frame is
 * already generous; the margin is for the delayed click some touch browsers
 * still emit. It has to stay well under the time a person needs to press and
 * release again, or the arm outlives its own gesture.
 */
const TIMEOUT_MS = 250;

/**
 * Suppress the one `click` that a finished drag is about to produce.
 *
 * Pairs with any gesture that reports whether it moved — `drag-deadzone-capture`
 * exposes exactly that as `onDragEnd(state, { moved })`. Arm on `moved`, and
 * only on `moved`: arming after a stationary press is how the click a user
 * meant gets eaten.
 */
export function useClickSwallow(
  ref: RefObject<HTMLElement | null>,
  options: UseClickSwallowOptions = {},
): ClickSwallowHandle {
  const { timeoutMs = TIMEOUT_MS, enabled = true } = options;

  const armed = useRef(false);
  const swallowed = useRef(0);
  const timer = useRef<number | null>(null);

  const config = useRef({ timeoutMs, options });
  config.current = { timeoutMs, options };

  const disarm = useCallback(() => {
    armed.current = false;
    if (timer.current !== null) {
      window.clearTimeout(timer.current);
      timer.current = null;
    }
  }, []);

  const arm = useCallback(() => {
    disarm();
    armed.current = true;
    // An expiry, not a standing flag. A drag that ends over empty space, or
    // one the browser cancelled, produces no click at all — and an arm left
    // standing swallows the user's next real click, whenever that arrives.
    timer.current = window.setTimeout(() => {
      armed.current = false;
      timer.current = null;
    }, config.current.timeoutMs);
  }, [disarm]);

  useEffect(() => {
    const el = ref.current;
    if (!el || !enabled) return;

    const onClickCapture = (e: MouseEvent) => {
      if (!armed.current) return;

      // Enter and Space on a focused link or button dispatch a click with
      // `detail === 0` and no pointer sequence behind it, as does
      // `element.click()`. There is no drag for those to be the tail of, and
      // swallowing them is what makes a drag carousel keyboard-inoperable.
      if (e.detail === 0) return;

      // Consumed here, so exactly one click is swallowed per arm.
      disarm();
      swallowed.current += 1;

      // Both, always. stopPropagation keeps it from the card's own handler and
      // from the router's link interception; preventDefault cancels the
      // default action, which is the part that actually follows an href.
      e.stopPropagation();
      e.preventDefault();

      config.current.options.onSwallow?.(e);
    };

    // A fresh press means the previous gesture is finished and the click it
    // was going to produce never arrived. Second safety net under the timer,
    // and the one that matters — it is deterministic rather than timed.
    const onPointerDown = () => disarm();

    // The third argument is the entire technique. In the bubble phase the
    // card's own handler has already run and the link has already navigated.
    el.addEventListener('click', onClickCapture, true);
    el.addEventListener('pointerdown', onPointerDown);

    return () => {
      el.removeEventListener('click', onClickCapture, true);
      el.removeEventListener('pointerdown', onPointerDown);
      // Without this the timer can fire after unmount and write to a ref that
      // nothing reads, and on a remount the widget starts life armed.
      disarm();
    };
  }, [ref, enabled, disarm]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The effect removes the capture-phase `click` listener with the same capture flag it was added with — passing `true` on the way out is required, since a listener added with capture is a different registration from one added without — removes the `pointerdown` listener, and calls `disarm()`, which clears the pending timeout and resets the flag so a remount does not start armed. No rAF, no pointer capture, nothing else held.

**Reduced motion.** Nothing changes, and the omission is deliberate rather than an oversight: this hook cancels an event, it does not animate anything, and there is no duration, distance, or easing in it to reduce. Behaviour identical under `prefers-reduced-motion: reduce`. Note that the keyboard path is unconditional for the same reason it matters here — the pass-through for `detail === 0` is an accessibility guarantee, not a motion setting, and it is not something a preference should be able to switch off.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Registering in the bubble phase. The card's own `onClick` runs first and the link has already navigated by the time the handler sees the event — the listener is correct and completely useless. The third argument to `addEventListener` is the whole fix.
- Calling `stopPropagation()` without `preventDefault()`. Every JavaScript handler is silenced and the `<a href>` still navigates, because following a link is a default action rather than a listener. The failure is confusing precisely because the swallow visibly "works" on buttons and does nothing on links.
- Leaving the flag set after the swallow. It eats the click after the drag as well, so the user drags, then clicks a card deliberately, and nothing happens. Consuming it inside the handler is one line and is the difference between a fix and a new bug.
- Setting the flag with no expiry at all. A drag that ends over empty space never produces a click, so the arm just sits there — and swallows a genuine click a minute later, at which point nobody will connect the two events.
- Swallowing keyboard activation. Enter and Space on a focused card dispatch a click with `detail === 0`, and if the flag happens to be armed the widget silently stops responding to the keyboard. It never shows up in testing because a carousel is tested by dragging it.
- Arming on every gesture instead of only on ones that moved. Without a dead zone upstream reporting `moved`, a two-pixel wobble during a click arms the swallow and the click is cancelled — the exact behaviour that makes drag carousels feel unreliable.
- Assuming the click lands on the element the pointer is over. Click targets the nearest common ancestor of the `mousedown` and `mouseup` targets, and while a pointer is captured the compatibility mouse events are retargeted to the capturing element. Scoping the listener to the drag surface is what makes it see the click at all.
- Reaching for `stopImmediatePropagation()` by default. It also silences capture-phase listeners registered earlier on the same node, which can include analytics or a focus manager that had nothing to do with the drag. Escalate to it only when a library has attached its own capture listener to the same element.
- Leaving the timer running at unmount. It fires against a ref nothing reads, and on remount the widget can start life armed and swallow the first click a user makes.

## Notes

- Designed to pair with `drag-deadzone-capture`: that hook decides whether the gesture moved, this one suppresses the consequence. They are separate because the classification is useful on its own, and because the swallow has edge cases — one click and no more, keyboard passes through — that have nothing to do with dragging.
- A component that activates on `pointerup` rather than on `click` cannot be helped by this; there is no click to cancel. That is a good argument for activating on `click` in a draggable surface, since `click` is also what the keyboard produces.
- `preventDefault` on the click does not undo focus. Focus was moved by `mousedown`, earlier in the sequence, so a swallowed drag can leave the card under the pointer focused. It is invisible in practice because focus from a pointer does not match `:focus-visible`.
- A `dblclick` is dispatched independently of the clicks that preceded it, so a component listening for double-click needs the same treatment applied to `dblclick`.

## Definition of done

Click a card: it opens, and the on-screen counter shows one activation and no swallow. Drag the row and release over a card: the row moves, the card does not open, and the swallow counter goes up by exactly one. Immediately click that same card: it opens — the swallow was consumed by the drag and did not carry over. Drag and release over the gap between cards, then click a card: it opens, because the arm expired instead of waiting for a click that never came. Tab to a card and press Enter, then Space: it opens both times, including immediately after a drag, and the swallow counter does not move. Put a real `<a href>` in the row and drag onto it: the page does not navigate.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Char Stagger Then Scale-Up

The headline is on screen from the first frame — small and ghosted, reading as a label. Characters resolve one at a time from left to right, and just before the last one lands the whole word scales to full size with a `back.out` overshoot. It assembles itself, then it asserts itself. Supporting copy fades up a quarter of a second into the scale, so the page is never doing only one thing at a time.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Characters resolve left to right, then the whole word scales up with an overshoot as the last one lands.

- Category: text
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. The text is split in JSX, not in the DOM: `text.split(" ")` gives word boxes, `Array.from(word)` gives one `inline-block` span per character. React owns every node, so no library mutates the tree and no `revert()` is needed to restore it.
2. The idle state — `opacity: dimOpacity` per character and `transform: scale(scaleFrom)` on the word — is written as inline JSX styles, not by GSAP. That makes the server-rendered markup and the no-JS render identical to the pre-animation frame, and it means a parent re-render cannot wipe out what GSAP wrote, because React only ever diffs props against props.
3. A `gsap.timeline` first tweens `[data-char]` to `opacity: 1` with `stagger: 0.07` and `duration: 0.28` on `power1.out`.
4. The word scale is appended at position `">-0.05"` — 50 ms *before* the character stagger ends. The overlap is what fuses two phases into one gesture; at `">"` they read as two separate animations queued back to back.
5. Supporting copy (`[data-fade]`) is appended at `"<0.25"` — 250 ms after the *scale started*, not after it finished. Relative-to-previous-start positioning is what keeps the choreography overlapping rather than sequential.
6. `transformOrigin: "50% 50%"` is set explicitly on the scale tween even though it is the default: a heading inside a flex column can inherit an origin from an earlier transform on an ancestor, and the word then grows out of one corner.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `SCALE_FROM = 0.42`
  Starting scale of the word. Around 0.4 the text reads as a caption; past ~0.65 the growth is not large enough to register as a change of role, and below ~0.3 the characters are illegible while they stagger, so the first half of the animation is wasted.
- `DIM_OPACITY = 0.24`
  Resting strength of an unresolved character, as opacity on `currentColor`. Zero would make the reveal a pop-in and lose the ghosted-label reading; above ~0.4 there is not enough contrast between resolved and unresolved for the sweep to be visible.
- `CHAR_STAGGER = 0.07`
  Seconds between adjacent characters. A ten-character word takes 0.7s to sweep. Below ~0.04 the characters resolve as a block; above ~0.12 a long headline outlasts the reader's patience.
- `CHAR_DURATION = 0.28`
  Seconds for one character. Deliberately four times the stagger, so several characters are always mid-resolve — that overlap is what makes it a sweep rather than a sequence of individual pops.
- `SCALE_DURATION = 0.9`
  Seconds for the scale-up. `back.out` spends most of its curve on the settle, so a shorter duration compresses the overshoot into something that reads as a bounce artefact.
- `OVERSHOOT = 1.3`
  The `back.out(n)` parameter. Around 1.3 the word passes a few percent beyond full size and returns. At 1.7 (GSAP's default) the overshoot on large type is tens of pixels and reads as a wobble.
- `FADE_STAGGER / FADE_DURATION / FADE_Y = 0.12 / 0.7 / 18`
  Supporting copy rises 18px over 0.7s, 0.12s apart. The travel is small on purpose — body copy that moves as far as the headline competes with it.
- `VIEW_THRESHOLD = 0.35`
  Fraction visible before the timeline runs. A headline is tall; requiring more than about a third means it has to be nearly centred before anything happens, and requiring less starts it while it is still a sliver at the bottom edge.

## API

```ts
function CharStaggerScaleUp(props: { text: string; children?: ReactNode; scaleFrom?: number; dimOpacity?: number; charStagger?: number; charDuration?: number; scaleDuration?: number; overshoot?: number; delay?: number; startOnView?: boolean; className?: string; textClassName?: string }): JSX.Element
```

- `text: string`
  The headline. Split per word and per character in JSX.
- `children: ReactNode`
  Supporting copy. Fades up after the scale has begun.
- `scaleFrom: number` — default `0.42`
  Starting scale of the whole word.
- `dimOpacity: number` — default `0.24`
  Starting opacity of each character.
- `charStagger: number` — default `0.07`
  Seconds between character reveals.
- `charDuration: number` — default `0.28`
  Seconds for one character to resolve.
- `scaleDuration: number` — default `0.9`
  Seconds for the scale-up.
- `overshoot: number` — default `1.3`
  The `back.out(n)` parameter — how far past 100% the word travels.
- `delay: number` — default `0`
  Seconds before the timeline starts.
- `startOnView: boolean` — default `true`
  Run when scrolled into view rather than on mount.
- `className: string`
  Merged onto the wrapper via `cn`.
- `textClassName: string`
  Merged onto the headline span — this is where type size and tracking go.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const SCALE_FROM = 0.42;
const DIM_OPACITY = 0.24;
const CHAR_STAGGER = 0.07;
const CHAR_DURATION = 0.28;
const SCALE_DURATION = 0.9;
const OVERSHOOT = 1.3;
const FADE_DURATION = 0.7;
const FADE_STAGGER = 0.12;
const FADE_Y = 18;
const VIEW_THRESHOLD = 0.35;

export function CharStaggerScaleUp({
  text,
  children,
  scaleFrom = SCALE_FROM,
  dimOpacity = DIM_OPACITY,
  charStagger = CHAR_STAGGER,
  charDuration = CHAR_DURATION,
  scaleDuration = SCALE_DURATION,
  overshoot = OVERSHOOT,
  delay = 0,
  startOnView = true,
  className,
  textClassName,
}: CharStaggerScaleUpProps) {
  const root = useRef<HTMLDivElement>(null);
  const word = useRef<HTMLSpanElement>(null);
  const reduced = useReducedMotion();
  const { inView } = useInView(root, { threshold: VIEW_THRESHOLD, once: true });

  useEffect(() => {
    const el = root.current;
    const wordEl = word.current;
    // Reduced motion needs no branch here: the idle state written into the
    // JSX below is already the finished state, so doing nothing is correct.
    if (!el || !wordEl || reduced) return;
    if (startOnView && !inView) return;

    const chars = Array.from(el.querySelectorAll<HTMLElement>('[data-char]'));
    const fades = Array.from(el.querySelectorAll<HTMLElement>('[data-fade]'));

    const ctx = gsap.context(() => {
      const tl = gsap.timeline({ delay });

      tl.to(chars, {
        opacity: 1,
        duration: charDuration,
        ease: 'power1.out',
        stagger: charStagger,
      }).to(
        wordEl,
        {
          scale: 1,
          duration: scaleDuration,
          ease: `back.out(${overshoot})`,
          // Set explicitly even though it is the default: a block-level
          // heading inside a flex column can inherit an origin from an
          // earlier transform, and the word then grows out of one corner.
          transformOrigin: '50% 50%',
        },
        '>-0.05',
      );

      if (fades.length > 0) {
        tl.to(
          fades,
          {
            opacity: 1,
            y: 0,
            duration: FADE_DURATION,
            ease: 'power3.out',
            stagger: FADE_STAGGER,
          },
          '<0.25',
        );
      }
    }, el);

    // revert(), not kill(): it also strips the inline transform and opacity
    // GSAP wrote, handing the nodes back in exactly the state React rendered.
    return () => ctx.revert();
  }, [
    text,
    reduced,
    inView,
    startOnView,
    delay,
    charDuration,
    charStagger,
    scaleDuration,
    overshoot,
  ]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The timeline is built inside a `gsap.context` scoped to the root, and teardown calls `ctx.revert()`. That kills the tweens and strips the inline `transform` and `opacity` GSAP wrote, handing the nodes back in exactly the state React rendered — which matters under React 19 StrictMode, where the effect runs twice on mount.

**Reduced motion.** The idle inline styles collapse to the finished state (`scale(1)`, `opacity: 1`, no translate) and the effect returns before building a timeline. The headline and its supporting copy are fully rendered at full size on first paint — nothing is hidden and nothing waits for a trigger.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Splitting text before the webfont has loaded. Character and word boxes are measured against the fallback face, so widths and line breaks are wrong and never re-flow once the real font arrives — see `font-safe-text-split` for the gating and re-split lifecycle this class of component needs.
- Letting a splitting library mutate the DOM under React. React has no record of the injected spans, so the next parent render replaces the whole subtree and the animation targets nodes that are no longer in the document. Splitting in JSX avoids the problem entirely.
- Writing the idle state with `gsap.set` in the effect. The first paint then shows the finished headline at full size before the effect runs, and it visibly snaps down before animating up.
- Splitting straight to characters without word boxes. A line break can then land between two letters of the same word.
- Hardcoding the dim colour as a hex value. `#3d3d3d` is invisible on a light background; opacity on `currentColor` composites correctly against any theme.
- Queuing the scale at `">"` instead of `">-0.05"`. The two phases stop overlapping and the headline reads as "characters appear… then a separate thing happens".
- Cleaning up with `kill()` rather than `revert()`. `kill()` stops the tweens but leaves GSAP's inline `transform` and `opacity` on the nodes, so a remount starts from the finished state.

## Notes

- No text-splitting dependency: the split is declarative JSX. GSAP `SplitText` is reserved for the two components whose subject *is* SplitText (`nested-splittext-restore`, `font-safe-text-split`); everything else here splits in React so consumers are not forced to adopt a DOM-mutating splitter for a per-character stagger.
- Each word is one `inline-block whitespace-nowrap` box with a real text node for the space between words, so lines still wrap normally between words.

## Definition of done

On entering the viewport the characters brighten one at a time from left to right, and the word begins growing before the last character has finished. The word overshoots full size once and settles. Supporting copy starts rising while the word is still growing, not after. Unmount mid-animation and the nodes carry no inline `transform` or `opacity`. With reduced motion enabled the finished headline is present on first paint.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: CSS Variable Clip-Path Tween

A panel reveal that tweens a CSS custom property instead of a CSS property. The stage clips itself with `inset(var(--kx-clip))`, and because custom properties inherit, any descendant carrying `.kx-clip-follow` clips with the same value in its own box — one tween, several clip boxes, no possible drift. The media pushes from 1.4 to 1 over half again the clip duration and the lines slide up on a stagger; the exit is the same timeline reversed, which turns the positive stagger into a last-line-first peel and the scale-down back into a push.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

One tweened custom property drives every clip-path on the panel, and reversing the timeline is the exit.

- Category: transition
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. GSAP's CSSPlugin special-cases any property whose name starts with `--`: it reads the start value with `getComputedStyle(target).getPropertyValue(prop)` and writes with `style.setProperty(prop, value)`. Because neither end is a plain number, the tween routes through the complex-string interpolator, which walks both strings and interpolates every number it finds pairwise — `100% 0% 0% 0%` to `0% 0% 0% 0%` is four independent number tweens in one string.
2. The tweened value feeds `clip-path: inset(var(--kx-clip))` on the stage. `inset()` takes `top right bottom left`, so a top inset of 100% collapses the box to nothing and 0% leaves it whole: the reveal is the top edge travelling down.
3. The reason to tween a variable rather than `clipPath` itself is inheritance. `.kx-clip-follow` on any descendant re-uses the same inherited value against its own border box, so a caption reveals in proportion with the panel without a second tween. Tweening `clipPath` on each element instead means N tweens that agree only until someone edits one.
4. The initial `--kx-clip` is declared in the injected stylesheet, not in React's inline style. GSAP writes the tweened value inline, and a React re-render owning that same inline property would reset it mid-tween. It also has to be declared somewhere: an undeclared custom property computes to the empty string, and a tween with no readable start value snaps to its end.
5. One paused timeline is built and then `play()`ed or `reverse()`d. Reversing is not a shortcut — it is the exit the source had: a reversed positive stagger runs last-element-first, and a reversed `scale: 1.4 -> 1` runs `1 -> 1.4`, so the panel leaves with its lines peeling off in reverse while the media is still pushing in.
6. The timeline is built inside `gsap.context()` with `open` deliberately absent from its dependencies. Rebuilding per state change would call `context.revert()`, which strips the inline value GSAP wrote — the closing tween would then read the stylesheet default, fully shut, as its start and animate from nowhere to nowhere.
7. Media and line timings are ratios of the clip duration (1.5x, 0.6x, offset 0.35x) rather than independent numbers, so retuning the reveal cannot desynchronise the three groups.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `duration = 1.2`
  Seconds for the clip. The source ran 2 s, but that timeline was scrubbed against scroll where duration is only a proportion of the scroll range. Played back at real time, 2 s is a panel you wait for; below ~0.8 s the `power3.inOut` has no room for its slow start and the edge appears to jump.
- `mediaScale = 1.4`
  Start scale of the media. Big enough that the settle is legible for the full duration, small enough that a 1x asset is not visibly softened. Also the reason the media needs an `overflow: hidden` wrapper: at 1.4 it is 40% wider than its box.
- `lineStagger = 0.125`
  Seconds between lines. Exactly the source value. At 0 the block arrives as one slab; past ~0.2 s the last line is still climbing after the clip has finished and the reveal appears to have two endings.
- `MEDIA_DURATION_RATIO = 1.5`
  The push outlives the clip by half again. The clip is the event; the scale still resolving after it is what stops the panel feeling like it stopped dead on arrival.
- `LINE_OFFSET_RATIO = 0.35`
  Fraction of the clip before the lines start. Any earlier and they climb inside a box that is still mostly clipped, so the first thing the eye catches is text being cut in half.
- `CLIP_SHUT = '100% 0% 0% 0%'`
  Four percentages, matching the four in `CLIP_OPEN`. The complex-string interpolator pairs numbers positionally, so `inset(100%)` against `inset(0% 0% 0% 0%)` would interpolate one number and leave the other three as literal text.

## API

```ts
function ClipPathVariableTween(props: { open: boolean; children: ReactNode; duration?: number; mediaScale?: number; lineStagger?: number; className?: string }): JSX.Element
```

- `open: boolean`
  `true` plays the reveal, `false` reverses it. Every change re-drives the same timeline.
- `children: ReactNode`
  Content. `[data-clip-media]` is pushed from `mediaScale` to 1; `[data-clip-line]` slides up from 120%.
- `duration: number` — default `1.2`
  Seconds for the clip. Media and line timings are ratios of it.
- `mediaScale: number` — default `1.4`
  Scale the media starts at. 1 disables the push.
- `lineStagger: number` — default `0.125`
  Seconds between lines. Reversed on exit, so the last line leaves first.
- `className: string`
  Merged onto the stage, which is the element that carries the clip.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** `inset(top right bottom left)`. Top at 100% collapses the box entirely. */
const CLIP_SHUT = '100% 0% 0% 0%';
const CLIP_OPEN = '0% 0% 0% 0%';

/**
 * Media scale outlives the clip by half again. The clip is the event; the push
 * continuing past it is what stops the panel feeling like it stopped dead.
 */
const MEDIA_DURATION_RATIO = 1.5;
const LINE_DURATION_RATIO = 0.6;
/** Lines start when the clip is a third open — before that they are hidden. */
const LINE_OFFSET_RATIO = 0.35;

const CLIP_CSS = `
.kx-clip-stage {
  /* Declared in CSS, never in React's inline style: GSAP writes the tweened
     value to the inline style, and a React re-render would reset it mid-tween.
     It also has to be declared SOMEWHERE — an undeclared custom property
     computes to the empty string, and a tween with no start value snaps. */
  --kx-clip: ${CLIP_SHUT};
  clip-path: inset(var(--kx-clip));
}
/* Any descendant clipped by the same inherited variable. */
.kx-clip-follow {
  clip-path: inset(var(--kx-clip));
}
`;

export interface ClipPathVariableTweenProps {
  /** `true` reveals, `false` clips away. Every change plays or reverses. */
  open: boolean;
  /**
   * Content. Two opt-in hooks:
   * `[data-clip-media]` is pushed from `mediaScale` to 1, and
   * `[data-clip-line]` slides up from 120% with a stagger.
   */
  children: ReactNode;
  /** Seconds for the clip itself. Media and lines are derived ratios of it. */
  duration?: number;
  /** Scale the media starts at. 1 disables the push. */
  mediaScale?: number;
  /** Seconds between lines. Reversed on exit, so the last line leaves first. */
  lineStagger?: number;
  className?: string;
}

export function ClipPathVariableTween({
  open,
  children,
  duration = 1.2,
  mediaScale = 1.4,
  lineStagger = 0.125,
  className,
}: ClipPathVariableTweenProps) {
  const root = useRef<HTMLDivElement>(null);
  const timeline = useRef<ReturnType<typeof gsap.timeline> | null>(null);
  const reduced = useReducedMotion();

  // Built once and held paused. Rebuilding it per `open` change would be
  // wrong twice over: `gsap.context().revert()` strips the inline value GSAP
  // wrote, so a closing tween would read the CSS default — fully shut — as its
  // start and animate from nowhere to nowhere.
  useGsap(
    gsap,
    () => {
      const el = root.current;
      if (!el) return;

      const media = el.querySelectorAll<HTMLElement>('[data-clip-media]');
      const lines = el.querySelectorAll<HTMLElement>('[data-clip-line]');

      const tl = gsap.timeline({ paused: true });

      tl.fromTo(
        el,
        { '--kx-clip': CLIP_SHUT },
        { '--kx-clip': CLIP_OPEN, duration, ease: 'power3.inOut' },
        0,
      );

      if (media.length > 0) {
        tl.fromTo(
          media,
          { scale: mediaScale },
          {
            scale: 1,
            duration: duration * MEDIA_DURATION_RATIO,
            ease: 'power2.out',
          },
          0,
        );
      }

      if (lines.length > 0) {
        tl.fromTo(
          lines,
          { yPercent: 120 },
          {
            yPercent: 0,
            duration: duration * LINE_DURATION_RATIO,
            ease: 'power3.out',
            stagger: lineStagger,
          },
          duration * LINE_OFFSET_RATIO,
        );
      }

      timeline.current = tl;
      return () => {
        timeline.current = null;
      };
    },
    root,
    [duration, mediaScale, lineStagger],
  );

  // Same dependency list plus `open`, so this always runs after the effect
  // above has rebuilt the timeline rather than driving a stale one.
  useEffect(() => {
    const tl = timeline.current;
    if (!tl) return;

    if (reduced) {
      // A jump, not a zero-duration tween: the timeline is seeked to the
      // correct end state and stays paused there. Clip, scale and line offsets
      // all land correctly because they are all on this one timeline.
      tl.progress(open ? 1 : 0).pause();
      return;
    }

    if (open) tl.play();
    else tl.reverse();
  }, [open, reduced, duration, mediaScale, lineStagger]);

  return (
    <div ref={root} className={cn('kx-clip-stage', className)}>
      <style href="kinetic-clip-path-variable-tween" precedence="medium">
        {CLIP_CSS}
      </style>
      {children}
    </div>
  );
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useGsap` runs everything inside `gsap.context()` and calls `revert()` on unmount, which kills the timeline and removes the inline `--kx-clip`, `transform` and `scale` GSAP wrote so React never inherits a stray style. The context callback also nulls the timeline ref, so the effect that plays it cannot touch a reverted timeline.

**Reduced motion.** The timeline is seeked with `tl.progress(open ? 1 : 0).pause()` — a jump to the correct end state, not a zero-duration tween. Because the clip, the media scale and every line offset all live on that one timeline, one seek lands all of them correctly, which is the practical argument for putting them there in the first place.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Writing the custom property through React's inline `style` as well. React owns that attribute and GSAP writes to it; the first re-render during a tween resets the value and the clip snaps back.
- Never declaring the custom property. An undeclared custom property computes to the empty string, so GSAP has nothing to parse as a start value and the tween jumps straight to its end on the first frame.
- Mismatching the number count between the two clip strings. The interpolator pairs numbers positionally, so `inset(100%)` to `inset(0% 0% 0% 0%)` animates the first number and carries the rest through as text.
- Rebuilding the timeline whenever the open state changes. `gsap.context().revert()` removes the inline value GSAP wrote, so the reverse tween reads the stylesheet default as its start and animates from the closed state to the closed state — the exit silently does nothing.
- Tweening `clipPath` on each element instead of one shared variable. It works on the day you write it and drifts the first time one of the durations is tuned, because nothing structural keeps them equal.
- Forgetting `overflow: hidden` on the media wrapper and on each line. A 1.4x scale overflows its box by 40%, and a line entering from `yPercent: 120` is visible below its own box the entire way up.
- Assuming a clipped-away panel is inert. `clip-path` does clip hit-testing, but anything positioned outside the clip region — a fixed-position child, a focusable control — can still be reached by the keyboard, so the panel also needs its interactive state driven from the same flag.
- Tweening `--kx-clip` with a scrubbed ScrollTrigger and expecting sub-pixel smoothness. Custom property writes invalidate style for the whole inheritance subtree, so a stage with hundreds of descendants pays for it on every frame. The technique earns its keep with a handful of followers, not hundreds.

## Notes

- The `open` flag is the API surface, so a faked route change, a real router, an `IntersectionObserver` or a click all drive it identically. Nothing here imports a router.
- Registering the property with `@property { syntax: "<percentage>+" }` is not needed: GSAP interpolates the string itself and never asks the browser to. Register it only if you also want CSS transitions or keyframes to animate the same variable.
- `inset()` is the only basic shape whose numbers interpolate this cleanly. `polygon()` works the same way as long as both sides have the same vertex count, which is the same constraint stated differently.
- For a full-page version, put the stage on the layout wrapper and the follower class on the header rule and the footer — one tween, three clip boxes, and the whole chrome resolves together.

## Definition of done

Click an index row: the panel's top edge travels down over 1.2 s, the media resolves from a 1.4x push, the three lines climb into place 0.125 s apart, and the meta rule at the bottom clips itself in step without a tween of its own. Click Close: the panel clips back up, the last line leaves first, and the media pushes in again — the index underneath is revealed, not covered by a second animation. With reduced motion the panel is simply present or absent with the media at 1x and the lines in place.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Compound Group Hover Card

A content card that answers a hover with a short sequence rather than a single state flip: it lifts, its icon tilts and overshoots its scale, a corner blob brightens, and the affordance arrow slides in — each on its own duration and delay. The trigger is `:hover, :has(:focus-visible)`, so a keyboard user tabbing to the link inside gets exactly the same four changes.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

One hover drives four changes on three elements, each with its own duration and curve. Keyboard gets all four.

- Category: primitive
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. The card owns `translate` and `border-color` on a 260ms `cubic-bezier(0.22, 1, 0.36, 1)`. It is the fastest change in the set because it is the one that acknowledges the pointer — anything slower and the card feels like it is deciding whether to respond.
2. The icon animates `rotate` over 320ms on the same ease and `scale` over 420ms on `cubic-bezier(0.34, 1.56, 0.64, 1)`, both delayed 40ms. Two curves on one element is only possible because `rotate` and `scale` are independent properties; packed into `transform` they would share a single duration and a single easing, and the overshoot would drag the rotation with it.
3. The corner blob is a radial gradient that is blurred once at paint time (`filter: blur(2rem)`) and thereafter only changes `opacity` 0.12 to 0.4 over 500ms and `scale` 1 to 1.15 over 700ms. It is the slowest element in the group, which is what makes it read as lighting rather than as a moving object.
4. `z-index: -1` on the blob places it above the card background and below the card content with no extra wrapper, and `isolation: isolate` on the card stops that negative index from escaping into the page stacking context and sliding behind an ancestor background.
5. The arrow translates 4px and goes from 0.4 to 1 opacity after an 80ms delay — last in the sequence, so the eye arrives at the call to action after the card has already committed to the hover.
6. The whole card is clickable through a stretched pseudo-element on the anchor (`::after { position: absolute; inset: 0 }`), so there is exactly one focusable, screen-reader-announced target. The card responds to that anchor's focus through `:has(:focus-visible)`, which is what gives keyboard parity without a single line of JavaScript.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `lift = -6px`
  Card travel on hover. Under 3px it is not distinguishable from a rendering shift; over about 10px the card visibly overlaps its neighbour in a tight grid and the shadow it does not have becomes conspicuous.
- `durations = 260 / 320 / 420 / 500 / 700 ms`
  Ascending by element weight: card, icon rotation, icon scale, blob opacity, blob scale. Equal durations collapse the sequence into a single snap; the spread is the entire effect. The 260ms floor is roughly the shortest a positional change can be and still be perceived as movement rather than a jump.
- `delays = 40ms icon, 80ms arrow`
  Small enough to feel like consequence rather than queueing. Past about 120ms the arrow reads as a second, separate event and a fast pointer pass leaves it half-animated.
- `icon scale = 1.1 with cubic-bezier(0.34, 1.56, 0.64, 1)`
  The 1.56 control point overshoots to roughly 1.13 before settling. Overshoot on a small element reads as physical; on the card itself it would read as a bug, which is why only the icon gets it.
- `blob opacity range = 0.12 to 0.40`
  It must be visible at rest — a blob that appears only on hover reads as a new object arriving, not as a light coming up. 0.12 is enough to establish it; past about 0.5 the accent starts tinting the body copy.
- `icon rotation = -6deg`
  Anticlockwise, because the arrow moves right and the two would otherwise both push the same direction and read as a shear. Past about 10deg a glyph-based icon starts to look misaligned rather than tilted.

## API

```ts
function CompoundGroupHover(props: { title: string; description: string; eyebrow?: string; icon?: ReactNode; href?: string; accent?: string; action?: string; className?: string }): JSX.Element
```

- `title: string`
  Card heading, rendered as an `h3`.
- `description: string`
  Body copy under the heading.
- `eyebrow: string`
  Small uppercase label above the title.
- `icon: ReactNode`
  Rendered inside the tilting badge. An inline SVG or a single character.
- `href: string`
  Renders the affordance link and stretches it over the whole card.
- `accent: string` — default `'var(--color-accent, currentColor)'`
  Drives the blob, the icon border and the link colour.
- `action: string` — default `'Read more'`
  Text of the affordance link.
- `className: string`
  Merged onto the card via `cn`. Use it for sizing inside a grid.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const HOVER_CARD_CSS = `
.kx-hcard {
  --kx-hcard-ease: cubic-bezier(0.22, 1, 0.36, 1);
  --kx-hcard-overshoot: cubic-bezier(0.34, 1.56, 0.64, 1);

  position: relative;
  isolation: isolate;
  overflow: hidden;
  display: flex;
  flex-direction: column;
  gap: 0.75rem;
  border: 1px solid var(--color-line, currentColor);
  border-radius: 12px;
  background-color: var(--color-surface, transparent);

  translate: 0 0;
  transition:
    translate 260ms var(--kx-hcard-ease),
    border-color 260ms linear;
}

.kx-hcard:hover,
.kx-hcard:has(:focus-visible) {
  translate: 0 var(--kx-hcard-lift, -6px);
  border-color: var(--color-line-strong, currentColor);
}

/* Icon: two properties, two curves. The rotation settles cleanly; the scale
   overshoots slightly and comes back, which is what reads as "picked up". */
.kx-hcard-icon {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 2.25rem;
  height: 2.25rem;
  border-radius: 9px;
  border: 1px solid var(--color-line, currentColor);
  color: var(--kx-hcard-accent);
  rotate: 0deg;
  scale: 1;
  transition:
    rotate 320ms var(--kx-hcard-ease) 40ms,
    scale 420ms var(--kx-hcard-overshoot) 40ms,
    border-color 260ms linear;
}

.kx-hcard:hover .kx-hcard-icon,
.kx-hcard:has(:focus-visible) .kx-hcard-icon {
  rotate: -6deg;
  scale: 1.1;
  border-color: var(--kx-hcard-accent);
}

/* The blob is blurred ONCE, at paint. Only opacity and scale animate, so the
   hover never re-runs a 2rem blur. Negative z-index puts it above the card
   background and below the card content without a wrapper. */
.kx-hcard-blob {
  position: absolute;
  right: -4rem;
  bottom: -4rem;
  width: 14rem;
  height: 14rem;
  border-radius: 9999px;
  background: radial-gradient(circle, var(--kx-hcard-accent) 0%, transparent 70%);
  filter: blur(2rem);
  opacity: 0.12;
  scale: 1;
  pointer-events: none;
  z-index: -1;
  transition:
    opacity 500ms var(--kx-hcard-ease),
    scale 700ms var(--kx-hcard-ease);
}

.kx-hcard:hover .kx-hcard-blob,
.kx-hcard:has(:focus-visible) .kx-hcard-blob {
  opacity: 0.4;
  scale: 1.15;
}

.kx-hcard-arrow {
  display: inline-block;
  translate: 0 0;
  opacity: 0.4;
  transition:
    translate 300ms var(--kx-hcard-ease) 80ms,
    opacity 220ms linear 80ms;
}

.kx-hcard:hover .kx-hcard-arrow,
.kx-hcard:has(:focus-visible) .kx-hcard-arrow {
  translate: 4px 0;
  opacity: 1;
}

/* Stretched link: the anchor stays the only focusable, screen-reader-visible
   target, and its pseudo-element makes the whole card the hit area. */
.kx-hcard-link {
  color: var(--kx-hcard-accent);
}

.kx-hcard-link::after {
  content: "";
  position: absolute;
  inset: 0;
  border-radius: inherit;
}

/* No motion: keep every change that carries meaning — the border and icon
   brighten, the blob comes up, the arrow reaches full opacity — and drop the
   three that are purely positional. Hover still visibly does something. */
@media (prefers-reduced-motion: reduce) {
  .kx-hcard:hover,
  .kx-hcard:has(:focus-visible) {
    translate: 0 0;
  }
  .kx-hcard:hover .kx-hcard-icon,
  .kx-hcard:has(:focus-visible) .kx-hcard-icon {
    rotate: 0deg;
    scale: 1;
  }
  .kx-hcard:hover .kx-hcard-arrow,
  .kx-hcard:has(:focus-visible) .kx-hcard-arrow {
    translate: 0 0;
  }
  .kx-hcard:hover .kx-hcard-blob,
  .kx-hcard:has(:focus-visible) .kx-hcard-blob {
    scale: 1;
  }
}
`;

export function CompoundGroupHover({
  title,
  description,
  eyebrow,
  icon,
  href,
  accent = 'var(--color-accent, currentColor)',
  action = 'Read more',
  className,
}: CompoundGroupHoverProps) {
  const style: StyleWithVars = { '--kx-hcard-accent': accent };

  return (
    <>
      <style href="kinetic-compound-group-hover" precedence="medium">
        {HOVER_CARD_CSS}
      </style>
      <article className={cn('kx-hcard p-6', className)} style={style}>
        <span className="kx-hcard-blob" aria-hidden="true" />

        {icon ? (
          <span className="kx-hcard-icon" aria-hidden="true">
            {icon}
          </span>
        ) : null}

        {eyebrow ? <span className="meta">{eyebrow}</span> : null}

        <h3 className="text-base tracking-tight text-fg">{title}</h3>
        <p className="text-[13px] leading-relaxed text-muted">{description}</p>

        {href ? (
          <a href={href} className="kx-hcard-link mt-auto pt-2 text-xs tracking-tight">
            {action}
            <span className="kx-hcard-arrow ml-1.5" aria-hidden="true">
              &rarr;
            </span>
          </a>
        ) : null}
      </article>
    </>
  );
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nothing to clean up. No listeners, no timers, no animation frames; the hover state lives entirely in the cascade. React removes the hoisted `<style>` when the last card unmounts.

**Reduced motion.** A `@media (prefers-reduced-motion: reduce)` block cancels the three positional changes — the card no longer lifts, the icon no longer tilts or scales, the arrow no longer slides — while keeping every non-positional one. The border still brightens, the blob still comes up from 0.12 to 0.4 opacity, and the arrow still reaches full opacity, so hover and keyboard focus remain visibly acknowledged.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Packing the icon lift into `transform: rotate(-6deg) scale(1.1)`. It works, but both halves are now one property with one duration — the moment you want the scale to overshoot and the rotation not to, you have to split them, and splitting `transform` mid-project means rewriting every rule that touches it.
- Transitioning `filter: blur()` on the blob instead of `opacity`. Every frame re-runs a 2rem blur over a 14rem box; on a grid of six cards a single pointer sweep drops the page into the teens.
- Making the card itself a `<div role="link" tabindex="0">` to get a focus state. It is not announced as a link, it does not middle-click, it does not open in a new tab, and it needs a keydown handler. The stretched `::after` on a real anchor gives all of that for one pseudo-element.
- Using `:focus-within` instead of `:has(:focus-visible)`. `:focus-within` fires on mouse clicks too, so the card sticks in its hover state after every click and only releases when something else is focused.
- Omitting `isolation: isolate` on the card. The blob's `z-index: -1` then resolves against whichever ancestor last created a stacking context and the blob disappears behind a section background — intermittently, depending on what else is on the page.
- Leaving all four changes in place under reduced motion. Lift, tilt and slide are motion; the border, the blob and the arrow opacity are not. Disabling the whole hover state is over-correction and leaves the card with no feedback at all.
- Forgetting `overflow: hidden` on the card. The blob is positioned 4rem outside the card on two sides and paints over the neighbouring card in a grid.

## Notes

- `:has()` needs Safari 15.4+, Chrome 105+ and Firefox 121+. Where it is unsupported the pointer hover still works exactly as written and the keyboard path degrades to the browser's own focus ring on the link.
- Independent `translate` / `rotate` / `scale` need Chrome 104+, Safari 14.1+, Firefox 72+. In older engines the properties are dropped and the card still changes colour and opacity on hover.
- The accent is one custom property, `--kx-hcard-accent`, read by the blob, the icon and the link. A grid of these differs only by that value.

## Definition of done

Hover the card and four things change on four different timings — you can see the arrow arrive after the card has already lifted. Tab to the link with the keyboard and the identical four changes happen. Click the card anywhere, including on the description text, and the link activates. Turn reduced motion on: nothing moves, but the border, blob and arrow still respond.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Conic @property Border

A rounded box wearing an animated conic-gradient border. Two bright stops travel around the ring in opposite quadrants, so the ring reads as rotating rather than blinking. The whole thing is one element and one keyframe — the only moving part is a registered custom property holding an angle, which the browser interpolates for you.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A gradient ring that rotates around a rounded box. Two highlights chase each other; no JavaScript runs.

- Category: primitive
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. `@property --kx-conic-angle { syntax: "<angle>"; inherits: false; initial-value: 0deg }` registers the custom property so the browser knows its value is an angle. An unregistered custom property is an untyped token stream: a keyframe from `0deg` to `360deg` has no interpolation rule and the value flips at the 50% mark instead of sweeping.
2. A single keyframe block, `@keyframes kx-conic-spin { to { --kx-conic-angle: 360deg } }`, drives that property from its `initial-value` to a full turn over `--kx-conic-duration` with `linear` timing. Linear is required: any ease makes the highlights visibly hesitate once per revolution.
3. The element carries two backgrounds. `linear-gradient(fill, fill) padding-box` paints the interior flat; `conic-gradient(from var(--kx-conic-angle), …) border-box` paints under the border. With `border: 1.5px solid transparent`, the conic layer survives the clip only in the ring, which is how the gradient follows `border-radius` — `border-image` cannot round corners.
4. The gradient has six stops with the glow colour at 55deg and 305deg and the rest colour everywhere else. Two highlights roughly opposite each other read as rotation; a single highlight reads as a light blinking on and off once per cycle.
5. `inherits: false` on the registration stops descendants from picking up the animating value. With inheritance on, every element in the subtree re-resolves its computed style on every frame of the animation, which turns a one-element repaint into a whole-subtree style recalculation.
6. Every colour is read through `var(--name, fallback)`, so the component renders correctly with no props and can be re-themed by setting `--conic-glow` or `--conic-fill` on any ancestor.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `glow stop positions = 55deg and 305deg`
  Two highlights, not one, and not diametrically opposite. 250 degrees apart means one is entering the top edge as the other leaves the bottom, so there is always motion somewhere on the ring. At 180 degrees apart the pair reads as a symmetric pulse; with one stop it reads as a blinking dot.
- `durationMs = 4000`
  One revolution. Below ~2500 ms the ring reads as a loading spinner and demands attention; above ~7000 ms the highlight barely appears to move and the border looks like a static gradient someone got wrong.
- `thickness = 1.5px`
  Sub-pixel on a 1x display, which is what keeps it a hairline rather than a stripe. At 1px the highlight is too thin to read colour; at 3px or more the conic banding between stops becomes visible as facets.
- `rest colour alpha = currentColor at 10%`
  The dim majority of the ring. At 0% the border disappears between highlights and the box appears to lose its outline; above ~20% the contrast against the glow collapses and the rotation stops reading.
- `reduced-motion parked angle = 132deg`
  Puts one highlight past the top-left shoulder rather than exactly on an edge or a corner. At the `initial-value` of 0deg the highlight sits dead centre on the right edge, which looks like a rendering artefact rather than a decision.

## API

```ts
function ConicBorder(props: { children: ReactNode; durationMs?: number; thickness?: string; radius?: string; glow?: string; rest?: string; fill?: string; paused?: boolean; className?: string }): JSX.Element
```

- `children: ReactNode`
  Content rendered inside the ring. The element is `inline-flex`, centred.
- `durationMs: number` — default `4000`
  Milliseconds for one full revolution.
- `thickness: string` — default `'1.5px'`
  Ring thickness. Becomes the transparent border width.
- `radius: string` — default `'9999px'`
  Corner radius. The gradient follows it, unlike `border-image`.
- `glow: string`
  Colour of the two travelling highlights. Defaults to `currentColor`.
- `rest: string`
  Colour of the dim ring between highlights. Defaults to `currentColor` at 10%.
- `fill: string`
  Interior fill. Must be opaque or the gradient shows through the middle.
- `paused: boolean` — default `false`
  Sets `animation-play-state: paused`, freezing the ring at its current angle.
- `className: string`
  Merged onto the ring element via `cn`. Use it for padding and typography.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/* Injected once per document. React 19 hoists `<style href precedence>` into
   <head> and de-duplicates by `href`, so a hundred rings ship one rule set —
   and `@property` registration is global anyway, so re-declaring it per
   instance would be pure waste. */
const CONIC_BORDER_CSS = `
@property --kx-conic-angle {
  syntax: "<angle>";
  inherits: false;
  initial-value: 0deg;
}

@keyframes kx-conic-spin {
  to { --kx-conic-angle: 360deg; }
}

.kx-conic {
  position: relative;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  isolation: isolate;

  border: var(--kx-conic-width, 1.5px) solid transparent;
  border-radius: var(--kx-conic-radius, 9999px);

  /* padding-box layer paints the interior, border-box layer paints under the
     ring. Order matters: the first background listed is the topmost. */
  background:
    linear-gradient(var(--kx-conic-fill), var(--kx-conic-fill)) padding-box,
    conic-gradient(
      from var(--kx-conic-angle),
      var(--kx-conic-rest)   0deg,
      var(--kx-conic-glow)  55deg,
      var(--kx-conic-rest) 130deg,
      var(--kx-conic-rest) 230deg,
      var(--kx-conic-glow) 305deg,
      var(--kx-conic-rest) 360deg
    ) border-box;

  animation: kx-conic-spin var(--kx-conic-duration, 4s) linear infinite;
}

.kx-conic[data-paused='true'] {
  animation-play-state: paused;
}

/* No motion: keep the ring, stop the revolution, and park a highlight
   off-axis so the border still reads as decorated rather than broken. */
@media (prefers-reduced-motion: reduce) {
  .kx-conic {
    animation: none;
    --kx-conic-angle: 132deg;
  }
}
`;

export function ConicBorder({
  children,
  durationMs = 4000,
  thickness = '1.5px',
  radius = '9999px',
  glow,
  rest,
  fill,
  paused = false,
  className,
}: ConicBorderProps) {
  /* Every colour resolves through a `var(..., fallback)` chain, so the
     component works with zero configuration and is themeable by setting one
     property on any ancestor. `Canvas` is the system background keyword — a
     last resort that is at least the right polarity in both colour schemes. */
  const style: StyleWithVars = {
    '--kx-conic-duration': `${durationMs}ms`,
    '--kx-conic-width': thickness,
    '--kx-conic-radius': radius,
    '--kx-conic-glow': glow ?? 'var(--conic-glow, currentColor)',
    '--kx-conic-rest':
      rest ?? 'var(--conic-rest, color-mix(in oklab, currentColor 10%, transparent))',
    '--kx-conic-fill': fill ?? 'var(--conic-fill, var(--color-bg, Canvas))',
  };

  return (
    <>
      <style href="kinetic-conic-property-border" precedence="medium">
        {CONIC_BORDER_CSS}
      </style>
      <div
        className={cn('kx-conic', className)}
        style={style}
        data-paused={paused ? 'true' : undefined}
      >
        {children}
      </div>
    </>
  );
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nothing to clean up. There is no listener, no timer and no animation frame; unmounting the element removes the only thing that was running. The hoisted `<style>` is reference-counted by React and removed when the last instance unmounts.

**Reduced motion.** A `@media (prefers-reduced-motion: reduce)` block sets `animation: none` and pins `--kx-conic-angle` to 132deg. The gradient border stays — same colours, same thickness — it simply does not revolve. Nothing is removed from the layout and no size changes.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Animating the custom property without registering it with `@property`. The animation runs — `getComputedStyle` even reports it — but the gradient snaps from its start angle to its end angle at the halfway point, because an unregistered custom property interpolates as a discrete token stream. This is the single most common way this effect is reported "broken".
- Writing `border: 1.5px solid` with no colour, or omitting the border entirely. With no border there is no border-box area outside the padding box, the conic layer is fully covered by the fill layer, and the ring is invisible. The border must exist and must be transparent.
- Putting the fill layer second in the `background` list. Backgrounds paint first-listed on top; with the order reversed the flat fill is painted underneath and the conic gradient covers the entire box, not just the ring.
- Leaving `inherits` at its default of `true`. Descendants then inherit an animating value, so the browser recomputes styles for the whole subtree every frame. On a card with 40 children this shows up as a steady 3-5 ms of style recalculation per frame in a performance profile.
- Assuming the animation is compositor-driven and reaching for `will-change: transform`. It is not: animating a registered property repaints the element background on the main thread every frame. That is cheap on a button and expensive on a full-width hero — scale the element, not the hint.
- Using a semi-transparent interior fill. The conic layer extends under the whole border box, so anything less than opaque lets the gradient bleed through the middle of the card.

## Notes

- `@property` needs Safari 16.4+, Chrome 85+, Firefox 128+. Where it is unsupported the `@property` rule is dropped, the keyframe cannot animate the custom property, and `from var(--kx-conic-angle)` falls back to the guaranteed-invalid initial value — the conic gradient still paints from 0deg. The degradation is a static two-highlight ring, which is an acceptable border on its own.
- The CSS ships inside the component as a `<style href precedence>` element. React 19 hoists it into `<head>` and de-duplicates by `href`, so any number of instances contribute one rule set and one `@property` registration.
- The class name is prefixed `kx-` rather than scoped per instance on purpose: `@property` registration is document-global, so per-instance scoping would buy nothing and cost a style element per mount.

## Definition of done

Two bright arcs travel continuously around the border and pass the corners without pausing or jumping — in particular, nothing snaps at the halfway point of the cycle. The interior stays fully opaque. Set `paused` and the arcs freeze where they are. Enable reduced motion at the OS level and the ring is still coloured but completely still.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: One Reveal Engine, Two Axes

Lines rise out of a clipping box and fade up as their group enters. The interesting part is that the same builder serves a vertical page section and a panel riding a pinned horizontal strip — handed the strip's tween as `containerAnimation`, ScrollTrigger measures against that timeline's progress instead of scroll position. One set of numbers, two directions, nothing to keep in sync by hand.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

The same staggered line reveal fires for vertical sections and for panels on a horizontal track.

- Category: scroll
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. The subtree is scanned for `[data-reveal-group]` elements; each becomes one ScrollTrigger. A subtree with no groups reveals as a single group rooted on the component itself.
2. Inside a group, every `[data-reveal]` element is a target of one `gsap.fromTo` running `{ yPercent: 110, opacity: 0.15 }` to `{ yPercent: 0, opacity: 1 }` on `power3.out` with a 0.12 s stagger — so the group is one tween, not one tween per line, and the stagger is real rather than simulated with delays.
3. When a `containerAnimation` is supplied it is spread into the trigger vars and the position keywords flip from `top 88% / top 45%` to `left 85% / left 45%`, because a trigger attached to a container animation measures along that container's axis.
4. The `containerAnimation` prop is tri-state: `undefined` means vertical flow, an animation means horizontal, and `null` means "a sibling owns the timeline and has not built it yet" — in which case nothing is built at all this commit.
5. `scrub: 0.4` ties the reveal to scroll position with a short catch-up, so reversing direction reverses the reveal instead of replaying it.
6. Everything is created inside a `gsap.context` scoped to the root, so `ctx.revert()` kills the triggers and restores the inline `transform` and `opacity` the tween wrote.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `lift = 110`
  Start offset as a percentage of the element's own height. 100 puts the line exactly at the bottom edge of its clipping box; 110 adds a sliver of overshoot so descenders are hidden through the whole travel rather than peeking under the mask on the first frame.
- `START_OPACITY = 0.15`
  Not 0. A line that fades from fully transparent reads as two separate events — a fade and a move. Starting at 0.15 makes the movement the thing you notice and the fade a supporting detail.
- `stagger = 0.12`
  Seconds between lines within a group. Below ~0.06 the lines read as one block; above ~0.2 the last line arrives after the eye has already moved on, which reads as lag rather than rhythm.
- `scrub = 0.4`
  Short catch-up so the reveal follows the scrollbar but survives a wheel step. At 0 the tween inherits every input spike; above ~1 the lines are still arriving after the section has left.
- `start / end (horizontal) = 'left 85%' / 'left 45%'`
  With `containerAnimation` the trigger is measured along the container's axis. Vertical keywords resolve to a position the element never occupies on that axis, so the tween simply never runs.

## API

```ts
function AxisReveals(props: { children: ReactNode; scroller?: RefObject<HTMLElement | null>; containerAnimation?: gsap.core.Animation | null; scrub?: number; lift?: number; stagger?: number; className?: string }): JSX.Element
```

- `children: ReactNode`
  Markup containing `[data-reveal-group]` scopes and `[data-reveal]` targets.
- `scroller: RefObject<HTMLElement | null>`
  Scroll container the triggers read. Omit for the document.
- `containerAnimation: gsap.core.Animation | null`
  Omit for vertical flow, pass a horizontal tween to measure against it, pass `null` to hold off until that tween exists.
- `scrub: number` — default `0.4`
  Seconds of catch-up on the reveal.
- `lift: number` — default `110`
  Start offset as a percentage of the element height.
- `stagger: number` — default `0.12`
  Seconds between elements inside a group.
- `className: string`
  Merged onto the wrapper. Use `contents` when the wrapper must not affect layout.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function AxisReveals({
  children,
  scroller,
  containerAnimation,
  scrub = 0.4,
  lift = 110,
  stagger = 0.12,
  className,
}: AxisRevealsProps) {
  const root = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();

  useEffect(() => {
    const rootEl = root.current;
    if (!rootEl || reduced) return;
    // Explicit "not ready": a sibling owns the timeline and has not built it.
    if (containerAnimation === null) return;

    const scrollerEl = scroller?.current ?? undefined;
    const horizontal = containerAnimation !== undefined;

    const ctx = gsap.context(() => {
      const groups = Array.from(rootEl.querySelectorAll<HTMLElement>('[data-reveal-group]'));
      // A subtree with no explicit groups reveals as one group.
      const scopes = groups.length > 0 ? groups : [rootEl];

      for (const group of scopes) {
        const targets = Array.from(group.querySelectorAll<HTMLElement>('[data-reveal]'));
        if (targets.length === 0) continue;

        gsap.fromTo(
          targets,
          { yPercent: lift, opacity: START_OPACITY },
          {
            yPercent: 0,
            opacity: 1,
            ease: 'power3.out',
            duration: 1,
            stagger,
            scrollTrigger: {
              trigger: group,
              scroller: scrollerEl,
              // The line everyone gets wrong. With `containerAnimation` the
              // trigger measures along the container's axis, so the position
              // keywords must be horizontal. "top 85%" against a horizontal
              // container resolves to a position the element never occupies,
              // and the reveal silently never fires.
              start: horizontal ? 'left 85%' : 'top 88%',
              end: horizontal ? 'left 45%' : 'top 45%',
              scrub,
              // Spreading rather than passing `undefined`: ScrollTrigger
              // branches on the key's presence, not on its value.
              ...(containerAnimation ? { containerAnimation } : {}),
            },
          },
        );
      }
    }, rootEl);

    return () => ctx.revert();
  }, [scroller, containerAnimation, scrub, lift, stagger, reduced]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `ctx.revert()` on unmount and on every dependency change: it kills each group's tween and ScrollTrigger and restores the inline `transform` and `opacity` GSAP wrote, so a re-mount measures clean markup rather than the last run's end state.

**Reduced motion.** No triggers are created and no `fromTo` runs, so every line renders at its final position and full opacity on first paint. The clipping boxes stay in the markup and do nothing, so the layout is byte-for-byte the finished state.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Keeping vertical keywords when passing `containerAnimation`. `start: "top 85%"` produces no error, no warning and no animation — the panels simply arrive already revealed, and the bug survives review because nothing is broken, only absent.
- Passing `containerAnimation: undefined` explicitly. ScrollTrigger branches on whether the key exists, so an `undefined` value is not the same as an absent key; the code spreads the object conditionally for exactly this reason.
- Treating a not-yet-built timeline as the vertical case. The strip's tween is created in a sibling effect and arrives one render later, so a naive `containerAnimation ?? undefined` builds a full set of vertical triggers on horizontal content and tears them down on the next commit — visible as a flash of pre-revealed panels.
- Writing a second reveal system for the horizontal section. Two systems mean two staggers, two easings and two sets of position keywords, and they diverge the first time someone tunes one of them.
- Building one tween per line instead of one tween per group. Stagger stops being a property of the group and becomes a pile of hand-computed delays, which no longer reverse correctly when the user scrolls back up.

## Notes

- Combine with `pinned-horizontal-track`: pass its `onTrack` payload's `animation` straight into `containerAnimation`.
- ScrollTrigger forbids `pin` on a trigger that has a `containerAnimation`. Pin the strip's section, never the panels riding it.

## Definition of done

Scroll the vertical section: the three lines rise out of their masks in sequence and reverse cleanly when you scroll back up. Keep scrolling into the pinned strip: each panel's lines rise with the same rhythm as it crosses the container, not as it crosses the viewport. With reduced motion on, every line is already in place.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Converging Flow Steps

A process diagram that assembles itself as you scroll. The two outer cards converge toward the middle from opposite ends while the connectors between them pop in at 35% through the timeline — after the cards are already moving. That ordering is the entire effect: connectors that arrive first read as "boxes with arrows", connectors that arrive during the movement read as "these things connect".

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A process diagram that closes from both ends while the connectors pop in a third of the way through.

- Category: scroll
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. One `gsap.timeline` on a `scrollTrigger` with `start: "top 92%"`, `end: "center 52%"` and `scrub: 1.2` — deliberately the slowest scrub in the set, because a diagram should settle rather than track the wheel.
2. The first and last cards get `fromTo` tweens at position 0 with `±14` on the layout axis, so they close toward the centre from opposite ends. Cards in between have nowhere to converge from and only fade; giving them a direction too makes the row look shuffled rather than closing.
3. The connectors get `fromTo({ autoAlpha: 0, scale: 0.6 }, { autoAlpha: 1, scale: 1, stagger: 0.2 })` placed at absolute timeline position `0.35`. The card tweens run 0 → 1, so 0.35 is a third of the way into their travel.
4. The convergence axis is chosen from the measured container width, not the viewport: under `stackBelow` px the row becomes a column and the tweens switch from `xPercent` to `yPercent`. A stacked column with horizontal convergence has cards sliding past each other sideways.
5. The single-step case is handled explicitly — `first === last` would otherwise mean two `fromTo` tweens fighting over one element, one pulling it from -14 and one from +14.
6. `ease: "none"` throughout. Under a scrub the ease applies to timeline time, so easing here desynchronises the two converging cards from each other.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `scrub = 1.2`
  Over a second of catch-up — very slow. Right for a diagram, which you want to see settle; wrong for a hero, which would feel unresponsive. Below ~0.6 the diagram snaps together as fast as you scroll and the assembly reads as a jump.
- `connectorAt = 0.35`
  Absolute timeline position, in seconds, where the connectors start. The cards run 0 → 1, so this is a third of the way into their travel. At 0 the arrows are present before there is anything to connect; past ~0.6 they arrive after everything has stopped and read as an afterthought.
- `converge = 14`
  Percent of the card's own size. Small on purpose: this is a settling gesture, not an entrance. Past ~25% the outer cards start visibly outside the tinted wrapper and the diagram looks broken at the start of the scrub.
- `CONNECTOR_SCALE = 0.6`
  Starting scale for the pop. Below ~0.4 the arrow is a dot for the first half of its tween; above ~0.8 there is no pop left to see.
- `connectorStagger = 0.2`
  Seconds between connectors. Long enough that a three-step flow reads left to right rather than all at once, which is what tells the reader the diagram has a direction.
- `stackBelow = 420`
  Container width in px below which three cards in a row are too narrow to hold a title and a line of body. Measured from the element, not the window, because this component is usually inside a column that is narrow while the window is wide.

## API

```ts
function ConvergingFlowSteps(props: { steps: { title: string; body?: string; kicker?: string }[]; converge?: number; scrub?: number; connectorAt?: number; connectorStagger?: number; stackBelow?: number; start?: string; end?: string; scrollerRef?: RefObject<HTMLElement | null>; className?: string }): JSX.Element
```

- `steps: { title: string; body?: string; kicker?: string }[]`
  Ordered steps. Connectors are inserted between consecutive pairs.
- `converge: number` — default `14`
  Outer-card travel as a percentage of its own size, along the layout axis.
- `scrub: number` — default `1.2`
  Seconds of catch-up behind the scroll position.
- `connectorAt: number` — default `0.35`
  Timeline position, in seconds, at which the connectors begin.
- `connectorStagger: number` — default `0.2`
  Seconds between connectors.
- `stackBelow: number` — default `420`
  Container width in px below which the row becomes a column and the axis flips.
- `start: string` — default `'top 92%'`
  ScrollTrigger start.
- `end: string` — default `'center 52%'`
  ScrollTrigger end.
- `scrollerRef: RefObject<HTMLElement | null>`
  The scroll container that owns the scroll position. Omit for the document.
- `className: string`
  Merged onto the wrapper via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const CONNECTOR_SCALE = 0.6;

export function ConvergingFlowSteps({
  steps,
  converge = 14,
  scrub = 1.2,
  connectorAt = 0.35,
  connectorStagger = 0.2,
  stackBelow = 420,
  start = 'top 92%',
  end = 'center 52%',
  scrollerRef,
  className,
}: ConvergingFlowStepsProps) {
  const root = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();
  const { width } = useResizeObserver(root);

  // The convergence axis has to follow the layout axis, or a stacked column
  // gets cards sliding in sideways past each other. Measured from the element
  // rather than the viewport: this component is often inside a panel that is
  // narrow while the window is wide.
  const stacked = width > 0 && width < stackBelow;

  useGsap(
    gsap,
    () => {
      const container = root.current;
      if (!container || reduced) return;

      const cards = Array.from(container.querySelectorAll<HTMLElement>('[data-flow-card]'));
      const connectors = Array.from(
        container.querySelectorAll<HTMLElement>('[data-flow-connector]'),
      );
      const first = cards[0];
      const last = cards[cards.length - 1];
      if (!first || !last) return;

      const axis = stacked ? 'yPercent' : 'xPercent';
      const tl = gsap.timeline({
        scrollTrigger: {
          trigger: container,
          scroller: scrollerRef?.current ?? undefined,
          start,
          end,
          scrub,
          invalidateOnRefresh: true,
        },
      });

      // Outer cards travel toward the centre from opposite ends. When there is
      // only one card, `first === last` and the two tweens would fight over
      // the same target, so it takes the middle treatment instead.
      if (first === last) {
        tl.fromTo(first, { autoAlpha: 0 }, { autoAlpha: 1, ease: 'none', duration: 1 }, 0);
      } else {
        tl.fromTo(
          first,
          { autoAlpha: 0, [axis]: -converge },
          { autoAlpha: 1, [axis]: 0, ease: 'none', duration: 1 },
          0,
        );
        tl.fromTo(
          last,
          { autoAlpha: 0, [axis]: converge },
          { autoAlpha: 1, [axis]: 0, ease: 'none', duration: 1 },
          0,
        );
      }

      // Everything between the ends has nowhere to converge from, so it only
      // fades. Giving it a direction too would make the row look like it was
      // being shuffled rather than closing.
      const middle = cards.slice(1, -1);
      if (middle.length > 0) {
        tl.fromTo(middle, { autoAlpha: 0 }, { autoAlpha: 1, ease: 'none', duration: 1 }, 0);
      }

      if (connectors.length > 0) {
        tl.fromTo(
          connectors,
          { autoAlpha: 0, scale: CONNECTOR_SCALE },
          {
            autoAlpha: 1,
            scale: 1,
            ease: 'none',
            duration: 1 - connectorAt,
            stagger: connectorStagger,
          },
          // Absolute timeline position in seconds. The cards occupy 0 -> 1, so
          // 0.35 puts the first connector a third of the way into their
          // travel: they are already moving when the link appears.
          connectorAt,
        );
      }
    },
    root,
    [converge, scrub, connectorAt, connectorStagger, start, end, stacked, reduced, steps.length],
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useGsap` reverts the `gsap.context` on unmount and whenever the layout axis or any timing prop changes. That kills the ScrollTrigger and strips the inline transform and opacity from every card and connector, which matters here because the axis flip rebuilds the whole timeline on resize and a stale trigger would keep writing `xPercent` to elements now laid out in a column.

**Reduced motion.** No timeline is built, so the diagram renders assembled: cards at their layout positions, connectors at full opacity and scale. The layout still responds to container width, because that is layout rather than motion.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Animating the connectors at position 0 alongside the cards. Everything arriving together reads as a set of boxes that happen to have arrows between them; the whole point is that the link appears while the boxes are still closing.
- Giving the middle cards a convergence direction too. With every card sliding, the row reads as being reshuffled rather than closing, and the two outer cards stop being the subject.
- Not handling the one-step case. `cards[0]` and `cards[cards.length - 1]` are the same element, so it receives two `fromTo` tweens with opposite start values and ends up wherever the second one decided.
- Choosing the layout axis from `window.innerWidth`. The component is usually inside a content column; a wide window with a narrow column stacks the cards visually while the tweens still converge horizontally, so they cross each other on the way in.
- Using `opacity` rather than `autoAlpha` on the connectors. An invisible SVG still takes hit-testing area between two cards, which quietly swallows clicks aimed at the card edges.
- Assuming `stagger` inside a scrubbed timeline behaves like duration. Each connector's start is offset in timeline seconds, so a large stagger pushes the timeline total past the card tweens and the cards finish before the scroll range ends — which is intended here, but is a surprise if you assumed the total was 1.

## Notes

- The wrapper tint is derived from the accent token rather than a second hard-coded colour, so re-theming the accent moves the panel with it.
- Connectors are inline SVG paths, so they inherit `currentColor` and need no asset.

## Definition of done

Scroll the diagram into view: the leftmost and rightmost cards slide toward the middle, and only once they are moving do the arrows between them scale up one after the other. Stop scrolling mid-way and the diagram keeps settling for more than a second. Narrow the container below 420px and the same sequence plays vertically with the arrows rotated. With reduced motion on, the diagram is complete before it scrolls into view.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Converging Headline Words

A stacked headline assembles out of the margins as you approach it. Odd lines enter from the right, even lines from the left, and both land on zero at the same scrub position, so they cross the frame in opposite directions and lock into a sentence. Because the tween is scrubbed, scrolling back up disassembles it — the headline is a function of scroll position, not a playback that has happened or not happened.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Headline words slide in from opposite margins and lock into a sentence, pinned to scroll position.

- Category: text
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. Each word is a block-level span with `data-word`. A single `gsap.timeline` with a `scrollTrigger` holds one `fromTo` per word, all inserted at position `0`, so every word shares the timeline's full length and therefore the full scroll range.
2. The travel is `xPercent`, not `x`: percent of *the element's own width*, so a short word and a long word both start entirely outside the frame and neither needs a hand-tuned pixel value.
3. Direction alternates on index parity — `i % 2 === 0 ? -travel : travel` — and the text alignment alternates with it, so each word enters from the side it is aligned to and travels the shortest distance to its resting place.
4. `ease: "none"` on every tween. Under `scrub` the scroll position *is* the easing curve; layering `power2.out` on top means the words accelerate away from the scrollbar and then wait for it, which is precisely the sensation people describe as the scroll feeling sticky.
5. `fromTo`, not `to`. A bare `to` reads its start value from the DOM, and the DOM already says `xPercent: 0` because the rendered markup is the assembled headline — that is what the no-JS and reduced-motion renders show.
6. `gsap.registerPlugin(ScrollTrigger)` is called inside the effect rather than at module scope, because `registerPlugin` touches `window` and this module is still evaluated during server rendering.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `TRAVEL = 120`
  Percent of each word's own width. At exactly 100 the word starts flush against the frame edge and is already peeking in on the first pixel of scroll; the extra 20% buys a moment of empty margin before it arrives.
- `SCRUB = 1`
  One second of catch-up between the scrollbar and the words. `scrub: true` welds them exactly, which on a trackpad exposes every jitter in the input; past ~1.5s the headline is still assembling well after the reader has stopped scrolling.
- `START = 'top bottom'`
  The scrub begins the instant the headline's top edge enters the viewport. Starting later means the words are still outside the frame when the headline is already half on screen, which reads as missing content rather than as an entrance.
- `END = 'top 25%'`
  Assembly completes when the headline top reaches the upper quarter of the viewport. Ending at centre leaves the headline unresolved while it is the dominant thing on screen; ending earlier compresses the whole effect into the bottom sliver of the viewport.

## API

```ts
function ConvergingScrubWords(props: { words: string[]; travel?: number; scrub?: number; start?: string; end?: string; scroller?: Element | null; className?: string }): JSX.Element
```

- `words: string[]`
  One per line. Even indices enter from the left, odd from the right.
- `travel: number` — default `120`
  Percent of each word's own width that it starts offset by.
- `scrub: number` — default `1`
  Seconds of catch-up between the scrollbar and the words.
- `start: string` — default `'top bottom'`
  ScrollTrigger `start`.
- `end: string` — default `'top 25%'`
  ScrollTrigger `end`.
- `scroller: Element | null` — default `null`
  Scroll container, when the headline is not in the document scroller.
- `className: string`
  Merged onto the wrapper via `cn` — type size and tracking go here.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const TRAVEL = 120;
const SCRUB = 1;
const START = 'top bottom';
const END = 'top 25%';

export function ConvergingScrubWords({
  words,
  travel = TRAVEL,
  scrub = SCRUB,
  start = START,
  end = END,
  scroller = null,
  className,
}: ConvergingScrubWordsProps) {
  const root = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();

  useEffect(() => {
    const el = root.current;
    // Reduced motion: the JSX below already renders the assembled headline at
    // its final position, so declining to attach the trigger is the whole
    // implementation. Nothing is hidden and nothing is left off-screen.
    if (!el || reduced) return;

    // Registered here rather than at module scope: registerPlugin touches
    // window, and this file is still evaluated during server rendering.
    gsap.registerPlugin(ScrollTrigger);

    const wordEls = Array.from(el.querySelectorAll<HTMLElement>('[data-word]'));
    if (wordEls.length === 0) return;

    const ctx = gsap.context(() => {
      const tl = gsap.timeline({
        scrollTrigger: {
          trigger: el,
          scroller: scroller ?? undefined,
          start,
          end,
          scrub,
        },
      });

      wordEls.forEach((w, i) => {
        // fromTo, not to. A bare `to` would read the start value off the DOM,
        // and the DOM already says 0 because the inline style below is the
        // final position for the no-JS and reduced-motion renders.
        tl.fromTo(
          w,
          { xPercent: i % 2 === 0 ? -travel : travel },
          { xPercent: 0, ease: 'none' },
          0,
        );
      });
    }, el);

    return () => ctx.revert();
  }, [words, travel, scrub, start, end, scroller, reduced]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `ctx.revert()` on the `gsap.context` scoped to the root. That kills the timeline, disposes the ScrollTrigger instance (so it stops measuring a detached element and stops contributing to `ScrollTrigger.refresh()`), and strips the inline transforms GSAP wrote.

**Reduced motion.** No ScrollTrigger is attached and no tween is created. The markup React renders is already the assembled headline at `xPercent: 0`, so the finished sentence is on screen from first paint — nothing is off-screen waiting for a scroll that will not drive it.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Using an ease other than `none` under `scrub`. The words lead or lag the scrollbar and the page feels like it is fighting the input — the single most common complaint about scrubbed animation.
- Using `to` instead of `fromTo`. GSAP samples the current DOM value as the start, which is the resting position, so nothing moves — or worse, it moves only after a resize invalidates the cached start.
- Animating `x` in pixels. A word that is 400px wide and one that is 120px wide need different offsets to clear the frame; `xPercent` is self-scaling and survives a font-size change.
- Setting `overflow: hidden` on the container. It stops the horizontal scrollbar, but CSS forces `overflow-y` to `auto` when one axis is `hidden`, which silently breaks any sticky ancestor and clips descenders. `overflow-x: clip` does the same job without that side effect.
- Omitting the `scroller` option when the headline lives inside a scrolling panel rather than the document. ScrollTrigger measures against the window, so the trigger fires at the wrong time or never.
- Registering ScrollTrigger at module scope. `registerPlugin` reaches for `window` and throws during server rendering.
- Cleaning up with `kill()` on the timeline only. The ScrollTrigger instance survives and keeps measuring a detached element; `ctx.revert()` disposes both and strips the inline transforms.

## Notes

- No text-splitting library: the words arrive as an array prop and are rendered as spans by React. A splitter would add a dependency and a DOM-mutation lifecycle for something the caller already has as data.
- If you feed this component text you split elsewhere, gate the split on `document.fonts.ready` — measuring before the webfont lands gives fallback-font line breaks that never re-flow. See `font-safe-text-split`.
- The `scroller` prop exists so the component can be demoed and used inside an `overflow-y-auto` panel rather than only in the document scroller.

## Definition of done

Scroll down slowly: the words travel inward from alternating sides and are exactly aligned when the headline top reaches the upper quarter of the viewport. Scroll back up and they separate again, tracking the scrollbar. No horizontal scrollbar appears on the document at any point. With reduced motion enabled the assembled headline is present on first paint and does not move.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Raycaster-Free Hover Picking

A ring of plates spins entirely on the compositor, so the main thread has no idea where anything is. Instead of measuring the DOM, the component recomputes the same transform in JavaScript — rotate, tilt, perspective divide — and hit-tests the resulting screen points against the pointer. A crosshair marks the computed position so you can see the mirror agreeing with the pixels.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Run the GPU's transform again on the CPU and hit-test the result. No raycaster, no rect reads.

- Category: primitive
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. The spin is one `Element.animate` keyframe pair with `iterations: Infinity`. It runs off the main thread, which means it keeps time even while JS is busy, and means the main thread must reconstruct the angle rather than remember it: `animation.currentTime` divided by the period gives the exact phase the compositor is drawing.
2. The mirror is four lines that shadow the CSS one for one. Two nested `rotateY` (ring spin, plate angle) collapse into a single angle sum, so a plate centre sits at `(r·sin a, 0, r·cos a)`. The stage `rotateX` turns that depth into vertical offset. The perspective divide `d / (d − z)` reproduces what the browser does with the `perspective` property.
3. Picking runs once per frame, not per `pointermove`. The geometry moves under a stationary cursor, so the correct answer changes on frames where no input arrived at all. An event-driven hit test would leave the hover state stuck on whatever plate happened to be there when the pointer last moved.
4. Plates with `z <= 0` are rejected before the distance compare. They are on the far side of the ring, drawn behind the near plates, and picking them would let a click pass through the front of the object.
5. The winner is the nearest projected point within a squared pick radius. Squared, because a comparison against `r²` gives the same ordering as a comparison against `r` without the square root.
6. This is the only correct approach when a vertex shader, a CSS transform, or GPU skinning moves the geometry after it leaves JavaScript. The CPU-side geometry never changed, so `Raycaster` intersects the undeformed mesh and reports hits on a shape that is not on screen. Mirroring the vertex transform on the CPU is the fix — the same maths, applied to one point instead of every vertex.
7. Everything inside the perspective root is `pointer-events: none`. There is nothing for the browser to hit-test; the container takes the pointer and the mirror decides what was under it.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `PERSPECTIVE = 900`
  Shared by the CSS `perspective` property and the JS divide. If the two ever disagree the crosshair drifts away from the plate it is meant to mark — which makes this the single most important value to keep in one place.
- `TILT = 16`
  Degrees of stage lean. Enough that the ring reads as a ring rather than a row; past ~30° the far plates hide behind the near ones and picking gets ambiguous even with the depth rejection.
- `PICK_RADIUS = 44`
  The pointer must land within 44 px of a projected centre. Matches the 44 px minimum touch target, and is wide enough to forgive the plate scaling down as it recedes.
- `PICK_RADIUS_SQ = PICK_RADIUS * PICK_RADIUS`
  Compared against squared distance so the loop never calls `Math.sqrt`. Fourteen square roots a frame is not a real cost, but the squared compare is free and is the habit worth having in a loop that might hold a thousand points.
- `RADIUS_RATIO = 0.36`
  Ring radius as a fraction of container width. Keeps the ring inside the box at its widest and leaves room for the pick-radius halo at the edges.
- `SPIN_PERIOD = 26`
  Seconds per revolution. Slow enough that a plate stays under the cursor long enough to click, fast enough that the per-frame re-pick is visibly necessary.

## API

```ts
function CpuMirrorPicking(props: { count?: number; period?: number; showMirror?: boolean; className?: string }): JSX.Element
```

- `count: number` — default `14`
  Plates around the ring.
- `period: number` — default `26`
  Seconds per revolution. The mirror divides the animation clock by this.
- `showMirror: boolean` — default `true`
  Draw the computed crosshair and the pick-radius halo.
- `className: string`
  Merged onto the perspective root via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** Must match the CSS `perspective` exactly — the mirror divides by this. */
const PERSPECTIVE = 900;
/** Stage lean, degrees. Matches the CSS `rotateX`. */
const TILT = 16;
const SIN_TILT = Math.sin((TILT * Math.PI) / 180);
const COS_TILT = Math.cos((TILT * Math.PI) / 180);
/** Pointer-to-plate distance that counts as a hit, in CSS pixels. */
const PICK_RADIUS = 44;
const PICK_RADIUS_SQ = PICK_RADIUS * PICK_RADIUS;
const RADIUS_RATIO = 0.36;
const MIN_RADIUS = 64;
const MAX_RADIUS = 190;
const SPIN_PERIOD = 26;

interface Projected {
  x: number;
  y: number;
  z: number;
  scale: number;
}

/**
 * The mirror. Every line here has a counterpart in the element's CSS:
 *
 *   ul   transform: rotateY(spin)              <- from the running animation
 *   li   transform: rotateY(theta) translateZ(radius)
 *   root perspective: PERSPECTIVE
 *   stage transform: rotateX(TILT)
 *
 * A plate's centre starts at the ring origin, so `rotateY(a) translateZ(r)`
 * puts it at (r·sin a, 0, r·cos a) with a = theta + spin. Composing the two
 * rotateY into one addition is the whole trick — the rest is the standard
 * perspective divide.
 */
function project(theta: number, spin: number, radius: number, cx: number, cy: number, out: Projected): void {
  const a = theta + spin;
  const x = Math.sin(a) * radius;
  const depth = Math.cos(a) * radius;
  // rotateX(t): y' = y·cos t − z·sin t, z' = y·sin t + z·cos t. y is 0 here,
  // so the tilt turns depth into vertical offset and shortens the ring.
  const y = -depth * SIN_TILT;
  const z = depth * COS_TILT;
  // CSS perspective: everything at depth z scales by d / (d − z).
  const scale = PERSPECTIVE / (PERSPECTIVE - z);
  out.x = cx + x * scale;
  out.y = cy + y * scale;
  out.z = z;
  out.scale = scale;
}

/**
 * `Animation.currentTime` is typed `CSSNumberish | null`: a plain number in
 * every shipping engine, but the spec permits a CSSNumericValue. Narrow it
 * rather than cast, and treat a null clock (animation not yet started) as 0.
 */
function readMs(anim: Animation | null): number {
  if (!anim) return 0;
  const t = anim.currentTime;
  if (t === null) return 0;
  return typeof t === 'number' ? t : t.to('ms').value;
}

export function CpuMirrorPicking({
  count = 14,
  period = SPIN_PERIOD,
  showMirror = true,
  className,
}: CpuMirrorPickingProps) {
  const root = useRef<HTMLDivElement>(null);
  const ring = useRef<HTMLUListElement>(null);
  const plates = useRef<(HTMLLIElement | null)[]>([]);
  const probe = useRef<HTMLDivElement>(null);
  const halo = useRef<HTMLDivElement>(null);

  const anim = useRef<Animation | null>(null);
  /** Pointer in the root's own coordinate space. Null when it has left. */
  const pointer = useRef<{ x: number; y: number } | null>(null);
  const hovered = useRef(-1);
  const scratch = useRef<Projected>({ x: 0, y: 0, z: 0, scale: 1 });

  const [hover, setHover] = useState(-1);
  const [picked, setPicked] = useState(-1);

  const reduced = useReducedMotion();
  const size = useResizeObserver(root);
  const radius = clamp(size.width * RADIUS_RATIO, MIN_RADIUS, MAX_RADIUS);

  // The compositor owns the spin. One keyframe pair, then the main thread is
  // out of the loop entirely — which is exactly why it has to reconstruct the
  // angle instead of remembering it.
  useEffect(() => {
    const el = ring.current;
    if (!el || reduced) return;
    const a = el.animate(
      [{ transform: 'rotateY(0deg)' }, { transform: 'rotateY(360deg)' }],
      { duration: period * 1000, iterations: Infinity, easing: 'linear' },
    );
    anim.current = a;
    return () => {
      a.cancel();
      anim.current = null;
    };
  }, [period, reduced]);

  const readPointer = useCallback((e: ReactPointerEvent<HTMLDivElement>) => {
    const el = root.current;
    if (!el) return;
    // One rect read per pointer event, for the container only. Reading a rect
    // per plate per event is the version that costs fourteen forced layouts.
    const rect = el.getBoundingClientRect();
    pointer.current = { x: e.clientX - rect.left, y: e.clientY - rect.top };
  }, []);

  const clearPointer = useCallback(() => {
    pointer.current = null;
  }, []);

  useRaf((_dt) => {
    if (size.width === 0) return;

    // Picking runs per frame, not per pointermove. The ring moves under a
    // stationary cursor, so the hit answer changes when nothing was pointed.
    const spin = reduced ? 0 : (readMs(anim.current) / (period * 1000)) * TAU;
    const cx = size.width / 2;
    const cy = size.height / 2;
    const p = pointer.current;
    const out = scratch.current;

    let best = -1;
    let bestDist = PICK_RADIUS_SQ;
    let bestX = 0;
    let bestY = 0;

    for (let i = 0; i < count; i += 1) {
      project((i / count) * TAU, spin, radius, cx, cy, out);

      // The projection pass already knows the depth, so the fade rides along
      // rather than needing a second traversal.
      const el = plates.current[i];
      if (el) {
        const depth = out.z / (radius * COS_TILT);
        el.style.opacity = (0.18 + 0.82 * (depth * 0.5 + 0.5)).toFixed(3);
      }

      // z <= 0 is the far half of the ring: drawn, but behind the near plates
      // and never the intended target of a click.
      if (!p || out.z <= 0) continue;
      const dx = p.x - out.x;
      const dy = p.y - out.y;
      const dist = dx * dx + dy * dy;
      if (dist < bestDist) {
        bestDist = dist;
        best = i;
        bestX = out.x;
        bestY = out.y;
      }
    }

    const marker = probe.current;
    if (marker) {
      marker.style.opacity = best >= 0 ? '1' : '0';
      if (best >= 0) {
        marker.style.transform = `translate3d(${bestX.toFixed(1)}px, ${bestY.toFixed(1)}px, 0) translate(-50%, -50%)`;
      }
    }
    const cursor = halo.current;
    if (cursor) {
      cursor.style.opacity = p ? '1' : '0';
      if (p) {
        cursor.style.transform = `translate3d(${p.x.toFixed(1)}px, ${p.y.toFixed(1)}px, 0) translate(-50%, -50%)`;
      }
    }

    if (best !== hovered.current) {
      hovered.current = best;
      setHover(best);
    }
  });
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The animation is cancelled on unmount or period change, which releases the compositor animation and nulls the ref. The frame loop unsubscribes with the hook; the shared RAF parks itself once no subscriber is left. No listeners are attached outside React.

**Reduced motion.** The spin animation is never created, so the ring holds still at phase zero. Picking is unaffected — the mirror simply reads a spin of 0 — which is the point: the technique is about where things are, not about them moving.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- `getBoundingClientRect()` per plate per pointermove. That is N forced layouts per event, and the rects are wrong anyway: a compositor-driven transform does not update layout boxes, so every rect reports the plate's unanimated position.
- Hit-testing only on `pointermove`. The ring rotates under a still cursor, so hover has to be re-evaluated every frame or it freezes on a stale plate.
- Letting the CSS and the mirror drift apart. A tweak to `perspective`, the tilt, or the transform order in one place and not the other produces a crosshair that is subtly, maddeningly offset. Keep both reading the same constants.
- Putting `overflow: hidden` on a `transform-style: preserve-3d` element. Overflow is a grouping property: it silently forces the subtree back to flat and the ring collapses into a line.
- Trusting `Raycaster` against a shader-deformed mesh. The vertex shader runs on the GPU; the `BufferGeometry` in memory is the rest pose. The ray intersects the rest pose and hits nothing you can see.
- Reading `animation.currentTime` as a number without narrowing. It is typed `CSSNumberish | null` — null before the animation starts, and permitted by spec to be a `CSSNumericValue`.
- Forgetting the far-half rejection. Without it the ring picks through itself, and a click near the centre selects a plate on the back.

## Notes

- The depth fade rides along on the projection pass that was going to run anyway — one extra style write per plate, no second traversal and no extra maths.
- The same mirror generalises: for a three.js scene, project the object's world position with `vector.project(camera)` and compare in NDC; for a shader-deformed mesh, re-run the deformation for that one vertex on the CPU. The principle is identical — hit-test the transform, not the source geometry.

## Definition of done

Hold the pointer still over a plate: the crosshair tracks the plate as it rotates away and hover releases at the pick radius, with no pointer events involved. Move to the middle of the ring and nothing on the far side lights up. Click and the plate under the crosshair — not the one under a stale rect — is the one that selects. With reduced motion the ring is static and picking still works.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: CSS Variable Stagger Reveal

A reveal system where JavaScript writes one number per element and then gets out of the way. The stagger delay is `calc(var(--kx-reveal-index) * var(--kx-reveal-step))`, so duration, travel, easing and the delay ramp all live in CSS where they can be retuned — or overridden from an unrelated stylesheet — without touching the component. The observer measures against the nearest scrollable ancestor, so the same component works inside a card, a modal, or the document.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Groups reveal as they enter their scroll container; the stagger delay is a CSS calc over an index the JS writes once.

- Category: scroll
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. On mount the component collects `[data-reveal-group]` descendants, falling back to itself as a single group, and writes `--kx-reveal-index` as an inline custom property on each `[data-reveal]` inside each group. Index restarts at zero per group, so a second group does not inherit a delay whose beginning the reader never saw.
2. One shipped rule computes the per-element delay: `--kx-reveal-delay: calc(var(--kx-reveal-index, 0) * var(--kx-reveal-step, 90ms))`, and both the opacity and transform transitions use it as their `transition-delay`. This is the entire stagger — there is no timeline object and no rAF loop anywhere in the component.
3. The start state (`opacity: 0`, `translate3d(0, var(--kx-reveal-distance), 0)`) is a CSS rule rather than an inline style, so it is already in effect before hydration and there is no frame of un-hidden content.
4. An IntersectionObserver with `threshold: 0.15` and `rootMargin: "0px 0px -8% 0px"` sets `data-kx-revealed` on the group. The negative bottom margin shrinks the observation box up from the bottom edge, so an element must be genuinely inside the container rather than merely touching its edge — without it, a reveal fires while the element is still one pixel of its own height into view.
5. The observer `root` is resolved in three steps: an explicit `scroller` ref if given, otherwise a walk up the ancestor chain for the first element whose computed `overflow-x` or `overflow-y` is `auto`, `scroll` or `overlay`, otherwise `null`, which is the value that means the viewport. Nothing in the component references `window`, so it behaves identically in a 320 px preview card and on a full page.
6. Revealed groups are unobserved immediately unless `repeat` is set, so a long page is not still servicing a hundred settled groups. `repeat` instead deletes the attribute on exit, and CSS runs the same transition backwards.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `stepMs = 90`
  Delay per index. Below ~50 ms the elements read as arriving together and the stagger is wasted; above ~140 ms a group of six takes over three quarters of a second to finish and the last line is still moving after the eye has reached it.
- `durationMs = 700`
  Per-element transition duration, roughly 8x the step. Keeping duration well above step is what makes the group overlap into one motion rather than resolve as six separate events.
- `distance = 28px`
  Travel. Small enough that the text never leaves its own line box — a reveal that starts 100 px down reads as an element flying in from elsewhere, which fights the impression that the content was always there.
- `ease = cubic-bezier(0.22, 1, 0.36, 1)`
  An ease-out-quint. Nearly all of the travel happens in the first third, so the element appears to arrive and settle rather than to decelerate the whole way. A symmetric ease-in-out on a reveal always reads as slow.
- `threshold = 0.15`
  Fraction of the group that must be visible. At 0 the reveal fires on a single pixel of intersection, which for a tall group means the stagger completes before the content is on screen. Past ~0.4 a group taller than the container can never satisfy it and never reveals at all.
- `rootMargin = 0px 0px -8% 0px`
  Shrinks the observation box 8% up from the bottom, so the element is genuinely inside the container before it fires. Positive values here are the usual mistake: they fire the reveal below the fold and the user scrolls onto content that has already finished animating.

## API

```ts
function CssVarStaggerReveal(props: { children: ReactNode; scroller?: RefObject<HTMLElement | null>; stepMs?: number; durationMs?: number; distance?: string; ease?: string; threshold?: number; rootMargin?: string; repeat?: boolean; className?: string }): JSX.Element
```

- `children: ReactNode`
  Mark groups with `data-reveal-group` and targets with `data-reveal`. A scope with no groups is treated as one group.
- `scroller: RefObject<HTMLElement | null>`
  Scroll container for the observer. Omit and the nearest scrollable ancestor is found by walking computed overflow.
- `stepMs: number` — default `90`
  Milliseconds of delay per index step. Written as `--kx-reveal-step`.
- `durationMs: number` — default `700`
  Transition duration. Written as `--kx-reveal-duration`.
- `distance: string` — default `'28px'`
  Starting vertical offset, any CSS length. Written as `--kx-reveal-distance`.
- `ease: string` — default `'cubic-bezier(0.22, 1, 0.36, 1)'`
  Timing function. Written as `--kx-reveal-ease`.
- `threshold: number` — default `0.15`
  Fraction of a group that must be visible before it reveals.
- `rootMargin: string` — default `'0px 0px -8% 0px'`
  Observation box inset. The negative bottom means "genuinely in view".
- `repeat: boolean` — default `false`
  Re-hide groups that leave the container. Off by default, which also lets settled groups be unobserved.
- `className: string`
  Merged onto the scope element.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * Nearest ancestor that actually scrolls. `overflow: auto` on an element that
 * has not overflowed yet still counts — it is the container the reveal will
 * live inside once content arrives, and testing `scrollHeight > clientHeight`
 * on mount would pick the document instead and fire everything at once.
 *
 * Returns `null` for "the viewport", which is the IntersectionObserver
 * `root` value that means the document.
 */
function nearestScrollParent(node: Element | null): Element | null {
  let el = node?.parentElement ?? null;
  while (el) {
    const { overflowY, overflowX } = getComputedStyle(el);
    const scrollable = /(auto|scroll|overlay)/.test(overflowY + overflowX);
    if (scrollable) return el;
    el = el.parentElement;
  }
  return null;
}

export function CssVarStaggerReveal({
  children,
  scroller,
  stepMs = 90,
  durationMs = 700,
  distance = '28px',
  ease = 'cubic-bezier(0.22, 1, 0.36, 1)',
  threshold = 0.15,
  rootMargin = '0px 0px -8% 0px',
  repeat = false,
  className,
}: CssVarStaggerRevealProps) {
  const root = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const rootEl = root.current;
    if (!rootEl) return;

    const groups = Array.from(rootEl.querySelectorAll<HTMLElement>(GROUP_SELECTOR));
    // A subtree with no declared groups is one group: the scope itself.
    const scopes: HTMLElement[] = groups.length > 0 ? groups : [rootEl];

    // Index is per group, not per document. Two sibling groups both start
    // their stagger at zero, so the second one does not inherit a delay the
    // reader never sees the beginning of.
    for (const group of scopes) {
      const targets = group.querySelectorAll<HTMLElement>(REVEAL_SELECTOR);
      targets.forEach((target, i) => {
        target.style.setProperty('--kx-reveal-index', String(i));
      });
    }

    const reveal = (group: HTMLElement) => {
      group.dataset.kxRevealed = 'true';
    };

    // No observer available: reveal rather than leave the content at
    // opacity 0 forever. A missing API must degrade to visible content.
    if (typeof IntersectionObserver === 'undefined') {
      for (const group of scopes) reveal(group);
      return;
    }

    // `undefined` from the prop means "find it"; `null` from the walk means
    // "the document", which is what IntersectionObserver's root expects.
    const container = scroller ? scroller.current : nearestScrollParent(rootEl);

    const observer = new IntersectionObserver(
      (entries) => {
        for (const entry of entries) {
          const target = entry.target;
          if (!(target instanceof HTMLElement)) continue;
          if (entry.isIntersecting) {
            reveal(target);
            // One-shot is the default: stop watching immediately so a long
            // page is not still servicing a hundred settled groups.
            if (!repeat) observer.unobserve(target);
          } else if (repeat) {
            delete target.dataset.kxRevealed;
          }
        }
      },
      { root: container ?? null, rootMargin, threshold },
    );

    for (const group of scopes) observer.observe(group);
    return () => observer.disconnect();
  }, [scroller, threshold, rootMargin, repeat]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `observer.disconnect()` in the effect teardown, which releases the observer's references to every group. The inline `--kx-reveal-index` properties and the `data-kx-revealed` attributes live on nodes React owns and are discarded with them. There is no rAF, no listener and no timer to cancel — the hoisted `<style>` is reference-counted and removed by React when the last instance unmounts.

**Reduced motion.** A `@media (prefers-reduced-motion: reduce)` block in the shipped rule set resolves every target to its END state — `opacity: 1`, `transform: none`, `transition: none` — so the content is simply present, with no travel and no delay ramp to sit through. The observer still runs and still sets `data-kx-revealed`, so anything else keyed off that attribute keeps working; it just has nothing to transition.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Writing the delay as an inline `transition-delay` per element. It works, and it moves the choreography into JavaScript where a designer cannot reach it and a stylesheet cannot override it. The point of the index-as-custom-property indirection is that JS contributes a number and CSS owns every unit.
- Numbering targets across the whole scope instead of per group. The second group starts at index 6 and sits at a 540 ms delay, so the reader watches nothing happen for half a second after it enters view.
- Assuming the scroll container is the window. Inside any `overflow-y: auto` panel, an observer with `root: null` compares against the viewport: everything in the panel is "in view" from the start, so the entire page reveals at once on mount and never staggers again.
- Testing `scrollHeight > clientHeight` when hunting for the scroll parent. A panel that has not overflowed yet is still the container the reveal will live inside once content arrives; rejecting it picks the document and fires everything at once.
- Putting the hidden start state in an inline style set from an effect. The server-rendered markup then paints visible, hides on hydration, and animates — a flash of correct content followed by a reveal, which is worse than no reveal.
- Shipping a hidden-by-default rule with no escape hatch for a document that never runs scripts. `@media (scripting: none)` restores opacity and transform; without it the page is simply blank for anyone who has JS off.
- Leaving the observer connected. It keeps a strong reference to every observed group, so an unmounted section is still measured on every scroll of the container that outlived it.
- Adding only `[data-kx-revealed] [data-reveal]` as the revealed selector. When the scope declares no groups, the marker lands on the scope element itself, which is not a descendant of itself — so the reveal silently never applies.

## Notes

- Every knob is a custom property, which means a consumer can retune the whole system from any ancestor: `--kx-reveal-step`, `--kx-reveal-duration`, `--kx-reveal-distance`, `--kx-reveal-ease`. The props are conveniences that write those same properties onto the scope element.
- This is the CSS-owned sibling of the GSAP reveal systems in the registry. Choose this one when the choreography is a fade-and-rise and the value is that a designer can retune it; choose a GSAP builder when the reveal needs scrubbing, a per-element timeline, or to be measured against a horizontal container animation.
- The observer watches groups, not individual elements. A group that is taller than its container reveals when 15% of it is visible — if a section is very tall, wrap the parts you want revealed separately in their own `data-reveal-group`.

## Definition of done

Scroll the container: each group's children rise and fade in one after another, about 90 ms apart, and the group does not start until it is genuinely inside the box rather than touching its bottom edge. Inspect a revealed child and its computed `transition-delay` equals index x 90 ms. Set `--kx-reveal-step: 200ms` on any ancestor in dev tools and the stagger widens immediately with no re-render. With reduced motion on, everything is already visible and in place. Unmount the scroller and no observer callbacks fire.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Cursor Clip-Path Mask

An upper layer is clipped to a circle that trails the pointer, so a disc of alternate content moves across a base layer. GSAP never tweens `clip-path`; it tweens a plain `{ x, y, r }` object and one `onUpdate` writes both the clip string and the ring outline from the same numbers on the same frame.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A disc of a second layer follows the pointer; hovering the trigger grows it until it covers the panel.

- Category: cursor
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. The animated value is a proxy object, not a DOM property. `gsap.to(proxy, { x, y, onUpdate: write })` gives normal tween semantics — easing, overwrite, duration — over three plain numbers, and `write()` turns them into a `clip-path` string plus a transform for the ring.
2. That indirection is the whole point. Tweening `clipPath` directly means GSAP parses and re-serialises a string each frame, and the ring outline drawn on top must be animated by a second, independent tween. Two interpolations of the same idea drift under fast movement, and a visible sliver of base layer appears between the ring and the edge of the disc.
3. It also lets position and radius be separate tweens with different durations and eases — 0.4s linear for the follow, 0.55s `power3.inOut` for the expansion — while still producing one coherent write. That is not expressible as a single `clipPath` tween.
4. The radius is written in px, not `%`. A percentage radius in `circle()` resolves against `sqrt(w^2 + h^2) / sqrt(2)`, not against the width, so the same percentage is a different physical size at every aspect ratio and the px-sized ring stops matching the disc it is supposed to outline.
5. Expansion targets `Math.hypot(clientWidth, clientHeight)` — one full diagonal, which is enough to cover the panel from any point inside it, including a corner.
6. The ring is a fixed-diameter element scaled by `r / radius` rather than an element whose width and height are rewritten, so each frame is a composited transform instead of a layout pass.
7. Hover detection uses `pointerover`/`pointerout` on the container, which bubble, so one listener pair covers every trigger in the subtree regardless of how React re-renders it. `pointerenter` does not bubble and would need a listener per trigger plus subscription bookkeeping.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `radius = 130`
  Resting disc radius in px. Small enough that the base layer still dominates and the disc reads as an instrument, large enough to show a readable fragment of the layer underneath. Below ~60 you are looking through a keyhole and cannot tell what the reveal layer is.
- `FOLLOW_DURATION = 0.4`
  Seconds of catch-up on position. Long enough that the disc reads as being dragged rather than teleported, short enough that it is still under the pointer when you stop to read what is inside it.
- `ease: 'none' on the follow = linear`
  Deliberately linear, unlike most cursor follows. The end value is remutated on every pointer event, so an eased tween re-eases from a fresh start each time and the disc reads as surging and stalling. Linear catch-up gives one steady drag speed no matter how the pointer moves.
- `EXPAND_DURATION = 0.55`
  Seconds for the disc to grow to a full diagonal and back. The distance travelled is large, so a follow-length 0.4s makes it feel like a cut; past ~0.8s the reveal has not finished before an impatient pointer has left the trigger.
- `expand ease 'power3.inOut' = power3.inOut`
  In-out for the expansion because it is a discrete state change with a beginning and an end, unlike the follow. The slow start keeps the growth from looking explosive; the slow finish stops the edge whipping off-panel.
- `ring opacity ramp = clamp(0, 1, 2 - scale)`
  The ring is scaled, so its 1px border thickens with it. Fading it out by the time the disc has doubled hides that artefact before it becomes visible, and it also gets the outline out of the way of a full-panel reveal.
- `off-panel park = -radius * 3`
  Where the disc sits before the first move and after leaving. Three radii guarantees no part of it clips back into view at any aspect ratio, and the reveal layer is invisible until the pointer earns it.

## API

```ts
function CursorClipPathMask(props: { base: ReactNode; reveal: ReactNode; radius?: number; className?: string }): JSX.Element
```

- `base: ReactNode`
  Always-visible bottom layer, and the layer that keeps all pointer events. Put `[data-mask-trigger]` elements here.
- `reveal: ReactNode`
  Top layer, visible only inside the disc. Clipped, `aria-hidden` and non-interactive.
- `radius: number` — default `130`
  Resting disc radius in CSS px.
- `className: string`
  Merged onto the root container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const FOLLOW_DURATION = 0.4;
const EXPAND_DURATION = 0.55;

export function CursorClipPathMask({
  base,
  reveal,
  radius = 130,
  className,
}: CursorClipPathMaskProps) {
  const root = useRef<HTMLDivElement>(null);
  const overlay = useRef<HTMLDivElement>(null);
  const ring = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const el = root.current;
    const layer = overlay.current;
    const outline = ring.current;
    if (!el || !layer || !outline) return;

    const fine = window.matchMedia('(pointer: fine)').matches;
    const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

    /* One object, three numbers, tweened by GSAP like any DOM property. The
       clip string is derived from it — never tweened itself. */
    const proxy = { x: 0, y: 0, r: radius };

    const write = () => {
      /* Radius in px, not `%`. A percentage radius in `circle()` resolves
         against sqrt(w^2 + h^2) / sqrt(2), NOT against the width — so a
         percentage hole is a different physical size on every panel aspect
         ratio, and the px-sized ring drawn on top of it stops matching. */
      layer.style.clipPath = `circle(${proxy.r}px at ${proxy.x}px ${proxy.y}px)`;

      /* Same frame, same numbers. The ring is a fixed-diameter element scaled
         to the current radius, so this is one composited transform rather than
         a width/height write that would relayout every frame. */
      const scale = proxy.r / radius;
      outline.style.transform = `translate3d(${proxy.x - radius}px, ${proxy.y - radius}px, 0) scale(${scale})`;
      // The border thickens with the scale, so the ring is faded out well
      // before the expansion makes that obvious.
      outline.style.opacity = String(gsap.utils.clamp(0, 1, 2 - scale));
    };

    if (!fine || reduced) {
      /* No pointer to follow, or motion the user declined. Park a static hole
         left-of-centre so both layers are legible at once and the component
         reads as a composed still rather than a blank panel. */
      const rect = el.getBoundingClientRect();
      proxy.x = rect.width * 0.34;
      proxy.y = rect.height * 0.5;
      write();
      return () => {
        layer.style.clipPath = '';
        outline.style.transform = '';
        outline.style.opacity = '';
      };
    }

    // Start off-panel so nothing is revealed before the first move.
    proxy.x = -radius * 3;
    proxy.y = -radius * 3;
    write();

    let entered = false;

    const onMove = (e: PointerEvent) => {
      const rect = el.getBoundingClientRect();
      const x = e.clientX - rect.left;
      const y = e.clientY - rect.top;

      if (!entered) {
        entered = true;
        // Teleport on entry, otherwise the hole slides in from the corner
        // over 400ms and reveals a diagonal streak of the layer beneath.
        gsap.set(proxy, { x, y });
        write();
        return;
      }

      /* `ease: 'none'` is deliberate. An eased follow re-eases from a new
         start value on every event, which under continuous movement reads as
         the hole surging and stalling. Linear catch-up at 0.4s gives a steady
         drag. `overwrite: 'auto'` claims x and y and leaves the radius tween
         from the trigger running underneath. */
      gsap.to(proxy, {
        x,
        y,
        duration: FOLLOW_DURATION,
        ease: 'none',
        overwrite: 'auto',
        onUpdate: write,
      });
    };

    const onLeave = () => {
      entered = false;
      gsap.to(proxy, {
        x: -radius * 3,
        y: -radius * 3,
        duration: 0.35,
        ease: 'power2.in',
        overwrite: 'auto',
        onUpdate: write,
      });
    };

    /* Enough radius to cover the panel from any point inside it: the far
       corner is at most one diagonal away. */
    const full = () => Math.hypot(el.clientWidth, el.clientHeight);

    const onEnterTrigger = (e: Event) => {
      const target = e.target;
      if (!(target instanceof Element) || !target.closest('[data-mask-trigger]')) return;
      gsap.to(proxy, {
        r: full(),
        duration: EXPAND_DURATION,
        ease: 'power3.inOut',
        overwrite: 'auto',
        onUpdate: write,
      });
    };

    const onLeaveTrigger = (e: Event) => {
      const target = e.target;
      if (!(target instanceof Element) || !target.closest('[data-mask-trigger]')) return;
      gsap.to(proxy, {
        r: radius,
        duration: EXPAND_DURATION,
        ease: 'power3.inOut',
        overwrite: 'auto',
        onUpdate: write,
      });
    };

    el.addEventListener('pointermove', onMove, { passive: true });
    el.addEventListener('pointerleave', onLeave);
    /* `pointerover`/`pointerout` bubble, so one pair of listeners covers every
       trigger in the subtree no matter how React re-renders it. `pointerenter`
       does not bubble and would need a listener per trigger. */
    el.addEventListener('pointerover', onEnterTrigger);
    el.addEventListener('pointerout', onLeaveTrigger);

    return () => {
      el.removeEventListener('pointermove', onMove);
      el.removeEventListener('pointerleave', onLeave);
      el.removeEventListener('pointerover', onEnterTrigger);
      el.removeEventListener('pointerout', onLeaveTrigger);
      gsap.killTweensOf(proxy);
      layer.style.clipPath = '';
      outline.style.transform = '';
      outline.style.opacity = '';
    };
  }, [radius]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes all four container listeners, calls `gsap.killTweensOf(proxy)` so no tween can write to a detached node after React releases it, then clears the inline `clipPath`, `transform` and `opacity` that `write()` set. The proxy is a local object and is garbage-collected with the closure.

**Reduced motion.** No listeners attach. The disc is written once, parked at 34% across and vertically centred, and never moves. Both layers stay readable and the composition still communicates what the component does; it simply does not animate.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Tweening `clipPath` as a string. GSAP re-parses it each frame and the ring must then be animated separately; the two interpolations diverge under fast movement and a crescent of the base layer shows between the outline and the disc edge.
- A percentage radius. `circle(20% at ...)` resolves against `sqrt(w^2 + h^2) / sqrt(2)`, so the disc is a different size on a wide panel than a tall one and no px-based outline can be made to match it.
- Forgetting `pointer-events: none` on the clipped layer. `clip-path` clips hit testing, not just paint, so the overlay becomes a region that swallows events inside the disc and passes them through everywhere else — hover targets then work or do not work depending on where the disc happens to be.
- Putting the trigger inside the reveal layer. It is clipped away, so it is only hoverable when it is already inside the disc, which is exactly when you no longer need to hover it. Triggers belong in the base layer.
- Easing the position follow. Because the tween restarts from a new end value on every event, an ease-out curve reads as the disc lunging and hesitating rather than being dragged.
- Animating the ring by writing `width` and `height`. That is a layout invalidation on every frame of the expansion, and it shows as jank on the exact interaction that is meant to feel expensive.
- Not teleporting on entry. Without the `gsap.set` on the first move, the disc eases in from its parked corner over 0.4s and drags a diagonal streak of the reveal layer across the panel every time the pointer enters.
- `overwrite: true` on either tween. It kills the other one, so the disc either freezes mid-expansion or stops following. `overwrite: "auto"` claims only the properties that tween actually animates, which is why position and radius can coexist on one proxy.

## Notes

- Gated on `(pointer: fine)`. On touch there is no pointer to follow: `pointermove` only fires mid-drag, so the disc would sit under the finger hiding it, and it would be stranded wherever the finger lifted. The touch path parks a static disc at 34% across and vertically centred, so both layers are legible at once and the panel reads as a composed still rather than blank.
- Reduced motion takes the same static path — the entire effect is continuous movement, so there is nothing to slow down honestly.
- The reveal layer is `aria-hidden`: it is a second rendering of content the base layer already presents, and exposing both would double every heading to a screen reader.
- Scoped to its own container rather than the viewport. Position is measured against the container rect, so the component composes anywhere and does not assume it owns the page.

## Definition of done

Move across the panel and a disc of the second layer drags along behind the pointer at a steady speed, with a thin ring exactly on its edge — no gap, no crescent of the base layer showing between them, even when you flick the pointer. Hover the trigger and the disc grows smoothly past the corners until the reveal layer fills the panel, with the ring fading out as it goes; leave and it shrinks back to the pointer. Resize the panel to a very wide or very tall aspect ratio and the disc stays circular and stays the same physical size. On touch the disc is parked left-of-centre and static.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Cursor-Reactive Shader Glow

A hero backdrop: a slowly drifting domain-warped noise field with a soft light that follows the pointer through it. The pointer never reaches a uniform directly — the listener records a target and the render loop damps toward it, so the light trails the hand at the same rate on a 60Hz and a 120Hz display. The composed colour is then scaled down until its Rec.709 luminance fits under `ceiling`, which is what makes the glow safe to put white headline copy on top of.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A warped-noise atmosphere with a light that trails the cursor, held under a hard luminance ceiling so copy stays readable.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. A `PlaneGeometry(2, 2)` under an `OrthographicCamera(-1, 1, 1, -1, 0, 1)` is a full-screen quad with no projection maths, so the camera never needs touching on resize and `vUv` is exactly 0..1 across the canvas.
2. The `pointermove` handler converts the event into 0..1 UV space against the canvas rect (flipping y, since UV is up and client y is down) and stores it as a target. The loop then runs `damp(current, target, smoothing, dt)` per axis, where `smoothing` is the fraction of the gap still remaining after one second. The naive `x += (t - x) * 0.1` converges twice as fast at 120Hz as at 60Hz, so the same hand movement would produce a visibly tighter follow on better hardware.
3. The noise is a domain warp: two decorrelated 2-octave fbm samples become a `vec2` offset fed into a third sample. The second channel is shifted by `vec2(2.3, 1.1)` — without that shift both channels return the same number and the warp degenerates into a plain diagonal translation of the field.
4. The pointer is added to all three fbm samples, weighted 0.20, -0.20 and 0.12. The sign flip between the two warp channels makes them shear against each other around the cursor. Three weak influences read as an atmosphere that responds; one strong influence reads as a field glued to the cursor, which is a different and much worse effect.
5. The light itself is two falling `smoothstep(radius, 0.0, d)` ramps — a tight core and a wide halo — mixed 0.65/0.35. The halo is squared, which pushes the last few percent of its falloff below the 8-bit quantisation floor and removes the termination ring the eye otherwise finds at the edge of a single smoothstep on a dark background.
6. Finally `dot(col, vec3(0.2126, 0.7152, 0.0722))` measures the output luminance and the whole vector is multiplied by `min(1.0, ceiling / lum)`. Scaling rather than clamping per channel is deliberate: clamping crushes the brightest channel first and the glow core visibly shifts hue as it brightens.
7. `energy` is measured from the follower's own displacement divided by `dt`, giving UV units per second. Measuring the follower rather than the raw pointer means the signal is already smooth, needs no second filter, and cannot be spiked by one stray event.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `smoothing = 0.0016`
  Fraction of the pointer gap still remaining after one second, so the light closes ~99.8% of the distance per second — roughly a 120ms tail. Raise it to 0.05 and the light lags far enough behind the cursor to feel broken rather than smooth; drop it to 1e-8 and it is welded to the pointer, at which point the damping is doing nothing and a raw uniform write would look identical.
- `ceiling = 0.175`
  Maximum Rec.709 luminance of the output. Against white text this leaves roughly 12:1 contrast, comfortably past the 4.5:1 floor. Past ~0.35 white headline copy over the glow core drops under 4.5:1 and the backdrop starts eating the content it exists to sit behind.
- `coreRadius / haloRadius = 0.22 / 0.85`
  Aspect-corrected UV units. Nearly 4x apart, which is what makes the pair read as one light with a soft surround rather than as two concentric discs. Bring them within ~2x and the halo's edge becomes visible as a ring at the core's boundary.
- `scale = 0.7`
  Noise frequency. Below 1.0 the features are LARGER than the canvas, which is what makes the field read as atmosphere. At 4.0 the same shader is visible turbulence and fights the copy for attention.
- `warp = 0.9`
  How far the two warp channels push the third sample, in noise-space units — just under one full cell. Near 0 the domain warp vanishes and the result is plain fbm with no flow. Past ~2 the warp folds the field back over itself and produces hard creases where the offset reverses.
- `ENERGY_FULL_SCALE = 1.8`
  UV units per second at which `uEnergy` saturates. A deliberate sweep across a hero is roughly 0.6/s, so normal movement lands mid-range and the brightening is legible. Set it to 0.3 and the reading pins at 1 on any movement at all, which makes the parameter meaningless.
- `ENERGY_SMOOTHING / PRESENCE_SMOOTHING = 0.002 / 0.02`
  Energy must track the hand or the brightening arrives after the gesture has finished; presence is a fade in and out and 400ms of it reads as a light coming up. Give presence the fast value and the glow flicks on and off at the canvas boundary.
- `STILL_TIME = 8.2`
  Time slice for the single reduced-motion frame. Not 0, because at t=0 the drift offset is zero on both axes and the field renders its least interesting slice.

## API

```ts
function CursorReactiveShaderGlow(props: { children?: ReactNode; ceiling?: number; coreRadius?: number; haloRadius?: number; scale?: number; warp?: number; fieldGain?: number; glowGain?: number; smoothing?: number; base?: readonly [number, number, number]; tint?: readonly [number, number, number]; glowTint?: readonly [number, number, number]; maxDpr?: number; className?: string }): JSX.Element
```

- `children: ReactNode`
  Overlay content. Pointer-transparent so the canvas keeps receiving moves.
- `ceiling: number` — default `0.175`
  Rec.709 luminance the output may never exceed.
- `coreRadius: number` — default `0.22`
  Radius of the tight glow core, in aspect-corrected UV units.
- `haloRadius: number` — default `0.85`
  Radius of the wide halo. Squared in the shader, so it has no visible edge.
- `scale: number` — default `0.7`
  Noise frequency. Below 1 the features are larger than the canvas.
- `warp: number` — default `0.9`
  How far the two warp channels displace the third noise sample.
- `fieldGain: number` — default `0.08`
  Peak brightness the noise field adds over `base`.
- `glowGain: number` — default `0.1`
  Peak brightness the cursor light adds over `base`.
- `smoothing: number` — default `0.0016`
  Fraction of the pointer gap still remaining after one second.
- `base: readonly [number, number, number]` — default `[0.03, 0.031, 0.038]`
  Deepest colour, linear 0..1 RGB.
- `tint: readonly [number, number, number]` — default `[0.62, 0.7, 0.95]`
  Colour the noise field lifts toward.
- `glowTint: readonly [number, number, number]` — default `[1, 0.94, 0.86]`
  Colour of the cursor light.
- `maxDpr: number` — default `2`
  Device pixel ratio cap. The field is low-frequency, so 2 is already generous.
- `className: string`
  Merged onto the root container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * UV units per second the follower must cover for `uEnergy` to read 1. A slow
 * deliberate sweep across a hero is roughly 0.6/s; above ~2.5 the reading
 * saturates on ordinary movement and the brightness stops meaning anything.
 */
const ENERGY_FULL_SCALE = 1.8;
/** Fast: energy must track the hand, or the brightening arrives after the move. */
const ENERGY_SMOOTHING = 0.002;
/** Slow: presence is a fade in and out, and 400ms of it reads as a light. */
const PRESENCE_SMOOTHING = 0.02;
/** Fixed time slice for the reduced-motion still. Not 0 — that is a flat frame. */
const STILL_TIME = 8.2;
/** Where the light sits in the reduced-motion still. Off-centre reads composed. */
const STILL_POINTER: readonly [number, number] = [0.34, 0.6];
const STILL_ENERGY = 0.35;

const BASE: readonly [number, number, number] = [0.03, 0.031, 0.038];
const TINT: readonly [number, number, number] = [0.62, 0.7, 0.95];
const GLOW_TINT: readonly [number, number, number] = [1, 0.94, 0.86];

interface GlowUniforms {
  /** three types `uniforms` as an open record; the index signature matches it. */
  [name: string]: THREE.IUniform;
  uResolution: THREE.IUniform<THREE.Vector2>;
  uTime: THREE.IUniform<number>;
  uPointer: THREE.IUniform<THREE.Vector2>;
  uPresence: THREE.IUniform<number>;
  uEnergy: THREE.IUniform<number>;
  uScale: THREE.IUniform<number>;
  uWarp: THREE.IUniform<number>;
  uCoreRadius: THREE.IUniform<number>;
  uHaloRadius: THREE.IUniform<number>;
  uFieldGain: THREE.IUniform<number>;
  uGlowGain: THREE.IUniform<number>;
  uCeiling: THREE.IUniform<number>;
  uBase: THREE.IUniform<THREE.Color>;
  uTint: THREE.IUniform<THREE.Color>;
  uGlowTint: THREE.IUniform<THREE.Color>;
}

interface Stage {
  renderer: THREE.WebGLRenderer;
  scene: THREE.Scene;
  camera: THREE.OrthographicCamera;
  geometry: THREE.PlaneGeometry;
  material: THREE.ShaderMaterial;
  uniforms: GlowUniforms;
}

export function CursorReactiveShaderGlow({
  children,
  ceiling = 0.175,
  coreRadius = 0.22,
  haloRadius = 0.85,
  scale = 0.7,
  warp = 0.9,
  fieldGain = 0.08,
  glowGain = 0.1,
  smoothing = 0.0016,
  base = BASE,
  tint = TINT,
  glowTint = GLOW_TINT,
  maxDpr = 2,
  className,
}: CursorReactiveShaderGlowProps) {
  const host = useRef<HTMLDivElement>(null);
  const mount = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);

  const { width, height } = useResizeObserver(host);
  const { inView } = useInView(host, { rootMargin: '10%' });
  const visible = useVisibility();
  const reduced = useReducedMotion();

  const [supported, setSupported] = useState(true);
  useEffect(() => setSupported(hasWebGL()), []);

  /* Raw pointer target in 0..1 with y up. `null` means no real pointer has been
     seen, which is distinct from a legitimate pointer in the bottom-left
     corner — the glow must not exist before the first move. */
  const target = useRef<{ x: number; y: number } | null>(null);
  const inside = useRef(false);
  /** The damped follower. Seeded at the centre so the first move eases outward. */
  const pos = useRef({ x: 0.5, y: 0.5 });
  const presence = useRef(0);
  const energy = useRef(0);

  /* Live config, read by the loop. Changing a number must not rebuild the
     renderer: Chromium kills the OLDEST context past ~16 per process, so a
     rebuild on every prop change blanks an unrelated canvas on the page. */
  const live = useRef({
    ceiling,
    coreRadius,
    haloRadius,
    scale,
    warp,
    fieldGain,
    glowGain,
    smoothing,
  });
  live.current = {
    ceiling,
    coreRadius,
    haloRadius,
    scale,
    warp,
    fieldGain,
    glowGain,
    smoothing,
  };

  const ready = supported && width > 1 && height > 1;

  useEffect(() => {
    const slot = mount.current;
    if (!slot || !ready) return;

    /* The canvas is created here, not owned by React. `reactStrictMode` is on,
       so this effect runs twice on mount; the first cleanup calls
       `forceContextLoss()`, and asking a React-owned <canvas> for a context
       afterwards hands back the DEAD one rather than a fresh context, leaving
       the preview permanently blank. A canvas created and removed per effect
       run has no such history. */
    const renderer = new THREE.WebGLRenderer({
      antialias: false,
      alpha: false,
      powerPreference: 'low-power',
    });
    renderer.setPixelRatio(pixelRatio(maxDpr));
    renderer.setSize(width, height, false);
    const canvas = renderer.domElement;
    canvas.style.display = 'block';
    canvas.style.width = '100%';
    canvas.style.height = '100%';
    /* `touch-action: none` is deliberately NOT set. This is a decorative
       backdrop; swallowing a touch scroll to feed a glow nobody can see under
       their own finger is a straight downgrade. */
    slot.appendChild(canvas);

    const uniforms: GlowUniforms = {
      uResolution: { value: new THREE.Vector2(width, height) },
      uTime: { value: 0 },
      uPointer: { value: new THREE.Vector2(pos.current.x, pos.current.y) },
      uPresence: { value: 0 },
      uEnergy: { value: 0 },
      uScale: { value: scale },
      uWarp: { value: warp },
      uCoreRadius: { value: coreRadius },
      uHaloRadius: { value: haloRadius },
      uFieldGain: { value: fieldGain },
      uGlowGain: { value: glowGain },
      uCeiling: { value: ceiling },
      uBase: { value: new THREE.Color(base[0], base[1], base[2]) },
      uTint: { value: new THREE.Color(tint[0], tint[1], tint[2]) },
      uGlowTint: { value: new THREE.Color(glowTint[0], glowTint[1], glowTint[2]) },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: cursorReactiveShaderGlowVertexShader,
      fragmentShader: cursorReactiveShaderGlowFragmentShader,
      uniforms,
    });

    // A 2x2 plane under an identity ortho camera is a full-screen quad with no
    // projection maths and no camera to keep in sync on resize.
    const geometry = new THREE.PlaneGeometry(2, 2);
    const scene = new THREE.Scene();
    scene.add(new THREE.Mesh(geometry, material));
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);

    /* Listener on the CANVAS, not the window: no document-level handler
       survives to drive a disposed renderer, and the rect it measures is the
       rect it draws into. Passive, because nothing here ever calls
       preventDefault and a non-passive move listener on a scrollable page
       forces the compositor to wait for JS on every event. */
    const onMove = (event: PointerEvent) => {
      const rect = canvas.getBoundingClientRect();
      if (rect.width === 0 || rect.height === 0) return;
      target.current = {
        x: (event.clientX - rect.left) / rect.width,
        // Flipped: UV y is up, client y is down.
        y: 1 - (event.clientY - rect.top) / rect.height,
      };
      inside.current = true;
    };
    const onLeave = () => {
      // Presence only. Leaving the position alone dims the light where it
      // stands; tweening it away drags a visible streak off the edge.
      inside.current = false;
    };

    canvas.addEventListener('pointermove', onMove, { passive: true });
    canvas.addEventListener('pointerleave', onLeave, { passive: true });

    stage.current = { renderer, scene, camera, geometry, material, uniforms };
    renderer.render(scene, camera);

    return () => {
      stage.current = null;
      canvas.removeEventListener('pointermove', onMove);
      canvas.removeEventListener('pointerleave', onLeave);
      // `dispose()` frees GPU objects but leaves the context alive until GC
      // decides otherwise, which may be never. `disposeRenderer` is the one
      // that calls `forceContextLoss()` and actually hands it back.
      disposeRenderer(renderer);
      geometry.dispose();
      material.dispose();
      canvas.remove();
    };
    // Colours and gains are pushed through `live`/`uniforms` from the loop, so
    // they must not appear here — a rebuild per prop change leaks contexts.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, maxDpr]);

  // Resize is its own effect, so a reflow never touches the renderer's lifetime.
  useEffect(() => {
    const s = stage.current;
    if (!s || width < 1 || height < 1) return;
    s.renderer.setPixelRatio(pixelRatio(maxDpr));
    s.renderer.setSize(width, height, false);
    // CSS pixels, not the drawing buffer: the shader only takes the ratio.
    s.uniforms.uResolution.value.set(width, height);
    // Render once, or a resize while paused stretches the previous framebuffer
    // until the pointer moves again.
    s.renderer.render(s.scene, s.camera);
  }, [width, height, maxDpr]);

  useRaf(
    (dt, elapsed) => {
      const s = stage.current;
      if (!s) return;
      const cfg = live.current;

      const previousX = pos.current.x;
      const previousY = pos.current.y;

      const aim = target.current;
      if (aim) {
        pos.current.x = damp(pos.current.x, aim.x, cfg.smoothing, dt);
        pos.current.y = damp(pos.current.y, aim.y, cfg.smoothing, dt);
      }

      // Speed of the follower, in UV units per second. Dividing by dt is what
      // makes it a velocity rather than a per-frame delta that reads twice as
      // large at 60Hz as at 120Hz for the same physical hand movement.
      const travelled = Math.hypot(pos.current.x - previousX, pos.current.y - previousY);
      const speed = travelled / Math.max(dt, 0.0001);
      energy.current = damp(
        energy.current,
        clamp(speed / ENERGY_FULL_SCALE, 0, 1),
        ENERGY_SMOOTHING,
        dt,
      );
      presence.current = damp(
        presence.current,
        inside.current && aim !== null ? 1 : 0,
        PRESENCE_SMOOTHING,
        dt,
      );

      const u = s.uniforms;
      u.uTime.value = elapsed;
      u.uPointer.value.set(pos.current.x, pos.current.y);
      u.uPresence.value = presence.current;
      u.uEnergy.value = energy.current;
      u.uScale.value = cfg.scale;
      u.uWarp.value = cfg.warp;
      u.uCoreRadius.value = cfg.coreRadius;
      u.uHaloRadius.value = cfg.haloRadius;
      u.uFieldGain.value = cfg.fieldGain;
      u.uGlowGain.value = cfg.glowGain;
      u.uCeiling.value = cfg.ceiling;

      s.renderer.render(s.scene, s.camera);
    },
    ready && inView && visible && !reduced,
  );

  /* Reduced motion gets a composed picture, not an empty box: one frame at a
     fixed time slice with the light parked off-centre. Nothing ever moves, and
     the pointer listener stays attached but its target is never consumed. */
  useEffect(() => {
    const s = stage.current;
    if (!s || !reduced || width < 1 || height < 1) return;
    const [stillX = 0.34, stillY = 0.6] = STILL_POINTER;
    s.uniforms.uTime.value = STILL_TIME;
    s.uniforms.uPointer.value.set(stillX, stillY);
    s.uniforms.uPresence.value = 1;
    s.uniforms.uEnergy.value = STILL_ENERGY;
    s.renderer.render(s.scene, s.camera);
  }, [reduced, width, height, ready]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the `pointermove` and `pointerleave` listeners from the canvas, nulls the stage ref so an in-flight frame cannot touch a disposed renderer, then calls `disposeRenderer` (which stops the animation loop, disposes the renderer and calls `forceContextLoss()` — `dispose()` alone leaves the context alive until GC decides otherwise, which may be never), disposes the geometry and the `ShaderMaterial`, and removes the canvas from the DOM. Because the canvas is created inside the effect, the StrictMode second run starts from a fresh element and a fresh context.

**Reduced motion.** The render loop never starts. One frame is drawn at a fixed time slice with the light parked at (0.34, 0.6), presence at 1 and energy at 0.35, so the panel is a composed still of the effect at rest rather than a flat rectangle. The pointer listener stays attached but its target is never read, so moving the cursor changes nothing.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Writing the pointer straight into the uniform from the event handler. The shader then gets one raw sample per event: a 120Hz trackpad delivers a staircase, and a dropped frame delivers a jump. The visible symptom is a light that judders during fast movement and snaps after a stall.
- Damping with a per-frame constant (`x += (t - x) * 0.1`). It is not frame-rate independent — the light trails noticeably further behind on a 60Hz laptop than on a 120Hz one, from identical code.
- Aspect-correcting the noise sample space but not the pointer. The glow becomes an ellipse 1.78x too wide on a 16:9 canvas, and the error scales with the container so it looks correct in a square preview and wrong in the hero it was written for.
- Deriving `energy` from raw pointer events. Event deltas depend on the sample rate, so the same hand movement measures differently per device, and one outlier event flashes the whole field.
- Letting the pointer target slide back to the centre on leave. That drags a visible streak of light across the canvas to the middle. Only `presence` is faded, so the light dims where it stands.
- Putting the pointer listener on `window` instead of the canvas. A document-level handler outlives the renderer it was written for, and the rect it measures is not the rect being drawn into — so after a scroll the glow sits at an offset from the cursor.
- Clamping the output per channel instead of scaling the vector. The brightest channel saturates first, so the glow core shifts hue as it gets brighter — a warm light turns pink at its centre.
- Rebuilding the renderer when a colour or gain prop changes. Chromium kills the oldest WebGL context past roughly 16 per renderer process, so a page with several of these blanks an unrelated canvas. Numbers go through a ref the loop reads; only size and support rebuild.
- Owning the `<canvas>` in React while calling `forceContextLoss()` on cleanup. Under `reactStrictMode` the effect runs twice, and the second `getContext` on that same element hands back the dead context — the preview is permanently blank in development and fine in production, which is the worst possible failure mode. The canvas is created inside the effect and removed with it.
- Making the content layer pointer-opaque. It covers the canvas, so `pointermove` stops firing exactly over the headline — the one place the glow is wanted. The overlay is `pointer-events-none`.

## Notes

- The two warp channels sample the same fbm function, so the shader is three fbm evaluations of two octaves each: twelve gradient-noise samples per fragment. Two octaves is enough because the result is immediately crushed by `smoothstep(0.25, 0.85)` and the finer detail is discarded.
- The hash is sin-free. `fract(sin(dot(p, k)) * 43758.5453)` quantises once the angle passes a few thousand radians and grows visible repeating bands — and it fails on mobile GPUs long before it fails on the desktop it was written on.
- Gradient noise rather than value noise: the lattice value is a dot product with a random gradient and is therefore zero at every lattice point, which is what stops the cell corners reading as a faint dot grid in the flat areas.
- Resize lives in its own effect and re-renders one frame, so a reflow while the loop is paused does not leave the previous framebuffer stretched across the new size.
- `touch-action` is deliberately left alone. Swallowing a touch scroll to drive a glow hidden under the user's own finger is a straight downgrade.

## Definition of done

Move the pointer across the panel and a soft light follows it with a short, even tail; the same tail length on a 60Hz and a 120Hz display. Move fast and the light brightens; stop and it settles to a dimmer ember without going out. Leave the panel and the light fades where it stands instead of sliding to the centre. The noise field keeps drifting slowly whether or not the pointer moves. White text over the glow core stays readable at any `glowGain`. Resize the container and the glow stays circular, not elliptical. In development, with StrictMode double-mounting, the canvas renders — it is not blank. With reduced motion the panel is a single composed still.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Cursor Repulsion Burst

Up to 1400 particles in one instanced draw call, each circling its own home on its own phase. The pointer opens a hole in the field with a linear falloff inside its radius, and a press fires a shock wave whose front tints the particles it is passing through. The pointer is damped on the CPU before it reaches a uniform, and bursts run in a pool of three slots so overlapping presses produce overlapping waves rather than one wave restarting.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

An orbiting particle field the pointer pushes out of the way, and a press detonates into a shock wave with a heat band.

- Category: cursor
- Runtime cost: webgl
- Dependencies: ogl@^1.0.11

## How it works

1. Three displacements are stacked in field space in the vertex shader before anything becomes a position: an idle orbit, cursor repulsion, then up to three shock waves. Each stage reads the position the previous one produced, so a particle already pushed aside by the cursor is the particle the wave throws.
2. All distances are measured in aspect-corrected space — x multiplied by `uResolution.x / uResolution.y` — and the resulting displacement is divided back out before it is added to the position. Without the correction the repulsion hole is an ellipse on any container that is not square, and the shock ring reaches the side edges before the top.
3. Repulsion is `max(radius - distance, 0) * repel`: linear inside the radius and exactly zero outside it, so the field beyond the pointer is untouched and the whole idea costs one `length()` per particle. A `smoothstep` would be softer but would also mean every particle on screen is permanently displaced a little, which reads as the field sagging toward the cursor.
4. The direction is `v / max(length(v), floor)` rather than `normalize(v)`. A true normalize is undefined at the origin and unstable just outside it, so the particle sitting under the cursor picks a new direction every frame from floating-point noise and buzzes. Dividing by a floor makes the vector shorter than unit length near the centre, so the push fades in and the direction stays put.
5. A burst slot is `vec4(originX, originY, progress, active)`. The displacement is `(0.25 + seed * 0.75) * push * easeOutCubic(t) * settle(t) * reach(d)`, where `settle` walks the whole thing back to zero by t = 1 so the slot can be freed without the field snapping home, and `reach` limits the throw to the neighbourhood of the origin so the burst is not a camera jolt.
6. The heat band is `exp(-b * b)` where `b = (distance - burstRadius * ease) / band`. The shock radius expands on the same cubic ease as the displacement, so only the particles the front is passing through right now take the tint. A flat tint over the whole burst just recolours the field; a Gaussian band travelling through it reads as heat.
7. Only `active` and `progress` change per frame per slot, so a burst costs three vec4 uniforms and a three-iteration loop — no per-particle CPU state and no buffer upload.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `smoothing = 0.0008`
  Fraction of the pointer gap still remaining after one second: a tight ~90ms tail, because a repulsion hole that lags is read as broken rather than as smooth — the hole has a visible edge, unlike a glow. Raise it past ~0.01 and the field is still opening where the cursor was half a second ago.
- `cursorRadius = 0.22`
  Field units, where 1 is the container HEIGHT. Roughly a fifth of the panel, so the hole is obviously deliberate but the field still dominates. Past ~0.45 the pointer clears most of the visible particles and there is nothing left to displace.
- `repel = 0.85`
  Displacement at the centre of the field, as a fraction of the radius. Below ~0.4 the hole never actually opens — particles crowd instead of clearing. Above 1.0 the inner particles are pushed past the rim and pile into a bright ring, which is the same artefact as a hard-edged mask.
- `BURST_SLOTS = 3`
  Concurrent waves. One slot means a second press restarts the wave from zero, which visibly sucks the first one back into its origin. Three covers a fast double or triple click, and each slot is a vec4 and a loop iteration, so the ceiling is set by taste rather than by cost.
- `burstDuration = 1.1`
  Seconds of life. Under ~0.6 the wave is gone before the eye finds it; over ~2 the field spends most of its time recovering and a second press lands in a field that is still deformed.
- `burstRadius / BURST_BAND = 0.55 / 0.085`
  How far the front travels, and how thick it is. The band is roughly 15% of the travel, which is a front rather than a wash — take it past ~0.25 and the Gaussian covers the whole burst at once, which is indistinguishable from tinting every particle.
- `burstPush = 0.17`
  Peak displacement in field units, multiplied by a per-particle 0.25-1.0. The spread is what gives the wave a ragged front; a uniform magnitude produces a clean expanding circle, which reads as a UI ripple rather than as a detonation.
- `MAX_DPR = 1.5`
  Additive fill is the entire cost here and it scales with the square of the ratio. These are soft round dots with no fine detail, so a third sample per axis resolves nothing a viewer can see and costs 78% more fragments.

## API

```ts
function CursorRepulsionBurst(props: { density?: number; maxCount?: number; sizeRange?: readonly [number, number]; cursorRadius?: number; repel?: number; burstPush?: number; burstRadius?: number; burstDuration?: number; smoothing?: number; breathe?: number; opacity?: number; colorA?: string; colorB?: string; heatColor?: string; background?: string; seed?: number | string; className?: string }): JSX.Element
```

- `density: number` — default `1100`
  Particles per megapixel of container area.
- `maxCount: number` — default `1400`
  Population ceiling, and the size the buffers are allocated at.
- `sizeRange: readonly [number, number]` — default `[1.6, 5.2]`
  Particle size in CSS pixels, biased toward the small end.
- `cursorRadius: number` — default `0.22`
  Repulsion radius in field units, where 1 is the container height.
- `repel: number` — default `0.85`
  Displacement at the centre of the repulsion field, as a fraction of its radius.
- `burstPush: number` — default `0.17`
  Peak burst displacement in field units, before the per-particle spread.
- `burstRadius: number` — default `0.55`
  How far a shock front travels before it dies.
- `burstDuration: number` — default `1.1`
  Life of one burst in seconds.
- `smoothing: number` — default `0.0008`
  Fraction of the pointer gap still remaining after one second.
- `breathe: number` — default `0.22`
  Depth of the orbit-radius breathing, 0 to 0.5.
- `opacity: number` — default `0.9`
  Overall alpha multiplier.
- `colorA: string` — default `'#8fb6ff'`
  First tint. Any value ogl's Color accepts.
- `colorB: string` — default `'#e6ecf7'`
  Second tint; each particle mixes between the two.
- `heatColor: string` — default `'#ff8a3c'`
  Colour of the shock front.
- `background: string` — default `'#06070b'`
  Opaque clear colour the additive field is composited onto.
- `seed: number | string` — default `'cursor-repulsion-burst'`
  Seeds the scatter, sizes, phases and burst magnitudes.
- `className: string`
  Merged onto the root container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** Floor on the population. Below this the field reads as a few stray specks. */
const MIN_COUNT = 220;
/** Slots in the burst pool. Three overlapping waves is the most anyone produces. */
const BURST_SLOTS = 3;
/** Width of the Gaussian heat band, in field units. */
const BURST_BAND = 0.085;
/** Fraction of the presence gap left after a second. ~200ms in and out. */
const PRESENCE_SMOOTHING = 0.007;
/** Size distribution exponent. Above 1 crowds the population into small sizes. */
const SIZE_BIAS = 1.8;
/**
 * Fill cost scales with dpr squared and these are soft round dots with no fine
 * detail, so a third sample per axis resolves nothing a viewer can see.
 */
const MAX_DPR = 1.5;
/** Field-space bounds. Wider than 0..1 so orbits never bare the edges. */
const HOME_MIN = -0.06;
const HOME_MAX = 1.06;

/** The reduced-motion still: a frozen frame with the pointer and one wave in it. */
const STILL_ELAPSED = 6.5;
const STILL_CURSOR: readonly [number, number] = [0.34, 0.56];
const STILL_BURST: readonly [number, number, number] = [0.66, 0.42, 0.42];

export function CursorRepulsionBurst({
  density = 1100,
  maxCount = 1400,
  sizeRange = [1.6, 5.2],
  cursorRadius = 0.22,
  repel = 0.85,
  burstPush = 0.17,
  burstRadius = 0.55,
  burstDuration = 1.1,
  smoothing = 0.0008,
  breathe = 0.22,
  opacity = 0.9,
  colorA = '#8fb6ff',
  colorB = '#e6ecf7',
  heatColor = '#ff8a3c',
  background = '#06070b',
  seed = 'cursor-repulsion-burst',
  className,
}: CursorRepulsionBurstProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  const { width, height } = useResizeObserver(host);
  const size = useRef({ width, height });
  size.current = { width, height };

  const reduced = useReducedMotion();
  const visible = useVisibility();
  const { inView } = useInView(host, { rootMargin: '10%' });
  const ready = width > 1 && height > 1;

  const [minSize = 1.6, maxSize = 5.2] = sizeRange;

  /* Raw pointer target in field space, or null until a real move has happened —
     which is not the same as a pointer resting at the bottom-left corner. */
  const target = useRef<{ x: number; y: number } | null>(null);
  const inside = useRef(false);
  /** The damped follower, seeded at the centre so the first move eases outward. */
  const follow = useRef({ x: 0.5, y: 0.5 });
  const presence = useRef(0);

  const slots = useRef<BurstSlot[]>(
    Array.from({ length: BURST_SLOTS }, () => ({ x: 0.5, y: 0.5, t: 0, active: false })),
  );
  const nextSlot = useRef(0);

  /* Live numbers the loop reads. Changing one must not rebuild the renderer:
     Chromium drops the OLDEST WebGL context past roughly 16 per process, so a
     rebuild per prop change can blank an unrelated canvas elsewhere on the page. */
  const live = useRef({
    cursorRadius,
    repel,
    burstPush,
    burstRadius,
    burstDuration,
    smoothing,
    breathe,
    opacity,
  });
  live.current = {
    cursorRadius,
    repel,
    burstPush,
    burstRadius,
    burstDuration,
    smoothing,
    breathe,
    opacity,
  };

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    if (!hasWebGL()) {
      setUnsupported(true);
      return;
    }

    /* ogl creates its own canvas, and it is appended and removed per effect
       run. Reusing one React-owned canvas breaks under StrictMode: the first
       cleanup force-loses the context, and `getContext` on that same element
       afterwards returns the dead one rather than a fresh context — the panel
       is then permanently blank in development and fine in production. */
    const renderer = new Renderer({
      dpr: pixelRatio(MAX_DPR),
      // Opaque: the pass is additive, and additive onto a transparent canvas
      // would have to brighten the page behind it, which the GPU cannot see.
      alpha: false,
      // Nothing occludes anything, so a depth buffer is memory plus a clear.
      depth: false,
      antialias: false,
      // Fill-bound, not shader-bound. The discrete GPU buys nothing here.
      powerPreference: 'low-power',
    });

    const gl = renderer.gl;
    const canvas = gl.canvas;

    const bg = new Color(background);
    gl.clearColor(bg.r, bg.g, bg.b, 1);

    const quad = new Float32Array([-0.5, -0.5, 0.5, -0.5, 0.5, 0.5, -0.5, 0.5]);
    const index = new Uint16Array([0, 1, 2, 0, 2, 3]);

    const total = Math.max(MIN_COUNT, Math.round(maxCount));
    const homes = new Float32Array(total * 2);
    const params = new Float32Array(total * 4);
    const seeds = new Float32Array(total * 4);

    const rng = createRng(seed);
    const lo = Math.max(0.5, Math.min(minSize, maxSize));
    const hi = Math.max(lo + 0.25, Math.max(minSize, maxSize));

    for (let i = 0; i < total; i += 1) {
      homes[i * 2] = randRange(rng, HOME_MIN, HOME_MAX);
      homes[i * 2 + 1] = randRange(rng, HOME_MIN, HOME_MAX);

      // Biased small: a linear distribution puts a quarter of the population in
      // the largest quarter of the range, and the field reads as gravel.
      const sizeT = Math.pow(rng(), SIZE_BIAS);
      params[i * 4] = lo + (hi - lo) * sizeT;
      params[i * 4 + 1] = randRange(rng, 0.004, 0.03);
      // Signed rate with a floor on the magnitude: a particle orbiting at
      // 0.001 rad/s is a particle that is simply not moving.
      params[i * 4 + 2] = (rng() < 0.5 ? -1 : 1) * randRange(rng, 0.12, 0.46);
      // Bigger particles are dimmer, so total light stays roughly constant.
      params[i * 4 + 3] = 0.34 + 0.5 * (1 - sizeT);

      seeds[i * 4] = rng() * Math.PI * 2;
      // Burst magnitude. Per-particle, so the wave has a ragged front rather
      // than a clean expanding circle — a clean circle reads as a UI ripple.
      seeds[i * 4 + 1] = rng();
      seeds[i * 4 + 2] = randRange(rng, 0.35, 1);
      seeds[i * 4 + 3] = rng();
    }

    const geometry = new Geometry(gl, {
      index: { data: index },
      position: { size: 2, data: quad },
      aHome: { size: 2, data: homes, instanced: 1 },
      aParams: { size: 4, data: params, instanced: 1 },
      aSeed: { size: 4, data: seeds, instanced: 1 },
    });

    const uniforms: Uniforms = {
      uResolution: { value: [1, 1] },
      uPixelRatio: { value: renderer.dpr },
      uElapsed: { value: 0 },
      uCursor: { value: [0.5, 0.5] },
      uCursorPresence: { value: 0 },
      uCursorRadius: { value: cursorRadius },
      uRepel: { value: repel },
      uBreathe: { value: clamp(breathe, 0, 0.5) },
      uBursts: { value: new Array<number>(BURST_SLOTS * 4).fill(0) },
      uBurstRadius: { value: burstRadius },
      uBurstPush: { value: burstPush },
      uBurstBand: { value: BURST_BAND },
      uColorA: { value: new Color(colorA) },
      uColorB: { value: new Color(colorB) },
      uHeatColor: { value: new Color(heatColor) },
      uOpacity: { value: opacity },
    };

    const program = new Program(gl, {
      vertex: CURSOR_REPULSION_BURST_VERT,
      fragment: CURSOR_REPULSION_BURST_FRAG,
      uniforms,
      transparent: true,
      depthTest: false,
      depthWrite: false,
      // ogl culls BACK faces by default and the quad's winding is not
      // guaranteed to face the way the driver expects. A culled particle is
      // not dim — it is absent.
      cullFace: false,
    });
    // Additive, overriding the source-over that `transparent: true` selected.
    // Order independent, so a thousand overlapping instances need no sort,
    // which is what makes one draw call possible at all.
    program.setBlendFunc(gl.ONE, gl.ONE);

    const mesh = new Mesh(gl, { geometry, program });

    el.appendChild(canvas);
    canvas.style.display = 'block';

    /* Listeners on the CANVAS, not the window. A document-level handler
       outlives the renderer it was written for, and the rect it measures is not
       the rect being drawn into — after a scroll the hole sits at an offset
       from the cursor. Passive, because nothing here calls preventDefault and a
       non-passive move handler makes the compositor wait for JS on every event. */
    const toField = (event: PointerEvent) => {
      const rect = canvas.getBoundingClientRect();
      if (rect.width === 0 || rect.height === 0) return null;
      return {
        x: (event.clientX - rect.left) / rect.width,
        // Flipped: field y is up, client y is down.
        y: 1 - (event.clientY - rect.top) / rect.height,
      };
    };

    const onMove = (event: PointerEvent) => {
      const point = toField(event);
      if (!point) return;
      target.current = point;
      inside.current = true;
    };

    const onDown = (event: PointerEvent) => {
      const point = toField(event);
      if (!point) return;
      // A press is also a position: on touch there is no hover, so without this
      // the wave would fire from wherever the pointer last happened to be.
      target.current = point;
      inside.current = true;

      const slot = slots.current[nextSlot.current % BURST_SLOTS];
      if (!slot) return;
      nextSlot.current = (nextSlot.current + 1) % BURST_SLOTS;
      slot.x = point.x;
      slot.y = point.y;
      slot.t = 0;
      slot.active = true;
    };

    const onLeave = () => {
      // Position is left where it is. Tweening it back to the centre drags a
      // visible furrow across the field on the way out.
      inside.current = false;
    };

    canvas.addEventListener('pointermove', onMove, { passive: true });
    canvas.addEventListener('pointerdown', onDown, { passive: true });
    canvas.addEventListener('pointerleave', onLeave, { passive: true });
    canvas.addEventListener('pointercancel', onLeave, { passive: true });

    const resize = (w: number, h: number) => {
      renderer.setSize(w, h);
      // `setSize` writes literal px into the canvas's inline style, which wins
      // over any class. Re-asserting percentages keeps it fluid between
      // resize notifications.
      canvas.style.width = '100%';
      canvas.style.height = '100%';

      uniforms.uResolution.value = [gl.drawingBufferWidth, gl.drawingBufferHeight];
      uniforms.uPixelRatio.value = renderer.dpr;

      // Population from area, not a fixed number: the same density reads right
      // in a 320px card and a 2000px hero. The buffers already hold `total`
      // particles in scattered order, so a prefix of them is still spatially
      // even — no rebuild, no reallocation, no new GPU memory.
      const megapixels = (w * h) / 1_000_000;
      const count = clamp(Math.round(megapixels * density), MIN_COUNT, total);
      geometry.setInstancedCount(count);
    };

    const draw = (elapsed: number) => {
      uniforms.uElapsed.value = elapsed;
      renderer.render({ scene: mesh });
    };

    resize(size.current.width, size.current.height);
    stage.current = { renderer, geometry, program, mesh, uniforms, resize, draw };
    draw(0);

    return () => {
      stage.current = null;
      canvas.removeEventListener('pointermove', onMove);
      canvas.removeEventListener('pointerdown', onDown);
      canvas.removeEventListener('pointerleave', onLeave);
      canvas.removeEventListener('pointercancel', onLeave);
      // ogl has no `dispose()`: `remove()` on the geometry deletes its VAOs and
      // every buffer, `remove()` on the program deletes the shaders and the
      // program, and only then is the context worth handing back. Dropping the
      // context is the part that matters — the browser's per-process budget is
      // about sixteen, and a lost one takes an unrelated canvas with it.
      geometry.remove();
      program.remove();
      loseContext(gl);
      canvas.width = 0;
      canvas.height = 0;
      canvas.remove();
    };
  }, [ready, density, maxCount, minSize, maxSize, seed]);

  // Colours are pushed into the live uniforms rather than being effect deps, so
  // recolouring never costs a context.
  useEffect(() => {
    const s = stage.current;
    if (!s) return;
    s.uniforms.uColorA.value.set(colorA);
    s.uniforms.uColorB.value.set(colorB);
    s.uniforms.uHeatColor.value.set(heatColor);
    const bg = new Color(background);
    s.renderer.gl.clearColor(bg.r, bg.g, bg.b, 1);
  }, [colorA, colorB, heatColor, background]);

  // Resize is its own effect: a reflow costs a `setSize` and an instanced-count
  // change, never a buffer rebuild.
  useEffect(() => {
    stage.current?.resize(width, height);
  }, [width, height]);

  useRaf(
    (dt, elapsed) => {
      const s = stage.current;
      if (!s) return;
      const cfg = live.current;

      const aim = target.current;
      if (aim) {
        follow.current.x = damp(follow.current.x, aim.x, cfg.smoothing, dt);
        follow.current.y = damp(follow.current.y, aim.y, cfg.smoothing, dt);
      }
      presence.current = damp(
        presence.current,
        inside.current && aim !== null ? 1 : 0,
        PRESENCE_SMOOTHING,
        dt,
      );

      // Bursts advance on wall-clock seconds, not on frames, so a wave lasts
      // `burstDuration` on a 30Hz phone and on a 144Hz monitor alike.
      const flat = s.uniforms.uBursts.value;
      const life = Math.max(cfg.burstDuration, 0.05);
      let i = 0;
      for (const slot of slots.current) {
        if (slot.active) {
          slot.t += dt / life;
          if (slot.t >= 1) {
            slot.t = 1;
            slot.active = false;
          }
        }
        flat[i * 4] = slot.x;
        flat[i * 4 + 1] = slot.y;
        flat[i * 4 + 2] = slot.t;
        flat[i * 4 + 3] = slot.active ? 1 : 0;
        i += 1;
      }

      const u = s.uniforms;
      // Mutated in place. Assigning a fresh tuple allocates two arrays a frame
      // and defeats ogl's redundant-uniform cache, which compares by length
      // first and then element by element against the array it kept.
      u.uCursor.value[0] = follow.current.x;
      u.uCursor.value[1] = follow.current.y;
      u.uCursorPresence.value = presence.current;
      u.uCursorRadius.value = cfg.cursorRadius;
      u.uRepel.value = cfg.repel;
      u.uBurstPush.value = cfg.burstPush;
      u.uBurstRadius.value = cfg.burstRadius;
      u.uBreathe.value = clamp(cfg.breathe, 0, 0.5);
      u.uOpacity.value = cfg.opacity;

      s.draw(elapsed);
    },
    ready && inView && visible && !reduced && !unsupported,
  );

  /* Reduced motion is a composed still, not an empty box: one frame with the
     pointer parked off-centre and a single wave frozen part-way out, so the
     panel shows what the effect produces. The listeners stay attached and their
     target is never consumed, so moving or clicking changes nothing. */
  useEffect(() => {
    const s = stage.current;
    if (!s || !reduced || !ready) return;
    const [cx = 0.34, cy = 0.56] = STILL_CURSOR;
    const [bx = 0.66, by = 0.42, bt = 0.42] = STILL_BURST;
    s.uniforms.uCursor.value[0] = cx;
    s.uniforms.uCursor.value[1] = cy;
    s.uniforms.uCursorPresence.value = 1;
    const flat = s.uniforms.uBursts.value;
    flat.fill(0);
    flat[0] = bx;
    flat[1] = by;
    flat[2] = bt;
    flat[3] = 1;
    s.draw(STILL_ELAPSED);
  }, [reduced, ready, width, height]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the four pointer listeners from the canvas, nulls the stage ref so an in-flight frame cannot touch a dead renderer, then `geometry.remove()` (deletes the VAOs and every buffer), `program.remove()` (deletes the shaders and the program), `loseContext(gl)`, zeroes the canvas dimensions and removes it from the DOM. ogl has no `dispose()`, and dropping the context is the part that matters — the per-process budget is about sixteen, and exceeding it kills the oldest context, which belongs to somebody else.

**Reduced motion.** The render loop never starts. One frame is drawn with the pointer parked at (0.34, 0.56) at full presence and a single wave frozen 42% of the way out, so the panel is a composed still of the effect rather than a static dot field. The listeners stay attached but their target is never consumed, so moving or pressing changes nothing on screen.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Writing pointer events straight into `uCursor`. The hole lands exactly where the last event was: a high-rate trackpad delivers a staircase, and after a stalled frame it is a jump that shoves the whole field sideways in one step. The listener records a target and the loop damps toward it.
- Damping with a per-frame constant (`x += (t - x) * 0.1`) instead of `damp(..., dt)`. The same code produces a noticeably tighter follow at 120Hz than at 60Hz, so the effect is tuned for whatever machine it was written on.
- Using `normalize()` for the repulsion direction. It is undefined at the origin, so the particle under the cursor jitters between random directions every frame — a visible buzzing speck exactly where the eye is.
- Aspect-correcting the distances but not dividing the displacement back out. Particles are then pushed further horizontally than vertically, and the hole slowly shears the field sideways as the pointer moves.
- Restarting one burst slot on every press. The in-flight wave is yanked back to its origin before the new one starts, which looks like a rendering fault rather than a second click. Three round-robin slots let waves overlap.
- Advancing burst progress per frame instead of by `dt / duration`. The wave is then twice as fast on a 120Hz display and half speed on a throttled tab.
- Deactivating a slot while its displacement is still non-zero. Every particle in it snaps home on one frame. The magnitude is multiplied by a settle term that reaches zero exactly when the slot expires.
- Handing ogl a Float32Array for `uniform vec4 uBursts[3]`. ogl resolves the active uniform name `uBursts[0]`, checks `Array.isArray(value)` to decide it is an array uniform, and a Float32Array fails that test — the uniform is silently skipped with a console warning and every burst is invisible. It must be a plain array.
- Leaving ogl's default BACK-face culling on. The quad winding is not guaranteed to face the way the driver expects, and a culled particle is not dim, it is absent — so the field renders empty on some machines and fine on others.
- Owning the canvas in React while calling `loseContext()` on cleanup. Under `reactStrictMode` the effect runs twice and the second `getContext` on that element hands back the dead context: blank in development, fine in production.
- Rebuilding the renderer when a colour changes. Chromium drops the oldest WebGL context past roughly sixteen per process, so recolouring one field can blank a different canvas on the same page. Colours are written into live uniforms.

## Notes

- `pointerdown` sets the pointer target as well as firing the wave. On touch there is no hover, so without it the burst would originate from wherever the pointer last happened to be — usually the previous tap.
- Blending is additive with an opaque clear colour, so a thousand overlapping instances need no depth sort and the whole field is one draw call. The fragment output is premultiplied because the destination is only ever added to.
- The population is derived from container area rather than fixed, and selected with `setInstancedCount` out of buffers allocated once at `maxCount`. Resizing changes the count without touching a byte of GPU memory.
- The scatter runs on `createRng(seed)`, never `Math.random()`, so the field is identical on every load and a visual regression is a real regression.
- Particles inside the repulsion radius also brighten, which stops the hole reading as a bald patch — the field gets denser and hotter at the rim instead.

## Definition of done

The field drifts on its own with no pointer on the page. Move the pointer in and a clear hole opens around it, tracking with a short even lag that is the same on a 60Hz and a 120Hz display, with the rim slightly brighter than the rest of the field. The particle directly under the cursor does not jitter. Press and a wave throws the nearby particles outward with a ragged front, a warm band travelling through them, and they drift back without snapping. Press three times quickly and you get three overlapping waves, not one wave restarting. Leave the panel and the hole closes where it stands. Resize to a wide container and the hole is still round. With reduced motion the panel is a single composed still.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Dot-Cloud Score Cylinder

A score wrapped around a cylinder and drawn entirely in dots: measure rings, vertical bar dividers, and note clusters that light as a playhead sweeps them. Two cylinders are stacked and turned to different yaws so they never present the same face at once, and both live in one buffer. Nothing uses a depth buffer — every dot is flattened to z = 0 before projection, and solidity comes from alpha and point size falling off with the model-space z.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Two counter-rotating cylinders of dots — rings, bar lines, notes — drawn from one buffer with no depth buffer.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. One `Float32Array` pair is filled in six consecutive passes — both cylinders' measure rings, then both cylinders' dividers, then both cylinders' notes. Buffer order is the draw order, so notes end up on top of everything without a sort and without a second object.
2. Identity travels in `aPointData = vec4(instanceIndex, isNote, pointScale, groupIndex)`, so the two cylinders share a geometry and the vertex shader picks the transform: instance 1 is mirrored with `p.z *= -1.0` and yawed -166°, instance 0 is yawed -90°.
3. Both are then yawed by `uSpin` (degrees, advancing linearly at `spinSpeed` per second) and tilted 8° on X, and instance 0 is pushed up by 0.3 *after* the rotation so the stack separation is a pure screen-space offset that does not tip with the spin.
4. Depth is faked from the transformed z: `depthT = clamp((z + 0.6) / 1.2, 0, 1)` drives alpha from 0.25 to 1.0 and point size from 0.65 to 1.0, so the far wall of the cylinder recedes without a depth test.
5. The playhead is `mod(floor(uElapsed / uNoteInterval), uGroupCount)`, computed in the vertex shader from the clock that is already there. A note group whose index matches gets 2x point size and full alpha, so highlighting a beat costs no React render and no uniform write.
6. Angles within each ring are sorted before being written into the buffer, and `gl_PointSize` gets the same clamp-plus-area-compensated-alpha treatment as every other point field here.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `BASE_SCALE = 1.5`
  Applied in the shader, not baked into the buffer, so re-framing the piece never re-uploads a vertex.
- `TILT = 8.0 degrees`
  X tilt. Below ~4° the cylinder collapses to a straight band and stops reading as a cylinder; past ~15° you look down the tube and the far wall crowds the near one.
- `INSTANCE_B_YAW = -166.0 degrees`
  Not -180. At exactly half a turn the two cylinders present mirror-image faces and the pair looks like one object reflected; 166° keeps them legibly distinct through the whole rotation.
- `STACK_OFFSET = 0.3`
  Vertical separation, applied after `rotateX` so it is screen-space. Applied before, the offset would tilt with the cylinder and the two would drift into each other as they turn.
- `DEPTH_HALF_RANGE = 0.6`
  z is normalised over ±0.6 while the cloud actually spans ±0.75, so the nearest and furthest dots saturate. Normalising over the exact range leaves the middle band looking flat.
- `DEPTH_MIN_SIZE / DEPTH_MAX_SIZE = 0.65 / 1.0`
  Far dots at 65% of near dots. Alpha alone is not enough — without the size falloff the far wall reads as a grey copy of the near one rather than as distance.
- `NOTE_ACTIVE_SCALE = 2.0`
  Point size multiplier for the lit note group. Area goes as the square, so 2x is a 4x brighter mark — visible at a glance without any colour change being required.
- `spinSpeed = 12 degrees/second`
  One revolution every 30s. The original ran at 1°/s, which is right for an ambient full-page object and far too slow to read in a preview card. Linear either way: easing it would make it look like it is arriving somewhere.
- `MEASURE_SCALE / NOTE_SCALE = 0.7 / 1.4`
  Notes are exactly double the measure dots so they survive the depth size falloff on the far wall, where a measure dot is already down to 0.46.

## API

```ts
function CylinderDotScore(props: { ringCount?: number; ringDots?: number; dividerCount?: number; dividerDots?: number; noteGroups?: number; noteDots?: number; spinSpeed?: number; noteInterval?: number; dotScale?: number; viewScale?: number; opacity?: number; color?: string; noteColor?: string; seed?: number | string; className?: string }): JSX.Element
```

- `ringCount: number` — default `10`
  Measure rings per cylinder, split evenly above and below the equator gap.
- `ringDots: number` — default `260`
  Dots in each measure ring.
- `dividerCount: number` — default `8`
  Vertical bar dividers per cylinder.
- `dividerDots: number` — default `34`
  Dots making up each divider.
- `noteGroups: number` — default `6`
  Note clusters per cylinder; the playhead cycles through them.
- `noteDots: number` — default `26`
  Dots per note cluster.
- `spinSpeed: number` — default `12`
  Degrees of yaw per second. Linear.
- `noteInterval: number` — default `1.2`
  Seconds each note group stays lit.
- `dotScale: number` — default `1`
  Global dot radius multiplier in CSS pixels.
- `viewScale: number` — default `0.62`
  Model-to-pixel scale as a fraction of the container short side.
- `opacity: number` — default `1`
  Multiplier applied to every dot.
- `color: string` — default `'#7d838c'`
  Measure and divider dot colour.
- `noteColor: string` — default `'#ffffff'`
  Note dot colour; lit notes go fully to this.
- `seed: number | string` — default `'cylinder-dot-score'`
  Seeds ring angles and note scatter for a stable, hydration-safe layout.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function CylinderDotScore({
  ringCount = 10,
  ringDots = 260,
  dividerCount = 8,
  dividerDots = 34,
  noteGroups = 6,
  noteDots = 26,
  spinSpeed = 12,
  noteInterval = 1.2,
  dotScale = 1,
  viewScale = 0.62,
  opacity = 1,
  color = '#7d838c',
  noteColor = '#ffffff',
  seed = 'cylinder-dot-score',
  className,
}: CylinderDotScoreProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  const { width, height } = useResizeObserver(host);
  const size = useRef({ width, height });
  size.current = { width, height };

  const reduced = useReducedMotion();
  const ready = width > 0 && height > 0;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    if (!hasWebGL()) {
      setUnsupported(true);
      return;
    }

    const renderer = new THREE.WebGLRenderer({ antialias: false, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setClearAlpha(0);

    const scene = new THREE.Scene();
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
    camera.position.z = 1;

    const rng = createRng(seed);

    /* ------------------------------------------------------------------
       Buffer layout IS the draw order. Points are blended in the order they
       appear, with depth testing off, so the six passes below are written
       consecutively into one pair of arrays: both cylinders' measures, then
       both cylinders' dividers, then both cylinders' notes. Notes last means
       notes on top, everywhere, without a sort and without a second object.
       ------------------------------------------------------------------ */
    const perCylinder = ringCount * ringDots + dividerCount * dividerDots + noteGroups * noteDots;
    const total = perCylinder * 2;

    const positions = new Float32Array(total * 3);
    const pointData = new Float32Array(total * 4);
    let cursor = 0;

    const write = (
      x: number,
      y: number,
      z: number,
      instance: number,
      isNote: number,
      scale: number,
      group: number,
    ) => {
      positions[cursor * 3] = x;
      positions[cursor * 3 + 1] = y;
      positions[cursor * 3 + 2] = z;
      pointData[cursor * 4] = instance;
      pointData[cursor * 4 + 1] = isNote;
      pointData[cursor * 4 + 2] = scale;
      pointData[cursor * 4 + 3] = group;
      cursor += 1;
    };

    /** y of measure ring `i`, mirrored around a gap at the equator. */
    const ringY = (i: number) => {
      const half = Math.floor(ringCount / 2);
      const step = i < half ? half - i : i - half + 1;
      return (i < half ? -1 : 1) * (GAP + step * RING_PITCH);
    };

    for (let instance = 0; instance < 2; instance += 1) {
      for (let ring = 0; ring < ringCount; ring += 1) {
        const y = ringY(ring);
        // Sorted angles, not raw ones. Points blend in buffer order, so an
        // unsorted ring interleaves near and far dots and the ring stipples
        // instead of reading as one continuous line of engraving.
        const angles = new Float32Array(ringDots);
        for (let i = 0; i < ringDots; i += 1) angles[i] = rng() * Math.PI * 2;
        angles.sort();
        for (let i = 0; i < ringDots; i += 1) {
          const a = angles[i] ?? 0;
          write(RADIUS * Math.cos(a), y, RADIUS * Math.sin(a), instance, 0, MEASURE_SCALE, 0);
        }
      }
    }

    const bandTop = GAP + Math.ceil(ringCount / 2) * RING_PITCH;
    for (let instance = 0; instance < 2; instance += 1) {
      for (let d = 0; d < dividerCount; d += 1) {
        const a = (d / dividerCount) * Math.PI * 2 + instance * 0.19;
        for (let i = 0; i < dividerDots; i += 1) {
          const t = dividerDots === 1 ? 0.5 : i / (dividerDots - 1);
          const y = -bandTop + t * bandTop * 2;
          write(RADIUS * Math.cos(a), y, RADIUS * Math.sin(a), instance, 0, MEASURE_SCALE, 0);
        }
      }
    }

    for (let instance = 0; instance < 2; instance += 1) {
      for (let g = 0; g < noteGroups; g += 1) {
        const centre = (g / noteGroups) * Math.PI * 2 + instance * 0.4;
        for (let i = 0; i < noteDots; i += 1) {
          const a = centre + (rng() - 0.5) * 0.22;
          const y = (rng() - 0.5) * 2 * bandTop;
          write(RADIUS * Math.cos(a), y, RADIUS * Math.sin(a), instance, 1, NOTE_SCALE, g);
        }
      }
    }

    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
    geometry.setAttribute('aPointData', new THREE.BufferAttribute(pointData, 4));

    const uniforms: Uniforms = {
      uSpin: { value: 0 },
      uElapsed: { value: 0 },
      uViewScale: { value: 1 },
      uViewportYOffset: { value: 0 },
      uPixelRatio: { value: renderer.getPixelRatio() },
      uDotScale: { value: dotScale },
      uOpacity: { value: opacity },
      uNoteInterval: { value: noteInterval },
      uGroupCount: { value: noteGroups },
      uColor: { value: new THREE.Color(color) },
      uNoteColor: { value: new THREE.Color(noteColor) },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: CYLINDER_DOT_SCORE_VERT,
      fragmentShader: CYLINDER_DOT_SCORE_FRAG,
      uniforms,
      transparent: true,
      // Both off. With depth testing on, the first dot rasterised at a given
      // pixel would win and the far wall of the cylinder would punch holes in
      // the near one, because every dot is flattened to the same z.
      depthTest: false,
      depthWrite: false,
    });

    const points = new THREE.Points(geometry, material);
    points.frustumCulled = false;
    scene.add(points);

    el.appendChild(renderer.domElement);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';

    const resize = (w: number, h: number) => {
      renderer.setSize(w, h, false);
      camera.left = -w / 2;
      camera.right = w / 2;
      camera.top = h / 2;
      camera.bottom = -h / 2;
      camera.updateProjectionMatrix();
      const scale = Math.min(w, h) * viewScale;
      uniforms.uViewScale.value = scale;
      // The stack spans 0 .. STACK_OFFSET in y; pulling the whole thing down
      // by half of that puts the pair's centre on the container's centre.
      uniforms.uViewportYOffset.value = -STACK_OFFSET * 0.5 * scale;
      uniforms.uPixelRatio.value = renderer.getPixelRatio();
    };

    const draw = (elapsed: number) => {
      uniforms.uElapsed.value = elapsed;
      uniforms.uSpin.value = elapsed * spinSpeed;
      renderer.render(scene, camera);
    };

    resize(size.current.width, size.current.height);
    stage.current = { resize, draw };
    draw(STATIC_ELAPSED);

    return () => {
      stage.current = null;
      disposeObject(scene);
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
  }, [
    ready,
    ringCount,
    ringDots,
    dividerCount,
    dividerDots,
    noteGroups,
    noteDots,
    spinSpeed,
    noteInterval,
    dotScale,
    viewScale,
    opacity,
    color,
    noteColor,
    seed,
  ]);

  useEffect(() => {
    stage.current?.resize(width, height);
    if (reduced) stage.current?.draw(STATIC_ELAPSED);
  }, [width, height, reduced]);

  useRaf((_dt, elapsed) => stage.current?.draw(elapsed), ready && !reduced && !unsupported);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nulls the stage ref so a queued frame cannot touch a dead renderer, disposes the geometry through `disposeObject(scene)`, disposes the material, calls `disposeRenderer` for `dispose` + `forceContextLoss` + a zeroed backing store, and removes the canvas. `useRaf` unsubscribes on unmount.

**Reduced motion.** No frame loop is opened. One frame is drawn at `uElapsed = 0.4`, which shows both cylinders at a legible yaw with the first note group lit, so the structure and the highlight convention are both visible. Neither the rotation nor the playhead advances.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Leaving `depthTest` on. Every dot is projected with z = 0, so the first fragment written at a pixel wins and the far wall of the cylinder punches holes in the near one. The whole design depends on buffer order, not on the depth buffer.
- Sorting note dots into the buffer before measure dots, or drawing them as a second object added earlier. With depth testing off, "on top" means "later in the buffer" — get it wrong and the notes are half-eaten by the rings that surround them.
- Applying the stack offset before `rotateX`. It then rotates with the model, and the two cylinders slowly drift into each other over the course of a revolution instead of staying vertically separated.
- Writing raw random angles into a ring. Blending happens in buffer order, so unsorted angles interleave near and far dots and the ring visibly stipples rather than reading as a continuous engraved line.
- Driving the playhead from React state and an interval. It re-renders the tree once per beat, and the highlight lands one frame after the beat because the uniform write happens in a commit rather than in the frame loop — deriving it from `uElapsed` in the shader avoids both.
- Rebuilding the buffer when the container resizes. Model space is size-independent; only `uViewScale` and `uViewportYOffset` change, so a reflow costs two uniform writes rather than a dropped GL context.
- Setting `frustumCulled` at its default. Positions are unit-scale around the origin and the real placement happens in the shader, so three's bounding sphere does not describe what is on screen.

## Notes

- The two cylinders are "instances" only in the conceptual sense — this is one non-instanced `Points` with an index in an attribute, which is cheaper than instancing for a case where every vertex differs anyway.
- Total dot count is `2 * (ringCount * ringDots + dividerCount * dividerDots + noteGroups * noteDots)`, about 6100 at the defaults, in one draw call.

## Definition of done

Two stacked cylinders of dots turn at a constant rate, showing different faces to the viewer. Dots on the far side are visibly smaller and dimmer than those on the near side, and no dot ever pops in front of one it should be behind. A cluster of larger note dots lights every 1.2 seconds and cycles around the cylinder. Resize the container and the piece rescales without a flicker. With reduced motion it holds a single legible frame.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Cylinder Gallery Drum

A flat PlaneGeometry per item, all sharing one compiled program, each bent around a common cylinder by its own uniform. The camera never moves and the CPU never touches a vertex: scrolling changes one float, `position`, and every plane recomputes its angle, its height and its focus weight from that single scalar. Because the ring offset is the shortest signed distance on a circular index, the list is genuinely endless in both directions with no clones and no rebuilding.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Nineteen planes wrapped around a drum in the vertex shader, spun by wheel or scroll, focus falling off from centre.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1, gsap@^3.15.0, lenis@^1.3.11

## How it works

1. The vertex shader treats a vertex's own x as an arc offset: `angle = uSpiralAngle + position.x`, then `pos.x = uRadius * sin(angle)` and `pos.z = uRadius * cos(angle)`, so one world unit of plane width wraps exactly one radian of drum. `pos.y = sin(position.y)` pulls the top and bottom edges in, which turns a rolled sheet into a barrel.
2. Per frame and per plane, `wrappedOffset(i, position, count)` returns the shortest signed distance from that plane to the focused index — the value that makes index 0 sit one step before index 18 rather than eighteen steps after it. That offset drives `uSpiralAngle = (offset / count) * 2π * turns`, the vertical stack `y = -offset * spacing`, and the focus term.
3. Focus is `gaussian(offset)` = `exp(-offset²)`: 1.0 at the centre, 0.368 one step out, 0.018 two, 0.0001 three. The fragment shader mixes toward luminance and dims by that weight, so attention falls off continuously instead of one plane being flagged "selected".
4. A single `uIntro` scalar lerps between two complete layouts inside the shader — `mix(rowPos, ringPos, uIntro)` — where `rowPos` is a flat facing row and `ringPos` is the drum. Every intermediate value is a valid frame, and the CPU lerps the mesh x/y positions with the same scalar so the two layouts stay consistent.
5. Signed scroll velocity feeds `uDeform`, which adds `sin(position.y * 3.0 + 100.0) * uDeform * 0.07` to z and `sin(position.x * 3.0) * uDeform * 0.04` to y. It samples `position` — the original flat coordinates — not the already-bent `pos`, so the ripple is locked to the picture and reads as the image flexing rather than the drum wobbling.
6. Pointer proximity is measured inside the vertex shader by projecting each vertex once as a probe (`ndc = probe.xy / probe.w`), taking `exp(-mouseDist² * 5.0)`, lifting z by half of it and passing it to the fragment shader, which pushes the centred UV outward by the same weight so the bump also magnifies — a lens, not a bump.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `PLANE_WIDTH / PLANE_HEIGHT = 1 / 1.95`
  Width 1 because the bend uses the vertex's raw x as radians — at width 1 each plane spans exactly 1 rad of the drum, which is the whole reason no trigonometry is needed on the CPU. Height must stay under 2π/3 or `sin(position.y)` leaves its monotonic range and the barrel folds its own edges back through the surface.
- `CAMERA_FOV / CAMERA_Z = 45 / 5`
  The camera never animates, so these only set how much drum is in shot. Below ~35° the ring flattens into a row and the depth cue vanishes; above ~60° the near plane balloons and the barrel curve reads as a keystone error.
- `OVERSCAN = 1.12`
  The cover-fit UV is divided by this, zooming the crop in 12%. At exactly 1.0 the wave and the bulge push vertices past the sampled region and the texture's own clamped border smears along the edge. Beyond ~1.25 the crop eats the subject.
- `segments = 64`
  The bend is evaluated per vertex, so subdivision *is* the curve. Below ~24 the drum visibly becomes a folded card and the mouse bulge turns into a triangular tent; past ~128 you are paying vertex cost for a curve the pixel grid cannot resolve.
- `POSITION_SMOOTHING = 0.0006`
  Fraction of remaining distance left after one second. Larger (slower) and the drum lags visibly behind the wheel; much smaller and the velocity spike that drives `uDeform` never has time to build, so the wave disappears.
- `SNAP_DELAY_MS = 170`
  Idle time before the drum eases to a whole index. Under ~120 ms it fires between the discrete events of a single trackpad flick and fights the gesture; over ~250 ms the gallery feels like it forgot to settle.
- `MAX_DEFORM / DEFORM_PER_INDEX = 1.5 / 0.42`
  Deform is clamped to ±1.5 because the shader multiplies it by 0.07 world units — past that the planes intersect each other and the far side of the drum pokes through the near side. 0.42 sets how many index-steps per second count as full deflection.
- `RADIUS_VELOCITY_GAIN = 0.5`
  The drum widens up to 50% at full speed, which is what sells inertia. Above ~0.8 the nearest plane crosses the camera's near plane during a fast flick and clips away.
- `gaussian falloff = 1 (exp(-offset²))`
  A falloff of 1 keeps the immediate neighbours legible at 0.37 while the third plane out is effectively gone. Raising it dims the neighbours to black and the ring loses its context; lowering it flattens every plane to the same weight.
- `renderOrder scale = -worldZ * 1000`
  Reconstructed drum depth, scaled up so it survives rounding to an integer sort key. At a smaller scale adjacent planes collapse into the same bucket and flicker between frames.

## API

```ts
function CylinderGallery(props: { items: CylinderGalleryItem[]; drive?: "pointer" | "page"; radius?: number; turns?: number; spacing?: number; segments?: number; pixelsPerIndex?: number; opacity?: number; paint?: (ctx: CanvasRenderingContext2D, item: CylinderGalleryItem, index: number, size: { width: number; height: number }) => void; onSelect?: (item: CylinderGalleryItem, index: number) => void; onFocusChange?: (item: CylinderGalleryItem, index: number) => void; className?: string }): JSX.Element
```

- `items: CylinderGalleryItem[]`
  `{ id, title, meta?, hue? }` per plane. One mesh and one generated texture each.
- `drive: "pointer" | "page"` — default `"pointer"`
  Wheel and drag inside the component, or document scroll via a shared infinite Lenis.
- `radius: number` — default `2`
  Drum radius in world units, before the velocity widening.
- `turns: number` — default `3`
  Full revolutions the ring spans across the whole list.
- `spacing: number` — default `0.8`
  World units of vertical travel per index step.
- `segments: number` — default `64`
  Plane subdivisions per axis. This is the resolution of the bend.
- `pixelsPerIndex: number` — default `240`
  Document scroll pixels per index step, in `page` mode only.
- `opacity: number` — default `1`
  Global alpha multiplier applied before the focus falloff.
- `paint: (ctx, item, index, size) => void`
  Override the generated plate. Receives a 2D context for a 512x1024 canvas.
- `onSelect: (item, index) => void`
  Tap on the drum. A drag never counts as a tap.
- `onFocusChange: (item, index) => void`
  Fires when a different index takes the centre.
- `className: string`
  Merged onto the wrapper via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function CylinderGallery({
  items,
  drive = 'pointer',
  radius = 2,
  turns = 3,
  spacing = 0.8,
  segments = 64,
  pixelsPerIndex = 240,
  opacity = 1,
  paint,
  onSelect,
  onFocusChange,
  className,
}: CylinderGalleryProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);

  const { width, height } = useResizeObserver(host);
  const { inView } = useInView(host, { threshold: 0 });
  const visible = useVisibility();
  const reduced = useReducedMotion();
  const pointer = useSmoothPointer({ target: host, smoothing: 0.0015 });

  // `hasWebGL` touches `document`, so it cannot run during render without
  // disagreeing with the server. Start optimistic and correct after mount:
  // both renders then agree and nothing hydrates twice.
  const [supported, setSupported] = useState(true);
  useEffect(() => setSupported(hasWebGL()), []);

  const [focused, setFocused] = useState(0);

  const position = useRef(0);
  const target = useRef(0);
  const velocity = useRef(0);
  const intro = useRef(0);
  const strength = useRef(0);
  const hovered = useRef(false);
  const focusedRef = useRef(0);
  const snapTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
  const snapTween = useRef<Tween | null>(null);

  // Everything the frame loop reads but must not resubscribe on. Written on
  // every render, read once per frame; the loop itself never re-creates.
  const live = useRef({ radius, turns, spacing, opacity, drive, pixelsPerIndex, items, onSelect, onFocusChange });
  live.current = { radius, turns, spacing, opacity, drive, pixelsPerIndex, items, onSelect, onFocusChange };

  // Rebuilding the scene is expensive, so it is keyed on what actually changes
  // the meshes — identity, label and hue — not on the array's reference, which
  // is new on every render for any caller who writes the list inline.
  const itemsKey = items.map((item) => `${item.id}:${item.title}:${item.hue ?? ''}`).join('|');

  const lenis = useLenis({ infinite: true, enabled: drive === 'page' });

  const killSnap = useCallback(() => {
    if (snapTimer.current !== null) {
      clearTimeout(snapTimer.current);
      snapTimer.current = null;
    }
    snapTween.current?.kill();
    snapTween.current = null;
  }, []);

  const scheduleSnap = useCallback(() => {
    if (snapTimer.current !== null) clearTimeout(snapTimer.current);
    snapTimer.current = setTimeout(() => {
      snapTimer.current = null;
      // Snap the TARGET, not the position: the frame loop keeps damping
      // toward it, so the settle stays one continuous motion instead of a
      // second animation fighting the first.
      snapTween.current = gsap.to(target, {
        current: Math.round(target.current),
        duration: SNAP_DURATION,
        ease: 'power3.out',
      });
    }, SNAP_DELAY_MS);
  }, []);

  /* ---- scene construction ------------------------------------------------ */

  const ready = width > 1 && height > 1 && supported;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready || items.length === 0) return;

    const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
    // Capped, not raw. A 3x phone with an uncapped ratio pays 9x the fill rate
    // for a difference nobody can see.
    renderer.setPixelRatio(pixelRatio());
    renderer.setSize(el.clientWidth, el.clientHeight, false);
    renderer.setClearColor(0x000000, 0);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';
    el.appendChild(renderer.domElement);

    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(
      CAMERA_FOV,
      el.clientWidth / Math.max(el.clientHeight, 1),
      0.1,
      100,
    );
    camera.position.z = CAMERA_Z;

    // One geometry for every plane. The bend is per-vertex, so the mesh has to
    // be dense enough that the curve reads as a curve: below ~24 segments the
    // drum visibly becomes a folded card.
    const geometry = new THREE.PlaneGeometry(PLANE_WIDTH, PLANE_HEIGHT, segments, segments);
    const planeAspect = PLANE_WIDTH / PLANE_HEIGHT;
    const paintItem = paint ?? paintPlate;
    const maxAnisotropy = Math.min(4, renderer.capabilities.getMaxAnisotropy());

    const planes: Plane[] = items.map((item, index) => {
      const canvas = document.createElement('canvas');
      canvas.width = TEXTURE_WIDTH;
      canvas.height = TEXTURE_HEIGHT;
      const ctx = canvas.getContext('2d');
      if (ctx) paintItem(ctx, item, index, { width: TEXTURE_WIDTH, height: TEXTURE_HEIGHT });

      const texture = new THREE.CanvasTexture(canvas);
      // sRGB in, sRGB out. Skip this and the plates render noticeably darker
      // than the CSS colours sitting next to them.
      texture.colorSpace = THREE.SRGBColorSpace;
      texture.anisotropy = maxAnisotropy;
      texture.needsUpdate = true;

      const uniforms: PlaneUniforms = {
        uTexture: { value: texture },
        uTextureAspect: { value: TEXTURE_WIDTH / TEXTURE_HEIGHT },
        uPlaneAspect: { value: planeAspect },
        uOverscan: { value: OVERSCAN },
        uSpiralAngle: { value: 0 },
        uRadius: { value: radius },
        uIntro: { value: 0 },
        uFocus: { value: 1 },
        uOpacity: { value: opacity },
        uDeform: { value: 0 },
        uMouseNdc: { value: new THREE.Vector2(0, 0) },
        uMouseStrength: { value: 0 },
      };

      // A material per mesh, because every plane needs its own spiralAngle,
      // radius and focus. three keys its program cache on the shader source,
      // so all of these share one compiled program regardless.
      const material = new THREE.ShaderMaterial({
        vertexShader: cylinderGalleryVertexShader,
        fragmentShader: cylinderGalleryFragmentShader,
        uniforms,
        transparent: true,
        side: THREE.DoubleSide,
        // Painted strictly back to front via renderOrder below, so neither
        // depth write nor depth test has anything to contribute — and both
        // would be wrong anyway, since the depth they compare is the depth of
        // a mesh the CPU thinks is still flat at the origin.
        depthWrite: false,
        depthTest: false,
      });

      const mesh = new THREE.Mesh(geometry, material);
      // The CPU-side geometry is a flat plane at mesh.position; the shape you
      // can actually see is somewhere else entirely. Frustum culling compares
      // against that stale bounding sphere and blanks planes that are plainly
      // on screen.
      mesh.frustumCulled = false;
      scene.add(mesh);
      return { mesh, uniforms, texture };
    });

    stage.current = { renderer, scene, camera, geometry, planes };
    renderer.render(scene, camera);

    return () => {
      stage.current = null;
      for (const plane of planes) {
        scene.remove(plane.mesh);
        // disposeObject walks a material's own properties looking for
        // textures. These live inside `uniforms`, two levels down, so it will
        // never find them — they have to be released by hand.
        plane.texture.dispose();
      }
      disposeObject(scene);
      geometry.dispose();
      // dispose() frees GPU objects and leaves the context alive. Only
      // forceContextLoss, which disposeRenderer calls, hands it back.
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
    // `items` is read through the key; `radius`/`opacity` only seed uniforms
    // the frame loop overwrites immediately.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, itemsKey, segments, paint]);

  /* ---- size ------------------------------------------------------------- */

  useEffect(() => {
    const current = stage.current;
    if (!current || width < 1 || height < 1) return;
    current.renderer.setPixelRatio(pixelRatio());
    // `false` — the canvas is sized by CSS at 100%/100%; letting three write
    // inline pixel dimensions makes it fight the flex parent on every resize.
    current.renderer.setSize(width, height, false);
    current.camera.aspect = width / height;
    current.camera.updateProjectionMatrix();
  }, [width, height]);

  /* ---- intro morph ------------------------------------------------------- */

  useEffect(() => {
    if (!ready) return;
    if (reduced) {
      intro.current = 1;
      return;
    }
    intro.current = 0;
    const tween = gsap.to(intro, {
      current: 1,
      duration: INTRO_DURATION,
      delay: INTRO_DELAY,
      ease: 'power3.inOut',
    });
    return () => {
      tween.kill();
    };
  }, [ready, reduced]);

  /* ---- input ------------------------------------------------------------- */

  useEffect(() => {
    const el = host.current;
    if (!el || drive !== 'pointer') return;

    const onWheel = (event: WheelEvent) => {
      // Non-passive on purpose: without preventDefault the drum spins AND the
      // page scrolls under it, which reads as two competing gestures.
      event.preventDefault();
      killSnap();
      target.current += event.deltaY * WHEEL_INDEX_PER_PIXEL;
      scheduleSnap();
    };

    el.addEventListener('wheel', onWheel, { passive: false });
    return () => el.removeEventListener('wheel', onWheel);
  }, [drive, killSnap, scheduleSnap]);

  useEffect(() => {
    const el = host.current;
    if (!el) return;
    const enter = () => {
      hovered.current = true;
    };
    const leave = () => {
      hovered.current = false;
    };
    el.addEventListener('pointerenter', enter);
    el.addEventListener('pointerleave', leave);
    return () => {
      el.removeEventListener('pointerenter', enter);
      el.removeEventListener('pointerleave', leave);
    };
  }, []);

  useDrag(host, {
    enabled: drive === 'pointer',
    onDragStart: killSnap,
    onDrag: (state) => {
      target.current -= state.deltaY * DRAG_INDEX_PER_PIXEL;
    },
    onDragEnd: (_state, moved) => {
      if (!moved) {
        const { items: list, onSelect: select } = live.current;
        const index = wrapIndex(Math.round(position.current), list.length);
        const item = list[index];
        if (item) select?.(item, index);
      }
      scheduleSnap();
    },
  });

  useEffect(() => killSnap, [killSnap]);

  /* ---- the frame --------------------------------------------------------- */

  useRaf(
    (dt) => {
      const current = stage.current;
      if (!current) return;
      const {
        radius: baseRadius,
        turns: baseTurns,
        spacing: baseSpacing,
        opacity: alpha,
        drive: mode,
        pixelsPerIndex: perIndex,
        items: list,
        onFocusChange: notify,
      } = live.current;

      const count = current.planes.length;
      if (count === 0) return;

      if (mode === 'page') {
        const instance = lenis.current;
        if (instance) target.current = instance.scroll / Math.max(perIndex, 1);
      }

      const previous = position.current;
      position.current = damp(position.current, target.current, POSITION_SMOOTHING, dt);

      // Index steps per second, smoothed by the same damp that produced the
      // position, so the wave can never lead the geometry it is bending.
      const instant = dt > 0 ? (position.current - previous) / dt : 0;
      velocity.current = damp(velocity.current, instant, 0.002, dt);
      const normalized = clamp(velocity.current / VELOCITY_REFERENCE, -1, 1);

      strength.current = damp(
        strength.current,
        hovered.current && !reduced ? 1 : 0,
        STRENGTH_SMOOTHING,
        dt,
      );

      const s = intro.current;
      const speed = Math.abs(normalized);
      const liveRadius = baseRadius * (1 + RADIUS_VELOCITY_GAIN * speed);
      const liveSpacing = baseSpacing * (1 + SPACING_VELOCITY_GAIN * speed);
      const angularScale = 1 + ANGULAR_VELOCITY_GAIN * speed;
      const deform = reduced
        ? 0
        : clamp(velocity.current * DEFORM_PER_INDEX, -MAX_DEFORM, MAX_DEFORM);

      // The flat-row layout spans the frustum's visible WIDTH at z = 0. Sizing
      // it from window.innerWidth, or from the visible height, leaves the row
      // short on wide viewports and clipped on narrow ones.
      const visibleWidth =
        2 * Math.tan((CAMERA_FOV * Math.PI) / 360) * CAMERA_Z * current.camera.aspect * 0.86;
      const step = visibleWidth / Math.max(count - 1, 1);
      const rowWidth = (count - 1) * step;

      const mx = pointer.current.active ? pointer.current.ndcX : 0;
      const my = pointer.current.active ? pointer.current.ndcY : 0;

      for (let i = 0; i < count; i++) {
        const plane = current.planes[i];
        if (!plane) continue;

        // The one call that makes a finite array behave like an infinite ring:
        // item 0 is one step BEFORE item 18, not eighteen steps after it.
        const offset = wrappedOffset(i, position.current, count);
        const angle = (offset / count) * Math.PI * 2 * baseTurns * angularScale;
        const y = -offset * liveSpacing;

        plane.mesh.position.x = (i * step - rowWidth / 2) * (1 - s);
        plane.mesh.position.y = y * s;
        plane.mesh.scale.setScalar(lerp(0.62, 1, s));

        const u = plane.uniforms;
        u.uSpiralAngle.value = angle;
        u.uRadius.value = liveRadius;
        u.uIntro.value = s;
        u.uDeform.value = deform;
        u.uOpacity.value = alpha;
        u.uMouseStrength.value = strength.current;
        u.uMouseNdc.value.set(mx, my);
        // exp(-d²): 1.000 at the centre, 0.368 one step out, 0.018 two, 0.0001
        // three. Continuous, branchless, and the reason the drum reads as
        // analogue rather than as a list with a selected row.
        u.uFocus.value = lerp(1, gaussian(offset), s);

        // Transparent meshes are sorted by three using the CPU position, which
        // for this drum is (0, y, 0) for every plane. Reconstructing the depth
        // the shader will actually produce and painting back to front is the
        // only way the far side of the ring stays behind the near side.
        const worldZ = liveRadius * Math.cos(angle) * s;
        plane.mesh.renderOrder = Math.round(-worldZ * 1000);
      }

      const nextFocus = wrapIndex(Math.round(position.current), count);
      if (nextFocus !== focusedRef.current) {
        focusedRef.current = nextFocus;
        setFocused(nextFocus);
        const item = list[nextFocus];
        if (item) notify?.(item, nextFocus);
      }

      current.renderer.render(current.scene, current.camera);
    },
    ready && inView && visible,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the wheel and pointerenter/pointerleave listeners, kills the intro tween and any pending snap timeout plus its tween, removes every mesh from the scene, disposes each `CanvasTexture` by hand (they sit inside `material.uniforms`, where `disposeObject` cannot reach), runs `disposeObject` for the geometries and materials, disposes the shared geometry, then `disposeRenderer` — `setAnimationLoop(null)`, `dispose()`, `forceContextLoss()` — and removes the canvas from the DOM. The frame loop reads a stage ref that is nulled first, so a queued frame after teardown is a no-op rather than a null context throw.

**Reduced motion.** The intro morph is skipped — `uIntro` is set to 1 on mount, so the drum is simply already assembled. The velocity wave is pinned to 0 and the pointer bulge never engages, so the surface stays flat. Navigation still works and still eases: wheel, drag and the snap-to-index tween are unchanged, because the user asked for less motion, not for a gallery that cannot move.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Scaling `uRadius` from 0 to animate the intro. At radius 0 every vertex of every plane lands on the origin, so the "flat" state is nineteen invisible slivers stacked in one spot. Lerp between two position vectors — `mix(rowPos, ringPos, uIntro)` — and the flat state is a real layout you can hold.
- Leaving `frustumCulled` at its default. The CPU-side geometry is still a flat plane sitting at `mesh.position`; the visible shape is somewhere else entirely. three culls against that stale bounding sphere and planes that are plainly on screen blink out at the edges.
- Trusting three's transparency sort. It orders transparent meshes by their object position, which for this drum is `(0, y, 0)` for every single plane, so the far side of the ring paints over the near side at random. Reconstruct the depth the shader will produce (`radius * cos(angle) * intro`) and set `renderOrder` from it each frame.
- Expecting `disposeObject` to free the plate textures. It scans a material's own properties for anything with `isTexture`; these textures live two levels down inside `material.uniforms`, so it never sees them and nineteen 512x1024 canvases stay resident on the GPU after unmount. They are disposed explicitly from a tracked list.
- Calling `renderer.dispose()` and stopping there. That releases GPU objects but keeps the WebGL context alive; Chromium caps a renderer process at roughly 16 and silently kills the oldest, so a docs page that mounts several of these blanks the ones above it. `disposeRenderer` calls `forceContextLoss`.
- Attaching the wheel listener passively. Without `preventDefault` the drum spins and the host page scrolls at the same time, which reads as two gestures fighting; the listener is registered with `{ passive: false }`.
- Sampling the deformation wave from the already-bent `pos` instead of the original `position`. The ripple then travels with the drum rotation rather than staying pinned to the image, and the effect looks like a rendering fault instead of the picture flexing.
- Sizing the flat-row layout from `window.innerWidth`. The row has to span the frustum's visible width at z = 0, which is `2 * tan(fov/2) * cameraZ * aspect` — the container width in pixels has no fixed relationship to that, so the row overshoots on wide viewports and clips on narrow ones.
- Omitting `#include <colorspace_fragment>` from a `ShaderMaterial`. three only injects output conversion into its own materials, so raw linear values ship into an sRGB framebuffer and the plates render visibly washed out next to the CSS around them.
- Rebuilding the scene when the `items` array identity changes. Any caller who writes the list inline hands over a new array every render, which would tear down nineteen textures and a GL context on every keystroke. The setup effect keys on a string built from id, title and hue.

## Notes

- Textures are drawn at mount to a 512x1024 canvas per item — a hue ramp, hairline bands and a numeral. The bands are not decoration: a smooth gradient hides every deformation the shader applies, so the plate needs structure for the wave and the bulge to bend.
- All nineteen materials are separate `ShaderMaterial` instances because each needs its own uniforms, but three keys its program cache on the shader source, so they share a single compiled program.
- `drive: "page"` opts into a shared refcounted Lenis with `infinite: true`, which is the technique in its original form — the gallery *is* the page. The default `drive: "pointer"` keeps every gesture inside the component's own box.

## Definition of done

On mount the planes start as a flat row facing you and curl into a drum over about 1.6 s. Wheel or drag spins it endlessly in both directions with no seam and no jump at the ends; stop moving and it eases to centre one plane. The centred plane is full colour and the neighbours fade toward grey within two steps. Flick hard and the images ripple, the drum widens, and the ripple runs opposite ways depending on direction. Move the pointer over a plane and a soft lens follows it, magnifying rather than just denting. Unmount from React DevTools and the canvas leaves the DOM with no context-lost warning; mount and unmount twenty times and no context is dropped. With `prefers-reduced-motion: reduce` the drum is already assembled on the first frame and neither the ripple nor the lens ever appears.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Dataset-Driven Parallax

Depth is declared in the markup: any descendant carrying `data-parallax="0.3"` drifts at that rate. One effect walks the container, parses the attribute and builds a scrubbed tween per layer, so adding a new plane to a hero is an attribute rather than a code change. Travel is expressed as a percentage of the element's own height, which keeps the effect proportional at every breakpoint.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Layers drift at a rate written on the element itself, over the widest possible scroll window.

- Category: scroll
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. The container is walked once for `[data-parallax]` descendants. The depth is read with a double fallback — `parseFloat(el.getAttribute(attr) ?? "") || fallback` — so a missing value, an empty value and a non-numeric value all land on the same default.
2. Each layer gets `gsap.to(layer, { yPercent: -(100 * depth), ease: "none" })`. `yPercent` is a percentage of the element's own height, so a 2000px hero and a 400px mobile hero travel proportionally with no media query.
3. `ease: "none"` is required, not stylistic. Any easing on a scrubbed tween means the layer accelerates and decelerates independently of the wheel, so two layers at different depths drift out of sync mid-scroll and snap back at the ends.
4. The trigger window is `start: "top bottom"` to `end: "bottom top"` — the full travel range, from the instant the element enters the scroller to the instant it leaves. That is the widest window available, which spreads the same travel across the most scroll distance.
5. `invalidateOnRefresh: true` makes ScrollTrigger recompute start and end on resize; percentage-based travel is derived from element height and a stale measurement leaves every layer offset.
6. Under reduced motion the effect returns before creating anything, so the layers render at their authored positions.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `DEFAULT_DEPTH = 0.15`
  Fallback drift: 15% of the element's height across the whole window. Below ~0.05 the layer looks static next to its neighbours; above ~0.4 it visibly separates from the content it belongs to and reads as a rendering fault.
- `start / end = 'top bottom' / 'bottom top'`
  The maximum-length window. Narrowing it (say `top 80%` to `bottom 20%`) forces the same travel through less scroll, which is the difference between drift and the page appearing to come apart.
- `yPercent multiplier = -100`
  Negative so layers move against the scroll — the direction that reads as distance. A positive multiplier moves them with the scroll, which reads as the layer being dragged.
- `scrub = true`
  Locked to scroll position with no lag. Parallax is a spatial relationship: a numeric scrub adds lag, and lagging layers cross each other during a fast flick.

## API

```ts
function DatasetParallax(props: { children: ReactNode; attribute?: string; fallback?: number; scrub?: boolean | number; scrollerRef?: RefObject<HTMLElement | null>; className?: string }): JSX.Element
```

- `children: ReactNode`
  Section content. Any descendant with the depth attribute becomes a layer.
- `attribute: string` — default `'data-parallax'`
  Attribute carrying the depth. Its value is parsed as a float.
- `fallback: number` — default `0.15`
  Depth used when the attribute is missing, empty or not a number.
- `scrub: boolean | number` — default `true`
  ScrollTrigger scrub. A number adds that many seconds of lag.
- `scrollerRef: RefObject<HTMLElement | null>`
  The scroll container that owns the scroll position. Omit for the document.
- `className: string`
  Merged onto the container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const DEFAULT_DEPTH = 0.15;

export function DatasetParallax({
  children,
  attribute = 'data-parallax',
  fallback = DEFAULT_DEPTH,
  scrub = true,
  scrollerRef,
  className,
}: DatasetParallaxProps) {
  const root = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();

  useGsap(
    gsap,
    () => {
      const el = root.current;
      if (!el || reduced) return;

      const scroller = scrollerRef?.current ?? undefined;

      for (const layer of Array.from(el.querySelectorAll<HTMLElement>(`[${attribute}]`))) {
        // Double fallback, and both halves are load-bearing. `?? ''` handles a
        // bare `data-parallax` with no value; `|| fallback` handles
        // `parseFloat` returning NaN on anything non-numeric. A NaN reaching
        // `yPercent` does not throw — it silently pins the layer at its
        // untransformed position, which looks like the effect simply not
        // working on that one element.
        const raw = layer.getAttribute(attribute) ?? '';
        const depth = parseFloat(raw) || fallback;

        gsap.to(layer, {
          yPercent: -(100 * depth),
          ease: 'none',
          scrollTrigger: {
            trigger: layer,
            scroller,
            // The widest possible window: begins the instant the layer's top
            // touches the bottom of the scroller and ends when its bottom
            // leaves the top. Any narrower range concentrates the same travel
            // into less scroll, which is what makes cheap parallax feel like
            // the page is sliding apart.
            start: 'top bottom',
            end: 'bottom top',
            scrub,
            // Percent-based travel is recomputed from element height; without
            // this a resize leaves every layer measured against the old one.
            invalidateOnRefresh: true,
          },
        });
      }
    },
    root,
    [attribute, fallback, scrub, reduced],
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useGsap` wraps the whole walk in a `gsap.context`; `ctx.revert()` on unmount kills every tween and its ScrollTrigger and strips the inline `transform` GSAP wrote. Without the revert the triggers survive the unmount and keep scrubbing detached nodes on the next page.

**Reduced motion.** The effect returns before creating any tween, so every layer stays exactly where the stylesheet put it. The layout is authored to be correct at rest, so nothing is missing — the planes simply do not separate.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Using `y` in pixels instead of `yPercent`. It looks correct at the breakpoint you tuned and wrong at every other one — on a short viewport a fixed 300px offset can push the layer entirely out of its own container.
- A single `|| 0.15` fallback. `el.dataset.parallax || "0.15"` covers the missing attribute, but `parseFloat("fast")` returns `NaN` and `NaN` reaching `yPercent` does not throw — the layer just silently stops moving, which is a bug you find by eye weeks later.
- Adding an ease to a scrubbed tween. The layer then accelerates on its own schedule rather than the wheel's, so layers at different depths drift out of relative order and snap at each end of the range.
- Omitting `invalidateOnRefresh`. Rotating a phone or opening a sidebar changes element height; the tween keeps using the height measured on mount and every layer sits at the wrong offset until reload.
- Leaving the scroller as the document when the content lives in an `overflow-y-auto` container. Every start and end is then measured against the window, so nothing moves at the right time — or at all.
- Building one giant timeline for all layers. Independent triggers per layer are correct here: a layer must respond to its own position in the scroller, not to a shared progress value.

## Notes

- The attribute name is configurable so the component can coexist with an existing convention rather than forcing `data-parallax` onto a codebase that already has one.
- Depths above 1 are legal and useful for a single foreground element that should outrun everything, but two such layers next to each other stop reading as depth.

## Definition of done

Scroll the section: layers with a larger `data-parallax` value visibly outrun the ones with smaller values, and every layer is back in its authored position when it leaves the scroller. Change an attribute value in devtools and reload — the rate changes with no code edit. Resize the window mid-scroll and the layers stay aligned with their content.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Delayed-Unmount Loader

An inverted full-cover loading panel that fades out on a plain CSS transition. The mechanism is the timing of its own removal: when `loading` goes false the element sets `data-exit` and starts a 600ms fade, and a matching 600ms timeout is what finally unmounts it. Nothing is animated in JavaScript — one boolean, one timeout, one transition.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A loading overlay that stays mounted 600ms past the signal so its fade can actually play before it leaves.

- Category: transition
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. Internal `mounted` state starts true so the overlay is present in the very first paint, before any effect has run. Deriving visibility from the `loading` prop alone is what makes the exit impossible to animate.
2. When `loading` flips false, `data-exit="true"` lands on the element and the CSS rule `.k-dul[data-exit="true"] { opacity: 0; pointer-events: none }` takes over the transition declared on `.k-dul`.
3. In the same effect a `setTimeout(() => setMounted(false), exitMs)` is armed. The timeout and the transition read the same `exitMs`, passed to CSS as the custom property `--k-dul-exit`, so they cannot drift apart.
4. If `loading` goes true again — a second route, a refetch — the effect clears the pending timeout and re-arms the overlay. Because the exit is a CSS transition rather than a keyframe, an interruption mid-fade reverses from wherever the opacity had got to instead of jumping to 1.
5. The panel is drawn with the foreground colour as its background and the background colour as its text, so the reveal reads as a tonal inversion rather than a curtain, and a single pulsing dot between two brackets is the only moving part.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `exitMs = 600`
  Drives both the CSS transition and the unmount timeout. Under ~350ms a full-bleed tonal flip reads as a flicker; over ~800ms the page is legible behind a veil that is still technically covering it. Whatever value you pick, the timeout must be >= the transition or the node disappears mid-fade.
- `pulse period = 1s`
  One cycle per second is close to a resting heart rate and reads as "alive, waiting". Faster reads as urgency and makes a slow load feel worse than it is.
- `pulse scale range = 0.86 -> 1`
  Small enough that the dot never appears to change its typographic size between the brackets; a larger range makes the bracket pair look mis-set.

## API

```ts
function DelayedUnmountLoader(props: { loading: boolean; exitMs?: number; label?: string; hint?: string; position?: 'fixed' | 'absolute'; className?: string }): JSX.Element | null
```

- `loading: boolean`
  While true the overlay is opaque. False starts the reveal.
- `exitMs: number` — default `600`
  Fade length and unmount delay. One number drives both.
- `label: string` — default `'Loading experience'`
  Left-hand text.
- `hint: string` — default `'it won’t be long'`
  Right-hand text.
- `position: 'fixed' | 'absolute'` — default `'fixed'`
  Viewport cover, or cover of the nearest positioned ancestor.
- `className: string`
  Merged onto the overlay.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function DelayedUnmountLoader({
  loading,
  exitMs = 600,
  label = 'Loading experience',
  hint = 'it won’t be long',
  position = 'fixed',
  className,
}: DelayedUnmountLoaderProps) {
  // Starts true so the overlay is in the very first paint. Deriving it from
  // `loading` alone is what makes the exit un-animatable.
  const [mounted, setMounted] = useState(true);

  useEffect(() => {
    if (loading) {
      // A second load (route change, refetch) re-arms the overlay.
      setMounted(true);
      return;
    }
    const t = setTimeout(() => setMounted(false), exitMs);
    return () => clearTimeout(t);
  }, [loading, exitMs]);

  if (!mounted && !loading) return null;

  return (
    <div
      // `data-exit` is the only thing that changes on the element. The
      // transition is declarative, so an interrupted reveal (loading goes
      // true again mid-fade) reverses from wherever it got to instead of
      // jumping.
      data-exit={!loading}
      aria-hidden={!loading}
      className={cn(
        'k-dul z-50 flex items-center justify-center',
        // Inverted: the loader is the page's negative, so the reveal reads as
        // a tonal flip rather than a curtain being pulled aside.
        'bg-fg text-bg',
        position === 'fixed' ? 'fixed inset-0' : 'absolute inset-0',
        className,
      )}
      style={{ ['--k-dul-exit' as string]: `${exitMs}ms` }}
    >
      <style>{CSS}</style>
      <div className="flex w-full items-center justify-between gap-2 px-4">
        <p className="w-1/3 font-mono text-[0.6875rem] uppercase leading-none tracking-[0.08em]">
          {label}
        </p>
        <p className="flex w-1/3 justify-center font-mono text-2xl leading-none tracking-[0.1em]">
          <span aria-hidden>[</span>
          <span className="k-dul-dot inline-block px-[0.15em]" aria-hidden>
            &middot;
          </span>
          <span aria-hidden>]</span>
        </p>
        <p className="w-1/3 text-right font-mono text-[0.6875rem] uppercase leading-none tracking-[0.08em]">
          {hint}
        </p>
      </div>
    </div>
  );
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The single timeout is cleared in the effect's cleanup, so a route change or an unmount during the fade cannot call `setMounted` on a component React has already released.

**Reduced motion.** The dot stops pulsing and sits at a fixed opacity, and the fade collapses to 1ms so the overlay simply disappears. The unmount delay is unchanged, and the exiting overlay is `pointer-events: none` throughout, so nothing is blocked while it waits.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Rendering `{loading && <Loader />}`. React removes the node on the same commit that flips the flag, so the transition has no element to run on and the loader disappears on a cut. The component owns its own removal.
- Using a keyframe animation with `forwards` for the exit. Interrupt it by starting a second load and it snaps to the start; a transition on a class/attribute is interruptible in both directions for free.
- Letting the timeout and the transition duration live in different files. They drift, and either the loader is cut off mid-fade or a fully transparent overlay sits on top of the page eating clicks. One `exitMs` feeds both, and the CSS reads it from a custom property.
- Forgetting `pointer-events: none` in the exit state. For the whole fade the page is visible but not clickable, which reads as the site having frozen just as it finished loading.
- Not clearing the timeout when `loading` goes true again. The stale timer unmounts the re-armed overlay mid-load and the page flashes through underneath.
- Leaving the pulse running under `prefers-reduced-motion`. An indefinitely looping animation is exactly what that preference exists to stop; the media query drops it to a static dot.

## Notes

- App Router wiring: render this in `app/layout.tsx` above `{children}` and drive `loading` from your own readiness state — `document.fonts.ready`, a data promise, or a route-change flag from `usePathname()`. For a first-load preloader that must never hang, use `safe-preloader` instead: this component trusts whoever owns the boolean.
- `position="absolute"` covers the nearest positioned ancestor instead of the viewport, which is what makes it embeddable in a card or a preview frame.
- The delayed-unmount pattern generalises: any exit animation on a conditionally rendered node needs the node to outlive the condition by at least the animation duration.

## Definition of done

Load the page and the inverted panel is in the first paint with its dot pulsing. When loading ends the panel fades over 600ms and the node is gone from the DOM immediately afterwards — not before. Trigger a second load mid-fade and the panel returns from its current opacity rather than snapping to full.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Depth Fade And Travelling Pulse

A lattice of dots bent around a shallow arc and lit by a pulse that travels across it. Depth is faked entirely from model-space z, which drives alpha and point size at the same time, so the arc reads as curved with no depth buffer and no perspective camera. The pulse is a cosine whose phase varies per column, and its crest also pushes dots toward the viewer, so the two techniques compound: the wave arrives as a moving band of brighter, larger dots.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A dot lattice on an arc: z drives alpha and point size together, and a per-column phase sweeps the pulse across the field.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. Columns are placed by angle across `arcSpan`, then z is renormalised so the centre column lands at exactly `+arcDepth` and both edges at `-arcDepth`, independent of the span. Without that renormalisation the usable z range shrinks with the span and the depth cue silently weakens whenever the arc is flattened.
2. The depth cue is `depthT = clamp((z + 0.55) / 1.1, 0, 1)`, which drives alpha from 0.25 to 1.0 *and* point size from 0.65 to 1.0. Both together are the point: alpha alone reads as a grey copy of the near dots, size alone reads as a resolution change, and only the pair reads as distance.
3. The pulse is `raw = 0.65 + 0.35 * cos(2π * (uElapsed / pulseCycle - phase))`, with `phase = columnT * waveTurns + rowT * 0.12` baked into an attribute. Subtracting the phase inside the cosine is what makes the crest move *along* the lattice rather than the whole field breathing in unison.
4. The crest, renormalised to 0..1, is added to z as `p.z += crest * uWaveDepth`, so the wave feeds the depth cue. A dot at the crest is pushed nearer, and the depth fade then brightens and enlarges it — one displacement drives three visible changes.
5. The pulse ramps in over the first second (`clamp(uElapsed / 1.0, 0, 1)`), so the first frame does not land on an arbitrary point of the cosine and flash. Yaw is `sin(elapsed * yawSpeed * 2π) * yawAmplitude` degrees, applied in the shader after the wave so the lattice rocks through its own depth range.
6. `gl_PointSize` is clamped to a 2px floor and alpha is compensated by `unclamped² / clamped²`, so the field keeps the same apparent density at DPR 1 and DPR 2 instead of getting heavier on retina.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `PULSE_BASE / PULSE_SWING = 0.65 / 0.35`
  The pulse rides between 0.30 and 1.00 of nominal size and alpha. A trough at 0 would make dots vanish entirely and the lattice would look like it is dropping frames rather than breathing.
- `DEFAULT_CYCLE / pulseCycle = 3.0 seconds`
  Under ~2s the crest outruns the eye following it across the lattice; over ~5s it stops reading as a wave and becomes an idle shimmer.
- `INTRO_SECONDS = 1.0`
  Ramps the pulse amplitude from 0. Without it the first rendered frame samples the cosine at an arbitrary phase and the whole field flashes on mount.
- `DEPTH_HALF_RANGE = 0.55`
  The arc spans ±0.34 and the wave adds up to +0.18, so normalising over ±0.55 leaves headroom at both ends — no dot sits at exactly 0 or 1 and the falloff never visibly clips.
- `DEPTH_MIN_SIZE / DEPTH_MAX_SIZE = 0.65 / 1.0`
  Far dots at 65% of near ones. Paired with the 0.25→1.0 alpha ramp; either cue on its own is ambiguous, and this ratio is the smallest that still reads as depth at preview-card sizes.
- `waveTurns = 1.4`
  Wavelengths visible across the lattice at any instant. At 1 the crest and trough sit at opposite edges and it reads as a tilt; past ~2.5 the bands are too narrow to track and the field just shimmers.
- `ROW_PHASE_LEAN = 0.12`
  Small row contribution to the phase, so the crest leans instead of arriving as a perfectly vertical bar. Bigger than ~0.3 and the wave starts reading as diagonal stripes.
- `yawAmplitude / yawSpeed = 16 degrees / 0.25 Hz`
  The lattice rocks rather than spins. A full rotation would carry columns through the arc's entire depth range and destroy the near/far reading the crest depends on.
- `crest tint threshold = smoothstep(0.65, 1.0, crest)`
  Only the top third of the crest picks up `crestColor`. Tinting the whole cosine spreads the accent across the field and the wave stops having a location.

## API

```ts
function DepthPulseTravellingWave(props: { columns?: number; rows?: number; arcSpan?: number; arcDepth?: number; fieldHeight?: number; pulseCycle?: number; waveTurns?: number; waveDepth?: number; yawAmplitude?: number; yawSpeed?: number; dotScale?: number; viewScale?: number; opacity?: number; color?: string; crestColor?: string; seed?: number | string; className?: string }): JSX.Element
```

- `columns: number` — default `110`
  Columns across the arc.
- `rows: number` — default `44`
  Rows down each column.
- `arcSpan: number` — default `110`
  Arc the lattice is bent around, in degrees.
- `arcDepth: number` — default `0.34`
  Half-depth of the arc in model units — how far the edges recede.
- `fieldHeight: number` — default `1.1`
  Lattice height in model units.
- `pulseCycle: number` — default `3`
  Seconds per pulse.
- `waveTurns: number` — default `1.4`
  Wavelengths visible across the lattice at any instant.
- `waveDepth: number` — default `0.18`
  How far a crest pushes a dot toward the viewer, in model units.
- `yawAmplitude: number` — default `16`
  Peak yaw of the whole lattice, in degrees.
- `yawSpeed: number` — default `0.25`
  Yaw oscillations per second.
- `dotScale: number` — default `1`
  Dot radius multiplier in CSS pixels.
- `viewScale: number` — default `0.46`
  Model-to-pixel scale as a fraction of the container short side.
- `opacity: number` — default `1`
  Multiplier applied to every dot.
- `color: string` — default `'#6f757e'`
  Base dot colour.
- `crestColor: string` — default `'#ffffff'`
  Colour mixed in at the top of the crest.
- `seed: number | string` — default `'depth-pulse-travelling-wave'`
  Seeds the sub-cell jitter for a stable, hydration-safe lattice.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function DepthPulseTravellingWave({
  columns = 110,
  rows = 44,
  arcSpan = 110,
  arcDepth = 0.34,
  fieldHeight = 1.1,
  pulseCycle = 3,
  waveTurns = 1.4,
  waveDepth = 0.18,
  yawAmplitude = 16,
  yawSpeed = 0.25,
  dotScale = 1,
  viewScale = 0.46,
  opacity = 1,
  color = '#6f757e',
  crestColor = '#ffffff',
  seed = 'depth-pulse-travelling-wave',
  className,
}: DepthPulseTravellingWaveProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  const { width, height } = useResizeObserver(host);
  const size = useRef({ width, height });
  size.current = { width, height };

  const reduced = useReducedMotion();
  const ready = width > 0 && height > 0;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    if (!hasWebGL()) {
      setUnsupported(true);
      return;
    }

    const renderer = new THREE.WebGLRenderer({ antialias: false, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setClearAlpha(0);

    const scene = new THREE.Scene();
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
    camera.position.z = 1;

    const rng = createRng(seed);

    const total = columns * rows;
    const positions = new Float32Array(total * 3);
    const wave = new Float32Array(total * 2);

    /* ------------------------------------------------------------------
       The arc. Columns are placed by angle, then z is renormalised so the
       centre column sits at +arcDepth and the two edges at -arcDepth
       exactly. Without the renormalisation the usable z range depends on
       arcSpan, and the depth fade would get weaker every time the arc was
       flattened — the cue would silently stop working at shallow spans.
       ------------------------------------------------------------------ */
    const halfSpan = (arcSpan * Math.PI) / 360;
    const cosEdge = Math.cos(halfSpan);
    // Guard the degenerate case: a 0 degree span has no depth to normalise.
    const depthSpan = Math.max(1e-4, 1 - cosEdge);

    let cursor = 0;
    for (let c = 0; c < columns; c += 1) {
      const colT = columns === 1 ? 0.5 : c / (columns - 1);
      const angle = (colT - 0.5) * 2 * halfSpan;
      const x = Math.sin(angle);
      const z = ((Math.cos(angle) - cosEdge) / depthSpan) * 2 * arcDepth - arcDepth;

      for (let r = 0; r < rows; r += 1) {
        const rowT = rows === 1 ? 0.5 : r / (rows - 1);
        // Sub-cell jitter, seeded. A perfect lattice moirés against the pixel
        // grid and shows banding as the field yaws.
        const jx = (rng() - 0.5) * (1 / columns) * 0.9;
        const jy = (rng() - 0.5) * (1 / rows) * 0.9;

        positions[cursor * 3] = x + jx;
        positions[cursor * 3 + 1] = (rowT - 0.5 + jy) * fieldHeight;
        positions[cursor * 3 + 2] = z;

        // Phase is what makes it travel. Constant phase across the lattice
        // would give a field that breathes in unison.
        wave[cursor * 2] = colT * waveTurns + rowT * ROW_PHASE_LEAN;
        wave[cursor * 2 + 1] = rng() - 0.5;
        cursor += 1;
      }
    }

    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
    geometry.setAttribute('aWave', new THREE.BufferAttribute(wave, 2));

    const uniforms: Uniforms = {
      uElapsed: { value: 0 },
      uViewScale: { value: 1 },
      uPixelRatio: { value: renderer.getPixelRatio() },
      uDotScale: { value: dotScale },
      uOpacity: { value: opacity },
      uPulseCycle: { value: pulseCycle },
      uWaveDepth: { value: waveDepth },
      uYaw: { value: 0 },
      uColor: { value: new THREE.Color(color) },
      uCrestColor: { value: new THREE.Color(crestColor) },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: DEPTH_PULSE_WAVE_VERT,
      fragmentShader: DEPTH_PULSE_WAVE_FRAG,
      uniforms,
      transparent: true,
      // Every dot is projected at z = 0; the depth cue is alpha and size, not
      // the depth buffer. Leaving these on would let near dots reject far ones
      // that were rasterised first and punch holes through the lattice.
      depthTest: false,
      depthWrite: false,
    });

    const points = new THREE.Points(geometry, material);
    // Positions are unit-scale around the origin and the real placement happens
    // in the shader, so three's bounding sphere does not describe what is on
    // screen and culling against it would blank the field at some sizes.
    points.frustumCulled = false;
    scene.add(points);

    el.appendChild(renderer.domElement);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';

    const resize = (w: number, h: number) => {
      renderer.setSize(w, h, false);
      camera.left = -w / 2;
      camera.right = w / 2;
      camera.top = h / 2;
      camera.bottom = -h / 2;
      camera.updateProjectionMatrix();
      uniforms.uViewScale.value = Math.min(w, h) * viewScale;
      uniforms.uPixelRatio.value = renderer.getPixelRatio();
    };

    const draw = (elapsed: number) => {
      uniforms.uElapsed.value = elapsed;
      // Yaw oscillates rather than spins. A full rotation would carry columns
      // through the arc's own depth range and the travelling crest would stop
      // being readable as a wave.
      uniforms.uYaw.value = Math.sin(elapsed * yawSpeed * Math.PI * 2) * yawAmplitude;
      renderer.render(scene, camera);
    };

    resize(size.current.width, size.current.height);
    stage.current = { resize, draw };
    draw(STATIC_ELAPSED);

    return () => {
      stage.current = null;
      disposeObject(scene);
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
  }, [
    ready,
    columns,
    rows,
    arcSpan,
    arcDepth,
    fieldHeight,
    pulseCycle,
    waveTurns,
    waveDepth,
    yawAmplitude,
    yawSpeed,
    dotScale,
    viewScale,
    opacity,
    color,
    crestColor,
    seed,
  ]);

  useEffect(() => {
    stage.current?.resize(width, height);
    if (reduced) stage.current?.draw(STATIC_ELAPSED);
  }, [width, height, reduced]);

  useRaf((_dt, elapsed) => stage.current?.draw(elapsed), ready && !reduced && !unsupported);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nulls the stage ref so a queued frame cannot touch a dead renderer, disposes the geometry through `disposeObject(scene)`, disposes the material, calls `disposeRenderer` for `dispose` + `forceContextLoss` + a zeroed backing store, and removes the canvas. `useRaf` unsubscribes on unmount, so a StrictMode double-invoke leaves no orphaned context.

**Reduced motion.** No frame loop is opened. A single frame is drawn at `uElapsed = 1.9` — past the one-second amplitude ramp, and a third of the way through the default cycle, so the crest sits inside the lattice rather than off its edge. Both the depth falloff and the wave band are visible in that still; neither advances.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Giving every dot the same phase. The field then pulses in unison, which reads as a loading state rather than as something moving through the lattice — the per-column phase offset *is* the effect.
- Fading alpha with depth but leaving point size constant. The far edge of the arc becomes a grey copy of the near edge instead of receding, because size is the cue the eye actually uses for distance at these scales.
- Leaving `depthTest` on. Every dot is projected at z = 0, so whichever dot rasterises first wins the pixel and the lattice develops holes wherever it folds back on itself.
- Starting the pulse at full amplitude. The first frame samples the cosine at whatever phase `elapsed` happens to be, and the field flashes on mount — hence the one-second amplitude ramp.
- Placing columns by angle without renormalising z. The depth range then scales with `cos(arcSpan/2)`, so flattening the arc quietly kills the depth fade and the component looks broken at shallow spans while working at wide ones.
- A perfectly regular lattice. It moirés against the pixel grid and shows banding as the field yaws; the seeded sub-cell jitter costs nothing and removes it.
- Rebuilding the buffer on resize. Model space is size-independent — only `uViewScale` and `uPixelRatio` change, so a container reflow costs two uniform writes rather than a dropped GL context.

## Notes

- Dot count is `columns * rows`, 4840 at the defaults, in one draw call with one attribute beyond position.
- The wave is purely a function of `uElapsed` and a baked per-dot phase, so there is no simulation state and no drift — pausing and resuming lands exactly where the clock says it should.

## Definition of done

A curved lattice of dots is visibly dimmer and smaller toward its left and right edges than at its centre. A band of brighter, larger dots sweeps repeatedly across the field, roughly once every three seconds, rather than the whole field brightening at once. The lattice rocks gently side to side. Nothing flashes on mount. Resize the container and the field rescales without a flicker or a dropped context. With reduced motion it holds a single frame showing both the depth falloff and the crest.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Dither Trail Image Reveal

The image rests dimmed and near-monochrome; dragging across it restores it through a trail of 5px blocks, each block either lit or not according to an 8x8 Bayer threshold. Twenty-four pointer samples live about a second and ride in two flat uniform arrays, so the whole trail is one fullscreen quad with no geometry and no render targets. Samples are spawned on distance travelled by a damped follower rather than per event, and each carries the velocity it was born with, so the reveal smears the way the hand moved.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A dimmed image restored through a trail of Bayer-thresholded blocks that smear in the direction the pointer moved.

- Category: cursor
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. The trail is state, not geometry. Twenty-four samples sit in a ring buffer as `vec4(u, v, life, speed)` plus a parallel `vec2` of velocity, uploaded as two flat uniform arrays every frame. The fragment shader loops all twenty-four and takes `max()` of their contributions, so a full trail costs one quad and twenty-four `length()` calls per fragment — no instanced sprites, no ping-pong feedback buffer, nothing to resize.
2. A sample is released when the FOLLOWER has travelled `spawnDistance`, or after `spawnInterval` with no movement. Spawning per pointer event instead clumps on a slow drag — events fire on sub-pixel movement — and leaves gaps on a flick, because the ring is short and a fast sweep can consume all of it between two frames. The time floor is what keeps a stationary hover from decaying to nothing under the cursor.
3. The Bayer threshold is sampled at the CENTRE of the 5px block the fragment sits in, not at the fragment itself. Per-fragment sampling lets the disc edge cut through a block, which puts a soft antialiased boundary on an effect whose entire argument is that it has none. Per-block, a block is wholly lit or wholly absent and the reveal has a dither vocabulary.
4. The 8x8 matrix is built recursively — `bayer4(a) = bayer2(a * 0.5) * 0.25 + bayer2(a)`, and again for 8 — because GLSL ES 1.00 has no integer bitwise operators and the usual derivation is bit-twiddled. Three multiplies and a `fract` produce the same 64-value ordering with no lookup texture and no GLSL3 upgrade.
5. Each sample contributes its stored velocity to a flow vector, weighted by how much it contributed to the mask, and the sum is clamped. The image is then sampled at `uv - flow`, with the flow SNAPPED to the same 5px grid as the dither: a smooth sub-pixel offset is a directional blur laid on top of the picture, while a snapped one moves whole blocks and belongs to the same rendering as the dots.
6. Colour is quantised twice at two different frequencies — the reveal mask against a per-block threshold, the tone against a per-pixel one — so the shape of the trail and the banding of the image do not moire against each other.
7. `object-fit: cover` is reproduced in uv space from the intrinsic aspect of the decoded texture, so the shader crops exactly the way the equivalent CSS would and a resize is two uniform writes rather than a re-layout.
8. The pointer state updates every frame while the DRAW is throttled to 30fps. The trail geometry is smooth because the samples are, and 30fps is invisible through 5px blocks; halving the draw rate halves the fill, which is the only real cost here.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `TRAIL_POINTS = 24`
  Ring length, and a compile-time `#define` because GLSL ES 1.00 needs a constant loop bound. At the default spacing this is roughly a second of trail. Past ~48 the shader is doing more work than the image is worth, and the far end of the trail is below the first dither level anyway.
- `MAX_BUFFER_WIDTH = 1100`
  Absolute cap on drawing-buffer width in device pixels, applied on top of the dpr cap. The output is 5px blocks quantised to four levels, so a wider buffer resolves nothing: a 2560px hero at dpr 2 would shade 26 million fragments per draw for a picture with no detail above the block size.
- `fps = 30`
  Draw ceiling. This is an overlay, not the subject, and the block size hides the difference between 30 and 120. The accumulator subtracts the budget rather than zeroing, so the long-run rate is exact instead of quietly losing the remainder each frame.
- `smoothing = 0.0002`
  Fraction of the pointer gap still remaining after one second — an ~80ms half-life. Tighter than a glow needs, because the trail has a visible head: lag past ~150ms and the reveal is drawing where the pointer was, which reads as dropped frames.
- `spawnDistance / spawnInterval = 0.012 / 0.042`
  Roughly 1.2% of the container per sample, or one every 42ms if the pointer is still. Below ~0.006 a slow drag exhausts the ring in a few centimetres; above ~0.03 a fast sweep is visibly a string of beads.
- `trail radius = 0.055 -> 0.115`
  A sample GROWS as it ages, so the trail widens and softens behind the head instead of fading as a constant-width stripe. Equal radii read as a paint stroke; the taper is what makes it a wake.
- `FLOW_MAX / FLOW_CLAMP = 0.04 / 0.055`
  Per-sample and total displacement ceilings in uv units. Uncapped, a flick tears the image into unrecognisable stripes; the total clamp also stops overlapping samples from summing into a displacement several times either individual one.
- `levels = 4`
  Quantisation steps per channel inside the reveal. Two is a duotone stencil that loses the photograph; past ~8 the dither is too fine to read as one and the effect looks like a slightly noisy image.
- `Bayer epsilon = 0.001`
  The matrix contains a zero cell, so `step(threshold, soft)` lights that cell in every block on the canvas — a permanent sparse grid of stray pixels everywhere the trail has never been. Biasing the threshold is what keeps the untouched area untouched.

## API

```ts
function DitherTrailImageReveal(props: { src: string; alt?: string; levels?: number; blockSize?: number; trailLife?: number; spawnDistance?: number; spawnInterval?: number; flowGain?: number; smoothing?: number; restBrightness?: number; restSaturation?: number; fps?: number; maxDpr?: number; className?: string }): JSX.Element
```

- `src: string`
  Required. Image URL — http(s), blob: or data:. Never a bundled asset.
- `alt: string` — default `''`
  Accessible name for the panel. Empty marks it decorative.
- `levels: number` — default `4`
  Quantisation steps per channel inside the reveal.
- `blockSize: number` — default `5`
  Dither block size in CSS pixels.
- `trailLife: number` — default `1.05`
  Life of one trail sample in seconds.
- `spawnDistance: number` — default `0.012`
  Follower travel in uv units that releases the next sample.
- `spawnInterval: number` — default `0.042`
  Seconds after which a sample is released even with no movement.
- `flowGain: number` — default `0.03`
  uv offset stored per uv/second of pointer velocity.
- `smoothing: number` — default `0.0002`
  Fraction of the pointer gap still remaining after one second.
- `restBrightness: number` — default `0.5`
  Brightness of the untouched image, 0 to 1.
- `restSaturation: number` — default `0.16`
  Saturation of the untouched image, 0 to 1.
- `fps: number` — default `30`
  Draw rate ceiling. Pointer state still updates every frame.
- `maxDpr: number` — default `1.5`
  Device pixel ratio cap, before the 1100px absolute buffer cap.
- `className: string`
  Merged onto the root container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** Samples in the ring. Must match TRAIL_POINTS in the fragment shader. */
const TRAIL_POINTS = 24;
/**
 * Hard cap on drawing-buffer width in device pixels. An overlay of 5px blocks
 * carries no detail a wider buffer could resolve, and fill is the whole cost:
 * a 2560px hero at dpr 2 would shade 26 million fragments per draw for a
 * picture that is quantised to four levels.
 */
const MAX_BUFFER_WIDTH = 1100;
/** uv units per second at which the speed term saturates. */
const SPEED_FULL_SCALE = 1.6;
/** Fraction of the velocity gap left after a second. Fast: speed must track. */
const VELOCITY_SMOOTHING = 0.001;
/** Ceiling on a single sample's stored flow, in uv units. */
const FLOW_MAX = 0.04;
/** Ceiling on the SUM of all samples' flow, applied in the shader. */
const FLOW_CLAMP = 0.055;

/** The reduced-motion still: a frozen swipe with a plausible velocity. */
const STILL_POINTS = 9;
const STILL_FLOW: readonly [number, number] = [0.02, 0.008];

interface RevealUniforms {
  /** three types `uniforms` as an open record; the index signature matches it. */
  [name: string]: THREE.IUniform;
  uResolution: THREE.IUniform<THREE.Vector2>;
  uImage: THREE.IUniform<THREE.Texture | null>;
  uHasImage: THREE.IUniform<number>;
  uUvScale: THREE.IUniform<THREE.Vector2>;
  uUvOffset: THREE.IUniform<THREE.Vector2>;
  /** Flat vec4 array: three's uniform setters take a typed array unchanged. */
  uTrail: THREE.IUniform<Float32Array>;
  uFlow: THREE.IUniform<Float32Array>;
  uBlock: THREE.IUniform<number>;
  uLevels: THREE.IUniform<number>;
  uFlowClamp: THREE.IUniform<number>;
  uRestBrightness: THREE.IUniform<number>;
  uRestSaturation: THREE.IUniform<number>;
}

interface Stage {
  renderer: THREE.WebGLRenderer;
  scene: THREE.Scene;
  camera: THREE.OrthographicCamera;
  geometry: THREE.PlaneGeometry;
  material: THREE.ShaderMaterial;
  uniforms: RevealUniforms;
  placeholder: THREE.DataTexture;
  render: () => void;
}

interface TrailSample {
  x: number;
  y: number;
  /** Elapsed seconds at spawn. Negative means the slot has never been used. */
  born: number;
  flowX: number;
  flowY: number;
  speed: number;
}

/**
 * A 1x1 opaque texture, bound before anything has loaded. Sampling an unbound
 * sampler2D is undefined behaviour: some drivers return black, some warn on
 * every draw, and one of them will be the reviewer's.
 */
function createPlaceholder(): THREE.DataTexture {
  const texture = new THREE.DataTexture(new Uint8Array([16, 17, 21, 255]), 1, 1);
  texture.needsUpdate = true;
  return texture;
}

export function DitherTrailImageReveal({
  src,
  alt = '',
  levels = 4,
  blockSize = 5,
  trailLife = 1.05,
  spawnDistance = 0.012,
  spawnInterval = 0.042,
  flowGain = 0.03,
  smoothing = 0.0002,
  restBrightness = 0.5,
  restSaturation = 0.16,
  fps = 30,
  maxDpr = 1.5,
  className,
}: DitherTrailImageRevealProps) {
  const host = useRef<HTMLDivElement>(null);
  const mount = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);

  const { width, height } = useResizeObserver(host);
  const { inView } = useInView(host, { rootMargin: '10%' });
  const visible = useVisibility();
  const reduced = useReducedMotion();
  /* A trail needs a pointer that exists while no button is held. On touch
     `pointermove` only fires mid-drag, so the reveal would appear under the
     finger that is covering it and then be stranded on lift. */
  const finePointer = useMediaQuery('(hover: hover) and (pointer: fine)');

  const [supported, setSupported] = useState(true);
  useEffect(() => setSupported(hasWebGL()), []);
  const [failed, setFailed] = useState(false);

  /** The decoded image, kept across renderer rebuilds so a resize never refetches. */
  const image = useRef<THREE.Texture | null>(null);
  /** Intrinsic aspect of that image; 0 until one has decoded. */
  const imageAspect = useRef(0);

  const target = useRef<{ x: number; y: number } | null>(null);
  const inside = useRef(false);
  const follow = useRef({ x: 0.5, y: 0.5 });
  const velocity = useRef({ x: 0, y: 0 });
  const lastSpawn = useRef({ x: 0.5, y: 0.5, at: -1 });
  const writeIndex = useRef(0);
  const budget = useRef(0);

  const trail = useRef<TrailSample[]>(
    Array.from({ length: TRAIL_POINTS }, () => ({
      x: 0,
      y: 0,
      born: -1,
      flowX: 0,
      flowY: 0,
      speed: 0,
    })),
  );

  const live = useRef({
    levels,
    blockSize,
    trailLife,
    spawnDistance,
    spawnInterval,
    flowGain,
    smoothing,
    restBrightness,
    restSaturation,
    fps,
  });
  live.current = {
    levels,
    blockSize,
    trailLife,
    spawnDistance,
    spawnInterval,
    flowGain,
    smoothing,
    restBrightness,
    restSaturation,
    fps,
  };

  const ready = supported && width > 1 && height > 1;

  /** object-fit: cover, replicated in uv space so the shader matches the CSS. */
  const applyCover = (w: number, h: number) => {
    const s = stage.current;
    if (!s || w < 1 || h < 1) return;
    const ia = imageAspect.current;
    if (ia <= 0) {
      s.uniforms.uUvScale.value.set(1, 1);
      s.uniforms.uUvOffset.value.set(0, 0);
      return;
    }
    const canvasAspect = w / h;
    if (ia > canvasAspect) {
      // Image is wider than the box: crop the sides.
      const scale = canvasAspect / ia;
      s.uniforms.uUvScale.value.set(scale, 1);
      s.uniforms.uUvOffset.value.set((1 - scale) * 0.5, 0);
    } else {
      const scale = ia / canvasAspect;
      s.uniforms.uUvScale.value.set(1, scale);
      s.uniforms.uUvOffset.value.set(0, (1 - scale) * 0.5);
    }
  };

  useEffect(() => {
    const slot = mount.current;
    if (!slot || !ready) return;

    /* The canvas is created here rather than owned by React. `reactStrictMode`
       double-invokes this effect; the first cleanup calls `forceContextLoss()`,
       and `getContext` on that same element afterwards returns the DEAD context
       instead of a fresh one — blank in development, fine in production, which
       is the worst way for a bug to behave. */
    const renderer = new THREE.WebGLRenderer({
      antialias: false,
      alpha: false,
      powerPreference: 'low-power',
    });
    // Two caps, and the lower wins: a ratio cap for sane machines and an
    // absolute width cap so a 4K hero cannot ask for a 7680px buffer.
    const ratio = Math.min(pixelRatio(maxDpr), MAX_BUFFER_WIDTH / Math.max(width, 1));
    renderer.setPixelRatio(Math.max(ratio, 0.5));
    renderer.setSize(width, height, false);
    const canvas = renderer.domElement;
    canvas.style.display = 'block';
    canvas.style.width = '100%';
    canvas.style.height = '100%';
    slot.appendChild(canvas);

    const placeholder = createPlaceholder();

    const uniforms: RevealUniforms = {
      uResolution: { value: new THREE.Vector2(width, height) },
      uImage: { value: image.current ?? placeholder },
      uHasImage: { value: image.current ? 1 : 0 },
      uUvScale: { value: new THREE.Vector2(1, 1) },
      uUvOffset: { value: new THREE.Vector2(0, 0) },
      uTrail: { value: new Float32Array(TRAIL_POINTS * 4) },
      uFlow: { value: new Float32Array(TRAIL_POINTS * 2) },
      uBlock: { value: blockSize },
      uLevels: { value: levels },
      uFlowClamp: { value: FLOW_CLAMP },
      uRestBrightness: { value: restBrightness },
      uRestSaturation: { value: restSaturation },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: ditherTrailImageRevealVertexShader,
      fragmentShader: ditherTrailImageRevealFragmentShader,
      uniforms,
    });

    const geometry = new THREE.PlaneGeometry(2, 2);
    const scene = new THREE.Scene();
    scene.add(new THREE.Mesh(geometry, material));
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
    const render = () => renderer.render(scene, camera);

    /* Listeners on the CANVAS, not the window: a document-level handler
       outlives the renderer it drives, and the rect it measures is not the rect
       being drawn into. Passive, because nothing calls preventDefault here and
       a non-passive move handler stalls the compositor on every event. */
    const onMove = (event: PointerEvent) => {
      const rect = canvas.getBoundingClientRect();
      if (rect.width === 0 || rect.height === 0) return;
      target.current = {
        x: (event.clientX - rect.left) / rect.width,
        // Flipped: uv y is up, client y is down.
        y: 1 - (event.clientY - rect.top) / rect.height,
      };
      if (!inside.current) {
        // Entering: teleport the follower rather than damping to it, or the
        // trail draws a stripe from wherever the pointer was last seen.
        follow.current.x = target.current.x;
        follow.current.y = target.current.y;
        lastSpawn.current.x = target.current.x;
        lastSpawn.current.y = target.current.y;
        velocity.current.x = 0;
        velocity.current.y = 0;
      }
      inside.current = true;
    };
    const onLeave = () => {
      inside.current = false;
      // Samples already in the ring keep ageing out on their own, so the trail
      // finishes its life instead of vanishing the instant the pointer leaves.
    };

    canvas.addEventListener('pointermove', onMove, { passive: true });
    canvas.addEventListener('pointerleave', onLeave, { passive: true });
    canvas.addEventListener('pointercancel', onLeave, { passive: true });

    stage.current = {
      renderer,
      scene,
      camera,
      geometry,
      material,
      uniforms,
      placeholder,
      render,
    };
    applyCover(width, height);
    render();

    return () => {
      stage.current = null;
      canvas.removeEventListener('pointermove', onMove);
      canvas.removeEventListener('pointerleave', onLeave);
      canvas.removeEventListener('pointercancel', onLeave);
      // `dispose()` frees GPU objects but leaves the context alive until GC
      // decides otherwise. `disposeRenderer` is the one that force-loses it,
      // and the per-process budget is about sixteen contexts.
      disposeRenderer(renderer);
      geometry.dispose();
      material.dispose();
      placeholder.dispose();
      canvas.remove();
    };
    // Everything else is pushed through `live` or the uniforms from the loop.
    // Rebuilding on a prop change would churn WebGL contexts.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, maxDpr]);

  /* Loading is its own effect and its own lifetime. It never throws: a 404
     leaves `uHasImage` at 0 and the shader keeps drawing its stand-in. */
  useEffect(() => {
    if (!ready || !src) return;
    let cancelled = false;
    setFailed(false);

    const loader = new THREE.TextureLoader();
    loader.load(
      src,
      (texture) => {
        if (cancelled) {
          // The component unmounted, or `src` changed, mid-decode. Without this
          // the texture is uploaded to a dead context and then leaked.
          texture.dispose();
          return;
        }
        texture.colorSpace = THREE.SRGBColorSpace;
        // No mipmaps: the quad is screen-filling, the image is never minified
        // past 1:1, and mipmapping a non-power-of-two texture silently fails.
        texture.generateMipmaps = false;
        texture.minFilter = THREE.LinearFilter;
        texture.magFilter = THREE.LinearFilter;
        texture.wrapS = THREE.ClampToEdgeWrapping;
        texture.wrapT = THREE.ClampToEdgeWrapping;

        image.current?.dispose();
        image.current = texture;

        const source = texture.image as { width?: number; height?: number } | null;
        const w = source?.width ?? 0;
        const h = source?.height ?? 0;
        imageAspect.current = w > 0 && h > 0 ? w / h : 0;

        const s = stage.current;
        if (!s) return;
        s.uniforms.uImage.value = texture;
        s.uniforms.uHasImage.value = 1;
        applyCover(width, height);
        s.render();
      },
      undefined,
      () => {
        if (cancelled) return;
        // A missing image is a content problem, not a crash. The stand-in field
        // keeps the panel legible and the trail keeps working on top of it.
        setFailed(true);
        imageAspect.current = 0;
        const s = stage.current;
        if (!s) return;
        s.uniforms.uHasImage.value = 0;
        s.render();
      },
    );

    return () => {
      cancelled = true;
    };
    // `width`/`height` are read for the cover fit but must not retrigger a
    // fetch; the resize effect re-applies the fit on its own.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [src, ready]);

  // The decoded texture outlives the renderer, so it is released on unmount
  // rather than in the loader effect, which reruns whenever `src` changes.
  useEffect(() => {
    return () => {
      image.current?.dispose();
      image.current = null;
    };
  }, []);

  useEffect(() => {
    const s = stage.current;
    if (!s || width < 1 || height < 1) return;
    const ratio = Math.min(pixelRatio(maxDpr), MAX_BUFFER_WIDTH / width);
    s.renderer.setPixelRatio(Math.max(ratio, 0.5));
    s.renderer.setSize(width, height, false);
    s.uniforms.uResolution.value.set(width, height);
    applyCover(width, height);
    // Redraw once, or a resize while the loop is paused leaves the previous
    // framebuffer stretched across the new size.
    s.render();
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [width, height, maxDpr]);

  const writeTrailUniforms = (elapsed: number, life: number) => {
    const s = stage.current;
    if (!s) return;
    const points = s.uniforms.uTrail.value;
    const flows = s.uniforms.uFlow.value;
    let i = 0;
    for (const sample of trail.current) {
      const age = sample.born < 0 ? Infinity : elapsed - sample.born;
      const remaining = clamp(1 - age / life, 0, 1);
      points[i * 4] = sample.x;
      points[i * 4 + 1] = sample.y;
      points[i * 4 + 2] = remaining;
      points[i * 4 + 3] = sample.speed;
      flows[i * 2] = sample.flowX;
      flows[i * 2 + 1] = sample.flowY;
      i += 1;
    }
  };

  useRaf(
    (dt, elapsed) => {
      const s = stage.current;
      if (!s) return;
      const cfg = live.current;

      const previousX = follow.current.x;
      const previousY = follow.current.y;

      const aim = target.current;
      if (aim) {
        follow.current.x = damp(follow.current.x, aim.x, cfg.smoothing, dt);
        follow.current.y = damp(follow.current.y, aim.y, cfg.smoothing, dt);
      }

      // Velocity of the FOLLOWER, in uv units per second. Dividing by dt is
      // what makes it a velocity rather than a per-frame delta that measures
      // twice as large at 60Hz as at 120Hz for the same hand movement.
      const step = Math.max(dt, 0.0001);
      velocity.current.x = damp(
        velocity.current.x,
        (follow.current.x - previousX) / step,
        VELOCITY_SMOOTHING,
        dt,
      );
      velocity.current.y = damp(
        velocity.current.y,
        (follow.current.y - previousY) / step,
        VELOCITY_SMOOTHING,
        dt,
      );

      /* Spawn on DISTANCE travelled, or on a time floor. Distance alone gives
         an evenly spaced trail but lets the reveal decay to nothing under a
         pointer that has stopped; the time floor keeps a stationary hover
         alive. Spawning per event instead would clump on a slow drag and smear
         on a flick, because events fire on sub-pixel movement. */
      if (inside.current && aim) {
        const moved = Math.hypot(
          follow.current.x - lastSpawn.current.x,
          follow.current.y - lastSpawn.current.y,
        );
        const waited = elapsed - lastSpawn.current.at;
        if (moved >= cfg.spawnDistance || waited >= cfg.spawnInterval) {
          const slot = trail.current[writeIndex.current % TRAIL_POINTS];
          if (slot) {
            writeIndex.current = (writeIndex.current + 1) % TRAIL_POINTS;
            slot.x = follow.current.x;
            slot.y = follow.current.y;
            slot.born = elapsed;
            slot.flowX = clamp(velocity.current.x * cfg.flowGain, -FLOW_MAX, FLOW_MAX);
            slot.flowY = clamp(velocity.current.y * cfg.flowGain, -FLOW_MAX, FLOW_MAX);
            slot.speed = clamp(
              Math.hypot(velocity.current.x, velocity.current.y) / SPEED_FULL_SCALE,
              0,
              1,
            );
          }
          lastSpawn.current.x = follow.current.x;
          lastSpawn.current.y = follow.current.y;
          lastSpawn.current.at = elapsed;
        }
      }

      const life = Math.max(cfg.trailLife, 0.05);
      writeTrailUniforms(elapsed, life);

      const u = s.uniforms;
      u.uBlock.value = Math.max(cfg.blockSize, 1);
      u.uLevels.value = Math.max(cfg.levels, 2);
      u.uRestBrightness.value = cfg.restBrightness;
      u.uRestSaturation.value = cfg.restSaturation;

      /* Draw-rate throttle. The state above updates every frame — a trail
         sampled at 30Hz has visible corners — but the DRAW is the expensive
         half and 30fps is indistinguishable through 5px blocks. Subtracting
         the budget rather than zeroing the accumulator keeps the long-run rate
         exact instead of quietly losing the remainder every frame. */
      const frameBudget = 1 / clamp(cfg.fps, 10, 120);
      budget.current += dt;
      if (budget.current < frameBudget) return;
      budget.current = Math.min(budget.current - frameBudget, frameBudget);

      s.render();
    },
    ready && inView && visible && !reduced && finePointer,
  );

  /* Reduced motion, and coarse pointers, get a composed still: a short frozen
     swipe baked into the ring so the panel shows what the effect produces. The
     listeners stay attached and their target is never consumed. */
  useEffect(() => {
    const s = stage.current;
    if (!s || !ready) return;
    if (!reduced && finePointer) return;

    const [flowX = 0.02, flowY = 0.008] = STILL_FLOW;
    let i = 0;
    for (const sample of trail.current) {
      const t = i / (STILL_POINTS - 1);
      const inSwipe = i < STILL_POINTS;
      sample.x = 0.3 + t * 0.42;
      sample.y = 0.4 + Math.sin(t * 2.2) * 0.12;
      sample.flowX = flowX;
      sample.flowY = flowY;
      sample.speed = inSwipe ? 0.45 : 0;
      // `born` is unused by the still: lives are written straight below.
      sample.born = -1;
      i += 1;
    }

    const points = s.uniforms.uTrail.value;
    const flows = s.uniforms.uFlow.value;
    let j = 0;
    for (const sample of trail.current) {
      const remaining = j < STILL_POINTS ? 1 - j / STILL_POINTS : 0;
      points[j * 4] = sample.x;
      points[j * 4 + 1] = sample.y;
      points[j * 4 + 2] = remaining;
      points[j * 4 + 3] = sample.speed;
      flows[j * 2] = sample.flowX;
      flows[j * 2 + 1] = sample.flowY;
      j += 1;
    }
    s.render();
  }, [reduced, finePointer, ready, width, height]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the three pointer listeners from the canvas, nulls the stage ref so an in-flight frame cannot touch a dead renderer, then `disposeRenderer(renderer)` — which force-loses the context, not just `dispose()`, since Chromium keeps roughly sixteen per process and drops the oldest — followed by the geometry, the material and the 1x1 placeholder texture, and finally removes the canvas from the DOM. The decoded image texture is disposed in a separate unmount effect, and an in-flight decode is cancelled by a flag so its callback disposes the result instead of binding it.

**Reduced motion.** The loop never starts. A short frozen swipe — nine samples with descending life and a plausible velocity — is baked into the ring and one frame is drawn, so the panel shows what the effect produces rather than a flat dimmed image. Coarse pointers get the same still, for the same reason. The listeners stay attached but their target is never consumed, so moving the pointer changes nothing.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Pushing pointer events straight into the trail. Event positions are not a path: they arrive at whatever rate the device chooses, cluster on slow movement and stop dead when the hand pauses. The handler records a target only; the loop damps a follower toward it and samples the follower.
- Damping with a per-frame constant (`x += (t - x) * 0.1`) instead of `damp(..., dt)`. The trail is visibly tighter at 120Hz than at 60Hz, so the feel is tuned to whichever machine it was authored on.
- Measuring velocity as a per-frame delta rather than dividing by `dt`. The same hand movement then reads as half the speed at 120Hz, and the smear strength — and with it the whole character of the effect — depends on the display.
- Sampling the Bayer threshold per fragment instead of per block. The reveal edge becomes smooth, which is precisely the thing a dither is supposed to replace, and the block grid stops being legible.
- Comparing against the Bayer matrix without an epsilon. Its zero cell passes `step()` everywhere, so one pixel in every 5x5 block is lit across the entire canvas, including areas the pointer has never visited.
- Dividing the 8x8 matrix by 63 instead of 64. A threshold of exactly 1.0 means the brightest level can never be selected, and the whitest part of the image clips one step down.
- Assuming `src` is decoded. A `TextureLoader` result arrives asynchronously and may never arrive at all. Leaving the sampler unbound until then is undefined behaviour — black on some drivers, a console warning per draw on others. A 1x1 placeholder is bound from the first frame and a `uHasImage` float selects a procedural stand-in.
- Letting a 404 throw or blank the panel. A component that cannot survive a missing image cannot be dropped into a CMS-backed page. The error callback leaves `uHasImage` at 0 and the trail keeps working over the stand-in field.
- Not cancelling an in-flight decode. If `src` changes or the component unmounts mid-load, the callback fires against a dead renderer and the texture is uploaded and then leaked. A `cancelled` flag disposes it instead.
- Rendering at full device pixel ratio. Fill is the entire cost of a fullscreen quad and it scales with the square of the ratio, for an image whose smallest feature is deliberately five pixels wide.
- Owning the canvas in React while calling `forceContextLoss()` on cleanup. Under `reactStrictMode` the effect runs twice and the second `getContext` on that same element returns the DEAD context: blank in development, fine in production, which is the worst way for a bug to behave.
- Shipping the demo image as a committed asset. The image is a prop; the demo paints its own canvas and passes a data URL, so the registry carries no binary.

## Notes

- `src` is required and is never bundled. Anything a browser can fetch works: an http(s) URL, a `blob:` from an upload, or a `data:` URL.
- Coarse pointers get the composed still rather than the live effect. `pointermove` only fires mid-drag on touch, so the reveal would appear under the finger covering it and then be stranded on lift.
- Without WebGL the component renders the image plainly with `object-fit: cover`. The picture is the content; the dither is decoration on top of it.
- The decoded texture is held across renderer rebuilds, so a resize or a dpr change re-uploads it rather than refetching. It is disposed in its own unmount effect, separate from the loader effect that reruns on every `src` change.
- Leaving the panel does not clear the trail. Samples keep ageing out on their own, so the reveal finishes its life instead of vanishing on `pointerleave`.
- The root carries `role="img"` and the `alt` text; an empty `alt` marks the whole panel decorative with `aria-hidden` instead.

## Definition of done

At rest the image is visible but dimmed and nearly grey. Drag across it and full colour appears in a trail of hard-edged square blocks that widens and fades behind the pointer, with the blocks smeared along the direction of travel — more on a flick, less on a slow drag. The untouched area contains no stray lit pixels anywhere. Stop moving and the reveal stays alive under the cursor instead of dying. Leave the panel and the trail finishes ageing out where it stands. The follow lag is identical on a 60Hz and a 120Hz display. Point at a `src` that 404s: the panel shows a banded stand-in field, the trail still works, and the console carries no exception. Resize wide and the image stays cover-cropped with no stretching, and the trail discs stay round.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Domain-Warped FBM Fog

A full-screen fragment shader on a single triangle. Two octaves of value-noise fbm are sampled twice to build a 2D offset, and that offset is fed back into a third sample — the result flows instead of cross-fading. The pointer enters the warp three times with different weights and a sign flip, so the fog leans toward the cursor without following it.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Slow, low-contrast fog that flows rather than fades, with a faint light that trails the cursor.

- Category: webgl
- Runtime cost: webgl
- Dependencies: none beyond React

## How it works

1. `fbm(p)` sums two octaves of 3D value noise with amplitudes 0.6 and 0.3 and lacunarity 1.93. The third dimension is time, so the field evolves continuously instead of scrolling.
2. The domain warp is `q = vec2(fbm(sp + m*0.20, t), fbm(sp + vec2(2.3,1.1) - m*0.20, t))`, then `n = fbm(sp + q*0.4 + m*0.12, t*0.8) * 0.5 + 0.5`. The `vec2(2.3, 1.1)` offset decorrelates the second channel from the first; without it both return the same number and the warp collapses into a diagonal translation.
3. Both the sample point and the pointer are multiplied by `aspect` on x before use, so the noise stays isotropic and the cursor glow stays circular on a wide screen.
4. `shade = smoothstep(0.25, 0.85, n)` crushes the noise into a soft two-tone field, and the final colour is `base + tint * (gain * shade + lift)` where `lift = (pointerY - 0.5) * 0.03` tilts the whole frame slightly as the cursor moves up and down.
5. The cursor light is `smoothstep(0.85, 0.0, d)` — arguments deliberately reversed to produce a falling ramp, 1 at the cursor and 0 at distance 0.85, without the extra `1.0 -`.
6. A vignette `smoothstep(1.25, 0.5, distance(uv, 0.5))` multiplies the result rather than subtracting from it, so the cursor glow dims with the corners instead of punching through them.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `scale = 0.7`
  Multiplier on the sample coordinate. Below 1.0 the noise features are LARGER than the screen, so you get a handful of slow masses. At 3.0 the same shader is television static.
- `warp = 0.4`
  How far `q` displaces the final sample. Under ~0.15 the warp is invisible and you are looking at plain fbm; over ~0.9 the field folds back on itself and produces hard creases that read as compression artefacts.
- `octaves = 2`
  Textbook fbm uses 4-6. Two is enough because the output goes straight through `smoothstep(0.25, 0.85, n)`, which discards the fine detail anyway. fbm is essentially the whole cost of this shader, so halving the octaves halves the frame time.
- `lacunarity = 1.93`
  Frequency step between octaves. Exactly 2.0 makes the two lattices coincide on every other cell boundary and stamps a faint axis-aligned cross into the field; an off-integer step decorrelates them.
- `amplitude schedule = 0.6 then 0.3`
  Starting below 1.0 keeps the two-octave sum inside roughly -0.9..0.9, so `n * 0.5 + 0.5` lands in 0..1 without clipping and the smoothstep window sits where the data actually is.
- `time scale = 0.03`
  The field advances 0.0005 units per frame at 60 Hz. It has to read as weather, not animation — at 0.3 it becomes a lava lamp and starts competing with the content on top of it.
- `gain = 0.22`
  Peak brightness above the base. The reference site sits at 0.08, which keeps the entire image inside the bottom 17% of the value range so white type sits on it perfectly. 0.22 is the standalone default; drop it toward 0.08 the moment you put text on top.
- `pointer smoothing = 0.02`
  Fraction of the gap left after one second. The pointer displaces a noise domain, so raw values make the whole field jump between pointer events rather than drift.

## API

```ts
function DomainWarpedFbm(props: { scale?: number; warp?: number; gain?: number; speed?: number; base?: readonly [number, number, number]; tint?: readonly [number, number, number]; maxDpr?: number; className?: string }): JSX.Element
```

- `scale: number` — default `0.7`
  Noise frequency. Below 1.0 the features are larger than the screen.
- `warp: number` — default `0.4`
  How far the first two fbm samples displace the third.
- `gain: number` — default `0.22`
  Peak brightness added above the base colour.
- `speed: number` — default `1`
  Multiplier on the drift, which is already very slow.
- `base: readonly [number, number, number]` — default `[0.03, 0.032, 0.042]`
  Base colour, linear 0..1 RGB, straight into the shader.
- `tint: readonly [number, number, number]` — default `[0.86, 0.9, 1]`
  Colour of the lit fog and the cursor glow.
- `maxDpr: number` — default `2`
  Upper bound on device pixel ratio.
- `className: string`
  Merged onto the host element.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const TRIANGLE = new Float32Array([-1, -1, 3, -1, -1, 3]);
const SCALE = 0.7;
const WARP = 0.4;
const GAIN = 0.22;
const BASE: readonly [number, number, number] = [0.03, 0.032, 0.042];
const TINT: readonly [number, number, number] = [0.86, 0.9, 1];

interface Gpu {
  gl: WebGL2RenderingContext;
  program: WebGLProgram;
  vao: WebGLVertexArrayObject;
  buffer: WebGLBuffer;
  locations: Map<string, WebGLUniformLocation | null>;
}

/* A local 60-line bootstrap rather than three.js or ogl. This component draws
   three vertices; a framework would be 100x its own weight in dependency. */
function build(gl: WebGL2RenderingContext, vertSrc: string, fragSrc: string): Gpu | null {
  const compile = (type: number, src: string): WebGLShader | null => {
    const shader = gl.createShader(type);
    if (!shader) return null;
    gl.shaderSource(shader, src);
    gl.compileShader(shader);
    if (gl.getShaderParameter(shader, gl.COMPILE_STATUS)) return shader;
    console.error('[domain-warped-fbm]', gl.getShaderInfoLog(shader));
    gl.deleteShader(shader);
    return null;
  };

  const vert = compile(gl.VERTEX_SHADER, vertSrc);
  const frag = compile(gl.FRAGMENT_SHADER, fragSrc);
  const program = gl.createProgram();
  const vao = gl.createVertexArray();
  const buffer = gl.createBuffer();
  if (!vert || !frag || !program || !vao || !buffer) return null;

  gl.attachShader(program, vert);
  gl.attachShader(program, frag);
  gl.linkProgram(program);
  gl.deleteShader(vert);
  gl.deleteShader(frag);
  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
    console.error('[domain-warped-fbm]', gl.getProgramInfoLog(program));
    gl.deleteProgram(program);
    return null;
  }

  gl.bindVertexArray(vao);
  gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
  gl.bufferData(gl.ARRAY_BUFFER, TRIANGLE, gl.STATIC_DRAW);
  const attrib = gl.getAttribLocation(program, 'a_pos');
  if (attrib >= 0) {
    gl.enableVertexAttribArray(attrib);
    gl.vertexAttribPointer(attrib, 2, gl.FLOAT, false, 0, 0);
  }
  gl.bindVertexArray(null);

  return { gl, program, vao, buffer, locations: new Map() };
}

function loc(gpu: Gpu, name: string): WebGLUniformLocation | null {
  const cached = gpu.locations.get(name);
  if (cached !== undefined) return cached;
  const found = gpu.gl.getUniformLocation(gpu.program, name);
  gpu.locations.set(name, found);
  return found;
}

export function DomainWarpedFbm({
  scale = SCALE,
  warp = WARP,
  gain = GAIN,
  speed = 1,
  base = BASE,
  tint = TINT,
  maxDpr = 2,
  className,
}: DomainWarpedFbmProps) {
  const host = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const gpuRef = useRef<Gpu | null>(null);

  const { width, height } = useResizeObserver(host);
  const reduced = useReducedMotion();
  const visible = useVisibility();
  // Heavy smoothing: the pointer drives a warp offset, and an unsmoothed
  // pointer makes the whole field snap between frames rather than drift.
  const pointer = useSmoothPointer({ target: host, smoothing: 0.02 });
  const [supported, setSupported] = useState(true);

  const paramsRef = useRef({ scale, warp, gain, speed, base, tint });
  paramsRef.current = { scale, warp, gain, speed, base, tint };

  const drawRef = useRef<(elapsed: number) => void>(() => {});
  drawRef.current = (elapsed: number) => {
    const gpu = gpuRef.current;
    if (!gpu) return;
    const { gl } = gpu;
    const params = paramsRef.current;
    const p = pointer.current;

    gl.useProgram(gpu.program);
    gl.uniform2f(
      loc(gpu, 'u_resolution'),
      gl.drawingBufferWidth,
      gl.drawingBufferHeight,
    );
    gl.uniform1f(loc(gpu, 'u_time'), elapsed * params.speed);
    gl.uniform2f(loc(gpu, 'u_pointer'), p.nx, 1 - p.ny);
    gl.uniform1f(loc(gpu, 'u_scale'), params.scale);
    gl.uniform1f(loc(gpu, 'u_warp'), params.warp);
    gl.uniform1f(loc(gpu, 'u_gain'), params.gain);
    gl.uniform3f(loc(gpu, 'u_base'), params.base[0], params.base[1], params.base[2]);
    gl.uniform3f(loc(gpu, 'u_tint'), params.tint[0], params.tint[1], params.tint[2]);

    gl.bindVertexArray(gpu.vao);
    gl.drawArrays(gl.TRIANGLES, 0, 3);
    gl.bindVertexArray(null);
  };

  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;
    if (!hasWebGL()) {
      setSupported(false);
      return;
    }

    const gl = canvas.getContext('webgl2', {
      antialias: false,
      alpha: false,
      depth: false,
      stencil: false,
      powerPreference: 'high-performance',
    });
    if (!gl) {
      setSupported(false);
      return;
    }

    const gpu = build(gl, DOMAIN_WARPED_FBM_VERT, DOMAIN_WARPED_FBM_FRAG);
    if (!gpu) {
      loseContext(gl);
      setSupported(false);
      return;
    }
    gpuRef.current = gpu;
    setSupported(true);

    return () => {
      gpuRef.current = null;
      gl.deleteVertexArray(gpu.vao);
      gl.deleteBuffer(gpu.buffer);
      gl.deleteProgram(gpu.program);
      loseContext(gl);
    };
  }, []);

  useEffect(() => {
    const canvas = canvasRef.current;
    const gpu = gpuRef.current;
    if (!canvas || !gpu || width === 0 || height === 0) return;

    const dpr = pixelRatio(maxDpr);
    const w = Math.max(1, Math.round(width * dpr));
    const h = Math.max(1, Math.round(height * dpr));
    if (canvas.width !== w || canvas.height !== h) {
      canvas.width = w;
      canvas.height = h;
    }
    gpu.gl.viewport(0, 0, w, h);
    // One frame here covers both the first paint and the reduced-motion path.
    drawRef.current(reduced ? 12 : 0);
  }, [width, height, maxDpr, supported, reduced]);

  const running = supported && visible && !reduced && width > 0 && height > 0;
  useRaf((_dt, elapsed) => drawRef.current(elapsed), running);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Deletes the VAO, the vertex buffer and the program, then `loseContext(gl)`. The rAF subscription and the pointer listener are removed by their hooks.

**Reduced motion.** The rAF loop never subscribes. One frame is drawn at a fixed `u_time` of 12 seconds — far enough into the sequence that the field is fully developed rather than at its symmetric t=0 state — and redrawn on resize. The cursor light does not track.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Aspect-correcting the sample space but not the pointer. The noise looks right and the cursor glow becomes an ellipse that stretches further the wider the window gets — the two must live in the same coordinate system.
- Using the same offset for both warp channels. `fbm(sp)` and `fbm(sp)` are the same number, so `q` becomes a scalar along the diagonal and the "warp" is a plain translation; you get sliding blobs with none of the folding.
- Feeding `sin()` a large argument inside the hash. `fract(sin(dot(p, ...)))` degrades badly once `p` is in the thousands: the noise develops repeating bands, and it fails on mobile GPUs at scales where the desktop still looks fine. Fold the input with `fract()` first.
- Running 5 octaves because that is what the tutorial did. The output is immediately crushed by a smoothstep, so octaves 3-5 cost real milliseconds and change nothing you can see.
- Letting the shader run in a hidden tab. `useVisibility` gates the loop; without it a backgrounded page keeps a GPU-bound fragment shader resident and the laptop fan tells the user about it.
- Relying on `dispose()`-style cleanup. Raw GL has none — the VAO, buffer and program are deleted explicitly and `loseContext(gl)` hands the context back, without which mounting this component twenty times kills the oldest contexts on the page.

## Notes

- Value noise rather than simplex: after `smoothstep(0.25, 0.85, n)` the two are indistinguishable, and value noise is eight hash calls and seven mixes with no permutation polynomial.
- Total brightness at the defaults runs roughly 0.03 to 0.30. Set `gain={0.08}` for the original hero behaviour, where the whole field stays under 0.18 and white type needs no scrim.

## Definition of done

Watch for ten seconds: the masses should visibly fold and stretch, not just brighten and dim in place. Move the cursor and a faint circular light follows it a beat late while the fog around it shears. Resize from 320px to full width and the noise features stay the same shape rather than stretching horizontally.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Dotted Notepad Surface

A panel textured with a dot grid drawn by a single tiled radial gradient, masked so the pattern dissolves toward the edges instead of ending on a rectangle. An optional turned-down corner is one hard-stopped linear gradient. Nothing is an image, nothing animates, and the whole surface costs one background layer.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A tiled dot grid that dissolves at the panel edges, with a hard-stopped folded corner.

- Category: primitive
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. One `radial-gradient(circle, dot 1.1px, transparent 1.3px)` is tiled by `background-size: 26px 26px`, so `background-size` alone controls the pitch of the grid and the gradient controls the dot. Changing pitch never requires touching the gradient.
2. The 0.2px between the coloured stop and the transparent stop is the antialiasing ramp. With both stops at the same offset the dot edge quantises to the device pixel grid and the dots render as squares at fractional zoom; wider than about 0.4px and they visibly blur.
3. `background-position: center` rather than `0 0` keeps the lattice symmetric about the panel as it resizes. Pinned to the top-left, a resize crops the pattern on one side only and the grid appears to slide.
4. `mask-image` takes two axis gradients — one vertical, one horizontal — each opaque in the middle and transparent for `--kx-pad-fade` at both ends, combined with `mask-composite: intersect`. Intersecting two linear masks fades all four edges while keeping the interior perfectly flat; a single radial mask would instead darken the corners more than the edges and make a rectangular panel read as a lens.
5. `background-attachment` decides what the tile origin is anchored to, and only matters once the dotted element is itself a scroll container. `scroll` anchors to the element border box so the grid holds still while content slides over it; `local` anchors to the scrolled content so the grid travels with the text and the panel reads as one continuous sheet.
6. The fold is a single absolutely-positioned square carrying `linear-gradient(225deg, void 0 43%, crease 43% 48%, under 48% 100%)`. Hard stops (a stop pair at the same offset) mean no interpolation, so the boundary is a crease and not a shadow. The 225deg gradient line points down-left, which puts the void band at the top-right corner where the paper is turned back.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `pitch = 26px`
  Tile size, therefore dot spacing. Below ~18px the grid starts to read as a flat tone rather than a texture and interferes with body text; above ~34px the dots read as individual objects on the page and compete with content.
- `dotSize = 1.1px`
  Dot radius. At exactly 1px the dot lands on a whole device pixel and hardens; the fractional value is what keeps it soft on 1x displays. Above ~1.6px the surface reads as polka dots rather than paper grain.
- `antialias gap = 0.2px`
  Distance from the colour stop to the transparent stop. This is the only softening the dot gets. At 0 the edge quantises and the dots go square at fractional zoom levels; at 0.5px and above the dot loses its centre and the grid looks smudged.
- `fade = 10%`
  How far the edge mask reaches in. Below ~6% the dissolve is too abrupt to read as intentional and looks like a clipping bug; above ~18% the usable flat area of a small panel disappears and content near the edge visibly ghosts.
- `fold stop positions = 43% / 48%`
  The crease is a 5% sliver. Thinner than ~3% and it drops below a pixel on a small fold and disappears; wider than ~8% and it stops reading as a lit edge and becomes a grey stripe. The 43% start places the crease off-centre so the flap looks lifted rather than symmetrically folded.
- `shadow = 0 34px 70px -34px`
  Negative spread equal to the Y offset. It shrinks the shadow box by exactly the amount the offset moved it, so the blur only escapes below the panel. Without the negative spread a 70px blur haloes all four sides and the sheet looks lit from nowhere.

## API

```ts
function DottedNotepadSurface(props: { children?: ReactNode; pitch?: number; dotSize?: number; fade?: string; scrollable?: boolean; attachment?: 'scroll' | 'local' | 'fixed'; fold?: boolean; radius?: string; className?: string; contentClassName?: string }): JSX.Element
```

- `children: ReactNode`
  Panel content. Rendered above the dot layer.
- `pitch: number` — default `26`
  Grid pitch in pixels. Becomes `background-size`.
- `dotSize: number` — default `1.1`
  Dot radius in pixels. The transparent stop lands 0.2px further out.
- `fade: string` — default `'10%'`
  How far the edge mask reaches in from each side.
- `scrollable: boolean` — default `false`
  Makes the dotted layer the scroll container, which is what gives `attachment` meaning.
- `attachment: 'scroll' | 'local' | 'fixed'` — default `'scroll'`
  Tile origin. `scroll` holds the grid still under scrolling content; `local` scrolls the grid with it.
- `fold: boolean` — default `false`
  Draws the turned-down top-right corner.
- `radius: string` — default `'20px'`
  Panel corner radius. The fold inherits it on its own corner.
- `className: string`
  Merged onto the panel. Use for sizing and border.
- `contentClassName: string`
  Merged onto the content wrapper. Put padding here so text clears the mask.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const NOTEPAD_CSS = `
.kx-notepad {
  position: relative;
  isolation: isolate;
  border-radius: var(--kx-pad-radius, 20px);
  overflow: hidden;

  /* Negative spread equal to the Y offset pulls the blur back inside the
     footprint, so the shadow only escapes below the panel. Without it a
     70px blur haloes all four sides and the sheet looks lit from nowhere. */
  box-shadow: 0 34px 70px -34px var(--kx-pad-shadow, rgb(0 0 0 / 0.55));
}

.kx-notepad-sheet {
  height: 100%;
  background-color: var(--kx-pad-bg, var(--color-bg-subtle, Canvas));

  /* One dot per tile. The 0.2px between the colour stop and the transparent
     stop IS the antialiasing — with the stops coincident the dot edge snaps
     to the device pixel grid and the dots go square at odd zoom levels. */
  background-image: radial-gradient(
    circle,
    var(--kx-pad-dot, color-mix(in oklab, currentColor 12%, transparent))
      var(--kx-pad-dot-size, 1.1px),
    transparent calc(var(--kx-pad-dot-size, 1.1px) + 0.2px)
  );
  background-size: var(--kx-pad-pitch, 26px) var(--kx-pad-pitch, 26px);

  /* Centred, not 0 0: the pattern then stays symmetric about the panel as it
     resizes instead of being pinned to the top-left and cropped on one side. */
  background-position: center;
  background-repeat: repeat;
  background-attachment: var(--kx-pad-attachment, scroll);

  /* Two axis gradients intersected. Mask reads alpha only, so the colour
     keyword here is arbitrary — 'black' means "keep", 'transparent' means
     "drop". A single radial mask would round the corners of the fade and
     make a rectangular panel look like a lens. */
  mask-image:
    linear-gradient(
      to bottom,
      transparent 0,
      black var(--kx-pad-fade, 10%),
      black calc(100% - var(--kx-pad-fade, 10%)),
      transparent 100%
    ),
    linear-gradient(
      to right,
      transparent 0,
      black var(--kx-pad-fade, 10%),
      black calc(100% - var(--kx-pad-fade, 10%)),
      transparent 100%
    );
  mask-composite: intersect;
}

.kx-notepad-sheet[data-scrollable='true'] {
  overflow-y: auto;
  overscroll-behavior: contain;
}

/* The turned corner: one hard-stopped gradient, no blur, no extra element.
   Band one is the void the fold reveals and must match whatever sits behind
   the panel; band two is a 5% sliver of highlight along the crease; band
   three is the underside of the flap. Hard stops ('0 43%', '43% 48%') are
   what make it read as a crease rather than a soft shadow. */
.kx-notepad-fold {
  position: absolute;
  inset: 0 0 auto auto;
  width: var(--kx-pad-fold, 52px);
  height: var(--kx-pad-fold, 52px);
  border-top-right-radius: var(--kx-pad-radius, 20px);
  pointer-events: none;
  background: linear-gradient(
    225deg,
    var(--kx-pad-void, var(--color-bg, Canvas)) 0 43%,
    var(--kx-pad-crease, color-mix(in oklab, currentColor 20%, transparent)) 43% 48%,
    var(--kx-pad-under, var(--color-surface, Canvas)) 48% 100%
  );
}

.kx-notepad-body {
  position: relative;
  z-index: 1;
}

/* Nothing here animates, so reduced motion has nothing to switch off. The
   surface is identical in both states by construction. */
`;

export function DottedNotepadSurface({
  children,
  pitch = 26,
  dotSize = 1.1,
  fade = '10%',
  scrollable = false,
  attachment = 'scroll',
  fold = false,
  radius = '20px',
  className,
  contentClassName,
}: DottedNotepadSurfaceProps) {
  const style: StyleWithVars = {
    '--kx-pad-pitch': `${pitch}px`,
    '--kx-pad-dot-size': `${dotSize}px`,
    '--kx-pad-fade': fade,
    '--kx-pad-radius': radius,
    '--kx-pad-attachment': attachment,
  };

  return (
    <>
      <style href="kinetic-dotted-notepad-surface" precedence="medium">
        {NOTEPAD_CSS}
      </style>
      <div className={cn('kx-notepad', className)} style={style}>
        <div className="kx-notepad-sheet" data-scrollable={scrollable ? 'true' : undefined}>
          <div className={cn('kx-notepad-body', contentClassName)}>{children}</div>
        </div>
        {fold ? <span className="kx-notepad-fold" aria-hidden="true" /> : null}
      </div>
    </>
  );
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nothing to clean up. No listeners, no timers, no animation frames. The hoisted `<style>` is reference-counted by React and removed when the last instance unmounts.

**Reduced motion.** Nothing in this component moves in either state — there is no animation, transition or timer to disable. The surface renders identically with `prefers-reduced-motion: reduce` set, including the fold and the edge fade.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Putting the mask on the panel and expecting only the dots to fade. A mask applies to everything the element paints, children included, so text within `--kx-pad-fade` of an edge ghosts out. Content padding must exceed the fade inset — that is why the component has a separate content wrapper for padding rather than padding the panel.
- Reaching for `background-attachment: fixed` to get a parallax grid. The tile origin becomes the viewport, but any ancestor with a `transform`, `filter`, `backdrop-filter` or `will-change` becomes the containing block instead, so the effect silently changes meaning as soon as someone animates a parent. It also repaints the element across its full area on every scroll frame, and iOS Safari has never implemented it usefully.
- Setting `background-attachment: local` on a panel that does not scroll and expecting a difference. `local` and `scroll` are identical until the element itself has overflow — the value is inert, so the "fix" appears to do nothing and gets removed.
- Coincident gradient stops on the dot (`radial-gradient(circle, c 1.1px, transparent 1.1px)`). It looks correct in a screenshot at 100% zoom and turns into a field of tiny squares on a 1.25x or 1.5x display.
- Using the `background` shorthand after setting `background-size`. The shorthand resets `background-size` to `auto`, the tile collapses to the gradient default, and the grid becomes one enormous dot.
- Assuming the fold reads as a hole without matching `--kx-pad-void` to what is actually behind the panel. The first band of the fold gradient is a flat colour pretending to be the page; against a different background it reads as a grey triangle stuck on the corner.

## Notes

- `mask-composite: intersect` needs Safari 15.4+, Chrome 120+ and Firefox 53+. Where it is unsupported only the first mask layer applies, so the grid fades top and bottom but not left and right — a degradation, not a break.
- The dot layer is a real background rather than a pseudo-element so that `background-attachment` has a scroll container to refer to. A decorative absolutely-positioned overlay could not express the `local` behaviour at all.
- The CSS ships inside the component as a `<style href precedence>` element; React 19 hoists it into `<head>` and de-duplicates by `href`, so any number of panels contribute one rule set.

## Definition of done

The dot grid is crisp at 100% and at 150% browser zoom — individual dots stay round, not square. All four edges dissolve rather than ending on a line, and the interior is perfectly even. With `scrollable` and `attachment="local"`, scrolling the panel moves the dots with the text; with `attachment="scroll"` the dots stay put while the text slides over them. With `fold`, the corner reads as turned paper with a single sharp crease and no blur.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Drag with a Dead Zone and Pointer Capture

A deliberate click moves the pointer one to three pixels; a tap on a phone moves five or more. A drag handler with no dead zone calls all of them drags, so the track lurches on every click and the code that suppresses the post-drag click starts suppressing clicks the user meant. This hook captures the pointer on `pointerdown` — so a fast throw that leaves the element keeps delivering moves — and only commits to a drag once the pointer is further than the threshold from the press point. Every one of the four ways a gesture can end funnels through a single exit, because the path you forget is the one that leaves the track welded to a pointer that is no longer there.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Captures the pointer on press but only commits to a drag past a distance threshold, so a shaky click stays a click.

- Category: primitive
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. `pointerdown` records the press point and calls `setPointerCapture(e.pointerId)` immediately, before any distance test. Capture first, commit second: at the moment the threshold is crossed the pointer may already be outside the element, and `setPointerCapture` on a pointer that has since ended throws `NotFoundError`. Inside its own `pointerdown` the pointer is guaranteed active, so it cannot throw there.
2. `pointermove` computes `distance = Math.hypot(clientX - startX, clientY - startY)` and returns early while it is under the threshold — 8 px for mouse and pen, 16 px for touch, read from `pointerType` on the live pointer rather than from a media query. Until it commits, no callback fires and nothing moves.
3. At the moment of commitment the delta origin is re-based to the current point (`lastX = clientX`). A consumer that integrates `deltaX` therefore starts from zero at the commit point instead of receiving the entire dead zone as the first frame's delta, which would snap the track 8 px the instant it engaged. `dx` still measures from the true press point, so the distance maths stays honest.
4. With `axis` set to `x` or `y` the threshold test becomes directional: if the cross axis clears the dead zone first *and* dominates the main axis, the gesture is abandoned as cancelled so the browser can scroll. Combined with `touch-action: pan-y`, a horizontal dragger and vertical page scrolling coexist on a phone.
5. One `finish(clientX, clientY, cancelled)` handles `pointerup`, `pointercancel`, `lostpointercapture` and the returned `cancel()`. It releases the capture if still held, nulls `pointerId`, and calls `onDragEnd(state, { moved, cancelled })`. The `pointerId === null` guard at the top makes the second arrival for one gesture a no-op — `lostpointercapture` always follows a release, so without it every drag would end twice.
6. The effect sets `touch-action` (from `axis`) and `user-select: none` on the element and restores the previous inline values on cleanup, and it cancels HTML5 `dragstart` so a press on an image does not turn into a native file drag.
7. `moved` is the whole output that matters downstream: false means the gesture was a tap and the consumer should treat it as a click; true means a click that arrives next should be swallowed.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `THRESHOLD = 8`
  Dead-zone radius in pixels for mouse and pen. A deliberate trackpad click slips one to three pixels, and a click while the hand is moving toward the target slips more, so below about 6 the dead zone stops catching real clicks. Above about 14 the beginning of a genuine drag feels glued down — the pointer has visibly moved and the track has not.
- `TOUCH_THRESHOLD = 16`
  Dead-zone radius for touch. A finger pad rolls as it presses and the reported point moves with it, typically 5-10 px on a tap; 8 px would classify a large share of taps as drags. Chrome's own touch-slop for scroll arbitration is in the same range, so this roughly matches what the platform already considers a tap.
- `touch-action (axis 'x') = 'pan-y'`
  Not `none`. `none` gives the element every gesture, including the vertical swipe that was meant to scroll the page, and a horizontal carousel that eats vertical swipes makes a phone page feel broken. `pan-y` hands vertical panning back to the browser, which then fires `pointercancel` when it claims the gesture — which is exactly why `pointercancel` has to be handled.

## API

```ts
function useDragDeadzone(ref: RefObject<HTMLElement | null>, options?: { threshold?: number; touchThreshold?: number; axis?: 'both' | 'x' | 'y'; primaryOnly?: boolean; manageStyles?: boolean; enabled?: boolean; onPress?: (state: DragDeadzoneState) => void; onDragStart?: (state: DragDeadzoneState) => void; onDrag?: (state: DragDeadzoneState) => void; onDragEnd?: (state: DragDeadzoneState, end: { moved: boolean; cancelled: boolean }) => void }): { dragging: RefObject<boolean>; pressed: RefObject<boolean>; distance: RefObject<number>; cancel: () => void }
```

- `threshold: number` — default `8`
  Dead-zone radius in pixels for mouse and pen input.
- `touchThreshold: number` — default `16`
  Dead-zone radius for touch, which needs roughly double.
- `axis: 'both' | 'x' | 'y'` — default `'both'`
  A single axis adds a directional lock and narrows `touch-action` to the other one.
- `primaryOnly: boolean` — default `true`
  Ignore secondary touches and any mouse button but the left one.
- `manageStyles: boolean` — default `true`
  Set `touch-action` and `user-select` on the element, restoring inline values on cleanup.
- `enabled: boolean` — default `true`
  Detach every listener when false. Any live capture is released as it detaches.
- `onPress: (state: DragDeadzoneState) => void`
  An accepted `pointerdown`, before any commitment. Kill in-flight settle tweens here.
- `onDragStart: (state: DragDeadzoneState) => void`
  The dead zone was cleared. At most once per gesture.
- `onDrag: (state: DragDeadzoneState) => void`
  Every move after commitment. `deltaX/deltaY` are re-based to the commit point.
- `onDragEnd: (state: DragDeadzoneState, end: DragEnd) => void`
  The single exit. `moved: false` means treat the gesture as a click.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * Dead-zone radius for a mouse, in pixels. Below ~6 a normal click's own
 * tremor clears it and every click becomes a two-pixel drag; above ~14 the
 * start of a deliberate drag feels glued down.
 */
const THRESHOLD = 8;
/** Dead-zone radius for touch. A finger rolls further than a mouse slips. */
const TOUCH_THRESHOLD = 16;

/**
 * Pointer drag that captures immediately and commits on distance.
 *
 * Deliberately does not swallow the trailing `click` — that is a separate
 * concern with its own edge cases (see `capture-phase-click-swallow`). What
 * this reports is the fact the swallow needs: whether the gesture moved.
 */
export function useDragDeadzone(
  ref: RefObject<HTMLElement | null>,
  options: UseDragDeadzoneOptions = {},
): DragDeadzoneHandle {
  const {
    threshold = THRESHOLD,
    touchThreshold = TOUCH_THRESHOLD,
    axis = 'both',
    primaryOnly = true,
    manageStyles = true,
    enabled = true,
  } = options;

  const dragging = useRef(false);
  const pressed = useRef(false);
  const distance = useRef(0);
  const abort = useRef<() => void>(() => {});

  const config = useRef({ threshold, touchThreshold, axis, primaryOnly, options });
  config.current = { threshold, touchThreshold, axis, primaryOnly, options };

  useEffect(() => {
    const el = ref.current;
    if (!el || !enabled) return;

    /** Non-null exactly while a gesture is live. The guard on every handler. */
    let pointerId: number | null = null;
    let pointerType = '';
    let startX = 0;
    let startY = 0;
    /** Origin for `deltaX/deltaY`. Re-based at commitment. */
    let lastX = 0;
    let lastY = 0;
    /** Previous sample, for the path-length integral. */
    let prevX = 0;
    let prevY = 0;
    let travel = 0;
    let committed = false;

    const previousTouchAction = el.style.touchAction;
    const previousUserSelect = el.style.userSelect;
    if (manageStyles) {
      // Without this, the first touch on a drag surface is arbitrated by the
      // browser: it starts a pan, fires `pointercancel`, and the drag never
      // happens. `pan-y` on a horizontal dragger keeps vertical page
      // scrolling working, which `none` would break.
      el.style.touchAction = axis === 'x' ? 'pan-y' : axis === 'y' ? 'pan-x' : 'none';
      el.style.userSelect = 'none';
    }

    const stateAt = (clientX: number, clientY: number): DragDeadzoneState => {
      const dx = clientX - startX;
      const dy = clientY - startY;
      return {
        dx,
        dy,
        deltaX: clientX - lastX,
        deltaY: clientY - lastY,
        clientX,
        clientY,
        distance: Math.hypot(dx, dy),
        travel,
        pointerId: pointerId ?? -1,
        pointerType,
      };
    };

    /**
     * The single exit. `pointerup`, `pointercancel`, `lostpointercapture` and
     * `cancel()` all arrive here, and the `pointerId` guard makes the second
     * arrival for one gesture a no-op — `lostpointercapture` always follows a
     * release, so without the guard every drag would end twice.
     */
    const finish = (clientX: number, clientY: number, cancelled: boolean) => {
      if (pointerId === null) return;
      const state = stateAt(clientX, clientY);
      const moved = committed;

      if (el.hasPointerCapture(pointerId)) el.releasePointerCapture(pointerId);
      pointerId = null;
      committed = false;
      travel = 0;
      dragging.current = false;
      pressed.current = false;
      distance.current = 0;

      config.current.options.onDragEnd?.(state, { moved, cancelled });
    };

    const onPointerDown = (e: PointerEvent) => {
      const cfg = config.current;
      // A second finger is not a new gesture. Overwriting `pointerId` here
      // orphans the first pointer's capture, which is then never released.
      if (pointerId !== null) return;
      if (cfg.primaryOnly && !e.isPrimary) return;
      // Right and middle button, and the second click of a double-click drag.
      if (e.pointerType === 'mouse' && e.button !== 0) return;

      pointerId = e.pointerId;
      pointerType = e.pointerType;
      startX = lastX = prevX = e.clientX;
      startY = lastY = prevY = e.clientY;
      travel = 0;
      committed = false;
      pressed.current = true;
      distance.current = 0;

      // Inside its own `pointerdown` the pointer is guaranteed active, so this
      // cannot throw. Deferring it to the commit is where it can: by then the
      // pointer may have ended, and `setPointerCapture` throws NotFoundError.
      el.setPointerCapture(e.pointerId);
      cfg.options.onPress?.(stateAt(e.clientX, e.clientY));
    };

    const onPointerMove = (e: PointerEvent) => {
      if (pointerId !== e.pointerId) return;
      const cfg = config.current;

      travel += Math.hypot(e.clientX - prevX, e.clientY - prevY);
      prevX = e.clientX;
      prevY = e.clientY;

      const dx = e.clientX - startX;
      const dy = e.clientY - startY;
      distance.current = Math.hypot(dx, dy);

      if (!committed) {
        const limit = pointerType === 'touch' ? cfg.touchThreshold : cfg.threshold;

        if (cfg.axis === 'both') {
          if (distance.current < limit) return;
        } else {
          const main = cfg.axis === 'x' ? dx : dy;
          const cross = cfg.axis === 'x' ? dy : dx;
          // Whichever axis clears the dead zone first owns the gesture. A
          // horizontal dragger that skips this eats every vertical flick that
          // happens to start on it, and the page will not scroll.
          if (Math.abs(cross) >= limit && Math.abs(cross) > Math.abs(main)) {
            finish(e.clientX, e.clientY, true);
            return;
          }
          if (Math.abs(main) < limit) return;
        }

        committed = true;
        dragging.current = true;
        // Re-base the delta origin at the commit point. Without this the first
        // `onDrag` carries the whole dead zone as its delta, and a consumer
        // integrating deltas sees the track snap 8 px the instant it commits.
        lastX = e.clientX;
        lastY = e.clientY;
        cfg.options.onDragStart?.(stateAt(e.clientX, e.clientY));
        return;
      }

      cfg.options.onDrag?.(stateAt(e.clientX, e.clientY));
      lastX = e.clientX;
      lastY = e.clientY;
    };

    const onPointerUp = (e: PointerEvent) => {
      if (pointerId !== e.pointerId) return;
      finish(e.clientX, e.clientY, false);
    };

    /** Browser took the gesture: its own pan, a long-press menu, a stylus lift. */
    const onPointerCancel = (e: PointerEvent) => {
      if (pointerId !== e.pointerId) return;
      finish(e.clientX, e.clientY, true);
    };

    /**
     * Capture ended without a release — an OS window switch, a disconnected
     * device, another element calling `setPointerCapture`. Omitting this is
     * how a carousel ends up stuck to a pointer that left the building:
     * `dragging` stays true and no further event will ever clear it.
     */
    const onLostCapture = (e: PointerEvent) => {
      if (pointerId !== e.pointerId) return;
      finish(e.clientX, e.clientY, true);
    };

    /** HTML's own drag-and-drop. Left alone it hijacks any press on an image. */
    const onNativeDragStart = (e: Event) => e.preventDefault();

    abort.current = () => finish(lastX, lastY, true);

    el.addEventListener('pointerdown', onPointerDown);
    el.addEventListener('pointermove', onPointerMove);
    el.addEventListener('pointerup', onPointerUp);
    el.addEventListener('pointercancel', onPointerCancel);
    el.addEventListener('lostpointercapture', onLostCapture);
    el.addEventListener('dragstart', onNativeDragStart);

    return () => {
      // Release first, while `pointerId` still says which pointer. An element
      // that unmounts holding a capture leaves the browser routing pointer
      // events at a detached node, and the pointer stays captured until the
      // next `pointerdown` anywhere in the document.
      if (pointerId !== null && el.hasPointerCapture(pointerId)) {
        el.releasePointerCapture(pointerId);
      }
      pointerId = null;
      committed = false;
      dragging.current = false;
      pressed.current = false;
      distance.current = 0;
      abort.current = () => {};

      el.removeEventListener('pointerdown', onPointerDown);
      el.removeEventListener('pointermove', onPointerMove);
      el.removeEventListener('pointerup', onPointerUp);
      el.removeEventListener('pointercancel', onPointerCancel);
      el.removeEventListener('lostpointercapture', onLostCapture);
      el.removeEventListener('dragstart', onNativeDragStart);

      if (manageStyles) {
        el.style.touchAction = previousTouchAction;
        el.style.userSelect = previousUserSelect;
      }
    };
  }, [ref, enabled, manageStyles, axis]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The cleanup releases the pointer capture first, while `pointerId` still records which pointer holds it, then nulls the gesture state, removes all six listeners (`pointerdown`, `pointermove`, `pointerup`, `pointercancel`, `lostpointercapture`, `dragstart`), neuters the `cancel()` closure, and restores the element's previous inline `touch-action` and `user-select`. There is no timer and no rAF. Under React 19 StrictMode the first effect has fully released its capture before the second attaches.

**Reduced motion.** Nothing changes, and that is the correct behaviour rather than an omission. Every position this hook reports is one the user is currently holding under their own finger — direct manipulation, one to one, with no animation of its own to shorten or remove, which is why the reduced-motion guidance explicitly exempts it. Reduced motion belongs to whatever happens after release: the settle, the snap, the momentum. Note that the dead zone is deliberately not widened either; a tremor threshold and a motion preference are different user needs and conflating them would degrade dragging for people who never asked for it.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- No dead zone at all. Every click becomes a two-pixel drag, so the track twitches on each press, and any click suppression built on "did it drag" now eats clicks the user intended. This is the failure that makes drag carousels feel untrustworthy.
- Capturing the pointer at the moment of commitment rather than on press. Two bugs at once: the moves that happened during the dead zone are lost, and if the pointer has already ended, `setPointerCapture` throws `NotFoundError` and the drag silently never starts.
- No pointer capture. Throw the track quickly and the pointer leaves the element; `pointermove` stops arriving, the track freezes mid-throw with the button still down, and the eventual `pointerup` lands somewhere else entirely, so the gesture never ends.
- Handling only `pointerup`. `pointercancel` fires whenever the browser claims the gesture for scrolling or a long-press menu — routine on touch — and `lostpointercapture` fires when the capture is dropped without a release. Miss either and `dragging` stays true forever: the next `pointermove` from an unrelated hover keeps driving the track.
- Not guarding against the second end event. `lostpointercapture` always follows a release, so a naive implementation runs its end logic twice per drag — two snap tweens, two velocity readings, and a click-swallow flag set and then cleared.
- Ending the drag without re-basing the delta origin at commitment. The first `onDrag` then reports the full dead-zone offset, and the track jumps by the threshold the moment it engages — small, but it is exactly the wrong 8 px because it lands on the frame the user is watching for feedback.
- Overwriting `pointerId` when a second finger lands. The first pointer's capture is then never released, so the element holds a capture for a pointer that has ended and the next gesture on it behaves unpredictably.
- Forgetting `touch-action`. On touch the browser arbitrates the gesture, decides it is a pan, and fires `pointercancel` before the dead zone is even cleared. The drag works perfectly on a desktop and does nothing at all on a phone, which is a hard bug to find without a device.
- Setting `touch-action: none` on a horizontal dragger. The element swallows vertical swipes too, so the page cannot be scrolled by dragging anywhere over the carousel — on a phone that is often most of the screen.
- Unmounting while the capture is held. The browser keeps routing pointer events to a detached node, and the pointer stays captured until the next `pointerdown` anywhere in the document, so the rest of the page appears to ignore the mouse.
- Using cumulative path length instead of straight-line distance for the dead zone. A hand tremor that wobbles back and forth over the same three pixels accumulates past any threshold without the pointer ever leaving the press point, so the click is classified as a drag — the tremor case the dead zone existed to catch.
- Calling `preventDefault()` on `pointerdown` to stop text selection. It also prevents focus, so the element can no longer be reached or activated from the keyboard. Setting `user-select: none` costs nothing and breaks nothing.

## Notes

- Pairs with `capture-phase-click-swallow`: this hook decides whether the gesture moved, that one suppresses the resulting click. They are separate because the swallow has its own edge cases — one click and no more, and keyboard activation must pass through — and because plenty of consumers want the classification without wanting to intercept clicks at all.
- Both `distance` and `travel` are reported. `distance` is what the dead zone tests; `travel` is the path integral, and their ratio is a cheap measure of how straight the gesture was, which is useful if you want to distinguish a flick from a scribble.
- The returned `cancel()` exists so a host can abort a gesture on Escape, on a route change, or when a modal opens. It runs the same single exit, so the capture is released and `onDragEnd` reports `cancelled: true`.
- Momentum, snapping and rubber-banding are deliberately absent. This is the input layer; what the position does after release belongs to whatever integrates the deltas.

## Definition of done

Press and release without moving: the row does not shift by even a pixel and the readout says the gesture was a tap. Press, wobble a few pixels inside the dead-zone ring, release: still a tap, and the ring never fills. Push past the ring and the row starts following the pointer from where it committed, with no initial jump. Drag fast off the side of the panel and keep going — the row keeps tracking, because the capture holds. Release outside the panel and the gesture ends there. On a phone, swipe horizontally and the row moves; swipe vertically and the page scrolls while the readout reports a cancelled gesture. Right-click on the row: nothing starts. Drag with a second finger already down: the first gesture keeps control. Unmount mid-drag and the rest of the page still responds to the mouse.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Drag Marquee

One unwrapped accumulator carries the idle drift, the drag and the throw; the wrap happens once, in the follow tween's `modifiers`, as `mod(x, period) - period`. Because that is a true modulo it is total — a delta of four periods in one frame lands correctly — and because it is the identity for `x` already inside `[-period, 0)` it never shows a seam. Pressing scatters the cards on a single paused timeline that is played forwards and reversed, and releasing hands the row over to a plugin-free inertial throw.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

An endless row that drifts, takes a drag and a throw, and scatters its cards while your hand is down.

- Category: layout
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. The row is `N` copies of the children inside a `w-max` flex track. `period` is the measured width of one copy — `getBoundingClientRect().width`, not `offsetWidth`, because the latter rounds and half a pixel of error is half a pixel of gap that only ever shows at the seam. The copy count is `clamp(ceil(hostWidth / period) + 1, 2, 8)`, which is exactly enough that a translation bounded by one period can never expose the end of the track.
2. Everything that moves the row adds to one number that is never corrected: the drift subtracts `speed * dt`, each `pointermove` adds `dx`, the release adds the throw distance. It walks off to -50000 and nothing cares, because the only consumer of it applies a modulo.
3. That modulo lives in `gsap.quickTo`'s `modifiers`, which post-processes the value on its way to the target. It cannot feed back: `resetTo` advances the tween's start from its own `s + ratio * c` rather than re-reading the target, so the wrapped value is output-only. Wrapping in `onUpdate` instead makes the next retarget interpolate from a value the tween does not believe in, and the row lurches a whole period.
4. For `x` in `[-period, 0)`, `mod(x, period) === x + period`, so `mod(x, period) - period === x`. The wrap is therefore the identity across the entire range the row normally occupies and only bites when the accumulator leaves it — the two sides of the boundary paint identical pixels, so there is nothing to snap.
5. The gap is a trailing `margin-right` on each tile *inside* a copy rather than `gap` on the track. A track-level gap sits between copies too, so the measured copy width would no longer equal the wrap period and the seam would gain one gap of drift every lap.
6. Release velocity is measured over a rolling ~70 ms window of `(accumulator, time)`, then projected with the `power3.out` identity: `p(t) = 1 - (1 - t)^3` has `p'(0) = 3`, so a tween of duration `D` covering `delta` departs at `3 * delta / D`. Retargeting by `v * D / 3` continues the gesture at exactly the speed the hand left, with the core library and no `InertiaPlugin`.
7. The press scatter is one paused timeline built once and stored in a ref, `play()` on `pointerdown` and `reverse()` on the release path. Per-tile rotation and offset come from a seeded generator indexed by position *within* a copy, so every copy of a tile scatters identically and the duplication stays invisible while the cards move.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `copies = clamp(ceil(hostWidth / period) + 1, 2, 8)`
  The `+ 1` is the copy that covers the wrap: with the translation bounded to one period, the window can start one full period into the track and still needs `hostWidth` of content after it. Drop it and the tail of the row shows background for part of every lap. The floor of 2 is the minimum that can hide a seam at all; the ceiling of 8 stops a one-word tile in a wide hero from producing hundreds of nodes.
- `POWER3_OUT_SLOPE = 3`
  The initial derivative of `power3.out`, and the divisor in `delta = v * D / 3`. Exact, not tuned: change the follow tween's ease and this changes with it — `power2` needs 2, `power4` needs 4. Leave it at 3 against a different ease and every throw is off by a constant factor.
- `smoothing = 0.5`
  Seconds the row takes to catch up with the pointer, and the `D` in the throw projection. Under ~0.2 s the row is welded to the finger and the throw is over before it registers; over ~0.8 s the lag between hand and content is large enough to read as dropped frames rather than as weight.
- `speed = 60`
  Idle drift in px/s. Below ~20 the row looks frozen at a glance and the affordance is lost; above ~120 the text is unreadable at rest, which defeats the point of putting words in it. At 0 the ticker is never registered at all, so a parked marquee costs nothing per frame.
- `VELOCITY_WINDOW = 0.07`
  Seconds of gesture history the release speed is averaged over. Shorter is effectively the last delta, which is noisy at 120 Hz and gives visibly different throws for identical gestures; much longer averages away a deliberate slow-down before release, so the row flies off when the user meant to place it.
- `MAX_VELOCITY = 4000`
  px/s the measured speed is clamped to. A coalesced pointer batch, a tab switch mid-drag or a synthetic event can report tens of thousands; without the clamp one bad sample throws the row several periods, and the wrap makes the result look random rather than fast.
- `MAX_THROW = 1200`
  Pixels one throw may carry. Roughly a screen and a half — far enough that a hard flick feels unbounded, close enough that the content the user was looking at is still findable when it stops.
- `DRAG_THRESHOLD = 5`
  Pixels of travel before a press becomes a drag. Below ~3 the tremor in a normal tap counts as a drag and every tap on a card is swallowed; above ~10 a small deliberate nudge does nothing at all.
- `scatter / spin = 6 (percent) / 10 (deg)`
  Half-ranges for the per-tile offset and rotation on press. The offset is a percentage of each tile's own size, so mixed tile widths scatter proportionally instead of the small ones flying off. Past ~15% and ~25° the tiles overlap their neighbours and the row stops reading as a row; below ~3% and ~5° the press produces no visible acknowledgement.
- `ease: back.inOut(3) = 3`
  The overshoot of the scatter, applied at both ends because the same timeline is played and reversed. It is what makes the cards spring apart and spring back rather than easing politely; at 1 the overshoot is invisible, past ~5 the return visibly overshoots the resting layout and the row wobbles after release.

## API

```ts
function DragMarquee(props: { children: ReactNode; speed?: number; gap?: number; smoothing?: number; scatter?: number; spin?: number; pressScale?: number; scatterDuration?: number; seed?: number | string; className?: string; tileClassName?: string; 'aria-label'?: string }): JSX.Element
```

- `children: ReactNode`
  One tile per child. The whole set is duplicated as many times as the width needs.
- `speed: number` — default `60`
  Idle drift in px/s. Positive drifts left; 0 parks the row and skips the ticker entirely.
- `gap: number` — default `24`
  Pixels between tiles, applied inside a copy so the spacing also spans the seam.
- `smoothing: number` — default `0.5`
  Seconds the row takes to catch up with the pointer. Doubles as the throw duration.
- `scatter: number` — default `6`
  Scatter distance on press, as a percentage of each tile's own size.
- `spin: number` — default `10`
  Half-range of the per-tile rotation on press, in degrees.
- `pressScale: number` — default `0.95`
  Tile scale while the pointer is down.
- `scatterDuration: number` — default `0.5`
  Seconds for the scatter out, and the same again back.
- `seed: number | string` — default `'drag-marquee'`
  Seeds the scatter. The same seed gives the same arrangement on server and client.
- `className: string`
  Merged onto the drag surface.
- `tileClassName: string`
  Merged onto every tile. Size the items here.
- `aria-label: string` — default `'Marquee'`
  Label for the focusable row, which also takes left and right arrow keys.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** The only place the track's transform is written. */
const paint = useCallback(() => {
  const track = trackRef.current;
  if (!track) return;
  track.style.transform = `translate3d(${proxyRef.current.x.toFixed(2)}px, 0px, 0px)`;
}, []);

/**
 * Move the accumulator to `value`. With motion allowed this retargets the
 * follow tween — `quickTo` reuses one tween and one `PropTween` rather than
 * allocating a tween per frame — and the wrap happens in its modifier. With
 * reduced motion there is no tween, so the wrap is applied here instead.
 */
const push = useCallback(
  (value: number) => {
    rawRef.current = value;
    const xTo = xToRef.current;
    if (xTo) {
      xTo(value);
      return;
    }
    const period = periodRef.current;
    proxyRef.current.x = period < 1 ? 0 : mod(value, period) - period;
    paint();
  },
  [paint],
);

/**
 * One follow tween for the life of the component. The wrap lives in
 * `modifiers`, which post-processes the value on its way to the target and
 * never feeds back: `resetTo` advances the tween's start from its own
 * `s + ratio * c`, not by re-reading `proxy.x`. Put the wrap anywhere else
 * — in `onUpdate`, say — and the next retarget interpolates from a value the
 * tween does not believe in, and the row lurches a full period.
 */
useEffect(() => {
  const proxy = proxyRef.current;
  if (reduced) {
    xToRef.current = null;
    return;
  }

  const xTo = gsap.quickTo(proxy, 'x', {
    duration: smoothing,
    ease: 'power3',
    modifiers: {
      // Reads the ref, so a resize changes the period without rebuilding
      // the tween — rebuilding mid-throw would restart the ease from rest.
      x: (value: number) => {
        const period = periodRef.current;
        return period < 1 ? 0 : mod(value, period) - period;
      },
    },
    onUpdate: paint,
  });
  xToRef.current = xTo;

  return () => {
    xToRef.current = null;
    gsap.killTweensOf(proxy);
  };
}, [reduced, smoothing, paint]);

useEffect(() => {
  const host = hostRef.current;
  if (!host) return;

  let pointerId: number | null = null;
  let lastX = 0;
  let pressX = 0;
  let pressY = 0;
  let moved = false;
  let swallowClick = false;
  /** Rolling window: the accumulator and clock at the start of the window. */
  let sampleRaw = 0;
  let sampleTime = 0;

  const now = () => performance.now() / 1000;

  const onPointerDown = (e: PointerEvent) => {
    // One pointer owns the row. A second finger arriving mid-throw would
    // otherwise reset the origin and the row would jump.
    if (pointerId !== null || !e.isPrimary) return;
    if (e.pointerType === 'mouse' && e.button !== 0) return;

    pointerId = e.pointerId;
    lastX = e.clientX;
    pressX = e.clientX;
    pressY = e.clientY;
    moved = false;
    sampleRaw = rawRef.current;
    sampleTime = now();
    pressedRef.current = true;

    // Capture on press, not once the threshold is crossed: by then the
    // pointer may already have left the element and `pointermove` would have
    // stopped arriving.
    host.setPointerCapture(e.pointerId);
    // Scatter on press, like a physical stack of cards being pinned — the
    // press, not the drag, is what the eye reads as "I have hold of this".
    scatterRef.current?.play();
  };

  const onPointerMove = (e: PointerEvent) => {
    if (pointerId !== e.pointerId) return;

    const dx = e.clientX - lastX;
    lastX = e.clientX;

    if (!moved) {
      if (Math.hypot(e.clientX - pressX, e.clientY - pressY) < DRAG_THRESHOLD) return;
      moved = true;
    }

    push(rawRef.current + dx);

    // Retire the velocity window once it is full. Measuring over a window
    // rather than off the last delta is what stops "drag, pause, lift" from
    // throwing the row: with no movement there are no events, the window
    // never advances, and the measured speed decays toward zero on its own.
    const t = now();
    if (t - sampleTime > VELOCITY_WINDOW) {
      sampleRaw = rawRef.current;
      sampleTime = t;
    }
  };

  /**
   * Idempotent. Called from `pointerup`, `pointercancel` and
   * `lostpointercapture`, all three of which can be the last event a gesture
   * produces, and at least one of which always arrives — including when the
   * pointer is released outside the window or the OS takes it away for a
   * gesture of its own. Guarding on `pointerId` makes the extra calls no-ops
   * instead of a double throw, and it is what stops a drag that ended
   * off-screen from leaving the row stuck mid-throw with the cards still
   * scattered.
   */
  const finish = (e: PointerEvent) => {
    if (pointerId !== e.pointerId) return;
    const id = pointerId;
    pointerId = null;
    pressedRef.current = false;

    const elapsed = now() - sampleTime;
    const velocity =
      moved && elapsed > 0
        ? clamp((rawRef.current - sampleRaw) / elapsed, -MAX_VELOCITY, MAX_VELOCITY)
        : 0;

    swallowClick = moved;
    moved = false;

    if (host.hasPointerCapture(id)) host.releasePointerCapture(id);
    scatterRef.current?.reverse();

    if (velocity !== 0) {
      // v·D/3 is the distance a `power3.out` of duration D covers when it
      // departs at v. Retargeting by exactly that hands the row over from
      // the finger without a change of speed.
      push(
        rawRef.current +
          clamp((velocity * smoothing) / POWER3_OUT_SLOPE, -MAX_THROW, MAX_THROW),
      );
    }
  };

  // Capture phase, ahead of any child's own handler. A drag ends with a
  // `click` on whatever happens to be under the pointer, so without this the
  // gesture that scrolls the row also activates a card.
  const onClick = (e: MouseEvent) => {
    if (!swallowClick) return;
    swallowClick = false;
    e.preventDefault();
    e.stopPropagation();
  };

  const onKeyDown = (e: KeyboardEvent) => {
    const direction = e.key === 'ArrowRight' ? 1 : e.key === 'ArrowLeft' ? -1 : 0;
    if (direction === 0) return;
    e.preventDefault();
    const step = perCopy > 0 ? periodRef.current / perCopy : periodRef.current;
    push(rawRef.current + direction * step);
  };

  host.addEventListener('pointerdown', onPointerDown);
  host.addEventListener('pointermove', onPointerMove);
  host.addEventListener('pointerup', finish);
  host.addEventListener('pointercancel', finish);
  host.addEventListener('lostpointercapture', finish);
  host.addEventListener('click', onClick, true);
  host.addEventListener('keydown', onKeyDown);

  return () => {
    host.removeEventListener('pointerdown', onPointerDown);
    host.removeEventListener('pointermove', onPointerMove);
    host.removeEventListener('pointerup', finish);
    host.removeEventListener('pointercancel', finish);
    host.removeEventListener('lostpointercapture', finish);
    host.removeEventListener('click', onClick, true);
    host.removeEventListener('keydown', onKeyDown);
    if (pointerId !== null && host.hasPointerCapture(pointerId)) {
      host.releasePointerCapture(pointerId);
    }
    pointerId = null;
    pressedRef.current = false;
  };
}, [push, smoothing, perCopy]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes `pointerdown`, `pointermove`, `pointerup`, `pointercancel`, `lostpointercapture`, the capture-phase `click` and `keydown`; releases pointer capture if a gesture is still live at unmount; removes the drift callback from `gsap.ticker`; kills the tweens on the proxy object so an in-flight throw cannot call `onUpdate` against a detached track; and reverts the `gsap.context` holding the scatter timeline, which also restores the tiles' inline transforms. Both shared resize observers and the shared intersection observer unregister.

**Reduced motion.** Dragging is unchanged — it is the user's own motion, and tracking it is the component. Everything the component would have animated by itself is dropped: the idle drift is never registered on the ticker, the follow tween is never created (so the row is written straight to the wrapped position, one-to-one with the pointer, and a release does not throw), and the scatter timeline is not built, so pressing moves nothing but the row. Arrow keys still step one tile, instantly.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Correcting the offset with `if (x < -period) x += period` instead of a modulo. It only ever undoes one period, so a fast flick, a coalesced pointer batch, or a tab that was backgrounded for a second leaves the row several periods out and it jumps to the wrong tile. `mod` is total: any magnitude, one step, right answer.
- Applying the wrap in `onUpdate` rather than in `modifiers`. The tween then interpolates from a start value it computed internally toward a target the wrap has already moved, so the next retarget travels a whole extra period. `modifiers` is post-processing on the way out and never feeds back into the tween's own bookkeeping.
- Putting the gap on the track with `gap` or `space-x`. It lands between copies as well as between tiles, so the measured copy width no longer equals the wrap period; the seam gains one gap per lap and slowly slides out of register. The gap belongs inside the copy, as a trailing margin on every tile.
- Measuring the period with `offsetWidth`. It rounds to whole pixels, and a sub-pixel error in the period is a permanent sub-pixel misalignment at the seam that shows as a hairline flicker once per lap.
- Hard-coding two copies. Two is enough only while one copy is at least as wide as the container; a short tile set in a wide hero runs out of content mid-lap and the row ends in empty space. The count has to come from the measured width.
- Randomising the scatter per DOM node. The duplicates are the whole trick, and the instant the cards move with different rotations the eye reads them as different content — the seam becomes obvious. Index the seed by position within a copy, so copy 3 tile 5 matches copy 1 tile 5.
- Rebuilding the scatter timeline per press, or putting the pressed flag in the `useGsap` deps. `revert()` strips the inline transforms GSAP wrote, so the reverse starts from the untouched stylesheet values and animates nowhere — the cards stay scattered. One paused timeline, `play()` and `reverse()` from the pointer handlers.
- Leaving the idle drift running during a drag. The row creeps out from under the finger, which is precisely what one-to-one tracking exists to prevent; over a slow careful drag the divergence is several tiles.
- Calling `setPointerCapture` only after the drag threshold is crossed. A fast gesture has already left the element by then, `pointermove` stops arriving, and the row sticks at the offset it had when the pointer crossed the boundary.
- Handling only `pointerup`. Release outside the window, or let the OS claim the gesture, and no `pointerup` arrives: the row stays captured, the drift never resumes, and the cards stay scattered mid-throw. `pointercancel` and `lostpointercapture` route to the same idempotent finish, guarded on the stored `pointerId` so the duplicate is a no-op rather than a second throw.
- Letting the click through after a drag. The gesture ends with a `click` on whichever card is under the pointer, so dragging the row also opens a project. It is swallowed in the capture phase, once, and only when the gesture actually moved.

## Notes

- The follow tween is retargeted, not recreated: `gsap.quickTo` keeps one tween and one `PropTween` alive and calls `resetTo` on it, so a marquee dragged for ten seconds allocates nothing per frame.
- The drift is registered on `gsap.ticker` rather than a second rAF loop, so the target and the tween that chases it advance in the same tick. On separate loops the row is one frame stale every other frame, which reads as a faint shimmer at speed.
- Because the drift keeps retargeting the same tween after release, the throw decays exponentially with a time constant of `smoothing / 3` rather than tracing a literal `power3` curve. The departure speed is still exactly the hand's, which is the part the eye judges.
- Only the first copy is exposed to assistive technology; the rest carry `aria-hidden`, so a screen reader reads the list once rather than four times.

## Definition of done

The row drifts on its own. Grab it and it follows your hand exactly, with no creep in the drift direction, and the cards tilt and shrink apart the instant you press — then settle back when you let go. Flick and release: it coasts on at the speed you left, slows, and rejoins the drift with no visible seam or jump. Drag several screens' worth in one fast swipe and the tiles stay in order — nothing teleports. Watch one tile go off the left edge and it reappears on the right at the same spacing as every other gap. Release the pointer outside the browser window and the row keeps drifting instead of freezing scattered. Release over a card and no click reaches it; tap without moving and it does. Resize the container narrower and wider — the seam never appears. Scroll it out of view and the drift stops until it is back.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Drag-Throw Scroll

A third input modality bolted onto a scroll position that already has two. Wheel, pointer drag and arrow keys all write to one place, so they cannot disagree — press stops whatever was coasting exactly where it looks, the drag maps 1:1 from the press point, and release converts the last 100 ms of hand movement into a decaying throw. Pointed at the document it drives the shared Lenis instance; pointed at a box it drives `scrollTop` through the same physics.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Grab the page and pull it; let go mid-move and it coasts on, decaying, as far as the flick earned.

- Category: scroll
- Runtime cost: dom
- Dependencies: lenis@^1.3.11

## How it works

1. On `pointerdown` the surface calls `setPointerCapture` and records `startY` plus `startScroll = lenis.scroll` — the animated position, not `targetScroll`, so grabbing a coasting page stops the content where the eye sees it rather than where the throw was headed.
2. Every `pointermove` recomputes the scroll target absolutely: `clamp(startScroll - (clientY - startY) * gain, 0, limit)`. Gain is `multiplier` for mouse and pen and hard-wired to 1 for touch, because a finger is physically on the content and any other value slides the content out from under it.
3. Positions are pushed into a 5-entry ring of `{ y, timeStamp }`. On release, velocity is `(newest.y - oldest.y) / (newest.t - oldest.t) * 1000` px/s using only samples inside a 100 ms window, so the number describes the hand rather than the event rate.
4. The throw target is `target + (-velocity * gain) * throwSeconds`, clamped to the scroll limit. Below `MIN_THROW_SPEED` nothing is issued at all, so a careful release parks instead of drifting.
5. The decay is one curve expressed twice: `lenis.scrollTo(y, { lerp: 0.05 })` for the page, and `damp(scrollTop, y, perFrameToSmoothing(0.05), dt)` on the shared rAF for a box scroller, which stops writing once it is within 0.5 px of target.
6. `ArrowUp` / `ArrowDown` on the focused surface step by `keyStep` px through `scrollTo(y, { duration: 0.2 })`, so keyboard, wheel and hand all mutate the same single position.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `multiplier = 2`
  Scroll px per mouse px. At 1 a long page needs a grab per viewport, because the cursor runs out of window; above ~3 the content outruns the hand and the gesture stops reading as direct manipulation. Touch ignores this entirely and uses 1.
- `throwSeconds = 0.65`
  Coast distance is velocity × this, so it is the time constant of the flick. Under ~0.3 a hard flick barely outruns the release and the throw is invisible; over ~1 a flick crosses the whole document and lands somewhere the user did not aim.
- `THROW_LERP = 0.05`
  Per-frame fraction of the remaining gap, i.e. a long slow settle — the point of a throw is that it decays visibly. At 0.2 it arrives in a few frames and reads as a jump; `perFrameToSmoothing` converts the same number for the `damp` path so the two sinks decay identically.
- `SAMPLE_WINDOW_MS = 100`
  Only samples newer than this count toward the release velocity. Without the window, a drag that travels fast and then stops dead for a second still throws, because the fast samples are still in the buffer — the page launches from a hand that was holding still.
- `SAMPLE_COUNT = 5`
  Ring length. One sample is pure jitter, and more than about five spans long enough that the window filter is doing all the work anyway; five covers roughly 80 ms at 60 Hz, which is one flick.
- `MIN_THROW_SPEED = 120 px/s`
  Below this no throw is issued. At 0.65 s of coast, 120 px/s is a 78 px slide — around the point where a deliberate stop stops feeling deliberate. Lower and the content creeps after every release.
- `SETTLE_EPSILON = 0.5 px`
  An exponential never actually arrives. Without a floor the box sink writes a sub-pixel `scrollTop` every frame forever, so the rAF subscription never idles and the scroll event never stops firing.
- `KEY_STEP_SECONDS = 0.2`
  Arrow-key travel time. Instant is disorienting because nothing connects the two positions; beyond ~0.35 s holding the key queues steps faster than they complete and the page falls behind the keyboard.

## API

```ts
function DragThrowScroll(props: { children?: ReactNode; scroller?: RefObject<HTMLElement | null>; multiplier?: number; throwSeconds?: number; keyStep?: number; enabled?: boolean; className?: string }): JSX.Element
```

- `children: ReactNode`
  The draggable content. The surface is `position: relative` and nothing else.
- `scroller: RefObject<HTMLElement | null>`
  Box to scroll. Omit to drive the document through the shared Lenis instance.
- `multiplier: number` — default `2`
  Scroll px per pointer px for mouse and pen. Touch is always 1.
- `throwSeconds: number` — default `0.65`
  Time constant of the release throw; distance is velocity × this.
- `keyStep: number` — default `100`
  Arrow-key step in px while the surface has focus.
- `enabled: boolean` — default `true`
  False removes every listener and restores native scrolling.
- `className: string`
  Merged onto the drag surface.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * Lenis's per-frame lerp for the throw, and the same curve expressed for
 * `damp` so a box scroller decays identically to the page. One number, two
 * sinks — tuning it in one place cannot desync them.
 */
const THROW_LERP = 0.05;
const THROW_SMOOTHING = perFrameToSmoothing(THROW_LERP);

const SAMPLE_COUNT = 5;
const SAMPLE_WINDOW_MS = 100;
const MIN_THROW_SPEED = 120;
const SETTLE_EPSILON = 0.5;
const KEY_STEP_SECONDS = 0.2;

/** Presses on real controls belong to those controls, not to the drag. */
const NO_DRAG = 'a,button,input,select,textarea,label,[data-no-drag]';

function scrollBoxOf(scroller?: RefObject<HTMLElement | null>): Element | null {
  if (scroller) return scroller.current;
  return typeof document === 'undefined' ? null : document.scrollingElement;
}

export function DragThrowScroll({
  children,
  scroller,
  multiplier = 2,
  throwSeconds = 0.65,
  keyStep = 100,
  enabled = true,
  className,
}: DragThrowScrollProps) {
  const surface = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();

  /* Lenis owns the document and nothing else. A component pointed at its own
     box must not build one — and under reduced motion nobody wants smoothing
     at all, so the page sink degrades to direct `scrollTop` writes. The hook
     is refcounted: several of these on one page share the single instance
     rather than stacking `wheel` handlers that each call `preventDefault`. */
  const viaLenis = enabled && !reduced && scroller === undefined;
  const lenis = useLenis({ enabled: viaLenis });

  /** Coast target for the box sink. `null` means nothing is in flight. */
  const glide = useRef<number | null>(null);

  useRaf(
    (dt) => {
      const to = glide.current;
      const box = scrollBoxOf(scroller);
      if (to === null || !box) return;
      const next = damp(box.scrollTop, to, THROW_SMOOTHING, dt);
      // Snap and stop. An exponential never arrives, so without a floor this
      // writes a sub-pixel delta every frame forever and the loop never idles.
      if (Math.abs(to - next) < SETTLE_EPSILON) {
        glide.current = null;
        box.scrollTop = to;
        return;
      }
      box.scrollTop = next;
    },
    // Only the box sink needs a loop: Lenis animates its own scrollTo, and
    // reduced motion has nothing to animate.
    enabled && !reduced && scroller !== undefined,
  );

  useEffect(() => {
    const el = surface.current;
    if (!el || !enabled) return;

    let pointerId: number | null = null;
    let startY = 0;
    let startScroll = 0;
    let target = 0;
    let gain = 1;
    const samples: Sample[] = [];

    /* -- the sink: Lenis when it exists, the raw box otherwise -------------- */

    const read = (): number => {
      const l = lenis.current;
      // `scroll`, not `targetScroll`. This is read on press, and grabbing a
      // coasting page has to stop it where the content LOOKS, not where it was
      // headed — otherwise the first pixel of the drag jumps forward by
      // whatever the throw had left to run.
      if (l) return l.scroll;
      return scrollBoxOf(scroller)?.scrollTop ?? 0;
    };

    const limitOf = (): number => {
      const l = lenis.current;
      if (l) return l.limit;
      const box = scrollBoxOf(scroller);
      return box ? Math.max(0, box.scrollHeight - box.clientHeight) : 0;
    };

    /** Direct manipulation: the content is under a finger, so no smoothing. */
    const jump = (y: number) => {
      glide.current = null;
      const l = lenis.current;
      if (l) {
        l.scrollTo(y, { immediate: true });
        return;
      }
      const box = scrollBoxOf(scroller);
      if (box) box.scrollTop = y;
    };

    /** Release: an exponential decay toward the thrown target. */
    const coast = (y: number) => {
      const l = lenis.current;
      if (l) {
        l.scrollTo(y, { lerp: THROW_LERP });
        return;
      }
      glide.current = y;
    };

    const step = (y: number) => {
      const l = lenis.current;
      if (l) {
        l.scrollTo(y, { duration: KEY_STEP_SECONDS });
        return;
      }
      glide.current = null;
      scrollBoxOf(scroller)?.scrollTo({ top: y, behavior: reduced ? 'auto' : 'smooth' });
    };

    /* -- velocity ---------------------------------------------------------- */

    /**
     * Pointer velocity in px/s, measured from the oldest sample still inside
     * the window to the newest. Time-based rather than per-event, so the
     * number describes the hand rather than the display.
     */
    const velocityAt = (now: number): number => {
      let oldest: Sample | undefined;
      for (const sample of samples) {
        if (now - sample.t <= SAMPLE_WINDOW_MS) {
          oldest = sample;
          break;
        }
      }
      const newest = samples[samples.length - 1];
      if (!oldest || !newest) return 0;
      const span = newest.t - oldest.t;
      if (span <= 0) return 0;
      return ((newest.y - oldest.y) / span) * 1000;
    };

    /* -- pointer lifecycle ------------------------------------------------- */

    const onPointerDown = (e: PointerEvent) => {
      if (pointerId !== null || !e.isPrimary) return;
      if (e.pointerType === 'mouse' && e.button !== 0) return;
      if (e.target instanceof Element && e.target.closest(NO_DRAG)) return;

      pointerId = e.pointerId;
      // A finger is physically on the content: any gain but 1 slides the
      // content out from under it. A mouse is an indirect device with a
      // window-height of travel available, so it gets the multiplier.
      gain = e.pointerType === 'touch' ? 1 : multiplier;
      startY = e.clientY;
      startScroll = read();
      target = startScroll;
      jump(startScroll);
      samples.length = 0;
      samples.push({ y: e.clientY, t: e.timeStamp });
      // Captured on press, not on some later threshold: by the time a
      // threshold would trip, the pointer may already be off the element.
      el.setPointerCapture(e.pointerId);
      el.dataset.dragging = 'true';
    };

    const onPointerMove = (e: PointerEvent) => {
      if (e.pointerId !== pointerId) return;
      // Absolute, from the press point. Accumulating per-event deltas onto the
      // live scroll position loses whatever the sink has not applied yet, and
      // the content drifts behind the hand over a long drag.
      target = clamp(startScroll - (e.clientY - startY) * gain, 0, limitOf());
      jump(target);
      samples.push({ y: e.clientY, t: e.timeStamp });
      if (samples.length > SAMPLE_COUNT) samples.shift();
    };

    const release = (e: PointerEvent, thrown: boolean) => {
      if (e.pointerId !== pointerId) return;
      pointerId = null;
      el.dataset.dragging = 'false';
      if (el.hasPointerCapture(e.pointerId)) el.releasePointerCapture(e.pointerId);

      if (!thrown || reduced) {
        samples.length = 0;
        return;
      }
      samples.push({ y: e.clientY, t: e.timeStamp });
      const velocity = velocityAt(e.timeStamp);
      samples.length = 0;
      const scrollVelocity = -velocity * gain;
      if (Math.abs(scrollVelocity) < MIN_THROW_SPEED) return;
      coast(clamp(target + scrollVelocity * throwSeconds, 0, limitOf()));
    };

    const onPointerUp = (e: PointerEvent) => release(e, true);
    // Both of these are aborts, so neither throws. `pointercancel` is the OS
    // taking the gesture; `lostpointercapture` is the catch-all — capture
    // revoked with no `pointerup` at all, which is the one path that would
    // otherwise leave the surface stuck believing a finger is still down. It
    // also fires immediately after a normal release, where the `pointerId`
    // guard above has already made it a no-op.
    const onPointerCancel = (e: PointerEvent) => release(e, false);
    const onLostCapture = (e: PointerEvent) => release(e, false);

    // Native HTML5 drag on any image or link inside would hijack the gesture
    // and hand back a ghost image instead of a scroll.
    const onDragStart = (e: Event) => e.preventDefault();

    const onKeyDown = (e: KeyboardEvent) => {
      const dir = e.key === 'ArrowDown' ? 1 : e.key === 'ArrowUp' ? -1 : 0;
      if (dir === 0) return;
      e.preventDefault();
      step(clamp(read() + dir * keyStep, 0, limitOf()));
    };

    el.addEventListener('pointerdown', onPointerDown);
    el.addEventListener('pointermove', onPointerMove);
    el.addEventListener('pointerup', onPointerUp);
    el.addEventListener('pointercancel', onPointerCancel);
    el.addEventListener('lostpointercapture', onLostCapture);
    el.addEventListener('dragstart', onDragStart);
    el.addEventListener('keydown', onKeyDown);

    return () => {
      el.removeEventListener('pointerdown', onPointerDown);
      el.removeEventListener('pointermove', onPointerMove);
      el.removeEventListener('pointerup', onPointerUp);
      el.removeEventListener('pointercancel', onPointerCancel);
      el.removeEventListener('lostpointercapture', onLostCapture);
      el.removeEventListener('dragstart', onDragStart);
      el.removeEventListener('keydown', onKeyDown);
      if (pointerId !== null && el.hasPointerCapture(pointerId)) {
        el.releasePointerCapture(pointerId);
      }
      el.dataset.dragging = 'false';
      glide.current = null;
    };
  }, [scroller, lenis, multiplier, throwSeconds, keyStep, enabled, reduced]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** All seven listeners are removed, any pointer still captured is released, the coast target is cleared so the shared rAF idles, and `data-dragging` is reset. The Lenis instance is refcounted by `useLenis`: the last consumer to unmount destroys it, earlier ones only detach.

**Reduced motion.** Dragging still works and is still 1:1 — pulling content with a finger is direct manipulation, not motion someone asked to be spared. What is removed is everything that keeps moving on its own: no Lenis instance is built, so the page scrolls natively, release stops exactly where the hand stopped, and arrow keys jump rather than travel.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Constructing a second Lenis instance instead of sharing one. Both bind `wheel`, both call `preventDefault`, and the page scrolls at exactly double speed — which looks like a badly tuned multiplier and gets "fixed" by halving the multiplier instead.
- Measuring velocity as the mean of per-event deltas. That is px per event, not px per second: the identical physical flick throws half as far on a 120 Hz display, because each event covers half the distance. Divide by real elapsed time.
- Not expiring old samples. Drag fast, hold still for a second, release — the buffer still holds the fast samples and the page launches from a stationary hand.
- Accumulating `scrollTo(current + delta)` per move. `current` is the animated position, which lags the target, so every event throws away the part the sink has not applied yet and the content drifts behind the hand over a long drag. Track the press point and compute the target absolutely.
- Omitting `setPointerCapture`. Drag past the edge of the surface and `pointermove` stops arriving, so the content freezes mid-gesture and then teleports when the pointer comes back.
- Treating `pointerup` as the only terminator. Capture can be revoked with no `pointerup` — the OS claims the gesture, the element is detached, another finger lands — and the surface is left believing a finger is still down, ignoring every later press. `pointercancel` and `lostpointercapture` both have to end the drag.
- Leaving `touch-action` at its default. The compositor claims the touch gesture, `pointermove` stops, and the drag dies in a `pointercancel` on the first frame while the page scrolls natively underneath.
- Forgetting that a host stylesheet with `scroll-behavior: smooth` fights a direct `scrollTop` write on the box sink, which shows up as a rubbery lag under the finger. Set `scroll-behavior: auto` on the scroll container.

## Notes

- The surface takes `tabIndex={0}` and binds `keydown` on itself rather than on `window`, so arrow keys still belong to a search field elsewhere on the page.
- Presses that land on `a, button, input, select, textarea, label` or anything marked `[data-no-drag]` are left alone, so a link inside the draggable area is still a link.
- `dragstart` is prevented on the surface: native HTML5 drag on an inner image or link would otherwise hand back a ghost image instead of a scroll.

## Definition of done

Press and pull upward: the content follows the pointer and stops the moment the pointer does. Flick and release: it coasts on and decays to a stop. Grab it mid-coast and it stops dead under your hand with no forward jump. Start a drag, run the pointer off the edge of the window and release there — the content stops instead of sticking, and the next press still works. Focus the surface and hold ArrowDown for stepped travel. With reduced motion on, release stops instantly.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Drag Mapped To Pin Progress

A drag surface laid over a pinned horizontal section. Instead of a tuned drag multiplier it reads the pin's live geometry — the scroll span it occupies and the pixels the strip travels — and converts one into the other, so a pixel of thumb is a pixel of track regardless of panel widths or zoom. Release throws it, and the throw decays in wall-clock time rather than per frame.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Drag a pinned horizontal strip and it moves exactly one pixel per pixel, then throws and settles.

- Category: scroll
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. The conversion is `ratio = (trigger.end - trigger.start) / getDistance()`: scroll pixels the pin occupies, divided by horizontal pixels the strip travels. Both are read on every use because ScrollTrigger recomputes `end` on each refresh.
2. During a drag the scroll position is set absolutely — `scrollTop = pressScrollTop - dx * ratio` — using the offset from the press point, never an accumulation of per-move deltas.
3. Velocity is sampled as `(clientX - lastX) / dt` in seconds and clamped to ±4000 px/s, so a single stuttering event pair cannot record an implausible throw.
4. On release the velocity decays with `damp(v, 0, friction, dt)` and the scroll advances by `-v * ratio * dt` each frame, so a 144 Hz display and a 60 Hz display travel the same distance in the same wall-clock time.
5. The loop self-parks: below 20 px/s the velocity is zeroed and the callback returns immediately on subsequent frames, so an idle component costs one comparison per frame.
6. `trigger.progress` is rounded to three decimals and written to a `--pin-progress` custom property on the surface only when it changes, so a progress rail can be pure CSS with no per-frame React render.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `friction = 0.002`
  Fraction of throw velocity remaining after one second. 0.002 lands a hard flick in roughly half a second. Near 0.1 the throw stops dead and the release feels like hitting a wall; above ~0.05 it coasts long enough that the user reaches for the scrollbar to stop it.
- `THROW_FLOOR = 20`
  Pixels per second below which the throw is cut and the loop parks. Exponential decay never reaches zero, so without a floor the component writes a sub-pixel scroll change forever and never idles.
- `MAX_THROW = 4000`
  Velocity clamp in px/s. Two pointer events 2 ms apart produce an enormous instantaneous velocity; unclamped, a single jittery sample launches the track across its entire range.
- `release timeout = 80 ms`
  Hold still for longer than this before letting go and the release is not a throw. Without it, pausing mid-drag and releasing fires the stale velocity from the last movement.
- `progress quantisation = 3 decimals`
  Below this the custom property is rewritten on nearly every frame with a change no one can see; above it the progress rail visibly steps.

## API

```ts
function DragToPinProgress(props: { children: ReactNode; scroller: RefObject<HTMLElement | null>; trigger: ScrollTrigger | null; getDistance?: () => number; friction?: number; className?: string }): JSX.Element
```

- `children: ReactNode`
  The pinned section and anything overlaying it.
- `scroller: RefObject<HTMLElement | null>`
  The scroll container whose `scrollTop` the drag writes.
- `trigger: ScrollTrigger | null`
  The pinned trigger being scrubbed. Dragging is disabled while null.
- `getDistance: () => number`
  Live horizontal travel of the strip in px. Omit for a 1:1 scroll mapping.
- `friction: number` — default `0.002`
  Fraction of throw velocity left after one second.
- `className: string`
  Merged onto the drag surface.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function DragToPinProgress({
  children,
  scroller,
  trigger,
  getDistance,
  friction = 0.002,
  className,
}: DragToPinProgressProps) {
  const surface = useRef<HTMLDivElement>(null);
  const startScroll = useRef(0);
  const throwVelocity = useRef(0);
  const lastMoveX = useRef(0);
  const lastMoveTime = useRef(0);
  const lastProgress = useRef(-1);
  const reduced = useReducedMotion();

  // Scroll pixels per pixel of horizontal track travel. Read live, because
  // `end` is recomputed on every ScrollTrigger refresh and the panel widths
  // change with the container.
  const ratio = () => {
    if (!trigger) return 1;
    const span = trigger.end - trigger.start;
    const travel = getDistance?.() ?? span;
    return travel > 0 ? span / travel : 1;
  };

  const applyScroll = (value: number) => {
    const el = scroller.current;
    if (!el) return;
    const max = el.scrollHeight - el.clientHeight;
    el.scrollTop = clamp(value, 0, max);
  };

  useDrag(surface, {
    enabled: trigger !== null,
    onDragStart: (state) => {
      throwVelocity.current = 0;
      startScroll.current = scroller.current?.scrollTop ?? 0;
      lastMoveX.current = state.clientX;
      lastMoveTime.current = performance.now();
    },
    onDrag: (state) => {
      // Absolute, from the press point — not an accumulation of deltas.
      // Accumulating drifts, because every clamp at the ends silently eats
      // part of a delta and the track never returns to where the hand is.
      applyScroll(startScroll.current - state.dx * ratio());

      const now = performance.now();
      const dt = (now - lastMoveTime.current) / 1000;
      if (dt > 0) {
        const instant = (state.clientX - lastMoveX.current) / dt;
        throwVelocity.current = clamp(instant, -MAX_THROW, MAX_THROW);
        lastMoveX.current = state.clientX;
        lastMoveTime.current = now;
      }
    },
    onDragEnd: (_state, moved) => {
      // A tap is not a throw. Without this, releasing after a pause launches
      // the track at whatever velocity the last move happened to record.
      if (!moved || reduced || performance.now() - lastMoveTime.current > 80) {
        throwVelocity.current = 0;
      }
    },
  });

  useRaf((dt) => {
    const el = surface.current;

    // Publish the pin's own progress as a CSS variable rather than state:
    // a progress rail must not cost a React render per frame.
    if (el && trigger) {
      const p = Math.round(trigger.progress * 1000) / 1000;
      if (p !== lastProgress.current) {
        lastProgress.current = p;
        el.style.setProperty('--pin-progress', String(p));
      }
    }

    if (throwVelocity.current === 0) return;

    // Exponential decay in wall-clock time, so the throw travels the same
    // distance on a 60 Hz panel as on a 144 Hz one.
    throwVelocity.current = damp(throwVelocity.current, 0, friction, dt);
    if (Math.abs(throwVelocity.current) < THROW_FLOOR) {
      throwVelocity.current = 0;
      return;
    }

    const current = scroller.current?.scrollTop ?? 0;
    applyScroll(current - throwVelocity.current * ratio() * dt);
  });
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useDrag` removes its pointerdown/move/up/cancel and capture-phase click listeners and releases any outstanding pointer capture; `useRaf` unsubscribes from the shared loop. The `--pin-progress` property dies with the element, and no timers or tweens are created that could outlive it.

**Reduced motion.** Dragging still works and still maps one pixel to one pixel — it is an input method, not decoration. The inertial throw is suppressed, so the strip stops the instant the pointer is released instead of coasting.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Inventing a drag multiplier. It is correct for exactly one panel count and one container width; change either and the strip either outruns the hand or lags behind it, and the number gets re-tuned by eye forever.
- Accumulating per-move deltas instead of using the offset from the press point. Every clamp at the ends of the range silently swallows part of a delta, so the track drifts away from the hand and never comes back.
- Caching `trigger.end - trigger.start`. ScrollTrigger recomputes it on every refresh — a font swap or a resize — and a cached span makes the drag mapping wrong for the rest of the session.
- Decaying the throw with a per-frame constant (`v *= 0.95`). The throw travels less than half as far on a 120 Hz display, so the component feels different on different hardware.
- Setting `touch-action: none` on the drag surface. It kills native vertical scrolling over the whole pinned section, so on a phone the page appears frozen; `pan-y` keeps vertical scroll and hands over only the horizontal gesture.
- Not swallowing the click after a drag. Releasing over a panel fires that panel's click handler, so throwing the track opens whatever happened to be under the finger.

## Notes

- Designed to sit around `pinned-horizontal-track`, whose `onTrack` payload supplies both `trigger` and `getDistance`.
- Because the drag writes `scrollTop`, ScrollTrigger updates through its normal scroll listener — no manual `ScrollTrigger.update()` call, and no second source of truth for position.

## Definition of done

Press and drag left: the strip follows the pointer exactly, and a panel edge under your thumb stays under your thumb. Flick and release: it coasts and settles smoothly. Drag to either end and it stops flush with no rubber band. The progress rail matches the strip at all times, including while throwing. With reduced motion on, release stops it dead.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Drifting Smoke Layers

An absolutely-positioned atmosphere layer for the back of a hero or a card. Three oversized elements, each painting two soft radial gradients, blurred and drifting on periods that never line up. It looks like a rendered volumetric pass and costs three composited transforms.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Slow volumetric fog built from blurred radial gradients on three coprime cycles. No texture, no canvas.

- Category: primitive
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. Each layer is `position: absolute; inset: -25%`, making it 150% of the container in both axes with the excess hanging off every side. The layer can then translate by ±10% of its own box and scale to 1.55 without ever bringing an edge into the container — an exactly-fitting layer shows a hard corner the moment it moves.
2. A layer paints two `radial-gradient(W% H% at X% Y%, tint, transparent E%)` ellipses at different centres and different alphas. Two overlapping ellipses per layer, six across the stack, produce density variation that a single gradient cannot: the visible boundary between clouds is where two soft fields disagree, not where a gradient stops.
3. `filter: blur(40px | 55px | 70px)` erases the elliptical shape entirely and leaves only the density field. The three different radii are what separate the layers in apparent depth — identical blur reads as three copies of one cloud sliding over each other.
4. One `@keyframes kx-smoke-drift` block serves all layers. Its two poses read `translate(var(--kx-smoke-x0), var(--kx-smoke-y0)) scale(var(--kx-smoke-s0)) rotate(0deg)` and the matching `…-x1/-y1/-s1/-r`; custom properties resolve per element, so each layer walks a different path through the same cycle without a keyframe block of its own.
5. The periods are 16s, 22s and 29s. The combined pattern only repeats at lcm(16, 22, 29) = 5104 seconds, roughly 85 minutes, so no viewer will ever see it loop. Equal periods repeat every cycle and the fog reads as a looping video.
6. Only `transform` and `opacity` are animated. The blurred result of each layer is rasterised once and composited thereafter, so a 70px blur is paid for at paint time, not sixty times a second.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `inset = -25%`
  Makes each layer 150% of the container. Worst case is scale 1.55 plus a 10% self-relative translate plus an 11deg rotation; 25% of overflow on each side covers all three with room left. At -10% the corner of the largest layer swings into view during the rotation.
- `periods = 16s / 22s / 29s`
  Chosen so lcm(16, 22, 29) = 5104s. Any pair sharing a factor collapses the combined period — 16/24/32 repeats every 96 seconds and is clearly a loop. 29 is prime, which is what pushes the total past an hour.
- `blur radii = 40px / 55px / 70px`
  Different radii are the depth cue. Below ~25px the elliptical shape of the gradient survives the blur and the fog reads as coloured blobs; above ~90px the layer flattens into an even wash with no internal structure and the drift stops being visible.
- `layer opacities = 0.55 / 0.40 / 0.30`
  Descending with distance. The three layers composite multiplicatively against the background, so equal opacities stack to an opaque haze; the falloff keeps total coverage under about 0.75 and preserves whatever sits behind.
- `scale range = 1.25 to 1.55`
  The breathing. Under about 1.15 the scale change is imperceptible next to the translation; over about 1.8 the browser re-rasterises the blurred layer at the new scale, which shows as a visible sharpness pop mid-cycle.
- `gradient edge stops = 60% to 70%`
  Where each ellipse reaches full transparency, relative to its own size. Below ~50% the falloff is steep enough that the blur cannot hide the ellipse; at 100% the gradient never fully clears and the layer becomes a flat tint with a bright spot.

## API

```ts
function DriftingSmokeLayers(props: { layers?: 1 | 2 | 3; tint?: string; intensity?: number; speed?: number; className?: string }): JSX.Element
```

- `layers: 1 | 2 | 3` — default `3`
  How many layers to render. Fewer layers, less depth and less fill-rate.
- `tint: string` — default `'var(--smoke-tint, currentColor)'`
  Any CSS colour. Mixed down per blob with `color-mix`.
- `intensity: number` — default `1`
  Multiplies every layer opacity. Below 1 for fog behind text.
- `speed: number` — default `1`
  Multiplies every period. 2 is half speed; the periods stay coprime under any multiplier.
- `className: string`
  Merged onto the wrapper via `cn`. Use it to change the inset or add a mask.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/* Hand-tuned rather than seeded-random: these are the poses, not samples from
   a distribution, and a PRNG here would only make them harder to adjust. */
const LAYER_SPECS: readonly LayerSpec[] = [
  {
    durationS: 16,
    blurPx: 40,
    opacity: 0.55,
    fromX: '-8%',
    fromY: '-6%',
    fromScale: 1.25,
    toX: '10%',
    toY: '8%',
    toScale: 1.45,
    rotateDeg: 8,
    blobs: [
      { w: 40, h: 50, x: 70, y: 30, alpha: 55, edge: 60 },
      { w: 45, h: 55, x: 30, y: 65, alpha: 40, edge: 62 },
    ],
  },
  {
    durationS: 22,
    blurPx: 55,
    opacity: 0.4,
    fromX: '6%',
    fromY: '4%',
    fromScale: 1.3,
    toX: '-9%',
    toY: '-7%',
    toScale: 1.5,
    rotateDeg: -11,
    blobs: [
      { w: 55, h: 45, x: 25, y: 35, alpha: 45, edge: 64 },
      { w: 50, h: 60, x: 75, y: 70, alpha: 32, edge: 66 },
    ],
  },
  {
    durationS: 29,
    blurPx: 70,
    opacity: 0.3,
    fromX: '-4%',
    fromY: '7%',
    fromScale: 1.35,
    toX: '8%',
    toY: '-9%',
    toScale: 1.55,
    rotateDeg: 6,
    blobs: [
      { w: 60, h: 60, x: 50, y: 20, alpha: 38, edge: 68 },
      { w: 48, h: 52, x: 20, y: 80, alpha: 28, edge: 70 },
    ],
  },
];

const SMOKE_CSS = `
/* One keyframe block for every layer. The transform endpoints are read from
   custom properties, which are resolved per element, so each layer follows a
   different path through the same two-pose cycle. */
@keyframes kx-smoke-drift {
  0%, 100% {
    transform:
      translate(var(--kx-smoke-x0), var(--kx-smoke-y0))
      scale(var(--kx-smoke-s0))
      rotate(0deg);
  }
  50% {
    transform:
      translate(var(--kx-smoke-x1), var(--kx-smoke-y1))
      scale(var(--kx-smoke-s1))
      rotate(var(--kx-smoke-r));
  }
}

.kx-smoke {
  position: absolute;
  inset: 0;
  overflow: hidden;
  pointer-events: none;
  /* Cuts the layers out of the page's paint and layout tree entirely. Without
     it the browser considers the oversized blurred children when computing
     the ancestor's ink overflow on every frame. */
  contain: paint;
}

.kx-smoke-layer {
  position: absolute;
  /* 150% of the container in both axes. A layer that exactly fits would show
     a hard edge the instant it translates. */
  inset: -25%;
  background: var(--kx-smoke-bg);
  filter: blur(var(--kx-smoke-blur));
  opacity: var(--kx-smoke-opacity);
  animation: kx-smoke-drift var(--kx-smoke-dur) ease-in-out infinite;
  will-change: transform;
}

/* Reduced motion parks every layer on its 50% pose rather than its 0% pose.
   The 50% pose is the fuller, more composed frame; 0% is where the layers are
   most nearly stacked, which reads as a single flat wash. */
@media (prefers-reduced-motion: reduce) {
  .kx-smoke-layer {
    animation: none;
    will-change: auto;
    transform:
      translate(var(--kx-smoke-x1), var(--kx-smoke-y1))
      scale(var(--kx-smoke-s1))
      rotate(var(--kx-smoke-r));
  }
}
`;

/** Two offset ellipses per layer. Percentages keep it resolution-independent. */
function backgroundFor(spec: LayerSpec, tint: string): string {
  return spec.blobs
    .map(
      (b) =>
        `radial-gradient(${b.w}% ${b.h}% at ${b.x}% ${b.y}%, ` +
        `color-mix(in oklab, ${tint} ${b.alpha}%, transparent), transparent ${b.edge}%)`,
    )
    .join(', ');
}

export function DriftingSmokeLayers({
  layers = 3,
  tint = 'var(--smoke-tint, currentColor)',
  intensity = 1,
  speed = 1,
  className,
}: DriftingSmokeLayersProps) {
  return (
    <>
      <style href="kinetic-drifting-smoke-layers" precedence="medium">
        {SMOKE_CSS}
      </style>
      <div className={cn('kx-smoke', className)} aria-hidden="true">
        {LAYER_SPECS.slice(0, layers).map((spec) => {
          const style: StyleWithVars = {
            '--kx-smoke-bg': backgroundFor(spec, tint),
            '--kx-smoke-blur': `${spec.blurPx}px`,
            '--kx-smoke-opacity': spec.opacity * intensity,
            '--kx-smoke-dur': `${spec.durationS * speed}s`,
            '--kx-smoke-x0': spec.fromX,
            '--kx-smoke-y0': spec.fromY,
            '--kx-smoke-s0': spec.fromScale,
            '--kx-smoke-x1': spec.toX,
            '--kx-smoke-y1': spec.toY,
            '--kx-smoke-s1': spec.toScale,
            '--kx-smoke-r': `${spec.rotateDeg}deg`,
          };
          return <span key={spec.durationS} className="kx-smoke-layer" style={style} />;
        })}
      </div>
    </>
  );
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nothing to clean up. No listeners, no timers, no animation frames, no observers. Unmounting removes the elements and the CSS animations with them; React removes the hoisted `<style>` when the last instance unmounts.

**Reduced motion.** A `@media (prefers-reduced-motion: reduce)` block sets `animation: none` and applies each layer's 50% pose as a static transform, so the fog is still there, still layered, still at full density — it simply stops drifting. `will-change` is reset to `auto` in the same block so the three large blurred layers are not held in compositor memory for an animation that is not running.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Animating `filter: blur()` itself, or animating the gradient stops. Both force the layer to be re-blurred every frame — a 70px blur over a 150%-size layer is tens of milliseconds of GPU work per frame and the whole page drops to single-digit FPS. Animate the transform of an already-blurred layer instead.
- Giving the layers the same duration with different delays. A delay does not decorrelate anything: after the first cycle every layer is at the same phase offset forever, and the stack visibly repeats on the shared period. The periods themselves have to be coprime.
- Sizing the layers to the container. At `inset: 0` the blur samples transparent pixels beyond the element box, so the fog fades out at exactly the container edge and the effect reads as a rectangle of smoke rather than smoke seen through a window.
- Omitting `overflow: hidden` on the wrapper. The layers are 150% of the container by design and will paint over neighbouring content, including through a parent with its own background.
- Leaving off `pointer-events: none`. The layer covers the whole container, so every button underneath stops being clickable and the cause is invisible in the DOM inspector unless you notice the transparent sibling on top.
- Setting `will-change: transform` and leaving it set under reduced motion. `will-change` promotes the element to its own compositor layer permanently; with the animation switched off that is three large blurred textures held in GPU memory for nothing. The reduced-motion block resets it to `auto`.

## Notes

- The component is `position: absolute; inset: 0`, so it expects a positioned ancestor and contributes nothing to layout. Put it as the first child of the section it should sit behind and give that section `position: relative`.
- `contain: paint` on the wrapper keeps the oversized blurred children out of the ancestor ink-overflow calculation, which otherwise runs on every frame of the drift.
- The tint reads `var(--smoke-tint, currentColor)` and is mixed with `color-mix(in oklab, …)`, so the fog inherits the text colour by default and can be re-themed by setting one property on any ancestor. `color-mix` needs Safari 16.2+, Chrome 111+, Firefox 113+.
- Fill-rate is the real cost: three full-container layers at 150% size, blurred. On a low-end phone drop to `layers={2}` — the depth reads almost as well and it removes the widest blur.

## Definition of done

Watch for a full minute: the density pattern never obviously repeats, and no layer edge or gradient ellipse becomes visible at any point in the cycle. Content behind the smoke stays clickable. In a performance profile the frames show composite work only — no repaints of the blurred layers. With reduced motion on, the fog is still present and completely still.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Dual-Canvas Depth Split

Two stacked canvases render the same instanced particle system with opposite `uZSign`, and the page content is a DOM sibling between them. Particles with negative depth pass behind the text and positive ones pass in front. Because size, parallax rate, brightness and softness are one continuous ramp across the depth axis, the plane where the split happens cannot be seen — the effect is that the copy is embedded in the field, and it stays live, selectable text throughout.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

One particle field rendered twice with the depth sign flipped, so the text sits inside the field rather than on top of it.

- Category: webgl
- Runtime cost: webgl
- Dependencies: ogl@^1.0.11

## How it works

1. `aDepth` is the camera axis, not a distance: -1 is far behind the content plane, +1 is close to the viewer, 0 is the content plane itself. The SIGN chooses which canvas draws a particle; the magnitude drives everything else, which is why the two layers look like one field.
2. Both layers share the same typed arrays, so the two contexts hold identical particles rather than two independent fields. Only the attribute descriptor objects are per-layer, because ogl writes the buffer handle and element count into the object it is given.
3. A particle on the wrong side of the plane is rejected in the VERTEX shader by writing `gl_Position = vec4(2.0, 2.0, 2.0, 1.0)` — outside the frustum on every axis, so all four vertices are clipped before rasterisation and it costs no fragments. The vertex cost doubles across the two layers; the fragment cost, which is the only cost that mattered, does not.
4. Near particles are bigger (`mix(minSize, maxSize, depth01)`), drift further per second (`0.35 + 0.65 * depth01`), are brighter, and have a softer edge — a defocus that stops the front layer reading as dirt on the screen. Four cues from one number.
5. The back canvas is opaque and blends additively (`ONE, ONE`), which is order independent so nothing needs sorting. The front canvas sits over live text and must be transparent, which rules additive out — there is nothing on the GPU to add to — so it blends premultiplied source-over (`ONE, ONE_MINUS_SRC_ALPHA`). One fragment shader emits premultiplied colour and serves both.
6. The population is derived from container area — `clamp(round(megapixels * density), 250, maxCount)` — and applied with `setInstancedCount` on both layers. Buffers are allocated once at `maxCount`, so a resize never reallocates.
7. Drift is a pure function of `elapsed` and the per-particle seed, with `fract` wrapping the field vertically and `uFadeBand` fading alpha to zero at both ends so the wrap seam is never visible. No per-particle state, so a still frame is drawable from one number.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `split = 0.38`
  Fraction of the population placed in front of the content. Under a half on purpose: dust in front of body copy is a legibility cost, and at 0.5 the text reads as fogged rather than embedded.
- `FRONT_OPACITY = 0.55`
  Extra alpha scale on the front layer only. Depth already brightens near particles, and the front layer is entirely near particles, so without this the layer that overlaps the text is the brightest thing on screen.
- `DEPTH_FLOOR = 0.05`
  Dead zone around the content plane. A particle at exactly 0 is rejected by both layers — `aDepth * uZSign <= 0.0` is false for neither sign — so it would silently never render.
- `sizeRange = [3, 34]`
  Disc diameter at the far and near ends of the ramp. The span is what sells the depth; at 8-to-14 the field is flat, and above ~40 the near particles are large enough that their own softness becomes the dominant texture of the page.
- `parallax factor = 0.35 + 0.65 * depth01`
  Near particles travel about three times as far per second as far ones. A larger ratio makes the far layer look frozen; a smaller one and the field moves as a single sheet, which removes the only depth cue that survives in a static screenshot.
- `MAX_DPR = 1.5`
  Two layers of soft additive discs is a fill-rate problem and fill scales with the square of the pixel ratio. Dust has no detail a third sample per axis would resolve, so a 3x phone renders at 1.5x and pays a quarter of the fragments.
- `FADE_BAND = 0.14`
  Fraction of the field height the wrap fade occupies at each end. Larger than a single-layer field needs, because the near particles are up to 34px across and their radius alone is a few percent of a short container.
- `size jitter = 0.7 .. 1.3`
  Multiplier on top of the depth ramp. Without it the depth ordering is perfectly readable from size alone, which reads as a diagram of a depth field rather than a depth field.

## API

```ts
function DualCanvasZSplit(props: { children?: ReactNode; density?: number; maxCount?: number; split?: number; sizeRange?: readonly [number, number]; speed?: number; wander?: number; opacity?: number; colorA?: string; colorB?: string; background?: string; seed?: number | string; className?: string }): JSX.Element
```

- `children: ReactNode`
  Content rendered between the two particle layers. Ordinary DOM, fully interactive.
- `density: number` — default `850`
  Particles per megapixel of container area. The count is derived from this, not fixed.
- `maxCount: number` — default `1600`
  Population ceiling, and the size the shared buffers are allocated at.
- `split: number` — default `0.38`
  Fraction of the population placed in front of the content.
- `sizeRange: readonly [number, number]` — default `[3, 34]`
  Disc diameter in CSS pixels at the far and near ends of the depth ramp.
- `speed: number` — default `1`
  Multiplier on the whole drift, including the upward march.
- `wander: number` — default `0.05`
  Sinusoidal wander amplitude in field units, where 1 is the container.
- `opacity: number` — default `0.6`
  Overall alpha multiplier. The front layer takes 0.55 of it.
- `colorA: string` — default `'#8ea6c4'`
  First tint. Any value ogl's `Color` accepts.
- `colorB: string` — default `'#e6d9c4'`
  Second tint; each particle mixes between the two by a seeded amount.
- `background: string` — default `'#06080c'`
  Opaque clear colour of the back canvas. The front canvas is transparent.
- `seed: number | string` — default `'dual-canvas-z-split'`
  Seeds the scatter. Same seed, same field on every reload and on the server.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
function createLayer(
  host: HTMLElement,
  data: FieldData,
  opts: {
    zSign: number;
    opaque: boolean;
    background: Color;
    colorA: Color;
    colorB: Color;
    speed: number;
    wander: number;
    opacity: number;
    minSize: number;
    maxSize: number;
  },
): Layer {
  const renderer = new Renderer({
    dpr: pixelRatio(MAX_DPR),
    // The back layer owns its pixels, so it is opaque and can blend
    // additively. The front layer sits over live DOM text and must be
    // transparent, which rules additive out — there is nothing on the GPU to
    // add to. It blends premultiplied source-over instead.
    alpha: !opts.opaque,
    premultipliedAlpha: !opts.opaque,
    // Nothing occludes anything in either layer; the depth ORDER is expressed
    // by which canvas a particle lands on, not by a z-buffer.
    depth: false,
    antialias: false,
    powerPreference: 'low-power',
  });

  const gl = renderer.gl;
  const canvas = gl.canvas;

  if (opts.opaque) gl.clearColor(opts.background.r, opts.background.g, opts.background.b, 1);
  else gl.clearColor(0, 0, 0, 0);

  // Each layer needs its own attribute descriptors — ogl writes the buffer
  // handle and the element count into the object it is handed — but the
  // underlying typed arrays are shared, so the two contexts hold identical
  // particles rather than two independent fields.
  const geometry = new Geometry(gl, {
    index: { data: data.index },
    position: { size: 2, data: data.quad },
    aOrigin: { size: 2, data: data.origins, instanced: 1 },
    aDepth: { size: 1, data: data.depths, instanced: 1 },
    aSeed: { size: 4, data: data.seeds, instanced: 1 },
  });

  const uniforms: Uniforms = {
    uResolution: { value: [1, 1] },
    uPixelRatio: { value: renderer.dpr },
    uElapsed: { value: 0 },
    uZSign: { value: opts.zSign },
    uDrift: { value: opts.speed },
    uRise: { value: RISE },
    uFlowScale: { value: FLOW_SCALE },
    uWander: { value: opts.wander },
    uFadeBand: { value: FADE_BAND },
    uMinSize: { value: opts.minSize },
    uMaxSize: { value: opts.maxSize },
    uColorA: { value: opts.colorA },
    uColorB: { value: opts.colorB },
    uOpacity: { value: opts.opacity },
  };

  const program = new Program(gl, {
    vertex: DUAL_CANVAS_Z_SPLIT_VERT,
    fragment: DUAL_CANVAS_Z_SPLIT_FRAG,
    uniforms,
    transparent: true,
    depthTest: false,
    depthWrite: false,
    // ogl defaults `cullFace` to BACK, and a culled particle is absent with no
    // error anywhere. Nothing here has a back face worth culling.
    cullFace: false,
  });
  if (opts.opaque) program.setBlendFunc(gl.ONE, gl.ONE);
  else program.setBlendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);

  const mesh = new Mesh(gl, { geometry, program });

  host.appendChild(canvas);
  canvas.style.display = 'block';

  return { renderer, geometry, program, mesh, uniforms, canvas };
}

export function DualCanvasZSplit({
  children,
  density = 850,
  maxCount = 1600,
  split = 0.38,
  sizeRange = [3, 34],
  speed = 1,
  wander = 0.05,
  opacity = 0.6,
  colorA = '#8ea6c4',
  colorB = '#e6d9c4',
  background = '#06080c',
  seed = 'dual-canvas-z-split',
  className,
}: DualCanvasZSplitProps) {
  const host = useRef<HTMLDivElement>(null);
  const backHost = useRef<HTMLDivElement>(null);
  const frontHost = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  const { width, height } = useResizeObserver(host);
  const size = useRef({ width, height });
  size.current = { width, height };

  const reduced = useReducedMotion();
  const visible = useVisibility();
  const { inView } = useInView(host, { rootMargin: '10%' });
  const ready = width > 1 && height > 1;

  const [minSize = 3, maxSize = 34] = sizeRange;

  useEffect(() => {
    const back = backHost.current;
    const front = frontHost.current;
    if (!back || !front || !ready) return;

    if (!hasWebGL()) {
      setUnsupported(true);
      return;
    }

    const total = Math.max(MIN_COUNT, Math.round(maxCount));
    const data: FieldData = {
      quad: new Float32Array([-0.5, -0.5, 0.5, -0.5, 0.5, 0.5, -0.5, 0.5]),
      index: new Uint16Array([0, 1, 2, 0, 2, 3]),
      origins: new Float32Array(total * 2),
      depths: new Float32Array(total),
      seeds: new Float32Array(total * 4),
    };

    const rng = createRng(seed);
    const frontShare = clamp(split, 0, 1);
    const lo = Math.max(1, Math.min(minSize, maxSize));
    const hi = Math.max(lo + 0.5, Math.max(minSize, maxSize));

    for (let i = 0; i < total; i += 1) {
      data.origins[i * 2] = randRange(rng, X_MIN, X_MAX);
      data.origins[i * 2 + 1] = rng();

      // The sign picks the canvas, the magnitude drives size, parallax,
      // brightness and softness. A particle exactly at 0 would be on the
      // content plane and belongs to neither layer, so the range excludes it.
      const inFront = rng() < frontShare;
      data.depths[i] = inFront
        ? randRange(rng, DEPTH_FLOOR, 1)
        : -randRange(rng, DEPTH_FLOOR, 1);

      data.seeds[i * 4] = rng() * Math.PI * 2;
      data.seeds[i * 4 + 1] = rng() * Math.PI * 2;
      data.seeds[i * 4 + 2] = rng();
      // Size jitter on top of the depth ramp. Without it the depth ordering is
      // perfectly legible from size alone, which reads as a diagram.
      data.seeds[i * 4 + 3] = randRange(rng, 0.7, 1.3);
    }

    const colA = new Color(colorA);
    const colB = new Color(colorB);
    const bg = new Color(background);
    const shared = {
      background: bg,
      colorA: colA,
      colorB: colB,
      speed,
      wander,
      minSize: lo,
      maxSize: hi,
    };

    const layers = [
      createLayer(back, data, { ...shared, zSign: -1, opaque: true, opacity }),
      createLayer(front, data, {
        ...shared,
        zSign: 1,
        opaque: false,
        opacity: opacity * FRONT_OPACITY,
      }),
    ];

    const resize = (w: number, h: number) => {
      // Population from area, not a fixed number, so one density reads right in
      // a 320px card and a 2000px hero. The buffers already hold `total`
      // particles in scattered order, so a prefix is still an even field —
      // nothing is reallocated.
      const megapixels = (w * h) / 1_000_000;
      const count = clamp(Math.round(megapixels * density), MIN_COUNT, total);

      for (const layer of layers) {
        layer.renderer.setSize(w, h);
        // `setSize` writes literal px into the canvas's inline style, which
        // beats any class. Re-asserting percentages keeps it fluid.
        layer.canvas.style.width = '100%';
        layer.canvas.style.height = '100%';
        layer.uniforms.uResolution.value = [
          layer.renderer.gl.drawingBufferWidth,
          layer.renderer.gl.drawingBufferHeight,
        ];
        layer.uniforms.uPixelRatio.value = layer.renderer.dpr;
        layer.geometry.setInstancedCount(count);
      }
    };

    const draw = (elapsed: number) => {
      for (const layer of layers) {
        layer.uniforms.uElapsed.value = elapsed;
        layer.renderer.render({ scene: layer.mesh });
      }
    };

    resize(size.current.width, size.current.height);
    stage.current = { layers, resize, draw };
    draw(STATIC_ELAPSED);

    return () => {
      stage.current = null;
      for (const layer of layers) {
        // ogl has no `dispose()`: `remove()` deletes the VAOs and every buffer,
        // then the program and its shaders, and only `WEBGL_lose_context` gives
        // the context itself back. This component holds two of them.
        layer.geometry.remove();
        layer.program.remove();
        loseContext(layer.renderer.gl);
        layer.canvas.width = 0;
        layer.canvas.height = 0;
        layer.canvas.remove();
      }
    };
  }, [
    ready,
    density,
    maxCount,
    split,
    minSize,
    maxSize,
    speed,
    wander,
    opacity,
    colorA,
    colorB,
    background,
    seed,
  ]);

  // Resize is its own effect: a reflow costs two `setSize` calls and an
  // instanced-count change, never a rebuild of the shared buffers.
  useEffect(() => {
    stage.current?.resize(width, height);
    if (reduced) stage.current?.draw(STATIC_ELAPSED);
  }, [width, height, reduced]);

  useRaf(
    (_dt, elapsed) => stage.current?.draw(elapsed),
    ready && inView && visible && !reduced && !unsupported,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Per layer: `geometry.remove()` deletes the VAOs and every buffer, `program.remove()` deletes the shaders and the program, `loseContext(gl)` hands the context back through `WEBGL_lose_context` — ogl has no `dispose()` and nothing else releases a context — then the canvas backing store is zeroed and the node removed. Both layers are torn down in the same cleanup, so the component never holds one context after the other has gone.

**Reduced motion.** The rAF subscription is never made and both layers are drawn once at `elapsed` 0. That is a complete frame, not a collapsed one: the scatter, depths, sizes, tints and wrap fade are all per-particle seeds that already vary at t=0, so the still shows the same depth split, in front of and behind the same text, with only the drift absent. Resizing redraws the same still in both layers.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Trying to do this with one canvas. A canvas is a single stacking-context leaf, so DOM content cannot be interleaved with parts of it. Two contexts is not an inefficiency here, it is the requirement — and it is two of the roughly sixteen a Chromium renderer process allows, which is exactly why both are released on unmount.
- Making the front canvas additive. With `alpha: true` the destination is zero, so an additive particle over text is a flat colour patch: the layer stops looking like light and starts looking like a sticker.
- Forgetting `pointer-events: none` on the front layer. It covers the content by construction, so every link and button underneath it stops responding, and nothing about the failure looks graphical.
- Letting a particle sit at depth exactly 0. `aDepth * uZSign <= 0.0` rejects it in BOTH layers, so it is uploaded, transformed and never seen — a silent leak of the population.
- Rejecting with `discard` in the fragment shader instead of parking the vertex. `discard` still rasterises the quad and runs the shader per fragment; a clip-space position outside the frustum throws the primitive away after four vertex invocations.
- Writing `gl_Position = vec4(2.0)` for the rejection. w is then 2, the perspective divide brings it back to exactly 1.0 on every axis, and the vertex survives clipping at the frustum boundary — a row of specks in the corner.
- Giving both layers the same attribute descriptor objects. ogl mutates them with a buffer handle belonging to the first context, and the second layer then renders from a buffer its context has never heard of.
- Assuming `renderer.setSize` leaves the CSS alone. ogl writes literal px into the canvas inline style, which beats any class, so the percentages must be re-asserted after every call in both layers.

## Notes

- The content is a DOM sibling, not a texture. It stays selectable, focusable and available to a screen reader while particles pass on both sides of it — which is the entire reason to accept two contexts instead of drawing the text into the field.
- ogl rather than three: two contexts, two instanced meshes, no lights, no cameras and no scene graph. `renderer.render` is called without a camera, so ogl skips frustum culling and the matrix uniforms — the shader writes clip space itself.
- `depth: false` on both contexts. The depth ORDER is expressed by which canvas a particle lands on, so a z-buffer would be memory plus a clear per frame for no result.
- Sizes are authored in CSS pixels and scaled by the pixel ratio in the shader, so the field is identical across a dpr change and nothing rebuilds when one happens.
- GLSL ES 1.00 with no derivative functions — the anti-aliasing floor is `1.0 / sizePx`, exact for a quad of that pixel size — so the same source compiles under a WebGL1 fallback context.

## Definition of done

Particles visibly pass both behind and in front of the text, and the text is still selectable with the mouse while they do. There is no horizontal line anywhere in the container where the field changes character. Near particles are larger, softer and move further per second than far ones. Links inside the content still respond to hover and click. Resize narrow and wide: discs stay circular and the population changes without a stutter. Two contexts per instance, both released on unmount — mount and unmount six instances and none of the earlier ones go black.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Dual-Direction Scrub Entrance

Two elements arrive on the same scrubbed trigger from different directions — the copy rises 60px, the panel slides in from the side by 55% of its own width. Because both tweens sit at position 0 of one timeline, their progress is identical at every scroll position, so the pair reads as one composed arrival. The 0.6s scrub lets them keep moving briefly after the wheel stops, which is the difference between weighted and welded.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Copy rises while a panel slides in from the side, both on one scrub with 600ms of lag.

- Category: scroll
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. A single `gsap.timeline` is created with `scrollTrigger: { trigger: root, start: "top 82%", end: "top 38%", scrub: 0.6 }`. One trigger drives both elements, so there is exactly one progress value in the system.
2. The primary element gets `fromTo({ autoAlpha: 0, y: 60 }, { autoAlpha: 1, y: 0 })` at position 0. `autoAlpha` rather than `opacity`: it also flips `visibility`, so the invisible element is not a click target on the way in.
3. The secondary gets `fromTo({ autoAlpha: 0, xPercent: ±55 }, { autoAlpha: 1, xPercent: 0 })`, also at position 0. `xPercent` is a share of its own width, so the entrance distance scales with the layout instead of being tuned per breakpoint.
4. Both tweens use `ease: "none"`. Under a scrub the ease is applied to timeline time, so easing here means the two elements travel at different rates through the same scroll range and stop looking like one gesture.
5. The secondary is wrapped in an `overflow-hidden` cell. At `xPercent: 55` it begins more than half its width outside the grid column, which without the clip is a horizontal scrollbar on the whole document.
6. `scrub: 0.6` gives ScrollTrigger 0.6s to catch the timeline up to the scroll position, so the elements decelerate into place after the wheel stops rather than freezing with it.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `scrub = 0.6`
  Seconds of catch-up. `true` (zero lag) welds the animation to the wheel and reads as dragging a slider. Past about 1.5s the section is still arriving long after you have stopped, which reads as lag rather than weight. 0.6 is the point where it feels like mass.
- `start / end = 'top 82%' / 'top 38%'`
  The section begins arriving just as it clears the bottom edge and is fully composed while still in the lower half of the screen. Ending at `top 38%` means the entrance completes before the content reaches the reading position — an animation that is still resolving under the eye is unreadable.
- `rise = 60`
  Pixels of vertical travel for the copy. Enough to register as arriving; small enough that the text is legible for most of the transit, which matters because the user is reading during it.
- `slide = 55`
  Percent of the secondary's own width. Above ~60% it starts entirely outside its column and the first half of the scrub shows an empty cell; below ~30% it reads as a nudge rather than an entrance.

## API

```ts
function DualDirectionScrubEntrance(props: { primary: ReactNode; secondary: ReactNode; from?: "left" | "right"; rise?: number; slide?: number; scrub?: number; start?: string; end?: string; scrollerRef?: RefObject<HTMLElement | null>; className?: string }): JSX.Element
```

- `primary: ReactNode`
  Rises from below. The reading anchor — usually the copy.
- `secondary: ReactNode`
  Slides in horizontally. Usually the card, figure or panel.
- `from: "left" | "right"` — default `'right'`
  Which edge the secondary enters from. Also flips the grid order.
- `rise: number` — default `60`
  Pixels the primary rises through.
- `slide: number` — default `55`
  Secondary travel as a percentage of its own width.
- `scrub: number` — default `0.6`
  Seconds of catch-up behind the scroll position.
- `start: string` — default `'top 82%'`
  ScrollTrigger start.
- `end: string` — default `'top 38%'`
  ScrollTrigger end.
- `scrollerRef: RefObject<HTMLElement | null>`
  The scroll container that owns the scroll position. Omit for the document.
- `className: string`
  Merged onto the grid container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function DualDirectionScrubEntrance({
  primary,
  secondary,
  from = 'right',
  rise = 60,
  slide = 55,
  scrub = 0.6,
  start = 'top 82%',
  end = 'top 38%',
  scrollerRef,
  className,
}: DualDirectionScrubEntranceProps) {
  const root = useRef<HTMLDivElement>(null);
  const primaryRef = useRef<HTMLDivElement>(null);
  const secondaryRef = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();

  useGsap(
    gsap,
    () => {
      const container = root.current;
      const a = primaryRef.current;
      const b = secondaryRef.current;
      if (!container || !a || !b || reduced) return;

      const tl = gsap.timeline({
        scrollTrigger: {
          trigger: container,
          scroller: scrollerRef?.current ?? undefined,
          start,
          end,
          // The number, not `true`. `true` welds the timeline to the wheel and
          // the section stops moving in the same millisecond the wheel does.
          scrub,
          invalidateOnRefresh: true,
        },
      });

      // `fromTo`, deliberately, and not `from`. A `from` tween on a scrubbed
      // trigger renders its start state immediately at build time and then
      // treats the element's *current* values as the destination — so a second
      // tween, a resize, or React re-applying a style mid-scroll silently
      // rewrites where the animation is heading. Stating both ends makes the
      // timeline idempotent.
      tl.fromTo(
        a,
        { autoAlpha: 0, y: rise },
        { autoAlpha: 1, y: 0, ease: 'none', duration: 1 },
        0,
      );

      tl.fromTo(
        b,
        { autoAlpha: 0, xPercent: from === 'right' ? slide : -slide },
        { autoAlpha: 1, xPercent: 0, ease: 'none', duration: 1 },
        // Position 0: both tweens share one progress value. Offsetting them
        // would make the pair read as a queue instead of a single arrival.
        0,
      );
    },
    root,
    [from, rise, slide, scrub, start, end, reduced],
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useGsap` builds the timeline inside a `gsap.context` and reverts it on unmount or any prop change. The revert kills the ScrollTrigger and restores the inline `transform`, `opacity` and `visibility` the tweens wrote — without it an unmount mid-scrub leaves the panel permanently half-slid and invisible if React reuses the node.

**Reduced motion.** No timeline and no trigger are created, so both elements render in their final layout position at full opacity on first paint. Nothing is hidden waiting for a scroll that the user may never make.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- `gsap.from()` on a scrubbed trigger. It renders the start state immediately at build time and treats whatever the element's values happen to be as the destination — so any later style change silently rewrites the target and the element ends up somewhere other than where the layout says. `fromTo` states both ends and is idempotent under a scrub.
- Two separate ScrollTriggers, one per element. Their start positions are computed from their own bounding boxes, so on a tall screen the copy is already finished before the panel has begun, and the composition falls apart at exactly the viewport heights you did not test.
- Easing a scrubbed tween. The ease is applied to timeline time, so the two elements move at different rates through the same scroll window and the pair stops reading as one gesture. Use `ease: "none"` and let the scrub supply the smoothing.
- No `overflow-hidden` around the sliding element. At `xPercent: 55` it sits outside its column at the start of the scrub, which extends the document width and adds a horizontal scrollbar that appears and disappears as you scroll.
- Using `opacity` instead of `autoAlpha`. The invisible element still receives pointer events, so a link inside a panel that has not arrived yet is clickable and focusable.
- Omitting `invalidateOnRefresh`. `xPercent` and the trigger boundaries are both derived from measurements taken at build time; after a resize the panel travels the wrong distance and starts at the wrong scroll position.

## Notes

- `from="left"` also reverses the grid order, so the panel enters from the side it visually occupies rather than crossing the copy on its way in.
- The `will-change-transform` hints sit on the two moving wrappers rather than on their contents, so the promoted layer is created once and the children are not each given their own.

## Definition of done

Scroll the section up from the bottom: the copy rises and the panel comes in from the right at exactly the same rate, both finishing together before the section reaches the middle of the screen. Stop the wheel mid-entrance and they keep moving for about half a second before settling. Scroll back down and the entrance reverses. No horizontal scrollbar appears at any point. With reduced motion on, the section is composed and static from the start.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Eased Number Counter

A number tweens from one value to another on `power2.inOut` rather than linearly, so it reads as loading rather than as a progress meter — slow to commit, quick through the middle, easing onto the final figure. The thing being tweened is a plain numeric object; the string on screen is formatted from it on every update and written with `textContent`, so React never re-renders while the count runs. A transparent sizer reserves the width of the wider endpoint, so nothing after the counter moves as digits are added.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A statistic that counts up on an eased curve and settles on its exact final figure without shifting the layout.

- Category: text
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. A local object `{ v: from }` is the tween target. `gsap.to(counter, { v: to, duration, ease })` interpolates the number; the DOM is not the tween target at all.
2. `onUpdate` calls a `write()` closure that does `el.textContent = prefix + format.format(counter.v) + suffix`. Writing `textContent` rather than React children means the tween never touches the reconciler.
3. The `Intl.NumberFormat` is built once in a `useMemo` keyed on `[locale, decimals, grouping]` — three primitives, so the memo actually holds. `minimumFractionDigits === maximumFractionDigits` also performs the rounding, so no `Math.round` or `toFixed` is needed in the tick.
4. `onComplete` assigns `counter.v = to` and writes once more. Tween interpolation lands on values like 99.999999997, and a headline number stopping one unit short of itself is a real bug report.
5. Before the tween starts, `write()` runs once with `v = from`, so the live node is never empty on the first frame and the element does not pop into existence when the tween begins.
6. The width reservation compares `format.format(to).length` against `format.format(from).length` and renders the longer of the two as a `text-transparent` cell stacked under the live node in an `inline-grid`, both at `col-start-1 row-start-1`.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `DURATION = 1.6`
  Seconds. Under ~1s the eye cannot track the digits and the effect is just a flicker before the answer; past ~2.5s the reader has finished the sentence around it and is waiting on a number that has stopped being interesting.
- `EASE = 'power2.inOut'`
  The in-out pair is what separates a counter from a progress bar. `none` reads as a machine metering out a value; `power2.out` starts at full speed and looks like it began before you looked. The slow start is the part that reads as "committing".
- `VIEW_THRESHOLD = 0.6`
  60% of the element visible before counting. A stat that starts at 1% visibility has finished before it clears the fold, so the reader arrives at a static number and never sees the effect.
- `decimals = 0`
  Also the rounding rule, via matched `minimumFractionDigits`/`maximumFractionDigits`. Leaving them unmatched lets `Intl` vary the digit count between frames, so the string length oscillates and the number jitters horizontally.

## API

```ts
function EasedNumberCounter(props: { to: number; from?: number; duration?: number; ease?: string; delay?: number; locale?: string; decimals?: number; grouping?: boolean; prefix?: string; suffix?: string; startOnView?: boolean; className?: string; onComplete?: () => void }): JSX.Element
```

- `to: number`
  The value to land on.
- `from: number` — default `0`
  The value to start from.
- `duration: number` — default `1.6`
  Seconds of counting.
- `ease: string` — default `'power2.inOut'`
  Any GSAP ease string. `none` makes it read as a meter.
- `delay: number` — default `0`
  Seconds to wait after the trigger before counting.
- `locale: string`
  BCP 47 tag. Omitted uses the runtime default locale.
- `decimals: number` — default `0`
  Fixed fraction digits. Also the rounding.
- `grouping: boolean` — default `true`
  Thousands separators.
- `prefix: string` — default `''`
  Literal text before the number, e.g. a currency sign.
- `suffix: string` — default `''`
  Literal text after the number, e.g. a percent sign.
- `startOnView: boolean` — default `true`
  Count when scrolled into view rather than on mount.
- `className: string`
  Merged onto the outer span via `cn`.
- `onComplete: () => void`
  Fired once the final figure is written.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const DURATION = 1.6;
const EASE = 'power2.inOut';
const VIEW_THRESHOLD = 0.6;

export function EasedNumberCounter({
  to,
  from = 0,
  duration = DURATION,
  ease = EASE,
  delay = 0,
  locale,
  decimals = 0,
  grouping = true,
  prefix = '',
  suffix = '',
  startOnView = true,
  className,
  onComplete,
}: EasedNumberCounterProps) {
  const root = useRef<HTMLSpanElement>(null);
  const live = useRef<HTMLSpanElement>(null);
  const reduced = useReducedMotion();
  const { inView } = useInView(root, { threshold: VIEW_THRESHOLD, once: true });

  // Held in a ref so an inline arrow from the caller does not restart the
  // count on every parent render.
  const complete = useRef(onComplete);
  complete.current = onComplete;

  // One formatter for the whole tween, keyed only on the primitives that
  // change it. An options *object* prop would be a new reference every render
  // and would rebuild the formatter — and restart the tween — continuously.
  const format = useMemo(
    () =>
      new Intl.NumberFormat(locale, {
        minimumFractionDigits: decimals,
        maximumFractionDigits: decimals,
        useGrouping: grouping,
      }),
    [locale, decimals, grouping],
  );

  useEffect(() => {
    const el = live.current;
    if (!el) return;

    const counter = { v: from };
    const write = () => {
      el.textContent = `${prefix}${format.format(counter.v)}${suffix}`;
    };

    // Reduced motion is the final figure, immediately — not a blank slot and
    // not a 0.01s tween that still flickers through every intermediate value.
    if (reduced) {
      counter.v = to;
      write();
      complete.current?.();
      return;
    }

    write();
    if (startOnView && !inView) return;

    const tween = gsap.to(counter, {
      v: to,
      duration,
      ease,
      delay,
      overwrite: true,
      onUpdate: write,
      onComplete: () => {
        // Snap to the exact target. Floating-point tweens land on
        // 99.99999999 often enough that a counter visibly stopping one short
        // of its own headline number is a real bug report.
        counter.v = to;
        write();
        complete.current?.();
      },
    });

    return () => {
      tween.kill();
    };
  }, [
    from,
    to,
    duration,
    ease,
    delay,
    prefix,
    suffix,
    format,
    reduced,
    inView,
    startOnView,
  ]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The effect returns `tween.kill()`. Because the tween target is a local object rather than a DOM node, nothing is left written to the element beyond the final string, and there are no inline styles to clear.

**Reduced motion.** Writes the final formatted figure immediately and fires `onComplete`, with no tween created at all. It is never left blank and never runs a shortened tween that still flickers through intermediate values.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Constructing `new Intl.NumberFormat()` inside `onUpdate`. It costs tens of microseconds and it is being built 60-120 times a second per counter; a page of eight stats spends milliseconds a frame building formatters it throws away.
- Tweening the string, or holding the value in `useState`. A `setState` per frame re-renders the subtree at display refresh rate, and worse, any unrelated parent render snaps the number back to the last committed value mid-count.
- Rendering the live value as React children. React will diff and overwrite whatever the tween wrote, so the count freezes on the first parent re-render.
- Not snapping to the exact target in `onComplete`. Floating-point interpolation lands near, not on, the target — the counter finishes at 99,999 instead of 100,000.
- Letting the box size itself from the current text. Every added digit widens the element and shoves the following copy sideways; the count ends up looking like a layout bug.
- Using `visibility: hidden` for the sizer. That removes it from the accessibility tree as well, and the transparent copy is the only readable text on the element — the live node is `aria-hidden` because it is mid-count garbage.

## Notes

- The `onComplete` callback is held in a ref that is reassigned on every render, so passing an inline arrow from the caller does not restart the count on every parent render.
- A number formatting *options object* prop was deliberately not exposed: an object literal is a new reference every render, which would rebuild the formatter, invalidate the effect, and restart the tween continuously.

## Definition of done

Scroll the stat into view: the number counts from its start value, decelerates, and stops on exactly the stated figure — check the last digit. Nothing to the right of the number moves while it counts. Enable reduced motion, reload, and the final figure is present on first paint. Force a parent re-render mid-count and the number keeps counting rather than snapping backwards.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Exit Warp Before Navigate

Choosing a destination does not navigate. It plays an exit: the DOM chrome lifts and fades, the ring of cards is shoved thirty slots forward while its vertical spacing explodes and its radius collapses, the planes dissolve in index order, and only after one settle frame does the router move. The ease is expo.in, so almost nothing happens for the first half-second and then everything happens at once.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A ring of cards tears itself apart and rushes past the camera, and only then does the route change.

- Category: transition
- Runtime cost: webgl
- Dependencies: three@^0.185.1, gsap@^3.15.0

## How it works

1. Four scalars describe the ring — `position`, `spacing`, `hSpacing`, `radius` — and one `layout()` reads them: `angle = wrappedOffset(i, position, count) * (2*PI/count) * hSpacing`, then `mesh.position.set(sin(angle) * radius, offset * spacing * 0.12, cos(angle) * radius - radius)` and `mesh.rotation.y = angle`. Idle and exit both drive the same function, so no second code path can disagree about where a card belongs.
2. Idle rotation is `position += dt * 0.16` inside `setAnimationLoop`, with `dt` in seconds clamped to 50 ms — a per-frame constant would spin twice as fast on a 120 Hz display.
3. On select, a timeline fades the chrome (`opacity: 0, y: -20, 0.5s, power2.out, stagger 0.05`) and a `tl.call` pinned at an absolute 0.4s starts the warp, so the ring begins moving 0.1s before the text has finished leaving.
4. The warp is one `gsap.to` on the scalar object: `position + 30`, `spacing 0.8 -> 10`, `hSpacing 1 -> 3`, `radius 2.3 -> 0.6`, 1.4s, `expo.in`, with `onUpdate` calling `layout()`. Radius shrinking while spacing explodes is what makes the planes leave in different directions instead of receding as a group.
5. Each material tweens `opacity: 0` over 1s with `delay: 0.03 * i`, so the ring dissolves in index order rather than as a single fade.
6. The tween's `onComplete` sets a 50 ms timeout, and only that timeout calls `onNavigate`. Textures are canvas-drawn gradients with the item label baked in, so the component ships without a single image.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `duration = 1.4`
  Seconds of warp. With expo.in the perceived length is roughly half the real one; below ~1.1s the accelerating half is too brief to register and it reads as a cut, above ~1.8s the destination feels withheld.
- `shove = 30`
  Ring slots travelled during the exit. For a six-item ring that is five full revolutions — enough that individual cards stop being trackable and the ring reads as a blur rather than as a carousel scrubbing.
- `WARP_CUE = 0.4`
  Absolute seconds at which the scene warp starts, against a 0.5s chrome fade. The 0.1s overlap fuses two moves into one gesture; at 0.5 they read as sequential steps, and at 0 the ring pulls the eye off the text before it has gone.
- `FADE_STAGGER = 0.03`
  Seconds between per-card dissolves. 30 ms x 6 cards is 180 ms of sweep — visible as a direction, short enough that the last card still fades inside the warp.
- `SETTLE_MS = 50`
  GSAP fires onComplete on the same frame the tween ends, before that frame is presented. Navigating there shows one frame of the un-warped ring. One extra tick guarantees the final layout has been painted.
- `WARP_SPACING / WARP_RADIUS = 10 / 0.6`
  Vertical gap goes 0.8 -> 10 while radius goes 2.3 -> 0.6. Spreading without shrinking looks like a zoom out; shrinking without spreading looks like a dolly. Both together are the only combination that reads as the ring tearing apart around the camera.
- `IDLE_SPEED = 0.16`
  Ring slots per second at rest. One card takes about six seconds to reach the front — slow enough to read as ambience, fast enough that the ring is never mistaken for a static image.

## API

```ts
function ExitWarpNavigation(props: { items: { id: string; label: string }[]; onNavigate: (id: string) => void; children?: ReactNode; duration?: number; shove?: number; className?: string }): JSX.Element
```

- `items: { id: string; label: string }[]`
  Destinations. One card and one nav button each; the label is drawn into the card texture.
- `onNavigate: (id: string) => void`
  Called after the warp and its settle frame. Do the router push here.
- `children: ReactNode`
  Chrome over the canvas. Descendants marked `data-warp-chrome` fade and lift first.
- `duration: number` — default `1.4`
  Warp length in seconds.
- `shove: number` — default `30`
  Ring slots the drum travels during the warp.
- `className: string`
  Merged onto the positioned wrapper.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
useEffect(() => {
  const el = host.current;
  if (!el) return;

  // Checked in an effect, never during render: `hasWebGL()` needs `document`
  // and returning different markup on the server than on the client is a
  // hydration mismatch, not a graceful degradation.
  if (!hasWebGL() || reduced) {
    setFallback(true);
    return;
  }
  setFallback(false);

  const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
  renderer.setPixelRatio(pixelRatio(2));
  renderer.setClearAlpha(0);
  el.appendChild(renderer.domElement);
  renderer.domElement.style.cssText = 'display:block;width:100%;height:100%';

  const scene = new THREE.Scene();
  const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 60);

  const geometry = new THREE.PlaneGeometry(1, CARD_H / CARD_W);
  const meshes: THREE.Mesh<THREE.PlaneGeometry, THREE.MeshBasicMaterial>[] = [];
  const textures: THREE.CanvasTexture[] = [];

  items.forEach((item, i) => {
    const texture = new THREE.CanvasTexture(drawCard(item.label, i, items.length));
    texture.colorSpace = THREE.SRGBColorSpace;
    textures.push(texture);
    const material = new THREE.MeshBasicMaterial({ map: texture, transparent: true });
    const mesh = new THREE.Mesh(geometry, material);
    scene.add(mesh);
    meshes.push(mesh);
  });

  const state: Warp = {
    position: 0,
    spacing: REST_SPACING,
    hSpacing: 1,
    radius: REST_RADIUS,
  };

  /* One layout function, driven by four scalars. The idle loop and the exit
     tween both call it; there is no second code path that could disagree
     about where a card belongs. */
  const layout = () => {
    const count = meshes.length;
    const step = count > 0 ? (Math.PI * 2) / count : 0;
    for (let i = 0; i < count; i += 1) {
      const mesh = meshes[i];
      if (!mesh) continue;
      const offset = wrappedOffset(i, state.position, count);
      const angle = offset * step * state.hSpacing;
      mesh.position.set(
        Math.sin(angle) * state.radius,
        offset * state.spacing * Y_PER_SLOT,
        Math.cos(angle) * state.radius - state.radius,
      );
      mesh.rotation.y = angle;
    }
  };

  const resize = () => {
    const w = el.clientWidth;
    const h = el.clientHeight;
    if (w === 0 || h === 0) return;
    renderer.setSize(w, h, false);
    camera.aspect = w / h;
    // Pull the camera back on narrow boxes so the ring never grows wider
    // than the frame; a fixed z crops the front card on a phone.
    camera.position.z = 3.2 * Math.max(1, 1.35 / camera.aspect);
    camera.updateProjectionMatrix();
  };

  const observer = new ResizeObserver(resize);
  observer.observe(el);
  resize();
  layout();

  let last = 0;
  renderer.setAnimationLoop((time) => {
    const dt = last === 0 ? 0 : Math.min((time - last) / 1000, 0.05);
    last = time;
    const b = bundle.current;
    if (b && !b.exiting) {
      // Seconds, not frames: a per-frame increment idles twice as fast on a
      // 120 Hz display as it does on 60 Hz.
      state.position += dt * IDLE_SPEED;
      layout();
    }
    renderer.render(scene, camera);
  });

  bundle.current = { renderer, scene, camera, geometry, meshes, textures, state, exiting: false };

  return () => {
    observer.disconnect();
    gsap.killTweensOf(state);
    for (const mesh of meshes) gsap.killTweensOf(mesh.material);
    // disposeRenderer stops the animation loop first: a queued frame that
    // renders into a context we just released throws out of cleanup.
    disposeRenderer(renderer);
    for (const mesh of meshes) mesh.material.dispose();
    for (const texture of textures) texture.dispose();
    geometry.dispose();
    renderer.domElement.remove();
    bundle.current = null;
  };
  // `ids` stands in for `items` so a caller passing a fresh array literal
  // every render does not rebuild the whole scene each time.
  // eslint-disable-next-line react-hooks/exhaustive-deps
}, [ids, reduced]);

const start = useCallback(
  (id: string) => {
    const b = bundle.current;
    const chromeEl = chrome.current;

    // Re-entrancy guard. Without it a double click starts two warps that
    // tween the same scalars in opposite directions and the ring jitters.
    if (b?.exiting) return;

    const chromeTargets = chromeEl
      ? Array.from(chromeEl.querySelectorAll<HTMLElement>('[data-warp-chrome]'))
      : [];

    if (!b) {
      // No GL: the static crossfade. Same shape, no warp.
      const target = chromeTargets.length > 0 ? chromeTargets : chromeEl;
      if (target) {
        gsap.to(target, {
          opacity: 0,
          duration: reduced ? 0.15 : 0.3,
          ease: 'power2.out',
          onComplete: () => navigate.current(id),
        });
      } else {
        navigate.current(id);
      }
      return;
    }

    b.exiting = true;
    const state = b.state;

    const tl = gsap.timeline();
    if (chromeTargets.length > 0) {
      tl.to(chromeTargets, {
        opacity: 0,
        y: -20,
        duration: CHROME_DURATION,
        ease: 'power2.out',
        stagger: CHROME_STAGGER,
      });
    }

    // Absolute position: the warp starts 0.1 s before the chrome finishes
    // leaving, so the two overlap into one gesture instead of reading as
    // "text goes, then something else happens".
    tl.call(
      () => {
        gsap.to(state, {
          position: state.position + shove,
          spacing: WARP_SPACING,
          hSpacing: WARP_HSPACING,
          radius: WARP_RADIUS,
          duration,
          ease: 'expo.in',
          onComplete: () => {
            // One more frame before the route changes. GSAP's onComplete
            // fires on the same frame the tween ends, so navigating here
            // shows a single frame of the un-warped ring.
            const t = setTimeout(() => navigate.current(id), SETTLE_MS);
            timers.current.push(t);
          },
        });
        for (let i = 0; i < b.meshes.length; i += 1) {
          const mesh = b.meshes[i];
          if (!mesh) continue;
          gsap.to(mesh.material, {
            opacity: 0,
            duration: 1,
            ease: 'power2.in',
            delay: FADE_STAGGER * i,
          });
        }
      },
      undefined,
      WARP_CUE,
    );
  },
  [duration, shove, reduced],
);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Disconnects the ResizeObserver, kills the tweens on the scalar object and on every material, clears the pending navigation timeout, calls `disposeRenderer` (which stops the animation loop, disposes, forces context loss and zeroes the canvas), then disposes every material, texture and the shared geometry, and removes the canvas element.

**Reduced motion.** No WebGL context is created. The same cards render as a static CSS-gradient grid, and choosing one fades the chrome over 0.15s before navigating — the transition still covers the swap, it just does not move.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Calling `router.push` in the click handler and animating afterwards. React unmounts the canvas as the route resolves, so the warp plays for two frames and then disappears; the navigation must be the last step, inside the tween's completion.
- No re-entrancy guard. A double click starts two warps tweening the same four scalars from different origins — the ring jitters and the second navigation fires into an already-unmounting tree.
- Navigating in `onComplete` instead of one tick later. The final frame has not been presented, so a single frame of the intact ring flashes just before the route changes.
- Calling `renderer.dispose()` and stopping there. The GL context stays alive; Chromium kills the oldest context once about sixteen exist, so an unrelated canvas elsewhere on the page goes black. `disposeRenderer` also calls `forceContextLoss()` and zeroes the backing store.
- Leaving the exit tweens running through unmount. They keep writing to disposed materials and to a scalar object nobody reads; the material writes throw once the context is gone. Cleanup kills the tweens on the state object and every material before disposing.
- Deciding whether WebGL exists during render. `hasWebGL()` needs `document`, so it returns false on the server and true on the client, and the two renders disagree — the check runs in an effect and flips to the static fallback afterwards.
- Advancing the idle rotation by a per-frame constant. The ring idles at double speed on a 120 Hz laptop, which is exactly the sort of bug that never reproduces on the developer's machine.

## Notes

- App Router wiring: `onNavigate={(id) => router.push(`/work/${id}`)}`. Call `router.prefetch` on hover (see `hover-prefetch-wipe`) so the 1.4s warp is spent downloading the destination rather than waiting after it.
- Reduced motion and no-WebGL share one path: a static grid of the same cards, a 0.3s fade of the chrome, then navigate. No context is ever created in that branch.
- The ring is index-driven, not raycast-driven. Picking is done with real DOM buttons over the canvas, which keeps the nav keyboard-reachable and screen-reader-legible for free.

## Definition of done

The ring idles at the same speed on a 60 Hz and a 120 Hz display. Choosing a destination fades the caption, then the ring barely moves for about half a second before tearing outward and past the camera; the new route appears only once the frame is empty, with no flash of the intact ring. Unmount mid-warp and the console stays clean.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Font-Safe Text Splitting

Splitting text into lines is a measurement, and measuring before the webfont arrives measures the fallback face. The line boxes are then wrapped in the wrong places and never re-flow when the real font swaps in — with a line mask, the visible symptom is words sliced in half by an invisible edge, and it only reproduces on a cold cache. This component owns the whole lifecycle: gate the first split on `document.fonts.ready`, re-split when a late font finishes loading, and re-split on width change behind a debounce.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Line splitting gated on document.fonts.ready, re-split on late fonts and on width change, debounced.

- Category: text
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. The first split is deferred behind `document.fonts.ready`, so the browser has finished laying out with the real faces before any line box is measured.
2. A `loadingdone` listener on `document.fonts` re-applies the split. Fonts requested after first paint — a lazily mounted section, a second weight, an icon face — trigger another layout pass that moves the line breaks under wrappers that were already fixed.
3. A `ResizeObserver` on the container re-applies the split behind a `debounceMs` timer. Line breaks are a function of container width and nothing else recomputes them; without this, rotating a phone leaves the wrappers describing a layout that no longer exists.
4. The resize guard compares `Math.round(entry.contentRect.width)` against the last value and returns when they match. On iOS the URL bar collapsing changes viewport *height* and fires resize; re-splitting there destroys and rebuilds the DOM mid-scroll for no benefit, on the device least able to spare the frames.
5. `apply()` always tears down first — `ctx.revert()` then `split.revert()` — so a re-split never nests one set of line wrappers inside the previous set. Nesting is what turns three re-splits into a paragraph wrapped nine deep.
6. A `revealed` flag is set by the ScrollTrigger `onEnter`. After the entrance has played, a re-split writes `gsap.set(lines, { yPercent: 0, opacity: 1 })` instead of `gsap.from(...)`, so rotating the device does not replay the entrance from off-screen.
7. `ScrollTrigger.refresh()` runs after every split, because wrapping lines changes this element's height and every trigger positioned below it is now measuring against stale coordinates.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `DEBOUNCE_MS = 200`
  Milliseconds of quiet after the last resize before re-splitting. A split is a full teardown and rebuild of the subtree; running it per resize event during a window drag rebuilds it dozens of times a second. Below ~120ms a drag still triggers repeatedly; past ~350ms the text is visibly broken while the user waits.
- `Y = 110`
  Percent of a line's own height it starts below the mask. Past 100 rather than at it, because the mask clips to the line box and descenders otherwise peek below the mask edge on the first frame.
- `DURATION = 0.9`
  Seconds per line. `power3.out` needs this much room for its deceleration to read; below ~0.5s the curve flattens and lines snap into place.
- `STAGGER = 0.09`
  Seconds between lines. Roughly a tenth of the duration, so several lines are always rising together and the block reads as one mass rather than as a queue.
- `START = 'top 88%'`
  The reveal fires as the block's top edge clears the bottom eighth of the viewport — after it is unambiguously on screen, but before the reader has arrived at it.
- `width comparison = Math.round(contentRect.width)`
  Sub-pixel `contentRect` values differ by fractions on a scrollbar appearing or a zoom level change, so an exact float comparison never matches and the debounce fires forever. Rounding to whole pixels is the smallest unit a line break can actually respond to.

## API

```ts
function FontSafeTextSplit(props: { children: ReactNode; type?: string; mask?: boolean; y?: number; duration?: number; stagger?: number; start?: string; scroller?: Element | null; debounceMs?: number; className?: string }): JSX.Element
```

- `children: ReactNode`
  Text or markup to split into lines.
- `type: string` — default `'lines'`
  SplitText `type`. Lines are what the mask and the re-split are for.
- `mask: boolean` — default `true`
  Wrap each line in an overflow-hidden box.
- `y: number` — default `110`
  Percent of a line's height it starts below the mask.
- `duration: number` — default `0.9`
  Seconds per line.
- `stagger: number` — default `0.09`
  Seconds between lines.
- `start: string` — default `'top 88%'`
  ScrollTrigger `start` for the reveal.
- `scroller: Element | null` — default `null`
  Scroll container, when the text is not in the document scroller.
- `debounceMs: number` — default `200`
  Milliseconds of quiet after the last resize before re-splitting.
- `className: string`
  Merged onto the container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const Y = 110;
const DURATION = 0.9;
const STAGGER = 0.09;
const START = 'top 88%';
const DEBOUNCE_MS = 200;

export function FontSafeTextSplit({
  children,
  type = 'lines',
  mask = true,
  y = Y,
  duration = DURATION,
  stagger = STAGGER,
  start = START,
  scroller = null,
  debounceMs = DEBOUNCE_MS,
  className,
}: FontSafeTextSplitProps) {
  const root = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();

  useEffect(() => {
    const el = root.current;
    // Reduced motion never splits. The markup React rendered is the finished
    // state, so the entire font/resize lifecycle below is unnecessary work.
    if (!el || reduced) return;

    gsap.registerPlugin(ScrollTrigger, SplitText);

    let cancelled = false;
    let split: SplitText | null = null;
    let ctx: gsap.Context | null = null;
    let timer = 0;
    // Once the lines have been revealed, a re-split must render them at their
    // final position. Replaying the entrance because the user rotated their
    // phone is the classic symptom of a re-split that forgot it had run.
    let revealed = false;
    // Last measured *width*. Height changes are ignored on purpose.
    let lastWidth = Math.round(el.getBoundingClientRect().width);

    const teardown = () => {
      ctx?.revert();
      ctx = null;
      split?.revert();
      split = null;
    };

    const apply = () => {
      if (cancelled) return;
      teardown();

      const s = new SplitText(el, {
        type,
        mask: mask ? 'lines' : undefined,
        linesClass: 'kinetic-fs-line',
        // SplitText restores the original text for assistive technology.
        // Without it a screen reader announces one fragment per line box.
        aria: 'auto',
      });
      split = s;

      ctx = gsap.context(() => {
        if (revealed) {
          // Already seen. Land the new line boxes in their final state.
          gsap.set(s.lines, { yPercent: 0, opacity: 1 });
          return;
        }
        gsap.from(s.lines, {
          yPercent: y,
          duration,
          stagger,
          ease: 'power3.out',
          scrollTrigger: {
            trigger: el,
            scroller: scroller ?? undefined,
            start,
            once: true,
            onEnter: () => {
              revealed = true;
            },
          },
        });
      }, el);

      // Wrapping lines changes this element's height, so every trigger below
      // it on the page is now measuring against stale coordinates.
      ScrollTrigger.refresh();
    };

    // 1. The first split waits for the fonts the document already knows about.
    void document.fonts.ready.then(apply);

    // 2. A font requested later — a lazy section, a second weight, an icon
    //    face — triggers another layout pass that moves the line breaks.
    const onFontsDone = () => apply();
    document.fonts.addEventListener('loadingdone', onFontsDone);

    // 3. Line breaks are a function of container width. Nothing else
    //    recomputes them, so a resize without a re-split leaves the wrappers
    //    describing a layout that no longer exists.
    const ro = new ResizeObserver((entries) => {
      const entry = entries[0];
      if (!entry) return;
      const width = Math.round(entry.contentRect.width);
      // Width-only. iOS fires resize when the URL bar collapses, which changes
      // height only; re-splitting there rebuilds the DOM mid-scroll for
      // nothing and drops frames on the device least able to spare them.
      if (width === lastWidth) return;
      lastWidth = width;
      window.clearTimeout(timer);
      timer = window.setTimeout(apply, debounceMs);
    });
    ro.observe(el);

    return () => {
      cancelled = true;
      window.clearTimeout(timer);
      ro.disconnect();
      document.fonts.removeEventListener('loadingdone', onFontsDone);
      teardown();
    };
  }, [
    children,
    type,
    mask,
    y,
    duration,
    stagger,
    start,
    scroller,
    debounceMs,
    reduced,
  ]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Sets a `cancelled` flag that closes the async `document.fonts.ready` gap, clears the pending debounce timeout, disconnects the `ResizeObserver`, removes the `loadingdone` listener, then reverts the `gsap.context` and the split in that order. Nothing can re-split or tween after unmount.

**Reduced motion.** The effect returns before registering anything: no split, no font listener, no ResizeObserver. The text React rendered is the finished state and is fully visible on first paint — which also means the entire measurement lifecycle costs nothing for users who asked for less motion.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Splitting synchronously on mount. On a cold cache the fallback face is measured, the line wrappers are fixed at the wrong break points, and when the real font swaps in the masked lines clip words in half. It works perfectly on every reload after the first, which is why it ships.
- Waiting only on `document.fonts.ready` and stopping there. It resolves once for the fonts the document knew about at that moment; a font requested later re-flows the text under wrappers that are already fixed.
- Re-splitting on every resize event. Each split is a full DOM teardown and rebuild, so dragging a window edge rebuilds the subtree dozens of times a second and the page locks up.
- Re-splitting on any resize rather than on width change. iOS fires resize on every URL-bar collapse, so scrolling on a phone continuously destroys and rebuilds the paragraph.
- Comparing raw `contentRect.width` floats. They wobble by fractions of a pixel and the debounce re-arms forever.
- Re-splitting without reverting the previous split first. The new line wrappers nest inside the old ones, and after a few resizes the paragraph is wrapped several layers deep with stale masks at every level.
- Replaying the entrance on re-split. The text drops back below its mask and rises again because the user rotated their phone, which reads as a rendering glitch.
- Skipping `ScrollTrigger.refresh()` after the split. The element's height changed, so every trigger below it on the page fires at the wrong scroll position — usually the bug reported as "the section below animates too early".

## Notes

- This is one of the two components that deliberately use GSAP `SplitText`, because the technique *is* SplitText's lifecycle. `SplitText` ships inside the main `gsap` package and is free to use; it is imported from `gsap/SplitText` rather than vendored, so this is a use grant with no redistribution. The other text components in this set split declaratively in JSX so consumers are not forced into GSAP for effects that do not need it.
- Every other split-based component in the registry inherits this problem. If you split text anywhere — by hand, with `split-type`, or with SplitText — the `document.fonts.ready` gate and the width-only debounced re-split apply just as much.
- GSAP 3.13+ offers `autoSplit` and `onRevert`, which cover part of this. The explicit lifecycle here is kept because it also handles the late-`loadingdone` case and gives you the `revealed` flag, and because it is legible: you can see exactly which of the three triggers fired.

## Definition of done

Hard-reload with the cache disabled and throttled network: the lines break correctly and no word is clipped by a mask edge, on the first load as well as subsequent ones. Drag the window narrower and the lines re-break about 200ms after you stop, once, without replaying the entrance. Scroll on an iOS device and the paragraph never rebuilds as the URL bar collapses. Resize repeatedly and inspect the DOM: line wrappers are exactly one level deep, never nested. A section below the text still triggers at the correct scroll position after a re-split.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: FOV-Derived Row Spacing

A perspective row that never guesses its spacing. Given a vertical field of view and a camera distance, it computes the visible width on the row plane, divides it across the gaps between item centres, and converts to pixels once at the end. The outermost item centres land on the frame edges by construction, at any aspect ratio, with no breakpoint table and no tuned magic number. It is the flat pre-intro layout of a three.js drum, done in the DOM with the identical arithmetic.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A row whose item spacing is solved from a field of view and a camera distance, so it spans the frame exactly at any size.

- Category: layout
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. A pinhole camera at distance d from a plane sees `visibleHeight = 2 · d · tan(fov / 2)` on that plane, and `visibleWidth = visibleHeight · aspect`. Both quantities are in world units; nothing pixel-sized is involved yet.
2. The step is `visibleWidth · spanRatio / (n − 1)` and item centres are `x_i = i · step − rowWidth / 2` where `rowWidth = (n − 1) · step`. The subtraction centres the row on the origin without a second measurement, because the outermost centres are at ±rowWidth/2 by definition.
3. World units become pixels through a single scalar, `pxPerUnit = heightPx / visibleHeight`, applied at the last multiplication. Every intermediate value stays resolution-independent, which is why a resize needs no re-derivation of anything but this one number.
4. CSS `perspective` is set to `cameraZ · pxPerUnit`, which reduces to `heightPx / (2 · tan(fov / 2))` — the cameraZ cancels. That cancellation is the proof that the world-unit scale and the CSS projection describe the same camera: if it did not cancel, the two coordinate systems would disagree and depth would foreshorten by the wrong amount.
5. Items are placed with `translate3d(x · pxPerUnit, 0, z · pxPerUnit)` and the browser performs the perspective divide. An element at world z projects with scale `cameraZ / (cameraZ − z)`, which is exactly what a `PerspectiveCamera` does to a plane at the same depth.
6. The optional bow pushes outer items away on a parabola, `z = −bow · t²` with `t = x / (visibleWidth / 2)`. Depth would shrink their projected x, so the unprojected x is pre-multiplied by `(cameraZ − z) / cameraZ` — the exact inverse of the divide — and the row still spans the frame with the bow at any strength.
7. The four camera scalars are damped rather than assigned, so changing the field of view reads as a dolly. The layout is a pure function of them, so an interruption mid-spread cannot desynchronise anything: there is no accumulated position to corrupt.
8. The frame loop snaps inside an epsilon, writes one final layout, and then returns immediately. Exponential damping never actually arrives, so without that gate the component would rewrite n transforms every frame forever for a row that has visibly stopped moving.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `visibleHeight = 2 · cameraZ · tan(fov / 2)`
  The exact height of the frustum cross-section at the row plane. Half the FOV subtends a right triangle of opposite `visibleHeight / 2` over adjacent `cameraZ`, so `tan(fov / 2) = (visibleHeight / 2) / cameraZ`. The factor of 2 and the half-angle are the two places this is most often written wrong; using `tan(fov)` overstates the span by roughly 3x at 70 degrees.
- `step = visibleWidth · spanRatio / (n − 1)`
  n − 1, not n. The step is the distance between adjacent item CENTRES, and n centres have n − 1 gaps between them. Dividing by n leaves the row one step short, so the last item never reaches the frame edge — the discrepancy is 1/n, which is invisible at twenty items and glaring at four.
- `x_i = i · step − rowWidth / 2`
  Centres the row on the origin arithmetically. With `rowWidth = (n − 1) · step`, item 0 sits at −rowWidth/2 and item n−1 at +rowWidth/2, so the row is symmetric for both odd and even counts without a special case and without measuring the assembled row afterwards.
- `perspective = heightPx / (2 · tan(fov / 2))`
  The CSS perspective distance in pixels that reproduces the same vertical FOV over a box of height H. Derived by asking at what distance the visible height equals H: `H = 2 · P · tan(fov / 2)`. It is `cameraZ · pxPerUnit` with the cameraZ cancelled, which is why the row can be moved nearer or further without touching this value.
- `depthScale = (cameraZ − z) / cameraZ`
  Perspective divides a point's projected x by `(cameraZ − z) / cameraZ`, so pre-multiplying the unprojected x by the same factor leaves the projection exactly where the flat row put it. Omitting it makes any bow pull the outer items inward, which is the bug usually patched by nudging spanRatio above 1 until it happens to look right at one screen size.
- `fov = 70`
  Degrees, vertical. Wide enough that the bow foreshortens visibly rather than reading as a flat scale-down. Above ~90 the near items grow fast enough to clip the frame; below ~40 the perspective is so weak that the depth compensation has nothing to compensate for and the row may as well be 2D.
- `cameraZ = 5`
  World units. It sets nothing visible on its own — it only fixes the unit scale, since a larger distance widens the visible area by the same ratio it shrinks everything on screen. 5 keeps the bow and the item sizes in a range where single decimal digits are meaningful, matching the drum this arithmetic came from.
- `bow = 0.6`
  World units of depth at the frame edge, about 12% of cameraZ. Enough that the outer items read as receding; past ~0.3 · cameraZ they shrink far enough that the row looks like a fisheye rather than a row, and the compensated x starts pushing content beyond the overflow clip.
- `smoothing = 0.0015`
  Fraction of the remaining gap left after one second, so the row is ~99.9% of the way to a new field of view within that second. Frame-rate independent by construction, so a 120 Hz display and a throttled tab converge on the same curve rather than the same per-frame ratio.
- `EPSILON = 0.0005`
  Summed absolute gap across the four scalars below which the layout snaps and the loop stops writing. Small enough to be sub-pixel at any plausible pxPerUnit, large enough that exponential damping crosses it in under a second instead of asymptoting forever.

## API

```ts
function FovDerivedRow(props: { children: ReactNode; fov?: number; cameraZ?: number; spanRatio?: number; bow?: number; smoothing?: number; className?: string; cellClassName?: string }): JSX.Element
```

- `children: ReactNode`
  One positioned cell per child, laid out on the derived step.
- `fov: number` — default `70`
  Vertical field of view in degrees. Drives both the spacing and the CSS perspective.
- `cameraZ: number` — default `5`
  Camera distance to the row plane in world units. Fixes the unit scale.
- `spanRatio: number` — default `1`
  Fraction of the visible width the row spans. 1 puts the outer centres on the frame edges.
- `bow: number` — default `0.6`
  World units the outermost items recede. Their x is compensated so the span is preserved.
- `smoothing: number` — default `0.0015`
  Fraction of the gap remaining after one second while the row re-spreads.
- `className: string`
  Merged onto the stage element.
- `cellClassName: string`
  Merged onto every positioned cell. Size the items here.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function FovDerivedRow({
  children,
  fov = FOV,
  cameraZ = CAMERA_Z,
  spanRatio = SPAN_RATIO,
  bow = BOW,
  smoothing = SMOOTHING,
  className,
  cellClassName,
}: FovDerivedRowProps) {
  const stage = useRef<HTMLDivElement>(null);
  const cells = useRef<Array<HTMLDivElement | null>>([]);

  const size = useResizeObserver(stage);
  const { inView } = useInView(stage, { threshold: 0 });
  const reduced = useReducedMotion();

  const items = Children.toArray(children);
  const count = items.length;

  /* The three scalars the layout is a pure function of. They are damped rather
     than assigned so that changing the FOV reads as a dolly, not as a jump —
     and because the layout is a pure function of them, interrupting mid-spread
     cannot desynchronise anything. */
  const live = useRef({ fov, cameraZ, spanRatio, bow });
  const current = useRef({ fov, cameraZ, spanRatio, bow });
  const settled = useRef(false);
  live.current = { fov, cameraZ, spanRatio, bow };

  /**
   * Lay the row out for one set of camera scalars. Pure: same inputs, same
   * transforms, no accumulated state.
   */
  const apply = (params: { fov: number; cameraZ: number; spanRatio: number; bow: number }) => {
    const el = stage.current;
    if (!el || count === 0) return;

    const widthPx = el.clientWidth;
    const heightPx = el.clientHeight;
    if (widthPx < 1 || heightPx < 1) return;

    // Half-angle first: every formula below wants tan(fov/2), never tan(fov).
    const tanHalfFov = Math.tan((params.fov * Math.PI) / 360);
    const visibleHeight = 2 * params.cameraZ * tanHalfFov;
    const visibleWidth = visibleHeight * (widthPx / heightPx);

    // World units to CSS pixels. The whole layout is computed in world units
    // and converted exactly once, here.
    const pxPerUnit = heightPx / visibleHeight;
    // P = H / (2 tan(fov/2)). Independent of cameraZ, which is the sanity
    // check that the world-unit scale and the projection agree.
    const perspectivePx = params.cameraZ * pxPerUnit;

    // n − 1, not n: the step is the distance between adjacent CENTRES, and a
    // row of n centres has n − 1 gaps. Dividing by n leaves the row short by
    // one step and the last item never reaches the frame edge.
    const gaps = Math.max(count - 1, 1);
    const step = count > 1 ? (visibleWidth * params.spanRatio) / gaps : 0;
    const rowWidth = (count - 1) * step;
    const halfSpan = Math.max(visibleWidth / 2, 1e-6);

    el.style.perspective = `${perspectivePx}px`;

    for (let i = 0; i < count; i += 1) {
      const cell = cells.current[i];
      if (!cell) continue;

      const flatX = i * step - rowWidth / 2;

      // Parabolic bow: 0 at the centre, `bow` units back at the frame edge.
      const t = flatX / halfSpan;
      const worldZ = -params.bow * t * t;

      // Depth compensation. Moving a point from z = 0 to z shrinks its
      // projected x by cameraZ / (cameraZ − z), so scaling the unprojected x
      // by the inverse leaves the projection exactly where the flat row put
      // it. Without this line, any bow pulls the outer items inward and the
      // row stops spanning the frame — the bug that gets "fixed" by nudging
      // spanRatio past 1 until it looks right at one screen size.
      const depthScale = (params.cameraZ - worldZ) / params.cameraZ;
      const worldX = flatX * depthScale;

      cell.style.transform =
        `translate(-50%, -50%) translate3d(${worldX * pxPerUnit}px, 0px, ${worldZ * pxPerUnit}px)`;
    }
  };

  // Resize is not an animation: re-derive and write immediately, or the row
  // lags a visible beat behind a window drag.
  useEffect(() => {
    apply(current.current);
    // `apply` closes over refs only; re-running on every render would fight
    // the frame loop for the same transforms.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [size.width, size.height, count]);

  useEffect(() => {
    if (!reduced) return;
    // Reduced motion is the resolved layout, not a fast spread: adopt the
    // target scalars outright and lay out once.
    current.current = { ...live.current };
    settled.current = false;
    apply(current.current);
  }, [reduced, fov, cameraZ, spanRatio, bow]);

  useRaf(
    (dt) => {
      const target = live.current;
      const now = current.current;

      const next = {
        fov: damp(now.fov, target.fov, smoothing, dt),
        cameraZ: damp(now.cameraZ, target.cameraZ, smoothing, dt),
        spanRatio: damp(now.spanRatio, target.spanRatio, smoothing, dt),
        bow: damp(now.bow, target.bow, smoothing, dt),
      };

      // Exponential damping never actually arrives, so it would rewrite n
      // transforms forever. Snap inside epsilon, lay out one last time, and
      // then skip the writes entirely until a prop moves again.
      const gap =
        Math.abs(next.fov - target.fov) +
        Math.abs(next.cameraZ - target.cameraZ) +
        Math.abs(next.spanRatio - target.spanRatio) +
        Math.abs(next.bow - target.bow);

      if (gap < EPSILON) {
        if (settled.current) return;
        current.current = { ...target };
        settled.current = true;
        apply(current.current);
        return;
      }

      settled.current = false;
      current.current = next;
      apply(next);
    },
    inView && !reduced,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useRaf` unsubscribes from the shared loop on unmount and cancels the frame when it is the last subscriber; `useResizeObserver` and `useInView` remove their targets from their shared observers. No listeners, timers or tweens are created directly. Inline transforms are written only to elements this component owns and rendered, so they are removed with them.

**Reduced motion.** The reduced branch adopts the target scalars outright and lays the row out once, so the resolved geometry is on screen rather than a fast spread toward it. The frame loop is not subscribed at all, so no work is scheduled for a user who asked for none, and a later prop change still re-derives the layout immediately through the same code path. Because the layout is a pure function of the four scalars, the reduced render is pixel-identical to the settled animated one.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Spacing a perspective row by `containerWidth / n`. It is wrong twice: it uses n instead of n − 1, and it ignores that the row plane is not the screen plane. It looks correct at one viewport because the error was absorbed into a hand-tuned padding, and it breaks on the first aspect-ratio change.
- Using `tan(fov)` instead of `tan(fov / 2)`. At 70 degrees that overstates the visible extent by about 3x, so the row spreads far past the frame. It survives review because the row still looks deliberate — just wildly too wide — and the fix gets applied as a 0.35 multiplier somewhere else.
- Applying degrees to `Math.tan` directly. `Math.tan(70)` is a perfectly finite number, so nothing throws and nothing warns; the layout is simply nonsense. `(fov * Math.PI) / 360` converts and halves in one step, which is also why that constant is 360 and not 180.
- Bowing items in z without compensating x. Depth shrinks projected x, so the outer items drift inward and the row silently stops spanning the frame. The formula is one multiplication and its absence is normally treated as a spacing problem rather than a projection one.
- Setting `perspective` from a fixed pixel value while deriving the spacing from an FOV. The two then describe different cameras: the arithmetic places items for one frustum and the browser projects them through another, so depth foreshortens by the wrong amount and no amount of spacing tuning fixes it.
- Deriving the layout from `window.innerWidth`. The component is correct on load and wrong the moment it sits in a resizable panel or a grid cell that reflows. Its own `clientWidth` and `clientHeight` are the only inputs that stay true, which is what `useResizeObserver` supplies.
- Letting the damping loop run forever. Exponential approach never reaches its target, so a settled row keeps writing n transforms per frame and the profiler shows a permanent baseline cost for a component that has not moved in a minute. Snap inside an epsilon and return.
- Recomputing on resize only inside the frame loop. A resize is not an animation; deferring it by a frame makes the row visibly lag a window drag by one tick, which reads as jank rather than as smoothing.
- Omitting `transform-style: preserve-3d`, or setting the perspective on an ancestor with its own transform. Either flattens the subtree and every `translateZ` collapses to no effect, leaving a row that is correctly spaced but stubbornly two-dimensional.

## Notes

- The spacing arithmetic is identical to the flat pre-intro row of a three.js drum gallery, which is the point: the formula belongs to the projection, not to the renderer. Porting it means replacing one conversion line, and this component is the DOM half of the pair that `layout-lerp-scalar` interpolates away from.
- With `bow: 0` and `spanRatio: 1` the component has a hands-on correctness test: the outermost item centres sit exactly on the left and right edges of the box, at every viewport, with no tuning. If they do not, one of the formulas above has been mistyped.
- `spanRatio` is the only aesthetic knob here — everything else is determined. Values below 1 inset the row from the frame; above 1 it deliberately overflows the clip, which is useful when the outer items are meant to be cut off.

## Definition of done

Set `bow` to 0 and the leftmost and rightmost item centres sit exactly on the edges of the box — resize the panel from narrow to wide and they stay there, with no jump and no breakpoint. Restore the bow and the outer items recede and shrink while their horizontal positions do not move. Raise the field of view and the row spreads on a smooth dolly rather than snapping. Item counts of 1 and 2 both render without a divide-by-zero or a NaN transform. With reduced motion on, the row is at its final geometry on first paint and the profiler shows no animation frames for it.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Fractional Render Scale

A drifting fog field with a latent grid that develops under the cursor, rendered into a canvas whose backing store is deliberately 0.6x the size of the element it fills. The browser upscales it, and the upscale is invisible because the content was authored for it: no detail finer than a dozen pixels, and the one thing with an edge — the grid — has its line width specified in backing-store pixels rather than CSS pixels. It is a background you can afford, and a demonstration of the cheapest large performance win in WebGL.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A field rendered into a backing store 0.6x its box — 36% of the fragments — with a grid measured in texels so the upscale never shows.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. The scale is applied through the pixel ratio: `renderer.setPixelRatio(pixelRatio(maxDpr) * scale)` followed by `setSize(w, h, false)`. three then sizes the backing store to `floor(w * dpr * scale)` while the canvas keeps `width: 100%` from CSS, so one number controls the ratio and there is no second sizing path to keep in sync.
2. The achieved ratio is measured rather than assumed. `setSize` floors, so `getDrawingBufferSize().x / cssWidth` can differ from `dpr * scale` by up to a pixel; that measured value becomes `uScale`, and every length the shader treats as a CSS pixel is `gl_FragCoord.xy / uScale`.
3. The fog is three sines multiplied and added, then pushed through `smoothstep(-0.15, 1.15, fog)`. It is not trying to be fbm — it is trying to contain no feature smaller than roughly a dozen pixels, which is the precondition for a bilinear upscale being undetectable.
4. The grid is drawn from `abs(fract(cell - 0.5) - 0.5) * pxPerCell`, which is the distance to the nearest line expressed in backing-store pixels, and a `smoothstep(width - 0.5, width + 0.5, d)` ramp across exactly one texel. A line specified this way is `1 / scale` CSS pixels wide after the upscale: softer as the scale drops, never thinner, so it cannot fall through the sampling grid.
5. No `fwidth`. The grid is axis-aligned in screen space, so the derivative of the cell coordinate is a constant the shader already holds — `uScale * uGridSize` backing pixels per cell. Computing it directly is exact, is one multiply, and needs no derivatives extension.
6. The geometry is a single triangle with vertices at (-1,-1), (3,-1) and (-1,3). It covers the viewport with three vertices and no diagonal, so the GPU never shades the seam pixels twice as it does where two triangles of a fullscreen quad meet.
7. The pointer is smoothed by `useSmoothPointer` with `perFrameToSmoothing(0.05)`, which reproduces the source's `x += (target - x) * 0.05` at 60 Hz while staying frame-rate independent, and its `nx`/`ny` are flipped to GL's y-up before reaching the uniform.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `renderScale = 0.6`
  Linear, so the saving is quadratic: 0.36 of the fragments, a 64% cut, about 2.8x less fragment work. A 2560x1440 window drops from 3.7 M fragments a frame to 1.3 M. Below roughly 0.5 the grid lines start to look conspicuously soft against crisp DOM text next to them; above 0.8 there is little left to win.
- `MIN_SCALE = 0.25`
  Floor on the prop. At 0.25 a one-texel line is already four CSS pixels wide — a third of a 44 px cell — and the grid stops reading as a grid and starts reading as a plaid.
- `lineWidth = 1 backing pixel`
  The unit is the whole point. One texel is the finest line the buffer can actually hold; asking for one CSS pixel at 0.6 scale asks for 0.6 of a texel, which the rasteriser answers with a dashed line that crawls as the box resizes.
- `gridSize = 44 CSS pixels`
  Authored in CSS pixels so the grid holds its apparent size when the render scale changes — the entire visual difference between 0.6 and 1.0 should be a slight softening, never a different layout.
- `majorEvery = 5`
  A 220 px major cell. Without a second scale the grid is a flat screen door; with one it acquires depth. Its line is 1.6x the minor width, which survives the upscale as a clear hierarchy where a colour difference alone would not.
- `POINTER_ALPHA = 0.05 per frame at 60 Hz`
  The source chose it to be slower than the eye expects, which reads as viscosity: about 330 ms to close 63% of the gap. Passed through `perFrameToSmoothing` so a 120 Hz display gets the same 330 ms rather than half of it.
- `glow exponent = exp(-d * d * 2.2)`
  A Gaussian on distance normalised by the radius, so `glowRadius` is where the glow has fallen to about 11%. A smoothstep here would put a visible circular edge on a field that has no other edges — the one place the upscale would be caught.
- `grid reveal = 0.18 + 0.82 * glow`
  The grid is mostly latent and the cursor develops it. At full strength everywhere it is a background; appearing under the pointer, it is a surface reacting to being touched. The 0.18 floor keeps the structure legible before the pointer arrives.
- `POINTER_EPSILON = 0.0002`
  Under reduced motion the image is a pure function of the pointer, so frames where it has not moved are skipped entirely. The threshold is well under one pixel of an ordinary box, so no real movement is ever swallowed.

## API

```ts
function FractionalRenderScale(props: { renderScale?: number; maxDpr?: number; gridSize?: number; majorEvery?: number; lineWidth?: number; glowRadius?: number; baseColor?: string; fogColor?: string; lineColor?: string; glowColor?: string; className?: string }): JSX.Element
```

- `renderScale: number` — default `0.6`
  Backing store size relative to the display pixel ratio. Clamped to 0.25..1.
- `maxDpr: number` — default `2`
  Cap on the device pixel ratio before the render scale is applied.
- `gridSize: number` — default `44`
  Grid spacing in CSS pixels. Floored at 4.
- `majorEvery: number` — default `5`
  Every nth line is drawn as a major one, 1.6x the width.
- `lineWidth: number` — default `1`
  Minor line width in backing-store pixels — not CSS pixels. Floored at 0.5.
- `glowRadius: number` — default `240`
  Cursor glow radius in CSS pixels, at which the glow has fallen to about 11%.
- `baseColor: string` — default `'#080b12'`
  Darkest colour of the field.
- `fogColor: string` — default `'#1d3350'`
  Colour the fog lifts toward.
- `lineColor: string` — default `'#8fb6df'`
  Grid line colour.
- `glowColor: string` — default `'#3f7fd0'`
  Additive colour under the pointer.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function FractionalRenderScale({
  renderScale = 0.6,
  maxDpr = 2,
  gridSize = 44,
  majorEvery = 5,
  lineWidth = 1,
  glowRadius = 240,
  baseColor = '#080b12',
  fogColor = '#1d3350',
  lineColor = '#8fb6df',
  glowColor = '#3f7fd0',
  className,
}: FractionalRenderScaleProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);

  const { width, height } = useResizeObserver(host);
  const { inView } = useInView(host, { threshold: 0 });
  const visible = useVisibility();
  const reduced = useReducedMotion();
  const pointer = useSmoothPointer({ target: host, smoothing: POINTER_SMOOTHING });

  const [supported, setSupported] = useState(true);
  useEffect(() => setSupported(hasWebGL()), []);

  /* Read inside resize and draw. Keeping them out of the effect's dependency
     list means dragging a render-scale slider re-sizes the backing store
     rather than tearing down the GL context on every step. */
  const live = useRef({ renderScale, maxDpr, gridSize, majorEvery, lineWidth, glowRadius });
  live.current = { renderScale, maxDpr, gridSize, majorEvery, lineWidth, glowRadius };

  const lastPointer = useRef<{ x: number; y: number } | null>(null);

  const ready = width > 1 && height > 1 && supported;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    const renderer = new THREE.WebGLRenderer({
      // Nothing in the field has a geometric edge, so MSAA has nothing to
      // sample — and at a fractional scale it would be antialiasing the wrong
      // grid anyway.
      antialias: false,
      // Opaque: the shader covers every pixel, and an alpha channel would make
      // the compositor blend the canvas over the page for no reason.
      alpha: false,
      depth: false,
      stencil: false,
      // The entire point of the component. On a laptop with switchable
      // graphics this keeps a decorative background off the discrete GPU.
      powerPreference: 'low-power',
    });
    renderer.setClearColor(0x000000, 1);
    renderer.domElement.style.display = 'block';
    // CSS size is 1x and fixed to the box; the backing store is set separately
    // by setSize(..., false). The gap between the two IS the render scale.
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';
    el.appendChild(renderer.domElement);

    const scene = new THREE.Scene();
    const camera = new THREE.Camera();

    // One oversized triangle, not a quad. It covers the viewport with three
    // vertices and no diagonal seam for the GPU to shade twice.
    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute(
      'position',
      new THREE.BufferAttribute(new Float32Array([-1, -1, 0, 3, -1, 0, -1, 3, 0]), 3),
    );

    const uniforms: Uniforms = {
      uResolution: { value: new THREE.Vector2(1, 1) },
      uScale: { value: 1 },
      uTime: { value: 0 },
      uPointer: { value: new THREE.Vector2(0.5, 0.5) },
      uGridSize: { value: gridSize },
      uMajorEvery: { value: majorEvery },
      uLineWidth: { value: lineWidth },
      uGlowRadius: { value: glowRadius },
      uBaseColor: { value: new THREE.Color(baseColor) },
      uFogColor: { value: new THREE.Color(fogColor) },
      uLineColor: { value: new THREE.Color(lineColor) },
      uGlowColor: { value: new THREE.Color(glowColor) },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: FRACTIONAL_SCALE_VERT,
      fragmentShader: FRACTIONAL_SCALE_FRAG,
      uniforms,
      depthTest: false,
      depthWrite: false,
    });

    const mesh = new THREE.Mesh(geometry, material);
    // The triangle's vertices sit outside a unit bounding sphere, and there is
    // no camera transform to cull against in the first place.
    mesh.frustumCulled = false;
    scene.add(mesh);

    const buffer = new THREE.Vector2();

    stage.current = {
      resize(w, h) {
        const state = live.current;
        const scale = clamp(state.renderScale, MIN_SCALE, 1);
        // Scale folded into the pixel ratio: three then multiplies it through
        // setSize for the backing store while the CSS size stays whatever the
        // stylesheet says. One number, no second sizing path to keep in sync.
        renderer.setPixelRatio(pixelRatio(state.maxDpr) * scale);
        renderer.setSize(w, h, false);

        renderer.getDrawingBufferSize(buffer);
        const bw = Math.max(1, Math.round(buffer.x));
        const bh = Math.max(1, Math.round(buffer.y));
        uniforms.uResolution.value.set(bw, bh);
        // Measured, not assumed. setSize floors, so the achieved ratio differs
        // from dpr * scale by up to a pixel — and the grid is authored in CSS
        // pixels, which would then drift against the layout.
        uniforms.uScale.value = w > 0 ? bw / w : 1;

        uniforms.uGridSize.value = Math.max(4, state.gridSize);
        uniforms.uMajorEvery.value = Math.max(1, Math.round(state.majorEvery));
        uniforms.uLineWidth.value = Math.max(0.5, state.lineWidth);
        uniforms.uGlowRadius.value = Math.max(1, state.glowRadius);
      },

      draw(time, pointerX, pointerY) {
        uniforms.uTime.value = time;
        uniforms.uPointer.value.set(pointerX, pointerY);
        renderer.render(scene, camera);
      },
    };

    stage.current.resize(el.clientWidth, el.clientHeight);
    stage.current.draw(0, 0.5, 0.5);

    return () => {
      stage.current = null;
      geometry.dispose();
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, baseColor, fogColor, lineColor, glowColor]);

  useEffect(() => {
    const current = stage.current;
    if (!current || width < 1 || height < 1) return;
    current.resize(width, height);
    // Resizing a canvas clears its drawing buffer. When time is frozen the
    // loop skips every frame in which the pointer has not moved, so the
    // redraw has to happen here or the field stays blank until it does. When
    // time is running the next frame covers it a few milliseconds later.
    if (reduced) {
      const state = pointer.current;
      current.draw(0, state.nx, 1 - state.ny);
      lastPointer.current = { x: state.nx, y: 1 - state.ny };
    }
  }, [
    width,
    height,
    reduced,
    renderScale,
    maxDpr,
    gridSize,
    majorEvery,
    lineWidth,
    glowRadius,
    pointer,
  ]);

  useRaf(
    (_dt, elapsed) => {
      const current = stage.current;
      if (!current) return;

      const state = pointer.current;
      const px = state.nx;
      // GL's y axis points up; the pointer's does not.
      const py = 1 - state.ny;

      // Reduced motion freezes time at 0 rather than stopping the render, so
      // the fog, the vignette and the cursor glow all survive — only the drift
      // is gone. With time constant the image is a pure function of the
      // pointer, so a frame where the pointer has not moved is skippable.
      if (reduced) {
        const last = lastPointer.current;
        if (
          last &&
          Math.abs(px - last.x) < POINTER_EPSILON &&
          Math.abs(py - last.y) < POINTER_EPSILON
        ) {
          return;
        }
      }

      lastPointer.current = { x: px, y: py };
      current.draw(reduced ? 0 : elapsed, px, py);
    },
    ready && inView && visible,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nulls the stage ref, disposes the triangle geometry and the ShaderMaterial, then calls `disposeRenderer` for `dispose` + `forceContextLoss` + a zeroed drawing buffer, and removes the canvas from the DOM. The canvas is three's own, created inside the effect and appended per effect run, so a StrictMode remount builds a new context instead of reattaching one that was just force-lost. The pointer listener belongs to `useSmoothPointer` and is removed with it; sizing, visibility and the frame loop are all shared subscriptions that release themselves.

**Reduced motion.** The component reads `useReducedMotion` itself and freezes `uTime` at 0 rather than stopping the render. The fog, the vignette, the grid and the cursor glow are all still drawn — none of them depends on time — so what is lost is exactly the drift and nothing else. With time constant the image is a pure function of the pointer, so the loop skips any frame in which the pointer has not moved by more than 0.0002, and a still page costs nothing beyond the empty rAF callback.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Setting only `canvas.width` and forgetting the CSS size, or the reverse. Either mistake produces a canvas that is simply smaller or simply blurrier than intended; the technique is the deliberate gap between the two sizes, and both have to be set on purpose.
- Putting `image-rendering: pixelated` on the canvas — sometimes inherited from a global rule aimed at sprite art. It replaces the bilinear upscale with nearest-neighbour and the entire effect turns into visible blocks.
- Specifying line widths, glow radii or grid spacing in device pixels via raw `gl_FragCoord`. Everything is tuned on one machine and then renders at 0.6 of that size at 0.6 scale, and a third of it again on a 3x phone. Divide by the measured scale and author in CSS pixels.
- Rendering content with fine detail at a fractional scale. Text, hairlines, high-frequency noise and hard-edged shapes all alias the moment the buffer shrinks. This technique is for soft fields, and content and scale have to be chosen together.
- Listening to `window.resize` instead of observing the element. A sidebar opening, a font loading and reflowing, or a flex sibling changing all resize the box with no window event — and `ResizeObserver` also fires once on observe, which handles the initial size with no separate call.
- Forgetting that resizing the canvas clears its drawing buffer. Any component that skips frames — as this one does when time is frozen — goes blank after a resize unless the resize path redraws explicitly.
- Reading `dpr * scale` back as the achieved ratio. `setSize` floors the backing store, so on most box widths the real ratio is slightly lower; using the nominal value makes the grid drift by a pixel against the layout as the window changes.
- Suppressing the render entirely under reduced motion. Time frozen at 0 still gives the fog, the vignette and the cursor glow, because none of them depend on it — a far better degradation than a flat colour, and the accessibility requirement is about motion, not about the image.
- Assuming `antialias: true` helps. There is no geometric edge to sample: the only visible edges come from the fragment shader, MSAA does not see them, and the request costs a multisampled buffer of the same size as everything just saved.

## Notes

- The renderer is created with `powerPreference: "low-power"`. On a laptop with switchable graphics this keeps a decorative background off the discrete GPU, which is worth more battery than the render scale itself.
- `renderScale` and `maxDpr` are read from a ref inside the resize path, so changing them re-sizes the backing store without rebuilding the GL context — a render-scale slider can be dragged live.
- A useful way to see the technique: set `renderScale` to 1 and then to 0.6 and watch the grid rather than the fog. The lines soften very slightly and nothing else about the image changes, while the fragment count falls by two thirds.
- The colours are individual string props rather than an array, so a caller passing literals does not hand the effect a new identity on every render.

## Definition of done

A soft blue fog drifting behind a faint grid, with the grid brightening into a pool under the cursor that trails a third of a second behind it. Open DevTools and the canvas element reports a backing store of 0.6 of its CSS size — the technique is verifiable, not merely claimed — while the image shows no blockiness and the grid lines stay continuous rather than dashed. Resize the window slowly: the grid keeps its 44 px spacing against the layout and never crawls. With reduced motion the fog stops drifting and everything else, cursor glow included, still works.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Fullscreen Triangle Pass

The smallest possible host for a full-screen fragment shader: a raw WebGL2 context, one buffer, one triangle whose vertices sit at (-1,-1), (3,-1) and (-1,3). The clipped triangle covers the viewport exactly, so there is no diagonal seam and no doubly-shaded band where two triangles would meet. Pass any GLSL ES 3.00 fragment source and it runs against `v_uv`, `u_resolution`, `u_time` and `u_pointer`.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

One 3-vertex triangle covers the viewport and runs your fragment shader. No three, no ogl, no seam.

- Category: webgl
- Runtime cost: webgl
- Dependencies: none beyond React

## How it works

1. A single `Float32Array([-1,-1, 3,-1, -1,3])` is uploaded once as `STATIC_DRAW` and bound into a VAO. The vertex shader is `gl_Position = vec4(a_pos, 0.0, 1.0)` — the positions are already in clip space, so there is no model, view or projection matrix anywhere in the component.
2. `v_uv = a_pos * 0.5 + 0.5` gives uv 0..1 at the visible corners and uv 2.0 at the two overshooting vertices; the rasteriser clips the triangle to the viewport and interpolates the varying linearly, so the surviving fragments carry exactly the uv a two-triangle quad would have produced.
3. The context is requested with `antialias: false, depth: false, stencil: false, alpha: false` — a fullscreen pass has no polygon interiors to multisample and no depth to test, and every one of those buffers costs width x height x DPR bytes plus a resolve.
4. Uniform locations are resolved lazily and memoised in a `Map` keyed by name, because `getUniformLocation` is a synchronous driver round-trip and calling it per frame per uniform is the single most common cause of a raw-GL component being slower than a three.js one.
5. `u_pointer` is fed from `useSmoothPointer` with the y axis flipped (`1 - ny`), so the shader receives the same handedness as `gl_FragCoord`.
6. Resize writes `canvas.width/height` at `pixelRatio(maxDpr)` and calls `gl.viewport`, then draws one frame immediately — which is also the only draw that happens under reduced motion.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `TRIANGLE = [-1,-1, 3,-1, -1,3]`
  The minimum overshoot that still guarantees full coverage. With 1.0 instead of 3.0 you get a half-screen triangle; with 5.0 the uv range widens to 0..3 and any shader that assumes uv is 0..1 at the vertices misinterprets its own derivatives.
- `MAX_DPR = 2`
  Fragment count is quadratic in DPR. A fullscreen shader at DPR 3 costs 2.25x what it costs at 2 for no perceptible gain, and it is the usual reason a hero shader stutters on a phone but not on the laptop it was built on.
- `pointer smoothing = 0.002`
  Fraction of the pointer gap remaining after one second. Raw pointer coordinates arrive in 8-16 ms bursts and pushing them straight into a uniform makes the light jitter one pixel per event.

## API

```ts
function FullscreenTrianglePass(props: { fragment?: string; uniforms?: Record<string, number | readonly number[]>; speed?: number; maxDpr?: number; className?: string }): JSX.Element
```

- `fragment: string` — default `FULLSCREEN_TRIANGLE_FRAG`
  GLSL ES 3.00 fragment source. Must open with `#version 300 es` and declare an `out vec4`. Changing it relinks the program.
- `uniforms: Record<string, number | readonly number[]>`
  Extra uniforms pushed every frame. Numbers become `uniform1f`; arrays of length 2/3/4 become `uniform2f`/`3f`/`4f`.
- `speed: number` — default `1`
  Multiplier applied to `u_time`.
- `maxDpr: number` — default `2`
  Upper bound on device pixel ratio.
- `className: string`
  Merged onto the host element.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/* Two vertices outside the viewport, one at the origin corner. Anything larger
   than 3.0 also works; 3.0 is the minimum that guarantees full coverage. */
const TRIANGLE = new Float32Array([-1, -1, 3, -1, -1, 3]);
const MAX_DPR = 2;

interface Pass {
  gl: WebGL2RenderingContext;
  program: WebGLProgram;
  vao: WebGLVertexArrayObject;
  buffer: WebGLBuffer;
  locations: Map<string, WebGLUniformLocation | null>;
}

function compileShader(
  gl: WebGL2RenderingContext,
  type: number,
  source: string,
): WebGLShader | null {
  const shader = gl.createShader(type);
  if (!shader) return null;
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
    // Log rather than throw: a shader that fails to compile should degrade to
    // the static fallback, not take the whole React tree down with it.
    console.error('[fullscreen-triangle-pass]', gl.getShaderInfoLog(shader));
    gl.deleteShader(shader);
    return null;
  }
  return shader;
}

function createPass(gl: WebGL2RenderingContext, fragment: string): Pass | null {
  const vert = compileShader(gl, gl.VERTEX_SHADER, FULLSCREEN_TRIANGLE_VERT);
  const frag = compileShader(gl, gl.FRAGMENT_SHADER, fragment);
  const program = gl.createProgram();
  if (!vert || !frag || !program) {
    if (vert) gl.deleteShader(vert);
    if (frag) gl.deleteShader(frag);
    if (program) gl.deleteProgram(program);
    return null;
  }

  gl.attachShader(program, vert);
  gl.attachShader(program, frag);
  gl.linkProgram(program);
  // Safe to delete immediately after linking — the program holds a reference.
  gl.deleteShader(vert);
  gl.deleteShader(frag);

  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
    console.error('[fullscreen-triangle-pass]', gl.getProgramInfoLog(program));
    gl.deleteProgram(program);
    return null;
  }

  const vao = gl.createVertexArray();
  const buffer = gl.createBuffer();
  if (!vao || !buffer) {
    gl.deleteProgram(program);
    return null;
  }

  gl.bindVertexArray(vao);
  gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
  gl.bufferData(gl.ARRAY_BUFFER, TRIANGLE, gl.STATIC_DRAW);
  const attrib = gl.getAttribLocation(program, 'a_pos');
  if (attrib >= 0) {
    gl.enableVertexAttribArray(attrib);
    gl.vertexAttribPointer(attrib, 2, gl.FLOAT, false, 0, 0);
  }
  gl.bindVertexArray(null);

  return { gl, program, vao, buffer, locations: new Map() };
}

/** Uniform locations are stable for the life of a program — look up once. */
function uniformLocation(pass: Pass, name: string): WebGLUniformLocation | null {
  const cached = pass.locations.get(name);
  if (cached !== undefined) return cached;
  const found = pass.gl.getUniformLocation(pass.program, name);
  pass.locations.set(name, found);
  return found;
}

function setUniform(
  gl: WebGL2RenderingContext,
  location: WebGLUniformLocation | null,
  value: UniformValue,
): void {
  // Null means the uniform was optimised out because the shader never reads
  // it. Silently skipping is correct; calling uniform*f with null is a no-op
  // that some drivers log as an error every frame.
  if (location === null) return;
  if (typeof value === 'number') {
    gl.uniform1f(location, value);
    return;
  }
  const a = value[0] ?? 0;
  const b = value[1] ?? 0;
  const c = value[2] ?? 0;
  const d = value[3] ?? 0;
  if (value.length === 2) gl.uniform2f(location, a, b);
  else if (value.length === 3) gl.uniform3f(location, a, b, c);
  else if (value.length >= 4) gl.uniform4f(location, a, b, c, d);
  else gl.uniform1f(location, a);
}

function disposePass(pass: Pass): void {
  const { gl } = pass;
  gl.deleteVertexArray(pass.vao);
  gl.deleteBuffer(pass.buffer);
  gl.deleteProgram(pass.program);
  // dispose alone leaves the context alive; only the extension hands it back.
  loseContext(gl);
}

export function FullscreenTrianglePass({
  fragment = FULLSCREEN_TRIANGLE_FRAG,
  uniforms,
  speed = 1,
  maxDpr = MAX_DPR,
  className,
}: FullscreenTrianglePassProps) {
  const host = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const passRef = useRef<Pass | null>(null);

  const { width, height } = useResizeObserver(host);
  const reduced = useReducedMotion();
  const visible = useVisibility();
  const pointer = useSmoothPointer({ target: host, smoothing: 0.002 });
  const [supported, setSupported] = useState(true);

  // Held in refs so a changed uniform object never re-creates the program.
  const uniformsRef = useRef(uniforms);
  uniformsRef.current = uniforms;
  const speedRef = useRef(speed);
  speedRef.current = speed;

  const drawRef = useRef<(elapsed: number) => void>(() => {});
  drawRef.current = (elapsed: number) => {
    const pass = passRef.current;
    if (!pass) return;
    const { gl } = pass;

    gl.useProgram(pass.program);
    setUniform(gl, uniformLocation(pass, 'u_resolution'), [
      gl.drawingBufferWidth,
      gl.drawingBufferHeight,
    ]);
    setUniform(gl, uniformLocation(pass, 'u_time'), elapsed * speedRef.current);
    const p = pointer.current;
    // Flip y: DOM coordinates grow downward, gl_FragCoord grows upward.
    setUniform(gl, uniformLocation(pass, 'u_pointer'), [p.nx, 1 - p.ny]);

    const extra = uniformsRef.current;
    if (extra) {
      for (const name of Object.keys(extra)) {
        const value = extra[name];
        if (value !== undefined) setUniform(gl, uniformLocation(pass, name), value);
      }
    }

    gl.bindVertexArray(pass.vao);
    gl.drawArrays(gl.TRIANGLES, 0, 3);
    gl.bindVertexArray(null);
  };

  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;
    if (!hasWebGL()) {
      setSupported(false);
      return;
    }

    // `antialias: false` — a fullscreen pass has no polygon edges to smooth,
    // so MSAA buys nothing and costs a multisample resolve every frame.
    const gl = canvas.getContext('webgl2', {
      antialias: false,
      alpha: false,
      depth: false,
      stencil: false,
      powerPreference: 'high-performance',
    });
    if (!gl) {
      setSupported(false);
      return;
    }

    const pass = createPass(gl, fragment);
    if (!pass) {
      loseContext(gl);
      setSupported(false);
      return;
    }
    passRef.current = pass;
    setSupported(true);

    return () => {
      passRef.current = null;
      disposePass(pass);
    };
  }, [fragment]);

  // Resize and the static frame share one effect: whenever the backing store
  // changes we must redraw, and under reduced motion that redraw is the only
  // one that ever happens.
  useEffect(() => {
    const canvas = canvasRef.current;
    const pass = passRef.current;
    if (!canvas || !pass || width === 0 || height === 0) return;

    const dpr = pixelRatio(maxDpr);
    const w = Math.max(1, Math.round(width * dpr));
    const h = Math.max(1, Math.round(height * dpr));
    if (canvas.width !== w || canvas.height !== h) {
      canvas.width = w;
      canvas.height = h;
    }
    pass.gl.viewport(0, 0, w, h);
    drawRef.current(0);
  }, [width, height, maxDpr, supported, fragment]);

  const running = supported && visible && !reduced && width > 0 && height > 0;
  useRaf((_dt, elapsed) => drawRef.current(elapsed), running);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Deletes the VAO, the vertex buffer and the program, then calls `loseContext(gl)` to hand the WebGL context back to the browser. The rAF subscription unsubscribes with the hook. The effect is keyed on `fragment`, so a source change tears the old program down before building the new one rather than leaking it.

**Reduced motion.** The rAF subscription never starts. The pass still draws exactly one frame on mount and one on every resize, so you get a fully composed still image rather than a blank canvas — `u_time` is pinned to 0 and the pointer light sits wherever it was seeded.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Putting a newline, a comment, or a leading space before `#version 300 es`. The directive must be the first token in the source or the compile fails with "version directive must occur before anything else", and because the shader source lives in a template literal the offending newline is invisible in the diff.
- Drawing a quad out of two triangles. GPUs shade in 2x2 fragment quads, so every quad the shared diagonal crosses is rasterised by both triangles and those fragments are shaded twice — a band of pure waste down the diagonal. It also breaks `fwidth`/`dFdx` across the seam, which shows up as a visible hairline in any analytic-AA shader.
- Calling `gl.getUniformLocation` inside the render loop. It is a driver round-trip, not a hash lookup; the locations are constant for the life of the program, so resolve them once and cache them.
- Passing a uniform that the shader never reads. `getUniformLocation` returns `null` for anything the compiler optimised out, and `gl.uniform1f(null, x)` is a silent no-op that some drivers log to the console 60 times a second. Skip on null.
- Calling `renderer.dispose()` or just dropping the canvas and assuming the context is released. Only `WEBGL_lose_context.loseContext()` hands it back, and Chromium kills the OLDEST live context when a page exceeds roughly 16 — so a leaked context here makes an unrelated component elsewhere on the page go black.
- Throwing on a shader compile error. A syntax error in a user-supplied fragment then unmounts the entire React subtree; logging the info log and falling back to the static poster keeps the page alive and puts the actual error in the console.

## Notes

- WebGL2 only. GLSL ES 3.00 gives `in`/`out`, integer bit operators and core derivatives without an extension dance; WebGL2 is available in every browser that has shipped since 2021 except pre-15.4 Safari, which the `hasWebGL` guard catches.
- Everything else in the WebGL category that does not use three.js is built on this exact pass — it is the shared floor, not a demo.

## Definition of done

The grid fills the frame edge to edge with no lighter or darker band along either diagonal, and the fine grid brightens under the cursor. Resize the container and the grid stays square with hairlines exactly one pixel wide at any DPR. Unmount and `WEBGL_lose_context` fires — mount and unmount twenty times and the twenty-first still renders instead of going black.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: GPU Cubic-Bezier Burst

Concentric rings of dots turning slowly. Fire a sector — by clicking it, or by waiting for the automatic cycle — and its particles burst outward and fade, each one following its own cubic-bezier curve. The curve is the same four numbers CSS takes, but solved per vertex per frame by Newton's method, which is what lets two hundred particles carry two hundred different easings while the CPU only advances a clock.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Rings of dots that burst on click, every particle solving its own cubic-bezier easing in the vertex shader.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. A cubic bezier is parametric: for a parameter `t` it gives a point `(x(t), y(t))`. Easing needs `y` at a given *x*, and a cubic has no closed-form inverse, so the shader runs Newton's method — 8 iterations of `t -= (x(t) - target) / x'(t)`, seeded with `t = x` because the curve is monotonic in x — then evaluates `y(t)`.
2. The four control numbers ride in an `aBezier` attribute rather than a uniform. That is the whole reason to solve on the GPU: a uniform would give every particle in the burst one shared easing, and per-particle easing computed on the CPU would mean a buffer upload every frame.
3. Firing writes the current burst-clock time into a contiguous slice of the `aStart` attribute — one sector, one range, one `needsUpdate`. Each particle then computes `age = uBurstTime - aStart - delay` and animates only while `0 <= age <= uBurstDuration`; a start time of 0 means never fired, which is why the clock starts at 1.
4. Resting dots and burst particles live in the same buffer and the same draw call, distinguished by an `isBurst` flag. Burst particles sit invisible on the outer ring until fired, rather than the resting dots being displaced — displacing them would tear a hole in the ring and then pop it shut when the burst ended.
5. There are two clocks. `uRotation` accumulates from delta time only when motion is allowed; `uBurstTime` always accumulates. Under reduced motion the ring freezes at 0.35 rad and the automatic cycle stops, but a click still fires a full burst, and the frame loop is subscribed only for as long as one is in flight.
6. Flight direction is `angle + uRotation`, evaluated live rather than baked, so a burst stays radial to the ring while the ring keeps turning underneath it. Alpha fades linearly against the eased flight, and point size shrinks to 45%, so the particle dissipates instead of blinking out at full size.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `NEWTON_ITERATIONS = 8`
  Newton converges quadratically here, so 4 iterations already land inside a pixel. 8 is cheap insurance for control points near 0 or 1, where the derivative shrinks and convergence slows.
- `MIN_DERIVATIVE = 0.000001`
  Newton divides by the derivative. A curve with a flat segment divides by ~0, `t` becomes NaN, and the NaN propagates into `gl_Position` — the vertex silently disappears rather than erroring.
- `base curve = (0, 0.9, 0.5, 1)`
  A hard ease-out: almost all the distance is covered in the first third. Each particle jitters around it, with x-coordinates clamped to 0..1 because the solver needs monotonicity in x — the same constraint CSS puts on `cubic-bezier()`.
- `MAX_LAUNCH_DELAY = 0.09s`
  Particles all leaving on one frame read as a single expanding ring. Staggering launches over ~90ms reads as a spray, and staying well under `burstDuration` keeps the last launch ahead of the first landing.
- `burstDuration = 0.45s`
  Longer than the 0.25s a click ping wants, because at preview-card size the eye needs the extra frames to actually see the easing differ between particles. Shorten it toward 0.25 when the burst is real button feedback.
- `BURST_END_SIZE = 0.45`
  Particles shrink to 45% over the flight. Constant-size particles read as confetti; shrinking ones read as one thing dissipating.
- `STATIC_ROTATION = 0.35 rad`
  Angle the ring is frozen at under reduced motion. Off-axis, so the field does not look like it snapped to a grid the moment motion was disabled.
- `RING_DOT_SCALE / BURST_DOT_SCALE = 0.7 / 1.15`
  Burst particles are visibly larger than the resting field, so the burst reads as the event rather than as the ring shedding pixels.
- `flight fan = +/- 0.175 rad`
  Jitter added to each particle's radial direction. Pure radial launches leave on rails and the burst looks like a line drawing; more than ~0.3 rad and the sectors start to overlap.

## API

```ts
function GpuBezierBurst(props: { ringCount?: number; ringDots?: number; innerRadius?: number; groups?: number; burstDots?: number; spinSpeed?: number; chordInterval?: number; burstDuration?: number; burstRadius?: number; dotScale?: number; viewScale?: number; opacity?: number; color?: string; burstColor?: string; seed?: number | string; className?: string }): JSX.Element
```

- `ringCount: number` — default `4`
  Concentric rings in the resting field.
- `ringDots: number` — default `190`
  Dots on the outermost ring; inner rings scale down to keep density even.
- `innerRadius: number` — default `0.55`
  Radius of the innermost ring as a fraction of the outermost.
- `groups: number` — default `6`
  Sectors that can be fired independently.
- `burstDots: number` — default `34`
  Burst particles per sector.
- `spinSpeed: number` — default `0.18`
  Ambient ring rotation in radians per second.
- `chordInterval: number` — default `1.5`
  Seconds between automatic firings.
- `burstDuration: number` — default `0.45`
  Seconds a single particle's flight lasts.
- `burstRadius: number` — default `26`
  How far a particle travels, in CSS pixels.
- `dotScale: number` — default `1`
  Dot radius multiplier in CSS pixels.
- `viewScale: number` — default `0.4`
  Model-to-pixel scale as a fraction of the container short side.
- `opacity: number` — default `1`
  Multiplier applied to every dot.
- `color: string` — default `'#6f757e'`
  Resting dot colour.
- `burstColor: string` — default `'#ffffff'`
  Colour mixed in at the hot start of a flight.
- `seed: number | string` — default `'gpu-bezier-burst'`
  Seeds every curve, delay and fan angle for a stable, hydration-safe field.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function GpuBezierBurst({
  ringCount = 4,
  ringDots = 190,
  innerRadius = 0.55,
  groups = 6,
  burstDots = 34,
  spinSpeed = 0.18,
  chordInterval = 1.5,
  burstDuration = 0.45,
  burstRadius = 26,
  dotScale = 1,
  viewScale = 0.4,
  opacity = 1,
  color = '#6f757e',
  burstColor = '#ffffff',
  seed = 'gpu-bezier-burst',
  className,
}: GpuBezierBurstProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  // Gates the frame loop under reduced motion: no ambient animation, but a
  // burst in flight still needs frames until it lands.
  const [burstLive, setBurstLive] = useState(false);

  const { width, height } = useResizeObserver(host);
  const size = useRef({ width, height });
  size.current = { width, height };

  const reduced = useReducedMotion();
  // Read inside the frame loop rather than closed over, so toggling the OS
  // setting does not tear down and rebuild the GL context.
  const reducedRef = useRef(reduced);
  reducedRef.current = reduced;

  const ready = width > 0 && height > 0;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    if (!hasWebGL()) {
      setUnsupported(true);
      return;
    }

    const renderer = new THREE.WebGLRenderer({ antialias: false, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setClearAlpha(0);

    const scene = new THREE.Scene();
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
    camera.position.z = 1;

    const rng = createRng(seed);

    const positions: number[] = [];
    const burstData: number[] = [];
    const bezier: number[] = [];

    /* ------------------------------------------------------------------
       Resting rings. Dot count scales with radius so the inner rings are
       not visibly denser than the outer ones — constant dots-per-ring is
       the classic tell of a generated field.
       ------------------------------------------------------------------ */
    for (let r = 0; r < ringCount; r += 1) {
      const t = ringCount === 1 ? 1 : r / (ringCount - 1);
      const radius = innerRadius + (1 - innerRadius) * t;
      const count = Math.max(8, Math.round(ringDots * radius));

      for (let i = 0; i < count; i += 1) {
        const angle = (i / count) * Math.PI * 2 + rng() * 0.01;
        positions.push(Math.cos(angle) * radius, Math.sin(angle) * radius, 0);
        // isBurst 0: these never move, so flight angle, delay and curve are unused.
        burstData.push(0, angle, RING_DOT_SCALE, 0);
        bezier.push(0, 0, 1, 1);
      }
    }

    /* ------------------------------------------------------------------
       Burst particles, grouped into contiguous sectors so firing one is a
       single contiguous write into the start-time buffer. They sit on the
       outer ring invisible until fired: displacing the resting dots
       instead would leave a hole in the ring, then pop them back.
       ------------------------------------------------------------------ */
    const groupRanges: { start: number; end: number }[] = [];
    const restingDots = positions.length / 3;
    const sector = (Math.PI * 2) / groups;

    for (let g = 0; g < groups; g += 1) {
      const start = positions.length / 3;
      const centre = g * sector;

      for (let i = 0; i < burstDots; i += 1) {
        const angle = centre + (rng() - 0.5) * sector * 0.9;
        const radius = 0.94 + rng() * 0.06;
        positions.push(Math.cos(angle) * radius, Math.sin(angle) * radius, 0);
        burstData.push(
          1,
          // Flight direction fans slightly off pure radial, so the burst
          // spreads instead of leaving on rails.
          angle + (rng() - 0.5) * 0.35,
          BURST_DOT_SCALE,
          rng() * MAX_LAUNCH_DELAY,
        );

        /* Each particle gets its own curve, jittered around an ease-out
           (0, 0.9, 0.5, 1). x-coordinates are clamped to 0..1 because the
           solver needs the curve monotonic in x — exactly the constraint
           CSS puts on cubic-bezier(). y is free to overshoot. */
        bezier.push(
          Math.min(1, Math.max(0, rng() * 0.25)),
          0.9 + (rng() - 0.5) * 0.3,
          Math.min(1, Math.max(0, 0.5 + (rng() - 0.5) * 0.4)),
          0.95 + rng() * 0.1,
        );
      }
      groupRanges.push({ start, end: positions.length / 3 });
    }

    const total = positions.length / 3;
    const starts = new Float32Array(total);

    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute('position', new THREE.BufferAttribute(Float32Array.from(positions), 3));
    geometry.setAttribute('aBurstData', new THREE.BufferAttribute(Float32Array.from(burstData), 4));
    geometry.setAttribute('aBezier', new THREE.BufferAttribute(Float32Array.from(bezier), 4));

    const startAttribute = new THREE.BufferAttribute(starts, 1);
    // The only buffer that changes at runtime, and only on a firing.
    startAttribute.setUsage(THREE.DynamicDrawUsage);
    geometry.setAttribute('aStart', startAttribute);

    const uniforms: Uniforms = {
      uBurstTime: { value: 0 },
      uRotation: { value: STATIC_ROTATION },
      uViewScale: { value: 1 },
      uPixelRatio: { value: renderer.getPixelRatio() },
      uDotScale: { value: dotScale },
      uOpacity: { value: opacity },
      uBurstDuration: { value: burstDuration },
      uBurstRadius: { value: burstRadius },
      uColor: { value: new THREE.Color(color) },
      uBurstColor: { value: new THREE.Color(burstColor) },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: GPU_BEZIER_BURST_VERT,
      fragmentShader: GPU_BEZIER_BURST_FRAG,
      uniforms,
      transparent: true,
      depthTest: false,
      depthWrite: false,
    });

    const points = new THREE.Points(geometry, material);
    // Vertices are unit-scale and the real placement happens in the shader, so
    // three's bounding sphere does not describe what is on screen.
    points.frustumCulled = false;
    scene.add(points);

    el.appendChild(renderer.domElement);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';

    /* -- the two clocks ------------------------------------------------ */
    let rotation = STATIC_ROTATION; // ambient; frozen under reduced motion
    let burstTime = 1; // feedback; always runs. Starts at 1 so a start
    //                    time of 0 can mean 'never fired'.
    let nextFire = chordInterval;
    let liveUntil = 0;
    let cursor = 0;

    const fire = (group: number) => {
      const range = groupRanges[group % groupRanges.length];
      if (!range) return;
      for (let i = range.start; i < range.end; i += 1) starts[i] = burstTime;
      startAttribute.needsUpdate = true;
      liveUntil = burstTime + burstDuration + MAX_LAUNCH_DELAY + 0.05;
      setBurstLive(true);
    };

    const render = () => renderer.render(scene, camera);

    const step = (dt: number) => {
      burstTime += dt;

      if (!reducedRef.current) {
        rotation += dt * spinSpeed;
        if (burstTime >= nextFire) {
          fire(cursor);
          cursor += 1;
          nextFire = burstTime + chordInterval;
        }
      } else if (burstTime > liveUntil) {
        // Nothing in flight and no ambient motion to draw: stand the loop
        // down. Idempotent, so this is safe to call every frame.
        setBurstLive(false);
      }

      uniforms.uRotation.value = rotation;
      uniforms.uBurstTime.value = burstTime;
      render();
    };

    const resize = (w: number, h: number) => {
      renderer.setSize(w, h, false);
      camera.left = -w / 2;
      camera.right = w / 2;
      camera.top = h / 2;
      camera.bottom = -h / 2;
      camera.updateProjectionMatrix();
      uniforms.uViewScale.value = Math.min(w, h) * viewScale;
      uniforms.uPixelRatio.value = renderer.getPixelRatio();
      render();
    };

    /* -- pointer: user-initiated, so it fires under reduced motion too -- */
    const onPointerDown = (event: PointerEvent) => {
      const rect = el.getBoundingClientRect();
      const x = event.clientX - rect.left - rect.width / 2;
      // Screen y grows downward, model y grows upward.
      const y = rect.height / 2 - (event.clientY - rect.top);
      // Undo the ambient rotation so the sector under the cursor is the one
      // that fires, not the one that was there before the ring turned.
      const angle = Math.atan2(y, x) - rotation;
      const normalised = ((angle % (Math.PI * 2)) + Math.PI * 2) % (Math.PI * 2);
      fire(Math.round(normalised / sector) % groups);
    };
    el.addEventListener('pointerdown', onPointerDown);

    resize(size.current.width, size.current.height);
    stage.current = { resize, step };

    return () => {
      stage.current = null;
      el.removeEventListener('pointerdown', onPointerDown);
      disposeObject(scene);
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
  }, [
    ready,
    ringCount,
    ringDots,
    innerRadius,
    groups,
    burstDots,
    spinSpeed,
    chordInterval,
    burstDuration,
    burstRadius,
    dotScale,
    viewScale,
    opacity,
    color,
    burstColor,
    seed,
  ]);

  useEffect(() => {
    stage.current?.resize(width, height);
  }, [width, height]);

  useRaf((dt) => stage.current?.step(dt), ready && !unsupported && (!reduced || burstLive));
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the pointerdown listener, nulls the stage ref so a queued frame cannot touch a dead renderer, disposes the geometry via `disposeObject(scene)`, disposes the material, calls `disposeRenderer` for `dispose` + `forceContextLoss` + a zeroed backing store, and removes the canvas. `useRaf` unsubscribes on unmount, so a StrictMode double-invoke leaves no orphaned context.

**Reduced motion.** The ambient rotation freezes at 0.35 rad and the automatic firing cycle stops, so nothing moves unprompted. A pointer press still fires a full burst, because that is feedback for something the user did rather than decoration. The frame loop is subscribed only while a burst is actually in flight and unsubscribes as soon as the last particle lands, so the idle cost is zero.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Freezing the burst along with the ambient rotation under reduced motion. The component then stops answering clicks, which is a broken interface, not an accessible one — feedback for a user action is not decoration, hence the two separate clocks.
- Leaving the frame loop running under reduced motion to keep the burst alive. It burns a GPU-backed rAF forever for a static image; subscribe only while a burst is in flight and stand down when it lands.
- Passing the control points as a uniform. It compiles, it animates, and every particle in the burst moves identically — the effect collapses into one expanding ring and the GPU solve buys nothing.
- Omitting the derivative guard in the Newton loop. Certain control points produce a near-zero derivative, `t` goes NaN, and the affected vertices vanish with no error anywhere — the symptom is a burst that is missing particles at some curves and not others.
- Displacing the resting ring dots instead of using dedicated burst particles. The ring develops a gap for the duration of the burst and snaps shut at the end.
- Baking the flight direction at fire time. The ring keeps rotating during the 0.45s flight, so the particles visibly drift off-radial and appear to curve away from their launch point.
- Sizing burst radius in model units. It then scales with the container, and the burst that felt right on a large canvas barely leaves the ring on a small preview card — pixels are the right unit for an effect this small.

## Notes

- One draw call and one buffer for the resting field and every burst particle. The only runtime upload is the start-time attribute, written once per firing rather than once per frame.
- Clicking maps the pointer angle back through the current rotation, so the sector under the cursor is the one that fires.
- The automatic cycle exists so the component reads as alive in a preview grid; drop `chordInterval` handling if the burst is wired to real user actions.

## Definition of done

Concentric rings of dots turn slowly. Roughly every 1.5 seconds one sector throws a spray of brighter particles outward that fade as they travel, and the particles visibly do not move in lockstep — some shoot ahead and settle, others trail. Clicking a sector fires it immediately. The ring never develops a gap where a burst came from. With reduced motion the ring is still and nothing fires on its own, but a click still produces a full burst.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: GSAP Cursor Follower

A container hides its native cursor and draws its own: a small disc that lags the pointer by a settling tween, and swells into a labelled puck whenever it passes over an element marked `data-cursor-target`. The lag comes from GSAP rather than from a damped rAF loop, which is why the disc comes to rest when the pointer stops instead of asymptoting toward it forever.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A puck that replaces the arrow inside a panel, trailing 0.4s behind and swelling to a label over targets.

- Category: cursor
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. On mount the puck is centred on its own coordinates with `gsap.set(circle, { xPercent: -50, yPercent: -50 })` and the positioning wrapper is parked at `x: -999, y: -999`. From then on the follow tween writes raw x/y and the centring composes into the same matrix, so there is no per-move offset arithmetic and exactly one composited transform per node.
2. Every `pointermove` issues `gsap.to(wrapper, { x: e.clientX - rect.left, y: e.clientY - rect.top, duration, ease: "power2.out", overwrite: "auto" })`. `overwrite: "auto"` retires the previous tween so the ~120 events a second do not accumulate into ~120 concurrent tweens writing the same transform.
3. This is deliberately GSAP smoothing rather than `useSmoothPointer`. A tween re-eases from its current velocity to a *rest* at the target, so the puck decelerates into stillness the instant the pointer stops; an exponential `damp` never actually arrives. Reach for the damped hook when you want a value that is permanently chasing, and for this when you want it to settle.
4. `pointerenter` teleports first (`duration: 0`) and only then fades in, so re-entering the panel does not drag a visible streak across it from wherever the puck was last parked.
5. The hover state is delegated: one handler runs `e.target.closest("[data-cursor-target]")` per move and compares the result with the previous state, tweening `scale` on the disc and `autoAlpha`/`scale` on the label only on the transition. Scale — not width/height — keeps the resize on the compositor with no layout pass.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `PARK = -999`
  Initial x/y. The element exists from first paint but must be *nowhere*; at 0,0 it flashes in the top-left corner for the frames between mount and the first pointer event.
- `duration = 0.4`
  Seconds of catch-up. Below ~0.2 the puck is welded to the pointer and the trailing read disappears; past ~0.7 it feels detached from the hand and users start chasing it.
- `size = 16`
  Resting diameter. Small enough to point precisely with, large enough to see against a busy panel. Applied as `scale: size / targetSize` so only the transform changes.
- `targetSize = 112`
  Diameter over a target. It has to hold a short label at 14px with real breathing room — under ~90 the text touches the circle edge and the puck reads as a broken badge.
- `RESIZE_DURATION = 0.45`
  The swell. With `expo.out` this is almost all its motion in the first 120ms, which is what makes the state change feel like a snap rather than an inflation.
- `FADE_DURATION = 0.3`
  Enter/leave opacity. Fast enough that the puck is present before the user has moved a meaningful distance into the panel.

## API

```ts
function CursorFollower(props: { children: ReactNode; label?: string; duration?: number; size?: number; targetSize?: number; className?: string }): JSX.Element
```

- `children: ReactNode`
  Panel content. Anything inside carrying `data-cursor-target` triggers the labelled state.
- `label: string` — default `'View'`
  Text revealed inside the puck over a target.
- `duration: number` — default `0.4`
  Seconds of catch-up on the follow tween.
- `size: number` — default `16`
  Resting diameter in px.
- `targetSize: number` — default `112`
  Diameter over a target, in px. Also the disc's laid-out size.
- `className: string`
  Merged onto the root container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** Far outside any container, so the puck is nowhere until a pointer exists. */
const PARK = -999;
const FADE_DURATION = 0.3;
const RESIZE_DURATION = 0.45;

export function CursorFollower({
  children,
  label = 'View',
  duration = 0.4,
  size = 16,
  targetSize = 112,
  className,
}: CursorFollowerProps) {
  const root = useRef<HTMLDivElement>(null);
  const wrap = useRef<HTMLDivElement>(null);
  const disc = useRef<HTMLDivElement>(null);
  const text = useRef<HTMLSpanElement>(null);

  useEffect(() => {
    const el = root.current;
    const point = wrap.current;
    const circle = disc.current;
    const caption = text.current;
    if (!el || !point || !circle || !caption) return;

    // A coarse pointer has no hover state, so the puck could only ever exist
    // between pointerdown and pointerup — and `cursor: none` on a touch device
    // hides nothing while still suppressing the text-selection caret.
    if (!window.matchMedia('(pointer: fine)').matches) return;

    const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
    const follow = reduced ? 0 : duration;
    const fade = reduced ? 0 : FADE_DURATION;
    const resize = reduced ? 0 : RESIZE_DURATION;

    // Centre both layers on their own coordinates once. After this the follow
    // tween writes raw x/y and the centring composes into the same matrix —
    // no offset arithmetic per move, and one composited transform per node.
    gsap.set(point, { x: PARK, y: PARK, autoAlpha: 0 });
    gsap.set(circle, { xPercent: -50, yPercent: -50, scale: size / targetSize });
    gsap.set(caption, { xPercent: -50, yPercent: -50, autoAlpha: 0, scale: 0.5 });

    // The puck *replaces* the arrow rather than accompanying it. Set from JS,
    // not from the class list, so a touch device never loses its cursor.
    const previousCursor = el.style.cursor;
    el.style.cursor = 'none';

    let overTarget = false;

    const place = (e: PointerEvent, instant: boolean) => {
      // Live rect: the container can scroll, resize, or be inside a
      // transformed ancestor. A rect cached on mount puts the puck at a
      // constant offset from the real pointer as soon as anything moves.
      const rect = el.getBoundingClientRect();
      gsap.to(point, {
        x: e.clientX - rect.left,
        y: e.clientY - rect.top,
        duration: instant ? 0 : follow,
        ease: 'power2.out',
        // Each move REPLACES the last tween instead of queueing behind it.
        // Without it, ~120 events a second means ~120 live 0.4s tweens all
        // writing the same transform, and the puck visibly stutters.
        overwrite: 'auto',
      });
    };

    const onEnter = (e: PointerEvent) => {
      // Teleport on entry, then fade in. Tweening from wherever the puck was
      // parked draws a visible streak diagonally across the panel every time
      // the pointer re-enters.
      place(e, true);
      gsap.to(point, { autoAlpha: 1, duration: fade, ease: 'power2.out', overwrite: 'auto' });
    };

    const onMove = (e: PointerEvent) => {
      place(e, false);

      const hit =
        e.target instanceof Element ? e.target.closest('[data-cursor-target]') : null;
      const next = hit !== null;
      // Only tween on the transition. Re-firing the same resize tween on every
      // move restarts its ease and the puck never reaches the target size.
      if (next === overTarget) return;
      overTarget = next;

      gsap.to(circle, {
        scale: next ? 1 : size / targetSize,
        duration: resize,
        ease: 'expo.out',
        overwrite: 'auto',
      });
      gsap.to(caption, {
        autoAlpha: next ? 1 : 0,
        scale: next ? 1 : 0.5,
        duration: resize,
        ease: 'expo.out',
        overwrite: 'auto',
      });
    };

    const onLeave = () => {
      gsap.to(point, { autoAlpha: 0, duration: fade, ease: 'power2.out', overwrite: 'auto' });
    };

    el.addEventListener('pointerenter', onEnter);
    el.addEventListener('pointermove', onMove, { passive: true });
    el.addEventListener('pointerleave', onLeave);

    return () => {
      el.removeEventListener('pointerenter', onEnter);
      el.removeEventListener('pointermove', onMove);
      el.removeEventListener('pointerleave', onLeave);
      el.style.cursor = previousCursor;
      // Kill before clearing, or an in-flight tween writes the transform
      // straight back onto a node React has already recycled.
      gsap.killTweensOf([point, circle, caption]);
      gsap.set([point, circle, caption], { clearProps: 'all' });
    };
  }, [duration, size, targetSize]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the three container listeners, restores the container's previous inline `cursor`, calls `gsap.killTweensOf` on the wrapper, disc and label, then `gsap.set(..., { clearProps: "all" })`. Kill precedes clear so no in-flight tween can write the transform back after React has recycled the node.

**Reduced motion.** The puck still appears and still swells over targets — the affordance is preserved — but every duration collapses to 0, so it is welded to the pointer with no trailing lag and the size change is a hard cut. The native cursor stays hidden, because a container with no cursor at all would be worse than one that moves.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Calling `gsap.to` per pointermove without `overwrite: "auto"`. Sixty to a hundred and twenty 0.4s tweens end up live at once, all writing the same transform, and the puck stutters instead of gliding — the single most common way this effect is got wrong.
- Fading in without teleporting first. On every re-entry the puck tweens from its parked coordinates, drawing a diagonal streak across the whole panel before it reaches the pointer.
- Re-issuing the resize tween on every move instead of only on the hover transition. Each call restarts the `expo.out` ease from the beginning, so the puck creeps toward the target size and never gets there while the pointer keeps moving.
- Transitioning `width` and `height` for the swell. That is a layout write per frame on an element the compositor could otherwise leave alone; `scale` on a fixed-size disc is the same picture for free.
- Caching the container rect on mount. The panel scrolls, resizes, and may sit inside a transformed ancestor — a stale rect offsets the puck from the real pointer by a constant amount that never corrects itself.
- Putting `cursor: none` in the class list. It then applies on touch devices too, where it hides nothing but does suppress the text-selection caret; setting it from the effect means it only ever exists where the puck does.

## Notes

- Gated on `(pointer: fine)`. On touch nothing attaches: no listeners, no `cursor: none`, and the puck stays at `autoAlpha: 0` parked off-container, so a tap does not flash a disc at the touch point.
- Mark any element inside with `data-cursor-target` to trigger the labelled state — including elements nested arbitrarily deep, since the check is a `closest()` walk.
- The root sets `isolate`, so the puck stacks above the panel content without needing a page-level z-index.

## Definition of done

Move into the panel: the arrow disappears and a small disc arrives at the pointer without sweeping in from an edge, then trails about 0.4s behind as you move. Pass over a marked target and it swells into a labelled puck; leave and it shrinks back. Stop moving and it comes fully to rest rather than creeping. On a touch device the native cursor and all default behaviour are untouched.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Height-First Media Stage

Almost every media stage on the web is sized width-first: a full-width box with an aspect ratio and whatever height falls out of it. On a short laptop that makes a 3:2 hero taller than the viewport, so the piece built to be seen at a glance has to be scrolled. This inverts the constraint — the height is authored, the width is derived from it through `aspect-ratio`, and `max-width: 100%` is the only escape hatch. The stage always fits vertically, and on a narrow screen it gives up size rather than overflowing. Layers cross-fade on opacity alone; the only JavaScript is the index.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A media stage sized from its height, with the width derived from the ratio, cross-fading layers and a caption that replays per index.

- Category: layout
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. The figure gets exactly three sizing declarations: `height` (authored, e.g. `min(80dvh, 100%)`), `aspect-ratio` (which derives the width from that height), and `max-width: 100%`. No width is ever set — setting one would over-constrain the box and `aspect-ratio` would be ignored.
2. When the derived width would exceed the container, `max-width: 100%` clamps it and the ratio then pulls the *height* down to match. That single line is what turns "always fits vertically" into "always fits", with no media query and no measurement.
3. The default height is `min(80dvh, 100%)`: `dvh` so a collapsing mobile URL bar cannot make the stage overflow, and the `100%` term so the same component also behaves inside a bounded parent instead of insisting on a fraction of the viewport.
4. Every layer stays mounted, absolutely positioned in the same stacking context, and only `opacity` changes — from 0 to 1 on the incoming layer and back on the outgoing one, with `pointer-events: none` on the hidden ones so an invisible layer cannot swallow clicks meant for the visible one.
5. The cross-fade transition is `linear`, not eased. Two layers whose opacities are each eased sum to less than 1 halfway through, and the stage visibly dips darker mid-transition; linear keeps the sum at exactly 1 throughout.
6. The caption wrapper carries `key={current}`, so changing index unmounts it and mounts a fresh node. A CSS entrance animation that has never run on a node plays from 0%, which is how the caption re-enters on every change without any JavaScript replay logic.
7. The keyframes live in a scoped `<style href="..." precedence="medium">`. React 19 hoists it into the head and deduplicates by `href`, so ten mounted stages inject one copy and nothing has to be added to a global sheet.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `height = 'min(80dvh, 100%)'`
  80% of the *dynamic* viewport height leaves room for a header and the top of the next section, so the stage reads as part of a page rather than as a takeover. `dvh` rather than `vh` because on iOS Safari `vh` is the URL-bar-collapsed height, so `80vh` overflows the actually visible area at rest. The `min(..., 100%)` term keeps it correct inside a bounded parent.
- `aspectRatio = '3 / 2'`
  Wider than the 80dvh height on any landscape display, so the width clamp is the binding constraint on desktop and the height clamp binds on a phone — both paths are exercised by the default. A ratio taller than the height would make the stage narrower than its own caption row.
- `duration = 500`
  Milliseconds of cross-fade. Under ~250ms the two layers read as a cut and the point of stacking them is lost; past ~800ms both layers are legible at once for long enough to look like a rendering fault.
- `caption entrance = 500ms cubic-bezier(0.22, 1, 0.36, 1), translateY(14px)`
  Matched to the cross-fade duration so caption and image resolve together. 14px is roughly one line of the caption type — enough travel to read as arrival, small enough that the text is never legible in the wrong place.
- `cross-fade easing = linear`
  Not a stylistic choice. Any easing applied to both layers makes their opacities sum to less than 1 in the middle of the transition, and the stage flashes darker halfway through every change.

## API

```ts
function HeightFirstMediaStage(props: { children: ReactNode; height?: string; aspectRatio?: string; duration?: number; caption?: (index: number) => ReactNode; index?: number; defaultIndex?: number; onIndexChange?: (index: number) => void; className?: string; 'aria-label'?: string }): JSX.Element
```

- `children: ReactNode`
  One media layer per child. All layers stay mounted and stacked.
- `height: string` — default `'min(80dvh, 100%)'`
  Authored height as a CSS length. The width is derived from it — never set a width here.
- `aspectRatio: string` — default `'3 / 2'`
  Ratio the derived width follows, as a CSS `aspect-ratio` value.
- `duration: number` — default `500`
  Cross-fade duration in milliseconds.
- `caption: (index: number) => ReactNode`
  Rendered into a node re-keyed on every index change, so its entrance keyframe replays.
- `index: number`
  Controlled index. Omit for uncontrolled behaviour.
- `defaultIndex: number` — default `0`
  Starting index when uncontrolled.
- `onIndexChange: (index: number) => void`
  Called with the wrapped index after either control is used.
- `className: string`
  Merged onto the centring wrapper via `cn`.
- `aria-label: string` — default `'Media stage'`
  Accessible name for the figure group.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * Scoped stylesheet. React 19 hoists and deduplicates it by `href`, so the
 * keyframe exists once no matter how many stages are mounted and nothing has
 * to be added to a global sheet.
 *
 * The class exists only so a `key` change can restart it: React unmounts the
 * old caption node and mounts a new one, the animation has never run on that
 * node, so it plays from 0%. Toggling a class on a persistent node would not
 * work — the animation would have to be removed for a frame first.
 */
const STAGE_CSS = `
@keyframes k-hfms-in {
  from { opacity: 0; transform: translateY(14px); }
  to   { opacity: 1; transform: translateY(0); }
}

.k-hfms-in {
  animation: k-hfms-in 500ms cubic-bezier(0.22, 1, 0.36, 1) both;
}

/* The caption's content is the information; its arrival is decoration. */
@media (prefers-reduced-motion: reduce) {
  .k-hfms-in { animation: none; }
}
`;
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nothing to release. There are no listeners, no rAF, no timers and no observers: the cross-fade and the caption entrance are both CSS on the elements themselves, so they die with the nodes. React 19 reference-counts the hoisted `<style>` and removes it when the last stage unmounts.

**Reduced motion.** The layer transition is set to `none`, so an index change is an instant cut between two fully opaque layers rather than a zero-length fade. The caption entrance is disabled by a `prefers-reduced-motion` block inside the scoped stylesheet, so the caption appears immediately at its final position and full opacity — the information still arrives, only its arrival is dropped. Sizing behaviour is identical either way.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Sizing width-first — `w-full` plus `aspect-ratio` — which is the common shape. On a 13" laptop the derived height exceeds the viewport, so the hero has to be scrolled to be seen and the layout silently breaks on exactly the machines designers use.
- Setting a width as well as the height. The box is then over-constrained, `aspect-ratio` is discarded, and the stage quietly stops being the ratio you asked for while still looking plausible in your own window.
- Using `vh` instead of `dvh`. On mobile Safari `100vh` is the tall viewport with the browser chrome hidden, so a stage sized against it overflows the visible area until the user scrolls — which is the exact failure this layout exists to prevent.
- Easing the opacity transition. Both layers dim toward the middle, their sum drops below 1, and the stage visibly darkens on every change. It looks like a dropped frame and is very hard to attribute to the easing curve.
- Mounting only the current layer. Each change then pays a fresh decode and paint, so the first frame of the incoming layer is empty and the transition starts from blank instead of from the outgoing image.
- Replaying the caption entrance by toggling a class on a persistent node. The animation is already applied, so re-adding the class does nothing — you would have to remove it, force a reflow, then re-add. Changing `key` remounts the node instead, and the animation runs because on that node it never has.
- Wrapping the index with `%`. In JavaScript `-1 % 5` is `-1`, so pressing Previous on the first item indexes past the start and the stage goes blank. `wrapIndex` uses a true modulo.
- Leaving hidden layers hittable. At `opacity: 0` a layer still receives pointer events and sits on top of the visible one, so links and buttons in the current layer stop responding.
- Putting the keyframes in a plain inline `<style>` with no `href`. Every mounted stage then injects its own copy of the same rule into the document.

## Notes

- Uncontrolled by default via `defaultIndex`, controlled when `index` is passed — in controlled mode the internal state is never written, so the parent stays the single source of truth.
- The figure is marked `role="group"` with `aria-roledescription="carousel"`, and non-current layers are `aria-hidden`, so a screen reader is offered one media layer at a time rather than all of them stacked.
- The only content this component draws itself is the counter and the controls; the layers are children, so it composes with a canvas, a video, a CSS gradient, or a Lottie without knowing which.

## Definition of done

Shorten the viewport to about 600px tall and the stage shrinks with it — no vertical scrollbar appears and no part of the media is cut off. Narrow the window until the derived width would exceed the container and the stage gives up height instead of clipping sideways. Press Next and the layers cross-fade with no dark dip halfway through, and the caption rises 14px into place on every change including the wrap from the last item back to the first. Press Previous on the first item and it lands on the last, not on a blank stage. Enable reduced motion and the change becomes an instant cut with the caption already in place.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Hinged Container Intro

A page-enter that tips its container up from below the fold like a lid rather than sliding it in. The panel starts at 120% of its own height, rotated -45deg in X about its bottom edge, and lands over 1.4s on expo.out; captions inside it stagger in starting 0.6s before it arrives. A cue fires at 0.8s so an expensive scene can start while the panel is still in flight.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

The page body swings up from below the fold, hinged on its own bottom edge, with captions following it in.

- Category: transition
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. A wrapper carries `perspective: 1200px` and the panel inside it gets `transformOrigin: "center bottom"` plus `transformPerspective`, so the rotation pivots on the edge the panel is about to rest on and the top edge sweeps a much longer arc than the bottom.
2. The panel tween is `fromTo(el, { yPercent: 120, rotateX: -45, opacity: 0 }, { yPercent: 0, rotateX: 0, opacity: 1, duration: 1.4, ease: "expo.out" })`. `yPercent` rather than a viewport unit means the same component works inside a 320px card and a full-bleed layout without re-tuning.
3. Elements matching `detailSelector` are collected with `querySelectorAll` on the panel and appended at `"-=0.6"`, so their 0.9s stagger overlaps the tail of the flight and the two moves read as one gesture.
4. A `tl.call(cue, undefined, 0.8)` sits at an absolute timeline position, so the cue stays at 0.8s even if either tween is retimed. That is where a WebGL scene, a video `play()`, or a data fetch is kicked off — mid-flight, while the eye is on the moving panel.
5. The whole timeline is built inside `useGsap`, keyed on `routeKey`; a key change reverts the previous context (restoring the inline styles GSAP wrote) and builds a fresh timeline from frame zero.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `duration = 1.4`
  Panel flight in seconds. Under ~1.1s the expo.out tail is too short to read as deceleration and the panel appears to snap; over ~1.8s the visitor is waiting on chrome before they can read anything.
- `tilt = -45`
  Degrees of X rotation at the start. At -20deg the perspective foreshortening is barely visible so it looks like a plain slide; past about -70deg the panel is nearly edge-on and its content is an unreadable sliver for most of the flight.
- `travel = 120`
  Percent of the panel's own height it starts below rest. 100 would put its top edge exactly at the bottom of its box, but the rotation lifts the top edge upward, so 100 lets a corner peek in at frame zero. The extra 20% covers the rotated bounding box.
- `perspective = 1200`
  Pixels. Around 600 the lens is wide enough that the panel visibly skews toward one corner; above ~2000 the projection is near-orthographic and the hinge stops reading as depth.
- `DETAIL_OVERLAP = 0.6`
  Seconds the caption stagger starts before the panel lands. At 0 the two moves read as two separate events with a dead beat between them; beyond ~0.9 the captions are moving while the panel is still steeply rotated and the text shears.
- `DETAIL_STAGGER = 0.1`
  Seconds between captions. Fast enough that three to five items finish inside the panel tween, slow enough that each is individually perceptible.
- `sceneCue = 0.8`
  Seconds into the timeline before the heavy cue fires. Late enough that the panel has visually committed to arriving (so a first-frame stall is hidden by motion), early enough that a 1.6s scene intro finishes about 1s after the panel lands rather than long after.

## API

```ts
function HingedContainerIntro(props: { children: ReactNode; routeKey?: string; duration?: number; tilt?: number; travel?: number; perspective?: number; detailSelector?: string; onSceneCue?: () => void; sceneCue?: number; className?: string }): JSX.Element
```

- `children: ReactNode`
  Page body. Rendered inside the hinging panel.
- `routeKey: string`
  Change to replay. Pass `usePathname()` in an App Router layout.
- `duration: number` — default `1.4`
  Panel flight time in seconds.
- `tilt: number` — default `-45`
  Starting X rotation in degrees.
- `travel: number` — default `120`
  Starting offset as a percentage of the panel's own height.
- `perspective: number` — default `1200`
  Perspective on the wrapper, in pixels.
- `detailSelector: string` — default `'[data-hinge-detail]'`
  Descendants that stagger in behind the panel.
- `onSceneCue: () => void`
  Called `sceneCue` seconds in. Start expensive work here.
- `sceneCue: number` — default `0.8`
  Absolute timeline position of the cue, in seconds.
- `className: string`
  Merged onto the perspective wrapper.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function HingedContainerIntro({
  children,
  routeKey,
  duration = 1.4,
  tilt = -45,
  travel = 120,
  perspective = 1200,
  detailSelector = '[data-hinge-detail]',
  onSceneCue,
  sceneCue = 0.8,
  className,
}: HingedContainerIntroProps) {
  const root = useRef<HTMLDivElement>(null);
  const panel = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();

  // Held in a ref so a caller passing an inline arrow does not have to
  // memoise it to avoid replaying the whole intro on every parent render.
  const cue = useRef(onSceneCue);
  cue.current = onSceneCue;

  useGsap(
    gsap,
    () => {
      const el = panel.current;
      if (!el || reduced) return;

      const details = Array.from(el.querySelectorAll<HTMLElement>(detailSelector));
      const tl = gsap.timeline({ defaults: { ease: 'expo.out' } });

      // transformOrigin bottom + negative rotateX is the whole trick: the
      // panel pivots on the edge it is about to sit on, so the top edge
      // travels much further than the bottom and the move reads as a hinge
      // instead of a translation with a tilt bolted on.
      tl.fromTo(
        el,
        {
          yPercent: travel,
          rotateX: tilt,
          opacity: 0,
          transformOrigin: 'center bottom',
          transformPerspective: perspective,
        },
        { yPercent: 0, rotateX: 0, opacity: 1, duration },
      );

      // Guarded: GSAP logs "target not found" for an empty array, and a
      // component that warns on every mount trains people to ignore the
      // console.
      if (details.length > 0) {
        tl.fromTo(
          details,
          { opacity: 0, y: 30 },
          { opacity: 1, y: 0, duration: DETAIL_DURATION, stagger: DETAIL_STAGGER },
          `-=${DETAIL_OVERLAP}`,
        );
      }

      // A number position is absolute on the timeline, so the cue stays at
      // 0.8 s no matter how the two tweens above are retimed.
      tl.call(
        () => {
          cue.current?.();
        },
        undefined,
        sceneCue,
      );
    },
    root,
    [routeKey, reduced],
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useGsap` reverts the `gsap.context` on unmount and on every `routeKey` change, which kills the timeline and restores the inline styles GSAP wrote to the panel and captions. The cue callback lives in a ref that React discards with the component, so a call queued at 0.8s cannot reach a stale closure.

**Reduced motion.** No timeline is built. A `prefers-reduced-motion` rule in the component's own stylesheet cancels the `opacity: 0` start state, so the panel and its captions render in their final position immediately, and `onSceneCue` fires on mount so anything it gates still loads.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Setting the start state only inside the effect. `useEffect` can run after the browser has painted, so the finished page flashes for one frame and then jumps below the fold. The start state is a CSS rule on `[data-hinged-panel]`; the reduced-motion branch of that same rule is what keeps the content from depending on JS at all.
- Rotating without `transformOrigin: "center bottom"`. About the centre the panel appears to tumble through its own resting position, and the bottom edge dips below the fold on the way in.
- Putting `perspective` on the panel instead of an ancestor. Then any transformed child gets its own vanishing point and the parallax between panel and captions is wrong at the edges.
- Positioning the cue with a relative `"-=0.6"` string. Retiming the panel tween silently moves the cue with it; a numeric position pins it to 0.8s absolute.
- Firing the cue only in the animated branch. Reduced-motion users then never get the scene, the video or the fetch it was gating — the cue is content delivery, not decoration.
- Passing an inline arrow as `onSceneCue` and putting it in the effect deps. Every parent render rebuilds the timeline and the intro restarts mid-flight; the callback is held in a ref instead.

## Notes

- App Router wiring: render this inside `app/layout.tsx` around `{children}` and pass `routeKey={usePathname()}`. The component itself never imports a router, so the same file works in Pages Router, Remix, or a modal keyed on a record id.
- The cue is not a substitute for a load event. If the thing it starts can fail, give it its own timeout — see `safe-preloader` for the ceiling pattern.

## Definition of done

On mount the panel rises from below with its top edge visibly further away than its bottom, settles without overshoot, and the captions land about a third of a second later. Switching route replays it from frame zero with no flash of the previous content. With reduced motion on, the panel is simply there, and the cue still fires.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Hover List Image Trail

Each row entered adds a plate to a column beside the list, and the column follows the pointer vertically with `quickTo`. Every plate is a masked-reveal pair — a clipping wrapper sliding up while the canvas inside slides down — and the stack is bounded by culling the oldest node rather than by pooling.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Hovering a row stacks a plate into a column that follows the pointer; the oldest is culled past twenty.

- Category: cursor
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. The spawn is two elements on one tween, moving in opposite directions. The wrapper animates `yPercent` from 100 to 0 while the canvas inside it animates from -100 to 0, on the same duration and the same ease. Because the wrapper clips, the two motions cancel and the plate is uncovered in place instead of flying in — the difference between a card arriving and a card being developed.
2. The cancellation only holds if both tweens share duration and ease exactly. Any mismatch and the plate visibly slides inside its own frame, which reads as a parallax bug rather than a reveal.
3. A node is created per hover and the stack is bounded by a cull, which is the deliberate opposite of `pooled-image-trail`. That is affordable here because hover entry is bounded by how fast a human can cross rows — roughly ten a second at worst — where a pointermove trail is bounded by the display refresh rate. The choice between pooling and culling follows from the event arrival rate, not from taste.
4. Every spawn drops the oldest node once the stack holds twenty, so the DOM has a hard ceiling at all times rather than a ceiling per interaction. Tweens are killed before removal so GSAP cannot write to a node the DOM has already released.
5. The column is centred on the pointer once with `gsap.set(stack, { yPercent: -50 })`, so the follow tween writes a raw `y` and never subtracts a half-height it would have to re-measure. A single `quickTo` at 0.5s with `power4` gives a long, heavy tail: `power4` spends most of its time near the destination, so the column snaps toward the pointer and then settles.
6. Plates are painted once into offscreen canvases at mount and blitted with a single `drawImage` on spawn, so no gradient, sheen or text work lands on the frame where a tween starts — the one frame that cannot afford it. There are no image assets and nothing allocated through `createObjectURL`, so nothing needs revoking.
7. `pointerover` bubbles, so one listener covers every row however React re-renders the list, but it also fires again for each descendant crossed inside the same row. The spawn is therefore gated on `relatedTarget` being outside the row, which turns "the event fired" into "the pointer actually changed rows".

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `MAX_PLATES = 20`
  Hard ceiling on live plates. Enough that a quick scan down a list leaves a visible stack with depth; low enough that twenty composited layers of 168x116 stay trivial. Remove this and an idle user running the pointer up and down the list allocates for as long as the page is open.
- `REVEAL_DURATION = 0.6`
  Seconds for the masked pair. Long for a hover response, deliberately: the reveal is the content of the interaction, not feedback about it. Below ~0.35 the opposite-direction pair is too fast to read as a reveal and just looks like a fade.
- `ease: 'expo.inOut' = expo.inOut`
  The most extreme standard curve, and the reason the reveal reads as mechanical rather than soft. Nearly all the travel happens in the middle third, so the plate is still at the start of its move, then has arrived, with very little visible in between.
- `followDuration = 0.5`
  Seconds of catch-up on the column. Longer than a cursor follow because the column is a heavy object carrying several plates; at 0.2 it is welded to the pointer and the stack stops feeling like it has mass.
- `follow ease 'power4' = power4 (in-out)`
  A very late curve, so the column covers the gap early and creeps the last few pixels. quickTo remutates the end value on every event, so an in-out curve absorbs direction changes instead of restarting an outward ramp each time.
- `PLATE_SCALE = 2`
  Backing-store multiplier for the offscreen plates. Fixed rather than `devicePixelRatio` so the drawn output is byte-identical on every machine and a screenshot diff of this component is meaningful.
- `hue step = 137.508 degrees`
  The golden angle. Consecutive plates are always far apart in hue and the sequence never repeats a near-duplicate, so a fast scan down the list never stacks two plates that read as the same colour.
- `monotonic zIndex = order += 1, never reset`
  A later plate must always sit above an earlier one. Reusing or resetting the counter lets two live plates tie, and tied z-indices resolve by DOM order, which changes as the cull removes nodes — the observable symptom is a plate flickering behind one that arrived before it.

## API

```ts
function HoverListImageTrail(props: { rows: TrailRow[]; tileWidth?: number; tileHeight?: number; followDuration?: number; seed?: string; className?: string }): JSX.Element
```

- `rows: TrailRow[]`
  List rows. `{ id, label, meta? }`; one plate is painted per row at mount.
- `tileWidth: number` — default `168`
  Plate width in CSS px.
- `tileHeight: number` — default `116`
  Plate height in CSS px.
- `followDuration: number` — default `0.5`
  Seconds of catch-up on the column follow.
- `seed: string` — default `'hover-list-image-trail'`
  Seeds the plate palette. Same seed, same colours, every render.
- `className: string`
  Merged onto the root container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const PLATE_SCALE = 2;
/** Hard ceiling on live plates. Every spawn past this drops the oldest. */
const MAX_PLATES = 20;
const REVEAL_DURATION = 0.6;

/**
 * Plates are painted once into offscreen canvases and blitted on spawn. No
 * image assets, and — more importantly — no gradient, text or shadow work on
 * the frame where a tween starts, which is exactly the frame that cannot
 * afford it.
 */
function paintPlate(
  ctx: CanvasRenderingContext2D,
  w: number,
  h: number,
  index: number,
  seed: string,
) {
  // Seeded, never `Math.random()`: the plate colours must be identical on the
  // server and the client, and identical across reloads so a visual diff of
  // this component means something.
  const rng = createRng(`${seed}-${index}`);
  // Golden-angle hue walk: consecutive plates are always far apart in hue, so
  // a fast scan down the list never stacks two similar colours.
  const hue = (index * 137.508 + rng() * 18) % 360;

  const bg = ctx.createLinearGradient(0, 0, w, h);
  bg.addColorStop(0, `hsl(${hue} 46% 26%)`);
  bg.addColorStop(1, `hsl(${(hue + 44) % 360} 52% 13%)`);
  ctx.fillStyle = bg;
  ctx.fillRect(0, 0, w, h);

  // A soft off-centre sheen so the plate has a light direction rather than
  // reading as a flat swatch.
  const sheen = ctx.createRadialGradient(w * 0.3, h * 0.22, 0, w * 0.3, h * 0.22, h * 1.15);
  sheen.addColorStop(0, 'rgba(255,255,255,0.22)');
  sheen.addColorStop(1, 'rgba(255,255,255,0)');
  ctx.fillStyle = sheen;
  ctx.fillRect(0, 0, w, h);

  ctx.strokeStyle = 'rgba(255,255,255,0.14)';
  ctx.lineWidth = 1;
  ctx.strokeRect(0.5, 0.5, w - 1, h - 1);

  ctx.fillStyle = 'rgba(255,255,255,0.82)';
  ctx.font = `500 ${Math.round(h * 0.19)}px ui-monospace, SFMono-Regular, Menlo, monospace`;
  ctx.textBaseline = 'alphabetic';
  ctx.fillText(String(index + 1).padStart(2, '0'), w * 0.07, h * 0.88);
}

export function HoverListImageTrail({
  rows,
  tileWidth = 168,
  tileHeight = 116,
  followDuration = 0.5,
  seed = 'hover-list-image-trail',
  className,
}: HoverListImageTrailProps) {
  const root = useRef<HTMLDivElement>(null);
  const column = useRef<HTMLDivElement>(null);
  const plates = useRef<HTMLCanvasElement[]>([]);

  // Paint one plate per row, once. Re-running only when the geometry or the
  // row count actually changes — not on every render.
  useEffect(() => {
    const bw = tileWidth * PLATE_SCALE;
    const bh = tileHeight * PLATE_SCALE;
    const made: HTMLCanvasElement[] = [];

    for (let i = 0; i < rows.length; i += 1) {
      const canvas = document.createElement('canvas');
      canvas.width = bw;
      canvas.height = bh;
      const ctx = canvas.getContext('2d');
      if (!ctx) continue;
      ctx.scale(PLATE_SCALE, PLATE_SCALE);
      paintPlate(ctx, tileWidth, tileHeight, i, seed);
      made.push(canvas);
    }

    plates.current = made;
    return () => {
      // Plain canvases: nothing was allocated through `createObjectURL`, so
      // there is nothing to revoke. Dropping the references is the disposal.
      plates.current = [];
    };
  }, [rows.length, tileWidth, tileHeight, seed]);

  useEffect(() => {
    const el = root.current;
    const stack = column.current;
    if (!el || !stack) return;

    // A trail that follows a cursor has no meaning without a cursor. On touch
    // `pointerenter` fires on tap, so every tap would stack a plate under the
    // finger and leave it there.
    if (!window.matchMedia('(pointer: fine)').matches) return;
    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return;

    /* Centring the column on the pointer once, so the follow tween writes a
       raw `y` and never has to subtract half a height it does not know. */
    gsap.set(stack, { yPercent: -50 });
    const yTo = gsap.quickTo(stack, 'y', { duration: followDuration, ease: 'power4' });

    let seeded = false;
    let order = 0;

    const onMove = (e: PointerEvent) => {
      const rect = el.getBoundingClientRect();
      const y = e.clientY - rect.top;
      if (seeded) {
        yTo(y);
      } else {
        seeded = true;
        // Second argument is quickTo's START value, so the column teleports on
        // entry instead of sweeping down the list from wherever it was left.
        yTo(y, y);
      }
    };

    const onLeave = () => {
      seeded = false;
    };

    const spawn = (index: number) => {
      const plate = plates.current[index];
      if (!plate) return;

      /* The wrapper is the mask. `overflow: hidden` plus a fixed size is what
         makes the opposite-direction pair read as a reveal instead of two
         elements sliding past each other. */
      const wrap = document.createElement('div');
      wrap.style.position = 'absolute';
      wrap.style.left = '0';
      wrap.style.top = '0';
      wrap.style.width = `${tileWidth}px`;
      wrap.style.height = `${tileHeight}px`;
      wrap.style.overflow = 'hidden';
      wrap.style.borderRadius = '4px';
      wrap.style.willChange = 'transform';
      // Monotonic, never reset: a later plate is always above an earlier one,
      // with no possibility of two plates tying and flickering.
      order += 1;
      wrap.style.zIndex = String(order);

      const canvas = document.createElement('canvas');
      canvas.width = plate.width;
      canvas.height = plate.height;
      canvas.style.width = `${tileWidth}px`;
      canvas.style.height = `${tileHeight}px`;
      canvas.style.display = 'block';
      canvas.style.willChange = 'transform';
      const ctx = canvas.getContext('2d');
      if (!ctx) return;
      // One blit. All the expensive drawing happened at mount.
      ctx.drawImage(plate, 0, 0);

      wrap.appendChild(canvas);
      stack.appendChild(wrap);

      /* The masked-reveal pair: wrapper up from +100%, canvas down from -100%,
         on the same duration and ease so they cancel exactly. Any mismatch in
         either and the plate visibly slides inside its own frame. */
      gsap.fromTo(
        wrap,
        { yPercent: 100 },
        { yPercent: 0, duration: REVEAL_DURATION, ease: 'expo.inOut', overwrite: 'auto' },
      );
      gsap.fromTo(
        canvas,
        { yPercent: -100 },
        { yPercent: 0, duration: REVEAL_DURATION, ease: 'expo.inOut', overwrite: 'auto' },
      );

      /* The cull. Not a nicety — without it the stack grows for as long as the
         page is open, and a user idly running the pointer up and down the list
         builds thousands of composited layers. Killing tweens before removal
         stops GSAP writing to a node React and the DOM have both let go of. */
      while (stack.children.length > MAX_PLATES) {
        const oldest = stack.firstElementChild;
        if (!oldest) break;
        gsap.killTweensOf(oldest);
        gsap.killTweensOf(oldest.firstElementChild);
        oldest.remove();
      }
    };

    const onOver = (e: Event) => {
      const target = e.target;
      if (!(target instanceof Element)) return;
      const row = target.closest('[data-trail-row]');
      if (!row) return;
      /* `pointerover` bubbles and fires again for every descendant crossed
         inside the same row, so the spawn is gated on actually changing rows
         rather than on the event firing. `relatedTarget` still inside the row
         means the pointer never left it. */
      const from = (e as PointerEvent).relatedTarget;
      if (from instanceof Node && row.contains(from)) return;
      const index = Number(row.getAttribute('data-trail-row'));
      if (!Number.isInteger(index)) return;
      spawn(index);
    };

    el.addEventListener('pointermove', onMove, { passive: true });
    el.addEventListener('pointerleave', onLeave);
    el.addEventListener('pointerover', onOver);

    return () => {
      el.removeEventListener('pointermove', onMove);
      el.removeEventListener('pointerleave', onLeave);
      el.removeEventListener('pointerover', onOver);
      gsap.killTweensOf(stack);
      // Every live plate is a node this effect created and React does not know
      // about, so this effect has to remove them itself.
      while (stack.firstElementChild) {
        const child = stack.firstElementChild;
        gsap.killTweensOf(child);
        gsap.killTweensOf(child.firstElementChild);
        child.remove();
      }
      gsap.set(stack, { clearProps: 'all' });
    };
  }, [followDuration, tileWidth, tileHeight]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes all three container listeners, kills tweens on the column and on every live plate and its canvas, then removes each plate node — these were created imperatively, so React will not clean them up — and clears the column transform. The offscreen plate canvases are released by nulling the ref array; they are plain canvases, never object URLs, so there is nothing to revoke.

**Reduced motion.** No listeners attach and no plates are ever created. What remains is the list itself — real links, real hover colour — which loses nothing functional. There is no meaningful static version of a trail, so the component removes itself rather than pretending.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- No cull. The stack grows for the lifetime of the page; a user idly running the pointer across the list builds thousands of composited layers and the tab degrades with no single frame that looks like the culprit.
- Culling by index or on a timer instead of on spawn. The ceiling then applies per interaction rather than at all times, and a burst of hovers still spikes the node count.
- Removing a node without `killTweensOf`. GSAP keeps writing transforms to a detached element, which is wasted work per frame forever and, in dev, a confusing set of live tweens for nodes that no longer exist.
- Mismatched duration or ease between the wrapper and the canvas. The cancellation breaks and the plate slides inside its own frame — it looks like a parallax effect nobody asked for, and reads as a bug.
- Putting `overflow: hidden` on the column instead of on each wrapper. Every plate is then clipped by one shared box, so plates offset from the column are cut off and the reveal only works for the newest one.
- Spawning on `pointerover` without checking `relatedTarget`. The event refires for every descendant crossed inside the same row, so a single hover over a row containing a number, a label and a date spawns three plates.
- Using `pointerenter` per row instead. It does not bubble, so it needs a listener on every row plus re-subscription whenever React re-renders the list — the bookkeeping is the bug surface.
- Letting the column receive pointer events. Plates then intercept the very moves that drive the follow, and the column stalls whenever it catches up with the pointer.
- `Math.random()` for the plate colours. The server and client disagree, React reports a hydration mismatch, and every reload produces a different set of plates so no visual regression is ever detectable.

## Notes

- Gated on `(pointer: fine)`. On touch nothing mounts: `pointerenter` fires on tap, so every tap would stack a plate directly under the finger and leave it there with no way to dismiss it, and the vertical follow has nothing to follow.
- Reduced motion disables the component entirely rather than shortening it. The plates and the column exist only as motion — there is no static state that still communicates anything — so the honest reduction is the plain list, which is fully functional on its own.
- The column is `aria-hidden`. The rows are real links and remain the accessible content; the plates are decoration with no text equivalent.
- Compare with `pooled-image-trail`, which solves the same visual problem for a pointermove-rate event by reusing a fixed ring of nodes. Neither approach is correct in general; the arrival rate of the event decides.

## Definition of done

Move down the list and each row entered drops a plate into the column, uncovered from the bottom rather than sliding in — watch the numeral in the corner and it should not move relative to the plate edge. The column follows your vertical position with a long settle. Hover a row, move within it across the number and the date, and exactly one plate appears. Run the pointer up and down the list for ten seconds and inspect the column in DevTools: it holds at most twenty children. On touch, or with reduced motion, the list is plain and no plates appear.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Prefetch-On-Hover Wipe

Two halves of one idea: spend the gap between "the visitor has decided" and "the visitor has clicked" making the next page free. `pointerenter` on any link inside the container prefetches it — 200 to 800 ms of warm-up nobody paid for — and the click covers the screen with a wipe, navigating only once the wipe has genuinely finished covering. Both halves are delegated from a single container, and the same predicate that decides what to intercept decides what to prefetch, so a download link or a cross-origin link is left entirely alone by both.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Warms the next page on hover, wipes the screen on click, and navigates once the wipe has actually covered.

- Category: transition
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. One container holds both delegated listeners. The click listener bubbles normally; the `pointerenter` listener cannot, because `pointerenter` does not bubble at all — so it is registered with `{ capture: true }`. The capture phase runs root-to-target for every event whether it bubbles or not, which makes it the only way to delegate the pointer-enter family.
2. `resolveLink` walks up from the event target with `closest('a[href]')` and returns null for anything the browser must handle itself: a `target` other than `_self`, a `download` attribute, `rel="external"`, a different origin, or a hash pointing at the current document. It gates both halves — a link you must not intercept is a link you must not prefetch either, and a cross-origin prefetch leaks the visitor's intent to a third party.
3. The prefetch is `onPrefetch(href)` if a callback was supplied, otherwise an injected `<link rel="prefetch" as="document">`. `as="document"` matters: without it the browser cannot pick a cache partition or a priority and will report the hint as unused even when the navigation follows immediately. A module-scope `Set` of already-hinted hrefs means a nav that remounts on every route change does not re-hint its whole link set each time.
4. The click calls `preventDefault()`, stores the resolved href in a ref, and flips `data-leaving` on the overlay, which runs a `transform: scaleX(0) -> scaleX(1)` transition from the anchored edge. Navigation waits for `transitionend`, filtered on both `event.target === overlay` and `event.propertyName === "transform"`, because `transitionend` fires once per property and also for descendants.
5. `transitionend` never fires for an element that is not being rendered — a `display: none` ancestor, a tab backgrounded mid-wipe — so a `duration + 120 ms` timer races it and a `fired` flag makes whichever wins the only one that navigates. A navigation that silently never happens is a dead link, which is strictly worse than an early one.
6. A `pageshow` listener clears the wipe. Back-navigation out of the browser's back/forward cache restores the DOM exactly as it was left, including the wipe mid-cover, with no script running to undo it — and `pageshow` is the only event dispatched on a bfcache restore. `load` is not, and neither are React's mount effects. `data-instant` suppresses the transition for exactly one frame so the restore snaps rather than playing a reveal of a page the visitor already saw.
7. The base rule carries an ease-out curve and the `[data-leaving="true"]` rule overrides the timing function with an ease-in, so covering accelerates away and retracting decelerates into place. One declaration, and it is the difference between a page transition and a garage door.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `duration = 0.3`
  Seconds to cover. This is dead time the visitor pays for on every click, so it is priced against the prefetch: roughly 300 ms is what a warm document needs to parse and paint, which is why the wipe and the fetch finish together. Past ~0.5 s the wipe is the slowest part of the navigation it was added to hide.
- `SAFETY_MS = 120`
  Milliseconds past the duration before navigation is forced. Long enough to lose the race with a real `transitionend` under load — a frame or two of jank costs more than 16 ms — short enough that a wipe which genuinely never rendered does not strand the visitor.
- `cover ease = cubic-bezier(0.4, 0, 1, 1)`
  Ease-in, no ease-out. The wipe must be at its fastest as it reaches full coverage: the last sliver of uncovered page is the part that reads as sluggishness, and an ease-out spends its longest stretch there.
- `retract ease = cubic-bezier(0, 0, 0.2, 1)`
  Ease-out, the mirror. Arriving should settle rather than snap. Reusing the cover curve for the retract makes the wipe linger and then flick away, because a reversed transition traverses the same curve in the same direction.
- `zIndex = 190`
  Above a custom cursor (150) and a scroll progress bar (120), both of which must be hidden while the screen is covered, and below a preloader (200), which owns first load outright.

## API

```ts
function HoverPrefetchWipe(props: { children: ReactNode; onNavigate: (href: string) => void; onPrefetch?: (href: string) => void; pageKey?: string; duration?: number; color?: string; direction?: "left" | "right" | "up" | "down"; zIndex?: number; position?: "fixed" | "absolute"; className?: string }): JSX.Element
```

- `children: ReactNode`
  Anything containing anchors. Every `<a href>` inside is handled by delegation.
- `onNavigate: (href: string) => void`
  Runs once the wipe has fully covered. Receives `pathname + search + hash`, which is what a router expects.
- `onPrefetch: (href: string) => void`
  The framework-specific half. Omitted, a `<link rel="prefetch" as="document">` is injected instead.
- `pageKey: string`
  Identity of the current page; a change retracts the wipe. Leave undefined for a full document navigation so the cover holds.
- `duration: number` — default `0.3`
  Seconds to cover, and to retract.
- `color: string` — default `'#fff'`
  Any CSS colour. Must be opaque or the swap shows through.
- `direction: "left" | "right" | "up" | "down"` — default `"left"`
  Edge the wipe grows from.
- `zIndex: number` — default `190`
  Above a custom cursor and a progress bar, below a preloader.
- `position: "fixed" | "absolute"` — default `"fixed"`
  `absolute` to scope the wipe to a bounded box; `fixed` for a real page transition.
- `className: string`
  Merged onto the container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * Hrefs already hinted to the browser. Module scope, so it is shared across
 * instances and survives remounts: a nav that remounts on every route change
 * would otherwise re-hint its entire link set on every navigation.
 */
const prefetched = new Set<string>();

/**
 * Milliseconds past the wipe duration before the navigation is forced.
 * `transitionend` is the accurate signal but it never fires if the overlay is
 * not being rendered — a `display: none` ancestor, a tab backgrounded mid-wipe
 * — and a navigation that silently never happens is a dead link.
 */
const SAFETY_MS = 120;

const WIPE_CSS = `
.kinetic-wipe {
  position: absolute;
  inset: 0;
  background: var(--kx-wipe-color, #fff);
  transform: var(--kx-wipe-from, scaleX(0));
  transform-origin: var(--kx-wipe-origin, left center);
  /* Base curve is the RETRACT: ease-out, so arriving decelerates. */
  transition: transform var(--kx-wipe-duration, 0.3s)
    cubic-bezier(0, 0, 0.2, 1);
  will-change: transform;
  /* Transparent and idle: must not eat the click it is waiting for. */
  pointer-events: none;
}
.kinetic-wipe[data-fixed='true'] {
  position: fixed;
}
.kinetic-wipe[data-leaving='true'] {
  transform: var(--kx-wipe-to, scaleX(1));
  /* Cover curve: ease-in, so leaving accelerates away. Asymmetry is the
     difference between a page transition and a garage door. */
  transition-timing-function: cubic-bezier(0.4, 0, 1, 1);
  /* Covering: now it SHOULD eat clicks. The outgoing page is still live
     underneath and a second click on a nav item would queue a second
     navigation behind an opaque surface. */
  pointer-events: auto;
}
/* Set for exactly one frame after a bfcache restore, so the overlay snaps back
   to rest instead of playing a reveal of a page the visitor already saw. */
.kinetic-wipe[data-instant='true'] {
  transition: none;
}
@media (prefers-reduced-motion: reduce) {
  /* Removed entirely rather than zero-duration: a zero-duration wipe is still
     one painted frame of full-bleed colour, which is a flash. The click
     handler navigates synchronously in this mode, so nothing is lost. */
  .kinetic-wipe { display: none; }
}
`;

/** Per-direction geometry: the two transforms and the anchored edge. */
const GEOMETRY = {
  left: { from: 'scaleX(0)', to: 'scaleX(1)', origin: 'left center' },
  right: { from: 'scaleX(0)', to: 'scaleX(1)', origin: 'right center' },
  up: { from: 'scaleY(0)', to: 'scaleY(1)', origin: 'bottom center' },
  down: { from: 'scaleY(0)', to: 'scaleY(1)', origin: 'top center' },
} as const;

export type WipeDirection = keyof typeof GEOMETRY;

export interface HoverPrefetchWipeProps {
  /** Anything containing anchors. Every `<a href>` inside is handled. */
  children: ReactNode;
  /**
   * Runs once the wipe has fully covered. Receives the app-relative href —
   * `pathname + search + hash` — which is what a router expects.
   */
  onNavigate: (href: string) => void;
  /**
   * The framework-specific half. Next.js: `(href) => router.prefetch(href)`.
   * Omitted, a `<link rel="prefetch" as="document">` is injected instead,
   * which is the right hint for a plain multi-page site.
   */
  onPrefetch?: (href: string) => void;
  /**
   * Identity of the current page — `usePathname()` in Next.js. A change
   * retracts the wipe. Left undefined the wipe stays up after `onNavigate`,
   * which is correct for a full document navigation: the browser keeps
   * painting the old page until the new one is ready, so lowering the curtain
   * early re-reveals the page you just left.
   */
  pageKey?: string;
  /** Seconds the wipe takes to cover, and to retract. */
  duration?: number;
  /** Any CSS colour. Must be opaque or the swap shows through. */
  color?: string;
  /** Edge the wipe grows from. */
  direction?: WipeDirection;
  zIndex?: number;
  /** `absolute` to demo inside a bounded box; `fixed` for a real page. */
  position?: 'fixed' | 'absolute';
  className?: string;
}

/**
 * The anchor a delegated event belongs to, or null if the browser should be
 * left alone. Every clause is a link that would break if intercepted — and the
 * same predicate gates both halves, because a link you must not intercept is a
 * link you must not prefetch either.
 */
function resolveLink(event: Event, root: HTMLElement): HTMLAnchorElement | null {
  const target = event.target;
  if (!(target instanceof Element)) return null;

  const anchor = target.closest('a[href]');
  if (!(anchor instanceof HTMLAnchorElement)) return null;
  if (!root.contains(anchor)) return null;

  // Opens elsewhere, downloads, or is explicitly marked as leaving the site.
  if (anchor.target !== '' && anchor.target !== '_self') return null;
  if (anchor.hasAttribute('download')) return null;
  if (anchor.rel.split(/\s+/).includes('external')) return null;

  // Cross-origin: prefetching leaks the visitor's intent to a third party and
  // intercepting breaks the navigation outright.
  if (anchor.origin !== window.location.origin) return null;

  // Same document, different fragment. Nothing to fetch, and covering the
  // screen in order to scroll down the page is absurd.
  if (
    anchor.hash !== '' &&
    anchor.pathname === window.location.pathname &&
    anchor.search === window.location.search
  ) {
    return null;
  }

  return anchor;
}

function hrefOf(anchor: HTMLAnchorElement): string {
  // Resolved and app-relative. `getAttribute('href')` hands a router raw
  // authored text like '../work', which it cannot resolve on its own.
  return `${anchor.pathname}${anchor.search}${anchor.hash}`;
}

export function HoverPrefetchWipe({
  children,
  onNavigate,
  onPrefetch,
  pageKey,
  duration = 0.3,
  color = '#fff',
  direction = 'left',
  zIndex = 190,
  position = 'fixed',
  className,
}: HoverPrefetchWipeProps) {
  const root = useRef<HTMLDivElement>(null);
  const wipe = useRef<HTMLDivElement>(null);
  const pending = useRef<string | null>(null);
  const reduced = useReducedMotion();

  const [leaving, setLeaving] = useState(false);
  const [instant, setInstant] = useState(false);

  // Held in refs so a new handler identity on the parent's render does not
  // re-bind the delegated listeners.
  const navigate = useRef(onNavigate);
  navigate.current = onNavigate;
  const prefetch = useRef(onPrefetch);
  prefetch.current = onPrefetch;

  /* -- halves one and two, both delegated from the same container ------- */
  useEffect(() => {
    const el = root.current;
    if (!el) return;

    const onEnter = (event: Event) => {
      const anchor = resolveLink(event, el);
      if (!anchor) return;

      const href = hrefOf(anchor);
      if (prefetched.has(href)) return;
      prefetched.add(href);

      const custom = prefetch.current;
      if (custom) {
        custom(href);
        return;
      }

      const link = document.createElement('link');
      link.rel = 'prefetch';
      // Without `as`, the browser cannot choose a cache partition or a
      // priority, and logs the hint as unused even when the navigation
      // follows immediately.
      link.as = 'document';
      link.href = href;
      document.head.appendChild(link);
    };

    const onClick = (event: MouseEvent) => {
      // Someone upstream already handled it, or the visitor asked for a new
      // tab, a new window, or a download. Middle and right clicks are not
      // navigations and must reach the browser untouched.
      if (event.defaultPrevented || event.button !== 0) return;
      if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;

      const anchor = resolveLink(event, el);
      if (!anchor) return;

      event.preventDefault();

      if (reduced) {
        navigate.current(hrefOf(anchor));
        return;
      }

      // A wipe already covering owns the navigation. Without this a second
      // click retargets `pending` mid-cover and the visitor lands on a page
      // they never aimed at.
      if (pending.current !== null) return;

      pending.current = hrefOf(anchor);
      setLeaving(true);
    };

    // `pointerenter` does not bubble, so delegation only works in the capture
    // phase — which runs root-to-target for every event, bubbling or not.
    el.addEventListener('pointerenter', onEnter, { capture: true, passive: true });
    el.addEventListener('click', onClick);

    return () => {
      el.removeEventListener('pointerenter', onEnter, { capture: true });
      el.removeEventListener('click', onClick);
    };
  }, [reduced]);

  /* -- navigate only once the wipe has actually finished covering ------- */
  useEffect(() => {
    if (!leaving) return;
    const overlay = wipe.current;
    const href = pending.current;
    if (!overlay || href === null) return;

    let fired = false;
    const commit = () => {
      if (fired) return;
      fired = true;
      navigate.current(href);
    };

    // `transitionend` fires once per animated property and also for
    // descendants, so both filters are required: without the target check a
    // transition on anything inside the overlay would trigger navigation.
    const onEnd = (event: TransitionEvent) => {
      if (event.target !== overlay || event.propertyName !== 'transform') return;
      commit();
    };

    overlay.addEventListener('transitionend', onEnd);
    const safety = window.setTimeout(commit, duration * 1000 + SAFETY_MS);

    return () => {
      overlay.removeEventListener('transitionend', onEnd);
      clearTimeout(safety);
    };
  }, [leaving, duration]);

  /* -- retract when the destination is on screen ----------------------- */
  const seenKey = useRef(pageKey);
  useEffect(() => {
    if (pageKey === undefined || seenKey.current === pageKey) return;
    seenKey.current = pageKey;
    // Driven by the same render that swapped the content in, so there is no
    // window in which the retracting wipe exposes the page just left.
    pending.current = null;
    setLeaving(false);
  }, [pageKey]);

  /* -- half three: survive the back/forward cache ---------------------- */
  useEffect(() => {
    const onShow = () => {
      pending.current = null;
      setInstant(true);
      setLeaving(false);
    };
    window.addEventListener('pageshow', onShow);
    return () => window.removeEventListener('pageshow', onShow);
  }, []);

  useEffect(() => {
    if (!instant) return;
    // One frame is enough for the resting transform to be committed with the
    // transition suppressed. Re-enable any earlier and style has not been
    // recalculated yet, so the snap becomes a fade after all.
    const frame = requestAnimationFrame(() => setInstant(false));
    return () => cancelAnimationFrame(frame);
  }, [instant]);

  const geometry = GEOMETRY[direction];

  return (
    <div ref={root} className={cn(position === 'absolute' && 'relative', className)}>
      <style href="kinetic-hover-prefetch-wipe" precedence="medium">
        {WIPE_CSS}
      </style>

      {children}

      <div
        ref={wipe}
        aria-hidden
        data-leaving={leaving ? 'true' : 'false'}
        data-instant={instant ? 'true' : 'false'}
        data-fixed={position === 'fixed' ? 'true' : 'false'}
        className="kinetic-wipe"
        style={
          {
            zIndex,
            '--kx-wipe-duration': `${duration}s`,
            '--kx-wipe-color': color,
            '--kx-wipe-from': geometry.from,
            '--kx-wipe-to': geometry.to,
            '--kx-wipe-origin': geometry.origin,
          } as CSSProperties
        }
      />
    </div>
  );
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Both delegated listeners are removed with the same `{ capture: true }` flag they were added with, or the removal silently fails to match. The `transitionend` listener and the safety timer are torn down together whenever the leaving state changes, the rAF that re-enables the transition after a bfcache restore is cancelled, and the `pageshow` listener is removed on unmount. Injected `<link rel="prefetch">` tags are deliberately left in the head: removing a hint mid-flight cancels the fetch it exists to start.

**Reduced motion.** The overlay gets `display: none` and the click handler calls `onNavigate` synchronously, so navigation is a hard cut with no coloured frame in either direction. Not a zero-duration wipe — that is still one painted frame of full-bleed colour, which is a flash. The prefetch half is untouched, because a warm cache is not motion and is precisely the thing a visitor on a slow connection wants kept.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Delegating `pointerenter` with a normal bubbling listener. It does not bubble, so the handler fires only when the pointer enters the container itself — once — and every link in the nav is silently never prefetched. `{ capture: true }` is not an optimisation here, it is the mechanism.
- Prefetching everything on mount. A nav of twelve links becomes twelve speculative document fetches competing with the page the visitor is actually reading. Hover is the signal that makes it worth the bandwidth.
- Prefetching cross-origin hrefs. Beyond the wasted request, it tells a third party which of its pages this visitor was considering before they chose. `resolveLink` rejects them for both halves.
- Navigating on a timer instead of `transitionend`. Under load the timer fires while the page is still visible through a half-drawn wipe, which is the exact artefact the wipe exists to hide. Under a throttled background tab it fires long after.
- Trusting `transitionend` alone. It never fires for an unrendered element, so a wipe inside a collapsed ancestor turns every link into a no-op. The safety timer is not belt-and-braces, it is the only thing standing between a CSS edge case and a dead nav.
- Filtering `transitionend` on neither target nor property name. It fires once per animated property and bubbles from descendants, so a hover transition on a child inside the overlay triggers the navigation early.
- Forgetting `pageshow`. On a bfcache restore the visitor lands on a full-bleed sheet of colour with nothing running to clear it. This is the single most common way a wipe transition ships broken, because it never reproduces on a hard reload.
- Leaving the overlay `pointer-events: none` while it covers. The outgoing page is still live underneath, so a second click on a nav item queues a second navigation behind an opaque surface. It flips to `auto` only in the leaving state, because at rest it must not eat the click it is waiting for.
- Retracting the wipe immediately after a full document navigation. The browser keeps painting the old page until the new one is ready, so lowering the curtain early re-reveals the page just left. That is why the retract is driven by `pageKey` and why leaving it undefined holds the cover.

## Notes

- Next.js App Router: `onPrefetch={(href) => router.prefetch(href)}`, `onNavigate={(href) => router.push(href)}`, `pageKey={usePathname()}`. Nothing in this file imports `next/link` or `next/navigation` — the prefetch half is the only framework-specific part of the technique, so it is a callback, and `router.prefetch` already dedupes and no-ops in dev.
- React Router: `onPrefetch` can stay omitted and let the injected `<link rel="prefetch">` warm the loader's data URL, or call your own route-module preloader. `pageKey={useLocation().pathname}`.
- Plain multi-page site: omit `onPrefetch` entirely and set `onNavigate={(href) => window.location.assign(href)}`. Leave `pageKey` undefined so the wipe stays up while the browser fetches, and let `pageshow` clear it on Back.
- Wrap the whole layout, not each nav: one container, one overlay, one pair of listeners, and every link on the page is covered including ones rendered later. `position="fixed"` for that; `absolute` only when the transition is scoped to a panel.
- The colour must be opaque. A translucent wipe shows the outgoing page through the swap, which is the one artefact the whole sequence exists to prevent.
- Pairs with `page-reveal-overlay` if you want the inbound half animated too — this component covers and hands off, that one replays a reveal on arrival.

## Definition of done

Hover a nav item and its dot lights — the href has been hinted, once, and hovering again does not re-hint. Click and the panel wipes over from the left in 0.4 s, the content swaps while covered, and the wipe retracts to the same edge with the opposite ease. Cmd-click, middle-click and a `download` link all behave like ordinary links with no wipe. On a real site, navigate away and press Back: the page appears with no leftover overlay and no reveal animation. With reduced motion the content swaps instantly and no coloured surface is ever painted.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Idle-Gated Page States

A page entrance is the one animation guaranteed to run at the worst possible moment: hydration, font swap, image decode and the first layout pass all land in the same few hundred milliseconds. Start a stagger there and it does not look slow, it looks broken — three elements arrive, the thread blocks, the rest snap in. This gates the entrance on two conditions at once, a floor delay resolved on a frame boundary and at least one report of an idle main thread, and starts only when the slower of the two finishes. Enter and leave are one paused timeline played forward and reversed.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A page entrance that will not start until a floor delay has elapsed and the main thread has reported itself idle.

- Category: transition
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. The machine is `preload -> gating -> entering -> settled`, with `leave(commit)` sending it to `leaving` and the exit's completion sending it back to `gating` for the next page. The current phase is written to `data-page-state` on the root so CSS can read it without a second source of truth.
2. `whenIdleAfter(delay, timeout, done)` is the gate. It schedules two independent waits and calls `done` only when both flags are set: a `setTimeout(delay)` whose callback schedules a `requestAnimationFrame`, and either `requestIdleCallback(cb, { timeout })` or — where that is missing — `setTimeout(cb, timeout)`. It returns a canceller that clears the timer, cancels the frame, and releases whichever of the two idle mechanisms was actually used.
3. The floor delay resolves inside the rAF rather than in the timer itself. A timer callback can fire in the middle of a long task; the frame callback after it cannot, so the first tween is handed a fresh frame budget instead of the tail end of somebody else's work.
4. `requestIdleCallback`'s `timeout` option is the safety net — the callback is guaranteed to run within that many milliseconds whether the thread ever goes idle or not — and the `setTimeout` fallback uses the same number as its delay, so both code paths have identical worst-case behaviour.
5. The first entrance uses `preloadDelay` (0.8 s) and every subsequent one uses `routeDelay` (0.15 s), switched by a `firstEnter` ref. Only the first competes with hydration; keeping 0.8 s for route changes would put nearly a second of nothing between every click and its page.
6. The choreography is ONE paused GSAP timeline: `fromTo([data-page-enter], { opacity: 0, y: 24 }, { opacity: 1, y: 0, stagger: 0.08 })`. `state === "entering"` calls `play()`; `state === "leaving"` calls `timeScale(enterDuration / leaveDuration).reverse()`. The timeline's `onComplete` and `onReverseComplete` report back into the machine, so no phase is advanced by a timer that could disagree with what is on screen.
7. The pre-JS hidden state is a stylesheet rule keyed on `[data-page-state="preload"]` and `[data-page-state="gating"]`, not a `gsap.set` in an effect. Effects run after the first paint, so a JS-only hidden state paints the page fully composed and then hides it. The build then applies `gsap.set(targets, from)` immediately, in the same React commit that swapped the page in, which covers every frame after that.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `PRELOAD_DELAY = 0.8`
  Seconds of floor delay before the FIRST entrance — the one competing with hydration, font loading and the initial layout pass. Below ~0.5 s the stagger still lands inside the hydration burst on a mid-range phone; above ~1 s a fast device shows a finished, blank-looking page and waits.
- `ROUTE_DELAY = 0.15`
  Seconds of floor delay for every entrance after the first. Hydration has already happened; the only competing work is the destination subtree's own mount. Long enough that the mount lands inside it, short enough that the click still feels answered.
- `IDLE_TIMEOUT = 1200`
  Milliseconds after which the idle wait gives up, passed both as `requestIdleCallback`'s `timeout` and as the fallback timer's delay. A saturated thread — a WebGL hero, a heavy hydration, a third-party long task — may never report idle, and an entrance that never starts is a blank page. Longer than a typical hydration burst, comfortably shorter than the ~2 s at which a visitor decides the site is broken.
- `ENTER_DURATION = 0.5`
  Seconds for the entrance, matching the source's `enterDuration`. With a 0.08 s stagger over four elements the last one finishes at 0.74 s, which is the upper limit for a page that should feel like it is already there.
- `LEAVE_DURATION = 0.5`
  Seconds for the exit, matching the source's `leaveDuration`. Applied as `timeScale(enterDuration / leaveDuration)` on the reversed timeline rather than as a second set of tweens, so the exit cannot drift from the entrance. Drop it to 0.25 for an exit that feels decisive against a gradual arrival.
- `ENTER_STAGGER = 0.08`
  Seconds between elements. Below ~0.05 s the group reads as one block and the stagger is wasted; above ~0.12 s the last element arrives after the eye has already moved on and the page feels like it is still loading.
- `ENTER_DISTANCE = 24`
  Pixels each element rises through. Small enough that no element crosses another's resting position — which would read as the layout reflowing rather than arriving — and large enough to be legible at the 0.5 s duration.

## API

```ts
function IdleGatedPageStates(props: { controller: IdlePageStates; pageKey: string; children: ReactNode; enterDuration?: number; leaveDuration?: number; stagger?: number; distance?: number; className?: string }): JSX.Element
function useIdlePageStates(options?: { preloadDelay?: number; routeDelay?: number; idleTimeout?: number; onGateOpen?: () => void }): { state: PageState; ready: () => void; leave: (commit: () => void) => void; entered: () => void; left: () => void }
function whenIdleAfter(delaySeconds: number, timeout: number, done: () => void): () => void
type PageState = "preload" | "gating" | "entering" | "settled" | "leaving"
```

- `controller: IdlePageStates`
  From `useIdlePageStates()`. Supplies the phase and receives the timeline's completions.
- `pageKey: string`
  Identity of the current page. A change rebuilds the timeline against the new `[data-page-enter]` elements. `usePathname()` in Next.js.
- `children: ReactNode`
  The page. Descendants marked `data-page-enter` are staggered in and, reversed, out.
- `enterDuration: number` — default `0.5`
  Seconds for the entrance.
- `leaveDuration: number` — default `0.5`
  Seconds for the exit, applied as a `timeScale` on the reversed timeline.
- `stagger: number` — default `0.08`
  Seconds between staggered elements. Reversed on exit, so the last one leaves first.
- `distance: number` — default `24`
  Pixels each element rises through.
- `className: string`
  Merged onto the root via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * Seconds of floor delay before the FIRST entrance. The one enter that
 * competes with hydration, font loading and the initial layout pass, so it is
 * the one that needs real headroom. Below ~0.5 s the stagger still lands
 * inside the hydration burst on a mid-range phone; above ~1 s a fast device
 * shows a finished, blank-looking page and waits.
 */
export const PRELOAD_DELAY = 0.8;

/**
 * Seconds of floor delay before every SUBSEQUENT entrance. Hydration has
 * already happened by then; the only competing work is the destination
 * subtree's own mount, which is a fraction of it. Keeping the first-load value
 * here would put nearly a second of nothing between every click and its page.
 */
export const ROUTE_DELAY = 0.15;

/**
 * Milliseconds after which the idle wait gives up. A thread that is genuinely
 * saturated — a WebGL hero, a heavy hydration, a long task from a third-party
 * script — may never report idle, and an entrance that never starts is a blank
 * page. 1200 ms is longer than a typical hydration burst and comfortably
 * shorter than the ~2 s at which a visitor decides the site is broken. It is
 * passed as `requestIdleCallback`'s own `timeout` option, and it is also the
 * fallback timer's delay, so both paths have identical worst-case behaviour.
 */
export const IDLE_TIMEOUT = 1200;

/** Seconds for the entrance. */
export const ENTER_DURATION = 0.5;
/** Seconds for the exit. */
export const LEAVE_DURATION = 0.5;

/** Seconds between staggered elements. */
const ENTER_STAGGER = 0.08;
/** Pixels each element rises through. */
const ENTER_DISTANCE = 24;
const ENTER_EASE = 'power2.out';

const PAGE_CSS = `
/* The pre-JS hidden state. It cannot come from a 'gsap.set' in an effect —
   effects run after the first paint, so the page would flash fully composed
   and then hide itself. Once GSAP is involved it writes 'opacity' to the
   inline style, which outranks this rule in both directions. */
.kx-idle-page[data-page-state='preload'] [data-page-enter],
.kx-idle-page[data-page-state='gating'] [data-page-enter] {
  opacity: 0;
}
/* Reduced motion never runs the gate, so nothing would ever remove the rule
   above before hydration. */
@media (prefers-reduced-motion: reduce) {
  .kx-idle-page[data-page-state='preload'] [data-page-enter],
  .kx-idle-page[data-page-state='gating'] [data-page-enter] {
    opacity: 1;
  }
}
/* Media Queries 5. Where it is unsupported the declaration is simply dropped,
   so this is a bonus rather than the fix — but where it is supported, a
   scripting-disabled visitor gets the page instead of an empty box. */
@media (scripting: none) {
  .kx-idle-page[data-page-state='preload'] [data-page-enter],
  .kx-idle-page[data-page-state='gating'] [data-page-enter] {
    opacity: 1;
  }
}
`;

/**
 * Call `done` once BOTH a floor delay has elapsed and the main thread has gone
 * idle. Returns the canceller — call it from effect cleanup.
 *
 * `requestIdleCallback` is used where it exists and a plain `setTimeout` where
 * it does not: Safari only shipped it in 17.4, so a fallback is not
 * hypothetical, and the two are cancelled with different functions. Exactly one
 * of them is ever scheduled, and the canceller releases whichever it was.
 */
export function whenIdleAfter(
  delaySeconds: number,
  timeout: number,
  done: () => void,
): () => void {
  let cancelled = false;
  let idleReady = false;
  let delayReady = false;

  const join = () => {
    if (cancelled || !idleReady || !delayReady) return;
    done();
  };

  // The floor delay resolves inside a rAF rather than directly in the timer.
  // A timer callback can fire in the middle of a long task; the frame callback
  // after it cannot, so the first tween is guaranteed a fresh frame budget
  // instead of the tail end of someone else's.
  let frame = 0;
  const delayTimer = setTimeout(() => {
    frame = requestAnimationFrame(() => {
      frame = 0;
      delayReady = true;
      join();
    });
  }, delaySeconds * 1000);

  let idleHandle = 0;
  let idleTimer: ReturnType<typeof setTimeout> | undefined;

  const onIdle = () => {
    idleHandle = 0;
    idleTimer = undefined;
    idleReady = true;
    join();
  };

  if (typeof window !== 'undefined' && 'requestIdleCallback' in window) {
    // The `timeout` option is the guarantee: the callback runs within this many
    // milliseconds whether the thread ever goes idle or not.
    idleHandle = window.requestIdleCallback(onIdle, { timeout });
  } else {
    idleTimer = setTimeout(onIdle, timeout);
  }

  return () => {
    cancelled = true;
    clearTimeout(delayTimer);
    if (frame !== 0) cancelAnimationFrame(frame);
    // Whichever branch ran is the one that gets released. Cancelling an idle
    // handle with `clearTimeout` is a silent no-op, which is how a gate leaks
    // into the next page and starts an entrance on a tree that no longer
    // exists.
    if (idleHandle !== 0) window.cancelIdleCallback(idleHandle);
    if (idleTimer !== undefined) clearTimeout(idleTimer);
  };
}

export type PageState =
  | 'preload'
  | 'gating'
  | 'entering'
  | 'settled'
  | 'leaving';

export interface IdlePageStatesOptions {
  /** Seconds of floor delay before the first entrance. */
  preloadDelay?: number;
  /** Seconds of floor delay before every entrance after the first. */
  routeDelay?: number;
  /** Milliseconds after which the idle wait gives up. */
  idleTimeout?: number;
  /**
   * Fired on the frame the gate opens, before the entrance starts. The place
   * for `ScrollTrigger.refresh()` — measure while nothing is moving, or every
   * trigger is offset by the distance the entrance travels.
   */
  onGateOpen?: () => void;
}

export interface IdlePageStates {
  /** Also written to `data-page-state` on the root, so CSS can read it. */
  state: PageState;
  /** Preload finished — fonts resolved, critical images decoded. */
  ready: () => void;
  /** Run the exit, then `commit` — your navigation. */
  leave: (commit: () => void) => void;
  /** Reported by the component when the entrance timeline completes. */
  entered: () => void;
  /** Reported by the component when the exit timeline reaches zero. */
  left: () => void;
}

export function useIdlePageStates(
  options: IdlePageStatesOptions = {},
): IdlePageStates {
  const {
    preloadDelay = PRELOAD_DELAY,
    routeDelay = ROUTE_DELAY,
    idleTimeout = IDLE_TIMEOUT,
    onGateOpen,
  } = options;

  const reduced = useReducedMotion();
  const [state, setState] = useState<PageState>('preload');

  const commit = useRef<(() => void) | null>(null);
  const firstEnter = useRef(true);
  const gateOpen = useRef(onGateOpen);
  gateOpen.current = onGateOpen;

  // The gate. Scheduled only while gating, and cancelled by returning the
  // canceller — so a route change or an unmount mid-wait releases the idle
  // handle instead of firing an entrance into a tree that has gone.
  useEffect(() => {
    if (state !== 'gating') return;

    // Reduced motion skips the gate entirely rather than waiting it out. The
    // gate exists to protect an animation; with no animation to protect, all it
    // would do is hold a blank page in front of someone who asked for less
    // motion, not more waiting.
    if (reduced) {
      firstEnter.current = false;
      setState('settled');
      return;
    }

    const delay = firstEnter.current ? preloadDelay : routeDelay;
    return whenIdleAfter(delay, idleTimeout, () => {
      firstEnter.current = false;
      gateOpen.current?.();
      setState('entering');
    });
  }, [state, reduced, preloadDelay, routeDelay, idleTimeout]);

  const ready = useCallback(() => {
    setState((s) => (s === 'preload' ? 'gating' : s));
  }, []);

  const entered = useCallback(() => {
    setState((s) => (s === 'entering' ? 'settled' : s));
  }, []);

  const leave = useCallback(
    (next: () => void) => {
      if (reduced) {
        next();
        return;
      }
      // A second click during an exit would queue a second commit and land the
      // visitor one page past where they aimed.
      if (commit.current !== null) return;
      commit.current = next;
      setState((s) =>
        s === 'entering' || s === 'settled' || s === 'gating' ? 'leaving' : s,
      );
    },
    [reduced],
  );

  const left = useCallback(() => {
    const next = commit.current;
    commit.current = null;
    next?.();
    // Straight back to gating, not to preload: the preloader is a first-load
    // state and showing it again on every route change is the classic version
    // of this mistake.
    setState('gating');
  }, []);

  useEffect(
    () => () => {
      commit.current = null;
    },
    [],
  );

  return useMemo(
    () => ({ state, ready, leave, entered, left }),
    [state, ready, leave, entered, left],
  );
}

export interface IdleGatedPageStatesProps {
  /** From `useIdlePageStates()`. */
  controller: IdlePageStates;
  /**
   * Identity of the current page. A change rebuilds the timeline against the
   * new page's `[data-page-enter]` elements. `usePathname()` in Next.js.
   */
  pageKey: string;
  /** The page. Descendants marked `data-page-enter` are staggered in and out. */
  children: ReactNode;
  /** Seconds for the entrance. */
  enterDuration?: number;
  /** Seconds for the exit. Applied as a `timeScale` on the reversed timeline. */
  leaveDuration?: number;
  /** Seconds between staggered elements. */
  stagger?: number;
  /** Pixels each element rises through. */
  distance?: number;
  className?: string;
}

export function IdleGatedPageStates({
  controller,
  pageKey,
  children,
  enterDuration = ENTER_DURATION,
  leaveDuration = LEAVE_DURATION,
  stagger = ENTER_STAGGER,
  distance = ENTER_DISTANCE,
  className,
}: IdleGatedPageStatesProps) {
  const root = useRef<HTMLDivElement>(null);
  const timeline = useRef<ReturnType<typeof gsap.timeline> | null>(null);
  const reduced = useReducedMotion();

  const { state, entered, left } = controller;

  // Held in refs so the timeline's completion callbacks are wired once, at
  // build time, and still call the current functions.
  const onEntered = useRef(entered);
  onEntered.current = entered;
  const onLeft = useRef(left);
  onLeft.current = left;

  // Built once per page and held paused. `state` is deliberately NOT a
  // dependency: `useGsap` reverts on every dependency change, and `revert()`
  // strips the inline values GSAP wrote — so a rebuild keyed on the phase would
  // hand the reverse tween the stylesheet default as its start value and the
  // exit would animate from nowhere to nowhere.
  useGsap(
    gsap,
    () => {
      const el = root.current;
      if (!el) return;

      const targets = Array.from(
        el.querySelectorAll<HTMLElement>('[data-page-enter]'),
      );
      if (targets.length === 0) return;

      const from = { opacity: 0, y: distance };

      // Applied immediately, in the same commit React swapped the page in, so
      // the destination is never painted composed and then hidden. The CSS rule
      // covers the frames before this file has run at all; this covers every
      // frame after.
      gsap.set(targets, from);

      const tl = gsap.timeline({
        paused: true,
        onComplete: () => onEntered.current(),
        onReverseComplete: () => onLeft.current(),
      });

      tl.fromTo(
        targets,
        from,
        {
          opacity: 1,
          y: 0,
          duration: enterDuration,
          ease: ENTER_EASE,
          stagger,
        },
        0,
      );

      timeline.current = tl;
      return () => {
        timeline.current = null;
      };
    },
    root,
    [pageKey, enterDuration, stagger, distance],
  );

  // The phase driver. Separate from the build for the reason above, and it
  // carries `pageKey` so it runs after — never before — a rebuild.
  useEffect(() => {
    const tl = timeline.current;
    if (!tl) return;

    if (reduced) {
      // A seek, not a zero-duration tween: the timeline is parked on its end
      // frame, so opacity, offset and stagger all land correctly because they
      // are all on this one timeline.
      tl.progress(1).pause();
      return;
    }

    if (state === 'entering') {
      tl.timeScale(1).play();
    } else if (state === 'leaving') {
      // One timeline, two speeds. `timeScale` is a ratio, so a 0.25 s exit off
      // a 0.5 s entrance is `0.5 / 0.25 = 2`, and the reversed stagger takes
      // the last element out first.
      tl.timeScale(enterDuration / Math.max(leaveDuration, 0.01)).reverse();
    }
  }, [state, reduced, pageKey, enterDuration, leaveDuration]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The gate's canceller is the effect's cleanup: it clears the floor-delay timer, cancels the pending `requestAnimationFrame`, and releases whichever idle mechanism was scheduled — `cancelIdleCallback` for the handle, `clearTimeout` for the fallback — with a `cancelled` flag so a callback already in the queue cannot fire after teardown. `useGsap` reverts the `gsap.context`, killing the timeline and stripping every inline style it wrote. The pending commit is nulled on unmount so a leave in flight cannot navigate a tree that has gone.

**Reduced motion.** The gate is skipped entirely — holding a blank page would be more waiting, not less motion — so `gating` advances straight to `settled` with no idle callback and no timer scheduled, and therefore nothing to cancel. The timeline is never played: the phase effect parks it with `tl.progress(1).pause()`, so opacity, offset and stagger all land on their end frame together because they are all on the one timeline. `leave()` calls the commit synchronously, and a stylesheet rule inside `@media (prefers-reduced-motion: reduce)` keeps `[data-page-enter]` visible for the frames before hydration.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Starting the entrance on mount. Mount is the single busiest moment in the page's life. The stagger runs against hydration and the first layout pass, so the first two or three elements animate and the rest jump — and it only reproduces on the devices you do not test on.
- Waiting for idle ALONE. On a fast machine `requestIdleCallback` fires almost immediately, before the hydration burst has even begun, so the gate opens straight into the work it was supposed to avoid. The floor delay is what makes the idle check meaningful.
- Waiting for a delay ALONE. On a slow machine the timer expires while the thread is still saturated and you are back to a stuttering stagger. Neither condition works without the other.
- Calling `requestIdleCallback` without the `timeout` option. On a page with a long-running rAF loop the callback may never fire, and the entrance never starts — a permanently blank page, on exactly the devices that can least afford it.
- Cancelling the wrong handle. `requestIdleCallback` returns a handle for `cancelIdleCallback`, and a `setTimeout` returns one for `clearTimeout`; passing either to the other is a silent no-op. Exactly one is ever scheduled and the canceller releases the one that was, or the gate outlives the page and fires an entrance into a tree that no longer exists.
- Assuming `requestIdleCallback` exists. Safari only shipped it in 17.4, so `window.requestIdleCallback(...)` throws on a browser that is still in real use — and it throws inside an effect, which takes the whole page down rather than degrading.
- Putting the phase in the `useGsap` dependency list. Every dependency change reverts the context, and `revert()` strips the inline values GSAP wrote — so the reverse tween reads the stylesheet default as its start value and the exit animates from nowhere to nowhere. The timeline is built once per page and driven from a second effect.
- Hiding `[data-page-enter]` from JavaScript only. An effect runs after the first paint, so the destination is painted fully composed and then hides itself — a flash of the finished page immediately before it animates in. The hidden state belongs in a stylesheet rule keyed on the phase.
- Returning to `preload` after a route change. The preloader is a first-load state; showing it again on every click is the classic version of this mistake. The machine goes back to `gating`, which re-runs the gate without re-running the preloader.
- Gating with reduced motion on. There is no animation left to protect, so all the gate does is hold a blank page in front of someone who asked for less motion, not more waiting. That path skips straight to `settled`.

## Notes

- In Next.js App Router: mount once in `app/layout.tsx` with `pageKey={usePathname()}`, call `ready()` from `document.fonts.ready`, and replace nav `<Link>` elements with buttons calling `leave(() => router.push(href))`. Nothing here imports `next/navigation` — the commit is a callback, so the same machine works under React Router or a plain `useState` page switch.
- `onGateOpen` fires on the frame the gate opens, before the entrance starts. That is where `ScrollTrigger.refresh()` belongs: measure while nothing is moving, or every trigger is offset by the distance the entrance travels. The source did the same thing, refreshing after its preload completed and before its enter.
- Neither `requestIdleCallback` nor `requestAnimationFrame` runs in a backgrounded tab, so the gate does not open until the tab is foregrounded. That is the correct behaviour — an entrance nobody can see is wasted work — but it is also why a headless screenshot taken against a background tab captures the pre-entrance state. Foreground the tab, or drive the timeline to `progress(1)` for capture.
- The preloader should stay up for the whole of `gating`, not just `preload`. The wait is dead time only if you show the visitor an empty page during it; behind a preloader it is indistinguishable from loading.
- The `@media (scripting: none)` rule reveals the content for visitors with JavaScript disabled. It is Media Queries 5 and is simply dropped where unsupported, so treat it as a bonus rather than as the fix.

## Definition of done

Load the preview: the preloader holds, then the content staggers up and in as one group with no element jumping ahead of the tween. Throttle the CPU to 6x in DevTools and reload — the entrance still runs as a smooth stagger rather than arriving in two jerks, because it starts later rather than starting on time and stuttering. Click a nav item: the current content staggers out last-element-first, the page swaps, and the next one arrives after a much shorter gate than the first load used. Click two nav items in quick succession and you land on the first one you clicked. With reduced motion the content is present immediately with no gate, no stagger, and no preloader held past the font load.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Instanced Quad Particles

Four vertices and six indices are shared by every particle; three instanced attributes carry position, size, spin, alpha, tint and shape. One `drawElementsInstanced` puts the whole field on screen. Quads instead of `gl_PointSize` because point sprites are capped at 255px on many drivers, cannot be rotated, and are culled whole the instant their centre leaves the viewport — a large sprite disappears while half of it is still visible.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Up to 1800 drifting particles in one draw call — quads rather than point sprites, so each one has its own size, spin and shape.

- Category: webgl
- Runtime cost: webgl
- Dependencies: ogl@^1.0.11

## How it works

1. The geometry is one unit quad in `position` (-0.5..0.5) plus an index buffer, and three attributes marked `instanced: 1`: `aOrigin` (field-space rest position), `aParams` (size in CSS px, signed spin rate, base alpha, tint mix) and `aSeed` (two flow phases, spin phase, shape mix). Ten floats per particle, 72 KB at the 1800 ceiling.
2. Buffers are allocated once at `maxCount` and never reallocated. The visible population comes from `geometry.setInstancedCount(count)` where `count` is derived from container area — `clamp(round(megapixels * density), 250, maxCount)` — so the same density reads correctly in a 320px card and a 2000px hero. Because the scatter is random, any prefix of the buffer is still a spatially even field.
3. The vertex shader rotates the quad corner in PIXEL space and only then divides by the drawing-buffer resolution to reach clip space. Rotating in clip space would shear the quad by the container aspect ratio, and a square particle would become a lozenge that changes shape as it spins.
4. Drift is a pure function of `elapsed` and the per-particle seed: the field marches upward with `fract(y + t * RISE)`, then two out-of-phase sinusoids sampled at the particle's own position add wander. No per-particle state is stored, so a resize, a tab switch or a reduced-motion still can all be drawn from one number.
5. `fract` teleports a particle from the top edge to the bottom, which is a visible pop. `uFadeBand` smoothsteps alpha to zero within 12% of each end, so the population always arrives and leaves at zero opacity.
6. One rounded-box SDF in the fragment shader covers both shapes. At `shape` 0 the half-extents and the corner radius are both 0.5, which reduces exactly to `length(uv) - 0.5` — a true circle. At 1 it is a narrow shard, and the shard is the only reason per-particle rotation is visible at all.
7. Blending is additive (`ONE, ONE`) onto an opaque clear colour, which is order independent — a thousand overlapping instances need no depth sort, which is what makes one draw call possible. The canvas is opaque rather than transparent because additive blending onto transparency would have to brighten the page background, and the GPU cannot see it.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `density = 900`
  Particles per megapixel. Tuned so a typical card holds 250-400 and a full-width hero approaches the ceiling. Doubling it does not double the perceived density — it doubles the fill rate and flattens the depth cue that comes from having gaps.
- `maxCount = 1800`
  Ceiling and allocation size. Not a performance limit on the vertex side — 1800 quads is 7200 vertices, nothing — but the fill cost of 1800 soft additive quads averaging 12px is roughly one full screen of blended pixels per frame.
- `MAX_DPR = 1.5`
  Additive fill is the entire cost of this component and it scales with the square of the pixel ratio. Dust has no fine detail that a third sample per axis resolves, so 3x phones render at 1.5x and the frame budget drops by a factor of four against an uncapped ratio.
- `SIZE_BIAS = 2.2`
  Exponent on the uniform random used for size. At 1 a quarter of the population lands in the largest quarter of the range, and a hundred 28px blobs is fog rather than dust. At 2.2 the large sizes are rare enough to read as individuals.
- `RISE = 0.045`
  Field heights per second at `speed` 1 — about 22 seconds to cross. Slow enough that the eye reads drift rather than travel; above ~0.15 the field looks like falling snow played in reverse.
- `FADE_BAND = 0.12`
  Fraction of the field height the wrap fade occupies at each end. Below ~0.06 the pop at the seam becomes visible for the largest particles, whose radius alone is a couple of percent of the height. Above 0.2 a quarter of the field is permanently dim.
- `FLOW_SCALE = 1.4`
  Cycles of wander across the field. Under 1 the whole population slides sideways as a sheet; well above 2 adjacent particles move in opposite directions and the motion reads as noise rather than air.
- `X_MIN / X_MAX = -0.08 / 1.08`
  Field-space x range. Seeding wider than the container means horizontal wander can never bare a strip at the left or right edge. The off-screen quads are clipped by the rasteriser and cost nothing — which is exactly what a point sprite could not do.
- `alpha per particle = 1 - 0.78 * sizeT`
  Large particles are dimmed so total emitted light is roughly independent of size. Without it the few big instances dominate every additive overlap and the field looks like it has hot spots.

## API

```ts
function InstancedQuadParticles(props: { density?: number; maxCount?: number; sizeRange?: readonly [number, number]; softness?: number; spin?: number; speed?: number; wander?: number; opacity?: number; colorA?: string; colorB?: string; background?: string; seed?: number | string; className?: string }): JSX.Element
```

- `density: number` — default `900`
  Particles per megapixel of container area. The count is derived from this, not fixed.
- `maxCount: number` — default `1800`
  Population ceiling, and the size the buffers are allocated at.
- `sizeRange: readonly [number, number]` — default `[5, 28]`
  Particle size in CSS pixels. The distribution is biased toward the small end.
- `softness: number` — default `0.62`
  Edge width, 0..1. 0 is a hard silhouette, 1 is a pure gradient. Floored at one device pixel.
- `spin: number` — default `0.5`
  Peak spin in radians per second; each particle takes a signed fraction of it.
- `speed: number` — default `1`
  Multiplier on the whole drift, including the upward march.
- `wander: number` — default `0.06`
  Sinusoidal wander amplitude in field units, where 1 is the container.
- `opacity: number` — default `0.55`
  Overall alpha multiplier applied in the fragment shader.
- `colorA: string` — default `'#9fb4cc'`
  First tint. Any value ogl's `Color` accepts.
- `colorB: string` — default `'#e8ddc9'`
  Second tint; each particle mixes between the two by a seeded amount.
- `background: string` — default `'#07090d'`
  Opaque clear colour the additive field is composited onto.
- `seed: number | string` — default `'instanced-quad-particles'`
  Seeds the scatter. Same seed, same field on every reload and on the server.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function InstancedQuadParticles({
  density = 900,
  maxCount = 1800,
  sizeRange = [5, 28],
  softness = 0.62,
  spin = 0.5,
  speed = 1,
  wander = 0.06,
  opacity = 0.55,
  colorA = '#9fb4cc',
  colorB = '#e8ddc9',
  background = '#07090d',
  seed = 'instanced-quad-particles',
  className,
}: InstancedQuadParticlesProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  const { width, height } = useResizeObserver(host);
  const size = useRef({ width, height });
  size.current = { width, height };

  const reduced = useReducedMotion();
  const visible = useVisibility();
  const { inView } = useInView(host, { rootMargin: '10%' });
  const ready = width > 1 && height > 1;

  const [minSize = 5, maxSize = 28] = sizeRange;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    if (!hasWebGL()) {
      setUnsupported(true);
      return;
    }

    // ogl creates its own canvas, and it is appended and removed per effect
    // run. Reusing one React-owned canvas would break under StrictMode: the
    // cleanup force-loses the context, and `getContext` on that same element
    // afterwards hands back the dead one rather than a fresh context.
    const renderer = new Renderer({
      dpr: pixelRatio(MAX_DPR),
      // Opaque, so the field owns every pixel and reads the same on a light or
      // a dark page. Additive blending onto a transparent canvas would have to
      // brighten whatever is behind it, which is the page background, which
      // the GPU cannot see.
      alpha: false,
      // Nothing is sorted and nothing occludes anything, so a depth buffer is
      // memory and a clear per frame for no result.
      depth: false,
      antialias: false,
      // The field is fill-bound, not shader-bound. Asking for the discrete GPU
      // on a laptop costs battery and buys nothing.
      powerPreference: 'low-power',
    });

    const gl = renderer.gl;
    const canvas = gl.canvas;

    const bg = new Color(background);
    gl.clearColor(bg.r, bg.g, bg.b, 1);

    // Four vertices, six indices, shared by every instance.
    const quad = new Float32Array([-0.5, -0.5, 0.5, -0.5, 0.5, 0.5, -0.5, 0.5]);
    const index = new Uint16Array([0, 1, 2, 0, 2, 3]);

    const total = Math.max(MIN_COUNT, Math.round(maxCount));
    const origins = new Float32Array(total * 2);
    const params = new Float32Array(total * 4);
    const seeds = new Float32Array(total * 4);

    const rng = createRng(seed);
    const lo = Math.max(1, Math.min(minSize, maxSize));
    const hi = Math.max(lo + 0.5, Math.max(minSize, maxSize));

    for (let i = 0; i < total; i += 1) {
      origins[i * 2] = randRange(rng, X_MIN, X_MAX);
      origins[i * 2 + 1] = rng();

      // Biased toward small: a linear distribution puts a quarter of the
      // population in the largest quarter of the size range, and a hundred
      // 28px blobs is fog rather than dust.
      const sizeT = Math.pow(rng(), SIZE_BIAS);
      params[i * 4] = lo + (hi - lo) * sizeT;
      params[i * 4 + 1] = randRange(rng, -1, 1) * spin;
      // Big particles are dimmer. Alpha per particle rather than per pixel
      // keeps the total light roughly constant as the size scales.
      params[i * 4 + 2] = 1 - 0.78 * sizeT;
      params[i * 4 + 3] = rng();

      seeds[i * 4] = rng() * Math.PI * 2;
      seeds[i * 4 + 1] = rng() * Math.PI * 2;
      seeds[i * 4 + 2] = rng();
      // A third are discs. The rest are shards, and the shards are the only
      // reason per-particle rotation is visible at all.
      seeds[i * 4 + 3] = rng() < 0.34 ? 0 : randRange(rng, 0.55, 1);
    }

    const geometry = new Geometry(gl, {
      index: { data: index },
      position: { size: 2, data: quad },
      aOrigin: { size: 2, data: origins, instanced: 1 },
      aParams: { size: 4, data: params, instanced: 1 },
      aSeed: { size: 4, data: seeds, instanced: 1 },
    });

    const uniforms: Uniforms = {
      uResolution: { value: [1, 1] },
      uPixelRatio: { value: renderer.dpr },
      uElapsed: { value: 0 },
      uDrift: { value: speed },
      uRise: { value: RISE },
      uFlowScale: { value: FLOW_SCALE },
      uWander: { value: wander },
      uFadeBand: { value: FADE_BAND },
      uColorA: { value: new Color(colorA) },
      uColorB: { value: new Color(colorB) },
      uSoftness: { value: clamp(softness, 0, 1) },
      uOpacity: { value: opacity },
    };

    const program = new Program(gl, {
      vertex: INSTANCED_QUAD_PARTICLES_VERT,
      fragment: INSTANCED_QUAD_PARTICLES_FRAG,
      uniforms,
      transparent: true,
      depthTest: false,
      depthWrite: false,
      // ogl defaults `cullFace` to BACK. The quad's index winding is not
      // guaranteed to face the way the driver expects once it is rotated in
      // the vertex shader, and a culled particle is simply absent.
      cullFace: false,
    });
    // Additive, overriding the source-over that `transparent: true` selected.
    // Order independent, so a thousand overlapping instances need no sort —
    // which is what makes one draw call possible in the first place.
    program.setBlendFunc(gl.ONE, gl.ONE);

    const mesh = new Mesh(gl, { geometry, program });

    el.appendChild(canvas);
    canvas.style.display = 'block';

    const resize = (w: number, h: number) => {
      renderer.setSize(w, h);
      // `setSize` writes literal px into the canvas's inline style, which wins
      // over any class. Re-asserting percentages keeps the element fluid
      // between resize notifications.
      canvas.style.width = '100%';
      canvas.style.height = '100%';

      uniforms.uResolution.value = [gl.drawingBufferWidth, gl.drawingBufferHeight];
      uniforms.uPixelRatio.value = renderer.dpr;

      // Population from area, not from a fixed number: the same density looks
      // right in a 320px card and in a 2000px hero. The buffers already hold
      // `total` particles in scattered order, so a prefix of them is still a
      // spatially even field — no rebuild, no reallocation.
      const megapixels = (w * h) / 1_000_000;
      const count = clamp(Math.round(megapixels * density), MIN_COUNT, total);
      geometry.setInstancedCount(count);
    };

    const draw = (elapsed: number) => {
      uniforms.uElapsed.value = elapsed;
      renderer.render({ scene: mesh });
    };

    resize(size.current.width, size.current.height);
    stage.current = { renderer, geometry, program, mesh, uniforms, resize, draw };
    draw(STATIC_ELAPSED);

    return () => {
      stage.current = null;
      // ogl has no `dispose()`: `remove()` on the geometry deletes its VAOs and
      // every buffer, `remove()` on the program deletes the shaders and the
      // program, and only then is the context worth handing back.
      geometry.remove();
      program.remove();
      loseContext(gl);
      canvas.width = 0;
      canvas.height = 0;
      canvas.remove();
    };
  }, [
    ready,
    density,
    maxCount,
    minSize,
    maxSize,
    softness,
    spin,
    speed,
    wander,
    opacity,
    colorA,
    colorB,
    background,
    seed,
  ]);

  // Resize is its own effect: a reflow costs a `setSize` and an instanced-count
  // change, never a buffer rebuild.
  useEffect(() => {
    stage.current?.resize(width, height);
    if (reduced) stage.current?.draw(STATIC_ELAPSED);
  }, [width, height, reduced]);

  useRaf(
    (_dt, elapsed) => stage.current?.draw(elapsed),
    ready && inView && visible && !reduced && !unsupported,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `geometry.remove()` deletes every VAO and every buffer, `program.remove()` deletes the shaders and the program, then `loseContext(gl)` hands the context back through `WEBGL_lose_context` — ogl has no `dispose()` and nothing else releases a context. The canvas backing store is zeroed and the node removed, so the drawing buffer goes with it rather than waiting for GC.

**Reduced motion.** The rAF subscription is never made and the field is drawn once at `elapsed` 0. That is a complete, correct frame rather than a collapsed one: the scatter, sizes, tints, shapes and spin phases are all per-particle seeds that already vary at t=0, and the wrap fade applies exactly as it does in motion. Resizing redraws the same still.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Reaching for `gl_PointSize`. It is capped — 255px on a great many drivers, and the cap is silent — it cannot be rotated, and the sprite is culled by its centre point, so anything large blinks out while half of it is still on screen.
- Leaving ogl's `cullFace` at its default. `Program` defaults it to `gl.BACK`; once the quad corners are rotated in the vertex shader the winding the driver sees is not the winding you authored, and culled particles are simply absent with no error anywhere.
- Rotating the corner offset after converting to clip space. The container aspect ratio shears it, so a particle is square only when the container is, and it visibly changes shape through a spin.
- Rebuilding the buffers on resize to change the particle count. `setInstancedCount` selects a prefix of what is already uploaded; reallocating 72 KB of GPU memory on every ResizeObserver notification is a stall for no visual difference.
- Wrapping with `fract` and no fade. The seam is a hard teleport, and at 1800 particles something is crossing it constantly, so the field flickers along one edge.
- Compositing an additive field onto a transparent canvas. Additive needs to know what it is adding to; with `alpha: true` the destination is zero, the result is the particle colour flat, and the field looks pasted on rather than glowing.
- Reusing one React-owned canvas across effect runs. Cleanup force-loses the context, and `getContext` on that same element afterwards returns the dead one — under StrictMode's mount / unmount / mount that means every instance is permanently black. ogl creates its own canvas, which is appended and removed per run.
- Assuming `renderer.setSize` leaves the CSS alone. ogl writes literal px into the canvas's inline `style`, which beats any class; the percentages have to be re-asserted after every call or the element stops being fluid.

## Notes

- ogl rather than three: the whole component is one instanced mesh with no lights, no camera and no scene graph, and ogl's `Geometry` exposes instanced attributes directly with `instanced: 1` instead of through an `InstancedBufferGeometry` wrapper.
- No camera is passed to `renderer.render`, which is deliberate. Without one ogl skips frustum culling and the matrix uniforms entirely — the shader writes clip space itself, so a projection matrix would be an identity multiply per vertex.
- `depth: false` on the context. Nothing occludes anything under additive blending, so a depth buffer would be memory plus a clear per frame for no result.
- Sizes are authored in CSS pixels and multiplied by the pixel ratio in the shader, so the field looks identical across a dpr change and nothing needs rebuilding when one happens.
- GLSL ES 1.00 with no derivative functions: the edge anti-aliasing floor is `1.0 / sizePx`, which is exact for a quad of that pixel size, so the same source compiles under a WebGL1 fallback context where `fwidth` needs an extension.

## Definition of done

The field drifts upward and sideways with no visible seam at the top or bottom edge, and no particle ever appears or vanishes abruptly. Individual particles spin, and the shards are visibly rotating rather than shimmering. Resize the container narrow and wide: particles stay square at every aspect ratio, and the population changes without a stutter. One draw call per frame in a frame capture, whatever the count. Mount and unmount a dozen instances and none of the earlier ones go black.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Inverse Scroll Scale

The inverse of the usual scroll-scale. Instead of growing as it rises, the media starts oversized and resolves down to exactly 1.0 over the first 60% of the scroller, so it settles into its frame rather than bursting out of it — and it is at rest for the whole time it is the thing you are actually looking at. No animation library: one rAF callback, gated by an IntersectionObserver.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Media enters oversized at 1.25x and settles to exactly 1.0 as it rises through the first 60% of the scroller.

- Category: scroll
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. Each frame the component reads the frame element's `getBoundingClientRect().top`, converts it to a position inside the scroller by subtracting the scroller's own rect top, and computes `t = clamp((height - top) / (span * height), 0, 1)`.
2. `t` is 0 while the frame's top edge sits on the bottom of the scroller and reaches 1 once it has climbed `span` of the scroller's height — 60% by default, so it is finished long before the element is centred.
3. Scale is a straight linear ramp: `from - (from - 1) * t`. It ends on exactly 1.0 by construction, which matters because a scale below 1 on an element sized to its frame would let the frame show through at the edges.
4. Optional smoothing runs the result through `damp(current, wanted, smoothing, dt)`, which raises the retention factor to the power of elapsed time and so converges at the same rate on 60Hz and 120Hz displays. The naive `x += (target - x) * 0.1` would run twice as fast on the faster display.
5. The frame is rounded to four decimals and compared against what was last written; on the many frames where nothing changed the style write is skipped entirely, so an idle instance costs one rect read.
6. An IntersectionObserver with a 20% rootMargin flips an `active` ref, and the rAF callback returns immediately when it is false. The observer is hand-rolled rather than pooled because it needs the demo's scroller as its `root`.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `from = 1.25`
  Starting scale. Must be at least 1 — anything less shows the frame through the edges of the media, because the media is sized to exactly fill the frame. Past ~1.4 the visible crop at the start is severe enough that the composition changes rather than just the size.
- `span = 0.6`
  Fraction of scroller height over which the scale resolves, measured up from the bottom edge. The whole argument for the effect: at 1.0 the media is still moving while it is centred and being read, which is exactly when it should be still. At 0.6 it lands well before that.
- `smoothing = 0`
  Off by default. The mapping from scroll position to scale is already continuous, so smoothing adds lag with nothing to hide. It exists for the case where the scroll source is itself steppy (a trackpad-free mouse wheel, or a snapped container).
- `rootMargin = '20% 0px 20% 0px'`
  Starts the rAF work a fifth of a scroller height before the frame is visible, so the first painted frame is already at the correct scale. Without the margin the element pops from its authored scale to its computed one on the frame it enters.
- `toFixed precision = 4`
  Below one device pixel of difference on a 4000px-wide element, so the rounding is invisible; its purpose is to make the "unchanged" comparison actually hit, which it never would on raw floats.

## API

```ts
function InverseScrollScale(props: { children: ReactNode; from?: number; span?: number; smoothing?: number; scrollerRef?: RefObject<HTMLElement | null>; className?: string }): JSX.Element
```

- `children: ReactNode`
  The media. Sized to fill the frame; this is what gets scaled.
- `from: number` — default `1.25`
  Starting scale. Must be >= 1.
- `span: number` — default `0.6`
  Fraction of scroller height over which the scale resolves.
- `smoothing: number` — default `0`
  Fraction of the remaining gap left after one second. 0 disables smoothing.
- `scrollerRef: RefObject<HTMLElement | null>`
  The scroll container that owns the scroll position. Omit for the document.
- `className: string`
  Merged onto the frame via `cn`. Set the frame size here.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function InverseScrollScale({
  children,
  from = 1.25,
  span = 0.6,
  smoothing = 0,
  scrollerRef,
  className,
}: InverseScrollScaleProps) {
  const frame = useRef<HTMLDivElement>(null);
  const media = useRef<HTMLDivElement>(null);
  const active = useRef(false);
  const scale = useRef(from);
  const written = useRef(-1);
  const reduced = useReducedMotion();

  // Gate the rAF work on visibility. Hand-rolled rather than `useInView`
  // because the observer needs a custom `root` — the demo's own scroller —
  // and a pooled observer keyed only by threshold would hand back one rooted
  // at the document.
  useEffect(() => {
    const el = frame.current;
    if (!el || reduced) return;

    const observer = new IntersectionObserver(
      (entries) => {
        for (const entry of entries) active.current = entry.isIntersecting;
      },
      { root: scrollerRef?.current ?? null, rootMargin: '20% 0px 20% 0px' },
    );
    observer.observe(el);
    return () => observer.disconnect();
  }, [reduced, scrollerRef]);

  useRaf(
    (dt) => {
      const el = frame.current;
      const target = media.current;
      if (!el || !target || !active.current) return;

      // One read pass, then one write pass. Reading the rect after writing a
      // transform in the same frame forces a synchronous layout.
      const scroller = scrollerRef?.current ?? null;
      const rect = el.getBoundingClientRect();
      const height = scroller ? scroller.clientHeight : window.innerHeight;
      const top = scroller ? rect.top - scroller.getBoundingClientRect().top : rect.top;

      // t is 0 while the frame's top edge is at the bottom of the scroller and
      // reaches 1 once it has risen `span` of the scroller's height.
      const t = clamp((height - top) / (span * height), 0, 1);
      const wanted = from - (from - 1) * t;

      scale.current =
        smoothing > 0 ? damp(scale.current, wanted, smoothing, dt) : wanted;

      // Four decimals is below one device pixel on a 4000px element, and the
      // equality check skips the style write on the many frames where nothing
      // changed — an idle instance then costs a rect read and nothing else.
      const next = Number(scale.current.toFixed(4));
      if (next === written.current) return;
      written.current = next;
      target.style.transform = `scale(${next})`;
    },
    !reduced,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useRaf` unsubscribes on unmount and drops the shared loop entirely when it was the last subscriber; the IntersectionObserver is disconnected in its own effect cleanup. Without the disconnect the observer holds a reference to a removed element and keeps firing on every scroll of a container the component no longer participates in.

**Reduced motion.** The media renders at scale 1 — its resolved state, filling the frame — and neither the IntersectionObserver nor the rAF subscription is created, so there is no per-frame work at all.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Using `window.innerHeight` when the element scrolls inside a container. Inside a 300px-tall panel on a 1000px-tall window, `t` never exceeds about 0.3, so the media stays visibly oversized for the whole scroll and never resolves.
- Scaling from below 1 up to 1 instead. The media is sized to its frame, so any scale under 1 leaves a gap at the edges and the background shows through as a hairline border that grows and shrinks.
- Reading `getBoundingClientRect()` after writing the transform in the same callback. That is a forced synchronous layout every frame, and it appears in a profile as a long purple bar attached to the rAF, not as anything obviously related to this component.
- Running the rAF callback for every instance on the page. Ten of these in a long article means ten rect reads per frame for elements that are nowhere near the viewport; the IntersectionObserver gate is what keeps the cost proportional to what is on screen.
- A per-frame lerp constant instead of `damp` when smoothing is enabled. On a 120Hz display the media reaches its target in half the scroll distance, so the effect is materially different on a MacBook Pro than on an external 60Hz monitor.
- Omitting `overflow: hidden` on the frame. At 1.25 the media is 25% larger than its box and overlaps whatever is next to it, which is most visible as text from the following section being covered as you scroll.

## Notes

- No animation library. The whole component is one rAF subscription and one IntersectionObserver.
- The transform is written imperatively rather than through React state, so no scroll frame causes a render.

## Definition of done

Scroll the frame up from the bottom of the scroller: the media is visibly cropped and oversized as it appears, and reaches its natural size a little past halfway up — after which it does not move at all while you read it. Scroll back down and it re-expands. No hairline of background is ever visible inside the frame. With reduced motion on, the media is at natural size at all scroll positions.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: IntersectionObserver Reveal

A wrapper that fades and lifts its child into place the first time it enters the scroll container. The transition is one inline string built from four numbers, so nothing is injected into the document and nothing has to load. Every instance that asks for the same root and the same observation box shares one IntersectionObserver, which is what makes it safe to put two hundred of these on a page.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

One element, one fade-and-rise on entry, no stylesheet and no library — with a single observer shared across every instance.

- Category: scroll
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. The element renders at `opacity: 0` and `translate3d(0, 28px, 0)` with a transition string of `opacity 0.7s cubic-bezier(0.22,1,0.36,1) {delay}s, transform 0.7s cubic-bezier(0.22,1,0.36,1) {delay}s`. State flips both properties at once, so the browser interpolates on the compositor and the main thread does nothing after the flip.
2. The observer is pooled in a two-level module map: root element first, then a `rootMargin|threshold` string. `null` is a legal Map key, so "the viewport" gets its own bucket without a sentinel. Each bucket holds a `Map<Element, handler>` and the observer callback dispatches by target — one callback for every reveal in a container.
3. The pool is refcounted. Teardown deletes the handler and unobserves, then disconnects and drops the bucket only when the last target has left. Disconnecting per instance would tear the shared observer out from under every other reveal in the same container.
4. The root is resolved as: an explicit `scroller` ref, else the first ancestor whose computed `overflow-x` or `overflow-y` is `auto`, `scroll` or `overlay`, else `null` for the viewport. `window` is never referenced, so the component behaves the same inside a 320 px preview card as on a full page.
5. `threshold: 0.15` with `rootMargin: "0px 0px -8% 0px"` shrinks the observation box 8% up from the bottom, so an element must be genuinely inside the container before it fires rather than merely touching its edge.
6. Staggering is the caller's job and costs one number: give siblings `delay={0}`, `0.08`, `0.16`. There is no group concept and no shared timeline, which is precisely what keeps the component this small.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `duration = 0.7`
  Seconds. Long enough that a 28 px rise reads as a settle rather than a snap; past ~1s a fast scroller has already read the text while it is still moving.
- `distance = 28`
  Pixels of travel. Roughly one and a half line heights — the element stays inside its own block, so the reveal reads as the content arriving rather than as a card flying in from off-screen. Above ~60 px the motion starts to compete with the scroll itself.
- `ease = cubic-bezier(0.22, 1, 0.36, 1)`
  Ease-out-quint. Most of the travel is spent in the first third, which is what makes a reveal feel like arrival. A symmetric curve on an entrance always reads as sluggish because the slow part happens while the element is still visibly out of place.
- `threshold = 0.15`
  15% of the element must be visible. At 0 a single intersecting pixel fires the reveal, so a tall element finishes animating before it is on screen. Above ~0.4 an element taller than the container can never satisfy it and never reveals at all.
- `rootMargin = 0px 0px -8% 0px`
  The negative bottom is the whole point: it pulls the trigger line 8% up from the container's bottom edge so the element is inside the box, not touching it. A positive bottom margin fires below the fold and the user scrolls onto content that has already finished.

## API

```ts
function IoReveal(props: { children: ReactNode; scroller?: RefObject<HTMLElement | null>; delay?: number; duration?: number; distance?: number; ease?: string; threshold?: number; rootMargin?: string; repeat?: boolean; as?: ElementType; className?: string }): JSX.Element
```

- `children: ReactNode`
  The revealed content.
- `scroller: RefObject<HTMLElement | null>`
  Scroll container for the observer. Omit and the nearest scrollable ancestor is found by walking computed overflow.
- `delay: number` — default `0`
  Seconds of delay. Staggering siblings is done by passing 0, 0.08, 0.16.
- `duration: number` — default `0.7`
  Seconds of travel and fade.
- `distance: number` — default `28`
  Starting vertical offset in pixels. Positive rises into place.
- `ease: string` — default `'cubic-bezier(0.22, 1, 0.36, 1)'`
  Any CSS timing function.
- `threshold: number` — default `0.15`
  Fraction of the element that must be visible before it fires.
- `rootMargin: string` — default `'0px 0px -8% 0px'`
  Observation box inset. Part of the shared-observer pool key.
- `repeat: boolean` — default `false`
  Re-hide when the element leaves. Off by default, which also lets settled targets be unobserved.
- `as: ElementType` — default `'div'`
  Element to render, so the wrapper can be inline or a list item.
- `className: string`
  Merged onto the rendered element.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/* --------------------------------------------------------------------------
   The shared observer pool.

   Keyed by root element first, then by the option string. `null` is a legal
   key in a Map, which is what lets "the viewport" share a bucket with itself
   without a sentinel value. Each bucket refcounts its targets and the
   observer is disconnected when the last one leaves, so a route change does
   not leave observers watching detached nodes.
   -------------------------------------------------------------------------- */
type Handler = (entry: IntersectionObserverEntry) => void;

interface Bucket {
  observer: IntersectionObserver;
  handlers: Map<Element, Handler>;
}

const pools = new Map<Element | null, Map<string, Bucket>>();

function bucketFor(root: Element | null, rootMargin: string, threshold: number): Bucket {
  let byOptions = pools.get(root);
  if (!byOptions) {
    byOptions = new Map<string, Bucket>();
    pools.set(root, byOptions);
  }
  const key = `${rootMargin}|${threshold}`;
  const existing = byOptions.get(key);
  if (existing) return existing;

  const handlers = new Map<Element, Handler>();
  const observer = new IntersectionObserver(
    (entries) => {
      for (const entry of entries) handlers.get(entry.target)?.(entry);
    },
    { root, rootMargin, threshold },
  );
  const bucket: Bucket = { observer, handlers };
  byOptions.set(key, bucket);
  return bucket;
}

function release(root: Element | null, rootMargin: string, threshold: number): void {
  const byOptions = pools.get(root);
  if (!byOptions) return;
  const key = `${rootMargin}|${threshold}`;
  const bucket = byOptions.get(key);
  if (!bucket || bucket.handlers.size > 0) return;
  bucket.observer.disconnect();
  byOptions.delete(key);
  if (byOptions.size === 0) pools.delete(root);
}

/**
 * Nearest ancestor that actually scrolls. An `overflow: auto` element that has
 * not overflowed yet still counts: it is the container this reveal will live
 * inside once content arrives. Returning `null` means the viewport, which is
 * the value IntersectionObserver's `root` already uses for that.
 */
function nearestScrollParent(node: Element | null): Element | null {
  let el = node?.parentElement ?? null;
  while (el) {
    const { overflowY, overflowX } = getComputedStyle(el);
    if (/(auto|scroll|overlay)/.test(overflowY + overflowX)) return el;
    el = el.parentElement;
  }
  return null;
}

export function IoReveal({
  children,
  scroller,
  delay = 0,
  duration = DURATION,
  distance = DISTANCE,
  ease = EASE,
  threshold = THRESHOLD,
  rootMargin = ROOT_MARGIN,
  repeat = false,
  as,
  className,
}: IoRevealProps) {
  const ref = useRef<HTMLElement>(null);
  const reduced = useReducedMotion();
  const [revealed, setRevealed] = useState(false);

  useEffect(() => {
    const el = ref.current;
    if (!el || reduced) return;
    if (typeof IntersectionObserver === 'undefined') {
      // A missing API degrades to visible content, never to a blank page.
      setRevealed(true);
      return;
    }

    const root = scroller ? scroller.current : nearestScrollParent(el);
    const bucket = bucketFor(root, rootMargin, threshold);

    const handle: Handler = (entry) => {
      if (entry.isIntersecting) {
        setRevealed(true);
        if (!repeat) {
          bucket.handlers.delete(el);
          bucket.observer.unobserve(el);
        }
      } else if (repeat) {
        setRevealed(false);
      }
    };

    bucket.handlers.set(el, handle);
    bucket.observer.observe(el);

    return () => {
      bucket.handlers.delete(el);
      bucket.observer.unobserve(el);
      // Refcounted: the observer only dies with its last target. Disconnecting
      // per instance would tear the shared observer out from under every other
      // reveal in the same container.
      release(root, rootMargin, threshold);
    };
  }, [scroller, rootMargin, threshold, repeat, reduced]);

  /* Reduced motion is a different render, not a faster one: no transition
     property is emitted at all, and the element is at its resolved end state
     from the first paint. */
  const style: CSSProperties = reduced
    ? {}
    : {
        opacity: revealed ? 1 : 0,
        transform: revealed ? 'translate3d(0, 0, 0)' : `translate3d(0, ${distance}px, 0)`,
        // One string, two properties, one shared delay. Written inline on
        // purpose: this variant ships no stylesheet, so there is nothing for a
        // consumer's CSS to load and nothing to hoist.
        transition: `opacity ${duration}s ${ease} ${delay}s, transform ${duration}s ${ease} ${delay}s`,
        willChange: revealed ? undefined : 'opacity, transform',
      };
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The effect deletes its handler from the shared bucket, unobserves its own element, then calls `release`, which disconnects the observer and drops the bucket only when no handlers remain. No listeners, no rAF, no timers. The pool itself holds no reference to an element once its handler is removed, so nothing keeps a detached node alive.

**Reduced motion.** The reduced branch renders a different element, not a faster one: the style object is empty, so no `opacity`, no `transform` and no `transition` are emitted and the content is at its resolved final state on the first paint. No observer is created either, which also means no work is scheduled for a user who asked for none. `useReducedMotion` reads through `useSyncExternalStore`, so the value lands in the hydration commit and the animated variant is never painted.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Keying the shared observer on `rootMargin` and `threshold` but not on the root. The first instance to mount then decides which container everyone measures against, and every later instance inside a different scroll panel reports "in view" from the start — so an entire panel reveals on mount and never animates again. The root has to be part of the key.
- Calling `observer.disconnect()` in a single instance's cleanup. With a shared observer that stops every other reveal in the same container dead, and the symptom appears only after a route change unmounts one card. Delete the handler, unobserve the one target, and disconnect only when the handler map is empty.
- Constructing an observer per element. It works and it is invisible at ten elements; at two hundred the browser services two hundred separate intersection computations on every scroll of the container and the frame budget goes to bookkeeping.
- One observer for the whole page with `root: null` when the content is inside an `overflow-y: auto` panel. Everything in the panel intersects the viewport from the start, so every reveal fires at mount.
- Animating `top` or `margin-top` instead of `transform`. Both are layout properties: the reveal then triggers layout on every frame for every element currently animating, and a page with a dozen simultaneous reveals visibly stutters.
- Leaving `will-change: opacity, transform` on after the reveal. Every settled element keeps its own compositor layer, and a long page accumulates hundreds of them until scrolling gets slower the further down you go. It is set only while the element is still hidden.
- Treating reduced motion as `duration: 0`. That still emits a transition and still runs the state flip through the compositor. Here the reduced branch emits no `transition`, no `opacity` and no `transform` at all, so the element is simply in its final position from the first paint.

## Notes

- This variant ships zero CSS, which is the trade it makes: the hidden start state is an inline style on the first render, so a document that never executes scripts renders the content hidden. `css-var-stagger-reveal` is the sibling that pays for a hoisted stylesheet and gets a `@media (scripting: none)` escape hatch in return. Choose this one for a component library where injecting global CSS is unwelcome; choose that one for a site where a designer will retune the choreography and no-JS has to look right.
- Compared to a GSAP reveal system, this cannot scrub, cannot be measured against a `containerAnimation`, and has no timeline you can seek. It is deliberately the floor of the feature set: entry, once, with a delay.
- `as` lets the wrapper be a `span` inside a paragraph or an `li` inside a list, so the reveal does not force an invalid nesting or an extra block-level box into the layout.

## Definition of done

Scroll the container and each element rises 28 px and fades in as it comes properly into view, not as it touches the bottom edge. Give three siblings delays of 0, 0.08 and 0.16 and they arrive in sequence. Mount fifty of them and the browser reports one IntersectionObserver, not fifty. Unmount one card and the rest keep revealing. With reduced motion on, every element is already in place and inspecting it shows no inline `transition` at all.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Single Param Object Timeline

A scroll-driven scene written as data instead of as tweens. One mutable object holds every animated quantity, GSAP tweens the object rather than the DOM, and a single onUpdate writes one transform string and two opacities. The story is then an array of rows — section id, point through the section, params to move to — each anchored to where its section actually sits after layout.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

One plain object holds every animated value; the scroll story is a table of keyframes anchored to real sections.

- Category: scroll
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. Every animated quantity lives in one object: `{ scale, spin, driftX, driftY, glow, dissolve }`. No element is a tween target; GSAP tweens the plain object and one `onUpdate` renders it, so the number of tweens is the number of story beats rather than the number of moving parts.
2. Each keyframe is anchored to a real section: `anchor = clamp(0, 1, (el.offsetTop + el.offsetHeight * t - view / 2) / total)`, where `total = container.offsetHeight - view` is the scroll distance the trigger covers.
3. That expression reads as "when the point `t` through this section reaches the middle of the viewport". `t = 0.5` is the section's own middle, so the beat fires when the reader is looking at the copy it belongs to, at any column width.
4. Rows are sorted by anchor and each is given `duration = nextAnchor - thisAnchor`, so the scene is continuously in motion between beats instead of arriving early and sitting still until the next anchor.
5. `ease: "none"` on every row. Under a scrub the ease warps timeline time, not screen time, so an eased row reaches its params before or after the section it is anchored to — which defeats the anchoring.
6. A `useResizeObserver` on the container re-runs the whole build when its height changes, because every anchor is a function of `offsetTop` and `offsetTop` moves whenever a line wraps.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `scrub = 0.8`
  Just under a second of catch-up. Enough that the scene continues to resolve after the wheel stops, which is what makes it read as a film rather than a slider; `true` welds it to the wheel and every scroll jitter shows up in the mark.
- `at = 0.5`
  Default point through a section at which its keyframe lands. 0.5 puts the beat on the section's midpoint crossing the middle of the scroller. Values near 0 fire while the section is still entering, which reads as the scene reacting to copy the reader has not got to yet.
- `REST.glow = 0.35`
  The scene's idle state, not zero. The stage has to be worth looking at before the first keyframe and after the last one; starting at 0 means the reader's first impression of the component is an empty box.
- `total floor = 1`
  Guards `container.offsetHeight - view` against 0 or negative, which happens for one frame during layout and on a short container. Without it every anchor divides by zero, becomes Infinity, clamps to 1, and the whole story collapses onto the last frame.
- `span floor = 0.001`
  Two keyframes anchored to the same point would otherwise get duration 0. GSAP accepts it, but the row then applies as an instant jump, so a carefully anchored beat becomes a snap.
- `section gap = 45vh`
  Spacing between story sections, in scroller heights. Below about 30vh two anchors land close enough that their spans overlap heavily and the beats blur together; well above it the scene is static for long stretches.

## API

```ts
function KeyframeParamObject(props: { sections: { id: string; label: string; title: string; body?: string; at?: number; to: Partial<StageParams> }[]; scrub?: number; scrollerRef?: RefObject<HTMLElement | null>; className?: string }): JSX.Element
```

- `sections: KeyframeSection[]`
  The story. Each row names a section, an optional point through it, and the params to move to.
- `sections[].at: number` — default `0.5`
  Point through the section, 0-1, at which its keyframe lands.
- `sections[].to: Partial<StageParams>`
  Params this beat moves to. Anything omitted holds its current value.
- `scrub: number` — default `0.8`
  Seconds of catch-up behind the scroll position.
- `scrollerRef: RefObject<HTMLElement | null>`
  The scroll container that owns the scroll position. Omit for the document.
- `className: string`
  Merged onto the container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function KeyframeParamObject({
  sections,
  scrub = 0.8,
  scrollerRef,
  className,
}: KeyframeParamObjectProps) {
  const root = useRef<HTMLDivElement>(null);
  const mark = useRef<HTMLDivElement>(null);
  const halo = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();
  // Rebuild the anchor table whenever the column reflows: every anchor is a
  // function of offsetTop, and offsetTop changes when a line wraps.
  const { height } = useResizeObserver(root);

  useGsap(
    gsap,
    () => {
      const container = root.current;
      const markEl = mark.current;
      const haloEl = halo.current;
      if (!container || !markEl || !haloEl) return;

      // The one mutable object. Cloned per build so a rebuild starts clean
      // rather than inheriting wherever the last scrub left it.
      const params: StageParams = { ...REST };

      const render = () => {
        markEl.style.transform =
          `translate3d(${params.driftX}%, ${params.driftY}%, 0) ` +
          `rotate(${params.spin * 360}deg) scale(${params.scale})`;
        markEl.style.opacity = String(Math.max(0, 1 - params.dissolve));
        haloEl.style.opacity = String(params.glow);
        haloEl.style.transform = `scale(${1 + params.glow * 0.6})`;
      };

      if (reduced) {
        // Land on the last keyframe: the end of the story, statically.
        for (const section of sections) Object.assign(params, section.to);
        render();
        return;
      }

      const scroller = scrollerRef?.current ?? null;
      const view = scroller ? scroller.clientHeight : window.innerHeight;
      // Scroll distance the trigger actually covers. Guarded against 0, which
      // would make every anchor Infinity and stack the whole story on frame 1.
      const total = Math.max(1, container.offsetHeight - view);

      const anchor = (el: HTMLElement, t: number) =>
        gsap.utils.clamp(0, 1, (el.offsetTop + el.offsetHeight * t - view / 2) / total);

      const rows = sections
        .map((section) => {
          const el = container.querySelector<HTMLElement>(`[data-keyframe="${section.id}"]`);
          return el ? { at: anchor(el, section.at ?? 0.5), to: section.to } : null;
        })
        .filter((row): row is { at: number; to: Partial<StageParams> } => row !== null)
        // Authoring order is document order, but a custom `at` can reorder
        // them; the timeline needs them sorted to compute each row's span.
        .sort((a, b) => a.at - b.at);

      const timeline = gsap.timeline({
        scrollTrigger: {
          trigger: container,
          scroller: scroller ?? undefined,
          start: 'top top',
          end: 'bottom bottom',
          scrub,
          invalidateOnRefresh: true,
        },
        onUpdate: render,
      });

      rows.forEach((row, i) => {
        const next = rows[i + 1];
        // Each row travels until the next one begins, so the scene is always
        // in motion between beats and never sits finished waiting for the
        // next anchor.
        const span = Math.max(0.001, (next ? next.at : 1) - row.at);
        // `ease: 'none'` — under a scrub the ease warps timeline time, so an
        // eased row arrives at its params before or after its own section.
        timeline.to(params, { ...row.to, duration: span, ease: 'none' }, row.at);
      });

      render();
    },
    root,
    [sections, scrub, scrollerRef, reduced, height],
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useGsap` reverts the `gsap.context`, which kills the timeline and its ScrollTrigger and drops the reference to the params object. This runs on every reflow as well as on unmount: a surviving trigger would keep scrubbing a timeline built against stale `offsetTop` values while a new one runs alongside it, and the two would write conflicting transforms to the same element on the same frame.

**Reduced motion.** No timeline and no ScrollTrigger are created. Every keyframe is folded into the params object in order and rendered once, so the stage shows the end of the story and the copy is fully readable and correctly laid out.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Hand-tuning keyframe positions as raw timeline fractions. A single line wrap moves every section below it, so the beat that was on the right paragraph at 1440px is a paragraph early at 1280px. Anchoring to `offsetTop` is the fix and is the reason for the whole `anchor` expression.
- Not rebuilding when the container reflows. The anchors are computed once from measurements taken at build time; a font swap, an image load or an orientation change moves the sections and the timeline keeps using the old numbers.
- Tweening the DOM directly instead of the object. With six properties across three elements you get a tween per property per beat, they fight over the same transform string, and the last one to write wins non-deterministically.
- Easing the rows under a scrub. The ease is applied to timeline time, so the params reach their target at a different scroll position than the anchor says — the beat visibly detaches from its heading.
- Reusing one module-level params object across builds. On rebuild the tweens start from wherever the previous scrub left the object rather than from the resting state, so the scene is subtly different after every resize.
- Letting `total` be zero. It happens on the first layout pass and on any container shorter than the viewport; every anchor becomes Infinity, clamps to 1, and the entire story plays in the last pixel of scroll.

## Notes

- The stage is `position: sticky`, not fixed, so it is bounded by the component rather than by the page and works inside any scroll container.
- Pass `sections` as a stable reference (module scope or memoised) — it is a dependency of the build effect.

## Definition of done

Scroll through the column: the mark scales, spins, drifts and dims, and each change lines up with the heading that names it reaching the middle of the panel. Resize the panel so the copy rewraps and scroll again — the beats still land on their headings. Stop mid-scroll and the scene keeps resolving for around a second. With reduced motion on, the stage shows the final state and nothing moves.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Knockout Zoom Pin

A sticky section holds a single word while a manufactured scroll range plays a zoom out: the word starts several screens wide, showing a gradient through its letters, and settles into a normal headline position. No library — the progress is read from the sticky section's own rect, smoothed exponentially in wall-clock time, and written as one composited transform per changed frame.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A word the size of the screen shrinks into a headline as you scroll, with the scene showing through its letters.

- Category: scroll
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. The scroll range is manufactured from the scroller's own height: the section is sized `hostHeight * (1 + viewports)` in pixels and the sticky child is sized `hostHeight`, so the leftover is exactly the pin duration. Pixels, not `vh`, because inside a scrollable box viewport units describe the wrong element.
2. Progress is `(hostTop - sectionTop) / (total - hostHeight)`, clamped. It comes from `getBoundingClientRect()` on the frame it is used, so it stays correct through resizes, font swaps and layout shifts with nothing to invalidate.
3. The raw progress is smoothed with `damp(smoothed, target, smoothing, dt)` — `x + (t - x) * (1 - s^dt)` — so the settle takes the same wall-clock time at 60 and 144 Hz. The per-frame form (`x += (t - x) * 0.1`) converges more than twice as fast on a high-refresh display.
4. Scale and position use different curves on purpose. Scale is `cover - (cover - 1) * easeOutCubic(L)`, front-loading the shrink; the recentre is `easeInCubic(L)`, which keeps the word centred until it is small enough for its position to mean anything.
5. The transform is built as a string, rounded to 4 decimals of scale and 0.1 px of translate, and compared with the previous frame's string. Unchanged frames skip the DOM write entirely, which at both ends of the range is most of them.
6. The letters are a window rather than a fill: `background-clip: text` with a transparent colour, so the gradient behind them scales with the word and the section reads as cut out of the page.
7. The word is sized in `cqw` against a `container-type: inline-size` pin box, so the component is identical in a 320 px preview card and a full-bleed page without a single breakpoint.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `cover = 7`
  Scale at progress 0 — enough that only the counters of one or two letters are on screen, so the opening frame reads as texture and the reveal of the word is the payoff. Below ~4 the word is legible immediately and there is nothing to reveal.
- `viewports = 1.6`
  Scroll travel as a multiple of the scroller height. Under ~1 the zoom is over before it registers; past ~2.5 the pin outstays its welcome and users start scrolling hard to escape it.
- `smoothing = 0.0067`
  Fraction of the gap remaining after one second — `e^-5`, i.e. the familiar `1 - exp(-5 * dt)` filter. It removes trackpad and wheel-step judder without the word feeling detached from the hand. At 0.05 the lag is visible as rubberiness.
- `rest = -0.3`
  Final vertical position as a fraction of the pinned box: three tenths above centre, which is where a display headline sits when body copy follows it.
- `veil window = progress 0.45 → 0.95`
  When the content behind fades up. Earlier and it competes with a word still too large to read past; later and it arrives after the motion has stopped, which reads as a second, unrelated event.
- `write quantisation = 4 dp scale, 0.1 px translate`
  Below a tenth of a device pixel nothing changes on screen, so the comparison lets idle frames cost one string build and one comparison instead of a style write and a composite.

## API

```ts
function KnockoutZoomPin(props: { children: ReactNode; behind?: ReactNode; cover?: number; viewports?: number; smoothing?: number; rest?: number; scroller?: RefObject<HTMLElement | null>; className?: string }): JSX.Element
```

- `children: ReactNode`
  The word. Kept on one line — it is a display element.
- `behind: ReactNode`
  Content faded up behind the word as it settles.
- `cover: number` — default `7`
  Scale at progress 0.
- `viewports: number` — default `1.6`
  Scroll travel as a multiple of the scroller height.
- `smoothing: number` — default `0.0067`
  Fraction of the gap left after one second.
- `rest: number` — default `-0.3`
  Final vertical position as a fraction of the pinned box height.
- `scroller: RefObject<HTMLElement | null>`
  Scroll container. Omit to auto-detect the nearest scrollable ancestor.
- `className: string`
  Merged onto the outer section.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function KnockoutZoomPin({
  children,
  behind,
  cover = 7,
  viewports = 1.6,
  smoothing = 0.0067,
  rest = -0.3,
  scroller,
  className,
}: KnockoutZoomPinProps) {
  const section = useRef<HTMLElement>(null);
  const pin = useRef<HTMLDivElement>(null);
  const word = useRef<HTMLDivElement>(null);
  const veil = useRef<HTMLDivElement>(null);

  const smoothed = useRef(0);
  const lastTransform = useRef('');
  const lastVeil = useRef('');
  const lastHeights = useRef(0);
  const reduced = useReducedMotion();

  useRaf((dt) => {
    const sectionEl = section.current;
    const pinEl = pin.current;
    const wordEl = word.current;
    if (!sectionEl || !pinEl || !wordEl) return;

    const host = scroller?.current ?? nearestScroller(sectionEl);
    const hostIsRoot = host === document.documentElement;
    const hostTop = hostIsRoot ? 0 : host.getBoundingClientRect().top;
    const hostHeight = hostIsRoot ? window.innerHeight : host.clientHeight;
    if (hostHeight === 0) return;

    // The pin range is manufactured from the scroller's own height, not from
    // `vh`: inside a box, viewport units describe the wrong thing entirely.
    const total = Math.round(hostHeight * (reduced ? 1 : 1 + viewports));
    if (total !== lastHeights.current) {
      lastHeights.current = total;
      sectionEl.style.height = `${total}px`;
      pinEl.style.height = `${hostHeight}px`;
    }

    const rect = sectionEl.getBoundingClientRect();
    const travel = total - hostHeight;
    const target = travel > 0 ? clamp((hostTop - rect.top) / travel, 0, 1) : 1;

    // `damp(x, t, s, dt)` is `x + (t - x) * (1 - s^dt)`; with s = e^-5 that is
    // exactly the `1 - exp(-5 * dt)` constant the technique is named for.
    smoothed.current = reduced ? target : damp(smoothed.current, target, smoothing, dt);
    const L = smoothed.current;

    // Ease-out on the scale: most of the shrink happens early, so the last
    // third of the scroll is a slow settle rather than a continued rush.
    const scale = cover - (cover - 1) * easeOutCubic(L);
    // Ease-IN on the recentre: while the word is huge its position is
    // meaningless, so it must not start travelling until it is nearly small.
    const y = lerp(0, rest * hostHeight, easeInCubic(L));

    const transform = `translate3d(0, ${y.toFixed(1)}px, 0) scale(${scale.toFixed(4)})`;
    if (transform !== lastTransform.current) {
      lastTransform.current = transform;
      wordEl.style.transform = transform;
    }

    const veilEl = veil.current;
    if (veilEl) {
      const opacity = easeInCubic(clamp((L - 0.45) / 0.5, 0, 1)).toFixed(3);
      if (opacity !== lastVeil.current) {
        lastVeil.current = opacity;
        veilEl.style.opacity = opacity;
      }
    }
  });
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useRaf` unsubscribes from the shared loop on unmount; the only state is refs. The inline `height` values written to the section and the pin die with the elements, and no observers, listeners or timers are registered.

**Reduced motion.** The manufactured range collapses to one screen and the smoothing is bypassed, so progress tracks scroll exactly. The word passes through at its resting scale with the caption already present — the section becomes an ordinary headline block instead of leaving a screen and a half of empty scrolling behind.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Sizing the range in `vh` inside a scrollable container. The section is then sized against the window while progress is measured against the box, so the zoom finishes early, late, or never — and it looks correct only when the container happens to be full-height.
- Smoothing with a per-frame constant. The zoom lags noticeably further behind the scroll on a 60 Hz display than on a 120 Hz one, and every attempt to tune it makes the other refresh rate worse.
- Using the same easing for scale and for position. Move the word early and it slides around the screen while still too large to locate, which reads as a bug rather than as choreography.
- Animating `font-size` or `width` instead of `transform: scale`. Every frame relayouts and re-rasterises glyphs at a new size — the single most reliable way to turn this effect into a slideshow on a laptop.
- Writing the transform unconditionally each frame. At the top and bottom of the range the value is identical for dozens of frames, and each write still costs a style invalidation and a composite.
- Caching the section rect. A font swap or an image landing above the section moves it, and a cached top makes the zoom finish at the wrong scroll position for the rest of the session.
- Leaving the manufactured range in place under reduced motion. The user gets a screen and a half of scrolling where nothing happens at all; the height must collapse along with the animation.

## Notes

- The scroll container is auto-detected by walking ancestors for a scrollable `overflow-y`, so the component works unchanged on a normal page. Pass `scroller` when the container is ambiguous or created later.
- The knockout is `background-clip: text`, not an SVG mask: no extra element, no viewBox to keep in sync, and the text stays selectable and readable to assistive technology.
- A single word works best. Two lines re-wrap as the scale changes and the knockout stops reading as one shape.

## Definition of done

The word is unreadably large at the top of the section and lands as a normal headline exactly as the section releases. Scrolling backwards reverses it at the same rate. Stopping mid-zoom settles within about a quarter second with no drift. Resizing the window mid-zoom keeps the word at the same progress. With reduced motion on, the section is one screen tall and nothing scales.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Layout Lerp Scalar

One function places every card from seven scalars — radius, spacing, rowSpread, turns, depth, focus, scale — and each named layout is only a set of values for them. Morphing is therefore `gsap.to(params, preset)`: a tween over an object literal, with no per-item choreography anywhere. Crucially it interpolates the *inputs*, `f(lerp(a, b, s))`, not the outputs, so every intermediate frame is a valid member of the same family instead of a set of cards sliding along straight lines through each other.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Row, stack, drum and fan are one placement function of seven numbers. Switching layout is a tween over an object.

- Category: layout
- Runtime cost: webgl
- Dependencies: three@^0.185.1, gsap@^3.15.0

## How it works

1. Placement is `offset = wrappedOffset(i, position, n)`, then `angle = (offset / n) * 2PI * turns` and `p = (radius * sin(angle) + offset * rowSpread * step, -offset * spacing, radius * (cos(angle) - 1) - depth * |offset|)`, with `rotation.y = angle`. Setting `radius` and `turns` to 0 leaves a straight line; adding `spacing` makes it a column; adding `turns` and `radius` wraps that column into a drum. There is no branch anywhere in it.
2. Because the parameters are what get tweened, the shape passes through the family rather than across it. `f` is nonlinear in `radius` and `turns`, so `f(lerp(a, b, s))` and `lerp(f(a), f(b), s)` are different animations: the first keeps the cards on a well-formed helix at every `s`, the second sends each card down a chord that cuts through the middle of the drum and through its neighbours.
3. `cos(angle) - 1` rather than `cos(angle)` puts the focused card at z = 0 for any radius. Growing the drum then pushes the far side away instead of pulling the near card into the camera, which is what makes `radius` safe to tween through large values.
4. The `depth` term gives the flat layouts a strictly monotonic z in `|offset|`. That is not a look — it is what lets three's painter sort order the transparent cards correctly. With every card at z = 0 the sort has nothing to rank and the overlap order in a stack is whatever the traversal happened to produce.
5. The row step is derived from the camera: `visibleHeight = 2 * cameraZ * tan(fov / 2)`, `visibleWidth = visibleHeight * aspect`, and `step = visibleWidth * fill / (n - 1)`. Card size comes from the same `visibleHeight`, so the whole layout is defined in fractions of the frustum and holds its proportions at any viewport.
6. Focus is `1 - focus * (1 - exp(-offset^2))` — 1.000 at the centre, 0.368 one step out, 0.018 two — driving both the card scale and a single `uFocus` uniform that desaturates and dims in the fragment shader. `focus` is itself one of the tweened parameters, so a layout can decide how much of a selection it is.
7. The vertex shader is the default transform and nothing else. Everything that moves is a CPU write to `position`, `rotation` and `scale`, which means the bounding sphere three culls against and the view depth it sorts by both describe where the card actually is. A drum that bends its planes in the vertex shader has to disable culling and reconstruct `renderOrder` by hand; this one gets both for free.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `PRESETS.drum = { radius: 2.55, spacing: 0.74, turns: 2, focus: 1, scale: 1 }`
  Two turns across twelve cards puts adjacent cards 60° apart, so the ring reads as a ring rather than as a coil. Below about 1.5 turns the far side is barely behind the near side and the drum flattens into a wheel; above 3 the cards on the back face are edge-on for most of a lap and the set looks half empty.
- `PRESETS.row.scale = 0.42`
  Matched to the derived row step so twelve cards just touch at the reference aspect. Larger and the row overlaps into a fan; smaller and it becomes a sparse dotted line. It is a scalar for exactly this reason — the row layout gets to pick its own card size.
- `depth = 0.35 (column) / 0.1 (row) / 0 (drum, fan)`
  World units of recession per index step. The drum and fan get their z from the radius, so they need none. The flat layouts need a non-zero value or their transparent cards have identical view depth and the sort order is arbitrary — the symptom is a stack whose overlap flickers as the ring drifts.
- `CARD_HEIGHT_RATIO = 0.4`
  Card height as a fraction of the frustum height at z = 0. Above ~0.55 the drum's vertical spacing has to grow to match or the cards intersect; below ~0.25 the whole formation floats in the middle of the frame with nothing at the edges.
- `CAMERA_FOV / CAMERA_Z = 42 / 7.2`
  A matched pair: they set the visible height, and everything else is a fraction of it. A wider FOV exaggerates the perspective divide so the far side of the drum shrinks dramatically — dramatic, but it also makes the row visibly bow. Change one and the layout is unchanged only if the other keeps `z * tan(fov / 2)` the same.
- `ROW_FILL = 0.92`
  Fraction of the visible width the flat row spans. At 1.0 the outermost cards are cut exactly by the frustum edge and their antialiased rims flicker as they cross it; much below 0.85 the row no longer reads as spanning the frame.
- `SCALE_FLOOR = 0.72`
  The scale an entirely out-of-focus card keeps. At 1.0 the focus falloff is only a dimming and the arrangement loses its centre; below ~0.5 the outer cards shrink so fast the drum looks like it is receding into a tunnel.
- `duration / MORPH_EASE = 1.25 / power3.inOut`
  Long enough to read the shape changing rather than snapping, short enough not to feel like a loading state. `inOut` because the morph has no impulse behind it — an `out` ease implies the shape was thrown, and the sudden start looks like a dropped frame.
- `drift = 0.16`
  Index steps per second of idle travel. About six seconds per card: slow enough to read a caption, fast enough that the wrap is visible within a few seconds of arriving. At 0 the ticker still runs but nothing moves, which is the right default for a layout driven by scroll instead.
- `CARD_CORNER = 0.055`
  Corner radius in units of card height, evaluated as an SDF in the fragment shader. Because the mask is drawn rather than sampled it stays crisp at any scale, and one number gives the same physical radius on both axes since the SDF works in height units and multiplies x by the aspect.

## API

```ts
function LayoutLerpScalar(props: { count?: number; layout?: 'row' | 'column' | 'drum' | 'fan'; params?: Partial<LayoutParams>; duration?: number; drift?: number; hueStart?: number; hueStep?: number; opacity?: number; onFocusChange?: (index: number) => void; className?: string }): JSX.Element
```

- `count: number` — default `12`
  How many cards. They wrap, so this is also the ring's period.
- `layout: 'row' | 'column' | 'drum' | 'fan'` — default `'drum'`
  Which preset the parameter vector is tweened toward.
- `params: Partial<LayoutParams>`
  Overrides individual scalars on top of the preset — radius, spacing, rowSpread, turns, depth, focus, scale. Compared by value.
- `duration: number` — default `1.25`
  Seconds of the morph between presets.
- `drift: number` — default `0.16`
  Index steps per second of idle travel. 0 parks the ring.
- `hueStart: number` — default `232`
  First card's hue, 0-360.
- `hueStep: number` — default `17`
  Degrees of hue between adjacent cards.
- `opacity: number` — default `1`
  Alpha multiplier applied before the focus falloff.
- `onFocusChange: (index: number) => void`
  Fires when a different card takes the focus position.
- `className: string`
  Merged onto the wrapper. The canvas fills it absolutely.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/* ---- the morph: one tween over an object literal ------------------------ */

useEffect(() => {
  const target: LayoutParams = { ...PRESETS[layout], ...params };
  const current = live.current;

  if (reduced) {
    Object.assign(current, target);
    return;
  }

  // Every parameter eases together, so the shape passes through a continuous
  // family of shapes rather than each card taking its own path. `overwrite`
  // matters: switch layout twice quickly and the second tween must take the
  // parameters from wherever the first one had got to, not fight it.
  const tween = gsap.to(current, { ...target, duration, ease: MORPH_EASE, overwrite: true });
  return () => {
    tween.kill();
  };
  // `params` is compared by value through `overrideKey`; the object literal
  // most callers pass is a new reference on every render.
  // eslint-disable-next-line react-hooks/exhaustive-deps
}, [layout, overrideKey, duration, reduced]);

useEffect(() => {
  const current = live.current;
  return () => {
    gsap.killTweensOf(current);
  };
}, []);

/* ---- the frame ---------------------------------------------------------- */

useRaf(
  (dt) => {
    const current = stage.current;
    if (!current) return;
    const n = current.cards.length;
    if (n === 0) return;

    const p = live.current;
    const speed = reduced ? 0 : drift;
    // Wrapped rather than left to grow: at 0.16 steps/s an unwrapped
    // accumulator is fine for days, but the modulo costs nothing and keeps
    // float precision constant no matter how long the tab stays open.
    position.current = mod(position.current + dt * speed, n);
    const pos = position.current;

    // The one place the camera and the layout meet. `visibleHeight` is the
    // frustum's height at z = 0 — `2 * z * tan(fov/2)` — and the width is
    // that times the aspect. Deriving the row step from it is why the row
    // spans the frame at any viewport instead of being a guessed constant.
    const visibleHeight = 2 * Math.tan((CAMERA_FOV * DEG_TO_RAD) / 2) * CAMERA_Z;
    const visibleWidth = visibleHeight * current.camera.aspect;
    const step = (visibleWidth * ROW_FILL) / Math.max(n - 1, 1);
    const cardHeight = visibleHeight * CARD_HEIGHT_RATIO;
    const cardWidth = cardHeight * CARD_ASPECT;

    for (let i = 0; i < n; i++) {
      const card = current.cards[i];
      if (!card) continue;

      // The call that makes a finite array behave like an endless ring:
      // card 0 is one step BEFORE card 11, not eleven steps after it.
      const offset = wrappedOffset(i, pos, n);
      const angle = (offset / n) * TWO_PI * p.turns;

      // The placement function. Seven scalars in, one transform out, and
      // every layout this component has is somewhere in here.
      card.mesh.position.set(
        p.radius * Math.sin(angle) + offset * p.rowSpread * step,
        -offset * p.spacing,
        // cos(angle) - 1 keeps the focused card at z = 0 whatever the
        // radius, so growing the drum pushes the ring back rather than
        // pulling the front card into the camera. The depth term is what
        // gives the flat layouts a strictly monotonic z, which is what lets
        // three sort them back-to-front without any renderOrder fixing.
        p.radius * (Math.cos(angle) - 1) - p.depth * Math.abs(offset),
      );
      card.mesh.rotation.y = angle;

      // exp(-d^2): 1.000 at the focus, 0.368 one step out, 0.018 two,
      // 0.0001 three. Continuous and branchless, and `focus` scales how much
      // of it applies — at 0 every card is lit equally, which is what makes
      // the flat row read as an index rather than as a selection.
      const f = 1 - p.focus * (1 - gaussian(offset));
      const s = p.scale * (SCALE_FLOOR + (1 - SCALE_FLOOR) * f);
      card.mesh.scale.set(cardWidth * s, cardHeight * s, 1);
      card.uniforms.uFocus.value = f;
      card.uniforms.uOpacity.value = opacity;
    }

    const nextFocus = wrapIndex(Math.round(pos), n);
    if (nextFocus !== focusedRef.current) {
      focusedRef.current = nextFocus;
      notify.current?.(nextFocus);
    }

    current.renderer.render(current.scene, current.camera);
  },
  ready && inView && visible,
);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Kills the parameter tween (and any tween of the same object) so GSAP cannot write into a vector nothing reads; removes every mesh from the scene, then `disposeObject` for the materials, `geometry.dispose()`, `prototype.dispose()`, and `disposeRenderer` — which stops the animation loop, disposes, calls `forceContextLoss()` and zeroes the backing store — before removing the canvas from the DOM. The shared rAF unsubscribes, and the shared resize, intersection and visibility observers all unregister. No textures are allocated, so there are none to leak.

**Reduced motion.** The idle drift is set to zero, so the ring holds still and the same card stays in focus. Layout changes still happen — refusing them would leave the component unable to answer its own prop — but the parameters are assigned rather than tweened, so the new arrangement is simply there on the next frame with nothing travelling across the screen. The frame loop keeps running only because it is what draws; with no drift and no tween it writes the same transforms every frame.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Cross-fading two layouts instead of blending their parameters. `lerp(f(a), f(b), s)` moves every card along the straight line between its two homes, so the drum passes through its own axis and the cards slide through one another. Interpolate the inputs and the shape is always a real member of the family.
- Reaching for `if (layout === "drum")` in the frame loop. Branching per layout means each new arrangement is new code and no pair of them can be shown halfway. Every parameter here is a number precisely so it can be tweened, and the presets are data.
- Multiplying a whole layout to zero and calling that a morph. Scaling `radius` to 0 does not produce a flat row — it produces every card stacked on the axis. A second term (`rowSpread * step`) has to take over as the first one leaves, which is why the row and the ring are separate parameters rather than one.
- Letting the transparent cards share a z. three ranks transparent meshes by view depth; with a flat layout at z = 0 the ranking is arbitrary and the overlap in a stack flips as the ring drifts. The `depth` parameter exists to keep the ordering strict.
- Copying the bend-in-the-vertex-shader approach and keeping frustum culling on. That combination blanks planes that are plainly on screen, because the bounding sphere describes the flat geometry at the CPU position. This component avoids the whole class of problem by keeping the layout on the CPU — but the two approaches cannot be mixed carelessly.
- Guessing the row step in world units. Hard-code it and the row overflows a narrow viewport and floats in the middle of a wide one. It has to come from the frustum: `2 * cameraZ * tan(fov / 2) * aspect`, divided across the set.
- Calling `renderer.dispose()` and stopping there. It frees GPU objects but leaves the WebGL context alive, and Chromium kills the oldest context once about sixteen exist — so an unrelated canvas elsewhere on the page goes black. `disposeRenderer` calls `forceContextLoss()`, which is the call that actually hands it back.
- Building the colours with `new THREE.Color(...)` from a hex string and expecting them to match the CSS beside them. Colours have to enter the linear working space (`setHSL(..., THREE.SRGBColorSpace)`) and the fragment shader has to end with `#include <colorspace_fragment>`, because three injects that chunk only into its own materials, never into a `ShaderMaterial`.
- Passing `params` as an inline object literal and putting it straight in the effect deps. It is a new reference every render, so the morph tween is killed and rebuilt on each one and the parameters never arrive. The override is compared by value through a serialised key.
- Rendering every frame regardless. The loop is gated on the element being in view and the tab being visible; a scrolled-past WebGL canvas that keeps drawing is one of the easier ways to halve a page's battery life for nothing.

## Notes

- The four presets are ordinary data — add a fifth by adding seven numbers, with no new code and no new branch. Any two of them can also be blended by hand at a fixed `s` by passing `params`.
- Each card owns a cloned `ShaderMaterial` so it can hold its own colours, but three keys its program cache on the shader source, so all twelve still share one compiled program and the clone costs a uniform bag.
- Nothing is fetched and no image ships: the card face — rounded rectangle, gradient, hairlines, rim — is a signed distance field in the fragment shader, and the shading of a card turning edge-on is one dot product against the transformed normal.

## Definition of done

The cards turn slowly and endlessly — watch one leave the bottom of the drum and come back at the top, at the same spacing. Switch layout: the whole formation unwinds into a row, or collapses into a stack, in one continuous motion, and at every instant it looks like a formation rather than cards travelling to new addresses. Nothing passes through the centre of the drum on the way. Switch layout twice quickly and the second morph starts from wherever the first had reached, with no jump. In the stack, the overlap order is stable while it drifts — nothing flickers in front of its neighbour. Resize the window from narrow to wide: the row still spans the frame and the cards keep their proportions. Scroll the canvas out of view and the GPU goes quiet.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Lenis On The GSAP Ticker

Lenis and ScrollTrigger each work alone and tear together, because each runs its own clock: Lenis advances the scroll position on its rAF, ScrollTrigger samples it on GSAP's, and a pinned section ends up a frame behind the page it is pinned to. Mounted once near the root, this hands Lenis to `gsap.ticker`, updates ScrollTrigger on Lenis's scroll event rather than per frame, and disables lag smoothing so the two agree about how much time passed.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Smooth scroll and ScrollTrigger on one clock, with the lag-smoothing line everyone omits.

- Category: scroll
- Runtime cost: dom
- Dependencies: gsap@^3.15.0, lenis@^1.3.11

## How it works

1. Lenis is driven by `gsap.ticker.add((t) => lenis.raf(t * 1000))` — seconds to milliseconds — and its own `autoRaf` is switched off. One clock advances the scroll position and the tweens, in that order, every frame.
2. `gsap.ticker.lagSmoothing(0)` is the line that makes it correct rather than merely working. GSAP normally clamps a large `deltaTime` after a stall so tweens do not jump; but that clamped value is now what Lenis integrates, so an under-reported frame leaves Lenis's scroll position permanently offset from ScrollTrigger's idea of it. Nothing resyncs them afterwards.
3. ScrollTrigger is updated from `lenis.on("scroll")`, not from the ticker. It then samples on the same tick the position actually changed, instead of one frame after — the difference is visible as a shimmering seam at the top edge of a pin.
4. `paused` calls `lenis.stop()` and `lenis.start()` rather than tearing the instance down. This is the preloader gate: construct on mount so everything is measured and ready, but refuse wheel input until the intro clears — which is why you cannot scroll during a well-built intro sequence.
5. Coming out of `paused`, and again on `load` and on `document.fonts.ready`, `ScrollTrigger.refresh()` re-measures. Images and fonts change document height after hydration, and every trigger below the fold was computed against the old one.
6. The instance itself is refcounted at module scope in `use-lenis`, so mounting the provider twice — a layout and a page, say — reuses one Lenis instead of creating two that both `preventDefault` on wheel and scroll the page at double speed.
7. Under `prefers-reduced-motion` no instance is constructed at all. The page scrolls natively and ScrollTrigger reads the native position, which is the path it is already correct on.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `duration = 1.05`
  Seconds for a wheel step to settle. Roughly the feel of Lenis's `lerp: 0.09`, which is the value most award-site builds land on: slow enough to read as smooth, fast enough that a trackpad flick does not feel like it is dragging the page through syrup. Past ~1.4 the page feels detached from the hand.
- `easing = 1.001 - 2^(-10t)`
  Lenis's own default — an exponential decay that is ~99.9 percent settled at t=1, so the tail never visibly crawls. The `1.001` guarantees it reaches exactly 1 rather than approaching it forever.
- `lagSmoothing = 0`
  Disabled, not tuned. Any non-zero threshold means GSAP will eventually report a deltaTime that did not happen, and Lenis will integrate it into a scroll position that does not match the document.
- `ScrollTrigger.update trigger = lenis scroll event`
  One update per position change, on the tick it changed. Calling it from the ticker instead costs an update on frames where nothing moved and delivers a stale position on frames where it did.

## API

```ts
function LenisGsapTicker(props: { children?: ReactNode; duration?: number; easing?: (t: number) => number; paused?: boolean; enabled?: boolean }): JSX.Element
```

- `children: ReactNode`
  Rendered as-is; the provider adds no DOM of its own.
- `duration: number` — default `1.05`
  Seconds for a wheel step to settle.
- `easing: (t: number) => number`
  Decay curve. Must be a stable reference — define it at module scope.
- `paused: boolean` — default `false`
  Holds input via `lenis.stop()` without destroying the instance. Releasing it also refreshes ScrollTrigger.
- `enabled: boolean` — default `true`
  False restores native scrolling and constructs nothing.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function LenisGsapTicker({
  children,
  duration = 1.05,
  easing = DEFAULT_EASING,
  paused = false,
  enabled = true,
}: LenisGsapTickerProps) {
  const reduced = useReducedMotion();
  // Smooth scrolling is the motion. Under `prefers-reduced-motion` the
  // instance is never built at all, so the page scrolls natively and
  // ScrollTrigger reads the native position — which it already does correctly.
  const active = enabled && !reduced;

  const lenis = useLenis({
    duration,
    easing,
    smoothWheel: true,
    enabled: active,
    // One clock. `useLenis` turns off Lenis's `autoRaf` when a ticker is
    // present and calls `lagSmoothing(0)` on it.
    ticker: gsap.ticker,
    // Sampled on scroll rather than every frame: ScrollTrigger then updates on
    // the same tick the position changed, instead of one frame later.
    onScroll: () => ScrollTrigger.update(),
  });

  useEffect(() => {
    const instance = lenis.current;
    if (!instance) return;
    if (paused) {
      instance.stop();
      return;
    }
    instance.start();
    // Whatever was covering the page while paused was almost certainly holding
    // layout at a different height.
    ScrollTrigger.refresh();
  }, [lenis, paused]);

  useEffect(() => {
    if (!active) return;
    let cancelled = false;
    const refresh = () => {
      if (!cancelled) ScrollTrigger.refresh();
    };

    // Images and fonts change document height after hydration. Without a
    // refresh here, every trigger below the fold is measured against a height
    // that no longer exists, and they all fire early by the difference.
    if (document.readyState === 'complete') refresh();
    else window.addEventListener('load', refresh, { once: true });
    void document.fonts?.ready.then(refresh);

    return () => {
      cancelled = true;
      window.removeEventListener('load', refresh);
    };
  }, [active]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `use-lenis` removes its scroll listener, removes the update function from `gsap.ticker`, and destroys the instance only when the last consumer unmounts. The provider removes its own `load` listener and guards the `document.fonts.ready` continuation with a cancelled flag, so a refresh cannot land after unmount.

**Reduced motion.** No Lenis instance is constructed when `prefers-reduced-motion: reduce` matches, so scrolling is entirely native and the ticker is left alone. ScrollTrigger keeps working against the native position. The query is live: toggling the OS setting takes effect on the next render without a reload.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Leaving lag smoothing at its default. Everything looks right until the first stall — a heavy image decode, a devtools pause — after which pinned sections sit permanently a few pixels off and no interaction resyncs them.
- Letting Lenis keep `autoRaf` while also adding it to the ticker. It then advances twice per frame: scrolling runs at double speed and the smoothing constant no longer means anything.
- Mounting the provider in two places. Two instances both listen on `wheel`, both call `preventDefault`, and the page moves twice as far as the gesture — the refcount in `use-lenis` exists specifically to make the second mount a no-op.
- Calling `ScrollTrigger.update` from the ticker instead of from the scroll event. Triggers lag the smoothed position by exactly one frame, which is most visible as a seam that shivers at the top of a pinned section.
- Skipping `ScrollTrigger.refresh()` after `load` and after fonts settle. Every trigger below the fold is measured against a document height that no longer exists, so they all fire early by the difference.
- Passing an inline arrow as `easing`. It is a new identity every render, so the effect that owns the instance tears Lenis down and rebuilds it on each one — visible as scroll position snapping to the top mid-gesture.
- Smooth-scrolling a subtree by mounting a second window-level Lenis. Lenis attaches to the window unless given an explicit wrapper; a nested instance fights the outer one for the same wheel events.

## Notes

- The preview does not mount an enabled instance. `useLenis` attaches to the window, and a window-level smooth scroll inside a documentation page would take over the page hosting the preview rather than the preview. The demo therefore shows the provider mounted with `enabled={false}` beside a local reproduction: the right-hand column is offset by the same exponential filter Lenis applies, the left is the raw native position, and the bar at the bottom is the instantaneous gap between them. The ticker wiring itself is exactly as shipped.
- The demo derives its filter constant with `perFrameToSmoothing(0.09)` from `lib/damp`, which converts Lenis's per-frame `lerp` into the per-second constant `damp` wants. That conversion is the same one that makes any ported per-frame easing frame-rate independent.
- Mount above everything that registers a ScrollTrigger. Triggers created before the ticker wiring exists still work, but they are measured against a document that has not yet been refreshed.
- Smooth scroll is a preference, not an improvement. Ship the `enabled` escape hatch and honour reduced motion — a real fraction of users find hijacked scrolling nauseating.

## Definition of done

Scrolling is smoothed and a pinned section stays welded to the page with no shivering seam at its top edge. Pause during a stall — hold a devtools breakpoint for a second — and on release the pin is still aligned. Mounting the provider twice does not double scroll speed. With reduced motion on, scrolling is native and ScrollTrigger still fires at the right positions.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Looping Scroll Cue

A short line that falls repeatedly through a clipping tube, the way a hero says "keep going" without saying it. It is pure CSS — one keyframe pair on one transform — so it costs nothing after mount and a dozen of them still emit a single rule. The character is entirely in the easing: the line hangs, dives, and hangs again, and the pause between dives is what reads as an instruction.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

The hairline that dives down a hero. One keyframe pair, a hard ease, and a seamless loop.

- Category: primitive
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. A `span` is the tube: `position: relative`, `overflow: hidden`, `block-size: var(--kx-cue-length)`, `inline-size: var(--kx-cue-thickness)`. Everything visible happens inside its clip.
2. A child span is the line: absolutely positioned at `top: 0`, `block-size: var(--kx-cue-run)` — 40% of the tube — with `background-color: currentColor`, so the cue takes the colour of whatever text it sits beside.
3. One keyframe pair moves it from `translateY(-100%)` to `translateY(250%)`. Percentages on `translateY` resolve against the element's own height, not the tube's, so with the line at 40% the two ends are exactly flush with the outside of the clip: 40% x 1 above the top, 40% x 2.5 = 100% below it.
4. The line's resting transform is set to `translateY(-100%)`, identical to the keyframe start, so the element is already outside the clip before the animation attaches and there is no first-frame flash.
5. The timing function is `cubic-bezier(.76, 0, .24, 1)`, applied over the whole iteration rather than per keyframe — a hard ease-in-out that spends most of the cycle nearly stationary at the two extremes, both of which are off-screen.
6. The stylesheet is a module-level template literal emitted through React 19's `<style href precedence>`, so it is hoisted to the document head once no matter how many cues render.
7. Reduced motion is answered twice: a `@media (prefers-reduced-motion: reduce)` block so the server-rendered first paint is already correct, and `data-static` from `useReducedMotion` so a setting changed mid-session takes effect. Both resolve to `animation: none; top: 50%; transform: translateY(-50%)`.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `travel = -100% to 250%`
  Relative to the line, not the tube. 350% of its own height means it is entirely outside the clip at both ends, so the wrap from the last frame back to the first happens while nothing is visible. Animating 0% to 100% instead makes the line vanish at the bottom edge and reappear at the top in the same frame, which is the visible seam every hand-rolled version has.
- `--kx-cue-run = 40%`
  The line's height as a fraction of the tube, and the number that makes 250% exactly the far edge. At 100% the line fills the tube and the cue reads as a wipe rather than a falling object; below about 20% it is too short to register as travelling at this speed.
- `timing function = cubic-bezier(.76, 0, .24, 1)`
  A hard ease-in-out with almost no linear section. `linear` reads as a loading bar and `ease-in-out` is too soft to punctuate. The steep middle is what compresses the visible part of the cycle into a dive, leaving a deliberate pause between repetitions.
- `--kx-cue-period = 1.8s`
  One dive plus the pause. Under about 1.2s the cue nags; past roughly 2.5s a visitor can land, look, and leave without ever seeing it move, which defeats the point of having it.
- `--kx-cue-length = 3.5rem`
  Long enough that the dive is legible as travel rather than as a blink, short enough to sit under a line of body copy without becoming a design element in its own right.

## API

```ts
function LoopingScrollCue(props: { length?: string; thickness?: string; run?: string; period?: number; delay?: number; paused?: boolean; className?: string }): JSX.Element
```

- `length: string` — default `'3.5rem'`
  Height of the tube. Any CSS length.
- `thickness: string` — default `'1px'`
  Width of the line.
- `run: string` — default `'40%'`
  Height of the travelling segment as a percentage of the tube.
- `period: number` — default `1.8`
  Seconds for one dive plus its pause.
- `delay: number` — default `0`
  Seconds before the first dive. Use it to stagger a row.
- `paused: boolean` — default `false`
  Park the line in the middle of the tube instead of running it.
- `className: string`
  Merged onto the tube. Set `text-*` to colour the line.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const CUE_CSS = `
@keyframes kx-scroll-cue-travel {
  from { transform: translateY(-100%); }
  to   { transform: translateY(250%); }
}
.kx-scroll-cue {
  position: relative;
  display: block;
  overflow: hidden;
  flex: none;
  inline-size: var(--kx-cue-thickness, 1px);
  block-size: var(--kx-cue-length, 3.5rem);
  color: currentColor;
}
.kx-scroll-cue-line {
  position: absolute;
  inset-inline: 0;
  top: 0;
  block-size: var(--kx-cue-run, 40%);
  background-color: currentColor;
  /* Matches the keyframe start, so the line is already outside the clip
     before the first frame and never flashes at rest. */
  transform: translateY(-100%);
  animation: var(--kx-cue-period, 1.8s) cubic-bezier(.76, 0, .24, 1) infinite
    kx-scroll-cue-travel;
  animation-delay: var(--kx-cue-delay, 0s);
}
/* Parked, not frozen. 'animation-play-state: paused' stops on whatever frame
   it reached, and for roughly half the cycle that frame is off-screen — the
   cue would simply vanish. */
.kx-scroll-cue[data-static='true'] .kx-scroll-cue-line {
  animation: none;
  top: 50%;
  transform: translateY(-50%);
}
@media (prefers-reduced-motion: reduce) {
  .kx-scroll-cue .kx-scroll-cue-line {
    animation: none;
    top: 50%;
    transform: translateY(-50%);
  }
}
`;

export interface LoopingScrollCueProps {
  /** Height of the tube. Any CSS length. */
  length?: string;
  /** Width of the line. Any CSS length. */
  thickness?: string;
  /** Height of the travelling segment, as a percentage of the tube. */
  run?: string;
  /** Seconds for one full dive. */
  period?: number;
  /** Seconds before the first dive. Stagger a row of cues with this. */
  delay?: number;
  /** Park the line in the middle instead of running it. */
  paused?: boolean;
  className?: string;
}

export function LoopingScrollCue({
  length = '3.5rem',
  thickness = '1px',
  run = '40%',
  period = 1.8,
  delay = 0,
  paused = false,
  className,
}: LoopingScrollCueProps) {
  const reduced = useReducedMotion();

  return (
    <>
      {/* Hoisted once by React 19 regardless of how many cues are on the page. */}
      <style href="kinetic-looping-scroll-cue" precedence="medium">
        {CUE_CSS}
      </style>
      <span
        aria-hidden
        data-static={reduced || paused ? 'true' : 'false'}
        className={cn('kx-scroll-cue', className)}
        style={
          {
            '--kx-cue-length': length,
            '--kx-cue-thickness': thickness,
            '--kx-cue-run': run,
            '--kx-cue-period': `${period}s`,
            '--kx-cue-delay': `${delay}s`,
          } as CSSProperties
        }
      >
        <span className="kx-scroll-cue-line" />
      </span>
    </>
  );
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nothing to release. No timers, no rAF, no listeners, no observers — the only side effect is the hoisted stylesheet, which React reference-counts and removes when the last cue unmounts.

**Reduced motion.** The line stops travelling and parks in the middle of the tube — visible, centred, still a cue. This is enforced both by a `@media (prefers-reduced-motion: reduce)` block in the hoisted stylesheet, which is correct from the first server-rendered paint, and by `data-static` driven from `useReducedMotion`, which catches the setting being changed while the page is open.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Animating `top` or `margin-top` instead of `transform`. Both are laid out on the main thread every frame; the transform runs on the compositor and is the difference between a cue that stays smooth during a heavy hero animation and one that stutters exactly when the page is busiest.
- Animating 0% to 100%. The line disappears at the bottom edge and is already back at the top on the next frame — the loop has a visible seam, and it is the single most common way this effect is got wrong.
- Assuming the percentages are relative to the tube. `translateY` percentages resolve against the transformed element, so changing the line's height silently changes where the travel ends, and a taller line stops exiting the clip.
- Using `animation-play-state: paused` for a paused state. The line stops on whatever frame it reached, and for roughly half the cycle that frame is outside the clip, so "paused" means "gone" about half the time it is used.
- Honouring reduced motion by rendering the animation's end state. The end state here is off-screen, so the cue would correctly render nothing. Park it in the middle instead: the point of a scroll cue is that it is visible.
- Relying on the `useReducedMotion` hook alone. It reads `false` during server render, so the first client paint animates for a frame before the hook corrects it — the media query in the stylesheet is what covers that window.
- Leaving the line's resting transform at its default. Without `transform: translateY(-100%)` matching the keyframe start, the line is briefly visible at the top of the tube between paint and the animation's first frame.

## Notes

- Cost is CSS. Nothing runs after mount, there is nothing to clean up, and a row of cues is one rule plus one custom-property block each.
- Stagger a row with `delay` — the same period at three different offsets reads as a single wave without any coordination.
- The cue is `aria-hidden`. It is a hint, not content, and a screen reader announcing a decorative line is noise.

## Definition of done

The line falls through the tube, disappears, and pauses before falling again — and at no point is it visible in two places or seen jumping back to the top. Watch a full minute: the loop point cannot be identified. Turn on reduced motion and the line is a static hairline in the centre of the tube, not an empty box.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Lottie Ratio Poster

A slot for a Lottie that costs nothing until the slot is nearly on screen. The box is reserved at a provisional ratio and filled with a poster drawn in CSS; an IntersectionObserver on the already-sized box starts the fetch; the resolved JSON reports its own composition size in its `w` and `h` fields, the box takes that exact ratio, the player mounts underneath and the poster crossfades away. The readout prices the provisional guess in pixels of layout shift. No Lottie runtime is imported — loading and playback go through a render prop, so the packaged part is the reservation, not the player.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Reserves the box, holds a drawn poster, fetches the JSON only in view, then corrects the ratio from the animation's own w and h.

- Category: primitive
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. The reserved box is a single `aspect-ratio` declaration on a full-width element, applied on first paint from the provisional ratio. That is what makes everything after it possible: a box with height cannot shift when it fills, and a box with height gives the IntersectionObserver something real to test.
2. The intersection test runs on that reserved box, with `once: true` and a 240px root margin, so the fetch starts roughly one flick of the wrist before the box arrives. Observing an unreserved, zero-height element instead is the classic failure — a collapsed box intersects the viewport from almost anywhere on the page, so the lazy load fires immediately and the laziness was decorative.
3. A Lottie JSON carries its composition size at the root: `w` and `h`, alongside `v`, `fr`, `ip`, `op` and `layers`. `w / h` is therefore the exact box before the player has been constructed, let alone measured, so the correction happens on the frame the file lands rather than after a layout pass.
4. The provisional ratio and the real ratio are both kept, and the difference is reported as `Math.abs(width / ratio - width / actual)` — the number of pixels everything below the box moved, at the current width. It is the same quantity that feeds Cumulative Layout Shift, in the units the user actually experienced.
5. The in-flight promise is stored in a ref rather than guarded by a boolean. StrictMode double-invokes the Effect: with a `started` flag the first call is abandoned by its own cleanup and the second is blocked by the flag, so the load silently never completes. Reusing the promise means one request and one subscription per Effect run.
6. The poster is dissolved two animation frames after `ready`, not on the same tick — one frame for React to commit the player and one for the browser to paint it. It is then unmounted on a timer rather than on `transitionend`, because a transition on a subtree that has been hidden never fires the event and the poster would sit over the player permanently.
7. A zero or missing dimension is treated as a failed load rather than divided by. `w / 0` is Infinity, which collapses `aspect-ratio` and takes the reserved box with it — the exact failure the component exists to prevent, arriving through the component itself.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `DEFAULT_RATIO = 16 / 9`
  The provisional ratio, and named as a guess rather than a default so nobody inherits it by accident. Take the real number out of the design file: against the 3:2 composition in the demo, 16:9 costs 47 pixels of shift at 380px wide.
- `ROOT_MARGIN = '240px'`
  About a third of a laptop viewport, or roughly 400ms of ordinary scrolling — enough for a one-megabyte JSON on a decent connection to land before the box arrives. Larger and you are prefetching things the user will never reach; smaller and the poster is still up when the box is centred.
- `FADE_MS = 320`
  Poster crossfade. Long enough to read as a dissolve rather than a cut, short enough that the poster is not still visibly over the first second of the animation.
- `FADE_SLACK = 60`
  Extra milliseconds before the poster is unmounted. The transition is driven by a class change, so the removal timer and the transition clock do not share an origin; without the slack the poster can be pulled at opacity 0.04.

## API

```ts
function LottieRatioPoster<T extends LottieRatioSource>(props: { load: () => Promise<T>; children: (state: { source: T; reduced: boolean }) => ReactNode; ratio?: number; rootMargin?: string; fade?: number; label?: string; className?: string }): JSX.Element
```

- `load: () => Promise<T>`
  Fetches the animation JSON. Called at most once, and only once the reserved box is within `rootMargin`.
- `children: (state: { source: T; reduced: boolean }) => ReactNode`
  Render prop for the player. Mounted absolutely inside the reserved box.
- `ratio: number` — default `16 / 9`
  Provisional width / height, used until the JSON reports its own.
- `rootMargin: string` — default `'240px'`
  How early to start fetching, as an IntersectionObserver root margin.
- `fade: number` — default `320`
  Poster crossfade in milliseconds.
- `label: string` — default `'animation'`
  Short text on the poster.
- `className: string`
  Merged onto the outer element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
useEffect(() => {
  if (!inView) return;
  let alive = true;

  request.current ??= loadRef.current();
  setPhase((prev) => (prev === 'waiting' ? 'loading' : prev));

  request.current.then(
    (data) => {
      if (alive) apply(data);
    },
    () => {
      if (alive) setPhase('failed');
    },
  );

  return () => {
    alive = false;
  };
}, [inView, apply]);

// The real ratio comes from the JSON's own composition size, so the box is
// exact from the frame the file lands rather than from the frame the player
// finishes measuring itself.
const actual = source ? source.w / source.h : null;
const applied = actual ?? ratio;

// What the guess cost, in the units the user experiences it in. Everything
// below this box moves by exactly this many pixels at the current width.
const shift =
  actual !== null && width > 0 ? Math.abs(width / ratio - width / actual) : 0;
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The intersection subscription is removed by `useInView`, which also unobserves after the first hit because it is used with `once`. Both timers are cleared and both `requestAnimationFrame` handles cancelled on teardown. The load promise cannot be aborted, so it is neutered instead: an `alive` flag in the Effect closure means a late resolution calls no setter after teardown. The promise itself is deliberately retained in a ref across Effect runs, which is what makes the request happen once rather than once per run.

**Reduced motion.** The poster loses its shimmer and the crossfade collapses to a zero-duration swap, so the poster is replaced rather than dissolved. The fetch is unaffected — reduced motion is a request about movement, not about content, and withholding the animation entirely would leave a permanent placeholder where the user expected something. The render prop is handed `reduced: true` so the player itself can park on its last frame, which is the conventional still for a Lottie.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Lazy-loading against an unreserved box. A zero-height element intersects the viewport from nearly anywhere in the document, so the observer fires on mount and the fetch was never deferred. Reserve first, observe second — in that order, in the same element.
- Waiting for the player to report the size. `lottie-web` measures its own SVG after construction, which is after the layout has already happened at the wrong ratio. The JSON's `w` and `h` are available the instant the fetch resolves, before anything is instantiated.
- Guarding a one-shot fetch with a boolean ref. StrictMode runs the Effect, tears it down and runs it again; the first call is discarded by its own cleanup and the second is refused by the flag, so the promise never lands and the poster stays up in development only. Hold the promise itself in the ref.
- Dissolving the poster in the same commit that mounts the player. The player has not painted, so the crossfade runs over an empty box and reads as a flash. Two `requestAnimationFrame` calls put it after the paint.
- Unmounting the poster on `transitionend`. If the subtree is hidden mid-transition — a route change, a tab switch, an `Activity` boundary — no event is delivered and the poster is stranded on top of the player. Use a timer.
- Dividing by a dimension you did not check. A malformed or truncated JSON with `h: 0` produces an Infinite ratio, `aspect-ratio` gives up, and the reserved box collapses to nothing.
- Shipping the Lottie runtime for a decoration. `lottie-web` is around 60KB gzipped before any animation data; if the thing being animated is one badge in a footer, the runtime costs more than the effect is worth, and this component is where you notice.

## Notes

- No Lottie runtime is imported and no `.json` is committed. `load` is any function returning the parsed animation, and `children` is where the player goes, so the same slot works for `lottie-web`, `@lottiefiles/dotlottie-web`, a video, or a canvas.
- Type the resolved JSON yourself and pass it as the generic: `LottieRatioPoster<MyLottie>` gives the render prop the full object rather than only `w` and `h`.
- For reduced motion the render prop receives `reduced: true`. The conventional response with `lottie-web` is to construct it with `autoplay: false` and call `anim.goToAndStop(anim.getDuration(true) - 1, true)` — `getDuration(true)` returns frames, so the last frame is one less than that.

## Definition of done

On load the box already occupies its full reserved height, with a poster in it and a readout reading `reserved 1.78 · waiting for viewport`. Scroll it into view and the readout goes to `fetching json` roughly a scroll-flick before the box arrives. When the JSON lands the box snaps to 1.50, the player fades up under the dissolving poster, and the readout names the shift in pixels. Set the provisional ratio to 1.5 and reload: same sequence, and the readout says `no shift`. With reduced motion the poster does not shimmer and the swap is instant.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Magnetic Pointer Button

The element translates toward the pointer by a fraction of its offset from centre, and the label translates further still, so the text appears to lead the box it sits in. Release is an elastic overshoot rather than a linear return, which is the difference between "springy" and "sliding back".

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A button that leans toward the cursor and springs back, with the label leading the box.

- Category: cursor
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. A window-level pointermove handler measures the pointer against the button's live bounding rect, not a cached one — the element is being translated by this same effect, so a rect captured on mount goes stale immediately.
2. Inside a hit area padded past the border, the offset from centre is scaled by `strength` and pushed into four `gsap.quickTo` setters: x and y for the button, x and y for the label at `labelStrength - 1` so it moves relative to its already-moving parent.
3. Outside that area, a single `gsap.to` with `elastic.out(1, 0.4)` and `overwrite: "auto"` returns both nodes to zero, cancelling any in-flight follow tween.
4. Cleanup kills tweens before clearing transforms, so nothing writes to the node after React releases it.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `strength = 0.35`
  Fraction of pointer offset the button travels. Below ~0.2 the effect is invisible; above ~0.6 the button outruns the cursor and reads as a rendering fault rather than an affordance.
- `labelStrength = 1.6`
  The label moves 0.6x the button offset *on top of* the button's own movement. That parallax between text and border is what makes the surface feel elastic instead of rigid.
- `padding = 24`
  Pixels of grace beyond the border. Without it the effect engages exactly at the edge, and the button visibly jumps as it snaps into the field.
- `FOLLOW_DURATION = 0.35`
  quickTo duration. Short enough to feel attached to the cursor, long enough to smooth the 8-16 ms gaps between pointer events.
- `RETURN_DURATION = 0.6`
  Elastic return. Shorter than this and the overshoot has no room to read as a spring.

## API

```ts
function MagneticButton(props: { children: ReactNode; strength?: number; labelStrength?: number; padding?: number; className?: string; onClick?: () => void; disabled?: boolean }): JSX.Element
```

- `children: ReactNode`
  Button label. Wrapped in the span that receives the parallax offset.
- `strength: number` — default `0.35`
  Fraction of the pointer offset the button travels.
- `labelStrength: number` — default `1.6`
  Label travel relative to the button. 1 disables parallax.
- `padding: number` — default `24`
  Pixels beyond the border that still count as near.
- `className: string`
  Merged onto the button element via `cn`.
- `onClick: () => void`
  Standard click handler.
- `disabled: boolean` — default `false`
  Disables the button and skips the effect entirely.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const RETURN_DURATION = 0.6;
const FOLLOW_DURATION = 0.35;

export function MagneticButton({
  children,
  strength = 0.35,
  labelStrength = 1.6,
  padding = 24,
  className,
  onClick,
  disabled = false,
}: MagneticButtonProps) {
  const root = useRef<HTMLButtonElement>(null);
  const label = useRef<HTMLSpanElement>(null);

  useEffect(() => {
    const el = root.current;
    const text = label.current;
    if (!el || !text || disabled) return;

    // A coarse pointer has no hover state: the effect would only ever fire on
    // touch-down, which reads as a glitch rather than an affordance.
    const fine = window.matchMedia('(pointer: fine)');
    const reduced = window.matchMedia('(prefers-reduced-motion: reduce)');
    if (!fine.matches || reduced.matches) return;

    // quickTo builds one reusable tween per property. The naive version calls
    // gsap.to() on every pointermove, which allocates a tween per event (~120
    // a second) and makes each one fight the last for the same property.
    const xTo = gsap.quickTo(el, 'x', { duration: FOLLOW_DURATION, ease: 'power3.out' });
    const yTo = gsap.quickTo(el, 'y', { duration: FOLLOW_DURATION, ease: 'power3.out' });
    const labelXTo = gsap.quickTo(text, 'x', { duration: FOLLOW_DURATION, ease: 'power3.out' });
    const labelYTo = gsap.quickTo(text, 'y', { duration: FOLLOW_DURATION, ease: 'power3.out' });

    const onMove = (e: PointerEvent) => {
      // Read the rect per move, not once on mount: the element is being
      // translated by this very effect, and any scroll or reflow invalidates
      // a cached rect. Stale centres make the button drift away permanently.
      const rect = el.getBoundingClientRect();
      const cx = rect.left + rect.width / 2;
      const cy = rect.top + rect.height / 2;

      const withinX = Math.abs(e.clientX - cx) < rect.width / 2 + padding;
      const withinY = Math.abs(e.clientY - cy) < rect.height / 2 + padding;

      if (withinX && withinY) {
        const dx = (e.clientX - cx) * strength;
        const dy = (e.clientY - cy) * strength;
        xTo(dx);
        yTo(dy);
        labelXTo(dx * (labelStrength - 1));
        labelYTo(dy * (labelStrength - 1));
        return;
      }

      // Release. Overshoot on the way home is what sells the elastic.
      gsap.to([el, text], {
        x: 0,
        y: 0,
        duration: RETURN_DURATION,
        ease: 'elastic.out(1, 0.4)',
        overwrite: 'auto',
      });
    };

    // Listen on the window, not the element. On the element, `pointerleave`
    // fires the moment the button moves out from under the cursor — it
    // chases itself away and stutters at the edge of the hit area.
    window.addEventListener('pointermove', onMove, { passive: true });

    return () => {
      window.removeEventListener('pointermove', onMove);
      // Kill before clearing: an in-flight tween would otherwise write a
      // transform back onto a node React has already handed to something else.
      gsap.killTweensOf([el, text]);
      gsap.set([el, text], { clearProps: 'transform' });
    };
  }, [strength, labelStrength, padding, disabled]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the window listener, calls `gsap.killTweensOf` on both nodes, then clears the transform with `gsap.set(..., { clearProps: "transform" })`. Kill precedes clear so no in-flight tween can restore it.

**Reduced motion.** The effect never attaches when `prefers-reduced-motion: reduce` matches. The button keeps its colour transition on hover, so it still responds — it just does not move.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Listening on the element instead of the window. `pointerleave` fires the instant the button translates out from under the cursor, so it chases itself away and stutters along the edge of its own hit area.
- Calling `gsap.to()` per pointermove. That allocates a fresh tween ~120 times a second and each one fights the previous for the same property. `quickTo` reuses one tween per property.
- Caching the bounding rect on mount. The element moves and the page scrolls; a stale centre makes the button drift further away with every pass.
- Skipping `overwrite: "auto"` on the return tween — the follow tween keeps running underneath and the button never actually reaches zero.
- Leaving the transform behind on unmount. Clear it, but kill tweens first, or an in-flight tween writes it straight back.

## Notes

- Gated behind `(pointer: fine)`. On touch there is no hover, so the effect would only fire on press, which reads as a glitch.

## Definition of done

Approach from any side and the button leans toward the cursor with the label leading it. Leave the padded area and it springs back past zero once before settling. Unmount mid-approach and no transform remains on the node. On a touch device it does not move at all.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Manufactured Scroll Range

Some content has no height. A ring of projects, a canvas scene, a stack of captions — one screen of markup that wants to be a page of interaction. The fix is to manufacture the range: a container sized `count x viewports` screens with a sticky viewport inside it, and `scrolled / scrollable` as the single input. One screen of scroll then means exactly one item, with no per-item measurement to keep in sync.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

An empty box N screens tall turns a one-screen scene into a scrollable sequence, with progress as a CSS variable and the index as state.

- Category: scroll
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. The container height is written in the scroller's own pixels — `hostHeight * (1 + count * viewports)` — and the sticky child is written at exactly `hostHeight`, so the difference between them is the scroll range and nothing else. Pixels rather than `vh` because inside a scrollable box, viewport units measure a different element entirely.
2. Progress is `(hostTop - containerTop) / (total - hostHeight)`, read from live rects on the frame it is used. Nothing is cached, so a font swap, an image landing above, or a resize corrects itself on the next frame with no invalidation step.
3. The two outputs are separated by cost. Continuous progress goes out as `--range-progress` and `--range-position` custom properties and to an optional `onFrame` callback — sixty times a second, never through React. The discrete index goes through `useState`, and only on the frame it changes.
4. Progress is quantised to four decimals before writing. Below that nothing downstream can render differently, so a stationary scroller performs zero style writes rather than 60 per second.
5. The index uses `floor`, not `round`, so item `i` owns `[i/count, (i+1)/count)` — equal slots, and the last item owns the end of the range instead of a half-slot.
6. A hysteresis band of 0.04 of a slot guards the index commit. A trackpad resting exactly on a boundary otherwise flips the index every frame, and each flip is a full React re-render of the viewport contents.
7. The render prop receives `{ index, count }`, so the child tree re-renders on item change only — the per-frame value is available to the same tree as an inherited custom property.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `viewports = 1`
  Screens of scroll per item. One is the value that makes the range legible: a full flick moves exactly one item, which is the mapping users infer within two gestures. Below ~0.6 items blur past; above ~2 the sequence feels padded.
- `HYSTERESIS = 0.04`
  Fraction of a slot the position must travel past a boundary before the index commits. Sized above trackpad jitter and sub-pixel rect noise, and far below anything a user could intend as a move.
- `progress quantisation = 4 decimal places`
  One ten-thousandth of the range is below the resolution of any downstream transform or colour mix, so comparing the formatted string lets an idle scroller skip the DOM write entirely.
- `range height = hostHeight * (1 + count * viewports)`
  The extra `1` is the sticky viewport's own screen. Without it the last item is only reachable at the exact bottom of the scroller and can never be centred.

## API

```ts
function ManufacturedScrollRange(props: { count: number; viewports?: number; children: (state: { index: number; count: number }) => ReactNode; onFrame?: (state: { progress: number; position: number; index: number }) => void; scroller?: RefObject<HTMLElement | null>; className?: string }): JSX.Element
```

- `count: number`
  How many items the manufactured range represents.
- `viewports: number` — default `1`
  Screens of scroll per item.
- `children: (state: { index: number; count: number }) => ReactNode`
  Rendered inside the sticky viewport; called again only when the index changes.
- `onFrame: (state: ScrollRangeState) => void`
  Per-frame progress, for work that must not go through React.
- `scroller: RefObject<HTMLElement | null>`
  Scroll container. Omit to auto-detect the nearest scrollable ancestor.
- `className: string`
  Merged onto the outer container.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function ManufacturedScrollRange({
  count,
  viewports = 1,
  children,
  onFrame,
  scroller,
  className,
}: ManufacturedScrollRangeProps) {
  const root = useRef<HTMLDivElement>(null);
  const viewport = useRef<HTMLDivElement>(null);

  const [index, setIndex] = useState(0);
  const indexRef = useRef(0);
  const lastHeight = useRef(0);
  const lastProgress = useRef('');

  useRaf((_dt) => {
    const rootEl = root.current;
    const viewportEl = viewport.current;
    if (!rootEl || !viewportEl || count <= 0) return;

    const host = scroller?.current ?? nearestScroller(rootEl);
    const hostIsRoot = host === document.documentElement;
    const hostTop = hostIsRoot ? 0 : host.getBoundingClientRect().top;
    const hostHeight = hostIsRoot ? window.innerHeight : host.clientHeight;
    if (hostHeight === 0) return;

    // The range is measured in the scroller's own pixels, not `vh`. Inside a
    // scrollable box, viewport units describe a completely different element.
    const total = Math.round(hostHeight * (1 + count * viewports));
    if (total !== lastHeight.current) {
      lastHeight.current = total;
      rootEl.style.height = `${total}px`;
      viewportEl.style.height = `${hostHeight}px`;
    }

    const travel = total - hostHeight;
    const progress = travel > 0 ? clamp((hostTop - rootEl.getBoundingClientRect().top) / travel, 0, 1) : 0;
    const position = progress * count;

    // Continuous value: out as a custom property, never as state. Quantised
    // so an idle scroller stops writing to the DOM entirely.
    const text = progress.toFixed(4);
    if (text !== lastProgress.current) {
      lastProgress.current = text;
      rootEl.style.setProperty('--range-progress', text);
      rootEl.style.setProperty('--range-position', position.toFixed(3));
    }

    // Discrete value: equal slots, `floor` not `round`, so item i owns
    // [i/count, (i+1)/count) and the last item owns the end of the range.
    const candidate = clamp(Math.floor(position), 0, count - 1);
    if (candidate !== indexRef.current) {
      // Distance past the boundary being crossed — going forward that is the
      // candidate's own edge, going back it is the current item's edge.
      const boundary = candidate > indexRef.current ? candidate : indexRef.current;
      if (Math.abs(position - boundary) > HYSTERESIS) {
        indexRef.current = candidate;
        setIndex(candidate);
      }
    }

    onFrame?.({ progress, position, index: indexRef.current });
  });
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useRaf` unsubscribes from the shared loop on unmount and no other listener, observer or timer is registered. The inline height and the custom properties are written on nodes React owns and disappear with them.

**Reduced motion.** The range is layout, not animation: it is how the sequence is navigated, so collapsing it would remove access to the content rather than remove motion. The component itself animates nothing — it publishes numbers. Consumers should read the discrete `index` under reduced motion and drive cuts, not `--range-progress` and continuous parallax.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Sizing the spacer in `vh` while the component lives inside a scrollable box. The height comes from the window and the progress comes from the box, so the sequence finishes early or never finishes — and it looks correct only when the box happens to be full-height.
- Pushing continuous progress through `setState`. That is a React render per frame for a value that only ever feeds a transform; the tree re-reconciles 60 times a second to move one bar.
- Committing the index with no hysteresis. Resting on a boundary makes the index oscillate, which reads as flicker and, if items fetch anything, as a request storm.
- Using `round` for the index. Items 0 and count-1 get half-width slots, so the first and last feel twice as fast as the middle for no reason the user can see.
- Putting the spacer as a sibling *before* the sticky element. Sticky positioning is bounded by the parent, so the viewport unsticks as soon as the spacer scrolls past and the sequence stops halfway.
- Deriving progress from `scroller.scrollTop / scrollHeight`. That is the whole document's progress, not the section's, so the mapping breaks the moment anything is added above or below.
- Forgetting `overflow: hidden` on the sticky viewport. Content sized to the viewport bleeds over neighbouring sections during the range and paints outside its own box.

## Notes

- The scroll container is auto-detected by walking ancestors for a scrollable `overflow-y`, so the component works unchanged on a normal page; pass `scroller` when the container is created later or ambiguous.
- Custom properties inherit, so anything inside the render prop can read `--range-progress` without prop drilling and without a re-render.
- For a ring rather than a list, replace the `clamp` on the index with `((i % count) + count) % count` and let the position wrap.

## Definition of done

One screen of scroll advances exactly one item. Resting the pointer on a slot boundary does not flip the index back and forth. The progress bar moves continuously while the item title changes in steps. Resizing the scroller keeps the current item on screen. React DevTools shows a render only when the item changes, not per frame.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: matchMedia Layout Teardown

A fanned card layout on desktop and a plain column on mobile, with the entire desktop branch registered inside `gsap.matchMedia()`. GSAP records every `set`, tween and returned cleanup made inside the callback and reverts them the moment the query stops matching, so crossing the breakpoint leaves no inline transforms, no live listeners and no half-applied layout behind.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Two layouts behind one gsap.matchMedia block. Cross the breakpoint and the desktop branch reverts itself.

- Category: layout
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. `gsap.matchMedia().add({ isDesktop, isMobile, reduced }, self => …)` uses the object form: several queries are evaluated at once and arrive as booleans on `self.conditions`, so one callback branches on width and on motion preference together instead of needing an `add` per combination. GSAP re-runs the callback when any of the queries flips, which means toggling the OS "reduce motion" setting reconfigures the layout live, without a reload.
2. The desktop branch positions the cards entirely through `gsap.set` — `position: absolute`, `left`, `top`, `rotation`, `zIndex` — rather than through breakpoint utility classes. That is deliberate: the breakpoint then exists in exactly one place, the query string, and the base markup can stay a plain flex column that doubles as the mobile layout.
3. Positions are percentages of the container (`left: 50 + offset * spread`%, `top: 50 + |offset| * arc`%) with `xPercent: -50, yPercent: -50` for centring. Because percentages resolve against the container box, the fan rescales on resize with no measuring pass, no `ResizeObserver` and no resize listener inside the branch.
4. Layout and interaction are kept on separate transform channels. `left`/`top` carry the fan, the entrance tween owns `y` and `autoAlpha`, and the pointer parallax writes only `x` via `gsap.quickTo`. Two animations sharing one property means one of them silently loses, usually the one that started first.
5. The callback returns a cleanup function that removes the pointer listeners. GSAP invokes it when the branch stops matching, not only on unmount, so a desktop-only listener cannot survive into the mobile layout.
6. On teardown the effect calls `mm.revert()`, which restores the inline styles GSAP wrote — including the `position: absolute` — so the authored column comes back unmodified. `mm.kill()` would stop the tweens but leave the fan frozen exactly where it was.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `breakpoint = 768`
  Where the fan takes over. The mobile query is deliberately `max-width: breakpoint - 1` rather than `max-width: breakpoint`: overlapping queries both match at exactly 768px and the two branches register at once, which is how a card ends up absolutely positioned inside a column.
- `spread = 15`
  Percent of container width per card step. At this value a five-card fan spans about 60% of the box with visible overlap. Past ~22% the outer cards leave the container; under ~8% they stack almost exactly and the fan reads as a printing error.
- `arc = 4`
  Percent of container height each step drops. A small positive arc puts the centre card highest, which is what makes the row read as a hand of cards rather than a straight strip. Zero is flat; past ~10% the outer cards fall out of the box bottom.
- `tilt = 5`
  Degrees per step, applied about a `50% 90%` origin so the cards rotate around their lower edge like a fan pivot. Rotating about the centre swings the tops and bottoms in opposite directions and the arc stops reading.
- `parallax = 26`
  Maximum pixels the outermost card travels with the pointer, scaled by its distance from centre. Enough to give the fan depth; past ~50px the cards visibly separate from their own shadows and the layout looks unstable.
- `ENTER_DURATION / ENTER_STAGGER = 0.7 / 0.06`
  A five-card fan finishes in 0.7 + 4 x 0.06 = 0.94 s. Longer staggers make the last card arrive after the user has already started reading; shorter ones collapse the sequence into a single flash.

## API

```ts
function MatchMediaLayoutTeardown(props: { children: ReactNode; breakpoint?: number; spread?: number; arc?: number; tilt?: number; parallax?: number; className?: string; itemClassName?: string }): JSX.Element
```

- `children: ReactNode`
  One card per child. Each is wrapped in the element GSAP positions.
- `breakpoint: number` — default `768`
  Pixel width at which the fan layout takes over.
- `spread: number` — default `15`
  Horizontal step per card, as a percentage of container width.
- `arc: number` — default `4`
  Vertical drop per step from centre, as a percentage of container height.
- `tilt: number` — default `5`
  Degrees of rotation per step from centre.
- `parallax: number` — default `26`
  Maximum pointer parallax in pixels for the outermost card.
- `className: string`
  Merged onto the container.
- `itemClassName: string`
  Merged onto every card wrapper. Give the cards a width here — the fan does not measure them.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
useEffect(() => {
  const root = rootRef.current;
  if (!root || count === 0) return;

  const mm = gsap.matchMedia();

  mm.add(
    {
      // Object form: every query is evaluated, and the results arrive as
      // booleans on `self.conditions`. One callback can therefore branch on
      // several axes (width AND motion preference) instead of needing a
      // separate `add` per combination, and GSAP re-runs it whenever ANY of
      // them flips — including the motion query, so a user toggling
      // "reduce motion" at runtime gets the static layout without a reload.
      isDesktop: `(min-width: ${breakpoint}px)`,
      isMobile: `(max-width: ${breakpoint - 1}px)`,
      reduced: '(prefers-reduced-motion: reduce)',
    },
    (self) => {
      // `noUncheckedIndexedAccess` makes every lookup `boolean | undefined`,
      // and `conditions` itself is optional. Default rather than assert.
      const conditions = self.conditions ?? {};
      const isDesktop = conditions.isDesktop ?? false;
      const reduced = conditions.reduced ?? false;

      // Mobile registers nothing at all. The base markup already IS the
      // mobile layout, so there is no work to do and, more importantly,
      // nothing for the revert to have to undo when we come back.
      if (!isDesktop) return;

      const cards = Array.from(root.querySelectorAll<HTMLElement>('[data-mm-card]'));
      const mid = (cards.length - 1) / 2;

      cards.forEach((card, i) => {
        const offset = i - mid;
        const away = Math.abs(offset);
        gsap.set(card, {
          position: 'absolute',
          // Percentages of the CONTAINER, so the fan rescales with the box
          // and no resize listener is needed inside this branch.
          left: `${50 + offset * spread}%`,
          top: `${50 + away * arc}%`,
          xPercent: -50,
          yPercent: -50,
          rotation: offset * tilt,
          zIndex: 100 - Math.round(away * 10),
          transformOrigin: '50% 90%',
        });
      });

      if (reduced) return;

      gsap.from(cards, {
        y: ENTER_Y,
        autoAlpha: 0,
        duration: ENTER_DURATION,
        ease: 'power3.out',
        stagger: ENTER_STAGGER,
      });

      // Parallax lives on `x`; the entrance owns `y` and `autoAlpha`. Two
      // animations on one property means one of them silently loses.
      const setters = cards.map((card) =>
        gsap.quickTo(card, 'x', { duration: PARALLAX_DURATION, ease: 'power3' }),
      );

      const onMove = (e: PointerEvent) => {
        const rect = root.getBoundingClientRect();
        const norm = (e.clientX - rect.left) / rect.width - 0.5;
        setters.forEach((setter, i) => {
          const depth = mid === 0 ? 0 : (i - mid) / mid;
          setter(norm * parallax * depth);
        });
      };
      const onLeave = () => setters.forEach((setter) => setter(0));

      root.addEventListener('pointermove', onMove);
      root.addEventListener('pointerleave', onLeave);

      // A cleanup returned from the callback runs when this branch stops
      // matching, not only on unmount. Without it, the desktop listener
      // survives into the mobile layout and keeps writing transforms to
      // elements that are back in the column.
      return () => {
        root.removeEventListener('pointermove', onMove);
        root.removeEventListener('pointerleave', onLeave);
      };
    },
  );

  // `revert()` restores the inline styles GSAP wrote — including the
  // `position: absolute` — so the base column comes back exactly as
  // authored. `kill()` would stop the tweens but leave the fan frozen in
  // place.
  return () => {
    mm.revert();
  };
}, [count, breakpoint, spread, arc, tilt, parallax]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `mm.revert()` on unmount reverts every recorded `set` and tween back to the pre-branch inline styles and runs each branch's returned cleanup, which removes the pointermove and pointerleave listeners. Nothing else is registered, so there is nothing else to release.

**Reduced motion.** `(prefers-reduced-motion: reduce)` is one of the queries in the same `add` block. When it matches, the desktop branch still composes the full fan with `gsap.set` and then returns early — no entrance tween, no pointer listener. The layout is identical; only the movement is gone. Because it is a matchMedia condition rather than a mount-time read, changing the OS setting reconfigures a mounted component immediately.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Registering animations once at mount and relying on CSS to hide them below the breakpoint. Resize past a breakpoint and a desktop-only ScrollTrigger keeps pinning on mobile, leaving a section stuck: the pin spacer is still in the document, the section will not scroll past, and nothing in the mobile stylesheet can undo it because the offending styles are inline. `matchMedia` reverts them instead.
- Using `mm.kill()` instead of `mm.revert()`. Kill stops the tweens but leaves every inline style GSAP wrote, so the fan freezes in place and the column never comes back.
- Overlapping queries: `(min-width: 768px)` paired with `(max-width: 768px)`. Both match at exactly 768px, both branches register, and the mobile teardown fights the desktop setup for one very confusing breakpoint width.
- Adding an event listener inside the callback without returning a cleanup. The listener outlives the branch, so a desktop pointer handler keeps writing transforms to cards that are back in the mobile column.
- Putting the responsive layout in Tailwind breakpoint classes AND the animation in matchMedia. The breakpoint now exists in two places and they drift; the classic symptom is a layout that switches at 768px while its animation switches at 1024px.
- Measuring the container inside the branch and hard-coding pixel offsets. The branch does not re-run on resize — only on a query change — so the fan is correct at the width it was registered at and wrong at every other width until you cross the breakpoint twice.
- Treating `self.conditions` as always defined. It is optional, and with `noUncheckedIndexedAccess` each lookup is `boolean | undefined`; a non-null assertion here compiles and then reads `undefined` as truthy-adjacent in the one edge case that matters.

## Notes

- No ScrollTrigger is used here, but the failure mode described in the first pitfall is the reason this pattern exists — a pinned desktop section that survives into a mobile layout is the single most common GSAP responsiveness bug, and `matchMedia` is the sanctioned fix.
- The same block also handles reduced motion: the `reduced` condition composes the final fan with `gsap.set` and returns before registering the entrance tween or the parallax listener, so the layout is identical and only the motion is absent.
- `gsap.context()` (via the `use-gsap` hook) is the right tool when you need scoped selectors and cleanup but no breakpoints. `matchMedia` is `context` plus queries — reach for it the moment a layout differs across breakpoints, not just its timing.

## Definition of done

Above 768px the cards fan out from the centre with a stagger, tilt outward, and drift with the pointer. Drag the window narrower past 768px and they return to a plain vertical column with no leftover transforms and no inline `position: absolute` on any card. Widen again and the fan re-registers and re-plays its entrance. Resize within the desktop range and the fan rescales with the box. Enable reduce-motion while it is open and the fan stays but stops moving.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Mixed Scrub Depth Layers

Elements marked with a depth index get two things from that index: how far they travel, and how much they lag. The travel is ordinary parallax; the lag — a different `scrub` value per depth — is what keeps the planes visibly apart while the eye is moving and lets them converge at rest. Works on a vertical page and, given a horizontal strip's tween, along that strip instead.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Layers separate while you scroll and converge when you stop, because each depth has its own scrub.

- Category: scroll
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. Each `[data-depth]` element is read once: `depth = clamp(parseInt(dataset.depth), 0, ladder.length - 1)`, so bad or missing markup lands on the nearest plane rather than throwing.
2. Distance comes from the normalised depth: `amount = (depth / (ladder.length - 1)) * travel`, tweened `fromTo(-amount → +amount)` in `yPercent` so it is relative to the element's own height and survives any layout.
3. Lag comes from the ladder: `scrub = ladder[depth]`, giving 0 / 0.25 / 0.5 / 1 seconds of catch-up across four planes. Depth 0 uses `scrub: true` rather than `scrub: 0`, because ScrollTrigger reads 0 as falsy and would drop scrubbing entirely.
4. The trigger window is the element's full crossing — `top bottom` to `bottom top` — so nothing is ever caught mid-tween on load and every layer is at a defined offset for any scroll position.
5. Passing a `containerAnimation` swaps the position keywords to `left right` / `right left`, so the same ladder drives layers riding a pinned horizontal strip.
6. The ladder array is serialised to a string for the effect dependency list, so a caller passing a fresh literal every render does not rebuild every trigger every render.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `DEFAULT_LADDER = [0, 0.25, 0.5, 1]`
  Seconds of catch-up per plane. Four values is the most the eye separates reliably; a fifth reads as the same distance as the fourth. Doubling at each step keeps the ratio between adjacent planes constant, which is what makes them read as evenly spaced.
- `travel = 26`
  yPercent at the deepest plane, so a tile moves just over a quarter of its own height across the whole crossing. Past ~40 the tiles visibly leave their grid cells and the layout looks broken; below ~10 the parallax is invisible once the lag is doing the work.
- `scrub for depth 0 = true`
  ScrollTrigger treats `scrub: 0` as falsy and turns scrubbing off, which makes the nearest plane a toggle animation instead of a locked one. `true` is the documented spelling of "no catch-up".
- `trigger window = 'top bottom' → 'bottom top'`
  The element's entire crossing of the scroller. A shorter window leaves the layer frozen at a partial offset above and below it, which shows up as a jump the first time it enters.

## API

```ts
function MixedScrubLayers(props: { children: ReactNode; scroller?: RefObject<HTMLElement | null>; containerAnimation?: gsap.core.Animation | null; ladder?: number[]; travel?: number; className?: string }): JSX.Element
```

- `children: ReactNode`
  Markup containing `[data-depth]` elements; 0 is nearest.
- `scroller: RefObject<HTMLElement | null>`
  Scroll container the triggers read. Omit for the document.
- `containerAnimation: gsap.core.Animation | null`
  A horizontal strip tween to measure along. `null` defers until it exists.
- `ladder: number[]` — default `[0, 0.25, 0.5, 1]`
  Seconds of catch-up per depth index. Length defines how many planes exist.
- `travel: number` — default `26`
  yPercent travel at the deepest plane.
- `className: string`
  Merged onto the wrapper.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function MixedScrubLayers({
  children,
  scroller,
  containerAnimation,
  ladder = DEFAULT_LADDER,
  travel = 26,
  className,
}: MixedScrubLayersProps) {
  const root = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();
  // Serialised so a fresh array literal from the caller does not rebuild
  // every trigger on every render.
  const ladderKey = ladder.join(',');

  useEffect(() => {
    const rootEl = root.current;
    if (!rootEl || reduced) return;
    if (containerAnimation === null) return;

    const steps = ladderKey.split(',').map(Number);
    const last = Math.max(1, steps.length - 1);
    const scrollerEl = scroller?.current ?? undefined;
    const horizontal = containerAnimation !== undefined;

    const ctx = gsap.context(() => {
      for (const el of Array.from(rootEl.querySelectorAll<HTMLElement>('[data-depth]'))) {
        const raw = Number.parseInt(el.dataset.depth ?? '0', 10);
        const depth = clamp(Number.isFinite(raw) ? raw : 0, 0, last);
        // Normalised depth drives distance; the ladder drives lag. Distance
        // alone collapses the moment the scroll stops — the lag is what keeps
        // the planes apart while the eye is still moving.
        const amount = (depth / last) * travel;
        const scrub = steps[depth] ?? 0;

        gsap.fromTo(
          el,
          { yPercent: -amount },
          {
            yPercent: amount,
            ease: 'none',
            scrollTrigger: {
              trigger: el,
              scroller: scrollerEl,
              // Full-crossing window: the layer starts moving as it enters
              // and stops as it leaves, so no layer is ever mid-jump on load.
              start: horizontal ? 'left right' : 'top bottom',
              end: horizontal ? 'right left' : 'bottom top',
              scrub: scrub === 0 ? true : scrub,
              ...(containerAnimation ? { containerAnimation } : {}),
            },
          },
        );
      }
    }, rootEl);

    return () => ctx.revert();
  }, [scroller, containerAnimation, ladderKey, travel, reduced]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `ctx.revert()` on unmount and on any dependency change kills each layer's tween and ScrollTrigger and strips the inline `transform` GSAP wrote, so a remount measures the authored layout rather than the previous run's offsets.

**Reduced motion.** No triggers are created, so every layer sits at its natural document position with no transform at all. The grid is the same grid — it simply does not separate, which is the point of the setting.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Building parallax from distance alone. Every layer lands on its final offset on the same frame, so the depth cue vanishes the instant scrolling stops and the composition flattens.
- Writing `scrub: 0` for the locked plane. It is falsy, so ScrollTrigger disables scrubbing and the layer plays as a one-shot toggle animation — the one plane that was supposed to be rock solid becomes the one that pops.
- Using `y` in pixels instead of `yPercent`. The offsets stop being proportional to the tiles, so a layout that reads well at desktop width has layers sliding out of their cells on a phone.
- Recreating triggers on every render because the ladder is a fresh array literal in the caller's JSX. The triggers are torn down and rebuilt mid-scroll and the layers snap back to their start offsets.
- Indexing the ladder without a bound. `data-depth="7"` on a four-value ladder yields `undefined`, which GSAP coerces into a scrub of `NaN` and the layer stops responding to scroll entirely.
- Keeping vertical position keywords when a `containerAnimation` is supplied. The trigger measures along the container's axis, so vertical keywords resolve to a position the element never reaches and the layer never moves.

## Notes

- Depth 0 is deliberately motionless. Something in the frame has to be still, or the whole composition reads as drift rather than depth.
- Combine with `pinned-horizontal-track` by feeding its `onTrack` payload's `animation` into `containerAnimation`.

## Definition of done

Scroll through the grid at speed: the tiles visibly separate into distinct planes, the depth-0 tile stays locked to the grid, and the deepest tiles trail furthest behind. Stop scrolling and, within about a second, everything settles into an aligned composition. Scroll backwards and the separation reverses rather than replaying.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Letter Scramble

Every character flips through a handful of wrong glyphs and then lands on the right one, each character starting a tenth of a second after the one before it, so the resolution sweeps left to right across the word. Each successive flip is held slightly longer than the last, which is what makes it read as settling rather than as a spinner that was switched off. Character widths are frozen to their final glyph before the first substitution, so the word does not breathe while it scrambles.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A word assembles out of noise — each character flips through wrong glyphs, decelerating onto the right one.

- Category: text
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. The word is split in JSX to one `inline-block` span per character, each carrying `data-final` with its resolved glyph. React owns every node; nothing is injected into the DOM.
2. A single `gsap.timeline` schedules `tl.call()` at absolute times. For character `i` the start time is `START_DELAY + i * stagger`; for flip `f` the time advances by `baseFlip + f * flipGrowth`, so hold durations grow 0.08, 0.105, 0.13, 0.155 … That arithmetic progression is the deceleration.
3. Each `call` assigns `c.textContent = randomGlyph`. After the last flip a final `call` writes `c.dataset.final`, and a `fromTo(c, { opacity: DIM }, { opacity: 1, duration: settle, ease: "power3.out" })` runs at the same time — the fade is what separates "resolved" from "one more wrong glyph".
4. Glyphs come from a seeded PRNG (`createRng(seed ?? text + ":" + run)` and `randInt`), never `Math.random`. The glyph sequence decides what is painted on the first client frame, and a server/client disagreement about that is a hydration mismatch.
5. Before the timeline is built, every character box is pinned with `c.style.width = getBoundingClientRect().width + "px"`, measured from the *final* glyph that is currently in the DOM. Proportional type gives `i` and `W` wildly different advance widths, so an unpinned word visibly breathes and every element after it on the line shudders in sympathy. A final `tl.call` at position `">"` clears the widths so the word reflows normally afterwards.
6. The whole build is deferred behind `document.fonts.ready`, because measuring before the webfont lands pins every box to a fallback-font width.
7. The real word is rendered once in an `sr-only` span and the animated characters are `aria-hidden`, since mid-flight they are literal garbage.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `GLYPHS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789#%&@$*'`
  The substitution pool. Uppercase and figures keep the visual weight even; adding lowercase mixes x-height and cap-height so the word appears to jitter vertically as well as horizontally. The punctuation adds texture without introducing very narrow glyphs.
- `FLIPS = 7`
  Wrong glyphs per character before resolving. Below ~4 there is no sense of searching; past ~10 the tail characters of a long word are still churning after the reader has looked away.
- `STAGGER = 0.1`
  Seconds between adjacent characters starting. Roughly the flip interval, so the sweep front is a couple of characters wide. Much smaller and the whole word scrambles as a block, losing the left-to-right read.
- `BASE_FLIP = 0.08`
  Seconds the first wrong glyph is held. About five frames at 60Hz — fast enough to be a blur, slow enough that the substitution is not skipped entirely on a slow frame.
- `FLIP_GROWTH = 0.025`
  Seconds added to each successive hold. This is the deceleration and it is the whole character of the effect: at 0 the flipping is constant-interval and reads as a slot machine that stopped, rather than as a search converging.
- `SETTLE = 0.45`
  Seconds of the opacity fade landing with the final glyph. Long enough to be a distinct beat after 0.08s flips; a shorter fade is indistinguishable from another substitution.
- `DIM = 0.35`
  Opacity the settle fade starts from. Fading from 0 makes the character disappear for a frame between the last wrong glyph and the right one, which reads as a dropped frame.
- `START_DELAY = 0.25`
  Seconds before the first character begins. Gives the page a moment to settle, so the scramble is not competing with layout for the reader's attention.
- `VIEW_THRESHOLD = 0.4`
  Fraction visible before the timeline runs, so a headline low on the page has actually arrived before it scrambles.

## API

```ts
function LetterScramble(props: { text: string; glyphs?: string; flips?: number; stagger?: number; baseFlip?: number; flipGrowth?: number; settle?: number; replayOnHover?: boolean; startOnView?: boolean; seed?: number | string; className?: string }): JSX.Element
```

- `text: string`
  The resolved word. Rendered as-is for SSR, reduced motion, and assistive technology.
- `glyphs: string` — default `'A-Z0-9#%&@$*'`
  Substitution pool. Keep to glyphs of similar visual weight.
- `flips: number` — default `7`
  Wrong glyphs shown per character before it resolves.
- `stagger: number` — default `0.1`
  Seconds between adjacent characters starting.
- `baseFlip: number` — default `0.08`
  Seconds the first wrong glyph is held.
- `flipGrowth: number` — default `0.025`
  Seconds added to each successive hold. This is the deceleration.
- `settle: number` — default `0.45`
  Seconds of the fade that lands with the final glyph.
- `replayOnHover: boolean` — default `true`
  Re-run on pointer enter, on fine pointers only.
- `startOnView: boolean` — default `true`
  Run when scrolled into view rather than on mount.
- `seed: number | string`
  Any string or number. The same seed gives the same sequence on every render.
- `className: string`
  Merged onto the outer span via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const GLYPHS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789#%&@$*';
const FLIPS = 7;
const STAGGER = 0.1;
const BASE_FLIP = 0.08;
const FLIP_GROWTH = 0.025;
const SETTLE = 0.45;
const START_DELAY = 0.25;
const DIM = 0.35;
const VIEW_THRESHOLD = 0.4;

export function LetterScramble({
  text,
  glyphs = GLYPHS,
  flips = FLIPS,
  stagger = STAGGER,
  baseFlip = BASE_FLIP,
  flipGrowth = FLIP_GROWTH,
  settle = SETTLE,
  replayOnHover = true,
  startOnView = true,
  seed,
  className,
}: LetterScrambleProps) {
  const root = useRef<HTMLSpanElement>(null);
  const reduced = useReducedMotion();
  const { inView } = useInView(root, { threshold: VIEW_THRESHOLD, once: true });
  const [run, setRun] = useState(0);

  useEffect(() => {
    const el = root.current;
    if (!el || reduced) return;
    if (startOnView && !inView) return;

    const chars = Array.from(el.querySelectorAll<HTMLElement>('[data-char]'));
    if (chars.length === 0 || glyphs.length === 0) return;

    // Seeded, never Math.random: the glyph sequence decides what is painted
    // on the first client frame, and a server/client disagreement about that
    // is a hydration mismatch.
    const rng = createRng(seed ?? `${text}:${run}`);

    let cancelled = false;
    let tl: gsap.core.Timeline | null = null;

    const restore = () => {
      for (const c of chars) {
        c.textContent = c.dataset.final ?? '';
        c.style.width = '';
        c.style.opacity = '';
      }
    };

    const build = () => {
      if (cancelled) return;

      // Measured after fonts are ready, and measured from the *final* glyph,
      // which is what is in the DOM right now. Measuring a substituted glyph
      // would lock in the wrong box.
      for (const c of chars) {
        c.style.width = `${c.getBoundingClientRect().width}px`;
      }

      tl = gsap.timeline();

      chars.forEach((c, i) => {
        const final = c.dataset.final ?? '';
        let t = START_DELAY + i * stagger;

        for (let f = 0; f < flips; f += 1) {
          const g = glyphs.charAt(randInt(rng, 0, glyphs.length));
          tl?.call(
            () => {
              c.textContent = g;
            },
            undefined,
            t,
          );
          t += baseFlip + f * flipGrowth;
        }

        tl?.call(
          () => {
            c.textContent = final;
          },
          undefined,
          t,
        );
        // The fade is what separates "resolved" from "one more wrong glyph".
        tl?.fromTo(
          c,
          { opacity: DIM },
          { opacity: 1, duration: settle, ease: 'power3.out' },
          t,
        );
      });

      // Release the frozen widths once nothing is substituting any more, so
      // the word reflows normally if the viewport or the font changes later.
      tl?.call(
        () => {
          for (const c of chars) c.style.width = '';
        },
        undefined,
        '>',
      );
    };

    // Splitting or measuring before the webfont lands measures the fallback,
    // and every character box is then frozen to the wrong width.
    void document.fonts.ready.then(build);

    return () => {
      cancelled = true;
      tl?.kill();
      restore();
    };
  }, [
    text,
    glyphs,
    flips,
    stagger,
    baseFlip,
    flipGrowth,
    settle,
    seed,
    startOnView,
    inView,
    reduced,
    run,
  ]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** A `cancelled` flag guards the async `document.fonts.ready` boundary so a build cannot start after unmount. Teardown kills the timeline and then restores every character: `textContent` back to `data-final`, and `style.width` and `style.opacity` cleared. Without that restore, unmounting mid-scramble would leave the word frozen as garbage inside pinned boxes.

**Reduced motion.** The effect returns before building anything, so the word stays exactly as React rendered it — the resolved text, at full opacity, on first paint. Hover replay is also disabled. Nothing is scrambled, hidden, or left mid-substitution.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Using `Math.random()` for the glyph sequence. The server and the client pick different glyphs, React reports a hydration mismatch, and the first frame flickers as the tree is patched.
- Not freezing the character widths. Every substitution changes the advance width, so the word pulses and everything after it on the line jitters for the whole animation.
- Measuring those widths before `document.fonts.ready`. Each box is then pinned to a fallback-font width, and when the real font arrives the glyphs are clipped or swimming inside boxes that are visibly the wrong size — the same failure mode described in `font-safe-text-split`.
- Measuring the width of a substituted glyph rather than the final one. The box is locked to the wrong character forever.
- Never releasing the frozen widths. The word cannot reflow on a viewport change or a late font swap, so it breaks out of its container at narrow widths.
- Constant-interval flipping. Without the growing hold the effect reads as a slot machine that was switched off rather than as a search that converged.
- Leaving the scrambling characters in the accessibility tree. A screen reader announces the random glyphs as they change; the real word must be exposed separately and the animated spans hidden.
- Re-running the effect from a `Math.random`-seeded value or an inline callback prop. The dependency array must contain only stable values or the scramble restarts on every parent render.

## Notes

- The original technique used GSAP MorphSVGPlugin to morph hand-drawn letter paths into random variants. MorphSVG is a paid GSAP Club plugin, so this is the dependency-free equivalent: character substitution from a glyph set on a per-character timeline, preserving the two things that actually make the original read the way it does — the 0.1s stagger and the `0.08 + n * 0.025` deceleration.
- No text-splitting library either. The split is declarative JSX; `SplitText` is reserved for the components whose subject is SplitText itself.
- Hover replay is gated on `(pointer: fine)` and on reduced motion being off — on touch there is no hover, so it would only fire on press and read as a glitch.

## Definition of done

On entering the viewport each character flips through several wrong glyphs and lands on the right one, left to right. Time the flips: the last is visibly slower than the first. The word occupies exactly the same width throughout, and nothing on the same line moves. Reload repeatedly with a fixed `seed` and the identical glyph sequence appears every time, with no hydration warning in the console. Unmount mid-scramble and remount, and the word is correct. With reduced motion enabled the resolved word is present on first paint.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Multipass Offscreen Composite

A hero field built the way a compositor builds one: a background ramp and three additive gradient fills are accumulated into an offscreen target, a bright-pass and blur run into a second target at half size, and a final pass adds them together with a vignette and a dither. The canvas is written exactly once, by the last pass. It is a small piece of art in its own right and a complete, disposable template for any offscreen chain.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Four passes into two render targets — ramp, additive fills, half-size bloom — and one composite that writes the canvas once.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. Passes 1 and 2 share one target. `renderer.autoClear = false` is set at construction, the scene target is cleared explicitly once with `renderer.clear(true, false, false)`, and the ramp and the fills are then rendered back to back. The absence of a clear between those two renders is the entire composite.
2. The ramp is a clip-space quad. Each fragment projects onto the ramp axis with `dot(uv - 0.5, dir) / (abs(dir.x) + abs(dir.y)) + 0.5`; the divisor is the largest that projection can reach inside the unit square, so the ramp reaches its end colour exactly at the far corner for any angle rather than saturating early.
3. The fills are three `PlaneGeometry(1, 1)` meshes in one rotated group, each drawn with a Gaussian falloff `exp(-d * d * uSoftness)` and `AdditiveBlending`. They travel around ellipses of different radii at speeds of 0.05, -0.08 and 0.11 revolutions per second, so the arrangement takes about 200 seconds to return to its start.
4. Both targets are `HalfFloatType`. Three additive fills overlap well past 1.0, and on an unsigned-byte target that overlap clips flat before the bright-pass runs — the bloom would then be told the image is uniformly hot wherever any two fills cross.
5. Pass 3 renders into a target at `bloomScale` (0.5) of the scene target. The bright-pass is a soft knee, `smoothstep(uThreshold, uThreshold + 0.25, luma)`, and the blur is a 3x3 tent with weights 4 / 2 / 1 normalised by 16. Its offsets are measured in the half-size target's texels, so the blur reaches twice as far across the image for the same nine taps.
6. Pass 4 reads both targets, adds `bloom * uBloomStrength`, multiplies by a vignette measured in a square space so it stays circular in a wide box, and adds triangular-PDF dither — the difference of two hashes, about 1/255 — to break the 8-bit banding a smooth ramp otherwise shows as hard contour lines.
7. Resizing calls `setSize` on both targets and rewrites `uResolution` and the bloom `uTexel`. Nothing is reallocated, and because no pass reads its own previous contents there is no clear-and-settle: the next frame redraws all four passes from scratch.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `renderer.autoClear = false`
  The one line that makes multipass possible in three. Left at its default, every `render()` clears its target first, so pass 2 wipes pass 1 and the layering silently collapses into whatever was drawn last — with no error and no warning.
- `bloomScale = 0.5`
  Quarter the pixels for the blur pass, and the tent's texel-sized offsets cover twice the distance. Below about 0.35 the half-resolution grid becomes visible as a soft blockiness in the upsample; at 1.0 the pass costs four times as much for a tighter, less useful glow.
- `BLOOM_RADIUS = 1.4`
  Tap spacing in bloom-target texels, so 2.8 scene pixels. Above roughly 2 the nine taps no longer overlap and the tent starts sampling a sparse grid, which shows up as a faint cross-shaped ringing around bright cores.
- `bloomThreshold = 0.34`
  Luma where the bright-pass starts. The ramp peaks near 0.18, so this sits above the background and below the fills: the glow comes from the lights, not from the whole frame. Drop it under the ramp and the bloom becomes a flat wash that just raises exposure.
- `knee width = 0.25`
  The smoothstep span above the threshold. With a hard step, a pixel pops into the bright set the instant it crosses the cut, so the bloom boundary crawls as the fills drift — the most common giveaway of a hand-rolled bloom.
- `DISC_SOFTNESS = 3.1`
  The k in `exp(-d*d*k)`, which puts the fill at 4.5% of peak at the edge of its own quad. Much lower and the Gaussian is still bright where the geometry stops, giving a visible square edge; much higher and the fill shrinks to a hard dot inside an oversized quad.
- `DITHER = 0.004`
  One 8-bit code. The ramp crosses only a few hundred codes over a thousand pixels, and without a sub-LSB perturbation that gradient bands into visible contour lines on any display. Larger values are perceptible as noise rather than as smoothness.
- `REVEAL_START / REVEAL_SPAN = 0.7 / 0.2`
  The source ties the fills to scroll with exactly this ramp: nothing until 70% of the progress, full by 90%, held after. The dead zone is deliberate — the ramp establishes the space first, and the light arrives as a separate event.
- `DISC_SQUASH / PLANE_TILT = 0.62 / -0.19 rad`
  The fills are round in their own plane; squashing them and rotating their shared group is what makes three moving blobs read as one ellipse seen at an angle instead of three unrelated circles.
- `STATIC_ELAPSED = 6.2 s`
  The frame drawn when motion is suppressed. At t = 0 all three fills sit at their starting phases; six seconds in, the composition is spread out and reads as a designed still rather than as a default state.
- `maxDpr = 2`
  Four full-screen passes are already 2.5 screens of fragments per frame (1 + 1 + 0.25 + 1). At a 3x backing store that is over twenty million fragment invocations per frame on a phone, for no visible gain over 2x.

## API

```ts
function MultipassOffscreenComposite(props: { reveal?: number; bloomStrength?: number; bloomThreshold?: number; bloomScale?: number; vignette?: number; drift?: number; rampAngle?: number; rampColors?: readonly [string, string, string]; fillColors?: readonly [string, string, string]; maxDpr?: number; className?: string }): JSX.Element
```

- `reveal: number` — default `1`
  Progress 0..1. The fills fade in between 0.7 and 0.9 and hold; the ramp is always drawn.
- `bloomStrength: number` — default `0.85`
  How much of the blurred bright-pass is added back in the composite.
- `bloomThreshold: number` — default `0.34`
  Luminance where the bright-pass begins to contribute, with a 0.25 knee above it.
- `bloomScale: number` — default `0.5`
  Bloom target size relative to the scene target. Changing it rebuilds both targets.
- `vignette: number` — default `0.38`
  Corner darkening in the composite, 0..1.
- `drift: number` — default `1`
  Multiplier on the fills' orbital speeds. 0 freezes them without stopping the passes.
- `rampAngle: number` — default `141`
  Ramp direction in degrees, counter-clockwise from +x.
- `rampColors: readonly [string, string, string]` — default `['#0a0f1a', '#16283c', '#070a12']`
  Start, bend and end stops of the background ramp.
- `fillColors: readonly [string, string, string]` — default `['#3f7ae0', '#2fd0b4', '#a866f0']`
  Colours of the three additive fills, largest first.
- `maxDpr: number` — default `2`
  Backing-store cap. Both targets follow the drawing buffer.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function MultipassOffscreenComposite({
  reveal = 1,
  bloomStrength = 0.85,
  bloomThreshold = 0.34,
  bloomScale = 0.5,
  vignette = 0.38,
  drift = 1,
  rampAngle = 141,
  rampColors = RAMP_COLORS,
  fillColors = FILL_COLORS,
  maxDpr = 2,
  className,
}: MultipassOffscreenCompositeProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);

  const { width, height } = useResizeObserver(host);
  const { inView } = useInView(host, { threshold: 0 });
  const visible = useVisibility();
  const reduced = useReducedMotion();

  const [supported, setSupported] = useState(true);
  useEffect(() => setSupported(hasWebGL()), []);

  /* Everything that only feeds a uniform lives here and is read inside the
     draw loop. None of it belongs in the effect's dependency list: rebuilding
     two render targets because a vignette changed by 0.01 would drop frames. */
  const live = useRef({ reveal, bloomStrength, bloomThreshold, vignette, drift });
  live.current = { reveal, bloomStrength, bloomThreshold, vignette, drift };

  const ready = width > 1 && height > 1 && supported;

  /* Joined, not spread. Array props are compared by identity, so an inline
     literal would be a new value every render and the effect would thrash. */
  const colorKey = `${rampColors.join('|')}/${fillColors.join('|')}`;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    const renderer = new THREE.WebGLRenderer({
      antialias: false,
      // Opaque. Pass 4 covers every pixel with alpha 1, so an alpha channel
      // would only cost bandwidth and force the compositor to blend.
      alpha: false,
      depth: false,
      stencil: false,
    });
    renderer.setPixelRatio(pixelRatio(maxDpr));
    renderer.setSize(el.clientWidth, el.clientHeight, false);
    renderer.setClearColor(0x000000, 1);
    // The single most important line in the file. See the header.
    renderer.autoClear = false;
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';
    el.appendChild(renderer.domElement);

    const buffer = new THREE.Vector2();
    renderer.getDrawingBufferSize(buffer);
    const bufferW = Math.max(2, Math.round(buffer.x));
    const bufferH = Math.max(2, Math.round(buffer.y));
    const bloomW = Math.max(2, Math.round(bufferW * bloomScale));
    const bloomH = Math.max(2, Math.round(bufferH * bloomScale));

    const sceneTarget = makeTarget(bufferW, bufferH);
    const bloomTarget = makeTarget(bloomW, bloomH);

    // Two cameras. The flat one is for the clip-space quads, whose vertex
    // shader ignores both matrices; the ortho one gives the fills a stable
    // -aspect..aspect x -1..1 space to move in.
    const flatCamera = new THREE.Camera();
    const contentCamera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 10);
    contentCamera.position.z = 1;

    const flatGeometry = new THREE.PlaneGeometry(2, 2);
    const discGeometry = new THREE.PlaneGeometry(1, 1);

    const [rampA = '#000000', rampB = '#000000', rampC = '#000000'] = rampColors;
    const rampUniforms: RampUniforms = {
      uResolution: { value: new THREE.Vector2(bufferW, bufferH) },
      uAngle: { value: (rampAngle * Math.PI) / 180 },
      uColorA: { value: new THREE.Color(rampA) },
      uColorB: { value: new THREE.Color(rampB) },
      uColorC: { value: new THREE.Color(rampC) },
    };
    const rampMaterial = new THREE.ShaderMaterial({
      vertexShader: MULTIPASS_FLAT_VERT,
      fragmentShader: MULTIPASS_RAMP_FRAG,
      uniforms: rampUniforms,
      depthTest: false,
      depthWrite: false,
    });
    const rampScene = new THREE.Scene();
    const rampQuad = new THREE.Mesh(flatGeometry, rampMaterial);
    rampQuad.frustumCulled = false;
    rampScene.add(rampQuad);

    const fillScene = new THREE.Scene();
    // One group, rotated once: the fills share a plane, and tilting the group
    // is what makes their paths read as one ellipse seen at an angle rather
    // than three unrelated circles.
    const fillGroup = new THREE.Group();
    fillGroup.rotation.z = PLANE_TILT;
    fillScene.add(fillGroup);

    const discMaterials: THREE.ShaderMaterial[] = [];
    const discMeshes: THREE.Mesh[] = [];
    for (let i = 0; i < DISCS.length; i++) {
      const spec = DISCS[i];
      if (!spec) continue;
      const uniforms: DiscUniforms = {
        uColor: { value: new THREE.Color(fillColors[i] ?? '#ffffff') },
        uIntensity: { value: 0 },
        uSoftness: { value: DISC_SOFTNESS },
      };
      const material = new THREE.ShaderMaterial({
        vertexShader: MULTIPASS_DISC_VERT,
        fragmentShader: MULTIPASS_DISC_FRAG,
        uniforms,
        transparent: true,
        blending: THREE.AdditiveBlending,
        depthTest: false,
        depthWrite: false,
      });
      const mesh = new THREE.Mesh(discGeometry, material);
      mesh.scale.set(spec.size, spec.size * DISC_SQUASH, 1);
      mesh.frustumCulled = false;
      fillGroup.add(mesh);
      discMaterials.push(material);
      discMeshes.push(mesh);
    }

    const bloomUniforms: BloomUniforms = {
      uSource: { value: sceneTarget.texture },
      uTexel: { value: new THREE.Vector2(1 / bloomW, 1 / bloomH) },
      uThreshold: { value: bloomThreshold },
      uRadius: { value: BLOOM_RADIUS },
    };
    const bloomMaterial = new THREE.ShaderMaterial({
      vertexShader: MULTIPASS_FLAT_VERT,
      fragmentShader: MULTIPASS_BLOOM_FRAG,
      uniforms: bloomUniforms,
      depthTest: false,
      depthWrite: false,
    });
    const bloomScene = new THREE.Scene();
    const bloomQuad = new THREE.Mesh(flatGeometry, bloomMaterial);
    bloomQuad.frustumCulled = false;
    bloomScene.add(bloomQuad);

    const compositeUniforms: CompositeUniforms = {
      uScene: { value: sceneTarget.texture },
      uBloom: { value: bloomTarget.texture },
      uResolution: { value: new THREE.Vector2(bufferW, bufferH) },
      uBloomStrength: { value: bloomStrength },
      uVignette: { value: vignette },
      uDither: { value: DITHER },
    };
    const compositeMaterial = new THREE.ShaderMaterial({
      vertexShader: MULTIPASS_FLAT_VERT,
      fragmentShader: MULTIPASS_COMPOSITE_FRAG,
      uniforms: compositeUniforms,
      depthTest: false,
      depthWrite: false,
    });
    const compositeScene = new THREE.Scene();
    const compositeQuad = new THREE.Mesh(flatGeometry, compositeMaterial);
    compositeQuad.frustumCulled = false;
    compositeScene.add(compositeQuad);

    stage.current = {
      resize(w, h) {
        renderer.setPixelRatio(pixelRatio(maxDpr));
        renderer.setSize(w, h, false);
        renderer.getDrawingBufferSize(buffer);
        const bw = Math.max(2, Math.round(buffer.x));
        const bh = Math.max(2, Math.round(buffer.y));

        const aspect = w / h;
        contentCamera.left = -aspect;
        contentCamera.right = aspect;
        contentCamera.updateProjectionMatrix();

        // setSize, never new. Allocating a pair of half-float targets is a
        // synchronous driver call; doing it from a ResizeObserver during a
        // window drag is how a smooth resize turns into a slideshow — and the
        // old targets would leak unless every one of them were disposed.
        sceneTarget.setSize(bw, bh);
        rampUniforms.uResolution.value.set(bw, bh);
        compositeUniforms.uResolution.value.set(bw, bh);

        const sw = Math.max(2, Math.round(bw * bloomScale));
        const sh = Math.max(2, Math.round(bh * bloomScale));
        bloomTarget.setSize(sw, sh);
        // Texel size is per target, and this one is not the canvas. Leaving it
        // at the old size makes the blur radius drift with the window.
        bloomUniforms.uTexel.value.set(1 / sw, 1 / sh);
      },

      draw(elapsed) {
        const state = live.current;

        // The source ties the fills to scroll with exactly this ramp.
        const fade = clamp((state.reveal - REVEAL_START) / REVEAL_SPAN, 0, 1);

        for (let i = 0; i < discMeshes.length; i++) {
          const mesh = discMeshes[i];
          const spec = DISCS[i];
          const material = discMaterials[i];
          if (!mesh || !spec || !material) continue;
          const angle = spec.phase + elapsed * spec.speed * state.drift * Math.PI * 2;
          mesh.position.set(Math.cos(angle) * spec.radius, Math.sin(angle) * spec.radius, 0);
          const intensity = material.uniforms.uIntensity;
          if (intensity) intensity.value = spec.intensity * fade;
        }

        // Passes 1 and 2 — one clear, two renders. The absence of a clear
        // between them IS the composite.
        renderer.setRenderTarget(sceneTarget);
        renderer.clear(true, false, false);
        renderer.render(rampScene, flatCamera);
        renderer.render(fillScene, contentCamera);

        // Pass 3 — bright-pass and blur at bloomScale. Nothing accumulates, so
        // this target never needs to survive a frame.
        bloomUniforms.uThreshold.value = state.bloomThreshold;
        renderer.setRenderTarget(bloomTarget);
        renderer.clear(true, false, false);
        renderer.render(bloomScene, flatCamera);

        // Pass 4 — the only write to the canvas.
        compositeUniforms.uBloomStrength.value = state.bloomStrength;
        compositeUniforms.uVignette.value = state.vignette;
        renderer.setRenderTarget(null);
        renderer.clear(true, false, false);
        renderer.render(compositeScene, flatCamera);
      },
    };

    stage.current.resize(el.clientWidth, el.clientHeight);
    stage.current.draw(0);

    return () => {
      stage.current = null;
      // Explicit, not disposeObject over the scenes: flatGeometry is shared by
      // three of them, and a traversal would dispose it three times.
      flatGeometry.dispose();
      discGeometry.dispose();
      rampMaterial.dispose();
      bloomMaterial.dispose();
      compositeMaterial.dispose();
      for (const material of discMaterials) material.dispose();
      // Both targets. Nothing walks a render target for you — each holds a
      // half-float texture and a framebuffer object.
      sceneTarget.dispose();
      bloomTarget.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, colorKey, rampAngle, bloomScale, maxDpr]);

  useEffect(() => {
    const current = stage.current;
    if (!current || width < 1 || height < 1) return;
    current.resize(width, height);
    // No pass reads its own previous contents, so a resized target needs no
    // clear-and-settle — but a still frame does need redrawing, since resizing
    // a target discards what it held.
    if (reduced) current.draw(STATIC_ELAPSED);
  }, [width, height, reduced]);

  useRaf(
    (_dt, elapsed) => {
      stage.current?.draw(elapsed);
    },
    ready && inView && visible && !reduced,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nulls the stage ref, disposes both `PlaneGeometry` instances, all six materials, and — separately, because nothing traverses them — both render targets. Then `disposeRenderer` performs `dispose` + `forceContextLoss` + a zeroed drawing buffer, and the canvas is removed from the DOM. The canvas is created inside the effect by three and appended per effect run, so a StrictMode remount builds a fresh context rather than reattaching the one that was just force-lost. `useRaf` releases its own subscription; the component adds no listeners of its own.

**Reduced motion.** The component reads `useReducedMotion` itself and never subscribes to rAF when it is set. All four passes still run, once, at a fixed elapsed of 6.2 seconds, and again after any resize — so the artwork is complete, correctly exposed and fully bloomed, it simply does not drift. A hero background is composition first and motion second; deleting it under reduced motion would leave a hole in the page, and freezing it at t = 0 would show an arrangement nobody designed.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Leaving `autoClear` at its default and wondering why only the last pass appears. Nothing errors; the ramp is simply gone, and the usual next move — reordering the renders — makes it worse.
- Setting `autoClear = false` and then forgetting to clear at all. The first target accumulates frame over frame, so the fills smear into permanent trails that look almost intentional for about two seconds.
- Recreating render targets in the resize handler. Allocating a pair of half-float framebuffers is a synchronous driver call; doing it on every ResizeObserver callback turns a window drag into a slideshow, and every previous pair leaks unless it is explicitly disposed.
- Disposing the renderer but not the targets. Render targets are not part of any scene graph, so nothing traverses them — each surviving one holds a full-resolution half-float texture plus a framebuffer object until the tab is closed.
- Using an 8-bit target for anything that feeds a bright-pass. Additive overlap clips at 1.0, so the bloom sees a plateau instead of a peak and the glow spreads uniformly across the crossing region.
- Premultiplying alpha in a shader that uses three's `AdditiveBlending`. That blend is already `(SrcAlpha, One)`, so multiplying in the shader squares the alpha and the fills all but vanish — then get "fixed" by tripling the intensity, which clips the cores.
- Reusing one `uTexel` or `uResolution` uniform across passes that render into differently sized targets. Everything looks right at one window size and the blur radius drifts as the window changes.
- Reading a colour buffer while it is still bound as the render target. It is undefined behaviour in WebGL and shows as tearing, black, or a correct image depending on the driver — which is why the bright-pass needs an offscreen target and cannot run on the canvas.
- Letting three convert colour space in the middle of the chain. Its output conversion is injected into built-in materials only, so a chain that mixes `ShaderMaterial` and `MeshBasicMaterial` converts at some passes and not others; this component uses `ShaderMaterial` everywhere and converts nowhere.

## Notes

- The renderer is created with `alpha: false`. Pass 4 covers every pixel at full alpha, so an alpha channel would only cost bandwidth and force the compositor to blend the canvas over the page.
- `reveal` is deliberately a plain number rather than an internal scroll listener. Drive it from whatever already tracks progress — `useInView`'s ratio, a scroll library, or a constant — and the component stays a renderer.
- The array props are compared through a joined string key, so passing an inline `[a, b, c]` literal does not tear down the GL stack on every render. Values that only feed a uniform (`reveal`, `bloomStrength`, `vignette`, `drift`) are read from a ref inside the draw loop and never appear in a dependency list.
- Geometries are disposed by hand rather than through `disposeObject` over each scene: the clip-space quad is shared by three scenes, and a traversal would dispose it three times.
- To extend the chain, add a target and a pass — the structure does not change. The costly mistakes are all in the two rules this file already follows: clear deliberately, and resize rather than reallocate.

## Definition of done

Three soft coloured lights drift across a dark angled ramp with a halo that is clearly wider and softer than the lights themselves, corners falling off, and no banding anywhere in the gradient — tilt a laptop screen and the ramp stays smooth. Resize the window continuously: the image tracks the box with no stutter, no flash of black, and the halo keeps the same apparent width. Set `reveal` to 0.5 and only the ramp is visible; sweep it to 1 and the lights come up over the last third. With reduced motion the full composition, bloom included, is present and still.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Nav Dot Wave

One keyframe block and N elements. Each nav item writes its own index into an inline `--i`, and the stylesheet turns that index into an animation delay, so a crest travels along the row. Adding a nav item requires no change to the CSS and no JavaScript at all.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Nav dots that lift in sequence. The index is an inline custom property; CSS derives the delay.

- Category: primitive
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. Every list item carries `style={{ "--i": i }}`. The dot's rule reads `animation-delay: calc(var(--i, 0) * var(--kx-dot-stagger, 60ms))`, so the phase offset of each dot is derived from its position rather than authored per item. The index is data; the timing is a function of it.
2. The keyframe is deliberately mostly flat: `0%, 60%, 100%` is the resting pose and only `30%` lifts. The dot therefore rests for 40% of every 1400 ms cycle. That long rest is what makes a staggered set read as a single crest travelling along the row instead of a row of dots vibrating in place.
3. 0% is the resting pose, not the lifted one, and that ordering is load-bearing. A positive `animation-delay` holds an element at its 0% pose until the delay expires, so if 0% were the lift, every dot would sit visibly raised for its share of the stagger on first paint and the row would *settle* into place rather than start from it.
4. The active item swaps to a second keyframe (`kx-dotwave-active`) with identical geometry but a constant `opacity: 1`. It participates in the wave so the row stays coherent, but it never dims, because a location marker that fades to 45% twice a second is a marker you cannot trust.
5. The lift is written with the `translate` property, not `transform`, so the active state's `scale: 1.6` composes independently and can carry its own spring transition without either value clobbering the other.
6. `reverse` negates the stagger to `-60ms`. Negative delays start an animation already partway through its cycle, so the phase gradient inverts and the crest runs right-to-left with no second keyframe.
7. The CSS ships in a `<style href="kinetic-nav-dot-wave" precedence="medium">` element. React 19 deduplicates and hoists it to the head by `href`, so the rules exist exactly once no matter how many navs are mounted, and nothing has to be added to a global stylesheet.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `durationMs = 1400`
  One dot's full cycle. Below ~900 ms the lift reads as a nervous twitch; above ~2000 ms the crest is so slow that a user glancing at the nav sees a static row and the effect is paid for but not perceived.
- `staggerMs = 60`
  Phase gap between neighbours. The crest travels at one item per 60 ms. Under ~30 ms the dots look simultaneous; over ~120 ms the wave breaks into visibly separate blips because the leading dot has finished its lift before the next begins.
- `keyframe rest span = 0%, 60%, 100%`
  The dot is flat for 40% of the cycle. Shrink the rest and adjacent dots overlap enough that the whole row appears raised at once, which is a vibration, not a wave.
- `peak position = 30%`
  The lift peaks in the first third and eases back over the next third. Symmetric timing (peak at 50%) makes each dot look like it is hovering rather than being flicked, and the crest loses its direction.
- `lift = 3`
  Pixels. A nav dot is 5px; 3px is a lift of over half its diameter, which is legible at a glance. Past ~6px the dots start colliding with the label baseline and the row looks broken rather than animated.
- `resting opacity = 0.45`
  Low enough that the peak at 1.0 registers as a change, high enough that an inactive nav item is still readable. Below ~0.3 the dots vanish against a dark surface and the row appears to lose items.
- `active scale = 1.6`
  The current-page dot has to win against five siblings that are all moving. Under ~1.3 it is lost in the wave; over ~2 it stops reading as the same kind of object as its neighbours.

## API

```ts
function NavDotWave(props: { items: readonly { label: string; href?: string }[]; activeIndex?: number; staggerMs?: number; durationMs?: number; lift?: number; size?: number; reverse?: boolean; className?: string }): JSX.Element
```

- `items: readonly NavDotWaveItem[]`
  Nav entries. Each is `{ label, href? }`; the label is also the React key.
- `activeIndex: number` — default `0`
  Index of the current page. Its dot grows, takes the accent colour and stops dimming.
- `staggerMs: number` — default `60`
  Milliseconds between one dot's phase and the next.
- `durationMs: number` — default `1400`
  Full cycle of a single dot, in milliseconds.
- `lift: number` — default `3`
  Peak lift in pixels.
- `size: number` — default `5`
  Dot diameter in pixels.
- `reverse: boolean` — default `false`
  Negates the stagger so the crest runs right-to-left.
- `className: string`
  Merged onto the `nav` element.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const DOT_WAVE_CSS = `
/* 0% is the RESTING pose, not the lifted one. That matters: a positive
   animation-delay holds the element at its 0% pose until the delay expires,
   so if 0% were the lift, every dot would sit visibly raised for its share of
   the stagger on first paint and the row would settle rather than start. */
@keyframes kx-dotwave {
  0%, 60%, 100% { opacity: 0.45; translate: 0 0; }
  30%           { opacity: 1;    translate: 0 var(--kx-dot-lift, -3px); }
}

/* The current item never dims — it is a location marker, and a marker that
   fades to 45% twice a second is a marker you cannot trust. */
@keyframes kx-dotwave-active {
  0%, 60%, 100% { opacity: 1; translate: 0 0; }
  30%           { opacity: 1; translate: 0 var(--kx-dot-lift, -3px); }
}

.kx-dotwave-list {
  display: flex;
  align-items: center;
  gap: var(--kx-dot-gap, 1.5rem);
  list-style: none;
  margin: 0;
  padding: 0;
}

.kx-dotwave-link {
  display: inline-flex;
  align-items: center;
  gap: 0.5rem;
  color: var(--color-muted, currentColor);
  transition: color 200ms linear;
}

.kx-dotwave-link:hover,
.kx-dotwave-item[data-active="true"] .kx-dotwave-link {
  color: var(--color-fg, currentColor);
}

.kx-dotwave-dot {
  width: var(--kx-dot-size, 5px);
  height: var(--kx-dot-size, 5px);
  border-radius: 9999px;
  background-color: currentColor;
  flex: none;
  scale: 1;

  animation: kx-dotwave var(--kx-dot-duration, 1400ms) ease-in-out infinite;
  animation-delay: calc(var(--i, 0) * var(--kx-dot-stagger, 60ms));

  /* 'translate' and 'opacity', not 'transform' — the scale below belongs to
     the active state and has to survive independently of the wave. */
  will-change: translate, opacity;
  transition: scale 260ms cubic-bezier(0.34, 1.56, 0.64, 1);
}

.kx-dotwave-item[data-active="true"] .kx-dotwave-dot {
  animation-name: kx-dotwave-active;
  background-color: var(--color-accent, currentColor);
  scale: 1.6;
}

/* No motion: the crest is decoration, so it goes. Everything that carries
   information stays — the current item keeps its accent colour and its larger
   dot, the rest keep their dimmed one. */
@media (prefers-reduced-motion: reduce) {
  .kx-dotwave-dot {
    animation: none;
    opacity: 0.45;
    will-change: auto;
  }
  .kx-dotwave-item[data-active="true"] .kx-dotwave-dot {
    opacity: 1;
  }
}
`;

export function NavDotWave({
  items,
  activeIndex = 0,
  staggerMs = 60,
  durationMs = 1400,
  lift = 3,
  size = 5,
  reverse = false,
  className,
}: NavDotWaveProps) {
  const rootStyle: StyleWithVars = {
    '--kx-dot-stagger': `${reverse ? -staggerMs : staggerMs}ms`,
    '--kx-dot-duration': `${durationMs}ms`,
    '--kx-dot-lift': `${-lift}px`,
    '--kx-dot-size': `${size}px`,
  };

  return (
    <>
      <style href="kinetic-nav-dot-wave" precedence="medium">
        {DOT_WAVE_CSS}
      </style>
      <nav className={cn('kx-dotwave', className)} style={rootStyle}>
        <ul className="kx-dotwave-list">
          {items.map((item, i) => {
            // The index is the only per-item data the stylesheet needs. Every
            // timing decision is derived from it in CSS.
            const itemStyle: StyleWithVars = { '--i': i };
            const active = i === activeIndex;
            return (
              <li
                key={item.label}
                className="kx-dotwave-item"
                data-active={active ? 'true' : 'false'}
                style={itemStyle}
              >
                <a
                  href={item.href ?? '#'}
                  className="kx-dotwave-link text-xs tracking-tight"
                  aria-current={active ? 'page' : undefined}
                >
                  <span className="kx-dotwave-dot" aria-hidden="true" />
                  {item.label}
                </a>
              </li>
            );
          })}
        </ul>
      </nav>
    </>
  );
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nothing imperative to tear down. The stylesheet is a React-managed `<style>` with an `href` key, so React owns its lifetime and deduplicates it across instances; unmounting the nav removes the elements and the animations with them.

**Reduced motion.** A `@media (prefers-reduced-motion: reduce)` block in the component's own stylesheet sets `animation: none` and `will-change: auto` on the dots, drops them to the resting opacity, and holds the active dot at full opacity. The accent colour and the 1.6x active scale stay, so the nav still shows where you are — only the travelling crest is removed.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Putting the lift at 0% of the keyframe. `animation-delay` freezes the element at its 0% pose, so on first paint the whole row sits raised and drops in sequence — the animation appears to run once backwards before starting.
- Animating `transform` for both the lift and the active scale. The last-declared transform wins, so the active dot either loses its lift or snaps back to scale 1 every cycle. Separate `translate` and `scale` properties compose instead.
- Driving the stagger from JavaScript with a timer or a per-item inline delay string. It costs a re-render per item, drifts out of phase with the CSS clock, and stops working the moment items are added dynamically.
- Letting the active dot dim with the rest. It is the only element on the page telling the user where they are; a marker at 45% opacity for most of every cycle is worse than no marker.
- Leaving `will-change: translate, opacity` on under reduced motion. The animation is gone but the compositor layer is not, so a nav that no longer moves still holds GPU memory on every dot.
- Removing the animation under reduced motion and removing the active state with it. The accent colour and the larger dot carry information, not decoration — only the crest should go.
- Keying the list by index while items reorder. The `--i` and the label desynchronise for one frame and a dot appears to jump across the row.

## Notes

- Nothing here is JavaScript-driven: no rAF, no observers, no state. The component's entire runtime cost is one style element and one inline custom property per item, which is why it is safe in a header that mounts on every route.
- The `--i` pattern generalises. Any staggered CSS animation — list entrances, grid reveals, letter-by-letter text — can take its delay from an index custom property instead of from generated per-item rules or a JavaScript timeline.
- Set `activeIndex` from your router. `aria-current="page"` is applied to the matching link, so the state is announced as well as drawn.

## Definition of done

A crest travels left-to-right along the dots once every 1.4 s and each dot is flat for most of that time. On first paint no dot is raised. The current item's dot is accent-coloured, 1.6x larger, and never dims while its neighbours do. Set `reverse` and the crest runs the other way. With reduced motion nothing moves, but the active dot is still larger and still accented.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: In-Shader Mouse Bulge

The pointer is a screen-space quantity and the mesh is a world-space one, so something has to convert between them. Instead of unprojecting the pointer on the CPU with a raycaster, every vertex projects ITSELF once, compares its own normalised device position against the pointer, and displaces by the result. Each vertex gets an exact distance, the cost is one extra matrix multiply per vertex, and nothing about it depends on the CPU knowing the mesh's real shape.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A soft lens that follows the cursor, measured by projecting every vertex to screen space instead of raycasting.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. The vertex shader runs `projectionMatrix * modelViewMatrix * vec4(pos, 1.0)` twice. The first is a probe: dividing its xy by w gives this vertex's own NDC position, which is the only common space the pointer and the geometry both live in.
2. NDC spans -1..1 on both axes whatever the viewport is, so a raw distance is stretched by the aspect ratio. The x component of the delta is multiplied by `uAspect` before the length is taken, which is what keeps the lens circular on a 16:9 canvas instead of an ellipse 1.78 times too wide.
3. The weight is `exp(-dot(delta, delta) * falloff)`. A Gaussian never actually reaches zero, so there is no radius at which the deformation visibly stops, and its derivative is continuous, so the sheen has no hard edge either — a smoothstep would give both a visible boundary ring.
4. The vertex is lifted by `bulge * uLift` and the weight is passed to the fragment shader, which pushes the centred UV outward by `centered * vBulge * uMagnify`. Lift alone is a bump; lift plus UV magnification is a lens, and that is the difference between a dent in the surface and glass sitting on top of it.
5. The second projection is the one that ships the vertex, evaluated after the displacement the first one made possible. The extra matrix multiply per vertex is the entire cost of the technique.
6. The strength uniform is damped toward the pointer's active state rather than switched, so the lens fades in on enter and out on leave instead of appearing at, and vanishing from, the last known position.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `falloff = 5`
  Tightness of the Gaussian in aspect-corrected NDC units, where the full viewport is 2 wide. At 5 the lens is roughly a third of the height across. Below ~2 it swells to cover the whole plane and reads as a global warp; above ~15 it collapses to a pinpoint that the vertex grid cannot resolve smoothly.
- `lift = 0.5`
  World units the crown rises, against a plane about 2.5 units tall at a camera distance of 3. Above ~1.2 the crown passes the camera's near plane and the lens punches a hole through itself when the cursor is centred.
- `magnify = 0.12`
  UV displacement at the crown. This is what makes it a lens rather than a bump. Above ~0.3 the magnification outruns the geometry, the texture visibly slides across the surface, and the illusion of glass breaks into a smear.
- `sheen = 0.18`
  Extra brightness at the crown. Small on purpose: the eye reads a slight highlight as curvature, and anything past ~0.4 reads as a blown-out light source instead.
- `segments = 128`
  The bulge is per-vertex, so the mesh density is the resolution of the lens. At 16 the Gaussian resolves into a faceted pyramid chasing the cursor; past ~192 the extra vertices land inside a single pixel of the highlight.
- `STRENGTH_SMOOTHING = 0.0008`
  Fraction of the gap left after one second, so the lens fades in over roughly a fifth of a second. Instant switching leaves the lens visible at the last known position for one frame after the cursor leaves, which flickers.
- `pointer smoothing = 0.0008`
  Matches the strength smoothing so the lens grows and moves at the same rate. A pointer smoothed much harder than the strength arrives late and the lens appears to be dragged; much softer and it inherits every jitter in the raw pointer stream.
- `CAMERA_FOV / CAMERA_Z = 45 / 3`
  Sets how much perspective the lift reads against. At a narrow FOV the raised crown barely changes size and the bulge looks flat; at a wide one the plane's own edges keystone enough to compete with the effect.

## API

```ts
function NdcMouseBulge(props: { strength?: number; falloff?: number; lift?: number; magnify?: number; sheen?: number; segments?: number; paint?: (ctx: CanvasRenderingContext2D, size: { width: number; height: number }) => void; className?: string }): JSX.Element
```

- `strength: number` — default `1`
  Peak displacement weight. 0 disables the effect.
- `falloff: number` — default `5`
  Gaussian tightness. Higher is a smaller, sharper lens.
- `lift: number` — default `0.5`
  World units the crown of the bulge rises toward the camera.
- `magnify: number` — default `0.12`
  How far the lens magnifies at the crown, in UV units.
- `sheen: number` — default `0.18`
  Extra brightness at the crown.
- `segments: number` — default `128`
  Plane subdivisions per axis. The resolution of the lens.
- `paint: (ctx, size) => void`
  Override the surface. Receives a 2D context for a 1024x1024 canvas.
- `className: string`
  Merged onto the wrapper via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function NdcMouseBulge({
  strength = 1,
  falloff = 5,
  lift = 0.5,
  magnify = 0.12,
  sheen = 0.18,
  segments = 128,
  paint,
  className,
}: NdcMouseBulgeProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);

  const { width, height } = useResizeObserver(host);
  const { inView } = useInView(host, { threshold: 0 });
  const visible = useVisibility();
  const reduced = useReducedMotion();
  // Already in NDC, which is exactly the space the shader compares in — no
  // conversion, no cached bounding rect to go stale on scroll.
  const pointer = useSmoothPointer({ target: host, smoothing: 0.0008 });

  const [supported, setSupported] = useState(true);
  useEffect(() => setSupported(hasWebGL()), []);

  const engaged = useRef(0);

  const live = useRef({ strength, falloff, lift, magnify, sheen });
  live.current = { strength, falloff, lift, magnify, sheen };

  const ready = width > 1 && height > 1 && supported;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setSize(el.clientWidth, el.clientHeight, false);
    renderer.setClearColor(0x000000, 0);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';
    el.appendChild(renderer.domElement);

    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(CAMERA_FOV, 1, 0.1, 100);
    camera.position.z = CAMERA_Z;

    const canvas = document.createElement('canvas');
    canvas.width = TEXTURE_SIZE;
    canvas.height = TEXTURE_SIZE;
    const ctx = canvas.getContext('2d');
    if (ctx) (paint ?? paintSurface)(ctx, { width: TEXTURE_SIZE, height: TEXTURE_SIZE });

    const texture = new THREE.CanvasTexture(canvas);
    texture.colorSpace = THREE.SRGBColorSpace;
    texture.wrapS = THREE.ClampToEdgeWrapping;
    texture.wrapT = THREE.ClampToEdgeWrapping;
    texture.anisotropy = Math.min(4, renderer.capabilities.getMaxAnisotropy());

    const uniforms: BulgeUniforms = {
      uTexture: { value: texture },
      uMouseNdc: { value: new THREE.Vector2(0, 0) },
      uAspect: { value: 1 },
      uStrength: { value: 0 },
      uFalloff: { value: falloff },
      uLift: { value: lift },
      uMagnify: { value: magnify },
      uSheen: { value: sheen },
    };

    // Dense. The bulge is evaluated per vertex, so the lens can only be as
    // round as the mesh is fine: at 16 segments the Gaussian resolves into a
    // faceted pyramid that follows the cursor.
    const geometry = new THREE.PlaneGeometry(1, 1, segments, segments);
    const material = new THREE.ShaderMaterial({
      vertexShader: ndcMouseBulgeVertexShader,
      fragmentShader: ndcMouseBulgeFragmentShader,
      uniforms,
    });
    const mesh = new THREE.Mesh(geometry, material);
    // The lift happens after the bounding sphere was computed; leaving culling
    // on lets three blank a plane that is filling the viewport.
    mesh.frustumCulled = false;
    scene.add(mesh);

    stage.current = { renderer, scene, camera, mesh, geometry, material, texture, uniforms };

    return () => {
      stage.current = null;
      scene.remove(mesh);
      // Inside `uniforms`, where `disposeObject` cannot see it.
      texture.dispose();
      disposeObject(scene);
      geometry.dispose();
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, segments, paint]);

  useEffect(() => {
    const current = stage.current;
    if (!current || width < 1 || height < 1) return;
    const aspect = width / height;
    current.renderer.setPixelRatio(pixelRatio());
    current.renderer.setSize(width, height, false);
    current.camera.aspect = aspect;
    current.camera.updateProjectionMatrix();

    // Cover the frustum exactly at z = 0. Derived from the camera, because the
    // visible extent at this distance has no fixed relationship to the pixel
    // width of the container.
    const visibleHeight = 2 * Math.tan((CAMERA_FOV * Math.PI) / 360) * CAMERA_Z;
    current.mesh.scale.set(visibleHeight * aspect, visibleHeight, 1);
    // The shader corrects its screen-space distance with this, so a stale
    // value turns the lens into an ellipse the moment the container reshapes.
    current.uniforms.uAspect.value = aspect;
  }, [width, height]);

  useRaf(
    (dt) => {
      const current = stage.current;
      if (!current) return;
      const { strength: peak, falloff: tightness, lift: rise, magnify: zoom, sheen: light } =
        live.current;

      // Fade the whole effect in and out with the pointer rather than snapping
      // it. Snapping leaves a lens sitting at the last known position for one
      // frame after the cursor leaves, which flickers.
      const wanted = pointer.current.active && !reduced ? peak : 0;
      engaged.current = damp(engaged.current, wanted, STRENGTH_SMOOTHING, dt);

      current.uniforms.uMouseNdc.value.set(pointer.current.ndcX, pointer.current.ndcY);
      current.uniforms.uStrength.value = engaged.current;
      current.uniforms.uFalloff.value = tightness;
      current.uniforms.uLift.value = rise;
      current.uniforms.uMagnify.value = zoom;
      current.uniforms.uSheen.value = light;

      current.renderer.render(current.scene, current.camera);
    },
    ready && inView && visible,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the mesh from the scene, disposes the `CanvasTexture` explicitly because it sits inside `material.uniforms` beyond `disposeObject`'s reach, runs `disposeObject` over the scene, disposes the geometry and material, then `disposeRenderer` — `setAnimationLoop(null)`, `dispose()`, `forceContextLoss()` — and removes the canvas from the DOM. The stage ref is nulled first so a frame already queued on the shared RAF loop exits before touching anything. `useSmoothPointer` removes its own listeners on unmount.

**Reduced motion.** The strength target is held at 0, so no vertex is ever displaced, the UV is never magnified and no sheen appears — the surface is a completely static image that ignores the pointer. The value is still damped to zero rather than assigned, so a lens that is on screen when the preference changes retracts smoothly instead of popping flat.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Comparing raw NDC distances. NDC is -1..1 on both axes regardless of the viewport, so on a 16:9 canvas the falloff is 1.78 times wider than it is tall and the lens is a visible ellipse. The x component of the delta is weighted by the aspect before the length is taken.
- Raycasting the pointer against the plane instead. It costs a matrix inversion per frame, returns exactly one hit point, and — decisively — it intersects the CPU-side geometry, which this shader has already moved. Once anything displaces vertices, the raycast answers a question about a surface that is not on screen.
- Projecting once and reusing `gl_Position`. The probe has to happen before the displacement and the final projection has to happen after it, so the two cannot be shared. Displacing after computing `gl_Position` simply has no effect at all.
- Using a linear or smoothstep falloff. Both reach exactly zero at a finite radius, which draws a visible ring on the surface where the deformation stops. The Gaussian is asymptotic and leaves no boundary.
- Lifting the vertex without magnifying the UV. The result is a bump, not a lens — the surface moves but the image printed on it does not, so it reads as a dent in a rigid sheet rather than glass laid over it.
- Leaving `frustumCulled` on. The lift happens after the bounding sphere was computed, so three can decide a plane that is filling the viewport is off screen and blank it.
- Sizing the plane from the container's pixel dimensions. The plane has to cover the frustum at z = 0, which is `2 * tan(fov/2) * distance` tall; a pixel width has no fixed relationship to that and the plane ends up short of the edges or overscaled.
- Forgetting to update `uAspect` on resize. The lens silently turns elliptical the moment the container reshapes, and because it still follows the cursor correctly the bug looks like a design decision.
- Calling `renderer.dispose()` alone on unmount. GPU objects are freed but the WebGL context survives, and Chromium drops the oldest once a renderer process holds about 16. `disposeRenderer` calls `forceContextLoss`.

## Notes

- `useSmoothPointer` already exposes `ndcX` / `ndcY`, so the pointer reaches the uniform without a single conversion and without a cached bounding rect that could go stale on scroll.
- This is the same two-projections-per-vertex trick `cylinder-gallery` uses; there it has to be in-shader, because the CPU geometry is a flat plane and the visible drum exists only on the GPU.

## Definition of done

Move the cursor over the surface and a round highlight follows it, swelling the lattice cells underneath rather than merely brightening them. The highlight is circular at any container aspect — resize from square to wide and it stays round. It has no visible outer edge or ring where the effect stops. Leave the surface and the lens retracts over about a fifth of a second rather than vanishing. Nothing changes when the cursor moves outside the component. With `prefers-reduced-motion: reduce` the surface is completely inert and the cursor has no effect at all.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Nested Split With True Restore

Splitting text destroys the markup inside it: a paragraph containing an `<em>` and an `<a>` goes into SplitText as semantic HTML and comes out as a flat pile of divs. This component splits into masked lines that rise into view, preserves each child element's own tag through the split, and on teardown restores the container's `innerHTML` byte-identically to what it was before anything touched it.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Splits rich markup into masked lines and restores the original innerHTML byte-for-byte on teardown.

- Category: text
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. `const originalHTML = el.innerHTML` is captured **before** any pre-processing. This string is the contract — everything else is arranged so it can be reapplied exactly.
2. The nested pre-pass walks the container's element children. Each child is split to lines on its own with a throwaway `new SplitText(child, { type: "lines" })`; the line markup is read while that split is live, the split is reverted, and each line is re-emitted inside a **shallow clone** of the child (`child.cloneNode(false)`) before the child is removed. A shallow clone carries the tag and every attribute and none of the content — `cloneNode(true)` would duplicate the child's entire text into every line.
3. The container is then split for real with `new SplitText(el, { type, mask: "lines", linesClass, aria: "auto" })`, and `gsap.from(split.lines, { yPercent: 110, duration: 0.9, stagger: 0.08, ease: "power3.out" })` runs inside a `gsap.context` scoped to the element.
4. The build is deferred behind `document.fonts.ready`, because line boxes measured against the fallback face break in the wrong places and never re-flow when the real font arrives. A `cancelled` flag closes the async gap so a build cannot start after unmount.
5. Teardown runs in a fixed order: `ctx.revert()` first, so the tween's inline styles are removed while the split nodes still exist; then `split.revert()`; then `if (el.innerHTML !== originalHTML) el.innerHTML = originalHTML`.
6. That last line is the whole point. GSAP's `revert()` restores the string SplitText itself captured at construction time — which, after a nested pre-pass, is the *intermediate* markup, not the original. The explicit restore is what makes the guarantee real.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `Y = 110`
  Percent of a line's own height it starts below the mask. Past 100 rather than at it, because `mask: "lines"` clips to the line box and descenders on the first frame otherwise peek below the mask edge on tall faces.
- `DURATION = 0.9`
  Seconds per line. Long enough that `power3.out` has room for its deceleration; below ~0.5s the ease flattens and the lines read as snapping into place.
- `STAGGER = 0.08`
  Seconds between lines. About a tenth of the duration, so five or six lines are always in motion together and the block reads as one rising mass rather than as a queue.
- `VIEW_THRESHOLD = 0.25`
  Fraction of the block visible before splitting and revealing. A paragraph is tall, so requiring more than about a quarter means it must be nearly centred before anything happens.
- `cloneNode(false) = false`
  Shallow, always. `true` copies the child's descendants, so every line of a five-line paragraph contains the whole paragraph and the block renders five times its own height.

## API

```ts
function NestedSplitRestore(props: { children: ReactNode; type?: string; mask?: boolean; nested?: boolean; y?: number; duration?: number; stagger?: number; delay?: number; startOnView?: boolean; className?: string }): JSX.Element
```

- `children: ReactNode`
  Markup to split. Element children keep their own tags and attributes through the pre-pass.
- `type: string` — default `'lines'`
  SplitText `type`. Lines are what the mask and the reveal use.
- `mask: boolean` — default `true`
  Wrap each line in an overflow-hidden box so it rises out of nothing.
- `nested: boolean` — default `true`
  Run the per-child pre-pass. Turn off for a single flat paragraph.
- `y: number` — default `110`
  Percent of a line's height it starts below the mask.
- `duration: number` — default `0.9`
  Seconds per line.
- `stagger: number` — default `0.08`
  Seconds between lines.
- `delay: number` — default `0`
  Seconds before the first line moves.
- `startOnView: boolean` — default `true`
  Split and reveal when scrolled into view rather than on mount.
- `className: string`
  Merged onto the container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const Y = 110;
const DURATION = 0.9;
const STAGGER = 0.08;
const VIEW_THRESHOLD = 0.25;

/**
 * Replace each element child of `host` with one shallow clone per visual line.
 * Text nodes sitting directly under `host` are left alone — they have no tag
 * to preserve, so the outer split handles them correctly already.
 */
function flattenChildrenToLines(host: HTMLElement): void {
  for (const child of Array.from(host.children)) {
    if (!(child instanceof HTMLElement)) continue;

    const inner = new SplitText(child, { type: 'lines' });
    // Read the line markup while the split is live, then put the child back
    // exactly as it was. Reading after revert would read the un-split child.
    const lines = inner.lines.map((line) => line.innerHTML);
    inner.revert();

    for (const markup of lines) {
      // cloneNode(false) — the tag and every attribute, none of the content.
      // cloneNode(true) would duplicate the child's entire text into each line.
      const clone = child.cloneNode(false);
      if (!(clone instanceof HTMLElement)) continue;
      clone.innerHTML = markup;
      host.insertBefore(clone, child);
    }
    host.removeChild(child);
  }
}

export function NestedSplitRestore({
  children,
  type = 'lines',
  mask = true,
  nested = true,
  y = Y,
  duration = DURATION,
  stagger = STAGGER,
  delay = 0,
  startOnView = true,
  className,
}: NestedSplitRestoreProps) {
  const root = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();
  const { inView } = useInView(root, { threshold: VIEW_THRESHOLD, once: true });

  useEffect(() => {
    const el = root.current;
    // Reduced motion never splits at all. The markup React rendered is the
    // finished state, and leaving it untouched is both the accessible answer
    // and the fast one.
    if (!el || reduced) return;
    if (startOnView && !inView) return;

    gsap.registerPlugin(SplitText);

    // Captured before the pre-pass, not after. This string is the contract.
    const originalHTML = el.innerHTML;

    let cancelled = false;
    let split: SplitText | null = null;
    let ctx: gsap.Context | null = null;

    const build = () => {
      if (cancelled) return;

      if (nested) flattenChildrenToLines(el);

      const s = new SplitText(el, {
        type,
        mask: mask ? 'lines' : undefined,
        linesClass: 'kinetic-split-line',
        // SplitText restores the original text to the accessibility tree
        // itself; without this the reveal is read out one line per node.
        aria: 'auto',
      });
      split = s;

      ctx = gsap.context(() => {
        gsap.from(s.lines, {
          yPercent: y,
          duration,
          stagger,
          delay,
          ease: 'power3.out',
        });
      }, el);
    };

    // Measuring line boxes before the webfont arrives measures the fallback,
    // so the lines break in the wrong places and never re-flow. See
    // `font-safe-text-split` for the full resize and late-font lifecycle.
    void document.fonts.ready.then(build);

    return () => {
      cancelled = true;
      // Order matters. The context reverts the tween's inline styles while the
      // split nodes still exist; reverting the split first would leave those
      // styles orphaned on nodes GSAP can no longer find.
      ctx?.revert();
      split?.revert();
      // The true restore. Only writes when something actually differs, so the
      // no-pre-pass case hands React back the very nodes it created.
      if (el.innerHTML !== originalHTML) el.innerHTML = originalHTML;
    };
  }, [
    children,
    type,
    mask,
    nested,
    y,
    duration,
    stagger,
    delay,
    startOnView,
    inView,
    reduced,
  ]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** A `cancelled` flag guards the async `document.fonts.ready` boundary. Teardown then runs `ctx.revert()` (kills the tweens and strips their inline styles while the split nodes still exist), `split.revert()`, and finally an explicit `el.innerHTML = originalHTML` when the two differ — the true restore.

**Reduced motion.** No split happens at all — the effect returns before touching the DOM. The markup React rendered is the finished state, so the text is fully visible and fully semantic on first paint, with every `<em>` and `<a>` intact. This is both the accessible answer and the fast one.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Trusting `revert()` to restore the original markup after a nested pre-pass. SplitText snapshots `innerHTML` at construction, which by then is your intermediate line markup — `revert()` faithfully restores the wrong thing, and the `<em>` and `<a>` are gone for good.
- Splitting before the webfont loads. Lines are measured against the fallback face, so they break in the wrong places and never re-flow; the mask then clips text that has moved outside its line box. See `font-safe-text-split`.
- Using `cloneNode(true)` in the pre-pass. Each line inherits the child's full contents and the block explodes to several times its height.
- Reading the line markup after reverting the inner split. Revert restores the child to its unsplit state, so you read the whole child back and produce one "line" containing everything.
- Reverting the split before the context. GSAP's inline styles are then orphaned on nodes the context can no longer find, so a remount starts from a half-animated state.
- Letting SplitText's line divs into the accessibility tree. Without `aria: "auto"` a screen reader announces one fragment per line, mid-sentence; with it SplitText restores the original text for assistive technology.
- Splitting at all under reduced motion. There is nothing to gain and a whole DOM tree to rebuild — the markup React rendered is already the finished state.

## Notes

- This is one of the two components that deliberately use GSAP `SplitText`, because the technique *is* SplitText: nested splitting and the shortcomings of its `revert()`. `SplitText` ships inside the main `gsap` package and is free to use; it is imported from `gsap/SplitText` rather than vendored, so this is a use grant and no redistribution is involved. The other text components here split declaratively in JSX so consumers are not forced into GSAP for effects that do not need it.
- The acceptance criterion is exact and testable: after teardown, `element.innerHTML` is byte-identical to what it was before the split — tags, attributes and whitespace included, not merely visually equivalent.
- The `nested` prop can be turned off for a single flat paragraph, in which case the pre-pass is skipped and the restore write never fires because the strings already match.

## Definition of done

Record `element.innerHTML` before mounting, unmount, and compare: the two strings are byte-identical, including the `<em>` and `<a>` tags and their attributes. Visually, lines rise from behind their own mask edge, staggered, with no character visible below the mask on the first frame. A screen reader reads the paragraph as continuous prose rather than as one fragment per line. With reduced motion enabled the paragraph is fully rendered on first paint and the DOM is never modified.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Single-Draw Orbit Rings

Five concentric orbits of static path dots, each carrying one brighter dot that travels it. Every dot in the system is a vertex of one `THREE.Points` object, so ring count and dot count cost buffer memory but never a second draw call. The outer rings are dimmer than the inner ones, which reads as depth even though the camera is orthographic and nothing is actually further away.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Concentric rings of dots, one bright marker travelling each ring, all of it in a single draw call.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. Each dot packs its whole identity into one attribute, `aPointData = vec4(kind, ringIndex, angle, dotRadius)`, where `kind` is 0 for a path dot and 1 for the orbiting marker. `position` is zeroed for every vertex and carries no information at all.
2. The vertex shader derives the ring radius as `uBaseRadius * scale * uExtent * 0.5` with `scale = 1.0 - (uRingCount - 1.0 - ringIndex) * 0.1`, so rings step 10% apart with the outermost at full radius, and `uExtent = min(width, height)` keeps the structure inside a preview of any aspect.
3. Path dots sit at `vec2(cos(angle), sin(angle)) * ringRadius`; markers use `angle - PI * 0.5 + uElapsed * uSpeed` instead, so the phase offset baked into the attribute becomes a starting position and the clock does the travelling.
4. Depth is faked with a focal length that no camera uses: `alpha = 0.15 + 0.65 * FOCAL_LENGTH / (FOCAL_LENGTH + ringRadius)` dims a ring in proportion to its size, so wider rings recede.
5. `gl_PointSize` is clamped to a 2px floor and the fragment alpha is then divided by the area that clamping invented — `vAlphaScale = unclamped² / clamped²` — so a dot forced twice as wide comes out four times fainter and the field looks identical at 1x and 3x device pixel ratio.
6. The fragment shader turns each square point sprite into a disc with `1.0 - smoothstep(0.43, 0.5, length(gl_PointCoord - 0.5))` and discards anything fully transparent, so the renderer is created with `antialias: false`.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `RING_STEP = 0.1`
  10% radius difference between adjacent rings. Below ~0.06 the rings visually merge into a band at preview size; above ~0.15 the innermost ring collapses to a dot when ringCount is 5.
- `FOCAL_LENGTH = 800.0`
  Not a camera property — the denominator of the alpha falloff. At 800 the outermost ring lands about 30% dimmer than the innermost at typical preview sizes: enough to read as depth, not enough to read as a fade-out. At 200 the outer rings vanish.
- `MIN_POINT_SIZE = 2.0`
  Hardware floor. Below roughly 1px most GPUs rasterise nothing at all, so a 1px dot at DPR 1 would simply be missing on some machines rather than faint.
- `UNCLAMPED_MIN_POINT_SIZE = 1.0`
  The size the dot *would* have had. It is the numerator of the area correction — without a separate constant there is nothing to compare the clamped size against and the compensation cannot be computed.
- `disc edge = smoothstep(0.43, 0.5, d)`
  A soft band 7% of the point radius wide. Narrower and a 2px dot aliases into a square; wider and every dot looks blurred rather than small.
- `baseRadius = 0.75`
  Outermost ring diameter as a fraction of the container short side. At 1.0 the ring touches the edge and the marker clips as it passes; 0.75 leaves a margin the marker can travel through.
- `dotsPerRing = 170`
  Dense enough that the path reads as a continuous line at 320px wide, sparse enough that the innermost ring is not a solid filled circle.
- `speed = 0.3`
  Radians per second — one lap every ~21s. Linear, no easing: a constant angular rate is what makes it read as a mechanism rather than an animation.

## API

```ts
function OrbitRingPoints(props: { ringCount?: number; dotsPerRing?: number; speed?: number; baseRadius?: number; dotRadius?: number; markerRadius?: number; opacity?: number; color?: string; markerColor?: string; seed?: number | string; className?: string }): JSX.Element
```

- `ringCount: number` — default `5`
  Concentric rings. Each gets exactly one travelling marker.
- `dotsPerRing: number` — default `170`
  Static path dots per ring.
- `speed: number` — default `0.3`
  Marker angular speed in radians per second.
- `baseRadius: number` — default `0.75`
  Outermost ring diameter as a fraction of the container short side.
- `dotRadius: number` — default `1`
  Path dot radius in CSS pixels, before pixel-ratio scaling.
- `markerRadius: number` — default `3`
  Marker radius in CSS pixels.
- `opacity: number` — default `1`
  Multiplier applied to every dot in the vertex shader.
- `color: string` — default `'#8a8f98'`
  Path dot colour, any value `THREE.Color` accepts.
- `markerColor: string` — default `'#ffffff'`
  Travelling marker colour.
- `seed: number | string` — default `'orbit-ring-points'`
  Seeds the angular scatter, so the ring is identical on server and client.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function OrbitRingPoints({
  ringCount = 5,
  dotsPerRing = 170,
  speed = 0.3,
  baseRadius = 0.75,
  dotRadius = 1,
  markerRadius = 3,
  opacity = 1,
  color = '#8a8f98',
  markerColor = '#ffffff',
  seed = 'orbit-ring-points',
  className,
}: OrbitRingPointsProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  const { width, height } = useResizeObserver(host);
  const size = useRef({ width, height });
  size.current = { width, height };

  const reduced = useReducedMotion();
  const ready = width > 0 && height > 0;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    if (!hasWebGL()) {
      setUnsupported(true);
      return;
    }

    // `antialias: false` is deliberate: the fragment shader anti-aliases each
    // disc itself with a smoothstep, so MSAA would pay for a whole extra
    // sample buffer to solve a problem that is already solved.
    const renderer = new THREE.WebGLRenderer({ antialias: false, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setClearAlpha(0);

    const scene = new THREE.Scene();
    // Orthographic and 1:1 with CSS pixels, so `gl_PointSize` in the shader is
    // a real pixel count and the ring radii are real pixel radii.
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
    camera.position.z = 1;

    const rng = createRng(seed);
    const perRing = dotsPerRing + 1; // path dots + one marker
    const total = ringCount * perRing;

    const positions = new Float32Array(total * 3); // stays all zeros
    const pointData = new Float32Array(total * 4);

    let at = 0;
    for (let ring = 0; ring < ringCount; ring += 1) {
      // Sorting the angles is not cosmetic. Points are drawn in buffer order,
      // and an unsorted ring interleaves near and far dots so the alpha blend
      // stipples along the path instead of reading as one continuous line.
      const angles = new Float32Array(dotsPerRing);
      for (let i = 0; i < dotsPerRing; i += 1) angles[i] = rng() * Math.PI * 2;
      angles.sort();

      for (let i = 0; i < dotsPerRing; i += 1) {
        pointData[at] = 0;
        pointData[at + 1] = ring;
        pointData[at + 2] = angles[i] ?? 0;
        pointData[at + 3] = dotRadius;
        at += 4;
      }

      pointData[at] = 1;
      pointData[at + 1] = ring;
      pointData[at + 2] = rng() * Math.PI * 2;
      pointData[at + 3] = markerRadius;
      at += 4;
    }

    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
    geometry.setAttribute('aPointData', new THREE.BufferAttribute(pointData, 4));

    const uniforms: Uniforms = {
      uElapsed: { value: 0 },
      uExtent: { value: 1 },
      uPixelRatio: { value: renderer.getPixelRatio() },
      uOpacity: { value: opacity },
      uRingCount: { value: ringCount },
      uSpeed: { value: speed },
      uBaseRadius: { value: baseRadius },
      uColor: { value: new THREE.Color(color) },
      uMarkerColor: { value: new THREE.Color(markerColor) },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: ORBIT_RING_POINTS_VERT,
      fragmentShader: ORBIT_RING_POINTS_FRAG,
      uniforms,
      transparent: true,
      depthTest: false,
      depthWrite: false,
    });

    const points = new THREE.Points(geometry, material);
    // Every vertex sits at the origin, so three computes a bounding sphere of
    // radius zero and culls the entire object the moment the camera is not
    // looking straight at (0,0,0). Displacement happens in the shader, which
    // the culler cannot see.
    points.frustumCulled = false;
    scene.add(points);

    el.appendChild(renderer.domElement);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';

    const resize = (w: number, h: number) => {
      renderer.setSize(w, h, false);
      camera.left = -w / 2;
      camera.right = w / 2;
      camera.top = h / 2;
      camera.bottom = -h / 2;
      camera.updateProjectionMatrix();
      // Ring radii scale off the SHORT side. Off the height alone, a wide
      // preview leaves the rings floating in a sea of empty space; off the
      // width alone, a tall one clips them.
      uniforms.uExtent.value = Math.min(w, h);
      uniforms.uPixelRatio.value = renderer.getPixelRatio();
    };

    const draw = (elapsed: number) => {
      uniforms.uElapsed.value = elapsed;
      renderer.render(scene, camera);
    };

    resize(size.current.width, size.current.height);
    stage.current = { renderer, scene, camera, uniforms, resize, draw };
    draw(STATIC_ELAPSED);

    return () => {
      stage.current = null;
      // Order matters: release the scene graph's GPU objects while the
      // context is still alive, then hand the context back.
      disposeObject(scene);
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
  }, [
    ready,
    ringCount,
    dotsPerRing,
    speed,
    baseRadius,
    dotRadius,
    markerRadius,
    opacity,
    color,
    markerColor,
    seed,
  ]);

  // Resize is its own effect so a container reflow costs a `setSize` call
  // rather than a full teardown and rebuild of the buffer.
  useEffect(() => {
    stage.current?.resize(width, height);
    if (reduced) stage.current?.draw(STATIC_ELAPSED);
  }, [width, height, reduced]);

  useRaf((_dt, elapsed) => stage.current?.draw(elapsed), ready && !reduced && !unsupported);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Clears the stage ref first so no queued frame can touch a dead renderer, then `disposeObject(scene)` for the geometry, `material.dispose()`, `disposeRenderer(renderer)` for `dispose` + `forceContextLoss` + zeroing the drawing buffer, and finally removes the canvas from the DOM. The rAF subscription is released by `useRaf` on unmount.

**Reduced motion.** The rAF subscription is never opened. One frame is drawn at `uElapsed = 0`, which parks every marker at twelve o'clock on its ring, so the full structure is visible and only the orbiting stops. Resizing still redraws that frame.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Leaving `frustumCulled` at its default. Every vertex sits at the origin, so three computes a bounding sphere of radius zero; the displacement is invisible to the culler and the entire object disappears the moment the camera is not pointed exactly at (0,0,0).
- Not sorting the angles within a ring before writing them into the buffer. Points are blended in buffer order with depth testing off, so an unsorted ring stipples — the path visibly breaks into a dotted texture instead of reading as one line.
- Clamping `gl_PointSize` without correcting the alpha. The clamp is invisible at DPR 3 and doubles the covered area at DPR 1, so the same component looks twice as bright on a cheap monitor as on a retina laptop.
- Turning on `antialias: true` to smooth the dots. The fragment shader already anti-aliases each disc; MSAA then allocates a multisample buffer the size of the canvas to solve nothing.
- Rebuilding the renderer on every resize. The buffer is size-independent — only the camera frustum and `uExtent` change — so a container reflow should cost a `setSize` call, not a teardown that drops and re-acquires a GL context.
- Calling `renderer.dispose()` and stopping there. It frees GPU objects but leaves the context alive; `disposeRenderer` also calls `forceContextLoss`, without which a grid of previews silently blacks out the oldest one at around sixteen contexts.

## Notes

- The camera is orthographic and spans the canvas 1:1 in CSS pixels, so `gl_PointSize` is a real pixel count and ring radii are real pixel radii. That is what makes the pixel-ratio compensation expressible at all.
- Ring count and dots per ring are both free at draw time. A hundred rings is one draw call and one buffer upload.

## Definition of done

Five rings of dots with one brighter dot travelling each, all at the same angular rate, the outer rings visibly dimmer than the inner ones. Resize the container and the rings rescale without flicker or a dropped context. Zoom the browser to 200% and the dots stay the same apparent brightness rather than getting denser. With reduced motion on, the rings render fully and the markers sit still at the top.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Key-Replayed Page Reveal

Two opaque layers and one CSS keyframe do the whole job of a route transition. The inbound layer carries `key={revealKey}`, so a route change unmounts it and mounts a new one — and a freshly mounted element runs its animation from frame zero, which replays the fade with no state, no library and nothing to reset. The outbound layer fades up to opaque and the navigation commits at 80% of that, while the screen is already covered, so the two halves hand off invisibly without ever referring to each other.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

An opaque overlay that fades away on every route change, replayed by nothing more than a changed React key.

- Category: transition
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. The inbound layer is `<div key={revealKey} className="kinetic-reveal-in" />`. Its animation runs `from { opacity: 1 }` to `to { opacity: 0; visibility: hidden }` over 0.55 s on `cubic-bezier(0.4, 0, 0.2, 1)` with `forwards`. Changing `revealKey` is the entire replay mechanism: React sees a different key, discards the node, mounts a new one, and the new node starts its animation at frame zero.
2. `visibility: hidden` in the `to` frame, held by `forwards`, is what retires the layer. At `opacity: 0` alone a full-viewport opaque surface stays composited for the rest of the page's life; `visibility` removes it from the compositor without unmounting anything.
3. `usePageCover(coverDuration)` returns `{ covering, cover }`. `cover(commit)` sets `covering` true — which flips `data-covering` on the outbound layer and runs `opacity: 0 -> 1` over `coverDuration` on `cubic-bezier(0.4, 0, 1, 1)` — then, after `coverDuration * 0.8` seconds, calls `setCovering(false)` and `commit()` in the same tick.
4. Both calls in one tick matters: React batches them into a single commit, so the cover drops to transparent on the exact frame the re-keyed inbound layer mounts at opacity 1. Split them across two ticks and there is one frame of bare destination content visible between the two halves.
5. The transition property is declared on the `[data-covering="true"]` rule only, never on the base rule, so release is a hard cut rather than a fade. The inbound layer is opaque and stacked above the cover at that instant, so the cut is invisible — and a symmetric fade there would compound two opacities and hold the screen dark past the end of the reveal.
6. The stylesheet is emitted through React 19's `<style href precedence>` hoisting, which dedupes by `href`. Per-instance values — durations, colour, z-index — ride in CSS custom properties set on the root, because there is only ever one copy of the rule block.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `revealDuration = 0.55`
  Seconds for the inbound fade. Under ~0.35 s the reveal reads as a flicker of the wrong colour rather than a curtain lifting; over ~0.8 s the destination is legible through a haze for long enough that people start clicking through it.
- `PAGE_COVER_DURATION = 0.32`
  Seconds for the outbound cover. Deliberately about half the reveal: leaving should feel decisive and arriving should feel gradual. Exported as a constant so the hook that times the commit and the layer that runs the transition cannot be handed two different numbers.
- `COMMIT_FRACTION = 0.8`
  Fraction of the cover the commit waits for. On `cubic-bezier(0.4, 0, 1, 1)` the layer is roughly 96% opaque at 80% of the way through, so the step to fully covered is imperceptible while a fifth of the perceived navigation latency disappears. At 1.0 every click pays a full 0.32 s of dead time; below ~0.6 the destination is visibly swapped behind a translucent sheet.
- `cover ease = cubic-bezier(0.4, 0, 1, 1)`
  Ease-in, no ease-out. The cover must be at its steepest as it approaches opaque, which is what makes 80% look like 100%. An ease-out cover crawls through its last 20% and the early commit becomes visible.
- `zIndex = 195`
  Above a custom cursor (150) and a scroll progress bar (120) — both of which must be hidden during a transition — and below a preloader (200), which must be able to sit over a reveal on first load.

## API

```ts
function PageRevealOverlay(props: { revealKey: string; revealDuration?: number; coverDuration?: number; covering?: boolean; color?: string; zIndex?: number; position?: "fixed" | "absolute"; className?: string }): JSX.Element
function usePageCover(coverDuration?: number): { covering: boolean; cover: (commit: () => void) => void }
```

- `revealKey: string`
  Identity of the current page. A change replays the reveal. `usePathname()` in Next.js.
- `revealDuration: number` — default `0.55`
  Seconds the inbound cover takes to fade away.
- `coverDuration: number` — default `0.32`
  Seconds the outbound cover takes to reach opaque. Pass the same value to `usePageCover`.
- `covering: boolean` — default `false`
  Drive from `usePageCover().covering`.
- `color: string` — default `'#000'`
  Any CSS colour. Must be opaque, or the page shows through the handoff.
- `zIndex: number` — default `195`
  Above the site and any custom cursor, below a preloader.
- `position: "fixed" | "absolute"` — default `"fixed"`
  `absolute` inside a bounded container; `fixed` for a real page transition.
- `className: string`
  Merged onto the root via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * Seconds the outbound cover takes to reach opaque. Shared default so the hook
 * that times the commit and the layer that runs the transition cannot be given
 * two different numbers.
 */
export const PAGE_COVER_DURATION = 0.32;

/**
 * Fraction of the cover the commit waits for. On the `cubic-bezier(0.4, 0, 1,
 * 1)` cover, 80% of the way through the screen is about 96% opaque, so the
 * step to fully covered is imperceptible — and a fifth of the perceived
 * navigation latency is gone. Waiting for 100% is a fifth of a second of dead
 * time on every single click.
 */
const COMMIT_FRACTION = 0.8;

const REVEAL_CSS = `
@keyframes kinetic-page-reveal {
  from { opacity: 1; }
  to   { opacity: 0; visibility: hidden; }
}
.kinetic-reveal-root {
  /* Never eats a click, not even mid-fade. The layer is opaque and covers the
     whole viewport; one swallowed click on a nav item is a dead site. */
  pointer-events: none;
  z-index: var(--kx-reveal-z, 195);
}
.kinetic-reveal-layer {
  position: absolute;
  inset: 0;
  background: var(--kx-reveal-color, #000);
}
/* Inbound. Starts opaque because it is mounted at the moment the destination
   is mounted, and holds the end frame with 'forwards' so 'visibility: hidden'
   retires the layer from compositing instead of leaving an invisible
   full-screen surface alive for the rest of the page's life. */
.kinetic-reveal-in {
  opacity: 1;
  animation: var(--kx-reveal-duration, 0.55s) cubic-bezier(0.4, 0, 0.2, 1)
    forwards kinetic-page-reveal;
}
/* Outbound. Idle is hidden as well as transparent, for the same reason. */
.kinetic-reveal-cover {
  opacity: 0;
  visibility: hidden;
}
/* The transition is declared on the covering state ONLY, so release is a cut.
   That is deliberate: at release the re-keyed inbound layer is already sitting
   at opacity 1 directly above this one, so a second fade here would compound
   two opacities and hold the screen dark past the end of the reveal. */
.kinetic-reveal-cover[data-covering='true'] {
  opacity: 1;
  visibility: visible;
  transition: opacity var(--kx-cover-duration, 0.32s)
    cubic-bezier(0.4, 0, 1, 1);
}
@media (prefers-reduced-motion: reduce) {
  /* Not 'animation: none' — that would leave the inbound layer parked at its
     opaque from-frame, permanently covering the site. The layers are removed
     entirely, and 'usePageCover' commits synchronously, so navigation is a
     hard cut to the destination with no flash of overlay in either direction. */
  .kinetic-reveal-layer { display: none; }
}
`;

export interface PageRevealOverlayProps {
  /**
   * Identity of the current page. A change replays the reveal. In Next.js App
   * Router this is `usePathname()`; in the demo it is a local state value.
   */
  revealKey: string;
  /** Seconds the inbound cover takes to fade away. */
  revealDuration?: number;
  /** Seconds the outbound cover takes to reach opaque. */
  coverDuration?: number;
  /** Drive from `usePageCover().covering`. */
  covering?: boolean;
  /** Any CSS colour. Must be opaque, or the page shows through the handoff. */
  color?: string;
  /** Above the site, below a preloader. */
  zIndex?: number;
  /** `absolute` to demo inside a bounded box; `fixed` for a real page. */
  position?: 'fixed' | 'absolute';
  className?: string;
}

export function PageRevealOverlay({
  revealKey,
  revealDuration = 0.55,
  coverDuration = PAGE_COVER_DURATION,
  covering = false,
  color = '#000',
  zIndex = 195,
  position = 'fixed',
  className,
}: PageRevealOverlayProps) {
  return (
    <>
      {/* React 19 hoists and dedupes by `href`, so a hundred navigations and
          any number of instances still emit exactly one rule block. Per
          instance values ride in custom properties for that reason. */}
      <style href="kinetic-page-reveal-overlay" precedence="medium">
        {REVEAL_CSS}
      </style>

      <div
        aria-hidden
        className={cn(
          'kinetic-reveal-root',
          position === 'fixed' ? 'fixed inset-0' : 'absolute inset-0',
          className,
        )}
        style={
          {
            '--kx-reveal-duration': `${revealDuration}s`,
            '--kx-cover-duration': `${coverDuration}s`,
            '--kx-reveal-color': color,
            '--kx-reveal-z': zIndex,
          } as CSSProperties
        }
      >
        {/* Cover first, reveal second: later in the DOM paints on top, and the
            inbound layer's opaque first frame is what hides the cover's cut. */}
        <div
          className="kinetic-reveal-layer kinetic-reveal-cover"
          data-covering={covering ? 'true' : 'false'}
        />
        <div key={revealKey} className="kinetic-reveal-layer kinetic-reveal-in" />
      </div>
    </>
  );
}

export interface PageCover {
  /** Feed to `PageRevealOverlay`. */
  covering: boolean;
  /** Raise the cover, then run `commit` — your navigation — under it. */
  cover: (commit: () => void) => void;
}

/**
 * The outbound half. `commit` is a callback rather than a router call so
 * nothing here depends on a routing library.
 */
export function usePageCover(coverDuration = PAGE_COVER_DURATION): PageCover {
  const [covering, setCovering] = useState(false);
  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
  const reduced = useReducedMotion();

  useEffect(
    () => () => {
      if (timer.current !== null) clearTimeout(timer.current);
      timer.current = null;
    },
    [],
  );

  const cover = useCallback(
    (commit: () => void) => {
      // Reduced motion: no cover at all, and the commit is synchronous. A
      // zero-duration cover would still be one frame of opaque colour, which
      // is a flash — the single most unpleasant thing to show someone who has
      // asked for less motion.
      if (reduced) {
        commit();
        return;
      }
      // A second click while a cover is already up would schedule a second
      // commit and navigate twice. The live timer is the lock.
      if (timer.current !== null) return;

      setCovering(true);
      timer.current = setTimeout(
        () => {
          timer.current = null;
          // Both in one tick, so React batches them into a single commit: the
          // cover drops to transparent on the exact frame the re-keyed reveal
          // layer mounts at opacity 1. Split across two ticks and there is one
          // frame of bare destination content between them.
          setCovering(false);
          commit();
        },
        coverDuration * COMMIT_FRACTION * 1000,
      );
    },
    [coverDuration, reduced],
  );

  return { covering, cover };
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The only resource is the commit timer, cleared in an unmount effect and nulled so the lock cannot survive a remount. There are no listeners, no rAF and no tweens; the animations are CSS and die with the nodes React removes.

**Reduced motion.** Both layers get `display: none`, and `usePageCover` calls the commit synchronously rather than starting a timer. Navigation is a hard cut straight to the destination — no cover, no reveal, and crucially not a zero-duration overlay, which would still be one frame of opaque colour.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Animating the overlay with a tween and a timeline. There is nothing to tween: the whole reason this is bulletproof is that a remount restarts a CSS animation, so there is no in-flight animation to kill, no state to reset, and a double navigation cannot leave the overlay half-faded.
- Using `animation: none` for reduced motion. That leaves the inbound layer parked on its opaque `from` frame, permanently covering the site — the failure looks like a blank page. The layers get `display: none` and `usePageCover` commits synchronously instead.
- Committing the navigation after the cover finishes. A fifth of a second of nothing happening after a click is exactly where a visitor decides the link is broken and clicks again.
- Omitting `pointer-events: none`. A full-viewport opaque div swallows the click on whatever the visitor aims at next, and mid-transition that is usually another nav item.
- Letting `cover()` run while a cover is already up. Without the live-timer lock a fast double click schedules two commits and navigates twice, so the visitor lands one page past where they aimed.
- Leaving the finished inbound layer at `opacity: 0` without `visibility: hidden`. It is still a composited full-viewport surface, and on a page that also runs a WebGL hero it costs a measurable slice of fill rate for the rest of the session.
- Fading the cover back out symmetrically. Two opaque layers both mid-fade multiply, not add: the screen stays darker for longer and the reveal appears to stall before it starts.

## Notes

- In Next.js App Router: mount once in `app/layout.tsx` with `revealKey={usePathname()}` and `position="fixed"`, then replace nav `<Link>` elements with buttons calling `cover(() => router.push(href))`. Nothing in this file imports `next/navigation` — the commit is a callback so the same component works under React Router or a plain state switch.
- The overlay colour must be opaque. A translucent colour makes both halves show the wrong page through the handoff, which is the one artefact this technique exists to prevent.
- The root carries `aria-hidden`: it is a purely decorative surface, and a screen reader announcing it on every navigation would be worse than no transition at all.
- Browser back and forward change the key without going through `cover()`, so they get the reveal but not the cover. That is correct — a history navigation has already happened by the time your code hears about it, so there is nothing left to cover.

## Definition of done

Click a nav item: the panel fades to the overlay colour, the destination content swaps while it is covered, and the overlay fades away over roughly half a second. The heading is never visible in an intermediate state, and there is no frame where old and new content are both on screen. Click two nav items in quick succession and you land on the second one, not past it. With reduced motion the content swaps instantly with no coloured frame in either direction.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Staggered Panel Wipe

The counter, the word list and the exit wipe are three parts of a single `gsap.timeline`, not three independent animations racing each other. The number is tweened on a plain object with `power2.inOut`, so it accelerates and settles instead of ticking linearly — the difference between a loading count and a progress bar wearing a costume.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

An eased 0-100 counter, a word list and a five-column wipe, all on one timeline so they cannot drift.

- Category: transition
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. A plain object `{ v: 0 }` is tweened to 100 over `countDuration` seconds. `onUpdate` writes `String(Math.round(count.v)).padStart(3, "0")` into a ref'd span. Tweening the object rather than the DOM keeps the eased value in one place and means the number is interpolated by the same engine, on the same clock, as everything else on the timeline.
2. The words are placed with `tl.set(wordEl, { textContent: w }, i * step)` where `step = countDuration / words.length` — for five words over 1.6 s that is one word every 320 ms. Because they are positioned on the timeline rather than scheduled with `setTimeout`, they stay locked to the counter if the timeline is retimed, paused, or seeked.
3. When the count lands, the content block leaves on `yPercent: -120, opacity: 0` over 0.5 s with `power3.inOut`. -120 rather than -100 clears the block past its own height plus a margin, so a descender never lingers at the top edge.
4. The five columns then retract with `scaleY: 0` and `transformOrigin: "top"`, 0.9 s of `power4.inOut`, staggered 0.08 s apart, inserted at `-=0.2` so the wipe begins while the content is still leaving. `scaleY` is a compositor-friendly transform; animating `height` here would relayout five elements every frame.
5. The whole build runs inside `useGsap`, which wraps it in a `gsap.context` scoped to the root and calls `ctx.revert()` on unmount, so a preloader torn down mid-count leaves no inline transforms behind.
6. Only after the timeline's `onComplete` fires does React set `gone` and return `null`. Unmounting on a timer instead would pull the nodes out from under running tweens.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `countDuration = 1.6`
  Seconds for 0 to 100. Under ~1.2 s the digits change too fast to read as a count and the word list flickers; over ~2.5 s people have already decided the site is slow.
- `CONTENT_DURATION = 0.5`
  Content exit. Long enough to read as a departure rather than a cut, short enough that it is finished before the panels have opened far enough to reveal what is behind it.
- `PANEL_DURATION = 0.9`
  Per-column retract. `power4.inOut` spends most of its time near the ends, so a shorter duration collapses the slow start and the whole wipe reads as a single instant cut.
- `PANEL_STAGGER = 0.08`
  Gap between columns. At 0 the five columns are one panel; past ~0.15 the last column is still standing after the first has finished, which reads as a stuck element rather than a sequence.
- `PANEL_OVERLAP = 0.2`
  Seconds the wipe is pulled back into the content exit. Without the overlap there is a dead beat between the number disappearing and the panels moving, and that pause is where the eye decides something has hung.
- `padStart(3, "0") = 3`
  Fixed three-digit width. Without it the counter changes character count at 10 and 100 and the number visibly jumps sideways twice mid-tween.

## API

```ts
function PanelWipePreloader(props: { words?: string[]; panels?: number; countDuration?: number; onDone?: () => void; position?: "fixed" | "absolute"; className?: string }): JSX.Element | null
```

- `words: string[]` — default `['Assets', 'Type', 'Shaders', 'Layout', 'Ready']`
  Words shown under the counter, spread evenly across the count.
- `panels: number` — default `5`
  Number of collapsing columns.
- `countDuration: number` — default `1.6`
  Seconds the counter takes to reach 100.
- `onDone: () => void`
  Fires from the timeline's `onComplete`, after the last column has collapsed.
- `position: "fixed" | "absolute"` — default `"fixed"`
  Use `absolute` inside a bounded container; `fixed` for a real full-page preloader.
- `className: string`
  Merged onto the root via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function PanelWipePreloader({
  words = ['Assets', 'Type', 'Shaders', 'Layout', 'Ready'],
  panels = 5,
  countDuration = 1.6,
  onDone,
  position = 'fixed',
  className,
}: PanelWipePreloaderProps) {
  const root = useRef<HTMLDivElement>(null);
  const content = useRef<HTMLDivElement>(null);
  const counter = useRef<HTMLSpanElement>(null);
  const word = useRef<HTMLSpanElement>(null);
  const reduced = useReducedMotion();
  const [gone, setGone] = useState(false);

  const done = useRef(onDone);
  done.current = onDone;

  useGsap(
    gsap,
    () => {
      const el = root.current;
      const contentEl = content.current;
      const counterEl = counter.current;
      const wordEl = word.current;
      if (!el || !contentEl || !counterEl || !wordEl) return;

      const columns = Array.from(el.querySelectorAll<HTMLElement>('[data-wipe-panel]'));

      if (reduced) {
        counterEl.textContent = '100';
        wordEl.textContent = words[words.length - 1] ?? '';
        setGone(true);
        done.current?.();
        return;
      }

      const count = { v: 0 };
      const tl = gsap.timeline({
        onComplete: () => {
          setGone(true);
          done.current?.();
        },
      });

      tl.to(count, {
        v: 100,
        duration: countDuration,
        ease: 'power2.inOut',
        onUpdate: () => {
          counterEl.textContent = String(Math.round(count.v)).padStart(3, '0');
        },
      });

      // Positioned on the SAME timeline as the counter, at computed times, so
      // the words stay locked to the number no matter how the timeline is
      // retimed, paused or seeked.
      const step = countDuration / Math.max(words.length, 1);
      words.forEach((w, i) => {
        tl.set(wordEl, { textContent: w }, i * step);
      });

      tl.to(contentEl, {
        yPercent: -120,
        opacity: 0,
        duration: CONTENT_DURATION,
        ease: 'power3.inOut',
      });

      if (columns.length > 0) {
        // transformOrigin top + scaleY 0 retracts each column upward like a
        // blind. The -0.2 overlap fuses the wipe with the tail of the content
        // exit so the two read as one gesture.
        tl.to(
          columns,
          {
            scaleY: 0,
            transformOrigin: 'top',
            duration: PANEL_DURATION,
            ease: 'power4.inOut',
            stagger: PANEL_STAGGER,
          },
          `-=${PANEL_OVERLAP}`,
        );
      }
    },
    root,
    [reduced],
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useGsap` runs the whole build inside a `gsap.context` scoped to the root and calls `ctx.revert()` on unmount, which kills the counter tween, the positioned `set` calls and the panel stagger, and restores every property they touched — including the span's original `textContent`.

**Reduced motion.** No timeline is built at all. The counter is written straight to 100, the last word is set, the component unmounts itself and `onDone` fires on the same tick — so a reduced-motion visitor sees the real page immediately rather than a silent panel that still has to be waited out.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Driving the counter with `setInterval` and the panels with GSAP. Two clocks, and on a loaded main thread the number finishes after the wipe has already covered it.
- Tweening a linear counter. It is the ease that sells the count — `power2.inOut` slows near 100, which is the shape of real work finishing.
- Animating panel `height` instead of `scaleY`. Five elements relayouting every frame on a page that is simultaneously mounting its real content is the one place the jank is guaranteed to be visible.
- Unmounting the preloader on a `setTimeout` sized to match the timeline. The two drift under load; unmount from `onComplete` instead.
- Leaving the preloader in the tree with `opacity: 0`. It still swallows every click on the page underneath. This returns `null`.
- Forgetting `transformOrigin: "top"`. The default centre origin makes the columns shrink to a band in the middle of the screen instead of retracting like a blind.

## Notes

- In a Next.js App Router project this mounts once in `app/layout.tsx`, above `{children}`, and calls `onDone` to flip a context flag the hero listens to. It is deliberately not keyed to the pathname — a preloader that replays on every navigation is a bug, not a feature.
- If the real site has an actual load signal (fonts ready, hero image decoded), gate `onDone` on both the timeline and that promise. See `safe-preloader` for the ceiling-and-floor version of that problem.
- The counter is decorative. The root carries `aria-hidden`, so a screen reader is never read a number climbing to 100.

## Definition of done

The number counts 000 to 100 with a visible ease, never changing width. Five words swap under it at even intervals and the last word lands as the number does. The content lifts away and five columns retract upward in sequence, the wipe starting before the content has finished leaving. `onDone` fires once, after the last column. With reduced motion the preloader is gone on the first frame. Unmount mid-count and no transforms or altered text remain.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Pause, Don't Unmount

A rotating stack of slabs mounted twice over: once behind `<Activity mode="hidden">` and once behind a plain conditional, switchable live. Hiding tears the Effects down either way — the WebGL context is released, which is what you want, since contexts are a scarce per-process resource. What Activity keeps is everything React owns: the fiber, the DOM, and every `useState` and `useRef` value inside. So the stack resumes at the angle it left, and the build counter on its fiber survives to be incremented again. Requires React 19.2 or newer.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

React 19's Activity hides a WebGL scene without losing its state. Effects still tear down, so the GL context is genuinely released.

- Category: primitive
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. `<Activity mode="hidden">` does three separable things, and conflating them is where the misuse starts: it sets `display: none` on the host children, it destroys the Effects inside — cleanup functions run, in order, exactly as on unmount — and it keeps the fiber alive, so state, refs and DOM nodes are all still there when `mode` goes back to `visible`. Children continue to re-render, at a priority below anything visible.
2. Because Effects are destroyed, the scene's cleanup runs on every hide: materials and geometry are disposed and `disposeRenderer` calls `renderer.forceContextLoss()`. That is the correct behaviour rather than a shortfall — Chromium hands out roughly sixteen WebGL contexts per renderer process and evicts the oldest past that, so a context parked behind `display: none` is the thing that blanks an unrelated canvas three sections down the page.
3. The rotation phase lives in a `useRef` inside the hidden subtree, and the build Effect seeds the slab rotations from it BEFORE the first draw. On re-show the scene is correct on frame one; there is no snap from zero up to the resumed angle. Under the `unmount` arm the same ref is a fresh zero because the fiber it lived on was collected.
4. The build counter is the proof, and it needs both halves to move: it increments inside the Effect, so it only rises if the Effect really re-ran, and it survives between runs only if the fiber was preserved. Under `activity` it climbs 1, 2, 3; under `unmount` it is pinned, because each show starts a new fiber whose counter is new too.
5. Build cost is measured with `performance.now()` from the top of the Effect to the end of the first completed `render`, so it covers context acquisition, program linking and the initial upload — the work Activity does not save. On a desktop GPU it lands in the tens of milliseconds; the point of the readout is that the number is not zero.
6. The size hook re-seeds synchronously from `getBoundingClientRect` on every Effect run, and its state is preserved across the hide as well, so the re-shown scene already knows its dimensions and skips the zero-sized first render that a fresh mount has to pass through. That one saved render round-trip is a second, quieter thing the preserved fiber buys.
7. The renderer creates its own canvas inside the Effect and it is removed in cleanup. A React-rendered `<canvas ref>` cannot work here: with `forceContextLoss()` in cleanup, StrictMode's double-invoke hands the second run a permanently dead element, and Activity turns that from a once-per-mount hazard into a once-per-toggle one.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `GAP = 0.2`
  Vertical spacing between slabs in world units, at a slab height of 1.15. Tight enough that the group reads as one stack rather than seven separate cards, wide enough that the back-to-front transparent sort has visible separation to work with.
- `TWIST = 0.24`
  Radians of rotation between neighbouring slabs — about 14 degrees, so seven slabs fan through 84 degrees, just under a quarter turn. Past a full turn the stack becomes rotationally ambiguous and "it resumed where it left" stops being checkable by eye.
- `count / period = 7 / 24`
  Seven slabs at 24 seconds a revolution: 15 degrees per second. Slow enough that a hide and a show a second apart leaves a gap the eye can measure against the readout, which is the entire experiment.
- `CAM_Y / CAM_Z = 2.05 / 4.4`
  A camera lean of about 25 degrees above the stack. Flatter and the slabs collapse into a single silhouette; steeper and it reads as a plan view where the vertical stacking disappears.
- `opacity ramp = 0.34 to 0.80`
  Bottom slab to top. The ramp is what makes the stack legible through itself; a constant alpha turns seven slabs into one muddy plane.

## API

```ts
function PauseDontUnmount(props: { strategy?: 'activity' | 'unmount'; count?: number; period?: number; color?: string; accent?: string; seed?: number | string; className?: string }): JSX.Element
```

- `strategy: 'activity' | 'unmount'` — default `'activity'`
  Which arm the switch starts on.
- `count: number` — default `7`
  Slabs in the stack.
- `period: number` — default `24`
  Seconds for one full rotation.
- `color: string` — default `'#5f6873'`
  Colour of the bottom slab.
- `accent: string` — default `'#e8e4dc'`
  Colour of the top slab. The stack lerps between the two.
- `seed: number | string` — default `'pause-dont-unmount'`
  Seeds the per-slab size jitter.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
useEffect(() => {
  const el = host.current;
  if (!el || !ready) return;

  if (!hasWebGL()) {
    setUnsupported(true);
    return;
  }

  // Timed from here to the first completed draw: allocating the context,
  // linking the programs and uploading the geometry are what re-showing
  // actually costs, and the number is the honest counterweight to "Activity
  // makes hiding free".
  const t0 = performance.now();

  // The renderer makes its own canvas inside the effect. Two reasons, and
  // both bite here: StrictMode double-invokes this effect, so a React-owned
  // `<canvas ref>` would be handed back after `forceContextLoss()` killed
  // it; and Activity destroys and re-runs this effect on every show, which
  // is the same hazard once per toggle instead of once per mount.
  const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
  renderer.setPixelRatio(pixelRatio());
  renderer.setClearAlpha(0);

  const scene = new THREE.Scene();
  const camera = new THREE.PerspectiveCamera(FOV, 1, 0.1, 100);
  camera.position.set(0, CAM_Y, CAM_Z);
  camera.lookAt(0, 0, 0);

  const geometry = new THREE.PlaneGeometry(SLAB_W, SLAB_H);
  const rng = createRng(seed);
  const base = new THREE.Color(color);
  const tint = new THREE.Color(accent);

  const slabs: Slab[] = [];
  const span = Math.max(count - 1, 1);

  for (let i = 0; i < count; i += 1) {
    const t = i / span;
    const material = new THREE.MeshBasicMaterial({
      color: base.clone().lerp(tint, t),
      transparent: true,
      opacity: 0.34 + 0.46 * t,
      side: THREE.DoubleSide,
      // The slabs are flat and stacked along Y with nothing between them, so
      // the transparent pass sorted back to front is already correct. Writing
      // depth would let the upper slabs clip the lower ones they overhang.
      depthWrite: false,
    });
    const mesh = new THREE.Mesh(geometry, material);
    const k = 0.66 + rng() * 0.46;
    mesh.scale.set(k, k, 1);
    mesh.position.y = (i - span / 2) * GAP;
    scene.add(mesh);
    slabs.push({ mesh, material });
  }

  el.appendChild(renderer.domElement);
  renderer.domElement.style.display = 'block';
  renderer.domElement.style.width = '100%';
  renderer.domElement.style.height = '100%';

  const resize = (w: number, h: number) => {
    renderer.setSize(w, h, false);
    camera.aspect = w / Math.max(h, 1);
    camera.updateProjectionMatrix();
    dirty.current = true;
  };
  resize(size.current.width, size.current.height);

  // Seed the scene from the PRESERVED phase before the first draw. Under
  // Activity this is wherever the stack was when it went away; under a
  // conditional the ref is new and this reads zero. Doing it before the
  // timed draw also means the resumed frame is correct on frame one, with
  // no snap from zero to the real angle.
  for (let i = 0; i < slabs.length; i += 1) {
    const slab = slabs[i];
    if (slab) slab.mesh.rotation.set(-Math.PI / 2, 0, phase.current + i * TWIST);
  }
  renderer.render(scene, camera);

  builds.current += 1;
  buildMs.current = performance.now() - t0;

  stage.current = { renderer, scene, camera, slabs, geometry, resize };
  report(true);

  return () => {
    stage.current = null;
    for (const slab of slabs) {
      scene.remove(slab.mesh);
      slab.material.dispose();
    }
    geometry.dispose();
    // Not optional. `dispose()` alone leaves the context alive and counting
    // against the per-process budget; only `forceContextLoss()`, which
    // `disposeRenderer` calls, actually gives it back. Every hide runs this.
    disposeRenderer(renderer);
    renderer.domElement.remove();
  };
}, [ready, count, color, accent, seed, report]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The Effect removes each slab and disposes its material, disposes the one shared geometry, calls `disposeRenderer` — which stops the loop, disposes the renderer and calls `forceContextLoss()` — and removes the canvas it appended. This runs on unmount, on a StrictMode double-invoke, and on every Activity hide, so it is exercised constantly rather than once. `useRaf` unsubscribes and the shared loop parks when its last subscriber leaves; the `ResizeObserver` unobserves with its hook. A separate Effect reports the scene as gone on teardown so the readout does not freeze on a stale row.

**Reduced motion.** The stack holds still — the phase is integrated from delta time, so freezing it is a matter of adding nothing — and with nothing marking the frame dirty the renderer draws once per build and then idles. The demonstration survives the loss of motion because it was never really about the motion: the build counter still climbs under `activity` and stays pinned under `unmount`, and the rebuild cost in milliseconds is still charged on every show. Only the resumed rotation angle stops being informative, since both arms sit at zero degrees.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Expecting Activity to keep the WebGL context alive. It does not, by design — Effects are destroyed on hide, so your cleanup runs and the context is released. If you had assumed otherwise and skipped disposal, you leak instead; if you assumed re-showing is free, the rebuild millisecond readout says otherwise.
- Lifting the state you wanted preserved above the boundary. Anything outside the `<Activity>` was never at risk, and anything the parent owns is not evidence of anything. The value has to live on a fiber inside the boundary or the comparison proves nothing.
- Changing the element at the boundary position instead of changing `mode`. Swapping `<Activity>{scene}</Activity>` for `{scene}` reconciles as a different type at that slot, so React unmounts the subtree and every preserved value goes with it. Keep the boundary mounted and toggle `mode`.
- Treating hidden as unrendered. Children keep re-rendering, only at a lower priority, so a parent state update still walks the hidden subtree. Anything expensive in render — not in an Effect — is still paid for while hidden.
- Assuming a ref into hidden DOM behaves the same as a ref into visible DOM. The DOM nodes themselves survive, but ref attachment is part of the layout-effect phase that the offscreen path tears down and replays, and this component does not depend on the answer either way. Do the work in an Effect, which is re-run on show, rather than caching a node in a closure that outlives the hide.
- Handing three's renderer a React-rendered `<canvas ref>`. Cleanup calls `forceContextLoss()`, and the next Effect run — from StrictMode or from a re-show — is given the same dead element. Let the renderer build its own canvas in the Effect and remove it in cleanup.
- Reading the build counter in development and taking the absolute number literally. StrictMode double-invokes Effects on mount, so the first build reads 2, not 1. The claim to check is the shape: climbing under `activity`, pinned under `unmount`.

## Notes

- `Activity` is exported from `react` from 19.2 (verified against 19.2.8: `exports.Activity = REACT_ACTIVITY_TYPE`, typed as `ExoticComponent<ActivityProps>` with `mode?: "hidden" | "visible"`). On anything older the import is undefined at runtime, not a build error, which fails as a blank subtree.
- The strongest real use is not a canvas at all — it is a tab, a route the user is likely to come back to, or a filter panel: scroll offsets, uncontrolled input values and list virtualisation windows are all preserved for free, and none of them cost a GPU context to rebuild.
- Pre-rendering the other direction, `mode="hidden"` on a subtree that has never been visible, mounts it at low priority without running Effects. Useful for warming a route, useless for warming a renderer, for the same reason as above.

## Definition of done

On `activity`: press hide, wait, press show. The stack picks up at the angle the readout froze at, `builds` has gone up by one, and the rebuild cost is a real number of milliseconds. On `unmount`: the same sequence returns the stack to zero degrees and `builds` never moves. Hide on either arm and the canvas is gone from the DOM inspector under `unmount` but present with `display: none` under `activity`. Neither arm accumulates WebGL contexts — toggle twenty times and the other previews on the page stay drawn.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Percent Slide Carousel

The simplest slide carousel that is still correct. A flex track holds one full-width slide per child and translates by `-100% * index`; because a percentage translate resolves against the translated element's own width, and the track is exactly one viewport-box wide, one step is exactly one slide. Nothing is measured, so nothing goes stale on resize.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A flex track translated by -100% per slide. One CSS transition, no measurement, no library.

- Category: layout
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. The viewport box is `overflow: hidden`. Inside it a flex track is `h-full w-full`, and every slide is `w-full shrink-0` — full width of the *track*, not of the flex line, so `count` slides overflow the track by `count - 1` widths instead of being compressed into it.
2. The track carries `transform: translateX(-${100 * index}%)`. A percentage in `translateX` is relative to the border box of the element being transformed, which is the track, whose width equals the viewport box, which equals one slide. So `-100%` is one slide exactly, with no numbers taken from layout.
3. That is the whole reason to prefer this over a pixel translate: a pixel offset needs a measured slide width, which needs a resize observer, which needs a re-measure pass that can land a frame late and show a seam. Here a resize changes the meaning of `100%` on the next paint for free.
4. The transition is `transform 600ms cubic-bezier(0.22, 1, 0.36, 1)` on the track only. Interrupting it mid-flight is handled by the compositor: the browser retargets from the current computed transform, so rapid clicks chain smoothly rather than restarting from the last committed index.
5. Navigation clamps rather than wraps by default. `-100% * index` is a linear function of the index with no modulo in it, so a wrap from the last slide to the first would translate the whole track back across every intermediate slide — a visible rewind. `loop` is offered but honest about that.
6. Each slide is a `role="group"` with `aria-roledescription="slide"` and an `aria-label` of `n of N`, so a screen reader announces position without the component owning any live region.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `duration = 600`
  Milliseconds for a full slide. Under ~350 ms a full-width traversal reads as a cut rather than a move and the eye loses which direction it went; over ~900 ms a rapid click-through feels blocked because each step is still finishing when the next arrives.
- `EASE = cubic-bezier(0.22, 1, 0.36, 1)`
  An expo-out curve: ~80% of the distance is covered in the first third of the duration. On a full-viewport traversal that front-loading is what keeps a 600 ms move from feeling slow, while the long flat tail hides the exact moment the slide lands.
- `translate step = 100%`
  Locked to the slide width by construction, not by choice. Any other value desynchronises the track from the slides and leaves a permanent sliver of the neighbour visible at rest.
- `shrink-0 on slides = flex-shrink: 0`
  Without it flexbox honours the container width and squeezes every slide to `1/count` of the track. The translate still moves a full track-width, so one click jumps `count` slides — the single most common way this pattern breaks.
- `loop = false`
  Default off. With a linear percentage translate there is no cheap wrap: going from the last index to 0 animates back through every slide. If you need a true loop, reach for the drum instead.

## API

```ts
function PercentSlideCarousel(props: { children: ReactNode; duration?: number; index?: number; defaultIndex?: number; onIndexChange?: (index: number) => void; loop?: boolean; className?: string; slideClassName?: string; "aria-label"?: string }): JSX.Element
```

- `children: ReactNode`
  One slide per child. Each is wrapped in a full-width, non-shrinking cell.
- `duration: number` — default `600`
  Slide transition duration in milliseconds.
- `index: number`
  Controlled index. Omit to let the component hold its own state.
- `defaultIndex: number` — default `0`
  Starting index when uncontrolled.
- `onIndexChange: (index: number) => void`
  Fires with the resolved index after clamping or wrapping.
- `loop: boolean` — default `false`
  Wrap past the ends. Off by default because the wrap animates backwards through every slide.
- `className: string`
  Merged onto the viewport box.
- `slideClassName: string`
  Merged onto every slide cell.
- `aria-label: string` — default `'Carousel'`
  Label for the carousel group.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const trackStyle = {
  // One slide is one track-width, so the step is exactly 100%. This is the
  // only carousel arithmetic that needs no numbers from layout at all.
  transform: `translateX(-${100 * current}%)`,
  // No transition under reduced motion: the slide still changes, it just
  // arrives instantly. Cutting the movement is the point; cutting the
  // navigation would be a bug.
  transition: reduced ? 'none' : `transform ${duration}ms ${EASE}`,
};
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nothing to clean up. No listeners, no timers, no animation frames, no imperative writes to the DOM; the only state is the current index and the browser owns the transition.

**Reduced motion.** The track transition is set to `none`, so the slide changes on the next paint with no traversal. Navigation, focus order and the announced position are untouched — only the movement between slides is removed.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Omitting `flex-shrink: 0` on the slides. Flexbox compresses them to fit the track, the `-100%` step no longer equals one slide, and the carousel advances by the whole set on the first click.
- Putting the transition on the slides instead of the track. Only the track moves; a transition on the children costs a style recalculation per slide per frame and animates nothing.
- Translating in pixels from a measured slide width. It works until the container resizes between the measure and the paint, at which point the track is offset by the difference and every slide sits a few pixels off-centre until the next navigation.
- Wrapping the index with a modulo and expecting a loop. `-100% * 0` after `-100% * (n - 1)` animates the whole track backwards past every slide; users read it as the carousel malfunctioning, not as a wrap.
- Marking off-screen slides `aria-hidden` while they still contain focusable children. Tab lands inside a hidden subtree, which is an accessibility violation and, in practice, scrolls the overflow container sideways and desynchronises it from the transform.
- Forgetting `overflow: hidden` on the viewport box. The overflowing slides remain visible, and inside a page-level container they widen the document and add a horizontal scrollbar.
- Killing the transition under reduced motion but also killing the index change. The slide must still change — reduced motion removes the traversal, not the navigation.

## Notes

- This is the flat, non-3D member of the carousel trio. `wrapping-drum-carousel` fakes depth with scale and `autoAlpha` over a `gsap.utils.wrap` ring and loops infinitely; `perspective-coverflow-scroller` uses real `perspective()` / `rotateY()` / `translateZ()` driven by a native scroll container. This one has no depth, no wrap and no JavaScript in the motion path at all — reach for it when the content is the point and the carousel is not.
- Because the motion is a single compositor-friendly transform on one element, it holds 60 fps on hardware where the other two do not. If you are shipping a hero on a low-end phone, this is the one that survives.
- Controlled and uncontrolled: pass `index` to drive it from outside, omit it and the component keeps its own state. `onIndexChange` fires in both cases.

## Definition of done

Click next and exactly one slide traverses the box in 600 ms with no neighbour visible at rest. Hold the next button down and the slides chain without restarting from the previous index. Resize the container mid-transition and the resting position stays flush with the box edges. At the last slide the next button is disabled unless `loop` is set. With reduced motion the slide changes instantly and the buttons still work.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Perspective Coverflow Scroller

A horizontal `overflow-x-auto` container with `scroll-snap-type: x proximity`. Each panel's distance from the centre of the viewport is normalised to roughly ±1 and mapped onto a per-element `perspective() translateZ() rotateY() scale()`, so panels turn their inside edge toward you as they leave the middle. The scroll position itself is never animated by JavaScript — momentum, rubber-banding and keyboard paging are the browser's.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Panels turn away from the centre in real 3D as you scroll a native container — no tween, no loop.

- Category: layout
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. A measure pass caches each panel's layout centre as `panel.offsetLeft + panel.offsetWidth / 2` and sets the track's left and right padding to `(scroller.clientWidth - endPanel.offsetWidth) / 2`, which is exactly enough runway for the first and last panel to reach the middle of the viewport.
2. On every coalesced scroll frame, the normalised offset is `r = clamp((centre - scrollLeft - half) / half, -1.2, 1.2)` where `half = scroller.clientWidth / 2`. `r = 0` is dead centre, `r = ±1` is one half-viewport out.
3. That single scalar drives four things: `rotateY = -rotation * r` (negative, so a panel on the right turns its left edge toward you — the flip-book read), `translateZ = -depth * |r|` (always receding), `scale = 1 - scaleFalloff * min(|r|, 1)`, and `opacity = 1 - opacityFalloff * min(|r|, 1.2)`.
4. `perspective(1300px)` is written inside each panel's own transform rather than as a `perspective` property on the track. A shared parent perspective gives every panel the same vanishing point, so panels near the edges skew as well as rotate; per-element perspective turns each panel about its own centre.
5. The two clamps differ on purpose — `min(|r|, 1)` for scale and `min(|r|, 1.2)` for opacity — so distant panels keep their proportions while continuing to fade out.
6. A `ResizeObserver` on the track re-runs the measure pass whenever content size changes (a font swap, a child growing), which is the deterministic replacement for the usual pile of `setTimeout(recompute, 300)` calls.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `perspective = 1300`
  Per-element perspective distance in px. Under ~700 the foreshortening is strong enough that a 40° turn hides most of the panel; over ~2000 the rotation flattens out and reads as a skew rather than a turn.
- `rotation = 40`
  Degrees of `rotateY` at the clamp. 40° is the point where the panel is visibly turned but still legible; past ~55° it is close enough to edge-on that text disappears and antialiasing on the near edge gets ugly.
- `depth = 130`
  Pixels of `translateZ`, always negative so off-centre panels recede. Combined with the rotation this is what makes the row read as the inside of a cylinder rather than a fanned deck. At 0 you get a pure hinge; past ~250 the far panels shrink faster than `scaleFalloff` intends and the two cues disagree.
- `scaleFalloff = 0.12`
  A panel at one half-width out renders at 0.88. Kept small because `translateZ` is already shrinking it perspectivally — stacking a large explicit scale on top double-counts the distance.
- `opacityFalloff = 0.35`
  The edge panels land near 0.58, not 0. They must stay readable, because on a proximity-snap track they are the affordance that tells you there is more to scroll to.
- `maxOffset = 1.2`
  Clamp on `r`. Without it, a long track keeps rotating panels past 90° and they flip to their back faces; 1.2 rather than 1.0 leaves a little travel past the half-width mark so the outermost visible panels are not all frozen at an identical angle.

## API

```ts
function PerspectiveCoverflowScroller(props: { children: ReactNode; perspective?: number; rotation?: number; depth?: number; scaleFalloff?: number; opacityFalloff?: number; maxOffset?: number; initialIndex?: number; className?: string; panelClassName?: string; 'aria-label'?: string }): JSX.Element
```

- `children: ReactNode`
  One panel per child. Each is wrapped in a snap-aligned cell.
- `perspective: number` — default `1300`
  Per-element perspective distance in px.
- `rotation: number` — default `40`
  Degrees of `rotateY` at the clamp.
- `depth: number` — default `130`
  Pixels of `translateZ` at the clamp. Applied negatively, so panels recede.
- `scaleFalloff: number` — default `0.12`
  How much a panel shrinks one half-viewport out.
- `opacityFalloff: number` — default `0.35`
  How much a panel fades one half-viewport out.
- `maxOffset: number` — default `1.2`
  Clamp on the normalised offset, so distant panels stop turning further.
- `initialIndex: number`
  Panel centred on mount. Defaults to the middle of the set.
- `className: string`
  Merged onto the scroll container.
- `panelClassName: string`
  Merged onto each snap cell. Size the panels here.
- `aria-label: string` — default `'Gallery'`
  Label for the scrollable region, which is focusable for keyboard scrolling.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * Cache each panel's layout centre and pad the track so the first and last
 * panel can reach the middle of the viewport.
 *
 * `offsetLeft`/`offsetWidth` are *layout* values: unaffected by `scrollLeft`
 * and, critically, unaffected by the transforms this component writes.
 * Reading `getBoundingClientRect()` in the scroll handler instead would feed
 * each panel's own `scale()` back into the next frame's offset.
 */
const measure = useCallback(() => {
  const scroller = scrollerRef.current;
  const track = trackRef.current;
  if (!scroller || !track) return;

  const panels = panelsRef.current;
  const first = panels[0];
  const last = panels[count - 1];

  // Half a viewport minus half a panel. The source of this technique used a
  // fixed `24vw`, which is wrong for any panel that is not ~52vw wide and
  // wrong for every container that is not the viewport.
  if (first) {
    track.style.paddingLeft = `${Math.max(0, (scroller.clientWidth - first.offsetWidth) / 2)}px`;
  }
  if (last) {
    track.style.paddingRight = `${Math.max(0, (scroller.clientWidth - last.offsetWidth) / 2)}px`;
  }

  // Read after the padding write: the padding moves every offsetLeft.
  centresRef.current = panels.map((panel) =>
    panel ? panel.offsetLeft + panel.offsetWidth / 2 : 0,
  );
}, [count]);

/** Write one transform per panel from the current scroll position. */
const update = useCallback(() => {
  const scroller = scrollerRef.current;
  if (!scroller) return;

  const half = scroller.clientWidth / 2 || 1;
  const scroll = scroller.scrollLeft;
  const panels = panelsRef.current;
  const centres = centresRef.current;

  for (let i = 0; i < panels.length; i += 1) {
    const panel = panels[i];
    const centre = centres[i];
    if (!panel || centre === undefined) continue;

    if (reduced) {
      panel.style.transform = '';
      panel.style.opacity = '';
      continue;
    }

    // Signed, normalised distance from the viewport centre: -1 = one half
    // width to the left, +1 = one half width to the right.
    const r = clamp((centre - scroll - half) / half, -maxOffset, maxOffset);
    const away = Math.abs(r);

    // Perspective lives *in the transform*, not on the parent. A shared
    // parent perspective gives every panel the same vanishing point, so
    // edge panels skew as well as rotate; per-element perspective turns each
    // panel about its own centre, which is the coverflow look.
    panel.style.transform =
      `perspective(${perspective}px) ` +
      `translateZ(${(-depth * away).toFixed(1)}px) ` +
      `rotateY(${(-rotation * r).toFixed(2)}deg) ` +
      `scale(${(1 - scaleFalloff * Math.min(away, 1)).toFixed(3)})`;

    // Two different clamps on purpose: scale bottoms out at 1, opacity keeps
    // going to `maxOffset`. Distant panels stay proportionate while fading.
    panel.style.opacity = (1 - opacityFalloff * Math.min(away, maxOffset)).toFixed(2);
  }
}, [reduced, perspective, rotation, depth, scaleFalloff, opacityFalloff, maxOffset]);

useEffect(() => {
  const scroller = scrollerRef.current;
  if (!scroller) return;

  measure();

  // Start centred on a panel, not on the midpoint of the scroll range: with
  // an even count the midpoint falls in the gap between two panels and the
  // component opens looking like nothing is selected.
  if (!centredRef.current && count > 0) {
    const target = initialIndex ?? Math.floor((count - 1) / 2);
    const centre = centresRef.current[clamp(Math.round(target), 0, count - 1)];
    if (centre !== undefined) {
      scroller.scrollLeft = centre - scroller.clientWidth / 2;
    }
    centredRef.current = true;
  }

  update();

  let frame = 0;
  const onScroll = () => {
    // Coalesce: a trackpad fires `scroll` far more often than the compositor
    // paints, and each handler run writes N transforms.
    if (frame !== 0) return;
    frame = requestAnimationFrame(() => {
      frame = 0;
      update();
    });
  };

  scroller.addEventListener('scroll', onScroll, { passive: true });

  return () => {
    scroller.removeEventListener('scroll', onScroll);
    if (frame !== 0) cancelAnimationFrame(frame);
  };
}, [measure, update, count, initialIndex]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the `scroll` listener, cancels any pending `requestAnimationFrame`, and disconnects the track `ResizeObserver`. The shared element observer unregisters the scroller. Inline `transform`/`opacity` written on panels dies with the nodes; no timer or tween outlives the component.

**Reduced motion.** The scroller keeps working exactly as it did — it is a real scroll container, and scrolling is user-driven, not animation. What is removed is the 3D: `transform` and `opacity` are cleared on every panel, so the row renders as a flat, fully opaque filmstrip that still snaps by proximity. Nothing moves that the user did not move.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Computing the offset from `getBoundingClientRect()`. The rect reflects the transform this component just wrote, so each panel's `scale()` feeds back into the next frame's offset and the row slowly drifts to a wrong steady state. `offsetLeft`/`offsetWidth` are layout values — untouched by transforms and by `scrollLeft`.
- Putting `perspective` on the track instead of in each panel's transform. Every panel then shares one vanishing point, so the ones near the edges skew into parallelograms instead of turning.
- Handling `scroll` without coalescing into a frame. A trackpad fires scroll events considerably faster than the compositor paints, and every run writes N style strings for no visible benefit.
- Padding the track with a viewport unit like `24vw`. It is correct for exactly one panel width and one container width; inside a card, a modal or a split layout the end panels can never reach the centre and are permanently unselectable.
- Setting `scroll-snap-type: x mandatory`. Release between two panels and the browser yanks you to one of them, which fights every attempt to scan the row. `proximity` snaps only when you were already close.
- Starting at `scrollLeft = 0`. The first panel is then hard against the left edge with nothing to its left, so the effect is invisible until the user scrolls. Centring on a panel on mount shows the technique in both directions immediately.
- Re-centring on every resize. `scrollLeft` is only assigned once, guarded by a ref — otherwise rotating a phone, or any resize during a scroll, teleports the user back to the middle mid-gesture.

## Notes

- One of three deliberately different carousel techniques here, and the distinctions are the point. This one is **true 3D on a native scroll container**: actual `rotateY` and `translateZ`, and no JavaScript animation drives the scroll at all — the handler only reads a position the browser already set. `wrapping-drum-carousel` is **fake 3D** driven by a tweened JS position with `rotationY: 0, z: 0` pinned, and wraps infinitely via `gsap.utils.wrap`. `percent-slide-carousel` is **flat, bounded, one CSS transition per index change**.
- Choose this one when the set is long, scanning matters more than stepping, and you want native momentum and keyboard support for free. It cannot loop: a native scroll container has real ends.
- Because the panels rotate in 3D, text inside them is composited on a rotated plane and will look softer than flat text. That is inherent to the technique, not a bug to tune away; keep small type out of the panels or accept it.

## Definition of done

On mount a panel sits centred and the ones either side are visibly turned toward it. Drag or trackpad-scroll and the turn follows continuously with no lag and no snap-back; release near a panel and it snaps, release between two and it does not. Scroll to either end and the outermost panel reaches the exact centre of the container. Resize the container and the end padding recomputes so it still can.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Pinned Horizontal Track

A full-height section is pinned by ScrollTrigger while a flex strip inside it translates on x. The pin lasts exactly as many scroll pixels as the strip has to travel, so the mapping is 1:1 and the section releases the moment the last panel lands. The tween and the trigger are handed back to the parent, so reveal systems and drag handles can drive off the same pin instead of building a second one.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A section pins while a strip of panels slides sideways, one scroll pixel per track pixel.

- Category: scroll
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. One measurement backs the whole construction: `distanceOf() = max(0, track.scrollWidth - root.clientWidth)`. It is a function, not a captured number, because fonts, images and container resizes all change it after first paint.
2. `gsap.to(track, { x: () => -distanceOf(), ease: "none" })` uses a function-based end value, so `invalidateOnRefresh: true` re-derives the travel on every refresh rather than replaying a stale target.
3. The ScrollTrigger pins the root with `start: "top top"` and `end: () => "+=" + distanceOf()`. Because the pin duration and the tween distance come from the same call, one scroll pixel always buys one track pixel.
4. `scrub: 1` gives the strip one second of catch-up, so a flicked wheel produces a glide rather than a jump; `anticipatePin: 1` lets ScrollTrigger apply the pin a frame early, which removes the single-frame jitter at high scroll speeds.
5. `document.fonts.ready` triggers `ScrollTrigger.refresh()`. A font swap changes `scrollWidth` after the pin was measured, and without the refresh the pin ends before the track does — the last panel is unreachable.
6. On build the component calls `onTrack({ animation, trigger, getDistance })`; on teardown it calls `onTrack(null)`, so consumers rebuild rather than holding a reverted tween.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `scrub = 1`
  Seconds of catch-up between the scrollbar and the strip. `true` (0) locks the track to the scrollbar and inherits every wheel step as a visible stutter; above ~1.5 the track keeps moving long after the wheel stops and reads as broken input.
- `anticipatePin = 1`
  Applies the pin one frame of predicted scroll early. At 0, a fast flick pins one frame late and the section visibly slips before locking. Above 1 it pins early enough to look premature.
- `end = `+=${max(1, distanceOf())}``
  Pin duration in pixels, equal to the horizontal travel. The `max(1, …)` floor exists because a track narrower than its container yields 0, and an end equal to start makes ScrollTrigger treat the trigger as degenerate and never fire it.

## API

```ts
function PinnedHorizontalTrack(props: { children: ReactNode; scroller?: RefObject<HTMLElement | null>; scrub?: number; onTrack?: (track: PinnedTrack | null) => void; className?: string; trackClassName?: string }): JSX.Element
```

- `children: ReactNode`
  Panels. The track is a flex row, so give each panel a width and `shrink-0`.
- `scroller: RefObject<HTMLElement | null>`
  The scroll container the trigger reads. Omit to use the document.
- `scrub: number` — default `1`
  Seconds of catch-up between scrollbar and strip.
- `onTrack: (track: PinnedTrack | null) => void`
  Receives `{ animation, trigger, getDistance }` on build and `null` on teardown.
- `className: string`
  Merged onto the pinned root.
- `trackClassName: string`
  Merged onto the moving strip.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function PinnedHorizontalTrack({
  children,
  scroller,
  scrub = 1,
  onTrack,
  className,
  trackClassName,
}: PinnedHorizontalTrackProps) {
  const root = useRef<HTMLDivElement>(null);
  const track = useRef<HTMLDivElement>(null);
  const onTrackRef = useRef(onTrack);
  onTrackRef.current = onTrack;
  const reduced = useReducedMotion();

  useEffect(() => {
    const rootEl = root.current;
    const trackEl = track.current;
    if (!rootEl || !trackEl || reduced) return;

    // `undefined` means "the document" to ScrollTrigger. Passing `null` would
    // be read as an explicit scroller and throw on the first refresh.
    const scrollerEl = scroller?.current ?? undefined;

    // The single source of truth. Both the tween's end value and the pin's
    // duration call it, so a refresh that changes one changes the other.
    const distanceOf = () => Math.max(0, trackEl.scrollWidth - rootEl.clientWidth);

    let cancelled = false;

    const ctx = gsap.context(() => {
      const animation = gsap.to(trackEl, {
        // Function-based value: re-evaluated by `invalidateOnRefresh`.
        x: () => -distanceOf(),
        ease: 'none',
        scrollTrigger: {
          trigger: rootEl,
          scroller: scrollerEl,
          pin: true,
          anticipatePin: 1,
          scrub,
          start: 'top top',
          // 1 px of scroll buys 1 px of track. Expressing the end as a
          // percentage of viewport height instead makes the mapping depend
          // on window shape, and the track finishes early on a short screen.
          end: () => `+=${Math.max(1, distanceOf())}`,
          invalidateOnRefresh: true,
        },
      });

      const trigger = animation.scrollTrigger;
      if (trigger) {
        onTrackRef.current?.({ animation, trigger, getDistance: distanceOf });
      }
    }, rootEl);

    // The most-forgotten line in scroll-driven layout. A font swap changes
    // `scrollWidth` after the pin has already been measured, and the last
    // panel becomes unreachable because the pin ends before the track does.
    void document.fonts?.ready.then(() => {
      if (!cancelled) ScrollTrigger.refresh();
    });

    return () => {
      cancelled = true;
      onTrackRef.current?.(null);
      // revert(), not kill(): it also removes the pin-spacer GSAP injected
      // into the DOM and restores the inline transform on the strip.
      ctx.revert();
    };
  }, [scroller, scrub, reduced]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Calls `onTrack(null)` so consumers drop their reference, then `ctx.revert()`, which kills the tween and the ScrollTrigger, removes the injected pin-spacer, and clears the inline transform from the strip. A pending `document.fonts.ready` refresh is gated behind a `cancelled` flag.

**Reduced motion.** No ScrollTrigger and no pin are created. The root becomes a horizontally scrollable row, so the same panels are still read left to right — under the reader's own control, at the reader's own speed.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Measuring `scrollWidth - clientWidth` once into a variable. Fonts swap after first paint and the number grows; the pin then ends before the track has finished travelling and the final panel can never be reached.
- Expressing `end` as a percentage of viewport height (`"+=" + distance * 100 / innerWidth + "%"`). It works on the machine it was tuned on and finishes the track early on a shorter screen, because the mapping now depends on window shape rather than on the travel itself.
- Passing `scroller: null` when the component sits on the page rather than in a box. ScrollTrigger reads `null` as an explicit scroller element and throws on the first refresh; omit the option instead, which is why the code coalesces to `undefined`.
- Calling `kill()` instead of `revert()` on unmount. `kill()` leaves the pin-spacer div GSAP injected into the DOM and the inline transform on the strip, so the next mount measures a layout that still contains the last one.
- Forgetting that a pinned element inside a custom scroller needs that scroller passed explicitly. Without it, ScrollTrigger measures the document, the trigger never becomes active inside the box, and the panels sit motionless.

## Notes

- Under `prefers-reduced-motion: reduce` no trigger is created at all and the strip becomes a native `overflow-x-auto` row, so every panel stays reachable by thumb, trackpad and keyboard.
- `gsap.registerPlugin(ScrollTrigger)` runs once at module scope behind a `typeof window` guard, so repeated imports are harmless and prerender never touches the plugin.

## Definition of done

Scroll down: the section locks, the panels slide left, and the last panel reaches the right edge at exactly the moment the section unpins. Resize the container mid-pin and the track still ends flush. With reduced motion on, the section never pins and the panels can be swiped sideways instead.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Pointer Palette Sampling

A surface you paint into a 2D canvas, plus a pointer that reads the pixel underneath it and snaps that read to the nearest entry in a named palette. The colour comes out as a CSS custom property on the root and as a throttled callback, so a chip can follow the cursor with no JavaScript per frame. It turns a palette from a legend you read into something you find by pointing.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Point at the artwork and it names the colour — a clamped pixel read snapped to the nearest palette entry.

- Category: cursor
- Runtime cost: canvas2d
- Dependencies: none beyond React

## How it works

1. The canvas is created with `document.createElement` inside the effect and appended to the root, not rendered with a React `ref`. `willReadFrequently` is only honoured on the first `getContext` for a given canvas, so the element and the context have to share one lifecycle — under StrictMode a rendered canvas survives the mount/unmount/remount cycle while the context does not.
2. On resize the backing store is set to `round(cssSize * min(devicePixelRatio, 2))` and the transform re-applied with `setTransform(dpr, 0, 0, dpr, 0, 0)`, in that order, because assigning `canvas.width` resets both the bitmap and the transform. The consumer's `paint` then draws in CSS pixels.
3. A `pointermove` converts client coordinates to bitmap coordinates with the canvas's own backing ratio — `canvas.width / rect.width` — rather than `devicePixelRatio`, so browser zoom and any CSS scale on an ancestor stay correct.
4. A 3x3 box centred on that pixel is clamped to `[0, canvas.width - 1]` and `[0, canvas.height - 1]`, then read in one `getImageData` call. The nine samples are averaged with alpha as the weight, so a dithered or grainy surface produces a stable colour instead of oscillating between two palette entries.
5. The average and every palette hex are converted sRGB → linear → OKLab, and the match is the smallest squared OKLab distance. Nearest-colour in raw RGB is dominated by the green channel and routinely calls a mid blue "black".
6. The match is written to `--kx-sample-color` on the root immediately, along with `--kx-sample-x` / `--kx-sample-y` in CSS pixels, and emitted through `onSample` on a throttle — position is a cursor and must not lag, colour is information and must not spam.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `willReadFrequently = true`
  A default 2D context lives in GPU memory, and each `getImageData` forces a synchronous readback that stalls the pipeline — on a pointermove that is a visible drag on the cursor. The flag moves the surface to a software backing: paint is marginally slower, reads are roughly an order of magnitude faster.
- `SAMPLE_BOX = 3`
  Odd, so the box centres on the pointer's own pixel. One pixel flickers between neighbouring palette entries over any gradient dither; 3x3 is enough to settle it, and 5x5 starts averaging across a real colour boundary so edges read as a colour that is not on screen.
- `MAX_DPR = 2`
  Sampling cost is per read and does not care, but paint cost is per pixel. A 3x display would quadruple the fill work relative to 1.5x for no perceptible gain on a flat-colour artwork.
- `throttleMs = 50`
  Matches the source. Fast enough that dragging across the artwork feels continuous, slow enough that a React consumer re-rendering a swatch on every emission stays under one render per three frames.
- `alpha weight = data[i + 3] / 255`
  Transparent pixels carry no colour but their RGB is usually zero, so an unweighted mean over a partly-transparent box returns something darker than anything visible. Weighting by alpha, and bailing when the total is zero, keeps the answer to what was actually painted.

## API

```ts
function PointerPaletteSampling(props: { palette: readonly PaletteEntry[]; paint: (ctx: CanvasRenderingContext2D, size: { width: number; height: number; dpr: number }) => void; paintKey?: string | number; onSample?: (entry: PaletteEntry | null) => void; throttleMs?: number; children?: ReactNode; className?: string }): JSX.Element
```

- `palette: readonly PaletteEntry[]`
  Named colours the read snaps to. `{ name, hex }`, `#rgb` or `#rrggbb`.
- `paint: (ctx, size) => void`
  Draws the surface. Context is pre-scaled and cleared, so draw in CSS pixels. Must not draw a cross-origin image.
- `paintKey: string | number`
  Bump to force a repaint when the painter's inputs change. The painter itself is read through a ref, so an inline arrow is safe.
- `onSample: (entry: PaletteEntry | null) => void`
  Throttled match. `null` when the pointer leaves.
- `throttleMs: number` — default `50`
  Minimum gap between emissions.
- `children: ReactNode`
  Overlay content, rendered in a positioned layer above the canvas.
- `className: string`
  Merged onto the root. Give it a size.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
function parseHex(hex: string): readonly [number, number, number] | null {
  const raw = hex.trim().replace(/^#/, '');
  const full =
    raw.length === 3
      ? raw
          .split('')
          .map((c) => c + c)
          .join('')
      : raw;
  if (!/^[0-9a-fA-F]{6}$/.test(full)) return null;
  const n = Number.parseInt(full, 16);
  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
}

function srgbToLinear(channel: number): number {
  const v = channel / 255;
  return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
}

/**
 * sRGB to OKLab. Nearest-colour in raw RGB is the usual shortcut and it is
 * wrong in a way users notice: RGB distance is dominated by green, so a mid
 * blue reads closer to black than to a lighter blue. OKLab is perceptually
 * uniform, so "nearest" means what the eye means.
 */
function rgbToOklab(r: number, g: number, b: number): Oklab {
  const lr = srgbToLinear(r);
  const lg = srgbToLinear(g);
  const lb = srgbToLinear(b);

  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);

  return [
    0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
  ];
}

export function PointerPaletteSampling({
  palette,
  paint,
  paintKey,
  onSample,
  throttleMs = 50,
  children,
  className,
}: PointerPaletteSamplingProps) {
  const root = useRef<HTMLDivElement>(null);
  const { width, height } = useResizeObserver(root);
  const reduced = useReducedMotion();

  // The canvas is created imperatively rather than rendered with a `ref`.
  // Under StrictMode a rendered canvas is the same element across the
  // mount / unmount / remount cycle, so the second mount inherits a context
  // whose `willReadFrequently` was decided on the first `getContext` — and any
  // teardown that disposes the context leaves the survivor holding a dead one.
  // Owning the element per effect run makes the two lifecycles the same.
  const [surface, setSurface] = useState<{
    canvas: HTMLCanvasElement;
    ctx: CanvasRenderingContext2D;
  } | null>(null);

  // Read through refs so an inline painter or handler does not tear the canvas
  // down on every parent render.
  const paintRef = useRef(paint);
  const sampleRef = useRef(onSample);
  useEffect(() => {
    paintRef.current = paint;
    sampleRef.current = onSample;
  });

  /** Palette in OKLab, computed once. Entries with an unparseable hex drop out. */
  const swatches = useMemo(() => {
    const out: { entry: PaletteEntry; lab: Oklab }[] = [];
    for (const entry of palette) {
      const rgb = parseHex(entry.hex);
      if (!rgb) continue;
      out.push({ entry, lab: rgbToOklab(rgb[0], rgb[1], rgb[2]) });
    }
    return out;
  }, [palette]);

  /* Mount the canvas. */
  useEffect(() => {
    const rootEl = root.current;
    if (!rootEl) return;

    const canvas = document.createElement('canvas');
    canvas.setAttribute('aria-hidden', 'true');
    canvas.style.cssText =
      'position:absolute;inset:0;display:block;width:100%;height:100%';

    // The one call where the flag counts.
    const ctx = canvas.getContext('2d', { willReadFrequently: true });
    if (!ctx) return;

    rootEl.appendChild(canvas);
    setSurface({ canvas, ctx });

    return () => {
      canvas.remove();
      // Guard the swap: on a StrictMode remount the next effect has already
      // published its canvas by the time this cleanup runs in some orderings.
      setSurface((current) => (current?.canvas === canvas ? null : current));
    };
  }, []);

  /* Size and paint. */
  useEffect(() => {
    if (!surface || width <= 0 || height <= 0) return;
    const { canvas, ctx } = surface;

    const dpr = Math.min(
      typeof window === 'undefined' ? 1 : window.devicePixelRatio || 1,
      MAX_DPR,
    );
    // Assigning width or height resets the bitmap AND the transform, so the
    // scale has to be re-applied after, never before.
    canvas.width = Math.max(1, Math.round(width * dpr));
    canvas.height = Math.max(1, Math.round(height * dpr));
    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
    ctx.clearRect(0, 0, width, height);

    paintRef.current(ctx, { width, height, dpr });
  }, [surface, width, height, paintKey]);

  /* Sample. */
  useEffect(() => {
    const rootEl = root.current;
    if (!rootEl || !surface || swatches.length === 0) return;
    const { canvas, ctx } = surface;

    let timer: ReturnType<typeof setTimeout> | null = null;
    let pendingIsClear = false;

    /**
     * The source's throttle, kept verbatim in behaviour: while an emission is
     * pending, a new colour is DROPPED rather than queued, so the consumer sees
     * one colour per window instead of a burst at the end of one. The single
     * exception is that a pending clear may be replaced — re-entering the
     * canvas within the window cancels the leave instead of flickering to
     * nothing and back.
     */
    const emit = (entry: PaletteEntry | null, isClear: boolean) => {
      if (timer !== null && !pendingIsClear) return;
      pendingIsClear = isClear;
      if (timer !== null) clearTimeout(timer);
      timer = setTimeout(() => {
        timer = null;
        pendingIsClear = false;
        sampleRef.current?.(entry);
      }, throttleMs);
    };

    const sampleAt = (clientX: number, clientY: number): PaletteEntry | null => {
      const rect = canvas.getBoundingClientRect();
      if (rect.width <= 0 || rect.height <= 0) return null;

      // Backing ratio, not devicePixelRatio: this is still correct under
      // browser zoom and under a CSS transform on any ancestor.
      const scaleX = canvas.width / rect.width;
      const scaleY = canvas.height / rect.height;

      const px = Math.round((clientX - rect.left) * scaleX);
      const py = Math.round((clientY - rect.top) * scaleY);
      const half = (SAMPLE_BOX - 1) / 2;

      // Clamp to the bitmap. An unclamped box at the right or bottom edge is
      // padded with transparent black, which pulls the average to black.
      const x0 = clamp(px - half, 0, canvas.width - 1);
      const y0 = clamp(py - half, 0, canvas.height - 1);
      const x1 = clamp(px + half, 0, canvas.width - 1);
      const y1 = clamp(py + half, 0, canvas.height - 1);
      const w = x1 - x0 + 1;
      const h = y1 - y0 + 1;
      if (w <= 0 || h <= 0) return null;

      const data = ctx.getImageData(x0, y0, w, h).data;

      // Alpha-weighted mean over the box. A single pixel flickers between two
      // palette entries on any dithered or noisy surface; nine pixels do not.
      let r = 0;
      let g = 0;
      let b = 0;
      let weight = 0;
      for (let i = 0; i + 3 < data.length; i += 4) {
        const a = (data[i + 3] ?? 0) / 255;
        if (a === 0) continue;
        r += (data[i] ?? 0) * a;
        g += (data[i + 1] ?? 0) * a;
        b += (data[i + 2] ?? 0) * a;
        weight += a;
      }
      // Fully transparent: there is no colour here, and dividing would be NaN.
      if (weight <= 0) return null;

      const lab = rgbToOklab(r / weight, g / weight, b / weight);
      let best: PaletteEntry | null = null;
      let bestDistance = Infinity;
      for (const swatch of swatches) {
        const dl = lab[0] - swatch.lab[0];
        const da = lab[1] - swatch.lab[1];
        const db = lab[2] - swatch.lab[2];
        const distance = dl * dl + da * da + db * db;
        if (distance < bestDistance) {
          bestDistance = distance;
          best = swatch.entry;
        }
      }
      return best;
    };

    const onMove = (event: PointerEvent) => {
      const entry = sampleAt(event.clientX, event.clientY);
      if (!entry) return;

      rootEl.dataset.sampling = 'true';
      rootEl.style.setProperty('--kx-sample-color', entry.hex);
      // The colour is throttled because it is information; the position is not,
      // because it is a cursor. Throttling the position makes the readout lag
      // the pointer by up to a frame budget and feel broken.
      if (!reduced) {
        const rect = canvas.getBoundingClientRect();
        rootEl.style.setProperty('--kx-sample-x', `${event.clientX - rect.left}px`);
        rootEl.style.setProperty('--kx-sample-y', `${event.clientY - rect.top}px`);
      }
      emit(entry, false);
    };

    const onLeave = () => {
      rootEl.dataset.sampling = 'false';
      emit(null, true);
    };

    // Pointer events already carry touch; `touch-action: none` on the root
    // stops a drag over the artwork from scrolling the page out from under it.
    rootEl.addEventListener('pointermove', onMove);
    rootEl.addEventListener('pointerdown', onMove);
    rootEl.addEventListener('pointerleave', onLeave);
    rootEl.addEventListener('pointercancel', onLeave);

    return () => {
      rootEl.removeEventListener('pointermove', onMove);
      rootEl.removeEventListener('pointerdown', onMove);
      rootEl.removeEventListener('pointerleave', onLeave);
      rootEl.removeEventListener('pointercancel', onLeave);
      if (timer !== null) clearTimeout(timer);
      timer = null;
      rootEl.dataset.sampling = 'false';
    };
  }, [surface, swatches, throttleMs, reduced]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The canvas element is removed from the DOM in the same effect that created it, which drops the bitmap and the context with it. The four pointer listeners are removed, any pending throttle timer is cleared so no emission lands after unmount, and `data-sampling` is reset. The shared ResizeObserver unsubscribes through the hook.

**Reduced motion.** Sampling is not motion, so it keeps working: the colour still updates and `onSample` still fires. What stops is the chase — `--kx-sample-x` and `--kx-sample-y` are left parked at their initial 50% so a readout pinned to those properties stays still and simply recolours, instead of flying around the frame after the cursor.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Calling `getContext("2d")` first and adding `{ willReadFrequently: true }` later. The attributes of a canvas context are fixed at creation; the second call returns the first context and silently ignores the options, so the optimisation appears to be applied and is not.
- Reading the box unclamped. A pointer on the right or bottom edge produces a rect that overhangs the bitmap — no exception, the overhang is filled with transparent black — so the average darkens and the match snaps to the palette's darkest entry along every border.
- Letting the clamp collapse the rect. `getImageData` with a zero width or height throws `IndexSizeError`, which is what happens on a 1px-wide canvas if the box is clamped naively to a range instead of to an inclusive index pair.
- Converting with `devicePixelRatio` instead of the backing ratio. Correct at 100% zoom on a static layout, then off by the zoom factor the moment the user hits Cmd-plus, and off by the scale factor inside any transformed ancestor.
- Drawing a cross-origin image into the canvas. The canvas is tainted from that draw onward and every `getImageData` throws `SecurityError` — including for the parts of the surface you painted yourself. Paint procedurally, or serve the image same-origin with CORS.
- Matching in RGB. Euclidean distance in sRGB is not perceptual: green outweighs red and blue roughly six to one, so mid-tones snap to the wrong hue and the palette looks mislabelled rather than the maths looking wrong.
- Rendering the canvas as JSX with a `ref` and disposing the context in cleanup. Under StrictMode the element is reused across the double-invoke while the effect runs twice, so the surviving mount holds a context the first teardown already reset.
- Throttling the pointer position along with the colour. The readout then trails the cursor by the throttle window and the whole interaction reads as laggy, even though the sampling itself is instant.

## Notes

- Everything downstream is CSS. `--kx-sample-color` and `--kx-sample-x` / `--kx-sample-y` mean a chip can follow the pointer and recolour itself with no rAF and no React render.
- `data-sampling` on the root is `true` while the pointer is over the artwork, which is the hook for fading the readout in and out.
- Palette entries with an unparseable hex are dropped at match time rather than throwing, so one bad token in a design-token export does not take the interaction down.

## Definition of done

Move the pointer across the artwork: the readout recolours continuously and names a palette entry, with no stutter under a fast drag. Park the cursor exactly on the right or bottom edge — the name must not jump to the darkest colour in the palette. Zoom the browser to 150% and point at the same region; the answer is unchanged. With reduced motion on, the readout stops following the pointer but still renames itself.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Pointer-Variable Gradient

A radial gradient declared once in CSS reads its centre from `--pointer-x` and `--pointer-y`. The pointer handler does nothing but write those two properties as percentages. There is no animation frame, no tween library and no `background` string assembled in JavaScript.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A soft glow tracks the pointer through two CSS custom properties. No rAF, no tween, no string rebuilding.

- Category: cursor
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. The gradient — its size, colour, stops and the layer underneath it — is declared once on the element. The only thing JavaScript ever writes is two custom properties, so the style engine invalidates the paint of one gradient rather than re-parsing a `background` shorthand it has already parsed thousands of times.
2. Values are written as percentages, not pixels. A percentage in a gradient position resolves against the element box, so the glow stays put relative to the panel across a resize with no resize listener and no recomputation — the value that was correct before the resize is still correct after it.
3. There is deliberately no `requestAnimationFrame`. A custom-property write is not a layout read, so there is nothing to batch away from; the browser already coalesces style changes into the next paint. Wrapping this in a frame loop adds one frame of latency and buys nothing measurable.
4. There is deliberately no tween. Smoothing the glow would mean owning a value between the pointer and the gradient, which means a frame loop, which is the cost this component exists to avoid. A 38rem glow is so diffuse that a few pixels of jitter are invisible — the smoothing would be paying for something no one can see.
5. Leaving removes the properties rather than writing the rest position back, so the fallback declared in the inline `style` takes over and the resting position is stated in exactly one place.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `REST_X / REST_Y = '50%' / '38%'`
  Where the glow sits before any pointer has been seen, and where it returns to on leave. Slightly above centre because a glow that sits dead-centre behind a headline reads as a lighting mistake, while one a little high reads as a source above the frame.
- `glowWidth / glowHeight = '38rem' / '30rem'`
  Wider than tall, matching the aspect of most content blocks. Sizing in rem rather than % means the glow keeps its physical size on a small panel instead of shrinking to a hotspot — a percentage-sized gradient in a 320px preview looks like a different effect entirely.
- `intensity = 0.09`
  Peak accent opacity at the centre. Under ~0.05 it is indistinguishable from a gradient banding artefact; over ~0.2 it stops being ambient light and becomes a coloured blob that competes with the text it is behind.
- `transparent 68% = 68%`
  Where the glow reaches zero. Ending short of 100% keeps the falloff inside the gradient box so the edge is never visible as a circle boundary against the panel edge.

## API

```ts
function PointerVarGradient(props: { children?: ReactNode; glowWidth?: string; glowHeight?: string; intensity?: number; className?: string }): JSX.Element
```

- `children: ReactNode`
  Content rendered over the gradient.
- `glowWidth: string` — default `'38rem'`
  Horizontal radius of the glow, any CSS length.
- `glowHeight: string` — default `'30rem'`
  Vertical radius of the glow, any CSS length.
- `intensity: number` — default `0.09`
  Peak accent opacity at the glow centre, 0..1.
- `className: string`
  Merged onto the root container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** Where the glow sits before the pointer has ever been seen. */
const REST_X = '50%';
const REST_Y = '38%';

export function PointerVarGradient({
  children,
  glowWidth = '38rem',
  glowHeight = '30rem',
  intensity = 0.09,
  className,
}: PointerVarGradientProps) {
  const root = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const el = root.current;
    if (!el) return;

    /* Fine pointers only. On touch a `pointermove` exists only during a drag,
       so the glow would be pinned under the finger that is scrolling the page
       and then abandoned there on lift — worse than not moving at all. The
       rest position set in the inline style stays, so touch users still get a
       composed gradient. */
    if (!window.matchMedia('(pointer: fine)').matches) return;

    const onMove = (e: PointerEvent) => {
      const rect = el.getBoundingClientRect();
      /* Percentages, not px. The gradient position resolves against the
         element box, so a percentage survives a resize with no listener and
         no recalculation — the glow stays where it was relative to the panel
         even if the panel changes size between moves. */
      el.style.setProperty(
        '--pointer-x',
        `${((e.clientX - rect.left) / rect.width) * 100}%`,
      );
      el.style.setProperty(
        '--pointer-y',
        `${((e.clientY - rect.top) / rect.height) * 100}%`,
      );
    };

    const onLeave = () => {
      /* Removing the property rather than writing the rest value back lets the
         inline `style` fallback take over, so the resting position is declared
         in exactly one place. */
      el.style.removeProperty('--pointer-x');
      el.style.removeProperty('--pointer-y');
    };

    el.addEventListener('pointermove', onMove, { passive: true });
    el.addEventListener('pointerleave', onLeave);

    return () => {
      el.removeEventListener('pointermove', onMove);
      el.removeEventListener('pointerleave', onLeave);
      el.style.removeProperty('--pointer-x');
      el.style.removeProperty('--pointer-y');
    };
  }, []);

  /* The gradient definition lives here and only here. The handler above never
     mentions colours, sizes or stops — it only moves the centre.

     No `transition`: an unregistered custom property is an untyped token, so
     the browser cannot interpolate it and a transition on the gradient would
     silently do nothing. Making the leave ease would mean registering the
     properties with `@property { syntax: '<percentage>' }` in a stylesheet,
     which is a real option but not a free one. The snap back is acceptable
     here because the glow at rest is barely above the background. */
  const style = {
    '--pointer-x': REST_X,
    '--pointer-y': REST_Y,
    backgroundImage: `radial-gradient(${glowWidth} ${glowHeight} at var(--pointer-x) var(--pointer-y), color-mix(in oklab, var(--k-accent) ${Math.round(
      intensity * 100,
    )}%, transparent), transparent 68%)`,
  } as CSSProperties;
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the two pointer listeners and removes both custom properties from the element, so a remount starts from the declared rest position rather than inheriting the last pointer location. Nothing else was ever allocated — no frame loop, no tween, no observer.

**Reduced motion.** Unchanged, and intentionally so. Nothing here animates: the gradient centre tracks the pointer one-to-one with no easing, no inertia and no continuing motion after input stops. Suppressing it would remove a hover affordance rather than a motion effect.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Rebuilding the whole `background` string in JavaScript on every move. The browser re-parses every layer, including the static one, and you have moved a CSS declaration into a hot event handler where it will drift out of sync with the stylesheet.
- Expecting a `transition` on the gradient to smooth the leave. An unregistered custom property is an untyped token and cannot be interpolated, so the transition silently does nothing and there is no warning anywhere. Smoothing requires `@property { syntax: "<percentage>"; inherits: false; initial-value: 50% }` in a real stylesheet.
- Writing pixel values instead of percentages. They are correct only until the element resizes, at which point the glow is offset by however much the box changed and stays wrong until the next pointer move.
- Wrapping the write in `requestAnimationFrame`. It adds a frame of latency to a write that was never the bottleneck. rAF batching is for handlers that read layout; this one does not.
- Setting the properties on `document.documentElement` instead of the element. Every subtree that uses the same variable names then responds to a pointer that is nowhere near it, and two instances on one page fight over the same two globals.
- Reading `getBoundingClientRect()` and caching it. The rect is cheap here because nothing in this component writes layout, so there is no forced reflow to avoid — but a cached rect goes stale on scroll, which is the actual bug people ship trying to optimise this.

## Notes

- Gated on `(pointer: fine)`. On touch no listener attaches at all: `pointermove` only fires mid-drag, so the glow would follow the finger that is scrolling and be abandoned wherever it lifted. The inline rest position remains, so touch users get a composed static gradient rather than a blank panel.
- No reduced-motion branch is needed and none is present. There is no animation to reduce — the glow does not move on its own, does not ease, and does not persist after the pointer leaves. It is a hover state that happens to be continuous.
- The glow colour is `color-mix(in oklab, var(--k-accent) N%, transparent)` so it follows the category accent and the light/dark theme without a second code path.
- This is the cheapest component in the cursor category. If an effect can be expressed this way it should be, and the interesting question about any pointer effect is why it cannot.

## Definition of done

Move across the panel and a soft accent glow follows the pointer exactly, with no lag and no easing. Leave and it snaps back above centre. Resize the panel while the pointer is stationary and the glow stays in the same relative position rather than sliding. Open DevTools and confirm the element has exactly two inline custom properties changing and that no `background` or `background-image` value is being rewritten. On touch the glow never moves.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Pooled Cursor Image Trail

Sweeping the pointer across the panel drops a trail of tiles behind it, each fading up over 220ms, holding, and fading out — total life 520ms. The tiles come from a fixed ring of 22 nodes created once at mount and reused by index, and a new one is only released when the pointer has travelled more than 130px since the last. Those two rules are the component; the tween values are decoration.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Tiles drop behind the cursor from a fixed ring of 22 reused nodes, one every 130px of travel.

- Category: cursor
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. A ring of `poolSize` absolutely-positioned canvases is rendered once, all with `will-change: transform` so layer promotion has already happened before the first spawn. Nothing is ever created or removed after mount.
2. `plateCount` gradient plates are painted into offscreen canvases at mount — the registry ships no image assets, so the "photographs" are drawn. A spawn is then a single `drawImage` blit, which keeps the gradient and text work off the frame where a tween starts.
3. On `pointermove` the handler measures `Math.hypot(x - anchor.x, y - anchor.y)` against the last spawn point and returns early below `threshold`. The very first move only seeds the anchor and spawns nothing, so entering from an edge does not drop a tile before any real movement has happened.
4. A spawn takes slot `spawned % poolSize`, picks a plate with a seeded RNG plus a one-line no-repeat guard (`if (i === last) i = (i + 1) % n`), blits it, then `gsap.killTweensOf(node)` before `gsap.set` reinitialises x, y, rotation, scale 0.92, opacity 0 and `zIndex: spawned`.
5. `zIndex` is the monotonically increasing spawn counter, so the newest tile always paints over older ones with no stacking logic at all. At ten spawns a second it would take roughly 285,000 years to reach `Number.MAX_SAFE_INTEGER`.
6. The life is one timeline: in over 220ms with `power2.out`, hold 100ms, out over 200ms with `power2.in`. The pool is sized so a slot's 520ms life always expires before the ring wraps back around to it.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `threshold = 130`
  Pixels of travel per tile, and the single most load-bearing number here. A deliberate sweep across a hero yields 8-10 readable tiles; small jitters yield none. Drop it toward 20 and a flick produces a solid smear of overlapping tiles; raise it past ~250 and normal mouse movement never triggers the effect at all.
- `poolSize = 22`
  The ring must not wrap while a tile is still visible. At 520ms of life you would have to move 22 x 130 = 2860px in 520ms to catch your own tail — a flick nobody performs by accident.
- `plateCount = 17`
  Deliberately coprime with the 22 slots, so the plate-to-slot pairing never settles into a short repeating pattern as the ring advances. Also fewer plates than slots, so the memory cost is bounded independently of pool size.
- `IN_DURATION / HOLD / OUT_DURATION = 0.22 / 0.1 / 0.2`
  520ms total. Fast in with `power2.out` (arrives), a beat of stillness so the tile is actually readable, then a `power2.in` exit (leaves). Collapse the hold and the trail reads as a blur instead of as a sequence of pictures.
- `START_SCALE = 0.92`
  An 8% growth on entry. Enough to read as arriving, small enough not to pop — at 0.7 it looks like a modal opening.
- `TILT = 7`
  Degrees of seeded rotation either way. Perfectly square tiles read as UI panels; a few degrees reads as prints dropped on a table. Past ~12 the corners of successive tiles collide and the trail looks untidy.
- `PLATE_SCALE = 2`
  Backing-store multiplier for the plate canvases. Fixed rather than `devicePixelRatio` so the drawn output is byte-identical on every machine and a visual regression is actually visible.

## API

```ts
function PooledImageTrail(props: { children?: ReactNode; threshold?: number; poolSize?: number; plateCount?: number; tileWidth?: number; tileHeight?: number; seed?: string; className?: string }): JSX.Element
```

- `children: ReactNode`
  Content rendered above the trail layer.
- `threshold: number` — default `130`
  Pixels of pointer travel required before another tile is released.
- `poolSize: number` — default `22`
  Number of reusable nodes in the ring.
- `plateCount: number` — default `17`
  Distinct plates painted at mount. Keep coprime with poolSize.
- `tileWidth: number` — default `236`
  Tile width in CSS px.
- `tileHeight: number` — default `160`
  Tile height in CSS px.
- `seed: string` — default `'pooled-image-trail'`
  Seeds plate choice and tilt so the sequence is deterministic.
- `className: string`
  Merged onto the root container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const IN_DURATION = 0.22;
const HOLD = 0.1;
const OUT_DURATION = 0.2;
const START_SCALE = 0.92;
const TILT = 7;

export function PooledImageTrail({
  children,
  threshold = 130,
  poolSize = 22,
  plateCount = 17,
  tileWidth = 236,
  tileHeight = 160,
  seed = 'pooled-image-trail',
  className,
}: PooledImageTrailProps) {
  const root = useRef<HTMLDivElement>(null);
  const slots = useRef<Array<HTMLCanvasElement | null>>([]);

  useEffect(() => {
    const el = root.current;
    if (!el) return;

    const nodes: HTMLCanvasElement[] = [];
    for (let i = 0; i < poolSize; i++) {
      const node = slots.current[i];
      if (node) nodes.push(node);
    }
    if (nodes.length === 0) return;

    const bw = tileWidth * PLATE_SCALE;
    const bh = tileHeight * PLATE_SCALE;

    // Paint every plate once, offscreen. A spawn is then a single blit; if the
    // plate were drawn at spawn time the gradient + text work would land on
    // the same frame as the tween start, which is the one frame that must not
    // drop.
    const plates: HTMLCanvasElement[] = [];
    for (let i = 0; i < plateCount; i++) {
      const plate = document.createElement('canvas');
      plate.width = bw;
      plate.height = bh;
      const pctx = plate.getContext('2d');
      if (!pctx) break;
      pctx.scale(PLATE_SCALE, PLATE_SCALE);
      paintPlate(pctx, tileWidth, tileHeight, i);
      plates.push(plate);
    }
    if (plates.length === 0) return;

    const contexts = nodes.map((node) => {
      node.width = bw;
      node.height = bh;
      return node.getContext('2d');
    });

    const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
    const fine = window.matchMedia('(pointer: fine)').matches;

    gsap.set(nodes, { xPercent: 0, yPercent: 0, opacity: 0, force3D: true });

    if (reduced || !fine) {
      // Poster fallback: three plates fanned in the middle, drawn once. The
      // panel is composed rather than empty, and nothing ever moves.
      const shown = Math.min(3, nodes.length, plates.length);
      for (let i = 0; i < shown; i++) {
        const ctx = contexts[i];
        const plate = plates[i % plates.length];
        const node = nodes[i];
        if (!ctx || !plate || !node) continue;
        ctx.drawImage(plate, 0, 0);
        gsap.set(node, {
          x: el.clientWidth / 2 - tileWidth / 2 + (i - 1) * tileWidth * 0.42,
          y: el.clientHeight / 2 - tileHeight / 2 + (i - 1) * 14,
          rotate: (i - 1) * 4,
          opacity: 1,
          zIndex: i,
        });
      }
      return () => {
        gsap.killTweensOf(nodes);
        gsap.set(nodes, { clearProps: 'all' });
      };
    }

    const rng = createRng(seed);
    /** Monotonic. Doubles as the ring index and as the z-index. */
    let spawned = 0;
    /** Where the last tile was dropped. `null` until the first move seeds it. */
    let anchor: { x: number; y: number } | null = null;
    let lastPlate = -1;

    const onMove = (e: PointerEvent) => {
      const rect = el.getBoundingClientRect();
      const x = e.clientX - rect.left;
      const y = e.clientY - rect.top;

      // First move seeds the anchor and spawns nothing. Otherwise the initial
      // distance is measured from (0, 0) and entering from the right-hand side
      // of a wide panel drops a tile immediately, before any real movement.
      if (anchor === null) {
        anchor = { x, y };
        return;
      }
      if (Math.hypot(x - anchor.x, y - anchor.y) < threshold) return;
      anchor = { x, y };

      const slot = spawned % nodes.length;
      const node = nodes[slot];
      const ctx = contexts[slot];
      if (!node || !ctx) return;
      spawned++;

      // One-line no-repeat guard. It does not attempt a uniform distribution,
      // because the only thing the eye actually notices is the same picture
      // twice in a row.
      let plateIndex = Math.floor(rng() * plates.length);
      if (plateIndex === lastPlate) plateIndex = (plateIndex + 1) % plates.length;
      lastPlate = plateIndex;
      const plate = plates[plateIndex];
      if (!plate) return;

      ctx.clearRect(0, 0, bw, bh);
      ctx.drawImage(plate, 0, 0);

      // Kill before reuse. A slot recycled while still fading out would carry
      // two competing tweens on `opacity` and visibly flicker.
      gsap.killTweensOf(node);
      gsap.set(node, {
        x: x - tileWidth / 2,
        y: y - tileHeight / 2,
        rotate: randRange(rng, -TILT, TILT),
        scale: START_SCALE,
        opacity: 0,
        // Monotonic z-index: the newest tile always paints over older ones and
        // there is no stacking logic to maintain.
        zIndex: spawned,
      });

      gsap
        .timeline()
        .to(node, { opacity: 1, scale: 1, duration: IN_DURATION, ease: 'power2.out' })
        .to(node, { opacity: 0, duration: OUT_DURATION, ease: 'power2.in' }, `+=${HOLD}`);
    };

    el.addEventListener('pointermove', onMove, { passive: true });

    return () => {
      el.removeEventListener('pointermove', onMove);
      gsap.killTweensOf(nodes);
      gsap.set(nodes, { clearProps: 'all' });
    };
  }, [threshold, poolSize, plateCount, tileWidth, tileHeight, seed]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the single `pointermove` listener, calls `gsap.killTweensOf` on every pool node — which also kills the per-spawn timelines, since they only target those nodes — then `gsap.set(nodes, { clearProps: "all" })`. The offscreen plate canvases are plain locals and are collected with the closure; nothing was allocated that needs revoking.

**Reduced motion.** No listener attaches and nothing animates. Three plates are drawn once into the first three pool slots, fanned across the centre with a few degrees of rotation each, so the panel is a composed still of what the effect produces rather than an empty rectangle.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Creating an element per spawn. A fast sweep across a wide hero allocates a hundred nodes, each forcing a style recalc, a layer promotion and a paint at the exact moment the main thread is busiest — the trail stutters precisely when it is being used hardest.
- Spawning on every `pointermove` instead of on distance travelled. Events fire on sub-pixel movement, so a flick produces a solid smear and a slow drift produces a dense clump; "moved" and "moved enough" are different predicates.
- Measuring the first move against a zeroed anchor. The distance from (0, 0) to wherever the pointer entered is usually well over the threshold, so a tile fires the instant the pointer crosses the boundary, before any movement has happened.
- Reusing a slot without `gsap.killTweensOf(node)` first. If the ring wraps onto a tile that is still fading out, two tweens fight over `opacity` and it flickers rather than restarting cleanly.
- Recomputing z-order from tile ages. A monotonic counter is correct, free, and cannot get out of sync; sorting is a whole class of bug bought for nothing.
- Painting the gradient plate at spawn time. The gradient fill, the radial sheen and the text layout all land on the same frame as the tween start, which is the one frame in the effect that must not drop. Paint once at mount and blit.
- Omitting `will-change: transform` from the pool. The browser promotes the tile to its own layer partway through its 220ms entry, so the first frames of every spawn are visibly cheaper-looking than the rest.

## Notes

- Gated on `(pointer: fine)`. On touch a `pointermove` only exists during a drag, so the trail would appear only under a finger that is already covering it and would then be stranded mid-life on lift. The touch path renders the same static fan as reduced motion.
- The tiles sit behind the content layer (`z-0` under a `z-10` child wrapper) so headline copy stays readable while the trail passes under it.
- Plate choice runs on `createRng(seed)`, never `Math.random()`, so the sequence is identical on every load and across a server render.

## Definition of done

Sweep the pointer slowly across the panel and tiles drop behind it roughly every 130px, each readable for about half a second before fading. Jiggle the pointer in place and nothing spawns. Flick as fast as you can and you get a spaced trail, not a smear, and no tile ever restarts mid-fade with a flicker. Enter the panel from an edge and no tile appears until you have actually moved. On touch or with reduced motion you see three static fanned plates.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Pre-Scatter Horizontal Gallery

A pinned horizontal strip whose media is deliberately off-grid: every item gets a small seeded resting offset, then rides in from ahead of its slot and runs out behind it, rotating through zero on the way past. Two `fromTo` pairs per item — one entry, one exit — measured against the strip's own tween rather than against scroll position, so the choreography is a property of where an item is in the container, not of where the page is.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A pinned strip where each item rests slightly off its slot, flies in from ahead and peels away behind.

- Category: scroll
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. The component owns a `PinnedHorizontalTrack` and captures its `onTrack` payload in state. The strip's tween is built in the child's effect and therefore arrives one commit late, which is why it is state and not a ref — the arrival has to re-run the builder.
2. Every `[data-scatter]` element draws one value from `createRng(seed)`: `rest = (rng() - 0.5) * scatter`, a resting `xPercent` offset. It is applied with `gsap.set` for every item whether or not it animates, so the composition is identical with motion on and off.
3. The entry is `fromTo(el, { xPercent: rest + sweep, yPercent: dir * lift, rotation: dir * rotation }, { xPercent: rest, yPercent: 0, rotation: 0 })` scrubbed over `left 110%` to `left 65%` — the item lags behind its slot and catches up as it crosses the container.
4. The exit is the mirror: `fromTo(el, { xPercent: rest, yPercent: 0, rotation: 0 }, { xPercent: rest - sweep, yPercent: -dir * lift, rotation: -dir * rotation })` over `right 35%` to `right -10%`, with `immediateRender: false` so it does not overwrite the entry's from-state at creation.
5. `dir` alternates by index parity, so odd items throw up and rotate clockwise while even items do the opposite, and the rotation passes continuously through zero between the two ranges.
6. Both triggers take `containerAnimation: track.animation` and horizontal position keywords, so ScrollTrigger measures each item along the strip's timeline instead of down the page.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `scatter = 32`
  Total resting spread as a percentage of the item's own width, i.e. ±16%. Below ~10 the grid still reads as a grid and the effect is invisible; above ~50 items collide with their neighbours' captions and it reads as a layout bug rather than a composition.
- `sweep = 400`
  Horizontal lag on entry and lead on exit, as a percentage of item width. Four widths is enough that the item is genuinely off-stage at the start of its range, so the catch-up is a travel rather than a nudge. Under ~150 the item is already visible when its tween begins and appears to jerk into place.
- `lift = 150`
  Vertical throw as a percentage of item height. At 100 the item starts exactly one height away, so its edge is still touching the frame; 150 clears the frame with margin, which is what makes it read as flying in rather than sliding.
- `rotation = 40°`
  Peak tilt. Under ~15° the rotation is mistaken for a rendering artefact; past ~60° the item is legibly upside-down at the extremes and text inside it becomes unreadable during the travel.
- `ENTER_START / ENTER_END = 'left 110%' / 'left 65%'`
  The item's leading edge, measured along the container. Starting past 100% means the tween begins before the item is visible, so nothing pops in already moving. Ending at 65% leaves the middle third of the crossing settled.
- `EXIT_START / EXIT_END = 'right 35%' / 'right -10%'`
  The trailing edge. Ending below 0% carries the item fully past the left frame before the tween completes, so it never freezes half-visible at the edge. The two ranges cannot overlap for any item narrower than 1.3 containers.
- `item scrub = true`
  Locked to the container animation, not a number. These triggers read the strip's progress, and the strip already scrubs with a second of catch-up, so a numeric scrub here smooths an already-smoothed signal and the items swim behind the panels they belong to.

## API

```ts
function PrescatterHorizontalGallery(props: { children: ReactNode; scroller?: RefObject<HTMLElement | null>; seed?: number | string; scatter?: number; rotation?: number; lift?: number; sweep?: number; scrub?: number; className?: string; trackClassName?: string }): JSX.Element
```

- `children: ReactNode`
  Panels for the strip. Give each a width and `shrink-0`, and mark the media inside `data-scatter`.
- `scroller: RefObject<HTMLElement | null>`
  Scroll container the triggers read. Omit for the document.
- `seed: number | string` — default `'gallery'`
  Anything hashable. The same seed rebuilds the same composition.
- `scatter: number` — default `32`
  Total resting spread as a percentage of item width.
- `rotation: number` — default `40`
  Peak tilt in degrees, alternating by index.
- `lift: number` — default `150`
  Vertical throw as a percentage of item height.
- `sweep: number` — default `400`
  Horizontal lag and lead as a percentage of item width.
- `scrub: number` — default `1`
  Seconds of catch-up on the strip, forwarded to the pinned track.
- `className: string`
  Merged onto the gallery wrapper.
- `trackClassName: string`
  Merged onto the moving strip.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * The item's leading edge crosses the container from just off the right
 * (110%) to two thirds in (65%), and its trailing edge leaves from a third in
 * (35%) to just past the left (-10%). The two ranges cannot overlap for any
 * item narrower than 1.3 containers, so every item gets a settled window in
 * the middle where it is simply itself.
 */
const ENTER_START = 'left 110%';
const ENTER_END = 'left 65%';
const EXIT_START = 'right 35%';
const EXIT_END = 'right -10%';

export function PrescatterHorizontalGallery({
  children,
  scroller,
  seed = 'gallery',
  scatter = 32,
  rotation = 40,
  lift = 150,
  sweep = 400,
  scrub = 1,
  className,
  trackClassName,
}: PrescatterHorizontalGalleryProps) {
  const root = useRef<HTMLDivElement>(null);
  // The strip's tween is built in a child's effect, so it arrives one commit
  // late. State, not a ref: the arrival has to re-run the builder below.
  const [track, setTrack] = useState<PinnedTrack | null>(null);
  const reduced = useReducedMotion();

  useEffect(() => {
    const rootEl = root.current;
    if (!rootEl) return;

    const containerAnimation = track?.animation;
    const scrollerEl = scroller?.current ?? undefined;

    const ctx = gsap.context(() => {
      const targets = Array.from(rootEl.querySelectorAll<HTMLElement>('[data-scatter]'));
      const rng = createRng(seed);

      targets.forEach((el, i) => {
        // Drawn for every item whether or not it animates, so adding motion
        // never shifts the resting composition.
        const rest = (rng() - 0.5) * scatter;
        // Parity, not the generator: alternating up/down and cw/ccw is a
        // rhythm, and a random sign clumps three the same way and looks broken.
        const dir = i % 2 === 0 ? 1 : -1;

        gsap.set(el, { xPercent: rest });
        // The resting scatter is layout. Under reduced motion the composition
        // survives and only the flight is dropped.
        if (reduced || !containerAnimation) return;

        gsap.fromTo(
          el,
          { xPercent: rest + sweep, yPercent: dir * lift, rotation: dir * rotation },
          {
            xPercent: rest,
            yPercent: 0,
            rotation: 0,
            ease: 'none',
            scrollTrigger: {
              trigger: el,
              scroller: scrollerEl,
              containerAnimation,
              start: ENTER_START,
              end: ENTER_END,
              // `true`, not a number. The strip already scrubs with catch-up,
              // and these triggers read the strip's progress rather than the
              // scrollbar, so they inherit that smoothing. A second scrub
              // value smooths the smoothed signal and the items swim.
              scrub: true,
            },
          },
        );

        gsap.fromTo(
          el,
          { xPercent: rest, yPercent: 0, rotation: 0 },
          {
            xPercent: rest - sweep,
            yPercent: -dir * lift,
            rotation: -dir * rotation,
            ease: 'none',
            // The single most important line here. A `fromTo` renders its
            // from-state at creation, so without this the exit immediately
            // overwrites the entry's from-state — every item starts on the
            // grid instead of off-stage, and the entry appears not to exist.
            immediateRender: false,
            scrollTrigger: {
              trigger: el,
              scroller: scrollerEl,
              containerAnimation,
              start: EXIT_START,
              end: EXIT_END,
              scrub: true,
            },
          },
        );
      });
    }, rootEl);

    return () => ctx.revert();
  }, [track, scroller, seed, scatter, rotation, lift, sweep, reduced]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** One `gsap.context` scoped to the root holds the `set` calls and both tweens per item, so `ctx.revert()` kills every tween, kills every ScrollTrigger, and strips the inline transforms back off the media. It runs on unmount and on every dependency change, including the commit where the strip's tween arrives.

**Reduced motion.** The resting scatter is still applied — it is layout, not motion, and the gallery is supposed to look deliberately off-grid. What is dropped is the flight: no entry or exit triggers are created, so every item sits at its offset from first paint. The pinned track also declines to pin, so the strip becomes a horizontally scrollable row and every item stays reachable.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Using `gsap.to` for the exit. A `to` records its start values when it is created, which is after the entry has already rendered its from-state — so the exit animates from `xPercent: rest + sweep` and the item never returns to its slot.
- Using a second `fromTo` for the exit without `immediateRender: false`. A `fromTo` writes its from-state immediately, so the later tween wins and every item starts on the grid: the entry animation exists, runs, and is invisible.
- Keeping vertical position keywords with a `containerAnimation`. `start: "top 110%"` on a horizontal container resolves to a position the element never occupies. No error, no warning, no animation — the items simply arrive pre-placed.
- Measuring the scatter in pixels off the container width. It has to be recomputed on every ScrollTrigger refresh or the composition creeps as the window resizes; expressed as `xPercent` it resolves against the element and never needs invalidating.
- `Math.random()` for the offsets. The server and the client disagree at hydration, and the composition is different on every reload, so nobody can tell a regression from a reroll.
- Building the item triggers before the strip's tween exists. Treating `undefined` as "no container animation" builds a full set of vertical triggers on horizontal content and tears them down on the next commit — a visible flash of items that were already in place.
- Alternating direction from the generator instead of from the index. A random sign lands three items the same way often enough to look like a bug, where parity always reads as rhythm.

## Notes

- Mark the media, not the panel: `data-scatter` on an inner element lets the panel keep the caption on the grid while the image drifts off it.
- ScrollTrigger forbids `pin` on a trigger that has a `containerAnimation`. The strip's section is pinned by `PinnedHorizontalTrack`; the items riding it are never pinned.
- Panels need `overflow: visible` for the sweep to be seen. Clipping happens once, at the pinned section's edge.

## Definition of done

Scroll into the section: it pins, the strip travels sideways, and each item swings in from ahead of its slot, straightens, holds through the middle of the crossing, then tilts the other way and runs out to the left. Scroll back up and every item reverses along the same path. Note that no two items rest exactly on the grid, and that reloading gives the identical composition. With reduced motion on, the items are already at their offsets and the strip can be swiped by hand.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Proximity Snap Track

A scrollable rail whose items may be any width. `scroll-snap-type: x proximity` snaps to an item only when the scroll comes to rest near one, so free scanning stays free. `scroll-snap-stop: always` caps a single fling at one item, so a hard swipe cannot launch the user past six cards. No JavaScript runs during the scroll.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A horizontal rail of variable-width cards that snaps only when you stop near one, and never skips past two at once.

- Category: layout
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. The container is `overflow-x: auto` with `scroll-snap-type: x proximity`. `proximity` means the browser only adjusts the resting position when the natural end of the scroll already falls close to a snap point; anywhere else, it leaves the position exactly where the user left it.
2. Each item declares `scroll-snap-align: start` (or `center`) — this is what makes it a snap point at all — and `scroll-snap-stop: always`, which forbids the browser from passing more than one snap point per gesture no matter how much momentum the fling carried.
3. `scroll-padding-inline` is set alongside `padding-inline` to the same gutter. They are different properties: `padding` insets the content, `scroll-padding` insets the *snapport* — the rectangle a snap position is measured against. With padding alone, a `start`-aligned item comes to rest flush against the container border and the inset the design asked for vanishes at every rest position.
4. `overscroll-behavior-x: contain` stops a horizontal fling that reaches the end of the rail from chaining to an ancestor scroller or triggering the browser's back-navigation gesture.
5. `scroll-behavior` is `smooth` normally and `auto` under reduced motion, which affects programmatic and keyboard-initiated scrolls. The snap adjustment itself is the browser's own and already respects the OS setting.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `snapType = 'proximity'`
  The whole argument of this component. With `mandatory`, the browser must always come to rest on a snap point, so on a rail of variable-width items it is physically impossible to stop between two of them — every attempt to park somewhere gets yanked. Worse, on a long rail `mandatory` plus a short flick can leave the user unable to reach a position at all. `proximity` snaps when it helps and gets out of the way when it does not.
- `snapStop = 'always'`
  Without it, a hard fling on a trackpad passes every snap point and lands on whichever item the momentum ran out over — which on a rail of 20 cards means the user has no way to advance by exactly one. `always` turns each item into a gate.
- `snapAlign = 'start'`
  Correct default for variable-width items: their left edges line up at rest, which reads as a column of starts. `center` is right only when items are uniform, because with mixed widths a centred rest position puts every item's left edge somewhere different.
- `gutter = 16`
  Set on both `padding-inline` and `scroll-padding-inline`. The two must match or the resting inset and the visual inset disagree by exactly this many pixels, which looks like a rounding bug.
- `gap = 12`
  Large enough that two adjacent cards read as separate snap targets, small enough that the next card is clearly a continuation of the row rather than a separate section.

## API

```ts
function ProximitySnapTrack(props: { children: ReactNode; snapType?: 'proximity' | 'mandatory'; snapAlign?: 'start' | 'center'; snapStop?: 'normal' | 'always'; gutter?: number; gap?: number; className?: string; itemClassName?: string; 'aria-label'?: string }): JSX.Element
```

- `children: ReactNode`
  One item per child. Widths may differ.
- `snapType: 'proximity' | 'mandatory'` — default `'proximity'`
  Snap strictness. `mandatory` is exposed so the difference can be felt, not because it is usually right here.
- `snapAlign: 'start' | 'center'` — default `'start'`
  Which edge of an item lines up with the snapport.
- `snapStop: 'normal' | 'always'` — default `'always'`
  `always` caps one gesture at one item.
- `gutter: number` — default `16`
  Inset in px, applied to both `padding-inline` and `scroll-padding-inline`.
- `gap: number` — default `12`
  Gap between items in px.
- `className: string`
  Merged onto the scroll container.
- `itemClassName: string`
  Merged onto each item cell.
- `aria-label: string` — default `'Track'`
  Label for the focusable scroll region.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const trackStyle: CSSProperties = {
  scrollSnapType: `x ${snapType}`,
  // `scroll-padding` is what a snap position is measured against, and it is
  // a separate property from `padding`. With padding alone, a `start`-aligned
  // item snaps flush to the container's border and the inset the design asked
  // for silently disappears at every rest position.
  scrollPaddingInline: `${gutter}px`,
  paddingInline: `${gutter}px`,
  gap: `${gap}px`,
  // Programmatic scrolls (anchor jumps, `scrollIntoView`, arrow keys in some
  // engines) animate unless told not to. Snapping itself is not affected —
  // it is the browser's own transition and honours the OS setting already.
  scrollBehavior: reduced ? 'auto' : 'smooth',
};

const itemStyle: CSSProperties = {
  scrollSnapAlign: snapAlign,
  scrollSnapStop: snapStop,
};
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nothing to release. All behaviour is declarative CSS on nodes React owns; the only subscription is `useReducedMotion`, which removes its own `matchMedia` listener on unmount. No listeners, no timers, no rAF.

**Reduced motion.** The rail behaves identically — it is a scroll container, and scrolling is the user moving, not the interface animating. The one change is `scroll-behavior: auto` instead of `smooth`, so keyboard and programmatic scrolls jump rather than glide. The snap adjustment is the browser's own transition and already follows the OS setting without any help.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- `scroll-snap-type: x mandatory` on a track with variable-width items. It makes it impossible to rest between items: every release is pulled to a snap point, so the user cannot park where they want, and on a long rail with wide items they end up fighting the browser for the whole length of the track. `proximity` is the correct choice whenever the items are not uniform or the track is long.
- Setting `padding-inline` without `scroll-padding-inline`. Every rest position then puts the item flush against the container edge, so the gutter appears while scrolling and disappears the instant you let go.
- Omitting `scroll-snap-stop: always`. A single hard swipe lands eight cards along, which makes stepping by one impossible and makes the rail feel slippery rather than mechanical.
- Hiding the scrollbar without making the container focusable. The rail becomes invisible to keyboard users and to anyone who was relying on the scrollbar as the affordance. `tabIndex={0}` and a `role`/`aria-label` restore arrow-key scrolling, and Chrome stops warning about a non-focusable scroll container.
- Leaving `overscroll-behavior-x` at `auto`. Flinging past the end chains into the page or, in Safari and Chrome, triggers the swipe-to-go-back gesture and the user loses the page.
- Reaching for a JS carousel because "the design has arrows". A snap track already has momentum, rubber-banding, keyboard support and accessible scroll semantics; arrows are one `scrollBy` call on top, not a reason to replace the mechanism.

## Notes

- Snap is a layout-level contract, not an animation. Everything here runs on the compositor and continues to work when the main thread is blocked, which is the reason to prefer it over a JS track whenever the interaction is genuinely "a scrollable row".
- Items are `shrink-0`. Without it, flex would compress them to fit the container and the track would never overflow, so there would be nothing to snap.
- `scroll-snap-stop` is ignored during programmatic scrolls in every engine — it only constrains user gestures. Arrows implemented with `scrollTo` can therefore still jump several items at once by design.

## Definition of done

Scroll the rail slowly and stop between two cards — it stays where you left it. Stop just past a card's edge and it eases onto that card. Fling as hard as you can and it advances exactly one card. Tab to the rail and press the arrow keys: it scrolls and snaps the same way. At every rest position the leading card sits inset from the container edge by the gutter, not flush against it.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: quickTo Cursor Preview

Hovering a row fades in a preview panel that then trails the pointer with a full second of catch-up, so it reads as a heavy object being dragged rather than a tooltip pinned to the cursor. Position comes from exactly two `gsap.quickTo` setters created once at mount; the hovered row is the only thing that ever enters React state.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A preview panel drifts a full second behind the pointer, driven by two reused quickTo tweens.

- Category: cursor
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. `gsap.quickTo(box, "x", { duration, ease })` returns a setter backed by ONE tween whose end value is mutated in place. A `pointermove` handler firing 60-120 times a second therefore allocates nothing after the first frame, where the `gsap.to()` equivalent allocates and garbage-collects a tween object per event and leaves each new tween fighting the last for the same property.
2. Hovered row is React state because it changes a handful of times a second and drives real DOM structure (text colour, stroke, offset). Panel position is never state: it changes on every pointer event, and a re-render per move would cost more than the animation it is driving.
3. `duration: 1` is roughly five times a normal cursor follow, and that is the entire design. Under `power3` the panel covers most of the gap early and then creeps, so it always reads as heading for the pointer without ever arriving — which is what makes it feel like mass rather than lag.
4. The first move after entry calls `xTo(x, x)` — quickTo's second argument is the tween's START value, so the panel is teleported rather than eased. Without it, re-entering the list sends the panel sailing diagonally across the whole component over a full second before it becomes useful.
5. Position is centred with `xPercent: -50, yPercent: -50` set once at mount, so `x`/`y` are raw pointer coordinates and no offset arithmetic appears in the hot handler.
6. Every preview is a gradient plate painted into an offscreen canvas at mount — the registry ships no image assets. Switching rows is one `drawImage` blit, so the gradient, band and text work never lands on the frame where the fade-in starts.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `duration = 1`
  Seconds of catch-up, and the whole character of the component. At 0.2 it is an ordinary tooltip that happens to be smooth; at 1 it is an object with weight. Past ~1.6 the panel is still crossing the list when the pointer has already left it, and the effect reads as broken rather than heavy.
- `ease: 'power3' = power3 (in-out)`
  In-out, not `.out`. Because the end value is remutated on every event, the tween is permanently restarting from its own midpoint; the symmetric curve means direction changes are absorbed smoothly instead of snapping to a new outward ramp each time.
- `FADE_DURATION = 0.35`
  Fade and scale on row change. Long enough to register as a cross-fade rather than a cut, short enough that dragging down a list of eight rows does not leave the panel permanently mid-transition.
- `scale 0.94 -> 1 = 0.94`
  A 6% growth on appear. Paired with opacity it reads as arriving from behind the page; without it the fade alone looks like a stuck render.
- `DOCK_INSET = 20`
  Pixels of margin when the panel docks to the right edge on touch or reduced motion. Clamped against `panelWidth / 2` so a panel wider than its container still lands fully inside rather than half off-screen.
- `PLATE_SCALE = 2`
  Backing-store multiplier for the plate canvases. Fixed rather than `devicePixelRatio` so the drawn output is identical on every machine and a visual regression is actually visible in a screenshot diff.

## API

```ts
function QuickToCursorPreview(props: { items: PreviewItem[]; duration?: number; panelWidth?: number; panelHeight?: number; className?: string }): JSX.Element
```

- `items: PreviewItem[]`
  Rows to render. `{ id, title, meta? }`; one plate is painted per item.
- `duration: number` — default `1`
  Seconds of catch-up on the follow. The defining value of the effect.
- `panelWidth: number` — default `260`
  Preview panel width in CSS px.
- `panelHeight: number` — default `180`
  Preview panel height in CSS px.
- `className: string`
  Merged onto the root container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const PLATE_SCALE = 2;
const FADE_DURATION = 0.35;
const DOCK_INSET = 20;

/**
 * True when the panel must NOT follow: no fine pointer (a `pointermove` on
 * touch only exists during a drag, so the panel would live under the finger
 * that is dragging it), or reduced motion (a full second of drift is precisely
 * what that user opted out of). One predicate, so the two effects below can
 * never disagree about which mode the component is in.
 */
function docked(): boolean {
  return (
    !window.matchMedia('(pointer: fine)').matches ||
    window.matchMedia('(prefers-reduced-motion: reduce)').matches
  );
}

export function QuickToCursorPreview({
  items,
  duration = 1,
  panelWidth = 260,
  panelHeight = 180,
  className,
}: QuickToCursorPreviewProps) {
  const root = useRef<HTMLDivElement>(null);
  const panel = useRef<HTMLDivElement>(null);
  const surface = useRef<HTMLCanvasElement>(null);
  const plates = useRef<HTMLCanvasElement[]>([]);

  /* Hovered row is React state because it changes a handful of times a
     second. Panel position is never state — it changes 120 times a second and
     a re-render per pointermove would dwarf the animation itself. */
  const [hovered, setHovered] = useState<number | null>(null);
  const { width, height } = useResizeObserver(root);

  const count = items.length;

  /* Paint every plate once. Drawing at hover time would put a gradient fill,
     four band rects and a text layout on the same frame as the fade-in. */
  useEffect(() => {
    const bw = panelWidth * PLATE_SCALE;
    const bh = panelHeight * PLATE_SCALE;
    const built: HTMLCanvasElement[] = [];
    for (let i = 0; i < count; i++) {
      const plate = document.createElement('canvas');
      plate.width = bw;
      plate.height = bh;
      const ctx = plate.getContext('2d');
      if (!ctx) break;
      ctx.scale(PLATE_SCALE, PLATE_SCALE);
      paintPlate(ctx, panelWidth, panelHeight, i);
      built.push(plate);
    }
    plates.current = built;

    const canvas = surface.current;
    if (canvas) {
      canvas.width = bw;
      canvas.height = bh;
    }
    return () => {
      plates.current = [];
    };
  }, [count, panelWidth, panelHeight]);

  /* Centre the panel on its own coordinates ONCE, at mount. Doing it with a
     negative margin or `left: -130px` instead means the offset and the
     transform fight, and the panel sits half a width off. */
  useEffect(() => {
    const box = panel.current;
    if (!box) return;
    gsap.set(box, { xPercent: -50, yPercent: -50, autoAlpha: 0, scale: 0.94 });
    return () => {
      gsap.killTweensOf(box);
      gsap.set(box, { clearProps: 'all' });
    };
  }, []);

  /* With no fine pointer — or with reduced motion, where a second of drift is
     exactly what the user opted out of — the panel docks to the right edge and
     only cross-fades as rows change. */
  useEffect(() => {
    const box = panel.current;
    if (!box || width === 0 || height === 0) return;
    if (!docked()) return;
    gsap.set(box, {
      x: Math.max(width - panelWidth / 2 - DOCK_INSET, panelWidth / 2),
      y: height / 2,
    });
  }, [width, height, panelWidth]);

  useEffect(() => {
    const el = root.current;
    const box = panel.current;
    if (!el || !box || docked()) return;

    // ONE tween per property, reused for the lifetime of the component.
    const xTo = gsap.quickTo(box, 'x', { duration, ease: 'power3' });
    const yTo = gsap.quickTo(box, 'y', { duration, ease: 'power3' });
    let seeded = false;

    const onMove = (e: PointerEvent) => {
      const rect = el.getBoundingClientRect();
      const x = e.clientX - rect.left;
      const y = e.clientY - rect.top;
      if (seeded) {
        xTo(x);
        yTo(y);
        return;
      }
      // Second argument is quickTo's `start` value: it snaps rather than
      // easing. Without it the panel sails in from wherever it was left,
      // taking a full second to cross the list on every re-entry.
      seeded = true;
      xTo(x, x);
      yTo(y, y);
    };

    const onLeave = () => {
      seeded = false;
    };

    el.addEventListener('pointermove', onMove, { passive: true });
    el.addEventListener('pointerleave', onLeave);

    /* Deliberately NOT clearing props here. `xPercent`, `yPercent` and
       `autoAlpha` belong to the mount effect; wiping them whenever `duration`
       changes would un-centre the panel and pop it to full opacity mid-hover.
       Teardown of those lives in the effect that set them. */
    return () => {
      el.removeEventListener('pointermove', onMove);
      el.removeEventListener('pointerleave', onLeave);
      gsap.killTweensOf(box);
    };
  }, [duration]);

  /* Visibility and content follow the hovered row, not the pointer. */
  useEffect(() => {
    const box = panel.current;
    const canvas = surface.current;
    if (!box || !canvas) return;

    const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

    if (hovered !== null) {
      const plate = plates.current[hovered];
      const ctx = canvas.getContext('2d');
      if (plate && ctx) {
        ctx.clearRect(0, 0, canvas.width, canvas.height);
        ctx.drawImage(plate, 0, 0);
      }
    }

    gsap.to(box, {
      autoAlpha: hovered === null ? 0 : 1,
      scale: hovered === null ? 0.94 : 1,
      duration: reduced ? 0 : FADE_DURATION,
      ease: 'power3.out',
      // Only the fade is overwritten; the quickTo tweens own x and y and must
      // keep running underneath, which is exactly what 'auto' guarantees.
      overwrite: 'auto',
    });
  }, [hovered]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The follow effect removes both listeners and calls `gsap.killTweensOf(box)`, which disposes the two quickTo tweens. The mount effect separately kills tweens and runs `clearProps: "all"`, restoring the centring transform and opacity it set. The offscreen plate canvases are dropped by nulling the ref array; they are plain canvases, never object URLs, so there is nothing to revoke.

**Reduced motion.** No `pointermove` listener attaches. The panel docks to the right edge, vertically centred, and hovering a row swaps its plate with a zero-duration cross-fade. The preview still works; it simply never moves.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Calling `gsap.to()` in the `pointermove` handler. It allocates a tween per event and every new one competes with the still-running previous tween for `x`, so the panel judders under fast movement — exactly when the follow is most visible.
- Putting the panel position in React state. Every pointer event becomes a render of the whole list; the follow gets slower the more rows you add, which is a scaling failure with no obvious cause at the call site.
- Omitting the start value on the first call after entry. The panel eases in from wherever it was abandoned, so re-entering the list gives a full second of a panel flying across the layout before it means anything.
- Centring with a negative margin or `left: -130px` as well as `xPercent: -50`. The two offsets compose and the panel sits half a width away from the pointer — a bug that looks like a follow-lag problem and is not one.
- Running `clearProps: "all"` in the cleanup of an effect that only owns `x` and `y`. Any dependency change then wipes the `xPercent`/`yPercent` centring and the `autoAlpha` state owned by a different effect, and the panel jumps or flashes to full opacity mid-hover. Each effect must tear down only what it set.
- Using `overwrite: true` on the fade tween. It kills the quickTo tweens that own `x` and `y`, and the panel freezes in place the moment you move between rows. `overwrite: "auto"` only claims the properties the fade actually animates.
- Transitioning `all` on the row text. The panel and rows share a stacking context, and a blanket transition catches `transform`, which then fights whatever else is animating it.

## Notes

- Gated on `(pointer: fine)`. On touch there is no hover and a `pointermove` only exists mid-drag, so the panel would live directly under the finger dragging it. The touch path docks the panel to the right edge and cross-fades on row change instead, which keeps the preview useful without pretending there is a cursor.
- Reduced motion takes the same docked path — a second of drift is precisely what that user opted out of — and the cross-fade duration drops to 0.
- Both branches read the same `docked()` predicate, so the follow effect and the dock effect can never disagree about which mode the component is in.
- The panel is `aria-hidden` and `pointer-events-none`: it is decoration for the row title, which remains the accessible content.

## Definition of done

Hover a row and the panel fades up over ~350ms while scaling from 0.94. Move the pointer and it follows with about a second of lag, always heading toward the pointer and never quite catching it. Move fast between rows and the image cross-fades while the follow keeps running underneath — the panel never freezes. Leave and re-enter the list and the panel appears at the pointer, not sailing in from the far side. On touch or with reduced motion the panel sits docked at the right edge and only its contents change.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Radial Mask Spotlight

A stacked layer is masked by a radial gradient whose centre follows the pointer, so content is lit rather than uncovered. The mask string is rewritten once per animation frame from a damped pointer position, and both the prefixed and unprefixed `mask-image` properties are set.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A layer masked to a soft disc follows the pointer, with a flat core that makes it read as a beam.

- Category: cursor
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. The gradient stops are the design: solid black to 30% of the radius, then a ramp to transparent at 72%. That flat core gives the beam a lit region with an actual size. A gradient that begins falling off at 0% has no lit area at all — just a bright point that fades, which the eye reads as blur rather than as light.
2. A px radius is used rather than a percentage. A percentage radius in a radial gradient resolves against the element box, so the same declaration produces a beam of a different physical size in every panel it is dropped into, and the effect stops being reusable.
3. Position comes from `useSmoothPointer` with a very low smoothing factor, so the beam has a small amount of drag. `damp` is frame-rate independent — the smoothing constant is the fraction of the gap left after one full second — so the same value produces the same feel at 60Hz and 144Hz rather than the beam arriving twice as fast on a fast display.
4. The mask is written in a `useRaf` callback, not in the pointer handler. Setting `mask-image` invalidates paint for the layer, and a fast pointer delivers two or three events per frame, so a per-event write does the same expensive work several times to produce one visible result.
5. The layer is seeded with a mask parked two radii off-panel, so the first painted frame — before rAF has run once — cannot show the layer unmasked. Nothing is written until `pointer.active` is true, which is what stops the beam flashing at the hook's centre-parked seed position on mount.
6. Both `maskImage` and `WebkitMaskImage` are set. This is not defensive habit: released Safari versions mishandle gradient masks without the prefix, and the failure mode is the layer being fully visible or fully invisible rather than slightly wrong.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `radius = 220`
  Beam radius in px, giving a 132px solid core and a 92px falloff. Below ~120 the core is too small to hold a line of text and the effect becomes a magnifier; above ~350 in a small panel the falloff never completes inside the box and the beam reads as an uneven wash.
- `CORE_STOP = 0.3`
  Where the solid region ends. This is the single number that separates "a light" from "a smudge". At 0 there is no lit area, only a peak; past ~0.5 the edge becomes hard enough that it reads as a cut-out hole instead of illumination.
- `EDGE_STOP = 0.72`
  Where the falloff reaches zero. Short of 100% so the gradient completes inside its own radius and the beam never shows a visible circular boundary at the edge of the declared circle.
- `smoothing = 0.0006`
  Fraction of the remaining distance still uncovered after one second — so the beam is effectively caught up within about 100ms. Enough drag to give the light some weight, not enough for the beam to visibly trail behind the thing you are pointing at, which would make it useless for reading.
- `FADE_MS = 260`
  Enter and leave fade on the whole layer. Long enough that the beam does not blink on and off as the pointer crosses the edge, short enough that leaving does not leave a light hanging in an unhovered panel.
- `rest mask offset = -radius * 2`
  Where the seeded mask sits before the first frame. Two radii guarantees no part of the falloff is inside the box at any panel size, so nothing is lit before the pointer has been seen.

## API

```ts
function RadialMaskSpotlight(props: { children: ReactNode; radius?: number; smoothing?: number; className?: string }): JSX.Element
```

- `children: ReactNode`
  Content of the lit layer. Should have a transparent background.
- `radius: number` — default `220`
  Beam radius in CSS px. Core is 30% of this, falloff completes at 72%.
- `smoothing: number` — default `0.0006`
  Fraction of the gap remaining after one second. Lower is tighter.
- `className: string`
  Merged onto the root container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** Where the solid core ends, as a fraction of `radius`. */
const CORE_STOP = 0.3;
/** Where the falloff reaches full transparency, as a fraction of `radius`. */
const EDGE_STOP = 0.72;
const FADE_MS = 260;

export function RadialMaskSpotlight({
  children,
  radius = 220,
  smoothing = 0.0006,
  className,
}: RadialMaskSpotlightProps) {
  const root = useRef<HTMLDivElement>(null);
  const lit = useRef<HTMLDivElement>(null);
  const enabled = useRef(false);
  const visible = useRef(false);

  const pointer = useSmoothPointer({
    target: root,
    smoothing,
    // Touch is explicitly off: this component is fine-pointer only, and
    // letting touch drags drive the mask would move the beam under the finger.
    touch: false,
  });

  useEffect(() => {
    const el = root.current;
    const layer = lit.current;
    if (!el || !layer) return;

    const fine = window.matchMedia('(pointer: fine)').matches;
    const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

    if (!fine) {
      /* No pointer to track. Rather than leaving a masked layer invisible, the
         mask is removed entirely so the lit layer simply shows in full — the
         content stays readable and nothing is hidden behind an effect that
         cannot be operated. */
      layer.style.maskImage = '';
      layer.style.webkitMaskImage = '';
      layer.style.opacity = '1';
      return;
    }

    enabled.current = !reduced;

    if (reduced) {
      /* Reduced motion keeps the spotlight — it is a hover affordance, not
         gratuitous movement — but pins it. A beam that chases the pointer with
         inertia is the part that was objected to, so the mask is written once,
         parked, and never updated again. */
      const rect = el.getBoundingClientRect();
      writeMask(layer, rect.width * 0.5, rect.height * 0.45, radius);
      layer.style.opacity = '1';
      return;
    }

    const onEnter = () => {
      visible.current = true;
      layer.style.opacity = '1';
    };
    const onLeave = () => {
      visible.current = false;
      layer.style.opacity = '0';
    };

    el.addEventListener('pointerenter', onEnter);
    el.addEventListener('pointerleave', onLeave);

    return () => {
      el.removeEventListener('pointerenter', onEnter);
      el.removeEventListener('pointerleave', onLeave);
      enabled.current = false;
      layer.style.maskImage = '';
      layer.style.webkitMaskImage = '';
      layer.style.opacity = '';
    };
  }, [radius]);

  useRaf(() => {
    const layer = lit.current;
    if (!layer || !enabled.current) return;
    const p = pointer.current;
    // `active` is false until a real pointer has been seen. Writing before
    // that would place the beam at the hook's centre-parked seed value, which
    // flashes a spotlight the user never asked for.
    if (!p.active) return;
    writeMask(layer, p.x, p.y, radius);
  });

  return (
    <div ref={root} className={cn('relative isolate overflow-hidden', className)}>
      <div
        ref={lit}
        className="absolute inset-0"
        style={{
          opacity: 0,
          transition: `opacity ${FADE_MS}ms ease-out`,
          // Seeded off-panel so the very first painted frame cannot show an
          // unmasked layer before rAF runs.
          maskImage: restMask(radius),
          WebkitMaskImage: restMask(radius),
        }}
      >
        {children}
      </div>
    </div>
  );
}

function maskFor(x: number, y: number, radius: number): string {
  /* `circle <radius>px at <x>px <y>px` — an explicit px radius rather than a
     percentage, because a percentage radius in a radial gradient resolves
     against the box and would make the beam a different physical size on
     every panel it is dropped into. */
  return `radial-gradient(circle ${radius}px at ${x}px ${y}px, #000 0%, #000 ${
    CORE_STOP * 100
  }%, transparent ${EDGE_STOP * 100}%)`;
}

function restMask(radius: number): string {
  return maskFor(-radius * 2, -radius * 2, radius);
}

function writeMask(layer: HTMLElement, x: number, y: number, radius: number) {
  const value = maskFor(x, y, radius);
  /* Both spellings. Safari has shipped unprefixed `mask-image` for years but
     still mishandles gradient masks without `-webkit-` in enough released
     versions that dropping the prefix means the layer is either fully visible
     or fully gone on those browsers — a total failure, not a degraded one. */
  layer.style.maskImage = value;
  layer.style.webkitMaskImage = value;
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the enter and leave listeners, flips the enabled flag so any in-flight frame is a no-op, and clears the inline `maskImage`, `WebkitMaskImage` and `opacity`. `useRaf` and `useSmoothPointer` unsubscribe themselves. Nothing was allocated beyond the two strings written per frame.

**Reduced motion.** The spotlight is still drawn — it is a hover affordance and removing it would hide content — but it never moves. The mask is written once at 50% across and 45% down, the rAF loop is left disabled, and no pointer listeners attach.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- A linear falloff from 0%. Without a flat core there is no lit region, just a bright centre that fades continuously, and the result reads as a blurred blob rather than a light. This is the most common way this effect is built and the most common reason it looks cheap.
- Setting only `maskImage`. Released Safari versions mishandle gradient masks without `-webkit-mask-image`, and the failure is total — the layer is either always visible or never visible — so it does not look like a mask bug when reported.
- Writing the mask in the `pointermove` handler. Every write invalidates paint for the layer, and a fast pointer produces several events per frame, so the same paint is thrown away two or three times before anything reaches the screen.
- A percentage radius. `circle 30% at ...` resolves against the element box, so the beam is a different size in every container and the constant that looked right in the design mock is wrong everywhere else.
- Writing the mask before the pointer has actually been seen. `useSmoothPointer` parks at the element centre so the first movement eases out sensibly, but that seed is not a real position — treating it as one flashes a spotlight in the middle of the panel on mount.
- Masking a layer containing interactive elements. `mask-image` does not clip hit testing, so links in the dark region are still clickable while being invisible. Either keep the masked layer non-interactive or accept that the mask is purely decorative.
- Putting the effect on a layer with its own background. The mask reveals the layer, and a masked opaque background is a visible disc of colour, not a light. The lit layer needs a transparent background so the beam shows content, not a shape.

## Notes

- Gated on `(pointer: fine)`. On touch the mask is removed entirely and the lit layer shows in full rather than staying hidden — an effect that cannot be operated must not be allowed to hide content. `useSmoothPointer` is also configured with `touch: false` so a scroll drag can never move the beam.
- Reduced motion keeps the spotlight but pins it: the mask is written once, centred slightly above middle, and never updated. The affordance survives; the chasing does not.
- Scoped to its own container and measured against its rect, so several instances can appear on one page without interfering.
- The masked layer is decorative by construction. If it holds links, remember that a mask hides paint but not hit testing.

## Definition of done

Move across the panel and a soft round beam follows the pointer with a slight drag, lighting the content under it. The centre of the beam is evenly lit rather than brightest at one point — cover the middle third with a finger and the light should look flat, not peaked. Enter and leave and the whole layer fades over about a quarter of a second rather than blinking. On first load, before you move, nothing is lit. Check in Safari that the beam appears at all. On touch the layer is fully visible with no mask.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Radial Ripple Dot Cloud

Several thousand dots in one draw call, with a wave travelling outward from a point left of centre. The displacement is a sine in radius minus a phase in time, attenuated exponentially, so the field is violent near the source and nearly still at the rim — which is what gives the motion an origin rather than making it a screensaver. Dot density along the radius is a hand-placed cubic B-spline, so the rings and gaps in the layout are drawn rather than derived from a formula.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A dot field with a travelling wave running out of one off-centre point, its density drawn by hand as a B-spline.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. Rest positions are baked once, in field units, into an `aOrigin` attribute: the field spans ±16/9 horizontally and ±1 vertically. The draw-time uniform `uCover = max(1, aspect / (16/9))` scales that field to cover the camera, so a resize writes one float instead of rebuilding a buffer.
2. Density along the radius comes from a uniform cubic B-spline over eight hand-placed control points — five spans — evaluated in JS at bake time. `bsplineWeights(t)` returns the four basis values `[(1-t)³, 4-6t²+3t³, 1+3t+3t²-3t³, t³] / 6` and `sampleRamp` blends control points `i..i+3`. The curve is C2 and does not pass through its control points, which is what lets a hand-placed sequence stay smooth.
3. Positions are chosen by rejection sampling: a seeded candidate uniform over the field rectangle is kept with probability `ramp(dist / maxRadius)`, where `maxRadius` is the distance from the ripple source to the farthest field corner. That is the only way to realise an arbitrary drawn radial density from a uniform PRNG without inverting the curve analytically.
4. The same ramp value is baked into `aScale` (0.55 + 0.75d) and `aAlpha` (0.3 + 0.7d), so a sparse band is also a dim band. Two independent curves would let them disagree and the field would read as noise with holes in it.
5. The vertex shader computes `dist = length(origin - uCenter)`, `wave = sin(dist * uFrequency - uElapsed * uSpeed)` — a travelling wave, because the time term is subtracted from the radius term — and `attenuated = wave * exp(-dist * uDecay)`, then displaces each dot along its own outward direction by `attenuated * uAmplitude`.
6. The direction is guarded: `dir = dist > 1e-5 ? delta / dist : vec2(0.0)`, because normalising a zero vector at the exact source yields NaN and one NaN vertex takes the whole point with it.
7. `gl_PointSize` is floored at 2 device pixels and the alpha is divided by the area that flooring invented, so the cloud has the same density on a 1x monitor as on a 3x phone. The fragment shader cuts a disc with `1 - smoothstep(0.42, 0.5, d)` and tints toward `uCrestColor` by the signed wave, so only the outgoing crest lights up.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `FIELD_HALF_W = 16 / 9`
  Half-width of the baked field, with the field 2 units tall. Baking at one fixed aspect is what makes a resize a single uniform write; 16:9 is the aspect most containers are near, so `uCover` is usually 1 and nothing is scaled at all.
- `DENSITY_RAMP = [1, 1, 0.34, 0.28, 0.92, 0.5, 0, -0.15]`
  Eight control points, so five spans. Sampled it reads 0.89 / 0.44 / 0.40 / 0.74 / 0.49 / 0.06 — dense core, gap, secondary band at ~60% radius, empty rim. The last point is negative deliberately: a control point is not a value, and pulling it below zero is what makes the tail actually reach zero instead of settling around 0.15.
- `centerX = 0.4`
  Ripple source at 40% of the width rather than 50%. A centred radial wave is bilaterally symmetric and the eye reads symmetry as a screensaver; a source off the axis reads as an impact somewhere in the scene.
- `frequency = 6.5 rad per field unit`
  Wavelength 2π/6.5 ≈ 0.97 units, about half the field height, so roughly two and a half crests fit between the source and the far corner. Past ~12 the rings alias against the dot spacing and the field boils; below ~3 there is only one crest and no ripple to read.
- `speed = 2.4 rad per second`
  Crest speed is speed / frequency = 0.37 field units per second, so a crest crosses the field in about six seconds. Fast enough to be motion, slow enough that the eye can follow a single ring outward.
- `decay = 0.85 per field unit`
  Amplitude is 43% at one unit from the source and 13% at the far corner, which gives the wave a source without a visible boundary. A linear falloff reaches exactly zero at a fixed radius and draws a hard circle there.
- `amplitude = 0.045 field units`
  2.25% of the field height — around 25px on a 1100px-tall field, in the same range as the 18px the technique was observed at. Past ~0.12 dots cross each other and the cloud shears instead of rippling.
- `size = 2.6 CSS pixels`
  Base diameter, scaled 0.55..1.3 per dot. Under ~2 the hardware point-size floor kicks in for most dots and the alpha compensation is doing all the work; over ~5 the dense core fills solid and the ripple stops being legible.
- `count = 6000`
  One interleaved-free buffer, one draw call. At this size the field is vertex-bound rather than fill-bound, and 6000 is roughly where the core reads as continuous without the gaps needing more dots to hide them.
- `MAX_ATTEMPTS_PER_DOT = 24`
  Rejection-sampling budget. The mean of the ramp is about 0.45, so ~2.2 attempts per kept dot; a 24x budget absorbs a much sparser custom curve and still terminates rather than spinning forever if someone authors a ramp that is zero everywhere.
- `STATIC_ELAPSED = 3.4 s`
  The frame drawn under reduced motion. Far enough in that two crests have left the source, so the still frame shows the ripple structure rather than the undisturbed lattice.

## API

```ts
function RadialRippleDotCloud(props: { count?: number; size?: number; frequency?: number; speed?: number; decay?: number; amplitude?: number; centerX?: number; centerY?: number; color?: string; crestColor?: string; opacity?: number; seed?: number | string; className?: string }): JSX.Element
```

- `count: number` — default `6000`
  Dots kept after density rejection. One draw call regardless.
- `size: number` — default `2.6`
  Base dot diameter in CSS pixels, before the per-dot density scale.
- `frequency: number` — default `6.5`
  Radians of wave per field unit; wavelength is 2π / frequency.
- `speed: number` — default `2.4`
  Radians of phase per second. Crest speed is speed / frequency.
- `decay: number` — default `0.85`
  Exponential attenuation per field unit of radius.
- `amplitude: number` — default `0.045`
  Peak displacement in field units, where the field is 2 units tall.
- `centerX: number` — default `0.4`
  Ripple source across the field, 0..1. Deliberately not centred.
- `centerY: number` — default `0.5`
  Ripple source down the field, 0..1.
- `color: string` — default `'#5d6b7a'`
  Dot colour in the troughs.
- `crestColor: string` — default `'#eaf2ff'`
  Dot colour on an outgoing crest.
- `opacity: number` — default `1`
  Multiplier applied after the per-dot area compensation.
- `seed: number | string` — default `'radial-ripple-dot-cloud'`
  Seeds rejection sampling, so the layout is stable across reloads and matches the server.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** Uniform cubic B-spline basis at parameter `t` within one span. */
function bsplineWeights(t: number): [number, number, number, number] {
  const t2 = t * t;
  const t3 = t2 * t;
  return [
    (1 - 3 * t + 3 * t2 - t3) / 6,
    (4 - 6 * t2 + 3 * t3) / 6,
    (1 + 3 * t + 3 * t2 - 3 * t3) / 6,
    t3 / 6,
  ];
}

/**
 * Sample the density curve at `u` in 0..1. `n` control points give `n - 3`
 * spans; the curve is C2 and does NOT pass through its control points, which
 * is the property that lets a hand-placed sequence stay smooth.
 */
function sampleRamp(ramp: readonly number[], u: number): number {
  const spans = ramp.length - 3;
  if (spans < 1) return clamp(ramp[0] ?? 0, 0, 1);
  const s = clamp(u, 0, 1) * spans;
  const span = Math.min(Math.floor(s), spans - 1);
  const weights = bsplineWeights(s - span);
  let total = 0;
  for (let k = 0; k < 4; k += 1) {
    total += (ramp[span + k] ?? 0) * (weights[k] ?? 0);
  }
  return clamp(total, 0, 1);
}

export function RadialRippleDotCloud({
  count = 6000,
  size = 2.6,
  frequency = 6.5,
  speed = 2.4,
  decay = 0.85,
  amplitude = 0.045,
  centerX = 0.4,
  centerY = 0.5,
  color = '#5d6b7a',
  crestColor = '#eaf2ff',
  opacity = 1,
  seed = 'radial-ripple-dot-cloud',
  className,
}: RadialRippleDotCloudProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  const { width, height } = useResizeObserver(host);
  const size2 = useRef({ width, height });
  size2.current = { width, height };

  const reduced = useReducedMotion();
  const visible = useVisibility();
  const { inView } = useInView(host, { threshold: 0 });
  const ready = width > 0 && height > 0;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    if (!hasWebGL()) {
      setUnsupported(true);
      return;
    }

    const renderer = new THREE.WebGLRenderer({ antialias: false, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setClearAlpha(0);

    const scene = new THREE.Scene();
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
    camera.position.z = 1;

    // Field-unit centre of the ripple. Baked alongside the origins so the
    // normalised radius each dot stores is measured from the same point the
    // shader will use.
    const cx = (centerX * 2 - 1) * FIELD_HALF_W;
    const cy = 1 - centerY * 2;

    /* The farthest corner from the source. Normalising radius by this is what
       makes the density ramp aspect-independent: the tail of the curve lands on
       the corner of the field rather than at some arbitrary unit distance. */
    const maxRadius = Math.max(
      Math.hypot(FIELD_HALF_W - cx, 1 - cy),
      Math.hypot(FIELD_HALF_W + cx, 1 - cy),
      Math.hypot(FIELD_HALF_W - cx, 1 + cy),
      Math.hypot(FIELD_HALF_W + cx, 1 + cy),
    );

    /* Rejection sampling against the density curve. Candidates are uniform over
       the field rectangle and kept with probability `ramp(r)`, which is the only
       way to get an arbitrary hand-drawn radial density out of a uniform PRNG
       without inverting the curve analytically. Seeded, so the layout is
       identical on the server, on the client, and on every reload. */
    const rng = createRng(seed);
    const wanted = Math.max(1, Math.round(count));
    const origins: number[] = [];
    const scales: number[] = [];
    const alphas: number[] = [];

    let attempts = 0;
    const budget = wanted * MAX_ATTEMPTS_PER_DOT;
    while (origins.length < wanted * 2 && attempts < budget) {
      attempts += 1;
      const x = (rng() * 2 - 1) * FIELD_HALF_W;
      const y = rng() * 2 - 1;
      const density = sampleRamp(DENSITY_RAMP, Math.hypot(x - cx, y - cy) / maxRadius);
      if (rng() > density) continue;
      origins.push(x, y);
      // The ramp is reused for weight as well as for density, so a sparse band
      // is also a dim one. Two curves would let them disagree and the field
      // would read as noise with holes in it.
      scales.push(0.55 + 0.75 * density);
      alphas.push(0.3 + 0.7 * density);
    }

    const kept = scales.length;
    const positions = new Float32Array(kept * 3); // zeros; the shader positions
    const originAttr = new Float32Array(kept * 2);
    const scaleAttr = new Float32Array(kept);
    const alphaAttr = new Float32Array(kept);
    for (let i = 0; i < kept; i += 1) {
      originAttr[i * 2] = origins[i * 2] ?? 0;
      originAttr[i * 2 + 1] = origins[i * 2 + 1] ?? 0;
      scaleAttr[i] = scales[i] ?? 1;
      alphaAttr[i] = alphas[i] ?? 1;
    }

    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
    geometry.setAttribute('aOrigin', new THREE.BufferAttribute(originAttr, 2));
    geometry.setAttribute('aScale', new THREE.BufferAttribute(scaleAttr, 1));
    geometry.setAttribute('aAlpha', new THREE.BufferAttribute(alphaAttr, 1));

    const uniforms: Uniforms = {
      uElapsed: { value: 0 },
      uCover: { value: 1 },
      uCenter: { value: new THREE.Vector2(cx, cy) },
      uFrequency: { value: frequency },
      uSpeed: { value: speed },
      uDecay: { value: decay },
      uAmplitude: { value: amplitude },
      uSize: { value: size },
      uPixelRatio: { value: renderer.getPixelRatio() },
      uColor: { value: new THREE.Color(color) },
      uCrestColor: { value: new THREE.Color(crestColor) },
      uOpacity: { value: opacity },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: RADIAL_RIPPLE_VERT,
      fragmentShader: RADIAL_RIPPLE_FRAG,
      uniforms,
      transparent: true,
      depthTest: false,
      depthWrite: false,
      // Additive, because overlapping dots in the dense core should read as
      // brighter rather than as a flat plate of the same colour.
      blending: THREE.AdditiveBlending,
    });

    const points = new THREE.Points(geometry, material);
    // Every vertex is displaced in the shader, so three's bounding sphere is
    // wrong by construction and culling against it can blank the whole cloud.
    points.frustumCulled = false;
    scene.add(points);

    el.appendChild(renderer.domElement);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';

    const resize = (w: number, h: number) => {
      if (w <= 0 || h <= 0) return;
      renderer.setSize(w, h, false);
      const aspect = w / h;
      camera.left = -aspect;
      camera.right = aspect;
      camera.top = 1;
      camera.bottom = -1;
      camera.updateProjectionMatrix();

      /* Cover, not contain. Past 16:9 the baked field is narrower than the
         camera, so it is scaled up until it reaches both edges; the alternative
         is a visible vertical seam where the dots stop. The centre is scaled by
         the same factor so the ripple stays put relative to the field. */
      const cover = Math.max(1, aspect / FIELD_HALF_W);
      uniforms.uCover.value = cover;
      uniforms.uCenter.value.set(cx * cover, cy * cover);
      // Re-read: moving a window between displays changes devicePixelRatio
      // without changing the CSS size, and dot sizes are specified in CSS px.
      uniforms.uPixelRatio.value = renderer.getPixelRatio();
    };

    const draw = (elapsed: number) => {
      uniforms.uElapsed.value = elapsed;
      renderer.render(scene, camera);
    };

    resize(size2.current.width, size2.current.height);
    stage.current = { resize, draw };
    draw(STATIC_ELAPSED);

    return () => {
      stage.current = null;
      disposeObject(scene);
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
  }, [
    ready,
    count,
    size,
    frequency,
    speed,
    decay,
    amplitude,
    centerX,
    centerY,
    color,
    crestColor,
    opacity,
    seed,
  ]);

  useEffect(() => {
    stage.current?.resize(width, height);
    // A resize clears the drawing buffer, so the frozen frame has to be
    // redrawn or a reduced-motion visitor sees an empty box after any reflow.
    if (reduced) stage.current?.draw(STATIC_ELAPSED);
  }, [width, height, reduced]);

  useRaf(
    (_dt, elapsed) => stage.current?.draw(elapsed),
    ready && inView && visible && !reduced && !unsupported,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nulls the stage ref, walks the scene with `disposeObject` to release the geometry and its four attribute buffers, disposes the ShaderMaterial explicitly, then calls `disposeRenderer` — `dispose` plus `forceContextLoss` plus a zeroed drawing buffer — and removes the canvas. The canvas is created inside the effect and appended imperatively rather than being owned by a React ref, so a StrictMode double-mount builds a fresh context instead of handing back the one that was just killed.

**Reduced motion.** The component reads `useReducedMotion` itself and opens no rAF subscription. One frame is drawn at `uElapsed = 3.4`, by which point two crests have left the source — so the still image shows the ripple structure and the drawn density bands, not the undisturbed lattice. The layout, the colours and the crest tinting are all present; only the travel stops. The frame is re-drawn on resize because a canvas resize clears the buffer.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Writing `sin(dist * frequency) * sin(elapsed * speed)`. That is a standing wave: the rings pulse in place and never travel. Subtracting the phase from the radius inside one sine is what makes crests move outward — and adding it instead sends them inward, which reads as a drain rather than an impact.
- Normalising the offset vector without guarding the source. At `dist == 0` the division produces NaN, the vertex is discarded by the rasteriser, and on some drivers the whole primitive goes with it — an intermittently missing dot that is very hard to attribute.
- Attenuating the radius instead of the wave, or using a linear falloff. Linear reaches zero at a fixed radius and draws a visible circle across the field; the exponential never quite reaches zero and has no edge.
- Rebuilding the position buffer on resize. It reallocates hundreds of kilobytes during a window drag and, if the layout is re-sampled, re-randomises every dot mid-motion. Baking in field units and scaling by one `uCover` uniform avoids both.
- Leaving `frustumCulled` at its default. Every vertex is displaced in the shader, so three's bounding sphere — computed from the undisplaced attribute — is wrong, and the whole cloud can vanish when the camera or the container changes.
- Using `Math.random()` for the layout. The server and the client disagree, so React logs a hydration mismatch, and the composition a designer approved is not the one the next visitor sees.
- Treating the B-spline control points as points on the curve. The curve does not pass through them — the value at the start of the first span is `(P0 + 4P1 + P2) / 6`. Authoring the ramp as if it were interpolating produces a flatter, wrong curve and hours of confusion.
- Driving dot brightness from a second curve independent of the density curve. Where they disagree the field reads as random noise with holes in it rather than as drawn bands.
- Forgetting that a resize clears the drawing buffer. Under reduced motion nothing redraws afterwards, so the component is blank after any reflow unless the frozen frame is re-rendered.

## Notes

- The camera is orthographic, ±aspect by ±1, so field units are directly comparable to the container height: 1 unit is half the visible height.
- `uCover` implements cover, not contain. Past 16:9 the baked field would otherwise stop short of the container edge and leave a visible vertical seam where the dots end.
- The ripple runs on absolute elapsed time from the shared rAF clock, so several instances on one page stay in phase with each other.

## Definition of done

Rings of dots visibly travel outward from a point left of centre, roughly two crests visible at a time, brightening as each crest passes and dimming behind it. The rim of the field barely moves. The layout has obvious drawn structure — a dense core, a gap, a second band — and is identical after a reload and after resizing the window. With reduced motion the field renders in full and holds a frozen mid-ripple frame.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Realtime Cube EnvMap

A `CubeCamera` sits inside the reflector and renders the six directions around it every other frame; that cube texture is assigned straight onto the material as its `envMap`. Because the panels supplying the reflection are orbiting, the highlights crawl across the surface instead of being painted on. No HDRI, no loader, no asset — the environment is scene geometry.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A metal knot reflecting panels that are actually orbiting it, captured six faces at a time every other frame.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. A `WebGLCubeRenderTarget(resolution, { generateMipmaps: true, minFilter: LinearMipmapLinearFilter })` backs a `CubeCamera(0.1, 60, target)` positioned at the reflector, and `cubeTarget.texture` is assigned to `material.envMap` once at build time — the texture object never changes identity, only its contents.
2. The environment is built from geometry: an inside-out `SphereGeometry(16)` with `side: BackSide` carrying a vertical gradient `CanvasTexture`, plus `panelCount` `PlaneGeometry` emitters on a ring of radius `panelRadius`, each `lookAt(0,0,0)` and lifted by `sin(i * 2.39996) * 0.9` so the reflection has vertical structure to move through.
3. Panels alternate bright and near-black via `color.setHSL(hue + i*26, i%2 ? 0.4 : 0.66, i%2 ? 0.08 : 0.62)`. The dark ones are load-bearing: a uniformly bright environment gives a mirror nothing to contrast against and the metal reads as matte plastic.
4. Each frame the ring and the reflector are rotated from `elapsed`, then — only on frames where `frames % refreshEvery === 0` — the reflector is set `visible = false`, `cubeCamera.update(renderer, scene)` runs, and it is set visible again before the single visible `renderer.render`.
5. Resize lives in its own effect: it sets renderer size, sets `camera.aspect`, moves the camera to `BASE_DISTANCE / Math.min(1, aspect)` so a portrait container does not clip the panel ring off both sides, and forces one capture plus one redraw so a reflow never leaves a stale or black frame on screen.
6. Teardown disposes the shell texture, both geometries, every panel material, the reflector material, then `cubeTarget.dispose()` — the cube target is not in the scene graph, so `disposeObject` never reaches it — and finally `disposeRenderer`, which is what calls `forceContextLoss()`.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `refreshEvery = 2`
  Cube captures per rendered frame. Six faces is six scene renders against the visible pass's one, so this is 6/7 of the component's cost. An env map is sampled by direction, not position, so at these rotation speeds a one-frame-old capture is not observable; at 4 or more the highlights visibly step.
- `resolution = 256`
  Cube face size. Cost is 6 x resolution² fragments plus a mip chain — about 2 MB of GPU memory. At 128 the panel edges alias into the reflection as jagged bands; above 512 nothing improves because roughness immediately blurs the detail away.
- `roughness = 0.08`
  Not 0. A perfect mirror shows the panels as hard-edged rectangles and every seam in the cube map becomes visible; a slight roughness selects a lower mip and softens exactly those seams. Above ~0.3 the reflection stops being readable as a scene at all.
- `envMapIntensity = 1.4`
  Reflected light multiplier. At 1 a dark environment leaves the object nearly invisible against the shell; above ~2 the bright panels clip to flat white and the curvature information in the highlight is lost.
- `panelRadius = 4.2`
  Ring radius against a ~1.4-unit reflector. Closer and the panels enter the camera frustum and read as walls rather than as light sources; further and they subtend too small an angle to produce a highlight worth reflecting.
- `BASE_DISTANCE = 7.2`
  Camera distance at aspect >= 1, chosen against a 34 degree field of view so the reflector fills about two thirds of the frame height. Divided by `min(1, aspect)` on narrower containers.
- `STATIC_POSE = 0.9`
  The `elapsed` value used for the reduced-motion still and for post-resize redraws. Not 0: at zero the knot is axis-aligned and the panels sit on the cardinal directions, which reads as a technical diagram instead of a lit object.
- `lift stagger = sin(i * 2.39996) * 0.9`
  2.39996 rad is the golden angle, so successive panels never repeat a height for any panel count. A constant height puts every panel in one band and the reflection has nothing to travel through vertically.

## API

```ts
function RealtimeCubeEnvmap(props: { shape?: 'knot' | 'icosahedron'; panelCount?: number; panelRadius?: number; spinSpeed?: number; objectSpin?: number; resolution?: number; refreshEvery?: number; roughness?: number; metalness?: number; envMapIntensity?: number; hue?: number; className?: string }): JSX.Element
```

- `shape: 'knot' | 'icosahedron'` — default `'knot'`
  Reflector silhouette. The knot has more curvature and so more reflection per pixel.
- `panelCount: number` — default `7`
  Emitting panels on the ring. Odd counts keep bright and dark panels from pairing off across the object.
- `panelRadius: number` — default `4.2`
  Ring radius in world units.
- `spinSpeed: number` — default `0.18`
  Panel ring rotation, radians per second. This is what makes the reflection move.
- `objectSpin: number` — default `0.32`
  Reflector rotation about Y, radians per second. X spins at 0.55 of this.
- `resolution: number` — default `256`
  Cube face size in pixels. Cost is six faces plus mips.
- `refreshEvery: number` — default `2`
  Capture the cube map every Nth rendered frame. 1 captures every frame.
- `roughness: number` — default `0.08`
  Surface roughness, which selects the env map mip level.
- `metalness: number` — default `1`
  1 is a mirror; 0 is diffuse and lit only by the env map.
- `envMapIntensity: number` — default `1.4`
  Multiplier on reflected light.
- `hue: number` — default `208`
  Base hue in degrees for the panels and the shell gradient.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function RealtimeCubeEnvmap({
  shape = 'knot',
  panelCount = 7,
  panelRadius = 4.2,
  spinSpeed = 0.18,
  objectSpin = 0.32,
  resolution = 256,
  refreshEvery = 2,
  roughness = 0.08,
  metalness = 1,
  envMapIntensity = 1.4,
  hue = 208,
  className,
}: RealtimeCubeEnvmapProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);

  const { width, height } = useResizeObserver(host);
  const { inView } = useInView(host, { threshold: 0 });
  const visible = useVisibility();
  const reduced = useReducedMotion();

  const [supported, setSupported] = useState(true);
  useEffect(() => setSupported(hasWebGL()), []);

  const size = useRef({ width, height });
  size.current = { width, height };

  const ready = width > 1 && height > 1 && supported;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: false });
    renderer.setPixelRatio(pixelRatio());
    renderer.setSize(el.clientWidth, el.clientHeight, false);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';
    el.appendChild(renderer.domElement);

    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(FIELD_OF_VIEW, 1, 0.1, 60);
    camera.position.set(0, 0.35, BASE_DISTANCE);
    camera.lookAt(0, 0, 0);

    // The shell is the environment's floor and sky in one object: a sphere
    // turned inside out. It is what the cube camera sees in every direction
    // the panels do not cover, so without it the reflection has large holes of
    // clear-colour black and the object reads as unlit rather than dark.
    const shellTexture = new THREE.CanvasTexture(makeShellTexture(hue));
    shellTexture.colorSpace = THREE.SRGBColorSpace;
    const shellGeometry = new THREE.SphereGeometry(16, 32, 16);
    const shellMaterial = new THREE.MeshBasicMaterial({
      map: shellTexture,
      side: THREE.BackSide,
    });
    scene.add(new THREE.Mesh(shellGeometry, shellMaterial));

    // Panels. Their arrangement is a pure function of the index — there is no
    // random scatter here, so there is no seed to keep in step between the
    // server render and the client one.
    const ring = new THREE.Group();
    const panelGeometry = new THREE.PlaneGeometry(1.5, 3.4);
    const panelMaterials: THREE.MeshBasicMaterial[] = [];
    const count = Math.max(2, Math.round(panelCount));

    for (let i = 0; i < count; i += 1) {
      const material = new THREE.MeshBasicMaterial({ side: THREE.DoubleSide });
      // Alternating bright and near-black panels. An environment that is
      // uniformly bright gives a mirror nothing to contrast against and the
      // metal reads as matte plastic; the dark panels are what draw the
      // specular edges.
      const bright = i % 2 === 0;
      material.color.setHSL(
        ((hue + i * 26) % 360) / 360,
        bright ? 0.66 : 0.4,
        bright ? 0.62 : 0.08,
      );
      panelMaterials.push(material);

      const panel = new THREE.Mesh(panelGeometry, material);
      const angle = (i / count) * Math.PI * 2;
      // Golden-angle stagger on the height, so the panels do not sit in a
      // single band and the reflection has vertical structure to move through.
      const lift = Math.sin(i * 2.39996) * 0.9;
      panel.position.set(
        Math.sin(angle) * panelRadius,
        lift,
        Math.cos(angle) * panelRadius,
      );
      panel.lookAt(0, 0, 0);
      ring.add(panel);
    }
    scene.add(ring);

    const reflectorGeometry =
      shape === 'knot'
        ? new THREE.TorusKnotGeometry(0.92, 0.31, 220, 32)
        : new THREE.IcosahedronGeometry(1.35, 2);

    // Mipmaps are not optional here. `roughness` selects a mip level of the
    // env map, so a cube target without them samples level 0 at every
    // roughness and the surface stays a hard mirror no matter what you pass.
    const cubeTarget = new THREE.WebGLCubeRenderTarget(Math.max(16, Math.round(resolution)), {
      generateMipmaps: true,
      minFilter: THREE.LinearMipmapLinearFilter,
    });
    const cubeCamera = new THREE.CubeCamera(0.1, 60, cubeTarget);
    // Co-located with the reflector: an env map is sampled by direction, so
    // the capture point is the only position information it carries. Offset it
    // and the reflections belong to a different object.
    cubeCamera.position.set(0, 0, 0);
    scene.add(cubeCamera);

    const material = new THREE.MeshPhysicalMaterial({
      metalness,
      roughness,
      envMapIntensity,
      // Assigned to the material rather than `scene.environment` on purpose.
      // A live capture belongs to one object at one point in space; sharing it
      // scene-wide would give every reflector the same viewpoint.
      envMap: cubeTarget.texture,
      color: 0xffffff,
    });
    const reflector = new THREE.Mesh(reflectorGeometry, material);
    scene.add(reflector);

    const throttle = Math.max(1, Math.round(refreshEvery));
    let frames = 0;

    const draw = (elapsed: number, forceCapture: boolean) => {
      ring.rotation.y = elapsed * spinSpeed;
      reflector.rotation.y = elapsed * objectSpin;
      reflector.rotation.x = elapsed * objectSpin * 0.55;

      frames += 1;
      if (forceCapture || frames % throttle === 0) {
        // Hide, capture, show — in that order, inside one frame. Skipping the
        // hide is the classic version of this bug: the object captures itself
        // and within a second the surface is a recursive tunnel.
        reflector.visible = false;
        cubeCamera.update(renderer, scene);
        reflector.visible = true;
      }

      renderer.render(scene, camera);
    };

    const resize = (w: number, h: number) => {
      if (w < 1 || h < 1) return;
      const aspect = w / h;
      renderer.setPixelRatio(pixelRatio());
      renderer.setSize(w, h, false);
      camera.aspect = aspect;
      // Pull the camera back on narrow containers. A fixed distance frames the
      // object on height alone, so a portrait preview clips the panel ring off
      // both sides and the reflections lose their source.
      camera.position.z = BASE_DISTANCE / Math.min(1, aspect);
      camera.updateProjectionMatrix();
    };

    resize(size.current.width, size.current.height);
    stage.current = { renderer, scene, camera, cubeTarget, resize, draw };
    // First frame forces a capture: with an empty cube map a metal surface is
    // pure black, and on a throttled refresh that black would be on screen for
    // `refreshEvery` frames.
    draw(STATIC_POSE, true);

    return () => {
      stage.current = null;
      scene.remove(cubeCamera);
      // Order matters: free the scene graph's GPU objects while the context is
      // still alive, then hand the context itself back.
      disposeObject(scene);
      shellTexture.dispose();
      shellGeometry.dispose();
      shellMaterial.dispose();
      panelGeometry.dispose();
      for (const panelMaterial of panelMaterials) panelMaterial.dispose();
      reflectorGeometry.dispose();
      material.dispose();
      // The cube target is not in the scene graph, so nothing above reaches
      // it. It holds six faces plus their mip chain — at 256px that is about
      // 2 MB of GPU memory per instance.
      cubeTarget.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
  }, [
    ready,
    shape,
    panelCount,
    panelRadius,
    spinSpeed,
    objectSpin,
    resolution,
    refreshEvery,
    roughness,
    metalness,
    envMapIntensity,
    hue,
  ]);

  // Resize in its own effect: a container reflow costs a `setSize` and one
  // redraw rather than a rebuild of the geometry and the cube target.
  useEffect(() => {
    const current = stage.current;
    if (!current) return;
    current.resize(width, height);
    current.draw(STATIC_POSE, true);
  }, [width, height, reduced]);

  useRaf(
    (_dt, elapsed) => stage.current?.draw(elapsed, false),
    ready && inView && visible && !reduced,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `disposeObject(scene)` walks the graph, then the shell canvas texture, shell and panel geometries, every panel material and the reflector material are disposed explicitly, then `cubeTarget.dispose()` releases the six faces and their mip chain, then `disposeRenderer(renderer)` calls `dispose()` and `forceContextLoss()` and zeroes the backing store, and the canvas node is removed. The `CubeCamera` is removed from the scene first so nothing holds a reference to a disposed target.

**Reduced motion.** The rAF subscription is never made, and the scene is drawn once at `STATIC_POSE` with a forced cube capture — a fully reflective still with the panels off the cardinal axes. Reflections, gradient shell and material are all exactly as they are in motion; only the rotation is absent. Resizing redraws the same pose rather than resuming.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Capturing with the reflector visible. It photographs its own previous frame, the next capture includes that photograph, and within about a second the surface is a recursive tunnel of dark shells. Hide it, capture, show it — inside the same frame, so it is never absent from the visible render.
- Creating the cube target without mipmaps. `roughness` picks a mip level of the env map; with only level 0 available the surface stays a hard mirror at every roughness value and the prop appears to do nothing.
- Refreshing the cube map every frame because it looks like the honest thing to do. That is seven scene renders per displayed frame, and it is the difference between a preview grid that holds 60fps and one that does not.
- Rendering the first frame without forcing a capture. An unwritten cube map is black, a metal surface reflecting black is black, and on a throttled refresh that black sits on screen for `refreshEvery` frames as a visible flash.
- Building the environment out of bright panels only. Metal is read entirely from the contrast between light and dark in its surroundings; with no dark panels the highlights have no edges and the material looks like painted plastic.
- Letting `disposeObject(scene)` stand in for cube-target cleanup. The target is not a child of anything, so nothing traverses it, and six faces plus mips leak per mount — which under StrictMode double-invocation is two leaks per page load.
- Leaving the camera distance fixed. Framing on height alone means a portrait container crops the panel ring away entirely, and the object loses the thing it is reflecting.

## Notes

- No lights in the scene. `metalness: 1` with `roughness` near 0 is lit purely by its environment, so a light would contribute almost nothing while adding a uniform to every shader compile.
- `transmission` is deliberately not exposed. Three renders a separate full-scene pass per transmissive object, which on top of six cube faces triples the frame cost for an effect the cube map already implies.
- The panel arrangement is a pure function of the index, so there is no RNG and nothing to seed — server and client markup cannot disagree.

## Definition of done

The bright bands on the object crawl across its surface continuously while it turns, and the same colours are visible on the panels orbiting behind it. There is no dark recursive tunnel anywhere on the surface at any moment. Raising `roughness` toward 0.3 progressively blurs the reflection instead of leaving it a hard mirror. Resize the container and the object stays fully in frame in both landscape and portrait. Mount and unmount a dozen instances and none of the earlier ones go black.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Re-Key Caption Replay

A wrapper that replays a staggered entrance every time its `entryKey` changes. It does it by being a different node: React unmounts the old caption and mounts a new one, and a freshly mounted element starts its CSS animation at frame zero. No forced reflow to restart the animation, no tween to kill, and a fast prev/next cannot leave the block half-entered because the half-entered node no longer exists.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A caption block whose staggered entrance replays on every index change, restarted by a changed React key.

- Category: transition
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. The children are wrapped in a single `<div key={entryKey}>`. Changing `entryKey` makes React discard that subtree and mount a fresh one; a new element runs its `animation` from frame zero, which is the entire replay mechanism. The key goes on the wrapper, not on each child — keyed individually, only the children whose own identity changed would replay, which for a caption is usually none of them.
2. One keyframe, `kinetic-rekey-in`, runs `opacity: 0` and `translateY(var(--kx-rekey-from))` to `opacity: 1` and `translateY(0)` over 0.5 s on `cubic-bezier(0.22, 1, 0.36, 1)`. Because the offset is a custom property rather than a literal, flipping its sign on the root turns a rise into a drop — both directions from one set of keyframes.
3. The stagger is a generated ladder of `:nth-child(n) { animation-delay: calc(var(--kx-rekey-stagger) * (n - 1)) }` rules, built once at module scope for the first eight children. A ninth-and-beyond rule pins the tail to the eighth delay, so an overlong block degrades to "the tail arrives together" rather than "the tail arrives first at delay zero".
4. `animation-fill-mode: both` is what makes the delay usable. Without it a delayed line is painted at its normal full-opacity style for the length of its own delay, then snaps to the from-frame to begin animating — every line flashes before it enters.
5. The stylesheet is emitted once through React 19's `<style href precedence>` hoisting, so duration, stagger and offset are read from CSS custom properties set on the wrapper. Ten captions on a page share one rule block and differ only in their variables.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `duration = 0.5`
  Seconds per line. With the 0.06 s stagger, a four-line block finishes in 0.68 s — under the ~0.7 s where a caption change starts to feel like waiting. Halve it and the ease has no room to decelerate, so the rise reads as a jump.
- `distance = 14`
  Pixels travelled. Roughly one line of leading at caption size: enough for the eye to register direction, small enough that the text is never far from where it lands. Past ~30 px the block reads as flying in from off-panel.
- `stagger = 0.06`
  Seconds between lines. At 0 the block is one object; past ~0.12 s the metadata is still arriving after the title has settled, which reads as a slow network rather than a sequence.
- `ease = cubic-bezier(0.22, 1, 0.36, 1)`
  An out-quart. It covers about 80% of the distance in the first third of the duration, so the line appears to arrive fast and then settle — which is what hides the fact that nothing is actually decelerating.
- `MAX_STAGGERED_LINES = 8`
  How many nth-child rules are generated. Eight covers eyebrow, title, two metadata rows and a counter with room spare. The number exists because CSS cannot do arithmetic on the child index, so the ladder has to be finite.

## API

```ts
function RekeyCaptionReplay(props: { entryKey: string | number; children: ReactNode; duration?: number; distance?: number; stagger?: number; direction?: "up" | "down"; className?: string }): JSX.Element
```

- `entryKey: string | number`
  Identity of the current caption. Any change replays the entrance.
- `children: ReactNode`
  Direct children each get their own delay, in source order.
- `duration: number` — default `0.5`
  Seconds one line's entrance lasts.
- `distance: number` — default `14`
  Pixels a line travels. Signed by `direction`.
- `stagger: number` — default `0.06`
  Seconds between successive lines. 0 makes the block arrive as one piece.
- `direction: "up" | "down"` — default `"up"`
  `up` enters from below; `down` enters from above, for a step backward.
- `className: string`
  Merged onto the keyed wrapper via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * How many direct children get their own delay. Eight covers eyebrow, title,
 * two metadata rows and a counter with room to spare; children past the eighth
 * are pinned to the eighth's delay rather than falling back to zero, so an
 * overlong block degrades to "the tail arrives together" instead of "the tail
 * arrives first".
 */
const MAX_STAGGERED_LINES = 8;

const STAGGER_RULES = [
  ...Array.from(
    { length: MAX_STAGGERED_LINES },
    (_, i) =>
      `.kinetic-rekey > :nth-child(${i + 1}) { animation-delay: calc(var(--kx-rekey-stagger, 0.06s) * ${i}); }`,
  ),
  `.kinetic-rekey > :nth-child(n + ${MAX_STAGGERED_LINES + 1}) { animation-delay: calc(var(--kx-rekey-stagger, 0.06s) * ${MAX_STAGGERED_LINES - 1}); }`,
].join('\n');

const REKEY_CSS = `
@keyframes kinetic-rekey-in {
  from { opacity: 0; transform: translateY(var(--kx-rekey-from, 14px)); }
  to   { opacity: 1; transform: translateY(0); }
}
/* One keyframe covers both directions: the offset is a custom property, so
   flipping its sign on the root turns a rise into a drop without a second
   set of keyframes to keep in sync. */
.kinetic-rekey > * {
  animation: var(--kx-rekey-duration, 0.5s) cubic-bezier(0.22, 1, 0.36, 1)
    both kinetic-rekey-in;
}
${STAGGER_RULES}
@media (prefers-reduced-motion: reduce) {
  /* The still state IS the destination: full opacity, no offset. Dropping the
     animation re-exposes those as the base values, which is why there is
     nothing to declare here beyond 'none'. A zero-duration animation would
     instead hold whatever 'both' resolved and still fire animationend. */
  .kinetic-rekey > * { animation: none; }
}
`;

export interface RekeyCaptionReplayProps {
  /**
   * Identity of the current caption. Any change replays the entrance — in a
   * slideshow this is the slide index, in a filter it is the active facet.
   */
  entryKey: string | number;
  /** Direct children each get their own delay, in source order. */
  children: ReactNode;
  /** Seconds one line's entrance lasts. */
  duration?: number;
  /** Pixels a line travels. Signed by `direction`. */
  distance?: number;
  /** Seconds between successive lines. 0 makes the block arrive as one piece. */
  stagger?: number;
  /**
   * `up` enters from below — the default, and correct for advancing forward.
   * `down` enters from above, which is what makes a step backward read as a
   * step backward rather than as another step forward.
   */
  direction?: 'up' | 'down';
  className?: string;
}

export function RekeyCaptionReplay({
  entryKey,
  children,
  duration = 0.5,
  distance = 14,
  stagger = 0.06,
  direction = 'up',
  className,
}: RekeyCaptionReplayProps) {
  const from = direction === 'up' ? distance : -distance;

  return (
    <>
      <style href="kinetic-rekey-caption-replay" precedence="medium">
        {REKEY_CSS}
      </style>

      {/* The key is on this wrapper, so every child is a new node on every
          change and every child animation restarts. Putting the key on the
          children individually would replay only the ones whose own identity
          changed, which for a caption is usually none of them. */}
      <div
        key={entryKey}
        className={cn('kinetic-rekey', className)}
        style={
          {
            '--kx-rekey-duration': `${duration}s`,
            '--kx-rekey-stagger': `${stagger}s`,
            '--kx-rekey-from': `${from}px`,
          } as CSSProperties
        }
      >
        {children}
      </div>
    </>
  );
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nothing to clean up. There are no listeners, no timers, no rAF and no tweens — the animation is CSS and the nodes running it are removed by React itself on every key change.

**Reduced motion.** `animation: none` on the children, which re-exposes their base styles — full opacity, no offset. The caption is fully rendered on the first frame after the key change, in its final position. This is the one case where dropping the animation is the correct still state rather than a cop-out, because the from-frame is the only thing the animation adds.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Restarting the animation by toggling a class off and on. The browser coalesces both mutations into one style recalculation and the animation never restarts, which is why that approach always ends up with a `void el.offsetWidth` forced reflow wedged between the two lines.
- Tweening the caption with an animation library instead. A fast prev/next leaves two opposing tweens on the same node and the text jitters between them; a remount cannot have that problem because the contended node is gone.
- Omitting `animation-fill-mode: both`. Every delayed line paints at full opacity for the length of its delay, then snaps to invisible to start animating. The block flickers, and it flickers worse the larger the stagger.
- Putting the key on the individual lines. Their identities usually do not change between captions, so React reuses the nodes and nothing replays — the most common way this technique silently does nothing.
- Wrapping anything focusable or stateful. The remount destroys DOM state and moves focus to the body: an input inside this loses its caret and its value on every key change. This is for display content only.
- Animating both directions with a second keyframe block. The two drift apart the first time someone tunes the offset. One keyframe reading a signed custom property cannot.

## Notes

- Pairs with a counter badge and prev/next controls to make a slideshow caption, which is where the technique was observed. The same wrapper works for a filter result header, a hovered-row detail panel, or a step label in a multi-step form summary.
- Direction is a prop rather than something derived internally, because only the caller knows whether an index change was forward, backward, or a jump from a thumbnail strip.
- For the media beside the caption, a CSS `transition` on the background beats a tween: an index change is a discrete event with one start and one end state, which is exactly what a transition is for.

## Definition of done

Step forward and the eyebrow, title and metadata rise into place one after another, roughly 60 ms apart. Step backward and they drop in from above instead. Click next four times as fast as you can and every caption plays its full entrance from the start with no jitter or stuck line. With reduced motion the new caption is simply there, complete, on the first frame.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Relaxed Seeded Scatter

Half the points sit on an exact lattice and half are seeded noise; fifteen relaxation sweeps then push the noisy ones apart until no neighbour pair is closer than 40% of the mean spacing. The result keeps the liveliness of random placement without the clusters that read as a bug. The visualiser leaves a dashed ghost at each point's pre-relaxation angle, so the displacement is legible, and prints the smallest gap before and after.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Seeded angles around a ring, pushed apart until nothing collides. Ghost ticks mark where they started.

- Category: primitive
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. `floor(count * evenRatio)` points are written at `(i / fixedCount) * 2PI` and flagged fixed; the remainder get `rng() * 2PI` from `createRng(seed)`, a mulberry32 stream. The raw array is copied before anything moves so the two states can be compared and interpolated.
2. The target gap is `(2PI / count) * 0.4` — 40% of the mean spacing on the full ring, not on the random subset, so the floor means the same thing regardless of how many points are pinned.
3. Each sweep sorts the nodes by `mod(angle, 2PI)`, then walks consecutive pairs measuring `gap = mod(next.angle - current.angle, 2PI)`. Because `mod` always measures the short way round, the pair that straddles zero needs no special case.
4. When a gap is under target, each free endpoint is moved by `(target - gap) * 0.5` away from the other; if one endpoint is pinned to the lattice the free one absorbs the whole `(target - gap)` instead, or points pile up against the lattice and never separate.
5. Angles are stored unwrapped — a point pushed below zero keeps a small negative value rather than jumping to just under 2PI — so the component can interpolate `raw -> relaxed` linearly and never take the long way round. Only the sort and the gap measurement wrap.
6. The visualiser eases that interpolation over 1.4 s with `easeOutQuart` on the shared rAF loop, writing the `transform` attribute of one `<g>` per point. The SVG uses a `-50 -50 100 100` viewBox, so it resizes with its container and needs no ResizeObserver.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `RELAX_PASSES = 15`
  Each sweep removes about half the remaining overlap, so 15 leaves 2^-15 of the initial error — fully converged for any count up to ~64. At 3 passes the tightest pairs are still visibly paired; past ~20 nothing measurable changes and you are paying O(passes · n log n) for nothing.
- `MIN_GAP_RATIO = 0.4`
  Floor on the neighbour gap as a fraction of the mean, so `targetGap = 0.4 * 2PI / count`. Below ~0.25 clusters survive and the scatter still reads as clumped. Above ~0.6 the relaxation cannot satisfy every pair at once, so it oscillates between passes and converges toward the lattice — which throws away the randomness you asked for.
- `EVEN_RATIO = 0.5`
  Fraction pinned to the exact lattice. At 0 the composition has no skeleton and the eye finds no structure; at 1 it is a clock face. Half and half is the mix that reads as deliberate but not mechanical.
- `PUSH_SHARE = 0.5`
  Each free neighbour absorbs half the deficit, so a pair separates by exactly the deficit per sweep. At 1.0 both move the full amount, overshoot, and the pair oscillates instead of settling.
- `MORPH_DURATION = 1.4`
  Seconds for the raw-to-relaxed sweep. Long enough to follow individual points leaving their ghosts; under ~0.6 s it reads as a single cut and the comparison is lost.
- `seed = 'kinetic'`
  Any fixed value works — what matters is that it is fixed. `hashSeed` turns the string into a 32-bit integer, so a named seed per instance gives every ring its own reproducible composition.

## API

```ts
function relaxedRingAngles(count: number, seed: number | string, options?: { passes?: number; minGapRatio?: number; evenRatio?: number; pushShare?: number }): RelaxedRing;
function RelaxedSeededScatter(props: { count?: number; seed?: number | string; passes?: number; minGapRatio?: number; evenRatio?: number; morph?: boolean; className?: string }): JSX.Element
```

- `count: number` — default `24`
  Points on the ring.
- `seed: number | string` — default `'kinetic'`
  Fixed seed. Strings are hashed with `hashSeed`.
- `passes: number` — default `15`
  Relaxation sweeps.
- `minGapRatio: number` — default `0.4`
  Minimum neighbour gap as a fraction of the mean spacing.
- `evenRatio: number` — default `0.5`
  Fraction of points pinned to an exact lattice.
- `morph: boolean` — default `true`
  Ease from the raw angles to the relaxed ones on first view.
- `className: string`
  Merged onto the outer element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** Sweeps. Each halves the residual overlap; 15 is fully converged for n<=64. */
const RELAX_PASSES = 15;
/** Floor on the neighbour gap, as a fraction of the mean gap. */
const MIN_GAP_RATIO = 0.4;
/** Half the points sit on an exact lattice and never move. */
const EVEN_RATIO = 0.5;
/** Each free neighbour absorbs half the deficit. */
const PUSH_SHARE = 0.5;

type Node = { id: number; angle: number; fixed: boolean };

/** Smallest neighbour gap on the circle, and how many pairs are under `target`. */
function ringStats(values: ArrayLike<number>, target: number) {
  const n = values.length;
  if (n < 2) return { minGap: TAU, crowded: 0 };
  const sorted = Array.from(values, (v) => mod(v, TAU)).sort((a, b) => a - b);
  let minGap = TAU;
  let crowded = 0;
  for (let i = 0; i < n; i++) {
    const a = sorted[i] ?? 0;
    const b = sorted[(i + 1) % n] ?? 0;
    const gap = i === n - 1 ? b + TAU - a : b - a;
    if (gap < minGap) minGap = gap;
    if (gap < target) crowded++;
  }
  return { minGap, crowded };
}

export function relaxedRingAngles(
  count: number,
  seed: number | string,
  options: RelaxedRingOptions = {},
): RelaxedRing {
  const {
    passes = RELAX_PASSES,
    minGapRatio = MIN_GAP_RATIO,
    evenRatio = EVEN_RATIO,
    pushShare = PUSH_SHARE,
  } = options;

  const n = Math.max(0, Math.floor(count));
  const angles = new Float32Array(n);
  const raw = new Float32Array(n);
  const targetGap = n > 0 ? (TAU / n) * minGapRatio : 0;
  const fixedCount = Math.floor(n * evenRatio);

  if (n === 0) {
    return { angles, raw, minGap: 0, rawMinGap: 0, crowded: 0, rawCrowded: 0, targetGap, fixedCount };
  }

  // Half order: an exact lattice, so the composition has a skeleton.
  for (let i = 0; i < fixedCount; i++) angles[i] = (i / fixedCount) * TAU;
  // Half chaos: seeded, never Math.random().
  const rng = createRng(seed);
  for (let i = fixedCount; i < n; i++) angles[i] = rng() * TAU;
  raw.set(angles);

  const nodes: Node[] = Array.from({ length: n }, (unused, id) => ({
    id,
    angle: angles[id] ?? 0,
    fixed: id < fixedCount,
  }));

  for (let pass = 0; pass < passes && n > 1; pass++) {
    // Re-sort every sweep. A push can carry a point across zero, which
    // re-orders the ring; a gap computed from stale neighbours pushes the
    // wrong point and leaves a permanent clump at the wrap.
    nodes.sort((a, b) => mod(a.angle, TAU) - mod(b.angle, TAU));

    for (let i = 0; i < n; i++) {
      const a = nodes[i];
      const b = nodes[(i + 1) % n];
      if (!a || !b || a === b) continue;

      // mod() measures the gap the short way round, so the pair that straddles
      // zero needs no special case.
      const gap = mod(b.angle - a.angle, TAU);
      if (gap >= targetGap) continue;

      const deficit = (targetGap - gap) * pushShare;
      if (a.fixed && b.fixed) continue;
      // A pinned neighbour cannot absorb its share, so the free one takes all
      // of it. Otherwise points pile up against the lattice and never separate.
      if (a.fixed) b.angle += deficit * 2;
      else if (b.fixed) a.angle -= deficit * 2;
      else {
        a.angle -= deficit;
        b.angle += deficit;
      }
    }
  }

  for (const node of nodes) angles[node.id] = node.angle;

  const after = ringStats(angles, targetGap);
  const before = ringStats(raw, targetGap);

  return {
    angles,
    raw,
    minGap: after.minGap,
    rawMinGap: before.minGap,
    crowded: after.crowded,
    rawCrowded: before.crowded,
    targetGap,
    fixedCount,
  };
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useRaf` unsubscribes on unmount and the shared frame is cancelled when the last subscriber leaves; the loop also unsubscribes itself the moment the morph completes, so a settled ring costs nothing. `useInView` unobserves the root. No timers, no listeners, no retained typed arrays beyond the memo.

**Reduced motion.** The relaxed angles render immediately with no sweep. The dashed ghosts at the raw angles stay, so the before/after comparison the component exists to make is fully readable without anything moving, and the gap readout is unchanged.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- `Math.random()` instead of a seeded generator. The server renders one arrangement and the client another, React reports a hydration mismatch and re-renders the subtree, and the layout is different on every reload so no visual diff is ever reviewable.
- Not re-sorting between sweeps. A push can carry a point across zero, which re-orders the ring; the next sweep then measures the gap to a point that is no longer the neighbour, pushes the wrong one, and leaves a permanent clump sitting exactly on the wrap.
- Measuring the gap as `next - current`. For the pair that straddles zero that is a large negative number, which is always below the target, so the relaxation shoves those two apart on every sweep forever and one point walks all the way around the ring.
- Splitting the deficit evenly when one neighbour is pinned. The free point only ever gets half the correction it needs, so it converges to half the required gap and stays visibly stuck to the lattice tick.
- Wrapping the angles into `[0, 2PI)` on the way out. The interpolation from `raw` to `angles` then sends any point that crossed zero the long way round the ring, and one tick sweeps a full circle during the settle while the rest move a few degrees.
- Rebuilding the ring on every render. `relaxedRingAngles` is O(passes · n log n) and allocates; without `useMemo` keyed on the inputs, every parent render re-runs 15 sweeps and re-allocates two typed arrays.

## Notes

- Relaxing over the full ring with the lattice pinned is a deliberate deviation from the version this was taken from, which relaxed only the random subset against itself. That version lets a random point land exactly on a lattice point, which is the one collision the technique is supposed to prevent.
- `relaxedRingAngles` is the shipped part. Feed the angles into whatever you are placing — CSS `rotate()`, an instanced attribute, a `THREE.Vector3` per item — the visualiser is only here to show what the numbers do.

## Definition of done

On first scroll into view the solid ticks slide off their dashed ghosts and stop; every accent tick stays exactly on its ghost because the lattice is pinned. The "min gap" readout shows a struck-through small number followed by a larger one at or above the target. Reload ten times and the arrangement is byte-identical. Set `evenRatio` to 0 and every tick moves.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Rotary Drag Carousel

Items sit at fixed stations around a circle whose hub is below the frame, so only the top arc is ever visible. The gesture is measured in angle rather than pixels: `atan2(y - cy, x - cx)`, differenced through a shortest-signed wrap, so a hand sweeping the top of the wheel turns it by the amount it actually travelled around the hub. Release and it keeps going at the speed it left at, then stops with a station facing up — one motion, no corrective hop.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A wheel of cards you grab and spin. Angular drag, projected inertia, and it always lands on a station.

- Category: layout
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. Layout is a pure function of one number. For wheel angle `A`, station `i` sits at screen angle `theta = A + i * (360 / count) - 90`, at `(cx + R cos theta, cy + R sin theta)`, rotated by the shortest signed distance to the top, `away = wrapRange(theta + 90, -180, 180)`. `A` is unbounded and may be -4000 without consequence, because `away` is the only value that ever needs wrapping.
2. The radius is floored at `1.25 x containerHeight`, which forces the hub `cy = topInset * height + R` strictly below the box. That is a correctness constraint, not a look: `atan2` about a point the user can touch converts a two-pixel wobble near the hub into a hundred degrees of spin.
3. Each `pointermove` computes the pointer's own angle about the hub and adds `wrapRange(current - previous, -180, 180)` to `A`. The wrap is what keeps a drag across the 180° seam from reading as a 359° jerk backwards.
4. Release velocity is measured over a rolling ~70 ms window of `(angle, time)` rather than off the final delta. Because a stationary finger produces no `pointermove` events, the window never advances while the hand is still, and the measured speed decays toward zero on its own — "drag, pause, lift" therefore does not throw.
5. Inertia without a plugin: `power3.out` is `p(t) = 1 - (1 - t)^3`, so `p'(0) = 3`. A tween of duration `D` covering `delta` degrees departs at `3 * delta / D` deg/s, so setting `delta = v * D / 3` makes a plain `gsap.to` continue the gesture at exactly the speed the hand left.
6. That projected landing angle is rounded to a multiple of the station spacing *before* the tween is created, so the throw and the snap are the same tween. Snapping afterwards is a second animation starting from rest — the small hop that gives away a hand-rolled dial.
7. Pointer capture is taken on `pointerdown`, and the release path is one idempotent `finish` guarded on the stored `pointerId`, wired to `pointerup`, `pointercancel` and `lostpointercapture` alike. A drag that ends off-screen still lands.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `MIN_RADIUS_HEIGHT_RATIO = 1.25`
  Radius floor as a multiple of container height, so the hub is always below the visible box. At 1.0 the hub lands exactly on the bottom edge and a press there divides by a near-zero radius; below 1.0 it is reachable and the wheel spins wildly for a pointer that barely moved.
- `POWER3_OUT_SLOPE = 3`
  The initial derivative of `power3.out`, and the divisor in `delta = v * D / 3`. It is exact, not tuned: change the ease and this number changes with it — `power2.out` needs 2, `power4.out` needs 4. Leave it at 3 with a different ease and the throw either undershoots or overshoots by a constant factor.
- `throwDuration = 1.1`
  Seconds of inertial travel. Under ~0.6 s the wheel stops so abruptly that a fast fling feels like it hit a wall; over ~1.6 s the tail is so slow it reads as broken rather than as momentum, and it delays the settle callback past the point anyone is still watching.
- `maxThrow = 260`
  Degrees one throw may carry, applied to the projected distance before snapping. Without a cap, a 900 deg/s fling projects 330° and the wheel makes most of a revolution from a flick — past about 270° the user loses track of which way it went and which station is coming.
- `VELOCITY_WINDOW = 0.07`
  Seconds of gesture history the release speed is averaged over. Shorter and it is effectively the last delta, which is noisy at 120 Hz and jitters the throw distance between identical gestures; much longer and a deliberate slow-down before release is averaged away, so the wheel throws when the user meant to place it.
- `MAX_VELOCITY = 900`
  Degrees per second the measured speed is clamped to. A pointer that jumps (a tab switch mid-drag, a synthetic event, a coalesced move across the hub) can report thousands of deg/s; clamping keeps one bad sample from spinning the wheel several turns.
- `DRAG_THRESHOLD = 5`
  Pixels of travel before a press becomes a drag. Below ~3 the hand tremor in a normal tap counts as a drag, so every tap is swallowed as a gesture; above ~10 a small deliberate nudge of the wheel does nothing at all.
- `CULL_DEG = 96`
  Stations more than this far from the top are `visibility: hidden`. Just past 90° they are behind the horizontal through the hub and outside the box in every supported aspect ratio, so painting them is pure cost; culling at exactly 90° makes the boundary coincide with the fade reaching its floor and items visibly wink out.
- `radiusRatio = 0.78`
  Radius as a fraction of container width, before the height floor. Larger flattens the arc until the wheel reads as a straight row; much smaller pulls the hub up toward the box and the visible arc bends so hard that only three stations fit.
- `fade = 0.85`
  Opacity lost per 90° off the top. The station one step out stays clearly legible, which is the affordance that says the wheel turns; at 1.0 the neighbours reach zero exactly at the cull angle and the wheel looks like it holds one card.

## API

```ts
function RotaryDragCarousel(props: { children: ReactNode; radiusRatio?: number; topInsetRatio?: number; snapDeg?: number; throwDuration?: number; maxThrow?: number; fade?: number; scaleFalloff?: number; initialIndex?: number; className?: string; itemClassName?: string; onIndexChange?: (index: number) => void; 'aria-label'?: string }): JSX.Element
```

- `children: ReactNode`
  One item per child. Each gets a station on the wheel.
- `radiusRatio: number` — default `0.78`
  Wheel radius as a fraction of container width, floored against height so the hub stays below the box.
- `topInsetRatio: number` — default `0.08`
  Where the top of the wheel sits, as a fraction of container height.
- `snapDeg: number`
  Degrees the wheel snaps to. Defaults to one station, `360 / count`.
- `throwDuration: number` — default `1.1`
  Seconds of inertial travel after release.
- `maxThrow: number` — default `260`
  Hard cap on how far one throw may carry, in degrees.
- `fade: number` — default `0.85`
  Opacity lost per 90° away from the top station.
- `scaleFalloff: number` — default `0.22`
  Scale lost at 90° away from the top station.
- `initialIndex: number` — default `0`
  Station facing up on mount. Seeded once, never re-applied.
- `className: string`
  Merged onto the drag surface.
- `itemClassName: string`
  Merged onto every station. Size the items here.
- `onIndexChange: (index: number) => void`
  Fires with the wrapped index of the station that lands facing up.
- `aria-label: string` — default `'Carousel'`
  Label for the focusable wheel, which also takes arrow keys.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * Write one transform per station from the current wheel angle. A pure
 * function of `angleRef.current` and the box size — nothing accumulates in
 * here, so interrupting the throw tween mid-flight cannot desynchronise it.
 */
const layout = useCallback(() => {
  const host = hostRef.current;
  if (!host || count === 0) return;

  const width = host.clientWidth;
  const height = host.clientHeight;
  if (width < 1 || height < 1) return;

  const radius = Math.max(radiusRatio * width, height * MIN_RADIUS_HEIGHT_RATIO);
  const cx = width / 2;
  const cy = topInsetRatio * height + radius;
  const angle = angleRef.current;

  for (let i = 0; i < count; i += 1) {
    const station = stationsRef.current[i];
    if (!station) continue;

    // Station i's screen angle. `UP_DEG` puts station 0 at the top when the
    // wheel is at 0, so the maths and the visual agree at rest.
    const theta = angle + i * step + UP_DEG;
    // Shortest signed distance to the top, in (-180, 180]. The wheel is a
    // real circle, so this is the only place wrapping is needed at all —
    // `angle` itself may be -4000 without consequence.
    const away = wrapRange(theta - UP_DEG, -180, 180);
    const distance = Math.abs(away);

    if (distance > CULL_DEG) {
      station.style.visibility = 'hidden';
      continue;
    }

    const rad = theta * DEG_TO_RAD;
    const x = cx + radius * Math.cos(rad);
    const y = cy + radius * Math.sin(rad);
    const t = Math.min(distance / 90, 1);

    station.style.visibility = 'visible';
    // Counter-rotating by `-away` would keep the cards upright; leaving the
    // rotation in is what makes it read as one rigid wheel rather than a row
    // of cards travelling along an arc.
    station.style.transform =
      `translate(-50%, -50%) translate(${x.toFixed(2)}px, ${y.toFixed(2)}px) ` +
      `rotate(${away.toFixed(2)}deg) ` +
      `scale(${(1 - scaleFalloff * t).toFixed(3)})`;
    station.style.opacity = clamp(1 - fade * t, 0, 1).toFixed(3);
    station.style.zIndex = String(100 - Math.round(distance));
  }
}, [count, step, radiusRatio, topInsetRatio, fade, scaleFalloff]);

/** Angle at which station `index` faces up: `angle + index * step = 0`. */
const angleForIndex = useCallback((index: number) => -index * step, [step]);

const report = useCallback(() => {
  if (count === 0) return;
  // `angle = -i * step` puts station i up, so `i = -angle / step`.
  const index = wrapIndex(Math.round(-angleRef.current / step), count);
  if (index === reportedRef.current) return;
  reportedRef.current = index;
  notify.current?.(index);
}, [count, step]);

/**
 * Land the wheel. `velocity` is degrees per second at the moment of release;
 * pass 0 for a keyboard step or a tap.
 */
const settle = useCallback(
  (velocity: number) => {
    const projected =
      angleRef.current +
      clamp(
        (velocity * throwDuration) / POWER3_OUT_SLOPE,
        -maxThrow,
        maxThrow,
      );
    // Round to a station BEFORE tweening. Snapping afterwards is a second
    // animation that starts from rest, which is the little hop that gives
    // away every hand-rolled dial.
    const landing = Math.round(projected / snap) * snap;

    gsap.killTweensOf(angleRef);

    if (reduced || Math.abs(landing - angleRef.current) < 0.01) {
      angleRef.current = landing;
      layout();
      report();
      return;
    }

    gsap.to(angleRef, {
      current: landing,
      duration: throwDuration,
      ease: 'power3.out',
      overwrite: true,
      onUpdate: layout,
      onComplete: report,
    });
  },
  [throwDuration, maxThrow, snap, reduced, layout, report],
);

useEffect(() => {
  const host = hostRef.current;
  if (!host) return;

  let pointerId: number | null = null;
  let lastPointerAngle = 0;
  let pressX = 0;
  let pressY = 0;
  let moved = false;
  let swallowClick = false;
  /** Rolling window: the wheel angle and clock at the start of the window. */
  let sampleAngle = 0;
  let sampleTime = 0;

  const now = () => performance.now() / 1000;

  const pointerAngle = (clientX: number, clientY: number) => {
    const rect = host.getBoundingClientRect();
    const radius = Math.max(
      radiusRatio * rect.width,
      rect.height * MIN_RADIUS_HEIGHT_RATIO,
    );
    const cx = rect.left + rect.width / 2;
    const cy = rect.top + topInsetRatio * rect.height + radius;
    return Math.atan2(clientY - cy, clientX - cx) / DEG_TO_RAD;
  };

  const onPointerDown = (e: PointerEvent) => {
    // One pointer owns the wheel. A second finger arriving mid-throw would
    // otherwise reset the origin angle and the wheel would jump.
    if (pointerId !== null || !e.isPrimary) return;
    if (e.pointerType === 'mouse' && e.button !== 0) return;

    pointerId = e.pointerId;
    pressX = e.clientX;
    pressY = e.clientY;
    moved = false;
    lastPointerAngle = pointerAngle(e.clientX, e.clientY);
    sampleAngle = angleRef.current;
    sampleTime = now();

    // Capture on press, not once the threshold is crossed: by then the
    // pointer may already have left the element, and `pointermove` would
    // have stopped arriving.
    host.setPointerCapture(e.pointerId);
    gsap.killTweensOf(angleRef);
  };

  const onPointerMove = (e: PointerEvent) => {
    if (pointerId !== e.pointerId) return;

    const current = pointerAngle(e.clientX, e.clientY);
    // Shortest signed step. Without the wrap, dragging across the 180°
    // seam reads as a 359° jerk in the wrong direction.
    const delta = wrapRange(current - lastPointerAngle, -180, 180);
    lastPointerAngle = current;

    if (!moved) {
      if (Math.hypot(e.clientX - pressX, e.clientY - pressY) < DRAG_THRESHOLD) return;
      moved = true;
    }

    angleRef.current += delta;
    layout();

    // Retire the velocity window once it is full. Measuring over a window
    // rather than off the last delta is what stops "drag, pause, lift" from
    // throwing the wheel: with no movement there are no events, the window
    // never advances, and the measured speed decays toward zero on its own.
    const t = now();
    if (t - sampleTime > VELOCITY_WINDOW) {
      sampleAngle = angleRef.current;
      sampleTime = t;
    }
  };

  /**
   * Idempotent. Called from `pointerup`, `pointercancel` and
   * `lostpointercapture`, all three of which can be the last event a gesture
   * produces, and at least one of which will always arrive — including when
   * the pointer is released outside the window, or the OS takes it away for
   * a gesture of its own. Guarding on `pointerId` makes the extra calls
   * no-ops instead of a double throw.
   */
  const finish = (e: PointerEvent) => {
    if (pointerId !== e.pointerId) return;
    const id = pointerId;
    pointerId = null;

    const elapsed = now() - sampleTime;
    const velocity =
      moved && elapsed > 0
        ? clamp((angleRef.current - sampleAngle) / elapsed, -MAX_VELOCITY, MAX_VELOCITY)
        : 0;

    swallowClick = moved;
    moved = false;

    if (host.hasPointerCapture(id)) host.releasePointerCapture(id);
    settle(velocity);
  };

  // Capture phase, ahead of any child's own handler. A throw ends with a
  // `click` on whatever happens to be under the pointer, so without this the
  // gesture that spins the wheel also activates a card.
  const onClick = (e: MouseEvent) => {
    if (!swallowClick) return;
    swallowClick = false;
    e.preventDefault();
    e.stopPropagation();
  };

  const onKeyDown = (e: KeyboardEvent) => {
    const direction =
      e.key === 'ArrowRight' || e.key === 'ArrowDown'
        ? -1
        : e.key === 'ArrowLeft' || e.key === 'ArrowUp'
          ? 1
          : 0;
    if (direction === 0) return;
    e.preventDefault();
    gsap.killTweensOf(angleRef);
    angleRef.current = Math.round(angleRef.current / snap) * snap + direction * snap;
    settle(0);
  };

  host.addEventListener('pointerdown', onPointerDown);
  host.addEventListener('pointermove', onPointerMove);
  host.addEventListener('pointerup', finish);
  host.addEventListener('pointercancel', finish);
  host.addEventListener('lostpointercapture', finish);
  host.addEventListener('click', onClick, true);
  host.addEventListener('keydown', onKeyDown);

  return () => {
    host.removeEventListener('pointerdown', onPointerDown);
    host.removeEventListener('pointermove', onPointerMove);
    host.removeEventListener('pointerup', finish);
    host.removeEventListener('pointercancel', finish);
    host.removeEventListener('lostpointercapture', finish);
    host.removeEventListener('click', onClick, true);
    host.removeEventListener('keydown', onKeyDown);
    if (pointerId !== null && host.hasPointerCapture(pointerId)) {
      host.releasePointerCapture(pointerId);
    }
    pointerId = null;
  };
}, [layout, settle, snap, radiusRatio, topInsetRatio]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes `pointerdown`, `pointermove`, `pointerup`, `pointercancel`, `lostpointercapture`, the capture-phase `click` and `keydown`; releases pointer capture if a gesture is still live at unmount; and kills the throw tween on the angle ref via a separate effect so an in-flight `gsap.to` cannot call `onUpdate` against detached nodes. The shared resize observer unregisters. Nothing but inline styles on the stations remains, and those die with the nodes.

**Reduced motion.** Dragging is unchanged — it is the user's own motion, tracked one-to-one, and removing it would remove the component. What goes away is everything the component would have animated by itself: the inertial throw is not created, so release rounds the current angle to the nearest station and assigns it in one frame, and an arrow key moves one station instantly. The wheel never travels further than the hand did.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Driving the rotation from `deltaX` instead of from an angle. A linear delta turns the wheel by the same amount wherever you grab it, so a drag near the left edge feels geared wrong and a drag straight down the middle does nothing at all. Angular input is what makes it feel like a physical wheel.
- Differencing raw `atan2` output. Crossing the ±180° seam gives a delta of about -359° instead of +1°, and the wheel snaps a full turn backwards once per revolution. Every angle difference here goes through `wrapRange(d, -180, 180)`.
- Putting the hub inside the container. Near the hub the pointer's angular change per pixel goes to infinity, so a press within a few pixels of it and a one-pixel jitter spins the wheel a hundred degrees. The radius floor makes that geometrically impossible rather than guarding it after the fact.
- Taking the release velocity from the last `pointermove`. Drag, hold still for half a second, lift, and the wheel flies off at the speed from before the pause, because the last event recorded was the last time the hand moved. A rolling time window measured against `performance.now()` at release decays to zero on its own.
- Snapping after the inertial tween instead of before it. The throw finishes, comes to rest between two stations, and a second tween hops it into place — two eases back to back, and it is instantly recognisable as fake momentum.
- Calling `setPointerCapture` only after the drag threshold is crossed. By then a fast gesture has already left the element, `pointermove` has stopped arriving, and the wheel sticks at the angle it had when the pointer crossed the boundary.
- Handling only `pointerup`. Release outside the window, let the OS claim the gesture, or have the element re-parented mid-drag and no `pointerup` arrives; the wheel stays captured and frozen mid-throw. `pointercancel` and `lostpointercapture` both route to the same idempotent finish, guarded on the stored `pointerId` so the duplicate is a no-op rather than a second throw.
- Letting the click through. A throw ends with a `click` dispatched on whatever card is under the pointer, so spinning the wheel also opens a project. The click is swallowed in the capture phase, once, only when the gesture actually moved.
- Reaching for `InertiaPlugin`. It is a Club GreenSock plugin — not redistributable, and not installable from a public registry — so a component that depends on it fails to build for most consumers. The `v * D / 3` projection reproduces the throw with the free core.
- Re-seeding `initialIndex` on resize. Rotate a phone mid-gesture and the wheel teleports back to its opening station. The seed is guarded by a ref and runs exactly once.

## Notes

- The counter-rotation is deliberately absent: each card is rotated *with* the wheel by `away`, so the whole thing reads as one rigid disc. Cancelling that rotation keeps labels upright but turns it into a row of cards sliding along an arc, which is a different and much weaker effect.
- The snap grid is a multiple of `360 / count`, so a station always lands facing up. The source of this technique snapped to a fixed 10°, which only coincides with item positions when `360 / count` is itself a multiple of 10 — with 7 or 9 items it lands between cards.
- Arrow keys step one station and route through the same settle path, so keyboard and pointer cannot disagree about where the wheel rests.

## Definition of done

Grab anywhere in the box and drag in an arc: the wheel follows your hand around the hub, and a drag near the left or right edge turns it less than the same pixel distance across the top. Fling and release — it keeps going, decelerates, and comes to rest with one card exactly upright, in a single continuous motion with no hop at the end. Drag, hold still for a second, then lift: it settles to the nearest station without throwing. Start a drag, move the pointer off the window, and release outside — the wheel still lands rather than freezing. Release over a card and no click reaches it; tap the same card without moving and the click goes through. Arrow keys step one card at a time.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Preloader That Cannot Hang

Every hand-rolled preloader eventually ships the same bug: a signal that never arrives — a 404 on a font, a decode that fails on iOS, an image behind a dead CDN — and the site is a permanent opaque rectangle nobody can see through or tab past. This inverts the contract. A hard ceiling guarantees the page is visible by a fixed time and the load signal only ever makes it sooner; a floor stops a warm cache turning the overlay into a two-frame flash; a session flag keeps it an introduction rather than a toll booth.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

An intro overlay with a hard ceiling, a minimum visible time and a once-per-session flag, so a stalled load cannot trap the page.

- Category: transition
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. A three-state phase machine — `holding`, `leaving`, `gone` — drives the render. It starts at `holding` on both server and client so the markup matches, and the session check runs in a `useLayoutEffect`, before paint, so a returning visitor never sees a single frame of the overlay.
2. THE CEILING: `setTimeout(reveal, ceilingMs)` is armed in an effect on mount, before anything subscribes to a load signal, and nothing clears it except a successful reveal or unmount. This is not a fallback — it is the actual guarantee, and the load signal is the optimisation.
3. THE FLOOR: when the signal does arrive, the remaining hold is `Math.max(0, floorMs - (performance.now() - started))` and the reveal is deferred by that much. Measured from mount, not from the signal, so the floor overlaps the load instead of being added to it.
4. The signal is `ready` when the prop is passed, otherwise the browser's own: `document.readyState === "complete"` is checked first and only then is a one-shot `load` listener attached, because if the document has already finished the event has been and gone and a listener alone would wait forever.
5. ONCE: on reveal, `sessionStorage[sessionKey] = "1"`, wrapped in try/catch because `setItem` throws in Safari private browsing and a preloader is not worth taking the page down for. Both the read and the write are guarded.
6. `reveal()` guards on a ref, not on state, so the ceiling and the floor firing in the same tick still reveal exactly once. It sets `leaving` — a CSS opacity transition on `[data-leaving="true"]` — and schedules the actual removal `fadeMs` later, so the node is never pulled out of the tree mid-transition. `onDone` fires from that same timer, after the overlay is gone.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `ceilingMs = 4000`
  The reveal deadline. Long enough that a genuinely slow first paint on a cold 3G connection is not cut off mid-load, short enough that a user staring at a broken overlay gives up after it rather than before. Past ~6s people reload, which restarts the same stall.
- `floorMs = 700`
  Minimum visible time. On a warm cache the signal resolves in about 40ms; without a floor the overlay appears and vanishes inside two frames, which reads as a rendering fault rather than an introduction. Below ~400ms the fade has no room to be perceived as deliberate.
- `fadeMs = 420`
  Fade-out duration, passed to CSS as `--k-safe-fade` and used as the removal delay so the two can never disagree. Long enough that the page underneath is already composited and visible through the fade; past ~700ms the user is looking at content they cannot yet click.
- `fade easing = cubic-bezier(0.22, 1, 0.36, 1)`
  Heavily front-loaded, so most of the opacity is gone in the first third and the perceived wait is shorter than the measured one. A linear fade of the same length feels about twice as long.
- `scan bar = 1.4s cubic-bezier(0.65, 0, 0.35, 1) infinite`
  A determinate progress bar would be a lie — nothing here knows a byte count. This is an indeterminate scan whose cycle is slow enough not to read as urgency and fast enough to prove the page is not frozen. The in-out curve keeps the ends from clipping at the container edges.
- `sessionKey = 'k-preloader'`
  Session, not local, storage. Local storage would mean the introduction plays once ever, so a returning visitor months later gets no reveal and QA can never see it again without clearing site data.

## API

```ts
function SafePreloader(props: { children?: ReactNode; ready?: boolean; ceilingMs?: number; floorMs?: number; fadeMs?: number; sessionKey?: string; once?: boolean; onDone?: () => void; position?: 'fixed' | 'absolute'; className?: string }): JSX.Element | null
```

- `children: ReactNode`
  Overlay content. Defaults to a label and an indeterminate scan bar.
- `ready: boolean`
  The load signal. Leave undefined to use the browser's own `load` event and `readyState`.
- `ceilingMs: number` — default `4000`
  Hard ceiling. The reveal happens by this time whether or not the signal ever arrives.
- `floorMs: number` — default `700`
  Minimum time the overlay stays up, measured from mount.
- `fadeMs: number` — default `420`
  Fade-out duration in ms. Also the delay before the node is removed.
- `sessionKey: string` — default `'k-preloader'`
  sessionStorage key used by the once-per-session gate.
- `once: boolean` — default `true`
  Set false to replay on every load, for development.
- `onDone: () => void`
  Fires after the overlay has finished leaving and unmounted.
- `position: 'fixed' | 'absolute'` — default `'fixed'`
  Absolute lets the overlay be scoped to a container instead of the viewport.
- `className: string`
  Merged onto the overlay via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const reveal = useCallback(() => {
  if (revealed.current) return;
  revealed.current = true;
  clearTimers();
  if (once) markShown(sessionKey);
  setPhase('leaving');
  // The node is removed only after the fade has actually run, so nothing is
  // pulled out of the tree mid-transition.
  timers.current.push(
    setTimeout(
      () => {
        setPhase('gone');
        done.current?.();
      },
      reduced ? 0 : fadeMs,
    ),
  );
}, [clearTimers, fadeMs, once, reduced, sessionKey]);

useLayoutEffect(() => {
  if (once && wasShown(sessionKey)) {
    revealed.current = true;
    setPhase('gone');
    return;
  }
  started.current = performance.now();
}, [once, sessionKey]);

// THE CEILING. Armed on mount, before any load signal is subscribed to, and
// never cancelled by anything except a successful reveal. If the signal
// never comes, this is what saves the page.
useEffect(() => {
  if (revealed.current) return;
  const id = setTimeout(reveal, ceilingMs);
  timers.current.push(id);
  return () => clearTimeout(id);
}, [ceilingMs, reveal]);

// THE FLOOR. When the signal arrives, wait out whatever is left of the
// minimum so a warm cache does not produce a two-frame black flash.
useEffect(() => {
  if (revealed.current) return;

  const settle = () => {
    const elapsed = performance.now() - started.current;
    const remaining = Math.max(0, (reduced ? 0 : floorMs) - elapsed);
    const id = setTimeout(reveal, remaining);
    timers.current.push(id);
  };

  if (ready !== undefined) {
    if (ready) settle();
    return;
  }

  // No `ready` prop: use the browser's own signal. If the document has
  // already finished loading, the event has been and gone — check first.
  if (document.readyState === 'complete') {
    settle();
    return;
  }
  window.addEventListener('load', settle, { once: true });
  return () => window.removeEventListener('load', settle);
}, [floorMs, ready, reduced, reveal]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Every timeout is pushed into a ref array and cleared on unmount, the ceiling effect clears its own id, and the one-shot `load` listener is removed by its effect. Because the removal timer is cleared, `setPhase` cannot run on a dead component and `onDone` cannot fire for a page that has already gone. No rAF, no observers, no global state beyond the session flag.

**Reduced motion.** The overlay still appears and the ceiling still applies — withholding content is a behaviour, not an animation, so it is not skipped. What goes away is the motion: the floor collapses to 0 so nothing is held longer than it must be, the removal delay drops to 0 and the CSS transition to 1ms, and the scanning bar becomes a static full-width rule via `animation: none; transform: scaleX(1)` rather than a pulsing one. The result is a brief still plate, not a zero-duration version of the animated one.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Having no ceiling at all. One 404 on a font or a decode that fails only on iOS, and the overlay stays up forever: the content is not visible, not scrollable, and not reachable by keyboard, and it happens to a fraction of users you will never hear from.
- Clearing the ceiling when the load signal is subscribed to, or when it fires. Whatever the signal hands off to — a floor timer, a promise chain, a decode — can itself stall, and the one thing that guaranteed a reveal has already been thrown away.
- Attaching a `load` listener without checking `document.readyState` first. On a warm cache or after a client-side navigation the event has already fired, so the listener never runs; the ceiling silently does all the work and you only discover it the day someone shortens the ceiling.
- Shipping without a floor. The overlay appears and vanishes inside two frames on a fast connection, producing a black flash on every load that reads as a broken paint and is nearly impossible to reproduce on a throttled dev machine.
- Starting the floor clock when the signal arrives instead of at mount. The floor is then added to the load time rather than overlapping it, so a 2s load becomes a 2.7s hold for no benefit.
- Using state for the reveal-once guard. The ceiling and the floor can both fire before React re-renders, so `reveal` runs twice and the second call re-arms the fade on a node that is already leaving. A ref flips synchronously and cannot be raced.
- Unmounting the overlay in the same commit that starts the fade. The node leaves the tree before the transition can run a single frame, so the overlay simply disappears and the fade you wrote never happens.
- Reading `sessionStorage` in `useEffect` instead of `useLayoutEffect`. The overlay gets one painted frame before the effect runs, so a returning visitor sees a flash of it on every single navigation.
- Initialising state from `sessionStorage` during render. The server has no session storage, so it renders `holding` while the client renders `gone`, and React logs a hydration mismatch and re-renders the tree.
- Calling `sessionStorage.setItem` unguarded. It throws in Safari private browsing, and an unhandled throw inside the reveal path leaves the overlay up permanently — the exact failure the component exists to prevent.
- Replaying it on every visit. A preloader is an introduction; on the fourth arrival in the same session it is a toll booth, and the fix is one flag rather than a shorter animation.
- Leaving timers pending on unmount. The removal timer fires after the route has changed, so `setPhase` runs on a dead component and `onDone` fires for a page that is no longer mounted.

## Notes

- `position` defaults to `fixed` for real page use and can be switched to `absolute` so the overlay can be demonstrated, or used, inside a bounded container.
- The overlay is `role="status"` with `aria-live="polite"`, so a screen reader announces the loading state once rather than reading a decorative bar, and the announcement is not interrupted by the reveal.
- `once={false}` exists for development and for the demo. In production the default keeps the overlay to one appearance per tab session.

## Definition of done

Simulate a signal that never arrives and the page is nonetheless visible and interactive at the ceiling. Reload with a warm cache and the overlay is visible for at least the floor — never a single-frame flash. Reload again in the same tab and no overlay is painted at all, not even one frame. Watch the reveal and the overlay fades rather than vanishing, with the content already composited underneath. Navigate away mid-hold and no state update warning appears and `onDone` never fires. With reduced motion on, the plate appears static and leaves immediately.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Scroll Deformation Wave

Signed, smoothed scroll velocity drives a single scalar, and that scalar scales two sine displacements in the vertex shader. Because the velocity keeps its sign, scrolling up bends the surface the opposite way from scrolling down, which is the direction cue that makes the effect read as momentum rather than as noise. Everything else — the wave shape, the shading, the crop — is a pure function of that one number.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

An image that ripples with scroll speed and bends the other way on the way back, from two sine terms.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. The depth term is `pos.z += sin(position.y * frequency + phase) * deform * amplitude`, and the shear term is `pos.y += sin(position.x * frequency) * deform * shear`. Both are sampled from `position` — the original flat attribute — not from the running `pos`.
2. That distinction is the whole technique. Sampling `position` fixes the wave to the picture, so a given pixel always sits at the same point on the sine and the image appears to flex. Sampling the already-displaced `pos` would make each term feed the next, so the wave travels through the surface and reads as a glitch.
3. The phase constant breaks the symmetry. Without it, `sin(y * f)` is odd about the plane's centre line and the top and bottom halves mirror each other exactly, which looks like a crease rather than a wave.
4. The slope, not the height, drives the shading: `vBend = cos(position.y * frequency + phase) * deform` is the analytic derivative of the depth term, so crests brighten and troughs darken with one cosine and no recomputed vertex normals.
5. `useScrollVelocity` supplies a two-stage smoothed signal — a low-pass on the raw delta, then a damped approach — and the component damps once more on top of it with a 0.0025 smoothing factor, so the ripple eases out for a beat after the scroll stops instead of snapping flat.
6. The fragment shader cover-fits the source into the quad and divides the sampled window by an overscan factor, which is what keeps the displaced vertices from sampling past the texture edge at the crest of every wave.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `amplitude = 0.07`
  World units of depth at full deflection, against a plane roughly 2.5 units tall. Below ~0.02 the ripple is lost in the perspective foreshortening; above ~0.2 the crests swing far enough toward the camera to cross the near plane and punch holes in the image.
- `shear = 0.04`
  Deliberately about half the amplitude. Its only job is to break the perfectly horizontal banding so the surface reads as cloth; raise it toward the amplitude and the two waves beat against each other into a visible moire.
- `frequency = 3`
  Radians per world unit, so roughly one and a half crests across the visible plane. Below ~1.5 there is less than a full wave on screen and the image just tilts; above ~8 the crests fall closer together than the vertex spacing and the wave aliases into flicker.
- `phase = 100`
  An arbitrary large offset whose only purpose is to be nowhere near a multiple of pi. At phase 0 the sine is odd about the plane's centre, the halves mirror, and the ripple looks like a fold down the middle.
- `maxDeform = 1.5`
  Ceiling on the signed scalar, so a trackpad flick cannot drive the displacement past the point where the surface self-intersects. Everything downstream multiplies by this, so it is the one number that bounds the entire effect.
- `reference = 900 px/s`
  Scroll speed that counts as full deflection. The hook defaults to 1500, which is tuned for whole-page parallax; a component-sized scroller rarely reaches it, so the wave would never appear.
- `DEFORM_SMOOTHING = 0.0025`
  Fraction of the gap remaining after one second. Slower and the wave lags visibly behind the scroll; much faster and it snaps flat the instant scrolling stops, losing the ease-out that makes it feel like momentum.
- `overscan = 1.12`
  Twelve percent crop held in reserve. At exactly 1.0 the displaced vertices sample past the edge of the texture at every crest and the clamped border pixel smears across the top and bottom of the image.
- `segments = 96`
  The wave is evaluated per vertex, so subdivision is its resolution. Below ~32 the sine renders as a polyline and the shading term steps in visible bands; above ~160 the vertices land inside a single pixel and only cost transform time.
- `shade = 0.22`
  How far the slope term swings brightness. At 0 the ripple is nearly invisible on a busy image; above ~0.5 the crests blow out to white and read as a lighting bug rather than as a surface.

## API

```ts
function ScrollDeformWave(props: { scrollTarget?: HTMLElement | null; amplitude?: number; shear?: number; frequency?: number; phase?: number; maxDeform?: number; reference?: number; shade?: number; overscan?: number; segments?: number; paint?: (ctx: CanvasRenderingContext2D, size: { width: number; height: number }) => void; className?: string }): JSX.Element
```

- `scrollTarget: HTMLElement | null` — default `null`
  Element whose scrollTop drives the wave. null reads window.scrollY.
- `amplitude: number` — default `0.07`
  Depth of the ripple in world units at full deflection.
- `shear: number` — default `0.04`
  Vertical shear, which breaks up the horizontal banding.
- `frequency: number` — default `3`
  Spatial frequency of the sine, in radians per world unit.
- `phase: number` — default `100`
  Phase offset, so the wave is not symmetric about the plane centre.
- `maxDeform: number` — default `1.5`
  Clamp on the signed deform scalar.
- `reference: number` — default `900`
  Pixels per second of scroll that count as full deflection.
- `shade: number` — default `0.22`
  How far the slope term brightens crests and darkens troughs.
- `overscan: number` — default `1.12`
  Crop held in reserve so displaced vertices never sample past the edge.
- `segments: number` — default `96`
  Plane subdivisions per axis. The resolution of the wave.
- `paint: (ctx, size) => void`
  Override the image. Receives a 2D context for a 1024x1024 canvas.
- `className: string`
  Merged onto the wrapper via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function ScrollDeformWave({
  scrollTarget = null,
  amplitude = 0.07,
  shear = 0.04,
  frequency = 3,
  phase = 100,
  maxDeform = 1.5,
  reference = 900,
  shade = 0.22,
  overscan = 1.12,
  segments = 96,
  paint,
  className,
}: ScrollDeformWaveProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);

  const { width, height } = useResizeObserver(host);
  const { inView } = useInView(host, { threshold: 0 });
  const visible = useVisibility();
  const reduced = useReducedMotion();

  // Signed and already smoothed. Raw scroll deltas are spiky enough that
  // feeding them straight into a geometry parameter produces visible stutter.
  const scroll = useScrollVelocity({ reference, target: scrollTarget });

  const [supported, setSupported] = useState(true);
  useEffect(() => setSupported(hasWebGL()), []);

  const deform = useRef(0);

  const live = useRef({ amplitude, shear, frequency, phase, maxDeform, shade, overscan });
  live.current = { amplitude, shear, frequency, phase, maxDeform, shade, overscan };

  const ready = width > 1 && height > 1 && supported;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setSize(el.clientWidth, el.clientHeight, false);
    renderer.setClearColor(0x000000, 0);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';
    el.appendChild(renderer.domElement);

    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(CAMERA_FOV, 1, 0.1, 100);
    camera.position.z = CAMERA_Z;

    const canvas = document.createElement('canvas');
    canvas.width = TEXTURE_WIDTH;
    canvas.height = TEXTURE_HEIGHT;
    const ctx = canvas.getContext('2d');
    if (ctx) (paint ?? paintImage)(ctx, { width: TEXTURE_WIDTH, height: TEXTURE_HEIGHT });

    const texture = new THREE.CanvasTexture(canvas);
    texture.colorSpace = THREE.SRGBColorSpace;
    texture.wrapS = THREE.ClampToEdgeWrapping;
    texture.wrapT = THREE.ClampToEdgeWrapping;
    texture.anisotropy = Math.min(4, renderer.capabilities.getMaxAnisotropy());

    const uniforms: WaveUniforms = {
      uTexture: { value: texture },
      uTextureAspect: { value: TEXTURE_WIDTH / TEXTURE_HEIGHT },
      uPlaneAspect: { value: 1 },
      uOverscan: { value: overscan },
      uShade: { value: shade },
      uDeform: { value: 0 },
      uFrequency: { value: frequency },
      uPhase: { value: phase },
      uAmplitude: { value: amplitude },
      uShear: { value: shear },
    };

    // A unit plane, rescaled on resize rather than rebuilt. The wave is
    // measured in world units, so the plane keeps a fixed subdivision and the
    // mesh scale carries the aspect.
    const geometry = new THREE.PlaneGeometry(1, 1, segments, segments);
    const material = new THREE.ShaderMaterial({
      vertexShader: scrollDeformWaveVertexShader,
      fragmentShader: scrollDeformWaveFragmentShader,
      uniforms,
      transparent: true,
    });
    const mesh = new THREE.Mesh(geometry, material);
    // The bend happens after the bounding sphere was computed, so a plane at
    // the edge of the frustum blinks out mid-ripple if this stays on.
    mesh.frustumCulled = false;
    scene.add(mesh);

    stage.current = { renderer, scene, camera, mesh, geometry, material, texture, uniforms };

    return () => {
      stage.current = null;
      scene.remove(mesh);
      // Lives inside `uniforms`, which `disposeObject` never walks.
      texture.dispose();
      disposeObject(scene);
      geometry.dispose();
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, segments, paint]);

  useEffect(() => {
    const current = stage.current;
    if (!current || width < 1 || height < 1) return;
    const aspect = width / height;
    current.renderer.setPixelRatio(pixelRatio());
    current.renderer.setSize(width, height, false);
    current.camera.aspect = aspect;
    current.camera.updateProjectionMatrix();

    // Cover the frustum exactly at z = 0, in world units derived from the
    // camera — not from `window.innerWidth`, which has no fixed relationship
    // to the visible extent at this distance.
    const visibleHeight = 2 * Math.tan((CAMERA_FOV * Math.PI) / 360) * CAMERA_Z;
    current.mesh.scale.set(visibleHeight * aspect, visibleHeight, 1);
    // The shader fits the texture into the QUAD, so this is the quad's aspect.
    current.uniforms.uPlaneAspect.value = aspect;
  }, [width, height]);

  useRaf(
    (dt) => {
      const current = stage.current;
      if (!current) return;
      const {
        amplitude: depth,
        shear: skew,
        frequency: freq,
        phase: offset,
        maxDeform: limit,
        shade: light,
        overscan: zoom,
      } = live.current;

      // Signed on purpose. Taking the magnitude would make scrolling up and
      // scrolling down produce an identical wave, and the direction cue — the
      // surface bending the other way — is most of the effect.
      const target = reduced ? 0 : clamp(scroll.current.normalized, -1, 1) * limit;
      deform.current = damp(deform.current, target, DEFORM_SMOOTHING, dt);

      current.uniforms.uDeform.value = deform.current;
      current.uniforms.uAmplitude.value = depth;
      current.uniforms.uShear.value = skew;
      current.uniforms.uFrequency.value = freq;
      current.uniforms.uPhase.value = offset;
      current.uniforms.uShade.value = light;
      current.uniforms.uOverscan.value = zoom;

      current.renderer.render(current.scene, current.camera);
    },
    ready && inView && visible,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the mesh from the scene, disposes the `CanvasTexture` by hand because it lives inside `material.uniforms` where `disposeObject` does not look, runs `disposeObject` over the scene, disposes the geometry and the material, then `disposeRenderer` for `setAnimationLoop(null)` / `dispose()` / `forceContextLoss()`, and removes the canvas element. The stage ref is nulled first so a queued frame is a no-op. `useScrollVelocity` unsubscribes with the shared RAF loop it was registered on.

**Reduced motion.** The deform scalar is forced to 0 regardless of scroll velocity, and it is still damped there, so a component that is mid-ripple when the preference changes eases flat rather than snapping. The image then stays perfectly still while scrolling — the cover fit and the resize handling continue to work, but no vertex is ever displaced and no shading swing occurs.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Sampling the wave from the running `pos` instead of the original `position`. Each term then feeds the next, the ripple travels through the surface as it deforms rather than staying pinned to the image, and the effect looks like a rendering fault instead of the photograph flexing.
- Taking the magnitude of the velocity. `abs(velocity)` makes scrolling up and scrolling down produce an identical wave, which throws away the direction cue that carries most of the effect. The scalar stays signed all the way into the uniform.
- Using a phase of 0. `sin(y * f)` is odd about the plane's centre, so the top and bottom halves mirror each other exactly and the ripple reads as a crease down the middle rather than a wave.
- Feeding raw scroll deltas into the uniform. A wheel emits discrete steps and a trackpad emits bursts; either drives the geometry into visible stutter. The signal is low-passed, damped, and damped again before it reaches the shader.
- Leaving `frustumCulled` on. The bounding sphere was computed for the flat plane, so when the component sits at the edge of the viewport three culls it against geometry the shader has already moved and the image blinks out mid-ripple.
- Fitting the plane with `window.innerWidth`. The plane has to cover the camera's frustum at z = 0, which is `2 * tan(fov/2) * distance` tall — a pixel width has no fixed relationship to that, so the image ends up letterboxed or overscaled depending on the viewport.
- Skipping the overscan. Displaced vertices sample outside [0,1] at the crest of every wave, and the texture's clamped border smears along the top and bottom edges exactly when the wave is at its most visible.
- Passing a ref to `scrollTarget`. The hook takes an `HTMLElement | null`, not a ref object, so a scroller inside the component has to be captured with a callback ref into state before it can be handed over — a plain ref would still be null on the render that matters.
- Calling `renderer.dispose()` alone. That frees GPU objects and leaves the context alive; a page with several WebGL components then hits Chromium's per-process cap and the oldest canvases go blank. `disposeRenderer` calls `forceContextLoss`.

## Notes

- `scrollTarget` defaults to `null`, which reads `window.scrollY`. Pass the scrolling element when the component lives inside its own `overflow-y-auto` container, as the demo does.
- The plane is a unit quad rescaled on resize rather than rebuilt, so a container resize never reallocates a 96x96 vertex buffer.

## Definition of done

Scroll the container and the image ripples in horizontal bands, with the crests catching a little more light than the troughs. Scroll the other way and the bands bow the opposite direction. Stop and the surface eases flat over about half a second rather than snapping. Flick hard and the ripple deepens but never folds through itself or shows a smeared edge. The image keeps its own proportions at any container aspect, and scrolling the page while the component is off screen costs nothing because the loop is gated on visibility. With `prefers-reduced-motion: reduce` the image is completely still at every scroll speed.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Scroll-Scrubbed Video

The hard part of a scroll-scrubbed hero is never the playback — it is the mapping and the throttle. Scroll becomes a smoothed progress value that snaps when it arrives; progress becomes a quantised frame index; the frame is only ever requested when that index changes; and the loop unsubscribes once the two agree. This component ships all four and draws its frames procedurally onto a canvas, so the technique can be read without a video file in the way.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

The scroll-to-frame mapping a scrubbed hero actually needs: smoothing, a snap, a frame quantiser and a loop that parks itself.

- Category: scroll
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. Progress is `(hostTop - sectionTop) / (total - hostHeight)` against a manufactured range, read from live rects each frame. The range height is written on mount and on resize as well as from the loop, so a section still below the fold already occupies its full height instead of shifting the page when it arrives.
2. The playhead follows with `damp(current, target, smoothing, dt)`, the per-second form of the familiar `current += (target - current) * 0.12`. `perFrameToSmoothing(0.12)` performs that conversion, so the feel is preserved and the settle no longer runs at double speed on a 144 Hz display.
3. A snap threshold ends the approach. Exponential smoothing is asymptotic: without `if (|target - current| < 0.0002) current = target` the value never arrives, and any loop that waits for arrival runs forever.
4. The frame index is `round(progress * (frames - 1))`, and the draw call is guarded by `index !== drawnIndex`. This is the same guard as the `Math.abs(video.currentTime - t) > 0.003` test in a real player: asking the decoder to seek to the frame it is already showing is what makes a scrubbed video judder.
5. The loop parks itself. Once the value has snapped, `useRaf` is disabled and the subscription dropped; a scroll listener on the container wakes it. A settled hero therefore costs nothing, rather than 60 wasted frames a second over a still image.
6. Work is gated on `useInView` with `rootMargin: 200px`, so the first frame is painted just before the section enters rather than just after — the difference between arriving on a picture and arriving on a blank box.
7. The canvas backing store is sized in device pixels and the element in CSS pixels, with the ratio clamped at 2. Assigning `width`/`height` also clears the canvas, so the resize path forces a redraw by resetting the drawn index to -1.
8. Smoothed progress is published as `--scrub-progress` on the section, so a scrubber bar can move continuously in CSS while the frame behind it advances in steps.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `frames = 96`
  Steps the range quantises to. Around three seconds of 30 fps footage. Fewer than ~48 and the stepping is visible as stutter; many more and consecutive frames differ by less than the smoothing can resolve, so decode work is spent on frames nobody perceives.
- `smoothing = perFrameToSmoothing(0.12)`
  The classic `0.12` per frame at 60 Hz expressed per second (~0.0004). It absorbs wheel steps without the playhead feeling detached from the gesture. The conversion is the point: the raw 0.12 would settle more than twice as fast at 144 Hz.
- `SNAP = 0.0002`
  Progress delta below which the playhead is considered arrived. Two ten-thousandths of the range is well under one frame at any sane frame count, so snapping is invisible — and it is what allows the loop to terminate at all.
- `rootMargin = 200px`
  Starts work just before the section enters. Enough lead time to decode and paint the first frame at typical scroll speeds, small enough that scrolling past does not warm up work that is never seen.
- `viewports = 2`
  Scroll travel as a multiple of the scroller height. Two screens over ~96 frames is roughly one frame per 15 px of scroll, which reads as a continuous shot rather than a flipbook.
- `MAX_DPR = 2`
  Backing-store cap. Past 2x the extra pixels are invisible on the phones that report 3x and 4x, but the per-frame fill cost scales with their square.

## API

```ts
function ScrollScrubbedVideo(props: { frames?: number; draw?: (ctx: CanvasRenderingContext2D, frame: ScrubFrame) => void; viewports?: number; smoothing?: number; children?: ReactNode; scroller?: RefObject<HTMLElement | null>; className?: string }): JSX.Element
```

- `frames: number` — default `96`
  Discrete frames the scroll range quantises to.
- `draw: (ctx, frame: ScrubFrame) => void`
  Called only when the frame index changes or after a resize. Replace with a `currentTime` write for real footage.
- `viewports: number` — default `2`
  Scroll travel as a multiple of the scroller height.
- `smoothing: number` — default `perFrameToSmoothing(0.12)`
  Fraction of the progress gap left after one second.
- `children: ReactNode`
  Overlaid on the canvas — captions, a scrubber, a title.
- `scroller: RefObject<HTMLElement | null>`
  Scroll container. Omit to auto-detect.
- `className: string`
  Merged onto the outer section.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function ScrollScrubbedVideo({
  frames = 96,
  draw = defaultDraw,
  viewports = 2,
  smoothing = DEFAULT_SMOOTHING,
  children,
  scroller,
  className,
}: ScrollScrubbedVideoProps) {
  const section = useRef<HTMLElement>(null);
  const pin = useRef<HTMLDivElement>(null);
  const canvas = useRef<HTMLCanvasElement>(null);

  const current = useRef(0);
  const drawnIndex = useRef(-1);
  const lastProgress = useRef('');
  const lastHeight = useRef(0);
  const palette = useRef<ScrubPalette | null>(null);
  const drawRef = useRef(draw);
  drawRef.current = draw;

  const reduced = useReducedMotion();
  const size = useResizeObserver(pin);
  // Work starts 200 px before the section enters, so the first frame is
  // already painted when it arrives rather than after it.
  const { inView } = useInView(section, { rootMargin: '200px' });

  // A self-parking loop. Once the smoothed value has reached the target there
  // is nothing left to compute, so the subscription is dropped entirely; a
  // scroll on the container wakes it. Without this, a settled hero keeps a
  // core busy re-deriving the same frame index sixty times a second.
  const [awake, setAwake] = useState(true);

  const render = (index: number, progress: number) => {
    const el = canvas.current;
    const ctx = el?.getContext('2d');
    if (!el || !ctx || size.width === 0 || size.height === 0) return;
    if (!palette.current) palette.current = readPalette(el);

    drawnIndex.current = index;
    ctx.save();
    const dpr = Math.min(window.devicePixelRatio || 1, MAX_DPR);
    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
    drawRef.current(ctx, {
      progress,
      index,
      frames,
      width: size.width,
      height: size.height,
      palette: palette.current,
    });
    ctx.restore();
  };

  useEffect(() => {
    const el = canvas.current;
    if (!el || size.width === 0 || size.height === 0) return;
    // The backing store is sized in device pixels and the element in CSS
    // pixels; assigning width/height also clears it, so a redraw is forced.
    const dpr = Math.min(window.devicePixelRatio || 1, MAX_DPR);
    el.width = Math.round(size.width * dpr);
    el.height = Math.round(size.height * dpr);
    palette.current = readPalette(el);
    drawnIndex.current = -1;
    setAwake(true);
  }, [size.width, size.height]);

  useEffect(() => {
    const sectionEl = section.current;
    if (!sectionEl) return;
    const host = scroller?.current ?? nearestScroller(sectionEl);
    const target = host === document.documentElement ? window : host;
    const wake = () => setAwake(true);
    target.addEventListener('scroll', wake, { passive: true });
    return () => target.removeEventListener('scroll', wake);
  }, [scroller]);

  // The manufactured range is layout, so it is written on mount and on resize
  // rather than only from the loop — a section still below the fold must
  // already occupy its full height, or entering it shifts everything below.
  useEffect(() => {
    const sync = () => {
      const sectionEl = section.current;
      const pinEl = pin.current;
      if (!sectionEl || !pinEl) return;
      const host = scroller?.current ?? nearestScroller(sectionEl);
      const hostHeight =
        host === document.documentElement ? window.innerHeight : host.clientHeight;
      if (hostHeight === 0) return;
      const total = Math.round(hostHeight * (reduced ? 1 : 1 + viewports));
      if (total === lastHeight.current) return;
      lastHeight.current = total;
      sectionEl.style.height = `${total}px`;
      pinEl.style.height = `${hostHeight}px`;
      setAwake(true);
    };
    sync();
    window.addEventListener('resize', sync);
    return () => window.removeEventListener('resize', sync);
  }, [reduced, viewports, scroller]);

  useRaf((dt) => {
    const sectionEl = section.current;
    const pinEl = pin.current;
    if (!sectionEl || !pinEl) return;

    const host = scroller?.current ?? nearestScroller(sectionEl);
    const hostIsRoot = host === document.documentElement;
    const hostTop = hostIsRoot ? 0 : host.getBoundingClientRect().top;
    const hostHeight = hostIsRoot ? window.innerHeight : host.clientHeight;
    if (hostHeight === 0) return;

    const total = Math.round(hostHeight * (reduced ? 1 : 1 + viewports));
    if (total !== lastHeight.current) {
      lastHeight.current = total;
      sectionEl.style.height = `${total}px`;
      pinEl.style.height = `${hostHeight}px`;
    }

    const travel = total - hostHeight;
    const target = reduced
      ? 0.5
      : travel > 0
        ? clamp((hostTop - sectionEl.getBoundingClientRect().top) / travel, 0, 1)
        : 0;

    // Smooth, then snap. Without the snap the value approaches the target
    // asymptotically and the loop can never decide it has arrived.
    current.current = reduced ? target : damp(current.current, target, smoothing, dt);
    let settled = false;
    if (Math.abs(target - current.current) < SNAP) {
      current.current = target;
      settled = true;
    }

    const text = current.current.toFixed(4);
    if (text !== lastProgress.current) {
      lastProgress.current = text;
      sectionEl.style.setProperty('--scrub-progress', text);
    }

    // The seek throttle. A real player writes `video.currentTime` here, and
    // only when the frame actually changed — re-seeking to the frame already
    // displayed makes the decoder stall and the playhead judder.
    const index = clamp(Math.round(current.current * (frames - 1)), 0, frames - 1);
    if (index !== drawnIndex.current) render(index, current.current);

    if (settled) setAwake(false);
  }, awake && inView);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useRaf` unsubscribes on unmount and again whenever the loop parks. The scroll and resize listeners are removed with their effects, `useInView` unobserves through its pool, and `useResizeObserver` disconnects. The canvas holds no timers and no decoded resources.

**Reduced motion.** The manufactured range collapses to a single screen and the playhead is pinned to the middle frame with no smoothing, so the section becomes a still image with its caption rather than several screens of scroll that scrub something. The loop parks immediately and never redraws.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Writing `video.currentTime` on every frame. The decoder is asked to seek to the position it is already at dozens of times a second, and on Safari in particular the playhead visibly stalls and jumps. Quantise to a frame and guard the assignment.
- Smoothing without a snap. The playhead approaches the target forever, the "is it settled" test never passes, and a loop written to park itself never does.
- Using a per-frame smoothing constant. The scrub lags noticeably further behind the scroll at 60 Hz than at 144 Hz, and there is no single value that feels right on both.
- Encoding the source with long GOPs. Seeking then lands on the nearest keyframe and decodes forward, which is why a scrub built on a normal web encode stutters no matter how good the JavaScript is — an all-intra encode is a prerequisite, not an optimisation.
- Running the loop while the section is off screen. The whole point of a scrubbed hero is that it costs nothing until it is on screen; without an IntersectionObserver gate it costs a decode loop for the entire page lifetime.
- Sizing the canvas in CSS only. The backing store stays at its default 300x150 and the image is stretched — the resize path must assign `width` and `height` in device pixels.
- Ignoring the device pixel ratio cap. A 4x phone quadruples the fill area for pixels nobody can see, and the scrub drops to single-digit frame rates.
- Leaving the manufactured range in place under reduced motion. The user gets several screens of scroll during which nothing at all changes.

## Notes

- No video file is shipped. `draw(ctx, frame)` renders each frame procedurally so the mapping, the quantiser and the throttle can be read on their own. A real implementation replaces the body of that call with a single assignment — `video.currentTime = frame.progress * (video.duration - 0.05)` — keeping the surrounding `index !== drawnIndex` guard exactly as it is, and draws the video element instead of the canvas.
- The other things a production version needs, none of which are part of the mapping: an all-intra encode (`-g 1`), several responsive encodes selected by width with the playhead position preserved across the swap, and a decode prime on Safari — `play()` followed immediately by `pause()` — because a video that has never played will not seek.
- The `frames` value should match the source: with a video, use `duration * fps` so one index step is one real frame.
- The default draw reads its colours from the `--k-*` custom properties on the canvas, so the placeholder footage follows the theme.

## Definition of done

Scrolling advances the frame counter smoothly and reverses exactly. Stopping settles within a few frames, after which a performance profile shows no rAF activity until the next scroll. Scrolling the section off screen stops all work. Resizing redraws at the correct resolution with no stretching. The settle takes the same wall-clock time at 60 and 144 Hz. With reduced motion on, one static frame is shown and the section is one screen tall.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Scrubbed Character Colour Reveal

A paragraph sits at 16% strength and resolves character by character as it crosses the viewport, with the reveal position pinned to the scrollbar rather than to a clock. Scroll back up and the characters ghost out again in reverse, because a scrubbed timeline is a function of position, not a playback. The stagger and durations are ratios of the scroll range rather than seconds, so the pacing per character is unchanged whether the paragraph is thirty words or three hundred.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A dim paragraph resolves character by character as it crosses the viewport, tied to scroll position not a clock.

- Category: text
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. The text is split in JSX — `text.split(" ")` for word boxes, `Array.from(word)` for one `inline-block` span per character — so React owns every node and nothing mutates the tree behind its back.
2. One `gsap.to(chars, { opacity: 1, stagger, duration, ease: "power1.out", scrollTrigger: {...} })` does the whole reveal. GSAP builds the stagger internally as a single tween whose total length is `duration + (n - 1) * stagger`.
3. ScrollTrigger maps that total length onto the distance between `start` and `end`, which is why `stagger: 0.1` and `duration: 0.35` are ratios, not seconds: each character begins 0.1/total of the way through the scroll range and takes 0.35/total to resolve. Change the paragraph length and the pacing per character is identical; change the scroll range and everything rescales together.
4. The resting opacity is written as a JSX inline style on each character, so the pre-scroll frame — including the server render and the no-JS render — is already the dim state, and GSAP has a real DOM value to tween away from.
5. The paragraph carries `aria-label={text}` and the character spans are inside an `aria-hidden` wrapper, so assistive technology reads one paragraph rather than two hundred single letters.
6. `ease: "power1.out"` applies *within* each character's own resolve, not across the stagger. The stagger itself remains linear against scroll, which is what keeps the sweep pinned to the scrollbar.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `DIM = 0.16`
  Resting strength as opacity on `currentColor`. Below ~0.1 the unread text is illegible and the block reads as a loading skeleton; above ~0.3 the contrast between resolved and unresolved is too weak for the sweep to be visible while scrolling.
- `STAGGER = 0.1`
  Timeline units between adjacent characters. Combined with `CHAR_DURATION` it sets the width of the resolve front: roughly 3-4 characters are mid-transition at any moment. Larger and the front narrows to one character at a time, which reads as a typewriter rather than a wash.
- `CHAR_DURATION = 0.35`
  3.5x the stagger, so several characters are always resolving together. Equal to the stagger it becomes a hard edge sweeping the paragraph; much larger and the front is so soft the reveal has no direction.
- `SCRUB = 0.75`
  Seconds of catch-up. `scrub: true` welds the reveal to the scrollbar exactly, which on a trackpad exposes every jitter in the input. Three quarters of a second smooths it without ever feeling like the text is animating on its own.
- `START / END = 'top 78%' / 'bottom 55%'`
  The reveal begins when the paragraph top is a little above the fold and completes when its bottom passes just past the middle. Ending at `bottom top` means the last characters only resolve as the paragraph leaves the screen, so the reader never sees the finished text.

## API

```ts
function ScrubCharColorReveal(props: { text: string; dim?: number; stagger?: number; charDuration?: number; scrub?: number; start?: string; end?: string; scroller?: Element | null; className?: string }): JSX.Element
```

- `text: string`
  Body copy. Split to words then characters in JSX.
- `dim: number` — default `0.16`
  Resting strength of an unrevealed character, 0-1.
- `stagger: number` — default `0.1`
  Timeline units between adjacent characters.
- `charDuration: number` — default `0.35`
  Timeline units for one character to resolve.
- `scrub: number` — default `0.75`
  Seconds of catch-up between the scrollbar and the reveal.
- `start: string` — default `'top 78%'`
  ScrollTrigger `start`.
- `end: string` — default `'bottom 55%'`
  ScrollTrigger `end`.
- `scroller: Element | null` — default `null`
  Scroll container, when the text is not in the document scroller.
- `className: string`
  Merged onto the paragraph via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const DIM = 0.16;
const STAGGER = 0.1;
const CHAR_DURATION = 0.35;
const SCRUB = 0.75;
const START = 'top 78%';
const END = 'bottom 55%';

export function ScrubCharColorReveal({
  text,
  dim = DIM,
  stagger = STAGGER,
  charDuration = CHAR_DURATION,
  scrub = SCRUB,
  start = START,
  end = END,
  scroller = null,
  className,
}: ScrubCharColorRevealProps) {
  const root = useRef<HTMLParagraphElement>(null);
  const reduced = useReducedMotion();

  useEffect(() => {
    const el = root.current;
    if (!el || reduced) return;

    gsap.registerPlugin(ScrollTrigger);

    const chars = Array.from(el.querySelectorAll<HTMLElement>('[data-char]'));
    if (chars.length === 0) return;

    const ctx = gsap.context(() => {
      gsap.to(chars, {
        opacity: 1,
        duration: charDuration,
        ease: 'power1.out',
        stagger,
        scrollTrigger: {
          trigger: el,
          scroller: scroller ?? undefined,
          start,
          end,
          scrub,
        },
      });
    }, el);

    return () => ctx.revert();
  }, [text, dim, stagger, charDuration, scrub, start, end, scroller, reduced]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `ctx.revert()` on the `gsap.context` scoped to the paragraph. That kills the staggered tween, disposes the ScrollTrigger instance so it stops measuring a detached node, and strips the inline `opacity` GSAP wrote — leaving React's own inline dim value intact.

**Reduced motion.** The resting opacity collapses to 1 in the JSX, so the paragraph renders fully resolved, and the effect returns before registering ScrollTrigger. The text is never left dim waiting for a scroll that will not drive it.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Splitting text before the webfont has loaded. Character boxes are measured against the fallback face, so widths and line breaks are wrong and never re-flow when the real font arrives — see `font-safe-text-split` for the `document.fonts.ready` gate and the debounced re-split this needs at scale.
- Treating `stagger` and `duration` as seconds. Under `scrub` they are proportions of the scroll range; a value tuned as "0.35 seconds" behaves completely differently the moment the trigger distance changes.
- Building a separate tween per character. That is one ScrollTrigger per character on a paragraph of two hundred, and refresh cost becomes visible on resize. A single staggered tween is one trigger.
- Leaving the character spans exposed to assistive technology. A screen reader announces every letter individually — `aria-label` on the paragraph plus `aria-hidden` on the spans is not optional here.
- Setting the resting opacity from `gsap.set` in the effect. The first paint then shows the paragraph at full strength before dimming it, which is a visible flash on every load.
- Splitting straight to characters with no word boxes. Line breaks land inside words and the paragraph becomes unreadable at narrow widths.
- Forgetting `scroller` when the paragraph lives in an `overflow-y-auto` panel. ScrollTrigger measures the window instead and the reveal fires at the wrong scroll position or not at all.

## Notes

- The split is declarative JSX, deliberately: GSAP `SplitText` is reserved for the two components whose subject *is* SplitText (`nested-splittext-restore`, `font-safe-text-split`). Here a React split gives the same per-character targets with no DOM mutation and no extra dependency for the consumer.
- Opacity on `currentColor` rather than a literal colour tween, so the component is correct in any theme without a per-context variant.

## Definition of done

Scroll the paragraph up through the viewport: characters brighten in a soft front sweeping left to right and top to bottom, and the front position tracks the scrollbar rather than a clock. Scroll back up and it reverses. Turn on a screen reader and the paragraph is announced once as whole sentences, not letter by letter. With reduced motion enabled the paragraph is at full strength on first paint.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Scrub Timeline Spine

A vertical rule that fills with scroll while entries alternate either side of it. Entries rest at 50% opacity rather than 0, so the animation adds emphasis to content that is already readable, and each one reverses as it leaves — so scrolling back up replays the sequence instead of showing a column of finished animations.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A rule that fills as you scroll, with entries alternating either side and reversing on the way back.

- Category: scroll
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. The rule is two elements: a faint full-height track, and a fill of the same height scaled with `gsap.fromTo(fill, { scaleY: 0 }, { scaleY: 1, ease: "none" })` on a `scrub: 0.6` trigger running `top 55%` → `bottom 75%`.
2. `transformOrigin: "top center"` is passed to the tween, not just set in CSS. GSAP writes its own transform string, and without it the fill grows from the centre and the rule appears to unroll in both directions at once.
3. Every entry gets its own trigger with `toggleActions: "play reverse play reverse"` — the four slots are onEnter, onLeave, onEnterBack, onLeaveBack. Reversing on leave is what makes the column scrubbable upward as well as downward.
4. Entries animate `fromTo({ opacity: 0.5, scale: 0.9 }, { opacity: 1, scale: 1, duration: 0.6, ease: "power2.out" })`. The rest state is 0.5, not 0, so nothing is gated behind a scroll event.
5. `transformOrigin` per entry follows the side it hangs off — `left center` on the left column, `right center` on the right — so each card grows outward from the spine. A centre origin makes both columns creep toward the middle and the rule looks squeezed.
6. Alternation is decided from the measured container width. Below `alternateAbove` px, entries stop alternating and stack to the right of a left-hand rule, and every origin becomes `left center`.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `restOpacity = 0.5`
  The resting state of an entry. Zero is the obvious choice and the wrong one: it makes the animation a gate on the content, so a failed script or a skipped trigger leaves a blank column, and a screen reader meets text that is visually absent. At 0.5 the animation is emphasis, not access.
- `restScale = 0.9`
  Paired with the opacity change so the entry gains presence rather than just brightness. Below ~0.85 the text visibly reflows as it scales and becomes hard to read mid-transition.
- `scrub = 0.6`
  Catch-up on the fill only. The rule keeps advancing for about half a second after the wheel stops, which reads as the timeline settling. `true` makes it feel welded to the mouse.
- `fillStart / fillEnd = 'top 55%' / 'bottom 75%'`
  The fill begins once the section is past halfway up the scroller and completes before its bottom clears. Ending at `bottom top` instead would leave the rule still filling while the last entry is already being read, which makes the last item feel unreached.
- `entryDuration = 0.6`
  Not scrubbed — this one plays on its own clock, so it must be short enough to finish before the next entry enters at normal scrolling speed.
- `alternateAbove = 420`
  Container width in px below which a half-width column cannot hold a title and a line of body. Measured from the element, not the window, because the spine is usually inside an article column narrower than the page.

## API

```ts
function ScrubTimelineSpine(props: { entries: { label: string; title: string; body?: string }[]; scrub?: number; restOpacity?: number; restScale?: number; entryDuration?: number; fillStart?: string; fillEnd?: string; entryStart?: string; alternateAbove?: number; scrollerRef?: RefObject<HTMLElement | null>; className?: string }): JSX.Element
```

- `entries: { label: string; title: string; body?: string }[]`
  Ordered entries. Rendered as an `<ol>` either side of the rule.
- `scrub: number` — default `0.6`
  Seconds of catch-up on the fill.
- `restOpacity: number` — default `0.5`
  Resting opacity of an inactive entry. Do not set 0.
- `restScale: number` — default `0.9`
  Resting scale of an inactive entry.
- `entryDuration: number` — default `0.6`
  Seconds for one entry to reach full emphasis.
- `fillStart: string` — default `'top 55%'`
  ScrollTrigger start for the fill.
- `fillEnd: string` — default `'bottom 75%'`
  ScrollTrigger end for the fill.
- `entryStart: string` — default `'top 78%'`
  ScrollTrigger start for each entry.
- `alternateAbove: number` — default `420`
  Container width in px above which entries alternate sides.
- `scrollerRef: RefObject<HTMLElement | null>`
  The scroll container that owns the scroll position. Omit for the document.
- `className: string`
  Merged onto the wrapper via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function ScrubTimelineSpine({
  entries,
  scrub = 0.6,
  restOpacity = 0.5,
  restScale = 0.9,
  entryDuration = 0.6,
  fillStart = 'top 55%',
  fillEnd = 'bottom 75%',
  entryStart = 'top 78%',
  alternateAbove = 420,
  scrollerRef,
  className,
}: ScrubTimelineSpineProps) {
  const root = useRef<HTMLDivElement>(null);
  const fill = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();
  const { width } = useResizeObserver(root);
  const alternate = width >= alternateAbove;

  useGsap(
    gsap,
    () => {
      const container = root.current;
      const line = fill.current;
      if (!container || !line) return;

      const items = Array.from(container.querySelectorAll<HTMLElement>('[data-spine-entry]'));
      const scroller = scrollerRef?.current ?? undefined;

      if (reduced) {
        gsap.set(line, { scaleY: 1 });
        gsap.set(items, { opacity: 1, scale: 1 });
        return;
      }

      gsap.fromTo(
        line,
        { scaleY: 0 },
        {
          scaleY: 1,
          ease: 'none',
          // transformOrigin is set in CSS too, but GSAP writes its own
          // transform string; without stating it here the fill grows from the
          // centre and the rule appears to unroll in both directions.
          transformOrigin: 'top center',
          scrollTrigger: {
            trigger: container,
            scroller,
            // Starts filling once the section is just past halfway up and
            // completes before its bottom leaves — so the rule is never still
            // filling while the last entry is already being read.
            start: fillStart,
            end: fillEnd,
            scrub,
            invalidateOnRefresh: true,
          },
        },
      );

      items.forEach((item, i) => {
        gsap.fromTo(
          item,
          { opacity: restOpacity, scale: restScale },
          {
            opacity: 1,
            scale: 1,
            duration: entryDuration,
            ease: 'power2.out',
            // Scale from the edge the entry hangs off, so it grows outward
            // from the spine. A centre origin pulls both columns toward the
            // middle and the rule looks like it is being squeezed.
            transformOrigin: alternate && i % 2 === 1 ? 'right center' : 'left center',
            scrollTrigger: {
              trigger: item,
              scroller,
              start: entryStart,
              // onEnter, onLeave, onEnterBack, onLeaveBack. Reversing on the
              // way out is what makes the column scrubbable upward as well as
              // downward.
              toggleActions: 'play reverse play reverse',
            },
          },
        );
      });
    },
    root,
    [
      scrub,
      restOpacity,
      restScale,
      entryDuration,
      fillStart,
      fillEnd,
      entryStart,
      alternate,
      reduced,
      entries.length,
    ],
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useGsap` reverts the `gsap.context`, killing the fill tween, all per-entry tweens and all of their ScrollTriggers, and restoring the inline transform and opacity. This matters more than usual here because the alternation flip rebuilds every trigger on resize: a surviving trigger would keep writing a right-edge `transform-origin` to a card now laid out on the left.

**Reduced motion.** The fill is set to `scaleY: 1` and every entry to full opacity and scale during the first effect, with no triggers created. The spine renders as a completed timeline — the rule is drawn, every entry is emphasised, and nothing changes with scroll.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- `toggleActions: "play none none none"`. The default-feeling choice, and it means scrolling back up shows a column of already-completed animations with no motion left in them. Reversing on leave is what makes the direction of travel legible.
- Resting entries at `opacity: 0`. The animation becomes a gate: any trigger that fails to fire — a mis-set scroller, a refresh during a resize, a JS error elsewhere — leaves the content permanently invisible while still occupying layout and still being read by assistive technology.
- Setting `transform-origin` only in CSS. GSAP writes a complete transform and its own `transform-origin`, so the CSS value is overwritten and the fill grows from the middle of the rule instead of the top.
- A single centre `transform-origin` for both columns. Cards then scale toward the spine, so the whole layout appears to pinch inward as you scroll instead of each entry growing outward from the rule.
- Scaling the same element that is the track. The fill needs to be a second element; scaling the visible track means the "remaining" portion disappears and the reader loses the sense of how much is left.
- One shared ScrollTrigger for all entries. The emphasis then depends on the section's progress rather than each entry's own position, so on a tall screen three entries brighten at once and none of them reads as current.

## Notes

- The fill uses the accent token, so it inherits the category accent when placed inside a `data-category` subtree.
- Entries are a real `<ol>`, so the sequence is conveyed structurally and not only by the drawn rule.

## Definition of done

Scroll down: the accent rule fills from the top and each entry brightens and grows outward from its own side of the rule as it arrives. Scroll back up and each entry dims again as it leaves the top, and the rule retreats. Stop mid-section and the fill continues for about half a second. Disable JavaScript and every entry is still readable at half opacity. Narrow the container and the entries stack to the right of a left-hand rule.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Pixels-Per-Second Marquee

A looping strip of content whose speed is expressed in pixels per second and whose duration is derived from it, never the other way round. A fixed `duration` means a 900px strip crawls while a 4000px strip sprints, so two marquees on the same page visibly disagree about how fast scrolling is — and adding one word to either changes its speed. The loop distance is exactly one content set plus its gap, so the wrap frame is pixel-identical to the frame before it and the seam is invisible.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A marquee whose duration is derived from measured width and a px/second speed, so every strip moves at the same rate.

- Category: text
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. A `ResizeObserver` on the first content copy gives `copyWidth`; the repeating unit is `setWidth = copyWidth + gap`, because the gap that follows a copy is part of the unit — omit it and the rhythm at the seam is one gap tighter than everywhere else, which reads as a stutter once per cycle.
2. Duration is `setWidth / speed` — seconds = px / (px per second). Every marquee on the site then moves at the same rate regardless of how much content is in it.
3. The number of copies is `Math.max(2, Math.ceil(rootWidth / setWidth) + 1)`, from a second `ResizeObserver` on the container. The `+1` covers the gap that the translation itself opens up; with the exact ceiling a blank wedge appears at the right edge on the last frame of every cycle.
4. The tween is `gsap.fromTo(track, { x: 0 }, { x: -setWidth, duration, ease: "none", repeat: -1 })`. `ease: "none"` is mandatory — any easing makes the strip accelerate and decelerate once per cycle, which turns the seam into a visible pulse.
5. Pausing lives in a *separate* effect that calls `tween.paused(!(visible && inView))`, driven by `useVisibility` (tab hidden) and `useInView` (scrolled away). Rebuilding the tween on a visibility flip would snap the strip back to x = 0.
6. Hover ramps the timeScale rather than toggling paused: `gsap.to(tween, { timeScale: 0 | 1, duration: 0.35, overwrite: true })`. The tween object is itself a valid GSAP target, so the strip glides to a stop instead of stopping dead.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `SPEED = 60`
  Pixels per second. Around 60px/s a 12px word takes a fifth of a second to cross its own width — readable while moving. Past ~120px/s the copy is decorative texture; below ~30px/s viewers assume it is stuck.
- `GAP = 48`
  Pixels between items and between the last item and the next copy. It must be identical in both places or the seam is visibly a different rhythm from the interior. Below ~24px adjacent items read as one phrase.
- `HOVER_RAMP = 0.35`
  Seconds to ramp `timeScale` between 1 and 0. Zero (a hard pause) reads as a broken animation; past ~0.6s the strip keeps drifting long enough that a user trying to read an item has to chase it.
- `copies = max(2, ceil(rootWidth / setWidth) + 1)`
  The floor of 2 covers content wider than the container, where the ceiling alone yields 1 and there is nothing to wrap into. The `+1` covers the width the translation itself vacates.

## API

```ts
function SeamlessMarquee(props: { children: ReactNode; speed?: number; direction?: 'left' | 'right'; gap?: number; pauseOnHover?: boolean; className?: string }): JSX.Element
```

- `children: ReactNode`
  One content set. Cloned as many times as the container width requires.
- `speed: number` — default `60`
  Pixels per second. Identical for every marquee whatever its width.
- `direction: 'left' | 'right'` — default `'left'`
  Travel direction.
- `gap: number` — default `48`
  Pixels between items and between copies.
- `pauseOnHover: boolean` — default `true`
  Ramp `timeScale` to 0 on pointer enter and back to 1 on leave.
- `className: string`
  Merged onto the clipping container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const SPEED = 60;
const GAP = 48;
const HOVER_RAMP = 0.35;

export function SeamlessMarquee({
  children,
  speed = SPEED,
  direction = 'left',
  gap = GAP,
  pauseOnHover = true,
  className,
}: SeamlessMarqueeProps) {
  const root = useRef<HTMLDivElement>(null);
  const track = useRef<HTMLDivElement>(null);
  const copy = useRef<HTMLDivElement>(null);
  const tween = useRef<gsap.core.Tween | null>(null);

  const reduced = useReducedMotion();
  const visible = useVisibility();
  const { inView } = useInView(root);
  const { width: rootWidth } = useResizeObserver(root);
  const { width: copyWidth } = useResizeObserver(copy);

  // The loop distance is one copy *plus* the gap that follows it — the gap is
  // part of the repeating unit. Leave it out and the rhythm of the seam is one
  // gap tighter than the rhythm everywhere else, which reads as a stutter.
  const setWidth = copyWidth + gap;
  const measured = copyWidth > 0;
  const copies =
    reduced || !measured ? 1 : Math.max(2, Math.ceil(rootWidth / setWidth) + 1);

  useEffect(() => {
    const el = track.current;
    if (!el || reduced || !measured) return;

    const duration = setWidth / speed;
    const t = gsap.fromTo(
      el,
      { x: direction === 'left' ? 0 : -setWidth },
      {
        x: direction === 'left' ? -setWidth : 0,
        duration,
        ease: 'none',
        repeat: -1,
      },
    );
    tween.current = t;

    return () => {
      tween.current = null;
      // Kill the hover timeScale tweens too — they target the tween object
      // itself, so killTweensOf(el) would not reach them.
      gsap.killTweensOf(t);
      t.kill();
      gsap.set(el, { clearProps: 'transform' });
    };
  }, [setWidth, measured, speed, direction, reduced]);

  // Separate effect so a visibility flip pauses in place instead of rebuilding
  // the tween, which would snap the strip back to its start position.
  useEffect(() => {
    const t = tween.current;
    if (!t) return;
    t.paused(!(visible && inView));
  }, [visible, inView, setWidth, measured, speed, direction, reduced]);

  const ramp = useCallback(
    (to: number) => {
      const t = tween.current;
      if (!pauseOnHover || !t) return;
      gsap.to(t, { timeScale: to, duration: HOVER_RAMP, overwrite: true });
    },
    [pauseOnHover],
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The build effect clears the tween ref, calls `gsap.killTweensOf(tween)` to catch in-flight hover `timeScale` ramps that target the tween object, then `tween.kill()`, then `gsap.set(track, { clearProps: "transform" })`. Both `ResizeObserver` instances are disconnected by their hooks.

**Reduced motion.** Renders a single, un-cloned content set with no tween created at all. The content is fully visible and static — the strip is not left mid-translation and nothing is clipped out of view.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Specifying `duration` instead of a px/second speed. Two marquees on one page then move at different rates, and editing the copy silently changes the speed of the one you edited.
- Translating by the copy width and forgetting the gap. The seam arrives one gap early every cycle — a small, regular hitch that is very hard to diagnose from the code.
- Hardcoding the clone count at 2. On a wide viewport with short content the strip runs out and a blank band sweeps through once per cycle.
- Any ease other than `none`. The strip speeds up and slows down once per loop, so the seam that is geometrically invisible becomes obvious from the velocity change alone.
- Rebuilding the tween when visibility or hover changes. The `fromTo` restarts at x = 0 and the strip teleports backwards.
- Killing only `killTweensOf(trackElement)` on unmount. The hover ramps target the *tween object*, not the element, so they survive and keep writing `timeScale` to a dead tween — `gsap.killTweensOf(t)` before `t.kill()` is what catches them.
- Leaving the cloned copies exposed to assistive technology. A screen reader reads the same six items three times; every clone past the first is `aria-hidden`.

## Notes

- Reduced motion renders exactly one copy with no tween and no transform, so the content sits statically at the left edge and remains fully readable.
- No text splitting is involved — the marquee moves whole content sets, so no split library dependency is imposed on consumers.

## Definition of done

Watch the seam for a full cycle: no jump, no blank wedge, no change in spacing as one copy hands over to the next. Put two marquees with very different content lengths side by side and both move at visibly the same speed. Hover and the strip glides to a stop over about a third of a second rather than halting. Switch browser tabs and back, and the strip resumes from where it was rather than restarting. With reduced motion the content is static and readable.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Self-Parking RAF

An eased value never arrives. Closing 12% of the remaining gap each frame closes it 100% never — the distance decays asymptotically and `current !== target` stays true for the life of the page, so a loop conditioned on that comparison never stops. One line fixes it: below a threshold, assign the target outright. The equality test can now succeed, the loop reaches its own stopping condition, and it unsubscribes itself. The frame callback exists only while something is genuinely moving.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

An epsilon snap lets a damped value reach its target exactly, so the frame loop hits its exit test and dies.

- Category: primitive
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. The damped step is `damp(current, target, smoothing, dt)`, which is `current + (target - current) * (1 - smoothing^dt)`. The exponent is what makes it frame-rate independent: the naked `* 0.12` from the source converges twice as fast at 120 Hz as at 60 Hz, so the same code feels different on different hardware and visibly speeds up whenever the browser drops frames.
2. After the step, `Math.abs(target - next) < epsilon` assigns `next = target` exactly. This is the entire technique. Without it the loop's exit condition — `next === target` — is unreachable, because exponential decay produces 1e-8, then 1e-9, then a denormal, and never a clean zero.
3. Parking is expressed as React state, not as a local flag: `setRunning(false)` drops the `useRaf` subscription, and when the last subscriber leaves the shared loop calls `cancelAnimationFrame` and stops scheduling frames at all. The saving is the whole callback plus the paint it would have dirtied, not merely the arithmetic.
4. Waking is driven by a `target` change in an effect, guarded by `value.current === target`. The guard is load-bearing: without it any unrelated re-render that happens to pass the same target restarts a loop that had already parked, which is how "self-parking" quietly degrades back into an always-on loop.
5. Because `perFrameToSmoothing(0.12)` is `0.88^60 ≈ 0.00047`, the value retains 0.047% of its gap after a second — so the settle time is a few hundred milliseconds and the epsilon is crossed within roughly twenty frames rather than being an escape hatch from a genuinely long tail.
6. A hidden tab and reduced motion both take the same short path: `park()` assigns the target, emits one `onFrame`, and never starts a loop. No observer means no reason to interpolate, and the value stays correct either way.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `per-frame rate = 0.12`
  Fraction of the remaining gap closed per frame at 60fps, converted through `perFrameToSmoothing`. It settles in about 300 ms — fast enough that a scrubber feels attached to the click, slow enough to read as motion. Above ~0.3 the damping is barely visible and the loop may as well be a jump; below ~0.05 the tail is long enough that a user beats it with the next click.
- `EPSILON = 0.0002`
  Snap threshold, in the units of the value. For the 0-1 normalised scrub position of the source this is a fifth of a pixel on a 1000 px track — invisible. Set it to 0 and the loop never parks, which is the exact bug this component exists to fix. Set it far too large and the last visible fraction of the travel is skipped as a jump.
- `MAX_DT = 0.1`
  Inherited from `useRaf`. A tab returning from the background delivers a multi-second delta; unclamped, `smoothing^dt` underflows to 0, the damp closes the entire gap in one frame, and the "settle" is a teleport.

## API

```ts
function useSelfParkingRaf(target: number, options: { smoothing?: number; epsilon?: number; onFrame: (value: number) => void }): { running: boolean; value: RefObject<number>; park: () => void }
```

- `target: number`
  The value to settle toward. Changing it wakes the loop; it is the only trigger.
- `smoothing: number` — default `perFrameToSmoothing(0.12)`
  Fraction of the gap remaining after one second. Smaller is snappier.
- `epsilon: number` — default `0.0002`
  Distance below which the value snaps to the target and the loop parks. Must match the unit of the value.
- `onFrame: (value: number) => void`
  Called with the damped value every frame while running, and once when it parks. For DOM writes.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * `0.12` of the gap per frame, measured at 60fps, expressed as the retention
 * factor `damp` wants. Using the raw 0.12 with a per-frame multiply would run
 * twice as fast on a 120 Hz display; this converges in the same wall-clock
 * time on any refresh rate.
 */
const SMOOTHING = perFrameToSmoothing(0.12);
/** The snap threshold. This single line is what allows the loop to end. */
const EPSILON = 0.0002;

/**
 * A damped value that runs a frame loop only while it is moving.
 *
 * `target` is a plain prop: changing it wakes the loop, and the loop parks
 * itself once it arrives. There is no `start`, and there is no
 * `requestAnimationFrame` running when the value is at rest.
 */
export function useSelfParkingRaf(
  target: number,
  options: SelfParkingOptions,
): SelfParkingValue {
  const { smoothing = SMOOTHING, epsilon = EPSILON } = options;
  const reduced = useReducedMotion();
  const visible = useVisibility();

  const value = useRef(target);
  const [running, setRunning] = useState(false);

  const config = useRef({ smoothing, epsilon, target, options });
  config.current = { smoothing, epsilon, target, options };

  const park = useCallback(() => {
    const cfg = config.current;
    value.current = cfg.target;
    cfg.options.onFrame(value.current);
    setRunning(false);
  }, []);

  // Waking the loop is the only thing a target change does. The guard matters:
  // without it, any unrelated re-render that happens to pass the same target
  // restarts a loop that had already parked.
  useEffect(() => {
    if (value.current === target) return;
    // Nothing to interpolate: reduced motion wants the end state, and a hidden
    // tab has no observer, so both arrive in one write instead of a loop.
    if (reduced || !visible) {
      park();
      return;
    }
    setRunning(true);
  }, [target, reduced, visible, park]);

  useRaf((dt) => {
    const cfg = config.current;
    let next = damp(value.current, cfg.target, cfg.smoothing, dt);

    // The whole technique. Asymptotic approach means `next` would otherwise
    // never equal `cfg.target`, so the exit test below could never pass.
    if (Math.abs(cfg.target - next) < cfg.epsilon) next = cfg.target;

    value.current = next;
    cfg.options.onFrame(next);

    // Parking flips `running`, which drops the `useRaf` subscription. When the
    // last subscriber goes, the shared loop cancels its frame entirely.
    if (next === cfg.target) setRunning(false);
  }, running);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useRaf` removes the subscription when `running` goes false or the component unmounts, and cancels the shared frame when it was the last subscriber — so an unmount mid-settle leaves nothing scheduled. The visibility and media-query listeners belong to `useVisibility` and `useReducedMotion`, which detach their own. No timers and no direct `requestAnimationFrame` handles are held.

**Reduced motion.** No loop is started at all. A target change calls `park()`, which assigns the target and emits a single `onFrame`, so the value lands on its final position in one write. That is the still, correct state rather than a zero-duration animation: `onFrame` still fires, so the DOM the consumer writes is identical to the end of a full settle, and `running` never goes true.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Omitting the epsilon snap. The value approaches the target forever, the exit test never passes, and one hover or one scrub leaves a rAF running for the rest of the session. It is invisible in a demo and shows up as a battery complaint.
- Expressing epsilon in the wrong unit. The threshold is compared against the value, so 0.0002 is correct for a 0-1 progress value and absurd for a pixel offset — at pixel scale it costs dozens of extra frames to cross, and the loop appears not to park.
- Keeping the loop alive to "avoid the cost of restarting it". Subscribing to a shared rAF is a `Set.add`; a frame callback plus the paint it dirties is orders of magnitude more. Restarting is free, running is not.
- Using `current += (target - current) * 0.12` directly. Frame-rate dependent: the same settle takes 300 ms at 60 Hz and 150 ms at 120 Hz, and speeds up mid-motion whenever a long task drops frames — the animation gets faster precisely when the page is struggling.
- Waking the loop without comparing against the current value. Every re-render that re-supplies the same target restarts the loop, which parks on its first frame and restarts on the next render — a loop that thrashes instead of resting.
- Calling `setState` from `onFrame`. That re-renders on every frame of the settle, which costs far more than the loop being parked ever saved. `onFrame` is for DOM writes.
- Reading the returned `value` ref during render. It changes between renders without notifying React, so the rendered output and the ref disagree; read it inside a frame callback or an event handler only.
- Forgetting that the loop is asleep when the target is set imperatively. Anything that mutates the underlying source without changing the `target` prop leaves the value stale, because nothing is polling — the trade for not running a loop is that changes must be declared.

## Notes

- The natural pairing is with an invalidate-driven renderer: a WebGL scene that renders only on demand plus a value that only moves on demand gives a page that is genuinely idle at rest, not merely cheap.
- The `park()` escape hatch exists for handoffs — a drag that takes over the value, or a route change that should not animate the old position. It emits one final `onFrame` so the DOM is left in the correct end state rather than mid-travel.
- `running` is exposed because parking is otherwise unobservable, and a component that claims to park should be able to prove it. The demo prints it beside a frame count that freezes.
- For several values settling together, one hook per value is fine — they all share the single `useRaf` loop, and the last one to park is the one that stops it.

## Definition of done

Click a timecode. The bar and the readout race to it and stop, and the status line goes from "rAF live" to "rAF parked" with the frame count frozen at roughly twenty — not climbing. Leave it alone for a minute: the count does not move. Open DevTools performance and record while idle after a seek; there are no animation frames. Click the timecode that is already active and nothing wakes. Switch tabs mid-settle and come back — the bar is already at its target with no catch-up sweep. With reduced motion on, a seek moves the bar in one step, the count reads 1, and the status never leaves "parked".

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Slab Page Transition

The outgoing page slides one screen height up and out while a solid slab rises from below to take its place. The route commits under the slab, the slab holds for a beat with the destination name on it, then the slab keeps travelling up and out while the new page follows it in from below. Nothing reverses direction at any point, which is the whole difference between a slab and a curtain: a curtain that drops and lifts reads as an interruption, a slab that passes through reads as travel.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

An opaque slab rises through the frame, the route changes under it, and it keeps going — nothing ever reverses.

- Category: transition
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. One paused GSAP timeline, played from zero on every navigation, covers the whole gesture. `to(content, { y: -H })` and `fromTo(slab, { y: +H }, { y: 0 })` both start at 0 and run for `duration`; a `.call()` at `duration` fires the caller's commit; `set(content, { y: +H })` on that same frame teleports the page below the frame; then `to(slab, { y: -H })` and `to(content, { y: 0 })` both start at `duration + hold`. Total length is `2 * duration + hold`.
2. The midpoint commit and the content teleport happen while the slab is exactly covering the frame, so neither is ever visible. That is the only reason the page can jump from -H to +H without a flash: there is an opaque surface in front of it for the whole of that frame.
3. Each half eases `power3.inOut` on its own rather than one tween covering the full 2H. An `inOut` across the whole travel is at its FASTEST in the middle — precisely where the slab has to look like it stopped. Two `inOut` halves meet at zero velocity, so the slab lands, holds, and leaves.
4. Travel is measured in pixels per run — `window.innerHeight` when `position="fixed"`, `root.getBoundingClientRect().height` when `"absolute"` — through GSAP function-based values. `yPercent: -100` would be 100% of the CONTENT element's own height, which on a long page is the whole document, so the page would fly thousands of pixels instead of one screen.
5. `tl.invalidate().play(0)` starts each run. `invalidate()` re-evaluates every function-based value, so a resized container or a flipped direction is picked up without rebuilding the timeline; without it the slab travels whatever height the box had when the component mounted.
6. Direction is a sign read from a ref inside those function values, and the ref is written in `run()` before `play(0)` rather than during render. `play(0)` renders the timeline synchronously, so a direction that only landed on the next React commit would be read one frame late and the two halves would disagree about which way is out.
7. The slab's parked position — `transform: translateY(100%)` — is declared in an injected stylesheet, not set from an effect. Effects run after the first paint, so a slab parked from JS is one frame of full-frame colour on mount. GSAP's inline transform outranks the rule while a transition runs, and when `useGsap` reverts it strips that inline value, which re-parks the slab with no extra code.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `SLAB_DURATION = 0.8`
  Seconds for ONE half; the full gesture is twice this plus the hold. The source ran 1 s per half and 0.8 keeps the weight while taking 0.4 s off the round trip. Under ~0.5 s the slab stops reading as a physical object and becomes a colour flash; over ~1.1 s the hold in the middle turns into a wait and people click a second nav item.
- `SLAB_HOLD = 0.12`
  Seconds the slab sits still at full cover. Two jobs: it is the beat in which the label is legible, and it is the margin in which React commits the destination — the commit fires at the start of the hold, so a page whose first layout costs two or three frames still finishes laying out before the slab moves off it. At 0 a heavy destination visibly settles while it is sliding in.
- `SLAB_EASE = 'power3.inOut'`
  Applied to each half separately. `inOut` is the only family that starts and ends at zero velocity, which is what makes the midpoint a stop rather than a peak. `power3` specifically: `power2` does not hold still long enough at the ends for the hold to read as deliberate, and `power4` spends so long near stationary that the 0.8 s feels like 1.2 s.
- `zIndex = 190`
  Above a custom cursor (150) and a scroll progress bar (120), both of which must be hidden during a transition, and below a preloader (200), which has to be able to sit over a slab on first load.

## API

```ts
function SlabPageTransition(props: { controller: SlabNavigation; children: ReactNode; duration?: number; hold?: number; direction?: "up" | "down"; color?: string; labelClassName?: string; position?: "fixed" | "absolute"; zIndex?: number; className?: string }): JSX.Element
function useSlabNavigation(): { host: RefObject<SlabRunner | null>; navigate: (commit: () => void, options?: { label?: string; direction?: "up" | "down" }) => void }
```

- `controller: SlabNavigation`
  From `useSlabNavigation()`. The component registers its runner on it.
- `children: ReactNode`
  The current page. Swapped by the `commit` you hand to `navigate`.
- `duration: number` — default `0.8`
  Seconds for ONE half. The full gesture is `2 * duration + hold`.
- `hold: number` — default `0.12`
  Seconds the slab holds at full cover, between the halves.
- `direction: "up" | "down"` — default `"up"`
  Default travel. Overridable per navigation via the options argument.
- `color: string` — default `'#000'`
  Any CSS colour. Must be opaque, or the swap shows through the slab.
- `labelClassName: string`
  Applied to the label span, so the caller owns its typography.
- `position: "fixed" | "absolute"` — default `"fixed"`
  `absolute` inside a bounded container; `fixed` for a real page transition.
- `zIndex: number` — default `190`
  Above the site and any custom cursor, below a preloader.
- `className: string`
  Merged onto the root via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * Seconds for one half. The source ran 1 s per half; 0.8 keeps the weight and
 * takes 0.4 s off the round trip. Under ~0.5 s the slab stops reading as a
 * physical object and becomes a colour flash; over ~1.1 s the hold in the
 * middle turns into a wait, and people click a second nav item.
 */
export const SLAB_DURATION = 0.8;

/**
 * Seconds the slab sits still at full cover, between the two halves. Two jobs:
 * it is the beat in which the slab's label is legible, and it is the margin in
 * which React commits the destination. The commit fires at the start of the
 * hold, so a destination whose first layout costs two or three frames still
 * finishes laying out before the slab starts moving off it. At 0 a heavy page
 * visibly settles while it is sliding in.
 */
export const SLAB_HOLD = 0.12;

/** Both halves. `inOut` on each is what makes the midpoint a stop, not a peak. */
const SLAB_EASE = 'power3.inOut';

const SLAB_CSS = `
.kx-slab-panel {
  /* An opaque full-frame surface must never eat a click, not even while it is
     covering. Mid-transition the pointer is usually already aimed at the next
     nav item. */
  pointer-events: none;
  z-index: var(--kx-slab-z, 190);
  background: var(--kx-slab-color, #000);
  display: flex;
  align-items: center;
  justify-content: center;
  overflow: hidden;
}
/* The parked position lives in CSS, not in an inline style and not in a
   'gsap.set' inside an effect. Effects run after the first paint, so a slab
   parked from JS is one frame of full-frame colour on mount. GSAP's inline
   'transform' outranks these rules while a transition runs, and when
   'useGsap' reverts it strips that inline value — which parks the slab again
   with no extra code. */
.kx-slab-park-up { transform: translateY(100%); }
.kx-slab-park-down { transform: translateY(-100%); }
`;

export interface SlabNavigateOptions {
  /** Written into the slab, legible during the hold. */
  label?: string;
  /** Overrides the component's `direction` for this one navigation. */
  direction?: 'up' | 'down';
}

/** What the component registers on the controller. Internal. */
export interface SlabRunner {
  run: (commit: () => void, options?: SlabNavigateOptions) => void;
}

export interface SlabNavigation {
  /** Pass straight to `<SlabPageTransition controller>`. Do not read it. */
  host: RefObject<SlabRunner | null>;
  /**
   * Raise the slab, run `commit` — your navigation — under it, then lower the
   * page in behind it.
   */
  navigate: (commit: () => void, options?: SlabNavigateOptions) => void;
}

/**
 * The caller's half. `commit` is a callback rather than a router call, so
 * nothing here depends on a routing library.
 */
export function useSlabNavigation(): SlabNavigation {
  const host = useRef<SlabRunner | null>(null);

  const navigate = useCallback(
    (commit: () => void, options?: SlabNavigateOptions) => {
      const runner = host.current;
      // No mounted component — the caller wired the hook up but rendered the
      // transition conditionally, or this fired during the first commit.
      // Navigate anyway. A transition that swallows navigations is worse than
      // no transition.
      if (!runner) {
        commit();
        return;
      }
      runner.run(commit, options);
    },
    [],
  );

  return useMemo(() => ({ host, navigate }), [navigate]);
}

export interface SlabPageTransitionProps {
  /** From `useSlabNavigation()`. */
  controller: SlabNavigation;
  /** The current page. Swapped by the `commit` you hand to `navigate`. */
  children: ReactNode;
  /** Seconds for ONE half. The full gesture is `2 * duration + hold`. */
  duration?: number;
  /** Seconds the slab holds at full cover between the halves. */
  hold?: number;
  /**
   * Default travel. `up` sends everything upward; `down` mirrors it, which is
   * what a back navigation wants. Overridable per navigation.
   */
  direction?: 'up' | 'down';
  /** Any CSS colour. Must be opaque, or the swap shows through the slab. */
  color?: string;
  /** Applied to the label span so the caller owns its type. */
  labelClassName?: string;
  /** `absolute` to demo inside a bounded box; `fixed` for a real page. */
  position?: 'fixed' | 'absolute';
  /** Above the site, below a preloader. */
  zIndex?: number;
  className?: string;
}

export function SlabPageTransition({
  controller,
  children,
  duration = SLAB_DURATION,
  hold = SLAB_HOLD,
  direction = 'up',
  color = '#000',
  labelClassName,
  position = 'fixed',
  zIndex = 190,
  className,
}: SlabPageTransitionProps) {
  const root = useRef<HTMLDivElement>(null);
  const content = useRef<HTMLDivElement>(null);
  const slab = useRef<HTMLDivElement>(null);
  const labelEl = useRef<HTMLSpanElement>(null);

  const timeline = useRef<ReturnType<typeof gsap.timeline> | null>(null);
  const pending = useRef<(() => void) | null>(null);
  const reduced = useReducedMotion();

  // Read inside the tweens' function-based values, so flipping direction
  // between navigations needs no rebuild — and therefore no `revert()`, which
  // would strip the transform GSAP is mid-way through writing. Set in `run`,
  // never during render: `play(0)` renders the timeline synchronously, so a
  // value that only lands on the next React commit would be read one frame
  // too late and the two halves would disagree about which way is out.
  const dir = useRef<'up' | 'down'>(direction);
  const defaultDir = useRef(direction);
  defaultDir.current = direction;

  // Built once and held paused. `direction` is deliberately NOT a dependency:
  // `useGsap` reverts on every dependency change, and revert removes the
  // inline transform, so a rebuild during a transition drops the slab back to
  // its CSS park mid-cover and the swap is visible.
  useGsap(
    gsap,
    () => {
      const rootEl = root.current;
      const contentEl = content.current;
      const slabEl = slab.current;
      if (!rootEl || !contentEl || !slabEl) return;

      // Travel in pixels, measured per run. `yPercent: -100` would be 100% of
      // the CONTENT's own height — on a long page that is the whole document,
      // so the page would fly thousands of pixels instead of one screen. The
      // original wrote `y: '-100vh'` for exactly this reason; measuring the
      // real box also gets the bounded case right, where one screen is the
      // container and not the viewport.
      const travel = () =>
        position === 'fixed'
          ? window.innerHeight
          : rootEl.getBoundingClientRect().height;
      const sign = () => (dir.current === 'down' ? -1 : 1);

      const tl = gsap.timeline({ paused: true });

      tl.to(contentEl, { y: () => -travel() * sign(), duration, ease: SLAB_EASE }, 0)
        .fromTo(
          slabEl,
          { y: () => travel() * sign() },
          { y: 0, duration, ease: SLAB_EASE },
          0,
        )
        // Midpoint. The slab is exactly covering the frame for the whole of
        // this and the `set` below, so neither is ever seen.
        .add(() => {
          const commit = pending.current;
          pending.current = null;
          commit?.();
        })
        .set(contentEl, { y: () => travel() * sign() })
        .to(
          slabEl,
          { y: () => -travel() * sign(), duration, ease: SLAB_EASE },
          duration + hold,
        )
        .to(contentEl, { y: 0, duration, ease: SLAB_EASE }, duration + hold)
        // Re-park the slab below the frame at the very end, so `progress(0)`
        // and `progress(1)` describe the same rest state and a second run
        // starts from a known place rather than from wherever it stopped.
        .set(slabEl, { y: () => travel() * sign() });

      timeline.current = tl;

      return () => {
        timeline.current = null;
        // A dependency change reverts and kills this timeline. If it happened
        // mid-transition the commit had not fired yet, so fire it here: the
        // visitor clicked a link and must end up on that page whatever the
        // animation did.
        const commit = pending.current;
        pending.current = null;
        commit?.();
      };
    },
    root,
    [duration, hold, position],
  );

  const run = useCallback(
    (commit: () => void, options?: SlabNavigateOptions) => {
      const tl = timeline.current;
      const span = labelEl.current;
      if (span) span.textContent = options?.label ?? '';
      dir.current = options?.direction ?? defaultDir.current;

      // Reduced motion: no slab and a synchronous commit. Not a zero-duration
      // slab — that is still one frame of full-frame colour, which is the
      // single most unpleasant thing to show someone who asked for less
      // motion. `pause(0)` suppresses callbacks, so the midpoint `.call()`
      // cannot fire a second commit.
      if (!tl || reduced) {
        tl?.pause(0);
        commit();
        return;
      }
      // A second click while the slab is in flight would queue a second commit
      // and land the visitor one page past where they aimed.
      if (tl.isActive()) return;

      pending.current = commit;
      // `invalidate()` before replaying re-evaluates every function-based
      // value: the box may have been resized, and `direction` may have
      // flipped, since the timeline was built. Without it the slab travels the
      // height the container had on mount.
      tl.invalidate().play(0);
    },
    [reduced],
  );

  useEffect(() => {
    const host = controller.host;
    host.current = { run };
    return () => {
      if (host.current?.run === run) host.current = null;
    };
  }, [controller, run]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useGsap` reverts the `gsap.context`, which kills the timeline and strips every inline transform it wrote — restoring the slab to the parked position its stylesheet rule specifies and the page to `y: 0`. The cleanup also flushes any commit that had not fired yet, so a prop change mid-transition cannot lose a navigation. The runner registration is removed from the controller on unmount, and it is removed only if it is still the current one, so a remount cannot null out the live handle.

**Reduced motion.** The timeline is never played. `navigate()` calls the commit synchronously and `tl.pause(0)` resets the slab to its rest position — deliberately not a zero-duration slab, which is still one frame of full-frame colour. `pause()` suppresses callbacks, so the midpoint `.call()` cannot fire a second commit. Navigation is a hard cut straight to the destination in both directions.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Using `yPercent: -100` on the page wrapper. Percentage transforms resolve against the element's OWN height, so on a 6000 px page the wrapper travels 6000 px in 0.8 s and the screen just goes blank a frame in. The travel has to be one screen — measured in pixels, or written as the original did with an explicit `vh` unit.
- Reversing the slab instead of driving it through. `tl.reverse()` after the commit sends the slab back down the way it came, and the eye reads the whole thing as a mistake being undone rather than as a move. The second half is a separate forward tween to `-H`.
- One `power3.inOut` across the full 2H travel. That ease is at maximum speed at its own midpoint, which is exactly the frame the route changes on, so the slab appears to accelerate straight through the cover and the label is unreadable.
- Putting the direction flag in the `useGsap` dependency list. Every dependency change reverts the context, and `revert()` strips the inline transform GSAP is mid-way through writing — so flipping direction during a transition drops the slab back to its CSS park while it is meant to be covering, and the content swap is visible. Direction is read from a ref by function-based values instead.
- Parking the slab with `gsap.set` in an effect. Effects run after the first paint, so the first frame of the page is a full-frame slab. The rest position belongs in a stylesheet; GSAP overrides it from the inline style the moment it is needed.
- Setting the slab label through state. `setLabel()` inside the navigate handler re-renders the subtree React is about to hand to GSAP on the exact frame the timeline starts. The label is one `textContent` write on a ref, and the slab is off-frame when it happens.
- Letting a second click start a second run. Without the `tl.isActive()` guard a double click queues two commits and the visitor lands one page past where they aimed.
- Dropping the commit when the timeline is destroyed. If a prop change reverts the context mid-transition, the `.call()` never fires and the route never changes — the visitor clicked a link and stayed put. The `useGsap` cleanup flushes any pending commit.
- Leaving the slab clickable. A full-frame opaque div swallows the pointer for the length of the transition, and mid-transition the pointer is usually already aimed at the next nav item. It carries `pointer-events: none` and `aria-hidden`.

## Notes

- In Next.js App Router: mount once in `app/layout.tsx` with `position="fixed"`, then replace nav `<Link>` elements with buttons calling `navigate(() => router.push(href), { label })`. Nothing in this file imports `next/navigation` — the commit is a callback, so the same component works under React Router or a plain `useState` page switch.
- The content wrapper stays in normal flow. A transform moves an element without taking it out of flow, so the page keeps its own height and the document still scrolls — which an `absolute inset-0` wrapper would break on any real page.
- The colour must be opaque. A translucent slab shows the content teleport at the midpoint, which is the single artefact this technique exists to hide.
- Browser back and forward change the route without going through `navigate()`, so they get no slab. That is correct: by the time your code hears about a history navigation it has already happened, and there is nothing left to cover.
- Set `direction: "down"` per navigation for anything that reads as going back — an up-nav click, a breadcrumb, a close button — and the site acquires a sense of which way the visitor is travelling for the cost of one ternary.

## Definition of done

Click a nav item: the page slides up out of frame while a coloured slab rises from below, the slab pauses at full cover with the destination name on it, then continues up and out while the new page follows it in from below. The slab never travels downward on a forward navigation, and there is no frame in which old and new content are both visible. Click a nav item to the left of the current one and the whole gesture mirrors — everything travels down. Click two items in quick succession and you land on the first one you clicked, not past it. Resize the preview and navigate again: the slab still travels exactly one frame height. With reduced motion the content swaps instantly with no coloured frame in either direction.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Slow Idle Float

The ambient motion you put on a hero image, a floating card or a badge so the page does not feel frozen. Fourteen pixels over five seconds is under the threshold at which the eye tracks it as movement — you read it as presence. Because it animates `translate` rather than `transform`, the element can still carry a hover scale or a tilt without the two fighting.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A 14px rise and fall over 5 seconds, on the independent translate property so hover transforms still work.

- Category: primitive
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. A two-pose keyframe: `0%, 100% { translate: 0 0 }` and `50% { translate: var(--kx-float-x) var(--kx-float-y) }`. Both endpoints of the round trip are the resting position, so the loop has no seam and the element always returns to exactly its layout position.
2. The animated property is `translate`, not `transform`. They are separate properties that compose in the order translate, rotate, scale, transform — so a consumer can put `hover:scale-105` (a `transform`) on the same element and both apply. An animation on `transform` would instead override any transition on `transform` for its entire duration, and the hover would appear dead.
3. Direction comes from custom properties rather than separate keyframe blocks: `axis="y"` writes `--kx-float-y: -14px` and leaves X at 0, `axis="x"` does the reverse. One keyframe block covers both axes and any diagonal a consumer wants to set by hand.
4. `phase` is applied as a negative `animation-delay` — `-durationMs * phase`. A negative delay means the animation is treated as having already been running for that long, so an element starts mid-flight on its first painted frame. A positive delay would make it sit dead still until its turn came round, which is exactly what makes staggered idle animations look broken on load.
5. `ease-in-out` is what makes it buoyant. The element decelerates into both extremes and hangs there; `linear` gives constant velocity and reads as a mechanical lift.
6. `will-change: translate` names the property that is actually animating. `will-change: transform` — the reflex — hints at a property this component never touches.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `distance = 14px`
  Peak travel. Average speed works out at roughly 11px per second, which is below the rate at which the eye starts tracking an object instead of just registering it. Under about 6px the motion is invisible on a 1x display; over about 24px it reads as a balloon on a string and pulls focus from the content.
- `durationMs = 5000`
  The round trip. Faster than about 3s and it becomes a pulse that competes with real feedback in the UI; slower than about 8s and the element appears to have simply drifted out of position rather than to be floating.
- `timing function = ease-in-out`
  Buoyancy comes from the hold at the two extremes. `linear` moves at constant velocity, which reads as a machine; `ease-out` alone makes the return leg abrupt and the loop develops a visible tick at 100%.
- `phase sign = negative`
  Negative delay starts the animation partway through its first cycle instead of postponing it. With a positive delay a staggered group is motionless for the first phase*duration milliseconds after mount — on a five-second cycle with four items that is several seconds of a page that looks frozen.

## API

```ts
function SlowFloatIdle(props: { children: ReactNode; distance?: number; durationMs?: number; axis?: 'x' | 'y'; phase?: number; className?: string }): JSX.Element
```

- `children: ReactNode`
  What floats. Wrapped in a block-level element that owns the `translate`.
- `distance: number` — default `14`
  Peak travel in pixels, reached at the midpoint of the cycle.
- `durationMs: number` — default `5000`
  Full round trip in milliseconds.
- `axis: 'x' | 'y'` — default `'y'`
  Direction of travel. `y` rises then falls; `x` drifts right then back.
- `phase: number` — default `0`
  Start position in the cycle, 0-1. Applied as a negative `animation-delay`.
- `className: string`
  Merged onto the wrapper via `cn`. Safe to use `transform`-based utilities here — the float does not use `transform`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const FLOAT_CSS = `
@keyframes kx-float-idle {
  0%, 100% { translate: 0 0; }
  50%      { translate: var(--kx-float-x, 0px) var(--kx-float-y, -14px); }
}

.kx-float {
  display: block;
  animation: kx-float-idle var(--kx-float-duration, 5s) ease-in-out infinite;
  animation-delay: var(--kx-float-delay, 0s);
  /* Names the property that is actually animating. 'will-change: transform'
     is the reflex here and it hints at the wrong property entirely. */
  will-change: translate;
}

/* No motion: the element rests at its natural layout position, not at the
   midpoint of the float. The hint is released too — a promoted layer for an
   animation that is not running is pure GPU memory. */
@media (prefers-reduced-motion: reduce) {
  .kx-float {
    animation: none;
    will-change: auto;
  }
}
`;

export function SlowFloatIdle({
  children,
  distance = 14,
  durationMs = 5000,
  axis = 'y',
  phase = 0,
  className,
}: SlowFloatIdleProps) {
  const style: StyleWithVars = {
    '--kx-float-duration': `${durationMs}ms`,
    // Negative: the animation is treated as having already run for this long,
    // so a set of floats is out of phase from the very first frame.
    '--kx-float-delay': `${-durationMs * phase}ms`,
    // Rise, not fall: negative Y is up. X drifts right on the positive side.
    '--kx-float-x': axis === 'x' ? `${distance}px` : '0px',
    '--kx-float-y': axis === 'y' ? `${-distance}px` : '0px',
  };

  return (
    <>
      <style href="kinetic-slow-float-idle" precedence="medium">
        {FLOAT_CSS}
      </style>
      <div className={cn('kx-float', className)} style={style}>
        {children}
      </div>
    </>
  );
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nothing to clean up. No listeners, no timers, no animation frames. Unmounting removes the element and its CSS animation; React removes the hoisted `<style>` when the last instance unmounts.

**Reduced motion.** A `@media (prefers-reduced-motion: reduce)` block sets `animation: none` and `will-change: auto`. The element rests at its natural layout position — not at the top of the float — so nothing shifts and no gap appears where the animation used to be.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Animating `transform` instead of `translate`. Animations beat transitions on the same property for as long as they run, so a `transition: transform` hover on the same element never has a visible effect — the hover looks broken and the cause is a keyframe elsewhere in the file.
- Animating `top` or `margin-top` for the float. Those are layout properties: the ancestor reflows on every frame and any sibling laid out after it jitters. Only `translate`, `transform`, `opacity` and `filter` stay off the layout path.
- Staggering a group with positive `animation-delay`. Every element holds at its 0% pose until its delay expires, so the group starts as a static row and comes alive one item at a time — most visible right after a page load, which is the worst possible moment.
- Setting `will-change: transform` for an animation on `translate`. The hint names a property that never changes; the browser may still promote the layer for other reasons, so the mistake produces no error and no benefit.
- Leaving `will-change` on when reduced motion is active. The element keeps a dedicated compositor layer for an animation that has been switched off — cost with no motion in exchange.
- Parking the element at the midpoint of the float for reduced motion. The float exists to add life, not to reposition anything; freezing it 14px above its layout position leaves a permanent, unexplained gap under the element.

## Notes

- The independent `translate`, `rotate` and `scale` properties need Chrome 104+, Safari 14.1+ and Firefox 72+. In an older engine the declaration is dropped and the element simply does not float — the layout is unaffected.
- The wrapper is a `div` with `display: block`. To float an inline element, pass `className="inline-block"`; a floated `display: inline` box would have nothing to translate.
- For a group, give each instance a different `phase` — 0, 0.25, 0.5, 0.75 for four items. Equal phases make the group move as one rigid object, which is more noticeable than no motion at all.

## Definition of done

The element rises about 14px, hangs, and settles back over five seconds with no visible tick at the loop point. Add a `hover:scale-110` to the same element and the scale still works while the float continues. Give three instances phases 0, 0.33 and 0.66 and all three are already at different heights on the first painted frame. With reduced motion on, the element sits exactly where the layout puts it.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Spring Lattice Field

A grid that behaves like a stretched sheet. A coarse lattice of damped springs runs on the CPU, is packed into an RGBA8 texture once per frame, and the fragment shader reads that texture with LINEAR filtering to displace its own sample coordinate. The pointer pushes cells outward and drags them along with its velocity; diffusion between neighbours turns each push into a wave that spreads and settles.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A CPU damped-spring lattice uploaded as a texture each frame, displacing a procedural grid the cursor can push around.

- Category: webgl
- Runtime cost: webgl
- Dependencies: none beyond React

## How it works

1. The lattice is `round(width / cellSize)` by `round(height / cellSize)` cells, sized in CSS pixels rather than device pixels so the simulation is identical on a retina display instead of running four times as many cells.
2. Each step, cells within `radius` of the pointer receive two impulses: a radial one along `(cell - pointer) / |cell - pointer|` scaled by `radialStrength`, and a flow one along the pointer's own velocity scaled by `flowStrength`. Both are weighted by `t*t*(3-2t)` where `t = 1 - dist/radius` — a smoothstep falloff, C1 at both ends, so the disturbance has no visible rim.
3. Then `vel = (vel - disp * returnStiffness) * velocityDamping` and `nextDisp = disp + vel + (neighbourAverage - disp) * diffusion`. The diffusion term is what makes it a sheet rather than a field of independent springs: a local push propagates outward as a wave instead of staying put.
4. The integration writes into a scratch buffer, not in place. In place, the +x and +y neighbours would already hold the new value when a cell reads them, and the wave would visibly drift toward the lattice origin.
5. Displacement is packed into the texture as `d / DISP_MAX * 0.5 + 0.5` in RG, with cell speed in B. Speed, not displacement, drives the glow — so the field lights up while it is moving and goes dark once it settles, which is what reads as elastic rather than as a permanent dent.
6. The shader adds `disp / gridDimensions` to its uv before drawing an `fwidth`-normalised grid, so lines stay one pixel wide even where the field is stretching them, and `u_density` is set to the lattice row count so the drawn lines land on cell boundaries.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `STEP = 1 / 60`
  Fixed simulation timestep. Every other physics constant is expressed per step — `velocityDamping = 0.93` only means "keep 93% per 1/60 s" if the step is always 1/60 s. Integrating per frame instead makes the field stiffer on a 60 Hz laptop than on a 120 Hz phone.
- `MAX_SUBSTEPS = 4`
  Catch-up ceiling. Returning to a backgrounded tab otherwise tries to simulate the whole elapsed time in one frame and the page locks up for seconds. The leftover accumulator is discarded when the ceiling is hit, or the debt compounds and the simulation runs saturated forever.
- `returnStiffness = 0.018`
  Spring constant per step. Above ~0.05 the lattice snaps back before the wave can spread and it reads as rubber sheeting; below ~0.006 disturbances take several seconds to clear and the grid looks permanently dented.
- `velocityDamping = 0.93`
  Velocity retained per step. At 1.0 the lattice never loses energy and rings forever; below ~0.85 the push is absorbed within a few cells and nothing propagates.
- `diffusion = 0.22`
  Fraction of the way each cell moves toward its neighbours' average per step. This is the wave speed. Past 0.25 the explicit scheme goes unstable and the lattice fills with checkerboard noise; near 0 the cells decouple and the grid dimples pointwise.
- `radius = 5.5`
  Pointer influence, in cells. Expressed in cells rather than pixels so the physics is unchanged at any `cellSize`. Under ~3 the cursor pokes a hole; past ~10 it lifts the whole panel and the motion loses its centre.
- `radialStrength = 0.02`
  Sustained outward push per step. Equilibrium displacement is roughly `radialStrength / returnStiffness` ≈ 1.1 cells — enough for the grid to visibly part around a resting cursor without approaching the encode range.
- `flowStrength = 0.08`
  Drag along the pointer velocity. A transient impulse peaks at about `impulse / (1 - velocityDamping)` ≈ 14x, so this is roughly ten times smaller than the radial constant for a comparable displacement. Raise it and fast swipes clip the encode range.
- `MAX_POINTER_SPEED = 45`
  Cells per second. A pointer that teleports across the element — tab switch, window drag, the first event after a long pause — otherwise injects one enormous impulse and the whole lattice snaps in a single step.
- `DISP_MAX = 2.5`
  Encode range in cells. Displacement is clamped to it before packing into 8 bits; an unclamped value wraps the byte and the cell flips to the opposite sign, which reads as a hard pop exactly where the motion is strongest.
- `cellSize = 18`
  CSS pixels per cell. Cost is quadratic: at 6 a 1440x900 panel is 36,000 cells and the step stops fitting in a frame. Above ~30 the lattice is coarse enough that LINEAR interpolation between cells becomes visible as flat facets.

## API

```ts
function SpringLatticeField(props: { cellSize?: number; radius?: number; radialStrength?: number; flowStrength?: number; ink?: readonly [number, number, number]; line?: readonly [number, number, number]; glow?: readonly [number, number, number]; maxDpr?: number; className?: string }): JSX.Element
```

- `cellSize: number` — default `18`
  CSS pixels per lattice cell. Cost is quadratic in this.
- `radius: number` — default `5.5`
  Pointer influence radius, in lattice cells.
- `radialStrength: number` — default `0.02`
  Outward push per fixed step, in cells/step².
- `flowStrength: number` — default `0.08`
  How strongly pointer velocity drags cells along with it.
- `ink: readonly [number, number, number]` — default `[0.035, 0.038, 0.048]`
  Base field colour, linear 0..1 RGB.
- `line: readonly [number, number, number]` — default `[0.16, 0.17, 0.2]`
  Grid line colour, added on top of ink.
- `glow: readonly [number, number, number]` — default `[0.35, 0.62, 0.95]`
  Colour added in proportion to cell speed.
- `maxDpr: number` — default `2`
  Upper bound on device pixel ratio.
- `className: string`
  Merged onto the host element.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const TRIANGLE = new Float32Array([-1, -1, 3, -1, -1, 3]);
const MAX_DPR = 2;

/* The simulation runs on a fixed timestep. Every constant below is tuned per
   STEP — `velocityDamping = 0.93` means "keep 93% of the velocity after 1/60 of
   a second", and it only means that if the step is always 1/60 of a second. A
   per-frame integration would make the field stiffer on a 60 Hz laptop than on
   a 120 Hz phone, which is the exact failure mode the frame-rate independence
   rule exists to prevent. Everything here is in LATTICE CELLS, not pixels, so
   the physics is identical at any cellSize. */
const STEP = 1 / 60;
/* Ceiling on catch-up steps per frame. Without it, returning to a backgrounded
   tab tries to simulate the whole elapsed time in one frame and the page hangs;
   with it, the field simply resumes from where it was. */
const MAX_SUBSTEPS = 4;

const RETURN_STIFFNESS = 0.018;
const VELOCITY_DAMPING = 0.93;
const DIFFUSION = 0.22;
/* Pointer speed cap, cells/second. A pointer teleporting across the element
   (tab switch, window drag) otherwise injects one enormous impulse and the
   lattice snaps past the encode range in a single step. */
const MAX_POINTER_SPEED = 45;
/* Encode range in cells. Displacement is packed into 8 bits as
   `d / DISP_MAX * 0.5 + 0.5`, so anything beyond this must be clamped — an
   unclamped value wraps the byte and the cell flips to the opposite sign,
   which reads as a hard pop. */
const DISP_MAX = 2.5;
/* Maps cell speed (cells/step) into the 0..1 glow channel. */
const ENERGY_SCALE = 6;

const MIN_CELLS = 8;
const MAX_CELLS = 80;

interface Lattice {
  cols: number;
  rows: number;
  /** Interleaved x,y displacement per cell, in cells. */
  disp: Float32Array;
  /** Interleaved x,y velocity per cell, in cells/step. */
  vel: Float32Array;
  /** Scratch buffer — diffusion must read the whole previous state. */
  next: Float32Array;
  /** RGBA8 upload staging. */
  pixels: Uint8Array;
}

function createLattice(cols: number, rows: number): Lattice {
  const cells = cols * rows;
  return {
    cols,
    rows,
    disp: new Float32Array(cells * 2),
    vel: new Float32Array(cells * 2),
    next: new Float32Array(cells * 2),
    pixels: new Uint8Array(cells * 4),
  };
}

/* One fixed-timestep step. Pointer position is in cell coordinates; pointer
   velocity is in cells/second and is converted here, so the caller does not
   have to know the step length. */
function stepLattice(
  lattice: Lattice,
  pointerX: number,
  pointerY: number,
  pointerVX: number,
  pointerVY: number,
  active: boolean,
  radius: number,
  radialStrength: number,
  flowStrength: number,
): void {
  const { cols, rows, disp, vel, next } = lattice;

  if (active) {
    // Only the cells inside the radius can be touched, so bound the loop
    // instead of testing every cell. At radius 5.5 that is ~120 cells out of
    // a couple of thousand.
    const minX = Math.max(0, Math.floor(pointerX - radius));
    const maxX = Math.min(cols - 1, Math.ceil(pointerX + radius));
    const minY = Math.max(0, Math.floor(pointerY - radius));
    const maxY = Math.min(rows - 1, Math.ceil(pointerY + radius));
    const flowX = pointerVX * STEP * flowStrength;
    const flowY = pointerVY * STEP * flowStrength;

    for (let y = minY; y <= maxY; y++) {
      for (let x = minX; x <= maxX; x++) {
        const dx = x - pointerX;
        const dy = y - pointerY;
        const dist = Math.sqrt(dx * dx + dy * dy);
        if (dist > radius) continue;

        /* Smoothstep falloff, not linear. A linear falloff has a corner at the
           radius: cells cross the boundary with non-zero force and the edge of
           the disturbance is a visible circle. `t*t*(3-2t)` is C1 at both ends,
           so the influence dies out with zero slope and no rim appears. */
        const t = 1 - dist / radius;
        const shaped = t * t * (3 - 2 * t);

        // At dist 0 the direction is undefined; pushing nothing is correct.
        const inv = dist > 1e-4 ? 1 / dist : 0;
        const i = (y * cols + x) * 2;
        vel[i] = (vel[i] ?? 0) + dx * inv * shaped * radialStrength + flowX * shaped;
        vel[i + 1] =
          (vel[i + 1] ?? 0) + dy * inv * shaped * radialStrength + flowY * shaped;
      }
    }
  }

  // Spring toward rest, then bleed energy. Damping applied AFTER the spring
  // term keeps the system unconditionally stable at these constants.
  for (let i = 0; i < vel.length; i++) {
    vel[i] = ((vel[i] ?? 0) - (disp[i] ?? 0) * RETURN_STIFFNESS) * VELOCITY_DAMPING;
  }

  /* Integrate and diffuse in one pass into `next`. Diffusion is what makes the
     lattice behave like a sheet rather than a field of independent springs:
     each cell is pulled `DIFFUSION` of the way toward its four neighbours'
     average, so a local push propagates outward as a wave. Writing in place
     would make the result depend on iteration order — the +x and +y neighbours
     would already be updated, and the wave would drift toward the origin. */
  for (let y = 0; y < rows; y++) {
    for (let x = 0; x < cols; x++) {
      const i = (y * cols + x) * 2;
      for (let c = 0; c < 2; c++) {
        const self = disp[i + c] ?? 0;
        // Edges mirror themselves: a free boundary. Clamping them to zero
        // instead pins the border and every wave reflects off it.
        const left = x > 0 ? disp[i - 2 + c] ?? self : self;
        const right = x < cols - 1 ? disp[i + 2 + c] ?? self : self;
        const up = y > 0 ? disp[i - cols * 2 + c] ?? self : self;
        const down = y < rows - 1 ? disp[i + cols * 2 + c] ?? self : self;
        const avg = (left + right + up + down) * 0.25;
        next[i + c] = self + (vel[i + c] ?? 0) + (avg - self) * DIFFUSION;
      }
    }
  }

  disp.set(next);
}

/** Pack displacement into RG and speed into B. Returns total energy. */
function encodeLattice(lattice: Lattice): number {
  const { disp, vel, pixels } = lattice;
  const cells = lattice.cols * lattice.rows;
  let total = 0;

  for (let c = 0; c < cells; c++) {
    const i = c * 2;
    const dx = disp[i] ?? 0;
    const dy = disp[i + 1] ?? 0;
    const vx = vel[i] ?? 0;
    const vy = vel[i + 1] ?? 0;
    const speed = Math.sqrt(vx * vx + vy * vy);
    total += speed;

    const o = c * 4;
    pixels[o] = encodeSigned(dx);
    pixels[o + 1] = encodeSigned(dy);
    pixels[o + 2] = Math.min(255, Math.round(speed * ENERGY_SCALE * 255));
    pixels[o + 3] = 255;
  }

  return total;
}

function encodeSigned(value: number): number {
  const n = value / DISP_MAX;
  const clamped = n < -1 ? -1 : n > 1 ? 1 : n;
  return Math.round((clamped * 0.5 + 0.5) * 255);
}

interface Pass {
  gl: WebGL2RenderingContext;
  program: WebGLProgram;
  vao: WebGLVertexArrayObject;
  buffer: WebGLBuffer;
  texture: WebGLTexture;
  locations: Map<string, WebGLUniformLocation | null>;
  /** Allocated texture dimensions, so resize can tell reallocation from upload. */
  texCols: number;
  texRows: number;
}

function compileShader(
  gl: WebGL2RenderingContext,
  type: number,
  source: string,
): WebGLShader | null {
  const shader = gl.createShader(type);
  if (!shader) return null;
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
    console.error('[spring-lattice-field]', gl.getShaderInfoLog(shader));
    gl.deleteShader(shader);
    return null;
  }
  return shader;
}

function createPass(gl: WebGL2RenderingContext): Pass | null {
  const vert = compileShader(gl, gl.VERTEX_SHADER, SPRING_LATTICE_VERT);
  const frag = compileShader(gl, gl.FRAGMENT_SHADER, SPRING_LATTICE_FRAG);
  const program = gl.createProgram();
  if (!vert || !frag || !program) {
    if (vert) gl.deleteShader(vert);
    if (frag) gl.deleteShader(frag);
    if (program) gl.deleteProgram(program);
    return null;
  }

  gl.attachShader(program, vert);
  gl.attachShader(program, frag);
  gl.linkProgram(program);
  gl.deleteShader(vert);
  gl.deleteShader(frag);

  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
    console.error('[spring-lattice-field]', gl.getProgramInfoLog(program));
    gl.deleteProgram(program);
    return null;
  }

  const vao = gl.createVertexArray();
  const buffer = gl.createBuffer();
  const texture = gl.createTexture();
  if (!vao || !buffer || !texture) {
    gl.deleteProgram(program);
    if (vao) gl.deleteVertexArray(vao);
    if (buffer) gl.deleteBuffer(buffer);
    if (texture) gl.deleteTexture(texture);
    return null;
  }

  gl.bindVertexArray(vao);
  gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
  gl.bufferData(gl.ARRAY_BUFFER, TRIANGLE, gl.STATIC_DRAW);
  const attrib = gl.getAttribLocation(program, 'a_pos');
  if (attrib >= 0) {
    gl.enableVertexAttribArray(attrib);
    gl.vertexAttribPointer(attrib, 2, gl.FLOAT, false, 0, 0);
  }
  gl.bindVertexArray(null);

  gl.activeTexture(gl.TEXTURE0);
  gl.bindTexture(gl.TEXTURE_2D, texture);
  /* LINEAR is load-bearing, not a default: it is what turns a 40x24 simulation
     into a smooth field across two million fragments. CLAMP_TO_EDGE because
     REPEAT would sample the opposite edge of the lattice at the border and
     stamp a seam there. */
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);

  return {
    gl,
    program,
    vao,
    buffer,
    texture,
    locations: new Map(),
    texCols: 0,
    texRows: 0,
  };
}

function uniformLocation(pass: Pass, name: string): WebGLUniformLocation | null {
  const cached = pass.locations.get(name);
  if (cached !== undefined) return cached;
  const found = pass.gl.getUniformLocation(pass.program, name);
  pass.locations.set(name, found);
  return found;
}

function setVec3(
  gl: WebGL2RenderingContext,
  location: WebGLUniformLocation | null,
  v: readonly [number, number, number],
): void {
  if (location === null) return;
  gl.uniform3f(location, v[0], v[1], v[2]);
}

function disposePass(pass: Pass): void {
  const { gl } = pass;
  gl.deleteVertexArray(pass.vao);
  gl.deleteBuffer(pass.buffer);
  gl.deleteTexture(pass.texture);
  gl.deleteProgram(pass.program);
  loseContext(gl);
}

export function SpringLatticeField({
  cellSize = 18,
  radius = 5.5,
  radialStrength = 0.02,
  flowStrength = 0.08,
  ink = [0.035, 0.038, 0.048],
  line = [0.16, 0.17, 0.2],
  glow = [0.35, 0.62, 0.95],
  maxDpr = MAX_DPR,
  className,
}: SpringLatticeFieldProps) {
  const host = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const passRef = useRef<Pass | null>(null);
  const latticeRef = useRef<Lattice | null>(null);
  const accumulator = useRef(0);
  const prevPointer = useRef<{ x: number; y: number } | null>(null);

  const { width, height } = useResizeObserver(host);
  const reduced = useReducedMotion();
  const visible = useVisibility();
  // Light smoothing only. Heavy smoothing would blunt the velocity signal the
  // flow push is built from, and the lattice would stop reacting to flicks.
  const pointer = useSmoothPointer({ target: host, smoothing: 0.004 });
  const [supported, setSupported] = useState(true);

  const params = useRef({ radius, radialStrength, flowStrength, ink, line, glow });
  params.current = { radius, radialStrength, flowStrength, ink, line, glow };

  const drawRef = useRef<() => void>(() => {});
  drawRef.current = () => {
    const pass = passRef.current;
    const lattice = latticeRef.current;
    if (!pass || !lattice) return;
    const { gl } = pass;
    const p = params.current;

    gl.useProgram(pass.program);
    gl.activeTexture(gl.TEXTURE0);
    gl.bindTexture(gl.TEXTURE_2D, pass.texture);

    if (pass.texCols !== lattice.cols || pass.texRows !== lattice.rows) {
      gl.texImage2D(
        gl.TEXTURE_2D,
        0,
        gl.RGBA8,
        lattice.cols,
        lattice.rows,
        0,
        gl.RGBA,
        gl.UNSIGNED_BYTE,
        lattice.pixels,
      );
      pass.texCols = lattice.cols;
      pass.texRows = lattice.rows;
    } else {
      // texSubImage2D, not texImage2D: re-specifying the texture every frame
      // makes the driver re-validate and often reallocate it, which shows up as
      // a steadily climbing GPU memory graph.
      gl.texSubImage2D(
        gl.TEXTURE_2D,
        0,
        0,
        0,
        lattice.cols,
        lattice.rows,
        gl.RGBA,
        gl.UNSIGNED_BYTE,
        lattice.pixels,
      );
    }

    const uField = uniformLocation(pass, 'u_field');
    if (uField !== null) gl.uniform1i(uField, 0);

    const uRes = uniformLocation(pass, 'u_resolution');
    if (uRes !== null) {
      gl.uniform2f(uRes, gl.drawingBufferWidth, gl.drawingBufferHeight);
    }
    const uGrid = uniformLocation(pass, 'u_grid');
    if (uGrid !== null) gl.uniform2f(uGrid, lattice.cols, lattice.rows);
    const uDisp = uniformLocation(pass, 'u_dispMax');
    if (uDisp !== null) gl.uniform1f(uDisp, DISP_MAX);
    /* Grid density is tied to the lattice row count so the drawn lines land on
       cell boundaries. Decoupling them makes the displacement look like it is
       sliding underneath the grid rather than moving it. */
    const uDensity = uniformLocation(pass, 'u_density');
    if (uDensity !== null) gl.uniform1f(uDensity, lattice.rows);

    setVec3(gl, uniformLocation(pass, 'u_ink'), p.ink);
    setVec3(gl, uniformLocation(pass, 'u_line'), p.line);
    setVec3(gl, uniformLocation(pass, 'u_glow'), p.glow);

    gl.bindVertexArray(pass.vao);
    gl.drawArrays(gl.TRIANGLES, 0, 3);
    gl.bindVertexArray(null);
  };

  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;
    if (!hasWebGL()) {
      setSupported(false);
      return;
    }

    const gl = canvas.getContext('webgl2', {
      antialias: false,
      alpha: false,
      depth: false,
      stencil: false,
      powerPreference: 'high-performance',
    });
    if (!gl) {
      setSupported(false);
      return;
    }

    const pass = createPass(gl);
    if (!pass) {
      loseContext(gl);
      setSupported(false);
      return;
    }
    passRef.current = pass;
    setSupported(true);

    return () => {
      passRef.current = null;
      disposePass(pass);
    };
  }, []);

  // Resize rebuilds the lattice and redraws. Under reduced motion this is the
  // only draw that ever happens, and it shows the field at rest.
  useEffect(() => {
    const canvas = canvasRef.current;
    const pass = passRef.current;
    if (!canvas || !pass || width === 0 || height === 0) return;

    const dpr = pixelRatio(maxDpr);
    const w = Math.max(1, Math.round(width * dpr));
    const h = Math.max(1, Math.round(height * dpr));
    if (canvas.width !== w || canvas.height !== h) {
      canvas.width = w;
      canvas.height = h;
    }
    pass.gl.viewport(0, 0, w, h);

    // Lattice resolution is in CSS pixels, deliberately: the simulation should
    // feel the same on a retina display, not run four times as many cells.
    const cols = Math.min(MAX_CELLS, Math.max(MIN_CELLS, Math.round(width / cellSize)));
    const rows = Math.min(MAX_CELLS, Math.max(MIN_CELLS, Math.round(height / cellSize)));
    const current = latticeRef.current;
    if (!current || current.cols !== cols || current.rows !== rows) {
      latticeRef.current = createLattice(cols, rows);
      encodeLattice(latticeRef.current);
      prevPointer.current = null;
      accumulator.current = 0;
    }

    drawRef.current();
  }, [width, height, cellSize, maxDpr, supported]);

  const running = supported && visible && !reduced && width > 0 && height > 0;

  useRaf((dt) => {
    const lattice = latticeRef.current;
    if (!lattice) return;
    const p = params.current;
    const state = pointer.current;

    const px = state.nx * lattice.cols;
    const py = state.ny * lattice.rows;

    // Velocity from the change in position, in cells/second, then capped.
    let vx = 0;
    let vy = 0;
    const prev = prevPointer.current;
    if (prev && dt > 0) {
      vx = (px - prev.x) / dt;
      vy = (py - prev.y) / dt;
      const speed = Math.sqrt(vx * vx + vy * vy);
      if (speed > MAX_POINTER_SPEED) {
        const k = MAX_POINTER_SPEED / speed;
        vx *= k;
        vy *= k;
      }
    }
    prevPointer.current = { x: px, y: py };

    accumulator.current += dt;
    let steps = 0;
    while (accumulator.current >= STEP && steps < MAX_SUBSTEPS) {
      stepLattice(
        lattice,
        px,
        py,
        vx,
        vy,
        state.active,
        p.radius,
        p.radialStrength,
        p.flowStrength,
      );
      accumulator.current -= STEP;
      steps++;
    }
    // Hit the ceiling: throw the backlog away rather than carrying a debt that
    // can never be paid off, which would leave the simulation permanently
    // saturated and running MAX_SUBSTEPS every frame.
    if (steps === MAX_SUBSTEPS) accumulator.current = 0;

    if (steps > 0) {
      encodeLattice(lattice);
      drawRef.current();
    }
  }, running);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Deletes the VAO, vertex buffer, field texture and program, then `loseContext(gl)`. The typed arrays are dropped with the lattice ref. The rAF subscription, resize observer and pointer listener unsubscribe with their hooks.

**Reduced motion.** No rAF subscription, so the lattice never steps and the pointer never disturbs it. One frame is drawn on mount and on resize showing the field at rest: the full grid, the vignette, no displacement and no glow. The component is a static grid, not a blank panel.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Integrating per frame instead of on a fixed accumulator. The constants above are tuned per 1/60 s; run them per frame and the same component is noticeably stiffer at 60 fps than at 120, and unstable under a frame spike. This is the one place the tuned constants and the frame-rate independence rule collide, and the accumulator is the resolution.
- Carrying the accumulator forward after hitting `MAX_SUBSTEPS`. The debt can never be repaid, so the simulation runs four substeps every frame from then on and quietly costs four times what it should.
- Diffusing in place. Cells read their +x and +y neighbours after those neighbours have already been updated, so the wave propagates faster in one diagonal than the other and visibly drifts toward the lattice origin.
- Setting the field texture to NEAREST. The lattice itself becomes visible as hard blocky steps — at `cellSize` 18 that is a grid of 18 px squares sliding under the drawn grid.
- Calling `texImage2D` every frame instead of `texSubImage2D`. Re-specifying the texture makes the driver re-validate and frequently reallocate it; the symptom is a GPU memory graph that climbs for as long as the page is open.
- Failing to clamp before encoding. Displacement past `DISP_MAX` wraps the unsigned byte, so a cell being pushed hard right suddenly reads as pushed hard left, and the field pops.
- Sizing the lattice in device pixels. A retina display quietly runs four times the cells for identical visual output, and the component drops frames only on the machines its author is least likely to be testing on.
- Heavy pointer smoothing. The flow push is built from the derivative of the pointer position, and over-smoothing flattens that derivative — the lattice stops responding to flicks while still responding to slow drags, which reads as lag rather than as smoothing.
- Leaving the context alive on unmount. Raw GL has no `dispose()`; the VAO, buffer, texture and program are deleted explicitly and `loseContext(gl)` hands the context back, or the page starts blanking its oldest canvases after roughly sixteen mounts.

## Notes

- The simulation could run on the GPU with ping-pong framebuffers, and at this lattice size it would be slower overall: two extra render targets, a readback whenever anything else needs the field state, and float-texture support to feature detect. A few thousand cells on the CPU cost under 0.2 ms and stay inspectable in a debugger.
- Resizing rebuilds the lattice from rest. Interpolating the old state into the new dimensions is possible but the disturbance is gone within a second of a resize anyway.

## Definition of done

Rest the cursor on the field and the grid parts around it by roughly one cell and holds there. Move it and a wave spreads outward through the lines and settles within about a second. Swipe fast and the lines are dragged along the swipe direction, glowing while they move and going dark once they stop. Grid lines stay one pixel wide even where they are most stretched. Throttle the CPU to 6x and the wave still travels at the same speed, just at fewer frames.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Spring To CSS linear()

A spring is a differential equation, and the usual way to run one on the web is a JavaScript loop that integrates it every frame — on the main thread, where a long task or a garbage collection makes it visibly hitch. `linear()` takes a list of output values and interpolates between them, and those values are not clamped to [0, 1], so a dense enough sample of a spring *is* the spring, overshoot included. Solve it once at author time, emit the samples, and the animation runs on the compositor where nothing on the main thread can reach it.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Solves a spring once, samples it into a CSS linear() string, and runs the whole bounce on the compositor.

- Category: primitive
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. The motion is the second-order system `d'' + 2*zeta*w0*d' + w0^2*d = 0` on the *remaining* distance `d`, with `d(0) = 1` and `d'(0) = -velocity`. The natural frequency is `w0 = sqrt(stiffness / mass)` and the damping ratio is `zeta = damping / (2 * sqrt(stiffness * mass))`.
2. Each damping regime has its own closed form. Underdamped (`zeta < 1`) is `exp(-zeta*w0*t) * (cos(wd*t) + b*sin(wd*t))` with `wd = w0*sqrt(1 - zeta^2)` and `b = (zeta*w0 - v0) / wd`. Critically damped (`zeta = 1`) collapses to `exp(-w0*t) * (1 + (w0 - v0)*t)`. Overdamped (`zeta > 1`) is a sum of two real exponentials with roots `-zeta*w0 ± w0*sqrt(zeta^2 - 1)`. Picking the wrong branch is silent until `sqrt(1 - zeta^2)` goes imaginary and every sample is NaN.
3. `bounce` is expressed against the critical damping coefficient `2*sqrt(stiffness*mass)` rather than as an absolute damping value, which is what makes `bounce: 0` mean exactly "no overshoot" at any stiffness. Without that normalisation the same damping number is bouncy at high stiffness and sluggish at low.
4. Duration is not a parameter — it is solved. A 240 Hz scan walks the solution until the spring is both close enough (`|d| < restDelta`) and slow enough (`|d'| < restSpeed`), and the first `t` that satisfies both becomes the duration. Both tests are needed: an underdamped spring crosses the target at full speed on every oscillation, so a distance-only test declares it settled half a bounce in.
5. The solved duration is divided by `resolutionMs` to get a stop count, capped at 200, and the solution is evaluated at each stop. Samples are `1 - d(t)` — progress, not remaining distance — and are deliberately left unclamped, because values above 1 are the overshoot and clamping them is precisely how a spring degrades into an ease-out.
6. The last sample is forced to exactly 1. The scan stopped within `restDelta` of the target, so it would otherwise be ~0.999 and every transition would end with a visible sub-pixel snap as the browser jumps from the final easing output to the real end value.
7. `fallback` is a monotonic `cubic-bezier()` meant to be declared on the line *before* the `linear()` one. An engine that cannot parse `linear()` drops that declaration during parsing and the earlier one survives — the ordinary CSS cascade, with no feature query.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `MAX_STOPS = 200`
  Upper bound on samples. The compositor shows one value per frame, so stops closer together than a frame are bytes with no visible effect — 200 stops across a 1.6s spring is one every 8 ms, already finer than a 120 Hz frame. It also bounds the emitted string: a slow overdamped spring at 10 ms resolution would otherwise run past a thousand stops.
- `resolutionMs = 10`
  Milliseconds between samples. Below ~6 ms the string grows with no visual change even at 165 Hz; past ~20 ms the linear segments between stops become long enough that the interpolation reads as faceted rather than smooth, most visibly around the first peak where curvature is highest.
- `SCAN_STEP = 1 / 240`
  Integration step for the settle scan — four samples per 60 Hz frame. Coarser steps can step straight over the narrow window where an underdamped spring is simultaneously near the target and slow, which sends the duration to `maxDurationMs`.
- `MIN_RATIO = 0.05`
  Floor on the damping ratio. At zeta = 0 the spring is undamped and never satisfies the rest test, so the scan runs to `maxDurationMs` and emits a 200-stop string of a curve that oscillates forever. `bounce` is clamped to `1 - MIN_RATIO` for the same reason.
- `restDelta = 0.005`
  Distance, as a fraction of the total, that counts as arrived. At 0.005 a 400 px move stops 2 px out, under the forced final sample, so the snap is invisible. An order of magnitude tighter roughly doubles the duration of a bouncy spring for motion nobody can see.
- `restSpeed = 0.1`
  Speed, in fractions per second, that counts as stopped. Paired with `restDelta` so a fast pass through the target is not mistaken for arrival.
- `precision = 4`
  Decimal places per sample. Four is sub-pixel on any realistic distance (0.0001 of 2000 px is 0.2 px) and keeps a 200-stop string near 1.4 KB. Full float precision triples the byte count for nothing.
- `maxDurationMs = 10000`
  Hard ceiling so a pathological configuration returns a long easing rather than hanging the scan loop.

## API

```ts
function springToLinear(spring?: { stiffness?: number; damping?: number; mass?: number; bounce?: number; velocity?: number; restDelta?: number; restSpeed?: number }, options?: { resolutionMs?: number; maxDurationMs?: number; precision?: number }): { easing: string; fallback: string; durationMs: number; samples: readonly number[] }
function useSpringEasing(spring?: SpringConfig, options?: LinearEasingOptions): SpringEasing
```

- `stiffness: number` — default `100`
  Restoring force per unit displacement. Higher is faster and tighter.
- `damping: number` — default `10`
  Resistance proportional to velocity. Ignored when `bounce` is given.
- `mass: number` — default `1`
  Inertia. Raising it lowers the natural frequency and lengthens the settle.
- `bounce: number`
  Overshoot 0-1, relative to critical damping. 0 is monotonic, 0.5 is lively. Overrides `damping`.
- `velocity: number` — default `0`
  Initial velocity in fractions of the distance per second, for handing off from a gesture.
- `restDelta: number` — default `0.005`
  Remaining distance, as a fraction, that counts as arrived.
- `restSpeed: number` — default `0.1`
  Speed, in fractions per second, that counts as stopped.
- `resolutionMs: number` — default `10`
  Milliseconds between emitted stops.
- `maxDurationMs: number` — default `10000`
  Ceiling on the solved duration.
- `precision: number` — default `4`
  Decimal places per sample.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * Upper bound on samples. The compositor can only show one value per frame, so
 * stops spaced closer than a frame are bytes with no visible effect: 200 stops
 * across a 1.6s spring is one every 8ms, already finer than a 120Hz frame.
 */
const MAX_STOPS = 200;
/** Integration step for the settle scan. 240Hz — four samples per 60Hz frame. */
const SCAN_STEP = 1 / 240;
/** A damping ratio of 0 never settles; this is the floor. */
const MIN_RATIO = 0.05;

/** Remaining distance and its derivative, at time `t` seconds. */
type Solver = (t: number) => readonly [distance: number, velocity: number];

/**
 * Closed-form solution of `d'' + 2*zeta*w0*d' + w0^2*d = 0` with `d(0) = 1`
 * and `d'(0) = -velocity`, i.e. the *remaining* distance to the target. All
 * three damping regimes have different solutions and picking the wrong branch
 * is silent: an overdamped spring evaluated with the underdamped formula
 * returns NaN the moment `sqrt(1 - zeta^2)` goes imaginary.
 */
function makeSolver(w0: number, zeta: number, v0: number): Solver {
  if (zeta < 1) {
    const wd = w0 * Math.sqrt(1 - zeta * zeta);
    const b = (zeta * w0 - v0) / wd;
    return (t) => {
      const decay = Math.exp(-zeta * w0 * t);
      const cos = Math.cos(wd * t);
      const sin = Math.sin(wd * t);
      const d = decay * (cos + b * sin);
      const dp = decay * (-zeta * w0 * (cos + b * sin) + (-wd * sin + b * wd * cos));
      return [d, dp];
    };
  }

  if (zeta === 1) {
    const a = w0 - v0;
    return (t) => {
      const decay = Math.exp(-w0 * t);
      return [decay * (1 + a * t), decay * (a - w0 * (1 + a * t))];
    };
  }

  const root = w0 * Math.sqrt(zeta * zeta - 1);
  const r1 = -zeta * w0 + root;
  const r2 = -zeta * w0 - root;
  const c1 = (-v0 - r2) / (r1 - r2);
  const c2 = 1 - c1;
  return (t) => {
    const e1 = Math.exp(r1 * t);
    const e2 = Math.exp(r2 * t);
    return [c1 * e1 + c2 * e2, c1 * r1 * e1 + c2 * r2 * e2];
  };
}

export function springToLinear(
  spring: SpringConfig = {},
  options: LinearEasingOptions = {},
): SpringEasing {
  const {
    stiffness = 100,
    mass = 1,
    velocity = 0,
    restDelta = 0.005,
    restSpeed = 0.1,
  } = spring;
  const { resolutionMs = 10, maxDurationMs = 10000, precision = 4 } = options;

  const w0 = Math.sqrt(stiffness / mass);
  // The critical damping coefficient. `bounce` is expressed against it, which
  // is what makes "bounce: 0" mean exactly "no overshoot" for any stiffness.
  const critical = 2 * Math.sqrt(stiffness * mass);
  const damping =
    spring.bounce === undefined
      ? (spring.damping ?? 10)
      : critical * (1 - clamp(spring.bounce, 0, 1 - MIN_RATIO));
  const zeta = Math.max(damping / critical, MIN_RATIO);

  const solve = makeSolver(w0, zeta, velocity);

  // Scan for the first moment the spring is both close enough and slow enough.
  // Distance alone is not sufficient: an underdamped spring passes through the
  // target at full speed on every oscillation, and a distance-only test would
  // declare it settled on the first crossing, half a bounce in.
  const maxSeconds = maxDurationMs / 1000;
  let settled = maxSeconds;
  for (let t = 0; t <= maxSeconds; t += SCAN_STEP) {
    const [d, dp] = solve(t);
    if (Math.abs(d) < restDelta && Math.abs(dp) < restSpeed) {
      settled = t;
      break;
    }
  }
  const durationMs = Math.max(Math.ceil(settled * 1000), 1);

  const stops = clamp(Math.round(durationMs / resolutionMs), 2, MAX_STOPS);
  const factor = 10 ** precision;
  const samples: number[] = [];
  for (let i = 0; i < stops; i++) {
    const t = (i / (stops - 1)) * (durationMs / 1000);
    // Progress, not remaining distance. NOT clamped: values above 1 are the
    // overshoot, and clamping them is exactly how a spring becomes an ease-out.
    samples.push(Math.round((1 - solve(t)[0]) * factor) / factor);
  }
  // The scan stops within `restDelta` of the target, so the final sample is
  // ~0.999. Left alone, every transition ends with a sub-pixel snap as the
  // browser jumps from the last easing output to the real end value.
  samples[stops - 1] = 1;

  return {
    easing: `linear(${samples.join(', ')})`,
    // Declared first so a browser without linear() support keeps it: the
    // unparseable longhand is dropped, the previous declaration survives.
    fallback: CSS_EASING.outQuart,
    durationMs,
    samples,
  };
}

/**
 * `springToLinear` with memoisation and a reduced-motion variant.
 *
 * Reduced motion does not shorten the animation to nothing — it removes the
 * oscillation. The damping ratio is forced to 1 and the initial velocity to 0,
 * which keeps the spring's stiffness and therefore its pace, and produces a
 * monotonic curve that arrives once and stays.
 */
export function useSpringEasing(
  spring: SpringConfig = {},
  options: LinearEasingOptions = {},
): SpringEasing {
  const reduced = useReducedMotion();
  const { stiffness, damping, mass, bounce, velocity, restDelta, restSpeed } = spring;
  const { resolutionMs, maxDurationMs, precision } = options;

  return useMemo(
    () =>
      springToLinear(
        reduced
          ? { stiffness, mass, bounce: 0, velocity: 0, restDelta, restSpeed }
          : { stiffness, damping, mass, bounce, velocity, restDelta, restSpeed },
        { resolutionMs, maxDurationMs, precision },
      ),
    [
      reduced,
      stiffness,
      damping,
      mass,
      bounce,
      velocity,
      restDelta,
      restSpeed,
      resolutionMs,
      maxDurationMs,
      precision,
    ],
  );
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nothing to clean up: `springToLinear` is a pure function and `useSpringEasing` only calls it inside `useMemo`. No timers, listeners, or animation frames are created. The reduced-motion subscription belongs to `useReducedMotion`, which removes its own media-query listener on unmount.

**Reduced motion.** `useSpringEasing` recomputes with `bounce: 0` and `velocity: 0`, forcing the damping ratio to exactly 1. That removes the oscillation — the trigger for vestibular discomfort — while keeping the stiffness and therefore the pace, so the motion stays the same length and simply arrives once instead of settling. It is not shortened to zero: the curve is still a real ease, just monotonic, and the demo's peak readout drops to 100% to show it.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Clamping the samples to [0, 1]. This is the one mistake that destroys the whole technique: the overshoot lives in the values above 1, and a clamped spring is an ease-out with extra bytes. It looks like the maths is wrong when the maths is fine.
- Reading the raw solution as progress. The closed form gives *remaining distance*, which starts at 1 and decays to 0; the easing needs `1 - d`. Emitting `d` directly produces an animation that runs backwards and every reviewer misdiagnoses it as an inverted easing.
- Using one formula for all damping ratios. `sqrt(1 - zeta^2)` is imaginary above zeta = 1, so an overdamped spring evaluated with the underdamped branch yields NaN, and `linear(0, NaN, NaN)` fails to parse — the transition silently reverts to `ease` with nothing in the console.
- Testing only distance for the settle time. An underdamped spring passes exactly through the target on every swing, so the scan stops on the first crossing and the emitted curve is cut off mid-bounce.
- Leaving the final sample at its solved value. It is ~0.999, and the browser jumps from there to the real end value in one frame — a visible tick at the end of every transition that reads as a rendering bug.
- Passing the `linear()` string through a CSS custom property. An unsupported value inside `var()` is invalid at computed-value time, which resolves the property to its *initial* value (`ease`) instead of falling back to the previous declaration. That silently defeats the two-declaration fallback in exactly the browsers that need it.
- Declaring the fallback after `linear()`. Later declarations win, so a supporting browser also uses the cubic-bezier and the spring never appears anywhere.
- Setting a duration by hand. Duration is an output of the spring, not an input; overriding it rescales the curve in time so a stiff spring animates slowly with a stiff shape, which looks wrong without looking obviously wrong.
- Recomputing the easing every render. The scan runs up to 2400 solver evaluations, so an unmemoised call inside a frequently-rendering component is measurable main-thread work to produce a string that never changes.
- Using this for anything interruptible. A `linear()` easing is a fixed curve of fixed length; a spring that must absorb a new target mid-flight, with its current velocity carried over, still needs a real per-frame integrator.

## Notes

- Deterministic and pure, so it is safe to precompute at build time and inline the string into a stylesheet — the runtime cost then drops to zero. `springToLinear` is exported separately from the hook for that reason.
- Works for any animatable property, including ones a JavaScript spring handles badly: `linear()` on a `background-color` transition springs the colour without touching the main thread at all.
- A `linear()` easing applies to Web Animations and CSS animations identically. Passing `easing` as the `easing` option of `element.animate()` gets the same compositor handoff.
- The overshoot means the property leaves the 0-1 range, so a spring on `scale` momentarily exceeds the target scale. Anything clipped by an `overflow: hidden` parent should be sized with that headroom in mind — the demo's peak readout is the exact multiplier.

## Definition of done

Press Run. The three squares cross their tracks and each one visibly passes its end position and settles back — Loose the most, Snap barely. The plotted curve beside each row rises above the dashed 100% line by the amount stated in the readout. Scroll or drag hard during the run and the motion does not hitch, because it is not on the main thread. Read the emitted string: it starts at 0, contains values greater than 1, and ends at exactly 1. Turn reduced motion on and re-run: every curve is monotonic, no square passes its end position, every peak reads 100%, and the durations are still hundreds of milliseconds rather than zero.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Step-End Blinking Caret

A bar caret that blinks the way a terminal cursor does: fully on, then fully off, with nothing in between. The switch is `animation-timing-function: step-end`, which holds each keyframe value until the next one rather than interpolating toward it. The keyframe distribution is deliberately uneven so the rhythm reads as alive rather than as a metronome, and the whole thing is CSS — no JavaScript runs after mount.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A text caret that snaps on and off instead of fading, using step-end timing and an uneven blink rhythm.

- Category: text
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. A single `@keyframes` rule sets `opacity: 1` at 0%, 70% and 100%, and `opacity: 0` at 20% and 50%. With `step-end`, each value is held until the following keyframe is reached, so opacity is only ever exactly 1 or exactly 0.
2. The shorthand `animation: var(--kx-caret-period, 1.05s) step-end infinite kinetic-caret-blink` puts the period in a custom property, so the `period` prop varies the speed through an inline `style` without generating a new class or a new keyframe rule.
3. The bar itself is an `inline-block` span with `background-color: currentColor`, so it inherits the colour of the text it sits in, and `vertical-align: -0.14em` to seat it on the baseline of the surrounding type rather than the box.
4. The `paused` state sets `animation: none; opacity: 1` rather than `animation-play-state: paused` — pausing freezes on whichever frame the clock happened to reach, which is a coin flip between a visible caret and an invisible one.
5. The stylesheet is emitted through React 19's `<style href precedence>` hoisting, so the rule is deduplicated by `href` and a hundred carets on a page produce exactly one rule in the document.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `period = 1.05`
  Seconds per full on-off-on-off cycle. Terminal defaults sit near 1s; below ~0.6s it reads as an error indicator, above ~1.6s the reader stops associating the blink with the text it follows.
- `keyframe stops = 0/20/50/70/100%`
  On 0-20, off 20-50, on 50-70, off 70-100. An even 50/50 square wave reads as a metronome. The long-on / short-off asymmetry is what makes it read as something alive rather than as a timer.
- `width = 2`
  Pixels. 1px disappears at typical body sizes on a low-DPI display; past 3px it stops being a caret and starts being a block cursor, which implies overtype mode.
- `vertical-align = -0.14em`
  Seats the bar on the text baseline. At 0 the caret floats above the descender line and looks like a stray rule; in `em` it tracks the type size, so the same caret is correct at 14px and at 72px.

## API

```ts
function StepEndCaret(props: { width?: number; height?: string; period?: number; paused?: boolean; className?: string }): JSX.Element
```

- `width: number` — default `2`
  Bar width in pixels.
- `height: string` — default `'1em'`
  Any CSS length. `em` keeps it locked to the surrounding type size.
- `period: number` — default `1.05`
  Seconds for one full on-off-on-off cycle.
- `paused: boolean` — default `false`
  Hold the caret solid — what a terminal does while keys are down.
- `className: string`
  Merged onto the bar via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const CARET_CSS = `
@keyframes kinetic-caret-blink {
  0%, 70%, 100% { opacity: 1; }
  20%, 50%      { opacity: 0; }
}
.kinetic-caret {
  display: inline-block;
  background-color: currentColor;
  vertical-align: -0.14em;
  animation: var(--kx-caret-period, 1.05s) step-end infinite kinetic-caret-blink;
}
/* Paused means solid, not frozen. 'animation-play-state: paused' stops on
   whatever frame it happened to be on, which is a 50% chance of an invisible
   caret. Dropping the animation entirely re-exposes the base opacity. */
.kinetic-caret[data-paused='true'] {
  animation: none;
  opacity: 1;
}
@media (prefers-reduced-motion: reduce) {
  .kinetic-caret {
    animation: none;
    opacity: 1;
  }
}
`;

export interface StepEndCaretProps {
  /** Bar width in px. */
  width?: number;
  /** Any CSS length. `em` keeps it locked to the type size around it. */
  height?: string;
  /** Seconds for one on-off-on-off cycle. */
  period?: number;
  /** Hold the caret solid — what a real terminal does while keys are down. */
  paused?: boolean;
  className?: string;
}

export function StepEndCaret({
  width = 2,
  height = '1em',
  period = 1.05,
  paused = false,
  className,
}: StepEndCaretProps) {
  return (
    <>
      <style href="kinetic-step-end-caret" precedence="medium">
        {CARET_CSS}
      </style>
      <span
        aria-hidden
        data-paused={paused ? 'true' : 'false'}
        className={cn('kinetic-caret', className)}
        style={
          {
            width,
            height,
            '--kx-caret-period': `${period}s`,
          } as CSSProperties
        }
      />
    </>
  );
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nothing to clean up. There is no effect, no timer and no listener; unmounting removes the span, and React's stylesheet hoisting handles the shared rule.

**Reduced motion.** A `@media (prefers-reduced-motion: reduce)` block inside the component stylesheet sets `animation: none; opacity: 1`. The caret remains fully visible and correctly positioned — it simply stops blinking. It is never left in the off state.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Leaving the default `ease` timing function. The opacity interpolates and the caret pulses like a glow, which reads as decoration; a cursor must be unambiguously present or absent.
- Using `animation-play-state: paused` for the held state. It stops on an arbitrary frame, so roughly half the time the "solid" caret is invisible and the user thinks the field lost focus.
- A symmetric 50/50 blink. It reads as mechanical timekeeping rather than as a cursor waiting for input.
- Hardcoding the caret colour. `background-color: currentColor` is what lets the same component sit inside inverted, accented or muted text without a variant per context.
- Emitting the keyframes per instance in a styled-component or inline `<style>` without a precedence key. Ten carets means ten identical rule sets the style engine has to resolve.
- Exposing the caret to assistive technology. It is `aria-hidden` — a screen reader announcing a decorative bar between every phrase is noise.

## Notes

- No JavaScript executes after mount: no rAF loop, no timer, no listener, nothing to clean up. The component is a span and a stylesheet.
- Designed to be composed — `asymmetric-typewriter` renders this component and drives its `paused` prop from its own typing state.

## Definition of done

The bar is either fully opaque or fully invisible at every moment — screenshot it repeatedly and no intermediate opacity appears. Set `paused` and it goes solid immediately rather than freezing wherever it was. Render ten carets and inspect the document: one `kinetic-step-end-caret` stylesheet. Enable reduced motion and the caret is present and solid.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Stepped Film Grain

A full-screen transparent grain layer for stacking over hero art, video, or flat colour. The pixels are an ordinary hash, and everything that makes it look like film rather than television snow is in the clock: the noise offset is quantised to twelve changes per second, and the frames in between are not drawn at all. Grain cells are sized in CSS pixels, so the overlay weighs the same on a laptop and on a 3x phone.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A transparent grain overlay whose pattern jumps twelve times a second instead of every frame, so it reads as film.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. A `PlaneGeometry(2, 2)` is written straight to clip space — `gl_Position = vec4(position.xy, 0.0, 1.0)` — so there are no matrices and no camera transform, only a fragment shader over the whole canvas.
2. Each fragment picks a lattice cell with `cell = floor(gl_FragCoord.xy / uPixelRatio / uCellSize) + uOffset`, dividing by the pixel ratio so a cell is a fixed number of CSS pixels rather than of device pixels.
3. `cell = mod(cell, uTile)` wraps the lattice at 170 cells, which keeps the hash argument small enough for float precision and turns the offset into a jump anywhere inside a finite, tiling field.
4. The value is `fract(sin(dot(cell, vec2(12.9898, 78.233))) * 43758.5453)`, shaped into signed grain by `g = (n - 0.5) * uContrast + uLift`. The lift is film base fog: it raises the mean so the layer opens crushed blacks instead of only speckling them.
5. One normal-blended draw carries both directions: the colour is `vec3(step(0.0, g))` — white above the lift, black below — and the alpha is `abs(g) * uOpacity`, with anything under 0.0035 discarded.
6. The rAF callback computes `index = floor(elapsed * stepsPerSecond) % steps` and returns immediately if the index is unchanged, so the GPU sees twelve draws a second regardless of display refresh rate. On a step it reads `uOffset` from a seeded table of integer jumps and renders once.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `stepsPerSecond = 12`
  The filmic/snow dial. Below about 8 the pattern visibly ticks and reads as a stutter; past about 18 the eye fuses the steps into continuous shimmer and it is television snow again. 12 is 24 fps film with each pattern held for two frames.
- `steps = 24`
  Table length. At 12 steps a second this is a 2-second cycle before the sequence repeats — long enough that nothing breathes on a one-second beat, and the whole table is 48 floats.
- `tile = 170`
  Cells before the lattice wraps. Large enough that the repeat is imperceptible in unstructured noise; small enough that `dot(cell, vec2(12.9898, 78.233))` stays around 15 000, where `fract(sin(x) * 43758)` still has usable precision.
- `contrast = 0.24`
  Peak-to-peak swing before opacity, giving a signed range of ±0.12. Past ~0.4 the grain competes with the image it sits on; below ~0.1 it disappears once the browser composites it at 8 bits.
- `lift = 0.095`
  Just under half the contrast, so roughly 80% of samples land above zero. That asymmetry is what makes it read as an emulsion over the image rather than as symmetric static in front of it.
- `opacity = 0.4`
  Peak alpha works out at 0.4 x 0.215 ≈ 0.086. Above ~0.6 the layer stops being texture and starts being a visible veil over type.
- `cellSize = 1 CSS pixel`
  One cell per CSS pixel is the finest grain that is still DPR-invariant. Larger values give coarser, pushed-film grain; smaller values ask for detail below a CSS pixel that the backing store cannot hold.
- `maxDpr = 1`
  A grain cell is a whole CSS pixel, so a 2x backing store draws four device pixels of identical value per cell — four times the fill rate for a bit-identical image. This is the one full-screen shader that should not be rendered at device resolution.
- `ALPHA_EPSILON = 0.0035`
  Just under 1/255. Below it an 8-bit compositor shows nothing, but blending still costs a framebuffer read-modify-write — and on a lifted, low-contrast field a large share of pixels land there.

## API

```ts
function SteppedFilmGrain(props: { opacity?: number; contrast?: number; lift?: number; cellSize?: number; tile?: number; stepsPerSecond?: number; steps?: number; maxDpr?: number; seed?: number | string; className?: string }): JSX.Element
```

- `opacity: number` — default `0.4`
  Overall strength, multiplied onto the grain magnitude.
- `contrast: number` — default `0.24`
  Peak-to-peak swing of the noise before opacity.
- `lift: number` — default `0.095`
  Mean added to the noise — base fog, which biases the layer toward lightening.
- `cellSize: number` — default `1`
  Size of one grain cell in CSS pixels. Clamped to a 0.25 floor.
- `tile: number` — default `170`
  Cells before the lattice repeats. Clamped to a floor of 8.
- `stepsPerSecond: number` — default `12`
  How many times a second the pattern changes. Also the draw rate.
- `steps: number` — default `24`
  Entries in the seeded offset table; the cycle length is steps / stepsPerSecond seconds.
- `maxDpr: number` — default `1`
  Backing-store cap. 1 is deliberate; see the constant.
- `seed: number | string` — default `'stepped-film-grain'`
  Seeds the offset table so the sequence is stable across reloads and matches the server.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function SteppedFilmGrain({
  opacity = 0.4,
  contrast = 0.24,
  lift = 0.095,
  cellSize = 1,
  tile = 170,
  stepsPerSecond = 12,
  steps = 24,
  maxDpr = 1,
  seed = 'stepped-film-grain',
  className,
}: SteppedFilmGrainProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  const { width, height } = useResizeObserver(host);
  const size = useRef({ width, height });
  size.current = { width, height };

  const reduced = useReducedMotion();
  const visible = useVisibility();
  const ready = width > 0 && height > 0;

  const stepCount = Math.max(1, Math.round(steps));

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    if (!hasWebGL()) {
      setUnsupported(true);
      return;
    }

    const renderer = new THREE.WebGLRenderer({
      // Nothing here has a geometric edge, so MSAA would allocate a
      // multisample buffer the size of the canvas and resolve it every draw
      // for no visible difference.
      antialias: false,
      alpha: true,
      depth: false,
      stencil: false,
      powerPreference: 'low-power',
    });
    renderer.setPixelRatio(pixelRatio(maxDpr));
    renderer.setClearAlpha(0);

    const scene = new THREE.Scene();
    // The quad is authored in clip space, so the camera exists only because
    // three's render signature requires one.
    const camera = new THREE.Camera();

    const geometry = new THREE.PlaneGeometry(2, 2);

    const uniforms: Uniforms = {
      uPixelRatio: { value: renderer.getPixelRatio() },
      uOffset: { value: new THREE.Vector2() },
      uCellSize: { value: Math.max(cellSize, 0.25) },
      uTile: { value: Math.max(tile, 8) },
      uContrast: { value: contrast },
      uLift: { value: lift },
      uOpacity: { value: opacity },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: STEPPED_FILM_GRAIN_VERT,
      fragmentShader: STEPPED_FILM_GRAIN_FRAG,
      uniforms,
      transparent: true,
      depthTest: false,
      depthWrite: false,
      // Normal blending, not additive: the shader emits black as well as white
      // and additive could only lighten, which turns grain into haze.
      blending: THREE.NormalBlending,
    });

    const quad = new THREE.Mesh(geometry, material);
    quad.frustumCulled = false;
    scene.add(quad);

    /* The offset table. Seeded, not `Math.random`, so the sequence is identical
       on the server, on the client, and on every reload — and integer, so each
       jump lands exactly on the cell lattice. A non-integer offset resamples
       cell boundaries and the grain appears to slide a fraction of a cell,
       which is the crawl this component exists to avoid. */
    const rng = createRng(seed);
    const wrap = uniforms.uTile.value;
    const offsets: Array<[number, number]> = [];
    for (let i = 0; i < stepCount; i += 1) {
      offsets.push([Math.floor(rng() * wrap), Math.floor(rng() * wrap)]);
    }

    el.appendChild(renderer.domElement);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';

    let lastIndex = -1;

    const resize = (w: number, h: number) => {
      if (w <= 0 || h <= 0) return;
      renderer.setPixelRatio(pixelRatio(maxDpr));
      renderer.setSize(w, h, false);
      // Re-read rather than assume: dragging the window between a retina and a
      // non-retina display changes devicePixelRatio without changing the CSS
      // size, and a stale value rescales every grain cell.
      uniforms.uPixelRatio.value = renderer.getPixelRatio();
      // Resizing a canvas clears its drawing buffer, and this component only
      // draws on a step change — without a redraw here the overlay would be
      // blank until the next step, up to 1/stepsPerSecond later.
      renderer.render(scene, camera);
    };

    const step = (index: number) => {
      if (index === lastIndex) return;
      lastIndex = index;
      const pair = offsets[index] ?? offsets[0];
      if (pair) uniforms.uOffset.value.set(pair[0], pair[1]);
      renderer.render(scene, camera);
    };

    resize(size.current.width, size.current.height);
    stage.current = { resize, step };
    step(0);

    return () => {
      stage.current = null;
      geometry.dispose();
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
  }, [ready, opacity, contrast, lift, cellSize, tile, stepCount, maxDpr, seed]);

  useEffect(() => {
    stage.current?.resize(width, height);
  }, [width, height]);

  useRaf((_dt, elapsed) => {
    // Quantised time, not time. Everything filmic about this component is the
    // fact that this number changes twelve times a second and the draw call
    // is skipped in between.
    const index = Math.floor(elapsed * stepsPerSecond) % stepCount;
    stage.current?.step(index);
  }, ready && visible && !reduced && !unsupported);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nulls the stage ref, disposes the quad geometry and the ShaderMaterial, calls `disposeRenderer` for `dispose` + `forceContextLoss` + a zeroed drawing buffer, then removes the canvas from the DOM. `useRaf` releases its own frame subscription, and there are no listeners of the component's own — sizing comes from the shared ResizeObserver and visibility from the shared document listener.

**Reduced motion.** The component reads `useReducedMotion` itself. No rAF subscription is opened, and the grain is drawn once at table entry 0 — the texture is fully present and correct, it simply never advances. That is the right degradation for grain: it is a surface quality, not a motion, and removing it entirely would change how the artwork beneath it reads.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Advancing the noise every frame. It is the single thing that separates film grain from TV static, and it also makes the effect frame-rate dependent — the same overlay churns twice as fast on a 120 Hz display. Quantising the offset fixes both at once.
- Sliding the offset by a constant per step instead of jumping to table entries. A constant increment makes the whole field crawl in one direction, and the eye locks onto and tracks that direction; uncorrelated jumps have nowhere to track.
- Using a fractional offset. Non-integer values move the lattice off the pixel grid, so cell boundaries resample and the grain shimmers within each step — the artefact the stepping was supposed to remove.
- Declaring `precision mediump float` out of habit. The hash argument reaches ~15 000, which a 16-bit float holds to three digits, so adjacent cells return the same value and the grain becomes flat blocks tens of pixels wide. This shader needs highp.
- Sizing grain in device pixels. `gl_FragCoord` is a device-pixel coordinate, so grain authored without dividing by the pixel ratio is three times finer and effectively invisible on the phone, while looking correct on the machine it was tuned on.
- Rendering the overlay at the device pixel ratio. A cell is one CSS pixel of constant value; a 2x buffer costs four times the fragments and produces the identical image.
- Forgetting that resizing a canvas clears its drawing buffer. A component that only draws on a step change goes blank for up to 1/stepsPerSecond after every resize, which during a window drag is a visible flicker — the resize path redraws explicitly.
- Using additive blending so the grain can only lighten. The result is haze rather than grain; emitting black or white with the magnitude in alpha gets both directions out of one normal-blended draw.

## Notes

- The host is `pointer-events-none` and `aria-hidden`. It is a decorative layer that must never intercept a click on the content underneath it.
- If WebGL is unavailable the component renders an empty box. A missing grain layer is a correct degradation — the content beneath is untouched.
- Stack it as the last child of a relatively-positioned container with `absolute inset-0`. It composites through the browser, so no blend mode is required, though `mix-blend-mode: overlay` is a reasonable variation over photography.

## Definition of done

A fine speckle over the content that visibly holds still for a beat and then changes, roughly twelve times a second — count it by eye and it should read as a flicker, not a fizz. Zoom the browser from 100% to 200% and the grain gets larger with the layout rather than staying pinned to device pixels. Resize the window and the overlay never blanks. With reduced motion the grain is still there and completely static.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Stroke-To-Fill Hover Rows

A list of large type where every row is an outline with a ghost of fill, and the hovered row materialises: the stroke drops to zero width, the fill goes to full `currentColor`, and the row steps 12px to the right while its siblings recede. The row does not light up, it becomes solid. Everything is CSS, so nothing but the compositor runs on hover.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

An index of outlined type where the hovered row fills in solid, drops its stroke, and steps sideways.

- Category: text
- Runtime cost: css
- Dependencies: none beyond React

## How it works

1. Two properties carry the effect, and they are separate on purpose: `-webkit-text-stroke-width` goes 1px to 0, and `-webkit-text-fill-color` goes from a ghost of `currentColor` to `currentColor` itself.
2. `-webkit-text-fill-color` overrides `color` for the glyph interior only, which is what lets the outline stay at `currentColor` while the inside is nearly transparent. Doing this with `color` alone is impossible — `color` is also what `currentColor` resolves to, so fading the fill fades the stroke with it and the row just dims.
3. The ghost is `color-mix(in oklch, currentColor var(--kx-sf-ghost, 16%), transparent)` rather than a literal `rgba`. It inherits the surrounding text colour, so one component is correct on a dark page and a light one, and mixing in oklch keeps the 16% step perceptually even instead of clumping toward black the way sRGB alpha does.
4. The three tunables are custom properties set on the `<ul>` from props (`--kx-sf-stroke`, `--kx-sf-ghost`, `--kx-sf-nudge`), so per-instance configuration needs no extra class and no extra rule.
5. Sibling dimming is scoped to the list's own hover: `.kinetic-sf-list:hover .kinetic-sf-row:not(:hover) { opacity: 0.45 }`. Scoping to the list is what makes the resting state "all rows equal" rather than "all rows dimmed".
6. Every hover rule is duplicated for `:focus-visible`. Each row is a real `<a>` or `<button>` inside an `<li>`, so keyboard traversal produces the same state change — without it a keyboard user tabbing ten identical outlines has no idea where they are.
7. The stylesheet is emitted once through React 19's `<style href precedence>` hoisting, so any number of lists on a page share one rule set.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `STROKE_WIDTH = 1`
  Pixels of outline at rest. At the 28-72px type this component targets, 1px is a hairline that still reads as a complete letterform; 2px starts to close up counters in tighter faces and the row looks bold rather than outlined.
- `GHOST = 16`
  Percent of `currentColor` mixed into the resting fill. At 0 the glyph interiors are fully transparent and the type dissolves into whatever is behind it; past ~30% the resting and hovered states are too close for the transition to register.
- `NUDGE = 12`
  Pixels the hovered row steps right. Enough to be unmistakable next to a static neighbour; past ~24px the row visibly leaves the left margin of the list and the alignment looks broken.
- `transition duration / curve = 380ms cubic-bezier(0.16, 1, 0.3, 1)`
  A strong ease-out. The row arrives quickly and settles, which matches the pointer having already stopped. A symmetric ease at this duration lags the cursor noticeably on a fast pass down a ten-row list.
- `sibling opacity = 0.45`
  Enough separation that the hovered row is unambiguous, while the others stay legible — dimming to 0.2 turns a browsable index into a spotlight and hides the thing the user is scanning for.

## API

```ts
function StrokeToFillRows(props: { items: StrokeToFillItem[]; strokeWidth?: number; ghost?: number; nudge?: number; className?: string; onSelect?: (item: StrokeToFillItem, index: number) => void }): JSX.Element
```

- `items: StrokeToFillItem[]`
  Rows. Each has a `label`, an optional `meta` node for right-hand metadata, and an optional `href`.
- `strokeWidth: number` — default `1`
  Outline thickness in px at rest.
- `ghost: number` — default `16`
  Resting fill as a percentage of `currentColor`.
- `nudge: number` — default `12`
  Pixels the hovered row steps right.
- `className: string`
  Merged onto the `<ul>` via `cn`.
- `onSelect: (item: StrokeToFillItem, index: number) => void`
  Called when a row without an `href` is activated.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const ROWS_CSS = `
.kinetic-sf-title {
  -webkit-text-stroke: var(--kx-sf-stroke, 1px) currentColor;
  -webkit-text-fill-color: color-mix(in oklch, currentColor var(--kx-sf-ghost, 16%), transparent);
  transition:
    -webkit-text-fill-color 380ms cubic-bezier(0.16, 1, 0.3, 1),
    -webkit-text-stroke-width 380ms cubic-bezier(0.16, 1, 0.3, 1),
    transform 380ms cubic-bezier(0.16, 1, 0.3, 1);
  transform: translate3d(0, 0, 0);
}
/* :focus-visible alongside :hover, always. A keyboard user tabbing an index
   of ten rows otherwise sees ten identical outlines and no current position. */
.kinetic-sf-row:hover .kinetic-sf-title,
.kinetic-sf-row:focus-visible .kinetic-sf-title {
  -webkit-text-fill-color: currentColor;
  -webkit-text-stroke-width: 0px;
  transform: translate3d(var(--kx-sf-nudge, 12px), 0, 0);
}
/* Everything that is not the hovered row recedes. Scoped to the list's own
   hover so the resting state is all rows equal, not all rows dimmed. */
.kinetic-sf-list:hover .kinetic-sf-row:not(:hover) {
  opacity: 0.45;
}
.kinetic-sf-row {
  transition: opacity 380ms cubic-bezier(0.16, 1, 0.3, 1);
}
@media (prefers-reduced-motion: reduce) {
  /* The stroke-to-fill swap is a state change, not motion, and it stays. The
     12 px lateral travel is motion, and it goes. */
  .kinetic-sf-row:hover .kinetic-sf-title,
  .kinetic-sf-row:focus-visible .kinetic-sf-title {
    transform: none;
  }
}
`;

export interface StrokeToFillItem {
  label: string;
  /** Right-hand metadata: a year, a category, a count. */
  meta?: ReactNode;
  href?: string;
}

export interface StrokeToFillRowsProps {
  items: StrokeToFillItem[];
  /** Outline thickness in px at rest. */
  strokeWidth?: number;
  /** Resting fill, as a percentage of `currentColor`. */
  ghost?: number;
  /** Pixels the hovered row steps right. */
  nudge?: number;
  className?: string;
  onSelect?: (item: StrokeToFillItem, index: number) => void;
}

const STROKE_WIDTH = 1;
const GHOST = 16;
const NUDGE = 12;

export function StrokeToFillRows({
  items,
  strokeWidth = STROKE_WIDTH,
  ghost = GHOST,
  nudge = NUDGE,
  className,
  onSelect,
}: StrokeToFillRowsProps) {
  return (
    <>
      <style href="kinetic-stroke-to-fill" precedence="medium">
        {ROWS_CSS}
      </style>
      <ul
        className={cn('kinetic-sf-list w-full', className)}
        style={
          {
            '--kx-sf-stroke': `${strokeWidth}px`,
            '--kx-sf-ghost': `${ghost}%`,
            '--kx-sf-nudge': `${nudge}px`,
          } as CSSProperties
        }
      >
        {items.map((item, i) => {
          const inner = (
            <>
              <span className="kinetic-sf-title block text-[clamp(28px,5.5vw,72px)] leading-[1.06] tracking-[-0.03em]">
                {item.label}
              </span>
              {item.meta ? (
                <span className="meta shrink-0 pt-[0.35em]">{item.meta}</span>
              ) : null}
            </>
          );

          return (
            <li key={`${item.label}-${i}`} className="border-b border-line">
              {item.href ? (
                <a
                  href={item.href}
                  className="kinetic-sf-row flex w-full items-start justify-between gap-6 py-[0.35em] text-left outline-none"
                >
                  {inner}
                </a>
              ) : (
                <button
                  type="button"
                  onClick={() => onSelect?.(item, i)}
                  className="kinetic-sf-row flex w-full items-start justify-between gap-6 py-[0.35em] text-left outline-none"
                >
                  {inner}
                </button>
              )}
            </li>
          );
        })}
      </ul>
    </>
  );
}
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nothing to clean up: no effect, no listener, no timer. Unmounting removes the list; React's `<style precedence>` hoisting owns the shared rule set.

**Reduced motion.** The stroke-to-fill swap is a state change, not motion, so it is kept in full — the hovered row still fills solid and its siblings still recede. Only the 12px lateral travel is removed, via `transform: none` in a `prefers-reduced-motion: reduce` block. The rows are never left unreadable.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Trying to build this with `color` alone. Fading the fill fades the stroke with it because `currentColor` resolves to the same value, so the row dims instead of filling.
- Transitioning the `-webkit-text-stroke` shorthand. Shorthands are not independently interpolable here; transition `-webkit-text-stroke-width` explicitly or the stroke snaps off in one frame while the fill glides.
- Hardcoding the resting fill as `rgba(255,255,255,0.16)`. The component is then wrong the moment it lands on a light background, and wrong again in an inverted section of the same page.
- Mixing the ghost in sRGB. The intermediate steps clump toward black, so the resting fill on a mid-tone accent looks muddy rather than faint.
- Dimming siblings without scoping to `.kinetic-sf-list:hover`. Every row is then permanently at 0.45 and the "recede" has nothing to recede from.
- Styling `:hover` and forgetting `:focus-visible`. Keyboard users get ten identical outlines and no indication of the current row, which is a genuine accessibility failure and not just a polish gap.
- Animating `left` or `margin-left` for the nudge. Both trigger layout on every row of a large-type index; `translate3d` stays on the compositor.

## Notes

- No text splitting and no motion library: this is a state change on a whole row, so imposing a splitter or GSAP on the consumer for a CSS-cost effect would be pure overhead.
- `-webkit-text-stroke` is unprefixed-less by history but supported in every current engine including Firefox and Safari. There is no standards-track alternative that composites the same way.
- Rows render as `<a>` when `href` is given and as `<button>` otherwise, so the list is keyboard-traversable either way without a `tabIndex` hack.

## Definition of done

Hover a row: the outline thins to nothing as the glyph interiors fill to full colour, and the row slides 12px right while the others fade back. Tab through with a keyboard and the same state appears on the focused row. Flip the page between light and dark themes and the resting ghost fill is still faintly visible in both, without editing the component. With reduced motion enabled the fill still happens and the row does not move.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Superellipse Text Avoidance

The headline is real DOM on top of an instanced particle field, and the field is pushed out of a 6-norm superellipse fitted to the headline's measured rect. Interior particles are remapped into a band hugging the shape rather than clamped onto it, so the hole has a bright rim instead of a pile-up. The same avoidance function runs a second time at exponent 2 for the damped pointer, because a disc is a superellipse with a lower exponent.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A particle field that flows around the headline, held off by a 6-norm superellipse fitted to the measured text box.

- Category: webgl
- Runtime cost: webgl
- Dependencies: ogl@^1.0.11

## How it works

1. The avoidance region is `pow(pow(|nx|, e) + pow(|ny|, e), 1/e) < 1` in the rect's own normalised space. At e = 2 that is an ellipse, at e = 6 a squircle, at e = 20 effectively a box. Six is the useful one: a circle around a wide headline clears a large empty halo past the ends of the line, and a box has four corner discontinuities that crease the field along straight lines.
2. Interior radii are REMAPPED, not clamped. `mapped = 1 + whip * min(r, 1 + whip) / (1 + whip) + max(r - (1 + whip), 0)` compresses [0, 1 + whip] into [1, 1 + whip] and is the identity beyond it. Clamping instead maps a whole area onto a curve, so every interior particle lands on the outline and the shape is drawn as one infinitely dense line with an empty interior behind it.
3. The displacement is `half * (n / max(r, 1e-3)) * (mapped - r)` — divided by a floor rather than normalized. A particle at the exact centre has no direction and `normalize()` returns NaN there, which propagates into `gl_Position` and drops the whole instance rather than one component. A lattice puts particles exactly on both axes on the first frame, so this case is reached immediately, not never.
4. `pow()` is undefined for a negative base and for zero raised to a non-positive power, and a symmetric field hits both. The norm takes `abs()` first and adds 1e-5, which costs nothing and removes an entire class of driver-dependent black frames.
5. The rect is measured, never passed in. `getBoundingClientRect()` on the text node and on the host produce four uv numbers; a ResizeObserver on the text node plus `document.fonts.ready` keeps them in step through a rewrap, a font swap and a container resize. A hand-tuned rect is wrong on the first webfont load and wrong again on the first narrow viewport.
6. The text rect is deliberately NOT aspect-corrected, because it was measured in element space and has to stay there or it stops agreeing with the letters. The pointer disc IS aspect-corrected, because it is a shape in screen space and an uncorrected one is a visible ellipse on any non-square container. The two live in the same shader and want opposite treatment.
7. Displaced particles brighten and grow slightly, tinted toward a third colour. Without it the field is just a hole and the exponent is invisible; with it the squircle is legible as a rim, which is the only on-screen evidence that the shape is not a box.
8. The scatter is a jittered lattice, then shuffled. Uniform random has clumps and voids at this population, and once the avoidance opens a real hole the accidental voids read as more holes. The shuffle matters because the instanced count is a prefix of the buffers — in lattice order a smaller count would draw only the top rows.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `exponent = 6`
  The p-norm. Below ~4 the shape is round enough that the clear zone bulges past the ends of the line; above ~10 the corners are sharp enough to crease the field visibly, which is the axis-aligned-box failure the superellipse exists to avoid.
- `WHIP_DISC = 0.3`
  Width of the band the interior is compressed into, in normalised units — the whole feel of the effect. Small values whip particles out hard and stack them into a bright outline; past ~0.6 the field bends around from so far away that the text no longer reads as the cause.
- `margin = 0.06`
  Clear ring around the text, in units of container HEIGHT, divided by the aspect ratio for x so the gap is the same number of pixels on all four sides. Adding one uv figure to both halves pads a wide container far more at the ends of the line than above it.
- `pointerRadius / pointerWhip = 0.16 / 0.45`
  The second field, at exponent 2. Softer than the text rect on purpose: the pointer is a passing influence and a hard-edged hole following the cursor competes with the headline it is supposed to frame.
- `smoothing = 0.0008`
  Fraction of the pointer gap still remaining after one second — an ~90ms tail. The pointer hole has a visible edge, unlike a glow, so lag reads as broken rather than as smooth.
- `CELL_JITTER = 0.42`
  Displacement inside a lattice cell, as a fraction of the cell. Zero is a visible grid; past ~0.5 neighbouring cells overlap and the stratification that made the scatter even in the first place is gone.
- `density = 900`
  Particles per megapixel, so the same value reads right in a 320px card and a 2000px hero. Too sparse and the rim is a dotted line rather than a shape.
- `MAX_DPR = 1.5`
  Additive fill is the whole cost and it scales with the square of the ratio. These are soft round dots with no fine detail, so a third sample per axis resolves nothing and costs 78% more fragments.

## API

```ts
function SuperellipseTextAvoidance(props: { children?: ReactNode; density?: number; maxCount?: number; sizeRange?: readonly [number, number]; exponent?: number; margin?: number; whip?: number; pointerRadius?: number; pointerWhip?: number; smoothing?: number; opacity?: number; colorA?: string; colorB?: string; glowColor?: string; background?: string; seed?: number | string; className?: string; textClassName?: string }): JSX.Element
```

- `children: ReactNode`
  The headline. Rendered above the field and measured for the avoidance rect.
- `density: number` — default `900`
  Particles per megapixel of container area.
- `maxCount: number` — default `1600`
  Population ceiling, and the size the buffers are allocated at.
- `sizeRange: readonly [number, number]` — default `[1.4, 4.4]`
  Particle size in CSS pixels, biased toward the small end.
- `exponent: number` — default `6`
  Superellipse exponent. 2 is a circle, 6 a squircle, high values a box.
- `margin: number` — default `0.06`
  Clear ring around the text, in units of container height.
- `whip: number` — default `0.3`
  Width of the band the interior is compressed into.
- `pointerRadius: number` — default `0.16`
  Pointer avoidance radius in container-height units. 0 disables it.
- `pointerWhip: number` — default `0.45`
  Whip band for the pointer disc.
- `smoothing: number` — default `0.0008`
  Fraction of the pointer gap still remaining after one second.
- `opacity: number` — default `0.92`
  Overall alpha multiplier.
- `colorA: string` — default `'#9ec6ff'`
  First tint. Any value ogl's Color accepts.
- `colorB: string` — default `'#eef2fb'`
  Second tint; each particle mixes between the two.
- `glowColor: string` — default `'#ffd9a0'`
  Tint for displaced particles, which is what makes the shape legible.
- `background: string` — default `'#07080d'`
  Opaque clear colour the additive field is composited onto.
- `seed: number | string` — default `'superellipse-text-avoidance'`
  Seeds the lattice jitter, sizes, phases and tints.
- `className: string`
  Merged onto the root container via `cn`.
- `textClassName: string`
  Merged onto the measured text layer.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** Floor on the population. Below this the field reads as a few stray specks. */
const MIN_COUNT = 260;
/**
 * Width of the band interior particles are compressed into, in normalised
 * superellipse units. The catalogue's WHIP_DISC. Small values throw particles
 * out hard and stack them on the outline; large ones bend the field around from
 * a distance and the text stops looking like the cause.
 */
const WHIP_DISC = 0.3;
/** Fraction of the presence gap left after a second. ~200ms in and out. */
const PRESENCE_SMOOTHING = 0.007;
/** Size distribution exponent. Above 1 crowds the population into small sizes. */
const SIZE_BIAS = 1.7;
/** Fill scales with dpr squared, and these are soft dots with no fine detail. */
const MAX_DPR = 1.5;
/** Lattice bounds. Wider than 0..1 so drift never bares the edges. */
const HOME_MIN = -0.05;
const HOME_MAX = 1.05;
/** Jitter as a fraction of a lattice cell. Past ~0.5 cells overlap and clump. */
const CELL_JITTER = 0.42;
/** The reduced-motion still: one frame with the pointer parked off to one side. */
const STILL_ELAPSED = 4.2;
const STILL_POINTER: readonly [number, number] = [0.3, 0.34];

export function SuperellipseTextAvoidance({
  children,
  density = 900,
  maxCount = 1600,
  sizeRange = [1.4, 4.4],
  exponent = 6,
  margin = 0.06,
  whip = WHIP_DISC,
  pointerRadius = 0.16,
  pointerWhip = 0.45,
  smoothing = 0.0008,
  opacity = 0.92,
  colorA = '#9ec6ff',
  colorB = '#eef2fb',
  glowColor = '#ffd9a0',
  background = '#07080d',
  seed = 'superellipse-text-avoidance',
  className,
  textClassName,
}: SuperellipseTextAvoidanceProps) {
  const host = useRef<HTMLDivElement>(null);
  const text = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  const { width, height } = useResizeObserver(host);
  const textSize = useResizeObserver(text);
  const size = useRef({ width, height });
  size.current = { width, height };

  const reduced = useReducedMotion();
  const reducedRef = useRef(reduced);
  reducedRef.current = reduced;
  const visible = useVisibility();
  const { inView } = useInView(host, { rootMargin: '10%' });
  const ready = width > 1 && height > 1;

  const [minSize = 1.4, maxSize = 4.4] = sizeRange;

  /* Raw pointer target in field space, or null until a real move — which is not
     the same as a pointer resting at the bottom-left corner. */
  const target = useRef<{ x: number; y: number } | null>(null);
  const inside = useRef(false);
  const follow = useRef({ x: 0.5, y: 0.5 });
  const presence = useRef(0);

  /* Live numbers the loop reads. Changing one must not rebuild the renderer:
     Chromium drops the OLDEST WebGL context past roughly 16 per process, so a
     rebuild per prop change can blank an unrelated canvas on the same page. */
  const live = useRef({ exponent, margin, whip, pointerRadius, pointerWhip, smoothing, opacity });
  live.current = { exponent, margin, whip, pointerRadius, pointerWhip, smoothing, opacity };

  /**
   * Reads the text box out of the DOM and writes it into `uRect` as uv centre
   * plus padded half-extents. No React state: a measurement that re-renders is
   * a measurement that can re-measure itself in a loop.
   */
  const measure = () => {
    const s = stage.current;
    const hostEl = host.current;
    const textEl = text.current;
    if (!s || !hostEl || !textEl) return;

    const hostBox = hostEl.getBoundingClientRect();
    if (hostBox.width < 1 || hostBox.height < 1) return;
    const textBox = textEl.getBoundingClientRect();

    if (textBox.width < 1 || textBox.height < 1) {
      // No children, or the text has not laid out yet. Presence 0 rather than a
      // zero-size rect, which would be a singularity at the centre of the field.
      s.uniforms.uRectPresence.value = 0;
      return;
    }

    const aspect = hostBox.width / hostBox.height;
    /* The margin is specified in HEIGHT units and divided by the aspect ratio
       for x, so the clear ring is the same number of pixels on all four sides.
       Adding the same uv figure to both halves pads a wide container far more
       at the ends of the line than above and below it. */
    const padX = live.current.margin / Math.max(aspect, 0.0001);
    const padY = live.current.margin;

    s.uniforms.uRect.value[0] = (textBox.left - hostBox.left + textBox.width * 0.5) / hostBox.width;
    // Flipped: field y is up, client y is down.
    s.uniforms.uRect.value[1] =
      1 - (textBox.top - hostBox.top + textBox.height * 0.5) / hostBox.height;
    s.uniforms.uRect.value[2] = textBox.width * 0.5 / hostBox.width + padX;
    s.uniforms.uRect.value[3] = textBox.height * 0.5 / hostBox.height + padY;
    s.uniforms.uRectPresence.value = 1;

    // The live loop picks this up next frame; a paused one has to be told.
    if (reducedRef.current) s.draw(STILL_ELAPSED);
  };

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    if (!hasWebGL()) {
      setUnsupported(true);
      return;
    }

    /* ogl creates its own canvas, and it is appended and removed per effect
       run. Reusing one React-owned canvas breaks under StrictMode: the first
       cleanup force-loses the context, and `getContext` on that element
       afterwards hands back the dead one rather than a fresh context — the
       panel is then permanently blank in development and fine in production. */
    const renderer = new Renderer({
      dpr: pixelRatio(MAX_DPR),
      // Opaque: the pass is additive, and additive onto a transparent canvas
      // would have to brighten the page behind it, which the GPU cannot see.
      alpha: false,
      // Nothing occludes anything, so a depth buffer is memory plus a clear.
      depth: false,
      antialias: false,
      powerPreference: 'low-power',
    });

    const gl = renderer.gl;
    const canvas = gl.canvas;

    const bg = new Color(background);
    gl.clearColor(bg.r, bg.g, bg.b, 1);

    const quad = new Float32Array([-0.5, -0.5, 0.5, -0.5, 0.5, 0.5, -0.5, 0.5]);
    const index = new Uint16Array([0, 1, 2, 0, 2, 3]);

    const total = Math.max(MIN_COUNT, Math.round(maxCount));
    const homes = new Float32Array(total * 2);
    const params = new Float32Array(total * 4);
    const seeds = new Float32Array(total * 4);

    const rng = createRng(seed);

    /* A STRATIFIED scatter, not `rng()` twice. Uniform random has clumps and
       voids at this population, and once the avoidance opens a real hole those
       accidental voids read as more holes — the shape of the field stops being
       legible. A jittered lattice is even everywhere and still looks organic.
       Cells are then SHUFFLED, because the instanced count is a prefix of these
       buffers: in lattice order a smaller count would draw the top rows only. */
    const aspect = Math.max(size.current.width, 1) / Math.max(size.current.height, 1);
    const cols = Math.max(2, Math.round(Math.sqrt(total * aspect)));
    const rows = Math.max(2, Math.ceil(total / cols));
    const cells: Array<[number, number]> = [];
    for (let r = 0; r < rows; r += 1) {
      for (let c = 0; c < cols; c += 1) {
        cells.push([(c + 0.5) / cols, (r + 0.5) / rows]);
      }
    }
    shuffle(rng, cells);

    const spanX = HOME_MAX - HOME_MIN;
    const spanY = HOME_MAX - HOME_MIN;

    for (let i = 0; i < total; i += 1) {
      const cell = cells[i % cells.length] ?? [0.5, 0.5];
      const [cellX = 0.5, cellY = 0.5] = cell;
      homes[i * 2] = HOME_MIN + (cellX + randRange(rng, -CELL_JITTER, CELL_JITTER) / cols) * spanX;
      homes[i * 2 + 1] =
        HOME_MIN + (cellY + randRange(rng, -CELL_JITTER, CELL_JITTER) / rows) * spanY;

      // Biased small: a linear distribution puts a quarter of the population in
      // the largest quarter of the range and the field reads as gravel.
      const sizeT = Math.pow(rng(), SIZE_BIAS);
      params[i * 4] = Math.max(0.5, minSize) + Math.max(maxSize - minSize, 0.25) * sizeT;
      // Drift radius and rate. Small, because this field is a texture the text
      // sits in — a fast one competes with the headline for attention.
      params[i * 4 + 1] = randRange(rng, 0.002, 0.014);
      params[i * 4 + 2] = (rng() < 0.5 ? -1 : 1) * randRange(rng, 0.08, 0.32);
      // Bigger particles are dimmer, so total light stays roughly constant.
      params[i * 4 + 3] = 0.32 + 0.5 * (1 - sizeT);

      seeds[i * 4] = rng() * Math.PI * 2;
      seeds[i * 4 + 1] = randRange(rng, 0.3, 1);
      seeds[i * 4 + 2] = rng();
      seeds[i * 4 + 3] = 0;
    }

    const geometry = new Geometry(gl, {
      index: { data: index },
      position: { size: 2, data: quad },
      aHome: { size: 2, data: homes, instanced: 1 },
      aParams: { size: 4, data: params, instanced: 1 },
      aSeed: { size: 4, data: seeds, instanced: 1 },
    });

    const uniforms: Uniforms = {
      uResolution: { value: [1, 1] },
      uPixelRatio: { value: renderer.dpr },
      uElapsed: { value: 0 },
      uRect: { value: [0.5, 0.5, 0.001, 0.001] },
      uRectPresence: { value: 0 },
      uExponent: { value: clamp(exponent, 2, 16) },
      uWhip: { value: Math.max(whip, 0.02) },
      uPointer: { value: [0.5, 0.5] },
      uPointerPresence: { value: 0 },
      uPointerRadius: { value: Math.max(pointerRadius, 0) },
      uPointerWhip: { value: Math.max(pointerWhip, 0.02) },
      uColorA: { value: new Color(colorA) },
      uColorB: { value: new Color(colorB) },
      uGlowColor: { value: new Color(glowColor) },
      uOpacity: { value: opacity },
    };

    const program = new Program(gl, {
      vertex: SUPERELLIPSE_TEXT_AVOIDANCE_VERT,
      fragment: SUPERELLIPSE_TEXT_AVOIDANCE_FRAG,
      uniforms,
      transparent: true,
      depthTest: false,
      depthWrite: false,
      // ogl culls BACK faces by default and the quad's winding is not
      // guaranteed to face the way the driver expects. A culled particle is not
      // dim — it is absent.
      cullFace: false,
    });
    // Additive, overriding the source-over that `transparent: true` selected.
    // Order independent, so a thousand overlapping instances need no sort.
    program.setBlendFunc(gl.ONE, gl.ONE);

    const mesh = new Mesh(gl, { geometry, program });

    el.insertBefore(canvas, el.firstChild);
    canvas.style.display = 'block';

    /* Listeners on the CANVAS, not the window. A document-level handler
       outlives the renderer it was written for, and the rect it measures is not
       the rect being drawn into — after a scroll the hole sits at an offset
       from the cursor. Passive, because nothing here calls preventDefault and a
       non-passive move handler makes the compositor wait for JS on every event. */
    const onMove = (event: PointerEvent) => {
      const rect = canvas.getBoundingClientRect();
      if (rect.width === 0 || rect.height === 0) return;
      target.current = {
        x: (event.clientX - rect.left) / rect.width,
        y: 1 - (event.clientY - rect.top) / rect.height,
      };
      inside.current = true;
    };
    const onLeave = () => {
      // Position is left where it is. Tweening it back to the centre drags a
      // visible furrow across the field on the way out.
      inside.current = false;
    };

    canvas.addEventListener('pointermove', onMove, { passive: true });
    canvas.addEventListener('pointerleave', onLeave, { passive: true });
    canvas.addEventListener('pointercancel', onLeave, { passive: true });

    const resize = (w: number, h: number) => {
      renderer.setSize(w, h);
      // `setSize` writes literal px into the canvas's inline style, which wins
      // over any class. Re-asserting percentages keeps it fluid between resize
      // notifications.
      canvas.style.width = '100%';
      canvas.style.height = '100%';

      uniforms.uResolution.value = [gl.drawingBufferWidth, gl.drawingBufferHeight];
      uniforms.uPixelRatio.value = renderer.dpr;

      // Population from area, not a fixed number: the same density reads right
      // in a 320px card and a 2000px hero. The buffers already hold `total`
      // particles in shuffled order, so a prefix of them is still spatially
      // even — no rebuild, no reallocation, no new GPU memory.
      const megapixels = (w * h) / 1_000_000;
      const count = clamp(Math.round(megapixels * density), MIN_COUNT, total);
      geometry.setInstancedCount(count);
    };

    const draw = (elapsed: number) => {
      uniforms.uElapsed.value = elapsed;
      renderer.render({ scene: mesh });
    };

    resize(size.current.width, size.current.height);
    stage.current = { renderer, geometry, program, mesh, uniforms, resize, draw };
    measure();
    draw(0);

    /* A webfont swap changes the text box after the first measurement, and
       nothing about a font swap resizes the element's border box on every
       engine — so the ResizeObserver alone is not enough. */
    let cancelled = false;
    if (typeof document !== 'undefined' && 'fonts' in document) {
      void document.fonts.ready.then(() => {
        if (!cancelled) measure();
      });
    }

    return () => {
      cancelled = true;
      stage.current = null;
      canvas.removeEventListener('pointermove', onMove);
      canvas.removeEventListener('pointerleave', onLeave);
      canvas.removeEventListener('pointercancel', onLeave);
      // ogl has no `dispose()`: `remove()` on the geometry deletes its VAOs and
      // every buffer, `remove()` on the program deletes the shaders and the
      // program, and only then is the context worth handing back. Dropping the
      // context is the part that matters — the per-process budget is about
      // sixteen, and exceeding it kills someone else's oldest context.
      geometry.remove();
      program.remove();
      loseContext(gl);
      canvas.width = 0;
      canvas.height = 0;
      canvas.remove();
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, density, maxCount, minSize, maxSize, seed]);

  // Colours go into the live uniforms rather than being effect deps, so
  // recolouring never costs a context.
  useEffect(() => {
    const s = stage.current;
    if (!s) return;
    s.uniforms.uColorA.value.set(colorA);
    s.uniforms.uColorB.value.set(colorB);
    s.uniforms.uGlowColor.value.set(glowColor);
    const bg = new Color(background);
    s.renderer.gl.clearColor(bg.r, bg.g, bg.b, 1);
  }, [colorA, colorB, glowColor, background]);

  // Resize is its own effect: a reflow costs a `setSize`, an instanced-count
  // change and a re-measure, never a buffer rebuild.
  useEffect(() => {
    stage.current?.resize(width, height);
    measure();
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [width, height]);

  // The text box changes on its own too — wrapping to a new line, a font swap,
  // or different children entirely.
  useEffect(() => {
    measure();
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [textSize.width, textSize.height, margin, children]);

  useRaf(
    (dt, elapsed) => {
      const s = stage.current;
      if (!s) return;
      const cfg = live.current;

      const aim = target.current;
      if (aim) {
        follow.current.x = damp(follow.current.x, aim.x, cfg.smoothing, dt);
        follow.current.y = damp(follow.current.y, aim.y, cfg.smoothing, dt);
      }
      presence.current = damp(
        presence.current,
        inside.current && aim !== null ? 1 : 0,
        PRESENCE_SMOOTHING,
        dt,
      );

      const u = s.uniforms;
      // Mutated in place. Assigning a fresh tuple allocates an array a frame and
      // defeats ogl's redundant-uniform cache, which compares by length first
      // and then element by element against the array it kept.
      u.uPointer.value[0] = follow.current.x;
      u.uPointer.value[1] = follow.current.y;
      u.uPointerPresence.value = presence.current;
      u.uPointerRadius.value = Math.max(cfg.pointerRadius, 0);
      u.uPointerWhip.value = Math.max(cfg.pointerWhip, 0.02);
      u.uExponent.value = clamp(cfg.exponent, 2, 16);
      u.uWhip.value = Math.max(cfg.whip, 0.02);
      u.uOpacity.value = cfg.opacity;

      s.draw(elapsed);
    },
    ready && inView && visible && !reduced && !unsupported,
  );

  /* Reduced motion is a composed still, not an empty box: one frame with the
     text rect fully avoided and the pointer parked off to one side, so the
     shape of the field is exactly what a moving version would show. The
     listeners stay attached and their target is never consumed. */
  useEffect(() => {
    const s = stage.current;
    if (!s || !reduced || !ready) return;
    const [px = 0.3, py = 0.34] = STILL_POINTER;
    s.uniforms.uPointer.value[0] = px;
    s.uniforms.uPointer.value[1] = py;
    s.uniforms.uPointerPresence.value = 1;
    s.draw(STILL_ELAPSED);
  }, [reduced, ready, width, height]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the three pointer listeners from the canvas, cancels the pending `document.fonts.ready` callback with a flag, nulls the stage ref so an in-flight frame cannot touch a dead renderer, then `geometry.remove()` (deletes the VAOs and every buffer), `program.remove()` (deletes the shaders and the program), `loseContext(gl)`, zeroes the canvas dimensions and removes it from the DOM. ogl has no `dispose()`, and dropping the context is the part that matters — the per-process budget is about sixteen, and exceeding it kills the oldest, which belongs to someone else.

**Reduced motion.** The loop never starts. One frame is drawn with the text rect fully avoided and the pointer parked off to one side at full presence, so the still shows exactly the shape a moving version produces — the drift is the only thing lost. Re-measuring after a font swap redraws that single frame rather than starting a loop. The listeners stay attached but their target is never consumed.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Using `normalize()` for the push direction. It is NaN at the origin, and NaN in `gl_Position` discards the entire primitive — so the bug looks like missing particles, not like a maths error.
- `pow()` with a negative base or a zero base. Both are undefined in GLSL, both are reached on the axes of a symmetric field, and the result is driver-dependent: fine on the machine it was written on, black on someone else's.
- Clamping interior particles onto the shell instead of remapping their radius. Every particle inside lands exactly on the outline, so the shape is one dense curve with a dead interior behind it — visibly a stencil rather than a field flowing around something.
- Hard-coding the text rect, or deriving it from a character count. It is wrong the moment a webfont swaps, the line rewraps, or the container narrows, and the hole drifts off the words while still looking deliberate.
- Relying on the ResizeObserver alone for the text box. A font swap does not necessarily change the element's border box on every engine, so the measurement has to be repeated after `document.fonts.ready` as well.
- Aspect-correcting the text rect. It was measured in element space; correcting it clears a region visibly narrower than the headline on a wide container, which is worse than not avoiding at all.
- Forgetting to aspect-correct the POINTER disc. Exactly the opposite case — a screen-space shape left uncorrected is an obvious ellipse on anything but a square container.
- Writing pointer events straight into `uPointer`. A high-rate trackpad delivers a staircase, and after a stalled frame it is a jump that drags the hole across the field in one step. The listener records a target; the loop damps toward it.
- Damping with a per-frame constant (`x += (t - x) * 0.1`) instead of `damp(..., dt)`. The follow is visibly tighter at 120Hz than at 60Hz, so the feel is tuned to whichever display it was authored on.
- Scattering with `rng()` twice. The clumps and voids of a uniform random field are indistinguishable from more avoidance holes once the real one exists. A jittered lattice, shuffled so the instanced-count prefix is still spatially even, costs the same.
- Leaving ogl's default BACK-face culling on. The quad winding is not guaranteed to face the way the driver expects, and a culled particle is not dim — it is absent, so the field renders empty on some machines and fine on others.
- Owning the canvas in React while calling `loseContext()` on cleanup. Under `reactStrictMode` the effect runs twice and the second `getContext` on that element returns the dead context: blank in development, fine in production.
- Letting the text layer swallow pointer events. It sits above the canvas, so without `pointer-events: none` the pointer hole disappears whenever the cursor crosses the headline — precisely where the effect is most visible.
- Re-measuring through React state. A measurement that triggers a render can trigger another measurement; the rect is written straight into the uniform instead.

## Notes

- `children` is the headline and is rendered as real DOM above the field, so it is selectable, searchable and styled with ordinary classes. The component only reads its box.
- The text layer is `pointer-events: none` so the canvas underneath keeps receiving moves. Anything interactive belongs outside it.
- The same `avoid()` function serves both fields; the pointer is just exponent 2 with a wider whip. Adding a third avoided region is one more call, not one more code path.
- Blending is additive with an opaque clear colour, so a thousand overlapping instances need no depth sort and the whole field is one draw call. The fragment output is premultiplied because the destination is only ever added to.
- Population is derived from container area and selected with `setInstancedCount` out of buffers allocated once at `maxCount`, so a resize changes the count without touching GPU memory.
- The scatter runs on `createRng(seed)`, never `Math.random()`, so the field is identical on every load and a visual regression is a real regression.

## Definition of done

The headline sits in a clear zone whose shape is a squircle, not a circle and not a rectangle: the gap above and below the line is the same as the gap at its ends, and the corners are rounded without being round. A brighter rim traces that shape. Resize the container until the headline rewraps to two lines — the clear zone re-fits within a frame, with no visible sweep from the old rect. Move the pointer in and a second, softer hole follows it with a short even lag that is identical on a 60Hz and a 120Hz display; the hole stays circular on a wide container and does not disappear when the pointer crosses the headline. No particle sits inside the clear zone and none pile into a single dense outline. Reload twice: the field is identical. With reduced motion the panel is one composed still with the same shape.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Area-Weighted Surface Particles

Turns any object — one primitive or a whole loaded model — into a particle shell whose density is uniform over the surface rather than over the mesh list. One cumulative distribution is built over the world-space area of every triangle in the object and sampled by binary search, so a face a thousand times larger than its neighbour is picked a thousand times more often. The shell then assembles bottom-up on a per-particle window, breathes along its own sampled normals, and is ringed by orbit lines whose radii are measured from the cloud instead of hard-coded.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Any mesh becomes a particle shell of even density, assembling bottom-up, with orbit rings measured off the sampled silhouette.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. Every mesh under the source object is traversed and each triangle is read in WORLD space via `matrixWorld`. `n = (b - a) × (c - a)` gives area as `|n| / 2` and the face normal as `n / |n|` in one operation; the running area total is written into a `Float64Array` cumulative table, one entry per triangle.
2. To place a particle, `rng() * totalArea` is looked up in that table by binary search. This is inverse-transform sampling over area, which is where per-mesh weighting comes from for free — the alternative, `count / meshCount` points per mesh, gives a dense speckle on the small parts and a sparse haze on the large ones, and no tuning fixes it because the error is structural.
3. The point inside the chosen triangle uses barycentric coordinates by reflection: draw `u, v` in the unit square and if `u + v > 1` replace them with `1 - u, 1 - v`, folding the far half back across the diagonal. `p = a + (b - a) * u + (c - a) * v` is then exactly uniform over the triangle.
4. The cloud is centred on its bounding-box centre and divided by its farthest sample, so the shell always has bounding-sphere radius 1. Camera distance follows from the frustum rather than from taste: `d = 1 / sin(min(vFovHalf, atan(tan(vFovHalf) * aspect))) * 1.14` fits the sphere in whichever axis is tighter.
5. Assembly order is the particle's own normalised target height, so `form = smoothstep(order * 0.45, order * 0.45 + 0.55, uForm)` builds the shell bottom-up — the object is constructed rather than faded in. `uForm` is damped toward 1 with `damp(form, 1, 0.05, dt)`, so the build takes about the same two seconds at 60 and at 120 Hz.
6. `eff = uScatter * (1 - form)` collapses the pre-assembly cloud into the arrival: each particle is pushed out along `normalize(aRand.xyz - 0.5 + 0.0001)` by `(0.6 + aRand.x * 2.2)` radii plus a slow per-axis sinusoid, and both fade to nothing exactly as that particle's own window closes.
7. Point size is perspective-corrected in the vertex shader: `uSize * jitter * uSizeScale / max(0.1, -mv.z)`, where `uSizeScale` is `pixelRatio * cameraDistance`. That makes `uSize` a literal CSS-pixel diameter for a particle at the centre of the shell, rather than the tuned constant this term usually is.
8. Orbit rings are measured, not authored: the cloud is cut into `ringCount` horizontal bands, the radii `sqrt(x² + z²)` within each band are sorted, and the 92nd percentile times 1.06 is the ring radius. Bands with fewer than 12 samples are skipped. All rings go into one buffer as `LineSegments`, so the set is one draw call.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `count = 9000`
  Particles, one buffer, one draw call. Enough that the silhouette of a torus knot reads as a solid surface at preview size; the cost is fill rather than vertex count, and doubling it doubles the blended pixel area rather than the detail.
- `size / maxSize = 2.4 / 22 CSS px`
  Diameter at the centre of the shell, and the ceiling after 1/z growth. The clamp is not cosmetic: a particle that drifts close to the near plane would otherwise ask for a point size in the thousands, which drivers answer by silently capping — or by dropping the draw call.
- `size jitter = 0.55 + aRand.w * 1.35`
  A 3.4x spread. With every particle the same size the cloud reads as a halftone screen; much wider and the largest sprites stop looking like members of the same population.
- `STAGGER / WINDOW = 0.45 / 0.55`
  They sum to exactly 1.0, so the last particle to start is also the one that finishes as `uForm` reaches 1 — no dead time at either end of the build. Raising STAGGER past ~0.6 leaves the base fully assembled while the top has not begun, which reads as two separate animations.
- `FORM_SMOOTHING = 0.05`
  Fraction of the assembly gap remaining after one second, which with the stagger gives a build of roughly two seconds. This is a `damp` smoothing value, not a per-frame lerp — the per-frame form of the same curve converges twice as fast at 120 Hz.
- `FORM_EPSILON = 0.9995`
  `damp` is asymptotic and never arrives, but the last stagger window needs `uForm` to reach exactly 1.0 or the topmost particles stay a hair short of their target forever. Past this threshold it snaps.
- `puff = 0.02 of the shell radius`
  Breathing amplitude along the sampled normal. At 2% the surface undulates while staying a surface; past roughly 6% the shell loses its silhouette and reads as a cloud that happens to be shaped like the object.
- `scatter = 0.9`
  Pre-assembly spread in shell radii, giving a cloud extending to about 2.6 radii. Small enough that the unformed state is still recognisably centred on the object; much larger and the particles start their travel off-screen, so the build begins with an empty frame.
- `RING_PERCENTILE = 0.92`
  Which measured radius in a band becomes the ring. The maximum is dragged outward by a single stray sample on a spike; the mean sinks inside the silhouette and the ring cuts through the shell.
- `MIN_BAND_SAMPLES / MIN_RING_RADIUS = 12 / 0.08`
  A band with almost nothing in it is a gap in the model, and a ring there would hang in empty air; a measured radius near zero is a dot rather than a ring. Both are skipped, which is why the ring count is a maximum and not a promise.
- `FIT_PADDING = 1.14`
  Slack between the unit sphere and the frustum. It has to cover the breathing, the ring margin and the fact that a sprite is drawn centred on its vertex, so a particle exactly on the silhouette still needs half its own width of room.
- `TILT = 0.2 rad`
  Static tilt applied on a parent group. Without it the measured rings project to straight lines and read as scan lines rather than orbits; much past 0.4 the top band occludes the shell.
- `RING_SEGMENTS = 128`
  Vertices per ring. Roughly where a hairline circle stops showing flats at 600px wide, and cheap enough that four rings are still 1024 line vertices in a single buffer.

## API

```ts
function SurfaceSampledParticles(props: { source?: () => THREE.Object3D | null; count?: number; size?: number; maxSize?: number; spin?: number; puff?: number; scatter?: number; ringCount?: number; ringOpacity?: number; opacity?: number; colorBase?: string; colorTip?: string; ringColor?: string; fov?: number; seed?: number | string; className?: string }): JSX.Element
```

- `source: () => THREE.Object3D | null`
  Builds the object to sample. Measured on the CPU, never added to the scene, disposed once sampling finishes. Held in a ref, so changing it does not itself trigger a rebuild.
- `count: number` — default `9000`
  Particle count. One buffer, one draw call; cost is linear in fill.
- `size: number` — default `2.4`
  Particle diameter in CSS pixels for a particle at the centre of the shell.
- `maxSize: number` — default `22`
  Ceiling in CSS pixels on the perspective-grown size.
- `spin: number` — default `0.16`
  Turntable speed in radians per second.
- `puff: number` — default `0.02`
  Breathing amplitude along the sampled normal, as a fraction of the shell radius.
- `scatter: number` — default `0.9`
  How far the pre-assembly cloud spreads, in shell radii.
- `ringCount: number` — default `4`
  Horizontal bands to measure orbit rings from. Bands that are too empty are skipped, so this is a maximum. 0 disables the rings.
- `ringOpacity: number` — default `0.3`
  Ring opacity once the shell has assembled; it ramps with the build.
- `opacity: number` — default `0.9`
  Overall alpha multiplier applied in the vertex shader.
- `colorBase: string` — default `'#6b7783'`
  Tint at the base of the shell.
- `colorTip: string` — default `'#ffffff'`
  Tint at the top of the shell.
- `ringColor: string` — default `'#8d9aa6'`
  Ring colour.
- `fov: number` — default `32`
  Vertical field of view in degrees. Camera distance and the perspective size term are both derived from it.
- `seed: number | string` — default `'surface-sampled-particles'`
  Seeds the sampling and the per-particle randoms, so the same shell is produced on the server and on every reload.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * Sample `count` points over the total world-space surface area of everything
 * under `root`, then centre and scale the result so its bounding sphere has
 * radius 1.
 */
function sampleSurface(root: THREE.Object3D, count: number, rng: Rng): Shell | null {
  // World matrices, not local ones: a mesh scaled 10x has 100x the area, and
  // sampling in local space would weight it as though it did not.
  root.updateMatrixWorld(true);

  const meshes: THREE.Mesh[] = [];
  root.traverse((obj) => {
    const mesh = obj as THREE.Mesh;
    if (mesh.isMesh && mesh.geometry) meshes.push(mesh);
  });

  let capacity = 0;
  for (const mesh of meshes) {
    const position = mesh.geometry.getAttribute('position');
    if (!position) continue;
    const index = mesh.geometry.getIndex();
    capacity += Math.floor((index ? index.count : position.count) / 3);
  }
  if (capacity === 0) return null;

  const tri = new Float32Array(capacity * 9);
  const triNormal = new Float32Array(capacity * 3);
  // Float64 for the running total. At tens of thousands of triangles a Float32
  // accumulator loses the smallest ones entirely — they land inside the
  // rounding error of the sum and become unreachable by any sample.
  const cumulative = new Float64Array(capacity);

  const a = new THREE.Vector3();
  const b = new THREE.Vector3();
  const c = new THREE.Vector3();
  const ab = new THREE.Vector3();
  const ac = new THREE.Vector3();
  const n = new THREE.Vector3();

  let triCount = 0;
  let total = 0;

  for (const mesh of meshes) {
    const position = mesh.geometry.getAttribute('position');
    if (!position) continue;
    const index = mesh.geometry.getIndex();
    const faces = Math.floor((index ? index.count : position.count) / 3);

    for (let f = 0; f < faces; f += 1) {
      const i0 = index ? index.getX(f * 3) : f * 3;
      const i1 = index ? index.getX(f * 3 + 1) : f * 3 + 1;
      const i2 = index ? index.getX(f * 3 + 2) : f * 3 + 2;

      a.fromBufferAttribute(position, i0).applyMatrix4(mesh.matrixWorld);
      b.fromBufferAttribute(position, i1).applyMatrix4(mesh.matrixWorld);
      c.fromBufferAttribute(position, i2).applyMatrix4(mesh.matrixWorld);

      ab.subVectors(b, a);
      ac.subVectors(c, a);
      n.crossVectors(ab, ac);
      // Half the cross product's magnitude is the triangle's area, and the
      // cross product's direction is its normal — one operation for both.
      const area = n.length() * 0.5;
      // Degenerate triangles are common in generated and exported geometry.
      // Keeping them would put zero-width steps in the distribution and, worse,
      // normalising a zero-length normal yields NaN.
      if (!(area > 0)) continue;
      n.divideScalar(area * 2);

      const t9 = triCount * 9;
      tri[t9] = a.x;
      tri[t9 + 1] = a.y;
      tri[t9 + 2] = a.z;
      tri[t9 + 3] = ab.x;
      tri[t9 + 4] = ab.y;
      tri[t9 + 5] = ab.z;
      tri[t9 + 6] = ac.x;
      tri[t9 + 7] = ac.y;
      tri[t9 + 8] = ac.z;

      const t3 = triCount * 3;
      triNormal[t3] = n.x;
      triNormal[t3 + 1] = n.y;
      triNormal[t3 + 2] = n.z;

      total += area;
      cumulative[triCount] = total;
      triCount += 1;
    }
  }

  if (triCount === 0 || total <= 0) return null;

  const positions = new Float32Array(count * 3);
  const normals = new Float32Array(count * 3);
  const rands = new Float32Array(count * 4);
  const orders = new Float32Array(count);

  let minX = Infinity;
  let minY = Infinity;
  let minZ = Infinity;
  let maxX = -Infinity;
  let maxY = -Infinity;
  let maxZ = -Infinity;

  for (let i = 0; i < count; i += 1) {
    // Inverse-transform sampling: a uniform draw across the cumulative area
    // picks each triangle in proportion to its own area, which is exactly the
    // per-mesh weighting the naive loop gets wrong.
    const t = lowerBound(cumulative, triCount, rng() * total);
    const t9 = t * 9;
    const t3 = t * 3;

    // Uniform barycentric coordinates by reflection: draw a point in the unit
    // square and fold the far half back across the diagonal. Cheaper than the
    // sqrt form and exactly uniform, where using u and v raw would pile
    // samples into one corner of every triangle.
    let u = rng();
    let v = rng();
    if (u + v > 1) {
      u = 1 - u;
      v = 1 - v;
    }

    const px = (tri[t9] ?? 0) + (tri[t9 + 3] ?? 0) * u + (tri[t9 + 6] ?? 0) * v;
    const py = (tri[t9 + 1] ?? 0) + (tri[t9 + 4] ?? 0) * u + (tri[t9 + 7] ?? 0) * v;
    const pz = (tri[t9 + 2] ?? 0) + (tri[t9 + 5] ?? 0) * u + (tri[t9 + 8] ?? 0) * v;

    positions[i * 3] = px;
    positions[i * 3 + 1] = py;
    positions[i * 3 + 2] = pz;

    normals[i * 3] = triNormal[t3] ?? 0;
    normals[i * 3 + 1] = triNormal[t3 + 1] ?? 0;
    normals[i * 3 + 2] = triNormal[t3 + 2] ?? 1;

    rands[i * 4] = rng();
    rands[i * 4 + 1] = rng();
    rands[i * 4 + 2] = rng();
    rands[i * 4 + 3] = rng();

    if (px < minX) minX = px;
    if (py < minY) minY = py;
    if (pz < minZ) minZ = pz;
    if (px > maxX) maxX = px;
    if (py > maxY) maxY = py;
    if (pz > maxZ) maxZ = pz;
  }

  // Fit to a unit bounding sphere around the box centre. Normalising here is
  // what lets `puff`, `scatter` and the camera distance be authored once and
  // stay correct for a source of any scale — including a model in metres.
  const cx = (minX + maxX) * 0.5;
  const cy = (minY + maxY) * 0.5;
  const cz = (minZ + maxZ) * 0.5;

  let maxDist = 0;
  for (let i = 0; i < count; i += 1) {
    const dx = (positions[i * 3] ?? 0) - cx;
    const dy = (positions[i * 3 + 1] ?? 0) - cy;
    const dz = (positions[i * 3 + 2] ?? 0) - cz;
    const d = Math.sqrt(dx * dx + dy * dy + dz * dz);
    if (d > maxDist) maxDist = d;
  }
  const scale = maxDist > 0 ? SHELL_RADIUS / maxDist : 1;

  let shellMinY = Infinity;
  let shellMaxY = -Infinity;
  for (let i = 0; i < count; i += 1) {
    const x = ((positions[i * 3] ?? 0) - cx) * scale;
    const y = ((positions[i * 3 + 1] ?? 0) - cy) * scale;
    const z = ((positions[i * 3 + 2] ?? 0) - cz) * scale;
    positions[i * 3] = x;
    positions[i * 3 + 1] = y;
    positions[i * 3 + 2] = z;
    if (y < shellMinY) shellMinY = y;
    if (y > shellMaxY) shellMaxY = y;
  }

  // Assembly order is the particle's own target height, so the shell builds
  // bottom-up. Deriving order from the destination rather than from the buffer
  // index is what makes the build read as construction instead of as noise
  // resolving.
  const span = Math.max(1e-6, shellMaxY - shellMinY);
  for (let i = 0; i < count; i += 1) {
    orders[i] = ((positions[i * 3 + 1] ?? 0) - shellMinY) / span;
  }

  return { positions, normals, rands, orders, minY: shellMinY, maxY: shellMaxY };
}

/**
 * Measure the cloud's silhouette radius in `bands` horizontal slices. The ring
 * radii come out of the geometry that was actually sampled, so swapping the
 * source does not need a new set of hand-tuned numbers.
 */
function measureRings(shell: Shell, bands: number, count: number): Ring[] {
  if (bands <= 0) return [];
  const span = shell.maxY - shell.minY;
  if (!(span > 0)) return [];

  const rings: Ring[] = [];
  for (let band = 0; band < bands; band += 1) {
    const y0 = shell.minY + (span * band) / bands;
    const y1 = shell.minY + (span * (band + 1)) / bands;

    const radii: number[] = [];
    for (let i = 0; i < count; i += 1) {
      const y = shell.positions[i * 3 + 1] ?? 0;
      if (y < y0 || y >= y1) continue;
      const x = shell.positions[i * 3] ?? 0;
      const z = shell.positions[i * 3 + 2] ?? 0;
      radii.push(Math.sqrt(x * x + z * z));
    }
    if (radii.length < MIN_BAND_SAMPLES) continue;

    radii.sort((p, q) => p - q);
    const at = Math.min(radii.length - 1, Math.floor(RING_PERCENTILE * (radii.length - 1)));
    const radius = (radii[at] ?? 0) * RING_MARGIN;
    if (radius < MIN_RING_RADIUS) continue;

    rings.push({ y: (y0 + y1) * 0.5, radius });
  }
  return rings;
}

/** All rings in one buffer, so the whole set is one draw call. */
function buildRingGeometry(rings: Ring[]): THREE.BufferGeometry {
  const vertices = new Float32Array(rings.length * RING_SEGMENTS * 2 * 3);
  let at = 0;
  for (const ring of rings) {
    for (let s = 0; s < RING_SEGMENTS; s += 1) {
      const a0 = (s / RING_SEGMENTS) * Math.PI * 2;
      const a1 = ((s + 1) / RING_SEGMENTS) * Math.PI * 2;
      vertices[at] = Math.cos(a0) * ring.radius;
      vertices[at + 1] = ring.y;
      vertices[at + 2] = Math.sin(a0) * ring.radius;
      vertices[at + 3] = Math.cos(a1) * ring.radius;
      vertices[at + 4] = ring.y;
      vertices[at + 5] = Math.sin(a1) * ring.radius;
      at += 6;
    }
  }
  const geometry = new THREE.BufferGeometry();
  geometry.setAttribute('position', new THREE.BufferAttribute(vertices, 3));
  return geometry;
}

export function SurfaceSampledParticles({
  source,
  count = 9000,
  size = 2.4,
  maxSize = 22,
  spin = 0.16,
  puff = 0.02,
  scatter = 0.9,
  ringCount = 4,
  ringOpacity = 0.3,
  opacity = 0.9,
  colorBase = '#6b7783',
  colorTip = '#ffffff',
  ringColor = '#8d9aa6',
  fov = 32,
  seed = 'surface-sampled-particles',
  className,
}: SurfaceSampledParticlesProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  const sourceRef = useRef(source);
  sourceRef.current = source;

  const { width, height } = useResizeObserver(host);
  const box = useRef({ width, height });
  box.current = { width, height };

  const reduced = useReducedMotion();
  const visible = useVisibility();
  const { inView } = useInView(host, { rootMargin: '10%' });
  const ready = width > 0 && height > 0;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    if (!hasWebGL()) {
      setUnsupported(true);
      return;
    }

    // The source object exists only to be measured. It is never added to the
    // scene, so nothing about it is ever uploaded to the GPU, and it is
    // disposed the moment sampling is done.
    const specimen = sourceRef.current?.() ?? buildDefaultSpecimen();
    const rng = createRng(seed);
    const total = Math.max(1, Math.round(count));
    const shell = sampleSurface(specimen, total, rng);
    disposeObject(specimen);
    if (!shell) {
      setUnsupported(true);
      return;
    }

    const renderer = new THREE.WebGLRenderer({ antialias: false, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setClearAlpha(0);
    const dpr = renderer.getPixelRatio();

    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(fov, 1, 0.1, 100);

    // Tilt outside, turntable inside: composing both on one Euler makes the
    // spin axis tilt with the object, which wobbles instead of turning.
    const tilt = new THREE.Group();
    tilt.rotation.x = TILT;
    const turntable = new THREE.Group();
    tilt.add(turntable);
    scene.add(tilt);

    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute('position', new THREE.BufferAttribute(shell.positions, 3));
    geometry.setAttribute('aNormal', new THREE.BufferAttribute(shell.normals, 3));
    geometry.setAttribute('aRand', new THREE.BufferAttribute(shell.rands, 4));
    geometry.setAttribute('aOrder', new THREE.BufferAttribute(shell.orders, 1));

    const uniforms: Uniforms = {
      uElapsed: { value: 0 },
      uForm: { value: 0 },
      uScatter: { value: scatter },
      uPuff: { value: puff },
      uSize: { value: size },
      uMaxSize: { value: maxSize * dpr },
      uSizeScale: { value: dpr },
      uOpacity: { value: opacity },
      uColorBase: { value: new THREE.Color(colorBase) },
      uColorTip: { value: new THREE.Color(colorTip) },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: SURFACE_SAMPLED_PARTICLES_VERT,
      fragmentShader: SURFACE_SAMPLED_PARTICLES_FRAG,
      uniforms,
      transparent: true,
      // No depth at all. Sorting nine thousand points per frame on the CPU is
      // not affordable, and it is not needed: the samples are in random buffer
      // order, so an unsorted alpha blend averages out into even density
      // rather than into visible layers.
      depthTest: false,
      depthWrite: false,
      blending: THREE.NormalBlending,
    });

    const points = new THREE.Points(geometry, material);
    // Displacement happens in the shader, where the frustum culler cannot see
    // it. The bounding sphere three computes from the rest positions is right
    // for the assembled shell and much too small for the scattered one.
    points.frustumCulled = false;
    turntable.add(points);

    const rings = measureRings(shell, Math.max(0, Math.round(ringCount)), total);
    let ringMaterial: THREE.LineBasicMaterial | null = null;
    if (rings.length > 0) {
      ringMaterial = new THREE.LineBasicMaterial({
        color: new THREE.Color(ringColor),
        transparent: true,
        opacity: 0,
        depthTest: false,
        depthWrite: false,
      });
      const ringLines = new THREE.LineSegments(buildRingGeometry(rings), ringMaterial);
      ringLines.frustumCulled = false;
      turntable.add(ringLines);
    }

    el.appendChild(renderer.domElement);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';

    let form = 0;
    let angle = 0;

    const resize = (w: number, h: number) => {
      if (w <= 0 || h <= 0) return;
      renderer.setSize(w, h, false);
      camera.aspect = w / h;

      // Fit the unit sphere in BOTH axes. Vertical fov alone leaves a tall
      // preview cropping the shell; the horizontal half-angle is the binding
      // constraint whenever the container is narrower than it is tall.
      const vHalf = (camera.fov * Math.PI) / 360;
      const hHalf = Math.atan(Math.tan(vHalf) * camera.aspect);
      const distance = (SHELL_RADIUS / Math.sin(Math.min(vHalf, hHalf))) * FIT_PADDING;
      camera.position.set(0, 0, distance);
      camera.far = distance + SHELL_RADIUS * 8;
      camera.updateProjectionMatrix();

      // Camera distance is half of the perspective size term, so it has to be
      // republished whenever the fit changes — otherwise particles keep the
      // pixel size of the previous layout.
      uniforms.uSizeScale.value = renderer.getPixelRatio() * distance;
      uniforms.uMaxSize.value = maxSize * renderer.getPixelRatio();
    };

    const render = () => {
      uniforms.uForm.value = form;
      turntable.rotation.y = angle;
      if (ringMaterial) ringMaterial.opacity = ringOpacity * form;
      renderer.render(scene, camera);
    };

    const step = (dt: number, elapsed: number) => {
      // Frame-rate independent: a per-frame constant would build the shell
      // twice as fast on a 120 Hz display.
      form = form >= FORM_EPSILON ? 1 : damp(form, 1, FORM_SMOOTHING, dt);
      angle += dt * spin;
      uniforms.uElapsed.value = elapsed;
      render();
    };

    const still = () => {
      form = 1;
      angle = STATIC_ANGLE;
      uniforms.uElapsed.value = STATIC_ELAPSED;
      render();
    };

    resize(box.current.width, box.current.height);
    stage.current = { resize, step, still };
    render();

    return () => {
      stage.current = null;
      disposeObject(scene);
      material.dispose();
      ringMaterial?.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
  }, [
    ready,
    count,
    size,
    maxSize,
    spin,
    puff,
    scatter,
    ringCount,
    ringOpacity,
    opacity,
    colorBase,
    colorTip,
    ringColor,
    fov,
    seed,
  ]);

  // Resize is its own effect: a container reflow costs a `setSize` and a
  // camera refit, never a re-sample of the surface.
  useEffect(() => {
    stage.current?.resize(width, height);
    if (reduced) stage.current?.still();
  }, [width, height, reduced]);

  useRaf(
    (dt, elapsed) => stage.current?.step(dt, elapsed),
    ready && inView && visible && !reduced && !unsupported,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The source object is disposed immediately after sampling, before the renderer even exists. On unmount the stage ref is nulled so an in-flight frame cannot draw into a dying context, `disposeObject(scene)` disposes the point geometry, the ring geometry and their materials, the point material and the ring material are disposed explicitly as well, then `disposeRenderer` performs `dispose()` + `forceContextLoss()` + a zeroed drawing buffer — `dispose()` alone leaves the context alive — and the canvas node is removed. `useRaf`, `useInView`, `useVisibility` and `useResizeObserver` release their own subscriptions.

**Reduced motion.** No rAF subscription is opened and one still frame is drawn with `uForm` forced to 1 and the turntable at 0.6 rad — a three-quarter view of the fully assembled shell with its rings at full opacity, not the unformed cloud. The shell, the density, the depth cue from perspective point sizing and the measured rings are all present; the assembly, the breathing and the rotation are what stop. A resize redraws the same still.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Sampling a fixed number of points per mesh. It is the obvious loop and it is wrong: density then tracks the mesh list rather than the surface, so a model whose parts differ in size gets a dense speckle on the small ones and a haze on the large ones. One cumulative table over all triangles of all meshes is the fix, and it is no more code.
- Building the area table in local space. A mesh scaled 10x has 100x the surface area; weighting by untransformed triangles gives that part a hundredth of the density it should have, and the bug only shows on models that use node transforms.
- Accumulating the running area total in a `Float32Array`. At tens of thousands of triangles the smallest ones land inside the rounding error of the sum, their cumulative entries stop increasing, and they become unreachable by any sample — whole thin features silently receive no particles.
- Keeping degenerate triangles. Exported and generated geometry is full of zero-area faces; they contribute zero-width steps to the distribution and, worse, normalising a zero-length cross product yields NaN. One NaN vertex position takes visible neighbours with it on some drivers.
- Using `u` and `v` raw as barycentric weights. Points then pile into one corner of every triangle, and at high triangle counts the cloud acquires a visible directional grain along the tessellation. Reflecting the far half of the unit square across the diagonal costs one comparison and is exactly uniform.
- Leaving `frustumCulled` on. Every displacement happens in the vertex shader, so the bounding sphere three computes from the rest positions is right for the assembled shell and far too small for the scattered one — the whole cloud blinks out during the part of the animation where it is largest.
- Making `gl_PointSize` constant. Point size does not fall off with distance on its own, so a 3D cloud with a fixed size has no depth at all — it looks like a flat stencil of the object. Dividing by view-space depth is the entire perspective cue, and `max(0.1, -mv.z)` is a required guard, not a nicety: a particle crossing the near plane otherwise asks for an infinite size and some drivers drop the draw.
- Caching the perspective size term at construction. Camera distance is derived from the container aspect ratio, so it changes on every reflow; a stale `uSizeScale` leaves particles at the pixel size of the previous layout.
- Depth-testing a translucent point cloud. With `depthWrite` on, nine thousand sprites occlude each other in buffer order and the cloud tears into hard layers; sorting them per frame on the CPU is unaffordable. Because the samples are already in random order, no depth and an unsorted blend average out into even density.
- Hard-coding ring radii for the model you happen to be sampling. They stop matching the moment the source changes, and nothing in the code says why the numbers were what they were. Measuring a percentile of the cloud's own radius per band is the same three lines and survives a new source.
- Adding the source object to the scene so it can be sampled. It never needs to be rendered — it is a CPU-side measuring stick. Leaving it in the graph uploads every one of its triangles to the GPU and draws a solid mesh through the middle of the particles.
- Making the `source` callback an effect dependency. An inline arrow changes identity on every parent render, so the entire surface is re-sampled — tens of thousands of triangles and a full buffer upload — on any unrelated state change upstream. It is held in a ref instead.

## Notes

- The technique is the same one used to scatter particles over a loaded GLB; the built-in specimen exists so the component ships with no asset. It is four primitives with deliberately mismatched areas — a torus knot, a small icosahedral finial, an open cylinder stem and a lathed base — which is precisely the case area weighting exists to handle.
- Pass `source` to sample something else: return the `scene` of a loaded model, or any procedural `Object3D`. It is measured, normalised to a unit bounding sphere and then disposed, so a source authored in metres and one authored in unit space both frame identically.
- Sampling costs one pass over every triangle plus a binary search per particle — a few milliseconds for 9000 particles over 10k triangles — and it happens once per rebuild, never per frame.
- Two draw calls: the whole point cloud, and every measured ring in one `LineSegments` buffer. The rings do not depth-test, so their far halves cross in front of the shell; at hairline width and 0.3 opacity that reads as an orbit diagram rather than as an error.
- The rAF subscription is gated on `useInView` and `useVisibility`, so a scrolled-away or backgrounded instance stops paying for fill. The assembly resumes from wherever it froze rather than restarting.
- three constructs its own canvas, which is appended and removed per effect run. Reusing a React-owned `<canvas ref>` is unsafe here: cleanup calls `forceContextLoss()`, and under React 19 StrictMode the remount would hand the effect back the dead context, leaving the component permanently black.

## Definition of done

On entering view the shell builds from the base upward over about two seconds and holds, then turns slowly. Density is even everywhere: the small finial and the large knot carry the same particles-per-square-millimetre, with no dense speckle on the small parts. Particles nearer the camera are visibly larger than those on the far side, and none of them pop out of existence as the cloud turns. The rings hug the silhouette — they widen where the form widens — and do not cut through the middle of it. Resize the container from wide to narrow: the shell stays fully in frame and particles keep the same apparent size rather than growing or shrinking. With reduced motion a fully assembled three-quarter view renders immediately and holds still.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Text-Target Particle Glyphs

Draws a word once into an offscreen 2D canvas with a font the page has already loaded, collects the inked pixels of that raster, and hands them out as destinations to a drifting particle cloud. The stagger is keyed to each destination's own horizontal position, so the word assembles left to right — it is written rather than faded in — and then dissolves right to left. Destinations are stored in glyph-box units and scaled by one uniform, so a container resize costs two uniform writes rather than a re-raster. Nothing ships but code: no glyph atlas, no texture, no font file.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A particle cloud gathers into a word rasterised from a font already on the page, written left to right, then lets it go.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. The word is measured once at a 100px probe size and then drawn at `1024 * 0.92 * 100 / probeWidth`, capped at 66% of the raster height. `measureText` is linear in font size, so a single measurement gives the exact fit that a binary search would converge to, for any string and any family.
2. One pass over the `getImageData` buffer collects the index of every pixel whose alpha exceeds 120 into an `Int32Array`, and tracks the min and max x and y as it goes. That array is the coverage list; the min/max are the ink box. Rejection sampling — guess a pixel, keep it if it is inked — is the usual approach and is much worse: text covers roughly 5% of its box, so the average particle needs twenty guesses and the worst case is unbounded.
3. A particle picks `pixels[floor(rng() * pixels.length)]`, unpacks it as `x = i % width, y = (i - x) / width`, adds a sub-pixel jitter, and normalises against the INK box rather than the canvas: `u = (x + rng() - minX) / boxW`. The destination is stored as `vec2(u - 0.5, (0.5 - v) * boxH / boxW)` — glyph-box units, with the aspect ratio folded into y.
4. Because the destination carries its own aspect, one `uWordWidth` uniform scales both axes in the vertex shader and the letterforms cannot be stretched. Layout is derived from the camera: `viewH = 2 * 6 * tan(fov/2)`, `viewW = viewH * aspect`, and `wordWidth = min(viewW * 0.86, viewH * 0.72 / glyphAspect)` — the width bound for the usual case, the height bound for a short wide frame.
5. The morph is `form = smoothstep(order * 0.45, order * 0.45 + 0.55, uMorph)` with `order = clamp(aTarget.x + 0.5, 0, 1)`. Order comes from the DESTINATION, not the buffer index: index order dissolves the word into place everywhere at once, destination order writes it left to right, and only the second one reads as language. `pos = mix(home, glyph, form)`.
6. The resting cloud is a seeded uniform scatter in 0..1 per axis, mapped through `uViewSize` to the visible frustum, so it fills whatever the container is. Drift amplitude is `mix(uHomeDrift * viewH, uGlyphDrift * wordWidth, form)`: a loose cloud at rest and a barely-breathing letterform once written, from one interpolated amplitude rather than two motion states that would need cross-fading.
7. Travel bows outward via `sin(form * PI)`, which is zero at both ends and peaks at the halfway point, displacing each particle along its own fixed angle. Without it fourteen thousand points run down fourteen thousand straight lines and the eye reads a lerp; with it the transit reads as a swarm.
8. Point size is perspective-corrected: `uSize * jitter * uSizeScale / max(0.1, -mv.z)` with `uSizeScale = pixelRatio * 6`, the camera's distance to the word plane, which makes `uSize` a literal CSS-pixel diameter for a landed particle. `uSize` is then scaled by `clamp(containerWidth / 880, 0.55, 1.15)`, because the word always spans the same fraction of the frame and its strokes are therefore thinner in CSS pixels on a small card.
9. Left unattended the component runs a cycle: damp toward 1, snap at 0.9995, hold, damp toward 0, hold, repeat. Supplying `progress` overrides the whole state machine and makes the word a scrubbable function of scroll — damped rather than assigned, so a scroll value that jumps between frames does not teleport the letters.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `raster size = 1024 x 320`
  The mask is the only description of the letterforms there is. A stroke narrower than about three pixels samples into a dotted line, and at 1024 across even a ten-character word keeps five or six pixels in its stems. Doubling it quadruples the single `getImageData` pass for detail that fourteen thousand particles cannot resolve.
- `RASTER_FILL / RASTER_CAP = 0.92 / 0.66`
  The text is fitted to 92% of the raster width, or to 66% of its height if that binds first. The width margin absorbs italic overhang and side bearings that `measureText` under-reports; the height cap is what stops a two-letter word from being fitted so large that its ascenders are clipped off the top of the canvas.
- `ALPHA_THRESHOLD = 120`
  Alpha above which a pixel counts as inked. Anti-aliasing puts a one-pixel skirt of low alpha around every stroke; including it thickens the word by two pixels everywhere and rounds off the corners, which is precisely the crispness the raster was for. Much above 160 and hairline serifs stop registering at all.
- `MIN_COVERAGE_PIXELS = 1200`
  Below this the raster is a failure rather than a short word — an unloaded font, an empty string, a canvas with no 2D context. Rendering it anyway crushes every particle onto a handful of pixels, which looks like a bug rather than like text, so the target is rejected and the cloud simply keeps drifting.
- `STAGGER / WINDOW = 0.45 / 0.55`
  They sum to exactly 1.0, so the last letter starts as late as possible and still finishes exactly as `uMorph` reaches 1 — no dead time at either end of the write. Below about 0.25 the word arrives all at once and the left-to-right reading is lost; above 0.6 the first letters sit finished for most of the animation.
- `WRITE_SMOOTHING / DISSOLVE_SMOOTHING = 0.05 / 0.012`
  Fraction of the gap remaining after one second, so roughly a two-second write and a faster dissolve. Asymmetric on purpose: the word has already been read by the time it leaves, and an exit as slow as the entrance makes the cycle feel stalled. Both are `damp` smoothings, not per-frame lerps — the per-frame form of the same curve runs twice as fast at 120 Hz.
- `MORPH_EPSILON = 0.9995`
  `damp` is asymptotic and never arrives, but the rightmost stagger window needs `uMorph` to reach exactly 1.0 or the last letter stays a hair short of its target forever. Past this threshold it snaps, and the same threshold mirrored at 0.0005 ends the dissolve.
- `fill / FILL_HEIGHT = 0.86 / 0.72`
  The word takes 86% of the visible width, or 72% of the visible height if the frame is short and wide. Both bounds are needed: width alone clips a tall word in a letterbox container, height alone leaves a short word floating in a tall one.
- `CAMERA_DISTANCE = 6 world units`
  Fixed, with the word scaled to fit rather than the camera moved. Distance is half of the perspective size term, so moving it would change every particle's pixel size on every reflow; holding it fixed means only `uWordWidth` and `uViewSize` change on resize.
- `REFERENCE_WIDTH clamp = 880px, 0.55x to 1.15x`
  The container width the default `size` was authored at. Since the word always spans the same fraction of the frame, its stroke thickness in CSS pixels is proportional to container width; particles that do not shrink with it fill the counters of the letters solid on a small card. The clamp stops the ramp from vanishing on a thumbnail or bloating on a 4K hero.
- `count = 14000`
  Enough that the strokes of a seven-character word read as continuous marks rather than as a dotted outline. Text needs more than a silhouette does, because the eye is checking letterforms it already knows against a template; the cost is fill, not vertex count.
- `size / maxSize = 2.2 / 18 CSS px`
  Landed diameter before the 0.6x-1.8x jitter, and the ceiling after 1/z growth. The clamp is not cosmetic: a particle drifting near the near plane would otherwise ask for a point size in the thousands, which drivers answer by capping silently or by dropping the draw call.
- `swarm = 0.05 of the word width`
  Peak mid-flight bow. Around 5% the transit looks like particles finding their place; past roughly 15% the cloud detours so far that the word appears to explode before it forms, and below 2% the straight-line lerp shows through.
- `homeDrift / glyphDrift = 0.05 of view height / 0.0016 of word width`
  A thirty-fold difference in amplitude, which is what separates "a cloud" from "a word that is alive". Give the written state more than about 0.005 and the letterforms visibly wobble, which reads as an unstable render rather than as breathing.
- `THICKNESS = 0.02 of the word width`
  Depth spread of the written word. Non-zero so perspective sizing has something to act on and the letters are made of particles at different depths rather than of a flat decal; small enough that the word still reads as typeset on a plane.

## API

```ts
function TextTargetParticleGlyphs(props: { text?: string; fontFamily?: string; fontWeight?: string | number; count?: number; size?: number; maxSize?: number; fill?: number; progress?: number; loop?: boolean; holdWritten?: number; holdScattered?: number; homeSpread?: number; homeDrift?: number; glyphDrift?: number; swarm?: number; opacity?: number; colorCloud?: string; colorGlyph?: string; fov?: number; seed?: number | string; className?: string }): JSX.Element
```

- `text: string` — default `'KINETIC'`
  The word to write. One line — a newline is not laid out.
- `fontFamily: string`
  CSS font family list for the raster. Defaults to the host element's computed family, so the word uses a font the page has already loaded.
- `fontWeight: string | number` — default `700`
  CSS font weight for the raster. Heavier strokes hold more particles and read better at small sizes.
- `count: number` — default `14000`
  Particle count. One buffer, one draw call; cost is linear in fill.
- `size: number` — default `2.2`
  Particle diameter in CSS pixels for a landed particle, before the per-particle jitter and the container-width ramp.
- `maxSize: number` — default `18`
  Ceiling in CSS pixels on the perspective-grown size.
- `fill: number` — default `0.86`
  Fraction of the visible width the written word spans, unless the height bound binds first.
- `progress: number`
  Authoritative morph from 0 (scattered) to 1 (written). Supply it to drive the word from scroll or a timeline; it is held in a ref, so a per-frame value does not rebuild anything.
- `loop: boolean` — default `true`
  Write, hold, dissolve, repeat. Ignored while `progress` is supplied; `false` writes once and keeps the word.
- `holdWritten: number` — default `2.4`
  Seconds the finished word is held before it dissolves.
- `holdScattered: number` — default `1.1`
  Seconds the cloud drifts before the next write.
- `homeSpread: number` — default `1.15`
  Resting cloud size as a multiple of the visible frame. Above 1 so there is no empty margin at the edges.
- `homeDrift: number` — default `0.05`
  Resting drift amplitude, as a fraction of the visible height.
- `glyphDrift: number` — default `0.0016`
  Residual drift once written, as a fraction of the word width. Keeps the letterforms alive without wobbling them.
- `swarm: number` — default `0.05`
  Peak mid-flight bow, as a fraction of the word width. Zero at both ends of the morph.
- `opacity: number` — default `0.95`
  Overall alpha multiplier applied in the vertex shader.
- `colorCloud: string` — default `'#5d6875'`
  Tint of the scattered cloud; particles cross to `colorGlyph` as they land.
- `colorGlyph: string` — default `'#ffffff'`
  Tint of the written word.
- `fov: number` — default `34`
  Vertical field of view in degrees. The visible extent, and therefore the word width, is derived from it.
- `seed: number | string` — default `'text-target-particle-glyphs'`
  Seeds the home scatter, the per-particle randoms and the destination draw, so the same cloud is produced on the server and on every reload.
- `className: string`
  Merged onto the host element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/**
 * Draw `text` into an offscreen canvas with a font already on the page and
 * collect every inked pixel. Returns `null` when the raster is unusable rather
 * than handing back a target that would render as a half-word.
 */
function rasteriseGlyphs(text: string, weight: string | number, family: string): GlyphMask | null {
  const line = text.trim();
  if (!line) return null;

  const canvas = document.createElement('canvas');
  canvas.width = RASTER_WIDTH;
  canvas.height = RASTER_HEIGHT;
  // `willReadFrequently` moves the canvas to a CPU backing store. There is
  // exactly one `getImageData` here, but on a GPU-backed canvas that single
  // read is a pipeline stall of several milliseconds.
  const ctx = canvas.getContext('2d', { willReadFrequently: true });
  if (!ctx) return null;

  const release = () => {
    canvas.width = 0;
    canvas.height = 0;
  };

  // Measure at a probe size and scale: `measureText` is linear in font size, so
  // one measurement gives the exact fit that a search would converge to.
  ctx.font = `${weight} ${PROBE_SIZE}px ${family}`;
  const probe = ctx.measureText(line).width;
  if (!(probe > 0)) {
    release();
    return null;
  }

  const fontSize = Math.min(
    (RASTER_WIDTH * RASTER_FILL * PROBE_SIZE) / probe,
    RASTER_HEIGHT * RASTER_CAP,
  );
  ctx.font = `${weight} ${fontSize}px ${family}`;
  ctx.textAlign = 'center';
  ctx.textBaseline = 'middle';
  ctx.fillStyle = '#ffffff';
  ctx.fillText(line, RASTER_WIDTH / 2, RASTER_HEIGHT / 2);

  const data = ctx.getImageData(0, 0, RASTER_WIDTH, RASTER_HEIGHT).data;

  // Allocate for the worst case and slice down. Growing a plain array to tens
  // of thousands of entries reallocates repeatedly inside the hot pass.
  const scratch = new Int32Array(RASTER_WIDTH * RASTER_HEIGHT);
  let covered = 0;
  let minX = RASTER_WIDTH;
  let minY = RASTER_HEIGHT;
  let maxX = -1;
  let maxY = -1;

  for (let y = 0; y < RASTER_HEIGHT; y += 1) {
    for (let x = 0; x < RASTER_WIDTH; x += 1) {
      const p = y * RASTER_WIDTH + x;
      if ((data[p * 4 + 3] ?? 0) <= ALPHA_THRESHOLD) continue;
      scratch[covered] = p;
      covered += 1;
      if (x < minX) minX = x;
      if (x > maxX) maxX = x;
      if (y < minY) minY = y;
      if (y > maxY) maxY = y;
    }
  }

  release();
  if (covered < MIN_COVERAGE_PIXELS || maxX <= minX || maxY <= minY) return null;

  // The measured ink box, not the canvas box. Ascenders, descenders and side
  // bearings differ per string; fitting to the canvas would leave the word
  // floating off-centre by whatever margin this particular string happens to
  // have.
  return { pixels: scratch.slice(0, covered), width: RASTER_WIDTH, minX, minY, maxX, maxY };
}

/**
 * Draw `count` destinations uniformly from the coverage list, in glyph-box
 * units: x spans -0.5..0.5 and y carries the box's aspect ratio so a single
 * width uniform scales both axes.
 */
function sampleGlyphTargets(mask: GlyphMask, count: number, rng: Rng): Float32Array {
  const targets = new Float32Array(count * 2);
  const boxW = mask.maxX - mask.minX;
  const boxH = mask.maxY - mask.minY;
  const aspect = boxH / boxW;

  for (let i = 0; i < count; i += 1) {
    const at = Math.min(mask.pixels.length - 1, Math.floor(rng() * mask.pixels.length));
    const packed = mask.pixels[at] ?? 0;
    const px = packed % mask.width;
    const py = (packed - px) / mask.width;

    // Sub-pixel jitter. Without it every particle sits on an integer pixel
    // centre and the word shows the raster lattice as soon as the container is
    // wide enough for a pixel to cover more than a particle.
    const u = (px + rng() - mask.minX) / boxW;
    const v = (py + rng() - mask.minY) / boxH;

    targets[i * 2] = u - 0.5;
    targets[i * 2 + 1] = (0.5 - v) * aspect;
  }
  return targets;
}

/** True when the family is not resolvable yet, so the raster must be redone later. */
function fontPending(spec: string): boolean {
  if (typeof document === 'undefined' || !document.fonts) return false;
  try {
    return !document.fonts.check(spec);
  } catch {
    return false;
  }
}

export function TextTargetParticleGlyphs({
  text = 'KINETIC',
  fontFamily,
  fontWeight = 700,
  count = 14000,
  size = 2.2,
  maxSize = 18,
  fill = 0.86,
  progress,
  loop = true,
  holdWritten = 2.4,
  holdScattered = 1.1,
  homeSpread = 1.15,
  homeDrift = 0.05,
  glyphDrift = 0.0016,
  swarm = 0.05,
  opacity = 0.95,
  colorCloud = '#5d6875',
  colorGlyph = '#ffffff',
  fov = 34,
  seed = 'text-target-particle-glyphs',
  className,
}: TextTargetParticleGlyphsProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  const progressRef = useRef(progress);
  progressRef.current = progress;

  const { width, height } = useResizeObserver(host);
  const box = useRef({ width, height });
  box.current = { width, height };

  const reduced = useReducedMotion();
  const visible = useVisibility();
  const { inView } = useInView(host, { rootMargin: '10%' });
  const ready = width > 0 && height > 0;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    if (!hasWebGL()) {
      setUnsupported(true);
      return;
    }

    const total = Math.max(1, Math.round(count));
    // A font already on the page, not one this component ships. The computed
    // family is whatever the host inherits, so the word matches its context.
    const family = fontFamily || window.getComputedStyle(el).fontFamily || 'sans-serif';
    const probeSpec = `${fontWeight} ${PROBE_SIZE}px ${family}`;

    // The renderer owns its canvas and it is appended here, per effect run.
    // Under StrictMode a React-owned `<canvas ref>` survives the double invoke
    // while the context does not, and the second mount is handed a context that
    // cleanup already killed.
    const renderer = new THREE.WebGLRenderer({ antialias: false, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setClearAlpha(0);
    const dpr = renderer.getPixelRatio();

    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(fov, 1, 0.1, CAMERA_DISTANCE * 4);
    camera.position.z = CAMERA_DISTANCE;

    const rng = createRng(seed);
    const home = new Float32Array(total * 3);
    const rands = new Float32Array(total * 4);
    for (let i = 0; i < total; i += 1) {
      home[i * 3] = rng();
      home[i * 3 + 1] = rng();
      home[i * 3 + 2] = rng();
      rands[i * 4] = rng();
      rands[i * 4 + 1] = rng();
      rands[i * 4 + 2] = rng();
      rands[i * 4 + 3] = rng();
    }

    const mask = rasteriseGlyphs(text, fontWeight, family);
    let glyphAspect = mask ? (mask.maxY - mask.minY) / (mask.maxX - mask.minX) : 1;
    let hasTarget = mask !== null;

    // One destination buffer for the life of the effect. The font-load reraster
    // writes through it in place rather than allocating a second one.
    const targetData = new Float32Array(total * 2);
    if (mask) targetData.set(sampleGlyphTargets(mask, total, createRng(seed)));
    const targetAttr = new THREE.BufferAttribute(targetData, 2);

    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute('position', new THREE.BufferAttribute(home, 3));
    geometry.setAttribute('aTarget', targetAttr);
    geometry.setAttribute('aRand', new THREE.BufferAttribute(rands, 4));

    const uniforms: Uniforms = {
      uElapsed: { value: 0 },
      uMorph: { value: 0 },
      uViewSize: { value: new THREE.Vector2(1, 1) },
      uHomeDepth: { value: 1 },
      uWordWidth: { value: 1 },
      uThickness: { value: THICKNESS },
      uHomeDrift: { value: homeDrift },
      uGlyphDrift: { value: glyphDrift },
      uSwarm: { value: swarm },
      uSize: { value: size },
      uMaxSize: { value: maxSize * dpr },
      uSizeScale: { value: dpr * CAMERA_DISTANCE },
      uOpacity: { value: opacity },
      uColorCloud: { value: new THREE.Color(colorCloud) },
      uColorGlyph: { value: new THREE.Color(colorGlyph) },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: TEXT_TARGET_PARTICLE_GLYPHS_VERT,
      fragmentShader: TEXT_TARGET_PARTICLE_GLYPHS_FRAG,
      uniforms,
      transparent: true,
      // No depth at all. Sorting fourteen thousand points per frame on the CPU
      // is not affordable, and it is not needed: the coverage list is drawn
      // from at random, so buffer order is uncorrelated with depth and the
      // unsorted blend averages into even density rather than into layers.
      depthTest: false,
      depthWrite: false,
      blending: THREE.NormalBlending,
    });

    const points = new THREE.Points(geometry, material);
    // Every position in this component is computed in the vertex shader, where
    // the frustum culler cannot see it. The bounding sphere three derives from
    // the raw attribute — a unit cube of 0..1 values — has nothing to do with
    // where the particles end up, and the whole cloud vanishes at some angles.
    points.frustumCulled = false;
    scene.add(points);

    el.appendChild(renderer.domElement);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';

    let morph = 0;
    let goal = 1;
    let hold = 0;

    const fit = (w: number) => {
      // Visible extent of the frame at the word's depth. Everything the shader
      // scales by comes from here, so the layout is derived from the camera
      // rather than guessed in world units and re-guessed per breakpoint.
      const vHalf = (camera.fov * Math.PI) / 360;
      const viewH = 2 * CAMERA_DISTANCE * Math.tan(vHalf);
      const viewW = viewH * camera.aspect;

      // Bound the word on both axes: width for the usual case, height for a
      // short wide frame where a tall word would otherwise run off the top.
      const wordWidth = Math.min(viewW * fill, (viewH * FILL_HEIGHT) / Math.max(0.05, glyphAspect));

      uniforms.uViewSize.value.set(viewW * homeSpread, viewH * homeSpread);
      uniforms.uHomeDepth.value = viewH * HOME_DEPTH;
      uniforms.uWordWidth.value = wordWidth;
      uniforms.uThickness.value = wordWidth * THICKNESS;

      const ratio = renderer.getPixelRatio();
      uniforms.uSizeScale.value = ratio * CAMERA_DISTANCE;
      uniforms.uMaxSize.value = maxSize * ratio;
      uniforms.uSize.value = size * clamp(w / REFERENCE_WIDTH, MIN_SIZE_SCALE, MAX_SIZE_SCALE);
    };

    const resize = (w: number, h: number) => {
      if (w <= 0 || h <= 0) return;
      renderer.setSize(w, h, false);
      camera.aspect = w / h;
      camera.updateProjectionMatrix();
      fit(w);
    };

    const render = () => {
      uniforms.uMorph.value = morph;
      renderer.render(scene, camera);
    };

    const step = (dt: number, elapsed: number) => {
      const scrub = progressRef.current;
      if (!hasTarget) {
        // No usable raster: the cloud drifts and nothing is ever written. Half a
        // word is worse than no word.
        morph = 0;
      } else if (scrub !== undefined) {
        // Damped rather than assigned, so a scroll value that jumps a hundred
        // pixels between frames does not teleport the letters.
        morph = damp(morph, clamp(scrub, 0, 1), SCRUB_SMOOTHING, dt);
      } else if (hold > 0) {
        hold -= dt;
      } else {
        morph = damp(morph, goal, goal === 1 ? WRITE_SMOOTHING : DISSOLVE_SMOOTHING, dt);
        if (goal === 1 && morph >= MORPH_EPSILON) {
          morph = 1;
          if (loop) {
            hold = holdWritten;
            goal = 0;
          }
        } else if (goal === 0 && morph <= 1 - MORPH_EPSILON) {
          morph = 0;
          hold = holdScattered;
          goal = 1;
        }
      }
      uniforms.uElapsed.value = elapsed;
      render();
    };

    const still = () => {
      morph = hasTarget ? STATIC_MORPH : 0;
      uniforms.uElapsed.value = STATIC_ELAPSED;
      render();
    };

    resize(box.current.width, box.current.height);
    stage.current = { resize, step, still };
    render();

    // A webfont that is still loading measures and rasters as the fallback
    // family, so the particles would land on the wrong letterforms and stay
    // there. Redo the raster once the page's fonts settle, reusing the seed so
    // the cloud does not reshuffle — only the destinations change.
    let live = true;
    if (fontPending(probeSpec)) {
      document.fonts.ready
        .then(() => {
          if (!live) return;
          const next = rasteriseGlyphs(text, fontWeight, family);
          if (!next) return;
          hasTarget = true;
          glyphAspect = (next.maxY - next.minY) / (next.maxX - next.minX);
          targetData.set(sampleGlyphTargets(next, total, createRng(seed)));
          targetAttr.needsUpdate = true;
          fit(box.current.width);
          render();
        })
        .catch(() => undefined);
    }

    return () => {
      live = false;
      stage.current = null;
      disposeObject(scene);
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
  }, [
    ready,
    text,
    fontFamily,
    fontWeight,
    count,
    size,
    maxSize,
    fill,
    loop,
    holdWritten,
    holdScattered,
    homeSpread,
    homeDrift,
    glyphDrift,
    swarm,
    opacity,
    colorCloud,
    colorGlyph,
    fov,
    seed,
  ]);

  // Resize is its own effect: a container reflow costs a `setSize` and a refit,
  // never a re-raster of the text or a re-upload of the destinations.
  useEffect(() => {
    stage.current?.resize(width, height);
    if (reduced) stage.current?.still();
  }, [width, height, reduced]);

  useRaf(
    (dt, elapsed) => stage.current?.step(dt, elapsed),
    ready && inView && visible && !reduced && !unsupported,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The offscreen 2D canvas has its width and height zeroed as soon as the coverage pass is done, releasing the backing store before the WebGL context is even created. A `live` flag is cleared on unmount so a `document.fonts.ready` promise that resolves after teardown cannot write into a disposed attribute. The stage ref is nulled so an in-flight frame cannot draw into a dying context, `disposeObject(scene)` disposes the point geometry and its attributes, the material is disposed explicitly as well, then `disposeRenderer` performs `dispose()` + `forceContextLoss()` + a zeroed drawing buffer — `dispose()` alone leaves the context alive — and the canvas node is removed. `useRaf`, `useInView`, `useVisibility` and `useResizeObserver` release their own subscriptions.

**Reduced motion.** No rAF subscription is opened and one still frame is drawn with `uMorph` forced to 1 and `uElapsed` at 0 — the word fully written and completely still, not the scattered cloud. The typography, the particle grain, the depth cue from perspective point sizing and the colour of the written state are all present; the writing, the drift and the dissolve cycle are what stop. A resize redraws the same still. If the raster was rejected there is nothing to write, so the still shows the motionless cloud instead.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Rejection-sampling the raster. Guessing a pixel and keeping it if it is inked is the first idea and it scales badly: glyph coverage is around 5% of the box, so the expected cost is twenty draws per particle and the worst case has no bound — a long word in a light weight can spin for a noticeable fraction of a second. One pass into a coverage list is O(pixels) once and O(1) per particle.
- Rasterising before the webfont has loaded. `measureText` and `fillText` silently fall back to another family, so the particles land on the wrong letterforms and stay there for the life of the page — and it only reproduces on a cold cache, which is why it ships. Check `document.fonts.check` and redo the raster on `document.fonts.ready`.
- Normalising destinations against the canvas box instead of the measured ink box. Ascenders, descenders and side bearings differ per string, so the word ends up floating off-centre by whatever margin that particular string happens to have, and the offset changes when the copy changes.
- Storing destinations in world units. They then depend on the camera, so every container resize means re-rasterising the text, re-sampling every particle and re-uploading the buffer — during a drag-resize, once per frame. Normalised units plus one scale uniform make the same resize two uniform writes.
- Scaling x and y by separate uniforms. It is the natural way to write it and it stretches the letterforms at one container width and squashes them at another. Folding the ink box aspect into the stored y and scaling both axes by a single width makes the distortion impossible to introduce.
- Ordering the stagger by buffer index. The word then resolves out of noise everywhere at once, which is a cross-fade with extra steps. Ordering by the destination's own x costs one `clamp` in the shader and turns the same animation into writing.
- Landing every particle on an integer pixel centre. Without sub-pixel jitter the raster lattice is visible as soon as the container is wide enough for one mask pixel to cover more than one particle, and the word acquires a faint corduroy texture.
- Rendering whatever the raster produced. An empty string, a font that never loaded, a zero-size canvas: all of them return a nearly empty mask, and mapping fourteen thousand particles onto forty pixels looks like a crash. Reject the target below a coverage floor and leave the cloud drifting instead.
- Leaving `frustumCulled` on. Every position in this component is computed in the vertex shader, so the bounding sphere three derives from the attribute — a unit cube of 0..1 values — has nothing to do with where the particles are, and the whole cloud vanishes at some container aspect ratios.
- Making `gl_PointSize` constant. Point size does not fall off with distance on its own, so the cloud has no depth cue at all and the word looks like a flat stencil. Dividing by view-space depth is the whole effect, and `max(0.1, -mv.z)` is a required guard, not a nicety.
- Depth-testing a translucent point cloud. With `depthWrite` on, fourteen thousand sprites occlude each other in buffer order and the strokes tear into hard layers; sorting per frame on the CPU is unaffordable. Because the coverage list is drawn from at random, buffer order is uncorrelated with depth and an unsorted blend averages into even density.
- Passing a scroll-driven `progress` as an effect dependency. The value changes every frame, so the text would be re-rasterised and every buffer rebuilt sixty times a second. It is held in a ref and read inside the frame callback.
- Calling `getImageData` on a GPU-backed canvas. There is exactly one read here, but without `willReadFrequently` that single read stalls the pipeline for several milliseconds during mount, on the same frame as the WebGL context creation.

## Notes

- The word is rasterised from a font that is already on the page: `fontFamily` defaults to the host element's computed family, so the particles adopt whatever the surrounding type is. No glyph atlas, texture or font file is shipped with the component, and nothing under `registry/` is a binary.
- One line only. A newline is not laid out — multi-line text needs one `fillText` per line, with the coverage pass and the ink box spanning all of them.
- The raster runs once per rebuild, plus once more if the font was still loading. It is a `fillText`, one `getImageData` over 327,680 pixels and one sampling loop — low single-digit milliseconds — and the canvas has its width and height zeroed straight afterwards to release the backing store.
- The font-load reraster reuses the same seed, so the cloud does not reshuffle when the real family arrives: only the destinations change, and any particle already in flight simply continues to a slightly different address.
- Supply `progress` to drive the word from scroll, a timeline or an audio envelope; leave it out and the component writes, holds, dissolves and rewrites on its own. `loop: false` writes once and keeps the word.
- One draw call and one buffer set for the whole effect. The cost is fill: fourteen thousand blended sprites, heaviest at the moment the word is written and its particles overlap inside the strokes.
- three constructs its own canvas, which is appended and removed per effect run. Reusing a React-owned `<canvas ref>` is unsafe here: cleanup calls `forceContextLoss()`, and under React 19 StrictMode the remount would hand the effect back the dead context, leaving the component permanently black.
- The rAF subscription is gated on `useInView` and `useVisibility`, so a scrolled-away or backgrounded instance stops paying for fill and resumes its cycle from wherever it froze.

## Definition of done

On entering view the cloud gathers into the word from left to right over about two seconds — watch the first letter finish while the last is still travelling — holds it, then dissolves right to left and repeats. The letterforms are legible and match the page's own font, with no gaps in the stems and no visible pixel lattice inside a stroke. Particles nearer the camera are larger, and none of them pop out of existence at any container aspect ratio. Resize from wide to narrow: the word stays fully inside the frame, keeps its proportions rather than stretching, and the particles get smaller with it instead of filling the counters solid. Hard-reload with the cache disabled on a page using a webfont: the word must end up in the real face, not the fallback. Set `text=""` and the cloud keeps drifting rather than collapsing into a blob. With reduced motion the finished word renders immediately and holds still.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Throttled Scrub To State

The bridge between a continuous scroll signal and discrete React state. A scrubbed ScrollTrigger calls back on every frame the scroll position moves; this component gates those ticks on elapsed time, on distance travelled, and on the animation frame, so the tree below it renders a few times per scroll instead of a hundred. The boundary frames always get through, which is what stops a fast flick from leaving the state stranded at 0.93.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A scrubbed trigger fires 120x a second; a time, distance and frame gate turns that into a handful of React renders.

- Category: scroll
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. A single `ScrollTrigger.create` with `scrub` runs `onUpdate`, which increments a tick counter in a ref and then decides whether that tick is worth a React render. Refs are used for everything except the committed state, because a ref write does not render.
2. Gate 1 is time: `performance.now() - lastAt < interval` returns early. A monotonic clock rather than `Date.now()`, so a system clock correction cannot produce a negative elapsed time and latch the gate shut.
3. Gate 2 is distance: `Math.abs(p - lastProgress) < minDelta` returns early. A slow drag passes the time gate continuously while moving a fraction of a percent, and that is a render for a change no one can see.
4. Gate 3 is the frame: the passing value is parked in a `pending` ref and a single `requestAnimationFrame` is scheduled if one is not already outstanding. ScrollTrigger fires per scroll event, not per paint, so several ticks can clear both other gates inside one frame — coalescing makes that one render.
5. The override: when `p <= 0 || p >= 1` the time and distance gates are skipped entirely, because there is no later tick to correct a dropped endpoint. A second guard compares against the last committed value so that sitting at the end of the range does not re-commit on every tick.
6. The committed state carries `commits` and `ticks` alongside `progress`, so the ratio between callbacks and renders is visible in the UI rather than only in a profiler.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `interval = 100`
  Milliseconds between commits — about 10 renders a second against roughly 120 ticks. Around 16ms the gate stops doing anything useful because it approximates one render per frame; past ~200ms the discrete steps are large enough that a reader notices the value lagging behind the scroll.
- `minDelta = 0.02`
  2% of the trigger range. Below about 0.005 a slow drag commits on almost every time window; above ~0.05 short triggers can complete their whole range in two or three commits and the readout jumps.
- `scrub = 0.4`
  Under half a second of catch-up. Long enough to smooth a jittery wheel into a continuous ramp, short enough that the committed value still feels attached to the hand. `true` welds it to the wheel and every scroll spike becomes a tick.
- `boundary test = p <= 0 || p >= 1`
  Inclusive, not strict. ScrollTrigger reports exactly 0 and exactly 1 at the ends, so `< 0` and `> 1` never match and the override silently does nothing.

## API

```ts
function ThrottledScrubState(props: { children: (state: { progress: number; commits: number; ticks: number }) => ReactNode; interval?: number; minDelta?: number; scrub?: number | boolean; scrollerRef?: RefObject<HTMLElement | null>; className?: string }): JSX.Element
```

- `children: (state: ScrubState) => ReactNode`
  Render prop, called only on committed states.
- `interval: number` — default `100`
  Minimum milliseconds between commits.
- `minDelta: number` — default `0.02`
  Minimum change in progress before a commit is worth making.
- `scrub: number | boolean` — default `0.4`
  Seconds of catch-up behind the scroll position.
- `scrollerRef: RefObject<HTMLElement | null>`
  The scroll container that owns the scroll position. Omit for the document.
- `className: string`
  Merged onto the wrapper via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function ThrottledScrubState({
  children,
  interval = 100,
  minDelta = 0.02,
  scrub = 0.4,
  scrollerRef,
  className,
}: ThrottledScrubStateProps) {
  const root = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();

  // The only React state in the component. Everything else is a ref, because
  // a ref write does not render.
  const [state, setState] = useState<ScrubState>({ progress: 0, commits: 0, ticks: 0 });

  const ticks = useRef(0);
  const commits = useRef(0);
  const lastAt = useRef(0);
  const lastProgress = useRef(0);
  const pending = useRef<number | null>(null);
  const frame = useRef(0);

  useGsap(
    gsap,
    () => {
      const el = root.current;
      if (!el) return;

      // Gate 3: coalesce. Several ticks can pass all the other gates inside
      // one frame (ScrollTrigger fires per scroll event, not per paint), and
      // three setStates in a frame is three renders for one visible change.
      const flush = () => {
        frame.current = 0;
        const value = pending.current;
        if (value === null) return;
        pending.current = null;
        commits.current += 1;
        setState({ progress: value, commits: commits.current, ticks: ticks.current });
      };

      const trigger = ScrollTrigger.create({
        trigger: el,
        scroller: scrollerRef?.current ?? undefined,
        start: 'top bottom',
        end: 'bottom top',
        // Reduced motion welds the readout to the wheel: the value still
        // tracks the scroll the reader is performing, but nothing continues
        // to move after they stop.
        scrub: reduced ? true : scrub,
        invalidateOnRefresh: true,
        onUpdate: (self) => {
          const p = self.progress;
          ticks.current += 1;

          // The override. The ends of the range are the two values that must
          // never be dropped, because there is no later tick to correct them.
          const boundary = p <= 0 || p >= 1;

          if (boundary) {
            // ...but do not re-commit the same boundary on every one of the
            // dozens of ticks that arrive while sitting at the end.
            if (p === lastProgress.current) return;
          } else {
            // Gate 1: time. `performance.now()` and not `Date.now()` — a
            // monotonic clock, so an NTP correction cannot make the elapsed
            // time negative and freeze the gate shut.
            if (performance.now() - lastAt.current < interval) return;
            // Gate 2: distance. A slow drag passes the time gate constantly
            // while moving a fraction of a percent, which is a render for a
            // change nobody can see.
            if (Math.abs(p - lastProgress.current) < minDelta) return;
          }

          lastAt.current = performance.now();
          lastProgress.current = p;
          pending.current = p;
          if (frame.current === 0) frame.current = requestAnimationFrame(flush);
        },
      });

      return () => {
        // Order matters: kill the source first, then drop the frame it may
        // have just scheduled. A flush that survives teardown calls setState
        // on an unmounted tree.
        trigger.kill();
        if (frame.current !== 0) {
          cancelAnimationFrame(frame.current);
          frame.current = 0;
        }
        pending.current = null;
      };
    },
    root,
    [interval, minDelta, scrub, scrollerRef, reduced],
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The context cleanup kills the ScrollTrigger first and only then cancels any outstanding animation frame, and nulls the pending value. Reversing the order leaves a window in which the still-live trigger schedules a frame that is never cancelled, and that flush calls `setState` on an unmounted tree — thrown from inside a rAF callback, so the stack trace names no component.

**Reduced motion.** The trigger stays, because the value tracks a scroll the reader is performing rather than animating on its own, but `scrub` becomes `true` — welded to the scroll position with no catch-up easing, so nothing continues to move after the reader stops. The gate is unchanged.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Calling `setState` directly from `onUpdate`. On a trackpad flick that is 100+ renders a second of the entire subtree; the symptom is that scrolling is smooth on an empty page and drops to single-digit frame rates as soon as a real list is rendered below the component.
- Throttling without the boundary override. Release a fast flick and the final tick lands inside the cooldown window, so the state stops at whatever value last got through — a progress bar that never quite reaches 100% and a "complete" branch that never runs.
- Re-committing the boundary on every tick. Once progress is pinned at 1, every subsequent tick passes the override, so idling at the end of the range renders continuously — the opposite of the intent.
- Skipping the rAF coalescer. ScrollTrigger fires per scroll event, so two or three ticks can pass the time and distance gates within a single frame and React renders three times for one painted change.
- Cancelling the frame before killing the trigger. The trigger can schedule a new frame between the two calls, and that flush lands after unmount — `setState` on a dead tree, thrown from a rAF callback with no component in the stack trace.
- Storing tick and commit counts in state. They are diagnostics about renders; putting them in state makes every diagnostic a render and the measurement becomes the thing being measured.

## Notes

- The continuous signal is still available: anything that needs per-frame precision should be written imperatively from `onUpdate`, and only the coarse state should come through the gate.
- The render prop receives the committed state only, so consumers cannot accidentally subscribe to the raw tick rate.

## Definition of done

Scroll the panel and watch the two counters: ticks climbs continuously while commits climbs in steps, at roughly a tenth the rate. Flick hard to the very bottom and the progress readout reads exactly 100%, not 93%. Hold still at the bottom and the commit counter stops increasing. Move the scroller by one or two pixels at a time and no commit happens until the distance threshold is crossed.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Tweened Cursor Uniform

A full-quad fragment shader draws a procedural grid and pulls its UVs toward a lens centred on the pointer. The lens position is not assigned into the uniform — GSAP tweens it onto a plain object, and the render loop copies that object across each frame, so the distortion trails the cursor and then comes fully to rest under it. Presence is a second, independent tween, so leaving the container dims the lens where it stands rather than dragging it away.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A shader grid with a lens under the pointer, whose position is tweened into the uniform so it settles instead of chasing.

- Category: cursor
- Runtime cost: webgl
- Dependencies: three@^0.185.1, gsap@^3.15.0

## How it works

1. A `pointermove` handler converts client coordinates into NDC against the live container rect: `x = ((e.clientX - rect.left) / rect.width) * 2 - 1` and `y = -(((e.clientY - rect.top) / rect.height) * 2 - 1)`, y negated because NDC counts upward and CSS counts downward.
2. That NDC pair is tweened onto a plain `{ x, y }` object with `gsap.to(pos, { x, y, duration: 0.6, ease: "power3.out", overwrite: true })`. This is the smoothing. Nothing else damps: the uniform copy in the rAF loop is a straight assignment.
3. The contrast with `useSmoothPointer` is the point. `damp` closes a fixed fraction of the remaining gap per second — always moving, always behind, asymptotic. A tween has a duration and an end, so `power3.out` decelerates the lens into a hard stop exactly under the cursor when the hand stops.
4. Presence is a separate scalar tweened to 1 over 0.4s on move and back to 0 over 0.6s on `pointerleave`, multiplied into the falloff in the shader. Splitting it from position is what makes the lens fade out in place instead of sliding off toward a parked coordinate.
5. The fragment shader works in aspect-corrected centre space, computes a Gaussian `fall = exp(-d² / r²)` from the cursor, and displaces the sampling point with `warped = p - normalize(p - c) * fall * uStrength * uAmount` before the grid function reads it — so the grid compresses toward the cursor like glass rather than smearing.
6. Anti-aliasing of the grid lines is derived from `uResolution` (`w = widthPx * cells / res`) instead of `fwidth`, so the same source compiles on a WebGL1 context with no derivatives extension pragma.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `PARKED_NDC = 999`
  Initial value of the tweened cursor object. Far outside the -1..1 NDC range, so `exp(-d²/r²)` underflows to exactly 0 and the very first frame is guaranteed lens-free. Initialising at (0,0) puts a full-strength bulge dead centre before the pointer has ever moved.
- `followDuration = 0.6`
  Seconds for the lens to reach the pointer. This is long for a cursor effect and deliberately so — the lens reads as heavy glass being dragged. Under ~0.25 it is welded to the pointer and the trailing quality disappears.
- `PRESENCE_IN / PRESENCE_OUT = 0.4 / 0.6`
  Asymmetric on purpose. Arrival must beat the eye to the pointer; departure is slower so the lens reads as dissipating rather than being switched off.
- `radius = 0.28`
  Gaussian sigma in centre space, where the short edge spans 1.0. So the lens core is a bit over a quarter of the container height. Past ~0.45 the falloff no longer reaches zero inside the frame and the whole grid warps.
- `amount = 0.22`
  Peak UV displacement toward the cursor, in centre-space units. Above ~0.35 the pull exceeds the local grid spacing and lines fold back through each other, which reads as a rendering fault.
- `pixelRatio cap = 2`
  Fill-rate is quadratic in DPR. On a 3x display an uncapped full-container fragment shader costs 2.25x more per frame for no visible gain.

## API

```ts
function TweenedCursorUniform(props: { followDuration?: number; radius?: number; amount?: number; className?: string }): JSX.Element
```

- `followDuration: number` — default `0.6`
  Seconds for the lens to catch the pointer.
- `radius: number` — default `0.28`
  Gaussian sigma of the lens, in centre-space units where the short edge is 1.
- `amount: number` — default `0.22`
  Peak UV displacement toward the cursor at full strength.
- `className: string`
  Merged onto the root container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
const FOLLOW_EASE = 'power3.out';
const PRESENCE_IN = 0.4;
const PRESENCE_OUT = 0.6;
/** Far outside NDC, so `exp(-d²/r²)` underflows to 0 before the first move. */
const PARKED_NDC = 999;

export function TweenedCursorUniform({
  followDuration = 0.6,
  radius = 0.28,
  amount = 0.22,
  className,
}: TweenedCursorUniformProps) {
  const host = useRef<HTMLDivElement>(null);
  const canvas = useRef<HTMLCanvasElement>(null);
  const api = useRef<Scene | null>(null);

  /* The two tween targets. Plain objects, not uniforms: GSAP writes numbers
     onto them and the loop copies them across once per frame. Tweening the
     uniform's `.value` vector directly works too, but this keeps the tween
     alive across a material rebuild. */
  const smooth = useRef({ x: PARKED_NDC, y: PARKED_NDC });
  const presence = useRef({ value: 0 });

  const reduced = useReducedMotion();
  const { width, height } = useResizeObserver(host);
  const { inView } = useInView(host, { rootMargin: '128px' });
  const visible = useVisibility();

  /* Build once. Never in the resize effect — recreating a WebGLRenderer on
     every resize leaks contexts, and Chromium kills the OLDEST live context
     when the ~16-per-process ceiling is hit, so an unrelated canvas
     elsewhere on the page goes black. */
  useEffect(() => {
    const el = canvas.current;
    if (!el || !hasWebGL()) return;

    const renderer = new THREE.WebGLRenderer({
      canvas: el,
      antialias: false,
      alpha: false,
      powerPreference: 'low-power',
    });
    renderer.setPixelRatio(pixelRatio(2));

    const material = new THREE.ShaderMaterial({
      vertexShader,
      fragmentShader,
      uniforms: {
        uResolution: { value: new THREE.Vector2(1, 1) },
        uCursor: { value: new THREE.Vector2(PARKED_NDC, PARKED_NDC) },
        uStrength: { value: 0 },
        uTime: { value: 0 },
        uRadius: { value: radius },
        uAmount: { value: amount },
        uInk: { value: new THREE.Color(0.08, 0.09, 0.11) },
        uPaper: { value: new THREE.Color(0.04, 0.04, 0.05) },
        uAccent: { value: new THREE.Color(0.95, 0.55, 0.2) },
      },
    });

    const geometry = new THREE.PlaneGeometry(2, 2);
    const scene = new THREE.Scene();
    scene.add(new THREE.Mesh(geometry, material));

    // A 2x2 plane under an identity-ish ortho camera is a full-screen quad
    // with no projection maths and no camera to keep in sync on resize.
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);

    api.current = { renderer, camera, scene, geometry, material };

    return () => {
      api.current = null;
      // `dispose()` alone frees GPU objects but leaves the context alive;
      // only `forceContextLoss()` hands it back, which is what this does.
      disposeRenderer(renderer);
      geometry.dispose();
      material.dispose();
    };
  }, [radius, amount]);

  /* Size in its own effect so a resize never touches the renderer's lifetime. */
  useEffect(() => {
    const s = api.current;
    if (!s || width === 0 || height === 0) return;
    s.renderer.setSize(width, height, false);
    const res = s.material.uniforms.uResolution;
    if (res) (res.value as THREE.Vector2).set(width, height);
    // Render once so a resize while paused still repaints, rather than
    // stretching the previous framebuffer until the pointer moves again.
    s.renderer.render(s.scene, s.camera);
  }, [width, height]);

  /* Pointer -> tween. The tween is the smoothing; nothing else damps. */
  useEffect(() => {
    const el = host.current;
    if (!el || reduced || !hasWebGL()) return;
    // A coarse pointer only produces events during a drag, so the lens would
    // pop into existence under a finger and vanish on release.
    if (!window.matchMedia('(pointer: fine)').matches) return;

    const pos = smooth.current;
    const pres = presence.current;

    const onMove = (e: PointerEvent) => {
      const rect = el.getBoundingClientRect();
      if (rect.width === 0 || rect.height === 0) return;
      const x = ((e.clientX - rect.left) / rect.width) * 2 - 1;
      const y = -(((e.clientY - rect.top) / rect.height) * 2 - 1);

      // `overwrite: true` (not 'auto'): each move must kill the whole previous
      // tween, including the half of it that has not started easing yet.
      gsap.to(pos, { x, y, duration: followDuration, ease: FOLLOW_EASE, overwrite: true });
      gsap.to(pres, { value: 1, duration: PRESENCE_IN, ease: 'power2.out', overwrite: 'auto' });
    };

    const onLeave = () => {
      // Fade presence only. Leaving position alone means the lens dims where
      // it stands; tweening it to a corner instead drags a visible streak.
      gsap.to(pres, { value: 0, duration: PRESENCE_OUT, ease: 'power2.out', overwrite: 'auto' });
    };

    el.addEventListener('pointermove', onMove, { passive: true });
    el.addEventListener('pointerleave', onLeave);

    return () => {
      el.removeEventListener('pointermove', onMove);
      el.removeEventListener('pointerleave', onLeave);
      gsap.killTweensOf([pos, pres]);
    };
  }, [followDuration, reduced]);

  useRaf(
    (_dt, elapsed) => {
      const s = api.current;
      if (!s) return;
      const u = s.material.uniforms;
      const cursor = u.uCursor;
      const strength = u.uStrength;
      const time = u.uTime;
      if (cursor) (cursor.value as THREE.Vector2).set(smooth.current.x, smooth.current.y);
      if (strength) strength.value = presence.current.value;
      if (time) time.value = elapsed;
      s.renderer.render(s.scene, s.camera);
    },
    inView && visible && !reduced,
  );

  /* Reduced motion still gets a picture — a single frame with the lens parked
     off-centre — rather than an empty box. One render, then nothing. */
  useEffect(() => {
    const s = api.current;
    if (!s || !reduced || width === 0 || height === 0) return;
    const cursor = s.material.uniforms.uCursor;
    const strength = s.material.uniforms.uStrength;
    if (cursor) (cursor.value as THREE.Vector2).set(-0.25, 0.15);
    if (strength) strength.value = 1;
    s.renderer.render(s.scene, s.camera);
  }, [reduced, width, height]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes both pointer listeners and kills the tweens on the two plain objects. The build effect nulls its handle, calls `disposeRenderer` (which stops the animation loop, disposes, forces context loss, and zeroes the backing store), then disposes the geometry and the material. The rAF subscription is released by `useRaf`.

**Reduced motion.** The rAF loop and the pointer listeners never attach. A single frame is rendered with the lens parked slightly off-centre at full strength, so the component is a static composed image of the effect rather than an empty box. It repaints once on resize and never again.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Assigning the pointer straight into the uniform and smoothing in the shader instead. The shader has no memory between frames without a render target, so the usual workaround is to lerp a JS variable per frame with a fixed alpha — which is frame-rate dependent and converges twice as fast at 120Hz.
- Tweening position and presence together. On `pointerleave` the lens then slides toward its parked coordinate at full strength, dragging a bright streak across the whole canvas on the way out.
- Leaving the tweened cursor at (0, 0) on mount. A full-strength bulge sits dead centre from the first painted frame until the user moves, which looks like a baked-in artefact rather than an interaction.
- Using `overwrite: "auto"` on the position tween. Auto only retires *rendered* conflicts; a burst of moves inside one frame can leave the earlier tween partly live. `overwrite: true` kills the previous tween outright, which is what you want when every event supersedes the last.
- Recreating the `WebGLRenderer` inside the resize effect. Each resize leaks a context, and Chromium silently kills the oldest of its ~16 per-process contexts, so an unrelated canvas elsewhere on the page goes black.
- Calling `renderer.dispose()` and stopping there. That frees GPU objects but not the context itself; `forceContextLoss()` — what `disposeRenderer` does — is the call that actually hands it back.
- Not repainting after a resize while the loop is paused. The framebuffer keeps the old dimensions and the browser stretches the last frame, so an off-screen preview reappears visibly smeared.

## Notes

- Gated on `(pointer: fine)`. On touch the listeners never attach, so the canvas renders the idle grid with the lens parked outside NDC — a tap cannot pop a bulge under the finger and leave it there on release.
- Guarded with `hasWebGL()`: on a blocklisted GPU or with hardware acceleration off, nothing is constructed and the container is simply an empty dark panel rather than a permanently blank canvas.
- The loop is gated on `useInView` plus `useVisibility`, so an off-screen or backgrounded instance costs zero GPU time.

## Definition of done

Move across the panel and the grid compresses under a soft circular lens that arrives about half a second behind the pointer, then settles precisely under it when you stop. Leave the panel and the lens fades out where it stands without sliding. Resize the container and the lens stays circular rather than becoming an ellipse. Unmount and the WebGL context count in about:gpu goes back down.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Cover-Fit UV Maths

A shader has no box to crop, so `object-fit: cover` has to happen on the texture coordinates before the sample. The fit is a pure function of two numbers — the texture aspect and the quad aspect — which means the quad can be reshaped on every frame and the crop simply follows, with no re-upload and no CPU work. The frame here cycles from tall to wide continuously, because a cover fit only ever tested at one aspect ratio has not been tested.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

object-fit: cover for a textured quad, solved in UV space so the crop follows a frame that reshapes every frame.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. The sampled window starts at the full texture, `scale = vec2(1.0)`, and is only ever narrowed. If `textureAspect > planeAspect` the texture has surplus width, so `scale.x = planeAspect / textureAspect`; otherwise it has surplus height and `scale.y = textureAspect / planeAspect`. Exactly one axis shrinks and the other reaches both edges of the image.
2. The leftover slack is `1 - scale`, and multiplying it by the focal point places that slack: `offset = (1.0 - scale) * uFocal`. At a focal of 0.5 the sampled window is `[(1-s)/2, (1+s)/2]` — centred — while 0 pins the crop to the left or top edge and 1 to the right or bottom.
3. The final coordinate is `vUv * scale + offset`, which is guaranteed to stay inside [0,1] because scale is never greater than 1 and offset is exactly the remaining room. Nothing has to be clamped and no branch depends on the fragment.
4. Overscan divides the scale further, shrinking the window past a strict fit. That reserve is what a vertex displacement elsewhere in a pipeline eats into: with no reserve, a wave or a bulge pushes a coordinate past the sampled region and the texture's clamped border smears along the edge.
5. The frame is driven by an eased triangle wave with a hold at each end, and its scale is fitted to the viewport by the contain rule — `frameAspect > maxW / maxH ? width-limited : height-limited` — so the tall end of the cycle stays fully on screen rather than running off the top and bottom.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `minAspect / maxAspect = 0.62 / 2.3`
  The range the frame sweeps. Both ends have to sit clearly on opposite sides of the source's own 16:9 so the shader is seen switching which axis it crops; a range that stays on one side of the texture aspect never exercises the other branch at all.
- `period / hold = 8 s / 0.12`
  Twelve percent of the cycle parked at each extreme. Without a hold the frame is only ever momentarily at its widest and the eye never gets to check the crop; past ~0.25 the component spends more time still than moving.
- `fill = 0.84`
  Fraction of the container the frame occupies at its largest. At 1.0 the frame is flush with the edges and its reshaping is invisible because there is no background to reshape against.
- `overscan = 1`
  Exactly 1 is a strict fit and the right default when nothing displaces the geometry. Raise it — 1.12 is the value `cylinder-gallery` uses — only when vertices move after the UV is computed; every increment past 1 is crop permanently thrown away.
- `focal = [0.5, 0.5]`
  Centres the slack on both axes. 0 or 1 pins the crop to an edge, which is what a subject-aware crop wants; anything outside [0,1] pushes the window off the texture and samples the clamped border.
- `texture size = 1200 x 675`
  A deliberately 16:9 source, so both branches of the fit are exercised as the frame sweeps past that ratio. The absolute size only sets sampling quality.
- `grid cell = width / 16`
  Square cells measured in source pixels. They are the test instrument: under a correct cover fit they stay square at every frame aspect, and the moment the maths degrades into a stretch they visibly become rectangles.

## API

```ts
function UvCoverFit(props: { minAspect?: number; maxAspect?: number; period?: number; hold?: number; fill?: number; overscan?: number; focal?: [number, number]; paint?: (ctx: CanvasRenderingContext2D, size: { width: number; height: number }) => void; textureSize?: { width: number; height: number }; className?: string }): JSX.Element
```

- `minAspect: number` — default `0.62`
  Narrowest frame aspect in the cycle (w / h).
- `maxAspect: number` — default `2.3`
  Widest frame aspect in the cycle (w / h).
- `period: number` — default `8`
  Seconds for a full narrow-wide-narrow cycle, holds included.
- `hold: number` — default `0.12`
  Fraction of the cycle spent parked at each extreme.
- `fill: number` — default `0.84`
  Fraction of the container the frame fills at its largest.
- `overscan: number` — default `1`
  Extra zoom on the crop. 1 fits exactly; above 1 keeps margin in reserve.
- `focal: [number, number]` — default `[0.5, 0.5]`
  Where the crop slack goes, per axis. 0.5 centres it.
- `paint: (ctx, size) => void`
  Override the source image. Receives a 2D context for the source canvas.
- `textureSize: { width: number; height: number }` — default `{ width: 1200, height: 675 }`
  Source canvas size. Its ratio is the texture aspect the shader fits.
- `className: string`
  Merged onto the wrapper via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function UvCoverFit({
  minAspect = 0.62,
  maxAspect = 2.3,
  period = 8,
  hold = 0.12,
  fill = 0.84,
  overscan = 1,
  focal = [0.5, 0.5],
  paint,
  textureSize = DEFAULT_TEXTURE,
  className,
}: UvCoverFitProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);

  const { width, height } = useResizeObserver(host);
  const { inView } = useInView(host, { threshold: 0 });
  const visible = useVisibility();
  const reduced = useReducedMotion();

  const [supported, setSupported] = useState(true);
  useEffect(() => setSupported(hasWebGL()), []);

  const elapsed = useRef(0);
  const viewport = useRef({ width: 1, height: 1 });

  const live = useRef({ minAspect, maxAspect, period, hold, fill, overscan, focal });
  live.current = { minAspect, maxAspect, period, hold, fill, overscan, focal };

  const ready = width > 1 && height > 1 && supported;
  const textureWidth = textureSize.width;
  const textureHeight = textureSize.height;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setSize(el.clientWidth, el.clientHeight, false);
    renderer.setClearColor(0x000000, 0);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';
    el.appendChild(renderer.domElement);

    const scene = new THREE.Scene();
    // Orthographic, because nothing here is about perspective. World units map
    // one-to-one to the frame: the quad's scale IS its aspect ratio, with no
    // frustum arithmetic in between.
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 10);
    camera.position.z = 1;

    const canvas = document.createElement('canvas');
    canvas.width = textureWidth;
    canvas.height = textureHeight;
    const ctx = canvas.getContext('2d');
    if (ctx) (paint ?? paintSource)(ctx, { width: textureWidth, height: textureHeight });

    const texture = new THREE.CanvasTexture(canvas);
    texture.colorSpace = THREE.SRGBColorSpace;
    // Clamp, not repeat. If a rounding error ever pushes a UV a hair past 1,
    // repeat wraps the far edge of the image into view as a bright seam;
    // clamp smears the border pixel instead, which is invisible.
    texture.wrapS = THREE.ClampToEdgeWrapping;
    texture.wrapT = THREE.ClampToEdgeWrapping;
    texture.anisotropy = Math.min(4, renderer.capabilities.getMaxAnisotropy());

    const uniforms: CoverUniforms = {
      uTexture: { value: texture },
      uTextureAspect: { value: textureWidth / textureHeight },
      uPlaneAspect: { value: 1 },
      uOverscan: { value: overscan },
      uFocal: { value: new THREE.Vector2(focal[0], focal[1]) },
    };

    // One quad, two triangles. The fit is per-fragment ratio arithmetic, so
    // subdividing would buy nothing at all.
    const geometry = new THREE.PlaneGeometry(1, 1);
    const material = new THREE.ShaderMaterial({
      vertexShader: uvCoverFitVertexShader,
      fragmentShader: uvCoverFitFragmentShader,
      uniforms,
    });
    const mesh = new THREE.Mesh(geometry, material);
    scene.add(mesh);

    stage.current = { renderer, scene, camera, mesh, geometry, material, texture, uniforms };

    return () => {
      stage.current = null;
      scene.remove(mesh);
      // Inside `uniforms`, so `disposeObject` will never reach it.
      texture.dispose();
      disposeObject(scene);
      geometry.dispose();
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, textureWidth, textureHeight, paint]);

  useEffect(() => {
    const current = stage.current;
    if (!current || width < 1 || height < 1) return;
    const aspect = width / height;
    current.renderer.setPixelRatio(pixelRatio());
    current.renderer.setSize(width, height, false);
    // Ortho bounds track the container aspect so a world unit is the same
    // number of pixels on both axes. Leave them at +/-1 and the quad is
    // stretched by the viewport, which would fake the exact bug this
    // component exists to avoid.
    current.camera.left = -aspect;
    current.camera.right = aspect;
    current.camera.top = 1;
    current.camera.bottom = -1;
    current.camera.updateProjectionMatrix();
    viewport.current = { width: aspect * 2, height: 2 };
  }, [width, height]);

  useRaf(
    (dt) => {
      const current = stage.current;
      if (!current) return;
      const {
        minAspect: low,
        maxAspect: high,
        period: cycle,
        hold: pause,
        fill: coverage,
        overscan: zoom,
        focal: focalPoint,
      } = live.current;

      if (!reduced) elapsed.current += dt;
      const phase = reduced ? 0.5 : cyclePhase(elapsed.current, Math.max(cycle, 1), pause);
      const frameAspect = lerp(low, high, phase);

      // Contain the frame inside the viewport at the requested aspect. Fitting
      // on width alone means the tall end of the cycle runs off the top and
      // bottom, which hides half the thing being demonstrated.
      const available = viewport.current;
      const maxW = available.width * coverage;
      const maxH = available.height * coverage;
      const frameW = frameAspect > maxW / maxH ? maxW : maxH * frameAspect;
      const frameH = frameAspect > maxW / maxH ? maxW / frameAspect : maxH;

      current.mesh.scale.set(frameW, frameH, 1);
      // The uniform is the QUAD's aspect, not the canvas's. Passing the
      // container aspect here is the classic bug: the crop then ignores the
      // frame and only tracks the browser window.
      current.uniforms.uPlaneAspect.value = frameAspect;
      current.uniforms.uOverscan.value = zoom;
      current.uniforms.uFocal.value.set(focalPoint[0], focalPoint[1]);

      current.renderer.render(current.scene, current.camera);
    },
    ready && inView && visible,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the quad from the scene, disposes the `CanvasTexture` explicitly because it sits inside `material.uniforms` where `disposeObject` cannot reach it, runs `disposeObject` over the scene, disposes the geometry and material, then calls `disposeRenderer` — `setAnimationLoop(null)`, `dispose()`, `forceContextLoss()` — and removes the canvas from the DOM. The stage ref is nulled before any of it, so a frame already queued by the shared RAF loop returns immediately instead of rendering into a dead context.

**Reduced motion.** The aspect cycle does not advance: elapsed time stops accumulating and the phase is pinned to 0.5, so the frame holds at the midpoint between `minAspect` and `maxAspect` and never reshapes. The cover fit itself still runs every frame and still responds correctly to container resizes — what is removed is the autonomous animation, not the behaviour.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Scaling the short axis up rather than the long axis down. `scale.y = planeAspect / textureAspect` when that ratio exceeds 1 pushes the sampled window past the edge of the texture, and with the default `RepeatWrapping` the far side of the image wraps into view as a bright seam across the frame.
- Passing the container's aspect ratio as `uPlaneAspect`. The uniform has to be the aspect of the QUAD being drawn; hand it the canvas aspect instead and the crop stops tracking the frame entirely and only responds to browser-window resizes.
- Leaving the orthographic camera at the default -1..1 bounds. A world unit is then a different number of pixels horizontally and vertically, so the quad is stretched by the viewport — faking the exact distortion this component exists to prevent. The bounds track the container aspect.
- Applying the offset before the scale. `(vUv + offset) * scale` shrinks the offset along with the coordinate, so the crop drifts toward the origin as the aspect mismatch grows instead of staying centred.
- Leaving `wrapS` / `wrapT` at `RepeatWrapping`. A rounding error of one ulp past 1.0 then wraps to the opposite edge of the image and shows as a one-pixel bright line; `ClampToEdgeWrapping` smears the border pixel instead, which is invisible.
- Testing with a smooth gradient. Every fit looks correct on a gradient. A square grid and a true circle are what make a stretch obvious — the cells go rectangular and the circle goes elliptical.
- Fitting the frame on width alone. The tall end of the aspect cycle then runs off the top and bottom of the container, hiding half of what is being demonstrated. The frame is contained on whichever axis is tighter.
- Omitting `#include <colorspace_fragment>` from the `ShaderMaterial`. three only injects output conversion into its own materials, so raw linear values ship into an sRGB framebuffer and the quad renders visibly washed out.
- Calling `renderer.dispose()` alone on unmount. It frees GPU objects but leaves the WebGL context alive, and Chromium silently kills the oldest context once a renderer process holds about 16 of them. `disposeRenderer` calls `forceContextLoss`.

## Notes

- The fit is per-fragment ratio arithmetic, so the quad is a single unsubdivided `PlaneGeometry(1, 1)`. `cylinder-gallery` runs the same maths per vertex instead, because there it feeds a bend that needs the result before rasterisation.
- The camera is orthographic so that world units map straight onto the frame: the mesh's scale IS its aspect ratio, with no frustum arithmetic sitting between the two.

## Definition of done

The frame reshapes continuously from tall to wide and back, pausing briefly at each extreme. Throughout, the grid cells stay square and the circle stays circular — nothing ever stretches. As the frame passes the source's own 16:9 ratio you can see the crop switch from trimming the top and bottom to trimming the sides, with the centre of the image staying put. Resize the container and the frame stays fully inside it at both ends of its cycle. With `prefers-reduced-motion: reduce` the frame holds at one aspect and does not animate, and the image inside it is still correctly cropped.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Velocity Afterimage Pass

A motion trail that stores no history. Two render targets take turns: one holds everything that has happened, the other receives that accumulation multiplied by a decay factor with the current frame composited over it, and next frame they swap roles. Because the trail is a texture rather than a list of past positions, its length is one float — so it can be driven straight from how fast the marks are moving and change continuously without allocating anything. Fast movement smears; slow movement is perfectly crisp.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Marks that smear into a tail when the pointer moves fast and stay crisp when it slows, from two targets swapping roles.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. Three half-float targets are allocated at container size x DPR x `resolutionScale`: `frame` receives only this frame's marks, and `ping`/`pong` alternate as the accumulation. Reading and writing one target in a single pass is undefined in WebGL, which is the only reason there are two.
2. Pass 1 clears `frame` and renders the content scene into it — one lead mark plus `satellites` orbiters, all sharing a single 1x1 `PlaneGeometry` and one 256px canvas-drawn radial falloff texture, so the whole cluster is a handful of draw calls and no per-frame allocation.
3. The lead follows the pointer through `damp(lead.x, pointer.ndcX * aspect, 0.0004, dt)`, and the satellites sit at `lead + (cos, sin)(i/n * 2PI + elapsed * 1.5) * 0.3` around it. The x target is multiplied by aspect because the orthographic frustum is widened to `[-aspect, aspect]` while staying `[-1, 1]` tall.
4. Trail length is measured from the *mark*, not the cursor: `speed = hypot(lead - previousLead) / dt`, normalised by `reference`, clamped to 0..1 and scaled by `maxDamp`. That target is then itself run through `damp(..., 0.003, dt)`, so the tail extends and retracts smoothly instead of popping to full length on the first fast frame.
5. Pass 2 renders a fullscreen quad into whichever target is not the current history, with `uCurrent = frame.texture`, `uHistory = ping.texture` and `uDamp` set to the smoothed speed. The fragment is `float alive = step(uCutoff, history.a); history *= uDamp * alive; gl_FragColor = max(current, history);` — `max` keeps the head at full strength and lets the tail sit underneath it.
6. Pass 3 blits the accumulation to the canvas through a stock `MeshBasicMaterial`, so three performs output colour conversion exactly once and the blend pass stays in linear space. Then `ping` and `pong` are swapped: what was just written becomes next frame's history.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `maxDamp = 0.9`
  Per-frame decay factor at full speed. Must stay below 1: at exactly 1 nothing ever decays and the trail becomes a permanent painted streak across the panel. Above ~0.95 the tail outlives the gesture by seconds and reads as a smudged framebuffer rather than motion.
- `cutoff = 0.06`
  Alpha below which `step()` zeroes a pixel outright. Geometric decay never actually reaches zero — at 0.9 a pixel still holds 0.5% of its value a hundred frames later, and on a half-float target that faint ghost of the very first frame is baked in permanently. Below ~0.02 the ghost is visible on a dark surface; above ~0.15 the tail ends in a hard edge instead of fading.
- `reference = 1.6`
  World units per second that count as full speed. The frustum is 2 units tall, so this is roughly 0.8 container heights per second — a brisk but ordinary hand movement. Set it much higher and only a violent flick produces any trail at all.
- `LEAD_SMOOTHING = 0.0004`
  Fraction of the gap to the pointer still remaining after one second. Tight enough that the lead feels attached to the cursor, loose enough that the mark keeps travelling for a frame or two after the hand stops — which is what gives the tail something to decay from.
- `DAMP_SMOOTHING = 0.003`
  Smoothing on the decay factor itself, deliberately looser than the position smoothing. If the trail length tracked speed instantly, a single dropped frame would spike `dt`, spike the measured speed, and flash a full-length tail out of a stationary mark.
- `ORBIT_RADIUS / ORBIT_SPEED = 0.3 / 1.5`
  Satellites orbit 0.3 world units out at 1.5 rad/s. The radius has to exceed the lead's own 0.34 half-size or the satellites never clear the lead's falloff and the cluster reads as one blob; the speed is what produces a curved tail rather than three parallel straight ones.
- `SPRITE_SIZE = 256`
  One canvas-drawn radial gradient shared by every mark. 256px is above the on-screen size of the largest mark at DPR 2, so it never magnifies into visible steps, and it is small enough that the upload is a single sub-millisecond cost at build time.
- `target type / filter = HalfFloatType, NearestFilter`
  The accumulation is multiplied by a fraction every frame. On the default 8-bit unsigned byte the result quantises into stair-stepped bands down the length of the trail. Nearest rather than linear because the blend samples texel-for-texel from a target of identical size — bilinear filtering would smear the trail sideways a little more on each of the hundreds of passes a pixel survives.

## API

```ts
function VelocityAfterimagePass(props: { maxDamp?: number; cutoff?: number; reference?: number; satellites?: number; hue?: number; resolutionScale?: number; className?: string }): JSX.Element
```

- `maxDamp: number` — default `0.9`
  Longest trail, as the per-frame decay factor. Must stay below 1.
- `cutoff: number` — default `0.06`
  Alpha below which a pixel is cut to nothing instead of decaying forever.
- `reference: number` — default `1.6`
  Mark travel in world units per second that counts as full speed.
- `satellites: number` — default `3`
  Marks orbiting the lead. 0 leaves a single mark.
- `hue: number` — default `196`
  Base hue in degrees. Satellites are offset 26 degrees apart from it.
- `resolutionScale: number` — default `1`
  Render target scale relative to the canvas. Below 1 trades tail sharpness for fill rate.
- `className: string`
  Merged onto the root container via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function VelocityAfterimagePass({
  maxDamp = 0.9,
  cutoff = 0.06,
  reference = 1.6,
  satellites = 3,
  hue = 196,
  resolutionScale = 1,
  className,
}: VelocityAfterimagePassProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);

  const { width, height } = useResizeObserver(host);
  const { inView } = useInView(host, { threshold: 0 });
  const visible = useVisibility();
  const reduced = useReducedMotion();
  const pointer = useSmoothPointer({ target: host, smoothing: 0.0005 });

  const [supported, setSupported] = useState(true);
  useEffect(() => setSupported(hasWebGL()), []);

  const elapsed = useRef(0);
  const dampNow = useRef(0);
  const last = useRef<{ x: number; y: number } | null>(null);
  const lead = useRef({ x: 0, y: 0 });

  const live = useRef({ maxDamp, cutoff, reference });
  live.current = { maxDamp, cutoff, reference };

  const ready = width > 1 && height > 1 && supported;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    const renderer = new THREE.WebGLRenderer({ antialias: false, alpha: true });
    const dpr = pixelRatio();
    renderer.setPixelRatio(dpr);
    renderer.setSize(el.clientWidth, el.clientHeight, false);
    renderer.setClearColor(0x000000, 0);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';
    el.appendChild(renderer.domElement);

    const bufferW = Math.max(2, Math.round(el.clientWidth * dpr * resolutionScale));
    const bufferH = Math.max(2, Math.round(el.clientHeight * dpr * resolutionScale));

    // Three targets: one for this frame's marks, two that swap as history.
    // Reading and writing the same target in one pass is undefined behaviour
    // in WebGL and shows up as tearing or a black frame depending on driver.
    const frame = makeTarget(bufferW, bufferH);
    const ping = makeTarget(bufferW, bufferH);
    const pong = makeTarget(bufferW, bufferH);

    const sprite = new THREE.CanvasTexture(makeSprite());
    sprite.colorSpace = THREE.SRGBColorSpace;

    const content = new THREE.Scene();
    const contentCamera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 10);
    contentCamera.position.z = 1;

    const markGeometry = new THREE.PlaneGeometry(1, 1);
    const markMaterials: THREE.MeshBasicMaterial[] = [];

    const makeMark = (size: number, lightness: number, shift: number) => {
      const material = new THREE.MeshBasicMaterial({
        map: sprite,
        transparent: true,
        depthWrite: false,
        depthTest: false,
      });
      material.color.setHSL(((hue + shift) % 360) / 360, 0.72, lightness);
      markMaterials.push(material);
      const mesh = new THREE.Mesh(markGeometry, material);
      mesh.scale.setScalar(size);
      content.add(mesh);
      return mesh;
    };

    const leadMesh = makeMark(LEAD_SIZE, 0.62, 0);
    const orbiters: THREE.Mesh[] = [];
    for (let i = 0; i < Math.max(satellites, 0); i++) {
      orbiters.push(makeMark(SATELLITE_SIZE, 0.5, (i + 1) * 26));
    }

    // Fullscreen quad, reused by both post passes. PlaneGeometry(2, 2) exactly
    // fills a -1..1 orthographic frustum with no scaling in between.
    const quadGeometry = new THREE.PlaneGeometry(2, 2);
    const quadCamera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);

    const blendUniforms: BlendUniforms = {
      uCurrent: { value: frame.texture },
      uHistory: { value: ping.texture },
      uDamp: { value: 0 },
      uCutoff: { value: cutoff },
    };
    const blendMaterial = new THREE.ShaderMaterial({
      vertexShader: velocityAfterimageVertexShader,
      fragmentShader: velocityAfterimageFragmentShader,
      uniforms: blendUniforms,
      depthWrite: false,
      depthTest: false,
    });
    const quadScene = new THREE.Scene();
    quadScene.add(new THREE.Mesh(quadGeometry, blendMaterial));

    // The final blit uses a stock material precisely so three applies its own
    // output colour-space conversion here, and only here.
    const screenMaterial = new THREE.MeshBasicMaterial({
      map: pong.texture,
      transparent: true,
      depthWrite: false,
      depthTest: false,
    });
    const screenScene = new THREE.Scene();
    screenScene.add(new THREE.Mesh(quadGeometry, screenMaterial));

    const stageValue: Stage = {
      renderer,
      content,
      contentCamera,
      quadScene,
      quadCamera,
      screenScene,
      frame,
      ping,
      pong,
      blendUniforms,
      screenMaterial,
      lead: leadMesh,
      orbiters,
      sprite,
      quadGeometry,
      markGeometry,
      blendMaterial,
      markMaterials,
    };
    stage.current = stageValue;

    return () => {
      stage.current = null;
      disposeObject(content);
      disposeObject(quadScene);
      disposeObject(screenScene);
      sprite.dispose();
      quadGeometry.dispose();
      markGeometry.dispose();
      blendMaterial.dispose();
      screenMaterial.dispose();
      for (const material of markMaterials) material.dispose();
      // Render targets are not part of any scene graph, so nothing walks them.
      // Each one holds a full-resolution half-float texture and a framebuffer.
      frame.dispose();
      ping.dispose();
      pong.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, satellites, hue, resolutionScale]);

  useEffect(() => {
    const current = stage.current;
    if (!current || width < 1 || height < 1) return;
    const dpr = pixelRatio();
    const aspect = width / height;
    current.renderer.setPixelRatio(dpr);
    current.renderer.setSize(width, height, false);
    current.contentCamera.left = -aspect;
    current.contentCamera.right = aspect;
    current.contentCamera.updateProjectionMatrix();

    const bufferW = Math.max(2, Math.round(width * dpr * resolutionScale));
    const bufferH = Math.max(2, Math.round(height * dpr * resolutionScale));
    for (const target of [current.frame, current.ping, current.pong]) {
      target.setSize(bufferW, bufferH);
      // setSize reallocates the texture, so whatever the history held is now
      // undefined memory. Without an explicit clear, the first frame after a
      // resize can composite garbage that then decays for a second.
      current.renderer.setRenderTarget(target);
      current.renderer.clear();
    }
    current.renderer.setRenderTarget(null);
  }, [width, height, resolutionScale]);

  useRaf(
    (dt) => {
      const current = stage.current;
      if (!current) return;
      const { maxDamp: longest, cutoff: floor, reference: full } = live.current;

      if (!reduced) elapsed.current += dt;

      const aspect = current.contentCamera.right;
      const targetX = pointer.current.active ? pointer.current.ndcX * aspect : 0;
      const targetY = pointer.current.active ? pointer.current.ndcY : 0;
      lead.current.x = damp(lead.current.x, targetX, LEAD_SMOOTHING, dt);
      lead.current.y = damp(lead.current.y, targetY, LEAD_SMOOTHING, dt);

      // Speed of the mark itself, not of the raw pointer. The mark is what is
      // being smeared, so a trail measured from the cursor would start before
      // the mark moves and keep going after it has stopped.
      const previous = last.current;
      const speed =
        previous && dt > 0
          ? Math.hypot(lead.current.x - previous.x, lead.current.y - previous.y) / dt
          : 0;
      last.current = { x: lead.current.x, y: lead.current.y };

      const wanted = reduced ? 0 : clamp(speed / Math.max(full, 0.0001), 0, 1) * longest;
      dampNow.current = damp(dampNow.current, wanted, DAMP_SMOOTHING, dt);

      current.lead.position.set(lead.current.x, lead.current.y, 0);
      for (let i = 0; i < current.orbiters.length; i++) {
        const orbiter = current.orbiters[i];
        if (!orbiter) continue;
        const phase = (i / current.orbiters.length) * Math.PI * 2 + elapsed.current * ORBIT_SPEED;
        orbiter.position.set(
          lead.current.x + Math.cos(phase) * ORBIT_RADIUS,
          lead.current.y + Math.sin(phase) * ORBIT_RADIUS,
          0,
        );
      }

      // Pass 1 — this frame's marks alone, into their own target.
      current.renderer.setRenderTarget(current.frame);
      current.renderer.clear();
      current.renderer.render(current.content, current.contentCamera);

      // Pass 2 — decayed history plus this frame, into the target that is not
      // currently the history. Reading and writing one target in a single pass
      // is undefined in WebGL, which is the entire reason for the swap.
      current.blendUniforms.uCurrent.value = current.frame.texture;
      current.blendUniforms.uHistory.value = current.ping.texture;
      current.blendUniforms.uDamp.value = dampNow.current;
      current.blendUniforms.uCutoff.value = floor;
      current.renderer.setRenderTarget(current.pong);
      current.renderer.render(current.quadScene, current.quadCamera);

      // Pass 3 — the accumulation to the canvas, through a stock material so
      // three performs output colour conversion exactly once.
      current.renderer.setRenderTarget(null);
      current.screenMaterial.map = current.pong.texture;
      current.renderer.render(current.screenScene, current.quadCamera);

      // Swap. The target just written becomes next frame's history.
      const swap = current.ping;
      current.ping = current.pong;
      current.pong = swap;
    },
    ready && inView && visible,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Nulls the stage handle first so an in-flight frame cannot touch a half-disposed renderer, then `disposeObject` on all three scenes, disposes the sprite texture, both geometries, the blend, screen and every mark material, then explicitly disposes `frame`, `ping` and `pong` — no scene graph reaches them — then `disposeRenderer` (which forces context loss, not just `dispose()`) and removes the canvas element. The rAF subscription is released by `useRaf`.

**Reduced motion.** The orbit clock is not advanced and the decay factor is pinned to 0, so no accumulation survives a frame: the panel shows the crisp mark cluster with the satellites holding their starting angles and no tail behind them, however fast the pointer moves. The marks still follow the pointer, since that is direct response to input rather than self-driven motion.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Blending a target into itself. It is the obvious shape — one history target, read it and write it — and it is undefined behaviour in WebGL: depending on driver you get tearing, a black frame, or a result that looks right on your machine and fails on someone else's.
- Leaving the targets at the default `UnsignedByteType`. Repeated multiplication by 0.9 on 8 bits per channel quantises the tail into visible stair-stepped bands, and the banding is worst on exactly the slow gradients the effect is made of.
- Using `LinearFilter` on the ping-pong pair. Each pass smears the accumulation by a fraction of a texel, and a pixel survives hundreds of passes, so the trail visibly fattens and drifts diagonally away from the path the pointer actually took.
- Decaying with no floor. `history *= 0.9` is a geometric series that never reaches zero, so a permanent ghost of the first frames stays welded into the buffer and the panel is never clean again. The `step(uCutoff, history.a)` factor cuts it instead.
- Compositing with `mix()` or additive blending instead of `max()`. `mix` dims the current frame in proportion to the trail behind it, so the head goes dark exactly when it is moving fastest; additive blows out to white wherever the path crosses itself.
- Applying output colour conversion in the blend pass. Its result goes into another render target that stays in linear working space, so converting there and again on the final blit brightens the accumulation on every pass until the whole panel is white within a second.
- Calling `setSize` on the targets after a resize and rendering straight away. `setSize` reallocates the texture, so the history now points at undefined memory, and the first composited frame is garbage that then decays for a full second.
- Deriving the trail from raw pointer speed. The mark is what is being smeared, and it lags the cursor — so a cursor-driven trail starts before the mark moves and keeps growing after it has stopped.
- Smoothing the decay factor with a per-frame constant (`d += (target - d) * 0.1`). That converges twice as fast at 120Hz, so the same hand speed produces a visibly shorter trail on a high-refresh display.
- Disposing the scene graph and stopping there. Render targets belong to no scene, so nothing walks them — each holds a full-resolution half-float texture plus a framebuffer, and three of them at DPR 2 is tens of megabytes retained per unmount.

## Notes

- Guarded with `hasWebGL()`: where a context cannot be acquired the component renders a single static radial gradient at the configured hue instead of an empty canvas.
- The loop is gated on `useInView` plus `useVisibility`, so an off-screen or backgrounded instance costs no GPU time at all — which matters more here than elsewhere, because this effect pays for three full-resolution passes per frame.
- `resolutionScale` below 1 trades tail sharpness for fill rate. Because the trail is low-frequency by nature, 0.6 is close to free visually and cuts the post-processing cost to roughly a third.

## Definition of done

Move the pointer slowly across the panel and the marks stay crisp with no tail. Flick across it and a smooth curved tail follows the cluster, fading to nothing rather than to a faint permanent ghost. Stop moving and the tail retracts over about a third of a second, leaving the surface clean. Resize the container mid-gesture and no block of garbage appears. Scroll the panel out of view and GPU work stops; unmount and the WebGL context count in about:gpu drops.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Velocity-Deformed Cards

Scroll position says where the page is; scroll velocity says how hard the user is pushing it, and that is the input that gives a list a material. Cards skew and stretch along the direction of travel, trail behind by an amount proportional to speed, and ease back to rest when you stop — the ease-out being a property of the filter rather than a keyframe.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Cards skew, stretch and trail in proportion to scroll speed, then settle on their own with no easing curve anywhere.

- Category: scroll
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. Velocity comes from `useScrollVelocity`, which filters twice: a one-pole low-pass on the raw per-frame delta so wheel steps stop ringing, then a damped approach toward that filtered value. The second stage is what produces the settle — a step change in speed leaves the filter as a curve, so no easing is ever authored.
2. Both stages use `damp(current, target, smoothing, dt)`, where `smoothing` is the fraction of the gap left after one second. The deformation therefore looks identical on a 60 Hz laptop and a 144 Hz monitor, which the per-frame form (`v += (target - v) * 0.1`) does not.
3. The normalised velocity drives four values per card: trailing translate, skew, stretch along the travel axis, and a squash across it at half the stretch, so the card roughly preserves its area. Without the squash the deformation reads as a scaling bug rather than as inertia.
4. Each card scales its share by a `data-deform` depth. Identical depths make the grid move as one rigid sheet; varied depths make it bend, which is the entire difference between "the page is skewing" and "these cards have weight".
5. Every transform is composed into a string, rounded, and compared with what was written last frame. A stationary list therefore performs zero style writes — at rest all cards produce the same string, and the loop costs one comparison each.
6. Card elements are collected once per `children` change instead of per frame. A `querySelectorAll` inside a rAF loop is a forced style recalculation 60 times a second for a list that changed once.
7. Only `transform` is animated, so the work stays on the compositor. Velocity is held in a ref and never enters React state — a value that changes every frame must not cause a render.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `maxSkew = 5`
  Degrees at full velocity. Around 5 the cards read as flexing; past ~10 the text inside becomes visibly sheared and the effect turns into a distraction the user actively fights.
- `maxLag = 28`
  Pixels a card trails at full velocity. Enough to open a visible gap against the container edge, small enough that a card never appears to belong to a different row.
- `maxStretch = 0.14`
  Fractional stretch along the travel axis. Fourteen percent is at the edge of what reads as elastic rather than broken; the cross-axis squash is half of it, which keeps the area roughly constant.
- `reference = 1400`
  Pixels per second that count as full deflection. A firm trackpad flick peaks around 1200-1800 px/s, so a normal gesture uses most of the range without a hard flick pinning it.
- `smoothing = 0.0002`
  Fraction of the velocity gap left after one second — a settle of roughly a third of a second. Faster and the cards twitch on every wheel step; slower and they keep moving after the scrollbar has visibly stopped, which reads as lag rather than as weight.
- `per-card depth = 0.55 – 1`
  The spread used in the demo. Below about 0.4 a card barely participates and looks broken next to its neighbours; a uniform 1 removes the bend that makes the grid feel like fabric.

## API

```ts
function VelocityDeformCards(props: { children: ReactNode; maxSkew?: number; maxLag?: number; maxStretch?: number; reference?: number; smoothing?: number; scroller?: RefObject<HTMLElement | null>; className?: string }): JSX.Element
```

- `children: ReactNode`
  The grid contents. Elements carrying `data-deform` are the ones deformed.
- `maxSkew: number` — default `5`
  Degrees of skew at full velocity.
- `maxLag: number` — default `28`
  Pixels a card trails at full velocity.
- `maxStretch: number` — default `0.14`
  Stretch along the travel axis at full velocity.
- `reference: number` — default `1400`
  Velocity in px/s that counts as full deflection.
- `smoothing: number` — default `0.0002`
  Fraction of the velocity gap left after one second.
- `scroller: RefObject<HTMLElement | null>`
  Scroll container. Omit to auto-detect.
- `className: string`
  Merged onto the wrapper — the grid definition usually lives here.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function VelocityDeformCards({
  children,
  maxSkew = 5,
  maxLag = 28,
  maxStretch = 0.14,
  reference = 1400,
  smoothing = 0.0002,
  scroller,
  className,
}: VelocityDeformCardsProps) {
  const root = useRef<HTMLDivElement>(null);
  const cards = useRef<HTMLElement[]>([]);
  const written = useRef<string[]>([]);
  const lastVelocity = useRef('');
  const reduced = useReducedMotion();

  // The hook wants an element, not a ref, so the container is resolved once
  // after mount — `document.documentElement` is the window-scroll case and is
  // read through `scrollTop` there too, which is correct on every engine.
  const [host, setHost] = useState<HTMLElement | null>(null);
  useEffect(() => {
    const rootEl = root.current;
    if (!rootEl) return;
    setHost(scroller?.current ?? nearestScroller(rootEl));
  }, [scroller]);

  const velocity = useScrollVelocity({
    reference,
    smoothing,
    target: host === document.documentElement ? null : host,
  });

  // Cached rather than queried per frame: a `querySelectorAll` inside the rAF
  // loop is a forced style recalc 60 times a second for a list that changed
  // once.
  useEffect(() => {
    const rootEl = root.current;
    if (!rootEl) return;
    cards.current = Array.from(rootEl.querySelectorAll<HTMLElement>('[data-deform]'));
    written.current = cards.current.map(() => '');
  }, [children]);

  useRaf((_dt) => {
    const rootEl = root.current;
    if (!rootEl) return;

    if (reduced) {
      // One pass to clear, then nothing. The guard below keeps it to one pass.
      for (let i = 0; i < cards.current.length; i += 1) {
        if (written.current[i] === '') continue;
        written.current[i] = '';
        const card = cards.current[i];
        if (card) card.style.transform = '';
      }
      return;
    }

    // -1..1, already low-passed twice. Positive is scrolling down.
    const v = velocity.current.normalized;
    const magnitude = Math.abs(v);

    for (let i = 0; i < cards.current.length; i += 1) {
      const card = cards.current[i];
      if (!card) continue;

      // Per-card depth is the whole effect: identical values make the list
      // move as one rigid sheet, varied values make it bend like cloth.
      const raw = Number.parseFloat(card.dataset.deform ?? '');
      const depth = Number.isFinite(raw) ? raw : 1;

      const lag = -v * maxLag * depth;
      const skew = -v * maxSkew * depth;
      const stretch = 1 + magnitude * maxStretch * depth;
      // Squash across the travel axis by half the stretch: the card keeps
      // roughly its area, which is what stops the deformation reading as a
      // scaling bug.
      const squash = 1 - magnitude * maxStretch * depth * 0.5;

      const transform =
        `translate3d(0, ${lag.toFixed(2)}px, 0) ` +
        `skewY(${skew.toFixed(2)}deg) ` +
        `scale(${squash.toFixed(4)}, ${stretch.toFixed(4)})`;

      // At rest every card produces the same string as last frame, so an idle
      // list costs one comparison per card and zero style invalidations.
      if (written.current[i] === transform) continue;
      written.current[i] = transform;
      card.style.transform = transform;
    }

    // Published for anything that would rather react in CSS than in JS —
    // guarded, so a stationary list stops writing to the DOM entirely.
    const text = v.toFixed(3);
    if (text !== lastVelocity.current) {
      lastVelocity.current = text;
      rootEl.style.setProperty('--scroll-velocity', text);
    }
  });
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useRaf` unsubscribes from the shared loop on unmount, and `useScrollVelocity` does the same. There are no listeners, observers or timers to remove; the only state is refs and one element resolved after mount, and every transform is written on nodes React owns.

**Reduced motion.** When `prefers-reduced-motion: reduce` matches, one pass clears every transform and the loop then writes nothing at all. The cards keep their layout, spacing and hover states, so the grid is intact — it simply does not flex. Toggling the OS setting takes effect on the next frame without a reload.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Feeding raw `scrollY` deltas straight into the transform. A trackpad emits bursts and a mouse wheel emits steps, so the cards strobe instead of flexing — the two filter stages exist precisely for this.
- Smoothing with a per-frame constant. The settle is more than twice as fast on a 144 Hz display, and every tuning pass that fixes one refresh rate breaks the other.
- Stretching without squashing. The cards visibly gain area at speed, which the eye reads as a rendering fault rather than as elasticity.
- Giving every card the same depth. The whole grid then skews as one plane, which looks like the viewport is broken rather than like the cards have mass.
- Putting velocity in React state. That is a re-render per frame, and the reconciliation cost alone is enough to lower the frame rate that the velocity is measured against — the effect degrades itself.
- Writing transforms unconditionally. Idle frames still cost a style invalidation and a composite for each card, on a list where nothing moved.
- Querying the cards inside the loop. `querySelectorAll` per frame forces style resolution 60 times a second for a list whose contents changed once.
- Animating `top`, `margin` or `height` for the trail instead of `transform`. Every frame relayouts the whole grid, and the deformation becomes a slideshow on any laptop.

## Notes

- The scroll container is auto-detected by walking ancestors for a scrollable `overflow-y`; pass `scroller` when it is ambiguous. `useScrollVelocity` takes an element rather than a ref, so the container is resolved once after mount.
- The normalised velocity is also published as `--scroll-velocity` on the root, so a border colour or a blur can react in CSS without another JS subscriber.
- Set `will-change: transform` on the cards, not on the container: the container never moves, and promoting a large scrolling element wastes memory for nothing.

## Definition of done

A fast flick skews and stretches the cards in the direction of travel by different amounts per column, and they settle within about a third of a second after the scroll stops, with no overshoot. Text stays readable throughout. At rest, a paint-flashing or style-recalc profile shows no per-frame work. The settle takes the same wall-clock time at 60 and 144 Hz. With reduced motion on, nothing deforms.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Vertex Shader Cylinder Bend

The bend on its own, with no gallery attached. A flat `PlaneGeometry` is fed to a vertex shader that reads each vertex's x coordinate as an arc parameter and re-emits it on the surface of a cylinder. Because curvature is a uniform rather than a mesh, the same buffer is flat, bowed or nearly closed between two frames — no `CylinderGeometry`, no rebuild, no re-upload.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A flat plane wrapped around a cylinder on the GPU, with the curvature living in a uniform you can animate.

- Category: webgl
- Runtime cost: webgl
- Dependencies: three@^0.185.1

## How it works

1. Curl is defined as radians of bend per world unit of plane width, so the radius is its reciprocal: `radius = 1.0 / curl`. A 3-unit plane at curl 0.62 wraps 1.86 rad of a circle of radius 1.61, and the arc length is still exactly 3 units — the banner bends without appearing to shrink.
2. `angle = uSpin + position.x * curl`, then `pos.x = radius * sin(angle)` and `pos.z = radius * cos(angle) - radius`. The trailing `- radius` pins the arc's midpoint at z = 0 so tightening the curl bends the ends away instead of lunging the whole banner at the camera.
3. The vertical bow is `pos.y = sin(position.y * k) / k`, which tends to `position.y` as k tends to 0 and becomes a full sine bow at k = 1. Normalising by k is what keeps the plane the same height at every bow depth.
4. The surface normal is available in closed form: differentiating the position gives tangents `(cos a, 0, -sin a)` and `(0, 1, 0)`, whose cross product is `(sin a, 0, cos a)`. Its z component — `cos(angle)` — is how squarely the patch faces the camera, so the shading term costs one cosine and no `normalMatrix`.
5. On resize the camera is moved rather than the plane resized: `distance = max(width / fit / (2 tan(fov/2) aspect), height / fit / (2 tan(fov/2)))`. The plane's world width is the yardstick `curl` is measured in, so it must never change with the viewport.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `PLANE_WIDTH / PLANE_HEIGHT = 3 / 1.4`
  Fixed world units on purpose. Curl is radians per world unit, so a plane that resized with the viewport would bend through a different total angle on every device — the same `curl` prop would mean something different on a phone.
- `curl = 0.62`
  Times the 3-unit width, this is 1.86 rad — about 106 degrees of arc. Under ~0.25 the bend is indistinguishable from a perspective skew; over ~1.6 the far edges pass 90 degrees from the camera, present zero pixels of width, and the banner appears to have been cut off.
- `curlSwing = 0.22`
  Amplitude of the idle breathing. Large enough that the curvature is visibly a live value rather than a baked mesh; large enough to pass 1.6 total and the ends would clip away at the peak of every cycle.
- `barrel = 0.3`
  k in `sin(k*y)/k`. At 0 the top and bottom edges are dead straight and the surface reads as a rolled poster; past ~1.2 the bow overtakes the curl and the plane looks like a saddle rather than a cylinder.
- `segments = 96`
  Subdivisions across the bend — the resolution of the curve, since it is evaluated per vertex. Below ~24 the arc becomes a visible polyline and the shading term steps in bands; above ~192 the extra vertices land inside a single pixel.
- `PlaneGeometry y-segments = 16`
  The cylinder bend is a function of x alone, so rows would be pure waste — except the barrel bow, which needs enough rows to curve rather than kink at the midline.
- `FIT = 0.86`
  Fraction of the frustum the banner fills. At 1.0 the receding edges touch the viewport border and the curl has nowhere to read against; below ~0.7 the component is mostly empty space.
- `shade = 0.55`
  How far the facing term is allowed to darken the edges. At 0 the bend reads as a flat trapezoid — a perspective mistake rather than a curve. At 1 the edges go fully black and the banner appears to end early.

## API

```ts
function VertexCylinderBend(props: { curl?: number; curlSwing?: number; parallax?: number; barrel?: number; shade?: number; segments?: number; period?: number; paint?: (ctx: CanvasRenderingContext2D, size: { width: number; height: number }) => void; className?: string }): JSX.Element
```

- `curl: number` — default `0.62`
  Radians of bend per world unit of plane width. 0 is flat.
- `curlSwing: number` — default `0.22`
  Peak extra curl added by the idle breathing cycle.
- `parallax: number` — default `0.34`
  Radians the banner rocks around the drum axis at full pointer travel.
- `barrel: number` — default `0.3`
  Vertical bow. 0 leaves the edges straight, ~1 is a full sine.
- `shade: number` — default `0.55`
  How far the facing term darkens the receding edges.
- `segments: number` — default `96`
  Subdivisions across the bend. This is the resolution of the curve.
- `period: number` — default `9`
  Seconds per breathing cycle.
- `paint: (ctx, size) => void`
  Override the banner face. Receives a 2D context for a 1024x512 canvas.
- `className: string`
  Merged onto the wrapper via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function VertexCylinderBend({
  curl = 0.62,
  curlSwing = 0.22,
  parallax = 0.34,
  barrel = 0.3,
  shade = 0.55,
  segments = 96,
  period = 9,
  paint,
  className,
}: VertexCylinderBendProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);

  const { width, height } = useResizeObserver(host);
  const { inView } = useInView(host, { threshold: 0 });
  const visible = useVisibility();
  const reduced = useReducedMotion();
  const pointer = useSmoothPointer({ target: host, smoothing: 0.002 });

  const [supported, setSupported] = useState(true);
  useEffect(() => setSupported(hasWebGL()), []);

  const elapsed = useRef(0);
  const spin = useRef(0);
  const curlNow = useRef(curl);

  const live = useRef({ curl, curlSwing, parallax, barrel, shade, period });
  live.current = { curl, curlSwing, parallax, barrel, shade, period };

  const ready = width > 1 && height > 1 && supported;

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setSize(el.clientWidth, el.clientHeight, false);
    renderer.setClearColor(0x000000, 0);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';
    el.appendChild(renderer.domElement);

    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(CAMERA_FOV, 1, 0.1, 100);

    const canvas = document.createElement('canvas');
    canvas.width = TEXTURE_WIDTH;
    canvas.height = TEXTURE_HEIGHT;
    const ctx = canvas.getContext('2d');
    if (ctx) (paint ?? paintBanner)(ctx, { width: TEXTURE_WIDTH, height: TEXTURE_HEIGHT });

    const texture = new THREE.CanvasTexture(canvas);
    texture.colorSpace = THREE.SRGBColorSpace;
    texture.anisotropy = Math.min(4, renderer.capabilities.getMaxAnisotropy());

    const uniforms: BendUniforms = {
      uTexture: { value: texture },
      uCurl: { value: curl },
      uSpin: { value: 0 },
      uBarrel: { value: barrel },
      uShade: { value: shade },
    };

    // Segments only along x. The bend is a function of x alone, so vertical
    // subdivision buys nothing but vertices — except the barrel bow, which
    // needs a handful of rows to curve at all.
    const geometry = new THREE.PlaneGeometry(PLANE_WIDTH, PLANE_HEIGHT, segments, 16);
    const material = new THREE.ShaderMaterial({
      vertexShader: vertexCylinderBendVertexShader,
      fragmentShader: vertexCylinderBendFragmentShader,
      uniforms,
      transparent: true,
      // The bend turns the far edges away from the camera, so without
      // DoubleSide a hard curl punches holes through the ends of the banner.
      side: THREE.DoubleSide,
    });

    const mesh = new THREE.Mesh(geometry, material);
    // The CPU bounding sphere describes a flat plane that the shader has
    // already moved. Culling against it blanks the banner at shallow angles.
    mesh.frustumCulled = false;
    scene.add(mesh);

    stage.current = { renderer, scene, camera, geometry, material, texture, uniforms };

    return () => {
      stage.current = null;
      scene.remove(mesh);
      // The texture is inside `uniforms`, where disposeObject cannot see it.
      texture.dispose();
      disposeObject(scene);
      geometry.dispose();
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, segments, paint]);

  useEffect(() => {
    const current = stage.current;
    if (!current || width < 1 || height < 1) return;
    const aspect = width / height;
    current.renderer.setPixelRatio(pixelRatio());
    current.renderer.setSize(width, height, false);
    current.camera.aspect = aspect;

    // Contain-fit by moving the camera, not by resizing the plane: the plane's
    // world width is what `curl` is measured against, so it has to stay fixed.
    // Take the larger of the two required distances or the banner is cropped
    // on whichever axis is tighter.
    const tanHalf = Math.tan((CAMERA_FOV * Math.PI) / 360);
    const forWidth = PLANE_WIDTH / FIT / (2 * tanHalf * aspect);
    const forHeight = PLANE_HEIGHT / FIT / (2 * tanHalf);
    current.camera.position.z = Math.max(forWidth, forHeight);
    current.camera.updateProjectionMatrix();
  }, [width, height]);

  useRaf(
    (dt) => {
      const current = stage.current;
      if (!current) return;
      const { curl: base, curlSwing: swing, parallax: sway, barrel: bow, shade: dark, period: cycle } =
        live.current;

      elapsed.current += dt;

      // Breathing curl. The whole reason the bend lives in a uniform is that
      // it can move; holding it at one value hides the technique.
      const target = reduced ? base : base + swing * Math.sin((elapsed.current * Math.PI * 2) / Math.max(cycle, 0.5));
      curlNow.current = damp(curlNow.current, target, CURL_SMOOTHING, dt);

      // Pointer rocks the banner around the drum axis. This survives reduced
      // motion because it is a direct response to input, not autonomous motion.
      // ndcX, not nx: ndc is -1..1 about the centre, so the banner rocks
      // symmetrically. nx is 0..1, which would bias every rock to one side.
      const aim = pointer.current.active ? pointer.current.ndcX * sway : 0;
      spin.current = damp(spin.current, aim, SPIN_SMOOTHING, dt);

      current.uniforms.uCurl.value = curlNow.current;
      current.uniforms.uSpin.value = spin.current;
      current.uniforms.uBarrel.value = bow;
      current.uniforms.uShade.value = dark;
      current.renderer.render(current.scene, current.camera);
    },
    ready && inView && visible,
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the mesh from the scene, disposes the `CanvasTexture` explicitly (it lives inside `material.uniforms`, out of `disposeObject`'s reach), runs `disposeObject` over the scene, disposes the geometry and material, then `disposeRenderer` for `setAnimationLoop(null)` / `dispose()` / `forceContextLoss()`, and removes the canvas from the DOM. The stage ref is nulled first, so any frame already queued returns immediately instead of touching a lost context.

**Reduced motion.** The breathing cycle is dropped: `uCurl` holds at the `curl` prop and never oscillates, so nothing moves on its own. The pointer rock is kept, because it is a direct one-to-one response to the user's own input rather than autonomous motion, and removing it would leave a component that ignores the cursor entirely.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Dividing by `curl` without a guard. The flat case is curl 0, which is an infinite radius: `1.0 / 0.0` in GLSL yields infinity, every vertex becomes NaN, and the mesh vanishes with no error anywhere. The shader clamps to 0.0001 and approaches flat instead.
- Omitting the `- radius` term from `pos.z`. The arc is then centred on the cylinder's axis rather than on the origin, so raising the curl walks the entire banner toward the camera and it appears to lunge every time the curvature changes.
- Bowing with a bare `sin(position.y)`. That silently rescales the plane — a 1.4-tall plane becomes 1.29 tall — so animating the bow makes the banner pulse in size. Normalising by k (`sin(k*y)/k`) keeps the height fixed at every depth.
- Leaving `frustumCulled` on. The bounding sphere describes the flat plane the shader has already moved, so at a hard curl three decides the banner is off screen and blanks it while it is plainly in view.
- Keeping the default `FrontSide`. The bend turns the far edges past 90 degrees from the camera, and single-sided faces punch clean holes through the ends of the banner at high curl.
- Resizing the plane geometry to fit the container. `curl` is radians per world unit, so a viewport-sized plane bends through a different total angle on every device and the prop stops meaning anything. Move the camera instead — and fit on the larger of the two required distances, or the banner is cropped on whichever axis is tighter.
- Texturing it with a smooth gradient. The bend is then almost invisible, because there is no structure for the foreshortening to compress. Evenly spaced vertical rules bunch toward the receding edges and make the curvature legible.
- Calling `renderer.dispose()` and stopping there. That frees GPU objects but keeps the WebGL context; Chromium caps a renderer process at roughly 16 and silently kills the oldest. `disposeRenderer` calls `forceContextLoss`.

## Notes

- This is the primitive that `cylinder-gallery` instantiates nineteen times. Isolated here so the arc maths can be read without the layout, focus and picking code around it.
- The normal is derived analytically rather than by recomputing vertex normals on the CPU, so `geometry.computeVertexNormals()` is never called and the buffer stays untouched after upload.

## Definition of done

The banner is visibly a section of a cylinder, not a skewed rectangle: the vertical rules bunch together toward both ends and the ends are darker than the middle. Over about nine seconds the curvature tightens and relaxes and the banner never changes size while it does. Move the cursor left and right and the whole arc rocks around its axis, following with a slight lag. Resize the container from wide to narrow and the banner stays fully in frame with the same amount of bend. With `prefers-reduced-motion: reduce` the curvature is frozen but the cursor rock still works.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Web Audio Scheduling Kit

Two clocks, one job each. `AudioContext.currentTime` is a sample counter and never drifts, but it cannot wake you up; `setInterval` can wake you up, but only when the main thread is free. The scheduler runs a 90 ms timer whose only responsibility is to ask which beats fall inside the next 300 ms and hand each one an exact audio time. The timer can fire late, early, or twice in a row and the notes still land in the same place.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

A lookahead sequencer: a coarse timer queues beats onto the sample-accurate audio clock, so tempo never drifts.

- Category: primitive
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. `nextTime` holds the audio-clock time of the next unqueued beat, initialised to `ctx.currentTime + START_LEAD` when `start()` runs. Every timer tick loops `while (nextTime < ctx.currentTime + lookahead)`, calls `onBeat({ time: nextTime, beat, step, ctx })`, and advances `nextTime += 60 / bpm`.
2. The advance accumulates from the previous beat time, never from `ctx.currentTime`. Re-basing on the clock each pass folds the timer's jitter into the tempo, and a sequence that re-bases runs measurably sharp inside a minute.
3. It is a `while` and not an `if` because one tick may have to cover several beats — the timer was throttled, the tempo is faster than the interval, or the tab just came back to the foreground.
4. `scheduleTone` builds an oscillator and a gain node per beat, ramps `gain` from its peak to 0.001 over `decay`, stops the oscillator `TAIL` seconds after the ramp ends, and disconnects both nodes in `onended` so the graph does not accumulate dead nodes.
5. The visual step index comes from a second, independent pass: a rAF loop reads `ctx.currentTime` once per frame and pops every queued beat whose time has passed, so the highlighted step is the step you can hear rather than the step that was most recently queued 300 ms ago.
6. `phase` is derived in the same loop as `1 - (nextQueuedBeat.time - now) / secondsPerBeat`, clamped to 0-1, and written to a ref rather than to state — a playhead needs a value every frame and state would re-render the whole sequencer 60 times a second.
7. On `visibilitychange` to hidden the lookahead widens to 1.5s, because a hidden tab clamps `setInterval` to roughly one call per second and a 0.3s window would leave gaps of missed beats.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `intervalMs = 90`
  How often the scheduler wakes. It only has to beat the lookahead window, not the tempo — at 96 bpm a beat is 625 ms, so the timer gets about seven chances to queue each one. Dropping to ~10 ms burns main-thread time for nothing; going past ~250 ms leaves too few chances inside a 300 ms window.
- `lookahead = 0.3`
  Seconds queued in advance. Must exceed the worst-case gap between timer calls, which under main-thread contention is several times `intervalMs` — 0.3s over a 0.09s interval is a 3x margin. Larger windows make a tempo or pattern change take longer to take effect, because beats already queued cannot be un-queued.
- `HIDDEN_LOOKAHEAD = 1.5`
  Seconds queued while the tab is hidden. Chrome and Firefox clamp background timers to about one call per second, so the window has to be over 1s or the sequence develops audible holes; 1.5s leaves margin over the clamp.
- `START_LEAD = 0.08`
  Seconds before the first beat. Covers constructing the context, resuming it, and the first `drain()` — all of which happen inside the click handler. Scheduling the downbeat at exactly `currentTime` means its attack is already partly in the past.
- `SILENCE = 0.001`
  The ramp target, -60 dB. `exponentialRampToValueAtTime` is undefined at 0 and throws a RangeError; ramping to a literal 0 is the single most common Web Audio mistake.
- `TAIL = 0.05`
  Seconds between the end of the decay ramp and `osc.stop()`. Stopping exactly at the end of the ramp truncates the waveform mid-cycle, which is an audible click on a triangle or square wave.
- `gain default = 0.14`
  Peak per tone. Three simultaneous rows sum to 0.42, which leaves headroom for their overlapping tails; at 0.4 each the same chord clips the destination.

## API

```ts
function useWebAudioScheduler(options?: { bpm?: number; steps?: number; lookahead?: number; intervalMs?: number; onBeat?: (beat: { time: number; beat: number; step: number; ctx: AudioContext }) => void }): { start: () => void; stop: () => void; running: boolean; step: number | null; phase: RefObject<number> }
function scheduleTone(ctx: AudioContext, options: { frequency: number; at: number; gain?: number; decay?: number; type?: OscillatorType }): void
```

- `bpm: number` — default `96`
  Tempo. One beat is `60 / bpm` seconds on the audio clock.
- `steps: number` — default `8`
  Beats per bar. Only affects the wrapped `step` index handed to `onBeat`.
- `lookahead: number` — default `0.3`
  Seconds of beats queued in advance. Must exceed the worst-case timer gap.
- `intervalMs: number` — default `90`
  How often the scheduling timer runs. Independent of the tempo.
- `onBeat: (beat: ScheduledBeat) => void`
  Called once per beat, `lookahead` seconds early. Schedule audio against `beat.time`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** `exponentialRampToValueAtTime` is undefined at 0, so silence is -60 dB. */
const SILENCE = 0.001;
/** Seconds after the ramp before `stop()`, so the cut is inaudible. */
const TAIL = 0.05;
/** Seconds before the first beat, absorbing the cost of `start()` itself. */
const START_LEAD = 0.08;
/** Lookahead used while the tab is hidden, in seconds. */
const HIDDEN_LOOKAHEAD = 1.5;

interface QueuedBeat {
  time: number;
  step: number;
}

/**
 * One decaying tone, scheduled and self-disposing.
 *
 * The oscillator and its gain node disconnect themselves in `onended`. A
 * sequencer that omits that leaks two nodes per beat — at 120 bpm that is
 * 7200 dead nodes an hour, all still attached to the destination.
 */
export function scheduleTone(ctx: AudioContext, options: ToneOptions): void {
  const { frequency, at, gain = 0.14, decay = 0.28, type = 'triangle' } = options;

  const osc = ctx.createOscillator();
  const env = ctx.createGain();
  osc.type = type;
  osc.frequency.setValueAtTime(frequency, at);
  env.gain.setValueAtTime(gain, at);
  env.gain.exponentialRampToValueAtTime(SILENCE, at + decay);
  osc.connect(env);
  env.connect(ctx.destination);
  osc.start(at);
  osc.stop(at + decay + TAIL);
  osc.onended = () => {
    osc.disconnect();
    env.disconnect();
  };
}

export function useWebAudioScheduler(
  options: UseWebAudioSchedulerOptions = {},
): WebAudioScheduler {
  const { bpm = 96, steps = 8, lookahead = 0.3, intervalMs = 90 } = options;
  const reduced = useReducedMotion();

  const [running, setRunning] = useState(false);
  const [step, setStep] = useState<number | null>(null);
  const phase = useRef(0);

  const ctxRef = useRef<AudioContext | null>(null);
  const timer = useRef<number | null>(null);
  const queue = useRef<QueuedBeat[]>([]);
  /** Audio time of the next beat to be scheduled. */
  const nextTime = useRef(0);
  /** Monotonic beat counter, so `step` survives a change of `steps`. */
  const counter = useRef(0);
  /** Widened while the tab is hidden, where timers are clamped to ~1 Hz. */
  const window_ = useRef(lookahead);

  const config = useRef({ bpm, steps, lookahead, intervalMs, reduced, options });
  config.current = { bpm, steps, lookahead, intervalMs, reduced, options };

  /** Queue every beat that falls inside the lookahead window. */
  const drain = useCallback(() => {
    const ctx = ctxRef.current;
    if (!ctx) return;
    const cfg = config.current;
    const secondsPerBeat = 60 / cfg.bpm;
    const horizon = ctx.currentTime + window_.current;

    // A `while`, not an `if`: one call may have to cover several beats when the
    // timer was throttled, and a fast tempo can put two beats in one window.
    while (nextTime.current < horizon) {
      const beat = counter.current;
      const at = nextTime.current;
      const index = wrapIndex(beat, cfg.steps);

      cfg.options.onBeat?.({ time: at, beat, step: index, ctx });
      queue.current.push({ time: at, step: index });

      // Accumulate from the previous beat time, never from `currentTime`.
      // Re-basing on the clock each pass folds the timer's jitter into the
      // tempo and the sequence drifts sharp within a minute.
      nextTime.current = at + secondsPerBeat;
      counter.current = beat + 1;
    }
  }, []);

  const stop = useCallback(() => {
    if (timer.current !== null) {
      clearInterval(timer.current);
      timer.current = null;
    }
    queue.current.length = 0;
    phase.current = 0;
    setRunning(false);
    setStep(null);
  }, []);

  const start = useCallback(() => {
    if (timer.current !== null) return;
    const cfg = config.current;

    let ctx = ctxRef.current;
    if (!ctx) {
      // Built inside the gesture handler that called `start`. Anywhere else
      // and the autoplay policy hands back a suspended context whose notes
      // are dropped silently.
      ctx = new AudioContext();
      ctxRef.current = ctx;
    }
    if (ctx.state === 'suspended') void ctx.resume();

    counter.current = 0;
    queue.current.length = 0;
    window_.current = document.visibilityState === 'hidden' ? HIDDEN_LOOKAHEAD : cfg.lookahead;
    nextTime.current = ctx.currentTime + START_LEAD;

    setRunning(true);
    drain();
    timer.current = window.setInterval(drain, cfg.intervalMs);
  }, [drain]);

  // The visual clock. Reading `ctx.currentTime` once per frame and popping the
  // beats that have passed keeps the highlight on the note you can hear; a
  // separate rAF counter of its own would slide out of step over a few bars.
  useRaf(() => {
    const ctx = ctxRef.current;
    if (!ctx) return;
    const now = ctx.currentTime;
    const q = queue.current;

    let current: QueuedBeat | null = null;
    while (q.length > 0) {
      const head = q[0];
      if (head === undefined || head.time > now) break;
      q.shift();
      current = head;
    }
    if (current) setStep(current.step);

    if (config.current.reduced) {
      phase.current = 0;
      return;
    }
    const secondsPerBeat = 60 / config.current.bpm;
    const head = q[0];
    // Time until the next queued beat, turned into progress through this one.
    phase.current =
      head === undefined ? 0 : clamp(1 - (head.time - now) / secondsPerBeat, 0, 1);
  }, running);

  useEffect(() => {
    if (!running) return;
    // A hidden tab clamps `setInterval` to roughly one call per second, so a
    // 0.3s window drops entire bars. Widening the window instead of stopping
    // means the bar plays through unbroken while the tab is in the background.
    const onVisibility = () => {
      window_.current =
        document.visibilityState === 'hidden' ? HIDDEN_LOOKAHEAD : config.current.lookahead;
      drain();
    };
    document.addEventListener('visibilitychange', onVisibility);
    return () => document.removeEventListener('visibilitychange', onVisibility);
  }, [running, drain]);

  useEffect(
    () => () => {
      if (timer.current !== null) clearInterval(timer.current);
      timer.current = null;
      queue.current.length = 0;
      const ctx = ctxRef.current;
      ctxRef.current = null;
      // close() cancels every note already scheduled in the future. Without
      // it a bar keeps playing after the component has gone.
      if (ctx && ctx.state !== 'closed') void ctx.close();
    },
    [],
  );
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The unmount cleanup clears the scheduling interval, empties the pending-beat queue, and calls `ctx.close()`, which cancels every note already committed to the audio thread. The `visibilitychange` listener is removed with its effect, and the rAF subscription is released by `useRaf` when `running` goes false. Each tone disconnects its own oscillator and gain node in `onended`.

**Reduced motion.** `step` still advances — a step index is information about the sound, not decoration — but `phase` is pinned to 0, so a playhead bound to it jumps from step to step in place of sliding continuously between them. The demo's playhead therefore renders as a static line on the current step.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Driving the sequence with one `setTimeout` per note. Every note then inherits main-thread jitter, and a single 80 ms layout pass puts that note 80 ms off the beat — clearly audible at any tempo.
- Advancing the beat time from `ctx.currentTime` instead of from the previous beat time. The timer never fires exactly on schedule, so each re-base rounds the interval down and the tempo creeps upward; a sequence started against a metronome is noticeably ahead within a minute.
- Using `if` instead of `while` in the drain. When the tab returns to the foreground, or the tempo is faster than the timer interval, one tick has several beats to queue — an `if` queues one and silently drops the rest.
- Setting the lookahead smaller than the worst-case timer gap. The window is the entire safety margin: at a 0.05s lookahead a single long frame means the beat is already in the past when the timer finally runs, and `osc.start(pastTime)` plays immediately, so the note is late *and* off-grid.
- Constructing the `AudioContext` at mount. The autoplay policy hands back a `suspended` context, `osc.start(at)` neither throws nor sounds, and the failure looks like a silent bug with a clean console.
- Ramping the gain to 0. `exponentialRampToValueAtTime(0, t)` throws — the target must be strictly positive.
- Leaving each beat's oscillator and gain connected. At 120 bpm that is two dead nodes a beat, 7200 an hour, all still attached to the destination; CPU climbs and the output eventually distorts.
- Counting the visual step with its own rAF counter rather than reading `ctx.currentTime`. The two clocks tick at different rates, so the highlight slides out of step with the sound over a few bars — the classic "my metronome light is not on the beat" bug.
- Highlighting the step at the moment it was *queued*. That is `lookahead` seconds before it sounds, so the playhead runs a third of a second ahead of the audio and looks broken.
- Publishing the beat phase as React state. Sixty re-renders a second of the whole sequencer to move one line; a ref plus a rAF write to a CSS custom property costs nothing.
- Never calling `ctx.close()`. Notes already queued keep playing after the component unmounts, and Chrome throws once about six contexts exist in one document.

## Notes

- A change to the pattern takes effect at most `lookahead` seconds later, because beats inside the window are already committed to the audio thread. That is inherent to lookahead scheduling, not a defect — shrink the window if you need a tighter response and accept the reduced timing margin.
- `onBeat` receives the context so the caller schedules its own nodes; the hook deliberately does not own the sound. Sequencing and synthesis are separate concerns and pairing them makes both untestable.
- For sub-millisecond scheduling with no main-thread involvement at all, the same shape moves into an `AudioWorklet` that posts beat messages. The lookahead pattern is identical; only the timer changes.

## Definition of done

Press Play: the highlight lands on a cell at the same instant you hear that cell, and stays in step after a minute of playing. Toggle a cell while it runs and the change is audible on the next pass. Switch to another tab for ten seconds and come back — the pattern is still on the grid with no gap or double-trigger. Press Stop and the step counter clears with no trailing note. Unmount while playing and nothing keeps sounding. With reduced motion on, the playhead line sits still on the current step instead of sweeping.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Wheel Accumulator Stepper

`wheel` is four input devices wearing one event name. A mouse notch is a single event carrying 100 units; a trackpad swipe is forty events of four units each, followed by a synthesised momentum tail that keeps arriving for about a second after the fingers lift; and `deltaMode` decides whether those numbers are pixels, lines, or whole pages. This hook scales the delta by `deltaMode`, sums it, and emits one step per 90 normalised pixels — then latches, and re-arms only when the incoming magnitude stops decaying, which is the one signal that separates a fresh flick from the tail of the last one.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Wheel input normalised by deltaMode and accumulated to a threshold, so one flick of any device moves exactly one step.

- Category: primitive
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. `wheelDelta(e, axis)` picks the axis — `Math.abs(deltaX) > Math.abs(deltaY) ? deltaX : deltaY` for `both`, so a sideways two-finger swipe and a mouse wheel drive the same widget — then multiplies by the scale `deltaMode` implies: 1 for pixel mode, 40 for line mode, 800 for page mode. Everything downstream counts pixels.
2. A signed accumulator sums the normalised deltas. While `Math.abs(units) >= step` it subtracts one signed `step` and calls `onStep(direction, detail)`, capped at `maxPerEvent` iterations. One mouse notch (100 units) clears the 90-unit threshold on its own; a trackpad swipe clears it after roughly a dozen events. No device detection anywhere.
3. After any step the accumulator is zeroed rather than left holding the remainder, and a latch closes. `peak` records the magnitude of the event that fired the step.
4. While latched, an event whose magnitude is below `peak` is absorbed: no accumulation, no step, but `preventDefault` still runs so the page does not scroll underneath the widget. The first event whose magnitude reaches `peak` re-arms. macOS momentum is monotonically decreasing, so a tail can never reach its own peak and is swallowed entirely; the next notch of a mouse wheel has an identical magnitude and re-arms immediately; a second deliberate flick exceeds it on its first event.
5. Two further resets bypass the latch: a gap greater than `gestureGapMs` since the previous accepted event, which means the gesture and its tail are finished, and a change of sign, since no momentum tail reverses direction.
6. `e.ctrlKey` events return before `preventDefault` and before accumulation — that combination is pinch-zoom on a trackpad and page zoom on a mouse, and swallowing it removes the only way to enlarge the page.
7. The listener is registered `{ passive: !preventDefault }`, so it is non-passive exactly when it intends to cancel. The live accumulator is exposed as a `RefObject`, not state, so a gauge can read it every frame without re-rendering the widget forty times per swipe.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `STEP = 90`
  Normalised pixels per step. It has to sit below one mouse notch so a single notch always moves exactly one item — Chrome reports 100 per notch and legacy browsers 120, so anything above 100 makes a mouse feel broken. Going much below ~60 puts it inside the range of a small trackpad twitch and the widget steps when the user meant to scroll past it.
- `LINE_UNITS = 40`
  Pixels assumed per line for `deltaMode === 1`. Firefox reports line mode on several platforms, where `deltaY` is typically 3 — 3 x 40 = 120 units, which matches what the same physical notch reports as pixels in Chrome. Using 1 here (i.e. not normalising at all) makes the stepper need thirty notches per step in Firefox and one in Chrome.
- `PAGE_UNITS = 800`
  Pixels assumed per page for `deltaMode === 2`. Roughly one viewport. The exact figure barely matters because any page-mode event is far past the threshold; what matters is that it is not 1, which would make a full-page wheel event register as almost no movement.
- `GESTURE_GAP_MS = 140`
  Silence that ends a gesture. Momentum tail events arrive at frame rate, so ~8-17 ms apart; sustained finger input is similar. 140 ms is far above both and far below the ~250 ms a person needs to lift, reposition, and flick again, so it never splits one gesture in two and never merges two.
- `MAX_PER_EVENT = 1`
  Steps emitted from a single event. One event should mean at most one step, and with the latch in place the only thing this guards is a single enormous delta — a page-mode wheel worth 800 units, or a synthetic event from an automation script, either of which would otherwise advance eight items in one frame. Raise it to 2 or 3 if a violent flick should travel further; the demo keeps it at 1.

## API

```ts
function useWheelStepper(ref: RefObject<HTMLElement | null>, options: { step?: number; axis?: 'both' | 'x' | 'y'; maxPerEvent?: number; gestureGapMs?: number; preventDefault?: boolean; enabled?: boolean; onStep: (direction: 1 | -1, detail: { index: number; delta: number; deltaMode: number; event: WheelEvent }) => void }): { units: RefObject<number>; latched: RefObject<boolean> }
function wheelDelta(e: WheelEvent, axis?: 'both' | 'x' | 'y'): number
function wheelUnitScale(deltaMode: number): number
```

- `step: number` — default `90`
  Normalised pixels of travel per emitted step. Must stay below one mouse notch (100).
- `axis: 'both' | 'x' | 'y'` — default `'both'`
  `both` uses whichever of `deltaX` / `deltaY` dominates, so horizontal and vertical input both work.
- `maxPerEvent: number` — default `1`
  Ceiling on steps emitted from one event. Guards a single page-mode delta worth 800 units.
- `gestureGapMs: number` — default `140`
  Silence that ends the gesture and clears the latch. Above frame interval, below a human reflick.
- `preventDefault: boolean` — default `true`
  Cancel the page scroll on every accepted event. Also decides whether the listener is passive.
- `enabled: boolean` — default `true`
  Detaches the listener when false — for a widget that only owns the wheel while open.
- `onStep: (direction: 1 | -1, detail: WheelStepDetail) => void`
  Called once per step, synchronously in the wheel handler. `+1` is down or right.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** Normalised pixels per step. */
const STEP = 90;
/** Pixels per line for `deltaMode === 1`. */
const LINE_UNITS = 40;
/** Pixels per page for `deltaMode === 2`. */
const PAGE_UNITS = 800;
/** Milliseconds of silence that end a gesture. */
const GESTURE_GAP_MS = 140;
/** Steps allowed out of one event. */
const MAX_PER_EVENT = 1;

/** The pixel scale implied by `deltaMode`. Unknown modes are treated as pixels. */
export function wheelUnitScale(deltaMode: number): number {
  if (deltaMode === 1) return LINE_UNITS;
  if (deltaMode === 2) return PAGE_UNITS;
  return 1;
}

/**
 * One wheel event as normalised pixels on the chosen axis.
 *
 * `'both'` takes whichever axis dominates, so a two-finger sideways swipe and
 * a mouse wheel drive the same widget and the user never has to discover
 * which axis it wanted.
 */
export function wheelDelta(e: WheelEvent, axis: WheelAxis = 'both'): number {
  const raw =
    axis === 'x'
      ? e.deltaX
      : axis === 'y'
        ? e.deltaY
        : Math.abs(e.deltaX) > Math.abs(e.deltaY)
          ? e.deltaX
          : e.deltaY;
  return raw * wheelUnitScale(e.deltaMode);
}

/**
 * Turn continuous wheel input into discrete steps, one per physical gesture.
 *
 * Attaches to `ref`, so the widget owns the wheel only while the pointer is
 * over it. Nothing is published as state: `onStep` fires on the event and the
 * live accumulator is a ref.
 */
export function useWheelStepper(
  ref: RefObject<HTMLElement | null>,
  options: UseWheelStepperOptions,
): WheelStepperState {
  const {
    step = STEP,
    axis = 'both',
    maxPerEvent = MAX_PER_EVENT,
    gestureGapMs = GESTURE_GAP_MS,
    preventDefault = true,
    enabled = true,
  } = options;

  const reduced = useReducedMotion();

  const units = useRef(0);
  const latched = useRef(false);

  const config = useRef({ step, axis, maxPerEvent, gestureGapMs, reduced, options });
  config.current = { step, axis, maxPerEvent, gestureGapMs, reduced, options };

  useEffect(() => {
    const el = ref.current;
    if (!el || !enabled) return;

    /** `timeStamp` of the previous accepted event, for the gesture gap. */
    let lastTime = 0;
    /** Largest magnitude seen since the latch closed. */
    let peak = 0;

    const onWheel = (e: WheelEvent) => {
      // ctrl+wheel is pinch-zoom on a trackpad and page zoom on a mouse.
      // Swallowing it takes away the user's only way to enlarge the page, so
      // it is passed through untouched — no preventDefault, no accumulation.
      if (e.ctrlKey) return;

      const cfg = config.current;
      const delta = wheelDelta(e, cfg.axis);
      // A pure cross-axis event on a single-axis widget, or the zero-delta
      // event some drivers emit at the end of a gesture. Neither is input.
      if (delta === 0) return;

      // Before the latch check, not after: while the widget is absorbing a
      // momentum tail the page must not scroll underneath it instead.
      if (preventDefault) e.preventDefault();

      const magnitude = Math.abs(delta);
      const gap = e.timeStamp - lastTime;
      lastTime = e.timeStamp;

      // Silence long enough to outlast a momentum tail's frame interval means
      // the previous gesture is over in every sense. Start clean.
      if (gap > cfg.gestureGapMs) {
        units.current = 0;
        latched.current = false;
      }

      // A reversal is always deliberate — no momentum tail changes sign — so
      // it clears both the latch and any units banked in the other direction.
      if (units.current !== 0 && Math.sign(delta) !== Math.sign(units.current)) {
        units.current = 0;
        latched.current = false;
      }

      if (latched.current) {
        // The whole technique. A tail decays, so it never reaches the peak it
        // had when the step fired; a new flick or the next wheel notch does,
        // on its first event. Magnitude alone cannot tell them apart and a
        // fixed cooldown either eats the second flick or leaks the tail.
        if (magnitude < peak) return;
        latched.current = false;
      }

      units.current += delta;

      // Reduced motion caps the burst at one step regardless of the option:
      // travelling several items from one flick is the motion-heavy part.
      const limit = cfg.reduced ? 1 : Math.max(1, cfg.maxPerEvent);
      let fired = 0;

      while (Math.abs(units.current) >= cfg.step && fired < limit) {
        const direction: 1 | -1 = units.current > 0 ? 1 : -1;
        units.current -= cfg.step * direction;
        cfg.options.onStep(direction, {
          index: fired,
          delta,
          deltaMode: e.deltaMode,
          event: e,
        });
        fired += 1;
      }

      if (fired > 0) {
        // Zeroed, not left with the remainder: a flick's overshoot belongs to
        // the flick that is now finished, and banking it means the next
        // gesture starts part-way to a step and fires early.
        units.current = 0;
        latched.current = true;
        peak = magnitude;
      }
    };

    // Non-passive only when it actually calls preventDefault. Registering
    // non-passive unconditionally opts the element out of the scrolling fast
    // path for nothing; calling preventDefault inside a passive listener is
    // ignored with a console error, which is the same bug from the other end.
    el.addEventListener('wheel', onWheel, { passive: !preventDefault });
    return () => {
      el.removeEventListener('wheel', onWheel);
      units.current = 0;
      latched.current = false;
    };
  }, [ref, enabled, preventDefault]);
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** The effect removes the `wheel` listener with the same capture flag it was added with, and zeroes both the accumulator and the latch so a remount does not inherit half a gesture. There is no timer, no rAF, and no pointer capture to release. Re-running under React 19 StrictMode is harmless: the second effect attaches a second listener only after the first has removed its own.

**Reduced motion.** Steps still fire — a step is the user's input, not decoration, and suppressing it would leave the widget unresponsive. What changes is the burst: the per-event step count is clamped to 1 regardless of `maxPerEvent`, so a violent flick advances one item instead of travelling several in a single frame. Whatever the consumer animates in response to a step is where a reduced-motion transition belongs.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Reading `deltaY` without reading `deltaMode`. The same physical notch is `deltaY: 100` in pixel mode and `deltaY: 3` in line mode, so a threshold tuned in Chrome needs about thirty notches per step in a line-mode browser. The bug never reproduces on the developer's machine.
- Stepping on every wheel event. A trackpad emits thirty to forty events per swipe, so a carousel jumps thirty slides for one gesture — the single most common wheel bug and the reason the accumulator exists at all.
- Accumulating with no latch. The accumulator fixes the burst but not the tail: macOS keeps synthesising decaying wheel events for about a second after the fingers lift, and a hard flick has enough left in that tail for three or four more thresholds. The carousel takes one step under your fingers and then keeps going on its own.
- Latching with a fixed cooldown instead. A cooldown long enough to outlast the tail (roughly 600-1000 ms) also eats the second of two deliberate flicks, so the widget feels dead when hurried; a cooldown short enough to keep double flicks alive lets the loud part of the tail through. Decay is the only signal that separates the two cases.
- Comparing each tail event against the previous event rather than against the peak. Tail magnitudes jitter, so `39 >= 38` looks like new input and re-arms mid-tail, which is exactly the extra step the latch was added to prevent. Comparing against the peak since the latch closed cannot be fooled by jitter.
- Carrying the leftover units past a step. Zeroing looks lossy but is correct: the overshoot belongs to the gesture that just ended, and banking 80 of 90 units means the next flick fires after a single event of travel.
- Skipping `preventDefault` while the latch is absorbing the tail. The widget correctly refuses to step, and the page scrolls instead — so the carousel holds still and the whole section slides away underneath it.
- Registering the listener non-passive when it never cancels. That opts the element out of the browser's scrolling fast path for nothing. The mirror-image bug is calling `preventDefault` inside a passive listener, where it is silently ignored with a console error and the page scrolls anyway.
- Swallowing `ctrl`+wheel. That is pinch-zoom on every trackpad and page zoom on every mouse; intercepting it means a low-vision user cannot enlarge the page while the pointer is anywhere over the widget.
- Publishing the accumulator as React state. Forty state updates per swipe re-render the whole widget to move a 40 px gauge; a ref plus one CSS custom property write costs nothing and cannot tear.
- Attaching to `window` instead of the element. The widget then steps while the pointer is somewhere else entirely, and a non-passive window-level wheel listener degrades scrolling for the whole document.

## Notes

- The latch makes one gesture mean one step, which is right for a carousel, a chapter list, or anything with discrete positions. For a continuous value — a zoom level, a scrub position — drop the latch and use the normalised delta directly; the `deltaMode` scaling is the part you still need.
- `onStep` is called synchronously inside the wheel handler, so it runs before the frame that would have scrolled. Keep it to a state update or a ref write; layout reads there cost a forced synchronous reflow on every notch.
- A trackpad in a browser that supports it will also fire `gesturestart` / `gesturechange` for pinch, which is a separate event stream. This hook deliberately ignores it rather than trying to reconstruct pinch from `ctrl`+wheel.

## Definition of done

Wheel over the panel with a mouse: every notch moves exactly one item, and a fast spin moves one per notch with no skipping. Flick hard on a trackpad and let go: the index advances exactly once and then holds still while the readout shows the tail arriving and being absorbed. Flick twice in quick succession and it advances twice. Push slowly and continuously and the gauge fills to the threshold before each step, so the accumulation is visible. Reverse direction mid-gesture and it steps back without first having to unwind the units already banked. Hold ctrl and wheel: the browser zooms, and the index does not move. Scroll the outer page with the pointer just outside the panel and the panel ignores it.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Shortest Signed Ring Offset

A ring of items laid out from `wrappedOffset(i, position, count)` — the shortest signed distance around the circle — with the naive `i - position` printed beside each one so the two can be compared while the ring turns. The dots move continuously through the seam; the raw numbers leap by a whole count at it. This is the single function that makes a finite array behave like an infinite one, and the only honest way to teach it is to show the version it replaces failing.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

Ten dots on a ring, each showing its wrapped offset and the raw index difference it replaces.

- Category: primitive
- Runtime cost: dom
- Dependencies: none beyond React

## How it works

1. `wrappedOffset(i, position, count)` computes `mod(i - position, count)` and then subtracts `count` when the result exceeds `count / 2`, producing a signed distance in `(-count/2, count/2]`. Negative means the item is behind the read head.
2. Each item is placed at `angle = (offset / count) * 2PI - PI/2`, so offset 0 sits under the notch at twelve o'clock and the ring is symmetric about it. Because a ±count jump in the offset is exactly one full turn, the dot lands on the same pixel and the seam is invisible.
3. Focus is `gaussian(|offset|, 0.45)` — `exp(-(0.45·d)²)` — driving scale from 0.74 to 1.20 and opacity from 0.30 to 1.00. A continuous falloff with no thresholds is what makes the ring read as analogue rather than stepped.
4. Dragging converts the pointer to an angle about the ring centre with `atan2`, then advances the target position by `shortestAngle(previous, current) / 2PI * count`. `shortestAngle` is required here for the same reason `wrappedOffset` is required for the layout: `atan2` flips from +PI to -PI at nine o'clock.
5. The ring position is eased with `damp(position, target, 0.0015, dt)` on the shared rAF loop, and every frame writes only `transform`, `opacity` and `z-index` — no layout reads, because width and height come from a ResizeObserver rather than `clientWidth`.
6. React re-renders only when `wrapIndex(Math.round(position), count)` changes, which is a couple of times a second; the sixty-times-a-second work is plain style writes on refs.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `count = 10`
  Items on the ring, and therefore the wrap threshold at count / 2 = 5. Ten keeps every raw label at most two characters wide, so the pills fit on a 320 px preview without colliding; above ~16 the labels overlap tangentially and the comparison becomes unreadable.
- `FOCUS_FALLOFF = 0.45`
  Gaussian falloff on |offset|. Yields 1.00 / 0.82 / 0.44 / 0.16 / 0.04 at distances 0-4, so roughly four items read as "near" on a ten-item ring. At 1.0 only the centre item is lit and the ring looks broken; at 0.2 nothing falls off and there is no focus at all.
- `SMOOTHING = 0.0015`
  Fraction of the remaining gap left after one second. Fast enough that the ring feels attached to the pointer, slow enough that releasing mid-drag reads as momentum rather than a cut. This is `damp`'s smoothing argument, not a per-frame lerp constant — a per-frame constant converges twice as fast at 120 Hz.
- `RADIUS_RATIO = 0.36`
  Ring radius as a fraction of the shorter container side. Above ~0.42 the 36 px pills clip the edges of a 16:10 frame; below ~0.30 adjacent pills touch.
- `IDLE_DRIFT = 0.22`
  Ring positions per second before the first interaction, so the seam sweeps past roughly every 45 s and the component demonstrates itself without being touched. Faster than ~0.6 and the raw labels change too quickly to read.
- `threshold (useDrag) = 3`
  Pixels of travel before a press becomes a rotation. Lower than the 8 px a carousel wants, because this ring has no click target to protect — it only has to reject hand tremor.

## API

```ts
function WrappedRingOffset(props: { count?: number; drift?: number; className?: string }): JSX.Element
```

- `count: number` — default `10`
  Items on the ring. The wrap threshold is count / 2.
- `drift: number` — default `0.22`
  Ring positions per second before the first interaction. 0 to sit still.
- `className: string`
  Merged onto the outer element via `cn`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
/** Fraction of the gap to the target that survives one second. */
const SMOOTHING = 0.0015;
/** Gaussian falloff on |offset|. At 0.45: 1.00 / 0.82 / 0.44 / 0.16 / 0.04. */
const FOCUS_FALLOFF = 0.45;
const RADIUS_RATIO = 0.36;
const IDLE_DRIFT = 0.22;

export function WrappedRingOffset({
  count = 10,
  drift = IDLE_DRIFT,
  className,
}: WrappedRingOffsetProps) {
  const root = useRef<HTMLDivElement>(null);
  const nodes = useRef<(HTMLLIElement | null)[]>([]);

  /** Where the ring is being pulled to. Fractional and unbounded. */
  const target = useRef(0);
  /** Where the ring actually is. Eased toward `target`. */
  const position = useRef(0);
  /** Suppresses the idle drift once a human has touched it. */
  const engaged = useRef(false);
  const grabAngle = useRef(0);
  const shown = useRef(0);

  const [index, setIndex] = useState(0);
  const reduced = useReducedMotion();
  const { width, height } = useResizeObserver(root);

  /** Pointer angle around the ring centre, measured fresh: the page scrolls. */
  const angleAt = useCallback((clientX: number, clientY: number) => {
    const box = root.current?.getBoundingClientRect();
    if (!box) return 0;
    return Math.atan2(clientY - (box.top + box.height / 2), clientX - (box.left + box.width / 2));
  }, []);

  useDrag(root, {
    threshold: 3,
    onDragStart: (s) => {
      engaged.current = true;
      grabAngle.current = angleAt(s.clientX, s.clientY);
    },
    onDrag: (s) => {
      const angle = angleAt(s.clientX, s.clientY);
      // shortestAngle, not `angle - grabAngle`: atan2 flips from +PI to -PI at
      // nine o'clock, and the raw difference there is a full turn of garbage
      // that spins the ring backwards every time the pointer crosses it.
      const step = (shortestAngle(grabAngle.current, angle) / TAU) * count;
      target.current -= step;
      grabAngle.current = angle;
    },
  });

  useRaf((dt) => {
    if (!engaged.current && !reduced) target.current += drift * dt;

    // Reduced motion still moves the ring — it just does not ease into place.
    position.current = reduced
      ? target.current
      : damp(position.current, target.current, SMOOTHING, dt);

    const p = position.current;
    const radius = Math.min(width, height) * RADIUS_RATIO;

    for (let i = 0; i < count; i++) {
      const el = nodes.current[i];
      if (!el) continue;

      // The one line the whole component exists to demonstrate. `offset` is
      // continuous in `p` even across the seam, because the ±count jump maps
      // to exactly one turn of the circle and lands on the same place.
      const offset = wrappedOffset(i, p, count);
      const angle = (offset / count) * TAU - Math.PI / 2;
      const focus = gaussian(Math.abs(offset), FOCUS_FALLOFF);

      const x = Math.cos(angle) * radius;
      const y = Math.sin(angle) * radius;
      // translate3d places the box origin, translate(-50%,-50%) re-centres it,
      // scale runs about that centre. One string, one composited property.
      el.style.transform = `translate3d(${x.toFixed(2)}px, ${y.toFixed(2)}px, 0) translate(-50%, -50%) scale(${(0.74 + focus * 0.46).toFixed(3)})`;
      el.style.opacity = (0.3 + focus * 0.7).toFixed(3);
      el.style.zIndex = String(10 + Math.round(focus * 40));
    }

    // Labels are integers, so they only need a render when the rounded ring
    // position changes — a couple of times a second, not sixty.
    const next = wrapIndex(Math.round(p), count);
    if (next !== shown.current) {
      shown.current = next;
      setIndex(next);
    }
  });
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** `useDrag` removes its five pointer listeners and releases any outstanding pointer capture; `useRaf` unsubscribes and cancels the shared frame when it was the last subscriber; `useResizeObserver` unobserves the root. No transforms are left behind because the nodes unmount with the component.

**Reduced motion.** The idle drift never starts and the `damp` easing is bypassed, so the ring tracks the drag one-to-one and stops dead on release. Dragging and the arrow keys still work, and the labels still update — the maths is the content here, so removing it would remove the component.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Using `i - position` for layout. The ring still turns, but item 0 renders nine slots away from item 9 instead of one slot back, so the last item snaps across the entire ring every time the position passes zero. That snap is the seam, and it is the whole reason this function exists.
- Using `%` instead of a true modulo. JavaScript's `%` returns a negative result for negative operands, so scrolling backwards past zero produces offsets outside `[0, count)` and half the ring inverts. `mod(n, m) = ((n % m) + m) % m` is the fix.
- Comparing `offset > count / 2` with `>=`. On an even count that puts the antipodal item at `-count/2` instead of `+count/2`, and the item directly opposite the read head flickers between the two on alternate frames.
- Taking `angle - previousAngle` when converting pointer motion to rotation. `atan2` wraps from +PI to -PI at nine o'clock, so the raw difference there is a full turn and the ring spins backwards once per lap. `shortestAngle` wraps the difference into `(-PI, PI]`.
- Reading `element.clientWidth` inside the rAF callback to compute the radius. The same loop has already written transforms, so every read forces a synchronous reflow — sixty per second, and it only shows up as jank once there are a few of these on a page. The size comes from a ResizeObserver instead.
- Driving the per-item transforms through React state. Sixty commits a second for ten nodes is an order of magnitude more work than writing `style.transform` on refs, and it makes the labels — which change twice a second — re-render at frame rate for nothing.

## Notes

- `wrappedOffset` is the same three lines behind an infinite marquee, a drum carousel, a cylinder of image planes, and any "closest N to the playhead" query. Pair it with a scroll library set to `infinite: true` and the sequence has no beginning and no end.
- The idle drift stops permanently at the first drag or arrow key. An ambient motion that resumes on top of a user's input reads as the component fighting them.

## Definition of done

Leave it alone: the ring drifts and, as each item passes the six o'clock antipode, its struck-through raw label flips sign by the full count while the dot itself does not move. Drag the ring in a full circle past nine o'clock and it keeps turning in the same direction. Press ArrowRight and the position readout increments by one. Resize the frame and the ring re-radiuses without the dots drifting off-centre.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.


---

# Build: Wrapping Drum Carousel

Cards sit stacked at the centre of the stage and are pushed outward by their signed distance from a fractional carousel position. That distance is wrapped into a ring, so the sequence has no first or last card and the position variable can drift forever. The drum reads as three-dimensional but every transform is flat: `rotationY` and `z` are pinned to zero on purpose.

Build this as a React component in my project. Match my existing conventions —
file layout, styling system, and naming — rather than the ones implied below.
Everything after this line is specification, not code to copy verbatim.

## What it does

An endless carousel that reads as a rotating drum with no 3D at all — only x, scale and fading opacity.

- Category: layout
- Runtime cost: dom
- Dependencies: gsap@^3.15.0

## How it works

1. `gsap.utils.wrap(-count / 2, count / 2)` turns `i - pos` into a signed ring offset in `(-count/2, count/2]`. For six cards at `pos = 0`, card 5 resolves to `-1` and renders one slot to the *left* of centre instead of five slots right — this single call is what makes a finite array behave like an endless one.
2. Horizontal placement is `x = offset * step` where `step = min(spacingRatio * stage.clientWidth, maxSpacing)`. Spacing is measured off the stage element, not `window.innerWidth`, so a preview in a grid cell lays out correctly when the grid reflows rather than only when the viewport does.
3. Depth is faked by two curves with deliberately different clamps: `scale = 1 - scaleFalloff * min(distance, 1)` bottoms out one slot from centre, while `autoAlpha = clamp(0, 1, 1.15 - 0.75 * distance)` keeps falling and reaches zero at distance 1.533. Cards therefore fade out *before* they shrink far enough to look wrong, which reads as recession into fog rather than into a vanishing point.
4. `rotationY: 0` and `z: 0` are written on every `gsap.set`. They are not decoration — they stop an ancestor `perspective` or `transform-style: preserve-3d` from turning a deliberately flat drum into a half-broken 3D one that skews at the edges.
5. `zIndex = 100 - round(10 * distance)` is stepped, not continuous, so cards at similar distances do not flicker past each other as `pos` crosses an integer.
6. Drag comes from `useDrag`, which handles pointer capture, an 8 px dead zone and the capture-phase click swallow. `onDrag` divides `deltaX` by the current spacing so the drum tracks the finger 1:1, and `onDragEnd` snaps to `Math.round(pos)` with a 0.7 s `power3.out` tween whose `onUpdate` re-runs the same layout function.
7. The wheel handler accumulates `deltaX` and fires one step per 90 units, capped at 3 steps per event, then discards the remainder — an inertial trackpad flick otherwise keeps queuing steps after the fingers lift.

## Constants — use these values

These are tuned. Each one has a reason; do not round them off or replace them
with values that "look cleaner".

- `spacingRatio = 0.46`
  Card spacing as a fraction of stage width. At 0.46 the neighbours are half-visible at the edges, which is what tells the user there is more to come. Below ~0.3 the cards overlap into a stack; above ~0.6 the neighbours leave the stage and the drum looks like a single card.
- `maxSpacing = 560`
  Upper bound in px. Without it a 3440 px monitor computes 1582 px of spacing and the neighbours are simply gone; the ratio has to stop scaling at roughly the width of one comfortable reading column.
- `scaleFalloff = 0.2`
  Neighbours render at 0.8. Less than ~0.12 and the depth cue disappears; more than ~0.3 and the off-centre cards look like a different component rather than the same one further away.
- `ALPHA_INTERCEPT / ALPHA_SLOPE = 1.15 / 0.75`
  Alpha is `1.15 - 0.75 * distance`. The intercept above 1 keeps the first ~0.2 of travel at full opacity so the centre card does not start dimming the instant you touch it; the slope puts the zero crossing at distance 1.533, comfortably past where scale clamps.
- `SNAP_DURATION = 0.7`
  Seconds for the release snap. Under ~0.45 the settle is abrupt enough that the drum reads as stepped; over ~0.9 a second drag arrives before the first has landed.
- `WHEEL_STEP = 90`
  Accumulated wheel units per index step. Matches roughly one detent on a mouse wheel and one deliberate trackpad swipe; at 40 a single flick advances four cards.
- `MAX_WHEEL_STEPS = 3`
  Ceiling on how many steps one wheel event may fire. A high-resolution trackpad can deliver a `deltaX` of 400+ in one event, which without the cap jumps five cards from a gesture the user read as one.
- `DRAG_THRESHOLD = 8`
  Pixels before a press counts as a drag. Below ~4 a click on a touchpad registers as a drag and the click swallow eats the tap; above ~12 short deliberate flicks are ignored.

## API

```ts
function WrappingDrumCarousel(props: { children: ReactNode; spacingRatio?: number; maxSpacing?: number; scaleFalloff?: number; className?: string; cardClassName?: string; onIndexChange?: (index: number) => void }): JSX.Element
```

- `children: ReactNode`
  One card per child. Each is wrapped in a positioned cell the component controls.
- `spacingRatio: number` — default `0.46`
  Card spacing as a fraction of the stage width.
- `maxSpacing: number` — default `560`
  Ceiling on spacing in pixels, so wide screens do not fling the neighbours off-stage.
- `scaleFalloff: number` — default `0.2`
  How much a card shrinks by one slot out from centre.
- `className: string`
  Merged onto the stage element.
- `cardClassName: string`
  Merged onto every positioned cell. This is where you size the cards.
- `onIndexChange: (index: number) => void`
  Fires on every snap with the wrapped index, always in `0..count-1`.

## Reference implementation of the core

This is the part that is hard to get right. Adapt it; do not treat the rest of
the component as fixed.

```tsx
export function WrappingDrumCarousel({
  children,
  spacingRatio = 0.46,
  maxSpacing = 560,
  scaleFalloff = 0.2,
  className,
  cardClassName,
  onIndexChange,
}: WrappingDrumCarouselProps) {
  const stageRef = useRef<HTMLDivElement>(null);
  const cardsRef = useRef<Array<HTMLDivElement | null>>([]);
  /** Fractional carousel position. Tweened by the snap, driven raw by drag. */
  const posRef = useRef({ pos: 0 });
  /** Integer target index. Unwrapped — it counts up forever. */
  const indexRef = useRef(0);
  /** Last computed spacing in px. Drag divides by this for 1:1 tracking. */
  const stepRef = useRef(1);

  const reduced = useReducedMotion();
  const size = useResizeObserver(stageRef);

  const items = Children.toArray(children);
  const count = items.length;

  const notify = useRef(onIndexChange);
  notify.current = onIndexChange;

  /**
   * Lay every card out for the current `pos`. Called on mount, on resize,
   * on every frame of the snap tween, and on every pointermove during a drag.
   * It is a pure function of `pos` — there is no accumulated state in here,
   * which is why interrupting the tween mid-flight cannot desynchronise it.
   */
  const layout = useCallback(() => {
    const stage = stageRef.current;
    if (!stage || count === 0) return;

    const step = Math.min(spacingRatio * stage.clientWidth, maxSpacing);
    stepRef.current = step > 0 ? step : 1;

    // Signed ring offset in (-count/2, count/2]. The whole illusion is here.
    const ring = gsap.utils.wrap(-count / 2, count / 2);
    const pos = posRef.current.pos;

    for (let i = 0; i < count; i += 1) {
      const card = cardsRef.current[i];
      if (!card) continue;

      const offset = ring(i - pos);
      const distance = Math.abs(offset);

      gsap.set(card, {
        xPercent: -50,
        yPercent: -50,
        x: offset * step,
        // Explicitly flat. Without these two, a `transform-style: preserve-3d`
        // or a stray `rotateY` on an ancestor turns a deliberately 2D drum
        // into a half-broken 3D one that skews at the edges.
        rotationY: 0,
        z: 0,
        // Scale bottoms out at one slot out; alpha keeps falling and hits 0 at
        // distance 1.533. Cards therefore fade into fog rather than shrink to
        // a vanishing point — that mismatch is what sells the cylinder.
        scale: 1 - scaleFalloff * Math.min(distance, 1),
        autoAlpha: gsap.utils.clamp(0, 1, ALPHA_INTERCEPT - ALPHA_SLOPE * distance),
        zIndex: 100 - Math.round(10 * distance),
        transformOrigin: '50% 50%',
      });
    }
  }, [count, spacingRatio, maxSpacing, scaleFalloff]);

  /** Tween `pos` to an integer index and re-lay out on every frame. */
  const snapTo = useCallback(
    (index: number) => {
      indexRef.current = index;
      notify.current?.(wrapIndex(index, count));

      if (reduced) {
        // Not "duration 0" via the tween: a zero-duration gsap.to does not
        // guarantee an onUpdate call, so the layout would never run.
        posRef.current.pos = index;
        layout();
        return;
      }

      gsap.to(posRef.current, {
        pos: index,
        duration: SNAP_DURATION,
        ease: 'power3.out',
        overwrite: true,
        onUpdate: layout,
      });
    },
    [count, layout, reduced],
  );

  useDrag(stageRef, {
    threshold: DRAG_THRESHOLD,
    onDragStart: () => {
      // Kill the snap first or it keeps writing `pos` underneath the drag and
      // the cards visibly fight the finger.
      gsap.killTweensOf(posRef.current);
    },
    onDrag: (state) => {
      posRef.current.pos -= state.deltaX / stepRef.current;
      layout();
    },
    onDragEnd: (_state, moved) => {
      if (moved) snapTo(Math.round(posRef.current.pos));
    },
  });
```

## Requirements

These are not optional. A version of this component that skips any of them is
not finished.

**Cleanup.** Removes the wheel listener, kills the tween on the internal position object, kills any tween on the card elements and clears every property GSAP wrote with `clearProps: "all"`. `useDrag` releases pointer capture and removes its own five listeners. Ordering matters: tweens are killed before props are cleared, or an in-flight tween writes the transform straight back.

**Reduced motion.** Drag still tracks the finger 1:1 — direct manipulation is not motion the user did not ask for. What changes is the release: instead of a 0.7 s `power3.out` tween, `pos` is assigned the target index and the layout runs once, so the drum arrives in a single frame. Wheel steps land instantly for the same reason.

**Frame-rate independence.** Any smoothing must be a function of delta time.
`x += (target - x) * 0.1` converges twice as fast at 120 Hz as at 60 Hz; use
`x = target + (x - target) * Math.pow(smoothing, dt)` instead, where
`smoothing` is the fraction of the gap remaining after one second.

**Strict mode.** Assume effects run twice in development. Setup must be
idempotent and teardown must fully undo it.

## Known pitfalls — avoid these specifically

- Reaching for `rotationY` and `translateZ` to get the drum look. This technique is flat on purpose — real 3D needs a shared or per-element perspective decision, correct `transform-style` on every ancestor, and it renders text on a rotated plane, which is where the blurring comes from. Write `rotationY: 0, z: 0` explicitly so an ancestor cannot opt you into 3D by accident.
- Accumulating position instead of recomputing it. If the layout adds a delta to each card's current transform, interrupting the snap tween mid-flight leaves the cards permanently offset from `pos`. Layout must be a pure function of `pos` and nothing else.
- Using `opacity` instead of `autoAlpha`. At `opacity: 0` the wrapped-around cards are still hit-testable, so a click intended for the centre card lands on an invisible one stacked on top of it. `autoAlpha` also sets `visibility: hidden`, which removes them from hit-testing.
- Forgetting to kill the snap tween on `onDragStart`. The tween keeps writing `pos` underneath the drag and the cards visibly stutter against the finger.
- Calling `preventDefault` on every wheel event. A vertical trackpad scroll over the carousel then does nothing and the page appears frozen. Only the horizontal component is claimed here — `Math.abs(deltaX) > Math.abs(deltaY)` gates the whole handler.
- Registering the wheel listener as passive. `preventDefault` is silently ignored on a passive listener and Chrome logs an "Unable to preventDefault inside passive event listener" warning on every event.
- Computing spacing from `window.innerWidth`. The carousel is then correct on load and wrong the moment it sits inside anything narrower than the viewport — a sidebar, a modal, a preview grid.

## Notes

- This is one of three deliberately different carousel techniques in the registry, and they must not be collapsed into one. This one is **fake 3D driven by a JS position variable**: `gsap.utils.wrap` maps a continuous, unbounded index onto the item count, and depth is scale plus `autoAlpha` only. `perspective-coverflow-scroller` is **true 3D driven by a native scroll container** — real `rotateY`/`translateZ`, no JS loop. `percent-slide-carousel` is **flat percentage translation with a CSS transition** and no wrapping at all.
- Choose this one when the sequence must be endless in both directions and the item count is small enough that every item can stay mounted. It cannot virtualise: every card is laid out on every frame of a drag.
- `touch-action: pan-y` on the stage tells the browser that horizontal gestures belong to the carousel and vertical ones to the page. Without it, dragging on a phone either scrolls the page or forces you to `preventDefault` every `touchmove`, which fights the browser instead of cooperating with it.

## Definition of done

Drag left past the last card and the first one arrives from the right without a gap or a jump. Release mid-way and it settles onto the nearest card. Neighbours are visibly smaller and dimmer, and inspecting a card shows a `matrix()` transform with no 3D component. Scroll the page vertically with the cursor over the carousel and the page scrolls normally; swipe horizontally and the drum steps one card.

When you are finished, tell me which of the requirements above you implemented
and where, so I can check them.