@3driseai/3drise-viewer 0.1.26 → 0.1.27

package/dist/components/particles/MagneticBottleParticles.js

@@ -0,0 +1,618 @@
+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 { SHAPE_SCALE, shapeGeometry, radialMap } from '../../utils/particleShape.js';
+import { useObjectReady } from '../../hooks/useObjectReady.js';
+import { useConfigLiveHandle } from '../../hooks/useConfigLive.js';
+/**
+ * Magnetic Bottle — Charged particles woven over any mesh shape: counter-rotating constant-bearing spirals that tighten into glowing tips, in two exact family colours; the cursor pinches, drifts or heats the orbits. Use for sci-fi and tech scenes.
+ */
+// Magnetic Bottle — charged particles woven into a shape by a magnetic field.
+// Movement: the chosen mesh is read as a flux surface: a ray from the axis at every angle and height
+//           gives its radius R(theta, h). Each particle orbits the axis on that surface. Magnetic flux
+//           through its orbit is conserved, so B ~ 1 / Rm(h)^2 (Rm = mean radius at that height), and
+//           the magnetic moment mu = v_perp^2 / B is an adiabatic invariant: where the surface narrows the
+//           field grows, v_perp grows as 1 / Rm, the orbit spins faster (omega ~ 1 / Rm^2) and v_par =
+//           sqrt(v^2 - v_perp^2) falls to zero at the mirror point, where the particle turns back.
+//           Positive and negative charges gyrate in opposite senses, so the two families cross into a
+//           woven lattice; each pitch angle mirrors at its own height, so the weave fills the shape.
+//           A cone gives the inward vortex (tight, fast, bright near the tip); polyhedra give pyramids.
+// Colour:   exact per family: positive = color, negative = counterColor. The pitch sets the light:
+//           sin(alpha) = v_perp / v -> brightness and whitening, so mirror points glow as bright rings.
+//           Every particle leaves a fading ink line (the woven shape) and a white-hot head.
+// Mouse (pointerMode, cursor on the camera-facing plane through the object):
+//   pinch — a magnet: the field grows under the cursor, the surface dents in and particles that reach
+//           the dent mirror off it.
+//   drift — an electric field: E x B drift carries every particle the same way round the cursor
+//           (charge independent), so the weave shears into a local swirl.
+//   heat  — an RF antenna at the cyclotron resonance: passing particles gain v_perp, flare in the
+//           heat colour and mirror earlier; collisions relax them back over seconds.
+// Trails (trailMode): streak = motion blur, comet = gyro tails, echo = afterglow, in family colour.
+//
+// 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);
+}
+const POINTER_MODES = ['pinch', 'drift', 'heat'];
+const NTH = 96, NHT = 96; // radial map resolution (angle x height)
+const H_STEP = 1 / 120;
+const V0 = 0.9; // speed along the orbit (units / s) at speed 1
+const TRAIL_LOOK = { streak: 0.25, comet: 1, echo: 1 };
+const TRAIL_ALPHA = { streak: 1.6, comet: 2, echo: 3 };
+const BOUNDS = { center: [0, 0, 0], radius: 1.25 };
+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 },
+        uWindings: { value: 1.6 },
+        uPitchSpread: { value: 0.6 },
+        uLineLife: { value: 6 },
+        uLineDensity: { value: 1 },
+        uCounterColor: colorUniform('#ffffff'),
+        uGlow: { value: 1 },
+        uPointerMode: { value: 0 },
+        uPointerStrength: { value: 1 },
+        uPointerRadius: { value: 1 },
+        uPointerColor: colorUniform('#ffffff'),
+        uTrailGain: { value: 1 },
+        uCamLocal: { value: new THREE.Vector3(0, 0, 3) },
+        ...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.uWindings.value = c.windings;
+    u.uPitchSpread.value = c.pitchSpread;
+    u.uLineLife.value = c.lineLife;
+    u.uLineDensity.value = c.lineDensity;
+    u.uCounterColor.value.set(c.counterColor);
+    u.uGlow.value = c.glow;
+    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);
+}
+// Light code shared by lines, heads and trails: c = family (0 / 1) + 2 x pitch (0..1) + 4 x heat (0..1)
+// packed as  code = family + 2 * round(pitch * 63) + 128 * round(heat * 31)
+const LIGHT_GLSL = /* glsl */ `
+uniform vec3 uColor, uCounterColor, uPointerColor;
+uniform float uGlow;
+vec3 familyLight(float code, out float pitch) {
+  float heat = floor(code / 128.0);
+  float rest = code - heat * 128.0;
+  float pq = floor(rest / 2.0);
+  float fam = rest - pq * 2.0;
+  pitch = pq / 63.0;
+  heat /= 31.0;
+  vec3 c = fam < 0.5 ? uColor : uCounterColor;
+  float s4 = pitch * pitch * pitch * pitch;
+  // tight orbits (sin(alpha) -> 1, near the mirror point) whiten and brighten into rings
+  vec3 col = mix(c, vec3(1.0), 0.3 * s4 * s4) * (0.55 + 0.6 * pitch + 0.9 * uGlow * s4 * s4);
+  return mix(col, uPointerColor * 1.6, heat);
+}
+`;
+const lineVertex = /* glsl */ `
+uniform float uSize, uViewH, uIntensity, uOpacity;
+uniform vec3 uCamLocal;
+${LIGHT_GLSL}
+attribute vec2 aL;      // light code, age fraction (-1 = empty)
+varying vec3 vCol;
+varying float vA;
+void main() {
+  vec4 mv = modelViewMatrix * vec4(position * uSize, 1.0);
+  float pitch;
+  vCol = familyLight(aL.x, pitch) * uIntensity;
+  float f = aL.y;
+  float fade = f < 0.0 ? 0.0 : smoothstep(0.0, 0.02, f) * (1.0 - smoothstep(0.45, 1.0, f));
+  // the far side of the surface is dimmer, so the front weave reads cleanly over the back one
+  vec3 radial = normalize(vec3(position.x, 0.0, position.z) + 1e-5);
+  float facing = dot(radial, normalize(uCamLocal - position));
+  vA = uOpacity * fade * 0.8 * mix(0.3, 1.0, smoothstep(-0.35, 0.35, facing));
+  gl_PointSize = clamp(uSize * uViewH * 0.005 * (0.8 + 0.5 * pitch) / -mv.z, 1.0, 12.0) * step(0.004, vA);
+  gl_Position = projectionMatrix * mv;
+}
+`;
+const lineFragment = /* 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 * 5.0) + 0.15 * exp(-r2 * 1.8)) * (1.0 - r2) * vA;
+  if (a < 0.002) discard;
+  gl_FragColor = vec4(vCol, a);
+}
+`;
+const headVertex = /* glsl */ `
+uniform float uSize, uViewH, uIntensity, uOpacity;
+${LIGHT_GLSL}
+attribute float aCode;
+varying vec3 vCol;
+varying float vA;
+void main() {
+  vec4 mv = modelViewMatrix * vec4(position * uSize, 1.0);
+  float pitch;
+  vCol = familyLight(aCode, pitch) * uIntensity;
+  vA = uOpacity * (0.6 + 0.4 * uGlow);
+  gl_PointSize = clamp(uSize * uViewH * 0.03 / -mv.z, 2.0, 36.0);
+  gl_Position = projectionMatrix * mv;
+}
+`;
+const headFragment = /* 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 * 45.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;
+  gl_FragColor = vec4(mix(normalize(vCol + 1e-4) * 1.2, vec3(1.0), core), a);
+}
+`;
+function build(u, c, size) {
+    const q = qualityScale(c.quality);
+    const n = Math.max(2, Math.round(c.particleCount));
+    const rng = mulberry32(seedMix(0xb077, c.seed));
+    // ---- the shape as a flux surface, normalised into the unit box round the origin ----
+    const geom = shapeGeometry(c.shape);
+    const map = radialMap(geom, NTH, NHT);
+    geom.dispose();
+    const R = map.R;
+    let rMax = 0;
+    for (let k = 0; k < R.length; k++)
+        rMax = Math.max(rMax, R[k]);
+    const hSpan = map.ymax - map.ymin;
+    const sc = SHAPE_SCALE; // real size: the shape's parameters set the object's size
+    for (let k = 0; k < R.length; k++)
+        R[k] *= sc;
+    const Y0 = -hSpan * sc / 2, Y1 = hSpan * sc / 2;
+    const bR = Math.max(BOUNDS.radius, Math.hypot(rMax, hSpan * sc / 2) * 1.08); // selection bounds grow with the shape
+    // mean radius per height (sets the field B ~ 1 / Rm^2), and where the surface is widest
+    const Rm = new Float32Array(NHT);
+    let jWide = 0;
+    for (let j = 0; j < NHT; j++) {
+        let s = 0;
+        for (let i = 0; i < NTH; i++)
+            s += R[j * NTH + i];
+        Rm[j] = s / NTH;
+        if (Rm[j] > Rm[jWide])
+            jWide = j;
+    }
+    const RW = Rm[jWide];
+    const hOf = (j) => Y0 + ((j + 0.5) / NHT) * (Y1 - Y0);
+    function rmAt(h) {
+        let f = (h - Y0) / (Y1 - Y0) * NHT - 0.5;
+        if (f < 0)
+            f = 0;
+        else if (f > NHT - 1.001)
+            f = NHT - 1.001;
+        const j = f | 0, t = f - j;
+        return Rm[j] + (Rm[j + 1] - Rm[j]) * t;
+    }
+    function rAt(th, h) {
+        let f = (h - Y0) / (Y1 - Y0) * NHT - 0.5;
+        if (f < 0)
+            f = 0;
+        else if (f > NHT - 1.001)
+            f = NHT - 1.001;
+        let g = (th / (Math.PI * 2)) * NTH;
+        g -= Math.floor(g / NTH) * NTH;
+        const j = f | 0, t = f - j, i = g | 0, s = g - i, i1 = (i + 1) % NTH;
+        const a = R[j * NTH + i] + (R[j * NTH + i1] - R[j * NTH + i]) * s;
+        const b = R[(j + 1) * NTH + i] + (R[(j + 1) * NTH + i1] - R[(j + 1) * NTH + i]) * s;
+        return a + (b - a) * t;
+    }
+    // ---- particles: bearing angle, charge family (handedness), phase, direction ----
+    const h = new Float32Array(n), th = new Float32Array(n), dir = new Int8Array(n), fam = new Uint8Array(n);
+    const psi = new Float32Array(n), heat = new Float32Array(n);
+    const hx = new Float32Array(n * 3), hv = new Float32Array(n * 3), code = new Float32Array(n), hK = new Float32Array(n);
+    const acc = new Float32Array(n);
+    const half = Math.ceil(n / 2);
+    for (let i = 0; i < n; i++) {
+        fam[i] = i % 2;
+        const k = i >> 1;
+        psi[i] = (k / half - 0.5) * 2; // -1..1, scaled by pitchSpread each step
+        h[i] = Y0 + (Y1 - Y0) * ((k * 0.618034) % 1); // golden-ratio spread along the height
+        th[i] = (k / half) * Math.PI * 2 + fam[i] * Math.PI / half;
+        dir[i] = k % 2 === 0 ? 1 : -1;
+    }
+    // meridian slope dRm/dh for arc length along the surface
+    const dRm = new Float32Array(NHT);
+    for (let j = 0; j < NHT; j++) {
+        const a = Rm[Math.max(j - 1, 0)], b = Rm[Math.min(j + 1, NHT - 1)];
+        dRm[j] = (b - a) / (((Math.min(j + 1, NHT - 1) - Math.max(j - 1, 0)) / NHT) * (Y1 - Y0));
+    }
+    function slopeAt(hh) {
+        let f = (hh - Y0) / (Y1 - Y0) * NHT - 0.5;
+        if (f < 0)
+            f = 0;
+        else if (f > NHT - 1.001)
+            f = NHT - 1.001;
+        const j = f | 0, t = f - j;
+        return dRm[j] + (dRm[j + 1] - dRm[j]) * t;
+    }
+    // ---- line ink: a ring of points the particles lay down ----
+    const NL = Math.max(8000, Math.round(60000 * q));
+    const lp = new Float32Array(NL * 3), la = new Float32Array(NL * 2), lb = new Float32Array(NL); // lb = birth time
+    for (let k = 0; k < NL; k++)
+        la[k * 2 + 1] = -1;
+    let lHead = 0;
+    let time = 0;
+    const P = new THREE.Vector3();
+    let trail = null;
+    function pack(f, pitch, ht) {
+        return f + 2 * Math.round(Math.min(Math.max(pitch, 0), 1) * 63) + 128 * Math.round(Math.min(Math.max(ht, 0), 1) * 31);
+    }
+    function step(dt) {
+        time += dt;
+        // bearing of the loxodromes: tan(psi) = R dtheta / dm; windings sets it, pitchSpread fans it per particle
+        const base = Math.atan(u.uWindings.value * 2.2);
+        const spread = 0.35 * u.uPitchSpread.value;
+        const mode = u.uPointerMode.value;
+        const S = u.uPointerStrength.value * u.uPointerActive.value;
+        const Rp = 0.28 * u.uPointerRadius.value;
+        P.copy(u.uPointer.value);
+        const spacing = 0.0055 / Math.max(u.uLineDensity.value, 0.05);
+        const life = Math.max(u.uLineLife.value, 0.1);
+        const cool = Math.exp(-dt / 1.6);
+        for (let i = 0; i < n; i++) {
+            const j = i * 3;
+            const px = hx[j], py = hx[j + 1], pz = hx[j + 2];
+            // cursor proximity (from the last position)
+            let g = 0;
+            if (S > 0.001) {
+                const ex = px - P.x, ey = py - P.y, ez = pz - P.z;
+                const d2 = ex * ex + ey * ey + ez * ez;
+                if (d2 < 9 * Rp * Rp)
+                    g = Math.exp(-d2 / (Rp * Rp));
+            }
+            if (mode === 2 && g > 0.02)
+                heat[i] = Math.min(heat[i] + 3 * S * g * dt, 1); // cyclotron heating
+            heat[i] *= cool;
+            const pinch = mode === 0 ? 1 - 0.5 * S * g : 1; // a magnet dents the surface
+            const rm = Math.max(rmAt(h[i]) * pinch, 0.012);
+            // heated or pinched orbits wind tighter (a stronger local field)
+            const b = Math.min(base + spread * psi[i] + 0.5 * heat[i] + (1 - pinch) * 0.9, 1.52);
+            const V = V0 * (1 + 0.6 * heat[i]);
+            const sl = slopeAt(h[i]);
+            let nh = h[i] + dir[i] * V * Math.cos(b) / Math.sqrt(1 + sl * sl) * dt;
+            if (nh < Y0 + 0.004) {
+                nh = Y0 + 0.004;
+                dir[i] = 1;
+            } // the ends turn the orbit back
+            if (nh > Y1 - 0.004) {
+                nh = Y1 - 0.004;
+                dir[i] = -1;
+            }
+            h[i] = nh;
+            let dth = (fam[i] ? -1 : 1) * V * Math.sin(b) / rm * dt;
+            const cap = 0.35; // at a closing tip the turn rate saturates
+            if (dth > cap)
+                dth = cap;
+            else if (dth < -cap)
+                dth = -cap;
+            if (mode === 1)
+                dth += 5 * S * g * dt; // E x B drift: the same sense for both charges
+            th[i] += dth;
+            const r = rAt(th[i], h[i]) * pinch;
+            const x = r * Math.cos(th[i]), y = h[i], z = r * Math.sin(th[i]);
+            hx[j] = x;
+            hx[j + 1] = y;
+            hx[j + 2] = z;
+            hv[j] = (x - px) / dt;
+            hv[j + 1] = (y - py) / dt;
+            hv[j + 2] = (z - pz) / dt;
+            const tight = Math.min(Math.max(1 - rm / RW, 0), 1); // 0 at the widest girth, 1 at a closing tip
+            code[i] = pack(fam[i], tight, heat[i]);
+            hK[i] = code[i] + 0.25; // trails read the same code
+            // lay ink along the path
+            const seg = Math.hypot(x - px, y - py, z - pz);
+            if (seg > 0.5) {
+                acc[i] = 0;
+                if (trail)
+                    trail.reset(i);
+                continue;
+            }
+            acc[i] += seg;
+            while (acc[i] >= spacing) {
+                acc[i] -= spacing;
+                const t = seg > 1e-6 ? 1 - acc[i] / seg : 1;
+                const k = lHead;
+                lHead = (lHead + 1) % NL;
+                lp[k * 3] = px + (x - px) * t;
+                lp[k * 3 + 1] = py + (y - py) * t;
+                lp[k * 3 + 2] = pz + (z - pz) * t;
+                la[k * 2] = code[i];
+                lb[k] = time;
+            }
+        }
+        // age of every ink point as a fraction of its life
+        for (let k = 0; k < NL; k++) {
+            if (la[k * 2 + 1] < -0.5 && lb[k] === 0)
+                continue;
+            const f = (time - lb[k]) / life;
+            la[k * 2 + 1] = f > 1 ? -1 : f;
+        }
+    }
+    // settle: particles spread round the surface and the lines are drawn
+    for (let i = 0; i < n; i++) {
+        const r = rAt(th[i], h[i]);
+        hx[i * 3] = r * Math.cos(th[i]);
+        hx[i * 3 + 1] = h[i];
+        hx[i * 3 + 2] = r * Math.sin(th[i]);
+    }
+    const warm = Math.min(u.uLineLife.value, 8);
+    for (let s = 0; s < warm / H_STEP; s++)
+        step(H_STEP);
+    // ---- geometry ----
+    const lgeo = new THREE.BufferGeometry();
+    const lpAttr = new THREE.BufferAttribute(lp, 3).setUsage(THREE.DynamicDrawUsage);
+    const laAttr = new THREE.BufferAttribute(la, 2).setUsage(THREE.DynamicDrawUsage);
+    lgeo.setAttribute('position', lpAttr);
+    lgeo.setAttribute('aL', laAttr);
+    const mk = (vs, fs) => new THREE.ShaderMaterial({
+        uniforms: u, vertexShader: vs, fragmentShader: fs, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending,
+    });
+    const lmat = mk(lineVertex, lineFragment);
+    const lines = new THREE.Points(lgeo, lmat);
+    lines.frustumCulled = false;
+    attachViewH(lines, u);
+    const hgeo = new THREE.BufferGeometry();
+    const hxAttr = new THREE.BufferAttribute(hx, 3).setUsage(THREE.DynamicDrawUsage);
+    const hcAttr = new THREE.BufferAttribute(code, 1).setUsage(THREE.DynamicDrawUsage);
+    hgeo.setAttribute('position', hxAttr);
+    hgeo.setAttribute('aCode', hcAttr);
+    const hmat = mk(headVertex, headFragment);
+    const heads = new THREE.Points(hgeo, hmat);
+    heads.frustumCulled = false;
+    heads.renderOrder = 3;
+    const object = new THREE.Group();
+    const proxy = createPickProxy(BOUNDS.center, bR);
+    object.add(lines, heads, proxy.mesh);
+    const trailGLSL = /* glsl */ `
+uniform float uTrailGain;
+${LIGHT_GLSL}
+vec3 trailShade(vec3 p, float f) {
+  float pitch;
+  vec3 c = familyLight(floor(TRAIL_K), pitch);
+  c /= max(max(c.r, max(c.g, c.b)), 1.0);                 // keep <= 1: a saturated colour cannot be tinted
+  return mix(c, uTrailColor, smoothstep(0.0, 0.55, f)) * uTrailGain;
+}
+vec3 trailView(vec3 mv, out float mag) { mag = 1.0; return mv; }
+`;
+    const materials = [lmat, hmat];
+    let trailKey = '', look = 1;
+    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, pos: hx, vel: hv, k: hK, glsl: trailGLSL, sizePx: 0.016, spacing: 0.002, sub: 12, 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);
+    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) {
+                object.worldToLocal(u.uCamLocal.value.copy(camera.position)).divideScalar(u.uSize.value);
+                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) {
+                lpAttr.needsUpdate = true;
+                laAttr.needsUpdate = true;
+                hxAttr.needsUpdate = true;
+                hcAttr.needsUpdate = true;
+                if (trail)
+                    trail.update(simD / look);
+            }
+        },
+        seek(t) { for (let s = 0; s < Math.round(t / H_STEP); s++)
+            step(H_STEP); lpAttr.needsUpdate = true; laAttr.needsUpdate = true; },
+        dispose() {
+            lgeo.dispose();
+            lmat.dispose();
+            hgeo.dispose();
+            hmat.dispose();
+            proxy.dispose();
+            if (trail)
+                trail.dispose();
+        },
+        _state: { hx, h, psi, heat },
+    };
+}
+/** 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: '#5fd6ff',
+    particleCount: 48,
+    shape: { type: 'cone', radius: 0.5, height: 1, radialSegments: 32 },
+    windings: 0.6,
+    pitchSpread: 0.3,
+    lineLife: 6,
+    lineDensity: 1,
+    counterColor: '#ff6fb3',
+    glow: 1,
+    seed: 1,
+    quality: 'medium',
+    pointerMode: 'drift',
+    pointerStrength: 1,
+    pointerRadius: 1,
+    pointerColor: '#fff0c8',
+    trailMode: 'comet',
+    trailLength: 0.8,
+    trailOpacity: 0.8,
+    trailColor: '#8f7bff',
+    trailShare: 1,
+};
+/** 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.magneticBottle.map((p) => p.value));
+const MagneticBottleParticles = ({ 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 MagneticBottleParticles;

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

@@ -0,0 +1,17 @@
+import React from 'react';
+import type { ObjectAnimations, ShapeBurstParticlesConfig, MouseMoveDomain } from '@3driseai/3drise-core';
+import type { ObjectReadyProps } from '../../types/objectReady';
+export interface ShapeBurstParticlesProps 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: ShapeBurstParticlesConfig;
+    /** Per-domain keyframes; the `particles` domain drives this object's config knobs. */
+    animations?: ObjectAnimations;
+}
+declare const ShapeBurstParticles: React.FC<ShapeBurstParticlesProps>;
+export default ShapeBurstParticles;
+//# sourceMappingURL=ShapeBurstParticles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ShapeBurstParticles.d.ts","sourceRoot":"","sources":["../../../src/components/particles/ShapeBurstParticles.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmE,MAAM,OAAO,CAAC;AAIxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAO1G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,MAAM,WAAW,wBAAyB,SAAQ,gBAAgB;IAC9D,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,yBAAyB,CAAC;IAClC,sFAAsF;IACtF,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACjC;AA4eD,QAAA,MAAM,mBAAmB,EAAE,KAAK,CAAC,EAAE,CAAC,wBAAwB,CAuD3D,CAAC;AAEF,eAAe,mBAAmB,CAAC"}