/**
 * Timer operating mode.
 *
 * - `countdown` — decreases time until it reaches `targetTimeMs`
 * - `countup` — increases time until it reaches `targetTimeMs` (if provided)
 */
type UseHoneyTimerMode = 'countdown' | 'countup';
type UseHoneyTimerOnEndHandler = () => void;
export interface UseHoneyTimerOptions {
    /**
     * Initial timer value in milliseconds.
     *
     * - Countdown: starting time
     * - Count-up: initial offset
     */
    initialTimeMs: number;
    /**
     * Target time in milliseconds.
     *
     * - Countdown: usually `0`
     * - Count-up: optional upper limit
     *
     * When reached, the timer stops and `onEnd` is invoked.
     *
     * @default 0
     */
    targetTimeMs?: number;
    /**
     * Direction in which the timer progresses.
     *
     * @default 'countdown'
     */
    mode?: UseHoneyTimerMode;
    /**
     * Whether the timer should automatically start on mount.
     *
     * @default false
     */
    autoStart?: boolean;
    /**
     * Optional callback invoked exactly once when the timer reaches the target time.
     */
    onEnd?: UseHoneyTimerOnEndHandler;
}
/**
 * Public control API returned by {@link useHoneyTimer}.
 */
export interface UseHoneyTimerApi {
    /**
     * Current timer value in milliseconds.
     *
     * This value updates over time while the timer is running.
     */
    timeMs: number;
    /**
     * Indicates whether the timer is currently progressing.
     */
    isRunning: boolean;
    /**
     * Starts the timer from `initialTimeMs`, resetting any previous state.
     */
    start: () => void;
    /**
     * Pauses the timer while preserving the current time value.
     */
    pause: () => void;
    /**
     * Resumes the timer from its current time value.
     *
     * Has no effect if the timer is already running.
     */
    resume: () => void;
    /**
     * Resets the timer to a specific time value.
     *
     * @param timeMs - Optional new timer value. Defaults to `initialTimeMs`.
     */
    reset: (timeMs?: number) => void;
}
/**
 * A high-precision timer hook built on top of {@link useHoneyRafLoop}.
 *
 * Features:
 * - Frame-accurate time progression using `requestAnimationFrame`
 * - Supports countdown and count-up modes
 * - Explicit lifecycle control (start / pause / resume / reset)
 * - Drift-free timing using delta-based updates
 * - Safe completion handling via `onEnd`
 *
 * Architectural notes:
 * - Time progression is handled imperatively via refs to avoid stale closures and unnecessary re-renders.
 * - React state is updated only with the derived timer value.
 * - RAF lifecycle is fully delegated to `useHoneyRafLoop`.
 *
 * @example
 * ```ts
 * const timer = useHoneyTimer({
 *   initialTimeMs: 10_000,
 *   targetTimeMs: 0,
 *   onEnd: () => console.log('Done'),
 * });
 *
 * timer.startTimer();
 * ```
 */
export declare const useHoneyTimer: ({ initialTimeMs, targetTimeMs, mode, autoStart, onEnd, }: UseHoneyTimerOptions) => UseHoneyTimerApi;
export {};