@3driseai/3drise-viewer 0.1.1

package/dist/hooks/useContinuousEffects.js

@@ -0,0 +1,177 @@
+import { useRef, useEffect } from "react";
+import { useFrame } from "@react-three/fiber";
+import { animateUniforms, cacheChildrenWithMaterials, handleEdgesAnimations, handleMaterialAnimations, handleMaterialEffects, handleTransformAnimations, handleTransformEffect } from "@3driseai/3drise-core";
+import usePathAnimation from "./usePathAnimation.js";
+// ═══════════════════════════════════════════════════════════════════════════════
+// DEBUG LOGGING
+// ═══════════════════════════════════════════════════════════════════════════════
+export const DEBUG_CONTINUOUS_EFFECTS = false;
+const log = (message, ...args) => {
+    if (DEBUG_CONTINUOUS_EFFECTS) {
+        console.log(`[ObjectAnimations] ${message}`, ...args);
+    }
+};
+export const useContinuousEffects = (
+// object: Object3D | null,
+objectSettings, options = {}, object) => {
+    const { enabled = true, animateMaterial = true, hovered = false } = options;
+    // console.log("useObjectAnimation called with:", {
+    //     object
+    // });
+    // const { object } = ref || {};
+    // Path animation hook for animations with pathId
+    const { startPathAnimation, updatePathAnimation, isAnimating: isPathAnimating, stopPathAnimation, } = usePathAnimation();
+    // ─────────────────────────────────────────────────────────────────────────────
+    // REFS
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Track which path animation is currently active
+    const activePathIdRef = useRef(null);
+    const effectStateRef = useRef(null);
+    // Cache children with materials to avoid traverse() every frame
+    const childrenWithMaterialsRef = useRef([]);
+    const lastObjectRef = useRef(null);
+    // Cache start values for material animations
+    const startValuesRef = useRef({});
+    // Cache start values for edges animations
+    const edgesStartValuesRef = useRef({});
+    // ─────────────────────────────────────────────────────────────────────────────
+    // DERIVED STATE (read from new continuous structure)
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Transform domain - now supports multiple effects (one per category)
+    const transformAnimations = objectSettings?.animations?.transform?.animations || [];
+    const transformEffects = objectSettings?.animations?.transform?.effects || [];
+    const enabledTransformEffects = transformEffects.filter(effect => effect.enabled);
+    const hasTransformEffects = enabledTransformEffects.length > 0;
+    const speed = objectSettings?.config?.speed ?? 1;
+    // Skip transform animations if any effect is enabled (effects take precedence)
+    const activeTransformAnimations = hasTransformEffects ? [] : transformAnimations;
+    const hasTransformAnimations = activeTransformAnimations.length > 0;
+    // Edges domain
+    const edgesAnimations = objectSettings?.animations?.edges?.animations || [];
+    const hasEdgesAnimations = edgesAnimations.length > 0;
+    // const effectsAnimations = objectSettings?.effects?.animations || [];
+    // const hasEffectsAnimations = effectsAnimations.length > 0;
+    // Material domain
+    const materialAnimations = objectSettings?.animations?.material?.animations || [];
+    const materialEffects = objectSettings?.animations?.material?.effects || [];
+    const enabledMaterialEffects = materialEffects.filter(effect => effect.enabled);
+    const hasMaterialEffects = enabledMaterialEffects.length > 0;
+    // Skip material animations if any effect is enabled (effects take precedence)
+    const activeMaterialAnimations = hasMaterialEffects ? [] : materialAnimations;
+    const hasMaterialAnimations = activeMaterialAnimations.length > 0;
+    // Combined check for any animations
+    const hasAnimations = hasTransformAnimations || hasMaterialAnimations;
+    // Continuous effects config
+    const applyToChildren = false;
+    // ─────────────────────────────────────────────────────────────────────────────
+    // CACHE CHILDREN WITH MATERIALS
+    // ─────────────────────────────────────────────────────────────────────────────
+    useEffect(() => {
+        if (!object || object === lastObjectRef.current)
+            return;
+        lastObjectRef.current = object;
+        childrenWithMaterialsRef.current = cacheChildrenWithMaterials(object);
+        log('cached children with materials', {
+            count: childrenWithMaterialsRef.current.length,
+            objectName: object.name
+        });
+        // Reset start values cache when object changes
+        startValuesRef.current = {};
+        edgesStartValuesRef.current = {};
+    }, [object]);
+    // ─────────────────────────────────────────────────────────────────────────────
+    // PATH ANIMATION LIFECYCLE
+    // ─────────────────────────────────────────────────────────────────────────────
+    useEffect(() => {
+        if (!enabled || !object)
+            return;
+        // Path animations come from transform.animations
+        const animations = objectSettings?.animations?.transform?.animations || [];
+        const pathAnimation = animations.find(anim => anim.pathId && anim.active);
+        if (pathAnimation?.pathId) {
+            // Start path animation if not already active or if pathId changed
+            if (activePathIdRef.current !== pathAnimation.pathId) {
+                activePathIdRef.current = pathAnimation.pathId;
+                log('starting path animation', { pathId: pathAnimation.pathId, duration: pathAnimation.duration });
+                startPathAnimation(pathAnimation.pathId, pathAnimation.duration / 1000, {
+                    ease: pathAnimation.ease,
+                    loop: pathAnimation.loop,
+                    yoyo: pathAnimation.yoyo,
+                    applyRotation: pathAnimation.applyRotation,
+                    offset: pathAnimation.offset,
+                    keepOriginalTransform: pathAnimation.keepOriginalTransform,
+                });
+            }
+        }
+        else if (activePathIdRef.current) {
+            // Stop path animation if no longer active
+            // log('stopping path animation', { pathId: activePathIdRef.current });
+            stopPathAnimation();
+            activePathIdRef.current = null;
+        }
+    }, [enabled, objectSettings?.animations?.transform?.animations, object, startPathAnimation, stopPathAnimation]);
+    // console.log(objectSettings?.meshSettings.name, hovered)
+    useFrame((state, delta) => {
+        // console.log({
+        //   enabled,
+        //   object,
+        //   objectSettings,
+        // })
+        if (!enabled || !object || !objectSettings)
+            return;
+        const time = state.clock.getElapsedTime();
+        const mouse = state.pointer;
+        const currentTime = Date.now();
+        // Update path animation if active
+        const pathIsActive = isPathAnimating();
+        if (pathIsActive) {
+            updatePathAnimation(delta, object);
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // TRANSFORM DOMAIN
+        // ─────────────────────────────────────────────────────────────────────────
+        if (hasTransformAnimations) {
+            handleTransformAnimations({
+                object,
+                meshSettings: objectSettings.meshSettings || {},
+                pathIsActive,
+            }, activeTransformAnimations, currentTime, hovered);
+        }
+        // Handle transform effect (wave, float, spin, etc.) - now supports multiple effects
+        if (hasTransformEffects) {
+            handleTransformEffect(object, enabledTransformEffects, time, delta, effectStateRef, hovered);
+        }
+        if (hasEdgesAnimations) {
+            handleEdgesAnimations({ object, startValuesCache: edgesStartValuesRef.current }, edgesAnimations, currentTime, hovered);
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // MATERIAL DOMAIN
+        // ─────────────────────────────────────────────────────────────────────────
+        if (animateMaterial) {
+            // Handle material animations (any material property)
+            if (hasMaterialAnimations) {
+                handleMaterialAnimations({
+                    object,
+                    materialSettings: objectSettings.materialSettings || {},
+                    startValuesCache: startValuesRef.current,
+                }, activeMaterialAnimations, currentTime, hovered);
+            }
+            // Handle material effects (color effects)
+            if (enabledMaterialEffects.length > 0) {
+                handleMaterialEffects(object, enabledMaterialEffects, time, delta, effectStateRef, applyToChildren);
+            }
+            // ─────────────────────────────────────────────────────────────────────────
+            // EDGES DOMAIN
+            // ─────────────────────────────────────────────────────────────────────────
+            // Animate uniforms (u_time, u_mouse, u_camera_position)
+            // console.log(time)
+        }
+        // console.log(enabled)
+        animateUniforms(childrenWithMaterialsRef.current, time * speed, mouse, state.camera.position);
+    });
+    return {
+        isPathAnimating,
+        effectStateRef,
+    };
+};
+export default useContinuousEffects;

package/dist/hooks/useCubeCamera.d.ts

@@ -0,0 +1,18 @@
+import * as THREE from 'three';
+import type { TimeSettings, HdrSettings } from '@3driseai/3drise-core';
+export interface UseCubeCameraOptions {
+    hdrSettings: HdrSettings;
+    skyVisible: boolean;
+    sunSystemVisible: boolean;
+    timeSettings: TimeSettings;
+    resolution?: number;
+    position?: THREE.Vector3;
+    onEnvironmentUpdate?: (texture: THREE.Texture) => void;
+}
+export declare const useCubeCamera: (options: UseCubeCameraOptions) => {
+    cubeCamera: THREE.CubeCamera | null;
+    updateEnvironment: () => THREE.Texture | null;
+    initializeCubeCamera: () => THREE.CubeCamera | null;
+    dispose: () => void;
+};
+//# sourceMappingURL=useCubeCamera.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useCubeCamera.d.ts","sourceRoot":"","sources":["../../src/hooks/useCubeCamera.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACvE,MAAM,WAAW,oBAAoB;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC;IACpB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,YAAY,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,KAAK,IAAI,CAAC;CAC1D;AAED,eAAO,MAAM,aAAa,GAAI,SAAS,oBAAoB,KAAG;IACtD,UAAU,EAAE,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC;IACpC,iBAAiB,EAAE,MAAM,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;IAC9C,oBAAoB,EAAE,MAAM,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC;IACpD,OAAO,EAAE,MAAM,IAAI,CAAC;CAqE3B,CAAC"}

package/dist/hooks/useCubeCamera.js

@@ -0,0 +1,73 @@
+import { useRef, useCallback, useEffect } from 'react';
+import { useThree, useFrame } from '@react-three/fiber';
+import * as THREE from 'three';
+import { createCubeCamera, updateCubeCamera, disposeCubeCamera, setSceneEnvironment, clearSceneEnvironment, } from '@3driseai/3drise-core';
+export const useCubeCamera = (options) => {
+    const { hdrSettings, skyVisible, sunSystemVisible, timeSettings, resolution = 512, position = new THREE.Vector3(0, 50, 0), onEnvironmentUpdate } = options;
+    const { scene, gl: renderer } = useThree();
+    const cubeCameraRef = useRef(null);
+    const isUpdatingRef = useRef(false);
+    const hdrActive = hdrSettings.visible && (hdrSettings.name || (hdrSettings.urls && hdrSettings.urls.length > 0)) ? true : false;
+    const initializeCubeCamera = useCallback(() => {
+        if (!renderer || !scene)
+            return null;
+        if (cubeCameraRef.current)
+            disposeCubeCamera(cubeCameraRef.current, scene);
+        cubeCameraRef.current = createCubeCamera(scene, resolution, position);
+        return cubeCameraRef.current;
+    }, [scene, renderer, resolution, position]);
+    const updateEnvironment = useCallback(() => {
+        if (!cubeCameraRef.current || !renderer || !scene)
+            return null;
+        if (isUpdatingRef.current)
+            return null;
+        try {
+            isUpdatingRef.current = true;
+            const texture = updateCubeCamera(cubeCameraRef.current, renderer, scene);
+            setSceneEnvironment(scene, texture);
+            onEnvironmentUpdate?.(texture);
+            return texture;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            isUpdatingRef.current = false;
+        }
+    }, [scene, renderer, onEnvironmentUpdate]);
+    const dispose = useCallback(() => {
+        if (cubeCameraRef.current && scene) {
+            disposeCubeCamera(cubeCameraRef.current, scene);
+            cubeCameraRef.current = null;
+        }
+    }, [scene]);
+    // Create or dispose cube camera based on active sky / HDR state
+    useEffect(() => {
+        if (hdrActive) {
+            dispose();
+            return;
+        }
+        if (skyVisible || sunSystemVisible) {
+            initializeCubeCamera();
+            updateEnvironment();
+        }
+        else {
+            dispose();
+            clearSceneEnvironment(scene);
+        }
+    }, [hdrActive, skyVisible, sunSystemVisible]);
+    // Live update when auto-animating (sky moves, environment changes)
+    const UPDATE_INTERVAL_MS = 300;
+    useFrame((state) => {
+        if (hdrActive || !(skyVisible || sunSystemVisible))
+            return;
+        if (!timeSettings.autoAnimate)
+            return;
+        if (state.clock.getElapsedTime() * 1000 > UPDATE_INTERVAL_MS) {
+            updateEnvironment();
+        }
+    });
+    // Cleanup on unmount
+    useEffect(() => () => dispose(), [dispose]);
+    return { cubeCamera: cubeCameraRef.current, updateEnvironment, initializeCubeCamera, dispose };
+};

package/dist/hooks/useEnvironmentEffects.d.ts

@@ -0,0 +1,12 @@
+import type { TimeSettings } from '@3driseai/3drise-core';
+export interface UseEnvironmentEffectsOptions {
+    updateEnvironment: () => void;
+    skyVisible: boolean;
+    sunSystemVisible: boolean;
+    timeSettings: TimeSettings;
+    updateDelay?: number;
+}
+export declare const useEnvironmentEffects: (options: UseEnvironmentEffectsOptions) => {
+    triggerUpdate: () => void;
+};
+//# sourceMappingURL=useEnvironmentEffects.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useEnvironmentEffects.d.ts","sourceRoot":"","sources":["../../src/hooks/useEnvironmentEffects.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,MAAM,WAAW,4BAA4B;IACzC,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,UAAU,EAAE,OAAO,CAAC;IACpB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,YAAY,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,qBAAqB,GAAI,SAAS,4BAA4B,KAAG;IACtE,aAAa,EAAE,MAAM,IAAI,CAAC;CAoBjC,CAAC"}

package/dist/hooks/useEnvironmentEffects.js

@@ -0,0 +1,22 @@
+import { useRef, useCallback, useEffect } from 'react';
+import { createDebouncedUpdate } from '@3driseai/3drise-core';
+export const useEnvironmentEffects = (options) => {
+    const { updateEnvironment, skyVisible, sunSystemVisible, timeSettings, updateDelay = 50 } = options;
+    const debouncedUpdate = useRef(createDebouncedUpdate(updateEnvironment, updateDelay));
+    useEffect(() => {
+        debouncedUpdate.current = createDebouncedUpdate(updateEnvironment, updateDelay);
+    }, [updateEnvironment, updateDelay]);
+    // Trigger debounced update when sky visibility changes
+    useEffect(() => {
+        debouncedUpdate.current();
+    }, [skyVisible, sunSystemVisible]);
+    // Trigger update when time settings change
+    useEffect(() => {
+        if (timeSettings.enabled)
+            updateEnvironment();
+    }, [timeSettings, updateEnvironment]);
+    const triggerUpdate = useCallback(() => {
+        updateEnvironment();
+    }, [updateEnvironment]);
+    return { triggerUpdate };
+};

package/dist/hooks/useFrameAnimations.d.ts

@@ -0,0 +1,24 @@
+import * as THREE from "three";
+import type { CameraState, Vector2Array } from "@3driseai/3drise-core";
+interface FrameAnimationOptions {
+    distance?: number;
+    scale?: Vector2Array;
+    duration?: number;
+    ease?: string;
+    onComplete?: () => void;
+    onStart?: () => void;
+}
+/**
+ * Custom hook for frame animations (moveToFront and zoom)
+ * Can be used in any component that needs to animate frames
+ */
+export declare const useFrameAnimations: (cameraSettings: CameraState) => {
+    moveToFront: (object: THREE.Object3D, options?: FrameAnimationOptions) => void;
+    zoomToFrame: (object: THREE.Object3D, options?: FrameAnimationOptions) => void;
+    restoreOriginalTransform: (object: THREE.Object3D, options?: FrameAnimationOptions) => void;
+    storeOriginalTransform: (object: THREE.Object3D) => void;
+    restoreCamera: (options?: FrameAnimationOptions) => void;
+    storeOriginalCameraState: () => void;
+};
+export default useFrameAnimations;
+//# sourceMappingURL=useFrameAnimations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useFrameAnimations.d.ts","sourceRoot":"","sources":["../../src/hooks/useFrameAnimations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACvE,UAAU,qBAAqB;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AASD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,gBAAgB,WAAW,KAAG;IACzD,WAAW,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC/E,WAAW,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC/E,wBAAwB,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC5F,sBAAsB,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC;IACzD,aAAa,EAAE,CAAC,OAAO,CAAC,EAAE,qBAAqB,KAAK,IAAI,CAAC;IACzD,wBAAwB,EAAE,MAAM,IAAI,CAAC;CAyM5C,CAAC;AACF,eAAe,kBAAkB,CAAC"}

package/dist/hooks/useFrameAnimations.js

@@ -0,0 +1,217 @@
+import * as THREE from "three";
+import { useRef } from "react";
+import cameraManager from "../utils/CameraSingleton.js";
+import { useGsapAnimation } from "../hooks/useGsapAnimation.js";
+import useCameraAnimation from "./useCameraAnimation.js";
+const DEFAULT_OPTIONS = {
+    distance: 5,
+    scale: [2, 2],
+    duration: 1.0,
+    ease: "power2.out"
+};
+/**
+ * Custom hook for frame animations (moveToFront and zoom)
+ * Can be used in any component that needs to animate frames
+ */
+export const useFrameAnimations = (cameraSettings) => {
+    const { animateObjects } = useGsapAnimation();
+    const { animateCamera } = useCameraAnimation({
+        autoAnimate: false,
+        defaultDuration: 1.0,
+        defaultEase: "power2.out"
+    });
+    // Store original transforms for each object by its UUID - use useRef to persist across renders
+    const originalTransformsRef = useRef(new Map());
+    const originalTransforms = originalTransformsRef.current;
+    // Store original camera state - use useRef to persist across renders
+    const originalCameraStateRef = useRef(null);
+    /**
+     * Stores the current camera position and controls target before animation
+     */
+    const storeOriginalCameraState = () => {
+        if (!originalCameraStateRef.current) {
+            const cameraPos = cameraManager.getPosition();
+            const currentTarget = cameraSettings.controls.target;
+            if (cameraPos && currentTarget) {
+                originalCameraStateRef.current = {
+                    position: cameraPos.clone(),
+                    target: new THREE.Vector3(currentTarget[0], currentTarget[1], currentTarget[2])
+                };
+            }
+        }
+    };
+    /**
+     * Restores the camera to its original position and controls target
+     * @param options - Configuration options for the animation
+     */
+    const restoreCamera = (options = {}) => {
+        const opts = { ...DEFAULT_OPTIONS, ...options };
+        const original = originalCameraStateRef.current;
+        if (!original) {
+            console.warn("No original camera state found");
+            return;
+        }
+        // Animate camera back to original position
+        animateCamera({
+            position: [original.position.x, original.position.y, original.position.z]
+        }, opts.duration, opts.ease, [original.target.x, original.target.y, original.target.z]).then(() => {
+            // Clear stored camera state after restoring
+            originalCameraStateRef.current = null;
+            opts.onComplete?.();
+        });
+        // Call onStart callback if provided
+        opts.onStart?.();
+    };
+    /**
+     * Stores the current transform of an object before animation
+     * @param object - The THREE.Group object to store transforms for
+     */
+    const storeOriginalTransform = (object) => {
+        if (!originalTransforms.has(object.uuid)) {
+            originalTransforms.set(object.uuid, {
+                position: object.position.clone(),
+                rotation: object.rotation.clone(),
+                scale: object.scale.clone()
+            });
+        }
+    };
+    /**
+     * Restores an object to its original transform
+     * @param object - The THREE.Group object to restore
+     * @param options - Configuration options for the animation
+     */
+    const restoreOriginalTransform = (object, options = {}) => {
+        const opts = { ...DEFAULT_OPTIONS, ...options };
+        const original = originalTransforms.get(object.uuid);
+        if (!original) {
+            console.warn("No original transform found for object", object.uuid);
+            return;
+        }
+        // Animate back to original transform
+        animateObjects([object], {
+            duration: opts.duration,
+            ease: opts.ease,
+            position: [original.position.x, original.position.y, original.position.z],
+            rotation: [original.rotation.x, original.rotation.y, original.rotation.z],
+            scale: [original.scale.x, original.scale.y, original.scale.z],
+            onComplete: () => {
+                // Remove from stored transforms after restoring
+                originalTransforms.delete(object.uuid);
+                opts.onComplete?.();
+            },
+            onStart: opts.onStart
+        });
+    };
+    /**
+     * Moves a frame to appear in front of the camera
+     * The frame will be positioned relative to the camera's current position and direction
+     * @param object - The THREE.Group object representing the frame
+     * @param options - Configuration options for the animation
+     */
+    const moveToFront = (object, options = {}) => {
+        const opts = { ...DEFAULT_OPTIONS, ...options };
+        // Store original transform before animating
+        storeOriginalTransform(object);
+        // Get camera information from singleton
+        const cameraPos = cameraManager.getPosition();
+        const cameraDirection = cameraManager.getWorldDirection();
+        if (!cameraPos || !cameraDirection) {
+            console.warn("Camera not available for moveToFront animation");
+            return;
+        }
+        // Calculate target position in world space (in front of camera)
+        const targetWorldPosition = cameraPos.clone()
+            .add(cameraDirection.multiplyScalar(opts.distance));
+        // Convert world position to local position relative to parent
+        const parent = object.parent;
+        const targetLocalPosition = targetWorldPosition.clone();
+        if (parent) {
+            parent.worldToLocal(targetLocalPosition);
+        }
+        // Calculate rotation to face camera in world space
+        const directionToCamera = new THREE.Vector3()
+            .subVectors(cameraPos, targetWorldPosition)
+            .normalize();
+        // Create world quaternion that faces the camera
+        const frameDefaultForward = new THREE.Vector3(0, 0, 1);
+        const worldQuaternion = new THREE.Quaternion().setFromUnitVectors(frameDefaultForward, directionToCamera);
+        // Convert world quaternion to local quaternion relative to parent
+        const localQuaternion = worldQuaternion.clone();
+        if (parent) {
+            const parentWorldQuaternion = new THREE.Quaternion();
+            parent.getWorldQuaternion(parentWorldQuaternion);
+            const parentWorldQuaternionInverse = parentWorldQuaternion.clone().invert();
+            localQuaternion.premultiply(parentWorldQuaternionInverse);
+        }
+        // Convert local quaternion to Euler angles for GSAP animation
+        const targetRotation = new THREE.Euler().setFromQuaternion(localQuaternion);
+        // Animate the frame using GSAP
+        animateObjects([object], {
+            duration: opts.duration,
+            ease: opts.ease,
+            position: [targetLocalPosition.x, targetLocalPosition.y, targetLocalPosition.z],
+            rotation: [targetRotation.x, targetRotation.y, targetRotation.z],
+            scale: [opts.scale[0], opts.scale[1], 1],
+            onComplete: opts.onComplete,
+            onStart: opts.onStart
+        });
+    };
+    /**
+     * Zooms the camera to focus on a specific frame
+     * The camera will move to a position in front of the frame from the current camera direction
+     * @param object - The THREE.Group object representing the frame
+     * @param options - Configuration options for the animation
+     */
+    const zoomToFrame = (object, options = {}) => {
+        const opts = { ...DEFAULT_OPTIONS, ...options };
+        // Store original camera state before animating
+        storeOriginalCameraState();
+        // Get current camera position
+        const cameraPos = cameraManager.getPosition();
+        if (!cameraPos) {
+            console.warn("Camera not available for zoomToFrame animation");
+            return;
+        }
+        // Get frame's world position
+        const frameWorldPos = new THREE.Vector3();
+        object.getWorldPosition(frameWorldPos);
+        // Get frame's forward direction in world space (positive Z axis by default)
+        const frameForward = new THREE.Vector3(0, 0, 1);
+        const frameWorldQuaternion = new THREE.Quaternion();
+        object.getWorldQuaternion(frameWorldQuaternion);
+        frameForward.applyQuaternion(frameWorldQuaternion);
+        // Calculate the direction from frame to current camera position
+        const frameToCameraDirection = new THREE.Vector3()
+            .subVectors(cameraPos, frameWorldPos)
+            .normalize();
+        // Determine which side of the frame the camera is on
+        // by checking the dot product of the frame's forward vector and the frame-to-camera direction
+        const dotProduct = frameForward.dot(frameToCameraDirection);
+        // If dot product is negative, camera is on the back side, so flip the forward direction
+        const adjustedForward = frameForward.clone();
+        if (dotProduct < 0) {
+            adjustedForward.negate();
+        }
+        // Position camera in front of the frame on the same side as current camera position
+        const targetCameraPos = frameWorldPos.clone()
+            .add(adjustedForward.multiplyScalar(opts.distance));
+        // Animate camera to new position
+        animateCamera({
+            position: [targetCameraPos.x, targetCameraPos.y, targetCameraPos.z]
+        }, opts.duration, opts.ease, [frameWorldPos.x, frameWorldPos.y, frameWorldPos.z]).then(() => {
+            // Call onComplete callback if provided
+            opts.onComplete?.();
+        });
+        // Call onStart callback if provided
+        opts.onStart?.();
+    };
+    return {
+        moveToFront,
+        zoomToFrame,
+        restoreOriginalTransform,
+        storeOriginalTransform,
+        restoreCamera,
+        storeOriginalCameraState
+    };
+};
+export default useFrameAnimations;

package/dist/hooks/useFrameEffects.d.ts

@@ -0,0 +1,6 @@
+export declare function useFrameEffects(isActive: boolean): {
+    handlePointerEnter: (e: any) => void;
+    handlePointerLeave: () => void;
+    hovered: boolean;
+};
+//# sourceMappingURL=useFrameEffects.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useFrameEffects.d.ts","sourceRoot":"","sources":["../../src/hooks/useFrameEffects.ts"],"names":[],"mappings":"AACA,wBAAgB,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG;IAC5C,kBAAkB,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;IACrC,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;CACpB,CAiBJ"}

package/dist/hooks/useFrameEffects.js

@@ -0,0 +1,19 @@
+import { useCallback, useState, useRef } from "react";
+export function useFrameEffects(isActive) {
+    const [hovered, setHovered] = useState(false);
+    const hoveredRef = useRef(false);
+    const handlePointerEnter = useCallback((e) => {
+        e.stopPropagation();
+        if (!isActive && !hoveredRef.current) {
+            hoveredRef.current = true;
+            setHovered(true);
+        }
+    }, [isActive]);
+    const handlePointerLeave = useCallback(() => {
+        if (!isActive && hoveredRef.current) {
+            hoveredRef.current = false;
+            setHovered(false);
+        }
+    }, [isActive]);
+    return { handlePointerEnter, handlePointerLeave, hovered };
+}