@3driseai/3drise-viewer 0.1.25 → 0.1.27

package/dist/animationsV2/nodeTracks.js

@@ -0,0 +1,165 @@
+// =============================================================================
+// Model-node tracks — animate one node inside a `model` (GLB) object.
+// =============================================================================
+//
+// A node is addressed by its ModelTree key (its name; ModelTree's selection mode is
+// name-only). A name matches the same node in every layout copy, so all matches
+// are written.
+//
+// Paths are node-relative and mirror a node override (config.nodeOverrides):
+// local transform, visibility, and the material tweak fields.
+//
+// Restore is exact rather than "authored": before the first write, the node's
+// current state is snapshotted (which already includes any saved node override,
+// applied by the viewer's useNodeOverrides), and a node's material is cloned so a
+// material shared across GLB meshes isn't changed for every mesh. Restore puts the
+// snapshot and the original materials back.
+//
+import { Color } from 'three';
+import { findById, findNodesByName, applySingleProperty } from '@3driseai/3drise-core';
+export const NODE_TRANSFORM_PATHS = ['position', 'rotation', 'scale', 'visible'];
+export const NODE_MATERIAL_KEYS = ['color', 'opacity', 'roughness', 'metalness', 'emissive', 'emissiveIntensity'];
+const CLIP_MATERIAL_KEY = '__clipOwnedMaterial';
+const nodeKey = (state, node) => `${state}|${node}`;
+const trackKey = (state, node, path) => `${state}|${node}|${path}`;
+/** original value per (state, node, path), captured before the first write */
+const snapshots = new Map();
+/** mesh -> its material(s) before we cloned them, per (state, node) */
+const originalMaterials = new Map();
+const nodeCache = new Map();
+export function clearNodeCaches() {
+    nodeCache.clear();
+}
+export function nodesFor(state, node) {
+    const key = nodeKey(state, node);
+    const cached = nodeCache.get(key);
+    if (cached && cached.length && cached.every(n => n.parent))
+        return cached;
+    const root = findById(state);
+    const found = root ? findNodesByName(root, node).filter((n) => n !== root) : [];
+    nodeCache.set(key, found);
+    return found;
+}
+const meshesUnder = (node) => {
+    const out = [];
+    node.traverse((c) => { if (c.isMesh && c.material)
+        out.push(c); });
+    return out;
+};
+const toHex = (c) => (c && typeof c.getHexString === 'function' ? `#${c.getHexString()}` : undefined);
+/** The node's current value for a node-relative path (first match), as a key value. */
+export function readNodeValue(state, node, path) {
+    const n = nodesFor(state, node)[0];
+    if (!n)
+        return undefined;
+    if (path === 'position')
+        return [n.position.x, n.position.y, n.position.z];
+    if (path === 'rotation')
+        return [n.rotation.x, n.rotation.y, n.rotation.z];
+    if (path === 'scale')
+        return [n.scale.x, n.scale.y, n.scale.z];
+    if (path === 'visible')
+        return !!n.visible;
+    if (path.startsWith('material.')) {
+        const key = path.slice('material.'.length);
+        const mesh = meshesUnder(n)[0];
+        const mat = mesh && (Array.isArray(mesh.material) ? mesh.material[0] : mesh.material);
+        if (!mat || !(key in mat))
+            return undefined;
+        const v = mat[key];
+        if (v instanceof Color || (v && v.isColor))
+            return toHex(v);
+        return typeof v === 'number' ? v : undefined;
+    }
+    return undefined;
+}
+/** Give each mesh under the node its own material (once), remembering the original. */
+function ownMaterials(state, node, n) {
+    const key = nodeKey(state, node);
+    const saved = originalMaterials.get(key) ?? [];
+    for (const mesh of meshesUnder(n)) {
+        const mats = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        if (mats.every((m) => m.userData?.[CLIP_MATERIAL_KEY]))
+            continue;
+        saved.push({ mesh, material: mesh.material });
+        const clones = mats.map((m) => {
+            const c = m.clone();
+            c.userData = { ...c.userData, [CLIP_MATERIAL_KEY]: true };
+            return c;
+        });
+        mesh.material = Array.isArray(mesh.material) ? clones : clones[0];
+    }
+    originalMaterials.set(key, saved);
+}
+export function applyNodeValue(state, node, path, value) {
+    const nodes = nodesFor(state, node);
+    if (!nodes.length)
+        return false;
+    const tk = trackKey(state, node, path);
+    if (!snapshots.has(tk)) {
+        const original = readNodeValue(state, node, path);
+        if (original !== undefined)
+            snapshots.set(tk, original);
+    }
+    for (const n of nodes) {
+        if (path === 'visible') {
+            n.visible = !!value;
+            continue;
+        }
+        if (path === 'position' || path === 'rotation' || path === 'scale') {
+            if (Array.isArray(value) && value.length >= 3)
+                n[path].set(Number(value[0]), Number(value[1]), Number(value[2]));
+            continue;
+        }
+        if (path.startsWith('material.')) {
+            ownMaterials(state, node, n);
+            const key = path.slice('material.'.length);
+            for (const mesh of meshesUnder(n)) {
+                const mats = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+                for (const mat of mats) {
+                    if (key === 'opacity' && typeof value === 'number')
+                        mat.transparent = value < 1;
+                    applySingleProperty(mat, key, value);
+                }
+            }
+        }
+    }
+    return true;
+}
+/** Put a node track back: its snapshot, and the node's original materials once no material track remains. */
+export function restoreNodeTrack(state, node, path, stillAnimated) {
+    const tk = trackKey(state, node, path);
+    const snap = snapshots.get(tk);
+    snapshots.delete(tk);
+    if (path.startsWith('material.')) {
+        const anyMaterialLeft = NODE_MATERIAL_KEYS.some(k => stillAnimated(`material.${k}`));
+        if (!anyMaterialLeft) {
+            const key = nodeKey(state, node);
+            for (const { mesh, material } of originalMaterials.get(key) ?? []) {
+                const current = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+                current.forEach((m) => m.userData?.[CLIP_MATERIAL_KEY] && m.dispose?.());
+                mesh.material = material;
+            }
+            originalMaterials.delete(key);
+            // snapshots of the other material keys of this node are now meaningless
+            NODE_MATERIAL_KEYS.forEach(k => snapshots.delete(trackKey(state, node, `material.${k}`)));
+            return;
+        }
+    }
+    if (snap !== undefined) {
+        for (const n of nodesFor(state, node)) {
+            if (path === 'visible')
+                n.visible = !!snap;
+            else if ((path === 'position' || path === 'rotation' || path === 'scale') && Array.isArray(snap)) {
+                n[path].set(Number(snap[0]), Number(snap[1]), Number(snap[2]));
+            }
+            else if (path.startsWith('material.')) {
+                const key = path.slice('material.'.length);
+                for (const mesh of meshesUnder(n)) {
+                    const mats = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+                    mats.forEach((m) => applySingleProperty(m, key, snap));
+                }
+            }
+        }
+    }
+}

