@hyperframes/studio 0.8.48 → 0.8.50

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

@@ -5,6 +5,7 @@ import {
   isInsertAllowedForZone,
   isLaneFree,
   resolveInsertRow,
+  resolveMainTrackDropStart,
   resolvePlacement,
   resolveZoneDropPlacement,
   timeRangesOverlap,
@@ -493,3 +494,25 @@ describe("resolveZoneDropPlacement (the whole drop decision, no same-track overl
     expect(result).toEqual({ track: 0, insertRow: 1 });
   });
 });
+
+describe("resolveMainTrackDropStart (magnetic first clip on an empty main track)", () => {
+  it("snaps to 0 when landing on an empty main track", () => {
+    expect(resolveMainTrackDropStart([], 1, 0, false, 7)).toBe(0);
+  });
+
+  it("leaves the drop start alone once the main track already holds another clip", () => {
+    expect(resolveMainTrackDropStart([el("other", 0, 0, 3)], 1, 0, false, 7)).toBe(7);
+  });
+
+  it("leaves the drop start alone when landing off the main track", () => {
+    expect(resolveMainTrackDropStart([], 1, 2, false, 7)).toBe(7);
+  });
+
+  it("a clip already resident on the main track doing a horizontal move is a no-op", () => {
+    expect(resolveMainTrackDropStart([], 0, 0, false, 7)).toBe(7);
+  });
+
+  it("an audio clip landing on track 0 is not the main track (visual zone only)", () => {
+    expect(resolveMainTrackDropStart([], 1, 0, true, 7)).toBe(7);
+  });
+});

package/src/player/components/timelineCollision.ts

@@ -1,5 +1,6 @@
 import type { TimelineElement } from "../store/playerStore";
 import { INSERT_BOUNDARY_BAND } from "./timelineLayout";
