@3driseai/3drise-viewer 0.1.26 → 0.1.27

package/dist/operations/catalogue/silkDrape.js

@@ -0,0 +1,340 @@
+// Silk drape — the magician's reveal. A sheet of silk falls onto the object and
+// drapes over its real shape (a Verlet cloth — stretch, shear and bend
+// constraints — colliding with the object's own surface samples and the floor),
+// settles, and then collapses flat as the object vanishes beneath it, before the
+// silk itself fades away. Reverting is the reveal: the silk appears on the floor,
+// the object rises under it, and the cloth lifts off and away.
+// With Disappear off (always, as an object effect) it stays draped: the silk
+// settles over the object and holds there (the veiled sculpture), breathing
+// faintly as if in still air; reverting lifts it away.
+// The simulation is baked once per object (in the background, a few frames per
+// task — nothing freezes), then played back by progress, so it scrubs both ways.
+// The silk is a lit MeshPhysical with sheen and a light clearcoat, a faint dye
+// variation, and a soft dissolve at the ends.
+import { gsap } from 'gsap';
+import { BufferAttribute, BufferGeometry, Color, DoubleSide, Mesh, MeshPhysicalMaterial, Vector3 } from 'three';
+import { defineOperation } from '../types.js';
+import { GLSL_NOISE, addLayer } from './shaderLayers.js';
+import { createFieldState, fieldUniforms, hideMeshes, localBounds, runProgress } from './transitionField.js';
+import { mulberry32, sampleSurfaceCached } from './surfaceSample.js';
+import { hideUntilWarm } from './warmup.js';
+const P = 'Slk';
+const KEY = 'silkDrape';
+const STATE = '__opSilkDrape';
+const R = 44; // cloth resolution (R × R particles)
+const F = 150; // baked frames
+const SUB = 4; // substeps per frame
+const ITER = 4; // constraint iterations per substep
+/** Timeline (progress = frame / F): the object vanishes at HIDE, the silk fades from FADE. */
+const HIDE = 0.5;
+const SHRINK_END = 0.64;
+const FADE_IN = 0.07;
+const FADE = 0.85;
+/** Where the silk has settled over the object (before it vanishes) — the held pose. */
+const DRAPED = 0.47;
+const bakes = new WeakMap();
+const tick = () => new Promise(r => setTimeout(r, 0));
+/** Simulate the whole drape → collapse once, F frames of R×R positions (root-local). */
+async function bakeDrape(target, size, softness, seed) {
+    const b = localBounds(target);
+    const bs = b.getSize(new Vector3()), c = b.getCenter(new Vector3());
+    const E = Math.max(bs.length(), 1e-3);
+    const sample = sampleSurfaceCached(target, 7000, 97);
+    const S0 = sample.position.slice(0, sample.count * 3), SN = sample.normal, NS = sample.count;
+    const S = new Float32Array(S0);
+    const rc = 0.03 * E, th = 0.011 * E, floorY = b.min.y + th * 0.4;
+    // collider grid (rebuilt when the object shrinks)
+    let grid = new Map();
+    const key = (x, y, z) => `${Math.floor(x / rc)},${Math.floor(y / rc)},${Math.floor(z / rc)}`;
+    const build = () => {
+        grid = new Map();
+        for (let i = 0; i < NS; i++) {
+            const k = key(S[i * 3], S[i * 3 + 1], S[i * 3 + 2]);
+            const l = grid.get(k);
+            if (l)
+                l.push(i);
+            else
+                grid.set(k, [i]);
+        }
+    };
+    build();
+    // cloth: a square sheet above the object, turned a little so corners hang in points
+    const rnd = mulberry32(seed);
+    const L = (Math.max(bs.x, bs.z) * 1.1 + 1.05 * bs.y) * size;
+    const sp = L / (R - 1);
+    const yaw = 0.35 + rnd() * 0.3, cy = Math.cos(yaw), sy = Math.sin(yaw);
+    const N = R * R;
+    const pos = new Float32Array(N * 3), prev = new Float32Array(N * 3);
+    for (let j = 0; j < R; j++)
+        for (let i = 0; i < R; i++) {
+            const u = (i / (R - 1) - 0.5) * L, v = (j / (R - 1) - 0.5) * L;
+            const k = (j * R + i) * 3;
+            pos[k] = c.x + u * cy - v * sy;
+            pos[k + 1] = b.max.y + 0.12 * bs.y + (rnd() - 0.5) * sp * 0.05;
+            pos[k + 2] = c.z + u * sy + v * cy;
+        }
+    prev.set(pos);
+    // constraints: stretch, shear, bend
+    const cons = [];
+    const add = (a, bb, stiff) => {
+        const d = Math.hypot(pos[a * 3] - pos[bb * 3], pos[a * 3 + 1] - pos[bb * 3 + 1], pos[a * 3 + 2] - pos[bb * 3 + 2]);
+        cons.push(a, bb, d, stiff);
+    };
+    const bend = 0.05 + 0.4 * (1 - softness);
+    for (let j = 0; j < R; j++)
+        for (let i = 0; i < R; i++) {
+            const a = j * R + i;
+            if (i + 1 < R)
+                add(a, a + 1, 1);
+            if (j + 1 < R)
+                add(a, a + R, 1);
+            if (i + 1 < R && j + 1 < R) {
+                add(a, a + R + 1, 0.7);
+                add(a + 1, a + R, 0.7);
+            }
+            if (i + 2 < R)
+                add(a, a + 2, bend);
+            if (j + 2 < R)
+                add(a, a + 2 * R, bend);
+        }
+    const C = new Float32Array(cons);
+    const nc = cons.length / 4;
+    const g = 3.6 * E, dt = 1 / 60 / SUB, damp = 0.992;
+    const frames = new Float32Array(F * N * 3);
+    const anchor = new Vector3(c.x, b.min.y, c.z);
+    let lastK = 1;
+    for (let f = 0; f < F; f++) {
+        frames.set(pos, f * N * 3);
+        // the object shrinks away under the silk after it has settled
+        const t = f / (F - 1);
+        const x = Math.min(1, Math.max(0, (t - HIDE) / (SHRINK_END - HIDE)));
+        const k = 1 - x * x * (3 - 2 * x) * 0.985;
+        if (Math.abs(k - lastK) > 1e-4) {
+            for (let i = 0; i < NS; i++) {
+                S[i * 3] = anchor.x + (S0[i * 3] - anchor.x) * k;
+                S[i * 3 + 1] = anchor.y + (S0[i * 3 + 1] - anchor.y) * k;
+                S[i * 3 + 2] = anchor.z + (S0[i * 3 + 2] - anchor.z) * k;
+            }
+            build();
+            lastK = k;
+        }
+        for (let s = 0; s < SUB; s++) {
+            for (let p = 0; p < N; p++) {
+                const o = p * 3;
+                for (let a = 0; a < 3; a++) {
+                    const v = (pos[o + a] - prev[o + a]) * damp;
+                    prev[o + a] = pos[o + a];
+                    pos[o + a] += v + (a === 1 ? -g * dt * dt : 0);
+                }
+            }
+            for (let it = 0; it < ITER; it++) {
+                for (let q = 0; q < nc; q++) {
+                    const a = C[q * 4] * 3, bb = C[q * 4 + 1] * 3, rest = C[q * 4 + 2], st = C[q * 4 + 3];
+                    const dx = pos[bb] - pos[a], dy = pos[bb + 1] - pos[a + 1], dz = pos[bb + 2] - pos[a + 2];
+                    const d = Math.sqrt(dx * dx + dy * dy + dz * dz) || 1e-9;
+                    const m = ((d - rest) / d) * 0.5 * st;
+                    pos[a] += dx * m;
+                    pos[a + 1] += dy * m;
+                    pos[a + 2] += dz * m;
+                    pos[bb] -= dx * m;
+                    pos[bb + 1] -= dy * m;
+                    pos[bb + 2] -= dz * m;
+                }
+            }
+            // collide with the object (nearest surface sample, pushed out along its normal) and the floor
+            for (let p = 0; p < N; p++) {
+                const o = p * 3;
+                const px = pos[o], py = pos[o + 1], pz = pos[o + 2];
+                const gx = Math.floor(px / rc), gy = Math.floor(py / rc), gz = Math.floor(pz / rc);
+                let best = -1, bd = rc * rc;
+                for (let a = -1; a <= 1; a++)
+                    for (let bb = -1; bb <= 1; bb++)
+                        for (let cc = -1; cc <= 1; cc++) {
+                            const l = grid.get(`${gx + a},${gy + bb},${gz + cc}`);
+                            if (!l)
+                                continue;
+                            for (const i of l) {
+                                const d = (S[i * 3] - px) ** 2 + (S[i * 3 + 1] - py) ** 2 + (S[i * 3 + 2] - pz) ** 2;
+                                if (d < bd) {
+                                    bd = d;
+                                    best = i;
+                                }
+                            }
+                        }
+                let hit = false;
+                if (best >= 0) {
+                    const nx = SN[best * 3], ny = SN[best * 3 + 1], nz = SN[best * 3 + 2];
+                    const dn = (px - S[best * 3]) * nx + (py - S[best * 3 + 1]) * ny + (pz - S[best * 3 + 2]) * nz;
+                    if (dn < th) {
+                        const push = th - dn;
+                        pos[o] += nx * push;
+                        pos[o + 1] += ny * push;
+                        pos[o + 2] += nz * push;
+                        hit = true;
+                    }
+                }
+                if (pos[o + 1] < floorY) {
+                    pos[o + 1] = floorY;
+                    hit = true;
+                }
+                if (hit) { // friction: silk clings where it touches
+                    for (let a = 0; a < 3; a++)
+                        prev[o + a] = pos[o + a] - (pos[o + a] - prev[o + a]) * 0.35;
+                }
+            }
+        }
+        if (f % 6 === 5)
+            await tick();
+    }
+    return frames;
+}
+function clothGeometry() {
+    const geo = new BufferGeometry();
+    const N = R * R;
+    const uv = new Float32Array(N * 2);
+    for (let j = 0; j < R; j++)
+        for (let i = 0; i < R; i++) {
+            uv[(j * R + i) * 2] = i / (R - 1);
+            uv[(j * R + i) * 2 + 1] = j / (R - 1);
+        }
+    const idx = [];
+    for (let j = 0; j < R - 1; j++)
+        for (let i = 0; i < R - 1; i++) {
+            const a = j * R + i;
+            idx.push(a, a + R, a + 1, a + 1, a + R, a + R + 1);
+        }
+    geo.setAttribute('position', new BufferAttribute(new Float32Array(N * 3), 3));
+    geo.setAttribute('normal', new BufferAttribute(new Float32Array(N * 3), 3));
+    geo.setAttribute('uv', new BufferAttribute(uv, 2));
+    geo.setIndex(idx);
+    return geo;
+}
+/** Show the baked frame for the current progress (interpolated) and the object's visibility. */
+function pose(target, s) {
+    if (!s.bake)
+        return;
+    const pr = Math.min(1, Math.max(0, s.field.progress.value));
+    const f = pr * (F - 1), f0 = Math.floor(f), f1 = Math.min(F - 1, f0 + 1), w = f - f0;
+    const N = R * R * 3;
+    const fr = s.bake.frames;
+    const attr = s.mesh.geometry.getAttribute('position');
+    const arr = attr.array;
+    for (let i = 0; i < N; i++)
+        arr[i] = fr[f0 * N + i] * (1 - w) + fr[f1 * N + i] * w;
+    attr.needsUpdate = true;
+    s.mesh.geometry.computeVertexNormals();
+    s.mesh.geometry.computeBoundingSphere();
+    s.fade.value = smooth(0, FADE_IN, pr) * (1 - smooth(FADE, 1, pr));
+    hideMeshes(target, KEY, pr >= HIDE);
+}
+const smooth = (a, b, x) => { const t = Math.min(1, Math.max(0, (x - a) / (b - a))); return t * t * (3 - 2 * t); };
+export default defineOperation({
+    value: 'silkDrape',
+    label: 'Silk drape',
+    description: 'Drop a silk sheet over the targets; it drapes, then collapses as they vanish — reverting is the reveal: the silk lifts off and away',
+    channel: 'visual',
+    multi: true,
+    toggles: true,
+    usableIn: ['interaction', 'action', 'object'],
+    params: {
+        color: { type: 'color', label: 'Silk', default: '#6a0f24' },
+        sheen: { type: 'color', label: 'Sheen', default: '#e07a8e' },
+        size: { type: 'number', label: 'Sheet size', default: 1, min: 0.6, max: 1.8, step: 0.05, unit: '×' },
+        softness: { type: 'number', label: 'Softness', default: 0.7, min: 0, max: 1, step: 0.01, hint: 'Stiff taffeta → liquid silk' },
+        duration: { type: 'number', label: 'Duration', default: 5.5, min: 0.3, max: 16, step: 0.1, unit: 's' },
+        disappear: { type: 'boolean', label: 'Disappear', default: true, hint: 'Off: the silk stays draped over the object (it holds there)' },
+    },
+    objectParams: { disappear: false },
+    apply(target, p) {
+        const key = `${p.size}|${p.softness}`;
+        let st = target.userData[STATE];
+        if (!st) {
+            const field = createFieldState(target);
+            const color = { value: new Color() }, fade = { value: 0 }, air = { value: 0 };
+            const mat = new MeshPhysicalMaterial({
+                color: 0xffffff, roughness: 0.36, metalness: 0, sheen: 0.7, sheenRoughness: 0.4, side: DoubleSide,
+                specularIntensity: 0.8, clearcoat: 0.15, clearcoatRoughness: 0.4,
+            });
+            addLayer(mat, 'silkCloth', {
+                uniforms: { ...fieldUniforms(P, field), uSlkColor: color, uSlkFade: fade, uSlkAir: air },
+                common: `varying vec2 vSlkUv;\n${GLSL_NOISE}`,
+                vertex: /* glsl */ `
+                vSlkUv = uv;
+                // held: the silk breathes faintly, as if in still air
+                transformed += normal * (uSlkAir * uSlkExtent * 0.0022 * sin(uSlkTime * 1.4 + uv.x * 11.0 + uv.y * 7.0) * (0.5 + 0.5 * sin(uSlkTime * 0.6 + uv.y * 4.0)));`,
+                diffuse: /* glsl */ `
+                {
+                  // soft dissolve at both ends of the run
+                  float n = fxFbm(vec3(vSlkUv * 7.0, 1.3));
+                  if (n > uSlkFade * 1.08) discard;
+                  // a faint dye variation, like real silk
+                  diffuseColor.rgb = uSlkColor * (0.94 + 0.12 * fxFbm(vec3(vSlkUv * 3.0, 7.0)));
+                }`,
+            }, { immediate: true });
+            const mesh = new Mesh(clothGeometry(), mat);
+            mesh.castShadow = true; // (no self-shadow: shadow acne on thin cloth)
+            mesh.frustumCulled = false;
+            mesh.userData.__opFxHelper = true;
+            mesh.raycast = () => { };
+            target.add(mesh);
+            hideUntilWarm(mesh);
+            st = { field, color, sheen: mat.sheenColor, fade, air, mesh, bake: null, ready: Promise.resolve(), key: '' };
+            target.userData[STATE] = st;
+        }
+        const s = st;
+        s.color.value.set(String(p.color));
+        s.sheen.set(String(p.sheen));
+        if (s.key !== key) {
+            s.key = key;
+            const cached = bakes.get(target);
+            if (cached?.key === key) {
+                s.bake = cached;
+                s.ready = Promise.resolve();
+            }
+            else {
+                s.bake = null;
+                s.ready = bakeDrape(target, Number(p.size), Number(p.softness), 11).then(frames => {
+                    const bk = { key, frames };
+                    bakes.set(target, bk);
+                    if (s.key === key)
+                        s.bake = bk;
+                });
+            }
+        }
+        pose(target, s);
+        gsap.killTweensOf(s.air);
+        if (p.disappear === false) {
+            return runProgress(target, s.field, DRAPED, {
+                duration: Number(p.duration) * DRAPED, ease: 'none', ready: s.ready, hold: true,
+                onUpdate: () => pose(target, s),
+                onComplete: () => { pose(target, s); gsap.to(s.air, { value: 1, duration: 1.5, ease: 'power1.inOut' }); },
+            });
+        }
+        s.air.value = 0;
+        return runProgress(target, s.field, 1, {
+            duration: Number(p.duration), ease: 'none', ready: s.ready,
+            onUpdate: () => pose(target, s),
+            onComplete: () => { pose(target, s); s.mesh.visible = false; },
+        });
+    },
+    revert(target, p) {
+        const s = target.userData[STATE];
+        if (!s)
+            return;
+        s.mesh.visible = true;
+        gsap.killTweensOf(s.air);
+        s.air.value = 0;
+        return runProgress(target, s.field, 0, {
+            // from the held drape it only has that part of the timeline to play back
+            duration: Number(p.duration) * Math.max(0.05, s.field.progress.value), ease: 'none', ready: s.ready,
+            onUpdate: () => pose(target, s),
+            onComplete: () => {
+                hideMeshes(target, KEY, false);
+                s.mesh.removeFromParent();
+                s.mesh.geometry.dispose();
+                s.mesh.material.dispose();
+                delete target.userData[STATE];
+            },
+        });
+    },
+});

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

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

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

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

