@3driseai/3drise-viewer 0.1.1

package/dist/hooks/useObjectEffects.js

@@ -0,0 +1,162 @@
+/**
+ * useObjectEffects.ts
+ *
+ * Hook for managing visual object effects like vanish, glow, etc.
+ * Maintains state for which objects have effects applied.
+ */
+import { useCallback, useRef } from 'react';
+import { MeshStandardMaterial, MeshPhysicalMaterial } from 'three';
+import { gsap } from 'gsap';
+/**
+ * Hook for managing visual object effects
+ */
+export function useObjectEffects() {
+    // Track which objects have effects applied
+    const glowingObjects = useRef(new Set());
+    const vanishedObjects = useRef(new Set());
+    // ============================================================================
+    // Vanish Effect
+    // ============================================================================
+    const vanishObject = useCallback((object, duration = 1.0, ease = "power2.inOut") => {
+        console.log('[useObjectEffects] vanishObject:', object.uuid);
+        object.traverse((child) => {
+            if (child.isMesh) {
+                const mesh = child;
+                const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+                materials.forEach((mat) => {
+                    // Store original values
+                    if (mat.userData.originalOpacity === undefined) {
+                        mat.userData.originalOpacity = mat.opacity;
+                        mat.userData.originalTransparent = mat.transparent;
+                    }
+                    mat.transparent = true;
+                    gsap.to(mat, {
+                        opacity: 0,
+                        duration,
+                        ease,
+                        onComplete: () => {
+                            object.visible = false;
+                        }
+                    });
+                });
+            }
+        });
+        vanishedObjects.current.add(object.uuid);
+    }, []);
+    const restoreVanishedObject = useCallback((object, duration = 1.0, ease = "power2.inOut") => {
+        console.log('[useObjectEffects] restoreVanishedObject:', object.uuid);
+        object.visible = true;
+        object.traverse((child) => {
+            if (child.isMesh) {
+                const mesh = child;
+                const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+                materials.forEach((mat) => {
+                    if (mat.userData.originalOpacity !== undefined) {
+                        const originalOpacity = mat.userData.originalOpacity;
+                        const originalTransparent = mat.userData.originalTransparent;
+                        gsap.to(mat, {
+                            opacity: originalOpacity,
+                            duration,
+                            ease,
+                            onComplete: () => {
+                                mat.transparent = originalTransparent;
+                            }
+                        });
+                    }
+                });
+            }
+        });
+        vanishedObjects.current.delete(object.uuid);
+    }, []);
+    // ============================================================================
+    // Glow Effect
+    // ============================================================================
+    const animateGlowEffect = useCallback((object) => {
+        console.log('[useObjectEffects] animateGlowEffect:', object.uuid);
+        object.traverse((child) => {
+            if (child.isMesh) {
+                const mesh = child;
+                const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+                materials.forEach((mat) => {
+                    if (mat instanceof MeshStandardMaterial || mat instanceof MeshPhysicalMaterial) {
+                        // Store original values
+                        if (!mat.userData.originalEmissive) {
+                            mat.userData.originalEmissive = mat.emissive.getHex();
+                            mat.userData.originalEmissiveIntensity = mat.emissiveIntensity;
+                            mat.userData.originalToneMapped = mat.toneMapped;
+                        }
+                        mat.toneMapped = false;
+                        gsap.to(mat, {
+                            emissiveIntensity: 3.0,
+                            duration: 0.4,
+                            ease: "power2.out"
+                        });
+                        gsap.to(mat.emissive, {
+                            r: 0.2,
+                            g: 0.5,
+                            b: 1.0,
+                            duration: 0.4,
+                            ease: "power2.out"
+                        });
+                    }
+                });
+            }
+        });
+        glowingObjects.current.add(object.uuid);
+    }, []);
+    const removeGlow = useCallback((object) => {
+        console.log('[useObjectEffects] removeGlow:', object.uuid);
+        object.traverse((child) => {
+            if (child.isMesh) {
+                const mesh = child;
+                const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+                materials.forEach((mat) => {
+                    if (mat instanceof MeshStandardMaterial || mat instanceof MeshPhysicalMaterial) {
+                        if (mat.userData.originalEmissive !== undefined) {
+                            const originalHex = mat.userData.originalEmissive;
+                            gsap.to(mat, {
+                                emissiveIntensity: mat.userData.originalEmissiveIntensity,
+                                duration: 0.3,
+                                ease: "power2.in",
+                                onComplete: () => {
+                                    mat.toneMapped = mat.userData.originalToneMapped;
+                                }
+                            });
+                            gsap.to(mat.emissive, {
+                                r: ((originalHex >> 16) & 255) / 255,
+                                g: ((originalHex >> 8) & 255) / 255,
+                                b: (originalHex & 255) / 255,
+                                duration: 0.3,
+                                ease: "power2.in"
+                            });
+                        }
+                    }
+                });
+            }
+        });
+        glowingObjects.current.delete(object.uuid);
+    }, []);
+    // ============================================================================
+    // State Checkers
+    // ============================================================================
+    const isVanished = useCallback((objectUuid) => {
+        return vanishedObjects.current.has(objectUuid);
+    }, []);
+    const isGlowing = useCallback((objectUuid) => {
+        return glowingObjects.current.has(objectUuid);
+    }, []);
+    return {
+        // State refs
+        glowingObjects,
+        vanishedObjects,
+        // Effect functions
+        vanishObject,
+        restoreVanishedObject,
+        animateGlowEffect,
+        removeGlow,
+        // State checkers
+        isVanished,
+        isGlowing,
+    };
+}
+export default useObjectEffects;

