@hyperframes/studio 0.8.47 → 0.8.49

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

@@ -5,6 +5,8 @@ import {
   canShiftTrackGapClips,
   commitCloseAllTrackGaps,
   commitCloseTrackGap,
+  resolveMainTrackDeleteRippleShifts,
+  resolveShiftedElements,
 } from "./timelineGapCommit";
 import { resolveAllTrackGaps } from "./timelineGaps";
 
@@ -150,6 +152,25 @@ describe("commitCloseAllTrackGaps", () => {
   });
 });
 
+describe("resolveShiftedElements", () => {
+  it("maps each shift to its element and new start", () => {
+    const elements = [el("a", 0, 2), el("c", 8, 1)];
+    const resolved = resolveShiftedElements(elements, [{ key: "c", newStart: 2 }]);
+    expect(resolved).toEqual([{ element: elements[1], start: 2 }]);
+  });
+
+  it("resolves by key when present, falling back to id", () => {
+    const withKey: TimelineElement = { ...el("a", 0, 2), key: "a-key" };
+    const resolved = resolveShiftedElements([withKey], [{ key: "a-key", newStart: 5 }]);
+    expect(resolved).toEqual([{ element: withKey, start: 5 }]);
+  });
+
+  it("drops a shift whose key matches no element", () => {
+    const elements = [el("a", 0, 2)];
+    expect(resolveShiftedElements(elements, [{ key: "ghost", newStart: 0 }])).toEqual([]);
+  });
+});
+
 describe("canShiftTrackGapClips", () => {
   it("is true only when every named clip is movable", () => {
     const lane = [el("a", 1, 2), lockedEl("b", 5, 3)];
@@ -161,3 +182,78 @@ describe("canShiftTrackGapClips", () => {
     expect(canShiftTrackGapClips([el("a", 0, 1)], [{ key: "ghost", newStart: 0 }])).toBe(false);
   });
 });
+
+describe("resolveMainTrackDeleteRippleShifts", () => {
+  it("closes the gap left by a deleted main-track clip", () => {
+    const deleted = [el("b", 2, 2)];
+    const survivors = [el("a", 0, 2), el("c", 8, 1)]; // "b" already removed from this set
+    // "c" shifts left by exactly "b"'s 2s duration (8 -> 6), not all the way
+    // to 2: the 4-6..8 span was already an open gap before the delete, and
+    // ripple must not also swallow it.
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deleted, true)).toEqual([
+      { key: "c", newStart: 6 },
+    ]);
+  });
+
+  it("does not also close a pre-existing gap the delete never touched", () => {
+    // a(0-2), b(2-4)[deleted], GAP(4-6), c(6-7): deleting b should slide c
+    // left by b's 2s only, landing at 4 — flush against a, the pre-existing
+    // gap collapsed only because it's now adjacent, not doubly-counted.
+    const deleted = [el("b", 2, 2)];
+    const survivors = [el("a", 0, 2), el("c", 6, 1)];
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deleted, true)).toEqual([
+      { key: "c", newStart: 4 },
+    ]);
+  });
+
+  it("leaves an untouched clip before the delete point exactly where it was", () => {
+    // a(0-2), GAP(2-5), b(5-7)[deleted]: nothing follows b, so nothing
+    // shifts — a keeps its own leading position, ripple included.
+    const deleted = [el("b", 5, 2)];
+    const survivors = [el("a", 0, 2)];
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deleted, true)).toBeNull();
+  });
+
+  it("returns null when ripple is off", () => {
+    const deleted = [el("b", 2, 2)];
+    const survivors = [el("a", 0, 2), el("c", 8, 1)];
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deleted, false)).toBeNull();
+  });
+
+  it("returns null when nothing deleted was on the main track", () => {
+    const deletedOverlay = [el("o", 2, 2, 1)]; // track 1, not main
+    const survivors = [el("a", 0, 2), el("c", 8, 1)];
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deletedOverlay, true)).toBeNull();
+  });
+
+  it("returns null when the survivors are already gapless", () => {
+    const deleted = [el("b", 100, 1)]; // deleted from far off the end
+    const survivors = [el("a", 0, 2), el("c", 2, 1)]; // already contiguous
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deleted, true)).toBeNull();
+  });
+
+  it("refuses the whole ripple (not a partial one) when a shifting survivor is locked", () => {
+    const deleted = [el("b", 2, 2)];
+    const survivors = [el("a", 0, 2), lockedEl("c", 8, 1)];
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deleted, true)).toBeNull();
+  });
+
+  it("ignores audio and non-main-track survivors even when a main-track clip was deleted", () => {
+    const deleted = [el("b", 2, 2)];
+    const survivors = [el("a", 0, 2), el("c", 8, 1), el("overlay", 3, 1, 1)];
+    const shifts = resolveMainTrackDeleteRippleShifts(survivors, deleted, true);
+    expect(shifts).toEqual([{ key: "c", newStart: 6 }]); // "overlay" (track 1) untouched
+  });
+
+  it("sums only the deleted spans that precede each survivor, for a multi-select delete", () => {
+    // a(0-2), b(2-4)[deleted], c(4-6), d(6-8)[deleted], e(8-9): a marquee
+    // delete of b and d in one batch. "c" sits before d, so it shifts by
+    // b's 2s alone; "e" sits after both, so it shifts by their 4s combined.
+    const deleted = [el("b", 2, 2), el("d", 6, 2)];
+    const survivors = [el("a", 0, 2), el("c", 4, 2), el("e", 8, 1)];
+    expect(resolveMainTrackDeleteRippleShifts(survivors, deleted, true)).toEqual([
+      { key: "c", newStart: 2 },
+      { key: "e", newStart: 4 },
+    ]);
+  });
+});

