tempest-react-sdk 0.80.0 → 0.82.0

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

@@ -15,6 +15,7 @@ import { ComponentType } from 'react';
 import { CompositionEventHandler } from 'react';
 import { Control } from 'react-hook-form';
 import { Controller } from 'react-hook-form';
+import { ControllerFieldState } from 'react-hook-form';
 import { ControllerRenderProps } from 'react-hook-form';
 import { createBrowserRouter } from 'react-router';
 import { createHashRouter } from 'react-router';
@@ -870,7 +871,10 @@ export declare interface ApiClientConfig {
      * Never logs a body, a header, or the query string — a bearer token in
      * `Authorization`, a password in a login payload and an `access_token` query
      * param would all end up in whatever the sink writes to. What is logged is
-     * the method, the path as the call site wrote it, and the numbers.
+     * the method, the path and the numbers. The path is cut at the first `?` or
+     * `#`, and an absolute URL loses its `user:password@`, so a query written
+     * into the path (`"/files?access_token=…"`) or the signature of a presigned
+     * URL stays out just like `params` does.
      */
     logger?: ApiClientLogger;
     /**
@@ -962,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;
@@ -1783,6 +1800,152 @@ export declare interface AudioRecording {
     durationMs: number;
 }
 
+/**
+ * An e-mail field: trimmed and lower-cased *before* it is validated.
+ *
+ * The order is the point. Validating first rejects `" ana@x.com"` pasted with a
+ * trailing space from a password manager, and a backend that compares e-mails
+ * case-sensitively creates a second account for `Ana@x.com`. An empty value gets
+ * its own sentence instead of "e-mail inválido", which reads like an accusation
+ * on a field the user simply has not reached yet.
+ *
+ * @returns A schema producing the normalized address.
+ */
+export declare function authEmail(): z.ZodPipe<z.ZodString, z.ZodEmail>;
+
+/**
+ * One entry of an auth form's `fields` list.
+ *
+ * The form is generated from this list, so the app declares *which* fields and
+ * *how they read* — never the markup, the wiring to react-hook-form or the error
+ * slot.
+ *
+ * @typeParam TName - The schema's keys, so a typo in `name` fails to compile.
+ */
+export declare interface AuthField<TName extends string = string> {
+    /** Key in the schema and in the submitted values. */
+    name: TName;
+    /** Visible label. Rich content works for `checkbox` (a terms link); keep it text for `pin`. */
+    label: ReactNode;
+    /** Control used to render it. Default `"text"`. */
+    type?: AuthFieldType;
+    /** Placeholder shown while the field is empty. */
+    placeholder?: string;
+    /**
+     * `autocomplete` token. Defaults per type: `email` → `"email"`, `password` →
+     * `"current-password"`, `phone` → `"tel"`. Sign-up and reset presets pass
+     * `"new-password"` so password managers offer to generate one.
+     */
+    autoComplete?: string;
+    /** Help text under the field, replaced by the error when there is one. */
+    helperText?: ReactNode;
+    /** Marks the control as required (visual hint + native attribute). */
+    required?: boolean;
+    /** `password` only: show the strength meter under the field. */
+    showStrength?: boolean;
+    /** `pin` only: number of cells. Default `6`. */
+    length?: number;
+    /** Render the control yourself — for a field none of the types covers. */
+    render?: (props: AuthFieldRenderProps) => ReactNode;
+}
+
+/** The field names a schema accepts. */
+export declare type AuthFieldName<TSchema extends z.ZodTypeAny> = Extract<keyof z.infer<TSchema>, string>;
+
+/** What a field's `render` receives: the react-hook-form binding plus the field's own config. */
+export declare interface AuthFieldRenderProps {
+    /** `name`, `value`, `onChange`, `onBlur` and `ref` — spread or wire them into the control. */
+    field: ControllerRenderProps<FieldValues, string>;
+    /** The field's validation state, including the server error mapped onto it. */
+    fieldState: ControllerFieldState;
+    /** The current error message, already resolved from `fieldState`. */
+    error?: string;
+    /** The config entry this field was declared with. */
+    config: AuthField;
+}
+
+/**
+ * Which SDK control renders a field.
+ *
+ * `text` and `email` → `Input`, `password` → `PasswordInput`, `phone` / `cpf` /
+ * `cnpj` → the masked inputs, `checkbox` → `Checkbox`, `pin` → `PinInput`. The
+ * list is closed on purpose: these are the controls an auth screen uses, and
+ * anything else goes through `render`.
+ */
+export declare type AuthFieldType = "text" | "email" | "password" | "phone" | "cpf" | "cnpj" | "checkbox" | "pin";
+
+/**
+ * A complete auth form generated from a list of field configs and a zod schema.
+ *
+ * Every hand-built login and sign-up screen repeated the same wiring: a
+ * `useZodForm`, one labelled input per field with its error slot, a password eye,
+ * a submit button disabled while the request runs, and a `catch` that copied the
+ * 422's field messages back onto the inputs. The app now declares *which* fields
+ * and *what happens on submit*; the rest is here, built on the SDK's own controls
+ * and its forms layer (`useZodForm` + `FormProvider` + `FormField`).
+ *
+ * Errors thrown by `onSubmit` are shown, never rethrown — a rethrow from a submit
+ * handler is an unhandled rejection with nowhere to go. A `TempestApiError` whose
+ * `fields` name fields of this form marks them; anything else, and any field
+ * message that matched no declared field, goes to an `Alert` above the fields,
+ * worded by `describeApiError`. Pass `onError` to log.
+ *
+ * @example
+ * const schema = z.object({ email: z.email("E-mail inválido") });
+ * <AuthForm
+ *     schema={schema}
+ *     fields={[{ name: "email", type: "email", label: "E-mail" }]}
+ *     submitLabel="Continuar"
+ *     onSubmit={async (values) => { await api.post("/auth/magic-link", { body: values }); }}
+ * />
+ */
+export declare function AuthForm<TSchema extends z.ZodTypeAny>({ schema, fields, onSubmit, submitLabel, defaultValues, beforeSubmit, afterSubmit, social, labels, errorOptions, onError, className, }: AuthFormProps<TSchema>): ReactNode;
+
+/** Fixed sentences of {@link AuthFormProps}, PT-BR by default. */
+export declare interface AuthFormLabels {
+    /** Text of the divider drawn above the `social` slot. Default `"ou"`. */
+    divider: string;
+    /**
+     * Fallback sentence of the error alert, when the thrown error carries nothing
+     * better. Default `"Não foi possível concluir agora. Tente de novo."`.
+     */
+    error: string;
+}
+
+export declare interface AuthFormProps<TSchema extends z.ZodTypeAny> {
+    /** Zod schema validating the values; its messages are what each field shows. */
+    schema: TSchema;
+    /** The fields, in display order. */
+    fields: readonly AuthField<AuthFieldName<TSchema>>[];
+    /**
+     * Called with the validated values. Throw to fail: a `TempestApiError` whose
+     * `fields` name fields of this form marks those fields; any other error shows
+     * an alert above the form.
+     */
+    onSubmit: (values: z.infer<TSchema>) => Promise<void> | void;
+    /** Submit button content. Default `"Enviar"`. */
+    submitLabel?: ReactNode;
+    /** Initial values. Fields left out start as `""` (`false` for checkboxes). */
+    defaultValues?: Partial<z.input<TSchema>>;
+    /** Content between the fields and the submit button — the "forgot password" link. */
+    beforeSubmit?: ReactNode;
+    /** Content after the submit button — the "no account? sign up" line. */
+    afterSubmit?: ReactNode;
+    /** Social sign-in buttons. Rendered under a divider reading `labels.divider`. */
+    social?: ReactNode;
+    /** Overrides for the fixed sentences. */
+    labels?: Partial<AuthFormLabels>;
+    /** Passed to `describeApiError` to word the alert — map error `codes`, `statuses`. */
+    errorOptions?: DescribeApiErrorOptions;
+    /** Called with every error `onSubmit` threw, after it is shown — for logging. */
+    onError?: (error: unknown) => void;
+    /** Class name for the `<form>`. */
+    className?: string;
+}
+
+/** The value object a schema produces, as react-hook-form sees it. */
+export declare type AuthFormValues<TSchema extends z.ZodTypeAny> = z.infer<TSchema> & FieldValues;
+
 /**
  * Router-agnostic auth gate. The caller decides what to render in either
  * branch — typically `<Outlet />` for protected layouts and `<Navigate />` for
@@ -1807,6 +1970,126 @@ export declare interface AuthGuardProps {
     fallback: ReactNode;
 }
 
+/**
+ * The layout shell of a sign-in, sign-up or password-recovery screen.
+ *
+ * Every app was hand-building the same page around its form: a colored top with
+ * the logo and a back button over a white sheet with rounded top corners on
+ * mobile, a 50/50 brand panel and form on desktop, a "Bem-vindo!" heading. This
+ * component is that page, so the app passes only the brand and the form.
+ *
+ * The switch between the two layouts is a JavaScript media query, not a CSS
+ * `@media` rule, because the breakpoint is a prop: a CSS media query cannot read a
+ * custom property. `useMediaQuery` evaluates synchronously on the first render, so
+ * a client-rendered page does not flash the wrong layout.
+ *
+ * @example
+ * <AuthPage brand={<img src="/logo.svg" alt="Acme" />} back="/" title="Bem-vindo!">
+ *     <LoginForm onSubmit={signIn} links={{ forgotPassword: "/recuperar", signUp: "/cadastro" }} />
+ * </AuthPage>
+ */
+export declare function AuthPage({ brand, title, subtitle, aside, variant, breakpoint, back, footer, headingLevel, as, children, className, style, ...props }: AuthPageProps): ReactNode;
+
+/** The brand panel of a `split` page — the colored half on desktop, the colored top on mobile. */
+export declare interface AuthPageAside {
+    /**
+     * Any CSS `background` value: a color, a token, a gradient, an image.
+     * Defaults to `var(--tempest-primary)`, so a themed app gets its brand color
+     * without passing anything.
+     */
+    background?: string;
+    /**
+     * Text color over that background. Defaults to `var(--tempest-text-on-primary)`,
+     * which is only right while the background is the primary color — set it
+     * together with a custom `background` so the back button and the app name
+     * keep their contrast.
+     */
+    color?: string;
+    /** Extra content under the brand on the panel: a tagline, an illustration. */
+    content?: ReactNode;
+}
+
+/** 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`. 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;
+    /** Click handler — used alone (a `<button>`) or together with `to`. */
+    onClick?: () => void;
+}
+
+/** Heading level of the page title. */
+export declare type AuthPageHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export declare interface AuthPageProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    /** Logo and/or app name, shown on the brand panel (split) or at the top of the card. */
+    brand?: ReactNode;
+    /** Page title, rendered as a heading — e.g. `"Bem-vindo!"`. */
+    title?: ReactNode;
+    /** Line under the title — e.g. `"Entre com sua conta para continuar"`. */
+    subtitle?: ReactNode;
+    /** Brand panel colors and extra content. */
+    aside?: AuthPageAside;
+    /**
+     * `split` (default): colored top + rounded white sheet below `breakpoint`,
+     * 50/50 brand panel and form at or above it. `card`: one centered card at
+     * every width — the internal-panel login.
+     */
+    variant?: AuthPageVariant;
+    /**
+     * Viewport width, in px, at which `split` turns into two columns. Default
+     * `768`, the width every hand-built auth screen this replaces switched at —
+     * deliberately not the `1024` of `useBreakpoint`, which is about navigation
+     * chrome, not about whether a form fits beside a brand panel.
+     */
+    breakpoint?: number;
+    /** Back action: a route string, or an object with `to`/`label`/`onClick`. Omit to hide it. */
+    back?: string | AuthPageBackAction;
+    /** Content under the form, inside the sheet or card — legal text, a secondary link. */
+    footer?: ReactNode;
+    /** Heading level of `title`. Default `1`, since the auth screen is usually the whole page. */
+    headingLevel?: AuthPageHeadingLevel;
+    /**
+     * Root element. Default `"main"`, the page's main landmark. Use `"div"` when
+     * the page is rendered inside a layout that already owns a `<main>` — two
+     * nested main landmarks are an accessibility violation.
+     */
+    as?: "main" | "div";
+    /** The form — usually an `AuthForm` or one of its presets. */
+    children?: ReactNode;
+}
+
+/** How the page is laid out: brand panel beside the form, or one centered card. */
+export declare type AuthPageVariant = "split" | "card";
+
+/**
+ * A password field with the minimum length every Tempest backend enforces.
+ *
+ * @param message - Sentence shown below 8 characters.
+ * @returns The password schema.
+ */
+export declare function authPassword(message?: string): z.ZodString;
+
+/**
+ * Props every preset (`LoginForm`, `SignUpForm`, …) shares.
+ *
+ * `schema` and `fields` become optional — the preset ships both — and the slots
+ * around the submit button are the preset's to fill, from its `links`.
+ *
+ * @typeParam TSchema - The schema in use; the preset's default when none is passed.
+ */
+export declare interface AuthPresetProps<TSchema extends z.ZodTypeAny> extends Omit<AuthFormProps<TSchema>, "schema" | "fields" | "labels" | "beforeSubmit" | "afterSubmit"> {
+    /** Replaces the preset's schema. Pair it with `fields` when it adds or renames keys. */
+    schema?: TSchema;
+    /** Replaces the preset's field list. */
+    fields?: readonly AuthField<AuthFieldName<TSchema>>[];
+}
+
 export declare interface AuthState<TUser> {
     user: TUser | null;
     token: string | null;
@@ -2376,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;
 
@@ -2523,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.
@@ -3911,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
@@ -4239,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.
@@ -4307,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.
      *
@@ -5252,6 +5592,22 @@ export declare interface CreateStorePersistOptions<T> {
  * without a working revocation, that boot `refresh()` restores the previous
  * account for whoever uses the browser next.
  *
+ * With `storage: "local"` the session belongs to the **origin**, not the tab:
+ * every tab reads and writes the same keys and follows what another tab wrote
+ * — on the `storage` event and, before any refresh, `logout()` or ending of
+ * the session, by comparing the stored session with the one it holds. A
+ * rotation elsewhere is adopted; a logout or another account's login
+ * 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). 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
  * replays with the new token and refreshes nothing. Three expired requests take
@@ -5316,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
@@ -5529,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)),
  * });