package/dist/hooks/useOrbitControls.d.ts

@@ -0,0 +1,7 @@
+import { OrbitControls as OrbitControlsImpl } from "three-stdlib";
+/**
+ * Hook to access OrbitControls from any component within the R3F Canvas
+ * Returns the OrbitControls instance with proper typing, or null if not available
+ */
+export declare function useOrbitControls(): OrbitControlsImpl | null;
+//# sourceMappingURL=useOrbitControls.d.ts.map

package/dist/hooks/useOrbitControls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOrbitControls.d.ts","sourceRoot":"","sources":["../../src/hooks/useOrbitControls.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,IAAI,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAElE;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,GAAG,IAAI,CAG3D"}

package/dist/hooks/useOrbitControls.js

@@ -0,0 +1,9 @@
+import { useThree } from '@react-three/fiber';
+/**
+ * Hook to access OrbitControls from any component within the R3F Canvas
+ * Returns the OrbitControls instance with proper typing, or null if not available
+ */
+export function useOrbitControls() {
+    const { controls } = useThree();
+    return controls;
+}

package/dist/hooks/useOutline.d.ts

@@ -0,0 +1,9 @@
+import type { OutlineMode, Point3 } from '../utils/extractOutline';
+import { BufferGeometry } from "three";
+/**
+ * Memoized outline points for a host geometry. `mode` switches exactly one
+ * behavior: '3d' returns angle-thresholded feature edges, '2d' returns the
+ * flat front-plane profile (angle is ignored in 2d).
+ */
+export declare function useOutline(geometry: BufferGeometry | null, mode: OutlineMode, angle: number): Point3[];
+//# sourceMappingURL=useOutline.d.ts.map

package/dist/hooks/useOutline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOutline.d.ts","sourceRoot":"","sources":["../../src/hooks/useOutline.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAEvC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAMtG"}

package/dist/hooks/useOutline.js

@@ -0,0 +1,14 @@
+import { useMemo } from 'react';
+import { contour2D, edges3D } from '../utils/extractOutline.js';
+/**
+ * Memoized outline points for a host geometry. `mode` switches exactly one
+ * behavior: '3d' returns angle-thresholded feature edges, '2d' returns the
+ * flat front-plane profile (angle is ignored in 2d).
+ */
+export function useOutline(geometry, mode, angle) {
+    return useMemo(() => {
+        if (!geometry)
+            return [];
+        return mode === '2d' ? contour2D(geometry) : edges3D(geometry, angle);
+    }, [geometry, mode, angle]);
+}

package/dist/hooks/useParticlePositions.d.ts

