@3driseai/3drise-viewer 0.1.25 → 0.1.27

package/dist/animationsV2/ClipsRuntime.js

@@ -0,0 +1,707 @@
+// =============================================================================
+// 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, isTargetMounted } from './appliers.js';
+import { restoreNodeTrack } from './nodeTracks.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();
+    sequences = new Map();
+    ctx = null;
+    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);
+        const direction = opts.reverse ? -1 : 1;
+        let time = opts.from ?? existing?.time ?? 0;
+        // Restart from the edge when playing past the end.
+        if (direction === 1 && time >= clip.duration)
+            time = 0;
+        if (direction === -1 && time <= 0)
+            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.bumpState();
+    }
+    pause(clipId) {
+        const inst = this.clips.get(clipId);
+        if (!inst)
+            return;
+        inst.playing = false;
+        this.bumpState();
+    }
+    resume(clipId) {
+        const inst = this.clips.get(clipId);
+        if (!inst)
+            return;
+        inst.playing = true;
+        this.bumpState();
+    }
+    /** Stop and put the clip's properties back to their authored values. */
+    stop(clipId) {
+        const inst = this.clips.get(clipId);
+        if (!inst)
+            return;
+        this.clips.delete(clipId);
+        this.pendingRestore.push(...inst.clip.tracks);
+        this.bumpState();
+    }
+    /** Hold the clip at t (seconds) — the editor playhead, or seek() from outside. */
+    pose(clip, t) {
+        const inst = this.clips.get(clip.id);
+        const time = Math.min(clip.duration, Math.max(0, t));
+        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();
+        }
+    }
+    /** The clip data changed (editor edit): keep time and play state, use the new tracks. */
+    updateClip(clip) {
+        const inst = this.clips.get(clip.id);
+        if (!inst)
+            return;
+        const removed = inst.clip.tracks.filter(t => !clip.tracks.some(n => n.id === t.id));
+        if (removed.length)
+            this.pendingRestore.push(...removed);
+        inst.clip = clip;
+        inst.time = Math.min(inst.time, clip.duration);
+        this.written.clear(); // values may have changed under the same time
+        this.bumpState();
+    }
+    getTime(clipId) { return this.clips.get(clipId)?.time ?? 0; }
+    isPlaying(clipId) { return !!this.clips.get(clipId)?.playing; }
+    isActive(clipId) { return this.clips.has(clipId); }
+    /** Value of a track at the clip's current time (the panel's value column). */
+    sampleAt(clip, track) {
+        return sampleTrack(track, this.getTime(clip.id));
+    }
+    // --- sequences ------------------------------------------------------------------
+    /**
+     * Play a sequence. `reverse` defaults to the sequence's own; `from` is sequence
+     * seconds (defaults to the current time, or the start edge of the run).
+     */
+    playSequence(seq, clips, opts = {}) {
+        const existing = this.sequences.get(seq.id);
+        const schedule = resolveSequence(seq, clips);
+        const direction = (opts.reverse ?? seq.reverse) ? -1 : 1;
+        const driven = isDriven(seq);
+        let time = opts.from ?? existing?.time ?? (direction === 1 ? 0 : schedule.duration);
+        // A played sequence restarts from its start edge; a driven one stays where it is.
+        if (!driven && direction === 1 && time >= schedule.duration)
+            time = 0;
+        if (!driven && direction === -1 && time <= 0)
+            time = schedule.duration;
+        this.sequences.set(seq.id, {
+            driven,
+            target: time,
+            seq,
+            schedule,
+            time,
+            speed: opts.speed ?? 1,
+            direction,
+            baseDirection: direction,
+            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.bumpState();
+    }
+    // --- input drivers --------------------------------------------------------------
+    /** Driven sequences that are running — what the input layer (ClipPlayer) feeds. */
+    getDrivenSequences() {
+        const out = [];
+        for (const inst of this.sequences.values()) {
+            if (!inst.driven || !inst.playing)
+                continue;
+            out.push({ id: inst.seq.id, driver: inst.seq.driver, settings: inst.seq.driverSettings, progress: this.progressOf(inst, inst.target) });
+        }
+        return out;
+    }
+    /**
+     * Set a sequence's position, 0–1 along its own direction (reverse flips it). A
+     * driven sequence eases there (its smoothing); any other is posed there at once.
+     */
+    setSequenceProgress(seqId, progress) {
+        const inst = this.sequences.get(seqId);
+        if (!inst)
+            return false;
+        const T = this.timeOf(inst, progress);
+        inst.target = T;
+        if (!inst.driven)
+            inst.time = T;
+        this.bump();
+        return true;
+    }
+    /**
+     * Move a driven sequence's target by `delta` of its length (the wheel). Returns
+     * false when it is already at that end — the caller then lets the event through
+     * (page scroll), so a visitor is never trapped inside the canvas.
+     */
+    nudgeSequenceProgress(seqId, delta) {
+        const inst = this.sequences.get(seqId);
+        if (!inst)
+            return false;
+        const p = this.progressOf(inst, inst.target);
+        const next = Math.min(1, Math.max(0, p + delta));
+        if (Math.abs(next - p) < 1e-6)
+            return false;
+        inst.target = this.timeOf(inst, next);
+        this.bump();
+        return true;
+    }
+    getSequenceProgress(seqId) {
+        const inst = this.sequences.get(seqId);
+        return inst ? this.progressOf(inst, inst.time) : 0;
+    }
+    progressOf(inst, T) {
+        const total = inst.schedule.duration;
+        if (total <= 0)
+            return 0;
+        const p = Math.min(1, Math.max(0, T / total));
+        return inst.seq.reverse ? 1 - p : p;
+    }
+    timeOf(inst, progress) {
+        const p = Math.min(1, Math.max(0, Number.isFinite(progress) ? progress : 0));
+        return (inst.seq.reverse ? 1 - p : p) * inst.schedule.duration;
+    }
+    pauseSequence(seqId) {
+        const inst = this.sequences.get(seqId);
+        if (!inst)
+            return;
+        this.dlog('pauseSequence', inst.seq.name, this.caller());
+        inst.playing = false;
+        this.bumpState();
+    }
+    resumeSequence(seqId) {
+        const inst = this.sequences.get(seqId);
+        if (!inst)
+            return;
+        this.dlog('resumeSequence', inst.seq.name);
+        inst.playing = true;
+        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.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)
+                this.updateSequence(seq, clips);
+            inst.time = Math.min(inst.schedule.duration, Math.max(0, T));
+            inst.target = inst.time;
+        }
+        else {
+            const schedule = resolveSequence(seq, clips);
+            const time = Math.min(schedule.duration, Math.max(0, T));
+            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();
+    }
+    /** The sequence or one of its clips changed: re-resolve, keep time and play state. */
+    updateSequence(seq, clips) {
+        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;
+        inst.schedule = resolveSequence(seq, clips);
+        inst.time = Math.min(inst.time, inst.schedule.duration);
+        inst.target = Math.min(inst.target, inst.schedule.duration);
+        // The driver can change while it runs (editing): a running sequence switches mode.
+        if (inst.playing)
+            inst.driven = isDriven(seq);
+        inst.active = new Set();
+        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; }
+    isSequencePlaying(seqId) { return !!this.sequences.get(seqId)?.playing; }
+    isSequenceActive(seqId) { return this.sequences.has(seqId); }
+    // --- frame ------------------------------------------------------------------
+    tick(delta) {
+        const ctx = this.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()) {
+            if (!inst.playing)
+                continue;
+            anyPlaying = true;
+            this.advanceClip(inst, dt);
+        }
+        for (const inst of [...this.sequences.values()]) {
+            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.
+        for (const inst of this.sequences.values()) {
+            const now = new Set();
+            for (const e of inst.schedule.entries)
+                if (isEntryActive(e, inst.time))
+                    now.add(e.id);
+            for (const id of inst.active) {
+                if (now.has(id))
+                    continue;
+                const e = inst.schedule.entries.find(x => x.id === id);
+                if (e)
+                    this.pendingRestore.push(...e.clip.tracks);
+            }
+            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)
+                continue;
+            // Recorded only when it landed: a target that is not mounted yet (a model still
+            // 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 = [];
+        for (const inst of this.clips.values()) {
+            drivers.push({ order: inst.order, run: () => sampleTracks(inst.clip.tracks, inst.time) });
+        }
+        for (const inst of this.sequences.values()) {
+            drivers.push({
+                order: inst.order,
+                run: function* () {
+                    for (const e of inst.schedule.entries) {
+                        if (!inst.active.has(e.id))
+                            continue;
+                        yield* sampleTracks(e.clip.tracks, entryLocalTime(e, inst.time));
+                    }
+                },
+            });
+        }
+        drivers.sort((a, b) => a.order - b.order);
+        for (const d of drivers)
+            yield* d.run();
+    }
+    runRestores(ctx) {
+        const tracks = this.pendingRestore;
+        this.pendingRestore = [];
+        const done = new Set();
+        for (const track of tracks) {
+            const key = targetKey(track.state, track.node, track.path);
+            if (done.has(key))
+                continue;
+            done.add(key);
+            this.written.delete(key);
+            if (track.node) {
+                // Node tracks restore their exact pre-animation snapshot (see nodeTracks).
+                const node = track.node;
+                restoreNodeTrack(track.state, node, track.path, (path) => this.isDriven(track.state, node, path));
+                continue;
+            }
+            // Another driver may still own this property; it re-writes this frame.
+            const authored = getAtPath(ctx.getSettings(track.state), track.path);
+            if (authored !== undefined)
+                applyValue(ctx, track.state, track.path, authored);
+        }
+    }
+    /** Whether any active driver still has a track on (state, node, path). */
+    isDriven(state, node, path) {
+        const hit = (t) => t.state === state && t.node === node && t.path === path && !t.muted;
+        for (const inst of this.clips.values())
+            if (inst.clip.tracks.some(hit))
+                return true;
+        for (const inst of this.sequences.values()) {
+            for (const e of inst.schedule.entries)
+                if (inst.active.has(e.id) && e.clip.tracks.some(hit))
+                    return true;
+        }
+        return false;
+    }
+    advanceClip(inst, delta) {
+        const { clip } = inst;
+        inst.time += delta * inst.speed * inst.direction;
+        const atEnd = inst.direction === 1 ? inst.time >= clip.duration : inst.time <= 0;
+        if (!atEnd)
+            return;
+        if (clip.yoyo) {
+            // Bounce at either edge. Without loop, stop after the return leg.
+            const returning = inst.direction === -1;
+            inst.time = inst.direction === 1 ? clip.duration : 0;
+            if (returning && !clip.loop)
+                return this.finishClip(inst);
+            inst.direction = inst.direction === 1 ? -1 : 1;
+            if (returning)
+                this.emit({ type: 'loop', kind: 'clip', id: clip.id });
+            return;
+        }
+        if (clip.loop) {
+            inst.time = inst.direction === 1 ? inst.time - clip.duration : inst.time + clip.duration;
+            this.emit({ type: 'loop', kind: 'clip', id: clip.id });
+            return;
+        }
+        inst.time = inst.direction === 1 ? clip.duration : 0;
+        this.finishClip(inst);
+    }
+    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);
+    }
+    /**
+     * Same edge rules as a clip, on the sequence clock. "Forward" is the run's base
+     * direction: a reversed run starts at the end and finishes at 0.
+     */
+    advanceSequence(inst, delta) {
+        const { seq } = inst;
+        const total = inst.schedule.duration;
+        if (inst.driven) {
+            // Ease toward the input's target. `smoothing` ≈ seconds to settle; 0 = exact.
+            const diff = inst.target - inst.time;
+            if (Math.abs(diff) < 1e-4) {
+                inst.time = inst.target;
+                return;
+            }
+            const smoothing = Math.max(0, seq.driverSettings?.smoothing ?? 0);
+            const k = smoothing <= 0 ? 1 : 1 - Math.exp(-delta * 4 / smoothing);
+            inst.time += diff * k;
+            return;
+        }
+        if (total <= 0) {
+            inst.time = 0;
+            return this.finishSequence(inst);
+        }
+        inst.time += delta * inst.speed * inst.direction;
+        const atEnd = inst.direction === 1 ? inst.time >= total : inst.time <= 0;
+        if (!atEnd)
+            return;
+        const edge = inst.direction === 1 ? total : 0;
+        const returning = inst.direction !== inst.baseDirection;
+        if (seq.yoyo) {
+            inst.time = edge;
+            if (returning && !seq.loop)
+                return this.finishSequence(inst);
+            inst.direction = inst.direction === 1 ? -1 : 1;
+            if (returning)
+                this.emit({ type: 'loop', kind: 'sequence', id: seq.id });
+            return;
+        }
+        if (seq.loop) {
+            // Jump back to the run's start edge. Entries past their window restore next tick.
+            inst.time = inst.direction === 1 ? inst.time - total : inst.time + total;
+            this.emit({ type: 'loop', kind: 'sequence', id: seq.id });
+            return;
+        }
+        inst.time = edge;
+        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);
+    }
+    emit(e) {
+        this.eventListeners.forEach(l => { try {
+            l(e);
+        }
+        catch (err) {
+            console.error('[ClipsRuntime] listener failed', err);
+        } });
+    }
+    bump() {
+        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) {
+        if (track.muted || track.keys.length === 0)
+            continue;
+        const value = sampleTrack(track, t);
+        if (value === undefined)
+            continue;
+        yield { state: track.state, node: track.node, path: track.path, value };
+    }
+}
+const clipsRuntime = new ClipsRuntime();
+export default clipsRuntime;