@hyperframes/studio 0.8.126 → 0.8.128

package/src/hooks/useTimelineEditing.ts

@@ -1,30 +1,10 @@
 // fallow-ignore-file complexity
-import { useCallback, useRef } from "react";
+import { useRef } from "react";
 import { useStableHandlers } from "./useStableHandlers";
 import { usePlayerStore, type TimelineElement } from "../player";
-import { toAuthoredStart, toCompositionTime } from "../player/store/timelineElement";
 import { useRazorSplit } from "./useRazorSplit";
 import { selectSplittableElements } from "../utils/timelineElementSplit";
 import { useTimelineAssetDropOps } from "./useTimelineAssetDropOps";
-import {
-  applyTimelineStackingReorder,
-  patchIframeDomTiming,
-  persistTimelineEdit,
-  formatTimelineAttributeNumber,
-  formatTimelineMediaOffset,
-  extendRootDurationIfNeeded,
-  buildTimelineMoveTimingPatch,
-  buildTimelineResizeTimingPatch,
-} from "./timelineEditingHelpers";
-import { playbackStartAttributeForElement } from "../player/lib/timelineElementHelpers";
-import {
-  captureDurationRollback,
-  finishClipTimingFallback,
-  sdkTimingGsapSync,
-  readFileContent,
-  syncPreviewContentDuration,
-} from "./timelineTimingSync";
-import type { PersistTimelineEditInput } from "./timelineEditingHelpers";
 import { useSetAudioGroupAttribute } from "./timelineAudioGroupVolume";
 import { useSetElementAttribute } from "./timelineElementFxAttribute";
 import { useSetElementsAttribute } from "./timelineElementsAttribute";
@@ -42,12 +22,10 @@ import {
   useTimelineTrackVisibilityEditing,
 } from "./timelineTrackVisibility";
 import { useTimelineGroupEditing } from "./useTimelineGroupEditing";
+import { useTimelineClipTimingEditing } from "./useTimelineClipTimingEditing";
 import { useBlockedTimelineEditToast } from "./useBlockedTimelineEditToast";
 import { useTimelineEditGate, type TimelineEditOutcome } from "./timelineEditPermission";
