@3driseai/3drise-viewer 0.1.25 → 0.1.27

package/dist/operations/catalogue/ivy.js

@@ -0,0 +1,469 @@
+// Ivy — vines grow over the object. The growth is space colonisation (the
+// branching algorithm used for trees and leaf veins): surface samples are the
+// attractors, each vine tip steps towards the attractors nearest to it and
+// consumes them, and every new node is snapped back onto the surface, so the
+// vines creep over the object's real shape, branching where there is room.
+// Stems are lit tubes that thicken towards the root (pipe model); ivy leaves
+// (five-lobed, cupped, veined) unfurl from folded as the tip passes, and sway
+// gently while it holds. A state, not an exit: reverting withers the ivy — the
+// leaves brown, droop and fall away, and the vines draw back to their roots.
+import { gsap } from 'gsap';
+import { BufferAttribute, BufferGeometry, Color, Matrix4, Mesh, MeshStandardMaterial, Shape, ShapeGeometry, SplineCurve, Vector2, Vector3, } from 'three';
+import { defineOperation } from '../types.js';
+import { GLSL_ROT, addLayer } from './shaderLayers.js';
+import { createFieldState, fieldUniforms, runProgress } from './transitionField.js';
+import { mulberry32, sampleSurfaceCached } from './surfaceSample.js';
+import { createFxInstances, disposeFxInstances } from './fxInstances.js';
+import { hideUntilWarm } from './warmup.js';
+const P = 'Ivy';
+const STATE = '__opIvy';
+/** Growth runs over progress 0..GROW; the last leaves unfurl by 1. */
+const GROW = 0.8;
+const UNFURL = 0.14;
+class Grid {
+    size;
+    cells = new Map();
+    constructor(size) {
+        this.size = size;
+    }
+    k(x, y, z) { return `${Math.floor(x / this.size)},${Math.floor(y / this.size)},${Math.floor(z / this.size)}`; }
+    add(i, x, y, z) { const k = this.k(x, y, z); const c = this.cells.get(k); if (c)
+        c.push(i);
+    else
+        this.cells.set(k, [i]); }
+    near(x, y, z, fn) {
+        const cx = Math.floor(x / this.size), cy = Math.floor(y / this.size), cz = Math.floor(z / this.size);
+        for (let a = -1; a <= 1; a++)
+            for (let b = -1; b <= 1; b++)
+                for (let c = -1; c <= 1; c++) {
+                    const l = this.cells.get(`${cx + a},${cy + b},${cz + c}`);
+                    if (l)
+                        for (const i of l)
+                            fn(i);
+                }
+    }
+}
+export function grow(sample, extent, attractors, from, seed) {
+    const rnd = mulberry32(seed);
+    const E = extent, D = 0.02 * E, DI = 0.11 * E, DK = 0.036 * E, OFF = 0.006 * E;
+    const S = sample.position, SN = sample.normal, N = sample.count;
+    const snapGrid = new Grid(0.05 * E);
+    for (let i = 0; i < N; i++)
+        snapGrid.add(i, S[i * 3], S[i * 3 + 1], S[i * 3 + 2]);
+    const A = Math.min(N, attractors);
+    // samples come mesh by mesh: take a random subset so every part of the object attracts
+    const AI = new Int32Array(N).map((_, i) => i);
+    for (let i = N - 1; i > 0; i--) {
+        const j = Math.floor(rnd() * (i + 1));
+        const t = AI[i];
+        AI[i] = AI[j];
+        AI[j] = t;
+    }
+    const alive = new Uint8Array(A).fill(1);
+    // each attractor remembers its nearest node within reach; only new nodes can change that
+    const nearest = new Int32Array(A).fill(-1);
+    const nearD = new Float32Array(A).fill(Infinity);
+    const attGrid = new Grid(DI);
+    for (let i = 0; i < A; i++)
+        attGrid.add(i, S[AI[i] * 3], S[AI[i] * 3 + 1], S[AI[i] * 3 + 2]);
+    const g = { pos: [], nrm: [], parent: [], birth: [], desc: [], count: 0 };
+    const len = [];
+    const addNode = (p, n, parent, l) => {
+        const i = g.count++;
+        g.pos.push(p.x, p.y, p.z);
+        g.nrm.push(n.x, n.y, n.z);
+        g.parent.push(parent);
+        len.push(l);
+        attGrid.near(p.x, p.y, p.z, (a) => {
+            if (!alive[a])
+                return;
+            const s = AI[a];
+            const d = (S[s * 3] - p.x) ** 2 + (S[s * 3 + 1] - p.y) ** 2 + (S[s * 3 + 2] - p.z) ** 2;
+            if (d < DK * DK) {
+                alive[a] = 0;
+                nearest[a] = -1;
+                return;
+            }
+            if (d >= DI * DI || d >= nearD[a])
+                return;
+            // only along the surface: never through the volume to the far side of a wall or tube
+            if (SN[s * 3] * n.x + SN[s * 3 + 1] * n.y + SN[s * 3 + 2] * n.z < 0.3)
+                return;
+            const dl = Math.sqrt(d) || 1;
+            if (Math.abs(((S[s * 3] - p.x) * n.x + (S[s * 3 + 1] - p.y) * n.y + (S[s * 3 + 2] - p.z) * n.z) / dl) > 0.6)
+                return;
+            nearD[a] = d;
+            nearest[a] = i;
+        });
+        return i;
+    };
+    const snap = (p, n) => {
+        let best = -1, bd = Infinity;
+        snapGrid.near(p.x, p.y, p.z, (i) => {
+            const d = (S[i * 3] - p.x) ** 2 + (S[i * 3 + 1] - p.y) ** 2 + (S[i * 3 + 2] - p.z) ** 2;
+            if (d < bd) {
+                bd = d;
+                best = i;
+            }
+        });
+        if (best < 0)
+            return false;
+        const s = new Vector3(S[best * 3], S[best * 3 + 1], S[best * 3 + 2]);
+        n.set(SN[best * 3], SN[best * 3 + 1], SN[best * 3 + 2]);
+        const d = p.clone().sub(s);
+        p.copy(s).add(d.sub(n.clone().multiplyScalar(d.dot(n)))).addScaledVector(n, OFF);
+        return true;
+    };
+    // roots: spread apart among the lowest (or highest, or any) samples
+    let minY = Infinity, maxY = -Infinity;
+    for (let i = 0; i < N; i++) {
+        minY = Math.min(minY, S[i * 3 + 1]);
+        maxY = Math.max(maxY, S[i * 3 + 1]);
+    }
+    const band = (maxY - minY) * 0.08;
+    const cand = [];
+    for (let i = 0; i < N; i++) {
+        const y = S[i * 3 + 1];
+        if (SN[i * 3 + 1] > -0.3 && (from === 'up' ? y < minY + band : from === 'down' ? y > maxY - band : rnd() < 0.02))
+            cand.push(i);
+    }
+    const roots = [];
+    const want = from === 'noise' ? 6 : 4;
+    if (cand.length)
+        roots.push(cand[Math.floor(rnd() * cand.length)]);
+    while (roots.length < want && roots.length < cand.length) {
+        let bi = -1, bd = -1;
+        for (const c of cand) {
+            let dm = Infinity;
+            for (const r of roots)
+                dm = Math.min(dm, (S[c * 3] - S[r * 3]) ** 2 + (S[c * 3 + 1] - S[r * 3 + 1]) ** 2 + (S[c * 3 + 2] - S[r * 3 + 2]) ** 2);
+            if (dm > bd) {
+                bd = dm;
+                bi = c;
+            }
+        }
+        roots.push(bi);
+    }
+    for (const r of roots)
+        addNode(new Vector3(S[r * 3], S[r * 3 + 1], S[r * 3 + 2]).addScaledVector(new Vector3(SN[r * 3], SN[r * 3 + 1], SN[r * 3 + 2]), OFF), new Vector3(SN[r * 3], SN[r * 3 + 1], SN[r * 3 + 2]), -1, 0);
+    const trop = from === 'up' ? 0.25 : from === 'down' ? -0.35 : 0;
+    const MAX = 4200;
+    // a node never grows two children the same way (the classic stuck-node repeat)
+    const childDirs = new Map();
+    for (let it = 0; it < 500 && g.count < MAX; it++) {
+        const pull = new Map();
+        for (let a = 0; a < A; a++) {
+            const bn = nearest[a];
+            if (bn < 0 || !alive[a])
+                continue;
+            const sa = AI[a];
+            const v = new Vector3(S[sa * 3] - g.pos[bn * 3], S[sa * 3 + 1] - g.pos[bn * 3 + 1], S[sa * 3 + 2] - g.pos[bn * 3 + 2]).normalize();
+            const acc = pull.get(bn);
+            if (acc)
+                acc.add(v);
+            else
+                pull.set(bn, v);
+        }
+        if (!pull.size)
+            break;
+        let grew = 0;
+        for (const [i, v] of pull) {
+            if (g.count >= MAX)
+                break;
+            const n = new Vector3(g.nrm[i * 3], g.nrm[i * 3 + 1], g.nrm[i * 3 + 2]);
+            const d = v.normalize().add(new Vector3(0, trop, 0)).add(new Vector3(rnd() - 0.5, rnd() - 0.5, rnd() - 0.5).multiplyScalar(0.3));
+            d.sub(n.clone().multiplyScalar(d.dot(n)));
+            if (d.lengthSq() < 1e-8)
+                continue;
+            d.normalize();
+            const dirs = childDirs.get(i) ?? [];
+            if (dirs.length >= 3 || dirs.some(c => c.dot(d) > 0.94))
+                continue;
+            dirs.push(d.clone());
+            childDirs.set(i, dirs);
+            const p = new Vector3(g.pos[i * 3], g.pos[i * 3 + 1], g.pos[i * 3 + 2]).addScaledVector(d.normalize(), D);
+            const nn = new Vector3();
+            if (!snap(p, nn))
+                continue;
+            // a snap that jumps a gap (onto another part) would draw a vine through the air
+            const step = Math.hypot(p.x - g.pos[i * 3], p.y - g.pos[i * 3 + 1], p.z - g.pos[i * 3 + 2]);
+            if (step > D * 1.8 || nn.dot(n) < 0.2)
+                continue;
+            addNode(p, nn, i, len[i] + D);
+            grew++;
+        }
+        if (!grew)
+            break;
+    }
+    let maxLen = 1e-6;
+    for (const l of len)
+        maxLen = Math.max(maxLen, l);
+    g.birth = len.map(l => (l / maxLen) * GROW);
+    g.desc = new Array(g.count).fill(0);
+    for (let i = g.count - 1; i >= 0; i--)
+        if (g.parent[i] >= 0)
+            g.desc[g.parent[i]] += g.desc[i] + 1;
+    return g;
+}
+const growthCache = new WeakMap();
+// ---------------------------------------------------------------- geometry
+const SIDES = 6;
+function stemGeometry(g, E) {
+    // short side stubs carry a leaf but no vine (ivy runs in long vines, not twigs)
+    const kids = new Array(g.count).fill(0);
+    for (const p of g.parent)
+        if (p >= 0)
+            kids[p]++;
+    const stub = new Uint8Array(g.count);
+    const segs = [];
+    for (let i = 0; i < g.count; i++) {
+        const p = g.parent[i];
+        if (p < 0)
+            continue;
+        stub[i] = stub[p] || (g.desc[i] < 3 && kids[p] > 1) ? 1 : 0; // parents come first
+        if (!stub[i])
+            segs.push(i);
+    }
+    const vc = segs.length * 2 * SIDES;
+    const pos = new Float32Array(vc * 3), nrm = new Float32Array(vc * 3), ctr = new Float32Array(vc * 3), from = new Float32Array(vc * 3);
+    const rad = new Float32Array(vc * 3), bir = new Float32Array(vc * 2);
+    const idx = [];
+    const radius = (i) => Math.min(E * 0.0015 * Math.pow(1 + g.desc[i], 0.33), E * 0.0075);
+    const a = new Vector3(), b = new Vector3(), t = new Vector3(), n = new Vector3(), u = new Vector3(), w = new Vector3(), o = new Vector3();
+    let v = 0;
+    segs.forEach((c, si) => {
+        const pi = g.parent[c];
+        a.set(g.pos[pi * 3], g.pos[pi * 3 + 1], g.pos[pi * 3 + 2]);
+        b.set(g.pos[c * 3], g.pos[c * 3 + 1], g.pos[c * 3 + 2]);
+        t.subVectors(b, a).normalize();
+        n.set(g.nrm[c * 3], g.nrm[c * 3 + 1], g.nrm[c * 3 + 2]);
+        u.crossVectors(t, n);
+        if (u.lengthSq() < 1e-8)
+            u.set(1, 0, 0).cross(t);
+        u.normalize();
+        w.crossVectors(u, t).normalize();
+        for (let end = 0; end < 2; end++) {
+            const node = end ? c : pi;
+            const r = radius(node);
+            const cen = end ? b : a;
+            for (let k = 0; k < SIDES; k++) {
+                const ang = (k / SIDES) * Math.PI * 2;
+                o.copy(u).multiplyScalar(Math.cos(ang)).addScaledVector(w, Math.sin(ang));
+                pos.set([cen.x + o.x * r, cen.y + o.y * r, cen.z + o.z * r], v * 3);
+                nrm.set([o.x, o.y, o.z], v * 3);
+                ctr.set([cen.x, cen.y, cen.z], v * 3);
+                from.set([a.x, a.y, a.z], v * 3);
+                rad.set([o.x * r, o.y * r, o.z * r], v * 3);
+                bir.set([g.birth[pi], g.birth[c]], v * 2);
+                v++;
+            }
+        }
+        const base = si * 2 * SIDES;
+        for (let k = 0; k < SIDES; k++) {
+            const k2 = (k + 1) % SIDES;
+            idx.push(base + k, base + k2, base + SIDES + k, base + k2, base + SIDES + k2, base + SIDES + k);
+        }
+    });
+    const geo = new BufferGeometry();
+    geo.setAttribute('position', new BufferAttribute(pos, 3));
+    geo.setAttribute('normal', new BufferAttribute(nrm, 3));
+    geo.setAttribute('aIvyCtr', new BufferAttribute(ctr, 3));
+    geo.setAttribute('aIvyFrom', new BufferAttribute(from, 3));
+    geo.setAttribute('aIvyRad', new BufferAttribute(rad, 3));
+    geo.setAttribute('aIvyB', new BufferAttribute(bir, 2));
+    geo.setIndex(idx);
+    return geo;
+}
+/** A five-lobed ivy leaf in the XY plane, petiole at the origin, blade along +Y (length 1). */
+function leafGeometry() {
+    const lobes = [
+        [180, 0.14], [150, 0.52], [124, 0.5], [98, 0.72], [72, 0.6], [44, 0.84], [22, 0.76], [0, 1.0],
+    ];
+    const pts = [];
+    const add = (deg, r) => { const a = (deg * Math.PI) / 180; pts.push(new Vector2(Math.sin(a) * r * 0.55, 0.42 + Math.cos(a) * r * 0.58)); };
+    for (const [d, r] of lobes)
+        add(d, r);
+    for (let i = lobes.length - 2; i >= 1; i--)
+        add(-lobes[i][0], lobes[i][1]);
+    add(-180, 0.12);
+    const curve = new SplineCurve(pts);
+    const shape = new Shape(curve.getPoints(44));
+    const geo = new ShapeGeometry(shape, 1);
+    geo.translate(0, -0.05, 0);
+    geo.computeVertexNormals();
+    return geo;
+}
+// ---------------------------------------------------------------- the operation
+export default defineOperation({
+    value: 'ivy',
+    label: 'Ivy',
+    description: 'Grow ivy over the targets — vines creep along the surface and leaves unfurl; reverting withers it away',
+    channel: 'visual',
+    multi: true,
+    toggles: true,
+    usableIn: ['interaction', 'action', 'object'],
+    params: {
+        from: { type: 'select', label: 'Grows from', default: 'up', options: [{ value: 'up', label: 'The base' }, { value: 'down', label: 'The top' }, { value: 'noise', label: 'Scattered roots' }] },
+        coverage: { type: 'number', label: 'Coverage', default: 0.55, min: 0.05, max: 1, step: 0.01 },
+        leafSize: { type: 'number', label: 'Leaf size', default: 1, min: 0.3, max: 3, step: 0.05, unit: '×' },
+        leaves: { type: 'number', label: 'Leaves', default: 0.6, min: 0, max: 1, step: 0.01, hint: 'Share of the nodes that carry a leaf' },
+        leafColor: { type: 'color', label: 'Leaves', default: '#2f5a1f' },
+        stemColor: { type: 'color', label: 'Vines', default: '#4a3a24' },
+        duration: { type: 'number', label: 'Duration', default: 5, min: 0.3, max: 20, step: 0.1, unit: 's' },
+    },
+    apply(target, p) {
+        const key = `${p.from}|${p.coverage}|${p.leafSize}|${p.leaves}`;
+        let st = target.userData[STATE];
+        let keep;
+        if (st && st.key !== key) {
+            // the shape of the growth changed (object-effect edit): rebuild on the same field (same progress, same clock)
+            disposeIvy(st);
+            keep = st.field;
+            delete target.userData[STATE];
+            st = undefined;
+        }
+        if (!st) {
+            const field = keep ?? createFieldState(target);
+            const E = field.extent.value;
+            const sample = sampleSurfaceCached(target, 9000, 61);
+            const cached = growthCache.get(target);
+            const gkey = `${p.from}|${p.coverage}|${sample.count}|${E.toFixed(4)}`;
+            const g = cached?.key === gkey ? cached.g : grow(sample, E, Math.round(500 + Number(p.coverage) * 3500), String(p.from), 71);
+            growthCache.set(target, { key: gkey, g });
+            const own = {
+                field, key, leaf: { value: new Color() }, stem: { value: new Color() }, wither: { value: 0 }, sway: { value: 1 },
+            };
+            // stems
+            const stemMat = new MeshStandardMaterial({ roughness: 0.75, metalness: 0 });
+            addLayer(stemMat, 'ivyStem', {
+                uniforms: { ...fieldUniforms(P, field), uIvyStem: own.stem, uIvyWither: own.wither },
+                common: 'varying float vIvyYoung;',
+                vertexPars: 'attribute vec3 aIvyCtr; attribute vec3 aIvyFrom; attribute vec3 aIvyRad; attribute vec2 aIvyB;',
+                vertex: /* glsl */ `
+                {
+                  float pr = uIvyProgress;
+                  float gr = clamp((pr - aIvyB.x) / max(aIvyB.y - aIvyB.x, 1e-5), 0.0, 1.0);
+                  float thick = pr <= aIvyB.x ? 0.0 : (0.35 + 0.65 * smoothstep(aIvyB.x, aIvyB.x + 0.25, pr));
+                  transformed = mix(aIvyFrom, aIvyCtr, gr) + aIvyRad * thick;
+                  vIvyYoung = 1.0 - smoothstep(0.0, 0.3, pr - aIvyB.y);
+                }`,
+                // fresh growth is green, older vine woody
+                diffuse: `diffuseColor.rgb = mix(mix(uIvyStem, vec3(0.2, 0.3, 0.08), vIvyYoung * 0.8), uIvyStem * vec3(0.7, 0.6, 0.5), uIvyWither);`,
+            }, { immediate: true });
+            own.stems = new Mesh(stemGeometry(g, E), stemMat);
+            own.stems.castShadow = true;
+            own.stems.receiveShadow = true;
+            own.stems.frustumCulled = false;
+            own.stems.userData.__opFxHelper = true;
+            own.stems.raycast = () => { };
+            target.add(own.stems);
+            hideUntilWarm(own.stems);
+            // leaves: on a share of the nodes, oriented along the growth, lifted off the surface
+            const rnd = mulberry32(83);
+            const picks = [];
+            for (let i = 0; i < g.count; i++)
+                if (g.parent[i] >= 0 && rnd() < Number(p.leaves))
+                    picks.push(i);
+            const count = Math.max(1, picks.length);
+            const positions = new Float32Array(count * 3), colors = new Float32Array(count * 3), births = new Float32Array(count), rands = new Float32Array(count * 4);
+            const mats = [];
+            const t = new Vector3(), n = new Vector3(), x = new Vector3(), y = new Vector3(), z = new Vector3(), side = new Vector3();
+            picks.forEach((i, k) => {
+                const pi = g.parent[i];
+                t.set(g.pos[i * 3] - g.pos[pi * 3], g.pos[i * 3 + 1] - g.pos[pi * 3 + 1], g.pos[i * 3 + 2] - g.pos[pi * 3 + 2]).normalize();
+                n.set(g.nrm[i * 3], g.nrm[i * 3 + 1], g.nrm[i * 3 + 2]);
+                side.crossVectors(n, t);
+                const th = (rnd() - 0.5) * 2.4;
+                y.copy(t).multiplyScalar(Math.cos(th)).addScaledVector(side, Math.sin(th)).addScaledVector(n, 0.55 + 0.4 * rnd()).normalize();
+                x.crossVectors(y, n).normalize();
+                z.crossVectors(x, y).normalize();
+                const young = 1 - g.birth[i] / GROW;
+                const s = E * 0.052 * Number(p.leafSize) * (0.55 + 0.5 * rnd()) * (0.75 + 0.4 * young);
+                const m = new Matrix4().makeBasis(x.multiplyScalar(s), y.multiplyScalar(s), z.multiplyScalar(s));
+                m.setPosition(g.pos[i * 3] + n.x * E * 0.004, g.pos[i * 3 + 1] + n.y * E * 0.004, g.pos[i * 3 + 2] + n.z * E * 0.004);
+                mats.push(m);
+                positions.set([g.pos[i * 3], g.pos[i * 3 + 1], g.pos[i * 3 + 2]], k * 3);
+                const v = 0.75 + 0.45 * rnd();
+                colors.set([v * (0.9 + 0.2 * rnd()), v, v * (0.85 + 0.2 * rnd())], k * 3);
+                births[k] = g.birth[i] + 0.02;
+                rands.set([rnd(), rnd(), rnd(), rnd()], k * 4);
+            });
+            own.leaves = createFxInstances(target, {
+                geometry: leafGeometry(), count, positions, colors,
+                attributes: { aIvyLB: [births, 1], aIvyLR: [rands, 4] },
+                layerKey: 'ivyLeaves', roughness: 0.42, metalness: 0, doubleSided: true,
+                layer: {
+                    uniforms: { ...fieldUniforms(P, field), uIvyLeaf: own.leaf, uIvyWither: own.wither, uIvySway: own.sway },
+                    common: `varying vec2 vIvyUv;\nvarying float vIvyAge;\n${GLSL_ROT}`,
+                    vertexPars: /* glsl */ `
+                    attribute float aIvyLB; attribute vec4 aIvyLR;
+                    mat3 ivyPose(vec3 p) {
+                      float g = smoothstep(aIvyLB, aIvyLB + ${UNFURL.toFixed(2)}, uIvyProgress);
+                      // unfurl: the halves open about the midrib, the blade lifts from the stem
+                      float fold = (1.0 - g) * 1.25 * sign(p.x);
+                      float sway = uIvySway * (sin(uIvyTime * (1.1 + aIvyLR.x) + aIvyLR.y * 6.28) * 0.07 + sin(uIvyTime * 2.7 + aIvyLR.z * 6.28) * 0.03);
+                      float droop = uIvyWither * (0.6 + 0.6 * aIvyLR.w);
+                      return fxRot(vec3(1.0, 0.0, 0.0), (1.0 - g) * 0.9 + sway + droop) * fxRot(vec3(0.0, 1.0, 0.0), fold);
+                    }`,
+                    normal: `objectNormal = ivyPose(position) * objectNormal;`,
+                    vertex: /* glsl */ `
+                    {
+                      vIvyUv = position.xy;
+                      float g = smoothstep(aIvyLB, aIvyLB + ${UNFURL.toFixed(2)}, uIvyProgress);
+                      vIvyAge = g;
+                      vec3 p = transformed;
+                      p.z += 0.09 * p.x * p.x - 0.04 * p.y;                       // cupped across the midrib
+                      transformed = ivyPose(position) * p * g;
+                    }`,
+                    diffuse: /* glsl */ `
+                    {
+                      // veins: a pale midrib and lateral veins running out to the lobes
+                      vec2 u = vIvyUv;
+                      float mid = 1.0 - smoothstep(0.0, 0.018, abs(u.x)) ;
+                      float ang = atan(u.x, u.y - 0.05);
+                      float lat = 1.0 - smoothstep(0.0, 0.05, abs(fract(ang / 0.62 + 0.5) - 0.5) * length(u));
+                      float vein = max(mid * step(0.0, u.y), lat * 0.6) * smoothstep(0.02, 0.2, length(u - vec2(0.0, 0.05)));
+                      vec3 leaf = uIvyLeaf * diffuseColor.rgb;                  // instance colour carries the variation
+                      leaf = mix(leaf, leaf * 1.7 + vec3(0.05, 0.06, 0.02), vein * 0.55);
+                      // young leaves are lighter and fresher
+                      leaf = mix(leaf * vec3(1.25, 1.35, 1.0), leaf, vIvyAge);
+                      vec3 dry = mix(vec3(0.13, 0.08, 0.035), vec3(0.24, 0.15, 0.06), diffuseColor.g);
+                      diffuseColor.rgb = mix(leaf, dry, uIvyWither);
+                    }`,
+                },
+            });
+            mats.forEach((m, k) => own.leaves.setMatrixAt(k, m));
+            own.leaves.instanceMatrix.needsUpdate = true;
+            st = own;
+            target.userData[STATE] = st;
+        }
+        const s = st;
+        s.leaf.value.set(String(p.leafColor));
+        s.stem.value.set(String(p.stemColor));
+        gsap.killTweensOf(s.wither);
+        s.wither.value = 0;
+        return runProgress(target, s.field, 1, { duration: Number(p.duration), ease: 'power1.inOut', hold: true });
+    },
+    revert(target, p) {
+        const s = target.userData[STATE];
+        if (!s)
+            return;
+        const d = Number(p.duration);
+        gsap.killTweensOf(s.wither);
+        if (d > 0)
+            gsap.to(s.wither, { value: 1, duration: d * 0.35, ease: 'power1.out' });
+        else
+            s.wither.value = 1;
+        return runProgress(target, s.field, 0, {
+            duration: d, ease: 'power1.in',
+            onComplete: () => { disposeIvy(s); delete target.userData[STATE]; },
+        });
+    },
+});
+function disposeIvy(s) {
+    gsap.killTweensOf(s.wither);
+    s.stems.removeFromParent();
+    s.stems.geometry.dispose();
+    s.stems.material.dispose();
+    disposeFxInstances(s.leaves);
+}

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

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

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

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

