@reactor-team/js-sdk 2.12.3 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,90 +1,307 @@
1
- import { z } from 'zod';
2
- import * as react_jsx_runtime from 'react/jsx-runtime';
3
- import React, { ReactNode } from 'react';
1
+ import * as react from 'react';
2
+ import { ReactNode, CSSProperties, VideoHTMLAttributes } from 'react';
4
3
 
5
4
  /**
6
- * Internal types for the Reactor SDK.
5
+ * Every Reactor failure carries `code`, `recoverable`, `status`, `operation`,
6
+ * `retry_after_ms` and `timestamp_ms` — `reactor-core`'s canonical shape,
7
+ * shared by every SDK on it. `timestamp`/`retryAfter` are kept alongside
8
+ * under their previous names for compatibility — see their own doc comments
9
+ * below — rather than dropped, since this package's public API may only
10
+ * grow.
7
11
  *
8
- * All Zod schemas and derived TypeScript types live here.
9
- * Version constants are sourced from package.json via resolveJsonModule.
12
+ * There is **one class**, not two: the `error` event payload and a rejected
13
+ * call's error are the same shape and the same instance type.
14
+ *
15
+ * `ReactorError` is the base of a typed hierarchy keyed by `code` —
16
+ * `reactor-core`'s own per-failure-kind classification — so `instanceof
17
+ * UnauthorizedError` and `code === 'UNAUTHORIZED'` are equivalent, one just
18
+ * typed. Codes are open-ended (the platform can send its own), so an
19
+ * unrecognized one falls back to the base class itself rather than
20
+ * throwing.
10
21
  */
22
+ /** Fields a `ReactorError` constructor accepts, all optional — an
23
+ * unrecognized code still constructs cleanly on the base class, and a
24
+ * purely local failure (no payload at all) still constructs cleanly too. */
25
+ interface ReactorErrorOptions {
26
+ code?: string | undefined;
27
+ recoverable?: boolean | undefined;
28
+ status?: number | undefined;
29
+ operation?: string | undefined;
30
+ retry_after_ms?: number | undefined;
31
+ timestamp_ms?: number | undefined;
32
+ }
33
+ declare class ReactorError extends Error {
34
+ /** The code this class stands for. `ReactorError` itself is the fallback,
35
+ * so it claims none and takes whatever the payload reported. */
36
+ static readonly code: string;
37
+ /** `reactor-core`'s own canonical code for this failure — the same value
38
+ * used to pick this instance's class (see the typed subclasses below for
39
+ * the vocabulary). Open-ended: an unrecognized code still constructs the
40
+ * base class, with `code` set to whatever was reported. */
41
+ readonly code: string;
42
+ /** Whether the same call could succeed later. */
43
+ readonly recoverable: boolean;
44
+ /** The HTTP status, when the failure came from one. */
45
+ readonly status: number | undefined;
46
+ /** Which call failed, e.g. "connect", "sendCommand". */
47
+ readonly operation: string | undefined;
48
+ /** Backoff hint the platform sent. */
49
+ readonly retry_after_ms: number | undefined;
50
+ /** When `reactor-core` reported this failure. For a purely local one (no
51
+ * payload at all — see {@link ReactorErrorOptions}), this is synthesized
52
+ * as the construction time instead, since there's nothing to report —
53
+ * not a value read off the wire. */
54
+ readonly timestamp_ms: number;
55
+ /** Same value as `retry_after_ms`, under its previous name. Kept for
56
+ * compatibility — prefer `retry_after_ms`. */
57
+ readonly retryAfter: number | undefined;
58
+ /** Same value as `timestamp_ms`, under its previous name. Kept for
59
+ * compatibility — prefer `timestamp_ms`. */
60
+ readonly timestamp: number;
61
+ constructor(message: string, options?: ReactorErrorOptions);
62
+ }
63
+ /** The request never got a reply — DNS, TLS, a refused socket. */
64
+ declare class NetworkError extends ReactorError {
65
+ static readonly code = "NETWORK_ERROR";
66
+ }
67
+ /** 401 or 403: the token is missing, expired, or not scoped for this call. */
68
+ declare class UnauthorizedError extends ReactorError {
69
+ static readonly code = "UNAUTHORIZED";
70
+ }
71
+ /** 404: no such model, session or upload. */
72
+ declare class NotFoundError extends ReactorError {
73
+ static readonly code = "NOT_FOUND";
74
+ }
75
+ /** 409: the session is in a state that does not allow this — usually a
76
+ * session left orphaned by a previous run that went away without
77
+ * disconnecting. */
78
+ declare class ConflictError extends ReactorError {
79
+ static readonly code = "CONFLICT";
80
+ }
81
+ /** 429: too many requests. `retry_after_ms` carries the server's
82
+ * `Retry-After` when it sent one; `undefined` means back off on your own
83
+ * terms rather than retrying immediately. */
84
+ declare class RateLimitedError extends ReactorError {
85
+ static readonly code = "RATE_LIMITED";
86
+ }
87
+ /** A 4xx other than the ones above: the request itself was wrong. */
88
+ declare class BadRequestError extends ReactorError {
89
+ static readonly code = "BAD_REQUEST";
90
+ }
91
+ /** 5xx: the coordinator failed, and the same request may work later. */
92
+ declare class ServerError extends ReactorError {
93
+ static readonly code = "SERVER_ERROR";
94
+ }
95
+ /** This client and the platform disagree on the protocol — upgrade the SDK. */
96
+ declare class VersionMismatchError extends ReactorError {
97
+ static readonly code = "VERSION_MISMATCH";
98
+ }
99
+ /** A reply arrived and could not be understood. */
100
+ declare class DecodeError extends ReactorError {
101
+ static readonly code = "DECODE_FAILED";
102
+ }
103
+ /** The operation is not allowed from the state the client is in — most often
104
+ * a call that needs a live session, made before `connect()` or after the
105
+ * status left `"ready"`. */
106
+ declare class InvalidStateError extends ReactorError {
107
+ static readonly code = "INVALID_STATE";
108
+ }
109
+ /** The session reached a state it cannot leave. Start a new one. */
110
+ declare class SessionTerminalError extends ReactorError {
111
+ static readonly code = "SESSION_TERMINAL";
112
+ }
113
+ /** The payload exceeds what the data channel accepts — send large content
114
+ * with `uploadFile()` and pass the `FileRef` instead of embedding it
115
+ * inline in a command. */
116
+ declare class MessageTooLargeError extends ReactorError {
117
+ static readonly code = "MESSAGE_TOO_LARGE";
118
+ }
119
+ /** The media transport failed. */
120
+ declare class TransportError extends ReactorError {
121
+ static readonly code = "TRANSPORT_ERROR";
122
+ }
123
+ /** The connection went away, either dropped mid-request or lost after being
124
+ * established. `reconnect()` is the way back. */
125
+ declare class DisconnectedError extends ReactorError {
126
+ static readonly code = "DISCONNECTED";
127
+ }
128
+ /** The operation was sent and nothing came back in time. */
129
+ declare class RequestTimeoutError extends ReactorError {
130
+ static readonly code = "REQUEST_TIMEOUT";
131
+ }
132
+ /** The operation was abandoned before it finished. */
133
+ declare class AbortedError extends ReactorError {
134
+ static readonly code = "ABORTED";
135
+ }
136
+ /**
137
+ * A `requestClip()`/`requestRecording()` call failed because the model's
138
+ * recorder is disabled or has crashed.
139
+ *
140
+ * Unlike every other code here, `RECORDER_DISABLED` isn't platform-sent —
141
+ * `reactor-core` produces it by matching known reason strings on an
142
+ * otherwise free-text `ClipFailed` message, as a stopgap until that message
143
+ * carries a structured reason (tracked as REA-5403). Treat it as best-effort:
144
+ * a clip failure for the same underlying reason may still arrive as the
145
+ * base `ReactorError` (`code: "INTERNAL_ERROR"`) if the reason text ever
146
+ * changes upstream.
147
+ *
148
+ * `recoverable` is `false`: the recorder being disabled or crashed isn't
149
+ * something retrying the same `requestClip()`/`requestRecording()` call can
150
+ * fix — it needs an operator to re-enable or restart the recorder on the
151
+ * model side first.
152
+ */
153
+ declare class RecorderDisabledError extends ReactorError {
154
+ static readonly code = "RECORDER_DISABLED";
155
+ }
11
156
 
12
- declare const TrackCapabilitySchema: z.ZodObject<{
13
- name: z.ZodString;
14
- kind: z.ZodEnum<{
15
- video: "video";
16
- audio: "audio";
17
- }>;
18
- direction: z.ZodEnum<{
19
- recvonly: "recvonly";
20
- sendonly: "sendonly";
21
- }>;
22
- }, z.core.$strip>;
23
- declare const CommandCapabilitySchema: z.ZodObject<{
24
- name: z.ZodString;
25
- description: z.ZodString;
26
- schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
27
- }, z.core.$strip>;
28
- declare const CapabilitiesSchema: z.ZodObject<{
29
- protocol_version: z.ZodString;
30
- tracks: z.ZodArray<z.ZodObject<{
31
- name: z.ZodString;
32
- kind: z.ZodEnum<{
33
- video: "video";
34
- audio: "audio";
35
- }>;
36
- direction: z.ZodEnum<{
37
- recvonly: "recvonly";
38
- sendonly: "sendonly";
39
- }>;
40
- }, z.core.$strip>>;
41
- commands: z.ZodOptional<z.ZodArray<z.ZodObject<{
42
- name: z.ZodString;
43
- description: z.ZodString;
44
- schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
45
- }, z.core.$strip>>>;
46
- emission_fps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
47
- }, z.core.$strip>;
48
- declare const SessionResponseSchema: z.ZodObject<{
49
- session_id: z.ZodString;
50
- state: z.ZodString;
51
- cluster: z.ZodString;
52
- model: z.ZodObject<{
53
- name: z.ZodString;
54
- version: z.ZodOptional<z.ZodString>;
55
- }, z.core.$strip>;
56
- server_info: z.ZodObject<{
57
- server_version: z.ZodString;
58
- }, z.core.$strip>;
59
- selected_transport: z.ZodOptional<z.ZodObject<{
60
- protocol: z.ZodString;
61
- version: z.ZodString;
62
- }, z.core.$strip>>;
63
- capabilities: z.ZodOptional<z.ZodObject<{
64
- protocol_version: z.ZodString;
65
- tracks: z.ZodArray<z.ZodObject<{
66
- name: z.ZodString;
67
- kind: z.ZodEnum<{
68
- video: "video";
69
- audio: "audio";
70
- }>;
71
- direction: z.ZodEnum<{
72
- recvonly: "recvonly";
73
- sendonly: "sendonly";
74
- }>;
75
- }, z.core.$strip>>;
76
- commands: z.ZodOptional<z.ZodArray<z.ZodObject<{
77
- name: z.ZodString;
78
- description: z.ZodString;
79
- schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
80
- }, z.core.$strip>>>;
81
- emission_fps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
82
- }, z.core.$strip>>;
83
- }, z.core.$strip>;
84
- type TrackCapability = z.infer<typeof TrackCapabilitySchema>;
85
- type CommandCapability = z.infer<typeof CommandCapabilitySchema>;
86
- type SessionResponse = z.infer<typeof SessionResponseSchema>;
87
- type Capabilities = z.infer<typeof CapabilitiesSchema>;
157
+ /**
158
+ * Reference to a file uploaded via `Reactor.uploadFile()`. Pass it back as a
159
+ * top-level value in `sendCommand()`'s `data` and it's extracted and sent as
160
+ * a separate upload reference rather than embedded in the JSON payload —
161
+ * see `extractFileRefs()`.
162
+ */
163
+ declare class FileRef {
164
+ readonly uploadId: string;
165
+ readonly name: string;
166
+ readonly mimeType: string;
167
+ readonly size: number;
168
+ constructor(uploadId: string, name: string, mimeType: string, size: number);
169
+ }
170
+ /**
171
+ * Structural check for anything shaped like a `FileRef`, for callers who'd
172
+ * rather duck-type than rely on `instanceof` (e.g. across two copies of this
173
+ * package bundled into the same page). `extractFileRefs()` uses this too,
174
+ * for the same reason.
175
+ */
176
+ declare function isFileRef(value: unknown): value is FileRef;
177
+
178
+ /**
179
+ * The `reactor-wasm` contract, mirrored by hand.
180
+ *
181
+ * `crates/reactor-wasm` generates the real `reactor_wasm.d.ts` at
182
+ * `mise run build:wasm` time (see `crates/reactor-wasm/src/types.rs` and
183
+ * `client.rs`), but that output isn't committed — the JS SDK depends on a
184
+ * build step, not a checked-in file. This file re-states that same contract
185
+ * so `sdks/js` type-checks on a fresh checkout too, before anyone has run the
186
+ * wasm build. Node resolution always prefers a real, installed module over an
187
+ * ambient ad-hoc declaration, so once `reactor_wasm.js`/`.d.ts` exist next to
188
+ * this at runtime, they're what actually loads — this file only fills the gap
189
+ * until then.
190
+ *
191
+ * Keep in sync with the two files above. Field naming follows the wire, not
192
+ * JavaScript: payloads that come out of the core keep snake_case
193
+ * (`protocol_version`, `retry_after_ms`, `playlist_url`, ...); only the
194
+ * options this crate defines itself are camelCase.
195
+ */
196
+ type ReactorStatus = 'disconnected' | 'connecting' | 'waiting' | 'ready';
197
+ type TrackKind = 'audio' | 'video';
198
+ type TrackDirection = 'recvonly' | 'sendonly';
199
+ interface ClientOptions {
200
+ modelName: string;
201
+ apiUrl?: string;
202
+ local?: boolean;
203
+ sdkType?: string;
204
+ sdkVersion?: string;
205
+ autoResumeTracks?: boolean;
206
+ extraArgs?: Record<string, unknown>;
207
+ heartbeatIntervalMs?: number;
208
+ readyTimeoutMs?: number;
209
+ controlRequestTimeoutMs?: number;
210
+ clipRequestTimeoutMs?: number;
211
+ maxSessionAttempts?: number;
212
+ maxSdpAttempts?: number;
213
+ sdpBackoffInitialMs?: number;
214
+ sdpBackoffMaxMs?: number;
215
+ sdpBackoffMultiplier?: number;
216
+ modelTracks?: TrackCapability[];
217
+ logLevel?: 'off' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
218
+ }
219
+ interface ConnectOptions {
220
+ sessionId?: string;
221
+ connectionId?: number;
222
+ autoResumeTracks?: boolean;
223
+ maxAttempts?: number;
224
+ }
225
+ /** A token, or a resolver called before every authenticated request.
226
+ * Returning "" sends no Authorization header. */
227
+ type JwtSource = string | (() => string | Promise<string>);
228
+ interface TrackCapability {
229
+ name: string;
230
+ kind: TrackKind;
231
+ direction: TrackDirection;
232
+ }
233
+ interface TrackMappingEntry extends TrackCapability {
234
+ mid: string;
235
+ }
236
+ interface CommandCapability$1 {
237
+ name: string;
238
+ description?: string;
239
+ schema?: unknown;
240
+ }
241
+ interface Capabilities$1 {
242
+ protocol_version: string;
243
+ tracks: TrackCapability[];
244
+ commands?: CommandCapability$1[];
245
+ emission_fps?: number;
246
+ }
247
+ interface SessionInfo {
248
+ session_id: string;
249
+ state: string;
250
+ model?: {
251
+ name: string;
252
+ version?: string;
253
+ };
254
+ cluster?: string;
255
+ server_info?: {
256
+ server_version: string;
257
+ };
258
+ selected_transport?: {
259
+ protocol: string;
260
+ version: string;
261
+ };
262
+ capabilities?: Capabilities$1;
263
+ [key: string]: unknown;
264
+ }
265
+ interface ReactorMessage {
266
+ type: string;
267
+ data: unknown;
268
+ }
269
+
270
+ /** The session resource, as the coordinator reports it — see
271
+ * `Reactor.getSessionInfo()`. */
272
+ type SessionResponse = SessionInfo;
273
+ /**
274
+ * Scope tag for `sendCommand()`. This SDK has no generic runtime-scope
275
+ * channel — see `Reactor`'s private `sendRuntimeScopedCommand()` for what
276
+ * `"runtime"` actually does here (routes a couple of recognized commands to
277
+ * their direct equivalents, warns and falls through to a normal send for
278
+ * anything else).
279
+ */
280
+ type MessageScope = 'application' | 'runtime';
281
+ /** Any object, except a function. */
282
+ type NotFunction<T> = T extends (...args: never[]) => unknown ? never : T;
283
+ /** One command the model declares in its capabilities. */
284
+ interface CommandCapability {
285
+ name: string;
286
+ description?: string;
287
+ schema?: unknown;
288
+ }
289
+ /**
290
+ * The runtime's declared capabilities for the session — negotiated tracks,
291
+ * and the command set when the model exposes one. Pushed once available (no
292
+ * explicit request needed) — see `Reactor.getCapabilities()`/
293
+ * `capabilitiesReceived`.
294
+ *
295
+ * camelCase — the wasm binding's own wire shape is snake_case
296
+ * (`protocol_version`, `emission_fps`), translated at the boundary in
297
+ * `internal/capabilities.ts` rather than exposed directly here.
298
+ */
299
+ interface Capabilities {
300
+ protocolVersion: string;
301
+ tracks: TrackCapability[];
302
+ commands?: CommandCapability[];
303
+ emissionFps?: number;
304
+ }
88
305
  /** One OpenAPI operation (the `post` of an event/webhook path item). */
