@3driseai/3drise-viewer 0.1.25 → 0.1.26

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

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

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

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

package/dist/operations/catalogue/focus.js

@@ -0,0 +1,22 @@
+import { Vector3 } from 'three';
+import { DEFAULT_EASE, defineOperation } from '../types.js';
+export default defineOperation({
+    value: 'focus',
+    label: 'Look at',
+    description: 'Turn the camera to face the target, without moving it',
+    multi: false,
+    toggles: true,
+    usableIn: ['interaction', 'action'],
+    exclusive: { group: 'camera', release: 'handover' },
+    params: {
+        duration: { type: 'number', label: 'Duration', default: 1, min: 0, max: 10, step: 0.05, unit: 's' },
+    },
+    apply(target, p, ctx) {
+        ctx.saveCameraHome();
+        const at = target.getWorldPosition(new Vector3());
+        void ctx.tools.animateCamera({}, Number(p.duration), DEFAULT_EASE, [at.x, at.y, at.z]);
+    },
+    revert(_target, p, ctx) {
+        ctx.restoreCameraHome(Number(p.duration), DEFAULT_EASE);
+    },
+});

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

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

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

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

package/dist/operations/catalogue/glow.js

@@ -0,0 +1,49 @@
+import { gsap } from 'gsap';
+import { defineOperation } from '../types.js';
+import { forEachMaterial, isLit, toColor } from './materialFx.js';
+const KEY = '__opGlow';
+export default defineOperation({
+    value: 'glow',
+    label: 'Glow',
+    description: 'Light the targets up with an emissive glow',
+    multi: true,
+    toggles: true,
+    usableIn: ['interaction', 'action'],
+    params: {
+        color: { type: 'color', label: 'Colour', default: '#3380ff' },
+        intensity: { type: 'number', label: 'Intensity', default: 3, min: 0, max: 20, step: 0.1 },
+        duration: { type: 'number', label: 'Duration', default: 0.4, min: 0, max: 10, step: 0.05, unit: 's' },
+    },
+    apply(target, p) {
+        const color = toColor(String(p.color));
+        forEachMaterial(target, (mat) => {
+            if (!isLit(mat))
+                return;
+            if (!mat.userData[KEY]) {
+                mat.userData[KEY] = { emissive: mat.emissive.getHex(), intensity: mat.emissiveIntensity, toneMapped: mat.toneMapped };
+            }
+            mat.toneMapped = false;
+            gsap.killTweensOf(mat);
+            gsap.killTweensOf(mat.emissive);
+            gsap.to(mat, { emissiveIntensity: Number(p.intensity), duration: Number(p.duration), ease: 'power2.out' });
+            gsap.to(mat.emissive, { r: color.r, g: color.g, b: color.b, duration: Number(p.duration), ease: 'power2.out' });
+        });
+    },
+    revert(target, p) {
+        forEachMaterial(target, (mat) => {
+            if (!isLit(mat))
+                return;
+            const orig = mat.userData[KEY];
+            if (!orig)
+                return;
+            const c = toColor('#000000').setHex(orig.emissive);
+            gsap.killTweensOf(mat);
+            gsap.killTweensOf(mat.emissive);
+            gsap.to(mat, {
+                emissiveIntensity: orig.intensity, duration: Number(p.duration), ease: 'power2.in',
+                onComplete: () => { mat.toneMapped = orig.toneMapped; delete mat.userData[KEY]; },
+            });
+            gsap.to(mat.emissive, { r: c.r, g: c.g, b: c.b, duration: Number(p.duration), ease: 'power2.in' });
+        });
+    },
+});

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

@@ -0,0 +1,6 @@
+import { Color, MeshStandardMaterial } from 'three';
+import type { Material, Object3D } from 'three';
+export declare function forEachMaterial(root: Object3D, fn: (mat: Material) => void): void;
+export declare const isLit: (m: Material) => m is MeshStandardMaterial;
+export declare const toColor: (hex: string) => Color;
+//# sourceMappingURL=materialFx.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"materialFx.d.ts","sourceRoot":"","sources":["../../../src/operations/catalogue/materialFx.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAwB,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAC1E,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEhD,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,QAM1E;AAED,eAAO,MAAM,KAAK,GAAI,GAAG,QAAQ,KAAG,CAAC,IAAI,oBACiC,CAAC;AAE3E,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,UAAmB,CAAC"}