@@ -5715,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;
     /**
@@ -6517,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;
 
@@ -6531,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(
@@ -6554,6 +6962,9 @@ export declare function deepMerge<T>(target: T, source: Partial<T>): T;
  */
 export declare const DEFAULT_API_ERROR_STRINGS: ApiErrorStrings;
 
+/** PT-BR defaults of {@link AuthFormLabels}. */
+export declare const DEFAULT_AUTH_FORM_LABELS: AuthFormLabels;
+
 /**
  * What a scanner looks for when you do not say.
  *
@@ -7890,6 +8301,51 @@ declare type FloatingActionButtonVariant = "primary" | "surface";
  */
 export declare function For<T>({ each, children, fallback }: ForProps<T>): ReactNode;
 
+/** Default fields of `ForgotPasswordForm`: the e-mail, with a line saying what happens next. */
+export declare const FORGOT_PASSWORD_FIELDS: readonly AuthField<"email">[];
+
+/**
+ * "Forgot password" form: the e-mail the reset link goes to.
+ *
+ * The confirmation screen after a successful submit is the app's call — most
+ * backends answer the same whether or not the address exists, so the copy
+ * belongs next to the backend's policy, not here.
+ *
+ * @example
+ * const [sent, setSent] = useState(false);
+ * <ForgotPasswordForm
+ *     onSubmit={async (values) => { await api.post("/auth/forgot-password", { body: values }); setSent(true); }}
+ *     links={{ signIn: "/login" }}
+ * />
+ */
+export declare function ForgotPasswordForm<TSchema extends z.ZodTypeAny = typeof forgotPasswordSchema>({ schema, fields, links, labels, submitLabel, ...props }: ForgotPasswordFormProps<TSchema>): ReactNode;
+
+/** Sentences of {@link ForgotPasswordForm}, PT-BR by default. */
+export declare interface ForgotPasswordFormLabels extends AuthFormLabels {
+    /** Default `"Lembrou a senha?"`. */
+    signInPrompt: string;
+    /** Default `"Entrar"`. */
+    signIn: string;
+}
+
+/** Routes the forgot-password form links to. */
+export declare interface ForgotPasswordFormLinks {
+    /** "Entrar" link, under the form. */
+    signIn?: string;
+}
+
+export declare interface ForgotPasswordFormProps<TSchema extends z.ZodTypeAny = typeof forgotPasswordSchema> extends AuthPresetProps<TSchema> {
+    /** Where the links go. */
+    links?: ForgotPasswordFormLinks;
+    /** Overrides for the fixed sentences. */
+    labels?: Partial<ForgotPasswordFormLabels>;
+}
+
+/** Default schema of `ForgotPasswordForm`: the e-mail the reset link goes to. */
+export declare const forgotPasswordSchema: z.ZodObject<{
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+}, z.core.$strip>;
+
 /**
  * Form wrapper with a built-in layout variant. Replaces ad-hoc `<form>` +
  * `<Stack>` / `<Grid>` boilerplate; pair with [[FormRow]], [[FormSection]],
@@ -7922,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;
 }
 
@@ -8272,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;
 }
 
@@ -8395,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;
 }
 
@@ -8444,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 {
     /**
@@ -8471,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. */
@@ -8491,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;
 }
