@hyperframes/studio 0.8.127 → 0.8.129

package/src/hooks/useTimelineClipTimingEditing.ts

@@ -0,0 +1,343 @@
+import { useCallback, type MutableRefObject } from "react";
+import type { TimelineElement } from "../player";
+import { toAuthoredStart, toCompositionTime } from "../player/store/timelineElement";
+import {
+  applyTimelineStackingReorder,
+  patchIframeDomTiming,
+  persistTimelineEdit,
+  formatTimelineAttributeNumber,
+  formatTimelineMediaOffset,
+  extendRootDurationIfNeeded,
+  buildTimelineMoveTimingPatch,
+  buildTimelineResizeTimingPatch,
+  type PersistTimelineEditInput,
+} from "./timelineEditingHelpers";
+import { playbackStartAttributeForElement } from "../player/lib/timelineElementHelpers";
+import {
+  captureDurationRollback,
+  finishClipTimingFallback,
+  sdkTimingGsapSync,
+  readFileContent,
+  syncPreviewContentDuration,
+  timingGestureStep,
+} from "./timelineTimingSync";
+import { serializeZLaneGesture } from "../components/nle/zLaneGesture";
+import { cutoverCommittedOrThrow, sdkTimingPersist } from "../utils/sdkCutover";
+import type { TimelineMoveUpdates, UseTimelineEditingOptions } from "./useTimelineEditingTypes";
+import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
+
+type UseTimelineClipTimingEditingOptions = Pick<
+  UseTimelineEditingOptions,
+  | "activeCompPath"
+  | "timelineElements"
+  | "showToast"
+  | "writeProjectFile"
+  | "recordEdit"
+  | "reloadPreview"
+  | "previewIframeRef"
+  | "pendingTimelineEditPathRef"
+  | "isRecordingRef"
+  | "sdkSession"
+  | "publishSdkSession"
+  | "forceReloadSdkSession"
+  | "invalidateGsapCache"
+  | "handleDomZIndexReorderCommitRef"
+> & {
+  editQueueRef: MutableRefObject<Promise<unknown>>;
+  projectIdRef: MutableRefObject<string | null>;
+};
+
+/** One clip's move and resize: the timing write, then its tween rewrite, as one undo step. */
+export function useTimelineClipTimingEditing({
+  activeCompPath,
+  timelineElements,
+  showToast,
+  writeProjectFile,
+  recordEdit,
+  reloadPreview,
+  previewIframeRef,
+  pendingTimelineEditPathRef,
+  isRecordingRef,
+  sdkSession,
+  publishSdkSession,
+  forceReloadSdkSession,
+  invalidateGsapCache,
+  handleDomZIndexReorderCommitRef,
+  editQueueRef,
+  projectIdRef,
+}: UseTimelineClipTimingEditingOptions) {
+  const enqueueEdit = useCallback(
+    (
+      element: TimelineElement,
+      label: string,
+      buildPatches: PersistTimelineEditInput["buildPatches"],
+      step: ReturnType<typeof timingGestureStep>,
+    ): Promise<void> => {
+      if (isRecordingRef?.current) {
+        showToast("Cannot edit timeline while recording", "error");
+        return Promise.resolve();
+      }
+      const pid = projectIdRef.current;
+      if (!pid) return Promise.resolve();
+      const queued = editQueueRef.current
+        .then(() =>
+          persistTimelineEdit({
+            projectId: pid,
+            element,
+            activeCompPath,
+            label,
+            buildPatches,
+            writeProjectFile,
+            recordEdit,
+            pendingTimelineEditPathRef,
+            ...step,
+          }),
+        )
+        .then(() => {
+          forceReloadSdkSession?.();
+        });
+      editQueueRef.current = queued.catch((error) => {
+        console.error(`[Timeline] Failed to persist: ${label}`, error);
+      });
+      return queued;
+    },
+    [
+      activeCompPath,
+      recordEdit,
+      writeProjectFile,
+      pendingTimelineEditPathRef,
+      showToast,
+      isRecordingRef,
+      forceReloadSdkSession,
+      editQueueRef,
+      projectIdRef,
+    ],
+  );
+  const handleTimelineElementMove = useCallback(
+    // fallow-ignore-next-line complexity
+    (element: TimelineElement, updates: TimelineMoveUpdates) => {
+      // fallow-ignore-next-line complexity
+      const commitMove = () => {
+        const targetPath = element.sourceFile || activeCompPath || "index.html";
+        const startChanged = updates.start !== element.start;
+        // A vertical-only lane move (start unchanged, authored track already in updates.track) must
+        // persist like any other move, or the lane snaps back on reload.
+        const trackChanged = updates.track !== element.track;
+        const authoredStart = toAuthoredStart(element, updates.start);
+        if (startChanged || trackChanged) {
+          const liveAttrs: Array<[string, string]> = [];
+          if (startChanged)
+            liveAttrs.push(["data-start", formatTimelineAttributeNumber(authoredStart)]);
+          if (trackChanged) {
+            liveAttrs.push(["data-track-index", formatTimelineAttributeNumber(updates.track)]);
+          }
+          patchIframeDomTiming(previewIframeRef.current, element, liveAttrs, activeCompPath);
+        }
+
+        const reorderDone = applyTimelineStackingReorder({
+          element,
+          stackingReorder: updates.stackingReorder,
+          timelineElements,
+          iframe: previewIframeRef.current,
+          activeCompPath,
+          commit: handleDomZIndexReorderCommitRef?.current,
+        });
+
+        if (!startChanged && !trackChanged) return reorderDone;
+
+        // Snapshot the duration BEFORE the optimistic updates below so a failed
+        // persist can roll the readout + live root back (see captureDurationRollback).
+        const rollbackDuration = captureDurationRollback(previewIframeRef.current);
+        // Read before the readout sync below: the SDK path (setTiming) can't grow the root duration.
+        const needsExtension = extendRootDurationIfNeeded(updates.start + element.duration);
+        // Optimistic duration readout from the just-patched live DOM (grows and shrinks).
+        syncPreviewContentDuration(previewIframeRef.current);
+
+        const buildMovePatches: PersistTimelineEditInput["buildPatches"] = (original, target) => {
+          // Persist lane changes too — data-start-only writes let reload snap the lane back.
+          const track = trackChanged ? updates.track : undefined;
+          return buildTimelineMoveTimingPatch(
+            original,
+            target,
+            authoredStart,
+            element.duration,
+            track,
+          );
+        };
+        const step = timingGestureStep("timeline-move");
+        const finishMoveGsapSync = (sdkGsap?: ReturnType<typeof sdkTimingGsapSync>) =>
+          // One GSAP sync per edit: the SDK commit's own (sdkGsap), else the server rewrite here.
+          finishClipTimingFallback({
+            iframe: previewIframeRef.current,
+            reloadPreview,
+            projectId: projectIdRef.current,
+            targetPath,
+            domId: element.domId,
+            label: "Move timeline clip",
+            coalesceKey: step.coalesceKey,
+            recordEdit,
+            writeProjectFile,
+            edit: { kind: "shift", delta: updates.start - element.start },
+            sdkGsap,
+          }).finally(() => invalidateGsapCache?.());
+        const moveFallback = () =>
+          enqueueEdit(element, "Move timeline clip", buildMovePatches, step).then(() =>
+            finishMoveGsapSync(),
+          );
+        return reorderDone
+          .then(() => {
+            // SDK setTiming writes start only; a lane change needs the fallback's track patch.
+            if (sdkSession && element.hfId && !element.link && !needsExtension && !trackChanged) {
+              return sdkTimingPersist(
+                element.hfId,
+                targetPath,
+                { start: authoredStart },
+                sdkSession,
+                {
+                  editHistory: { recordEdit },
+                  writeProjectFile,
+                  reloadPreview,
+                  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),
+                  publishSession: publishSdkSession,
+                },
+                { label: "Move timeline clip", ...step, skipRefresh: true },
+              ).then((result) => {
+                if (!cutoverCommittedOrThrow(result)) return moveFallback();
+                return finishMoveGsapSync(sdkTimingGsapSync(result));
+              });
+            }
+            return moveFallback();
+          })
+          .catch((error) => {
+            // Failed persist: revert the optimistic duration readout + live root.
+            rollbackDuration();
+            showToast(getStudioSaveErrorMessage(error), "error");
+            throw error;
+          });
+      };
+      return updates.stackingReorder ? serializeZLaneGesture(commitMove) : commitMove();
+    },
+    [
+      previewIframeRef,
+      enqueueEdit,
+      activeCompPath,
+      sdkSession,
+      publishSdkSession,
+      recordEdit,
+      writeProjectFile,
+      reloadPreview,
+      timelineElements,
+      handleDomZIndexReorderCommitRef,
+      showToast,
+      invalidateGsapCache,
+      projectIdRef,
+    ],
+  );
+
+  const handleTimelineElementResize = useCallback(
+    // fallow-ignore-next-line complexity
+    (
+      element: TimelineElement,
+      updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
+    ) => {
+      const authoredStart = toAuthoredStart(element, updates.start);
+      const liveAttrs: Array<[string, string]> = [
+        ["data-start", formatTimelineAttributeNumber(authoredStart)],
+        ["data-duration", formatTimelineAttributeNumber(updates.duration)],
+      ];
+      if (updates.playbackStart != null) {
+        const liveAttr = playbackStartAttributeForElement(element);
+        liveAttrs.push([liveAttr, formatTimelineMediaOffset(updates.playbackStart)]);
+      }
+      patchIframeDomTiming(previewIframeRef.current, element, liveAttrs, activeCompPath);
+      // Snapshot the duration BEFORE the optimistic updates below so a failed
+      // persist can roll the readout + live root back (see captureDurationRollback).
+      const rollbackDuration = captureDurationRollback(previewIframeRef.current);
+      // Read before the readout sync below: the SDK path (setTiming) can't grow the root duration.
+      const needsExtension = extendRootDurationIfNeeded(updates.start + updates.duration);
+      // Optimistic duration readout from the just-patched live DOM (grows and shrinks).
+      syncPreviewContentDuration(previewIframeRef.current);
+      const targetPath = element.sourceFile || activeCompPath || "index.html";
+      const buildResizePatches: PersistTimelineEditInput["buildPatches"] = (original, target) => {
+        return buildTimelineResizeTimingPatch(original, target, element, updates);
+      };
+      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, then soft-reload with the rewritten
+      // script (timing-only resize) — same no-flash path as move; full reload is
+      // the fallback.
+      const step = timingGestureStep("timeline-resize");
+      const finishResizeGsapSync = (sdkGsap?: ReturnType<typeof sdkTimingGsapSync>) =>
+        finishClipTimingFallback({
+          iframe: previewIframeRef.current,
+          reloadPreview,
+          projectId: projectIdRef.current,
+          targetPath,
+          domId: element.domId,
+          label: "Resize timeline clip",
+          coalesceKey: step.coalesceKey,
+          recordEdit,
+          writeProjectFile,
+          edit: {
+            kind: "scale",
+            from: { start: toCompositionTime(element, element.start), duration: element.duration },
+            to: { start: toCompositionTime(element, updates.start), duration: updates.duration },
+          },
+          sdkGsap,
+        }).finally(() => invalidateGsapCache?.());
+      const resizeFallback = () =>
+        enqueueEdit(element, "Resize timeline clip", buildResizePatches, step).then(() =>
+          finishResizeGsapSync(),
+        );
+      const persistDone =
+        sdkSession && element.hfId && !element.link && !hasPbsAdjustment && !needsExtension
+          ? sdkTimingPersist(
+              element.hfId,
+              targetPath,
+              { start: authoredStart, duration: updates.duration },
+              sdkSession,
+              {
+                editHistory: { recordEdit },
+                writeProjectFile,
+                reloadPreview,
+                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),
+                publishSession: publishSdkSession,
+              },
+              { label: "Resize timeline clip", ...step, skipRefresh: true },
+            ).then((result) => {
+              if (!cutoverCommittedOrThrow(result)) return resizeFallback();
+              return finishResizeGsapSync(sdkTimingGsapSync(result));
+            })
+          : resizeFallback();
+      return persistDone.catch((error) => {
+        // Failed persist: revert the optimistic duration readout + live root.
+        rollbackDuration();
+        showToast(getStudioSaveErrorMessage(error), "error");
+        throw error;
+      });
+    },
+    [
+      previewIframeRef,
+      enqueueEdit,
+      activeCompPath,
+      sdkSession,
+      publishSdkSession,
+      recordEdit,
+      writeProjectFile,
+      reloadPreview,
+      showToast,
+      invalidateGsapCache,
+      projectIdRef,
+    ],
+  );
+
+  return { handleTimelineElementMove, handleTimelineElementResize };
+}

