Nocturne Baths — Fluid Splash Cursor

Fluid Splash Cursor (page-level GPU Navier–Stokes overlay)

Goal

Build a page whose pointer drags liquid ink across the entire document — not inside a hero box, not behind the content, but on a transparent full-window layer that composites over headlines, tables, borders and photographs alike. Moving the pointer pushes a force and a puff of dye into a fluid simulation running on the GPU; the ink curls, spreads and dissipates on its own. Clicking bursts. The page underneath is never touched: no blend mode inverts it, no canvas covers it, no listener steals its clicks.

The demo dress is Nocturne Baths № 4, a municipal swimming pool that only opens after dark.

Tech

Vanilla HTML/CSS/JS. No library at all — not GSAP, not three.js, not a shader loader. Raw WebGL2 with a WebGL1 fallback, one requestAnimationFrame loop, ES module syntax so it drops into a bundler or a plain <script type="module"> unchanged. The whole solver is one exported function:

const fluid = splashCursor({ curl: 12, densityDissipation: 3, color: "#ff0000" });

If you are tempted to reach for three.js: don't. The entire GPU side is ten fragment shaders and a fullscreen quad — copy, clear, splat, advection, divergence, curl, vorticity, pressure, gradient-subtract and display — and pulling in a scene graph to draw a quad triples the bundle for nothing.

The mechanic

What a fluid solver actually is here

Two fields live in floating-point textures:

• velocity — a low-resolution vector field (128 on the short side is plenty; it is a force field, nobody sees it)
• dye — the visible ink, high resolution (1440 on the short side), because this one *is* seen

Every frame, in this exact order:

1. curl — measure the local rotation of the velocity field
2. vorticity confinement — push energy back into the small eddies the numerics keep eating, so the ink keeps curling instead of going smooth and dead. This is the curl parameter, and it is the single knob that decides whether the effect reads as *smoke* or as *paint*
3. divergence — measure where the field is compressing
4. pressure decay, then 20 Jacobi pressure iterations — solve for a pressure field that cancels that compression
5. gradient subtract — remove the pressure gradient from velocity, which is what makes the fluid incompressible and therefore *swirl* instead of pile up
6. advect velocity, then advect dye — semi-Lagrangian: for each texel look *backwards* along the velocity field and fetch what used to be there. Unconditionally stable at any timestep, which is why the effect survives a dropped frame

Each advection divides by 1 + dissipation * dt, and that is the whole of "fading".

Everything is double-buffered: you cannot read and write the same texture in one pass, so every field is a read/write pair that swaps after each blit.

The splat

A splat is a gaussian added to a target, written by one shader used twice:

vec2 p = vUv - point.xy;
p.x *= aspectRatio;              // or the splat is an ellipse on a wide window
vec3 splat = exp(-dot(p, p) / radius) * color;
gl_FragColor = vec4(texture2D(uTarget, vUv).xyz + splat, 1.0);

First into velocity, where the "colour" is the force vector (dx, dy) * splatForce. Then into dye at the same point, where the colour is ink. Same shader, two targets — that is the whole input path.

The part that makes it an OVERLAY rather than a background

This is what separates it from every fluid hero you have seen. Three things, all load-bearing:

canvas.getContext("webgl2", { alpha: true, preserveDrawingBuffer: false });

float a = max(c.r, max(c.g, c.b));    // alpha comes from the ink's own brightness
gl_FragColor = vec4(c, a);            // premultiplied

gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);

Unpainted water has zero brightness, therefore zero alpha, therefore the document shows through untouched. Painted water composites *over* it. And nothing ever clears the drawing buffer by hand: with preserveDrawingBuffer: false the browser wipes it to transparent black between frames, which is exactly the behaviour we want. Turn preservation on "to be safe" and the ink smears permanently across the screen.

The fourth thing is not a flag but a number: intensity, which scales every dye colour down to ~15%. At full value the splats are opaque paint and the page dies underneath them.

