@reactor-team/js-sdk 2.3.2 → 2.5.0

package/dist/index.d.mts

@@ -9,6 +9,81 @@ type ReactorStatus = "disconnected" | "connecting" | "waiting" | "ready";
  * - "runtime": platform-level control messages (e.g., capabilities exchange).
  */
 type MessageScope = "application" | "runtime";
+/**
+ * Describes a single named media track for SDP negotiation.
+ *
+ * Track names must exactly match the class attribute names defined on the
+ * model's Python code.  The name is encoded as the SDP MID so both sides
+ * can route media by name rather than by positional index.
+ *
+ * Use the {@link video} and {@link audio} helper functions to create
+ * instances instead of constructing this interface directly.
+ */
+interface TrackConfig {
+    name: string;
+    kind: "audio" | "video";
+}
+/**
+ * Optional configuration for a video track (reserved for future use).
+ */
+interface VideoTrackOptions {
+    /** Maximum framerate constraint for the video track. */
+    maxFramerate?: number;
+}
+/**
+ * Optional configuration for an audio track (reserved for future use).
+ */
+interface AudioTrackOptions {
+    /** Sample rate constraint for the audio track. */
+    sampleRate?: number;
+}
+/**
+ * Creates a **video** {@link TrackConfig}.
+ *
+ * A track declared in the **`receive`** array means the client will
+ * **RECEIVE** video frames **from the model** (model → client).
+ *
+ * A track declared in the **`send`** array means the client will
+ * **SEND** video frames **to the model** (client → model).
+ *
+ * Track names must be unique across both arrays — the same name cannot
+ * appear in `receive` and `send`.
+ *
+ * @param name    - The track name.  Must match the model's declared track attribute name.
+ * @param options - Reserved for future constraints (e.g. `maxFramerate`).
+ *
+ * When no `receive` array is provided to the Reactor constructor, a single
+ * `video("main_video")` track is used by default.
+ *
+ * @example
+ * ```ts
+ * receive: [video("main_video")]          // receive video from the model
+ * send:    [video("webcam")]              // send webcam video to the model
+ * ```
+ */
+declare function video(name: string, _options?: VideoTrackOptions): TrackConfig;
+/**
+ * Creates an **audio** {@link TrackConfig}.
+ *
+ * A track declared in the **`receive`** array means the client will
+ * **RECEIVE** audio samples **from the model** (model → client).
+ *
+ * A track declared in the **`send`** array means the client will
+ * **SEND** audio samples **to the model** (client → model).
+ *
+ * Track names must be unique across both arrays — the same name cannot
+ * appear in `receive` and `send`.
+ *
+ * @param name    - The track name.  Must match the model's declared track attribute name.
+ * @param options - Reserved for future constraints (e.g. `sampleRate`).
+ *
+ * @example
+ * ```ts
+ * receive: [audio("main_audio")]          // receive audio from the model
+ * send:    [audio("mic")]                 // send microphone audio to the model
+ * ```
+ */
+declare function audio(name: string, _options?: AudioTrackOptions): TrackConfig;
 interface ReactorError {
     code: string;
     message: string;
@@ -31,13 +106,42 @@ interface ConnectOptions {
     /** Maximum number of SDP polling attempts before giving up. Default: 6. */
     maxAttempts?: number;
 }
-type ReactorEvent = "statusChanged" | "sessionIdChanged" | "newMessage" | "streamChanged" | "error" | "sessionExpirationChanged";
+interface ConnectionStats {
+    /** ICE candidate-pair round-trip time in milliseconds */
+    rtt?: number;
+    /** ICE candidate type: "host", "srflx", "prflx", or "relay" (TURN) */
+    candidateType?: string;
+    /** Estimated available outgoing bitrate in bits/second */
+    availableOutgoingBitrate?: number;
+    /** Received video frames per second */
+    framesPerSecond?: number;
+    /** Ratio of packets lost (0-1) */
+    packetLossRatio?: number;
+    /** Network jitter in seconds (from inbound-rtp) */
+    jitter?: number;
+    timestamp: number;
+}
+type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "trackReceived" | "error" | "sessionExpirationChanged" | "statsUpdate";
 
 declare const PROD_COORDINATOR_URL = "https://api.reactor.inc";
 declare const OptionsSchema: z.ZodObject<{
     coordinatorUrl: z.ZodDefault<z.ZodString>;
     modelName: z.ZodString;
     local: z.ZodDefault<z.ZodBoolean>;
+    receive: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            audio: "audio";
+            video: "video";
+        }>;
+    }, z.core.$strip>>>;
+    send: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            audio: "audio";
+            video: "video";
+        }>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 type Options = z.input<typeof OptionsSchema>;
 type EventHandler = (...args: any[]) => void;