package/dist/operations/catalogue/materialFx.js

@@ -0,0 +1,13 @@
+// Material helpers shared by glow / fade. Originals are kept on the material's
+// userData under op-specific keys, so glow and fade can stack and revert exactly.
+import { Color, MeshPhysicalMaterial, MeshStandardMaterial } from 'three';
+export function forEachMaterial(root, fn) {
+    root.traverse((child) => {
+        if (!child.isMesh && !child.isPoints && !child.isLine)
+            return;
+        const mats = Array.isArray(child.material) ? child.material : [child.material];
+        mats.forEach((m) => m && fn(m));
+    });
+}
+export const isLit = (m) => m instanceof MeshStandardMaterial || m instanceof MeshPhysicalMaterial;
+export const toColor = (hex) => new Color(hex);

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

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

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

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

package/dist/operations/catalogue/moveToFront.js

@@ -0,0 +1,25 @@
+import { DEFAULT_EASE, defineOperation } from '../types.js';
+export default defineOperation({
+    value: 'moveToFront',
+    label: 'Bring to front',
+    description: 'Bring the target in front of the camera',
+    multi: false,
+    toggles: true,
+    usableIn: ['interaction', 'action'],
+    exclusive: { group: 'front', release: 'revert' },
+    params: {
+        distance: { type: 'number', label: 'Distance', default: 2, min: 0.1, max: 100, step: 0.1 },
+        width: { type: 'number', label: 'Scale X', default: 6, min: 0.01, max: 100, step: 0.1 },
+        height: { type: 'number', label: 'Scale Y', default: 4, min: 0.01, max: 100, step: 0.1 },
+        duration: { type: 'number', label: 'Duration', default: 1, min: 0, max: 10, step: 0.05, unit: 's' },
+    },
+    apply(target, p, ctx) {
+        ctx.tools.moveToFront(target, {
+            distance: Number(p.distance), scale: [Number(p.width), Number(p.height)],
+            duration: Number(p.duration), ease: DEFAULT_EASE,
+        });
+    },
+    revert(target, p, ctx) {
+        ctx.tools.restoreTransform(target, { duration: Number(p.duration), ease: DEFAULT_EASE });
+    },
+});

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

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

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

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

package/dist/operations/catalogue/visibility.js

@@ -0,0 +1,24 @@
+import { defineOperation } from '../types.js';
+const KEY = '__opVisible';
+export default defineOperation({
+    value: 'visibility',
+    label: 'Show / hide',
+    description: 'Hide (or show) the targets instantly',
+    multi: true,
+    toggles: true,
+    usableIn: ['interaction', 'action'],
+    params: {
+        mode: { type: 'select', label: 'Make it', default: 'hide', options: [{ value: 'hide', label: 'Hidden' }, { value: 'show', label: 'Visible' }] },
+    },
+    apply(target, p) {
+        if (target.userData[KEY] === undefined)
+            target.userData[KEY] = target.visible;
+        target.visible = p.mode === 'show';
+    },
+    revert(target) {
+        if (target.userData[KEY] === undefined)
+            return;
+        target.visible = target.userData[KEY];
+        delete target.userData[KEY];
+    },
+});

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

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

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

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

package/dist/operations/catalogue/zoom.js

