tempest-react-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2327 @@
+import { ButtonHTMLAttributes } from 'react';
+import { Component } from 'react';
+import { ComponentType } from 'react';
+import { CSSProperties } from 'react';
+import { default as default_2 } from 'dexie';
+import { DefaultOptions } from '@tanstack/react-query';
+import { ErrorInfo } from 'react';
+import { FieldValues } from 'react-hook-form';
+import { ForwardRefExoticComponent } from 'react';
+import { HTMLAttributes } from 'react';
+import { InputHTMLAttributes } from 'react';
+import { JSX } from 'react/jsx-runtime';
+import { lazy } from 'react';
+import { PersistOptions } from 'zustand/middleware';
+import { QueryClient } from '@tanstack/react-query';
+import { ReactElement } from 'react';
+import { ReactNode } from 'react';
+import { ReactPortal } from 'react';
+import { RefAttributes } from 'react';
+import { RefObject } from 'react';
+import { SelectHTMLAttributes } from 'react';
+import { StoreApi } from 'zustand';
+import { Table as Table_2 } from 'dexie';
+import { TextareaHTMLAttributes } from 'react';
+import { UseBoundStore } from 'zustand';
+import { UseFormProps } from 'react-hook-form';
+import { UseFormReturn } from 'react-hook-form';
+import { z } from 'zod';
+
+export declare interface ApiClient {
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, options?: RequestOptions): Promise<T>;
+    put<T>(path: string, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, options?: RequestOptions): Promise<T>;
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    upload<T>(path: string, formData: FormData, method?: "POST" | "PUT" | "PATCH"): Promise<T>;
+}
+
+export declare interface ApiClientConfig {
+    /** Base URL for every request. Required. */
+    baseURL: string;
+    /** Returns the current bearer token (or null/undefined). Called per request. */
+    getToken?: () => string | null | undefined;
+    /** Called on 401 responses. Use it to logout the user or trigger a refresh. */
+    onUnauthorized?: (response: Response) => void | Promise<void>;
+    /**
+     * Optional refresh hook. When provided and the original request returns 401,
+     * the client awaits `refresh()` then retries the request once.
+     */
+    refresh?: () => Promise<void>;
+    /** Whether to send cookies on cross-origin requests (default: false). */
+    withCredentials?: boolean;
+    /** Default headers merged into every request. */
+    headers?: Record<string, string>;
+    /** Optional fetch implementation (defaults to globalThis.fetch). */
+    fetcher?: typeof fetch;
+}
+
+export declare interface ApiError {
+    status: number;
+    detail: string;
+    body?: unknown;
+}
+
+export declare interface AudioPlayer {
+    /** Play `src`. Returns the underlying element, or `null` when the browser blocked autoplay. */
+    play: (src: string, options?: PlayAudioOptions) => Promise<HTMLAudioElement | null>;
+    /** Stop the currently-playing clip and rewind it. */
+    stop: () => void;
+    /** Currently playing audio element, or `null`. */
+    current: () => HTMLAudioElement | null;
+}
+
+/**
+ * Router-agnostic auth gate. The caller decides what to render in either
+ * branch — typically `<Outlet />` for protected layouts and `<Navigate />` for
+ * the redirect. Pair with {@link createAuthStore} or any custom auth source.
+ *
+ * @example
+ * <AuthGuard
+ *     isAuthenticated={useAuthStore((s) => s.isAuthenticated)}
+ *     fallback={<Navigate to="/login" replace />}
+ * >
+ *     <Outlet />
+ * </AuthGuard>
+ */
+export declare function AuthGuard({ isAuthenticated, children, fallback }: AuthGuardProps): JSX.Element;
+
+export declare interface AuthGuardProps {
+    /** Whether the current user is authenticated. */
+    isAuthenticated: boolean;
+    /** Element to render when authenticated. */
+    children: ReactNode;
+    /** Element to render when not authenticated. Use this to redirect (e.g. `<Navigate to="/login" />`). */
+    fallback: ReactNode;
+}
+
+export declare interface AuthState<TUser> {
+    user: TUser | null;
+    token: string | null;
+    isAuthenticated: boolean;
+    setSession: (session: {
+        user: TUser;
+        token: string;
+    }) => void;
+    setUser: (user: TUser | null) => void;
+    setToken: (token: string | null) => void;
+    logout: () => void;
+}
+
+/**
+ * Round avatar. Falls back to colored initials when the image fails to load
+ * or no `src` is provided. Optional status dot in the bottom-right corner.
+ */
+export declare function Avatar({ src, alt, name, size, status, className, onClick, }: AvatarProps): JSX.Element;
+
+export declare interface AvatarProps {
+    src?: string;
+    alt?: string;
+    name?: string;
+    size?: AvatarSize;
+    status?: AvatarStatus;
+    className?: string;
+    onClick?: () => void;
+}
+
+export declare type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
+
+export declare type AvatarStatus = "online" | "offline" | "busy";
+
+/** Pill-shaped status badge with semantic color variants. */
+export declare function Badge({ variant, className, children, ...props }: BadgeProps): JSX.Element;
+
+export declare interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
+    variant?: BadgeVariant;
+}
+
+export declare type BadgeVariant = "neutral" | "success" | "warning" | "danger" | "info";
+
+export declare interface BreadcrumbItem {
+    label: ReactNode;
+    href?: string;
+    onClick?: () => void;
+}
+
+/**
+ * Hierarchical navigation breadcrumbs. The last item is rendered as plain
+ * text with `aria-current="page"`. Items with neither `href` nor `onClick`
+ * also render as text (intermediate but non-clickable).
+ */
+export declare function Breadcrumbs({ items, separator, className }: BreadcrumbsProps): JSX.Element;
+
+export declare interface BreadcrumbsProps {
+    items: BreadcrumbItem[];
+    separator?: ReactNode;
+    className?: string;
+}
+
+/**
+ * Primary action button with variants, sizes and a loading state that
+ * preserves layout via an absolutely-positioned spinner.
+ */
+export declare function Button({ variant, size, loading, fullWidth, leftIcon, rightIcon, disabled, className, children, ...props }: ButtonProps): JSX.Element;
+
+export declare interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    loading?: boolean;
+    fullWidth?: boolean;
+    leftIcon?: ReactNode;
+    rightIcon?: ReactNode;
+}
+
+export declare type ButtonSize = "sm" | "md" | "lg";
+
+export declare type ButtonVariant = "primary" | "secondary" | "danger" | "ghost";
+
+/** Recommended `gcTime` presets (milliseconds). */
+export declare const CACHE_TIME: {
+    readonly SHORT: number;
+    readonly DEFAULT: number;
+    readonly LONG: number;
+};
+
+/**
+ * Card container with optional header (title + actions). Use `flush` when you
+ * need to host content (tables, lists) that should not have inner padding.
+ */
+export declare function Card({ title, actions, flush, className, children, ...props }: CardProps): JSX.Element;
+
+export declare interface CardProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    title?: ReactNode;
+    actions?: ReactNode;
+    flush?: boolean;
+}
+
+export declare type Catalog = Record<string, Messages>;
+
+export declare const CEPInput: ForwardRefExoticComponent<Omit<InputProps, "onChange" | "value"> & {
+value: string;
+onChange: (value: string) => void;
+} & RefAttributes<HTMLInputElement>>;
+
+/**
+ * Accessible checkbox. Supports a tri-state via `indeterminate` and pairs the
+ * input with a label/description column for forms.
+ */
+export declare const Checkbox: ForwardRefExoticComponent<CheckboxProps & RefAttributes<HTMLInputElement>>;
+
+export declare interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type"> {
+    label?: ReactNode;
+    description?: ReactNode;
+    /** Render the box in the indeterminate state regardless of `checked`. */
+    indeterminate?: boolean;
+    wrapperClassName?: string;
+}
+
+/**
+ * Multi-value input. Type a value and press Enter (or comma / Tab) to push a
+ * chip. Backspace on empty input removes the last chip.
+ */
+export declare function ChipInput({ value, onChange, label, placeholder, helperText, error, commitKeys, normalize, className, }: ChipInputProps): JSX.Element;
+
+export declare interface ChipInputProps {
+    value: string[];
+    onChange: (next: string[]) => void;
+    label?: string;
+    placeholder?: string;
+    helperText?: string;
+    error?: string;
+    /** Keys that commit the current draft as a chip. Default: Enter, comma, Tab. */
+    commitKeys?: string[];
+    /** Lowercase + trim each chip + dedupe. Default: true. */
+    normalize?: boolean;
+    className?: string;
+}
+
+declare type ClassValue = string | number | bigint | boolean | null | undefined | ClassValue[];
+
+/**
+ * Tiny classnames helper. Accepts strings, falsy values and nested arrays.
+ *
+ * @param values - Class entries, conditionally truthy.
+ * @returns A single space-joined class string.
+ */
+export declare function cn(...values: ClassValue[]): string;
+
+export declare const CNPJInput: ForwardRefExoticComponent<Omit<InputProps, "onChange" | "value"> & {
+value: string;
+onChange: (value: string) => void;
+} & RefAttributes<HTMLInputElement>>;
+
+/**
+ * Quick confirmation prompt built on top of {@link Modal}. Use for destructive
+ * actions with `variant="danger"`.
+ */
+export declare function ConfirmDialog({ open, title, description, confirmLabel, cancelLabel, variant, loading, onConfirm, onCancel, }: ConfirmDialogProps): JSX.Element;
+
+export declare interface ConfirmDialogProps {
+    open: boolean;
+    title: ReactNode;
+    description?: ReactNode;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    variant?: "primary" | "danger";
+    loading?: boolean;
+    onConfirm: () => void | Promise<void>;
+    onCancel: () => void;
+}
+
+/** Default sink that writes to the browser console. */
+export declare const consoleSink: LoggerSink;
+
+/**
+ * Dev-friendly adapter that logs every call to `console`. Use as a default
+ * before plugging the real provider (Sentry / Datadog / PostHog).
+ */
+export declare const consoleTelemetryAdapter: TelemetryAdapter;
+
+/** Page-level horizontal container with a max-width preset and side padding. */
+export declare function Container({ size, className, children, ...props }: ContainerProps): JSX.Element;
+
+export declare interface ContainerProps extends HTMLAttributes<HTMLDivElement> {
+    size?: ContainerSize;
+}
+
+export declare type ContainerSize = "sm" | "md" | "lg" | "xl" | "full";
+
+export declare const CPFInput: ForwardRefExoticComponent<Omit<InputProps, "onChange" | "value"> & {
+value: string;
+onChange: (value: string) => void;
+} & RefAttributes<HTMLInputElement>>;
+
+/**
+ * Create a typed HTTP client backed by `fetch`.
+ *
+ * Handles JSON serialization, query params, bearer auth via `getToken`,
+ * automatic refresh + retry on 401 when `refresh` is supplied, and uploads
+ * via `FormData`. Throws an `ApiError` on non-2xx responses.
+ */
+export declare function createApiClient(config: ApiClientConfig): ApiClient;
+
+/**
+ * Create an isolated audio player that tracks a single "current" clip.
+ * Multiple players coexist independently; use this when several layers of UI
+ * need their own playback state.
+ */
+export declare function createAudioPlayer(): AudioPlayer;
+
+/**
+ * Build a typed Zustand auth store with `persist` middleware. Each app passes
+ * its own `TUser` shape so the SDK does not own the user model.
+ *
+ * @example
+ * const useAuthStore = createAuthStore<UserResponse>();
+ * const { user, token, logout } = useAuthStore();
+ */
+export declare function createAuthStore<TUser>(options?: CreateAuthStoreOptions<TUser>): UseBoundStore<Omit<StoreApi<AuthState<TUser>>, "setState" | "persist"> & {
+setState(partial: AuthState<TUser> | Partial<AuthState<TUser>> | ((state: AuthState<TUser>) => AuthState<TUser> | Partial<AuthState<TUser>>), replace?: false | undefined): unknown;
+setState(state: AuthState<TUser> | ((state: AuthState<TUser>) => AuthState<TUser>), replace: true): unknown;
+persist: {
+setOptions: (options: Partial<PersistOptions<AuthState<TUser>, unknown, unknown>>) => void;
+clearStorage: () => void;
+rehydrate: () => Promise<void> | void;
+hasHydrated: () => boolean;
+onHydrate: (fn: (state: AuthState<TUser>) => void) => () => void;
+onFinishHydration: (fn: (state: AuthState<TUser>) => void) => () => void;
+getOptions: () => Partial<PersistOptions<AuthState<TUser>, unknown, unknown>>;
+};
+}>;
+
+export declare interface CreateAuthStoreOptions<TUser> {
+    /** Persist key used in storage (default: "tempest-auth"). */
+    name?: string;
+    /** Which storage to persist into (default: localStorage). */
+    storage?: "local" | "session";
+    /** Initial user (useful for SSR hydration). */
+    initialUser?: TUser | null;
+    /** Initial token. */
+    initialToken?: string | null;
+}
+
+/**
+ * Open a Server-Sent Events stream with automatic exponential-backoff reconnect.
+ *
+ * Heartbeat events (default `"ping"`) keep the socket alive without firing
+ * `onMessage`. Pass `withCredentials: true` when the backend authenticates via
+ * cookies. Call `close()` from the returned controller to tear down.
+ *
+ * @param url - Full SSE endpoint URL.
+ * @param options - Stream configuration and callbacks.
+ * @returns A controller exposing `close`, `reconnect` and the current `status`.
+ */
+export declare function createEventStream<T = unknown>(url: string, options?: CreateEventStreamOptions<T>): EventStreamController;
+
+export declare interface CreateEventStreamOptions<T> {
+    /** Send cookies with the EventSource handshake. Default: false. */
+    withCredentials?: boolean;
+    /** Subscribe to named events in addition to `message`. */
+    namedEvents?: readonly string[];
+    /** Treat these named events as heartbeat-only (no callback). Default: `["ping"]`. */
+    heartbeatEvents?: readonly string[];
+    /** Max reconnect attempts. Default: 10. Pass 0 to disable reconnect. */
+    maxRetries?: number;
+    /** Initial backoff in ms; doubles per attempt, capped at `maxBackoff`. Default: 1000. */
+    initialBackoff?: number;
+    /** Maximum backoff in ms. Default: 30000. */
+    maxBackoff?: number;
+    /** Parse `event.data`. Defaults to JSON with raw-string fallback. */
+    parser?: (raw: string) => T;
+    onOpen?: () => void;
+    onMessage?: (message: EventStreamMessage<T>) => void;
+    onError?: (error: Event) => void;
+    onStatusChange?: (status: EventStreamStatus) => void;
+}
+
+/**
+ * Create an i18n object with translation, pluralization and Intl helpers.
+ *
+ * The catalog is a plain `{ [locale]: { [key]: "..." } }` map — bring your
+ * own keys, namespaces, or nested-key conventions. The SDK does not enforce
+ * a schema so you can plug it into any string-loading pipeline.
+ *
+ * @example
+ * const i18n = createI18n({
+ *     locale: "pt-BR",
+ *     fallbackLocale: "en",
+ *     messages: {
+ *         "pt-BR": {
+ *             "greet": "Olá, {name}",
+ *             "alos_one": "{count} Alô",
+ *             "alos_other": "{count} Alôs",
+ *         },
+ *         "en": { greet: "Hi, {name}", alos_one: "{count} Alo", alos_other: "{count} Alos" },
+ *     },
+ * });
+ * i18n.t("greet", { name: "Mau" });          // "Olá, Mau"
+ * i18n.plural("alos", 3);                     // "3 Alôs"
+ */
+export declare function createI18n(options: CreateI18nOptions): I18n;
+
+export declare interface CreateI18nOptions {
+    /** Initial locale. */
+    locale: string;
+    /** Fallback locale used when a key is missing in the active locale. */
+    fallbackLocale?: string;
+    /** Catalog `{ [locale]: { [key]: "..." } }`. */
+    messages: Catalog;
+}
+
+/**
+ * Trivial in-memory adapter. Suitable for tests, local development, or as a
+ * fallback wrapping the real provider while it loads.
+ */
+export declare function createInMemoryFlags(options?: InMemoryFlagsOptions): FeatureFlagsAdapter & {
+    set: (key: string, value: FlagValue) => void;
+};
+
+/**
+ * Create a structured leveled logger. Plug arbitrary sinks (Sentry, Datadog,
+ * remote ingestion) by implementing the `LoggerSink` interface.
+ */
+export declare function createLogger(options?: CreateLoggerOptions): Logger;
+
+export declare interface CreateLoggerOptions {
+    /** Lowest level recorded. Default: `"info"`. */
+    level?: LogLevel;
+    /** Output adapters. Default: a `console.*` sink. */
+    sinks?: LoggerSink[];
+    /** Initial namespace (prepended to every message). */
+    namespace?: string;
+}
+
+/**
+ * Build a typed IndexedDB-backed store using Dexie. Optionally scope every
+ * operation by an `ownerField` (useful for multi-user SSE history, drafts,
+ * cache per workspace, etc.).
+ *
+ * Dexie is an **optional peer dependency** — install it (`npm i dexie`) only
+ * when your app needs offline storage.
+ *
+ * @example
+ * type Note = { id: string; owner_id: string; text: string; created_at: string };
+ * const notes = createOfflineStore<Note, string>({
+ *     databaseName: "TempestNotes",
+ *     version: 1,
+ *     tableName: "notes",
+ *     indexes: "&id, owner_id, created_at",
+ *     ownerField: "owner_id",
+ * });
+ * await notes.put({ id: "n1", owner_id: "u1", text: "hi", created_at: ... }, "u1");
+ * const mine = await notes.list("u1", { orderBy: "created_at", reverse: true });
+ */
+export declare function createOfflineStore<TItem, TKey extends string | number = string>(config: OfflineStoreConfig<TItem>): OfflineStore<TItem, TKey>;
+
+/**
+ * Build a typed query-key factory for a domain. Each entry can be a static
+ * tuple or a function returning a tuple. The returned object is `as const`
+ * so TanStack Query infers literal keys.
+ *
+ * @example
+ * const userKeys = createQueryKeys("user", {
+ *     me: () => ["me"] as const,
+ *     byId: (id: string) => [id] as const,
+ *     list: (filters: { page: number }) => ["list", filters] as const,
+ * });
+ * // userKeys.byId("42") === ["user", "42"]
+ */
+export declare function createQueryKeys<TKey extends string, TEntries extends Record<string, KeyBuilder | readonly unknown[]>>(scope: TKey, entries: TEntries): {
+    all: readonly [TKey];
+} & { [K in keyof TEntries]: TEntries[K] extends KeyBuilder ? (...args: Parameters<TEntries[K]>) => readonly [TKey, ...ReturnType<TEntries[K]>] : TEntries[K] extends readonly unknown[] ? readonly [TKey, ...TEntries[K]] : never; };
+
+/**
+ * Deduplicate concurrent refresh calls. When multiple 401 responses arrive
+ * at once, all of them share the same in-flight `refresh()` promise instead
+ * of triggering N parallel refreshes.
+ *
+ * @example
+ * const refresh = createRefreshQueue(() => AuthService.refresh());
+ *
+ * // In every request that hits 401:
+ * await refresh();
+ * // ...retry the original request
+ */
+export declare function createRefreshQueue(refresh: () => Promise<void>): () => Promise<void>;
+
+/**
+ * Open a WebSocket with automatic exponential-backoff reconnect, optional
+ * heartbeat pings, and typed JSON parsing.
+ *
+ * @param url - Full ws:// or wss:// URL.
+ * @param options - Connection configuration and callbacks.
+ * @returns Controller exposing `send`, `close`, `reconnect`, and `status`.
+ */
+export declare function createWebSocket<T = unknown>(url: string, options?: CreateWebSocketOptions<T>): WebSocketController;
+
+export declare interface CreateWebSocketOptions<T> {
+    /** Subprotocol(s) forwarded to the `WebSocket` constructor. */
+    protocols?: string | string[];
+    /** Max reconnect attempts. Default: 10. Pass 0 to disable. */
+    maxRetries?: number;
+    /** Initial backoff (ms). Doubles each attempt, capped at `maxBackoff`. Default: 1000. */
+    initialBackoff?: number;
+    /** Maximum backoff (ms). Default: 30000. */
+    maxBackoff?: number;
+    /**
+     * Ping interval (ms). When set, the client sends `pingPayload` periodically
+     * to keep the socket alive. Default: 0 (disabled).
+     */
+    pingInterval?: number;
+    /** Payload sent on each ping. Default: `JSON.stringify({ type: "ping" })`. */
+    pingPayload?: string | ArrayBufferLike | Blob | ArrayBufferView;
+    /** Parse incoming frames. Default: JSON with raw-string fallback. */
+    parser?: (raw: string) => T;
+    onOpen?: (event: Event) => void;
+    onMessage?: (message: WebSocketMessage<T>) => void;
+    onClose?: (event: CloseEvent) => void;
+    onError?: (event: Event) => void;
+    onStatusChange?: (status: WebSocketStatus) => void;
+}
+
+/**
+ * Thin wrapper around the native `<input type="date">` (or `datetime-local`,
+ * `time`, `month`). For richer pickers, pair with `react-datepicker` directly
+ * — this primitive keeps the SDK dep-free.
+ */
+export declare const DatePicker: ForwardRefExoticComponent<DatePickerProps & RefAttributes<HTMLInputElement>>;
+
+export declare interface DatePickerProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "value" | "onChange"> {
+    /** ISO date string (`YYYY-MM-DD`) or empty. */
+    value: string;
+    onChange: (value: string) => void;
+    label?: string;
+    helperText?: string;
+    error?: string;
+    /** Lower bound (`YYYY-MM-DD`). */
+    min?: string;
+    /** Upper bound (`YYYY-MM-DD`). */
+    max?: string;
+    /** Mode. `date` (default), `datetime-local`, `time`, or `month`. */
+    mode?: "date" | "datetime-local" | "time" | "month";
+    wrapperClassName?: string;
+}
+
+export declare interface DecodedJWT {
+    header: Record<string, unknown>;
+    payload: Record<string, unknown> & {
+        exp?: number;
+        iat?: number;
+        sub?: string;
+    };
+    signature: string;
+}
+
+/**
+ * Decode a JWT into header/payload/signature. Does **not** verify the
+ * signature — for that, do it server-side or use a JOSE library on the
+ * client.
+ *
+ * @throws If the token shape is invalid (missing parts, bad JSON).
+ */
+export declare function decodeJWT(token: string): DecodedJWT;
+
+export declare type DocumentVisibility = "visible" | "hidden";
+
+/**
+ * Sliding side panel. Same building blocks as {@link Modal} but anchored to
+ * an edge. Locks body scroll while open.
+ */
+export declare function Drawer({ open, onClose, placement, title, children, footer, closeOnBackdrop, closeOnEsc, hideCloseButton, className, }: DrawerProps): ReactPortal | null;
+
+export declare type DrawerPlacement = "right" | "left" | "top" | "bottom";
+
+export declare interface DrawerProps {
+    open: boolean;
+    onClose: () => void;
+    placement?: DrawerPlacement;
+    title?: ReactNode;
+    children?: ReactNode;
+    footer?: ReactNode;
+    closeOnBackdrop?: boolean;
+    closeOnEsc?: boolean;
+    hideCloseButton?: boolean;
+    className?: string;
+}
+
+export declare interface ElementSize {
+    width: number;
+    height: number;
+}
+
+/** Centered "nothing here yet" placeholder with optional icon and CTA. */
+export declare function EmptyState({ icon, title, description, action, className }: EmptyStateProps): JSX.Element;
+
+export declare interface EmptyStateProps {
+    icon?: ReactNode;
+    title: ReactNode;
+    description?: ReactNode;
+    action?: ReactNode;
+    className?: string;
+}
+
+/**
+ * Class-based React error boundary with a render-prop or static fallback.
+ * Auto-resets when any value in `resetKeys` changes.
+ *
+ * @example
+ * <ErrorBoundary
+ *     resetKeys={[location.pathname]}
+ *     onError={(err) => reportError(err)}
+ *     fallback={({ error, reset }) => (
+ *         <ErrorState description={error.message} onRetry={reset} />
+ *     )}
+ * >
+ *     <App />
+ * </ErrorBoundary>
+ */
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    state: ErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    componentDidUpdate(previousProps: ErrorBoundaryProps): void;
+    reset: () => void;
+    render(): ReactNode;
+}
+
+export declare interface ErrorBoundaryProps {
+    children: ReactNode;
+    /**
+     * Element shown when a descendant throws. Receives the captured error and
+     * a `reset` callback that clears the boundary state.
+     */
+    fallback: ReactNode | ((props: ErrorBoundaryRenderProps) => ReactNode);
+    /** Forwarded to your error tracker (Sentry, Datadog, console, etc.). */
+    onError?: (error: Error, info: ErrorInfo) => void;
+    /**
+     * When any value in this array changes, the boundary automatically resets.
+     * Useful for clearing the error after a navigation.
+     */
+    resetKeys?: readonly unknown[];
+}
+
+export declare interface ErrorBoundaryRenderProps {
+    error: Error;
+    reset: () => void;
+}
+
+declare interface ErrorBoundaryState {
+    error: Error | null;
+}
+
+/** Error placeholder with optional retry CTA. Use when a request fails. */
+export declare function ErrorState({ title, description, onRetry, retryLabel, icon, className, }: ErrorStateProps): JSX.Element;
+
+export declare interface ErrorStateProps {
+    title?: ReactNode;
+    description?: ReactNode;
+    onRetry?: () => void;
+    retryLabel?: string;
+    icon?: ReactNode;
+    className?: string;
+}
+
+export declare interface EventStreamController {
+    close: () => void;
+    /** Force an immediate reconnect, resetting the retry counter. */
+    reconnect: () => void;
+    /** Current connection status. */
+    readonly status: EventStreamStatus;
+}
+
+export declare interface EventStreamMessage<T> {
+    /** Server-named event (default `"message"`). */
+    event: string;
+    /** Parsed payload — JSON-decoded when possible, raw string otherwise. */
+    data: T;
+    /** Server-supplied id, if any. */
+    id?: string;
+    /** Raw `MessageEvent` for advanced cases. */
+    raw: MessageEvent;
+}
+
+export declare type EventStreamStatus = "idle" | "connecting" | "open" | "closed" | "error";
+
+export declare interface FeatureFlagsAdapter {
+    /** Synchronous lookup of a flag with a default. */
+    isEnabled: (key: string, defaultValue?: boolean) => boolean;
+    /** Read a string/number/json flag value. */
+    get: <T extends FlagValue = FlagValue>(key: string, defaultValue?: T) => T;
+    /** Subscribe to flag changes. Optional. */
+    onChange?: (listener: () => void) => () => void;
+}
+
+/** Inject a feature flags adapter into the tree. */
+export declare function FeatureFlagsProvider({ adapter, children }: FeatureFlagsProviderProps): JSX.Element;
+
+export declare interface FeatureFlagsProviderProps {
+    adapter: FeatureFlagsAdapter;
+    children: ReactNode;
+}
+
+/**
+ * Drag-and-drop file dropzone. Pair with `uploadWithProgress` from the SDK
+ * to wire actual uploads with byte-level progress.
+ */
+export declare function FileUpload({ value, onChange, label, accept, multiple, maxSize, onReject, disabled, title, subtitle, className, }: FileUploadProps): JSX.Element;
+
+export declare interface FileUploadProps {
+    /** Files currently in the dropzone (controlled). */
+    value: File[];
+    /** Called with the new list when the user adds or removes a file. */
+    onChange: (files: File[]) => void;
+    label?: string;
+    /** Accept attribute forwarded to `<input>`. */
+    accept?: string;
+    /** Allow multiple files. Default: false. */
+    multiple?: boolean;
+    /** Max file size in bytes. Files above are rejected via `onReject`. */
+    maxSize?: number;
+    /** Called with rejected files when they exceed `maxSize` or fail the `accept` filter. */
+    onReject?: (rejected: {
+        file: File;
+        reason: "size" | "type";
+    }[]) => void;
+    disabled?: boolean;
+    /** Title shown on the empty dropzone. */
+    title?: string;
+    /** Helper line below the title. */
+    subtitle?: string;
+    className?: string;
+}
+
+export declare type FilterPredicate<T> = (item: T, search: string) => boolean;
+
+export declare type FlagValue = boolean | string | number | null;
+
+/** Format an 11-digit Brazilian CEP-like value as `00000-000`. */
+export declare function formatCEP(value: string): string;
+
+/** Format an unmasked CNPJ-shaped value as `00.000.000/0000-00`. */
+export declare function formatCNPJ(value: string): string;
+
+/**
+ * Apply the Brazilian CPF mask `XXX.XXX.XXX-XX`.
+ *
+ * @param value - Raw digits or partially masked string.
+ * @returns Masked CPF string.
+ */
+export declare function formatCPF(value: string): string;
+
+/**
+ * Format a number as Brazilian Real currency.
+ *
+ * @param value - The amount in BRL.
+ * @returns A locale-formatted string, e.g. "R$ 1.234,56".
+ */
+export declare function formatCurrency(value: number): string;
+
+/**
+ * Format an ISO date or Date instance as `dd/MM/yyyy`.
+ *
+ * @param value - ISO string or Date.
+ * @returns Formatted date string, or empty string when input is invalid.
+ */
+export declare function formatDate(value: string | Date): string;
+
+/**
+ * Format an ISO date or Date instance as `dd/MM/yyyy HH:mm`.
+ *
+ * @param value - ISO string or Date.
+ * @returns Formatted datetime string, or empty string when input is invalid.
+ */
+export declare function formatDateTime(value: string | Date): string;
+
+/**
+ * Format a fraction (0-1) as a percentage with one decimal.
+ *
+ * @param value - Fraction between 0 and 1.
+ * @returns Formatted percent string, e.g. "12,5%".
+ */
+export declare function formatPercent(value: number): string;
+
+/**
+ * Apply the Brazilian phone mask `(XX) XXXXX-XXXX` or `(XX) XXXX-XXXX`.
+ *
+ * @param value - Raw digits or partially masked string.
+ * @returns Masked phone string.
+ */
+export declare function formatPhone(value: string): string;
+
+/**
+ * Generate an RFC4122 v4 idempotency key (UUID). Use as the value for an
+ * `Idempotency-Key` header on POST/PATCH requests that must not run twice.
+ */
+export declare function generateIdempotencyKey(): string;
+
+export declare interface GeolocationState {
+    loading: boolean;
+    error: GeolocationPositionError | null;
+    coords: GeolocationCoordinates | null;
+    timestamp: number | null;
+}
+
+/**
+ * Inline-safe theme resolution intended for early bootstrap (e.g. inside the
+ * `<head>` script that prevents the flash of incorrect theme). Reads from
+ * localStorage and falls back to `prefers-color-scheme`.
+ */
+export declare function getInitialTheme(options?: GetInitialThemeOptions): ResolvedTheme;
+
+export declare interface GetInitialThemeOptions {
+    /** localStorage key. Default: `"tempest-theme"`. */
+    storageKey?: string;
+    /** Theme used when nothing is stored and the user has no system preference. */
+    defaultTheme?: ThemeMode;
+}
+
+/** Simple CSS-Grid wrapper for equal-width or custom column layouts. */
+export declare function Grid({ columns, gap, className, style, children, ...props }: GridProps): JSX.Element;
+
+export declare interface GridProps extends HTMLAttributes<HTMLDivElement> {
+    /** Number of columns or a custom `grid-template-columns` value. */
+    columns?: number | string;
+    /** Gap as a CSS length. Numbers map to a multiple of the 4px scale. */
+    gap?: number | string;
+    children?: ReactNode;
+}
+
+export declare interface I18n {
+    /** Currently active locale. */
+    locale: string;
+    /** Fallback locale (or `null` when not configured). */
+    fallbackLocale: string | null;
+    /**
+     * Translate `key`, interpolating `{name}` placeholders from `params`.
+     * Falls back to the configured fallback locale, then to the key itself.
+     */
+    t: (key: string, params?: InterpolationValues) => string;
+    /**
+     * Plural-aware translation. Tries `${key}_one` for `count === 1` and
+     * `${key}_other` otherwise, with `{count}` available for interpolation.
+     */
+    plural: (key: string, count: number, params?: InterpolationValues) => string;
+    /** Format a number using `Intl.NumberFormat` on the active locale. */
+    formatNumber: (value: number, options?: Intl.NumberFormatOptions) => string;
+    /** Format a Date using `Intl.DateTimeFormat` on the active locale. */
+    formatDate: (value: Date | string, options?: Intl.DateTimeFormatOptions) => string;
+    /** Build a new `I18n` instance pointing at a different locale. */
+    withLocale: (locale: string) => I18n;
+}
+
+export declare interface I18nContextValue extends I18n {
+    /** Switch the active locale. Persisted when `storageKey` is set. */
+    setLocale: (locale: string) => void;
+    /** Locales available in the catalog. */
+    availableLocales: string[];
+}
+
+/**
+ * React provider for the SDK's lightweight i18n. Exposes the translation
+ * helpers and a `setLocale` setter to children.
+ */
+export declare function I18nProvider({ children, locale: initialLocale, fallbackLocale, messages, storageKey, }: I18nProviderProps): JSX.Element;
+
+export declare interface I18nProviderProps {
+    children: ReactNode;
+    /** Initial locale. */
+    locale: string;
+    /** Fallback locale used when a key is missing. */
+    fallbackLocale?: string;
+    /** Translation catalog. */
+    messages: Catalog;
+    /** localStorage key for persisting the user choice. Pass `null` to disable. Default: `"tempest-locale"`. */
+    storageKey?: string | null;
+}
+
+export declare interface InMemoryFlagsOptions {
+    initial?: Record<string, FlagValue>;
+}
+
+/**
+ * Labelled text input with helper/error slots and optional adornment icons.
+ * Forwards refs to the underlying `<input>` for integration with form libraries.
+ */
+export declare const Input: ForwardRefExoticComponent<InputProps & RefAttributes<HTMLInputElement>>;
+
+export declare interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+    label?: string;
+    helperText?: string;
+    error?: string;
+    leftIcon?: ReactNode;
+    rightIcon?: ReactNode;
+    wrapperClassName?: string;
+}
+
+/**
+ * Install a `notificationclick` handler that focuses an existing client when
+ * possible and falls back to opening a new window.
+ */
+export declare function installNotificationClickHandler(options?: InstallNotificationClickHandlerOptions): void;
+
+export declare interface InstallNotificationClickHandlerOptions {
+    /** Resolve the destination URL from the notification data. Default: `data.url`. */
+    resolveUrl?: (data: unknown) => string;
+}
+
+/**
+ * Install a `push` event listener that parses the payload as JSON (with a
+ * plain-text fallback) and shows a notification.
+ */
+export declare function installPushHandler(options?: InstallPushHandlerOptions): void;
+
+export declare interface InstallPushHandlerOptions {
+    /** Title used when the payload omits one. */
+    defaultTitle?: string;
+    /** Icon used when the payload omits one. */
+    defaultIcon?: string;
+    /** Badge image (mobile). */
+    defaultBadge?: string;
+    /**
+     * Transform the raw payload before showing the notification. Return `null`
+     * to suppress the notification entirely (e.g. silent pings).
+     */
+    transform?: (payload: PushPayload) => PushPayload | null;
+}
+
+/**
+ * Install a `message` listener that activates a waiting worker when the host
+ * app sends `{ type: "SKIP_WAITING" }`.
+ */
+export declare function installSkipWaitingListener(): void;
+
+export declare type InterpolationValues = Record<string, string | number>;
+
+/**
+ * Return true when the JWT's `exp` claim is in the past (or missing).
+ *
+ * @param token - JWT to inspect.
+ * @param leewaySeconds - Treat tokens expiring within this window as expired.
+ */
+export declare function isJWTExpired(token: string, leewaySeconds?: number): boolean;
+
+/**
+ * Convenience check for environments where the Push API is unavailable
+ * (Safari iOS without PWA install, older browsers, SSR, etc.).
+ */
+export declare function isPushSupported(): boolean;
+
+/** True when the Web Share API is available in this environment. */
+export declare function isShareSupported(): boolean;
+
+export declare interface KeyboardShortcut {
+    /** Key name (`"k"`, `"Enter"`, `"Escape"`, `"ArrowDown"`, etc.). Case-insensitive. */
+    key: string;
+    ctrl?: boolean;
+    meta?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    /** Match either Ctrl or Cmd. Useful for cross-OS shortcuts. */
+    mod?: boolean;
+}
+
+declare type KeyBuilder = (...args: any[]) => readonly unknown[];
+
+/**
+ * Wrap `React.lazy` with automatic retry. Common cause of failure:
+ * deployed-then-cached `index.html` references chunk filenames that no
+ * longer exist. Retrying after a short delay typically picks up the new
+ * bundle; a final `location.reload()` recovers from stale `index.html`.
+ *
+ * @example
+ * const Settings = lazyWithRetry(() => import("./Settings"));
+ */
+export declare function lazyWithRetry<T extends ComponentType<unknown>>(factory: () => Promise<{
+    default: T;
+}>, options?: LazyWithRetryOptions): ReturnType<typeof lazy<T>>;
+
+export declare interface LazyWithRetryOptions {
+    /** Max attempts. Default: 3. */
+    retries?: number;
+    /** Initial delay (ms) before retrying. Default: 400. */
+    initialDelay?: number;
+    /**
+     * Reload the page after every retry fails. Helps when the stale chunk
+     * error is caused by an old `index.html` referencing deleted bundles.
+     * Default: true.
+     */
+    reloadOnFinalFailure?: boolean;
+}
+
+export declare interface ListOptions<TItem> {
+    /** Property to order by. Default: `keyPath`. */
+    orderBy?: keyof TItem & string;
+    /** Reverse the ordering. Default: false. */
+    reverse?: boolean;
+    /** Maximum number of items to return. */
+    limit?: number;
+    /** Skip this many items from the start of the result set. */
+    offset?: number;
+    /** Custom predicate applied after the index query. */
+    filter?: (item: TItem) => boolean;
+}
+
+export declare interface LogEntry {
+    level: LogLevel;
+    message: string;
+    context?: Record<string, unknown>;
+    timestamp: number;
+}
+
+export declare interface Logger {
+    debug: (message: string, context?: Record<string, unknown>) => void;
+    info: (message: string, context?: Record<string, unknown>) => void;
+    warn: (message: string, context?: Record<string, unknown>) => void;
+    error: (message: string, context?: Record<string, unknown>) => void;
+    /** Build a child logger that prefixes the namespace to each message. */
+    child: (namespace: string) => Logger;
+}
+
+export declare interface LoggerSink {
+    (entry: LogEntry): void;
+}
+
+export declare type LogLevel = "debug" | "info" | "warn" | "error";
+
+export declare type Messages = Record<string, string>;
+
+/**
+ * Portal-rendered modal dialog with backdrop, Esc handler, and slots for
+ * header/body/footer. Locks body scroll while open.
+ */
+export declare function Modal({ open, onClose, title, children, footer, size, closeOnBackdrop, closeOnEsc, className, hideCloseButton, }: ModalProps): ReactPortal | null;
+
+export declare interface ModalProps {
+    open: boolean;
+    onClose: () => void;
+    title?: ReactNode;
+    children?: ReactNode;
+    footer?: ReactNode;
+    size?: ModalSize;
+    closeOnBackdrop?: boolean;
+    closeOnEsc?: boolean;
+    className?: string;
+    hideCloseButton?: boolean;
+}
+
+export declare type ModalSize = "sm" | "md" | "lg" | "xl";
+
+/**
+ * Currency-masked input. Stores the value as an integer number of cents to
+ * avoid floating-point error. Suitable for `react-hook-form` once you adapt
+ * the field to expose cents.
+ */
+export declare const MoneyInput: ForwardRefExoticComponent<MoneyInputProps & RefAttributes<HTMLInputElement>>;
+
+export declare interface MoneyInputProps extends Omit<InputProps, "value" | "onChange" | "type"> {
+    /** Cents (integer). Internally treated as 1/100 of the currency unit. */
+    value: number;
+    onChange: (cents: number) => void;
+    /** Currency code for `Intl.NumberFormat`. Default: `"BRL"`. */
+    currency?: string;
+    /** Locale for `Intl.NumberFormat`. Default: `"pt-BR"`. */
+    locale?: string;
+}
+
+export declare interface OfflineStore<TItem, TKey extends string | number> {
+    /** Insert or replace a record. */
+    put: (item: TItem, owner?: string) => Promise<TKey>;
+    /** Insert or replace multiple records in a single transaction. */
+    bulkPut: (items: TItem[], owner?: string) => Promise<TKey>;
+    /** Fetch one record by its primary key. */
+    get: (key: TKey) => Promise<TItem | undefined>;
+    /** List records, optionally scoped to `owner` when `ownerField` is configured. */
+    list: (owner?: string, options?: ListOptions<TItem>) => Promise<TItem[]>;
+    /** Partial update by primary key. Returns the number of records changed. */
+    update: (key: TKey, changes: Partial<TItem>) => Promise<number>;
+    /** Apply a modification to every record matching `owner`. */
+    updateMany: (owner: string | undefined, changes: Partial<TItem>) => Promise<number>;
+    /** Delete one record by primary key. */
+    delete: (key: TKey) => Promise<void>;
+    /** Delete every record matching `owner` (or the entire table when no scope is set). */
+    clear: (owner?: string) => Promise<void>;
+    /** Count records, optionally scoped to `owner`. */
+    count: (owner?: string) => Promise<number>;
+    /** Raw Dexie table for advanced queries. */
+    raw: Table_2<TItem, TKey>;
+    /** Underlying Dexie instance. */
+    db: default_2;
+}
+
+export declare interface OfflineStoreConfig<TItem> {
+    /** IndexedDB database name. */
+    databaseName: string;
+    /** Schema version. Bump when changing indexes; pair with a migration if needed. */
+    version: number;
+    /** Object-store name. */
+    tableName: string;
+    /**
+     * Dexie index definition for the table. Use `&` for the primary key
+     * (unique), e.g. `"&id, owner_id, created_at"`. See Dexie docs for the
+     * full syntax.
+     */
+    indexes: string;
+    /** Property used as the primary key (default: `"id"`). */
+    keyPath?: keyof TItem & string;
+    /**
+     * Optional owner scoping. When set, every read/write method honors the
+     * `owner` argument and persists it on each record (e.g. multi-tenant
+     * notifications keyed by `user_id`).
+     */
+    ownerField?: keyof TItem & string;
+}
+
+/**
+ * Numeric pagination controls. Pair with {@link usePagination} for state.
+ */
+export declare function Pagination({ page, totalPages, onPageChange, pageSize, onPageSizeChange, pageSizeOptions, totalItems, siblingCount, className, }: PaginationProps): JSX.Element | null;
+
+export declare interface PaginationProps {
+    page: number;
+    totalPages: number;
+    onPageChange: (page: number) => void;
+    pageSize?: number;
+    onPageSizeChange?: (size: number) => void;
+    pageSizeOptions?: number[];
+    /** Total items count; if provided, renders the summary text. */
+    totalItems?: number;
+    /** Max number of numbered page buttons to show. Default 7. */
+    siblingCount?: number;
+    className?: string;
+}
+
+/**
+ * Validate an unknown response payload against a zod schema.
+ *
+ * In development, throws a detailed error pointing at the divergent field.
+ * In production, throws a generic error so internals do not leak to users.
+ *
+ * @param schema - The zod schema to parse against.
+ * @param raw - The raw response payload.
+ * @param context - A label used in error messages, e.g. "POST /auth/login".
+ * @returns The parsed, typed payload.
+ */
+export declare function parseResponse<TSchema extends z.ZodTypeAny>(schema: TSchema, raw: unknown, context: string): z.infer<TSchema>;
+
+export declare const PhoneInput: ForwardRefExoticComponent<Omit<InputProps, "onChange" | "value"> & {
+value: string;
+onChange: (value: string) => void;
+} & RefAttributes<HTMLInputElement>>;
+
+/**
+ * Convenience wrapper around a shared {@link AudioPlayer}. Use this for
+ * one-off notification sounds. For more complex flows (e.g. several
+ * simultaneous channels), build a dedicated player with {@link createAudioPlayer}.
+ */
+export declare function playAudio(src: string, options?: PlayAudioOptions): Promise<HTMLAudioElement | null>;
+
+export declare interface PlayAudioOptions {
+    /** Volume between 0 and 1. Default: 1. */
+    volume?: number;
+    /** Loop the clip. Default: false. */
+    loop?: boolean;
+    /** Begin playback immediately. Default: true. */
+    autoplay?: boolean;
+    /** Stop the previous clip managed by this player. Default: false. */
+    stopPrevious?: boolean;
+    /** Fired when playback ends naturally. */
+    onEnded?: () => void;
+    /** Fired on playback error. */
+    onError?: (error: unknown) => void;
+}
+
+/** Linear progress bar with determinate / indeterminate modes. */
+export declare function Progress({ value, max, variant, indeterminate, showLabel, label, className, }: ProgressProps): JSX.Element;
+
+export declare interface ProgressProps {
+    /** Value between 0 and `max` (or 0-100 by default). Ignored when `indeterminate`. */
+    value?: number;
+    max?: number;
+    variant?: ProgressVariant;
+    /** Show an animated indeterminate bar. Default: false. */
+    indeterminate?: boolean;
+    /** Render a numeric label "x% / max" above the bar. Default: false. */
+    showLabel?: boolean;
+    /** Optional left-aligned descriptor (e.g. "Enviando arquivo…"). */
+    label?: string;
+    className?: string;
+}
+
+export declare type ProgressVariant = "primary" | "success" | "warning" | "danger";
+
+/**
+ * Service-worker context helpers for handling `push` and `notificationclick`
+ * events. Import these inside your own `sw.ts` — they expect to run in the
+ * service-worker global scope, not in the main thread.
+ *
+ * @example
+ *   /// <reference lib="webworker" />
+ *   import { installPushHandler, installNotificationClickHandler } from "tempest-react-sdk";
+ *
+ *   installPushHandler({ defaultIcon: "/icons/Logo.png" });
+ *   installNotificationClickHandler();
+ */
+export declare interface PushPayload {
+    title?: string;
+    body?: string;
+    icon?: string;
+    badge?: string;
+    image?: string;
+    tag?: string;
+    url?: string;
+    /** Arbitrary extra data forwarded to `event.notification.data`. */
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Wrapper around `QueryClientProvider` that bootstraps a `QueryClient` with
+ * sane SDK defaults (5-minute stale time, 30-minute gc time, 1 retry).
+ */
+export declare function QueryProvider({ children, client, defaultOptions }: QueryProviderProps): JSX.Element;
+
+export declare interface QueryProviderProps {
+    children: ReactNode;
+    /** Pass an existing client to share it across roots. */
+    client?: QueryClient;
+    /** Overrides for the default options applied when no `client` is provided. */
+    defaultOptions?: DefaultOptions;
+}
+
+/**
+ * Single radio button. Inside a {@link RadioGroup}, name/checked/onChange are
+ * managed by the group; outside, behaves as a regular radio input.
+ */
+export declare const Radio: ForwardRefExoticComponent<RadioProps & RefAttributes<HTMLInputElement>>;
+
+/**
+ * Wraps multiple {@link Radio} children and coordinates selection via context.
+ * Pass `value` for controlled mode or `defaultValue` for uncontrolled.
+ */
+export declare function RadioGroup({ value, defaultValue, onChange, name, disabled, horizontal, className, children, }: RadioGroupProps): JSX.Element;
+
+export declare interface RadioGroupProps {
+    /** Selected value (controlled). */
+    value?: string;
+    /** Default selected value (uncontrolled). */
+    defaultValue?: string;
+    /** Called when the selection changes. */
+    onChange?: (value: string) => void;
+    /** `name` attribute applied to every Radio inside. Auto-generated if omitted. */
+    name?: string;
+    /** Disable every Radio inside. */
+    disabled?: boolean;
+    /** Lay out radios horizontally. Default: false (column). */
+    horizontal?: boolean;
+    className?: string;
+    children: ReactNode;
+}
+
+export declare interface RadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type"> {
+    label?: ReactNode;
+    description?: ReactNode;
+    value: string;
+    wrapperClassName?: string;
+}
+
+/** Recommended refetch intervals (milliseconds). */
+export declare const REFETCH_TIME: {
+    readonly REALTIME: number;
+    readonly FAST: number;
+    readonly DEFAULT: number;
+    readonly SLOW: number;
+};
+
+/**
+ * Register a service worker with consistent update-detection wiring.
+ *
+ * Skips silently when the runtime has no `serviceWorker` support. The host
+ * app keeps full control over the SW file — this helper only handles the
+ * boilerplate around `register()` and `updatefound`.
+ *
+ * @returns The registration when it succeeds, or `null` when unsupported.
+ */
+export declare function registerServiceWorker(options: RegisterServiceWorkerOptions): Promise<ServiceWorkerRegistration | null>;
+
+export declare interface RegisterServiceWorkerOptions {
+    /** Public URL of the compiled service worker file (e.g. `/sw.js`). */
+    url: string;
+    /** SW scope (default: SW directory). */
+    scope?: string;
+    /** Called once the registration is active. */
+    onReady?: (registration: ServiceWorkerRegistration) => void;
+    /**
+     * Called when a new worker has finished installing while another worker
+     * still controls the page. The host app typically prompts the user to
+     * reload and then calls {@link skipWaiting} on the returned worker.
+     */
+    onUpdate?: (waiting: ServiceWorker, registration: ServiceWorkerRegistration) => void;
+    /** Called on registration failure. */
+    onError?: (error: unknown) => void;
+}
+
+export declare interface RequestOptions extends Omit<RequestInit, "body"> {
+    body?: unknown;
+    params?: Record<string, string | number | boolean | undefined | null>;
+}
+
+export declare type ResolvedTheme = "light" | "dark";
+
+declare type Resolver<T> = (values: unknown, context: unknown, options: {
+    criteriaMode?: "firstError" | "all";
+}) => Promise<ResolverOutput<T>>;
+
+declare interface ResolverError {
+    type: string;
+    message: string;
+}
+
+declare interface ResolverOutput<T> {
+    values: T | object;
+    errors: Record<string, ResolverError | object>;
+}
+
+/**
+ * Run `factory()` with exponential backoff. Each attempt awaits an
+ * increasing delay capped at `maxDelay`. Throws the last error if every
+ * attempt fails.
+ *
+ * @example
+ * const data = await retry(() => api.get("/flaky"), { retries: 5 });
+ */
+export declare function retry<T>(factory: () => Promise<T>, options?: RetryOptions): Promise<T>;
+
+export declare interface RetryOptions {
+    /** Max attempts (including the first). Default: 3. */
+    retries?: number;
+    /** Initial backoff in ms. Doubles each attempt, capped at `maxDelay`. Default: 300. */
+    initialDelay?: number;
+    /** Maximum delay between attempts. Default: 10_000. */
+    maxDelay?: number;
+    /**
+     * Return false to stop retrying for a specific error.
+     * Default: retry on any thrown error.
+     */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /** Called before each retry with the upcoming delay. */
+    onRetry?: (info: {
+        attempt: number;
+        delay: number;
+        error: unknown;
+    }) => void;
+    /** Cancel pending retries. */
+    signal?: AbortSignal;
+}
+
+/**
+ * Search input with magnifier icon and a clear button. Controlled component:
+ * pass `value` and `onChange`.
+ */
+export declare const SearchBar: ForwardRefExoticComponent<SearchBarProps & RefAttributes<HTMLInputElement>>;
+
+export declare interface SearchBarProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "onChange"> {
+    value: string;
+    onChange: (value: string) => void;
+    onClear?: () => void;
+    wrapperClassName?: string;
+}
+
+/**
+ * Native `<select>` wrapper with label/helper/error slots. Either provide
+ * `options` for a quick render, or pass `<option>` children directly.
+ */
+export declare const Select: ForwardRefExoticComponent<SelectProps & RefAttributes<HTMLSelectElement>>;
+
+export declare interface SelectOption {
+    value: string | number;
+    label: string;
+    disabled?: boolean;
+}
+
+export declare interface SelectProps extends SelectHTMLAttributes<HTMLSelectElement> {
+    label?: string;
+    helperText?: string;
+    error?: string;
+    options?: SelectOption[];
+    placeholder?: string;
+    wrapperClassName?: string;
+}
+
+/**
+ * Wrap the Web Share API with a uniform result object. Falls through to
+ * `unsupported: true` when the browser lacks `navigator.share`, leaving the
+ * caller free to render a custom fallback (copy-link, social buttons).
+ */
+export declare function share(payload: SharePayload): Promise<ShareResult>;
+
+export declare interface SharePayload {
+    title?: string;
+    text?: string;
+    url?: string;
+    /** Files to share (supported only on a subset of browsers). */
+    files?: File[];
+}
+
+export declare interface ShareResult {
+    /** True when `navigator.share` resolved successfully. */
+    shared: boolean;
+    /** True when the platform did not support the requested payload. */
+    unsupported: boolean;
+    /** True when the user cancelled the share dialog. */
+    cancelled: boolean;
+    error?: unknown;
+}
+
+/** Loading placeholder block. Use `variant="text"` for inline lines, `circle` for avatars. */
+export declare function Skeleton({ variant, width, height, className, style }: SkeletonProps): JSX.Element;
+
+export declare interface SkeletonProps {
+    variant?: "rect" | "text" | "circle";
+    width?: number | string;
+    height?: number | string;
+    className?: string;
+    style?: CSSProperties;
+}
+
+/**
+ * Tell a waiting worker to activate immediately. Pair with `onUpdate` to roll
+ * out updates after the user confirms a reload prompt.
+ */
+export declare function skipWaiting(worker: ServiceWorker): void;
+
+/** Loading spinner with three preset sizes. Provide `label` for screen readers. */
+export declare function Spinner({ size, className, label }: SpinnerProps): JSX.Element;
+
+export declare interface SpinnerProps {
+    size?: SpinnerSize;
+    className?: string;
+    label?: string;
+}
+
+export declare type SpinnerSize = "sm" | "md" | "lg";
+
+/** Flex-based vertical or horizontal stack with a numeric `gap`. */
+export declare function Stack({ direction, gap, align, justify, wrap, className, style, children, ...props }: StackProps): JSX.Element;
+
+export declare type StackAlign = "start" | "center" | "end" | "stretch";
+
+export declare type StackJustify = "start" | "center" | "end" | "between";
+
+export declare interface StackProps extends HTMLAttributes<HTMLDivElement> {
+    /** Direction. Default `vertical`. */
+    direction?: "vertical" | "horizontal";
+    /** Gap as a CSS length. Numbers map to a multiple of the 4px scale. */
+    gap?: number | string;
+    align?: StackAlign;
+    justify?: StackJustify;
+    wrap?: boolean;
+    children?: ReactNode;
+}
+
+/** Recommended `staleTime` presets (milliseconds). */
+export declare const STALE_TIME: {
+    readonly SHORT: number;
+    readonly DEFAULT: number;
+    readonly LONG: number;
+    readonly INFINITE: number;
+};
+
+export declare interface StepItem {
+    label: ReactNode;
+}
+
+/**
+ * Linear progress indicator for multi-step flows. Steps before `current`
+ * render as completed; the step at `current` is active; later steps are
+ * upcoming.
+ */
+export declare function Stepper({ steps, current, orientation, className }: StepperProps): JSX.Element;
+
+export declare interface StepperProps {
+    steps: StepItem[];
+    /** Index of the currently active step (0-based). */
+    current: number;
+    orientation?: "horizontal" | "vertical";
+    className?: string;
+}
+
+/** Stop the clip currently playing on the shared default player. */
+export declare function stopAudio(): void;
+
+/**
+ * Typed wrapper around `localStorage` that JSON-encodes values and
+ * silently handles environments where storage is unavailable (SSR, private mode).
+ */
+export declare const storage: {
+    get<T>(key: string, fallback: T): T;
+    set<T>(key: string, value: T): void;
+    remove(key: string): void;
+};
+
+/** Toggle switch backed by a checkbox input. Accessible via keyboard. */
+export declare const Switch: ForwardRefExoticComponent<SwitchProps & RefAttributes<HTMLInputElement>>;
+
+export declare interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type"> {
+    label?: ReactNode;
+    wrapperClassName?: string;
+}
+
+export declare interface TabItem {
+    id: string;
+    label: ReactNode;
+    content: ReactNode;
+    disabled?: boolean;
+}
+
+/**
+ * Lightweight table that maps a list of rows through declarative `columns`.
+ * Provide `rowKey` so React reconciliation works. Rows become clickable when
+ * `onRowClick` is supplied.
+ */
+export declare function Table<T>({ columns, data, rowKey, onRowClick, emptyMessage, className, }: TableProps<T>): JSX.Element;
+
+export declare type TableAlign = "left" | "right" | "center";
+
+export declare interface TableColumn<T> {
+    key: string;
+    header: ReactNode;
+    /** Render the cell content. Defaults to `row[key]` if not provided. */
+    render?: (row: T, index: number) => ReactNode;
+    align?: TableAlign;
+    width?: string | number;
+    className?: string;
+}
+
+export declare interface TableProps<T> {
+    columns: TableColumn<T>[];
+    data: T[];
+    rowKey: (row: T, index: number) => string | number;
+    onRowClick?: (row: T) => void;
+    emptyMessage?: ReactNode;
+    className?: string;
+}
+
+/**
+ * Accessible tabs with an underline (default) or pill variant. Controlled via
+ * `activeId` + `onChange` or uncontrolled via `defaultId`.
+ */
+export declare function Tabs({ items, defaultId, activeId, onChange, variant, className, }: TabsProps): JSX.Element;
+
+export declare interface TabsProps {
+    items: TabItem[];
+    /** Initial active tab id. Defaults to the first non-disabled item. */
+    defaultId?: string;
+    /** Controlled active id. When provided, ignore internal state. */
+    activeId?: string;
+    onChange?: (id: string) => void;
+    variant?: "underline" | "pill";
+    className?: string;
+}
+
+export declare interface TelemetryAdapter {
+    /** Optional. Called when the provider mounts. */
+    init?: () => void | Promise<void>;
+    /** Associate the current session with a user. */
+    identify: (user: TelemetryUser | null) => void;
+    /** Track a discrete event. */
+    track: (event: TelemetryEvent) => void;
+    /** Report an error / exception with optional context. */
+    captureException: (error: unknown, context?: Record<string, unknown>) => void;
+    /** Flush queued events (e.g. before page unload). */
+    flush?: () => Promise<void> | void;
+}
+
+export declare interface TelemetryEvent {
+    name: string;
+    properties?: Record<string, unknown>;
+}
+
+/**
+ * Inject a telemetry adapter into the tree. Apps can swap implementations
+ * (Sentry, Datadog, PostHog, console) without touching call sites.
+ */
+export declare function TelemetryProvider({ adapter, children }: TelemetryProviderProps): JSX.Element;
+
+export declare interface TelemetryProviderProps {
+    adapter: TelemetryAdapter;
+    children: ReactNode;
+}
+
+export declare interface TelemetryUser {
+    id?: string;
+    email?: string;
+    name?: string;
+    /** Free-form trait bag (plan, role, region, etc.). */
+    traits?: Record<string, unknown>;
+}
+
+/**
+ * Multi-line text input. Mirrors the {@link Input} API for label/helper/error.
+ */
+export declare const Textarea: ForwardRefExoticComponent<TextareaProps & RefAttributes<HTMLTextAreaElement>>;
+
+export declare interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    label?: string;
+    helperText?: string;
+    error?: string;
+    wrapperClassName?: string;
+}
+
+export declare interface ThemeContextValue {
+    /** Raw user preference (light / dark / system). */
+    theme: ThemeMode;
+    /** Effective theme actually applied to the DOM (light or dark). */
+    resolvedTheme: ResolvedTheme;
+    /** Update the preference. Persisted to localStorage when `storageKey` is set. */
+    setTheme: (next: ThemeMode) => void;
+    /** Convenience: flip light ↔ dark. When in `system` mode, switches to the opposite of the current resolved theme. */
+    toggle: () => void;
+}
+
+/**
+ * Plain HTML snippet that sets `data-tempest-theme` on `<html>` before React
+ * hydrates. Inline this in `<head>` to avoid a flash of the wrong theme on
+ * first paint.
+ *
+ * @example
+ * <script dangerouslySetInnerHTML={{ __html: themeInitScript() }} />
+ */
+export declare function themeInitScript(options?: GetInitialThemeOptions): string;
+
+export declare type ThemeMode = "light" | "dark" | "system";
+
+/**
+ * Wire dark/light theming. Writes a data attribute on a target element (the
+ * `<html>` element by default) and exposes the current preference via
+ * {@link useTheme}.
+ *
+ * Pair with `themeInitScript()` in the HTML head to prevent the flash of
+ * incorrect theme on first paint.
+ */
+export declare function ThemeProvider({ children, defaultTheme, storageKey, target, attribute, }: ThemeProviderProps): JSX.Element;
+
+export declare interface ThemeProviderProps {
+    children: ReactNode;
+    /** Initial preference when nothing is stored. Default: `"system"`. */
+    defaultTheme?: ThemeMode;
+    /** localStorage key used to persist the preference. Pass `null` to disable persistence. Default: `"tempest-theme"`. */
+    storageKey?: string | null;
+    /**
+     * Element that receives the `data-tempest-theme` attribute. Defaults to
+     * `document.documentElement`. Override when scoping the theme to a subtree.
+     */
+    target?: () => HTMLElement | null;
+    /** Attribute name written on the target. Default: `"data-tempest-theme"`. */
+    attribute?: string;
+}
+
+export declare interface ToastApi {
+    show: (options: ToastOptions) => string;
+    dismiss: (id: string) => void;
+    success: (description: string, options?: Omit<ToastOptions, "variant" | "description">) => string;
+    error: (description: string, options?: Omit<ToastOptions, "variant" | "description">) => string;
+    warning: (description: string, options?: Omit<ToastOptions, "variant" | "description">) => string;
+    info: (description: string, options?: Omit<ToastOptions, "variant" | "description">) => string;
+}
+
+export declare interface ToastOptions {
+    id?: string;
+    title?: string;
+    description?: string;
+    variant?: ToastVariant;
+    /** Auto-dismiss timeout in ms. Pass `0` to keep the toast until dismissed manually. */
+    duration?: number;
+}
+
+/**
+ * Renders a portalled toast container and exposes the imperative {@link useToast} API.
+ */
+export declare function ToastProvider({ children, defaultDuration }: ToastProviderProps): JSX.Element;
+
+export declare interface ToastProviderProps {
+    children: ReactNode;
+    /** Default auto-dismiss duration (ms). Default 4000. */
+    defaultDuration?: number;
+}
+
+export declare type ToastVariant = "success" | "warning" | "error" | "info";
+
+/**
+ * Lightweight tooltip. Shows on hover and on focus (keyboard-friendly). Wraps
+ * a single child element via `cloneElement`, so the trigger keeps its own ref
+ * and props.
+ */
+export declare function Tooltip({ content, placement, children, disabled, openDelay, }: TooltipProps): JSX.Element;
+
+export declare type TooltipPlacement = "top" | "bottom" | "left" | "right";
+
+export declare interface TooltipProps {
+    /** Tooltip content. Plain text recommended; rich content also works. */
+    content: ReactNode;
+    /** Placement relative to the trigger. Default: `"top"`. */
+    placement?: TooltipPlacement;
+    /** Single React element to attach hover/focus listeners to. */
+    children: ReactElement;
+    /** Disable the tooltip without changing the trigger. */
+    disabled?: boolean;
+    /** Delay (ms) before showing the tooltip. Default: 150. */
+    openDelay?: number;
+}
+
+/** Strip any masking and return only digits. */
+export declare function unmask(value: string): string;
+
+/**
+ * Unregister all registered service workers for this origin.
+ *
+ * @returns Number of workers that were unregistered.
+ */
+export declare function unregisterAllServiceWorkers(): Promise<number>;
+
+export declare interface UploadProgressEvent {
+    /** Bytes already uploaded. */
+    loaded: number;
+    /** Total payload size in bytes — only meaningful when `lengthComputable` is true. */
+    total: number;
+    /** Fraction between 0 and 1, or null when total is unknown. */
+    fraction: number | null;
+    lengthComputable: boolean;
+}
+
+/**
+ * Upload a file (or any payload) with byte-level progress reporting.
+ *
+ * `fetch` cannot report upload progress in browsers, so this helper falls
+ * back to `XMLHttpRequest`. It mirrors the error contract used by
+ * {@link createApiClient}: non-2xx responses throw an {@link ApiError}.
+ *
+ * @returns The parsed JSON response, or the raw text when the response is not JSON.
+ */
+export declare function uploadWithProgress<T = unknown>(options: UploadWithProgressOptions): Promise<T>;
+
+export declare interface UploadWithProgressOptions {
+    url: string;
+    body: FormData | Blob | File;
+    method?: "POST" | "PUT" | "PATCH";
+    headers?: Record<string, string>;
+    /** Returns the current bearer token. */
+    getToken?: () => string | null | undefined;
+    /** Send cookies. Defaults to false. */
+    withCredentials?: boolean;
+    /** Called on every `progress` event from the XHR upload channel. */
+    onProgress?: (event: UploadProgressEvent) => void;
+    /** Abort the request. */
+    signal?: AbortSignal;
+    /** Override the JSON parser. Defaults to `JSON.parse`. */
+    parser?: (raw: string) => unknown;
+}
+
+/**
+ * Convert a base64url-encoded VAPID public key into the `Uint8Array` format
+ * required by `PushManager.subscribe({ applicationServerKey })`.
+ *
+ * @param base64String - VAPID public key (URL-safe base64).
+ * @returns The decoded key as bytes.
+ */
+export declare function urlBase64ToUint8Array(base64String: string): Uint8Array<ArrayBuffer>;
+
+/**
+ * Hook-managed audio player. Each component instance gets its own
+ * {@link AudioPlayer}, so unmounting cleanly stops playback. Useful for
+ * notification chimes, UI feedback sounds, and per-component soundtracks.
+ */
+export declare function useAudio(): UseAudioResult;
+
+export declare interface UseAudioResult {
+    /** Play `src` on the hook's private player. */
+    play: (src: string, options?: PlayAudioOptions) => Promise<void>;
+    /** Stop the current clip. */
+    stop: () => void;
+    /**
+     * Whether the browser's autoplay policy has been satisfied. Becomes
+     * `true` after the first successful `play()`.
+     */
+    unlocked: boolean;
+}
+
+/**
+ * React hook for the PWA install prompt. Captures the `beforeinstallprompt`
+ * event so you can defer the install UI to a moment that fits your UX.
+ */
+export declare function useBeforeInstallPrompt(): UseBeforeInstallPromptResult;
+
+export declare interface UseBeforeInstallPromptResult {
+    /** True when the browser fired `beforeinstallprompt` and the user has not yet decided. */
+    installable: boolean;
+    /** True after the user accepts the install prompt. */
+    installed: boolean;
+    /** Show the install prompt. Resolves with the user's choice. */
+    prompt: () => Promise<"accepted" | "dismissed" | "unsupported">;
+}
+
+/**
+ * Client-side filter helper. Performs a case-insensitive match on the listed
+ * keys when no custom predicate is provided.
+ *
+ * @param items - Source list.
+ * @param search - Search string.
+ * @param keysOrPredicate - Either a list of keys to match against or a custom predicate.
+ * @returns Filtered list (referential identity preserved when search is empty).
+ */
+export declare function useClientFilter<T extends Record<string, unknown>>(items: T[], search: string, keysOrPredicate: (keyof T)[] | FilterPredicate<T>): T[];
+
+/**
+ * Wrapper around `navigator.clipboard.writeText` with a transient `copied`
+ * flag for UI feedback ("Copied!" toast). Falls back gracefully when the
+ * Clipboard API is unavailable.
+ */
+export declare function useClipboard(options?: UseClipboardOptions): UseClipboardResult;
+
+export declare interface UseClipboardOptions {
+    /** Time (ms) before the `copied` flag resets back to false. Default: 1500. */
+    resetAfter?: number;
+}
+
+export declare interface UseClipboardResult {
+    /** True briefly after a successful copy. */
+    copied: boolean;
+    /** Copy a string to the clipboard. Returns `true` on success. */
+    copy: (text: string) => Promise<boolean>;
+    /** Manually reset the `copied` flag. */
+    reset: () => void;
+}
+
+/**
+ * Debounce a fast-changing value. Returns the latest value once `delay` ms
+ * have elapsed without further changes.
+ *
+ * @param value - The value to debounce.
+ * @param delay - Delay in milliseconds (default 300).
+ * @returns The debounced value.
+ */
+export declare function useDebounce<T>(value: T, delay?: number): T;
+
+/**
+ * Memoize a value with a structural equality check. Use when an object/array
+ * created during render is fed to `useEffect` dependencies and you want to
+ * avoid spurious effect runs when only the reference changes.
+ */
+export declare function useDeepMemo<T>(value: T): T;
+
+/** Subscribe to `document.visibilityState`. Returns `"visible"` during SSR. */
+export declare function useDocumentVisibility(): DocumentVisibility;
+
+/**
+ * Hook that propagates errors to the nearest {@link ErrorBoundary}.
+ *
+ * React error boundaries only catch errors thrown during render. Async errors
+ * (failed mutations, websocket failures, etc.) need to be re-thrown in a
+ * render pass — that is what `throwError` does.
+ *
+ * @example
+ * const throwError = useErrorHandler();
+ * useEffect(() => {
+ *     stream.on("error", throwError);
+ * }, []);
+ */
+export declare function useErrorHandler(): (error: unknown) => void;
+
+/**
+ * React hook wrapper around {@link createEventStream}. Connection lifecycle is
+ * tied to the component (and the `url`/`enabled` dependencies); the stream
+ * closes on unmount.
+ *
+ * @example
+ * useEventStream<Notification>(`${API}/notifications/stream`, {
+ *     enabled: !!user,
+ *     withCredentials: true,
+ *     onMessage: ({ data }) => addNotification(data),
+ * });
+ */
+export declare function useEventStream<T = unknown>(url: string, options?: UseEventStreamOptions<T>): UseEventStreamResult<T>;
+
+export declare interface UseEventStreamOptions<T> extends Omit<CreateEventStreamOptions<T>, "onStatusChange"> {
+    /** When false, the stream is not opened. Useful for "wait for auth". Default: true. */
+    enabled?: boolean;
+}
+
+export declare interface UseEventStreamResult<T> {
+    status: EventStreamStatus;
+    /** Last message received (excluding heartbeats). */
+    lastMessage: EventStreamMessage<T> | null;
+    /** Force a reconnect. */
+    reconnect: () => void;
+}
+
+/**
+ * Read a boolean flag and re-render when the adapter fires `onChange`.
+ *
+ * @example
+ * const showNewFeed = useFeatureFlag("new-feed", false);
+ */
+export declare function useFeatureFlag(key: string, defaultValue?: boolean): boolean;
+
+/**
+ * Read a typed flag value (string / number / boolean / null) and re-render
+ * on change.
+ */
+export declare function useFlagValue<T extends FlagValue = FlagValue>(key: string, defaultValue?: T): T;
+
+/**
+ * Trap keyboard focus inside `containerRef` while `active` is true. Cycles
+ * Tab and Shift+Tab between the first and last focusable descendants. Pair
+ * with Modal/Drawer for fully-accessible overlays.
+ */
+export declare function useFocusTrap(containerRef: RefObject<HTMLElement | null>, active: boolean): void;
+
+/** React hook around the Geolocation API. */
+export declare function useGeolocation(options?: UseGeolocationOptions): GeolocationState;
+
+export declare interface UseGeolocationOptions extends PositionOptions {
+    /** Use `watchPosition` instead of one-shot `getCurrentPosition`. Default: false. */
+    watch?: boolean;
+    /** Disable the hook without unmounting. Default: false. */
+    disabled?: boolean;
+}
+
+/**
+ * Access translation helpers. Must be used inside an {@link I18nProvider}.
+ */
+export declare function useI18n(): I18nContextValue;
+
+/**
+ * Detect when the user has been idle for `timeout` ms (no interaction).
+ * Returns `true` once the threshold elapses and back to `false` on activity.
+ */
+export declare function useIdle(timeout?: number): boolean;
+
+/**
+ * Track whether the referenced element intersects the viewport. Useful for
+ * lazy-loading images, "load more" sentinels, and animation triggers.
+ *
+ * @returns `IntersectionObserverEntry | null`. `null` until the first observation.
+ */
+export declare function useIntersectionObserver(ref: RefObject<Element | null>, options?: UseIntersectionObserverOptions): IntersectionObserverEntry | null;
+
+export declare interface UseIntersectionObserverOptions extends IntersectionObserverInit {
+    /** Stop observing after the first intersection (one-shot). Default: false. */
+    once?: boolean;
+}
+
+/**
+ * Bind a global keyboard shortcut. Supports modifier combinations and a
+ * cross-OS `mod` key (Ctrl on Windows/Linux, Cmd on macOS).
+ *
+ * @example
+ * useKeyboardShortcut({ key: "k", mod: true }, () => openSearch());
+ */
+export declare function useKeyboardShortcut(shortcut: KeyboardShortcut, handler: (event: KeyboardEvent) => void, options?: UseKeyboardShortcutOptions): void;
+
+export declare interface UseKeyboardShortcutOptions {
+    /** Disable the shortcut without unmounting. Default: false. */
+    disabled?: boolean;
+    /** Listen to the entire window. Pass `false` to scope to a specific element via the handler. Default: true. */
+    global?: boolean;
+    /** Suppress the event from firing inside `<input>`/`<textarea>`/`[contenteditable]`. Default: true. */
+    ignoreInput?: boolean;
+}
+
+/**
+ * Subscribe to a CSS media query and re-render on match changes.
+ *
+ * @param query - A standard CSS media query string, e.g. "(max-width: 768px)".
+ * @returns True when the query matches.
+ */
+export declare function useMediaQuery(query: string): boolean;
+
+/**
+ * Track the browser's `navigator.onLine` value and re-render on changes.
+ * Returns `true` during SSR (assumption: server is online).
+ */
+export declare function useOnline(): boolean;
+
+/**
+ * Manage page/size state for paginated lists. Reset goes back to page 1
+ * without touching the page size.
+ *
+ * @param initialPage - Starting page (default 1).
+ * @param initialSize - Starting page size (default 50).
+ * @returns Pagination state and setters.
+ */
+export declare function usePagination(initialPage?: number, initialSize?: number): UsePaginationResult;
+
+export declare interface UsePaginationResult {
+    page: number;
+    size: number;
+    setPage: (page: number) => void;
+    setSize: (size: number) => void;
+    reset: () => void;
+}
+
+/**
+ * Poll an async factory on a fixed interval. Skips overlapping requests if a
+ * prior call has not finished. Pause via `disabled` or `stopWhen`.
+ */
+export declare function usePoll<T>(factory: () => Promise<T>, options: UsePollOptions<T>): UsePollResult<T>;
+
+export declare interface UsePollOptions<T> {
+    /** Polling interval in ms. */
+    interval: number;
+    /** Disable polling without unmounting. Default: false. */
+    disabled?: boolean;
+    /** Stop polling once the predicate returns true. */
+    stopWhen?: (data: T) => boolean;
+    /** Called on each error. */
+    onError?: (error: unknown) => void;
+}
+
+export declare interface UsePollResult<T> {
+    data: T | null;
+    error: unknown;
+    loading: boolean;
+    stop: () => void;
+    start: () => void;
+}
+
+/**
+ * React hook around {@link WebPushClient}. Tracks subscription, permission and
+ * loading state; exposes imperative `subscribe`/`unsubscribe` actions.
+ *
+ * The hook does NOT register the service worker — the host app must do that
+ * (e.g. via `vite-plugin-pwa` or a manual `navigator.serviceWorker.register`).
+ *
+ * @example
+ * const push = usePushSubscription({
+ *     vapidPublicKey: import.meta.env.VITE_VAPID_PUBLIC_KEY,
+ *     onSubscribe: (sub) => api.post("/webpush/subscribe", { body: sub }),
+ *     onUnsubscribe: () => api.delete("/webpush/my"),
+ * });
+ */
+export declare function usePushSubscription(config: WebPushClientConfig): UsePushSubscriptionResult;
+
+export declare interface UsePushSubscriptionResult {
+    /** True when the browser exposes the Push + Notification APIs. */
+    supported: boolean;
+    /** Current `Notification.permission` value, or `"unsupported"`. */
+    permission: NotificationPermission | "unsupported";
+    /** True when a subscription is active on this device. */
+    subscribed: boolean;
+    /** True while a subscribe/unsubscribe call is in-flight. */
+    loading: boolean;
+    /** Last error thrown by subscribe/unsubscribe, if any. */
+    error: Error | null;
+    subscribe: () => Promise<void>;
+    unsubscribe: () => Promise<void>;
+    /** Re-read the current subscription/permission state from the browser. */
+    refresh: () => Promise<void>;
+}
+
+/**
+ * Track size changes of a DOM element via `ResizeObserver`.
+ * Returns `null` until the first measurement.
+ */
+export declare function useResizeObserver(ref: RefObject<Element | null>): ElementSize | null;
+
+/**
+ * Lock `<body>` scroll while `active` is true. Restores the previous overflow
+ * value on unmount. Safe to nest: stacks the restoration via a counter.
+ */
+export declare function useScrollLock(active: boolean): void;
+
+/**
+ * Returns a stable function reference that always invokes the latest
+ * `callback` argument. Use to break dependency cycles in effects without
+ * triggering re-runs when the callback identity changes.
+ */
+export declare function useStableCallback<TArgs extends unknown[], TReturn>(callback: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+
+/**
+ * Access the active telemetry adapter. Returns `null` when no provider is
+ * mounted (calls are silently dropped — useful for unit tests).
+ */
+export declare function useTelemetry(): TelemetryAdapter | null;
+
+/**
+ * Read and mutate the current theme. Must be used inside a {@link ThemeProvider}.
+ */
+export declare function useTheme(): ThemeContextValue;
+
+/**
+ * Access the toast API. Must be used inside a {@link ToastProvider}.
+ *
+ * @returns Methods to show and dismiss toasts.
+ */
+export declare function useToast(): ToastApi;
+
+/**
+ * Shortcut for components that only need the `t` function — avoids destructuring.
+ */
+export declare function useTranslate(): I18nContextValue["t"];
+
+/**
+ * React hook for the public ViaCEP service (`viacep.com.br`). No backend
+ * required. Returns address fields when the CEP exists, or sets `error` for
+ * invalid CEPs.
+ */
+export declare function useViaCEP(): UseViaCEPResult;
+
+export declare interface UseViaCEPResult {
+    loading: boolean;
+    error: string | null;
+    data: ViaCEPResult | null;
+    /** Fetch the given CEP (8 digits or masked). Sets `data`/`error`. Returns the result. */
+    lookup: (cep: string) => Promise<ViaCEPResult | null>;
+    reset: () => void;
+}
+
+/**
+ * React hook around {@link createWebSocket}. Manages the connection lifecycle
+ * for the host component and tears it down on unmount.
+ */
+export declare function useWebSocket<T = unknown>(url: string, options?: UseWebSocketOptions<T>): UseWebSocketResult<T>;
+
+export declare interface UseWebSocketOptions<T> extends Omit<CreateWebSocketOptions<T>, "onStatusChange"> {
+    /** When false, the socket is not opened. Default: true. */
+    enabled?: boolean;
+}
+
+export declare interface UseWebSocketResult<T> {
+    status: WebSocketStatus;
+    /** Last decoded frame received. */
+    lastMessage: WebSocketMessage<T> | null;
+    /** Send a payload through the active connection. Returns false when not open. */
+    send: (payload: string | ArrayBufferLike | Blob | ArrayBufferView) => boolean;
+    /** Force a reconnect, resetting the retry counter. */
+    reconnect: () => void;
+}
+
+/**
+ * Convenience wrapper around `react-hook-form`'s `useForm` that wires a zod
+ * resolver and infers the form's value type from the schema.
+ *
+ * Both `react-hook-form` and `zod` are optional peer dependencies — install
+ * them when your app uses forms.
+ *
+ * @example
+ * const form = useZodForm(loginSchema, { defaultValues: { email: "" } });
+ * form.register("email");
+ */
+export declare function useZodForm<TSchema extends z.ZodTypeAny, TValues extends FieldValues = z.infer<TSchema> & FieldValues>(schema: TSchema, options?: Omit<UseFormProps<TValues>, "resolver">): UseFormReturn<TValues>;
+
+/**
+ * Validate a Brazilian CNPJ using the standard check-digit algorithm.
+ * Accepts masked or raw input; rejects all-equal digits.
+ */
+export declare function validateCNPJ(value: string): boolean;
+
+/**
+ * Validate a Brazilian CPF using the standard check-digit algorithm.
+ * Accepts masked or raw input; rejects all-equal digits ("111.111.111-11").
+ */
+export declare function validateCPF(value: string): boolean;
+
+/**
+ * Validate `values` against a zod schema and return a per-field error map
+ * compatible with most form libraries.
+ *
+ * Field paths follow zod's `issue.path.join(".")` convention — nested fields
+ * become `"address.city"`, array entries `"items.0.name"`. The first issue
+ * per path wins (subsequent ones are dropped to keep error UIs tidy).
+ *
+ * @param schema - zod schema describing the form shape.
+ * @param values - Raw form values (typed as `unknown`).
+ * @returns Either `{ success: true, data, errors: {} }` or `{ success: false, errors }`.
+ */
+export declare function validateForm<TSchema extends z.ZodTypeAny>(schema: TSchema, values: unknown): ValidateFormResult<z.infer<TSchema>>;
+
+export declare interface ValidateFormFailure {
+    success: false;
+    errors: Record<string, string>;
+}
+
+export declare type ValidateFormResult<T> = ValidateFormSuccess<T> | ValidateFormFailure;
+
+export declare interface ValidateFormSuccess<T> {
+    success: true;
+    data: T;
+    errors: Record<string, string>;
+}
+
+export declare interface ViaCEPResult {
+    cep: string;
+    logradouro: string;
+    complemento: string;
+    bairro: string;
+    localidade: string;
+    uf: string;
+    ibge?: string;
+    gia?: string;
+    ddd?: string;
+    siafi?: string;
+}
+
+/**
+ * Fixed-height virtual list. Renders only the visible window plus a small
+ * overscan buffer. Suitable for lists of thousands of identical rows.
+ *
+ * For variable heights, use `react-window`/`@tanstack/react-virtual` — those
+ * solve a more general problem at the cost of extra setup.
+ */
+export declare function VirtualList<T>({ items, itemHeight, renderItem, height, overscan, getKey, className, style, }: VirtualListProps<T>): JSX.Element;
+
+export declare interface VirtualListProps<T> {
+    items: T[];
+    /** Fixed pixel height for each row. */
+    itemHeight: number;
+    /** Render a single row. */
+    renderItem: (item: T, index: number) => ReactNode;
+    /** Container height (px) or any CSS length. */
+    height: number | string;
+    /** Number of items rendered above/below the viewport. Default: 4. */
+    overscan?: number;
+    /** Stable key derivation; defaults to the index. */
+    getKey?: (item: T, index: number) => string | number;
+    className?: string;
+    style?: CSSProperties;
+}
+
+/**
+ * Browser-side Web Push helper. Wraps `Notification.requestPermission`,
+ * `pushManager.subscribe`, and the corresponding teardown. Transport is up to
+ * the caller via `onSubscribe` / `onUnsubscribe` callbacks.
+ */
+export declare class WebPushClient {
+    private readonly config;
+    constructor(config: WebPushClientConfig);
+    /** Whether the runtime supports the Push API. */
+    static isSupported(): boolean;
+    private registration;
+    /** Current `Notification.permission` value, or `"unsupported"`. */
+    permission(): NotificationPermission | "unsupported";
+    /**
+     * Ask the user for notification permission.
+     *
+     * @throws {WebPushUnsupportedError} If the runtime lacks the Notification API.
+     * @returns The resulting `NotificationPermission` value.
+     */
+    requestPermission(): Promise<NotificationPermission>;
+    /** Return the active push subscription, if any. */
+    getSubscription(): Promise<PushSubscription | null>;
+    /** True when a subscription already exists for this browser. */
+    isSubscribed(): Promise<boolean>;
+    /**
+     * Subscribe the current device. Requests permission, creates a push
+     * subscription if none exists, and forwards the JSON payload to
+     * `onSubscribe` for backend persistence.
+     *
+     * @returns The active `PushSubscription`.
+     * @throws {WebPushUnsupportedError} If Web Push is unavailable.
+     * @throws {WebPushPermissionDeniedError} If the user denies the prompt.
+     */
+    subscribe(): Promise<PushSubscription>;
+    /**
+     * Cancel the current subscription. Calls `onUnsubscribe` first (so the
+     * backend can purge the record) and then `subscription.unsubscribe()`.
+     *
+     * @returns True when an active subscription was removed, false otherwise.
+     */
+    unsubscribe(): Promise<boolean>;
+}
+
+export declare interface WebPushClientConfig {
+    /** VAPID public key (URL-safe base64). */
+    vapidPublicKey: string;
+    /**
+     * Persist the subscription on the backend. The SDK does not own this call —
+     * the host app decides the endpoint and how the payload is serialized.
+     */
+    onSubscribe: (subscription: PushSubscriptionJSON) => Promise<void> | void;
+    /** Remove the subscription from the backend. Called before `subscription.unsubscribe()`. */
+    onUnsubscribe?: (subscription: PushSubscriptionJSON) => Promise<void> | void;
+    /**
+     * Override how the service worker registration is obtained.
+     * Defaults to `navigator.serviceWorker.ready` — provide this only when you
+     * register the SW yourself and want to reuse the registration.
+     */
+    getRegistration?: () => Promise<ServiceWorkerRegistration>;
+}
+
+export declare class WebPushPermissionDeniedError extends Error {
+    constructor();
+}
+
+export declare class WebPushUnsupportedError extends Error {
+    constructor();
+}
+
+export declare interface WebSocketController {
+    /** Send a payload over the current connection. No-op when not open. */
+    send: (payload: string | ArrayBufferLike | Blob | ArrayBufferView) => boolean;
+    /** Close the connection and stop reconnecting. */
+    close: (code?: number, reason?: string) => void;
+    /** Force an immediate reconnect, resetting the retry counter. */
+    reconnect: () => void;
+    /** Current connection status. */
+    readonly status: WebSocketStatus;
+}
+
+export declare interface WebSocketMessage<T> {
+    /** Parsed payload — JSON-decoded when possible, raw string otherwise. */
+    data: T;
+    /** The original `MessageEvent`. */
+    raw: MessageEvent;
+}
+
+export declare type WebSocketStatus = "idle" | "connecting" | "open" | "closing" | "closed" | "error";
+
+/**
+ * Minimal `react-hook-form` resolver built on top of zod. Mirrors the shape
+ * produced by `@hookform/resolvers/zod` so it can be passed straight to
+ * `useForm({ resolver })`.
+ *
+ * @example
+ * const form = useForm<LoginForm>({ resolver: zodResolver(loginSchema) });
+ */
+export declare function zodResolver<TSchema extends z.ZodTypeAny>(schema: TSchema): Resolver<z.infer<TSchema>>;
+
+export { }