@3driseai/3drise-viewer 0.1.28 → 0.1.30

package/dist/operations/catalogue/leafFall.js

@@ -0,0 +1,74 @@
+// Leaf fall — the object is light as a leaf. A gust lifts it and carries it off
+// downwind, gliding side to side the way a falling plate does: it swings across
+// the wind, rocks like a pendulum (most tilted at the ends of each swing, where
+// it turns), tips over a little at each turn and slowly yaws — growing smaller
+// as the wind takes it. The way back is a leaf settling: it flutters down from
+// above, the swings and the rocking dying away, and touches down softly.
+import { Quaternion, Vector3 } from 'three';
+import { clamp01, physicalExit, smooth } from './physicalExit.js';
+const _r = new Quaternion(), _p = new Quaternion(), _y = new Quaternion();
+const _wind = new Vector3(), _across = new Vector3();
+function axes(f, wind) {
+    if (wind === 'left')
+        _wind.copy(f.right).negate();
+    else if (wind === 'away')
+        _wind.copy(f.toward).negate();
+    else
+        _wind.copy(f.right);
+    _across.crossVectors(f.up, _wind).normalize(); // horizontal, across the wind
+}
+/** Rock about the wind (roll), tip over at the turns (pitch, about `across`), yaw slowly. */
+function attitude(out, a, roll, pitch, yaw) {
+    _r.setFromAxisAngle(_wind, roll);
+    _p.setFromAxisAngle(_across, pitch);
+    _y.setFromAxisAngle(a.frame.up, yaw);
+    out.q.copy(a.local(_r.multiply(_p).multiply(_y)));
+}
+export default physicalExit({
+    value: 'leafFall',
+    label: 'Leaf fall',
+    description: 'A gust lifts it and carries it away, gliding side to side and rocking like a falling leaf — it comes back fluttering down and settles softly',
+    params: {
+        wind: {
+            type: 'select', label: 'Wind', default: 'right', options: [
+                { value: 'right', label: 'To the right' }, { value: 'left', label: 'To the left' }, { value: 'away', label: 'Away' },
+            ], hint: 'Screen-relative when it starts',
+        },
+        swings: { type: 'number', label: 'Swings', default: 3, min: 1, max: 8, step: 0.5, hint: 'Side-to-side glides on the way' },
+        rock: { type: 'number', label: 'Rock', default: 32, min: 0, max: 75, step: 1, unit: '°', hint: 'How far it tilts at the end of a swing' },
+        drift: { type: 'number', label: 'Drift', default: 4, min: 0.5, max: 15, step: 0.25, hint: 'How far the wind carries it, × its size' },
+        duration: { type: 'number', label: 'Duration', default: 3.2, min: 0.6, max: 12, step: 0.05, unit: 's' },
+    },
+    exit(u, out, a) {
+        const p = a.p, H = a.size.y, span = a.span;
+        axes(a.frame, p.wind);
+        const n = Number(p.swings), rock = Number(p.rock) * Math.PI / 180;
+        const e = smooth(0, 0.18, u); // the gust takes hold
+        const ph = 2 * Math.PI * n * u;
+        const glide = Math.sin(ph); // −1..1 across the wind
+        const carry = Number(p.drift) * span * Math.pow(u, 1.7); // the wind picks it up and speeds it on
+        const lift = H * (0.75 * smooth(0, 0.45, u) - 0.3 * smooth(0.45, 1, u));
+        out.off.set(0, 0, 0)
+            .addScaledVector(_wind, carry)
+            .addScaledVector(_across, 0.45 * span * glide * e)
+            .addScaledVector(a.frame.up, lift);
+        // tilted most at the ends of a swing; tips over a little where it turns
+        attitude(out, a, -rock * glide * e, 0.35 * rock * Math.sin(2 * ph) * e, 0.7 * Math.PI * u * u);
+        out.s.setScalar(1 - smooth(0.5, 1, u));
+    },
+    enter(v, out, a) {
+        const p = a.p, H = a.size.y, span = a.span;
+        axes(a.frame, p.wind);
+        const n = Number(p.swings), rock = Number(p.rock) * Math.PI / 180;
+        const left = 1 - v;
+        const ph = 2 * Math.PI * n * v;
+        const glide = Math.sin(ph);
+        const die = Math.pow(left, 1.3); // the swings die away as it settles
+        out.off.set(0, 0, 0)
+            .addScaledVector(_wind, -0.8 * span * left * left) // drifts in from upwind
+            .addScaledVector(_across, 0.45 * span * glide * die)
+            .addScaledVector(a.frame.up, 2.6 * H * Math.pow(left, 1.6)); // slows as it comes down
+        attitude(out, a, -rock * glide * die, 0.35 * rock * Math.sin(2 * ph) * die, -0.5 * Math.PI * left * left);
+        out.s.setScalar(smooth(0, 0.2, clamp01(v)));
+    },
+});