package/dist/operations/catalogue/spin.js

@@ -0,0 +1,42 @@
+// Spin — the target turns a whole number of times about one of its own local
+// axes and lands exactly where it started. One-shot: triggering again spins again.
+import { gsap } from 'gsap';
+import { Quaternion, Vector3 } from 'three';
+import { defineOperation } from '../types.js';
+const KEY = '__opSpin';
+const AXES = { x: new Vector3(1, 0, 0), y: new Vector3(0, 1, 0), z: new Vector3(0, 0, 1) };
+export default defineOperation({
+    value: 'spin',
+    label: 'Spin',
+    description: 'Turn the target a full turn (or more) about its own axis, landing where it started',
+    channel: 'transform',
+    multi: true,
+    toggles: false,
+    usableIn: ['interaction', 'action'],
+    params: {
+        axis: { type: 'select', label: 'Axis', default: 'y', options: [{ value: 'y', label: 'Up (Y)' }, { value: 'x', label: 'Side (X)' }, { value: 'z', label: 'Front (Z)' }] },
+        turns: { type: 'number', label: 'Turns', default: 1, min: 1, max: 10, step: 1 },
+        reverse: { type: 'boolean', label: 'Reverse', default: false },
+        duration: { type: 'number', label: 'Duration', default: 1.2, min: 0.1, max: 20, step: 0.05, unit: 's' },
+    },
+    apply(target, p) {
+        // A spin already running is finished first, so the rest pose is never lost.
+        const running = target.userData[KEY];
+        if (running) {
+            gsap.killTweensOf(running.proxy);
+            target.quaternion.copy(running.rest);
+        }
+        const axis = AXES[String(p.axis)] ?? AXES.y;
+        const st = { rest: target.quaternion.clone(), proxy: { angle: 0 } };
+        target.userData[KEY] = st;
+        const turn = new Quaternion();
+        const turns = Math.max(1, Math.round(Number(p.turns)));
+        gsap.to(st.proxy, {
+            angle: (p.reverse ? -1 : 1) * turns * Math.PI * 2,
+            duration: Number(p.duration), ease: 'power2.inOut',
+            // rest · turn(axis, a) = a turn about the object's own axis
+            onUpdate: () => { target.quaternion.copy(st.rest).multiply(turn.setFromAxisAngle(axis, st.proxy.angle)); },
+            onComplete: () => { target.quaternion.copy(st.rest); delete target.userData[KEY]; },
+        });
+    },
+});

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

