@3driseai/3drise-viewer 0.1.28 → 0.1.29

package/dist/operations/catalogue/grow.js

@@ -0,0 +1,19 @@
+// Grow — the object scales up (or down) and stays there, with a small overshoot
+// as it arrives. From its base (it stays on the ground) or from its centre.
+import { DURATION, heldPhysical } from './physicalHeld.js';
+export default heldPhysical({
+    value: 'grow', label: 'Grow',
+    description: 'Scale up (or down) and stay — settles with a small overshoot; switching off brings it back',
+    ease: 'back.out(1.5)',
+    periodic: false,
+    params: {
+        scale: { type: 'number', label: 'Size', default: 1.25, min: 0.05, max: 5, step: 0.05, unit: '×' },
+        from: { type: 'select', label: 'From', default: 'base', options: [{ value: 'base', label: 'Its base' }, { value: 'center', label: 'Its centre' }] },
+        duration: { ...DURATION, default: 0.6, max: 6, hint: 'How long it takes to arrive, and to go back' },
+    },
+    memory: () => null,
+    move(part, st) {
+        part.s.setScalar(Math.max(0.001, 1 + (Number(st.p.scale) - 1) * st.amp.v));
+        part.pivot.copy(st.p.from === 'center' ? st.body.centerLocal : st.body.bottomLocal);
+    },
+});

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

@@ -1 +1 @@
-{"version":3,"file":"hologram.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/hologram.ts"],"names":[],"mappings":";AAgBA,wBAsFG"}
+{"version":3,"file":"hologram.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/hologram.ts"],"names":[],"mappings":";AAgBA,wBA4FG"}

package/dist/operations/catalogue/hologram.js

@@ -5,7 +5,7 @@
 // Reverting scans it back in: hologram first, then solid.
 import { defineOperation } from '../types.js';
 import { addLayer, forEachMeshMaterial, removeLayer } from './shaderLayers.js';
-import { SWEEP_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, runProgress, setFieldParams } from './transitionField.js';
+import { SWEEP_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, goneGlsl, runProgress, setFieldParams, setReveal } from './transitionField.js';
 import { Color } from 'three';
 const P = 'Holo';
 const KEY = 'hologram';