package/src/player/components/timelineGapCommit.ts

@@ -10,8 +10,11 @@ import {
   resolveAllTrackGaps,
   resolveCloseGapShifts,
   resolveTrackGapAt,
+  round3,
+  TRACK_GAP_EPSILON_S,
   type TrackGapShift,
 } from "./timelineGaps";
+import { isMainTrackElement } from "./timelineZones";
 
 /**
  * Commit layer for the track-gap context menu ("Close gap" / "Close all gaps").
@@ -35,16 +38,29 @@ const keyOf = (e: TimelineElement) => e.key ?? e.id;
 // timelineClipDragCommit.ts.
 let gapCloseGestureSeq = 0;
 
-/** True when every clip named in `shifts` may be time-moved. */
+/** Resolve each shift to its named element, dropping any shift whose key
+ *  matches nothing — the type stays honest without a non-null assertion. */
+export function resolveShiftedElements(
+  elements: readonly TimelineElement[],
+  shifts: readonly TrackGapShift[],
+): Array<{ element: TimelineElement; start: number }> {
+  const byKey = new Map(elements.map((e) => [keyOf(e), e]));
+  return shifts.flatMap((s) => {
+    const element = byKey.get(s.key);
+    return element ? [{ element, start: s.newStart }] : [];
+  });
+}
+
+/** True when every shift names a real clip that may be time-moved. */
 export function canShiftTrackGapClips(
   laneElements: readonly TimelineElement[],
   shifts: readonly TrackGapShift[],
 ): boolean {
-  const byKey = new Map(laneElements.map((e) => [keyOf(e), e]));
-  return shifts.every((s) => {
-    const element = byKey.get(s.key);
-    return element != null && getTimelineEditCapabilities(element).canMove;
-  });
+  const resolved = resolveShiftedElements(laneElements, shifts);
+  return (
+    resolved.length === shifts.length &&
+    resolved.every((r) => getTimelineEditCapabilities(r.element).canMove)
+  );
 }
 
 function buildShiftEdits(
@@ -52,11 +68,10 @@ function buildShiftEdits(
   shifts: readonly TrackGapShift[],
 ): TimelineMoveEdit[] | null {
   if (shifts.length === 0 || !canShiftTrackGapClips(laneElements, shifts)) return null;
-  const byKey = new Map(laneElements.map((e) => [keyOf(e), e]));
-  return shifts.map((s) => {
-    const element = byKey.get(s.key)!;
-    return { element, updates: { start: s.newStart, track: element.track } };
-  });
+  return resolveShiftedElements(laneElements, shifts).map(({ element, start }) => ({
+    element,
+    updates: { start, track: element.track },
+  }));
 }
 
 function commitShifts(
@@ -101,3 +116,33 @@ export function commitCloseAllTrackGaps(
     deps,
   );
 }
+
+/** What a ripple-edit delete must additionally shift on the main track. Pure
+ *  — no IO; the caller persists the shifts itself. Null means nothing to
+ *  ripple: off, nothing deleted was on the main track, already gapless, or a
+ *  shifting clip is locked (same whole-action refusal as the gap-close menu). */
+export function resolveMainTrackDeleteRippleShifts(
+  survivingElements: readonly TimelineElement[],
+  deletedElements: readonly TimelineElement[],
+  rippleEnabled: boolean,
+): TrackGapShift[] | null {
+  const deletedMainTrack = deletedElements.filter(isMainTrackElement);
+  if (!rippleEnabled || deletedMainTrack.length === 0) return null;
+  const survivors = survivingElements.filter(isMainTrackElement);
+  // Shift each survivor left by the duration of the deleted clips before it —
+  // the removed span itself, not a gap re-resolved on the survivors, which
+  // can't tell an untouched adjacent gap from the one just opened.
+  const shifts: TrackGapShift[] = [];
+  for (const survivor of survivors) {
+    const width = deletedMainTrack
+      .filter((d) => d.start < survivor.start)
+      .reduce((sum, d) => sum + d.duration, 0);
+    if (width <= 0) continue;
+    const newStart = round3(Math.max(laneGapFloor(survivors), survivor.start - width));
+    if (Math.abs(newStart - survivor.start) > TRACK_GAP_EPSILON_S) {
+      shifts.push({ key: keyOf(survivor), newStart });
+    }
+  }
+  if (shifts.length === 0 || !canShiftTrackGapClips(survivors, shifts)) return null;
+  return shifts;
+}

package/src/player/components/timelineGaps.ts

@@ -13,7 +13,7 @@ import type { TimelineElement } from "../store/playerStore";
  * - Computed starts are rounded to millisecond precision, matching the drag
  *   commit's `round3`.
  */
-const TRACK_GAP_EPSILON_S = 1e-3;
+export const TRACK_GAP_EPSILON_S = 1e-3;
 
 const keyOf = (e: TimelineElement) => e.key ?? e.id;
 
@@ -28,7 +28,7 @@ const keyOf = (e: TimelineElement) => e.key ?? e.id;
 export function laneGapFloor(elements: readonly TimelineElement[]): number {
   return Math.max(0, ...elements.map((e) => e.expandedParentStart ?? 0));
 }
-const round3 = (v: number) => Math.round(v * 1000) / 1000;
+export const round3 = (v: number) => Math.round(v * 1000) / 1000;
 const endOf = (e: TimelineElement) => e.start + e.duration;
 
 /** Lane clips sorted by start (key as a deterministic tie-break). */

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

@@ -217,7 +217,6 @@ describe("track-area breathing pad y-math", () => {
       scrollTop: 0,
       contentOrigin: GUTTER,
       pixelsPerSecond: 100,
-      duration: 60,
       rowHeights: baseRows(3),
       trackOrder: [0, 1, 2],
     };

package/src/player/components/timelineLayout.ts

@@ -568,8 +568,6 @@ export function resolveTimelineAssetDrop(
     scrollTop: number;
     contentOrigin: number;
     pixelsPerSecond: number;
-    duration: number;
-    clampStartToDuration?: boolean;
     rowHeights?: readonly number[];
     trackOrder: number[];
   },
@@ -584,10 +582,7 @@ export function resolveTimelineAssetDrop(
   });
   const contentY = clientY - input.rectTop + input.scrollTop;
   const pointerStart = Math.round((x / Math.max(input.pixelsPerSecond, 1)) * 100) / 100;
-  const start = Math.max(
-    0,
-    input.clampStartToDuration === false ? pointerStart : Math.min(input.duration, pointerStart),
-  );
+  const start = Math.max(0, pointerStart);
   // Row from the shared row→y inverse so the top pad is honoured; a drop in the
   // pad above the first lane floors to row 0, a drop in the bottom pad rounds
   // past the last lane (getDefaultDroppedTrack then appends a new track).

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import type { TimelineElement } from "../store/playerStore";
-import { classifyZone, normalizeToZones } from "./timelineZones";
+import { classifyZone, isMainTrackElement, normalizeToZones } from "./timelineZones";
 
 function el(id: string, tag: string, track: number, duration = 2): TimelineElement {
   return { id, tag, start: 0, duration, track };
@@ -55,6 +55,25 @@ describe("classifyZone", () => {
   });
 });
 
