@hyperframes/studio 0.7.57 → 0.7.58

package/src/hooks/useTimelineEditing.ts

@@ -31,6 +31,7 @@ import {
   useTimelineTrackVisibilityEditing,
 } from "./timelineTrackVisibility";
 import { useTimelineGroupEditing } from "./useTimelineGroupEditing";
+import { serializeZLaneGesture } from "../components/nle/zLaneGesture";
 import { sdkTimingPersist } from "../utils/sdkCutover";
 import type { UseTimelineEditingOptions } from "./useTimelineEditingTypes";
 
@@ -127,105 +128,108 @@ export function useTimelineEditing({
   const handleTimelineElementMove = useCallback(
     // fallow-ignore-next-line complexity
     (element: TimelineElement, updates: TimelineMoveUpdates) => {
-      const targetPath = element.sourceFile || activeCompPath || "index.html";
-      const startChanged = updates.start !== element.start;
-      // A vertical-only lane move arrives with start unchanged but track changed
-      // (on this single-element path the drag commit has already folded the
-      // AUTHORED persist track into updates.track). It must persist like any
-      // other move — early-returning on !startChanged alone silently dropped
-      // the file write, so the lane snapped back on reload.
-      const trackChanged = updates.track !== element.track;
+      const commitMove = () => {
+        const targetPath = element.sourceFile || activeCompPath || "index.html";
+        const startChanged = updates.start !== element.start;
+        // A vertical-only lane move arrives with start unchanged but track changed
+        // (on this single-element path the drag commit has already folded the
+        // AUTHORED persist track into updates.track). It must persist like any
+        // other move — early-returning on !startChanged alone silently dropped
+        // the file write, so the lane snapped back on reload.
+        const trackChanged = updates.track !== element.track;
 
-      if (startChanged || trackChanged) {
-        const liveAttrs: Array<[string, string]> = [];
-        if (startChanged) {
-          liveAttrs.push(["data-start", formatTimelineAttributeNumber(updates.start)]);
-        }
-        if (trackChanged) {
-          liveAttrs.push(["data-track-index", formatTimelineAttributeNumber(updates.track)]);
+        if (startChanged || trackChanged) {
+          const liveAttrs: Array<[string, string]> = [];
+          if (startChanged) {
+            liveAttrs.push(["data-start", formatTimelineAttributeNumber(updates.start)]);
+          }
+          if (trackChanged) {
+            liveAttrs.push(["data-track-index", formatTimelineAttributeNumber(updates.track)]);
+          }
+          patchIframeDomTiming(previewIframeRef.current, element, liveAttrs, activeCompPath);
         }
-        patchIframeDomTiming(previewIframeRef.current, element, liveAttrs);
-      }
 
-      const reorderDone = applyTimelineStackingReorder({
-        element,
-        stackingReorder: updates.stackingReorder,
-        timelineElements,
-        iframe: previewIframeRef.current,
-        activeCompPath,
-        commit: handleDomZIndexReorderCommitRef?.current,
-      });
+        const reorderDone = applyTimelineStackingReorder({
+          element,
+          stackingReorder: updates.stackingReorder,
+          timelineElements,
+          iframe: previewIframeRef.current,
+          activeCompPath,
+          commit: handleDomZIndexReorderCommitRef?.current,
+        });
 
-      if (!startChanged && !trackChanged) return reorderDone;
+        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);
-      // needsExtension gates the SDK path (setTiming can't grow the root duration), so read the store BEFORE the readout sync below optimistically updates it.
-      const needsExtension = extendRootDurationIfNeeded(updates.start + element.duration);
-      // Optimistic duration readout: content-driven (grow AND shrink), from the just-patched live DOM. See syncPreviewContentDuration.
-      syncPreviewContentDuration(previewIframeRef.current);
+        // 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);
+        // needsExtension gates the SDK path (setTiming can't grow the root duration), so read the store BEFORE the readout sync below optimistically updates it.
+        const needsExtension = extendRootDurationIfNeeded(updates.start + element.duration);
+        // Optimistic duration readout: content-driven (grow AND shrink), from the just-patched live DOM. See syncPreviewContentDuration.
+        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,
-          updates.start,
-          element.duration,
-          track,
-        );
-      };
-      const coalesceKey = `timeline-move:${element.hfId ?? element.id}`;
-      const moveFallback = () =>
-        enqueueEdit(element, "Move timeline clip", buildMovePatches, coalesceKey).then(() =>
-          // Soft-reload with the server's rewritten GSAP script — the timing-only move already patched
-          // DOM + store, so swapping the script avoids the all-clips flash; falls back to reloadPreview().
-          finishClipTimingFallback({
-            iframe: previewIframeRef.current,
-            reloadPreview,
-            projectId: projectIdRef.current,
-            targetPath,
-            domId: element.domId,
-            label: "Move timeline clip",
-            coalesceKey,
-            recordEdit,
-            edit: { kind: "shift", delta: updates.start - element.start },
-          }),
-        );
-      return reorderDone
-        .then(() => {
-          // The SDK setTiming path writes start only — a lane change must take
-          // the fallback, whose patch builder writes data-track-index too.
-          if (sdkSession && element.hfId && !needsExtension && !trackChanged) {
-            return sdkTimingPersist(
-              element.hfId,
+        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,
+            updates.start,
+            element.duration,
+            track,
+          );
+        };
+        const coalesceKey = `timeline-move:${element.hfId ?? element.id}`;
+        const moveFallback = () =>
+          enqueueEdit(element, "Move timeline clip", buildMovePatches, coalesceKey).then(() =>
+            // Soft-reload with the server's rewritten GSAP script — the timing-only move already patched
+            // DOM + store, so swapping the script avoids the all-clips flash; falls back to reloadPreview().
+            finishClipTimingFallback({
+              iframe: previewIframeRef.current,
+              reloadPreview,
+              projectId: projectIdRef.current,
               targetPath,
-              { start: updates.start },
-              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();
-        })
-        .catch((error) => {
-          // Failed persist: revert the optimistic duration readout + live root.
-          rollbackDuration();
-          throw error;
-        });
+              domId: element.domId,
+              label: "Move timeline clip",
+              coalesceKey,
+              recordEdit,
+              edit: { kind: "shift", delta: updates.start - element.start },
+            }),
+          );
+        return reorderDone
+          .then(() => {
+            // The SDK setTiming path writes start only — a lane change must take
+            // the fallback, whose patch builder writes data-track-index too.
+            if (sdkSession && element.hfId && !needsExtension && !trackChanged) {
+              return sdkTimingPersist(
+                element.hfId,
+                targetPath,
+                { start: updates.start },
+                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();
+          })
+          .catch((error) => {
+            // Failed persist: revert the optimistic duration readout + live root.
+            rollbackDuration();
+            throw error;
+          });
+      };
+      return updates.stackingReorder ? serializeZLaneGesture(commitMove) : commitMove();
     },
     [
       previewIframeRef,
@@ -261,7 +265,7 @@ export function useTimelineEditing({
             : "data-media-start";
         liveAttrs.push([liveAttr, formatTimelineAttributeNumber(updates.playbackStart)]);
       }
-      patchIframeDomTiming(previewIframeRef.current, element, liveAttrs);
+      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);

package/src/hooks/useTimelineEditingTypes.ts

@@ -23,7 +23,7 @@ export type TimelineZIndexReorderCommit = (
     key?: string;
   }>,
   coalesceKey?: string,
-) => Promise<void>;
+) => Promise<import("./domEditCommitTypes").DomEditPatchBatchesResult | undefined | void>;
 
 export interface UseTimelineEditingOptions {
   projectId: string | null;

package/src/hooks/useTimelineGroupEditing.ts

@@ -37,6 +37,8 @@ export interface TimelineGroupResizeChange {
 export interface TimelineGroupCommitOptions {
   beforeTiming?: Promise<void>;
   coalesceKey?: string;
+  /** Per-entry undo coalesce window override (ms) — see EditHistoryEntry.coalesceMs. */
+  coalesceMs?: number;
 }
 
 interface UseTimelineGroupEditingOptions {
@@ -137,6 +139,7 @@ export function useTimelineGroupEditing({
       label: string,
       batchChanges: PersistTimelineBatchChange[],
       coalesceKey: string,
+      coalesceMs?: number,
     ) => {
       await persistTimelineBatchEdit({
         projectId,
@@ -148,6 +151,7 @@ export function useTimelineGroupEditing({
         domEditSaveTimestampRef,
         pendingTimelineEditPathRef,
         coalesceKey,
+        coalesceMs,
       });
       forceReloadSdkSession?.();
     },
@@ -176,6 +180,7 @@ export function useTimelineGroupEditing({
       needsExtension: boolean;
       label: string;
       coalesceKey: string;
+      coalesceMs?: number;
     }): Promise<boolean> => {
       const sharedPath = allChangesSharePath(input.changes, activeCompPath);
       const canUseSdk =
@@ -196,7 +201,7 @@ export function useTimelineGroupEditing({
           compositionPath: activeCompPath,
           readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
         },
-        { label: input.label, coalesceKey: input.coalesceKey },
+        { label: input.label, coalesceKey: input.coalesceKey, coalesceMs: input.coalesceMs },
       );
     },
     [
@@ -220,20 +225,38 @@ export function useTimelineGroupEditing({
         if (change.track != null) {
           attrs.push(["data-track-index", formatTimelineAttributeNumber(change.track)]);
         }
-        patchIframeDomTiming(previewIframeRef.current, change.element, attrs);
+        patchIframeDomTiming(previewIframeRef.current, change.element, attrs, activeCompPath);
       }
 
+      // TRACK-ONLY batch: every change keeps its start (moves never carry a
+      // duration change), so nothing timing-related changed — the batch only
+      // rewrites data-track-index, which the renderer never reads (documented
+      // in core runtime/timeline.ts; track is a studio lane concept). The live
+      // DOM patch above + the gesture owner's optimistic store update fully
+      // cover the UI, so after the persist there is nothing to GSAP-shift and
+      // nothing for the preview to recompute: skip the fallback below entirely.
+      // Running it anyway is what made the mirrored z-order lane move blink —
+      // a zero-delta batch yields no scriptText, and finishGroupTimingGsapFallback
+      // used to full-reload the iframe when there was no script to soft-swap
+      // (it now rebinds the runtime timing in place, but a track-only batch
+      // needs NO preview sync at all, so the skip stays).
+      const trackOnly = changes.every((change) => change.start === change.element.start);
+
       const maxEnd = Math.max(...changes.map((change) => change.start + change.element.duration));
       // 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);
       // needsExtension gates the SDK path (setTiming can't grow the root duration),
       // so read the store BEFORE the readout sync below optimistically updates it.
+      // Track-only batches leave every clip end unchanged, so both this and the
+      // readout sync below are provable no-ops there — kept unconditional so the
+      // duration machinery stays on one code path.
       const needsExtension = extendRootDurationIfNeeded(maxEnd);
       // Optimistic duration readout: content-driven (grow AND shrink), read from
       // the just-patched live DOM. See syncPreviewContentDuration.
       syncPreviewContentDuration(previewIframeRef.current);
       const coalesceKey = options?.coalesceKey ?? moveCoalesceKey(changes);
+      const coalesceMs = options?.coalesceMs;
       return enqueueGroupOperation("Move timeline clips", async (projectId) => {
         await options?.beforeTiming;
         const handledBySdk = await trySdkBatchPersist({
@@ -243,6 +266,7 @@ export function useTimelineGroupEditing({
           needsExtension,
           label: "Move timeline clips",
           coalesceKey,
+          coalesceMs,
         });
         if (handledBySdk) return;
 
@@ -261,7 +285,12 @@ export function useTimelineGroupEditing({
               ),
           })),
           coalesceKey,
+          coalesceMs,
         );
+        // Track-only: no timing delta → no GSAP positions to shift and no
+        // reload (see the trackOnly doc above). Mixed batches (any start
+        // change) keep the full fallback below.
+        if (trackOnly) return;
         await finishGroupTimingGsapFallback({
           projectId,
           iframe: previewIframeRef.current,
@@ -313,7 +342,7 @@ export function useTimelineGroupEditing({
               : "data-media-start";
           liveAttrs.push([liveAttr, formatTimelineAttributeNumber(change.playbackStart)]);
         }
-        patchIframeDomTiming(previewIframeRef.current, change.element, liveAttrs);
+        patchIframeDomTiming(previewIframeRef.current, change.element, liveAttrs, activeCompPath);
       }
 
       const maxEnd = Math.max(...changes.map((change) => change.start + change.duration));
@@ -327,6 +356,7 @@ export function useTimelineGroupEditing({
       // the just-patched live DOM. See syncPreviewContentDuration.
       syncPreviewContentDuration(previewIframeRef.current);
       const coalesceKey = options?.coalesceKey ?? resizeCoalesceKey(changes);
+      const coalesceMs = options?.coalesceMs;
       return enqueueGroupOperation("Resize timeline clips", async (projectId) => {
         await options?.beforeTiming;
         const handledBySdk = await trySdkBatchPersist({
@@ -339,6 +369,7 @@ export function useTimelineGroupEditing({
           needsExtension,
           label: "Resize timeline clips",
           coalesceKey,
+          coalesceMs,
         });
         if (handledBySdk) return;
 
@@ -355,6 +386,7 @@ export function useTimelineGroupEditing({
               }),
           })),
           coalesceKey,
+          coalesceMs,
         );
         await finishGroupTimingGsapFallback({
           projectId,

package/src/player/components/Timeline.test.ts

@@ -25,6 +25,7 @@ import {
   PLAYHEAD_HEAD_W,
   RULER_H,
   TRACK_H,
+  TRACKS_LEFT_PAD,
   getTimelineDisplayContentWidth,
   getTimelineFitPps,
 } from "./timelineLayout";
@@ -152,7 +153,8 @@ describe("Timeline provider boundary", () => {
     });
 
     const row = button.parentElement?.parentElement;
-    const trackContent = row?.children.item(1);
+    // Row children: [sticky gutter, TRACKS_LEFT_PAD spacer, time-mapped content].
+    const trackContent = row?.children.item(2);
     expect(onToggleTrackHidden).toHaveBeenCalledWith(0, false);
     expect(trackContent).toBeInstanceOf(HTMLElement);
     if (!(trackContent instanceof HTMLElement)) {
@@ -454,27 +456,27 @@ describe("shouldAutoScrollTimeline", () => {
 });
 
 describe("getTimelineFitPps (min 60s extent + fit headroom)", () => {
-  const viewport = 632; // usable width = 632 - GUTTER - 2 = 598
+  const viewport = 632; // usable width = 632 - GUTTER - TRACKS_LEFT_PAD - 2
 
   it("computes fit pps against the 60s floor for short compositions", () => {
     // A 10s comp maps 60s onto the viewport → the comp takes ~1/6 of the width.
     // (10 * 1.2 = 12s of headroom-padded content is still under the 60s floor.)
     const pps = getTimelineFitPps(viewport, 10);
-    expect(pps).toBeCloseTo((viewport - GUTTER - 2) / MIN_TIMELINE_EXTENT_S);
-    expect(10 * pps).toBeCloseTo((viewport - GUTTER - 2) / 6);
+    expect(pps).toBeCloseTo((viewport - GUTTER - TRACKS_LEFT_PAD - 2) / MIN_TIMELINE_EXTENT_S);
+    expect(10 * pps).toBeCloseTo((viewport - GUTTER - TRACKS_LEFT_PAD - 2) / 6);
   });
 
   it("fits duration * FIT_ZOOM_HEADROOM (not the bare duration) for long compositions", () => {
     expect(getTimelineFitPps(viewport, 60)).toBeCloseTo(
-      (viewport - GUTTER - 2) / (60 * FIT_ZOOM_HEADROOM),
+      (viewport - GUTTER - TRACKS_LEFT_PAD - 2) / (60 * FIT_ZOOM_HEADROOM),
     );
     expect(getTimelineFitPps(viewport, 120)).toBeCloseTo(
-      (viewport - GUTTER - 2) / (120 * FIT_ZOOM_HEADROOM),
+      (viewport - GUTTER - TRACKS_LEFT_PAD - 2) / (120 * FIT_ZOOM_HEADROOM),
     );
   });
 
   it("leaves CapCut-style trailing headroom: the comp ends at 1/1.2 of the usable width", () => {
-    const usable = viewport - GUTTER - 2;
+    const usable = viewport - GUTTER - TRACKS_LEFT_PAD - 2;
     const pps = getTimelineFitPps(viewport, 120);
     // Composition content occupies usable/1.2 px; the remaining ~17% is empty
     // droppable ruler/lane surface past the end.
@@ -484,16 +486,16 @@ describe("getTimelineFitPps (min 60s extent + fit headroom)", () => {
 
   it("falls back to 100 pps before the viewport is measured", () => {
     expect(getTimelineFitPps(0, 10)).toBe(100);
-    expect(getTimelineFitPps(GUTTER, 10)).toBe(100);
+    expect(getTimelineFitPps(GUTTER + TRACKS_LEFT_PAD, 10)).toBe(100);
     expect(getTimelineFitPps(Number.NaN, 10)).toBe(100);
   });
 
   it("uses the floor for zero/invalid durations", () => {
     expect(getTimelineFitPps(viewport, 0)).toBeCloseTo(
-      (viewport - GUTTER - 2) / MIN_TIMELINE_EXTENT_S,
+      (viewport - GUTTER - TRACKS_LEFT_PAD - 2) / MIN_TIMELINE_EXTENT_S,
     );
     expect(getTimelineFitPps(viewport, Number.NaN)).toBeCloseTo(
-      (viewport - GUTTER - 2) / MIN_TIMELINE_EXTENT_S,
+      (viewport - GUTTER - TRACKS_LEFT_PAD - 2) / MIN_TIMELINE_EXTENT_S,
     );
   });
 });
@@ -509,7 +511,7 @@ describe("getTimelineDisplayContentWidth", () => {
   it("still fills the viewport when that is larger than the 60s floor", () => {
     expect(
       getTimelineDisplayContentWidth({ trackContentWidth: 200, viewportWidth: 2000, pps: 5 }),
-    ).toBe(2000 - GUTTER - 2);
+    ).toBe(2000 - GUTTER - TRACKS_LEFT_PAD - 2);
   });
 
   it("tracks a drag ghost past every other bound (drag-to-extend)", () => {
@@ -599,20 +601,28 @@ describe("getTimelineScrollLeftForZoomAnchor", () => {
 });
 
 describe("getTimelinePlayheadLeft", () => {
-  it("offsets the wrapper by half the head width so the line CENTER = GUTTER + t*pps", () => {
+  it("offsets the wrapper by half the head width so the line CENTER = GUTTER + TRACKS_LEFT_PAD + t*pps", () => {
     // Wrapper left + PLAYHEAD_HEAD_W/2 (where the 1px line is centered) must
-    // equal GUTTER + t*pps at any zoom.
-    expect(getTimelinePlayheadLeft(4, 20) + PLAYHEAD_HEAD_W / 2).toBe(GUTTER + 4 * 20);
-    expect(getTimelinePlayheadLeft(10, 7.5) + PLAYHEAD_HEAD_W / 2).toBe(GUTTER + 75);
+    // equal GUTTER + TRACKS_LEFT_PAD + t*pps at any zoom.
+    expect(getTimelinePlayheadLeft(4, 20) + PLAYHEAD_HEAD_W / 2).toBe(
+      GUTTER + TRACKS_LEFT_PAD + 4 * 20,
+    );
+    expect(getTimelinePlayheadLeft(10, 7.5) + PLAYHEAD_HEAD_W / 2).toBe(
+      GUTTER + TRACKS_LEFT_PAD + 75,
+    );
   });
 
-  it("centers the line exactly on the gutter (the 00:00 tick) at t = 0", () => {
-    expect(getTimelinePlayheadLeft(0, 20) + PLAYHEAD_HEAD_W / 2).toBe(GUTTER);
+  it("centers the line exactly on the left pad's end (the 00:00 tick) at t = 0", () => {
+    expect(getTimelinePlayheadLeft(0, 20) + PLAYHEAD_HEAD_W / 2).toBe(GUTTER + TRACKS_LEFT_PAD);
   });
 
   it("guards invalid input", () => {
-    expect(getTimelinePlayheadLeft(Number.NaN, 20)).toBe(GUTTER - PLAYHEAD_HEAD_W / 2);
-    expect(getTimelinePlayheadLeft(4, Number.NaN)).toBe(GUTTER - PLAYHEAD_HEAD_W / 2);
+    expect(getTimelinePlayheadLeft(Number.NaN, 20)).toBe(
+      GUTTER + TRACKS_LEFT_PAD - PLAYHEAD_HEAD_W / 2,
+    );
+    expect(getTimelinePlayheadLeft(4, Number.NaN)).toBe(
+      GUTTER + TRACKS_LEFT_PAD - PLAYHEAD_HEAD_W / 2,
+    );
   });
 });
 
@@ -681,7 +691,7 @@ describe("resolveTimelineAssetDrop", () => {
           trackHeight: 72,
           trackOrder: [0, 3, 7],
         },
-        432,
+        480, // rectLeft(100) + GUTTER + TRACKS_LEFT_PAD + 3s*100pps
         // clientY updated for TRACKS_TOP_PAD=72: rectTop(200) + RULER_H(24) +
         // TRACKS_TOP_PAD(72) + TRACK_H(48) + TRACK_H/2(24) = 368 → row 1 → track 3.
         368,
@@ -702,7 +712,7 @@ describe("resolveTimelineAssetDrop", () => {
           trackHeight: 72,
           trackOrder: [0, 3, 7],
         },
-        250,
+        250 + TRACKS_LEFT_PAD,
         600,
       ),
     ).toEqual({ start: 1.18, track: 8 });