@3driseai/3drise-viewer 0.1.25 → 0.1.26

package/dist/animationsV2/appliers.js

@@ -0,0 +1,204 @@
+import { findById, SceneStore, applySingleProperty, applyMaterialPropertyToObject, traverseSkippingEdgesAndEffects, EDGES_GROUP_KEY, } from '@3driseai/3drise-core';
+import { CONFIG_LIVE_KEY } from '../hooks/useConfigLive.js';
+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';
+// --- live-target caches (cleared when the scene changes under us) -------------
+const objectCache = new Map();
+const handleCache = new Map();
+export function clearApplierCaches() {
+    objectCache.clear();
+    handleCache.clear();
+    clearNodeCaches();
+}
+function objectFor(state) {
+    const cached = objectCache.get(state);
+    if (cached && cached.parent)
+        return cached;
+    const found = findById(state);
+    if (found)
+        objectCache.set(state, found);
+    else
+        objectCache.delete(state);
+    return found;
+}
+function configHandleFor(state) {
+    const cached = handleCache.get(state);
+    if (cached && cached.alive)
+        return cached;
+    let found = null;
+    SceneStore.scene?.traverse((o) => {
+        if (found)
+            return;
+        const h = o.userData?.[CONFIG_LIVE_KEY];
+        if (h && h.alive && h.id === state)
+            found = h;
+    });
+    if (found)
+        handleCache.set(state, found);
+    else
+        handleCache.delete(state);
+    return found;
+}
+function edgesGroupOf(obj) {
+    for (const child of obj.children)
+        if (child.userData?.[EDGES_GROUP_KEY])
+            return child;
+    return null;
+}
+const asVec3 = (v) => Array.isArray(v) && v.length >= 3 ? [Number(v[0]), Number(v[1]), Number(v[2])] : null;
+const applyCamera = (ctx, _state, path, value) => {
+    const cam = ctx.camera;
+    if (!cam)
+        return false;
+    if (path === 'position') {
+        const v = asVec3(value);
+        if (v)
+            cam.position.set(...v);
+    }
+    else if (path === 'fov' && typeof value === 'number') {
+        cam.fov = value;
+        cam.updateProjectionMatrix();
+    }
+    else if (path === 'controls.target') {
+        const v = asVec3(value);
+        if (v && ctx.controls?.target) {
+            ctx.controls.target.set(...v);
+            ctx.controls.update?.();
+        }
+    }
+};
+const applyTransform = (_ctx, state, path, value) => {
+    const obj = objectFor(state);
+    if (!obj)
+        return false;
+    const prop = path.slice('meshSettings.'.length);
+    if (prop === 'visible') {
+        obj.visible = !!value;
+        return;
+    }
+    const v = asVec3(value);
+    if (!v)
+        return false;
+    if (prop === 'position')
+        obj.position.set(...v);
+    else if (prop === 'rotation')
+        obj.rotation.set(...v);
+    else if (prop === 'scale')
+        obj.scale.set(...v);
+};
+const applyMaterial = (_ctx, state, path, value) => {
+    const obj = objectFor(state);
+    if (!obj)
+        return false;
+    const key = path.slice('materialSettings.'.length);
+    traverseSkippingEdgesAndEffects(obj, true, (node) => {
+        if (!node.material)
+            return;
+        const mats = Array.isArray(node.material) ? node.material : [node.material];
+        for (const mat of mats) {
+            if (key === 'opacity' && typeof value === 'number' && 'transparent' in mat)
+                mat.transparent = value < 1;
+            applySingleProperty(mat, key, value);
+        }
+    });
+};
+const applyEdgesMaterial = (_ctx, state, path, value) => {
+    const obj = objectFor(state);
+    const edges = obj && edgesGroupOf(obj);
+    if (!edges)
+        return false;
+    applyMaterialPropertyToObject(edges, path.slice('edgesSettings.materialSettings.'.length), value);
+};
+const applyConfig = (_ctx, state, path, value) => {
+    const handle = configHandleFor(state);
+    if (!handle)
+        return false;
+    if (typeof value === 'number' || typeof value === 'string' || typeof value === 'boolean') {
+        handle.set(path.slice('config.'.length), value);
+    }
+};
+// --- environment: the same live paths the controllers' sliders use -------------------
+/** Sky: the sky mesh's shader uniforms (what useSkyUniforms.updateUniforms writes). */
+const SKY_UNIFORM_KEYS = new Set(['turbidity', 'rayleigh', 'mieCoefficient', 'mieDirectionalG']);
+const applySky = (_ctx, _state, path, value) => {
+    if (typeof value !== 'number')
+        return;
+    const sky = objectFor('3drise-sky');
+    const uniforms = sky?.material?.uniforms;
+    if (!uniforms)
+        return false;
+    if (SKY_UNIFORM_KEYS.has(path)) {
+        if (uniforms[path])
+            uniforms[path].value = value;
+        return;
+    }
+    if ((path === 'elevation' || path === 'azimuth') && uniforms.sunPosition) {
+        // The other angle comes from the current sun, so the two can be keyed separately.
+        const { x, y, z } = uniforms.sunPosition.value;
+        const r = Math.sqrt(x * x + y * y + z * z) || 1;
+        const current = { elevation: 90 - Math.acos(y / r) * (180 / Math.PI), azimuth: Math.atan2(z, x) * (180 / Math.PI) };
+        const elevation = path === 'elevation' ? value : current.elevation;
+        const azimuth = path === 'azimuth' ? value : current.azimuth;
+        uniforms.sunPosition.value.copy(createSunPosition(elevation, azimuth));
+    }
+};
+/** Clouds: the layer's live handle — `config.*` is the deck, `cirrus.*` the high layer. */
+const applyClouds = (ctx, _state, path, value) => {
+    if (typeof value !== 'number' && typeof value !== 'boolean' && typeof value !== 'string')
+        return;
+    const id = ctx.getSettings('clouds')?.id;
+    const handle = id ? objectFor(id)?.userData?.[CLOUD_LIVE_KEY] : undefined;
+    if (!handle)
+        return false;
+    if (path.startsWith('config.'))
+        handle.deck(path.slice('config.'.length), value);
+    else if (path.startsWith('cirrus.'))
+        handle.cirrus(path.slice('cirrus.'.length), value);
+};
+/** Ocean: the world ocean's live handle — `config.*`. */
+const applyOcean = (ctx, _state, path, value) => {
+    if (typeof value !== 'number' && typeof value !== 'boolean' && typeof value !== 'string')
+        return;
+    const id = ctx.getSettings('ocean')?.id;
+    const handle = id ? objectFor(id)?.userData?.[OCEAN_LIVE_KEY] : undefined;
+    if (!handle || !path.startsWith('config.'))
+        return false;
+    handle.config(path.slice('config.'.length), value);
+};
+/** Procedural terrain: its live handle — `config.*`. */
+const applyTerrain = (ctx, _state, path, value) => {
+    if (typeof value !== 'number' && typeof value !== 'boolean' && typeof value !== 'string')
+        return;
+    const id = ctx.getSettings('terrain')?.id;
+    const handle = id ? objectFor(id)?.userData?.[TERRAIN_LIVE_KEY] : undefined;
+    if (!handle || !path.startsWith('config.'))
+        return false;
+    handle.config(path.slice('config.'.length), value);
+};
+const APPLIERS = [
+    { match: (s) => s === 'camera', apply: applyCamera },
+    // Environment before the generic path families: the ocean's `config.*` is not an object's.
+    { match: (s) => s === 'sky', apply: applySky },
+    { match: (s) => s === 'clouds', apply: applyClouds },
+    { match: (s) => s === 'ocean', apply: applyOcean },
+    { match: (s) => s === 'terrain', apply: applyTerrain },
+    { match: (_s, p) => p.startsWith('meshSettings.'), apply: applyTransform },
+    { match: (_s, p) => p.startsWith('materialSettings.'), apply: applyMaterial },
+    { match: (_s, p) => p.startsWith('edgesSettings.materialSettings.'), apply: applyEdgesMaterial },
+    { match: (_s, p) => p.startsWith('config.'), apply: applyConfig },
+];
+/** 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 function applyValue(ctx, state, path, value, node) {
+    if (node)
+        return applyNodeValue(state, node, path, value);
+    const entry = APPLIERS.find(a => a.match(state, path));
+    return entry ? entry.apply(ctx, state, path, value) !== false : false;
+}
+/** 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/clipUtils.d.ts

@@ -0,0 +1,33 @@
+import type { AnimationClip, EaseName, Keyframe, KeyValue, Track } from './types';
+export declare const uid: (prefix: string) => string;
+/** Read a dotted settings path ('materialSettings.opacity') from a settings object. */
+export declare function getAtPath(obj: any, path: string): any;
+export declare const secondsToFrame: (t: number, fps: number) => number;
+export declare const frameToSeconds: (frame: number, fps: number) => number;
+export declare const snapToFrame: (t: number, fps: number) => number;
+/** 'SS:FF' timecode (minutes folded into seconds past 59 — clips are short). */
+export declare function timecode(t: number, fps: number): string;
+export declare function easeProgress(ease: EaseName | undefined, p: number): number;
+/**
+ * The track's value at time t. Before the first key: the first key's value;
+ * after the last: the last key's value. Keys must be sorted by t.
+ */
+export declare function sampleTrack(track: Track, t: number): KeyValue | undefined;
+export declare const sortKeys: (keys: Keyframe[]) => Keyframe[];
+/** Add a key at t, or replace the value of a key already on that frame. */
+export declare function upsertKey(track: Track, t: number, value: KeyValue, fps: number): Track;
+/** Move keys by dt seconds, clamped to [0, duration], snapped to frames unless `free`. */
+export declare function moveKeys(clip: AnimationClip, selection: Set<string>, dt: number, free: boolean): AnimationClip;
+export declare function deleteKeys(clip: AnimationClip, selection: Set<string>): AnimationClip;
+export declare function setKeysEase(clip: AnimationClip, selection: Set<string>, ease: EaseName): AnimationClip;
+export declare function setKeyValue(clip: AnimationClip, keyId: string, value: KeyValue): AnimationClip;
+export declare function findKey(clip: AnimationClip, keyId: string): {
+    track: Track;
+    key: Keyframe;
+} | undefined;
+/** All key times of the clip, sorted and unique (for Shift+←/→). */
+export declare function allKeyTimes(clip: AnimationClip): number[];
+export declare function newClip(name: string, key: string): AnimationClip;
+/** Deep copy with fresh ids (duplicate). */
+export declare function cloneClip(clip: AnimationClip, name: string, key: string): AnimationClip;
+//# sourceMappingURL=clipUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"clipUtils.d.ts","sourceRoot":"","sources":["../../src/animationsV2/clipUtils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAOlF,eAAO,MAAM,GAAG,GAAI,QAAQ,MAAM,WAAqF,CAAC;AAExH,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAOrD;AAMD,eAAO,MAAM,cAAc,GAAI,GAAG,MAAM,EAAE,KAAK,MAAM,WAAwB,CAAC;AAC9E,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,KAAK,MAAM,WAAgB,CAAC;AAC1E,eAAO,MAAM,WAAW,GAAI,GAAG,MAAM,EAAE,KAAK,MAAM,WAAgD,CAAC;AAEnG,gFAAgF;AAChF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAKvD;AAaD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAsBzE;AAMD,eAAO,MAAM,QAAQ,GAAI,MAAM,QAAQ,EAAE,eAAwC,CAAC;AAElF,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK,CAOtF;AAED,0FAA0F;AAC1F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,aAAa,CAc9G;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,aAAa,CAKrF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,GAAG,aAAa,CAQtG;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,aAAa,CAQ9F;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,QAAQ,CAAA;CAAE,GAAG,SAAS,CAMvG;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,EAAE,CAIzD;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAEhE;AAED,4CAA4C;AAC5C,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAQvF"}