-import { serializeZLaneGesture } from "../components/nle/zLaneGesture";
-import { cutoverCommittedOrThrow, sdkTimingPersist } from "../utils/sdkCutover";
-import type { TimelineMoveUpdates, UseTimelineEditingOptions } from "./useTimelineEditingTypes";
-import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
+import type { UseTimelineEditingOptions } from "./useTimelineEditingTypes";
 
 export function useTimelineEditing({
   projectId,
@@ -76,51 +54,6 @@ export function useTimelineEditing({
   const checkEditable = useTimelineEditGate(canEdit, showToast);
   const guard = useTimelineEditGuard(canEdit, showToast);
 
-  const enqueueEdit = useCallback(
-    (
-      element: TimelineElement,
-      label: string,
-      buildPatches: PersistTimelineEditInput["buildPatches"],
-      coalesceKey?: string,
-    ): 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,
-            coalesceKey,
-          }),
-        )
-        .then(() => {
-          forceReloadSdkSession?.();
-        });
-      editQueueRef.current = queued.catch((error) => {
-        console.error(`[Timeline] Failed to persist: ${label}`, error);
-      });
-      return queued;
-    },
-    [
-      activeCompPath,
-      recordEdit,
-      writeProjectFile,
-      pendingTimelineEditPathRef,
-      showToast,
-      isRecordingRef,
-      forceReloadSdkSession,
-    ],
-  );
   const groupEditing = useTimelineGroupEditing({
     activeCompPath,
     editQueueRef,
@@ -137,231 +70,24 @@ export function useTimelineEditing({
     showToast,
     writeProjectFile,
   });
-  const handleTimelineElementMove = useCallback(
-    // fallow-ignore-next-line complexity
-    (element: TimelineElement, updates: TimelineMoveUpdates) => {
-      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;
-        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);
-        // 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,
-            authoredStart,
-            element.duration,
-            track,
-          );
-        };
-        const coalesceKey = `timeline-move:${element.hfId ?? element.id}`;
-        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,
-            recordEdit,
-            writeProjectFile,
-            edit: { kind: "shift", delta: updates.start - element.start },
-            sdkGsap,
-          }).finally(() => invalidateGsapCache?.());
-        const moveFallback = () =>
-          enqueueEdit(element, "Move timeline clip", buildMovePatches, coalesceKey).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", coalesceKey, 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,
-    ],
-  );
-
-  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);
-      // 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 + updates.duration);
-      // Optimistic duration readout: content-driven (grow AND shrink), from the just-patched live DOM. See syncPreviewContentDuration.
-      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 coalesceKey = `timeline-resize:${element.hfId ?? element.id}`;
-      const finishResizeGsapSync = (sdkGsap?: ReturnType<typeof sdkTimingGsapSync>) =>
-        finishClipTimingFallback({
-          iframe: previewIframeRef.current,
-          reloadPreview,
-          projectId: projectIdRef.current,
-          targetPath,
-          domId: element.domId,
-          label: "Resize timeline clip",
-          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, coalesceKey).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", coalesceKey, 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,
-    ],
-  );
+  const { handleTimelineElementMove, handleTimelineElementResize } = useTimelineClipTimingEditing({
+    activeCompPath,
+    timelineElements,
+    showToast,
+    writeProjectFile,
+    recordEdit,
+    reloadPreview,
+    previewIframeRef,
+    pendingTimelineEditPathRef,
+    isRecordingRef,
+    sdkSession,
+    publishSdkSession,
+    forceReloadSdkSession,
+    invalidateGsapCache,
+    handleDomZIndexReorderCommitRef,
+    editQueueRef,
+    projectIdRef,
+  });
 
   const handleToggleTrackHidden = useTimelineTrackVisibilityEditing({
     projectIdRef,

package/src/hooks/useTimelineGroupEditing.test.tsx

@@ -1,11 +1,20 @@
 // @vitest-environment happy-dom
 
 import { act } from "react";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createStudioApi,
+  openProjectHistory,
+  type StudioApiAdapter,
+} from "@hyperframes/studio-server";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { Root } from "react-dom/client";
 import type { TimelineElement } from "../player";
 import { persistTimelineMoveEditsAtomically } from "./timelineMoveAdapter";
 import { useTimelineGroupEditing } from "./useTimelineGroupEditing";
+import { usePersistentEditHistory } from "./usePersistentEditHistory";
 import { installReactActEnvironment, mountReactHarness } from "./domSelectionTestHarness";
 
 installReactActEnvironment();
@@ -149,3 +158,85 @@ it.each([false, true])(
     }
   },
 );