@@ -0,0 +1,32 @@
+import { Quaternion, Vector3 } from 'three';
+import { DEFAULT_EASE, defineOperation } from '../types.js';
+export default defineOperation({
+    value: 'zoom',
+    label: 'Zoom to',
+    description: 'Fly the camera close to the target, facing it',
+    multi: false,
+    toggles: true,
+    usableIn: ['interaction', 'action'],
+    exclusive: { group: 'camera', release: 'handover' },
+    params: {
+        distance: { type: 'number', label: 'Distance', default: 2, min: 0.1, max: 100, step: 0.1 },
+        duration: { type: 'number', label: 'Duration', default: 1, min: 0, max: 10, step: 0.05, unit: 's' },
+    },
+    apply(target, p, ctx) {
+        const pose = ctx.tools.cameraPose();
+        if (!pose)
+            return;
+        ctx.saveCameraHome();
+        const camPos = new Vector3(...pose.position);
+        const at = target.getWorldPosition(new Vector3());
+        // Stand in front of the target, on the side the camera is already on.
+        const forward = new Vector3(0, 0, 1).applyQuaternion(target.getWorldQuaternion(new Quaternion()));
+        if (forward.dot(camPos.clone().sub(at).normalize()) < 0)
+            forward.negate();
+        const to = at.clone().add(forward.multiplyScalar(Number(p.distance)));
+        void ctx.tools.animateCamera({ position: [to.x, to.y, to.z] }, Number(p.duration), DEFAULT_EASE, [at.x, at.y, at.z]);
+    },
+    revert(_target, p, ctx) {
+        ctx.restoreCameraHome(Number(p.duration), DEFAULT_EASE);
+    },
+});

package/dist/operations/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export { OPERATIONS, getOperation, operationsFor, resolveParams } from './registry';
+export { runEffect, applyOperation, revertOperation, isOperationOn, resolveEffectTargets, runActionEffects, areActionEffectsOn, subscribeActionEffects, registerOperationTools, } from './runtime';
+export { useOperationsRuntime } from './useOperationsRuntime';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/operations/index.js

@@ -0,0 +1,4 @@
+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 { useOperationsRuntime } from './useOperationsRuntime.js';

package/dist/operations/registry.d.ts

@@ -0,0 +1,11 @@
+import type { 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). */
+export declare const operationsFor: (source: OperationSource, opts?: {
+    gallery?: boolean;
+}) => OperationDefinition[];
+/** 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

@@ -0,0 +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"}

package/dist/operations/registry.js

@@ -0,0 +1,21 @@
+import glow from './catalogue/glow.js';
+import fade from './catalogue/fade.js';
+import visibility from './catalogue/visibility.js';
+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];
+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));
+/** Defaults overlaid with the effect's own values (unknown keys dropped). */
+export function resolveParams(def, overrides) {
+    const out = {};
+    for (const [key, spec] of Object.entries(def.params ?? {})) {
+        const v = overrides?.[key];
+        out[key] = v === undefined || v === null ? spec.default : v;
+    }
+    return out;
+}

package/dist/operations/runtime.d.ts

@@ -0,0 +1,22 @@
+import type { Object3D } from 'three';
+import type { ActionSequence, OperationEffect, OperationName } from '@3driseai/3drise-core';
+import type { OperationDefinition, OperationParams, OperationTools } from './types';
+/** 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;
+/** The objects an effect acts on: 'self', object ids, narrowed to model nodes. */
+export declare function resolveEffectTargets(effect: OperationEffect, self?: Object3D | null): Object3D[];
+/**
+ * Run one effect.
+ *   trigger  interactions: toggle when the operation toggles, else apply
+ *   apply / revert / toggle  explicit
+ */
+export declare function runEffect(effect: OperationEffect, mode: 'trigger' | 'apply' | 'revert' | 'toggle', self?: Object3D | null): 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;
+/** Subscribe to action-effects on/off changes (studio badges). */
+export declare function subscribeActionEffects(fn: () => void): () => void;
+//# sourceMappingURL=runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/operations/runtime.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEtC,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAgB,MAAM,uBAAuB,CAAC;AAG1G,OAAO,KAAK,EAAoB,mBAAmB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AA2BtG,kEAAkE;AAClE,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,IAAI,CAQpE;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,CAE1E;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,mBAAmB,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAkBnI;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,mBAAmB,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,CASnF;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,QAAQ,EAAE,CAahG;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,IAAI,CAWhI;AAQD,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAQvF;AAED,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,YAAkC,CAAC;AAEtF,kEAAkE;AAClE,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAGjE"}