@@ -0,0 +1,17 @@
+import type { Object3D } from 'three';
+export interface SurfaceSample {
+    count: number;
+    /** xyz root-local */
+    position: Float32Array;
+    /** xyz root-local, unit */
+    normal: Float32Array;
+    /** rgb linear */
+    color: Float32Array;
+    /** 4 independent 0..1 randoms per point */
+    random: Float32Array;
+}
+export declare function mulberry32(seed: number): () => number;
+export declare function sampleSurface(root: Object3D, count: number, seed?: number): SurfaceSample;
+/** sampleSurface, remembered per object — replaying an effect costs nothing. */
+export declare function sampleSurfaceCached(root: Object3D, count: number, seed?: number): SurfaceSample;
+//# sourceMappingURL=surfaceSample.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceSample.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/surfaceSample.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAY,QAAQ,EAAW,MAAM,OAAO,CAAC;AAGzD,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,QAAQ,EAAE,YAAY,CAAC;IACvB,2BAA2B;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,iBAAiB;IACjB,KAAK,EAAE,YAAY,CAAC;IACpB,2CAA2C;IAC3C,MAAM,EAAE,YAAY,CAAC;CACxB;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,gBAQtC;AA0ED,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,SAAI,GAAG,aAAa,CAkDpF;AAwBD,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,SAAI,GAAG,aAAa,CAW1F"}