Shading

Optional, on by default, and cheap: take the gradient of the dye field's own brightness, treat it as a surface normal, dot it with a head-on light. The ink gains volume and stops looking like an airbrush. It is a #define in the display shader, so switching it needs a re-link, not a uniform.

Layout / HTML

A page-level overlay needs a page to be over. Three screens, all CSS — no images anywhere, so the only thing the fluid can be compositing with is ordinary document content:

<body>
  <header class="chrome">…mark, three links, "Open until 02:00" with a pip…</header>

  <main id="top">
    <section class="basin">
      <div class="tiles"></div>   <!-- pool floor: two repeating-linear-gradients -->
      <div class="lamp"></div>    <!-- one blurred radial: a sodium lamp -->
      <div class="basin-copy">
        <p class="eyebrow">Municipal Baths № 4 · Ostend · since 1934</p>
        <h1>The water is<br />warmest at<br /><em>one in the morning.</em></h1>
        <p class="lede">…two sentences…</p>
        <p class="hint"><span class="hint-dot"></span>Move your hand across the surface</p>
      </div>
      <div class="gauge">…four readouts: surface, air, salinity, swimmers…</div>
      <div class="dial">
        <span class="dial-label">Water</span>
        <button data-water="still">Still</button>
        <button data-water="wake" class="is-on">Wake</button>
        <button data-water="riptide">Riptide</button>
        <span class="dial-label">Dye</span>
        <button data-dye="spectrum" class="is-on">Spectrum</button>
        <button data-dye="sodium">Sodium</button>
      </div>
    </section>

    <section class="waters">…four pools, each a row: numeral, name, temperature, depth…</section>
    <section class="hours">…four opening slots in a hairline grid…</section>
    <footer class="foot">…"Season keys are issued on the first cold night." + a pill CTA…</footer>
  </main>
</body>

The tiled floor is not decoration. Dye over a flat field reads as a smudge; dye crossing grout lines reads as water. A 64px grid of 1px hairlines under a radial mask is enough, and it costs nothing.

Dress

Ostend, 1934, a glass-roofed pool open only between 21:00 and 02:00.

• Ground #06090c night, #0a1218 basin, #0e1a22 tile — nearly black, because the ink is additive and needs somewhere dark to glow
• Ink #e7edee bone, #78898f dim
• Accent #ffb45a, a sodium poolside lamp. Exactly one accent: the dye already brings every hue there is, and a second brand colour turns the page into noise
• Type Bricolage Grotesque for the voice (wdth 82, opsz 96, wght 620 on the display; the italic at wght 380 for the amber line) and Azeret Mono for every readout, label and button. A municipal bath is signage and instrumentation before it is design
• Display at clamp(2.3rem, 5.4vw, 4.6rem), line-height 0.94, tracking −0.028em

Config

Everything is an option with a real default. The three presets on the page are the same solver, named after water instead of after parameters, because nobody browsing knows what vorticity confinement feels like until they see it:

const WATERS = {
  still:   { curl: 2,  densityDissipation: 1.6, velocityDissipation: 1.4, splatForce: 4200, splatRadius: 0.28 },
  wake:    { curl: 12, densityDissipation: 3,   velocityDissipation: 2.4, splatForce: 6000, splatRadius: 0.2  },
  riptide: { curl: 34, densityDissipation: 4.4, velocityDissipation: 3.8, splatForce: 7400, splatRadius: 0.14 },
};

| option | default | what it does | |---|---|---| | simResolution | 128 | velocity/pressure grid, short side | | dyeResolution | 1440 | the visible ink. This is the expensive one | | densityDissipation | 3.5 | how fast the ink fades | | velocityDissipation | 2 | how fast the motion stops | | pressure | 0.1 | how much pressure survives each frame | | pressureIterations | 20 | below ~12 the flow goes blocky | | curl | 3 | vorticity confinement: the swirl | | splatRadius | 0.2 | | | splatForce | 6000 | | | shading | true | fake normals from the dye gradient | | colorUpdateSpeed | 10 | hue re-rolls per second while rainbow | | rainbow | true | cycle hues, or hold color | | color | "#ff0000" | used only when rainbow is false | | intensity | 0.15 | master dye level | | maxDpr | 2 | | | idleStopMs | 4000 | stop the loop this long after the last input | | respectReducedMotion | true | | | zIndex | 50 | | | mount | document.body | |