package/dist/operations/runtime.js

@@ -0,0 +1,161 @@
+import { SceneActions, findNodesByName } from '@3driseai/3drise-core';
+import { findById } from '../utils/sceneQuery.js';
+import { getOperation, resolveParams } from './registry.js';
+const active = new Map(); // `${op}:${uuid}`
+const slots = new Map(); // exclusive group → active key
+const toolsStack = [];
+let cameraHome = null;
+const keyOf = (op, target) => `${op}:${target.uuid}`;
+const tools = () => toolsStack[toolsStack.length - 1];
+function context(self) {
+    const t = tools();
+    if (!t)
+        return null;
+    return {
+        tools: t,
+        self,
+        saveCameraHome: () => { if (!cameraHome)
+            cameraHome = t.cameraPose(); },
+        restoreCameraHome: (duration, ease) => {
+            const home = cameraHome;
+            cameraHome = null;
+            if (home)
+                void t.animateCamera({ position: home.position }, duration, ease, home.target);
+        },
+    };
+}
+/** Register the mounted scene's tools. Returns the unregister. */
+export function registerOperationTools(t) {
+    toolsStack.push(t);
+    ensureActionsSubscription();
+    return () => {
+        const i = toolsStack.lastIndexOf(t);
+        if (i >= 0)
+            toolsStack.splice(i, 1);
+        if (toolsStack.length === 0) {
+            active.clear();
+            slots.clear();
+            cameraHome = null;
+        }
+    };
+}
+export function isOperationOn(op, target) {
+    return active.has(keyOf(op, target));
+}
+export function applyOperation(def, target, params, self) {
+    const ctx = context(self);
+    if (!ctx)
+        return false;
+    const key = keyOf(def.value, target);
+    if (def.exclusive) {
+        const prevKey = slots.get(def.exclusive.group);
+        if (prevKey && prevKey !== key) {
+            const prev = active.get(prevKey);
+            active.delete(prevKey);
+            const prevDef = prev && getOperation(prev.op);
+            // `revert` puts the previous one back; `handover` leaves it to the new one.
+            if (prev && prevDef?.revert && def.exclusive.release === 'revert')
+                prevDef.revert(prev.target, prev.params, ctx);
+        }
+        slots.set(def.exclusive.group, key);
+    }
+    void def.apply(target, params, ctx);
+    if (def.revert)
+        active.set(key, { op: def.value, target, params });
+    return true;
+}
+export function revertOperation(def, target) {
+    const key = keyOf(def.value, target);
+    const entry = active.get(key);
+    const ctx = context();
+    if (!entry || !ctx || !def.revert)
+        return false;
+    active.delete(key);
+    if (def.exclusive && slots.get(def.exclusive.group) === key)
+        slots.delete(def.exclusive.group);
+    def.revert(target, entry.params, ctx);
+    return true;
+}
+/** The objects an effect acts on: 'self', object ids, narrowed to model nodes. */
+export function resolveEffectTargets(effect, self) {
+    const out = [];
+    for (const t of effect.targets ?? []) {
+        const root = t === 'self' ? self : findById(t);
+        if (!root)
+            continue;
+        const names = t === 'self' ? undefined : effect.meshNames?.[t];
+        if (names?.length) {
+            for (const name of names)
+                out.push(...findNodesByName(root, name).filter(n => n !== root));
+        }
+        else {
+            out.push(root);
+        }
+    }
+    return out;
+}
+/**
+ * Run one effect.
+ *   trigger  interactions: toggle when the operation toggles, else apply
+ *   apply / revert / toggle  explicit
+ */
+export function runEffect(effect, mode, self) {
+    const def = getOperation(effect.operation);
+    if (!def)
+        return;
+    const targets = resolveEffectTargets(effect, self);
+    const params = resolveParams(def, effect.params);
+    for (const target of def.multi ? targets : targets.slice(0, 1)) {
+        const on = isOperationOn(def.value, target);
+        const m = mode === 'trigger' ? (def.toggles ? 'toggle' : 'apply') : mode;
+        if (m === 'revert' || (m === 'toggle' && on))
+            revertOperation(def, target);
+        else if (m === 'apply' || m === 'toggle')
+            applyOperation(def, target, params, self);
+    }
+}
+// ---------------------------------------------------------------- actions
+const actionEffectsOn = new Set();
+const listeners = new Set();
+const notify = () => listeners.forEach(l => { try {
+    l();
+}
+catch { /* listener error */ } });
+/** Apply or undo an action's effects directly (the editor's "Try it"). */
+export function runActionEffects(action, mode) {
+    const on = actionEffectsOn.has(action.id);
+    if (mode === 'apply' && on)
+        return;
+    if (mode === 'revert' && !on)
+        return;
+    for (const effect of action.effects ?? [])
+        runEffect(effect, mode);
+    if (mode === 'apply')
+        actionEffectsOn.add(action.id);
+    else
+        actionEffectsOn.delete(action.id);
+    notify();
+}
+export const areActionEffectsOn = (actionId) => actionEffectsOn.has(actionId);
+/** Subscribe to action-effects on/off changes (studio badges). */
+export function subscribeActionEffects(fn) {
+    listeners.add(fn);
+    return () => { listeners.delete(fn); };
+}
+let unsubscribeActions = null;
+function ensureActionsSubscription() {
+    if (unsubscribeActions)
+        return;
+    unsubscribeActions = SceneActions.onEvent((e) => {
+        if (e.type === 'applied') {
+            if (e.runEffects)
+                runActionEffects(e.action, 'apply');
+        }
+        else if (e.type === 'reverted') {
+            runActionEffects(e.action, 'revert');
+        }
+        else if (e.type === 'reset') {
+            e.actions.forEach(a => runActionEffects(a, 'revert'));
+        }
+    });
+}

