@3driseai/3drise-viewer 0.1.19 → 0.1.21

package/dist/components/particles/FaradayPowderParticles.js

@@ -0,0 +1,783 @@
+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';
+/**
+ * Faraday Powder — Glowing powder on an invisible vibrating plate: acoustic streaming gathers it into swirling heaps at the antinodes, hotter where the plate moves most; the cursor bows, touches or taps the plate. Use for abstract, sound and fire-like scenes.
+ */
+// Faraday Powder — fine powder on an invisible vibrating plate (Faraday 1831). Particles only.
+// Movement: the same centre-clamped square plate as Chladni Sand: Chladni mode pairs
+//           phi = cos(m pi u) cos(n pi v) +/- cos(n pi u) cos(m pi v), each ringing with a Lorentzian
+//           resonance while the drive frequency glides through them. Powder too light to be thrown
+//           ballistically does the opposite of sand: acoustic streaming in the air above the plate
+//           carries it up the gradient of w^2 into the antinodes, where it gathers in little heaps
+//           that hover (height ~ w^2) and turn, neighbouring heaps in opposite senses (the streaming
+//           cells alternate with the sign of w). When the drive leaves a resonance the heaps settle
+//           and wait; the next figure pulls them somewhere else.
+// Colour:   brightness and colour from the local vibration energy A^2 w^2 the powder sits in:
+//           resting dust is a dim ember of the base colour, dust churning in a strong antinode
+//           heats toward the glow colour. Additive soft puffs, so dense heaps bloom.
+// 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 heaps migrate to a figure with a nodal line through the finger.
+//   tap    — taps along the cursor path: a bending wave rings outward and blows the powder up in
+//            an expanding ring; the broadband ring-down scatters the heaps for a moment.
+// Trails (trailMode): streak = long exposure, comet = swirl threads, echo = smoke 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 NMAX = 10; // highest mode index
+const H_STEP = 1 / 60;
+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: 1.6, comet: 1.3, echo: 4 };
+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 },
+        uGlowColor: colorUniform('#ffffff'),
+        uHover: { value: 1 },
+        uSwirl: { value: 1 },
+        uPuffSize: { 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.uGlowColor.value.set(c.glowColor);
+    u.uHover.value = c.hover;
+    u.uSwirl.value = c.swirl;
+    u.uPuffSize.value = c.puffSize;
+    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;';
+// energy ramp: dim ember of the base colour -> glow colour
+const HEAT_GLSL = /* glsl */ `
+uniform vec3 uColor, uGlowColor;
+vec3 heat(float e) {
+  float t = smoothstep(0.0, 1.6, e);
+  return mix(uColor * 0.55, mix(uColor, uGlowColor, smoothstep(0.4, 1.0, t)), smoothstep(0.0, 0.45, t)) * (0.55 + 0.8 * t);
+}
+`;
+const powderVertex = /* glsl */ `
+${BASE_U}
+${HEAT_GLSL}
+uniform float uPuffSize;
+attribute float aE;       // local vibration energy A^2 w^2 (smoothed)
+attribute float aSeed;
+varying vec3 vCol;
+varying float vA;
+void main() {
+  vec4 mv = modelViewMatrix * vec4(position * uSize, 1.0);
+  vCol = heat(aE) * uIntensity;
+  vA = uOpacity * 0.55;
+  float px = uPuffSize * uSize * uViewH * 0.011 * (0.7 + 0.6 * aSeed) / -mv.z;
+  gl_PointSize = clamp(px, 1.0, 32.0);
+  gl_Position = projectionMatrix * mv;
+}
+`;
+const powderFragment = /* 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;
+  if (a < 0.004) 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(0xfa2d, 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;
+    // ---- powder ----
+    const pos = new Float32Array(n * 3), vel = new Float32Array(n * 3);
+    const seedA = new Float32Array(n);
+    const EN = new Float32Array(n); // local vibration energy (smoothed), drives the colour
+    const EXP = new Float32Array(n); // exposure memory of speed (trails)
+    const rpos = new Float32Array(n * 3);
+    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;
+        pos[j + 1] = warm ? 0 : 0.25 + 0.3 * rng();
+        vel[j] = 0;
+        vel[j + 1] = warm ? 0 : -0.3;
+        vel[j + 2] = 0;
+    }
+    for (let i = 0; i < n; i++) {
+        sprinkle(i, true);
+        seedA[i] = rng();
+    }
+    // ---- 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;
+        }
+        // ---- powder ----
+        const relax = 1 - Math.exp(-h / 0.3);
+        const eRelax = 1 - Math.exp(-h / 0.25);
+        const hov = Math.max(u.uHover.value, 0), sw = Math.max(u.uSwirl.value, 0);
+        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 sweeps the powder aside; the bow's stick-slip puffs it up
+        const RF = 0.09 * Rr, RB = 0.3 * Rr;
+        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;
+            let en = 0;
+            if (!onPlate) {
+                // blown off the edge: settles out of the air, then is sprinkled back on
+                const dr = Math.exp(-h / 0.25);
+                vy -= 1.5 * h;
+                vx *= dr;
+                vz *= dr;
+                x += vx * h;
+                y += vy * h;
+                z += vz * h;
+                if (y < -0.6 || x > 1.35 || x < -1.35 || z > 1.35 || z < -1.35 || y > 0.9) {
+                    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 {
+                sampleW(x, z, smp);
+                const w = smp[0], gx = smp[1], gz = smp[2];
+                const aw = w < 0 ? -w : w;
+                en = amp * amp * w * w;
+                const live = amp * aw * GAIN > 0.15 ? 1 : 0;
+                // acoustic streaming: up the gradient of w^2, plus a swirl whose sense follows the sign of w
+                const k = 0.6 * amp;
+                const sg = w >= 0 ? 1 : -1;
+                let ux = k * w * gx - 0.25 * sw * sg * gz * aw * amp;
+                let uz = k * w * gz + 0.25 * sw * sg * gx * aw * amp;
+                const ul = Math.hypot(ux, uz);
+                if (ul > 0.35) {
+                    ux *= 0.35 / ul;
+                    uz *= 0.35 / ul;
+                }
+                vx += (ux * live - vx) * relax + (hr() - 0.5) * 0.25 * live * aw;
+                vz += (uz * live - vz) * relax + (hr() - 0.5) * 0.25 * live * aw;
+                const yT = live ? Math.min(0.012 * hov * amp * w * w * (0.3 + 1.4 * seedA[i]), 0.1 * Math.max(hov, 0.01)) : 0;
+                if (y > yT + 0.02)
+                    vy -= 1.5 * h;
+                else
+                    vy = (yT - y) * 2.5; // settles slowly when lifted high
+                x += vx * h;
+                y += vy * h;
+                z += vz * h;
+                if (y < 0)
+                    y = 0;
+                if (fingS > 0.02) {
+                    const dx = x - hp.x, dz = z - hp.z, d2 = dx * dx + dz * dz;
+                    if (d2 < RF * RF) {
+                        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.3 * fingS + fvx * 0.7;
+                        vz = dz / d * 0.3 * fingS + fvz * 0.7;
+                        vy = Math.max(vy, 0.08 + 0.1 * hr());
+                        en += 0.8 * fingS;
+                    }
+                }
+                if (bowS > 0.02) {
+                    const dx = x - bx, dz = z - bz, d2 = dx * dx + dz * dz;
+                    if (d2 < RB * RB && hr() < bowS * 0.3 * (1 - Math.sqrt(d2) / RB)) {
+                        vy = Math.max(vy, 0.2 + 0.3 * hr() * bowS);
+                        vx += (hr() - 0.5) * 0.3 - (ex === 0 ? Math.sign(bx) * 0.2 : 0);
+                        vz += (hr() - 0.5) * 0.3 - (ez === 0 ? Math.sign(bz) * 0.2 : 0);
+                        en += 1.2 * bowS;
+                    }
+                }
+                // tap bending waves blow the powder up
+                if (nTap) {
+                    for (let t = 0; t < MAX_TAPS; t++) {
+                        const age = TP[t * 4 + 2];
+                        if (age >= 1.4 || TP[t * 4 + 3] <= 0)
+                            continue;
+                        const dx = x - TP[t * 4], dz = z - TP[t * 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[t * 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 && hr() < 0.8) {
+                            const e = S * Math.exp(-(rf * rf) / (reach * reach));
+                            vy = Math.max(vy, 0.35 * e * (0.5 + hr()));
+                            vx += dx / r * 0.2 * e;
+                            vz += dz / r * 0.2 * e;
+                            en += 1.5 * e;
+                        }
+                    }
+                }
+            }
+            EN[i] += (en - EN[i]) * eRelax;
+            pos[j] = x;
+            pos[j + 1] = y;
+            pos[j + 2] = z;
+            vel[j] = vx;
+            vel[j + 1] = vy;
+            vel[j + 2] = vz;
+            rpos[j] = x;
+            rpos[j + 1] = y + 0.004;
+            rpos[j + 2] = z;
+            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 = '';
+    const stepper = createFixedStep(H_STEP, 4);
+    for (let s = 0; s < 200; s++)
+        step(H_STEP * 2); // the first heaps have gathered
+    // ---- geometry ----
+    const geo = new THREE.BufferGeometry();
+    const posAttr = new THREE.BufferAttribute(rpos, 3).setUsage(THREE.DynamicDrawUsage);
+    const eAttr = new THREE.BufferAttribute(EN, 1).setUsage(THREE.DynamicDrawUsage);
+    geo.setAttribute('position', posAttr);
+    geo.setAttribute('aE', eAttr);
+    geo.setAttribute('aSeed', new THREE.BufferAttribute(seedA, 1));
+    const mat = new THREE.ShaderMaterial({
+        uniforms: u, vertexShader: powderVertex, fragmentShader: powderFragment,
+        transparent: true, depthWrite: false, blending: THREE.AdditiveBlending,
+    });
+    const powder = new THREE.Points(geo, mat);
+    powder.frustumCulled = false;
+    attachViewH(powder, 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(powder, puffs, proxy.mesh);
+    const anchor = new THREE.Vector3(0, 0, 0);
+    const up = new THREE.Vector3(0, 1, 0);
+    // ---- trails: moving powder, coloured by the same heat ramp ----
+    const trailGLSL = /* glsl */ `
+${HEAT_GLSL}
+uniform float uTrailGain;
+vec3 trailShade(vec3 p, float f) {
+  float e = clamp(TRAIL_K * 2.2, 0.0, 1.0);
+  return heat(0.6 + 1.2 * e) * 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;
+        object.add(trail.object);
+        materials.push(...trail.materials);
+    }
+    buildTrails(c.trailMode, c.trailShare);
+    function upload() {
+        posAttr.needsUpdate = true;
+        eAttr.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, EN, 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: '#ff8a2a',
+    particleCount: 12000,
+    frequency: 4.63,
+    sweep: 0.3,
+    damping: 0.025,
+    amplitude: 1,
+    glowColor: '#ffe7a6',
+    hover: 1,
+    swirl: 1,
+    puffSize: 1,
+    seed: 1,
+    quality: 'medium',
+    pointerMode: 'bow',
+    pointerStrength: 1,
+    pointerRadius: 1,
+    pointerColor: '#fff4dc',
+    trailMode: 'comet',
+    trailLength: 1.6,
+    trailOpacity: 0.6,
+    trailColor: '#ff5a1e',
+    trailShare: 0.6,
+};
+/** 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.faradayPowder.map((p) => p.value));
+const FaradayPowderParticles = ({ 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 FaradayPowderParticles;