@3driseai/3drise-viewer 0.1.26 → 0.1.27

package/dist/operations/catalogue/flock.js

@@ -0,0 +1,163 @@
+// Flock — the surface takes flight: every spot becomes a small bird (a real lit
+// instanced mesh, flapping its wings, carrying the colour of the spot it left).
+// As the front passes, birds hop off the surface, then fly away in curving
+// streams — out and up, or all toward one side of the screen — accelerating
+// until they are gone. Birds always face the way they fly, so on revert they
+// fly back in (head first) and settle into place as the surface re-forms.
+import { BufferAttribute, BufferGeometry, Vector3 } from 'three';
+import { defineOperation } from '../types.js';
+import { addLayer, forEachMeshMaterial, removeLayer } from './shaderLayers.js';
+import { DIRECTION_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, hideMeshes, runProgress, screenRight, setFieldParams, surfaceLayer, } from './transitionField.js';
+import { sampleSurfaceCached } from './surfaceSample.js';
+import { createFxInstances, disposeFxInstances } from './fxInstances.js';
+const P = 'Flk';
+const KEY = 'flock';
+const STATE = '__opFlock';
+const LIFE = 1.0;
+/** A unit bird in its own frame: x = right, y = up, z = forward. aWing marks the flapping tips. */
+function birdGeometry() {
+    const v = [
+        // body
+        0, 0, 0.5, -0.07, 0, -0.45, 0.07, 0, -0.45,
+        // left wing (tip flaps)
+        0, 0, 0.18, -0.95, 0, -0.12, 0, 0, -0.22,
+        // right wing
+        0, 0, 0.18, 0, 0, -0.22, 0.95, 0, -0.12,
+        // tail
+        0, 0, -0.35, -0.18, 0, -0.62, 0.18, 0, -0.62,
+    ];
+    const wing = [0, 0, 0, 0, -1, 0, 0, 0, 1, 0, 0, 0];
+    const g = new BufferGeometry();
+    g.setAttribute('position', new BufferAttribute(new Float32Array(v), 3));
+    g.setAttribute('normal', new BufferAttribute(new Float32Array(Array(12).fill([0, 1, 0]).flat()), 3));
+    g.setAttribute('aWing', new BufferAttribute(new Float32Array(wing), 1));
+    return g;
+}
+export default defineOperation({
+    value: 'flock',
+    label: 'Flock',
+    description: 'Turn the targets into a flock of birds that takes off and flies away — reverting flies them home',
+    channel: 'visual',
+    multi: true,
+    toggles: true,
+    usableIn: ['interaction', 'action'],
+    params: {
+        direction: { type: 'select', label: 'Take-off order', default: 'down', options: DIRECTION_OPTIONS },
+        exit: { type: 'select', label: 'Fly', default: 'away', options: [{ value: 'away', label: 'Out and up' }, { value: 'left', label: 'To the right' }, { value: 'right', label: 'To the left' }, { value: 'up', label: 'Straight up' }] },
+        birds: { type: 'number', label: 'Birds', default: 1400, min: 100, max: 12000, step: 100 },
+        birdSize: { type: 'number', label: 'Bird size', default: 1, min: 0.3, max: 4, step: 0.05, unit: '×' },
+        speed: { type: 'number', label: 'Speed', default: 1, min: 0.2, max: 4, step: 0.05, unit: '×' },
+        edgeColor: { type: 'color', label: 'Edge colour', default: '#ffffff' },
+        scale: { type: 'number', label: 'Pattern', default: 2.5, min: 0.5, max: 12, step: 0.1 },
+        duration: { type: 'number', label: 'Duration', default: 3.4, min: 0.3, max: 14, step: 0.1, unit: 's' },
+    },
+    apply(target, p, ctx) {
+        let st = target.userData[STATE];
+        if (!st) {
+            const field = createFieldState(target);
+            field.edgeWidth.value = 0.04;
+            const own = {
+                field, exit: { value: new Vector3(1, 0, 0) }, mode: { value: 0 }, speed: { value: 1 }, dirSign: { value: 1 }, bird: { value: 1 }, mats: new Set(),
+            };
+            const sample = sampleSurfaceCached(target, Math.round(Number(p.birds)), 53);
+            const n = sample.count;
+            const pos = sample.position.slice(0, n * 3);
+            own.mesh = createFxInstances(target, {
+                geometry: birdGeometry(),
+                count: n, positions: pos, colors: sample.color.slice(0, n * 3),
+                attributes: { aFlkP: [pos, 3], aFlkN: [sample.normal.slice(0, n * 3), 3], aFlkR: [sample.random.slice(0, n * 4), 4] },
+                layerKey: 'flockInstances', roughness: 0.65, metalness: 0, doubleSided: true,
+                layer: {
+                    uniforms: { ...fieldUniforms(P, field), uFlkExit: own.exit, uFlkMode: own.mode, uFlkSpeed: own.speed, uFlkDirSign: own.dirSign, uFlkBird: own.bird },
+                    common: fieldGlsl(P),
+                    vertexPars: /* glsl */ `
+                    attribute float aWing; attribute vec3 aFlkP; attribute vec3 aFlkN; attribute vec4 aFlkR;
+                    float flkAge() { return (uFlkProgress - FlkBirthOf(FlkField(FlkNorm(aFlkP)))) / ${LIFE.toFixed(1)}; }
+                    // offset from the bird's home spot at age a (0..1)
+                    vec3 flkPath(float a) {
+                      float E = uFlkExtent;
+                      float take = smoothstep(0.0, 0.1, a);
+                      vec3 hop = (aFlkN * 0.06 + vec3(0.0, 0.05, 0.0)) * E * take;
+                      float t = max(a - 0.06, 0.0);
+                      vec3 C = uFlkMin + uFlkSize * 0.5;
+                      vec3 away = normalize(vec3(aFlkP.x - C.x, 0.0, aFlkP.z - C.z) + (aFlkR.xyz - 0.5) * 0.7 + vec3(1e-3, 0.0, 0.0));
+                      vec3 dir = uFlkMode < 0.5
+                        ? normalize(away + vec3(0.0, 0.55 + 0.45 * aFlkR.y, 0.0))
+                        : normalize(uFlkExit + (aFlkR.xyz - 0.5) * 0.45 + vec3(0.0, 0.2 + 0.2 * aFlkR.y, 0.0));
+                      float dist = E * uFlkSpeed * (1.0 * t + 5.5 * t * t);
+                      vec3 sideV = normalize(cross(dir, vec3(0.0, 1.0, 0.0)) + vec3(1e-3));
+                      vec3 curve = sideV * sin(t * 4.0 + aFlkR.z * 6.28) * 0.28 * E * t
+                                 + vec3(0.0, 1.0, 0.0) * sin(t * 3.0 + aFlkR.w * 6.28) * 0.12 * E * t;
+                      return hop + dir * dist + curve;
+                    }
+                    // the bird's frame: facing the way it moves (backwards in time when reverting)
+                    mat3 flkFrame(float a) {
+                      float a0 = min(a, 0.99);
+                      vec3 v = (flkPath(a0 + 0.01) - flkPath(a0)) * uFlkDirSign;
+                      vec3 fwd = length(v) > 1e-6 ? normalize(v) : vec3(0.0, 0.0, 1.0);
+                      vec3 right = normalize(cross(fwd, vec3(0.0, 1.0, 0.0)) + vec3(1e-4));
+                      vec3 up = cross(right, fwd);
+                      return mat3(right, up, fwd);
+                    }`,
+                    normal: `{ objectNormal = flkFrame(clamp(flkAge(), 0.0, 1.0)) * objectNormal; }`,
+                    vertex: /* glsl */ `
+                    {
+                      float a = flkAge();
+                      if (a <= 0.0) { transformed *= 0.0; }
+                      else {
+                        a = min(a, 1.0);
+                        vec3 v = transformed;
+                        // wing beat: fast, with a little variation per bird
+                        v.y += abs(aWing) * sin(uFlkTime * (16.0 + 6.0 * aFlkR.x) + aFlkR.y * 6.28) * 0.38;
+                        float size = uFlkExtent * 0.03 * uFlkBird * (0.8 + 0.4 * aFlkR.w);
+                        float sc = smoothstep(0.0, 0.06, a) * (1.0 - smoothstep(0.88, 1.0, a));
+                        transformed = flkFrame(a) * (v * size * sc) + flkPath(a);
+                      }
+                    }`,
+                },
+            });
+            const layer = surfaceLayer(P, field, 'tint');
+            forEachMeshMaterial(target, (mat, m) => {
+                if (m.userData?.__opFxHelper)
+                    return;
+                if (addLayer(mat, KEY, layer))
+                    own.mats.add(mat);
+            });
+            st = own;
+            target.userData[STATE] = st;
+        }
+        const s = st;
+        setFieldParams(s.field, p, target, ctx);
+        s.speed.value = Number(p.speed);
+        s.bird.value = Number(p.birdSize);
+        s.dirSign.value = 1;
+        s.mode.value = p.exit === 'away' ? 0 : 1;
+        if (p.exit === 'up')
+            s.exit.value.set(0, 1, 0);
+        else if (p.exit === 'left' || p.exit === 'right') {
+            const r = screenRight(target, ctx);
+            s.exit.value.copy(p.exit === 'left' ? r : r.negate());
+        }
+        s.mesh.visible = true;
+        return runProgress(target, s.field, 1 + LIFE, {
+            duration: Number(p.duration), ease: 'power1.in',
+            onComplete: () => { hideMeshes(target, KEY, true); s.mesh.visible = false; },
+        });
+    },
+    revert(target, p) {
+        const s = target.userData[STATE];
+        if (!s)
+            return;
+        hideMeshes(target, KEY, false);
+        s.mesh.visible = true;
+        s.dirSign.value = -1;
+        return runProgress(target, s.field, 0, {
+            duration: Number(p.duration), ease: 'power1.out',
+            onComplete: () => {
+                s.mats.forEach(m => removeLayer(m, KEY));
+                disposeFxInstances(s.mesh);
+                delete target.userData[STATE];
+            },
+        });
+    },
+});

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