The controller it returns: { canvas, config, running, splat(x, y, dx, dy, color?), set(partial), destroy() }. splat takes CSS pixels in viewport coordinates; dx/dy are a push in the same units the solver uses internally, so compute them the way a real pointer does — travel as a fraction of the window, times splatForce — or a scripted trace hits ten times harder than a hand and the ink comes out as a bruise. The dye field is y-up and the DOM is y-down, so a push downward on screen is a *negative* dy; and correct both components by aspect ratio the way the internal handler does (dx *= aspect when aspect < 1, dy /= aspect when aspect > 1) or a vertical flick pushes harder than a horizontal one of the same length.

Behaviour worth building deliberately

Attract mode, and the cap it must have. A page whose only effect is pointer-driven shows *nothing* until someone moves the mouse — and on a phone, where there is no hover, possibly never. So the basin traces itself, on a Lissajous with two incommensurate frequencies so the stroke never retraces itself and never settles into a loop that piles dye into one blob:

const x = box.left + box.width  * (0.44 + 0.40 * Math.sin(t * 5.6));
const y = box.top  + box.height * (0.34 + 0.22 * Math.sin(t * 7.3 + 0.6));
fluid.splat(x, y, ((x - px) / innerWidth) * force, (-(y - py) / innerHeight) * force);

It ends in one of two ways, and both are required:

• a real pointermove or pointerdown takes over — the invitation was answered, so fade the hint out with it and never come back;
• or a hard time cap (12 s) — and this one is the whole ballgame. Every traced splat resets the solver's idle timer, so a trace with no end feeds the loop *for ever*, and it does that hardest in exactly the case the trace exists for: a phone nobody touches, left open at the top of the page. Without the cap, "leave it alone and the GPU work stops" is false on the one device where it matters. On this exit leave the hint up: nobody was there to read it.

Measured on the finished page, untouched: draws continue while the trace runs, keep going through the solver's four-second idle window, and hit zero from about 17 s onward.

The click burst. A pointerdown writes one splat, not a stroke: the same colour multiplied by 10 and a random kick of 10 * (Math.random() - 0.5) horizontally and 30 * (Math.random() - 0.5) vertically. It exists so that tapping does something on a touchscreen, where there is no hover to trail from. Seed the pointer's position from the same event first, then suppress the move-splat, or the tap fires twice.

Idle stop. Cancel the rAF four seconds after the last pointer input; any movement or splat() call restarts it. This is the difference between a decorative canvas and a laptop fan, and it is the single most valuable thing to add to any port of this effect.

Reduced motion. The ink keeps swirling and the hue keeps cycling after the hand has stopped, so this is autonomous motion, not a direct response to input. Under prefers-reduced-motion: reduce mount nothing — return the same shape of controller (canvas: null, running: false, no-op splat/set/destroy) so callers do not have to branch — and make sure the page reads without it. That includes hiding the hint in CSS: "Move your hand across the surface" invites an interaction that, under this setting, does not exist.

Cleanup. destroy() removes every listener, cancels the frame, deletes every framebuffer and texture, drops the two buffers and calls WEBGL_lose_context. Also listen for webglcontextlost and stop, rather than looping against a dead context.

Traps