package/dist/operations/types.d.ts

@@ -0,0 +1,96 @@
+import type { Object3D } from 'three';
+import type { OperationName, OperationParamValue, Vector3Array } from '@3driseai/3drise-core';
+/** A parameter the studio shows under the effect, with its default. */
+export type OperationParamSpec = {
+    type: 'number';
+    label: string;
+    default: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+    hint?: string;
+} | {
+    type: 'color';
+    label: string;
+    default: string;
+    hint?: string;
+} | {
+    type: 'select';
+    label: string;
+    default: string;
+    options: Array<{
+        value: string;
+        label: string;
+    }>;
+    hint?: string;
+} | {
+    type: 'boolean';
+    label: string;
+    default: boolean;
+    hint?: string;
+};
+export type OperationParams = Record<string, OperationParamValue>;
+export type OperationSource = 'interaction' | 'action';
+/** Scene tools the runtime hands an operation (built from the viewer's hooks). */
+export interface OperationTools {
+    /** Animate the camera; `lookAt` moves the orbit target. */
+    animateCamera: (to: {
+        position?: Vector3Array;
+    }, duration: number, ease: string, lookAt?: Vector3Array) => Promise<void>;
+    /** Where the camera is and looks right now. */
+    cameraPose: () => {
+        position: Vector3Array;
+        target: Vector3Array;
+    } | null;
+    moveToFront: (object: Object3D, options: {
+        distance: number;
+        scale: [number, number];
+        duration: number;
+        ease: string;
+    }) => void;
+    restoreTransform: (object: Object3D, options: {
+        duration: number;
+        ease: string;
+    }) => void;
+}
+export interface OperationContext {
+    tools: OperationTools;
+    /** The object an interaction is on (interactions only). */
+    self?: Object3D | null;
+    /** Remember the camera pose once, before the first camera operation. */
+    saveCameraHome: () => void;
+    /** Fly back to the remembered pose and forget it. */
+    restoreCameraHome: (duration: number, ease: string) => void;
+}
+export interface OperationDefinition {
+    value: OperationName;
+    label: string;
+    /** One line for the studio (tooltip). */
+    description: string;
+    /** More than one target allowed. */
+    multi: boolean;
+    /** An interaction triggered again undoes it. */
+    toggles: boolean;
+    /** Where the operation can be used. */
+    usableIn: OperationSource[];
+    /** Only on gallery objects. */
+    galleryOnly?: boolean;
+    /**
+     * One target of this group is "on" at a time, scene-wide. Applying another:
+     * `revert` undoes the previous one first (bring to front), `handover` just
+     * takes over (camera moves — the remembered home pose stays).
+     */
+    exclusive?: {
+        group: string;
+        release: 'revert' | 'handover';
+    };
+    params?: Record<string, OperationParamSpec>;
+    apply: (target: Object3D, params: OperationParams, ctx: OperationContext) => void | Promise<void>;
+    /** No revert = one-way (applies only). */
+    revert?: (target: Object3D, params: OperationParams, ctx: OperationContext) => void;
+}
+/** Type helper for catalogue files. */
+export declare const defineOperation: (def: OperationDefinition) => OperationDefinition;
+export declare const DEFAULT_EASE = "power2.out";
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/operations/types.ts"],"names":[],"mappings":"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"}

