tempest-react-sdk 0.51.0 → 0.53.0

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

@@ -1059,6 +1059,88 @@ export declare type AsyncStatus = "idle" | "pending" | "success" | "error";
  */
 export declare const AUDIO_MIME_CANDIDATES: readonly string[];
 
+/** A running mix. */
+export declare interface AudioBus {
+    /**
+     * Play a stream through the shared mix.
+     *
+     * @param stream - The stream to play. Only its first audio track is used.
+     * @param options - `gain` is the initial multiplier, default `1`.
+     * @returns A handle to adjust or detach this source.
+     */
+    attach: (stream: MediaStream, options?: {
+        gain?: number;
+    }) => AudioBusHandle;
+    /** Scale every source, on top of its own gain. */
+    setMasterGain: (gain: number) => void;
+    /** Current master gain, after clamping. */
+    readonly masterGain: number;
+    /**
+     * Route the whole mix to one output device.
+     *
+     * @param deviceId - Device id from `useMediaDevices().audioOutputs`, or `""`
+     *   for the system default.
+     * @returns `false` when the engine cannot route audio, or the device is gone.
+     */
+    setOutputDevice: (deviceId: string) => Promise<boolean>;
+    /** Device id the mix is routed to. `""` is the system default. */
+    readonly outputDevice: string;
+    /**
+     * Resume a context the browser started suspended.
+     *
+     * Autoplay policy suspends a context created outside a user gesture, and a
+     * suspended context is silent with no error anywhere. Call this from the
+     * click that starts playback.
+     */
+    resume: () => Promise<void>;
+    /**
+     * Detach everything and close the context this bus created.
+     *
+     * Idempotent, and the bus stays callable afterwards: `attach` hands back an
+     * inert handle instead of throwing. That is not politeness — creating a node
+     * on a closed `AudioContext` throws `InvalidStateError`, and the stream that
+     * arrives late is the normal case (a WebRTC `ontrack` firing after the
+     * component that owned the bus went away).
+     */
+    close: () => void;
+    /** Whether this browser gave us a Web Audio graph at all. */
+    readonly supported: boolean;
+    /** Whether this browser can route the mix to a chosen output device. */
+    readonly canSelectOutput: boolean;
+}
+
+/** One source attached to the bus. */
+export declare interface AudioBusHandle {
+    /**
+     * Set this source's gain, where `1` is the level it arrived at.
+     *
+     * Values above `1` are the point of the whole graph: `element.volume` is
+     * clamped at `1`, so a quiet talker could only ever be attenuated — the one
+     * correction nobody needs.
+     */
+    setGain: (gain: number) => void;
+    /** Current gain, after clamping. */
+    readonly gain: number;
+    /** Detach this source and release its nodes. The bus stays up. */
+    stop: () => void;
+}
+
+/** Options for {@link createAudioBus}. */
+export declare interface AudioBusOptions {
+    /** Ceiling for every gain on this bus. Default {@link DEFAULT_MAX_GAIN}. */
+    maxGain?: number;
+    /** Override the master limiter, or pass `false` to run without one. */
+    limiter?: Partial<LimiterSettings> | false;
+    /**
+     * Reuse an existing `AudioContext` instead of creating one.
+     *
+     * Browsers cap the number of live contexts (Chrome allows around six), so a
+     * page that already has one — a level meter, a player — should hand it over
+     * rather than open a second.
+     */
+    context?: AudioContext;
+}
+
 /**
  * Playback transport for one clip: play/pause, a seek bar, elapsed and total time.
  *
@@ -2910,6 +2992,34 @@ export declare const CPFInput: ForwardRefExoticComponent<Omit<InputProps, "value
  */
 export declare function createApiClient(config: ApiClientConfig): ApiClient;
 
+/**
+ * Mix several streams into one output, with gain above 100% and a master limiter.
+ *
+ * Three things make this a graph instead of a few `<audio>` elements:
+ *
+ * 1. **`element.volume` is clamped at `1`.** A participant who speaks too quietly
+ *    can only be turned *down* — the one correction nobody needs. A `GainNode`
+ *    has no ceiling, so this bus takes one (`maxGain`, default 3).
+ * 2. **Clipping is a property of the sum.** Three sources at 200% each are clean
+ *    alone and distort the instant they play together. A per-source limiter
+ *    cannot see that; the one after the mix can, which is where this puts it.
+ * 3. **`setSinkId` lives on the element, not on the context.** Sending the mix to
+ *    a headset while the rest of the system keeps the speakers is only reachable
+ *    by leaving through a `MediaStreamAudioDestinationNode` into a real
+ *    `<audio>`. `AudioContext.setSinkId` has far thinner support.
+ *
+ * @param options - See {@link AudioBusOptions}.
+ * @returns The bus. On an engine with no Web Audio it is inert but callable, and
+ *   `supported` is `false` — a page without sound beats a page that throws.
+ *
+ * @example
+ * const bus = createAudioBus({ maxGain: 3 });
+ * const handle = bus.attach(remoteStream, { gain: 1 });
+ * handle.setGain(2.4);              // above 1 — the point of the whole thing
+ * await bus.setOutputDevice(headsetId);
+ */
+export declare function createAudioBus({ maxGain, limiter: limiterOptions, context: injectedContext, }?: AudioBusOptions): AudioBus;
+
 /**
  * Create an isolated audio player that tracks a single "current" clip.
  * Multiple players coexist independently; use this when several layers of UI
@@ -3320,6 +3430,60 @@ export declare interface CreateLoggerOptions {
  */
 export declare function createMediaRecorder(stream: MediaStream, options: MediaRecordingOptions): MediaRecorderHandle;
 
