hookery 1.0.0 → 1.0.1

package/dist/index.d.mts

@@ -1,3130 +0,0 @@
-import * as react from 'react';
-import { useEffect, EffectCallback, DependencyList, RefObject, UIEvent, MutableRefObject, FormEvent } from 'react';
-import { AnimationConfig, AnimationItem } from 'lottie-web';
-import * as THREE from 'three';
-
-/**
- * useIsomorphicLayoutEffect
- *
- * SSR-safe version of useLayoutEffect.
- * Uses useEffect on the server and useLayoutEffect in the browser.
- *
- * @example
- * ```tsx
- * useIsomorphicLayoutEffect(() => {
- *   // DOM measurements or mutations
- * }, [dependency]);
- * ```
- */
-declare const useIsomorphicLayoutEffect: typeof useEffect;
-
-interface UseToggleOptions {
-    /** Initial value for the toggle (default: false) */
-    initialValue?: boolean;
-}
-interface UseToggleReturn {
-    /** Current toggle value */
-    value: boolean;
-    /** Toggle the value */
-    toggle: () => void;
-    /** Set value to true */
-    setTrue: () => void;
-    /** Set value to false */
-    setFalse: () => void;
-    /** Set to specific value */
-    setValue: (value: boolean) => void;
-}
-/**
- * useToggle
- *
- * A simple hook for managing boolean state with stable action handlers.
- *
- * @param options - Configuration options
- * @returns Object with value and control functions
- *
- * @example
- * ```tsx
- * const { value, toggle, setTrue, setFalse } = useToggle();
- *
- * return (
- *   <div>
- *     <p>Value: {value ? 'ON' : 'OFF'}</p>
- *     <button onClick={toggle}>Toggle</button>
- *     <button onClick={setTrue}>Set ON</button>
- *     <button onClick={setFalse}>Set OFF</button>
- *   </div>
- * );
- * ```
- */
-declare function useToggle(options?: UseToggleOptions): UseToggleReturn;
-
-interface UseCounterOptions {
-    /** Initial value (default: 0) */
-    initialValue?: number;
-    /** Minimum value (optional) */
-    min?: number;
-    /** Maximum value (optional) */
-    max?: number;
-    /** Step value for increment/decrement (default: 1) */
-    step?: number;
-}
-interface UseCounterReturn {
-    /** Current count value */
-    count: number;
-    /** Increment by step */
-    increment: () => void;
-    /** Decrement by step */
-    decrement: () => void;
-    /** Reset to initial value */
-    reset: () => void;
-    /** Set to specific value */
-    set: (value: number) => void;
-}
-/**
- * useCounter
- *
- * A hook for managing numeric state with increment, decrement, and bounds.
- *
- * @param options - Configuration options
- * @returns Object with count value and control functions
- *
- * @example
- * ```tsx
- * const { count, increment, decrement, reset } = useCounter({
- *   initialValue: 0,
- *   min: 0,
- *   max: 10,
- *   step: 1,
- * });
- *
- * return (
- *   <div>
- *     <p>Count: {count}</p>
- *     <button onClick={decrement}>-</button>
- *     <button onClick={increment}>+</button>
- *     <button onClick={reset}>Reset</button>
- *   </div>
- * );
- * ```
- */
-declare function useCounter(options?: UseCounterOptions): UseCounterReturn;
-
-/**
- * usePrevious
- *
- * A hook that returns the previous value of a state or prop.
- *
- * @param value - The value to track
- * @returns The previous value (undefined on first render)
- *
- * @example
- * ```tsx
- * const [count, setCount] = useState(0);
- * const previousCount = usePrevious(count);
- *
- * console.log(`Current: ${count}, Previous: ${previousCount}`);
- * ```
- */
-declare function usePrevious<T>(value: T): T | undefined;
-
-/**
- * useMount
- *
- * A hook that runs a callback once when the component mounts.
- * Works correctly with React Strict Mode.
- *
- * @param callback - Function to run on mount
- *
- * @example
- * ```tsx
- * useMount(() => {
- *   console.log('Component mounted!');
- *   // Initialize analytics, fetch initial data, etc.
- * });
- * ```
- */
-declare function useMount(callback: () => void | (() => void)): void;
-
-/**
- * useUnmount
- *
- * A hook that runs a callback when the component unmounts.
- * Always uses the latest callback reference.
- *
- * @param callback - Function to run on unmount
- *
- * @example
- * ```tsx
- * useUnmount(() => {
- *   console.log('Component unmounted!');
- *   // Cleanup subscriptions, cancel requests, etc.
- * });
- * ```
- */
-declare function useUnmount(callback: () => void): void;
-
-interface UseDebounceOptions {
-    /** Delay in milliseconds (default: 500) */
-    delay?: number;
-    /** Maximum wait time in milliseconds (optional) */
-    maxWait?: number;
-    /** Leading edge execution (default: false) */
-    leading?: boolean;
-    /** Trailing edge execution (default: true) */
-    trailing?: boolean;
-}
-interface UseDebounceReturn<T> {
-    /** The debounced value */
-    debouncedValue: T;
-    /** Whether currently in debounce period */
-    isPending: boolean;
-    /** Cancel pending debounce */
-    cancel: () => void;
-    /** Flush debounced value immediately */
-    flush: () => void;
-}
-/**
- * useDebounce
- *
- * A hook that debounces a value, delaying updates until after a specified delay.
- *
- * @param value - The value to debounce
- * @param options - Configuration options
- * @returns Object with debounced value and control functions
- *
- * @example
- * ```tsx
- * const [searchTerm, setSearchTerm] = useState('');
- * const { debouncedValue } = useDebounce(searchTerm, { delay: 300 });
- *
- * useEffect(() => {
- *   // API call with debounced value
- *   fetchResults(debouncedValue);
- * }, [debouncedValue]);
- * ```
- */
-declare function useDebounce<T>(value: T, options?: UseDebounceOptions): UseDebounceReturn<T>;
-
-interface UseThrottleOptions {
-    /** Throttle interval in milliseconds (default: 500) */
-    interval?: number;
-    /** Execute on leading edge (default: true) */
-    leading?: boolean;
-    /** Execute on trailing edge (default: true) */
-    trailing?: boolean;
-}
-interface UseThrottleReturn<T> {
-    /** The throttled value */
-    throttledValue: T;
-    /** Whether currently in throttle period */
-    isPending: boolean;
-}
-/**
- * useThrottle
- *
- * A hook that throttles a value, limiting how often it can update.
- *
- * @param value - The value to throttle
- * @param options - Configuration options
- * @returns Object with throttled value and pending state
- *
- * @example
- * ```tsx
- * const [scrollY, setScrollY] = useState(0);
- * const { throttledValue } = useThrottle(scrollY, { interval: 100 });
- *
- * useEffect(() => {
- *   // Update UI with throttled scroll position
- *   updateScrollIndicator(throttledValue);
- * }, [throttledValue]);
- * ```
- */
-declare function useThrottle<T>(value: T, options?: UseThrottleOptions): UseThrottleReturn<T>;
-
-interface UseLocalStorageOptions<T> {
-    /** Serializer function (default: JSON.stringify) */
-    serializer?: (value: T) => string;
-    /** Deserializer function (default: JSON.parse) */
-    deserializer?: (value: string) => T;
-    /** Sync across tabs (default: true) */
-    syncAcrossTabs?: boolean;
-}
-interface UseLocalStorageReturn<T> {
-    /** Current stored value */
-    value: T;
-    /** Set the value */
-    setValue: (value: T | ((prev: T) => T)) => void;
-    /** Remove the value from storage */
-    remove: () => void;
-    /** Check if value exists in storage */
-    exists: boolean;
-}
-/**
- * useLocalStorage
- *
- * A hook for persisting state in localStorage with SSR support and cross-tab sync.
- *
- * @param key - Storage key
- * @param initialValue - Default value if key doesn't exist
- * @param options - Configuration options
- * @returns Object with value and control functions
- *
- * @example
- * ```tsx
- * interface AppSettings {
- *   theme: 'dark' | 'light';
- *   notifications: boolean;
- * }
- *
- * // Default settings
- * const defaults: AppSettings = { theme: 'light', notifications: true };
- *
- * export function SettingsPanel() {
- *   const {
- *     value: settings,
- *     setValue: setSettings,
- *     remove,
- *     exists
- *   } = useLocalStorage<AppSettings>('app-settings', defaults);
- *
- *   const toggleTheme = () => {
- *     setSettings(prev => ({
- *       ...prev,
- *       theme: prev.theme === 'dark' ? 'light' : 'dark'
- *     }));
- *   };
- *
- *   return (
- *     <div className={`panel ${settings.theme}`}>
- *       <h2>Settings {exists ? '(Saved)' : '(Default)'}</h2>
- *
- *       <div className="option">
- *         <label>Theme: {settings.theme}</label>
- *         <button onClick={toggleTheme}>Toggle Theme</button>
- *       </div>
- *
- *       <div className="option">
- *         <label>
- *           <input
- *             type="checkbox"
- *             checked={settings.notifications}
- *             onChange={e => setSettings(p => ({ ...p, notifications: e.target.checked }))}
- *           />
- *           Enable Notifications
- *         </label>
- *       </div>
- *
- *       <button onClick={remove} className="danger">
- *         Reset to Defaults
- *       </button>
- *     </div>
- *   );
- * }
- * ```
- */
-declare function useLocalStorage<T>(key: string, initialValue: T, options?: UseLocalStorageOptions<T>): UseLocalStorageReturn<T>;
-
-interface UseSessionStorageOptions<T> {
-    /** Serializer function (default: JSON.stringify) */
-    serializer?: (value: T) => string;
-    /** Deserializer function (default: JSON.parse) */
-    deserializer?: (value: string) => T;
-    /** Initialize even if key exists (default: false) */
-    initializeWithValue?: boolean;
-}
-/**
- * useSessionStorage
- *
- * A hook for managing state in sessionStorage.
- * Clears when the page session ends (tab close).
- *
- * @param key - Storage key
- * @param initialValue - Initial value
- * @param options - Configuration options
- * @returns [value, setValue, removeValue]
- *
- * @example
- * ```tsx
- * interface FormData {
- *   step: number;
- *   data: Record<string, any>;
- * }
- *
- * const initialForm: FormData = { step: 1, data: {} };
- *
- * export function MultiStepForm() {
- *   // Persist form state even if user refreshes, but clear on close
- *   const [formState, setFormState, clearSession] = useSessionStorage<FormData>(
- *     'registration_form',
- *     initialForm
- *   );
- *
- *   const nextStep = (newData: any) => {
- *     setFormState(prev => ({
- *       step: prev.step + 1,
- *       data: { ...prev.data, ...newData }
- *     }));
- *   };
- *
- *   return (
- *     <div>
- *       <h1>Step {formState.step}</h1>
- *       <FormStep
- *         step={formState.step}
- *         onSubmit={nextStep}
- *       />
- *
- *       <button onClick={clearSession}>
- *         Cancel & Clear Session
- *       </button>
- *     </div>
- *   );
- * }
- * ```
- */
-declare function useSessionStorage<T>(key: string, initialValue: T | (() => T), options?: UseSessionStorageOptions<T>): [T, (value: T | ((val: T) => T)) => void, () => void];
-
-interface UseTimeoutOptions {
-    /** Delay in milliseconds */
-    delay: number;
-    /** Auto-start the timeout (default: true) */
-    autoStart?: boolean;
-}
-interface UseTimeoutReturn {
-    /** Whether the timeout is currently running */
-    isRunning: boolean;
-    /** Whether the timeout has completed */
-    isComplete: boolean;
-    /** Start or restart the timeout */
-    start: () => void;
-    /** Stop/cancel the timeout */
-    stop: () => void;
-    /** Reset the timeout to initial state */
-    reset: () => void;
-}
-/**
- * useTimeout
- *
- * A declarative hook for managing timeouts.
- *
- * @param callback - Function to call when timeout completes
- * @param options - Configuration options
- * @returns Object with timeout state and control functions
- *
- * @example
- * ```tsx
- * const { isRunning, start, stop } = useTimeout(
- *   () => console.log('Timeout completed!'),
- *   { delay: 3000 }
- * );
- *
- * return (
- *   <div>
- *     <p>Status: {isRunning ? 'Running' : 'Stopped'}</p>
- *     <button onClick={start}>Start</button>
- *     <button onClick={stop}>Stop</button>
- *   </div>
- * );
- * ```
- */
-declare function useTimeout(callback: () => void, options: UseTimeoutOptions): UseTimeoutReturn;
-
-interface UseIntervalOptions {
-    /** Interval delay in milliseconds */
-    delay: number;
-    /** Auto-start the interval (default: true) */
-    autoStart?: boolean;
-    /** Execute callback immediately on start (default: false) */
-    immediate?: boolean;
-}
-interface UseIntervalReturn {
-    /** Whether the interval is currently running */
-    isRunning: boolean;
-    /** Number of times the callback has been called */
-    count: number;
-    /** Start the interval */
-    start: () => void;
-    /** Stop/pause the interval */
-    stop: () => void;
-    /** Reset count to 0 */
-    reset: () => void;
-}
-/**
- * useInterval
- *
- * A declarative hook for managing intervals.
- *
- * @param callback - Function to call on each interval tick
- * @param options - Configuration options
- * @returns Object with interval state and control functions
- *
- * @example
- * ```tsx
- * const { count, isRunning, start, stop } = useInterval(
- *   () => console.log('Tick!'),
- *   { delay: 1000 }
- * );
- *
- * return (
- *   <div>
- *     <p>Count: {count}</p>
- *     <button onClick={isRunning ? stop : start}>
- *       {isRunning ? 'Stop' : 'Start'}
- *     </button>
- *   </div>
- * );
- * ```
- */
-declare function useInterval(callback: () => void, options: UseIntervalOptions): UseIntervalReturn;
-
-/**
- * useUpdateEffect
- *
- * A hook that works like useEffect but skips the first render.
- * Useful when you only want to run an effect on updates, not on mount.
- *
- * @param effect - Effect callback (same as useEffect)
- * @param deps - Dependency array (same as useEffect)
- *
- * @example
- * ```tsx
- * const [count, setCount] = useState(0);
- *
- * useUpdateEffect(() => {
- *   console.log('Count updated to:', count);
- *   // This won't run on initial mount, only on updates
- * }, [count]);
- * ```
- */
-declare function useUpdateEffect(effect: EffectCallback, deps?: DependencyList): void;
-
-/**
- * useIsMounted
- *
- * A hook that returns a function to check if the component is still mounted.
- * Useful for preventing state updates on unmounted components in async operations.
- *
- * @returns Function that returns true if component is mounted
- *
- * @example
- * ```tsx
- * const isMounted = useIsMounted();
- *
- * useEffect(() => {
- *   fetchData().then((data) => {
- *     if (isMounted()) {
- *       setData(data); // Safe - only updates if mounted
- *     }
- *   });
- * }, []);
- * ```
- */
-declare function useIsMounted(): () => boolean;
-
-/**
- * useStableCallback
- *
- * Creates a callback function that maintains a stable reference identity
- * while accessing the latest props/state. Useful for avoiding
- * unnecessary effect re-executions.
- *
- * @param callback - The function to stabilize
- * @returns A stable callback function
- *
- * @example
- * ```tsx
- * const stableLog = useStableCallback(() => {
- *   console.log(count); // Alway access latest count
- * });
- *
- * // stableLog identity never changes, safe to use in useEffect deps
- * useEffect(() => {
- *   stableLog();
- * }, [stableLog]);
- * ```
- */
-declare function useStableCallback<T extends (...args: any[]) => any>(callback: T): T;
-
-interface UseMediaQueryOptions {
-    /** Default value for SSR (default: false) */
-    defaultValue?: boolean;
-    /** Initialize on mount only (default: false) */
-    initializeOnMount?: boolean;
-}
-/**
- * useMediaQuery
- *
- * A hook that tracks the state of a CSS media query.
- * Supports SSR with default values and hydration mismatch prevention.
- *
- * @param query - CSS media query string
- * @param options - Configuration options
- * @returns Whether the media query matches
- *
- * @example
- * ```tsx
- * // Basic Mobile Detection
- * const isMobile = useMediaQuery('(max-width: 768px)');
- *
- * // Advanced Usage with SSR support
- * const isDarkMode = useMediaQuery('(prefers-color-scheme: dark)', {
- *   defaultValue: false,       // Default value during server rendering
- *   initializeOnMount: true    // Prevent hydration mismatch by initializing on mount
- * });
- *
- * return (
- *   <div style={{ background: isDarkMode ? '#333' : '#FFF' }}>
- *     <h1>{isMobile ? 'Mobile View' : 'Desktop View'}</h1>
- *     <p>Current Theme: {isDarkMode ? 'Dark' : 'Light'}</p>
- *   </div>
- * );
- * ```
- */
-declare function useMediaQuery(query: string, options?: UseMediaQueryOptions): boolean;
-
-interface WindowSize {
-    /** Window inner width */
-    width: number;
-    /** Window inner height */
-    height: number;
-}
-interface UseWindowSizeOptions {
-    /** Debounce delay in ms (default: 0) */
-    debounce?: number;
-    /** Initial width for SSR (default: 0) */
-    initialWidth?: number;
-    /** Initial height for SSR (default: 0) */
-    initialHeight?: number;
-}
-/**
- * useWindowSize
- *
- * A hook that tracks the browser window dimensions.
- * Handles debouncing to avoid performance issues during resize.
- *
- * @param options - Configuration options
- * @returns Object with width and height
- *
- * @example
- * ```tsx
- * const { width, height } = useWindowSize({
- *   debounce: 100,          // Wait 100ms after resize stops
- *   initialWidth: 1920,     // Predictable server-side width
- *   initialHeight: 1080
- * });
- *
- * const isLandscape = width > height;
- *
- * return (
- *   <div>
- *     <h2>Viewport Info</h2>
- *     <p>Dimensions: {width}px x {height}px</p>
- *     <p>Orientation: {isLandscape ? 'Landscape' : 'Portrait'}</p>
- *
- *     {width < 768 && (
- *       <div className="mobile-warning">
- *         Optimized for Desktop
- *       </div>
- *     )}
- *   </div>
- * );
- * ```
- */
-declare function useWindowSize(options?: UseWindowSizeOptions): WindowSize;
-
-interface UseClickOutsideOptions {
-    /** Events to listen for (default: ['mousedown', 'touchstart']) */
-    events?: Array<'mousedown' | 'mouseup' | 'touchstart' | 'touchend'>;
-    /** Whether the listener is active (default: true) */
-    enabled?: boolean;
-}
-/**
- * useClickOutside
- *
- * A hook that detects clicks outside of a referenced element.
- * Useful for closing modals, dropdowns, or popovers.
- *
- * @param ref - React ref to the element to monitor
- * @param callback - Function to call when clicking outside
- * @param options - Configuration options
- *
- * @example
- * ```tsx
- * const [isOpen, setIsOpen] = useState(false);
- * const menuRef = useRef<HTMLDivElement>(null);
- *
- * useClickOutside(menuRef, () => {
- *   console.log('Clicked outside menu, closing...');
- *   setIsOpen(false);
- * }, {
- *   enabled: isOpen, // Only listen when menu is open (performance)
- *   events: ['mousedown', 'touchstart'] // Handle touch devices too
- * });
- *
- * return (
- *   <div className="relative">
- *     <button onClick={() => setIsOpen(!isOpen)}>Toggle Menu</button>
- *
- *     {isOpen && (
- *       <div ref={menuRef} className="dropdown-menu">
- *         <p>Menu Item 1</p>
- *         <p>Menu Item 2</p>
- *       </div>
- *     )}
- *   </div>
- * );
- * ```
- */
-declare function useClickOutside<T extends HTMLElement = HTMLElement>(ref: RefObject<T | null>, callback: (event: MouseEvent | TouchEvent) => void, options?: UseClickOutsideOptions): void;
-
-interface UseHoverReturn<T extends HTMLElement = HTMLElement> {
-    /** Whether the element is being hovered */
-    isHovered: boolean;
-    /** Ref to attach to the target element */
-    ref: React.RefCallback<T>;
-    /** Props to spread on the target element */
-    hoverProps: {
-        onMouseEnter: () => void;
-        onMouseLeave: () => void;
-    };
-}
-/**
- * useHover
- *
- * A hook that tracks hover state of an element.
- * Provides both a ref-based and prop-based API for flexibility.
- *
- * @returns Object with hover state, ref, and event handlers
- *
- * @example
- * ```tsx
- * // pattern 1: Using Ref (Recommended for access to DOM)
- * const { isHovered: isCardHovered, ref: cardRef } = useHover<HTMLDivElement>();
- *
- * // pattern 2: Using Spread Props (Easier for simpler components)
- * const { isHovered: isBtnHovered, hoverProps } = useHover();
- *
- * return (
- *   <div>
- *     <div
- *       ref={cardRef}
- *       style={{
- *         padding: 20,
- *         background: isCardHovered ? '#eee' : '#fff'
- *       }}
- *     >
- *       {isCardHovered ? 'Card Active!' : 'Hover Card'}
- *     </div>
- *
- *     <button
- *       {...hoverProps}
- *       style={{ opacity: isBtnHovered ? 1 : 0.7 }}
- *     >
- *       {isBtnHovered ? 'Click Me!' : 'Button'}
- *     </button>
- *   </div>
- * );
- * ```
- */
-declare function useHover<T extends HTMLElement = HTMLElement>(): UseHoverReturn<T>;
-
-interface UseKeyPressOptions {
-    /** Target element (default: window) */
-    target?: 'window' | 'document';
-    /** Event type (default: 'keydown') */
-    event?: 'keydown' | 'keyup' | 'keypress';
-    /** Whether to prevent default behavior */
-    preventDefault?: boolean;
-    /** Whether the listener is active (default: true) */
-    enabled?: boolean;
-}
-/**
- * useKeyPress
- *
- * A hook that tracks whether a specific key is pressed.
- *
- * @param targetKey - The key to track (e.g., 'Enter', 'Escape', 'a')
- * @param callback - Optional callback when key is pressed
- * @param options - Configuration options
- * @returns Whether the key is currently pressed
- *
- * @example
- * ```tsx
- * // Simple usage
- * const isEnterPressed = useKeyPress('Enter');
- *
- * // With callback
- * useKeyPress('Escape', () => {
- *   closeModal();
- * });
- *
- * // With modifiers (check inside callback)
- * useKeyPress('s', (event) => {
- *   if (event.ctrlKey) {
- *     event.preventDefault();
- *     saveDocument();
- *   }
- * });
- * ```
- */
-declare function useKeyPress(targetKey: string, callback?: (event: KeyboardEvent) => void, options?: UseKeyPressOptions): boolean;
-
-interface ScrollPosition {
-    /** Horizontal scroll position */
-    x: number;
-    /** Vertical scroll position */
-    y: number;
-}
-interface UseScrollOptions {
-    /** Throttle delay in ms (default: 0) */
-    throttle?: number;
-}
-interface UseScrollReturn extends ScrollPosition {
-    /** Whether scroll is at the top */
-    isAtTop: boolean;
-    /** Whether scroll is at the bottom */
-    isAtBottom: boolean;
-    /** Whether scroll is at the left */
-    isAtLeft: boolean;
-    /** Whether scroll is at the right */
-    isAtRight: boolean;
-    /** Scroll direction */
-    direction: 'up' | 'down' | 'left' | 'right' | null;
-}
-/**
- * useScroll
- *
- * A hook that tracks scroll position of window or an element.
- * Provides coordinates, direction, and boundary detection (top/bottom/left/right).
- *
- * @param ref - Optional ref to track element scroll (defaults to window)
- * @param options - Configuration options
- * @returns Object with scroll position and state
- *
- * @example
- * ```tsx
- * // Track window scroll with progress bar
- * const { y, direction, isAtTop, isAtBottom } = useScroll();
- *
- * // Track specific element
- * const containerRef = useRef<HTMLDivElement>(null);
- * const { x } = useScroll(containerRef, { throttle: 100 });
- *
- * return (
- *   <>
- *     <div className="fixed-header" style={{ opacity: isAtTop ? 1 : 0.8 }}>
- *       Scrolling: {direction}
- *       {isAtBottom && <span> (Reached Bottom!)</span>}
- *     </div>
- *
- *     <div
- *       ref={containerRef}
- *       style={{ width: 300, overflowX: 'scroll', whiteSpace: 'nowrap' }}
- *     >
- *       {items.map(item => <Item key={item.id} {...item} />)}
- *     </div>
- *   </>
- * );
- * ```
- */
-declare function useScroll<T extends HTMLElement = HTMLElement>(ref?: RefObject<T | null>, options?: UseScrollOptions): UseScrollReturn;
-
-interface UseIntersectionOptions {
-    /** Root element for intersection (default: viewport) */
-    root?: Element | null;
-    /** Root margin (default: '0px') */
-    rootMargin?: string;
-    /** Threshold(s) for intersection (default: 0) */
-    threshold?: number | number[];
-    /** Trigger only once (default: false) */
-    triggerOnce?: boolean;
-    /** Whether the observer is active (default: true) */
-    enabled?: boolean;
-}
-interface UseIntersectionReturn {
-    /** Whether the element is intersecting */
-    isIntersecting: boolean;
-    /** The intersection entry */
-    entry: IntersectionObserverEntry | null;
-    /** Ref to attach to the target element */
-    ref: RefObject<HTMLElement | null>;
-}
-/**
- * useIntersection
- *
- * A hook that uses IntersectionObserver to detect element visibility.
- * Perfect for lazy loading images, infinite scrolling, or animations.
- *
- * @param options - Configuration options
- * @returns Object with intersection state and ref
- *
- * @example
- * ```tsx
- * const { ref, isIntersecting, entry } = useIntersection({
- *   threshold: 0.5,     // Trigger when 50% visible
- *   triggerOnce: true,  // Only trigger once (good for animations)
- *   rootMargin: '100px' // Pre-load before appearing on screen
- * });
- *
- * return (
- *   <div
- *     ref={ref}
- *     className={`transition-opacity duration-500 ${
- *       isIntersecting ? 'opacity-100' : 'opacity-0'
- *     }`}
- *   >
- *     {isIntersecting ? (
- *       <img src="heavy-image.jpg" alt="Lazy loaded" />
- *     ) : (
- *       <div className="placeholder" />
- *     )}
- *   </div>
- * );
- * ```
- */
-declare function useIntersection(options?: UseIntersectionOptions): UseIntersectionReturn;
-
-interface UseCopyToClipboardReturn {
-    /** The last copied value */
-    copiedValue: string | null;
-    /** Whether the copy was successful */
-    isSuccess: boolean;
-    /** Any error that occurred */
-    error: Error | null;
-    /** Function to copy text to clipboard */
-    copy: (text: string) => Promise<boolean>;
-    /** Reset state */
-    reset: () => void;
-}
-/**
- * useCopyToClipboard
- *
- * A hook for copying text to the clipboard.
- * Uses modern Clipboard API with fallback for legacy browsers.
- *
- * @returns Object with copy function and state
- *
- * @example
- * ```tsx
- * const { copy, copiedValue, isSuccess, error } = useCopyToClipboard();
- *
- * const handleCopy = async () => {
- *   const success = await copy('API_KEY_12345');
- *   if (success) {
- *     toast.success('Copied to clipboard!');
- *   }
- * };
- *
- * return (
- *   <div className="api-key-box">
- *     <code>API_KEY_12345</code>
- *
- *     <button onClick={handleCopy} disabled={isSuccess}>
- *       {isSuccess ? 'Copied!' : 'Copy Key'}
- *     </button>
- *
- *     {error && <p className="error">Failed to copy: {error.message}</p>}
- *
- *     {isSuccess && (
- *       <p className="hint">
- *         Last copied: {copiedValue}
- *       </p>
- *     )}
- *   </div>
- * );
- * ```
- */
-declare function useCopyToClipboard(): UseCopyToClipboardReturn;
-
-interface UseDocumentTitleOptions {
-    /** Restore previous title on unmount (default: true) */
-    restoreOnUnmount?: boolean;
-}
-/**
- * useDocumentTitle
- *
- * A hook that sets the document title.
- *
- * @param title - The title to set
- * @param options - Configuration options
- *
- * @example
- * ```tsx
- * useDocumentTitle('Dashboard - My App');
- *
- * // With dynamic title
- * useDocumentTitle(`${unreadCount} new messages`);
- *
- * // Don't restore on unmount
- * useDocumentTitle('Settings', { restoreOnUnmount: false });
- * ```
- */
-declare function useDocumentTitle(title: string, options?: UseDocumentTitleOptions): void;
-
-/**
- * useLockBodyScroll
- *
- * A hook that locks body scroll when active (useful for modals).
- *
- * @param lock - Whether to lock scroll (default: true)
- *
- * @example
- * ```tsx
- * const [isModalOpen, setIsModalOpen] = useState(false);
- *
- * useLockBodyScroll(isModalOpen);
- *
- * return (
- *   <>
- *     <button onClick={() => setIsModalOpen(true)}>Open Modal</button>
- *     {isModalOpen && <Modal onClose={() => setIsModalOpen(false)} />}
- *   </>
- * );
- * ```
- */
-declare function useLockBodyScroll(lock?: boolean): void;
-
-type Theme = 'light' | 'dark' | 'system';
-interface UseThemeOptions {
-    /** Key to store theme in localStorage (default: 'theme') */
-    storageKey?: string;
-    /** Attribute to apply to HTML element (default: 'data-theme') */
-    attribute?: string;
-    /** Default theme if storage is empty (default: 'system') */
-    defaultTheme?: Theme;
-    /** Disable transition on theme switch to prevent flicker (default: true) */
-    disableTransitionOnChange?: boolean;
-}
-interface UseThemeReturn {
-    /** Active theme (light/dark/system) */
-    theme: Theme;
-    /** Resolved theme (light/dark) */
-    resolvedTheme: 'light' | 'dark';
-    /** Set theme */
-    setTheme: (theme: Theme) => void;
-    /** Toggle between light and dark */
-    toggleTheme: () => void;
-}
-/**
- * useTheme
- *
- * A hook for managing light/dark mode with system preference support
- * and no-flash-of-unstyled-content (FOUC).
- *
- * @param options - Configuration options
- * @returns Theme state and controls
- *
- * @example
- * ```tsx
- * const { theme, toggleTheme } = useTheme();
- *
- * return (
- *   <button onClick={toggleTheme}>
- *     Current: {theme}
- *   </button>
- * );
- * ```
- */
-declare function useTheme(options?: UseThemeOptions): UseThemeReturn;
-
-interface UseEventOptions {
-    /** Capture phase (default: false) */
-    capture?: boolean;
-    /** Passive listener (default: false) */
-    passive?: boolean;
-    /** Once listener (default: false) */
-    once?: boolean;
-}
-/**
- * useEvent
- *
- * A hook that attaches an event listener to a target element.
- * Handles adding/removing listeners automatically on cleanup.
- *
- * @param name - Event name
- * @param handler - Event handler function
- * @param target - Target element (default: window)
- * @param options - Event options
- *
- * @example
- * ```tsx
- * useEvent('click', handleClick);
- * useEvent('scroll', handleScroll, window, { passive: true });
- * ```
- */
-declare function useEvent<KD extends keyof DocumentEventMap>(name: KD, handler: (this: Document, ev: DocumentEventMap[KD]) => any, target?: Document | null, options?: UseEventOptions): void;
-declare function useEvent<KH extends keyof HTMLElementEventMap>(name: KH, handler: (this: HTMLElement, ev: HTMLElementEventMap[KH]) => any, target?: HTMLElement | null, options?: UseEventOptions): void;
-declare function useEvent<KW extends keyof WindowEventMap>(name: KW, handler: (this: Window, ev: WindowEventMap[KW]) => any, target?: Window | null, options?: UseEventOptions): void;
-
-interface UseLongPressOptions {
-    /** Time in ms to trigger long press (default: 500) */
-    threshold?: number;
-    /** Cancel on movement (default: true) */
-    cancelOnMove?: boolean;
-    /** Triggered when long press starts */
-    onStart?: (event: AnyEvent) => void;
-    /** Triggered when long press finishes successfully */
-    onFinish?: (event: AnyEvent) => void;
-    /** Triggered when long press is cancelled */
-    onCancel?: (event: AnyEvent) => void;
-}
-type AnyEvent = MouseEvent | TouchEvent | React.MouseEvent | React.TouchEvent;
-interface UseLongPressReturn {
-    onMouseDown: (e: any) => void;
-    onTouchStart: (e: any) => void;
-    onMouseUp: (e: any) => void;
-    onMouseLeave: (e: any) => void;
-    onTouchEnd: (e: any) => void;
-}
-/**
- * useLongPress
- *
- * A hook for detecting long press gestures.
- *
- * @param onLongPress - Callback fired when long press threshold is reached
- * @param options - Configuration options
- * @returns Event handlers to spread onto element
- *
- * @example
- * ```tsx
- * const onLongPress = () => {
- *   console.log('Long pressed!');
- * };
- *
- * const bind = useLongPress(onLongPress);
- *
- * return <button {...bind}>Press me</button>;
- * ```
- */
-declare function useLongPress(onLongPress: (event: AnyEvent) => void, options?: UseLongPressOptions): UseLongPressReturn;
-
-/**
- * useWindowFocus
- *
- * A hook that detects if the window currently has focus.
- *
- * @returns boolean - true if window is focused, false if blurred
- *
- * @example
- * ```tsx
- * const isFocused = useWindowFocus();
- *
- * useEffect(() => {
- *   if (isFocused) {
- *     // Resume polling
- *   } else {
- *     // Pause polling
- *   }
- * }, [isFocused]);
- * ```
- */
-declare function useWindowFocus(): boolean;
-
-interface UseResizeObserverOptions {
-    /** Output only contentRect (default: true) */
-    contentRect?: boolean;
-    /** Throttling delay in ms (default: 0) */
-    throttle?: number;
-}
-/**
- * useResizeObserver
- *
- * A hook that tracks element size changes using ResizeObserver.
- *
- * @param ref - Ref to the element to observe
- * @param options - Configuration options
- * @returns The resize observer entry's contentRect
- *
- * @example
- * ```tsx
- * const ref = useRef<HTMLDivElement>(null);
- * const rect = useResizeObserver(ref);
- *
- * return (
- *   <div ref={ref}>
- *     Width: {rect?.width}, Height: {rect?.height}
- *   </div>
- * );
- * ```
- */
-declare function useResizeObserver<T extends HTMLElement = HTMLElement>(ref: RefObject<T | null>, options?: UseResizeObserverOptions): DOMRectReadOnly | undefined;
-
-interface UseMutationObserverOptions extends MutationObserverInit {
-}
-/**
- * useMutationObserver
- *
- * A hook that tracks mutations in the DOM using MutationObserver.
- *
- * @param ref - Ref to the element to observe
- * @param callback - Function to call on mutation
- * @param options - MutationObserver options
- *
- * @example
- * ```tsx
- * const ref = useRef(null);
- * useMutationObserver(ref, (mutations) => {
- *   console.log('DOM changed!', mutations);
- * }, { childList: true });
- * ```
- */
-declare function useMutationObserver<T extends HTMLElement>(ref: RefObject<T | null>, callback: MutationCallback, options?: UseMutationObserverOptions): void;
-
-/**
- * usePageLeave
- *
- * It triggers a callback when the mouse leaves the page (e.g. intent to close tab).
- *
- * @param onPageLeave - Callback function
- *
- * @example
- * ```tsx
- * usePageLeave(() => {
- *   console.log('User is leaving!');
- * });
- * ```
- */
-declare function usePageLeave(onPageLeave: () => void): void;
-
-interface EyeDropperOpenOptions {
-    signal?: AbortSignal;
-}
-interface UseEyeDropperReturn {
-    isSupported: boolean;
-    open: (options?: EyeDropperOpenOptions) => Promise<{
-        sRGBHex: string;
-    } | undefined>;
-}
-/**
- * useEyeDropper
- *
- * A hook for using the EyeDropper API to sample colors from the screen.
- *
- * @returns Object with support status and open function
- *
- * @example
- * ```tsx
- * const { open, isSupported } = useEyeDropper();
- *
- * const pickColor = async () => {
- *   try {
- *     const color = await open();
- *     console.log(color?.sRGBHex);
- *   } catch (e) {
- *     console.error(e);
- *   }
- * };
- * ```
- */
-declare function useEyeDropper(): UseEyeDropperReturn;
-
-interface UseOnlineReturn {
-    /** Whether the browser is online */
-    isOnline: boolean;
-    /** Whether the browser is offline */
-    isOffline: boolean;
-    /** Time since last status change (in ms) */
-    since: number | null;
-}
-/**
- * useOnline
- *
- * A hook that tracks the browser's online/offline status.
- *
- * @returns Object with online status
- *
- * @example
- * ```tsx
- * const { isOnline, isOffline } = useOnline();
- *
- * return (
- *   <div>
- *     {isOnline ? '🟢 Online' : '🔴 Offline'}
- *   </div>
- * );
- * ```
- */
-declare function useOnline(): UseOnlineReturn;
-
-interface NetworkState {
-    online: boolean;
-    downlink?: number;
-    downlinkMax?: number;
-    effectiveType?: 'slow-2g' | '2g' | '3g' | '4g';
-    rtt?: number;
-    saveData?: boolean;
-    type?: 'bluetooth' | 'cellular' | 'ethernet' | 'none' | 'wifi' | 'wimax' | 'other' | 'unknown';
-}
-/**
- * useNetworkState
- *
- * A hook that tracks detailed network connection information.
- * Note: Browser support varies for Navigator.connection.
- */
-declare function useNetworkState(): NetworkState;
-
-interface UseFullscreenReturn {
-    /** Whether fullscreen is active */
-    isFullscreen: boolean;
-    /** Whether fullscreen is supported */
-    isSupported: boolean;
-    /** Enter fullscreen mode */
-    enter: () => Promise<void>;
-    /** Exit fullscreen mode */
-    exit: () => Promise<void>;
-    /** Toggle fullscreen mode */
-    toggle: () => Promise<void>;
-}
-/**
- * useFullscreen
- *
- * A hook for controlling the Fullscreen API.
- *
- * @param ref - Optional ref to element to make fullscreen (defaults to document.documentElement)
- * @returns Object with fullscreen state and controls
- *
- * @example
- * ```tsx
- * // Fullscreen the whole document
- * const { isFullscreen, toggle, isSupported } = useFullscreen();
- *
- * // Fullscreen a specific element
- * const videoRef = useRef<HTMLVideoElement>(null);
- * const { isFullscreen, enter, exit } = useFullscreen(videoRef);
- *
- * return (
- *   <div>
- *     <video ref={videoRef} />
- *     <button onClick={toggle} disabled={!isSupported}>
- *       {isFullscreen ? 'Exit' : 'Enter'} Fullscreen
- *     </button>
- *   </div>
- * );
- * ```
- */
-declare function useFullscreen<T extends HTMLElement = HTMLElement>(ref?: RefObject<T | null>): UseFullscreenReturn;
-
-interface ShareData {
-    /** Title of the shared content */
-    title?: string;
-    /** Text/description of the shared content */
-    text?: string;
-    /** URL to share */
-    url?: string;
-}
-interface UseShareReturn {
-    /** Whether Web Share API is supported */
-    isSupported: boolean;
-    /** Whether a share is currently in progress */
-    isSharing: boolean;
-    /** Whether share was successful */
-    isSuccess: boolean;
-    /** Any error that occurred */
-    error: Error | null;
-    /** Share data */
-    share: (data: ShareData) => Promise<boolean>;
-    /** Check if specific data can be shared */
-    canShare: (data?: ShareData) => boolean;
-}
-/**
- * useShare
- *
- * A hook for using the Web Share API.
- *
- * @returns Object with share function and state
- *
- * @example
- * ```tsx
- * const { share, isSupported, isSharing } = useShare();
- *
- * const handleShare = async () => {
- *   const success = await share({
- *     title: 'Check this out!',
- *     text: 'A very interesting article',
- *     url: window.location.href,
- *   });
- *
- *   if (success) {
- *     console.log('Shared successfully!');
- *   }
- * };
- *
- * if (!isSupported) {
- *   return <CopyLinkButton />;
- * }
- *
- * return (
- *   <button onClick={handleShare} disabled={isSharing}>
- *     {isSharing ? 'Sharing...' : 'Share'}
- *   </button>
- * );
- * ```
- */
-declare function useShare(): UseShareReturn;
-
-type PermissionName = 'geolocation' | 'notifications' | 'push' | 'midi' | 'camera' | 'microphone' | 'speaker-selection' | 'device-info' | 'background-fetch' | 'background-sync' | 'bluetooth' | 'persistent-storage' | 'ambient-light-sensor' | 'accelerometer' | 'gyroscope' | 'magnetometer' | 'clipboard-read' | 'clipboard-write' | 'display-capture' | 'nfc';
-type PermissionState = 'granted' | 'denied' | 'prompt' | 'unknown';
-/**
- * usePermissions
- *
- * A hook to query and track permission status for browser APIs.
- *
- * @param name - The name of the permission to query
- * @returns The current state of the permission
- *
- * @example
- * ```tsx
- * const status = usePermissions('geolocation');
- *
- * return <div>Location permission: {status}</div>;
- * ```
- */
-declare function usePermissions(name: PermissionName | string): PermissionState;
-
-interface UseWakeLockReturn {
-    isSupported: boolean;
-    released: boolean;
-    request: () => Promise<void>;
-    release: () => Promise<void>;
-}
-/**
- * useWakeLock
- *
- * A hook to prevent the device screen from dimming/sleeping.
- *
- * @param onRequest - Callback when lock is acquired
- * @param onRelease - Callback when lock is released
- * @returns Object with lock status and controls
- */
-declare function useWakeLock({ onRequest, onRelease, onError, }?: {
-    onRequest?: () => void;
-    onRelease?: () => void;
-    onError?: (err: Error) => void;
-}): UseWakeLockReturn;
-
-interface UseMediaDevicesReturn {
-    devices: MediaDeviceInfo[];
-    isLoading: boolean;
-    error: Error | null;
-    isSupported: boolean;
-}
-/**
- * useMediaDevices
- *
- * A hook to list and track connected hardware (cameras, microphones, speakers).
- * Automatically updates when devices are plugged in or removed.
- *
- * @returns Object with devices list, loading state, and support status
- *
- * @example
- * ```tsx
- * const { devices, isLoading, error, isSupported } = useMediaDevices();
- *
- * if (!isSupported) return <p>Media Devices API not supported</p>;
- * if (isLoading) return <p>Scanning hardware...</p>;
- *
- * const cameras = devices.filter(d => d.kind === 'videoinput');
- * const mics = devices.filter(d => d.kind === 'audioinput');
- *
- * return (
- *   <div className="device-manager">
- *     <h3>Cameras ({cameras.length})</h3>
- *     <ul>
- *       {cameras.map(c => <li key={c.deviceId}>{c.label || 'Unknown Camera'}</li>)}
- *     </ul>
- *
- *     <h3>Microphones ({mics.length})</h3>
- *     <ul>
- *       {mics.map(m => <li key={m.deviceId}>{m.label || 'Unknown Mic'}</li>)}
- *     </ul>
- *
- *     {error && <p className="error">{error.message}</p>}
- *   </div>
- * );
- * ```
- */
-declare function useMediaDevices(): UseMediaDevicesReturn;
-
-type RecorderStatus = 'idle' | 'recording' | 'paused' | 'stopped';
-interface UseMediaRecorderReturn {
-    status: RecorderStatus;
-    start: (timeSlice?: number) => void;
-    stop: () => void;
-    pause: () => void;
-    resume: () => void;
-    isRecording: boolean;
-    mediaBlob: Blob | undefined;
-    mediaUrl: string | undefined;
-    clear: () => void;
-    error: Error | null;
-}
-/**
- * useMediaRecorder
- *
- * A hook to record media (audio/video) from a MediaStream.
- * Returns a Blob and URL for the recording.
- *
- * @param stream - The MediaStream to record (from useMediaDevices)
- * @param options - MediaRecorder options (mimeType, bitsPerSecond)
- * @returns Object with recording controls and data
- *
- * @example
- * ```tsx
- * const [stream, setStream] = useState<MediaStream | null>(null);
- * const {
- *   status,
- *   start,
- *   stop,
- *   mediaUrl,
- *   clear
- * } = useMediaRecorder(stream);
- *
- * // Setup camera (simplified)
- * useEffect(() => {
- *   navigator.mediaDevices.getUserMedia({ video: true, audio: true })
- *     .then(setStream);
- * }, []);
- *
- * return (
- *   <div>
- *     <video
- *       ref={v => v && (v.srcObject = stream)}
- *       autoPlay muted
- *       width={300}
- *     />
- *
- *     <div className="controls">
- *       <button onClick={() => start()}>Record</button>
- *       <button onClick={stop} disabled={status !== 'recording'}>Stop</button>
- *     </div>
- *
- *     {mediaUrl && (
- *       <div className="preview">
- *         <h3>Recorded Video</h3>
- *         <video src={mediaUrl} controls width={300} />
- *         <a href={mediaUrl} download="recording.webm">Download</a>
- *         <button onClick={clear}>Clear</button>
- *       </div>
- *     )}
- *   </div>
- * );
- * ```
- */
-declare function useMediaRecorder(stream: MediaStream | null, options?: MediaRecorderOptions): UseMediaRecorderReturn;
-
-interface BatteryState {
-    supported: boolean;
-    loading: boolean;
-    level: number;
-    charging: boolean;
-    chargingTime: number;
-    dischargingTime: number;
-}
-/**
- * useBattery
- *
- * A hook that tracks battery status.
- *
- * @returns Battery state object
- */
-declare function useBattery(): BatteryState;
-
-interface UseBluetoothReturn {
-    isSupported: boolean;
-    isConnected: boolean;
-    isConnecting: boolean;
-    device: BluetoothDevice | null;
-    server: BluetoothRemoteGATTServer | null;
-    error: Error | null;
-    requestDevice: (options?: RequestDeviceOptions) => Promise<void>;
-    disconnect: () => void;
-}
-/**
- * useBluetooth
- *
- * A hook for connecting to Bluetooth Low Energy (BLE) devices.
- */
-declare function useBluetooth(): UseBluetoothReturn;
-
-interface UseGamepadOptions {
-    /** Enable polling loop (default: true) */
-    enabled?: boolean;
-}
-/**
- * useGamepad
- *
- * A hook that tracks connected gamepads and their state.
- * Uses requestAnimationFrame for polling input state.
- */
-declare function useGamepad(options?: UseGamepadOptions): {
-    gamepads: (Gamepad | null)[];
-};
-
-interface UseFileSystemReturn {
-    isSupported: boolean;
-    file: File | null;
-    fileHandle: FileSystemFileHandle | null;
-    openFile: (options?: OpenFilePickerOptions) => Promise<void>;
-    saveFile: (data: BlobPart, options?: SaveFilePickerOptions) => Promise<void>;
-    error: Error | null;
-}
-/**
- * useFileSystem
- *
- * A hook for the File System Access API.
- */
-declare function useFileSystem(): UseFileSystemReturn;
-
-interface StorageEstimateState {
-    quota: number | undefined;
-    usage: number | undefined;
-    supported: boolean;
-    loading: boolean;
-}
-/**
- * useStorageEstimate
- *
- * A hook to estimate storage quota and usage.
- */
-declare function useStorageEstimate(): StorageEstimateState;
-
-type AsyncStatus = 'idle' | 'pending' | 'success' | 'error';
-interface UseAsyncOptions<T> {
-    /** Execute immediately on mount (default: false) */
-    immediate?: boolean;
-    /** Initial data value */
-    initialData?: T;
-    /** Callback on success */
-    onSuccess?: (data: T) => void;
-    /** Callback on error */
-    onError?: (error: Error) => void;
-}
-interface UseAsyncReturn<T, Args extends unknown[]> {
-    /** The async function execution result */
-    data: T | undefined;
-    /** Any error that occurred */
-    error: Error | null;
-    /** Current status */
-    status: AsyncStatus;
-    /** Whether currently loading */
-    isLoading: boolean;
-    /** Whether request was successful */
-    isSuccess: boolean;
-    /** Whether request errored */
-    isError: boolean;
-    /** Execute the async function */
-    execute: (...args: Args) => Promise<T | undefined>;
-    /** Reset to initial state */
-    reset: () => void;
-}
-/**
- * useAsync
- *
- * A hook for managing async function state.
- *
- * @param asyncFunction - The async function to execute
- * @param options - Configuration options
- * @returns Object with async state and execute function
- *
- * @example
- * ```tsx
- * const fetchUser = async (id: number) => {
- *   const response = await fetch(`/api/users/${id}`);
- *   return response.json();
- * };
- *
- * const { data, isLoading, execute } = useAsync(fetchUser);
- *
- * return (
- *   <div>
- *     <button onClick={() => execute(1)}>Load User</button>
- *     {isLoading && <Spinner />}
- *     {data && <UserCard user={data} />}
- *   </div>
- * );
- * ```
- */
-declare function useAsync<T, Args extends unknown[] = []>(asyncFunction: (...args: Args) => Promise<T>, options?: UseAsyncOptions<T>): UseAsyncReturn<T, Args>;
-
-type FetchStatus = 'idle' | 'loading' | 'success' | 'error';
-interface UseFetchOptions<T> extends Omit<RequestInit, 'signal'> {
-    /** Execute immediately (default: true) */
-    immediate?: boolean;
-    /** Initial data value */
-    initialData?: T;
-    /** Transform response before setting data */
-    transform?: (response: Response) => Promise<T>;
-    /** Number of retry attempts (default: 0) */
-    retries?: number;
-    /** Retry delay in ms (default: 1000) */
-    retryDelay?: number;
-    /** Callback on success */
-    onSuccess?: (data: T) => void;
-    /** Callback on error */
-    onError?: (error: Error) => void;
-    /** Abort previous request (default: true) */
-    abortPrevious?: boolean;
-}
-interface UseFetchReturn<T> {
-    /** Fetched data */
-    data: T | undefined;
-    /** Error if any */
-    error: Error | null;
-    /** Current status */
-    status: FetchStatus;
-    /** Loading state */
-    isLoading: boolean;
-    /** Success state */
-    isSuccess: boolean;
-    /** Error state */
-    isError: boolean;
-    /** Refetch data */
-    refetch: () => Promise<void>;
-    /** Abort current request */
-    abort: () => void;
-}
-/**
- * useFetch
- *
- * A powerful hook for data fetching with abort, retry, and race condition handling.
- *
- * @param url - URL to fetch
- * @param options - Fetch and hook options
- * @returns Object with data, status, and control functions
- *
- * @example
- * ```tsx
- * interface User { id: number; name: string; }
- *
- * const {
- *   data,
- *   isLoading,
- *   error,
- *   refetch,
- *   abort
- * } = useFetch<User[]>('/api/users', {
- *   retries: 3,
- *   retryDelay: 2000,
- *   immediate: true,
- *   transform: async (res) => {
- *     const json = await res.json();
- *     return json.users; // Transform response structure
- *   },
- *   onSuccess: (data) => console.log('Fetched:', data.length),
- *   onError: (err) => console.error('Failed:', err)
- * });
- *
- * if (isLoading) return <div>Loading... <button onClick={abort}>Cancel</button></div>;
- * if (error) return <ErrorDisplay message={error.message} onRetry={refetch} />;
- *
- * return (
- *   <ul>
- *     {data?.map(user => (
- *       <li key={user.id}>{user.name}</li>
- *     ))}
- *   </ul>
- * );
- * ```
- */
-declare function useFetch<T = unknown>(url: string | null, options?: UseFetchOptions<T>): UseFetchReturn<T>;
-
-type ScriptStatus = 'idle' | 'loading' | 'ready' | 'error';
-interface UseScriptOptions {
-    /** Load script immediately (default: true) */
-    immediate?: boolean;
-    /** Remove script on unmount (default: false) */
-    removeOnUnmount?: boolean;
-    /** Script attributes */
-    attributes?: Record<string, string>;
-}
-interface UseScriptReturn {
-    /** Script loading status */
-    status: ScriptStatus;
-    /** Whether script is loading */
-    isLoading: boolean;
-    /** Whether script is ready */
-    isReady: boolean;
-    /** Whether script failed to load */
-    isError: boolean;
-    /** Load the script manually */
-    load: () => void;
-}
-/**
- * useScript
- *
- * A hook for dynamically loading external scripts.
- *
- * @param src - Script source URL
- * @param options - Configuration options
- * @returns Object with script status and controls
- *
- * @example
- * ```tsx
- * const { isReady, isLoading, isError } = useScript(
- *   'https://maps.googleapis.com/maps/api/js?key=YOUR_KEY'
- * );
- *
- * if (isLoading) return <LoadingSpinner />;
- * if (isError) return <ErrorMessage />;
- * if (isReady) return <GoogleMap />;
- * ```
- */
-declare function useScript(src: string, options?: UseScriptOptions): UseScriptReturn;
-
-type WorkerFunction<T, R> = (input: T) => R;
-type WorkerStatus = 'idle' | 'running' | 'error' | 'success';
-interface UseWorkerReturn<T, R> {
-    result: R | undefined;
-    error: Error | null;
-    status: WorkerStatus;
-    run: (input: T) => void;
-    terminate: () => void;
-}
-/**
- * useWorker
- *
- * A hook to offload heavy computation to a Web Worker.
- *
- * @param workerScript - URL string or Function code to run in worker
- */
-declare function useWorker<T = any, R = any>(workerScript: string | WorkerFunction<T, R>): UseWorkerReturn<T, R>;
-
-interface UseIndexedDBReturn<T> {
-    value: T | undefined;
-    set: (value: T) => Promise<void>;
-    remove: () => Promise<void>;
-    error: Error | null;
-    isLoading: boolean;
-}
-/**
- * useIndexedDB
- *
- * A simple hook to persist data in IndexedDB.
- * Suitable for storing large objects/blobs that LocalStorage can't handle.
- */
-declare function useIndexedDB<T = any>(dbName: string, storeName: string, key: string): UseIndexedDBReturn<T>;
-
-interface UseHistoryOptions {
-    /** Maximum history size (default: 100) */
-    maxSize?: number;
-}
-interface UseHistoryReturn<T> {
-    /** Current value */
-    value: T;
-    /** Set new value (adds to history) */
-    set: (value: T | ((prev: T) => T)) => void;
-    /** Undo to previous value */
-    undo: () => void;
-    /** Redo to next value */
-    redo: () => void;
-    /** Clear history and set new value */
-    reset: (value: T) => void;
-    /** Whether undo is available */
-    canUndo: boolean;
-    /** Whether redo is available */
-    canRedo: boolean;
-    /** History array (past values) */
-    history: T[];
-    /** Current position in history */
-    position: number;
-    /** Go to specific position in history */
-    go: (position: number) => void;
-}
-/**
- * useHistory
- *
- * A hook for managing state with undo/redo functionality.
- *
- * @param initialValue - Initial state value
- * @param options - Configuration options
- * @returns Object with value, history controls, and state
- *
- * @example
- * ```tsx
- * const { value, set, undo, redo, canUndo, canRedo } = useHistory('');
- *
- * return (
- *   <div>
- *     <input value={value} onChange={(e) => set(e.target.value)} />
- *     <button onClick={undo} disabled={!canUndo}>Undo</button>
- *     <button onClick={redo} disabled={!canRedo}>Redo</button>
- *   </div>
- * );
- * ```
- */
-declare function useHistory<T>(initialValue: T, options?: UseHistoryOptions): UseHistoryReturn<T>;
-
-interface UseStepOptions {
-    /** Initial step (default: 0) */
-    initialStep?: number;
-    /** Total number of steps */
-    maxStep: number;
-}
-interface UseStepReturn {
-    /** Current step (0-indexed) */
-    currentStep: number;
-    /** Current step (1-indexed for display) */
-    step: number;
-    /** Go to next step */
-    next: () => void;
-    /** Go to previous step */
-    prev: () => void;
-    /** Go to specific step */
-    goTo: (step: number) => void;
-    /** Reset to initial step */
-    reset: () => void;
-    /** Whether at first step */
-    isFirst: boolean;
-    /** Whether at last step */
-    isLast: boolean;
-    /** Progress percentage (0-100) */
-    progress: number;
-    /** Total number of steps */
-    totalSteps: number;
-    /** Whether a specific step is completed */
-    isStepComplete: (step: number) => boolean;
-}
-/**
- * useStep
- *
- * A hook for managing wizard/stepper flow.
- *
- * @param options - Configuration options
- * @returns Object with step state and control functions
- *
- * @example
- * ```tsx
- * const steps = ['Personal Info', 'Address', 'Payment', 'Confirm'];
- *
- * const { currentStep, step, next, prev, isFirst, isLast, progress } = useStep({
- *   maxStep: steps.length,
- * });
- *
- * return (
- *   <div>
- *     <ProgressBar value={progress} />
- *     <h2>Step {step}: {steps[currentStep]}</h2>
- *     {currentStep === 0 && <PersonalInfoForm />}
- *     {currentStep === 1 && <AddressForm />}
- *     {currentStep === 2 && <PaymentForm />}
- *     {currentStep === 3 && <ConfirmForm />}
- *     <div>
- *       <button onClick={prev} disabled={isFirst}>Back</button>
- *       <button onClick={next} disabled={isLast}>Next</button>
- *     </div>
- *   </div>
- * );
- * ```
- */
-declare function useStep(options: UseStepOptions): UseStepReturn;
-
-interface UsePaginationOptions {
-    /** Total number of items */
-    totalItems: number;
-    /** Items per page (default: 10) */
-    pageSize?: number;
-    /** Initial page (1-indexed, default: 1) */
-    initialPage?: number;
-    /** Number of sibling pages to show (default: 1) */
-    siblings?: number;
-}
-interface UsePaginationReturn {
-    /** Current page (1-indexed) */
-    page: number;
-    /** Total number of pages */
-    totalPages: number;
-    /** Items per page */
-    pageSize: number;
-    /** Go to next page */
-    next: () => void;
-    /** Go to previous page */
-    prev: () => void;
-    /** Go to specific page */
-    goTo: (page: number) => void;
-    /** Go to first page */
-    first: () => void;
-    /** Go to last page */
-    last: () => void;
-    /** Whether at first page */
-    isFirst: boolean;
-    /** Whether at last page */
-    isLast: boolean;
-    /** Start index for current page (0-indexed) */
-    startIndex: number;
-    /** End index for current page (0-indexed, exclusive) */
-    endIndex: number;
-    /** Page range for pagination UI */
-    range: (number | 'dots')[];
-    /** Set page size */
-    setPageSize: (size: number) => void;
-}
-/**
- * usePagination
- *
- * A hook for managing pagination state and logic.
- *
- * @param options - Configuration options
- * @returns Object with pagination state and controls
- *
- * @example
- * ```tsx
- * const { page, totalPages, next, prev, range, isFirst, isLast } = usePagination({
- *   totalItems: 100,
- *   pageSize: 10,
- * });
- *
- * return (
- *   <div>
- *     <button onClick={prev} disabled={isFirst}>Previous</button>
- *
- *     {range.map((item, index) =>
- *       item === 'dots' ? (
- *         <span key={index}>...</span>
- *       ) : (
- *         <button
- *           key={index}
- *           onClick={() => goTo(item)}
- *           className={item === page ? 'active' : ''}
- *         >
- *           {item}
- *         </button>
- *       )
- *     )}
- *
- *     <button onClick={next} disabled={isLast}>Next</button>
- *   </div>
- * );
- * ```
- */
-declare function usePagination(options: UsePaginationOptions): UsePaginationReturn;
-
-interface MachineState<S> {
-    value: S;
-    context?: any;
-}
-interface MachineConfig<S extends string, E extends string> {
-    initial: S;
-    states: {
-        [key in S]: {
-            on?: {
-                [key in E]?: S | {
-                    target: S;
-                    action?: () => void;
-                };
-            };
-            effect?: () => (() => void) | void;
-        };
-    };
-}
-/**
- * useMachine
- *
- * A lightweight state machine hook.
- */
-declare function useMachine<S extends string, E extends string>(config: MachineConfig<S, E>): [S, (event: E) => void];
-
-interface UseVirtualListOptions {
-    /** Height of individual item */
-    itemHeight: number;
-    /** Total number of items */
-    itemCount: number;
-    /** Height of scrollable container (viewport) */
-    containerHeight: number;
-    /** Number of items to render outside viewport (buffer) */
-    overscan?: number;
-}
-interface VirtualItem {
-    index: number;
-    style: {
-        position: 'absolute';
-        top: number;
-        height: number;
-        width: '100%';
-    };
-}
-interface UseVirtualListReturn {
-    items: VirtualItem[];
-    totalHeight: number;
-    onScroll: (event: UIEvent<HTMLElement>) => void;
-}
-/**
- * useVirtualList
- *
- * A hook for efficiently rendering large lists by only rendering visible items.
- * Assumes fixed height items.
- */
-declare function useVirtualList(options: UseVirtualListOptions): UseVirtualListReturn;
-
-interface UseInfiniteScrollOptions {
-    /** Threshold for intersection (0.0 - 1.0) */
-    threshold?: number;
-    /** Root margin for intersection */
-    rootMargin?: string;
-    /** Whether loading is currently in progress */
-    isLoading?: boolean;
-    /** Whether there is more data to load */
-    hasMore?: boolean;
-    /** Disable the observer */
-    disabled?: boolean;
-}
-/**
- * useInfiniteScroll
- *
- * A hook that triggers a callback when an element (target) becomes visible.
- * Useful for infinite scrolling.
- *
- * @param onLoadMore - Function to call when target is visible
- * @param options - Configuration options
- * @returns A ref to attach to the sentinel element (bottom of list)
- */
-declare function useInfiniteScroll(onLoadMore: () => void, options?: UseInfiniteScrollOptions): MutableRefObject<HTMLDivElement | null>;
-
-interface AnthropicMessage {
-    role: 'user' | 'assistant';
-    content: string;
-}
-interface UseAnthropicOptions {
-    apiKey?: string;
-    model?: string;
-    maxTokens?: number;
-    temperature?: number;
-}
-declare function useAnthropic(options?: UseAnthropicOptions): {
-    chat: (messages: AnthropicMessage[]) => Promise<any>;
-    response: string | null;
-    loading: boolean;
-    error: any;
-};
-
-interface UseEmbeddingsReturn {
-    embeddings: number[][] | null;
-    loading: boolean;
-    error: any;
-    generate: (texts: string[]) => Promise<number[][]>;
-}
-/**
- * useEmbeddings
- *
- * Generic hook to manage embedding generation.
- * The actual provider logic is passed via the `fetcher` callback.
- */
-declare function useEmbeddings(fetcher: (texts: string[]) => Promise<number[][]>): UseEmbeddingsReturn;
-
-interface GeminiPart {
-    text: string;
-}
-interface GeminiContent {
-    role: 'user' | 'model';
-    parts: GeminiPart[];
-}
-interface UseGeminiOptions {
-    apiKey?: string;
-    model?: string;
-}
-declare function useGemini(options?: UseGeminiOptions): {
-    chat: (contents: GeminiContent[]) => Promise<any>;
-    response: string | null;
-    loading: boolean;
-    error: any;
-};
-
-interface UseLLMStreamOptions {
-    onToken?: (token: string, fullText: string) => void;
-    onComplete?: (fullText: string) => void;
-    onError?: (error: any) => void;
-}
-interface UseLLMStreamReturn {
-    stream: (url: string, fetchOptions?: RequestInit) => Promise<void>;
-    cancel: () => void;
-    data: string;
-    loading: boolean;
-    error: any;
-}
-/**
- * useLLMStream
- *
- * A hook for handling streaming responses (Server-Sent Events) from LLM APIs.
- * Simplifies the process of reading chunks and updating UI in real-time.
- *
- * @param options - Callbacks for token updates, completion, and errors
- * @returns Object with stream initiator, canceler, and current data
- *
- * @example
- * ```tsx
- * const { stream, data, loading, error } = useLLMStream({
- *   onToken: (token) => console.log('Received token:', token),
- *   onComplete: (fullText) => console.log('Stream finished:', fullText)
- * });
- *
- * const handleAsk = async (prompt: string) => {
- *   await stream('/api/chat', {
- *     method: 'POST',
- *     body: JSON.stringify({ prompt }),
- *     headers: { 'Content-Type': 'application/json' }
- *   });
- * };
- *
- * return (
- *   <div className="chat-box">
- *     <div className="response">
- *       {data || (loading ? 'Generating...' : 'Waiting for prompt...')}
- *     </div>
- *
- *     <button onClick={() => handleAsk('Write a React hook')}>
- *       Ask AI
- *     </button>
- *
- *     {error && <div className="error">{error.message}</div>}
- *   </div>
- * );
- * ```
- */
-declare function useLLMStream(options?: UseLLMStreamOptions): UseLLMStreamReturn;
-
-interface Message {
-    role: 'system' | 'user' | 'assistant';
-    content: string;
-}
-interface UseOpenAIOptions {
-    apiKey?: string;
-    apiBase?: string;
-    model?: string;
-    temperature?: number;
-    stream?: boolean;
-}
-declare function useOpenAI(options?: UseOpenAIOptions): {
-    chat: (messages: Message[]) => Promise<any>;
-    response: string | null;
-    loading: boolean;
-    error: any;
-};
-
-interface RAGDocument {
-    id: string;
-    content: string;
-    metadata?: Record<string, any>;
-}
-interface UseRAGOptions {
-    retrieve: (query: string) => Promise<RAGDocument[]>;
-    generate: (prompt: string, context: RAGDocument[]) => Promise<string>;
-}
-declare function useRAG(options: UseRAGOptions): {
-    ask: (query: string) => Promise<string>;
-    answer: string | null;
-    retrievedDocs: RAGDocument[];
-    loading: boolean;
-    error: any;
-};
-
-interface UseSearchHighlightOptions {
-    highlightTag?: string;
-    highlightClass?: string;
-    caseSensitive?: boolean;
-}
-interface HighlightPart {
-    text: string;
-    isMatch: boolean;
-}
-/**
- * useSearchHighlight
- *
- * Splits text into parts based on a search query.
- */
-declare function useSearchHighlight(text: string, query: string, options?: UseSearchHighlightOptions): HighlightPart[];
-
-type Vector = number[];
-interface SemanticResult<T> {
-    item: T;
-    score: number;
-}
-/**
- * useSemanticSearch
- *
- * Performs client-side vector similarity search (Cosine Similarity).
- * Assumes embeddings are already generated.
- */
-declare function useSemanticSearch<T>(queryEmbedding: Vector | null, items: T[], getItemEmbedding: (item: T) => Vector, topK?: number): SemanticResult<T>[];
-
-interface UseSTTOptions {
-    continuous?: boolean;
-    interimResults?: boolean;
-    lang?: string;
-    onResult?: (transcript: string) => void;
-    onError?: (error: any) => void;
-    onEnd?: () => void;
-}
-interface UseSTTReturn {
-    listen: () => void;
-    stop: () => void;
-    abort: () => void;
-    listening: boolean;
-    transcript: string;
-    supported: boolean;
-}
-/**
- * useSTT
- *
- * A hook for Speech-to-Text (Recognition) integration.
- * Provides real-time transcription with controls for continuous or one-shot listening.
- *
- * @param options - Configuration options (lang, continuous, interimResults, etc.)
- * @returns Object with recognition controls and transcription state
- *
- * @example
- * ```tsx
- * const { listen, stop, transcript, listening, supported } = useSTT({
- *   lang: 'en-US',
- *   continuous: true,
- *   interimResults: true
- * });
- *
- * if (!supported) return <p>Speech Recognition not supported in this browser</p>;
- *
- * return (
- *   <div className="stt-container">
- *     <div className="controls">
- *       <button onClick={listen} disabled={listening}>Start Listening</button>
- *       <button onClick={stop} disabled={!listening}>Stop</button>
- *     </div>
- *
- *     <div className={`status ${listening ? 'active' : ''}`}>
- *       {listening ? '🎤 Listening...' : 'Mic Off'}
- *     </div>
- *
- *     <div className="transcript">
- *       <h3>Transcript:</h3>
- *       <p>{transcript || 'Start speaking to see transcription...'}</p>
- *     </div>
- *   </div>
- * );
- * ```
- */
-declare function useSTT(options?: UseSTTOptions): UseSTTReturn;
-
-interface UseTTSOptions {
-    volume?: number;
-    rate?: number;
-    pitch?: number;
-    voiceURI?: string;
-    onStart?: () => void;
-    onEnd?: () => void;
-    onError?: (event: SpeechSynthesisErrorEvent) => void;
-}
-/**
- * useTTS
- *
- * A hook for Text-to-Speech (Synthesis) integration.
- * Wraps the Web Speech API with a React-friendly interface.
- *
- * @param options - Configuration options (volume, rate, voice, etc.)
- * @returns Object with speech controls and state
- *
- * @example
- * ```tsx
- * const { speak, cancel, speaking, supported, voices } = useTTS({
- *   volume: 1,
- *   rate: 1,
- * });
- *
- * if (!supported) return <p>Text-to-Speech not supported</p>;
- *
- * return (
- *   <div>
- *     <textarea id="text-input" defaultValue="Hello world" />
- *
- *     <div className="controls">
- *       <button onClick={() => speak(document.querySelector('textarea')?.value || '')}>
- *         Speak
- *       </button>
- *       <button onClick={cancel} disabled={!speaking}>
- *         Stop
- *       </button>
- *     </div>
- *
- *     <div className="status">
- *       {speaking ? '🔊 Speaking...' : 'Idle'}
- *     </div>
- *
- *     <div className="voices">
- *       <p>Available Voices: {voices.length}</p>
- *     </div>
- *   </div>
- * );
- * ```
- */
-declare function useTTS(options?: UseTTSOptions): {
-    speak: (text: string, overrideOptions?: UseTTSOptions) => void;
-    cancel: () => void;
-    speaking: boolean;
-    supported: boolean;
-    voices: SpeechSynthesisVoice[];
-};
-
-type AnimationCallback = (time: number, deltaTime: number) => void;
-declare function useAnimate(callback: AnimationCallback, running?: boolean): void;
-
-interface UseMediaRefReturn<T extends HTMLMediaElement> {
-    ref: React.RefObject<T>;
-    controls: {
-        play: () => Promise<void>;
-        pause: () => void;
-        toggle: () => void;
-        seek: (time: number) => void;
-        mute: () => void;
-        unmute: () => void;
-        setVolume: (val: number) => void;
-    };
-    state: {
-        playing: boolean;
-        paused: boolean;
-        muted: boolean;
-        volume: number;
-        time: number;
-        duration: number;
-        buffered: number;
-        waiting: boolean;
-        ended: boolean;
-    };
-}
-/**
- * useVideoRef
- *
- * A hook providing a declarative interface for HTML5 Video elements.
- * Returns a ref, easy-to-use controls, and real-time playback state.
- *
- * @returns Object with ref, controls (play, pause, volume), and state (time, duration, etc.)
- *
- * @example
- * ```tsx
- * const { ref, controls, state } = useVideoRef();
- *
- * return (
- *   <div className="player">
- *     <video ref={ref} src="movie.mp4" width="600" />
- *
- *     <div className="ui">
- *       <button onClick={controls.toggle}>
- *         {state.paused ? '▶️ Play' : '⏸️ Pause'}
- *       </button>
- *
- *       <input
- *         type="range"
- *         min="0"
- *         max={state.duration}
- *         value={state.time}
- *         onChange={(e) => controls.seek(Number(e.target.value))}
- *       />
- *
- *       <span>{Math.round(state.time)}s / {Math.round(state.duration)}s</span>
- *
- *       <button onClick={controls.mute}>
- *         {state.muted ? '🔈' : '🔊'}
- *       </button>
- *     </div>
- *   </div>
- * );
- * ```
- */
-declare function useVideoRef(): UseMediaRefReturn<HTMLVideoElement>;
-
-/**
- * useAudioRef
- *
- * Helper for audio elements.
- * Provides controls (play, pause, seek, volume) and state (time, duration, buffered).
- *
- * @returns Object with ref, controls, and state
- *
- * @example
- * ```tsx
- * const { ref, controls, state } = useAudioRef();
- *
- * return (
- *   <div>
- *     <audio ref={ref} src="song.mp3" />
- *     <button onClick={controls.toggle}>
- *       {state.paused ? 'Play' : 'Pause'}
- *     </button>
- *   </div>
- * );
- * ```
- */
-declare function useAudioRef(): UseMediaRefReturn<HTMLAudioElement>;
-
-interface UseCanvasOptions {
-    width?: number;
-    height?: number;
-    animate?: (context: CanvasRenderingContext2D, frameCount: number) => void;
-}
-declare function useCanvas(options?: UseCanvasOptions): react.RefObject<HTMLCanvasElement>;
-
-declare function useFrameRate(running?: boolean): number;
-
-interface UseLottieOptions extends Omit<AnimationConfig, 'container'> {
-    path?: string;
-    animationData?: any;
-    speed?: number;
-    direction?: 1 | -1;
-    isPlaying?: boolean;
-}
-declare function useLottie(containerRef: React.RefObject<HTMLElement>, options: UseLottieOptions): AnimationItem | undefined;
-
-interface UseParallaxOptions {
-    speed?: number;
-    axis?: 'y' | 'x';
-}
-/**
- * useParallax
- *
- * Returns a style object with transform to create a parallax effect.
- * Needs to be attached to the element style.
- */
-declare function useParallax(options?: UseParallaxOptions): {
-    ref: react.RefObject<HTMLElement>;
-    style: {
-        transform: string;
-        willChange: string;
-    };
-};
-
-interface SpringConfig {
-    stiffness?: number;
-    damping?: number;
-    mass?: number;
-}
-interface UseSpringCoreOptions extends SpringConfig {
-    initialValue?: number;
-}
-/**
- * useSpringCore
- *
- * A simplified spring physics implementation using a semi-implicit Euler integration
- * or basic RK4 (simplified here for performant React state updates).
- *
- * Note: For high frequency animation, use useAnimate directly with refs.
- * This hook is for state-based spring values.
- */
-declare function useSpringCore(targetValue: number, options?: UseSpringCoreOptions): number;
-
-interface UseSVGAnimationOptions {
-    duration?: number;
-    delay?: number;
-    easing?: (t: number) => number;
-}
-declare function useSVGAnimation(length: number, options?: UseSVGAnimationOptions): {
-    strokeDasharray: number;
-    strokeDashoffset: number;
-};
-
-interface UseThreeJSOptions {
-    init?: (scene: THREE.Scene, camera: THREE.PerspectiveCamera, renderer: THREE.WebGLRenderer) => void;
-    animate?: (time: number, scene: THREE.Scene, camera: THREE.PerspectiveCamera) => void;
-    resize?: boolean;
-}
-declare function useThreeJS(containerRef: React.RefObject<HTMLElement>, options?: UseThreeJSOptions): {
-    scene: THREE.Scene<THREE.Object3DEventMap> | undefined;
-    camera: THREE.PerspectiveCamera | undefined;
-    renderer: THREE.WebGLRenderer | undefined;
-};
-
-declare function useBroadcastChannel<T>(channelName: string): {
-    postMessage: (message: T) => void;
-    lastMessage: T | null;
-};
-
-interface UseCalendarOptions {
-    initialDate?: Date;
-}
-declare function useCalendar(options?: UseCalendarOptions): {
-    date: Date;
-    daysInMonth: number;
-    firstDayOfMonth: number;
-    nextMonth: () => void;
-    prevMonth: () => void;
-    setHeader: react.Dispatch<react.SetStateAction<Date>>;
-};
-
-interface UseDragAndDropOptions {
-    onDrop?: (files: File[]) => void;
-    accept?: string[];
-}
-declare function useDragAndDrop(options?: UseDragAndDropOptions): {
-    ref: react.RefObject<HTMLElement>;
-    isDragging: boolean;
-};
-
-interface UseFileProcessingOptions {
-    limit?: number;
-    accept?: string[];
-}
-declare function useFileProcessing(options?: UseFileProcessingOptions): {
-    process: (file: File) => Promise<string>;
-    processing: boolean;
-    error: string | null;
-};
-
-interface UseFormOptions<T> {
-    /** Initial values for the form fields */
-    initialValues: T;
-    /** Callback function when form is submitted successfully */
-    onSubmit: (values: T) => void | Promise<void>;
-    /** Validation function that returns an object of error messages */
-    validate?: (values: T) => Record<keyof T, string> | Promise<Record<keyof T, string>>;
-}
-interface UseFormReturn<T> {
-    /** Current form values */
-    values: T;
-    /** Current validation errors */
-    errors: Record<keyof T, string>;
-    /** Touched fields status */
-    touched: Record<keyof T, boolean>;
-    /** Whether the form is currently submitting */
-    isSubmitting: boolean;
-    /** Handle input change events */
-    handleChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
-    /** Handle input blur events */
-    handleBlur: (e: React.FocusEvent<any>) => void;
-    /** Handle form submission */
-    handleSubmit: (e?: FormEvent) => Promise<void>;
-    /** Manually set a field value */
-    setFieldValue: (name: keyof T, value: any) => void;
-    /** Manually set all form values */
-    setValues: React.Dispatch<React.SetStateAction<T>>;
-}
-/**
- * useForm
- *
- * A simple yet powerful hook for managing form state, validation, and submission.
- * It handles values, errors, touched states, and provides handlers for inputs and forms.
- *
- * @param options - Configuration options for the form
- * @returns Object with form state and handlers
- *
- * @example
- * ```tsx
- * interface LoginForm {
- *   email: string;
- *   password: string;
- * }
- *
- * const {
- *   values,
- *   errors,
- *   handleChange,
- *   handleSubmit,
- *   isSubmitting
- * } = useForm<LoginForm>({
- *   initialValues: { email: '', password: '' },
- *
- *   validate: (values) => {
- *     const errors: Partial<Record<keyof LoginForm, string>> = {};
- *     if (!values.email) errors.email = 'Email required';
- *     if (!values.password) errors.password = 'Password required';
- *     return errors as Record<keyof LoginForm, string>;
- *   },
- *
- *   onSubmit: async (values) => {
- *     console.log('Logging in...', values);
- *     await new Promise(r => setTimeout(r, 1000));
- *   }
- * });
- *
- * return (
- *   <form onSubmit={handleSubmit} className="login-form">
- *     <div className="field">
- *       <label>Email</label>
- *       <input
- *         name="email"
- *         value={values.email}
- *         onChange={handleChange}
- *         className={errors.email ? 'invalid' : ''}
- *       />
- *       {errors.email && <span className="error">{errors.email}</span>}
- *     </div>
- *
- *     <div className="field">
- *       <label>Password</label>
- *       <input
- *         name="password"
- *         type="password"
- *         value={values.password}
- *         onChange={handleChange}
- *       />
- *       {errors.password && <span className="error">{errors.password}</span>}
- *     </div>
- *
- *     <button type="submit" disabled={isSubmitting}>
- *       {isSubmitting ? 'Verifying...' : 'Login'}
- *     </button>
- *   </form>
- * );
- * ```
- */
-declare function useForm<T extends Record<string, any>>(options: UseFormOptions<T>): UseFormReturn<T>;
-
-/**
- * useMarkdown
- *
- * Simple parser or wrapper typically.
- * Here we return a simple compilation function.
- */
-declare function useMarkdown(): {
-    compile: (markdown: string) => string;
-};
-
-declare function usePDF(): {
-    generate: (content: string, filename?: string) => Promise<boolean>;
-    generating: boolean;
-};
-
-/**
- * usePresence
- *
- * Tracks basic user presence (online/idle) or remote presence list logic.
- */
-declare function usePresence(heartbeatInterval?: number): {
-    isIdle: boolean;
-    lastActive: number;
-};
-
-interface CollabEvent {
-    type: string;
-    payload: any;
-    timestamp: number;
-    userId: string;
-}
-/**
- * useRealtimeCollab
- *
- * Logic stub for Operational Transformation or CRDTs.
- * Simple event log for now.
- */
-declare function useRealtimeCollab(userId: string): {
-    events: CollabEvent[];
-    emit: (type: string, payload: any) => void;
-    applyRemote: (event: CollabEvent) => void;
-};
-
-type ShortcutHandler = (event: KeyboardEvent) => void;
-interface ShortcutMap {
-    [key: string]: ShortcutHandler;
-}
-/**
- * useShortcuts
- *
- * Defines keyboard shortcuts.
- * key combo format: 'Control+Shift+K', 'Enter', 'a'
- */
-declare function useShortcuts(shortcuts: ShortcutMap): void;
-
-interface UseSortableOptions<T> {
-    items: T[];
-    onReorder: (newItems: T[]) => void;
-}
-declare function useSortable<T>(options: UseSortableOptions<T>): {
-    draggedIndex: number | null;
-    setDraggedIndex: react.Dispatch<react.SetStateAction<number | null>>;
-    move: (fromIndex: number, toIndex: number) => void;
-};
-
-type CellValue = string | number | null;
-type GridData = CellValue[][];
-interface UseSpreadsheetOptions {
-    rows: number;
-    cols: number;
-    initialData?: GridData;
-}
-declare function useSpreadsheet(options: UseSpreadsheetOptions): {
-    data: GridData;
-    setCell: (r: number, c: number, value: CellValue) => void;
-    selectedCell: {
-        r: number;
-        c: number;
-    } | null;
-    setSelectedCell: react.Dispatch<react.SetStateAction<{
-        r: number;
-        c: number;
-    } | null>>;
-};
-
-type SortDirection = 'asc' | 'desc';
-interface Column<T> {
-    /** Property key of the data item */
-    key: keyof T;
-    /** Header label for the column */
-    label: string;
-    /** Whether the column is sortable */
-    sortable?: boolean;
-}
-interface UseTableOptions<T> {
-    /** Array of data items to display */
-    data: T[];
-    /** Array of column definitions */
-    columns: Column<T>[];
-    /** Initial sorting configuration */
-    initialSort?: {
-        key: keyof T;
-        direction: SortDirection;
-    };
-}
-interface UseTableReturn<T> {
-    /** Sorted and filtered items */
-    items: T[];
-    /** Function to request sorting by a key */
-    requestSort: (key: keyof T) => void;
-    /** Current sort configuration */
-    sortConfig: {
-        key: keyof T;
-        direction: SortDirection;
-    } | null;
-    /** Column definitions (passed through) */
-    columns: Column<T>[];
-}
-/**
- * useTable
- *
- * A headless hook for managing table state, including sorting and column definitions.
- *
- * @param options - Table configuration options
- * @returns Object with sorted items and sort controls
- *
- * @example
- * ```tsx
- * interface User { id: number; name: string; age: number; email: string; }
- *
- * const data: User[] = [
- *   { id: 1, name: 'Alice', age: 28, email: 'alice@example.com' },
- *   { id: 2, name: 'Bob', age: 34, email: 'bob@example.com' },
- * ];
- *
- * const columns: Column<User>[] = [
- *   { key: 'name', label: 'Full Name', sortable: true },
- *   { key: 'age', label: 'Age', sortable: true },
- *   { key: 'email', label: 'Email' },
- * ];
- *
- * export function DataTable() {
- *   const { items, requestSort, sortConfig, columns: cols } = useTable({ data, columns });
- *
- *   return (
- *     <table className="data-table">
- *       <thead>
- *         <tr>
- *           {cols.map(col => (
- *             <th
- *               key={col.key.toString()}
- *               onClick={() => col.sortable && requestSort(col.key)}
- *               className={col.sortable ? 'sortable' : ''}
- *             >
- *               {col.label}
- *               {sortConfig?.key === col.key && (
- *                 <span>{sortConfig.direction === 'asc' ? ' ↑' : ' ↓'}</span>
- *               )}
- *             </th>
- *           ))}
- *         </tr>
- *       </thead>
- *       <tbody>
- *         {items.map(user => (
- *           <tr key={user.id}>
- *             <td>{user.name}</td>
- *             <td>{user.age}</td>
- *             <td>{user.email}</td>
- *           </tr>
- *         ))}
- *       </tbody>
- *     </table>
- *   );
- * }
- * ```
- */
-declare function useTable<T>(options: UseTableOptions<T>): UseTableReturn<T>;
-
-interface UseWebRTCOptions {
-    iceServers?: RTCIceServer[];
-}
-/**
- * useWebRTC
- *
- * Basic wrapper for RTCPeerConnection.
- */
-declare function useWebRTC(options?: UseWebRTCOptions): {
-    pc: RTCPeerConnection | null;
-    connectionState: RTCPeerConnectionState;
-    signalingState: RTCSignalingState;
-};
-
-interface UseWebSocketOptions {
-    onOpen?: (event: Event) => void;
-    onClose?: (event: CloseEvent) => void;
-    onMessage?: (event: MessageEvent) => void;
-    onError?: (event: Event) => void;
-    reconnect?: boolean;
-    reconnectAttempts?: number;
-    reconnectInterval?: number;
-}
-declare function useWebSocket(url: string, options?: UseWebSocketOptions): {
-    send: (data: string | ArrayBuffer | Blob | ArrayBufferView) => void;
-    lastMessage: MessageEvent<any> | null;
-    isConnected: boolean;
-    ws: WebSocket | null;
-};
-
-declare function useClickAnywhere(handler: (event: MouseEvent) => void): void;
-
-interface UseCountdownOptions {
-    countStart: number;
-    intervalMs?: number;
-    isIncrement?: boolean;
-    countStop?: number;
-}
-interface UseCountdownReturn {
-    count: number;
-    startCountdown: () => void;
-    stopCountdown: () => void;
-    resetCountdown: () => void;
-}
-declare function useCountdown({ countStart, intervalMs, isIncrement, countStop, }: UseCountdownOptions): UseCountdownReturn;
-
-interface DebounceOptions {
-    leading?: boolean;
-    trailing?: boolean;
-    maxWait?: number;
-}
-interface ControlFunctions {
-    cancel: () => void;
-    flush: () => void;
-}
-declare function useDebounceCallback<T extends (...args: any[]) => any>(func: T, wait?: number, options?: DebounceOptions): ((...args: Parameters<T>) => void) & ControlFunctions;
-
-declare function useIsClient(): boolean;
-
-interface UseListActions<T> {
-    set: (list: T[]) => void;
-    push: (element: T) => void;
-    updateAt: (index: number, element: T) => void;
-    insertAt: (index: number, element: T) => void;
-    update: (predicate: (a: T, b: T) => boolean, newElement: T) => void;
-    removeAt: (index: number) => void;
-    clear: () => void;
-    reset: () => void;
-}
-type UseListReturn<T> = [T[], UseListActions<T>];
-declare function useList<T>(initialList?: T[]): UseListReturn<T>;
-
-type MapOrEntries<K, V> = Map<K, V> | [K, V][];
-interface UseMapActions<K, V> {
-    set: (key: K, value: V) => void;
-    setAll: (entries: MapOrEntries<K, V>) => void;
-    remove: (key: K) => void;
-    reset: () => void;
-}
-type UseMapReturn<K, V> = [Map<K, V>, UseMapActions<K, V>];
-/**
- * useMap
- *
- * A specific hook for managing `Map` state in React.
- * Simplifies adding, removing, and updating Map entries while ensuring immutability.
- *
- * @param initialState - Initial Map entries
- * @returns [map, actions]
- *
- * @example
- * ```tsx
- * const initialData = [['key1', 'value1'], ['key2', 'value2']] as const;
- * const [map, mapActions] = useMap<string, string>(initialData);
- *
- * return (
- *   <div>
- *     <h3>Map Size: {map.size}</h3>
- *
- *     <button onClick={() => mapActions.set('newKey', 'newValue')}>
- *       Add/Update Key
- *     </button>
- *     <button onClick={() => mapActions.setAll([['fresh', 'start']])}>
- *       Replace All
- *     </button>
- *     <button onClick={() => mapActions.reset()}>
- *       Reset to Initial
- *     </button>
- *
- *     <ul>
- *       {Array.from(map.entries()).map(([key, value]) => (
- *         <li key={key}>
- *           <strong>{key}:</strong> {value}
- *           <button onClick={() => mapActions.remove(key)}>X</button>
- *         </li>
- *       ))}
- *     </ul>
- *   </div>
- * );
- * ```
- */
-declare function useMap<K, V>(initialState?: MapOrEntries<K, V>): UseMapReturn<K, V>;
-
-interface UseQueueActions<T> {
-    add: (element: T) => void;
-    remove: () => T | undefined;
-    clear: () => void;
-}
-type UseQueueReturn<T> = {
-    queue: T[];
-    first: T;
-    last: T;
-    size: number;
-} & UseQueueActions<T>;
-/**
- * useQueue
- *
- * A hook for managing a queue data structure (FIFO - First In First Out).
- *
- * @param initialValue - Initial elements in the queue
- * @returns Object with queue state and operations
- *
- * @example
- * ```tsx
- * const {
- *   add,
- *   remove,
- *   clear,
- *   first,
- *   last,
- *   size,
- *   queue
- * } = useQueue<string>(['Task 1']);
- *
- * return (
- *   <div>
- *     <h2>Task Queue ({size})</h2>
- *
- *     <div className="controls">
- *       <button onClick={() => add(`Task ${Date.now()}`)}>Add Task</button>
- *       <button onClick={() => remove()} disabled={size === 0}>Process Next</button>
- *       <button onClick={clear}>Clear All</button>
- *     </div>
- *
- *     <div className="status">
- *       <p>Next: {first || 'None'}</p>
- *       <p>Newest: {last || 'None'}</p>
- *     </div>
- *
- *     <ul>
- *       {queue.map((task, index) => (
- *         <li key={index}>{task}</li>
- *       ))}
- *     </ul>
- *   </div>
- * );
- * ```
- */
-/**
- * useQueue
- *
- * A hook for managing a queue data structure (FIFO - First In First Out).
- *
- * @param initialValue - Initial elements in the queue
- * @returns Object with queue state and operations
- *
- * @example
- * ```tsx
- * const {
- *   add,
- *   remove,
- *   clear,
- *   first,
- *   last,
- *   size,
- *   queue
- * } = useQueue<string>(['Task 1']);
- *
- * return (
- *   <div>
- *     <h2>Task Queue ({size})</h2>
- *
- *     <div className="controls">
- *       <button onClick={() => add(`Task ${Date.now()}`)}>Add Task</button>
- *       <button onClick={() => remove()} disabled={size === 0}>Process Next</button>
- *       <button onClick={clear}>Clear All</button>
- *     </div>
- *
- *     <div className="status">
- *       <p>Next: {first || 'None'}</p>
- *       <p>Newest: {last || 'None'}</p>
- *     </div>
- *
- *     <ul>
- *       {queue.map((task, index) => (
- *         <li key={index}>{task}</li>
- *       ))}
- *     </ul>
- *   </div>
- * );
- * ```
- */
-declare function useQueue<T>(initialValue?: T[]): UseQueueReturn<T>;
-
-declare function useScreen(): Screen | undefined;
-
-interface UseSetActions<K> {
-    add: (key: K) => void;
-    remove: (key: K) => void;
-    toggle: (key: K) => void;
-    reset: () => void;
-    clear: () => void;
-}
-type UseSetReturn<K> = [Set<K>, UseSetActions<K>];
-/**
- * useSet
- *
- * A specific hook for managing `Set` state in React.
- * Useful for tracking selections, tags, or active filters.
- *
- * @param initialSet - Initial Set entries
- * @returns [set, actions]
- *
- * @example
- * ```tsx
- * const availableTags = ['React', 'Vue', 'Angular', 'Svelte'];
- * const [selectedTags, { toggle, has, clear }] = useSet<string>(new Set(['React']));
- *
- * return (
- *   <div>
- *     <h2>Select Frameworks ({selectedTags.size})</h2>
- *
- *     <div className="tags">
- *       {availableTags.map(tag => (
- *         <button
- *           key={tag}
- *           onClick={() => toggle(tag)}
- *           className={selectedTags.has(tag) ? 'active' : ''}
- *         >
- *           {tag} {selectedTags.has(tag) ? '✓' : ''}
- *         </button>
- *       ))}
- *     </div>
- *
- *     <button onClick={clear}>Clear Selection</button>
- *
- *     <pre>
- *       Selection: {JSON.stringify(Array.from(selectedTags))}
- *     </pre>
- *   </div>
- * );
- * ```
- */
-declare function useSet<K>(initialSet?: Set<K>): UseSetReturn<K>;
-
-/**
- * Check if code is running on the server (SSR)
- */
-declare const isServer: boolean;
-/**
- * Check if code is running in the browser
- */
-declare const isBrowser: boolean;
-/**
- * No-operation function
- */
-declare const noop: () => void;
-
-export { type AnimationCallback, type AnthropicMessage, type AnyEvent, type AsyncStatus, type BatteryState, type CellValue, type CollabEvent, type Column, type EyeDropperOpenOptions, type FetchStatus, type GeminiContent, type GeminiPart, type GridData, type HighlightPart, type MachineConfig, type MachineState, type Message, type NetworkState, type PermissionName, type PermissionState, type RAGDocument, type RecorderStatus, type ScriptStatus, type ScrollPosition, type SemanticResult, type ShareData, type ShortcutHandler, type ShortcutMap, type SortDirection, type SpringConfig, type StorageEstimateState, type Theme, type UseAnthropicOptions, type UseAsyncOptions, type UseAsyncReturn, type UseBluetoothReturn, type UseCalendarOptions, type UseCanvasOptions, type UseClickOutsideOptions, type UseCopyToClipboardReturn, type UseCountdownOptions, type UseCountdownReturn, type UseCounterOptions, type UseCounterReturn, type UseDebounceOptions, type UseDebounceReturn, type UseDocumentTitleOptions, type UseDragAndDropOptions, type UseEmbeddingsReturn, type UseEventOptions, type UseEyeDropperReturn, type UseFetchOptions, type UseFetchReturn, type UseFileProcessingOptions, type UseFileSystemReturn, type UseFormOptions, type UseFormReturn, type UseFullscreenReturn, type UseGamepadOptions, type UseGeminiOptions, type UseHistoryOptions, type UseHistoryReturn, type UseHoverReturn, type UseIndexedDBReturn, type UseInfiniteScrollOptions, type UseIntersectionOptions, type UseIntersectionReturn, type UseIntervalOptions, type UseIntervalReturn, type UseKeyPressOptions, type UseLLMStreamOptions, type UseLLMStreamReturn, type UseListActions, type UseListReturn, type UseLocalStorageOptions, type UseLocalStorageReturn, type UseLongPressOptions, type UseLongPressReturn, type UseLottieOptions, type UseMapActions, type UseMapReturn, type UseMediaQueryOptions, type UseMediaRecorderReturn, type UseMediaRefReturn, type UseMutationObserverOptions, type UseOnlineReturn, type UseOpenAIOptions, type UsePaginationOptions, type UsePaginationReturn, type UseParallaxOptions, type UseQueueActions, type UseQueueReturn, type UseRAGOptions, type UseResizeObserverOptions, type UseSTTOptions, type UseSTTReturn, type UseSVGAnimationOptions, type UseScriptOptions, type UseScriptReturn, type UseScrollOptions, type UseScrollReturn, type UseSearchHighlightOptions, type UseSessionStorageOptions, type UseSetActions, type UseSetReturn, type UseShareReturn, type UseSortableOptions, type UseSpreadsheetOptions, type UseSpringCoreOptions, type UseStepOptions, type UseStepReturn, type UseTTSOptions, type UseTableOptions, type UseTableReturn, type UseThemeOptions, type UseThemeReturn, type UseThreeJSOptions, type UseThrottleOptions, type UseThrottleReturn, type UseTimeoutOptions, type UseTimeoutReturn, type UseToggleOptions, type UseToggleReturn, type UseVirtualListOptions, type UseVirtualListReturn, type UseWakeLockReturn, type UseWebRTCOptions, type UseWebSocketOptions, type UseWindowSizeOptions, type UseWorkerReturn, type Vector, type VirtualItem, type WindowSize, type WorkerStatus, isBrowser, isServer, noop, useAnimate, useAnthropic, useAsync, useAudioRef, useBattery, useBluetooth, useBroadcastChannel, useCalendar, useCanvas, useClickAnywhere, useClickOutside, useCopyToClipboard, useCountdown, useCounter, useDebounce, useDebounceCallback, useDocumentTitle, useDragAndDrop, useEmbeddings, useEvent, useEyeDropper, useFetch, useFileProcessing, useFileSystem, useForm, useFrameRate, useFullscreen, useGamepad, useGemini, useHistory, useHover, useIndexedDB, useInfiniteScroll, useIntersection, useInterval, useIsClient, useIsMounted, useIsomorphicLayoutEffect, useKeyPress, useLLMStream, useList, useLocalStorage, useLockBodyScroll, useLongPress, useLottie, useMachine, useMap, useMarkdown, useMediaDevices, useMediaQuery, useMediaRecorder, useMount, useMutationObserver, useNetworkState, useOnline, useOpenAI, usePDF, usePageLeave, usePagination, useParallax, usePermissions, usePresence, usePrevious, useQueue, useRAG, useRealtimeCollab, useResizeObserver, useSTT, useSVGAnimation, useScreen, useScript, useScroll, useSearchHighlight, useSemanticSearch, useSessionStorage, useSet, useShare, useShortcuts, useSortable, useSpreadsheet, useSpringCore, useStableCallback, useStep, useStorageEstimate, useTTS, useTable, useTheme, useThreeJS, useThrottle, useTimeout, useToggle, useUnmount, useUpdateEffect, useVideoRef, useVirtualList, useWakeLock, useWebRTC, useWebSocket, useWindowFocus, useWindowSize, useWorker };