tempest-react-sdk 0.53.0 → 0.55.0

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

@@ -539,10 +539,41 @@ export declare function announce(message: string, politeness?: AnnouncePolitenes
  */
 export declare type AnnouncePoliteness = "polite" | "assertive";
 
+/**
+ * Any React component, whatever props it declares.
+ *
+ * Props sit in a *parameter* position, so a bound over them is contravariant:
+ * `ComponentType<unknown>` reads as "a component that accepts every possible
+ * props object", and only a component that declares no props at all satisfies
+ * it. A page typed `({ mode }: Props) => …` is rejected, and so is one whose
+ * props are entirely optional. `any` is the only bound that admits every
+ * component — which is why React itself declares `lazy` and
+ * `LazyExoticComponent` as `ComponentType<any>`. `ComponentType<never>` is not
+ * an escape: it fails React's own bound through
+ * `ComponentClass.getDerivedStateFromProps`, where the props land back in a
+ * covariant position.
+ *
+ * This relaxes the *bound* only. `T` is still inferred as the concrete
+ * component, so the rendered element keeps checking its props and `preload()`
+ * still resolves to the concrete module.
+ */
+declare type AnyComponent = ComponentType<any>;
+
 declare type AnyEventTarget = EventTarget | {
     current: EventTarget | null;
 } | null | undefined;
 
+/**
+ * Any page component a route can point at, whatever props it declares.
+ *
+ * Same contravariance as `lazyWithRetry`, which this field is handed to:
+ * `ComponentType<unknown>` means "accepts every possible props object", so a
+ * route module default-exporting `({ id }: Props) => …` would not assign here —
+ * and neither would one whose props are all optional. React declares its own
+ * `lazy` as `ComponentType<any>` for the same reason.
+ */
+declare type AnyRouteComponent = ComponentType<any>;
+
 /**
  * Translation key the {@link useDescribeApiError} hook looks up.
  *
@@ -717,13 +748,21 @@ export declare interface ApiError {
     retryAfter?: number;
     /**
      * Field-level messages from a validation response, keyed by the field path
-     * the backend named (`"email"`, `"items.0.price"`).
+     * the backend named (`"email"`, `"items.0.price"`, `"phone"`).
+     *
+     * Present whenever the body named a field, through either shape a Tempest
+     * stack sends:
+     *
+     * - FastAPI's validation list — `detail: [{ loc, msg, type }]`, one entry per
+     *   field, each keyed by its `loc` path.
+     * - The singular keys a `tempest-fastapi-sdk` backend uses once it owns the
+     *   handler — `detail.field`, then top-level `field`, then `details.field`, in
+     *   that order. There the single value is the same sentence as `detail`.
      *
-     * Present only when the body carried a validation list — a FastAPI `422`
-     * answers with `detail: [{ loc, msg, type }]`. This is the shape a form
-     * needs: `detail` is one line for a log or a developer, and pulling the
-     * fields back out of it means parsing prose. The first message wins when a
-     * field appears twice, because a field shows one error at a time.
+     * This is the shape a form needs: `detail` is one line for a log or a
+     * developer, and pulling the fields back out of it means parsing prose. The
+     * first message wins when a field appears twice, because a field shows one
+     * error at a time.
      */
     fields?: Record<string, string>;
     /** The raw parsed error body, when available. */
@@ -959,7 +998,12 @@ export declare interface AppRouterProps {
     basename?: string;
     /** Initial URLs for the `"memory"` router (tests / non-DOM hosts). */
     initialEntries?: string[];
-    /** Suspense fallback shown while a `lazy` route chunk loads. */
+    /**
+     * Suspense fallback shown while a `lazy` route chunk loads, and the default
+     * for a route whose `guard` answers `"pending"` — one spinner covers both
+     * kinds of "not ready yet". A route overrides it with its own
+     * `guardFallback`.
+     */
     fallback?: ReactNode;
 }
 
@@ -2130,8 +2174,8 @@ declare type CameraStreamStatus = "idle" | "loading" | "ready" | "error";
 
 /**
  * Conditionally render based on an access check. Renders `children` when the
- * action is allowed, otherwise `fallback` (or nothing). While an async check is
- * pending, nothing is rendered.
+ * action is allowed and `fallback` when it is denied. While an async check is
+ * pending it renders `pending`, which defaults to `fallback`.
  *
  * @example
  * ```tsx
@@ -2139,8 +2183,20 @@ declare type CameraStreamStatus = "idle" | "loading" | "ready" | "error";
  *   <NewPostButton />
  * </Can>
  * ```
+ *
+ * @example
+ * ```tsx
+ * <Can
+ *   action="read"
+ *   resource="finance"
+ *   fallback={<p>No access</p>}
+ *   pending={<Spinner />}
+ * >
+ *   <FinancePanel />
+ * </Can>
+ * ```
  */
-export declare function Can({ action, resource, params, children, fallback }: CanProps): JSX.Element;
+export declare function Can({ action, resource, params, children, fallback, pending }: CanProps): JSX.Element;
 
 /**
  * Arguments describing the access check to perform.
@@ -2159,6 +2215,16 @@ export declare interface CanProps extends CanParams {
     children: ReactNode;
     /** Rendered when the action is denied. Defaults to nothing. */
     fallback?: ReactNode;
+    /**
+     * Rendered while an async check is still in flight. Defaults to
+     * {@link fallback}, which keeps the pre-existing behaviour.
+     *
+     * Worth setting whenever `fallback` says something denial-shaped: without
+     * it, a permission that resolves over the network flashes "no access" to
+     * someone who has it. `pending={null}` renders nothing until the answer
+     * lands; `pending={<Spinner />}` says why the screen is waiting.
+     */
+    pending?: ReactNode;
 }
 
 /**
@@ -3155,6 +3221,16 @@ export declare interface CreateEventStreamOptions<T> {
     maxBackoff?: number;
     /** Parse `event.data`. Defaults to JSON with raw-string fallback. */
     parser?: (raw: string) => T;
+    /**
+     * A frame arrived that is not valid JSON, and no `parser` was supplied.
+     *
+     * Registering this drops the frame instead of delivering it: the previous
+     * behaviour handed `onMessage` the raw `string` announced as your message
+     * type, so the failure surfaced later, at the first property access, with
+     * nothing left pointing at the parse. Leave it out and that behaviour is
+     * kept, with a one-time warning in development builds.
+     */
+    onParseError?: (error: unknown, raw: string) => void;
     onOpen?: () => void;
     onMessage?: (message: EventStreamMessage<T>) => void;
     onError?: (error: Event) => void;