+/**
+ * Build several {@link OfflineStore}s that share one IndexedDB database.
+ *
+ * `createOfflineStore` gives each store a database of its own, which is the
+ * right shape for one isolated cache. It is the wrong shape as soon as the
+ * tables belong together: chats and their messages, an entity and its drafts,
+ * anything you would read or clear as a unit. Splitting those across databases
+ * costs a real transaction — Dexie runs one atomically only *within* a single
+ * database — and it splits the version bump for a related change across two
+ * places.
+ *
+ * This keeps them in one database at one version, so a schema change is one
+ * bump and a multi-table write can be wrapped in `db.transaction(...)`.
+ *
+ * Stores are reached through `store<TItem>(name)` rather than a prebuilt map.
+ * That is forced rather than chosen: Dexie's `Table<T>` expands `UpdateSpec<T>`
+ * over the keys of `T`, so building `{ [K in keyof TSchema]: OfflineStore<…> }`
+ * — or even naming `OfflineStore<TSchema[K], string>` inside the accessor —
+ * makes the checker answer TS2589 ("excessively deep"). Taking the record type
+ * as a parameter keeps it a plain type argument, which resolves fine. The table
+ * name is still checked against the declared schema.
+ *
+ * The store surface is identical to `createOfflineStore`; only ownership of the
+ * database changes. `ownerField` is set per table, since a database commonly
+ * mixes per-user data with shared data.
+ *
+ * @param config - Database name, version, and one entry per table.
+ * @returns A `store(name)` accessor, the shared Dexie instance, and a
+ *   `destroy()` that drops the database.
+ *
+ * @example
+ * type Chat = { id: string; service_id: string; updated_at: string };
+ * type Message = { id: string; service_chat_id: string; created_at: string };
+ *
+ * const database = createOfflineDatabase<{ chats: Chat; messages: Message }>({
+ *     databaseName: "ChatDatabase",
+ *     version: 1,
+ *     tables: {
+ *         chats: { indexes: "&id, service_id, updated_at" },
+ *         messages: { indexes: "&id, service_chat_id, created_at" },
+ *     },
+ * });
+ *
+ * const chats = database.store<Chat>("chats");
+ * const messages = database.store<Message>("messages");
+ *
+ * // Both tables in one atomic transaction — impossible across two databases.
+ * await database.db.transaction("rw", chats.raw, messages.raw, async () => {
+ *     await chats.put(chat);
+ *     await messages.bulkPut(pending);
+ * });
+ */
+export declare function createOfflineDatabase<TSchema extends OfflineSchema>(config: OfflineDatabaseConfig<TSchema>): OfflineDatabase<TSchema>;
+
 /**
  * Build a typed IndexedDB-backed store using Dexie. Optionally scope every
  * operation by an `ownerField` (useful for multi-user SSE history, drafts,
@@ -3561,14 +3725,44 @@ export declare function createQueryKeys<TKey extends string, TEntries extends Re
  * at once, all of them share the same in-flight `refresh()` promise instead
  * of triggering N parallel refreshes.
  *
+ * **In-flight sharing alone does not collapse a burst.** A page that fires
+ * several requests at once gets several 401s back, but they do not land inside
+ * one window: the stragglers arrive after the first refresh already resolved,
+ * find no promise to join, and each starts another one — rotating a token that
+ * is already fresh. Measured against a mock backend, five concurrent expired
+ * requests took two refreshes, not one.
+ *
+ * Pass `getToken` to close that gap. The queue remembers the token its last
+ * refresh produced, and a call that finds that same token still in place returns
+ * immediately, because the refresh it was about to perform has already happened.
+ * The same five requests then take exactly one refresh, and so do twenty.
+ *
+ * @param refresh - Performs the refresh and installs the new credentials.
+ * @param options - Optional token reader that enables already-refreshed
+ *   detection.
+ * @returns A function that refreshes at most once per rotation.
+ *
  * @example
- * const refresh = createRefreshQueue(() => AuthService.refresh());
+ * const refresh = createRefreshQueue(() => AuthService.refresh(), {
+ *     getToken: () => useAuthStore.getState().token,
+ * });
  *
  * // In every request that hits 401:
  * await refresh();
  * // ...retry the original request
  */