@@ -8946,6 +9419,43 @@ export declare interface InstallBackgroundSyncOptions {
      * persisting and replaying every header, credentials included.
      */
     credentialHeaders?: readonly string[];
+    /**
+     * Origins besides the worker's own that a replayed request may carry a
+     * credential header to — typically the API host when it is not the app's
+     * origin (`["https://api.acme.com"]`). Default `[]`: only the worker's origin.
+     *
+     * A credential re-applied at replay comes from the page, so it is the app's
+     * credential, whatever the request originally carried under the same header
+     * name. Before 0.81.0 the worker checked only the name, and a mutation to a
+     * third party that failed offline carrying that party's `Authorization` was
+     * replayed to it with the app's bearer (#523). Now, with the rule
+     * `isTrustedCredentialTarget` enforces on the live `ApiClient`:
+     * - an entry that carried a credential header to an origin outside this
+     *   scope is dropped before `beforeReplay` runs — re-sending it without the
+     *   credential would be a request the app never made, and with the app's
+     *   credential, a leak;
+     * - a request returned by `beforeReplay` (custom or default) that carries a
+     *   header from `credentialHeaders` to an origin outside this scope is
+     *   dropped instead of sent.
+     *
+     * Both drops warn once per origin per replay in development builds. Entries
+     * with no credential header are not affected: the browser attaches that
+     * origin's own cookies, as it did on the original attempt.
+     */
+    trustedOrigins?: readonly string[];
+    /**
+     * 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;
     /**
      * Prepare each queued request right before it is replayed: return the
      * request to send (typically with the current credentials applied) or
@@ -8973,20 +9483,11 @@ export declare interface InstallBackgroundSyncOptions {
      * `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.
+     * Whatever the hook returns is still held to `trustedOrigins`: a credential
+     * header bound for an origin outside the worker's own and `trustedOrigins` is
+     * never sent.
      */
-    ownerPolicy?: BackgroundSyncOwnerPolicy;
     beforeReplay?: (request: Request, context: BackgroundSyncReplayContext) => Request | null | Promise<Request | null>;
 }
 