+import { isMainTrackElement } from "./timelineZones";
 
 /**
  * Keep a landing track inside the dragged clip's kind-zone: visual clips stay in
@@ -140,6 +141,32 @@ export function resolveZoneDropPlacement(input: {
   return { track: placement.track, insertRow: null };
 }
 
+function landsOnMainTrack(landingTrack: number, isAudio: boolean): boolean {
+  return isMainTrackElement({
+    id: "",
+    tag: isAudio ? "audio" : "video",
+    start: 0,
+    duration: 0,
+    track: landingTrack,
+  });
+}
+
+/** An existing clip newly landing on an empty main track commits at start=0.
+ *  No-op once the main track holds another clip, off the main track, or for
+ *  a clip already resident there. `others` excludes the landing clip itself. */
+export function resolveMainTrackDropStart(
+  others: readonly TimelineElement[],
+  originTrack: number,
+  landingTrack: number,
+  isAudio: boolean,
+  desiredStart: number,
+): number {
+  if (originTrack === landingTrack || !landsOnMainTrack(landingTrack, isAudio)) {
+    return desiredStart;
+  }
+  return others.some(isMainTrackElement) ? desiredStart : 0;
+}
+
 /**
  * Decide whether a vertical drag is inserting a new track at a lane boundary.
  * `rowFloat` is the pointer's position in track-height units from the top of the

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

@@ -220,4 +220,35 @@ describe("useTimelineAssetDrop", () => {
     expect(view.api.isDragOver).toBe(false);
     act(() => view.root.unmount());
   });
+
+  it("previews the exact placement the drop commits, and clears it after", () => {
+    const onAssetDrop = vi.fn();
+    const view = renderHarness(onAssetDrop);
+    const payload = JSON.stringify({ path: "assets/a.png" });
+
+    act(() => view.api.handleAssetDragOver(dragEvent(assetTransfer(payload), 400, 100)));
+    const preview = view.api.dropPreview;
+    expect(preview).toEqual({ start: 10, track: 0 });
+
+    act(() => view.api.handleAssetDrop(dragEvent(assetTransfer(payload), 400, 100)));
+    expect(onAssetDrop).toHaveBeenCalledExactlyOnceWith("assets/a.png", preview);
+    expect(view.api.dropPreview).toBeNull();
+    act(() => view.root.unmount());
+  });
+
+  it("moves the preview with the pointer and drops it when the drag leaves", () => {
+    const view = renderHarness(vi.fn());
+    act(() => view.api.handleAssetDragOver(dragEvent(assetTransfer("{}"), 400, 100)));
+    act(() => view.api.handleAssetDragOver(dragEvent(assetTransfer("{}"), 800, 100)));
+    expect(view.api.dropPreview?.start).toBe(20);
+
+    act(() =>
+      view.api.handleAssetDragLeave({
+        relatedTarget: null,
+        currentTarget: document.body,
+      } as unknown as React.DragEvent),
+    );
+    expect(view.api.dropPreview).toBeNull();
+    act(() => view.root.unmount());
+  });
 });

package/src/player/components/timelineDragDrop.ts

@@ -98,6 +98,7 @@ export function useTimelineAssetDrop({
   sessionEpoch,
 }: UseTimelineAssetDropOptions) {
   const [isDragOver, setIsDragOver] = useState(false);
+  const [dropPreview, setDropPreview] = useState<TimelinePlacement | null>(null);
   const dragPointerRef = useRef<{ clientX: number; clientY: number; sessionEpoch: number } | null>(
     null,
   );
@@ -142,6 +143,28 @@ export function useTimelineAssetDrop({
     [scrollRef, sessionEpoch, stepAutoScroll],
   );
 
+  const resolveDropPlacement = useCallback(
+    (clientX: number, clientY: number): TimelinePlacement => {
+      const scroll = scrollRef.current;
+      const rect = scroll?.getBoundingClientRect();
+      return resolveTimelineAssetDrop(
+        {
+          rectLeft: rect?.left ?? 0,
+          rectTop: rect?.top ?? 0,
+          scrollLeft: scroll?.scrollLeft ?? 0,
+          scrollTop: scroll?.scrollTop ?? 0,
+          contentOrigin,
+          pixelsPerSecond: ppsRef.current,
+          rowHeights: rowGeometryRef.current.rowHeights,
+          trackOrder: trackOrderRef.current,
+        },
+        clientX,
+        clientY,
+      );
+    },
+    [scrollRef, ppsRef, trackOrderRef, rowGeometryRef, contentOrigin],
+  );
+
   const handleAssetDragOver = useCallback(
     (e: React.DragEvent) => {
       const types = Array.from(e.dataTransfer.types);
@@ -154,15 +177,20 @@ export function useTimelineAssetDrop({
       e.dataTransfer.dropEffect = "copy";
       activeDropEpochRef.current = sessionEpoch;
       setIsDragOver(true);
+      const next = resolveDropPlacement(e.clientX, e.clientY);
+      setDropPreview((prev) =>
+        prev?.start === next.start && prev.track === next.track ? prev : next,
+      );
       syncAutoScroll(e.clientX, e.clientY);
     },
-    [sessionEpoch, syncAutoScroll],
+    [resolveDropPlacement, sessionEpoch, syncAutoScroll],
   );
 
   const clearDropPreview = useCallback(() => {
     activeDropEpochRef.current = null;
     stopAutoScroll();
     setIsDragOver(false);
+    setDropPreview(null);
   }, [stopAutoScroll]);
 
   const handleAssetDragLeave = useCallback(
@@ -174,28 +202,6 @@ export function useTimelineAssetDrop({
     [clearDropPreview],
   );
 
-  const resolveDropPlacement = useCallback(
-    (clientX: number, clientY: number): TimelinePlacement => {
-      const scroll = scrollRef.current;
-      const rect = scroll?.getBoundingClientRect();
-      return resolveTimelineAssetDrop(
-        {
-          rectLeft: rect?.left ?? 0,
-          rectTop: rect?.top ?? 0,
-          scrollLeft: scroll?.scrollLeft ?? 0,
-          scrollTop: scroll?.scrollTop ?? 0,
-          contentOrigin,
-          pixelsPerSecond: ppsRef.current,
-          rowHeights: rowGeometryRef.current.rowHeights,
-          trackOrder: trackOrderRef.current,
-        },
-        clientX,
-        clientY,
-      );
-    },
-    [scrollRef, ppsRef, trackOrderRef, rowGeometryRef, contentOrigin],
-  );
-
   const handleAssetDrop = useCallback(
     (e: React.DragEvent) => {
       e.preventDefault();
@@ -240,6 +246,7 @@ export function useTimelineAssetDrop({
 
   return {
     isDragOver,
+    dropPreview,
     handleAssetDragOver,
     handleAssetDragLeave,
     handleAssetDrop,

package/src/player/components/timelineDragLanding.ts

@@ -0,0 +1,108 @@
+import type { TimelineElement } from "../store/playerStore";
+import type { DragCommitDeps } from "./timelineClipDragCommit";
+import type { DraggedClipState } from "./timelineClipDragTypes";
+import { classifyZone, normalizeToZones } from "./timelineZones";
+import { resolveMainTrackDropStart } from "./timelineCollision";
+import { isAudioTimelineElement } from "../../utils/timelineInspector";
+import { resolveExpandedHostAlias } from "./timelineAuthoredMoveTarget";
+import { sameSourceFile } from "./timelineAuthoredTrack";
+import { round3 } from "./timelineGaps";
+
+const keyOf = (e: TimelineElement) => e.key ?? e.id;
+
+/** A fractional track for a new lane at boundary `insertRow` (0 = above the top);
+ *  normalizeToZones compacts it to an integer lane and shifts the clips below. */
+function insertTrackValue(trackOrder: number[], insertRow: number): number {
+  if (trackOrder.length === 0) return 0;
+  if (insertRow <= 0) return trackOrder[0] - 0.5;
+  if (insertRow >= trackOrder.length) return trackOrder[trackOrder.length - 1] + 0.5;
+  return (trackOrder[insertRow - 1] + trackOrder[insertRow]) / 2;
+}
+
+/** The source-file lane layout after inserting `element` at boundary `insertRow`:
+ *  the whole-set renumber both the commit and the drag preview read. */
+export function layoutAfterTrackInsert(
+  element: TimelineElement,
+  previewStart: number,
+  insertRow: number,
+  multi: {
+    keys: ReadonlySet<string>;
+    movedStart: (e: TimelineElement) => number;
+  } | null,
+  deps: Pick<DragCommitDeps, "elements" | "trackOrder">,
+): {
+  normalized: TimelineElement[];
+  targetTrack: number;
+  writable: (src: TimelineElement) => boolean;
+} | null {
+  const { elements, trackOrder } = deps;
+  const editKey = keyOf(element);
+  // Expanded-child rows are synthetic host lanes, not source-file topology.
+  if (element.expandedParentStart != null) return null;
+  const targetTrack = insertTrackValue(trackOrder, insertRow);
+  // Foreign display rows and the opposite zone must not affect this topology.
+  const writableZone = classifyZone(element);
+  const writable = (src: TimelineElement): boolean =>
+    sameSourceFile(src, element) &&
+    classifyZone(src) === writableZone &&
+    src.expandedParentStart == null;
+  const topologyOrder = [...new Set(elements.filter(writable).map((e) => e.track))].sort(
+    (a, b) => a - b,
+  );
+  const topologyInsertRow = topologyOrder.filter((track) => track < targetTrack).length;
+  const topologyTargetTrack = insertTrackValue(topologyOrder, topologyInsertRow);
+  const normalized = normalizeToZones(
+    elements.filter(writable).map((e) => {
+      if (keyOf(e) === editKey) {
+        return { ...e, start: previewStart, track: topologyTargetTrack };
+      }
+      if (multi?.keys.has(keyOf(e))) return { ...e, start: multi.movedStart(e) };
+      return e;
+    }),
+  );
+  return { normalized, targetTrack, writable };
+}
+
+/** The start a solo clip lands at, for both the ghost and the commit: 0 on an empty
+ *  main track, judged on the final lane (after the renumber and the host alias).
+ *  Returned in the dragged clip's own frame. */
+export function resolveDragLandingStart(
+  drag: DraggedClipState,
+  deps: Pick<DragCommitDeps, "elements" | "trackOrder" | "selectedKeys">,
+): number {
+  const alias = resolveExpandedHostAlias(drag, deps);
+  const target = alias?.drag ?? drag;
+  const keys = alias?.selectedKeys ?? deps.selectedKeys;
+  const element = target.element;
+  const key = keyOf(element);
+  if (keys && keys.size > 1 && keys.has(key)) return drag.previewStart;
+
+  let landingTrack = target.previewTrack;
+  let renumbered = new Map<string, number>();
+  if (target.insertRow != null) {
+    const layout = layoutAfterTrackInsert(
+      element,
+      target.previewStart,
+      target.insertRow,
+      null,
+      deps,
+    );
+    if (layout) {
+      renumbered = new Map(layout.normalized.map((n) => [keyOf(n), n.track]));
+      landingTrack = renumbered.get(key) ?? layout.targetTrack;
+    }
+  }
+  const others = deps.elements
+    .filter((e) => keyOf(e) !== key)
+    .map((e) => (renumbered.has(keyOf(e)) ? { ...e, track: renumbered.get(keyOf(e))! } : e));
+  const snapped = resolveMainTrackDropStart(
+    others,
+    element.track,
+    landingTrack,
+    isAudioTimelineElement(element),
+    target.previewStart,
+  );
+  return snapped === target.previewStart
+    ? drag.previewStart
+    : round3(drag.previewStart + snapped - target.previewStart);
+}

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

