@q9labsai/chalk-react-native 4.0.0

package/src/space-client/create-native-space-client.ts

@@ -0,0 +1,280 @@
+import {
+  AsyncStorageV1PendingTargetStore,
+  CloudflareSFUClient,
+  createChalkChatFileHttpTransport,
+  createChalkWhiteboardV1Client,
+  createChalkWhiteboardV1FileHttpTransport,
+  createCloudflareSFUHTTPTransport,
+  createReactNativeSyncLifecycle,
+  createReactNativeWebSocketFactory,
+  createV1SyncClient,
+  type DiagnosticObservation,
+  type GetAccess,
+  type ReactNativeWebSocket,
+  type ReactNativeWebSocketConstructor,
+  type ReactNativeAsyncStorage,
+} from "@q9labsai/chalk-client";
+import { createSpaceClientForPlatform, type SpaceClientPlatform } from "@q9labsai/chalk-client/effect";
+import type { SpaceClient } from "@q9labsai/chalk-client";
+import { RTCPeerConnection, mediaDevices } from "@cloudflare/react-native-webrtc";
+import { AppState } from "react-native";
+
+import { authenticatedNativeCredential, bindNativeAuthenticatedTelemetry, createTelemetry, registerNativeJourneyContext, syncTransportCloseDiagnostic, type RtcPeerConnection, type TelemetryJourney } from "../telemetry";
+
+type PlatformDependencies = NonNullable<SpaceClientPlatform["dependencies"]>;
+type MediaFactoryInput = Parameters<NonNullable<PlatformDependencies["createMediaClient"]>>[0];
+type SyncFactoryInput = Parameters<NonNullable<PlatformDependencies["createSyncClient"]>>[0];
+type ChatFileFactoryInput = Parameters<NonNullable<PlatformDependencies["createChatFileTransport"]>>[0];
+type WhiteboardFactoryInput = Parameters<NonNullable<PlatformDependencies["createWhiteboardClient"]>>[0];
+
+export type NativeSpaceClientOptions = {
+  readonly space: string;
+  readonly getAccess: GetAccess;
+  readonly baseUrl?: string;
+  readonly syncUrl?: string;
+  readonly whiteboardURL?: string | null;
+  readonly microphone?: boolean;
+  readonly camera?: boolean;
+  readonly syncStartupTimeoutMs?: number;
+  readonly storage?: ReactNativeAsyncStorage;
+  readonly telemetry?: TelemetryJourney;
+};
+
+export function createNativeSpaceClient(options: NativeSpaceClientOptions): SpaceClient {
+  const { storage, telemetry: journey } = options;
+  const apiBaseURL = options.baseUrl ?? "https://api.chalkmeet.com";
+  const syncURL = options.syncUrl ?? defaultSyncURL(apiBaseURL);
+  const telemetry = journey ? createTelemetry(journey) : undefined;
+  const fetch = telemetryFetch(journey);
+  const lifecycle = createReactNativeSyncLifecycle({ appState: AppState });
+  const webSocket = createReactNativeWebSocketFactory(nativeWebSocketConstructor(journey));
+  const dependencies: PlatformDependencies = {
+    clock: {
+      now: () => Date.now(),
+      setTimeout: (callback, milliseconds) => globalThis.setTimeout(callback, milliseconds),
+      clearTimeout: (handle) => globalThis.clearTimeout(handle as ReturnType<typeof globalThis.setTimeout>),
+    },
+    mediaDevices: {
+      getUserMedia: async (constraints) => (await mediaDevices.getUserMedia(constraints)) as unknown as globalThis.MediaStream,
+      getDisplayMedia: async () => (await mediaDevices.getDisplayMedia()) as unknown as globalThis.MediaStream,
+    },
+    createMediaClient: (input) => createMediaClient(apiBaseURL, input, fetch, telemetry?.observePeerConnection, journey),
+    createSyncClient: (input) => createSyncClient(syncURL, input, lifecycle, webSocket, storage),
+    createChatFileTransport: (input) => createChatFileTransport(apiBaseURL, input, fetch),
+    createWhiteboardClient: options.whiteboardURL === null ? undefined : (input) => createWhiteboardClient(apiBaseURL, options.whiteboardURL ?? whiteboardURL(syncURL), input, fetch, lifecycle, webSocket),
+    subscribeForeground: (listener) => {
+      const subscription = AppState.addEventListener("change", (state) => {
+        if (state === "active") listener();
+      });
+      return () => subscription.remove();
+    },
+  };
+
+  const client = createSpaceClientForPlatform(
+    { space: options.space, getAccess: options.getAccess, baseUrl: apiBaseURL },
+    {
+      apiBaseUrl: apiBaseURL,
+      syncUrl: syncURL,
+      whiteboardUrl: options.whiteboardURL,
+      telemetry: journey?.context,
+      dependencies,
+      fetch,
+      syncStartupTimeoutMs: options.syncStartupTimeoutMs ?? 30_000,
+      initialMicrophoneEnabled: options.microphone,
+      initialCameraEnabled: options.camera,
+      onConnectionDiagnostic: (event) => journey?.recordDiagnostic(connectionDiagnostic(event)),
+    },
+  );
+  bindNativeAuthenticatedTelemetry(client, journey);
+  registerNativeJourneyContext(client, journey, telemetry);
+  return client;
+}
+
+type PlatformDiagnostic = Parameters<NonNullable<SpaceClientPlatform["onConnectionDiagnostic"]>>[0];
+
+function connectionDiagnostic(event: PlatformDiagnostic): DiagnosticObservation {
+  if (event.event === "space_join_span" && event.step && event.spanId && event.outcome) {
+    return {
+      category: "connection",
+      code: `space.join.${event.step}.${event.outcome}`,
+      phase: joinTracePhase(event.step),
+      state: event.outcome === "succeeded" ? "succeeded" : event.outcome === "failed" ? "failed" : "observed",
+      ...(event.durationMs === undefined ? {} : { metricValue: event.durationMs }),
+      attributes: {
+        span_id: event.spanId,
+        ...(event.parentSpanId ? { parent_span_id: event.parentSpanId } : {}),
+        step: event.step,
+        outcome: event.outcome,
+        epoch: event.epoch,
+        ...(event.code ? { failure_code: event.code } : {}),
+      },
+    };
+  }
+  return {
+    category: "connection",
+    code: event.event,
+    phase: event.state === "joining" ? "signaling" : event.state === "leaving" || event.state === "left" ? "terminal" : "recovery",
+    state: event.event.endsWith("_failed") || event.event.endsWith("_exhausted") ? "failed" : "observed",
+  };
+}
+
+function joinTracePhase(step: NonNullable<PlatformDiagnostic["step"]>): "authentication" | "signaling" | "media" | "recovery" {
+  switch (step) {
+    case "acquire_initial_media":
+    case "create_media_client":
+    case "start_media":
+      return "media";
+    default:
+      return "signaling";
+  }
+}
+
+function createMediaClient(apiBaseURL: string, input: MediaFactoryInput, fetch: typeof globalThis.fetch, observePeerConnection: ((peerConnection: RtcPeerConnection) => () => void) | undefined, journey: TelemetryJourney | undefined) {
+  const { subject } = input.access;
+  return new CloudflareSFUClient({
+    bootstrap: input.access.media.clientPayload,
+    participantId: subject.participantId,
+    transport: createCloudflareSFUHTTPTransport({
+      apiBaseURL,
+      credential: () => authenticatedNativeCredential(input.credential, journey),
+      tenantId: subject.tenantId,
+      spaceId: subject.spaceId,
+      episodeId: subject.episodeId,
+      participantId: subject.participantId,
+      fetch,
+    }),
+    peerConnectionFactory: (configuration) => {
+      const connection = new RTCPeerConnection(configuration);
+      observePeerConnection?.(connection as unknown as RtcPeerConnection);
+      return connection as unknown as globalThis.RTCPeerConnection;
+    },
+    onError: input.onFailure,
+    onScreenEnded: input.onScreenEnded,
+  });
+}
+
+function createSyncClient(syncURL: string, input: SyncFactoryInput, lifecycle: ReturnType<typeof createReactNativeSyncLifecycle>, webSocket: ReturnType<typeof createReactNativeWebSocketFactory>, storage: ReactNativeAsyncStorage | undefined) {
+  const subject = input.access.subject;
+  const scope = `${subject.tenantId}:${subject.episodeId}:${subject.participantId}`;
+  return createV1SyncClient({
+    url: syncURL,
+    token: input.token,
+    mediaPlane: input.media,
+    lifecycle,
+    webSocket,
+    telemetry: input.telemetry,
+    ...(storage ? { pendingStore: new AsyncStorageV1PendingTargetStore({ scope, storage }) } : {}),
+  });
+}
+
+function createChatFileTransport(apiBaseURL: string, input: ChatFileFactoryInput, fetch: typeof globalThis.fetch) {
+  return createChalkChatFileHttpTransport({ baseUrl: apiBaseURL, token: input.token, fetch });
+}
+
+function createWhiteboardClient(apiBaseURL: string, url: string, input: WhiteboardFactoryInput, fetch: typeof globalThis.fetch, lifecycle: ReturnType<typeof createReactNativeSyncLifecycle>, webSocket: ReturnType<typeof createReactNativeWebSocketFactory>) {
+  let sceneId: string | null = null;
+  const files = createChalkWhiteboardV1FileHttpTransport({
+    baseUrl: apiBaseURL,
+    token: input.token,
+    sceneId: () => {
+      if (sceneId === null) throw new TypeError("Whiteboard scene is not ready");
+      return sceneId;
+    },
+    fetch,
+  });
+  return createChalkWhiteboardV1Client({
+    url,
+    token: input.token,
+    files,
+    lifecycle,
+    webSocket,
+    onSummary: (summary) => {
+      sceneId = summary.sceneId;
+      input.onSummary(summary);
+    },
+  });
+}
+
+function telemetryFetch(journey: TelemetryJourney | undefined): typeof globalThis.fetch {
+  if (!journey) return globalThis.fetch;
+  return (input, init) => {
+    const headers = new Headers(init?.headers);
+    for (const [name, value] of Object.entries(journey.headers)) headers.set(name, value);
+    return globalThis.fetch(input, { ...init, headers });
+  };
+}
+
+function nativeWebSocketConstructor(journey: TelemetryJourney | undefined): ReactNativeWebSocketConstructor {
+  const RuntimeWebSocket = globalThis.WebSocket as unknown as new (url: string, protocols?: string | string[], options?: { readonly headers?: Readonly<Record<string, string>> }) => ReactNativeWebSocket;
+
+  return class ChalkNativeWebSocket implements ReactNativeWebSocket {
+    onopen: ((event: unknown) => void) | null = null;
+    onmessage: ((event: { readonly data: unknown }) => void) | null = null;
+    onclose: ((event: { readonly code?: unknown; readonly reason?: unknown }) => void) | null = null;
+    onerror: ((event: unknown) => void) | null = null;
+    readonly #socket: ReactNativeWebSocket;
+
+    constructor(url: string) {
+      this.#socket = new RuntimeWebSocket(url, undefined, journey ? { headers: journey.headers } : undefined);
+      this.#socket.onopen = (event) => this.onopen?.(event);
+      this.#socket.onmessage = (event) => {
+        recordSyncFrame(journey, "server_to_client", event.data);
+        this.onmessage?.(event);
+      };
+      this.#socket.onclose = (event) => {
+        recordSyncTransportClose(journey, event);
+        this.onclose?.(event);
+      };
+      this.#socket.onerror = (event) => {
+        journey?.recordDiagnostic({ category: "network", code: "sync_websocket_error", phase: "signaling", state: "failed" });
+        this.onerror?.(event);
+      };
+    }
+
+    send(data: string): void {
+      recordSyncFrame(journey, "client_to_server", data);
+      this.#socket.send(data);
+    }
+
+    close(code?: number, reason?: string): void {
+      this.#socket.close(code, reason);
+    }
+  };
+}
+
+function recordSyncTransportClose(journey: TelemetryJourney | undefined, event: { readonly code?: unknown; readonly reason?: unknown }): void {
+  if (!journey) return;
+  journey.recordDiagnostic(syncTransportCloseDiagnostic(event));
+}
+
+function recordSyncFrame(journey: TelemetryJourney | undefined, direction: "client_to_server" | "server_to_client", data: unknown): void {
+  if (!journey) return;
+  let frameType = "binary";
+  if (typeof data === "string") {
+    try {
+      const frame = JSON.parse(data) as { readonly type?: unknown };
+      frameType = typeof frame.type === "string" ? frame.type : "unknown";
+    } catch {
+      frameType = "invalid_json";
+    }
+  }
+  journey.recordSyncFrame({ direction, frameType });
+}
+
+function whiteboardURL(syncURL: string): string {
+  const url = new URL(syncURL);
+  url.pathname = "/v1/whiteboard";
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+
+function defaultSyncURL(apiBaseURL: string): string {
+  const url = new URL(apiBaseURL);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  if (url.hostname.startsWith("api.")) url.hostname = `sync.${url.hostname.slice(4)}`;
+  url.pathname = "/v1/sync";
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}

package/src/telemetry.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it, vi } from "vitest";
+import { createTelemetry, getNativeJourneyContext, registerNativeJourneyContext, syncTransportCloseDiagnostic, type RtcPeerConnection, type TelemetryJourney } from "./telemetry";
+
+describe("createTelemetry", () => {
+  it("bounds Sync transport close diagnostics without recording raw reasons", () => {
+    expect(syncTransportCloseDiagnostic({ code: 1008, reason: "invalid token" })).toEqual({
+      category: "network",
+      code: "sync_websocket_closed_1008_invalid_token",
+      phase: "signaling",
+      state: "failed",
+    });
+    expect(syncTransportCloseDiagnostic({ code: 1008, reason: "secret detail" }).code).toBe("sync_websocket_closed_1008_other");
+    expect(syncTransportCloseDiagnostic({ code: 1000, reason: "" }).state).toBe("observed");
+  });
+
+  it("propagates one journey through API and sync transport configuration", () => {
+    const journey = createJourney();
+    const telemetry = createTelemetry(journey);
+
+    expect(telemetry.connection).toEqual({
+      apiHeaders: journey.headers,
+      context: journey.context,
+      syncCorrelation: {
+        journey_id: journey.context.journeyId,
+        traceparent: journey.context.traceparent,
+        tracestate: journey.context.tracestate,
+      },
+    });
+
+    telemetry.recordSyncFrame({ direction: "client_to_server", frameType: "space.join" });
+    expect(journey.recordSyncFrame).toHaveBeenCalledWith({ direction: "client_to_server", frameType: "space.join" });
+  });
+
+  it("records production whiteboard metrics without forwarding renderer attributes", () => {
+    const journey = createJourney();
+    const telemetry = createTelemetry(journey);
+
+    telemetry.recordWhiteboardMetric({
+      name: "whiteboard.renderer.termination",
+      value: 1,
+      attributes: { renderer_generation: "private-cardinality-value" },
+    });
+
+    expect(journey.recordDiagnostic).toHaveBeenCalledWith({
+      category: "whiteboard_renderer",
+      code: "whiteboard.renderer.termination",
+      metricValue: 1,
+      phase: "media",
+      state: "failed",
+    });
+  });
+
+  it("keeps the native client journey seam private and exact-client scoped", () => {
+    const journey = createJourney();
+    const telemetry = createTelemetry(journey);
+    const client = {};
+    registerNativeJourneyContext(client, journey, telemetry);
+
+    expect(getNativeJourneyContext(client)).toMatchObject({
+      journeyId: journey.context.journeyId,
+      traceparent: journey.context.traceparent,
+      tracestate: journey.context.tracestate,
+    });
+    getNativeJourneyContext(client)?.recordWhiteboardMetric({ name: "whiteboard.renderer.ready", value: 1 });
+    expect(journey.recordDiagnostic).toHaveBeenCalledWith({
+      category: "whiteboard_renderer",
+      code: "whiteboard.renderer.ready",
+      metricValue: 1,
+      phase: "media",
+      state: "observed",
+    });
+    expect(getNativeJourneyContext({})).toBeUndefined();
+  });
+
+  it("records aggregate RTC summaries from native peer-connection stats", async () => {
+    const journey = createJourney();
+    const telemetry = createTelemetry(journey);
+    const peerConnection = createPeerConnection();
+    const stop = telemetry.observePeerConnection(peerConnection);
+
+    peerConnection.connectionState = "connected";
+    peerConnection.emit("connectionstatechange");
+
+    await vi.waitFor(() => expect(journey.recordRtcSummary).toHaveBeenCalled());
+    expect(journey.recordRtcSummary).toHaveBeenLastCalledWith({ connectionState: "connected", iceConnectionState: "completed", signalingState: "stable" }, [
+      { type: "inbound-rtp", bytesReceived: 1200, packetsLost: 2 },
+      { type: "candidate-pair", roundTripTime: 0.03 },
+    ]);
+
+    stop();
+    peerConnection.emit("iceconnectionstatechange");
+    expect(journey.recordRtcSummary).toHaveBeenCalledTimes(2);
+  });
+});
+
+function createJourney(): TelemetryJourney & {
+  recordDiagnostic: ReturnType<typeof vi.fn>;
+  recordRtcSummary: ReturnType<typeof vi.fn>;
+  recordSyncFrame: ReturnType<typeof vi.fn>;
+} {
+  return {
+    context: {
+      journeyId: "00000000-0000-4000-8000-000000000001",
+      rootJourneyId: "00000000-0000-4000-8000-000000000001",
+      traceparent: "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+      tracestate: "chalk=mobile",
+    },
+    headers: {
+      "x-chalk-journey-id": "00000000-0000-4000-8000-000000000001",
+      traceparent: "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+    },
+    recordDiagnostic: vi.fn(),
+    recordRtcSummary: vi.fn(),
+    recordSyncFrame: vi.fn(),
+  };
+}
+
+function createPeerConnection(): RtcPeerConnection & { emit(event: "connectionstatechange" | "iceconnectionstatechange" | "signalingstatechange"): void; connectionState: string } {
+  const listeners = new Map<string, Set<() => void>>();
+
+  return {
+    connectionState: "connecting",
+    iceConnectionState: "completed",
+    signalingState: "stable",
+    addEventListener(event, listener) {
+      const eventListeners = listeners.get(event) ?? new Set();
+      eventListeners.add(listener);
+      listeners.set(event, eventListeners);
+    },
+    removeEventListener(event, listener) {
+      listeners.get(event)?.delete(listener);
+    },
+    async getStats() {
+      return new Map([
+        ["inbound", { type: "inbound-rtp", bytesReceived: 1200, packetsLost: 2 }],
+        ["pair", { type: "candidate-pair", roundTripTime: 0.03 }],
+      ]);
+    },
+    emit(event) {
+      for (const listener of listeners.get(event) ?? []) listener();
+    },
+  };
+}

package/src/telemetry.ts

@@ -0,0 +1,234 @@
+import { syncTelemetryCorrelation, type DiagnosticObservation, type JourneyTelemetryContext, type RtcConnectionStateSnapshot, type RtcStatsLike, type SyncFrameObservation } from "@q9labsai/chalk-client/telemetry";
+
+export interface TelemetryJourney {
+  readonly context: JourneyTelemetryContext;
+  readonly headers: Readonly<Record<string, string>>;
+  /** Internal native bridge; callers must not inspect or derive media credentials. */
+  readonly setAuthenticatedTelemetryHeaders?: (headers: Readonly<Record<string, string>> | undefined) => void;
+  recordDiagnostic(observation: DiagnosticObservation): unknown;
+  recordRtcSummary(connection: RtcConnectionStateSnapshot, stats: Iterable<RtcStatsLike>): unknown;
+  recordSyncFrame(observation: SyncFrameObservation): unknown;
+}
+
+export interface WhiteboardMetric {
+  readonly name: string;
+  readonly value: number;
+  readonly attributes?: Readonly<Record<string, string | number | boolean>>;
+}
+
+export interface ConnectionTelemetry {
+  readonly apiHeaders: Readonly<Record<string, string>>;
+  readonly context: JourneyTelemetryContext;
+  readonly syncCorrelation: ReturnType<typeof syncTelemetryCorrelation>;
+}
+
+export interface RtcPeerConnection {
+  readonly connectionState?: string;
+  readonly iceConnectionState?: string;
+  readonly signalingState?: string;
+  addEventListener(type: NativeRtcStateEvent, listener: () => void): void;
+  getStats(): Promise<unknown>;
+  removeEventListener(type: NativeRtcStateEvent, listener: () => void): void;
+}
+
+type NativeRtcStateEvent = "connectionstatechange" | "iceconnectionstatechange" | "signalingstatechange";
+
+const rtcStateEvents: readonly NativeRtcStateEvent[] = ["connectionstatechange", "iceconnectionstatechange", "signalingstatechange"];
+
+export interface Telemetry {
+  readonly connection: ConnectionTelemetry;
+  observePeerConnection(peerConnection: RtcPeerConnection): () => void;
+  recordSyncFrame(observation: SyncFrameObservation): void;
+  recordWhiteboardMetric(metric: WhiteboardMetric): void;
+}
+
+export interface NativeJourneyContext {
+  readonly journeyId: string;
+  readonly traceparent: string;
+  readonly tracestate?: string;
+  readonly recordWhiteboardMetric: (metric: WhiteboardMetric) => void;
+}
+
+const nativeJourneyContexts = new WeakMap<object, NativeJourneyContext>();
+
+type NativeTelemetryClient = {
+  readonly getSnapshot: () => { readonly connection: { readonly status: string } };
+  readonly subscribe: (listener: () => void) => () => void;
+  readonly dispose: () => void;
+};
+
+export async function authenticatedNativeCredential(credential: () => Promise<string>, journey: TelemetryJourney | undefined): Promise<string> {
+  const value = await credential();
+  try {
+    journey?.setAuthenticatedTelemetryHeaders?.({ Authorization: `Bearer ${value}` });
+  } catch {
+    // Telemetry exporters cannot interrupt an authenticated media request.
+  }
+  return value;
+}
+
+/** Binds authenticated-header cleanup to the private native client's terminal lifecycle. */
+export function bindNativeAuthenticatedTelemetry(client: NativeTelemetryClient, journey: TelemetryJourney | undefined): void {
+  const setHeaders = journey?.setAuthenticatedTelemetryHeaders;
+  if (!setHeaders) return;
+
+  const clear = () => {
+    try {
+      setHeaders(undefined);
+    } catch {
+      // Telemetry exporters cannot interrupt client teardown.
+    }
+  };
+  const onSnapshot = () => {
+    const status = client.getSnapshot().connection.status;
+    if (status === "idle" || status === "failed" || status === "left") clear();
+  };
+  const unsubscribe = client.subscribe(onSnapshot);
+  let disposed = false;
+  const originalDispose = client.dispose;
+  (client as NativeTelemetryClient & { dispose: () => void }).dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    clear();
+    unsubscribe();
+    originalDispose();
+  };
+}
+
+export function registerNativeJourneyContext(client: object, journey: TelemetryJourney | undefined, telemetry: Telemetry | undefined): void {
+  if (!journey || !telemetry) return;
+  nativeJourneyContexts.set(client, {
+    journeyId: journey.context.journeyId,
+    traceparent: journey.context.traceparent,
+    ...(journey.context.tracestate ? { tracestate: journey.context.tracestate } : {}),
+    recordWhiteboardMetric: telemetry.recordWhiteboardMetric,
+  });
+}
+
+export function getNativeJourneyContext(client: object): NativeJourneyContext | undefined {
+  return nativeJourneyContexts.get(client);
+}
+
+/** Connects a typed journey to native API, WebSocket, and WebRTC boundaries without collecting raw media or network data. */
+export function createTelemetry(journey: TelemetryJourney): Telemetry {
+  const connection: ConnectionTelemetry = {
+    apiHeaders: journey.headers,
+    context: journey.context,
+    syncCorrelation: syncTelemetryCorrelation(journey.context),
+  };
+
+  return {
+    connection,
+    observePeerConnection(peerConnection) {
+      return observeNativeRtc(peerConnection, journey);
+    },
+    recordSyncFrame(observation) {
+      journey.recordSyncFrame(observation);
+    },
+    recordWhiteboardMetric(metric) {
+      journey.recordDiagnostic({
+        category: "whiteboard_renderer",
+        code: metric.name,
+        metricValue: metric.value,
+        phase: "media",
+        state: isFailedWhiteboardMetric(metric.name) ? "failed" : "observed",
+      });
+    },
+  };
+}
+
+export function syncTransportCloseDiagnostic(event: { readonly code?: unknown; readonly reason?: unknown }): DiagnosticObservation {
+  const code = typeof event.code === "number" ? event.code : null;
+  const reason = typeof event.reason === "string" ? event.reason : "";
+  return {
+    category: "network",
+    code: code === null ? "sync_websocket_closed_unknown" : `sync_websocket_closed_${code}_${syncCloseReason(reason)}`,
+    phase: "signaling",
+    state: code === 1000 ? "observed" : "failed",
+  };
+}
+
+function syncCloseReason(reason: string): string {
+  switch (reason) {
+    case "authentication failed":
+    case "heartbeat timeout":
+    case "hello timeout":
+    case "invalid token":
+    case "policy violation":
+    case "space actions unsupported":
+    case "text frames only":
+    case "transport error":
+      return reason.replaceAll(" ", "_");
+    default:
+      return reason ? "other" : "none";
+  }
+}
+
+function isFailedWhiteboardMetric(name: string): boolean {
+  return name.endsWith(".failure") || name.endsWith(".termination");
+}
+
+function observeNativeRtc(peerConnection: RtcPeerConnection, journey: TelemetryJourney): () => void {
+  let disposed = false;
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    for (const event of rtcStateEvents) peerConnection.removeEventListener(event, capture);
+  };
+  const capture = () => {
+    void peerConnection
+      .getStats()
+      .then((stats) => journey.recordRtcSummary(rtcConnectionState(peerConnection), rtcStats(stats)))
+      .catch(() => undefined);
+    if (peerConnection.connectionState === "closed") dispose();
+  };
+
+  for (const event of rtcStateEvents) peerConnection.addEventListener(event, capture);
+  capture();
+
+  return dispose;
+}
+
+function rtcConnectionState(peerConnection: RtcPeerConnection): RtcConnectionStateSnapshot {
+  return {
+    connectionState: peerConnection.connectionState,
+    iceConnectionState: peerConnection.iceConnectionState,
+    signalingState: peerConnection.signalingState,
+  };
+}
+
+function rtcStats(stats: unknown): readonly RtcStatsLike[] {
+  if (Array.isArray(stats)) return stats.filter(isRtcStatsLike);
+  if (isIterable(stats)) return Array.from(stats, statsValue).filter(isRtcStatsLike);
+  if (hasForEach(stats)) return forEachStats(stats);
+  if (isObject(stats)) return Object.values(stats).filter(isRtcStatsLike);
+  return [];
+}
+
+function isIterable(value: unknown): value is Iterable<unknown> {
+  return isObject(value) && Symbol.iterator in value;
+}
+
+function hasForEach(value: unknown): value is { forEach(callback: (entry: unknown) => void): void } {
+  return isObject(value) && "forEach" in value && typeof value.forEach === "function";
+}
+
+function forEachStats(stats: { forEach(callback: (entry: unknown) => void): void }): RtcStatsLike[] {
+  const entries: RtcStatsLike[] = [];
+  stats.forEach((entry) => {
+    if (isRtcStatsLike(entry)) entries.push(entry);
+  });
+  return entries;
+}
+
+function statsValue(entry: unknown): unknown {
+  return Array.isArray(entry) ? entry[1] : entry;
+}
+
+function isRtcStatsLike(value: unknown): value is RtcStatsLike {
+  return isObject(value) && typeof value.type === "string";
+}
+
+function isObject(value: unknown): value is Record<PropertyKey, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/test-support/test-renderer.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from "vitest";
+
+import { renderHook } from "./test-renderer";
+
+describe("test renderer", () => {
+  it("loads the workspace renderHook harness", () => {
+    expect(renderHook).toBeTypeOf("function");
+  });
+});

package/src/test-support/test-renderer.ts

@@ -0,0 +1,26 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import type { ComponentType, ReactNode } from "react";
+
+type RenderHookOptions<Props> = {
+  readonly initialProps?: Props;
+  readonly wrapper?: ComponentType<{ readonly children?: ReactNode }>;
+};
+
+type RenderHookResult<Result, Props> = {
+  readonly result: { readonly current: Result };
+  readonly rerender: (props?: Props) => void;
+  readonly unmount: () => void;
+};
+
+type RenderHook = <Result, Props = undefined>(callback: (props: Props) => Result, options?: RenderHookOptions<Props>) => RenderHookResult<Result, Props>;
+type Act = (callback: () => void | Promise<void>) => void | Promise<void>;
+type WaitFor = (callback: () => void | Promise<void>) => Promise<void>;
+
+const testingLibrary = createRequire(import.meta.url)(join(process.cwd(), "../react/node_modules", "@" + "testing-library", "react")) as {
+  readonly act: Act;
+  readonly renderHook: RenderHook;
+  readonly waitFor: WaitFor;
+};
+
+export const { act, renderHook, waitFor } = testingLibrary;