@hyperframes/studio 0.8.55 → 0.8.57

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -8,7 +8,7 @@
  *  - onIframeLoad             — orchestrates initializeAdapter with a message-based fallback
  */
 
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
 import { liveTime, usePlayerStore } from "../store/playerStore";
 import type { TimelineElement } from "../store/playerStore";
 import type { PlaybackAdapter, IframeWindow } from "../lib/playbackTypes";
@@ -19,7 +19,6 @@ import {
   buildTimelineElementsFromClips,
   syncManifestTimeline,
   clipTreeParentMap,
-  collectTopLevelElementIds,
   collectSubCompositionDomChildren,
   collectSubCompositionHostState,
   hydrateTimelineFromPreview,
@@ -34,7 +33,7 @@ import {
 // Re-exported for the tests and callers that have always imported it from here.
 export { resolveReloadSeekTime } from "./timelineSyncHydration";
 
-interface UseTimelineSyncCallbacksParams {
+export interface UseTimelineSyncCallbacksParams {
   iframeRef: React.RefObject<HTMLIFrameElement | null>;
   probeIntervalRef: React.MutableRefObject<ReturnType<typeof setInterval> | undefined>;
   pendingSeekRef: React.MutableRefObject<number | null>;
@@ -47,6 +46,19 @@ interface UseTimelineSyncCallbacksParams {
   setIsPlaying: (v: boolean) => void;
   attachIframeShortcutListeners: () => void;
   applyPreviewAudioState: () => void;
+  /**
+   * Fires once the restore-seek is issued and owns when `commit` (the store hydration) runs.
+   * The default reveals the iframe and commits at once; a shadow reload defers it to promotion.
+   */
+  onAdapterReady?: (
+    iframe: HTMLIFrameElement | null,
+    context: number | undefined,
+    commit: () => void,
+  ) => void;
+  /** False when the load for `context` was superseded: it must then cause no side effects. */
+  isCurrent?: (context?: number) => boolean;
+  /** Fires when no adapter appeared within the wait window. */
+  onLoadGiveUp?: (context?: number) => void;
 }
 
 /**
@@ -63,18 +75,54 @@ interface UseTimelineSyncCallbacksParams {
  * resets currentTime on project switch. Invariant: an edit NEVER moves the
  * playhead (the clamp below is the one sanctioned move — content shrank past it).
  */
-/**
- * Undo the `visibility: hidden` that refreshPlayer sets across a full reload.
- * Safe to call when the iframe was never hidden (idempotent no-op). Every reload
- * completion + failure path funnels through here so the preview can never get
- * stuck invisible.
- */
+/** Undo a hidden `visibility` on an iframe; idempotent no-op otherwise. */
 export function revealIframe(iframe: HTMLIFrameElement | null): void {
   if (iframe && iframe.style.visibility === "hidden") {
     iframe.style.visibility = "";
   }
 }
 
+function revealAndCommit(
+  iframe: HTMLIFrameElement | null,
+  _context: number | undefined,
+  commit: () => void,
+): void {
+  revealIframe(iframe);
+  commit();
+}
+
+export type PreviewIframeRole = "live" | "shadow";
+
+export interface PreviewIframeSlot {
+  gen: number;
+  role: PreviewIframeRole;
+  url?: string;
+}
+
+/** Queue a hidden shadow slot for the reload URL, replacing any earlier unpromoted shadow. */
+export function planShadowReload(
+  slots: PreviewIframeSlot[],
+  nextGen: number,
+  url: string,
+): PreviewIframeSlot[] {
+  const live = slots.find((slot) => slot.role === "live");
+  return live ? [live, { gen: nextGen, role: "shadow", url }] : [{ gen: nextGen, role: "live" }];
+}
+
+/** Drop any pending shadow; the live slot (and its key) is untouched. */
+export function planShadowDiscard(slots: PreviewIframeSlot[]): PreviewIframeSlot[] {
+  return slots.filter((slot) => slot.role === "live");
+}
+
+/** Atomically make the ready shadow the only (live) slot; a stale readyGen is a no-op. */
+export function planShadowPromotion(
+  slots: PreviewIframeSlot[],
+  readyGen: number,
+): PreviewIframeSlot[] {
+  const ready = slots.find((slot) => slot.gen === readyGen && slot.role === "shadow");
+  return ready ? [{ ...ready, role: "live" }] : slots;
+}
+
 /**
  * The transport TOTAL a clip-manifest message should write to the store.
  *
@@ -111,6 +159,9 @@ export function useTimelineSyncCallbacks({
   setIsPlaying,
   attachIframeShortcutListeners,
   applyPreviewAudioState,
+  onAdapterReady = revealAndCommit,
+  isCurrent,
+  onLoadGiveUp,
 }: UseTimelineSyncCallbacksParams) {
   // Convert a runtime timeline message (from iframe postMessage) into TimelineElements
   const processTimelineMessage = useCallback(
@@ -130,13 +181,11 @@ export function useTimelineSyncCallbacks({
         const parentMap = clipTreeParentMap(iframeRef.current?.contentWindow ?? null);
         const domClipChildren = collectSubCompositionDomChildren(iframeDoc, data.clips, parentMap);
         usePlayerStore.getState().setClipParentMap(parentMap);
-        usePlayerStore.getState().setTopLevelIds(collectTopLevelElementIds(iframeDoc));
         usePlayerStore.getState().setDomClipChildren(domClipChildren);
         usePlayerStore
           .getState()
           .setSubCompositionHostState(collectSubCompositionHostState(iframeDoc, data.clips));
       } catch {
-        usePlayerStore.getState().setTopLevelIds(null);
         // cross-origin or __clipTree not available — maps stay empty
       }
 
@@ -186,94 +235,112 @@ export function useTimelineSyncCallbacks({
     } catch {}
   }, [iframeRef, syncTimelineElements]);
 
-  const initializeAdapter = useCallback(() => {
-    const adapter = getAdapter();
-    if (!adapter || adapter.getDuration() <= 0) return false;
-
-    adapter.pause();
-    const startTime = seekAdapterToRestorePoint(adapter, pendingSeekRef);
-    // The correct frame is now rendered — reveal the iframe that refreshPlayer hid
-    // for the reload, so the user sees the restored frame directly (never the raw
-    // all-clips DOM). Cleared unconditionally: any later failure path must not leave
-    // the preview stuck invisible.
-    revealIframe(iframeRef.current);
-    // Keep non-React listeners such as the capture link and time display in sync
-    // with the initial adapter seek on iframe load.
-    liveTime.notify(startTime);
-    syncAdapterDuration(adapter, setDuration);
-    setCurrentTime(startTime);
-    if (!isRefreshingRef.current) {
-      // Enables Play from actual play-readiness, not just a known duration —
-      // a click before this resolves used to start the timeline with media,
-      // images or fonts still loading and never recover.
-      requestTimelineReady(safeContentDocument(iframeRef.current));
-    }
-    isRefreshingRef.current = false;
-    setIsPlaying(false);
-
-    hydrateTimelineFromPreview({
-      iframe: iframeRef.current,
-      adapter,
+  const initializeAdapter = useCallback(
+    (context?: number) => {
+      if (isCurrent && !isCurrent(context)) return true;
+      const adapter = getAdapter();
+      if (!adapter || adapter.getDuration() <= 0) return false;
+
+      adapter.pause();
+      const startTime = seekAdapterToRestorePoint(adapter, pendingSeekRef);
+      const commit = () => {
+        // Keep non-React listeners such as the capture link and time display in sync
+        // with the initial adapter seek on iframe load.
+        liveTime.notify(startTime);
+        syncAdapterDuration(adapter, setDuration);
+        setCurrentTime(startTime);
+        if (!isRefreshingRef.current) {
+          // Enables Play from actual play-readiness, not just a known duration —
+          // a click before this resolves used to start the timeline with media,
+          // images or fonts still loading and never recover.
+          requestTimelineReady(safeContentDocument(iframeRef.current));
+        }
+        isRefreshingRef.current = false;
+        setIsPlaying(false);
+
+        hydrateTimelineFromPreview({
+          iframe: iframeRef.current,
+          adapter,
+          processTimelineMessage,
+          enrichMissingCompositions,
+          applyPreviewAudioState,
+          attachIframeShortcutListeners,
+          syncTimelineElements,
+        });
+      };
+      onAdapterReady(iframeRef.current, context, commit);
+      return true;
+    },
+    [
+      getAdapter,
+      setDuration,
+      setCurrentTime,
+      requestTimelineReady,
+      setIsPlaying,
       processTimelineMessage,
       enrichMissingCompositions,
-      applyPreviewAudioState,
-      attachIframeShortcutListeners,
       syncTimelineElements,
-    });
-    return true;
-  }, [
-    getAdapter,
-    setDuration,
-    setCurrentTime,
-    requestTimelineReady,
-    setIsPlaying,
-    processTimelineMessage,
-    enrichMissingCompositions,
-    syncTimelineElements,
-    attachIframeShortcutListeners,
-    applyPreviewAudioState,
-    iframeRef,
-    isRefreshingRef,
-    pendingSeekRef,
-  ]);
-
-  const onIframeLoad = useCallback(() => {
-    applyPreviewAudioState();
-    if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+      attachIframeShortcutListeners,
+      applyPreviewAudioState,
+      onAdapterReady,
+      isCurrent,
+      iframeRef,
+      isRefreshingRef,
+      pendingSeekRef,
+    ],
+  );
 
-    // Fast path: adapter already available (in-place reloads, cached compositions)
-    if (initializeAdapter()) return;
+  // Drops the previous load's readiness listener so a superseded load cannot settle later.
+  const stopWaitingRef = useRef<(() => void) | null>(null);
 
-    // The runtime posts "state" or "timeline" messages once ready.
-    // Listen for those instead of polling.
-    const iframe = iframeRef.current;
-    let settled = false;
+  const onIframeLoad = useCallback(
+    (context?: number) => {
+      applyPreviewAudioState();
+      if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+      stopWaitingRef.current?.();
+      stopWaitingRef.current = null;
 
-    const trySettle = () => {
-      if (settled) return;
-      if (initializeAdapter()) {
-        settled = true;
-        window.removeEventListener("message", onMessage);
-        if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
-      }
-    };
+      // Fast path: adapter already available (in-place reloads, cached compositions)
+      if (initializeAdapter(context)) return;
 
-    const onMessage = (e: MessageEvent) => {
-      if (isPreviewReadinessMessage(e, iframe)) trySettle();
-    };
-    window.addEventListener("message", onMessage);
+      // The runtime posts "state" or "timeline" messages once ready.
+      // Listen for those instead of polling.
+      const iframe = iframeRef.current;
+      let settled = false;
 
-    // Safety net: if no message arrives within 5s, try one last time then give up.
-    probeIntervalRef.current = setTimeout(() => {
-      if (!settled) {
-        trySettle();
-      }
-      window.removeEventListener("message", onMessage);
-      // Never leave the preview stuck invisible if the runtime never settled
-      // (initializeAdapter reveals on success; this covers the give-up case).
-      revealIframe(iframeRef.current);
-    }, 5000) as unknown as ReturnType<typeof setInterval>;
-  }, [initializeAdapter, iframeRef, probeIntervalRef, applyPreviewAudioState]);
+      const trySettle = () => {
+        if (settled) return;
+        if (initializeAdapter(context)) {
+          settled = true;
+          window.removeEventListener("message", onMessage);
+          if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+        }
+      };
+
+      const onMessage = (e: MessageEvent) => {
+        if (isPreviewReadinessMessage(e, iframe)) trySettle();
+      };
+      window.addEventListener("message", onMessage);
+      stopWaitingRef.current = () => window.removeEventListener("message", onMessage);
+
+      // Safety net: if no message arrives within 5s, try one last time then give up.
+      probeIntervalRef.current = setTimeout(() => {
+        if (!settled) {
+          trySettle();
+        }
+        window.removeEventListener("message", onMessage);
+        if (!settled) onLoadGiveUp?.(context);
+        revealIframe(iframeRef.current);
+      }, 5000) as unknown as ReturnType<typeof setInterval>;
+    },
+    [initializeAdapter, iframeRef, probeIntervalRef, applyPreviewAudioState, onLoadGiveUp],
+  );
+
+  const cancelPendingLoad = useCallback(() => {
+    if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+    stopWaitingRef.current?.();
+    stopWaitingRef.current = null;
+  }, [probeIntervalRef]);
 
   // Stable refs so mount-effect closures always call the latest version
   const processTimelineMessageRef = { current: processTimelineMessage };
@@ -286,5 +353,6 @@ export function useTimelineSyncCallbacks({
     enrichMissingCompositionsRef,
     initializeAdapter,
     onIframeLoad,
+    cancelPendingLoad,
   };
 }

package/src/player/store/playerStore.ts

@@ -202,8 +202,6 @@ interface PlayerState extends PlayerStoreSlices {
   clipManifest: ClipManifestClip[] | null;
   setClipManifest: (clips: ClipManifestClip[] | null) => void;
   clipParentMap: Map<string, string>;
-  topLevelIds: ReadonlySet<string> | null;
-  setTopLevelIds: (ids: ReadonlySet<string> | null) => void;
   setClipParentMap: (map: Map<string, string>) => void;
   /**
    * Sub-composition DOM descendants (groups + their children) that have no
@@ -394,8 +392,6 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   setClipManifest: (clips) => set({ clipManifest: clips }),
   clipParentMap: new Map(),
   setClipParentMap: (map) => set({ clipParentMap: map }),
-  topLevelIds: null,
-  setTopLevelIds: (ids) => set({ topLevelIds: ids }),
   domClipChildren: [],
   setDomClipChildren: (children) => set({ domClipChildren: children }),
   subCompositionHostState: new Map(),

package/src/player/store/timelineElement.ts

@@ -77,10 +77,8 @@ export interface TimelineElement {
   audioGroupFxChain?: string;
   audioGroupAutomation?: string;
   /**
-   * Set by useTimelineRowElements on an inline-expanded sub-composition
-   * child: the absolute master-timeline start of the sub-comp host the child
-   * lives in. Presence marks the element as expanded; edits subtract it to get
-   * the child's local (sourceFile-relative) time. Works at any nesting depth.
+   * Legacy source-coordinate marker for an inline sub-composition child. The
+   * current timeline keeps sub-compositions as single rows.
    */
   expandedParentStart?: number;
   expandedHostKey?: string;

package/src/player/store/timelineResetState.ts

@@ -44,7 +44,6 @@ export function createTimelineResetState() {
     beatPersist: null,
     clipManifest: null,
     clipParentMap: new Map<string, string>(),
-    topLevelIds: null,
     domClipChildren: [],
     subCompositionHostState: new Map<string, SubCompositionHostState>(),
   };

package/src/styles/hex-baseline.json

@@ -1,5 +1,5 @@
 {
-  "total": 418,
+  "total": 385,
   "files": {
     "packages/studio/src/captions/components/CaptionOverlay.tsx": 5,
     "packages/studio/src/captions/components/CaptionTimeline.tsx": 11,
@@ -61,7 +61,6 @@
     "packages/studio/src/player/components/SpeedMenu.tsx": 2,
     "packages/studio/src/player/components/TimelineAutomationLane.tsx": 4,
     "packages/studio/src/player/components/TimelineCanvas.tsx": 13,
-    "packages/studio/src/player/components/TimelineClip.tsx": 2,
     "packages/studio/src/player/components/TimelineClipDiamonds.tsx": 2,
     "packages/studio/src/player/components/TimelineDiamondConnectors.tsx": 2,
     "packages/studio/src/player/components/TimelineEmptyState.tsx": 1,
@@ -75,9 +74,9 @@
     "packages/studio/src/player/components/TimelineTrackHeader.tsx": 2,
     "packages/studio/src/player/components/TimelineTrackPlainHeader.tsx": 2,
     "packages/studio/src/player/components/VideoThumbnail.tsx": 6,
-    "packages/studio/src/player/components/timelineTheme.ts": 29,
+    "packages/studio/src/player/components/timelineTheme.ts": 5,
     "packages/studio/src/player/components/trackHeaderLabelRows.tsx": 6,
-    "packages/studio/src/styles/studio.css": 70,
+    "packages/studio/src/styles/studio.css": 63,
     "packages/studio/src/telemetry/client.ts": 1,
     "packages/studio/src/webmcp/webmcpTestUtils.ts": 1
   }

package/src/styles/studio.css

@@ -200,8 +200,8 @@ body {
 }
 
 .timeline-clip {
-  background-color: rgba(255, 255, 255, 0.055);
-  border: 1px solid rgba(255, 255, 255, 0.09);
+  background-color: var(--clip-bg);
+  border: 1px solid var(--clip-border);
   border-radius: 8px;
 }
 
@@ -210,13 +210,13 @@ body {
   position: absolute;
   inset: 0;
   border-radius: inherit;
-  background: rgba(60, 230, 172, 0.2);
+  background: var(--clip-bg-active);
   opacity: 0;
   pointer-events: none;
 }
 
 .timeline-clip[data-active] {
-  border-color: rgba(60, 230, 172, 0.55);
+  border-color: var(--clip-border-active);
 }
 
 .timeline-clip[data-active]::before {
@@ -240,11 +240,11 @@ body {
 }
 
 .timeline-clip.is-hovered {
-  background-color: rgba(255, 255, 255, 0.09);
+  background-color: var(--clip-bg-hover);
 }
 
 .timeline-clip[data-active].is-hovered {
-  border-color: rgba(60, 230, 172, 0.75);
+  border-color: var(--clip-border-hover);
 }
 
 .timeline-clip.is-selected {
@@ -258,7 +258,7 @@ body {
 .timeline-clip.is-dragging {
   /* Solid background so the picked-up clip reads clearly while dragging — audio
      clips (waveform drawn on a separate layer) would otherwise look transparent. */
-  background-color: rgba(38, 42, 52, 0.96);
+  background-color: var(--clip-bg-dragging);
   box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
 }
 

package/src/styles/theme.css

@@ -46,6 +46,35 @@
   --color-brand-gradient-from: #06e3fa;
   --color-brand-gradient-to: #4fdb5e;
 
+  /* The timeline's own surfaces: darker and bluer than the shared scale, so they
+   * get their own names instead of snapping to the nearest --color-bg/-surface
+   * step (a host themes the timeline by overriding these). */
+  --timeline-shell-bg: #0a0a0b;
+  --timeline-shell-border: rgba(255, 255, 255, 0.05);
+  --timeline-ruler-border: rgba(255, 255, 255, 0.16);
+  --timeline-row-bg: #101014;
+  --timeline-row-border: rgba(255, 255, 255, 0.06);
+  --timeline-gutter-bg: #0e0f12;
+  --timeline-gutter-border: rgba(255, 255, 255, 0.1);
+  --timeline-text-primary: rgba(255, 255, 255, 0.92);
+  --timeline-text-secondary: rgba(255, 255, 255, 0.62);
+  --timeline-tick-text: rgba(255, 255, 255, 0.34);
+  --timeline-tick-major: rgba(255, 255, 255, 0.1);
+  --timeline-tick-minor: rgba(255, 255, 255, 0.06);
+  --timeline-clip-bg: rgba(255, 255, 255, 0.12);
+  --timeline-clip-bg-active: rgba(60, 230, 172, 0.2);
+  --timeline-clip-bg-hover: rgba(255, 255, 255, 0.16);
+  --timeline-clip-bg-dragging: rgba(38, 42, 52, 0.96);
+  --timeline-clip-border: rgba(255, 255, 255, 0.22);
+  --timeline-clip-border-hover: rgba(60, 230, 172, 0.75);
+  --timeline-clip-border-active: rgba(60, 230, 172, 0.55);
+  --timeline-handle: rgba(255, 255, 255, 0.55);
+  --timeline-resize-seam: rgba(255, 255, 255, 0.12);
+  --timeline-resize-active: rgba(255, 255, 255, 0.24);
+  --timeline-track-clip-fill: rgba(255, 255, 255, 0.055);
+  --timeline-track-clip-active: rgba(60, 230, 172, 0.16);
+  --timeline-track-label: rgba(255, 255, 255, 0.5);
+
   /* -------------------------------------------------------------- geometry */
 
   --radius-sm: 0.25rem;

package/src/telemetry/events.test.ts

@@ -9,6 +9,7 @@ vi.mock("./client", () => ({
 
 const {
   trackStudioSessionStart,
+  trackPreviewFirstFrame,
   trackStudioRenderStart,
   trackStudioRazorSplit,
   trackStudioExpandedClipEdit,
@@ -34,6 +35,23 @@ describe("studio telemetry events", () => {
     expect(trackEvent).toHaveBeenCalledWith("studio_session_start", { has_project: false });
   });
 
+  it("trackPreviewFirstFrame emits timing, composition duration, and version", () => {
+    trackPreviewFirstFrame({
+      duration_ms: 842,
+      composition_seconds: 12.5,
+      clip_count: 8,
+      media_clip_count: 5,
+      studio_version: "0.8.56",
+    });
+    expect(trackEvent).toHaveBeenCalledWith("preview_first_frame", {
+      duration_ms: 842,
+      composition_seconds: 12.5,
+      clip_count: 8,
+      media_clip_count: 5,
+      studio_version: "0.8.56",
+    });
+  });
+
   it("trackStudioRenderStart emits 'studio_render_start' with all render opts", () => {
     trackStudioRenderStart({
       fps: 30,

package/src/telemetry/events.ts

@@ -11,6 +11,16 @@ export function trackStudioSessionStart(props: { has_project: boolean }): void {
   });
 }
 
+export function trackPreviewFirstFrame(props: {
+  duration_ms: number;
+  composition_seconds: number;
+  clip_count: number;
+  media_clip_count: number;
+  studio_version: string;
+}): void {
+  trackEvent("preview_first_frame", props);
+}
+
 export function trackStudioRenderStart(props: {
   fps: number;
   quality: string;

package/src/telemetry/system.test.ts

@@ -0,0 +1,49 @@
+// @vitest-environment happy-dom
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// The `studio_*` transport carries browser metadata built here, and this is its
+// only test. tab_id has a module test of its own, but nothing there fails if
+// this file stops attaching it — the two are separate facts.
+describe("browser system meta", () => {
+  // Both modules are imported AFTER resetModules so they share one tabId
+  // instance; a top-level import would be a different copy of the memo.
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  async function load() {
+    const [{ getBrowserSystemMeta }, tab] = await Promise.all([
+      import("./system"),
+      import("./tabId"),
+    ]);
+    return { getBrowserSystemMeta, resolveTabId: tab.resolveTabId };
+  }
+
+  it("carries the tab id, from the same source as the studio:* transport", async () => {
+    const { getBrowserSystemMeta, resolveTabId } = await load();
+    expect(getBrowserSystemMeta().tab_id).toBe(resolveTabId());
+  });
+
+  it("keeps the meta memoized, so one page reports one tab id", async () => {
+    const { getBrowserSystemMeta } = await load();
+    const first = getBrowserSystemMeta();
+    expect(getBrowserSystemMeta()).toBe(first);
+    expect(getBrowserSystemMeta().tab_id).toBe(first.tab_id);
+  });
+
+  it("has a tab id in the no-DOM fallback, not an empty string", async () => {
+    // The empty-meta branch is taken on SSR. An empty or missing tab_id would
+    // read in PostHog as "this event predates the property" rather than "this
+    // event has no page", which is the encoding mistake this property exists
+    // to avoid. Stubbing the globals is what actually reaches that branch —
+    // happy-dom otherwise satisfies the `typeof window` check every time.
+    vi.stubGlobal("navigator", undefined);
+    vi.stubGlobal("window", undefined);
+    const { getBrowserSystemMeta } = await load();
+    const meta = getBrowserSystemMeta();
+    expect(meta.user_agent).toBe("");
+    expect(typeof meta.tab_id).toBe("string");
+    expect(meta.tab_id.length).toBeGreaterThan(0);
+    vi.unstubAllGlobals();
+  });
+});

package/src/telemetry/system.ts

@@ -5,6 +5,7 @@
 // ---------------------------------------------------------------------------
 
 import { agentRuntimeProperty } from "./agentRuntime";
+import { tabIdProperty } from "./tabId";
 
 export interface BrowserSystemMeta {
   user_agent: string;
@@ -17,6 +18,8 @@ export interface BrowserSystemMeta {
   studio_version: string;
   /** Which coding agent is driving this Studio, or null when a person is. */
   agent_runtime: string;
+  /** One id per page load. distinct_id identifies a browser, not a page. */
+  tab_id: string;
 }
 
 const EMPTY_META: BrowserSystemMeta = {
@@ -29,6 +32,7 @@ const EMPTY_META: BrowserSystemMeta = {
   is_mobile: false,
   studio_version: "dev",
   agent_runtime: "none",
+  tab_id: "unknown",
 };
 
 let cached: BrowserSystemMeta | null = null;
@@ -54,6 +58,8 @@ export function getBrowserSystemMeta(): BrowserSystemMeta {
     // Same value the `studio:*` transport attaches, from the same accessor —
     // two families that disagreed here would split every agent breakdown.
     agent_runtime: agentRuntimeProperty(),
+    // Same shared module as the `studio:*` transport, for the same reason.
+    tab_id: tabIdProperty(),
   };
   return cached;
 }

package/src/telemetry/tabId.test.ts

@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resetTabIdForTests, resolveTabId, tabIdProperty } from "./tabId";
+
+afterEach(() => {
+  resetTabIdForTests();
+});
+
+describe("tab id", () => {
+  it("is stable for the life of the page", () => {
+    // The whole value of the property: every event from one page load must
+    // carry the SAME id, or a burst still reads as several sources.
+    const first = resolveTabId();
+    expect(resolveTabId()).toBe(first);
+    expect(tabIdProperty()).toBe(first);
+  });
+
+  it("is not empty, since an empty value would read as an absent one", () => {
+    expect(resolveTabId().length).toBeGreaterThan(0);
+  });
+
+  it("mints a new id after a fresh page load", () => {
+    // resetTabIdForTests stands in for a reload: the memo is all that survives
+    // a page, so clearing it is exactly what a reload does.
+    const first = resolveTabId();
+    resetTabIdForTests();
+    expect(resolveTabId()).not.toBe(first);
+  });
+
+  it("never touches storage", () => {
+    // Deliberate: a stored id would drift into a tab-session id, silently
+    // changing what every query means. This asserts the intent directly rather
+    // than inferring it, so adding a read OR a write fails here.
+    const seen: string[] = [];
+    vi.stubGlobal("localStorage", {
+      getItem: (k: string) => (seen.push(`get:${k}`), null),
+      setItem: (k: string) => void seen.push(`set:${k}`),
+      removeItem: (k: string) => void seen.push(`remove:${k}`),
+    });
+    resolveTabId();
+    expect(seen).toEqual([]);
+    vi.unstubAllGlobals();
+  });
+});