@hyperframes/studio 0.7.90 → 0.7.93

package/src/hooks/useGsapKeyframeOps.test.tsx

@@ -7,9 +7,20 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import type { KeyframeCacheEntry } from "../player/store/playerStore";
+import { usePlayerStore } from "../player/store/playerStore";
 import { useGsapKeyframeOps } from "./useGsapKeyframeOps";
 
 type HookApi = ReturnType<typeof useGsapKeyframeOps>;
+type CommitResult = { ok: boolean; changed: boolean };
+type CommitOptions = { onResult?: (result: CommitResult) => void };
+type CommitCall = [selection: unknown, mutation: unknown, options: CommitOptions];
+
+function readCommitOptions(args: unknown[]): CommitOptions {
+  // The hook accepts the production writer type; these test doubles expose only
+  // the third tuple member they exercise.
+  return (args as unknown as CommitCall)[2];
+}
 
 let cleanup: (() => void) | null = null;
 afterEach(() => {
@@ -21,15 +32,14 @@ const selection: DomEditSelection = { id: "box", selector: "#box" } as DomEditSe
 
 function successfulCommitMutation() {
   return vi.fn<(...args: unknown[]) => Promise<unknown>>(async (...args) => {
-    const options = args[2] as {
-      onResult?: (result: { ok: boolean; changed: boolean }) => void;
-    };
+    const options = readCommitOptions(args);
     options.onResult?.({ ok: true, changed: true });
   });
 }
 
 function renderKeyframeOps(over: {
   commitMutation: (...args: unknown[]) => Promise<unknown>;
+  commitMutationSafely?: (...args: unknown[]) => Promise<void>;
   trackGsapSaveFailure: (...args: unknown[]) => void;
 }) {
   const captured: { api: HookApi | null } = { api: null };
@@ -41,7 +51,7 @@ function renderKeyframeOps(over: {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any -- test doubles
       commitMutation: over.commitMutation as any,
       // eslint-disable-next-line @typescript-eslint/no-explicit-any -- test doubles
-      commitMutationSafely: (() => {}) as any,
+      commitMutationSafely: (over.commitMutationSafely ?? (async () => {})) as any,
       // eslint-disable-next-line @typescript-eslint/no-explicit-any -- test doubles
       trackGsapSaveFailure: over.trackGsapSaveFailure as any,
       sdkSession: null,
@@ -135,7 +145,7 @@ describe("useGsapKeyframeOps — moveKeyframe settlement", () => {
 
   it("returns false when the writer accepts but does not change the keyframe", async () => {
     const commitMutation = vi.fn(async (...args: unknown[]) => {
-      const options = args[2] as { onResult?: (result: { ok: boolean; changed: boolean }) => void };
+      const options = readCommitOptions(args);
       options.onResult?.({ ok: true, changed: false });
     });
     const { committed, trackGsapSaveFailure } = await moveKeyframeWith(commitMutation);
@@ -203,6 +213,74 @@ describe("useGsapKeyframeOps — keyframe transaction options", () => {
     );
   });
 
+  it("clears delete-all cache only when persistence confirms the change", async () => {
+    let finishCommit: (() => void) | undefined;
+    const commitMutationSafely = vi.fn(
+      (...args: unknown[]) =>
+        new Promise<void>((resolve) => {
+          const options = readCommitOptions(args);
+          finishCommit = () => {
+            options.onResult?.({ ok: true, changed: true });
+            resolve();
+          };
+        }),
+    );
+    const api = renderKeyframeOps({
+      commitMutation: successfulCommitMutation(),
+      commitMutationSafely,
+      trackGsapSaveFailure: vi.fn(),
+    });
+    const cached: KeyframeCacheEntry = {
+      format: "percentage",
+      keyframes: [
+        { percentage: 0, properties: { x: 0 } },
+        { percentage: 100, properties: { x: 200 } },
+      ],
+    };
+    usePlayerStore.setState({ keyframeCache: new Map([["index.html#box", cached]]) });
+
+    const pending = api.removeAllKeyframes(selection, "box-to-0-position");
+    expect(commitMutationSafely).toHaveBeenCalledWith(
+      selection,
+      { type: "remove-all-keyframes", animationId: "box-to-0-position" },
+      expect.objectContaining({ label: "Remove all keyframes", softReload: true }),
+    );
+    expect(usePlayerStore.getState().keyframeCache.get("index.html#box")).toBe(cached);
+
+    finishCommit?.();
+    await pending;
+    expect(usePlayerStore.getState().keyframeCache.has("index.html#box")).toBe(false);
+  });
+
+  it("clears the live DOM identity for a selector-only selection", async () => {
+    const element = document.createElement("div");
+    element.id = "box";
+    const selectorOnlySelection: DomEditSelection = {
+      ...selection,
+      id: undefined,
+      selector: ".box",
+      element,
+    };
+    const commitMutationSafely = vi.fn(async (...args: unknown[]) => {
+      const options = readCommitOptions(args);
+      options.onResult?.({ ok: true, changed: true });
+    });
+    const api = renderKeyframeOps({
+      commitMutation: successfulCommitMutation(),
+      commitMutationSafely,
+      trackGsapSaveFailure: vi.fn(),
+    });
+    const cached: KeyframeCacheEntry = {
+      format: "percentage",
+      keyframes: [{ percentage: 0, properties: { x: 0 } }],
+    };
+    usePlayerStore.setState({ keyframeCache: new Map([["index.html#box", cached]]) });
+
+    await api.removeAllKeyframes(selectorOnlySelection, "box-to-0-position");
+
+    expect(usePlayerStore.getState().keyframeCache.has("index.html#box")).toBe(false);
+  });
+
   it("threads one coalesce key through skipped convert reload and terminal batch edit", async () => {
     const commitMutation = successfulCommitMutation();
     const api = renderKeyframeOps({ commitMutation, trackGsapSaveFailure: vi.fn() });

package/src/hooks/useGsapKeyframeOps.ts

@@ -15,7 +15,6 @@ import {
 } from "../utils/sdkCutover";
 import type { KeyframeCacheEntry } from "../player/store/playerStore";
 import { commitKeyframeAtTimeImpl } from "./gsapKeyframeCommit";
-import { idFromSelector } from "./gsapShared";
 import {
   clearKeyframeCacheForElement,
   readKeyframeSnapshot,
@@ -336,11 +335,9 @@ export function useGsapKeyframeOps({
   const removeAllKeyframes = useCallback(
     async (selection: DomEditSelection, animationId: string) => {
       const targetPath = selection.sourceFile || activeCompPath || "index.html";
-      // remove-all-keyframes collapses the tween to a static hold and the commit
-      // path doesn't return parsed animations, so the keyframe cache is never
-      // refreshed — clear it here so the timeline diamonds disappear immediately.
-      const elementId = selection.id ?? idFromSelector(selection.selector);
-      if (elementId) clearKeyframeCacheForElement(targetPath, elementId);
+      // A class/descendant selector can resolve a live element whose selection
+      // deliberately has no id. The cache is still keyed by that DOM id.
+      const cacheElementId = selection.id || selection.element?.id;
       if (sdkSession && sdkDeps) {
         const handled = await sdkGsapRemoveAllKeyframesPersist(
           targetPath,
@@ -349,12 +346,26 @@ export function useGsapKeyframeOps({
           sdkDeps,
           { label: "Remove all keyframes" },
         );
-        if (cutoverCommittedOrThrow(handled)) return;
+        if (cutoverCommittedOrThrow(handled)) {
+          if (cacheElementId) clearKeyframeCacheForElement(targetPath, cacheElementId);
+          return;
+        }
       }
-      commitMutationSafely(
+      await commitMutationSafely(
         selection,
         { type: "remove-all-keyframes", animationId },
-        { label: "Remove all keyframes", softReload: true },
+        {
+          label: "Remove all keyframes",
+          softReload: true,
+          // The committed result is the single success boundary: clearing
+          // before it makes failed saves lie, while waiting for the reload leaves
+          // stale diamonds visible during the source round-trip.
+          onResult: (result) => {
+            if (result.changed !== false && cacheElementId) {
+              clearKeyframeCacheForElement(targetPath, cacheElementId);
+            }
+          },
+        },
       );
     },
     [commitMutationSafely, activeCompPath, sdkSession, sdkDeps],

package/src/hooks/usePreviewPersistence.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it, vi } from "vitest";
+import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
+import { drainStudioSaveQueues } from "./usePreviewPersistence";
+
+describe("drainStudioSaveQueues", () => {
+  it("does not erase a pending-field conflict with a clean DOM queue", async () => {
+    const conflict = new StudioFileConflictError({
+      filePath: "index.html",
+      currentVersion: "v2",
+      currentContent: "external",
+      attemptedContent: "studio",
+    });
+    const waitForDomQueue = vi.fn(async () => ({ status: "clean" as const }));
+
+    await expect(
+      drainStudioSaveQueues(
+        async () => ({ status: "conflict" as const, error: conflict }),
+        waitForDomQueue,
+      ),
+    ).resolves.toEqual({ status: "conflict", error: conflict });
+    expect(waitForDomQueue).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/usePreviewPersistence.ts

@@ -3,12 +3,14 @@ import { useMountEffect } from "./useMountEffect";
 import {
   installStudioManualEditSeekReapply,
   reapplyPositionEditsAfterSeek,
-  readStudioFileChangePath,
 } from "../components/editor/manualEdits";
 import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
 import type { EditHistoryKind } from "../utils/editHistory";
-import { createDomEditSaveQueue } from "../utils/domEditSaveQueue";
-import { flushStudioPendingEdits } from "../utils/studioPendingEdits";
+import { createDomEditSaveQueue, type DomEditSaveDrainResult } from "../utils/domEditSaveQueue";
+import {
+  flushStudioPendingEdits,
+  type StudioPendingEditsDrainResult,
+} from "../utils/studioPendingEdits";
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import { applyUndoRestoreToPreview, type UndoRestoreFile } from "../utils/gsapUndoRestore";
 import { usePlayerStore } from "../player";
@@ -29,19 +31,12 @@ interface RecordEditInput {
 }
 
 interface UsePreviewPersistenceParams {
-  projectId: string | null;
   showToast: (message: string, tone?: "error" | "info") => void;
   readOptionalProjectFile: (path: string) => Promise<string>;
   writeProjectFile: (path: string, content: string) => Promise<void>;
   recordEdit: (entry: RecordEditInput) => Promise<void>;
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
   activeCompPathRef: React.MutableRefObject<string | null>;
-  /** Shared timestamp ref — written by any studio save (code tab, timeline, DOM edits).
-   *  Used to suppress file-change echoes so we don't reload after our own saves. */
-  domEditSaveTimestampRef: React.MutableRefObject<number>;
-  /** Tracks in-flight timeline edits that patch the iframe DOM directly. File-change
-   *  events for these paths are always suppressed since the preview is already up-to-date. */
-  pendingTimelineEditPathRef?: React.MutableRefObject<Set<string>>;
   /** Called to reload the preview after undo/redo or external file changes. */
   reloadPreview: () => void;
 }
@@ -71,19 +66,13 @@ function installManualEditReapply(iframe: HTMLIFrameElement): void {
   }
 }
 
-function shouldReloadForStudioFileChange(
-  payload: unknown,
-  pendingTimelineEditPathRef: React.MutableRefObject<Set<string>> | undefined,
-  domEditSaveTimestampRef: React.MutableRefObject<number>,
-): boolean {
-  const changedPath = readStudioFileChangePath(payload);
-  if (!changedPath) return false;
-  const pendingTimelinePaths = pendingTimelineEditPathRef?.current;
-  if (pendingTimelinePaths?.has(changedPath)) {
-    pendingTimelinePaths.delete(changedPath);
-    return false;
-  }
-  return Date.now() - domEditSaveTimestampRef.current >= 4000;
+export async function drainStudioSaveQueues(
+  flushPendingFields: () => Promise<StudioPendingEditsDrainResult>,
+  waitForDomQueue: () => Promise<DomEditSaveDrainResult>,
+): Promise<StudioPendingEditsDrainResult | DomEditSaveDrainResult> {
+  const pending = await flushPendingFields();
+  if (pending.status !== "clean") return pending;
+  return waitForDomQueue();
 }
 
 // fallow-ignore-next-line complexity
@@ -107,16 +96,13 @@ async function clearLegacyStudioMotionFile(
 // ── Hook ──
 
 export function usePreviewPersistence({
-  projectId,
   showToast,
   readOptionalProjectFile: _readOptionalProjectFile,
   writeProjectFile: _writeProjectFile,
   recordEdit: _recordEdit,
   previewIframeRef,
   activeCompPathRef,
-  domEditSaveTimestampRef,
   reloadPreview,
-  pendingTimelineEditPathRef,
 }: UsePreviewPersistenceParams) {
   void _recordEdit;
 
@@ -152,22 +138,23 @@ export function usePreviewPersistence({
     });
   }
 
-  // Keep a ref to the latest projectId so async save callbacks always read the
-  // current value, even when the callback was captured in a stale closure.
-  const projectIdRef = useRef(projectId);
-  projectIdRef.current = projectId;
-
   // ── Queue / drain helpers ──
 
   const queueDomEditSave = useCallback(<T>(save: () => Promise<T>): Promise<T> => {
     return domEditSaveQueueRef.current?.enqueue(save) ?? save();
   }, []);
 
-  const waitForPendingDomEditSaves = useCallback(async () => {
-    await flushStudioPendingEdits();
-    await domEditSaveQueueRef.current?.waitForIdle();
+  const drainPendingDomEditSaves = useCallback(async () => {
+    return drainStudioSaveQueues(flushStudioPendingEdits, async () => {
+      return (await domEditSaveQueueRef.current?.waitForIdle()) ?? { status: "clean" as const };
+    });
   }, []);
 
+  const waitForPendingDomEditSaves = useCallback(async (): Promise<void> => {
+    const result = await drainPendingDomEditSaves();
+    if (result.status !== "clean") throw result.error;
+  }, [drainPendingDomEditSaves]);
+
   const resetDomEditSaveQueueBreaker = useCallback(() => {
     domEditSaveQueueRef.current?.reset();
     setDomEditSaveQueuePaused(null);
@@ -235,35 +222,12 @@ export function usePreviewPersistence({
     void clearLegacyStudioMotionFile(_readOptionalProjectFile, _writeProjectFile);
   });
 
-  // ── Listen for external file changes (HMR / SSE) ──
-  useMountEffect(() => {
-    const handler = (payload?: unknown) => {
-      if (
-        shouldReloadForStudioFileChange(
-          payload,
-          pendingTimelineEditPathRef,
-          domEditSaveTimestampRef,
-        )
-      ) {
-        // fallow-ignore-next-line code-duplication
-        reloadPreview();
-      }
-    };
-    if (import.meta.hot) {
-      import.meta.hot.on("hf:file-change", handler);
-      return () => import.meta.hot?.off?.("hf:file-change", handler);
-    }
-    // SSE fallback for embedded studio server
-    const es = new EventSource("/api/events");
-    es.addEventListener("file-change", handler);
-    return () => es.close();
-  });
-
   return {
     domTextCommitVersionRef,
     domEditSaveQueueRef,
     applyStudioManualEditsToPreviewRef,
     queueDomEditSave,
+    drainPendingDomEditSaves,
     waitForPendingDomEditSaves,
     domEditSaveQueuePaused,
     resetDomEditSaveQueueBreaker,

package/src/hooks/useSdkSession.ts

@@ -1,11 +1,11 @@
 import { useState, useEffect, useCallback, useRef } from "react";
-import type { MutableRefObject } from "react";
 import { openComposition } from "@hyperframes/sdk";
 import type { Composition } from "@hyperframes/sdk";
 import { readStudioFileChangePath } from "../components/editor/manualEdits";
 import { isSelfWriteEcho } from "./sdkSelfWriteRegistry";
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import type { PublishSdkSession } from "../utils/sdkCutover";
+import { addExternalFileReloadListener } from "./externalFileReloadBus";
 
 /**
  * Read a project file's content, or undefined on a non-2xx (optional read).
@@ -48,22 +48,6 @@ export function shouldReloadSdkSession(payload: unknown, activeCompPath: string
  * stale. The session has NO persist queue — Studio is the sole file writer; see
  * the open effect below.
  */
-// Reload-suppression baseline: a file-change within this window of our own SDK
-// cutover write is a CANDIDATE echo, but the decision is content-identity based
-// (isSelfWriteEcho) not time-only — so an undo write that lands inside the window
-// still reloads (its reverted bytes were never registered as a self-write). The
-// window only bounds how long a registered self-write stays suppressible.
-const SELF_WRITE_SUPPRESS_MS = 2000;
-
-/** Best-effort read of the changed file's content from a file-change payload. */
-function readFileChangeContent(payload: unknown): string | null {
-  if (!payload || typeof payload !== "object") return null;
-  const record = payload as Record<string, unknown>;
-  if (typeof record.content === "string") return record.content;
-  if ("data" in record) return readFileChangeContent(record.data);
-  return null;
-}
-
 /**
  * Decide whether a file-change for the active composition should reload the SDK
  * session. `content` is the new on-disk bytes (from the payload or a re-read);
@@ -157,7 +141,6 @@ function disposeSdkSession(session: Composition): void {
 export function useSdkSession(
   projectId: string | null,
   activeCompPath: string | null,
-  domEditSaveTimestampRef?: MutableRefObject<number>,
 ): SdkSessionHandle {
   const [ownedSession, setOwnedSession] = useState<OwnedSdkSession | null>(null);
   const ownedSessionRef = useRef<OwnedSdkSession | null>(null);
@@ -171,40 +154,13 @@ export function useSdkSession(
   const reloadTokenRef = useRef(reloadToken);
   reloadTokenRef.current = reloadToken;
 
-  // ── Re-open on external change to the active composition ──
-  useEffect(() => {
-    if (!activeCompPath) return;
-    const compPath = activeCompPath;
-    const readProjectId = projectId ?? null;
-    const handler = (payload?: unknown) => {
-      if (!shouldReloadSdkSession(payload, compPath)) return;
-      const withinWindow =
-        !!domEditSaveTimestampRef &&
-        Date.now() - domEditSaveTimestampRef.current < SELF_WRITE_SUPPRESS_MS;
-      const decide = (content: string | null) => {
-        if (shouldReloadOnFileChange(compPath, content, withinWindow)) setReloadToken((t) => t + 1);
-      };
-      const payloadContent = readFileChangeContent(payload);
-      // Prefer payload content; otherwise re-read so the decision is by IDENTITY
-      // (an undo's reverted bytes won't match a registered self-write → reload).
-      if (payloadContent != null || readProjectId == null) {
-        decide(payloadContent);
-        return;
-      }
-      readProjectFileOptional(readProjectId, compPath)
-        .then((c) => decide(c ?? null))
-        .catch(() => decide(null));
-    };
-    if (import.meta.hot) {
-      import.meta.hot.on("hf:file-change", handler);
-      return () => import.meta.hot?.off?.("hf:file-change", handler);
-    }
-    // SSE fallback for the embedded studio server.
-    const es = new EventSource("/api/events");
-    es.addEventListener("file-change", handler);
-    return () => es.close();
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [activeCompPath, projectId]);
+  useEffect(
+    () =>
+      addExternalFileReloadListener((changedPath) => {
+        if (changedPath === activeCompPathRef.current) setReloadToken((token) => token + 1);
+      }),
+    [],
+  );
 
   // ── Open / re-open the session ──
   useEffect(() => {

package/src/hooks/useStudioExternalFileChanges.ts

@@ -0,0 +1,81 @@
+import { useCallback, type MutableRefObject } from "react";
+import {
+  deleteExternalConflictSnapshot,
+  loadExternalConflictSnapshot,
+  persistExternalConflictSnapshot,
+  persistExternalFailureSnapshot,
+} from "../utils/externalConflictStorage";
+import { notifyExternalFileReload } from "./externalFileReloadBus";
+import { useExternalFileChangeCoordinator } from "./useExternalFileChangeCoordinator";
+import type { useFileManager } from "./useFileManager";
+import type { usePreviewPersistence } from "./usePreviewPersistence";
+
+type FileManager = Pick<
+  ReturnType<typeof useFileManager>,
+  | "editingFile"
+  | "flushPendingSourceSave"
+  | "discardPendingSourceSave"
+  | "getPendingSourceCandidate"
+  | "overwriteExternalConflict"
+  | "readProjectFile"
+  | "updateEditingFileContent"
+>;
+
+type PreviewPersistence = Pick<
+  ReturnType<typeof usePreviewPersistence>,
+  "drainPendingDomEditSaves" | "resetDomEditSaveQueueBreaker"
+>;
+
+interface UseStudioExternalFileChangesOptions {
+  projectId: string | null;
+  activeCompPath: string | null;
+  masterCompPath: string | null;
+  fileManager: FileManager;
+  previewPersistence: PreviewPersistence;
+  pendingTimelineEditPathRef: MutableRefObject<Set<string>>;
+  reloadPreview: () => void;
+}
+
+/** Connects the app's save queues, recovery storage, and reload surfaces to one owner. */
+export function useStudioExternalFileChanges({
+  projectId,
+  activeCompPath,
+  masterCompPath,
+  fileManager,
+  previewPersistence,
+  pendingTimelineEditPathRef,
+  reloadPreview,
+}: UseStudioExternalFileChangesOptions) {
+  const { flushPendingSourceSave, discardPendingSourceSave } = fileManager;
+  const { drainPendingDomEditSaves, resetDomEditSaveQueueBreaker } = previewPersistence;
+  const drainPendingChanges = useCallback(async () => {
+    const source = await flushPendingSourceSave();
+    if (source.status !== "clean") return source;
+    return drainPendingDomEditSaves();
+  }, [drainPendingDomEditSaves, flushPendingSourceSave]);
+
+  const discardPendingChanges = useCallback(() => {
+    discardPendingSourceSave();
+    resetDomEditSaveQueueBreaker();
+  }, [discardPendingSourceSave, resetDomEditSaveQueueBreaker]);
+
+  return useExternalFileChangeCoordinator({
+    projectId,
+    activeCompPath,
+    recoveryFilePath: fileManager.editingFile?.path ?? activeCompPath ?? masterCompPath,
+    pendingTimelineEditPathRef,
+    drainPendingChanges,
+    getPendingCandidate: fileManager.getPendingSourceCandidate,
+    discardPendingChanges,
+    reloadPreview,
+    reloadSdkSession: notifyExternalFileReload,
+    persistConflictSnapshot: persistExternalConflictSnapshot,
+    persistFailureSnapshot: persistExternalFailureSnapshot,
+    loadConflictSnapshot: loadExternalConflictSnapshot,
+    deleteConflictSnapshot: deleteExternalConflictSnapshot,
+    overwriteConflict: fileManager.overwriteExternalConflict,
+    readProjectFile: fileManager.readProjectFile,
+    onUseExternalFile: fileManager.updateEditingFileContent,
+    resetSaveQueues: resetDomEditSaveQueueBreaker,
+  });
+}

package/src/hooks/useStudioSdkSessions.ts

@@ -1,4 +1,4 @@
-import { useEffect, type MutableRefObject } from "react";
+import { useEffect } from "react";
 import { useSdkSession } from "./useSdkSession";
 import { usePreviewVariablesStore } from "./previewVariablesStore";
 
@@ -17,18 +17,13 @@ import { usePreviewVariablesStore } from "./previewVariablesStore";
 export function useStudioSdkSessions(
   projectId: string | null,
   activeCompPath: string | null,
-  domEditSaveTimestampRef: MutableRefObject<number>,
   masterCompPath: string | null,
 ) {
   // On the master view (no explicit comp) the schema panels target the project's
   // resolved main composition — the first `.html` in the tree, not a hardcoded
   // "index.html" that may not exist. `null` when the project has no composition
   // yet, which correctly leaves the session (and the panels) empty.
-  const sdkHandle = useSdkSession(
-    projectId,
-    activeCompPath ?? masterCompPath,
-    domEditSaveTimestampRef,
-  );
+  const sdkHandle = useSdkSession(projectId, activeCompPath ?? masterCompPath);
   const editFlowSdkSession = activeCompPath ? sdkHandle.session : null;
   useEffect(() => {
     usePreviewVariablesStore.getState().setValues(null);

package/src/hooks/useStudioSessionStart.ts

@@ -0,0 +1,15 @@
+import { useEffect } from "react";
+import { hasFiredSessionStart, markSessionStartFired } from "../telemetry/config";
+import { trackStudioSessionStart } from "../telemetry/events";
+
+export function useStudioSessionStart(
+  projectId: string | null,
+  resolving: boolean,
+  waitingForServer: boolean,
+): void {
+  useEffect(() => {
+    if (resolving || waitingForServer || hasFiredSessionStart()) return;
+    markSessionStartFired();
+    trackStudioSessionStart({ has_project: projectId != null });
+  }, [projectId, resolving, waitingForServer]);
+}

package/src/hooks/useStudioTestHooks.test.tsx

@@ -59,11 +59,15 @@ describe("timeline performance fixture", () => {
     expect(Math.max(...perTrack.values())).toBeLessThanOrEqual(128);
   });
 
-  it.each(PROFILES)("generates an identical 50k %s fixture", (profile) => {
-    const first = createTimelinePerformanceFixture({ elementCount: 50_000, profile });
-    const second = createTimelinePerformanceFixture({ elementCount: 50_000, profile });
-    expect(second).toEqual(first);
-  });
+  it.each(PROFILES)(
+    "generates an identical 50k %s fixture",
+    (profile) => {
+      const first = createTimelinePerformanceFixture({ elementCount: 50_000, profile });
+      const second = createTimelinePerformanceFixture({ elementCount: 50_000, profile });
+      expect(second).toEqual(first);
+    },
+    30_000,
+  );
 
   it.each(PROFILES)("builds the %s 1k scale profile", (profile) => {
     const fixture = createTimelinePerformanceFixture({ elementCount: 1_000, profile });
@@ -90,7 +94,7 @@ describe("timeline performance fixture", () => {
     usePlayerStore.setState({
       isPlaying: true,
       requestedSeekTime: 42,
-      clipRevealRequest: { elementId: "stale", nonce: 7 },
+      timelineFocus: { id: "stale", projectId: null, sessionEpoch: 0, nonce: 7 },
       clipManifest: [],
       lintFindingsByElement: new Map([["stale", { count: 1, messages: ["stale"] }]]),
     });
@@ -108,7 +112,7 @@ describe("timeline performance fixture", () => {
     expect(usePlayerStore.getState()).toMatchObject({
       isPlaying: false,
       requestedSeekTime: null,
-      clipRevealRequest: null,
+      timelineFocus: null,
       clipManifest: null,
       duration: 600,
       timelineReady: true,