tempest-react-sdk 0.20.0 → 0.22.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.
@@ -1531,6 +1561,44 @@ export declare interface CreateLoggerOptions {
  */
 export declare function createOfflineStore<TItem, TKey extends string | number = string>(config: OfflineStoreConfig<TItem>): OfflineStore<TItem, TKey>;
 
+/**
+ * Create an offline-first sync engine over an IndexedDB outbox.
+ *
+ * The engine drains queued mutations to the server (`deliver`) and pulls the
+ * server delta back (`pullPage` + `applyRemote`), advancing a watermark so each
+ * run only fetches what changed. `flush` is single-flight and skips cleanly
+ * while offline; failed deliveries stay queued with their attempt count bumped.
+ *
+ * Dexie is an **optional peer dependency** (via {@link createOfflineStore}) —
+ * install it (`npm i dexie`) when you use this engine.
+ *
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ * @typeParam TRemote - Server item shape returned by `pullPage`.
+ * @param config - Transport callbacks + outbox/watermark configuration.
+ * @returns The sync handle (`enqueue`, `flush`, `pendingCount`, …).
+ *
+ * @example
+ * const sync = createOfflineSync<Note, NoteDto>({
+ *     databaseName: "NotesOutbox",
+ *     watermark: { storageKey: "notes.watermark" },
+ *     deliver: async (entry) => {
+ *         if (entry.op === "delete") return api.remove(entry.recordId);
+ *         await api.upsert(entry.recordId, entry.payload!);
+ *     },
+ *     pullPage: async (since, cursor) => {
+ *         const page = await api.changes(since, cursor);
+ *         return { items: page.items, nextCursor: page.next, serverTime: page.now };
+ *     },
+ *     applyRemote: async (dto) => {
+ *         if (dto.deleted) return localStore.remove(dto.id);
+ *         await localStore.save(fromDto(dto));
+ *     },
+ * });
+ * await sync.enqueue("create", note.id, note);
+ * await sync.flush("after-mutation");
+ */
+export declare function createOfflineSync<TPayload = unknown, TRemote = unknown>(config: OfflineSyncConfig<TPayload, TRemote>): OfflineSync<TPayload>;
+
 /**
  * Build a {@link RoutingBackend} backed by an OSRM server **you host**. OSRM
  * only serves a driving profile, so motorcycle/bus durations are derived by
@@ -3368,6 +3436,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.
@@ -3447,6 +3526,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`.
@@ -3501,6 +3596,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).
  *
@@ -3550,6 +3653,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.
  *
@@ -3761,6 +3873,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.
  *
@@ -4226,6 +4359,85 @@ export declare interface OfflineStoreConfig<TItem> {
     ownerField?: keyof TItem & string;
 }
 
+/**
+ * Offline-first sync engine: a durable outbox plus a paginated delta pull.
+ *
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ */
+export declare interface OfflineSync<TPayload> {
+    /**
+     * Queue a mutation. Returns the generated entry id.
+     *
+     * @param op - The mutation kind.
+     * @param recordId - Primary key of the affected record.
+     * @param payload - Record snapshot (for `create`/`update`).
+     */
+    enqueue: (op: OutboxOp, recordId: string, payload?: TPayload) => Promise<string>;
+    /**
+     * Run a full sync (drain the outbox, then pull the delta). Concurrent
+     * calls share one in-flight promise, so triggers never overlap.
+     *
+     * @param trigger - Label for why the run happened. Default `"manual"`.
+     */
+    flush: (trigger?: SyncTrigger) => Promise<SyncRunSummary>;
+    /** Number of mutations still queued. */
+    pendingCount: () => Promise<number>;
+    /** The queued mutations in FIFO order. */
+    listPending: () => Promise<OutboxEntry<TPayload>[]>;
+    /** Drop every queued mutation (e.g. on logout). */
+    clearOutbox: () => Promise<void>;
+    /** Reset the pull watermark (e.g. on logout / account switch). */
+    resetWatermark: () => void;
+}
+
+/**
+ * Configuration for {@link createOfflineSync}.
+ *
+ * The engine owns the outbox, the single-flight flush, the offline guard, the
+ * paginated pull loop and the watermark; the three transport callbacks
+ * (`deliver`, `pullPage`, `applyRemote`) are where the app plugs in its own
+ * endpoints, record shape and conflict resolution.
+ *
+ * @typeParam TPayload - Record snapshot carried by outbox entries.
+ * @typeParam TRemote - Server item shape returned by `pullPage`.
+ */
+export declare interface OfflineSyncConfig<TPayload, TRemote> {
+    /** IndexedDB database name for the outbox (kept separate per queue). */
+    databaseName: string;
+    /** Outbox object-store name. Default `"outbox"`. */
+    tableName?: string;
+    /** Outbox schema version. Default `1`. */
+    version?: number;
+    /** Prefix for generated entry ids. Default `"outbox"`. */
+    idPrefix?: string;
+    /**
+     * Deliver one queued mutation to the server. Throwing keeps the entry
+     * queued (its `attempts`/`lastError` are bumped) for the next run.
+     */
+    deliver: (entry: OutboxEntry<TPayload>) => Promise<void>;
+    /** Fetch one page of the server delta since `since`, from `cursor`. */
+    pullPage: (since: string | null, cursor: string | null) => Promise<PullPage<TRemote>>;
+    /**
+     * Merge one pulled item into the local store. The app owns conflict
+     * resolution here (e.g. last-write-wins, keeping newer local pending
+     * edits, resolving tombstones and downloading blobs).
+     */
+    applyRemote: (item: TRemote) => Promise<void>;
+    /** Watermark persistence, or `{ storageKey }` for a `localStorage` default. */
+    watermark: WatermarkStore | {
+        storageKey: string;
+    };
+    /** Called after an entry is delivered and acked. */
+    onEntryDelivered?: (entry: OutboxEntry<TPayload>) => void | Promise<void>;
+    /** Called after an entry fails delivery (it stays queued). */
+    onEntryFailed?: (entry: OutboxEntry<TPayload>, error: unknown) => void | Promise<void>;
+    /**
+     * Connectivity check. Default reads `navigator.onLine` (always online in
+     * non-browser environments). When it returns `false`, `flush` is skipped.
+     */
+    isOnline?: () => boolean;
+}
+
 /** Offset-paginated response envelope (fastapi-pagination `Page[T]`). */
 export declare interface OffsetPage<T> {
     /** The rows for the current page. */
@@ -4314,6 +4526,39 @@ export declare interface OSRMBackendOptions {
     modeDurationFactors?: Partial<Record<TravelMode, number>>;
 }
 
+/**
+ * A single queued mutation.
+ *
+ * @typeParam TPayload - The record snapshot shape carried by
+ *   `create`/`update` entries (omitted for `delete`).
+ */
+export declare interface OutboxEntry<TPayload = unknown> {
+    /** Stable per-entry id (generated with {@link randomId}). */
+    id: string;
+    /** The mutation kind. */
+    op: OutboxOp;
+    /** Primary key of the record the mutation targets. */
+    recordId: string;
+    /** Epoch milliseconds when the mutation was queued. */
+    enqueuedAt: number;
+    /** How many delivery attempts have been made so far. */
+    attempts: number;
+    /** Last delivery error message, kept for UI/debug. */
+    lastError?: string;
+    /** Record snapshot for `create`/`update`. Omitted for `delete`. */
+    payload?: TPayload;
+}
+
+/**
+ * Mutation kinds queued in the outbox.
+ *
+ * `create`/`update` carry a snapshot of the record; `delete` needs only the
+ * record id. The distinction between `create` and `update` is advisory — the
+ * engine treats both as "deliver this record" and leaves the create-vs-update
+ * decision to the app's `deliver` callback (a `PUT` upsert usually ignores it).
+ */
+export declare type OutboxOp = "create" | "update" | "delete";
+
 export { Outlet }
 
 /**
@@ -4657,6 +4902,23 @@ export declare type ProgressVariant = "primary" | "success" | "warning" | "dange
  */
 export declare function projectMercator(coord: Coordinate): MercatorPoint;
 
+/**
+ * One page of the server delta pull.
+ *
+ * @typeParam TRemote - The server-side item shape.
+ */
+export declare interface PullPage<TRemote> {
+    /** Items changed since the watermark, in this page. */
+    items: TRemote[];
+    /** Cursor for the next page, or `null` when this is the last page. */
+    nextCursor: string | null;
+    /**
+     * Server clock to persist as the next watermark once the whole delta is
+     * applied. `null` leaves the watermark unchanged.
+     */
+    serverTime: string | null;
+}
+
 /**
  * Service-worker context helpers for handling `push` and `notificationclick`
  * events. Import these inside your own `sw.ts` — they expect to run in the
@@ -4847,6 +5109,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>;
@@ -4866,6 +5133,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;
 }
 
 /**
@@ -5243,6 +5531,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;
@@ -5574,6 +5889,26 @@ export declare interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputE
     wrapperClassName?: string;
 }
 
+/** Outcome of a single {@link OfflineSync.flush} run. */
+export declare interface SyncRunSummary {
+    /** The trigger passed to `flush`. */
+    trigger: SyncTrigger;
+    /** Entries delivered to the server this run. */
+    succeeded: number;
+    /** Entries that failed and stay queued for the next run. */
+    failed: number;
+    /** Total wall-clock milliseconds the run took. */
+    durationMs: number;
+    /** `true` when the run was skipped because the device was offline. */
+    skipped: boolean;
+}
+
+/**
+ * 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.
+ */
+export declare type SyncTrigger = "boot" | "online-event" | "after-mutation" | "manual" | "interval" | (string & {});
+
 export declare interface TabItem {
     id: string;
     label: ReactNode;
@@ -6725,6 +7060,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.
@@ -6819,6 +7223,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;
@@ -7719,6 +8169,19 @@ export declare interface VisuallyHiddenProps extends HTMLAttributes<HTMLElement>
     as?: keyof JSX_2.IntrinsicElements;
 }
 
+/**
+ * Pluggable persistence for the pull watermark (the "changed since" cursor).
+ * Pass an object with a `storageKey` to use a `localStorage`-backed default.
+ */
+export declare interface WatermarkStore {
+    /** Read the current watermark, or `null` when none is stored. */
+    get: () => string | null;
+    /** Persist a new watermark. */
+    set: (value: string) => void;
+    /** Drop the watermark (e.g. on logout / account switch). */
+    clear: () => void;
+}
+
 /**
  * Browser-side Web Push helper. Wraps `Notification.requestPermission`,
  * `pushManager.subscribe`, and the corresponding teardown. Transport is up to
@@ -7843,6 +8306,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