@@ -9141,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;
 
@@ -9150,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;
 }
@@ -9196,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;
 
@@ -9221,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.
@@ -9620,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
@@ -9920,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;
 }
 
@@ -10320,6 +10833,64 @@ export declare interface LoggerSink {
     (entry: LogEntry): void;
 }
 
+/**
+ * Default fields of `LoginForm`: e-mail and password.
+ *
+ * Exported, like the other presets' lists, so an app extends the defaults
+ * (`[...LOGIN_FIELDS, { name: "remember", type: "checkbox", … }]`) instead of
+ * retyping them.
+ */
+export declare const LOGIN_FIELDS: readonly AuthField<"email" | "password">[];
+
+/**
+ * Sign-in form: e-mail and password, "forgot password" link, sign-up line and a
+ * slot for social buttons.
+ *
+ * `AuthForm` with the defaults every app wrote by hand: the e-mail trimmed and
+ * lower-cased before validation, `current-password` autocomplete so the saved
+ * password is offered, and the two links in the place users look for them. What
+ * happens on success — storing the session, redirecting — stays in `onSubmit`.
+ *
+ * @example
+ * <LoginForm
+ *     onSubmit={async (values) => { await auth.login(values); navigate("/"); }}
+ *     links={{ forgotPassword: "/recuperar-senha", signUp: "/cadastro" }}
+ *     social={<GoogleSignIn component={GoogleLogin} onSuccess={signInWithGoogle} />}
+ * />
+ */
+export declare function LoginForm<TSchema extends z.ZodTypeAny = typeof loginSchema>({ schema, fields, links, labels, submitLabel, ...props }: LoginFormProps<TSchema>): ReactNode;
+
+/** Sentences of {@link LoginForm}, PT-BR by default. */
+export declare interface LoginFormLabels extends AuthFormLabels {
+    /** Default `"Esqueceu a senha?"`. */
+    forgotPassword: string;
+    /** Default `"Não tem uma conta?"`. */
+    signUpPrompt: string;
+    /** Default `"Cadastre-se"`. */
+    signUp: string;
+}
+
+/** Routes the login form links to. Each link is rendered only when its route is set. */
+export declare interface LoginFormLinks {
+    /** "Esqueceu a senha?" link, above the submit button. */
+    forgotPassword?: string;
+    /** "Cadastre-se" link, under the form. */
+    signUp?: string;
+}
+
+export declare interface LoginFormProps<TSchema extends z.ZodTypeAny = typeof loginSchema> extends AuthPresetProps<TSchema> {
+    /** Where the links go. */
+    links?: LoginFormLinks;
+    /** Overrides for the fixed sentences. */
+    labels?: Partial<LoginFormLabels>;
+}
+
+/** Default schema of `LoginForm`: normalized e-mail + password of at least 8 characters. */
+export declare const loginSchema: z.ZodObject<{
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+    password: z.ZodString;
+}, z.core.$strip>;
+
 export declare type LogLevel = "debug" | "info" | "warn" | "error";
 
 /**
@@ -11193,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;
@@ -11565,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>;
     /**
@@ -11625,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. */
@@ -11703,9 +12303,22 @@ export declare interface OfflineSync<TPayload> {
     pendingCount: () => Promise<number>;
     /** The queued mutations in FIFO order. */
     listPending: () => Promise<OutboxEntry<TPayload>[]>;
-    /** Drop every queued mutation (e.g. on logout). */
+    /**
+     * Drop every queued mutation (e.g. on logout).
+     *
+     * Also ends the current session for any `flush` already in flight: that run
+     * delivers no further entry, pulls and applies nothing more and writes no
+     * watermark, and resolves with `interrupted: true`. A `flush` called after this
+     * starts a fresh run instead of joining the abandoned one.
+     */
     clearOutbox: () => Promise<void>;
-    /** Reset the pull watermark (e.g. on logout / account switch). */
+    /**
+     * Reset the pull watermark (e.g. on logout / account switch).
+     *
+     * Ends the current session for an in-flight `flush` exactly like
+     * {@link OfflineSync.clearOutbox}, so the run cannot write the ended
+     * session's watermark back after the reset.
+     */
     resetWatermark: () => void;
     /** Read the current reactive {@link SyncState} snapshot synchronously. */
     getState: () => SyncState;
@@ -11788,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> {
@@ -12069,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;
 }
 
 /**
@@ -12635,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}. */
@@ -13105,13 +13766,25 @@ export declare function projectMercator(coord: Coordinate): MercatorPoint;
  * 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.
+ * explicit `{ error: true }`.
+ *
+ * The worker applies only the header names the original request carried, and
+ * only to the worker's own origin or the `trustedOrigins` given to
+ * {@link installBackgroundSync}: an entry bound for any other origin is dropped
+ * without asking this page. Matching the name is not enough on its own — a
+ * request to a third party carries *that party's* `Authorization`, and until
+ * 0.81.0 its replay received the app's bearer (#523). `getHeaders` still gets
+ * the URL, for an app whose trusted origins need different credentials.
  *
  * 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.
@@ -13233,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>;
 }
 
