@q9labsai/chalk-react-native 4.0.0

package/src/components/native-space-view/useSpaceViewPanels.controlled.test.ts

@@ -0,0 +1,40 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it, vi } from "vitest";
+
+import { act, renderHook } from "../../test-support/test-renderer";
+
+const alert = vi.hoisted(() => ({ alert: vi.fn() }));
+
+vi.mock("react-native", () => ({ Alert: alert, Share: { share: vi.fn(async () => undefined) } }));
+
+import { useSpaceViewPanels } from "./useSpaceViewPanels";
+
+describe("controlled Space view fixture state", () => {
+  it("updates production panel and whiteboard state without remounting the hook", () => {
+    const base = {
+      canWhiteboard: true,
+      canDraw: true,
+      canClear: false,
+      canEndEpisode: false,
+      transport: null,
+      onLeave: vi.fn(),
+      onEndEpisode: undefined,
+      run: vi.fn(async (action: () => void | Promise<void>) => {
+        await action();
+      }),
+    };
+    const { result, rerender } = renderHook(({ state }) => useSpaceViewPanels({ ...base, controlledState: state }), { initialProps: { state: { layout: "grid" as const, panel: null, settingsOpen: false, whiteboardOpen: false } } });
+
+    expect(result.current.layout.layout).toBe("grid");
+    expect(result.current.panel).toBeNull();
+    expect(result.current.whiteboard.isOpen).toBe(false);
+
+    act(() => rerender({ state: { layout: "presentation", panel: "participants", settingsOpen: true, whiteboardOpen: true } }));
+
+    expect(result.current.layout.layout).toBe("presentation");
+    expect(result.current.panel).toBe("participants");
+    expect(result.current.settingsOpen).toBe(true);
+    expect(result.current.whiteboard.isOpen).toBe(true);
+  });
+});

package/src/components/native-space-view/useSpaceViewPanels.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it, vi } from "vitest";
+
+const alert = vi.hoisted(() => ({ alert: vi.fn() }));
+
+vi.mock("react", () => ({
+  useCallback: <T>(callback: T) => callback,
+  useEffect: () => undefined,
+  useMemo: <T>(factory: () => T) => factory(),
+  useRef: <T>(current: T) => ({ current }),
+  useState: <T>(initial: T): readonly [T, (next: T) => void] => [initial, vi.fn()],
+}));
+vi.mock("react-native", () => ({ Alert: alert, Share: { share: vi.fn(async () => undefined) } }));
+vi.mock("../../hooks/useLayout", () => ({
+  useLayout: () => ({ layout: "grid", isMobileView: true, isFullscreen: false, setLayout: vi.fn(), toggleLayout: vi.fn(), toggleFullscreen: vi.fn(async () => undefined) }),
+}));
+
+import { useSpaceViewPanels } from "./useSpaceViewPanels";
+
+describe("useSpaceViewPanels", () => {
+  it("composes layout, panel state, whiteboard state, and leave actions", () => {
+    const panels = useSpaceViewPanels({
+      spaceName: "Space",
+      inviteLink: "https://example.test/space",
+      canWhiteboard: true,
+      canDraw: true,
+      canClear: false,
+      canEndEpisode: true,
+      transport: null,
+      onLeave: vi.fn(),
+      onEndEpisode: vi.fn(),
+      run: vi.fn(async (action) => {
+        await action();
+      }),
+    });
+
+    expect(panels).toMatchObject({ layout: { layout: "grid" }, panel: null, formattedDuration: "0:00", whiteboard: { isOpen: false, canDraw: true } });
+    expect(panels.whiteboard.journeyId).toMatch(/^native-whiteboard-|^[0-9a-f-]{36}$/u);
+    expect(panels.whiteboard.onMetric).toBeUndefined();
+    panels.openPanel("participants");
+    expect(panels.openPanel).toBeTypeOf("function");
+    panels.handleLeave();
+    expect(alert.alert).toHaveBeenCalledWith("Leave Space?", "Choose how you want to leave.", expect.any(Array));
+  });
+
+  it("forwards registered W3C journey context to the whiteboard surface", () => {
+    const onMetric = vi.fn();
+    const panels = useSpaceViewPanels({
+      canWhiteboard: true,
+      canDraw: true,
+      canClear: false,
+      canEndEpisode: false,
+      transport: null,
+      onLeave: vi.fn(),
+      onEndEpisode: undefined,
+      run: vi.fn(async (action) => {
+        await action();
+      }),
+      journeyContext: {
+        journeyId: "00000000-0000-4000-8000-000000000001",
+        traceparent: "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+        tracestate: "chalk=mobile",
+        recordWhiteboardMetric: onMetric,
+      },
+    });
+
+    expect(panels.whiteboard).toMatchObject({
+      journeyId: "00000000-0000-4000-8000-000000000001",
+      traceparent: "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+      tracestate: "chalk=mobile",
+      onMetric,
+    });
+  });
+});

