@3driseai/3drise-viewer 0.1.17 → 0.1.19

package/dist/components/particles/BioluminescentWakeParticles.js

@@ -0,0 +1,1145 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { useFrame } from '@react-three/fiber';
+import { GENERATIVE_PARTICLES_ANIMATABLE } from '@3driseai/3drise-core';
+import { applyConfigKeyframeAnimations } from '../../utils/configAnimations.js';
+import { createPointerUniforms, stepPointerField, usePointerField } from '../../utils/pointerField.js';
+import { createTrailUniforms, applyTrailConfig, createCpuTrail } from '../../utils/particleTrails.js';
+import { useObjectReady } from '../../hooks/useObjectReady.js';
+import { useConfigLiveHandle } from '../../hooks/useConfigLive.js';
+/**
+ * Sea Sparkle — Bioluminescent plankton that flash when the water shears: swell orbits, excitable cells that tire and recover, moon glitter; the cursor is a hand, falling pebbles or a hunting fish. Use for night sea and fantasy scenes.
+ */
+// Sea Sparkle — bioluminescent plankton in a moonlit sea.
+// Movement: plankton are passive tracers. Linear deep-water swell (two Gerstner waves, deep-water
+//           dispersion w = sqrt(g k)) moves each cell on its closed orbital ellipse, amplitude
+//           A e^{k y}; the cloud drifts with a slow current. Noctiluca are buoyant, so cells sit in an
+//           exponential layer under the surface.
+// Colour:   mechanically stimulated luminescence. Every cell is an excitable unit: when the local
+//           shear rate of the water exceeds its threshold (lognormal across cells) it flashes
+//           (luciferin blue, ~0.2 s decay), spends part of its reserve and needs `recovery` seconds
+//           to recharge — so wakes glow bright once and fade as the cells tire. Light leaving deeper
+//           cells is absorbed (exp(-c depth)), shifted toward `deepColor` and widened by forward
+//           scattering. The surface is a moon-glitter layer: Cox–Munk style micro-facets on the
+//           same swell, glinting where a facet's normal bisects moon and eye.
+// Mouse (pointerMode; the cursor lives on the water plane):
+//   hand   — a swimmer's hand: moving-sphere potential flow (dipole) + wake; shear ~ 3 U R^3 / r^4
+//            lights a sheath around the stroke and a glowing wake behind it. A still hand is dark.
+//   pebble — pebbles dropped along the cursor path: a splash burst, a sinking pebble trailing a wake,
+//            and capillary–gravity ripple packets whose crests light expanding rings.
+//   fish   — a fish that hunts the cursor (cruises in a circle when the cursor rests): the shear in
+//            its boundary layer outlines the body in light and its tail sheds a reverse Karman street
+//            of vortices that stir a glowing, swirling wake.
+// Trails (trailMode): streak = long exposure, comet = glow threads, echo = afterglow — only
+//           glowing cells leave light (TRAIL_K = emission).
+//
+// Generated from the approved lab module (particle lab, batch 2). Sim units = object-local / size.
+/** mulberry32 — seeded PRNG, returns a function giving floats in [0,1). */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return function () {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** Standard normal from a uniform PRNG (Box–Muller, one value per call). */
+function gauss(rng) {
+    const u = Math.max(rng(), 1e-9);
+    const v = rng();
+    return Math.sqrt(-2 * Math.log(u)) * Math.cos(6.283185307 * v);
+}
+/** Viewport-height hook so point sizes are pixel-correct at any canvas size. */
+function attachViewH(obj, u) {
+    const scratch = new THREE.Vector2();
+    obj.onBeforeRender = (renderer) => {
+        renderer.getDrawingBufferSize(scratch);
+        u.uViewH.value = scratch.y;
+    };
+}
+function colorUniform(hex) {
+    return { value: new THREE.Color(hex) };
+}
+/** Quality levels scale counts, raymarch samples and trail caps. Structural. */
+const QUALITY_SCALE = { low: 0.5, medium: 1, high: 1.6 };
+function qualityScale(q) { return QUALITY_SCALE[q] || 1; }
+/** Mix the object's own base seed with the `seed` knob into a mulberry32 seed. */
+function seedMix(base, seed) {
+    let h = (base ^ Math.imul((Math.round(seed) | 0) + 0x9e37, 0x85ebca6b)) >>> 0;
+    h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35) >>> 0;
+    return (h ^ (h >>> 16)) >>> 0;
+}
+/** Fixed-step clock: the same motion at 30, 60 or 144 Hz. `run(d, step)` advances d sim-seconds
+ *  in steps of exactly H (at most maxSteps per call; a longer backlog is dropped, not caught up). */
+function createFixedStep(H, maxSteps) {
+    let acc = 0;
+    return {
+        H,
+        run(d, step) {
+            acc += Math.max(d, 0);
+            let k = 0;
+            while (acc >= H && k < maxSteps) {
+                step(H);
+                acc -= H;
+                k++;
+            }
+            if (k === maxSteps)
+                acc = Math.min(acc, H);
+            return acc / H; // leftover fraction, for render interpolation
+        },
+        reset() { acc = 0; },
+    };
+}
+/** Selection bounds: an invisible sphere the editor can pick, frame and size (never rendered,
+ *  still raycastable and counted by Box3.setFromObject). */
+function createPickProxy(center, radius) {
+    const geo = new THREE.SphereGeometry(1, 16, 10);
+    const mat = new THREE.MeshBasicMaterial({ visible: false });
+    const mesh = new THREE.Mesh(geo, mat);
+    mesh.name = 'pickProxy';
+    mesh.position.set(center[0], center[1], center[2]);
+    mesh.scale.setScalar(radius);
+    return { mesh, dispose() { geo.dispose(); mat.dispose(); } };
+}
+const _frustum = new THREE.Frustum();
+const _pm = new THREE.Matrix4();
+const _sphere = new THREE.Sphere();
+/** Off-screen test: false when the object's bounding sphere is outside the camera frustum. */
+function inView(object, camera, center, radius, size) {
+    if (!camera || !camera.projectionMatrix)
+        return true;
+    object.updateWorldMatrix(true, false);
+    _sphere.center.set(center[0], center[1], center[2]).multiplyScalar(size).applyMatrix4(object.matrixWorld);
+    _sphere.radius = radius * size * object.matrixWorld.getMaxScaleOnAxis();
+    _pm.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+    _frustum.setFromProjectionMatrix(_pm);
+    return _frustum.intersectsSphere(_sphere);
+}
+const POINTER_MODES = ['hand', 'pebble', 'fish'];
+const HX = 1.0; // half width of the sea patch (sim units)
+const D = 0.3; // depth of the plankton layer
+const LAYER = 0.06; // e-folding depth of the buoyant cell layer
+const G = 0.981; // sim gravity: 1 sim unit ~ 10 m of sea, so the swell is slow and calm
+const H_STEP = 1 / 30;
+const TH0 = 1.5; // median shear threshold (1/s) at sensitivity 1
+const MAX_PEBBLES = 6;
+const MAX_VORT = 16;
+const RIP_C = 0.3; // ripple packet speed
+const RIP_L = 0.05; // ripple crest spacing
+const ANCHOR = [0, -0.035, 0];
+// seconds of water motion per trail second, per trail type (cells drift a few cm/s; a flash lasts 0.2 s)
+const TRAIL_SCALE = { streak: 3.5, comet: 2.5, echo: 1 };
+const TRAIL_GAIN = { streak: 0.55, comet: 1, echo: 3.5 }; // even out the three looks
+const BOUNDS = { center: [0, -0.1, 0], radius: 1.5 };
+function createUniforms() {
+    const pebbles = [];
+    for (let i = 0; i < MAX_PEBBLES; i++)
+        pebbles.push(new THREE.Vector4(0, 0, 99, 0));
+    return {
+        uTime: { value: 0 },
+        uSize: { value: 1 },
+        uViewH: { value: 800 },
+        uIntensity: { value: 1 },
+        uSpeed: { value: 1 },
+        uOpacity: { value: 0.9 },
+        uColor: colorUniform('#ffffff'),
+        uParticleCount: { value: 0 },
+        uSwellHeight: { value: 1 },
+        uCurrent: { value: 0.3 },
+        uSensitivity: { value: 1 },
+        uRecovery: { value: 6 },
+        uGlowTime: { value: 1 },
+        uWaterClarity: { value: 1 },
+        uDeepColor: colorUniform('#ffffff'),
+        uMoonlight: { value: 0.6 },
+        uPointerMode: { value: 0 },
+        uPointerStrength: { value: 1 },
+        uPointerRadius: { value: 1 },
+        uPointerColor: colorUniform('#ffffff'),
+        uWave0: { value: new THREE.Vector4() }, // dir.x, dir.z, k, A
+        uWave1: { value: new THREE.Vector4() },
+        uWavePh: { value: new THREE.Vector2() }, // current phase of each wave (w t - phi)
+        uCurOff: { value: new THREE.Vector2() }, // current offset (x, z)
+        uPebbles: { value: pebbles }, // x, z, age, strength
+        uCamLocal: { value: new THREE.Vector3(0, 1, 2) },
+        uTrailGain: { value: 1 },
+        ...createPointerUniforms(),
+        ...createTrailUniforms(),
+    };
+}
+function applyConfig(u, c, size) {
+    u.uSize.value = size;
+    u.uIntensity.value = c.intensity;
+    u.uSpeed.value = c.speed;
+    u.uOpacity.value = c.opacity;
+    u.uColor.value.set(c.color);
+    u.uParticleCount.value = c.particleCount;
+    u.uSwellHeight.value = c.swellHeight;
+    u.uCurrent.value = c.current;
+    u.uSensitivity.value = c.sensitivity;
+    u.uRecovery.value = c.recovery;
+    u.uGlowTime.value = c.glowTime;
+    u.uWaterClarity.value = c.waterClarity;
+    u.uDeepColor.value.set(c.deepColor);
+    u.uMoonlight.value = c.moonlight;
+    u.uPointerMode.value = POINTER_MODES.indexOf(c.pointerMode); // -1 = 'none' (off)
+    u.uPointerStrength.value = c.pointerStrength;
+    u.uPointerRadius.value = c.pointerRadius;
+    u.uPointerColor.value.set(c.pointerColor);
+    applyTrailConfig(u, c);
+}
+const BASE_U = 'uniform float uSize, uViewH, uIntensity, uOpacity;';
+// Shared water optics: absorption, depth tint, edge fade.
+const WATER_GLSL = /* glsl */ `
+uniform vec3 uColor, uDeepColor;
+uniform float uWaterClarity;
+float edgeFade(vec3 p) {
+  vec2 e = ${HX.toFixed(2)} - abs(p.xz);
+  return smoothstep(0.0, 0.18, min(e.x, e.y));
+}
+float absorb(float depth) { return exp(-depth * 7.0 / max(uWaterClarity, 0.05)); }
+vec3 depthTint(float depth) { return mix(uColor, uDeepColor, 1.0 - exp(-depth * 6.0 / max(uWaterClarity, 0.05))); }
+`;
+const cellVertex = /* glsl */ `
+${BASE_U}
+${WATER_GLSL}
+uniform float uMoonlight;
+attribute float aL;    // emitted light (0..~1.4)
+attribute float aSeed;
+varying vec3 vCol;
+varying float vA;
+void main() {
+  float depth = max(-position.y, 0.0);
+  float L = aL * edgeFade(position);
+  float att = absorb(depth);
+  // forward scattering in the water widens deeper flashes into soft discs (energy conserved)
+  float blur = 1.0 + depth * 10.0;
+  vec4 mv = modelViewMatrix * vec4(position * uSize, 1.0);
+  float Lc = min(L, 1.4);
+  float px = uSize * uViewH * (0.0035 + 0.013 * sqrt(Lc)) * (0.8 + 0.4 * aSeed) * blur / -mv.z;
+  vec3 glow = depthTint(depth) * L * att * 4.0;
+  // unlit cells are specks catching a little moonlight near the surface
+  vec3 speck = vec3(0.45, 0.55, 0.7) * 0.07 * uMoonlight * exp(-depth * 18.0) * edgeFade(position);
+  vCol = (glow + speck) * uIntensity;
+  vA = uOpacity / (blur * blur);
+  gl_PointSize = clamp(px, 1.0, 64.0);
+  gl_Position = projectionMatrix * mv;
+}
+`;
+const cellFragment = /* glsl */ `
+varying vec3 vCol;
+varying float vA;
+void main() {
+  vec2 d = gl_PointCoord * 2.0 - 1.0;
+  float r2 = dot(d, d);
+  if (r2 > 1.0) discard;
+  float a = (exp(-r2 * 10.0) + 0.22 * exp(-r2 * 2.5)) * (1.0 - r2) * vA;
+  vec3 c = vCol * a;
+  if (max(c.r, max(c.g, c.b)) < 0.0015) discard;
+  gl_FragColor = vec4(vCol, a);
+}
+`;
+// In-water scattering: every lit cell also lights the water around it — a wide, faint disc
+// (radius ~ a few scattering lengths). Where many cells flash together (a fish, a wake) the
+// discs merge into a continuous glow; lone flashes stay points. Cells below a small emission
+// are collapsed to zero size so the pass costs almost nothing when the sea is dark.
+const haloVertex = /* glsl */ `
+${BASE_U}
+${WATER_GLSL}
+attribute float aL;
+varying vec3 vCol;
+varying float vA;
+void main() {
+  float depth = max(-position.y, 0.0);
+  float L = aL * edgeFade(position);
+  vec4 mv = modelViewMatrix * vec4(position * uSize, 1.0);
+  float on = step(0.12, L);
+  gl_PointSize = on * clamp(uSize * uViewH * (0.065 + 0.2 * depth) / -mv.z, 0.0, 180.0);
+  vCol = depthTint(depth + 0.05) * uIntensity;
+  vA = on * min(L, 1.4) * absorb(depth) * 0.12 * uOpacity;
+  gl_Position = projectionMatrix * mv;
+}
+`;
+const haloFragment = /* glsl */ `
+varying vec3 vCol;
+varying float vA;
+void main() {
+  vec2 d = gl_PointCoord * 2.0 - 1.0;
+  float r2 = dot(d, d);
+  if (r2 > 1.0) discard;
+  float a = exp(-r2 * 3.0) * (1.0 - r2) * vA;
+  gl_FragColor = vec4(vCol, a);
+}
+`;
+// Moon glitter: facets on the swell (same waves as the plankton) plus pebble ripples. Each facet
+// rocks slowly around the mean normal (Cox–Munk slope spread), so the glitter path twinkles calmly.
+const surfVertex = /* glsl */ `
+${BASE_U}
+uniform float uTime, uMoonlight, uSwellHeight;
+uniform vec4 uWave0, uWave1;
+uniform vec2 uWavePh, uCurOff;
+uniform vec4 uPebbles[${MAX_PEBBLES}];
+uniform vec3 uCamLocal;
+attribute vec2 aRnd;
+varying vec3 vCol;
+varying float vA;
+void wave(vec4 w, float ph, vec2 xw, inout vec3 P, inout vec2 slope) {
+  float th = w.z * dot(w.xy, xw) - ph;
+  float A = w.w * uSwellHeight;
+  P.xz -= w.xy * A * sin(th);
+  P.y += A * cos(th);
+  slope -= w.xy * (w.z * A * sin(th));
+}
+void main() {
+  vec3 P = position;
+  vec2 xw = position.xz - uCurOff;
+  vec2 slope = vec2(0.0);
+  wave(uWave0, uWavePh.x, xw, P, slope);
+  wave(uWave1, uWavePh.y, xw, P, slope);
+  for (int i = 0; i < ${MAX_PEBBLES}; i++) {
+    vec4 pb = uPebbles[i];
+    if (pb.w <= 0.0 || pb.z > 4.5) continue;
+    vec2 dd = position.xz - pb.xy;
+    float rho = length(dd) + 1e-4;
+    float rf = ${RIP_C.toFixed(3)} * pb.z;
+    float w = 0.03 + 0.016 * pb.z;
+    float x = rho - rf;
+    float env = pb.w * 0.004 * exp(-pb.z / 1.6) * exp(-(x * x) / (w * w)) / sqrt(1.0 + rf / 0.08);
+    float kk = 6.2831853 / ${RIP_L.toFixed(3)};
+    P.y += env * cos(kk * x);
+    slope -= (dd / rho) * env * kk * sin(kk * x);
+  }
+  vec2 rock = vec2(sin(aRnd.x * 6.2831 + uTime * (0.35 + 0.5 * aRnd.y)), cos(aRnd.y * 6.2831 + uTime * (0.3 + 0.45 * aRnd.x)));
+  vec3 n = normalize(vec3(-slope.x + 0.09 * rock.x, 1.0, -slope.y + 0.09 * rock.y));
+  vec3 V = normalize(uCamLocal - P);
+  vec3 Lm = normalize(vec3(0.0, 0.42, -0.9));      // low moon behind the patch
+  vec3 Hh = normalize(Lm + V);
+  float ndv = max(dot(n, V), 0.0);
+  float F = 0.02 + 0.98 * pow(1.0 - ndv, 5.0);
+  float spec = pow(max(dot(n, Hh), 0.0), 1400.0) * 90.0 * F;
+  vec2 e = ${HX.toFixed(2)} - abs(position.xz);
+  float edge = smoothstep(0.0, 0.3, min(e.x, e.y));
+  vec3 sky = vec3(0.10, 0.14, 0.22);
+  vCol = (vec3(0.80, 0.86, 1.0) * spec + sky * F * 0.5) * uMoonlight * uIntensity;
+  vA = edge * uOpacity;
+  vec4 mv = modelViewMatrix * vec4(P * uSize, 1.0);
+  gl_PointSize = clamp(uSize * uViewH * 0.0022 * (1.0 + min(spec, 3.0) * 0.8) / -mv.z, 1.0, 16.0);
+  gl_Position = projectionMatrix * mv;
+}
+`;
+const surfFragment = /* glsl */ `
+varying vec3 vCol;
+varying float vA;
+void main() {
+  vec2 d = gl_PointCoord * 2.0 - 1.0;
+  float r2 = dot(d, d);
+  if (r2 > 1.0) discard;
+  float a = (exp(-r2 * 6.0) + 0.2 * exp(-r2 * 2.0)) * (1.0 - r2) * vA;
+  if (max(vCol.r, max(vCol.g, vCol.b)) * a < 0.002) discard;
+  gl_FragColor = vec4(vCol, a);
+}
+`;
+// Splash glyphs for the pebble mode: a short white burst where each pebble enters.
+const splashVertex = /* glsl */ `
+uniform float uSize, uViewH, uPointerRadius;
+attribute vec2 aPb; // age, strength
+varying float vA;
+void main() {
+  vec4 mv = modelViewMatrix * vec4(position * uSize, 1.0);
+  float age = aPb.x;
+  vA = aPb.y * exp(-age / 0.12) * step(age, 0.6);
+  gl_PointSize = clamp(uSize * uViewH * 0.05 * uPointerRadius * (0.4 + age * 3.0) / -mv.z, 0.0, 200.0) * step(0.01, vA);
+  gl_Position = projectionMatrix * mv;
+}
+`;
+const splashFragment = /* glsl */ `
+uniform vec3 uPointerColor;
+uniform float uOpacity, uIntensity;
+varying float vA;
+void main() {
+  vec2 d = gl_PointCoord * 2.0 - 1.0;
+  float r2 = dot(d, d);
+  if (r2 > 1.0) discard;
+  float ring = exp(-pow((sqrt(r2) - 0.6) / 0.18, 2.0));
+  float a = (0.6 * exp(-r2 * 8.0) + 0.5 * ring) * (1.0 - r2) * vA * uOpacity;
+  if (a < 0.003) discard;
+  gl_FragColor = vec4(uPointerColor * uIntensity, a);
+}
+`;
+function build(u, c, size) {
+    const q = qualityScale(c.quality);
+    const n = Math.max(1, Math.round(c.particleCount * q));
+    const rng = mulberry32(seedMix(0x5e45, c.seed));
+    // ---- swell: two waves, deep-water dispersion ----
+    const waves = [
+        { ang: 0.35 + (rng() - 0.5) * 0.3, lambda: 0.85, amp: 0.013, phi: rng() * 6.283, dx: 0, dz: 0, k: 0, om: 0 },
+        { ang: -0.55 + (rng() - 0.5) * 0.3, lambda: 0.5, amp: 0.006, phi: rng() * 6.283, dx: 0, dz: 0, k: 0, om: 0 },
+    ];
+    for (const w of waves) {
+        w.dx = Math.sin(w.ang);
+        w.dz = -Math.cos(w.ang); // travelling mostly toward -z, away from the camera
+        w.k = (2 * Math.PI) / w.lambda;
+        w.om = Math.sqrt(G * w.k);
+    }
+    u.uWave0.value.set(waves[0].dx, waves[0].dz, waves[0].k, waves[0].amp);
+    u.uWave1.value.set(waves[1].dx, waves[1].dz, waves[1].k, waves[1].amp);
+    // ---- cells: water-frame rest positions, cached wave phases, excitable state ----
+    const rx = new Float32Array(n), ry = new Float32Array(n), rz = new Float32Array(n);
+    const pc = new Float32Array(n * 2), ps = new Float32Array(n * 2), ek = new Float32Array(n * 2);
+    const thr = new Float32Array(n), res = new Float32Array(n), cd = new Float32Array(n);
+    const L = new Float32Array(n);
+    // exposure memory: the brightest light a cell gave during the camera's exposure window (trails use it)
+    const EXP = new Float32Array(n);
+    const pos = new Float32Array(n * 3), vel = new Float32Array(n * 3);
+    let trail = null, trailKey = '', trailScale = 1;
+    const seedA = new Float32Array(n);
+    const dirty = new Uint8Array(n);
+    for (let i = 0; i < n; i++) {
+        rx[i] = (rng() * 2 - 1) * HX;
+        rz[i] = (rng() * 2 - 1) * HX;
+        ry[i] = -Math.min(-Math.log(1 - rng() * 0.995) * LAYER, D);
+        thr[i] = TH0 * Math.exp(0.55 * gauss(rng));
+        res[i] = 1;
+        seedA[i] = rng();
+        dirty[i] = 1;
+    }
+    function refresh(i) {
+        for (let w = 0; w < 2; w++) {
+            const W = waves[w];
+            const th = W.k * (W.dx * rx[i] + W.dz * rz[i]) + W.phi;
+            pc[i * 2 + w] = Math.cos(th);
+            ps[i * 2 + w] = Math.sin(th);
+            ek[i * 2 + w] = Math.exp(W.k * ry[i]);
+        }
+        dirty[i] = 0;
+    }
+    // ---- pointer agents ----
+    const PB = new Float64Array(MAX_PEBBLES * 4); // x, z, age, strength
+    for (let k = 0; k < MAX_PEBBLES; k++)
+        PB[k * 4 + 2] = 99;
+    let pebHead = 0, dropClock = 0, lastDropX = 1e9, lastDropZ = 1e9;
+    const PK = new Float64Array(MAX_PEBBLES * 12);
+    const fish = { x: 0.5, z: 0, y: -0.06, psi: Math.PI / 2, v: 0.28, tail: 0, lastSin: 0, wander: rng() * 6.28 };
+    const VX = new Float64Array(MAX_VORT * 5); // x, z, gamma, age, alive
+    let vHead = 0;
+    // uniform grid over the patch (world coordinates) so cursor agents visit only nearby cells
+    const GN = 24, GS = (2 * HX) / GN;
+    const gStart = new Int32Array(GN * GN + 1), gCell = new Int32Array(n), gOrder = new Int32Array(n);
+    const stamp = new Uint32Array(n), touch = new Int32Array(n);
+    const SX = new Float32Array(n), UX = new Float32Array(n), UY = new Float32Array(n), UZ = new Float32Array(n);
+    let stampId = 0, nTouch = 0, gridAge = 0;
+    const PAD = 0.05;
+    function buildGrid() {
+        gStart.fill(0);
+        for (let i = 0; i < n; i++) {
+            let gx = Math.floor((rx[i] + curX + HX) / GS), gz = Math.floor((rz[i] + curZ + HX) / GS);
+            gx = gx < 0 ? 0 : gx >= GN ? GN - 1 : gx;
+            gz = gz < 0 ? 0 : gz >= GN ? GN - 1 : gz;
+            const g = gz * GN + gx;
+            gCell[i] = g;
+            gStart[g + 1]++;
+        }
+        for (let g = 0; g < GN * GN; g++)
+            gStart[g + 1] += gStart[g];
+        const fill = gStart.slice(0, GN * GN);
+        for (let i = 0; i < n; i++)
+            gOrder[fill[gCell[i]]++] = i;
+    }
+    // mark every cell in the buckets overlapping a square (or an annulus r0..r1 when ring = 1)
+    function addBox(cx, cz, r1in, r0in, ring) {
+        const r1 = r1in + PAD, r0 = Math.max(r0in - PAD, 0);
+        const gx0 = Math.max(0, Math.floor((cx - r1 + HX) / GS)), gx1 = Math.min(GN - 1, Math.floor((cx + r1 + HX) / GS));
+        const gz0 = Math.max(0, Math.floor((cz - r1 + HX) / GS)), gz1 = Math.min(GN - 1, Math.floor((cz + r1 + HX) / GS));
+        for (let gz = gz0; gz <= gz1; gz++)
+            for (let gx = gx0; gx <= gx1; gx++) {
+                if (ring) {
+                    const bx0 = -HX + gx * GS, bz0 = -HX + gz * GS;
+                    const nx = Math.max(bx0 - cx, 0, cx - bx0 - GS), nz = Math.max(bz0 - cz, 0, cz - bz0 - GS);
+                    const fx = Math.max(Math.abs(bx0 - cx), Math.abs(bx0 + GS - cx)), fz = Math.max(Math.abs(bz0 - cz), Math.abs(bz0 + GS - cz));
+                    if (nx * nx + nz * nz > r1 * r1 || fx * fx + fz * fz < r0 * r0)
+                        continue;
+                }
+                const g = gz * GN + gx;
+                for (let q = gStart[g]; q < gStart[g + 1]; q++) {
+                    const i = gOrder[q];
+                    if (stamp[i] !== stampId) {
+                        stamp[i] = stampId;
+                        touch[nTouch++] = i;
+                    }
+                }
+            }
+    }
+    let time = 0;
+    let curX = 0, curZ = 0;
+    const hp = new THREE.Vector3(), hv = new THREE.Vector3();
+    function step(h) {
+        time += h;
+        const sw = Math.max(u.uSwellHeight.value, 0);
+        const sens = Math.max(u.uSensitivity.value, 0.05);
+        const tauL = 0.22 * Math.max(u.uGlowTime.value, 0.05);
+        const decL = Math.exp(-h / tauL);
+        const rec = h / Math.max(u.uRecovery.value, 0.1);
+        // current: slow drift toward +x, slightly across
+        const cur = 0.035 * u.uCurrent.value;
+        curX += cur * 0.92 * h;
+        curZ += cur * 0.38 * h;
+        u.uCurOff.value.set(curX, curZ);
+        // wave clocks
+        const W0 = waves[0], W1 = waves[1];
+        const C0 = Math.cos(W0.om * time), S0 = Math.sin(W0.om * time);
+        const C1 = Math.cos(W1.om * time), S1 = Math.sin(W1.om * time);
+        const Aw0 = W0.amp * sw, Aw1 = W1.amp * sw, om0 = W0.om, om1 = W1.om;
+        const sk0 = W0.om * W0.k, sk1 = W1.om * W1.k; // shear per unit amplitude
+        const dx0 = W0.dx, dz0 = W0.dz, dx1 = W1.dx, dz1 = W1.dz;
+        u.uWavePh.value.set(waves[0].om * time - waves[0].phi, waves[1].om * time - waves[1].phi);
+        // pointer
+        const mode = u.uPointerMode.value;
+        const Sp = u.uPointerStrength.value;
+        const act = u.uPointerActive.value;
+        const Rr = u.uPointerRadius.value;
+        hp.copy(u.uPointer.value);
+        hv.copy(u.uPointerVel.value);
+        hp.x -= curX;
+        hp.z -= curZ; // into the water frame
+        const useHand = mode === 0 && Sp * act > 0.01;
+        const usePeb = mode === 1 && Sp > 0.01;
+        const useFish = mode === 2 && Sp > 0.01;
+        const RH = 0.055 * Rr;
+        const hs = Sp * act;
+        const hSpeed = Math.hypot(hv.x, hv.z);
+        const hY = Math.min(Math.max(hp.y, -D * 0.6), -0.012);
+        // pebbles: one every 0.4 s while the cursor is active, or after 0.25 of travel
+        if (usePeb) {
+            dropClock += h;
+            const moved = Math.hypot(hp.x - lastDropX, hp.z - lastDropZ);
+            if (act > 0.6 && (dropClock > 0.55 || moved > 0.25 * Rr) && dropClock > 0.15) {
+                const k = pebHead % MAX_PEBBLES;
+                pebHead++;
+                PB[k * 4] = hp.x;
+                PB[k * 4 + 1] = hp.z;
+                PB[k * 4 + 2] = 0;
+                PB[k * 4 + 3] = Sp * Rr;
+                dropClock = 0;
+                lastDropX = hp.x;
+                lastDropZ = hp.z;
+            }
+        }
+        // per-pebble constants for this step (splash, sinking wake, ripple band) so the cell loop is cheap
+        let nPeb = 0;
+        for (let k = 0; k < MAX_PEBBLES; k++) {
+            PB[k * 4 + 2] += h;
+            const age = PB[k * 4 + 2], st = PB[k * 4 + 3];
+            const pbv = u.uPebbles.value[k];
+            pbv.set(PB[k * 4] + curX, PB[k * 4 + 1] + curZ, age, age < 4.5 ? st : 0);
+            if (age >= 3.5)
+                continue;
+            const o = nPeb * 12;
+            const rf = RIP_C * age, w = 0.03 + 0.016 * age;
+            const r0 = Math.max(rf - 2.3 * w, 0), r1 = rf + 2.3 * w;
+            PK[o] = PB[k * 4];
+            PK[o + 1] = PB[k * 4 + 1];
+            PK[o + 2] = age;
+            PK[o + 3] = st;
+            PK[o + 4] = rf;
+            PK[o + 5] = w;
+            PK[o + 6] = r0 * r0;
+            PK[o + 7] = r1 * r1;
+            PK[o + 8] = st * 18 * Math.exp(-age / 1.6) / Math.sqrt(1 + rf / 0.08);
+            if (PK[o + 8] * sens < 0.3 * TH0) {
+                PK[o + 6] = 1e9;
+                PK[o + 7] = -1;
+            } // too weak to light anything
+            PK[o + 9] = age < 0.3 ? 60 * Math.exp(-age / 0.08) : 0; // splash amplitude
+            PK[o + 10] = -0.35 * age; // pebble depth
+            PK[o + 11] = 0.015 * st + 0.004; // pebble radius
+            nPeb++;
+        }
+        // fish: steer toward the cursor (or cruise a slow circle), beat the tail, shed vortices
+        let fcos = 0, fsin = 0, fa = 0, fb = 0, fc = 0;
+        if (useFish) {
+            const F = fish;
+            let tx, tz;
+            // targets are chosen in the world (inside the patch), then taken into the water frame
+            if (act > 0.3) {
+                tx = hp.x + curX;
+                tz = hp.z + curZ;
+            }
+            else {
+                F.wander += h * 0.16;
+                tx = 0.62 * Math.cos(F.wander);
+                tz = 0.5 * Math.sin(F.wander);
+            }
+            tx = Math.max(-0.85, Math.min(0.85, tx)) - curX;
+            tz = Math.max(-0.85, Math.min(0.85, tz)) - curZ;
+            const dx = tx - F.x, dz = tz - F.z;
+            const dist = Math.hypot(dx, dz);
+            const want = Math.atan2(dz, dx);
+            let dpsi = want - F.psi;
+            while (dpsi > Math.PI)
+                dpsi -= 2 * Math.PI;
+            while (dpsi < -Math.PI)
+                dpsi += 2 * Math.PI;
+            const turn = 2.6 * Math.min(Sp, 2);
+            F.psi += Math.max(-turn * h, Math.min(turn * h, dpsi));
+            const vDes = (act > 0.3 ? Math.min(0.3 + dist * 1.5, 1.1) : 0.34) * Math.min(Sp, 2.5);
+            F.v += (vDes - F.v) * Math.min(1, h * 1.8);
+            fcos = Math.cos(F.psi);
+            fsin = Math.sin(F.psi);
+            F.x += fcos * F.v * h;
+            F.z += fsin * F.v * h;
+            F.y = -0.04 + 0.008 * Math.sin(time * 0.7);
+            const freq = 1.3 + 3.2 * F.v / Math.max(Rr, 0.3);
+            F.tail += 6.2831853 * freq * h;
+            fa = 0.15 * Rr;
+            fb = 0.032 * Rr;
+            fc = 0.025 * Rr;
+            const sn = Math.sin(F.tail);
+            if ((sn >= 0) !== (F.lastSin >= 0)) {
+                // tail tip at the end of a stroke sheds a vortex, alternating sign: a reverse Karman street
+                const k = vHead % MAX_VORT;
+                vHead++;
+                const lat = 0.9 * fb * Math.cos(F.tail);
+                const tx2 = F.x - fcos * fa * 1.15 - fsin * lat, tz2 = F.z - fsin * fa * 1.15 + fcos * lat;
+                VX[k * 5] = tx2;
+                VX[k * 5 + 1] = tz2;
+                VX[k * 5 + 2] = (sn >= 0 ? 1 : -1) * 1.1 * F.v * fa;
+                VX[k * 5 + 3] = 0;
+                VX[k * 5 + 4] = 1;
+            }
+            F.lastSin = sn;
+        }
+        // vortices: decay, grow, and their bounding box
+        let vMinX = 1e9, vMaxX = -1e9, vMinZ = 1e9, vMaxZ = -1e9;
+        const liveV = [];
+        for (let k = 0; k < MAX_VORT; k++) {
+            if (!VX[k * 5 + 4])
+                continue;
+            VX[k * 5 + 3] += h;
+            VX[k * 5 + 2] *= Math.exp(-h / 2.4);
+            if (VX[k * 5 + 3] > 7 || !useFish && VX[k * 5 + 3] > 3) {
+                VX[k * 5 + 4] = 0;
+                continue;
+            }
+            const a = 0.028 + 0.018 * VX[k * 5 + 3];
+            liveV.push(k);
+            vMinX = Math.min(vMinX, VX[k * 5] - 3 * a);
+            vMaxX = Math.max(vMaxX, VX[k * 5] + 3 * a);
+            vMinZ = Math.min(vMinZ, VX[k * 5 + 1] - 3 * a);
+            vMaxZ = Math.max(vMaxZ, VX[k * 5 + 1] + 3 * a);
+        }
+        // vortices advect each other (2D Biot–Savart) so the street spreads and pairs
+        for (const k of liveV) {
+            let ux = 0, uz = 0;
+            for (const m of liveV) {
+                if (m === k)
+                    continue;
+                const dx = VX[k * 5] - VX[m * 5], dz = VX[k * 5 + 1] - VX[m * 5 + 1];
+                const a = 0.028 + 0.018 * VX[m * 5 + 3];
+                const f = VX[m * 5 + 2] / (6.2831853 * (dx * dx + dz * dz + a * a));
+                ux += -dz * f;
+                uz += dx * f;
+            }
+            VX[k * 5] += ux * h;
+            VX[k * 5 + 1] += uz * h;
+        }
+        const nV = liveV.length;
+        const F = fish;
+        const hvx = hv.x, hvy = 0, hvz = hv.z;
+        const hvn = hSpeed > 1e-4 ? 1 / hSpeed : 0;
+        // ---- cursor agents: only cells inside an agent's reach are visited (grid buckets) ----
+        const anyAgent = useHand || nPeb > 0 || useFish || nV > 0;
+        if (!anyAgent)
+            gridAge = 0;
+        stampId++;
+        if (anyAgent) {
+            // cells drift slowly, so the grid is rebuilt every 6 steps and agent boxes are padded
+            if (gridAge <= 0) {
+                buildGrid();
+                gridAge = 6;
+            }
+            gridAge--;
+            nTouch = 0;
+            if (useHand)
+                addBox(hp.x + curX, hp.z + curZ, 7 * RH, 0, 0);
+            for (let q = 0, o = 0; q < nPeb; q++, o += 12) {
+                const cx = PK[o] + curX, cz = PK[o + 1] + curZ;
+                addBox(cx, cz, 0.12, 0, 0); // splash + sinking pebble
+                if (PK[o + 7] > 0)
+                    addBox(cx, cz, Math.sqrt(PK[o + 7]), Math.sqrt(PK[o + 6]), 1); // ripple band
+            }
+            if (useFish)
+                addBox(F.x + curX, F.z + curZ, 2 * fa, 0, 0);
+            for (let q = 0; q < nV; q++) {
+                const k = liveV[q];
+                addBox(VX[k * 5] + curX, VX[k * 5 + 1] + curZ, 3 * (0.028 + 0.018 * VX[k * 5 + 3]), 0, 0);
+            }
+            for (let t = 0; t < nTouch; t++) {
+                const i = touch[t];
+                const x = rx[i], y = ry[i], z = rz[i];
+                let s = 0;
+                let ux = 0, uy = 0, uz = 0;
+                if (useHand) {
+                    const qx = x - hp.x, qy = y - hY, qz = z - hp.z;
+                    const r2 = qx * qx + qy * qy + qz * qz;
+                    if (r2 < 49 * RH * RH) {
+                        const r = Math.sqrt(r2) + 1e-6;
+                        if (r > RH) {
+                            const k3 = (RH * RH * RH) / (2 * r2 * r);
+                            const vr = (hvx * qx + hvy * qy + hvz * qz) / r;
+                            ux += hs * k3 * (3 * vr * qx / r - hvx);
+                            uy += hs * k3 * (3 * vr * qy / r - hvy);
+                            uz += hs * k3 * (3 * vr * qz / r - hvz);
+                            s += hs * 3 * hSpeed * RH * RH * RH / (r2 * r2);
+                        }
+                        else {
+                            ux += hs * hvx;
+                            uz += hs * hvz;
+                            s += hs * hSpeed / RH;
+                        }
+                        const behind = -(qx * hvx + qz * hvz) * hvn;
+                        if (behind > 0) {
+                            const perp2 = r2 - behind * behind;
+                            const wk = hs * Math.exp(-perp2 / (RH * RH) - behind / (4 * RH));
+                            ux += hvx * wk * 0.6;
+                            uz += hvz * wk * 0.6;
+                            s += wk * hSpeed / RH * 0.9;
+                        }
+                    }
+                }
+                if (nPeb && y > -D - 0.01) {
+                    for (let q = 0, o = 0; q < nPeb; q++, o += 12) {
+                        const dx = x - PK[o], dz = z - PK[o + 1];
+                        const rho2 = dx * dx + dz * dz;
+                        const st = PK[o + 3];
+                        if (PK[o + 9] > 0 && rho2 < 0.01 * st * st + 0.0016 && y > -0.12) { // splash
+                            // compact bump kernels (~gaussian in rho, ~e^{30 y} in depth) — no transcendentals
+                            const b = 1 - rho2 / (0.01 * st * st + 0.0016);
+                            const dz4 = 1 + y * 7.5;
+                            const e = dz4 > 0 ? b * b * b * dz4 * dz4 * dz4 * dz4 : 0;
+                            s += PK[o + 9] * e;
+                            const rho = Math.sqrt(rho2) + 1e-4;
+                            const push = e * PK[o + 9] / 120;
+                            ux += dx / rho * push;
+                            uz += dz / rho * push;
+                        }
+                        // sinking pebble and its short wake
+                        if (rho2 < 0.01 && PK[o + 10] > -D - 0.05) {
+                            const dy = y - PK[o + 10];
+                            if (dy > -0.03 && dy < 0.14) {
+                                const Rp = PK[o + 11];
+                                s += (0.35 / Rp) * Math.exp(-rho2 / (Rp * Rp * 2.2) - Math.max(dy, 0) / 0.07);
+                            }
+                        }
+                        // ripple packet: crests light a ring near the surface
+                        if (y > -0.09 && rho2 > PK[o + 6] && rho2 < PK[o + 7]) {
+                            const xr = Math.sqrt(rho2) - PK[o + 4];
+                            const w = PK[o + 5];
+                            const cr = Math.cos(6.2831853 * xr / RIP_L);
+                            const b = 1 - (xr * xr) / (5.3 * w * w); // bump with the band's support (2.3 w)
+                            const dz4 = 1 + y * 7; // ~e^{28 y}
+                            if (b > 0 && dz4 > 0)
+                                s += PK[o + 8] * b * b * b * dz4 * dz4 * dz4 * dz4 * cr * cr;
+                        }
+                    }
+                }
+                if (useFish) {
+                    const dx = x - F.x, dz = z - F.z, dy = y - F.y;
+                    if (dx * dx + dz * dz < 4 * fa * fa && dy * dy < 0.01) {
+                        const ua = dx * fcos + dz * fsin, va = -dx * fsin + dz * fcos;
+                        const tailf = Math.max(0, (fa - ua) / (2 * fa));
+                        const wig = 0.9 * fb * tailf * tailf * Math.sin(F.tail - 5 * tailf);
+                        const e2 = (ua / fa) * (ua / fa) + ((va - wig) / fb) * ((va - wig) / fb) + (dy / fc) * (dy / fc);
+                        if (e2 < 5) {
+                            const de = Math.sqrt(e2);
+                            const ds = (de - 1) * fb; // ~distance to the body surface
+                            // shear in the boundary layer and the displaced water around the body
+                            const delta = 0.028 * Rr + 0.006;
+                            if (ds > -delta)
+                                s += (F.v / delta) * 0.5 * Math.exp(-(ds * ds) / (delta * delta));
+                            if (de < 1.2) { // no penetration: water is pushed off the body
+                                const push = F.v * 2.2 * (1.2 - de);
+                                const lat = (va - wig) >= 0 ? 1 : -1;
+                                ux += -fsin * lat * push;
+                                uz += fcos * lat * push;
+                                uy += (dy >= 0 ? 1 : -1) * push * 0.3;
+                            }
+                        }
+                    }
+                }
+                if (nV && x > vMinX && x < vMaxX && z > vMinZ && z < vMaxZ) {
+                    const dfac = Math.exp(-((y - F.y) * (y - F.y)) / 0.0049);
+                    if (dfac > 0.02) {
+                        for (let q = 0; q < nV; q++) {
+                            const k = liveV[q];
+                            const dx = x - VX[k * 5], dz = z - VX[k * 5 + 1];
+                            const a = 0.028 + 0.018 * VX[k * 5 + 3];
+                            const r2 = dx * dx + dz * dz;
+                            if (r2 > 9 * a * a)
+                                continue;
+                            const G2 = VX[k * 5 + 2];
+                            const f = (G2 / (6.2831853 * (r2 + a * a))) * dfac;
+                            ux += -dz * f;
+                            uz += dx * f;
+                            s += Math.abs(G2) / (3.14159 * a * a) * Math.exp(-r2 / (a * a)) * dfac * 0.7;
+                        }
+                    }
+                }
+                SX[i] = s;
+                UX[i] = ux;
+                UY[i] = uy;
+                UZ[i] = uz;
+            }
+        }
+        const decE = Math.exp(-h / Math.max(0.6 * u.uTrailLength.value, 0.1));
+        cellLoop(h, curX, curZ, stampId, cur, sens, decL, rec, decE, C0, S0, C1, S1, Aw0, Aw1, om0, om1, sk0, sk1, dx0, dz0, dx1, dz1);
+    }
+    // the per-cell hot loop, kept in its own small function so V8 keeps its scalars in registers
+    function cellLoop(h, cX, cZ, sid, cur, sens, decL, rec, decE, C0, S0, C1, S1, Aw0, Aw1, om0, om1, sk0, sk1, dx0, dz0, dx1, dz1) {
+        const k0 = waves[0].k, k1 = waves[1].k;
+        const kx0 = k0 * dx0, kz0 = k0 * dz0, kx1 = k1 * dx1, kz1 = k1 * dz1;
+        for (let i = 0; i < n; i++) {
+            let x = rx[i], y = ry[i], z = rz[i];
+            let s = 0; // shear rate felt by the cell (1/s)
+            let ux = 0, uy = 0, uz = 0; // extra flow from the cursor agents
+            if (stamp[i] === sid) {
+                s = SX[i];
+                ux = UX[i];
+                uy = UY[i];
+                uz = UZ[i];
+            }
+            if (ux !== 0 || uy !== 0 || uz !== 0) {
+                const ddx = ux * h, ddz = uz * h;
+                let ny = y + uy * h;
+                if (ny > -0.003)
+                    ny = -0.003;
+                else if (ny < -D)
+                    ny = -D;
+                const ddy = ny - y;
+                x += ddx;
+                y = ny;
+                z += ddz;
+                rx[i] = x;
+                ry[i] = y;
+                rz[i] = z;
+                // small moves: rotate the cached wave phases and rescale e^{ky} instead of recomputing them
+                const i2 = i * 2;
+                const a0 = kx0 * ddx + kz0 * ddz, a1 = kx1 * ddx + kz1 * ddz;
+                if (a0 * a0 + a1 * a1 < 0.01) {
+                    const q0 = 1 - 0.5 * a0 * a0, q1 = 1 - 0.5 * a1 * a1;
+                    const p0 = pc[i2], s0 = ps[i2], p1 = pc[i2 + 1], s1 = ps[i2 + 1];
+                    pc[i2] = p0 * q0 - s0 * a0;
+                    ps[i2] = s0 * q0 + p0 * a0;
+                    pc[i2 + 1] = p1 * q1 - s1 * a1;
+                    ps[i2 + 1] = s1 * q1 + p1 * a1;
+                    const e0 = k0 * ddy, e1 = k1 * ddy;
+                    ek[i2] *= 1 + e0 + 0.5 * e0 * e0;
+                    ek[i2 + 1] *= 1 + e1 + 0.5 * e1 * e1;
+                }
+                else
+                    dirty[i] = 1;
+            }
+            // periodic patch: keep world = water frame + current inside [-HX, HX]
+            let wrapped = false;
+            if (x + cX > HX) {
+                x -= 2 * HX;
+                rx[i] = x;
+                dirty[i] = 1;
+                wrapped = true;
+            }
+            else if (x + cX < -HX) {
+                x += 2 * HX;
+                rx[i] = x;
+                dirty[i] = 1;
+                wrapped = true;
+            }
+            if (z + cZ > HX) {
+                z -= 2 * HX;
+                rz[i] = z;
+                dirty[i] = 1;
+                wrapped = true;
+            }
+            else if (z + cZ < -HX) {
+                z += 2 * HX;
+                rz[i] = z;
+                dirty[i] = 1;
+                wrapped = true;
+            }
+            if (dirty[i])
+                refresh(i);
+            // swell: orbital displacement and shear (strongest at crests, where the swell steepens)
+            // cos/sin(th - w t) from the cached phase by rotation (two waves, unrolled)
+            const i2 = i * 2;
+            const ct0 = pc[i2] * C0 + ps[i2] * S0, st0 = ps[i2] * C0 - pc[i2] * S0;
+            const ct1 = pc[i2 + 1] * C1 + ps[i2 + 1] * S1, st1 = ps[i2 + 1] * C1 - pc[i2 + 1] * S1;
+            const A0 = Aw0 * ek[i2], A1 = Aw1 * ek[i2 + 1];
+            const ox = -(dx0 * A0 * st0 + dx1 * A1 * st1), oz = -(dz0 * A0 * st0 + dz1 * A1 * st1);
+            const oy = A0 * ct0 + A1 * ct1;
+            const vx = dx0 * A0 * om0 * ct0 + dx1 * A1 * om1 * ct1;
+            const vz = dz0 * A0 * om0 * ct0 + dz1 * A1 * om1 * ct1;
+            const vy = A0 * om0 * st0 + A1 * om1 * st1;
+            // crest factor max(cos, 0)^6, branch-free (a data-dependent branch here costs more than the maths)
+            const m0 = 0.5 * (ct0 + Math.abs(ct0)), m1 = 0.5 * (ct1 + Math.abs(ct1));
+            const c0 = m0 * m0 * m0, c1 = m1 * m1 * m1;
+            s += A0 * sk0 * (1 + 3.2 * c0 * c0) + A1 * sk1 * (1 + 3.2 * c1 * c1);
+            // world position (current offset, periodic patch)
+            const wx = x + cX + ox, wz = z + cZ + oz;
+            const wy = Math.min(y + oy, -0.001);
+            const j = i * 3;
+            vel[j] = vx + ux + cur * 0.92;
+            vel[j + 1] = vy + uy;
+            vel[j + 2] = vz + uz + cur * 0.38;
+            pos[j] = wx;
+            pos[j + 1] = wy;
+            pos[j + 2] = wz;
+            if (wrapped && trail)
+                trail.reset(i);
+            // excitable cell: threshold, flash, fatigue, recovery
+            let l = L[i] * decL;
+            let r = res[i];
+            const cdi = cd[i] - h;
+            cd[i] = cdi;
+            if (cdi <= 0 && r > 0.04 && s * sens > thr[i]) {
+                let over = (s * sens) / thr[i] - 1;
+                if (over > 1.5)
+                    over = 1.5;
+                const fl = r * (0.75 + 0.45 * over);
+                if (fl > l)
+                    l = fl;
+                r *= 0.62;
+                cd[i] = 0.16 + 0.12 * seedA[i];
+            }
+            res[i] = r + (1 - r) * rec;
+            // near the patch edge, light fades (cells wrap there)
+            const ex = HX - (wx < 0 ? -wx : wx), ez = HX - (wz < 0 ? -wz : wz);
+            const em = ex < ez ? ex : ez;
+            const li = em < 0.12 ? l * (em > 0 ? em / 0.12 : 0) : l;
+            L[i] = li;
+            const e = EXP[i] * decE;
+            EXP[i] = li > e ? li : e;
+        }
+    }
+    const stepper = createFixedStep(H_STEP, 4);
+    for (let i = 0; i < n; i++)
+        refresh(i);
+    // warm up: settle recovery state and fill the swell history
+    for (let s = 0; s < 60; s++)
+        step(H_STEP);
+    // ---- geometry ----
+    const geo = new THREE.BufferGeometry();
+    const posAttr = new THREE.BufferAttribute(pos, 3).setUsage(THREE.DynamicDrawUsage);
+    const lAttr = new THREE.BufferAttribute(L, 1).setUsage(THREE.DynamicDrawUsage);
+    geo.setAttribute('position', posAttr);
+    geo.setAttribute('aL', lAttr);
+    geo.setAttribute('aSeed', new THREE.BufferAttribute(seedA, 1));
+    const mat = new THREE.ShaderMaterial({
+        uniforms: u, vertexShader: cellVertex, fragmentShader: cellFragment,
+        transparent: true, depthWrite: false, blending: THREE.AdditiveBlending,
+    });
+    const cells = new THREE.Points(geo, mat);
+    cells.frustumCulled = false;
+    attachViewH(cells, u);
+    const hmat = new THREE.ShaderMaterial({
+        uniforms: u, vertexShader: haloVertex, fragmentShader: haloFragment,
+        transparent: true, depthWrite: false, blending: THREE.AdditiveBlending,
+    });
+    const halos = new THREE.Points(geo, hmat);
+    halos.frustumCulled = false;
+    const NS = Math.round(170 * Math.sqrt(q));
+    const sp = new Float32Array(NS * NS * 3), sr = new Float32Array(NS * NS * 2);
+    const srng = mulberry32(seedMix(0x6a17, c.seed));
+    for (let a = 0, p = 0; a < NS; a++)
+        for (let b = 0; b < NS; b++, p++) {
+            sp[p * 3] = -HX + (2 * HX * (a + srng())) / NS;
+            sp[p * 3 + 2] = -HX + (2 * HX * (b + srng())) / NS;
+            sr[p * 2] = srng();
+            sr[p * 2 + 1] = srng();
+        }
+    const sgeo = new THREE.BufferGeometry();
+    sgeo.setAttribute('position', new THREE.BufferAttribute(sp, 3));
+    sgeo.setAttribute('aRnd', new THREE.BufferAttribute(sr, 2));
+    const smat = new THREE.ShaderMaterial({
+        uniforms: u, vertexShader: surfVertex, fragmentShader: surfFragment,
+        transparent: true, depthWrite: false, blending: THREE.AdditiveBlending,
+    });
+    const surface = new THREE.Points(sgeo, smat);
+    surface.frustumCulled = false;
+    const pgeo = new THREE.BufferGeometry();
+    const pp = new Float32Array(MAX_PEBBLES * 3), pa = new Float32Array(MAX_PEBBLES * 2);
+    const ppAttr = new THREE.BufferAttribute(pp, 3).setUsage(THREE.DynamicDrawUsage);
+    const paAttr = new THREE.BufferAttribute(pa, 2).setUsage(THREE.DynamicDrawUsage);
+    pgeo.setAttribute('position', ppAttr);
+    pgeo.setAttribute('aPb', paAttr);
+    const pmat = new THREE.ShaderMaterial({
+        uniforms: u, vertexShader: splashVertex, fragmentShader: splashFragment,
+        transparent: true, depthWrite: false, blending: THREE.AdditiveBlending,
+    });
+    const splashes = new THREE.Points(pgeo, pmat);
+    splashes.frustumCulled = false;
+    const object = new THREE.Group();
+    const proxy = createPickProxy(BOUNDS.center, BOUNDS.radius);
+    object.add(surface, halos, cells, splashes, proxy.mesh);
+    const anchor = new THREE.Vector3(...ANCHOR);
+    const up = new THREE.Vector3(0, 1, 0);
+    // ---- trails: only glowing cells leave light ----
+    const trailGLSL = /* glsl */ `
+${WATER_GLSL}
+uniform float uTrailGain;
+vec3 trailShade(vec3 p, float f) {
+  float depth = max(-p.y, 0.0);
+  return depthTint(depth) * TRAIL_K * absorb(depth) * edgeFade(p) * 3.0 * uTrailGain;
+}
+vec3 trailView(vec3 mv, out float mag) { mag = 1.0; return mv; }
+`;
+    const materials = [mat, hmat, smat, pmat];
+    trailKey = '';
+    function buildTrails(mode, share) {
+        const key = mode + ':' + share;
+        if (key === trailKey)
+            return;
+        trailKey = key;
+        if (trail) {
+            object.remove(trail.object);
+            trail.dispose();
+            trail = null;
+        }
+        materials.length = 4;
+        trailScale = TRAIL_SCALE[mode] || 1;
+        u.uTrailGain.value = TRAIL_GAIN[mode] || 1;
+        trail = createCpuTrail(mode, { u, n, pos, vel, k: EXP, glsl: trailGLSL, sizePx: 0.0075, spacing: 0.0015, sub: 6 });
+        if (!trail)
+            return;
+        object.add(trail.object);
+        materials.push(...trail.materials);
+    }
+    buildTrails(c.trailMode, c.trailShare);
+    function upload() {
+        posAttr.needsUpdate = true;
+        lAttr.needsUpdate = true;
+        for (let k = 0; k < MAX_PEBBLES; k++) {
+            const v = u.uPebbles.value[k];
+            pp[k * 3] = v.x;
+            pp[k * 3 + 1] = 0.004;
+            pp[k * 3 + 2] = v.y;
+            pa[k * 2] = v.z;
+            pa[k * 2 + 1] = v.w > 0 ? Math.min(v.w, 2) : 0;
+        }
+        ppAttr.needsUpdate = true;
+        paAttr.needsUpdate = true;
+    }
+    return {
+        object,
+        materials,
+        apply(cfg) { if (cfg)
+            buildTrails(cfg.trailMode, cfg.trailShare); },
+        update(dt, camera, pointer) {
+            const rdt = Math.min(Math.max(dt, 0), 1 / 20);
+            if (camera && !inView(object, camera, BOUNDS.center, BOUNDS.radius, u.uSize.value))
+                return;
+            const d = rdt * u.uSpeed.value;
+            u.uTime.value += d;
+            if (camera) {
+                object.worldToLocal(u.uCamLocal.value.copy(camera.position)).divideScalar(u.uSize.value);
+                if (pointer)
+                    stepPointerField(u, pointer, camera, object, u.uSize.value, rdt, anchor, up);
+            }
+            u.uVelScale.value = trailScale; // the sea moves slowly: exposures look back further
+            let simD = 0;
+            stepper.run(d, (hh) => { step(hh); simD += hh; });
+            if (simD > 0) {
+                upload();
+                if (trail)
+                    trail.update(simD * trailScale);
+            }
+        },
+        seek(t) { for (let s = 0; s < Math.round(t / H_STEP); s++)
+            step(H_STEP); upload(); },
+        dispose() {
+            geo.dispose();
+            mat.dispose();
+            hmat.dispose();
+            sgeo.dispose();
+            smat.dispose();
+            pgeo.dispose();
+            pmat.dispose();
+            proxy.dispose();
+            if (trail)
+                trail.dispose();
+        },
+        _state: { pos, vel, L, res, EXP },
+    };
+}
+/** Defaults for every knob, so an older saved config still renders (identical to the catalog entry). */
+const DEFAULTS = {
+    intensity: 1,
+    speed: 1,
+    opacity: 0.9,
+    size: 1,
+    color: '#3cc3ff',
+    particleCount: 36000,
+    swellHeight: 1,
+    current: 0.3,
+    sensitivity: 1,
+    recovery: 6,
+    glowTime: 1,
+    waterClarity: 1,
+    deepColor: '#1a8f8a',
+    moonlight: 0.6,
+    seed: 1,
+    quality: 'medium',
+    pointerMode: 'fish',
+    pointerStrength: 1,
+    pointerRadius: 1,
+    pointerColor: '#dff4ff',
+    trailMode: 'streak',
+    trailLength: 1.5,
+    trailOpacity: 0.6,
+    trailColor: '#2f7dff',
+    trailShare: 1,
+};
+/** Knobs that rebuild the simulation: they change on commit, never through the live path. */
+const STRUCTURAL = ['particleCount', 'seed', 'quality'];
+/** Knobs an animation (or mouse move) may drive per frame — generated from applyConfig. */
+const ANIMATABLE = new Set(GENERATIVE_PARTICLES_ANIMATABLE.bioluminescentWake.map((p) => p.value));
+const BioluminescentWakeParticles = ({ id, size, config, animations, onObjectReady, onObjectDispose }) => {
+    const rootRef = useRef(null);
+    useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
+    const s = size > 0 ? size : 1;
+    const cfg = useMemo(() => ({ ...DEFAULTS, ...config }), [config]);
+    // uniforms outlive the objects, so keyframe animations survive a rebuild
+    const uniforms = useMemo(() => createUniforms(), []);
+    // rebuilt only when a structural knob changes (trails rebuild inside apply())
+    const instance = useMemo(() => build(uniforms, cfg, s), [uniforms, cfg.particleCount, cfg.seed, cfg.quality]);
+    useEffect(() => () => instance.dispose(), [instance]);
+    useLayoutEffect(() => {
+        applyConfig(uniforms, cfg, s);
+        instance.apply(cfg);
+    }, [instance, uniforms, cfg, s]);
+    // Slider drags and keyframe animations are both overrides on the committed config.
+    // This is the one place they are merged and pushed, so they compose instead of
+    // overwriting each other; the animation wins, because it is the active driver.
+    const keyframes = animations?.particles?.animations;
+    const animOverride = useRef({});
+    const animFrom = useRef({});
+    const animStart = useRef(0);
+    // Editing a keyframe restarts its cycle rather than dropping the user mid-way.
+    useEffect(() => { animStart.current = performance.now(); animFrom.current = {}; }, [keyframes]);
+    const push = useCallback((overrides) => {
+        const merged = { ...cfg, ...overrides, ...animOverride.current };
+        const z = merged.size;
+        applyConfig(uniforms, merged, z && z > 0 ? z : s);
+    }, [cfg, uniforms, s]);
+    const live = useConfigLiveHandle(rootRef, id, 'particles', cfg, STRUCTURAL, push);
+    const pointer = usePointerField();
+    useFrame((state, delta) => {
+        instance.update(Math.min(delta, 0.1), state.camera, pointer);
+        if (keyframes?.length) {
+            applyConfigKeyframeAnimations(keyframes, animFrom.current, cfg, animOverride.current, performance.now() - animStart.current, ANIMATABLE);
+            push(live.current);
+        }
+    });
+    return (_jsx("group", { ref: rootRef, children: _jsx("primitive", { object: instance.object }) }));
+};
+export default BioluminescentWakeParticles;