@3driseai/3drise-viewer 0.1.26 → 0.1.28

package/dist/components/particles/ShapeFlowParticles.js

@@ -0,0 +1,755 @@
+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 { shapeField } from '../../utils/particleShape.js';
+import { useObjectReady } from '../../hooks/useObjectReady.js';
+import { useConfigLiveHandle } from '../../hooks/useConfigLive.js';
+/**
+ * Shape Flow — A wind tunnel of particle streams flowing round an invisible mesh shape: divergence-free flow, wake eddies, streaklines coloured by pressure; the cursor is a second obstacle, a jet or a vortex. Use for tech, aero and product scenes.
+ */
+// Shape Flow — a wind tunnel: streams of tracer particles flowing past an invisible mesh shape.
+// Movement: the air is an incompressible flow round the shape. A uniform wind U is written as a
+//           vector potential psi = (U x x) / 2 and constrained at the obstacle the Bridson way
+//           (curl-noise for procedural fluid flow, 2007): psi' = a(d) psi + (1 - a(d)) n (n . psi), with
+//           d the distance to the shape, n its normal and a a smooth ramp over a boundary layer. The
+//           velocity u = curl psi' is divergence-free and tangent to the surface, so the streams part
+//           at the front, speed round the sides and close behind. Downstream of the shape a wake of
+//           ABC (Arnold–Beltrami–Childress) eddies, carried with the wind and faded in behind the body,
+//           curls the closing streams. The base flow is precomputed on a grid when the shape changes.
+//           Tracers are released on a regular lattice of lanes upstream and advected with RK2, so the
+//           picture is a clean set of streaklines.
+// Colour:   exact, from Bernoulli: pressure coefficient Cp = 1 - |u|^2 / U^2. High pressure (the
+//           stagnation point at the nose, the slow wake) takes `color`; low pressure (fast flow round
+//           the shoulders) takes `fastColor`; the fastest flow whitens. Tails fade into trailColor.
+// Mouse (pointerMode, cursor on the camera-facing plane through the object):
+//   obstacle — a second, spherical body at the cursor (the potential-flow sphere solution): the
+//              streams part round it too.
+//   jet      — the cursor blows along its own motion: a travelling puff pushes the streams.
+//   vortex   — a vortex line along the view axis at the cursor: the streams wrap round it.
+// Trails (trailMode): streak = motion blur, comet = streaklines, echo = smoke.
+//
+// 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 = ['obstacle', 'jet', 'vortex'];
+const RAKES = ['tube', 'sheet', 'cross'];
+const H_STEP = 1 / 90;
+const U0 = 0.55; // wind speed (units / s) at flowSpeed 1
+const XL0 = 1.7, YL0 = 1.15; // smallest tunnel half extents (along the wind / across)
+const GX = 56, GY = 40, GZ = 40; // base-flow grid
+const DELTA = 0.32; // boundary-layer thickness for the potential ramp
+const TRAIL_LOOK = { streak: 0.35, comet: 1, echo: 1 };
+const TRAIL_ALPHA = { streak: 1.8, comet: 2, echo: 2.6 };
+const BOUNDS = { center: [0, 0, 0], radius: 1.6 };
+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 },
+        uFlowSpeed: { value: 1 },
+        uWindPitch: { value: 0 },
+        uLanes: { value: 22 },
+        uStreamWidth: { value: 0.75 },
+        uTurbulence: { value: 0.6 },
+        uFastColor: colorUniform('#ffffff'),
+        uHeadSize: { value: 1 },
+        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.uFlowSpeed.value = c.flowSpeed;
+    u.uWindPitch.value = c.windPitch;
+    u.uLanes.value = c.lanes;
+    u.uStreamWidth.value = c.streamWidth;
+    u.uTurbulence.value = c.turbulence;
+    u.uFastColor.value.set(c.fastColor);
+    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 = speed ratio s = |u| / (1.8 U) (0..1) + 2 x cursor glow (0..31)
+const PRESSURE_GLSL = /* glsl */ `
+uniform vec3 uColor, uFastColor, uPointerColor;
+vec3 pressureLight(float code) {
+  float glow = floor(code / 2.0) / 31.0;
+  float s = code - 2.0 * floor(code / 2.0);
+  float q = s * 1.8;                                   // |u| / U
+  float cp = 1.0 - q * q;                              // Bernoulli pressure coefficient
+  float t = smoothstep(0.9, -1.4, cp);                 // 0 high pressure .. 1 low pressure
+  vec3 c = mix(uColor, uFastColor, t);
+  c = mix(c, vec3(1.0), 0.45 * smoothstep(-1.2, -2.2, cp));   // the fastest flow whitens
+  return mix(c, uPointerColor, 0.6 * glow) * (1.1 + 0.6 * t);
+}
+`;
+const headVertex = /* glsl */ `
+uniform float uSize, uViewH, uIntensity, uOpacity, uHeadSize;
+${PRESSURE_GLSL}
+attribute vec2 aH;       // code, fade (spawn / exit)
+varying vec3 vCol;
+varying float vA;
+void main() {
+  vec4 mv = modelViewMatrix * vec4(position * uSize, 1.0);
+  vCol = pressureLight(aH.x) * uIntensity;
+  vA = uOpacity * aH.y * 0.9;
+  gl_PointSize = clamp(uHeadSize * uSize * uViewH * 0.014 / -mv.z, 1.5, 22.0) * step(0.01, aH.y);
+  gl_Position = projectionMatrix * mv;
+}
+`;
+// smooth ramp from Bridson's paper: 0 at the surface, 1 beyond the boundary layer
+function ramp(r) {
+    if (r >= 1)
+        return 1;
+    if (r <= 0)
+        return 0;
+    return (15 / 8) * r - (10 / 8) * r * r * r + (3 / 8) * r * r * r * r * r;
+}
+function build(u, c, size) {
+    const q = qualityScale(c.quality);
+    const n = Math.max(50, Math.round(c.particleCount * q));
+    const rng = mulberry32(seedMix(0xf10e, c.seed));
+    const F = shapeField(c.shape);
+    // the tunnel grows with the shape: a margin upstream / downstream and round the sides
+    const ext = Math.max(F.rMax, (F.Y1 - F.Y0) / 2);
+    const XL = Math.max(XL0, ext + 0.95), YL = Math.max(YL0, ext + 0.4);
+    const bR = Math.max(BOUNDS.radius, Math.hypot(XL, YL) * 0.95);
+    const pitch = (c.windPitch * Math.PI) / 180;
+    const Ux = Math.cos(pitch), Uy = Math.sin(pitch); // unit wind direction (in the x-y plane)
+    // ---- signed distance to the shape, from its radial field ----
+    function sdf(x, y, z) {
+        const r = Math.hypot(x, z), th = Math.atan2(z, x);
+        const hc = Math.min(Math.max(y, F.Y0), F.Y1);
+        const R = F.rAt(th, hc);
+        const dr = r - R;
+        const dy = y > F.Y1 ? y - F.Y1 : y < F.Y0 ? F.Y0 - y : 0;
+        if (dy === 0) {
+            if (dr >= 0)
+                return dr;
+            return Math.max(dr, y - F.Y1, F.Y0 - y); // inside: nearest wall or cap
+        }
+        return dr <= 0 ? dy : Math.hypot(dr, dy); // above or below the caps
+    }
+    // ---- base flow on a grid: u = curl psi', psi' = a psi + (1 - a) n (n . psi), psi = (U x x) / 2 ----
+    const dx = (2 * XL) / (GX - 1), dy = (2 * YL) / (GY - 1), dz = (2 * YL) / (GZ - 1);
+    const NN = GX * GY * GZ;
+    const D = new Float32Array(NN);
+    const idx = (i, j, k) => (k * GY + j) * GX + i;
+    const gxp = (i) => -XL + i * dx, gyp = (j) => -YL + j * dy, gzp = (k) => -YL + k * dz;
+    for (let k = 0; k < GZ; k++)
+        for (let j = 0; j < GY; j++)
+            for (let i = 0; i < GX; i++)
+                D[idx(i, j, k)] = sdf(gxp(i), gyp(j), gzp(k));
+    const PS = new Float32Array(NN * 3);
+    for (let k = 0; k < GZ; k++)
+        for (let j = 0; j < GY; j++)
+            for (let i = 0; i < GX; i++) {
+                const o = idx(i, j, k);
+                const x = gxp(i), y = gyp(j), z = gzp(k);
+                // psi = (U x x) / 2 with U = (Ux, Uy, 0)
+                let px = 0.5 * (Uy * z), py = 0.5 * (-Ux * z), pz = 0.5 * (Ux * y - Uy * x);
+                const d = D[o];
+                const a = ramp(d / DELTA);
+                if (a < 1) {
+                    // normal from the distance field
+                    const i0 = Math.max(i - 1, 0), i1 = Math.min(i + 1, GX - 1), j0 = Math.max(j - 1, 0), j1 = Math.min(j + 1, GY - 1), k0 = Math.max(k - 1, 0), k1 = Math.min(k + 1, GZ - 1);
+                    let nx = (D[idx(i1, j, k)] - D[idx(i0, j, k)]) / ((i1 - i0) * dx);
+                    let ny = (D[idx(i, j1, k)] - D[idx(i, j0, k)]) / ((j1 - j0) * dy);
+                    let nz = (D[idx(i, j, k1)] - D[idx(i, j, k0)]) / ((k1 - k0) * dz);
+                    const nl = Math.hypot(nx, ny, nz) || 1;
+                    nx /= nl;
+                    ny /= nl;
+                    nz /= nl;
+                    const pn = px * nx + py * ny + pz * nz;
+                    px = a * px + (1 - a) * nx * pn;
+                    py = a * py + (1 - a) * ny * pn;
+                    pz = a * pz + (1 - a) * nz * pn;
+                }
+                PS[o * 3] = px;
+                PS[o * 3 + 1] = py;
+                PS[o * 3 + 2] = pz;
+            }
+    const V = new Float32Array(NN * 3); // unit-wind velocity field
+    for (let k = 0; k < GZ; k++)
+        for (let j = 0; j < GY; j++)
+            for (let i = 0; i < GX; i++) {
+                const o = idx(i, j, k);
+                const i0 = Math.max(i - 1, 0), i1 = Math.min(i + 1, GX - 1), j0 = Math.max(j - 1, 0), j1 = Math.min(j + 1, GY - 1), k0 = Math.max(k - 1, 0), k1 = Math.min(k + 1, GZ - 1);
+                const ddy = (c2) => (PS[idx(i, j1, k) * 3 + c2] - PS[idx(i, j0, k) * 3 + c2]) / ((j1 - j0) * dy);
+                const ddz = (c2) => (PS[idx(i, j, k1) * 3 + c2] - PS[idx(i, j, k0) * 3 + c2]) / ((k1 - k0) * dz);
+                const ddx = (c2) => (PS[idx(i1, j, k) * 3 + c2] - PS[idx(i0, j, k) * 3 + c2]) / ((i1 - i0) * dx);
+                V[o * 3] = ddy(2) - ddz(1);
+                V[o * 3 + 1] = ddz(0) - ddx(2);
+                V[o * 3 + 2] = ddx(1) - ddy(0);
+            }
+    const NG = new Float32Array(NN * 3); // outward normal of the distance field
+    for (let k = 0; k < GZ; k++)
+        for (let j = 0; j < GY; j++)
+            for (let i = 0; i < GX; i++) {
+                const o = idx(i, j, k);
+                const i0 = Math.max(i - 1, 0), i1 = Math.min(i + 1, GX - 1), j0 = Math.max(j - 1, 0), j1 = Math.min(j + 1, GY - 1), k0 = Math.max(k - 1, 0), k1 = Math.min(k + 1, GZ - 1);
+                let nx = (D[idx(i1, j, k)] - D[idx(i0, j, k)]) / ((i1 - i0) * dx);
+                let ny = (D[idx(i, j1, k)] - D[idx(i, j0, k)]) / ((j1 - j0) * dy);
+                let nz = (D[idx(i, j, k1)] - D[idx(i, j, k0)]) / ((k1 - k0) * dz);
+                const nl = Math.hypot(nx, ny, nz) || 1;
+                NG[o * 3] = nx / nl;
+                NG[o * 3 + 1] = ny / nl;
+                NG[o * 3 + 2] = nz / nl;
+            }
+    const W = new Float32Array(NN); // wake mask: behind the body, outside it
+    for (let k = 0; k < GZ; k++)
+        for (let j = 0; j < GY; j++)
+            for (let i = 0; i < GX; i++) {
+                const o = idx(i, j, k);
+                const x = gxp(i), y = gyp(j), z = gzp(k);
+                const along = x * Ux + y * Uy, ax = x - along * Ux, ay = y - along * Uy;
+                const across = Math.hypot(ax, ay, z);
+                const behind = Math.min(Math.max((along - 0.1) / 0.5, 0), 1);
+                W[o] = behind * Math.exp(-(across * across) / (0.75 * 0.75)) * ramp(D[o] / 0.25);
+            }
+    const sv = new Float32Array(8);
+    function sample(x, y, z) {
+        let fx = (x + XL) / dx, fy = (y + YL) / dy, fz = (z + YL) / dz;
+        if (fx < 0)
+            fx = 0;
+        else if (fx > GX - 1.001)
+            fx = GX - 1.001;
+        if (fy < 0)
+            fy = 0;
+        else if (fy > GY - 1.001)
+            fy = GY - 1.001;
+        if (fz < 0)
+            fz = 0;
+        else if (fz > GZ - 1.001)
+            fz = GZ - 1.001;
+        const i = fx | 0, j = fy | 0, k = fz | 0, tx = fx - i, ty = fy - j, tz = fz - k;
+        const o000 = (k * GY + j) * GX + i, o100 = o000 + 1, o010 = o000 + GX, o110 = o010 + 1;
+        const o001 = o000 + GX * GY, o101 = o001 + 1, o011 = o001 + GX, o111 = o011 + 1;
+        const w000 = (1 - tx) * (1 - ty) * (1 - tz), w100 = tx * (1 - ty) * (1 - tz), w010 = (1 - tx) * ty * (1 - tz), w110 = tx * ty * (1 - tz);
+        const w001 = (1 - tx) * (1 - ty) * tz, w101 = tx * (1 - ty) * tz, w011 = (1 - tx) * ty * tz, w111 = tx * ty * tz;
+        for (let cc = 0; cc < 3; cc++) {
+            sv[cc] = V[o000 * 3 + cc] * w000 + V[o100 * 3 + cc] * w100 + V[o010 * 3 + cc] * w010 + V[o110 * 3 + cc] * w110
+                + V[o001 * 3 + cc] * w001 + V[o101 * 3 + cc] * w101 + V[o011 * 3 + cc] * w011 + V[o111 * 3 + cc] * w111;
+        }
+        sv[3] = W[o000] * w000 + W[o100] * w100 + W[o010] * w010 + W[o110] * w110 + W[o001] * w001 + W[o101] * w101 + W[o011] * w011 + W[o111] * w111;
+        sv[4] = D[o000] * w000 + D[o100] * w100 + D[o010] * w010 + D[o110] * w110 + D[o001] * w001 + D[o101] * w101 + D[o011] * w011 + D[o111] * w111;
+        for (let cc = 0; cc < 3; cc++) {
+            sv[5 + cc] = NG[o000 * 3 + cc] * w000 + NG[o100 * 3 + cc] * w100 + NG[o010 * 3 + cc] * w010 + NG[o110 * 3 + cc] * w110
+                + NG[o001 * 3 + cc] * w001 + NG[o101 * 3 + cc] * w101 + NG[o011 * 3 + cc] * w011 + NG[o111 * 3 + cc] * w111;
+        }
+    }
+    // ---- tracers on a lattice of lanes upstream ----
+    const L = Math.max(2, Math.round(c.lanes));
+    const e1x = -Uy, e1y = Ux; // across the wind in the x-y plane (e2 = z)
+    // the rake: where the streams are released. tube = a ring of lanes round the body (the stream tube
+    // bulges round the shape), sheet = one vertical smoke rake, cross = a vertical and a horizontal rake
+    const rake = RAKES.includes(c.rake) ? c.rake : 'tube';
+    const laneA = new Float32Array(n), laneB = new Float32Array(n), phase = new Float32Array(n);
+    const perLane = Math.ceil(n / L);
+    for (let i = 0; i < n; i++) {
+        const l = i % L, k = Math.floor(i / L);
+        const f = (l + 0.5) / L;
+        if (rake === 'tube') {
+            laneA[i] = Math.cos(f * Math.PI * 2) * 0.62;
+            laneB[i] = Math.sin(f * Math.PI * 2) * 0.62;
+        }
+        else if (rake === 'sheet') {
+            laneA[i] = f * 2 - 1;
+            laneB[i] = (l % 2 ? 1 : -1) * 0.012;
+        } // a hair either side of the symmetry plane
+        else {
+            const g = ((l >> 1) + 0.5) / Math.ceil(L / 2) * 2 - 1;
+            if (l % 2 === 0) {
+                laneA[i] = g;
+                laneB[i] = 0;
+            }
+            else {
+                laneA[i] = 0;
+                laneB[i] = g;
+            }
+        }
+        phase[i] = (k + rng()) / perLane; // stratified along the lane, no synchronised fronts
+    }
+    const x = new Float32Array(n * 3), v = new Float32Array(n * 3), code = new Float32Array(n), fade = new Float32Array(n);
+    const hA = new Float32Array(n * 2), glow = new Float32Array(n);
+    const S0 = -XL * 0.95; // release plane, along the wind
+    let trail = null;
+    function release(i, frac) {
+        const w = u.uStreamWidth.value * YL * 0.95;
+        const a = laneA[i] * w, b = laneB[i] * w;
+        const along = S0 + frac * (2 * XL * 0.95);
+        x[i * 3] = along * Ux + a * e1x;
+        x[i * 3 + 1] = along * Uy + a * e1y;
+        x[i * 3 + 2] = b;
+        fade[i] = frac > 0.02 ? 1 : 0;
+        if (trail)
+            trail.reset(i);
+    }
+    let time = 0;
+    const P = new THREE.Vector3(), PV = new THREE.Vector3(), axis = new THREE.Vector3(0, 0, 1);
+    const vel = new Float32Array(3);
+    function velocity(px, py, pz, t, mode, S, Rp) {
+        sample(px, py, pz);
+        const Ug = U0 * u.uFlowSpeed.value;
+        let vx = sv[0] * Ug, vy = sv[1] * Ug, vz = sv[2] * Ug;
+        // skin of the body: a slip current along the surface carries tracers off the stagnation point, and
+        // anything that strays inside is pushed back out (tracers never pile up on the body)
+        const dd = sv[4];
+        if (dd < 0.15) {
+            const nx = sv[5], ny = sv[6], nz = sv[7];
+            if (dd < 0) {
+                // inside the body (only through grid leakage): straight back out
+                const out = Ug * (0.6 + 10 * -dd);
+                vx = nx * out;
+                vy = ny * out;
+                vz = nz * out;
+            }
+            else {
+                // impermeable skin: remove any inflow through the surface (the coarse grid leaks a little)
+                const vn = vx * nx + vy * ny + vz * nz;
+                const wgt = 1 - dd / 0.15;
+                if (vn < 0) {
+                    vx -= vn * nx * wgt;
+                    vy -= vn * ny * wgt;
+                    vz -= vn * nz * wgt;
+                }
+                // slip current along the skin carries tracers off the stagnation point
+                const un = Ux * nx + Uy * ny;
+                let tx = Ux - un * nx, ty = Uy - un * ny, tz = -un * nz;
+                if (Math.hypot(tx, ty, tz) < 0.35) {
+                    // head-on (a flat face or an edge square to the wind): go round the side the tracer is on,
+                    // i.e. away from the wind axis through the body, so a symmetric body splits the stream both ways
+                    const al = px * Ux + py * Uy;
+                    let rx = px - al * Ux, ry = py - al * Uy, rz = pz;
+                    const rn = rx * nx + ry * ny + rz * nz;
+                    rx -= rn * nx;
+                    ry -= rn * ny;
+                    rz -= rn * nz;
+                    const rl = Math.hypot(rx, ry, rz);
+                    if (rl > 1e-4) {
+                        tx += rx / rl * 0.8;
+                        ty += ry / rl * 0.8;
+                        tz += rz / rl * 0.8;
+                    }
+                }
+                const tn = Math.hypot(tx, ty, tz) || 1;
+                const g = 0.6 * Ug * wgt;
+                vx += tx / tn * g;
+                vy += ty / tn * g;
+                vz += tz / tn * g;
+                if (dd < 0.03) {
+                    const push = Ug * (0.03 - dd) * 30;
+                    vx += nx * push;
+                    vy += ny * push;
+                    vz += nz * push;
+                }
+            }
+        }
+        // wake eddies: an ABC flow carried with the wind, faded in behind the body
+        const tb = u.uTurbulence.value * sv[3];
+        if (tb > 0.002) {
+            const kk = 4.2, ph = t * Ug * kk;
+            const X = px * kk - ph, Y = py * kk, Z = pz * kk;
+            const A = 0.55 * Ug * tb;
+            vx += A * (Math.sin(Z + 0.3 * ph) + Math.cos(Y));
+            vy += A * (Math.sin(X) + Math.cos(Z + 0.3 * ph));
+            vz += A * (Math.sin(Y) + Math.cos(X));
+        }
+        // the cursor
+        if (S > 0.001) {
+            let ex = px - P.x, ey = py - P.y, ez = pz - P.z;
+            if (mode === 0) { // a sphere in potential flow: U + (a^3/2)(U/r^3 - 3(U.x)x/r^5)
+                const a = 0.22 * u.uPointerRadius.value * Math.min(S, 2);
+                const r2 = ex * ex + ey * ey + ez * ez, r = Math.sqrt(r2) + 1e-4;
+                if (r < 5 * a) {
+                    const ua = Ug * Ux, ub = Ug * Uy;
+                    const ud = ua * ex + ub * ey;
+                    const k3 = (a * a * a) / 2 / (r2 * r);
+                    vx += k3 * (ua - 3 * ud * ex / r2);
+                    vy += k3 * (ub - 3 * ud * ey / r2);
+                    vz += k3 * (-3 * ud * ez / r2);
+                    if (r < a * 1.02) {
+                        vx += ex / r * Ug * 2;
+                        vy += ey / r * Ug * 2;
+                        vz += ez / r * Ug * 2;
+                    } // never inside
+                }
+            }
+            else {
+                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));
+                    if (mode === 1) { // a puff along the cursor's motion
+                        vx += PV.x * 1.6 * S * g;
+                        vy += PV.y * 1.6 * S * g;
+                        vz += PV.z * 1.6 * S * g;
+                    }
+                    else { // line vortex (Rankine-softened)
+                        const G = 0.5 * S * Ug / (d2 / (Rp * Rp) + 0.15) * Math.min(1, 3 * g + 0.2);
+                        vx += (axis.y * ez - axis.z * ey) * G / Rp;
+                        vy += (axis.z * ex - axis.x * ez) * G / Rp;
+                        vz += (axis.x * ey - axis.y * ex) * G / Rp;
+                    }
+                }
+            }
+        }
+        vel[0] = vx;
+        vel[1] = vy;
+        vel[2] = vz;
+    }
+    function step(dt) {
+        time += dt;
+        const mode = u.uPointerMode.value;
+        const S = u.uPointerStrength.value * u.uPointerActive.value;
+        const Rp = 0.3 * u.uPointerRadius.value;
+        P.copy(u.uPointer.value);
+        PV.copy(u.uPointerVel.value);
+        const Ug = Math.max(U0 * u.uFlowSpeed.value, 1e-4);
+        for (let i = 0; i < n; i++) {
+            const j = i * 3;
+            const px = x[j], py = x[j + 1], pz = x[j + 2];
+            // RK2 (midpoint)
+            velocity(px, py, pz, time, mode, S, Rp);
+            const mx = px + vel[0] * dt * 0.5, my = py + vel[1] * dt * 0.5, mz = pz + vel[2] * dt * 0.5;
+            velocity(mx, my, mz, time + dt * 0.5, mode, S, Rp);
+            let nx = px + vel[0] * dt, ny = py + vel[1] * dt, nz = pz + vel[2] * dt;
+            v[j] = vel[0];
+            v[j + 1] = vel[1];
+            v[j + 2] = vel[2];
+            const along = nx * Ux + ny * Uy;
+            if (along > XL * 0.97 || Math.abs(nz) > YL || Math.abs(-nx * Uy + ny * Ux) > YL * 1.05) {
+                release(i, 0); // back to its lane at the release plane
+                continue;
+            }
+            x[j] = nx;
+            x[j + 1] = ny;
+            x[j + 2] = nz;
+            // fade in after release, out before the exit
+            const inF = Math.min((along - S0) / 0.25, 1), outF = Math.min((XL * 0.97 - along) / 0.35, 1);
+            fade[i] = Math.max(Math.min(inF, outF), 0);
+            // glow from the cursor (how much it is being pushed)
+            let gl = 0;
+            if (S > 0.001) {
+                const ex = nx - P.x, ey = ny - P.y, ez = nz - P.z;
+                gl = Math.exp(-(ex * ex + ey * ey + ez * ez) / (Rp * Rp * 1.5));
+            }
+            glow[i] += (gl - glow[i]) * Math.min(1, dt * 5);
+            const s = Math.min(Math.hypot(vel[0], vel[1], vel[2]) / (1.8 * Ug), 0.999);
+            code[i] = s + 2 * Math.round(Math.min(glow[i], 1) * 31);
+            hA[i * 2] = code[i];
+            hA[i * 2 + 1] = fade[i];
+        }
+    }
+    const hgeo = new THREE.BufferGeometry();
+    const xAttr = new THREE.BufferAttribute(x, 3).setUsage(THREE.DynamicDrawUsage);
+    const hAttr = new THREE.BufferAttribute(hA, 2).setUsage(THREE.DynamicDrawUsage);
+    hgeo.setAttribute('position', xAttr);
+    hgeo.setAttribute('aH', hAttr);
+    const hmat = new THREE.ShaderMaterial({
+        uniforms: u, vertexShader: headVertex, fragmentShader: HEAD_FRAG,
+        transparent: true, depthWrite: false, blending: THREE.AdditiveBlending,
+    });
+    const heads = new THREE.Points(hgeo, hmat);
+    heads.frustumCulled = false;
+    heads.renderOrder = 3;
+    attachViewH(heads, u);
+    const object = new THREE.Group();
+    const proxy = createPickProxy(BOUNDS.center, bR);
+    object.add(heads, proxy.mesh);
+    // streaklines carry the pressure colour; the fade (spawn / exit) is packed as brightness in k
+    const tk = new Float32Array(n);
+    const trailGLSL = /* glsl */ `
+${PRESSURE_GLSL}
+vec3 trailShade(vec3 p, float f) {
+  float lvl = floor(TRAIL_K / 64.0);
+  vec3 c = pressureLight(TRAIL_K - 64.0 * lvl);
+  c /= max(max(c.r, max(c.g, c.b)), 1.0);
+  return mix(c, uTrailColor, smoothstep(0.0, 0.7, f)) * (lvl / 15.0);
+}
+vec3 trailView(vec3 mv, out float mag) { mag = 1.0; return mv; }
+`;
+    let trailKey = '', look = 1;
+    const materials = [hmat];
+    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 = 1;
+        trail = createCpuTrail(mode, { u, n, pos: x, vel: v, k: tk, glsl: trailGLSL, sizePx: 0.01, spacing: 0.0015, sub: 8, alpha: TRAIL_ALPHA[mode] });
+        if (!trail)
+            return;
+        trail.object.renderOrder = 2;
+        object.add(trail.object);
+        materials.push(...trail.materials);
+    }
+    buildTrails(c.trailMode, c.trailShare);
+    function packTrails() {
+        for (let i = 0; i < n; i++)
+            tk[i] = Math.min(code[i], 63.9) + 64 * Math.round(fade[i] * 15);
+    }
+    // steady state from the start: every tracer is released at its lane and carried along its own
+    // streamline for its phase of the crossing time (coarse steps, no cursor)
+    {
+        const Ug = Math.max(U0 * u.uFlowSpeed.value, 1e-3);
+        const cross = (2 * XL * 0.95) / Ug;
+        const hs = 0.05;
+        for (let i = 0; i < n; i++) {
+            release(i, 0);
+            const j = i * 3;
+            const steps = Math.round((phase[i] * cross) / hs);
+            let t0 = 0;
+            for (let s2 = 0; s2 < steps; s2++) {
+                velocity(x[j], x[j + 1], x[j + 2], t0, -1, 0, 1);
+                const mx = x[j] + vel[0] * hs * 0.5, my = x[j + 1] + vel[1] * hs * 0.5, mz = x[j + 2] + vel[2] * hs * 0.5;
+                velocity(mx, my, mz, t0 + hs * 0.5, -1, 0, 1);
+                x[j] += vel[0] * hs;
+                x[j + 1] += vel[1] * hs;
+                x[j + 2] += vel[2] * hs;
+                t0 += hs;
+                if (x[j] * Ux + x[j + 1] * Uy > XL * 0.9)
+                    break;
+            }
+        }
+        time = 0;
+    }
+    const stepper = createFixedStep(H_STEP, 6);
+    for (let s = 0; s < 45; s++)
+        step(H_STEP);
+    packTrails();
+    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) {
+                packTrails();
+                xAttr.needsUpdate = true;
+                hAttr.needsUpdate = true;
+                if (trail)
+                    trail.update(simD / look);
+            }
+        },
+        seek(tt) { for (let s = 0; s < Math.round(tt / H_STEP); s++)
+            step(H_STEP); packTrails(); xAttr.needsUpdate = true; hAttr.needsUpdate = true; },
+        dispose() { hgeo.dispose(); hmat.dispose(); proxy.dispose(); if (trail)
+            trail.dispose(); },
+        _state: { x, code, V, D },
+    };
+}
+/** 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: '#3f7bff',
+    particleCount: 2400,
+    shape: { type: 'sphere', radius: 0.5, segments: 32, rings: 32 },
+    flowSpeed: 1,
+    windPitch: 0,
+    rake: 'sheet',
+    lanes: 44,
+    streamWidth: 0.85,
+    turbulence: 0.9,
+    fastColor: '#ff6a3d',
+    headSize: 1,
+    seed: 1,
+    quality: 'medium',
+    pointerMode: 'obstacle',
+    pointerStrength: 1,
+    pointerRadius: 1,
+    pointerColor: '#ffffff',
+    trailMode: 'comet',
+    trailLength: 1.2,
+    trailOpacity: 0.7,
+    trailColor: '#1b2a6b',
+    trailShare: 1,
+};
+/** Knobs that rebuild the simulation: they change on commit, never through the live path. */
+const STRUCTURAL = ['particleCount', 'shape', 'rake', 'lanes', 'windPitch', 'seed', 'quality'];
+/** Knobs an animation (or mouse move) may drive per frame — generated from applyConfig. */
+const ANIMATABLE = new Set(GENERATIVE_PARTICLES_ANIMATABLE.shapeFlow.map((p) => p.value));
+const ShapeFlowParticles = ({ 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.rake, cfg.lanes, cfg.windPitch, 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 ShapeFlowParticles;