@hyperframes/studio 0.6.109 → 0.6.111

package/src/hooks/useTimelineEditing.ts

@@ -1,11 +1,7 @@
 // Pre-existing-complex timeline hook (DOM patch + GSAP position shift/scale +
-// playback-start resolution); this PR adds guarded shadow-timing dispatches in
-// the move/resize .then() chains, which nudges several callbacks over the CC
-// threshold. The added branches are telemetry-only.
+// playback-start resolution).
 // fallow-ignore-file complexity
 import { useCallback, useRef } from "react";
-import type { Composition } from "@hyperframes/sdk";
-import { runShadowDelete, runShadowTiming } from "../utils/sdkShadow";
 import type { TimelineElement } from "../player";
 import { usePlayerStore } from "../player";
 import { useRazorSplit } from "./useRazorSplit";
@@ -37,6 +33,8 @@ import {
   scaleGsapPositions,
 } from "./timelineEditingHelpers";
 import type { PersistTimelineEditInput } from "./timelineEditingHelpers";
+import { sdkTimingPersist } from "../utils/sdkCutover";
+import type { Composition } from "@hyperframes/sdk";
 
 // ── Types ──
 
@@ -60,8 +58,10 @@ interface UseTimelineEditingOptions {
   pendingTimelineEditPathRef: React.MutableRefObject<Set<string>>;
   uploadProjectFiles: (files: Iterable<File>, dir?: string) => Promise<string[]>;
   isRecordingRef?: React.RefObject<boolean>;
-  /** Stage 7 Step 3b: SDK session for shadow timing dispatch (server stays authoritative). */
+  /** Stage 7 §3.2: SDK session for routing timing ops through setTiming. */
   sdkSession?: Composition | null;
+  /** Resync the SDK session after a server-authoritative timeline write. */
+  forceReloadSdkSession?: () => void;
 }
 
 // ── Hook ──
