tempest-react-sdk 0.81.0 → 0.82.0

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

@@ -966,7 +966,20 @@ export declare interface ApiClientConfig {
      * without it, and is exposed the same way.
      */
     csrf?: boolean | CsrfOptions;
-    /** Default headers merged into every request. */
+    /**
+     * Default headers merged into every request inside the credential scope.
+     *
+     * Treated as a credential since 0.82.0 — an `X-Api-Key` set once here is as
+     * much a secret as the bearer — so they go only to `baseURL`'s origin and
+     * {@link trustedOrigins}. A redirect would move them past that check, and
+     * unlike `Authorization` no browser strips them on a cross-origin hop
+     * (measured in Chrome 150, #554). So while this is non-empty, an in-scope
+     * request goes out with `redirect: "manual"`, and a redirect answering it
+     * is thrown as a `TempestApiError` with `code: "REDIRECT_REFUSED"` — the
+     * browser hides the `Location`, so the same-origin case cannot be told
+     * apart and followed by hand. Call the final URL (FastAPI's trailing-slash
+     * `307` is the usual source), or pass `redirect: "follow"` on the call.
+     */
     headers?: Record<string, string>;
     /** Optional fetch implementation (defaults to globalThis.fetch). */
     fetcher?: typeof fetch;
@@ -1998,7 +2011,11 @@ export declare interface AuthPageAside {
 
 /** The back action, as an object when the label or the behavior is not the default. */
 export declare interface AuthPageBackAction {
-    /** Route to navigate to, rendered as a router `Link`. */
+    /**
+     * Route to navigate to, rendered as a router `Link`. Passes through
+     * `safeLinkUrl`: a destination it rejects is dropped, leaving the button with
+     * `onClick` or, without one, no back action at all.
+     */
     to?: string;
     /** Visible label (and accessible name). Default `"Voltar"`. */
     label?: string;
@@ -2642,6 +2659,12 @@ export declare interface BreadcrumbItem {
  * Hierarchical navigation breadcrumbs. The last item is rendered as plain
  * text with `aria-current="page"`. Items with neither `href` nor `onClick`
  * also render as text (intermediate but non-clickable).
+ *
+ * Each `href` is vetted with `safeLinkUrl`'s allowlist: an item whose URL uses a scheme
+ * outside `http:`/`https:`/`mailto:`/`tel:`/`sms:` loses the `href`, and renders
+ * as text unless it also has an `onClick`. A trail built from API data — the
+ * folder names of a document tree — would otherwise put a clickable
+ * `javascript:` link on the page under React 18, which writes it verbatim.
  */
 export declare function Breadcrumbs({ items, separator, className }: BreadcrumbsProps): JSX.Element;
 
@@ -2789,6 +2812,13 @@ export declare function buildOpenInChromeIntent(): string | null;
  * link gets `aria-disabled="true"`, `role="link"`, `tabIndex={-1}`, no `href`, and
  * its click and middle-click cancelled.
  *
+ * The `href` is vetted first, with `safeLinkUrl`'s allowlist: `http:`, `https:`, `mailto:`,
+ * `tel:`, `sms:` and relative URLs pass, anything else renders as the same inert,
+ * `aria-disabled` link. React 19 blocks a `javascript:` href but the peer range
+ * admits React 18, which writes it verbatim (#447), and a CTA built from API data
+ * should not need the app to remember that. A link to a custom scheme (`whatsapp:`,
+ * an app deep link) goes through {@link ButtonSlot} with the app's own `<a>`.
+ *
  * To style another element — a react-router `Link` — use {@link ButtonSlot}. It is
  * a separate component, not an `asChild` prop, so an app that never uses it does
  * not ship the prop merge and ref composition it needs.
@@ -4177,7 +4207,21 @@ export declare const CPFInput: ForwardRefExoticComponent<Omit<InputProps, "value
  * destination of a credentialed request could come from a value read off the
  * network. A request to another origin still goes out; it goes without the
  * header, and a development build says so once. Declare the exceptions in
- * {@link ApiClientConfig.trustedOrigins}.
+ * {@link ApiClientConfig.trustedOrigins}. Since 0.82.0 the static
+ * {@link ApiClientConfig.headers} follow the same scope, and a `401` from
+ * outside it is thrown without `refresh` or `onUnauthorized` — it answered a
+ * request that never carried this session's credential.
+ *
+ * **Redirects.** The scope is checked against the URL the request starts at;
+ * where a redirect then goes is the transport's call. For `Authorization` that
+ * is safe: browsers strip it on a cross-origin redirect, measured in Chrome 150
+ * for `fetch` and XHR on `301`/`302`/`303`/`307`/`308` (#554). They strip
+ * nothing else, so a request carrying the static {@link ApiClientConfig.headers}
+ * goes out with `redirect: "manual"`, and a redirect answering it is thrown as a
+ * {@link TempestApiError} with `code: "REDIRECT_REFUSED"` instead of being
+ * followed. It cannot be followed by hand: a browser's manual redirect is an
+ * opaque response whose `Location` is unreadable. A `redirect` set on the call
+ * always wins.
  *
  * **CSRF** is off unless you set `csrf`. With it, every unsafe request (anything
  * but `GET`/`HEAD`/`OPTIONS`/`TRACE`) echoes the `csrf_token` cookie in an
@@ -4505,7 +4549,13 @@ export declare function createDataProvider(client: ApiClient, options?: DataProv
  *
  * When `url` is a function it is called before every connection, so a
  * reconnect presents a fresh credential instead of the one that expired. A
- * resolution still pending when `close()` or `reconnect()` runs is discarded.
+ * resolution still pending when `close()` or `reconnect()` runs is discarded, and
+ * one that has not started yet is never made: a stream closed in the same tick
+ * it was created asks for no URL — no ticket request, for the ticket stream.
+ *
+ * Pass `sessionKey` to bind the stream to the session it opened under: once
+ * the key changes, no frame of the previous session reaches `onMessage`, and
+ * the stream reconnects for the new one.
  *
  * @param url - Full SSE endpoint URL, or a function returning it per connection.
  * @param options - Stream configuration and callbacks.
@@ -4573,6 +4623,30 @@ export declare interface CreateEventStreamOptions<T> {
      * URL that never resolved never had an `EventSource`.
      */
     onUrlError?: (error: unknown) => void;
+    /**
+     * Read the current session key; the stream belongs to the session that was
+     * current when it connected.
+     *
+     * The server cannot end the stream for you. The `tempest-fastapi-sdk` SSE
+     * router checks the ticket only when the stream opens, and neither logout
+     * nor refresh-token revocation touches an open stream: it lives until the
+     * client leaves. So a tab that switches from user A to user B without
+     * closing the stream keeps receiving A's events under B.
+     *
+     * With this set, the key is read when each connection starts, again when
+     * its URL resolved, and before every frame is delivered. A frame that
+     * arrives after the key changed is dropped, never delivered, and the stream
+     * reconnects for the session now current — with a fresh ticket, for the
+     * ticket stream. A URL resolved while the key changed is discarded the same
+     * way, since the ticket inside it may belong to either session.
+     *
+     * The check runs when a frame arrives: a stream that stays quiet holds its
+     * connection until the next frame or until `close()`. The hook form closes
+     * it as soon as the key changes.
+     *
+     * Keys are compared with `Object.is`. Leave it out and nothing changes.
+     */
+    sessionKey?: () => SessionKey;
     /**
      * Whether a URL-resolution failure is worth another attempt. Default: always.
      *
@@ -5526,8 +5600,13 @@ export declare interface CreateStorePersistOptions<T> {
  * elsewhere ends the session here too, with `onSessionEnd` told it happened
  * `elsewhere`. Before 0.81.0 a tab left open after logout kept account A and,
  * on its next `401`, redeemed account B's refresh token from the shared
- * storage, persisting `{ user: A, token: B }` (#524). `storage: "session"` is
- * per tab and behaves as before.
+ * storage, persisting `{ user: A, token: B }` (#524). Whether the stored
+ * session is the held one is decided by a **session lineage** that `login()`
+ * mints and every rotation keeps — not by comparing users, which took two
+ * sign-ins whose user had not loaded yet for the same account (#544). Two tabs
+ * never redeem the same refresh token at once: the redemption runs under an
+ * origin-wide Web Lock when the browser has one. `storage: "session"` is per
+ * tab and behaves as before.
  *
  * 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
@@ -5593,9 +5672,14 @@ export declare interface CreateTempestAuthOptions<TUser> {
      * 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.
+     * An explicit `logout()` revokes, and so does a `"switch"` in body mode:
+     * the replaced session's refresh token is still in the client's hands, and
+     * the tempest-fastapi-sdk revokes by rotation family, so the session the
+     * new login opened is untouched even for the same user. Before 0.82.0 a
+     * switch revoked nothing and the replaced token stayed redeemable until it
+     * expired. A `"switch"` in cookie mode does not revoke — 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
@@ -5806,9 +5890,23 @@ export declare interface CreateThemeOptions {
  * cookie) on the ticket request, and the ticket in the URL opens that stream
  * and nothing else.
  *
+ * With the `api` of `createTempestAuth` as `client` and no `sessionKey`, the
+ * stream follows that preset's session (since 0.82.0): it closes the moment
+ * the session is replaced or ends, reopens with a fresh ticket for the next
+ * one, stays closed while nobody is signed in, and ignores token rotation.
+ * Any other client binds only through `sessionKey`, checked per frame.
+ *
  * @example
  * const stream = createTicketEventStream<Notification>({
+ *     client: auth.api,
+ *     onMessage: ({ data }) => addNotification(data),
+ * });
+ *
+ * @example
+ * // A client createTempestAuth did not build
+ * const stream = createTicketEventStream<Notification>({
  *     client: api,
+ *     sessionKey: () => useAuthStore.getState().user?.id ?? null,
  *     onMessage: ({ data }) => addNotification(data),
  *     onUrlError: (error) => toast.error(describeApiError(error)),
  * });
@@ -5992,6 +6090,24 @@ export declare interface CreateWebSocketOptions<T> {
     queueWhileClosed?: boolean;
     /** Cap on buffered payloads when `queueWhileClosed` is on. Default: 100. */
     maxQueuedMessages?: number;
+    /**
+     * Who is signed in right now — a stable, non-secret id such as the user id;
+     * `null`/`undefined` when nobody is. Read when a payload is buffered by
+     * `queueWhileClosed` and again when the buffer drains on the next open: a
+     * payload goes out only while the same principal is signed in, and is
+     * dropped otherwise.
+     *
+     * The URL and the protocols are fixed for the controller's life, so a socket
+     * that authenticates by cookie re-handshakes as whoever is signed in at
+     * reconnect time. Without this, a frame buffered by one account during the
+     * backoff was sent on the reconnect under the next account's cookie when the
+     * app did not `close()` the socket on logout (#531).
+     *
+     * Read synchronously. A non-string, non-number value (the `Promise` of an
+     * `async` getter) or a getter that throws reads as nobody. Default: no
+     * owner check.
+     */
+    getPrincipal?: () => string | number | null | undefined;
     /** Parse incoming frames. Default: JSON with raw-string fallback. */
     parser?: (raw: string) => T;
     /**
@@ -6794,10 +6910,18 @@ export declare function decodeJWT(token: string): DecodedJWT;
  * compression was enabled — or by a write that fell back after `gzipSync`
  * failed — still read back.
  *
+ * The output size is bounded before anything is inflated. fflate sizes its
+ * output buffer from the gzip trailer (`ISIZE`) and never grows it — measured: a
+ * 1 MB payload whose trailer claims 10 bytes inflates to exactly 10 — so
+ * refusing a trailer above {@link MAX_DECOMPRESSED_BYTES} bounds the allocation,
+ * whatever the trailer says about the real data. A corrupted or hostile value
+ * fails fast instead of taking the tab's memory.
+ *
  * @typeParam T - The expected value shape.
  * @param raw - The stored string.
  * @returns The decoded value.
- * @throws If the payload is neither valid compressed data nor valid JSON.
+ * @throws If the payload is neither valid compressed data nor valid JSON, or
+ *   declares a decompressed size above 64 MiB.
  */
 export declare function decompressFromString<T>(raw: string): T;
 
@@ -6808,6 +6932,13 @@ export declare function decompressFromString<T>(raw: string): T;
  * - Arrays and non-plain values (dates, class instances, primitives) replace
  *   the target value entirely — they are not merged element by element.
  * - Neither `target` nor `source` is mutated.
+ * - `__proto__`, `constructor` and `prototype` keys in `source` are skipped.
+ *   Assigning `result["__proto__"]` does not create a key: it **replaces the
+ *   result's prototype**, so a `JSON.parse`d settings blob carrying
+ *   `{"__proto__": {"isAdmin": true}}` produced an object whose `isAdmin` read
+ *   `true` through inheritance while `Object.keys` showed nothing. No global
+ *   prototype is touched either way; the skip removes the surprise, and the
+ *   other two names go with it because nothing legitimate merges into them.
  *
  * @example
  * deepMerge(
@@ -8247,7 +8378,7 @@ export declare type FormActionsAlign = "start" | "center" | "end" | "between";
 export declare interface FormActionsProps extends HTMLAttributes<HTMLDivElement> {
     /** Horizontal alignment of buttons. Default `end`. */
     align?: FormActionsAlign;
-    /** Gap between buttons. Numbers map to a multiple of the 4px scale (default `2` → 8px). */
+    /** Gap between buttons. Numbers map to a multiple of the 4px scale (default `2` → 8px). A number is a step, not pixels (`6` → 24px): above `12` a development build warns once, and a string such as `"96px"` passes through untouched. */
     gap?: number | string;
 }
 
@@ -8597,7 +8728,7 @@ export { FormProvider }
 export declare function FormRow({ gap, className, style, children, ...props }: FormRowProps): JSX.Element;
 
 export declare interface FormRowProps extends HTMLAttributes<HTMLDivElement> {
-    /** Gap between row items. Numbers map to a multiple of the 4px scale (default `3` → 12px). */
+    /** Gap between row items. Numbers map to a multiple of the 4px scale (default `3` → 12px). A number is a step, not pixels (`6` → 24px): above `12` a development build warns once, and a string such as `"96px"` passes through untouched. */
     gap?: number | string;
 }
 
@@ -8720,7 +8851,14 @@ export declare interface GetListParams {
         field: string;
         order?: "asc" | "desc";
     };
-    /** Arbitrary filter query params, spread onto the request. */
+    /**
+     * Arbitrary filter query params, spread onto the request **before**
+     * `pagination` and `sort`. A filter whose key equals a pagination or sort
+     * param name (`page`, `size`, `order_by`, `ascending` by default) is
+     * overridden by the structured value when that one is set: until 0.81.0 the
+     * filter won, so `filters: { page: 1 }` from a table's filter state silently
+     * pinned every request to page 1.
+     */
     filters?: DataFilters;
 }
 
@@ -8769,7 +8907,7 @@ export declare function getThemePreset(name: string): CreateThemeOptions | undef
  *     />
  * </GoogleOAuthProvider>
  */
-export declare function GoogleSignIn({ component: Component, onSuccess, onError, locale, theme, text, shape, size, disableOneTap, width, className, style, }: GoogleSignInProps): JSX.Element;
+export declare function GoogleSignIn({ component: Component, onSuccess, onError, locale, theme, text, shape, size, disableOneTap, width, nonce, className, style, }: GoogleSignInProps): JSX.Element;
 
 export declare interface GoogleSignInProps {
     /**
@@ -8796,6 +8934,16 @@ export declare interface GoogleSignInProps {
     disableOneTap?: boolean;
     /** Optional `width` override (px) — Google's button is fixed-width. */
     width?: number;
+    /**
+     * Server-issued nonce Google copies into the ID token's `nonce` claim.
+     *
+     * The backend issues one per sign-in attempt, keeps it, and rejects an
+     * `id_token` whose claim does not match — which is what stops a token
+     * captured elsewhere from being replayed against your API. Until 0.82.0
+     * the wrapper dropped it, so an app could not bind the token through
+     * `<GoogleSignIn>` at all (#530).
+     */
+    nonce?: string;
     /** Optional className applied to the wrapper. */
     className?: string;
     /** Optional inline style applied to the wrapper. */
@@ -8816,7 +8964,7 @@ export declare function Grid({ columns, gap, className, style, children, ...prop
 export declare interface GridProps extends HTMLAttributes<HTMLDivElement> {
     /** Number of columns or a custom `grid-template-columns` value. Accepts responsive object. */
     columns?: ResponsiveValue<number | string>;
-    /** Gap as a CSS length. Numbers map to a multiple of the 4px scale. Accepts responsive object. */
+    /** Gap as a CSS length. Numbers map to a multiple of the 4px scale. Accepts responsive object. A number is a step, not pixels (`6` → 24px): above `12` a development build warns once, and a string such as `"96px"` passes through untouched. */
     gap?: ResponsiveValue<number | string>;
     children?: ReactNode;
 }
@@ -9494,7 +9642,9 @@ export declare type InstallMethod = "native" | "ios" | "manual" | "none";
  *
  * A click on an action button opens that action's URL (see
  * {@link PushNotificationAction.url}); a click on the body, or on an action
- * without one, opens the top-level `url`.
+ * without one, opens the top-level `url`. Only a same-origin `http(s)` URL is
+ * opened by default; see {@link InstallNotificationClickHandlerOptions.resolveUrl}
+ * for opting into another origin.
  */
 export declare function installNotificationClickHandler(options?: InstallNotificationClickHandlerOptions): void;
 
@@ -9503,6 +9653,12 @@ export declare interface InstallNotificationClickHandlerOptions {
      * Resolve the destination URL from the notification data and the clicked
      * action id (`""` or `undefined` for a click on the body). Default: the
      * action's entry in `data.actionUrls`, else `data.url`, else `"/"`.
+     *
+     * The default only ever opens a page of the worker's **own origin**: a URL on
+     * another origin, or with a scheme other than `http:`/`https:`, becomes `"/"`.
+     * A resolver of your own is how an app opts into another origin — what it
+     * returns may point anywhere `http:`/`https:`, and any other scheme still
+     * becomes `"/"`.
      */
     resolveUrl?: (data: unknown, action: string | undefined) => string;
 }
@@ -9549,8 +9705,9 @@ export declare interface InstallPrecacheOptions {
  * Every `NotificationOptions` member the payload carries is forwarded —
  * `actions`, `requireInteraction`, `vibrate`, `silent`, `renotify`,
  * `timestamp`, `dir` and `lang` alongside `body`, `icon`, `badge`, `image` and
- * `tag`. `data` receives the top-level `url` (default `"/"`), the payload's
- * own `data`, and `actionUrls` mapping each action id to its `url`.
+ * `tag`. `data` receives the payload's own `data`, then the top-level `url`
+ * (default `"/"`) and `actionUrls` mapping each action id to its `url` — in that
+ * order, so `payload.data` cannot override where a click goes.
  */
 export declare function installPushHandler(options?: InstallPushHandlerOptions): void;
 
@@ -9574,9 +9731,10 @@ export declare interface InstallPushHandlerOptions {
  * `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
+ * route's `credentialHeaders`), or a CORS `fetch` sent with
+ * `credentials: "include"`, 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`
+ * (or `private`, without that opt-in) or `Vary: *` 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.
@@ -9973,11 +10131,13 @@ declare type IssuePathSegment = PropertyKey | {
  * rather than the request blocked: the upload still goes through, it just goes
  * without the API's bearer token.
  *
- * Both sides are resolved against the document first, so a relative `baseURL`
- * or `endpoint` — the shape behind a dev-server or reverse proxy — compares
- * equal to the absolute URL the request actually goes to. Outside a browsing
- * context a relative target resolves to nothing and is allowed: there is no
- * origin for it to cross.
+ * Both sides are resolved first, so a relative `baseURL` or `endpoint` — the
+ * shape behind a dev-server or reverse proxy — compares equal to the absolute
+ * URL the request actually goes to. The target resolves against the document
+ * base URL, where the transport sends it; the reference against the page's
+ * own address, which a `<base href>` cannot move. Outside a browsing context a
+ * relative target is allowed — there is no origin for it to cross — and a
+ * target that does not parse is refused rather than trusted.
  *
  * @param target - The URL the request is about to go to.
  * @param reference - The origin the credential belongs to, normally the
@@ -10273,7 +10433,7 @@ declare interface LayoutProps {
     layout?: FormLayout;
     /** Number of columns when `layout="grid"`, or a custom `grid-template-columns` value. Default `2`. */
     columns?: number | string;
-    /** Gap between fields. Numbers map to a multiple of the 4px scale (default `4` → 16px). */
+    /** Gap between fields. Numbers map to a multiple of the 4px scale (default `4` → 16px). A number is a step, not pixels (`6` → 24px): above `12` a development build warns once, and a string such as `"96px"` passes through untouched. */
     gap?: number | string;
 }
 
@@ -11604,7 +11764,12 @@ export declare function NavigationMenu({ items, portal, className, ...props }: N
 export declare interface NavigationMenuItem {
     /** Visible label for the entry. */
     label: ReactNode;
-    /** When set, the entry renders as an anchor. */
+    /**
+     * When set, the entry renders as an anchor. The URL is checked against
+     * `safeLinkUrl`'s allowlist: a scheme outside `http:`/`https:`/`mailto:`/`tel:`/`sms:`
+     * renders the entry as a button instead, so a menu built from API data cannot
+     * put a clickable `javascript:` link on the page under React 18.
+     */
     href?: string;
     /** Invoked when the entry is activated (click / Enter). */
     onSelect?: () => void;
@@ -11976,7 +12141,8 @@ export declare interface OfflineQueryPersistence {
     /**
      * Load the persisted snapshot into the `QueryClient`. Call once on boot,
      * before rendering queries, so cached data is available offline. A no-op
-     * once {@link OfflineQueryPersistence.clear} has been called.
+     * once {@link OfflineQueryPersistence.clear} has been called, and — with
+     * `getPrincipal` — for a snapshot written under another principal.
      */
     restore: () => Promise<void>;
     /**
@@ -12036,6 +12202,29 @@ export declare interface OfflineQueryPersistenceOptions {
      * one trailing write per window. Default `1000`.
      */
     throttleMs?: number;
+    /**
+     * Who is signed in right now — a stable, non-secret id such as the user id;
+     * `null`/`undefined` when nobody is. Read on every write, which stamps the
+     * snapshot with a one-way fingerprint of it (never the id itself), and on
+     * `restore()`, which hydrates only a snapshot stamped with the same
+     * fingerprint.
+     *
+     * `clear()` on logout already deletes the snapshot; this covers the session
+     * that ends without it — a token that expired, a crash, a tab closed while
+     * signed in. Without it, the next account to boot on the browser is shown
+     * the previous account's cached responses (#531). A snapshot written before
+     * this option was set carries no stamp and is not restored either; it is a
+     * cache, so the cost is one cold start.
+     *
+     * A foreign snapshot is skipped, not deleted: a cookie app that only learns
+     * the principal after a `/me` round trip would otherwise wipe its own cache
+     * on every cold start. The next write replaces it.
+     *
+     * Read synchronously. A non-string, non-number value (the `Promise` of an
+     * `async` getter) or a getter that throws reads as nobody. Omit it to restore
+     * every snapshot, as before 0.82.0.
+     */
+    getPrincipal?: () => string | number | null | undefined;
 }
 
 /** Maps each table name to the record type it stores. */
@@ -12212,6 +12401,30 @@ export declare interface OfflineSyncConfig<TPayload, TRemote> {
     crossTab?: boolean;
     /** Channel name when `crossTab` is on. Default `tempest-sync:${databaseName}`. */
     broadcastChannelName?: string;
+    /**
+     * Who is signed in right now — a stable, non-secret id such as the user id;
+     * `null`/`undefined` when nobody is. Read synchronously when an entry is
+     * queued, which stamps it with a one-way fingerprint (`entry.owner`, never
+     * the id itself), and again right before each delivery:
+     *
+     * - same principal → delivered;
+     * - nobody signed in now → held: it stays queued and goes out when its owner
+     *   signs back in, so a flush fired by the `online` event before login loses
+     *   nothing;
+     * - anybody else → deleted unsent and counted in `summary.dropped`, because
+     *   delivering it would send the previous account's mutation with the next
+     *   account's session.
+     *
+     * `clearOutbox()` on logout already empties the queue; this covers the app
+     * that forgets it, or a session that ends without a logout (#531). Entries
+     * queued before this option was set carry no stamp and are delivered as
+     * before — they are the user's own unsynced edits, and holding them would
+     * strand every queue on upgrade.
+     *
+     * A non-string, non-number value (the `Promise` of an `async` getter) or a
+     * getter that throws reads as nobody. Default: no owner binding.
+     */
+    getPrincipal?: () => string | number | null | undefined;
 }
 
 export declare interface OfflineTableConfig<TItem> {
@@ -12493,6 +12706,13 @@ export declare interface OutboxEntry<TPayload = unknown> {
     lastError?: string;
     /** Record snapshot for `create`/`update`. Omitted for `delete`. */
     payload?: TPayload;
+    /**
+     * One-way fingerprint of whoever was signed in when the entry was queued
+     * (`null` for nobody), stamped only when the engine has
+     * {@link OfflineSyncConfig.getPrincipal}. Absent on entries queued without
+     * it, which are delivered as before.
+     */
+    owner?: string | null;
 }
 
 /**
@@ -13059,6 +13279,23 @@ export declare interface PeerMeshOptions {
     onState?: (state: MeshState, detail?: string) => void;
     /** Called for a failure worth surfacing that is not fatal to the mesh. */
     onNotice?: (reason: string) => void;
+    /**
+     * Decide whether an offer from a peer the mesh has no link to is answered.
+     *
+     * By default the mesh answers any offer that reaches {@link PeerMesh.accept},
+     * opening a link and publishing the local tracks to it — the answering side
+     * usually learns of a peer from its offer, so that is the documented flow.
+     * It also means whether the microphone and camera reach someone rests only
+     * on the signalling server relaying offers to the right people. Pass a gate
+     * — typically "is this user in the room roster I fetched" — to make that
+     * the app's decision too. A refused offer opens nothing, answers nothing and
+     * reports `onNotice("offer_refused")`. Peers added with `addPeer` are not
+     * asked: adding them was the decision.
+     *
+     * @param peerId - The `from` of the offer.
+     * @returns `true` to answer it.
+     */
+    acceptPeer?: (peerId: string) => boolean;
     /** Initial encoder limits. */
     quality?: MeshQuality;
     /** Measure every link, on one timer the mesh owns. See {@link MeshStatsOptions}. */
@@ -13541,7 +13778,13 @@ export declare function projectMercator(coord: Coordinate): MercatorPoint;
  *
  * 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.
+ * and drops the entry when no signed-in tab is its owner. Without it every
+ * entry is `"unbound"` and replays with whichever session answers — the next
+ * account's bearer included, unless `clearSessionData()` ran on logout — so a
+ * development build warns once per call (#531). Treating an unbound
+ * credentialed entry as `"unknown"` instead would change nothing: an
+ * `"unknown"` entry replays when no answering tab reports a principal, which is
+ * exactly the page that omits `getPrincipal`.
  *
  * @param getHeaders - Resolves the headers for one queued request at replay.
  * @param options - `getPrincipal` binds entries to their owner.
@@ -13663,7 +13906,14 @@ export declare interface PushPayload {
     dir?: NotificationDirection;
     /** BCP 47 language tag of the title and body. */
     lang?: string;
-    /** Arbitrary extra data forwarded to `event.notification.data`. */
+    /**
+     * Arbitrary extra data forwarded to `event.notification.data`.
+     *
+     * Its `url` and `actionUrls` keys are overwritten by the top-level `url` and
+     * the actions' `url`s: those two keys decide where a click goes, and a
+     * free-form bag — often filled from the record that triggered the push — must
+     * not be able to redirect it.
+     */
     data?: Record<string, unknown>;
 }
 
@@ -14580,7 +14830,11 @@ export declare interface ResumableUploadOptions {
     chunkSize?: number;
     /** Sent as `Upload-Metadata` (base64-encoded values), e.g. `{ filename }`. */
     metadata?: Record<string, string>;
-    /** Extra headers on every request. */
+    /**
+     * Extra headers on every request inside the credential scope — the
+     * `endpoint`'s origin plus {@link trustedOrigins}. A `Location` on another
+     * host gets only the tus headers, never these (since 0.82.0).
+     */
     headers?: Record<string, string>;
     /** Returns the current bearer token, read before each request. */
     getToken?: () => string | null | undefined;
@@ -14592,13 +14846,20 @@ export declare interface ResumableUploadOptions {
      * 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`).
+     * `Idempotency-Key` is never replayed (#479).
+     *
+     * Without it, since 0.82.0 the record is bound to a fingerprint of the
+     * `getToken` token instead, so another account's record is still never
+     * adopted (#528) — but a token rotates: a reload after a refresh that no
+     * chunk landed under starts the upload over. Pass `getPrincipal` to keep
+     * resuming across refreshes, and always with a cookie session, where there
+     * is no token to bind to and the record stays unbound.
+     *
+     * `getToken: auth.getToken` — the getter of `createTempestAuth` itself, not
+     * an arrow around it — binds to that preset's session instead, as if
+     * `getPrincipal: auth.sessionKey` were passed: the record survives token
+     * rotation, a switch of account stops the run, and a new `login()`, even
+     * into the same account, starts over.
      *
      * It is read again before every chunk and every record write: when it
      * names someone else mid-run, the run stops with
@@ -14675,10 +14936,11 @@ export declare interface ResumableUploadRecord {
     /** 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.
+     * One-way fingerprint of the principal that created the upload (`"p:<hex>"`)
+     * or, without {@link ResumableUploadOptions.getPrincipal}, of the bearer
+     * token of its last write (`"t:<hex>"`, since 0.82.0); `null` for an
+     * anonymous one. Absent when the upload ran with neither getter, and on
+     * records written before 0.78.0.
      */
     owner?: string | null;
 }
@@ -14999,8 +15261,9 @@ export declare interface RuntimeRoute {
      */
     rangeRequests?: boolean;
     /**
-     * Opt in to caching requests that carry a credential header (see
-     * `credentialHeaders`), and responses marked `Cache-Control: private`.
+     * Opt in to caching credentialed requests — those that carry a credential
+     * header (see `credentialHeaders`) or are a CORS-mode `fetch` sent with
+     * `credentials: "include"` — and responses marked `Cache-Control: private`.
      * Default `false`.
      *
      * Cache Storage is keyed by URL and outlives the session: without this
@@ -15017,11 +15280,18 @@ export declare interface RuntimeRoute {
      * `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
+     * A cookie session is only partly visible here: the worker cannot see
+     * `Cookie`. What it can see is a `fetch` that asked for cookies explicitly —
+     * `mode: "cors"` with `credentials: "include"`, which is what `ApiClient`
+     * sends under `withCredentials` — and since 0.82.0 that request is treated
+     * as credentialed too (#531). `<img>`, `<audio>` and `<video>` also send
+     * `credentials: "include"`, but in `no-cors` mode, so they keep caching. A
+     * plain same-origin `fetch` (`credentials: "same-origin"`, the default)
+     * carries the cookie without saying so; such an API stays private only
      * through `Cache-Control: private`/`no-store` on its responses and
-     * `clearSessionData()` on logout.
+     * `clearSessionData()` on logout. Opting a cookie request in caches it by
+     * URL — there is no credential header to vary on — so `clearSessionData()`
+     * is then its only isolation.
      */
     cacheAuthenticated?: boolean;
     /**
@@ -15645,6 +15915,16 @@ export declare interface SequentialScaleOptions {
     ordinal?: boolean;
 }
 
+/**
+ * Identifies the session a stream belongs to: the signed-in user's id, an
+ * auth epoch, `null` when signed out.
+ *
+ * A primitive on purpose. The hook form lists it in its effect dependencies,
+ * and an object built inline would be a new identity on every render, so the
+ * stream would reopen on every render.
+ */
+export declare type SessionKey = string | number | boolean | null | undefined;
+
 /**
  * Thrown when the session that started an operation is no longer the current
  * one by the time it settles: a `refresh` hook (rethrown by
@@ -16026,6 +16306,10 @@ export declare interface SidebarItem {
      * A `disabled` entry ignores this and stays a `<button disabled>`: there is no
      * disabled state for an anchor, and dropping the `href` to fake one leaves a
      * link that announces itself as actionable and is not.
+     *
+     * The URL goes through `safeLinkUrl`: a scheme outside
+     * `http:`/`https:`/`mailto:`/`tel:`/`sms:` makes the entry a button, the same
+     * as an entry without `href`.
      */
     href?: string;
 }
@@ -16506,7 +16790,7 @@ export declare type StackJustify = "start" | "center" | "end" | "between";
 export declare interface StackProps extends HTMLAttributes<HTMLDivElement> {
     /** Direction. Accepts responsive object — e.g. `{ mobile: "vertical", desktop: "horizontal" }`. */
     direction?: ResponsiveValue<StackDirection>;
-    /** Gap as a CSS length. Numbers map to a multiple of the 4px scale. Accepts responsive object. */
+    /** Gap as a CSS length. Numbers map to a multiple of the 4px scale. Accepts responsive object. A number is a step, not pixels (`6` → 24px): above `12` a development build warns once, and a string such as `"96px"` passes through untouched. */
     gap?: ResponsiveValue<number | string>;
     align?: StackAlign;
     justify?: StackJustify;
@@ -16727,6 +17011,17 @@ export declare interface SyncRunSummary {
      * run that went to completion.
      */
     interrupted?: true;
+    /**
+     * Entries left queued because nobody is signed in and they belong to
+     * somebody (see {@link OfflineSyncConfig.getPrincipal}). Absent when zero.
+     */
+    held?: number;
+    /**
+     * Entries deleted unsent because they were queued under another principal —
+     * or while signed out — and somebody else is signed in now (see
+     * {@link OfflineSyncConfig.getPrincipal}). Absent when zero.
+     */
+    dropped?: number;
 }
 
 /**
@@ -17020,6 +17315,23 @@ export declare interface TempestAuth<TUser, TCredentials> {
     refresh: () => Promise<void>;
     /** The current access token, or null. */
     getToken: () => string | null;
+    /**
+     * The key of the session signed in now, or `null` when nobody is.
+     *
+     * It changes when the session is replaced — `login()`, even into the same
+     * account, a sign-in or sign-out in another tab, `logout()` — and stays
+     * the same while that session's tokens rotate: it is the session lineage
+     * `login()` mints, not the token. That is the identity a per-session
+     * resource needs. `useTicketEventStream`/`createTicketEventStream` read it
+     * on their own from `api`, and `createResumableUpload` from `getToken`;
+     * pass it as `sessionKey` or `getPrincipal` anywhere else.
+     *
+     * A session that has no lineage — persisted before lineages existed, or
+     * restored from a refresh cookie without a `login()` in this storage —
+     * answers `"unlineaged"`. Replacing it still takes a
+     * `login()`, which mints one, so the key still changes on a switch.
+     */
+    sessionKey: () => string | null;
     /**
      * Stop following the other tabs: removes the `storage` listener this
      * preset adds to `window`. Idempotent.
@@ -17194,6 +17506,10 @@ export declare function themeContrast(options: CreateThemeOptions): number | nul
  * hydrates. Inline this in `<head>` to avoid a flash of the wrong theme on
  * first paint.
  *
+ * Both options are embedded through an escaper that keeps them inside the
+ * `<script>` element whatever they contain, so the snippet is safe to inline
+ * even when the storage key comes from configuration.
+ *
  * @example
  * <script dangerouslySetInnerHTML={{ __html: themeInitScript() }} />
  */
@@ -17289,6 +17605,10 @@ export declare interface TicketEventStreamSource {
      * Authenticated client the ticket is requested through, so it carries the
      * `Authorization` header or the session cookie, the CSRF header, and the
      * 401 refresh-and-replay that a hand-rolled `fetch` would lose.
+     *
+     * The `api` of `createTempestAuth` also carries the session it acts for,
+     * and the stream binds to it when `sessionKey` is not passed — see
+     * {@link useTicketEventStream}.
      */
     client: Pick<ApiClient, "post" | "url">;
     /** Router prefix, relative to the client's base URL. Default: `"/sse"`. */
@@ -18094,7 +18414,12 @@ export declare function uploadFingerprint(endpoint: string, file: Blob | File):
  * allowing a preflight.
  *
  * A file larger than `post.max_bytes` is refused before anything is sent, with
- * the same `413 FILE_TOO_LARGE` the server would answer. Server errors are
+ * the same `413 FILE_TOO_LARGE` the server would answer. A numeric string
+ * (`"5242880"`) compares as a number; a missing or non-numeric `max_bytes` —
+ * a bare boto3 `generate_presigned_post` has none — skips this precheck, and
+ * the signed policy's `content-length-range` stays the control that refuses
+ * the bytes. The precheck saves a wasted upload; it never was the limit.
+ * Server errors are
  * normalized into one `TempestApiError` whichever backend answered: the S3 XML
  * (`EntityTooLarge` → `FILE_TOO_LARGE`, `EntityTooSmall` → `FILE_TOO_SMALL`,
  * `AccessDenied` → `SIGNED_URL_INVALID`, or `SIGNED_URL_EXPIRED` when the policy
@@ -18151,18 +18476,22 @@ export declare interface UploadWithProgressOptions {
     getToken?: () => string | null | undefined;
     /**
      * Origin the `getToken` credential belongs to, normally the API's.
+     * Defaults to the page's own origin (`location.origin`).
      *
      * Unlike `createApiClient`, this helper has no base URL to infer a scope
-     * from — the caller names the destination on every call. Set this when the
-     * `url` can come from somewhere other than your own code (a signed URL the
-     * API handed back, a value from a response body) and the token must not
-     * follow it off-origin. Left unset, the header goes wherever `url` points,
-     * which is the behaviour every version before 0.66.0 had.
+     * from — the caller names the destination on every call, and the `url` can
+     * come from somewhere other than your own code (a signed URL the API handed
+     * back, a value from a response body). Until 0.82.0 an unset scope sent the
+     * token wherever `url` pointed; it now starts closed, like the CSRF token
+     * always did, and an API on another origin sets this to receive it (#530).
+     *
+     * Outside a browsing context there is no page origin, and the scope falls
+     * back to `url` itself.
      */
     credentialOrigin?: string;
     /**
      * Extra origins allowed to receive the credential, on top of
-     * {@link credentialOrigin}. Ignored when that one is unset.
+     * {@link credentialOrigin} (or the page origin it defaults to).
      */
     trustedOrigins?: readonly string[];
     /** Send cookies. Defaults to false. */
@@ -18171,12 +18500,9 @@ export declare interface UploadWithProgressOptions {
      * Send a CSRF token with the upload, as `createApiClient`'s `csrf` does.
      * Off by default; `true` reads the `csrf_token` cookie into `X-CSRF-Token`.
      *
-     * Scoped to {@link credentialOrigin} plus {@link trustedOrigins} — and,
-     * unlike the bearer token, scoped even when `credentialOrigin` is unset:
-     * then the scope is the page's own origin. The bearer default stays open
-     * only for compatibility with every version before 0.66.0; this option is
-     * new, so it starts closed. An API on another origin sets
-     * `credentialOrigin` to receive the token.
+     * Scoped exactly like the bearer token: to {@link credentialOrigin} (the
+     * page's own origin when unset) plus {@link trustedOrigins}. An API on
+     * another origin sets `credentialOrigin` to receive the token.
      */
     csrf?: boolean | CsrfOptions;
     /** Called on every `progress` event from the XHR upload channel. */
@@ -18557,9 +18883,19 @@ export declare function useBreakpoint(): BreakpointHelpers;
  *
  * Handles sync booleans, sync {@link CanResult}, and promises of either. When
  * no provider is present, access is allowed (see `useAccessControl`). The check
- * re-runs whenever the params change.
+ * re-runs whenever the params change; they are compared by their
+ * `JSON.stringify` form, so an inline object literal does not re-run it on
+ * every render.
+ *
+ * A resolved answer is stored with the control and the params it answers, and
+ * is only returned while both still match. Until 0.81.0 the previous answer was
+ * returned with `isLoading: false` for the render between a params change and
+ * the effect that re-ran the check, so `<Can>` showed the children for the new
+ * resource for one frame on the strength of the old resource's permission. The
+ * first render for new params now reads `{ allowed: false, isLoading: true }`.
  *
  * @param params - The action/resource being checked.
+ * @returns The answer for exactly these params, or the pending state.
  */
 export declare function useCan(params: CanParams): UseCanResult;
 
@@ -18899,8 +19235,12 @@ export declare function useEventListener<K extends keyof HTMLElementEventMap>(ev
 
 /**
  * React hook wrapper around {@link createEventStream}. Connection lifecycle is
- * tied to the component (and the `url`/`enabled` dependencies); the stream
- * closes on unmount.
+ * tied to the component (and the `url`/`enabled`/`sessionKey` dependencies);
+ * the stream closes on unmount.
+ *
+ * Pass `sessionKey` (the signed-in user's id) whenever the stream carries one
+ * user's data: a change of account then closes the previous user's stream and
+ * clears `lastMessage`, even when `enabled` never went `false` in between.
  *
  * A string `url` reopens the stream when it changes. A function `url` does not:
  * an inline arrow is a new function every render, and keying on its identity
@@ -18932,9 +19272,24 @@ export declare function useEventListener<K extends keyof HTMLElementEventMap>(ev
  */
 export declare function useEventStream<T = unknown>(url: EventStreamUrl, options?: UseEventStreamOptions<T>): UseEventStreamResult<T>;
 
-export declare interface UseEventStreamOptions<T> extends Omit<CreateEventStreamOptions<T>, "onStatusChange"> {
+export declare interface UseEventStreamOptions<T> extends Omit<CreateEventStreamOptions<T>, "onStatusChange" | "sessionKey"> {
     /** When false, the stream is not opened. Useful for "wait for auth". Default: true. */
     enabled?: boolean;
+    /**
+     * The session the stream belongs to — the signed-in user's id, typically.
+     *
+     * A change closes the stream, clears `lastMessage` and, while `enabled`,
+     * opens a new connection for the new session (a fresh ticket, for
+     * {@link useTicketEventStream}). Without it, a tab that switches accounts
+     * without passing through `enabled: false` keeps the previous user's
+     * stream open and delivers its events under the new user: the server does
+     * not end an open stream on logout or revocation, so the client has to.
+     *
+     * A frame that arrives between the render that changed the key and the
+     * effect that closes the stream is dropped as well. Default: `undefined`,
+     * which never changes, so the stream follows `url` and `enabled` alone.
+     */
+    sessionKey?: SessionKey;
 }
 
 export declare interface UseEventStreamResult<T> {
@@ -20958,11 +21313,33 @@ export declare function useThrottle<T>(value: T, delay: number): T;
  * Reopening on identity would reconnect on every render for a client built
  * inline.
  *
+ * The stream is bound to a session: the ticket names the channel of the user
+ * who asked for it, the server never ends an open stream on logout, and a tab
+ * that switches accounts without `enabled` going `false` would otherwise keep
+ * delivering the previous user's events. A change of session closes that
+ * stream and asks a ticket for the new one.
+ *
+ * With the `api` of `createTempestAuth` as `client`, that binding is automatic
+ * (since 0.82.0): the session is read from the client — `auth.sessionKey()`,
+ * the lineage `login()` mints — so a switch closes the stream, a token
+ * rotation of the same session does not, and while nobody is signed in the
+ * stream stays `idle` without asking for a ticket. Any other client keeps the
+ * behaviour it had: pass `sessionKey` (the signed-in user's id). A
+ * `sessionKey` passed explicitly always wins over the client's.
+ *
  * @example
  * const { status } = useTicketEventStream<Notification>({
+ *     client: auth.api,
+ *     schema: notificationSchema,
+ *     onMessage: ({ data }) => addNotification(data),
+ * });
+ *
+ * @example
+ * // A client createTempestAuth did not build
+ * const { status } = useTicketEventStream<Notification>({
  *     client: api,
  *     enabled: isAuthenticated,
- *     schema: notificationSchema,
+ *     sessionKey: user?.id ?? null,
  *     onMessage: ({ data }) => addNotification(data),
  * });
  *
@@ -21184,7 +21561,7 @@ export { useWatch }
  * for the host component and tears it down on unmount.
  *
  * Every callback is read through a ref, so `onOpen` / `onMessage` / `onClose` /
- * `onError` / `onReconnecting` / `onReconnected` / `onLost` always run the
+ * `onError` / `onReconnecting` / `onReconnected` / `onLost` / `getPrincipal` always run the
  * latest closure — an inline arrow function is fine and never reopens the
  * socket. Connection-shaping options (`protocols`, `maxRetries`,
  * `initialBackoff`, `maxBackoff`, `jitter`, `handshakeTimeout`,
@@ -21275,6 +21652,12 @@ export declare function validateCPF(value: string): boolean;
  * become `"address.city"`, array entries `"items.0.name"`. The first issue
  * per path wins (subsequent ones are dropped to keep error UIs tidy).
  *
+ * The map is a plain object, but every key is written as an **own** property
+ * and looked up with `hasOwnProperty`: with `path in errors` and `errors[path] =`
+ * a field named `constructor` or `toString` read as already failed through
+ * `Object.prototype` and lost its message, and an issue a `superRefine` files
+ * under `__proto__` replaced the map's prototype instead of becoming a key.
+ *
  * @param schema - zod schema describing the form shape.
  * @param values - Raw form values (typed as `unknown`).
  * @returns Either `{ success: true, data, errors: {} }` or `{ success: false, errors }`.
@@ -22381,6 +22764,12 @@ export declare function writeXlsx(headers: readonly string[], rows: readonly (re
  * `ResolverOptions` is accepted and ignored, because react-hook-form always
  * passes the whole object.
  *
+ * Errors are written as **own** properties and checked with `hasOwnProperty`.
+ * A plain `errors[path]` read saw `Object.prototype.constructor` for a field
+ * named `constructor`, so `firstError` mode kept the inherited function instead
+ * of the message, and an issue a `superRefine` files under `__proto__` replaced
+ * the map's prototype instead of adding the field.
+ *
  * @example
  * const form = useForm<LoginForm>({ resolver: zodResolver(loginSchema) });
  */