@3driseai/3drise-viewer 0.1.26 → 0.1.27

package/dist/components/particles/ShapeBurstParticles.js

@@ -0,0 +1,588 @@
+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, applyConfigMouseMove } from '../../utils/configAnimations.js';
+import { createPointerUniforms, stepPointerField, usePointerField } from '../../utils/pointerField.js';
+import { createTrailUniforms, applyTrailConfig, createCpuTrail } from '../../utils/particleTrails.js';
+import { sampleSurface } from '../../utils/particleShape.js';
+import { useObjectReady } from '../../hooks/useObjectReady.js';
+import { useConfigLiveHandle } from '../../hooks/useConfigLive.js';
+/**
+ * Shape Burst — Bursts of charged particles that spiral out in a magnetic field and land exactly on a mesh shape, white-hot cooling to two family colours, then dissolve; the cursor detonates, curls or pulls them. Use for reveals, logos and impact moments.
+ */
+// Shape Burst — a burst of charged particles that curls out and lands exactly on a mesh shape.
+// Movement: every burst fires N particles from one point. Each has a target on the shape's surface
+//           (area-weighted, stratified, so the shape fills evenly). In a vertical magnetic field with
+//           linear drag the velocity obeys v' = (-k + i q w) v in the horizontal plane (complex form),
+//           so it spirals and decays: x(t) = v0 / (k - i q w) (1 - e^{(-k + i q w) t}). Launching with
+//           v0 = (k - i q w) T makes every particle land exactly on its target T, whatever its charge:
+//           positives and negatives curl out in opposite spirals and settle into the same shape. It
+//           holds, then dissolves (a slow outward drift while it fades), and the next burst fires.
+// Colour:   exact: heat = |v| / |v0| (1 at launch, 0 at rest) takes a particle from heatColor (white-hot)
+//           to its family colour (positive = color, negative = counterColor) as it slows and lands.
+// Mouse (pointerMode, cursor on the camera-facing plane through the object):
+//   detonate — moving the cursor fires bursts at the cursor (rate limited), sized by pointerRadius.
+//   magnet   — a strong local field under the cursor: particles flying through curl tighter.
+//   gravity  — a pull toward the cursor; landed particles are held on their shape by a spring, so the
+//              shape stretches toward the cursor and snaps back when it leaves.
+// Trails (trailMode): streak = motion blur, comet = spiral tails, echo = embers.
+//
+// Generated from the approved lab module (particle lab, shapes batch). Sim units = object-local / size.
+// config.shape is a mesh-builder geometry config ({ type, ...params }); utils/particleShape builds it with
+// the core mesh builders (createMeshByType) and reads it as a surface.
+// ---------------------------------------------------------------------------------------------
+// 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;
+    };
+}
+/** 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);
+}
+/** Shared GLSL for heads (a white-hot core in a coloured glow). */
+const HEAD_FRAG = /* 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 core = exp(-r2 * 40.0);
+  float glow = exp(-r2 * 8.0) * 0.5 + exp(-r2 * 2.5) * 0.1;
+  float a = clamp((core + glow) * (1.0 - r2) * vA, 0.0, 1.0);
+  if (a < 0.003) discard;
+  vec3 c = vCol / max(max(vCol.r, max(vCol.g, vCol.b)), 1.0);
+  gl_FragColor = vec4(mix(c, vec3(1.0), core * 0.9), a);
+}
+`;
+const POINTER_MODES = ['detonate', 'magnet', 'gravity'];
+const H_STEP = 1 / 120;
+const W_PER_FIELD = 4.2; // cyclotron rate (rad / s) per unit field
+const TRAIL_LOOK = { streak: 0.12, comet: 1, echo: 1 };
+const TRAIL_ALPHA = { streak: 1.4, comet: 1.6, echo: 2.4 };
+const BOUNDS = { center: [0, 0, 0], radius: 1.3 };
+const FADE = 1.2; // seconds of dissolve
+const INK_EVERY = 1; // particles that draw lines (1 = all)
+const INK_SPACING = 0.006;
+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 },
+        uInterval: { value: 2.8 },
+        uFormSpeed: { value: 2.4 },
+        uFieldStrength: { value: 1 },
+        uHoldTime: { value: 1.2 },
+        uDissolve: { value: 0.3 },
+        uCounterColor: colorUniform('#ffffff'),
+        uHeatColor: colorUniform('#ffffff'),
+        uHeadSize: { value: 1 },
+        uInkTime: { value: 0 },
+        uPointerMode: { value: 0 },
+        uPointerStrength: { value: 1 },
+        uPointerRadius: { value: 1 },
+        uPointerColor: colorUniform('#ffffff'),
+        ...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.uInterval.value = c.interval;
+    u.uFormSpeed.value = c.formSpeed;
+    u.uFieldStrength.value = c.fieldStrength;
+    u.uHoldTime.value = c.holdTime;
+    u.uDissolve.value = c.dissolve;
+    u.uCounterColor.value.set(c.counterColor);
+    u.uHeatColor.value.set(c.heatColor);
+    u.uHeadSize.value = c.headSize;
+    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);
+}
+// code = family (0/1) + 2 x heat (0..63) + 128 x brightness (0..31) + 4096 x cursor glow (0..7)
+const HEAT_GLSL = /* glsl */ `
+uniform vec3 uColor, uCounterColor, uHeatColor, uPointerColor;
+vec3 burstLight(float code, out float bri) {
+  float gl = floor(code / 4096.0); code -= gl * 4096.0;
+  float b = floor(code / 128.0); code -= b * 128.0;
+  float ht = floor(code / 2.0);
+  float fam = code - ht * 2.0;
+  bri = b / 31.0;
+  float heat = ht / 63.0;
+  vec3 c = mix(fam < 0.5 ? uColor : uCounterColor, uHeatColor, smoothstep(0.55, 1.0, heat));
+  return mix(c, uPointerColor, 0.6 * gl / 7.0) * (0.9 + 0.8 * heat);
+}
+`;
+const headVertex = /* glsl */ `
+uniform float uSize, uViewH, uIntensity, uOpacity, uHeadSize;
+${HEAT_GLSL}
+attribute float aCode;
+varying vec3 vCol;
+varying float vA;
+void main() {
+  vec4 mv = modelViewMatrix * vec4(position * uSize, 1.0);
+  float bri;
+  vCol = burstLight(aCode, bri) * uIntensity;
+  vA = uOpacity * bri;
+  gl_PointSize = clamp(uHeadSize * uSize * uViewH * 0.016 / -mv.z, 1.5, 28.0) * step(0.01, bri);
+  gl_Position = projectionMatrix * mv;
+}
+`;
+const inkVertex = /* glsl */ `
+uniform float uSize, uViewH, uIntensity, uOpacity, uInkTime;
+${HEAT_GLSL}
+attribute vec2 aI;       // colour code at deposit, time the line dies
+varying vec3 vCol;
+varying float vA;
+void main() {
+  vec4 mv = modelViewMatrix * vec4(position * uSize, 1.0);
+  float bri;
+  vCol = burstLight(aI.x, bri) * uIntensity;
+  float left = aI.y - uInkTime;
+  vA = aI.y < 0.0 ? 0.0 : uOpacity * 0.8 * clamp(left / ${FADE.toFixed(2)}, 0.0, 1.0);
+  gl_PointSize = clamp(uSize * uViewH * 0.0055 / -mv.z, 1.0, 8.0) * step(0.004, vA);
+  gl_Position = projectionMatrix * mv;
+}
+`;
+const inkFragment = /* 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 * 4.0) * (1.0 - r2) * vA;
+  if (a < 0.002) discard;
+  gl_FragColor = vec4(vCol, a);
+}
+`;
+function build(u, c, size) {
+    const q = qualityScale(c.quality);
+    const nb = Math.max(20, Math.round(c.particleCount * q));
+    const SLOTS = 3; // bursts that can be alive at once
+    const N = nb * SLOTS;
+    const rng = mulberry32(seedMix(0xb125, c.seed));
+    // targets: several stratified sets over the surface, a fresh one for each burst
+    const SETS = 4;
+    const targets = [];
+    for (let s = 0; s < SETS; s++)
+        targets.push(sampleSurface(c.shape, nb, rng));
+    let ext = 0;
+    for (let k = 0; k < targets[0].length; k += 3)
+        ext = Math.max(ext, Math.hypot(targets[0][k], targets[0][k + 1], targets[0][k + 2]));
+    const bR = Math.max(BOUNDS.radius, ext * 1.35); // bounds grow with the shape (and its dissolve)
+    const x = new Float32Array(N * 3), v = new Float32Array(N * 3), T = new Float32Array(N * 3), O = new Float32Array(N * 3);
+    const v0 = new Float32Array(N), age = new Float32Array(N), sc = new Float32Array(N);
+    const fam = new Uint8Array(N), alive = new Uint8Array(N);
+    const code = new Float32Array(N), glow = new Float32Array(N);
+    // ink: the spiral path every particle draws, living as long as its burst
+    const NI = Math.max(20000, Math.round(nb * SLOTS * 90));
+    const ip = new Float32Array(NI * 3), ia = new Float32Array(NI * 2); // code at deposit, time of death
+    for (let k = 0; k < NI; k++)
+        ia[k * 2 + 1] = -1;
+    let iHead = 0, simTime = 0;
+    const inkAcc = new Float32Array(N);
+    let trail = null;
+    let burstNo = 0, clock = 0, detClock = 0;
+    const last = new THREE.Vector3(1e9, 0, 0), P = new THREE.Vector3(), axis = new THREE.Vector3(0, 0, 1);
+    function fire(ox, oy, oz, scale) {
+        const set = targets[burstNo % SETS];
+        const base = (burstNo % SLOTS) * nb;
+        burstNo++;
+        const k = Math.max(u.uFormSpeed.value, 0.2), w = W_PER_FIELD * u.uFieldStrength.value;
+        for (let i = 0; i < nb; i++) {
+            const p = base + i, j = p * 3;
+            const f = i % 2, qs = f ? -1 : 1;
+            const tx = set[i * 3] * scale, ty = set[i * 3 + 1] * scale, tz = set[i * 3 + 2] * scale;
+            T[j] = ox + tx;
+            T[j + 1] = oy + ty;
+            T[j + 2] = oz + tz;
+            O[j] = ox;
+            O[j + 1] = oy;
+            O[j + 2] = oz;
+            x[j] = ox;
+            x[j + 1] = oy;
+            x[j + 2] = oz;
+            // v0 = (k - i q w) T  (complex in x + i z), so the drag-and-field spiral ends exactly at T
+            v[j] = k * tx + qs * w * tz;
+            v[j + 1] = k * ty;
+            v[j + 2] = k * tz - qs * w * tx;
+            v0[p] = Math.hypot(v[j], v[j + 1], v[j + 2]) + 1e-6;
+            age[p] = 0;
+            fam[p] = f;
+            alive[p] = 1;
+            sc[p] = scale;
+            inkAcc[p] = 0;
+            if (trail)
+                trail.reset(p);
+        }
+    }
+    function step(dt) {
+        simTime += dt;
+        const k = Math.max(u.uFormSpeed.value, 0.2), w0 = W_PER_FIELD * u.uFieldStrength.value;
+        const hold = u.uHoldTime.value, dis = u.uDissolve.value;
+        const formT = 3.2 / k;
+        const life = formT + hold + FADE;
+        const mode = u.uPointerMode.value;
+        const S = u.uPointerStrength.value * u.uPointerActive.value;
+        const Rp = 0.35 * u.uPointerRadius.value;
+        P.copy(u.uPointer.value);
+        // the burst clock
+        clock += dt;
+        if (clock >= Math.max(u.uInterval.value, life * 0.34)) {
+            clock = 0;
+            fire(0, 0, 0, 1);
+        }
+        // detonations at the cursor
+        detClock += dt;
+        if (mode === 0 && S > 0.3 && detClock > 0.45 && P.distanceTo(last) > 0.15) {
+            detClock = 0;
+            last.copy(P);
+            fire(P.x, P.y, P.z, 0.35 * u.uPointerRadius.value * Math.min(u.uPointerStrength.value, 2));
+            clock = Math.min(clock, u.uInterval.value * 0.5);
+        }
+        const decay = Math.exp(-k * dt);
+        for (let p = 0; p < N; p++) {
+            if (!alive[p])
+                continue;
+            const j = p * 3, i2 = p;
+            const a = (age[p] += dt);
+            if (a > life) {
+                alive[p] = 0;
+                code[p] = 0;
+                v[j] = v[j + 1] = v[j + 2] = 0;
+                continue;
+            }
+            let w = w0 * (fam[p] ? -1 : 1);
+            let gx = 0, gy = 0, gz = 0, gl = 0;
+            if (S > 0.001 && mode > 0) {
+                let ex = x[j] - P.x, ey = x[j + 1] - P.y, ez = x[j + 2] - P.z;
+                const al = ex * axis.x + ey * axis.y + ez * axis.z;
+                ex -= axis.x * al;
+                ey -= axis.y * al;
+                ez -= axis.z * al;
+                const d2 = ex * ex + ey * ey + ez * ez;
+                if (d2 < 9 * Rp * Rp) {
+                    const g = Math.exp(-d2 / (Rp * Rp));
+                    gl = g;
+                    if (mode === 1)
+                        w += (fam[p] ? -1 : 1) * 14 * S * g; // local field
+                    else {
+                        const f = 6 * S * g;
+                        gx = -ex * f;
+                        gy = -ey * f;
+                        gz = -ez * f;
+                    } // pull
+                }
+            }
+            glow[p] += (gl - glow[p]) * Math.min(1, dt * 8);
+            // exact drag + field step: rotate the horizontal velocity by w dt, decay by e^{-k dt}
+            const ca = Math.cos(w * dt), sa = Math.sin(w * dt);
+            const vx = v[j] * ca + v[j + 2] * sa, vz = -v[j] * sa + v[j + 2] * ca;
+            v[j] = vx * decay;
+            v[j + 1] *= decay;
+            v[j + 2] = vz * decay;
+            // after landing a spring holds the shape (so a pulled shape snaps back); the dissolve drifts it out
+            if (a > formT) { // critically damped: no wobble
+                const ks = 36, kd = 2 * Math.sqrt(ks);
+                v[j] += (-(x[j] - T[j]) * ks - v[j] * kd) * dt;
+                v[j + 1] += (-(x[j + 1] - T[j + 1]) * ks - v[j + 1] * kd) * dt;
+                v[j + 2] += (-(x[j + 2] - T[j + 2]) * ks - v[j + 2] * kd) * dt;
+            }
+            if (a > formT + hold && dis > 0) {
+                const o = dis * 0.6 * dt; // the shape swells out from its origin as it fades
+                T[j] += (T[j] - O[j]) * o;
+                T[j + 1] += (T[j + 1] - O[j + 1]) * o;
+                T[j + 2] += (T[j + 2] - O[j + 2]) * o;
+            }
+            v[j] += gx * dt;
+            v[j + 1] += gy * dt;
+            v[j + 2] += gz * dt;
+            const px = x[j], py = x[j + 1], pz = x[j + 2];
+            x[j] += v[j] * dt;
+            x[j + 1] += v[j + 1] * dt;
+            x[j + 2] += v[j + 2] * dt;
+            // light: heat from speed, brightness from the life cycle (quick flash in, fade out in the dissolve)
+            const heat = Math.min(Math.hypot(v[j], v[j + 1], v[j + 2]) / v0[p], 1);
+            const fin = Math.min(a / 0.06, 1), fout = a > formT + hold ? Math.max(1 - (a - formT - hold) / FADE, 0) : 1;
+            const bri = fin * fout * fout;
+            code[p] = fam[p] + 2 * Math.round(heat * 63) + 128 * Math.round(bri * 31) + 4096 * Math.round(Math.min(glow[p], 1) * 7);
+            // lay ink along the flight (a line that lives until the burst has faded)
+            if (i2 % INK_EVERY === 0) {
+                const seg = Math.hypot(x[j] - px, x[j + 1] - py, x[j + 2] - pz);
+                inkAcc[p] += seg;
+                const sp = INK_SPACING;
+                while (inkAcc[p] >= sp) {
+                    inkAcc[p] -= sp;
+                    const t = seg > 1e-6 ? 1 - inkAcc[p] / seg : 1;
+                    const q2 = iHead;
+                    iHead = (iHead + 1) % NI;
+                    ip[q2 * 3] = px + (x[j] - px) * t;
+                    ip[q2 * 3 + 1] = py + (x[j + 1] - py) * t;
+                    ip[q2 * 3 + 2] = pz + (x[j + 2] - pz) * t;
+                    ia[q2 * 2] = fam[p] + 2 * Math.round(heat * 63) + 128 * 31;
+                    ia[q2 * 2 + 1] = simTime + (life - a);
+                }
+            }
+        }
+    }
+    const hgeo = new THREE.BufferGeometry();
+    const xAttr = new THREE.BufferAttribute(x, 3).setUsage(THREE.DynamicDrawUsage);
+    const cAttr = new THREE.BufferAttribute(code, 1).setUsage(THREE.DynamicDrawUsage);
+    hgeo.setAttribute('position', xAttr);
+    hgeo.setAttribute('aCode', cAttr);
+    const hmat = new THREE.ShaderMaterial({
+        uniforms: u, vertexShader: headVertex, fragmentShader: HEAD_FRAG,
+        transparent: true, depthWrite: false, blending: THREE.AdditiveBlending,
+    });
+    const pts = new THREE.Points(hgeo, hmat);
+    pts.frustumCulled = false;
+    pts.renderOrder = 3;
+    attachViewH(pts, u);
+    const igeo = new THREE.BufferGeometry();
+    const ipAttr = new THREE.BufferAttribute(ip, 3).setUsage(THREE.DynamicDrawUsage);
+    const iaAttr = new THREE.BufferAttribute(ia, 2).setUsage(THREE.DynamicDrawUsage);
+    igeo.setAttribute('position', ipAttr);
+    igeo.setAttribute('aI', iaAttr);
+    const imat = new THREE.ShaderMaterial({
+        uniforms: u, vertexShader: inkVertex, fragmentShader: inkFragment,
+        transparent: true, depthWrite: false, blending: THREE.AdditiveBlending,
+    });
+    const ink = new THREE.Points(igeo, imat);
+    ink.frustumCulled = false;
+    ink.renderOrder = 1;
+    const object = new THREE.Group();
+    const proxy = createPickProxy(BOUNDS.center, bR);
+    object.add(ink, pts, proxy.mesh);
+    const trailGLSL = /* glsl */ `
+${HEAT_GLSL}
+vec3 trailShade(vec3 p, float f) {
+  float bri;
+  vec3 c = burstLight(TRAIL_K, bri);
+  c /= max(max(c.r, max(c.g, c.b)), 1.0);                 // keep <= 1 so the tail colour shows
+  return mix(c, uTrailColor, smoothstep(0.0, 0.6, f)) * bri;
+}
+vec3 trailView(vec3 mv, out float mag) { mag = 1.0; return mv; }
+`;
+    let trailKey = '', look = 1;
+    const materials = [hmat, imat];
+    function buildTrails(mode, share) {
+        look = TRAIL_LOOK[mode] || 1;
+        const key = mode + ':' + share;
+        if (key === trailKey)
+            return;
+        trailKey = key;
+        if (trail) {
+            object.remove(trail.object);
+            trail.dispose();
+            trail = null;
+        }
+        materials.length = 2;
+        trail = createCpuTrail(mode, { u, n: N, pos: x, vel: v, k: code, glsl: trailGLSL, sizePx: 0.008, spacing: 0.0015, sub: 10, alpha: TRAIL_ALPHA[mode] });
+        if (!trail)
+            return;
+        trail.object.renderOrder = 2;
+        object.add(trail.object);
+        materials.push(...trail.materials);
+    }
+    buildTrails(c.trailMode, c.trailShare);
+    const stepper = createFixedStep(H_STEP, 8);
+    fire(0, 0, 0, 1);
+    for (let s = 0; s < 0.5 / H_STEP; s++)
+        step(H_STEP); // open mid-burst: the spirals are on screen
+    const invWorld = new THREE.Matrix4();
+    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, bR, u.uSize.value))
+                return;
+            const d = rdt * u.uSpeed.value;
+            u.uTime.value += d;
+            if (camera) {
+                camera.getWorldDirection(axis);
+                axis.transformDirection(invWorld.copy(object.matrixWorld).invert()).normalize();
+                if (pointer)
+                    stepPointerField(u, pointer, camera, object, u.uSize.value, rdt);
+            }
+            u.uVelScale.value = look;
+            let simD = 0;
+            stepper.run(d, (hh) => { step(hh); simD += hh; });
+            if (simD > 0) {
+                xAttr.needsUpdate = true;
+                cAttr.needsUpdate = true;
+                ipAttr.needsUpdate = true;
+                iaAttr.needsUpdate = true;
+                u.uInkTime.value = simTime;
+                if (trail)
+                    trail.update(simD / look);
+            }
+        },
+        seek(tt) { for (let s = 0; s < Math.round(tt / H_STEP); s++)
+            step(H_STEP); xAttr.needsUpdate = true; cAttr.needsUpdate = true; },
+        dispose() { hgeo.dispose(); hmat.dispose(); igeo.dispose(); imat.dispose(); proxy.dispose(); if (trail)
+            trail.dispose(); },
+        _state: { x, code, alive },
+    };
+}
+/** 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: '#45d1ff',
+    particleCount: 180,
+    shape: { type: 'icosahedron', radius: 0.5, detail: 0 },
+    interval: 2.8,
+    formSpeed: 2.4,
+    fieldStrength: 1,
+    holdTime: 1.2,
+    dissolve: 0.3,
+    counterColor: '#ff5aa8',
+    heatColor: '#fff6e0',
+    headSize: 1.4,
+    seed: 1,
+    quality: 'medium',
+    pointerMode: 'detonate',
+    pointerStrength: 1,
+    pointerRadius: 1,
+    pointerColor: '#ffffff',
+    trailMode: 'comet',
+    trailLength: 0.4,
+    trailOpacity: 0.8,
+    trailColor: '#6a5cff',
+    trailShare: 0.5,
+};
+/** Knobs that rebuild the simulation: they change on commit, never through the live path. */
+const STRUCTURAL = ['particleCount', 'shape', 'seed', 'quality'];
+/** Knobs an animation (or mouse move) may drive per frame — generated from applyConfig. */
+const ANIMATABLE = new Set(GENERATIVE_PARTICLES_ANIMATABLE.shapeBurst.map((p) => p.value));
+const ShapeBurstParticles = ({ id, size, config, animations, mouseMove, onObjectReady, onObjectDispose }) => {
+    const rootRef = useRef(null);
+    useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
+    const s = size > 0 ? size : 1;
+    const cfg = useMemo(() => ({ ...DEFAULTS, ...config }), [config]);
+    // the shape is an object: rebuild on a change of its content, not of its identity
+    const shapeKey = JSON.stringify(cfg.shape);
+    // 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, shapeKey]);
+    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);
+        // Keyframes first, pointer on top: a knob bound to both follows the cursor.
+        const pointerBound = !!mouseMove?.enabled && !!mouseMove.properties?.length;
+        if (keyframes?.length || pointerBound) {
+            applyConfigKeyframeAnimations(keyframes, animFrom.current, cfg, animOverride.current, performance.now() - animStart.current, ANIMATABLE);
+            if (pointerBound)
+                applyConfigMouseMove(mouseMove.properties, cfg, animOverride.current, state.pointer, ANIMATABLE);
+            push(live.current);
+        }
+    });
+    return (_jsx("group", { ref: rootRef, children: _jsx("primitive", { object: instance.object }) }));
+};
+export default ShapeBurstParticles;