@@ -80,6 +80,7 @@ export function useTimelineEditing({
   uploadProjectFiles,
   isRecordingRef,
   sdkSession,
+  forceReloadSdkSession,
 }: UseTimelineEditingOptions) {
   const projectIdRef = useRef(projectId);
   projectIdRef.current = projectId;
@@ -92,6 +93,7 @@ export function useTimelineEditing({
       element: TimelineElement,
       label: string,
       buildPatches: PersistTimelineEditInput["buildPatches"],
+      coalesceKey?: string,
     ): Promise<void> => {
       if (isRecordingRef?.current) {
         showToast("Cannot edit timeline while recording", "error");
@@ -99,19 +101,25 @@ export function useTimelineEditing({
       }
       const pid = projectIdRef.current;
       if (!pid) return Promise.resolve();
-      const queued = editQueueRef.current.then(() =>
-        persistTimelineEdit({
-          projectId: pid,
-          element,
-          activeCompPath,
-          label,
-          buildPatches,
-          writeProjectFile,
-          recordEdit,
-          domEditSaveTimestampRef,
-          pendingTimelineEditPathRef,
-        }),
-      );
+      const queued = editQueueRef.current
+        .then(() =>
+          persistTimelineEdit({
+            projectId: pid,
+            element,
+            activeCompPath,
+            label,
+            buildPatches,
+            writeProjectFile,
+            recordEdit,
+            domEditSaveTimestampRef,
+            pendingTimelineEditPathRef,
+            coalesceKey,
+          }),
+        )
+        .then(() => {
+          // Server wrote the file; resync the stale in-memory SDK doc.
+          forceReloadSdkSession?.();
+        });
       editQueueRef.current = queued.catch((error) => {
         console.error(`[Timeline] Failed to persist: ${label}`, error);
       });
@@ -125,18 +133,20 @@ export function useTimelineEditing({
       pendingTimelineEditPathRef,
       showToast,
       isRecordingRef,
+      forceReloadSdkSession,
     ],
   );
 
+  // fallow-ignore-next-line complexity
   const handleTimelineElementMove = useCallback(
+    // fallow-ignore-next-line complexity
     (element: TimelineElement, updates: Pick<TimelineElement, "start" | "track">) => {
       patchIframeDomTiming(previewIframeRef.current, element, [
         ["data-start", formatTimelineAttributeNumber(updates.start)],
         ["data-track-index", String(updates.track)],
       ]);
-      const delta = updates.start - element.start;
-      const filePath = element.sourceFile || activeCompPath || "index.html";
-      return enqueueEdit(element, "Move timeline clip", (original, target) => {
+      const targetPath = element.sourceFile || activeCompPath || "index.html";
+      const buildMovePatches: PersistTimelineEditInput["buildPatches"] = (original, target) => {
         let patched = applyPatchByTarget(original, target, {
           type: "attribute",
           property: "start",
@@ -147,24 +157,63 @@ export function useTimelineEditing({
           property: "track-index",
           value: String(updates.track),
         });
-      }).then(() => {
-        if (sdkSession)
-          runShadowTiming(sdkSession, element.hfId, {
-            start: updates.start,
-            trackIndex: updates.track,
-          });
-        const pid = projectIdRef.current;
-        if (delta !== 0 && element.domId && pid) {
-          return shiftGsapPositions(pid, filePath, element.domId, delta)
-            .then(() => reloadPreview())
-            .catch((err) => console.error("[Timeline] Failed to shift GSAP positions", err));
-        }
-      });
+      };
+      // Server-path fallback (no SDK session): persist the attr patch, then
+      // shift GSAP tween positions on the server and reload the preview — the
+      // SDK path folds both into setTiming, but the fallback must do them
+      // explicitly or the clip moves while its GSAP tweens stay put + the
+      // preview never refreshes. coalesceKey mirrors the SDK branch so undo
+      // granularity is identical on either path.
+      const coalesceKey = `timeline-move:${element.hfId ?? element.id}`;
+      const moveFallback = () =>
+        enqueueEdit(element, "Move timeline clip", buildMovePatches, coalesceKey).then(() => {
+          const pid = projectIdRef.current;
+          const delta = updates.start - element.start;
+          if (delta !== 0 && element.domId && pid) {
+            return shiftGsapPositions(pid, targetPath, element.domId, delta)
+              .then(() => reloadPreview())
+              .catch((err) => console.error("[Timeline] Failed to shift GSAP positions", err));
+          }
+          return reloadPreview();
+        });
+      if (sdkSession && element.hfId) {
+        return sdkTimingPersist(
+          element.hfId,
+          targetPath,
+          { start: updates.start, trackIndex: updates.track },
+          sdkSession,
+          {
+            editHistory: { recordEdit },
+            writeProjectFile,
+            reloadPreview,
+            domEditSaveTimestampRef,
+            compositionPath: activeCompPath,
+            // Capture on-disk bytes as the undo `before` so undoing a timing move
+            // restores the file verbatim, not a normalized full-DOM re-emit.
+            readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
+          },
+          { label: "Move timeline clip", coalesceKey },
+        ).then((handled) => {
+          if (!handled) return moveFallback();
+        });
+      }
+      return moveFallback();
     },
-    [previewIframeRef, enqueueEdit, activeCompPath, reloadPreview, sdkSession],
+    [
+      previewIframeRef,
+      enqueueEdit,
+      activeCompPath,
+      sdkSession,
+      recordEdit,
+      writeProjectFile,
+      reloadPreview,
+      domEditSaveTimestampRef,
+    ],
   );
 
+  // fallow-ignore-next-line complexity
   const handleTimelineElementResize = useCallback(
+    // fallow-ignore-next-line complexity
     (
       element: TimelineElement,
       updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
@@ -173,6 +222,9 @@ export function useTimelineEditing({
         ["data-start", formatTimelineAttributeNumber(updates.start)],
         ["data-duration", formatTimelineAttributeNumber(updates.duration)],
       ];
+      // Patch the live playback-start/media-start attr too, or a resize that
+      // trims the playback start leaves the preview showing the old in-point
+      // until the next reload (the persisted patch handles it via pbs below).
       if (updates.playbackStart != null) {
         const liveAttr =
           element.playbackStartAttr === "playback-start"
@@ -181,10 +233,8 @@ export function useTimelineEditing({
         liveAttrs.push([liveAttr, formatTimelineAttributeNumber(updates.playbackStart)]);
       }
       patchIframeDomTiming(previewIframeRef.current, element, liveAttrs);
-      const filePath = element.sourceFile || activeCompPath || "index.html";
-      const timingChanged =
-        updates.start !== element.start || updates.duration !== element.duration;
-      return enqueueEdit(element, "Resize timeline clip", (original, target) => {
+      const targetPath = element.sourceFile || activeCompPath || "index.html";
+      const buildResizePatches: PersistTimelineEditInput["buildPatches"] = (original, target) => {
         const pbs = resolveResizePlaybackStart(original, target, element, updates);
         let patched = applyPatchByTarget(original, target, {
           type: "attribute",
@@ -204,34 +254,77 @@ export function useTimelineEditing({
           });
         }
         return patched;
-      }).then(() => {
-        if (sdkSession)
-          runShadowTiming(sdkSession, element.hfId, {
-            start: updates.start,
-            duration: updates.duration,
-          });
-        const pid = projectIdRef.current;
-        if (timingChanged && element.domId && pid) {
-          return scaleGsapPositions(
-            pid,
-            filePath,
-            element.domId,
-            element.start,
-            element.duration,
-            updates.start,
-            updates.duration,
-          )
-            .then(() => reloadPreview())
-            .catch((err) => console.error("[Timeline] Failed to scale GSAP positions", err));
-        }
-        return reloadPreview();
-      });
+      };
+      // SDK path: skip when a playback-start adjustment is needed (setTiming has no pbs field).
+      // The second clause fires because trimming the start of a clip that has a
+      // playback-start attribute implicitly shifts that in-point — which the SDK
+      // setTiming op can't express — so those resizes must take the server path.
+      const hasPbsAdjustment =
+        updates.playbackStart != null ||
+        (updates.start !== element.start && element.playbackStart != null);
+      // Server-path fallback: after persisting the attr patch, scale GSAP tween
+      // positions/durations on the server and reload the preview. The SDK path
+      // folds both into setTiming; the fallback must do them explicitly or the
+      // clip resizes while its GSAP tweens keep their old timing + the preview
+      // never refreshes. coalesceKey mirrors the SDK branch for undo parity.
+      const coalesceKey = `timeline-resize:${element.hfId ?? element.id}`;
+      const timingChanged =
+        updates.start !== element.start || updates.duration !== element.duration;
+      const resizeFallback = () =>
+        enqueueEdit(element, "Resize timeline clip", buildResizePatches, coalesceKey).then(() => {
+          const pid = projectIdRef.current;
+          if (timingChanged && element.domId && pid) {
+            return scaleGsapPositions(
+              pid,
+              targetPath,
+              element.domId,
+              element.start,
+              element.duration,
+              updates.start,
+              updates.duration,
+            )
+              .then(() => reloadPreview())
+              .catch((err) => console.error("[Timeline] Failed to scale GSAP positions", err));
+          }
+          return reloadPreview();
+        });
+      if (sdkSession && element.hfId && !hasPbsAdjustment) {
+        return sdkTimingPersist(
+          element.hfId,
+          targetPath,
+          { start: updates.start, duration: updates.duration },
+          sdkSession,
+          {
+            editHistory: { recordEdit },
+            writeProjectFile,
+            reloadPreview,
+            domEditSaveTimestampRef,
+            compositionPath: activeCompPath,
+            // Capture on-disk bytes as the undo `before` so undoing a timing
+            // resize restores the file verbatim, not a normalized full-DOM re-emit.
+            readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
+          },
+          { label: "Resize timeline clip", coalesceKey },
+        ).then((handled) => {
+          if (!handled) return resizeFallback();
+        });
+      }
+      return resizeFallback();
     },
-    [previewIframeRef, enqueueEdit, activeCompPath, reloadPreview, sdkSession],
+    [
+      previewIframeRef,
+      enqueueEdit,
+      activeCompPath,
+      sdkSession,
+      recordEdit,
+      writeProjectFile,
+      reloadPreview,
+      domEditSaveTimestampRef,
+    ],
   );
 
+  // fallow-ignore-next-line complexity
   const handleTimelineElementDelete = useCallback(
-    // Pre-existing handler complexity, unchanged by this PR.
     // fallow-ignore-next-line complexity
     async (element: TimelineElement) => {
       if (isRecordingRef?.current) {
@@ -287,8 +380,8 @@ export function useTimelineEditing({
             timelineElements.filter((te) => (te.key ?? te.id) !== (element.key ?? element.id)),
           );
         usePlayerStore.getState().setSelectedElementId(null);
+        forceReloadSdkSession?.();
         reloadPreview();
-        if (sdkSession) runShadowDelete(sdkSession, element.hfId);
         showToast(`Deleted ${label}. Use Undo to restore it.`, "info");
       } catch (error) {
         const message = error instanceof Error ? error.message : "Failed to delete timeline clip";
@@ -304,12 +397,12 @@ export function useTimelineEditing({
       domEditSaveTimestampRef,
       reloadPreview,
       isRecordingRef,
-      sdkSession,
+      forceReloadSdkSession,
     ],
   );
 
+  // fallow-ignore-next-line complexity
   const handleTimelineAssetDrop = useCallback(
-    // Pre-existing handler complexity, unchanged by this PR.
     // fallow-ignore-next-line complexity
     async (
       assetPath: string,
@@ -373,6 +466,7 @@ export function useTimelineEditing({
           recordEdit,
         });
 
+        forceReloadSdkSession?.();
         reloadPreview();
       } catch (error) {
         const message =
@@ -389,11 +483,12 @@ export function useTimelineEditing({
       domEditSaveTimestampRef,
       reloadPreview,
       isRecordingRef,
+      forceReloadSdkSession,
     ],
   );
 
+  // fallow-ignore-next-line complexity
   const handleTimelineFileDrop = useCallback(
-    // Pre-existing handler complexity, unchanged by this PR.
     // fallow-ignore-next-line complexity
     async (files: File[], placement?: Pick<TimelineElement, "start" | "track">) => {
       if (isRecordingRef?.current) {

package/src/utils/gsapSoftReload.ts

@@ -31,6 +31,19 @@ function findGsapScriptElements(doc: Document): HTMLScriptElement[] {
   return results;
 }
 
+/**
+ * Extract the GSAP timeline script text from a serialized HTML document, for
+ * feeding into applySoftReload. Returns null when zero or multiple GSAP scripts
+ * are present (ambiguous — caller should fall back to a full reload), matching
+ * applySoftReload's own single-script requirement.
+ */
+export function extractGsapScriptText(html: string): string | null {
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  const scripts = findGsapScriptElements(doc);
+  if (scripts.length !== 1) return null;
+  return scripts[0].textContent || null;
+}
+
 /** Check that the new script repopulated __timelines with at least one entry. */
 function verifyTimelinesPopulated(win: IframeWindow): boolean {
   const tlKeys = win.__timelines
@@ -73,6 +86,7 @@ export function applySoftReload(iframe: HTMLIFrameElement | null, scriptText: st
   // full iframe reload that destroys the very WebGL context we're preserving.
   let deferredToAsync = false;
 
+  // fallow-ignore-next-line complexity
   const doReload = () => {
     const timelines = win.__timelines;
     const allTargets: Element[] = [];

package/src/utils/sdkCutover.gate.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it, vi } from "vitest";
+
+// Dark-launch contract: with STUDIO_SDK_CUTOVER_ENABLED=false, EVERY cutover
+// persist chokepoint must return false so the caller takes the legacy server
+// path — even when a valid SDK session exists (one always does, for
+// shadow/selection). This is the contract the prod flag-flip rests on; a future
+// refactor of the gate guards that silently re-enables cutover on flag-off
+// turns these red. (sdkCutover.test.ts mocks the flag TRUE; this is its sibling.)
+vi.mock("../components/editor/manualEditingAvailability", () => ({
+  STUDIO_SDK_CUTOVER_ENABLED: false,
+  STUDIO_SDK_RESOLVER_SHADOW_ENABLED: false,
+}));
+vi.mock("./studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
+import { sdkTimingPersist, sdkGsapTweenPersist, sdkDeletePersist } from "./sdkCutover";
+
+const makeSession = () =>
+  ({
+    getElement: () => ({ inlineStyles: {} }),
+    serialize: () => "<html></html>",
+    batch: (fn: () => void) => fn(),
+    setTiming: vi.fn(),
+    dispatch: vi.fn(),
+  }) as never;
+
+const makeDeps = () =>
+  ({
+    editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
+    writeProjectFile: vi.fn().mockResolvedValue(undefined),
+    reloadPreview: vi.fn(),
+    domEditSaveTimestampRef: { current: 0 },
+  }) as never;
+
+describe("dark-launch gate — STUDIO_SDK_CUTOVER_ENABLED=false ⇒ persist returns false", () => {
+  it("sdkTimingPersist falls back without writing", async () => {
+    const deps = makeDeps();
+    expect(await sdkTimingPersist("hf-a", "/c.html", { start: 1 }, makeSession(), deps)).toBe(
+      false,
+    );
+    expect(
+      (deps as unknown as { writeProjectFile: ReturnType<typeof vi.fn> }).writeProjectFile,
+    ).not.toHaveBeenCalled();
+  });
+
+  it("sdkGsapTweenPersist (shared GSAP-op chokepoint) falls back", async () => {
+    expect(
+      await sdkGsapTweenPersist(
+        "/c.html",
+        { kind: "remove", animationId: "a" },
+        makeSession(),
+        makeDeps(),
+      ),
+    ).toBe(false);
+  });
+
+  it("sdkDeletePersist falls back", async () => {
+    expect(
+      await sdkDeletePersist("hf-a", "<html></html>", "/c.html", makeSession(), makeDeps()),
+    ).toBe(false);
+  });
+});