@@ -0,0 +1,34 @@
+// @vitest-environment happy-dom
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { usePlayerStore } from "../store/playerStore";
+import { timelineClipFocusId } from "./timelineNavigationIdentity";
+import { selectAndRevealTimelineElement } from "./timelineDropReveal";
+
+beforeEach(() => {
+  usePlayerStore.getState().reset();
+});
+
+describe("selectAndRevealTimelineElement", () => {
+  it("selects the element and requests a scroll-to-focus on the same key", () => {
+    selectAndRevealTimelineElement("index.html#clip-1");
+
+    expect(usePlayerStore.getState().selectedElementId).toBe("index.html#clip-1");
+    expect(usePlayerStore.getState().timelineFocus?.id).toBe(
+      timelineClipFocusId("index.html#clip-1"),
+    );
+  });
+
+  it("moves the focus request to the new element when called again", () => {
+    selectAndRevealTimelineElement("index.html#clip-1");
+    const firstNonce = usePlayerStore.getState().timelineFocus?.nonce;
+
+    selectAndRevealTimelineElement("index.html#clip-2");
+
+    expect(usePlayerStore.getState().selectedElementId).toBe("index.html#clip-2");
+    expect(usePlayerStore.getState().timelineFocus?.id).toBe(
+      timelineClipFocusId("index.html#clip-2"),
+    );
+    expect(usePlayerStore.getState().timelineFocus?.nonce).not.toBe(firstNonce);
+  });
+});

