From 018a04770b32d9ef6b8ebeb871df0d934796a25f Mon Sep 17 00:00:00 2001
From: Robin Andeer <robin.andeer@gmail.com>
Date: Tue, 26 May 2026 16:27:30 -0400
Subject: [PATCH] feat: add connection quality indicator and network preflight

In-call warnings use LiveKit quality plus WebRTC RTT/loss when the server still reports good. Preflight is WebSocket-only and non-blocking; optional ConnectionQualityDevTools for local verification.
---
 CHANGELOG.md                                  |  17 +
 Justfile                                      |  58 +++-
 examples/vanilla-js/index.html                |  28 +-
 examples/vanilla-js/styles.css                |   7 +
 packages/core/README.md                       |  17 +
 packages/core/src/client.ts                   |  19 +-
 packages/core/src/connection-check.ts         |  86 +++++
 packages/core/src/connection-quality.test.ts  |  83 +++++
 packages/core/src/connection-quality.ts       |  76 ++++
 packages/core/src/connection-stats.test.ts    |  93 +++++
 packages/core/src/connection-stats.ts         |  54 +++
 packages/core/src/index.ts                    |  21 ++
 packages/react/src/components/AvatarCall.tsx  |  29 ++
 .../react/src/components/AvatarSession.tsx    |   2 +-
 .../src/components/ConnectionIndicator.tsx    |  95 +++++
 .../components/ConnectionQualityDevTools.tsx  |  18 +
 .../react/src/hooks/useConnectionCheck.ts     |  75 ++++
 .../react/src/hooks/useConnectionQuality.ts   | 327 ++++++++++++++++++
 packages/react/src/index.test.ts              |   4 +
 packages/react/src/index.ts                   |  20 ++
 packages/react/src/styles.css                 | 101 +++++-
 packages/react/src/types.ts                   |  11 +
 22 files changed, 1232 insertions(+), 9 deletions(-)
 create mode 100644 packages/core/src/connection-check.ts
 create mode 100644 packages/core/src/connection-quality.test.ts
 create mode 100644 packages/core/src/connection-quality.ts
 create mode 100644 packages/core/src/connection-stats.test.ts
 create mode 100644 packages/core/src/connection-stats.ts
 create mode 100644 packages/react/src/components/ConnectionIndicator.tsx
 create mode 100644 packages/react/src/components/ConnectionQualityDevTools.tsx
 create mode 100644 packages/react/src/hooks/useConnectionCheck.ts
 create mode 100644 packages/react/src/hooks/useConnectionQuality.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2d7fe7b..2373e73 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **`checkAvatarConnection()`** — preflight WebSocket/WebRTC checks using LiveKit `ConnectionCheck`, with normalized results (no LiveKit types in the public API).
