@3driseai/3drise-viewer 0.1.24 → 0.1.25

package/dist/api/sceneHandle.d.ts

@@ -0,0 +1,63 @@
+import type { ActionSequence, AnimationSequence } from '@3driseai/3drise-core';
+export interface SceneActionInfo {
+    id: string;
+    key?: string;
+    name: string;
+    description?: string;
+    applied: boolean;
+}
+export interface SceneAnimationInfo {
+    id: string;
+    name: string;
+    description?: string;
+    /** Seconds, one forward pass: Σ(delay + duration) over steps */
+    duration: number;
+    loop: boolean;
+    yoyo: boolean;
+    playing: boolean;
+}
+export interface ScenePlayOptions {
+    speed?: number;
+    reverse?: boolean;
+}
+export type SceneHandleEventType = 'actionApplied' | 'actionReverted' | 'animationStart' | 'animationEnd';
+export interface SceneHandleEvent {
+    type: SceneHandleEventType;
+    id: string;
+    key?: string;
+    name: string;
+}
+export interface SceneHandle {
+    actions: {
+        list(): SceneActionInfo[];
+        apply(ref: string): boolean;
+        revert(ref: string): boolean;
+        /** Returns true when it applied, false when it reverted (or the action was not found). */
+        toggle(ref: string): boolean;
+        isApplied(ref: string): boolean;
+        /** Revert every applied action of this project — back to the authored scene. */
+        reset(): void;
+    };
+    animations: {
+        list(): SceneAnimationInfo[];
+        play(ref: string, options?: ScenePlayOptions): boolean;
+        pause(ref: string): boolean;
+        resume(ref: string): boolean;
+        stop(ref: string): boolean;
+        /** Jump to a point in the animation, 0–1. */
+        seek(ref: string, progress: number): boolean;
+        isPlaying(ref: string): boolean;
+    };
+    /** Subscribe to this project's action / animation events. Returns the unsubscribe. */
+    on(type: SceneHandleEventType, listener: (event: SceneHandleEvent) => void): () => void;
+}
+export interface SceneHandleSource {
+    actions: ActionSequence[];
+    animations: AnimationSequence[];
+}
+/**
+ * Build a handle over one project's actions and animations. `getSource` is read on
+ * every call, so the handle stays valid if the project data is replaced.
+ */
+export declare function createSceneHandle(getSource: () => SceneHandleSource): SceneHandle;
+//# sourceMappingURL=sceneHandle.d.ts.map

package/dist/api/sceneHandle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sceneHandle.d.ts","sourceRoot":"","sources":["../../src/api/sceneHandle.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,cAAc,EAAkB,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/F,MAAM,WAAW,eAAe;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,cAAc,CAAC;AAE1G,MAAM,WAAW,gBAAgB;IAC7B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE;QACL,IAAI,IAAI,eAAe,EAAE,CAAC;QAC1B,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAC5B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAC7B,0FAA0F;QAC1F,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAC7B,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAChC,gFAAgF;QAChF,KAAK,IAAI,IAAI,CAAC;KACjB,CAAC;IACF,UAAU,EAAE;QACR,IAAI,IAAI,kBAAkB,EAAE,CAAC;QAC7B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC;QACvD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAC5B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAC7B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAC3B,6CAA6C;QAC7C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAC7C,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACnC,CAAC;IACF,sFAAsF;IACtF,EAAE,CAAC,IAAI,EAAE,oBAAoB,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC3F;AAED,MAAM,WAAW,iBAAiB;IAC9B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,UAAU,EAAE,iBAAiB,EAAE,CAAC;CACnC;AA0BD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,iBAAiB,GAAG,WAAW,CAuGjF"}

package/dist/api/sceneHandle.js

