@decartai/sdk 0.1.5 → 0.1.6

package/README.md

@@ -129,6 +129,70 @@ subscriber.on("connectionChange", (state) => {
 subscriber.disconnect();
 ```
 
+### Connection quality
+
+There are two layers: a **preflight** check before connecting, and an **in-session** quality
+signal while connected. Both report on a shared `"good" | "fair" | "poor" | "critical"` scale —
+the SDK reports, you decide what to do (gate the UI, warn the user, etc.).
+
+**Preflight (before connecting).** A fast, network-only reachability check — it spins up a
+throwaway peer connection against public STUN, so there's no session and no cost:
+
+```typescript
+const { quality, metrics, reasons } = await client.realtime.checkConnectivity();
+// metrics: { transport: "udp" | "relay" | "failed", rttMs }
+if (quality === "critical") showFallbackUI(reasons);
+```
+
+**In-session quality.** While connected, the SDK derives a smoothed verdict from WebRTC stats
+(latency, packet loss, bandwidth headroom, frame rate) and tells you which dimension is the
+bottleneck:
+
+```typescript
+const realtimeClient = await client.realtime.connect(stream, {
+  model,
+  onRemoteStream: (s) => { videoElement.srcObject = s; },
+  onConnectionQuality: ({ quality, limitingFactor, metrics }) => {
+    // limitingFactor: "bandwidth" | "latency" | "loss" | "stall" | "cpu" | "none"
+    // metrics: { rttMs, fps, packetLoss, upstreamJitterMs, availableUpstreamKbps, ... }
+    console.log(quality, limitingFactor);
+  },
+});
+
+// also available as an event and a getter:
+realtimeClient.on("connectionQuality", (report) => { /* ... */ });
+realtimeClient.getConnectionQuality(); // latest report, or null before the first sample
+```
+
+**Glass-to-glass latency (opt-in, diagnostic).** Network RTT hides the dominant cost in
+real-time video — model inference — so a session can read "good" while actually feeling laggy.
+Set `debugQuality: true` to measure the *real* camera→display latency: the SDK stamps a pixel
+marker into each outgoing frame and reads it back off the rendered output, surfacing **startup**
+(`ttffMs`) and **steady-state** (`g2gMs`) latency plus end-to-end frame drops (`g2gDropRatio`).
+When present, glass-to-glass drives the latency verdict instead of RTT.
+
+> ⚠️ Diagnostic only. The marker is **visible** (bottom-left of the published and rendered video)
+> and adds per-frame pixel work — don't enable it for production / end-user sessions.
+
+```typescript
+const realtimeClient = await client.realtime.connect(stream, {
+  model,
+  debugQuality: true,
+  onConnectionQuality: ({ quality, metrics }) => {
+    console.log(metrics.ttffMs, metrics.g2gMs, metrics.g2gDropRatio);
+  },
+});
+```
+
+For a *measured* verdict before connecting (instead of the network-only check), use the **deep
+probe**: it briefly opens a real session with a synthetic source, measures glass-to-glass, then
+tears it down. It requires a `model` and costs a short GPU session:
+
+```typescript
+const probe = await client.realtime.checkConnectivity({ deep: true, model });
+console.log(probe.quality, probe.metrics.g2gMs, probe.metrics.ttffMs);
+```
+
 ### Async Processing (Queue API)
 
 For video generation jobs, use the queue API to submit jobs and poll for results:

package/dist/index.d.ts

@@ -7,11 +7,14 @@ import { ProcessClient } from "./process/client.js";
 import { JobStatus, JobStatusResponse, JobSubmitResponse, QueueJobResult, QueueSubmitAndPollOptions, QueueSubmitOptions } from "./queue/types.js";
 import { QueueClient } from "./queue/client.js";
 import { DecartSDKError, ERROR_CODES } from "./utils/errors.js";
-import { ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, ReconnectEvent, VideoStallEvent } from "./realtime/observability/diagnostics.js";
+import { G2GMetrics } from "./realtime/observability/glass-to-glass.js";
 import { WebRTCStats } from "./realtime/observability/webrtc-stats.js";
+import { ConnectionQuality, ConnectionQualityLimitingFactor, ConnectionQualityMetrics, ConnectionQualityReport } from "./realtime/observability/connection-quality.js";
+import { ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, ReconnectEvent, VideoStallEvent } from "./realtime/observability/diagnostics.js";
 import { ConnectionState, GenerationEndedMessage, QueuePosition, QueuePositionMessage } from "./realtime/types.js";
 import { SetInput } from "./realtime/methods.js";
 import { Events, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState } from "./realtime/client.js";
+import { CheckConnectivityOptions, ConnectivityMetrics, ConnectivityReport, ConnectivityTransport } from "./realtime/preflight.js";
 import { RealTimeSubscribeClient, SubscribeEvents, SubscribeOptions } from "./realtime/subscribe-client.js";
 import { ModelState } from "./shared/types.js";
 import { CreateTokenOptions, CreateTokenResponse, TokensClient } from "./tokens/client.js";
@@ -62,6 +65,29 @@ declare const createDecartClient: (options?: DecartClientOptions) => {
   realtime: {
     connect: (stream: MediaStream | null, options: RealTimeClientConnectOptions) => Promise<RealTimeClient>;
     subscribe: (options: SubscribeOptions) => Promise<RealTimeSubscribeClient>;
+    /**
+     * Check whether the user's network can support a real-time session
+     * *before* connecting — so you can gate showing the integration.
+     *
+     * Default (STUN-only): validates WebRTC reachability (UDP egress / TURN
+     * need) and approximate latency via a throwaway peer connection — no
+     * session, instant. Opt-in deep probe (`{ deep: true, model }`): briefly
+     * opens a real session with a synthetic source and measures *true*
+     * glass-to-glass latency (and end-to-end drops / upstream loss+jitter),
+     * then tears it down — accurate, but costs a short GPU session.
+     *
+     * @example
+     * ```ts
+     * // Fast, pre-session reachability check
+     * const { quality, reasons } = await client.realtime.checkConnectivity();
+     * if (quality === "critical") showFallbackUI(reasons);
+     *
+     * // Accurate, measured glass-to-glass verdict
+     * const probe = await client.realtime.checkConnectivity({ deep: true, model: models.realtime("mirage") });
+     * console.log(probe.metrics.g2gMs);
+     * ```
+     */
+    checkConnectivity: (options?: CheckConnectivityOptions) => Promise<ConnectivityReport>;
   };
   /**
    * Client for synchronous image generation.
@@ -149,4 +175,4 @@ declare const createDecartClient: (options?: DecartClientOptions) => {
   files: FilesClient;
 };
 //#endregion
-export { type CanonicalModel, type ClientSessionConnectionBreakdownEvent, type ClientSessionConnectionBreakdownPhase, type ConnectionState, type CreateTokenOptions, type CreateTokenResponse, type CustomModelDefinition, DecartClientOptions, type DecartSDKError, type DiagnosticEvent, type DiagnosticEventName, type DiagnosticEvents, ERROR_CODES, type FileInput, type FileReference, type FileUploadInput, type FilesClient, type GenerationEndedMessage, type ImageModelDefinition, type ImageModels, type JobStatus, type JobStatusResponse, type JobSubmitResponse, type ListedModelDefinition, type LogLevel, type Logger, type Model, type ModelDefinition, type ModelKind, type ModelState, type ProcessClient, type ProcessOptions, type QueueClient, type QueueJobResult, type QueuePosition, type QueuePositionMessage, type QueueSubmitAndPollOptions, type QueueSubmitOptions, type ReactNativeFile, type RealTimeClient, type RealTimeClientConnectOptions, type RealTimeClientInitialState, type Events as RealTimeEvents, type RealTimeModels, type RealTimeSubscribeClient, type ReconnectEvent, type SetInput, type SubscribeEvents, type SubscribeOptions, type TokensClient, type UploadFileOptions, type VideoModelDefinition, type VideoModels, type VideoStallEvent, type WebRTCStats, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveModelAlias };
+export { type CanonicalModel, type CheckConnectivityOptions, type ClientSessionConnectionBreakdownEvent, type ClientSessionConnectionBreakdownPhase, type ConnectionQuality, type ConnectionQualityLimitingFactor, type ConnectionQualityMetrics, type ConnectionQualityReport, type ConnectionState, type ConnectivityMetrics, type ConnectivityReport, type ConnectivityTransport, type CreateTokenOptions, type CreateTokenResponse, type CustomModelDefinition, DecartClientOptions, type DecartSDKError, type DiagnosticEvent, type DiagnosticEventName, type DiagnosticEvents, ERROR_CODES, type FileInput, type FileReference, type FileUploadInput, type FilesClient, type G2GMetrics, type GenerationEndedMessage, type ImageModelDefinition, type ImageModels, type JobStatus, type JobStatusResponse, type JobSubmitResponse, type ListedModelDefinition, type LogLevel, type Logger, type Model, type ModelDefinition, type ModelKind, type ModelState, type ProcessClient, type ProcessOptions, type QueueClient, type QueueJobResult, type QueuePosition, type QueuePositionMessage, type QueueSubmitAndPollOptions, type QueueSubmitOptions, type ReactNativeFile, type RealTimeClient, type RealTimeClientConnectOptions, type RealTimeClientInitialState, type Events as RealTimeEvents, type RealTimeModels, type RealTimeSubscribeClient, type ReconnectEvent, type SetInput, type SubscribeEvents, type SubscribeOptions, type TokensClient, type UploadFileOptions, type VideoModelDefinition, type VideoModels, type VideoStallEvent, type WebRTCStats, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveModelAlias };

package/dist/index.js

@@ -5,6 +5,7 @@ import { createQueueClient } from "./queue/client.js";
 import { isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, resolveCanonicalModelAlias, resolveModelAlias } from "./shared/model.js";
 import { createConsoleLogger, noopLogger } from "./utils/logger.js";
 import { createRealTimeClient } from "./realtime/client.js";
+import { createPreflight } from "./realtime/preflight.js";
 import { createRealTimeSubscribeClient } from "./realtime/subscribe-client.js";
 import { createTokensClient } from "./tokens/client.js";
 import { readEnv } from "./utils/env.js";
@@ -78,6 +79,10 @@ const createDecartClient = (options = {}) => {
 		integration,
 		logger
 	});
+	const preflight = createPreflight({
+		logger,
+		connect: realtimePublish.connect
+	});
 	const process = createProcessClient({
 		baseUrl,
 		apiKey: apiKey || "",
@@ -101,7 +106,8 @@ const createDecartClient = (options = {}) => {
 	return {
 		realtime: {
 			connect: realtimePublish.connect,
-			subscribe: realtimeSubscribe.subscribe
+			subscribe: realtimeSubscribe.subscribe,
+			checkConnectivity: preflight.checkConnectivity
 		},
 		process,
 		queue,

package/dist/realtime/client.d.ts

@@ -1,7 +1,8 @@
 import { CustomModelDefinition, ModelDefinition } from "../shared/model.js";
 import { DecartSDKError } from "../utils/errors.js";
-import { DiagnosticEvent } from "./observability/diagnostics.js";
 import { WebRTCStats } from "./observability/webrtc-stats.js";
+import { ConnectionQualityReport } from "./observability/connection-quality.js";
+import { DiagnosticEvent } from "./observability/diagnostics.js";
 import { ConnectionState, GenerationEnded, GenerationTick, ImageSetOptions, QueuePosition } from "./types.js";
 import { SetInput } from "./methods.js";
 import { z } from "zod";
@@ -17,6 +18,7 @@ declare const realTimeClientInitialStateSchema: z.ZodObject<{
 }, z.core.$strip>;
 type OnRemoteStreamFn = (stream: MediaStream) => void;
 type OnConnectionChangeFn = (state: ConnectionState) => void;
+type OnConnectionQualityFn = (report: ConnectionQualityReport) => void;
 type OnQueuePositionFn = (queuePosition: QueuePosition) => void;
 type RealTimeClientInitialState = z.infer<typeof realTimeClientInitialStateSchema>;
 declare const realTimeClientConnectOptionsSchema: z.ZodObject<{
@@ -36,6 +38,7 @@ declare const realTimeClientConnectOptionsSchema: z.ZodObject<{
   }, z.core.$strip>;
   onRemoteStream: z.ZodCustom<OnRemoteStreamFn, OnRemoteStreamFn>;
   onConnectionChange: z.ZodOptional<z.ZodCustom<OnConnectionChangeFn, OnConnectionChangeFn>>;
+  onConnectionQuality: z.ZodOptional<z.ZodCustom<OnConnectionQualityFn, OnConnectionQualityFn>>;
   onQueuePosition: z.ZodOptional<z.ZodCustom<OnQueuePositionFn, OnQueuePositionFn>>;
   initialState: z.ZodOptional<z.ZodObject<{
     prompt: z.ZodOptional<z.ZodObject<{
@@ -54,12 +57,14 @@ declare const realTimeClientConnectOptionsSchema: z.ZodObject<{
     h264: "h264";
     vp9: "vp9";
   }>>;
+  debugQuality: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 type RealTimeClientConnectOptions = Omit<z.infer<typeof realTimeClientConnectOptionsSchema>, "model"> & {
   model: ModelDefinition | CustomModelDefinition;
 };
 type Events = {
   connectionChange: ConnectionState;
+  connectionQuality: ConnectionQualityReport;
   queuePosition: QueuePosition;
   error: DecartSDKError;
   generationTick: GenerationTick;
@@ -76,6 +81,8 @@ type RealTimeClient = {
   }) => Promise<void>;
   isConnected: () => boolean;
   getConnectionState: () => ConnectionState;
+  /** Latest interpreted connection-quality verdict, or null before any stats arrive. */
+  getConnectionQuality: () => ConnectionQualityReport | null;
   disconnect: () => void;
   on: <K extends keyof Events>(event: K, listener: (data: Events[K]) => void) => void;
   off: <K extends keyof Events>(event: K, listener: (data: Events[K]) => void) => void;

package/dist/realtime/client.js

@@ -17,12 +17,14 @@ const realTimeClientConnectOptionsSchema = z.object({
 	model: modelDefinitionSchema,
 	onRemoteStream: z.custom((val) => typeof val === "function", { message: "onRemoteStream must be a function" }),
 	onConnectionChange: z.custom((val) => typeof val === "function", { message: "onConnectionChange must be a function" }).optional(),
+	onConnectionQuality: z.custom((val) => typeof val === "function", { message: "onConnectionQuality must be a function" }).optional(),
 	onQueuePosition: z.custom((val) => typeof val === "function", { message: "onQueuePosition must be a function" }).optional(),
 	initialState: realTimeClientInitialStateSchema.optional(),
 	queryParams: z.record(z.string(), z.string()).optional(),
 	mirror: z.union([z.literal("auto"), z.boolean()]).optional(),
 	resolution: z.enum(["720p", "1080p"]).optional(),
-	preferredVideoCodec: z.enum(["h264", "vp9"]).optional()
+	preferredVideoCodec: z.enum(["h264", "vp9"]).optional(),
+	debugQuality: z.boolean().optional()
 });
 const createRealTimeClient = (opts) => {
 	const { baseUrl, apiKey, integration } = opts;
@@ -30,7 +32,7 @@ const createRealTimeClient = (opts) => {
 	const connect = async (stream, options) => {
 		const parsedOptions = realTimeClientConnectOptionsSchema.safeParse(options);
 		if (!parsedOptions.success) throw parsedOptions.error;
-		const { onRemoteStream, onConnectionChange, onQueuePosition, initialState, resolution, preferredVideoCodec } = parsedOptions.data;
+		const { onRemoteStream, onConnectionChange, onConnectionQuality, onQueuePosition, initialState, resolution, preferredVideoCodec } = parsedOptions.data;
 		const mirror = parsedOptions.data.mirror ?? false;
 		let inputStream = stream ?? new MediaStream();
 		let mirroredStream;
@@ -43,6 +45,7 @@ const createRealTimeClient = (opts) => {
 		} catch (error) {
 			logger.warn("Failed to mirror input stream; falling back to un-mirrored input", { error: error instanceof Error ? error.message : String(error) });
 		}
+		const debugQuality = parsedOptions.data.debugQuality ?? false;
 		let session;
 		let observability;
 		try {
@@ -61,14 +64,21 @@ const createRealTimeClient = (opts) => {
 				integration,
 				logger,
 				onDiagnostic: (event) => emitOrBuffer("diagnostic", event),
-				onStats: (stats) => emitOrBuffer("stats", stats)
+				onStats: (stats) => emitOrBuffer("stats", stats),
+				onConnectionQuality: (report) => {
+					emitOrBuffer("connectionQuality", report);
+					onConnectionQuality?.(report);
+				},
+				debugQuality
 			});
+			if (debugQuality) inputStream = observability.attachOutgoingStream(inputStream, resolveFpsNumber(options.model.fps));
 			const safariCodec = isDesktopSafari() ? "vp8" : void 0;
 			const publishCodec = safariCodec ?? preferredVideoCodec;
 			session = new StreamSession({
 				url: `${url}?${new URLSearchParams({
 					...safariCodec ? { livekit_server_codec: safariCodec } : {},
 					...options.queryParams ?? {},
+					...debugQuality ? { pixel_latency: "1" } : {},
 					api_key: apiKey,
 					model: options.model.name,
 					...resolution ? { resolution } : {}
@@ -110,6 +120,7 @@ const createRealTimeClient = (opts) => {
 				...realtimeMethods(activeSession, imageToBase64),
 				isConnected: () => activeSession.isConnected(),
 				getConnectionState: () => activeSession.getConnectionState(),
+				getConnectionQuality: () => observability?.getConnectionQuality() ?? null,
 				disconnect: () => {
 					observability?.stop();
 					stop();

package/dist/realtime/config-realtime.js

@@ -43,7 +43,62 @@ const REALTIME_CONFIG = {
 		statsMinIntervalMs: 500,
 		telemetryReportIntervalMs: 1e4,
 		telemetryUrl: "https://platform.decart.ai/api/v1/telemetry",
-		telemetryMaxItemsPerReport: 120
+		telemetryMaxItemsPerReport: 120,
+		connectionQuality: {
+			windowSamples: 5,
+			warmupSamples: 8,
+			downgradeConsecutive: 5,
+			upgradeConsecutive: 5,
+			rtt: {
+				goodMs: 150,
+				fairMs: 300,
+				poorMs: 500,
+				relayExtraMs: 100
+			},
+			glassToGlass: {
+				goodMs: 500,
+				fairMs: 900,
+				poorMs: 1500
+			},
+			ttff: {
+				goodMs: 4e3,
+				fairMs: 6e3,
+				poorMs: 1e4
+			},
+			loss: {
+				good: .001,
+				fair: .01,
+				poor: .05
+			},
+			g2gDrop: {
+				good: .001,
+				fair: .01,
+				poor: .05
+			},
+			upstream: {
+				goodRatio: 1,
+				fairRatio: .8,
+				poorRatio: .5,
+				requiredUpstreamKbps: 3500
+			},
+			stall: {
+				goodFps: 20,
+				fairFps: 12,
+				poorFps: 5
+			}
+		}
+	},
+	preflight: {
+		defaultStunUrls: ["stun:stun.l.google.com:19302"],
+		iceGatherTimeoutMs: 5e3,
+		rtt: {
+			goodMs: 150,
+			marginalMs: 300
+		},
+		active: {
+			durationMs: 12e3,
+			minSamples: 5
+		}
 	}
 };
 //#endregion

package/dist/realtime/media-channel.js

@@ -42,6 +42,7 @@ var MediaChannel = class {
 			if (track.kind !== Track.Kind.Video && track.kind !== Track.Kind.Audio) return;
 			const mediaStreamTrack = track.mediaStreamTrack;
 			if (mediaStreamTrack) {
+				if (track.kind === Track.Kind.Video) this.config.observability?.attachRemoteVideoTrack(mediaStreamTrack);
 				const tracks = this.remoteStream?.getTracks() ?? [];
 				if (!tracks.includes(mediaStreamTrack)) tracks.push(mediaStreamTrack);
 				this.remoteStream = new MediaStream(tracks);

package/dist/realtime/mirror-stream.js

@@ -12,7 +12,13 @@ function shouldMirrorTrack(track) {
 	}
 	return facingMode === "user";
 }
-function createMirroredStream(input, opts) {
+/**
+* Wrap `input`'s video track so each published frame passes through `transform`.
+* Uses Insertable Streams (frame-accurate) where supported, a canvas
+* `captureStream` pump otherwise. No-ops (returns `input` unchanged) when there
+* is no video track. Audio tracks pass through untouched.
+*/
+function createFrameTransformPump(input, opts) {
 	const [sourceVideo] = input.getVideoTracks();
 	const audioTracks = input.getAudioTracks();
 	if (!sourceVideo) return {
@@ -20,46 +26,53 @@ function createMirroredStream(input, opts) {
 		dispose: () => {},
 		impl: "noop"
 	};
-	if (isMediaStreamTrackProcessorSupported()) return createWithTrackProcessor(sourceVideo, audioTracks);
-	return createWithCanvas(sourceVideo, audioTracks, opts.fps);
+	if (isMediaStreamTrackProcessorSupported()) return createWithTrackProcessor(sourceVideo, audioTracks, opts.transform);
+	return createWithCanvas(sourceVideo, audioTracks, opts.fps, opts.transform);
+}
+function createMirroredStream(input, opts) {
+	return createFrameTransformPump(input, {
+		fps: opts.fps,
+		transform: (ctx, source, w, h) => {
+			ctx.save();
+			ctx.setTransform(-1, 0, 0, 1, w, 0);
+			ctx.drawImage(source, 0, 0, w, h);
+			ctx.restore();
+		}
+	});
 }
-function createWithTrackProcessor(sourceVideo, audioTracks) {
+function createWithTrackProcessor(sourceVideo, audioTracks, transform) {
 	const Processor = globalThis.MediaStreamTrackProcessor;
 	const Generator = globalThis.MediaStreamTrackGenerator;
-	if (!new OffscreenCanvas(1, 1).getContext("2d")) throw new Error("createMirroredStream: OffscreenCanvas 2D context unavailable");
+	if (!new OffscreenCanvas(1, 1).getContext("2d")) throw new Error("createFrameTransformPump: OffscreenCanvas 2D context unavailable");
 	const processor = new Processor({ track: sourceVideo });
 	const generator = new Generator({ kind: "video" });
 	let canvas = new OffscreenCanvas(1, 1);
 	let ctx = canvas.getContext("2d");
-	const transform = new TransformStream({ transform(frame, controller) {
+	const pipeline = new TransformStream({ transform(frame, controller) {
 		const w = frame.displayWidth;
 		const h = frame.displayHeight;
 		if (canvas.width !== w || canvas.height !== h) {
 			canvas = new OffscreenCanvas(w, h);
 			ctx = canvas.getContext("2d");
 		}
-		let flipped;
+		let out;
 		try {
-			ctx.save();
-			ctx.setTransform(-1, 0, 0, 1, w, 0);
-			ctx.drawImage(frame, 0, 0, w, h);
-			ctx.restore();
-			flipped = new VideoFrame(canvas, {
+			transform(ctx, frame, w, h);
+			out = new VideoFrame(canvas, {
 				timestamp: frame.timestamp,
 				alpha: "discard"
 			});
-			controller.enqueue(flipped);
-			flipped = void 0;
+			controller.enqueue(out);
+			out = void 0;
 		} finally {
-			flipped?.close();
+			out?.close();
 			frame.close();
 		}
 	} });
-	processor.readable.pipeThrough(transform).pipeTo(generator.writable).catch(() => {});
-	const stream = new MediaStream([generator, ...audioTracks]);
+	processor.readable.pipeThrough(pipeline).pipeTo(generator.writable).catch(() => {});
 	let disposed = false;
 	return {
-		stream,
+		stream: new MediaStream([generator, ...audioTracks]),
 		impl: "track-processor",
 		dispose: () => {
 			if (disposed) return;
@@ -68,14 +81,14 @@ function createWithTrackProcessor(sourceVideo, audioTracks) {
 		}
 	};
 }
-function createWithCanvas(sourceVideo, audioTracks, fps) {
-	if (typeof document === "undefined") throw new Error("createMirroredStream requires a DOM environment (document is undefined)");
+function createWithCanvas(sourceVideo, audioTracks, fps, transform) {
+	if (typeof document === "undefined") throw new Error("createFrameTransformPump requires a DOM environment (document is undefined)");
 	const canvas = document.createElement("canvas");
 	const ctx = canvas.getContext("2d");
-	if (!ctx) throw new Error("createMirroredStream: 2D canvas context unavailable");
-	if (typeof canvas.captureStream !== "function") throw new Error("createMirroredStream: canvas.captureStream unavailable");
-	const [flippedTrack] = canvas.captureStream(fps).getVideoTracks();
-	if (!flippedTrack) throw new Error("createMirroredStream: canvas.captureStream produced no video track");
+	if (!ctx) throw new Error("createFrameTransformPump: 2D canvas context unavailable");
+	if (typeof canvas.captureStream !== "function") throw new Error("createFrameTransformPump: canvas.captureStream unavailable");
+	const [outTrack] = canvas.captureStream(fps).getVideoTracks();
+	if (!outTrack) throw new Error("createFrameTransformPump: canvas.captureStream produced no video track");
 	const video = document.createElement("video");
 	video.muted = true;
 	video.playsInline = true;
@@ -90,26 +103,23 @@ function createWithCanvas(sourceVideo, audioTracks, fps) {
 		if (w > 0 && h > 0) {
 			if (canvas.width !== w) canvas.width = w;
 			if (canvas.height !== h) canvas.height = h;
-			ctx.save();
-			ctx.setTransform(-1, 0, 0, 1, w, 0);
-			ctx.drawImage(video, 0, 0, w, h);
-			ctx.restore();
+			transform(ctx, video, w, h);
 		}
 		rafHandle = requestAnimationFrame(draw);
 	};
 	video.play().catch(() => {});
 	rafHandle = requestAnimationFrame(draw);
 	return {
-		stream: new MediaStream([flippedTrack, ...audioTracks]),
+		stream: new MediaStream([outTrack, ...audioTracks]),
 		impl: "canvas",
 		dispose: () => {
 			if (disposed) return;
 			disposed = true;
 			if (rafHandle !== null) cancelAnimationFrame(rafHandle);
-			flippedTrack.stop();
+			outTrack.stop();
 			video.srcObject = null;
 		}
 	};
 }
 //#endregion
-export { createMirroredStream, shouldMirrorTrack };
+export { createFrameTransformPump, createMirroredStream, shouldMirrorTrack };

package/dist/realtime/observability/connection-quality.d.ts

@@ -0,0 +1,54 @@
+//#region src/realtime/observability/connection-quality.d.ts
+/**
+ * Smoothed verdict on whether the connection is good enough for the realtime
+ * pipeline, derived from the raw `WebRTCStats` the SDK already collects.
+ *
+ * Note: the bandwidth dimension relies on Chromium-only stats
+ * (`availableOutgoingBitrate`), so on Safari/Firefox the verdict reflects
+ * latency, loss, and fps only.
+ */
+type ConnectionQuality = "good" | "fair" | "poor" | "critical";
+/** Which dimension pulled the verdict down to its current level. */
+type ConnectionQualityLimitingFactor = "bandwidth" | "latency" | "loss" | "stall" | "cpu" | "none";
+/** Human-meaningful numbers behind the verdict; the full raw stats are on the `stats` event. */
+type ConnectionQualityMetrics = {
+  /** Round-trip time in ms, or null until measured. */
+  rttMs: number | null;
+  /**
+   * Mid-stream (steady-state) glass-to-glass latency (ms) — the real per-frame
+   * camera→display latency through the model, excluding startup. Only populated
+   * when the opt-in pixel-marker measurement is on (`connect({ debugQuality: true })`)
+   * and past warm-up; null otherwise. When present it drives the latency verdict
+   * instead of `rttMs`.
+   */
+  g2gMs: number | null;
+  /**
+   * Time-to-first-frame (ms) — startup latency from connect to the first rendered
+   * model frame. One-shot; populated under g2g measurement once the first frame
+   * arrives. Surfaced for visibility; does not drive the live verdict (it's
+   * historical by the time a verdict exists).
+   */
+  ttffMs: number | null;
+  /** Rendered (inbound) frames per second, or null until measured. */
+  fps: number | null;
+  /** Fraction (0–1) of our outbound packets the server reports lost, or null until measured. */
+  packetLoss: number | null;
+  /** Server's view of upstream (client→server) jitter in ms, or null. Observational. */
+  upstreamJitterMs: number | null;
+  /**
+   * End-to-end frame drop ratio (0–1) inferred from the pixel-marker seq stream.
+   * Only populated under the opt-in g2g measurement; null otherwise.
+   */
+  g2gDropRatio: number | null;
+  /** Estimated available upstream bandwidth in kbps. Chromium-only — null on Safari/Firefox. */
+  availableUpstreamKbps: number | null;
+};
+type ConnectionQualityReport = {
+  quality: ConnectionQuality;
+  limitingFactor: ConnectionQualityLimitingFactor;
+  /** True while the connection ramps; the verdict is provisional. */
+  warmingUp: boolean;
+  metrics: ConnectionQualityMetrics;
+};
+//#endregion
+export { ConnectionQuality, ConnectionQualityLimitingFactor, ConnectionQualityMetrics, ConnectionQualityReport };