tempest-react-sdk 0.21.0 → 0.23.0

package/dist/tempest-react-sdk.d.ts

@@ -38,6 +38,7 @@ import { LabelHTMLAttributes } from 'react';
 import { lazy } from 'react';
 import { Link } from 'react-router-dom';
 import { MemoryRouter } from 'react-router-dom';
+import { MouseEvent as MouseEvent_2 } from 'react';
 import { MouseEventHandler } from 'react';
 import { Navigate } from 'react-router-dom';
 import { NavigateOptions } from 'react-router-dom';
@@ -67,6 +68,7 @@ import { Table as Table_2 } from 'dexie';
 import { TextareaHTMLAttributes } from 'react';
 import { To } from 'react-router-dom';
 import { ToggleEventHandler } from 'react';
+import { TouchEvent as TouchEvent_2 } from 'react';
 import { TouchEventHandler } from 'react';
 import { TransitionEventHandler } from 'react';
 import { UIEventHandler } from 'react';
@@ -580,6 +582,24 @@ export declare type BannerVariant = "info" | "success" | "warning" | "danger";
  */
 export declare function bearingDeg(origin: Coordinate, destination: Coordinate): number;
 
+/**
+ * The Chromium-only `beforeinstallprompt` event. iOS Safari never fires it —
+ * for those users the app falls back to manual "Add to Home Screen"
+ * instructions. Ported into the SDK so consumers get the type without a global
+ * augmentation.
+ */
+export declare interface BeforeInstallPromptEvent extends Event {
+    /** Platforms the prompt can target (e.g. `["web", "android"]`). */
+    readonly platforms: readonly string[];
+    /** Resolves once the user accepts or dismisses the prompt. */
+    readonly userChoice: Promise<{
+        outcome: "accepted" | "dismissed";
+        platform: string;
+    }>;
+    /** Shows the native install prompt. */
+    prompt: () => Promise<void>;
+}
+
 /**
  * Fixed-bottom mobile tab bar. 3–5 items recommended. Pair with
  * `<Show below="md">` to render only on mobile.
@@ -723,6 +743,16 @@ export declare function buildApiError(status: number, body: unknown, headers?: H
     get(name: string): string | null;
 }, sentRequestId?: string): ApiError;
 
+/**
+ * Builds an `intent://` URL that re-opens the current page inside Chrome on
+ * Android. When Chrome is missing, the fallback URL points to the Play Store so
+ * the user can still recover. Returns `null` outside Android.
+ *
+ * @returns The `intent://` URL, or `null` when not on Android or without a DOM.
+ * @see https://developer.chrome.com/docs/multidevice/android/intents
+ */
+export declare function buildOpenInChromeIntent(): string | null;
+
 /**
  * Primary action button with variants, sizes and a loading state that
  * preserves layout via an absolutely-positioned spinner.
@@ -759,6 +789,25 @@ export declare const CACHE_TIME: {
     readonly LONG: number;
 };
 
+/** A cache-name matcher: a prefix string, a `RegExp`, or a predicate. */
+export declare type CacheFilter = string | RegExp | ((name: string) => boolean);
+
+/**
+ * Main-thread helpers to inspect and clear the Cache Storage buckets a service
+ * worker fills — for a "X MB cacheado" readout and a "limpar cache" action
+ * (e.g. on logout). All guard `caches` so they no-op safely under SSR / older
+ * browsers.
+ */
+/** Per-cache usage summary returned by {@link inspectCaches}. */
+export declare interface CacheReport {
+    /** The Cache Storage bucket name. */
+    name: string;
+    /** Number of cached responses. */
+    entries: number;
+    /** Approximate total bytes, or `null` when byte measurement was skipped. */
+    bytes: number | null;
+}
+
 /**
  * Standalone month-grid date picker. Renders a header with the month/year and
  * prev/next buttons, a weekday row, and a 6x7 grid of day buttons. Selection and
@@ -957,8 +1006,12 @@ export declare interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInpu
 /**
  * Multi-value input. Type a value and press Enter (or comma / Tab) to push a
  * chip. Backspace on empty input removes the last chip.
+ *
+ * Name the field with `label` (associated through `htmlFor`) or, when the label
+ * lives elsewhere in the layout, with `aria-label`. The placeholder is not an
+ * accessible name — it disappears as soon as the first chip is added.
  */