package/dist/animationsV2/normalize.d.ts

@@ -0,0 +1,4 @@
+import type { AnimationClip, AnimationSequence } from './types';
+export declare function normalizeClip(row: any): AnimationClip;
+export declare function normalizeSequence(row: any): AnimationSequence;
+//# sourceMappingURL=normalize.d.ts.map

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

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

@@ -0,0 +1,60 @@
+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,
+        name: row.name ?? 'Clip',
+        key: row.key ?? '',
+        description: row.description ?? undefined,
+        duration: Number(row.duration) || 4,
+        fps: Number(row.fps) || 30,
+        loop: flag(row.loop),
+        yoyo: flag(row.yoyo),
+        endMode: row.endMode === 'restore' ? 'restore' : 'hold',
+        tracks: Array.isArray(row.tracks) ? row.tracks : [],
+    };
+}
+export function normalizeSequence(row) {
+    const steps = Array.isArray(row.steps) ? row.steps : [];
+    return {
+        id: row.id,
+        name: row.name ?? 'Sequence',
+        key: row.key ?? '',
+        description: row.description ?? undefined,
+        steps: steps.map((s, i) => ({
+            id: s?.id ?? `step-${i}`,
+            clips: Array.isArray(s?.clips)
+                ? s.clips
+                    .filter((c) => c && typeof c.clipId === 'string')
+                    .map((c, j) => ({
+                    id: c.id ?? `sc-${i}-${j}`,
+                    clipId: c.clipId,
+                    delay: Math.max(0, Number(c.delay) || 0),
+                    speed: Number(c.speed) > 0 ? Number(c.speed) : 1,
+                }))
+                : [],
+        })),
+        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: flag(row.driverSettings?.invert),
+        },
+        autoplay: flag(row.autoplay),
+    };
+}