@@ -13957,6 +14637,68 @@ export declare interface RequestOptions extends Omit<RequestInit, "body"> {
  */
 export declare function requestPersistentStorage(): Promise<boolean>;
 
+/** Default fields of `ResetPasswordForm`: new password (with strength meter) and confirmation. */
+export declare const RESET_PASSWORD_FIELDS: readonly AuthField<"password" | "confirmPassword">[];
+
+/**
+ * "Choose a new password" form: password and confirmation, with the mismatch
+ * reported under the confirmation field.
+ *
+ * The reset token stays out of the fields: it comes from the URL, and the app
+ * adds it in `onSubmit` — `{ ...values, token }` — where it also decides what an
+ * expired token looks like.
+ *
+ * @example
+ * const [params] = useSearchParams();
+ * <ResetPasswordForm
+ *     hints={["Pelo menos 8 caracteres"]}
+ *     onSubmit={async (values) => {
+ *         await api.post("/auth/reset-password", { body: { ...values, token: params.get("token") } });
+ *     }}
+ * />
+ */
+export declare function ResetPasswordForm<TSchema extends z.ZodTypeAny = typeof resetPasswordSchema>({ schema, fields, hints, links, labels, submitLabel, ...props }: ResetPasswordFormProps<TSchema>): ReactNode;
+
+/** Sentences of {@link ResetPasswordForm}, PT-BR by default. */
+export declare interface ResetPasswordFormLabels extends AuthFormLabels {
+    /** Default `"Lembrou a senha?"`. */
+    signInPrompt: string;
+    /** Default `"Entrar"`. */
+    signIn: string;
+    /** Accessible name of the hints list. Default `"Requisitos da senha"`. */
+    hints: string;
+}
+
+/** Routes the reset-password form links to. */
+export declare interface ResetPasswordFormLinks {
+    /** "Entrar" link, under the form. */
+    signIn?: string;
+}
+
+export declare interface ResetPasswordFormProps<TSchema extends z.ZodTypeAny = typeof resetPasswordSchema> extends AuthPresetProps<TSchema> {
+    /**
+     * Password requirements listed above the submit button ("Pelo menos 8
+     * caracteres", "Uma letra maiúscula"). Kept as text the app writes, because
+     * only the backend knows its rules.
+     */
+    hints?: ReactNode[];
+    /** Where the links go. */
+    links?: ResetPasswordFormLinks;
+    /** Overrides for the fixed sentences. */
+    labels?: Partial<ResetPasswordFormLabels>;
+}
+
+/**
+ * Default schema of `ResetPasswordForm`: new password and its confirmation.
+ *
+ * The mismatch is reported on `confirmPassword` (`path`), so the message lands
+ * under the field the user has to fix rather than in a form-level alert.
+ */
+export declare const resetPasswordSchema: z.ZodObject<{
+    password: z.ZodString;
+    confirmPassword: z.ZodString;
+}, z.core.$strip>;
+
 /**
  * A two-pane split layout with a draggable divider. The first pane is sized via
  * `flex-basis` as a percentage; the second pane fills the rest. Drag the divider
@@ -14088,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;
@@ -14100,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
@@ -14183,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;
 }
@@ -14507,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
@@ -14525,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;
     /**
@@ -15153,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
@@ -15534,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;
 }
@@ -15593,6 +16369,9 @@ export declare interface SidebarSeparator {
     key: string;
 }
 
+/** Default fields of `SignUpForm`: name, e-mail and a password with strength meter. */
+export declare const SIGN_UP_FIELDS: readonly AuthField<"name" | "email" | "password">[];
+
 /**
  * Signature capture on a canvas — the "sign here" field of a delivery receipt,
  * a service order, a term of acceptance.
@@ -15664,6 +16443,59 @@ export declare interface SignaturePadProps {
     className?: string;
 }
 
+/**
+ * Sign-up form: name, e-mail and password by default, plus the "Já tem uma conta?"
+ * line.
+ *
+ * Apps differ most here — a phone, a CPF, a terms checkbox — so the usual call
+ * passes `fields` and a `schema` built with `signUpSchema.extend({...})`. The
+ * password defaults to `new-password` autocomplete, which is what makes a
+ * password manager offer to generate one.
+ *
+ * @example
+ * <SignUpForm
+ *     schema={signUpSchema.extend({ terms: z.literal(true, "Aceite os termos") })}
+ *     fields={[...SIGN_UP_FIELDS, { name: "terms", type: "checkbox", label: "Aceito os termos" }]}
+ *     onSubmit={async (values) => { await api.post("/auth/register", { body: values }); }}
+ *     links={{ signIn: "/login" }}
+ * />
+ */
+export declare function SignUpForm<TSchema extends z.ZodTypeAny = typeof signUpSchema>({ schema, fields, links, labels, submitLabel, ...props }: SignUpFormProps<TSchema>): ReactNode;
+
+/** Sentences of {@link SignUpForm}, PT-BR by default. */
+export declare interface SignUpFormLabels extends AuthFormLabels {
+    /** Default `"Já tem uma conta?"`. */
+    signInPrompt: string;
+    /** Default `"Entrar"`. */
+    signIn: string;
+}
+
+/** Routes the sign-up form links to. */
+export declare interface SignUpFormLinks {
+    /** "Entrar" link, under the form. */
+    signIn?: string;
+}
+
+export declare interface SignUpFormProps<TSchema extends z.ZodTypeAny = typeof signUpSchema> extends AuthPresetProps<TSchema> {
+    /** Where the links go. */
+    links?: SignUpFormLinks;
+    /** Overrides for the fixed sentences. */
+    labels?: Partial<SignUpFormLabels>;
+}
+
+/**
+ * Default schema of `SignUpForm`: name, e-mail and password.
+ *
+ * Exported so an app adds its own fields with `.extend()` instead of rewriting
+ * the three it shares with every other app — see the phone and terms example in
+ * the docs.
+ */
+export declare const signUpSchema: z.ZodObject<{
+    name: z.ZodString;
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+    password: z.ZodString;
+}, z.core.$strip>;
+
 /** Loading placeholder block. Use `variant="text"` for inline lines, `circle` for avatars. */
 export declare function Skeleton({ variant, width, height, className, style }: SkeletonProps): JSX.Element;
 
@@ -15958,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;
@@ -16169,6 +17001,27 @@ export declare interface SyncRunSummary {
     skipped: boolean;
     /** Last delivery error message seen this run, or `null` when none failed. */
     lastError: string | null;
+    /**
+     * `true` when {@link OfflineSync.clearOutbox} or {@link OfflineSync.resetWatermark}
+     * ended the session while this run was in flight, so it stopped early.
+     *
+     * The counts cover only what happened before the stop: a delivery already in
+     * progress at logout is still counted, but no later entry was sent, no further
+     * page was pulled or applied, and the watermark was not written. Absent on a
+     * 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;
 }
 
 /**
@@ -16462,6 +17315,34 @@ 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.
+     *
+     * An app keeps one preset for the page's lifetime and never needs it; it
+     * exists for tests and hot-module reload, which build several presets in
+     * one window. A disposed preset still compares the shared storage with
+     * its session before every refresh, so it never redeems another tab's
+     * refresh token.
+     */
+    dispose: () => void;
 }
 
 /**
@@ -16558,6 +17439,22 @@ declare interface TempestSessionEnd<TUser> {
      * call to fail and keep the local half of the teardown independent of it.
      */
     api: ApiClient;
+    /**
+     * Whether another tab of the origin ended or replaced the session, and this
+     * tab is only catching up (#524). With `storage: "local"` the session's
+     * keys are shared by every tab, so a `logout()` or a `login()` in one tab
+     * ends the session in all of them: `reason` is `"logout"` when the other
+     * tab left no session behind and `"switch"` when it installed another
+     * account.
+     *
+     * The other tab already ran this hook for the same session. Teardown that
+     * lives in this tab's memory (an in-memory cache, an open socket) still has
+     * to run here; teardown of state the origin shares (IndexedDB, Cache
+     * Storage, a push subscription) was done there, and on `"switch"` redoing
+     * it here would wipe what the new account already wrote — skip it when
+     * this is `true`.
+     */
+    elsewhere: boolean;
 }
 
 /** The token envelope returned by a Tempest FastAPI SDK login/refresh route. */
@@ -16609,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() }} />
  */
@@ -16704,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"`. */
@@ -17509,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
@@ -17566,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. */
@@ -17586,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. */
@@ -17972,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;
 
@@ -18314,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
@@ -18347,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> {
@@ -20373,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),
  * });
  *
@@ -20599,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`,
@@ -20690,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 }`.
@@ -21796,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) });
  */