@@ -0,0 +1,19 @@
+import type { PositionShape } from '@3driseai/3drise-core';
+import type { Points } from "three";
+interface UseParticlePositionsProps {
+    shapeType: string;
+    targetShape: PositionShape | undefined;
+    count: number;
+    outlines: boolean;
+    targetOutLines: boolean | undefined;
+    pointsRef: React.RefObject<Points | null>;
+}
+export declare const useParticlePositions: ({ shapeType, targetShape, count, outlines, targetOutLines, pointsRef, }: UseParticlePositionsProps) => {
+    basePositions: import("react").RefObject<any>;
+    targetPositions: import("react").RefObject<any>;
+    animationProgress: import("react").RefObject<number>;
+    positionsVersion: number;
+    uvs: any;
+};
+export {};
+//# sourceMappingURL=useParticlePositions.d.ts.map

package/dist/hooks/useParticlePositions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useParticlePositions.d.ts","sourceRoot":"","sources":["../../src/hooks/useParticlePositions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACpC,UAAU,yBAAyB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,aAAa,GAAG,SAAS,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7C;AAsBD,eAAO,MAAM,oBAAoB,GAAI,yEAAyE,yBAAyB;;;;;;CAkCtI,CAAC"}

package/dist/hooks/useParticlePositions.js

@@ -0,0 +1,56 @@
+import { useEffect, useRef, useState } from 'react';
+import { PositionsCreator, shapeConfig } from '@3driseai/3drise-core';
+function generateUVsFromPositions(positions) {
+    const count = positions.length / 3;
+    let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+    for (let i = 0; i < positions.length; i += 3) {
+        minX = Math.min(minX, positions[i]);
+        maxX = Math.max(maxX, positions[i]);
+        minY = Math.min(minY, positions[i + 1]);
+        maxY = Math.max(maxY, positions[i + 1]);
+    }
+    const rangeX = maxX - minX || 1;
+    const rangeY = maxY - minY || 1;
+    const uvs = new Float32Array(count * 2);
+    for (let i = 0; i < positions.length; i += 3) {
+        const idx = (i / 3) * 2;
+        uvs[idx] = (positions[i] - minX) / rangeX;
+        uvs[idx + 1] = (positions[i + 1] - minY) / rangeY;
+    }
+    return uvs;
+}
+export const useParticlePositions = ({ shapeType, targetShape, count, outlines, targetOutLines, pointsRef, }) => {
+    const basePositions = useRef(null);
+    const targetPositions = useRef(null);
+    const animationProgress = useRef(0);
+    const uvs = useRef(null);
+    const [positionsVersion, setPositionsVersion] = useState(0);
+    useEffect(() => {
+        const shapeParams = {
+            length: count,
+            name: shapeType,
+            outlines,
+            ...(shapeConfig[shapeType] || {}),
+        };
+        const newPositions = PositionsCreator.generatePositions(shapeParams);
+        basePositions.current = newPositions;
+        uvs.current = generateUVsFromPositions(newPositions);
+        setPositionsVersion(v => v + 1);
+    }, [shapeType, count, outlines]);
+    useEffect(() => {
+        if (!targetShape || targetShape === 'none') {
+            targetPositions.current = null;
+        }
+        else {
+            const shapeParams = {
+                length: count,
+                name: targetShape,
+                outlines: targetOutLines,
+                ...(shapeConfig[targetShape] || {}),
+            };
+            targetPositions.current = PositionsCreator.generatePositions(shapeParams);
+            animationProgress.current = 0;
+        }
+    }, [targetShape, count, targetOutLines]);
+    return { basePositions, targetPositions, animationProgress, positionsVersion, uvs: uvs.current };
+};

package/dist/hooks/useParticlesColors.d.ts

@@ -0,0 +1,14 @@
+import { Color } from 'three';
+interface UseParticlesColorsProps {
+    color: string;
+    targetColor?: string;
+}
+export declare const useParticlesColors: ({ color, targetColor }: UseParticlesColorsProps) => {
+    baseColorRef: import("react").RefObject<Color>;
+    targetColorRef: import("react").RefObject<Color>;
+    colorAnimationProgress: import("react").RefObject<number>;
+    currentColorRef: import("react").RefObject<Color>;
+    handleColorsAnimation: (materialRef: any, delta: any, speed: any) => void;
+};
+export {};
+//# sourceMappingURL=useParticlesColors.d.ts.map

