@hyperframes/studio 0.8.56 → 0.8.58

package/src/player/hooks/useTimelinePlayer.ts

@@ -3,6 +3,8 @@ import { usePlayerStore, liveTime, type TimelineElement } from "../store/playerS
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { usePlaybackKeyboard } from "./usePlaybackKeyboard";
 import { useTimelineSyncCallbacks } from "./useTimelineSyncCallbacks";
+import { useShadowPreviewReload } from "./useShadowPreviewReload";
+import { resolvePlaybackAdapter } from "./playbackAdapterResolution";
 import { useTimelinePlayerLoop } from "./useTimelinePlayerLoop";
 import { logReload } from "../../utils/reloadDebug";
 
@@ -24,18 +26,8 @@ export {
 } from "../lib/playbackShortcuts";
 
 import type { PlaybackAdapter, IframeWindow } from "../lib/playbackTypes";
-import {
-  getAdapterDuration,
-  wrapTimeline,
-  getDefaultStaticSeekPlaybackClock,
-  releaseStaticSeekCache,
-  resolveStaticSeekFallback,
-  type StaticSeekCacheEntry,
-} from "../lib/playbackAdapter";
-import {
-  readTimelineDurationFromDocument,
-  mergeTimelineElementsPreservingDowngrades,
-} from "../lib/timelineDOM";
+import { releaseStaticSeekCache, type StaticSeekCacheEntry } from "../lib/playbackAdapter";
+import { mergeTimelineElementsPreservingDowngrades } from "../lib/timelineDOM";
 import { normalizeToZones } from "../components/timelineZones";
 import { applyPreviewAudioFlags, setPreviewPlaybackRate } from "../lib/timelineIframeHelpers";
 import { scrubMusicAtSeek, stopScrubPreviewAudio } from "../lib/playbackScrub";
@@ -47,7 +39,17 @@ import { createPreviewMessageHandler } from "./previewMessageRouter";
 import { timelineElementsChanged } from "./timelinePlayerSync";
 import { safeContentDocument } from "./timelineSyncHydration";
 