-export declare function createRefreshQueue(refresh: () => Promise<void>): () => Promise<void>;
+export declare function createRefreshQueue(refresh: () => Promise<void>, options?: CreateRefreshQueueOptions): () => Promise<void>;
+
+export declare interface CreateRefreshQueueOptions {
+    /**
+     * Reads the credential the refresh installs — typically the access token.
+     *
+     * Supplying it makes the queue skip a refresh whose work another caller has
+     * already done. Without it, only calls that literally overlap in time are
+     * collapsed.
+     */
+    getToken?: () => string | null | undefined;
+}
 
 /**
  * Chunked, resumable upload speaking the **tus 1.0.0** protocol (core plus the
@@ -3931,12 +4125,29 @@ export declare interface CreateThemeOptions {
 export declare function createVideoRecorder(stream: MediaStream, options?: VideoRecorderOptions): VideoRecorderHandle;
 
 /**
- * Open a WebSocket with automatic exponential-backoff reconnect, optional
- * heartbeat pings, and typed JSON parsing.
+ * Open a WebSocket that survives a bad network: exponential backoff with jitter,
+ * a handshake timeout, a silence watchdog, optional heartbeat pings and typed
+ * JSON parsing.
+ *
+ * Three failure modes are covered that an event-driven retry loop misses on its
+ * own, because none of them fire an event: a handshake that hangs instead of
+ * failing, an open socket whose link died mid-flight, and a device with its
+ * radio off burning the retry budget. See `handshakeTimeout`, `silenceTimeout`
+ * and `waitForOnline`.
  *
  * @param url - Full ws:// or wss:// URL.
  * @param options - Connection configuration and callbacks.
- * @returns Controller exposing `send`, `close`, `reconnect`, and `status`.
+ * @returns Controller exposing `send`, `close`, `reconnect`, `setSilenceTimeout`,
+ *   `opened` and `status`.
+ *
+ * @example
+ * const socket = createWebSocket(url, {
+ *   silenceTimeout: 75_000,
+ *   onReconnecting: (n, total) => setBanner(`Reconectando ${n}/${total}…`),
+ *   onReconnected: () => refetchEverything(),
+ *   onLost: (reason) => setBanner(reason === "rejected" ? "Acesso negado" : "Sem conexão"),
+ * });
+ * await socket.opened;
  */
 export declare function createWebSocket<T = unknown>(url: string, options?: CreateWebSocketOptions<T>): WebSocketController;
 
@@ -3949,6 +4160,50 @@ export declare interface CreateWebSocketOptions<T> {
     initialBackoff?: number;
     /** Maximum backoff (ms). Default: 30000. */
     maxBackoff?: number;
+    /**
+     * Fraction of each backoff delay added at random, 0–1. Default: 0.3.
+     *
+     * Matters when the *server* is what went down: every client retries on the
+     * same schedule, so the box comes back up into a synchronized stampede. Pass
+     * `0` for a fixed schedule.
+     */
+    jitter?: number;
+    /**
+     * How long one handshake may stay in `CONNECTING` before the attempt is
+     * abandoned and retried (ms). Default: 8000. Pass 0 to disable.
+     *
+     * A `WebSocket` that cannot reach its server does not necessarily fail: it
+     * sits in `CONNECTING` firing neither `open` nor `close` nor `error`. A retry
+     * chain built only on those events stops on its first hung attempt and never
+     * moves again — and hung, rather than refused, is precisely how a bad mobile
+     * link behaves, which is the case reconnection exists for.
+     */
+    handshakeTimeout?: number;
+    /**
+     * Silence tolerated on an open socket before the link is treated as dead (ms).
+     * Default: 0 (off).
+     *
+     * The socket only reports a connection that closes cleanly. A link that dies
+     * mid-flight leaves `readyState` at `OPEN` on this side with nothing ever
+     * arriving again, so silence is the only symptom available. The timer is
+     * re-armed by **any** inbound frame, not just by pings — traffic is traffic.
+     *
+     * Set it to a comfortable multiple of the server's ping interval (2.5× is a
+     * good default) so one dropped ping is not mistaken for an outage. When the
+     * server announces its own interval in the handshake, feed that back with
+     * {@link WebSocketController.setSilenceTimeout} instead of hard-coding the
+     * value on both ends.
+     */
+    silenceTimeout?: number;
+    /**
+     * Suspend the retry schedule while `navigator.onLine` is false, and resume on
+     * the `online` event. Default: true.
+     *
+     * Burning retries against a radio that is switched off is how a phone
+     * exhausts its budget inside a tunnel and gives up exactly when it comes out
+     * the other side.
+     */
+    waitForOnline?: boolean;
     /**
      * Ping interval (ms). When set, the client sends `pingPayload` periodically
      * to keep the socket alive. Default: 0 (disabled).
@@ -3989,6 +4244,34 @@ export declare interface CreateWebSocketOptions<T> {
     onClose?: (event: CloseEvent) => void;
     onError?: (event: Event) => void;
     onStatusChange?: (status: WebSocketStatus) => void;
+    /**
+     * A retry has been scheduled. `attempt` is 1-based, `total` is `maxRetries`.
+     *
+     * Reconnecting is not an error and reads badly as one: announcing every
+     * attempt puts a fresh "the connection dropped" in front of someone whose
+     * session is in the middle of coming back on its own. Show a quiet
+     * reconnecting state here and treat {@link CreateWebSocketOptions.onLost} as
+     * the failure.
+     */
+    onReconnecting?: (attempt: number, total: number) => void;
+    /**
+     * The socket is back up after at least one retry.
+     *
+     * Nothing is resumed for you: a server that keys state by connection sees a
+     * brand-new client, so this is where the caller re-subscribes, re-joins or
+     * refetches whatever the gap invalidated.
+     */
+    onReconnected?: () => void;
+    /**
+     * No further attempt will be made — `"rejected"` when the server refused the
+     * client outright (close code 4400–4499, minus the 4408 heartbeat timeout),
+     * `"exhausted"` when the schedule ran out.
+     *
+     * This is the one that deserves UI, because it is the only state the caller
+     * can act on: offer a "try again" that calls
+     * {@link WebSocketController.reconnect}.
+     */
+    onLost?: (reason: WebSocketLostReason) => void;
 }
 
 /**
@@ -4616,6 +4899,9 @@ export declare const DEFAULT_CHUNK_SIZE: number;
  */
 export declare const DEFAULT_CIRCUITY_FACTOR = 1.3;
 