package/src/hooks/useTimelineDeleteOps.test.tsx

@@ -62,6 +62,7 @@ describe("useTimelineDeleteOps: ripple undo label", () => {
   function mountDeleteHarness(overrides: {
     handleTimelineGroupMove: DeleteOpsOptions["handleTimelineGroupMove"];
     showToast?: DeleteOpsOptions["showToast"];
+    recordEdit?: DeleteOpsOptions["recordEdit"];
   }) {
     const elements = [el("hf-a", 0, 2), el("hf-b", 2, 2), el("hf-c", 4, 2)];
     let hook: ReturnType<typeof useTimelineDeleteOps> | null = null;
@@ -72,7 +73,7 @@ describe("useTimelineDeleteOps: ripple undo label", () => {
         timelineElements: elements,
         showToast: overrides.showToast ?? vi.fn(),
         writeProjectFile: vi.fn().mockResolvedValue(undefined),
-        recordEdit: vi.fn().mockResolvedValue(undefined),
+        recordEdit: overrides.recordEdit ?? vi.fn().mockResolvedValue(undefined),
         reloadPreview: vi.fn(),
         previewIframeRef: { current: null },
         handleTimelineGroupMove: overrides.handleTimelineGroupMove,
@@ -120,6 +121,24 @@ describe("useTimelineDeleteOps: ripple undo label", () => {
     );
   });
 
+  it("holds the delete's undo step open under the key its ripple joins, however late the ripple lands", async () => {
+    stubRemoveElementsFetch(html, html.replace(/<div data-hf-id="hf-b"[^\n]*\n/, ""));
+    const handleTimelineGroupMove = vi.fn().mockResolvedValue(undefined);
+    const recordEdit = vi.fn().mockResolvedValue(undefined);
+    const { b, getHook } = mountDeleteHarness({ handleTimelineGroupMove, recordEdit });
+
+    await act(async () => {
+      await getHook().handleTimelineElementDelete(b);
+    });
+
+    const [[deleted]] = recordEdit.mock.calls;
+    expect(deleted).toMatchObject({ coalesceMs: Infinity });
+    expect(handleTimelineGroupMove).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ coalesceKey: deleted.coalesceKey }),
+    );
+  });
+
   it("removes a multi-clip selection with one request, however many clips it holds", async () => {
     const handleTimelineGroupMove = vi.fn().mockResolvedValue(undefined);
     const { elements, getHook } = mountDeleteHarness({ handleTimelineGroupMove });

package/src/hooks/useTimelineDeleteOps.ts

@@ -9,7 +9,7 @@ import { saveServerRewriteWithHistory, type RecordEditInput } from "../utils/stu
 import { studioWriteHeaders } from "../utils/studioFileVersion";
 import { getTimelineElementLabel } from "../utils/studioHelpers";
 import { buildPatchTarget, removeIframeTimelineElements } from "./timelineEditingHelpers";
-import { captureDurationRollback } from "./timelineTimingSync";
+import { captureDurationRollback, timingGestureStep } from "./timelineTimingSync";
 import { setLinkInSource } from "../components/editor/mediaLinkEdits";
 import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";
 import { furthestClipEndFromSource } from "../player/lib/timelineElementHelpers";
@@ -57,11 +57,6 @@ interface UseTimelineDeleteOpsOptions {
   ) => Promise<void>;
 }
 
-// Per-gesture-unique coalesce key — a monotonic counter, not Date.now() /
-// Math.random() (determinism rules), mirroring gapCloseGestureSeq in
-// timelineGapCommit.ts.
-let deleteGestureSeq = 0;
-
 function unlinkInSource(source: string, survivors: readonly TimelineElement[]): string {
   const targets = survivors.map(buildPatchTarget).filter((target) => target !== null);
   return targets.length > 0 ? setLinkInSource(source, targets, null) : source;
@@ -107,10 +102,8 @@ export function useTimelineDeleteOps({
         (candidate) => (candidate.sourceFile || activeCompPath || "index.html") === targetPath,
       );
       try {
-        // Shared with the ripple move below so a folded ripple is one undo
-        // step with the delete, not two (editHistory.ts coalesces by key +
-        // window across separate recordEdit calls, not by label).
-        const coalesceKey = `main-track-ripple-delete:${deleteGestureSeq++}`;
+        // Shared with the ripple move below so a folded ripple is one undo step with the delete.
+        const step = timingGestureStep("main-track-ripple-delete");
         const deleteHistoryLabel = "Delete timeline clip";
         let rollbackDuration = () => {};
         try {
@@ -118,7 +111,7 @@ export function useTimelineDeleteOps({
             projectId: pid,
             path: targetPath,
             label: deleteHistoryLabel,
-            coalesceKey,
+            ...step,
             writeFile: writeProjectFile,
             recordEdit,
             rewrite: async (originalContent) => {
@@ -189,8 +182,7 @@ export function useTimelineDeleteOps({
         if (rippleChanges) {
           try {
             await handleTimelineGroupMove(rippleChanges, {
-              coalesceKey,
-              coalesceMs: Number.POSITIVE_INFINITY,
+              coalesceKey: step.coalesceKey,
               // Coalescing keeps the LAST entry's label; without this the undo
               // toast reads "Undid Move timeline clips" after a delete, naming
               // the ripple's mechanics instead of what the user actually did.

package/src/hooks/useTimelineEditing.test.tsx

@@ -306,9 +306,10 @@ function stubProjectFetch(files: string | Record<string, string>, gsapBody?: unk
       (url) => jsonResponse({ content: fileContent(pathAfter(url, "/files/")) }),
     ],
     [
-      "/api/projects/p1/gsap-mutations/",
+      "/api/projects/p1/gsap-mutations",
       (url) => {
-        const content = fileContent(pathAfter(url, "/gsap-mutations/")) ?? "";
+        const content =
+          fileContent(pathAfter(url, url.includes("-batch/") ? "-batch/" : "s/")) ?? "";
         return jsonResponse(
           gsapBody ?? { mutated: false, scriptText: null, before: content, after: content },
         );
@@ -1166,6 +1167,41 @@ describe("useTimelineEditing timeline z-index reorder", () => {
     expect(groupWrite.mock.calls[0]![1]).toBe(singleWrite.mock.calls[0]![1]);
     group.unmount();
   });
+
+  it("gives each single-clip move and resize its own undo step, which its GSAP rewrite joins", async () => {
+    const source = '<div id="clip" data-start="0" data-duration="1"></div>';
+    const clip = timelineElement({ id: "clip", track: 0, zIndex: 0, start: 0, duration: 1 });
+    stubProjectFetch(source, {
+      mutated: true,
+      scriptText: null,
+      before: "tweens at 0",
+      after: source,
+    });
+    const recordEdit = vi.fn(async (_edit: { coalesceKey?: string; coalesceMs?: number }) => {});
+    const h = renderTimelineEditingHook({
+      timelineElements: [clip],
+      iframe: createPreviewIframe([{ id: "clip", track: 0 }]),
+      onZIndexCommit: vi.fn().mockResolvedValue(undefined),
+      projectId: "p1",
+      writeProjectFile: vi.fn(async () => {}),
+      recordEdit,
+    });
+
+    await act(async () => {
+      await h.move(clip, { start: 0.5, track: clip.track });
+      await h.move(clip, { start: 1, track: clip.track });
+      await h.resize(clip, { start: 0, duration: 2 });
+    });
+
+    const steps = recordEdit.mock.calls.map(([edit]) => edit);
+    expect(steps.map((edit) => edit.coalesceMs)).toEqual(Array(6).fill(Infinity));
+    const [move, fold, again, foldAgain, resize, resizeFold] = steps.map(
+      (edit) => edit.coalesceKey,
+    );
+    expect([fold, foldAgain, resizeFold]).toEqual([move, again, resize]);
+    expect(new Set([move, again, resize]).size).toBe(3);
+    h.unmount();
+  });
 });
 
 describe("useTimelineEditing duration rollback on failed persist", () => {
@@ -1936,8 +1972,11 @@ function setupNestedHarness() {
   const fetchMock = stubProjectFetch(NESTED_FILES);
   const scaleCalls = () =>
     fetchMock.mock.calls
-      .filter((call) => requestUrl(call[0]).includes("/gsap-mutations/"))
-      .map((call) => JSON.parse(String((call[1] as RequestInit).body)))
+      .filter((call) => requestUrl(call[0]).includes("/gsap-mutations"))
+      .flatMap((call) => {
+        const body = JSON.parse(String((call[1] as RequestInit).body));
+        return body.mutations ?? [body];
+      })
       .filter((body) => body.type === "scale-positions");
   usePlayerStore.getState().setDuration(20);
   const hook = renderTimelineEditingHook({
@@ -2285,6 +2324,19 @@ describe("clip timing edits sync GSAP exactly once", () => {
             applyServerMutation(pathAfter(url, "/gsap-mutations/"), JSON.parse(String(init?.body))),
           );
         }
+        if (url.includes("/gsap-mutations-batch/")) {
+          const path = pathAfter(url, "/gsap-mutations-batch/");
+          const steps = (
+            JSON.parse(String(init?.body)) as { mutations: Record<string, unknown>[] }
+          ).mutations.map((mutation) => applyServerMutation(path, mutation));
+          const last = steps[steps.length - 1]!;
+          return jsonResponse({
+            ...last,
+            before: steps[0]!.before,
+            mutated: steps[0]!.before !== last.after,
+            changed: steps[0]!.before !== last.after,
+          });
+        }
         if (url.includes("/files/"))
           return jsonResponse({ content: files[pathAfter(url, "/files/")] });
         throw new Error(`Unexpected fetch: ${url}`);
@@ -2404,6 +2456,13 @@ describe("clip timing edits sync GSAP exactly once", () => {
         `tl.from("#scene h1", { y: 20, duration: 1 }, 3.5);`,
         `tl.to("#side", { x: 5, duration: 1 }, 3);`,
       ]);
+      if (!withSdk) {
+        const gsapUrls = h.fetchMock.mock.calls
+          .map((call) => requestUrl(call[0]))
+          .filter((url) => url.includes("/gsap-mutations"));
+        // Both clips live in one file, so their rewrites travel as one request.
+        expect(gsapUrls).toEqual([expect.stringContaining("/gsap-mutations-batch/")]);
+      }
       h.hook.unmount();
     });
   }