@3driseai/3drise-viewer 0.1.26 → 0.1.28

package/dist/operations/catalogue/displayImage.js

@@ -4,6 +4,7 @@ export default defineOperation({
     value: 'displayImage',
     label: 'Show image',
     description: "Show the clicked frame's image on the target",
+    channel: 'visual',
     multi: false,
     toggles: false,
     usableIn: ['interaction'],

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

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

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

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

package/dist/operations/catalogue/dissolve.js

@@ -0,0 +1,57 @@
+// Dissolve — the targets burn away along a calm noise front with a glowing edge;
+// reverting grows them back. Built on the shared transition field, so it has the
+// same directions as every other transition (including screen left/right) and
+// shares its root-space pattern (no swimming, multi-mesh models dissolve as one).
+import { defineOperation } from '../types.js';
+import { addLayer, forEachMeshMaterial, removeLayer } from './shaderLayers.js';
+import { DIRECTION_OPTIONS, createFieldState, hideMeshes, runProgress, setFieldParams, surfaceLayer } from './transitionField.js';
+const P = 'Dis';
+const KEY = 'dissolve';
+const STATE = '__opDissolve';
+export default defineOperation({
+    value: 'dissolve',
+    label: 'Dissolve',
+    description: 'Burn the targets away along a glowing edge — reverting grows them back',
+    channel: 'visual',
+    multi: true,
+    toggles: true,
+    usableIn: ['interaction', 'action'],
+    params: {
+        direction: { type: 'select', label: 'Direction', default: 'noise', options: DIRECTION_OPTIONS },
+        edgeColor: { type: 'color', label: 'Edge colour', default: '#ff7a2e' },
+        edgeWidth: { type: 'number', label: 'Edge width', default: 0.08, min: 0.01, max: 0.3, step: 0.01 },
+        scale: { type: 'number', label: 'Grain', default: 3, min: 0.5, max: 12, step: 0.1, hint: 'Size of the burn pattern — higher = finer' },
+        duration: { type: 'number', label: 'Duration', default: 1.6, min: 0.1, max: 10, step: 0.05, unit: 's' },
+    },
+    apply(target, p, ctx) {
+        let st = target.userData[STATE];
+        if (!st) {
+            st = { field: createFieldState(target), mats: new Set() };
+            const own = st;
+            const layer = surfaceLayer(P, own.field, 'ember');
+            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);
+        return runProgress(target, s.field, 1, {
+            duration: Number(p.duration), ease: 'power1.in',
+            onComplete: () => hideMeshes(target, KEY, true),
+        });
+    },
+    revert(target, p) {
+        const s = target.userData[STATE];
+        if (!s)
+            return;
+        hideMeshes(target, KEY, false);
+        return runProgress(target, s.field, 0, {
+            duration: Number(p.duration), ease: 'power1.out',
+            onComplete: () => { s.mats.forEach(m => removeLayer(m, KEY)); delete target.userData[STATE]; },
+        });
+    },
+});

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

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

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

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

package/dist/operations/catalogue/emberAsh.js

@@ -0,0 +1,171 @@
+// Ember ash — the object burns the way wood and paper do, not the way a dissolve
+// does: a dull-red front chars the surface to charcoal, glowing embers breathe
+// in the cracks just behind it, the charcoal pales to powdery grey ash, and the
+// ash comes away in flakes that a wind carries off — tumbling, curling in
+// turbulence, rising on the heat, a few still glowing as they cool.
+// Reverting runs the fire backwards: the flakes blow back and the object un-burns.
+import { Color, Vector3 } from 'three';
+import { defineOperation } from '../types.js';
+import { GLSL_WORLEY, addLayer, forEachMeshMaterial, removeLayer } from './shaderLayers.js';
+import { DIRECTION_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, hideMeshes, runProgress, screenRight, setFieldParams, } from './transitionField.js';
+import { sampleSurfaceCached } from './surfaceSample.js';
+import { GLSL_POINT_SIZE, createFxPoints, disposeFxPoints } from './fxPoints.js';
+const P = 'Ash';
+const KEY = 'emberAsh';
+const STATE = '__opEmberAsh';
+/** The ash front trails the char front by LAG; flakes fly for LIFE (progress units). */
+const LAG = 0.3;
+const LIFE = 0.7;
+const END = 1 + LAG + LIFE;
+/** Shared GLSL: the char front, the ash front, and where a point stands between them. */
+const FRONTS = /* glsl */ `
+float ashChar(float f) { return smoothstep(0.0, 0.12, AshThreshold() - f); }
+float ashAshT() {
+  float pa = clamp((uAshProgress - ${LAG.toFixed(2)}) / 1.0, 0.0, 1.0);
+  return pa * (1.0 + 2.0 * uAshEdgeWidth) - uAshEdgeWidth;
+}
+`;
+function surfaceLayerFor(st) {
+    return {
+        uniforms: { ...fieldUniforms(P, st.field), uAshEmber: st.ember },
+        common: `varying vec3 vAshQ;\nvarying vec3 vAshR;\n${fieldGlsl(P)}\n${GLSL_WORLEY}\n${FRONTS}`,
+        vertex: /* glsl */ `
+        vAshR = (uAshRootInv * modelMatrix * vec4(transformed, 1.0)).xyz;
+        vAshQ = AshNorm(vAshR);`,
+        diffuse: /* glsl */ `
+        {
+          float f = AshField(vAshQ);
+          float ta = ashAshT();
+          if (f < ta) discard;                                           // gone to the wind
+          float ch = ashChar(f);
+          float toAsh = 1.0 - smoothstep(0.0, 0.14, f - ta);            // pales just before it flakes
+          vec3 charcoal = vec3(0.045, 0.04, 0.036) * (0.7 + 0.6 * fxNoise(vAshR / uAshExtent * 60.0));
+          vec3 ash = vec3(0.58, 0.56, 0.53) * (0.8 + 0.3 * fxNoise(vAshR / uAshExtent * 90.0));
+          diffuseColor.rgb = mix(diffuseColor.rgb, charcoal, ch * 0.96);
+          diffuseColor.rgb = mix(diffuseColor.rgb, ash, toAsh);
+        }`,
+        material: /* glsl */ `
+        {
+          float ch = ashChar(AshField(vAshQ));
+          roughnessFactor = mix(roughnessFactor, 0.95, ch);
+          metalnessFactor = mix(metalnessFactor, 0.0, ch);
+        }`,
+        fragment: /* glsl */ `
+        {
+          float f = AshField(vAshQ);
+          float tc = AshThreshold();
+          float ch = ashChar(f);
+          float ta = ashAshT();
+          float toAsh = 1.0 - smoothstep(0.0, 0.14, f - ta);
+          // embers live in the cracks just behind the char front, and die as it turns to ash
+          vec3 cell = fxWorley(vAshR / uAshExtent * 22.0);
+          float crack = 1.0 - smoothstep(0.0, 0.08, cell.y - cell.x);
+          float speck = step(0.78, fxNoise(vAshR / uAshExtent * 75.0));
+          float heat = ch * (1.0 - toAsh) * exp(-max(tc - f, 0.0) / 0.12);
+          float breathe = 0.7 + 0.3 * sin(uAshTime * 2.1 + cell.z * 6.2832);
+          float glow = heat * breathe * (crack * 0.9 + speck * 0.6);
+          vec3 emberC = mix(uAshEmber * vec3(0.5, 0.12, 0.02), uAshEmber, glow);
+          // the front itself: a dull red line, never white-hot
+          float front = exp(-abs(tc - f) / 0.018) * step(0.0001, uAshProgress) * step(uAshProgress, 0.9999);
+          outgoingLight += emberC * glow * 1.5 + uAshEmber * vec3(0.9, 0.35, 0.12) * front * 0.7;
+        }`,
+    };
+}
+export default defineOperation({
+    value: 'emberAsh',
+    label: 'Ember ash',
+    description: 'Char the targets to glowing charcoal, then pale ash that the wind blows away — reverting un-burns them',
+    channel: 'visual',
+    multi: true,
+    toggles: true,
+    usableIn: ['interaction', 'action'],
+    params: {
+        direction: { type: 'select', label: 'Burn direction', default: 'up', options: DIRECTION_OPTIONS },
+        wind: { type: 'select', label: 'Wind', default: 'left', options: [{ value: 'left', label: 'Left → right' }, { value: 'right', label: 'Right → left' }, { value: 'up', label: 'Rising' }] },
+        windStrength: { type: 'number', label: 'Wind strength', default: 1, min: 0, max: 4, step: 0.05, unit: '×' },
+        ember: { type: 'color', label: 'Ember colour', default: '#ff6a1f' },
+        flakes: { type: 'number', label: 'Ash flakes', default: 16000, min: 2000, max: 80000, step: 1000 },
+        flakeSize: { type: 'number', label: 'Flake size', default: 1, min: 0.2, max: 4, step: 0.1, unit: '×' },
+        scale: { type: 'number', label: 'Burn pattern', default: 2.5, min: 0.5, max: 12, step: 0.1 },
+        duration: { type: 'number', label: 'Duration', default: 4, min: 0.3, max: 14, step: 0.1, unit: 's' },
+    },
+    apply(target, p, ctx) {
+        let st = target.userData[STATE];
+        if (!st) {
+            const field = createFieldState(target);
+            field.edgeWidth.value = 0.05;
+            const own = { field, wind: { value: new Vector3(1, 0, 0) }, windStrength: { value: 1 }, ember: { value: new Color() }, flake: { value: 1 }, mats: new Set() };
+            const sample = sampleSurfaceCached(target, Math.round(Number(p.flakes)), 7);
+            own.points = createFxPoints(target, sample, {
+                additive: false,
+                uniforms: { ...fieldUniforms(P, field), uAshWind: own.wind, uAshWindK: own.windStrength, uAshEmber: own.ember, uAshFlake: own.flake },
+                vertexPars: fieldGlsl(P) + GLSL_POINT_SIZE + FRONTS,
+                vertexMain: /* glsl */ `
+                  float f = AshField(AshNorm(aP));
+                  // a flake leaves when the ash front reaches it
+                  float born = ${LAG.toFixed(2)} + AshBirthOf(f);
+                  float a = (uAshProgress - born) / ${LIFE.toFixed(2)};
+                  if (a <= 0.0 || a >= 1.0) { gl_Position = vec4(2.0, 2.0, 2.0, 1.0); gl_PointSize = 0.0; vColor = vec3(0.0); vAlpha = 0.0; return; }
+                  float E = uAshExtent;
+                  // wind: accelerating along the wind, curling in slow turbulence, lifted by the heat
+                  vec3 np = aP / E * 2.2 + aR.xyz * 5.0;
+                  vec3 turb = vec3(fxNoise(np + vec3(a * 1.6, 0.0, 0.0)), fxNoise(np + vec3(17.0, a * 1.6, 3.0)), fxNoise(np + vec3(5.0, 11.0, a * 1.6))) - 0.5;
+                  vec3 local = aP + aN * (0.02 * E * sqrt(a))
+                             + uAshWind * (E * uAshWindK * (0.5 * a + 1.3 * a * a) * (0.7 + 0.6 * aR.x))
+                             + turb * (0.5 * E * a)
+                             + vec3(0.0, 0.22 * E * a * (0.5 + aR.y), 0.0);
+                  vec4 mv = modelViewMatrix * vec4(local, 1.0);
+                  gl_Position = projectionMatrix * mv;
+                  // most flakes are grey ash; one in six still glows, cooling as it flies
+                  float glowing = step(0.83, aR.w);
+                  vec3 ash = mix(vec3(0.66, 0.64, 0.6), vec3(0.24, 0.23, 0.22), aR.z);
+                  vec3 hot = mix(uAshEmber * 1.8, uAshEmber * vec3(0.35, 0.08, 0.02), a);
+                  vColor = mix(ash, hot, glowing);
+                  vAlpha = smoothstep(0.0, 0.05, a) * (1.0 - smoothstep(0.7, 1.0, a));
+                  // a tumbling flake shows its face, then its edge
+                  float tumble = 0.35 + 0.65 * abs(sin(a * (9.0 + 12.0 * aR.y) + aR.x * 6.28));
+                  gl_PointSize = clamp(fxPointPx(E * 0.0055 * uAshFlake * (0.5 + aR.z) * tumble, mv), 1.0, 14.0);`,
+            });
+            const layer = surfaceLayerFor(own);
+            forEachMeshMaterial(target, (mat, mesh) => {
+                if (mesh.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.ember.value.set(String(p.ember));
+        s.windStrength.value = Number(p.windStrength);
+        s.flake.value = Number(p.flakeSize);
+        if (p.wind === 'up')
+            s.wind.value.set(0, 1, 0);
+        else {
+            const r = screenRight(target, ctx);
+            s.wind.value.copy(p.wind === 'right' ? r.negate() : r);
+        }
+        s.points.visible = true;
+        return runProgress(target, s.field, END, {
+            duration: Number(p.duration), ease: 'none',
+            onComplete: () => { hideMeshes(target, KEY, true); s.points.visible = false; },
+        });
+    },
+    revert(target, p) {
+        const s = target.userData[STATE];
+        if (!s)
+            return;
+        hideMeshes(target, KEY, false);
+        s.points.visible = true;
+        return runProgress(target, s.field, 0, {
+            duration: Number(p.duration), ease: 'none',
+            onComplete: () => {
+                s.mats.forEach(m => removeLayer(m, KEY));
+                disposeFxPoints(s.points);
+                delete target.userData[STATE];
+            },
+        });
+    },
+});

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

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

package/dist/operations/catalogue/fade.js

@@ -6,6 +6,7 @@ export default defineOperation({
     value: 'fade',
     label: 'Fade out',
     description: 'Fade the targets away (to a set opacity)',
+    channel: 'visual',
     multi: true,
     toggles: true,
     usableIn: ['interaction', 'action'],

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

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

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

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

package/dist/operations/catalogue/flip.js

@@ -0,0 +1,69 @@
+// Flip — a proper little jump: crouch (anticipation), spring up, a full flip in
+// the air about the object's centre, and a squash on landing. One-shot, lands
+// exactly on the rest pose.
+import { gsap } from 'gsap';
+import { Quaternion, Vector3 } from 'three';
+import { defineOperation } from '../types.js';
+import { acquireRest, poseAbout, releaseRest } from './restPose.js';
+const KEY = '__opFlip';
+const AXES = { x: new Vector3(1, 0, 0), z: new Vector3(0, 0, 1), y: new Vector3(0, 1, 0) };
+const NO_TURN = new Quaternion();
+const smooth = (x) => x * x * (3 - 2 * x);
+export default defineOperation({
+    value: 'flip',
+    label: 'Flip',
+    description: 'Crouch, jump and flip in the air, landing with a squash',
+    channel: 'transform',
+    multi: true,
+    toggles: false,
+    usableIn: ['interaction', 'action'],
+    params: {
+        axis: { type: 'select', label: 'Flip', default: 'x', options: [{ value: 'x', label: 'Forward (X)' }, { value: 'z', label: 'Sideways (Z)' }, { value: 'y', label: 'Twist (Y)' }] },
+        height: { type: 'number', label: 'Jump height', default: 0.45, min: 0.1, max: 4, step: 0.05, hint: 'A fraction of the object’s own height' },
+        reverse: { type: 'boolean', label: 'Backwards', default: false },
+        duration: { type: 'number', label: 'Duration', default: 1.3, min: 0.3, 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 = { u: 0 };
+        target.userData[KEY] = { proxy };
+        const axis = AXES[String(p.axis)] ?? AXES.x;
+        const dir = p.reverse ? -1 : 1;
+        const h = rest.size.y * Number(p.height);
+        const q = new Quaternion(), s = new Vector3(), off = new Vector3();
+        const CROUCH = 0.18, LAND = 0.82;
+        gsap.to(proxy, {
+            u: 1, duration: Number(p.duration), ease: 'none',
+            onUpdate: () => {
+                const u = proxy.u;
+                if (u < CROUCH) {
+                    // anticipation: squash down and release, about the base
+                    const v = u / CROUCH;
+                    const sy = 1 - 0.16 * Math.sin(Math.PI * v);
+                    const sxz = 1 / Math.sqrt(sy);
+                    poseAbout(target, rest, rest.bottomLocal, NO_TURN, s.set(sxz, sy, sxz));
+                }
+                else if (u < LAND) {
+                    // ballistic hop + a full turn about the centre, eased so it hangs at the top
+                    const v = (u - CROUCH) / (LAND - CROUCH);
+                    off.set(0, 4 * h * v * (1 - v), 0);
+                    q.setFromAxisAngle(axis, dir * 2 * Math.PI * smooth(v));
+                    poseAbout(target, rest, rest.centerLocal, q, s.set(1, 1, 1), off);
+                }
+                else {
+                    // landing: squash that rings out once
+                    const v = (u - LAND) / (1 - LAND);
+                    const sy = 1 - 0.14 * Math.sin(Math.PI * v) * (1 - v * 0.4);
+                    const sxz = 1 / Math.sqrt(sy);
+                    poseAbout(target, rest, rest.bottomLocal, NO_TURN, s.set(sxz, sy, sxz));
+                }
+            },
+            onComplete: () => { delete target.userData[KEY]; releaseRest(target); },
+        });
+    },
+});

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

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

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

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

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