@hyperframes/studio 0.7.92 → 0.7.93

package/src/hooks/useGsapAwareEditing.ts

@@ -30,6 +30,8 @@ import { logResize, logResizeSettle } from "../utils/resizeDebug";
 import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditOverlay";
 import { runGestureTransaction } from "./gestureTransaction";
 import { hasNonHoldTweenForElement } from "./gsapRuntimeKeyframes";
+import { assertGsapEditPersisted } from "./gsapEditOutcome";
+import type { GsapAnimationFetchOptions } from "./useGsapAnimationFetchFallback";
 
 // Distinct coalesceKey per group drag so consecutive group drags don't fold
 // into one another's undo entry (module-local counter, not Date.now()).
@@ -42,7 +44,10 @@ export interface UseGsapAwareEditingParams {
   previewIframeRef: React.RefObject<HTMLIFrameElement | null>;
   showToast: (message: string, tone?: "error" | "info") => void;
   bumpGsapCache: () => void;
-  makeFetchFallback: (selection: DomEditSelection) => () => Promise<GsapAnimation[]>;
+  makeFetchFallback: (
+    selection: DomEditSelection,
+    options?: GsapAnimationFetchOptions,
+  ) => () => Promise<GsapAnimation[]>;
   trackGsapInteractionFailure: (
     error: unknown,
     selection: DomEditSelection,
@@ -112,7 +117,7 @@ export function useGsapAwareEditing({
     ) => {
       if (gsapCommitMutation) {
         try {
-          await tryGsapDragIntercept(
+          const outcome = await tryGsapDragIntercept(
             selection,
             next,
             selectedGsapAnimations,
@@ -121,6 +126,7 @@ export function useGsapAwareEditing({
             makeFetchFallback(selection),
             modifiers,
           );
+          assertGsapEditPersisted(outcome);
         } catch (error) {
           trackGsapInteractionFailure(error, selection, "drag", "Move animated layer");
           throw error;
@@ -155,16 +161,42 @@ export function useGsapAwareEditing({
           coalesceKey,
           coalesceMs: Number.POSITIVE_INFINITY,
         });
+      const preflightAnimations = new Map<DomEditSelection, GsapAnimation[]>();
+      // Editability is user-atomic: prove every member can be written before
+      // the first source mutation. Network failures after this point retain the
+      // existing multi-request semantics, but a blocked member can never leave
+      // earlier siblings partially moved.
+      for (const { selection } of updates) {
+        try {
+          const animations = await makeFetchFallback(selection, { failOnFetchError: true })();
+          preflightAnimations.set(selection, animations);
+          const outcome = await tryGsapDragIntercept(
+            selection,
+            { x: 0, y: 0 },
+            animations,
+            previewIframeRef.current,
+            coalescedCommit,
+            undefined,
+            { preflightOnly: true },
+          );
+          assertGsapEditPersisted(outcome);
+        } catch (error) {
+          trackGsapInteractionFailure(error, selection, "drag", "Move animated layer (group)");
+          throw error;
+        }
+      }
       for (const { selection, next } of updates) {
         try {
-          await tryGsapDragIntercept(
+          const outcome = await tryGsapDragIntercept(
             selection,
             next,
-            [],
+            preflightAnimations.get(selection) ?? [],
             previewIframeRef.current,
             coalescedCommit,
             makeFetchFallback(selection),
+            { preflightPassed: true },
           );
+          assertGsapEditPersisted(outcome);
         } catch (error) {
           trackGsapInteractionFailure(error, selection, "drag", "Move animated layer (group)");
           throw error;
@@ -217,7 +249,7 @@ export function useGsapAwareEditing({
           if (gsapCommitMutation) {
             const commitMutation = commit(gsapCommitMutation);
             try {
-              const handled = await tryGsapResizeIntercept(
+              const outcome = await tryGsapResizeIntercept(
                 selection,
                 next,
                 selectedGsapAnimations,
@@ -225,26 +257,26 @@ export function useGsapAwareEditing({
                 commitMutation,
                 makeFetchFallback(selection),
               );
-              if (handled) {
-                logResize("intercept-handled", {
-                  scaleRoute,
-                  willForwardOffset: !!(offset && !scaleRoute),
-                });
-                // Scale-route resize persists its residual position internally.
-                // Width/height persists the already-settled anchor through drag.
-                if (offset && !scaleRoute) {
-                  await tryGsapDragIntercept(
-                    selection,
-                    offset,
-                    selectedGsapAnimations,
-                    previewIframeRef.current,
-                    commitMutation,
-                    makeFetchFallback(selection),
-                  );
-                }
-                logResizeSettle(selection.element, scaleRoute ? "gsap-scale" : "gsap-size");
-                return;
+              assertGsapEditPersisted(outcome);
+              logResize("intercept-handled", {
+                scaleRoute,
+                willForwardOffset: !!(offset && !scaleRoute),
+              });
+              // Scale-route resize persists its residual position internally.
+              // Width/height persists the already-settled anchor through drag.
+              if (offset && !scaleRoute) {
+                const dragOutcome = await tryGsapDragIntercept(
+                  selection,
+                  offset,
+                  selectedGsapAnimations,
+                  previewIframeRef.current,
+                  commitMutation,
+                  makeFetchFallback(selection),
+                );
+                assertGsapEditPersisted(dragOutcome);
               }
+              logResizeSettle(selection.element, scaleRoute ? "gsap-scale" : "gsap-size");
+              return;
             } catch (error) {
               trackGsapInteractionFailure(error, selection, "resize", "Resize animated layer");
               throw error;
@@ -278,8 +310,9 @@ export function useGsapAwareEditing({
         try {
           // Single source of truth for rotation too: tryGsapRotationIntercept handles
           // tweened elements (keyframes) and static ones (a tl.set), so there's no
-          // CSS-var fallback. It returns false only for a selectorless element (no-op).
-          await tryGsapRotationIntercept(
+          // CSS-var fallback. Selectorless/computed source rejects so the gesture
+          // transaction can restore its draft instead of reporting a false success.
+          const outcome = await tryGsapRotationIntercept(
             selection,
             next.angle,
             selectedGsapAnimations,
@@ -287,6 +320,7 @@ export function useGsapAwareEditing({
             gsapCommitMutation,
             makeFetchFallback(selection),
           );
+          assertGsapEditPersisted(outcome);
         } catch (error) {
           trackGsapInteractionFailure(error, selection, "rotation", "Rotate animated layer");
           throw error;
@@ -304,7 +338,10 @@ export function useGsapAwareEditing({
 
   // ── Animated property commit ──
 
-  const { commitAnimatedProperty, commitAnimatedProperties } = useAnimatedPropertyCommit({
+  const {
+    commitAnimatedProperty: commitAnimatedPropertyRaw,
+    commitAnimatedProperties: commitAnimatedPropertiesRaw,
+  } = useAnimatedPropertyCommit({
     selectedGsapAnimations,
     gsapCommitMutation,
     addGsapAnimation: (sel, method, time) => addGsapAnimation(sel, method, time),
@@ -313,6 +350,30 @@ export function useGsapAwareEditing({
     bumpGsapCache,
   });
 
+  const commitAnimatedProperties = useCallback(
+    async (selection: DomEditSelection, properties: Record<string, number | string>) => {
+      try {
+        await commitAnimatedPropertiesRaw(selection, properties);
+      } catch (error) {
+        trackGsapInteractionFailure(error, selection, "property", "Edit animated property");
+        throw error;
+      }
+    },
+    [commitAnimatedPropertiesRaw, trackGsapInteractionFailure],
+  );
+
+  const commitAnimatedProperty = useCallback(
+    async (selection: DomEditSelection, property: string, value: number | string) => {
+      try {
+        await commitAnimatedPropertyRaw(selection, property, value);
+      } catch (error) {
+        trackGsapInteractionFailure(error, selection, "property", "Edit animated property");
+        throw error;
+      }
+    },
+    [commitAnimatedPropertyRaw, trackGsapInteractionFailure],
+  );
+
   // ── Arc path wrappers ──
 
   const handleSetArcPath = useCallback(

package/src/hooks/useGsapInteractionFailureTelemetry.test.tsx

@@ -0,0 +1,42 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { mountReactHarness } from "./domSelectionTestHarness";
+import { GsapEditBlockedError } from "./gsapEditOutcome";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const trackStudioSaveFailure = vi.hoisted(() => vi.fn());
+vi.mock("../utils/studioSaveDiagnostics", () => ({ trackStudioSaveFailure }));
+
+import { useGsapInteractionFailureTelemetry } from "./useGsapInteractionFailureTelemetry";
+
+describe("useGsapInteractionFailureTelemetry", () => {
+  it("surfaces the blocked reason instead of a generic save failure", () => {
+    const showToast = vi.fn();
+    const selection = {
+      id: "clip",
+      selector: "#clip",
+      element: document.createElement("div"),
+    } as unknown as DomEditSelection;
+    let report!: ReturnType<typeof useGsapInteractionFailureTelemetry>;
+    function Harness() {
+      report = useGsapInteractionFailureTelemetry("index.html", showToast);
+      return null;
+    }
+    const root = mountReactHarness(<Harness />);
+
+    act(() => report(new GsapEditBlockedError("unroll-required"), selection, "drag", "Move"));
+
+    expect(showToast).toHaveBeenCalledWith(
+      "This motion comes from a helper or loop. Choose Unroll to edit it explicitly.",
+      "error",
+    );
+    expect(trackStudioSaveFailure).toHaveBeenCalledWith(
+      expect.objectContaining({ source: "gsap_commit", mutationType: "drag", targetId: "clip" }),
+    );
+    act(() => root.unmount());
+  });
+});

package/src/hooks/useGsapInteractionFailureTelemetry.ts

@@ -1,6 +1,7 @@
 import { useCallback } from "react";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import { trackStudioSaveFailure } from "../utils/studioSaveDiagnostics";
+import { isGsapEditBlockedError } from "./gsapEditOutcome";
 
 export function useGsapInteractionFailureTelemetry(
   activeCompPath: string | null,
@@ -18,7 +19,10 @@ export function useGsapInteractionFailureTelemetry(
         targetSelector: selection.selector,
         targetSourceFile: selection.sourceFile,
       });
-      showToast("Failed to save animated edit.", "error");
+      showToast(
+        isGsapEditBlockedError(error) ? error.message : "Failed to save animated edit.",
+        "error",
+      );
     },
     [activeCompPath, showToast],
   );

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]);
+}