+- **`useConnectionQuality()`** and **`ConnectionIndicator`** — composable in-call warning when the local network is degraded or reconnecting (debounced; local participant only).
+- **`useConnectionCheck()`** and **`AvatarCall` `connectionCheck` prop** — optional silent background preflight (no UI; in-call warnings use `ConnectionIndicator`).
+- **`session.connectionQuality`** getter on core `AvatarSession`.
+
+### Fixed
+
+- **`ConnectionQualityChanged`** in core now only reflects the **local** participant (avoids avatar quality updates being shown as the user's network issue).
+- **Preflight `checkAvatarConnection`** defaults to WebSocket-only (no full WebRTC join on the session token before the call).
+- **`useConnectionQuality`** treats LiveKit **`signalReconnecting`** like reconnecting for the in-call warning.
+- **`AvatarSession` state** maps LiveKit **`signalReconnecting`** to `reconnecting` (was incorrectly treated as `ended`).
+- **`ConnectionIndicator`** also uses inbound WebRTC stats (RTT / packet loss) when LiveKit still reports `good`, so slow links (e.g. DevTools 3G) can surface **Slow connection**.
+- **`ConnectionQualityDevTools`** and **`connectionDebug`** / **`connectionPreviewWarning`** on `AvatarCall` — opt-in dev overlay (metrics top-right; does not affect control bar layout).
+- Warning pill includes an amber **signal** dot; reconnecting uses a slightly warmer tone.
+
 ## [0.16.0] - 2026-05-12
 
 ### Added
diff --git a/Justfile b/Justfile
index a4ac928..10fb989 100644
--- a/Justfile
+++ b/Justfile
@@ -1,3 +1,8 @@
+# Run `just` or `just --list` to see recipes. Requires https://github.com/casey/just
+
+default:
+    @just --list
+
 # Build
 build: build-core build-react
 build-core:
@@ -15,15 +20,60 @@ typecheck: build-core
     cd packages/react && bun run typecheck
 lint:
     bun run lint
+verify: typecheck lint test build
 
-# Dev
+# Dev (packages)
 dev-core:
     cd packages/core && bun run dev
 dev-react: build-core
     cd packages/react && bun run dev
 
-# Examples
+# Link workspace packages for local example development (run once per clone if needed)
+link-packages:
+    cd packages/core && bun link
+    cd packages/react && bun link
+
+playground: build link-packages
+    cd playground && bun install && bun link @runwayml/avatars @runwayml/avatars-react && bun run dev
+
+# Examples — build SDK, link workspace packages, install, then start dev server.
+# Core-only examples link @runwayml/avatars; React examples link both packages.
+
 vanilla-js: build-core
-    cd examples/vanilla-js && bun install && bun run dev
+    cd examples/vanilla-js && bun install && bun link @runwayml/avatars && bun run dev
+
 sveltekit: build-core
-    cd examples/sveltekit && bun install && bun run dev
+    cd examples/sveltekit && bun install && bun link @runwayml/avatars && bun run dev
+
+dev-express: build link-packages
+    cd examples/express && bun install && bun link @runwayml/avatars @runwayml/avatars-react && bun run dev
+
+dev-nextjs: build link-packages
+    cd examples/nextjs && bun install && bun link @runwayml/avatars @runwayml/avatars-react && bun run dev
+
+dev-nextjs-simple: build link-packages
+    cd examples/nextjs-simple && bun install && bun link @runwayml/avatars @runwayml/avatars-react && bun run dev
+
+dev-nextjs-client-events: build link-packages
+    cd examples/nextjs-client-events && bun install && bun link @runwayml/avatars @runwayml/avatars-react && bun run dev
+
+dev-nextjs-server-actions: build link-packages
+    cd examples/nextjs-server-actions && bun install && bun link @runwayml/avatars @runwayml/avatars-react && bun run dev
+
+dev-nextjs-rpc: build link-packages
+    cd examples/nextjs-rpc && bun install && bun link @runwayml/avatars @runwayml/avatars-react && bun run dev
+
+dev-nextjs-rpc-external-api: build link-packages
+    cd examples/nextjs-rpc-external-api && bun install && bun link @runwayml/avatars @runwayml/avatars-react && bun run dev
+
+dev-nextjs-rpc-weather: build link-packages
+    cd examples/nextjs-rpc-weather && bun install && bun link @runwayml/avatars @runwayml/avatars-react && bun run dev
+
+dev-subtitles: build link-packages
+    cd examples/subtitles && bun install && bun link @runwayml/avatars @runwayml/avatars-react && bun run dev
+
+dev-react-router: build link-packages
+    cd examples/react-router && bun install && bun link @runwayml/avatars @runwayml/avatars-react && bun run dev
+
+elevenlabs: build link-packages
+    cd examples/nextjs-elevenlabs && bun install && bun link @runwayml/avatars @runwayml/avatars-react && bun run dev
diff --git a/examples/vanilla-js/index.html b/examples/vanilla-js/index.html
index a3d539a..fcf1b52 100644
--- a/examples/vanilla-js/index.html
+++ b/examples/vanilla-js/index.html
@@ -17,11 +17,17 @@
         <button id="end" disabled>End call</button>
       </div>
       <p id="status">Ready</p>
+      <p id="connection-warning" hidden></p>
     </main>
 
     <script type="module">
       import './styles.css';
-      import { streamTo, AvatarEvent } from '@runwayml/avatars';
+      import {
+        streamTo,
+        AvatarEvent,
+        connectionQualityWarningMessage,
+        isDegradedConnectionQuality,
+      } from '@runwayml/avatars';
 
       const avatarEl = document.getElementById('avatar');
       const webcamEl = document.getElementById('webcam');
@@ -29,6 +35,7 @@
       const muteBtn = document.getElementById('mute');
       const endBtn = document.getElementById('end');
       const statusEl = document.getElementById('status');
+      const connectionWarningEl = document.getElementById('connection-warning');
 
       async function fetchCredentials() {
         const res = await fetch('/api/avatar/connect', {
@@ -44,6 +51,7 @@
         startBtn.disabled = true;
 
         const credentials = await fetchCredentials();
+
         const session = await streamTo({ credentials, target: avatarEl });
 
         session.on(AvatarEvent.AvatarVideoReady, () => {
@@ -69,6 +77,23 @@
           console.error('Session error:', err);
         });
 
+        session.on(AvatarEvent.ConnectionQualityChanged, (quality) => {
+          const message = connectionQualityWarningMessage(quality);
+          if (message && isDegradedConnectionQuality(quality)) {
+            connectionWarningEl.hidden = false;
+            connectionWarningEl.textContent = message;
+          } else if (!isDegradedConnectionQuality(quality)) {
+            connectionWarningEl.hidden = true;
+          }
+        });
+
+        session.on(AvatarEvent.StateChanged, (state) => {
+          if (state === 'reconnecting') {
+            connectionWarningEl.hidden = false;
+            connectionWarningEl.textContent = 'Reconnecting…';
+          }
+        });
+
         muteBtn.disabled = false;
         endBtn.disabled = false;
 
@@ -78,6 +103,7 @@
           session.end();
           webcamEl.srcObject = null;
           statusEl.textContent = 'Ended';
+          connectionWarningEl.hidden = true;
           startBtn.disabled = false;
           muteBtn.disabled = true;
           endBtn.disabled = true;
diff --git a/examples/vanilla-js/styles.css b/examples/vanilla-js/styles.css
index be2e9f1..ecedfb6 100644
--- a/examples/vanilla-js/styles.css
+++ b/examples/vanilla-js/styles.css
@@ -95,3 +95,10 @@ button:disabled {
   color: #555;
   letter-spacing: 0.02em;
 }
+
+#connection-warning {
+  font-size: 0.8125rem;
+  color: #e8c47c;
+  text-align: center;
+  max-width: 100%;
+}
diff --git a/packages/core/README.md b/packages/core/README.md
index 454cdc7..6dc34b3 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -56,6 +56,23 @@ session.on(AvatarEvent.Error, (error) => {});
 session.on(AvatarEvent.AvatarVideoReady, (track) => {});
 session.on(AvatarEvent.AvatarAudioReady, (track) => {});
 session.on(AvatarEvent.MediaChanged, () => {});
+session.on(AvatarEvent.ConnectionQualityChanged, (quality) => {
+  // excellent | good | poor | lost | unknown (local participant only)
+});
+```
+
+### Connection preflight
+
+```javascript
+import { checkAvatarConnection } from '@runwayml/avatars';
+
+const result = await checkAvatarConnection({
+  serverUrl: credentials.serverUrl,
+  token: credentials.token,
+});
+if (!result.success) {
+  console.warn('Network check failed', result.checks);
+}
 ```
 
 ### Error handling
diff --git a/packages/core/src/client.ts b/packages/core/src/client.ts
index 42eb14c..3835b58 100644
--- a/packages/core/src/client.ts
+++ b/packages/core/src/client.ts
@@ -57,6 +57,7 @@ function toSessionState(cs: ConnectionState): SessionState {
     case ConnectionState.Connected:
       return 'active';
     case ConnectionState.Reconnecting:
+    case ConnectionState.SignalReconnecting:
       return 'reconnecting';
     case ConnectionState.Disconnected:
       return 'ended';
@@ -89,6 +90,7 @@ export class AvatarSession extends Emitter<AvatarEventMap> {
   private _userSpeaking = false;
   private _avatarSpeaking = false;
   private _connectedAt: number | null = null;
+  private _connectionQuality: ConnectionQuality = 'unknown';
 
   readonly mic: MediaController;
   readonly camera: MediaController;
@@ -151,6 +153,11 @@ export class AvatarSession extends Emitter<AvatarEventMap> {
     return Date.now() - this._connectedAt;
   }
 
+  /** Local participant connection quality (from LiveKit). */
+  get connectionQuality(): ConnectionQuality {
+    return this._connectionQuality;
+  }
+
   waitFor<K extends keyof AvatarEventMap>(event: K): Promise<AvatarEventMap[K][0]> {
     return new Promise((resolve) => {
       this.once(event, ((...args: AvatarEventMap[K]) => {
@@ -426,10 +433,17 @@ export class AvatarSession extends Emitter<AvatarEventMap> {
 
     room.on(
       RoomEvent.ConnectionQualityChanged,
-      (quality: LKConnectionQuality, _participant: Participant) => {
-        this.emit(AvatarEvent.ConnectionQualityChanged, toLKQuality(quality));
+      (quality: LKConnectionQuality, participant: Participant) => {
+        if (!participant.isLocal) {
+          return;
+        }
+        const mapped = toLKQuality(quality);
+        this._connectionQuality = mapped;
+        this.emit(AvatarEvent.ConnectionQualityChanged, mapped);
       },
     );
+
+    this._connectionQuality = toLKQuality(room.localParticipant.connectionQuality);
   }
 
   private reattachTracks(): void {
@@ -611,6 +625,7 @@ export class AvatarSession extends Emitter<AvatarEventMap> {
     this._userSpeaking = false;
     this._avatarSpeaking = false;
     this._connectedAt = null;
+    this._connectionQuality = 'unknown';
     this.flatDeltaAcc.reset();
     this.setState('ended');
   }
diff --git a/packages/core/src/connection-check.ts b/packages/core/src/connection-check.ts
new file mode 100644
index 0000000..0557e72
--- /dev/null
+++ b/packages/core/src/connection-check.ts
@@ -0,0 +1,86 @@
+import {
+  CheckStatus,
+  ConnectionCheck,
+  type CheckInfo,
+} from 'livekit-client';
+
+export type ConnectionCheckStatus =
+  | 'idle'
+  | 'running'
+  | 'skipped'
+  | 'success'
+  | 'failed';
+
+export interface ConnectionCheckStep {
+  name: string;
+  description: string;
+  status: ConnectionCheckStatus;
+  logs: ReadonlyArray<{ level: 'info' | 'warning' | 'error'; message: string }>;
+}
+
+export interface AvatarConnectionCheckOptions {
+  serverUrl: string;
+  token: string;
+  /**
+   * Also run a full WebRTC room join after the WebSocket check.
+   * Default false — WebRTC preflight uses the same session token as the call and can
+   * leave the room in a bad state before AvatarSession connects.
+   */
+  webrtc?: boolean;
+}
+
+export interface AvatarConnectionCheckResult {
+  success: boolean;
+  checks: ReadonlyArray<ConnectionCheckStep>;
+}
+
+function mapCheckStatus(status: CheckStatus): ConnectionCheckStatus {
+  switch (status) {
+    case CheckStatus.IDLE:
+      return 'idle';
+    case CheckStatus.RUNNING:
+      return 'running';
+    case CheckStatus.SKIPPED:
+      return 'skipped';
+    case CheckStatus.SUCCESS:
+      return 'success';
+    case CheckStatus.FAILED:
+      return 'failed';
+    default:
+      return 'idle';
+  }
+}
+
+function mapCheckInfo(info: CheckInfo): ConnectionCheckStep {
+  return {
+    name: info.name,
+    description: info.description,
+    status: mapCheckStatus(info.status),
+    logs: info.logs.map((log) => ({
+      level: log.level,
+      message: log.message,
+    })),
+  };
+}
+
+/**
+ * Preflight connectivity checks against a LiveKit server using session credentials.
+ * Run before joining an avatar session (same `serverUrl` + `token` as connect).
+ */
+export async function checkAvatarConnection(
+  options: AvatarConnectionCheckOptions,
+): Promise<AvatarConnectionCheckResult> {
+  const { serverUrl, token, webrtc = false } = options;
+  const checker = new ConnectionCheck(serverUrl, token);
+
+  await checker.checkWebsocket();
+  if (webrtc) {
+    await checker.checkWebRTC();
+  }
+
+  const checks = checker.getResults().map(mapCheckInfo);
+  return {
+    success: checker.isSuccess(),
+    checks,
+  };
+}
diff --git a/packages/core/src/connection-quality.test.ts b/packages/core/src/connection-quality.test.ts
new file mode 100644
index 0000000..4cda73c
--- /dev/null
+++ b/packages/core/src/connection-quality.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  connectionQualityWarningMessage,
+  isDegradedConnectionQuality,
+  shouldShowConnectionQualityWarning,
+} from './connection-quality';
+
+describe('connection-quality', () => {
+  it('detects degraded quality levels', () => {
+    expect(isDegradedConnectionQuality('poor')).toBe(true);
+    expect(isDegradedConnectionQuality('lost')).toBe(true);
+    expect(isDegradedConnectionQuality('good')).toBe(false);
+    expect(isDegradedConnectionQuality('excellent')).toBe(false);
+  });
+
+  it('returns warning copy for degraded and reconnecting states', () => {
+    expect(connectionQualityWarningMessage('poor')).toBe('Unstable connection');
+    expect(connectionQualityWarningMessage('lost')).toBe(
+      'Connection lost — check your network',
+    );
+    expect(connectionQualityWarningMessage('good', 'reconnecting')).toBe(
+      'Reconnecting…',
+    );
+    expect(connectionQualityWarningMessage('excellent')).toBeNull();
+    expect(
+      connectionQualityWarningMessage('good', undefined, {
+        statsStressed: true,
+      }),
+    ).toBe('Slow connection');
+  });
+
+  it('shows warning when WebRTC stats are stressed', () => {
+    const now = 10_000;
+    expect(
+      shouldShowConnectionQualityWarning({
+        quality: 'good',
+        degradedSinceMs: null,
+        statsDegradedSinceMs: now - 3000,
+        stableSinceMs: null,
+        now,
+      }),
+    ).toBe(true);
+  });
+
+  it('debounces showing and hiding warnings', () => {
+    const now = 10_000;
+    expect(
+      shouldShowConnectionQualityWarning({
+        quality: 'poor',
+        degradedSinceMs: now - 1000,
+        stableSinceMs: null,
+        now,
+      }),
+    ).toBe(false);
+
+    expect(
+      shouldShowConnectionQualityWarning({
+        quality: 'poor',
+        degradedSinceMs: now - 3000,
+        stableSinceMs: null,
+        now,
+      }),
+    ).toBe(true);
+
+    expect(
+      shouldShowConnectionQualityWarning({
+        quality: 'good',
+        degradedSinceMs: null,
+        stableSinceMs: now - 2000,
+        now,
+      }),
+    ).toBe(true);
+
+    expect(
+      shouldShowConnectionQualityWarning({
+        quality: 'good',
+        degradedSinceMs: null,
+        stableSinceMs: now - 6000,
+        now,
+      }),
+    ).toBe(false);
+  });
+});
diff --git a/packages/core/src/connection-quality.ts b/packages/core/src/connection-quality.ts
new file mode 100644
index 0000000..e62261e
--- /dev/null
+++ b/packages/core/src/connection-quality.ts
@@ -0,0 +1,76 @@
+import type { ConnectionQuality, SessionState } from './types';
+
+export const CONNECTION_QUALITY_SHOW_DELAY_MS = 2500;
+export const CONNECTION_QUALITY_HIDE_DELAY_MS = 5000;
+
+export function isDegradedConnectionQuality(
+  quality: ConnectionQuality,
+): boolean {
+  return quality === 'poor' || quality === 'lost';
+}
+
+export function connectionQualityWarningMessage(
+  quality: ConnectionQuality,
+  sessionState?: SessionState,
+  options?: { statsStressed?: boolean },
+): string | null {
+  if (sessionState === 'reconnecting') {
+    return 'Reconnecting…';
+  }
+  switch (quality) {
+    case 'lost':
+      return 'Connection lost — check your network';
+    case 'poor':
+      return 'Unstable connection';
+    default:
+      if (options?.statsStressed) {
+        return 'Slow connection';
+      }
+      return null;
+  }
+}
+
+export function shouldShowConnectionQualityWarning({
+  quality,
+  sessionState,
+  degradedSinceMs,
+  statsDegradedSinceMs,
+  stableSinceMs,
+  now = Date.now(),
+}: {
+  quality: ConnectionQuality;
+  sessionState?: SessionState;
+  degradedSinceMs: number | null;
+  /** Client-side WebRTC stats stress (when LiveKit quality is still good). */
+  statsDegradedSinceMs?: number | null;
+  stableSinceMs: number | null;
+  now?: number;
+}): boolean {
+  if (sessionState === 'reconnecting') {
+    return true;
+  }
+
+  const isLiveKitDegraded = isDegradedConnectionQuality(quality);
+  const isStatsDegraded = statsDegradedSinceMs != null;
+
+  if (isLiveKitDegraded || isStatsDegraded) {
+    const sinceMs = [
+      isLiveKitDegraded ? degradedSinceMs : null,
+      isStatsDegraded ? statsDegradedSinceMs ?? null : null,
+    ]
+      .filter((value): value is number => value !== null)
+      .reduce<number | null>(
+        (earliest, value) =>
+          earliest === null ? value : Math.min(earliest, value),
+        null,
+      );
+    if (sinceMs === null) {
+      return false;
+    }
+    return now - sinceMs >= CONNECTION_QUALITY_SHOW_DELAY_MS;
+  }
+  if (stableSinceMs !== null) {
+    return now - stableSinceMs < CONNECTION_QUALITY_HIDE_DELAY_MS;
+  }
+  return false;
+}
diff --git a/packages/core/src/connection-stats.test.ts b/packages/core/src/connection-stats.test.ts
new file mode 100644
index 0000000..e4905dc
--- /dev/null
+++ b/packages/core/src/connection-stats.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'bun:test';
+import { isRtcStatsDegraded, summarizeRtcStats } from './connection-stats';
+
+function mockReport(entries: Array<[string, object]>): RTCStatsReport {
+  const map = new Map<string, object>(entries);
+  return {
+    forEach(
+      callback: (value: object, key: string) => void,
+    ) {
+      map.forEach((value, key) => {
+        callback(value, key);
+      });
+    },
+  } as RTCStatsReport;
+}
+
+describe('connection-stats', () => {
+  it('detects high RTT on candidate-pair', () => {
+    const report = mockReport([
+      [
+        'pair',
+        {
+          type: 'candidate-pair',
+          state: 'succeeded',
+          currentRoundTripTime: 0.5,
+        },
+      ],
+    ]);
+    expect(isRtcStatsDegraded(report)).toBe(true);
+  });
+
+  it('detects inbound packet loss', () => {
+    const report = mockReport([
+      [
+        'in',
+        {
+          type: 'inbound-rtp',
+          packetsReceived: 90,
+          packetsLost: 10,
+        },
+      ],
+    ]);
+    expect(isRtcStatsDegraded(report)).toBe(true);
+  });
+
+  it('summarizes RTT and loss', () => {
+    const summary = summarizeRtcStats(
+      mockReport([
+        [
+          'pair',
+          {
+            type: 'candidate-pair',
+            state: 'succeeded',
+            currentRoundTripTime: 0.12,
+          },
+        ],
+        [
+          'in',
+          {
+            type: 'inbound-rtp',
+            packetsReceived: 100,
+            packetsLost: 1,
+          },
+        ],
+      ]),
+    );
+    expect(summary.maxRttMs).toBe(120);
+    expect(summary.maxLossRatio).toBeCloseTo(0.01);
+    expect(summary.degraded).toBe(false);
+  });
+
+  it('returns false for healthy stats', () => {
+    const report = mockReport([
+      [
+        'pair',
+        {
+          type: 'candidate-pair',
+          state: 'succeeded',
+          currentRoundTripTime: 0.05,
+        },
+      ],
+      [
+        'in',
+        {
+          type: 'inbound-rtp',
+          packetsReceived: 1000,
+          packetsLost: 0,
+        },
+      ],
+    ]);
+    expect(isRtcStatsDegraded(report)).toBe(false);
+  });
+});
diff --git a/packages/core/src/connection-stats.ts b/packages/core/src/connection-stats.ts
new file mode 100644
index 0000000..60cd727
--- /dev/null
+++ b/packages/core/src/connection-stats.ts
@@ -0,0 +1,54 @@
+/** RTT above this (ms) suggests a slow or constrained path (e.g. 3G). */
+export const CONNECTION_STATS_RTT_THRESHOLD_MS = 400;
+
+/** Inbound packet loss ratio above this counts as degraded. */
+export const CONNECTION_STATS_PACKET_LOSS_RATIO = 0.03;
+
+export type RtcStatsSummary = {
+  maxRttMs: number;
+  maxLossRatio: number;
+  degraded: boolean;
+};
+
+export function summarizeRtcStats(report: RTCStatsReport): RtcStatsSummary {
+  let maxRttMs = 0;
+  let maxLossRatio = 0;
+
+  report.forEach((stat) => {
+    if (stat.type === 'candidate-pair') {
+      const pair = stat as RTCStats & {
+        state?: string;
+        currentRoundTripTime?: number;
+      };
+      if (pair.state === 'succeeded' && typeof pair.currentRoundTripTime === 'number') {
+        maxRttMs = Math.max(maxRttMs, pair.currentRoundTripTime * 1000);
+      }
+    }
+
+    if (stat.type === 'inbound-rtp') {
+      const inbound = stat as RTCInboundRtpStreamStats;
+      const received = inbound.packetsReceived ?? 0;
+      const lost = inbound.packetsLost ?? 0;
+      const total = received + lost;
+      if (total > 0) {
+        maxLossRatio = Math.max(maxLossRatio, lost / total);
+      }
+    }
+  });
+
+  return {
+    maxRttMs,
+    maxLossRatio,
+    degraded:
+      maxRttMs >= CONNECTION_STATS_RTT_THRESHOLD_MS ||
+      maxLossRatio >= CONNECTION_STATS_PACKET_LOSS_RATIO,
+  };
+}
+
+/**
+ * Infer network stress from WebRTC stats when LiveKit still reports "good".
+ * Uses ICE RTT and inbound RTP loss (subscriber path — avatar video downlink).
+ */
+export function isRtcStatsDegraded(report: RTCStatsReport): boolean {
+  return summarizeRtcStats(report).degraded;
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 9bcaec3..73130b5 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -1,3 +1,24 @@
+export { checkAvatarConnection } from './connection-check';
+export type {
+  AvatarConnectionCheckOptions,
+  AvatarConnectionCheckResult,
+  ConnectionCheckStatus,
+  ConnectionCheckStep,
+} from './connection-check';
+export {
+  CONNECTION_QUALITY_HIDE_DELAY_MS,
+  CONNECTION_QUALITY_SHOW_DELAY_MS,
+  connectionQualityWarningMessage,
+  isDegradedConnectionQuality,
+  shouldShowConnectionQualityWarning,
+} from './connection-quality';
+export {
+  CONNECTION_STATS_PACKET_LOSS_RATIO,
+  CONNECTION_STATS_RTT_THRESHOLD_MS,
+  isRtcStatsDegraded,
+  summarizeRtcStats,
+} from './connection-stats';
+export type { RtcStatsSummary } from './connection-stats';
 export { AvatarSession, connect, streamTo } from './client';
 export { AvatarError } from './error';
 export type { AvatarErrorCode } from './error';
diff --git a/packages/react/src/components/AvatarCall.tsx b/packages/react/src/components/AvatarCall.tsx
index 11d6ff0..61b0ea7 100644
--- a/packages/react/src/components/AvatarCall.tsx
+++ b/packages/react/src/components/AvatarCall.tsx
@@ -25,11 +25,13 @@
  * ```
  */
 
+import { useConnectionCheck } from '../hooks/useConnectionCheck';
 import { useCredentials } from '../hooks/useCredentials';
 import { useLatest } from '../hooks/useLatest';
 import type { AvatarCallProps, ClientEvent } from '../types';
 import { AvatarSession } from './AvatarSession';
 import { AvatarVideo } from './AvatarVideo';
+import { ConnectionIndicator } from './ConnectionIndicator';
 import { ControlBar } from './ControlBar';
 import { UserVideo } from './UserVideo';
 
@@ -49,6 +51,9 @@ export function AvatarCall<E extends ClientEvent = ClientEvent>({
   onClientEvent,
   children,
   initialScreenStream,
+  connectionCheck = false,
+  connectionDebug = false,
+  connectionPreviewWarning = false,
   __unstable_roomOptions,
   ...props
 }: AvatarCallProps<E>) {
@@ -69,6 +74,15 @@ export function AvatarCall<E extends ClientEvent = ClientEvent>({
     onErrorRef.current?.(err);
   };
 
+  const readyCredentials =
+    credentialsState.status === 'ready' ? credentialsState.credentials : null;
+
+  const preflight = useConnectionCheck({
+    credentials: readyCredentials,
+    enabled: connectionCheck && readyCredentials !== null,
+    runOnMount: connectionCheck,
+  });
+
   const backgroundStyle = avatarImageUrl
     ? ({ '--avatar-image': `url(${avatarImageUrl})` } as React.CSSProperties)
     : undefined;
@@ -76,6 +90,10 @@ export function AvatarCall<E extends ClientEvent = ClientEvent>({
   const defaultChildren = (
     <>
       <AvatarVideo />
+      <ConnectionIndicator
+        debug={connectionDebug}
+        previewWarning={connectionPreviewWarning}
+      />
       <UserVideo />
       <ControlBar />
     </>
@@ -105,6 +123,17 @@ export function AvatarCall<E extends ClientEvent = ClientEvent>({
       {...props}
       data-avatar-call=""
       data-avatar-id={avatarId}
+      data-connection-check={
+        connectionCheck
+          ? preflight.status === 'running'
+            ? 'running'
+            : preflight.result?.success
+              ? 'passed'
+              : preflight.result
+                ? 'failed'
+                : undefined
+          : undefined
+      }
       style={{ ...props.style, ...backgroundStyle }}
     >
       <AvatarSession
diff --git a/packages/react/src/components/AvatarSession.tsx b/packages/react/src/components/AvatarSession.tsx
index 2dea22e..8fce927 100644
--- a/packages/react/src/components/AvatarSession.tsx
+++ b/packages/react/src/components/AvatarSession.tsx
@@ -294,7 +294,7 @@ function AvatarSessionContextInner({
   return (
     <AvatarSessionContext.Provider value={contextValue}>
       <MediaDeviceErrorContext.Provider value={mediaDeviceErrors}>
-        {children}
+        <div data-avatar-session-surface="">{children}</div>
       </MediaDeviceErrorContext.Provider>
     </AvatarSessionContext.Provider>
   );
diff --git a/packages/react/src/components/ConnectionIndicator.tsx b/packages/react/src/components/ConnectionIndicator.tsx
new file mode 100644
index 0000000..911322e
--- /dev/null
+++ b/packages/react/src/components/ConnectionIndicator.tsx
@@ -0,0 +1,95 @@
+'use client';
+
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import {
+  useConnectionQuality,
+  type ConnectionQualityDiagnostics,
+  type UseConnectionQualityReturn,
+} from '../hooks/useConnectionQuality';
+
+export interface ConnectionIndicatorProps
+  extends Omit<ComponentPropsWithoutRef<'div'>, 'children'> {
+  children?: (state: UseConnectionQualityReturn) => ReactNode;
+  /**
+   * Live metrics overlay for verifying warnings (RTT, loss, debounce timers).
+   * Also enable `connectionPreviewWarning` on AvatarCall to force the user-facing pill.
+   */
+  debug?: boolean;
+  /** Show the warning pill immediately (UI smoke test; ignores network). */
+  previewWarning?: boolean;
+}
+
+function ConnectionQualityDebugPanel({
+  diagnostics,
+}: {
+  diagnostics: ConnectionQualityDiagnostics;
+}) {
+  const lossPct =
+    diagnostics.maxLossRatio !== null
+      ? `${(diagnostics.maxLossRatio * 100).toFixed(1)}%`
+      : '—';
+  const rtt =
+    diagnostics.maxRttMs !== null
+      ? `${Math.round(diagnostics.maxRttMs)}ms`
+      : '—';
+
+  return (
+    <pre data-avatar-connection-debug="">
+      {`lk: ${diagnostics.quality} · rtc: ${diagnostics.connectionState}
+warn: ${diagnostics.showWarning ? 'yes' : 'no'}${diagnostics.message ? ` · ${diagnostics.message}` : ''}
+stats: rtt ${rtt} · loss ${lossPct} · tracks ${diagnostics.tracksSampled}
+stress: lk ${diagnostics.livekitDegraded ? 'yes' : 'no'} · rtc ${diagnostics.statsStressed ? 'yes' : 'no'}
+show in: ${diagnostics.msUntilShow !== null ? `${diagnostics.msUntilShow}ms` : '—'}`}
+    </pre>
+  );
+}
+
+/**
+ * Subtle overlay when the local network connection is degraded or reconnecting.
+ * Renders nothing when connection quality is good.
+ */
+export function ConnectionIndicator({
+  children,
+  debug = false,
+  previewWarning = false,
+  ...props
+}: ConnectionIndicatorProps) {
+  const connection = useConnectionQuality({ debug });
+
+  const showWarning = previewWarning || connection.showWarning;
+  const message = previewWarning
+    ? 'Slow connection (preview)'
+    : connection.message;
+
+  if (children) {
+    return <>{children({ ...connection, showWarning, message })}</>;
+  }
+
+  const showPill = showWarning && message;
+  const diagnostics = connection.diagnostics;
+
+  if (!showPill && !diagnostics) {
+    return null;
+  }
+
+  return (
+    <div data-avatar-connection-overlay="" {...props}>
+      {diagnostics ? (
+        <ConnectionQualityDebugPanel diagnostics={diagnostics} />
+      ) : null}
+      {showPill ? (
+        <output
+          data-avatar-connection-indicator=""
+          data-connection-quality={connection.quality}
+          data-connection-reason={
+            previewWarning ? 'preview' : (connection.reason ?? undefined)
+          }
+          aria-live="polite"
+        >
+          <span data-avatar-connection-signal="" aria-hidden="true" />
+          <span data-avatar-connection-message="">{message}</span>
+        </output>
+      ) : null}
+    </div>
+  );
+}
diff --git a/packages/react/src/components/ConnectionQualityDevTools.tsx b/packages/react/src/components/ConnectionQualityDevTools.tsx
new file mode 100644
index 0000000..7a73ef3
--- /dev/null
+++ b/packages/react/src/components/ConnectionQualityDevTools.tsx
@@ -0,0 +1,18 @@
+'use client';
+
+import { ConnectionIndicator } from './ConnectionIndicator';
+
+export interface ConnectionQualityDevToolsProps {
+  /** Force the warning pill (UI smoke test). */
+  previewWarning?: boolean;
+}
+
+/**
+ * Optional dev overlay: live metrics + the same warning pill as production.
+ * Mount inside `AvatarSession` / custom `AvatarCall` children — not enabled by default.
+ */
+export function ConnectionQualityDevTools({
+  previewWarning = false,
+}: ConnectionQualityDevToolsProps) {
+  return <ConnectionIndicator debug previewWarning={previewWarning} />;
+}
diff --git a/packages/react/src/hooks/useConnectionCheck.ts b/packages/react/src/hooks/useConnectionCheck.ts
new file mode 100644
index 0000000..634bf33
--- /dev/null
+++ b/packages/react/src/hooks/useConnectionCheck.ts
@@ -0,0 +1,75 @@
+'use client';
+
+import {
+  checkAvatarConnection,
+  type AvatarConnectionCheckResult,
+  type SessionCredentials,
+} from '@runwayml/avatars';
+import * as React from 'react';
+
+export type UseConnectionCheckReturn = {
+  status: 'idle' | 'running' | 'success' | 'failed' | 'error';
+  result: AvatarConnectionCheckResult | null;
+  error: Error | null;
+  run: () => Promise<AvatarConnectionCheckResult | null>;
+};
+
+export function useConnectionCheck({
+  credentials,
+  enabled = true,
+  webrtc = false,
+  runOnMount = false,
+}: {
+  credentials: SessionCredentials | null;
+  enabled?: boolean;
+  webrtc?: boolean;
+  runOnMount?: boolean;
+}): UseConnectionCheckReturn {
+  const [status, setStatus] = React.useState<UseConnectionCheckReturn['status']>(
+    'idle',
+  );
+  const [result, setResult] =
+    React.useState<AvatarConnectionCheckResult | null>(null);
+  const [error, setError] = React.useState<Error | null>(null);
+  const runningRef = React.useRef(false);
+  const resultRef = React.useRef(result);
+  resultRef.current = result;
+
+  const run = React.useCallback(async () => {
+    if (!credentials || !enabled) {
+      return null;
+    }
+    if (runningRef.current) {
+      return resultRef.current;
+    }
+    runningRef.current = true;
+    setStatus('running');
+    setError(null);
+    try {
+      const next = await checkAvatarConnection({
+        serverUrl: credentials.serverUrl,
+        token: credentials.token,
+        webrtc,
+      });
+      setResult(next);
+      setStatus(next.success ? 'success' : 'failed');
+      return next;
+    } catch (err) {
+      const nextError = err instanceof Error ? err : new Error(String(err));
+      setError(nextError);
+      setStatus('error');
+      return null;
+    } finally {
+      runningRef.current = false;
+    }
+  }, [credentials, enabled, webrtc]);
+
+  React.useEffect(() => {
+    if (!runOnMount || !credentials || !enabled) {
+      return;
+    }
+    void run();
+  }, [runOnMount, credentials, enabled, run]);
+
+  return { status, result, error, run };
+}
diff --git a/packages/react/src/hooks/useConnectionQuality.ts b/packages/react/src/hooks/useConnectionQuality.ts
new file mode 100644
index 0000000..87401d6
--- /dev/null
+++ b/packages/react/src/hooks/useConnectionQuality.ts
@@ -0,0 +1,327 @@
+'use client';
+
+import { useConnectionState, useRoomContext } from '@livekit/components-react';
+import {
+  CONNECTION_QUALITY_SHOW_DELAY_MS,
+  connectionQualityWarningMessage,
+  isDegradedConnectionQuality,
+  summarizeRtcStats,
+  shouldShowConnectionQualityWarning,
+  type ConnectionQuality,
+} from '@runwayml/avatars';
+import {
+  ConnectionQuality as LKConnectionQuality,
+  ConnectionState,
+  RoomEvent,
+} from 'livekit-client';
+import type { Participant, RemoteTrack } from 'livekit-client';
+import * as React from 'react';
+
+export type ConnectionQualityWarningReason = 'degraded' | 'reconnecting';
+
+export type ConnectionQualityDiagnostics = {
+  connectionState: string;
+  quality: ConnectionQuality;
+  showWarning: boolean;
+  message: string | null;
+  statsStressed: boolean;
+  livekitDegraded: boolean;
+  maxRttMs: number | null;
+  maxLossRatio: number | null;
+  tracksSampled: number;
+  msUntilShow: number | null;
+  lastSampleAt: number | null;
+};
+
+export type UseConnectionQualityReturn = {
+  quality: ConnectionQuality;
+  showWarning: boolean;
+  message: string | null;
+  reason: ConnectionQualityWarningReason | null;
+  diagnostics: ConnectionQualityDiagnostics | null;
+};
+
+type DebounceTimestamps = {
+  degradedSinceMs: number | null;
+  statsDegradedSinceMs: number | null;
+  stableSinceMs: number | null;
+};
+
+const EMPTY_DEBOUNCE: DebounceTimestamps = {
+  degradedSinceMs: null,
+  statsDegradedSinceMs: null,
+  stableSinceMs: null,
+};
+
+function mapLiveKitQuality(quality: LKConnectionQuality): ConnectionQuality {
+  switch (quality) {
+    case LKConnectionQuality.Excellent:
+      return 'excellent';
+    case LKConnectionQuality.Good:
+      return 'good';
+    case LKConnectionQuality.Poor:
+      return 'poor';
+    case LKConnectionQuality.Lost:
+      return 'lost';
+    default:
+      return 'unknown';
+  }
+}
+
+function msUntilWarningShow(
+  debounce: DebounceTimestamps,
+  quality: ConnectionQuality,
+  now: number,
+): number | null {
+  const isLiveKitDegraded = isDegradedConnectionQuality(quality);
+  const isStatsDegraded = debounce.statsDegradedSinceMs != null;
+  if (!isLiveKitDegraded && !isStatsDegraded) {
+    return null;
+  }
+  const sinceMs = [
+    isLiveKitDegraded ? debounce.degradedSinceMs : null,
+    isStatsDegraded ? debounce.statsDegradedSinceMs : null,
+  ]
+    .filter((value): value is number => value !== null)
+    .reduce<number | null>(
+      (earliest, value) =>
+        earliest === null ? value : Math.min(earliest, value),
+      null,
+    );
+  if (sinceMs === null) {
+    return null;
+  }
+  return Math.max(0, CONNECTION_QUALITY_SHOW_DELAY_MS - (now - sinceMs));
+}
+
+function applyDegradedTransition(
+  prev: DebounceTimestamps,
+  isDegraded: boolean,
+  key: 'degradedSinceMs' | 'statsDegradedSinceMs',
+  now: number,
+): DebounceTimestamps {
+  if (isDegraded) {
+    if (prev[key] !== null) {
+      return prev;
+    }
+    return { ...prev, [key]: now, stableSinceMs: null };
+  }
+  if (prev[key] === null) {
+    return prev;
+  }
+  return {
+    ...prev,
+    [key]: null,
+    stableSinceMs: prev.stableSinceMs ?? now,
+  };
+}
+
+/**
+ * Tracks local connection quality with debounced warnings for unstable networks.
+ * Must be used within AvatarSession / AvatarCall.
+ */
+export function useConnectionQuality(options?: {
+  debug?: boolean;
+}): UseConnectionQualityReturn {
+  const debug = options?.debug === true;
+  const room = useRoomContext();
+  const connectionState = useConnectionState();
+  const [quality, setQuality] = React.useState<ConnectionQuality>(() =>
+    mapLiveKitQuality(room.localParticipant.connectionQuality),
+  );
+  const [debounce, setDebounce] =
+    React.useState<DebounceTimestamps>(EMPTY_DEBOUNCE);
+  const [statsSnapshot, setStatsSnapshot] = React.useState<{
+    maxRttMs: number | null;
+    maxLossRatio: number | null;
+    tracksSampled: number;
+    lastSampleAt: number | null;
+  }>({
+    maxRttMs: null,
+    maxLossRatio: null,
+    tracksSampled: 0,
+    lastSampleAt: null,
+  });
+  const [debugClock, setDebugClock] = React.useState(() => Date.now());
+
+  const isReconnecting =
+    connectionState === ConnectionState.Reconnecting ||
+    connectionState === ConnectionState.SignalReconnecting;
+
+  React.useEffect(() => {
+    function handleQualityChanged(
+      nextQuality: LKConnectionQuality,
+      participant: Participant,
+    ) {
+      if (!participant.isLocal) {
+        return;
+      }
+      const mapped = mapLiveKitQuality(nextQuality);
+      setQuality(mapped);
+      const now = Date.now();
+      setDebounce((prev) =>
+        applyDegradedTransition(
+          prev,
+          isDegradedConnectionQuality(mapped),
+          'degradedSinceMs',
+          now,
+        ),
+      );
+    }
+
+    room.on(RoomEvent.ConnectionQualityChanged, handleQualityChanged);
+    setQuality(mapLiveKitQuality(room.localParticipant.connectionQuality));
+    return () => {
+      room.off(RoomEvent.ConnectionQualityChanged, handleQualityChanged);
+    };
+  }, [room]);
+
+  React.useEffect(() => {
+    if (connectionState !== ConnectionState.Connected) {
+      setDebounce(EMPTY_DEBOUNCE);
+      setStatsSnapshot({
+        maxRttMs: null,
+        maxLossRatio: null,
+        tracksSampled: 0,
+        lastSampleAt: null,
+      });
+      return;
+    }
+
+    let cancelled = false;
+
+    async function sampleStats() {
+      const tracks: Array<RemoteTrack> = [];
+      for (const participant of room.remoteParticipants.values()) {
+        for (const publication of participant.trackPublications.values()) {
+          if (!publication.isSubscribed) {
+            continue;
+          }
+          const track = publication.track;
+          if (!track || typeof track.getRTCStatsReport !== 'function') {
+            continue;
+          }
+          tracks.push(track);
+        }
+      }
+
+      const reports = await Promise.all(
+        tracks.map((track) => track.getRTCStatsReport()),
+      );
+
+      if (cancelled) {
+        return;
+      }
+
+      let maxRttMs = 0;
+      let maxLossRatio = 0;
+      let stressed = false;
+
+      for (const report of reports) {
+        if (!report) {
+          continue;
+        }
+        const summary = summarizeRtcStats(report);
+        maxRttMs = Math.max(maxRttMs, summary.maxRttMs);
+        maxLossRatio = Math.max(maxLossRatio, summary.maxLossRatio);
+        if (summary.degraded) {
+          stressed = true;
+        }
+      }
+
+      const now = Date.now();
+      setDebounce((prev) =>
+        applyDegradedTransition(
+          prev,
+          stressed,
+          'statsDegradedSinceMs',
+          now,
+        ),
+      );
+      setStatsSnapshot({
+        maxRttMs: tracks.length > 0 ? maxRttMs : null,
+        maxLossRatio: tracks.length > 0 ? maxLossRatio : null,
+        tracksSampled: tracks.length,
+        lastSampleAt: now,
+      });
+    }
+
+    void sampleStats();
+    const id = window.setInterval(() => void sampleStats(), 2000);
+    return () => {
+      cancelled = true;
+      window.clearInterval(id);
+    };
+  }, [room, connectionState]);
+
+  React.useEffect(() => {
+    if (!debug) {
+      return;
+    }
+    const id = window.setInterval(() => setDebugClock(Date.now()), 500);
+    return () => window.clearInterval(id);
+  }, [debug]);
+
+  React.useEffect(() => {
+    const remaining = msUntilWarningShow(debounce, quality, Date.now());
+    if (remaining === null || remaining <= 0) {
+      return;
+    }
+    const id = window.setTimeout(() => {
+      setDebounce((prev) => ({ ...prev }));
+    }, remaining);
+    return () => window.clearTimeout(id);
+  }, [debounce, quality]);
+
+  const statsStressedActive = debounce.statsDegradedSinceMs !== null;
+  const livekitDegraded = isDegradedConnectionQuality(quality);
+
+  const showWarning = isReconnecting
+    ? true
+    : shouldShowConnectionQualityWarning({
+        quality,
+        degradedSinceMs: debounce.degradedSinceMs,
+        statsDegradedSinceMs: debounce.statsDegradedSinceMs,
+        stableSinceMs: debounce.stableSinceMs,
+      });
+
+  const reason: ConnectionQualityWarningReason | null = isReconnecting
+    ? 'reconnecting'
+    : showWarning && (livekitDegraded || statsStressedActive)
+      ? 'degraded'
+      : null;
+
+  const message = showWarning
+    ? connectionQualityWarningMessage(
+        quality,
+        isReconnecting ? 'reconnecting' : undefined,
+        {
+          statsStressed: statsStressedActive && !livekitDegraded,
+        },
+      )
+    : null;
+
+  const diagnostics: ConnectionQualityDiagnostics | null = debug
+    ? {
+        connectionState,
+        quality,
+        showWarning,
+        message,
+        statsStressed: statsStressedActive,
+        livekitDegraded,
+        maxRttMs: statsSnapshot.maxRttMs,
+        maxLossRatio: statsSnapshot.maxLossRatio,
+        tracksSampled: statsSnapshot.tracksSampled,
+        msUntilShow: msUntilWarningShow(debounce, quality, debugClock),
+        lastSampleAt: statsSnapshot.lastSampleAt,
+      }
+    : null;
+
+  return {
+    quality,
+    showWarning,
+    message,
+    reason,
+    diagnostics,
+  };
+}
diff --git a/packages/react/src/index.test.ts b/packages/react/src/index.test.ts
index 0054648..dd66d4f 100644
--- a/packages/react/src/index.test.ts
+++ b/packages/react/src/index.test.ts
@@ -6,6 +6,7 @@ describe('package exports', () => {
     expect(exports.AvatarCall).toBeDefined();
     expect(exports.AvatarSession).toBeDefined();
     expect(exports.AvatarVideo).toBeDefined();
+    expect(exports.ConnectionIndicator).toBeDefined();
     expect(exports.ControlBar).toBeDefined();
     expect(exports.UserVideo).toBeDefined();
     expect(exports.ScreenShareVideo).toBeDefined();
@@ -20,6 +21,9 @@ describe('package exports', () => {
     expect(exports.useLocalMedia).toBeDefined();
     expect(exports.useTranscription).toBeDefined();
     expect(exports.useTranscript).toBeDefined();
+    expect(exports.useConnectionQuality).toBeDefined();
+    expect(exports.useConnectionCheck).toBeDefined();
+    expect(exports.checkAvatarConnection).toBeDefined();
   });
 
   it('exports client event hooks and helpers', async () => {
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index 81c6411..dd9b129 100644
--- a/packages/react/src/index.ts
+++ b/packages/react/src/index.ts
@@ -5,10 +5,22 @@ export { AvatarProvider } from './components/AvatarProvider';
 export { AvatarSession } from './components/AvatarSession';
 export type { AvatarVideoStatus } from './components/AvatarVideo';
 export { AvatarVideo } from './components/AvatarVideo';
+export { ConnectionIndicator } from './components/ConnectionIndicator';
+export type { ConnectionIndicatorProps } from './components/ConnectionIndicator';
+export { ConnectionQualityDevTools } from './components/ConnectionQualityDevTools';
+export type { ConnectionQualityDevToolsProps } from './components/ConnectionQualityDevTools';
 export { ControlBar } from './components/ControlBar';
 export { PageActions } from './components/PageActions';
 export { ScreenShareVideo } from './components/ScreenShareVideo';
 export { UserVideo } from './components/UserVideo';
+export { useConnectionCheck } from './hooks/useConnectionCheck';
+export type { UseConnectionCheckReturn } from './hooks/useConnectionCheck';
+export type {
+  ConnectionQualityDiagnostics,
+  ConnectionQualityWarningReason,
+  UseConnectionQualityReturn,
+} from './hooks/useConnectionQuality';
+export { useConnectionQuality } from './hooks/useConnectionQuality';
 export { useAvatar } from './hooks/useAvatar';
 export { useAvatarSession } from './hooks/useAvatarSession';
 export type { AvatarStatus } from './hooks/useAvatarStatus';
@@ -24,12 +36,17 @@ export { useTranscription } from './hooks/useTranscription';
 
 // Re-export core types and utilities
 export type {
+  AvatarConnectionCheckOptions,
+  AvatarConnectionCheckResult,
   ClientEvent,
   ClientEventFromTool,
   ClientEventHandler,
   ClientEventsFrom,
   ClientToolArgs,
   ClientToolDef,
+  ConnectionCheckStatus,
+  ConnectionCheckStep,
+  ConnectionQuality,
   ConnectResponse,
   InferSchemaInput,
   InferSchemaOutput,
@@ -43,8 +60,11 @@ export type {
   TranscriptionHandler,
 } from '@runwayml/avatars';
 export {
+  checkAvatarConnection,
   clientTool,
+  connectionQualityWarningMessage,
   getClientToolSchema,
+  isDegradedConnectionQuality,
   validateClientToolArgs,
 } from '@runwayml/avatars';
 
diff --git a/packages/react/src/styles.css b/packages/react/src/styles.css
index 7fa58e2..87c84a5 100644
--- a/packages/react/src/styles.css
+++ b/packages/react/src/styles.css
@@ -15,6 +15,16 @@
  */
 
 /* AvatarCall Container - CSS Custom Properties scoped to component */
+/* LiveKit room shell fills the call frame */
+[data-avatar-call] > div {
+  position: relative;
+  flex: 1;
+  min-height: 0;
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+}
+
 [data-avatar-call] {
   /* Customizable variables */
   --avatar-bg-connecting: #1a1a1a;
@@ -101,6 +111,94 @@
   background: transparent;
 }
 
+[data-avatar-session-surface] {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+[data-avatar-connection-overlay] {
+  position: absolute;
+  inset: 0;
+  z-index: 4;
+  pointer-events: none;
+}
+
+[data-avatar-connection-indicator] {
+  position: absolute;
+  top: 12px;
+  left: 12px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  max-width: calc(100% - 24px);
+  padding: 6px 12px;
+  border-radius: 999px;
+  border: 1px solid var(--avatar-screen-share-indicator-border);
+  background: var(--avatar-screen-share-indicator-bg);
+  backdrop-filter: blur(20px);
+  -webkit-backdrop-filter: blur(20px);
+  color: var(--avatar-text-secondary);
+  font-size: 13px;
+  line-height: 18px;
+  pointer-events: none;
+}
+
+[data-avatar-connection-signal] {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  flex-shrink: 0;
+  background: #f5c518;
+  box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.35), 0 0 8px rgba(245, 197, 24, 0.65);
+}
+
+[data-avatar-connection-indicator][data-connection-reason="reconnecting"]
+  [data-avatar-connection-signal] {
+  background: #f59e0b;
+  box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.35), 0 0 8px rgba(245, 158, 11, 0.65);
+}
+
+[data-avatar-connection-debug] {
+  position: absolute;
+  top: 12px;
+  right: 8px;
+  left: auto;
+  max-width: min(240px, calc(100% - 140px));
+  max-height: 28vh;
+  margin: 0;
+  padding: 6px 8px;
+  border-radius: 8px;
+  background: rgba(0, 0, 0, 0.72);
+  color: rgba(255, 255, 255, 0.85);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 10px;
+  line-height: 1.4;
+  white-space: pre-wrap;
+  word-break: break-word;
+  overflow: auto;
+  pointer-events: none;
+}
+
+[data-avatar-connection-preflight] {
+  position: absolute;
+  top: 12px;
+  left: 12px;
+  right: 12px;
+  z-index: 1;
+  margin: 0;
+  padding: 8px 12px;
+  border-radius: 8px;
+  background: rgba(0, 0, 0, 0.55);
+  color: var(--avatar-text-secondary);
+  font-size: 13px;
+  line-height: 18px;
+  text-align: center;
+  pointer-events: none;
+}
+
 /* ControlBar */
 [data-avatar-control-bar] {
   position: absolute;
@@ -114,7 +212,8 @@
   justify-content: center;
   gap: 12px;
   background: linear-gradient(to top, rgba(0, 0, 0, 0.4), transparent);
-  z-index: 2;
+  z-index: 5;
+  pointer-events: auto;
 }
 
 @media (max-width: 480px) {
diff --git a/packages/react/src/types.ts b/packages/react/src/types.ts
index a797e20..348e303 100644
--- a/packages/react/src/types.ts
+++ b/packages/react/src/types.ts
@@ -69,6 +69,17 @@ export interface AvatarCallProps<E extends ClientEvent = ClientEvent>
   extends Omit<React.ComponentPropsWithoutRef<'div'>, 'onError'>,
     Omit<AvatarProviderProps<E>, 'fallback'> {
   avatarImageUrl?: string;
+  /**
+   * Run LiveKit preflight checks in the background after credentials load.
+   * Does not block join or show UI — use `ConnectionIndicator` for in-call warnings.
+   */
+  connectionCheck?: boolean;
+  /**
+   * Live metrics overlay (dev). Prefer `<ConnectionQualityDevTools />` in custom layouts.
+   */
+  connectionDebug?: boolean;
+  /** Force the warning pill visible (UI smoke test; ignores network). */
+  connectionPreviewWarning?: boolean;
 }
 
 export interface UseAvatarReturn {