@3driseai/3drise-viewer 0.1.28 → 0.1.29

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];
+            });
+        },
+    });
+}

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

@@ -0,0 +1,45 @@
+import { Quaternion, Vector3 } from 'three';
+import type { Object3D } from 'three';
+/** One effect's contribution. Mutate it in place (in a tween's onUpdate, or in `sample`). */
+export interface MixPart {
+    /** Turn about the pivot, in the object's own axes. */
+    q: Quaternion;
+    /** Scale about the pivot. */
+    s: Vector3;
+    /** The point that stays put under q / s, in the object's local space. */
+    pivot: Vector3;
+    /** Offset in world units. */
+    off: Vector3;
+    /** Called each frame before composing: time and delta in seconds. */
+    sample?: (part: MixPart, time: number, dt: number) => void;
+}
+/** What an effect needs to know about the object it moves (measured when its first part joined). */
+export interface MixBody {
+    /** Bounds centre and bottom-centre, in the object's local space. */
+    centerLocal: Vector3;
+    bottomLocal: Vector3;
+    /** World-space size. */
+    size: Vector3;
+}
+/**
+ * Compose now — one object's mix, or all of them. Call it after something else
+ * wrote the object's transform in this frame (the object's frame hook does).
+ */
+export declare function tickMix(target?: Object3D | null): void;
+/** Add (or get) this effect's part on the object. `key` is the effect's own. */
+export declare function joinMix(target: Object3D, key: string, sample?: MixPart['sample']): {
+    part: MixPart;
+    body: MixBody;
+};
+/** Take this effect's part off. With the last part gone the object is back on its base. */
+export declare function leaveMix(target: Object3D, key: string): void;
+/** Compose this object now (after changing a part outside the ticker). */
+export declare function composeMix(target: Object3D): void;
+/** The object's base transform while effects move it (its own transform otherwise). */
+export declare function mixBase(target: Object3D): {
+    position: Vector3;
+    quaternion: Quaternion;
+    scale: Vector3;
+};
+export declare const isMixed: (target: Object3D) => boolean;
+//# sourceMappingURL=physicalMix.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"physicalMix.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/physicalMix.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAQ,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEtC,6FAA6F;AAC7F,MAAM,WAAW,OAAO;IACpB,sDAAsD;IACtD,CAAC,EAAE,UAAU,CAAC;IACd,6BAA6B;IAC7B,CAAC,EAAE,OAAO,CAAC;IACX,yEAAyE;IACzE,KAAK,EAAE,OAAO,CAAC;IACf,6BAA6B;IAC7B,GAAG,EAAE,OAAO,CAAC;IACb,qEAAqE;IACrE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9D;AAED,oGAAoG;AACpG,MAAM,WAAW,OAAO;IACpB,oEAAoE;IACpE,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,wBAAwB;IACxB,IAAI,EAAE,OAAO,CAAC;CACjB;AA+DD;;;GAGG;AACH,wBAAgB,OAAO,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,QAK/C;AAED,gFAAgF;AAChF,wBAAgB,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAmBnH;AAED,2FAA2F;AAC3F,wBAAgB,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,QAOrD;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,MAAM,EAAE,QAAQ,QAAqD;AAEhG,uFAAuF;AACvF,wBAAgB,OAAO,CAAC,MAAM,EAAE,QAAQ,GAAG;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAGvG;AAED,eAAO,MAAM,OAAO,GAAI,QAAQ,QAAQ,YAAsB,CAAC"}

package/dist/operations/catalogue/physicalMix.js

