@hua-labs/motion-core 2.2.2 → 2.3.0

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import * as react from 'react';
-import { CSSProperties, RefObject } from 'react';
+import react__default, { CSSProperties, RefObject } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
  * HUA Motion Core - 의존성 제로 모션 엔진
@@ -35,7 +36,7 @@ interface MotionOptions {
     onComplete?: () => void;
     onCancel?: () => void;
 }
-interface Motion {
+interface Motion$1 {
     id: string;
     element: HTMLElement;
     isRunning: boolean;
@@ -72,7 +73,7 @@ declare class MotionEngine {
     /**
      * 모션 상태 확인
      */
-    getMotion(motionId: string): Motion | undefined;
+    getMotion(motionId: string): Motion$1 | undefined;
     /**
      * 실행 중인 모션 수
      */
@@ -133,6 +134,10 @@ declare class TransitionEffects {
     private static instance;
     private activeTransitions;
     static getInstance(): TransitionEffects;
+    /**
+     * 공통 전환 실행 헬퍼
+     */
+    private executeTransition;
     /**
      * 페이드 인/아웃 전환
      */
@@ -188,130 +193,6 @@ declare class TransitionEffects {
 }
 declare const transitionEffects: TransitionEffects;
 
-/**
- * HUA Motion Core - 성능 최적화 시스템
- *
- * GPU 가속, 레이어 관리, 메모리 최적화를 위한 유틸리티들
- * 브라우저별 최적화 전략 포함
- */
-interface PerformanceOptimizerMetrics {
-    fps: number;
-    memoryUsage?: number;
-    gpuTime?: number;
-    cpuTime?: number;
-    layerCount: number;
-    activeMotions: number;
-}
-interface OptimizationConfig {
-    enableGPUAcceleration: boolean;
-    enableLayerSeparation: boolean;
-    enableMemoryOptimization: boolean;
-    targetFPS: number;
-    maxLayerCount: number;
-    memoryThreshold: number;
-}
-declare class PerformanceOptimizer {
-    private static instance;
-    private config;
-    private performanceObserver;
-    private metrics;
-    private layerRegistry;
-    private isMonitoring;
-    constructor();
-    static getInstance(): PerformanceOptimizer;
-    /**
-     * 성능 모니터링 초기화
-     */
-    private initializePerformanceMonitoring;
-    /**
-     * 성능 메트릭 업데이트
-     */
-    private updatePerformanceMetrics;
-    /**
-     * FPS 계산
-     */
-    private calculateFPS;
-    /**
-     * GPU 가속 활성화
-     */
-    enableGPUAcceleration(element: HTMLElement): void;
-    /**
-     * 레이어 분리 및 최적화
-     */
-    createOptimizedLayer(element: HTMLElement): void;
-    /**
-     * 레이어 등록
-     */
-    private registerLayer;
-    /**
-     * 레이어 제거
-     */
-    removeLayer(element: HTMLElement): void;
-    /**
-     * 레이어 수 제한 체크
-     */
-    private checkLayerLimit;
-    /**
-     * 오래된 레이어 정리
-     */
-    private cleanupOldLayers;
-    /**
-     * 메모리 사용량 체크
-     */
-    private checkMemoryUsage;
-    /**
-     * 메모리 정리
-     */
-    private cleanupMemory;
-    /**
-     * 성능 최적화 설정 업데이트
-     */
-    updateConfig(newConfig: Partial<OptimizationConfig>): void;
-    /**
-     * 모든 GPU 가속 비활성화
-     */
-    private disableAllGPUAcceleration;
-    /**
-     * 모든 레이어 비활성화
-     */
-    private disableAllLayers;
-    /**
-     * 성능 메트릭 가져오기
-     */
-    getMetrics(): PerformanceOptimizerMetrics;
-    /**
-     * 성능 모니터링 시작
-     */
-    startMonitoring(): void;
-    /**
-     * 성능 모니터링 중지
-     */
-    stopMonitoring(): void;
-    /**
-     * 메트릭 업데이트
-     */
-    private updateMetrics;
-    /**
-     * 성능 리포트 생성
-     */
-    generateReport(): string;
-    /**
-     * 바이트 단위 포맷팅
-     */
-    private formatBytes;
-    /**
-     * 성능 최적화 권장사항
-     */
-    getOptimizationRecommendations(): string[];
-    /**
-     * 정리
-     */
-    destroy(): void;
-    private lastFrameTime?;
-    private monitoringInterval?;
-}
-declare const performanceOptimizer: PerformanceOptimizer;
-
 type MotionElement = HTMLDivElement | HTMLSpanElement | HTMLButtonElement | HTMLHeadingElement | HTMLParagraphElement | HTMLImageElement;
 type MotionStyle = CSSProperties & {
     '--motion-delay'?: string;
@@ -588,7 +469,7 @@ interface MotionPreset {
 interface PresetConfig {
     [key: string]: MotionPreset;
 }
-interface SpringConfig {
+interface SpringConfig$1 {
     mass?: number;
     stiffness?: number;
     damping?: number;
@@ -677,9 +558,25 @@ declare function useSmartMotion<T extends HTMLElement = HTMLDivElement>(options?
  * 내부에서 선택된 type에 맞는 로직만 실행 (6개 훅 동시 호출 제거)
  */
 
+interface MotionEffects {
+    fade?: boolean | {
+        targetOpacity?: number;
+    };
+    slide?: boolean | {
+        direction?: 'up' | 'down' | 'left' | 'right';
+        distance?: number;
+    };
+    scale?: boolean | {
+        from?: number;
+        to?: number;
+    };
+    bounce?: boolean;
+}
 interface UseUnifiedMotionOptions extends Omit<BaseMotionOptions, 'autoStart'> {
-    /** Motion type to use */
-    type: EntranceType;
+    /** Motion type to use (single effect mode) */
+    type?: EntranceType;
+    /** Multiple effects to combine (multi-effect mode) */
+    effects?: MotionEffects;
     /** Auto start animation @default true */
     autoStart?: boolean;
     /** Slide distance (px) for slide types @default 50 */
@@ -1044,6 +941,383 @@ declare function useGestureMotion(options: GestureMotionOptions): {
     isActive: boolean;
 };
 
+interface ButtonEffectOptions extends BaseMotionOptions {
+    type?: 'scale' | 'ripple' | 'glow' | 'shake' | 'bounce' | 'slide' | 'custom';
+    scaleAmount?: number;
+    rippleColor?: string;
+    rippleSize?: number;
+    rippleDuration?: number;
+    glowColor?: string;
+    glowSize?: number;
+    glowIntensity?: number;
+    shakeAmount?: number;
+    shakeFrequency?: number;
+    bounceHeight?: number;
+    bounceStiffness?: number;
+    slideDistance?: number;
+    slideDirection?: 'left' | 'right' | 'up' | 'down';
+    hoverScale?: number;
+    hoverRotate?: number;
+    hoverTranslateY?: number;
+    hoverTranslateX?: number;
+    activeScale?: number;
+    activeRotate?: number;
+    activeTranslateY?: number;
+    activeTranslateX?: number;
+    focusScale?: number;
+    focusGlow?: boolean;
+    disabled?: boolean;
+    disabledOpacity?: number;
+    autoStart?: boolean;
+}
+declare function useButtonEffect<T extends MotionElement = HTMLButtonElement>(options?: ButtonEffectOptions): BaseMotionReturn<T> & {
+    buttonType: string;
+    isPressed: boolean;
+    isHovered: boolean;
+    isFocused: boolean;
+    ripplePosition: {
+        x: number;
+        y: number;
+    };
+    currentGlowIntensity: number;
+    shakeOffset: number;
+    bounceOffset: number;
+    slideOffset: number;
+    pressButton: () => void;
+    releaseButton: () => void;
+    setButtonState: (state: 'idle' | 'hover' | 'active' | 'focus' | 'disabled') => void;
+};
+
+interface VisibilityToggleOptions extends BaseMotionOptions {
+    showScale?: number;
+    showOpacity?: number;
+    showRotate?: number;
+    showTranslateY?: number;
+    showTranslateX?: number;
+    hideScale?: number;
+    hideOpacity?: number;
+    hideRotate?: number;
+    hideTranslateY?: number;
+    hideTranslateX?: number;
+}
+declare function useVisibilityToggle<T extends MotionElement = HTMLDivElement>(options?: VisibilityToggleOptions): InteractionReturn<T>;
+
+interface ScrollToggleOptions extends BaseMotionOptions {
+    showScale?: number;
+    showOpacity?: number;
+    showRotate?: number;
+    showTranslateY?: number;
+    showTranslateX?: number;
+    hideScale?: number;
+    hideOpacity?: number;
+    hideRotate?: number;
+    hideTranslateY?: number;
+    hideTranslateX?: number;
+    scrollThreshold?: number;
+    scrollDirection?: 'up' | 'down' | 'both';
+}
+declare function useScrollToggle<T extends MotionElement = HTMLDivElement>(options?: ScrollToggleOptions): BaseMotionReturn<T>;
+
+interface CardListOptions extends BaseMotionOptions {
+    staggerDelay?: number;
+    cardScale?: number;
+    cardOpacity?: number;
+    cardRotate?: number;
+    cardTranslateY?: number;
+    cardTranslateX?: number;
+    initialScale?: number;
+    initialOpacity?: number;
+    initialRotate?: number;
+    initialTranslateY?: number;
+    initialTranslateX?: number;
+    gridColumns?: number;
+    gridGap?: number;
+}
+declare function useCardList<T extends MotionElement = HTMLDivElement>(options?: CardListOptions): BaseMotionReturn<T> & {
+    cardStyles: React.CSSProperties[];
+    staggerDelay: number;
+    gridColumns: number;
+    gridGap: number;
+};
+
+interface LoadingSpinnerOptions extends BaseMotionOptions {
+    type?: 'rotate' | 'pulse' | 'bounce' | 'wave' | 'dots' | 'bars' | 'custom';
+    rotationSpeed?: number;
+    pulseSpeed?: number;
+    bounceHeight?: number;
+    waveCount?: number;
+    dotCount?: number;
+    barCount?: number;
+    color?: string;
+    backgroundColor?: string;
+    size?: number;
+    thickness?: number;
+    autoStart?: boolean;
+    infinite?: boolean;
+}
+declare function useLoadingSpinner<T extends MotionElement = HTMLDivElement>(options?: LoadingSpinnerOptions): BaseMotionReturn<T> & {
+    isLoading: boolean;
+    spinnerType: string;
+    rotationAngle: number;
+    pulseScale: number;
+    bounceOffset: number;
+    waveProgress: number;
+    dotProgress: number;
+    barProgress: number;
+    startLoading: () => void;
+    stopLoading: () => void;
+    setLoadingState: (loading: boolean) => void;
+};
+
+interface NavigationOptions extends BaseMotionOptions {
+    type?: 'slide' | 'fade' | 'scale' | 'rotate' | 'custom';
+    slideDirection?: 'left' | 'right' | 'up' | 'down';
+    staggerDelay?: number;
+    itemScale?: number;
+    itemOpacity?: number;
+    itemRotate?: number;
+    itemTranslateY?: number;
+    itemTranslateX?: number;
+    initialScale?: number;
+    initialOpacity?: number;
+    initialRotate?: number;
+    initialTranslateY?: number;
+    initialTranslateX?: number;
+    activeScale?: number;
+    activeOpacity?: number;
+    activeRotate?: number;
+    activeTranslateY?: number;
+    activeTranslateX?: number;
+    hoverScale?: number;
+    hoverOpacity?: number;
+    hoverRotate?: number;
+    hoverTranslateY?: number;
+    hoverTranslateX?: number;
+    itemCount?: number;
+    autoStart?: boolean;
+}
+declare function useNavigation<T extends MotionElement = HTMLDivElement>(options?: NavigationOptions): BaseMotionReturn<T> & {
+    isOpen: boolean;
+    activeIndex: number;
+    itemStyles: React.CSSProperties[];
+    openMenu: () => void;
+    closeMenu: () => void;
+    toggleMenu: () => void;
+    setActiveItem: (index: number) => void;
+    goToNext: () => void;
+    goToPrevious: () => void;
+};
+
+interface SkeletonOptions extends BaseMotionOptions {
+    /** 스켈레톤 배경색 */
+    backgroundColor?: string;
+    /** 스켈레톤 하이라이트 색상 */
+    highlightColor?: string;
+    /** 모션 속도 (ms) */
+    motionSpeed?: number;
+    /** 스켈레톤 높이 */
+    height?: number;
+    /** 스켈레톤 너비 */
+    width?: number | string;
+    /** 보더 반지름 */
+    borderRadius?: number;
+    /** 웨이브 모션 활성화 여부 */
+    wave?: boolean;
+    /** 펄스 모션 활성화 여부 */
+    pulse?: boolean;
+}
+declare function useSkeleton<T extends MotionElement = HTMLDivElement>(options?: SkeletonOptions): BaseMotionReturn<T>;
+
+interface TypewriterOptions {
+    /** 타이핑할 텍스트 */
+    text: string;
+    /** 글자당 딜레이 (ms) @default 50 */
+    speed?: number;
+    /** 시작 딜레이 (ms) @default 0 */
+    delay?: number;
+    /** 활성화 여부 @default true */
+    enabled?: boolean;
+    /** 완료 콜백 */
+    onComplete?: () => void;
+}
+interface TypewriterReturn {
+    /** 현재 표시 중인 텍스트 */
+    displayText: string;
+    /** 타이핑 진행 중 여부 */
+    isTyping: boolean;
+    /** 진행률 (0-1) */
+    progress: number;
+    /** 타이핑 재시작 */
+    restart: () => void;
+}
+/**
+ * useTypewriter - 타이핑 효과 훅
+ *
+ * @example
+ * ```tsx
+ * const { displayText, isTyping } = useTypewriter({ text: 'Hello, world!' })
+ * return <h1>{displayText}<span className="animate-pulse">|</span></h1>
+ * ```
+ */
+declare function useTypewriter(options: TypewriterOptions): TypewriterReturn;
+
+interface CustomCursorOptions {
+    /** 활성화 여부 @default true */
+    enabled?: boolean;
+    /** 커서 크기 (px) @default 32 */
+    size?: number;
+    /** 스프링 스무딩 (0-1, 낮을수록 부드러움) @default 0.15 */
+    smoothing?: number;
+    /** 호버 시 스케일 @default 1.5 */
+    hoverScale?: number;
+    /** data-cursor 속성 요소 감지 @default true */
+    detectLabels?: boolean;
+}
+interface CustomCursorReturn {
+    /** 커서 x 좌표 (smoothed) */
+    x: number;
+    /** 커서 y 좌표 (smoothed) */
+    y: number;
+    /** 호버 중인 요소의 data-cursor 값 */
+    label: string | null;
+    /** 호버 상태 여부 */
+    isHovering: boolean;
+    /** 커서 스타일 (CSS variables 포함) */
+    style: CSSProperties;
+    /** 커서 가시 여부 */
+    isVisible: boolean;
+}
+/**
+ * useCustomCursor - 커스텀 커서 효과 훅
+ *
+ * 마우스를 따라다니는 커스텀 커서를 구현합니다.
+ * 스프링 보간으로 부드러운 추적, data-cursor 라벨 감지.
+ *
+ * @example
+ * ```tsx
+ * const cursor = useCustomCursor()
+ * return (
+ *   <>
+ *     <div style={cursor.style} className="custom-cursor" />
+ *     <button data-cursor="Click me">Hover me</button>
+ *   </>
+ * )
+ * ```
+ */
+declare function useCustomCursor(options?: CustomCursorOptions): CustomCursorReturn;
+
+interface MagneticCursorOptions {
+    /** 자석 끌림 강도 (0-1) @default 0.3 */
+    strength?: number;
+    /** 자석 작동 반경 (px) @default 100 */
+    radius?: number;
+    /** 활성화 여부 @default true */
+    enabled?: boolean;
+}
+interface MagneticCursorReturn<T extends HTMLElement = HTMLElement> {
+    /** 자석 대상 요소에 연결할 ref */
+    ref: React.RefObject<T | null>;
+    /** 마우스 이벤트 핸들러 */
+    handlers: {
+        onMouseMove: (e: React.MouseEvent) => void;
+        onMouseLeave: () => void;
+    };
+    /** 요소에 적용할 transform 스타일 */
+    style: CSSProperties;
+}
+/**
+ * useMagneticCursor - 자석 커서 효과 훅
+ *
+ * 마우스가 요소 근처에 오면 요소가 마우스 쪽으로 끌려오는 효과.
+ * 버튼, 아이콘 등에 적용하면 인터랙티브 느낌 향상.
+ *
+ * @example
+ * ```tsx
+ * const magnetic = useMagneticCursor<HTMLButtonElement>({ strength: 0.4 })
+ * return <button ref={magnetic.ref} style={magnetic.style} {...magnetic.handlers}>Click</button>
+ * ```
+ */
+declare function useMagneticCursor<T extends HTMLElement = HTMLElement>(options?: MagneticCursorOptions): MagneticCursorReturn<T>;
+
+interface SmoothScrollOptions {
+    /** 활성화 여부 @default true */
+    enabled?: boolean;
+    /** 스무딩 계수 (0-1, 낮을수록 부드러움) @default 0.1 */
+    lerp?: number;
+    /** 마우스 휠 배율 @default 1 */
+    wheelMultiplier?: number;
+    /** 터치 배율 @default 2 */
+    touchMultiplier?: number;
+    /** 방향 @default 'vertical' */
+    direction?: 'vertical' | 'horizontal';
+    /** 콜백: 스크롤 값 변경 시 */
+    onScroll?: (scroll: number) => void;
+}
+interface SmoothScrollReturn {
+    /** 현재 스크롤 위치 (smoothed) */
+    scroll: number;
+    /** 목표 스크롤 위치 */
+    targetScroll: number;
+    /** 스크롤 진행률 (0-1) */
+    progress: number;
+    /** 특정 위치로 스크롤 */
+    scrollTo: (target: number | HTMLElement, options?: {
+        offset?: number;
+    }) => void;
+    /** 스크롤 중지 */
+    stop: () => void;
+}
+/**
+ * useSmoothScroll - 부드러운 스크롤 훅
+ *
+ * lenis 스타일의 smooth scrolling. 네이티브 스크롤을 가로채서
+ * lerp 보간으로 부드러운 스크롤 경험을 제공합니다.
+ *
+ * @example
+ * ```tsx
+ * const { scroll, progress, scrollTo } = useSmoothScroll({ lerp: 0.08 })
+ * return <button onClick={() => scrollTo(document.getElementById('section')!)}>Go</button>
+ * ```
+ */
+declare function useSmoothScroll(options?: SmoothScrollOptions): SmoothScrollReturn;
+
+interface ElementProgressOptions {
+    /** 요소가 뷰포트 아래에서 시작되는 위치 (0 = 하단, 1 = 상단) @default 0 */
+    start?: number;
+    /** 요소가 뷰포트 위에서 끝나는 위치 @default 1 */
+    end?: number;
+    /** 클램프 여부 @default true */
+    clamp?: boolean;
+}
+interface ElementProgressReturn<T extends HTMLElement = HTMLElement> {
+    /** 대상 요소 ref */
+    ref: React.RefObject<T | null>;
+    /** 요소의 스크롤 진행률 (0-1) */
+    progress: number;
+    /** 요소가 뷰포트 안에 있는지 */
+    isInView: boolean;
+}
+/**
+ * useElementProgress - 요소 단위 스크롤 진행률 훅
+ *
+ * useScrollProgress의 확장판. 페이지 전체가 아니라
+ * 특정 요소가 뷰포트를 통과하는 진행률을 추적합니다.
+ *
+ * 공유 스크롤 리스너(subscribeScroll)를 사용해 N개 인스턴스도
+ * 단 하나의 scroll/resize 이벤트 + rAF 배칭으로 처리됩니다.
+ *
+ * @example
+ * ```tsx
+ * const { ref, progress, isInView } = useElementProgress<HTMLDivElement>()
+ * return (
+ *   <div ref={ref} style={{ opacity: progress }}>
+ *     Fades in as you scroll
+ *   </div>
+ * )
+ * ```
+ */
+declare function useElementProgress<T extends HTMLElement = HTMLElement>(options?: ElementProgressOptions): ElementProgressReturn<T>;
+
 declare const MOTION_PRESETS: PresetConfig;
 declare const PAGE_MOTIONS: Record<PageType, PageMotionsConfig>;
 /**
@@ -1059,6 +1333,172 @@ declare function getPagePreset(pageType: PageType): PageMotionsConfig;
  */
 declare function getMotionPreset(type: string): MotionPreset;
 
+/** 프로필 전체의 기본 모션 디폴트 */
+interface MotionProfileBase {
+    /** 기본 duration (ms) */
+    duration: number;
+    /** 기본 easing (CSS 또는 named preset) */
+    easing: string;
+    /** IntersectionObserver 임계값 */
+    threshold: number;
+    /** 한 번만 트리거할지 여부 */
+    triggerOnce: boolean;
+}
+/** 입장 애니메이션 디폴트 */
+interface MotionProfileEntrance {
+    slide: {
+        /** 슬라이드 거리 (px) */
+        distance: number;
+        /** 슬라이드 전용 이징 */
+        easing: string;
+    };
+    fade: {
+        /** 초기 투명도 */
+        initialOpacity: number;
+    };
+    scale: {
+        /** 초기 스케일 (useScrollReveal/useStagger용, 0.95 등 미세 변화) */
+        from: number;
+    };
+    bounce: {
+        /** 바운스 강도 */
+        intensity: number;
+        /** 바운스 전용 이징 */
+        easing: string;
+    };
+}
+/** 스태거 디폴트 */
+interface MotionProfileStagger {
+    /** 아이템 간 딜레이 (ms) */
+    perItem: number;
+    /** 첫 아이템 전 딜레이 (ms) */
+    baseDelay: number;
+}
+/** 인터랙션 디폴트 */
+interface MotionProfileInteraction {
+    hover: {
+        /** 호버 시 스케일 */
+        scale: number;
+        /** 호버 시 Y 오프셋 (px) */
+        y: number;
+        /** 호버 duration (ms) */
+        duration: number;
+        /** 호버 이징 */
+        easing: string;
+    };
+}
+/** 스프링 물리 디폴트 */
+interface MotionProfileSpring {
+    /** 질량 */
+    mass: number;
+    /** 강성 */
+    stiffness: number;
+    /** 감쇠 */
+    damping: number;
+    /** 정지 임계값 */
+    restDelta: number;
+    /** 정지 속도 */
+    restSpeed: number;
+}
+/** reduced motion 전략 */
+type ReducedMotionStrategy = 'skip' | 'fade-only' | 'minimal';
+/** 전체 Motion Profile */
+interface MotionProfile {
+    /** 프로필 이름 */
+    name: string;
+    /** 공통 디폴트 */
+    base: MotionProfileBase;
+    /** 입장 애니메이션 */
+    entrance: MotionProfileEntrance;
+    /** 스태거 */
+    stagger: MotionProfileStagger;
+    /** 인터랙션 */
+    interaction: MotionProfileInteraction;
+    /** 스프링 물리 */
+    spring: MotionProfileSpring;
+    /** reduced motion 전략 */
+    reducedMotion: ReducedMotionStrategy;
+}
+/** 내장 프로필 이름 */
+type BuiltInProfileName = 'neutral' | 'hua';
+/** DeepPartial 유틸리티 */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+/**
+ * neutral 프로필 — 기존 하드코딩 디폴트와 동일.
+ * Provider 없을 때 fallback으로 사용되므로 하위 호환 100% 보장.
+ */
+declare const neutral: MotionProfile;
+
+/**
+ * HUA 프로필 — 스르륵 쫀뜩한 브랜드 시그니처.
+ *
+ * 특징:
+ * - CSS ease-out 기반이되 끝에 미세한 오버슈트 (1.04~1.06)
+ * - 도착점을 살짝 지나쳤다가 돌아오는 탄성
+ * - 바운스 없이 쫀뜩 (높은 감쇠 + 높은 강성)
+ * - neutral보다 짧은 duration, 좁은 distance → 더 정교한 느낌
+ */
+declare const hua: MotionProfile;
+
+interface MotionProfileProviderProps {
+    /** 내장 프로필 이름 또는 커스텀 프로필 객체 */
+    profile?: BuiltInProfileName | MotionProfile;
+    /** 선택한 프로필 위에 부분 오버라이드 */
+    overrides?: DeepPartial<MotionProfile>;
+    children: React.ReactNode;
+}
+declare function MotionProfileProvider({ profile, overrides, children, }: MotionProfileProviderProps): react.FunctionComponentElement<react.ProviderProps<MotionProfile>>;
+/**
+ * 현재 프로필을 가져옴.
+ * Provider 밖에서 호출 시 neutral 프로필 반환 (하위 호환).
+ */
+declare function useMotionProfile(): MotionProfile;
+
+/** 이름 또는 객체에서 프로필 resolve */
+declare function resolveProfile(profile: BuiltInProfileName | MotionProfile): MotionProfile;
+/** 프로필에 오버라이드를 깊은 병합 */
+declare function mergeProfileOverrides(base: MotionProfile, overrides: DeepPartial<MotionProfile>): MotionProfile;
+
+/**
+ * Shared IntersectionObserver Pool
+ *
+ * threshold|rootMargin 조합별로 하나의 IntersectionObserver를 공유합니다.
+ * N개 훅 = K개 observer (K = 고유 옵션 조합 수, 보통 1~3).
+ *
+ * sharedScroll.ts와 동일한 singleton pool 패턴.
+ *
+ * @example
+ * ```ts
+ * useEffect(() => {
+ *   if (!ref.current) return
+ *   return observeElement(
+ *     ref.current,
+ *     (entry) => { if (entry.isIntersecting) start() },
+ *     { threshold: 0.1 },
+ *     true // once
+ *   )
+ * }, [])
+ * ```
+ */
+type EntryCallback = (entry: IntersectionObserverEntry) => void;
+/**
+ * element를 공유 IntersectionObserver에 등록.
+ * 반환 함수를 호출하면 구독 해제.
+ *
+ * @param element - 관찰할 DOM element
+ * @param callback - intersection 변화 시 호출되는 콜백 (해당 element의 entry만 전달)
+ * @param options - threshold, rootMargin
+ * @param once - true이면 첫 intersection 후 자동 unsubscribe
+ * @returns unsubscribe 함수
+ */
+declare function observeElement(element: Element, callback: EntryCallback, options?: {
+    threshold?: number | number[];
+    rootMargin?: string;
+}, once?: boolean): () => void;
+
 type EasingFunction = (t: number) => number;
 declare const linear: EasingFunction;
 declare const easeIn: EasingFunction;
@@ -1086,4 +1526,102 @@ declare const easingPresets: {
 };
 declare function getPresetEasing(preset: keyof typeof easingPresets): EasingFunction;
 
-export { type BaseMotionOptions, type BaseMotionReturn, type BounceOptions, type EasingFunction, type EasingType, type EntranceType, type FadeInOptions, type GestureConfig, type GestureOptions$1 as GestureOptions, type GradientOptions, type HoverMotionOptions, type InViewOptions, type InViewReturn, type InteractionReturn, MOTION_PRESETS, type Motion, type MotionCallback, type MotionConfig, type MotionDirection$1 as MotionDirection, type MotionEasing, type MotionElement, MotionEngine, type MotionFrame, type MotionOptions, type MotionPreset, type MotionProgressCallback, type MotionState$1 as MotionState, type MotionStateCallback, type MotionTrigger, type MotionType$1 as MotionType, type MouseOptions, type MouseReturn, type OptimizationConfig, type OrchestrationConfig, PAGE_MOTIONS, type PageMotionElement, type PageMotionRef, type PageMotionsConfig, type PageType, type PerformanceMetrics, PerformanceOptimizer, type PerformanceOptimizerMetrics, type PresetConfig, type PulseOptions, type ReducedMotionReturn, type RepeatOptions, type ScaleOptions, type ScrollRevealMotionType, type ScrollRevealOptions, type SlideOptions, type SpringConfig, type SpringOptions, type ToggleMotionOptions, TransitionEffects, type TransitionOptions, type TransitionType, type UseUnifiedMotionOptions, type WindowSizeOptions, type WindowSizeReturn, applyEasing, easeIn, easeInOut, easeInOutQuad, easeInQuad, easeOut, easeOutQuad, easingPresets, getAvailableEasings, getEasing, getMotionPreset, getPagePreset, getPresetEasing, isEasingFunction, isValidEasing, linear, mergeWithPreset, motionEngine, performanceOptimizer, safeApplyEasing, transitionEffects, useBounceIn, useClickToggle, useFadeIn, useFocusToggle, useGesture, useGestureMotion, useGradient, useHoverMotion, useInView, useMotionState, useMouse, usePageMotions, usePulse, useReducedMotion, useRepeat, useScaleIn, useScrollProgress, useScrollReveal, useSimplePageMotion, useSlideDown, useSlideLeft, useSlideRight, useSlideUp, useSmartMotion, useSpringMotion, useToggleMotion, useUnifiedMotion, useWindowSize };
+/**
+ * Spring physics calculation (Hooke's Law + damping)
+ *
+ * Pure function — no side effects, fully testable.
+ */
+interface SpringConfig {
+    stiffness: number;
+    damping: number;
+    mass: number;
+}
+interface SpringResult {
+    value: number;
+    velocity: number;
+}
+/**
+ * Calculate one step of a damped spring simulation.
+ *
+ * @param currentValue   Current position
+ * @param currentVelocity Current velocity
+ * @param targetValue    Equilibrium (target) position
+ * @param deltaTime      Time step in seconds
+ * @param config         Spring parameters (stiffness, damping, mass)
+ */
+declare function calculateSpring(currentValue: number, currentVelocity: number, targetValue: number, deltaTime: number, config: SpringConfig): SpringResult;
+
+type MotionAs = 'div' | 'span' | 'section' | 'article' | 'header' | 'footer' | 'main' | 'nav';
+interface MotionProps extends react__default.HTMLAttributes<HTMLElement> {
+    /** HTML 요소 타입 @default 'div' */
+    as?: MotionAs;
+    /** 모션 타입 */
+    type?: EntranceType;
+    /** 멀티이펙트 */
+    effects?: MotionEffects;
+    /** 스크롤 기반 reveal 모드 */
+    scroll?: boolean | ScrollRevealOptions;
+    /** 딜레이 (ms) */
+    delay?: number;
+    /** 지속시간 (ms) */
+    duration?: number;
+    children: react__default.ReactNode;
+}
+/**
+ * Motion wrapper component
+ *
+ * ref/style 수동 연결 없이 모션을 적용하는 래퍼 컴포넌트.
+ *
+ * @example
+ * // 기본 fadeIn
+ * <Motion>content</Motion>
+ *
+ * // 스크롤 reveal
+ * <Motion scroll delay={200} className="grid grid-cols-3">...</Motion>
+ *
+ * // 커스텀 요소 + 타입
+ * <Motion as="section" type="slideUp" duration={800}>...</Motion>
+ */
+declare function Motion({ as: Component, type, effects, scroll, delay, duration, children, className, style: userStyle, ...rest }: MotionProps): react_jsx_runtime.JSX.Element;
+
+interface UseStaggerOptions {
+    /** 자식 아이템 개수 */
+    count: number;
+    /** 아이템 간 딜레이 (ms) @default 100 */
+    staggerDelay?: number;
+    /** 전체 시작 딜레이 (ms) @default 0 */
+    baseDelay?: number;
+    /** 애니메이션 지속시간 (ms) @default 700 */
+    duration?: number;
+    /** 모션 타입 @default 'fadeIn' */
+    motionType?: ScrollRevealMotionType;
+    /** IntersectionObserver 임계값 @default 0.1 */
+    threshold?: number;
+    /** 이징 함수 @default 'ease-out' */
+    easing?: string;
+}
+interface UseStaggerReturn {
+    /** 부모 컨테이너 ref — IntersectionObserver 연결 */
+    containerRef: RefObject<HTMLDivElement | null>;
+    /** 자식 아이템별 style 배열 */
+    styles: CSSProperties[];
+    /** 전체 visible 여부 */
+    isVisible: boolean;
+}
+/**
+ * useStagger — 리스트 아이템에 순차 딜레이를 적용하는 훅
+ *
+ * 단일 IntersectionObserver로 컨테이너를 관찰하고,
+ * 자식 아이템별로 CSS transition-delay를 자동 계산합니다.
+ *
+ * @example
+ * const stagger = useStagger({ count: items.length, staggerDelay: 100 });
+ * <div ref={stagger.containerRef}>
+ *   {items.map((item, i) => (
+ *     <div style={stagger.styles[i]} key={i}>{item}</div>
+ *   ))}
+ * </div>
+ */
+declare function useStagger(options: UseStaggerOptions): UseStaggerReturn;
+
+export { type BaseMotionOptions, type BaseMotionReturn, type BounceOptions, type BuiltInProfileName, type ButtonEffectOptions, type CardListOptions, type CustomCursorOptions, type CustomCursorReturn, type DeepPartial, type EasingFunction, type EasingType, type ElementProgressOptions, type ElementProgressReturn, type EntranceType, type FadeInOptions, type GestureConfig, type GestureOptions$1 as GestureOptions, type GradientOptions, type HoverMotionOptions, type InViewOptions, type InViewReturn, type InteractionReturn, type LoadingSpinnerOptions, MOTION_PRESETS, type MagneticCursorOptions, type MagneticCursorReturn, Motion, type MotionCallback, type MotionConfig, type MotionDirection$1 as MotionDirection, type MotionEasing, type MotionEffects, type MotionElement, MotionEngine, type MotionFrame, type Motion$1 as MotionInstance, type MotionOptions, type MotionPreset, type MotionProfile, type MotionProfileBase, type MotionProfileEntrance, type MotionProfileInteraction, MotionProfileProvider, type MotionProfileProviderProps, type MotionProfileSpring, type MotionProfileStagger, type MotionProgressCallback, type MotionProps, type MotionState$1 as MotionState, type MotionStateCallback, type MotionTrigger, type MotionType$1 as MotionType, type MouseOptions, type MouseReturn, type NavigationOptions, type OrchestrationConfig, PAGE_MOTIONS, type PageMotionElement, type PageMotionRef, type PageMotionsConfig, type PageType, type PerformanceMetrics, type PresetConfig, type PulseOptions, type ReducedMotionReturn, type ReducedMotionStrategy, type RepeatOptions, type ScaleOptions, type ScrollRevealMotionType, type ScrollRevealOptions, type ScrollToggleOptions, type SkeletonOptions, type SlideOptions, type SmoothScrollOptions, type SmoothScrollReturn, type SpringConfig$1 as SpringConfig, type SpringOptions, type SpringConfig as SpringPhysicsConfig, type SpringResult, type ToggleMotionOptions, TransitionEffects, type TransitionOptions, type TransitionType, type TypewriterOptions, type TypewriterReturn, type UseStaggerOptions, type UseStaggerReturn, type UseUnifiedMotionOptions, type VisibilityToggleOptions, type WindowSizeOptions, type WindowSizeReturn, applyEasing, calculateSpring, easeIn, easeInOut, easeInOutQuad, easeInQuad, easeOut, easeOutQuad, easingPresets, getAvailableEasings, getEasing, getMotionPreset, getPagePreset, getPresetEasing, hua, isEasingFunction, isValidEasing, linear, mergeProfileOverrides, mergeWithPreset, motionEngine, neutral, observeElement, resolveProfile, safeApplyEasing, transitionEffects, useBounceIn, useButtonEffect, useCardList, useClickToggle, useCustomCursor, useElementProgress, useFadeIn, useFocusToggle, useGesture, useGestureMotion, useGradient, useHoverMotion, useInView, useLoadingSpinner, useMagneticCursor, useMotionProfile, useMotionState, useMouse, useNavigation, usePageMotions, usePulse, useReducedMotion, useRepeat, useScaleIn, useScrollProgress, useScrollReveal, useScrollToggle, useSimplePageMotion, useSkeleton, useSlideDown, useSlideLeft, useSlideRight, useSlideUp, useSmartMotion, useSmoothScroll, useSpringMotion, useStagger, useToggleMotion, useTypewriter, useUnifiedMotion, useVisibilityToggle, useWindowSize };