@3driseai/3drise-viewer 0.1.24 → 0.1.26

package/dist/hooks/useInteraction.js

@@ -1,248 +1,102 @@
 /**
- * useInteraction.ts
+ * useInteraction — runs an object's interactions.
  *
- * Hook for handling Interactions on scene objects.
- * Provides executeInteraction function and utility functions for:
- * - Resolving target objects
- * - Executing operations
- * - Triggering animations
+ * An interaction (core `Interaction`) is a trigger plus three kinds of reaction,
+ * run in this order:
+ *
+ *   effects     operations on their targets, through the shared operations runtime
+ *               (../operations) — a triggered interaction toggles an operation that
+ *               can be undone, and applies one that can't. 'self' = the object the
+ *               interaction is on.
+ *   animations  play / pause / stop / toggle a clip or a sequence (ClipsRuntime).
+ *               play starts from the beginning, or resumes if paused; toggle plays
+ *               forward, then back — "back" is the opposite of a sequence's own
+ *               reverse.
+ *   actions     apply / revert / toggle an action (SceneActions; its own effects
+ *               run through the same runtime).
  */
-import { useCallback, useRef } from 'react';
-import { AnimationsManager, texturesManager } from '@3driseai/3drise-core';
-import useCameraAnimation from '../hooks/useCameraAnimation.js';
-import { useFrameAnimations } from '../hooks/useFrameAnimations.js';
-import { useObjectEffects } from '../hooks/useObjectEffects.js';
-import { findById } from '../utils/sceneQuery.js';
-// =============================================================================
-// TYPES
-// =============================================================================
-// =============================================================================
-// HOOK
-// =============================================================================
-export function useInteraction({ 
-// mode = 'default',
-cameraSettings, sequences, }) {
-    // Redux state
-    // Track currently animated object for toggle behavior
-    const currentAnimatedRef = useRef(null);
-    // Hooks
-    const { animateCamera } = useCameraAnimation({
-        autoAnimate: false,
-        defaultDuration: 1,
-        defaultEase: "power2.out"
-    });
-    const { moveToFront, zoomToFrame, restoreOriginalTransform, restoreCamera } = useFrameAnimations(cameraSettings);
-    const { vanishObject, restoreVanishedObject, animateGlowEffect, removeGlow, isVanished, isGlowing, glowingObjects, vanishedObjects, } = useObjectEffects();
-    // ===========================================================================
-    // UTILITY: Resolve Target Objects
-    // ===========================================================================
-    const resolveTargets = useCallback((interaction, currentRef) => {
-        const { targetIds, targetMode } = interaction;
-        // If no targetIds specified, return current object only
-        if (!targetIds || targetIds.length === 0) {
-            return [currentRef];
-        }
-        const targetRefs = [];
-        // Add current object if mode is 'add'
-        if (targetMode === 'add') {
-            targetRefs.push(currentRef);
-        }
-        // Lookup targets from scene
-        targetIds.forEach(id => {
-            const obj = findById(id);
-            if (obj) {
-                targetRefs.push(obj);
-            }
-        });
-        return targetRefs.length > 0 ? targetRefs : [currentRef];
+import { useCallback, useMemo, useRef } from 'react';
+import { SceneActions } from '@3driseai/3drise-core';
+import ClipsRuntime from '../animationsV2/ClipsRuntime.js';
+import { clipMap } from '../animationsV2/sequenceUtils.js';
+import { runEffect } from '../operations/runtime.js';
+import { useOperationsRuntime } from '../operations/useOperationsRuntime.js';
+export function useInteraction({ cameraSettings, sequences = [], clips = [], actionSequences = [], }) {
+    // The scene's operation tools (camera, bring-to-front…) for the shared runtime.
+    useOperationsRuntime(cameraSettings);
+    // Toggle state: animation ids whose last toggle went "forward".
+    const toggledRef = useRef(new Set());
+    const clipsById = useMemo(() => clipMap(clips), [clips]);
+    /** First trigger → forward (false), next → back (true), … per key. */
+    const nextIsBack = useCallback((key) => {
+        const toggled = toggledRef.current;
+        const back = toggled.has(key);
+        if (back)
+            toggled.delete(key);
+        else
+            toggled.add(key);
+        return back;
     }, []);
-    // ===========================================================================
-    // UTILITY: Trigger Animations
-    // ===========================================================================
-    const triggerAnimations = useCallback((animationIds) => {
-        if (!animationIds || animationIds.length === 0)
+    // ---------------------------------------------------------------- run
+    const executeInteraction = useCallback((params) => {
+        const { interaction, ref } = params;
+        if (!interaction?.enabled)
             return;
-        animationIds.forEach(animationId => {
-            const sequence = sequences.find(s => s.id === animationId);
-            if (sequence) {
-                AnimationsManager.playSequence(sequence);
+        // 1. Effects — each on its own targets.
+        for (const effect of interaction.effects ?? [])
+            runEffect(effect, 'trigger', ref);
+        // 2. Animations.
+        for (const a of interaction.animations ?? []) {
+            if (a.kind === 'clip') {
+                const clip = clipsById.get(a.ref);
+                if (!clip)
+                    continue;
+                if (a.command === 'pause')
+                    ClipsRuntime.pause(clip.id);
+                else if (a.command === 'stop')
+                    ClipsRuntime.stop(clip.id);
+                else if (a.command === 'toggle')
+                    ClipsRuntime.play(clip, { reverse: nextIsBack(`clip:${clip.id}`) });
+                else if (ClipsRuntime.isActive(clip.id) && !ClipsRuntime.isPlaying(clip.id) && ClipsRuntime.getTime(clip.id) < clip.duration)
+                    ClipsRuntime.resume(clip.id);
+                else
+                    ClipsRuntime.play(clip, { from: 0 });
             }
-        });
-    }, [sequences]);
-    // ===========================================================================
-    // UTILITY: Execute Single Operation
-    // ===========================================================================
-    const executeOperation = useCallback(async (operation, ref, createdObject, textureUrl) => {
-        if (!operation || operation === 'none')
-            return;
-        const defaultDuration = 1.0;
-        const defaultEase = "power2.out";
-        const defaultDistance = 2.0;
-        const isCurrentlySelected = currentAnimatedRef.current !== null;
-        const isSameObject = currentAnimatedRef.current?.uuid === ref.uuid;
-        switch (operation) {
-            case 'vanish': {
-                if (isVanished(ref.uuid)) {
-                    restoreVanishedObject(ref, defaultDuration, defaultEase);
+            else {
+                const seq = sequences.find(s => s.id === a.ref);
+                if (!seq)
+                    continue;
+                if (a.command === 'pause')
+                    ClipsRuntime.pauseSequence(seq.id);
+                else if (a.command === 'stop')
+                    ClipsRuntime.stopSequence(seq.id);
+                else if (a.command === 'toggle') {
+                    const back = nextIsBack(`seq:${seq.id}`);
+                    ClipsRuntime.playSequence(seq, clipsById, { reverse: back ? !seq.reverse : seq.reverse });
                 }
-                else {
-                    vanishObject(ref, defaultDuration, defaultEase);
-                }
-                break;
-            }
-            case 'glow': {
-                if (isGlowing(ref.uuid)) {
-                    removeGlow(ref);
+                else if (ClipsRuntime.isSequenceActive(seq.id) && !ClipsRuntime.isSequencePlaying(seq.id) && ClipsRuntime.getSequenceProgress(seq.id) < 1) {
+                    ClipsRuntime.resumeSequence(seq.id);
                 }
                 else {
-                    animateGlowEffect(ref);
-                }
-                break;
-            }
-            case 'focus': {
-                animateCamera({}, defaultDuration, defaultEase, createdObject.meshSettings.position);
-                break;
-            }
-            case 'moveToFront': {
-                // Toggle: if clicking the same object, restore it
-                if (isCurrentlySelected && isSameObject) {
-                    restoreOriginalTransform(currentAnimatedRef.current, {
-                        duration: defaultDuration,
-                        ease: defaultEase
-                    });
-                    currentAnimatedRef.current = null;
-                    return;
-                }
-                // Restore previous object if different
-                if (isCurrentlySelected && !isSameObject) {
-                    restoreOriginalTransform(currentAnimatedRef.current, {
-                        duration: defaultDuration,
-                        ease: defaultEase
-                    });
-                }
-                // Apply new animation
-                moveToFront(ref, {
-                    distance: defaultDistance,
-                    scale: [6, 4],
-                    duration: defaultDuration,
-                    ease: defaultEase
-                });
-                currentAnimatedRef.current = ref;
-                break;
-            }
-            case 'zoom': {
-                // Toggle: if clicking the same object, restore camera
-                if (isCurrentlySelected && isSameObject) {
-                    restoreCamera({ duration: defaultDuration, ease: defaultEase });
-                    currentAnimatedRef.current = null;
-                    return;
-                }
-                // Restore previous camera if different object
-                if (isCurrentlySelected && !isSameObject) {
-                    restoreCamera({ duration: defaultDuration, ease: defaultEase });
+                    // From the start edge of its own direction.
+                    const total = ClipsRuntime.getSequenceDuration(seq.id);
+                    ClipsRuntime.playSequence(seq, clipsById, { from: seq.reverse && total > 0 ? total : 0 });
                 }
-                // Apply new zoom
-                zoomToFrame(ref, {
-                    distance: defaultDistance,
-                    duration: defaultDuration,
-                    ease: defaultEase
-                });
-                currentAnimatedRef.current = ref;
-                break;
             }
-            case 'playAnimation':
-                // Handled by triggerAnimations
-                break;
-            case 'displayImage': {
-                if (!textureUrl)
-                    break;
-                let applier;
-                let meshWithMap = null;
-                ref.traverse((child) => {
-                    if (!applier && typeof child.userData?.applyTexture === 'function') {
-                        applier = child.userData.applyTexture;
-                    }
-                    else if (!meshWithMap && child.material) {
-                        meshWithMap = child;
-                    }
-                });
-                if (applier) {
-                    applier(textureUrl);
-                }
-                else if (meshWithMap) {
-                    const name = textureUrl.split('/').pop()?.split('.')[0] || `texture-${Date.now()}`;
-                    try {
-                        const loaded = await texturesManager.loadTexture(name, textureUrl, 'images');
-                        const mat = meshWithMap.material;
-                        mat.map = loaded;
-                        mat.needsUpdate = true;
-                    }
-                    catch (err) {
-                    }
-                }
-                break;
-            }
-            case 'create':
-            case 'update':
-            case 'delete':
-            case 'toggle':
-            case 'loadProject':
-                break;
         }
-    }, [
-        isVanished,
-        isGlowing,
-        vanishObject,
-        restoreVanishedObject,
-        animateGlowEffect,
-        removeGlow,
-        animateCamera,
-        moveToFront,
-        zoomToFrame,
-        restoreOriginalTransform,
-        restoreCamera,
-    ]);
-    // ===========================================================================
-    // UTILITY: Execute Multiple Operations
-    // ===========================================================================
-    const executeOperations = useCallback((operations, ref, createdObject, textureUrl) => {
-        if (!operations || operations.length === 0)
-            return;
-        operations.forEach(operation => {
-            executeOperation(operation, ref, createdObject, textureUrl);
-        });
-    }, [executeOperation]);
-    // ===========================================================================
-    // MAIN: Execute Interaction
-    // ===========================================================================
-    const executeInteraction = useCallback((params) => {
-        const { interaction, ref, createdObject } = params;
-        if (!interaction.enabled)
-            return;
-        let textureUrl = undefined;
-        if (interaction.operations?.includes('displayImage')) {
-            textureUrl = ref.userData?.url;
+        // 3. Actions.
+        for (const a of interaction.actions ?? []) {
+            const action = actionSequences.find(x => x.id === a.ref);
+            if (!action)
+                continue;
+            if (a.command === 'revert')
+                SceneActions.revertAction(action);
+            else if (a.command === 'toggle')
+                SceneActions.toggleAction(action);
+            else
+                SceneActions.applyAction(action);
         }
-        // 1. Resolve target objects
-        const targets = resolveTargets(interaction, ref);
-        // 2. Execute operations on each target
-        targets.forEach(targetRef => {
-            // Find the createdObject for this target (if different from original)
-            // For now, use the original createdObject for position data
-            executeOperations(interaction.operations, targetRef, createdObject, textureUrl);
-        });
-        // 3. Trigger animations
-        triggerAnimations(interaction.animationIds);
-    }, [resolveTargets, executeOperations, triggerAnimations]);
-    // ===========================================================================
-    // RETURN
-    // ===========================================================================
-    return {
-        executeInteraction,
-        // Expose refs for context to share
-        currentAnimatedRef,
-        glowingObjects,
-        vanishedObjects,
-    };
+    }, [clipsById, sequences, actionSequences, nextIsBack]);
+    return { executeInteraction };
 }
 export default useInteraction;

package/dist/hooks/useLightConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useLightConfig.d.ts","sourceRoot":"","sources":["../../src/hooks/useLightConfig.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEzD,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAS/E;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CA6B7E;AAED,MAAM,WAAW,oBAAoB;IACjC,kFAAkF;IAClF,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,gEAAgE;IAChE,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CACrE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC1B,OAAO,EAAE,SAAS,CAAC,QAAQ,GAAG,IAAI,CAAC,EACnC,QAAQ,EAAE,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC,EACjC,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,EAAE,gBAAgB,EAAE,GAAG,SAAS,EAC1C,SAAS,CAAC,EAAE,eAAe,GAC5B,oBAAoB,CA2DtB;AAED,eAAe,cAAc,CAAC"}
+{"version":3,"file":"useLightConfig.d.ts","sourceRoot":"","sources":["../../src/hooks/useLightConfig.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEzD,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAU/E;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CA6B7E;AAED,MAAM,WAAW,oBAAoB;IACjC,kFAAkF;IAClF,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,gEAAgE;IAChE,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CACrE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC1B,OAAO,EAAE,SAAS,CAAC,QAAQ,GAAG,IAAI,CAAC,EACnC,QAAQ,EAAE,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC,EACjC,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,EAAE,gBAAgB,EAAE,GAAG,SAAS,EAC1C,SAAS,CAAC,EAAE,eAAe,GAC5B,oBAAoB,CAiEtB;AAED,eAAe,cAAc,CAAC"}

package/dist/hooks/useLightConfig.js

@@ -26,6 +26,7 @@ import { DEFAULT_LIGHTS, getGenerativeAnimatable } from '@3driseai/3drise-core';
 import { useFrame } from '@react-three/fiber';
 import { applyConfigKeyframeAnimations, applyConfigMouseMove } from '../utils/configAnimations.js';
 import { useLightLive } from './useLightLive.js';
+import { useLightTargets } from './useLightTargets.js';
 import { kelvinToColor } from '../components/lightBulb/kelvin.js';
 const tmpColor = new Color();
 /**
@@ -84,6 +85,12 @@ export function useLightConfig(rootRef, lightRef, id, config, animations, mouseM
         return merged;
     }, [config]);
     const live = useLightLive(rootRef, lightRef, id, base);
+    // Objects this light drives (a shade, a diffuser, a cover). Its own useFrame,
+    // so it is unaffected by the early-out below, and it reads the light one
+    // frame behind the component that sets it — invisible, and cheaper than
+    // fighting R3F's frame ordering, where a non-zero priority would take the
+    // render loop over.
+    useLightTargets(lightRef, base.targetIds, base.targetMeshes, base.intensity ?? 1);
     const merged = useRef(base);
     const animOverride = useRef({});
     const animFrom = useRef({});

package/dist/hooks/useLightLive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useLightLive.d.ts","sourceRoot":"","sources":["../../src/hooks/useLightLive.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvD,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAa7C,CAAC;AAKF,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAyB1H;AAED;;;GAGG;AACH,wBAAgB,YAAY,CACxB,OAAO,EAAE,SAAS,CAAC,QAAQ,GAAG,IAAI,CAAC,EACnC,QAAQ,EAAE,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC,EACjC,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAMnD;AAED,eAAe,YAAY,CAAC"}
+{"version":3,"file":"useLightLive.d.ts","sourceRoot":"","sources":["../../src/hooks/useLightLive.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvD,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAe7C,CAAC;AAKF,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAyB1H;AAED;;;GAGG;AACH,wBAAgB,YAAY,CACxB,OAAO,EAAE,SAAS,CAAC,QAAQ,GAAG,IAAI,CAAC,EACnC,QAAQ,EAAE,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC,EACjC,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAMnD;AAED,eAAe,YAAY,CAAC"}

package/dist/hooks/useLightLive.js

@@ -2,6 +2,8 @@ import { useConfigLiveHandle } from './useConfigLive.js';
 import { kelvinToColor } from '../components/lightBulb/kelvin.js';
 export const LIGHT_STRUCTURAL = [
     'shape', 'glass', 'glassTint', 'colorMode', 'on', 'targetPosition',
+    // Which objects the light drives: a selection, never a drag.
+    'targetIds', 'targetMeshes',
     // spotBeam: the gobo is redrawn and the beam/emitter geometry is rebuilt.
     'pattern', 'patternSoftness', 'patternRotation', 'beamMode', 'emitter',
     // ledArray: the die layout is rebuilt. fluorescentTube: the tube geometry is.

package/dist/hooks/useLightTargets.d.ts

@@ -0,0 +1,7 @@
+import type { Light } from 'three';
+import type { RefObject } from 'react';
+export declare function useLightTargets(lightRef: RefObject<Light | null>, targetIds: string[] | undefined, targetMeshes: Record<string, string[]> | undefined, 
+/** The light's committed intensity — what "full output" means for it. */
+baseIntensity: number): void;
+export default useLightTargets;
+//# sourceMappingURL=useLightTargets.d.ts.map

package/dist/hooks/useLightTargets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLightTargets.d.ts","sourceRoot":"","sources":["../../src/hooks/useLightTargets.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAS,KAAK,EAA4B,MAAM,OAAO,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAmBvC,wBAAgB,eAAe,CAC3B,QAAQ,EAAE,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC,EACjC,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,EAC/B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS;AAClD,yEAAyE;AACzE,aAAa,EAAE,MAAM,GACtB,IAAI,CA0FN;AAED,eAAe,eAAe,CAAC"}

package/dist/hooks/useLightTargets.js

@@ -0,0 +1,132 @@
+// =============================================================================
+// useLightTargets — a light pushes its live state onto objects it does not own
+// =============================================================================
+//
+// `config.targetIds` names scene objects ('mesh' / 'model') that a light drives:
+// a lampshade round a bulb, a diffuser over an LED panel, a glass cover. The
+// light never moves or owns them — it only writes their emissive, so they glow
+// with it. Because the value read is the light's LIVE intensity rather than its
+// config, everything the light does comes along for nothing: the bulb's tungsten
+// warm-up, the candle's flicker, the fluorescent's starter stutter, keyframes,
+// pointer bindings.
+//
+// Three decisions worth knowing:
+//
+//   - The driven object's own `emissiveIntensity` is the strength. There is no
+//     new knob: every mesh already has that control, per object, in the material
+//     panel.
+//
+//   - Lights ACCUMULATE. The first light to touch a material in a frame clears
+//     it, every light after adds. Two bulbs in one pendant sum correctly, and
+//     there is no question of which one wins.
+//
+//   - Each driven mesh gets a CLONE of its material. The 3drise material system
+//     hands out shared instances from MaterialLibrary, so writing emissive on
+//     the original would light every other mesh using that material too. The
+//     clone is re-made whenever the material system swaps the source out, so
+//     editing a material still reaches a driven object (one frame later).
+//
+// Resolution is a runtime lookup inside useFrame — the use `findById` is for —
+// never at render time. See the object-resolution rule.
+//
+import { useEffect, useRef } from 'react';
+import { useFrame } from '@react-three/fiber';
+import { findById } from '../utils/sceneQuery.js';
+const hasEmissive = (m) => !!m && 'emissive' in m && !!m.emissive;
+/** A light contributing more than a few times its own configured output is a
+ *  keyframe overshooting, not a design intent — clamp so a shade cannot blow out. */
+const MAX_OUTPUT = 4;
+export function useLightTargets(lightRef, targetIds, targetMeshes, 
+/** The light's committed intensity — what "full output" means for it. */
+baseIntensity) {
+    const driven = useRef([]);
+    const key = useRef('');
+    /** Hand every material back and drop our clones. */
+    const release = () => {
+        for (const d of driven.current) {
+            if (d.mesh.material === d.clone)
+                d.mesh.material = d.source;
+            d.clone.dispose();
+        }
+        driven.current = [];
+    };
+    useEffect(() => release, []);
+    useFrame((state) => {
+        const light = lightRef.current;
+        const ids = targetIds ?? [];
+        // --- resolve, and only when the selection actually changed -----------
+        const wanted = ids.join(',') + '|' + JSON.stringify(targetMeshes ?? {});
+        const stale = driven.current.some((d) => !d.mesh.parent);
+        if (wanted !== key.current || stale) {
+            release();
+            key.current = wanted;
+            for (const id of ids) {
+                const root = findById(id);
+                if (!root) {
+                    // Not mounted yet, or deleted. Re-resolved next frame because
+                    // the key is only committed once everything is found.
+                    key.current = '';
+                    continue;
+                }
+                const names = targetMeshes?.[id];
+                root.traverse((o) => {
+                    const mesh = o;
+                    if (!mesh.isMesh)
+                        return;
+                    // A model target can be narrowed to named meshes inside it;
+                    // no list means the whole model.
+                    if (names && names.length && !names.includes(mesh.name))
+                        return;
+                    const source = mesh.material;
+                    if (Array.isArray(mesh.material) || !hasEmissive(source))
+                        return;
+                    const clone = source.clone();
+                    clone.userData = { ...clone.userData, __litClone: true };
+                    mesh.material = clone;
+                    driven.current.push({ mesh, source, clone });
+                });
+            }
+        }
+        if (!driven.current.length)
+            return;
+        // --- the material system may have swapped a source out from under us --
+        for (const d of driven.current) {
+            if (d.mesh.material !== d.clone && !d.mesh.material?.userData?.__litClone) {
+                const next = d.mesh.material;
+                if (hasEmissive(next)) {
+                    d.clone.dispose();
+                    d.source = next;
+                    d.clone = next.clone();
+                    d.clone.userData = { ...d.clone.userData, __litClone: true };
+                    d.mesh.material = d.clone;
+                }
+            }
+        }
+        // --- accumulate -------------------------------------------------------
+        // One key per frame: whoever gets there first clears, the rest add. If a
+        // renderer ever hands two lights different clock values in one frame the
+        // worst case is last-writer-wins, which is where this started.
+        const frame = state.clock.elapsedTime;
+        const output = light
+            ? Math.min(Math.max(light.intensity / Math.max(baseIntensity, 1e-6), 0), MAX_OUTPUT)
+            : 0;
+        for (const d of driven.current) {
+            const m = d.clone;
+            if (!m.emissive)
+                continue;
+            if (m.userData.__litFrame !== frame) {
+                m.userData.__litFrame = frame;
+                m.emissive.setRGB(0, 0, 0);
+                // The object's own value is the strength; the colour is what the
+                // lights sum into.
+                m.emissiveIntensity = d.source.emissiveIntensity ?? 1;
+            }
+            if (light && output > 0) {
+                m.emissive.r += light.color.r * output;
+                m.emissive.g += light.color.g * output;
+                m.emissive.b += light.color.b * output;
+            }
+        }
+    });
+}
+export default useLightTargets;

package/dist/hooks/useObjectAnimation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useObjectAnimation.d.ts","sourceRoot":"","sources":["../../src/hooks/useObjectAnimation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEnE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAEzE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAE3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,UAAU,yBAAyB;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,UAAU,wBAAyB,SAAQ,0BAA0B,EAAE,2BAA2B;CACjG;AAGD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAAI,gBAAgB,qBAAqB,GAAG,IAAI,EAAE,iBAAiB,OAAO,EAAE,UAAS,yBAA8B,EAAE,SAAS,cAAc,KAAG,wBAAwB,GAAG,IAexM,CAAC"}
+{"version":3,"file":"useObjectAnimation.d.ts","sourceRoot":"","sources":["../../src/hooks/useObjectAnimation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEnE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAEzE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,UAAU,yBAAyB;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,UAAU,wBAAyB,SAAQ,0BAA0B,EAAE,2BAA2B;CACjG;AAGD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAAI,gBAAgB,qBAAqB,GAAG,IAAI,EAAE,iBAAiB,OAAO,EAAE,UAAS,yBAA8B,EAAE,SAAS,cAAc,KAAG,wBAAwB,GAAG,IAcxM,CAAC"}

package/dist/hooks/useObjectAnimation.js

@@ -3,7 +3,6 @@ import { useFrame } from '@react-three/fiber';
 import { findById } from '@3driseai/3drise-core';
 import { useContinuousEffects } from "./useContinuousEffects.js";
 import { useMouseMove } from "./useInteractionEffects.js";
-import { useSequenceAnimation } from "./useSequenceAnimation.js";
 /**
  * Drive every continuous animation for one scene object.
  *
@@ -28,6 +27,5 @@ export const useObjectAnimation = (objectSettings, animateMaterial, options = {}
     const source = object ?? fallbackRef;
     const continuousResult = useContinuousEffects(objectSettings, { enabled, animateMaterial, hovered }, source);
     const mouseMoveResult = useMouseMove(objectSettings, { enabled, animateMaterial }, source);
-    useSequenceAnimation(objectSettings?.id, source);
     return { ...continuousResult, ...mouseMoveResult };
 };

package/dist/hooks/useOceanMaterial.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOceanMaterial.d.ts","sourceRoot":"","sources":["../../src/hooks/useOceanMaterial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAIvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAI7E,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE7E;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,uBAAuB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;gFAE4E;IAC5E,OAAO,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;CACtF;AAED,MAAM,WAAW,mBAAmB;IAChC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B;0DACsD;IACtD,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;CAChD;AAED,wBAAgB,gBAAgB,CAAC,EAC7B,EAAE,EACF,MAAM,EACN,OAAO,EACP,WAAW,EACX,YAAY,EACZ,YAAgB,EAChB,OAAO,GACV,EAAE,uBAAuB,GAAG,mBAAmB,CAuE/C;AAED,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"useOceanMaterial.d.ts","sourceRoot":"","sources":["../../src/hooks/useOceanMaterial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAI7E,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE7E;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,uBAAuB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;gFAE4E;IAC5E,OAAO,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;CACtF;AAED,MAAM,WAAW,mBAAmB;IAChC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B;0DACsD;IACtD,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;CAChD;AAED,wBAAgB,gBAAgB,CAAC,EAC7B,EAAE,EACF,MAAM,EACN,OAAO,EACP,WAAW,EACX,YAAY,EACZ,YAAgB,EAChB,OAAO,GACV,EAAE,uBAAuB,GAAG,mBAAmB,CAkE/C;AAED,eAAe,gBAAgB,CAAC"}

package/dist/hooks/useOceanMaterial.js

@@ -1,7 +1,6 @@
 import { useEffect, useMemo, useRef } from 'react';
 import { useFrame } from '@react-three/fiber';
 import { useCloudSun } from './useCloudSun.js';
-import { useLiveTransitionEvents } from './useLiveTransitionEvents.js';
 import { OCEAN_LIVE_KEY } from './useOceanLive.js';
 import { OceanSurfaceMaterial } from '../shaders/ocean/OceanSurfaceMaterial.js';
 import { applySunUniforms } from '../utils/cloudUniforms.js';
@@ -36,10 +35,6 @@ export function useOceanMaterial({ id, config, quality, skySettings, timeSetting
         root.userData[OCEAN_LIVE_KEY] = liveHandle;
         return () => { delete root.userData[OCEAN_LIVE_KEY]; };
     }, [id, liveHandle]);
-    // Sequence-authored transitions (`transition.state === 'ocean'`) — shared by
-    // both hosts (OceanSurface, WaterBody), the same way the material and the
-    // live handle already are.
-    useLiveTransitionEvents('ocean', liveConfig, config, rootRef);
     useFrame((state) => {
         const shader = material;
         updateSun();

package/dist/hooks/useRuntimeSettings.d.ts

@@ -0,0 +1,15 @@
+/**
+ * An element's settings with any applied action patches laid over them.
+ *
+ * `state` is the element's action address: its object id, or 'camera' | 'sky' |
+ * 'ocean' | 'clouds' | 'terrain'. Subscribes to that one element only, so applying an action
+ * re-renders the elements it touches and nothing else. With no patch applied this
+ * returns `base` itself — no copy, no identity change.
+ *
+ * Call it where authored settings enter the renderer (ObjectNode, CameraController,
+ * EnvironmentManager, the editor's environment connectors), never deeper: everything
+ * downstream should see one consistent, patched settings object.
+ */
+export declare function useRuntimeSettings<T>(state: string | undefined | null, base: T): T;
+export default useRuntimeSettings;
+//# sourceMappingURL=useRuntimeSettings.d.ts.map

package/dist/hooks/useRuntimeSettings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRuntimeSettings.d.ts","sourceRoot":"","sources":["../../src/hooks/useRuntimeSettings.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAQlF;AAED,eAAe,kBAAkB,CAAC"}

package/dist/hooks/useRuntimeSettings.js

@@ -0,0 +1,22 @@
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
+import { SceneActions, applySettingsPatch } from '@3driseai/3drise-core';
+const noopUnsubscribe = () => { };
+/**
+ * An element's settings with any applied action patches laid over them.
+ *
+ * `state` is the element's action address: its object id, or 'camera' | 'sky' |
+ * 'ocean' | 'clouds' | 'terrain'. Subscribes to that one element only, so applying an action
+ * re-renders the elements it touches and nothing else. With no patch applied this
+ * returns `base` itself — no copy, no identity change.
+ *
+ * Call it where authored settings enter the renderer (ObjectNode, CameraController,
+ * EnvironmentManager, the editor's environment connectors), never deeper: everything
+ * downstream should see one consistent, patched settings object.
+ */
+export function useRuntimeSettings(state, base) {
+    const subscribe = useCallback((listener) => (state ? SceneActions.subscribe(state, listener) : noopUnsubscribe), [state]);
+    const getSnapshot = useCallback(() => SceneActions.getPatch(state), [state]);
+    const patch = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    return useMemo(() => (patch && base ? applySettingsPatch(base, patch) : base), [base, patch]);
+}
+export default useRuntimeSettings;

package/dist/hooks/useSequenceAnimation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useSequenceAnimation.d.ts","sourceRoot":"","sources":["../../src/hooks/useSequenceAnimation.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAqB/D;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAAI,UAAU,MAAM,GAAG,SAAS,EAAE,eAAe,cAAc,KAAG,IA6JlG,CAAC;AACF,eAAe,oBAAoB,CAAC"}
+{"version":3,"file":"useSequenceAnimation.d.ts","sourceRoot":"","sources":["../../src/hooks/useSequenceAnimation.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAgC/D;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAAI,UAAU,MAAM,GAAG,SAAS,EAAE,eAAe,cAAc,KAAG,IAoKlG,CAAC;AACF,eAAe,oBAAoB,CAAC"}