@3driseai/3drise-viewer 0.1.26 → 0.1.27

package/dist/animationsV2/ClipsRuntime.js

@@ -1,7 +1,43 @@
+// =============================================================================
+// ClipsRuntime — plays, poses and restores clips and sequences. Execution only.
+// =============================================================================
+//
+// Data lives in Redux (animationClipsSlice, animationSequencesSlice); this holds
+// runtime instances:
+//
+//   clip instance      — one clip on its own clock. Honours the clip's loop, yoyo
+//                        and endMode.
+//   sequence instance  — one clock over a resolved schedule (sequenceUtils). Each
+//                        scheduled clip plays once, forward, at its own local time;
+//                        loop / yoyo / reverse / endMode act on the whole sequence.
+//
+// Either kind is `playing` (time advances by frame delta × speed, not wall clock,
+// so pause / seek / speed are exact) or posed (held at a time: the editor
+// playhead, a finished 'hold', a seek).
+//
+// Each frame every active driver proposes a value per property; the proposals are
+// merged in priority order (activation order; inside a sequence, schedule order)
+// so the last one wins, and only a property whose WINNING value changed is
+// written. Writing a material property every frame would flag it for recompile,
+// and re-writing an unchanged camera would fight the user's orbit.
+//
+// A property that stops being driven (stop, a 'restore' end, a sequence entry
+// scrubbed back before its start) is written back to its authored value.
+//
+// Sequence cues switch actions (SceneActions) by time: each tick a sequence works
+// out which of its actions should be on at its current time and applies / reverts
+// only what changed. It reverts only what it applied itself — an action already on
+// (a click, the API) is left alone. Effects run while the sequence plays (or is
+// driven); a posed sequence (the editor's scrub) applies patches only. Stopping
+// the sequence reverts its actions; a 'hold' finish keeps them.
+//
+import { SceneActions } from '@3driseai/3drise-core';
 import { getAtPath, sampleTrack } from './clipUtils.js';
-import { applyValue, clearApplierCaches } from './appliers.js';
+import { applyValue, clearApplierCaches, isTargetMounted } from './appliers.js';
 import { restoreNodeTrack } from './nodeTracks.js';