package/dist/operations/types.js

@@ -0,0 +1,3 @@
+/** Type helper for catalogue files. */
+export const defineOperation = (def) => def;
+export const DEFAULT_EASE = 'power2.out';

package/dist/operations/useOperationsRuntime.d.ts

@@ -0,0 +1,3 @@
+import type { CameraState } from '@3driseai/3drise-core';
+export declare function useOperationsRuntime(cameraSettings: CameraState): void;
+//# sourceMappingURL=useOperationsRuntime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useOperationsRuntime.d.ts","sourceRoot":"","sources":["../../src/operations/useOperationsRuntime.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,uBAAuB,CAAC;AAQvE,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,WAAW,QAuB/D"}

package/dist/operations/useOperationsRuntime.js

@@ -0,0 +1,31 @@
+// Mounts the operations runtime on the scene: builds the scene tools from the
+// viewer's hooks and registers them. Called once, in ObjectsRenderer.
+import { useEffect, useRef } from 'react';
+import cameraManager from '../utils/CameraSingleton.js';
+import useCameraAnimation from '../hooks/useCameraAnimation.js';
+import { useFrameAnimations } from '../hooks/useFrameAnimations.js';
+import { useOrbitControls } from '../hooks/useOrbitControls.js';
+import { registerOperationTools } from './runtime.js';
+export function useOperationsRuntime(cameraSettings) {
+    const { animateCamera } = useCameraAnimation({ autoAnimate: false, defaultDuration: 1, defaultEase: 'power2.out' });
+    const { moveToFront, restoreOriginalTransform } = useFrameAnimations(cameraSettings);
+    const controls = useOrbitControls();
+    // Latest hook functions, read at call time (the registration itself is stable).
+    const latest = useRef({ animateCamera, moveToFront, restoreOriginalTransform, controls, cameraSettings });
+    latest.current = { animateCamera, moveToFront, restoreOriginalTransform, controls, cameraSettings };
+    useEffect(() => registerOperationTools({
+        animateCamera: (to, duration, ease, lookAt) => latest.current.animateCamera(to, duration, ease, lookAt),
+        cameraPose: () => {
+            const pos = cameraManager.getPosition();
+            if (!pos)
+                return null;
+            const t = latest.current.controls?.target;
+            const target = t
+                ? [t.x, t.y, t.z]
+                : latest.current.cameraSettings?.controls?.target ?? [0, 0, 0];
+            return { position: [pos.x, pos.y, pos.z], target };
+        },
+        moveToFront: (object, o) => latest.current.moveToFront(object, o),
+        restoreTransform: (object, o) => latest.current.restoreOriginalTransform(object, o),
+    }), []);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3driseai/3drise-viewer",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -39,6 +39,6 @@
   },
   "dependencies": {
     "@3driseai/3drise-common": "^1.0.1",
-    "@3driseai/3drise-core": "^1.0.18"
+    "@3driseai/3drise-core": "^1.0.19"
   }
 }