@@ -0,0 +1,144 @@
+// Physical mix — how effects move an object without owning its transform.
+//
+// A physical effect never writes position / rotation / scale itself. It adds a
+// *part* to the object's mix: a turn and a scale about a pivot, plus a world
+// offset. Each frame the mix lays every part over the object's BASE transform —
+// the one the scene authored or animates — and writes the result. So:
+//
+//   - effects stack: float + sway + a jelly all show at once, in the order they joined;
+//   - the base stays free: move the object in the studio, keyframe it, play a clip —
+//     the effects ride on top. The mix notices any transform it did not write itself
+//     and takes it as the new base;
+//   - when the last part leaves, the object is back on its base exactly.
+//
+// The mix is composed from the gsap ticker and, for objects in the React tree,
+// again from the object's own frame hook (after its property animations wrote,
+// before the render) — see tickMix. Composing twice in a frame is harmless.
+import { gsap } from 'gsap';
+import { Box3, Quaternion, Vector3 } from 'three';
+const mixes = new Map();
+let ticking = false;
+const _a = new Vector3(), _b = new Vector3(), _P = new Vector3(), _S = new Vector3(), _W = new Vector3();
+const _Q = new Quaternion();
+function measure(target) {
+    target.updateWorldMatrix(true, true);
+    const box = new Box3().setFromObject(target);
+    if (box.isEmpty())
+        return { centerLocal: new Vector3(), bottomLocal: new Vector3(), size: new Vector3(1, 1, 1) };
+    const c = box.getCenter(new Vector3());
+    const bottom = new Vector3(c.x, box.min.y, c.z);
+    return { centerLocal: target.worldToLocal(c.clone()), bottomLocal: target.worldToLocal(bottom), size: box.getSize(new Vector3()) };
+}
+/** Lay the parts over the base and write the transform. */
+function compose(m) {
+    const t = m.target;
+    // a transform we did not write = the scene moved the object: that is the new base
+    if (!t.position.equals(m.lastP))
+        m.baseP.copy(t.position);
+    if (!t.quaternion.equals(m.lastQ))
+        m.baseQ.copy(t.quaternion);
+    if (!t.scale.equals(m.lastS))
+        m.baseS.copy(t.scale);
+    _P.copy(m.baseP);
+    _Q.copy(m.baseQ);
+    _S.copy(m.baseS);
+    _W.set(0, 0, 0);
+    for (const part of m.parts.values()) {
+        // the pivot keeps its place in the parent's space under this part's turn and scale
+        _a.copy(part.pivot).multiply(_S).applyQuaternion(_Q);
+        _Q.multiply(part.q);
+        _S.multiply(part.s);
+        _b.copy(part.pivot).multiply(_S).applyQuaternion(_Q);
+        _P.add(_a).sub(_b);
+        _W.add(part.off);
+    }
+    if (_W.lengthSq() > 0) {
+        if (t.parent) {
+            t.parent.localToWorld(_P).add(_W);
+            t.parent.worldToLocal(_P);
+        }
+        else
+            _P.add(_W);
+    }
+    t.position.copy(_P);
+    t.quaternion.copy(_Q);
+    t.scale.copy(_S);
+    m.lastP.copy(t.position);
+    m.lastQ.copy(t.quaternion);
+    m.lastS.copy(t.scale);
+}
+function step(m, now) {
+    // time moves once per frame, however often the mix is composed in it
+    const dt = m.stamp ? Math.min(0.1, (now - m.stamp) / 1000) : 0;
+    if (dt > 0 || !m.stamp) {
+        m.stamp = now;
+        m.time += dt;
+        for (const part of m.parts.values())
+            part.sample?.(part, m.time, dt);
+    }
+    compose(m);
+}
+const tickAll = () => { const now = performance.now(); mixes.forEach(m => step(m, now)); };
+/**
+ * Compose now — one object's mix, or all of them. Call it after something else
+ * wrote the object's transform in this frame (the object's frame hook does).
+ */
+export function tickMix(target) {
+    if (!mixes.size)
+        return;
+    if (!target) {
+        tickAll();
+        return;
+    }
+    const m = mixes.get(target);
+    if (m)
+        step(m, performance.now());
+}
+/** Add (or get) this effect's part on the object. `key` is the effect's own. */
+export function joinMix(target, key, sample) {
+    let m = mixes.get(target);
+    if (!m) {
+        m = {
+            target, ...measure(target),
+            baseP: target.position.clone(), baseQ: target.quaternion.clone(), baseS: target.scale.clone(),
+            lastP: target.position.clone(), lastQ: target.quaternion.clone(), lastS: target.scale.clone(),
+            parts: new Map(), time: 0, stamp: 0,
+        };
+        mixes.set(target, m);
+        if (!ticking) {
+            ticking = true;
+            gsap.ticker.add(tickAll);
+        }
+    }
+    let part = m.parts.get(key);
+    if (!part) {
+        part = { q: new Quaternion(), s: new Vector3(1, 1, 1), pivot: m.centerLocal.clone(), off: new Vector3() };
+        m.parts.set(key, part);
+    }
+    if (sample)
+        part.sample = sample;
+    return { part, body: m };
+}
+/** Take this effect's part off. With the last part gone the object is back on its base. */
+export function leaveMix(target, key) {
+    const m = mixes.get(target);
+    if (!m || !m.parts.delete(key))
+        return;
+    compose(m);
+    if (m.parts.size)
+        return;
+    mixes.delete(target);
+    if (!mixes.size && ticking) {
+        ticking = false;
+        gsap.ticker.remove(tickAll);
+    }
+}
+/** Compose this object now (after changing a part outside the ticker). */
+export function composeMix(target) { const m = mixes.get(target); if (m)
+    compose(m); }
+/** The object's base transform while effects move it (its own transform otherwise). */
+export function mixBase(target) {
+    const m = mixes.get(target);
+    return m ? { position: m.baseP, quaternion: m.baseQ, scale: m.baseS } : target;
+}
+export const isMixed = (target) => mixes.has(target);

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

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

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

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

