@hua-labs/motion-core 2.3.0 → 2.4.1

package/dist/index.d.ts

@@ -0,0 +1,1579 @@
+import { P as PageType, a as PageMotionRef, b as PageMotionsConfig, B as BaseMotionOptions, E as EntranceType, M as MotionElement, c as BaseMotionReturn, F as FadeInOptions, d as EntranceMotionReturn, S as SlideOptions, e as ScaleOptions, f as BounceOptions, g as PulseOptions, h as SpringOptions, G as GradientOptions, H as HoverMotionOptions, i as ScrollRevealOptions, R as RepeatOptions, T as ToggleMotionOptions, I as InteractionReturn, j as InViewOptions, k as InViewReturn, l as MouseOptions, m as MouseReturn, n as ReducedMotionReturn, W as WindowSizeOptions, o as WindowSizeReturn, p as ScrollRevealMotionType } from './springPhysics-BZVRi9PQ.js';
+export { A as AutoMotionReturn, q as BuiltInProfileName, D as DeepPartial, r as EasingFunction, s as EasingType, t as GestureConfig, u as GestureOptions, v as MOTION_PRESETS, w as MotionCallback, x as MotionConfig, y as MotionDirection, z as MotionEasing, C as MotionEngine, J as MotionFrame, K as MotionInstance, L as MotionOptions, N as MotionPreset, O as MotionProfile, Q as MotionProfileBase, U as MotionProfileEntrance, V as MotionProfileInteraction, X as MotionProfileProvider, Y as MotionProfileProviderProps, Z as MotionProfileSpring, _ as MotionProfileStagger, $ as MotionProgressCallback, a0 as MotionState, a1 as MotionStateCallback, a2 as MotionTrigger, a3 as MotionType, a4 as ObserverReturn, a5 as OrchestrationConfig, a6 as PAGE_MOTIONS, a7 as PageMotionElement, a8 as PerformanceMetrics, a9 as PresetConfig, aa as ReducedMotionStrategy, ab as SequenceOrchestrationConfig, ac as SpringConfig, ad as SpringPhysicsConfig, ae as SpringResult, af as StyleMotionReturn, ag as ToggleMotionReturn, ah as TransitionEffects, ai as TransitionOptions, aj as TransitionType, ak as applyEasing, al as calculateSpring, am as easeIn, an as easeInOut, ao as easeInOutQuad, ap as easeInQuad, aq as easeOut, ar as easeOutQuad, as as easingPresets, at as getAvailableEasings, au as getEasing, av as getMotionPreset, aw as getPagePreset, ax as getPresetEasing, ay as hua, az as isEasingFunction, aA as isValidEasing, aB as linear, aC as mergeProfileOverrides, aD as mergeWithPreset, aE as motionEngine, aF as neutral, aG as resolveProfile, aH as safeApplyEasing, aI as transitionEffects, aJ as useMotionProfile } from './springPhysics-BZVRi9PQ.js';
+import * as react from 'react';
+import react__default, { CSSProperties, RefObject } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * 1단계 API: 프리셋 기반 페이지 모션 (기존 방식)
+ *
+ * 사용법:
+ * ```typescript
+ * const motions = useSimplePageMotion('home')
+ * ```
+ *
+ * 지원하는 페이지 타입:
+ * - 'home': 홈페이지
+ * - 'dashboard': 대시보드
+ * - 'product': 제품 페이지
+ * - 'blog': 블로그
+ */
+declare function useSimplePageMotion(pageType: PageType): Record<string, PageMotionRef<HTMLElement>>;
+
+/**
+ * 2단계 API: 페이지 레벨 모션 관리 (상태 관리자 버전)
+ *
+ * 사용법:
+ * ```typescript
+ * const motions = usePageMotions({
+ *   hero: { type: 'hero' },
+ *   title: { type: 'title' },
+ *   button: { type: 'button', hover: true, click: true }
+ * })
+ * ```
+ */
+declare function usePageMotions(config: PageMotionsConfig): {
+    reset: () => void;
+};
+
+type MotionType = 'fadeIn' | 'slideUp' | 'slideLeft' | 'slideRight' | 'scaleIn' | 'bounceIn';
+type ElementType = 'hero' | 'title' | 'button' | 'card' | 'text' | 'image';
+interface SmartMotionOptions {
+    type?: ElementType;
+    entrance?: MotionType;
+    hover?: boolean;
+    click?: boolean;
+    delay?: number;
+    duration?: number;
+    threshold?: number;
+    autoLanguageSync?: boolean;
+}
+/**
+ * 3단계 API: 개별 요소 모션
+ *
+ * 사용법:
+ * ```typescript
+ * const heroRef = useSmartMotion({ type: 'hero' })
+ * const titleRef = useSmartMotion({ type: 'title' })
+ * const buttonRef = useSmartMotion({ type: 'button' })
+ * ```
+ */
+declare function useSmartMotion<T extends HTMLElement = HTMLDivElement>(options?: SmartMotionOptions): {
+    ref: React.RefObject<T | null>;
+    style: React.CSSProperties;
+    isVisible: boolean;
+    isHovered: boolean;
+    isClicked: boolean;
+};
+
+/**
+ * @hua-labs/motion-core - useUnifiedMotion
+ *
+ * 통합 Motion Hook - 단일 타입으로 여러 모션 효과 중 하나를 선택
+ * 내부에서 선택된 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 (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 */
+    distance?: number;
+}
+declare function useUnifiedMotion<T extends MotionElement = HTMLDivElement>(options: UseUnifiedMotionOptions): BaseMotionReturn<T>;
+
+declare function useFadeIn<T extends MotionElement = HTMLDivElement>(options?: FadeInOptions): EntranceMotionReturn<T>;
+
+declare function useSlideUp<T extends MotionElement = HTMLDivElement>(options?: SlideOptions): EntranceMotionReturn<T>;
+
+/**
+ * useSlideLeft - 오른쪽에서 왼쪽으로 슬라이드하며 나타나는 애니메이션 훅
+ *
+ * useSlideUp의 wrapper로, direction: 'left'를 기본값으로 사용합니다.
+ * IntersectionObserver를 통해 뷰포트 진입 시 자동으로 애니메이션이 시작됩니다.
+ *
+ * @example
+ * ```tsx
+ * const slideLeft = useSlideLeft({ duration: 700, distance: 50 });
+ *
+ * return (
+ *   <div ref={slideLeft.ref} style={slideLeft.style}>
+ *     Content slides in from right
+ *   </div>
+ * );
+ * ```
+ */
+declare function useSlideLeft<T extends MotionElement = HTMLDivElement>(options?: Omit<SlideOptions, "direction">): EntranceMotionReturn<T>;
+
+/**
+ * useSlideRight - 왼쪽에서 오른쪽으로 슬라이드하며 나타나는 애니메이션 훅
+ *
+ * useSlideUp의 wrapper로, direction: 'right'를 기본값으로 사용합니다.
+ * IntersectionObserver를 통해 뷰포트 진입 시 자동으로 애니메이션이 시작됩니다.
+ *
+ * @example
+ * ```tsx
+ * const slideRight = useSlideRight({ duration: 700, distance: 50 });
+ *
+ * return (
+ *   <div ref={slideRight.ref} style={slideRight.style}>
+ *     Content slides in from left
+ *   </div>
+ * );
+ * ```
+ */
+declare function useSlideRight<T extends MotionElement = HTMLDivElement>(options?: Omit<SlideOptions, "direction">): EntranceMotionReturn<T>;
+
+declare function useScaleIn<T extends MotionElement = HTMLDivElement>(options?: ScaleOptions): EntranceMotionReturn<T>;
+
+declare function useBounceIn<T extends MotionElement = HTMLDivElement>(options?: BounceOptions): EntranceMotionReturn<T>;
+
+declare function usePulse<T extends MotionElement = HTMLDivElement>(options?: PulseOptions): BaseMotionReturn<T>;
+
+interface SpringMotionOptions extends SpringOptions {
+    /** 시작 값 */
+    from: number;
+    /** 목표 값 */
+    to: number;
+    /** 활성화 여부 */
+    enabled?: boolean;
+}
+declare function useSpringMotion<T extends MotionElement = HTMLDivElement>(options: SpringMotionOptions): BaseMotionReturn<T> & {
+    value: number;
+    velocity: number;
+};
+
+declare function useGradient<T extends MotionElement = HTMLDivElement>(options?: GradientOptions): BaseMotionReturn<T>;
+
+declare function useHoverMotion<T extends MotionElement = HTMLDivElement>(options?: HoverMotionOptions): BaseMotionReturn<T> & {
+    isHovered: boolean;
+};
+
+interface ClickToggleOptions {
+    initialState?: boolean;
+    toggleOnClick?: boolean;
+    toggleOnDoubleClick?: boolean;
+    toggleOnRightClick?: boolean;
+    toggleOnEnter?: boolean;
+    toggleOnSpace?: boolean;
+    autoReset?: boolean;
+    resetDelay?: number;
+    preventDefault?: boolean;
+    stopPropagation?: boolean;
+    showOnMount?: boolean;
+}
+interface ClickToggleReturn {
+    isActive: boolean;
+    mounted: boolean;
+    toggle: () => void;
+    activate: () => void;
+    deactivate: () => void;
+    reset: () => void;
+    clickHandlers: {
+        onClick?: (event: React.MouseEvent) => void;
+        onDoubleClick?: (event: React.MouseEvent) => void;
+        onContextMenu?: (event: React.MouseEvent) => void;
+        onKeyDown?: (event: React.KeyboardEvent) => void;
+    };
+}
+declare function useClickToggle(options?: ClickToggleOptions): ClickToggleReturn;
+
+interface FocusToggleOptions {
+    initialState?: boolean;
+    toggleOnFocus?: boolean;
+    toggleOnBlur?: boolean;
+    toggleOnFocusIn?: boolean;
+    toggleOnFocusOut?: boolean;
+    autoReset?: boolean;
+    resetDelay?: number;
+    preventDefault?: boolean;
+    stopPropagation?: boolean;
+    showOnMount?: boolean;
+}
+interface FocusToggleReturn {
+    isActive: boolean;
+    mounted: boolean;
+    toggle: () => void;
+    activate: () => void;
+    deactivate: () => void;
+    reset: () => void;
+    focusHandlers: {
+        onFocus?: (event: React.FocusEvent) => void;
+        onBlur?: (event: React.FocusEvent) => void;
+        onFocusIn?: (event: React.FocusEvent) => void;
+        onFocusOut?: (event: React.FocusEvent) => void;
+    };
+    ref: React.RefObject<HTMLElement | null>;
+}
+declare function useFocusToggle(options?: FocusToggleOptions): FocusToggleReturn;
+
+declare function useScrollReveal<T extends MotionElement = HTMLDivElement>(options?: ScrollRevealOptions): BaseMotionReturn<T>;
+
+interface ScrollProgressOptions {
+    target?: number;
+    offset?: number;
+    showOnMount?: boolean;
+}
+declare function useScrollProgress(options?: ScrollProgressOptions): {
+    progress: number;
+    mounted: boolean;
+};
+
+type MotionState = 'idle' | 'playing' | 'paused' | 'completed' | 'error';
+type MotionDirection = 'forward' | 'reverse' | 'alternate';
+interface MotionStateOptions {
+    initialState?: MotionState;
+    autoStart?: boolean;
+    loop?: boolean;
+    direction?: MotionDirection;
+    duration?: number;
+    delay?: number;
+    showOnMount?: boolean;
+}
+interface MotionStateReturn {
+    state: MotionState;
+    direction: MotionDirection;
+    progress: number;
+    elapsed: number;
+    remaining: number;
+    mounted: boolean;
+    play: () => void;
+    pause: () => void;
+    stop: () => void;
+    reset: () => void;
+    reverse: () => void;
+    seek: (progress: number) => void;
+    setState: (newState: MotionState) => void;
+}
+declare function useMotionState(options?: MotionStateOptions): MotionStateReturn;
+
+declare function useRepeat<T extends MotionElement = HTMLDivElement>(options?: RepeatOptions): BaseMotionReturn<T> & {
+    isAnimating: boolean;
+};
+
+declare function useToggleMotion<T extends MotionElement = HTMLDivElement>(options?: ToggleMotionOptions): InteractionReturn<T>;
+
+/**
+ * useSlideDown - 아래에서 위로 슬라이드하며 나타나는 애니메이션 훅
+ *
+ * useSlideUp의 wrapper로, direction: 'down'을 기본값으로 사용합니다.
+ * IntersectionObserver를 통해 뷰포트 진입 시 자동으로 애니메이션이 시작됩니다.
+ *
+ * @example
+ * ```tsx
+ * const slideDown = useSlideDown({ duration: 700, distance: 50 });
+ *
+ * return (
+ *   <div ref={slideDown.ref} style={slideDown.style}>
+ *     Content slides down into view
+ *   </div>
+ * );
+ * ```
+ */
+declare function useSlideDown<T extends MotionElement = HTMLDivElement>(options?: Omit<SlideOptions, "direction">): EntranceMotionReturn<T>;
+
+/**
+ * useInView - 요소의 뷰포트 가시성 감지 훅
+ * Viewport visibility detection hook
+ *
+ * @description
+ * Intersection Observer를 사용하여 요소가 뷰포트에 보이는지 감지.
+ * 스크롤 애니메이션, 레이지 로딩 등에 활용.
+ * Detects whether an element is visible in the viewport using Intersection Observer.
+ * Useful for scroll animations, lazy loading, etc.
+ *
+ * @example
+ * ```tsx
+ * const { ref, inView } = useInView({ threshold: 0.5, triggerOnce: true })
+ *
+ * return (
+ *   <div ref={ref} style={{ opacity: inView ? 1 : 0 }}>
+ *     {inView ? 'Visible!' : 'Not visible'}
+ *   </div>
+ * )
+ * ```
+ */
+declare function useInView<T extends HTMLElement = HTMLDivElement>(options?: InViewOptions): InViewReturn<T>;
+
+/**
+ * useMouse - 마우스 위치 추적 훅
+ * Mouse position tracking hook
+ *
+ * @description
+ * 마우스 위치를 실시간으로 추적. 커서 따라다니는 효과,
+ * 마우스 기반 인터랙션 등에 활용.
+ * Tracks mouse position in real-time. Useful for cursor-following effects
+ * and mouse-based interactions.
+ *
+ * @example
+ * ```tsx
+ * const { x, y, elementX, elementY } = useMouse()
+ *
+ * return (
+ *   <div style={{
+ *     '--mouse-x': elementX,
+ *     '--mouse-y': elementY
+ *   }}>
+ *     Mouse: {x}, {y}
+ *   </div>
+ * )
+ * ```
+ */
+declare function useMouse(options?: MouseOptions): MouseReturn;
+
+/**
+ * useReducedMotion - 모션 감소 설정 감지 훅
+ * Reduced motion preference detection hook
+ *
+ * @description
+ * 사용자의 prefers-reduced-motion 설정을 감지.
+ * 접근성을 위해 모션을 줄이거나 비활성화할 때 사용.
+ * Detects user's prefers-reduced-motion setting.
+ * Used to reduce or disable motion for accessibility.
+ *
+ * @returns {boolean} 모션 감소 선호 여부 / Whether reduced motion is preferred
+ *
+ * @example
+ * ```tsx
+ * const prefersReducedMotion = useReducedMotion()
+ *
+ * return (
+ *   <motion.div
+ *     animate={prefersReducedMotion ? {} : { scale: [1, 1.1, 1] }}
+ *     transition={{ duration: prefersReducedMotion ? 0 : 0.3 }}
+ *   >
+ *     Accessible Motion
+ *   </motion.div>
+ * )
+ * ```
+ */
+declare function useReducedMotion(): boolean;
+/**
+ * useReducedMotionObject - 객체 형태 반환 (backwards compat)
+ * Returns `{ prefersReducedMotion: boolean }` for backwards compatibility.
+ *
+ * @deprecated Use `useReducedMotion()` which returns `boolean` directly.
+ *
+ * @example
+ * ```tsx
+ * const { prefersReducedMotion } = useReducedMotionObject()
+ * ```
+ */
+declare function useReducedMotionObject(): ReducedMotionReturn;
+
+/**
+ * useWindowSize - 윈도우 크기 추적 훅
+ * Window size tracking hook
+ *
+ * @description
+ * 브라우저 윈도우 크기 변경을 감지.
+ * 반응형 레이아웃, 리사이즈 기반 애니메이션 등에 활용.
+ * Detects browser window size changes.
+ * Useful for responsive layouts and resize-based animations.
+ *
+ * @example
+ * ```tsx
+ * const { width, height, isMounted } = useWindowSize({ debounce: 100 })
+ *
+ * return (
+ *   <div>
+ *     {isMounted ? `${width} x ${height}` : 'Loading...'}
+ *   </div>
+ * )
+ * ```
+ */
+declare function useWindowSize(options?: WindowSizeOptions): WindowSizeReturn;
+
+interface GestureOptions {
+    enabled?: boolean;
+    threshold?: number;
+    timeout?: number;
+    swipeThreshold?: number;
+    swipeVelocity?: number;
+    swipeDirections?: ('up' | 'down' | 'left' | 'right')[];
+    pinchThreshold?: number;
+    minScale?: number;
+    maxScale?: number;
+    rotateThreshold?: number;
+    panThreshold?: number;
+    onSwipe?: (direction: 'up' | 'down' | 'left' | 'right', distance: number, velocity: number) => void;
+    onPinch?: (scale: number, delta: number) => void;
+    onRotate?: (angle: number, delta: number) => void;
+    onPan?: (deltaX: number, deltaY: number, totalX: number, totalY: number) => void;
+    onTap?: (x: number, y: number) => void;
+    onDoubleTap?: (x: number, y: number) => void;
+    onLongPress?: (x: number, y: number) => void;
+    onStart?: (x: number, y: number) => void;
+    onMove?: (x: number, y: number) => void;
+    onEnd?: (x: number, y: number) => void;
+}
+interface GestureReturn {
+    isActive: boolean;
+    gesture: string | null;
+    scale: number;
+    rotation: number;
+    deltaX: number;
+    deltaY: number;
+    distance: number;
+    velocity: number;
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+    onTouchStart: (e: React.TouchEvent | TouchEvent) => void;
+    onTouchMove: (e: React.TouchEvent | TouchEvent) => void;
+    onTouchEnd: (e: React.TouchEvent | TouchEvent) => void;
+    onMouseDown: (e: React.MouseEvent | MouseEvent) => void;
+    onMouseMove: (e: React.MouseEvent | MouseEvent) => void;
+    onMouseUp: (e: React.MouseEvent | MouseEvent) => void;
+}
+declare function useGesture(options?: GestureOptions): GestureReturn;
+
+interface GestureMotionOptions {
+    gestureType: 'hover' | 'drag' | 'pinch' | 'swipe' | 'tilt';
+    duration?: number;
+    easing?: string;
+    sensitivity?: number;
+    enabled?: boolean;
+    onGestureStart?: () => void;
+    onGestureEnd?: () => void;
+}
+interface GestureState {
+    isActive: boolean;
+    x: number;
+    y: number;
+    deltaX: number;
+    deltaY: number;
+    scale: number;
+    rotation: number;
+}
+declare function useGestureMotion(options: GestureMotionOptions): {
+    ref: react.RefObject<HTMLElement | null>;
+    gestureState: GestureState;
+    motionStyle: react.CSSProperties;
+    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>;
+
+/**
+ * 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;
+
+interface AutoFadeConfig {
+    initialOpacity?: number;
+    targetOpacity?: number;
+    duration?: number;
+    delay?: number;
+    repeat?: boolean;
+    repeatDelay?: number;
+    repeatCount?: number;
+    ease?: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+    autoStart?: boolean;
+    onComplete?: () => void;
+    onRepeat?: (count: number) => void;
+    showOnMount?: boolean;
+}
+interface AutoFadeReturn {
+    opacity: number;
+    isAnimating: boolean;
+    isVisible: boolean;
+    mounted: boolean;
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+    fadeIn: () => void;
+    fadeOut: () => void;
+    toggle: () => void;
+}
+declare function useAutoFade(options?: AutoFadeConfig): AutoFadeReturn;
+
+interface AutoPlayConfig {
+    interval?: number;
+    delay?: number;
+    repeat?: number | "infinite";
+    autoStart?: boolean;
+    pauseOnHover?: boolean;
+    pauseOnBlur?: boolean;
+    showOnMount?: boolean;
+}
+declare function useAutoPlay(options?: AutoPlayConfig): {
+    isPlaying: boolean;
+    isPaused: boolean;
+    currentStep: number;
+    mounted: boolean;
+    start: () => void;
+    stop: () => void;
+    pause: () => void;
+    resume: () => void;
+    next: () => void;
+    previous: () => void;
+    goTo: (step: number) => void;
+};
+
+interface AutoScaleConfig {
+    initialScale?: number;
+    targetScale?: number;
+    duration?: number;
+    delay?: number;
+    repeat?: boolean;
+    repeatDelay?: number;
+    repeatCount?: number;
+    ease?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "bounce" | "elastic";
+    autoStart?: boolean;
+    onComplete?: () => void;
+    onRepeat?: (count: number) => void;
+    showOnMount?: boolean;
+    centerTransform?: boolean;
+}
+interface AutoScaleReturn {
+    scale: number;
+    isAnimating: boolean;
+    isVisible: boolean;
+    mounted: boolean;
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+    scaleIn: () => void;
+    scaleOut: () => void;
+    toggle: () => void;
+}
+declare function useAutoScale(options?: AutoScaleConfig): AutoScaleReturn;
+
+type SlideDirection = "left" | "right" | "up" | "down" | "left-up" | "left-down" | "right-up" | "right-down";
+interface AutoSlideConfig {
+    direction?: SlideDirection;
+    distance?: number;
+    initialPosition?: {
+        x: number;
+        y: number;
+    };
+    targetPosition?: {
+        x: number;
+        y: number;
+    };
+    duration?: number;
+    delay?: number;
+    repeat?: boolean;
+    repeatDelay?: number;
+    repeatCount?: number;
+    ease?: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+    autoStart?: boolean;
+    onComplete?: () => void;
+    onRepeat?: (count: number) => void;
+    showOnMount?: boolean;
+}
+interface AutoSlideReturn {
+    position: {
+        x: number;
+        y: number;
+    };
+    isAnimating: boolean;
+    isVisible: boolean;
+    mounted: boolean;
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+    slideIn: () => void;
+    slideOut: () => void;
+    toggle: () => void;
+}
+declare function useAutoSlide(options?: AutoSlideConfig): AutoSlideReturn;
+
+interface MotionStep$1 {
+    id: string;
+    motion: () => void;
+    delay?: number;
+    duration?: number;
+    onComplete?: () => void;
+}
+interface MotionOrchestraOptions {
+    mode?: "sequential" | "parallel" | "stagger";
+    staggerDelay?: number;
+    autoStart?: boolean;
+    loop?: boolean;
+    onComplete?: () => void;
+}
+declare function useMotionOrchestra(options?: MotionOrchestraOptions): {
+    addMotion: (step: MotionStep$1) => void;
+    removeMotion: (id: string) => void;
+    play: () => void;
+    stop: () => void;
+    pause: () => void;
+    resume: () => void;
+    isPlaying: boolean;
+    currentStep: number;
+    completedSteps: Set<string>;
+    totalSteps: number;
+};
+
+interface MotionStep {
+    id: string;
+    duration: number;
+    delay?: number;
+    ease?: "linear" | "ease-in" | "ease-out" | "ease-in-out" | "bounce" | "elastic";
+    onStart?: () => void;
+    onUpdate?: (progress: number) => void;
+    onComplete?: () => void;
+    onError?: (error: Error) => void;
+}
+interface OrchestrationConfig {
+    autoStart?: boolean;
+    loop?: boolean;
+    loopCount?: number;
+    loopDelay?: number;
+    timeline?: MotionStep[];
+    duration?: number;
+    speed?: number;
+    reverse?: boolean;
+    onStart?: () => void;
+    onComplete?: () => void;
+    onLoop?: (count: number) => void;
+    onError?: (error: Error) => void;
+    onProgress?: (progress: number) => void;
+    onStepStart?: (stepId: string) => void;
+    onStepComplete?: (stepId: string) => void;
+}
+interface OrchestrationReturn {
+    isPlaying: boolean;
+    isPaused: boolean;
+    currentTime: number;
+    progress: number;
+    currentStep: string | null;
+    loopCount: number;
+    error: string | null;
+    play: () => void;
+    pause: () => void;
+    stop: () => void;
+    reset: () => void;
+    seek: (time: number) => void;
+    setSpeed: (speed: number) => void;
+    reverse: () => void;
+    addStep: (step: MotionStep) => void;
+    removeStep: (stepId: string) => void;
+    updateStep: (stepId: string, updates: Partial<MotionStep>) => void;
+    reorderSteps: (stepIds: string[]) => void;
+    getStepProgress: (stepId: string) => number;
+    getStepTime: (stepId: string) => number;
+    getTotalDuration: () => number;
+}
+declare function useOrchestration(options?: OrchestrationConfig): OrchestrationReturn;
+
+/** The subset of BaseMotionReturn that useSequence actually consumes. */
+type SequenceMotionResult = Pick<BaseMotionReturn<MotionElement>, "start" | "stop" | "reset" | "ref"> & {
+    pause?: () => void;
+    resume?: () => void;
+};
+interface SequenceConfig {
+    autoStart?: boolean;
+    loop?: boolean;
+}
+/** @deprecated Use useOrchestration or useMotionOrchestra instead. */
+interface SequenceItem {
+    hook: () => SequenceMotionResult;
+    delay?: number;
+}
+/** @deprecated Use useOrchestration or useMotionOrchestra instead. */
+declare function useSequence(sequence: SequenceItem[], options?: SequenceConfig): {
+    start: () => void;
+    stop: () => void;
+    pause: () => void;
+    resume: () => void;
+    reset: () => void;
+    isPlaying: boolean;
+    currentIndex: number;
+    totalMotions: number;
+    ref: react.RefObject<MotionElement | null>;
+};
+
+interface LayoutMotionConfig {
+    from: {
+        width?: number | string;
+        height?: number | string;
+        flexDirection?: "row" | "column" | "row-reverse" | "column-reverse";
+        justifyContent?: "flex-start" | "flex-end" | "center" | "space-between" | "space-around" | "space-evenly";
+        alignItems?: "flex-start" | "flex-end" | "center" | "stretch" | "baseline";
+        gap?: number | string;
+        gridTemplateColumns?: string;
+        gridTemplateRows?: string;
+        gridGap?: number | string;
+    };
+    to: {
+        width?: number | string;
+        height?: number | string;
+        flexDirection?: "row" | "column" | "row-reverse" | "column-reverse";
+        justifyContent?: "flex-start" | "flex-end" | "center" | "space-between" | "space-around" | "space-evenly";
+        alignItems?: "flex-start" | "flex-end" | "center" | "stretch" | "baseline";
+        gap?: number | string;
+        gridTemplateColumns?: string;
+        gridTemplateRows?: string;
+        gridGap?: number | string;
+    };
+    duration?: number;
+    easing?: string;
+    autoStart?: boolean;
+    onComplete?: () => void;
+}
+interface LayoutState {
+    isAnimating: boolean;
+    progress: number;
+    currentStyle: React.CSSProperties;
+}
+declare function useLayoutMotion(config: LayoutMotionConfig): {
+    ref: react.RefObject<HTMLDivElement | null>;
+    state: LayoutState;
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+};
+declare function createLayoutTransition(from: LayoutMotionConfig["from"], to: LayoutMotionConfig["to"], options?: Partial<LayoutMotionConfig>): {
+    from: {
+        width?: number | string;
+        height?: number | string;
+        flexDirection?: "row" | "column" | "row-reverse" | "column-reverse";
+        justifyContent?: "flex-start" | "flex-end" | "center" | "space-between" | "space-around" | "space-evenly";
+        alignItems?: "flex-start" | "flex-end" | "center" | "stretch" | "baseline";
+        gap?: number | string;
+        gridTemplateColumns?: string;
+        gridTemplateRows?: string;
+        gridGap?: number | string;
+    };
+    to: {
+        width?: number | string;
+        height?: number | string;
+        flexDirection?: "row" | "column" | "row-reverse" | "column-reverse";
+        justifyContent?: "flex-start" | "flex-end" | "center" | "space-between" | "space-around" | "space-evenly";
+        alignItems?: "flex-start" | "flex-end" | "center" | "stretch" | "baseline";
+        gap?: number | string;
+        gridTemplateColumns?: string;
+        gridTemplateRows?: string;
+        gridGap?: number | string;
+    };
+    duration: number;
+    easing: string;
+    autoStart: boolean;
+    onComplete: (() => void) | undefined;
+};
+
+interface KeyboardToggleConfig {
+    initialState?: boolean;
+    keys?: string[];
+    keyCode?: number;
+    keyCombo?: string[];
+    toggleOnKeyDown?: boolean;
+    toggleOnKeyUp?: boolean;
+    toggleOnKeyPress?: boolean;
+    autoReset?: boolean;
+    resetDelay?: number;
+    preventDefault?: boolean;
+    stopPropagation?: boolean;
+    requireFocus?: boolean;
+    showOnMount?: boolean;
+}
+interface KeyboardToggleReturn {
+    isActive: boolean;
+    mounted: boolean;
+    toggle: () => void;
+    activate: () => void;
+    deactivate: () => void;
+    reset: () => void;
+    keyboardHandlers: {
+        onKeyDown?: (event: React.KeyboardEvent) => void;
+        onKeyUp?: (event: React.KeyboardEvent) => void;
+        onKeyPress?: (event: React.KeyboardEvent) => void;
+    };
+    ref: React.RefObject<HTMLElement | null>;
+}
+declare function useKeyboardToggle(options?: KeyboardToggleConfig): KeyboardToggleReturn;
+
+type ScrollDirection = "up" | "down" | "idle";
+interface ScrollDirectionConfig {
+    threshold?: number;
+    idleDelay?: number;
+    showOnMount?: boolean;
+}
+declare function useScrollDirection(options?: ScrollDirectionConfig): {
+    direction: ScrollDirection;
+    mounted: boolean;
+};
+
+interface StickyToggleConfig {
+    offset?: number;
+    behavior?: "smooth" | "auto";
+    showOnMount?: boolean;
+}
+declare function useStickyToggle(options?: StickyToggleConfig): {
+    isSticky: boolean;
+    mounted: boolean;
+};
+
+interface InteractiveConfig {
+    hoverScale?: number;
+    clickScale?: number;
+    duration?: number;
+}
+interface InteractiveState {
+    scale: number;
+    isHovered: boolean;
+    isClicked: boolean;
+}
+declare function useInteractive(config?: InteractiveConfig): {
+    ref: (element: HTMLDivElement | null) => void;
+    scale: number;
+    isHovered: boolean;
+    isClicked: boolean;
+    handleMouseEnter: () => void;
+    handleMouseLeave: () => void;
+    handleMouseDown: () => void;
+    handleMouseUp: () => void;
+};
+
+interface PerformanceMonitorConfig {
+    threshold?: number;
+    onPerformanceIssue?: (fps: number) => void;
+}
+interface PerformanceMonitorState {
+    fps: number;
+    isLowPerformance: boolean;
+    frameCount: number;
+}
+declare function usePerformanceMonitor(config?: PerformanceMonitorConfig): {
+    ref: (element: HTMLDivElement | null) => void;
+    fps: number;
+    isLowPerformance: boolean;
+    frameCount: number;
+};
+
+interface LanguageConfig {
+    motionType: "fadeIn" | "slideUp" | "slideLeft" | "slideRight" | "scaleIn" | "bounceIn";
+    duration?: number;
+    delay?: number;
+    threshold?: number;
+    pauseOnLanguageChange?: boolean;
+    restartOnLanguageChange?: boolean;
+    currentLanguage?: string;
+}
+declare function useLanguageAwareMotion(options: LanguageConfig): {
+    ref: react.RefObject<HTMLElement | null>;
+    isVisible: boolean;
+    isPaused: boolean;
+    style: {
+        opacity: number;
+        transform: string;
+        transition: string;
+    } | {
+        opacity: number;
+        transition: string;
+        transform?: undefined;
+    };
+    pauseMotion: () => void;
+    resumeMotion: () => void;
+    restartMotion: () => void;
+    currentLanguage: string;
+};
+
+interface GameLoopConfig {
+    fps?: number;
+    autoStart?: boolean;
+    maxFPS?: number;
+    minFPS?: number;
+    showOnMount?: boolean;
+}
+interface GameState {
+    isRunning: boolean;
+    fps: number;
+    deltaTime: number;
+    elapsedTime: number;
+    frameCount: number;
+    mounted: boolean;
+}
+interface GameLoopReturn {
+    isRunning: boolean;
+    fps: number;
+    deltaTime: number;
+    elapsedTime: number;
+    frameCount: number;
+    mounted: boolean;
+    start: () => void;
+    stop: () => void;
+    pause: () => void;
+    resume: () => void;
+    reset: () => void;
+    onUpdate: (callback: (deltaTime: number, elapsedTime: number) => void) => void;
+    onRender: (callback: (deltaTime: number, elapsedTime: number) => void) => void;
+}
+declare function useGameLoop(options?: GameLoopConfig): GameLoopReturn;
+
+interface AutoMotionConfig {
+    duration?: number;
+    delay?: number;
+    autoStart?: boolean;
+    easing?: string;
+    type?: "fade" | "slide" | "scale" | "rotate";
+}
+interface MotionConfig {
+    duration?: number;
+    delay?: number;
+    autoStart?: boolean;
+    easing?: string;
+    type?: "fade" | "slide" | "scale" | "rotate";
+}
+interface MotionFromToConfig {
+    from: Record<string, any>;
+    to: Record<string, any>;
+    duration?: number;
+    delay?: number;
+    autoStart?: boolean;
+    ease?: string;
+}
+declare function useMotion(configOrFrom?: MotionConfig | Record<string, any>, to?: Record<string, any>, options?: {
+    duration?: number;
+    delay?: number;
+    autoStart?: boolean;
+    ease?: string;
+}): {
+    ref: (element: HTMLDivElement | null) => void;
+    style: react__default.CSSProperties;
+    transform: string;
+    opacity: number;
+    backgroundColor: string | undefined;
+    isAnimating: boolean;
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+};
+
+interface ViewportToggleConfig {
+    threshold?: number;
+    rootMargin?: string;
+    trigger?: "enter" | "exit" | "both";
+    once?: boolean;
+    showOnMount?: boolean;
+}
+/**
+ * IntersectionObserver를 사용해 뷰포트 진입/이탈을 감지하는 훅.
+ * (구 hua-pro의 useVisibilityToggle — animation lifecycle 기반의
+ * motion-core useVisibilityToggle과 충돌을 피해 이름을 변경함)
+ */
+declare function useViewportToggle(options?: ViewportToggleConfig): {
+    ref: react.RefObject<HTMLElement | null>;
+    isVisible: boolean;
+    mounted: boolean;
+};
+
+interface ScrollPositionToggleConfig {
+    threshold?: number;
+    showOnMount?: boolean;
+    smooth?: boolean;
+}
+/**
+ * window.pageYOffset 기준 스크롤 위치 임계값에 따라 가시성을 토글하는 훅.
+ * (구 hua-pro의 useScrollToggle — animation lifecycle 기반의
+ * motion-core useScrollToggle과 충돌을 피해 이름을 변경함)
+ */
+declare function useScrollPositionToggle(options?: ScrollPositionToggleConfig): {
+    isVisible: boolean;
+    scrollToTop: () => void;
+    mounted: boolean;
+};
+
+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 CountUpOptions {
+    /** 목표 숫자 */
+    end: number;
+    /** 숫자 뒤에 붙는 접미사 (%, +, 명 등) */
+    suffix?: string;
+    /** 애니메이션 지속 시간 (ms) */
+    duration?: number;
+    /** 시작 지연 시간 (ms) */
+    delay?: number;
+    /** 애니메이션 활성화 여부 (true가 되면 시작, 한 번만 실행) */
+    active?: boolean;
+}
+interface CountUpReturn {
+    /** 현재 숫자 값 */
+    value: number;
+    /** 접미사 포함 표시 문자열 */
+    display: string;
+}
+/**
+ * useCountUp — 숫자 카운트업 애니메이션
+ *
+ * 통계, 대시보드, 메트릭 수치 강조에 적합.
+ * ease-out cubic 이징으로 자연스러운 감속 효과.
+ *
+ * @example
+ * ```tsx
+ * const { display } = useCountUp({ end: 1200, suffix: '+', active: isInView })
+ * return <span>{display}</span>
+ * ```
+ */
+declare function useCountUp(options: CountUpOptions): CountUpReturn;
+
+interface ClipRevealOptions {
+    /** 시작 지연 시간 (ms) */
+    delay?: number;
+    /** 애니메이션 지속 시간 (ms) */
+    duration?: number;
+    /** CSS 이징 함수 */
+    easing?: string;
+    /** 애니메이션 활성화 여부 (true가 되면 시작, 한 번만 실행) */
+    active?: boolean;
+}
+interface ClipRevealReturn {
+    /** overflow:hidden 컨테이너에 적용할 스타일 */
+    containerStyle: CSSProperties;
+    /** 슬라이딩 텍스트에 적용할 스타일 */
+    textStyle: CSSProperties;
+    /** 등장 완료 여부 */
+    isVisible: boolean;
+}
+/**
+ * useClipReveal — overflow clip으로 텍스트가 아래→위로 등장
+ *
+ * 커버 타이틀, 히어로 헤드라인, 큰 문구에 적합.
+ * 컨테이너에 overflow:hidden을 적용하고, 내부 텍스트가 translateY로 올라옴.
+ *
+ * @example
+ * ```tsx
+ * const { containerStyle, textStyle } = useClipReveal({ delay: 200, active: isInView })
+ * return (
+ *   <span style={containerStyle}>
+ *     <span style={textStyle}>Hello World</span>
+ *   </span>
+ * )
+ * ```
+ */
+declare function useClipReveal(options?: ClipRevealOptions): ClipRevealReturn;
+
+interface BlurInOptions {
+    /** 시작 지연 시간 (ms) */
+    delay?: number;
+    /** 애니메이션 지속 시간 (ms) */
+    duration?: number;
+    /** 초기 블러 강도 (px) */
+    blurAmount?: number;
+    /** 초기 스케일 (0~1) */
+    scale?: number;
+    /** CSS 이징 함수 */
+    easing?: string;
+    /** 애니메이션 활성화 여부 (true가 되면 시작, 한 번만 실행) */
+    active?: boolean;
+}
+interface BlurInReturn {
+    /** 요소에 적용할 스타일 */
+    style: CSSProperties;
+    /** 등장 완료 여부 */
+    isVisible: boolean;
+}
+/**
+ * useBlurIn — 블러에서 선명하게 + 스케일 등장
+ *
+ * 인용구, 임팩트 문구, 핵심 메시지에 적합.
+ * blur + scale + opacity 세 가지가 동시에 전환됨.
+ *
+ * @example
+ * ```tsx
+ * const { style } = useBlurIn({ blurAmount: 12, scale: 0.95, active: isInView })
+ * return <blockquote style={style}>Deep insight here</blockquote>
+ * ```
+ */
+declare function useBlurIn(options?: BlurInOptions): BlurInReturn;
+
+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 AutoFadeConfig, type AutoMotionConfig, type AutoPlayConfig, type AutoScaleConfig, type AutoSlideConfig, BaseMotionOptions, BaseMotionReturn, type BlurInOptions, type BlurInReturn, BounceOptions, type ButtonEffectOptions, type CardListOptions, type ClipRevealOptions, type ClipRevealReturn, type CountUpOptions, type CountUpReturn, type CustomCursorOptions, type CustomCursorReturn, type ElementProgressOptions, type ElementProgressReturn, EntranceMotionReturn, EntranceType, FadeInOptions, type GameLoopConfig, type GameState, GradientOptions, HoverMotionOptions, InViewOptions, InViewReturn, InteractionReturn, type InteractiveConfig, type InteractiveState, type KeyboardToggleConfig, type LanguageConfig, type LayoutMotionConfig, type LayoutState, type LoadingSpinnerOptions, type MagneticCursorOptions, type MagneticCursorReturn, Motion, type MotionEffects, MotionElement, type MotionFromToConfig, type MotionProps, MouseOptions, MouseReturn, type NavigationOptions, PageMotionRef, PageMotionsConfig, PageType, type PerformanceMonitorConfig, type PerformanceMonitorState, PulseOptions, ReducedMotionReturn, RepeatOptions, ScaleOptions, type ScrollDirectionConfig, type ScrollPositionToggleConfig, ScrollRevealMotionType, ScrollRevealOptions, type ScrollToggleOptions, type SequenceConfig, type SkeletonOptions, SlideOptions, type SmoothScrollOptions, type SmoothScrollReturn, SpringOptions, type StickyToggleConfig, ToggleMotionOptions, type TypewriterOptions, type TypewriterReturn, type MotionConfig as UseMotionConfig, type OrchestrationConfig as UseOrchestrationConfig, type UseStaggerOptions, type UseStaggerReturn, type UseUnifiedMotionOptions, type ViewportToggleConfig, type VisibilityToggleOptions, WindowSizeOptions, WindowSizeReturn, createLayoutTransition, observeElement, useAutoFade, useAutoPlay, useAutoScale, useAutoSlide, useBlurIn, useBounceIn, useButtonEffect, useCardList, useClickToggle, useClipReveal, useCountUp, useCustomCursor, useElementProgress, useFadeIn, useFocusToggle, useGameLoop, useGesture, useGestureMotion, useGradient, useHoverMotion, useInView, useInteractive, useKeyboardToggle, useLanguageAwareMotion, useLayoutMotion, useLoadingSpinner, useMagneticCursor, useMotion, useMotionOrchestra, useMotionState, useMouse, useNavigation, useOrchestration, usePageMotions, usePerformanceMonitor, usePulse, useReducedMotion, useReducedMotionObject, useRepeat, useScaleIn, useScrollDirection, useScrollPositionToggle, useScrollProgress, useScrollReveal, useScrollToggle, useSequence, useSimplePageMotion, useSkeleton, useSlideDown, useSlideLeft, useSlideRight, useSlideUp, useSmartMotion, useSmoothScroll, useSpringMotion, useStagger, useStickyToggle, useToggleMotion, useTypewriter, useUnifiedMotion, useViewportToggle, useVisibilityToggle, useWindowSize };