+
+const SLOWER_THAN_THE_DEFAULT_WINDOW_MS = 400;
+
+it("undoes each group move with its GSAP rewrite in one step, however long the rewrite takes", async () => {
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+  const dir = mkdtempSync(join(tmpdir(), "hf-group-move-undo-"));
+  const historyRoot = mkdtempSync(join(tmpdir(), "hf-group-move-undo-history-"));
+  const before = [
+    '<div data-composition-id="root" data-duration="4">',
+    '<div id="a" data-start="0" data-duration="2"></div>',
+    '<div id="b" data-start="0" data-duration="2"></div>',
+    "</div>",
+    '<script>const tl = gsap.timeline({ paused: true }); tl.to("#a", { x: 10, duration: 1 }, 0); tl.to("#b", { x: 10, duration: 1 }, 0); window.__timelines["root"] = tl;</script>',
+  ].join("");
+  writeFileSync(join(dir, "index.html"), before);
+  const history = await openProjectHistory({ projectDir: dir, historyRoot });
+  const api = createStudioApi({
+    listProjects: () => [],
+    resolveProject: (id: string) => (id === "demo" ? { id, dir } : null),
+    history: () => history,
+  } as unknown as StudioApiAdapter);
+  let rewriteAsked = () => {};
+  vi.stubGlobal("fetch", async (url: string, init?: RequestInit) => {
+    if (url.includes("/gsap-mutations")) {
+      rewriteAsked();
+      await new Promise((wait) => setTimeout(wait, SLOWER_THAN_THE_DEFAULT_WINDOW_MS));
+    }
+    return api.request(url.replace(/^\/api/, ""), init);
+  });
+  let editHistory!: ReturnType<typeof usePersistentEditHistory>;
+  let editing!: ReturnType<typeof useTimelineGroupEditing>;
+  function Harness() {
+    editHistory = usePersistentEditHistory({ projectId: "demo" });
+    editing = useTimelineGroupEditing({
+      activeCompPath: "index.html",
+      editQueueRef: { current: Promise.resolve() },
+      pendingTimelineEditPathRef: { current: new Set() },
+      previewIframeRef: { current: null },
+      projectIdRef: { current: "demo" },
+      recordEdit: editHistory.recordEdit,
+      reloadPreview: vi.fn(),
+      showToast: vi.fn(),
+      writeProjectFile: async (path, content) => writeFileSync(join(dir, path), content),
+    });
+    return null;
+  }
+  const root = mountReactHarness(<Harness />);
+  const file = () => readFileSync(join(dir, "index.html"), "utf8");
+  const moveTo = (from: number, to: number) =>
+    act(async () => {
+      const rewriting = new Promise<void>((resolve) => (rewriteAsked = resolve));
+      const moved = editing.handleTimelineGroupMove([
+        { element: el("a", from, 2), start: to },
+        { element: el("b", from, 2), start: to },
+      ]);
+      await rewriting;
+      await vi.advanceTimersByTimeAsync(SLOWER_THAN_THE_DEFAULT_WINDOW_MS);
+      await moved;
+    });
+  const undo = () =>
+    act(() =>
+      editHistory.undo({ readFile: async (path) => readFileSync(join(dir, path), "utf8") }),
+    );
+  try {
+    await moveTo(0, 1);
+    const once = file();
+    await moveTo(1, 2);
+    expect(file()).toContain('tl.to("#a", { x: 10, duration: 1 }, 2)');
+
+    await undo();
+    expect(file()).toBe(once);
+    await undo();
+    expect(file()).toBe(before);
+  } finally {
+    act(() => root.unmount());
+    await history.close();
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    rmSync(dir, { recursive: true, force: true });
+    rmSync(historyRoot, { recursive: true, force: true });
+  }
+});

package/src/hooks/useTimelineGroupEditing.ts