package/dist/operations/catalogue/pop.js

@@ -0,0 +1,44 @@
+// Pop — pressure builds inside the object: it inflates while its first shape
+// modes ring faster and faster (it bulges unevenly, one way then the other —
+// an underdamped spring being driven), then it bursts to nothing in a few frames.
+// The way back: it pops out of nothing, overshoots and rings down like jelly
+// until it is exactly at rest.
+import { physicalExit, ring, smooth } from './physicalExit.js';
+const INFLATE_END = 0.84;
+export default physicalExit({
+    value: 'pop',
+    label: 'Pop',
+    description: 'Inflates and wobbles under rising pressure, then bursts to nothing — it pops back out of nothing and rings down',
+    params: {
+        inflate: { type: 'number', label: 'Inflate', default: 0.28, min: 0, max: 1, step: 0.01, hint: 'How much bigger it gets before it bursts' },
+        wobble: { type: 'number', label: 'Wobble', default: 0.09, min: 0, max: 0.3, step: 0.005, hint: 'How unevenly it bulges' },
+        rings: { type: 'number', label: 'Rings', default: 3, min: 1, max: 7, step: 0.5, hint: 'Wobbles as it settles on the way back' },
+        duration: { type: 'number', label: 'Duration', default: 1.1, min: 0.3, max: 5, step: 0.05, unit: 's' },
+    },
+    exit(u, out, a) {
+        const p = a.p;
+        const t = Math.min(1, u / INFLATE_END);
+        const k = 1 + Number(p.inflate) * Math.pow(smooth(0, 1, t), 1.4);
+        // the two shape modes, driven faster as the pressure rises (phase ∝ t + t²)
+        const amp = Number(p.wobble) * smooth(0.12, 0.9, t);
+        const ph = 2 * Math.PI * (2.2 * t + 5.5 * t * t);
+        const m1 = amp * Math.sin(ph), m2 = amp * Math.sin(1.37 * ph + 2.1);
+        // the burst: a last swell, gone within ~15% of the duration
+        const b = smooth(INFLATE_END, 1, u);
+        const burst = (1 + 0.22 * Math.sin(Math.PI * Math.min(1, b * 1.6))) * Math.pow(1 - b, 2);
+        const g = k * burst;
+        out.s.set(g * (1 + m1 - 0.5 * m2), g * (1 - m1), g * (1 + m2 - 0.5 * m1));
+    },
+    enter(v, out, a) {
+        const p = a.p;
+        // out of nothing: a quick spring past full size
+        const grow = 1 - Math.pow(1 - smooth(0, 0.22, v), 3);
+        const sg = Math.max(0, (v - 0.12) / 0.88);
+        const n = Number(p.rings);
+        const r = 0.22 * ring(sg, n / 2, 3.4); // overshoots first, rings down to exactly 1
+        // the ring alternates which way it bulges (the same shape modes as the exit)
+        const w = Number(p.wobble) * 1.8 * ring(sg, n / 2 + 0.25, 3.4);
+        const g = grow * (1 + r);
+        out.s.set(g * (1 + w), g * (1 - w), g * (1 + 0.6 * w));
+    },
+});

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

@@ -1 +1 @@
-{"version":3,"file":"print3d.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/print3d.ts"],"names":[],"mappings":";AA8MA,wBAgFG"}
+{"version":3,"file":"print3d.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/print3d.ts"],"names":[],"mappings":";AA+MA,wBAmFG"}