@hyperframes/studio 0.8.48 → 0.8.50

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

@@ -2,7 +2,7 @@
 
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { defaultTimelineTheme } from "./timelineTheme";
 import { TimelineGestureOverlay } from "./TimelineGestureOverlay";
 import type { DraggedClipState } from "./timelineClipDragTypes";
@@ -65,6 +65,40 @@ describe("TimelineGestureOverlay", () => {
     act(() => root.unmount());
   });
 
+  it("asks for the same thumbnail frames as the clip at rest", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const renderClipContent = vi.fn(() => null);
+    act(() => {
+      root.render(
+        <TimelineGestureOverlay
+          drag={drag}
+          scrollRef={{
+            current: {
+              scrollLeft: 0,
+              scrollTop: 0,
+              getBoundingClientRect: () => ({ left: 0, top: 0 }),
+            } as HTMLDivElement,
+          }}
+          pixelsPerSecond={100}
+          rowHeight={42}
+          selectedElementId="hero"
+          currentTime={4}
+          theme={defaultTimelineTheme}
+          getTrackStyle={getTrackStyle}
+          renderClipContent={renderClipContent}
+        />,
+      );
+    });
+    expect(renderClipContent).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.anything(),
+      expect.objectContaining({ rich: false }),
+    );
+    act(() => root.unmount());
+  });
+
   it("keeps the stable overlay host after terminal cleanup", () => {
     const host = document.createElement("div");
     document.body.append(host);

package/src/player/components/TimelineGestureOverlay.tsx

@@ -89,7 +89,7 @@ export const TimelineGestureOverlay = memo(function TimelineGestureOverlay({
               getTrackStyle(element.tag),
               renderClipContent,
               renderClipOverlay,
-              { priority: "interaction", rich: true },
+              { priority: "interaction", rich: false },
             )}
           </TimelineClip>
         </div>

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

@@ -70,6 +70,8 @@ interface RenderLanesOptions {
   draggedClip?: DraggedClipState | null;
   onToggleTrackHidden?: TimelineEditCallbacks["onToggleTrackHidden"];
   onContextMenuLane?: (e: React.MouseEvent, track: number, time: number) => void;
+  hoveredClip?: string | null;
+  renderClipContent?: React.ComponentProps<typeof TimelineLanes>["renderClipContent"];
 }
 
 function renderLanes(options: RenderLanesOptions = {}): {
@@ -135,7 +137,8 @@ function renderLanes(options: RenderLanesOptions = {}): {
           laneCounts={laneCounts}
           selectedElementId={null}
           selectedElementIds={next.selectedElementIds ?? new Set()}
-          hoveredClip={null}
+          hoveredClip={next.hoveredClip ?? null}
+          renderClipContent={next.renderClipContent}
           draggedClip={next.draggedClip ?? null}
           draggedElement={null}
           multiDragPreview={next.multiDragPreview ?? null}
@@ -395,3 +398,21 @@ describe("TimelineLanes selection", () => {
     act(() => view.root.unmount());
   });
 });
+
+describe("TimelineLanes clip thumbnails", () => {
+  it("asks for the same frames at rest, hovered and selected", () => {
+    const rich: unknown[] = [];
+    const renderClipContent = vi.fn(
+      (_el: TimelineElement, _style: unknown, context: { rich: boolean }) => {
+        rich.push(context.rich);
+        return null;
+      },
+    );
+    const elements = [element("clip-a", TRACK_A)];
+    const view = renderLanes({ elements, renderClipContent });
+    view.rerender({ elements, renderClipContent, hoveredClip: "clip-a" });
+    view.rerender({ elements, renderClipContent, selectedElementIds: new Set(["clip-a"]) });
+    expect(new Set(rich)).toEqual(new Set([false]));
+    act(() => view.root.unmount());
+  });
+});

package/src/player/components/TimelineOverlays.tsx

@@ -52,6 +52,10 @@ interface TimelineOverlaysProps {
   onSplitElement: TimelineEditCallbacks["onSplitElement"];
   pinZoomBeforeEdit: () => void;
   onDeleteElement?: (element: TimelineElement) => Promise<void> | void;
+  onCopyClip?: () => boolean;
+  onPasteClip?: () => Promise<void>;
+  onDuplicateClip?: () => Promise<boolean>;
+  canPasteClip?: () => boolean;
   gapContextMenu: TrackGapContextMenuState | null;
   onDismissGapContextMenu: () => void;
   onCloseTrackGap: () => void;
@@ -119,6 +123,10 @@ export function TimelineOverlays({
   onSplitElement,
   pinZoomBeforeEdit,
   onDeleteElement,
+  onCopyClip,
+  onPasteClip,
+  onDuplicateClip,
+  canPasteClip,
   gapContextMenu,
   onDismissGapContextMenu,
   onCloseTrackGap,
@@ -249,6 +257,10 @@ export function TimelineOverlays({
             pinZoomBeforeEdit();
             onDeleteElement?.(element);
           }}
+          onCopy={onCopyClip}
+          onPaste={onPasteClip}
+          onDuplicate={onDuplicateClip}
+          canPaste={canPasteClip?.() ?? false}
         />
       )}
 

package/src/player/components/TimelineTypes.ts

@@ -22,5 +22,9 @@ export interface TimelineProps extends TimelineDropCallbacks, TimelineEditOverri
   renderClipOverlay?: (element: TimelineElement) => ReactNode;
   onDeleteElement?: (element: TimelineElement) => Promise<void> | void;
   onSelectElement?: (element: TimelineElement | null) => void;
+  onCopyClip?: () => boolean;
+  onPasteClip?: () => Promise<void>;
+  onDuplicateClip?: () => Promise<boolean>;
+  canPasteClip?: () => boolean;
   theme?: Partial<TimelineTheme>;
 }

package/src/player/components/timelineAuthoredMoveTarget.ts

@@ -3,7 +3,7 @@ import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
 import { getTimelineEditCapabilities } from "./timelineEditing";
 import type { DraggedClipState } from "./timelineClipDragTypes";
 
-/** Whether Studio may write timing to this clip (false for locked/implicit rows). */
+/** Whether Studio may write timing to this clip (false for locked rows). */
 export function canMoveTimelineElement(element: TimelineElement): boolean {
   return getTimelineEditCapabilities({
     tag: element.tag,
@@ -16,7 +16,6 @@ export function canMoveTimelineElement(element: TimelineElement): boolean {
     playbackStart: element.playbackStart,
     playbackStartAttr: element.playbackStartAttr,
     sourceDuration: element.sourceDuration,
-    timingSource: element.timingSource,
     timelineLocked: element.timelineLocked,
   }).canMove;
 }

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

@@ -11,10 +11,10 @@ const clip: TimelineElement = {
 };
 
 describe("resolveClipRenderContext", () => {
-  it("prioritizes interactive clips and enables rich thumbnails", () => {
+  it("prioritizes interactive clips without changing their thumbnail frames", () => {
     expect(resolveClipRenderContext(clip, { start: 0, end: 1 }, true)).toEqual({
       priority: "interaction",
-      rich: true,
+      rich: false,
     });
   });
 

package/src/player/components/timelineClipChildren.tsx

@@ -9,7 +9,8 @@ export function resolveClipRenderContext(
   visibleTimeRange: TimelineTimeRange,
   interactive: boolean,
 ): TimelineClipRenderContext {
-  if (interactive) return { priority: "interaction", rich: true };
+  // Interaction only reorders loading; `rich` would swap the frames under the pointer.
+  if (interactive) return { priority: "interaction", rich: false };
   const visible =
     element.start < visibleTimeRange.end &&
     element.start + element.duration > visibleTimeRange.start;

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

@@ -1223,6 +1223,120 @@ describe("commitDraggedClipMove", () => {
       expect(onStackingPatches).not.toHaveBeenCalled();
     });
   });
+
+  describe("magnetic main track on a track-insert", () => {
+    it("a top-gutter insert that renumbers to literal track 0 snaps its start to 0", () => {
+      // Sole visual clip sits on track 1 — the real main track (0) is genuinely
+      // empty. Dragging it into the top insert-gutter creates a new lane that
+      // normalizeToZones renumbers to literal 0, so the main-track rule must apply
+      // even though the preview never saw a literal-0 landing track.
+      const elements = [el("v1", 1, 0, 5)];
+      const { onMoveElements } = runClipMove(
+        drag(elements[0], { previewStart: 8, previewTrack: 1, insertRow: 0 }),
+        { elements, trackOrder: [1] },
+      );
+      const map = editMap(onMoveElements.mock.calls[0][0]);
+      expect(map.v1).toEqual({ start: 0, track: 0 });
+    });
+
+    it("the z-sync candidate reflects the snapped start, not the raw previewStart", async () => {
+      // v1 snaps from previewStart 8 to 0 (see the test above). A foreign-file
+      // sibling at [2, 5) only overlaps the SNAPPED window [0, 5), never the
+      // raw [8, 13) — so a z-sync firing at all proves the candidate the
+      // stacking check reads from carries the snapped start.
+      const v1 = el("v1", 2, 0, 5);
+      const sibling = el("s", 1, 2, 3); // [2, 5) — same source file, same paint scope
+      const elements = [v1, sibling];
+      const onStackingPatches = vi.fn();
+      // v1 lands on lane 0, which paints above lane 1 (lower track paints higher),
+      // yet carries the lower z: a violation only while the two overlap in time.
+      commitDraggedClipMove(drag(v1, { previewStart: 8, previewTrack: 2, insertRow: 0 }), {
+        elements,
+        trackOrder: [1, 2],
+        updateElement: vi.fn(),
+        onMoveElement: vi.fn(),
+        onMoveElements: vi.fn(),
+        readZIndex: (element) => (element.key === "v1" ? 1 : 10),
+        onStackingPatches,
+      });
+      await flushMicrotasks();
+      expect(onStackingPatches).toHaveBeenCalledTimes(1);
+    });
+
+    it("a plain lane change onto the empty main track snaps its committed start to 0", () => {
+      const elements = [el("v1", 1, 0, 5)];
+      const spies = runClipMove(drag(elements[0], { previewStart: 8, previewTrack: 0 }), {
+        elements,
+        trackOrder: [0, 1],
+      });
+      expect(expectAtomicMoveMap(spies).v1).toEqual({ start: 0, track: 0 });
+    });
+
+    it("the z-sync candidate of a plain lane change carries the snapped start", async () => {
+      // The sibling [2, 5) overlaps v1 only at the snapped [0, 5), never at the raw [8, 13).
+      const v1 = el("v1", 2, 0, 5);
+      const sibling = el("s", 1, 2, 3);
+      const onStackingPatches = vi.fn();
+      commitDraggedClipMove(drag(v1, { previewStart: 8, previewTrack: 0 }), {
+        elements: [v1, sibling],
+        trackOrder: [0, 1, 2],
+        updateElement: vi.fn(),
+        onMoveElement: vi.fn(),
+        onMoveElements: vi.fn(),
+        readZIndex: (element) => (element.key === "v1" ? 1 : 10),
+        onStackingPatches,
+      });
+      await flushMicrotasks();
+      expect(onStackingPatches).toHaveBeenCalledTimes(1);
+    });
+
+    it("a top-gutter insert that pushes the old track-0 clip down snaps to the new track 0", () => {
+      const oldMain = el("old", 0, 0, 3);
+      const dragged = el("v1", 2, 0, 5);
+      const { onMoveElements } = runClipMove(
+        drag(dragged, { previewStart: 8, previewTrack: 2, insertRow: 0 }),
+        { elements: [oldMain, dragged], trackOrder: [0, 2] },
+      );
+      const map = editMap(onMoveElements.mock.calls[0][0]);
+      expect(map.old.track).toBe(1);
+      expect(map.v1).toEqual({ start: 0, track: 0 });
+    });
+
+    it("an expanded child dragged with its host commits the HOST at 0", () => {
+      for (const [hostStart, childStart] of [
+        [30, 32],
+        [20, 22],
+      ]) {
+        const host = el("host", 1, hostStart, 10);
+        const child: TimelineElement = {
+          ...el("child", 2, childStart, 4),
+          expandedHostKey: "host",
+          expandedParentStart: hostStart,
+        };
+        const { onMoveElements } = runClipMove(
+          drag(child, { previewStart: childStart, previewTrack: 0 }),
+          {
+            elements: [host, child],
+            trackOrder: [0, 1, 2],
+            selectedKeys: new Set(["host", "child"]),
+          },
+        );
+        expect(editMap(onMoveElements.mock.calls[0][0]).host).toEqual({ start: 0, track: 0 });
+      }
+    });
+
+    it("a multi-selection top-gutter insert does NOT snap (siblings key off the unsnapped start)", () => {
+      const dragged = el("v1", 1, 0, 5);
+      const sibling = el("v2", 1, 10, 5);
+      const elements = [dragged, sibling];
+      const { onMoveElements } = runClipMove(
+        drag(dragged, { previewStart: 8, previewTrack: 1, insertRow: 0 }),
+        { elements, trackOrder: [1], selectedKeys: new Set(["v1", "v2"]) },
+      );
+      const map = editMap(onMoveElements.mock.calls[0][0]);
+      expect(map.v1.start).toBe(8); // unsnapped — multi-selection guard
+    });
+  });
 });
 
 describe("commitZMirrorLaneMove", () => {

package/src/player/components/timelineClipDragCommit.ts

@@ -3,7 +3,8 @@ import type { DraggedClipState } from "./useTimelineClipDrag";
 // Type-only: erased at runtime, so the timelineZMirror → timelineClipDragCommit
 // value-import edge stays acyclic.
 import type { ZMirrorLaneMove } from "./timelineZMirror";
-import { classifyZone, normalizeToZones } from "./timelineZones";
+import { classifyZone } from "./timelineZones";
+import { layoutAfterTrackInsert, resolveDragLandingStart } from "./timelineDragLanding";
 import { computeStackingPatches, type StackingPatch } from "./timelineStackingSync";
 import {
   canMoveTimelineElement as canMoveElement,
@@ -16,7 +17,7 @@ import {
 } from "./timelineOptimisticRevision";
 import { runLaneZGesture } from "../../components/nle/zLaneGesture";
 import { refreshAfterDurableLaneMove } from "./timelineLaneMoveRefresh";
-import { authoredTrackForLane, sameSourceFile } from "./timelineAuthoredTrack";
+import { authoredTrackForLane } from "./timelineAuthoredTrack";
 
 type StartTrack = Pick<TimelineElement, "start" | "track">;
 export interface TimelineMoveEdit {
@@ -172,24 +173,11 @@ export function persistMoveEdits(
   );
 }
 
-/**
- * A fractional track value for a NEW lane inserted at boundary `insertRow` in
- * `trackOrder` (0 = above the top, `length` = below the bottom). normalizeToZones
- * then compacts it to a distinct integer lane between its neighbours, and the
- * clips at/below the insert shift down by one — the sanctioned index-renumber.
- */
-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;
-}
-
 /**
  * Build the time-shift resolver for a multi-selection drag: every member of the
  * selection moves by the dragged clip's delta (clamped ≥ 0); non-members are
- * untouched. Returns null when this is not a multi-selection drag. A locked /
- * implicit member is dropped from the moving set (a marquee can sweep one in).
+ * untouched. Returns null when this is not a multi-selection drag. A locked
+ * member is dropped from the moving set (a marquee can sweep one in).
  */
 function resolveMultiSelection(
   drag: DraggedClipState,
@@ -231,7 +219,8 @@ function resolveMultiSelection(
  *   permitted multi-clip write) via a whole-set re-normalize; persisted atomically.
  */
 // fallow-ignore-next-line complexity
-export function commitDraggedClipMove(drag: DraggedClipState, deps: DragCommitDeps): void {
+export function commitDraggedClipMove(rawDrag: DraggedClipState, deps: DragCommitDeps): void {
+  const drag = { ...rawDrag, previewStart: resolveDragLandingStart(rawDrag, deps) };
   const hostAlias = resolveExpandedHostAlias(drag, deps);
   if (hostAlias) {
     commitDraggedClipMove(hostAlias.drag, { ...deps, selectedKeys: hostAlias.selectedKeys });
@@ -353,36 +342,11 @@ function buildTrackInsertEdits(
   } | null,
   deps: DragCommitDeps,
 ): { candidate: TimelineElement[]; edits: TimelineMoveEdit[] } | null {
-  const { elements, trackOrder } = deps;
+  const { elements } = 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);
-  const candidate = elements.map((e) => {
-    if (keyOf(e) === editKey) return { ...e, start: previewStart, track: targetTrack };
-    if (multi?.keys.has(keyOf(e))) return { ...e, start: multi.movedStart(e) };
-    return e;
-  });
-  // 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;
-    }),
-  );
+  const layout = layoutAfterTrackInsert(element, previewStart, insertRow, multi, deps);
+  if (!layout) return null;
+  const { normalized, targetTrack, writable } = layout;
   const bySrc = new Map(elements.map((e) => [keyOf(e), e]));
   // A partial zone renumber creates collisions; refuse a shifted locked row.
   for (const norm of normalized) {
@@ -399,6 +363,11 @@ function buildTrackInsertEdits(
       return null;
     }
   }
+  const candidate = elements.map((e) => {
+    if (keyOf(e) === editKey) return { ...e, start: previewStart, track: targetTrack };
+    if (multi?.keys.has(keyOf(e))) return { ...e, start: multi.movedStart(e) };
+    return e;
+  });
   const edits: TimelineMoveEdit[] = [];
   if (multi) {
     for (const src of elements) {
@@ -415,10 +384,10 @@ function buildTrackInsertEdits(
   for (const norm of normalized) {
     const src = bySrc.get(keyOf(norm));
     if (!src || !canMoveElement(src)) continue;
-    const start =
-      keyOf(norm) === editKey || multi?.keys.has(keyOf(norm))
-        ? (multi?.movedStart(src) ?? previewStart)
-        : src.start;
+    const normKey = keyOf(norm);
+    let start = src.start;
+    if (normKey === editKey) start = previewStart;
+    else if (multi?.keys.has(normKey)) start = multi.movedStart(src);
     edits.push({ element: src, updates: { start, track: norm.track } });
   }
   return { candidate, edits };

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.