package/dist/animationsV2/sequenceUtils.d.ts

@@ -0,0 +1,98 @@
+import type { AnimationClip, AnimationSequence, SequenceCue, StepClip } from './types';
+export interface ScheduledClip {
+    /** `${stepClip.id}` — stable across re-resolves of the same sequence. */
+    id: string;
+    stepIndex: number;
+    /** Row within the step. */
+    row: number;
+    stepClip: StepClip;
+    clip: AnimationClip;
+    /** Sequence seconds. */
+    start: number;
+    end: number;
+}
+export interface ScheduledCue {
+    cue: SequenceCue;
+    stepIndex: number;
+    /** Sequence seconds. */
+    time: number;
+}
+export interface SequenceSchedule {
+    /** In priority order (schedule index = activation order). */
+    entries: ScheduledClip[];
+    steps: {
+        start: number;
+        end: number;
+    }[];
+    /** Sorted by time (authored order breaks ties). Cues on a missing step are dropped. */
+    cues: ScheduledCue[];
+    duration: number;
+}
+export type ClipLookup = ReadonlyMap<string, AnimationClip> | ((id: string) => AnimationClip | undefined);
+export declare const clipMap: (clips: readonly AnimationClip[]) => Map<string, AnimationClip>;
+/** Step clips whose clip is missing (deleted, not loaded) are skipped. */
+export declare function resolveSequence(seq: AnimationSequence, clips: ClipLookup): SequenceSchedule;
+/** Every cued action's state at sequence time T: on when its last cue at or before T is 'apply'. */
+export declare function cueStatesAt(schedule: SequenceSchedule, T: number): Map<string, boolean>;
+/**
+ * Where sequence time T sits, as a cue anchor: the step it falls in (a boundary
+ * belongs to the step that starts there) and the offset into it.
+ */
+export declare function anchorAt(seq: AnimationSequence, schedule: SequenceSchedule, T: number): {
+    stepId: string;
+    at: number;
+} | null;
+/** On / off spans of one action along the sequence (for drawing). */
+export declare function cueSpans(schedule: SequenceSchedule, actionId: string): Array<{
+    from: number;
+    to: number;
+}>;
+export interface CueConflict {
+    cue: SequenceCue;
+    /** The clip whose track animates a property the action patches. */
+    clip: AnimationClip;
+    state: string;
+    path: string;
+}
+/**
+ * 'apply' cues whose action patches a property that a clip of the same step
+ * animates — the clip writes over the patch while it runs.
+ */
+export declare function findCueConflicts(seq: AnimationSequence, clips: ClipLookup, getAction: (id: string) => {
+    targets?: Array<{
+        state: string;
+        patch: any;
+    }>;
+} | undefined): CueConflict[];
+export declare function newCue(actionId: string, stepId: string, at: number, mode?: SequenceCue['mode']): SequenceCue;
+/** Clip-local time (seconds, 0..clip.duration) of an entry at sequence time T. */
+export declare function entryLocalTime(entry: ScheduledClip, T: number): number;
+/**
+ * Whether an entry writes at sequence time T: from its start on, and after its end
+ * only if its clip holds ('hold'); a 'restore' clip lets go at its end.
+ */
+export declare function isEntryActive(entry: ScheduledClip, T: number): boolean;
+export interface StepConflict {
+    stepIndex: number;
+    /** The upper row — its animation is hidden while the other drives the property. */
+    masked: StepClip;
+    /** The lower row — it wins. */
+    winner: StepClip;
+    state: string;
+    node?: string;
+    path: string;
+}
+/**
+ * Same-step clips that drive the same property at the same time. A pair conflicts
+ * when the upper row is still ANIMATING while the lower row is active (animating,
+ * or holding its end value) — then the lower row hides it. An upper row that only
+ * holds under a lower one animating is the expected override, not a conflict.
+ */
+export declare function findSequenceConflicts(seq: AnimationSequence, clips: ClipLookup): StepConflict[];
+/** Step-clip ids involved in any conflict (row markers). */
+export declare function conflictedStepClipIds(conflicts: readonly StepConflict[]): Set<string>;
+export declare function newSequence(name: string, key: string): AnimationSequence;
+export declare function newStepClip(clipId: string): StepClip;
+/** Deep copy with fresh ids (duplicate). */
+export declare function cloneSequence(seq: AnimationSequence, name: string, key: string): AnimationSequence;
+//# sourceMappingURL=sequenceUtils.d.ts.map

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

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

