/**
 * Optional URL routing integration for `<AuthFlow/>`.
 *
 * The SDK stays router-agnostic: consumers construct an `AuthFlowRouter`
 * adapter from their app's router (Next.js, React Router, TanStack, etc.)
 * and a `routes` map of which auth step maps to which URL path.
 *
 * Steps omitted from the map render in place without changing the URL
 * (e.g. `CHECKING_SESSION`, `PROVIDER_PENDING`, `AUTHENTICATED`).
 */
import type { AuthStep } from './auth-types';
/**
 * URL path for a given auth step. Consumers control the path strings;
 * the SDK only matches via string equality (returned by `getPath`).
 */
export type AuthFlowRoutes = Partial<Record<AuthStep, string>>;
/**
 * Router adapter the SDK uses to read and update the URL. Built by the
 * consumer from their framework's primitives.
 *
 * @example Next.js (App Router)
 * ```tsx
 * import { usePathname, useRouter } from 'next/navigation';
 *
 * function useAuthRouter(): AuthFlowRouter {
 *   const router = useRouter();
 *   const pathname = usePathname();
 *   const pathRef = useRef(pathname);
 *   pathRef.current = pathname;
 *   const listenersRef = useRef(new Set<(p: string) => void>());
 *
 *   useEffect(() => {
 *     for (const cb of listenersRef.current) cb(pathname);
 *   }, [pathname]);
 *
 *   return {
 *     push:    (p) => router.push(p),
 *     replace: (p) => router.replace(p),
 *     getPath: () => pathRef.current,
 *     subscribe: (cb) => {
 *       listenersRef.current.add(cb);
 *       return () => listenersRef.current.delete(cb);
 *     },
 *   };
 * }
 * ```
 */
export interface AuthFlowRouter {
    /** Navigate to `path`, adding a history entry. */
    push: (path: string) => void;
    /** Navigate to `path`, replacing the current history entry. */
    replace: (path: string) => void;
    /** Return the current URL path (pathname only — no query / hash). */
    getPath: () => string;
    /**
     * Subscribe to path changes (back/forward, programmatic push/replace).
     * Returns an unsubscribe function.
     */
    subscribe: (callback: (path: string) => void) => () => void;
}