package/dist/components/particles/ShapeFlowParticles.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import type { ObjectAnimations, ShapeFlowParticlesConfig, MouseMoveDomain } from '@3driseai/3drise-core';
+import type { ObjectReadyProps } from '../../types/objectReady';
+export interface ShapeFlowParticlesProps extends ObjectReadyProps {
+    /** Pointer bindings for this object's config knobs (mouseMove.particles). */
+    mouseMove?: MouseMoveDomain;
+    /** Scene object id: the controller finds the live-edit handle by it. */
+    id?: string;
+    /** World size of the object (units); the object's transform scales it further. */
+    size: number;
+    config: ShapeFlowParticlesConfig;
+    /** Per-domain keyframes; the `particles` domain drives this object's config knobs. */
+    animations?: ObjectAnimations;
+}
+declare const ShapeFlowParticles: React.FC<ShapeFlowParticlesProps>;
+export default ShapeFlowParticles;
+//# sourceMappingURL=ShapeFlowParticles.d.ts.map

package/dist/components/particles/ShapeFlowParticles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShapeFlowParticles.d.ts","sourceRoot":"","sources":["../../../src/components/particles/ShapeFlowParticles.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmE,MAAM,OAAO,CAAC;AAIxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAOzG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC7D,6EAA6E;IAC7E,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,wEAAwE;IACxE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,wBAAwB,CAAC;IACjC,sFAAsF;IACtF,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACjC;AAumBD,QAAA,MAAM,kBAAkB,EAAE,KAAK,CAAC,EAAE,CAAC,uBAAuB,CAuDzD,CAAC;AAEF,eAAe,kBAAkB,CAAC"}