package/dist/animationsV2/sequenceUtils.js

@@ -0,0 +1,220 @@
+import { DEFAULT_DRIVER_SETTINGS } from './types.js';
+import { uid } from './clipUtils.js';
+const lookup = (clips, id) => (typeof clips === 'function' ? clips(id) : clips.get(id));
+export const clipMap = (clips) => new Map(clips.map(c => [c.id, c]));
+const safeSpeed = (s) => (Number.isFinite(s) && s > 0 ? s : 1);
+const safeDelay = (d) => (Number.isFinite(d) && d > 0 ? d : 0);
+/** Step clips whose clip is missing (deleted, not loaded) are skipped. */
+export function resolveSequence(seq, clips) {
+    const entries = [];
+    const steps = [];
+    let cursor = 0;
+    seq.steps.forEach((step, stepIndex) => {
+        const stepStart = cursor;
+        let stepEnd = stepStart;
+        step.clips.forEach((stepClip, row) => {
+            const clip = lookup(clips, stepClip.clipId);
+            if (!clip)
+                return;
+            const start = stepStart + safeDelay(stepClip.delay);
+            const end = start + Math.max(0, clip.duration) / safeSpeed(stepClip.speed);
+            entries.push({ id: stepClip.id, stepIndex, row, stepClip, clip, start, end });
+            stepEnd = Math.max(stepEnd, end);
+        });
+        steps.push({ start: stepStart, end: stepEnd });
+        cursor = stepEnd;
+    });
+    const stepIndexById = new Map(seq.steps.map((s, i) => [s.id, i]));
+    const cues = [];
+    (seq.cues ?? []).forEach((cue) => {
+        const stepIndex = stepIndexById.get(cue.stepId);
+        if (stepIndex === undefined)
+            return;
+        const time = Math.min(cursor, steps[stepIndex].start + safeDelay(cue.at));
+        cues.push({ cue, stepIndex, time });
+    });
+    cues.sort((a, b) => a.time - b.time); // stable: authored order breaks ties
+    return { entries, steps, cues, duration: cursor };
+}
+// --- cues (actions) ----------------------------------------------------------------
+/** Every cued action's state at sequence time T: on when its last cue at or before T is 'apply'. */
+export function cueStatesAt(schedule, T) {
+    const out = new Map();
+    for (const c of schedule.cues) {
+        if (!out.has(c.cue.actionId))
+            out.set(c.cue.actionId, false);
+        if (c.time <= T + 1e-9)
+            out.set(c.cue.actionId, c.cue.mode === 'apply');
+    }
+    return out;
+}
+/**
+ * Where sequence time T sits, as a cue anchor: the step it falls in (a boundary
+ * belongs to the step that starts there) and the offset into it.
+ */
+export function anchorAt(seq, schedule, T) {
+    if (!seq.steps.length)
+        return null;
+    let index = 0;
+    schedule.steps.forEach((s, i) => { if (T >= s.start - 1e-9)
+        index = i; });
+    const start = schedule.steps[index]?.start ?? 0;
+    return { stepId: seq.steps[index].id, at: Math.max(0, T - start) };
+}
+/** On / off spans of one action along the sequence (for drawing). */
+export function cueSpans(schedule, actionId) {
+    const spans = [];
+    let onAt = null;
+    for (const c of schedule.cues) {
+        if (c.cue.actionId !== actionId)
+            continue;
+        if (c.cue.mode === 'apply' && onAt === null)
+            onAt = c.time;
+        else if (c.cue.mode === 'revert' && onAt !== null) {
+            spans.push({ from: onAt, to: c.time });
+            onAt = null;
+        }
+    }
+    if (onAt !== null)
+        spans.push({ from: onAt, to: schedule.duration });
+    return spans;
+}
+/** Leaf paths of a patch ('meshSettings.position', 'config.intensity'…); arrays are leaves. */
+function patchPaths(patch, prefix = '') {
+    if (!patch || typeof patch !== 'object' || Array.isArray(patch))
+        return prefix ? [prefix] : [];
+    return Object.entries(patch).flatMap(([k, v]) => patchPaths(v, prefix ? `${prefix}.${k}` : k));
+}
+const overlapsPath = (a, b) => a === b || a.startsWith(`${b}.`) || b.startsWith(`${a}.`);
+/**
+ * 'apply' cues whose action patches a property that a clip of the same step
+ * animates — the clip writes over the patch while it runs.
+ */
+export function findCueConflicts(seq, clips, getAction) {
+    const schedule = resolveSequence(seq, clips);
+    const out = [];
+    for (const sc of schedule.cues) {
+        if (sc.cue.mode !== 'apply')
+            continue;
+        const action = getAction(sc.cue.actionId);
+        if (!action?.targets?.length)
+            continue;
+        const entries = schedule.entries.filter(e => e.stepIndex === sc.stepIndex);
+        for (const target of action.targets) {
+            const paths = patchPaths(target.patch);
+            for (const e of entries) {
+                for (const track of e.clip.tracks) {
+                    if (track.muted || track.node || track.state !== target.state || !track.keys.length)
+                        continue;
+                    if (paths.some(p => overlapsPath(p, track.path)))
+                        out.push({ cue: sc.cue, clip: e.clip, state: track.state, path: track.path });
+                }
+            }
+        }
+    }
+    return out;
+}
+export function newCue(actionId, stepId, at, mode = 'apply') {
+    return { id: uid('cue'), actionId, stepId, at: Math.max(0, at), mode };
+}
+/** Clip-local time (seconds, 0..clip.duration) of an entry at sequence time T. */
+export function entryLocalTime(entry, T) {
+    const local = (T - entry.start) * safeSpeed(entry.stepClip.speed);
+    return Math.min(entry.clip.duration, Math.max(0, local));
+}
+/**
+ * Whether an entry writes at sequence time T: from its start on, and after its end
+ * only if its clip holds ('hold'); a 'restore' clip lets go at its end.
+ */
+export function isEntryActive(entry, T) {
+    if (T < entry.start)
+        return false;
+    return T <= entry.end || entry.clip.endMode !== 'restore';
+}
+const targetKey = (state, node, path) => `${state}|${node ?? ''}|${path}`;
+/**
+ * Same-step clips that drive the same property at the same time. A pair conflicts
+ * when the upper row is still ANIMATING while the lower row is active (animating,
+ * or holding its end value) — then the lower row hides it. An upper row that only
+ * holds under a lower one animating is the expected override, not a conflict.
+ */
+export function findSequenceConflicts(seq, clips) {
+    const { entries } = resolveSequence(seq, clips);
+    const out = [];
+    const byStep = new Map();
+    entries.forEach(e => {
+        const list = byStep.get(e.stepIndex) ?? [];
+        list.push(e);
+        byStep.set(e.stepIndex, list);
+    });
+    for (const [stepIndex, list] of byStep) {
+        for (let i = 0; i < list.length; i++) {
+            const upper = list[i];
+            if (upper.end <= upper.start)
+                continue; // nothing animates
+            const upperTargets = new Map();
+            upper.clip.tracks.forEach(t => {
+                if (!t.muted && t.keys.length)
+                    upperTargets.set(targetKey(t.state, t.node, t.path), t);
+            });
+            if (!upperTargets.size)
+                continue;
+            for (let j = i + 1; j < list.length; j++) {
+                const lower = list[j];
+                const lowerEnd = lower.clip.endMode === 'restore' ? lower.end : Infinity;
+                const overlaps = upper.start < lowerEnd && lower.start < upper.end;
+                if (!overlaps)
+                    continue;
+                const seen = new Set();
+                lower.clip.tracks.forEach(t => {
+                    if (t.muted || !t.keys.length)
+                        return;
+                    const k = targetKey(t.state, t.node, t.path);
+                    const hit = upperTargets.get(k);
+                    if (!hit || seen.has(k))
+                        return;
+                    seen.add(k);
+                    out.push({ stepIndex, masked: upper.stepClip, winner: lower.stepClip, state: hit.state, node: hit.node, path: hit.path });
+                });
+            }
+        }
+    }
+    return out;
+}
+/** Step-clip ids involved in any conflict (row markers). */
+export function conflictedStepClipIds(conflicts) {
+    const ids = new Set();
+    conflicts.forEach(c => { ids.add(c.masked.id); ids.add(c.winner.id); });
+    return ids;
+}
+// --- builders ----------------------------------------------------------------------
+export function newSequence(name, key) {
+    return {
+        id: uid('seq'), name, key, steps: [{ id: uid('step'), clips: [] }], cues: [],
+        loop: false, yoyo: false, reverse: false, endMode: 'hold',
+        driver: 'time', driverSettings: { ...DEFAULT_DRIVER_SETTINGS }, autoplay: false,
+    };
+}
+export function newStepClip(clipId) {
+    return { id: uid('sc'), clipId, delay: 0, speed: 1 };
+}
+/** Deep copy with fresh ids (duplicate). */
+export function cloneSequence(seq, name, key) {
+    return {
+        ...seq,
+        id: uid('seq'),
+        name,
+        key,
+        isDirty: undefined,
+        ...(() => {
+            // Fresh step ids — cues follow their step to the copy.
+            const stepIds = new Map(seq.steps.map(s => [s.id, uid('step')]));
+            return {
+                steps: seq.steps.map(s => ({ id: stepIds.get(s.id), clips: s.clips.map(c => ({ ...c, id: uid('sc') })) })),
+                cues: (seq.cues ?? [])
+                    .filter(c => stepIds.has(c.stepId))
+                    .map(c => ({ ...c, id: uid('cue'), stepId: stepIds.get(c.stepId) })),
+            };
+        })(),
+    };
+}