package/src/player/components/timelineDropReveal.ts

@@ -0,0 +1,12 @@
+import { usePlayerStore } from "../store/playerStore";
+import { timelineClipFocusId } from "./timelineNavigationIdentity";
+
+/**
+ * Select a newly-created clip and scroll the timeline to it, the same pair of
+ * calls AssetCard/AudioRow use to reveal an existing clip on activation.
+ */
+export function selectAndRevealTimelineElement(key: string): void {
+  const store = usePlayerStore.getState();
+  store.setSelectedElementId(key);
+  store.requestTimelineFocus(timelineClipFocusId(key));
+}

package/src/player/components/timelineEditCapabilities.ts

@@ -42,10 +42,9 @@ export function getTimelineEditCapabilities(input: {
   playbackStart?: number;
   playbackStartAttr?: "media-start" | "playback-start";
   sourceDuration?: number;
-  timingSource?: "authored" | "implicit";
   timelineLocked?: boolean;
 }): TimelineEditCapabilities {
-  if (input.timingSource === "implicit" || input.timelineLocked) {
+  if (input.timelineLocked) {
     return { canMove: false, canTrimStart: false, canTrimEnd: false };
   }
 

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

@@ -412,21 +412,6 @@ describe("getTimelineEditCapabilities", () => {
     });
   });
 