-import { entryLocalTime, isEntryActive, resolveSequence, } from './sequenceUtils.js';
+import { cueStatesAt, entryLocalTime, isEntryActive, resolveSequence, } from './sequenceUtils.js';
+/** Longest an autoplaying sequence waits for its targets. */
+const MAX_TARGET_WAIT_MS = 8000;
 const targetKey = (state, node, path) => `${state}|${node ?? ''}|${path}`;
 class ClipsRuntime {
     clips = new Map();
@@ -10,26 +46,79 @@ class ClipsRuntime {
     order = 0;
     version = 0;
     listeners = new Set();
+    /** Coarse: play / pause / stop / start / end / reset / data edits — never per frame. */
+    stateVersion = 0;
+    stateListeners = new Set();
     eventListeners = new Set();
     /** tracks whose authored value must be written back on the next tick */
     pendingRestore = [];
     /** last written value per property (targetKey -> JSON) */
     written = new Map();
+    // --- diagnostics ------------------------------------------------------------------
+    // On with `?animdebug=1` in the URL, or localStorage '3drise.animdebug' = '1'
+    // (ClipPlayer reads it). Logs every lifecycle call on sequences (with the caller's
+    // stack for the ones that stop / pose / pause), the target wait, progress once a
+    // second, and writes that don't land. Nothing changes behaviour.
+    debug = false;
+    logAt = new Map();
+    dlog(...args) {
+        if (this.debug)
+            console.log('%c[anim]', 'color:#a78bfa;font-weight:bold', `${(performance.now() / 1000).toFixed(2)}s`, ...args);
+    }
+    /** At most once per `ms` per key. */
+    dlogEvery(key, ms, ...args) {
+        if (!this.debug)
+            return;
+        const now = performance.now();
+        if (now - (this.logAt.get(key) ?? -Infinity) < ms)
+            return;
+        this.logAt.set(key, now);
+        this.dlog(...args);
+    }
+    caller() {
+        return (new Error().stack ?? '').split('\n').slice(3, 8).map(l => l.trim()).join(' ← ');
+    }
     // --- wiring -------------------------------------------------------------------
     setContext(ctx) {
+        this.dlog('setContext', ctx ? { camera: !!ctx.camera, controls: !!ctx.controls, getAction: !!ctx.getAction } : null);
         this.ctx = ctx;
         this.written.clear();
         clearApplierCaches();
     }
+    /**
+     * Every change, including each frame's time while anything plays. For UI that
+     * follows the playhead, write through refs in the listener — never re-render React
+     * per frame (the timeline panels would re-render ~60×/s on the render thread).
+     */
     subscribe(listener) {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
     }
     getVersion() { return this.version; }
+    /** State changes only (play / pause / stop / start / end / reset / edits) — safe for React. */
+    subscribeState(listener) {
+        this.stateListeners.add(listener);
+        return () => this.stateListeners.delete(listener);
+    }
+    getStateVersion() { return this.stateVersion; }
     on(listener) {
         this.eventListeners.add(listener);
         return () => this.eventListeners.delete(listener);
     }
+    /**
+     * Forget every instance without writing anything back — a new scene is loading
+     * (the singleton outlives a route change: whatever the studio was playing must not
+     * carry into the published view).
+     */
+    reset() {
+        this.dlog('reset', { clips: this.clips.size, sequences: [...this.sequences.values()].map(i => i.seq.name) }, this.caller());
+        this.clips.clear();
+        this.sequences.clear();
+        this.pendingRestore = [];
+        this.written.clear();
+        clearApplierCaches();
+        this.bumpState();
+    }
     // --- clips ----------------------------------------------------------------------
     play(clip, opts = {}) {
         const existing = this.clips.get(clip.id);
@@ -42,21 +131,21 @@ class ClipsRuntime {
             time = clip.duration;
         this.clips.set(clip.id, { clip, time, speed: opts.speed ?? 1, direction, playing: true, order: ++this.order });
         this.emit({ type: 'start', kind: 'clip', id: clip.id });
-        this.bump();
+        this.bumpState();
     }
     pause(clipId) {
         const inst = this.clips.get(clipId);
         if (!inst)
             return;
         inst.playing = false;
-        this.bump();
+        this.bumpState();
     }
     resume(clipId) {
         const inst = this.clips.get(clipId);
         if (!inst)
             return;
         inst.playing = true;
-        this.bump();
+        this.bumpState();
     }
     /** Stop and put the clip's properties back to their authored values. */
     stop(clipId) {
@@ -65,7 +154,7 @@ class ClipsRuntime {
             return;
         this.clips.delete(clipId);
         this.pendingRestore.push(...inst.clip.tracks);
-        this.bump();
+        this.bumpState();
     }
     /** Hold the clip at t (seconds) — the editor playhead, or seek() from outside. */
     pose(clip, t) {
@@ -74,11 +163,12 @@ class ClipsRuntime {
         if (inst) {
             inst.clip = clip;
             inst.time = time;
+            this.bump();
         }
         else {
             this.clips.set(clip.id, { clip, time, speed: 1, direction: 1, playing: false, order: ++this.order });
+            this.bumpState();
         }
-        this.bump();
     }
     /** The clip data changed (editor edit): keep time and play state, use the new tracks. */
     updateClip(clip) {
@@ -91,7 +181,7 @@ class ClipsRuntime {
         inst.clip = clip;
         inst.time = Math.min(inst.time, clip.duration);
         this.written.clear(); // values may have changed under the same time
-        this.bump();
+        this.bumpState();
     }
     getTime(clipId) { return this.clips.get(clipId)?.time ?? 0; }
     isPlaying(clipId) { return !!this.clips.get(clipId)?.playing; }
@@ -128,9 +218,16 @@ class ClipsRuntime {
             playing: true,
             order: ++this.order,
             active: existing?.active ?? new Set(),
+            cueState: existing?.cueState ?? new Map(),
+            owned: existing?.owned ?? new Set(),
+            waitUntil: opts.waitForTargets ? Date.now() + MAX_TARGET_WAIT_MS : undefined,
         });
+        this.dlog('playSequence', seq.name, {
+            id: seq.id, driven, driver: seq.driver, time, duration: schedule.duration, entries: schedule.entries.length,
+            steps: seq.steps.length, cues: schedule.cues.length, waitForTargets: !!opts.waitForTargets, replaced: !!existing,
+        }, this.caller());
         this.emit({ type: 'start', kind: 'sequence', id: seq.id });
-        this.bump();
+        this.bumpState();
     }
     // --- input drivers --------------------------------------------------------------
     /** Driven sequences that are running — what the input layer (ClipPlayer) feeds. */
@@ -194,28 +291,33 @@ class ClipsRuntime {
         const inst = this.sequences.get(seqId);
         if (!inst)
             return;
+        this.dlog('pauseSequence', inst.seq.name, this.caller());
         inst.playing = false;
-        this.bump();
+        this.bumpState();
     }
     resumeSequence(seqId) {
         const inst = this.sequences.get(seqId);
         if (!inst)
             return;
+        this.dlog('resumeSequence', inst.seq.name);
         inst.playing = true;
-        this.bump();
+        this.bumpState();
     }
     /** Stop and put every property the sequence drove back to its authored value. */
     stopSequence(seqId) {
         const inst = this.sequences.get(seqId);
         if (!inst)
             return;
+        this.dlog('stopSequence', inst.seq.name, this.caller());
         this.sequences.delete(seqId);
         inst.schedule.entries.forEach(e => this.pendingRestore.push(...e.clip.tracks));
-        this.bump();
+        this.releaseActions(inst);
+        this.bumpState();
     }
     /** Hold the sequence at T (sequence seconds) — the panel's scrub, or seek(). */
     poseSequence(seq, clips, T) {
         const inst = this.sequences.get(seq.id);
+        this.dlog('poseSequence', seq.name, { T, existing: !!inst, wasPlaying: !!inst?.playing }, this.caller());
         if (inst) {
             // Edited data goes through the re-resolve path (restores what the old schedule drove).
             if (inst.seq !== seq)
@@ -229,7 +331,10 @@ class ClipsRuntime {
             this.sequences.set(seq.id, {
                 seq, schedule, time, target: time, driven: false,
                 speed: 1, direction: 1, baseDirection: 1, playing: false, order: ++this.order, active: new Set(),
+                cueState: new Map(), owned: new Set(),
             });
+            this.bumpState();
+            return;
         }
         this.bump();
     }
@@ -238,6 +343,7 @@ class ClipsRuntime {
         const inst = this.sequences.get(seq.id);
         if (!inst)
             return;
+        this.dlog('updateSequence', seq.name, { playing: inst.playing, time: inst.time }, this.caller());
         // Restore everything the old schedule drove; whatever is still driven re-writes this frame.
         inst.schedule.entries.forEach(e => this.pendingRestore.push(...e.clip.tracks));
         inst.seq = seq;
@@ -248,7 +354,27 @@ class ClipsRuntime {
         if (inst.playing)
             inst.driven = isDriven(seq);
         inst.active = new Set();
-        this.bump();
+        this.bumpState();
+    }
+    /**
+     * Whether a PLAYING clip or sequence writes the camera right now. The player then
+     * holds OrbitControls off so its own update (damping, distance / angle limits,
+     * auto-rotate) doesn't fight the animation. A posed (paused) one doesn't count —
+     * in the editor you can still orbit around a held pose.
+     */
+    isDrivingCamera() {
+        const camera = (tracks) => tracks.some(t => t.state === 'camera' && !t.muted && t.keys.length > 0);
+        for (const inst of this.clips.values())
+            if (inst.playing && camera(inst.clip.tracks))
+                return true;
+        for (const inst of this.sequences.values()) {
+            if (!inst.playing)
+                continue;
+            for (const e of inst.schedule.entries)
+                if (inst.active.has(e.id) && camera(e.clip.tracks))
+                    return true;
+        }
+        return false;
     }
     getSequenceTime(seqId) { return this.sequences.get(seqId)?.time ?? 0; }
     getSequenceDuration(seqId) { return this.sequences.get(seqId)?.schedule.duration ?? 0; }
@@ -257,8 +383,11 @@ class ClipsRuntime {
     // --- frame ------------------------------------------------------------------
     tick(delta) {
         const ctx = this.ctx;
-        if (!ctx)
+        if (!ctx) {
+            if (this.sequences.size || this.clips.size)
+                this.dlogEvery('noctx', 1000, 'tick skipped: no context yet', { sequences: this.sequences.size });
             return;
+        }
         const dt = Math.min(delta, 0.1);
         let anyPlaying = false;
         for (const inst of this.clips.values()) {
@@ -271,7 +400,20 @@ class ClipsRuntime {
             if (!inst.playing)
                 continue;
             anyPlaying = true;
+            if (inst.waitUntil !== undefined) {
+                const missing = this.missingTargets(ctx, inst);
+                if (Date.now() < inst.waitUntil && missing.length) {
+                    this.dlogEvery(`wait:${inst.seq.id}`, 1000, 'waiting for targets', inst.seq.name, missing);
+                    continue; // hold at the start
+                }
+                this.dlog('wait over', inst.seq.name, missing.length ? { reason: 'timeout', stillMissing: missing } : { reason: 'all targets mounted' });
+                inst.waitUntil = undefined;
+            }
             this.advanceSequence(inst, dt);
+            this.dlogEvery(`adv:${inst.seq.id}`, 1000, 'playing', inst.seq.name, {
+                time: round2(inst.time), duration: round2(inst.schedule.duration), driven: inst.driven,
+                ...(inst.driven ? { target: round2(inst.target) } : {}), delta: round2(delta),
+            });
         }
         // Sequence entries that stopped writing (scrubbed back before their start, or
         // a 'restore' clip past its end) give their properties back.
@@ -289,12 +431,20 @@ class ClipsRuntime {
             }
             inst.active = now;
         }
+        // Cued actions: patches land before this frame's restores and writes read them.
+        // A sequence still waiting for its targets doesn't fire its cues yet — their
+        // effects would run on objects that aren't there (and never run again).
+        for (const inst of this.sequences.values()) {
+            if (inst.waitUntil === undefined)
+                this.syncCues(ctx, inst);
+        }
         if (this.pendingRestore.length)
             this.runRestores(ctx);
         // Proposals in priority order; the last one per property wins.
         const winners = new Map();
         for (const p of this.proposals())
             winners.set(targetKey(p.state, p.node, p.path), p);
+        const failed = [];
         for (const [key, p] of winners) {
             const json = JSON.stringify(p.value);
             if (this.written.get(key) === json)
@@ -303,10 +453,81 @@ class ClipsRuntime {
             // loading) is retried next frame instead of being skipped for good.
             if (applyValue(ctx, p.state, p.path, p.value, p.node))
                 this.written.set(key, json);
+            else if (this.debug)
+                failed.push(key);
         }
+        if (failed.length)
+            this.dlogEvery('failed', 1000, `writes not landed (${failed.length})`, failed.slice(0, 12));
         if (anyPlaying)
             this.bump();
     }
+    /** Objects / nodes the sequence animates — or its cued actions touch — that aren't in the scene yet. */
+    missingTargets(ctx, inst) {
+        const missing = new Set();
+        for (const e of inst.schedule.entries) {
+            for (const t of e.clip.tracks) {
+                if (t.muted || !t.keys.length)
+                    continue;
+                if (!isTargetMounted(ctx, t.state, t.node))
+                    missing.add(t.node ? `${t.state} › ${t.node}` : t.state);
+            }
+        }
+        if (ctx.getAction) {
+            for (const sc of inst.schedule.cues) {
+                const action = ctx.getAction(sc.cue.actionId);
+                if (!action)
+                    continue;
+                for (const t of action.targets ?? [])
+                    if (!isTargetMounted(ctx, t.state))
+                        missing.add(t.state);
+                for (const eff of action.effects ?? []) {
+                    for (const id of eff.targets ?? [])
+                        if (id !== 'self' && !isTargetMounted(ctx, id))
+                            missing.add(id);
+                }
+            }
+        }
+        return [...missing];
+    }
+    /** Apply / revert the actions whose cue state changed since the last tick. */
+    syncCues(ctx, inst) {
+        if (!ctx.getAction)
+            return;
+        const wanted = cueStatesAt(inst.schedule, inst.time);
+        const ids = new Set([...wanted.keys(), ...inst.cueState.keys()]);
+        for (const id of ids) {
+            const on = wanted.get(id) ?? false; // a removed cue counts as off
+            if ((inst.cueState.get(id) ?? false) === on) {
+                if (!wanted.has(id))
+                    inst.cueState.delete(id);
+                continue;
+            }
+            if (wanted.has(id))
+                inst.cueState.set(id, on);
+            else
+                inst.cueState.delete(id);
+            if (on) {
+                if (SceneActions.isActionApplied(id))
+                    continue; // someone else's — leave it
+                const action = ctx.getAction(id);
+                if (!action)
+                    continue;
+                SceneActions.applyAction(action, { effects: inst.playing });
+                inst.owned.add(id);
+            }
+            else if (inst.owned.has(id)) {
+                inst.owned.delete(id);
+                SceneActions.revertAction(id);
+            }
+        }
+    }
+    /** Revert every action the sequence applied (stop / close). */
+    releaseActions(inst) {
+        for (const id of inst.owned)
+            SceneActions.revertAction(id);
+        inst.owned.clear();
+        inst.cueState.clear();
+    }
     /** Every driver's values for this frame, lowest priority first. */
     *proposals() {
         const drivers = [];
@@ -391,6 +612,7 @@ class ClipsRuntime {
     }
     finishClip(inst) {
         inst.playing = false;
+        this.bumpState();
         this.emit({ type: 'end', kind: 'clip', id: inst.clip.id });
         if (inst.clip.endMode === 'restore')
             this.stop(inst.clip.id);
@@ -443,7 +665,9 @@ class ClipsRuntime {
         this.finishSequence(inst);
     }
     finishSequence(inst) {
+        this.dlog('finished', inst.seq.name, { time: inst.time, endMode: inst.seq.endMode });
         inst.playing = false;
+        this.bumpState();
         this.emit({ type: 'end', kind: 'sequence', id: inst.seq.id });
         if (inst.seq.endMode === 'restore')
             this.stopSequence(inst.seq.id);
@@ -460,7 +684,14 @@ class ClipsRuntime {
         this.version += 1;
         this.listeners.forEach(l => l());
     }
+    /** A state change: notifies both kinds of subscribers. */
+    bumpState() {
+        this.stateVersion += 1;
+        this.stateListeners.forEach(l => l());
+        this.bump();
+    }
 }
+const round2 = (n) => Math.round(n * 100) / 100;
 const isDriven = (seq) => !!seq.driver && seq.driver !== 'time';
 function* sampleTracks(tracks, t) {
     for (const track of tracks) {

package/dist/animationsV2/appliers.d.ts

@@ -1,3 +1,4 @@
+import type { ActionSequence } from '@3driseai/3drise-core';
 import type { PerspectiveCamera } from 'three';
 import type { KeyValue } from './types';
 export interface ApplyContext {
@@ -6,11 +7,15 @@ export interface ApplyContext {
     controls: any;
     /** Authored settings for an element (object id or 'camera'), action patches included. */
     getSettings: (state: string) => any;
+    /** Action definitions, for sequence cues. Without it cues are ignored. */
+    getAction?: (id: string) => ActionSequence | undefined;
 }
 export declare function clearApplierCaches(): void;
 /** Write one value. Unknown paths are ignored (the track picker never offers them). */
 /** Write one value to the live scene. False when its target is not mounted yet. */
 export declare function applyValue(ctx: ApplyContext, state: string, path: string, value: KeyValue, node?: string): boolean;
+/** Whether a track's target is in the scene yet (a model may still be loading). */
+export declare function isTargetMounted(ctx: ApplyContext, state: string, node?: string): boolean;
 /** Whether a (state, path) has an applier — used by the track picker. */
 export declare function isApplicable(state: string, path: string): boolean;
 //# sourceMappingURL=appliers.d.ts.map

package/dist/animationsV2/appliers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"appliers.d.ts","sourceRoot":"","sources":["../../src/animationsV2/appliers.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAc/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGxC,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,qDAAqD;IACrD,QAAQ,EAAE,GAAG,CAAC;IACd,yFAAyF;IACzF,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,GAAG,CAAC;CACrC;AAWD,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC;AAqKD,uFAAuF;AACvF,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAIlH;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE"}
+{"version":3,"file":"appliers.d.ts","sourceRoot":"","sources":["../../src/animationsV2/appliers.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAc/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGxC,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,qDAAqD;IACrD,QAAQ,EAAE,GAAG,CAAC;IACd,yFAAyF;IACzF,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,GAAG,CAAC;IACpC,0EAA0E;IAC1E,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,cAAc,GAAG,SAAS,CAAC;CACxD;AAWD,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC;AA2KD,uFAAuF;AACvF,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAIlH;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAKxF;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE"}

package/dist/animationsV2/appliers.js

@@ -4,7 +4,7 @@ import { CLOUD_LIVE_KEY } from '../hooks/useCloudLive.js';
 import { OCEAN_LIVE_KEY } from '../hooks/useOceanLive.js';
 import { TERRAIN_LIVE_KEY } from '../hooks/useTerrainLive.js';
 import { createSunPosition } from '../utils/utils3d.js';
-import { applyNodeValue, clearNodeCaches } from './nodeTracks.js';
+import { applyNodeValue, clearNodeCaches, nodesFor } from './nodeTracks.js';
 // --- live-target caches (cleared when the scene changes under us) -------------
 const objectCache = new Map();
 const handleCache = new Map();
@@ -53,10 +53,18 @@ const applyCamera = (ctx, _state, path, value) => {
     const cam = ctx.camera;
     if (!cam)
         return false;
+    const target = ctx.controls?.target;
     if (path === 'position') {
         const v = asVec3(value);
-        if (v)
-            cam.position.set(...v);
+        if (!v)
+            return;
+        cam.position.set(...v);
+        // Face the orbit target NOW: OrbitControls oriented the camera earlier this frame
+        // from the old position, so without this the view lags a frame behind and wobbles.
+        // With the controls switched off (authored), the camera keeps its own orientation.
+        const orbiting = ctx.getSettings('camera')?.controls?.enabled !== false;
+        if (target && orbiting)
+            cam.lookAt(target);
     }
     else if (path === 'fov' && typeof value === 'number') {
         cam.fov = value;
@@ -64,10 +72,10 @@ const applyCamera = (ctx, _state, path, value) => {
     }
     else if (path === 'controls.target') {
         const v = asVec3(value);
-        if (v && ctx.controls?.target) {
-            ctx.controls.target.set(...v);
-            ctx.controls.update?.();
-        }
+        if (!v || !target)
+            return false;
+        target.set(...v);
+        cam.lookAt(target);
     }
 };
 const applyTransform = (_ctx, state, path, value) => {
@@ -198,6 +206,16 @@ export function applyValue(ctx, state, path, value, node) {
     const entry = APPLIERS.find(a => a.match(state, path));
     return entry ? entry.apply(ctx, state, path, value) !== false : false;
 }
+/** Whether a track's target is in the scene yet (a model may still be loading). */
+export function isTargetMounted(ctx, state, node) {
+    if (state === 'camera')
+        return !!ctx.camera;
+    if (state === 'sky' || state === 'clouds' || state === 'ocean' || state === 'terrain')
+        return true;
+    if (node)
+        return nodesFor(state, node).length > 0;
+    return !!objectFor(state);
+}
 /** Whether a (state, path) has an applier — used by the track picker. */
 export function isApplicable(state, path) {
     return APPLIERS.some(a => a.match(state, path));

package/dist/animationsV2/index.d.ts

@@ -10,7 +10,7 @@ export type { ApplyContext } from './appliers';
 export { readNodeValue, NODE_TRANSFORM_PATHS, NODE_MATERIAL_KEYS } from './nodeTracks';
 export { resolveElementSettings, isEnvironmentState, ENVIRONMENT_STATES as CLIP_ENVIRONMENT_STATES } from './elementSettings';
 export type { ElementSources } from './elementSettings';
-export type { AnimationClip, Track as ClipTrack, Keyframe as ClipKeyframe, KeyValue as ClipKeyValue, EaseName as ClipEaseName, SequenceStep, StepClip, AnimationSequence as ClipSequence, SequenceDriver, SequenceDriverSettings, } from './types';
+export type { AnimationClip, Track as ClipTrack, Keyframe as ClipKeyframe, KeyValue as ClipKeyValue, EaseName as ClipEaseName, SequenceStep, StepClip, SequenceCue, AnimationSequence as ClipSequence, SequenceDriver, SequenceDriverSettings, } from './types';
 export { DEFAULT_DRIVER_SETTINGS } from './types';
 export { DEFAULT_EASE as CLIP_DEFAULT_EASE, FPS_PRESETS as CLIP_FPS_PRESETS } from './types';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/animationsV2/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvF,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,kBAAkB,IAAI,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC9H,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EACR,aAAa,EAAE,KAAK,IAAI,SAAS,EAAE,QAAQ,IAAI,YAAY,EAAE,QAAQ,IAAI,YAAY,EAAE,QAAQ,IAAI,YAAY,EAC/G,YAAY,EAAE,QAAQ,EAAE,iBAAiB,IAAI,YAAY,EAAE,cAAc,EAAE,sBAAsB,GACpG,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,YAAY,IAAI,iBAAiB,EAAE,WAAW,IAAI,gBAAgB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/animationsV2/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvF,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,kBAAkB,IAAI,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC9H,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EACR,aAAa,EAAE,KAAK,IAAI,SAAS,EAAE,QAAQ,IAAI,YAAY,EAAE,QAAQ,IAAI,YAAY,EAAE,QAAQ,IAAI,YAAY,EAC/G,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,IAAI,YAAY,EAAE,cAAc,EAAE,sBAAsB,GACjH,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,YAAY,IAAI,iBAAiB,EAAE,WAAW,IAAI,gBAAgB,EAAE,MAAM,SAAS,CAAC"}

package/dist/animationsV2/normalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/animationsV2/normalize.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAkB,MAAM,SAAS,CAAC;AAKhF,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,aAAa,CAarD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,iBAAiB,CAgC7D"}
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/animationsV2/normalize.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAkB,MAAM,SAAS,CAAC;AAQhF,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,aAAa,CAarD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,iBAAiB,CAyC7D"}

package/dist/animationsV2/normalize.js

@@ -1,5 +1,7 @@
 import { DEFAULT_DRIVER_SETTINGS } from './types.js';
 const DRIVERS = ['time', 'mouseWheel', 'mouseX', 'mouseY'];
+/** A stored flag: true / 1 / '1' / 'true' only — `!!'0'` would be true. */
+const flag = (v) => v === true || v === 1 || v === '1' || v === 'true';
 export function normalizeClip(row) {
     return {
         id: row.id,
@@ -8,8 +10,8 @@ export function normalizeClip(row) {
         description: row.description ?? undefined,
         duration: Number(row.duration) || 4,
         fps: Number(row.fps) || 30,
-        loop: !!row.loop,
-        yoyo: !!row.yoyo,
+        loop: flag(row.loop),
+        yoyo: flag(row.yoyo),
         endMode: row.endMode === 'restore' ? 'restore' : 'hold',
         tracks: Array.isArray(row.tracks) ? row.tracks : [],
     };
@@ -34,16 +36,25 @@ export function normalizeSequence(row) {
                 }))
                 : [],
         })),
-        loop: !!row.loop,
-        yoyo: !!row.yoyo,
-        reverse: !!row.reverse,
+        cues: (Array.isArray(row.cues) ? row.cues : [])
+            .filter((c) => c && typeof c.actionId === 'string' && typeof c.stepId === 'string')
+            .map((c, i) => ({
+            id: c.id ?? `cue-${i}`,
+            actionId: c.actionId,
+            stepId: c.stepId,
+            at: Math.max(0, Number(c.at) || 0),
+            mode: c.mode === 'revert' ? 'revert' : 'apply',
+        })),
+        loop: flag(row.loop),
+        yoyo: flag(row.yoyo),
+        reverse: flag(row.reverse),
         endMode: row.endMode === 'restore' ? 'restore' : 'hold',
         driver: DRIVERS.includes(row.driver) ? row.driver : 'time',
         driverSettings: {
             sensitivity: Number(row.driverSettings?.sensitivity) > 0 ? Number(row.driverSettings.sensitivity) : DEFAULT_DRIVER_SETTINGS.sensitivity,
             smoothing: Number(row.driverSettings?.smoothing) >= 0 ? Number(row.driverSettings.smoothing) : DEFAULT_DRIVER_SETTINGS.smoothing,
-            invert: !!row.driverSettings?.invert,
+            invert: flag(row.driverSettings?.invert),
         },
-        autoplay: !!row.autoplay,
+        autoplay: flag(row.autoplay),
     };
 }