-export declare function ChipInput({ value, onChange, label, placeholder, helperText, error, commitKeys, normalize, className, }: ChipInputProps): JSX.Element;
+export declare function ChipInput({ value, onChange, label, placeholder, helperText, error, commitKeys, normalize, className, id, "aria-label": ariaLabel, }: ChipInputProps): JSX.Element;
 
 export declare interface ChipInputProps {
     value: string[];
@@ -967,6 +1020,13 @@ export declare interface ChipInputProps {
     placeholder?: string;
     helperText?: string;
     error?: string;
+    /** Id for the inner input. Generated when omitted. */
+    id?: string;
+    /**
+     * Accessible name for the inner input when there is no visible `label`.
+     * Without either, screen readers announce an unnamed text field.
+     */
+    "aria-label"?: string;
     /** Keys that commit the current draft as a chip. Default: Enter, comma, Tab. */
     commitKeys?: string[];
     /** Lowercase + trim each chip + dedupe. Default: true. */
@@ -1006,6 +1066,18 @@ export declare function clampLatitude(latitude: number): number;
 
 declare type ClassValue = string | number | bigint | boolean | null | undefined | ClassValue[];
 
+/**
+ * Delete Cache Storage buckets whose name passes `filter` (all of them when no
+ * filter is given).
+ *
+ * @param filter - Which caches to delete.
+ * @returns The names of the caches that were deleted.
+ *
+ * @example
+ * await clearCaches("tempest-"); // drop every SDK-managed cache on logout
+ */
+export declare function clearCaches(filter?: CacheFilter): Promise<string[]>;
+
 /**
  * Wraps its children in a `<div>` and invokes `onOutside` whenever a
  * `mousedown` or `touchstart` event occurs outside that subtree.
@@ -2076,6 +2148,11 @@ export declare interface DataProviderOptions {
  * - Search matches a case-insensitive substring across `searchKeys`
  *   (or every string/number column when not provided).
  * - Pagination is hidden when the result fits on a single page.
+ *
+ * The header memo depends on `columns` and `sort` only: `toggleSort` is
+ * recreated each render but always closes over the same setter, so including it
+ * would rebuild every header on every render without changing behaviour. That
+ * is why `exhaustive-deps` is silenced on that dependency array.
  */
 export declare function DataTable<T>({ data, columns, pageSize, searchable, searchKeys, initialSort, rowKey, emptyMessage, className, ...rest }: DataTableProps<T>): JSX.Element;
 
@@ -2542,6 +2619,13 @@ export declare interface ErrorTextProps extends HTMLAttributes<HTMLParagraphElem
 
 export declare function estimatePasswordStrength(value: string): PasswordStrength;
 
+/**
+ * Read the origin's current storage usage and quota.
+ *
+ * @returns The estimate, or `{ usage: null, quota: null }` when unsupported.
+ */
+export declare function estimateStorage(): Promise<StorageEstimate_2>;
+
 /**
  * Offline travel estimate between two coordinates. No network — distance comes
  * from {@link haversineKm} scaled by circuity, duration from a mode-adjusted
@@ -3188,6 +3272,24 @@ export declare interface HideProps {
     children: ReactNode;
 }
 
+/**
+ * Resolve a conflict by keeping whichever record carries the higher version
+ * number (monotonic counter / row version). The remote record wins ties.
+ *
+ * @typeParam T - The record shape.
+ * @param local - The current local record, or `undefined` when new.
+ * @param remote - The incoming remote record.
+ * @param getVersion - Reads the monotonic version number.
+ * @returns The winning record.
+ *
+ * @example
+ * applyRemote: async (dto) => {
+ *     const local = await store.get(dto.id);
+ *     await store.save(higherVersionWins(local, dto, (r) => r.version));
+ * }
+ */
+export declare function higherVersionWins<T>(local: T | undefined, remote: T, getVersion: (record: T) => number): T;
+
 /**
  * Content preview shown when the trigger is hovered or focused.
  *
@@ -3313,6 +3415,24 @@ export declare interface InputProps extends Omit<InputHTMLAttributes<HTMLInputEl
 
 export declare type InputSize = "sm" | "md" | "lg";
 
+/**
+ * Report entry counts (and optionally byte sizes) for the Cache Storage
+ * buckets whose name passes `filter`.
+ *
+ * @param options - `filter` narrows which caches to include; `measureBytes`
+ *   (default `true`) reads each response to sum sizes — set `false` for a fast,
+ *   count-only report.
+ * @returns One {@link CacheReport} per matching cache. Empty when unsupported.
+ *
+ * @example
+ * const reports = await inspectCaches({ filter: "tempest-" });
+ * const totalMb = reports.reduce((n, r) => n + (r.bytes ?? 0), 0) / 1e6;
+ */
+export declare function inspectCaches(options?: {
+    filter?: CacheFilter;
+    measureBytes?: boolean;
+}): Promise<CacheReport[]>;
+
 /**
  * Install the background-sync queue: on a failed mutating request, the request
  * is serialized to IndexedDB and a sync is registered; the original fetch still
@@ -3347,6 +3467,13 @@ export declare interface InstallBackgroundSyncOptions {
     queueName?: string;
     /** Drop queued requests older than this (minutes) on replay. Default `1440` (24h). */
     maxRetentionMinutes?: number;
+    /**
+     * Also drain the queue on the `periodicsync` event carrying this tag,
+     * complementing the one-off `sync` replay so long-pending mutations retry
+     * even without a fresh navigation. Register the periodic sync from the main
+     * thread with {@link registerPeriodicSync}. Default `${queueName}-periodic`.
+     */
+    periodicSyncTag?: string;
 }
 
 /**
@@ -3406,6 +3533,17 @@ export declare interface InstallButtonProps extends Omit<ButtonProps, "onClick"
     onResult?: (outcome: InstallOutcome) => void;
 }
 
+/**
+ * Strategy the UI should use to install the app:
+ *
+ * - `"native"`: trigger `BeforeInstallPromptEvent.prompt()`.
+ * - `"ios"`: show iOS Safari Share → Add to Home Screen instructions.
+ * - `"manual"`: show generic browser-menu instructions (Chromium forks that
+ *   strip the prompt API, plus the timeout fallback when no event arrives).
+ * - `"none"`: nothing to offer (already installed or unsupported runtime).
+ */
+export declare type InstallMethod = "native" | "ios" | "manual" | "none";
+
 /**
  * Install a `notificationclick` handler that focuses an existing client when
  * possible and falls back to opening a new window.
@@ -3443,6 +3581,13 @@ export declare interface InstallPrecacheOptions {
     navigateFallbackDenylist?: RegExp[];
     /** Activate the new worker immediately after precaching. Default `true`. */
     skipWaiting?: boolean;
+    /**
+     * Enable the Navigation Preload API on `activate`, so the browser fetches
+     * the navigation request in parallel with the worker boot and the handler
+     * serves `event.preloadResponse` — cutting first-navigation latency after
+     * the worker starts. Silently ignored where unsupported. Default `true`.
+     */
+    navigationPreload?: boolean;
 }
 
 /**
@@ -3485,6 +3630,22 @@ export declare function installSkipWaitingListener(): void;
 
 export declare type InterpolationValues = Record<string, string | number>;
 
+/**
+ * Detects any Android browser.
+ *
+ * @returns `true` when the user agent reports Android.
+ */
+export declare function isAndroid(): boolean;
+
+/**
+ * Detects Android browsers that ship a Chromium fork with the
+ * `beforeinstallprompt` event stripped or unreliable. Those users must install
+ * via the browser menu manually, identical to iOS Safari.
+ *
+ * @returns `true` when running on such an Android browser.
+ */
+export declare function isAndroidWithoutPromptApi(): boolean;
+
 /**
  * Type guard for the {@link ApiError} shape. Matches both {@link TempestApiError}
  * instances and plain objects carrying `status` + `detail`.
@@ -3539,6 +3700,14 @@ export declare function isDefined<T>(value: T | null | undefined): value is T;
  */
 export declare function isEmpty(value: unknown): boolean;
 
+/**
+ * Detects iOS / iPadOS Safari, including modern iPads that report `MacIntel`
+ * plus multi-touch instead of an `iPad` user agent.
+ *
+ * @returns `true` when running on iOS/iPadOS.
+ */
+export declare function isIOS(): boolean;
+
 /**
  * Return true when the JWT's `exp` claim is in the past (or missing).
  *
@@ -3588,6 +3757,15 @@ export declare function isPushSupported(): boolean;
 /** True when the Web Share API is available in this environment. */
 export declare function isShareSupported(): boolean;
 