package/dist/hooks/useParticlesColors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useParticlesColors.d.ts","sourceRoot":"","sources":["../../src/hooks/useParticlesColors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAC9B,UAAU,uBAAuB;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,kBAAkB,GAAI,wBAAwB,uBAAuB;;;;;;CAwBjF,CAAC"}

package/dist/hooks/useParticlesColors.js

@@ -0,0 +1,27 @@
+import { useRef, useEffect, useCallback } from 'react';
+import { Color } from 'three';
+export const useParticlesColors = ({ color, targetColor }) => {
+    const baseColorRef = useRef(new Color(color));
+    const colorAnimationProgress = useRef(0);
+    const currentColorRef = useRef(new Color());
+    const targetColorRef = useRef(targetColor ? new Color(targetColor) : new Color(color));
+    useEffect(() => { baseColorRef.current.set(color); }, [color]);
+    useEffect(() => {
+        if (targetColor) {
+            colorAnimationProgress.current = 0;
+            targetColorRef.current.set(targetColor);
+        }
+    }, [targetColor]);
+    const handleColorsAnimation = useCallback((materialRef, delta, speed) => {
+        if (!materialRef.current)
+            return;
+        if (!targetColor || targetColor === color) {
+            colorAnimationProgress.current = 0;
+            return;
+        }
+        colorAnimationProgress.current = Math.min(colorAnimationProgress.current + delta * speed, 1);
+        currentColorRef.current.lerpColors(baseColorRef.current, targetColorRef.current, colorAnimationProgress.current);
+        materialRef.current.uniforms.uColor.value = currentColorRef.current;
+    }, [color, targetColor]);
+    return { baseColorRef, targetColorRef, colorAnimationProgress, currentColorRef, handleColorsAnimation };
+};

package/dist/hooks/useParticlesTextures.d.ts

@@ -0,0 +1,10 @@
+import type { Texture } from "three";
+export declare const useParticlesTextures: () => {
+    currentTexture: import("react").RefObject<any>;
+    prevTexture: import("react").RefObject<any>;
+    loadTexture: (url: any) => Promise<Texture<unknown, import("three").TextureEventMap>>;
+    clearPreviousTexture: () => void;
+    textureProgress: import("react").RefObject<number>;
+    handleTextureAnimation: (materialRef: any, delta: any, speed: any) => void;
+};
+//# sourceMappingURL=useParticlesTextures.d.ts.map

package/dist/hooks/useParticlesTextures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useParticlesTextures.d.ts","sourceRoot":"","sources":["../../src/hooks/useParticlesTextures.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAErC,eAAO,MAAM,oBAAoB;;;;;;;CAoBhC,CAAC"}

package/dist/hooks/useParticlesTextures.js

@@ -0,0 +1,23 @@
+import { useRef, useCallback } from 'react';
+import { texturesManager } from '@3driseai/3drise-core';
+export const useParticlesTextures = () => {
+    const currentTexture = useRef(null);
+    const prevTexture = useRef(null);
+    const textureProgress = useRef(0);
+    const loadTexture = async (url) => {
+        if (currentTexture.current)
+            prevTexture.current = currentTexture.current;
+        const tex = await texturesManager.loadTexture(`image-${url}`, url, 'images');
+        if (tex)
+            currentTexture.current = tex;
+        return tex;
+    };
+    const clearPreviousTexture = () => { prevTexture.current = null; };
+    const handleTextureAnimation = useCallback((materialRef, delta, speed) => {
+        if (!materialRef.current || !currentTexture.current)
+            return;
+        textureProgress.current = Math.min(textureProgress.current + delta * speed, 1);
+        materialRef.current.uniforms.uTextureMorph.value = textureProgress.current;
+    }, []);
+    return { currentTexture, prevTexture, loadTexture, clearPreviousTexture, textureProgress, handleTextureAnimation };
+};

package/dist/hooks/usePathAnimation.d.ts