@@ -1 +1 @@
-{"version":3,"file":"focus.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/focus.ts"],"names":[],"mappings":";AAGA,wBAmBG"}
+{"version":3,"file":"focus.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/focus.ts"],"names":[],"mappings":";AAGA,wBAoBG"}

package/dist/operations/catalogue/focus.js

@@ -4,6 +4,7 @@ export default defineOperation({
     value: 'focus',
     label: 'Look at',
     description: 'Turn the camera to face the target, without moving it',
+    channel: 'camera',
     multi: false,
     toggles: true,
     usableIn: ['interaction', 'action'],

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

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

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

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

package/dist/operations/catalogue/frame.js

@@ -0,0 +1,44 @@
+// Frame — fly the camera so the whole target fills the view, from the side the
+// camera is already on (unlike Zoom, which stands a fixed distance in front of
+// the target's face). Reverting flies back.
+import { Box3, Sphere, Vector3 } from 'three';
+import cameraManager from '../../utils/CameraSingleton.js';
+import { defineOperation } from '../types.js';
+export default defineOperation({
+    value: 'frame',
+    label: 'Frame',
+    description: 'Fly the camera so the whole target fits the view, keeping the current viewing side',
+    channel: 'camera',
+    multi: false,
+    toggles: true,
+    usableIn: ['interaction', 'action'],
+    exclusive: { group: 'camera', release: 'handover' },
+    params: {
+        margin: { type: 'number', label: 'Margin', default: 1.25, min: 1, max: 4, step: 0.05, unit: '×', hint: 'Room around the object — 1 fits it edge to edge' },
+        duration: { type: 'number', label: 'Duration', default: 1.2, min: 0, max: 10, step: 0.05, unit: 's' },
+    },
+    apply(target, p, ctx) {
+        const pose = ctx.tools.cameraPose();
+        const cam = cameraManager.getCamera();
+        if (!pose || !cam)
+            return;
+        const sphere = new Box3().setFromObject(target).getBoundingSphere(new Sphere());
+        if (!Number.isFinite(sphere.radius) || sphere.radius <= 0)
+            return;
+        ctx.saveCameraHome();
+        // the tighter of the vertical and horizontal fields of view decides the distance
+        const vFov = (cam.fov * Math.PI) / 180;
+        const hFov = 2 * Math.atan(Math.tan(vFov / 2) * cam.aspect);
+        const fit = sphere.radius / Math.sin(Math.min(vFov, hFov) / 2);
+        const dist = Math.max(fit * Number(p.margin), cam.near * 2);
+        const dir = new Vector3(...pose.position).sub(sphere.center);
+        if (dir.lengthSq() < 1e-8)
+            dir.set(0, 0, 1);
+        const to = sphere.center.clone().add(dir.normalize().multiplyScalar(dist));
+        const c = sphere.center;
+        void ctx.tools.animateCamera({ position: [to.x, to.y, to.z] }, Number(p.duration), 'power3.inOut', [c.x, c.y, c.z]);
+    },
+    revert(_target, p, ctx) {
+        ctx.restoreCameraHome(Number(p.duration), 'power3.inOut');
+    },
+});

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

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

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

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

package/dist/operations/catalogue/frost.js

@@ -0,0 +1,111 @@
+// Frost — ice spreads over the object along a feathery front: the surface turns
+// to faceted crystal (3D cellular pattern in the object's own space), glossy
+// where the ice is clear and rough and white where frost crusts along the facet
+// seams, with glints that catch the light cell by cell. The base colour and the
+// roughness change BEFORE lighting, so the ice is lit by the scene like a real
+// material. A state, not an exit: it stays frozen while on; reverting thaws.
+import { Color } from 'three';
+import { defineOperation } from '../types.js';
+import { GLSL_WORLEY, addLayer, forEachMeshMaterial, removeLayer } from './shaderLayers.js';
+import { DIRECTION_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, runProgress, setFieldParams } from './transitionField.js';
+const P = 'Frs';
+const KEY = 'frost';
+const STATE = '__opFrost';
+function layerFor(st) {
+    // computed ONCE per fragment, in the first anchor (diffuse), then shared: the
+    // cellular pattern is the costly part to compile and to run
+    const frozen = /* glsl */ `
+      float frsT = FrsThreshold();
+      float frsF = FrsField(vFrsQ);
+      float fr = frsFr;
+      vec3 cell = frsCell;
+      float seam = frsSeam;
+    `;
+    return {
+        uniforms: { ...fieldUniforms(P, st.field), uFrsIce: st.ice, uFrsDensity: st.density },
+        common: `varying vec3 vFrsQ;\nvarying vec3 vFrsR;\nvarying vec3 vFrsView;\n${fieldGlsl(P)}\n${GLSL_WORLEY}`,
+        fragmentPars: 'float frsFr = 0.0; vec3 frsCell = vec3(1.0); float frsSeam = 0.0;',
+        vertex: /* glsl */ `
+        vFrsR = (uFrsRootInv * modelMatrix * vec4(transformed, 1.0)).xyz;
+        vFrsQ = FrsNorm(vFrsR);
+        vFrsView = (modelViewMatrix * vec4(transformed, 1.0)).xyz;`,
+        diffuse: /* glsl */ `
+        {
+          frsFr = smoothstep(0.0, uFrsEdgeWidth, FrsThreshold() - FrsField(vFrsQ));
+          frsCell = fxWorley(vFrsR * (uFrsDensity / uFrsExtent));
+          frsSeam = 1.0 - smoothstep(0.0, 0.09, frsCell.y - frsCell.x);
+          ${frozen}
+          vec3 clearIce = uFrsIce * (0.55 + 0.25 * cell.z);
+          vec3 crust = vec3(0.93, 0.96, 1.0);
+          vec3 ice = mix(clearIce, crust, clamp(seam * 0.9 + 0.2 * fxFbm(vFrsR / uFrsExtent * 18.0), 0.0, 1.0));
+          diffuseColor.rgb = mix(diffuseColor.rgb, ice, fr * 0.9);
+        }`,
+        material: /* glsl */ `
+        {
+          ${frozen}
+          roughnessFactor = mix(roughnessFactor, mix(0.12, 0.75, seam), fr);
+          metalnessFactor = mix(metalnessFactor, 0.0, fr);
+        }`,
+        fragment: /* glsl */ `
+        {
+          ${frozen}
+          vec3 v = normalize(-vFrsView);
+          // each facet has its own crystal plane: some catch the light, most don't
+          vec3 g = normalize(fxHash3(floor(vFrsR * (uFrsDensity / uFrsExtent)) + 17.0) - 0.5);
+          float glint = pow(max(dot(g, v), 0.0), 90.0) * (1.0 - seam);
+          vec3 nv = normalize(cross(dFdx(vFrsView), dFdy(vFrsView)));
+          float rim = pow(1.0 - abs(dot(nv, v)), 3.0);
+          // the growing front: a thin bright crystalline line
+          float front = exp(-abs(frsT - frsF) / 0.012) * step(0.0001, uFrsProgress) * step(uFrsProgress, 0.9999);
+          outgoingLight += fr * (vec3(1.0) * glint * 4.0 + uFrsIce * rim * 0.45) + vec3(0.85, 0.95, 1.0) * front * 1.2;
+        }`,
+    };
+}
+export default defineOperation({
+    value: 'frost',
+    label: 'Frost',
+    description: 'Spread faceted ice with glinting crystals over the targets — reverting thaws them',
+    channel: 'visual',
+    multi: true,
+    toggles: true,
+    usableIn: ['interaction', 'action', 'object'],
+    stack: 'surface',
+    params: {
+        direction: { type: 'select', label: 'Direction', default: 'up', options: DIRECTION_OPTIONS },
+        ice: { type: 'color', label: 'Ice', default: '#bfe4ff' },
+        density: { type: 'number', label: 'Crystals', default: 14, min: 3, max: 60, step: 1, hint: 'Facets across the object' },
+        scale: { type: 'number', label: 'Front pattern', default: 3, min: 0.5, max: 12, step: 0.1 },
+        duration: { type: 'number', label: 'Duration', default: 2.6, min: 0.3, max: 12, step: 0.1, unit: 's' },
+    },
+    apply(target, p, ctx) {
+        let st = target.userData[STATE];
+        if (!st) {
+            const field = createFieldState(target);
+            field.edgeWidth.value = 0.05;
+            st = { field, ice: { value: new Color() }, density: { value: 14 }, mats: new Set() };
+            const own = st;
+            const layer = layerFor(own);
+            forEachMeshMaterial(target, (mat, mesh) => {
+                if (mesh.userData?.__opFxHelper)
+                    return;
+                if (addLayer(mat, KEY, layer))
+                    own.mats.add(mat);
+            });
+            target.userData[STATE] = st;
+        }
+        const s = st;
+        setFieldParams(s.field, p, target, ctx);
+        s.ice.value.set(String(p.ice));
+        s.density.value = Number(p.density);
+        return runProgress(target, s.field, 1, { duration: Number(p.duration), ease: 'power1.out', hold: true });
+    },
+    revert(target, p) {
+        const s = target.userData[STATE];
+        if (!s)
+            return;
+        return runProgress(target, s.field, 0, {
+            duration: Number(p.duration), ease: 'power1.in',
+            onComplete: () => { s.mats.forEach(m => removeLayer(m, KEY)); delete target.userData[STATE]; },
+        });
+    },
+});

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

@@ -0,0 +1,21 @@
+import { InstancedMesh } from 'three';
+import type { BufferGeometry, Object3D } from 'three';
+import { type ShaderLayer } from './shaderLayers';
+export interface FxInstancesOptions {
+    geometry: BufferGeometry;
+    count: number;
+    /** xyz root-local centre per instance */
+    positions: Float32Array;
+    /** rgb linear per instance */
+    colors: Float32Array;
+    /** Extra per-instance attributes, e.g. { aVoxBirth: [data, 1] } */
+    attributes: Record<string, [Float32Array, number]>;
+    layerKey: string;
+    layer: ShaderLayer;
+    roughness?: number;
+    metalness?: number;
+    doubleSided?: boolean;
+}
+export declare function createFxInstances(root: Object3D, o: FxInstancesOptions): InstancedMesh;
+export declare function disposeFxInstances(mesh: InstancedMesh | null | undefined): void;
+//# sourceMappingURL=fxInstances.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fxInstances.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/fxInstances.ts"],"names":[],"mappings":"AAOA,OAAO,EAA+C,aAAa,EAAiC,MAAM,OAAO,CAAC;AAClH,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtD,OAAO,EAAY,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG5D,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,EAAE,cAAc,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,SAAS,EAAE,YAAY,CAAC;IACxB,8BAA8B;IAC9B,MAAM,EAAE,YAAY,CAAC;IACrB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,kBAAkB,GAAG,aAAa,CA0BtF;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,QAMxE"}

package/dist/operations/catalogue/fxInstances.js

@@ -0,0 +1,47 @@
+// =============================================================================
+// Effect instances — an InstancedMesh attached to a target for the length of an
+// effect (voxels, petals…). A real lit MeshStandardMaterial, so the pieces are
+// shaded and cast shadows like the object itself; their motion is a shader layer
+// (per-instance attributes), so nothing is animated on the CPU.
+// Root-local, never raycasts, never counts in bounds, disposed with the effect.
+// =============================================================================
+import { Color, DoubleSide, InstancedBufferAttribute, InstancedMesh, Matrix4, MeshStandardMaterial } from 'three';
+import { addLayer } from './shaderLayers.js';
+import { hideUntilWarm } from './warmup.js';
+export function createFxInstances(root, o) {
+    const geo = o.geometry;
+    for (const [name, [data, size]] of Object.entries(o.attributes))
+        geo.setAttribute(name, new InstancedBufferAttribute(data, size));
+    const mat = new MeshStandardMaterial({
+        roughness: o.roughness ?? 0.6, metalness: o.metalness ?? 0.05,
+        side: o.doubleSided ? DoubleSide : undefined,
+    });
+    addLayer(mat, o.layerKey, o.layer, { immediate: true }); // a new material: compiled as a helper
+    const mesh = new InstancedMesh(geo, mat, o.count);
+    const m = new Matrix4();
+    const c = new Color();
+    for (let i = 0; i < o.count; i++) {
+        m.makeTranslation(o.positions[i * 3], o.positions[i * 3 + 1], o.positions[i * 3 + 2]);
+        mesh.setMatrixAt(i, m);
+        mesh.setColorAt(i, c.setRGB(o.colors[i * 3], o.colors[i * 3 + 1], o.colors[i * 3 + 2]));
+    }
+    mesh.instanceMatrix.needsUpdate = true;
+    if (mesh.instanceColor)
+        mesh.instanceColor.needsUpdate = true;
+    mesh.frustumCulled = false;
+    mesh.castShadow = true;
+    mesh.receiveShadow = true;
+    mesh.raycast = () => { };
+    mesh.userData.__opFxHelper = true;
+    root.add(mesh);
+    hideUntilWarm(mesh);
+    return mesh;
+}
+export function disposeFxInstances(mesh) {
+    if (!mesh)
+        return;
+    mesh.removeFromParent();
+    mesh.geometry.dispose();
+    mesh.material.dispose();
+    mesh.dispose();
+}

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

@@ -0,0 +1,22 @@
+import { Points } from 'three';
+import type { Object3D } from 'three';
+import type { SurfaceSample } from './surfaceSample';
+export interface FxPointsOptions {
+    uniforms: Record<string, {
+        value: unknown;
+    }>;
+    /** GLSL before main (after uniform/attribute declarations). */
+    vertexPars: string;
+    /**
+     * main() body. Attributes: aP (root-local position), aN (normal), aC (colour),
+     * aR (vec4 random). Must write gl_Position, gl_PointSize and vColor (rgb) / vAlpha.
+     * `uFxViewH` is the drawing-buffer height, for perspective point sizes.
+     */
+    vertexMain: string;
+    additive: boolean;
+}
+export declare function createFxPoints(root: Object3D, sample: SurfaceSample, o: FxPointsOptions): Points;
+export declare function disposeFxPoints(pts: Points | null | undefined): void;
+/** Perspective point size in pixels for a world-size `s` at view depth `z` (GLSL). */
+export declare const GLSL_POINT_SIZE = "\nfloat fxPointPx(float s, vec4 mv) { return s * uFxViewH * projectionMatrix[1][1] * 0.5 / max(-mv.z, 1e-3); }\n";
+//# sourceMappingURL=fxPoints.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fxPoints.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/fxPoints.ts"],"names":[],"mappings":"AAKA,OAAO,EAAqE,MAAM,EAA2B,MAAM,OAAO,CAAC;AAC3H,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAIrD,MAAM,WAAW,eAAe;IAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC7C,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;CACrB;AAiBD,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,EAAE,eAAe,GAAG,MAAM,CAoChG;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,QAK7D;AAED,sFAAsF;AACtF,eAAO,MAAM,eAAe,qHAE3B,CAAC"}

package/dist/operations/catalogue/fxPoints.js

@@ -0,0 +1,70 @@
+// =============================================================================
+// Effect particles — a Points cloud attached to a target for the length of a
+// transition. Lives in the target's root-local space (so it moves with it),
+// never raycasts, never counts in bounds, and is disposed with the effect.
+// =============================================================================
+import { AdditiveBlending, BufferAttribute, BufferGeometry, NormalBlending, Points, ShaderMaterial, Vector2 } from 'three';
+import { uniformDecl } from './shaderLayers.js';
+import { hideUntilWarm } from './warmup.js';
+const FRAG = /* glsl */ `
+varying vec3 vColor;
+varying float vAlpha;
+void main() {
+  vec2 d = gl_PointCoord - 0.5;
+  float r2 = dot(d, d) * 4.0;
+  if (r2 > 1.0) discard;
+  // soft core + halo
+  float a = exp(-r2 * 3.2) * vAlpha;
+  if (a < 0.004) discard;
+  gl_FragColor = vec4(vColor * a, a);
+  #include <tonemapping_fragment>
+  #include <colorspace_fragment>
+}`;
+export function createFxPoints(root, sample, o) {
+    const geo = new BufferGeometry();
+    geo.setAttribute('position', new BufferAttribute(sample.position.slice(0, sample.count * 3), 3));
+    geo.setAttribute('aP', new BufferAttribute(sample.position.slice(0, sample.count * 3), 3));
+    geo.setAttribute('aN', new BufferAttribute(sample.normal.slice(0, sample.count * 3), 3));
+    geo.setAttribute('aC', new BufferAttribute(sample.color.slice(0, sample.count * 3), 3));
+    geo.setAttribute('aR', new BufferAttribute(sample.random.slice(0, sample.count * 4), 4));
+    const viewH = { value: 1000 };
+    const uniforms = { ...o.uniforms, uFxViewH: viewH };
+    const decl = Object.keys(uniforms).map(n => uniformDecl(n, uniforms[n].value)).join('\n');
+    const mat = new ShaderMaterial({
+        uniforms: uniforms,
+        vertexShader: `${decl}
+attribute vec3 aP; attribute vec3 aN; attribute vec3 aC; attribute vec4 aR;
+varying vec3 vColor; varying float vAlpha;
+${o.vertexPars}
+void main() {
+${o.vertexMain}
+}`,
+        fragmentShader: FRAG,
+        transparent: true,
+        depthWrite: false,
+        // premultiplied: additive glow, or normal "over" for solid colour
+        blending: o.additive ? AdditiveBlending : NormalBlending,
+        premultipliedAlpha: true,
+    });
+    const pts = new Points(geo, mat);
+    pts.frustumCulled = false;
+    pts.raycast = () => { };
+    pts.userData.__opFxHelper = true;
+    pts.renderOrder = 10;
+    const size = new Vector2();
+    pts.onBeforeRender = (renderer) => { viewH.value = renderer.getDrawingBufferSize(size).y; };
+    root.add(pts);
+    hideUntilWarm(pts);
+    return pts;
+}
+export function disposeFxPoints(pts) {
+    if (!pts)
+        return;
+    pts.removeFromParent();
+    pts.geometry.dispose();
+    pts.material.dispose();
+}
+/** Perspective point size in pixels for a world-size `s` at view depth `z` (GLSL). */
+export const GLSL_POINT_SIZE = /* glsl */ `
+float fxPointPx(float s, vec4 mv) { return s * uFxViewH * projectionMatrix[1][1] * 0.5 / max(-mv.z, 1e-3); }
+`;

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

@@ -1 +1 @@
-{"version":3,"file":"glow.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/glow.ts"],"names":[],"mappings":";AAMA,wBAyCG"}
+{"version":3,"file":"glow.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/glow.ts"],"names":[],"mappings":";AAMA,wBA0CG"}

package/dist/operations/catalogue/glow.js

@@ -6,9 +6,10 @@ export default defineOperation({
     value: 'glow',
     label: 'Glow',
     description: 'Light the targets up with an emissive glow',
+    channel: 'visual',
     multi: true,
     toggles: true,
-    usableIn: ['interaction', 'action'],
+    usableIn: ['interaction', 'action', 'object'],
     params: {
         color: { type: 'color', label: 'Colour', default: '#3380ff' },
         intensity: { type: 'number', label: 'Intensity', default: 3, min: 0, max: 20, step: 0.1 },

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

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

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

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