@copilotkit/web-inspector 1.57.1 → 1.57.3

package/src/index.ts

@@ -47,6 +47,15 @@ import {
   isValidDockMode,
 } from "./lib/persistence";
 import type { PersistedState } from "./lib/persistence";
+import {
+  TELEMETRY_DOCS_URL,
+  ensureTelemetryDistinctId,
+  getTelemetryDistinctIdForUrl,
+  maybeShowDisclosure,
+  trackBannerClicked,
+  trackBannerViewed,
+  trackThreadsTabClicked,
+} from "./lib/telemetry";
 
 export const WEB_INSPECTOR_TAG = "cpk-web-inspector" as const;
 
@@ -57,7 +66,8 @@ type MenuKey =
   | "agents"
   | "frontend-tools"
   | "agent-context"
-  | "threads";
+  | "threads"
+  | "settings";
 
 type MenuItem = {
   key: MenuKey;
@@ -2408,11 +2418,32 @@ export class WebInspectorElement extends LitElement {
   private announcementHtml: string | null = null;
   private announcementTimestamp: string | null = null;
   private announcementPreviewText: string | null = null;
+  // Forward-compat for an optional `cta_label` field on the announcement
+  // CDN payload (e.g. "Try threads", "New feature"). The current schema
+  // ({timestamp, previewText, announcement}) doesn't carry it, so this is
+  // null in production today; we read it defensively in fetchAnnouncement
+  // so a future CDN-side schema bump lights up `cta_label` on banner_clicked
+  // without an inspector release.
+  private announcementCtaLabel: string | null = null;
   private hasUnseenAnnouncement = false;
   private announcementLoaded = false;
   private announcementPromise: Promise<void> | null = null;
   private showAnnouncementPreview = true;
   private announcementExpanded = false;
+  // Per-instance dedup for `oss.inspector.banner_viewed` so the event fires
+  // at most once per announcement timestamp per inspector mount. Plan calls
+  // for "de-dup per timestamp per session"; instance-scoping is closer
+  // to per-mount than per-tab (sessionStorage), but for the inspector the
+  // distinction is academic — inspector instances rarely outlive the page.
+  private viewedBannerTimestamps: Set<string> = new Set();
+  private pendingBannerViewed: {
+    banner_id: string;
+    cta_label?: string;
+  } | null = null;
+  // Per-instance dedup for `oss.inspector.banner_clicked` (keyed by
+  // `${bannerId}:${cta}`) so copy-button retries and accidental multi-clicks
+  // don't inflate funnel counts beyond one signal per intent type per banner.
+  private clickedBannerIds: Set<string> = new Set();
 
   get core(): CopilotKitCore | null {
     return this._core;
@@ -2603,6 +2634,11 @@ export class WebInspectorElement extends LitElement {
       onRuntimeConnectionStatusChanged: ({ status }) => {
         this.runtimeStatus = status;
         if (status === "connected") {
+          if (!core.telemetryDisabled) {
+            ensureTelemetryDistinctId();
+            maybeShowDisclosure();
+          }
+          this.flushPendingBannerViewed();
           for (const agentId of this._ownedThreadStores.keys()) {
             this.refreshOwnedThreadStore(agentId);
           }
@@ -3913,6 +3949,11 @@ ${argsString}</pre
         color: #010507;
         font-weight: 600;
       }
+      .cpk-tab-icon {
+        display: inline-flex;
+        flex-shrink: 0;
+        align-items: center;
+      }
       .cpk-tab-active .cpk-tab-icon {
         color: #757cf2;
       }
@@ -4337,6 +4378,24 @@ ${argsString}</pre
                 <div class="min-w-[160px] max-w-xs">${agentSelector}</div>
                 <div class="flex items-center gap-1">
                   ${this.renderDockControls()}
+                  <button
+                    class="flex h-8 w-8 items-center justify-center rounded-md transition hover:bg-gray-100 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-gray-400 ${
+                      this.selectedMenu === "settings"
+                        ? "bg-gray-100 text-gray-700"
+                        : "text-gray-400 hover:text-gray-600"
+                    }"
+                    type="button"
+                    aria-label="Settings"
+                    aria-pressed=${this.selectedMenu === "settings"}
+                    @click=${() =>
+                      this.handleMenuSelect(
+                        this.selectedMenu === "settings"
+                          ? "ag-ui-events"
+                          : "settings",
+                      )}
+                  >
+                    ${this.renderIcon("Settings")}
+                  </button>
                   <button
                     class="flex h-8 w-8 items-center justify-center rounded-md text-gray-400 transition hover:bg-gray-100 hover:text-gray-600 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-gray-400"
                     type="button"
@@ -5601,9 +5660,64 @@ ${argsString}</pre
       return this.renderThreadsView();
     }
 
+    if (this.selectedMenu === "settings") {
+      return this.renderSettingsPanel();
+    }
+
     return nothing;
   }
 
+  private renderSettingsPanel() {
+    const optedOut = this.core?.telemetryDisabled ?? false;
+    return html`
+      <div class="flex h-full flex-col overflow-hidden">
+        <div class="overflow-auto p-4">
+          <div class="space-y-3">
+            <h2 class="text-sm font-semibold text-slate-900">Settings</h2>
+
+            <div class="space-y-2">
+              <h3 class="text-sm text-slate-500">Privacy</h3>
+              <div class="rounded-lg border border-slate-200 bg-white p-4 space-y-3">
+                <p class="text-sm text-gray-600 flex items-start gap-2">
+                  <span>${optedOut ? "❌" : "✅"}</span>
+                  <span>
+                    ${
+                      optedOut
+                        ? "You have disabled anonymous interaction data collection."
+                        : "CopilotKit is currently collecting anonymous interaction data from the inspector so we know which features people use. We never collect message content, agent state, prompts, or completions."
+                    }
+                  </span>
+                </p>
+                <a
+                  class="inline-flex items-center gap-1 text-sm text-slate-700 underline hover:text-slate-900"
+                  href=${TELEMETRY_DOCS_URL}
+                  target="_blank"
+                  rel="noopener"
+                >Learn more →</a>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    `;
+  }
+
+  // Fires `banner_clicked` at most once per `${bannerId}:${cta}` per mount so
+  // copy-button retries and accidental multi-clicks don't inflate funnel counts.
+  private trackBannerClickedOnce(opts: { cta: "body" | "dismiss" }): void {
+    if (this.core?.telemetryDisabled) return;
+    const id = this.announcementTimestamp;
+    if (!id) return;
+    const key = `${id}:${opts.cta}`;
+    if (this.clickedBannerIds.has(key)) return;
+    this.clickedBannerIds.add(key);
+    trackBannerClicked({
+      banner_id: id,
+      cta: opts.cta,
+      cta_label: this.announcementCtaLabel ?? undefined,
+    });
+  }
+
   private handleThreadDividerPointerDown = (event: PointerEvent) => {
     this.threadDividerResizing = true;
     this.threadDividerPointerId = event.pointerId;
@@ -6371,7 +6485,10 @@ ${prettyEvent}</pre
   }
 
   private handleMenuSelect(key: MenuKey): void {
-    if (!this.menuItems.some((item) => item.key === key)) {
+    if (
+      key !== "settings" &&
+      !this.menuItems.some((item) => item.key === key)
+    ) {
       return;
     }
 
@@ -6410,6 +6527,9 @@ ${prettyEvent}</pre
     }
 
     if (key === "threads") {
+      if (this.selectedMenu !== "threads" && !this.core?.telemetryDisabled) {
+        trackThreadsTabClicked();
+      }
       this.autoSelectLatestThread();
     }
 
@@ -7286,6 +7406,16 @@ ${prettyEvent}</pre
     </div>`;
   }
 
+  private flushPendingBannerViewed(): void {
+    if (!this.pendingBannerViewed || this.core?.telemetryDisabled) {
+      this.pendingBannerViewed = null;
+      return;
+    }
+    if (this.runtimeStatus !== "connected") return;
+    trackBannerViewed(this.pendingBannerViewed);
+    this.pendingBannerViewed = null;
+  }
+
   private ensureAnnouncementLoading(): void {
     if (
       this.announcementPromise ||
@@ -7326,6 +7456,7 @@ ${prettyEvent}</pre
   }
 
   private handleDismissAnnouncement = (): void => {
+    this.trackBannerClickedOnce({ cta: "dismiss" });
     this.markAnnouncementSeen();
   };
 
@@ -7340,6 +7471,7 @@ ${prettyEvent}</pre
         timestamp?: unknown;
         previewText?: unknown;
         announcement?: unknown;
+        cta_label?: unknown;
       };
 
       const timestamp =
@@ -7348,6 +7480,8 @@ ${prettyEvent}</pre
         typeof data?.previewText === "string" ? data.previewText : null;
       const markdown =
         typeof data?.announcement === "string" ? data.announcement : null;
+      const ctaLabel =
+        typeof data?.cta_label === "string" ? data.cta_label : null;
 
       if (!timestamp || !markdown) {
         throw new Error("Malformed announcement payload");
@@ -7357,6 +7491,7 @@ ${prettyEvent}</pre
 
       this.announcementTimestamp = timestamp;
       this.announcementPreviewText = previewText ?? "";
+      this.announcementCtaLabel = ctaLabel;
       this.hasUnseenAnnouncement =
         (!storedTimestamp || storedTimestamp !== timestamp) &&
         !!this.announcementPreviewText;
@@ -7364,6 +7499,22 @@ ${prettyEvent}</pre
       this.announcementHtml = await this.convertMarkdownToHtml(markdown);
       this.announcementLoaded = true;
 
+      // banner_viewed: gate on actual visibility and per-mount dedup.
+      // Store as pending rather than firing immediately — telemetryDisabled
+      // may not be known yet if /info hasn't returned. Flushed in
+      // onRuntimeConnectionStatusChanged once the handshake completes.
+      if (
+        this.hasUnseenAnnouncement &&
+        !this.viewedBannerTimestamps.has(timestamp)
+      ) {
+        this.viewedBannerTimestamps.add(timestamp);
+        this.pendingBannerViewed = {
+          banner_id: timestamp,
+          cta_label: ctaLabel ?? undefined,
+        };
+        this.flushPendingBannerViewed();
+      }
+
       this.requestUpdate();
     } catch (error) {
       // Swallowing here would hide non-network failures (malformed JSON, the
@@ -7422,6 +7573,10 @@ ${prettyEvent}</pre
     const target = event.target instanceof HTMLElement ? event.target : null;
     const button = target?.closest(".announcement-code__copy");
     if (!(button instanceof HTMLButtonElement)) {
+      // banner_clicked fires once per banner per cta-type per mount. Dedup
+      // prevents accidental multi-clicks from inflating funnel counts beyond
+      // one "body" signal and one "dismiss" signal per banner.
+      this.trackBannerClickedOnce({ cta: "body" });
       return;
     }
     event.preventDefault();
@@ -7466,6 +7621,20 @@ ${prettyEvent}</pre
       if (!url.searchParams.has("ref")) {
         url.searchParams.append("ref", "cpk-inspector");
       }
+      // Propagate the inspector's anonymous distinct-ID so the website /
+      // Ops API can call posthog.alias(...) on signup-flow landing and
+      // close the banner_viewed → banner_clicked → signup_attributed
+      // funnel. Returns null when the user has opted out, so opt-out
+      // suppresses cross-domain ID leaks too.
+      if (
+        !url.searchParams.has("posthog_distinct_id") &&
+        !this.core?.telemetryDisabled
+      ) {
+        const distinctId = getTelemetryDistinctIdForUrl();
+        if (distinctId) {
+          url.searchParams.append("posthog_distinct_id", distinctId);
+        }
+      }
       return url.toString();
     } catch {
       return href;

package/src/lib/__tests__/telemetry.test.ts

@@ -0,0 +1,323 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { MockInstance } from "vitest";
+
+import {
+  TELEMETRY_DOCS_URL,
+  TELEMETRY_EVENTS,
+  TELEMETRY_INGEST_URL,
+  getTelemetryDistinctIdForUrl,
+  maybeShowDisclosure,
+  track,
+  trackBannerClicked,
+  trackBannerViewed,
+  trackThreadsTabClicked,
+} from "../telemetry";
+import {
+  _resetTelemetryPersistenceForTesting,
+  getOrCreateTelemetryDistinctId,
+  hasTelemetryDisclosureBeenShown,
+  isTelemetryOptedOut,
+  markTelemetryDisclosureShown,
+  setTelemetryOptOut,
+} from "../persistence";
+
+// The wrapper short-circuits before any network call when opted out, but
+// for the network-touching cases we mock fetch globally so we can read
+// what would have been sent without making real HTTP requests.
+let fetchMock: MockInstance<typeof fetch>;
+let consoleInfoSpy: MockInstance<typeof console.info>;
+
+beforeEach(() => {
+  // Each test starts from a clean localStorage so distinct-ID + opt-out
+  // + disclosure-shown flags don't leak across cases.
+  window.localStorage.clear();
+  _resetTelemetryPersistenceForTesting();
+
+  // The wrapper POSTs via globalThis.fetch with a 3s AbortController
+  // timeout. Stub it with a resolving Response so happy-path sends
+  // complete synchronously (the wrapper does `void` on the promise).
+  fetchMock = vi
+    .spyOn(globalThis, "fetch")
+    .mockResolvedValue(new Response(null, { status: 204 }));
+
+  consoleInfoSpy = vi.spyOn(console, "info").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+// ─── Wire body shape ────────────────────────────────────────────────────────
+
+describe("track()", () => {
+  it("posts to telemetry.copilotkit.ai/ingest with confirmed IngestPayload shape", async () => {
+    track(TELEMETRY_EVENTS.bannerViewed, {
+      banner_id: "2025-05-01T00:00:00Z",
+    });
+
+    await Promise.resolve();
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0]!;
+    expect(url).toBe(TELEMETRY_INGEST_URL);
+    expect(init?.method).toBe("POST");
+    expect((init?.headers as Record<string, string>)["Content-Type"]).toBe(
+      "application/json",
+    );
+    expect(
+      (init?.headers as Record<string, string>)["X-CopilotKit-Telemetry-Id"],
+    ).toMatch(/^[0-9a-f-]{36}$/);
+
+    // Ben confirmed shape (telemetry-sink-ingest/index.ts:127-134):
+    // package is a top-level object { name, version? }, NOT inside properties.
+    const body = JSON.parse((init?.body as string) ?? "{}") as {
+      event: string;
+      properties: Record<string, unknown>;
+      package: { name: string; version?: string };
+      ts: number;
+    };
+    expect(body.event).toBe("oss.inspector.banner_viewed");
+    expect(body.properties.banner_id).toBe("2025-05-01T00:00:00Z");
+    expect(typeof body.properties.distinct_id).toBe("string");
+    // package is top-level object, not a string inside properties
+    expect(body.package).toEqual({ name: "@copilotkit/web-inspector" });
+    expect(body.properties).not.toHaveProperty("package");
+    expect(typeof body.ts).toBe("number");
+  });
+
+  it("sends regardless of localStorage opt-out — callers gate on core.telemetryDisabled", async () => {
+    setTelemetryOptOut(true);
+    expect(isTelemetryOptedOut()).toBe(true);
+
+    track(TELEMETRY_EVENTS.bannerClicked, {
+      banner_id: "x",
+      cta: "body",
+    });
+    await Promise.resolve();
+
+    // track() no longer short-circuits on localStorage; opt-out is enforced
+    // at the call site via core.telemetryDisabled before track*() is invoked.
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("swallows fetch failures (telemetry is best-effort)", async () => {
+    fetchMock.mockRejectedValueOnce(new Error("network down"));
+
+    expect(() => track(TELEMETRY_EVENTS.threadsTabClicked)).not.toThrow();
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+
+  it("does not send when fetch is unavailable (SSR / pre-fetch environment)", async () => {
+    vi.stubGlobal("fetch", undefined);
+
+    expect(() =>
+      track(TELEMETRY_EVENTS.bannerViewed, { banner_id: "abc" }),
+    ).not.toThrow();
+
+    // No fetch call possible — restore happens in afterEach via unstubAllGlobals
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("never includes message content or agent state in the payload", async () => {
+    track(TELEMETRY_EVENTS.bannerViewed, { banner_id: "abc" });
+    await Promise.resolve();
+
+    const [, init] = fetchMock.mock.calls[0]!;
+    const raw = (init?.body as string) ?? "{}";
+    // Forbidden content keys (privacy invariant — never send inspector content)
+    expect(raw).not.toMatch(
+      /messages|completion|prompt|state_snapshot|agent_state|content|user_id/i,
+    );
+  });
+});
+
+// ─── Typed per-event helpers ─────────────────────────────────────────────────
+
+describe("typed helpers", () => {
+  it("trackBannerViewed sends banner_id and optional cta_label", async () => {
+    trackBannerViewed({ banner_id: "ts-2025", cta_label: "Try threads" });
+    await Promise.resolve();
+    const [, init] = fetchMock.mock.calls[0]!;
+    const body = JSON.parse((init?.body as string) ?? "{}") as {
+      event: string;
+      properties: Record<string, unknown>;
+    };
+    expect(body.event).toBe(TELEMETRY_EVENTS.bannerViewed);
+    expect(body.properties.banner_id).toBe("ts-2025");
+    expect(body.properties.cta_label).toBe("Try threads");
+  });
+
+  it("trackBannerViewed omits cta_label when undefined (JSON.stringify drops it)", async () => {
+    trackBannerViewed({ banner_id: "ts-2025" });
+    await Promise.resolve();
+    const [, init] = fetchMock.mock.calls[0]!;
+    const raw = (init?.body as string) ?? "{}";
+    expect(raw).not.toContain("cta_label");
+  });
+
+  it("trackBannerClicked sends banner_id, cta, and optional cta_label", async () => {
+    trackBannerClicked({ banner_id: "ts-2025", cta: "body" });
+    await Promise.resolve();
+    const [, init] = fetchMock.mock.calls[0]!;
+    const body = JSON.parse((init?.body as string) ?? "{}") as {
+      event: string;
+      properties: Record<string, unknown>;
+    };
+    expect(body.event).toBe(TELEMETRY_EVENTS.bannerClicked);
+    expect(body.properties.banner_id).toBe("ts-2025");
+    expect(body.properties.cta).toBe("body");
+  });
+
+  it("trackThreadsTabClicked sends no caller-supplied properties", async () => {
+    trackThreadsTabClicked();
+    await Promise.resolve();
+    const [, init] = fetchMock.mock.calls[0]!;
+    const body = JSON.parse((init?.body as string) ?? "{}") as {
+      event: string;
+      properties: Record<string, unknown>;
+    };
+    expect(body.event).toBe(TELEMETRY_EVENTS.threadsTabClicked);
+    // Only distinct_id should be in properties (no caller keys)
+    expect(Object.keys(body.properties)).toEqual(["distinct_id"]);
+  });
+});
+
+// ─── Distinct ID lifecycle ───────────────────────────────────────────────────
+
+describe("distinct ID lifecycle", () => {
+  it("persists across calls within the same session", () => {
+    const first = getOrCreateTelemetryDistinctId();
+    const second = getOrCreateTelemetryDistinctId();
+    expect(first).toBe(second);
+    expect(
+      window.localStorage.getItem("cpk:inspector:telemetry:distinct_id"),
+    ).toBe(first);
+  });
+
+  it("generates a UUID-v4-shaped value", () => {
+    const id = getOrCreateTelemetryDistinctId();
+    expect(id).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+    );
+  });
+
+  it("returns a UUID without throwing in SSR (window undefined)", () => {
+    vi.stubGlobal("window", undefined);
+    expect(() => getOrCreateTelemetryDistinctId()).not.toThrow();
+    const id = getOrCreateTelemetryDistinctId();
+    expect(id).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+    );
+  });
+
+  it("returns a UUID without throwing when localStorage.getItem throws", () => {
+    vi.spyOn(window.localStorage, "getItem").mockImplementation(() => {
+      throw new DOMException("QuotaExceededError");
+    });
+    expect(() => getOrCreateTelemetryDistinctId()).not.toThrow();
+    const id = getOrCreateTelemetryDistinctId();
+    expect(id).toMatch(/^[0-9a-f]{8}-/);
+  });
+
+  it("returns the same UUID across calls when localStorage throws (funnel coherence)", () => {
+    vi.spyOn(window.localStorage, "getItem").mockImplementation(() => {
+      throw new DOMException("QuotaExceededError");
+    });
+    vi.spyOn(window.localStorage, "setItem").mockImplementation(() => {
+      throw new DOMException("QuotaExceededError");
+    });
+    const first = getOrCreateTelemetryDistinctId();
+    const second = getOrCreateTelemetryDistinctId();
+    expect(first).toBe(second);
+  });
+});
+
+// ─── Persistence error-resilience ───────────────────────────────────────────
+
+describe("persistence error-resilience", () => {
+  it("isTelemetryOptedOut returns false (not disabled) when localStorage throws", () => {
+    vi.spyOn(window.localStorage, "getItem").mockImplementation(() => {
+      throw new DOMException("SecurityError");
+    });
+    // Must fail to "not opted out" — if it returned true, all users in
+    // restricted-storage contexts would have telemetry silently disabled.
+    expect(isTelemetryOptedOut()).toBe(false);
+  });
+
+  it("setTelemetryOptOut does not throw when localStorage.setItem throws", () => {
+    vi.spyOn(window.localStorage, "setItem").mockImplementation(() => {
+      throw new DOMException("QuotaExceededError");
+    });
+    expect(() => setTelemetryOptOut(true)).not.toThrow();
+  });
+
+  it("markTelemetryDisclosureShown does not throw when localStorage.setItem throws", () => {
+    vi.spyOn(window.localStorage, "setItem").mockImplementation(() => {
+      throw new DOMException("QuotaExceededError");
+    });
+    // Failure means the disclosure fires on every mount instead of once —
+    // a UX regression, not a data leak. The important invariant is no throw.
+    expect(() => markTelemetryDisclosureShown()).not.toThrow();
+  });
+});
+
+// ─── maybeShowDisclosure() ───────────────────────────────────────────────────
+
+describe("maybeShowDisclosure()", () => {
+  it("logs once and sets the disclosure-shown flag", () => {
+    maybeShowDisclosure();
+    expect(consoleInfoSpy).toHaveBeenCalledTimes(1);
+    const [message] = consoleInfoSpy.mock.calls[0]!;
+    expect(message).toContain(TELEMETRY_DOCS_URL);
+    expect(hasTelemetryDisclosureBeenShown()).toBe(true);
+
+    maybeShowDisclosure();
+    // No second log — flag short-circuits.
+    expect(consoleInfoSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not log when the user is already opted out", () => {
+    setTelemetryOptOut(true);
+
+    maybeShowDisclosure();
+
+    expect(consoleInfoSpy).not.toHaveBeenCalled();
+    // The flag stays unset so a future opt-in flips back to "first run"
+    // behavior — see the wrapper's design comment.
+    expect(hasTelemetryDisclosureBeenShown()).toBe(false);
+  });
+});
+
+// ─── getTelemetryDistinctIdForUrl() ─────────────────────────────────────────
+
+describe("getTelemetryDistinctIdForUrl()", () => {
+  it("returns the persisted distinct-ID when not opted out", () => {
+    const id = getTelemetryDistinctIdForUrl();
+    expect(id).not.toBeNull();
+    expect(id).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+    );
+    // Same ID across calls — ensures URL propagation matches the ID
+    // that goes on event sends.
+    expect(getTelemetryDistinctIdForUrl()).toBe(id);
+  });
+
+  it("returns null when the user is opted out (no cross-domain leak)", () => {
+    setTelemetryOptOut(true);
+    expect(getTelemetryDistinctIdForUrl()).toBeNull();
+  });
+});
+
+// ─── Opt-out round-trip ──────────────────────────────────────────────────────
+
+describe("opt-out round-trip", () => {
+  it("setTelemetryOptOut(true) → isTelemetryOptedOut() is true", () => {
+    expect(isTelemetryOptedOut()).toBe(false);
+    setTelemetryOptOut(true);
+    expect(isTelemetryOptedOut()).toBe(true);
+    setTelemetryOptOut(false);
+    expect(isTelemetryOptedOut()).toBe(false);
+  });
+});