@@ -0,0 +1,160 @@
+// =============================================================================
+// SceneHandle — control a loaded 3drise project from outside it
+// =============================================================================
+//
+// What a developer extending a project gets from <ProjectLoader ref={…} /> or
+// onSceneReady(handle): trigger the project's actions and animations from their
+// own UI, and hear when they run.
+//
+//   scene.current?.actions.toggle('open-door');
+//   scene.current?.animations.play('intro', { speed: 1.5 });
+//   const off = scene.current?.on('actionApplied', (e) => console.log(e.key));
+//
+// Addressing (`ref`): an action's `key` first (stable across renames and project
+// copies — prefer it), then its id, then its exact name. Animations have no key
+// yet, so id, then name. An ambiguous name warns and uses the first match.
+//
+// This is a thin layer: object clicks go through the same SceneActions /
+// AnimationsManager calls, so a button and a click behave identically.
+//
+import { AnimationsManager, SceneActions } from '@3driseai/3drise-core';
+function resolve(items, ref, kind) {
+    if (!ref)
+        return undefined;
+    const byKey = items.find(i => i.key === ref);
+    if (byKey)
+        return byKey;
+    const byId = items.find(i => i.id === ref);
+    if (byId)
+        return byId;
+    const byName = items.filter(i => i.name === ref);
+    if (byName.length > 1) {
+        console.warn(`[3drise] ${byName.length} ${kind}s are named "${ref}"; using the first.${kind === 'action' ? ' Address it by its key instead.' : ''}`);
+    }
+    if (byName.length === 0) {
+        console.warn(`[3drise] No ${kind} "${ref}" in this project. Known: ${items.map(i => i.key ?? i.name).join(', ') || 'none'}`);
+    }
+    return byName[0];
+}
+function animationDuration(seq) {
+    return (seq.steps ?? []).reduce((sum, s) => sum + (s.delay || 0) + (s.duration || 0), 0);
+}
+/**
+ * Build a handle over one project's actions and animations. `getSource` is read on
+ * every call, so the handle stays valid if the project data is replaced.
+ */
+export function createSceneHandle(getSource) {
+    const actions = () => getSource().actions ?? [];
+    const animations = () => getSource().animations ?? [];
+    const findAction = (ref) => resolve(actions(), ref, 'action');
+    const findAnimation = (ref) => resolve(animations(), ref, 'animation');
+    return {
+        actions: {
+            list: () => actions().map(a => ({
+                id: a.id,
+                key: a.key,
+                name: a.name,
+                description: a.description,
+                applied: SceneActions.isActionApplied(a.id),
+            })),
+            apply(ref) {
+                const a = findAction(ref);
+                if (!a)
+                    return false;
+                SceneActions.applyAction(a);
+                return true;
+            },
+            revert(ref) {
+                const a = findAction(ref);
+                if (!a)
+                    return false;
+                SceneActions.revertAction(a);
+                return true;
+            },
+            toggle(ref) {
+                const a = findAction(ref);
+                return a ? SceneActions.toggleAction(a) : false;
+            },
+            isApplied(ref) {
+                const a = findAction(ref);
+                return a ? SceneActions.isActionApplied(a.id) : false;
+            },
+            reset() {
+                // Only this project's actions — another scene on the page keeps its state.
+                for (const a of actions())
+                    SceneActions.revertAction(a.id);
+            },
+        },
+        animations: {
+            list: () => animations().map(s => ({
+                id: s.id,
+                name: s.name,
+                description: s.description,
+                duration: animationDuration(s),
+                loop: !!s.loop,
+                yoyo: !!s.yoyo,
+                playing: AnimationsManager.isSequencePlaying(s.id),
+            })),
+            play(ref, options = {}) {
+                const s = findAnimation(ref);
+                if (!s)
+                    return false;
+                AnimationsManager.playSequence(s, { speed: options.speed, reverse: options.reverse });
+                return true;
+            },
+            pause(ref) {
+                const s = findAnimation(ref);
+                if (!s)
+                    return false;
+                AnimationsManager.pauseSequence(s.id);
+                return true;
+            },
+            resume(ref) {
+                const s = findAnimation(ref);
+                if (!s)
+                    return false;
+                AnimationsManager.resumeSequence(s.id);
+                return true;
+            },
+            stop(ref) {
+                const s = findAnimation(ref);
+                if (!s)
+                    return false;
+                AnimationsManager.stopSequence(s.id);
+                return true;
+            },
+            seek(ref, progress) {
+                const s = findAnimation(ref);
+                if (!s)
+                    return false;
+                AnimationsManager.seekToProgress(s.id, progress);
+                return true;
+            },
+            isPlaying(ref) {
+                const s = findAnimation(ref);
+                return s ? AnimationsManager.isSequencePlaying(s.id) : false;
+            },
+        },
+        on(type, listener) {
+            if (type === 'actionApplied' || type === 'actionReverted') {
+                return SceneActions.onEvent((e) => {
+                    if (e.type === 'reset')
+                        return;
+                    if ((type === 'actionApplied') !== (e.type === 'applied'))
+                        return;
+                    const a = actions().find(x => x.id === e.actionId);
+                    if (a)
+                        listener({ type, id: a.id, key: a.key, name: a.name });
+                });
+            }
+            const managerEvent = type === 'animationStart' ? 'sequenceStart' : 'sequenceEnd';
+            const handler = (e) => {
+                const s = animations().find(x => x.id === e.sequenceId);
+                if (s)
+                    listener({ type, id: s.id, name: s.name });
+            };
+            AnimationsManager.on(managerEvent, handler);
+            return () => AnimationsManager.off(managerEvent, handler);
+        },
+    };
+}

package/dist/components/CameraController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CameraController.d.ts","sourceRoot":"","sources":["../../src/components/CameraController.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAQ7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,UAAU,qBAAsB,SAAQ,gBAAgB;IACpD,QAAQ,EAAE,WAAW,CAAC;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;IAC1C,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;CAC/C;AAGD,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAwJ5D,CAAC;AACF,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"CameraController.d.ts","sourceRoot":"","sources":["../../src/components/CameraController.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAS7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,UAAU,qBAAsB,SAAQ,gBAAgB;IACpD,QAAQ,EAAE,WAAW,CAAC;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;IAC1C,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;CAC/C;AAGD,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CA0J5D,CAAC;AACF,eAAe,gBAAgB,CAAC"}

package/dist/components/CameraController.js

@@ -7,7 +7,10 @@ import { cameraManager } from '../utils/CameraSingleton.js';
 import { useAnimationEvents } from '../hooks/useAnimationEvents.js';
 import { usePathAnimation } from '../hooks/usePathAnimation.js';
 import { OrbitControls } from "@react-three/drei";
