@3driseai/3drise-core 1.0.25 → 1.0.27

package/dist/utils/animationTargets.js

@@ -0,0 +1,356 @@
+// =============================================================================
+// Animation targets — Self / Each / Targets on groups and models
+// =============================================================================
+//
+// An Animation-tab row on a group or a model reaches (AnimationOptions.scope):
+//   self     the object as one piece — the old path, `to` absolute (not handled here)
+//   each     every part on its own: a group's leaf child objects (full depth, through
+//            nested groups), a model's meshes
+//   targets  only the chosen ones (AnimationOptions.targets), each on its own:
+//            group → child objects by id (a model child optionally narrowed to nodes),
+//            model → nodes by name (every layout copy)
+//
+// Transform `to` on each / targets is RELATIVE to the target's own rest value:
+// position / rotation are added, scale is multiplied. Material `to` stays absolute.
+//
+// Rest values:
+//   a scene object root (a group child) → `userData.baseTransform`, written by the
+//     viewer's AnimatedObject from the object's settings, so editing the child in the
+//     studio moves its rest too;
+//   a model node / mesh → snapshotted before the first write (it already carries any
+//     saved node override).
+// A target the rows stop driving (row removed, switched off, scope changed) is put
+// back on its rest at the end of the frame (`AnimationTargetState.endFrame`).
+//
+// Materials: a model node whose material is shared with a mesh outside the targets
+// gets its own clone before the first write (otherwise the whole model changes);
+// the original is put back when nothing drives that node's material any more.
+//
+// Stagger (AnimationOptions.stagger): each target starts `delay` seconds later, its
+// delay = total · rank / (n − 1), rank by tree order / axis / centre-out / seeded random.
+//
+import { Box3, Vector3 } from 'three';
+import { findNodesByName } from './nodeOverrides.js';
+import { getMaterialPropertyValue, applyMaterialPropertyToObject } from './materialUtils.js';
+/** What kind of root the scope works on; null = scope does not apply (self). */
+export function targetRootKind(root) {
+    const t = root.userData?.objectType;
+    return t === 'group' || t === 'model' ? t : null;
+}
+/** The scope a row really runs with on this root ('self' when it cannot apply). */
+export function effectiveScope(root, anim) {
+    const scope = anim.scope ?? 'self';
+    if (scope === 'self' || !targetRootKind(root))
+        return 'self';
+    if (scope === 'targets' && !anim.targets?.length)
+        return 'self';
+    return scope;
+}
+const isFxHelper = (o) => !!o.userData?.__opFxHelper;
+/** Leaf object roots under a group (through nested groups), tree order. */
+function groupLeaves(root) {
+    const out = [];
+    const walk = (n) => {
+        for (const c of n.children) {
+            if (isFxHelper(c))
+                continue;
+            if (c.userData?.id) {
+                if (c.userData.objectType === 'group')
+                    walk(c);
+                else
+                    out.push(c);
+            }
+            else
+                walk(c);
+        }
+    };
+    walk(root);
+    return out;
+}
+/** The object root with this id under `root` (any depth). */
+function findObjectRoot(root, id) {
+    let hit = null;
+    root.traverse((c) => { if (!hit && c !== root && c.userData?.id === id)
+        hit = c; });
+    return hit;
+}
+/** A model's meshes, tree order (effect helpers left out). */
+function meshesOf(root) {
+    const out = [];
+    const walk = (n) => {
+        for (const c of n.children) {
+            if (isFxHelper(c))
+                continue;
+            if (c.isMesh)
+                out.push(c);
+            walk(c);
+        }
+    };
+    walk(root);
+    return out;
+}
+const nodesNamed = (root, name) => findNodesByName(root, name).filter(n => n !== root);
+/**
+ * The Object3Ds a row reaches on `root`, in tree order, without duplicates.
+ * 'self' (or a root that is neither a group nor a model) → [root].
+ */
+export function resolveAnimationTargets(root, scope, targets) {
+    const kind = targetRootKind(root);
+    if (!kind || !scope || scope === 'self')
+        return [root];
+    let out;
+    if (kind === 'group') {
+        if (scope === 'each')
+            out = groupLeaves(root);
+        else {
+            out = [];
+            for (const t of targets ?? []) {
+                const child = findObjectRoot(root, t.id);
+                if (!child)
+                    continue;
+                if (t.nodes?.length)
+                    for (const n of t.nodes)
+                        out.push(...nodesNamed(child, n));
+                else
+                    out.push(child);
+            }
+        }
+    }
+    else {
+        if (scope === 'each')
+            out = meshesOf(root);
+        else {
+            out = [];
+            for (const t of targets ?? [])
+                out.push(...nodesNamed(root, t.id));
+        }
+    }
+    return [...new Set(out)];
+}
+// -----------------------------------------------------------------------------
+// Stagger
+// -----------------------------------------------------------------------------
+const hash = (s) => { let h = 2166136261; for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+} return h >>> 0; };
+function mulberry32(seed) {
+    return () => {
+        seed |= 0;
+        seed = (seed + 0x6d2b79f5) | 0;
+        let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** Seconds each target waits, same order as `objs`. No stagger / total 0 / one target → all 0. */
+export function staggerDelays(root, objs, stagger, seed) {
+    const n = objs.length;
+    const total = Math.max(0, Number(stagger?.total) || 0);
+    if (!total || n < 2)
+        return objs.map(() => 0);
+    const order = stagger?.order ?? 'tree';
+    let ranked; // indices into objs, first goes first
+    if (order === 'tree')
+        ranked = objs.map((_, i) => i);
+    else if (order === 'random') {
+        const rnd = mulberry32(hash(seed));
+        ranked = objs.map((_, i) => i);
+        for (let i = n - 1; i > 0; i--) {
+            const j = Math.floor(rnd() * (i + 1));
+            [ranked[i], ranked[j]] = [ranked[j], ranked[i]];
+        }
+    }
+    else {
+        root.updateWorldMatrix(true, true);
+        const box = new Box3();
+        const centres = objs.map((o) => {
+            const c = new Vector3();
+            box.setFromObject(o);
+            if (box.isEmpty())
+                o.getWorldPosition(c);
+            else
+                box.getCenter(c);
+            return root.worldToLocal(c);
+        });
+        let key;
+        if (order === 'radial') {
+            const mid = centres.reduce((a, c) => a.add(c), new Vector3()).divideScalar(n);
+            key = (c) => c.distanceTo(mid);
+        }
+        else
+            key = (c) => c[order];
+        ranked = objs.map((_, i) => i).sort((a, b) => key(centres[a]) - key(centres[b]) || a - b);
+    }
+    const delays = new Array(n).fill(0);
+    ranked.forEach((idx, rank) => { delays[idx] = (total * rank) / (n - 1); });
+    return delays;
+}
+/** Re-resolve a row's targets this often (frames) — children join / leave, models load. */
+const RESOLVE_EVERY = 60;
+export class AnimationTargetState {
+    root;
+    frame = 0;
+    resolved = new Map();
+    /** Transform rest snapshots of nodes (object roots use userData.baseTransform). */
+    restT = new Map();
+    /** Material rest values per target and property. */
+    restM = new Map();
+    /** Written this frame / last frame: `${uuid}|t|position` → target. */
+    touched = new Map();
+    last = new Map();
+    /** Material clones made per target node. */
+    owned = new Map();
+    constructor(root) {
+        this.root = root;
+    }
+    get object() { return this.root; }
+    beginFrame() {
+        this.frame++;
+        this.last = this.touched;
+        this.touched = new Map();
+    }
+    /** Targets + delays of a row, cached. */
+    targetsOf(anim, scope) {
+        const key = `${anim.property}|${scope}|${JSON.stringify(anim.targets ?? null)}|${JSON.stringify(anim.stagger ?? null)}`;
+        const hit = this.resolved.get(key);
+        if (hit && this.frame - hit.frame < RESOLVE_EVERY && hit.objs.every(o => o.parent))
+            return hit;
+        const objs = resolveAnimationTargets(this.root, scope, anim.targets);
+        const same = hit && hit.objs.length === objs.length && hit.objs.every((o, i) => o === objs[i]);
+        const delays = same ? hit.delays : staggerDelays(this.root, objs, anim.stagger, `${this.root.userData?.id ?? this.root.uuid}|${anim.property}`);
+        const next = { objs, delays, frame: this.frame };
+        this.resolved.set(key, next);
+        return next;
+    }
+    /** Keep a target on what it has (a hover row while not hovered): not restored this frame. */
+    hold(obj, domain, prop) {
+        const k = `${obj.uuid}|${domain}|${prop}`;
+        const prev = this.last.get(k);
+        if (prev)
+            this.touched.set(k, prev);
+    }
+    // ---- transform ----------------------------------------------------------
+    transformRest(obj, prop) {
+        const base = obj.userData?.baseTransform?.[prop];
+        if (Array.isArray(base) && base.length >= 3)
+            return [base[0], base[1], base[2]];
+        let snap = this.restT.get(obj);
+        if (!snap) {
+            snap = {};
+            this.restT.set(obj, snap);
+        }
+        if (!snap[prop]) {
+            const v = obj[prop];
+            snap[prop] = [v.x, v.y, v.z];
+        }
+        return snap[prop];
+    }
+    writeTransform(obj, prop, v) {
+        obj[prop].set(v[0], v[1], v[2]);
+        this.touched.set(`${obj.uuid}|t|${prop}`, { obj, domain: 't', prop });
+    }
+    /** Mark a transform as driven without writing (keyframe rows write themselves). */
+    touchTransform(obj, prop) {
+        this.transformRest(obj, prop);
+        this.touched.set(`${obj.uuid}|t|${prop}`, { obj, domain: 't', prop });
+    }
+    // ---- material -----------------------------------------------------------
+    /** The target's own value before the first write (what it goes back to). */
+    materialRest(obj, prop) {
+        let rec = this.restM.get(obj);
+        if (!rec) {
+            rec = {};
+            this.restM.set(obj, rec);
+        }
+        if (!(prop in rec))
+            rec[prop] = getMaterialPropertyValue(obj, prop);
+        return rec[prop];
+    }
+    writeMaterial(obj, prop, value) {
+        if (!obj.userData?.id)
+            this.ownMaterials(obj);
+        applyMaterialPropertyToObject(obj, prop, value);
+        this.touched.set(`${obj.uuid}|m|${prop}`, { obj, domain: 'm', prop });
+    }
+    /** A model node: clone the materials it shares with meshes outside it (once). */
+    ownMaterials(node) {
+        if (this.owned.has(node))
+            return;
+        const inside = new Set();
+        node.traverse(c => inside.add(c));
+        const sharedOutside = new Set();
+        this.root.traverse((c) => {
+            if (inside.has(c))
+                return;
+            const m = c.material;
+            if (!m)
+                return;
+            for (const x of Array.isArray(m) ? m : [m])
+                if (x)
+                    sharedOutside.add(x);
+        });
+        const list = [];
+        node.traverse((c) => {
+            const m = c.material;
+            if (!m || isFxHelper(c))
+                return;
+            const arr = Array.isArray(m) ? m : [m];
+            if (!arr.some(x => sharedOutside.has(x)))
+                return;
+            list.push({ mesh: c, original: m });
+            c.material = Array.isArray(m) ? m.map(x => (sharedOutside.has(x) ? x.clone() : x)) : m.clone();
+        });
+        this.owned.set(node, list);
+    }
+    releaseMaterials(node) {
+        const list = this.owned.get(node);
+        if (!list)
+            return;
+        for (const { mesh, original } of list) {
+            const cur = mesh.material;
+            for (const x of Array.isArray(cur) ? cur : [cur]) {
+                if (x && !(Array.isArray(original) ? original.includes(x) : original === x))
+                    x.dispose?.();
+            }
+            mesh.material = original;
+        }
+        this.owned.delete(node);
+        this.restM.delete(node);
+    }
+    // ---- end of frame -------------------------------------------------------
+    /** Put back on their rest the targets driven last frame and not this frame. */
+    endFrame() {
+        for (const [k, t] of this.last) {
+            if (this.touched.has(k))
+                continue;
+            if (t.domain === 't') {
+                const prop = t.prop;
+                const r = this.transformRest(t.obj, prop);
+                t.obj[prop].set(r[0], r[1], r[2]);
+                this.restT.get(t.obj) && delete this.restT.get(t.obj)[prop];
+            }
+            else {
+                const rec = this.restM.get(t.obj);
+                if (rec && t.prop in rec)
+                    applyMaterialPropertyToObject(t.obj, t.prop, rec[t.prop]);
+                if (rec)
+                    delete rec[t.prop];
+                const stillDriven = [...this.touched.values()].some(x => x.obj === t.obj && x.domain === 'm');
+                if (!stillDriven)
+                    this.releaseMaterials(t.obj);
+            }
+        }
+        this.last = new Map();
+    }
+    /** Everything back on its rest (the object goes away / the hook stops). */
+    dispose() {
+        this.beginFrame();
+        this.endFrame();
+        for (const node of [...this.owned.keys()])
+            this.releaseMaterials(node);
+        this.resolved.clear();
+        this.restT.clear();
+        this.restM.clear();
+    }
+}

package/dist/utils/cdnUrls.d.ts

@@ -0,0 +1,5 @@
+export declare const SPACES_ORIGIN_HOST = ".sfo3.digitaloceanspaces.com/";
+export declare const SPACES_CDN_HOST = ".sfo3.cdn.digitaloceanspaces.com/";
+/** Origin Spaces URL → CDN URL. Anything else (CDN, data:, blob:, relative, null) passes through. */
+export declare const toCdn: <T extends string | null | undefined>(url: T) => T;
+//# sourceMappingURL=cdnUrls.d.ts.map

package/dist/utils/cdnUrls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdnUrls.d.ts","sourceRoot":"","sources":["../../src/utils/cdnUrls.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,kBAAkB,kCAAkC,CAAC;AAClE,eAAO,MAAM,eAAe,sCAAsC,CAAC;AAEnE,qGAAqG;AACrG,eAAO,MAAM,KAAK,GAAI,CAAC,SAAS,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,CAAC,KAAG,CACuB,CAAC"}

package/dist/utils/cdnUrls.js

@@ -0,0 +1,8 @@
+// Asset URLs are stored with the Spaces origin host (generatePublicUrl in data-center).
+// Anything that DISPLAYS or FETCHES an asset goes through the Spaces CDN instead. The DB keeps
+// the origin URL so string matches (templatesUsingUrl, delete key extraction) are unaffected —
+// so call toCdn only where a URL is shown or fetched, never on a value that gets saved back.
+export const SPACES_ORIGIN_HOST = '.sfo3.digitaloceanspaces.com/';
+export const SPACES_CDN_HOST = '.sfo3.cdn.digitaloceanspaces.com/';
+/** Origin Spaces URL → CDN URL. Anything else (CDN, data:, blob:, relative, null) passes through. */
+export const toCdn = (url) => (typeof url === 'string' ? url.replace(SPACES_ORIGIN_HOST, SPACES_CDN_HOST) : url);

package/dist/utils/handleMaterialEffects.d.ts

@@ -1,10 +1,13 @@
 import { Object3D } from "three";
 import { AnimationOptions, ColorEffectV2, EffectState, MaterialSettings } from "../types";
+import { type AnimationTargetState } from "./animationTargets";
 export interface MaterialAnimationContext {
     object: Object3D;
     materialSettings: MaterialSettings;
     /** Cache of start values for animations (property -> value) */
     startValuesCache: Record<string, any>;
+    /** Groups / models: rows scoped each / targets run through it (see animationTargets.ts). */
+    targets?: AnimationTargetState;
 }
 export declare const DEBUG_MATERIAL_EFFECTS = false;
 /**

package/dist/utils/handleMaterialEffects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handleMaterialEffects.d.ts","sourceRoot":"","sources":["../../src/utils/handleMaterialEffects.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC1F,MAAM,WAAW,wBAAwB;IACrC,MAAM,EAAE,QAAQ,CAAC;IACjB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,+DAA+D;IAC/D,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACzC;AAMD,eAAO,MAAM,sBAAsB,QAAQ,CAAC;AAmC5C;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,wBAAwB,EAAE,SAAS,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CA6B/I;AAID;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,wBAAwB,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAWnJ;AAID;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE;IACnH,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;CAC/B,EAAE,eAAe,GAAE,OAAe,GAAG,IAAI,CAcjD"}
+{"version":3,"file":"handleMaterialEffects.d.ts","sourceRoot":"","sources":["../../src/utils/handleMaterialEffects.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC1F,OAAO,EAAkB,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,MAAM,WAAW,wBAAwB;IACrC,MAAM,EAAE,QAAQ,CAAC;IACjB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,+DAA+D;IAC/D,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtC,4FAA4F;IAC5F,OAAO,CAAC,EAAE,oBAAoB,CAAC;CAClC;AAMD,eAAO,MAAM,sBAAsB,QAAQ,CAAC;AAmC5C;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,wBAAwB,EAAE,SAAS,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CA6B/I;AAID;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,wBAAwB,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAgBnJ;AA0BD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE;IACnH,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;CAC/B,EAAE,eAAe,GAAE,OAAe,GAAG,IAAI,CAcjD"}

package/dist/utils/handleMaterialEffects.js

@@ -10,6 +10,7 @@ import { calculateTimeProgress, getMaterialPropertyValue, interpolateValue, appl
 import { applyEasing, gsapEasingMap } from "./animationsUtils.js";
 import { createDefaultEffectState, } from "./utils.js";
 import { applyAllColorEffects } from "./frameAnimations.js";
+import { effectiveScope } from "./animationTargets.js";
 // =============================================================================
 // DEBUG
 // =============================================================================
@@ -98,9 +99,37 @@ export function handleMaterialAnimations(ctx, animations, currentTime, hovered)
         if (property === "position" || property === "rotation" || property === "scale") {
             return;
         }
+        const scope = ctx.targets ? effectiveScope(ctx.object, animation) : 'self';
+        if (scope !== 'self') {
+            animateMaterialTargets(ctx.targets, animation, scope, currentTime, hovered);
+            return;
+        }
         animateMaterialProperty(ctx, animation, currentTime, hovered);
     });
 }
+/** A row scoped each / targets: each target from its own value to `to` (absolute), `delay` later each (stagger). */
+function animateMaterialTargets(state, animation, scope, currentTime, hovered) {
+    const { property, to, duration, ease, loop = false, yoyo = false } = animation;
+    if (to === undefined)
+        return;
+    const { objs, delays } = state.targetsOf(animation, scope);
+    if (animation.triggerMode === "hover" && !hovered) {
+        for (const o of objs)
+            state.hold(o, 'm', property);
+        return;
+    }
+    const easing = ease ? (gsapEasingMap[ease] || ease) : null;
+    objs.forEach((target, i) => {
+        const rest = state.materialRest(target, property);
+        const from = animation.from !== undefined ? animation.from : rest;
+        if (from === null || from === undefined)
+            return;
+        let t = calculateTimeProgress(currentTime - delays[i] * 1000, duration, yoyo, loop);
+        if (easing)
+            t = applyEasing(easing, t);
+        state.writeMaterial(target, property, interpolateValue(property, from, to, t));
+    });
+}
 // =============================================================================
 // HANDLE MATERIAL EFFECTS (COLOR EFFECTS)
 // =============================================================================

package/dist/utils/handleTransformEffects.d.ts

@@ -2,10 +2,24 @@ import type { Object3D } from 'three';
 import type { AnimationOptions, Vector3Array } from "../types/scene3d";
 import type { TransformEffectV2 } from "../types/objectSettings";
 import type { EffectState } from "../types/effects";
+import { type AnimationTargetState } from "./animationTargets";
 export interface TransformAnimationContext {
     object: Object3D;
     meshSettings: any;
     pathIsActive: boolean;
+    /** Groups / models: rows scoped each / targets run through it (see animationTargets.ts). Absent = every row on the object itself. */
+    targets?: AnimationTargetState;
+    /**
+     * A timeline clip driving a row's `to` (by its index in the list): laid over the authored value
+     * while the clip runs — live, never written to the settings. Absent / undefined = the row's own.
+     */
+    liveTo?: (index: number) => Vector3Array | undefined;
+    /**
+     * A timeline clip has taken this property over (the object itself: target null; a group's /
+     * model's child: that child). The clip has full control while it is active: the row stops on
+     * that target — nothing is added, nothing is restored — and runs again once the clip ends.
+     */
+    takenOver?: (target: Object3D | null, property: 'position' | 'rotation' | 'scale') => boolean;
 }
 export declare const DEBUG_TRANSFORM_EFFECTS = false;
 /**

package/dist/utils/handleTransformEffects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handleTransformEffects.d.ts","sourceRoot":"","sources":["../../src/utils/handleTransformEffects.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAKtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,MAAM,WAAW,yBAAyB;IACtC,MAAM,EAAE,QAAQ,CAAC;IACjB,YAAY,EAAE,GAAG,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;CACzB;AAMD,eAAO,MAAM,uBAAuB,QAAQ,CAAC;AAS7C;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,UAAU,GAAG,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,IAAI,CAwBpO;AAID;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,yBAAyB,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CA0DrK;AAID;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,iBAAiB,GAAG,iBAAiB,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE;IACtJ,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;CAC/B,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAqBjC"}
+{"version":3,"file":"handleTransformEffects.d.ts","sourceRoot":"","sources":["../../src/utils/handleTransformEffects.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAKtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAkB,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,MAAM,WAAW,yBAAyB;IACtC,MAAM,EAAE,QAAQ,CAAC;IACjB,YAAY,EAAE,GAAG,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,qIAAqI;IACrI,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,YAAY,GAAG,SAAS,CAAC;IACrD;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,EAAE,QAAQ,EAAE,UAAU,GAAG,UAAU,GAAG,OAAO,KAAK,OAAO,CAAC;CACjG;AAMD,eAAO,MAAM,uBAAuB,QAAQ,CAAC;AAS7C;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,UAAU,GAAG,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,IAAI,CAwBpO;AAID;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,yBAAyB,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CA2CrK;AAyCD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,iBAAiB,GAAG,iBAAiB,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE;IACtJ,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;CAC/B,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAqBjC"}

package/dist/utils/handleTransformEffects.js

@@ -10,6 +10,7 @@ import { applyEasing, gsapEasingMap } from "./animationsUtils.js";
 import { applyTransformEffects } from "../utils/frameAnimations.js";
 import { calculateTimeProgress } from "./materialUtils.js";
 import { createDefaultEffectState } from "./utils.js";
+import { effectiveScope } from "./animationTargets.js";
 // =============================================================================
 // DEBUG
 // =============================================================================
@@ -64,20 +65,27 @@ export function handleTransformAnimations(ctx, animations, currentTime, hovered,
     // Without a delta (older callers) one frame, the old per-frame behaviour.
     const frames = delta === undefined ? 1 : Math.min(Math.max(delta, 0), 0.1) * 60;
     // console.log("handleTransformAnimations called with animations:", animations);
-    animations.forEach((animation) => {
-        const { property, ease, duration, loop = false, to, yoyo = false, active, type = "interpolation", objectIds, triggerMode = "always", } = animation;
+    animations.forEach((row, index) => {
+        const live = ctx.liveTo?.(index);
+        const animation = live ? { ...row, to: live } : row;
+        const { property, ease, duration, loop = false, to, yoyo = false, active, type = "interpolation", triggerMode = "always", } = animation;
         if (!active)
             return;
-        if (triggerMode === "hover" && !hovered)
+        // Only handle transform properties
+        if (property !== "position" && property !== "rotation" && property !== "scale") {
             return;
-        // Skip position/rotation if path animation is active (path controls these)
-        if (pathIsActive &&
-            (property === "position" || property === "rotation") &&
-            (!objectIds || objectIds.length === 0)) {
+        }
+        const scope = ctx.targets ? effectiveScope(object, animation) : 'self';
+        if (scope !== 'self') {
+            animateTargets(ctx.targets, animation, property, scope, currentTime, hovered, frames, ctx.takenOver);
             return;
         }
-        // Only handle transform properties
-        if (property !== "position" && property !== "rotation" && property !== "scale") {
+        if (ctx.takenOver?.(null, property))
+            return; // a clip drives it: the clip has full control
+        if (triggerMode === "hover" && !hovered)
+            return;
+        // Skip position/rotation if path animation is active (path controls these)
+        if (pathIsActive && (property === "position" || property === "rotation")) {
             return;
         }
         // Calculate animation progress
@@ -88,32 +96,51 @@ export function handleTransformAnimations(ctx, animations, currentTime, hovered,
             timeProgress = applyEasing(easingFunctionName, timeProgress);
         }
         const animationSpeed = 1000 / duration;
-        // Determine which objects to animate
-        const targetsToAnimate = [];
-        if (objectIds && objectIds.length > 0) {
-            // Animate specific children by name
-            // Every match, not getObjectByName's first: a model repeated by
-            // meshSettings.layout has the same part name once per copy.
-            const names = new Set(objectIds);
-            object.traverse((child) => {
-                if (child.name && names.has(child.name)) {
-                    targetsToAnimate.push(child);
-                }
-            });
-            log("animating specific targets", { objectIds, found: targetsToAnimate.length });
-        }
-        else {
-            // Animate the parent object
-            targetsToAnimate.push(object);
-        }
         // Get start value from meshSettings
         const start = meshSettings[property];
         if (!start || !to)
             return;
-        // Apply animation to each target
-        targetsToAnimate.forEach((target) => {
-            animateTransformProperty(target, property, start, to, timeProgress, type, animationSpeed, frames);
+        animateTransformProperty(object, property, start, to, timeProgress, type, animationSpeed, frames);
+    });
+}
+/**
+ * A row scoped each / targets: every target on its own, `to` relative to the target's rest
+ * (position / rotation added, scale multiplied), each target `delay` later (stagger).
+ */
+function animateTargets(state, animation, property, scope, currentTime, hovered, frames, takenOver) {
+    const { ease, duration, loop = false, to, yoyo = false, type = "interpolation", triggerMode = "always" } = animation;
+    const { objs, delays } = state.targetsOf(animation, scope);
+    if (triggerMode === "hover" && !hovered) {
+        for (const o of objs)
+            state.hold(o, 't', property);
+        return;
+    }
+    if (!Array.isArray(to) || to.length < 3)
+        return;
+    const isScale = property === "scale";
+    const animationSpeed = 1000 / duration;
+    const easing = ease ? (gsapEasingMap[ease] || ease) : null;
+    objs.forEach((target, i) => {
+        // a clip drives this target: leave it to the clip (held — not put back to its rest either)
+        if (takenOver?.(target, property)) {
+            state.hold(target, 't', property);
+            return;
+        }
+        if (type === "keyframe") {
+            // Continuous: the same increment per frame on each target (a stagger has nothing to offset).
+            state.touchTransform(target, property);
+            animateTransformProperty(target, property, [0, 0, 0], to, 0, "keyframe", animationSpeed, frames);
+            return;
+        }
+        let t = calculateTimeProgress(currentTime - delays[i] * 1000, duration, yoyo, loop);
+        if (easing)
+            t = applyEasing(easing, t);
+        const rest = state.transformRest(target, property);
+        const v = rest.map((r, k) => {
+            const d = Number(to[k]) || 0;
+            return isScale ? r * MathUtils.lerp(1, d, t) : r + MathUtils.lerp(0, d, t);
         });
+        state.writeTransform(target, property, v);
     });
 }
 // =============================================================================

package/dist/utils/index.d.ts

@@ -21,6 +21,7 @@ export * from './utils';
 export * from './edgeUtils';
 export * from './surfaceUtils';
 export * from './objectTreeUtils';
+export * from './animationTargets';
 export * from './handleTransformEffects';
 export * from './handleEdgesAnimations';
 export * from './handleLightAnimations';
@@ -47,4 +48,5 @@ export * from './actionKeys';
 export * from './objectEffects';
 export * from './cameraControls';
 export * from './materialVariant';
+export * from './cdnUrls';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC"}

package/dist/utils/index.js

@@ -21,6 +21,7 @@ export * from './utils.js';
 export * from './edgeUtils.js';
 export * from './surfaceUtils.js';
 export * from './objectTreeUtils.js';
+export * from './animationTargets.js';
 export * from './handleTransformEffects.js';
 export * from './handleEdgesAnimations.js';
 export * from './handleLightAnimations.js';
@@ -47,3 +48,4 @@ export * from './actionKeys.js';
 export * from './objectEffects.js';
 export * from './cameraControls.js';
 export * from './materialVariant.js';
+export * from './cdnUrls.js';

package/dist/utils/materialApplicationUtils.d.ts

@@ -17,8 +17,12 @@ export declare const SELF_OWNED_MATERIAL_KEY = "__ownsItsMaterial";
  * with EDGES_GROUP_KEY, GEREATIVE_EFFECTS_KEY or SELF_OWNED_MATERIAL_KEY — unless obj itself
  * carries that mark (so an edges group or generative effects group can still
  * apply its own material via useMaterialApplication).
+ * `stopAtObjects`: also stop at the roots of child scene objects — an object's material
+ * never reaches the objects parented under it (they apply their own).
  */
-export declare function traverseSkippingEdgesAndEffects(obj: Object3D, isRoot: boolean, callback: (node: Object3D) => void): void;
+export declare function traverseSkippingEdgesAndEffects(obj: Object3D, isRoot: boolean, callback: (node: Object3D) => void, stopAtObjects?: boolean): void;
+/** The root of a scene object (the viewer's AnimatedObject tags it with its id and type). */
+export declare const isSceneObjectRoot: (obj: Object3D) => boolean;
 /**
  * Create a fresh material instance for a variant and apply settings to it.
  */