package/dist/operations/catalogue/lidarScan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lidarScan.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/lidarScan.ts"],"names":[],"mappings":";AAuGA,wBAqJG"}
+{"version":3,"file":"lidarScan.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/lidarScan.ts"],"names":[],"mappings":";AAuGA,wBAwJG"}

package/dist/operations/catalogue/lidarScan.js

@@ -14,7 +14,7 @@
 import { AdditiveBlending, Color, DoubleSide, Mesh, PlaneGeometry, Quaternion, ShaderMaterial, Vector3 } from 'three';
 import { defineOperation } from '../types.js';
 import { addLayer, forEachMeshMaterial, removeLayer } from './shaderLayers.js';
-import { SWEEP_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, hideMeshes, localBounds, runProgress, setFieldParams, sweepVector, } from './transitionField.js';
+import { SWEEP_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, hideMeshes, localBounds, runProgress, setFieldParams, setReveal, sweepVector, } from './transitionField.js';
 import { sampleSurfaceCached } from './surfaceSample.js';
 import { GLSL_POINT_SIZE, createFxPoints, disposeFxPoints } from './fxPoints.js';
 import { hideUntilWarm } from './warmup.js';
@@ -104,6 +104,7 @@ export default defineOperation({
         disappear: { type: 'boolean', label: 'Disappear', default: true, hint: 'Off: the object stays in scanned mode — mesh and point cloud' },
     },
     objectParams: { disappear: false },
+    presence: 'paint',
     apply(target, p, ctx) {
         let st = target.userData[STATE];
         if (!st) {
@@ -167,6 +168,7 @@ export default defineOperation({
                   float a = LdrAlong(vLdrQ);
                   float s1 = ldrFront(0.0), s2 = ldrFront(${MESH.toFixed(2)});
                   if (a < s2) discard;                                  // only the point cloud is left
+                  if (uLdrReveal > 0.5 && a >= s1) discard;             // revealed by the laser: nothing ahead of it
                   float on = step(0.0001, uLdrProgress) * step(uLdrProgress, ${(END - 0.0001).toFixed(4)});
                   if (a < s1) {
                     // the reconstructed mesh: lattice lines only, dimming as it goes
@@ -221,6 +223,7 @@ export default defineOperation({
         if (!s)
             return;
         hideMeshes(target, KEY, false);
+        setReveal(s.field, p);
         s.points.visible = true;
         const sheetOn = p.sheet !== false;
         // from a hold it only has part of the way to go: keep the same speed

package/dist/operations/catalogue/liquidMetal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"liquidMetal.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/liquidMetal.ts"],"names":[],"mappings":";AA6EA,wBA8CG"}
+{"version":3,"file":"liquidMetal.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/liquidMetal.ts"],"names":[],"mappings":";AAgGA,wBAwDG"}

package/dist/operations/catalogue/liquidMetal.js

@@ -2,6 +2,9 @@
 // from the top down and flows out into a puddle on the ground (higher parts
 // travel further), with slow ripples running across the pool while it lies
 // there. Reverting pulls it back up into shape and the chrome fades off.
+// With Disappear off (an object effect's default) the object turns to chrome and
+// stays, unmelted: the studio reflection turns slowly, a soft ripple runs over it.
+// The chrome comes in along a front (Direction) so it can paint the object in.
 //
 // The chrome is a procedural studio environment (sky gradient, horizon band,
 // two soft boxes) reflected about the surface normal, so it reads as metal in
@@ -11,22 +14,25 @@ import { gsap } from 'gsap';
 import { Color } from 'three';
 import { defineOperation } from '../types.js';
 import { addLayer, forEachMeshMaterial, removeLayer } from './shaderLayers.js';
-import { createFieldState, fieldGlsl, fieldUniforms, runProgress, syncRoot } from './transitionField.js';
+import { DIRECTION_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, runProgress, setFieldParams, setReveal, syncRoot } from './transitionField.js';
 const P = 'Liq';
 const KEY = 'liquidMetal';
 const STATE = '__opLiquid';
+/** The chrome comes in over this much of the progress; the melt runs after it. */
+const CHROME = 0.2;
 function layerFor(st) {
     return {
-        uniforms: { ...fieldUniforms(P, st.field), uLiqTint: st.tint, uLiqSpread: st.spread },
-        common: `varying float vLiqM;\nvarying vec3 vLiqView;\n${fieldGlsl(P)}`,
+        uniforms: { ...fieldUniforms(P, st.field), uLiqTint: st.tint, uLiqSpread: st.spread, uLiqKeep: st.keep },
+        common: `varying float vLiqM;\nvarying vec3 vLiqView;\nvarying vec3 vLiqQ;\n${fieldGlsl(P)}`,
         vertex: /* glsl */ `
         {
           mat4 toRoot = uLiqRootInv * modelMatrix;
           vec3 rl = (toRoot * vec4(transformed, 1.0)).xyz;
           vec3 q = LiqNorm(rl);
+          vLiqQ = q;
           float E = uLiqExtent;
-          // melt runs after the chrome has come in; the top gives way first
-          float mp = clamp((uLiqProgress - 0.18) / 0.82, 0.0, 1.0);
+          // melt runs after the chrome has come in; the top gives way first (never in keep)
+          float mp = clamp((uLiqProgress - 0.18) / 0.82, 0.0, 1.0) * (1.0 - uLiqKeep);
           float wob = 0.12 * (fxNoise(q * 4.0) - 0.5);
           float m = clamp(mp * 1.3 - (1.0 - q.y) * 0.3 + wob, 0.0, 1.0);
           m = m * m;   // slow start: it sags before it runs
@@ -48,7 +54,13 @@ function layerFor(st) {
         }`,
         fragment: /* glsl */ `
         {
-          float chrome = smoothstep(0.0, 0.2, uLiqProgress);
+          // the chrome comes in along a front over the first part of the progress
+          float tc = clamp(uLiqProgress / ${CHROME}, 0.0, 1.0) * (1.0 + 2.0 * uLiqEdgeWidth) - uLiqEdgeWidth;
+          float d = LiqField(vLiqQ) - tc;
+          float chrome = smoothstep(0.0, 0.08, -d);
+          // painting the object in: nothing ahead of the front, full chrome right behind it
+          if (uLiqReveal > 0.5) { if (d > 0.0) discard; chrome = 1.0; }
+          float held = uLiqKeep * step(0.9999, uLiqProgress);
           vec3 nv = normalize(cross(dFdx(vLiqView), dFdy(vLiqView)));
           #if defined( STANDARD ) || defined( PHONG ) || defined( LAMBERT ) || defined( TOON )
             vec3 n = normalize(mix(normal, nv, smoothstep(0.05, 0.5, vLiqM)));
@@ -56,8 +68,12 @@ function layerFor(st) {
             vec3 n = nv;
           #endif
           vec3 v = normalize(vLiqView);
+          // holding as chrome: a soft ripple runs over the surface, the studio turns slowly
+          n = normalize(n + held * 0.04 * vec3(sin(vLiqQ.y * 22.0 - uLiqTime * 1.6), 0.0, cos(vLiqQ.x * 19.0 - uLiqTime * 1.3)));
           vec3 rv = reflect(v, n);
           vec3 rw = normalize((vec4(rv, 0.0) * viewMatrix).xyz);   // view → world direction
+          float ra = held * uLiqTime * 0.25;
+          rw = vec3(rw.x * cos(ra) - rw.z * sin(ra), rw.y, rw.x * sin(ra) + rw.z * cos(ra));
           // studio: dark floor, bright sky, a crisp horizon band and two soft boxes
           float up = rw.y;
           vec3 env = mix(vec3(0.05), vec3(0.85, 0.9, 1.0), smoothstep(-0.15, 0.6, up));
@@ -66,6 +82,8 @@ function layerFor(st) {
           env += vec3(1.2) * smoothstep(0.9, 0.98, dot(rw, normalize(vec3(-0.7, 0.35, -0.3))));
           float fres = 0.65 + 0.35 * pow(1.0 - abs(dot(n, -v)), 3.0);
           vec3 metal = uLiqTint * env * fres;
+          // a bright lip right at the front
+          metal *= 1.0 + 1.5 * (1.0 - smoothstep(0.0, 0.05, abs(d))) * step(0.0001, uLiqProgress) * step(uLiqProgress, ${CHROME} - 0.0001);
           outgoingLight = mix(outgoingLight, metal, chrome);
         }`,
     };
@@ -73,21 +91,26 @@ function layerFor(st) {
 export default defineOperation({
     value: 'liquidMetal',
     label: 'Liquid metal',
-    description: 'Turn the targets to chrome and melt them into a rippling pool — reverting pulls them back into shape',
+    description: 'Turn the targets to chrome and melt them into a rippling pool (or, Disappear off, keep them as chrome) — reverting pulls them back into shape',
     channel: 'visual',
     multi: true,
     toggles: true,
-    usableIn: ['interaction', 'action'],
+    usableIn: ['interaction', 'action', 'object'],
+    objectParams: { disappear: false },
+    presence: 'paint',
     params: {
+        direction: { type: 'select', label: 'Direction', default: 'up', options: DIRECTION_OPTIONS, hint: 'How the chrome comes in' },
         tint: { type: 'color', label: 'Metal', default: '#dfe7ee' },
-        spread: { type: 'number', label: 'Pool size', default: 1, min: 0.2, max: 3, step: 0.05, unit: '×' },
+        disappear: { type: 'boolean', label: 'Disappear', default: true, hint: 'Off: the object turns to chrome and stays' },
+        spread: { type: 'number', label: 'Pool size', default: 1, min: 0.2, max: 3, step: 0.05, unit: '×', showWhen: { disappear: ['true'] } },
         duration: { type: 'number', label: 'Duration', default: 3.4, min: 0.3, max: 12, step: 0.1, unit: 's' },
     },
-    apply(target, p) {
+    apply(target, p, ctx) {
         let st = target.userData[STATE];
         if (!st) {
             const field = createFieldState(target);
-            const own = { field, tint: { value: new Color() }, spread: { value: 1 }, mats: new Set() };
+            field.edgeWidth.value = 0.04;
+            const own = { field, tint: { value: new Color() }, spread: { value: 1 }, keep: { value: 0 }, mats: new Set() };
             // ripples keep moving while it lies melted
             own.tick = () => { own.field.time.value += gsap.ticker.deltaRatio() / 60; syncRoot(target, own.field); };
             const layer = layerFor(own);
@@ -102,16 +125,22 @@ export default defineOperation({
             target.userData[STATE] = st;
         }
         const s = st;
+        setFieldParams(s.field, p, target, ctx);
         s.tint.value.set(String(p.tint));
         s.spread.value = Number(p.spread);
+        s.keep.value = p.disappear === false ? 1 : 0;
+        // keep: only the chrome comes in (the melt is off), then it holds — its own ticker keeps the time running
+        if (s.keep.value)
+            return runProgress(target, s.field, 1, { duration: Number(p.duration) * CHROME * 1.5, ease: 'none', clock: false });
         return runProgress(target, s.field, 1, { duration: Number(p.duration), ease: 'power1.inOut', clock: false });
     },
     revert(target, p) {
         const s = target.userData[STATE];
         if (!s)
             return;
+        setReveal(s.field, p);
         return runProgress(target, s.field, 0, {
-            duration: Number(p.duration), ease: 'power1.inOut', clock: false,
+            duration: Number(p.duration) * (s.keep.value ? CHROME * 1.5 : 1) * Math.min(1, Math.max(0.1, s.field.progress.value)), ease: s.keep.value ? 'none' : 'power1.inOut', clock: false,
             onComplete: () => {
                 gsap.ticker.remove(s.tick);
                 s.mats.forEach(m => removeLayer(m, KEY));

package/dist/operations/catalogue/metalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metalize.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/metalize.ts"],"names":[],"mappings":";AA8EA,wBA4DG"}
+{"version":3,"file":"metalize.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/metalize.ts"],"names":[],"mappings":";AAiFA,wBA+DG"}

package/dist/operations/catalogue/metalize.js

@@ -11,7 +11,7 @@
 import { Color } from 'three';
 import { defineOperation } from '../types.js';
 import { addLayer, forEachMeshMaterial, removeLayer } from './shaderLayers.js';
-import { DIRECTION_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, runProgress, setFieldParams } from './transitionField.js';
+import { DIRECTION_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, goneGlsl, runProgress, setFieldParams, setReveal } from './transitionField.js';
 const P = 'Mtl';
 const KEY = 'metalize';
 const STATE = '__opMetalize';
@@ -24,7 +24,7 @@ const DEFAULT_CUSTOM = '#9fd0ff';
 function layerFor(st) {
     return {
         uniforms: { ...fieldUniforms(P, st.field), uMtlTint: st.tint, uMtlRough: st.rough, uMtlIrid: st.irid, uMtlLip: st.lip, uMtlCool: st.cool },
-        common: `varying vec3 vMtlQ;\nvarying vec3 vMtlR;\nvarying vec3 vMtlView;\n${fieldGlsl(P)}`,
+        common: `varying vec3 vMtlQ;\nvarying vec3 vMtlR;\nvarying vec3 vMtlView;\n${fieldGlsl(P)}\n${goneGlsl(P)}`,
         vertex: /* glsl */ `
         vMtlR = (uMtlRootInv * modelMatrix * vec4(transformed, 1.0)).xyz;
         vMtlQ = MtlNorm(vMtlR);
@@ -33,6 +33,9 @@ function layerFor(st) {
         {
           float d = MtlThreshold() - MtlField(vMtlQ);          // > 0 behind the front
           float m = smoothstep(0.0, uMtlEdgeWidth, d);
+          // revealed by the metal: nothing ahead of the front, full metal right behind it
+          if (uMtlReveal > 0.5) { if (d < 0.0) discard; m = 1.0; }
+          if (MtlGone(vMtlQ) > 0.5) { m = 0.0; d = -1.0; }    // wiped by the look that replaces it
           if (m > 0.0 || d > -0.05) {
             vec3 nv = normalize(cross(dFdx(vMtlView), dFdy(vMtlView)));
             #if defined( STANDARD ) || defined( PHONG ) || defined( LAMBERT ) || defined( TOON )
@@ -77,6 +80,8 @@ export default defineOperation({
     multi: true,
     toggles: true,
     usableIn: ['interaction', 'action', 'object'],
+    presence: 'paint',
+    field: (target) => target.userData[STATE]?.field,
     stack: 'surface',
     params: {
         metal: {
@@ -127,6 +132,7 @@ export default defineOperation({
         const s = target.userData[STATE];
         if (!s)
             return;
+        setReveal(s.field, p);
         return runProgress(target, s.field, 0, {
             duration: Number(p.duration), ease: 'power1.inOut',
             onComplete: () => { s.mats.forEach(m => removeLayer(m, KEY)); delete target.userData[STATE]; },

package/dist/operations/catalogue/motionTrail.d.ts

@@ -0,0 +1,6 @@
+import type { OperationDefinition } from '../types';
+/** Sample and draw every trail now (the ticker does this every frame; tests stepping time call it by hand). */
+export declare function tickTrails(): void;
+/** Every trail, in gallery order. */
+export declare const TRAILS: OperationDefinition[];
+//# sourceMappingURL=motionTrail.d.ts.map

package/dist/operations/catalogue/motionTrail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"motionTrail.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/motionTrail.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,mBAAmB,EAAsB,MAAM,UAAU,CAAC;AAOxE,+GAA+G;AAC/G,wBAAgB,UAAU,SAAiB;AA4I3C,qCAAqC;AACrC,eAAO,MAAM,MAAM,EAAE,mBAAmB,EA6BvC,CAAC"}

package/dist/operations/catalogue/motionTrail.js

@@ -0,0 +1,221 @@
+// Motion trails — add-ons that draw where the object has just been, whatever moves it:
+// physical effects, clips, held motions, a drag in the studio. A trail watches the
+// object's own world transform (trailCore: a short history, smoothed velocity and
+// acceleration, sampled every frame on gsap's clock) — no other effect knows about it.
+//
+// One effect per style, all on this one engine and ONE settings API (the agent and the
+// studio see the same shape for every trail):
+//   length · amount · size · opacity (Strength) · color · color2 (· color3) · duration (Fade)
+// Length is how long it lasts, Amount how much of it, Size how big — each style scales
+// them; the colours mean "main" and "what it turns / fades into" in every style.
+// Each trail keeps its own state (`__opTrail_<style>`), so trails combine on one object.
+//
+//   afterimageTrail     fading Fresnel copies of the object along its path        trailGhosts
+//   longExposureTrail   a dense smear of faint copies — a long-exposure photo      trailGhosts
+//   chromaticEchoTrail  red / green / blue copies a beat apart: fringe → white     trailGhosts
+//   streaksTrail        crisp light ribbons from points spread over its surface    trailStreaks
+// Stamp trails — copies of the object left where it was, each turning into something
+// and going away in place (trailStamps.ts + trailStampStyles.ts):
+//   smoke, ash, hologram, ink, frost (its own meshes, new shaders)
+//   sand (surface grains), voxel (cubes), shatter (its triangles as Voronoi shards),
+//   wireframe (its real edges), bubbles
+//
+// Everything lives in the SCENE (not under the object): an exit hides the object and
+// the trail must keep going after it is gone. Built, compiled in the background
+// (hideUntilWarm / warmHelpers), then faded in; switched off it fades out, waits for
+// particles still in flight to finish, and is removed.
+import { gsap } from 'gsap';
+import { Color, Group, Matrix4, Vector3 } from 'three';
+import { defineOperation } from '../types.js';
+import { hideUntilWarm, warmHelpers, warmMode } from './warmup.js';
+import { cameraPos, measure, newHistory, record } from './trailCore.js';
+import { afterimage, chromaticEcho, longExposure } from './trailGhosts.js';
+import { streaks } from './trailStreaks.js';
+import { ash, bubbles, frost, hologram, ink, sand, shatter, smoke, voxel, wireframe } from './trailStampStyles.js';
+// one ticker for every trail; time is gsap's own clock (follows the global time scale)
+const active = new Set();
+const tickAll = () => active.forEach(t => t());
+/** Sample and draw every trail now (the ticker does this every frame; tests stepping time call it by hand). */
+export function tickTrails() { tickAll(); }
+const clock = () => gsap.globalTimeline.time();
+function paramsOf(style, p, prev) {
+    // colour settings are sRGB hex; Color converts them to the linear working space
+    const col = (v, old) => (old ?? new Color()).set(String(v));
+    return {
+        style,
+        length: Number(p.length),
+        amount: Number(p.amount),
+        size: Number(p.size),
+        opacity: Number(p.opacity),
+        color: col(p.color, prev?.color), color2: col(p.color2, prev?.color2), color3: col(p.color3 ?? p.color2, prev?.color3),
+    };
+}
+/** What a trail is built for — a change here rebuilds it (the others apply live). */
+const shapeKey = (p) => `${Math.round(Number(p.amount) * 20)}`;
+function build(KEY, styleName, style, target, p) {
+    const group = new Group();
+    group.name = `trail:${styleName}`;
+    group.userData.__opFxHelper = true;
+    group.matrixAutoUpdate = false;
+    let root = target;
+    while (root.parent)
+        root = root.parent;
+    root.add(group);
+    const { span, floor } = measure(target);
+    const ctx = {
+        target, group, env: { v: 0 }, p: paramsOf(styleName, p), span, floor,
+        hist: newHistory(), head: 0, count: 0, now: clock(), dt: 0,
+        vel: new Vector3(), acc: new Vector3(), speed: 0, world: new Matrix4(), cam: null,
+    };
+    style.build(ctx);
+    hideUntilWarm(group);
+    const camAt = new Vector3();
+    const st = { ctx, style, shape: shapeKey(p), tick: () => undefined };
+    st.tick = () => {
+        if (!target.parent) {
+            dispose(KEY, target);
+            return;
+        } // the object left the scene
+        ctx.cam = cameraPos(camAt);
+        record(ctx, clock());
+        style.update(ctx);
+    };
+    return st;
+}
+function dispose(KEY, target) {
+    const st = target.userData[KEY];
+    if (!st)
+        return;
+    active.delete(st.tick);
+    if (!active.size)
+        gsap.ticker.remove(tickAll);
+    gsap.killTweensOf(st.ctx.env);
+    st.resolve?.();
+    st.style.dispose?.(st.ctx);
+    st.ctx.group.removeFromParent();
+    delete target.userData[KEY];
+}
+/** Resolves once the style has nothing left in flight (or after `max` seconds). */
+function settled(st, max) {
+    return new Promise(resolve => {
+        const t0 = performance.now();
+        const check = () => {
+            if (!st.style.alive?.(st.ctx) || performance.now() - t0 > max * 1000) {
+                gsap.ticker.remove(check);
+                resolve();
+            }
+        };
+        gsap.ticker.add(check);
+    });
+}
+/** One trail effect: a style on the shared engine, with the shared settings. */
+function trail(spec) {
+    const KEY = `__opTrail_${spec.style}`;
+    const value = `${spec.style}Trail`;
+    const c = (s) => ({ type: 'color', label: s.label, default: s.default, ...(s.hint ? { hint: s.hint } : {}) });
+    return defineOperation({
+        value, label: spec.label,
+        description: `${spec.description} — wherever the object moves (physical effects, clips, a drag); nothing while it stands still. Combines with other trails`,
+        channel: 'visual',
+        multi: true,
+        toggles: true,
+        usableIn: ['interaction', 'action', 'object'],
+        addOn: true, // on before an entrance, off after an exit (Follows visibility)
+        params: {
+            length: { type: 'number', label: 'Length', default: 0.35, min: 0.05, max: 2, step: 0.01, unit: 's', hint: 'How long the trail lasts' },
+            amount: { type: 'number', label: 'Amount', default: 0.35, min: 0, max: 1, step: 0.01, hint: 'How much of it — copies, ribbons, grains' },
+            size: { type: 'number', label: 'Size', default: 0.35, min: 0, max: 1, step: 0.01, hint: 'Width, grain size, how far it spreads' },
+            opacity: { type: 'number', label: 'Strength', default: 0.7, min: 0.05, max: 2, step: 0.05 },
+            color: c(spec.color),
+            color2: c(spec.color2),
+            ...(spec.color3 ? { color3: c(spec.color3) } : {}),
+            duration: { type: 'number', label: 'Fade', default: 0.35, min: 0, max: 3, step: 0.05, unit: 's', hint: 'How long it takes to switch on and off' },
+        },
+        apply(target, p) {
+            let st = target.userData[KEY];
+            if (st && st.shape !== shapeKey(p)) {
+                dispose(KEY, target);
+                st = undefined;
+            } // a different build: made again
+            if (!st) {
+                st = build(KEY, spec.style, spec.impl, target, p);
+                target.userData[KEY] = st;
+                if (!active.size)
+                    gsap.ticker.add(tickAll);
+                active.add(st.tick);
+            }
+            const s = st;
+            s.ending = false;
+            s.ctx.p = paramsOf(spec.style, p, s.ctx.p);
+            const ready = warmHelpers(s.ctx.group);
+            if (warmMode.on)
+                return ready; // a warm-only run: compiled, nothing shown
+            return ready.then(() => new Promise(resolve => {
+                gsap.killTweensOf(s.ctx.env);
+                s.resolve?.();
+                s.resolve = resolve;
+                const D = Number(p.duration) * (1 - s.ctx.env.v);
+                if (D <= 1e-4) {
+                    s.ctx.env.v = 1;
+                    s.resolve = undefined;
+                    resolve();
+                    return;
+                }
+                gsap.to(s.ctx.env, { v: 1, duration: D, ease: 'power1.out', onComplete: () => { s.resolve = undefined; resolve(); } });
+            }));
+        },
+        revert(target, p) {
+            const st = target.userData[KEY];
+            if (!st)
+                return;
+            gsap.killTweensOf(st.ctx.env);
+            st.resolve?.();
+            const D = Number(p.duration) * st.ctx.env.v;
+            if (D <= 1e-4) {
+                dispose(KEY, target);
+                return;
+            }
+            st.ending = true;
+            return new Promise(resolve => {
+                st.resolve = resolve;
+                gsap.to(st.ctx.env, {
+                    v: 0, duration: D, ease: 'power1.in',
+                    // particles still in flight finish (up to 4 s), then it is removed — unless switched on again meanwhile
+                    onComplete: () => { void settled(st, 4).then(() => { if (st.ending && target.userData[KEY] === st)
+                        dispose(KEY, target); resolve(); }); },
+                });
+            });
+        },
+    });
+}
+/** Every trail, in gallery order. */
+export const TRAILS = [
+    trail({ style: 'afterimage', impl: afterimage, label: 'Afterimage trail', description: 'Fading glassy copies of the object along its path',
+        color: { label: 'Colour', default: '#bfe6ff' }, color2: { label: 'Tail colour', default: '#7d5cff', hint: 'The colour it fades into' } }),
+    trail({ style: 'longExposure', impl: longExposure, label: 'Long exposure', description: 'A dense smear of faint copies, like a long-exposure photo',
+        color: { label: 'Colour', default: '#bfe6ff' }, color2: { label: 'Tail colour', default: '#7d5cff', hint: 'The colour it fades into' } }),
+    trail({ style: 'chromaticEcho', impl: chromaticEcho, label: 'Chromatic echo', description: 'Three coloured copies a beat apart — a fringe that adds up to white',
+        color: { label: 'First echo', default: '#ff2b1c', hint: 'Three colours that add up to white' }, color2: { label: 'Second echo', default: '#22ff4e' }, color3: { label: 'Third echo', default: '#2b5cff' } }),
+    trail({ style: 'streaks', impl: streaks, label: 'Light streaks', description: 'Crisp light ribbons drawn from points over its surface',
+        color: { label: 'Colour', default: '#bfe6ff' }, color2: { label: 'Tail colour', default: '#7d5cff', hint: 'The colour it fades into' } }),
+    trail({ style: 'smoke', impl: smoke, label: 'Smoke trail', description: 'Copies of the object left behind turn to smoke in its shape, billow up and evaporate',
+        color: { label: 'Smoke colour', default: '#e4e8ee', hint: 'Where light falls on it' }, color2: { label: 'Shade colour', default: '#5d6673', hint: 'Its underside' } }),
+    trail({ style: 'ash', impl: ash, label: 'Ash trail', description: 'Copies left behind burn from within along a glowing ember front, and are gone',
+        color: { label: 'Ash colour', default: '#8d8a86' }, color2: { label: 'Ember colour', default: '#ff7a1f', hint: 'The glowing front' } }),
+    trail({ style: 'sand', impl: sand, label: 'Sand trail', description: 'Copies left behind fall apart into grains that pour down into a little heap',
+        color: { label: 'Sand colour', default: '#dcc59c' }, color2: { label: 'Dark grains', default: '#8a6f4a', hint: 'Grains vary between the two' } }),
+    trail({ style: 'hologram', impl: hologram, label: 'Hologram trail', description: 'Copies left behind as holograms that glitch out band by band',
+        color: { label: 'Hologram colour', default: '#45dcff' }, color2: { label: 'Grid colour', default: '#e6fbff', hint: 'Grid lines and the rim' } }),
+    trail({ style: 'voxel', impl: voxel, label: 'Voxel trail', description: 'Copies left behind as cubes that drop from the top, tumble and shrink away',
+        color: { label: 'Voxel colour', default: '#7cc4ff' }, color2: { label: 'Edge colour', default: '#f2f9ff' } }),
+    trail({ style: 'shatter', impl: shatter, label: 'Shatter trail', description: 'Copies left behind cut into glass shards from its own triangles, drifting apart',
+        color: { label: 'Shard colour', default: '#b9d6ff' }, color2: { label: 'Rim colour', default: '#ffffff', hint: 'The light along its edges' } }),
+    trail({ style: 'ink', impl: ink, label: 'Ink trail', description: 'Copies left behind swirl into ink in water and tear into filaments',
+        color: { label: 'Ink colour', default: '#1b2c80' }, color2: { label: 'Bleed colour', default: '#8fb0ff', hint: 'Where it thins out' } }),
+    trail({ style: 'frost', impl: frost, label: 'Frost trail', description: 'Copies left behind frost over, crack open and melt away',
+        color: { label: 'Ice colour', default: '#cdeeff' }, color2: { label: 'Rim colour', default: '#ffffff', hint: 'Its rim and cracks' } }),
+    trail({ style: 'wireframe', impl: wireframe, label: 'Wireframe trail', description: 'Copies left behind as its real mesh edges, each retracting into its middle',
+        color: { label: 'Wire colour', default: '#7ff0ff' }, color2: { label: 'Fade colour', default: '#7a5cff', hint: 'The colour it ages into' } }),
+    trail({ style: 'bubbles', impl: bubbles, label: 'Bubble trail', description: 'Soap bubbles form over copies of it, rise, wobble and pop',
+        color: { label: 'Bubble colour', default: '#bfeaff' }, color2: { label: 'Sheen colour', default: '#ff9fd8', hint: 'The soap-film colour sliding over each bubble' } }),
+];

package/dist/operations/catalogue/particleSwarm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particleSwarm.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/particleSwarm.ts"],"names":[],"mappings":";AAiCA,wBAsGG"}
+{"version":3,"file":"particleSwarm.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/particleSwarm.ts"],"names":[],"mappings":";AAoCA,wBAwHG"}