• The first pointer event has no previous position. Its delta is measured from (0, 0), which is the whole screen, which is one enormous splat wherever the pointer entered. Seed the previous coordinates on the first event and emit nothing.
• preserveDrawingBuffer: true smears the ink permanently. It looks like a bug in the dissipation; it is not.
• A resize keeps the ink and throws away the maths. dye and velocity are copied into the new size with the copy shader — losing them means the picture blinks out mid-stroke — while pressure, divergence and curl are simply recreated at zero, because they are rebuilt from scratch every frame anyway. Free the targets you replace: a resize that only allocates leaks two textures and two framebuffers per double buffer, every time.
• Clamp dt. dt = min((now - last) / 1000, 1/60). Advection is stable at any timestep, but a tab that was backgrounded for two seconds hands you a two-second step and the whole field jumps.
• **Device pixel ratio must be capped *and* recomputed.** A 3× phone buffer is 2.25× the pixels of a 2× one for no visible gain in a blurry fluid. And capturing the ratio once means dragging the window to a different display desyncs the pointer from the buffer — the classic version of this bug in every fluid port.
• Half-float render targets are not guaranteed. Probe each format with a 4×4 test attachment and fall back R16F → RG16F → RGBA16F. Without linear filtering, advection has to interpolate by hand (#define MANUAL_FILTERING) and the dye buffer must drop to 256 or the page crawls.
• idleStopMs must exceed the dye's visible lifetime. At any sane dissipation the ink is long gone before four seconds; push densityDissipation below ~0.5 and the last trail will freeze on screen until the pointer moves again.
• Resolution is the SHORT side, and the long side follows the aspect ratio. Hard-code a square and splats become ellipses on a wide window.
• pointer-events: none on the canvas is not optional. It is a fixed, full-window element at z-index 50; without it the entire document becomes unclickable.
• The overlay is only over what is below its z-index. A modal or a fixed nav at z-index 100 will sit on top of the ink and the effect will look like it stops at that element. That is why the z-index is a constructor option and not a constant.
• On a light ground, lower intensity. The same value that reads as a glow on black reads as a stain on paper.

Definition of done

Move the pointer anywhere on the page and coloured ink follows it, curls behind it and dissolves — over the headline, over the pool table, over the footer, with the text still perfectly legible through it. Click and it bursts. Press *Riptide* and the same stroke becomes tighter and more filamentary; press *Sodium* and every hue collapses to one amber. Leave it alone for five seconds and the GPU work stops completely; move again and it resumes instantly. Under prefers-reduced-motion there is no canvas in the DOM at all and the page is still a page.

Adapting this to React

Everything above describes a mount(config) that already returns exactly what a useEffect cleanup wants: it calls splashCursor() to get a fluid controller with its own destroy(), wires the six preset buttons and the attract-mode trace on top of it, and hands back one function that unwinds all three. What's missing isn't machinery, it's an owner — the dispatch that currently invokes mount() runs at import time, gated on nothing but window.MP, and every DOM lookup inside it assumes the whole document belongs to this component.

Under React 19 with StrictMode, every effect mounts, unmounts, and mounts again before anything reaches the screen. Call mount() a second time without first running the cleanup the first call returned, and you get two of everything at once: two position: fixed; inset: 0 canvases stacked at the same z-index, each running its own WebGL2 context, its own solver loop, and its own window pointer listeners, so one mouse move splats ink into two independent dye fields on two independently-rolling rainbow timers — the colour under the cursor stops being a single hue. Both copies also wire the same six [data-water]/[data-dye] buttons, so one click toggles two solvers at once, and both run their own attract-mode trace over the same basin at the same time. None of this throws, and none of it reproduces in a production build — only development double-invokes the effect — which is exactly why it survives review: the ink still looks right, just doubled.

*(1) The entry point* — the module ends with if (window.MP && window.MP.register) { window.MP.register(...) } else { mount(Object.assign({}, KNOB_DEFAULTS)) }. window.MP is this catalogue's own editor bridge; it won't exist in a React host, so this always falls to the else branch and runs the instant the module is evaluated — before this component's own JSX, the header/basin/dial markup mount() depends on, has committed anything. Unlike a lookup that throws on a missing container, this one fails quietly in two different ways at once: splashCursor() doesn't need any of that markup — it defaults its own mount target to document.body and appends a canvas there directly — so the fluid overlay actually starts and tracks the pointer correctly from the very first paint, while document.querySelector(".hint")/".basin" return null and the document.querySelectorAll("[data-water]")/"[data-dye]" loops run over empty, already-captured NodeLists and wire nothing, permanently. The attract-mode trace doesn't even get that far: with stage undefined, stage?.getBoundingClientRect() is undefined too, so the very first scheduled frame satisfies !box and calls stopDrift() before a single splat is drawn. The ink works from the first paint; the buttons and the self-drawing hint never will. Move the whole body — dropping the window.MP dispatch entirely — into a useEffect with an empty dependency array, and only call it once this component's own markup is on the page.

*(2) Element lookups* — not every lookup here wants the same fix. The pointermove/pointerdown/touchmove/resize listeners splashCursor() binds to window and document are supposed to stay unscoped: this component's entire premise is a page-level overlay, and confining pointer tracking to a container would undo the one thing the rest of this prompt is about. What does need a root ref is the furniture mount() itself queries — .hint, .basin, [data-water], [data-dye] — since those are elements this component renders. Give the component a root ref, render the header/basin/dial markup under it, and query those four off the ref instead of document; during the StrictMode remount two copies of that markup exist for an instant, and an unscoped querySelectorAll will happily wire buttons on the copy that's on its way out.

*(3) Cleanup* — there's no GSAP, ScrollTrigger, Lenis, or SplitText anywhere in this file, and nothing here awaits a promise — no texture, no font, no fetch — so those variants don't apply. What has to survive the port intact is the teardown mount() already assembles out of two independent requestAnimationFrame loops and two independent sets of window listeners, and the discipline needed is narrow: use the exact function mount() returns as the effect's cleanup, not a shorter one written by hand.

Two rAF loops, not one

fluid.destroy() only unwinds what splashCursor() itself created: its own solver loop, its own pointermove/pointerdown/touchmove/resize listeners, its framebuffers, and — critically — the WebGL2 context itself, released through WEBGL_lose_context. It knows nothing about the attract-mode trace() loop mount() layers on top, which has its own requestAnimationFrame handle (drift), its own twelve-second setTimeout (expira), and its own pair of window hand-off listeners (tomaElRelevo, on pointermove and pointerdown) that exist only to notice a real pointer arriving. Cleaning up only fluid leaves all of that running: a second mount adds a second attract trace racing the first over the same basin, and the hand-off listeners keep multiplying on every remount. Worse, because fluid.destroy() is also the only thing that frees the live WebGL2 context, skipping it doesn't just leak DOM listeners — it leaks a GPU context per skipped remount, and browsers cap how many of those can exist at once; eventually a later mount's own canvas.getContext("webgl2", ...) call returns null and the whole effect goes dark, canvas and all, with nothing in the console to explain why. Call stopAttract() and offs.forEach((off) => off()) in the same cleanup, exactly as mount()'s own returned function already does — do not reach past it and call fluid.destroy() directly, or you keep the fluid and lose everything mount() built on top of it.

Where the canvas actually lives

The canvas is position: fixed; inset: 0, and config.mount defaults to document.body — splashCursor() appends it there itself rather than into any JSX tree. Keep doing that from inside the effect rather than rendering <canvas> bound by a ref: a fixed-position element's containing block becomes the nearest ancestor with a CSS transform, filter, or perspective instead of the viewport, so if this component's root ever ends up nested under an animated wrapper elsewhere in the app — a parallax section, a page-transition container — a JSX-rendered fixed canvas would start covering only that ancestor's box instead of the whole document, and "ink over the entire page" would quietly become "ink over one card." Appending straight to document.body (or to another explicit, untransformed node passed through config.mount) sidesteps that regardless of where the React component itself renders, and lets destroy()'s own canvas.remove() stay the only thing that ever touches its place in the tree.