+/** Default ceiling for a per-source or master gain, as a multiplier. */
+export declare const DEFAULT_MAX_GAIN = 3;
+
 /**
  * Per-mode multipliers applied to the car duration. Mirrors
  * `DEFAULT_MODE_DURATION_FACTORS` from `tempest-fastapi-sdk` — motorcycles are
@@ -4658,6 +4944,9 @@ export declare function defineRoutes(routes: TempestRouteObject[]): TempestRoute
  *
  * The funnel, in order:
  *
+ * 0. `codes[error.code]` — the sentence you wrote for that exact backend case.
+ *    Checked first because nothing the funnel derives can beat it, and because a
+ *    request that never landed carries no `code` for it to shadow.
  * 1. A request that never reached the server — `status === 0`, or a non-API
  *    error thrown while the browser reports itself offline — produces the
  *    offline sentence. This is the step apps skip, and skipping it renders
@@ -4670,7 +4959,8 @@ export declare function defineRoutes(routes: TempestRouteObject[]): TempestRoute
  *    names internals. The per-field messages stay on `fields`, where a form can
  *    attach them to the inputs that failed.
  * 3. The backend's own `detail`, which is the most specific thing available and
- *    is already written for a person.
+ *    is already written for a person — unless `useDetail: false` says that text
+ *    is for developers.
  * 4. `fallback`, with `(HTTP <status>)` appended when a status is known, so the
  *    screenshot in the support ticket carries the one fact a developer needs.
  *
@@ -4683,12 +4973,53 @@ export declare function defineRoutes(routes: TempestRouteObject[]): TempestRoute
  *     toast(describeApiError(error, "Não foi possível salvar o pedido"));
  * }
  *
+ * @example
+ * catch (error) {
+ *     toast(
+ *         describeApiError(error, "Não foi possível se candidatar", {
+ *             codes: {
+ *                 SERVICE_FULL: "Este serviço atingiu o limite de vagas.",
+ *                 CANDIDATE_ALREADY_EXISTS: "Você já se candidatou a este serviço.",
+ *             },
+ *             useDetail: false,
+ *         }),
+ *     );
+ * }
+ *
  * @param error - The caught value, of any shape.
  * @param fallback - What to say when the error carries nothing better.
- * @param strings - Overrides for the fixed sentences.
+ * @param options - A `codes` catalog, `useDetail`, and overrides for the fixed
+ *     sentences.
  * @returns A sentence to show the user.
  */
-export declare function describeApiError(error: unknown, fallback: string, strings?: Partial<ApiErrorStrings>): string;
+export declare function describeApiError(error: unknown, fallback: string, options?: DescribeApiErrorOptions): string;
+
+/**
+ * Everything {@link describeApiError} accepts beyond the error and the fallback.
+ *
+ * Extends the fixed sentences rather than sitting beside them, so a caller that
+ * already passed `{ offline, validation }` keeps compiling untouched.
+ */
+export declare interface DescribeApiErrorOptions extends Partial<ApiErrorStrings> {
+    /**
+     * Maps the backend's programmatic `code` to a sentence in your language.
+     *
+     * The client already surfaces `code` on `ApiError`, but without this every
+     * app writes the same `switch` over it. A hit here wins over every other
+     * step: it is the only sentence written for that exact case, by someone who
+     * knew both the backend contract and the screen it lands on.
+     */
+    codes?: Readonly<Record<string, string>>;
+    /**
+     * Whether the backend's `detail` may be shown when no `code` matched.
+     * Default `true`.
+     *
+     * Set it to `false` when `detail` is written for developers rather than
+     * users, or when it could echo internals — the result is then always either
+     * a sentence you wrote or the fallback.
+     */
+    useDetail?: boolean;
+}
 
 /**
  * One filter, in words: `"Status é Pago"`.
@@ -5667,30 +5998,41 @@ export declare function formatPercent(value: number): string;
 /**
  * Apply the Brazilian phone mask `(XX) XXXXX-XXXX` or `(XX) XXXX-XXXX`.
  *
+ * By default the grouping is decided by **length**, which is what a field
+ * accepting both landlines and mobiles needs.
+ *
+ * `mobile: true` is for a field that only accepts mobile numbers, and it exists
+ * because the default is wrong as an as-you-type mask there. Reading anything up
+ * to ten digits as a landline puts the hyphen after the fourth subscriber digit,
+ * so a half-typed mobile renders `(11) 9123-4`; it only becomes `(11) 91234-5`
+ * once the eleventh digit lands. The separator visibly jumps backwards while the
+ * user is still typing. With `mobile`, the same input reads `(11) 91234` and the
+ * hyphen never moves. It also inserts the leading `9` every Brazilian mobile
+ * carries, so a ten-digit number gets corrected rather than masked as a landline.
+ *
  * @param value - Raw digits or partially masked string.
+ * @param options - Masking options.
  * @returns Masked phone string.
- */
-export declare function formatPhone(value: string): string;
-
-/**
- * Glue between `react-hook-form` `Controller` and the SDK's controlled
- * components. Wraps any control that accepts `{ value, onChange, label,
- * error }` and routes RHF state into it — eliminating the per-field
- * `<Controller render={...} />` boilerplate.
  *
  * @example
- * const form = useZodForm(schema);
- * <FormProvider {...form}>
- *     <Form>
- *         <FormField name="email" label="Email" required>
- *             <Input type="email" />
- *         </FormField>
- *         <FormField name="cep" label="CEP">
- *             <CEPInput />
- *         </FormField>
- *     </Form>
- * </FormProvider>;
+ * formatPhone("1191234");                      // "(11) 9123-4"
+ * formatPhone("1191234", { mobile: true });    // "(11) 91234"
+ * formatPhone("1112345678", { mobile: true }); // "(11) 91234-5678" — 9 inserted
  */
