tempest-react-sdk 0.54.0 → 0.56.0

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

@@ -242,7 +242,7 @@ export declare interface AIChatComposerHandle {
     getValue: () => string;
 }
 
-export declare interface AIChatComposerProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, OverriddenDomProps_8> {
+export declare interface AIChatComposerProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, OverriddenDomProps_9> {
     /** Called with the trimmed prompt. The field clears only when this does not throw. */
     onSend: (text: string) => void | Promise<void>;
     /**
@@ -313,7 +313,7 @@ export declare interface AIChatMessage {
     data?: Record<string, unknown>;
 }
 
-export declare interface AIChatProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_7> {
+export declare interface AIChatProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_8> {
     /** The transcript, **oldest first**. Never reordered by the component. */
     messages: readonly AIChatMessage[];
     /** Renders the composer when given. Receives the trimmed prompt. */
@@ -1221,7 +1221,7 @@ export declare interface AudioPlayerHandle {
     current: () => HTMLAudioElement | null;
 }
 
-export declare interface AudioPlayerProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_4> {
+export declare interface AudioPlayerProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_5> {
     /**
      * What to play — a URL, or a `Blob`/`File` straight from a recorder.
      *
@@ -1324,7 +1324,7 @@ export declare interface AudioRecorderOptions {
     onError?: (error: unknown) => void;
 }
 
-export declare interface AudioRecorderProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_5> {
+export declare interface AudioRecorderProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_6> {
     /**
      * Called once a recording is finished and (when asked) converted.
      *
@@ -1601,7 +1601,7 @@ export declare interface BarcodePoint {
  */
 export declare function BarcodeScanner({ onScan, formats, paused, detector, intervalMs, repeatDelayMs, torch, aspectRatio, locale, footer, unsupported, onError, className, ...rest }: BarcodeScannerProps): JSX.Element;
 
-export declare interface BarcodeScannerProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_6> {
+export declare interface BarcodeScannerProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_7> {
     /** Called for every accepted read — repeats of the same value are suppressed. */
     onScan: (result: BarcodeScanResult) => void;
     /** Symbologies to look for. Defaults to QR + EAN-13 + Code 128. */
@@ -2381,7 +2381,7 @@ export declare interface ChatComposerHandle {
     setValue: (text: string) => void;
 }
 
-export declare interface ChatComposerProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, OverriddenDomProps_3> {
+export declare interface ChatComposerProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, OverriddenDomProps_4> {
     /** Called with the trimmed text. The field clears only when this does not throw. */
     onSend: (text: string) => void | Promise<void>;
     /** Locale for the placeholder and the send label. Default `"pt-BR"`. */
@@ -2437,7 +2437,7 @@ export declare interface ChatMessage {
     data?: Record<string, unknown>;
 }
 
-export declare interface ChatProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_2> {
+export declare interface ChatProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_3> {
     /** The thread, **oldest first**. Never reordered by the component. */
     messages: readonly ChatMessage[];
     /** Author id treated as "own" — decides side, colour and status ticks. */
@@ -3728,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.
@@ -5058,6 +5085,17 @@ export declare const DEFAULT_MAX_GAIN = 3;
  */
 export declare const DEFAULT_MODE_DURATION_FACTORS: Record<TravelMode, number>;
 
+/**
+ * The speed presets the player offers, and why they stop at 2×.
+ *
+ * The spec lets a browser drop the audio once `playbackRate` leaves a range it
+ * considers useful, and that limit varies by engine. These four sit inside every
+ * range measured, so the default control never silences a clip by accident. A
+ * caller who wants 4× can pass it — and should test it with sound on the
+ * browsers they support before promising it.
+ */
+export declare const DEFAULT_PLAYBACK_RATES: readonly number[];
+
 /**
  * COSE algorithms offered when the server sends no `pubKeyCredParams`, in
  * preference order.
@@ -5783,7 +5821,7 @@ export declare interface Filter {
  */
 export declare function FilterBar({ fields, value, onChange, locale, actions, className, ...rest }: FilterBarProps): JSX.Element;
 
-export declare interface FilterBarProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_12> {
+export declare interface FilterBarProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_13> {
     /** Fields the user may filter by. */
     fields: readonly FilterField[];
     /** Applied filters. Controlled. */
@@ -8083,7 +8121,7 @@ export declare type MarkdownInline = {
     type: "break";
 };
 
-export declare interface MarkdownProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_11> {
+export declare interface MarkdownProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_12> {
     /** The Markdown source. */
     source: string;
     /**
@@ -8121,7 +8159,7 @@ export declare interface MarkdownProps extends Omit<HTMLAttributes<HTMLDivElemen
  */
 export declare function Masonry<T>({ items, children, itemKey, columns, gap, className, style, ...rest }: MasonryProps<T>): JSX.Element;
 
-export declare interface MasonryProps<T> extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_10> {
+export declare interface MasonryProps<T> extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_11> {
     /** What to lay out. */
     items: readonly T[];
     /** Render one card. */
@@ -8363,6 +8401,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. */
@@ -9402,37 +9543,49 @@ export { Outlet }
 declare type OverriddenDomProps = "children" | "title" | "onSelect";
 
 /** DOM attributes this component redefines. */
-declare type OverriddenDomProps_10 = "children";
+declare type OverriddenDomProps_10 = "children" | "onChange" | "defaultValue";
 
 /** DOM attributes this component redefines. */
 declare type OverriddenDomProps_11 = "children";
 
 /** DOM attributes this component redefines. */
-declare type OverriddenDomProps_12 = "children" | "onChange";
+declare type OverriddenDomProps_12 = "children";
 
 /** DOM attributes this component redefines. */
-declare type OverriddenDomProps_2 = "children" | "onSubmit";
+declare type OverriddenDomProps_13 = "children" | "onChange";
 
-/** DOM attributes the composer redefines. */
-declare type OverriddenDomProps_3 = "onSubmit" | "value" | "defaultValue" | "rows";
+/**
+ * DOM attributes this component redefines.
+ *
+ * `onRateChange` is a real collision, not tidiness: React types it on every
+ * element as the media `ratechange` handler, `ReactEventHandler`. Ours carries
+ * the rate the viewer picked, and a `(rate: number) => void` is not assignable
+ * to a handler that receives an event — same shape of clash as `Input`'s `size`
+ * against `HTMLInputElement.size`. The DOM one is useless on a `<div>` anyway:
+ * the event fires on the media element inside, which this component owns.
+ */
+declare type OverriddenDomProps_2 = "children" | "onRateChange";
 
 /** DOM attributes this component redefines. */
-declare type OverriddenDomProps_4 = "children";
+declare type OverriddenDomProps_3 = "children" | "onSubmit";
+
+/** DOM attributes the composer redefines. */
+declare type OverriddenDomProps_4 = "onSubmit" | "value" | "defaultValue" | "rows";
 
 /** DOM attributes this component redefines. */
-declare type OverriddenDomProps_5 = "children" | "onError";
+declare type OverriddenDomProps_5 = "children";
 
 /** DOM attributes this component redefines. */
 declare type OverriddenDomProps_6 = "children" | "onError";
 
 /** DOM attributes this component redefines. */
-declare type OverriddenDomProps_7 = "children" | "onSubmit";
-
-/** DOM attributes the composer redefines. */
-declare type OverriddenDomProps_8 = "onSubmit" | "value" | "defaultValue" | "rows";
+declare type OverriddenDomProps_7 = "children" | "onError";
 
 /** DOM attributes this component redefines. */
-declare type OverriddenDomProps_9 = "children" | "onChange" | "defaultValue";
+declare type OverriddenDomProps_8 = "children" | "onSubmit";
+
+/** DOM attributes the composer redefines. */
+declare type OverriddenDomProps_9 = "onSubmit" | "value" | "defaultValue" | "rows";
 
 /**
  * Page wrapper with header + (optional) toolbar + content + footer. Pairs
@@ -9811,6 +9964,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`.
  *
@@ -10834,6 +11068,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";
 
 /**
@@ -11183,6 +11433,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;
 
@@ -13175,7 +13445,7 @@ export declare interface TransferItem {
     data?: Record<string, unknown>;
 }
 
-export declare interface TransferProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_9> {
+export declare interface TransferProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_10> {
     /** The whole catalogue. Both panes are derived from it. */
     items: readonly TransferItem[];
     /** Ids on the target side. Controlled. */
@@ -16407,6 +16677,88 @@ export declare interface ViaCEPResult {
     siafi?: string;
 }
 
+/**
+ * Playback transport for one video: play/pause, seek, volume, speed, fullscreen.
+ *
+ * Built on a real `<video>` element, and deliberately **not** an overlay: the
+ * controls sit in a bar under the frame rather than on top of it. Controls drawn
+ * over video have to earn their contrast against arbitrary pixels, which no
+ * `--tempest-*` token can promise — every text token in this SDK is resolved
+ * against a known surface, and the two contrast defects this repo shipped were
+ * both a text token used over a surface it was never checked against. A bar with
+ * its own surface inherits the theme and is legible by construction.
+ *
+ * The seek bar, the volume slider and the speed picker are bare `<input>` and
+ * `<select>` elements rather than the SDK's `Slider` and `Select`: those are form
+ * fields, with a label row and a value badge, and a transport wants neither. The
+ * native elements keep the keyboard and screen-reader behaviour that matters here
+ * for free.
+ *
+ * @example
+ * const rec = useVideoRecorder(screen.stream);
+ * {rec.recording && (
+ *     <VideoPlayer src={rec.recording.blob} durationMs={rec.recording.durationMs} />
+ * )}
+ */
+export declare function VideoPlayer({ src, durationMs, poster, tracks, aspectRatio, rate, rates, onRateChange, shiftPitch, fullscreen, autoPlay, loop, muted, locale, actions, onEnded, onError, disabled, className, ...rest }: VideoPlayerProps): JSX.Element;
+
+export declare interface VideoPlayerProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_2> {
+    /**
+     * What to play — a URL, or a `Blob`/`File` straight from a recorder.
+     *
+     * A `Blob` is wrapped in an object URL that is revoked when it changes or the
+     * component unmounts, so a session that records twenty clips does not leak
+     * twenty URLs for the lifetime of the tab.
+     */
+    src: string | Blob | null;
+    /**
+     * Known length in milliseconds.
+     *
+     * Pass it whenever you have it — a recording from `useVideoRecorder` always
+     * does. Without it the element's own `duration` is used, and a fresh
+     * `MediaRecorder` blob may report `Infinity` until it is probed for one.
+     */
+    durationMs?: number;
+    /** Still shown before playback. Pair it with `captureFrame` from `/imaging`. */
+    poster?: string;
+    /** Caption and subtitle files. */
+    tracks?: readonly VideoTextTrack[];
+    /** Frame shape while the video has no intrinsic size yet. Default `16 / 9`. */
+    aspectRatio?: number;
+    /**
+     * Playback rate. Controlled when passed with `onRateChange`.
+     *
+     * Written to both `playbackRate` and `defaultPlaybackRate`, because the
+     * element resets the first to the second when a source loads — a player that
+     * only writes `playbackRate` silently drops back to 1× on every clip change.
+     */
+    rate?: number;
+    /** Presets the control offers. `[]` hides it. Default {@link DEFAULT_PLAYBACK_RATES}. */
+    rates?: readonly number[];
+    /** Called with the rate the viewer picked. */
+    onRateChange?: (rate: number) => void;
+    /** Let the pitch rise with the rate (`preservesPitch = false`). Default `false`. */
+    shiftPitch?: boolean;
+    /** Offer a fullscreen button where the browser supports it. Default `true`. */
+    fullscreen?: boolean;
+    /** Start playing as soon as `src` is ready. Default `false`. */
+    autoPlay?: boolean;
+    /** Loop. Default `false`. */
+    loop?: boolean;
+    /** Start muted. Autoplay without a gesture needs this. Default `false`. */
+    muted?: boolean;
+    /** Locale for the labels. Default `"pt-BR"`. */
+    locale?: "pt-BR" | "en";
+    /** Rendered at the end of the control row — a download button, a delete button. */
+    actions?: ReactNode;
+    /** Fired when playback reaches the end. */
+    onEnded?: () => void;
+    /** Fired when the element reports a decode/network error. */
+    onError?: (error: unknown) => void;
+    /** No `src` yet, or playback not allowed. */
+    disabled?: boolean;
+}
+
 /** Imperative video recorder. Same shape as the audio one. */
 export declare type VideoRecorderHandle = MediaRecorderHandle;
 
@@ -16452,6 +16804,20 @@ export declare interface VideoRecorderOptions {
  */
 export declare type VideoRecording = MediaRecording;
 
+/** One caption or subtitle file, rendered as a `<track>`. */
+export declare interface VideoTextTrack {
+    /** URL of the WebVTT file. */
+    src: string;
+    /** BCP 47 language tag, e.g. `"pt-BR"`. */
+    srcLang: string;
+    /** Name shown in the browser's own track menu. */
+    label: string;
+    /** Track kind. Default `"captions"`. */
+    kind?: "subtitles" | "captions" | "descriptions" | "chapters" | "metadata";
+    /** Whether this track is on unless the viewer picks another. */
+    default?: boolean;
+}
+
 /**
  * Fixed-height virtual list. Renders only the visible window plus a small
  * overscan buffer. Suitable for lists of thousands of identical rows.