+/**
+ * Reports whether the app is running as an installed PWA (Android Chrome, iOS,
+ * or desktop). Use it to suppress install CTAs once the user is already in the
+ * standalone shell.
+ *
+ * @returns `true` when the display mode is standalone or iOS reports standalone.
+ */
+export declare function isStandalone(): boolean;
+
 /**
  * Type guard asserting a value is a string primitive.
  *
@@ -3655,6 +3833,31 @@ export declare interface LabelProps extends LabelHTMLAttributes<HTMLLabelElement
     required?: boolean;
 }
 
+/**
+ * Conflict-resolution helpers for the `applyRemote` callback of
+ * {@link createOfflineSync}. Each takes the current local record (or
+ * `undefined` when the record is new locally) and the incoming remote record,
+ * and returns the winner. Ties resolve to the remote copy, treating the server
+ * as authoritative.
+ */
+/**
+ * Resolve a conflict by keeping whichever record was written last, comparing a
+ * timestamp field. The remote record wins ties.
+ *
+ * @typeParam T - The record shape.
+ * @param local - The current local record, or `undefined` when new.
+ * @param remote - The incoming remote record.
+ * @param getTimestamp - Reads the comparison timestamp (epoch ms, ISO string or `Date`).
+ * @returns The winning record.
+ *
+ * @example
+ * applyRemote: async (dto) => {
+ *     const local = await store.get(dto.id);
+ *     await store.save(lastWriteWins(local, dto, (r) => r.updatedAt));
+ * }
+ */
+export declare function lastWriteWins<T>(local: T | undefined, remote: T, getTimestamp: (record: T) => number | string | Date): T;
+
 declare interface LayoutProps {
     /** Field arrangement. `stack` stacks fields vertically, `inline` lines them up in a wrapping row, `grid` arranges them in `columns` equal-width tracks. Default `stack`. */
     layout?: FormLayout;
@@ -3799,6 +4002,27 @@ export declare interface LoggerSink {
 
 export declare type LogLevel = "debug" | "info" | "warn" | "error";
 
+/**
+ * DOM event handlers produced by {@link useLongPressHandlers}, ready to spread
+ * onto a JSX element (`<div {...handlers}>`).
+ */
+export declare interface LongPressHandlers {
+    /** Starts the hold timer on mouse press. */
+    onMouseDown: (event: MouseEvent_2) => void;
+    /** Cancels the pending hold when the mouse is released. */
+    onMouseUp: () => void;
+    /** Cancels the pending hold when the pointer leaves the element. */
+    onMouseLeave: () => void;
+    /** Starts the hold timer on touch start. */
+    onTouchStart: (event: TouchEvent_2) => void;
+    /** Cancels the pending hold when the touch ends. */
+    onTouchEnd: () => void;
+    /** Cancels the pending hold when the finger moves. */
+    onTouchMove: () => void;
+    /** Fires the long-press immediately (desktop right-click parity). */
+    onContextMenu: (event: MouseEvent_2) => void;
+}
+
 /**
  * Memoize only the most recent call of `fn`, keyed by shallow-equal arguments.
  *
@@ -3885,8 +4109,13 @@ 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.
+ *
+ * The `dialog` role needs an accessible name: a `title` supplies it via
+ * `aria-labelledby`, and a titleless dialog should pass `aria-label`. The
+ * header heading is only rendered when there is a title, so a close-button-only
+ * header does not leave an empty `h3` behind.
  */
-export declare function Modal({ open, onClose, title, children, footer, size, closeOnBackdrop, closeOnEsc, className, hideCloseButton, fullscreen, fullscreenOnMobile, }: ModalProps): ReactPortal | null;
+export declare function Modal({ open, onClose, title, children, footer, size, closeOnBackdrop, closeOnEsc, className, hideCloseButton, fullscreen, fullscreenOnMobile, "aria-label": ariaLabel, }: ModalProps): ReactPortal | null;
 
 export declare interface ModalProps {
     open: boolean;
@@ -3903,6 +4132,11 @@ export declare interface ModalProps {
     fullscreen?: boolean;
     /** Auto-fullscreen on mobile viewports (< 640px). Default `false`. */
     fullscreenOnMobile?: boolean;
+    /**
+     * Accessible name for the dialog. Only needed when there is no `title` —
+     * with a `title` the dialog is named by it through `aria-labelledby`.
+     */
+    "aria-label"?: string;
 }
 
 /** Imperative API returned by {@link useModals}. */
@@ -4008,6 +4242,10 @@ export declare interface MultiSelectProps {
     className?: string;
 }
 
+declare interface MutationContext<TData> {
+    previous: TData | undefined;
+}
+
 /**
  * Top app bar. Three-slot layout (logo / nav / actions) that collapses
  * gracefully on mobile (nav slot wraps below).
@@ -4216,6 +4454,67 @@ export declare interface OAuthError {
     raw?: unknown;
 }
 
+/**
+ * Fixed bar that appears while the browser is offline and, by default, flashes
+ * a brief confirmation when the connection returns. Backed by {@link useOnline}
+ * — no props needed for the common case.
+ *
+ * Renders nothing while online (after any flash has elapsed), so it is safe to
+ * mount unconditionally at the app root.
+ *
+ * @example
+ * <OfflineIndicator position="top" />
+ */
+export declare function OfflineIndicator({ position, offlineLabel, onlineLabel, onlineFlashMs, className, children, ...props }: OfflineIndicatorProps): JSX.Element | null;
+
+export declare type OfflineIndicatorPosition = "top" | "bottom";
+
+export declare interface OfflineIndicatorProps extends HTMLAttributes<HTMLDivElement> {
+    /** Where to pin the fixed bar. Default `"bottom"`. */
+    position?: OfflineIndicatorPosition;
+    /** Message shown while offline. */
+    offlineLabel?: ReactNode;
+    /** Message flashed briefly when connectivity returns. */
+    onlineLabel?: ReactNode;
+    /**
+     * How long (ms) to keep the "back online" flash visible. `0` hides it
+     * entirely. Default `3000`.
+     */
+    onlineFlashMs?: number;
+    /** Override the offline body entirely (icon + label ignored). */
+    children?: ReactNode;
+}
+
+/** Handle returned by {@link persistQueryClientOffline}. */
+export declare interface OfflineQueryPersistence {
+    /**
+     * Load the persisted snapshot into the `QueryClient`. Call once on boot,
+     * before rendering queries, so cached data is available offline.
+     */
+    restore: () => Promise<void>;
+    /** Write the current cache snapshot immediately (bypassing the throttle). */
+    flush: () => Promise<void>;
+    /** Stop persisting and drop the pending write. */
+    unsubscribe: () => void;
+    /** Delete the persisted snapshot (e.g. on logout). */
+    clear: () => Promise<void>;
+}
+
+/** Options for {@link persistQueryClientOffline}. */
+export declare interface OfflineQueryPersistenceOptions {
+    /** The `QueryClient` to snapshot and restore. */
+    queryClient: QueryClient;
+    /** IndexedDB database name for the snapshot. Default `"TempestQueryCache"`. */
+    databaseName?: string;
+    /** Row key under which the snapshot is stored. Default `"tanstack-query"`. */
+    key?: string;
+    /**
+     * Minimum gap between snapshot writes, in ms — cache churn is coalesced into
+     * one trailing write per window. Default `1000`.
+     */
+    throttleMs?: number;
+}
+
 export declare interface OfflineStore<TItem, TKey extends string | number> {
     /** Insert or replace a record. */
     put: (item: TItem, owner?: string) => Promise<TKey>;
@@ -4293,6 +4592,23 @@ export declare interface OfflineSync<TPayload> {
     clearOutbox: () => Promise<void>;
     /** Reset the pull watermark (e.g. on logout / account switch). */
     resetWatermark: () => void;
+    /** Read the current reactive {@link SyncState} snapshot synchronously. */
+    getState: () => SyncState;
+    /**
+     * Subscribe to {@link SyncState} changes. The listener fires on every
+     * enqueue, flush transition and outbox clear.
+     *
+     * @param listener - Called with the new snapshot on each change.
+     * @returns An unsubscribe function.
+     */
+    subscribe: (listener: (state: SyncState) => void) => () => void;
+    /**
+     * Release resources held by the engine — currently the cross-tab
+     * `BroadcastChannel` when `crossTab` is enabled. Safe to call when none was
+     * opened. Optional in long-lived apps (the channel is reclaimed on tab
+     * close); call it in tests and on teardown.
+     */
+    dispose: () => void;
 }
 
 /**
@@ -4341,6 +4657,22 @@ export declare interface OfflineSyncConfig<TPayload, TRemote> {
      * non-browser environments). When it returns `false`, `flush` is skipped.
      */
     isOnline?: () => boolean;
+    /**
+     * Broadcast {@link SyncState} across browser tabs of the same origin via a
+     * `BroadcastChannel`, so every tab shows a coherent pending count / phase
+     * (e.g. one tab flushing drops the badge to zero everywhere). The outbox is
+     * already a shared IndexedDB; this only shares the in-memory state. Silently
+     * ignored where `BroadcastChannel` is unavailable. Default `false`.
+     *
+     * When the Web Locks API is available, `flush` is additionally coordinated
+     * *across* tabs: only one tab runs at a time and others skip while the lock
+     * is held (they pick up the result via the broadcast). Delivery should still
+     * be idempotent (upsert by client id). Without Web Locks, `flush` falls back
+     * to per-tab single-flight.
+     */
+    crossTab?: boolean;
+    /** Channel name when `crossTab` is on. Default `tempest-sync:${databaseName}`. */
+    broadcastChannelName?: string;
 }
 
 /** Offset-paginated response envelope (fastapi-pagination `Page[T]`). */
@@ -4431,6 +4763,16 @@ export declare interface OSRMBackendOptions {
     modeDurationFactors?: Partial<Record<TravelMode, number>>;
 }
 
+/** The outbox entry a mutation's variables map to. */
+export declare interface OutboxDraft<TPayload> {
+    /** The mutation kind. */
+    op: OutboxOp;
+    /** Primary key of the affected record. */
+    recordId: string;
+    /** Record snapshot for `create`/`update` (omit for `delete`). */
+    payload?: TPayload;
+}
+
 /**
  * A single queued mutation.
  *
@@ -4594,6 +4936,27 @@ export declare interface PermissionsFromTokenOptions {
     claim?: string;
 }
 
+/**
+ * Persist a TanStack `QueryClient` cache to IndexedDB (via
+ * {@link createOfflineStore}) and restore it on boot — so a reload or a cold
+ * offline start shows the last-known data instead of empty screens.
+ *
+ * Self-contained: uses `dehydrate`/`hydrate` from `@tanstack/react-query`
+ * directly, so no `@tanstack/react-query-persist-client` dependency is needed.
+ * Writes are throttled and subscribe to the query cache; call `unsubscribe` on
+ * teardown. Dexie is a peer dependency of the offline store — install it.
+ *
+ * @param options - The client plus storage/throttle configuration.
+ * @returns A handle with `restore`, `flush`, `clear` and `unsubscribe`.
+ *
+ * @example
+ * const persistence = persistQueryClientOffline({ queryClient });
+ * await persistence.restore(); // before first render
+ * // ... later, on logout:
+ * await persistence.clear();
+ */
+export declare function persistQueryClientOffline(options: OfflineQueryPersistenceOptions): OfflineQueryPersistence;
+
 export declare const PhoneInput: ForwardRefExoticComponent<Omit<InputProps, "value" | "onChange"> & {
 value: string;
 onChange: (value: string) => void;
@@ -4778,8 +5141,13 @@ export declare interface PostHogLike {
     reset?: () => void;
 }
 
-/** Linear progress bar with determinate / indeterminate modes. */
-export declare function Progress({ value, max, variant, indeterminate, showLabel, label, className, }: ProgressProps): JSX.Element;
+/**
+ * Linear progress bar with determinate / indeterminate modes.
+ *
+ * The `progressbar` role requires an accessible name: it comes from
+ * `aria-labelledby`, then explicit `aria-label`, then the visible `label`.
+ */
+export declare function Progress({ value, max, variant, indeterminate, showLabel, label, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className, }: ProgressProps): JSX.Element;
 
 export declare interface ProgressProps {
     /** Value between 0 and `max` (or 0-100 by default). Ignored when `indeterminate`. */
@@ -4792,6 +5160,14 @@ export declare interface ProgressProps {
     showLabel?: boolean;
     /** Optional left-aligned descriptor (e.g. "Enviando arquivo…"). */
     label?: string;
+    /**
+     * Accessible name for the bar. Defaults to `label` when that is set —
+     * provide it explicitly whenever the bar renders without a visible label,
+     * otherwise screen readers announce an unnamed progressbar.
+     */
+    "aria-label"?: string;
+    /** Id of an existing element that names the bar (alternative to `aria-label`). */
+    "aria-labelledby"?: string;
     className?: string;
 }
 
@@ -5007,6 +5383,42 @@ export declare interface RefreshIndicatorProps {
     className?: string;
 }
 
+/**
+ * Request a Periodic Background Sync registration.
+ *
+ * Checks the `periodic-background-sync` permission first and only registers
+ * when it is granted, so calling this unconditionally is safe. The browser
+ * ultimately decides whether and how often the `periodicsync` event fires.
+ *
+ * @param options - The registration, tag and interval.
+ * @returns `true` when the periodic sync was registered, else `false`
+ *   (unsupported, permission denied, or registration threw).
+ *
+ * @example
+ * const reg = await navigator.serviceWorker.ready;
+ * await registerPeriodicSync({ registration: reg, minIntervalMinutes: 360 });
+ */
+export declare function registerPeriodicSync(options: RegisterPeriodicSyncOptions): Promise<boolean>;
+
+/**
+ * Main-thread helper to register a Periodic Background Sync, the counterpart to
+ * the `periodicsync` listener installed by `installBackgroundSync`. Chrome-only
+ * and gated behind the `periodic-background-sync` permission plus a site
+ * engagement heuristic; degrades to a no-op (returns `false`) everywhere else.
+ */
+/** Options for {@link registerPeriodicSync}. */
+export declare interface RegisterPeriodicSyncOptions {
+    /** The active service-worker registration. */
+    registration: ServiceWorkerRegistration;
+    /** Sync tag; must match `installBackgroundSync`'s `periodicSyncTag`. Default `tempest-bg-sync-periodic`. */
+    tag?: string;
+    /**
+     * Minimum interval between runs, in minutes. The browser treats this as a
+     * floor and may space runs out much further. Default `720` (12h).
+     */
+    minIntervalMinutes?: number;
+}
+
 /**
  * Register a service worker with consistent update-detection wiring.
  *
@@ -5014,6 +5426,11 @@ export declare interface RefreshIndicatorProps {
  * app keeps full control over the SW file — this helper only handles the
  * boilerplate around `register()` and `updatefound`.
  *
+ * With `autoUpdate` enabled it additionally polls `registration.update()` on
+ * an interval and (by default) reloads the page when a freshly activated worker
+ * takes control — a framework-agnostic equivalent of `vite-plugin-pwa`'s
+ * auto-update client, implemented directly on `navigator.serviceWorker`.
+ *
  * @returns The registration when it succeeds, or `null` when unsupported.
  */
 export declare function registerServiceWorker(options: RegisterServiceWorkerOptions): Promise<ServiceWorkerRegistration | null>;
@@ -5033,6 +5450,27 @@ export declare interface RegisterServiceWorkerOptions {
     onUpdate?: (waiting: ServiceWorker, registration: ServiceWorkerRegistration) => void;
     /** Called on registration failure. */
     onError?: (error: unknown) => void;
+    /**
+     * When `true`, poll the server for a fresh service worker on an interval
+     * (see {@link RegisterServiceWorkerOptions.updateIntervalMs}) and, unless
+     * {@link RegisterServiceWorkerOptions.reloadOnActivate} is disabled, reload
+     * the page as soon as a new worker takes control. Mirrors the auto-update
+     * behaviour of `vite-plugin-pwa` without depending on it. Default `false`.
+     */
+    autoUpdate?: boolean;
+    /**
+     * How often, in ms, to call `registration.update()` while `autoUpdate` is
+     * on. Browsers already re-check roughly every 24h; an hourly poll keeps
+     * long-lived sessions current without flooding the network. Default
+     * `3600000` (1 hour).
+     */
+    updateIntervalMs?: number;
+    /**
+     * When `autoUpdate` is on, reload the page once a new worker takes control
+     * (`controllerchange`), guarded against reload loops. Set to `false` to
+     * keep polling but leave the reload to the host app. Default `true`.
+     */
+    reloadOnActivate?: boolean;
 }
 
 /**
@@ -5069,6 +5507,24 @@ export declare interface RelativeTimeProps extends HTMLAttributes<HTMLTimeElemen
     locale?: "pt" | "en";
 }
 
+/**
+ * Build an `applyOptimistic` that removes the entry matching the item's id
+ * (by `idField`) from the list. For `delete` mutations, pass variables carrying
+ * at least the id field.
+ *
+ * @typeParam T - The list item shape.
+ * @param idField - The identity field. Default `"id"`.
+ * @returns An `(current, item) => T[]` patcher for a list cache.
+ *
+ * @example
+ * useOfflineMutation<{ id: string }, Note[], Note>({
+ *     sync, queryKey: ["notes"],
+ *     toEntry: ({ id }) => ({ op: "delete", recordId: id }),
+ *     applyOptimistic: removeById(),
+ * });
+ */
+export declare function removeById<T, V extends Partial<Record<keyof T, unknown>> = T>(idField?: keyof T): (current: T[] | undefined, item: V) => T[];
+
 export declare interface ReorderPayload {
     from: number;
     to: number;
@@ -5079,6 +5535,17 @@ export declare interface RequestOptions extends Omit<RequestInit, "body"> {
     params?: Record<string, string | number | boolean | undefined | null>;
 }
 
+/**
+ * Ask the browser to make this origin's storage persistent, so IndexedDB and
+ * the Cache Storage are not silently evicted under disk pressure — essential
+ * for durable offline-first data.
+ *
+ * The browser may grant silently, prompt, or deny based on engagement heuristics.
+ *
+ * @returns `true` when storage is (now or already) persisted, else `false`.
+ */
+export declare function requestPersistentStorage(): Promise<boolean>;
+
 /**
  * A two-pane split layout with a draggable divider. The first pane is sized via
  * `flex-basis` as a percentage; the second pane fills the rest. Drag the divider
@@ -5410,6 +5877,33 @@ export declare interface SentryLike {
  */
 export declare function share(payload: SharePayload): Promise<ShareResult>;
 
+/**
+ * Try the Web Share API with the given `Blob` as a file; fall back to a
+ * download anchor when the browser cannot share files (desktop Firefox, older
+ * iOS Safari, etc.).
+ *
+ * A companion to {@link share} for the common "export a generated artifact"
+ * flow: on mobile it opens the native share sheet, and everywhere else it
+ * triggers a plain download. Returns early when the user shares or cancels the
+ * dialog; otherwise it downloads.
+ *
+ * @param blob - The binary payload to share or download.
+ * @param fileName - The file name presented to the user.
+ * @param options - Optional `title` for the share dialog.
+ * @returns A promise that resolves once the share or download completes.
+ *
+ * @example
+ * const zip = new Blob([bytes], { type: "application/zip" });
+ * await shareOrDownloadBlob(zip, "export.zip");
+ */
+export declare function shareOrDownloadBlob(blob: Blob, fileName: string, options?: ShareOrDownloadOptions): Promise<void>;
+
+/** Options for {@link shareOrDownloadBlob}. */
+export declare interface ShareOrDownloadOptions {
+    /** Title passed to the Web Share dialog. Defaults to the file name. */
+    title?: string;
+}
+
 export declare interface SharePayload {
     title?: string;
     text?: string;
@@ -5731,6 +6225,15 @@ export declare const storage: {
     remove(key: string): void;
 };
 
+/** Raw usage/quota reading from the Storage API, in bytes. */
+declare interface StorageEstimate_2 {
+    /** Bytes currently used by this origin, or `null` when unknown. */
+    usage: number | null;
+    /** Total bytes available to this origin, or `null` when unknown. */
+    quota: number | null;
+}
+export { StorageEstimate_2 as StorageEstimate }
+
 export { SubmitHandler }
 
 /** Toggle switch backed by a checkbox input. Accessible via keyboard. */
@@ -5741,6 +6244,17 @@ export declare interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputE
     wrapperClassName?: string;
 }
 
+/**
+ * Coarse lifecycle phase of the sync engine, surfaced through
+ * {@link OfflineSync.getState} / {@link OfflineSync.subscribe} for reactive UI.
+ *
+ * - `"idle"` — nothing in flight and the last run (if any) fully succeeded.
+ * - `"syncing"` — a `flush` run is currently in progress.
+ * - `"offline"` — the last run was skipped because the device was offline.
+ * - `"error"` — the last run left at least one entry queued after a failure.
+ */
+export declare type SyncPhase = "idle" | "syncing" | "offline" | "error";
+
 /** Outcome of a single {@link OfflineSync.flush} run. */
 export declare interface SyncRunSummary {
     /** The trigger passed to `flush`. */
@@ -5753,8 +6267,91 @@ export declare interface SyncRunSummary {
     durationMs: number;
     /** `true` when the run was skipped because the device was offline. */
     skipped: boolean;
+    /** Last delivery error message seen this run, or `null` when none failed. */
+    lastError: string | null;
+}
+
+/**
+ * Immutable snapshot of the engine's reactive state. A fresh object is emitted
+ * to subscribers on every change, so it is safe to use as a
+ * `useSyncExternalStore` snapshot (reference equality signals "no change").
+ */
+export declare interface SyncState {
+    /** Current lifecycle phase. */
+    phase: SyncPhase;
+    /** Number of mutations still queued in the outbox. */
+    pending: number;
+    /** Summary of the most recent `flush` run, or `null` before the first. */
+    lastSummary: SyncRunSummary | null;
+    /** Message of the most recent delivery failure, or `null`. */
+    lastError: string | null;
+    /** Epoch ms of the last non-skipped run, or `null` before the first. */
+    lastSyncedAt: number | null;
+}
+
+/**
+ * Compact status snapshot for a status badge/pill. Prefer this over
+ * {@link useOfflineSync} when a component only needs to *display* status and
+ * does not trigger flushes itself.
+ */
+export declare interface SyncStatus {
+    /** The dominant tone to render. */
+    tone: SyncTone;
+    /** Number of mutations still queued. */
+    pending: number;
+    /** `true` while a flush run is in progress. */
+    syncing: boolean;
+    /** `true` when the last run was skipped for being offline. */
+    offline: boolean;
+    /** Message of the most recent delivery failure, or `null`. */
+    lastError: string | null;
 }
 
+/**
+ * Compact pill showing offline-sync status: a tone-colored icon plus a label
+ * and optional pending count.
+ *
+ * Two modes: pass `sync` to have the badge observe an engine via
+ * `useSyncStatus` (zero wiring), or pass an explicit `tone` (+ `pending`) to
+ * keep it presentational and testable without IndexedDB.
+ *
+ * @example
+ * // Connected — auto-wires the engine:
+ * <SyncStatusBadge sync={notesSync} />
+ *
+ * // Presentational — you own the state:
+ * const { tone, pending } = useSyncStatus(notesSync);
+ * <SyncStatusBadge tone={tone} pending={pending} />
+ */
+export declare function SyncStatusBadge({ sync, ...rest }: SyncStatusBadgeProps): JSX.Element;
+
+export declare interface SyncStatusBadgeProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children"> {
+    /**
+     * The dominant tone. Required when `sync` is not passed. Ignored when `sync`
+     * is passed (the tone is derived from the engine).
+     */
+    tone?: SyncTone;
+    /**
+     * An `OfflineSync` engine to observe directly. When set, the badge wires
+     * `useSyncStatus` internally, so `tone` and `pending` come from the engine.
+     */
+    sync?: OfflineSync<unknown>;
+    /** Number of queued mutations, appended to the label when `> 0`. */
+    pending?: number;
+    /** Override the per-tone label text. */
+    labels?: Partial<Record<SyncTone, string>>;
+    /** Show the pending count next to the label. Default `true`. */
+    showPending?: boolean;
+    /** Render only the icon (no text). Default `false`. */
+    iconOnly?: boolean;
+}
+
+/**
+ * Presentation-ready tone for a sync status indicator. Collapses the engine's
+ * {@link SyncState} into the single most relevant signal for a badge/pill.
+ */
+export declare type SyncTone = "idle" | "syncing" | "pending" | "offline" | "error";
+
 /**
  * Why a sync run was triggered. The listed values are the common ones; any
  * string is accepted so apps can add their own telemetry labels.
@@ -6214,6 +6811,9 @@ export declare function ToggleGroup({ type, value, defaultValue, onValueChange,
  * A single selectable item inside a {@link ToggleGroup}. Reads and updates the
  * group's shared state through context.
  *
+ * Icon-only items need an explicit `aria-label` (forwarded to the button):
+ * an SVG child gives screen readers nothing to announce.
+ *
  * @param props - {@link ToggleGroupItemProps}.
  * @returns A `role="button"` element exposing its state via `aria-pressed`.
  */
@@ -6437,6 +7037,36 @@ export declare function unprojectMercator(point: MercatorPoint): Coordinate;
  */
 export declare function unregisterAllServiceWorkers(): Promise<number>;
 
+/**
+ * Fixed toast prompting the user to activate a freshly installed service
+ * worker. Presentational — pair with {@link useServiceWorkerUpdate}, feeding
+ * `updateAvailable` to `open` and `applyUpdate` to `onUpdate`.
+ *
+ * Renders nothing while `open` is `false`.
+ *
+ * @example
+ * const { updateAvailable, applyUpdate } = useServiceWorkerUpdate({ url: "/sw.js" });
+ * <UpdatePrompt open={updateAvailable} onUpdate={applyUpdate} />
+ */
+export declare function UpdatePrompt({ open, onUpdate, onDismiss, message, actionLabel, position, className, ...props }: UpdatePromptProps): JSX.Element | null;
+
+export declare type UpdatePromptPosition = "top" | "bottom";
+
+export declare interface UpdatePromptProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** Whether the prompt is visible. Feed from `useServiceWorkerUpdate().updateAvailable`. */
+    open: boolean;
+    /** Called when the user confirms the update. Wire to `applyUpdate`. */
+    onUpdate: () => void;
+    /** Called when the user dismisses the prompt. Omit to hide the dismiss button. */
+    onDismiss?: () => void;
+    /** Body message. */
+    message?: ReactNode;
+    /** Confirm button label. Default `"Atualizar"`. */
+    actionLabel?: string;
+    /** Where to pin the fixed toast. Default `"bottom"`. */
+    position?: UpdatePromptPosition;
+}
+
 /** Variables accepted by the update mutation. */
 export declare interface UpdateVariables {
     /** The record id to update. */
@@ -6488,6 +7118,30 @@ export declare interface UploadWithProgressOptions {
     requestId?: () => string;
 }
 
+/**
+ * Ready-made `applyOptimistic` builders for {@link useOfflineMutation} over a
+ * list-shaped query cache (`TData = T[]`). They cover the two most common
+ * optimistic edits — insert-or-update and remove — so callers stop hand-writing
+ * the array spread. Both compare records by an id field (`"id"` by default) and
+ * treat the mutation variables as the record itself.
+ */
+/**
+ * Build an `applyOptimistic` that inserts the item when absent or shallow-merges
+ * it into the existing entry (matched by `idField`). New items append to the end.
+ *
+ * @typeParam T - The list item shape.
+ * @param idField - The identity field. Default `"id"`.
+ * @returns An `(current, item) => T[]` patcher for a list cache.
+ *
+ * @example
+ * useOfflineMutation<Note, Note[], Note>({
+ *     sync, queryKey: ["notes"],
+ *     toEntry: (n) => ({ op: "update", recordId: n.id, payload: n }),
+ *     applyOptimistic: upsertById(),
+ * });
+ */
+export declare function upsertById<T>(idField?: keyof T): (current: T[] | undefined, item: T) => T[];
+
 /**
  * Convert a base64url-encoded VAPID public key into the `Uint8Array` format
  * required by `PushManager.subscribe({ applicationServerKey })`.
@@ -6880,7 +7534,17 @@ export { UseFormReturn }
 
 export { useFormState }
 
-/** React hook around the Geolocation API. */
+/**
+ * React hook around the Geolocation API.
+ *
+ * The effect depends on the individual `PositionOptions` fields instead of the
+ * rest object, which is a new reference on every render and would restart the
+ * watch continuously. `exhaustive-deps` is silenced there because those fields
+ * are the whole of what the effect reads from it.
+ *
+ * @param options - Geolocation options plus `watch` and `disabled` switches.
+ * @returns The latest position, error and loading state.
+ */
 export declare function useGeolocation(options?: UseGeolocationOptions): GeolocationState;
 
 export declare interface UseGeolocationOptions extends PositionOptions {
@@ -6912,6 +7576,75 @@ export declare function useI18n(): I18nContextValue;
  */
 export declare function useIdle(timeout?: number): boolean;
 
+/**
+ * React hook that resolves how (and whether) to offer PWA installation.
+ *
+ * It caches the `beforeinstallprompt` event, detects iOS/iPadOS, detects
+ * Android Chromium forks that lack the prompt API, detects standalone display
+ * mode, and applies a decline cooldown persisted in `localStorage`. The
+ * resulting `method` tells the UI which install affordance to render.
+ *
+ * The decline persistence is pluggable through
+ * {@link UseInstallPromptOptions.declineStorageKey} and
+ * {@link UseInstallPromptOptions.declineCooldownMs} — no app-specific storage
+ * layer is required, and it is SSR-guarded.
+ *
+ * @param options - Optional storage key, cooldown, and fallback-delay tuning.
+ * @returns The install state plus `install()` and `recordDecline()` actions.
+ *
+ * @example
+ * const { method, install } = useInstallPrompt();
+ * if (method === "native") return <button onClick={install}>Install</button>;
+ */
+export declare function useInstallPrompt(options?: UseInstallPromptOptions): UseInstallPromptResult;
+
+/** Options for {@link useInstallPrompt}. */
+export declare interface UseInstallPromptOptions {
+    /**
+     * `localStorage` key used to persist the decline timestamp. Defaults to
+     * `"tempest:install-declined-at"`.
+     */
+    declineStorageKey?: string;
+    /**
+     * How long, in ms, the install CTA stays hidden after the user declines.
+     * Defaults to 7 days.
+     */
+    declineCooldownMs?: number;
+    /**
+     * How long, in ms, to wait for a `beforeinstallprompt` event before
+     * resolving to the `"manual"` method. Defaults to `3000`.
+     */
+    manualFallbackDelayMs?: number;
+}
+
+/** State returned by {@link useInstallPrompt}. */
+export declare interface UseInstallPromptResult {
+    /** The cached `beforeinstallprompt` event, or `null` when unavailable. */
+    deferredPrompt: BeforeInstallPromptEvent | null;
+    /** True when the app can be installed through any supported method. */
+    canInstall: boolean;
+    /** True when running on iOS/iPadOS Safari. */
+    isIOS: boolean;
+    /** True when already running as an installed PWA. */
+    isStandalone: boolean;
+    /** True when the browser is an Android Chromium fork with no prompt API. */
+    isManualAndroid: boolean;
+    /** True when no `beforeinstallprompt` arrived within the timeout window. */
+    promptTimedOut: boolean;
+    /** The resolved install strategy the UI should follow. */
+    method: InstallMethod;
+    /** An `intent://` URL to re-open the page in Chrome on Android, else `null`. */
+    openInChromeIntent: string | null;
+    /**
+     * Triggers the native prompt.
+     *
+     * @returns `true` when the user accepted the install, `false` otherwise.
+     */
+    install: () => Promise<boolean>;
+    /** Records that the user declined the CTA, starting the cooldown window. */
+    recordDecline: () => void;
+}
+
 /**
  * Track whether the referenced element intersects the viewport. Useful for
  * lazy-loading images, "load more" sentinels, and animation triggers.
@@ -6945,6 +7678,12 @@ export declare function useIsFirstRender(): boolean;
  * Bind a global keyboard shortcut. Supports modifier combinations and a
  * cross-OS `mod` key (Ctrl on Windows/Linux, Cmd on macOS).
  *
+ * The effect depends on the individual `shortcut` fields rather than on the
+ * object itself: callers pass an inline literal (`{ key: "k", mod: true }`),
+ * which is a fresh reference on every render and would otherwise tear down and
+ * re-add the listener each time. `exhaustive-deps` is silenced for that line
+ * because the destructured fields are the complete dependency set.
+ *
  * @example
  * useKeyboardShortcut({ key: "k", mod: true }, () => openSearch());
  */
@@ -7006,6 +7745,52 @@ export { useLocation }
  */
 export declare function useLongPress<T extends HTMLElement>(ref: RefObject<T | null>, fn: () => void, options?: UseLongPressOptions): void;
 
+/**
+ * Returns DOM event handlers that detect a long press (touch or mouse hold)
+ * and invoke `onLongPress` once after `delayMs`.
+ *
+ * Cancels on touch movement or pointer release. Also wires `contextmenu` to
+ * fire `onLongPress` immediately so a right-click on desktop opens selection
+ * mode the same way an Android long-press does on mobile.
+ *
+ * The hook does not `preventDefault` on the underlying click — the consumer
+ * decides whether the subsequent click should still fire. Track that with the
+ * returned `wasLongPress()` guard to tell "long-press fired" apart from a
+ * "regular click".
+ *
+ * Unlike {@link useLongPress}, which attaches pointer listeners to a `ref`,
+ * this variant returns handler props you spread directly onto an element and
+ * exposes a `wasLongPress()` guard.
+ *
+ * @param onLongPress - Callback invoked once the hold threshold is reached.
+ * @param options - Optional `delayMs` and `disabled` flags.
+ * @returns The spreadable handlers plus a `wasLongPress()` guard.
+ *
+ * @example
+ * const longPress = useLongPressHandlers(() => enterSelectionMode(), { delayMs: 600 });
+ * <button {...longPress} onClick={() => { if (!longPress.wasLongPress()) navigate(); }}>
+ *   Item
+ * </button>
+ */
+export declare function useLongPressHandlers(onLongPress: () => void, options?: UseLongPressHandlersOptions): UseLongPressHandlersResult;
+
+/** Options accepted by {@link useLongPressHandlers}. */
+export declare interface UseLongPressHandlersOptions {
+    /** Hold duration in ms before `onLongPress` fires. Defaults to `500`. */
+    delayMs?: number;
+    /** When `true`, the hook is inert and every handler is a no-op. */
+    disabled?: boolean;
+}
+
+/** Return shape of {@link useLongPressHandlers}. */
+export declare type UseLongPressHandlersResult = LongPressHandlers & {
+    /**
+     * Reads whether the most recent interaction fired a long-press. Use it in
+     * the element's `onClick` to suppress the click that follows a long-press.
+     */
+    wasLongPress: () => boolean;
+};
+
 export declare interface UseLongPressOptions {
     /** Press duration in ms. Default `500`. */
     delay?: number;
@@ -7115,6 +7900,126 @@ export declare interface UseOAuthCallbackResult<T> {
  */
 export declare function useObjectUrl(blob: Blob | null | undefined): string | null;
 
+/**
+ * Optimistic mutation that writes to an {@link OfflineSync} outbox instead of
+ * hitting the network directly, bridging the sync engine and TanStack Query.
+ *
+ * On `mutate` it enqueues the entry, optimistically patches the given query
+ * cache key and kicks a flush; if the enqueue itself throws, the cache is
+ * rolled back to its previous value. Server delivery happens later inside the
+ * engine's flush loop, so the UI updates instantly and survives reloads and
+ * offline periods.
+ *
+ * @typeParam TVariables - The `mutate(variables)` input shape.
+ * @typeParam TData - The cached query data optimistically patched.
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ * @param options - Engine, variables→entry mapping and cache wiring.
+ * @returns The TanStack {@link UseMutationResult}; the mutation resolves to the
+ *   generated outbox entry id.
+ *
+ * @example
+ * const addNote = useOfflineMutation({
+ *     sync: notesSync,
+ *     queryKey: ["notes"],
+ *     toEntry: (note: Note) => ({ op: "create", recordId: note.id, payload: note }),
+ *     applyOptimistic: (current: Note[] = [], note) => [...current, note],
+ * });
+ * addNote.mutate(newNote);
+ */
+export declare function useOfflineMutation<TVariables, TData = unknown, TPayload = unknown>(options: UseOfflineMutationOptions<TVariables, TData, TPayload>): UseMutationResult<string, Error, TVariables, MutationContext<TData>>;
+
+/**
+ * Configuration for {@link useOfflineMutation}.
+ *
+ * @typeParam TVariables - The `mutate(variables)` input shape.
+ * @typeParam TData - The cached query data optimistically patched.
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ */
+export declare interface UseOfflineMutationOptions<TVariables, TData, TPayload> {
+    /** The engine the mutation enqueues into. */
+    sync: OfflineSync<TPayload>;
+    /** Map `mutate` variables into an outbox entry. */
+    toEntry: (variables: TVariables) => OutboxDraft<TPayload>;
+    /**
+     * Query key to optimistically patch and (optionally) invalidate. Omit to
+     * only enqueue without touching the React Query cache.
+     */
+    queryKey?: QueryKey;
+    /**
+     * Produce the next cached value from the current one and the variables.
+     * Runs in `onMutate`; the previous value is restored automatically if the
+     * enqueue throws. Requires `queryKey`.
+     */
+    applyOptimistic?: (current: TData | undefined, variables: TVariables) => TData;
+    /**
+     * Trigger a flush after enqueueing. `true` (default) uses
+     * `"after-mutation"`; pass a custom {@link SyncTrigger} string, or `false`
+     * to leave flushing to the caller / auto-flush hooks.
+     */
+    flush?: boolean | SyncTrigger;
+    /** Invalidate `queryKey` in `onSettled` so a later read refetches. Default `false`. */
+    invalidate?: boolean;
+}
+
+/**
+ * Subscribe a React component to an {@link OfflineSync} engine.
+ *
+ * Re-renders whenever the engine's {@link SyncState} changes (enqueue, flush
+ * transition, outbox clear) via `useSyncExternalStore`, and optionally wires
+ * auto-flush on mount, on the `online` event and on an interval. The engine
+ * itself is created once by the app and passed in — the hook never owns it, so
+ * multiple components can observe the same queue.
+ *
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ * @param sync - The engine returned by `createOfflineSync`.
+ * @param options - Auto-flush triggers.
+ * @returns The reactive state merged with `enqueue`/`flush` actions.
+ *
+ * @example
+ * const { pending, syncing, phase, flush } = useOfflineSync(notesSync, {
+ *     flushOnMount: true,
+ *     intervalMs: 30_000,
+ * });
+ * return <SyncStatusBadge pending={pending} syncing={syncing} phase={phase} />;
+ */
+export declare function useOfflineSync<TPayload>(sync: OfflineSync<TPayload>, options?: UseOfflineSyncOptions): UseOfflineSyncResult<TPayload>;
+
+/**
+ * Options for {@link useOfflineSync}. All auto-flush triggers are opt-in except
+ * `flushOnOnline`, which defaults to `true` so the app catches up the moment
+ * connectivity returns.
+ */
+export declare interface UseOfflineSyncOptions {
+    /** Flush once when the component mounts (trigger `"boot"`). Default `false`. */
+    flushOnMount?: boolean;
+    /**
+     * Flush when the browser fires the `online` event (trigger
+     * `"online-event"`). Default `true`.
+     */
+    flushOnOnline?: boolean;
+    /**
+     * Flush on this interval in milliseconds (trigger `"interval"`). `0`
+     * disables the timer. Default `0`.
+     */
+    intervalMs?: number;
+}
+
+/**
+ * Reactive view of an {@link OfflineSync} engine, plus its imperative actions.
+ * Extends {@link SyncState} so `phase`, `pending`, `lastSummary`, `lastError`
+ * and `lastSyncedAt` are read directly off the result.
+ *
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ */
+export declare interface UseOfflineSyncResult<TPayload> extends SyncState {
+    /** `true` while a flush run is in progress (`phase === "syncing"`). */
+    syncing: boolean;
+    /** Queue a mutation. Mirrors {@link OfflineSync.enqueue}. */
+    enqueue: (op: OutboxOp, recordId: string, payload?: TPayload) => Promise<string>;
+    /** Trigger a flush run. Mirrors {@link OfflineSync.flush}. */
+    flush: (trigger?: SyncTrigger) => Promise<SyncRunSummary>;
+}
+
 /**
  * Query a single record by id through the active {@link useDataProvider}.
  *
@@ -7133,10 +8038,40 @@ export declare type UseOneOptions<T> = Omit<UseQueryOptions<T, Error, T>, "query
 };
 
 /**
- * Track the browser's `navigator.onLine` value and re-render on changes.
- * Returns `true` during SSR (assumption: server is online).
+ * Track connectivity and re-render on changes.
+ *
+ * With no options it mirrors `navigator.onLine` (assuming online during SSR and
+ * before the first event). Pass `pingUrl` to additionally probe real
+ * reachability — the browser's `onLine` flag lies behind captive portals and
+ * dead links, so the probe downgrades the result to `false` when the network is
+ * unusable even though `navigator.onLine` is `true`.
+ *
+ * @param options - Optional reachability-probe configuration.
+ * @returns `true` when the device is online (and reachable, when probing).
+ *
+ * @example
+ * const online = useOnline(); // navigator.onLine only
+ * const reallyOnline = useOnline({ pingUrl: "/health", intervalMs: 15_000 });
+ */
+export declare function useOnline(options?: UseOnlineOptions): boolean;
+
+/**
+ * Options for {@link useOnline}. Omit them for the cheap `navigator.onLine`
+ * behaviour; pass `pingUrl` to add a real-reachability probe on top.
  */
-export declare function useOnline(): boolean;
+export declare interface UseOnlineOptions {
+    /**
+     * URL to probe for real connectivity. `navigator.onLine` reports `true`
+     * behind a captive portal or when the machine has a link but no internet;
+     * a periodic `HEAD` to this URL catches those cases. When set, the result
+     * is `navigator.onLine && lastProbeSucceeded`.
+     */
+    pingUrl?: string;
+    /** How often to probe, in ms. Default `30000`. */
+    intervalMs?: number;
+    /** Abort a probe after this many ms and treat it as offline. Default `5000`. */
+    timeoutMs?: number;
+}
 
 /**
  * Offset-pagination hook over TanStack Query for the fastapi-pagination /
@@ -7383,6 +8318,52 @@ export declare function useScrollLock(active: boolean): void;
 
 export { useSearchParams }
 
+/**
+ * Register a service worker and expose a user-driven update flow.
+ *
+ * Wraps {@link registerServiceWorker}: when a fresh worker finishes installing
+ * while the page is still controlled by the old one, `updateAvailable` flips to
+ * `true`. Call `applyUpdate` — typically from an "atualizar" toast — to tell the
+ * waiting worker to activate and reload the page once it takes control.
+ *
+ * Skips cleanly when the runtime has no service-worker support (`registration`
+ * stays `null`, `updateAvailable` stays `false`).
+ *
+ * @param options - Registration options (`url` required); `autoUpdate` should
+ *   stay off so the reload is user-confirmed.
+ * @returns The update state and `applyUpdate` action.
+ *
+ * @example
+ * const { updateAvailable, applyUpdate } = useServiceWorkerUpdate({ url: "/sw.js" });
+ * return (
+ *     <UpdatePrompt open={updateAvailable} onUpdate={applyUpdate} />
+ * );
+ */
+export declare function useServiceWorkerUpdate(options: UseServiceWorkerUpdateOptions): UseServiceWorkerUpdateResult;
+
+/**
+ * Options for {@link useServiceWorkerUpdate}. Mirrors the registration options
+ * minus the callbacks the hook owns internally (`onUpdate`); `onReady` and
+ * `onError` still pass through for host-side logging.
+ *
+ * Leave `autoUpdate` off (the default): this hook exists to hand the reload
+ * decision to the user, so a silent auto-reload would defeat the prompt.
+ */
+export declare type UseServiceWorkerUpdateOptions = Omit<RegisterServiceWorkerOptions, "onUpdate">;
+
+/** Reactive service-worker update state plus the apply action. */
+export declare interface UseServiceWorkerUpdateResult {
+    /** `true` once a new worker has installed and is waiting to activate. */
+    updateAvailable: boolean;
+    /**
+     * Activate the waiting worker and reload the page once it takes control.
+     * No-op when no update is waiting.
+     */
+    applyUpdate: () => void;
+    /** The active registration, or `null` before it resolves / when unsupported. */
+    registration: ServiceWorkerRegistration | null;
+}
+
 /**
  * Reactive `Set` wrapper. Mutating via `add` / `delete` / `clear` / `toggle`
  * triggers a re-render and yields a fresh `set` reference each time.
@@ -7410,6 +8391,50 @@ export declare interface UseSetResult<T> {
  */
 export declare function useStableCallback<TArgs extends unknown[], TReturn>(callback: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
 
+/**
+ * Track the origin's storage usage, quota and persistence flag, refreshing on
+ * demand. Pair with {@link requestPersistentStorage} to surface a "usando X de
+ * Y MB" meter and a "tornar armazenamento permanente" action.
+ *
+ * @param options - `pollMs` re-reads the estimate on an interval (`0` = off,
+ *   the default).
+ * @returns The reactive storage state and actions.
+ *
+ * @example
+ * const { usage, quota, ratio, persisted, requestPersist } = useStorageEstimate();
+ * return <Meter value={ratio ?? 0} onClick={requestPersist} />;
+ */
+export declare function useStorageEstimate(options?: {
+    pollMs?: number;
+}): UseStorageEstimateResult;
+
+/** Reactive storage-quota state exposed by {@link useStorageEstimate}. */
+export declare interface UseStorageEstimateResult extends StorageEstimate_2 {
+    /** `true` when the Storage API is available. */
+    supported: boolean;
+    /** `usage / quota` in `[0, 1]`, or `null` when either value is unknown. */
+    ratio: number | null;
+    /** Whether storage is persisted, `null` before the first read / unsupported. */
+    persisted: boolean | null;
+    /** `true` during the initial read or a `refresh`. */
+    loading: boolean;
+    /** Re-read usage/quota and the persisted flag from the browser. */
+    refresh: () => Promise<void>;
+    /** Request persistent storage; refreshes state and returns the outcome. */
+    requestPersist: () => Promise<boolean>;
+}
+
+/**
+ * Subscribe to an {@link OfflineSync} engine and return a display-only
+ * {@link SyncStatus}. A thin read-only companion to {@link useOfflineSync},
+ * intended to feed a `<SyncStatusBadge>` without exposing flush actions.
+ *
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ * @param sync - The engine returned by `createOfflineSync`.
+ * @returns The compact status snapshot.
+ */
+export declare function useSyncStatus<TPayload>(sync: OfflineSync<TPayload>): SyncStatus;
+
 /**
  * Access the active telemetry adapter. Returns `null` when no provider is
  * mounted (calls are silently dropped — useful for unit tests).
@@ -8043,6 +9068,32 @@ export declare type WithSelectors<S> = S extends {
  */
 export declare function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
 
+/**
+ * Write a minimal single-sheet Office Open XML (`.xlsx`) workbook and return
+ * its bytes. No extra dependency beyond `fflate` — the archive is assembled and
+ * deflated in-process.
+ *
+ * The output is UTF-8 throughout, so accents round-trip in
+ * Excel/LibreOffice/Google Sheets without the BOM-detection fragility that
+ * plagues CSV exports. The XML stays compact: inline strings (no shared-string
+ * table), no styles, no merged cells. Numeric cells use the native `"n"` type
+ * so spreadsheets recognise them as numbers; `null` renders as an empty cell.
+ *
+ * @param headers - Column headers written as the first row.
+ * @param rows - Data rows; each value is a string, a number, or `null` (empty).
+ * @returns The `.xlsx` file contents as a `Uint8Array`.
+ *
+ * @example
+ * const bytes = writeXlsx(
+ *   ["Name", "Score"],
+ *   [["Ada", 99], ["Alan", null]],
+ * );
+ * const blob = new Blob([bytes], {
+ *   type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+ * });
+ */
+export declare function writeXlsx(headers: readonly string[], rows: readonly (readonly (string | number | null)[])[]): Uint8Array;
+
 /**
  * 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