@3driseai/3drise-viewer 0.1.28 → 0.1.30

package/dist/operations/catalogue/particleSwarm.js

@@ -4,6 +4,8 @@
 // rotation (inner rings faster, like a disc). While it is on, the swarm keeps
 // turning. Reverting pulls every particle back to its exact spot and the
 // surface closes behind them.
+// With Disappear off (an object effect's default) the object stays as a particle
+// cloud in its own shape: every particle on its spot, twinkling and breathing.
 import { gsap } from 'gsap';
 import { defineOperation } from '../types.js';
 import { addLayer, forEachMeshMaterial, removeLayer } from './shaderLayers.js';
@@ -18,17 +20,19 @@ const FLIGHT = 0.5;
 export default defineOperation({
     value: 'particleSwarm',
     label: 'Particle swarm',
-    description: 'Break the targets into their own coloured particles that swirl around them — reverting reassembles',
+    description: 'Break the targets into their own coloured particles that swirl around them (or, Disappear off, stay as a particle cloud) — reverting reassembles',
     channel: 'visual',
     multi: true,
     toggles: true,
-    usableIn: ['interaction', 'action'],
+    usableIn: ['interaction', 'action', 'object'],
+    objectParams: { disappear: false },
     params: {
         direction: { type: 'select', label: 'Direction', default: 'up', options: DIRECTION_OPTIONS },
+        disappear: { type: 'boolean', label: 'Disappear', default: true, hint: 'Off: the object stays as a cloud of particles in its own shape' },
         particles: { type: 'number', label: 'Particles', default: 30000, min: 2000, max: 120000, step: 1000 },
         particleSize: { type: 'number', label: 'Particle size', default: 1, min: 0.2, max: 4, step: 0.1, unit: '×' },
-        spread: { type: 'number', label: 'Spread', default: 1, min: 0.3, max: 3, step: 0.05, unit: '×', hint: 'Radius of the vortex' },
-        speed: { type: 'number', label: 'Swirl speed', default: 1, min: 0, max: 4, step: 0.05, unit: '×' },
+        spread: { type: 'number', label: 'Spread', default: 1, min: 0.3, max: 3, step: 0.05, unit: '×', hint: 'Radius of the vortex', showWhen: { disappear: ['true'] } },
+        speed: { type: 'number', label: 'Swirl speed', default: 1, min: 0, max: 4, step: 0.05, unit: '×', showWhen: { disappear: ['true'] } },
         edgeColor: { type: 'color', label: 'Edge colour', default: '#9fe8ff' },
         glow: { type: 'boolean', label: 'Glow', default: true, hint: 'Additive light — off keeps the true surface colours' },
         duration: { type: 'number', label: 'Duration', default: 2.8, min: 0.3, max: 12, step: 0.1, unit: 's' },
@@ -39,16 +43,19 @@ export default defineOperation({
             const field = createFieldState(target);
             field.edgeWidth.value = 0.05;
             field.scale.value = 2.5;
-            const flight = { value: FLIGHT }, spread = { value: 1 }, speed = { value: 1 }, size = { value: 1 };
+            const flight = { value: FLIGHT }, spread = { value: 1 }, speed = { value: 1 }, size = { value: 1 }, keep = { value: 0 };
             const sample = sampleSurfaceCached(target, Math.round(Number(p.particles)), 11);
             const points = createFxPoints(target, sample, {
                 additive: !!p.glow,
-                uniforms: { ...fieldUniforms(P, field), uSwmFlight: flight, uSwmSpread: spread, uSwmSpeed: speed, uSwmPtSize: size },
+                uniforms: { ...fieldUniforms(P, field), uSwmFlight: flight, uSwmSpread: spread, uSwmSpeed: speed, uSwmPtSize: size, uSwmKeep: keep },
                 vertexPars: fieldGlsl(P) + GLSL_POINT_SIZE,
                 vertexMain: /* glsl */ `
                   float birth = ${P}BirthOf(${P}Field(${P}Norm(aP)));
                   float a = clamp((uSwmProgress - birth) / uSwmFlight, 0.0, 1.0);
                   if (a <= 0.0) { gl_Position = vec4(2.0, 2.0, 2.0, 1.0); gl_PointSize = 0.0; vColor = vec3(0.0); vAlpha = 0.0; return; }
+                  // keep: the particle appears on its spot and stays there
+                  float held = uSwmKeep * step(0.9999, uSwmProgress);
+                  a = mix(a, min(a, 0.001), uSwmKeep);
                   float E = uSwmExtent;
                   vec3 C = u${P}Min + u${P}Size * 0.5;
                   // destination: a tilted two-arm spiral galaxy around the object's centre.
@@ -71,19 +78,22 @@ export default defineOperation({
                   vec3 ctrl = aP + aN * (0.25 * E) + vec3(0.0, 0.12 * E, 0.0);
                   float k = a * a * (3.0 - 2.0 * a);
                   vec3 local = mix(mix(aP, ctrl, k), mix(ctrl, D, k), k);
+                  // holding as a cloud: particles jitter on their spots, the whole cloud breathes
+                  local += held * (aN * E * 0.004 * sin(u${P}Time * (2.0 + 2.0 * aR.w) + aR.z * 40.0));
+                  local = C + (local - C) * (1.0 + held * 0.012 * sin(u${P}Time * 0.9));
                   vec4 mv = modelViewMatrix * vec4(local, 1.0);
                   gl_Position = projectionMatrix * mv;
                   // the colour of the spot it left, brighter in flight, a slow shimmer in the vortex
                   float flightGlow = sin(3.14159 * a);
                   float shimmer = 0.85 + 0.15 * sin(u${P}Time * (1.0 + 2.0 * aR.w) + aR.z * 6.2832);
                   vColor = aC * (1.0 + 0.4 * flightGlow) * shimmer + u${P}EdgeColor * 0.25 * flightGlow * flightGlow;
-                  vAlpha = smoothstep(0.0, 0.08, a);
+                  vAlpha = mix(smoothstep(0.0, 0.08, a), 0.75 + 0.25 * sin(u${P}Time * (3.0 + 4.0 * aR.x) + aR.y * 50.0), uSwmKeep);
                   gl_PointSize = clamp(fxPointPx(E * 0.0045 * uSwmPtSize * (0.6 + 0.8 * aR.w), mv), 0.0, 20.0);`,
             });
             const own = {};
             // while the swarm exists it keeps turning, even after the transition finished
             const tick = () => { own.field.time.value += gsap.ticker.deltaRatio() / 60; syncRoot(target, own.field); };
-            Object.assign(own, { field, flight, spread, speed, size, points, mats: new Set(), tick });
+            Object.assign(own, { field, flight, spread, speed, size, keep, points, mats: new Set(), tick });
             st = own;
             const layer = surfaceLayer(P, field, 'tint');
             forEachMeshMaterial(target, (mat, mesh) => {
@@ -100,6 +110,15 @@ export default defineOperation({
         s.spread.value = Number(p.spread);
         s.speed.value = Number(p.speed);
         s.size.value = Number(p.particleSize);
+        s.keep.value = p.disappear === false ? 1 : 0;
+        setMeshesHidden(target, false);
+        if (s.keep.value) {
+            // keep: the surface becomes its particles (0 → 1) and holds — its own ticker keeps the time running
+            return runProgress(target, s.field, 1, {
+                duration: Number(p.duration) / (1 + FLIGHT), ease: 'none', clock: false,
+                onComplete: () => setMeshesHidden(target, true),
+            });
+        }
         return runProgress(target, s.field, 1 + FLIGHT, {
             duration: Number(p.duration), ease: 'power1.inOut', clock: false,
             onComplete: () => setMeshesHidden(target, true),
@@ -110,8 +129,9 @@ export default defineOperation({
         if (!s)
             return;
         setMeshesHidden(target, false);
+        // from a hold it only has part of the way to go: keep the same speed
         return runProgress(target, s.field, 0, {
-            duration: Number(p.duration), ease: 'power1.inOut', clock: false,
+            duration: Number(p.duration) * Math.min(1, Math.max(0.1, s.field.progress.value / (1 + FLIGHT))), 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/petalPeel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"petalPeel.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/petalPeel.ts"],"names":[],"mappings":";AAsBA,wBAqHG"}
+{"version":3,"file":"petalPeel.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/petalPeel.ts"],"names":[],"mappings":";AAwBA,wBA2IG"}

package/dist/operations/catalogue/petalPeel.js

@@ -4,6 +4,8 @@
 // rocking tumble — and settles flat on the ground around the base. The flakes
 // are real lit, double-sided instances (one instanced mesh, casting shadows).
 // Reverting lifts them back into place and the surface closes.
+// With Disappear off (an object effect's default) the object stays "lifted": every
+// flake hinged up off the surface like raised scales, breathing in slow waves.
 import { CircleGeometry } from 'three';
 import { defineOperation } from '../types.js';
 import { GLSL_ROT, addLayer, forEachMeshMaterial, removeLayer } from './shaderLayers.js';
@@ -17,16 +19,18 @@ const LIFE = 0.8;
 export default defineOperation({
     value: 'petalPeel',
     label: 'Petal peel',
-    description: 'Peel the targets into flakes that flutter down like leaves — reverting lifts them back',
+    description: 'Peel the targets into flakes that flutter down like leaves (or, Disappear off, stay lifted like raised scales) — reverting lifts them back',
     channel: 'visual',
     multi: true,
     toggles: true,
-    usableIn: ['interaction', 'action'],
+    usableIn: ['interaction', 'action', 'object'],
+    objectParams: { disappear: false },
     params: {
         direction: { type: 'select', label: 'Direction', default: 'down', options: DIRECTION_OPTIONS },
+        disappear: { type: 'boolean', label: 'Disappear', default: true, hint: 'Off: the flakes stay lifted off the surface, like raised scales' },
         petals: { type: 'number', label: 'Petals', default: 2600, min: 300, max: 20000, step: 100 },
         petalSize: { type: 'number', label: 'Petal size', default: 1, min: 0.3, max: 4, step: 0.05, unit: '×' },
-        drift: { type: 'number', label: 'Drift', default: 1, min: 0, max: 4, step: 0.05, unit: '×', hint: 'How far they sway and scatter' },
+        drift: { type: 'number', label: 'Drift', default: 1, min: 0, max: 4, step: 0.05, unit: '×', hint: 'How far they sway and scatter', showWhen: { disappear: ['true'] } },
         edgeColor: { type: 'color', label: 'Edge colour', default: '#fff1d6' },
         scale: { type: 'number', label: 'Pattern', default: 2.5, min: 0.5, max: 12, step: 0.1 },
         duration: { type: 'number', label: 'Duration', default: 4, min: 0.3, max: 14, step: 0.1, unit: 's' },
@@ -36,7 +40,7 @@ export default defineOperation({
         if (!st) {
             const field = createFieldState(target);
             field.edgeWidth.value = 0.04;
-            const life = { value: LIFE }, drift = { value: 1 };
+            const life = { value: LIFE }, drift = { value: 1 }, keep = { value: 0 };
             const count = Math.round(Number(p.petals));
             const sample = sampleSurfaceCached(target, count, 47);
             // petal size from the surface area each one has to cover
@@ -54,7 +58,7 @@ export default defineOperation({
                 },
                 layerKey: 'petalInstances', roughness: 0.7, metalness: 0, doubleSided: true,
                 layer: {
-                    uniforms: { ...fieldUniforms(P, field), uPdlLife: life, uPdlDrift: drift },
+                    uniforms: { ...fieldUniforms(P, field), uPdlLife: life, uPdlDrift: drift, uPdlKeep: keep },
                     common: fieldGlsl(P) + GLSL_ROT,
                     vertexPars: /* glsl */ `
                     attribute vec3 aPdlP; attribute vec3 aPdlN; attribute vec4 aPdlR;
@@ -78,12 +82,22 @@ export default defineOperation({
                       mat3 lying = fxRot(vec3(0.0, 1.0, 0.0), aPdlR.y * 6.28) * mat3(1.0, 0.0, 0.0, 0.0, 0.0, -1.0, 0.0, 1.0, 0.0);
                       float settle = smoothstep(land, land + 0.06, a);
                       return mat3(mix(inAir[0], lying[0], settle), mix(inAir[1], lying[1], settle), mix(inAir[2], lying[2], settle));
-                    }`,
-                    normal: `{ objectNormal = pdlRot(pdlAge()) * objectNormal; }`,
+                    }
+                    // lifted (keep): hinged up off the surface, breathing in slow waves across the object
+                    float pdlLift(float a) {
+                      float held = uPdlKeep * step(0.9999, uPdlProgress);
+                      float wave = sin(uPdlTime * 1.1 + dot(aPdlP, vec3(1.0, 0.6, 0.3)) / uPdlExtent * 7.0 + aPdlR.x * 0.8);
+                      return smoothstep(0.0, 0.14, a) * (0.5 + held * 0.14 * wave);
+                    }
+                    mat3 pdlLifted(float a) { return pdlFrame() * fxRot(vec3(1.0, 0.0, 0.0), pdlLift(a)); }`,
+                    normal: `{ objectNormal = (uPdlKeep > 0.5 ? pdlLifted(pdlAge()) : pdlRot(pdlAge())) * objectNormal; }`,
                     vertex: /* glsl */ `
                     {
                       float a = pdlAge();
                       if (a <= 0.0) { transformed *= 0.0; }
+                      else if (uPdlKeep > 0.5) {
+                        transformed = pdlLifted(a) * transformed + aPdlN * (0.012 * uPdlExtent) * smoothstep(0.0, 0.14, a);
+                      }
                       else {
                         a = min(a, 1.0);
                         float E = uPdlExtent;
@@ -101,7 +115,7 @@ export default defineOperation({
                     }`,
                 },
             });
-            st = { field, life, drift, mesh, mats: new Set() };
+            st = { field, life, drift, keep, mesh, mats: new Set() };
             const own = st;
             const layer = surfaceLayer(P, field, 'tint');
             forEachMeshMaterial(target, (mat, m) => {
@@ -115,6 +129,15 @@ export default defineOperation({
         const s = st;
         setFieldParams(s.field, p, target, ctx);
         s.drift.value = Number(p.drift);
+        s.keep.value = p.disappear === false ? 1 : 0;
+        hideMeshes(target, KEY, false);
+        if (s.keep.value) {
+            // keep: the surface lifts into flakes (0 → 1) and holds
+            return runProgress(target, s.field, 1, {
+                duration: Number(p.duration) / (1 + LIFE), ease: 'none', hold: true,
+                onComplete: () => hideMeshes(target, KEY, true),
+            });
+        }
         return runProgress(target, s.field, 1 + LIFE, {
             duration: Number(p.duration), ease: 'none',
             onComplete: () => hideMeshes(target, KEY, true),
@@ -125,8 +148,9 @@ export default defineOperation({
         if (!s)
             return;
         hideMeshes(target, KEY, false);
+        // from a hold it only has part of the way to go: keep the same speed
         return runProgress(target, s.field, 0, {
-            duration: Number(p.duration), ease: 'none',
+            duration: Number(p.duration) * Math.min(1, Math.max(0.1, s.field.progress.value / (1 + LIFE))), ease: 'none',
             onComplete: () => {
                 s.mats.forEach(m => removeLayer(m, KEY));
                 disposeFxInstances(s.mesh);

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"}

package/dist/operations/catalogue/petrify.js

@@ -7,17 +7,20 @@
 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 = 'Stn';
 const KEY = 'petrify';
 const STATE = '__opPetrify';
 function layerFor(st) {
     const amount = /* glsl */ `
       float stnD = StnThreshold() - StnField(vStnQ);
-      float st = smoothstep(0.0, uStnEdgeWidth, stnD);`;
+      float st = smoothstep(0.0, uStnEdgeWidth, stnD);
+      // revealed by the stone: nothing ahead of the front, full stone right behind it
+      if (uStnReveal > 0.5) { if (stnD < 0.0) discard; st = 1.0; }
+      if (StnGone(vStnQ) > 0.5) { st = 0.0; stnD = -1.0; }   // wiped by the look that replaces it`;
     return {
         uniforms: { ...fieldUniforms(P, st.field), uStnStone: st.stone },
-        common: `varying vec3 vStnQ;\nvarying vec3 vStnR;\n${fieldGlsl(P)}`,
+        common: `varying vec3 vStnQ;\nvarying vec3 vStnR;\n${fieldGlsl(P)}\n${goneGlsl(P)}`,
         vertex: /* glsl */ `
         vStnR = (uStnRootInv * modelMatrix * vec4(transformed, 1.0)).xyz;
         vStnQ = StnNorm(vStnR);`,
@@ -54,6 +57,8 @@ export default defineOperation({
     multi: true,
     toggles: true,
     usableIn: ['interaction', 'action', 'object'],
+    presence: 'paint',
+    field: (target) => target.userData[STATE]?.field,
     stack: 'surface',
     params: {
         direction: { type: 'select', label: 'Direction', default: 'up', options: DIRECTION_OPTIONS },
@@ -86,6 +91,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/physicalExit.d.ts

@@ -0,0 +1,55 @@
+import { Quaternion, Vector3 } from 'three';
+import { type OperationDefinition, type OperationParamSpec, type OperationParams } from '../types';
+/** What a path writes: a turn and scale about a pivot (object-local), plus a world offset. */
+export interface ExitPose {
+    q: Quaternion;
+    s: Vector3;
+    off: Vector3;
+    /** 'center' or 'bottom' of the object's bounds. */
+    pivot: 'center' | 'bottom';
+}
+/** The world frame the path is laid out in, fixed when the motion starts. */
+export interface ExitFrame {
+    /** World up. */
+    up: Vector3;
+    /** Screen right on the ground plane (world X with no camera). */
+    right: Vector3;
+    /** From the object towards the camera on the ground plane (world +Z with no camera). */
+    toward: Vector3;
+    /** From the object's base to the camera (world), or null without a camera. */
+    camera: Vector3 | null;
+}
+export interface ExitPathArgs<M> {
+    /** World size at rest, and its largest side. */
+    size: Vector3;
+    span: number;
+    p: OperationParams;
+    frame: ExitFrame;
+    /** Built once per run by `prepare` (tables, random draws). */
+    mem: M;
+    /** A turn given in WORLD axes, as the object-local turn ExitPose.q expects. */
+    local: (qWorld: Quaternion) => Quaternion;
+    /** The object's own axis (0 x, 1 y, 2 z) that lies closest to a WORLD direction at rest — for stretching along it. */
+    axis: (worldDir: Vector3) => 0 | 1 | 2;
+}
+export interface ExitSpec<M = unknown> {
+    value: string;
+    label: string;
+    description: string;
+    params: Record<string, OperationParamSpec>;
+    /** Per-run data shared by both paths (an integrated angle table…). */
+    prepare?: (args: Omit<ExitPathArgs<M>, 'mem' | 'local' | 'axis'>) => M;
+    /** u: 0 at rest → 1 gone. Must be the identity at u = 0 and scale ~0 at u = 1. */
+    exit: (u: number, out: ExitPose, a: ExitPathArgs<M>) => void;
+    /** v: 0 gone → 1 at rest. Scale ~0 at v = 0, the identity at v = 1. */
+    enter: (v: number, out: ExitPose, a: ExitPathArgs<M>) => void;
+}
+export declare const clamp01: (x: number) => number;
+export declare const smooth: (a: number, b: number, x: number) => number;
+/** Stretch by `k` along one local axis keeping the volume (the other two by 1/√k), times a uniform `size`. */
+export declare function stretchAxis(s: Vector3, axis: 0 | 1 | 2, k: number, size?: number): void;
+/** A damped ring that starts at 0, moves first in `+` and lands exactly at 0 at σ = 1. */
+export declare const ring: (sg: number, cycles: number, decay?: number) => number;
+/** Build a physical exit operation from its two paths. */
+export declare function physicalExit<M = unknown>(spec: ExitSpec<M>): OperationDefinition;
+//# sourceMappingURL=physicalExit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"physicalExit.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/physicalExit.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAE5C,OAAO,EAA0C,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AAI3I,8FAA8F;AAC9F,MAAM,WAAW,QAAQ;IACrB,CAAC,EAAE,UAAU,CAAC;IACd,CAAC,EAAE,OAAO,CAAC;IACX,GAAG,EAAE,OAAO,CAAC;IACb,mDAAmD;IACnD,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAC9B;AAED,6EAA6E;AAC7E,MAAM,WAAW,SAAS;IACtB,gBAAgB;IAChB,EAAE,EAAE,OAAO,CAAC;IACZ,iEAAiE;IACjE,KAAK,EAAE,OAAO,CAAC;IACf,wFAAwF;IACxF,MAAM,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC3B,gDAAgD;IAChD,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,eAAe,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;IACjB,8DAA8D;IAC9D,GAAG,EAAE,CAAC,CAAC;IACP,+EAA+E;IAC/E,KAAK,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,UAAU,CAAC;IAC1C,sHAAsH;IACtH,IAAI,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC3C,sEAAsE;IACtE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,kFAAkF;IAClF,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC7D,uEAAuE;IACvE,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;CACjE;AAeD,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,WAAgC,CAAC;AAClE,eAAO,MAAM,MAAM,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,WAA0E,CAAC;AAEjI,8GAA8G;AAC9G,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,SAAI,QAG3E;AAED,0FAA0F;AAC1F,eAAO,MAAM,IAAI,GAAI,IAAI,MAAM,EAAE,QAAQ,MAAM,EAAE,cAAS,WACqB,CAAC;AAiBhF,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,mBAAmB,CA+FhF"}

package/dist/operations/catalogue/physicalExit.js

@@ -0,0 +1,165 @@
+// Physical exits — the object leaves the scene by a motion of its own (blast off,
+// drain into a vortex, fall like a leaf) and comes back by ANOTHER motion: a rocket
+// lands, it does not un-launch. One shape for all of them:
+//
+//   apply   the exit path, u: 0 (at rest) → 1 (gone: scale ~0, then hidden)
+//   revert  from gone: the entrance path, v: 0 (gone) → 1 (exactly at rest)
+//           from part-way out: back along the exit path (it turns round mid-flight)
+//   apply while it is still coming in: back along the entrance path (it turns round)
+//
+// Paths are pure functions of their own progress, written as physics in time (the
+// tween is linear, the motion's easing is the physics), so a turn-round is seamless
+// and `duration: 0` lands exactly. They ride on the object's transform through the
+// physical mix (./physicalMix.ts) — never writing position / rotation / scale —
+// so they stack with held motions and follow a moving base.
+//
+// presence 'vanish': as an object effect following visibility, shown = the entrance,
+// hidden = the exit.
+import { gsap } from 'gsap';
+import { Quaternion, Vector3 } from 'three';
+import { defineOperation } from '../types.js';
+import { acquireRest, poseAbout, releaseRest } from './restPose.js';
+import { mixBase } from './physicalMix.js';
+const UP = new Vector3(0, 1, 0);
+const GONE = 1e-4;
+export const clamp01 = (x) => Math.min(1, Math.max(0, x));
+export const smooth = (a, b, x) => { const v = clamp01((x - a) / (b - a)); return v * v * (3 - 2 * v); };
+/** Stretch by `k` along one local axis keeping the volume (the other two by 1/√k), times a uniform `size`. */
+export function stretchAxis(s, axis, k, size = 1) {
+    const o = 1 / Math.sqrt(Math.max(k, 0.02));
+    s.set(o * size, o * size, o * size).setComponent(axis, k * size);
+}
+/** A damped ring that starts at 0, moves first in `+` and lands exactly at 0 at σ = 1. */
+export const ring = (sg, cycles, decay = 3) => Math.sin(2 * Math.PI * cycles * sg) * Math.exp(-decay * sg) * (1 - sg * sg);
+/** The camera's ground-plane frame at trigger time (world X / +Z without a camera). */
+function frameOf(target, ctx) {
+    const frame = { up: UP.clone(), right: new Vector3(1, 0, 0), toward: new Vector3(0, 0, 1), camera: null };
+    const cam = ctx?.tools?.cameraPose?.();
+    if (!cam)
+        return frame;
+    const at = mixBase(target).position.clone(); // where it stands at its base, not where a path left it
+    target.parent?.localToWorld(at);
+    frame.camera = new Vector3(cam.position[0], cam.position[1], cam.position[2]).sub(at);
+    const t = new Vector3(cam.position[0] - at.x, 0, cam.position[2] - at.z);
+    if (t.lengthSq() < 1e-8)
+        return frame;
+    frame.toward.copy(t.normalize());
+    frame.right.crossVectors(UP, frame.toward).normalize();
+    return frame;
+}
+/** Build a physical exit operation from its two paths. */
+export function physicalExit(spec) {
+    const KEY = `__opExit_${spec.value}`;
+    const pose = { q: new Quaternion(), s: new Vector3(1, 1, 1), off: new Vector3(), pivot: 'center' };
+    const draw = (target, st) => {
+        const a = st.args;
+        pose.q.identity();
+        pose.s.set(1, 1, 1);
+        pose.off.set(0, 0, 0);
+        pose.pivot = 'center';
+        if (st.mode === 'exit')
+            spec.exit(st.t, pose, a);
+        else
+            spec.enter(st.t, pose, a);
+        pose.s.set(Math.max(pose.s.x, GONE), Math.max(pose.s.y, GONE), Math.max(pose.s.z, GONE));
+        const pivot = pose.pivot === 'bottom' ? st.rest.bottomLocal : st.rest.centerLocal;
+        poseAbout(target, st.rest, pivot, pose.q, pose.s, pose.off, KEY);
+    };
+    const setup = (target, st, p, ctx) => {
+        st.frame = frameOf(target, ctx);
+        const size = st.rest.size.clone();
+        const base = { size, span: Math.max(size.x, size.y, size.z, 1e-6), p, frame: st.frame };
+        // the object's world turn at its BASE (not the pose this path left it in)
+        const W = target.parent ? target.parent.getWorldQuaternion(new Quaternion()) : new Quaternion();
+        W.multiply(mixBase(target).quaternion);
+        const Wi = W.clone().invert();
+        const local = (qWorld) => qWorld.premultiply(Wi).multiply(W);
+        const _d = new Vector3();
+        const axis = (dir) => {
+            _d.copy(dir).applyQuaternion(Wi);
+            const x = Math.abs(_d.x), y = Math.abs(_d.y), z = Math.abs(_d.z);
+            return x >= y && x >= z ? 0 : y >= z ? 1 : 2;
+        };
+        st.args = { ...base, local, axis, mem: spec.prepare ? spec.prepare(base) : undefined };
+    };
+    /** Move along the current path to `to`; resolves when it gets there (or is replaced). */
+    const run = (target, st, to, seconds, done) => {
+        gsap.killTweensOf(st.proxy);
+        st.resolve?.();
+        st.proxy.t = st.t;
+        return new Promise(resolve => {
+            st.resolve = resolve;
+            const finish = () => { st.t = to; draw(target, st); st.resolve = undefined; done(); resolve(); };
+            if (seconds <= 1e-4 || Math.abs(to - st.t) < 1e-6) {
+                finish();
+                return;
+            }
+            gsap.to(st.proxy, {
+                t: to, duration: seconds, ease: 'none',
+                onUpdate: () => { st.t = st.proxy.t; draw(target, st); },
+                onComplete: finish,
+            });
+        });
+    };
+    const release = (target) => {
+        const st = target.userData[KEY];
+        if (!st)
+            return;
+        gsap.killTweensOf(st.proxy);
+        st.resolve?.();
+        delete target.userData[KEY];
+        releaseRest(target, KEY);
+    };
+    return defineOperation({
+        value: spec.value,
+        label: spec.label,
+        description: spec.description,
+        channel: 'transform',
+        multi: true,
+        toggles: true,
+        usableIn: ['interaction', 'action', 'object'],
+        presence: 'vanish',
+        params: spec.params,
+        apply(target, p, ctx) {
+            let st = target.userData[KEY];
+            if (!st) {
+                st = { rest: acquireRest(target, KEY), mode: 'exit', t: 0, proxy: { t: 0 }, frame: frameOf(target, ctx) };
+                target.userData[KEY] = st;
+                setup(target, st, p, ctx);
+            }
+            else
+                st.args = { ...st.args, p };
+            const D = Number(p.duration);
+            const s = st;
+            // still coming in: turn round along the entrance, back to gone
+            if (s.mode === 'enter' && s.t < 1)
+                return run(target, s, 0, D * s.t, () => { s.mode = 'exit'; s.t = 1; target.visible = false; });
+            if (s.mode === 'enter') {
+                s.mode = 'exit';
+                s.t = 0;
+                setup(target, s, p, ctx);
+            }
+            return run(target, s, 1, D * (1 - s.t), () => { target.visible = false; });
+        },
+        revert(target, p, ctx) {
+            const st = target.userData[KEY];
+            if (!st)
+                return;
+            st.args = { ...st.args, p };
+            target.visible = true; // it comes back shown (it may have gone while the object was hidden)
+            const D = Number(p.duration);
+            const done = () => release(target);
+            // part-way out: turn round along the exit
+            if (st.mode === 'exit' && st.t < 1)
+                return run(target, st, 0, D * st.t, done);
+            // gone: the entrance (re-laid out for where the camera is now)
+            if (st.mode === 'exit') {
+                st.mode = 'enter';
+                st.t = 0;
+                setup(target, st, p, ctx);
+                draw(target, st);
+            }
+            return run(target, st, 1, D * (1 - st.t), done);
+        },
+    });
+}

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

@@ -0,0 +1,41 @@
+import type { OperationDefinition, OperationParamSpec, OperationParams } from '../types';
+import { type MixBody, type MixPart } from './physicalMix';
+export interface HeldState<M> {
+    /** Strength 0..1 (the in / out envelope). */
+    amp: {
+        v: number;
+    };
+    /** The effect's current parameters (a live edit lands here). */
+    p: OperationParams;
+    body: MixBody;
+    /** The effect's own memory between frames. */
+    mem: M;
+    /** Leaving (the out is playing). */
+    out: boolean;
+    /** The motion's own clock, seconds — runs backwards while `__backward` is set. */
+    t: number;
+    resolve?: () => void;
+}
+export interface HeldPhysicalSpec<M> {
+    value: string;
+    label: string;
+    description: string;
+    params: Record<string, OperationParamSpec>;
+    /** Ease of the in / out envelope (default sine.inOut). */
+    ease?: string;
+    /** A repeating motion (see the header). Default true; false = a state that arrives and stays. */
+    periodic?: boolean;
+    memory: (body: MixBody, p: OperationParams) => M;
+    /** Fill `part` for this frame. `time` is the motion's clock and `dt` its step (negative when it runs backwards). */
+    move: (part: MixPart, st: HeldState<M>, time: number, dt: number) => void;
+    /** The out is starting (e.g. pick where to land). */
+    onOut?: (st: HeldState<M>) => void;
+}
+/** A periodic effect's pass. */
+export declare const DURATION: Extract<OperationParamSpec, {
+    type: 'number';
+}>;
+/** How long a periodic effect takes to build up, and to settle, within a pass of `duration`. */
+export declare const periodicEase: (duration: number) => number;
+export declare function heldPhysical<M>(spec: HeldPhysicalSpec<M>): OperationDefinition;
+//# sourceMappingURL=physicalHeld.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"physicalHeld.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/physicalHeld.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACzF,OAAO,EAAqB,KAAK,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAE9E,MAAM,WAAW,SAAS,CAAC,CAAC;IACxB,6CAA6C;IAC7C,GAAG,EAAE;QAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnB,gEAAgE;IAChE,CAAC,EAAE,eAAe,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,8CAA8C;IAC9C,GAAG,EAAE,CAAC,CAAC;IACP,oCAAoC;IACpC,GAAG,EAAE,OAAO,CAAC;IACb,kFAAkF;IAClF,CAAC,EAAE,MAAM,CAAC;IACV,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC3C,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iGAAiG;IACjG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,eAAe,KAAK,CAAC,CAAC;IACjD,oHAAoH;IACpH,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1E,qDAAqD;IACrD,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;CACtC;AAED,gCAAgC;AAChC,eAAO,MAAM,QAAQ,EAAE,OAAO,CAAC,kBAAkB,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAgL,CAAC;AAEtP,gGAAgG;AAChG,eAAO,MAAM,YAAY,GAAI,UAAU,MAAM,WAAgD,CAAC;AAE9F,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAmD9E"}

package/dist/operations/catalogue/physicalHeld.js

@@ -0,0 +1,78 @@
+// Held physical effects (float, sway, bounce…): one shape for all of them.
+//
+//   in    the motion's strength eases 0 → 1 while it is already moving
+//   hold  it keeps moving for as long as the effect is on
+//   out   the strength eases back to 0, the object settles on its base
+//
+// Two kinds:
+//   periodic  a motion that repeats (float, sway, bounce…). `duration` is one PASS —
+//             in + moving + out. Whoever plays it decides how long it stays on: an
+//             object effect plays one pass and settles, or keeps it on with Loop
+//             (see ObjectEffectsController); an interaction keeps it on until toggled.
+//             `__backward` runs its clock backwards (playback reverse / yoyo).
+//   state     it arrives and stays (grow). `duration` is the in / out time.
+//
+// The motion itself is a `move` function that fills the effect's part of the
+// physical mix (./physicalMix.ts) each frame — so these stack with each other
+// and ride on the object's own (authored / animated) transform.
+import { gsap } from 'gsap';
+import { defineOperation } from '../types.js';
+import { joinMix, leaveMix } from './physicalMix.js';
+/** A periodic effect's pass. */
+export const DURATION = { type: 'number', label: 'Duration', default: 4, min: 0.2, max: 30, step: 0.1, unit: 's', hint: 'One pass: it builds up, moves and settles. With Loop it just keeps going' };
+/** How long a periodic effect takes to build up, and to settle, within a pass of `duration`. */
+export const periodicEase = (duration) => Math.min(0.8, Math.max(0, duration) * 0.25);
+export function heldPhysical(spec) {
+    const KEY = `__op_${spec.value}`;
+    const periodic = spec.periodic !== false;
+    const easeTime = (p) => (periodic ? periodicEase(Number(p.duration)) : Number(p.duration));
+    const run = (target, st, to, duration, done) => {
+        gsap.killTweensOf(st.amp);
+        st.resolve?.(); // a run that is replaced still finishes for whoever waits on it
+        return new Promise((resolve) => {
+            st.resolve = resolve;
+            gsap.to(st.amp, {
+                v: to, duration, ease: spec.ease ?? 'sine.inOut',
+                onComplete: () => { if (st.resolve === resolve)
+                    st.resolve = undefined; done?.(); resolve(); },
+            });
+        });
+    };
+    return defineOperation({
+        value: spec.value, label: spec.label, description: spec.description,
+        channel: 'transform', multi: true, toggles: true,
+        usableIn: ['interaction', 'action', 'object'],
+        periodic,
+        params: spec.params,
+        apply(target, p) {
+            let st = target.userData[KEY];
+            if (!st) {
+                const own = { amp: { v: 0 }, p, out: false, t: 0 };
+                const { body } = joinMix(target, KEY, (part, _time, dt) => {
+                    const step = own.p.__backward === true ? -dt : dt;
+                    own.t += step;
+                    spec.move(part, own, own.t, step);
+                });
+                own.body = body;
+                own.mem = spec.memory(body, p);
+                st = own;
+                target.userData[KEY] = st;
+            }
+            st.p = p;
+            st.out = false;
+            return run(target, st, 1, easeTime(p));
+        },
+        revert(target, p) {
+            const st = target.userData[KEY];
+            if (!st)
+                return;
+            st.out = true;
+            spec.onOut?.(st);
+            // from part-way it takes part of the time (same speed both ways)
+            return run(target, st, 0, easeTime(p) * Math.min(1, Math.max(0.1, Math.abs(st.amp.v))), () => {
+                leaveMix(target, KEY);
+                delete target.userData[KEY];
+            });
+        },
+    });
+}