@@ -0,0 +1,26 @@
+import * as THREE from 'three';
+import type { Vector3Array } from '@3driseai/3drise-core';
+import type { Object3D } from "three";
+export interface PathAnimationOptions {
+    ease?: string;
+    loop?: boolean;
+    yoyo?: boolean;
+    speed?: number;
+    faceDirection?: boolean;
+    applyRotation?: boolean;
+    offset?: Vector3Array;
+    keepOriginalTransform?: boolean;
+    onComplete?: () => void;
+}
+export declare const usePathAnimation: () => {
+    startPathAnimation: (pathId: string, duration: number, options?: PathAnimationOptions) => boolean;
+    stopPathAnimation: () => void;
+    updatePathAnimation: (delta: number, object: Object3D) => boolean;
+    isAnimating: () => boolean;
+    getPositionAt: (t: number) => {
+        position: THREE.Vector3;
+        direction: THREE.Vector3;
+    };
+};
+export default usePathAnimation;
+//# sourceMappingURL=usePathAnimation.d.ts.map

package/dist/hooks/usePathAnimation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePathAnimation.d.ts","sourceRoot":"","sources":["../../src/hooks/usePathAnimation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtC,MAAM,WAAW,oBAAoB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAGD,eAAO,MAAM,gBAAgB,QAAO;IAC5B,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC;IAClG,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,mBAAmB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,KAAK,OAAO,CAAC;IAClE,WAAW,EAAE,MAAM,OAAO,CAAC;IAC3B,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK;QAC1B,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC;QACxB,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC;KAC5B,CAAC;CA6HT,CAAC;AACF,eAAe,gBAAgB,CAAC"}

package/dist/hooks/usePathAnimation.js