@@ -10,8 +10,8 @@ import {
   type PublishSdkSession,
 } from "../utils/sdkCutover";
 import {
-  buildTimelineMoveTimingPatch,
-  buildTimelineResizeTimingPatch,
+  applyTimelineMoveAttributes,
+  applyTimelineResizeAttributes,
   extendRootDurationIfNeeded,
   formatTimelineAttributeNumber,
   formatTimelineMediaOffset,
@@ -24,10 +24,11 @@ import { playbackStartAttributeForElement } from "../player/lib/timelineElementH
 import {
   captureDurationRollback,
   finishGroupTimingGsapFallback,
+  timingGestureStep,
   sdkTimingGsapSync,
   readFileContent,
-  scaleGsapPositions,
-  shiftGsapPositions,
+  scaleGsapMutation,
+  shiftGsapMutation,
   syncPreviewContentDuration,
 } from "./timelineTimingSync";
 import type { GsapMutationStatus } from "./gsapMutationClient";
@@ -50,8 +51,6 @@ export interface TimelineGroupResizeChange {
 export interface TimelineGroupCommitOptions {
   beforeTiming?: Promise<void>;
   coalesceKey?: string;
-  /** Per-entry undo coalesce window override (ms) — see EditHistoryEntry.coalesceMs. */
-  coalesceMs?: number;
   /** Overrides the default "Move timeline clips" undo-history label. Coalescing
    *  keeps the LAST entry's label (editHistory.ts), so a mechanical follow-up
    *  move folded into another gesture's coalesceKey (e.g. the ripple after a
@@ -95,14 +94,6 @@ function allChangesSharePath(
     : null;
 }
 
-function moveCoalesceKey(changes: readonly TimelineGroupMoveChange[]): string {
-  return `timeline-group-move:${changes.map((change) => change.element.hfId ?? change.element.id).join(",")}`;
-}
-
-function resizeCoalesceKey(changes: readonly TimelineGroupResizeChange[]): string {
-  return `timeline-group-resize:${changes.map((change) => change.element.hfId ?? change.element.id).join(",")}`;
-}
-
 function toSdkTimingChanges<T extends { element: TimelineElement }>(
   changes: readonly T[],
   timingUpdate: (change: T) => { start: number; duration?: number },
@@ -287,8 +278,7 @@ export function useTimelineGroupEditing({
       // 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;
+      const { coalesceKey, coalesceMs } = timingGestureStep("timeline-group-move", options);
       const label = options?.label ?? "Move timeline clips";
       return enqueueGroupOperation(label, async (projectId) => {
         await options?.beforeTiming;
@@ -312,7 +302,7 @@ export function useTimelineGroupEditing({
             changes.map((change) => ({
               element: change.element,
               buildPatches: (original, target) =>
-                buildTimelineMoveTimingPatch(
+                applyTimelineMoveAttributes(
                   original,
                   target,
                   toAuthoredStart(change.element, change.start),
@@ -347,12 +337,8 @@ export function useTimelineGroupEditing({
             changes,
             sdkGsap: sdk?.sdkGsap,
             resolveChangePath: (element) => targetPathFor(element, activeCompPath),
-            mutateChange: (change, changePath) => {
-              const delta = change.start - change.element.start;
-              const domId = change.element.domId;
-              if (delta === 0 || !domId) return null;
-              return shiftGsapPositions(projectId, changePath, domId, delta);
-            },
+            mutationFor: (change) =>
+              shiftGsapMutation(change.element.domId, change.start - change.element.start),
           });
         } finally {
           invalidateGsapCache?.();
@@ -411,8 +397,7 @@ export function useTimelineGroupEditing({
       // Optimistic duration readout: content-driven (grow AND shrink), read from
       // the just-patched live DOM. See syncPreviewContentDuration.
       syncPreviewContentDuration(previewIframeRef.current);
-      const coalesceKey = options?.coalesceKey ?? resizeCoalesceKey(changes);
-      const coalesceMs = options?.coalesceMs;
+      const { coalesceKey, coalesceMs } = timingGestureStep("timeline-group-resize", options);
       return enqueueGroupOperation("Resize timeline clips", async (projectId) => {
         await options?.beforeTiming;
         const sdk = await trySdkBatchPersist({
@@ -434,7 +419,7 @@ export function useTimelineGroupEditing({
             changes.map((change) => ({
               element: change.element,
               buildPatches: (original, target) =>
-                buildTimelineResizeTimingPatch(original, target, change.element, {
+                applyTimelineResizeAttributes(original, target, change.element, {
                   start: change.start,
                   duration: change.duration,
                   playbackStart: change.playbackStart,
@@ -460,22 +445,14 @@ export function useTimelineGroupEditing({
             changes,
             sdkGsap: sdk?.sdkGsap,
             resolveChangePath: (element) => targetPathFor(element, activeCompPath),
-            mutateChange: (change, changePath) => {
-              const domId = change.element.domId;
-              const timingChanged =
-                change.start !== change.element.start ||
-                change.duration !== change.element.duration;
-              if (!timingChanged || !domId) return null;
-              return scaleGsapPositions(
-                projectId,
-                changePath,
-                domId,
+            mutationFor: (change) =>
+              scaleGsapMutation(
+                change.element.domId,
                 toCompositionTime(change.element, change.element.start),
                 change.element.duration,
                 toCompositionTime(change.element, change.start),
                 change.duration,
-              );
-            },
+              ),
           });
         } finally {
           invalidateGsapCache?.();

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

@@ -87,10 +87,17 @@ describe("timeline viewport geometry", () => {
   });
 });
 
+/** The track's content row: a clip's parent, past its `display: contents` wrapper. */
+function trackContentOf(clip: HTMLElement | null | undefined): HTMLElement | null {
+  let row = clip?.parentElement ?? null;
+  while (row?.style.display === "contents") row = row.parentElement;
+  return row;
+}
+
 function getHorizontalGeometry(host: HTMLElement, clipId: string, tickLabel: string) {
   const clip = host.querySelector<HTMLElement>(`[data-el-id="${clipId}"]`);
   if (!clip) throw new Error(`Missing timeline clip ${clipId}`);
-  const trackContent = clip.parentElement;
+  const trackContent = trackContentOf(clip);
   if (!trackContent) throw new Error(`Missing content row for ${clipId}`);
   const trackHeader = trackContent.previousElementSibling;
   if (!(trackHeader instanceof HTMLElement)) throw new Error(`Missing track header for ${clipId}`);
@@ -708,7 +715,7 @@ describe("Timeline provider boundary", () => {
     expect(host.querySelector('button[aria-label="Hide clip-2 lanes"]')).toBeNull();
 
     const clip = host.querySelector<HTMLElement>('[data-el-id="clip-1"]');
-    const row = clip?.parentElement?.parentElement;
+    const row = trackContentOf(clip)?.parentElement;
     expectTrackExpansion(row, ["clip-1"], TRACK_H + 2 * LANE_H);
 
     // Collapsing sticks (does not bounce back open via auto-expand).
@@ -731,8 +738,9 @@ describe("Timeline provider boundary", () => {
   it("expands and collapses every clip on a shared track together", () => {
     const { host, root } = renderSharedAutomationTimeline();
 
-    const row = host.querySelector<HTMLElement>('[data-el-id="narration-1"]')?.parentElement
-      ?.parentElement;
+    const row = trackContentOf(
+      host.querySelector<HTMLElement>('[data-el-id="narration-1"]'),
+    )?.parentElement;
     // A row of several clips is named for the track, so the caret is too.
     const caret = () => host.querySelector<HTMLButtonElement>('button[aria-label$=" lanes"]');
     expect(caret()?.getAttribute("aria-label")).toBe("Show Track 1 lanes");

package/src/player/components/TimelineClip.tsx

@@ -20,6 +20,7 @@ import { clipSpeedSuffix } from "./clipToolAttrs";
 interface TimelineClipProps {
   el: TimelineElement;
   pps: number;
+  passengerStyle?: CSSProperties;
   clipY: number;
   clipHeight?: number;
   isSelected: boolean;
@@ -46,6 +47,7 @@ interface TimelineClipProps {
 export const TimelineClip = memo(function TimelineClip({
   el,
   pps,
+  passengerStyle,
   clipY,
   clipHeight,
   isSelected,
@@ -123,6 +125,7 @@ export const TimelineClip = memo(function TimelineClip({
     padding: 0,
     textAlign: "left",
     transform: isDragging ? "translateY(-1px)" : undefined,
+    ...passengerStyle,
   };
 
   return (

package/src/player/components/TimelineCompactDiamonds.tsx

@@ -1,3 +1,4 @@
+import type { CSSProperties } from "react";
 import type { KeyframeCacheEntry, TimelineElement } from "../store/playerStore";
 import { CLIP_Y } from "./timelineLayout";
 import type { TimelineLaneBaseProps } from "./timelineLaneProps";
@@ -22,6 +23,7 @@ interface TimelineCompactDiamondsProps extends Pick<
   beatsActive: boolean;
   accentColor: string;
   isSelected: boolean;
+  passengerStyle?: CSSProperties;
   rovingTargetId: string | null;
 }
 
@@ -35,6 +37,7 @@ export function TimelineCompactDiamonds({
   beatsActive,
   accentColor,
   isSelected,
+  passengerStyle,
   currentTime,
   selectedKeyframes,
   rovingTargetId,
@@ -55,6 +58,7 @@ export function TimelineCompactDiamonds({
         width,
         height: rowHeight - 2 * CLIP_Y,
         zIndex: isSelected ? 11 : 6,
+        ...passengerStyle,
       }}
     >
       <TimelineClipDiamonds