tempest-react-sdk 0.52.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
@@ -4015,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;
 
@@ -4033,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).
@@ -4073,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;
 }
 
 /**
@@ -4700,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
@@ -5831,25 +6033,6 @@ export declare interface FormatPhoneOptions {
     mobile?: boolean;
 }
 
-/**
- * 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>;
- */
 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 {
@@ -6165,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;
 
@@ -6895,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.
  *
@@ -7308,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> {
@@ -8603,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.
  *
@@ -9675,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;
@@ -9688,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;
 }
 
@@ -10578,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. */
@@ -10920,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. */
@@ -10935,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;
 }
 
@@ -12380,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.
  *
@@ -12640,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.
  *
@@ -15105,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.
@@ -15138,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;
 }
 
 /**
@@ -15797,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;
@@ -15808,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;