@3driseai/3drise-viewer 0.1.19 → 0.1.20

package/dist/components/particles/ChladniSandParticles.js

@@ -0,0 +1,912 @@
+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';
+/**
+ * Chladni Sand — Sand on an invisible vibrating plate: resonant plate modes throw grains onto the nodal lines, drawing Chladni figures that form and re-form; the cursor bows, touches or taps the plate. Use for science, sound and abstract scenes.
+ */
+// Chladni Sand — sand dancing on a bowed metal plate (cymatics, Chladni 1787). Particles only: the
+// plate itself is invisible; the sand draws the figures.
+// Movement: the plate is a centre-clamped square plate. Its standing waves are the classic Chladni
+//           combinations phi = cos(m pi u) cos(n pi v) +/- cos(n pi u) cos(m pi v), each ringing with a
+//           Lorentzian resonance around its own frequency (the + and - pair are split, the seed adds
+//           small plate imperfections). The drive frequency glides slowly through the resonances, so
+//           figures form, dissolve and re-form. Where the plate's acceleration exceeds g (Gamma > 1)
+//           grains are thrown up; each hop lands a random step away with a step length that grows
+//           with the local vibration, so grains random-walk out of the moving regions and freeze on
+//           the nodal lines. Grains that hop off the edge fall away and are sprinkled back on.
+// Colour:   the sand is lit by a low raking light over its own pile height (density -> heightfield
+//           -> normal), so the ridges read in relief; a few dark mineral grains; grains in flight
+//           leave the pile's shadow and catch the light in the second colour.
+// Mouse (pointerMode; the cursor lives on the plate plane):
+//   bow    — a violin bow on the nearest point of the edge: modes with an antinode there are
+//            favoured and bowing speed pumps energy in; rosin dust puffs off the edge.
+//   finger — a fingertip touching the plate forces a node there: modes that move under it are
+//            damped, so the figure snaps to one with a nodal line through the finger.
+//   tap    — taps along the cursor path: a dispersive bending wave rings outward, throwing grains
+//            in an expanding ring, and the broadband ring-down scrambles the figure for a moment.
+// Trails (trailMode): streak = long exposure (hop arcs), comet = migration paths, echo = dust haze.
+//
+// Generated from the approved lab module (particle lab, batch 3). Sim units = object-local / size.
+// ---------------------------------------------------------------------------------------------
+// Engine features
+// ---------------------------------------------------------------------------------------------
+const QUALITY_SCALE = { low: 0.5, medium: 1, high: 1.6 };
+/** 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) };
+}
+function qualityScale(q) { return QUALITY_SCALE[q] || 1; }
+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;
+}
+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;
+        },
+        reset() { acc = 0; },
+    };
+}
+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();
+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 = ['bow', 'finger', 'tap'];
+const HX = 1; // half size of the plate (sim units)
+const NG = 97; // vibration grid (odd -> a sample at the clamped centre)
+const DG = 72; // sand heightfield grid
+const NMAX = 10; // highest mode index
+const H_STEP = 1 / 60;
+const G_SIM = 7.5; // gravity for the hops (slow, calm)
+const GAIN = 1.7; // Gamma per unit of normalised displacement at amplitude 1
+const SWEEP_T = 46; // seconds per sweep cycle
+const RING_UP = 0.45; // mode amplitude time constant (the plate rings up / down)
+const MAX_TAPS = 4;
+const NPUFF = 320;
+const BOUNDS = { center: [0, 0, 0], radius: 1.55 };
+const TRAIL_GAIN = { streak: 3, comet: 2.5, echo: 5 };
+function createUniforms() {
+    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 },
+        uFrequency: { value: 5 },
+        uSweep: { value: 0.3 },
+        uDamping: { value: 0.05 },
+        uAmplitude: { value: 1 },
+        uHopColor: colorUniform('#ffffff'),
+        uLightAngle: { value: 22 },
+        uGrainSize: { value: 1 },
+        uPointerMode: { value: 0 },
+        uPointerStrength: { value: 1 },
+        uPointerRadius: { value: 1 },
+        uPointerColor: colorUniform('#ffffff'),
+        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.uFrequency.value = c.frequency;
+    u.uSweep.value = c.sweep;
+    u.uDamping.value = c.damping;
+    u.uAmplitude.value = c.amplitude;
+    u.uHopColor.value.set(c.hopColor);
+    u.uLightAngle.value = c.lightAngle;
+    u.uGrainSize.value = c.grainSize;
+    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;';
+// ---- grains: lit over their heightfield; in flight they take the hop colour ----
+const grainVertex = /* glsl */ `
+${BASE_U}
+uniform vec3 uColor, uHopColor;
+uniform float uGrainSize;
+attribute float aShade;   // raking-light factor (1 = flat); >= 1.15 means the grain is in flight
+attribute float aSeed;    // size / mineral seed
+varying vec3 vCol;
+varying float vA;
+void main() {
+  vec4 mv = modelViewMatrix * vec4(position * uSize, 1.0);
+  // mineral mix: a few dark grains (magnetite), the rest quartz of slightly varying tone
+  float tone = aSeed < 0.07 ? 0.38 : 0.82 + 0.36 * fract(aSeed * 17.3);
+  float flying = step(1.15, aShade);
+  vCol = mix(uColor * tone * aShade, uHopColor * min(aShade, 1.6), flying) * uIntensity;
+  vA = uOpacity;
+  float px = uGrainSize * uSize * uViewH * 0.0085 * (0.75 + 0.5 * aSeed) / -mv.z;
+  gl_PointSize = clamp(px, 1.0, 24.0);
+  gl_Position = projectionMatrix * mv;
+}
+`;
+const grainFragment = /* 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;
+  // a small lit sphere, a touch brighter toward the light side
+  float a = (1.0 - smoothstep(0.55, 1.0, r2)) * (1.0 - 0.125 * (d.x - d.y)) * vA;
+  if (a < 0.01) discard;
+  gl_FragColor = vec4(vCol, a);
+}
+`;
+// rosin dust off the bowed edge
+const puffVertex = /* glsl */ `
+${BASE_U}
+attribute float aAge;
+varying float vA;
+void main() {
+  vec4 mv = modelViewMatrix * vec4(position * uSize, 1.0);
+  vA = aAge < 0.0 ? 0.0 : exp(-aAge / 0.5) * smoothstep(0.0, 0.05, aAge) * uOpacity;
+  gl_PointSize = clamp(uSize * uViewH * 0.009 * (1.0 + 2.0 * max(aAge, 0.0)) / -mv.z, 1.0, 30.0) * step(0.003, vA);
+  gl_Position = projectionMatrix * mv;
+}
+`;
+const puffFragment = /* glsl */ `
+uniform vec3 uPointerColor;
+uniform float 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 a = exp(-r2 * 3.5) * (1.0 - r2) * vA * 0.6;
+  if (a < 0.004) discard;
+  gl_FragColor = vec4(uPointerColor * uIntensity, a);
+}
+`;
+function build(u, c, size) {
+    const q = qualityScale(c.quality);
+    const n = Math.max(500, Math.round(c.particleCount * q));
+    const rng = mulberry32(seedMix(0xc4a1, c.seed));
+    // ---- modes: Chladni pairs with split +/- frequencies and small seeded imperfections ----
+    const modes = [];
+    for (let m = 0; m <= NMAX; m++)
+        for (let nn = m; nn <= NMAX; nn++) {
+            for (const s of m === nn ? [1] : [1, -1]) {
+                const f0 = Math.sqrt(m * m + nn * nn);
+                if (f0 < 1.9)
+                    continue;
+                modes.push({ m, n: nn, s, f: f0 * (1 + (m === nn ? 0 : s * 0.035)) * (1 + 0.012 * gauss(rng)) });
+            }
+        }
+    const K = modes.length;
+    // cosine tables on the grid, and each mode's RMS so every shape has unit RMS
+    const C = new Float32Array((NMAX + 1) * NG);
+    for (let m = 0; m <= NMAX; m++)
+        for (let i = 0; i < NG; i++)
+            C[m * NG + i] = Math.cos((m * Math.PI * i) / (NG - 1));
+    const norm = new Float32Array(K);
+    for (let k = 0; k < K; k++) {
+        const { m, n: nn, s } = modes[k];
+        let acc = 0;
+        for (let j = 0; j < NG; j++)
+            for (let i = 0; i < NG; i++) {
+                const v = C[m * NG + i] * C[nn * NG + j] + s * C[nn * NG + i] * C[m * NG + j];
+                acc += v * v;
+            }
+        norm[k] = 1 / Math.sqrt(acc / (NG * NG) + 1e-9);
+    }
+    function phiAt(k, x, z) {
+        const md = modes[k];
+        const a = (x + HX) * Math.PI / (2 * HX), b = (z + HX) * Math.PI / (2 * HX);
+        return (Math.cos(md.m * a) * Math.cos(md.n * b) + md.s * Math.cos(md.n * a) * Math.cos(md.m * b)) * norm[k];
+    }
+    const A = new Float32Array(K); // resonant amplitudes (ring up / down)
+    const E = new Float32Array(K); // tap ring-down (signed)
+    const W = new Float32Array(NG * NG);
+    const active = new Int32Array(K);
+    const T = new Float32Array(K);
+    const topQ = new Int32Array(8), topV = new Float32Array(8);
+    let stepNo = 0;
+    // ---- grains ----
+    const pos = new Float32Array(n * 3), vel = new Float32Array(n * 3);
+    const shade = new Float32Array(n);
+    const seedA = new Float32Array(n);
+    const EXP = new Float32Array(n);
+    const ground = new Uint8Array(n); // 1 resting on the plate
+    const thr = new Float32Array(n);
+    const pileY = new Float32Array(n); // per-grain jitter inside the pile
+    function sprinkle(i, warm) {
+        const j = i * 3;
+        pos[j] = (rng() * 2 - 1) * HX * 0.97;
+        pos[j + 2] = (rng() * 2 - 1) * HX * 0.97;
+        if (warm) {
+            pos[j + 1] = 0;
+            ground[i] = 1;
+            vel[j] = vel[j + 1] = vel[j + 2] = 0;
+        }
+        else {
+            pos[j + 1] = 0.35 + 0.35 * rng();
+            ground[i] = 0;
+            vel[j] = 0;
+            vel[j + 1] = -0.6;
+            vel[j + 2] = 0;
+        }
+    }
+    for (let i = 0; i < n; i++) {
+        sprinkle(i, true);
+        seedA[i] = rng();
+        thr[i] = 1 + 0.12 * gauss(rng);
+        pileY[i] = rng();
+        shade[i] = 1;
+    }
+    // ---- pointer agents ----
+    const TP = new Float32Array(MAX_TAPS * 4);
+    for (let k = 0; k < MAX_TAPS; k++)
+        TP[k * 4 + 2] = 99;
+    let tapHead = 0, tapClock = 0, lastTapX = 1e9, lastTapZ = 1e9;
+    const PP = new Float32Array(NPUFF * 3), PV = new Float32Array(NPUFF * 3), PA = new Float32Array(NPUFF);
+    PA.fill(-1);
+    let puffHead = 0, puffAcc = 0;
+    const hp = new THREE.Vector3(), hv = new THREE.Vector3();
+    const WARM = 200 * H_STEP * 2;
+    let time = -WARM; // the sweep's phase is 0 when the object appears
+    // one uniform draw per call keeps the hop statistics deterministic
+    const hr = mulberry32(seedMix(0x7ab5, c.seed));
+    function sampleW(x, z, out) {
+        let fx = (x + HX) / (2 * HX) * (NG - 1), fz = (z + HX) / (2 * HX) * (NG - 1);
+        if (fx < 0)
+            fx = 0;
+        else if (fx > NG - 1.001)
+            fx = NG - 1.001;
+        if (fz < 0)
+            fz = 0;
+        else if (fz > NG - 1.001)
+            fz = NG - 1.001;
+        const i0 = fx | 0, j0 = fz | 0, tx = fx - i0, tz = fz - j0;
+        const o = j0 * NG + i0;
+        const w00 = W[o], w10 = W[o + 1], w01 = W[o + NG], w11 = W[o + NG + 1];
+        const a = w00 + (w10 - w00) * tx, b = w01 + (w11 - w01) * tx;
+        out[0] = a + (b - a) * tz;
+        const inv = (NG - 1) / (2 * HX);
+        out[1] = ((w10 - w00) + ((w11 - w01) - (w10 - w00)) * tz) * inv;
+        out[2] = (b - a) * inv;
+    }
+    const smp = new Float32Array(3);
+    function step(h) {
+        time += h;
+        const amp = Math.max(u.uAmplitude.value, 0);
+        const fEff = u.uFrequency.value * Math.pow(2, u.uSweep.value * Math.sin((6.2831853 * time) / SWEEP_T));
+        const bw = Math.max(u.uDamping.value, 0.005);
+        // pointer
+        const mode = u.uPointerMode.value;
+        const S = u.uPointerStrength.value, act = u.uPointerActive.value, Rr = u.uPointerRadius.value;
+        hp.copy(u.uPointer.value);
+        hv.copy(u.uPointerVel.value);
+        const spd = Math.hypot(hv.x, hv.z);
+        const bowS = mode === 0 && S > 0.01 ? S * act * Math.min(1, spd / 0.6) : 0;
+        const fingS = mode === 1 && S > 0.01 && Math.abs(hp.x) < HX && Math.abs(hp.z) < HX ? S * act : 0;
+        // bow point: nearest point on the plate edge
+        let bx = Math.max(-HX, Math.min(HX, hp.x)), bz = Math.max(-HX, Math.min(HX, hp.z));
+        if (HX - Math.abs(bx) < HX - Math.abs(bz))
+            bx = Math.sign(bx || 1) * HX;
+        else
+            bz = Math.sign(bz || 1) * HX;
+        const ex = Math.abs(bx) === HX ? 0 : 1, ez = 1 - ex; // direction along the edge
+        // taps
+        const useTap = mode === 2 && S > 0.01;
+        tapClock += h;
+        if (useTap && act > 0.6 && Math.abs(hp.x) < HX && Math.abs(hp.z) < HX) {
+            const moved = Math.hypot(hp.x - lastTapX, hp.z - lastTapZ);
+            if ((tapClock > 0.4 || moved > 0.16) && tapClock > 0.12) {
+                const k = tapHead % MAX_TAPS;
+                tapHead++;
+                TP[k * 4] = hp.x;
+                TP[k * 4 + 1] = hp.z;
+                TP[k * 4 + 2] = 0;
+                TP[k * 4 + 3] = S * Rr;
+                tapClock = 0;
+                lastTapX = hp.x;
+                lastTapZ = hp.z;
+                // broadband ring-down: every mode is struck in proportion to its shape at the tap
+                for (let q = 0; q < K; q++)
+                    E[q] += 0.35 * S * phiAt(q, hp.x, hp.z) / (1 + modes[q].f / 5); // a light global ring-down
+            }
+        }
+        for (let k = 0; k < MAX_TAPS; k++)
+            TP[k * 4 + 2] += h;
+        const decE = Math.exp(-h / 0.7);
+        const kA = 1 - Math.exp(-h / (RING_UP / (1 + 3 * Math.max(bowS, fingS))));
+        const bwEff = bw * (1 + 6 * bowS);
+        let maxBase = 0, maxNew = 0;
+        for (let q = 0; q < K; q++) {
+            const d0 = (fEff - modes[q].f) / (bw * modes[q].f);
+            const t0 = 1 / ((1 + d0 * d0) * (1 + d0 * d0)); // response power: clean, well-separated figures
+            if (t0 > maxBase)
+                maxBase = t0;
+            const d = (fEff - modes[q].f) / (bwEff * modes[q].f);
+            let t = 1 / ((1 + d * d) * (1 + d * d));
+            if (bowS > 0) {
+                // edge coupling, averaged over the bow width
+                let cpl = 0;
+                for (let s = -2; s <= 2; s++) {
+                    const o = s * 0.03 * Rr;
+                    const p = phiAt(q, Math.max(-HX, Math.min(HX, bx + ex * o)), Math.max(-HX, Math.min(HX, bz + ez * o)));
+                    cpl += p * p;
+                }
+                t *= (1 - bowS * 0.95) + bowS * 0.95 * 1.3 * cpl / 5;
+            }
+            if (fingS > 0) {
+                let sup = 0;
+                for (let s = 0; s < 5; s++) {
+                    const ang = s * 1.2566;
+                    const r = s === 0 ? 0 : 0.035 * Rr;
+                    const p = phiAt(q, hp.x + r * Math.cos(ang), hp.z + r * Math.sin(ang));
+                    sup += p * p;
+                }
+                t *= Math.exp(-5 * fingS * sup / 5);
+            }
+            T[q] = t;
+            if (t > maxNew)
+                maxNew = t;
+        }
+        // the drive's energy goes into the modes the bow / finger allow: keep the loudest one at the
+        // undisturbed level (a bow pumps a little more in, a finger takes a little out)
+        const target = bowS > 0 ? Math.max(maxBase, 0.6) * (1 + 1.2 * bowS) : fingS > 0 ? maxBase * (1 - 0.2 * fingS / (1 + fingS)) : maxBase;
+        const rescale = (bowS > 0 || fingS > 0) && maxNew > 1e-6 ? target / maxNew : 1;
+        let nAct = 0, peak = 0;
+        for (let q = 0; q < K; q++) {
+            const t = T[q] * rescale;
+            A[q] += (t - A[q]) * kA;
+            E[q] *= decE;
+            const v = A[q] + E[q];
+            if (Math.abs(v) > 0.03)
+                active[nAct++] = q;
+            if (Math.abs(v) > peak)
+                peak = Math.abs(v);
+        }
+        stepNo++;
+        // vibration field on the grid (modes ring up over ~0.45 s, so every other step is plenty)
+        if ((stepNo & 1) === 1 || nAct === 0) {
+            W.fill(0);
+            for (let a = 0; a < nAct; a++) {
+                const q = active[a];
+                const { m, n: nn, s } = modes[q];
+                const cc = (A[q] + E[q]) * norm[q];
+                for (let j = 0; j < NG; j++) {
+                    const cmj = C[m * NG + j], cnj = C[nn * NG + j];
+                    const row = j * NG;
+                    for (let i = 0; i < NG; i++)
+                        W[row + i] += cc * (C[m * NG + i] * cnj + s * C[nn * NG + i] * cmj);
+                }
+            }
+        }
+        // rosin dust
+        if (bowS > 0.05) {
+            puffAcc += bowS * 90 * h;
+            while (puffAcc >= 1) {
+                puffAcc -= 1;
+                const k = puffHead % NPUFF;
+                puffHead++;
+                const o = (hr() - 0.5) * 0.08 * Rr;
+                PP[k * 3] = bx + ex * o;
+                PP[k * 3 + 1] = 0.005;
+                PP[k * 3 + 2] = bz + ez * o;
+                const outx = ex === 0 ? Math.sign(bx) : 0, outz = ez === 0 ? Math.sign(bz) : 0;
+                PV[k * 3] = outx * (0.06 + 0.1 * hr()) + (hr() - 0.5) * 0.08;
+                PV[k * 3 + 1] = 0.04 + 0.12 * hr();
+                PV[k * 3 + 2] = outz * (0.06 + 0.1 * hr()) + (hr() - 0.5) * 0.08;
+                PA[k] = 0;
+            }
+        }
+        for (let k = 0; k < NPUFF; k++) {
+            if (PA[k] < 0)
+                continue;
+            PA[k] += h;
+            if (PA[k] > 2.5) {
+                PA[k] = -1;
+                continue;
+            }
+            const dmp = Math.exp(-h / 0.6);
+            PV[k * 3] *= dmp;
+            PV[k * 3 + 1] = PV[k * 3 + 1] * dmp - 0.02 * h;
+            PV[k * 3 + 2] *= dmp;
+            PP[k * 3] += PV[k * 3] * h;
+            PP[k * 3 + 1] += PV[k * 3 + 1] * h;
+            PP[k * 3 + 2] += PV[k * 3 + 2] * h;
+        }
+        // ---- grains ----
+        const gain = amp * GAIN;
+        const HOP = 0.62, HSTEP = 0.22, DRIFT = 0.05;
+        const fric = Math.exp(-h / 0.04);
+        const decEx = Math.exp(-h / Math.max(0.5 * u.uTrailLength.value, 0.1));
+        let nTap = 0;
+        for (let k = 0; k < MAX_TAPS; k++)
+            if (TP[k * 4 + 2] < 1.4 && TP[k * 4 + 3] > 0)
+                nTap++;
+        // direct contact: the fingertip ploughs through the sand; the bow's stick-slip rattles the edge
+        const RF = 0.07 * Rr, RB = 0.28 * Rr;
+        const handOn = fingS > 0.02 || bowS > 0.02;
+        const fvx = Math.max(-1.5, Math.min(1.5, hv.x)), fvz = Math.max(-1.5, Math.min(1.5, hv.z));
+        for (let i = 0; i < n; i++) {
+            const j = i * 3;
+            let x = pos[j], y = pos[j + 1], z = pos[j + 2];
+            let vx = vel[j], vy = vel[j + 1], vz = vel[j + 2];
+            const onPlate = x > -HX && x < HX && z > -HX && z < HX;
+            // resting grains with no velocity are re-checked every third step (the field changes slowly)
+            if (ground[i] && vx === 0 && vz === 0 && !nTap && !handOn && onPlate && (i + stepNo) % 3 !== 0) {
+                EXP[i] *= decEx;
+                continue;
+            }
+            if (onPlate)
+                sampleW(x, z, smp);
+            else {
+                smp[0] = 0;
+                smp[1] = 0;
+                smp[2] = 0;
+            }
+            const w = smp[0], gx = smp[1], gz = smp[2];
+            const aw = w < 0 ? -w : w;
+            const G = Math.min(gain * aw, 6);
+            if (!onPlate) {
+                // fell off the edge: free fall, then a fresh sprinkle from above
+                ground[i] = 0;
+                vy -= G_SIM * h;
+                x += vx * h;
+                y += vy * h;
+                z += vz * h;
+                if (y < -0.6) {
+                    pos[j] = x;
+                    pos[j + 1] = y;
+                    pos[j + 2] = z;
+                    sprinkle(i, false);
+                    x = pos[j];
+                    y = pos[j + 1];
+                    z = pos[j + 2];
+                    vx = vel[j];
+                    vy = vel[j + 1];
+                    vz = vel[j + 2];
+                    if (trail)
+                        trail.reset(i);
+                }
+            }
+            else if (ground[i]) {
+                if (G > thr[i]) {
+                    // hop: height from the excess acceleration, a random step that grows with the vibration
+                    const ex2 = Math.sqrt(G - thr[i]);
+                    vy = HOP * ex2 * (0.55 + 0.8 * hr());
+                    const ang = 6.2831853 * hr();
+                    const st = HSTEP * ex2 * (0.3 + hr());
+                    const sg = w >= 0 ? 1 : -1;
+                    let dx = -DRIFT * sg * gx, dz = -DRIFT * sg * gz;
+                    const dl = Math.hypot(dx, dz);
+                    if (dl > 0.12) {
+                        dx *= 0.12 / dl;
+                        dz *= 0.12 / dl;
+                    }
+                    vx = Math.cos(ang) * st + dx;
+                    vz = Math.sin(ang) * st + dz;
+                    ground[i] = 0;
+                    y = 0.001;
+                }
+                else {
+                    vx *= fric;
+                    vz *= fric;
+                    vy = 0;
+                    if (vx * vx + vz * vz < 1e-6) {
+                        vx = 0;
+                        vz = 0;
+                    }
+                    x += vx * h;
+                    z += vz * h;
+                }
+            }
+            else {
+                vy -= G_SIM * h;
+                x += vx * h;
+                y += vy * h;
+                z += vz * h;
+                if (y <= 0 && x > -HX && x < HX && z > -HX && z < HX) {
+                    y = 0;
+                    vy = 0;
+                    vx *= 0.25;
+                    vz *= 0.25;
+                    ground[i] = 1;
+                    if (vx * vx + vz * vz < 1e-6) {
+                        vx = 0;
+                        vz = 0;
+                    }
+                }
+            }
+            if (handOn && onPlate) {
+                if (fingS > 0.02) {
+                    const dx = x - hp.x, dz = z - hp.z, d2 = dx * dx + dz * dz;
+                    if (d2 < RF * RF && y < 0.03) {
+                        // pushed out of the fingertip's footprint, carried along with its motion: a groove
+                        const d = Math.sqrt(d2) + 1e-5;
+                        x = hp.x + dx / d * RF * 1.02;
+                        z = hp.z + dz / d * RF * 1.02;
+                        vx = dx / d * 0.25 * fingS + fvx * 0.6;
+                        vz = dz / d * 0.25 * fingS + fvz * 0.6;
+                        if (hr() < 0.25) {
+                            vy = 0.25 + 0.3 * hr();
+                            ground[i] = 0;
+                            y = Math.max(y, 0.001);
+                        }
+                    }
+                }
+                if (bowS > 0.02 && ground[i]) {
+                    const dx = x - bx, dz = z - bz, d2 = dx * dx + dz * dz;
+                    if (d2 < RB * RB && hr() < bowS * 0.35 * (1 - Math.sqrt(d2) / RB)) {
+                        // grains near the bowed edge chatter: sharp hops, thrown in from the edge
+                        const ang = 6.2831853 * hr();
+                        vy = 0.5 + 0.6 * hr() * bowS;
+                        vx = Math.cos(ang) * 0.2 - (ex === 0 ? Math.sign(bx) * 0.25 : 0);
+                        vz = Math.sin(ang) * 0.2 - (ez === 0 ? Math.sign(bz) * 0.25 : 0);
+                        ground[i] = 0;
+                        y = 0.001;
+                    }
+                }
+            }
+            // tap bending waves throw the grains they pass
+            if (nTap && onPlate && ground[i]) {
+                for (let k = 0; k < MAX_TAPS; k++) {
+                    const age = TP[k * 4 + 2];
+                    if (age >= 1.4 || TP[k * 4 + 3] <= 0)
+                        continue;
+                    const dx = x - TP[k * 4], dz = z - TP[k * 4 + 1];
+                    const r = Math.sqrt(dx * dx + dz * dz) + 1e-4;
+                    // the bending wave is damped within the tap's reach (pointerRadius): a local ring
+                    const reach = 0.3 * TP[k * 4 + 3] / Math.max(S, 0.01);
+                    const rf = 0.8 * age, wd = 0.025 + 0.04 * age;
+                    if (rf > 1.3 * reach)
+                        continue;
+                    const off = r - rf;
+                    if (off * off < wd * wd) {
+                        const e = S * Math.exp(-(rf * rf) / (reach * reach)) * (r < 0.25 * reach ? 1.3 : 1);
+                        if (hr() < 0.85) {
+                            vy = Math.min(1.3, 0.9 * e * (0.6 + 0.8 * hr()));
+                            vx = dx / r * 0.4 * e + (hr() - 0.5) * 0.12;
+                            vz = dz / r * 0.4 * e + (hr() - 0.5) * 0.12;
+                            ground[i] = 0;
+                            y = Math.max(y, 0.001);
+                        }
+                    }
+                }
+            }
+            pos[j] = x;
+            pos[j + 1] = y;
+            pos[j + 2] = z;
+            vel[j] = vx;
+            vel[j + 1] = vy;
+            vel[j + 2] = vz;
+            // exposure memory of the grain's speed (trails are shaded by it)
+            const sp = Math.sqrt(vx * vx + vy * vy + vz * vz);
+            const e = EXP[i] * decEx;
+            EXP[i] = sp > e ? sp : e;
+        }
+        lastPeak = peak;
+    }
+    let lastPeak = 0;
+    let trail = null, trailKey = '';
+    // ---- sand heightfield -> raking-light shade per grain (render only) ----
+    const DC = new Float32Array(DG * DG), DS = new Float32Array(DG * DG), HS = new Float32Array(DG * DG);
+    const rpos = new Float32Array(n * 3);
+    function shadeGrains() {
+        DC.fill(0);
+        for (let i = 0; i < n; i++) {
+            if (!ground[i])
+                continue;
+            const gx = Math.floor((pos[i * 3] + HX) / (2 * HX) * DG), gz = Math.floor((pos[i * 3 + 2] + HX) / (2 * HX) * DG);
+            if (gx < 0 || gz < 0 || gx >= DG || gz >= DG)
+                continue;
+            DC[gz * DG + gx] += 1;
+        }
+        // one 3x3 blur, then height ~ sqrt(count) (a grain pile's volume spreads into its footprint)
+        const avg = n / (DG * DG);
+        for (let j = 0; j < DG; j++)
+            for (let i = 0; i < DG; i++) {
+                let s = 0, wsum = 0;
+                for (let b = -1; b <= 1; b++)
+                    for (let a = -1; a <= 1; a++) {
+                        const ii = i + a, jj = j + b;
+                        if (ii < 0 || jj < 0 || ii >= DG || jj >= DG)
+                            continue;
+                        const ww = a === 0 && b === 0 ? 4 : (a === 0 || b === 0 ? 2 : 1);
+                        s += DC[jj * DG + ii] * ww;
+                        wsum += ww;
+                    }
+                DS[j * DG + i] = Math.sqrt(s / wsum / avg);
+            }
+        const el = (u.uLightAngle.value * Math.PI) / 180;
+        const Lx = -0.78 * Math.cos(el), Ly = Math.sin(el), Lz = 0.62 * Math.cos(el);
+        const Ll = Math.hypot(Lx, Ly, Lz);
+        const cell = (2 * HX) / DG, HK = 0.006;
+        for (let j = 0; j < DG; j++)
+            for (let i = 0; i < DG; i++) {
+                const hL = DS[j * DG + Math.max(i - 1, 0)], hR = DS[j * DG + Math.min(i + 1, DG - 1)];
+                const hD = DS[Math.max(j - 1, 0) * DG + i], hU = DS[Math.min(j + 1, DG - 1) * DG + i];
+                const dx = (hR - hL) * HK / (2 * cell) * 3, dz = (hU - hD) * HK / (2 * cell) * 3;
+                const nl = Math.hypot(dx, 1, dz);
+                const ndl = (-dx * Lx + Ly - dz * Lz) / (nl * Ll);
+                HS[j * DG + i] = Math.max(0.12, 0.35 + 0.65 * Math.max(ndl, 0) / (Ly / Ll));
+            }
+        for (let i = 0; i < n; i++) {
+            const j = i * 3;
+            rpos[j] = pos[j];
+            rpos[j + 2] = pos[j + 2];
+            const gx = Math.floor((pos[j] + HX) / (2 * HX) * DG), gz = Math.floor((pos[j + 2] + HX) / (2 * HX) * DG);
+            const inside = gx >= 0 && gz >= 0 && gx < DG && gz < DG;
+            const hgt = inside ? DS[gz * DG + gx] * HK : 0;
+            if (ground[i]) {
+                rpos[j + 1] = hgt * (0.35 + 0.65 * pileY[i]) + 0.002;
+                shade[i] = inside ? Math.min(HS[gz * DG + gx], 1.1) : 1;
+            }
+            else {
+                rpos[j + 1] = pos[j + 1] + 0.002 + hgt * 0.5;
+                shade[i] = 1.15 + Math.min(pos[j + 1] * 8, 0.4);
+            }
+        }
+    }
+    const stepper = createFixedStep(H_STEP, 4);
+    for (let s = 0; s < 200; s++)
+        step(H_STEP * 2); // ~7 s of hops at a coarse step: the first figure has formed
+    shadeGrains();
+    // ---- geometry ----
+    const geo = new THREE.BufferGeometry();
+    const posAttr = new THREE.BufferAttribute(rpos, 3).setUsage(THREE.DynamicDrawUsage);
+    const shAttr = new THREE.BufferAttribute(shade, 1).setUsage(THREE.DynamicDrawUsage);
+    geo.setAttribute('position', posAttr);
+    geo.setAttribute('aShade', shAttr);
+    geo.setAttribute('aSeed', new THREE.BufferAttribute(seedA, 1));
+    const mat = new THREE.ShaderMaterial({
+        uniforms: u, vertexShader: grainVertex, fragmentShader: grainFragment,
+        transparent: true, depthWrite: false,
+    });
+    const grains = new THREE.Points(geo, mat);
+    grains.frustumCulled = false;
+    grains.renderOrder = 2;
+    attachViewH(grains, u);
+    const fgeo = new THREE.BufferGeometry();
+    const ppAttr = new THREE.BufferAttribute(PP, 3).setUsage(THREE.DynamicDrawUsage);
+    const paAttr = new THREE.BufferAttribute(PA, 1).setUsage(THREE.DynamicDrawUsage);
+    fgeo.setAttribute('position', ppAttr);
+    fgeo.setAttribute('aAge', paAttr);
+    const fmat = new THREE.ShaderMaterial({
+        uniforms: u, vertexShader: puffVertex, fragmentShader: puffFragment,
+        transparent: true, depthWrite: false, blending: THREE.AdditiveBlending,
+    });
+    const puffs = new THREE.Points(fgeo, fmat);
+    puffs.frustumCulled = false;
+    puffs.renderOrder = 3;
+    const object = new THREE.Group();
+    const proxy = createPickProxy(BOUNDS.center, BOUNDS.radius);
+    object.add(grains, puffs, proxy.mesh);
+    const anchor = new THREE.Vector3(0, 0, 0);
+    const up = new THREE.Vector3(0, 1, 0);
+    // ---- trails: grains in motion, shaded by an exposure memory of their speed ----
+    const trailGLSL = /* glsl */ `
+uniform vec3 uColor, uHopColor;
+uniform float uTrailGain;
+vec3 trailShade(vec3 p, float f) {
+  float e = clamp(TRAIL_K * 2.2, 0.0, 1.0);
+  return mix(uColor, uHopColor, 0.5) * e * 0.55 * uTrailGain;
+}
+vec3 trailView(vec3 mv, out float mag) { mag = 1.0; return mv; }
+`;
+    const materials = [mat, fmat];
+    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 = 2;
+        u.uTrailGain.value = TRAIL_GAIN[mode] || 1;
+        trail = createCpuTrail(mode, { u, n, pos: rpos, vel, k: EXP, glsl: trailGLSL, sizePx: 0.005, spacing: 0.002, sub: 8 });
+        if (!trail)
+            return;
+        trail.object.renderOrder = 1;
+        object.add(trail.object);
+        materials.push(...trail.materials);
+    }
+    buildTrails(c.trailMode, c.trailShare);
+    let shadeTick = 0;
+    function upload() {
+        if ((shadeTick++ & 1) === 0)
+            shadeGrains();
+        else {
+            for (let i = 0; i < n; i++) {
+                if (ground[i])
+                    continue;
+                const j = i * 3;
+                rpos[j] = pos[j];
+                rpos[j + 1] = pos[j + 1] + 0.002;
+                rpos[j + 2] = pos[j + 2];
+            }
+        }
+        posAttr.needsUpdate = true;
+        shAttr.needsUpdate = true;
+        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 && pointer)
+                stepPointerField(u, pointer, camera, object, u.uSize.value, rdt, anchor, up);
+            u.uVelScale.value = 1;
+            let simD = 0;
+            stepper.run(d, (hh) => { step(hh); simD += hh; });
+            if (simD > 0) {
+                upload();
+                if (trail)
+                    trail.update(simD);
+            }
+        },
+        seek(t) { for (let s = 0; s < Math.round(t / H_STEP); s++)
+            step(H_STEP); upload(); },
+        dispose() {
+            geo.dispose();
+            mat.dispose();
+            fgeo.dispose();
+            fmat.dispose();
+            proxy.dispose();
+            if (trail)
+                trail.dispose();
+        },
+        _state: { pos, vel, ground, A, E, W, get peak() { return lastPeak; } },
+    };
+}
+/** 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: '#f1e3c2',
+    particleCount: 20000,
+    frequency: 4.63,
+    sweep: 0.4,
+    damping: 0.025,
+    amplitude: 1,
+    hopColor: '#fff3d6',
+    lightAngle: 22,
+    grainSize: 1,
+    seed: 1,
+    quality: 'medium',
+    pointerMode: 'bow',
+    pointerStrength: 1,
+    pointerRadius: 1,
+    pointerColor: '#fff4dc',
+    trailMode: 'streak',
+    trailLength: 1.6,
+    trailOpacity: 0.6,
+    trailColor: '#ffcf8a',
+    trailShare: 0.5,
+};
+/** 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.chladniSand.map((p) => p.value));
+const ChladniSandParticles = ({ 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 ChladniSandParticles;