@3driseai/3drise-viewer 0.1.15 → 0.1.17

package/dist/components/effects/FieldLinesEffect.js

@@ -0,0 +1,260 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { useFrame } from '@react-three/fiber';
+import { applyGenerativeAnimations } from '../../utils/handleGenerativeEffectsAnimations.js';
+import { useObjectReady } from '../../hooks/useObjectReady.js';
+/**
+ * Magnetic dipole field lines around the host, from the analytic line equation
+ * r = L sin^2(theta), with trapped particles that bounce between magnetic
+ * mirror points and drift around the axis, like the Van Allen belts.
+ *
+ * The geometry only carries (shell, azimuth, s) per vertex; the shape is
+ * computed in the vertex shader, so extent, twist and tilt animate for free.
+ */
+const FIELD_LINE_SAMPLES = 96;
+function mulberry32(seed) {
+    return () => {
+        seed |= 0;
+        seed = (seed + 0x6d2b79f5) | 0;
+        let r = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+        r = (r + Math.imul(r ^ (r >>> 7), 61 | r)) ^ r;
+        return ((r ^ (r >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function buildFieldLines(shells, linesPerShell) {
+    const S = Math.round(Math.min(Math.max(shells, 1), 8));
+    const P = Math.round(Math.min(Math.max(linesPerShell, 2), 32));
+    const n = S * P * FIELD_LINE_SAMPLES;
+    const aShell = new Float32Array(n), aPhi = new Float32Array(n), aS = new Float32Array(n);
+    const index = new Uint32Array(S * P * (FIELD_LINE_SAMPLES - 1) * 2);
+    let v = 0, w = 0;
+    for (let s = 0; s < S; s++) {
+        for (let p = 0; p < P; p++) {
+            // stagger alternate shells by half a step so the lines interleave
+            const phi = ((p + (s % 2) * 0.5) / P) * Math.PI * 2;
+            for (let i = 0; i < FIELD_LINE_SAMPLES; i++) {
+                aShell[v] = S > 1 ? s / (S - 1) : 1;
+                aPhi[v] = phi;
+                aS[v] = i / (FIELD_LINE_SAMPLES - 1);
+                if (i > 0) {
+                    index[w++] = v - 1;
+                    index[w++] = v;
+                }
+                v++;
+            }
+        }
+    }
+    const geo = new THREE.BufferGeometry();
+    geo.setAttribute('position', new THREE.BufferAttribute(new Float32Array(n * 3), 3));
+    geo.setAttribute('aShell', new THREE.BufferAttribute(aShell, 1));
+    geo.setAttribute('aPhi', new THREE.BufferAttribute(aPhi, 1));
+    geo.setAttribute('aS', new THREE.BufferAttribute(aS, 1));
+    geo.setIndex(new THREE.BufferAttribute(index, 1));
+    return geo;
+}
+function buildFieldParticles(shells, linesPerShell, perLine) {
+    const S = Math.round(Math.min(Math.max(shells, 1), 8));
+    const P = Math.round(Math.min(Math.max(linesPerShell, 2), 32));
+    const Q = Math.round(Math.min(Math.max(perLine, 0), 40));
+    const n = S * P * Q;
+    const rand = mulberry32(11);
+    const aShell = new Float32Array(n), aPhi = new Float32Array(n), aSeed = new Float32Array(n * 3);
+    let v = 0;
+    for (let s = 0; s < S; s++) {
+        for (let p = 0; p < P; p++) {
+            const phi = ((p + (s % 2) * 0.5) / P) * Math.PI * 2;
+            for (let q = 0; q < Q; q++) {
+                aShell[v] = S > 1 ? s / (S - 1) : 1;
+                aPhi[v] = phi;
+                aSeed[v * 3] = rand();
+                aSeed[v * 3 + 1] = rand();
+                aSeed[v * 3 + 2] = rand();
+                v++;
+            }
+        }
+    }
+    const geo = new THREE.BufferGeometry();
+    geo.setAttribute('position', new THREE.BufferAttribute(new Float32Array(n * 3), 3));
+    geo.setAttribute('aShell', new THREE.BufferAttribute(aShell, 1));
+    geo.setAttribute('aPhi', new THREE.BufferAttribute(aPhi, 1));
+    geo.setAttribute('aSeed', new THREE.BufferAttribute(aSeed, 3));
+    return geo;
+}
+const lineVert = /* glsl */ `
+  attribute float aShell;
+  attribute float aPhi;
+  attribute float aS;
+  varying float vGlow;
+  
+  uniform float uTime;
+  uniform float uBound;
+  uniform float uExtent;
+  uniform float uTwist;
+  uniform float uTilt;
+
+  const float PI  = 3.14159265359;
+  const float TAU = 6.28318530718;
+
+  // the shell parameter u in 0..1 maps to an L-shell between the surface and uExtent
+  float shellL(float u){
+    return 1.05 + (max(uExtent, 1.1) - 1.05) * pow(u, 1.25);
+  }
+
+  // A dipole field line obeys r = L sin^2(theta): it leaves the surface
+  // (r = 1) where sin^2(theta0) = 1/L, arcs out to r = L at the equator and
+  // comes back down at pi - theta0. s runs 0..1 between the two footpoints.
+  vec3 fieldPoint(float L, float phi, float s, out float r){
+    float th0 = asin(sqrt(1.0 / L));
+    float th  = mix(th0, PI - th0, s);
+    float st  = sin(th);
+    r = L * st * st;
+    float ph = phi + uTwist * (th - 0.5 * PI) + uTime * 0.04;
+    vec3 p = r * vec3(st * cos(ph), cos(th), st * sin(ph));
+    // tilt the dipole axis about X
+    float c = cos(radians(uTilt)), sn = sin(radians(uTilt));
+    return vec3(p.x, c * p.y - sn * p.z, sn * p.y + c * p.z);
+  }
+
+
+  void main(){
+    float r;
+    vec3 p = fieldPoint(shellL(aShell), aPhi, aS, r);
+    // |B| falls off as 1/r^3, so the lines burn brightest near the footpoints
+    vGlow = clamp(pow(1.0 / r, 1.5), 0.0, 1.0);
+    gl_Position = projectionMatrix * modelViewMatrix * vec4(p * uBound, 1.0);
+  }
+`;
+const lineFrag = /* glsl */ `
+  uniform vec3  uColor;
+  uniform vec3  uApexColor;
+  uniform float uOpacity;
+  uniform float uIntensity;
+  varying float vGlow;
+
+  void main(){
+    vec3 col = mix(uApexColor, uColor, vGlow);
+    float a = (0.14 + 0.5 * vGlow) * uOpacity;
+    gl_FragColor = vec4(col * uIntensity, a);
+  }
+`;
+const particleVert = /* glsl */ `
+  attribute float aShell;
+  attribute float aPhi;
+  attribute vec3  aSeed;
+  uniform float uParticleSize;
+  uniform float uIntensity;
+  varying float vGlow;
+  varying float vSign;
+  
+  uniform float uTime;
+  uniform float uBound;
+  uniform float uExtent;
+  uniform float uTwist;
+  uniform float uTilt;
+
+  const float PI  = 3.14159265359;
+  const float TAU = 6.28318530718;
+
+  // the shell parameter u in 0..1 maps to an L-shell between the surface and uExtent
+  float shellL(float u){
+    return 1.05 + (max(uExtent, 1.1) - 1.05) * pow(u, 1.25);
+  }
+
+  // A dipole field line obeys r = L sin^2(theta): it leaves the surface
+  // (r = 1) where sin^2(theta0) = 1/L, arcs out to r = L at the equator and
+  // comes back down at pi - theta0. s runs 0..1 between the two footpoints.
+  vec3 fieldPoint(float L, float phi, float s, out float r){
+    float th0 = asin(sqrt(1.0 / L));
+    float th  = mix(th0, PI - th0, s);
+    float st  = sin(th);
+    r = L * st * st;
+    float ph = phi + uTwist * (th - 0.5 * PI) + uTime * 0.04;
+    vec3 p = r * vec3(st * cos(ph), cos(th), st * sin(ph));
+    // tilt the dipole axis about X
+    float c = cos(radians(uTilt)), sn = sin(radians(uTilt));
+    return vec3(p.x, c * p.y - sn * p.z, sn * p.y + c * p.z);
+  }
+
+
+  void main(){
+    // Trapped particles bounce between two magnetic mirror points, slowing to
+    // a stop at each end, while drifting around the planet: ions one way,
+    // electrons the other. The seed sets pitch angle, phase and drift.
+    float amp = mix(0.18, 0.49, aSeed.y);
+    float w   = 0.9 + 0.5 * aSeed.x;
+    float s   = 0.5 + amp * sin(uTime * w + aSeed.x * TAU);
+    float drift = (aSeed.z - 0.5) * 0.35;
+    float r;
+    vec3 p = fieldPoint(shellL(aShell), aPhi + drift * uTime, s, r);
+    vGlow = clamp(pow(1.0 / r, 1.2), 0.0, 1.0);
+    vSign = step(0.5, aSeed.z);
+    vec4 mv = modelViewMatrix * vec4(p * uBound, 1.0);
+    gl_PointSize = uParticleSize * uIntensity * (0.7 + 0.6 * aSeed.y) * (14.0 * uBound / max(-mv.z, 1e-3));
+    gl_Position = projectionMatrix * mv;
+  }
+`;
+const particleFrag = /* glsl */ `
+  uniform vec3  uColor;
+  uniform vec3  uApexColor;
+  uniform float uOpacity;
+  varying float vGlow;
+  varying float vSign;
+
+  void main(){
+    float d = length(gl_PointCoord - 0.5);
+    if (d > 0.5) discard;
+    float core = smoothstep(0.5, 0.0, d);
+    vec3 tint = mix(uColor, uApexColor, vSign * 0.7);
+    vec3 col = mix(tint, vec3(1.0), core * core * 0.6);
+    gl_FragColor = vec4(col, core * core * (0.5 + 0.5 * vGlow) * uOpacity);
+  }
+`;
+const FieldLinesEffect = ({ boundingRadius, config, animations, onObjectReady, onObjectDispose }) => {
+    const { intensity, speed, color, opacity, shells = 4, linesPerShell = 12, extent = 3.2, twist = 0, tilt = 11, particleCount = 6, particleSize = 1.2, apexColor = '#6a5cff', } = config;
+    const rootRef = useRef(null);
+    const animCache = useRef({});
+    useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
+    // one uniform set, shared by the lines and the particles
+    const uniforms = useMemo(() => ({
+        uTime: { value: 0 },
+        uSpeed: { value: 1 },
+        uIntensity: { value: 1 },
+        uOpacity: { value: 1 },
+        uColor: { value: new THREE.Color() },
+        uApexColor: { value: new THREE.Color() },
+        uBound: { value: 1 },
+        uExtent: { value: 3.2 },
+        uTwist: { value: 0 },
+        uTilt: { value: 11 },
+        uParticleSize: { value: 1.2 },
+    }), []);
+    const materials = useMemo(() => [
+        new THREE.ShaderMaterial({ vertexShader: lineVert, fragmentShader: lineFrag, uniforms, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending }),
+        new THREE.ShaderMaterial({ vertexShader: particleVert, fragmentShader: particleFrag, uniforms, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending }),
+    ], [uniforms]);
+    useEffect(() => () => materials.forEach((m) => m.dispose()), [materials]);
+    const lineGeometry = useMemo(() => buildFieldLines(shells, linesPerShell), [shells, linesPerShell]);
+    const particleGeometry = useMemo(() => buildFieldParticles(shells, linesPerShell, particleCount), [shells, linesPerShell, particleCount]);
+    useEffect(() => () => lineGeometry.dispose(), [lineGeometry]);
+    useEffect(() => () => particleGeometry.dispose(), [particleGeometry]);
+    useLayoutEffect(() => {
+        uniforms.uSpeed.value = speed;
+        uniforms.uIntensity.value = intensity;
+        uniforms.uOpacity.value = opacity;
+        uniforms.uColor.value.set(color);
+        uniforms.uApexColor.value.set(apexColor);
+        uniforms.uBound.value = boundingRadius;
+        uniforms.uExtent.value = extent;
+        uniforms.uTwist.value = twist;
+        uniforms.uTilt.value = tilt;
+        uniforms.uParticleSize.value = particleSize;
+    }, [uniforms, speed, intensity, opacity, color, apexColor, boundingRadius, extent, twist, tilt, particleSize]);
+    useFrame((_, delta) => {
+        uniforms.uTime.value += delta * uniforms.uSpeed.value;
+        if (animations?.length)
+            applyGenerativeAnimations(materials, animations, animCache.current, Date.now(), false);
+    });
+    return (_jsxs("group", { ref: rootRef, children: [_jsx("lineSegments", { geometry: lineGeometry, material: materials[0], frustumCulled: false }), _jsx("points", { geometry: particleGeometry, material: materials[1], frustumCulled: false })] }));
+};
+export default FieldLinesEffect;

package/dist/components/effects/FireflySwarmEffect.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import type { AnimationOptions, FireflySwarmConfig } from '@3driseai/3drise-core';
+import type { ObjectReadyProps } from '../../types/objectReady';
+export interface FireflySwarmEffectProps extends ObjectReadyProps {
+    boundingRadius: number;
+    config: FireflySwarmConfig;
+    animations?: AnimationOptions[];
+    /** True when the effect is attached to an object, so it can react to the host. */
+    hasHost?: boolean;
+}
+declare const FireflySwarmEffect: React.FC<FireflySwarmEffectProps>;
+export default FireflySwarmEffect;
+//# sourceMappingURL=FireflySwarmEffect.d.ts.map

package/dist/components/effects/FireflySwarmEffect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FireflySwarmEffect.d.ts","sourceRoot":"","sources":["../../../src/components/effects/FireflySwarmEffect.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAsD,MAAM,OAAO,CAAC;AAG3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAGlF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC7D,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAChC,kFAAkF;IAClF,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAwXD,QAAA,MAAM,kBAAkB,EAAE,KAAK,CAAC,EAAE,CAAC,uBAAuB,CA+BzD,CAAC;AAEF,eAAe,kBAAkB,CAAC"}

package/dist/components/effects/FireflySwarmEffect.js

@@ -0,0 +1,408 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { useFrame } from '@react-three/fiber';
+import { applyGenerativeAnimations } from '../../utils/handleGenerativeEffectsAnimations.js';
+import { useObjectReady } from '../../hooks/useObjectReady.js';
+/**
+ * Kuramoto-coupled fireflies drifting on a divergence-free flow: random blinking slowly locks into sync, with ripples of light rolling through the swarm. Use for night, garden, forest, magical scenes.
+ *
+ * dθᵢ/dt = ωᵢ + K/Σw · Σⱼ wᵢⱼ sin(θⱼ − θᵢ), wᵢⱼ = e^(−d²/ℓ²) · flash when θ wraps · drift = ABC flow (∇·u = 0)
+ */
+// ---------------------------------------------------------------------------
+// Synchronous fireflies as Kuramoto oscillators.
+// Each firefly carries a phase theta_i that advances at its own natural rate
+// omega_i (spread ~8% around the mean) and is nudged toward its neighbours:
+//   dtheta_i/dt = omega_i + K / sum_j w_ij * sum_j w_ij sin(theta_j - theta_i)
+// with w_ij = exp(-d_ij^2 / l^2). Because the coupling is local, order does not
+// appear everywhere at once: synchronised patches grow, meet and leave phase
+// gradients behind, which read as waves of light rolling through the swarm.
+// A firefly flashes when its phase wraps (short rise, ~0.2 s decay). The
+// coupling breathes slowly (and each natural rate drifts a little), so the
+// swarm keeps sliding out of and back into step instead of freezing.
+// The bodies drift on an ABC (Arnold-Beltrami-Childress) flow, an exactly
+// divergence-free velocity field, so the swarm stirs without clumping; a soft
+// ellipsoidal shell keeps them around the host.
+// ---------------------------------------------------------------------------
+const vert = /* glsl */ `
+  attribute vec3 aFly;       // phase fraction (0..1, 0 = flash), seed, per-fly frequency (Hz)
+  uniform float uTime;
+  uniform float uIntensity;
+  uniform float uGlowSize;
+  uniform float uBound;
+  uniform float uViewH;
+  varying float vFlash;
+  varying float vSeed;
+  varying float vRad;        // sprite radius in world units
+  varying float vFade;
+
+  void main(){
+    // time since the phase last wrapped, in seconds
+    float tau = aFly.x / max(aFly.z, 0.02);
+    // luciferin pulse: fast rise, exponential decay (~0.2 s)
+    float rise = smoothstep(0.0, 0.05, tau);
+    float flash = rise * (0.85 * exp(-max(tau - 0.05, 0.0) / 0.2) + 0.15 * exp(-tau / 0.7));
+    vFlash = flash;
+    vSeed = aFly.y;
+    vec3 p = position;
+    // slow bobbing on top of the drift
+    p.y += 0.035 * uBound * sin(uTime * (0.7 + 0.5 * aFly.y) + aFly.y * 40.0);
+    vec4 mv = modelViewMatrix * vec4(p, 1.0);
+    float body = 0.03 * uBound;
+    float halo = 0.55 * uBound * uGlowSize * (0.7 + 0.3 * uIntensity);
+    vRad = flash > 0.004 ? max(halo, body) : body;
+    float pix = vRad * projectionMatrix[1][1] * uViewH / max(-mv.z, 0.05);
+    gl_PointSize = clamp(pix, 1.5, 200.0);
+    // keep energy when a sprite is clamped to a minimum size
+    vFade = min(pix / 1.5, 1.0);
+    gl_Position = projectionMatrix * mv;
+  }
+`;
+const frag = /* glsl */ `
+  uniform vec3 uColor;
+  uniform vec3 uFlashColor;
+  uniform float uIntensity;
+  uniform float uOpacity;
+  uniform float uGlowSize;
+  uniform float uBound;
+  varying float vFlash;
+  varying float vSeed;
+  varying float vRad;
+  varying float vFade;
+
+  void main(){
+    float d = length(gl_PointCoord - 0.5) * 2.0;
+    if (d > 1.0) discard;
+    float r = d * vRad / uBound;                 // radius in host units
+    float edge = 1.0 - smoothstep(0.75, 1.0, d);
+    // faint body: a tiny soft dot that is always there
+    float bodyR = 0.018;
+    float body = exp(-(r * r) / (bodyR * bodyR)) * 0.5;
+    // flash: hot lantern core + wide soft halo (additive, energy kept low)
+    float g = max(uGlowSize, 0.2);
+    float core = exp(-(r * r) / (0.0016 * g * g + 0.0004));
+    float halo = exp(-r / (0.34 * g)) * 0.06 + exp(-r / (0.15 * g)) * 0.2 + exp(-r / (0.05 * g)) * 0.45;
+    float f = vFlash;
+    // small per-fly colour variation: some lanterns are greener, some warmer
+    vec3 flashCol = mix(uFlashColor, uFlashColor * vec3(1.25, 0.95, 0.5), vSeed * 0.5);
+    vec3 col = uColor * body * (1.0 - 0.6 * f);
+    col += flashCol * f * (halo + core * 1.1);
+    col += vec3(1.0, 1.0, 0.86) * core * f * f * 1.7;   // white-hot only in the thin core
+    col *= edge * uIntensity * uOpacity * vFade * vFade;
+    if (max(col.r, max(col.g, col.b)) < 0.002) discard;
+    gl_FragColor = vec4(col, 1.0);
+  }
+`;
+function mulberry32(seed) {
+    return () => {
+        seed |= 0;
+        seed = (seed + 0x6d2b79f5) | 0;
+        let r = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+        r = (r + Math.imul(r ^ (r >>> 7), 61 | r)) ^ r;
+        return ((r ^ (r >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function createUniforms() {
+    return {
+        uTime: { value: 0 },
+        uSpeed: { value: 1 },
+        uIntensity: { value: 1 },
+        uOpacity: { value: 1 },
+        uColor: { value: new THREE.Color() },
+        uFlashColor: { value: new THREE.Color() },
+        uCoupling: { value: 1 },
+        uFrequency: { value: 0.55 },
+        uSpread: { value: 2.4 },
+        uDriftSpeed: { value: 1 },
+        uGlowSize: { value: 1 },
+        uBound: { value: 1 },
+        uViewH: { value: 800 },
+    };
+}
+function applyConfig(u, c, bound, env) {
+    u.uSpeed.value = c.speed;
+    u.uIntensity.value = c.intensity;
+    u.uOpacity.value = c.opacity;
+    u.uColor.value.set(c.color);
+    u.uFlashColor.value.set(c.flashColor);
+    u.uCoupling.value = c.coupling;
+    u.uFrequency.value = c.frequency;
+    u.uSpread.value = c.spread;
+    u.uDriftSpeed.value = c.driftSpeed;
+    u.uGlowSize.value = c.glowSize;
+    u.uBound.value = bound;
+}
+function build(u, c, bound, env) {
+    const n = Math.round(Math.min(Math.max(c.count, 20), 400));
+    const hasHost = !!(env && env.hasHost);
+    const TAU = Math.PI * 2;
+    const SIM_DT = 1 / 30;
+    const PACE = 0.06;
+    const rand = mulberry32(1307);
+    const pos = new Float32Array(n * 3);
+    const fly = new Float32Array(n * 3);
+    const theta = new Float32Array(n);
+    const omegaDev = new Float32Array(n); // relative natural-frequency offset
+    const drift = new Float32Array(n); // phase of the slow frequency wander
+    const sn = new Float32Array(n);
+    const cs = new Float32Array(n);
+    const w = new Float32Array(n * n);
+    const wsum = new Float32Array(n);
+    // homes: uniform in an ellipsoidal shell around the host (unit direction + radial fraction)
+    const b = bound;
+    const cy = 0.25 * b;
+    const SQ = 0.72; // vertical squash of the shell
+    const rIn0 = hasHost ? 1.15 * b : 0;
+    const homeDir = new Float32Array(n * 3);
+    const homeS = new Float32Array(n);
+    const spinRate = new Float32Array(n);
+    const off = new Float32Array(n * 3); // flow-driven offset from home
+    for (let i = 0; i < n; i++) {
+        let dx = 0, dy = 1, dz = 0, sr = 0.5;
+        for (let k = 0; k < 40; k++) {
+            dy = rand() * 2 - 1;
+            const ph = rand() * TAU, rr = Math.sqrt(1 - dy * dy);
+            dx = rr * Math.cos(ph);
+            dz = rr * Math.sin(ph);
+            // radius with density uniform in volume
+            const ri = rIn0 / b, ro = Math.max(c.spread, ri + 0.45);
+            const r = Math.cbrt(ri * ri * ri + rand() * (ro * ro * ro - ri * ri * ri));
+            sr = Math.min(Math.max((r - ri) / (ro - ri), 0), 1);
+            if (dy * SQ * r + 0.25 > -0.7)
+                break;
+        }
+        homeDir[i * 3] = dx;
+        homeDir[i * 3 + 1] = dy;
+        homeDir[i * 3 + 2] = dz;
+        homeS[i] = sr;
+        spinRate[i] = (0.6 + 0.8 * rand()) * (rand() < 0.8 ? 1 : -0.6);
+        theta[i] = rand() * TAU;
+        // gaussian spread of natural frequencies (sigma = 8%)
+        const g = Math.sqrt(-2 * Math.log(1 - rand() * 0.9999)) * Math.cos(TAU * rand());
+        omegaDev[i] = Math.max(-0.25, Math.min(0.25, g * 0.08));
+        drift[i] = rand() * TAU;
+        fly[i * 3 + 1] = rand();
+    }
+    const geo = new THREE.BufferGeometry();
+    const posAttr = new THREE.BufferAttribute(pos, 3);
+    const flyAttr = new THREE.BufferAttribute(fly, 3);
+    posAttr.setUsage(THREE.DynamicDrawUsage);
+    flyAttr.setUsage(THREE.DynamicDrawUsage);
+    geo.setAttribute('position', posAttr);
+    geo.setAttribute('aFly', flyAttr);
+    const mat = new THREE.ShaderMaterial({
+        vertexShader: vert, fragmentShader: frag, uniforms: u,
+        transparent: true, depthWrite: false, blending: THREE.AdditiveBlending,
+    });
+    const pts = new THREE.Points(geo, mat);
+    pts.frustumCulled = false;
+    const vp = new THREE.Vector2();
+    pts.onBeforeRender = (renderer) => {
+        renderer.getDrawingBufferSize(vp);
+        u.uViewH.value = vp.y * 0.5;
+    };
+    const group = new THREE.Group();
+    group.add(pts);
+    let simTime = 0; // seconds of simulated time
+    let acc = 0; // leftover time for the fixed-rate oscillator step
+    let stepCount = 0;
+    // coupling weights, refreshed a few times a second (bodies move slowly)
+    function refreshWeights() {
+        const ell = Math.max(0.3 * u.uSpread.value * b, 0.25 * b);
+        const inv = 1 / (ell * ell);
+        for (let i = 0; i < n; i++)
+            wsum[i] = 0;
+        for (let i = 0; i < n; i++) {
+            const xi = pos[i * 3], yi = pos[i * 3 + 1], zi = pos[i * 3 + 2];
+            w[i * n + i] = 0;
+            for (let j = i + 1; j < n; j++) {
+                const dx = pos[j * 3] - xi, dy = pos[j * 3 + 1] - yi, dz = pos[j * 3 + 2] - zi;
+                const q = (dx * dx + dy * dy + dz * dz) * inv;
+                const v = q < 9 ? Math.exp(-q) : 0;
+                w[i * n + j] = v;
+                w[j * n + i] = v;
+                wsum[i] += v;
+                wsum[j] += v;
+            }
+        }
+    }
+    // natural angular frequency of fly i at time t. A slowly turning frequency
+    // gradient acts as a pacemaker: once locked, phase lags away from the fast side,
+    // so each synchronised flash sweeps across the swarm as a travelling wave.
+    let gx = 1, gy = 0, gz = 0;
+    function omegaOf(i, t, base) {
+        const i3 = i * 3;
+        const grad = (pos[i3] * gx + (pos[i3 + 1] - cy) * gy + pos[i3 + 2] * gz) / Math.max(u.uSpread.value * b, 0.1);
+        return base * (1 + omegaDev[i] + 0.022 * Math.sin(0.045 * t + drift[i]) + PACE * grad);
+    }
+    function turnPacemaker(t) {
+        const a = 0.021 * t + 0.6, e = 0.35 * Math.sin(0.013 * t);
+        gx = Math.cos(a) * Math.cos(e);
+        gy = Math.sin(e);
+        gz = Math.sin(a) * Math.cos(e);
+    }
+    function oscillatorStep(h) {
+        const base = TAU * Math.max(u.uFrequency.value, 0.02);
+        // slow breathing of the coupling: ramps up from zero, then eases in and out of sync
+        const t = simTime;
+        turnPacemaker(t);
+        const ramp = Math.min(t / 14, 1);
+        const breathe = 0.6 + 0.4 * Math.cos((TAU * Math.max(t - 14, 0)) / 80);
+        const K = Math.max(u.uCoupling.value, 0) * 0.35 * base * ramp * ramp * (3 - 2 * ramp) * breathe;
+        for (let i = 0; i < n; i++) {
+            sn[i] = Math.sin(theta[i]);
+            cs[i] = Math.cos(theta[i]);
+        }
+        for (let i = 0; i < n; i++) {
+            let S = 0, C = 0;
+            const row = i * n;
+            for (let j = 0; j < n; j++) {
+                const wij = w[row + j];
+                S += wij * sn[j];
+                C += wij * cs[j];
+            }
+            // sum_j w_ij sin(theta_j - theta_i) = cos(theta_i) S - sin(theta_i) C
+            const pull = (cs[i] * S - sn[i] * C) / Math.max(wsum[i], 1);
+            let th = theta[i] + (omegaOf(i, t, base) + K * pull) * h;
+            th -= TAU * Math.floor(th / TAU);
+            theta[i] = th;
+        }
+    }
+    // Each fly is tethered to a home that circles the host slowly; the ABC flow
+    // stirs the offset from home, so neighbours wander together while the
+    // swarm as a whole keeps its even spread (no clumping at the shell).
+    let spin = 0;
+    function driftStep(h) {
+        const t = simTime;
+        const k = 1.05 / b;
+        const amp = 0.11 * b * u.uDriftSpeed.value;
+        spin += h * 0.045 * u.uDriftSpeed.value;
+        // ABC flow with slowly turning phases: still exactly divergence-free
+        const p1 = 0.13 * t, p2 = 0.09 * t + 1.7, p3 = 0.11 * t + 4.1;
+        const A = amp, B = 0.8 * amp, C = 0.65 * amp;
+        const rOut = Math.max(u.uSpread.value * b, rIn0 + 0.45 * b);
+        const tether = 0.25;
+        for (let i = 0; i < n; i++) {
+            const i3 = i * 3;
+            const r = rIn0 + homeS[i] * (rOut - rIn0);
+            const ang = spin * spinRate[i] * (1.6 * b / (r + b));
+            const ca = Math.cos(ang), sa = Math.sin(ang);
+            const dx = homeDir[i3], dz = homeDir[i3 + 2];
+            const hx = (ca * dx - sa * dz) * r;
+            const hy = homeDir[i3 + 1] * SQ * r + cy;
+            const hz = (sa * dx + ca * dz) * r;
+            let x = pos[i3], y = pos[i3 + 1], z = pos[i3 + 2];
+            const vx = A * Math.sin(k * z + p1) + C * Math.cos(k * y + p3);
+            const vy = B * Math.sin(k * x + p2) + A * Math.cos(k * z + p1);
+            const vz = C * Math.sin(k * y + p3) + B * Math.cos(k * x + p2);
+            const ox = off[i3] + (vx - tether * off[i3]) * h;
+            const oy = off[i3 + 1] + (vy - tether * off[i3 + 1]) * h;
+            const oz = off[i3 + 2] + (vz - tether * off[i3 + 2]) * h;
+            off[i3] = ox;
+            off[i3 + 1] = oy;
+            off[i3 + 2] = oz;
+            x = hx + ox;
+            y = hy + oy;
+            z = hz + oz;
+            // keep clear of the host and above the floor (a soft projection)
+            if (rIn0 > 0) {
+                const d = Math.sqrt(x * x + y * y + z * z) + 1e-6;
+                const lim = rIn0 * 0.92;
+                if (d < lim + 0.15 * b) {
+                    const e = (lim + 0.15 * b - d) / (0.15 * b);
+                    const nd = d + 0.15 * b * e * e * 0.5;
+                    const f = Math.max(nd, lim) / d;
+                    x *= f;
+                    y *= f;
+                    z *= f;
+                }
+            }
+            if (y < -0.75 * b)
+                y = -0.75 * b - 0.1 * b * Math.tanh((-0.75 * b - y) / (0.1 * b));
+            pos[i3] = x;
+            pos[i3 + 1] = y;
+            pos[i3 + 2] = z;
+        }
+    }
+    driftStep(0);
+    refreshWeights();
+    return {
+        object: group,
+        materials: [mat],
+        apply(c2) { },
+        update(dt, camera) {
+            const h = Math.min(Math.max(dt, 0), 0.1) * Math.max(u.uSpeed.value, 0);
+            u.uTime.value += h;
+            // drift: substeps of at most 1/30 s
+            const subs = Math.max(1, Math.ceil(h / SIM_DT));
+            for (let s = 0; s < subs; s++) {
+                driftStep(h / subs);
+                simTime += h / subs;
+            }
+            // oscillators at a fixed rate
+            acc += h;
+            let guard = 0;
+            while (acc >= SIM_DT && guard < 6) {
+                oscillatorStep(SIM_DT);
+                acc -= SIM_DT;
+                guard++;
+                stepCount++;
+                if (stepCount % 10 === 0)
+                    refreshWeights();
+            }
+            if (guard >= 6)
+                acc = 0;
+            // render phase = state + the unstepped remainder
+            const base = TAU * Math.max(u.uFrequency.value, 0.02);
+            for (let i = 0; i < n; i++) {
+                const om = omegaOf(i, simTime, base);
+                let th = theta[i] + om * acc;
+                th -= TAU * Math.floor(th / TAU);
+                fly[i * 3] = th / TAU;
+                fly[i * 3 + 2] = om / TAU;
+            }
+            posAttr.needsUpdate = true;
+            flyAttr.needsUpdate = true;
+        },
+        dispose() { geo.dispose(); mat.dispose(); },
+    };
+}
+/** Defaults for every knob, so an older saved config still renders. */
+const DEFAULTS = {
+    intensity: 1,
+    speed: 1,
+    color: '#6f7d45',
+    opacity: 1,
+    count: 150,
+    coupling: 1,
+    frequency: 0.55,
+    spread: 2.4,
+    driftSpeed: 1,
+    glowSize: 1,
+    flashColor: '#d4ff5c',
+};
+const FireflySwarmEffect = ({ boundingRadius, config, animations, hasHost = false, onObjectReady, onObjectDispose }) => {
+    const rootRef = useRef(null);
+    const animCache = useRef({});
+    useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
+    // a standalone effect gets boundingRadius 1
+    const b = boundingRadius > 0 ? boundingRadius : 1;
+    const cfg = useMemo(() => ({ ...DEFAULTS, ...config }), [config]);
+    const env = useMemo(() => ({ hasHost: hasHost }), [hasHost]);
+    // uniforms outlive the objects, so keyframe animations survive a rebuild
+    const uniforms = useMemo(() => createUniforms(), []);
+    // rebuilt only when the host size or a structural knob changes
+    const instance = useMemo(() => build(uniforms, { ...DEFAULTS, ...config }, b, env), [uniforms, b, env, cfg.count]);
+    useEffect(() => () => instance.dispose(), [instance]);
+    useLayoutEffect(() => {
+        applyConfig(uniforms, cfg, b, env);
+        instance.apply(cfg);
+    }, [instance, uniforms, cfg, b, env]);
+    useFrame((state, delta) => {
+        instance.update(Math.min(delta, 0.1), state.camera);
+        if (animations?.length)
+            applyGenerativeAnimations(instance.materials, animations, animCache.current, Date.now(), false);
+    });
+    return (_jsx("group", { ref: rootRef, children: _jsx("primitive", { object: instance.object }) }));
+};
+export default FireflySwarmEffect;