@hyperframes/studio 0.8.47 → 0.8.49

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

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import type { TimelineElement } from "../store/playerStore";
 import {
   computeDragPreview,
@@ -7,6 +7,7 @@ import {
   type DragPreviewContext,
 } from "./timelineClipDragPreview";
 import type { DraggedClipState } from "./timelineClipDragTypes";
+import { commitDraggedClipMove } from "./timelineClipDragCommit";
 import { LANE_H, RULER_H, TRACKS_TOP_PAD, TRACK_H } from "./timelineLayout";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -198,6 +199,72 @@ describe("computeDragPreview — plain horizontal drag never arms a phantom inse
   });
 });
 
+describe("computeDragPreview — magnetic first clip on an empty main track", () => {
+  // v-lower sits alone on lane 1; lane 0 (the main track) is empty.
+  const vLower = clip("v-lower", 1, 10, 4, 5);
+
+  // Grab v-lower mid-body on lane 1, aim at `targetRowFloat` (same x — no
+  // horizontal move), against the given sibling elements and selection.
+  function dragUpToMainTrack(
+    elements: TimelineElement[],
+    targetRowFloat = 0.5,
+    selectedKeys: ReadonlySet<string> = new Set(),
+  ) {
+    const originClientY = yForRow(1.5);
+    const drag: DraggedClipState = {
+      pointerId: 0,
+      element: vLower,
+      originClientX: 800,
+      originClientY,
+      originScrollLeft: 0,
+      originScrollTop: 0,
+      pointerClientX: 800,
+      pointerClientY: originClientY,
+      pointerOffsetX: 0,
+      pointerOffsetY: 0,
+      previewStart: vLower.start,
+      previewTrack: vLower.track,
+      insertRow: null,
+      snapTime: null,
+      snapType: null,
+      started: true,
+    };
+    return computeDragPreview(drag, 800, yForRow(targetRowFloat), {
+      ...ctx(undefined, elements),
+      trackOrder: [0, 1],
+      selectedKeys,
+    });
+  }
+
+  it("dragging straight up onto the empty main track snaps the preview start to 0", () => {
+    const next = dragUpToMainTrack([vLower]);
+    expect(next.previewTrack).toBe(0);
+    expect(next.insertRow).toBeNull();
+    expect(next.previewStart).toBe(0);
+  });
+
+  it("does not touch the start once the main track already holds a clip", () => {
+    const vMain = clip("v-main", 0, 0, 3, 5);
+    const next = dragUpToMainTrack([vLower, vMain]);
+    expect(next.previewStart).toBe(10); // unchanged — main track wasn't empty
+  });
+
+  it("aiming the top gutter over an empty main track snaps the ghost: the insert renumbers onto track 0", () => {
+    const next = dragUpToMainTrack([vLower], -0.6);
+    expect(next.insertRow).toBe(0);
+    expect(next.previewStart).toBe(0);
+  });
+
+  it("does not retime the rest of a multi-selection when the grabbed clip lands on the empty main track", () => {
+    const vOther = clip("v-other", 1, 15, 3, 5);
+    const next = dragUpToMainTrack([vLower, vOther], 0.5, new Set(["v-lower", "v-other"]));
+    expect(next.previewTrack).toBe(0);
+    // The grabbed clip's OWN vertical-only move must not force a horizontal
+    // shift that resolveMultiSelection would then apply to v-other.
+    expect(next.previewStart).toBe(10);
+  });
+});
+
 describe("computeResizePreview — composition source continuity", () => {
   it("seeds a legacy composition offset and advances it at playback rate", () => {
     const element = {
@@ -254,3 +321,108 @@ describe("getTimelineDragOverlayPosition", () => {
     expect(getTimelineDragOverlayPosition(drag, null)).toBeNull();
   });
 });
+
+describe("computeDragPreview — the ghost start is the committed start", () => {
+  function preview(
+    element: TimelineElement,
+    elements: TimelineElement[],
+    originRow: number,
+    targetRowFloat: number,
+    selectedKeys: ReadonlySet<string> = new Set(),
+  ): DraggedClipState {
+    const originClientY = yForRow(originRow + 0.5);
+    const drag: DraggedClipState = {
+      pointerId: 0,
+      element,
+      originClientX: 800,
+      originClientY,
+      originScrollLeft: 0,
+      originScrollTop: 0,
+      pointerClientX: 800,
+      pointerClientY: originClientY,
+      pointerOffsetX: 0,
+      pointerOffsetY: 0,
+      previewStart: element.start,
+      previewTrack: element.track,
+      insertRow: null,
+      snapTime: null,
+      snapType: null,
+      started: true,
+    };
+    return computeDragPreview(drag, 800, yForRow(targetRowFloat), {
+      ...ctx(undefined, elements),
+      trackOrder: [0, 1, 2],
+      selectedKeys,
+    });
+  }
+
+  function committedStart(
+    ghost: DraggedClipState,
+    committed: TimelineElement,
+    elements: TimelineElement[],
+    selectedKeys: ReadonlySet<string> = new Set(),
+  ): number | undefined {
+    const onMoveElement = vi.fn();
+    const onMoveElements = vi.fn();
+    commitDraggedClipMove(ghost, {
+      elements,
+      trackOrder: [0, 1, 2],
+      updateElement: vi.fn(),
+      onMoveElement,
+      onMoveElements,
+      selectedKeys,
+    });
+    const edits = onMoveElements.mock.calls[0]?.[0] as
+      | Array<{ element: TimelineElement; updates: { start: number } }>
+      | undefined;
+    const single = onMoveElement.mock.calls[0];
+    if (single) return single[1].start;
+    return edits?.find((e) => e.element.id === committed.id)?.updates.start;
+  }
+
+  const lower = clip("lower", 1, 10, 4, 5);
+
+  it("plain move onto the empty main track", () => {
+    const ghost = preview(lower, [lower], 1, 0.5);
+    expect(ghost.previewStart).toBe(0);
+    expect(committedStart(ghost, lower, [lower])).toBe(ghost.previewStart);
+  });
+
+  it("top-gutter insert that pushes the old track-0 clip down lands on track 0 at 0", () => {
+    const oldMain = clip("old-main", 0, 0, 3, 5);
+    const elements = [oldMain, lower];
+    const ghost = preview(lower, elements, 1, -0.6);
+    expect(ghost.insertRow).toBe(0);
+    expect(ghost.previewStart).toBe(0);
+    expect(committedStart(ghost, lower, elements)).toBe(0);
+  });
+
+  it("top-gutter insert with a clip staying on track 0 keeps the pointer start", () => {
+    const stays = clip("stays", 0, 0, 3, 5);
+    const elements = [stays, lower];
+    // Insert between lane 0 and 1: the resident track-0 clip does not move.
+    const ghost = preview(lower, elements, 1, 1.0);
+    expect(ghost.previewStart).toBe(10);
+    expect(committedStart(ghost, lower, elements)).toBe(10);
+  });
+
+  it("expanded child dragged with its host: the host commits at 0 and the ghost matches", () => {
+    for (const [hostStart, childStart] of [
+      [30, 32],
+      [20, 22],
+    ]) {
+      const host = clip("host", 1, hostStart, 10, 5);
+      const child: TimelineElement = {
+        ...clip("child", 2, childStart, 4, 5),
+        expandedHostKey: "host",
+        expandedParentStart: hostStart,
+      };
+      const elements = [host, child];
+      const keys = new Set(["host", "child"]);
+      const ghost = preview(child, elements, 2, 0.5, keys);
+      expect(ghost.previewTrack).toBe(0);
+      expect(ghost.previewStart).toBe(childStart - hostStart);
+      expect(committedStart(ghost, host, elements, keys)).toBe(0);
+    }
+  });
+});

package/src/player/components/timelineClipDragPreview.ts

@@ -20,6 +20,7 @@ import {
 } from "./timelineGroupEditing";
 import { clampGroupMoveDelta } from "./timelineMultiDragPreview";
 import type { DraggedClipState, ResizingClipState } from "./timelineClipDragTypes";
+import { resolveDragLandingStart } from "./timelineDragLanding";
 
 /** Snap-target builder closure supplied by the hook (closes over refs + store). */
 type BuildSnapTargets = (
@@ -200,12 +201,18 @@ export function computeDragPreview(
     nextMove.track,
     ctx,
   );
+  const placed = { ...drag, previewStart, previewTrack, insertRow };
+  const snappedStart = resolveDragLandingStart(placed, {
+    elements,
+    trackOrder,
+    selectedKeys,
+  });
   return {
     ...drag,
     started: true,
     pointerClientX: clientX,
     pointerClientY: clientY,
-    previewStart,
+    previewStart: snappedStart,
     previewTrack,
     // The lane the POINTER aims at (pre-collision): the commit reads it to tell a
     // deliberate vertical lane change from a horizontal drag merely bumped sideways.

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

@@ -56,7 +56,6 @@ function renderHarness(
     api = useTimelineAssetDrop({
       scrollRef: { current: scroll },
       ppsRef: { current: 40 },
-      durationRef: { current: 120 },
       trackOrderRef: { current: tracks },
       rowGeometryRef: { current: geometry },
       contentOrigin: 0,
@@ -138,7 +137,6 @@ describe("useTimelineAssetDrop", () => {
   it("drops once on a model row outside the mounted window and appends below the last row", () => {
     const onAssetDrop = vi.fn();
     const view = renderHarness(onAssetDrop);
-    usePlayerStore.getState().setCurrentTime(12.5);
     view.scroll.scrollTop = view.scroll.scrollHeight - view.scroll.clientHeight;
     const transfer = assetTransfer(JSON.stringify({ path: "/media/hero.mp4" }));
 
@@ -148,11 +146,29 @@ describe("useTimelineAssetDrop", () => {
     });
 
     expect(onAssetDrop).toHaveBeenCalledTimes(1);
-    expect(onAssetDrop).toHaveBeenCalledWith("/media/hero.mp4", { start: 12.5, track: 100 });
+    // pps=40, clientX=400 -> 10s at the pointer, not the playhead.
+    expect(onAssetDrop).toHaveBeenCalledWith("/media/hero.mp4", { start: 10, track: 100 });
     expect(view.api.isDragOver).toBe(false);
     act(() => view.root.unmount());
   });
 
+  it("places the drop at the pointer x, ignoring the playhead", () => {
+    const onAssetDrop = vi.fn();
+    const view = renderHarness(onAssetDrop);
+    usePlayerStore.getState().setCurrentTime(50);
+    const transfer = assetTransfer(JSON.stringify({ path: "/media/hero.mp4" }));
+
+    act(() => {
+      view.api.handleAssetDragOver(dragEvent(transfer, 80, 100));
+      view.api.handleAssetDrop(dragEvent(transfer, 80, 100));
+    });
+
+    // pps=40, clientX=80 -> 2s, far from the 50s playhead: proves start tracks
+    // the drop position, not usePlayerStore.currentTime.
+    expect(onAssetDrop).toHaveBeenCalledWith("/media/hero.mp4", { start: 2, track: 0 });
+    act(() => view.root.unmount());
+  });
+
   it("ignores malformed payloads and clears the actor on project reset", () => {
     const onAssetDrop = vi.fn();
     const view = renderHarness(onAssetDrop, 1);
@@ -190,7 +206,8 @@ describe("useTimelineAssetDrop", () => {
     });
 
     expect(onAssetDrop).not.toHaveBeenCalled();
-    expect(onBlockDrop).toHaveBeenCalledExactlyOnceWith("title-card", { start: 0, track: 0 });
+    // pps=40, clientX=400 -> 10s at the pointer.
+    expect(onBlockDrop).toHaveBeenCalledExactlyOnceWith("title-card", { start: 10, track: 0 });
     act(() => view.root.unmount());
   });
 

package/src/player/components/timelineDragDrop.ts

@@ -4,7 +4,6 @@ import {
   parseTimelineCompositionPayload,
   TIMELINE_COMPOSITION_MIME,
 } from "../../utils/timelineCompositionDrop";
-import { usePlayerStore } from "../store/playerStore";
 import { resolveTimelineAssetDrop, type TimelineRowGeometry } from "./timelineLayout";
 import type { TimelineDropCallbacks } from "./timelineCallbacks";
 import {
@@ -15,7 +14,6 @@ import {
 interface UseTimelineAssetDropOptions extends TimelineDropCallbacks {
   scrollRef: RefObject<HTMLDivElement | null>;
   ppsRef: RefObject<number>;
-  durationRef: RefObject<number>;
   trackOrderRef: RefObject<number[]>;
   rowGeometryRef: RefObject<TimelineRowGeometry>;
   contentOrigin: number;
@@ -53,11 +51,6 @@ function invokeDropCallback(callback: () => Promise<void> | void): void {
   }
 }
 
-function resolveDropStart(usePointerStart: boolean, pointerStart: number): number {
-  if (usePointerStart) return pointerStart;
-  return Math.max(0, usePlayerStore.getState().currentTime);
-}
-
 function applyFileDrop(
   transfer: DataTransfer,
   onFileDrop: TimelineDropCallbacks["onFileDrop"],
@@ -87,17 +80,14 @@ function applyTypedJsonDrop(
 }
 
 /**
- * Dropping an asset/file/block onto the timeline places it at the PLAYHEAD —
- * start is the current playhead time, only the track comes from the drop y.
- * Deliberate product choice (user preference, 2026-07-09): every add lands at
- * the playhead regardless of drop x, like CapCut's add-to-timeline. External
- * OS file drops and internal asset drops share this same placement path, so
- * both land identically.
+ * Dropping an asset/file/block/composition onto the timeline places it at the
+ * exact time and track it was dropped on, like CapCut (pointer placement on
+ * every track but the magnetic main track). Supersedes the prior playhead
+ * decision (#2291); playhead adds stay available, see useAddAssetAtPlayhead.
  */
 export function useTimelineAssetDrop({
   scrollRef,
   ppsRef,
-  durationRef,
   trackOrderRef,
   rowGeometryRef,
   contentOrigin,
@@ -185,10 +175,10 @@ export function useTimelineAssetDrop({
   );
 
   const resolveDropPlacement = useCallback(
-    (clientX: number, clientY: number, usePointerStart = false): TimelinePlacement => {
+    (clientX: number, clientY: number): TimelinePlacement => {
       const scroll = scrollRef.current;
       const rect = scroll?.getBoundingClientRect();
-      const pointer = resolveTimelineAssetDrop(
+      return resolveTimelineAssetDrop(
         {
           rectLeft: rect?.left ?? 0,
           rectTop: rect?.top ?? 0,
@@ -196,20 +186,14 @@ export function useTimelineAssetDrop({
           scrollTop: scroll?.scrollTop ?? 0,
           contentOrigin,
           pixelsPerSecond: ppsRef.current,
-          duration: durationRef.current,
-          clampStartToDuration: !usePointerStart,
           rowHeights: rowGeometryRef.current.rowHeights,
           trackOrder: trackOrderRef.current,
         },
         clientX,
         clientY,
       );
-      return {
-        start: resolveDropStart(usePointerStart, pointer.start),
-        track: pointer.track,
-      };
     },
-    [scrollRef, ppsRef, durationRef, trackOrderRef, rowGeometryRef, contentOrigin],
+    [scrollRef, ppsRef, trackOrderRef, rowGeometryRef, contentOrigin],
   );
 
   const handleAssetDrop = useCallback(
@@ -218,15 +202,15 @@ export function useTimelineAssetDrop({
       const canCommit = activeDropEpochRef.current === sessionEpoch;
       clearDropPreview();
       if (!canCommit) return;
+      const placement = resolveDropPlacement(e.clientX, e.clientY);
+
       const compositionPayload = parseTimelineCompositionPayload(
         e.dataTransfer.getData(TIMELINE_COMPOSITION_MIME),
       );
       if (compositionPayload && onCompositionDrop) {
-        const placement = resolveDropPlacement(e.clientX, e.clientY, true);
         invokeDropCallback(() => onCompositionDrop(compositionPayload.sourcePath, placement));
         return;
       }
-      const placement = resolveDropPlacement(e.clientX, e.clientY);
 
       if (applyFileDrop(e.dataTransfer, onFileDrop, placement)) return;
       if (applyTypedJsonDrop(e.dataTransfer, TIMELINE_ASSET_MIME, "path", onAssetDrop, placement)) {

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