package/dist/animationsV2/types.d.ts

@@ -0,0 +1,115 @@
+/** Easing of the segment leaving a key. Names match core's easingUtils, plus 'step'. */
+export type EaseName = 'linear' | 'step' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | 'easeInQuart' | 'easeOutQuart' | 'easeInOutQuart' | 'easeInSine' | 'easeOutSine' | 'easeInOutSine' | 'easeInExpo' | 'easeOutExpo' | 'easeInOutExpo' | 'easeInBack' | 'easeOutBack' | 'easeInOutBack' | 'easeOutElastic' | 'easeOutBounce';
+export type KeyValue = number | number[] | string | boolean;
+export interface Keyframe {
+    /** Stable within the track — selection and drag follow it, not the index. */
+    id: string;
+    /** Seconds from clip start. */
+    t: number;
+    value: KeyValue;
+    /** Easing of the segment LEAVING this key. */
+    ease?: EaseName;
+}
+export interface Track {
+    id: string;
+    /** Object id, or 'camera'. (sky / clouds / ocean come later.) */
+    state: string;
+    /**
+     * A node inside a `model` object (its ModelTree key: the node name). When set,
+     * `path` is relative to that node: 'position' | 'rotation' | 'scale' | 'visible' |
+     * 'material.<color|opacity|roughness|metalness|emissive|emissiveIntensity>' —
+     * the same fields a node override (config.nodeOverrides) carries.
+     */
+    node?: string;
+    /** Settings path on that element ('meshSettings.position', 'materialSettings.opacity', 'config.intensity'…), or node-relative when `node` is set. */
+    path: string;
+    /** Sorted by t. */
+    keys: Keyframe[];
+    muted?: boolean;
+}
+export interface AnimationClip {
+    id: string;
+    name: string;
+    key: string;
+    description?: string;
+    /** Seconds. */
+    duration: number;
+    /** Timeline frame rate — display and snapping only; playback samples real time. */
+    fps: number;
+    loop: boolean;
+    yoyo: boolean;
+    /** When a non-looping clip finishes: keep the last values, or return to authored. */
+    endMode: 'hold' | 'restore';
+    tracks: Track[];
+    /** Unsaved changes (save bookkeeping, never sent). */
+    isDirty?: boolean;
+}
+/** One clip inside a step. Plays once, forward — loop / yoyo / reverse are the sequence's. */
+export interface StepClip {
+    id: string;
+    /** AnimationClip id. */
+    clipId: string;
+    /** Seconds after the step starts (>= 0). */
+    delay: number;
+    /** 1 = authored speed. */
+    speed: number;
+}
+/** Clips that start together. The step ends when its longest clip ends; then the next step starts. */
+export interface SequenceStep {
+    id: string;
+    clips: StepClip[];
+}
+/**
+ * An action switched at a moment of the sequence. Anchored to a step (not absolute
+ * time), so retiming clips or reordering steps keeps it on the moment it was put on.
+ *
+ * Cues are STATE, not events: at sequence time T an action is on when its last cue
+ * at or before T is 'apply' (off when 'revert', or when it has no cue yet). So
+ * scrubbing, reverse, yoyo, loop and input drivers all land on the same scene.
+ */
+export interface SequenceCue {
+    id: string;
+    /** ActionSequence id. */
+    actionId: string;
+    /** Step it is anchored to. */
+    stepId: string;
+    /** Seconds after that step starts (>= 0). */
+    at: number;
+    mode: 'apply' | 'revert';
+}
+/** What moves a sequence's clock: time (it plays), or an input that scrubs it. */
+export type SequenceDriver = 'time' | 'mouseWheel' | 'mouseX' | 'mouseY';
+export interface SequenceDriverSettings {
+    /** mouseWheel: progress per wheel pixel is sensitivity / 1000 (1 ≈ one long scroll for the whole sequence). */
+    sensitivity: number;
+    /** 0 = follows the input exactly; higher = eases toward it (≈ seconds to settle). */
+    smoothing: number;
+    /** Flip the direction: right-to-left, bottom-to-top, wheel up = forward. */
+    invert: boolean;
+}
+export declare const DEFAULT_DRIVER_SETTINGS: SequenceDriverSettings;
+export interface AnimationSequence {
+    id: string;
+    name: string;
+    key: string;
+    description?: string;
+    /** Run in order. */
+    steps: SequenceStep[];
+    /** Actions switched on / off along the sequence. */
+    cues: SequenceCue[];
+    /** Whole-sequence playback. */
+    loop: boolean;
+    yoyo: boolean;
+    reverse: boolean;
+    endMode: 'hold' | 'restore';
+    /** What moves the clock. Input drivers scrub the sequence instead of playing it. */
+    driver: SequenceDriver;
+    driverSettings: SequenceDriverSettings;
+    /** Start when the project loads (published viewer; the studio never autoplays). */
+    autoplay: boolean;
+    /** Unsaved changes (save bookkeeping, never sent). */
+    isDirty?: boolean;
+}
+export declare const DEFAULT_EASE: EaseName;
+export declare const FPS_PRESETS: readonly [24, 25, 30, 60];
+//# sourceMappingURL=types.d.ts.map