+export declare function formatPhone(value: string, options?: FormatPhoneOptions): string;
+
+export declare interface FormatPhoneOptions {
+    /**
+     * Treat the number as a mobile line: insert the mandatory `9` after the area
+     * code when it is missing, and group the subscriber part `5+4` from the
+     * first digit typed instead of waiting for the eleventh.
+     *
+     * Default `false`, which keeps the length-based behaviour: `4+4` up to ten
+     * digits, `5+4` at eleven.
+     */
+    mobile?: boolean;
+}
+
 export declare function FormField<TValues extends FieldValues = FieldValues, TName extends FieldPath<TValues> = FieldPath<TValues>>({ name, label, helperText, required, control, children }: FormFieldProps<TValues, TName>): JSX.Element;
 
 export declare interface FormFieldChildProps {
@@ -6006,6 +6348,17 @@ export { HashRouter }
  */
 export declare function haversineKm(origin: Coordinate, destination: Coordinate): number;
 
+/**
+ * Heartbeat timeout, which sits inside the rejection range but is not one.
+ *
+ * `tempest-fastapi-sdk` closes with 4408 when no `pong` arrived within
+ * `WS_HEARTBEAT_TIMEOUT_SECONDS`. That is the *link* failing, not the server
+ * refusing the peer — exactly the case reconnection exists for. Treating the
+ * whole 4400–4499 range as fatal, which is the obvious reading, makes one
+ * missed pong permanent.
+ */
+export declare const HEARTBEAT_CLOSE_CODE = 4408;
+
 /** Convert a hex color to OKLCH. */
 export declare function hexToOklch(hex: string): Oklch;
 
@@ -6736,6 +7089,18 @@ export declare function isPlatformAuthenticatorAvailable(): Promise<boolean>;
  */
 export declare function isPushSupported(): boolean;
 
+/**
+ * Whether a close code means the server refused this client for good.
+ *
+ * @param code - The `CloseEvent.code`.
+ * @returns `true` when reconnecting can only reproduce the refusal.
+ *
+ * @example
+ * isRejectionCloseCode(4401); // true — unauthorized
+ * isRejectionCloseCode(4408); // false — heartbeat timeout, retry it
+ */
+export declare function isRejectionCloseCode(code: number): boolean;
+
 /**
  * Whether an HTTP status describes a condition a replay can plausibly fix.
  *
@@ -7149,6 +7514,20 @@ export declare interface LightboxProps {
     className?: string;
 }
 
+/** Shape of the master limiter. Matches `DynamicsCompressorNode`'s params. */
+export declare interface LimiterSettings {
+    /** dBFS above which the compressor starts working. */
+    threshold: number;
+    /** dB range over which the curve bends. `0` is a hard knee. */
+    knee: number;
+    /** Input/output ratio above the threshold. 20 is limiting, not compression. */
+    ratio: number;
+    /** Seconds to clamp a peak. */
+    attack: number;
+    /** Seconds to let go. */
+    release: number;
+}
+
 export { Link }
 
 export declare interface ListOptions<TItem> {
@@ -8052,6 +8431,36 @@ export declare interface OAuthError {
     raw?: unknown;
 }
 
+export declare interface OfflineDatabase<TSchema extends OfflineSchema> {
+    /**
+     * The {@link OfflineStore} for one table.
+     *
+     * The name is checked against the declared schema; the record type is
+     * supplied by the caller — `store<Chat>("chats")`. Deriving it from the
+     * schema instead (`OfflineStore<TSchema[K], string>`) is what the shape
+     * below documents as unavailable: Dexie's `Table<T>` expands `UpdateSpec<T>`
+     * over the keys of `T`, and an unresolved indexed access there makes the
+     * checker answer TS2589 no matter how the value is cast.
+     *
+     * Stores are created once and memoised, so repeated calls with the same
+     * name return the same object.
+     */
+    store: <TItem>(name: keyof TSchema & string) => OfflineStore<TItem, string>;
+    /** The Dexie instance shared by every store. */
+    db: default_2;
+    /** Delete the whole database from the browser. */
+    destroy: () => Promise<void>;
+}
+
+export declare interface OfflineDatabaseConfig<TSchema extends OfflineSchema> {
+    /** IndexedDB database name. */
+    databaseName: string;
+    /** Schema version. Bump when changing any table's indexes. */
+    version: number;
+    /** One entry per object store, all inside this single database. */
+    tables: OfflineTablesConfig<TSchema>;
+}
+
 /**
  * Fixed bar that appears while the browser is offline and, by default, flashes
  * a brief confirmation when the connection returns. Backed by {@link useOnline}
@@ -8113,6 +8522,9 @@ export declare interface OfflineQueryPersistenceOptions {
     throttleMs?: number;
 }
 
+/** Maps each table name to the record type it stores. */
+export declare type OfflineSchema = Record<string, unknown>;
+
 export declare interface OfflineStore<TItem, TKey extends string | number> {
     /** Insert or replace a record. */
     put: (item: TItem, owner?: string) => Promise<TKey>;
@@ -8273,6 +8685,25 @@ export declare interface OfflineSyncConfig<TPayload, TRemote> {
     broadcastChannelName?: string;
 }
 
+export declare interface OfflineTableConfig<TItem> {
+    /**
+     * Dexie index definition for this table. Use `&` for a unique primary key,
+     * e.g. `"&id, service_id, created_at"`.
+     */
+    indexes: string;
+    /** Property used as the primary key (default: `"id"`). */
+    keyPath?: keyof TItem & string;
+    /**
+     * Optional owner scoping for this table. Set per table, since one database
+     * commonly mixes scoped and unscoped data.
+     */
+    ownerField?: keyof TItem & string;
+}
+
+export declare type OfflineTablesConfig<TSchema extends OfflineSchema> = {
+    [K in keyof TSchema]: OfflineTableConfig<TSchema[K]>;
+};
+
 /** A pan offset in frame pixels, measured from the centered position. */
 declare interface Offset {
     x: number;
@@ -8392,6 +8823,68 @@ export declare interface OpenModalOptions {
 /** The operators a field offers. */
 export declare function operatorsFor(field: FilterField): FilterOperator[];
 
+/**
+ * @tempest-limits file-lines — parsing a session description, merging one
+ * `fmtp` line and inserting a missing one are the same pass over the same
+ * grammar; split apart, each half is a parser of half an SDP.
+ */
+/** What an Opus `fmtp` line can be asked to carry. Every field is optional. */
+export declare interface OpusProfile {
+    /**
+     * Ceiling the encoder is asked to respect, in bits per second.
+     *
+     * This describes what we want **to receive**. To cap what we *send*, use
+     * `setSenderBitrate` — in a mesh that is the one that matters, because the
+     * uplink carries one copy per participant.
+     */
+    maxAverageBitrate?: number;
+    /** Highest sample rate worth decoding, in Hz. `48000` for full band. */
+    maxPlaybackRate?: number;
+    /**
+     * Two channels instead of one.
+     *
+     * Sets `stereo` **and** `sprop-stereo`, which point in opposite directions:
+     * `stereo=1` asks the *remote* to send two channels, `sprop-stereo=1`
+     * announces that *we* will. Setting only one leaves the link asymmetric,
+     * which is the recurring reason "I asked for stereo and got mono".
+     */
+    stereo?: boolean;
+    /**
+     * In-band forward error correction (`useinbandfec`).
+     *
+     * Rebuilds a lost packet from the next one, which keeps speech intelligible
+     * on a lossy link — and smears music, since it spends bitrate on redundancy
+     * instead of detail.
+     */
+    fec?: boolean;
+    /**
+     * Discontinuous transmission (`usedtx`): stop sending during silence.
+     *
+     * Saves uplink in a mesh, at the cost of clipping the first instant after a
+     * pause. Wrong for music and for a shared screen, where the quiet passages
+     * are content.
+     */
+    dtx?: boolean;
+    /** Constant bitrate (`cbr`). Off by default, as Opus intends. */
+    cbr?: boolean;
+    /**
+     * Any other `fmtp` key, merged verbatim.
+     *
+     * The escape hatch for a parameter this type does not model. Values are
+     * written as given; a key with an empty string is emitted as a bare flag.
+     */
+    extra?: Record<string, string>;
+}
+
+/**
+ * Profiles to apply, keyed by audio m-line index (`0`, `1`, …) or by `mid`.
+ *
+ * Position and `mid` can be mixed in one object. A key that matches nothing is
+ * ignored rather than an error — an SDP is negotiated, and a slot that was not
+ * offered this time is normal.
+ */
+export declare type OpusProfileMap = Record<string | number, OpusProfile>;
+
 /**
  * First sequential step that clears 2:1 against the chart surface.
  *
@@ -9464,7 +9957,7 @@ export declare function range(start: number, end: number, step?: number): number
  * stays accessible and works with keyboards/screen readers without
  * heavyweight positioning libs. The active fill is positioned via percentages.
  */
-export declare function RangeSlider({ value, onChange, min, max, step, label, helperText, disabled, formatValue, className, }: RangeSliderProps): JSX.Element;
+export declare function RangeSlider({ value, onChange, min, max, step, label, helperText, disabled, formatValue, "aria-label": ariaLabel, className, }: RangeSliderProps): JSX.Element;
 
 export declare interface RangeSliderProps {
     value: RangeValue;
@@ -9477,6 +9970,14 @@ export declare interface RangeSliderProps {
     disabled?: boolean;
     /** Formatter for the value badge next to the label. Defaults to `min – max`. */
     formatValue?: (value: RangeValue) => string;
+    /**
+     * Accessible name for the pair, for when the visible `label` block does not fit.
+     *
+     * Each thumb still gets its own suffixed name — `"Preço (mínimo)"` and
+     * `"Preço (máximo)"` — because a screen reader user moving between the two
+     * needs to know which end they are on. Takes precedence over `label`.
+     */
+    "aria-label"?: string;
     className?: string;
 }
 
@@ -10367,6 +10868,56 @@ export declare interface SequentialScaleOptions {
  */
 export declare function setAudioOutput(element: HTMLMediaElement | null, sinkId: string): Promise<boolean>;
 
+/**
+ * Cap what one sender transmits, in bits per second.
+ *
+ * This is the other half of the pair that confuses people: an Opus `fmtp` line
+ * describes what we want **to receive**, while this is what limits what we
+ * **send**. Both are needed, and in a mesh topology this one matters more,
+ * because the uplink carries one copy of the stream per participant.
+ *
+ * The read-modify-write is not ceremony. `setParameters` only accepts the very
+ * object `getParameters` handed back — a freshly built one is rejected — and a
+ * sender that has not negotiated yet reports **no** encodings at all, so writing
+ * to `encodings[0]` without checking throws on exactly the call that sets the
+ * cap before the first offer.
+ *
+ * @param sender - The `RTCRtpSender` to cap, from `pc.getSenders()` or
+ *   `transceiver.sender`.
+ * @param maxBitrate - Ceiling in bits per second, or `null` to lift the cap.
+ * @returns `false` when the browser refused the change, which happens when the
+ *   sender has no track or the transceiver is gone. Playback continues
+ *   uncapped — a call that keeps running beats one that throws over a bitrate.
+ *
+ * @example
+ * const sender = pc.getSenders().find((s) => s.track?.kind === "audio");
+ * if (sender) await setSenderBitrate(sender, 48_000);
+ */
+export declare function setSenderBitrate(sender: RTCRtpSender, maxBitrate: number | null): Promise<boolean>;
+
+/**
+ * Set a local description, falling back to the untouched one if it is refused.
+ *
+ * Chrome has been tightening what `setLocalDescription` accepts from edited SDP,
+ * and there is no way to know in advance. Without a fallback the call dies
+ * instead of merely losing the profile — which is the wrong trade by a wide
+ * margin: worse audio beats no audio.
+ *
+ * @param connection - The peer connection.
+ * @param description - The description from `createOffer` / `createAnswer`.
+ * @param profiles - Passed straight to {@link tuneOpus}.
+ * @returns `"tuned"` when the rewritten SDP was accepted, `"original"` when the
+ *   fallback was used — worth reporting, because it means the profile silently
+ *   did not apply.
+ * @throws Whatever `setLocalDescription` throws for the original description: at
+ *   that point the failure is not about the rewrite and the caller has to know.
+ *
+ * @example
+ * const applied = await setTunedLocalDescription(pc, await pc.createOffer(), profiles);
+ * if (applied === "original") logger.warn("opus profile refused by the browser");
+ */
+export declare function setTunedLocalDescription(connection: RTCPeerConnection, description: RTCSessionDescriptionInit, profiles: OpusProfile | OpusProfileMap): Promise<TunedDescriptionResult>;
+
 /** Imperative handle over a pool of short sound effects. */
 export declare interface SfxPool {
     /** Play a clip, allocating and caching its element on first use. */
@@ -10709,7 +11260,7 @@ export declare function sleep(ms: number): Promise<void>;
  * accessible (keyboard + screen reader) with no positioning libs. The active
  * fill is a percentage-width bar. For a two-thumb range, use `RangeSlider`.
  */
-export declare function Slider({ value, onChange, min, max, step, label, helperText, disabled, formatValue, className, }: SliderProps): JSX.Element;
+export declare function Slider({ value, onChange, min, max, step, label, helperText, disabled, formatValue, "aria-label": ariaLabel, className, }: SliderProps): JSX.Element;
 
 export declare interface SliderProps {
     /** Current value. */
@@ -10724,6 +11275,17 @@ export declare interface SliderProps {
     disabled?: boolean;
     /** Formatter for the value badge next to the label. Defaults to the raw number. */
     formatValue?: (value: number) => string;
+    /**
+     * Accessible name, for when the visible `label` block does not fit.
+     *
+     * A slider in a one-line footer, a table cell or a toolbar has no room for the
+     * label row above the track, and without this every such control announces
+     * itself as "Slider" — several on the same screen become indistinguishable to a
+     * screen reader. Takes precedence over `label`; wrapping the field in an outer
+     * `<label>` does not work, because an explicit `aria-label` on the input wins
+     * the accessible-name precedence order.
+     */
+    "aria-label"?: string;
     className?: string;
 }
 
@@ -12169,6 +12731,42 @@ export declare interface TruncateTextProps extends HTMLAttributes<HTMLDivElement
     children: ReactNode;
 }
 
+/** Which description a peer connection actually accepted. */
+export declare type TunedDescriptionResult = "tuned" | "original";
+
+/**
+ * Apply Opus profiles to the audio m-lines of a session description.
+ *
+ * Audio over WebRTC is mono and narrow by default, and the only place that is
+ * corrected is the SDP — which is why shared-screen audio famously sounds like a
+ * telephone: music and video inherit the speech profile (mono, ~32 kbps, FEC on,
+ * DTX gating the quiet passages) and no high-level API lets you change it.
+ *
+ * Deliberately **without** built-in presets: which values to use is the
+ * consumer's call — voice in a mesh does not want what system audio wants — and
+ * a preset table is the kind of thing that has no business inside a dependency.
+ * What lives here is the parsing, merging and insertion, which is where the long
+ * tail is. Getting any of it wrong degrades silently: nobody sees an exception,
+ * the audio is just worse.
+ *
+ * @param sdp - The description from `createOffer` or `createAnswer`.
+ * @param profiles - One {@link OpusProfile} for every audio m-line, or an
+ *   {@link OpusProfileMap} keyed by audio m-line index or by `mid`.
+ * @returns The rewritten SDP, with CRLF line endings as RFC 4566 requires.
+ *   Untouched when there is no Opus, when no profile matches, or when a profile
+ *   asks for nothing.
+ *
+ * @example
+ * const tuned = tuneOpus(offer.sdp, {
+ *   0: { maxAverageBitrate: 48_000, stereo: false, fec: true, dtx: true },
+ *   1: { maxAverageBitrate: 192_000, stereo: true, fec: false, dtx: false },
+ * });
+ *
+ * @example
+ * const tuned = tuneOpus(offer.sdp, { stereo: true, dtx: false });
+ */
+export declare function tuneOpus(sdp: string, profiles: OpusProfile | OpusProfileMap): string;
+
 /**
  * Clock label for a turn — the time, not a relative phrase.
  *
@@ -12429,6 +13027,31 @@ export declare interface UseAsyncResult<T> {
  */
 export declare function useAudio(): UseAudioResult;
 
+/**
+ * Keep one {@link AudioBus} alive for as long as the component is mounted.
+ *
+ * The bus is built on the first render and closed on unmount, which matters more
+ * than it looks: browsers cap the number of live `AudioContext`s (Chrome allows
+ * around six), so a bus leaked on unmount eventually breaks every later one on
+ * the page.
+ *
+ * Options are read once. A bus is a device route and a mixing graph, not a
+ * render output — rebuilding it because a prop changed would drop every attached
+ * source mid-sentence. Change gain and output through the bus itself.
+ *
+ * @param options - See {@link AudioBusOptions}. Read on the first render only.
+ * @returns The bus, stable for the component's lifetime.
+ *
+ * @example
+ * const bus = useAudioBus({ maxGain: 3 });
+ *
+ * useEffect(() => {
+ *   const handle = bus.attach(stream, { gain: 1 });
+ *   return () => handle.stop();
+ * }, [bus, stream]);
+ */
+export declare function useAudioBus(options?: AudioBusOptions): AudioBus;
+
 /**
  * Record the given stream, with a clock, a level meter and a state machine.
  *
@@ -12844,7 +13467,7 @@ export declare function useDelete<T>(resource: string, options?: UseDeleteOption
 /** Options for the delete mutation (mutationFn + onSuccess are provided). */
 export declare type UseDeleteOptions<T> = Omit<UseMutationOptions<T, Error, string | number>, "mutationFn">;
 
-export declare function useDescribeApiError(): (error: unknown, fallback: string) => string;
+export declare function useDescribeApiError(): (error: unknown, fallback: string, options?: DescribeApiErrorOptions) => string;
 
 /**
  * Manage open/closed boolean state with stable `open`/`close`/`toggle` handlers.
@@ -14894,11 +15517,13 @@ export { useWatch }
  * for the host component and tears it down on unmount.
  *
  * Every callback is read through a ref, so `onOpen` / `onMessage` / `onClose` /
- * `onError` always run the latest closure — an inline arrow function is fine
- * and never reopens the socket. Connection-shaping options (`protocols`,
- * `maxRetries`, `initialBackoff`, `maxBackoff`, `pingInterval`,
- * `queueWhileClosed`) are baked into the connection, so changing one reopens
- * it with the new value rather than being silently ignored.
+ * `onError` / `onReconnecting` / `onReconnected` / `onLost` 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`,
+ * `silenceTimeout`, `waitForOnline`, `pingInterval`, `queueWhileClosed`) are
+ * baked into the connection, so changing one reopens it with the new value
+ * rather than being silently ignored.
  *
  * @param url - Full ws:// or wss:// URL.
  * @param options - Connection configuration and callbacks.
@@ -14927,6 +15552,13 @@ export declare interface UseWebSocketResult<T> {
     send: (payload: string | Blob | BufferSource) => boolean;
     /** Force a reconnect, resetting the retry counter. */
     reconnect: () => void;
+    /**
+     * Change the silence watchdog at runtime, in ms. `0` disables it.
+     *
+     * For a server that announces its own heartbeat interval in the first frame,
+     * so the tolerated silence is not hard-coded on both ends.
+     */
+    setSilenceTimeout: (ms: number) => void;
 }
 
 /**
@@ -15586,10 +16218,38 @@ export declare interface WebSocketController {
     close: (code?: number, reason?: string) => void;
     /** Force an immediate reconnect, resetting the retry counter. */
     reconnect: () => void;
+    /**
+     * Change the silence watchdog at runtime, in ms. `0` disables it.
+     *
+     * For the common case where the server announces its heartbeat interval in
+     * the first frame, so the tolerated silence is not hard-coded on both ends:
+     *
+     * ```ts
+     * onMessage: ({ data }) => {
+     *   if (data.type === "welcome") socket.setSilenceTimeout(data.heartbeat_seconds * 2500);
+     * }
+     * ```
+     */
+    setSilenceTimeout: (ms: number) => void;
+    /**
+     * Resolves on the first successful open, rejects when the socket is lost
+     * before ever opening.
+     *
+     * Joining and dropping are different events: a call that never connected has
+     * to be reported, while one that dropped mid-session should reconnect
+     * quietly. Await this for the join, handle
+     * {@link CreateWebSocketOptions.onLost} for the drop. Pair it with
+     * `maxRetries: 0` when the first attempt should fail fast instead of
+     * spending the whole schedule on a server that is not there.
+     */
+    opened: Promise<void>;
     /** Current connection status. */
     readonly status: WebSocketStatus;
 }
 
+/** Why a socket stopped trying to come back. */
+export declare type WebSocketLostReason = "rejected" | "exhausted";
+
 export declare interface WebSocketMessage<T> {
     /** Parsed payload — JSON-decoded when possible, raw string otherwise. */
     data: T;
@@ -15597,12 +16257,6 @@ export declare interface WebSocketMessage<T> {
     raw: MessageEvent;
 }
 
-/**
- * @tempest-limits file-lines, function-lines — reconnect with backoff, heartbeat,
- * the send queue that survives a disconnect and the listener set that must be re-
- * attached to each new socket — one connection's lifetime, one closure. The queue
- * and the reconnect timer are the same decision seen twice.
- */
 export declare type WebSocketStatus = "idle" | "connecting" | "open" | "closing" | "closed" | "error";
 
 export declare type WeekStart = 0 | 1;