package/dist/operations/catalogue/jelly.js

@@ -0,0 +1,50 @@
+// Jelly — a volume-preserving squash-and-stretch spring, anchored at the base:
+// it squashes first, then rings out like soft rubber (critically tuned so it
+// settles exactly at rest when the duration ends). One-shot.
+import { gsap } from 'gsap';
+import { Quaternion, Vector3 } from 'three';
+import { defineOperation } from '../types.js';
+import { acquireRest, poseAbout, releaseRest } from './restPose.js';
+const KEY = '__opJelly';
+const NO_TURN = new Quaternion();
+export default defineOperation({
+    value: 'jelly',
+    label: 'Jelly',
+    description: 'Squash and wobble like soft rubber, keeping its volume — settles back to rest',
+    channel: 'transform',
+    multi: true,
+    toggles: false,
+    usableIn: ['interaction', 'action'],
+    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 },
+        duration: { type: 'number', label: 'Duration', default: 1.1, min: 0.2, max: 5, step: 0.05, unit: 's' },
+    },
+    apply(target, p) {
+        const running = target.userData[KEY];
+        if (running) {
+            gsap.killTweensOf(running.proxy);
+            releaseRest(target);
+        }
+        const rest = acquireRest(target);
+        const proxy = { t: 0 };
+        target.userData[KEY] = { proxy };
+        const A = Number(p.strength);
+        const D = Number(p.duration);
+        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',
+            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);
+            },
+            onComplete: () => { delete target.userData[KEY]; releaseRest(target); },
+        });
+    },
+});

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

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

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

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