@hyperframes/studio 0.7.86 → 0.7.87

package/src/player/components/useTimelineActiveClips.ts

@@ -1,5 +1,5 @@
 import { useCallback, useLayoutEffect, useRef } from "react";
-import { liveTime } from "../store/playerStore";
+import { liveTime, type TimelineElement } from "../store/playerStore";
 import { useMountEffect } from "../../hooks/useMountEffect";
 
 interface ActiveClipRecord {
@@ -13,7 +13,34 @@ interface ActiveClipRecord {
 interface UseTimelineActiveClipsInput {
   scrollRef: React.RefObject<HTMLDivElement | null>;
   currentTime: number;
-  clipStateVersion: string;
+  clipStateVersion: unknown;
+  elementStateVersion: unknown;
+}
+
+function isTimelineIntervalActive(
+  interval: Pick<ActiveClipRecord, "start" | "end" | "hidden">,
+  time: number,
+): boolean {
+  return (
+    Number.isFinite(time) &&
+    !interval.hidden &&
+    Number.isFinite(interval.start) &&
+    Number.isFinite(interval.end) &&
+    time >= interval.start &&
+    time <= interval.end
+  );
+}
+
+/** Model-first active state. Rendered nodes receive this on their first mount. */
+export function isTimelineClipActive(element: TimelineElement, time: number): boolean {
+  return isTimelineIntervalActive(
+    {
+      start: element.start,
+      end: element.start + Math.max(0, element.duration),
+      hidden: element.hidden === true,
+    },
+    time,
+  );
 }
 
 function readFiniteNumber(value: string | undefined): number | null {
@@ -27,66 +54,37 @@ function readClipRecord(element: Element): ActiveClipRecord | null {
   const id = element.dataset.elId;
   const start = readFiniteNumber(element.dataset.clipStart);
   const end = readFiniteNumber(element.dataset.clipEnd);
-  const hidden = element.dataset.clipHidden === "true";
   if (!id || start === null || end === null) return null;
-  return { id, start, end, hidden, element };
+  return { id, start, end, hidden: element.dataset.clipHidden === "true", element };
 }
 
 function collectTimelineClipRecords(container: HTMLElement): ActiveClipRecord[] {
-  const records: ActiveClipRecord[] = [];
-  for (const element of container.querySelectorAll('[data-clip="true"]')) {
-    const record = readClipRecord(element);
-    if (record) records.push(record);
-  }
-  return records;
-}
-
-function indexClipRecordsById(records: ActiveClipRecord[]): Map<string, ActiveClipRecord> {
-  const recordsById = new Map<string, ActiveClipRecord>();
-  for (const record of records) recordsById.set(record.id, record);
-  return recordsById;
+  return [...container.querySelectorAll('[data-clip="true"]')]
+    .map(readClipRecord)
+    .filter((record): record is ActiveClipRecord => record !== null);
 }
 
 function getActiveClipIds(records: ActiveClipRecord[], time: number): Set<string> {
-  const next = new Set<string>();
-  if (!Number.isFinite(time)) return next;
-  for (const record of records) {
-    if (record.hidden) continue;
-    if (time >= record.start && time <= record.end) next.add(record.id);
-  }
-  return next;
-}
-
-function setsMatch(left: Set<string>, right: Set<string>): boolean {
-  if (left.size !== right.size) return false;
-  for (const value of left) {
-    if (!right.has(value)) return false;
-  }
-  return true;
+  return new Set(
+    records.filter((record) => isTimelineIntervalActive(record, time)).map((record) => record.id),
+  );
 }
 
 function applyActiveClipDiff(
   records: ActiveClipRecord[],
   previous: Set<string>,
   time: number,
-  // Force every record's attribute to match its active state instead of only
-  // touching clips whose active-state changed. Required whenever `records` were
-  // freshly re-queried after a render: a clip that stayed active but got a new
-  // DOM node (e.g. moved lanes on a reorder) would otherwise be skipped by the
-  // diff and render without `data-active` despite still being at the playhead.
   syncAll = false,
-) {
+): void {
   const next = getActiveClipIds(records, time);
-  const changed = !setsMatch(previous, next);
   for (const record of records) {
-    const wasActive = previous.has(record.id);
     const isActive = next.has(record.id);
-    if (!syncAll && wasActive === isActive) continue;
-    record.element.toggleAttribute("data-active", isActive);
+    if (syncAll || previous.has(record.id) !== isActive) {
+      record.element.toggleAttribute("data-active", isActive);
+    }
   }
   previous.clear();
   for (const id of next) previous.add(id);
-  return changed;
 }
 
 export function updateTimelineActiveClipClasses(
@@ -94,30 +92,28 @@ export function updateTimelineActiveClipClasses(
   previous: Set<string>,
   time: number,
   syncAll = false,
-) {
+): void {
   applyActiveClipDiff(collectTimelineClipRecords(container), previous, time, syncAll);
 }
 
+/** Keeps the currently mounted clip window synchronized with the RAF playback clock. */
 export function useTimelineActiveClips({
   scrollRef,
   currentTime,
   clipStateVersion,
-}: UseTimelineActiveClipsInput) {
+  elementStateVersion,
+}: UseTimelineActiveClipsInput): void {
   const recordsRef = useRef<ActiveClipRecord[]>([]);
-  const recordsByIdRef = useRef(new Map<string, ActiveClipRecord>());
   const previousActiveIdsRef = useRef(new Set<string>());
-
   const refreshRecords = useCallback(
     (time: number) => {
       const scroll = scrollRef.current;
       if (!scroll) {
         recordsRef.current = [];
-        recordsByIdRef.current.clear();
         previousActiveIdsRef.current.clear();
         return;
       }
       recordsRef.current = collectTimelineClipRecords(scroll);
-      recordsByIdRef.current = indexClipRecordsById(recordsRef.current);
       applyActiveClipDiff(recordsRef.current, previousActiveIdsRef.current, time, true);
     },
     [scrollRef],
@@ -125,12 +121,10 @@ export function useTimelineActiveClips({
 
   useLayoutEffect(() => {
     refreshRecords(currentTime);
-  }, [currentTime, clipStateVersion, refreshRecords]);
-
-  useMountEffect(() => {
-    const unsub = liveTime.subscribe((time) => {
+  }, [clipStateVersion, currentTime, elementStateVersion, refreshRecords]);
+  useMountEffect(() =>
+    liveTime.subscribe((time) => {
       applyActiveClipDiff(recordsRef.current, previousActiveIdsRef.current, time);
-    });
-    return unsub;
-  });
+    }),
+  );
 }

package/src/player/components/useTimelineClipDrag.ts

@@ -3,18 +3,15 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import {
   applyTimelineAutoScrollStep,
   resolveTimelineAutoScrollLoopAction,
-  resolveTimelineDragEscape,
 } from "./timelineEditing";
 import { usePlayerStore } from "../store/playerStore";
 import type { TimelineElement } from "../store/playerStore";
-import { isMusicTrack, isAudioTimelineElement } from "../../utils/timelineInspector";
 import { mergeUserBeats } from "../../utils/beatEditing";
 import {
   buildTimelineGroupResizeMembers,
   type TimelineGroupResizeSession,
 } from "./timelineGroupEditing";
 import { collectTimelineSnapTargets, type TimelineSnapTarget } from "./timelineSnapping";
-import { commitDraggedClipMove } from "./timelineClipDragCommit";
 import type { StackingPatch } from "./timelineStackingSync";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import {
@@ -28,11 +25,9 @@ import type {
   ResizingClipState,
   BlockedClipState,
 } from "./timelineClipDragTypes";
-import {
-  beginTimelineOptimisticGesture,
-  rollbackLatestTimelineOptimisticGesture,
-} from "./timelineOptimisticRevision";
-import { commitTimelineGroupResize } from "./timelineGroupResizeCommit";
+import { mountTimelineClipDragGestureLifecycle } from "./timelineClipDragGestureLifecycle";
+import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";
+import type { TimelineRowGeometry } from "./timelineLayout";
 
 export type {
   DraggedClipState,
@@ -48,7 +43,7 @@ interface UseTimelineClipDragInput {
   ppsRef: React.RefObject<number>;
   durationRef: React.RefObject<number>;
   trackOrderRef: React.RefObject<number[]>;
-  rowHeightsRef?: React.RefObject<readonly number[]>;
+  rowGeometryRef?: React.RefObject<TimelineRowGeometry>;
   onMoveElement?: (
     element: TimelineElement,
     updates: Pick<TimelineElement, "start" | "track">,
@@ -86,7 +81,7 @@ export function useTimelineClipDrag({
   ppsRef,
   durationRef,
   trackOrderRef,
-  rowHeightsRef,
+  rowGeometryRef,
   onMoveElement,
   onMoveElements,
   onResizeElement,
@@ -102,12 +97,11 @@ export function useTimelineClipDrag({
   const rawBeatTimes = usePlayerStore((s) => s.beatAnalysis?.beatTimes ?? EMPTY_BEAT_TIMES);
   const rawBeatStrengths = usePlayerStore((s) => s.beatAnalysis?.beatStrengths ?? EMPTY_BEAT_TIMES);
   const beatEdits = usePlayerStore((s) => s.beatEdits);
-  const musicStart = usePlayerStore((s) => s.elements.find(isMusicTrack)?.start ?? 0);
-  const musicPlaybackStart = usePlayerStore(
-    (s) => s.elements.find(isMusicTrack)?.playbackStart ?? 0,
-  );
-  const musicDuration = usePlayerStore((s) => s.elements.find(isMusicTrack)?.duration ?? 0);
-  const musicSrc = usePlayerStore((s) => s.elements.find(isMusicTrack)?.src ?? null);
+  const musicElement = usePlayerStore((s) => getTimelineElementIndexes(s.elements).musicElement);
+  const musicStart = musicElement?.start ?? 0;
+  const musicPlaybackStart = musicElement?.playbackStart ?? 0;
+  const musicDuration = musicElement?.duration ?? 0;
+  const musicSrc = musicElement?.src ?? null;
 
   const adjustedBeatTimes = useMemo(() => {
     if (rawBeatTimes === EMPTY_BEAT_TIMES || musicDuration === 0) return EMPTY_BEAT_TIMES;
@@ -234,23 +228,21 @@ export function useTimelineClipDrag({
       // Build the audio-track set once per gesture (see snapTargetsCacheRef): it
       // only feeds zone-aware drop placement and is frozen while dragging.
       if (!dragAudioTracksRef.current) {
-        dragAudioTracksRef.current = new Set(
-          elementsRef.current.filter(isAudioTimelineElement).map((e) => e.track),
-        );
+        dragAudioTracksRef.current = getTimelineElementIndexes(elementsRef.current).audioTracks;
       }
       return computeDragPreview(drag, clientX, clientY, {
         scroll: scrollRef.current,
         pps: ppsRef.current,
         duration: durationRef.current,
         trackOrder: trackOrderRef.current,
-        rowHeights: rowHeightsRef?.current,
+        rowHeights: rowGeometryRef?.current.rowHeights,
         elements: elementsRef.current,
         selectedKeys: usePlayerStore.getState().selectedElementIds,
         buildSnapTargets,
         audioTracks: dragAudioTracksRef.current,
       });
     },
-    [scrollRef, ppsRef, durationRef, trackOrderRef, rowHeightsRef, buildSnapTargets],
+    [scrollRef, ppsRef, durationRef, trackOrderRef, rowGeometryRef, buildSnapTargets],
   );
 
   // Recompute the trim preview for a pointer x. Shared by the pointermove resize
@@ -363,215 +355,33 @@ export function useTimelineClipDrag({
   stopClipDragAutoScrollRef.current = stopClipDragAutoScroll;
 
   useMountEffect(() => {
-    const clearSuppressedClick = () => {
-      requestAnimationFrame(() => {
-        suppressClickRef.current = false;
-      });
-    };
-
-    /* ── pointermove branch handlers (dispatched by drag/resize/blocked) ── */
-    const handleResizePointerMove = (e: PointerEvent, resize: ResizingClipState) => {
-      const distance = Math.abs(e.clientX - resize.originClientX);
-      if (!resize.started && distance < 2) return;
-
-      setShowPopover(false);
-      setRangeSelectionRef.current?.(null);
-
-      applyResizePointerRef.current(resize, e.clientX);
-      // Edge auto-scroll during a trim, exactly like the move branch — lets a
-      // right-edge trim keep extending past the current viewport (the stepper
-      // re-runs the scroll-compensated preview each frame).
-      syncClipDragAutoScrollRef.current(e.clientX, e.clientY);
-    };
-
-    const handleBlockedPointerMove = (e: PointerEvent, blocked: BlockedClipState) => {
-      const distance = Math.hypot(
-        e.clientX - blocked.originClientX,
-        e.clientY - blocked.originClientY,
-      );
-      const threshold = blocked.intent === "move" ? 4 : 2;
-      if (!blocked.started && distance < threshold) return;
-      if (!blocked.started) {
-        blocked.started = true;
-        blockedClipRef.current = blocked;
-        suppressClickRef.current = true;
-        setShowPopover(false);
-        setRangeSelectionRef.current?.(null);
-        onBlockedEditAttemptRef.current?.(blocked.element, blocked.intent);
-      }
-    };
-
-    const handleDragPointerMove = (e: PointerEvent, drag: DraggedClipState) => {
-      const distance = Math.hypot(e.clientX - drag.originClientX, e.clientY - drag.originClientY);
-      if (!drag.started && distance < 4) return;
-
-      setShowPopover(false);
-      setRangeSelectionRef.current?.(null);
-
-      setDraggedClip((prev) =>
-        prev ? updateDraggedClipPreviewRef.current(prev, e.clientX, e.clientY) : prev,
-      );
-      syncClipDragAutoScrollRef.current(e.clientX, e.clientY);
-    };
-
-    const handleWindowPointerMove = (e: PointerEvent) => {
-      const resize = resizingClipRef.current;
-      if (resize) return handleResizePointerMove(e, resize);
-      const blocked = blockedClipRef.current;
-      if (blocked) return handleBlockedPointerMove(e, blocked);
-      const drag = draggedClipRef.current;
-      if (drag) handleDragPointerMove(e, drag);
-    };
-
-    /* ── pointerup commit handlers (dispatched by drag/resize/blocked) ──── */
-    const commitResizePointerUp = (resize: ResizingClipState) => {
-      resizingClipRef.current = null;
-      setResizingClip(null);
-      const groupSession = groupResizeRef.current;
-      groupResizeRef.current = null;
-      if (!resize.started) {
-        // No preview ran, so no group store-mutation to undo; guard is defensive.
-        if (groupSession) restoreGroupResizeMembers(groupSession);
-        return;
-      }
-
-      suppressClickRef.current = true;
-      clearSuppressedClick();
-
-      if (groupSession) {
-        commitTimelineGroupResize(groupSession, updateElement, onResizeElementsRef.current);
-        return;
-      }
-
-      const hasChanged =
-        resize.previewStart !== resize.element.start ||
-        resize.previewDuration !== resize.element.duration ||
-        resize.previewPlaybackStart !== resize.element.playbackStart;
-      if (!hasChanged) return;
-
-      const resizeKey = resize.element.key ?? resize.element.id;
-      const revision = beginTimelineOptimisticGesture(updateElement, [resizeKey]);
-      updateElement(resizeKey, {
-        start: resize.previewStart,
-        duration: resize.previewDuration,
-        playbackStart: resize.previewPlaybackStart,
-      });
-
-      Promise.resolve(
-        onResizeElementRef.current?.(resize.element, {
-          start: resize.previewStart,
-          duration: resize.previewDuration,
-          playbackStart: resize.previewPlaybackStart,
-        }),
-      ).catch((error) => {
-        rollbackLatestTimelineOptimisticGesture(updateElement, revision, [
-          {
-            key: resizeKey,
-            updates: {
-              start: resize.element.start,
-              duration: resize.element.duration,
-              playbackStart: resize.element.playbackStart,
-            },
-          },
-        ]);
-        console.error("[Timeline] Failed to persist clip resize", error);
-      });
-    };
-
-    const finishBlockedPointerUp = (blocked: BlockedClipState) => {
-      blockedClipRef.current = null;
-      if (!blocked.started) return;
-      clearSuppressedClick();
-    };
-
-    const commitDragPointerUp = (drag: DraggedClipState) => {
-      draggedClipRef.current = null;
-      setDraggedClip(null);
-      if (!drag.started) return;
-
-      suppressClickRef.current = true;
-      clearSuppressedClick();
-
-      // Commit the drag — insert (new track), main-track ripple (reflow contiguous),
-      // a plain single-clip move, or a multi-selection move (every selected clip
-      // shifts by the dragged clip's time delta). See timelineClipDragCommit.
-      commitDraggedClipMove(drag, {
-        elements: elementsRef.current,
-        trackOrder: trackOrderRef.current,
-        updateElement,
-        onMoveElement: onMoveElementRef.current,
-        onMoveElements: onMoveElementsRef.current,
-        selectedKeys: usePlayerStore.getState().selectedElementIds,
-        // Lane ↔ stacking: engages only when the timeline layer provisions both
-        // deps (Timeline.tsx). Absent → commitDraggedClipMove skips the z-sync.
-        readZIndex: readZIndexRef.current,
-        onStackingPatches: onStackingPatchesRef.current,
-        refreshAfterLaneMove: refreshAfterLaneMoveRef.current,
-      });
-    };
-
-    const handleWindowPointerUp = () => {
-      stopClipDragAutoScrollRef.current();
-
-      const resize = resizingClipRef.current;
-      if (resize) return commitResizePointerUp(resize);
-
-      const blocked = blockedClipRef.current;
-      if (blocked) return finishBlockedPointerUp(blocked);
-
-      const drag = draggedClipRef.current;
-      if (!drag) {
-        // Escape-cancel leaves the click suppressor armed so the click this
-        // pointerup generates can't act on the clip; disarm it right after.
-        if (suppressClickRef.current) clearSuppressedClick();
-        return;
-      }
-      commitDragPointerUp(drag);
-    };
-
-    // Escape cancels the in-progress gesture: no commit, no undo entry. The
-    // previews live only in the drag/resize state (the store is untouched
-    // until the pointerup commit), so clearing them restores the pre-drag
-    // timeline. Clip drags never take pointer capture (all tracking runs on
-    // these window listeners), so there is no capture to release; the null
-    // refs make the remaining pointermove/pointerup a no-op.
-    const handleWindowKeyDown = (e: KeyboardEvent) => {
-      const decision = resolveTimelineDragEscape({
-        key: e.key,
-        drag: draggedClipRef.current,
-        resize: resizingClipRef.current,
-        blocked: blockedClipRef.current,
-      });
-      if (!decision.cancel) return;
-      e.preventDefault();
-      e.stopPropagation();
-      stopClipDragAutoScrollRef.current();
-      draggedClipRef.current = null;
-      setDraggedClip(null);
-      resizingClipRef.current = null;
-      setResizingClip(null);
-      // Undo any group-resize preview store-mutation (non-grabbed members) so the
-      // cancelled gesture restores the pre-drag timeline, like the single-clip path.
-      const groupSession = groupResizeRef.current;
-      groupResizeRef.current = null;
-      if (groupSession) restoreGroupResizeMembers(groupSession);
-      blockedClipRef.current = null;
-      // The pointer is usually still down; keep the suppressor armed until the
-      // eventual pointerup (which disarms it) so its click can't reselect.
-      if (decision.suppressClick) suppressClickRef.current = true;
-    };
-
-    window.addEventListener("pointermove", handleWindowPointerMove);
-    window.addEventListener("pointerup", handleWindowPointerUp);
-    window.addEventListener("pointercancel", handleWindowPointerUp);
-    window.addEventListener("keydown", handleWindowKeyDown, true);
-    return () => {
-      stopClipDragAutoScrollRef.current();
-      window.removeEventListener("pointermove", handleWindowPointerMove);
-      window.removeEventListener("pointerup", handleWindowPointerUp);
-      window.removeEventListener("pointercancel", handleWindowPointerUp);
-      window.removeEventListener("keydown", handleWindowKeyDown, true);
-    };
+    return mountTimelineClipDragGestureLifecycle({
+      draggedClipRef,
+      resizingClipRef,
+      blockedClipRef,
+      groupResizeRef,
+      suppressClickRef,
+      elementsRef,
+      trackOrderRef,
+      setDraggedClip,
+      setResizingClip,
+      setShowPopover,
+      setRangeSelectionRef,
+      applyResizePointerRef,
+      syncClipDragAutoScrollRef,
+      stopClipDragAutoScrollRef,
+      updateDraggedClipPreviewRef,
+      restoreGroupResizeMembers,
+      updateElement,
+      onMoveElementRef,
+      onMoveElementsRef,
+      onResizeElementRef,
+      onResizeElementsRef,
+      onBlockedEditAttemptRef,
+      readZIndexRef,
+      onStackingPatchesRef,
+      refreshAfterLaneMoveRef,
+    });
   });
 
   return {

package/src/player/components/useTimelineClipRenderWindow.ts

@@ -0,0 +1,95 @@
+import { useMemo, type RefObject } from "react";
+import { createTimelineClipIndex } from "../lib/timelineClipIndex";
+import type { TimelineElement } from "../store/playerStore";
+import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
+import type { TimelineRowGeometry } from "./timelineLayout";
+import type { TimelineScrollViewportSnapshot } from "./useTimelineScrollViewport";
+import { useTimelineRevealClip } from "./useTimelineRevealClip";
+
+interface UseTimelineClipRenderWindowInput {
+  tracks: Parameters<typeof createTimelineClipIndex>[0];
+  viewport: TimelineScrollViewportSnapshot;
+  pixelsPerSecond: number;
+  contentOrigin: number;
+  duration: number;
+  selectedElementId?: string;
+  draggedElementId?: string;
+  resizingElementId?: string;
+  revealElementId?: string;
+  focusedEaseElementId?: string;
+  clipContextMenuElementId?: string;
+  keyframeContextMenuElementId?: string;
+  focusedElementId?: string;
+  scrollRef: RefObject<HTMLDivElement | null>;
+  elements: readonly TimelineElement[];
+  rowGeometry: TimelineRowGeometry;
+  allowHorizontalReveal: boolean;
+  rowVirtualizationActive: boolean;
+  sessionEpoch: number;
+}
+
+export function useTimelineClipRenderWindow({
+  tracks,
+  viewport,
+  pixelsPerSecond,
+  contentOrigin,
+  duration,
+  selectedElementId,
+  draggedElementId,
+  resizingElementId,
+  revealElementId,
+  focusedEaseElementId,
+  clipContextMenuElementId,
+  keyframeContextMenuElementId,
+  focusedElementId,
+  scrollRef,
+  elements,
+  rowGeometry,
+  allowHorizontalReveal,
+  rowVirtualizationActive,
+  sessionEpoch,
+}: UseTimelineClipRenderWindowInput) {
+  const clipIndex = useMemo(() => createTimelineClipIndex(tracks), [tracks]);
+  const renderTimeRange = useMemo(
+    () => getTimelineRenderTimeRange(viewport, pixelsPerSecond, contentOrigin, duration),
+    [contentOrigin, duration, pixelsPerSecond, viewport],
+  );
+  const pinnedClipIdentities = useMemo(
+    () =>
+      new Set(
+        [
+          selectedElementId,
+          draggedElementId,
+          resizingElementId,
+          revealElementId,
+          focusedEaseElementId,
+          clipContextMenuElementId,
+          keyframeContextMenuElementId,
+          focusedElementId,
+        ].filter((identity): identity is string => identity !== undefined),
+      ),
+    [
+      clipContextMenuElementId,
+      draggedElementId,
+      focusedEaseElementId,
+      focusedElementId,
+      keyframeContextMenuElementId,
+      resizingElementId,
+      revealElementId,
+      selectedElementId,
+    ],
+  );
+  useTimelineRevealClip({
+    scrollRef,
+    elements,
+    rowGeometry,
+    pixelsPerSecond,
+    contentOrigin,
+    allowHorizontal: allowHorizontalReveal,
+    deferFocusUntilViewportUpdate: rowVirtualizationActive,
+    focusedElementId,
+    viewportVersion: viewport,
+    sessionEpoch,
+  });
+  return { clipIndex, renderTimeRange, pinnedClipIdentities };
+}

package/src/player/components/useTimelineGeometry.ts

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useRef, type RefObject } from "react";
+import { useEffect, useRef, type RefObject } from "react";
 import { usePlayerStore, type TimelineElement, type ZoomMode } from "../store/playerStore";
 import { getTimelinePixelsPerSecond } from "./timelineZoom";
 import {
@@ -78,13 +78,6 @@ export function useTimelineGeometry({
     resizeGhostEndPx,
   });
   const displayDuration = pps > 0 ? displayContentWidth / pps : effectiveDuration;
-  const clipStateVersion = useMemo(
-    () =>
-      expandedElements
-        .map((el) => `${el.key ?? el.id}:${el.start}:${el.duration}:${el.track}`)
-        .join("|"),
-    [expandedElements],
-  );
   const zoomModeRef = useRef(zoomMode);
   zoomModeRef.current = zoomMode;
   const manualZoomPercentRef = useRef(manualZoomPercent);
@@ -92,7 +85,7 @@ export function useTimelineGeometry({
   fitPpsRef.current = fitPps;
 
   // Restore the horizontal scroll offset after an edit re-derives the elements
-  // (clipStateVersion changes) so the reload doesn't jump the view. Only in manual
+  // (the immutable element snapshot changes) so the reload doesn't jump the view. Only in manual
   // (pinned) mode — fit mode hides the x-scrollbar (scrollLeft is always 0) — and
   // never mid-drag (auto-scroll owns the offset then). rAF waits for the new layout
   // so the clamp reads the post-resync scrollWidth. zoomMode is a legitimate dep:
@@ -109,7 +102,7 @@ export function useTimelineGeometry({
     });
     return () => cancelAnimationFrame(raf);
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [clipStateVersion, zoomMode]);
+  }, [expandedElements, zoomMode]);
   // Publish the live scale so edit handlers OUTSIDE <Timeline> (the keyboard-delete
   // path) can pin the zoom via pinTimelineZoomToCurrent without threading geometry.
   // In a useEffect (not the render body) so React-18 concurrent replay — Suspense
@@ -125,7 +118,7 @@ export function useTimelineGeometry({
     fitPps,
     displayContentWidth,
     displayDuration,
-    clipStateVersion,
+    clipStateVersion: expandedElements,
     zoomModeRef,
     manualZoomPercentRef,
   };