@@ -3365,7 +3441,35 @@ export declare interface CreateLaunchDarklyFeatureFlagsAdapterOptions {
  * const meter = createLevelMeter(stream);
  * const tick = () => { bar.style.transform = `scaleX(${meter.level()})`; raf = requestAnimationFrame(tick); };
  */
-export declare function createLevelMeter(stream: MediaStream, { fftSize, decay }?: LevelMeterOptions): LevelMeter;
+export declare function createLevelMeter(stream: MediaStream, { fftSize, decay, context: injectedContext }?: LevelMeterOptions): LevelMeter;
+
+/**
+ * Track one link's throughput, resolution and round trip across samples.
+ *
+ * Every rate here is a **delta**. `bytesSent` is cumulative since the connection
+ * opened, so dividing it by the session length gives the historical average —
+ * a number that only ever falls and never shows what is happening now. The
+ * previous reading is kept on the sampler and subtracted, which is the part
+ * every hand-rolled copy of this ends up rewriting.
+ *
+ * Bytes are summed across every matching sender, because a peer publishing a
+ * camera and a screen at once occupies one uplink with both — and the uplink is
+ * what runs out. Resolution and frame rate come from the **largest** stream by
+ * area, which is the one that dominates that bandwidth and the one somebody
+ * watching the call is looking at.
+ *
+ * @param options - See {@link LinkStatsSamplerOptions}.
+ * @returns A sampler. Use one per `RTCPeerConnection`.
+ *
+ * @example
+ * const sampler = createLinkStatsSampler();
+ *
+ * setInterval(async () => {
+ *   const stats = await sampler.sample(pc);
+ *   badge.textContent = `${stats.kbps} kbps · ${stats.rttMs ?? "—"} ms`;
+ * }, 2000);
+ */
+export declare function createLinkStatsSampler(options?: LinkStatsSamplerOptions): LinkStatsSampler;
 
 /**
  * `localStorage`-backed resume storage — the default.
@@ -3624,6 +3728,33 @@ export declare interface CreatePasskeyClientOptions {
     credentials?: CredentialsContainerLike;
 }
 
+/**
+ * One `RTCPeerConnection` per peer, with the slots negotiated up front.
+ *
+ * The signalling protocol stays yours: this produces and accepts three message
+ * shapes (`offer`, `answer`, `ice`) and leaves delivery, room membership and
+ * identity to your server. What it owns is the part that is the same in every
+ * mesh and wrong in most of them — see {@link PeerMesh} for the traps each
+ * method exists to avoid.
+ *
+ * @param options - See {@link PeerMeshOptions}.
+ * @returns The mesh.
+ *
+ * @example
+ * const mesh = createPeerMesh({
+ *     slots: [
+ *         { name: "mic", kind: "audio" },
+ *         { name: "cam", kind: "video" },
+ *     ],
+ *     send: (message) => socket.send(message),
+ *     onPeers: setPeers,
+ * });
+ * socket.onMessage = (message) => void mesh.accept(message);
+ * await mesh.addPeer("peer-2", { offerer: true });
+ * await mesh.setLocalTrack("mic", micTrack);
+ */
+export declare function createPeerMesh(options: PeerMeshOptions): PeerMesh;
+
 /**
  * Record a live GPS trajectory from `navigator.geolocation.watchPosition`.
  * Framework-free — the {@link usePositionTracker} hook wraps this for React.
@@ -4124,6 +4255,41 @@ export declare interface CreateThemeOptions {
  */
 export declare function createVideoRecorder(stream: MediaStream, options?: VideoRecorderOptions): VideoRecorderHandle;
 
+/**
+ * Build the processing a microphone is published through.
+ *
+ * Ordered the way a console is: cut what is not speech, gate what is left, level
+ * it, shape it, set how loud it goes out, then hold a ceiling. **The order is not
+ * cosmetic.** Gating before the high-pass lets a rumble hold the gate open;
+ * compressing before the gate lifts the noise floor up to meet the threshold; and
+ * a limiter placed before the output gain is a ceiling the gain then walks
+ * straight through.
+ *
+ * This sits *after* the browser's own echo cancellation and noise suppression,
+ * which stay on: the two solve different problems. The browser's is trained on
+ * stationary noise inside the capture pipeline; this cuts what it leaves behind
+ * and decides when the line should be silent at all.
+ *
+ * @param source - The captured microphone track.
+ * @param settings - Which stages to build. Default {@link DEFAULT_VOICE_CHAIN}.
+ * @param options - See {@link VoiceChainOptions}.
+ * @returns The track to publish plus its teardown. On an engine with no Web Audio,
+ *   and when every stage is off, the source track is handed back untouched and
+ *   `supported` is `false` — a call without processing beats a call that throws.
+ *   The idle case is decided **before** a context is opened, because browsers cap
+ *   how many can be live and one built for a chain that does nothing still counts.
+ *
+ * @example
+ * const floor = await measureNoiseFloor(stream);
+ * const chain = createVoiceChain(micTrack, {
+ *     ...DEFAULT_VOICE_CHAIN,
+ *     gate: true,
+ *     gateThreshold: suggestGateThreshold(floor),
+ * }, { gain: 1.4 });
+ * await mesh.setLocalTrack("mic", chain.track);
+ */
+export declare function createVoiceChain(source: MediaStreamTrack, settings?: VoiceChainSettings, { gain, context: injectedContext, ownsSource }?: VoiceChainOptions): VoiceChain;
+
 /**
  * Open a WebSocket that survives a bad network: exponential backoff with jitter,
  * a handshake timeout, a silence watchdog, optional heartbeat pings and typed
@@ -4239,6 +4405,16 @@ export declare interface CreateWebSocketOptions<T> {
     maxQueuedMessages?: number;
     /** Parse incoming frames. Default: JSON with raw-string fallback. */
     parser?: (raw: string) => T;
+    /**
+     * A frame arrived that is not valid JSON, and no `parser` was supplied.
+     *
+     * Registering this drops the frame instead of delivering it: the previous
+     * behaviour handed `onMessage` the raw `string` announced as your message
+     * type, so the failure surfaced later, at the first property access, with
+     * nothing left pointing at the parse. Leave it out and that behaviour is
+     * kept, with a one-time warning in development builds.
+     */
+    onParseError?: (error: unknown, raw: string) => void;
     onOpen?: (event: Event) => void;
     onMessage?: (message: WebSocketMessage<T>) => void;
     onClose?: (event: CloseEvent) => void;
@@ -4924,6 +5100,19 @@ export declare const DEFAULT_PUB_KEY_CRED_PARAMS: {
     alg: number;
 }[];
 
+/** The key a caller gets when it does not choose one. */
+export declare const DEFAULT_PUSH_TO_TALK_KEY = "Space";
+
+/**
+ * What a call wants before anybody touches a slider.
+ *
+ * High-pass, leveller and limiter only. Gate, presence, hiss cut and de-esser are
+ * off because each has an audible cost when it is not needed — a gate set for the
+ * wrong room clips words, presence on a bright microphone is harsh, and a de-esser
+ * on a voice that does not hiss just dulls it.
+ */
+export declare const DEFAULT_VOICE_CHAIN: VoiceChainSettings;
+
 /**
  * Identity helper that types a declarative route tree. Use it so editors give
  * autocomplete and type-checking on every node; the array is returned as-is.
@@ -4952,12 +5141,20 @@ export declare function defineRoutes(routes: TempestRouteObject[]): TempestRoute
  *    offline sentence. This is the step apps skip, and skipping it renders
  *    "erro 0" or a raw `TypeError` at the user.
  * 2. A validation rejection — `error.fields` is set — produces the validation
- *    sentence, **not** `detail`. On a `422` the `detail` line is assembled from
- *    the backend's field paths and the validator's own wording
+ *    sentence, **not** `detail`. On a FastAPI `422` the `detail` line is assembled
+ *    from the backend's field paths and the validator's own wording
  *    (`"items.0.price: Input should be greater than 0"`), which is right for a
  *    log and wrong for a person: it is half English in a pt-BR screen and it
  *    names internals. The per-field messages stay on `fields`, where a form can
  *    attach them to the inputs that failed.
+ *
+ *    This step also catches a business error that named a single field, whose
+ *    `detail` **was** a finished sentence ("Cidade não encontrada para o estado
+ *    informado."). The trade is deliberate: that sentence is now on `fields`,
+ *    against the input it is about, which is where it does the most good. Three
+ *    ways back, in order of preference: `codes: { VALIDATION_ERROR: "…" }` (step 0,
+ *    which still wins), `validation: error.detail` at the call site, or reading
+ *    `error.detail` yourself — it is untouched.
  * 3. The backend's own `detail`, which is the most specific thing available and
  *    is already written for a person — unless `useDetail: false` says that text
  *    is for developers.
@@ -5204,11 +5401,21 @@ export declare interface DrawerProps {
 }
 
 /**
- * Dropdown menu — list of selectable actions anchored to a trigger.
+ * Dropdown menu — a list of actions anchored to a trigger, following the
+ * [APG menu button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/).
+ *
+ * `role="menu"` is a promise about the keyboard, and this component keeps it:
  *
- * - Toggle on trigger click.
- * - Close on outside click / Escape / item selection.
- * - Arrow keys navigate, Enter activates focused item.
+ * - `Enter`, `Space` or `ArrowDown` on the trigger opens and focuses the first
+ *   entry; `ArrowUp` opens and focuses the last.
+ * - `ArrowUp` / `ArrowDown` move with wrap, `Home` / `End` jump to the ends.
+ * - `Escape` closes and returns focus to the trigger, so the next `Tab` continues
+ *   from where the user was rather than from the top of the document.
+ * - `Tab` closes the menu and lets the page's own tab order take over.
+ * - Focus is managed: entries carry `tabIndex={-1}` and only the active one is
+ *   `0`, which is what stops `Tab` from walking the menu one entry at a time.
+ *
+ * Disabled entries, separators and labels are skipped by every movement.
  */
 export declare function DropdownMenu({ trigger, items, placement, className, }: DropdownMenuProps): JSX.Element;
 
@@ -5220,6 +5427,23 @@ export declare type DropdownMenuEntry = {
     danger?: boolean;
     disabled?: boolean;
     onSelect: () => void;
+} | {
+    /**
+     * An entry that carries on/off state.
+     *
+     * Rendered as `role="menuitemcheckbox"` with `aria-checked`, which is how
+     * a screen reader announces "checked" instead of leaving the state
+     * invisible. Selecting it does **not** close the menu: toggling two
+     * settings in a row is the ordinary case, and closing after the first
+     * would make the second a second trip.
+     */
+    type: "checkbox";
+    id: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    checked: boolean;
+    disabled?: boolean;
+    onSelect: () => void;
 } | {
     type: "separator";
     id: string;
@@ -5234,6 +5458,7 @@ export declare type DropdownMenuPlacement = "bottom-start" | "bottom-end" | "top
 export declare interface DropdownMenuProps {
     trigger: ReactElement<{
         onClick?: (e: React.MouseEvent) => void;
+        onKeyDown?: (e: KeyboardEvent_2) => void;
         "aria-expanded"?: boolean;
         "aria-controls"?: string;
         "aria-haspopup"?: boolean | "menu";
@@ -5483,11 +5708,6 @@ export declare interface EventStreamMessage<T> {
     raw: MessageEvent;
 }
 
-/**
- * @tempest-limits function-lines — the body is the SSE line protocol — accumulate
- * `data:` lines until a blank line, track `id:` for Last-Event-ID, honour `retry:` —
- * plus the reconnect that uses the id it just tracked.
- */
 export declare type EventStreamStatus = "idle" | "connecting" | "open" | "closed" | "error";
 
 /**
@@ -5962,6 +6182,38 @@ export declare function formatDateForInput(value: string | Date): string;
  */
 export declare function formatDateTime(value: string | Date): string;
 
+/**
+ * Format an ISO date or Date instance as `yyyy-MM-ddTHH:mm`, the value an
+ * `<input type="datetime-local">` accepts.
+ *
+ * The sibling of {@link formatDateForInput}, and it exists for the same reason:
+ * `toISOString().slice(0, 16)` is the reflex and it is wrong. `toISOString`
+ * converts to UTC first, so a 22:00 appointment in UTC-3 opens the form on the
+ * next day at 01:00 — here the trap costs the hour as well as the date.
+ *
+ * A value already in `yyyy-MM-ddTHH:mm` is returned untouched. A value carrying
+ * a zone (`...Z`, `...-03:00`) deliberately does **not** take that shortcut: it
+ * is a different instant from the naive string that looks like it, so it is
+ * converted to the local calendar parts the input has to show.
+ *
+ * Seconds are dropped. A `datetime-local` steps by the minute unless the app
+ * sets `step`, so a `:ss` the field cannot represent would be silently discarded
+ * on the first edit anyway — truncating here keeps the rendered value and the
+ * submitted value the same.
+ *
+ * @example
+ * <input
+ *     type="datetime-local"
+ *     defaultValue={formatDateTimeForInput(appointment.startsAt)}
+ * />
+ *
+ * @param value - ISO string or Date.
+ * @returns The `yyyy-MM-ddTHH:mm` value, or an empty string when the input is
+ *   invalid — which is what a datetime input reads as "no value", unlike
+ *   `"Invalid Date"`.
+ */
+export declare function formatDateTimeForInput(value: string | Date): string;
+
 /**
  * Rendering helpers for the numbers a profiler produces.
  */
@@ -7000,6 +7252,23 @@ export declare function isDefined<T>(value: T | null | undefined): value is T;
  */
 export declare function isEmpty(value: unknown): boolean;
 
+/**
+ * Whether this environment can present anything fullscreen at all.
+ *
+ * Two independent reasons for `false`, and skipping either one ships a button
+ * that does nothing when pressed: the API can be missing (older WebKit, and every
+ * browser on iOS for non-`<video>` elements), or present and **disabled** — a
+ * document inside an `<iframe>` without the `allowfullscreen` attribute exposes
+ * `requestFullscreen` and rejects every call to it, which `fullscreenEnabled`
+ * reports up front.
+ *
+ * An engine that exposes the methods and no flag at all is treated as capable:
+ * the flag is the newer half of the API, so its absence says nothing.
+ *
+ * @returns `true` when a fullscreen request stands a chance of being honoured.
+ */
+export declare function isFullscreenSupported(): boolean;
+
 /** Whether any turn in the thread is still streaming. */
 export declare function isGenerating(messages: readonly AIChatMessage[]): boolean;
 
@@ -7162,6 +7431,20 @@ export declare function isValidLongitude(value: number): boolean;
 /** Whether `MediaRecorder` exists and can produce at least one video container. */
 export declare function isVideoRecordingSupported(): boolean;
 
+/**
+ * Whether any of this would change the signal.
+ *
+ * A chain that only passes audio through still costs a re-encode and a handful of
+ * nodes, so a caller that rebuilds on every settings change should ask first —
+ * and {@link createVoiceChain} asks too, handing back `source` rather than
+ * building a graph that does nothing.
+ *
+ * @param settings - The stages under consideration.
+ * @param gain - The output multiplier that would be applied. Default `1`.
+ * @returns `true` when the chain would be audibly transparent.
+ */
+export declare function isVoiceChainIdle(settings: VoiceChainSettings, gain?: number): boolean;
+
 /** The surface every store built by {@link createJsonStorage} exposes. */
 export declare interface JsonStorage {
     /**
@@ -7395,13 +7678,22 @@ declare interface LayoutProps {
  * up the new bundle; a final `location.reload()` recovers from stale
  * `index.html`.
  *
+ * The wrapped component keeps its own props: `T` is inferred from the module
+ * the factory resolves to, so a page declaring required, optional or no props
+ * all pass through and the rendered element is still checked against them. See
+ * {@link AnyComponent} for why the constraint has to be written the way it is.
+ *
+ * @param factory Dynamic import of the module whose `default` is the component.
+ * @param options Retry count, initial backoff and the final-failure reload.
+ * @returns The lazy component, carrying an extra `preload()`.
+ *
  * @example
  * const Settings = lazyWithRetry(() => import("./Settings"));
  *
  * // Warm the chunk when the route becomes likely, not when it is needed.
  * <a href="/settings" onMouseEnter={() => void Settings.preload()}>Settings</a>
  */
-export declare function lazyWithRetry<T extends ComponentType<unknown>>(factory: () => Promise<{
+export declare function lazyWithRetry<T extends AnyComponent>(factory: () => Promise<{
     default: T;
 }>, options?: LazyWithRetryOptions): PreloadableLazy<T>;
 
@@ -7449,8 +7741,21 @@ export declare interface LevelMeterOptions {
      * A raw RMS reading is jittery enough to make a meter look broken. Attack is left
      * instant — a meter that lags the voice going *up* reads as "not recording" —
      * while the decay is eased, which is how every hardware meter behaves.
+     *
+     * `0` turns the smoothing off and reports the window's RMS as measured, which is
+     * what a detector wants: {@link monitorVoiceActivity} applies its own release,
+     * and two of them stacked would hold the indicator open long past the speech.
      */
     decay?: number;
+    /**
+     * Reuse an existing `AudioContext` instead of creating one.
+     *
+     * Browsers cap live contexts (Chrome allows around six), and a meter per remote
+     * participant reaches that in a five-person call. A caller measuring several
+     * streams should open one context and hand it to every meter. `stop()` closes
+     * only a context this meter created — an injected one belongs to the caller.
+     */
+    context?: AudioContext;
 }
 
 /**
@@ -7530,6 +7835,78 @@ export declare interface LimiterSettings {
 
 export { Link }
 
+/**
+ * One link's outbound picture, in the shape a call UI actually renders.
+ *
+ * Everything here is derived, not reported: WebRTC hands out cumulative
+ * counters and a graph of candidate pairs, and turning that into
+ * `"1,2 Mbps · 42 ms · 1080p60"` is the work {@link createLinkStatsSampler}
+ * does.
+ */
+export declare interface LinkStats {
+    /** Throughput since the previous sample. `0` on the first one — there is no delta yet. */
+    kbps: number;
+    /** Width of the largest stream being sent, or `0` before one is reported. */
+    width: number;
+    /** Height of the largest stream being sent, or `0` before one is reported. */
+    height: number;
+    /** Frame rate of the largest stream being sent, or `0` when the browser omits it. */
+    fps: number;
+    /** Round trip to the peer in milliseconds, or `null` before the first reading. */
+    rttMs: number | null;
+}
+
+/** Which media a sampler counts. */
+export declare type LinkStatsKind = "video" | "audio" | "all";
+
+/**
+ * A sampler bound to one connection.
+ *
+ * Holds the previous byte counter and timestamp, which is the whole reason this
+ * is an object rather than a function: the rate is a delta, so somebody has to
+ * remember the last reading. One sampler per link — sharing one across peers
+ * subtracts one connection's counter from another's and reports nonsense.
+ */
+export declare interface LinkStatsSampler {
+    /**
+     * Reduce a report you already have.
+     *
+     * @param report - A report from `RTCPeerConnection.getStats()`.
+     * @returns The stats for this sample.
+     */
+    read: (report: RTCStatsReport) => LinkStats;
+    /**
+     * Fetch a report and reduce it.
+     *
+     * @param connection - The connection to sample.
+     * @returns The stats for this sample.
+     */
+    sample: (connection: RTCPeerConnection) => Promise<LinkStats>;
+    /**
+     * Drop the baseline the rate is derived from.
+     *
+     * Call it after an ICE restart, a reconnect, or a pause — otherwise the next
+     * sample divides the bytes of the whole gap by the whole gap and reports the
+     * average of a period nobody is asking about. The next reading comes back at
+     * `0` kbps and starts a fresh baseline; the resolution and round trip already
+     * on screen are kept, so the badge does not blank out.
+     */
+    reset: () => void;
+}
+
+/** Options for {@link createLinkStatsSampler}. */
+export declare interface LinkStatsSamplerOptions {
+    /**
+     * Which media the throughput counts. Default `"video"`.
+     *
+     * Video is the default because it is what saturates an uplink — audio is an
+     * order of magnitude cheaper, and mixing it in moves the number by less than
+     * the noise between two samples. Use `"all"` when the figure is meant to be
+     * the connection's real cost rather than the picture's.
+     */
+    kind?: LinkStatsKind;
+}
+
 export declare interface ListOptions<TItem> {
     /** Property to order by. Default: `keyPath`. */
     orderBy?: keyof TItem & string;
@@ -7800,6 +8177,29 @@ export declare interface MasonryProps<T> extends Omit<HTMLAttributes<HTMLDivElem
  */
 export declare function matrixToPath(matrix: QRMatrix, margin?: number): string;
 
+/**
+ * Listen to a room at rest and report how loud its silence is.
+ *
+ * The number a person cannot guess. Setting a gate by ear means switching it on
+ * and hearing what disappeared, which only works if you already know what should
+ * have disappeared — so the usual outcome is leaving it at a default that is
+ * wrong for that room. Measuring replaces the guess.
+ *
+ * The result is the **peak** RMS window observed, not the average: a threshold
+ * under the loudest thing the quiet room did will be opened by that thing.
+ *
+ * @param stream - A live capture of the room while nobody speaks.
+ * @param options - See {@link NoiseFloorOptions}.
+ * @returns The peak RMS observed, `0..1`. `0` when this engine has no Web Audio
+ *   or the stream carries no audio track — which {@link suggestGateThreshold}
+ *   turns into its own floor rather than into a gate that never opens.
+ *
+ * @example
+ * const floor = await measureNoiseFloor(stream, { onProgress: setProgress });
+ * setThreshold(suggestGateThreshold(floor));
+ */
+export declare function measureNoiseFloor(stream: MediaStream, { onProgress, durationMs, context: injectedContext, }?: NoiseFloorOptions): Promise<number>;
+
 /** A classified capture error with a human-readable, English message. */
 export declare interface MediaAccessError {
     kind: MediaAccessErrorKind;
@@ -7990,6 +8390,109 @@ export declare interface MercatorPoint {
     y: number;
 }
 
+/** A message the mesh produces and accepts. The transport is the caller's. */
+export declare type MeshMessage = {
+    type: "offer";
+    to: string;
+    from?: string;
+    sdp: string;
+} | {
+    type: "answer";
+    to: string;
+    from?: string;
+    sdp: string;
+} | {
+    type: "ice";
+    to: string;
+    from?: string;
+    candidate: string | null;
+    sdpMid: string | null;
+    sdpMLineIndex: number | null;
+};
+
+/** One remote participant, as the mesh currently sees it. */
+export declare interface MeshPeer {
+    /** The id the caller registered this peer under. */
+    peerId: string;
+    /** The connection's own state, straight from `RTCPeerConnection`. */
+    connection: RTCPeerConnectionState;
+    /** Inbound stream per slot name, `null` for a slot the peer is not sending. */
+    streams: Record<string, MediaStream | null>;
+}
+
+/** Encoder limits, before the room divides them. */
+export declare interface MeshQuality {
+    /**
+     * Cap per video slot, in kbps. `null` leaves that slot uncapped.
+     *
+     * Divided by the size of the room — see {@link PeerMesh.applyQuality}.
+     */
+    video?: Record<string, number | null>;
+    /**
+     * Cap per audio slot, in **bps**, matching `setSenderBitrate`.
+     *
+     * Never divided. Audio is an order of magnitude cheaper than video and is
+     * the part of a call that has to survive: dividing it buys back a few
+     * percent of the uplink in exchange for the only thing everyone needs.
+     */
+    audio?: Record<string, number>;
+    /** Frame ceiling written onto every video encoding. */
+    maxFramerate?: number;
+    /** What a video encoder gives up first. */
+    degradationPreference?: RTCDegradationPreference;
+    /**
+     * Total uplink to divide among the peers, in kbps.
+     *
+     * A mesh sends one copy of everything **per participant**, so a cap that is
+     * comfortable one-to-one saturates a home connection with four people.
+     */
+    uplinkBudgetKbps?: number;
+    /**
+     * Floor each video slot keeps after the division, in kbps.
+     *
+     * Dividing without a floor eventually allocates tens of kbps per stream,
+     * which buys a blur that updates once a second: everybody loses the picture
+     * instead of the excess giving way.
+     */
+    minVideoKbps?: number;
+    /**
+     * Budget below which `maintain-framerate` is overridden.
+     *
+     * Somebody who asked for fluidity wants a good picture in motion, not the
+     * number 60. Once the share of the uplink is this small, holding the frame
+     * rate halves what each frame gets and the result is worse than the lower
+     * rate it replaced.
+     */
+    fluidFloorKbps?: number;
+}
+
+/**
+ * One media lane, negotiated once and reused for the life of the link.
+ *
+ * The order of the slot list is the wire protocol: the offerer allocates one
+ * m-line per slot in this order, so a slot's `mid` is its ordinal and both ends
+ * read the same identity off it. Reorder the list and the two sides disagree
+ * about which lane carries the camera.
+ */
+export declare interface MeshSlot {
+    /** Stable name the caller uses in {@link PeerMesh.setLocalTrack}. */
+    name: string;
+    /** Whether the lane carries audio or video. */
+    kind: MeshSlotKind;
+}
+
+/** What a slot carries. */
+export declare type MeshSlotKind = "audio" | "video";
+
+/**
+ * The single state a call badge shows.
+ *
+ * `connected` covers being alone in the room: a mesh with no peers has nothing
+ * to connect to and is not failing, which is the case a naive "any link
+ * connected?" check reports as broken for as long as nobody else joins.
+ */
+export declare type MeshState = "connecting" | "connected" | "reconnecting" | "failed" | "closed";
+
 export declare type Messages = Record<string, string>;
 
 /** Lifecycle of a microphone stream. */
@@ -8096,6 +8599,56 @@ export declare interface MoneyProps extends HTMLAttributes<HTMLSpanElement> {
     locale?: string;
 }
 
+/**
+ * Report when a track is carrying speech.
+ *
+ * Runs entirely on the **receiving** side, over a track the connection already
+ * delivers, and that is the whole point: a speaking indicator changes several
+ * times per second, so signalling it through a server floods the room with
+ * messages carrying information every client can derive for free.
+ *
+ * Two details separate this from a threshold on a level meter:
+ *
+ * 1. **The release.** RMS drops to nothing in the gaps between words, so a bare
+ *    comparison strobes on every syllable. The state only falls after
+ *    `releaseMs` of quiet.
+ * 2. **`onChange` fires on the flip, not on the sample.** A callback per poll
+ *    would re-render a participant list ten times a second to say the same thing.
+ *
+ * The meter underneath runs with smoothing off: its eased decay plus this release
+ * would hold the indicator open long after the speech stopped.
+ *
+ * @param stream - The stream whose first audio track is measured.
+ * @param onChange - Called only when the speaking state actually flips.
+ * @param options - See {@link VoiceActivityOptions}.
+ * @returns A handle carrying the current state and the teardown.
+ *
+ * @example
+ * const vad = monitorVoiceActivity(remoteStream, (speaking) => setSpeaking(speaking));
+ * // later
+ * vad.stop();
+ */
+export declare function monitorVoiceActivity(stream: MediaStream, onChange: (speaking: boolean) => void, { threshold, releaseMs, pollMs, context, }?: VoiceActivityOptions): VoiceActivityMonitor;
+
+/**
+ * Play your own processed microphone back to you.
+ *
+ * The only way to hear what these filters do without a second person on the call.
+ * Every number the chain is tuned by — how deep the de-esser cuts, where the gate
+ * sits, how much presence is too much — is a judgement made by ear, and without
+ * this the only available ear belongs to somebody else.
+ *
+ * **Feedback is the hazard, and the reason this is a held, explicit action rather
+ * than a setting:** without headphones the speakers feed the microphone that feeds
+ * the speakers. Say so in the UI that offers it.
+ *
+ * @param source - The raw captured track to listen to. It is never stopped here.
+ * @param settings - The stages to hear it through. Default {@link DEFAULT_VOICE_CHAIN}.
+ * @param options - See {@link VoiceChainOptions}; `ownsSource` is forced to `false`.
+ * @returns A handle that stops the monitor.
+ */
+export declare function monitorVoiceChain(source: MediaStreamTrack, settings?: VoiceChainSettings, options?: Omit<VoiceChainOptions, "ownsSource">): VoiceMonitor;
+
 /** Reorder helper: move `from` to `to`, returning a new array. */
 export declare function moveItem<T>(items: T[], from: number, to: number): T[];
 
@@ -8264,6 +8817,16 @@ export declare interface NavigationRailProps extends Omit<HTMLAttributes<HTMLEle
 
 export { NavLink }
 
+/** Options for {@link measureNoiseFloor}. */
+export declare interface NoiseFloorOptions {
+    /** Called with `0..1` so a dialog can show the wait. */
+    onProgress?: (fraction: number) => void;
+    /** How long to listen. Default `3000`. */
+    durationMs?: number;
+    /** Reuse an existing `AudioContext` rather than opening one. */
+    context?: AudioContext;
+}
+
 /**
  * Turn one raw detection into a {@link BarcodeScanResult}.
  *
@@ -9032,8 +9595,19 @@ export declare interface PageProps extends Omit<HTMLAttributes<HTMLElement>, "ti
 
 /**
  * Numeric pagination controls. Pair with {@link usePagination} for state.
+ *
+ * Narrow screens collapse to `‹` / `›` plus the summary by default, which turns
+ * random access into sequential access — fine for a desktop-first app, wrong for
+ * one whose traffic is phones. `compactOnMobile={false}` keeps the numbers at
+ * every width: the row scrolls on its own instead of widening the page, and the
+ * effect below keeps the current page inside the visible part of that row.
+ *
+ * The scroll is why this is one boolean rather than a `variant`. Simply
+ * un-hiding the buttons would push a nine-button row past a 360px viewport and
+ * give the whole document a horizontal scrollbar — the opt-out has to carry its
+ * own layout, so it does.
  */
-export declare function Pagination({ page, totalPages, onPageChange, pageSize, onPageSizeChange, pageSizeOptions, totalItems, siblingCount, className, }: PaginationProps): JSX.Element | null;
+export declare function Pagination({ page, totalPages, onPageChange, pageSize, onPageSizeChange, pageSizeOptions, totalItems, siblingCount, compactOnMobile, className, }: PaginationProps): JSX.Element | null;
 
 export declare interface PaginationProps {
     page: number;
@@ -9044,8 +9618,20 @@ export declare interface PaginationProps {
     pageSizeOptions?: number[];
     /** Total items count; if provided, renders the summary text. */
     totalItems?: number;
-    /** Max number of numbered page buttons to show. Default 7. */
+    /** Pages kept around the current one; ~`siblingCount + 4` buttons render. Default 3. */
     siblingCount?: number;
+    /**
+     * Below 640px, drop to `‹` / `›` plus the summary and hide the numbered
+     * buttons and the size select. Default `true`.
+     *
+     * The default suits a desktop-first app, and costs the thing pagination is
+     * for on a phone: reaching page 7 becomes six taps on "next" instead of one
+     * tap on `7`. Pass `false` in a mobile-first app and the numbers stay at
+     * every width — the row scrolls horizontally by itself rather than pushing
+     * the page wider, and the current page is scrolled into view when it
+     * changes.
+     */
+    compactOnMobile?: boolean;
     className?: string;
 }
 
@@ -9057,13 +9643,28 @@ declare type ParamValue = string | number | boolean | undefined | null;
 /**
  * Validate an unknown response payload against a zod schema.
  *
- * In development, throws a detailed error pointing at the divergent field.
- * In production, throws a generic error so internals do not leak to users.
+ * A development build throws a detailed error naming every divergent field path
+ * and embedding the raw payload; every other build throws a generic sentence, so
+ * server internals never reach a user's screen or an error tracker.
+ *
+ * Which one you get comes from `isDevBuild()`, the SDK's single answer to that
+ * question, rather than from a check written here. This function used to ask
+ * `typeof process !== "undefined" && process.env?.NODE_ENV === "development"`,
+ * and a browser has no `process` identifier at all — so the guard short-circuited
+ * and the detailed branch was dead in exactly the build it was written for, no
+ * matter what the bundler substituted behind it.
+ *
+ * The rule `isDevBuild()` applies is `NODE_ENV !== "production"`, which is wider
+ * than the old `"development" || "test"`: a staging build that never sets
+ * `NODE_ENV=production` gets the drift report, raw payload included.
  *
  * @param schema - The zod schema to parse against.
  * @param raw - The raw response payload.
  * @param context - A label used in error messages, e.g. "POST /auth/login".
  * @returns The parsed, typed payload.
+ * @throws Error When the payload does not match the schema: `[parseResponse]
+ * Contract drift on <context>` with the field paths and the raw payload in a
+ * development build, `Resposta inválida do servidor (<context>).` otherwise.
  */
 export declare function parseResponse<TSchema extends z.ZodTypeAny>(schema: TSchema, raw: unknown, context: string): z.infer<TSchema>;
 
@@ -9340,6 +9941,87 @@ export declare interface PcmAudio {
     sampleRate: number;
 }
 
+/** A running mesh. */
+export declare interface PeerMesh {
+    /**
+     * Open a link to a peer.
+     *
+     * `offerer` decides which side sends the offer, and exactly one side of each
+     * link must say `true`. Drive it from the arrival order your server already
+     * imposes — the peer that joined **later** offers, the one already in the
+     * room answers. That avoids glare by construction, without the rollback
+     * dance of perfect negotiation and without depending on a browser
+     * implementing argument-less `setLocalDescription`.
+     */
+    addPeer: (peerId: string, options: {
+        offerer: boolean;
+    }) => Promise<void>;
+    /** Close one link and give its share of the uplink back to the others. */
+    removePeer: (peerId: string) => void;
+    /** Feed the mesh an `offer`, `answer` or `ice` message from `from`. */
+    accept: (message: MeshMessage & {
+        from: string;
+    }) => Promise<void>;
+    /**
+     * Publish or retract one slot across every live link.
+     *
+     * `null` retracts: the sender keeps its negotiated transceiver and stops
+     * producing, which is what mutes a microphone without disturbing the other
+     * slots or the connection. Nothing renegotiates — the m-lines were allocated
+     * before any track existed, which is what makes a mesh survive toggling: a
+     * renegotiation per toggle is N-1 simultaneous offer/answer rounds every time
+     * somebody unmutes.
+     */
+    setLocalTrack: (slot: string, track: MediaStreamTrack | null) => Promise<void>;
+    /** Apply encoder limits, divided by the current size of the room. */
+    applyQuality: (quality: MeshQuality) => Promise<void>;
+    /** Replace the ICE servers used for links opened from now on. */
+    setIceServers: (servers: RTCIceServer[]) => void;
+    /** Close every link and report `closed`. */
+    stop: () => void;
+    /** The peers as the mesh currently sees them. */
+    readonly peers: MeshPeer[];
+}
+
+/** Options for `createPeerMesh`. */
+export declare interface PeerMeshOptions {
+    /** The lanes every link negotiates, in the order they are allocated. */
+    slots: readonly MeshSlot[];
+    /** Send one message to the peer named by `to`. The transport is yours. */
+    send: (message: MeshMessage) => void;
+    /** ICE servers for every connection this mesh opens. */
+    iceServers?: RTCIceServer[];
+    /** Called whenever the peer list or any peer's streams change. */
+    onPeers?: (peers: MeshPeer[]) => void;
+    /** Called when the aggregate state changes, with an optional detail. */
+    onState?: (state: MeshState, detail?: string) => void;
+    /** Called for a failure worth surfacing that is not fatal to the mesh. */
+    onNotice?: (reason: string) => void;
+    /** Initial encoder limits. */
+    quality?: MeshQuality;
+    /**
+     * Applies a local description, so the SDP can be rewritten on the way out.
+     *
+     * Defaults to `connection.setLocalDescription(description)`. The reason it
+     * is a seam is `setTunedLocalDescription`: the mesh is what creates every
+     * offer and answer, so without a hook here there is nowhere left to put the
+     * Opus rewrite, and a call that adopts the mesh silently loses the bitrate
+     * and channel layout it had negotiated before.
+     *
+     * Profiles are keyed by **audio m-line position**, which is legitimate for
+     * exactly the reason slot routing is: the slot list fixes the order, so the
+     * first audio slot is always the first audio m-line.
+     *
+     * @example
+     * setLocalDescription: (connection, description) =>
+     *     setTunedLocalDescription(connection, description, {
+     *         0: MIC_PROFILE,
+     *         1: SYSTEM_AUDIO_PROFILE,
+     *     }),
+     */
+    setLocalDescription?: (connection: RTCPeerConnection, description: RTCSessionDescriptionInit) => Promise<unknown>;
+}
+
 /**
  * What percentage of `total` is `part`, with an empty base yielding `0`.
  *
@@ -9597,8 +10279,13 @@ export declare interface PopoverProps {
  * Renders its children into a different part of the DOM tree via a React portal.
  *
  * Useful for overlays (modals, tooltips, dropdowns) that must escape parent
- * overflow/stacking contexts. Defaults to `document.body` when no `container`
- * is provided.
+ * overflow/stacking contexts.
+ *
+ * Without `container` the target is the element currently presented fullscreen,
+ * and `document.body` the rest of the time. `body` alone would be wrong during
+ * fullscreen: the browser paints only the fullscreen element's subtree, so an
+ * overlay mounted outside it is invisible and unclickable while looking perfectly
+ * healthy in the DOM. Passing `container` opts out of that and pins the target.
  *
  * SSR-safe: renders `null` on the server and on the first client render, then
  * mounts the portal after hydration (when `document` is available).
@@ -9611,7 +10298,12 @@ export declare function Portal({ children, container }: PortalProps): ReactNode;
 export declare interface PortalProps {
     /** Content rendered through the portal. */
     children: ReactNode;
-    /** Target DOM node to render into. Defaults to `document.body`. */
+    /**
+     * Target DOM node to render into.
+     *
+     * Defaults to the fullscreen element while one is presented, and to
+     * `document.body` otherwise.
+     */
     container?: Element | null;
 }
 
@@ -9645,7 +10337,7 @@ export declare interface PostHogLike {
 }
 
 /** A lazy component that can also be fetched ahead of being rendered. */
-export declare type PreloadableLazy<T extends ComponentType<unknown>> = ReturnType<typeof lazy<T>> & {
+export declare type PreloadableLazy<T extends AnyComponent> = ReturnType<typeof lazy<T>> & {
     /**
      * Start fetching the chunk now, before anything renders it.
      *
@@ -9743,6 +10435,20 @@ export declare interface PullPage<TRemote> {
     serverTime: string | null;
 }
 
+/**
+ * The keys worth offering for push-to-talk.
+ *
+ * Identified by `code` rather than `key` so a binding survives a layout change:
+ * on an ABNT2 keyboard the `key` reported for the backquote position is not what
+ * a US layout reports, while `Backquote` is the same physical key everywhere.
+ *
+ * Left-hand modifiers only. The right-hand ones sit under the hand that is
+ * usually on the mouse, and a modifier that is also a shortcut prefix
+ * (`ControlLeft` with a browser shortcut) is a deliberate trade the caller makes
+ * by choosing it.
+ */
+export declare const PUSH_TO_TALK_KEYS: readonly PushToTalkKey[];
+
 /**
  * Service-worker context helpers for handling `push` and `notificationclick`
  * events. Import these inside your own `sw.ts` — they expect to run in the
@@ -9767,6 +10473,23 @@ export declare interface PushPayload {
     data?: Record<string, unknown>;
 }
 
+/** A key offered for push-to-talk, with the label a settings screen shows. */
+export declare interface PushToTalkKey {
+    /** `KeyboardEvent.code`, which is layout-independent. */
+    code: string;
+    /** What to show a person. `code` itself is not a label. */
+    label: string;
+}
+
+/**
+ * The label to show for a `KeyboardEvent.code`.
+ *
+ * @param code - The bound key's code.
+ * @returns Its label, or the code itself for a key this list does not name —
+ *     showing `"F13"` beats showing nothing.
+ */
+export declare function pushToTalkKeyLabel(code: string): string;
+
 /** Raised when a payload cannot be encoded at the requested level. */
 export declare class QRCapacityError extends Error {
     readonly length: number;
@@ -10030,6 +10753,29 @@ export declare function readableForeground(background: string, light?: string, d
  */
 export declare function readDeviceProfile(): DeviceProfile;
 
+/**
+ * Read the round trip of the candidate pair actually carrying the link.
+ *
+ * A connection routinely keeps several viable pairs alive at once — host,
+ * server-reflexive, relayed — and only one of them carries traffic. Reading the
+ * first `succeeded` pair makes the number jump between paths that are not being
+ * travelled: 8 ms on an idle host pair alternating with 180 ms on the TURN pair
+ * doing the work. The pair the transport names in `selectedCandidatePairId` is
+ * the one being used.
+ *
+ * A succeeded pair is kept as a fallback because not every browser fills that
+ * field in — losing the reading entirely is worse than an occasionally
+ * optimistic one.
+ *
+ * @param report - A report from `RTCPeerConnection.getStats()`.
+ * @returns Round trip in milliseconds, rounded, or `null` when nothing reported
+ *   one — which is the normal state before the connection settles.
+ *
+ * @example
+ * const rttMs = readRoundTripMs(await pc.getStats());
+ */
+export declare function readRoundTripMs(report: RTCStatsReport): number | null;
+
 /**
  * Read a token's computed value from an element (default: `<html>`).
  *
@@ -10116,7 +10862,19 @@ export declare interface RegisterPeriodicSyncOptions {
  *
  * Skips silently when the runtime has no `serviceWorker` support. The host
  * app keeps full control over the SW file — this helper only handles the
- * boilerplate around `register()` and `updatefound`.
+ * boilerplate around `register()` and update detection.
+ *
+ * Two things can mean "an update is ready", and only one of them is an event.
+ * `updatefound` covers the worker that installs while this tab is open. The
+ * commoner case has no event at all: the user visited after a deploy, the new
+ * worker installed and went to `waiting`, they closed the tab, and they are back
+ * now. `install` already happened, so nothing fires — which is why `waiting` is
+ * read directly once the registration resolves. Both routes go through the same
+ * dedupe, so a worker is announced once even when both apply.
+ *
+ * Neither route fires without `navigator.serviceWorker.controller`: no
+ * controller means this is the first install, which is `onReady` territory, not
+ * an update the user should be prompted about.
  *
  * With `autoUpdate` enabled it additionally polls `registration.update()` on
  * an interval and (by default) reloads the page when a freshly activated worker
@@ -10138,6 +10896,10 @@ export declare interface RegisterServiceWorkerOptions {
      * Called when a new worker has finished installing while another worker
      * still controls the page. The host app typically prompts the user to
      * reload and then calls {@link skipWaiting} on the returned worker.
+     *
+     * Fires for a worker that was already `waiting` when `register()` resolved
+     * — the state a user returning after a deploy actually finds — as well as
+     * for one that installs during this session, and at most once per worker.
      */
     onUpdate?: (waiting: ServiceWorker, registration: ServiceWorkerRegistration) => void;
     /** Called on registration failure. */
@@ -10283,6 +11045,22 @@ export declare interface ResizableProps extends Omit<HTMLAttributes<HTMLDivEleme
     children: [ReactNode, ReactNode];
 }
 
+/**
+ * Decide what the encoder gives up, letting physics override the preference.
+ *
+ * `maintain-framerate` is honoured while there are bits enough for the frames to
+ * be worth keeping. Once the room's division has taken the budget below the
+ * fluid floor, holding the rate halves what each frame receives and the picture
+ * is worse than the lower rate it replaced — so below that line the preference
+ * is overridden rather than obeyed.
+ *
+ * @param quality - What was asked for.
+ * @param effective - What the room's share actually allows.
+ * @returns The degradation preference to write onto the senders, or `undefined`
+ *     when the caller expressed no preference.
+ */
+export declare function resolveDegradation(quality: MeshQuality, effective: MeshQuality): RTCDegradationPreference | undefined;
+
 export declare type ResolvedTheme = "light" | "dark";
 
 /**
@@ -10484,22 +11262,40 @@ export { Route }
 
 /**
  * Declarative route guard built on React Router's `<Navigate>`. Renders its
- * children when `when` is truthy, otherwise redirects. Pairs naturally with
- * `createAuthStore` for protected areas.
+ * children when `when` is `true`, redirects when it is `false`, and holds on
+ * `"pending"`. Pairs naturally with `createAuthStore` for protected areas, and
+ * with `useCan` for permissions that resolve over the network.
  *
  * @example
  * <RouteGuard when={useAuthStore((s) => s.isAuthenticated)} redirectTo="/login">
  *     <Outlet />
  * </RouteGuard>
+ *
+ * @example
+ * const { allowed, isLoading } = useCan({ action: "read", resource: "finance" });
+ *
+ * <RouteGuard when={isLoading ? "pending" : allowed} fallback={<Spinner />}>
+ *     <Outlet />
+ * </RouteGuard>
  */
-export declare function RouteGuard({ when, redirectTo, replace, children }: RouteGuardProps): JSX.Element;
+export declare function RouteGuard({ when, fallback, redirectTo, replace, children, }: RouteGuardProps): JSX.Element;
 
 export declare interface RouteGuardProps {
     /**
-     * Whether access is allowed. Pass a boolean or anything truthy/falsy —
-     * typically `useAuthStore((s) => s.isAuthenticated)`.
+     * Whether access is allowed — typically
+     * `useAuthStore((s) => s.isAuthenticated)`.
+     *
+     * `"pending"` is the third answer, for a permission that has not resolved
+     * yet: it holds the decision and renders {@link fallback} instead of
+     * choosing between two wrong moves — redirecting someone who does have
+     * access, or showing the screen to someone who does not.
+     */
+    when: RouteGuardResult;
+    /**
+     * Rendered while `when` is `"pending"`. Defaults to nothing, which is a
+     * blank screen — pass the same spinner the rest of the app uses.
      */
-    when: boolean;
+    fallback?: ReactNode;
     /** Where to redirect when `when` is falsy (default: `"/"`). */
     redirectTo?: string;
     /** Replace history entry on redirect instead of pushing (default: true). */
@@ -10508,6 +11304,19 @@ export declare interface RouteGuardProps {
     children: ReactNode;
 }
 
+/**
+ * What a route guard can answer.
+ *
+ * `true` renders the route, `false` redirects — and `"pending"` is the third
+ * answer a two-state guard cannot give. Without it, a permission that resolves
+ * asynchronously has to lie while it is in flight, and both lies are wrong:
+ * answering `false` redirects the person who **does** have the permission,
+ * every time the route is opened cold (F5 on the URL, an external link);
+ * answering `true` renders the screen for someone who does not, until the
+ * answer lands.
+ */
+export declare type RouteGuardResult = boolean | "pending";
+
 /** Router history strategy used by {@link AppRouter}. */
 export declare type RouterKind = "browser" | "hash" | "memory";
 
@@ -10601,6 +11410,26 @@ export declare interface SafeAreaProps extends HTMLAttributes<HTMLDivElement> {
     children?: ReactNode;
 }
 
+/**
+ * Divide the video caps by the size of the room.
+ *
+ * A mesh sends one copy of everything per participant, so the uplink is the
+ * shared resource and the caps are what compete for it. Nothing is divided while
+ * the caller is alone with one peer — that is the case the largest sizes exist
+ * for, and dividing a budget that is not being shared would make them
+ * unreachable in the only call where they fit.
+ *
+ * The floor is what keeps the division honest: without it a busy room allocates
+ * tens of kbps per stream, and everybody loses the picture instead of the excess
+ * giving way.
+ *
+ * @param quality - The caps as asked for.
+ * @param peers - How many links are live.
+ * @returns The caps to actually apply. The input is never mutated, so a room
+ *     that empties out climbs back to what was asked for.
+ */
+export declare function scaleForRoom(quality: MeshQuality, peers: number): MeshQuality;
+
 /** The ten steps of a Tempest tint scale, lightest to darkest. */
 export declare type ScaleStep = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
 
@@ -11649,6 +12478,19 @@ export { StorageEstimate_2 as StorageEstimate }
 
 export { SubmitHandler }
 
+/**
+ * Turn a measured noise floor into a threshold worth using.
+ *
+ * Sits above the floor by a margin rather than on it, and is clamped at both
+ * ends: a room measured as perfectly silent (or not measured at all) would
+ * otherwise get a threshold of zero, which is a gate that never closes, and a
+ * room measured while somebody talked would get one nothing opens.
+ *
+ * @param noiseFloor - Peak RMS measured while nobody spoke.
+ * @returns A threshold for {@link VoiceChainSettings.gateThreshold}, `0.004..0.12`.
+ */
+export declare function suggestGateThreshold(noiseFloor: number): number;
+
 /** Toggle switch backed by a checkbox input. Accessible via keyboard. */
 export declare const Switch: ForwardRefExoticComponent<SwitchProps & RefAttributes<HTMLInputElement>>;
 
@@ -12010,15 +12852,30 @@ export declare interface TempestRouteObject {
      * under the {@link AppRouter} `<Suspense>` boundary.
      */
     lazy?: () => Promise<{
-        default: ComponentType<unknown>;
+        default: AnyRouteComponent;
     }>;
     /** Nested child routes (rendered through this route's `<Outlet />`). */
     children?: TempestRouteObject[];
     /**
      * Access guard. When `false` (or a function returning `false`), the route
-     * renders a redirect to {@link redirectTo} instead of its element.
+     * renders a redirect to {@link redirectTo} instead of its element. When the
+     * function returns `"pending"`, the decision is held and {@link guardFallback}
+     * renders instead — see {@link RouteGuardResult}.
+     *
+     * The function runs inside the guard component's render, so it **may call
+     * hooks** — which is what lets an async permission check like `useCan` plug
+     * straight in. The usual rule applies: call the same hooks on every render
+     * of that route. Guarded routes are keyed per route object, so navigating
+     * between two routes whose guards call different hooks remounts rather than
+     * breaking hook order.
+     */
+    guard?: boolean | (() => RouteGuardResult);
+    /**
+     * Rendered while {@link guard} answers `"pending"`. Defaults to the
+     * {@link AppRouter} `fallback`, so a route tree that already passes a
+     * spinner for `lazy` chunks reuses it here with no extra wiring.
      */
-    guard?: boolean | (() => boolean);
+    guardFallback?: ReactNode;
     /** Destination used when `guard` fails (default: `"/"`). */
     redirectTo?: string;
     /** Match the path case-sensitively. */
@@ -13599,6 +14456,71 @@ export { UseFormReturn }
 
 export { useFormState }
 
+/**
+ * Drive an immersive mode whose state stays true to the browser.
+ *
+ * The mistake this exists to remove is storing `isFullscreen` in state and
+ * flipping it inside your own `enter()` / `exit()`. Fullscreen ends in ways your
+ * code never sees — `Esc`, the browser's own exit affordance, F11 pressed while an
+ * API fullscreen is active — and each of those leaves the flag saying "sair" over
+ * a page that is already windowed. The only honest source is the
+ * `fullscreenchange` event, which fires for every one of them, so that is what
+ * this hook reads and what the returned `isFullscreen` reflects. The action
+ * callbacks never touch it.
+ *
+ * The subscription is not this hook's own: it lives in `useFullscreenElement`,
+ * shared with `usePortalHost`, which needs the same fact to decide where an
+ * overlay mounts while fullscreen is on. Two independent listeners for one event
+ * would mean two copies of the WebKit prefix dance and two places to fix the next
+ * quirk, so the primitive answers "which element is presented" once and each
+ * consumer asks its own question of the answer.
+ *
+ * WebKit's prefixed members are handled throughout — `webkitfullscreenchange`,
+ * `webkitFullscreenElement`, `webkitRequestFullscreen`, `webkitExitFullscreen` —
+ * because Safari on iPad still ships them and nothing else.
+ *
+ * `isFullscreen` is identity against the target, not containment: a `<video>`
+ * inside your element going fullscreen on its own is not your element being
+ * presented, and reporting `true` there would put your exit control inside a
+ * subtree the browser is not painting.
+ *
+ * @param ref - The element to present. Omit it to present the whole page
+ * (`document.documentElement`).
+ * @returns `{ isFullscreen, supported, enter, exit, toggle }`.
+ * @throws Nothing during render. `enter()` and `toggle()` reject with the
+ * browser's own error when the request is refused — most often a `TypeError`
+ * because the call did not come from a user gesture — and with an `Error` when
+ * there is no element to present or the environment ships no Fullscreen API.
+ *
+ * @example
+ * const stage = useRef<HTMLDivElement>(null);
+ * const { isFullscreen, supported, toggle } = useFullscreen(stage);
+ *
+ * <div ref={stage}>
+ *   <video src="/aula.mp4" controls />
+ *   {supported ? (
+ *     <button onClick={() => void toggle().catch(() => setRefused(true))}>
+ *       {isFullscreen ? "Sair da tela cheia" : "Tela cheia"}
+ *     </button>
+ *   ) : null}
+ * </div>
+ */
+export declare function useFullscreen(ref?: RefObject<HTMLElement | null>): UseFullscreenResult;
+
+/** Value returned by {@link useFullscreen}. */
+export declare interface UseFullscreenResult {
+    /** Whether the target element is the one the browser is presenting right now. */
+    isFullscreen: boolean;
+    /** Whether a request stands a chance at all — hide the control when `false`. */
+    supported: boolean;
+    /** Present the target. Must be called from a user gesture. Rejects if refused. */
+    enter: () => Promise<void>;
+    /** Leave fullscreen. Resolves immediately when nothing is presented. */
+    exit: () => Promise<void>;
+    /** Leave if the target is presented, otherwise enter. Same gesture rule as `enter`. */
+    toggle: () => Promise<void>;
+}
+
 /**
  * React hook around the Geolocation API.
  *
@@ -13813,6 +14735,51 @@ export declare interface UseKeyboardShortcutOptions {
  */
 export declare function useLatestRef<T>(value: T): RefObject<T>;
 
+/**
+ * Poll one connection's throughput, resolution and round trip.
+ *
+ * Sampling runs only while the connection is `"connected"`, so a link that is
+ * still negotiating or already gone costs nothing. The last reading is kept
+ * across pauses rather than cleared, because a badge that blanks every time the
+ * tab loses focus reads as a broken connection.
+ *
+ * Coming back from a pause resets the baseline first. Without that, the sample
+ * after a five-minute background stretch divides five minutes of bytes by five
+ * minutes and reports the average of a period the person is not asking about.
+ *
+ * @param connection - The connection to watch, or `null` before one exists.
+ * @param options - See {@link UseLinkStatsOptions}.
+ * @returns The latest reading, or `null` before the first sample lands.
+ *
+ * @example
+ * const stats = useLinkStats(pc);
+ *
+ * return <span>{stats ? `${stats.kbps} kbps · ${stats.rttMs ?? "—"} ms` : "medindo…"}</span>;
+ */
+export declare function useLinkStats(connection: RTCPeerConnection | null, options?: UseLinkStatsOptions): LinkStats | null;
+
+/** Options for {@link useLinkStats}. */
+export declare interface UseLinkStatsOptions {
+    /**
+     * How often to sample, in milliseconds. Default `2000`.
+     *
+     * `getStats()` walks every report a connection holds, and a mesh runs one
+     * per participant — on the device least able to pay for it. The numbers feed
+     * a latency badge and a throughput figure nobody reads at 1 Hz, so the
+     * default is deliberately slower than a frame budget suggests.
+     */
+    intervalMs?: number;
+    /**
+     * Stop sampling while the tab is in the background. Default `true`.
+     *
+     * The audio path is untouched by this — people in a backgrounded call still
+     * expect to hear it. What stops is the measuring, which nobody can see.
+     */
+    pauseWhenHidden?: boolean;
+    /** Which media the throughput counts. Default `"video"`. */
+    kind?: LinkStatsKind;
+}
+
 /**
  * Query a paginated list of a resource through the active {@link useDataProvider}.
  *
@@ -14758,6 +15725,57 @@ export declare interface UsePushSubscriptionResult {
     refresh: () => Promise<void>;
 }
 
+/**
+ * Hold a key to transmit; release it to go silent again.
+ *
+ * Looks like `keydown`/`keyup` and is not, because three things go wrong:
+ *
+ * 1. **`blur` has to release.** Alt-tabbing away while holding the key means the
+ *    browser never sees the `keyup`, and the microphone stays open for as long as
+ *    the person is looking at another window — exactly what push-to-talk exists
+ *    to prevent.
+ * 2. **Auto-repeat has to be ignored.** A held key repeats at the keyboard's rate,
+ *    and without the `repeat` check `onDown` fires on every one of them.
+ * 3. **A text field has to win.** Space bound to push-to-talk with the focus in an
+ *    `<input>` means the space never reaches the message being written.
+ *
+ * Unmounting releases too, for the same reason `blur` does: the callback that
+ * stops transmitting has to run even when the component holding it goes away
+ * mid-press.
+ *
+ * The callbacks are read through a ref that a commit-time effect refreshes, so
+ * passing inline arrows neither tears the listeners down on every render nor
+ * writes to the ref during one — a render React discards would leave the ref
+ * pointing at callbacks that never became the UI.
+ *
+ * @param options - See {@link UsePushToTalkOptions}.
+ *
+ * @example
+ * usePushToTalk({
+ *     code: "Space",
+ *     onDown: () => setMicEnabled(true),
+ *     onUp: () => setMicEnabled(false),
+ * });
+ */
+export declare function usePushToTalk({ code, onDown, onUp, enabled, }: UsePushToTalkOptions): void;
+
+/** Options for {@link usePushToTalk}. */
+export declare interface UsePushToTalkOptions {
+    /** `KeyboardEvent.code` to hold. Default {@link DEFAULT_PUSH_TO_TALK_KEY}. */
+    code?: string;
+    /** Called once when the key goes down. */
+    onDown: () => void;
+    /** Called when the key comes up, the window blurs, or the hook unmounts. */
+    onUp: () => void;
+    /**
+     * Whether the binding is live. Default `true`.
+     *
+     * Turning it off releases first, so flipping a call from push-to-talk to an
+     * open microphone while the key is held does not leave `onUp` unfired.
+     */
+    enabled?: boolean;
+}
+
 /**
  * FIFO queue with an optional `limit`. When more items are added than `limit`
  * allows, the surplus is kept in an internal overflow buffer and surfaces into
@@ -16111,6 +17129,98 @@ export declare interface VisuallyHiddenProps extends HTMLAttributes<HTMLElement>
     as?: keyof JSX.IntrinsicElements;
 }
 
+/** A running voice-activity monitor. */
+export declare interface VoiceActivityMonitor {
+    /** Whether the track is currently carrying speech. */
+    readonly speaking: boolean;
+    /** Stop sampling and release the analysis graph. */
+    stop: () => void;
+}
+
+/** Options for {@link monitorVoiceActivity}. */
+export declare interface VoiceActivityOptions {
+    /** RMS at or above which a window counts as speech. Default `0.045`. */
+    threshold?: number;
+    /** How long the state stays `true` after the level drops. Default `350`. */
+    releaseMs?: number;
+    /** How often the level is sampled, in ms. Default `100`. */
+    pollMs?: number;
+    /**
+     * Reuse an existing `AudioContext` instead of creating one.
+     *
+     * A monitor per remote participant hits the browser's cap on live contexts
+     * (Chrome allows around six) in a five-person call. Open one and share it.
+     */
+    context?: AudioContext;
+}
+
+/** A running voice chain. */
+export declare interface VoiceChain {
+    /** The processed track to publish. */
+    track: MediaStreamTrack;
+    /** Stop the detectors, disconnect the graph, and release the track. */
+    release: () => void;
+    /**
+     * Whether a graph was actually built.
+     *
+     * `false` when this engine has no Web Audio, and also when the settings asked
+     * for nothing — in both cases `track` is `source`, untouched.
+     */
+    readonly supported: boolean;
+}
+
+/** Options for {@link createVoiceChain}. */
+export declare interface VoiceChainOptions {
+    /** Output multiplier, applied after every stage and before the limiter. Default `1`. */
+    gain?: number;
+    /**
+     * Reuse an existing `AudioContext` instead of creating one.
+     *
+     * Browsers cap live contexts (Chrome allows around six), so a page that already
+     * has one — a level meter, an audio bus — should hand it over.
+     */
+    context?: AudioContext;
+    /**
+     * Whether `release()` also stops `source`. Default `true`.
+     *
+     * Pass `false` when the track belongs to somebody else: a settings dialog
+     * building a second chain over its live preview would otherwise kill the meter
+     * the person is watching while they listen.
+     */
+    ownsSource?: boolean;
+}
+
+/** Which stages a voice chain builds. */
+export declare interface VoiceChainSettings {
+    /** Cut everything below speech: fans, traffic rumble, desk knocks, plosives. */
+    highPass: boolean;
+    /** Silence the line when nobody is talking. */
+    gate: boolean;
+    /** RMS below which the gate closes, 0..1. See {@link suggestGateThreshold}. */
+    gateThreshold: number;
+    /** Even out the distance between a whisper and a shout. */
+    compressor: boolean;
+    /** Lift the consonant band so speech reads without getting louder. */
+    presence: boolean;
+    /** Roll off hiss above what speech uses. */
+    hissCut: boolean;
+    /** Ride down harsh S and CH sounds. */
+    deEsser: boolean;
+    /**
+     * Hard ceiling before the signal leaves.
+     *
+     * On by default and worth leaving on: the leveller is 3:1, which controls the
+     * average and lets a peak through, and `gain` can reach well above 1.
+     */
+    limiter: boolean;
+}
+
+/** A running monitor. */
+export declare interface VoiceMonitor {
+    /** Stop listening and release the graph. Does **not** stop the source track. */
+    stop: () => void;
+}
+
 /**
  * Pluggable persistence for the pull watermark (the "changed since" cursor).
  * Pass an object with a `storageKey` to use a `localStorage`-backed default.