@@ -19,6 +19,8 @@ export default defineOperation({
     toggles: true,
     usableIn: ['interaction', 'action', 'object'],
     objectParams: { disappear: false },
+    presence: 'paint',
+    field: (target) => target.userData[STATE]?.field,
     params: {
         direction: { type: 'select', label: 'Scan', default: 'down', options: SWEEP_OPTIONS },
         color: { type: 'color', label: 'Colour', default: '#3fd4ff' },
@@ -35,7 +37,7 @@ export default defineOperation({
             const own = st;
             const layer = {
                 uniforms: { ...fieldUniforms(P, field), uHoloColor: st.color, uHoloDensity: st.density, uHoloGap: st.gap, uHoloKeep: st.keep },
-                common: `varying vec3 vHoloR;\nvarying vec3 vHoloView;\n${fieldGlsl(P)}`,
+                common: `varying vec3 vHoloR;\nvarying vec3 vHoloView;\n${fieldGlsl(P)}\n${goneGlsl(P)}`,
                 vertex: /* glsl */ `
                 vHoloR = (uHoloRootInv * modelMatrix * vec4(transformed, 1.0)).xyz;
                 vHoloView = (modelViewMatrix * vec4(transformed, 1.0)).xyz;`,
@@ -48,8 +50,10 @@ export default defineOperation({
                   float fa = mix(-band, 1.0 + uHoloGap + band, clamp(uHoloProgress, 0.0, 1.0)); // solid → hologram
                   // hologram → gone (never, when the object should stay as a hologram)
                   float fb = uHoloKeep > 0.5 ? -1.0 : fa - uHoloGap;
-                  if (s < fb) discard;
-                  if (s < fa) {
+                  float gone = HoloGone(q);                   // wiped by the look that replaces it
+                  if (gone < 0.5 && s < fb) discard;
+                  if (gone > 0.5) {
+                  } else if (s < fa) {
                     // grid in root-local units, square cells, anti-aliased
                     vec3 cell = vHoloR * (uHoloDensity / uHoloExtent);
                     vec3 g = abs(fract(cell - 0.5) - 0.5) / max(fwidth(cell), vec3(1e-4));
@@ -64,6 +68,7 @@ export default defineOperation({
                     if (I < 0.32) discard;
                     outgoingLight = uHoloColor * I * 1.6;
                   } else {
+                    if (uHoloReveal > 0.5) discard;           // revealed by the scan: nothing ahead of the plane
                     // the solid side gets a faint pre-glow just ahead of the plane
                     outgoingLight += uHoloColor * exp(-(s - fa) / 0.03) * 0.6;
                   }
@@ -78,7 +83,7 @@ export default defineOperation({
             target.userData[STATE] = st;
         }
         const s = st;
-        setFieldParams(s.field, { direction: p.direction }, target, ctx);
+        setFieldParams(s.field, { direction: p.direction, __reveal: p.__reveal }, target, ctx);
         s.color.value.set(String(p.color));
         s.density.value = Number(p.density);
         s.gap.value = Number(p.hold);
@@ -95,6 +100,7 @@ export default defineOperation({
         if (!s)
             return;
         setMeshesHidden(target, false);
+        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/jelly.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jelly.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/jelly.ts"],"names":[],"mappings":";AAWA,wBAqCG"}
+{"version":3,"file":"jelly.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/jelly.ts"],"names":[],"mappings":";AAWA,wBA8CG"}

package/dist/operations/catalogue/jelly.js

@@ -14,7 +14,7 @@ export default defineOperation({
     channel: 'transform',
     multi: true,
     toggles: false,
-    usableIn: ['interaction', 'action'],
+    usableIn: ['interaction', 'action', 'object'],
     params: {
         strength: { type: 'number', label: 'Squash', default: 0.28, min: 0.02, max: 0.7, step: 0.01 },
         wobbles: { type: 'number', label: 'Wobbles', default: 3, min: 1, max: 8, step: 0.5 },
@@ -24,27 +24,37 @@ export default defineOperation({
         const running = target.userData[KEY];
         if (running) {
             gsap.killTweensOf(running.proxy);
-            releaseRest(target);
+            releaseRest(target, KEY);
         }
-        const rest = acquireRest(target);
-        const proxy = { t: 0 };
-        target.userData[KEY] = { proxy };
+        const rest = acquireRest(target, KEY);
         const A = Number(p.strength);
         const D = Number(p.duration);
+        // p.__backward (playback: reverse / yoyo) plays the same move backwards in time.
+        const back = p.__backward === true;
+        const proxy = { t: back ? D : 0 };
+        target.userData[KEY] = { proxy };
         const w = 2 * Math.PI * (Number(p.wobbles) / D); // rad/s
         const k = 4.6 / D; // decays to 1% by the end
         const s = new Vector3();
         gsap.to(proxy, {
-            t: D, duration: D, ease: 'none',
+            t: back ? 0 : D, duration: D, ease: 'none',
             onUpdate: () => {
                 const t = proxy.t;
                 // damped spring, squash first
                 const sy = 1 - A * Math.exp(-k * t) * Math.sin(w * t);
                 const sxz = 1 / Math.sqrt(Math.max(sy, 0.05)); // keep the volume
                 s.set(sxz, sy, sxz);
-                poseAbout(target, rest, rest.bottomLocal, NO_TURN, s);
+                poseAbout(target, rest, rest.bottomLocal, NO_TURN, s, undefined, KEY);
             },
-            onComplete: () => { delete target.userData[KEY]; releaseRest(target); },
+            onComplete: () => { delete target.userData[KEY]; releaseRest(target, KEY); },
         });
     },
+    cancel(target) {
+        const running = target.userData[KEY];
+        if (!running)
+            return;
+        gsap.killTweensOf(running.proxy);
+        delete target.userData[KEY];
+        releaseRest(target, KEY);
+    },
 });

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

@@ -0,0 +1,3 @@
+declare const _default: import("..").OperationDefinition;
+export default _default;
+//# sourceMappingURL=knockAway.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"knockAway.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/knockAway.ts"],"names":[],"mappings":";AA0BA,wBAmDG"}

package/dist/operations/catalogue/knockAway.js

@@ -0,0 +1,74 @@
+// Knock away — the object is struck from the side at a point above or below its
+// centre. The impulse gives it linear AND angular velocity, the spin set by the
+// arm of the hit over its inertia (a box from its own bounds: I ∝ h² + w²), so a
+// tall thing struck high tips and tumbles while a flat one mostly skims. It
+// compresses at the impact, flies off on a ballistic arc, slowed by drag, tumbling
+// at a constant rate, and is gone. The way back: it is thrown in from the other
+// side with back-spin, lands upright and settles with two small hops and a rock.
+import { Quaternion, Vector3 } from 'three';
+import { clamp01, physicalExit, ring, smooth, stretchAxis } from './physicalExit.js';
+const LAND = 0.62;
+const _d = new Vector3(), _n = new Vector3(), _q = new Quaternion(), _y = new Quaternion();
+function axes(a) {
+    const f = a.frame;
+    _d.copy(f.right).multiplyScalar(a.p.side === 'right' ? -1 : 1); // struck from the left = flies right
+    _n.crossVectors(f.up, _d).normalize(); // + about it tips the top towards _d
+}
+/** Turns of tumble over the flight: the hit's arm over the inertia (box), scaled by the strength. */
+function tumbleTurns(a) {
+    const H = a.size.y, W = Math.max(a.size.x, a.size.z);
+    const arm = (Number(a.p.hit) - 0.5) * 2; // −1 (bottom) … 1 (top)
+    return 1.3 * arm * (Number(a.p.strength) / 6) * (H * H) / (H * H + W * W) * 2;
+}
+export default physicalExit({
+    value: 'knockAway',
+    label: 'Knock away',
+    description: 'Struck from the side: it flies off on an arc, tumbling by where it was hit — tall things tip, flat ones skim; it is thrown back in and lands with a hop',
+    params: {
+        side: {
+            type: 'select', label: 'Struck from', default: 'left', options: [{ value: 'left', label: 'The left' }, { value: 'right', label: 'The right' }],
+            hint: 'Screen-relative when it starts',
+        },
+        strength: { type: 'number', label: 'Strength', default: 6, min: 2, max: 30, step: 0.5, hint: 'How far it flies, × its size' },
+        lift: { type: 'number', label: 'Arc', default: 1.6, min: 0, max: 5, step: 0.05, hint: 'Height of the arc, × its height' },
+        hit: { type: 'number', label: 'Hit height', default: 0.75, min: 0, max: 1, step: 0.01, hint: '0 = struck at its base, 1 = at its top' },
+        duration: { type: 'number', label: 'Duration', default: 1.6, min: 0.3, max: 6, step: 0.05, unit: 's' },
+    },
+    exit(u, out, a) {
+        const p = a.p, H = a.size.y;
+        axes(a);
+        const dist = Number(p.strength) * a.span;
+        const x = dist * (1 - Math.pow(1 - u, 1.25)); // drag slows it
+        const y = 4 * Number(p.lift) * H * u * (1 - u);
+        out.off.copy(_d).multiplyScalar(x).addScaledVector(a.frame.up, y);
+        const th = 2 * Math.PI * tumbleTurns(a) * u;
+        _q.setFromAxisAngle(_n, th).multiply(_y.setFromAxisAngle(a.frame.up, 0.35 * u));
+        out.q.copy(a.local(_q));
+        // compressed by the blow for an instant
+        const squash = 0.18 * Math.sin(Math.PI * Math.min(1, u / 0.12));
+        stretchAxis(out.s, a.axis(_d), 1 - squash, 1 - smooth(0.7, 1, u));
+    },
+    enter(v, out, a) {
+        const p = a.p, H = a.size.y;
+        axes(a);
+        const dist = Number(p.strength) * a.span * 0.7;
+        if (v < LAND) {
+            const tau = v / LAND;
+            const x = -0.15 * a.span - dist * Math.pow(1 - tau, 1.15);
+            const y = 4 * Number(p.lift) * 0.8 * H * tau * (1 - tau);
+            out.off.copy(_d).multiplyScalar(x).addScaledVector(a.frame.up, y);
+            // back-spin that runs out exactly as it lands upright
+            const th = -2 * Math.PI * 0.75 * Math.sign(tumbleTurns(a) || 1) * Math.pow(1 - tau, 1.3);
+            out.q.copy(a.local(_q.setFromAxisAngle(_n, th)));
+            out.s.setScalar(smooth(0, 0.25, tau));
+            return;
+        }
+        // two shrinking hops over the last bit, rocking
+        const sg = clamp01((v - LAND) / (1 - LAND));
+        const x = -0.15 * a.span * Math.pow(1 - sg, 1.5);
+        const y = 0.22 * H * Math.abs(Math.sin(2 * Math.PI * sg)) * (1 - sg) * (1 - sg);
+        out.off.copy(_d).multiplyScalar(x).addScaledVector(a.frame.up, y);
+        out.q.copy(a.local(_q.setFromAxisAngle(_n, 0.12 * ring(sg, 1.5, 3))));
+        out.pivot = 'bottom';
+    },
+});

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

@@ -0,0 +1,3 @@
+declare const _default: import("..").OperationDefinition;
+export default _default;
+//# sourceMappingURL=leafFall.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"leafFall.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/leafFall.ts"],"names":[],"mappings":";AA2BA,wBA+CG"}

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/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/petrify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"petrify.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/petrify.ts"],"names":[],"mappings":";AAqDA,wBA0CG"}
+{"version":3,"file":"petrify.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/petrify.ts"],"names":[],"mappings":";AAwDA,wBA6CG"}