@3driseai/3drise-viewer 0.1.26 → 0.1.28

package/dist/operations/catalogue/voxelize.js

@@ -0,0 +1,148 @@
+// Voxelise — the surface is digitised into small cubes, then the cubes peel off
+// and float away. Each cube is a real lit voxel (one instanced mesh, casting
+// shadows) holding the average colour of the surface it replaced. As the front
+// passes, the surface goes and its voxel pops in with a brief flash; a moment
+// later the voxel lifts off along the surface normal and upward, tumbling and
+// shrinking. Reverting flies every cube back and the surface re-forms.
+import { BoxGeometry } from 'three';
+import { defineOperation } from '../types.js';
+import { GLSL_ROT, addLayer, forEachMeshMaterial, removeLayer } from './shaderLayers.js';
+import { DIRECTION_OPTIONS, createFieldState, fieldGlsl, fieldUniforms, hideMeshes, runProgress, setFieldParams, surfaceLayer, } from './transitionField.js';
+import { sampleSurfaceCached, mulberry32 } from './surfaceSample.js';
+import { createFxInstances, disposeFxInstances } from './fxInstances.js';
+const P = 'Vox';
+const KEY = 'voxelize';
+const STATE = '__opVoxelize';
+const LIFE = 0.75;
+/** Quantise surface samples to a grid: one voxel per occupied cell, averaged. */
+function buildVoxels(target, resolution) {
+    const sample = sampleSurfaceCached(target, 40000, 37);
+    let min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+    for (let i = 0; i < sample.count; i++)
+        for (let a = 0; a < 3; a++) {
+            min[a] = Math.min(min[a], sample.position[i * 3 + a]);
+            max[a] = Math.max(max[a], sample.position[i * 3 + a]);
+        }
+    const cell = Math.max(max[0] - min[0], max[1] - min[1], max[2] - min[2], 1e-3) / Math.max(4, resolution);
+    const cells = new Map();
+    for (let i = 0; i < sample.count; i++) {
+        const ix = Math.floor((sample.position[i * 3] - min[0]) / cell);
+        const iy = Math.floor((sample.position[i * 3 + 1] - min[1]) / cell);
+        const iz = Math.floor((sample.position[i * 3 + 2] - min[2]) / cell);
+        const key = `${ix},${iy},${iz}`;
+        let v = cells.get(key);
+        if (!v) {
+            v = { p: [min[0] + (ix + 0.5) * cell, min[1] + (iy + 0.5) * cell, min[2] + (iz + 0.5) * cell], n: [0, 0, 0], c: [0, 0, 0], k: 0 };
+            cells.set(key, v);
+        }
+        for (let a = 0; a < 3; a++) {
+            v.n[a] += sample.normal[i * 3 + a];
+            v.c[a] += sample.color[i * 3 + a];
+        }
+        v.k++;
+    }
+    const n = cells.size;
+    const positions = new Float32Array(n * 3), normals = new Float32Array(n * 3), colors = new Float32Array(n * 3), rand = new Float32Array(n * 4);
+    const rnd = mulberry32(41);
+    let i = 0;
+    for (const v of cells.values()) {
+        const len = Math.hypot(v.n[0], v.n[1], v.n[2]) || 1;
+        for (let a = 0; a < 3; a++) {
+            positions[i * 3 + a] = v.p[a];
+            normals[i * 3 + a] = v.n[a] / len;
+            colors[i * 3 + a] = v.c[a] / v.k;
+        }
+        for (let a = 0; a < 4; a++)
+            rand[i * 4 + a] = rnd();
+        i++;
+    }
+    return { n, cell, positions, normals, colors, rand };
+}
+export default defineOperation({
+    value: 'voxelize',
+    label: 'Voxelise',
+    description: 'Digitise the targets into cubes that peel off and float away — reverting clicks them back',
+    channel: 'visual',
+    multi: true,
+    toggles: true,
+    usableIn: ['interaction', 'action'],
+    params: {
+        direction: { type: 'select', label: 'Direction', default: 'up', options: DIRECTION_OPTIONS },
+        resolution: { type: 'number', label: 'Resolution', default: 26, min: 6, max: 70, step: 1, hint: 'Cubes across the object’s largest side' },
+        lift: { type: 'number', label: 'Float', default: 1, min: 0, max: 4, step: 0.05, unit: '×' },
+        edgeColor: { type: 'color', label: 'Scan colour', default: '#7fe3ff' },
+        scale: { type: 'number', label: 'Pattern', default: 2, min: 0.5, max: 12, step: 0.1 },
+        duration: { type: 'number', label: 'Duration', default: 3, 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.04;
+            const life = { value: LIFE }, lift = { value: 1 };
+            const vox = buildVoxels(target, Math.round(Number(p.resolution)));
+            const s = vox.cell * 0.94;
+            const mesh = createFxInstances(target, {
+                geometry: new BoxGeometry(s, s, s),
+                count: vox.n, positions: vox.positions, colors: vox.colors,
+                attributes: { aVoxP: [vox.positions, 3], aVoxN: [vox.normals, 3], aVoxR: [vox.rand, 4] },
+                layerKey: 'voxelInstances', roughness: 0.55, metalness: 0.05,
+                layer: {
+                    uniforms: { ...fieldUniforms(P, field), uVoxLife: life, uVoxLift: lift },
+                    common: `varying float vVoxFlash;\n${fieldGlsl(P)}\n${GLSL_ROT}`,
+                    vertexPars: /* glsl */ `
+                    attribute vec3 aVoxP; attribute vec3 aVoxN; attribute vec4 aVoxR;
+                    float voxAge() { return (uVoxProgress - VoxBirthOf(VoxField(VoxNorm(aVoxP)))) / uVoxLife; }
+                    mat3 voxSpin(float a) { float fly = smoothstep(0.3, 1.0, a); return fxRot(normalize(aVoxR.xyz - 0.5 + vec3(1e-3)), fly * fly * (2.0 + 3.0 * aVoxR.w)); }`,
+                    normal: `{ objectNormal = voxSpin(voxAge()) * objectNormal; }`,
+                    vertex: /* glsl */ `
+                    {
+                      float a = voxAge();
+                      float pop = smoothstep(0.0, 0.14, a);
+                      float fly = smoothstep(0.3, 1.0, a);
+                      float sc = pop * (1.0 - smoothstep(0.72, 1.0, a));
+                      float E = uVoxExtent;
+                      vec3 off = (aVoxN * 0.3 + vec3(0.0, 1.0, 0.0) * (0.6 + 0.8 * aVoxR.y)) * E * 0.55 * uVoxLift * fly * fly
+                               + (aVoxR.xyz - 0.5) * E * 0.25 * fly;
+                      transformed = voxSpin(a) * (transformed * sc) + off;
+                      vVoxFlash = pop * (1.0 - smoothstep(0.1, 0.24, a));
+                    }`,
+                    emissive: `totalEmissiveRadiance += uVoxEdgeColor * vVoxFlash * 0.7;`,
+                },
+            });
+            st = { field, life, lift, mesh, mats: new Set() };
+            const own = st;
+            const layer = surfaceLayer(P, field, 'tint');
+            forEachMeshMaterial(target, (mat, m) => {
+                if (m.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.lift.value = Number(p.lift);
+        s.mesh.visible = true;
+        return runProgress(target, s.field, 1 + LIFE, {
+            duration: Number(p.duration), ease: 'none',
+            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;
+        return runProgress(target, s.field, 0, {
+            duration: Number(p.duration), ease: 'none',
+            onComplete: () => {
+                s.mats.forEach(m => removeLayer(m, KEY));
+                disposeFxInstances(s.mesh);
+                delete target.userData[STATE];
+            },
+        });
+    },
+});

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

@@ -0,0 +1,22 @@
+import type { Object3D } from 'three';
+export interface WarmContext {
+    gl: any;
+    scene: any;
+    cam: any;
+}
+export declare function warmContext(): WarmContext | null;
+/** compileAsync with a safety timeout (a driver that never reports ready must not hang an effect). */
+export declare function compileInBackground(root: Object3D, timeoutMs?: number): Promise<void>;
+/** Keep a freshly created helper off screen until its shaders are compiled (see warmHelpers). */
+export declare function hideUntilWarm(obj: Object3D): void;
+/** Compile every helper under `root` that is waiting, in the background, then show it. */
+export declare function warmHelpers(root: Object3D): Promise<void>;
+/**
+ * Warm-only runs (pre-warming): while this is on, an effect's runProgress compiles
+ * everything it needs and then stops — nothing animates. See runtime.prewarmEffect.
+ */
+export declare const warmMode: {
+    on: boolean;
+};
+export declare function retainPrograms(root: Object3D): void;
+//# sourceMappingURL=warmup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"warmup.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/warmup.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAY,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGhD,MAAM,WAAW,WAAW;IAAG,EAAE,EAAE,GAAG,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC;IAAC,GAAG,EAAE,GAAG,CAAA;CAAE;AAE9D,wBAAgB,WAAW,IAAI,WAAW,GAAG,IAAI,CAGhD;AAED,sGAAsG;AACtG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAQnF;AAUD,iGAAiG;AACjG,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,QAI1C;AAED,0FAA0F;AAC1F,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzD;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ;;CAAgB,CAAC;AAStC,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,QAmB5C"}

package/dist/operations/catalogue/warmup.js

@@ -0,0 +1,106 @@
+// =============================================================================
+// Shader warm-up — effects never freeze the scene.
+// =============================================================================
+//
+// WebGL compiles a shader program the first time a material is drawn with new
+// code, and three.js does that synchronously inside the frame: the whole scene
+// stops until it is done (worst on Windows, where ANGLE translates to Direct3D).
+// three's compileAsync avoids that — with KHR_parallel_shader_compile it issues
+// the compile and polls for completion without blocking — but only for objects
+// that are NOT being drawn yet: a visible material with new code still compiles
+// synchronously on the next frame.
+//
+// So effects compile before anything changes on screen:
+//   • layered materials: the layer is staged, a hidden clone with the same code
+//     is compiled in the background, then the layer is committed to the live
+//     material — three finds the finished program in its cache (same cache key)
+//     and reuses it, no compile (see shaderLayers.commitPendingLayers);
+//   • effect helpers (particles, threads, rings, beams, instances): their
+//     materials start hidden (material.visible = false; three still compiles
+//     hidden materials) and are shown once their program is ready.
+// Without a renderer / camera (SSR, tests) everything happens immediately.
+//
+import { SceneStore } from '@3driseai/3drise-core';
+import { InstancedMesh, LineSegments, Mesh, Points } from 'three';
+import cameraManager from '../../utils/CameraSingleton.js';
+export function warmContext() {
+    const gl = SceneStore.gl, scene = SceneStore.scene, cam = cameraManager.getCamera?.();
+    return gl && scene && cam && typeof gl.compileAsync === 'function' ? { gl, scene, cam } : null;
+}
+/** compileAsync with a safety timeout (a driver that never reports ready must not hang an effect). */
+export function compileInBackground(root, timeoutMs = 8000) {
+    const ctx = warmContext();
+    if (!ctx)
+        return Promise.resolve();
+    let timer;
+    return Promise.race([
+        Promise.resolve(ctx.gl.compileAsync(root, ctx.cam, ctx.scene)).then(() => undefined, () => undefined),
+        new Promise(r => { timer = setTimeout(r, timeoutMs); }),
+    ]).finally(() => clearTimeout(timer));
+}
+const FLAG = '__opFxWarm';
+const materialsOf = (obj) => {
+    const out = [];
+    obj.traverse((c) => { if (c.material)
+        out.push(...(Array.isArray(c.material) ? c.material : [c.material])); });
+    return out;
+};
+/** Keep a freshly created helper off screen until its shaders are compiled (see warmHelpers). */
+export function hideUntilWarm(obj) {
+    if (!warmContext())
+        return;
+    for (const m of materialsOf(obj))
+        m.visible = false;
+    obj.userData[FLAG] = true;
+}
+/** Compile every helper under `root` that is waiting, in the background, then show it. */
+export function warmHelpers(root) {
+    const waiting = [];
+    root.traverse((c) => { if (c.userData?.[FLAG])
+        waiting.push(c); });
+    return Promise.all(waiting.map(h => compileInBackground(h).then(() => {
+        for (const m of materialsOf(h))
+            m.visible = true;
+        delete h.userData[FLAG];
+        retainPrograms(h);
+    }))).then(() => undefined);
+}
+/**
+ * Warm-only runs (pre-warming): while this is on, an effect's runProgress compiles
+ * everything it needs and then stops — nothing animates. See runtime.prewarmEffect.
+ */
+export const warmMode = { on: false };
+/**
+ * Effect helpers are disposed when an effect ends, and three destroys a program
+ * when its last material goes — so the next play would compile again. Keep one
+ * tiny, never-drawn clone per helper material so its program stays cached.
+ */
+const retained = [];
+const retainedKeys = new Set();
+export function retainPrograms(root) {
+    const ctx = warmContext();
+    if (!ctx)
+        return;
+    root.traverse((c) => {
+        const mats = c.material ? (Array.isArray(c.material) ? c.material : [c.material]) : [];
+        for (const m of mats) {
+            const key = `${c.type}|${m.type}|${m.vertexShader?.length ?? ''}|${m.fragmentShader?.length ?? ''}|${m.customProgramCacheKey?.() ?? ''}`;
+            if (retainedKeys.has(key))
+                continue;
+            retainedKeys.add(key);
+            const keep = m.clone();
+            keep.onBeforeCompile = m.onBeforeCompile;
+            keep.customProgramCacheKey = m.customProgramCacheKey;
+            keep.visible = true;
+            const stand = c.isInstancedMesh ? new InstancedMesh(c.geometry, keep, 1) : c.isPoints ? new Points(c.geometry, keep)
+                : c.isLineSegments ? new LineSegments(c.geometry, keep) : c.isMesh ? new Mesh(c.geometry, keep) : null;
+            if (!stand)
+                continue;
+            try {
+                ctx.gl.compile(stand, ctx.cam, ctx.scene);
+                retained.push(keep);
+            }
+            catch { /* ignore */ }
+        }
+    });
+}

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

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

package/dist/operations/catalogue/zoom.js

@@ -4,6 +4,7 @@ export default defineOperation({
     value: 'zoom',
     label: 'Zoom to',
     description: 'Fly the camera close to the target, facing it',
+    channel: 'camera',
     multi: false,
     toggles: true,
     usableIn: ['interaction', 'action'],

package/dist/operations/index.d.ts

@@ -1,5 +1,7 @@
 export * from './types';
-export { OPERATIONS, getOperation, operationsFor, resolveParams } from './registry';
-export { runEffect, applyOperation, revertOperation, isOperationOn, resolveEffectTargets, runActionEffects, areActionEffectsOn, subscribeActionEffects, registerOperationTools, } from './runtime';
+export { OPERATIONS, getOperation, operationsFor, resolveParams, channelOf } from './registry';
+export { runEffect, applyOperation, revertOperation, runOf, isOperationOn, resolveEffectTargets, runActionEffects, previewEffect, previewEffects, isPreviewing, prewarmEffect, areActionEffectsOn, subscribeActionEffects, registerOperationTools, } from './runtime';
 export { useOperationsRuntime } from './useOperationsRuntime';
+export { ObjectEffectsController, runningObjectEffects, objectEffectParams, isObjectOperation, surfaceSignature } from './objectEffects';
+export { useObjectEffectLayers } from './useObjectEffectLayers';
 //# sourceMappingURL=index.d.ts.map

package/dist/operations/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/operations/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EACH,SAAS,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,oBAAoB,EAC/E,gBAAgB,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,sBAAsB,GACvF,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/operations/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC/F,OAAO,EACH,SAAS,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,oBAAoB,EACtF,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,sBAAsB,GACnJ,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACzI,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/operations/index.js

@@ -1,4 +1,6 @@
 export * from './types.js';
-export { OPERATIONS, getOperation, operationsFor, resolveParams } from './registry.js';
-export { runEffect, applyOperation, revertOperation, isOperationOn, resolveEffectTargets, runActionEffects, areActionEffectsOn, subscribeActionEffects, registerOperationTools, } from './runtime.js';
+export { OPERATIONS, getOperation, operationsFor, resolveParams, channelOf } from './registry.js';
+export { runEffect, applyOperation, revertOperation, runOf, isOperationOn, resolveEffectTargets, runActionEffects, previewEffect, previewEffects, isPreviewing, prewarmEffect, areActionEffectsOn, subscribeActionEffects, registerOperationTools, } from './runtime.js';
 export { useOperationsRuntime } from './useOperationsRuntime.js';
+export { ObjectEffectsController, runningObjectEffects, objectEffectParams, isObjectOperation, surfaceSignature } from './objectEffects.js';
+export { useObjectEffectLayers } from './useObjectEffectLayers.js';

package/dist/operations/objectEffects.d.ts

@@ -0,0 +1,46 @@
+import type { Object3D } from 'three';
+import type { ObjectEffect } from '@3driseai/3drise-core';
+import type { OperationDefinition, OperationParams } from './types';
+/** An operation can be an object effect. */
+export declare const isObjectOperation: (def: OperationDefinition | undefined) => def is OperationDefinition;
+/**
+ * The effects that actually run: on, known, usable on objects, one per operation,
+ * and one of each stack (the first wins).
+ */
+export declare function runningObjectEffects(effects: ObjectEffect[] | undefined): ObjectEffect[];
+/** An object effect's parameters: defaults, its overrides, then what object effects force. */
+export declare const objectEffectParams: (def: OperationDefinition, effect: Pick<ObjectEffect, "params">) => OperationParams;
+export declare class ObjectEffectsController {
+    private root;
+    private running;
+    private effects;
+    private refreshing;
+    private disposed;
+    constructor(root: Object3D);
+    /** The object's targets for an effect: the object, or its named nodes. */
+    private targetsOf;
+    private on;
+    private off;
+    /**
+     * Bring what runs in line with `effects`.
+     *   animate  switching an effect on / off plays its transition (studio, actions)
+     *   instant  everything lands in its end state at once (scene load)
+     * A changed parameter always lands at once.
+     */
+    sync(effects: ObjectEffect[] | undefined, mode: 'animate' | 'instant'): void;
+    /**
+     * The object's meshes or materials were replaced: take every effect off the
+     * old ones and put it straight back on the new ones (no transition).
+     */
+    refresh(): Promise<void>;
+    /** Take everything off at once (the object is going away). */
+    dispose(): void;
+    /** Ids of the effects running now (tests / studio). */
+    get runningIds(): string[];
+}
+/**
+ * What identifies the object's own drawable surface: its meshes and their
+ * materials (effect helpers left out). A change means effects must move over.
+ */
+export declare function surfaceSignature(root: Object3D): string;
+//# sourceMappingURL=objectEffects.d.ts.map

package/dist/operations/objectEffects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"objectEffects.d.ts","sourceRoot":"","sources":["../../src/operations/objectEffects.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEtC,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,uBAAuB,CAAC;AAGzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAEpE,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB,GAAI,KAAK,mBAAmB,GAAG,SAAS,KAAG,GAAG,IAAI,mBACpB,CAAC;AAE7D;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,SAAS,GAAG,YAAY,EAAE,CAgBxF;AAED,8FAA8F;AAC9F,eAAO,MAAM,kBAAkB,GAAI,KAAK,mBAAmB,EAAE,QAAQ,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,KAAG,eACzB,CAAC;AAY5E,qBAAa,uBAAuB;IAMpB,OAAO,CAAC,IAAI;IALxB,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,QAAQ,CAAS;gBAEL,IAAI,EAAE,QAAQ;IAElC,0EAA0E;IAC1E,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,EAAE;IAIV,OAAO,CAAC,GAAG;IAQX;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,SAAS,GAAG,SAAS;IAwBrE;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAaxB,8DAA8D;IAC9D,OAAO;IAMP,uDAAuD;IACvD,IAAI,UAAU,IAAI,MAAM,EAAE,CAAqC;CAClE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAQvD"}

package/dist/operations/objectEffects.js

@@ -0,0 +1,136 @@
+import { findNodesByName } from '@3driseai/3drise-core';
+import { getOperation, resolveParams } from './registry.js';
+import { applyOperation, forceRevert, runOf } from './runtime.js';
+/** An operation can be an object effect. */
+export const isObjectOperation = (def) => !!def && def.usableIn.includes('object') && !!def.revert;
+/**
+ * The effects that actually run: on, known, usable on objects, one per operation,
+ * and one of each stack (the first wins).
+ */
+export function runningObjectEffects(effects) {
+    const out = [];
+    const ops = new Set();
+    const stacks = new Set();
+    for (const e of effects ?? []) {
+        if (!e?.enabled)
+            continue;
+        const def = getOperation(e.operation);
+        if (!isObjectOperation(def) || ops.has(def.value))
+            continue;
+        if (def.stack) {
+            if (stacks.has(def.stack))
+                continue;
+            stacks.add(def.stack);
+        }
+        ops.add(def.value);
+        out.push(e);
+    }
+    return out;
+}
+/** An object effect's parameters: defaults, its overrides, then what object effects force. */
+export const objectEffectParams = (def, effect) => ({ ...resolveParams(def, effect.params), ...(def.objectParams ?? {}) });
+const namesKey = (e) => (e.meshNames ?? []).join('|');
+export class ObjectEffectsController {
+    root;
+    running = new Map(); // effect id →
+    effects = [];
+    refreshing = null;
+    disposed = false;
+    constructor(root) {
+        this.root = root;
+    }
+    /** The object's targets for an effect: the object, or its named nodes. */
+    targetsOf(e) {
+        if (!e.meshNames?.length)
+            return [this.root];
+        const out = [];
+        for (const name of e.meshNames)
+            out.push(...findNodesByName(this.root, name).filter(n => n !== this.root));
+        return out;
+    }
+    on(def, targets, params) {
+        for (const t of targets)
+            applyOperation(def, t, params, this.root, { bare: true });
+    }
+    off(r, instant) {
+        const def = getOperation(r.op);
+        if (!def)
+            return;
+        // with its own parameters — it may have gone on at once (load / edit), but goes off with its transition
+        const params = instant ? { ...r.params, duration: 0 } : r.params;
+        for (const t of r.targets)
+            forceRevert(def, t, params);
+    }
+    /**
+     * Bring what runs in line with `effects`.
+     *   animate  switching an effect on / off plays its transition (studio, actions)
+     *   instant  everything lands in its end state at once (scene load)
+     * A changed parameter always lands at once.
+     */
+    sync(effects, mode) {
+        if (this.disposed)
+            return;
+        this.effects = effects ?? [];
+        if (this.refreshing)
+            return; // the refresh puts the latest list back when it is done
+        const next = runningObjectEffects(effects);
+        const byId = new Map(next.map(e => [e.id, e]));
+        for (const [id, r] of this.running) {
+            const e = byId.get(id);
+            if (e && e.operation === r.op && namesKey(e) === r.targetsKey)
+                continue;
+            this.off(r, mode === 'instant');
+            this.running.delete(id);
+        }
+        for (const e of next) {
+            const def = getOperation(e.operation);
+            const params = objectEffectParams(def, e);
+            const paramsKey = JSON.stringify(params);
+            const r = this.running.get(e.id);
+            if (r && r.paramsKey === paramsKey)
+                continue;
+            const targets = r?.targets ?? this.targetsOf(e);
+            this.on(def, targets, r || mode === 'instant' ? { ...params, duration: 0 } : params);
+            this.running.set(e.id, { op: def.value, targets, targetsKey: namesKey(e), params, paramsKey });
+        }
+    }
+    /**
+     * The object's meshes or materials were replaced: take every effect off the
+     * old ones and put it straight back on the new ones (no transition).
+     */
+    refresh() {
+        if (this.refreshing || !this.running.size)
+            return this.refreshing ?? Promise.resolve();
+        const list = [...this.running.values()];
+        this.running.clear();
+        list.forEach(r => this.off(r, true));
+        const done = Promise.all(list.flatMap(r => r.targets.map(t => runOf(r.op, t))));
+        this.refreshing = done.then(() => {
+            this.refreshing = null;
+            this.sync(this.effects, 'instant');
+        });
+        return this.refreshing;
+    }
+    /** Take everything off at once (the object is going away). */
+    dispose() {
+        this.running.forEach(r => this.off(r, true));
+        this.running.clear();
+        this.disposed = true;
+    }
+    /** Ids of the effects running now (tests / studio). */
+    get runningIds() { return [...this.running.keys()]; }
+}
+/**
+ * What identifies the object's own drawable surface: its meshes and their
+ * materials (effect helpers left out). A change means effects must move over.
+ */
+export function surfaceSignature(root) {
+    const parts = [];
+    root.traverse((c) => {
+        if (!c.isMesh || c.userData?.__opFxHelper)
+            return;
+        const mats = Array.isArray(c.material) ? c.material : [c.material];
+        parts.push(c.uuid + ':' + mats.map((m) => m?.uuid ?? '').join(','));
+    });
+    return parts.join(';');
+}

package/dist/operations/registry.d.ts

@@ -1,11 +1,16 @@
-import type { OperationName } from '@3driseai/3drise-core';
+import type { OperationChannel, OperationEffect, OperationName } from '@3driseai/3drise-core';
 import type { OperationDefinition, OperationParams, OperationSource } from './types';
 export declare const OPERATIONS: OperationDefinition[];
 export declare const getOperation: (name: OperationName) => OperationDefinition | undefined;
-/** Operations offered in a context (gallery-only ones only on gallery objects). */
+/** Operations offered in a context (gallery-only ones only on gallery objects), optionally one channel. */
 export declare const operationsFor: (source: OperationSource, opts?: {
     gallery?: boolean;
+    channel?: OperationChannel;
 }) => OperationDefinition[];
+/** An effect's channel — the stored one, else its operation's (effects saved before channels). */
+export declare const channelOf: (effect: Pick<OperationEffect, "operation"> & {
+    channel?: OperationChannel;
+}) => OperationChannel;
 /** Defaults overlaid with the effect's own values (unknown keys dropped). */
 export declare function resolveParams(def: OperationDefinition, overrides?: OperationParams): OperationParams;
 //# sourceMappingURL=registry.d.ts.map

package/dist/operations/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/operations/registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AASrF,eAAO,MAAM,UAAU,EAAE,mBAAmB,EAAqE,CAAC;AAIlH,eAAO,MAAM,YAAY,GAAI,MAAM,aAAa,KAAG,mBAAmB,GAAG,SAA6B,CAAC;AAEvG,mFAAmF;AACnF,eAAO,MAAM,aAAa,GAAI,QAAQ,eAAe,EAAE,OAAM;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,KAAG,mBAAmB,EAClB,CAAC;AAE5F,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,GAAG,EAAE,mBAAmB,EAAE,SAAS,CAAC,EAAE,eAAe,GAAG,eAAe,CAOpG"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/operations/registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC9F,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AA0CrF,eAAO,MAAM,UAAU,EAAE,mBAAmB,EAO3C,CAAC;AAIF,eAAO,MAAM,YAAY,GAAI,MAAM,aAAa,KAAG,mBAAmB,GAAG,SAA6B,CAAC;AAEvG,2GAA2G;AAC3G,eAAO,MAAM,aAAa,GAAI,QAAQ,eAAe,EAAE,OAAM;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,gBAAgB,CAAA;CAAO,KAAG,mBAAmB,EACG,CAAC;AAE7I,kGAAkG;AAClG,eAAO,MAAM,SAAS,GAAI,QAAQ,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,gBAAgB,CAAA;CAAE,KAAG,gBAC/B,CAAC;AAE1E,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,GAAG,EAAE,mBAAmB,EAAE,SAAS,CAAC,EAAE,eAAe,GAAG,eAAe,CAOpG"}

package/dist/operations/registry.js

@@ -5,11 +5,53 @@ import zoom from './catalogue/zoom.js';
 import focus from './catalogue/focus.js';
 import moveToFront from './catalogue/moveToFront.js';
 import displayImage from './catalogue/displayImage.js';
-export const OPERATIONS = [glow, fade, visibility, zoom, focus, moveToFront, displayImage];
+import rimLight from './catalogue/rimLight.js';
+import dissolve from './catalogue/dissolve.js';
+import spin from './catalogue/spin.js';
+import jelly from './catalogue/jelly.js';
+import flip from './catalogue/flip.js';
+import swirl from './catalogue/swirl.js';
+import emberAsh from './catalogue/emberAsh.js';
+import particleSwarm from './catalogue/particleSwarm.js';
+import hologram from './catalogue/hologram.js';
+import shatter from './catalogue/shatter.js';
+import sandErosion from './catalogue/sandErosion.js';
+import teleport from './catalogue/teleport.js';
+import inkBloom from './catalogue/inkBloom.js';
+import flock from './catalogue/flock.js';
+import metalize from './catalogue/metalize.js';
+import liquidMetal from './catalogue/liquidMetal.js';
+import frost from './catalogue/frost.js';
+import heatCracks from './catalogue/heatCracks.js';
+import petrify from './catalogue/petrify.js';
+import portal from './catalogue/portal.js';
+import voxelize from './catalogue/voxelize.js';
+import unweave from './catalogue/unweave.js';
+import petalPeel from './catalogue/petalPeel.js';
+import frame from './catalogue/frame.js';
+import orbit from './catalogue/orbit.js';
+import kintsugi from './catalogue/kintsugi.js';
+import rainBeads from './catalogue/rainBeads.js';
+import ivy from './catalogue/ivy.js';
+import curlSmoke from './catalogue/curlSmoke.js';
+import lidarScan from './catalogue/lidarScan.js';
+import print3d from './catalogue/print3d.js';
+import silkDrape from './catalogue/silkDrape.js';
+// Grouped by channel (picker order): transform · visual · camera.
+export const OPERATIONS = [
+    jelly, flip, spin, swirl, moveToFront,
+    glow, rimLight, dissolve, emberAsh, particleSwarm, hologram, shatter,
+    sandErosion, teleport, inkBloom, flock, liquidMetal, metalize, frost, heatCracks, petrify, kintsugi, rainBeads, ivy,
+    portal, voxelize, unweave, petalPeel, curlSmoke, lidarScan, print3d, silkDrape,
+    fade, visibility, displayImage,
+    zoom, frame, focus, orbit,
+];
 const byName = new Map(OPERATIONS.map(o => [o.value, o]));
 export const getOperation = (name) => byName.get(name);
-/** Operations offered in a context (gallery-only ones only on gallery objects). */
-export const operationsFor = (source, opts = {}) => OPERATIONS.filter(o => o.usableIn.includes(source) && (!o.galleryOnly || opts.gallery));
+/** Operations offered in a context (gallery-only ones only on gallery objects), optionally one channel. */
+export const operationsFor = (source, opts = {}) => OPERATIONS.filter(o => o.usableIn.includes(source) && (!o.galleryOnly || opts.gallery) && (!opts.channel || o.channel === opts.channel));
+/** An effect's channel — the stored one, else its operation's (effects saved before channels). */
+export const channelOf = (effect) => effect.channel ?? getOperation(effect.operation)?.channel ?? 'visual';
 /** Defaults overlaid with the effect's own values (unknown keys dropped). */
 export function resolveParams(def, overrides) {
     const out = {};

package/dist/operations/runtime.d.ts

@@ -4,8 +4,25 @@ import type { OperationDefinition, OperationParams, OperationTools } from './typ
 /** Register the mounted scene's tools. Returns the unregister. */
 export declare function registerOperationTools(t: OperationTools): () => void;
 export declare function isOperationOn(op: OperationName, target: Object3D): boolean;
-export declare function applyOperation(def: OperationDefinition, target: Object3D, params: OperationParams, self?: Object3D | null): boolean;
-export declare function revertOperation(def: OperationDefinition, target: Object3D): boolean;
+export declare function applyOperation(def: OperationDefinition, target: Object3D, params: OperationParams, self?: Object3D | null, opts?: {
+    bare?: boolean;
+}): boolean;
+/** The last run (apply or revert) of an op on a target — resolves when it has really finished. */
+export declare const runOf: (op: OperationName, target: Object3D) => Promise<void>;
+/**
+ * Undo an operation that is on. `params` overrides the ones it was applied with
+ * (e.g. a zero duration to take it off at once); `bare` runs it with no scene tools.
+ */
+export declare function revertOperation(def: OperationDefinition, target: Object3D, opts?: {
+    params?: Partial<OperationParams>;
+    bare?: boolean;
+}): boolean;
+/**
+ * Undo an operation's effect on a target even when the runtime no longer tracks
+ * it as on (its scene tools were unregistered first, on unmount). Reverts of
+ * operations that are not on do nothing.
+ */
+export declare function forceRevert(def: OperationDefinition, target: Object3D, params: OperationParams): void;
 /** The objects an effect acts on: 'self', object ids, narrowed to model nodes. */
 export declare function resolveEffectTargets(effect: OperationEffect, self?: Object3D | null): Object3D[];
 /**
@@ -14,6 +31,27 @@ export declare function resolveEffectTargets(effect: OperationEffect, self?: Obj
  *   apply / revert / toggle  explicit
  */
 export declare function runEffect(effect: OperationEffect, mode: 'trigger' | 'apply' | 'revert' | 'toggle', self?: Object3D | null): void;
+/**
+ * Play an effect for the studio and put everything back: apply, wait for the run
+ * to REALLY finish (it may first compile its shaders in the background), hold a
+ * moment, revert and wait for that too. One-shot operations (spin, jelly, flip)
+ * just play; orbit plays and flies home. An effect that is already on is replayed
+ * (revert, then apply) so the scene ends as it was.
+ * Pressing play again on the same row — also after switching its operation —
+ * replaces the running preview: the old one is put back and the new one plays.
+ */
+export declare function previewEffect(effect: OperationEffect, self?: Object3D | null): Promise<boolean>;
+/** Preview several effects together (an interaction's "Try it"). */
+export declare function previewEffects(effects: OperationEffect[], self?: Object3D | null): Promise<boolean>;
+export declare const isPreviewing: (effectId: string) => boolean;
+/**
+ * Compile an effect's shaders ahead of time, without showing anything, so its
+ * first real play starts instantly. Visual effects only (the others have no
+ * shaders). Runs one at a time, in the background; each (effect, target) once.
+ * Used when an effect is picked in the editor and, for every effect a scene's
+ * interactions and actions use, when the scene loads.
+ */
+export declare function prewarmEffect(effect: OperationEffect, self?: Object3D | null): Promise<void>;
 /** Apply or undo an action's effects directly (the editor's "Try it"). */
 export declare function runActionEffects(action: ActionSequence, mode: 'apply' | 'revert'): void;
 export declare const areActionEffectsOn: (actionId: string) => boolean;