+describe("isMainTrackElement", () => {
+  it("is true for a visual clip on display track 0", () => {
+    expect(isMainTrackElement(el("v", "video", 0))).toBe(true);
+  });
+
+  it("is false for a visual clip on any other track", () => {
+    expect(isMainTrackElement(el("v", "video", 1))).toBe(false);
+  });
+
+  it("is false for an audio clip even on track 0 (audio-only project has no main track)", () => {
+    expect(isMainTrackElement(el("m", "audio", 0))).toBe(false);
+  });
+
+  it("is false for an inline-expanded sub-composition child on track 0", () => {
+    const child: TimelineElement = { ...el("c", "video", 0), expandedParentStart: 4 };
+    expect(isMainTrackElement(child)).toBe(false);
+  });
+});
+
 describe("normalizeToZones — CapCut-stable lanes follow the track-index (never z)", () => {
   it("orders visual lanes by authored track-index (ascending), audio at the bottom", () => {
     // img (track 0), vid (track 2), mus (audio, track 5). Lanes follow the track

package/src/player/components/timelineZones.ts

@@ -2,9 +2,9 @@ import type { TimelineElement } from "../store/playerStore";
 import { isAudioTimelineElement } from "../../utils/timelineInspector";
 
 /**
- * Free-form vertical zones, top → bottom: visual, audio. There is no "main track"
- * — canvas layering is CSS z-index (the renderer ignores track index), so the
- * timeline's only job is to keep visual clips grouped above audio clips.
+ * Free-form vertical zones, top → bottom: visual, audio. Canvas layering is
+ * CSS z-index (the renderer ignores track index), so a track's only structural
+ * job is to keep visual clips grouped above audio clips.
  */
 export type TrackZone = "visual" | "audio";
 
@@ -14,6 +14,13 @@ export function classifyZone(el: TimelineElement): TrackZone {
   return isAudioTimelineElement(el) ? "audio" : "visual";
 }
 
+/** The "main track" is a convention, not a schema field: the first
+ *  visual-zone display lane, matched only when it actually holds a visual
+ *  clip and isn't an inline-expanded sub-composition child. */
+export function isMainTrackElement(el: TimelineElement): boolean {
+  return el.track === 0 && classifyZone(el) === "visual" && el.expandedParentStart == null;
+}
+
 const keyOf = (el: TimelineElement) => el.key ?? el.id;
 
 const EPS = 1e-6;

package/src/player/components/useAutomationLaneGestures.ts

@@ -13,7 +13,7 @@
 
 import { useCallback, useRef, useState, type PointerEvent as ReactPointerEvent } from "react";
 import type { AutomationRange, HfAutomationLane } from "@hyperframes/core/audio-automation";
-import { curveForDrag, formatValue, GRAB_PX, POINT_MERGE_SEC } from "./automationLaneGeometry";
+import { curveForDrag, formatValue, GRAB_PX, mergeInsertPoint } from "./automationLaneGeometry";
 import { pointInSelection } from "./automationLaneSelection";
 import { capturePointer } from "./automationLanePointer";
 import { useAutomationEdgeStretch } from "./useAutomationEdgeStretch";
@@ -548,15 +548,7 @@ export function useAutomationLaneGestures({
         return;
       }
       const { t, v } = pointAt(e.clientX, e.clientY);
-      const kept = lane.points.filter((p) => Math.abs(p.t - t) > POINT_MERGE_SEC);
-      // A lane's first point alone would be a constant, which is not what
-      // clicking an empty lane means: seed the far end at the same value so the
-      // envelope has somewhere to go.
-      const seeded = lane.points.length === 0 && t > POINT_MERGE_SEC ? [{ t: 0, v }] : [];
-      commitPoints(
-        [...seeded, ...kept, { t, v }].sort((a, b) => a.t - b.t),
-        true,
-      );
+      commitPoints(mergeInsertPoint(lane.points, t, v), true);
     },
     [lane, pointAt, commitPoints, readOnly, hitIndex, segmentIndex],
   );

package/src/player/components/useTimelineFocusCoordinator.test.tsx

@@ -35,12 +35,16 @@ function Harness({
   mountedId,
   logicalRows = rows,
   projectId = "project-a",
+  lastScrollLeftRef: sharedLastScrollLeftRef,
 }: {
   mountedId?: string;
   logicalRows?: readonly TimelineLogicalRow[];
   projectId?: string;
+  lastScrollLeftRef?: React.RefObject<number>;
 }) {
   const scrollRef = useRef<HTMLDivElement>(null);
+  const ownLastScrollLeftRef = useRef(0);
+  const lastScrollLeftRef = sharedLastScrollLeftRef ?? ownLastScrollLeftRef;
   const rowGeometry = useMemo(() => {
     const rowKeys = [...new Set(logicalRows.map((row) => row.physicalTrackKey))];
     return createTimelineRowGeometry(
@@ -60,6 +64,7 @@ function Harness({
     projectId,
     sessionEpoch: 1,
     syncScrollViewport,
+    lastScrollLeftRef,
   });
   return (
     <div
@@ -171,4 +176,65 @@ describe("useTimelineFocusCoordinator", () => {
     expect(usePlayerStore.getState().timelineFocus?.id).toBe(nextRowId);
     expect(document.activeElement?.getAttribute("data-timeline-focus-id")).toBe(nextRowId);
   });
+
+  it("keeps a request alive across a few renders where its target hasn't landed yet", async () => {
+    // A request issued the same tick as its own element's creation (a fresh
+    // drop) can race logicalRows by a render or two; it must not be dropped
+    // before the element actually appears.
+    usePlayerStore.getState().requestTimelineFocus(clipId);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const notYetRows: readonly TimelineLogicalRow[] = [{ ...rows[0]!, items: [] }];
+      await act(async () => root.render(<Harness logicalRows={notYetRows} />));
+    }
+    expect(usePlayerStore.getState().timelineFocus?.id).toBe(clipId);
+
+    await act(async () => root.render(<Harness logicalRows={rows} mountedId={clipId} />));
+    expect(usePlayerStore.getState().timelineFocus?.id).toBe(clipId);
+    expect(document.activeElement?.getAttribute("data-timeline-focus-id")).toBe(clipId);
+  });
+
+  it("gives up once a target never lands after its retry budget", async () => {
+    usePlayerStore.getState().requestTimelineFocus(clipId);
+    for (let attempt = 0; attempt < 6; attempt++) {
+      // A fresh array reference each render, like a real re-render caused by
+      // unrelated state, or the memoized resolution never recomputes at all.
+      const neverRows: readonly TimelineLogicalRow[] = [{ ...rows[0]!, items: [] }];
+      await act(async () => root.render(<Harness logicalRows={neverRows} />));
+    }
+    expect(usePlayerStore.getState().timelineFocus).toBeNull();
+  });
+
+  it("clears an unresolved request on a timeout even if nothing else ever re-renders", async () => {
+    // The render-count retry budget can't advance without a rerun; if the
+    // target never lands and nothing else re-renders, only a wall-time
+    // backstop clears it — otherwise it sits forever, eligible to resolve
+    // against an unrelated element that later reuses its id.
+    vi.useFakeTimers();
+    try {
+      usePlayerStore.getState().requestTimelineFocus(clipId);
+      const neverRows: readonly TimelineLogicalRow[] = [{ ...rows[0]!, items: [] }];
+      await act(async () => root.render(<Harness logicalRows={neverRows} />));
+      expect(usePlayerStore.getState().timelineFocus?.id).toBe(clipId);
+
+      await act(async () => {
+        vi.advanceTimersByTime(4001);
+      });
+
+      expect(usePlayerStore.getState().timelineFocus).toBeNull();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("keeps lastScrollLeftRef in sync with a reveal so a sibling restore effect doesn't undo it", async () => {
+    // Timeline.tsx's own "restore scroll after an edit re-derives the elements"
+    // effect reads this ref to decide what to scroll back to. A reveal that
+    // doesn't update it looks, to that effect, like scroll drift to undo.
+    const lastScrollLeftRef = { current: 999 };
+    usePlayerStore.getState().requestTimelineFocus(clipId);
+    await act(async () => root.render(<Harness lastScrollLeftRef={lastScrollLeftRef} />));
+    const scroll = host.firstElementChild as HTMLDivElement;
+
+    expect(lastScrollLeftRef.current).toBe(scroll.scrollLeft);
+  });
 });

package/src/player/components/useTimelineFocusCoordinator.ts

@@ -11,6 +11,7 @@ import {
   type TimelineLogicalTarget,
 } from "./timelineKeyboardNavigation";
 import { computeRevealScroll } from "./timelineRevealScroll";
+import { recordRetryAttempt, type RetryBudgetState } from "../../utils/retryBudget";
 
 interface TimelineFocusCoordinatorInput {
   scrollRef: RefObject<HTMLDivElement | null>;
@@ -24,6 +25,7 @@ interface TimelineFocusCoordinatorInput {
   projectId: string | null;
   sessionEpoch: number;
   syncScrollViewport: (element: HTMLDivElement) => void;
+  lastScrollLeftRef: RefObject<number>;
 }
 
 export interface TimelineFocusCoordinatorState {
@@ -77,6 +79,7 @@ function scrollToTarget(
   pixelsPerSecond: number,
   contentOrigin: number,
   allowHorizontal: boolean,
+  lastScrollLeftRef: RefObject<number>,
 ): boolean {
   const rowIndex = rowGeometry.getRowIndex(resolution.row.physicalTrackKey);
   if (rowIndex < 0) return false;
@@ -103,11 +106,26 @@ function scrollToTarget(
     stickyTop: RULER_H,
     allowHorizontal: allowHorizontal && left !== null,
   });
-  if (target.left !== null) container.scrollLeft = target.left;
+  if (target.left !== null) {
+    container.scrollLeft = target.left;
+    // Keep the geometry effect's "restore scroll after an edit re-derives the
+    // elements" in sync, or it reads the pre-reveal position on the next tick
+    // and scrolls the freshly-revealed clip back out of view.
+    lastScrollLeftRef.current = target.left;
+  }
   if (target.top !== null) container.scrollTop = target.top;
   return target.left !== null || target.top !== null;
 }
 
+// A request racing a fresh element's own creation (drop/paste) resolves within
+// a render or two; past this many misses on the same nonce it truly never will.
+const MAX_UNRESOLVED_FOCUS_RETRIES = 5;
+
+// Backstop for a request whose target never appears and nothing else ever
+// re-renders: the retry budget above can't advance without a rerun, so this
+// bounds it by wall time instead, independent of re-renders.
+const UNRESOLVED_FOCUS_TIMEOUT_MS = 4000;
+
 /** Model-first focus actor; mounting is a consequence of its returned pins. */
 // Resolution, fallback, reveal, and focus form one ordered state machine.
 // fallow-ignore-next-line complexity
@@ -123,11 +141,13 @@ export function useTimelineFocusCoordinator({
   projectId,
   sessionEpoch,
   syncScrollViewport,
+  lastScrollLeftRef,
 }: TimelineFocusCoordinatorInput): TimelineFocusCoordinatorState {
   const request = usePlayerStore((state) => state.timelineFocus);
   const previousRowsRef = useRef(logicalRows);
   const resolvedRef = useRef<{ nonce: number; id: string } | null>(null);
   const appliedRef = useRef<{ nonce: number; id: string } | null>(null);
+  const unresolvedFocusAttemptsRef = useRef<RetryBudgetState<number>>({ id: -1, count: 0 });
   const resolution = useMemo<ResolvedFocus | null>(() => {
     if (isCurrentRequest(request, projectId, sessionEpoch)) {
       if (resolvedRef.current?.nonce !== request.nonce) {
@@ -163,8 +183,26 @@ export function useTimelineFocusCoordinator({
   useEffect(() => {
     if (!isCurrentRequest(request, projectId, sessionEpoch)) return;
     if (!resolution) {
-      usePlayerStore.getState().clearTimelineFocus(request.nonce);
-      return;
+      // A request issued the same tick as its element (a fresh drop/paste) can
+      // outrun logicalRows by a render or two; only give up once it clearly
+      // never resolves, so the reveal isn't lost to that ordinary race.
+      const withinBudget = recordRetryAttempt(
+        unresolvedFocusAttemptsRef,
+        request.nonce,
+        MAX_UNRESOLVED_FOCUS_RETRIES,
+      );
+      if (!withinBudget) {
+        usePlayerStore.getState().clearTimelineFocus(request.nonce);
+        return;
+      }
+      const nonce = request.nonce;
+      const timeout = setTimeout(() => {
+        usePlayerStore.getState().clearTimelineFocus(nonce);
+      }, UNRESOLVED_FOCUS_TIMEOUT_MS);
+      return () => clearTimeout(timeout);
+    }
+    if (unresolvedFocusAttemptsRef.current.count !== 0) {
+      unresolvedFocusAttemptsRef.current = { id: -1, count: 0 };
     }
     if (resolution.target.id !== request.id) {
       usePlayerStore.getState().requestTimelineFocus(resolution.target.id);
@@ -187,6 +225,7 @@ export function useTimelineFocusCoordinator({
         pixelsPerSecond,
         contentOrigin,
         allowHorizontal,
+        lastScrollLeftRef,
       )
     ) {
       syncScrollViewport(container);
@@ -197,6 +236,7 @@ export function useTimelineFocusCoordinator({
     allowHorizontal,
     contentOrigin,
     elements,
+    lastScrollLeftRef,
     pixelsPerSecond,
     projectId,
     request,

package/src/player/components/useTimelineGeometry.test.tsx

@@ -0,0 +1,117 @@
+// @vitest-environment happy-dom
+
+import React, { act, useRef } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { useTimelineGeometry } from "./useTimelineGeometry";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const element: TimelineElement = { id: "hero", tag: "div", start: 20, duration: 2, track: 1 };
+
+const nextFrame = () => new Promise<number>((resolve) => requestAnimationFrame(resolve));
+
+function Harness({
+  expandedElements,
+  lastScrollLeftRef,
+  scrollWidth = 20_000,
+}: {
+  expandedElements: TimelineElement[];
+  lastScrollLeftRef: React.RefObject<number>;
+  scrollWidth?: number;
+}) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const isDragging = useRef(false);
+  const ppsRef = useRef(0);
+  const fitPpsRef = useRef(0);
+  useTimelineGeometry({
+    viewportWidth: 1600,
+    effectiveDuration: 60,
+    zoomMode: "manual",
+    manualZoomPercent: 100,
+    ppsRef,
+    fitPpsRef,
+    draggedClip: null,
+    resizingClip: null,
+    expandedElements,
+    isDragging,
+    scrollRef,
+    lastScrollLeftRef,
+    contentOrigin: 32,
+  });
+  return (
+    <div
+      ref={(node) => {
+        scrollRef.current = node;
+        if (node) {
+          Object.defineProperty(node, "clientWidth", { configurable: true, value: 1600 });
+          Object.defineProperty(node, "scrollWidth", { configurable: true, value: scrollWidth });
+        }
+      }}
+    />
+  );
+}
+
+let host: HTMLDivElement;
+let root: Root;
+beforeEach(() => {
+  usePlayerStore.setState({ timelineProjectId: "project-a" });
+  host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+});
+afterEach(() => {
+  act(() => root.unmount());
+  usePlayerStore.getState().reset();
+  document.body.replaceChildren();
+});
+
+describe("useTimelineGeometry restore-scroll effect", () => {
+  it("reads lastScrollLeftRef at frame time, not effect time, so a same-commit reveal isn't undone", async () => {
+    // A sibling effect in the same commit (a fresh timeline-focus reveal) can
+    // update lastScrollLeftRef and the DOM scrollLeft together after this
+    // effect has already scheduled its frame. The frame must see that update,
+    // not the value that was current when it was scheduled.
+    const lastScrollLeftRef = { current: 132 };
+    act(() => {
+      root.render(<Harness expandedElements={[]} lastScrollLeftRef={lastScrollLeftRef} />);
+    });
+    const scroll = host.firstElementChild as HTMLDivElement;
+    scroll.scrollLeft = 132;
+
+    // Flush this effect (it schedules a frame, capturing whatever it reads
+    // right now) BEFORE the sibling mutates the ref, exactly as in a real
+    // commit where this effect registers and runs ahead of the reveal's.
+    act(() => {
+      root.render(<Harness expandedElements={[element]} lastScrollLeftRef={lastScrollLeftRef} />);
+    });
+    // Simulate the sibling reveal effect: it runs after this one in the same
+    // commit and updates both the DOM and the ref before the frame fires.
+    lastScrollLeftRef.current = 450;
+    scroll.scrollLeft = 450;
+    await act(async () => {
+      await nextFrame();
+    });
+
+    expect(scroll.scrollLeft).toBe(450);
+  });
+
+  it("still restores the pre-edit position when nothing else changed the ref mid-frame", async () => {
+    const lastScrollLeftRef = { current: 300 };
+    act(() => {
+      root.render(<Harness expandedElements={[]} lastScrollLeftRef={lastScrollLeftRef} />);
+    });
+    const scroll = host.firstElementChild as HTMLDivElement;
+    scroll.scrollLeft = 0;
+
+    act(() => {
+      root.render(<Harness expandedElements={[element]} lastScrollLeftRef={lastScrollLeftRef} />);
+    });
+    await act(async () => {
+      await nextFrame();
+    });
+
+    expect(scroll.scrollLeft).toBe(300);
+  });
+});