package/dist/operations/catalogue/surfaceSample.js

@@ -0,0 +1,187 @@
+// =============================================================================
+// Surface sampling — particles that ARE the object's surface.
+// =============================================================================
+//
+// Samples points over every mesh of a target, area-weighted in world units, and
+// returns them in the target's root-local space with their normal and the colour
+// the surface has there:
+//   material colour × vertex colour × base-colour texture (read once, on the CPU,
+//   from a 256px copy; compressed / GPU-only textures fall back to the colour).
+// Seeded, so the same object always breaks up the same way.
+//
+import { Color, Matrix3, Matrix4, SRGBColorSpace, Vector2, Vector3 } from 'three';
+import { MeshSurfaceSampler } from 'three/examples/jsm/math/MeshSurfaceSampler.js';
+export function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+// ---------------------------------------------------------------- texture reads
+const texCache = new WeakMap();
+function readTexture(tex) {
+    if (texCache.has(tex))
+        return texCache.get(tex);
+    let out = null;
+    try {
+        const img = tex.image;
+        const iw = img?.width, ih = img?.height;
+        if (iw && ih && typeof document !== 'undefined' && !tex.isCompressedTexture && !tex.isDataTexture) {
+            const w = Math.min(256, iw), h = Math.min(256, ih);
+            const canvas = document.createElement('canvas');
+            canvas.width = w;
+            canvas.height = h;
+            const ctx = canvas.getContext('2d', { willReadFrequently: true });
+            if (ctx) {
+                ctx.drawImage(img, 0, 0, w, h);
+                out = { data: ctx.getImageData(0, 0, w, h).data, w, h };
+            }
+        }
+    }
+    catch {
+        out = null; // tainted / unsupported image — colour only
+    }
+    texCache.set(tex, out);
+    return out;
+}
+const _uv3 = new Vector3();
+const _c = new Color();
+function sampleTexture(tex, uv, target) {
+    const px = readTexture(tex);
+    if (!px)
+        return false;
+    tex.updateMatrix();
+    _uv3.set(uv.x, uv.y, 1).applyMatrix3(tex.matrix);
+    const u = _uv3.x - Math.floor(_uv3.x);
+    const v = _uv3.y - Math.floor(_uv3.y);
+    const x = Math.min(px.w - 1, Math.floor(u * px.w));
+    const y = Math.min(px.h - 1, Math.floor((tex.flipY ? 1 - v : v) * px.h));
+    const i = (y * px.w + x) * 4;
+    _c.setRGB(px.data[i] / 255, px.data[i + 1] / 255, px.data[i + 2] / 255, SRGBColorSpace);
+    target.multiply(_c);
+    return true;
+}
+function materialOf(mesh, faceIndex) {
+    if (!Array.isArray(mesh.material))
+        return mesh.material;
+    const vi = faceIndex * 3;
+    const g = mesh.geometry.groups.find((gr) => vi >= gr.start && vi < gr.start + gr.count);
+    return mesh.material[g?.materialIndex ?? 0];
+}
+// ---------------------------------------------------------------- sampling
+/** Area of a mesh's geometry in root-local units (for the per-mesh share). */
+function meshArea(geo, m) {
+    const pos = geo.getAttribute('position');
+    const idx = geo.index;
+    const tris = idx ? idx.count / 3 : pos.count / 3;
+    const a = new Vector3(), b = new Vector3(), c = new Vector3();
+    // Estimate on a stride so huge meshes stay cheap.
+    const stride = Math.max(1, Math.floor(tris / 4000));
+    let area = 0;
+    for (let t = 0; t < tris; t += stride) {
+        const i0 = idx ? idx.getX(t * 3) : t * 3, i1 = idx ? idx.getX(t * 3 + 1) : t * 3 + 1, i2 = idx ? idx.getX(t * 3 + 2) : t * 3 + 2;
+        a.fromBufferAttribute(pos, i0).applyMatrix4(m);
+        b.fromBufferAttribute(pos, i1).applyMatrix4(m);
+        c.fromBufferAttribute(pos, i2).applyMatrix4(m);
+        area += b.sub(a).cross(c.sub(a)).length() * 0.5;
+    }
+    return area * stride;
+}
+export function sampleSurface(root, count, seed = 1) {
+    root.updateWorldMatrix(true, true);
+    const rootInv = new Matrix4().copy(root.matrixWorld).invert();
+    const meshes = [];
+    root.traverse((c) => {
+        if (!c.isMesh || !c.geometry?.getAttribute('position') || c.userData?.__opFxHelper || !c.visible)
+            return;
+        const m = new Matrix4().multiplyMatrices(rootInv, c.matrixWorld);
+        meshes.push({ mesh: c, m, area: meshArea(c.geometry, m) });
+    });
+    const total = meshes.reduce((s, x) => s + x.area, 0) || 1;
+    const out = {
+        count, position: new Float32Array(count * 3), normal: new Float32Array(count * 3),
+        color: new Float32Array(count * 3), random: new Float32Array(count * 4),
+    };
+    const rnd = mulberry32(seed);
+    for (let i = 0; i < count * 4; i++)
+        out.random[i] = rnd();
+    if (!meshes.length)
+        return { ...out, count: 0 };
+    const p = new Vector3(), n = new Vector3(), col = new Color(), uv = new Vector2(), base = new Color();
+    const nm = new Matrix3();
+    let k = 0;
+    meshes.forEach((entry, mi) => {
+        const share = mi === meshes.length - 1 ? count - k : Math.round((entry.area / total) * count);
+        if (share <= 0)
+            return;
+        const sampler = new MeshSurfaceSampler(entry.mesh);
+        // seeded (setRandomGenerator exists at runtime but is missing from @types/three)
+        sampler.randomFunction = rnd;
+        sampler.build();
+        nm.getNormalMatrix(entry.m);
+        const geo = entry.mesh.geometry;
+        const hasColor = !!geo.getAttribute('color');
+        const hasUv = !!geo.getAttribute('uv');
+        for (let s = 0; s < share && k < count; s++, k++) {
+            const face = sampler.sampleFaceIndex(); // runtime API, missing from @types/three
+            sampler.sampleFace(face, p, n, hasColor ? col : undefined, hasUv ? uv : undefined);
+            p.applyMatrix4(entry.m);
+            n.applyMatrix3(nm).normalize();
+            const mat = materialOf(entry.mesh, face);
+            base.setRGB(1, 1, 1);
+            if (hasColor)
+                base.copy(col);
+            if (mat?.color)
+                base.multiply(mat.color);
+            if (hasUv && mat?.map)
+                sampleTexture(mat.map, uv, base);
+            p.toArray(out.position, k * 3);
+            n.toArray(out.normal, k * 3);
+            out.color[k * 3] = base.r;
+            out.color[k * 3 + 1] = base.g;
+            out.color[k * 3 + 2] = base.b;
+        }
+    });
+    out.count = k;
+    return out;
+}
+// ---------------------------------------------------------------- cache
+/**
+ * What a sample depends on: every visible mesh's geometry, material and placement
+ * relative to the root. Moving the whole object does not invalidate it.
+ */
+function signature(root) {
+    root.updateWorldMatrix(true, true);
+    const inv = new Matrix4().copy(root.matrixWorld).invert();
+    const m = new Matrix4();
+    const parts = [];
+    root.traverse((c) => {
+        if (!c.isMesh || c.userData?.__opFxHelper || !c.visible || !c.geometry)
+            return;
+        m.multiplyMatrices(inv, c.matrixWorld);
+        const mats = Array.isArray(c.material) ? c.material : [c.material];
+        parts.push(`${c.geometry.uuid}:${c.geometry.attributes.position?.version ?? 0}:${mats.map((x) => x?.uuid).join('/')}:${m.elements.map(e => e.toFixed(4)).join(',')}`);
+    });
+    return parts.join('|');
+}
+const sampleCache = new WeakMap();
+/** sampleSurface, remembered per object — replaying an effect costs nothing. */
+export function sampleSurfaceCached(root, count, seed = 1) {
+    const key = `${count}|${seed}|${signature(root)}`;
+    let byKey = sampleCache.get(root);
+    if (!byKey) {
+        byKey = new Map();
+        sampleCache.set(root, byKey);
+    }
+    let hit = byKey.get(key);
+    if (!hit) {
+        hit = sampleSurface(root, count, seed);
+        byKey.clear(); // one sample per object: the latest configuration
+        byKey.set(key, hit);
+    }
+    return hit;
+}

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

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

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

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