89
306
  interface ModelSchemaOperation {
90
307
  operationId?: string;
@@ -105,12 +322,12 @@ interface ModelSchemaPathItem {
105
322
  [key: string]: unknown;
106
323
  }
107
324
  /**
108
- * The model's OpenAPI 3.1 schema, returned by the runtime in response to a
109
- * `requestSchema` runtime-channel command. This is a pass-through of the
110
- * runtime's document, not a shape the SDK reshapes: client-triggerable
111
- * events live under `paths` as `POST /events/<name>` operations, outbound
112
- * model messages under `webhooks`, and media tracks under `x-reactor.tracks`.
113
- * Read the parts you need.
325
+ * The model's OpenAPI 3.1 schema, returned by `requestSchema()`/cached by
326
+ * `getSchema()`. A pass-through of the runtime's document, not a shape this
327
+ * SDK reshapes: client-triggerable events live under `paths` as
328
+ * `POST /events/<name>` operations, outbound model messages under
329
+ * `webhooks`, and media tracks under `x-reactor.tracks`. Read the parts you
330
+ * need.
114
331
  */
115
332
  interface ModelSchema {
116
333
  openapi: string;
@@ -121,7 +338,7 @@ interface ModelSchema {
121
338
  };
122
339
  paths?: Record<string, ModelSchemaPathItem>;
123
340
  webhooks?: Record<string, ModelSchemaPathItem>;
124
- "x-reactor"?: {
341
+ 'x-reactor'?: {
125
342
  tracks?: Array<{
126
343
  name: string;
127
344
  kind: string;
@@ -131,441 +348,245 @@ interface ModelSchema {
131
348
  components?: Record<string, unknown>;
132
349
  [key: string]: unknown;
133
350
  }
134
-
135
351
  /**
136
- * Reference to an uploaded file, returned by {@link Reactor.uploadFile}.
137
- *
138
- * Pass a `FileRef` as a value in {@link Reactor.sendCommand} and it will
139
- * be serialized into the `uploads` section of the wire envelope, separate
140
- * from scalar arguments. The runtime resolves each reference to bytes
141
- * before dispatching the event to the model handler.
352
+ * Severity tier of a content-moderation event delivered as the inner
353
+ * payload of a `runtimeMessage` with `type === "moderation"`. `"warn"`
354
+ * continues the session (informational only); `"terminate"` ends it shortly
355
+ * after the message is dispatched.
142
356
  */
143
- declare class FileRef {
144
- readonly uploadId: string;
145
- readonly name: string;
146
- readonly mimeType: string;
147
- readonly size: number;
148
- constructor(uploadId: string, name: string, mimeType: string, size: number);
149
- }
150
-
151
- type ReactorStatus = "disconnected" | "connecting" | "waiting" | "ready";
357
+ type ModerationAction = 'warn' | 'terminate';
152
358
  /**
153
- * The message scope identifies the envelope layer a data channel message belongs to.
154
- * - "application": model-defined commands (client->runtime) and model-emitted payloads (runtime->client).
155
- * - "runtime": platform-level control messages (e.g., capabilities exchange).
359
+ * Inner payload of a `runtimeMessage` with `type === "moderation"`. Surfaces
360
+ * a content-moderation outcome to the client app on any moderatable input
361
+ * (free-text fields, file uploads) the configured policy flags — subscribe
362
+ * via `reactor.on("runtimeMessage", ...)` and filter on `type`.
156
363
  */
157
- type MessageScope = "application" | "runtime";
158
-
159
- interface ReactorError {
160
- code: string;
364
+ interface ModerationEvent {
365
+ action: ModerationAction;
366
+ /** Modality of the flagged input. `"text"` for string fields, `"image"`
367
+ * for file-upload payloads with an image MIME type. */
368
+ input_kind: 'text' | 'image';
369
+ /** Name of the inbound command/event whose payload was flagged. */
370
+ command: string;
371
+ /** Category labels that flagged (e.g. `["sexual"]`, `["violence/graphic"]`). */
372
+ categories: string[];
373
+ /** Short human-readable summary suitable for UI rendering. */
161
374
  message: string;
162
- timestamp: number;
163
- recoverable: boolean;
164
- component: "api" | "gpu";
165
- retryAfter?: number;
166
- }
167
- declare class ConflictError extends Error {
168
- constructor(message: string);
169
- }
170
- declare class AbortError extends Error {
171
- constructor(message: string);
172
- }
173
- /** Matches both our custom AbortError and the native DOMException thrown by fetch(). */
174
- declare function isAbortError(error: unknown): boolean;
175
- declare class SessionLostError extends Error {
176
- constructor(message: string);
177
- }
178
- declare function isSessionLostError(error: unknown): boolean;
179
- interface ReactorState$1 {
180
- status: ReactorStatus;
181
- lastError?: ReactorError;
182
375
  }
183
376
  /**
184
- * Options for configuring the connect polling behavior.
377
+ * `Reactor` construction options. Only `modelName` is required.
378
+ *
379
+ * Everything but `jwt` passes straight through to the wasm binding's
380
+ * `ClientOptions` — see `crates/reactor-wasm/src/types.rs` for what each
381
+ * field does. `jwt` lives here instead because the binding takes it as a
382
+ * second constructor argument, not a field; `Reactor` accepts one options
383
+ * object and splits it internally.
185
384
  */
186
- interface ConnectOptions {
187
- /** Maximum number of SDP polling attempts before giving up. Default: 6. */
188
- maxAttempts?: number;
189
- /**
190
- * When true (default), sends `resume_track` for every recvonly track
191
- * immediately after the connection is established, causing the backend to
192
- * begin streaming those tracks — this preserves the pre-multi-connection
193
- * behaviour where output tracks flow automatically on connect. Set to false
194
- * to keep recvonly tracks paused on connect and resume them individually via
195
- * `resumeTrack()` (e.g. multi-connection apps that only subscribe to a
196
- * subset of peers).
197
- *
198
- * A track that arrives after that is resumed on its own, so one track
199
- * appearing never disturbs another the caller has paused.
200
- */
201
- autoResumeTracks?: boolean;
202
- /**
203
- * Attach to a session that already exists (e.g. one created by a backend)
204
- * instead of creating a new one. When set, `connect()` skips `POST /sessions`
205
- * and brings up the transport directly against this id. The JWT passed to
206
- * `connect()` must be valid for the account that owns the session.
207
- */
208
- sessionId?: string;
209
- /**
210
- * Use a specific WebRTC connection id instead of minting one. When omitted
211
- * (default), the transport registers a fresh connection (`POST .../connections`)
212
- * and the server mints the id. When set, the transport skips registration and
213
- * sends its SDP offer directly to that connection — so the id must already have
214
- * been registered under this session (e.g. a backend called `POST .../connections`
215
- * and handed the id to this client) and must still be open.
216
- *
217
- * `connect()` rejects if the id is invalid (out of the server's accepted range)
218
- * or if no open connection with that id exists for the session.
219
- */
220
- connectionId?: number;
385
+ interface ReactorOptions extends ClientOptions {
386
+ /** A token, or a resolver called before every authenticated request.
387
+ * Omit for an unauthenticated local runtime. Replaceable later by passing
388
+ * a new one to `connect()`. */
389
+ jwt?: JwtSource;
221
390
  }
222
391
  /**
223
- * Transport-agnostic timing breakdown of the connect() handshake, recorded
224
- * once per connection and included in every subsequent {@link ConnectionStats}
225
- * update. All durations are in milliseconds (from `performance.now()`).
392
+ * Timing breakdown of the `connect()` handshake, recorded once per connection
393
+ * and included in every subsequent `ConnectionStats` update. All durations
394
+ * are in milliseconds (from `performance.now()`).
226
395
  *
227
- * For transport-specific timings (e.g. ICE negotiation, data channel open),
228
- * see the relevant transport stats type (e.g. {@link WebRTCTransportTimings}).
396
+ * `sessionCreationMs` covers session creation/adoption (the binding's
397
+ * `"connecting"` phase); `transportConnectingMs` covers the session-ready
398
+ * wait and transport handshake together (the `"waiting"` phase) — that
399
+ * handshake happens entirely inside `reactor-core`, so this can only split
400
+ * on the phase boundaries the binding's status events expose, not on the
401
+ * finer steps within each one.
229
402
  */
230
403
  interface ConnectionTimings {
231
- /** POST /sessions round-trip time */
232
404
  sessionCreationMs: number;
233
- /** Total time spent in transport.connect() (signaling, negotiation, etc.) */
234
405
  transportConnectingMs: number;
235
- /** End-to-end: connect() invocation → status "ready" */
406
+ /** End-to-end: connect() invocation → status "ready". */
236
407
  totalMs: number;
237
408
  }
238
409
  interface ConnectionStats {
239
410
  /** ICE candidate-pair round-trip time in milliseconds */
240
- rtt?: number;
411
+ rtt?: number | undefined;
241
412
  /** ICE candidate type: "host", "srflx", "prflx", or "relay" (TURN) */
242
- candidateType?: string;
413
+ candidateType?: string | undefined;
243
414
  /** Estimated available incoming bitrate in bits/second */
244
- availableIncomingBitrate?: number;
415
+ availableIncomingBitrate?: number | undefined;
245
416
  /** Estimated available outgoing bitrate in bits/second */
246
- availableOutgoingBitrate?: number;
247
- /** Real-time Incoming bitrate in bits/second */
248
- incomingBitrate?: number;
249
- /** Real-time Outgoing bitrate in bits/second */
250
- outgoingBitrate?: number;
417
+ availableOutgoingBitrate?: number | undefined;
418
+ /** Real-time incoming bitrate in bits/second */
419
+ incomingBitrate?: number | undefined;
420
+ /** Real-time outgoing bitrate in bits/second */
421
+ outgoingBitrate?: number | undefined;
251
422
  /** Received video frames per second */
252
- framesPerSecond?: number;
423
+ framesPerSecond?: number | undefined;
253
424
  /** Ratio of packets lost (0-1) */
254
- packetLossRatio?: number;
425
+ packetLossRatio?: number | undefined;
255
426
  /** Network jitter in seconds (from inbound-rtp) */
256
- jitter?: number;
427
+ jitter?: number | undefined;
257
428
  /** Timing breakdown of the initial connection handshake (set once, persisted until disconnect) */
258
- connectionTimings?: ConnectionTimings;
429
+ connectionTimings?: ConnectionTimings | undefined;
259
430
  timestamp: number;
260
431
  }
261
- type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "trackReceived" | "error" | "sessionExpirationChanged" | "schemaReceived" | "statsUpdate";
432
+ /** Discriminator on a {@link Clip}. `"snap"` from `requestClip()`, `"recording"` from `requestRecording()`. */
433
+ type ClipKind = 'snap' | 'recording';
262
434
  /**
263
- * Severity tier of a content moderation event delivered as the inner
264
- * payload of a `runtimeMessage` with `type === "moderation"`.
435
+ * A finished (or soon-available) clip, from `requestClip()` / `requestRecording()`.
265
436
  *
266
- * - `"warn"`: the input scored above the warn threshold but below the
267
- * terminate threshold. The session continues; this is informational
268
- * only.
269
- * - `"terminate"`: the input crossed the terminate threshold. The
270
- * session will be ended shortly after this message is dispatched.
271
- */
272
- type ModerationAction = "warn" | "terminate";
273
- /**
274
- * Inner payload of a `runtimeMessage` with `type === "moderation"`.
275
- *
276
- * Surfaces a content-moderation outcome to the client app. Fires on
277
- * any moderatable input (free-text fields, file uploads) that the
278
- * configured moderation policy flags. Apps receive it by subscribing
279
- * to the existing `runtimeMessage` event and filtering on `type`:
280
- *
281
- * reactor.on("runtimeMessage", (m) => {
282
- * if (m?.type === "moderation") {
283
- * const payload = m.data as ModerationEvent;
284
- * // ...render banner, log, etc.
285
- * }
286
- * });
287
- */
288
- interface ModerationEvent {
289
- /** Severity tier — `"warn"` continues the session, `"terminate"` ends it. */
290
- action: ModerationAction;
291
- /**
292
- * Modality of the flagged input. `"text"` for string fields,
293
- * `"image"` for `UploadedFile` payloads with an image MIME type.
294
- */
295
- input_kind: "text" | "image";
296
- /**
297
- * Name of the inbound command/event whose payload was flagged
298
- * (e.g. `"set_prompt"`, `"set_image"`, `"fileUploaded"`).
299
- */
300
- command: string;
301
- /** Category labels that flagged (e.g. `["sexual"]`, `["violence/graphic"]`). */
302
- categories: string[];
303
- /** Short human-readable summary suitable for UI rendering. */
304
- message: string;
305
- }
306
-
307
- /**
308
- * Lazy resolver for the Coordinator bearer token. The SDK calls this
309
- * immediately before each authenticated HTTP request, so short-lived
310
- * tokens (Clerk session JWTs, etc.) are refreshed transparently.
311
- * Returning `""` suppresses the `Authorization` header entirely.
312
- */
313
- type JwtResolver = () => string | Promise<string>;
314
- /** Static token, or a {@link JwtResolver} invoked per request. */
315
- type JwtSource = string | JwtResolver;
316
- /** Wrap a {@link JwtSource} into a {@link JwtResolver}. */
317
- declare function normalizeJwtSource(source: JwtSource): JwtResolver;
318
-
319
- /**
320
- * Stateless primitives for the Reactor recording feature.
321
- *
322
- * This module owns:
323
- * - Public-facing {@link Clip} type, {@link RecordingError} class, and
324
- * the `RuntimeRecordingMessageType` enum.
325
- * - Wire schemas (`ClipReadyPayloadSchema`, `ClipFailedPayloadSchema`)
326
- * plus `clipFromPayload` to convert snake_case wire payloads into
327
- * camelCase `Clip` objects.
328
- * - HTTP helpers `fetchPlaylist` (deadline-driven polling) and
329
- * `parsePlaylist` (HLS `.m3u8` parser).
330
- * - The `downloadClipAsFile` helper that streams the referenced
331
- * fMP4 chunks, remuxes them into a flat social-media-ready MP4
332
- * via `mp4box` (PTS=0, faststart, `major_brand=isom`), and
333
- * returns a Blob for browser download.
334
- *
335
- * Stateful pieces (FIFO promise correlator, in-flight request
336
- * lifecycle, integration with Reactor's event bus) live in the
337
- * `RecordingClient` class in `core/RecordingClient.ts`.
338
- *
339
- * Wire contract is documented end-to-end in the *Video Recording
340
- * Feature* Notion page; the runtime side ships in
341
- * `reactor_runtime/recording/`.
342
- */
343
-
344
- /**
345
- * Names of the runtime-scoped messages used by the recording feature.
346
- * Outbound names are sent via `Reactor.sendCommand(name, …, "runtime")`;
347
- * inbound names appear as `message.type` on `runtimeMessage` events.
348
- */
349
- declare const RuntimeRecordingMessageType: {
350
- readonly REQUEST_CLIP: "requestClip";
351
- readonly REQUEST_RECORDING: "requestRecording";
352
- readonly CLIP_READY: "clipReady";
353
- readonly CLIP_FAILED: "clipFailed";
354
- };
355
- /** Discriminator on a {@link Clip}. `"snap"` from `requestClip`, `"recording"` from `requestRecording`. */
356
- type ClipKind = "snap" | "recording";
357
- /**
358
- * Resolved outcome of a {@link Reactor.requestClip} / {@link Reactor.requestRecording} call.
359
- *
360
- * The runtime returns immediately on every request — it does *not*
361
- * block until the in-progress chunk has been finalised. The response
362
- * is a *promise*: `endMarker` reflects wall-clock at request time
363
- * and may point inside a chunk ffmpeg is still writing. The
364
- * `/clips` manifest endpoint returns `202 Retry-After` while that
365
- * chunk is in flight; the SDK polls until `200`.
366
- *
367
- * - `startMarker` / `endMarker` / `nowMarker` are session-relative
368
- * seconds since recorder start.
369
- * - `predictedReadyAtMs` is a **Unix epoch in milliseconds** — the
370
- * runtime's estimate of when the boundary chunk will be servable
371
- * by `/clips`. Compare against `Date.now()` to drive a "ready in
372
- * Ns" indicator. It is only an estimate: the SDK polls `/clips`
373
- * until the manifest is actually ready and does not give up when
374
- * this epoch passes (see {@link fetchPlaylist} for the polling and
375
- * cancellation model).
376
- * - `playlistUrl` is short-lived in production (the embedded chunk
377
- * URLs are presigned for a few minutes). Re-issuing the request
378
- * produces a fresh URL with fresh presigning.
437
+ * The runtime returns immediately on every request — it does not block until
438
+ * the in-progress chunk finalizes. `predictedReadyAtMs` is the runtime's own
439
+ * estimate of when `playlistUrl` becomes fetchable; `fetchPlaylist()` and
440
+ * `downloadClipAsFile()` poll past it until the manifest is actually ready.
379
441
  */
380
442
  interface Clip {
381
443
  sessionId: string;
382
444
  kind: ClipKind;
445
+ /** Session-relative seconds since recorder start. */
383
446
  startMarker: number;
384
447
  endMarker: number;
385
448
  nowMarker: number;
449
+ /** Unix epoch in milliseconds. */
386
450
  predictedReadyAtMs: number;
451
+ /** Absolute HLS manifest URL — short-lived; re-issuing the request produces a fresh one. */
387
452
  playlistUrl: string;
388
453
  }
389
- /**
390
- * Error thrown when a recording request cannot be served.
391
- *
392
- * `code` is a stable, machine-readable identifier; `reason` is the
393
- * raw string the runtime / manifest endpoint returned (passed through
394
- * verbatim from `clipFailed.reason`, the `/clips` HTTP body, or the
395
- * SDK's pre-flight check).
396
- */
397
- declare class RecordingError extends Error {
398
- readonly code: "RECORDER_DISABLED" | "INVALID_DURATION" | "REQUEST_TIMEOUT" | "DISCONNECTED" | "CLIP_GONE" | "CLIP_NOT_READY" | "PLAYLIST_FETCH_FAILED" | "CHUNK_FETCH_FAILED" | "INVALID_PLAYLIST" | "DOWNLOAD_UNSUPPORTED" | "INTERNAL_ERROR";
399
- readonly reason: string;
400
- constructor(code: "RECORDER_DISABLED" | "INVALID_DURATION" | "REQUEST_TIMEOUT" | "DISCONNECTED" | "CLIP_GONE" | "CLIP_NOT_READY" | "PLAYLIST_FETCH_FAILED" | "CHUNK_FETCH_FAILED" | "INVALID_PLAYLIST" | "DOWNLOAD_UNSUPPORTED" | "INTERNAL_ERROR", reason: string);
401
- }
402
- /** `clipReady.data` payload as serialised by `ClipResult.to_dict()`. */
403
- declare const ClipReadyPayloadSchema: z.ZodObject<{
404
- session_id: z.ZodString;
405
- kind: z.ZodEnum<{
406
- snap: "snap";
407
- recording: "recording";
408
- }>;
409
- start_marker: z.ZodNumber;
410
- end_marker: z.ZodNumber;
411
- now_marker: z.ZodNumber;
412
- predicted_ready_at_ms: z.ZodNumber;
413
- playlist_url: z.ZodString;
414
- }, z.core.$loose>;
415
- type ClipReadyPayload = z.infer<typeof ClipReadyPayloadSchema>;
416
- /** `clipFailed.data` payload — short reason string from the runtime. */
417
- declare const ClipFailedPayloadSchema: z.ZodObject<{
418
- reason: z.ZodDefault<z.ZodString>;
419
- }, z.core.$loose>;
420
- type ClipFailedPayload = z.infer<typeof ClipFailedPayloadSchema>;
421
- /** Options for {@link clipFromPayload}. */
422
- interface ParseClipOptions {
423
- /**
424
- * Coordinator base URL. When set, resolves `payload.playlist_url`
425
- * against this base — used to convert the runtime's path-only
426
- * playlist URL (``/clips?session_id=…``) into an absolute URL the
427
- * browser/SDK can fetch. Also handles the legacy case where an
428
- * older runtime emits an absolute URL bound to its own
429
- * ``0.0.0.0`` listener: the host/port are rewritten onto the
430
- * coordinator.
431
- */
432
- coordinatorBaseUrl?: string;
454
+ interface ReactorEventMap {
455
+ statusChanged: (status: ReactorStatus) => void;
456
+ sessionIdChanged: (sessionId: string | undefined) => void;
457
+ error: (error: ReactorError) => void;
458
+ /** Application-scope payload from the model. */
459
+ message: (message: ReactorMessage) => void;
460
+ /** Platform-scope payload, same name as the Python SDK's `runtime_message`. */
461
+ runtimeMessage: (message: ReactorMessage) => void;
462
+ /** The model's command schema, fired once the auto-request on `"ready"`
463
+ * lands — see `getSchema()`. */
464
+ schemaReceived: (schema: ModelSchema) => void;
465
+ /** The runtime's declared capabilities, fired once available — see
466
+ * `getCapabilities()`. */
467
+ capabilitiesReceived: (capabilities: Capabilities) => void;
468
+ /** Fired when the model side of a track's media becomes available.
469
+ * `Reactor` resolves the wasm binding's raw `(name, mid)` through
470
+ * `getTrackByName`/`getStreamByName` before emitting, so callers don't
471
+ * need an extra step. `reactor-core` only ever dispatches this once the
472
+ * track is already resolvable (it drops the underlying event entirely
473
+ * otherwise), so `track`/`stream` are always real values here, never
474
+ * `undefined`; `mid` rides along as an extra escape hatch for callers
475
+ * that want the binding's own identifier (e.g. for
476
+ * `getTrackByMid`/`getStreamByMid`). */
477
+ trackReceived: (name: string, track: MediaStreamTrack, stream: MediaStream, mid: string | undefined) => void;
478
+ /** Fired every `STATS_INTERVAL_MS` while the session is "ready" — see
479
+ * `getStats()`. */
480
+ statsUpdate: (stats: ConnectionStats) => void;
433
481
  }
482
+ type ReactorEventName = keyof ReactorEventMap;
483
+
434
484
  /**
435
- * Convert a validated {@link ClipReadyPayload} into the public {@link Clip}.
436
- * Pure: no IO, no side effects.
485
+ * Browser-side primitives for turning a `Clip` (from `requestClip()` /
486
+ * `requestRecording()`) into playable or downloadable media.
487
+ *
488
+ * `Clip.playlistUrl` names an HLS media playlist — `#EXT-X-VERSION:7`
489
+ * fragmented MP4, an `#EXT-X-MAP` init segment followed by `.m4s` media
490
+ * fragments — that the caller fetches and assembles; Reactor itself doesn't
491
+ * host clips. This module owns fetching and parsing that playlist
492
+ * (`fetchPlaylist` / `parsePlaylist`), wrapping it for a `<video>` element or
493
+ * `hls.js` (`createPlayableManifestUrl`), and assembling the referenced
494
+ * chunks into a flat, downloadable MP4 (`downloadClipAsFile`).
437
495
  */
438
- declare function clipFromPayload(payload: ClipReadyPayload, options?: ParseClipOptions): Clip;
496
+
439
497
  /**
440
- * Resolve `target` against `base`, returning an absolute URL.
441
- *
442
- * Two cases:
443
- *
444
- * * **Path-only / relative target** (no scheme — e.g. the
445
- * runtime's current ``/clips?session_id=…`` shape): joined
446
- * against ``base`` via ``new URL(target, base)``, preserving
447
- * path, query, and fragment.
448
- * * **Absolute target** (``http://…`` / ``https://…``, e.g. a legacy
449
- * runtime emitting a URL bound to its own ``0.0.0.0`` listener):
450
- * scheme, hostname, and port are replaced with ``base``'s,
451
- * preserving path, query, and fragment.
498
+ * Error thrown when a clip's playlist or chunks can't be fetched, parsed, or
499
+ * assembled into a file. Scoped to this module — a failure in
500
+ * `requestClip()` / `requestRecording()` themselves surfaces as a
501
+ * `ReactorError`, since those go through `reactor-core`'s own error channel.
452
502
  *
453
- * Returns the original ``target`` on any parse failure rather than
454
- * throwing — the SDK consumes the URL eagerly and shouldn't break
455
- * a session over a malformed clip envelope.
503
+ * `code` is a stable, machine-readable identifier; `reason` is the raw
504
+ * string behind it (an HTTP status, a parse complaint, …).
456
505
  */
457
- declare function rewriteUrlHost(target: string, base: string): string;
458
- /** Internal — segments referenced by an HLS manifest, in playback order. */
506
+ declare class RecordingError extends Error {
507
+ readonly code: 'CLIP_GONE' | 'CLIP_NOT_READY' | 'PLAYLIST_FETCH_FAILED' | 'CHUNK_FETCH_FAILED' | 'INVALID_PLAYLIST' | 'DOWNLOAD_UNSUPPORTED';
508
+ readonly reason: string;
509
+ constructor(code: 'CLIP_GONE' | 'CLIP_NOT_READY' | 'PLAYLIST_FETCH_FAILED' | 'CHUNK_FETCH_FAILED' | 'INVALID_PLAYLIST' | 'DOWNLOAD_UNSUPPORTED', reason: string);
510
+ }
511
+ /** Segments referenced by an HLS manifest, in playback order. */
459
512
  interface ParsedPlaylist {
460
513
  initUrl: string;
461
514
  segmentUrls: string[];
462
515
  }
463
516
  /**
464
- * Suggested grace period for callers that opt into a *bounded* wait by
465
- * passing it as {@link FetchPlaylistOptions.slackMs}. It is **not** a
466
- * default: {@link fetchPlaylist} polls indefinitely unless a bound is
467
- * supplied. Provided so callers who do want the old ~15 s ceiling can
468
- * ask for it by name rather than hard-coding a magic number.
517
+ * Suggested grace period for callers that opt into a bounded wait by passing
518
+ * it as `FetchPlaylistOptions.slackMs`. Not a default — `fetchPlaylist()`
519
+ * polls indefinitely unless a bound is supplied.
469
520
  */
470
521
  declare const DEFAULT_PLAYLIST_POLL_SLACK_MS = 15000;
471
522
  interface FetchPlaylistOptions {
472
523
  /**
473
- * Unix epoch (ms) when the runtime predicts the boundary chunk will
474
- * be servable. Pass `clip.predictedReadyAtMs` here. On its own it
475
- * does *not* stop polling — it only anchors the optional `slackMs`
476
- * deadline. Use it to drive a "ready in Ns" indicator.
524
+ * Unix epoch (ms) when the runtime predicts the boundary chunk will be
525
+ * servable — pass `clip.predictedReadyAtMs`. On its own this doesn't stop
526
+ * polling; it only anchors the optional `slackMs` deadline.
477
527
  */
478
528
  predictedReadyAtMs?: number;
479
529
  /**
480
- * Opt-in grace period that turns polling into a *bounded* wait. When
481
- * set to a finite value, a stuck `202` produces `CLIP_NOT_READY` once
482
- * `max(predictedReadyAtMs, pollStart) + slackMs` passes. Omit (the
483
- * default) to poll indefinitely until the manifest is ready or the
484
- * caller aborts via `signal`. See {@link DEFAULT_PLAYLIST_POLL_SLACK_MS}
485
- * for a sensible value if you want the old ~15 s ceiling.
530
+ * Opt-in grace period that turns polling into a bounded wait: a stuck
531
+ * `202` produces `CLIP_NOT_READY` once `max(predictedReadyAtMs, pollStart)
532
+ * + slackMs` passes. Omit (the default) to poll indefinitely until the
533
+ * manifest is ready or the caller aborts via `signal`.
486
534
  */
487
535
  slackMs?: number;
488
- /**
489
- * Hard cap on the per-poll wait. The server's `Retry-After` header is
490
- * honored but clamped. Default 2000 ms keeps pending UI snappy.
491
- */
536
+ /** Hard cap on the per-poll wait. `Retry-After` is honored but clamped. Default 2000 ms. */
492
537
  maxRetryDelayMs?: number;
493
- /** Floor on the per-poll wait so we don't hot-loop on cheap networks. Default 200 ms. */
538
+ /** Floor on the per-poll wait so a cheap network doesn't hot-loop. Default 200 ms. */
494
539
  minRetryDelayMs?: number;
495
540
  /**
496
541
  * Opt-in cap on the number of `202` responses tolerated before
497
- * `CLIP_NOT_READY`. Omit (the default) to poll indefinitely; set it
498
- * for a simple attempt-count ceiling when you don't have a
499
- * `predictedReadyAtMs` to anchor a `slackMs` deadline.
542
+ * `CLIP_NOT_READY`. Omit (the default) to poll indefinitely.
500
543
  */
501
544
  maxRetries?: number;
502
545
  /**
503
- * Aborts in-flight fetches and the inter-poll sleep. Because polling
504
- * is unbounded by default, this is the primary way a caller ends a
505
- * wait that is taking too long (a timeout, a user "cancel", a React
506
- * unmount).
546
+ * Aborts in-flight fetches and the inter-poll sleep — the primary way to
547
+ * end an unbounded wait (a timeout, a user cancel, a component unmount).
507
548
  */
508
549
  signal?: AbortSignal;
509
550
  /**
510
- * Coordinator JWT. When set, attached as `Authorization: Bearer
511
- * <jwt>` on the manifest GET — the Coordinator hop. In local mode
512
- * (HttpRuntime), leave undefined.
551
+ * Coordinator JWT, attached as `Authorization: Bearer <jwt>` on the
552
+ * manifest GET. Omit in local mode (HttpRuntime).
513
553
  */
514
554
  jwt?: string;
515
555
  }
516
556
  /**
517
- * Fetch the playlist URL, polling on `202 Accepted` (which the manifest
518
- * endpoint returns while the boundary chunk is still uploading).
557
+ * Fetch `playlistUrl`, polling on `202 Accepted` — returned while the
558
+ * boundary chunk is still uploading.
519
559
  *
520
- * Polling is **unbounded by default** — it keeps retrying on `202`
521
- * until the manifest is ready or the caller aborts via `signal`. This
522
- * matches the reality that a clip's boundary chunk can take arbitrarily
523
- * long to land (a paused model closes no chunks; a long recording's
524
- * final chunk is large). Callers own the give-up policy: pass `signal`
525
- * to cancel, or opt into a ceiling with `slackMs` / `maxRetries`.
526
- *
527
- * - `200` → returns the manifest body.
528
- * - `410` / `404` → throws `CLIP_GONE`.
529
- * - `5xx`/other → throws `PLAYLIST_FETCH_FAILED` (no retry).
530
- * - `202` past an opt-in `slackMs` deadline or `maxRetries` cap →
531
- * throws `CLIP_NOT_READY`.
532
- * - aborted `signal` → rejects with the fetch/`sleep` `AbortError`.
560
+ * - `200` → the manifest body.
561
+ * - `410` / `404` → `CLIP_GONE`.
562
+ * - other → `PLAYLIST_FETCH_FAILED` (no retry).
563
+ * - `202` past an opt-in `slackMs` deadline or `maxRetries` cap → `CLIP_NOT_READY`.
564
+ * - aborted `signal` → rejects with the fetch/sleep `AbortError`.
533
565
  */
534
566
  declare function fetchPlaylist(playlistUrl: string, options?: FetchPlaylistOptions): Promise<string>;
535
567
  /**
536
- * Parse an HLS `.m3u8` body into the init segment URL plus the ordered
537
- * list of media segment URLs. Resolves relative URLs against the
538
- * playlist URL itself.
568
+ * Parse an HLS `.m3u8` body into the init segment URL plus the ordered media
569
+ * segment URLs, resolving relative URLs against `playlistUrl` itself.
539
570
  */
540
571
  declare function parsePlaylist(manifestBody: string, playlistUrl: string): ParsedPlaylist;
541
572
  /**
542
- * Wrap an HLS manifest body in a `blob:` URL suitable for `<video src>`
543
- * or `hls.js`. Bypasses the "player can't set Authorization headers"
544
- * problem: the manifest body is served from browser memory, and the
545
- * chunk URLs inside are already-signed S3 GETs.
546
- *
547
- * Path-only / relative chunk URLs in the body are absolutized against
548
- * ``playlistUrl`` first. Without this rewrite the browser would
549
- * resolve them against the ``blob:`` URL's effective base — the page's
550
- * origin — and a local-dev frontend on (e.g.) port 3000 would issue
551
- * chunk fetches against its own dev server instead of the
552
- * HttpRuntime's ``/clips/chunks/...`` endpoint on port 8080. In
553
- * production / kind-cluster mode the manifest already carries absolute
554
- * presigned S3 URLs and `resolveAgainst` is a no-op on them.
573
+ * Wrap an HLS manifest body in a `blob:` URL suitable for `<video src>` or
574
+ * `hls.js`. Bypasses "the player can't set an Authorization header": the
575
+ * manifest is served from memory, and its chunk URLs are already-signed S3
576
+ * GETs. Path-only chunk URLs in the body are absolutized against
577
+ * `playlistUrl` first — without that, the browser would resolve them against
578
+ * the `blob:` URL's own origin instead of the runtime's.
555
579
  *
556
- * Caller owns the returned URL — revoke it via `URL.revokeObjectURL`
557
- * when playback tears down. Browser-only; throws `INVALID_PLAYLIST`
558
- * outside a DOM environment.
580
+ * Caller owns the returned URL — revoke it via `URL.revokeObjectURL` when
581
+ * playback tears down. Browser-only; throws `INVALID_PLAYLIST` outside a DOM
582
+ * environment.
559
583
  */
560
584
  declare function createPlayableManifestUrl(manifestBody: string, playlistUrl: string): string;
561
585
  interface DownloadClipOptions {
562
- /**
563
- * Coordinator JWT. Attached on the manifest GET only; the chunks
564
- * referenced inside the manifest are S3 presigned URLs and are
565
- * fetched unauthenticated.
566
- */
586
+ /** Coordinator JWT for the manifest GET. The chunks it references are S3
587
+ * presigned URLs, fetched unauthenticated. */
567
588
  jwt?: string;
568
- /** Forwarded to every request. Cancels both the playlist poll and any in-flight chunk fetches. */
589
+ /** Cancels both the playlist poll and any in-flight chunk fetches. */
569
590
  signal?: AbortSignal;
570
591
  /** Called after each chunk completes — useful for progress UI. */
571
592
  onProgress?: (info: {
@@ -575,625 +596,565 @@ interface DownloadClipOptions {
575
596
  }) => void;
576
597
  }
577
598
  /**
578
- * Stream the chunks referenced by `clip.playlistUrl`, remux the
579
- * assembled bytes into a flat social-media-ready MP4, and (when
580
- * `filename` is non-null) trigger a browser-native `<a download>`.
581
- * Pass `filename: null` to skip the download trigger and just
582
- * receive the Blob.
599
+ * Fetch the chunks `clip.playlistUrl` references, remux them into a flat
600
+ * MP4, and (when `filename` is non-null) trigger a browser `<a download>`.
601
+ * Pass `filename: null` to skip the download trigger and just get the Blob.
583
602
  *
584
- * The remux step rewrites the container only — H.264 NAL units and
585
- * AAC packets pass through unchanged — so `start_time=0`,
586
- * `+faststart`, and `major_brand=isom` come for free without any
587
- * re-encode cost. See {@link maybeRemux} for the fallback
588
- * semantics on the rare parse failure.
603
+ * See {@link assembleClipBlob} for the remux and memory-bound caveats.
589
604
  */
590
605
  declare function downloadClipAsFile(clip: Clip, filename?: string | null, options?: DownloadClipOptions): Promise<Blob>;
591
606
 
592
607
  /**
593
- * Per-Reactor recording client. Owns the FIFO promise correlator for
594
- * inbound `clipReady` / `clipFailed` runtime messages and the
595
- * lifecycle hooks (subscribe on construct, reject pending requests
596
- * on disconnect). Reactor exposes thin delegations for the common
597
- * case; this class is exported for advanced consumers and isolated
598
- * testing.
608
+ * A live connection to a Reactor model.
599
609
  */
600
-
601
- /** Default per-request timeout for `clipReady` / `clipFailed`. */
602
- declare const DEFAULT_CLIP_REQUEST_TIMEOUT_MS = 10000;
603
- /** Slim adapter the {@link RecordingClient} requires from its host. */
604
- interface RecordingClientHost {
605
- /**
606
- * Subscribe to runtime-scoped messages on the data channel.
607
- * Returns an unsubscribe function. Mirrors the
608
- * `reactor.on("runtimeMessage", …)` pattern.
609
- */
610
- onRuntimeMessage: (handler: (message: unknown) => void) => () => void;
611
- /**
612
- * Subscribe to status changes (so the client can reject pending
613
- * requests on disconnect). Returns an unsubscribe function.
614
- */
615
- onStatusChanged: (handler: (status: ReactorStatus) => void) => () => void;
616
- /**
617
- * Send a runtime-scoped command on the data channel. The
618
- * `RecordingClient` uses this to fire `requestClip` /
619
- * `requestRecording`.
610
+ declare class Reactor implements Disposable {
611
+ private readonly clientOptions;
612
+ private jwt;
613
+ private client;
614
+ private clientPromise;
615
+ private disposed;
616
+ private _lastError;
617
+ private schema;
618
+ /** Bumped on every `refreshSchema()` call — lets a call detect it's been
619
+ * superseded by a newer one even when `client` itself hasn't changed
620
+ * (e.g. two "ready" transitions on the same reused client). */
621
+ private schemaRefreshId;
622
+ private capabilities;
623
+ private stats;
624
+ private connectionTimings;
625
+ private statsPollHandle;
626
+ /** Bumped on every `startStatsPolling()`/`stopStatsPolling()` call — lets an
627
+ * in-flight `getStats()` recognize it's stale once it resolves, even if
628
+ * `this.client` hasn't changed in the meantime. */
629
+ private statsPollGeneration;
630
+ /** Set on the "connecting" status transition, cleared once `connectionTimings`
631
+ * is finalized on "ready" — see `handleStatusChanged()`. */
632
+ private connectStartTime;
633
+ private waitingStartTime;
634
+ private readonly emitter;
635
+ /** Serializes connect()/reconnect()/disconnect() (and the free() inside
636
+ * disconnect()/[Symbol.dispose]) against each other. Calling into the
637
+ * client concurrently with one of these (e.g. a user clicking Disconnect
638
+ * mid-connect) races its internal state and can throw ("attempted to
639
+ * take ownership of Rust value while it was borrowed") or corrupt it
640
+ * outright. */
641
+ private readonly queue;
642
+ constructor(options: ReactorOptions);
643
+ /**
644
+ * `jwt`, when given, replaces whatever `new Reactor({ jwt })` was given —
645
+ * including on a client that's still around from a recoverable
646
+ * `disconnect(true)`.
647
+ *
648
+ * Throws if already connected or connecting; call `disconnect()` first.
620
649
  */
621
- sendRuntimeCommand: (command: string, data: Record<string, unknown>) => Promise<void>;
622
- /** Current connection status — guards `requestClip` before it goes on the wire. */
623
- getStatus: () => ReactorStatus;
650
+ connect(jwt?: JwtSource, options?: ConnectOptions): Promise<void>;
624
651
  /**
625
- * Coordinator base URL used to resolve `clip.playlistUrl` against.
652
+ * Ends the connection. By default (`recoverable = false`) this also frees
653
+ * the wasm resource graph — the pump/dispatcher/heartbeat tasks and the
654
+ * peer connection — in one step. Pass `recoverable: true` to keep the
655
+ * wasm client alive so a later `connect()`/`reconnect()` doesn't have to
656
+ * reload wasm and reconstruct it from scratch.
626
657
  *
627
- * The runtime now emits a path-only ``playlist_url`` (e.g.
628
- * ``/clips?session_id=…``) so the SDK is the absolute-origin owner
629
- * for both local-dev (HttpRuntime on the SDK's ``apiUrl``) and
630
- * production (Coordinator on the SDK's ``apiUrl``). We always
631
- * resolve against the ``Reactor``'s coordinator URL — there is no
632
- * remote-vs-local divergence on the read path.
658
+ * Note this only governs the *local* resource graph — the binding's own
659
+ * `disconnect()` always ends the session server-side regardless of this
660
+ * flag, so `recoverable` isn't a way to keep the session itself alive.
633
661
  *
634
- * For backwards-compat with older runtimes that emitted absolute
635
- * URLs (scheme + host bound to the runtime's own listener,
636
- * e.g. ``http://0.0.0.0:8080/clips?…``), the same URL is also used
637
- * to rewrite the host onto the coordinator — see
638
- * ``rewriteUrlHost`` in ``utils/recording.ts``.
639
- */
640
- getCoordinatorBaseUrl: () => string | undefined;
641
- }
642
- declare class RecordingClient {
643
- private readonly host;
644
- private pendingClipRequests;
645
- /** Timeout applied per request; configurable for tests. */
646
- private readonly requestTimeoutMs;
647
- /** Cleanup handles for the host event subscriptions. */
648
- private readonly unsubscribers;
649
- constructor(host: RecordingClientHost, options?: {
650
- requestTimeoutMs?: number;
651
- });
652
- /**
653
- * Request a clip covering the last `durationSeconds` of the live
654
- * session. See {@link Reactor.requestClip}.
662
+ * Queued behind any in-flight `connect()`/`reconnect()` — see `queue`'s
663
+ * docs for why calling into the client concurrently with one of those is
664
+ * unsafe.
655
665
  */
656
- requestClip(durationSeconds: number): Promise<Clip>;
657
- /**
658
- * Request a clip covering the entire session up to "now". See
659
- * {@link Reactor.requestRecording}.
660
- */
661
- requestRecording(): Promise<Clip>;
666
+ disconnect(recoverable?: boolean): Promise<void>;
662
667
  /**
663
- * Poll `/clips` and return the raw manifest body. Same polling
664
- * semantics as the bare {@link fetchPlaylist} helper; the caller is
665
- * responsible for supplying the Coordinator JWT via `options.jwt`
666
- * (origin-scoped to `clip.playlistUrl`). In local mode against the
667
- * HttpRuntime, `options.jwt` should be omitted.
668
+ * Only `options.maxAttempts` has an effect here — the rest of
669
+ * `ConnectOptions` (session adoption, connection id, auto-resume) only
670
+ * makes sense when establishing a session in the first place, same as v2's
671
+ * `reconnect()` always ignored them.
668
672
  */
669
- fetchPlaylist(clip: Clip, options?: FetchPlaylistOptions): Promise<string>;
673
+ reconnect(options?: ConnectOptions): Promise<void>;
670
674
  /**
671
- * Fetch the manifest and return a `blob:` URL suitable for
672
- * `<video src>` / `hls.js`. The player reads the manifest from
673
- * browser memory; chunk URLs inside are presigned S3 GETs.
675
+ * Sends a command to the model and resolves with its correlated reply.
674
676
  *
675
- * Caller owns the returned URL — revoke it via `URL.revokeObjectURL`
676
- * when playback tears down. Pass `options.jwt` for production
677
- * `/clips` (the Coordinator hop) — see {@link FetchPlaylistOptions}.
678
- */
679
- getPlayableManifestUrl(clip: Clip, options?: FetchPlaylistOptions): Promise<string>;
680
- /**
681
- * Thin delegation to {@link downloadClipAsFile}. Caller must pass
682
- * `options.jwt` in production — see {@link DownloadClipOptions}.
683
- */
684
- downloadClipAsFile(clip: Clip, filename?: string | null, options?: DownloadClipOptions): Promise<Blob>;
685
- /**
686
- * Drop every pending request and unsubscribe from host events.
687
- * Safe to call multiple times; further `requestClip` /
688
- * `requestRecording` calls after `destroy()` will hang waiting for
689
- * a response that will never arrive — host should not call into
690
- * the client after destroy.
691
- */
692
- destroy(): void;
693
- /**
694
- * Register a pending FIFO entry, send the runtime message via
695
- * the host, and resolve when the next `clipReady` / `clipFailed`
696
- * arrives.
697
- */
698
- private dispatchClipRequest;
699
- /**
700
- * Match inbound `clipReady` / `clipFailed` to the next pending
701
- * request FIFO; ignore every other runtime message type.
702
- */
703
- private onRuntimeMessage;
704
- private onStatusChanged;
705
- /** Reject every in-flight request with a typed disconnect error. */
706
- private rejectPending;
707
- }
708
-
709
- declare const DEFAULT_BASE_URL = "https://api.reactor.inc";
710
- declare const OptionsSchema: z.ZodObject<{
711
- apiUrl: z.ZodDefault<z.ZodString>;
712
- modelName: z.ZodString;
713
- local: z.ZodDefault<z.ZodBoolean>;
714
- modelTracks: z.ZodOptional<z.ZodArray<z.ZodObject<{
715
- name: z.ZodString;
716
- kind: z.ZodEnum<{
717
- video: "video";
718
- audio: "audio";
719
- }>;
720
- direction: z.ZodEnum<{
721
- recvonly: "recvonly";
722
- sendonly: "sendonly";
723
- }>;
724
- }, z.core.$strip>>>;
725
- }, z.core.$strip>;
726
- type Options = z.input<typeof OptionsSchema>;
727
-
728
- type EventHandler = (...args: any[]) => void;
729
- declare class Reactor {
730
- private coordinatorClient;
731
- private transportClient;
732
- private status;
733
- private coordinatorUrl;
734
- private lastError?;
735
- private model;
736
- private sessionExpiration?;
737
- private local;
738
- private sessionId?;
739
- /**
740
- * True only when the active session was created by THIS connect flow
741
- * (via `createSession()`). False when the session was adopted via
742
- * `connect({ sessionId })`. We must never DELETE a session we did not
743
- * create — another client (or the backend that created it) owns its
744
- * lifecycle, so on disconnect/teardown/error an adopting client tears
745
- * down its own transport but leaves the session alive.
746
- */
747
- private createdSession;
748
- private retryingSessionLoss;
749
- private connectStartTime?;
750
- private connectionTimings?;
751
- private schema?;
752
- private tracks;
753
- private presetTracks?;
754
- private autoResumeTracks;
755
- private sessionResponse?;
756
- private jwtResolver?;
757
- /** Per-Reactor recording client. See {@link RecordingClient}. */
758
- readonly recording: RecordingClient;
759
- constructor(options: Options);
760
- private eventListeners;
761
- /**
762
- * Returns the JWT resolver supplied to the most recent
763
- * {@link connect} call, or `undefined` if none was set (pre-connect
764
- * or local mode). Used by clip surfaces as a fallback when their
765
- * own `getJwt` prop is omitted.
766
- */
767
- getJwtResolver(): JwtResolver | undefined;
768
- on(event: ReactorEvent, handler: EventHandler): void;
769
- off(event: ReactorEvent, handler: EventHandler): void;
770
- emit(event: ReactorEvent, ...args: any[]): void;
771
- /**
772
- * Sends a command to the model via the data channel.
677
+ * `undefined` means the handler acknowledged the command but sent no
678
+ * reply body. The binding's own typed signature promises `undefined` for
679
+ * that case, but its serializer (serde_wasm_bindgen's `json_compatible`
680
+ * mode) actually hands back `null` — normalized here so callers can rely
681
+ * on the documented type instead of the binding's serialization quirk.
773
682
  *
774
- * When any value in `data` is a {@link FileRef}, it is automatically
775
- * extracted and serialized into a separate `uploads` section on the
776
- * wire, keyed by the parameter name. Scalar values remain in `data`.
777
- */
778
- sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
779
- /**
780
- * Uploads a file to the session's object store and returns a {@link FileRef}.
683
+ * A `FileRef` (from `uploadFile`) may be passed as a top-level value in
684
+ * `data` alongside regular parameters — it is extracted and sent as a
685
+ * separate upload reference rather than embedded in the JSON payload.
781
686
  *
782
- * Flow:
783
- * 1. POST /sessions/{id}/uploads → allocate presigned PUT URL
784
- * 2. PUT file bytes to the presigned URL
785
- * 3. Send `fileUploaded` notification on the runtime data channel
786
- * (fires `@file_uploaded` on the model if registered)
787
- * 4. Return a `FileRef` to pass into {@link sendCommand}
687
+ * Unlike every other method here, this never rejects — a failure (the
688
+ * session isn't `"ready"`, the send itself fails, …) is reported through
689
+ * `getLastError()`/the `error` event instead, resolving with `undefined`.
690
+ * This is a JS-only compatibility shim, kept because callers routinely
691
+ * fire-and-forget `sendCommand(...)` without `await`/`catch`, and a
692
+ * rejection nobody handles is an unhandled-rejection warning at best. It
693
+ * is deliberately not applied to `publishTrack`/`uploadFile`/etc., which
694
+ * throw normally.
788
695
  *
789
- * In local mode, the presigned URL returned by the runtime is rewritten
790
- * to use the SDK-configured base URL (scheme + host), so port-forwarded
791
- * setups work correctly (REA-1573).
792
- */
793
- uploadFile(file: File | Blob, options?: {
794
- name?: string;
795
- }): Promise<FileRef>;
796
- /**
797
- * Request a clip covering the last `durationSeconds` of the live
798
- * session. Capped server-side at `recording.clip_max_seconds`
799
- * (default 5 minutes). Resolves with a {@link Clip} whose
800
- * `playlistUrl` can be handed to any HLS-capable player.
696
+ * `scope` is forwarded to `sendRuntimeScopedCommand()` — see there for
697
+ * what `"runtime"` actually does.
801
698
  *
802
- * @throws {RecordingError} on invalid input, transport failure,
803
- * timeout, runtime-side `clipFailed`, or disconnect mid-request.
804
- */
805
- requestClip(durationSeconds: number): Promise<Clip>;
806
- /**
807
- * Request a clip covering the entire session up to "now". Same
808
- * mechanics as {@link requestClip} with `start = 0`; only the
809
- * resolved {@link Clip.kind} discriminator differs.
699
+ * `data` accepts any object, except a function.
810
700
  */
811
- requestRecording(): Promise<Clip>;
701
+ sendCommand<T extends object = Record<string, unknown>>(command: string, data?: NotFunction<T>, scope?: MessageScope): Promise<ReactorMessage | undefined>;
812
702
  /**
813
- * Stream the chunks referenced by `clip.playlistUrl` and trigger a
814
- * native browser download of the assembled fragmented-MP4 Blob.
815
- * Pass `filename: null` to skip the download trigger and receive
816
- * the Blob (useful for non-DOM consumers and tests).
817
- */
818
- downloadClipAsFile(clip: Clip, filename?: string | null, options?: DownloadClipOptions): Promise<Blob>;
703
+ * Handles `sendCommand(command, data, "runtime")` — this SDK has no
704
+ * generic runtime-scope channel. `reactor-core`'s `send_command` is a
705
+ * single channel; `requestSchema`/clip requests/heartbeat are each their
706
+ * own dedicated RPC instead of a scoped envelope, so there's nothing
707
+ * generic to route a scope through at the wire level.
708
+ *
709
+ * `requestSchema` and `requestCapabilities` route to their direct
710
+ * equivalents below, neither of which returns a `ReactorMessage` the way a
711
+ * normal `sendCommand()` reply would, so both resolve `undefined`; the
712
+ * actual data surfaces through `getSchema()`/`schemaReceived` and
713
+ * `getCapabilities()`/`capabilitiesReceived` as it already does. Anything
714
+ * else has no runtime-scope destination to route to — rather than silently
715
+ * doing nothing, it falls through as a normal application-scope send, with
716
+ * a console warning.
717
+ */
718
+ private sendRuntimeScopedCommand;
719
+ /** Requests the model's command schema directly. Most callers don't need
720
+ * this — it's already fetched once and cached as soon as the session
721
+ * reaches `"ready"`; use `getSchema()` for that. Resolves `undefined`
722
+ * when the model doesn't expose a schema — the binding replies with a
723
+ * wire `null` in that case rather than omitting the field. */
724
+ requestSchema(): Promise<ModelSchema | undefined>;
725
+ /** The model's command schema (an OpenAPI document), cached from the
726
+ * `requestSchema()` call fired automatically on `"ready"`. `undefined`
727
+ * until that reply has landed. */
728
+ getSchema(): ModelSchema | undefined;
729
+ /** The runtime's declared capabilities (negotiated tracks, and the
730
+ * command set when the model exposes one) — pushed once available, no
731
+ * explicit request needed. `undefined` until `capabilitiesReceived`
732
+ * fires. */
733
+ getCapabilities(): Capabilities | undefined;
734
+ /** The session resource, as the coordinator reports it — id, state,
735
+ * model, cluster, server info, and (once negotiated) `capabilities`.
736
+ * A live read straight off the wasm client, not cached — reflects
737
+ * whatever's current. `undefined` before a client exists. */
738
+ getSessionInfo(): SessionResponse | undefined;
819
739
  /**
820
- * Publishes a MediaStreamTrack to a named sendonly track.
821
- * The transceiver is already set up from capabilities — this just
822
- * calls replaceTrack() on the sender.
740
+ * Publishes a local `MediaStreamTrack` under `name` — the counterpart to a
741
+ * `sendonly` track the model declares. Awaitable. Queued behind
742
+ * connect()/disconnect()/reconnect() (unlike `sendCommand()`): a track
743
+ * operation awaits its own control round-trip, and a concurrent
744
+ * disconnect() freeing the wasm client mid-await would otherwise resume
745
+ * into a freed client — the same class of use-after-free `queue` exists to
746
+ * prevent for connect/disconnect/reconnect themselves.
823
747
  */
824
748
  publishTrack(name: string, track: MediaStreamTrack): Promise<void>;
825
- unpublishTrack(name: string): Promise<void>;
826
- pauseTrack(name: string): void;
827
- resumeTrack(name: string): void;
828
- /** Whether `name` is a track this client receives rather than sends. */
829
- private isRecvonly;
830
749
  /**
831
- * Reconnects to an existing session with a fresh transport.
750
+ * Unlike every other track method, this doesn't reject — a failure is
751
+ * reported through the `error` event instead, since this is commonly the
752
+ * last call in a `finally` block, and raising there would replace
753
+ * whatever exception was already propagating.
832
754
  */
833
- reconnect(options?: ConnectOptions): Promise<void>;
755
+ unpublishTrack(name: string): Promise<void>;
834
756
  /**
835
- * Connects to the coordinator, creates a session, then establishes
836
- * the transport using server-declared capabilities. `jwtToken` may
837
- * be a static string or a {@link JwtSource} resolver; pass a
838
- * resolver when the token is short-lived so each Coordinator HTTP
839
- * hop sees a fresh value.
840
- *
841
- * Pass `options.sessionId` to attach to a session that already exists
842
- * (e.g. one created by a backend) instead of creating a new one — session
843
- * creation is skipped and the transport is brought up against that id. The
844
- * `jwtToken` must be valid for the account that owns the session. Works in
845
- * local mode too (it looks the session up by id rather than starting one).
757
+ * Stops a received track: the receiver goes inactive and the runtime stops
758
+ * producing it. Awaitable, and queued behind connect()/disconnect()/
759
+ * reconnect() for the same reason as `publishTrack()`.
846
760
  */
847
- connect(jwtToken?: JwtSource, options?: ConnectOptions): Promise<void>;
761
+ pauseTrack(name: string): Promise<void>;
762
+ /** Resumes a track previously stopped with `pauseTrack()`. */
763
+ resumeTrack(name: string): Promise<void>;
848
764
  /**
849
- * Sets up event handlers for the transport client.
850
- * Each handler captures the client reference to ignore stale events.
765
+ * Requests a clip covering the last `durationSeconds` of the session.
766
+ * `reactor-core` correlates the reply itself (and enforces `"ready"`), so
767
+ * this is a thin delegation, same as `requestSchema()`. See
768
+ * `downloadClipAsFile()` to turn the result into a file.
851
769
  */
852
- private setupTransportHandlers;
770
+ requestClip(durationSeconds: number): Promise<Clip>;
771
+ /** Requests a clip covering the entire session up to now. See `requestClip()`. */
772
+ requestRecording(): Promise<Clip>;
773
+ /** Thin delegation to the standalone `downloadClipAsFile()` — see its own doc comment. */
774
+ downloadClipAsFile(clip: Clip, filename?: string | null, options?: DownloadClipOptions): Promise<Blob>;
853
775
  /**
854
- * Disconnects from both the transport and the coordinator.
776
+ * Uploads a file to the session's object store, resolving with a
777
+ * `FileRef` to pass as a top-level value in a `sendCommand()`'s `data`
778
+ * (see `extractFileRefs`). The binding itself takes `(file, name?)`
779
+ * positionally and already applies the right defaulting — a bare
780
+ * `Blob`'s name falls back to `"upload"`, and an empty/missing mime type
781
+ * to `"application/octet-stream"` — so there's nothing to wrap here.
782
+ *
783
+ * Queued behind connect()/disconnect()/reconnect(), same as the track
784
+ * ops: this awaits its own round-trip, and a concurrent disconnect()
785
+ * freeing the wasm client mid-upload would otherwise resume into a freed
786
+ * client — the same use-after-free class of race the queue exists to
787
+ * prevent.
855
788
  */
856
- disconnect(recoverable?: boolean): Promise<void>;
857
- getSessionId(): string | undefined;
789
+ uploadFile(file: File | Blob, options?: {
790
+ name?: string;
791
+ }): Promise<FileRef>;
792
+ /** All tracks the model declared, whether or not media has arrived for —
793
+ * or been published to — them yet. Empty before a client exists. */
794
+ tracks(): TrackCapability[];
795
+ /** Same as `tracks()`, plus each entry's negotiated `mid` — the id
796
+ * `trackReceived`'s `mid` argument and the `getXByMid` escape hatches key
797
+ * on. Only populated once SDP negotiation has assigned mids. */
798
+ trackMapping(): TrackMappingEntry[];
799
+ pausedTracks(): string[];
800
+ /** Drops to the raw `RTCPeerConnection` for anything this class doesn't
801
+ * wrap directly. `undefined` before a client exists. */
802
+ getPeerConnection(): RTCPeerConnection | undefined;
803
+ getTrackByMid(mid: string): MediaStreamTrack | undefined;
804
+ getStreamByMid(mid: string): MediaStream | undefined;
805
+ getTrackByName(name: string): MediaStreamTrack | undefined;
806
+ getStreamByName(name: string): MediaStream | undefined;
807
+ /**
808
+ * Supports `using reactor = new Reactor(...)`: releases the wasm resource
809
+ * graph and drops every registered event handler for good. Unlike a plain
810
+ * `disconnect()`, this instance is unusable afterward — construct a new
811
+ * `Reactor` instead of trying to `connect()` again.
812
+ */
813
+ [Symbol.dispose](): void;
814
+ /** The wasm binding's own terser `status()` name can be added alongside
815
+ * this later if it turns out to be worth it. */
858
816
  getStatus(): ReactorStatus;
859
- getState(): ReactorState$1;
817
+ /** See `getStatus()`. */
818
+ getSessionId(): string | undefined;
819
+ /** The `jwt` this instance was constructed (or last `connect()`ed) with —
820
+ * lets a component composed inside a `ReactorProvider` (e.g. `ClipPlayer`)
821
+ * authenticate its own requests without the caller repeating the resolver. */
822
+ getJwtResolver(): JwtSource | undefined;
823
+ /** The most recent `ReactorError`, from either an `error` event or a
824
+ * rejected call — whichever landed last. `undefined` until the first
825
+ * failure. */
860
826
  getLastError(): ReactorError | undefined;
861
- /**
862
- * The model's OpenAPI schema (events, outbound messages, tracks),
863
- * received over the runtime channel shortly after the session becomes
864
- * ready. `undefined` until the `schemaReceived` event has fired.
865
- */
866
- getSchema(): ModelSchema | undefined;
867
- getSessionInfo(): SessionResponse | undefined;
827
+ /** The most recent WebRTC connection stats, polled every `STATS_INTERVAL_MS`
828
+ * while "ready" — see `statsUpdate`. `undefined` before the first sample. */
868
829
  getStats(): ConnectionStats | undefined;
869
- /** Timing breakdown from the most recent connect() handshake. */
830
+ /** Timing breakdown from the most recent `connect()`/`reconnect()`
831
+ * handshake — see `ConnectionTimings`. */
870
832
  getConnectionTimings(): ConnectionTimings | undefined;
871
- private setSessionId;
872
- private setStatus;
873
- private setSessionExpiration;
874
- private resetConnectionTimings;
875
- private finalizeConnectionTimings;
876
- private createError;
833
+ on<Name extends keyof ReactorEventMap>(event: Name, handler: ReactorEventMap[Name]): void;
834
+ off<Name extends keyof ReactorEventMap>(event: Name, handler: ReactorEventMap[Name]): void;
835
+ once<Name extends keyof ReactorEventMap>(event: Name, handler: ReactorEventMap[Name]): void;
836
+ private getOrCreateClient;
837
+ private createClient;
838
+ /** Fired once per `"ready"` transition — see `getSchema()`. `getSchema()`
839
+ * isn't guaranteed populated by the time a `statusChanged` "ready" handler
840
+ * runs (this fetch is async and dispatched separately), so callers that
841
+ * need the schema as soon as it lands should listen for `schemaReceived`
842
+ * instead of reading `getSchema()` synchronously off `statusChanged`.
843
+ *
844
+ * Guards against a stale reply: if `disconnect()`/a later `connect()`
845
+ * replaces `client` before this resolves, or a newer `refreshSchema()`
846
+ * call for the same client wins the race, the result is discarded rather
847
+ * than clobbering `this.schema` (or emitting `schema`) with old data.
848
+ *
849
+ * A rejection here (e.g. the session drops mid-request) surfaces like any
850
+ * other binding failure, through the same `error` event as `onError`. */
851
+ private refreshSchema;
852
+ /** The binding replies with a wire `null` (not an omitted field) when the
853
+ * model doesn't expose a schema — normalized to `undefined` so callers
854
+ * get the same "no schema" sentinel `getSchema()` already uses instead
855
+ * of a document they could otherwise dereference. */
856
+ private normalizeSchema;
857
+ /** Frees the wasm resource graph, if one exists, and clears the cached
858
+ * schema. Reusable — unlike `[Symbol.dispose]`, this doesn't set the
859
+ * permanent `disposed` flag, so a later `connect()`/`reconnect()` lazily
860
+ * builds a fresh client.
861
+ *
862
+ * Only called from within `disconnect()`'s queued task, so `client.free()`
863
+ * is safe to call directly here — the queue already guarantees no other
864
+ * operation is running concurrently against it. */
865
+ private freeClient;
866
+ /** Tracks `connectionTimings` off the binding's own "connecting" → "waiting"
867
+ * → "ready" status sequence (see `ReactorStatus`), and starts/stops stats
868
+ * polling around the "ready" window. */
869
+ private handleStatusChanged;
870
+ private startStatsPolling;
871
+ private stopStatsPolling;
872
+ /** Called on every `disconnect()` and on `[Symbol.dispose]`. Leaves
873
+ * `client`/`schema` alone — that's `freeClient()`'s job, run separately
874
+ * when `disconnect()` isn't recoverable. `capabilities` is cleared here
875
+ * regardless, though: unlike the schema, it isn't re-fetched on demand,
876
+ * so a recoverable disconnect that skips `freeClient()` would otherwise
877
+ * leave `getCapabilities()` returning the previous session's stale
878
+ * tracks/commands until a new `capabilitiesReceived` lands. */
879
+ private resetConnectionState;
880
+ /** Wraps `cause` and records it as the most recent failure, for a call
881
+ * that's about to throw rather than emit — see `getLastError()`'s doc
882
+ * comment. */
883
+ private captureError;
884
+ /** Wraps `cause`, records it as the most recent failure, and fires the
885
+ * `error` event — the one place recording and emitting happen together,
886
+ * so `getLastError()` never drifts from what listeners were told. */
887
+ private emitError;
888
+ private assertNotDisposed;
877
889
  }
878
890
 
891
+ /** Lazy resolver for a Coordinator/runtime bearer token, called immediately
892
+ * before each authenticated request — see `JwtSource`. */
893
+ type JwtResolver = () => string | Promise<string>;
894
+ /**
895
+ * Wraps a `JwtSource` into a `JwtResolver`: a static string becomes a
896
+ * resolver that always returns it, a resolver passes through unchanged.
897
+ * Useful for feeding a source that may be either form (e.g. a
898
+ * `ReactorProvider`'s `jwtToken`) into a `getJwt` prop that expects a
899
+ * resolver.
900
+ */
901
+ declare function normalizeJwtSource(source: JwtSource): JwtResolver;
902
+
903
+ /** State kept reactive for `useReactor` selectors. Stats/schema/capabilities
904
+ * aren't mirrored here — reach them through the `internal.reactor` escape
905
+ * hatch. */
879
906
  interface ReactorState {
880
907
  status: ReactorStatus;
881
- /**
882
- * Media tracks received from the model, keyed by track name.
883
- *
884
- * Each entry maps a recvonly track name (e.g. `"main_video"`,
885
- * `"main_audio"`) to the live `MediaStreamTrack` delivered by the model.
886
- */
908
+ sessionId: string | undefined;
909
+ lastError: ReactorError | undefined;
910
+ /** Most recent app-scope `message` payload; `runtimeMessage` isn't mirrored
911
+ * here — subscribe on `internal.reactor` for that. */
912
+ lastMessage: ReactorMessage | undefined;
913
+ /** Media tracks received from the model, keyed by track name. Reset to
914
+ * `{}` on every "disconnected" status transition — a fresh connection
915
+ * invalidates whatever arrived under the previous one. Append-only within
916
+ * a session: a track pausing/unpublishing mid-session doesn't remove its
917
+ * entry, so a stale `MediaStreamTrack` can linger until the next
918
+ * disconnect. Matches v2's identical behavior (`core/store.ts`). */
887
919
  tracks: Record<string, MediaStreamTrack>;
888
- lastError?: ReactorError;
889
- sessionId?: string;
890
- sessionExpiration?: number;
891
- /** Token source for Coordinator HTTP calls — see {@link JwtSource}. */
892
- jwtToken?: JwtSource;
893
- /**
894
- * Default connect options set by the provider. Applied as base values
895
- * whenever `connect()` is called without explicit options, so that
896
- * provider-level settings like `autoResumeTracks` are honoured for
897
- * both autoConnect and manual connect calls.
898
- */
899
- connectOptions?: ConnectOptions;
920
+ /** The `jwt` the store was created with — see `createReactorStore`'s
921
+ * `options.jwt`. Set once at creation, not resynced afterward. */
922
+ jwtToken: JwtSource | undefined;
923
+ /** The `defaultConnectOptions` the store was created with — set once at
924
+ * creation, not resynced afterward. Lets a component read the
925
+ * provider-level defaults (e.g. `autoResumeTracks`) without threading
926
+ * them through props of its own. */
927
+ connectOptions: ConnectOptions | undefined;
900
928
  }
901
929
  interface ReactorActions {
902
- sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
903
- /**
904
- * Connect the underlying {@link Reactor}. `options` is forwarded verbatim —
905
- * pass `options.sessionId` to attach to an existing session instead of
906
- * creating one (see {@link ConnectOptions}).
907
- */
908
- connect(jwtToken?: JwtSource, options?: ConnectOptions): Promise<void>;
909
- disconnect(recoverable?: boolean): Promise<void>;
910
- publish(name: string, track: MediaStreamTrack): Promise<void>;
911
- unpublish(name: string): Promise<void>;
912
- /**
913
- * Ask the runtime to stop processing a recvonly track. Top-level
914
- * alias for `internal.reactor.pauseTrack(…)` — lifted onto the store
915
- * so consumers don't have to reach through `internal.reactor`. See
916
- * {@link Reactor.pauseTrack}.
917
- */
918
- pauseTrack(name: string): void;
919
- /**
920
- * Ask the runtime to resume a previously paused recvonly track.
921
- * Top-level alias for `internal.reactor.resumeTrack(…)`. See
922
- * {@link Reactor.resumeTrack}.
923
- */
924
- resumeTrack(name: string): void;
925
- reconnect(options?: ConnectOptions): Promise<void>;
926
- uploadFile(file: File | Blob, options?: {
930
+ connect: (jwt?: JwtSource, options?: ConnectOptions) => Promise<void>;
931
+ disconnect: (recoverable?: boolean) => Promise<void>;
932
+ reconnect: (options?: ConnectOptions) => Promise<void>;
933
+ sendCommand: <T extends object = Record<string, unknown>>(command: string, data?: NotFunction<T>, scope?: MessageScope) => Promise<ReactorMessage | undefined>;
934
+ publish: (name: string, track: MediaStreamTrack) => Promise<void>;
935
+ unpublish: (name: string) => Promise<void>;
936
+ pauseTrack: (name: string) => Promise<void>;
937
+ resumeTrack: (name: string) => Promise<void>;
938
+ uploadFile: (file: File | Blob, options?: {
927
939
  name?: string;
928
- }): Promise<FileRef>;
929
- /**
930
- * Capture the trailing `durationSeconds` of the live session as a
931
- * clip. Top-level alias for `internal.reactor.requestClip(…)` —
932
- * lifted onto the store so consumers don't have to reach through
933
- * `internal.reactor` for the common case. See
934
- * {@link Reactor.requestClip}.
935
- */
936
- requestClip(durationSeconds: number): Promise<Clip>;
937
- /**
938
- * Capture the entire session up to "now" as a clip. Top-level
939
- * alias for `internal.reactor.requestRecording()`. See
940
- * {@link Reactor.requestRecording}.
941
- */
942
- requestRecording(): Promise<Clip>;
943
- /**
944
- * Stream the chunks referenced by `clip.playlistUrl` and trigger a
945
- * native browser download of the assembled MP4. Top-level alias
946
- * for `internal.reactor.downloadClipAsFile(…)`. See
947
- * {@link Reactor.downloadClipAsFile}.
948
- */
949
- downloadClipAsFile(clip: Clip, filename?: string | null, options?: DownloadClipOptions): Promise<Blob>;
940
+ }) => Promise<FileRef>;
941
+ requestClip: (durationSeconds: number) => Promise<Clip>;
942
+ requestRecording: () => Promise<Clip>;
943
+ downloadClipAsFile: (clip: Clip, filename?: string | null, options?: DownloadClipOptions) => Promise<Blob>;
950
944
  }
951
- interface ReactorInternalState {
945
+ interface ReactorInternal {
946
+ /** Escape hatch: the underlying `Reactor` instance, for anything the
947
+ * selector state / action bindings above don't cover. */
952
948
  reactor: Reactor;
953
949
  }
954
950
  type ReactorStore = ReactorState & ReactorActions & {
955
- internal: ReactorInternalState;
951
+ internal: ReactorInternal;
956
952
  };
957
- interface ReactorInitializationProps extends Options {
958
- /** Token source for the underlying {@link Reactor} — see {@link JwtSource}. */
959
- jwtToken?: JwtSource;
960
- /** Default connect options applied when `connect()` is called without explicit options. */
961
- connectOptions?: ConnectOptions;
962
- }
963
953
 
964
- /**
965
- * Options for the React provider's connect behavior.
966
- * Extends the core ConnectOptions with autoConnect for the React lifecycle.
967
- */
954
+ /** `connectOptions` for the provider — adds `autoConnect` to the core
955
+ * `ConnectOptions`. Live, same as every other `ReactorProviderProps` field —
956
+ * see `ReactorProvider`'s doc comment. */
968
957
  interface ReactorConnectOptions extends ConnectOptions {
969
- /** Whether to automatically connect when the provider mounts. Default: false. */
958
+ /** Connect automatically once a Reactor is built — initial mount, or any
959
+ * later rebuild. Default `false`. */
970
960
  autoConnect?: boolean;
971
961
  }
972
- interface ReactorProviderProps extends Omit<ReactorInitializationProps, "jwtToken"> {
973
- connectOptions?: ReactorConnectOptions;
974
- /**
975
- * Static JWT token. Use when you hold a long-lived SDK JWT (e.g.
976
- * minted via `/tokens`). For short-lived tokens use {@link getJwt}.
977
- */
978
- jwtToken?: string;
979
- /**
980
- * Lazy JWT resolver invoked immediately before each Coordinator
981
- * HTTP request. Preferred for short-lived tokens. Wins over
982
- * {@link jwtToken} when both are provided.
983
- */
984
- getJwt?: JwtResolver;
962
+ interface ReactorProviderProps {
963
+ apiUrl?: string | undefined;
964
+ modelName: string;
965
+ local?: boolean | undefined;
966
+ /** Media tracks to declare up front, so the transport can prepare the SDP
967
+ * offer in parallel with session polling instead of waiting to discover
968
+ * them from the model's schema. */
969
+ modelTracks?: TrackCapability[] | undefined;
970
+ /** Static token, or a resolver called before every authenticated request
971
+ * — see `JwtSource`. Required for `autoConnect` against a non-local
972
+ * runtime; can also be supplied later via an explicit `connect()` call
973
+ * instead. */
974
+ jwtToken?: JwtSource | undefined;
975
+ connectOptions?: ReactorConnectOptions | undefined;
985
976
  children?: ReactNode;
986
977
  }
987
- declare function ReactorProvider({ children, connectOptions, jwtToken, getJwt, ...props }: ReactorProviderProps): react_jsx_runtime.JSX.Element;
988
- declare function useReactorStore<T = ReactorStore>(selector: (state: ReactorStore) => T): T;
978
+ /**
979
+ * Owns a `Reactor` instance and exposes it to `useReactor` below.
980
+ *
981
+ * `apiUrl`/`modelName`/`local`/`modelTracks`/`jwtToken`/`connectOptions`
982
+ * (including `autoConnect`) are live: changing any of them tears down the
983
+ * current `Reactor` (`disconnect()` then `[Symbol.dispose]()`) and builds a
984
+ * fresh one — the same way `useLiveKitRoom` rebuilds its `Room` when its
985
+ * construction `options` change. `Reactor` has no equivalent of LiveKit's
986
+ * `token`/`serverUrl` split (reconnecting the *same* instance with new
987
+ * credentials) or its live `connect` boolean (toggling the same `Room`'s
988
+ * connection without rebuilding it) — its constructor bundles everything, so
989
+ * any change, `autoConnect` included, means a fresh instance rather than
990
+ * reconnecting/disconnecting the existing one. Pass a stable `jwtToken`
991
+ * (e.g. via `useCallback` for a resolver) and stable `modelTracks`/
992
+ * `connectOptions` references if you don't want an unrelated parent render to
993
+ * rebuild the connection — object/array props are compared by reference
994
+ * (`modelTracks`/`connectOptions` via a `JSON.stringify` snapshot, same as
995
+ * `useLiveKitRoom` does for its own `options`).
996
+ *
997
+ * Unmounting tears down the same way — see `Reactor.disconnect()`/
998
+ * `[Symbol.dispose]()` for what that frees.
999
+ */
1000
+ declare function ReactorProvider({ apiUrl, modelName, local, modelTracks, jwtToken, connectOptions, children, }: ReactorProviderProps): react.JSX.Element;
1001
+
1002
+ /** Reads from the nearest `ReactorProvider`'s store, with a shallow-equality
1003
+ * check on the selector's result — so a selector returning a fresh object
1004
+ * each call doesn't cause a re-render on every unrelated store update. */
1005
+ declare function useReactor<T>(selector: (state: ReactorStore) => T): T;
1006
+ /** Subscribes to app-scope `message` payloads sent by the model via
1007
+ * `get_ctx().send()`. `handler` is kept in a ref so identity churn on
1008
+ * every render doesn't retrigger the subscription effect. */
1009
+ declare function useReactorMessage(handler: (message: ReactorMessage) => void): void;
1010
+ /** Subscribes to platform-scope `runtimeMessage` payloads (moderation,
1011
+ * clip/recording lifecycle, ...) — see `useReactorMessage` for app-scope
1012
+ * payloads instead. */
1013
+ declare function useReactorInternalMessage(handler: (message: ReactorMessage) => void): void;
1014
+ /** The most recent `statsUpdate` sample; `undefined` until the first one
1015
+ * arrives, and reset back to `undefined` on unmount or reactor change. */
1016
+ declare function useStats(): ConnectionStats | undefined;
989
1017
 
990
1018
  interface ReactorViewProps {
991
- /**
992
- * The name of the recvonly track to render.
993
- * Must match a track name declared in the server capabilities.
994
- * Check the model's documentation for available track names.
995
- * Defaults to `"main_video"`.
996
- */
1019
+ /** Name of the recvonly video track to render. Must match a track name
1020
+ * declared in the model's capabilities. Defaults to `"main_video"`. */
997
1021
  track?: string;
998
- /**
999
- * Optional name of a recvonly audio track to play alongside the video
1000
- * (e.g. `"main_audio"`). The audio is mixed into the same `<video>` element.
1001
- * Check the model's documentation for available track names.
1002
- */
1022
+ /** Name of a recvonly audio track to mix into the same `<video>` element
1023
+ * alongside `track`. */
1003
1024
  audioTrack?: string;
1004
1025
  width?: number;
1005
1026
  height?: number;
1006
1027
  className?: string;
1007
- style?: React.CSSProperties;
1008
- videoObjectFit?: NonNullable<React.VideoHTMLAttributes<HTMLVideoElement>["style"]>["objectFit"];
1009
- /**
1010
- * Controls whether inbound audio plays. Default is `true`
1011
- * (muted) when no `audioTrack` is set — keeps the underlying
1012
- * `<video>` element within browser autoplay policies; `false`
1013
- * when an `audioTrack` is set. Pass an explicit value to
1014
- * override either default.
1015
- */
1028
+ style?: CSSProperties;
1029
+ videoObjectFit?: NonNullable<VideoHTMLAttributes<HTMLVideoElement>['style']>['objectFit'];
1030
+ /** Defaults to `true` when no `audioTrack` is set (keeps the element within
1031
+ * browser autoplay policies), `false` otherwise. Pass an explicit value to
1032
+ * override either default. */
1016
1033
  muted?: boolean;
1017
1034
  }
1018
- declare function ReactorView({ track, audioTrack, width, height, className, style, videoObjectFit, muted, }: ReactorViewProps): react_jsx_runtime.JSX.Element;
1035
+ declare function ReactorView({ track, audioTrack, width, height, className, style, videoObjectFit, muted, }: ReactorViewProps): react.JSX.Element;
1019
1036
 
1020
1037
  interface WebcamStreamProps {
1021
- /**
1022
- * The name of the sendonly **video** track to publish the webcam to.
1023
- * Must match a track name declared in the server capabilities.
1024
- * Check the model's documentation for available track names.
1025
- */
1038
+ /** Name of the sendonly video track to publish the webcam to. Must match a
1039
+ * track name declared in the model's capabilities. */
1026
1040
  track: string;
1027
- /**
1028
- * Capture and publish the microphone alongside the webcam. Pass
1029
- * `true` for default constraints, or an explicit
1030
- * `MediaTrackConstraints` to control sample rate / device / echo
1031
- * cancellation. Requires {@link audioTrack} so the SDK knows
1032
- * which sendonly track to publish the mic to. Default `false`.
1033
- */
1041
+ /** Capture and publish the microphone alongside the webcam. `true` for
1042
+ * default constraints, or explicit `MediaTrackConstraints`. Requires
1043
+ * `audioTrack`. Defaults to `false`. */
1034
1044
  audio?: boolean | MediaTrackConstraints;
1035
- /**
1036
- * The name of the sendonly **audio** track to publish the mic to.
1037
- * Ignored when {@link audio} is `false` (the default); required
1038
- * otherwise.
1039
- */
1045
+ /** Name of the sendonly audio track to publish the mic to. Ignored unless
1046
+ * `audio` is set. */
1040
1047
  audioTrack?: string;
1041
1048
  className?: string;
1042
- style?: React.CSSProperties;
1049
+ style?: CSSProperties;
1050
+ /** Read once, at mount — changing this after mount doesn't re-request
1051
+ * `getUserMedia`. Matches v2. */
1043
1052
  videoConstraints?: MediaTrackConstraints;
1044
1053
  showWebcam?: boolean;
1045
- videoObjectFit?: NonNullable<React.VideoHTMLAttributes<HTMLVideoElement>["style"]>["objectFit"];
1046
- /**
1047
- * Fires once `getUserMedia` is rejected with `NotAllowedError`
1048
- * or `PermissionDeniedError`.
1049
- */
1054
+ videoObjectFit?: NonNullable<VideoHTMLAttributes<HTMLVideoElement>['style']>['objectFit'];
1055
+ /** Fires once `getUserMedia` is rejected with `NotAllowedError` or
1056
+ * `PermissionDeniedError`. */
1050
1057
  onPermissionDenied?: () => void;
1051
- /**
1052
- * Fires after the local media stream has been published (both
1053
- * video and audio when {@link audio} is enabled). Re-fires
1054
- * after a reconnect.
1055
- */
1058
+ /** Fires after the local media has been published (video, and audio when
1059
+ * `audio` is enabled). Re-fires after a reconnect. */
1056
1060
  onPublished?: () => void;
1057
- /**
1058
- * Fires on non-permission `getUserMedia` failures and on
1059
- * publish / unpublish rejections. Permission denials route to
1060
- * {@link onPermissionDenied} instead.
1061
- */
1061
+ /** Fires on non-permission `getUserMedia` failures and on publish/unpublish
1062
+ * rejections. Permission denials route to `onPermissionDenied` instead. */
1062
1063
  onError?: (error: Error) => void;
1063
1064
  }
1064
- declare function WebcamStream({ track, audio, audioTrack, className, style, videoConstraints, showWebcam, videoObjectFit, onPermissionDenied, onPublished, onError, }: WebcamStreamProps): react_jsx_runtime.JSX.Element;
1065
+ declare function WebcamStream({ track, audio, audioTrack, className, style, videoConstraints, showWebcam, videoObjectFit, onPermissionDenied, onPublished, onError, }: WebcamStreamProps): react.JSX.Element;
1065
1066
 
1066
1067
  /**
1067
- * Video preview for a captured {@link Clip}.
1068
+ * Video preview for a captured {@link Clip}. Streams the clip with `hls.js`
1069
+ * wherever Media Source Extensions exist — every current browser, iOS
1070
+ * Safari 17.1 and later included. `hls.js` is dynamically imported, so
1071
+ * bundlers give it a chunk of its own that an app importing this component
1072
+ * fetches on first play, and one that never renders a player drops
1073
+ * entirely. Where Media Source Extensions don't exist — iOS before 17.1 —
1074
+ * the clip is assembled into a single MP4 and played from memory instead.
1075
+ * Failures surface in an inline error overlay; the chunks remain
1076
+ * downloadable via {@link useClipDownload}/`ClipDownloadButton` either way.
1068
1077
  *
1069
- * Renders an HLS manifest through the browser's native
1070
- * ``<video controls>`` element. On Safari / iOS the manifest is
1071
- * attached directly (native HLS support). On Chrome / Firefox / Edge
1072
- * ``hls.js`` is dynamically imported — declared as an **optional peer
1073
- * dependency** so consumers who don't use this component aren't billed
1074
- * the ~80 KB. If ``hls.js`` isn't installed and native HLS isn't
1075
- * available the player surfaces an inline error overlay; the
1076
- * underlying chunks remain downloadable via {@link useClipDownload} /
1077
- * {@link ClipDownloadButton} (which don't depend on hls.js at all).
1078
+ * Preview only — this component doesn't render a download UI. Compose it
1079
+ * with `ClipDownloadButton`, or build a custom download surface around
1080
+ * `useClipDownload`.
1078
1081
  *
1079
- * **Preview only.** This component intentionally does *not* render a
1080
- * download UI. Compose it with {@link ClipDownloadButton} or build
1081
- * your own download surface around {@link useClipDownload} — the
1082
- * separation keeps both pieces independently extendible and avoids
1083
- * baking layout decisions into the SDK.
1084
- *
1085
- * Unlike {@link ReactorView} / {@link WebcamStream} this component
1086
- * **does not require a ``ReactorProvider``** in the tree. It
1087
- * operates on the ``Clip`` value alone, so it stays usable after
1088
- * ``reactor.disconnect()`` and works with clips loaded from
1089
- * fixtures, server logs, or any other source. When a
1090
- * ``ReactorProvider`` is mounted above, an omitted ``getJwt``
1091
- * inherits the provider's resolver.
1092
- *
1093
- * @example Compose with the download button (explicit `getJwt`):
1094
- * ```tsx
1095
- * <div>
1096
- * <ClipPlayer clip={clip} getJwt={() => jwt} />
1097
- * <ClipDownloadButton clip={clip} getJwt={() => jwt} />
1098
- * </div>
1099
- * ```
1100
- *
1101
- * @example Local dev (HttpRuntime, no auth on /clips):
1102
- * ```tsx
1103
- * <ClipPlayer clip={clip} />
1104
- * ```
1082
+ * Unlike `ReactorView`/`WebcamStream`, this doesn't require a
1083
+ * `ReactorProvider` in the tree — it operates on the `Clip` value alone, so
1084
+ * it stays usable after `reactor.disconnect()` and works with clips loaded
1085
+ * from fixtures or any other source. When a `ReactorProvider` is mounted
1086
+ * above, an omitted `getJwt` inherits the provider's resolver.
1105
1087
  */
1106
1088
  interface ClipPlayerProps {
1107
- /**
1108
- * The captured clip to play. When this prop changes by reference
1109
- * the player re-fetches the manifest and re-attaches the player.
1110
- */
1089
+ /** The captured clip to play. Re-fetches the manifest and re-attaches the
1090
+ * player when this changes by reference. */
1111
1091
  clip: Clip;
1112
1092
  /**
1113
- * Lazy resolver for the Coordinator JWT used on the ``/clips``
1114
- * manifest GET. Called at request time so token refreshes are
1115
- * picked up automatically.
1116
- *
1117
- * - **Production:** required outside a ``<ReactorProvider>``;
1118
- * optional inside one (inherits the provider's resolver).
1119
- * - **Local-dev (HttpRuntime):** omit — ``/clips`` is auth-free.
1093
+ * Lazy resolver for the Coordinator JWT used on the manifest GET, called
1094
+ * at request time so token refreshes are picked up automatically.
1120
1095
  *
1121
- * Chunk URLs inside the manifest are presigned (prod) or
1122
- * unauthenticated (local) and are fetched without
1123
- * ``Authorization`` in either case.
1096
+ * Required outside a `ReactorProvider` in production; optional inside one
1097
+ * (inherits the provider's resolver). Omit in local-dev mode (HttpRuntime)
1098
+ * — the manifest endpoint there is auth-free.
1124
1099
  */
1125
1100
  getJwt?: () => string | Promise<string>;
1126
1101
  /**
1127
- * Opt into a *bounded* wait: give up polling the ``/clips`` manifest
1128
- * endpoint with ``CLIP_NOT_READY`` once
1129
- * ``max(clip.predictedReadyAtMs, pollStart) + slackMs`` passes. By
1130
- * default this is **unset** — the player polls indefinitely until the
1131
- * clip is ready, and stops only when it unmounts or ``clip`` changes
1132
- * (both abort the in-flight poll). Set a value when you want a hard
1133
- * ceiling (e.g. ``120_000`` for a two-minute cap). Forwarded
1134
- * directly to {@link fetchPlaylist}'s ``slackMs`` option — see that
1135
- * helper for the polling semantics.
1102
+ * Opt into a bounded wait: give up polling the manifest with
1103
+ * `CLIP_NOT_READY` once `max(clip.predictedReadyAtMs, pollStart) + slackMs`
1104
+ * passes. Unset by default — the player polls indefinitely until the clip
1105
+ * is ready, stopping only when it unmounts or `clip` changes. Forwarded
1106
+ * directly to `fetchPlaylist()`'s `slackMs` option.
1136
1107
  */
1137
1108
  slackMs?: number;
1138
- /** Play automatically once the manifest is attached. Default ``true``. */
1109
+ /** Play automatically once the manifest is attached. Default `true`. */
1139
1110
  autoPlay?: boolean;
1140
- /**
1141
- * Start muted. Default ``true`` because browser autoplay policies
1142
- * block audio-bearing video from playing without a user gesture;
1143
- * the user can unmute via the native ``<video controls>``.
1144
- */
1111
+ /** Start muted. Default `true` — browser autoplay policies block
1112
+ * audio-bearing video from playing without a user gesture; the user can
1113
+ * unmute via the native controls. */
1145
1114
  muted?: boolean;
1146
1115
  className?: string;
1147
- style?: React.CSSProperties;
1148
- /**
1149
- * Fires when the player enters its inline error state. Receives
1150
- * the originating error: a ``RecordingError`` for manifest-fetch
1151
- * failures, a plain ``Error`` for hls.js / native playback or
1152
- * missing-peer-dep cases.
1153
- */
1116
+ style?: CSSProperties;
1117
+ /** Fires when the player enters its inline error state. A `RecordingError`
1118
+ * for manifest-fetch failures, a plain `Error` for hls.js/element playback
1119
+ * failures. */
1154
1120
  onError?: (error: Error) => void;
1155
1121
  }
1156
- declare function ClipPlayer({ clip, getJwt, slackMs, autoPlay, muted, className, style, onError, }: ClipPlayerProps): react_jsx_runtime.JSX.Element;
1122
+ declare function ClipPlayer({ clip, getJwt, slackMs, autoPlay, muted, className, style, onError, }: ClipPlayerProps): react.JSX.Element;
1157
1123
 
1158
1124
  /**
1159
1125
  * State machine for an in-progress clip download.
1160
1126
  *
1161
- * - ``idle``: no download in flight (initial state, and what the hook
1162
- * returns to after a successful save).
1163
- * - ``downloading``: chunks are being fetched. ``fetched`` and
1164
- * ``total`` count the number of chunks (init segment + media
1165
- * segments) — useful for a progress bar. ``total`` is 0 until the
1166
- * manifest is parsed and the chunk count is known.
1167
- * - ``error``: most recent attempt failed; the ``message`` is suitable
1168
- * for surfacing inline. ``RecordingError`` instances are formatted
1169
- * as ``"<CODE>: <reason>"`` for grep-ability.
1127
+ * - `idle`: no download in flight (initial state, and what the hook returns
1128
+ * to after a successful save).
1129
+ * - `downloading`: chunks are being fetched. `fetched`/`total` count the
1130
+ * chunks (init segment + media segments) — useful for a progress bar.
1131
+ * `total` is 0 until the manifest is parsed and the chunk count is known.
1132
+ * - `error`: most recent attempt failed; `message` is suitable for
1133
+ * surfacing inline. `RecordingError`s are formatted as `"<CODE>: <reason>"`.
1170
1134
  */
1171
1135
  type ClipDownloadState = {
1172
- kind: "idle";
1136
+ kind: 'idle';
1173
1137
  } | {
1174
- kind: "downloading";
1138
+ kind: 'downloading';
1175
1139
  fetched: number;
1176
1140
  total: number;
1177
1141
  } | {
1178
- kind: "error";
1142
+ kind: 'error';
1179
1143
  message: string;
1180
1144
  };
1181
1145
  interface UseClipDownloadOptions {
1182
- /**
1183
- * Filename used when the browser save dialog opens. Pass ``null``
1184
- * to skip the ``<a download>`` trigger entirely — the returned
1185
- * Blob is still resolved so the caller can ``URL.createObjectURL``
1186
- * it or re-upload it. Default ``"reactor-clip.mp4"``.
1187
- */
1146
+ /** Filename used when the browser save dialog opens. Pass `null` to skip
1147
+ * the `<a download>` trigger entirely — the returned Blob is still
1148
+ * resolved so the caller can `URL.createObjectURL` it or re-upload it.
1149
+ * Default `"reactor-clip.mp4"`. */
1188
1150
  filename?: string | null;
1189
1151
  /**
1190
- * Lazy resolver for the Coordinator JWT used on the ``/clips``
1191
- * manifest GET. Called on every {@link download} invocation, so
1192
- * token refreshes are picked up automatically.
1152
+ * Lazy resolver for the Coordinator JWT used on the manifest GET. Called
1153
+ * on every {@link UseClipDownloadResult.download} invocation, so token
1154
+ * refreshes are picked up automatically.
1193
1155
  *
1194
- * Optional inside a ``<ReactorProvider>`` (inherits the provider's
1195
- * resolver) and in local-dev mode. See
1196
- * {@link ClipPlayerProps.getJwt}.
1156
+ * Optional inside a `ReactorProvider` (inherits the provider's resolver)
1157
+ * and in local-dev mode.
1197
1158
  */
1198
1159
  getJwt?: () => string | Promise<string>;
1199
1160
  }
@@ -1201,158 +1162,73 @@ interface UseClipDownloadResult {
1201
1162
  /** Current state of the most recent download attempt. */
1202
1163
  state: ClipDownloadState;
1203
1164
  /**
1204
- * Trigger a download. Resolves with the assembled fragmented-MP4
1205
- * Blob, or ``undefined`` if a download was already in flight (the
1206
- * call is a no-op in that case — guarding against double-click is
1207
- * the hook's responsibility, not the caller's).
1208
- *
1209
- * Errors are caught and surfaced via {@link state} — the returned
1210
- * Promise still resolves to ``undefined`` rather than rejecting,
1211
- * because the typical caller is a click handler that doesn't await.
1212
- * Use ``state.kind === "error"`` to drive failure UI.
1165
+ * Trigger a download. Resolves with the assembled fragmented-MP4 Blob, or
1166
+ * `undefined` if a download was already in flight (a no-op in that case)
1167
+ * or the attempt failed. Errors are surfaced via {@link state} rather than
1168
+ * a rejection — check `state.kind === "error"` to drive failure UI.
1213
1169
  */
1214
1170
  download: () => Promise<Blob | undefined>;
1215
- /** Reset to ``idle``. Does *not* cancel an in-flight download. */
1171
+ /** Reset to `idle`. Does *not* cancel an in-flight download. */
1216
1172
  reset: () => void;
1217
1173
  }
1218
1174
  /**
1219
- * Headless download primitive for a {@link Clip}.
1220
- *
1221
- * Wraps {@link downloadClipAsFile} in a React state machine so the
1222
- * consumer can render any button they want, anywhere they want, and
1223
- * still get progress + error feedback. Used internally by
1224
- * {@link ClipPlayer}'s built-in download button — when you need
1225
- * custom placement or styling, set ``showDownloadButton={false}`` on
1226
- * the player and call this hook directly.
1175
+ * Headless download primitive for a {@link Clip}. Wraps `downloadClipAsFile`
1176
+ * in a React state machine so the consumer can render any button they want,
1177
+ * anywhere they want, and still get progress + error feedback. Used
1178
+ * internally by `ClipDownloadButton` — reach for this hook directly when you
1179
+ * need custom placement or styling.
1227
1180
  *
1228
- * Stable callback identity: ``download`` and ``reset`` are the same
1229
- * function reference across renders, so they're safe to pass through
1230
- * memoized children without forcing re-renders.
1231
- *
1232
- * @example Render a download button anywhere in your tree:
1233
- * ```tsx
1234
- * function ClipCard({ clip }: { clip: Clip }) {
1235
- * const jwt = useReactor((s) => s.jwtToken);
1236
- * const { state, download } = useClipDownload(clip, {
1237
- * filename: `snap-${clip.sessionId}.mp4`,
1238
- * getJwt: jwt ? () => jwt : undefined,
1239
- * });
1240
- * return (
1241
- * <button onClick={download} disabled={state.kind === "downloading"}>
1242
- * {state.kind === "downloading"
1243
- * ? `${state.fetched}/${state.total}`
1244
- * : state.kind === "error"
1245
- * ? "Retry"
1246
- * : "Download"}
1247
- * </button>
1248
- * );
1249
- * }
1250
- * ```
1181
+ * `download`/`reset` are stable callback identities across renders, so
1182
+ * they're safe to pass through memoized children without forcing re-renders.
1251
1183
  */
1252
1184
  declare function useClipDownload(clip: Clip, options?: UseClipDownloadOptions): UseClipDownloadResult;
1253
1185
 
1254
1186
  /**
1255
- * Standalone download button for a captured {@link Clip}.
1256
- *
1257
- * Drops anywhere in your UI — modal headers, list rows, hover menus,
1258
- * floating action buttons — and is responsible for nothing more than
1259
- * triggering a download and reflecting its state. Internally wraps
1260
- * {@link useClipDownload}; for completely custom UIs (progress bars,
1261
- * menu items, post-download blob handling) call that hook directly.
1187
+ * Standalone download button for a captured {@link Clip}. Drops anywhere in
1188
+ * your UI — modal headers, list rows, hover menus, floating action buttons
1189
+ * — and is responsible for nothing more than triggering a download and
1190
+ * reflecting its state. Wraps `useClipDownload` internally; for completely
1191
+ * custom UIs (progress bars, menu items, post-download blob handling) call
1192
+ * that hook directly.
1262
1193
  *
1263
- * Styling is intentionally minimal. Override via ``className``,
1264
- * ``style``, or replace the inner content with the ``children``
1265
- * render-prop. No CSS file is shipped — every default style is
1266
- * inline so it loses to anything the consumer provides.
1267
- *
1268
- * @example Default label, state-aware:
1269
- * ```tsx
1270
- * <ClipDownloadButton clip={clip} getJwt={() => jwt} />
1271
- * ```
1272
- *
1273
- * @example Custom label that follows the state:
1274
- * ```tsx
1275
- * <ClipDownloadButton clip={clip} getJwt={() => jwt}>
1276
- * {(s) => (s.kind === "downloading" ? `${s.fetched}/${s.total}` : "Save MP4")}
1277
- * </ClipDownloadButton>
1278
- * ```
1279
- *
1280
- * @example Static label:
1281
- * ```tsx
1282
- * <ClipDownloadButton clip={clip} getJwt={() => jwt}>Save</ClipDownloadButton>
1283
- * ```
1194
+ * Styling is intentionally minimal — override via `className`/`style`, or
1195
+ * replace the inner content with the `children` render-prop. No CSS file is
1196
+ * shipped; every default style is inline so it loses to anything the
1197
+ * consumer provides.
1284
1198
  */
1285
1199
  interface ClipDownloadButtonProps {
1286
1200
  /** The clip to download. */
1287
1201
  clip: Clip;
1288
- /**
1289
- * Lazy JWT resolver. Optional inside a ``<ReactorProvider>``
1290
- * (inherits the provider's resolver) and in local-dev mode. See
1291
- * {@link ClipPlayerProps.getJwt}.
1292
- */
1202
+ /** Lazy JWT resolver. Optional inside a `ReactorProvider` (inherits the
1203
+ * provider's resolver) and in local-dev mode. See `ClipPlayerProps.getJwt`. */
1293
1204
  getJwt?: () => string | Promise<string>;
1294
- /** Filename for the saved MP4. Default ``"reactor-clip.mp4"``. */
1205
+ /** Filename for the saved MP4. Default `"reactor-clip.mp4"`. */
1295
1206
  filename?: string;
1296
1207
  /**
1297
- * Inner content of the button. Three forms:
1208
+ * Inner content of the button. Three forms:
1298
1209
  *
1299
- * - **Omitted** — renders a sensible default label that follows
1300
- * the state (``"Download"`` / ``"Downloading 3/8…"`` / etc.).
1301
- * - **`ReactNode`** — static label. No state-driven text.
1302
- * - **`(state) => ReactNode`** — state-aware render function;
1303
- * use for custom progress strings, spinners, etc.
1304
- */
1305
- children?: React.ReactNode | ((state: ClipDownloadState) => React.ReactNode);
1306
- /** Forwarded to the underlying ``<button>``. */
1210
+ * - Omitted — renders a default label that follows the state
1211
+ * (`"Download"` / `"Downloading 3/8…"` / etc.).
1212
+ * - `ReactNode` — static label, no state-driven text.
1213
+ * - `(state) => ReactNode` — state-aware render function, for custom
1214
+ * progress strings, spinners, etc.
1215
+ */
1216
+ children?: ReactNode | ((state: ClipDownloadState) => ReactNode);
1217
+ /** Forwarded to the underlying `<button>`. */
1307
1218
  className?: string;
1308
- /** Forwarded to the underlying ``<button>`` — merges *after* the defaults so each property overrides. */
1309
- style?: React.CSSProperties;
1310
- /** Forwarded to the underlying ``<button>``. ORed with the internal "downloading" state. */
1219
+ /** Forwarded to the underlying `<button>` — merges after the defaults so
1220
+ * each property overrides. */
1221
+ style?: CSSProperties;
1222
+ /** Forwarded to the underlying `<button>`. ORed with the internal
1223
+ * "downloading" state. */
1311
1224
  disabled?: boolean;
1312
- /**
1313
- * Fires when the download completes with the assembled MP4 ``Blob``.
1314
- */
1225
+ /** Fires when the download completes with the assembled MP4 Blob. */
1315
1226
  onSuccess?: (blob: Blob) => void;
1316
- /**
1317
- * Fires when the download fails. Message mirrors the in-button
1318
- * state — ``"<CODE>: <reason>"`` for ``RecordingError``s, the
1319
- * plain error message otherwise.
1320
- */
1227
+ /** Fires when the download fails. Message mirrors the in-button state —
1228
+ * `"<CODE>: <reason>"` for `RecordingError`s, the plain error message
1229
+ * otherwise. */
1321
1230
  onError?: (error: Error) => void;
1322
1231
  }
1323
- declare function ClipDownloadButton({ clip, getJwt, filename, children, className, style, disabled, onSuccess, onError, }: ClipDownloadButtonProps): react_jsx_runtime.JSX.Element;
1324
-
1325
- /**
1326
- * Generic hook for accessing selected parts of the Reactor store.
1327
- *
1328
- * @param selector - A function that selects part of the store state.
1329
- * @returns The selected slice from the store.
1330
- */
1331
- declare function useReactor<T>(selector: (state: ReactorStore) => T): T;
1332
- /**
1333
- * Hook for receiving model application messages.
1334
- *
1335
- * Only fires for messages sent by the model via `get_ctx().send()`.
1336
- * Internal platform-level messages (e.g. capabilities) are NOT delivered here.
1337
- *
1338
- * @param handler - Callback invoked with each application message payload.
1339
- */
1340
- declare function useReactorMessage(handler: (message: any) => void): void;
1341
- /**
1342
- * Hook for receiving internal platform-level (runtime) messages.
1343
- *
1344
- * This is intended for advanced use cases that need access to the runtime
1345
- * control layer, such as capabilities negotiation. Model application messages
1346
- * sent via `get_ctx().send()` are NOT delivered through this hook — use
1347
- * {@link useReactorMessage} for those.
1348
- *
1349
- * @param handler - Callback invoked with each runtime message payload.
1350
- */
1351
- declare function useReactorInternalMessage(handler: (message: any) => void): void;
1352
- /**
1353
- * Hook that returns the current connection stats (RTT, etc.).
1354
- * Updates every ~2s while connected. Returns undefined when disconnected.
1355
- */
1356
- declare function useStats(): ConnectionStats | undefined;
1232
+ declare function ClipDownloadButton({ clip, getJwt, filename, children, className, style, disabled, onSuccess, onError, }: ClipDownloadButtonProps): react.JSX.Element;
1357
1233
 
1358
- export { AbortError, type Capabilities, type Clip, ClipDownloadButton, type ClipDownloadButtonProps, type ClipDownloadState, type ClipFailedPayload, type ClipKind, ClipPlayer, type ClipPlayerProps, type ClipReadyPayload, type CommandCapability, ConflictError, type ConnectOptions, type ConnectionStats, type ConnectionTimings, DEFAULT_BASE_URL, DEFAULT_CLIP_REQUEST_TIMEOUT_MS, DEFAULT_PLAYLIST_POLL_SLACK_MS, type DownloadClipOptions, type FetchPlaylistOptions, FileRef, type JwtResolver, type JwtSource, type MessageScope, type ModelSchema, type ModelSchemaOperation, type ModelSchemaPathItem, type ModerationAction, type ModerationEvent, type Options, type ParseClipOptions, Reactor, type ReactorConnectOptions, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, type ReactorStore, ReactorView, type ReactorViewProps, RecordingClient, type RecordingClientHost, RecordingError, RuntimeRecordingMessageType, SessionLostError, type SessionResponse, type TrackCapability, type UseClipDownloadOptions, type UseClipDownloadResult, WebcamStream, type WebcamStreamProps, clipFromPayload, createPlayableManifestUrl, downloadClipAsFile, fetchPlaylist, isAbortError, isSessionLostError, normalizeJwtSource, parsePlaylist, rewriteUrlHost, useClipDownload, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats };
1234
+ export { AbortedError, BadRequestError, type Capabilities, type Clip, ClipDownloadButton, type ClipDownloadButtonProps, type ClipDownloadState, type ClipKind, ClipPlayer, type ClipPlayerProps, type CommandCapability, ConflictError, type ConnectOptions, type ConnectionStats, type ConnectionTimings, DEFAULT_PLAYLIST_POLL_SLACK_MS, DecodeError, DisconnectedError, type DownloadClipOptions, type FetchPlaylistOptions, FileRef, InvalidStateError, type JwtResolver, type JwtSource, type MessageScope, MessageTooLargeError, type ModelSchema, type ModelSchemaOperation, type ModelSchemaPathItem, type ModerationAction, type ModerationEvent, NetworkError, NotFoundError, RateLimitedError, Reactor, type ReactorActions, type ReactorConnectOptions, ReactorError, type ReactorEventMap, type ReactorEventName, type ReactorMessage, type ReactorOptions, ReactorProvider, type ReactorProviderProps, type ReactorState, type ReactorStatus, type ReactorStore, ReactorView, type ReactorViewProps, RecorderDisabledError, RecordingError, RequestTimeoutError, ServerError, type SessionResponse, SessionTerminalError, type TrackCapability, type TrackDirection, type TrackKind, type TrackMappingEntry, TransportError, UnauthorizedError, type UseClipDownloadOptions, type UseClipDownloadResult, VersionMismatchError, WebcamStream, type WebcamStreamProps, createPlayableManifestUrl, downloadClipAsFile, fetchPlaylist, isFileRef, normalizeJwtSource, parsePlaylist, useClipDownload, useReactor, useReactorInternalMessage, useReactorMessage, useStats };