+import { useRuntimeSettings } from '../hooks/useRuntimeSettings.js';
 export const CameraController = ({ enableAutoAnimation = true, animationDuration = 1, animationEase = "power2.out", settings, onObjectReady, onObjectDispose, onControlsReady, onControlsDispose, }) => {
+    // Authored camera + any applied action patch ('camera').
+    settings = useRuntimeSettings('camera', settings);
     const { camera, set } = useThree();
     const cameraRef = useRef(camera);
     const transformAnimationProgress = useRef(0);
@@ -104,7 +107,7 @@ export const CameraController = ({ enableAutoAnimation = true, animationDuration
     useAnimationEvents({
         onStepStart: (event) => {
             if (event.step?.transitions) {
-                const stepDuration = event.step.duration || 1;
+                const stepDuration = event.step.duration ?? 1; // 0 = instant (actions)
                 event.step.transitions.forEach((transition) => {
                     const { state, properties, pathId } = transition;
                     if (state === 'camera') {

package/dist/components/EnvironmentManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EnvironmentManager.d.ts","sourceRoot":"","sources":["../../src/components/EnvironmentManager.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAqB,MAAM,OAAO,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAkB,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAGhF,OAAO,KAAK,EACR,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAIhE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;iFAWiF;AACjF,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG;IAChF,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAClC,OAAO,CAAC,EAAE,yBAAyB,CAAC;IACpC,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC9B,CAAC;AAEF,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC7D,YAAY,EAAE,YAAY,CAAC;IAC3B,iFAAiF;IACjF,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,cAAc,CAAC,EAAE,wBAAwB,CAAC;IAC1C,eAAe,CAAC,EAAE,yBAAyB,CAAC;IAC5C,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,cAAc,CAAC,mBAAmB,CAAC,CAAC;IACxD,YAAY,CAAC,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC;IAC9C;sEACkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB;AAoBD,QAAA,MAAM,kBAAkB,8FAwGtB,CAAC;AAGH,eAAe,kBAAkB,CAAC"}
+{"version":3,"file":"EnvironmentManager.d.ts","sourceRoot":"","sources":["../../src/components/EnvironmentManager.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAqB,MAAM,OAAO,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAkB,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAGhF,OAAO,KAAK,EACR,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAIhE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;iFAWiF;AACjF,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG;IAChF,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAClC,OAAO,CAAC,EAAE,yBAAyB,CAAC;IACpC,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC9B,CAAC;AAEF,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC7D,YAAY,EAAE,YAAY,CAAC;IAC3B,iFAAiF;IACjF,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,cAAc,CAAC,EAAE,wBAAwB,CAAC;IAC1C,eAAe,CAAC,EAAE,yBAAyB,CAAC;IAC5C,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,cAAc,CAAC,mBAAmB,CAAC,CAAC;IACxD,YAAY,CAAC,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC;IAC9C;sEACkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB;AAoBD,QAAA,MAAM,kBAAkB,8FAyGtB,CAAC;AAGH,eAAe,kBAAkB,CAAC"}

package/dist/components/EnvironmentManager.js

@@ -7,6 +7,7 @@ import { useEnvironmentProbe } from '../hooks/useEnvironmentProbe.js';
 import TerrainBuilder from './TerrainBuilder.js';
 import LandscapeBuilder from './LandscapeBuilder.js';
 import OceanBuilder from './OceanBuilder.js';
+import { useRuntimeSettings } from '../hooks/useRuntimeSettings.js';
 const DEFAULT_HDR = {
     visible: false,
     name: null,
@@ -25,11 +26,12 @@ const DEFAULT_HDR = {
 const ORIGIN = new Vector3(0, 0, 0);
 const EnvironmentManager = forwardRef(({ timeSettings, environment, hdrSettings, skySettings, cloudsSettings, terrainSettings, landscapeSettings, oceanSettings, fogSettings, cubeCameraResolution = 512, skyboxScale = 100000, playerPosition = ORIGIN, onTimeOfDayChange, onTimeUpdate, driveTime = true, onObjectReady, onObjectDispose, }, ref) => {
     const hdr = hdrSettings ?? environment?.hdr ?? DEFAULT_HDR;
-    const sky = skySettings ?? environment?.sky;
-    const clouds = cloudsSettings ?? environment?.clouds;
+    // Authored settings + applied action patches (runtime only).
+    const sky = useRuntimeSettings('sky', skySettings ?? environment?.sky);
+    const clouds = useRuntimeSettings('clouds', cloudsSettings ?? environment?.clouds);
     const terrain = terrainSettings ?? environment?.terrain;
     const landscape = landscapeSettings ?? environment?.landscape;
-    const ocean = oceanSettings ?? environment?.ocean;
+    const ocean = useRuntimeSettings('ocean', oceanSettings ?? environment?.ocean);
     const fog = fogSettings ?? environment?.fog;
     const sunSystemVisible = !!sky?.sunSystem?.visible;
     // Previously hardcoded true, which kept a cube camera alive — and re-captured

package/dist/components/ObjectNode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ObjectNode.d.ts","sourceRoot":"","sources":["../../src/components/ObjectNode.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,KAAK,EAAe,qBAAqB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAiBrD,KAAK,eAAe,GAAG,gBAAgB,GAAG;IACtC,IAAI,EAAE,cAAc,CAAC;IACrB,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;CAC7G,CAAC;AAkBF,QAAA,MAAM,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAsIzC,CAAC;AACF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"ObjectNode.d.ts","sourceRoot":"","sources":["../../src/components/ObjectNode.tsx"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,KAAK,EAAe,qBAAqB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAiBrD,KAAK,eAAe,GAAG,gBAAgB,GAAG;IACtC,IAAI,EAAE,cAAc,CAAC;IACrB,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;CAC7G,CAAC;AAkBF,QAAA,MAAM,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAyIzC,CAAC;AACF,eAAe,UAAU,CAAC"}

package/dist/components/ObjectNode.js

@@ -15,6 +15,7 @@ import GridGenerator from "./GridsGenerator.js";
 import OceanBuilder from "./OceanBuilder.js";
 import LandscapeObject from "./LandscapeObject.js";
 import LayoutInstances from "./LayoutInstances.js";
+import { useRuntimeSettings } from "../hooks/useRuntimeSettings.js";
 import { SELF_MANAGED_MATERIAL } from "../constants.js";
 import { LAYOUT_CAPABLE_TYPES, getObjectLayoutSupport, normalizeObjectLayout, isGenerativeParticlesConfig } from "@3driseai/3drise-core";
 // Slots after the first render with no ready callbacks: one object reports once.
@@ -47,7 +48,10 @@ const GroupWithChildren = ({ createdObject, children, onObjectReady, onObjectDis
     return (_jsxs(CreatedObject, { createdObject: createdObject, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose, handleObjectClick: handleObjectClick, shouldApply3driseMaterial: !isGroup && !selfManagedMaterial, children: [!isGroup && renderObject(createdObject, handleObjectClick), children.map(childNode => (_jsx(ObjectNode, { node: childNode, handleObjectClick: handleObjectClick, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }, childNode.objectId)))] }, createdObject.id));
 };
 const ObjectNode = ({ node, onObjectReady, onObjectDispose, handleObjectClick }) => {
-    const { children, createdObject } = node;
+    const { children } = node;
+    // Authored settings + any applied action patches (runtime only). Every renderer
+    // below sees the patched object, so an action can change anything an edit can.
+    const createdObject = useRuntimeSettings(node.createdObject?.id, node.createdObject);
     // Children describe themselves with their own settings; the scene above
     // knows them by the node's createdObject, so relabel on the way up.
     const relabel = useCallback((obj) => ({

package/dist/components/ObjectsRenderer.d.ts

@@ -1,4 +1,4 @@
-import type { AnimationSequence, GeneralObjectSettings, CameraState, CreatedObjectSettings } from '@3driseai/3drise-core';
+import type { ActionSequence, AnimationSequence, GeneralObjectSettings, CameraState, CreatedObjectSettings } from '@3driseai/3drise-core';
 import type { ObjectReadyProps } from '../types/objectReady';
 import React from "react";
 import { Object3D } from "three";
@@ -10,6 +10,7 @@ interface ObjectsRendererProps extends ObjectReadyProps {
     onObjectsReady?: () => void;
     handleObjectClick?: (object: CreatedObjectSettings, ref: Object3D, event: ThreeEvent<MouseEvent>) => void;
     sequences?: AnimationSequence[];
+    actionSequences?: ActionSequence[];
 }
 declare const ObjectsRenderer: React.FC<ObjectsRendererProps>;
 export default ObjectsRenderer;

package/dist/components/ObjectsRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ObjectsRenderer.d.ts","sourceRoot":"","sources":["../../src/components/ObjectsRenderer.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAI1H,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,UAAU,oBAAqB,SAAQ,gBAAgB;IACnD,cAAc,EAAE,WAAW,CAAC;IAC5B,qBAAqB,EAAE,qBAAqB,CAAC;IAC7C,cAAc,EAAE,qBAAqB,EAAE,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;IAC1G,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACnC;AAGD,QAAA,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,oBAAoB,CA0ClD,CAAC;AAEH,eAAe,eAAe,CAAC"}
+{"version":3,"file":"ObjectsRenderer.d.ts","sourceRoot":"","sources":["../../src/components/ObjectsRenderer.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAI1I,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,UAAU,oBAAqB,SAAQ,gBAAgB;IACnD,cAAc,EAAE,WAAW,CAAC;IAC5B,qBAAqB,EAAE,qBAAqB,CAAC;IAC7C,cAAc,EAAE,qBAAqB,EAAE,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;IAC1G,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAChC,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;CACtC;AAGD,QAAA,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,oBAAoB,CA2ClD,CAAC;AAEH,eAAe,eAAe,CAAC"}

package/dist/components/ObjectsRenderer.js

@@ -4,7 +4,7 @@ import { buildObjectTree } from '@3driseai/3drise-core';
 import ObjectNode from './ObjectNode.js';
 import useInteraction from '../hooks/useInteraction.js';
 import { useObjectReady } from '../hooks/useObjectReady.js';
-const ObjectsRenderer = memo(({ cameraSettings, createdObjects, generalObjectSettings, onObjectsReady, onObjectReady, onObjectDispose, handleObjectClick, sequences = [], }) => {
+const ObjectsRenderer = memo(({ cameraSettings, createdObjects, generalObjectSettings, onObjectsReady, onObjectReady, onObjectDispose, handleObjectClick, sequences = [], actionSequences = [], }) => {
     const groupRef = useRef(null);
     const objectsTree = useMemo(() => buildObjectTree(createdObjects), [createdObjects]);
     const readyObjectsCount = useRef(0);
@@ -32,6 +32,7 @@ const ObjectsRenderer = memo(({ cameraSettings, createdObjects, generalObjectSet
     const { executeInteraction } = useInteraction({
         cameraSettings,
         sequences,
+        actionSequences,
     });
     const handleObjectClickHandler = (createdObject, ref, event) => {
         const clickInteractions = filterInteractionsByEvent(createdObject.actions, "click");

package/dist/components/ProjectLoader.d.ts

@@ -1,9 +1,10 @@
+import type { SceneHandle } from "../api/sceneHandle";
 import type { CreatedObjectSettings, HtmlElement } from '@3driseai/3drise-core';
 import React from "react";
 import { Object3D } from "three";
 import { type ThreeEvent } from "@react-three/fiber";
 import type { ObjectReadyProps } from "../types/objectReady";
-type ProjectProps = ObjectReadyProps & {
+declare const ProjectLoader: React.ForwardRefExoticComponent<ObjectReadyProps & {
     projectId: string;
     loadingIndicator?: React.ReactNode;
     onObjectClick?: (object: CreatedObjectSettings, ref: Object3D, event: ThreeEvent<MouseEvent>) => void;
@@ -11,7 +12,12 @@ type ProjectProps = ObjectReadyProps & {
     onElementClick?: (element: HtmlElement) => void;
     onElementHover?: (element: HtmlElement | null) => void;
     onSceneInitialized?: () => void;
-};
-declare const ProjectLoader: React.FC<ProjectProps>;
+    /**
+     * Called once the project is loaded and its canvas exists, with the handle for
+     * driving its actions and animations from your own UI. The same handle is also
+     * available through `ref`.
+     */
+    onSceneReady?: (scene: SceneHandle) => void;
+} & React.RefAttributes<SceneHandle>>;
 export default ProjectLoader;
 //# sourceMappingURL=ProjectLoader.d.ts.map

package/dist/components/ProjectLoader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProjectLoader.d.ts","sourceRoot":"","sources":["../../src/components/ProjectLoader.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGhF,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,KAAK,YAAY,GAAG,gBAAgB,GAAG;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACnC,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;IACtG,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,QAAQ,KAAK,IAAI,CAAC;IACvE,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;IAChD,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IACvD,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;CACnC,CAAC;AAGF,QAAA,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,YAAY,CAsDzC,CAAC;AACF,eAAe,aAAa,CAAC"}
+{"version":3,"file":"ProjectLoader.d.ts","sourceRoot":"","sources":["../../src/components/ProjectLoader.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAItD,OAAO,KAAK,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGhF,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAkB7D,QAAA,MAAM,aAAa;eAhBJ,MAAM;uBACE,KAAK,CAAC,SAAS;oBAClB,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI;oBACrF,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,QAAQ,KAAK,IAAI;qBACrD,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI;qBAC9B,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI;yBACjC,MAAM,IAAI;IAC/B;;;;OAIG;mBACY,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI;qCA0D7C,CAAC;AAEH,eAAe,aAAa,CAAC"}

package/dist/components/ProjectLoader.js

@@ -1,11 +1,11 @@
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
+import { forwardRef, useEffect, useState } from "react";
 import { dataCenterServer } from '../constants.js';
 import SceneBuilder from "./SceneBuilder.js";
 import { loadAssets, } from "@3driseai/3drise-core";
 import LoadingIndicator from "./LoadingIndicator.js";
 import { useMeshController } from "../hooks/useMeshController.js";
-const ProjectLoader = ({ projectId, onObjectClick, onObjectHover, onElementClick, onElementHover, onSceneInitialized, onObjectReady, onObjectDispose, loadingIndicator = _jsx(LoadingIndicator, { text: "Loading project...", fullScreen: true, animate: true }) }) => {
+const ProjectLoader = forwardRef(({ projectId, onObjectClick, onObjectHover, onElementClick, onElementHover, onSceneInitialized, onSceneReady, onObjectReady, onObjectDispose, loadingIndicator = _jsx(LoadingIndicator, { text: "Loading project...", fullScreen: true, animate: true }) }, ref) => {
     const [project, setProject] = useState(null);
     const meshController = useMeshController();
     useEffect(() => {
@@ -56,6 +56,7 @@ const ProjectLoader = ({ projectId, onObjectClick, onObjectHover, onElementClick
                 flexDirection: 'column', gap: '1rem'
             }, children: loadingIndicator });
     }
-    return _jsx(_Fragment, { children: _jsx(SceneBuilder, { project: project, onSceneInitialized: onSceneInitialized, onUiElementClick: onElementClick, onUiElementHover: onElementHover, onObjectClick: onObjectClick, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }) });
-};
+    return _jsx(_Fragment, { children: _jsx(SceneBuilder, { ref: ref, project: project, onSceneReady: onSceneReady, onSceneInitialized: onSceneInitialized, onUiElementClick: onElementClick, onUiElementHover: onElementHover, onObjectClick: onObjectClick, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }) });
+});
+ProjectLoader.displayName = 'ProjectLoader';
 export default ProjectLoader;

package/dist/components/SceneBuilder.d.ts

@@ -1,6 +1,14 @@
+import { type SceneHandle } from "../api/sceneHandle";
 import type { SceneBuilderProps } from '@3driseai/3drise-core';
 import React from "react";
 import type { ObjectReadyProps } from "../types/objectReady";
-declare const SceneBuilder: React.FC<SceneBuilderProps & ObjectReadyProps>;
+export type SceneBuilderViewerProps = SceneBuilderProps & ObjectReadyProps & {
+    /** Called once the canvas exists, with the handle for driving this project's actions and animations. */
+    onSceneReady?: (scene: SceneHandle) => void;
+};
+declare const SceneBuilder: React.ForwardRefExoticComponent<SceneBuilderProps & ObjectReadyProps & {
+    /** Called once the canvas exists, with the handle for driving this project's actions and animations. */
+    onSceneReady?: (scene: SceneHandle) => void;
+} & React.RefAttributes<SceneHandle>>;
 export default SceneBuilder;
 //# sourceMappingURL=SceneBuilder.d.ts.map

package/dist/components/SceneBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SceneBuilder.d.ts","sourceRoot":"","sources":["../../src/components/SceneBuilder.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAQ/D,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,QAAA,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,GAAG,gBAAgB,CAuIhE,CAAC;AACF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"SceneBuilder.d.ts","sourceRoot":"","sources":["../../src/components/SceneBuilder.tsx"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,WAAW,EAA0B,MAAM,oBAAoB,CAAC;AAGjG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAQ/D,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,gBAAgB,GAAG;IACzE,wGAAwG;IACxG,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CAC/C,CAAC;AAEF,QAAA,MAAM,YAAY;IAJd,wGAAwG;mBACzF,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI;qCAkJ7C,CAAC;AAEH,eAAe,YAAY,CAAC"}

package/dist/components/SceneBuilder.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState } from "react";
+import { forwardRef, useImperativeHandle, useMemo, useRef, useState } from "react";
+import { createSceneHandle } from "../api/sceneHandle.js";
 import { Canvas } from "@react-three/fiber";
 import { LIGHTING_PRESETS, SceneStore } from "@3driseai/3drise-core";
 import { NoToneMapping } from "three";
@@ -9,7 +10,7 @@ import CameraController from "./CameraController.js";
 import ObjectsRenderer from "./ObjectsRenderer.js";
 import CursorController from "./cursor/CursorController.js";
 import { Physics } from "@react-three/rapier";
-const SceneBuilder = ({ project, width = "100%", height = "100vh", style = {}, className = "", onSceneInitialized, onUiElementClick, onObjectClick, onObjectReady, onObjectDispose, }) => {
+const SceneBuilder = forwardRef(({ project, width = "100%", height = "100vh", style = {}, className = "", onSceneInitialized, onSceneReady, onUiElementClick, onObjectClick, onObjectReady, onObjectDispose, }, ref) => {
     const sceneSettings = (project.sceneSettingsData || {});
     // const meshController = useMeshController();
     const [isThreeJsMounted, setIsThreeJsMounted] = useState(false);
@@ -41,6 +42,13 @@ const SceneBuilder = ({ project, width = "100%", height = "100vh", style = {}, c
         }
     });
     const animationSequences = project.animationSequences || [];
+    const actionSequences = project.actionSequences || [];
+    // The external control handle (see api/sceneHandle). Built once; reads the
+    // current project lists through a ref, so it never goes stale.
+    const handleSource = useRef({ actions: actionSequences, animations: animationSequences });
+    handleSource.current = { actions: actionSequences, animations: animationSequences };
+    const sceneHandle = useMemo(() => createSceneHandle(() => handleSource.current), []);
+    useImperativeHandle(ref, () => sceneHandle, [sceneHandle]);
     const sceneObjects = project.sceneObjects || sceneSettings.scene?.objectSettings || [];
     const modelObjects = sceneObjects.filter((obj) => obj.type === "model");
     const meshObjects = sceneObjects.filter((obj) => obj.type === "mesh");
@@ -131,6 +139,8 @@ const SceneBuilder = ({ project, width = "100%", height = "100vh", style = {}, c
                 if (onSceneInitialized) {
                     onSceneInitialized();
                 }
-            }, children: _jsxs(Physics, { gravity: physicsSettings.gravity, paused: !physicsSettings.enabled, debug: physicsSettings.debug, children: [_jsx(LightsManager, { config: lighting[0], onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }), environment && _jsx(EnvironmentManager, { environment: environment, timeSettings: timeSettings, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }), _jsx(CameraController, { settings: camera, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }), _jsx(ObjectsRenderer, { cameraSettings: camera, generalObjectSettings: generalObjectSettings, createdObjects: sceneObjects, onObjectsReady: undefined, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose, sequences: animationSequences, handleObjectClick: onObjectClick ? (object, ref, event) => onObjectClick(object, ref, event) : undefined }), _jsx(CursorController, { effects: project.cursor?.effects, clickActions: project.cursor?.clickActions, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose })] }) }) }));
-};
+                onSceneReady?.(sceneHandle);
+            }, children: _jsxs(Physics, { gravity: physicsSettings.gravity, paused: !physicsSettings.enabled, debug: physicsSettings.debug, children: [_jsx(LightsManager, { config: lighting[0], onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }), environment && _jsx(EnvironmentManager, { environment: environment, timeSettings: timeSettings, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }), _jsx(CameraController, { settings: camera, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose }), _jsx(ObjectsRenderer, { cameraSettings: camera, generalObjectSettings: generalObjectSettings, createdObjects: sceneObjects, onObjectsReady: undefined, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose, sequences: animationSequences, actionSequences: actionSequences, handleObjectClick: onObjectClick ? (object, ref, event) => onObjectClick(object, ref, event) : undefined }), _jsx(CursorController, { effects: project.cursor?.effects, clickActions: project.cursor?.clickActions, onObjectReady: onObjectReady, onObjectDispose: onObjectDispose })] }) }) }));
+});
+SceneBuilder.displayName = 'SceneBuilder';
 export default SceneBuilder;

package/dist/components/Stars.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Stars.d.ts","sourceRoot":"","sources":["../../src/components/Stars.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO,EAAE,cAAc,EAA4C,MAAM,OAAO,CAAC;AAQjF,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,MAAM,WAAW,UAAW,SAAQ,gBAAgB;IAChD,QAAQ,EAAE,qBAAqB,CAAC;IAChC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAOD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAuDnE;AAYD,QAAA,MAAM,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,UAAU,CA2K/B,CAAC;AACF,eAAe,KAAK,CAAC"}
+{"version":3,"file":"Stars.d.ts","sourceRoot":"","sources":["../../src/components/Stars.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO,EAAE,cAAc,EAA4C,MAAM,OAAO,CAAC;AAQjF,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,MAAM,WAAW,UAAW,SAAQ,gBAAgB;IAChD,QAAQ,EAAE,qBAAqB,CAAC;IAChC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAOD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAuDnE;AAYD,QAAA,MAAM,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,UAAU,CA4K/B,CAAC;AACF,eAAe,KAAK,CAAC"}

package/dist/components/Stars.js

@@ -135,7 +135,8 @@ const Stars = ({ settings, timeSettings, sunSystemEnabled = false, onObjectReady
                     pointsRef.current.visible = toProps.visible;
                 }
                 // color — existing path
-                setDuration(event.step.duration);
+                // speed = 1 / duration below; keep an instant (0) step finite.
+                setDuration(Math.max(event.step.duration ?? 1, 0.001));
                 if (toProps.color !== undefined) {
                     setColors({
                         baseColor: fromProps.color,

package/dist/hooks/index.d.ts

@@ -45,6 +45,7 @@ export type { UseLightMouseMoveOptions } from './useLightMouseMove';
 export { useLightMouseMove } from './useLightMouseMove';
 export { useLightShadow } from './useLightShadow';
 export { LIGHT_STRUCTURAL, applyLightLive, useLightLive } from './useLightLive';
+export { useLightTargets } from './useLightTargets';
 export type { UseLightConfigResult } from './useLightConfig';
 export { applyLightConfig, useLightConfig } from './useLightConfig';
 export { useMaterialApplication } from './useMaterialApplication';
@@ -88,4 +89,5 @@ export type { LandscapeLiveHandle } from './useLandscapeLive';
 export { LANDSCAPE_LIVE_KEY, useLandscapeLive } from './useLandscapeLive';
 export { useLandscapeMaps } from './useLandscapeMaps';
 export type { LandscapeMapsState } from './useLandscapeMaps';
+export { useRuntimeSettings } from './useRuntimeSettings';
 //# sourceMappingURL=index.d.ts.map

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

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

package/dist/hooks/index.js

@@ -31,6 +31,7 @@ export { useLightHandlers } from './useLightHandlers.js';
 export { useLightMouseMove } from './useLightMouseMove.js';
 export { useLightShadow } from './useLightShadow.js';
 export { LIGHT_STRUCTURAL, applyLightLive, useLightLive } from './useLightLive.js';
+export { useLightTargets } from './useLightTargets.js';
 export { applyLightConfig, useLightConfig } from './useLightConfig.js';
 export { useMaterialApplication } from './useMaterialApplication.js';
 export { useMaterialOptions } from './useMaterialOptions.js';
@@ -64,3 +65,4 @@ export { useWaterEnvironment } from './useWaterEnvironment.js';
 export { useWaterReflections } from './useWaterReflections.js';
 export { LANDSCAPE_LIVE_KEY, useLandscapeLive } from './useLandscapeLive.js';
 export { useLandscapeMaps } from './useLandscapeMaps.js';
+export { useRuntimeSettings } from './useRuntimeSettings.js';

package/dist/hooks/useInteraction.d.ts

@@ -1,7 +1,8 @@
-import type { AnimationSequence, CameraState } from '@3driseai/3drise-core';
-export declare function useInteraction({ cameraSettings, sequences, }: {
+import type { ActionSequence, AnimationSequence, CameraState } from '@3driseai/3drise-core';
+export declare function useInteraction({ cameraSettings, sequences, actionSequences, }: {
     cameraSettings: CameraState;
     sequences: AnimationSequence[];
+    actionSequences?: ActionSequence[];
 }): {
     executeInteraction: (params: any) => void;
     currentAnimatedRef: import("react").RefObject<any>;

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

@@ -1 +1 @@
-{"version":3,"file":"useInteraction.d.ts","sourceRoot":"","sources":["../../src/hooks/useInteraction.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAA4B,MAAM,uBAAuB,CAAC;AAatG,wBAAgB,cAAc,CAAC,EAE/B,cAAc,EAAE,SAAS,GAAG,EAAE;IAClB,cAAc,EAAE,WAAW,CAAC;IAC5B,SAAS,EAAE,iBAAiB,EAAE,CAAC;CAClC;;;;;EA+NR;AACD,eAAe,cAAc,CAAC"}
+{"version":3,"file":"useInteraction.d.ts","sourceRoot":"","sources":["../../src/hooks/useInteraction.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,WAAW,EAA4B,MAAM,uBAAuB,CAAC;AAatH,wBAAgB,cAAc,CAAC,EAE/B,cAAc,EAAE,SAAS,EAAE,eAAoB,GAAG,EAAE;IACxC,cAAc,EAAE,WAAW,CAAC;IAC5B,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;CACtC;;;;;EAkQR;AACD,eAAe,cAAc,CAAC"}

package/dist/hooks/useInteraction.js

@@ -8,7 +8,7 @@
  * - Triggering animations
  */
 import { useCallback, useRef } from 'react';
-import { AnimationsManager, texturesManager } from '@3driseai/3drise-core';
+import { AnimationsManager, SceneActions, texturesManager } from '@3driseai/3drise-core';
 import useCameraAnimation from '../hooks/useCameraAnimation.js';
 import { useFrameAnimations } from '../hooks/useFrameAnimations.js';
 import { useObjectEffects } from '../hooks/useObjectEffects.js';
@@ -21,10 +21,12 @@ import { findById } from '../utils/sceneQuery.js';
 // =============================================================================
 export function useInteraction({ 
 // mode = 'default',
-cameraSettings, sequences, }) {
+cameraSettings, sequences, actionSequences = [], }) {
     // Redux state
     // Track currently animated object for toggle behavior
     const currentAnimatedRef = useRef(null);
+    // Animation ids whose last toggle played forward — the next toggle plays them reversed.
+    const toggledAnimationsRef = useRef(new Set());
     // Hooks
     const { animateCamera } = useCameraAnimation({
         autoAnimate: false,
@@ -59,17 +61,46 @@ cameraSettings, sequences, }) {
     // ===========================================================================
     // UTILITY: Trigger Animations
     // ===========================================================================
-    const triggerAnimations = useCallback((animationIds) => {
+    // 'toggle' in an interaction's operations is a modifier, not an effect of its own:
+    // it makes that interaction's animations and actions two-state. Animations play
+    // forward then reversed; actions apply then revert (their patches are removed).
+    const triggerAnimations = useCallback((animationIds, toggle = false) => {
         if (!animationIds || animationIds.length === 0)
             return;
         animationIds.forEach(animationId => {
             const sequence = sequences.find(s => s.id === animationId);
-            if (sequence) {
+            if (!sequence)
+                return;
+            if (!toggle) {
                 AnimationsManager.playSequence(sequence);
+                return;
             }
+            const toggled = toggledAnimationsRef.current;
+            const reverse = toggled.has(animationId);
+            if (reverse)
+                toggled.delete(animationId);
+            else
+                toggled.add(animationId);
+            AnimationsManager.playSequence(sequence, { reverse });
         });
     }, [sequences]);
     // ===========================================================================
+    // UTILITY: Trigger Actions (instant)
+    // ===========================================================================
+    const triggerActions = useCallback((actionIds, toggle = false) => {
+        if (!actionIds || actionIds.length === 0)
+            return;
+        actionIds.forEach(actionId => {
+            const action = actionSequences.find(a => a.id === actionId);
+            if (!action)
+                return;
+            if (toggle)
+                SceneActions.toggleAction(action);
+            else
+                SceneActions.applyAction(action);
+        });
+    }, [actionSequences]);
+    // ===========================================================================
     // UTILITY: Execute Single Operation
     // ===========================================================================
     const executeOperation = useCallback(async (operation, ref, createdObject, textureUrl) => {
@@ -182,10 +213,12 @@ cameraSettings, sequences, }) {
                 }
                 break;
             }
+            case 'toggle':
+                // Modifier for animationIds/actionIds — handled in executeInteraction.
+                break;
             case 'create':
             case 'update':
             case 'delete':
-            case 'toggle':
             case 'loadProject':
                 break;
         }
@@ -231,9 +264,11 @@ cameraSettings, sequences, }) {
             // For now, use the original createdObject for position data
             executeOperations(interaction.operations, targetRef, createdObject, textureUrl);
         });
-        // 3. Trigger animations
-        triggerAnimations(interaction.animationIds);
-    }, [resolveTargets, executeOperations, triggerAnimations]);
+        // 3. Trigger animations and actions ('toggle' makes both two-state)
+        const toggle = interaction.operations?.includes('toggle') ?? false;
+        triggerAnimations(interaction.animationIds, toggle);
+        triggerActions(interaction.actionIds, toggle);
+    }, [resolveTargets, executeOperations, triggerAnimations, triggerActions]);
     // ===========================================================================
     // RETURN
     // ===========================================================================

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/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'. 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'. 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"}

package/dist/hooks/useSequenceAnimation.js

@@ -15,6 +15,17 @@ function lerp(a, b, t) {
 function lerpVec3(a, b, t) {
     return [lerp(a[0], b[0], t), lerp(a[1], b[1], t), lerp(a[2], b[2], t)];
 }
+/** Transform lerp for one step at progress p (non-path). */
+function applyTransform(obj, step, p) {
+    obj.position.set(...lerpVec3(step.fromPosition, step.toPosition, p));
+    obj.rotation.set(...lerpVec3(step.fromRotation, step.toRotation, p));
+    obj.scale.set(...lerpVec3(step.fromScale, step.toScale, p));
+}
+/** Transform + material for one step at progress p (non-path). */
+function applyTransformAndMaterial(obj, step, p) {
+    applyTransform(obj, step, p);
+    interpolateMaterialProps(obj, step.materialFrom, step.materialTo, p);
+}
 /** Get material-related properties from a transition properties record */
 function extractMaterialProps(props) {
     if (!props)
@@ -67,7 +78,8 @@ export const useSequenceAnimation = (objectId, objectSource) => {
             const transition = event.step.transitions[transitionIndex];
             const stagger = event.step.stagger || 0;
             const staggerOffsetMs = transitionIndex * stagger * 1000;
-            const d = event.step.duration || 1;
+            // `?? 1`, not `|| 1`: a 0 duration is an instant change (actions), not a missing value.
+            const d = event.step.duration ?? 1;
             const ease = event.step.ease || 'linear';
             const { properties, pathId = null } = transition;
             // Visibility shortcut
@@ -120,6 +132,18 @@ export const useSequenceAnimation = (objectId, objectSource) => {
                 visibilityOverride: null,
                 pathId,
             });
+            // Instant step (an action, or a 0-length animation step): land on `to` now.
+            // The manager emits stepStart and sequenceEnd in the same tick for these, and
+            // sequenceEnd clears stepRef, so waiting for useFrame would apply nothing.
+            if (d === 0) {
+                stopPathAnimation();
+                if (resolvedObject && stepRef.current) {
+                    applyTransformAndMaterial(resolvedObject, stepRef.current, 1);
+                }
+                updateStepRef(null);
+                updateProgressRef(1);
+                return;
+            }
             updateProgressRef(0);
             if (pathId) {
                 startPathAnimation(pathId, d, { ease });
@@ -176,15 +200,9 @@ export const useSequenceAnimation = (objectId, objectSource) => {
             resolvedObject.scale.set(...sca);
         }
         else {
-            // — Transform —
-            const pos = lerpVec3(step.fromPosition, step.toPosition, p);
-            const rot = lerpVec3(step.fromRotation, step.toRotation, p);
-            const sca = lerpVec3(step.fromScale, step.toScale, p);
-            resolvedObject.position.set(...pos);
-            resolvedObject.rotation.set(...rot);
-            resolvedObject.scale.set(...sca);
+            applyTransform(resolvedObject, step, p);
         }
-        // — Material properties —
+        // Material properties
         interpolateMaterialProps(resolvedObject, step.materialFrom, step.materialTo, p);
         if (p >= 1) {
             updateProgressRef(1);

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { AnimationsManager as animationsManager, fontManager } from '@3driseai/3
 export * from './types';
 export * from './components';
 export * from './hooks';
+export { createSceneHandle } from './api/sceneHandle';
+export type { SceneHandle, SceneHandleEvent, SceneHandleEventType, SceneActionInfo, SceneAnimationInfo, ScenePlayOptions } from './api/sceneHandle';
 export type { PathAnimationOptions as PathAnimationHookOptions } from './hooks/usePathAnimation';
 export { cameraManager } from './utils/CameraSingleton';
 export { applyAnchorSettings, createCurves, createSunPosition, randomRange, } from './utils/utils3d';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAG1F,OAAO,EAAE,iBAAiB,IAAI,iBAAiB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAG5F,cAAc,SAAS,CAAC;AAGxB,cAAc,cAAc,CAAC;AAG7B,cAAc,SAAS,CAAC;AAExB,YAAY,EAAE,oBAAoB,IAAI,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAGjG,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,WAAW,GAAG,MAAM,iBAAiB,CAAC;AACrG,OAAO,EAAE,mBAAmB,IAAI,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACvF,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC;AACtF,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC7F,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC/E,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACvF,YAAY,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EACL,oBAAoB,EACpB,4BAA4B,EAC5B,qBAAqB,EACrB,eAAe,EACf,8BAA8B,GAC/B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpG,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnF,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC1F,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrF,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,6BAA6B,EAC7B,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,6BAA6B,EAC7B,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,GACd,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlF,OAAO,EACL,sBAAsB,EACtB,aAAa,EACb,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAC5F,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,EAChB,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,sBAAsB,EACtB,eAAe,EACf,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,yBAAyB,EACzB,eAAe,EACf,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,eAAe,EACf,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,yBAAyB,EACzB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -6,6 +6,8 @@ export * from './types/index.js';
 export * from './components/index.js';
 // Hooks (hooks/index.ts owns the list)
 export * from './hooks/index.js';
+// External control of a loaded project (ProjectLoader ref / onSceneReady)
+export { createSceneHandle } from './api/sceneHandle.js';
 // Utils
 export { cameraManager } from './utils/CameraSingleton.js';
 export { applyAnchorSettings, createCurves, createSunPosition, randomRange, } from './utils/utils3d.js';

package/package.json

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