# FX Atlas

A working library of high-end interactive web effects: fluid simulations and other dynamic WebGL2 work.
Each effect is a single self-contained page with a live control panel, named presets and a "How it works" section, verified in real Chrome on an Apple M5 GPU by a scripted harness. The code is written from the papers; the few pages that adapt MIT-licensed code say so in their credits (§10).

- **Gallery:** `index.html`. Live thumbnails, filterable by technique family.
- **Effects:** `effects/<slug>/index.html`. Each one is self-contained: inline JS and CSS, plain WebGL2, no build step, no network requests.
- **Research:** `research/*.md`, about 6,800 lines in nine topic files. `research/INDEX.md` maps families to sections and consolidates 311 checked references with their licences.
- **Verification:** `tools/verify.mjs`, with screenshots and `result.json` per effect in `verify/<slug>/` and the summary table in `verify/REPORT.md`.

To run it locally:

```
cd fx-library && python3 -m http.server 8765
open http://127.0.0.1:8765/
```

The effect pages accept these URL parameters:
- `?preset=<Name>` opens a named preset.
- `?panel` opens the controls.
- `?embed` is the gallery thumbnail mode: no UI, DPR 1, autopilot forever.
- `C` on the keyboard toggles the panel.

**Contents:**
1. [How the library is built](#1-how-the-library-is-built)
2. [Taxonomy](#2-taxonomy)
3. [Comparison of techniques](#3-comparison-of-techniques)
4. [The benchmark and the field](#4-the-benchmark-and-the-field)
5. [Effect catalogue](#5-effect-catalogue)
6. [How every effect was verified](#6-how-every-effect-was-verified)
7. [Verification results](#7-verification-results)
8. [What couldn't be made to work](#8-what-couldnt-be-made-to-work-and-known-limitations)
9. [Lessons learned](#9-lessons-learned)
10. [References and credits](#10-references-and-credits)

---

## 1. How the library is built

Every page shares one byte-identical **shell**. It is the block between the `FX shell` markers in each file, and its reference copy is `effects/_template/index.html`. The shell owns everything that is not the effect itself:

| Concern | What the shell does |
|---|---|
| Panel | Generated from a param schema: range (linear/log), colour, toggle and select controls, with `live:false` for parameters that re-allocate. Auto-generates the parameter and preset tables in the docs. |
| Presets | 3–4 named looks per effect. The reserved keys `theme` (light/dark), `bg` and `note`. `?preset=` deep links. |
| Pointer | Normalised stage coordinates (y up), smoothed velocity, `segment()` for capsule splats from last frame's position to this frame's. A gap of more than 150 ms starts a new stroke. |
| Autopilot | A ghost pointer draws an intro stroke on load, so a page is never blank while it waits for input. In `?embed` it runs forever. |
| Loop | A rAF loop with clamped dt. It idle-stops after the effect's `idleMs` (7 s by default; pages set 1.8–9.5 s); ambient pages never idle-stop. Every page pauses off-screen (IntersectionObserver) and on hidden tabs (`visibilitychange`). |
| Reduced motion | Renders one still from N frames of autopilot simulation and offers "Play anyway". |
| Fallback | Without WebGL2, without `EXT_color_buffer_float` (for effects that need float targets), on context loss or on a runtime error: a styled message over the effect's own `poster.jpg`. Never a broken canvas. |
| Sizing | ResizeObserver, DPR capped at 2 (1 in embed), `fitCanvas()`. |
| Metering | FPS plus per-frame GPU milliseconds via `EXT_disjoint_timer_query_webgl2`, shown in the panel and exposed on `window.FX.stats` for the harness. |
| GL kit | Program compilation, float render targets, ping-pong pairs, and `run(prog, uniforms, out)`, which sets uniforms by their GLSL type. |

Effect pages contain only their own effect code (shaders and any JS simulation), the param schema, the presets and the docs. That keeps the effects comparable, and it is why one harness can drive all of them identically.

---

## 2. Taxonomy

The library groups techniques into eight families. These are the gallery's filter chips.

| Family | What it simulates or draws | Techniques in this family |
|---|---|---|
| **Grid fluids** | Flow on an Eulerian grid. The stable-fluids pages keep velocity, pressure and dye in textures; the lattice Boltzmann page keeps nine particle populations per cell instead. | Stable fluids (Stam 1999 / GPU Gems 38), vorticity confinement, implicit viscosity, MacCormack advection (BFECC studied, not used), lattice Boltzmann (D2Q9) |
| **Smoke, fire & ink** | Grid fluids with extra physics (buoyancy, combustion, sinking ink), plus a burning front on paper | Boussinesq buoyancy, fuel/temperature/soot combustion with blackbody emission, Beer-Lambert ink compositing, 2.5D self-shadowing, an eikonal arrival-time burn front (Scorch) |
| **Particle fluids** | Liquids made of particles, with free surfaces, splashes and surface tension. | FLIP/PIC hybrids (grid pressure solve; APIC studied, not used), SPH/PBF, 2D metaball height-field rendering |
| **Water & caustics** | A liquid surface rather than a volume: waves, refraction, focused light. | Damped wave equation (height-field ripples), Jacobian/area-ratio caustics, refraction of a canvas-drawn backdrop |
| **Patterns & blobs** | Implicit or self-organising shapes. | Gray-Scott reaction-diffusion, metaballs/2D implicit goo with exponential smooth-min, raymarched 3D SDF blobs |
| **Particles & trails** | Very many points, or chains of points, moved by fields. | 1M+ GPGPU particles in curl noise, morphing particle targets, leader-follower tube ribbons (the ServiceTitan Max technique) |
| **Distortion & post** | Effects that move or relight existing pixels instead of drawing new matter. | Flowmap/displacement advection, liquid-glass refraction, bloom pyramids, god-rays, chromatic aberration |
| **Gradients & light** | Large, calm, procedural colour fields and light transport. | Stripe-style gradient mesh, twisted ribbon sheets with filament lines, 2D radiance cascades (Vercel-style soft global illumination) |

---

## 3. Comparison of techniques

This table covers 32 of the 35 technique families studied in `research/` (it leaves out particle-fluid rendering, scroll-driven 3D scenes and scroll-scrubbed media). The cost, mobile and complexity values are the research estimates; the measured numbers for the effects we actually built are in §5 and §7. **Cost** is the research's qualitative GPU-cost rating (low, medium, high, very high), judged from estimates for a base M1 at 2560×1440; it is not a fixed ms band. **Complexity** runs from 1 to 5. **Mobile** means a mid-range phone GPU at 60 fps.

| Technique | Look | Cost | Complexity | Mobile | Best use |
|---|---|---|---|---|---|
| Stable fluids (grid) | Dense swirling medium. With heavy implicit viscosity and grip splats, big lazy syrupy S-curves and a wake | medium | 3 | ok | The base engine for fluid pages: velocity at a short side of about 128 (RG16F), dye at 1024–1440, fixed 60 Hz step, open edges for overlays |
| MacCormack / BFECC advection | The same flow with crisp dye. Stripes and filaments keep their contrast for the whole ~3 s life | medium | 2 | ok | Dye advection whenever fine detail matters. MacCormack is 2 passes plus a 4-texel clamp; BFECC is 3 passes |
| Dye rendering (dark vs light) | Dark: luminous strands with white-hot crests and bloom. Light: thick glossy syrup, deep where it pools, with a soft cast shadow | low | 2 | good | The display pass that decides whether a sim reads as liquid, ink, neon or smoke |
| Lit tube trails (ServiceTitan Max) | 16 tapered metallic tubes snake after the cursor, lit by coloured point lights, bloomed with threshold 0 | low | 2 | good | The benchmark hero. In plain WebGL2: instanced ribbons with an analytic cylinder normal plus a bloom pyramid |
| Ink in water | Mushroom caps that drip into Rayleigh-Taylor fingers. Pale saturated veils, near-black cores, no haze | medium | 3 | ok | The rare fluid that looks better on light pages (multiply blend) |
| Smoke | A rising column that breaks into Kelvin-Helmholtz roll-ups, with key-lit tops and self-shadowed undersides | medium | 3 | ok | A dark hero with an incense-stick cursor wake. Quarter-res shadow march under 4 ms |
| Fire | White-yellow bases cooling to red tips that tear into soot, HDR bloom, rising embers | high | 4 | ok | A dark "fuse" wake, or burning paper on light pages |
| Feedback-buffer smoke | Wisps drifting on a slowly changing current, with no real vortices | low | 1 | good | The mobile and no-float fallback for smoke and fire; smoky distortion of imagery |
| Volumetric raymarch | Real depth: self-shadowed billows, silver linings, fireballs | very high | 4 | poor | Half-res centrepieces with temporal accumulation only |
| FLIP / PIC / APIC | Free-surface liquid that sloshes, folds and throws droplets. APIC is smooth but keeps its swirl | medium | 3 | ok | Liquid pools with the cursor as an obstacle. Needs no neighbour search: scatter with `gl.POINTS` and additive blending |
| SPH / PBF | Particle water with surface-tension beading: droplets split and rejoin (mercury, dew) | high | 4 | poor | Beads and droplets at modest counts (16k–65k in 2D). Not full-screen trails |
| MLS-MPM | Heavy curling water; viscoplastic honey, frosting, impasto paint | medium | 4 | ok | Tactile paint on light backgrounds. Mostly WebGPU in the wild |
| Height-field ripples | A thick liquid-glass sheet. The cursor drags a trough that leaves big rounded swells in a V wake | low | 2 | good | A lighting-only overlay on live DOM. Also the height source for caustics |
| Lattice Boltzmann | Lab-tank fluid with coherent, rhythmic vortices: the Kármán vortex street | high | 4 | poor | Cursor-as-cylinder vortex streets. Needs fp32 targets |
| Caustics | A sharp, breathing net of light filaments with cusps and knots | medium | 3 | ok | Luminous filament wakes on dark, driven by ripples. The analytic version is a cheap ambient backdrop |
| Reaction-diffusion | Self-organising coral, mitosis, mazes and worms, embossed as enamel | medium | 3 | ok | A pattern that grows behind the stroke and retracts about 3 s later |
| Metaballs / 2D goo | Soft blobs that reach toward each other, neck, merge and pinch off | low | 2 | good | Cheap, robust goo trails and lava lamps. The SVG goo filter as a no-WebGL fallback |
| Raymarched SDF blobs | True 3D droplets melting together: chrome, mercury, glass, iridescence | high | 4 | poor | Liquid-metal cursor followers. Must be scissored to the blob bounding box |
| Curl noise | Coiling, divergence-free flow. Particles stay evenly spread | low | 2 | good | The velocity field for particles and ribbons. Bridson's rigid-body potential gives cursor grip |
| GPGPU particles (1M+) | 1–2M hair-fine additive points that read as luminous silk | high | 4 | ok | Dark hero silk and morphing logos. State in RGBA32F; blending in RGBA16F |
| Leader-follower ribbons | Glossy or luminous tapered streamers with sliding specular glints | low | 3 | good | The benchmark look at a fraction of its cost |
| Flowmap distortion | Content smeared as if a finger were dragged through wet paint, then healing back to sharp | low | 3 | good | Hero type or photo smear-and-heal. Advect a displacement field, never the colours |
| Liquid glass | Thick clear glass: flat centre, lensed rim, bezel-only dispersion, Fresnel, frost | low | 3 | good | Cursor glass droplets refracting a canvas-drawn backdrop (WebGL cannot refract the DOM) |
| Bloom / chromatic post | Hot cores with multi-scale haze, speed-reactive fringes, grain | medium | 3 | ok | Dark backgrounds only. A 13-tap mip bloom plus one composite pass |
| Stripe gradient mesh | Huge soft blobs of 4 brand colours folding like back-lit silk | low | 2 | good | A calm hero on light or dark. About 1 noise period across the whole viewport |
| Ribbon sheet (current Stripe) | One broad silk ribbon twisting diagonally, with hairline fibres and glowing folds | medium | 4 | ok | A flagship hero. The dark variant approaches the benchmark |
| Domain-warped mesh gradients | Soft colour fields from drifting pins, or marbled agate veins from fbm warping | medium | 3 | ok | Organic full-bleed backgrounds |
| Aurora curtains | Green-to-violet light sheets with crisp hems and sliding rays | medium | 3 | ok | Dark atmospheric hero tops |
| Glows, beams, spotlights | Restrained light leaks, cursor-lit borders, conic sweeps (Linear/Vercel style) | low | 2 | good | An accent layer over any background |
| Hidden-fluid control fields | No dye: the velocity field reveals a second layer, parts particles or splits RGB | low | 3 | good | The cheapest premium family (sim at 6–25% of screen, 2–5 pressure iterations) |
| 2D radiance cascades | Emissive shapes flood the page with soft GI: contact-sharp shadows, colour bounce | high | 4 | ok | Logo or LED heroes; depth on light pages where bloom fails |
| Dithering and grain | Invisible 1-LSB dither that removes banding | low | 1 | good | Mandatory as the last pass of every effect |

---

## 4. The benchmark and the field

### 4.1 The servicetitan.com/max hero is not a fluid

The brief named the servicetitan.com/max hero as the benchmark: "big, smooth, genuinely fluid". Reading the production bundle shows that it is **`TubesCursor` from `threejs-components@0.0.19`** (Kevin Levron, ISC). The research verified this independently twice: through the HTML, the lazy chunk and the library bundle.

- **Tubes:** 16 tubes, each a follow-the-leader point chain (alpha 0.5 per frame).
- **Geometry:** rebuilt on the CPU every frame as a tapered `TubeGeometry` (`sin(πt)` radius).
- **Material:** `MeshStandardMaterial` with metalness 1 and roughness 0.25, and **no environment map**, so each tube is a black mirror.
- **Lights:** four coloured point lights (`#0070d4 #6cb4ee #4da3e8 #89c9f7`, intensity 200).
- **Bloom:** threshold 0, strength 1.5, radius 0.5. It turns the specular streaks into luminous filaments.
- **Idle:** a 1:2 Lissajous figure-eight when the pointer leaves.
- **Lifecycle:** DPR pinned to 2, MSAA off, paused off-screen and on hidden tabs.

Why it reads as premium:
- exactly one hero effect
- three blues plus one light colour on true black
- light as the medium: metal plus bloom
- CSS does the ambient glow (a masked plus-grid, a radial glow, a bottom fade)
- never a dead frame

What it gets wrong, and our pages fix:
- **Per-frame lerps.** Tail length is about `N·(1−a)/a` frames, so on 120 Hz displays the tails are half as long.
- **No light-background mode.**
- **`touch-action:none` on a full-hero canvas** stops touch scrolling. (Our shell keeps `touch-action:none` on its stage too, but shrinks the stage to 88svh on touch screens so a strip of page stays scrollable; lesson 24.)

The library carries two answers:
- **`neon-tubes`** rebuilds the technique from scratch, without copying TubesCursor code: instanced ribbons with an analytic tube normal, a bloom pyramid and dt-correct easing.
- **`fluid-trail`** answers the brief's "genuinely fluid" with a real stable-fluids solver whose "ServiceTitan ribbon" dark preset renders as luminous filaments.

### 4.2 What the best studios actually do

This is from `research/site-survey.md` (34 sites inspected, bundles read where possible) and the "Real sites" sections of the other research files (89 sites in all).

1. **The fluid is usually hidden.**
   - Lando Norris (OFF+BRAND) thresholds the fluid into a reveal mask.
   - Active Theory and Igloo Inc push GPGPU particles with fluid velocity.
   - Lusion's "screen paint" drives RGB-shift distortion.
   - Unseen perturbs water reflections.
   - These sims are tiny: 10% of screen resolution with 4 Poisson iterations (Lando), 128² with about 3 (Igloo), 256² with 5 (Active Theory).
2. **Pixel budgets are explicit.**
   - Lusion caps rendering at 2560×1440 and adds an FSR upscaler.
   - TubesCursor pins DPR to 2.
   - Vercel renders its hero in a Worker on an OffscreenCanvas.
3. **Vercel's hero is 2D radiance cascades.**
   - It tries WebGPU, then WebGL2 (only with `EXT_color_buffer_float`), then a static WebP.
   - Reduced motion gets the static image.
4. **Premium motion is damped, not lerped.**
   - Lusion runs pointer and camera motion through second-order dynamics (f = 1.5 Hz, ζ = 0.8, r = 2, after t3ssel8r).
   - Active Theory normalises its dissipation constants to the refresh rate.
5. **Fallback stills match the shader.** Stripe preloads per-breakpoint WebP posters, and Vercel ships desktop and mobile WebP fallbacks inside the hero.
6. **Never block clicks.** Listen on the document, hit-test the canvas rectangle, and set `pointer-events:none` on the canvas.

### 4.3 Patterns that make an effect feel premium

These are distilled from the survey and used as the library's bar:

- **Motion:**
  - second-order filters on anything that follows input
  - `decay = pow(d60, dt·60)` instead of per-frame constants
  - immediate pointer response, slow cross-fades for mode changes
  - a low-amplitude idle, then an idle-stop
- **Restraint:**
  - one hero effect, contained
  - cut faint dye with a smoothstep so it never becomes haze
  - big means low frequency, not high amplitude
- **Colour:**
  - three colours plus a light colour
  - on dark, colour lives in highlights and bloom
  - on light, colour lives in thickness and absorption (a Beer-Lambert ramp) with soft coloured shadows
- **Depth:** bloom on dark; height-field normals, Blinn-Phong and a soft cast shadow on light; always dither the final 8-bit output.
- **Performance:** cap total pixels, pause when invisible, boot behind a poster, and measure.

---

## 5. Effect catalogue

The library has 24 effects. Each page has a full-screen demo, a slide-out panel with every key parameter, 3–4 named presets, and a "How it works" article. The article has a pipeline diagram, the non-obvious ideas, auto-generated parameter and preset tables, measured performance and credits. The GPU numbers in this table come from the canonical serial harness runs (§7); Cost and Mobile are the builders' estimates (`tools/meta.json`).

<!-- gen:catalogue -->
| # | Effect | Family | Technique | Presets | GPU ms mean / p95 | Cost | Mobile |
|---|---|---|---|---|---|---|---|
| 1 | [Fluid Trail](effects/fluid-trail/) | Grid fluids | Stable fluids (Stam) with vorticity confinement and implicit viscosity; simulation shaders adapted from… | 4 | 5.11 / 8.21 | medium | good |
| 2 | [Silk Wake](effects/silk-wake/) | Grid fluids | Stable fluids + MacCormack advection with tube-profile specular dye rendering | 4 | 4.84 / 7.76 | medium | ok |
| 3 | [Marbled Contours](effects/marbled-contours/) | Grid fluids | Stable fluids + MacCormack ink rendered as second-order distance anti-aliased iso-contours,… | 3 | 5.57 / 8.4 | medium | ok |
| 4 | [Vortex Street](effects/karman-wake/) | Grid fluids | Lattice Boltzmann (D2Q9 BGK) with a cursor obstacle | 4 | 5.83 / 8.94 | medium | good |
| 5 | [Sumi Bloom](effects/ink-drop/) | Smoke, fire & ink | Buoyant stable fluids with subtractive Beer-Lambert ink | 4 | 5.05 / 8.59 | medium | ok |
| 6 | [Incense Wake](effects/incense-wake/) | Smoke, fire & ink | Buoyant smoke (temperature + density) with 2.5D self-shadowing | 3 | 5.21 / 7.72 | medium | ok |
| 7 | [Ember Trail](effects/ember-trail/) | Smoke, fire & ink | Combustion fluid (static fuel bed, delayed igniter, T⁴ cooling, MAC projection, clamped MacCormack) with a… | 4 | 5.12 / 9.41 | medium | good |
| 8 | [Scorch](effects/scorch/) | Smoke, fire & ink | Burning-front propagation on a paper sheet: an arrival-time (eikonal) field through anisotropic fibre… | 3 | 3.78 / 5.73 | medium | ok |
| 9 | [Mercury Pool](effects/flip-liquid/) | Particle fluids | 2D FLIP/PIC particle-grid liquid on the GPU (MAC grid, ghost-fluid RB-SOR, async column readback) | 4 | 5.73 / 9.58 | medium | good |
| 10 | [Mercury Beads](effects/mercury-beads/) | Particle fluids | CPU position-based SPH (Clavet double-density relaxation) with cohesion, XSPH and ridge-cut bridges; GPU… | 3 | 3.97 / 5.59 | medium | ok |
| 11 | [Viscous Glass](effects/ripple-glass/) | Water & caustics | Height-field wave equation (9-point leapfrog, Kelvin–Voigt viscosity via squared-Chebyshev passes) with a… | 3 | 3.66 / 5.49 | medium | ok |
| 12 | [Caustic Light](effects/caustic-filaments/) | Water & caustics | Forward light mesh: water height field (24 crest-peaked wind waves + 120 Hz wave-equation ripples + wake… | 4 | 5.66 / 9.63 | medium | ok |
| 13 | [Coral Wake](effects/coral-wake/) | Patterns & blobs | Gray-Scott reaction-diffusion with a cursor style map, lit as an embossed surface | 4 | 6.54 / 10.47 | medium | ok |
| 14 | [Goo Trail](effects/goo-trail/) | Patterns & blobs | Metaballs / exponential smooth-min capsule field with lit goo shading | 4 | 3.32 / 5.95 | low | good |
| 15 | [Liquid Metal](effects/liquid-metal/) | Patterns & blobs | Raymarched 3D SDF round cones with cubic smooth-min, energy-conserving prefiltered studio, seam-continuous… | 4 | 5.91 / 10 | medium | ok |
| 16 | [Curl Silk](effects/curl-silk/) | Particles & trails | 1M-particle GPGPU curl-noise flow (psrdnoise stream function, RK2 + inertia, MRT state) with a… | 4 | 4.69 / 6.95 | high | ok |
| 17 | [Morph Swarm](effects/morph-swarm/) | Particles & trails | GPGPU particles with target-shape springs blended into curl-noise flow | 3 | 9.66 / 14.2 | medium | good |
| 18 | [Neon Tubes](effects/neon-tubes/) | Particles & trails | Leader-follower cursor tubes (instanced ribbons, analytic cylinder normals, point lights, bloom pyramid) | 4 | 4.33 / 5.82 | medium | good |
| 19 | [Wet Paint Smear](effects/liquid-smear/) | Distortion & post | Cursor flowmap: incompressible stable-fluids velocity advects an RG16F offset field D by MacCormack (D' =… | 4 | 4.72 / 7.13 | medium | good |
| 20 | [Liquid Glass](effects/glass-droplet/) | Distortion & post | SDF liquid-glass lens: squircle bezel with a clamped slope, analytic gradients through smooth-min, 7-tap… | 4 | 2.56 / 3.31 | low | good |
| 21 | [Prism Bloom](effects/prism-bloom/) | Distortion & post | HDR age-coded fluid wake with Karis mip-chain bloom, gap-only cursor god-rays, compressed spectral… | 3 | 7.53 / 12.04 | medium | ok |
| 22 | [Silk Mesh](effects/silk-mesh/) | Gradients & light | Stripe-style animated gradient mesh: vertex-displaced, anisotropic-drape plane with ordered smoothstep^4… | 4 | 3.29 / 4.99 | medium | good |
| 23 | [Filament Wave](effects/filament-wave/) | Gradients & light | Twisted 3D sheet with constant-width iso-line filaments and fold glow | 3 | 4.17 / 6.22 | medium | ok |
| 24 | [Radiance Halo](effects/led-halo/) | Gradients & light | 2D global illumination with radiance cascades (bilinear-fix merge, jump-flood SDF, soft shadows, coloured… | 3 | 4.48 / 6.44 | high | ok |
<!-- /gen:catalogue -->

### Grid fluids

**Fluid Trail** (`fluid-trail`): *the reference, ported. This is effect #1.*
- **Engine:** stable fluids on a 228×128 velocity grid with a 1820×1024 dye field. Vorticity confinement, implicit (Jacobi) viscosity, warm-started pressure, open edges.
- **Light look:** the dye is a height field lit as glossy syrup: Blinn-Phong, a colour ramp by thickness, and a soft cast shadow.
- **Dark look:** emissive filaments with glow.
- **Key ideas:**
  - the pointer only partly grips the fluid, so the dye is a wake left behind it, not paint under it
  - capsule splats from last frame's pointer to this frame's, with deposit per distance travelled
  - stripes that survive curves
  - a radial clear zone around the pointer, with `pointer-events:none` over a live demo hero whose buttons still work
- **Presets:** Crimson syrup (the reference look), Emerald, ServiceTitan ribbon (dark), Neon.

**Silk Wake** (`silk-wake`): *the fluid-native answer to the ServiceTitan Max hero.*
- **Look:** hair-thin chrome threads ride a viscous wake and swell into lazy S-curves around the vortices a stroke leaves. They hold for about 3 s, then thin and fade.
- **Engine:** MacCormack dye advection keeps the threads separate for their whole life. An on-page toggle switches to semi-Lagrangian, which widens each thread until the display drops it within about 1.5 s (Raw dye shows the blur itself). The display is tube-profile specular (white-hot core, coloured rim, bloom).
- **Key ideas:**
  - grip, not impulse
  - the wake must move slower than the pen
  - lay dye where the flow would already have carried it
- **Presets:** Max Blue, Aurora, Molten, Pearl Thread (light).

**Marbled Contours** (`marbled-contours`):
- **Look:** single-channel ink is never drawn as a cloud, only as its iso-contours. The lines stay constant-width and anti-aliased however hard the flow stretches them, because they are drawn from distance, not threshold. Advected contours are material lines, so a stroke combs them into suminagashi marbling or a moving topographic map.
- **Engine:** CFL-adaptive MacCormack with fp32 ink for flat regions, and contour level of detail as on a topographic map.
- **Presets:** Suminagashi (washi paper), Neon Topo, Gold Leaf.

**Vortex Street** (`karman-wake`):
- **Engine:** a real D2Q9 lattice Boltzmann wind tunnel. 41,600 cells, stepped 1,920 times a second as 32 substeps per frame, with fused stream+collide in RGBA32F.
- **Look:** the cursor is a soft cylinder in the current. Above Re ≈ 47 it sheds a von Kármán street (measured St ≈ 0.19) of luminous dye that trails behind it.
- **Key ideas:**
  - a speed-capped follower respects the lattice Mach limit
  - a hidden sponge layer is the whole wind tunnel
  - it never blows up at any slider setting
- **Presets:** Aurora, Ink stream (light), Plasma, Smoke tunnel (a streakline rake).

### Smoke, fire & ink

**Sumi Bloom** (`ink-drop`):
- **Look:** ink dropped into still water. Caps roll up into twin lobes and drip into Rayleigh-Taylor fingers, and poured ribbons sag into curtains.
- **Engine:** none of this is drawn. It comes from the ink's weight riding in a spare velocity channel, plus the pressure projection. Pigments are concentrations composited by Beer-Lambert, so inks mix subtractively on paper.
- **Presets:** Sumi, Indigo & vermilion, Bioluminescent (dark, additive), CMY.

**Incense Wake** (`incense-wake`):
- **Engine:** separate heat and smoke fields. A cooling clock decides where the laminar thread starts to curl, and drag on cooled air makes wisps rise and then hang.
- **Lighting:** a quarter-resolution, IGN-jittered optical-depth march toward each lamp gives self-shadowed volume with a forward-scatter rim and a crisp optical-depth cut. There is no haze.
- **Presets:** Temple, Studio (light), Neon smoke.

**Ember Trail** (`ember-trail`):
- **Engine:** a combustion fluid. The cursor lays fuel on the "ground", and an igniter following 0.14 s behind sets it alight. Flames are the physical blackbody colour of the simulated temperature in HDR, with noise-displaced tongues whose tips come from T⁴ radiative cooling, ridged-noise filaments in the hot cores, embers, and a Karis-averaged bloom.
- **Presets:** Campfire, Blue flame, Hellfire, Plasma.

**Scorch** (`scorch`):
- **Look:** a paper sheet over an editorial hero. Touching it ignites a blackbody ember line that creeps through anisotropic fibre noise, chars, and burns through to the page beneath. Once the fire is out, the burn plays backwards and the sheet heals.
- **Engine:** modelled as burn travel time, not cell states.
- **Presets:** Parchment, Blueprint, Ash.

### Particle fluids

**Mercury Pool** (`flip-liquid`):
- **Engine:** 65,536 GPU particles in a 2D FLIP/PIC liquid, entirely in WebGL2 fragment shaders. Scatter uses `gl.POINTS` plus additive blending into an RGBA16F staggered grid (Safari/WebKit does not expose `EXT_float_blend`, so RGBA32F blending is not portable), with a ghost-fluid red-black SOR pressure solve and G2P with RK2.
- **Look:** the cursor is a solid paddle that scoops, splashes and throws droplets.
- **Presets:** Mercury, Milk, Ink, Honey.

**Mercury Beads** (`mercury-beads`):
- **Engine:** 3,000 particles of position-based SPH (Clavet double-density relaxation) with cohesion and XSPH, on the CPU, with about 2.1 ms of solver JS per frame (3.5 ms mean JS per frame in the canonical harness run).
- **Look:** a cursor "knife" slices beads, and surface tension snaps the halves round again. A dimpled gravity tray with ridges brings them home.
- **Note:** the page explains why the research picked FLIP/APIC for the GPU, and why CPU SPH is viable at this scale.
- **Presets:** Mercury, Gold, Water beads (light).

### Water & caustics

**Viscous Glass** (`ripple-glass`):
- **Engine:** a damped wave equation on a 356×200 height field, on a fixed step chosen from the stability bound, with an isotropic stencil and Kelvin-Voigt viscosity.
- **Cursor:** a volume-conserving moving dimple leaves a true Mach-cone V wake and ploughs a furrow that creeps flat over about 3.5 s.
- **Rendering:** refracts a canvas-drawn hero (WebGL cannot refract the DOM), with glints, Fresnel and crisp caustic filaments.
- **Presets:** Clear (light editorial), Deep pool, Glass (slow and heavy).

**Caustic Light** (`caustic-filaments`):
- **Engine:** sunlight traced forward through moving water. 126,000 rays become small triangles of light, and brightness comes from their area change (the screen-space derivative of each ray's source position, taken where its light lands). Folds thinner than a pixel stay crisp, and dispersion is done in two channels.
- **Cursor:** its wake is a converging lens that adds light: a band of brighter creases.
- **Presets:** Pool (light), Ocean floor, Gold light, Prism.

### Patterns & blobs

**Coral Wake** (`coral-wake`):
- **Engine:** Gray-Scott reaction-diffusion on 2.5 px cells, storing (1−A, B) in RG16F. The cursor paints a lobed, decaying wake. Inside it the feed/kill "style map" sits in a living regime, and everywhere else in a dying one.
- **Look:** coral, mazes and cells grow behind you and retreat by their own chemistry. They are lit as glossy enamel, gold relief or neon iso-lines.
- **Presets:** Coral, Labyrinth, Mitosis, Gold relief.

**Goo Trail** (`goo-trail`):
- **Engine:** no grid. Up to 128 CPU beads on spring strands are drawn exactly in one pass, as uneven capsules joined with the exponential smooth-min (a metaball field in log space).
- **Look:** necks pinch and snap under an art-directed Plateau-Rayleigh instability. It is one of the cheapest effects in the library (only Liquid Glass and Silk Mesh measured lower).
- **Presets:** Slime, Honey, Lava, Ink.

**Liquid Metal** (`liquid-metal`):
- **Engine:** 3–12 sphere and round-cone SDF droplets merged with smooth-min and sphere-traced at 0.55 of canvas resolution (adaptive), then upsampled, culled by the smooth-min's support. They are lit by a procedural photo studio that is prefiltered for anti-aliasing.
- **Materials:** chrome, gold, spectral thin-film iridescence, or dispersive glass that refracts on the way in and on the way out.
- **Presets:** Chrome, Iridescent (light), Glass, Gold.

### Particles & trails

**Curl Silk** (`curl-silk`):
- **Engine:** 1,048,576 GPU particles ride the curl of a stream function, so they never bunch or tear and draw unbroken silk threads.
- **Cursor:** stirs a real 82×48 vorticity/stream-function fluid, which leaves big figure-eight eddies.
- **Look:** particles have inertia, and about a third of the frame is kept as calm black water.
- **Presets:** Silk, Aurora, Graphite (light), Ember.

**Morph Swarm** (`morph-swarm`):
- **Engine:** a quarter-million particles spring to rank-matched samples of words drawn on a hidden canvas. They hold, dissolve left to right into a curl-noise current, and re-form as the next word.
- **Cursor:** a hidden laminar fluid wake parts the letters like water and keeps the springs off while it heals (the Igloo Inc trick).
- **Presets:** Monochrome, Neon, Ink (light).

**Neon Tubes** (`neon-tubes`): *the ServiceTitan Max technique, rebuilt from scratch in plain WebGL2.*
- **Engine:** 16 tapered tubes as follow-the-leader chains with refresh-rate-exact substeps. They are drawn as attribute-less instanced ribbons with an analytic cylinder normal, round folds and centripetal Catmull-Rom, then GGX shading from four coloured point lights, a Karis dual-filter bloom, ACES and dither.
- **Presets:** ServiceTitan Max, Neon, Liquid chrome (light, cast shadow), Candy.

### Distortion & post

**Wet Paint Smear** (`liquid-smear`):
- **Look:** a procedurally shader-painted picture (an impasto seascape by default) behaves like wet oil, then relaxes back to exactly the original in about 3 s.
- **Engine:** a small incompressible flow advects an RG16F *offset* field by MacCormack, and the pristine image is sampled once at `uv + D`, so it never blurs. Relaxation uses `exp(−dt/τ)`. The RGB split follows the flow only where paint moved, and wetness is lit in slope space.
- **Presets:** Oil painting, Editorial, Neon poster, Dusk photo.

**Liquid Glass** (`glass-droplet`):
- **Look:** a thick SDF glass drop trails the cursor over a canvas-painted product UI, merging into the toolbar with smooth-min.
- **Engine:** a squircle bezel with a clamped slope, analytic gradients through smooth-min, per-wavelength refraction (a spectrum, not an RGB split), frost from a Gaussian pyramid, and Fresnel on the grazing part only, so the centre stays clear.
- **Presets:** Clear, Dark glass, Prism, Frosted.

**Prism Bloom** (`prism-bloom`):
- **Engine:** a fluid wake that carries dye *and* age, so the colour is history: white-hot at the head, cooling through the palette. The post stack is a Karis-supersampled mip-chain bloom that cuts shimmer on hair-thin strands by about a quarter, god-rays that escape only through gaps in the wake, earned spectral aberration that rises with speed, lens dirt only where there is light, grain and a hue-preserving tonemap.
- **Presets:** Comet, Ember, Synthwave.

### Gradients & light

**Silk Mesh** (`silk-mesh`):
- **Look:** the classic Stripe gradient rebuilt as a material. A tessellated sheet is displaced by slow simplex noise in long drapes, with real normals and a satin sheen. The cursor presses a soft trough and drags the colour.
- **Engine:** four colours over-paint in a fixed order with `smoothstep()^4` weights, mixed in Oklab, so the colours never turn to mud. "Big means low frequency, not high amplitude."
- **Presets:** Stripe classic, Midnight, Pastel, Sunset.

**Filament Wave** (`filament-wave`):
- **Look:** the current-generation Stripe look. One twisted ribbon sheet (49k triangles, shaped entirely in the vertex shader) is covered in 120–190 iso-line filaments (150 by default; the slider goes to 800).
- **Engine:** each filament is held to constant pixel width by its own screen-space derivative. Filaments crowd together where the sheet turns edge-on, and a facing-ratio term, (1 − |N·V|)³ from finite-difference normals, makes the folds glow. The silhouette uses MSAA, and the palette is authored in Oklab.
- **Cursor:** crossing the ribbon rolls a glowing fold down its length.
- **Presets:** Stripe 2025, Night, Mono.

**Radiance Halo** (`led-halo`):
- **Engine:** 2D global illumination with radiance cascades (the technique behind Vercel's hero), solved every frame. You carry a light through a room of sculptures, neon glyphs and paper cut-outs.
- **Look:** contact-sharp shadows that widen with distance, light pooling inside a broken ring and beaming out of its gap, and colour bleed.
- **Key ideas:** the penumbra condition sets the budget, top-down merging, the bilinear fix, a distance field built once per scene, and analytic lights.
- **Presets:** Gallery, Neon sign, Paper (light).

---

## 6. How every effect was verified

All of this ran in real Google Chrome (headless, `channel: 'chrome'`, ANGLE on Metal on an **Apple M5**), driven by Playwright through `tools/verify.mjs`. Pages were served over `python3 -m http.server` on localhost. In this setup headless Chrome uses the real GPU and rAF runs at about 60 Hz, so FPS is capped at 60. Cost therefore comes from the shell's per-frame `EXT_disjoint_timer_query_webgl2` meter. On Apple GPUs that reading is inflated by clock scaling and is best read as a conservative, relative signal (§9, lesson 25).

| Check | What it does | Fails when |
|---|---|---|
| Desktop sweep | 1280×720 CSS at DPR 2 (a **2560×1440** backing store). A 1.5 s lemniscate pointer sweep with slow and fast stretches. FPS comes from an independent rAF recorder; GPU and JS ms come from `FX.stats`. Screenshots mid-motion, at +0.7 s and at +3 s (staying power), with image statistics to catch blank frames. | FPS < 55, fewer than 30 effect frames in the sweep, fallback on a capable GPU, console or GL error (a blank-looking screenshot is a warning) |
| Presets | Applies every preset, sweeps, screenshots | any error, or fewer than 2 presets |
| Control fuzz | Sets every control to its min and its max | setParam throws, a GL error, the effect falls back, or a console error (there is no image check, so NaN or black output would not be caught) |
| Idle | Non-ambient effects must stop the rAF loop after the idle timeout; ambient ones must stop rendering when scrolled off-screen (hidden-tab pausing is in the shell but not exercised by the harness) | frames keep running |
| Mobile | 390×844 at DPR 3, touch emulation. A CDP touch drag measured without a screenshot in the timed window, a second drag for the picture, a touch-scroll test from the bottom of the screen, and the panel opened on a phone. | horizontal overflow, panel off-screen, page not scrollable by touch, errors |
| Reduced motion | `prefers-reduced-motion: reduce` | the loop keeps running instead of showing a still |
| No WebGL2 | `getContext('webgl2')` returns null | no styled fallback message |
| Embed | `?embed` at 640×400 (the gallery thumbnail); also saves `poster.jpg` | fewer than 10 frames in 500 ms, the HUD is visible, or a console error |

Warnings, which are not failures: frame p95 > 20 ms, GPU p95 > 12 ms, JS p95 > 8 ms, touch FPS < 45.

**Budgets.** The bar set for builders was GPU p95 ≤ 8 ms preferred and < 12 ms required at 2560×1440, with JS ≤ 4 ms per frame. Later calibration showed the per-frame reading runs 2.5–4.5× above full-clock work at light loads, so these budgets are conservative proxies (§9, lesson 25).

**Canonical numbers.** While the effects were being built, up to eight agents ran harnesses on one GPU, and the same build read anywhere from 3.4 to 12 ms. `TIME_ELAPSED` queries count other processes' GPU work. The numbers below therefore come from **serial runs with nothing else using the GPU**: `tools/verify-all.sh` for every check, then `tools/gpu-median.sh`, which takes the **median of three** locked desktop sweeps per effect, because one build's reading still varies from run to run with the GPU clock, typically by 1–3 ms and by up to about 6 ms p95 (coral-wake: 9.53–15.72 ms).

**Review loop.** Each effect also passed through at least one independent critique round: a fresh agent scored it against the bar from the screenshots and its own probes, then a fix round followed. A second round ran whenever the score was below 8 or the verdict was "rework".

<!-- gen:results -->
## 7. Verification results

Canonical runs, 2026-10-31, Apple M5, Chrome 156, nothing else using the GPU. Checks come from serial harness runs: a full pass over every effect (with mobile and reduced-motion re-run for all after the touch-scroll fix to the shell), full re-runs of the five optimised effects, then `tools/gpu-median.sh`. GPU ms are the **median of three** locked desktop sweeps per effect, from `tools/gpu-median.sh`. Per-check data is in `verify/<slug>/result.json` (each run is in `gpuMsRuns`), with the screenshots alongside; a related table (JS mean rather than p95, plus frame p95, presets and fuzz columns) is in `verify/REPORT.md`.

**24/24 effects pass every check.** Desktop sweep FPS at 2560×1440 is 59.3–60 (rAF is capped at 60 Hz; 59.3 is one late frame in the 1.5 s window), and the 390 px touch drag runs at 60 fps. Per-frame GPU reading, p95 (median of 3 runs): 13 effects ≤ 8 ms, 22 under the 12 ms proxy budget, library median 7.74 ms. JS p95 per frame is under 1 ms everywhere except `mercury-beads` (4.1 ms), `goo-trail` (1.1 ms), which simulate on the CPU by design (SPH particles and bead strands). Over the proxy: `morph-swarm` (14.2 ms; runs 16.79 / 12.85 / 14.2), `prism-bloom` (12.04 ms; runs 12.32 / 12.04 / 10.13). Both hold 60 fps with no long frames; see §8 and §9 lesson 25.

| Effect | Result | FPS | GPU ms mean / p95 | JS ms p95 | Idle | 390px touch fps | Touch scroll | Reduced | No WebGL2 | Embed |
|---|---|---|---|---|---|---|---|---|---|---|
| [Fluid Trail](effects/fluid-trail/) | **PASS** | 60 | 5.11 / 8.21 | 0.4 | stops after 7.1s | 60 | 385px | ✓ | ✓ | ✓ |
| [Silk Wake](effects/silk-wake/) | **PASS** | 60 | 4.84 / 7.76 | 0.5 | stops after 7.1s | 60 | 385px | ✓ | ✓ | ✓ |
| [Marbled Contours](effects/marbled-contours/) | **PASS** | 60 | 5.57 / 8.4 | 0.4 | stops after 7.1s | 60 | 385px | ✓ | ✓ | ✓ |
| [Vortex Street](effects/karman-wake/) | **PASS** | 60 | 5.83 / 8.94 | 0.4 | pauses off-screen | 60 | 385px | ✓ | ✓ | ✓ |
| [Sumi Bloom](effects/ink-drop/) | **PASS** | 59.3 | 5.05 / 8.59 | 0.3 | stops after 9.1s | 60 | 385px | ✓ | ✓ | ✓ |
| [Incense Wake](effects/incense-wake/) | **PASS** | 60 | 5.21 / 7.72 | 0.3 | stops after 7.1s | 60 | 385px | ✓ | ✓ | ✓ |
| [Ember Trail](effects/ember-trail/) | **PASS** | 60 | 5.12 / 9.41 | 0.4 | stops after 7.1s | 60 | 385px | ✓ | ✓ | ✓ |
| [Scorch](effects/scorch/) | **PASS** | 60 | 3.78 / 5.73 | 0.3 | stops after 11.4s | 60 | 385px | ✓ | ✓ | ✓ |
| [Mercury Pool](effects/flip-liquid/) | **PASS** | 60 | 5.73 / 9.58 | 0.7 | stops after 9.1s | 60 | 385px | ✓ | ✓ | ✓ |
| [Mercury Beads](effects/mercury-beads/) | **PASS** | 60 | 3.97 / 5.59 | 4.1 | stops after 8.1s | 60 | 385px | ✓ | ✓ | ✓ |
| [Viscous Glass](effects/ripple-glass/) | **PASS** | 60 | 3.66 / 5.49 | 0.3 | stops after 8.1s | 60 | 385px | ✓ | ✓ | ✓ |
| [Caustic Light](effects/caustic-filaments/) | **PASS** | 60 | 5.66 / 9.63 | 0.3 | pauses off-screen | 60 | 385px | ✓ | ✓ | ✓ |
| [Coral Wake](effects/coral-wake/) | **PASS** | 60 | 6.54 / 10.47 | 0.4 | stops after 8.4s | 60 | 385px | ✓ | ✓ | ✓ |
| [Goo Trail](effects/goo-trail/) | **PASS** | 60 | 3.32 / 5.95 | 1.1 | stops after 2.3s | 60 | 385px | ✓ | ✓ | ✓ |
| [Liquid Metal](effects/liquid-metal/) | **PASS** | 60 | 5.91 / 10 | 0.4 | stops after 8.1s | 60 | 385px | ✓ | ✓ | ✓ |
| [Curl Silk](effects/curl-silk/) | **PASS** | 60 | 4.69 / 6.95 | 0.3 | pauses off-screen | 60 | 385px | ✓ | ✓ | ✓ |
| [Morph Swarm](effects/morph-swarm/) | **PASS** | 60 | 9.66 / 14.2 | 0.3 | pauses off-screen | 60 | 385px | ✓ | ✓ | ✓ |
| [Neon Tubes](effects/neon-tubes/) | **PASS** | 60 | 4.33 / 5.82 | 0.8 | pauses off-screen | 60 | 385px | ✓ | ✓ | ✓ |
| [Wet Paint Smear](effects/liquid-smear/) | **PASS** | 60 | 4.72 / 7.13 | 0.3 | stops after 8.9s | 60 | 385px | ✓ | ✓ | ✓ |
| [Liquid Glass](effects/glass-droplet/) | **PASS** | 60 | 2.56 / 3.31 | 0.2 | stops after 7.1s | 60 | 385px | ✓ | ✓ | ✓ |
| [Prism Bloom](effects/prism-bloom/) | **PASS** | 60 | 7.53 / 12.04 | 0.3 | stops after 7.1s | 60 | 385px | ✓ | ✓ | ✓ |
| [Silk Mesh](effects/silk-mesh/) | **PASS** | 60 | 3.29 / 4.99 | 0.3 | pauses off-screen | 60 | 385px | ✓ | ✓ | ✓ |
| [Filament Wave](effects/filament-wave/) | **PASS** | 60 | 4.17 / 6.22 | 0.3 | pauses off-screen | 60 | 385px | ✓ | ✓ | ✓ |
| [Radiance Halo](effects/led-halo/) | **PASS** | 60 | 4.48 / 6.44 | 0.4 | stops after 7.1s | 60 | 385px | ✓ | ✓ | ✓ |

Warnings:

- `morph-swarm`: desktop: GPU p95 14.2ms (median of 3 runs) at 2560x1440
- `prism-bloom`: desktop: GPU p95 12.04ms (median of 3 runs) at 2560x1440
<!-- /gen:results -->

---

## 8. What couldn't be made to work, and known limitations

**Not built, because the research judged them infeasible at 60 fps at 1440p in single-file WebGL2:**
- **3D SPH/PBF beyond about 15–30k particles.** Without compute shaders, the neighbour search needs a sorting network of 100+ passes. The library uses 2D FLIP (`flip-liquid`) and 2D CPU SPH (`mercury-beads`) instead.
- **Full-resolution 3D screen-space fluid rendering** (the bilateral filter alone costs about 15–30 ms) and **full-resolution raymarched volumetric smoke/fire**. Smoke and fire are 2D sims: `incense-wake` lights its smoke as a 2.5D volume, and `ember-trail` renders emissive blackbody flames with bloom-lit smoke.
- **Liquid glass that refracts live DOM text.** WebGL cannot sample the DOM. Every refraction page (`glass-droplet`, `ripple-glass`, `liquid-smear`) paints its own hero into a canvas texture, and the overlays on real HTML are lighting/colour only.
- **MLS-MPM** (honey, frosting, impasto) was not built either, although it is not infeasible: the research rated 3D MLS-MPM feasible only with scaling (about 100–150k particles plus half-res rendering). Most verified implementations are WebGPU, though saharan's Water3D shows a WebGL2 GPGPU version exists.

**Partly met:**
- **`morph-swarm` stays above the 12 ms per-frame GPU reading** (median in §7), even though two optimisation rounds cut its real full-clock work by 41–46%, to about 3.3 ms in the heaviest frames. It holds 60 fps with no long frames. The cause is a measurement effect: on this M5 the per-frame reading stops tracking work above about 2–3 ms of full-clock load (§9, lesson 25). Reaching a reading under 10 ms would mean fewer particles, which visibly coarsens the letter grain, so we didn't do it.
- **`prism-bloom`** reads 12.0 ms p95 (median of runs from 10.1 to 12.3), right at the proxy line. It holds 60 fps, and no further optimisation round was run.
- **`incense-wake`** paints its own lit backdrop. The planned overlay variant (a premultiplied canvas over live page content) was not implemented.

**Known artifacts:** each page lists its own in "Performance & compatibility". The most visible:
- **Silk Wake:** a fast stroke across an older bundle can tear it into a short fan of dashes for about 1 s.
- **Neon Tubes:** very tight folds in dense bundles can show a small notch, because the tubes are drawn back to front without a depth buffer.
- **Mercury Pool:** a deliberate drag up across the copy carries a transient sheet of liquid over the paragraph, because the paddle is solid.
- **Viscous Glass:** a perfectly straight stroke is subtle on paper; curved strokes bend the type.
- **Radiance Halo:** soft grey smudges of 10–15 levels can appear beside some lit edges. That is the angular limit of 4 base rays.
- **Coral Wake:** on a portrait phone the intro band covers the hero text for a few seconds.
- **Vortex Street:** at combined extreme slider settings (Re ≈ 4,000) the dye shows hairy, under-resolved fringes. It stays stable.

**Limits of the verification itself:**
- **One machine and one browser.** Everything was measured in Chrome 156 on one Apple M5.
- **No real phones.** "Mobile" is 390×844 at DPR 3 emulation on the desktop GPU.
- **No Safari or Firefox runs.** iOS/WebKit lacks `EXT_float_blend`, which the effects avoid by design, but nothing was run there.
- **120/144 Hz behaviour was checked only by synthetic replays.** All physics is dt-based or fixed-step.
- **Headless rAF is capped at 60 Hz**, so FPS cannot show headroom. GPU readings are a relative signal (§9, lesson 25).
- **Per-page numbers differ.** Each page's own "Performance & compatibility" numbers come from its builder's runs, most of them on a GPU shared with other agents' harnesses (only the five optimised effects were re-measured under `tools/gpulock.sh`), so they can differ substantially from the canonical medians here.

---

## 9. Lessons learned

### The ten we started with (from the reference trail)

1. **Mix toward the pointer velocity with a capped grip; don't add velocity splats.** The fluid is left behind as a wake instead of being shoved.
2. **Normalise dye deposit by distance travelled per brush width**, so slow and fast strokes lay the same density.
3. **Splat a capsule from last frame's pointer to this frame's**, so fast strokes don't turn into dotted lines.
4. **Cut faint dye with a smoothstep alpha threshold**, so there is never haze.
5. **Stripes finer than about 20 px smear under semi-Lagrangian advection.** Go coarser, or use MacCormack/BFECC.
6. **Implicit Jacobi viscosity, (I − ν·dt·∇²)v = v₀, gives big syrupy swirls.**
7. **Keep a radial clear zone around the pointer plus a low grip**, so the effect never covers what you are about to click.
8. **On light backgrounds use height-field normals, Blinn-Phong, a colour ramp by thickness and a soft cast shadow.** Bloom only reads on dark.
9. **Engineering hygiene:**
   - dt-based physics
   - DPR cap of 2
   - stop the loop when idle
   - respect `prefers-reduced-motion`
   - fail gracefully without WebGL2 or `EXT_color_buffer_float`
10. **Taste:** big, smooth, genuinely fluid, about 3 s of staying power, viscous, rich depth, trailing behind the cursor, never blocking clicks.

### New lessons from research and from building 24 effects

**The benchmark and the field**

11. **The ServiceTitan Max hero is lit tubes, not a fluid.**
    - Its "liquid ribbons" are metalness-1 tubes with no environment map, so only the coloured point-light streaks show, and threshold-0 bloom turns them into filaments.
    - Reproducing it (`neon-tubes`) and answering it with a real fluid (`silk-wake`, `fluid-trail` ServiceTitan ribbon) were separate jobs.
12. **The best studios mostly hide the fluid** (§4.2). They use a coarse, cheap velocity field as a mask, a force or a distortion. `morph-swarm` uses that Igloo-style trick: it parts particles with an invisible wake.

**Frame rate and simulation steps**

13. **Per-frame constants break on 120 Hz displays.**
    - Every decay and lerp has to be `pow(k60, dt·60)` or `exp(−dt/τ)`.
    - Chained lags, as in tube followers, need exact substeps.
    - A fixed 60 Hz simulation step with an accumulator is safer than variable dt for advection, because 120 Hz semi-Lagrangian steps smear about 3× more.
14. **Pre-roll the simulation before the first paint.** Several effects simulate 1–1.6 s of autopilot before the first visible frame, so the page opens already beautiful instead of on a growing dot:
    - `ink-drop`: 96 steps
    - `incense-wake`: 1.4 s
    - `coral-wake`: 30 frames

**GPU formats and the WebGL2 platform**

15. **Blending into RGBA32F is not portable.** Safari/WebKit (including iOS) does not expose `EXT_float_blend` (WebKit bug 247240), so scatter (P2G, splats) goes into RGBA16F, and positions stay in RGBA32F read with `texelFetch`.
    - Chrome on this M5 *does* expose `EXT_float_blend`, and additive blending into RGBA32F works there (checked directly). The research had attributed the limit to Apple GPUs; it is a browser limit.
    - An RG32F displacement field even broke the warp under ANGLE/Metal, so offsets stay in RG16F.
    - Store offsets, not absolute UVs: half-float near 1.0 resolves only about 1.25 px at 2560 wide.
16. **fp16 precision is a design input.** Reaction-diffusion stores (1−A, B), because A sits near 1 where fp16 is coarse.
17. **WebGL can't refract or sample the DOM.**
    - Every refraction and distortion effect paints its own hero into a canvas texture.
    - Effects over live HTML (`fluid-trail`, `goo-trail`, `coral-wake`, `ember-trail`) must be lighting or colour overlays with `pointer-events:none`.

**Advection and solvers**

18. **Second-order advection has failure modes.**
    - MacCormack's correction over many LBM substeps per frame (dye moving many cells per pass) produced lattice-scale teeth in `karman-wake`, and an RK2 trace fixed it.
    - The min/max clamp limiter is not optional.
19. **Spend solver iterations only where they show.**
    - `silk-wake`'s residual divergence fell from 60% at 6 pressure sweeps to 44% at 10 and 31% at 16, but replays at 6 and 10 sweeps looked the same, so it stays at 6.
    - Lattice Boltzmann steps cost about 0.03 ms each almost regardless of grid size, so `karman-wake` traded resolution for steps.

**Measuring and budgeting on ANGLE/Metal**

20. **Pass count is a budget of its own.**
    - A frame crossing about 16 render passes cost about 4 ms more on this machine.
    - Per-draw timer queries add about 1.5 ms each and split command buffers, so profile whole frames over N frames.
    - Chrome's `getBufferSubData` is a synchronous round trip: read back rarely and small (`flip-liquid` reads 128×16 every 4th frame).
21. **Never trust GPU numbers from a shared GPU.**
    - `TIME_ELAPSED` includes other clients' work, and concurrent harnesses swung the same build 2–3×.
    - Canonical numbers need a serial run or a lock (`tools/gpulock.sh`).
    - Mid-drag full-resolution screenshots also depress the measured touch FPS (46 vs 60), so the harness now times drags without them.

**Look and interaction**

22. **Haze and milky films are the main enemy of "premium".** The fixes that worked:
    - gate broad sheen by paint luminance on dark backgrounds (`liquid-smear`)
    - use only the grazing part of Fresnel (F − F₀) so glass centres stay clear (`glass-droplet`)
    - cut by optical depth, not density (`incense-wake`)
    - draw iso-lines from distance, not threshold (`marbled-contours`)
23. **Strokes need state across hitches.**
    - A pause of more than 150 ms between pointer events starts a new stroke, and page-load hitches or screenshots then break ribbons into "pills".
    - Effects that carry state along a stroke (troughs, ribbons, ink pours) must bridge gaps.
24. **A full-screen stage that takes every touch traps phone users.**
    - The shell now keeps the stage at 88svh on coarse pointers, so a strip of the page below stays scrollable.
    - The harness checks this with a touch swipe.
25. **On Apple GPUs the per-frame GPU timer reports something closer to "how long the GPU took at whatever clock it chose" than to "how much work this frame is".**
    - **The calibration.** We drew a fixed, blended shader load whose cost at full clock is known: K draws back to back in one query, with blending on, so tile-based hidden-surface removal can't skip any of them.
    - **Light loads are inflated 2.5–4.5×.** Full-clock loads of 0.5 / 1.0 / 1.8 / 2.6 ms read 1.4 / 4.1 / 4.7 / 6.5 ms mean (1.6 / 4.3 / 7.5 / 9.7 p95) when timed once per 60 Hz frame. The GPU evidently clocks down when it has slack.
    - **Heavier loads plateau.** The `morph-swarm` optimiser measured synthetic loads from 3.3 to 6.3 ms all reading about 10.5–11 ms mean and 13–14 ms p95.
    - **Run-to-run spread** for the same build is typically 1–3 ms, and up to about 6 ms p95 in the canonical runs (coral-wake 9.53–15.72, fluid-trail 6.37–11.94).
    - **What this means for the numbers:**
      - the readings in this atlas are conservative, relative numbers
      - the canonical value is the median of 3 serial runs (`tools/gpu-median.sh`)
      - the "< 12 ms p95" budget is a proxy, not the real limit
      - a page that reads 12–13 ms while holding 60 fps with no long frames is still using well under the frame time at full clock
    - **For absolute cost**, time K back-to-back frames or passes in one query, and keep blending on or vary the inputs so tile-based hidden-surface removal can't discard repeated opaque draws. Our own first calibration made that mistake and under-read 10×.

### Shell and harness gaps the builders reported (future work)

Builders worked around these in effect code. All are small API additions:
- `onIdle(reason)`, or separate pause/idle hooks, to tell an inactivity stop from an off-screen or hidden-tab pause.
- `onTheme`, `onFail` and `onResume` hooks.
- A control-state API (disable or annotate a control from effect code).
- A first-class pre-roll hook.
- A `fresh` flag on `pointer.segment()`.
- MRT and async-readback (PBO + fence) helpers in the GL kit.
- A per-device param schema.
- A text-input control.
- Harness options:
  - a fixed-step virtual clock for deterministic A/B replays
  - timed intro screenshots (+100 ms, +1 s, +2 s)
  - a single-stroke staying-power probe
  - a scripted fast-reversal test
  - a high-refresh (120/144 Hz) rAF mode
  - `--nofloat` and `--nomsaa`
  - configurable poster timing

---

## 10. References and credits

`research/INDEX.md` holds the de-duplicated list of research references: 113 code repositories and packages, 101 papers and articles, 56 demos and 41 sites. Every GitHub licence was checked with `gh api` and every URL was fetched on 2026-10-30. Each effect page has its own references and credits, with licences, in its "How it works" section.

**Foundational papers:**
- Jos Stam, "Stable Fluids", SIGGRAPH 1999 — https://www.dgp.toronto.edu/public_user/stam/reality/Research/pdf/ns.pdf
- Mark Harris, "Fast Fluid Dynamics Simulation on the GPU", GPU Gems ch. 38 — https://developer.nvidia.com/gpugems/gpugems/part-vi-beyond-triangles/chapter-38-fast-fluid-dynamics-simulation-gpu
- Fedkiw, Stam, Jensen, "Visual Simulation of Smoke", SIGGRAPH 2001 (vorticity confinement) — https://web.stanford.edu/class/cs237d/smoke.pdf
- Selle et al., "An Unconditionally Stable MacCormack Method", 2008 — https://yingjie.math.gatech.edu/publications/SFKLR.pdf
- Kim et al., "FlowFixer: Using BFECC for Fluid Simulation", 2005 — https://faculty.cc.gatech.edu/~jarek/papers/FlowFixer.pdf
- Jiang et al., "The Affine Particle-In-Cell Method", 2015 — https://www.math.ucdavis.edu/~jteran/papers/JSSTS15.pdf
- Macklin & Müller, "Position Based Fluids", 2013 — https://mmacklin.com/pbf_sig_preprint.pdf
- Nguyen, Fedkiw, Jensen, "Physically Based Modeling and Animation of Fire", 2002 — https://cseweb.ucsd.edu/~henrik/papers/fire/
- Bridson, Hourihan, Nordenstam, "Curl-Noise for Procedural Fluid Flow", SIGGRAPH 2007 — https://www.cs.ubc.ca/~rbridson/docs/bridson-siggraph2007-curlnoise.pdf
- J. Pearson, "Complex Patterns in a Simple System", Science 1993 — https://arxiv.org/abs/patt-sol/9304003
- Tessendorf, "Interactive Water Surfaces" (iWave) — https://jtessen.people.clemson.edu/reports/papers_files/Interactive_Water_Surfaces.pdf
- Evan Wallace, "Rendering Realtime Caustics in WebGL", 2016 — https://medium.com/@evanwallace/rendering-realtime-caustics-in-webgl-2a99a29a0b2c
- Inigo Quilez, "Smooth minimum" — https://iquilezles.org/articles/smin/
- Alexander Sannikov, radiance cascades (jason.today's walkthrough) — https://jason.today/rc

**Open-source code adapted (licences kept in the page source and credits):**
- PavelDoGreat/WebGL-Fluid-Simulation (MIT) — https://github.com/PavelDoGreat/WebGL-Fluid-Simulation.
  - `fluid-trail` adapts the reference trail's simulation shaders (curl, vorticity confinement, advection, divergence, Jacobi pressure, gradient subtract) and their pass order from it, with the full MIT notice in the effect's header comment.
  - Several other grid-fluid pages follow the same pass layout and credit it.
- Stefan Gustavson & Ian McEwan, psrdnoise (MIT) — https://github.com/stegu/psrdnoise. The 2D function, non-tiling, is used in `curl-silk`.
- Ian McEwan, Ashima Arts & Stefan Gustavson, webgl-noise (MIT) — https://github.com/stegu/webgl-noise. 3D simplex noise is used in `silk-mesh`.
- Inigo Quilez, "Round Cone - distance 3D", Shadertoy `tdXGWr` (MIT) — https://www.shadertoy.com/view/tdXGWr. `liquid-metal` adapts sdBlob.
- Dave Hoskins, "Hash without Sine" (MIT) — https://www.shadertoy.com/view/4djSRW. 13 of the 24 pages use it for dither or noise, each crediting it in its references (most also in a shader comment).

Everything else was written from scratch, from papers, articles and the observed behaviour of the reference sites.

**Licence policy.** We never pasted non-commercial (CC BY-NC-SA, including Shadertoy's default), GPL, Prosperity, or all-rights-reserved code into a page. Those references were read for ideas only. We never copied proprietary site code: the ServiceTitan, Stripe, Vercel and Lusion techniques are reimplemented from their documented behaviour.