@@ -50,6 +154,10 @@ declare class Reactor {
     private model;
     private sessionExpiration?;
     private local;
+    /** Tracks the client RECEIVES from the model (model → client). */
+    private receive;
+    /** Tracks the client SENDS to the model (client → model). */
+    private send;
     private sessionId?;
     constructor(options: Options);
     private eventListeners;
@@ -57,24 +165,26 @@ declare class Reactor {
     off(event: ReactorEvent, handler: EventHandler): void;
     emit(event: ReactorEvent, ...args: any[]): void;
     /**
-     * Public method to send a message to the machine.
-     * Wraps the message in the specified channel envelope (defaults to "application").
-     * @param command The command name to send.
+     * Sends a command to the model via the data channel.
+     *
+     * @param command The command name.
      * @param data The command payload.
-     * @param scope The envelope scope – "application" (default) for model commands,
-     *              "runtime" for platform-level messages (e.g. requestCapabilities).
-     * @throws Error if not in ready state
+     * @param scope "application" (default) for model commands, "runtime" for platform messages.
      */
     sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
     /**
-     * Public method to publish a track to the machine.
-     * @param track The track to send to the machine.
+     * Publishes a MediaStreamTrack to a named send track.
+     *
+     * @param name The declared send track name (e.g. "webcam").
+     * @param track The MediaStreamTrack to publish.
      */
-    publishTrack(track: MediaStreamTrack): Promise<void>;
+    publishTrack(name: string, track: MediaStreamTrack): Promise<void>;
     /**
-     * Public method to unpublish the currently published track.
+     * Unpublishes the track with the given name.
+     *
+     * @param name The declared send track name to unpublish.
      */
-    unpublishTrack(): Promise<void>;
+    unpublishTrack(name: string): Promise<void>;
     /**
      * Public method for reconnecting to an existing session, that may have been interrupted but can be recovered.
      * @param options Optional connect options (e.g. maxAttempts for SDP polling)
@@ -114,6 +224,7 @@ declare class Reactor {
      * Get the last error that occurred
      */
     getLastError(): ReactorError | undefined;
+    getStats(): ConnectionStats | undefined;
     /**
      * Create and store an error
      */
@@ -122,19 +233,24 @@ declare class Reactor {
 
 interface ReactorState {
     status: ReactorStatus;
-    videoTrack: MediaStreamTrack | null;
+    /**
+     * Media tracks received from the model, keyed by track name.
+     *
+     * Each entry maps a declared **receive** track name (e.g. `"main_video"`,
+     * `"main_audio"`) to the live `MediaStreamTrack` delivered by the model.
+     */
+    tracks: Record<string, MediaStreamTrack>;
     lastError?: ReactorError;
     sessionId?: string;
     sessionExpiration?: number;
-    insecureApiKey?: string;
     jwtToken?: string;
 }
 interface ReactorActions {
     sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
     connect(jwtToken?: string, options?: ConnectOptions): Promise<void>;
     disconnect(recoverable?: boolean): Promise<void>;
-    publishVideoStream(stream: MediaStream): Promise<void>;
-    unpublishVideoStream(): Promise<void>;
+    publish(name: string, track: MediaStreamTrack): Promise<void>;
+    unpublish(name: string): Promise<void>;
     reconnect(options?: ConnectOptions): Promise<void>;
 }
 interface ReactorInternalState {
@@ -164,13 +280,26 @@ declare function ReactorProvider({ children, connectOptions, jwtToken, ...props
 declare function useReactorStore<T = ReactorStore>(selector: (state: ReactorStore) => T): T;
 
 interface ReactorViewProps {
+    /**
+     * The name of the **receive** track to render.
+     * Must match a track name declared in the `receive` array (model → client).
+     * Defaults to `"main_video"`.
+     */
+    track?: string;
+    /**
+     * Optional name of a **receive** audio track to play alongside the video
+     * (e.g. `"main_audio"`).  The audio is mixed into the same `<video>` element.
+     */
+    audioTrack?: string;
     width?: number;
     height?: number;
     className?: string;
     style?: React.CSSProperties;
     videoObjectFit?: NonNullable<React.VideoHTMLAttributes<HTMLVideoElement>["style"]>["objectFit"];
+    /** Controls whether inbound audio plays. Default true (muted) to satisfy browser autoplay policies. */
+    muted?: boolean;
 }
-declare function ReactorView({ width, height, className, style, videoObjectFit, }: ReactorViewProps): react_jsx_runtime.JSX.Element;
+declare function ReactorView({ track, audioTrack, width, height, className, style, videoObjectFit, muted, }: ReactorViewProps): react_jsx_runtime.JSX.Element;
 
 interface ReactorControllerProps {
     className?: string;
@@ -178,14 +307,19 @@ interface ReactorControllerProps {
 }
 declare function ReactorController({ className, style, }: ReactorControllerProps): react_jsx_runtime.JSX.Element;
 
-interface Props {
+interface WebcamStreamProps {
+    /**
+     * The name of the **send** track to publish the webcam to.
+     * Must match a track name declared in the `send` array (client → model).
+     */
+    track: string;
     className?: string;
     style?: React.CSSProperties;
     videoConstraints?: MediaTrackConstraints;
     showWebcam?: boolean;
     videoObjectFit?: NonNullable<React.VideoHTMLAttributes<HTMLVideoElement>["style"]>["objectFit"];
 }
-declare function WebcamStream({ className, style, videoConstraints, showWebcam, videoObjectFit, }: Props): react_jsx_runtime.JSX.Element;
+declare function WebcamStream({ track, className, style, videoConstraints, showWebcam, videoObjectFit, }: WebcamStreamProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Generic hook for accessing selected parts of the Reactor store.
@@ -195,15 +329,30 @@ declare function WebcamStream({ className, style, videoConstraints, showWebcam,
  */
 declare function useReactor<T>(selector: (state: ReactorStore) => T): T;
 /**
- * Hook for handling message subscriptions with proper React lifecycle management.
+ * Hook for receiving model application messages.
+ *
+ * Only fires for messages sent by the model via `get_ctx().send()`.
+ * Internal platform-level messages (e.g. capabilities) are NOT delivered here.
+ *
+ * @param handler - Callback invoked with each application message payload.
+ */
+declare function useReactorMessage(handler: (message: any) => void): void;
+/**
+ * Hook for receiving internal platform-level (runtime) messages.
  *
- * The handler receives the message payload and the scope it arrived on:
- *   - "application" for model-defined messages (via get_ctx().send())
- *   - "runtime" for platform-level messages (e.g., capabilities response)
+ * This is intended for advanced use cases that need access to the runtime
+ * control layer, such as capabilities negotiation. Model application messages
+ * sent via `get_ctx().send()` are NOT delivered through this hook — use
+ * {@link useReactorMessage} for those.
  *
- * @param handler - The message handler function (message, scope)
+ * @param handler - Callback invoked with each runtime message payload.
+ */
+declare function useReactorInternalMessage(handler: (message: any) => void): void;
+/**
+ * Hook that returns the current connection stats (RTT, etc.).
+ * Updates every ~2s while connected. Returns undefined when disconnected.
  */
-declare function useReactorMessage(handler: (message: any, scope: MessageScope) => void): void;
+declare function useStats(): ConnectionStats | undefined;
 
 /**
  * ⚠️ INSECURE: Fetches a JWT token directly from the client.
@@ -218,4 +367,4 @@ declare function useReactorMessage(handler: (message: any, scope: MessageScope)
  */
 declare function fetchInsecureJwtToken(apiKey: string, coordinatorUrl?: string): Promise<string>;
 
-export { ConflictError, type ConnectOptions, type MessageScope, type Options, PROD_COORDINATOR_URL, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, ReactorView, type ReactorViewProps, WebcamStream, fetchInsecureJwtToken, useReactor, useReactorMessage, useReactorStore };
+export { type AudioTrackOptions, ConflictError, type ConnectOptions, type ConnectionStats, type MessageScope, type Options, PROD_COORDINATOR_URL, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, ReactorView, type ReactorViewProps, type TrackConfig, type VideoTrackOptions, WebcamStream, type WebcamStreamProps, audio, fetchInsecureJwtToken, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats, video };

package/dist/index.d.ts

@@ -9,6 +9,81 @@ type ReactorStatus = "disconnected" | "connecting" | "waiting" | "ready";
  * - "runtime": platform-level control messages (e.g., capabilities exchange).
  */
 type MessageScope = "application" | "runtime";
+/**
+ * Describes a single named media track for SDP negotiation.
+ *
+ * Track names must exactly match the class attribute names defined on the
+ * model's Python code.  The name is encoded as the SDP MID so both sides
+ * can route media by name rather than by positional index.
+ *
+ * Use the {@link video} and {@link audio} helper functions to create
+ * instances instead of constructing this interface directly.
+ */
+interface TrackConfig {
+    name: string;
+    kind: "audio" | "video";
+}
+/**
+ * Optional configuration for a video track (reserved for future use).
+ */
+interface VideoTrackOptions {
+    /** Maximum framerate constraint for the video track. */
+    maxFramerate?: number;
+}
+/**
+ * Optional configuration for an audio track (reserved for future use).
+ */
+interface AudioTrackOptions {
+    /** Sample rate constraint for the audio track. */
+    sampleRate?: number;
+}
+/**
+ * Creates a **video** {@link TrackConfig}.
+ *
+ * A track declared in the **`receive`** array means the client will
+ * **RECEIVE** video frames **from the model** (model → client).
+ *
+ * A track declared in the **`send`** array means the client will
+ * **SEND** video frames **to the model** (client → model).
+ *
+ * Track names must be unique across both arrays — the same name cannot
+ * appear in `receive` and `send`.
+ *
+ * @param name    - The track name.  Must match the model's declared track attribute name.
+ * @param options - Reserved for future constraints (e.g. `maxFramerate`).
+ *
+ * When no `receive` array is provided to the Reactor constructor, a single
+ * `video("main_video")` track is used by default.
+ *
+ * @example
+ * ```ts
+ * receive: [video("main_video")]          // receive video from the model
+ * send:    [video("webcam")]              // send webcam video to the model
+ * ```
+ */
+declare function video(name: string, _options?: VideoTrackOptions): TrackConfig;
+/**
+ * Creates an **audio** {@link TrackConfig}.
+ *
+ * A track declared in the **`receive`** array means the client will
+ * **RECEIVE** audio samples **from the model** (model → client).
+ *
+ * A track declared in the **`send`** array means the client will
+ * **SEND** audio samples **to the model** (client → model).
+ *
+ * Track names must be unique across both arrays — the same name cannot
+ * appear in `receive` and `send`.
+ *
+ * @param name    - The track name.  Must match the model's declared track attribute name.
+ * @param options - Reserved for future constraints (e.g. `sampleRate`).
+ *
+ * @example
+ * ```ts
+ * receive: [audio("main_audio")]          // receive audio from the model
+ * send:    [audio("mic")]                 // send microphone audio to the model
+ * ```
+ */
+declare function audio(name: string, _options?: AudioTrackOptions): TrackConfig;
 interface ReactorError {
     code: string;
     message: string;
@@ -31,13 +106,42 @@ interface ConnectOptions {
     /** Maximum number of SDP polling attempts before giving up. Default: 6. */
     maxAttempts?: number;
 }
-type ReactorEvent = "statusChanged" | "sessionIdChanged" | "newMessage" | "streamChanged" | "error" | "sessionExpirationChanged";
+interface ConnectionStats {
+    /** ICE candidate-pair round-trip time in milliseconds */
+    rtt?: number;
+    /** ICE candidate type: "host", "srflx", "prflx", or "relay" (TURN) */
+    candidateType?: string;
+    /** Estimated available outgoing bitrate in bits/second */
+    availableOutgoingBitrate?: number;
+    /** Received video frames per second */
+    framesPerSecond?: number;
+    /** Ratio of packets lost (0-1) */
+    packetLossRatio?: number;
+    /** Network jitter in seconds (from inbound-rtp) */
+    jitter?: number;
+    timestamp: number;
+}
+type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "trackReceived" | "error" | "sessionExpirationChanged" | "statsUpdate";
 
 declare const PROD_COORDINATOR_URL = "https://api.reactor.inc";
 declare const OptionsSchema: z.ZodObject<{
     coordinatorUrl: z.ZodDefault<z.ZodString>;
     modelName: z.ZodString;
     local: z.ZodDefault<z.ZodBoolean>;
+    receive: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            audio: "audio";
+            video: "video";
+        }>;
+    }, z.core.$strip>>>;
+    send: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            audio: "audio";
+            video: "video";
+        }>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 type Options = z.input<typeof OptionsSchema>;
 type EventHandler = (...args: any[]) => void;
@@ -50,6 +154,10 @@ declare class Reactor {
     private model;
     private sessionExpiration?;
     private local;
+    /** Tracks the client RECEIVES from the model (model → client). */
+    private receive;
+    /** Tracks the client SENDS to the model (client → model). */
+    private send;
     private sessionId?;
     constructor(options: Options);
     private eventListeners;
@@ -57,24 +165,26 @@ declare class Reactor {
     off(event: ReactorEvent, handler: EventHandler): void;
     emit(event: ReactorEvent, ...args: any[]): void;
     /**
-     * Public method to send a message to the machine.
-     * Wraps the message in the specified channel envelope (defaults to "application").
-     * @param command The command name to send.
+     * Sends a command to the model via the data channel.
+     *
+     * @param command The command name.
      * @param data The command payload.
-     * @param scope The envelope scope – "application" (default) for model commands,
-     *              "runtime" for platform-level messages (e.g. requestCapabilities).
-     * @throws Error if not in ready state
+     * @param scope "application" (default) for model commands, "runtime" for platform messages.
      */
     sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
     /**
-     * Public method to publish a track to the machine.
-     * @param track The track to send to the machine.
+     * Publishes a MediaStreamTrack to a named send track.
+     *
+     * @param name The declared send track name (e.g. "webcam").
+     * @param track The MediaStreamTrack to publish.
      */
-    publishTrack(track: MediaStreamTrack): Promise<void>;
+    publishTrack(name: string, track: MediaStreamTrack): Promise<void>;
     /**
-     * Public method to unpublish the currently published track.
+     * Unpublishes the track with the given name.
+     *
+     * @param name The declared send track name to unpublish.
      */
-    unpublishTrack(): Promise<void>;
+    unpublishTrack(name: string): Promise<void>;
     /**
      * Public method for reconnecting to an existing session, that may have been interrupted but can be recovered.
      * @param options Optional connect options (e.g. maxAttempts for SDP polling)
@@ -114,6 +224,7 @@ declare class Reactor {
      * Get the last error that occurred
      */
     getLastError(): ReactorError | undefined;
+    getStats(): ConnectionStats | undefined;
     /**
      * Create and store an error
      */
@@ -122,19 +233,24 @@ declare class Reactor {
 
 interface ReactorState {
     status: ReactorStatus;
-    videoTrack: MediaStreamTrack | null;
+    /**
+     * Media tracks received from the model, keyed by track name.
+     *
+     * Each entry maps a declared **receive** track name (e.g. `"main_video"`,
+     * `"main_audio"`) to the live `MediaStreamTrack` delivered by the model.
+     */
+    tracks: Record<string, MediaStreamTrack>;
     lastError?: ReactorError;
     sessionId?: string;
     sessionExpiration?: number;
-    insecureApiKey?: string;
     jwtToken?: string;
 }
 interface ReactorActions {
     sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
     connect(jwtToken?: string, options?: ConnectOptions): Promise<void>;
     disconnect(recoverable?: boolean): Promise<void>;
-    publishVideoStream(stream: MediaStream): Promise<void>;
-    unpublishVideoStream(): Promise<void>;
+    publish(name: string, track: MediaStreamTrack): Promise<void>;
+    unpublish(name: string): Promise<void>;
     reconnect(options?: ConnectOptions): Promise<void>;
 }
 interface ReactorInternalState {
@@ -164,13 +280,26 @@ declare function ReactorProvider({ children, connectOptions, jwtToken, ...props
 declare function useReactorStore<T = ReactorStore>(selector: (state: ReactorStore) => T): T;
 
 interface ReactorViewProps {
+    /**
+     * The name of the **receive** track to render.
+     * Must match a track name declared in the `receive` array (model → client).
+     * Defaults to `"main_video"`.
+     */
+    track?: string;
+    /**
+     * Optional name of a **receive** audio track to play alongside the video
+     * (e.g. `"main_audio"`).  The audio is mixed into the same `<video>` element.
+     */
+    audioTrack?: string;
     width?: number;
     height?: number;
     className?: string;
     style?: React.CSSProperties;
     videoObjectFit?: NonNullable<React.VideoHTMLAttributes<HTMLVideoElement>["style"]>["objectFit"];
+    /** Controls whether inbound audio plays. Default true (muted) to satisfy browser autoplay policies. */
+    muted?: boolean;
 }
-declare function ReactorView({ width, height, className, style, videoObjectFit, }: ReactorViewProps): react_jsx_runtime.JSX.Element;
+declare function ReactorView({ track, audioTrack, width, height, className, style, videoObjectFit, muted, }: ReactorViewProps): react_jsx_runtime.JSX.Element;
 
 interface ReactorControllerProps {
     className?: string;
@@ -178,14 +307,19 @@ interface ReactorControllerProps {
 }
 declare function ReactorController({ className, style, }: ReactorControllerProps): react_jsx_runtime.JSX.Element;
 
-interface Props {
+interface WebcamStreamProps {
+    /**
+     * The name of the **send** track to publish the webcam to.
+     * Must match a track name declared in the `send` array (client → model).
+     */
+    track: string;
     className?: string;
     style?: React.CSSProperties;
     videoConstraints?: MediaTrackConstraints;
     showWebcam?: boolean;
     videoObjectFit?: NonNullable<React.VideoHTMLAttributes<HTMLVideoElement>["style"]>["objectFit"];
 }
-declare function WebcamStream({ className, style, videoConstraints, showWebcam, videoObjectFit, }: Props): react_jsx_runtime.JSX.Element;
+declare function WebcamStream({ track, className, style, videoConstraints, showWebcam, videoObjectFit, }: WebcamStreamProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Generic hook for accessing selected parts of the Reactor store.
@@ -195,15 +329,30 @@ declare function WebcamStream({ className, style, videoConstraints, showWebcam,
  */
 declare function useReactor<T>(selector: (state: ReactorStore) => T): T;
 /**
- * Hook for handling message subscriptions with proper React lifecycle management.
+ * Hook for receiving model application messages.
+ *
+ * Only fires for messages sent by the model via `get_ctx().send()`.
+ * Internal platform-level messages (e.g. capabilities) are NOT delivered here.
+ *
+ * @param handler - Callback invoked with each application message payload.
+ */
+declare function useReactorMessage(handler: (message: any) => void): void;
+/**
+ * Hook for receiving internal platform-level (runtime) messages.
  *
- * The handler receives the message payload and the scope it arrived on:
- *   - "application" for model-defined messages (via get_ctx().send())
- *   - "runtime" for platform-level messages (e.g., capabilities response)
+ * This is intended for advanced use cases that need access to the runtime
+ * control layer, such as capabilities negotiation. Model application messages
+ * sent via `get_ctx().send()` are NOT delivered through this hook — use
+ * {@link useReactorMessage} for those.
  *
- * @param handler - The message handler function (message, scope)
+ * @param handler - Callback invoked with each runtime message payload.
+ */
+declare function useReactorInternalMessage(handler: (message: any) => void): void;
+/**
+ * Hook that returns the current connection stats (RTT, etc.).
+ * Updates every ~2s while connected. Returns undefined when disconnected.
  */
-declare function useReactorMessage(handler: (message: any, scope: MessageScope) => void): void;
+declare function useStats(): ConnectionStats | undefined;
 
 /**
  * ⚠️ INSECURE: Fetches a JWT token directly from the client.
@@ -218,4 +367,4 @@ declare function useReactorMessage(handler: (message: any, scope: MessageScope)
  */
 declare function fetchInsecureJwtToken(apiKey: string, coordinatorUrl?: string): Promise<string>;
 
-export { ConflictError, type ConnectOptions, type MessageScope, type Options, PROD_COORDINATOR_URL, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, ReactorView, type ReactorViewProps, WebcamStream, fetchInsecureJwtToken, useReactor, useReactorMessage, useReactorStore };
+export { type AudioTrackOptions, ConflictError, type ConnectOptions, type ConnectionStats, type MessageScope, type Options, PROD_COORDINATOR_URL, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, ReactorView, type ReactorViewProps, type TrackConfig, type VideoTrackOptions, WebcamStream, type WebcamStreamProps, audio, fetchInsecureJwtToken, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats, video };