package/src/components/native-space-view/useSpaceViewPanels.ts

@@ -0,0 +1,170 @@
+import type { ChalkWhiteboardV1Transport } from "@q9labsai/chalk-client";
+import { useCallback, useEffect, useMemo, useRef, useState, type Dispatch, type SetStateAction } from "react";
+import { Alert, type AlertButton, Share } from "react-native";
+
+import { useLayout, type UseLayoutReturn } from "../../hooks/useLayout";
+import type { NativeJourneyContext, WhiteboardMetric } from "../../telemetry";
+import type { SpaceViewProps } from "../SpaceView";
+import { formatSpaceDuration } from "./format-space-duration";
+import type { SpaceViewActionRunner, SpacePanelName } from "./types";
+
+const emptyElements: readonly unknown[] = Object.freeze([]);
+const emptyParticipants: readonly string[] = Object.freeze([]);
+
+export interface SpaceWhiteboardState {
+  readonly isOpen: boolean;
+  readonly canDraw: boolean;
+  readonly canClear: boolean;
+  readonly elements: readonly unknown[];
+  readonly openParticipants: readonly string[];
+  readonly transport: ChalkWhiteboardV1Transport | null;
+  readonly journeyId: string;
+  readonly traceparent?: string;
+  readonly tracestate?: string;
+  readonly onMetric?: (metric: WhiteboardMetric) => void;
+  readonly open: () => void;
+  readonly close: () => void;
+  readonly toggle: () => void;
+  readonly requestSync: () => void;
+  readonly clear: () => void;
+}
+
+export interface SpaceViewPanels {
+  readonly layout: UseLayoutReturn;
+  readonly panel: SpacePanelName | null;
+  readonly secondsElapsed: number;
+  readonly formattedDuration: string;
+  readonly actionsOpen: boolean;
+  readonly reactionPickerOpen: boolean;
+  readonly settingsOpen: boolean;
+  readonly whiteboard: SpaceWhiteboardState;
+  readonly setActionsOpen: Dispatch<SetStateAction<boolean>>;
+  readonly setReactionPickerOpen: Dispatch<SetStateAction<boolean>>;
+  readonly handleLeave: () => void;
+  readonly openPanel: (nextPanel: SpacePanelName) => void;
+  readonly closePanel: () => void;
+  readonly handleInviteParticipants: () => void;
+}
+
+interface UseSpaceViewPanelsOptions {
+  readonly spaceName?: string;
+  readonly inviteLink?: string;
+  readonly layout?: SpaceViewProps["layout"];
+  readonly onLayoutChange?: SpaceViewProps["onLayoutChange"];
+  readonly canWhiteboard: boolean;
+  readonly canDraw: boolean;
+  readonly canClear: boolean;
+  readonly canEndEpisode: boolean;
+  readonly transport: ChalkWhiteboardV1Transport | null;
+  readonly onLeave: SpaceViewProps["onLeave"];
+  readonly onEndEpisode: SpaceViewProps["onEndEpisode"];
+  readonly run: SpaceViewActionRunner;
+  readonly journeyContext?: NativeJourneyContext;
+  /** Test-fixture state only; SpaceView does not expose controlled panel state publicly. */
+  readonly initialState?: SpaceViewFixtureState;
+  /** Test-fixture state only; SpaceView does not expose controlled panel state publicly. */
+  readonly controlledState?: SpaceViewFixtureState;
+}
+
+type SpaceViewFixtureState = {
+  readonly layout?: SpaceViewProps["layout"];
+  readonly panel?: SpacePanelName | null;
+  readonly actionsOpen?: boolean;
+  readonly reactionPickerOpen?: boolean;
+  readonly settingsOpen?: boolean;
+  readonly durationSeconds?: number;
+  readonly whiteboardOpen?: boolean;
+};
+
+export function useSpaceViewPanels({ spaceName, inviteLink, layout: controlledLayout, onLayoutChange, canWhiteboard, canDraw, canClear, canEndEpisode, transport, onLeave, onEndEpisode, run, journeyContext, initialState, controlledState }: UseSpaceViewPanelsOptions): SpaceViewPanels {
+  const fixtureLayout = controlledState?.layout ?? initialState?.layout ?? controlledLayout;
+  const layout = useLayout({ layout: fixtureLayout, onLayoutChange });
+  const [panel, setPanel] = useState<SpacePanelName | null>(initialState?.panel ?? null);
+  const [actionsOpen, setActionsOpen] = useState(initialState?.actionsOpen ?? false);
+  const [reactionPickerOpen, setReactionPickerOpen] = useState(initialState?.reactionPickerOpen ?? false);
+  const [secondsElapsed, setSecondsElapsed] = useState(0);
+  const [settingsOpen, setSettingsOpen] = useState(initialState?.settingsOpen ?? false);
+  const [whiteboardOpen, setWhiteboardOpen] = useState(initialState?.whiteboardOpen ?? false);
+  const generatedJourneyId = useRef(globalThis.crypto?.randomUUID?.() ?? `native-whiteboard-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+
+  useEffect(() => {
+    const durationSeconds = Math.max(0, Math.floor(controlledState?.durationSeconds ?? initialState?.durationSeconds ?? 0));
+    const startedAt = Date.now() - durationSeconds * 1_000;
+    const update = () => setSecondsElapsed(Math.max(0, Math.floor((Date.now() - startedAt) / 1_000)));
+    update();
+    const timer = globalThis.setInterval(update, 1_000);
+    return () => globalThis.clearInterval(timer);
+  }, [controlledState?.durationSeconds, initialState?.durationSeconds]);
+
+  useEffect(() => {
+    if (controlledState?.panel !== undefined) setPanel(controlledState.panel ?? null);
+    if (controlledState?.actionsOpen !== undefined) setActionsOpen(controlledState.actionsOpen);
+    if (controlledState?.reactionPickerOpen !== undefined) setReactionPickerOpen(controlledState.reactionPickerOpen);
+    if (controlledState?.settingsOpen !== undefined) setSettingsOpen(controlledState.settingsOpen);
+    if (controlledState?.whiteboardOpen !== undefined) setWhiteboardOpen(controlledState.whiteboardOpen);
+  }, [controlledState]);
+
+  const whiteboard = useMemo<SpaceWhiteboardState>(
+    () => ({
+      isOpen: canWhiteboard && whiteboardOpen,
+      canDraw: canWhiteboard && canDraw,
+      canClear: canWhiteboard && canClear,
+      elements: emptyElements,
+      openParticipants: emptyParticipants,
+      transport,
+      journeyId: journeyContext?.journeyId ?? generatedJourneyId.current,
+      ...(journeyContext?.traceparent ? { traceparent: journeyContext.traceparent } : {}),
+      ...(journeyContext?.tracestate ? { tracestate: journeyContext.tracestate } : {}),
+      ...(journeyContext ? { onMetric: journeyContext.recordWhiteboardMetric } : {}),
+      open: () => canWhiteboard && setWhiteboardOpen(true),
+      close: () => setWhiteboardOpen(false),
+      toggle: () => canWhiteboard && setWhiteboardOpen((value) => !value),
+      requestSync: () => void run(() => transport?.requestSnapshot()),
+      clear: () => void run(() => transport?.clear()),
+    }),
+    [canClear, canDraw, canWhiteboard, journeyContext, run, transport, whiteboardOpen],
+  );
+
+  const handleLeave = useCallback(() => {
+    const buttons: AlertButton[] = [
+      { text: "Cancel", style: "cancel" },
+      { text: "Leave", style: "destructive", onPress: () => void run(onLeave) },
+    ];
+    if (canEndEpisode && onEndEpisode) {
+      buttons.splice(1, 0, {
+        text: "End for All",
+        style: "destructive",
+        onPress: () => void run(onEndEpisode),
+      });
+    }
+    Alert.alert("Leave Space?", "Choose how you want to leave.", buttons);
+  }, [canEndEpisode, onEndEpisode, onLeave, run]);
+
+  const handleInviteParticipants = useCallback(() => {
+    void run(async () => {
+      if (!inviteLink) throw new Error("The Space invite is not ready yet.");
+      await Share.share({ message: inviteLink, title: spaceName || "Chalk Space", url: inviteLink });
+    });
+  }, [inviteLink, run, spaceName]);
+
+  return {
+    layout,
+    panel,
+    secondsElapsed,
+    formattedDuration: formatSpaceDuration(secondsElapsed),
+    actionsOpen,
+    reactionPickerOpen,
+    whiteboard,
+    settingsOpen,
+    setActionsOpen,
+    setReactionPickerOpen,
+    handleLeave,
+    openPanel: (nextPanel: SpacePanelName) => {
+      setActionsOpen(false);
+      if (nextPanel === "whiteboard") whiteboard.open();
+      else setPanel(nextPanel);
+    },
+    closePanel: () => setPanel(null),
+    handleInviteParticipants,
+  };
+}

package/src/components/rtc-video-view-availability.ts

@@ -0,0 +1,16 @@
+import type { ComponentType } from "react";
+import type { StyleProp, ViewProps, ViewStyle } from "react-native";
+
+export interface RtcVideoViewProps extends ViewProps {
+  streamURL: string;
+  mirror?: boolean;
+  objectFit?: "cover" | "contain";
+  zOrder?: number;
+  style?: StyleProp<ViewStyle>;
+}
+
+type RtcVideoViewComponent = ComponentType<RtcVideoViewProps>;
+
+export function canRenderRtcVideoView(component: unknown): component is RtcVideoViewComponent {
+  return typeof component === "function" || (typeof component === "object" && component !== null);
+}

package/src/components/space-lifecycle.test.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import { describe, expect, it } from "vitest";
+
+describe("SpaceLifecyclePhase", () => {
+  it("keeps the exported source contract on the canonical native phases", () => {
+    const sourcePath = fileURLToPath(new URL("./space-lifecycle.ts", import.meta.url));
+    const sourceFile = ts.createSourceFile("space-lifecycle.ts", readFileSync(sourcePath, "utf8"), ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const declaration = sourceFile.statements.find((statement): statement is ts.TypeAliasDeclaration => ts.isTypeAliasDeclaration(statement) && statement.name.text === "SpaceLifecyclePhase");
+
+    expect(declaration).toBeDefined();
+    if (!declaration || !ts.isUnionTypeNode(declaration.type)) throw new Error("SpaceLifecyclePhase must remain an exported string union.");
+
+    expect(declaration.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)).toBe(true);
+    const phases = declaration.type.types.map((member) => (ts.isLiteralTypeNode(member) && ts.isStringLiteral(member.literal) ? member.literal.text : "<invalid>"));
+    expect(phases).toEqual(["entrance", "joining", "live", "left"]);
+  });
+});

package/src/components/space-lifecycle.ts

@@ -0,0 +1,2 @@
+/** Lifecycle phases used by native operating-system call integrations. */
+export type SpaceLifecyclePhase = "entrance" | "joining" | "live" | "left";

package/src/components/useAndroidConnectionService.ts

@@ -0,0 +1,55 @@
+import { useMemo, useSyncExternalStore } from "react";
+import { Platform } from "react-native";
+import { addAndroidConnectionServiceListener, endAndroidConnectionServiceCall, ensureAndroidConnectionServiceRegistered, setAndroidConnectionServiceActive, startAndroidConnectionServiceCall } from "../android/connection-service";
+import { AndroidConnectionServiceController } from "./android-connection-service-controller";
+import type { SpaceLifecyclePhase } from "./space-lifecycle";
+
+interface UseAndroidConnectionServiceOptions {
+  displayName: string;
+  enabled: boolean;
+  hasVideo: boolean;
+  joinNonce: number;
+  onDisconnectRequest: () => void;
+  phase: SpaceLifecyclePhase;
+  spaceId: string;
+  spaceName: string;
+}
+
+export function useAndroidConnectionService({ displayName, enabled, hasVideo, joinNonce, onDisconnectRequest, phase, spaceId, spaceName }: UseAndroidConnectionServiceOptions): void {
+  const isEnabled = enabled && Platform.OS === "android";
+  const controller = useMemo(
+    () =>
+      new AndroidConnectionServiceController(
+        {
+          displayName,
+          enabled: isEnabled,
+          hasVideo,
+          joinNonce,
+          onDisconnectRequest,
+          phase,
+          spaceId,
+          spaceName,
+        },
+        {
+          addListener: addAndroidConnectionServiceListener,
+          endCall: endAndroidConnectionServiceCall,
+          ensureRegistered: ensureAndroidConnectionServiceRegistered,
+          setActive: setAndroidConnectionServiceActive,
+          startCall: startAndroidConnectionServiceCall,
+        },
+      ),
+    [],
+  );
+
+  controller.update({
+    displayName,
+    enabled: isEnabled,
+    hasVideo,
+    joinNonce,
+    onDisconnectRequest,
+    phase,
+    spaceId,
+    spaceName,
+  });
+  useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+}

package/src/context/space-client-context.test.tsx

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+
+import { ChalkProvider, useSpaceClient } from "./space-client-context";
+
+describe("ChalkProvider", () => {
+  it("provides the canonical SpaceClient context entry", () => {
+    expect(ChalkProvider).toBeTypeOf("function");
+    expect(useSpaceClient).toBeTypeOf("function");
+  });
+});

package/src/context/space-client-context.tsx

@@ -0,0 +1,21 @@
+import type { SpaceClient } from "@q9labsai/chalk-client";
+import type { ReactNode } from "react";
+import { createContext, useContext, useMemo } from "react";
+
+export type ChalkProviderProps = {
+  readonly children: ReactNode;
+  readonly client: SpaceClient;
+};
+
+const SpaceClientContext = createContext<SpaceClient | null>(null);
+
+export function ChalkProvider({ children, client }: ChalkProviderProps): React.JSX.Element {
+  const value = useMemo(() => client, [client]);
+  return <SpaceClientContext.Provider value={value}>{children}</SpaceClientContext.Provider>;
+}
+
+export function useSpaceClient(): SpaceClient {
+  const client = useContext(SpaceClientContext);
+  if (!client) throw new Error("Chalk hooks must be used within a ChalkProvider.");
+  return client;
+}

package/src/diagnostics.test.ts

@@ -0,0 +1,29 @@
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { buildDevDiagnosticsCopyText, classifyTarget, getDevDiagnosticsState, recordDiagnosticsFailure, resetDevDiagnosticsState, setDevDiagnosticsEnvironment } from "./diagnostics";
+
+describe("native diagnostics", () => {
+  beforeEach(resetDevDiagnosticsState);
+
+  it("does not retain caller credentials", () => {
+    expect(buildDevDiagnosticsCopyText()).not.toContain("inviteToken");
+  });
+
+  it("uses the broker as the single environment boundary", () => {
+    setDevDiagnosticsEnvironment({
+      brokerUrl: "http://localhost:8787/local-chalk",
+    });
+    expect(getDevDiagnosticsState().environment.target).toBe("local");
+    expect(classifyTarget("https://chalkmeet.com/local-chalk")).toBe("production");
+  });
+
+  it("records failures without legacy auth or transport state", () => {
+    recordDiagnosticsFailure("connection-join", "Sync unavailable");
+    expect(getDevDiagnosticsState().lastFailure).toMatchObject({
+      source: "connection-join",
+      message: "Sync unavailable",
+    });
+    expect(buildDevDiagnosticsCopyText()).not.toContain("apiKey");
+    expect(buildDevDiagnosticsCopyText()).not.toContain("RealtimeKit");
+  });
+});

package/src/diagnostics.ts

@@ -0,0 +1,187 @@
+import type { ConnectionSlice } from "@q9labsai/chalk-client";
+import type { DeviceInfo } from "./runtime";
+
+export type ConnectionDiagnosticsSnapshot = Pick<ConnectionSlice, "status" | "lastError">;
+
+export type DevDiagnosticsOutcome = "error" | "observed" | "success";
+
+export interface DevDiagnosticsTimelineEntry {
+  readonly id: string;
+  readonly timestamp: string;
+  readonly eventType: string;
+  readonly outcome: DevDiagnosticsOutcome;
+  readonly title: string;
+  readonly detail?: string;
+}
+
+export interface DevDiagnosticsState {
+  readonly enabled: boolean;
+  readonly environment: {
+    readonly buildProfile: string | null;
+    readonly brokerUrl: string | null;
+    readonly target: "custom" | "local" | "production" | "unknown";
+    readonly routeKind: string | null;
+    readonly routeSpaceId: string | null;
+    readonly routeSource: string | null;
+  };
+  readonly device: DeviceInfo | null;
+  readonly connection: ConnectionDiagnosticsSnapshot | null;
+  readonly lastFailure: {
+    readonly source: string;
+    readonly message: string;
+    readonly occurredAt: string;
+  } | null;
+  readonly timeline: readonly DevDiagnosticsTimelineEntry[];
+}
+
+const runtimeEnv = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;
+const isDevelopmentRuntime = typeof __DEV__ !== "undefined" ? __DEV__ : runtimeEnv?.VITEST === "true" || runtimeEnv?.NODE_ENV !== "production";
+const maximumTimelineItems = 120;
+const listeners = new Set<() => void>();
+let state = initialState();
+
+export function classifyTarget(brokerUrl: string | null | undefined): DevDiagnosticsState["environment"]["target"] {
+  if (!brokerUrl) return "unknown";
+  try {
+    const hostname = new URL(brokerUrl).hostname;
+    if (["localhost", "127.0.0.1", "0.0.0.0"].includes(hostname)) return "local";
+    if (hostname === "chalkmeet.com" || hostname.endsWith(".chalkmeet.com")) return "production";
+    return "custom";
+  } catch {
+    return "unknown";
+  }
+}
+
+export function resolveDevDiagnosticsMode({ isDevRuntime, brokerUrl }: { readonly isDevRuntime: boolean; readonly brokerUrl: string | null | undefined }): {
+  readonly enabled: boolean;
+  readonly buildProfile: "development" | "production";
+} {
+  return {
+    enabled: isDevRuntime,
+    buildProfile: isDevRuntime || classifyTarget(brokerUrl) === "local" ? "development" : "production",
+  };
+}
+
+export function subscribeDevDiagnostics(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function getDevDiagnosticsState(): DevDiagnosticsState {
+  return state;
+}
+
+export function setDevDiagnosticsEnvironment(next: Partial<DevDiagnosticsState["environment"]>): void {
+  update((current) => ({
+    ...current,
+    environment: {
+      ...current.environment,
+      ...next,
+      target: next.brokerUrl ? classifyTarget(next.brokerUrl) : current.environment.target,
+    },
+  }));
+}
+
+export function setDevDiagnosticsDevice(device: DeviceInfo | null): void {
+  update((current) => ({
+    ...current,
+    device,
+  }));
+}
+
+export function setDevDiagnosticsConnection(snapshot: ConnectionDiagnosticsSnapshot | null): void {
+  const previous = state.connection;
+  update((current) => ({ ...current, connection: snapshot }));
+  if (snapshot && snapshot.status !== previous?.status) {
+    appendTimeline({
+      eventType: "connection.state",
+      outcome: snapshot.lastError ? "error" : "observed",
+      title: snapshot.status,
+      ...(snapshot.lastError?.message ? { detail: snapshot.lastError.message } : {}),
+    });
+  }
+}
+
+export function recordDevDiagnosticsLifecycleEvent(eventType: string, title: string, detail?: string): void {
+  appendTimeline({ eventType, title, outcome: "observed", ...(detail ? { detail } : {}) });
+}
+
+export function recordDiagnosticsFailure(source: string, message: string): void {
+  const occurredAt = new Date().toISOString();
+  update((current) => ({
+    ...current,
+    lastFailure: { source, message, occurredAt },
+  }));
+  appendTimeline({
+    eventType: source,
+    outcome: "error",
+    title: source.replaceAll("-", " "),
+    detail: message,
+    timestamp: occurredAt,
+  });
+}
+
+export function clearDevDiagnosticsLogs(): void {
+  update((current) => ({ ...current, lastFailure: null, timeline: [] }));
+}
+
+export function resetDevDiagnosticsState(): void {
+  state = initialState();
+  emit();
+}
+
+export function buildDevDiagnosticsCopyText(): string {
+  return JSON.stringify(
+    {
+      generatedAt: new Date().toISOString(),
+      ...state,
+    },
+    null,
+    2,
+  );
+}
+
+function initialState(): DevDiagnosticsState {
+  return {
+    enabled: isDevelopmentRuntime,
+    environment: {
+      buildProfile: null,
+      brokerUrl: null,
+      target: "unknown",
+      routeKind: null,
+      routeSpaceId: null,
+      routeSource: null,
+    },
+    device: null,
+    connection: null,
+    lastFailure: null,
+    timeline: [],
+  };
+}
+
+function appendTimeline(
+  input: Omit<DevDiagnosticsTimelineEntry, "id" | "timestamp"> & {
+    readonly timestamp?: string;
+  },
+): void {
+  const timestamp = input.timestamp ?? new Date().toISOString();
+  const entry: DevDiagnosticsTimelineEntry = {
+    ...input,
+    id: `${input.eventType}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    timestamp,
+  };
+  update((current) => ({
+    ...current,
+    timeline: [entry, ...current.timeline].slice(0, maximumTimelineItems),
+  }));
+}
+
+function update(updater: (current: DevDiagnosticsState) => DevDiagnosticsState): void {
+  if (!isDevelopmentRuntime) return;
+  state = updater(state);
+  emit();
+}
+
+function emit(): void {
+  for (const listener of listeners) listener();
+}