-  it("keeps implicit layout layers selectable but not timeline-editable", () => {
-    expect(
-      getTimelineEditCapabilities({
-        duration: 8,
-        selector: ".scene-shell",
-        tag: "div",
-        timingSource: "implicit",
-      }),
-    ).toEqual({
-      canMove: false,
-      canTrimStart: false,
-      canTrimEnd: false,
-    });
-  });
-
   it("allows move and both trims for patchable media clips with offset support", () => {
     expect(
       getTimelineEditCapabilities({
@@ -496,7 +481,6 @@ describe("getTimelineEditCapabilities", () => {
         tag: "div",
         duration: 4,
         selector: "#hero-card",
-        timingSource: "authored",
       }),
     ).toEqual({
       canMove: true,

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

@@ -34,11 +34,9 @@ describe("buildTimelineGroupResizeMembers (legacy 36413da7f semantics)", () => {
     expect(buildTimelineGroupResizeMembers([a, locked], keys("a", "b"), "a", "end")).toBeNull();
   });
 
-  it("degrades when a member is implicitly timed or has no patch target", () => {
+  it("degrades when a member has no patch target", () => {
     const a = el("a");
-    const implicit = el("b", { timingSource: "implicit" });
     const noTarget = el("c", { domId: undefined, selector: undefined });
-    expect(buildTimelineGroupResizeMembers([a, implicit], keys("a", "b"), "a", "end")).toBeNull();
     expect(buildTimelineGroupResizeMembers([a, noTarget], keys("a", "c"), "a", "end")).toBeNull();
   });
 

package/src/player/components/timelineGroupEditing.ts

@@ -198,7 +198,6 @@ function canTrimEdge(element: TimelineElement, edge: TimelineGroupResizeEdge): b
     playbackStart: element.playbackStart,
     playbackStartAttr: element.playbackStartAttr,
     sourceDuration: element.sourceDuration,
-    timingSource: element.timingSource,
     timelineLocked: element.timelineLocked,
   });
   return edge === "start" ? caps.canTrimStart : caps.canTrimEnd;

package/src/player/components/timelineTrackDisplay.ts

@@ -3,7 +3,7 @@
  *
  * `TimelineElement.track` is a z-order SORT key, not a row number: an expanded
  * sub-composition child gets a synthesized fractional key (`host.track + n /
- * (siblings + 2)`, see `useExpandedTimelineElements`), so putting it in a string
+ * (siblings + 2)`, see `useTimelineRowElements`), so putting it in a string
  * announces "Hide track 0.16666666666666666". Every user-visible track number,
  * whether it is rendered by a component or baked into an undo-history label,
  * routes through here; the raw key stays in callbacks and lookups only.

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

@@ -2,7 +2,6 @@ import { describe, expect, it, vi } from "vitest";
 import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "../lib/playbackTypes";
 import { createTimelineElementFromManifestClip } from "../lib/timelineDOM";
-import { buildExpandedElements } from "../hooks/useExpandedTimelineElements";
 import { normalizeToZones } from "./timelineZones";
 import { commitDraggedClipMove, type TimelineMoveEdit } from "./timelineClipDragCommit";
 import type { DraggedClipState } from "./useTimelineClipDrag";
@@ -113,56 +112,4 @@ describe("track persist pipeline (manifest → factory → lanes → drag commit
     const up = commitLaneChange(byId.get("g")!, 0, elements, [0, 1, 2]);
     expect(up[0].updates.track).toBe(3); // authored, NOT display lane 0
   });
-
-  it("an expanded sub-comp child's lane change persists the sibling's authored track from ITS file", () => {
-    // Host timeline: the sub-comp host plus a root clip, discovered through the
-    // factory and lane-normalized like the store does.
-    const hostManifest = [
-      manifestClip({
-        id: "scene",
-        kind: "composition",
-        tagName: "div",
-        track: 0,
-        start: 0,
-        duration: 10,
-        compositionId: "scene",
-        compositionSrc: "scene.html",
-      }),
-      manifestClip({ id: "root-clip", kind: "video", tagName: "video", track: 1, start: 0 }),
-    ];
-    // scene.html has SPARSE authored tracks 3 and 7.
-    const childClips = [
-      manifestClip({ id: "c3", track: 3, start: 1, duration: 2, parentCompositionId: "scene" }),
-      manifestClip({ id: "c7", track: 7, start: 4, duration: 2, parentCompositionId: "scene" }),
-    ];
-    const storeElements = normalizeToZones(fromManifest(hostManifest));
-    const parentMap = new Map([
-      ["c3", "scene"],
-      ["c7", "scene"],
-    ]);
-    const expanded = buildExpandedElements(
-      storeElements,
-      [...hostManifest, ...childClips],
-      parentMap,
-      "scene",
-      "scene",
-    );
-
-    // The children replaced the host row: synthetic display lanes, but the
-    // authored track (in scene.html's coordinate space) survived the expansion.
-    const c3 = expanded.find((e) => e.domId === "c3")!;
-    const c7 = expanded.find((e) => e.domId === "c7")!;
-    expect(c3).toMatchObject({ authoredTrack: 3, sourceFile: "scene.html" });
-    expect(c7).toMatchObject({ authoredTrack: 7, sourceFile: "scene.html" });
-    expect(c3.stackingContextId).toBe("root");
-    expect(c3.track).not.toBe(3); // display row is synthetic
-
-    // Drag c3 onto c7's display lane: the persist target is c3's OWN file, so
-    // the written track must be c7's authored 7 — not the display-lane integer.
-    const trackOrder = [...new Set(expanded.map((e) => e.track))].sort((a, b) => a - b);
-    const edits = commitLaneChange(c3, c7.track, expanded, trackOrder);
-    expect(edits).toHaveLength(1);
-    expect(edits[0].updates.track).toBe(7);
-    expect(edits[0].updates.track).not.toBe(c7.track);
-  });
 });

package/src/player/components/useTimelineClipContextMenu.ts

@@ -0,0 +1,32 @@
+import { useCallback } from "react";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import type { ClipContextMenuState } from "./TimelineOverlays";
+
+/** A clicked member of an active multi-selection keeps the whole group
+ *  selected, so the context menu it opens acts on all of it. */
+export function useClipContextMenu(
+  onSelectElement: ((element: TimelineElement | null) => void) | undefined,
+  dismissGapMenu: () => void,
+  setClipContextMenu: (state: ClipContextMenuState | null) => void,
+) {
+  const selectedElementIds = usePlayerStore((s) => s.selectedElementIds);
+  const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
+  return useCallback(
+    (e: React.MouseEvent, el: TimelineElement) => {
+      e.preventDefault();
+      const id = el.key ?? el.id;
+      if (!(selectedElementIds.size > 1 && selectedElementIds.has(id))) {
+        setSelectedElementId(id);
+        onSelectElement?.(el);
+      }
+      dismissGapMenu();
+      setClipContextMenu({
+        x: e.clientX,
+        y: e.clientY,
+        element: el,
+        sessionEpoch: usePlayerStore.getState().timelineSessionEpoch,
+      });
+    },
+    [selectedElementIds, setSelectedElementId, onSelectElement, dismissGapMenu, setClipContextMenu],
+  );
+}

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);
+  });
 });