-export function useTimelinePlayer() {
+export interface UseTimelinePlayerOptions {
+  /** Runs right after a reloaded preview becomes the live iframe. */
+  onShadowPromoted?: () => void;
+  /** A reload was abandoned (cause in the message); the previous preview is still showing. */
+  onPreviewReloadFailed?: (message: string) => void;
+}
+
+export function useTimelinePlayer({
+  onShadowPromoted,
+  onPreviewReloadFailed,
+}: UseTimelinePlayerOptions = {}) {
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
   const rafRef = useRef<number>(0);
   const probeIntervalRef = useRef<ReturnType<typeof setInterval> | undefined>(undefined);
@@ -128,84 +130,23 @@ export function useTimelinePlayer() {
     [setElements, requestTimelineReady, setDuration],
   );
 
-  // Pre-existing dispatcher complexity — surfaced by this PR's line shifts, not new logic.
-  // fallow-ignore-next-line complexity
-  const getAdapter = useCallback((): PlaybackAdapter | null => {
-    try {
-      const iframe = iframeRef.current;
-      const win = iframe?.contentWindow as IframeWindow | null;
-      if (!iframe || !win) return null;
-
-      const playerAdapter =
-        win.__player && typeof win.__player.play === "function" ? win.__player : null;
-      const docDuration = readTimelineDurationFromDocument(iframe.contentDocument);
-      const adapterDur = getAdapterDuration(playerAdapter);
-
-      if (adapterDur > 0 && docDuration <= adapterDur) {
-        releaseStaticSeekCache(staticSeekAdapterRef, staticSeekWarnedRef);
-        return playerAdapter;
-      }
-
-      let timelineAdapter: PlaybackAdapter | null = null;
-      if (win.__timeline) {
-        const adapter = wrapTimeline(win.__timeline);
-        const dur = getAdapterDuration(adapter);
-        if (dur > 0 && docDuration <= dur) {
-          releaseStaticSeekCache(staticSeekAdapterRef, staticSeekWarnedRef);
-          return adapter;
-        }
-        if (dur > 0) timelineAdapter ??= adapter;
-      }
-
-      if (win.__timelines) {
-        const keys = Object.keys(win.__timelines);
-        if (keys.length > 0) {
-          // Resolve the root composition id from the DOM — the outermost [data-composition-id]
-          // is the master; otherwise Object.keys() order lets a sub-composition hijack transport.
-          const rootId = iframe?.contentDocument
-            ?.querySelector("[data-composition-id]")
-            ?.getAttribute("data-composition-id");
-          const key = rootId && rootId in win.__timelines ? rootId : keys[keys.length - 1];
-          const adapter = wrapTimeline(win.__timelines[key]);
-          const dur = getAdapterDuration(adapter);
-          if (dur > 0 && docDuration <= dur) {
-            releaseStaticSeekCache(staticSeekAdapterRef, staticSeekWarnedRef);
-            return adapter;
-          }
-          if (dur > 0) timelineAdapter ??= adapter;
-        }
-      }
-
-      // The document timeline extends past every native adapter's duration.
-      // Wrap the best available adapter with the effective duration so the
-      // seek slider, seek clamping, and duration display cover the full range.
-      const bestAdapter = playerAdapter ?? timelineAdapter;
-      const effectiveDuration = Math.max(
-        usePlayerStore.getState().duration,
-        docDuration,
-        adapterDur,
-      );
-      if (
-        bestAdapter &&
-        effectiveDuration > 0 &&
-        ("renderSeek" in bestAdapter || typeof bestAdapter.seek === "function")
-      ) {
-        return resolveStaticSeekFallback({
+  const getAdapter = useCallback(
+    (overrideIframe?: HTMLIFrameElement | null): PlaybackAdapter | null => {
+      try {
+        // undefined means "no override"; an explicit null override means "no adapter".
+        const iframe = overrideIframe !== undefined ? overrideIframe : iframeRef.current;
+        const win = iframe?.contentWindow as IframeWindow | null;
+        if (!iframe || !win) return null;
+        return resolvePlaybackAdapter(iframe, win, {
           cache: staticSeekAdapterRef,
           warned: staticSeekWarnedRef,
-          bestAdapter,
-          effectiveDuration,
-          docDuration,
-          clock: getDefaultStaticSeekPlaybackClock(win),
-          getPlaybackRate: () => usePlayerStore.getState().playbackRate,
         });
+      } catch {
+        return null;
       }
-
-      return bestAdapter;
-    } catch {
-      return null;
-    }
-  }, []);
+    },
+    [],
+  );
 
   const { startRAFLoop, stopRAFLoop, stopReverseLoop } = useTimelinePlayerLoop({
     rafRef,
@@ -435,6 +376,32 @@ export function useTimelinePlayer() {
       attachIframeShortcutListeners,
       applyPreviewAudioState,
     });
+
+  // Full-reload edits load behind a hidden shadow iframe (useShadowPreviewReload.ts).
+  const {
+    previewSlots,
+    onShadowIframeLoad,
+    onShadowReadyChange,
+    onShadowError,
+    setShadowIframeNode,
+    beginShadowReload,
+    resetPreviewSlots,
+  } = useShadowPreviewReload({
+    iframeRef,
+    getAdapter,
+    pendingSeekRef,
+    isRefreshingRef,
+    syncTimelineElements,
+    setDuration,
+    setCurrentTime,
+    requestTimelineReady,
+    setIsPlaying,
+    attachIframeShortcutListeners,
+    applyPreviewAudioState,
+    onPromoted: onShadowPromoted,
+    onReloadFailed: onPreviewReloadFailed,
+  });
+
   const saveSeekPosition = useCallback(() => {
     // Never DEGRADE the saved position. Overlapping reloads (e.g. an external
     // file drop = upload reload + insert reload back-to-back) call this while
@@ -464,22 +431,15 @@ export function useTimelinePlayer() {
     if (!iframe) return;
     logReload("refreshPlayer", () => ({ stack: new Error("refreshPlayer").stack }));
     saveSeekPosition();
-    // Hide the iframe across the full reload so the user never sees the reloading
-    // document's RAW DOM (every clip stacked and visible) in the window between the
-    // new document parsing and the runtime initializing + seeking. initializeAdapter
-    // reveals it again right after its restore seek renders the correct frame.
-    // Tradeoff: this shows the parent stage background (a brief "freeze"/blank, on
-    // the order of the reload time ~100-300ms) INSTEAD of the all-clips flash. A
-    // blank is far less jarring than a burst of every asset appearing at once.
-    // Only the FULL-reload edits (drops/inserts) hit this — timing edits now take
-    // the soft-reload path and never touch refreshPlayer.
-    iframe.style.visibility = "hidden";
+    // The old iframe is no longer navigated away, so stop its playback (and audio) here.
+    getAdapter()?.pause();
+    // The live iframe is never hidden; the reload loads in a shadow and is promoted once painted.
     const src = iframe.src;
     const url = new URL(src, window.location.origin);
     url.searchParams.set("_t", String(Date.now()));
     applyPreviewVariablesToUrl(url);
-    iframe.src = url.toString();
-  }, [saveSeekPosition]);
+    beginShadowReload(url.toString());
+  }, [saveSeekPosition, getAdapter, beginShadowReload]);
   const getAdapterRef = useRef(getAdapter);
   getAdapterRef.current = getAdapter;
 
@@ -557,5 +517,11 @@ export function useTimelinePlayer() {
     refreshPlayer,
     saveSeekPosition,
     resetPlayer,
+    previewSlots,
+    onShadowIframeLoad,
+    onShadowReadyChange,
+    onShadowError,
+    setShadowIframeNode,
+    resetPreviewSlots,
   };
 }

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";
@@ -33,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>;
@@ -46,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;
 }
 
 /**
@@ -62,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.
  *
@@ -110,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(
@@ -183,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 };
@@ -283,5 +353,6 @@ export function useTimelineSyncCallbacks({
     enrichMissingCompositionsRef,
     initializeAdapter,
     onIframeLoad,
+    cancelPendingLoad,
   };
 }

package/src/player/index.ts

@@ -7,6 +7,13 @@ export { CompositionThumbnail } from "./components/CompositionThumbnail";
 
 // Hooks
 export { useTimelinePlayer } from "./hooks/useTimelinePlayer";
+export { usePlayerHandle } from "./hooks/usePlayerHandle";
+export type {
+  PlayerHandle,
+  PlayerHandleElement,
+  PlayerHandleListener,
+  PlayerHandleTimeListener,
+} from "./hooks/usePlayerHandle";
 export { resolveIframe } from "./lib/timelineDOM";
 
 // Store

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;
 }