package/dist/animationsV2/clipUtils.js

@@ -0,0 +1,164 @@
+import { applyEasing, interpolateValue } from '@3driseai/3drise-core';
+import { DEFAULT_EASE } from './types.js';
+// -----------------------------------------------------------------------------
+// ids, paths
+// -----------------------------------------------------------------------------
+export const uid = (prefix) => `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`;
+/** Read a dotted settings path ('materialSettings.opacity') from a settings object. */
+export function getAtPath(obj, path) {
+    let cur = obj;
+    for (const part of path.split('.')) {
+        if (cur == null)
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+// -----------------------------------------------------------------------------
+// time
+// -----------------------------------------------------------------------------
+export const secondsToFrame = (t, fps) => Math.round(t * fps);
+export const frameToSeconds = (frame, fps) => frame / fps;
+export const snapToFrame = (t, fps) => frameToSeconds(secondsToFrame(t, fps), fps);
+/** 'SS:FF' timecode (minutes folded into seconds past 59 — clips are short). */
+export function timecode(t, fps) {
+    const totalFrames = Math.max(0, secondsToFrame(t, fps));
+    const s = Math.floor(totalFrames / fps);
+    const f = totalFrames - s * fps;
+    return `${String(s).padStart(2, '0')}:${String(f).padStart(2, '0')}`;
+}
+// -----------------------------------------------------------------------------
+// sampling
+// -----------------------------------------------------------------------------
+/** Values that do not interpolate (booleans, non-colour strings) step at the next key. */
+function isSteppedValue(v) {
+    if (typeof v === 'boolean')
+        return true;
+    if (typeof v === 'string')
+        return !/^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(v);
+    return false;
+}
+export function easeProgress(ease, p) {
+    const name = ease ?? DEFAULT_EASE;
+    if (name === 'step')
+        return 0;
+    if (name === 'linear')
+        return p;
+    return applyEasing(name, p);
+}
+/**
+ * The track's value at time t. Before the first key: the first key's value;
+ * after the last: the last key's value. Keys must be sorted by t.
+ */
+export function sampleTrack(track, t) {
+    const keys = track.keys;
+    if (keys.length === 0)
+        return undefined;
+    if (t <= keys[0].t)
+        return keys[0].value;
+    const last = keys[keys.length - 1];
+    if (t >= last.t)
+        return last.value;
+    // binary search: last key with k.t <= t
+    let lo = 0;
+    let hi = keys.length - 1;
+    while (hi - lo > 1) {
+        const mid = (lo + hi) >> 1;
+        if (keys[mid].t <= t)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    const a = keys[lo];
+    const b = keys[hi];
+    if (isSteppedValue(a.value) || isSteppedValue(b.value))
+        return a.value;
+    const span = b.t - a.t;
+    const p = span > 0 ? easeProgress(a.ease, (t - a.t) / span) : 1;
+    // interpolateValue is type-aware (numbers, arrays, hex colours); the property name
+    // only disambiguates colour keys, so pass the path's last segment.
+    return interpolateValue(track.path.split('.').pop() ?? track.path, a.value, b.value, p);
+}
+// -----------------------------------------------------------------------------
+// key / track edits (pure — the slice stores the results)
+// -----------------------------------------------------------------------------
+export const sortKeys = (keys) => [...keys].sort((a, b) => a.t - b.t);
+/** Add a key at t, or replace the value of a key already on that frame. */
+export function upsertKey(track, t, value, fps) {
+    const frame = secondsToFrame(t, fps);
+    const existing = track.keys.find(k => secondsToFrame(k.t, fps) === frame);
+    if (existing) {
+        return { ...track, keys: track.keys.map(k => (k.id === existing.id ? { ...k, value } : k)) };
+    }
+    return { ...track, keys: sortKeys([...track.keys, { id: uid('k'), t: snapToFrame(t, fps), value }]) };
+}
+/** Move keys by dt seconds, clamped to [0, duration], snapped to frames unless `free`. */
+export function moveKeys(clip, selection, dt, free) {
+    return {
+        ...clip,
+        tracks: clip.tracks.map(track => {
+            if (!track.keys.some(k => selection.has(k.id)))
+                return track;
+            const keys = track.keys.map(k => {
+                if (!selection.has(k.id))
+                    return k;
+                let t = Math.min(clip.duration, Math.max(0, k.t + dt));
+                if (!free)
+                    t = snapToFrame(t, clip.fps);
+                return { ...k, t };
+            });
+            return { ...track, keys: sortKeys(keys) };
+        }),
+    };
+}
+export function deleteKeys(clip, selection) {
+    return {
+        ...clip,
+        tracks: clip.tracks.map(track => ({ ...track, keys: track.keys.filter(k => !selection.has(k.id)) })),
+    };
+}
+export function setKeysEase(clip, selection, ease) {
+    return {
+        ...clip,
+        tracks: clip.tracks.map(track => ({
+            ...track,
+            keys: track.keys.map(k => (selection.has(k.id) ? { ...k, ease } : k)),
+        })),
+    };
+}
+export function setKeyValue(clip, keyId, value) {
+    return {
+        ...clip,
+        tracks: clip.tracks.map(track => ({
+            ...track,
+            keys: track.keys.map(k => (k.id === keyId ? { ...k, value } : k)),
+        })),
+    };
+}
+export function findKey(clip, keyId) {
+    for (const track of clip.tracks) {
+        const key = track.keys.find(k => k.id === keyId);
+        if (key)
+            return { track, key };
+    }
+    return undefined;
+}
+/** All key times of the clip, sorted and unique (for Shift+←/→). */
+export function allKeyTimes(clip) {
+    const set = new Set();
+    clip.tracks.forEach(tr => tr.keys.forEach(k => set.add(k.t)));
+    return [...set].sort((a, b) => a - b);
+}
+export function newClip(name, key) {
+    return { id: uid('clip'), name, key, duration: 4, fps: 30, loop: false, yoyo: false, endMode: 'hold', tracks: [] };
+}
+/** Deep copy with fresh ids (duplicate). */
+export function cloneClip(clip, name, key) {
+    return {
+        ...clip,
+        id: uid('clip'),
+        name,
+        key,
+        tracks: clip.tracks.map(tr => ({ ...tr, id: uid('tr'), keys: tr.keys.map(k => ({ ...k, id: uid('k') })) })),
+    };
+}

package/dist/animationsV2/elementSettings.d.ts

@@ -0,0 +1,15 @@
+export interface ElementSources {
+    objects: Array<{
+        id: string;
+    }>;
+    camera: unknown;
+    sky: unknown;
+    clouds: unknown;
+    ocean: unknown;
+    terrain: unknown;
+}
+export declare const ENVIRONMENT_STATES: readonly ["sky", "clouds", "ocean", "terrain"];
+export type EnvironmentState = typeof ENVIRONMENT_STATES[number];
+export declare const isEnvironmentState: (state: string) => state is EnvironmentState;
+export declare function resolveElementSettings(state: string, src: ElementSources): any;
+//# sourceMappingURL=elementSettings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"elementSettings.d.ts","sourceRoot":"","sources":["../../src/animationsV2/elementSettings.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/B,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,eAAO,MAAM,kBAAkB,gDAAiD,CAAC;AACjF,MAAM,MAAM,gBAAgB,GAAG,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC;AACjE,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,KAAK,IAAI,gBACD,CAAC;AAE5D,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,GAAG,CAU9E"}

package/dist/animationsV2/elementSettings.js

@@ -0,0 +1,16 @@
+// Authored settings of any animatable element, with applied action patches — the
+// value a track starts from and returns to. Elements: an object id, 'camera', or an
+// environment element ('sky' | 'clouds' | 'ocean' | 'terrain'; the first three are the ids actions use).
+import { SceneActions, applySettingsPatch } from '@3driseai/3drise-core';
+export const ENVIRONMENT_STATES = ['sky', 'clouds', 'ocean', 'terrain'];
+export const isEnvironmentState = (state) => ENVIRONMENT_STATES.includes(state);
+export function resolveElementSettings(state, src) {
+    const base = state === 'camera' ? src.camera
+        : state === 'sky' ? src.sky
+            : state === 'clouds' ? src.clouds
+                : state === 'ocean' ? src.ocean
+                    : state === 'terrain' ? src.terrain
+                        : src.objects.find(o => o.id === state);
+    const patch = SceneActions.getPatch(state);
+    return base && patch ? applySettingsPatch(base, patch) : base;
+}

package/dist/animationsV2/index.d.ts

@@ -0,0 +1,16 @@
+export { default as ClipsRuntime } from './ClipsRuntime';
+export type { RuntimeEvent, RuntimeEventType, DrivenSequence } from './ClipsRuntime';
+export { default as ClipPlayer } from './ClipPlayer';
+export type { ClipPlayerProps } from './ClipPlayer';
+export * from './clipUtils';
+export * from './sequenceUtils';
+export * from './normalize';
+export { applyValue, clearApplierCaches } from './appliers';
+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 { 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

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

package/dist/animationsV2/index.js

@@ -0,0 +1,12 @@
+// Animations V2 runtime — clips, sequences, and the player. One ClipsRuntime
+// instance serves the studio and the published viewer.
+export { default as ClipsRuntime } from './ClipsRuntime.js';
+export { default as ClipPlayer } from './ClipPlayer.js';
+export * from './clipUtils.js';
+export * from './sequenceUtils.js';
+export * from './normalize.js';
+export { applyValue, clearApplierCaches } from './appliers.js';
+export { readNodeValue, NODE_TRANSFORM_PATHS, NODE_MATERIAL_KEYS } from './nodeTracks.js';
+export { resolveElementSettings, isEnvironmentState, ENVIRONMENT_STATES as CLIP_ENVIRONMENT_STATES } from './elementSettings.js';
+export { DEFAULT_DRIVER_SETTINGS } from './types.js';
+export { DEFAULT_EASE as CLIP_DEFAULT_EASE, FPS_PRESETS as CLIP_FPS_PRESETS } from './types.js';

package/dist/animationsV2/nodeTracks.d.ts

@@ -0,0 +1,13 @@
+import type { KeyValue } from './types';
+type Obj = any;
+export declare const NODE_TRANSFORM_PATHS: readonly ["position", "rotation", "scale", "visible"];
+export declare const NODE_MATERIAL_KEYS: readonly ["color", "opacity", "roughness", "metalness", "emissive", "emissiveIntensity"];
+export declare function clearNodeCaches(): void;
+export declare function nodesFor(state: string, node: string): Obj[];
+/** The node's current value for a node-relative path (first match), as a key value. */
+export declare function readNodeValue(state: string, node: string, path: string): KeyValue | undefined;
+export declare function applyNodeValue(state: string, node: string, path: string, value: KeyValue): boolean;
+/** Put a node track back: its snapshot, and the node's original materials once no material track remains. */
+export declare function restoreNodeTrack(state: string, node: string, path: string, stillAnimated: (path: string) => boolean): void;
+export {};
+//# sourceMappingURL=nodeTracks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nodeTracks.d.ts","sourceRoot":"","sources":["../../src/animationsV2/nodeTracks.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,KAAK,GAAG,GAAG,GAAG,CAAC;AAEf,eAAO,MAAM,oBAAoB,uDAAwD,CAAC;AAC1F,eAAO,MAAM,kBAAkB,0FAA2F,CAAC;AAa3H,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,EAAE,CAQ3D;AAUD,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAiB7F;AAoBD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CA2BlG;AAED,6GAA6G;AAC7G,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAiC1H"}

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));
+                }
+            }
+        }
+    }
+}