@@ -0,0 +1,130 @@
+import { useRef, useCallback, useEffect } from 'react';
+import * as THREE from 'three';
+import { smoothPathCorners, createPathSpline, applyEasing, resolveEasing } from '@3driseai/3drise-core';
+import { AnimationsManager } from '@3driseai/3drise-core';
+export const usePathAnimation = () => {
+    const pointsRef = useRef([]);
+    const progressRef = useRef(0);
+    const durationRef = useRef(1);
+    const splineRef = useRef(null);
+    const activeRef = useRef(false);
+    const directionRef = useRef(1);
+    const easeRef = useRef(null);
+    const loopRef = useRef(false);
+    const yoyoRef = useRef(false);
+    const speedRef = useRef(1);
+    const faceRef = useRef(true);
+    const applyRotRef = useRef(true);
+    const offsetRef = useRef(null);
+    const onCompleteRef = useRef(null);
+    const targetQuatRef = useRef(new THREE.Quaternion());
+    useEffect(() => () => { splineRef.current = null; }, []);
+    const startPathAnimation = useCallback((pathId, duration, options = {}) => {
+        const cfg = AnimationsManager.getPath(pathId);
+        if (!cfg || cfg.points.length < 2)
+            return false;
+        const smooth = cfg.smoothCorners ?? 0;
+        const pts = smooth > 0 && cfg.points.length >= 3
+            ? smoothPathCorners(cfg.points, smooth)
+            : cfg.points;
+        pointsRef.current = pts;
+        progressRef.current = 0;
+        durationRef.current = duration;
+        activeRef.current = true;
+        directionRef.current = 1;
+        easeRef.current = options.ease ?? null;
+        loopRef.current = options.loop ?? false;
+        yoyoRef.current = options.yoyo ?? false;
+        speedRef.current = options.speed ?? 1;
+        faceRef.current = options.faceDirection ?? true;
+        applyRotRef.current = options.applyRotation ?? cfg.applyRotation ?? true;
+        offsetRef.current = options.offset ?? cfg.offset ?? null;
+        onCompleteRef.current = options.onComplete ?? null;
+        const curve = cfg.curve ?? 1;
+        splineRef.current = createPathSpline(pts, curve);
+        return true;
+    }, []);
+    const stopPathAnimation = useCallback(() => {
+        activeRef.current = false;
+        splineRef.current = null;
+        progressRef.current = 0;
+        directionRef.current = 1;
+    }, []);
+    const getPositionAt = useCallback((t) => {
+        const pts = pointsRef.current;
+        const spline = splineRef.current;
+        const clamped = Math.max(0, Math.min(1, t));
+        if (spline) {
+            return {
+                position: spline.getPointAt(clamped),
+                direction: spline.getTangentAt(clamped).normalize(),
+            };
+        }
+        const segs = pts.length - 1;
+        const idx = Math.min(Math.floor(clamped * segs), segs - 1);
+        const sp = clamped * segs - idx;
+        const a = pts[idx], b = pts[idx + 1];
+        return {
+            position: new THREE.Vector3(a[0] + (b[0] - a[0]) * sp, a[1] + (b[1] - a[1]) * sp, a[2] + (b[2] - a[2]) * sp),
+            direction: new THREE.Vector3(b[0] - a[0], b[1] - a[1], b[2] - a[2]).normalize(),
+        };
+    }, []);
+    const updatePathAnimation = useCallback((delta, object) => {
+        if (!activeRef.current)
+            return false;
+        progressRef.current += (delta / durationRef.current) * speedRef.current * directionRef.current;
+        let p = progressRef.current;
+        if (p >= 1 || p <= 0) {
+            if (yoyoRef.current) {
+                directionRef.current *= -1;
+                p = Math.max(0, Math.min(1, p));
+                progressRef.current = p;
+                if (!loopRef.current && directionRef.current === 1 && p <= 0) {
+                    activeRef.current = false;
+                    onCompleteRef.current?.();
+                    return false;
+                }
+            }
+            else if (loopRef.current) {
+                progressRef.current = ((p % 1) + 1) % 1;
+                p = progressRef.current;
+            }
+            else {
+                progressRef.current = Math.max(0, Math.min(1, p));
+                activeRef.current = false;
+                onCompleteRef.current?.();
+                return false;
+            }
+        }
+        const eased = easeRef.current ? applyEasing(resolveEasing(easeRef.current), p) : p;
+        const { position, direction } = getPositionAt(eased);
+        if (offsetRef.current) {
+            position.x += offsetRef.current[0];
+            position.y += offsetRef.current[1];
+            position.z += offsetRef.current[2];
+        }
+        // Convert world-space position to parent local space (handles nested groups)
+        // if (object.parent) {
+        //   object.parent.worldToLocal(position);
+        // }
+        object.position.copy(position);
+        if (applyRotRef.current && faceRef.current && direction.lengthSq() > 0.0001) {
+            const up = new THREE.Vector3(0, 1, 0);
+            const mat = new THREE.Matrix4();
+            mat.lookAt(position, new THREE.Vector3().copy(position).add(direction), up);
+            targetQuatRef.current.setFromRotationMatrix(mat);
+            targetQuatRef.current.multiply(new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), Math.PI));
+            // Strip parent's world rotation so quaternion is in local space
+            // if (object.parent) {
+            //   const parentWorldQuat = new THREE.Quaternion();
+            //   object.parent.getWorldQuaternion(parentWorldQuat);
+            //   targetQuatRef.current.premultiply(parentWorldQuat.invert());
+            // }
+            object.quaternion.slerp(targetQuatRef.current, 1);
+        }
+        return true;
+    }, [getPositionAt]);
+    const isAnimating = useCallback(() => activeRef.current, []);
+    return { startPathAnimation, stopPathAnimation, updatePathAnimation, isAnimating, getPositionAt };
+};
+export default usePathAnimation;

package/dist/hooks/useSequenceAnimation.d.ts

@@ -0,0 +1,14 @@
+import type { Object3D } from "three";
+/**
+ * useSequenceAnimation
+ *
+ * Subscribes to AnimationsManager step events and, for each frame while a step
+ * is active, interpolates both transform AND material properties on the given
+ * object. Path-based transitions are delegated to usePathAnimation.
+ *
+ * Designed to be called inside useObjectAnimation so that AnimatedObject stays
+ * a thin group wrapper.
+ */
+export declare const useSequenceAnimation: (objectId: string | undefined, objectRef: Object3D | null | undefined) => void;
+export default useSequenceAnimation;
+//# sourceMappingURL=useSequenceAnimation.d.ts.map

package/dist/hooks/useSequenceAnimation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSequenceAnimation.d.ts","sourceRoot":"","sources":["../../src/hooks/useSequenceAnimation.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AA2BtC;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAAI,UAAU,MAAM,GAAG,SAAS,EAAE,WAAW,QAAQ,GAAG,IAAI,GAAG,SAAS,KAAG,IAyN3G,CAAC;AACF,eAAe,oBAAoB,CAAC"}