@hyperframes/studio 0.7.55 → 0.7.56

package/src/player/components/timelineClipDragPreview.ts

@@ -1,52 +1,337 @@
+import { resolveTimelineMove, resolveTimelineResize } from "./timelineEditing";
 import type { TimelineElement } from "../store/playerStore";
-import type { TimelineStackingReorderIntent } from "./timelineEditing";
-import type { TimelineLayerId } from "./timelineTrackOrder";
+import { TRACK_H, getTimelineRowFromY, INSERT_BOUNDARY_BAND } from "./timelineLayout";
+import { isMusicTrack, isAudioTimelineElement } from "../../utils/timelineInspector";
+import {
+  TIMELINE_SNAP_PX,
+  snapMoveToTargets,
+  snapTimelineTime,
+  type TimelineSnapTarget,
+} from "./timelineSnapping";
+import { resolveInsertRow, resolveZoneDropPlacement } from "./timelineCollision";
+import {
+  applyTimelineGroupResizePreview,
+  type TimelineGroupResizeSession,
+} from "./timelineGroupEditing";
+import { clampGroupMoveDelta } from "./timelineMultiDragPreview";
+import type { DraggedClipState, ResizingClipState } from "./timelineClipDragTypes";
 
-interface DragPreviewState {
-  element: Pick<TimelineElement, "track">;
-  previewLayerId: TimelineLayerId;
-  previewLayerIndex: number;
+/** Snap-target builder closure supplied by the hook (closes over refs + store). */
+type BuildSnapTargets = (
+  excludeElementKey: string | null,
+  includeBeats: boolean,
+) => TimelineSnapTarget[];
+
+export interface DragPreviewContext {
+  scroll: HTMLDivElement | null;
+  pps: number;
+  duration: number;
+  trackOrder: number[];
+  elements: TimelineElement[];
+  selectedKeys: ReadonlySet<string>;
+  buildSnapTargets: BuildSnapTargets;
+  /**
+   * The set of tracks that hold audio clips (drives zone-aware drop placement).
+   * Frozen for the whole gesture, so the hook builds it ONCE at drag start and
+   * passes it in — see useTimelineClipDrag. Absent (e.g. in unit tests) ⇒ built
+   * on demand from `elements`, so the result is identical either way.
+   */
+  audioTracks?: ReadonlySet<number>;
 }
 
-export interface TimelineMovePreview {
-  start: number;
-  track: number;
-  previewLayerId?: TimelineLayerId;
-  previewLayerIndex?: number;
-  stackingReorder?: TimelineStackingReorderIntent | null;
+/**
+ * Max start a drag may reach. Allow dragging past the current content into the
+ * rendered timeline extent (the viewport-fill keeps that ≥ the viewport width).
+ * The composition grows to fit on commit (content-driven duration), so don't
+ * cap at content length.
+ */
+function resolveDragMaxStart(scroll: HTMLDivElement | null, pps: number, duration: number): number {
+  return Math.max(duration, scroll && pps > 0 ? scroll.scrollWidth / pps : duration);
 }
 
-export interface TimelineGroupMovePreview {
-  active: boolean;
-  previewStart: number;
+/**
+ * Rigid group move: when the grabbed clip is part of a multi-selection, the
+ * WHOLE formation shifts by its delta on commit (see timelineClipDragCommit).
+ * Clamp that delta here — against every selected member's start — so the
+ * grabbed clip can't out-run the group: it STOPS the instant any member would
+ * cross 0, exactly as it lands on commit. Lane changes still apply to the
+ * grabbed clip only, so only the start (x) is constrained.
+ */
+function resolveGroupClampedStart(
+  snapStart: number,
+  element: TimelineElement,
+  dragKey: string,
+  elements: TimelineElement[],
+  selectedKeys: ReadonlySet<string>,
+): number {
+  if (selectedKeys.size <= 1 || !selectedKeys.has(dragKey)) return snapStart;
+  const memberStarts = elements.filter((e) => selectedKeys.has(e.key ?? e.id)).map((e) => e.start);
+  const clampedDelta = clampGroupMoveDelta(snapStart - element.start, memberStarts);
+  return element.start + clampedDelta;
 }
 
-export function resolveDragPreviewPlacement(
-  drag: DragPreviewState,
-  nextMove: TimelineMovePreview,
-  groupMove: TimelineGroupMovePreview,
-): {
+/**
+ * The whole drop decision (no same-track overlap, zone-respecting, relocate or
+ * create) — one tested pure function, so what runs here is what's verified.
+ */
+function resolveDropPlacement(
+  drag: DraggedClipState,
+  clientY: number,
+  previewStart: number,
+  desiredTrack: number,
+  ctx: DragPreviewContext,
+): { track: number; insertRow: number | null } {
+  const { scroll, trackOrder, elements } = ctx;
+  // rowFloat = the pointer's position in track-heights from the top lane; a
+  // near-boundary hover requests a deliberate new-track insert. Uses the
+  // shared row→y inverse so the top breathing pad is subtracted consistently.
+  const rowFloat = scroll
+    ? getTimelineRowFromY(clientY - scroll.getBoundingClientRect().top + scroll.scrollTop)
+    : 0;
+  // Geometry-exact band (the clip inset) so an insert only arms in the visible
+  // gutter BETWEEN clip bodies — dragging over a clip body is a lane move, never a
+  // phantom insert (the plain-horizontal-drag misfire). See INSERT_BOUNDARY_BAND.
+  const rawInsertRow = resolveInsertRow(rowFloat, trackOrder.length, INSERT_BOUNDARY_BAND);
+  // Pointer sub-row half: when a drop must auto-create a track (aimed span
+  // occupied, no free lane), open it on the side the pointer is nearer.
+  const preferInsertAbove = rowFloat - Math.floor(rowFloat) < 0.5;
+  const audioTracks =
+    ctx.audioTracks ?? new Set(elements.filter(isAudioTimelineElement).map((e) => e.track));
+  return resolveZoneDropPlacement({
+    order: trackOrder,
+    audioTracks,
+    elements,
+    desiredTrack,
+    deliberateInsertRow: rawInsertRow,
+    start: previewStart,
+    duration: drag.element.duration,
+    dragKey: drag.element.key ?? drag.element.id,
+    isAudio: isAudioTimelineElement(drag.element),
+    preferInsertAbove,
+  });
+}
+
+/** Recompute the dragged-clip preview (move + snap + group clamp + drop placement). */
+export function computeDragPreview(
+  drag: DraggedClipState,
+  clientX: number,
+  clientY: number,
+  ctx: DragPreviewContext,
+): DraggedClipState {
+  const { scroll, pps, duration, trackOrder, elements, selectedKeys, buildSnapTargets } = ctx;
+  const dragMaxStart = resolveDragMaxStart(scroll, pps, duration);
+  const nextMove = resolveTimelineMove(
+    {
+      start: drag.element.start,
+      track: drag.element.track,
+      duration: drag.element.duration,
+      originClientX: drag.originClientX,
+      originClientY: drag.originClientY,
+      originScrollLeft: drag.originScrollLeft,
+      originScrollTop: drag.originScrollTop,
+      currentScrollLeft: scroll?.scrollLeft ?? drag.originScrollLeft,
+      currentScrollTop: scroll?.scrollTop ?? drag.originScrollTop,
+      pixelsPerSecond: pps,
+      trackHeight: TRACK_H,
+      maxStart: dragMaxStart,
+      trackOrder,
+    },
+    clientX,
+    clientY,
+  );
+  // The music track defines the beats, so it must not snap to them —
+  // but it still snaps to the playhead and other clip edges.
+  const targets = buildSnapTargets(
+    drag.element.key ?? drag.element.id,
+    !isMusicTrack(drag.element),
+  );
+  const snap = snapMoveToTargets(
+    nextMove.start,
+    drag.element.duration,
+    targets,
+    pps,
+    // Relaxed clamp: allow the snapped start past the content, up to the
+    // rendered extent (see dragMaxStart) — the composition grows on commit.
+    dragMaxStart + drag.element.duration,
+  );
+  const dragKey = drag.element.key ?? drag.element.id;
+  const previewStart = resolveGroupClampedStart(
+    snap.start,
+    drag.element,
+    dragKey,
+    elements,
+    selectedKeys,
+  );
+  const { track: previewTrack, insertRow } = resolveDropPlacement(
+    drag,
+    clientY,
+    previewStart,
+    nextMove.track,
+    ctx,
+  );
+  return {
+    ...drag,
+    started: true,
+    pointerClientX: clientX,
+    pointerClientY: clientY,
+    previewStart,
+    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.
+    desiredTrack: nextMove.track,
+    insertRow,
+    snapTime: snap.snapTime,
+    snapType: snap.snapType,
+  };
+}
+
+export interface ResizePreviewContext {
+  scroll: HTMLDivElement | null;
+  pps: number;
+  buildSnapTargets: BuildSnapTargets;
+}
+
+export interface ResizePreviewResult {
+  originScrollLeft: number;
   previewStart: number;
-  previewTrack: number;
-  previewLayerId: TimelineLayerId;
-  previewLayerIndex: number;
-  previewStackingReorder: TimelineStackingReorderIntent | null;
-} {
-  if (groupMove.active) {
-    return {
-      previewStart: groupMove.previewStart,
-      previewTrack: drag.element.track,
-      previewLayerId: drag.previewLayerId,
-      previewLayerIndex: drag.previewLayerIndex,
-      previewStackingReorder: null,
-    };
+  previewDuration: number;
+  previewPlaybackStart?: number;
+}
+
+/** Compute the trim preview for a pointer x (pure — the hook applies the state). */
+// fallow-ignore-next-line complexity
+export function computeResizePreview(
+  resize: ResizingClipState,
+  clientX: number,
+  ctx: ResizePreviewContext,
+): ResizePreviewResult {
+  const { scroll, pps, buildSnapTargets } = ctx;
+  // Scroll compensation: auto-scroll moves the content while the pointer stays
+  // put, so fold the scroll delta into the pointer x (mirrors
+  // resolveTimelineMove's originScrollLeft handling).
+  const originScrollLeft = resize.originScrollLeft ?? scroll?.scrollLeft ?? 0;
+  const effectiveClientX = clientX + ((scroll?.scrollLeft ?? originScrollLeft) - originScrollLeft);
+
+  const sourceRemaining =
+    resize.element.sourceDuration != null
+      ? Math.max(
+          0,
+          (resize.element.sourceDuration - (resize.element.playbackStart ?? 0)) /
+            Math.max(resize.element.playbackRate ?? 1, 0.1),
+        )
+      : Number.POSITIVE_INFINITY;
+  const normalizedTag = resize.element.tag.toLowerCase();
+  const canSeedPlaybackStart = normalizedTag === "audio" || normalizedTag === "video";
+  const playbackRate = Math.max(resize.element.playbackRate ?? 1, 0.1);
+  // Trim limit = available source media only — NOT the composition length.
+  // Duration is content-driven (the comp grows/shrinks to fit on commit), so
+  // capping a trim at the current comp end both blocked extending the last clip
+  // rightward and, after a far move, collapsed a clip to the sliver between its
+  // start and the comp end (the 8s→0.95s audio incident). Images/text/shapes
+  // have no source, so they extend freely.
+  const maxEnd = resize.element.start + sourceRemaining;
+  let nextResize = resolveTimelineResize(
+    {
+      start: resize.element.start,
+      duration: resize.element.duration,
+      originClientX: resize.originClientX,
+      pixelsPerSecond: pps,
+      minStart: 0,
+      maxEnd,
+      playbackStart:
+        resize.edge === "start" && canSeedPlaybackStart
+          ? (resize.element.playbackStart ?? 0)
+          : resize.element.playbackStart,
+      playbackRate: resize.element.playbackRate,
+    },
+    resize.edge,
+    effectiveClientX,
+  );
+
+  // Snap edge to unified targets (beats + clip edges + playhead) when available.
+  // The snap must stay inside the same limits resolveTimelineResize enforces, or
+  // it would push the edge past the available source media / composition end.
+  // The music track defines the beats, so it must not snap to them — but it
+  // still snaps to the playhead and other clip edges.
+  const trimTargets = buildSnapTargets(
+    resize.element.key ?? resize.element.id,
+    !isMusicTrack(resize.element),
+  );
+  if (trimTargets.length > 0) {
+    const snapSecs = TIMELINE_SNAP_PX / Math.max(pps, 1);
+    if (resize.edge === "end") {
+      const edgeTime = nextResize.start + nextResize.duration;
+      const snapped = snapTimelineTime(edgeTime, trimTargets, snapSecs).time;
+      // Stay within [start+minDuration, maxEnd] so the snap can't create a
+      // degenerate clip or run past the source/composition limit.
+      const snappedDuration = Math.round((snapped - nextResize.start) * 1000) / 1000;
+      if (snapped !== edgeTime && snapped <= maxEnd + 1e-6 && snappedDuration >= 0.05) {
+        nextResize = { ...nextResize, duration: snappedDuration };
+      }
+    } else {
+      const snapped = snapTimelineTime(nextResize.start, trimTargets, snapSecs).time;
+      const delta = nextResize.start - snapped; // >0 when snapping left
+      // Leftward snap reveals more source; cap so playbackStart can't go < 0.
+      const maxLeftDelta =
+        nextResize.playbackStart != null
+          ? nextResize.playbackStart / playbackRate
+          : Number.POSITIVE_INFINITY;
+      // Also require the resulting duration to stay >= minDuration so a rightward
+      // snap (delta < 0) can't collapse the clip to zero/negative.
+      const snappedDuration = Math.round((nextResize.duration + delta) * 1000) / 1000;
+      if (
+        snapped !== nextResize.start &&
+        snapped >= 0 &&
+        delta <= maxLeftDelta + 1e-6 &&
+        snappedDuration >= 0.05
+      ) {
+        nextResize = {
+          ...nextResize,
+          start: snapped,
+          duration: snappedDuration,
+          playbackStart:
+            nextResize.playbackStart != null
+              ? Math.round(Math.max(0, nextResize.playbackStart - delta * playbackRate) * 1000) /
+                1000
+              : undefined,
+        };
+      }
+    }
   }
 
   return {
-    previewStart: groupMove.previewStart,
-    previewTrack: nextMove.track,
-    previewLayerId: nextMove.previewLayerId ?? drag.previewLayerId,
-    previewLayerIndex: nextMove.previewLayerIndex ?? drag.previewLayerIndex,
-    previewStackingReorder: nextMove.stackingReorder ?? null,
+    originScrollLeft,
+    previewStart: nextResize.start,
+    previewDuration: nextResize.duration,
+    previewPlaybackStart: nextResize.playbackStart,
   };
 }
+
+/**
+ * Apply a rigid group-resize preview: fold the grabbed clip's raw delta into the
+ * session, preview every non-grabbed member through the store (`updateElement`),
+ * and set the grabbed clip's preview state (it renders from resizingClip state, so
+ * its store value stays pristine until commit — like the single-clip path).
+ */
+export function previewGroupResize(
+  session: TimelineGroupResizeSession,
+  next: ResizePreviewResult,
+  grabbedKey: string,
+  updateElement: (
+    key: string,
+    patch: { start: number; duration: number; playbackStart?: number },
+  ) => void,
+  setResizeState: (v: ResizePreviewResult) => void,
+): void {
+  const grabbedChange = applyTimelineGroupResizePreview(session, next);
+  for (const c of session.changes) {
+    if (c.key === grabbedKey) continue;
+    updateElement(c.key, { start: c.start, duration: c.duration, playbackStart: c.playbackStart });
+  }
+  setResizeState({
+    originScrollLeft: next.originScrollLeft,
+    previewStart: grabbedChange?.start ?? next.previewStart,
+    previewDuration: grabbedChange?.duration ?? next.previewDuration,
+    previewPlaybackStart: grabbedChange?.playbackStart ?? next.previewPlaybackStart,
+  });
+}

package/src/player/components/timelineClipDragTypes.ts

@@ -0,0 +1,65 @@
+import type { TimelineElement } from "../store/playerStore";
+import type { TimelineSnapType } from "./timelineSnapping";
+import type { BlockedTimelineEditIntent } from "./timelineEditing";
+
+/* ── Shared clip-drag state types ───────────────────────────────── */
+export interface DraggedClipState {
+  element: TimelineElement;
+  originClientX: number;
+  originClientY: number;
+  originScrollLeft: number;
+  originScrollTop: number;
+  pointerClientX: number;
+  pointerClientY: number;
+  pointerOffsetX: number;
+  pointerOffsetY: number;
+  previewStart: number;
+  previewTrack: number;
+  /**
+   * The lane the POINTER aims at (from the drag's vertical position), before
+   * collision resolution. `previewTrack` is where the clip actually LANDS —
+   * which may differ from `desiredTrack` when the aimed span is occupied and the
+   * collision rules bump the dragged clip to a free lane. The commit reads this
+   * to tell a deliberate VERTICAL lane change (pointer aimed at another lane →
+   * stacking sync allowed) from a plain HORIZONTAL drag whose clip merely got
+   * bumped sideways (never touches z). Optional: when absent the commit falls
+   * back to `previewTrack` (pre-existing behaviour).
+   */
+  desiredTrack?: number;
+  /**
+   * When non-null, the drop inserts a NEW track at this visual row boundary
+   * (0 = above the top lane, trackOrder.length = below the bottom) instead of
+   * landing on previewTrack. Drives the insertion-line indicator.
+   */
+  insertRow: number | null;
+  /** Snap target the clip will land on, for the guide highlight. */
+  snapTime: number | null;
+  snapType: TimelineSnapType | null;
+  started: boolean;
+}
+
+export interface ResizingClipState {
+  element: TimelineElement;
+  edge: "start" | "end";
+  originClientX: number;
+  /**
+   * scrollLeft at gesture start. Edge auto-scroll moves the content under a
+   * stationary pointer, so the trim math folds (current − origin) scrollLeft
+   * into the pointer x — mirroring resolveTimelineMove's scroll compensation.
+   * Optional so pre-existing constructors/tests stay valid; when absent the
+   * first preview update captures the current scrollLeft.
+   */
+  originScrollLeft?: number;
+  previewStart: number;
+  previewDuration: number;
+  previewPlaybackStart?: number;
+  started: boolean;
+}
+
+export interface BlockedClipState {
+  element: TimelineElement;
+  intent: BlockedTimelineEditIntent;
+  originClientX: number;
+  originClientY: number;
+  started: boolean;
+}

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

@@ -9,6 +9,7 @@ import {
   resolveZoneDropPlacement,
   timeRangesOverlap,
 } from "./timelineCollision";
+import { INSERT_BOUNDARY_BAND } from "./timelineLayout";
 
 function el(id: string, track: number, start: number, duration: number): TimelineElement {
   return { id, tag: "video", start, duration, track };
@@ -191,8 +192,47 @@ describe("resolveInsertRow", () => {
   });
 });
 
-// (The production insert-band suite imports INSERT_BOUNDARY_BAND from timelineLayout,
-// which lands with the timeline glue swap — the full suite re-lands there.)
+describe("resolveInsertRow — production band only arms in the inter-clip gutter (UX rule 1)", () => {
+  // The production band equals the clip inset (CLIP_Y / TRACK_H): a clip body fills
+  // [band, 1 − band] of its row, so an insert must ONLY arm in the thin gutter that
+  // straddles a boundary — never while the pointer is over a clip body. This is the
+  // regression for the plain-horizontal-drag misfire (the old 0.32 band armed an
+  // insert across ~64% of every row).
+  const n = 3;
+  const b = INSERT_BOUNDARY_BAND;
+
+  it("the band is the clip inset (3/48), not the old feel-tuned 0.32", () => {
+    expect(b).toBeCloseTo(3 / 48, 10);
+    expect(b).toBeLessThan(0.1);
+  });
+
+  it("returns null across the WHOLE clip body of every lane (no insert = move-to-lane)", () => {
+    // Sweep each lane's body [band+ε, 1−band−ε] in fine steps → always a move.
+    for (let lane = 0; lane < n; lane++) {
+      for (let frac = b + 0.01; frac <= 1 - b - 0.01 + 1e-9; frac += 0.02) {
+        expect(resolveInsertRow(lane + frac, n, b)).toBeNull();
+      }
+    }
+  });
+
+  it("arms an insert in the gutter straddling every internal boundary (dead-zone-free)", () => {
+    // Just under a boundary → insert BELOW the upper lane; just over → ABOVE the
+    // lower lane. Both resolve to the same boundary row, so the gutter has no dead
+    // spot that neither moves nor inserts.
+    expect(resolveInsertRow(1 - b / 2, n, b)).toBe(1); // bottom gutter of lane 0
+    expect(resolveInsertRow(1 + b / 2, n, b)).toBe(1); // top gutter of lane 1
+    expect(resolveInsertRow(2 - b / 2, n, b)).toBe(2);
+    expect(resolveInsertRow(2 + b / 2, n, b)).toBe(2);
+  });
+
+  it("still arms a top / bottom insert above the first / below the last lane", () => {
+    expect(resolveInsertRow(b / 2, n, b)).toBe(0); // top gutter of lane 0 → insert above top
+    expect(resolveInsertRow(-0.4, n, b)).toBe(0); // in the top breathing pad
+    expect(resolveInsertRow(n - b / 2, n, b)).toBe(n); // bottom gutter of last lane
+    expect(resolveInsertRow(n + 0.4, n, b)).toBe(n); // in the bottom breathing pad
+  });
+});
+
 describe("clampTrackToZone", () => {
   // trackOrder [0,1,2,3]: rows 0,1 = visual; rows 2,3 = audio (audioRow = 2).
   const order = [0, 1, 2, 3];

package/src/player/components/timelineDragDrop.ts

@@ -1,23 +1,50 @@
 import { useCallback, useState, type RefObject } from "react";
 import { TIMELINE_ASSET_MIME, TIMELINE_BLOCK_MIME } from "../../utils/timelineAssetDrop";
+import { usePlayerStore } from "../store/playerStore";
 import { TRACK_H, resolveTimelineAssetDrop } from "./timelineLayout";
 import type { TimelineDropCallbacks } from "./timelineCallbacks";
-import type { StackingTimelineLayer, TimelineLayerId } from "./timelineTrackOrder";
 
 interface UseTimelineAssetDropOptions extends TimelineDropCallbacks {
   scrollRef: RefObject<HTMLDivElement | null>;
   ppsRef: RefObject<number>;
   durationRef: RefObject<number>;
-  trackOrderRef: RefObject<TimelineLayerId[]>;
-  timelineLayersRef: RefObject<StackingTimelineLayer[]>;
+  trackOrderRef: RefObject<number[]>;
 }
 
+type TimelinePlacement = { start: number; track: number };
+
+/**
+ * Parse a JSON drag payload and, if it yields a value, forward it to the drop
+ * callback. Malformed payloads are ignored. Shared by the asset + block paths so
+ * the parse/guard/dispatch shape lives in one place.
+ */
+function applyJsonDropPayload(
+  raw: string,
+  pick: (parsed: Record<string, string | undefined>) => string | undefined,
+  apply: (value: string, placement: TimelinePlacement) => void,
+  placement: TimelinePlacement,
+): void {
+  try {
+    const value = pick(JSON.parse(raw) as Record<string, string | undefined>);
+    if (value) apply(value, placement);
+  } catch {
+    /* ignore malformed drag payloads */
+  }
+}
+
+/**
+ * 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.
+ */
 export function useTimelineAssetDrop({
   scrollRef,
   ppsRef,
   durationRef,
   trackOrderRef,
-  timelineLayersRef,
   onFileDrop,
   onAssetDrop,
   onBlockDrop,
@@ -25,83 +52,65 @@ export function useTimelineAssetDrop({
   const [isDragOver, setIsDragOver] = useState(false);
 
   const handleAssetDragOver = useCallback((e: React.DragEvent) => {
-    const hasFiles = e.dataTransfer.files.length > 0;
     const types = Array.from(e.dataTransfer.types);
+    const hasFiles = types.includes("Files");
     const hasAsset = types.includes(TIMELINE_ASSET_MIME);
     const hasBlock = types.includes(TIMELINE_BLOCK_MIME);
     if (!hasFiles && !hasAsset && !hasBlock) return;
     e.preventDefault();
-    if (hasAsset || hasBlock) e.dataTransfer.dropEffect = "copy";
+    e.dataTransfer.dropEffect = "copy";
     setIsDragOver(true);
   }, []);
 
+  const clearDropPreview = useCallback(() => setIsDragOver(false), []);
+
+  const resolveDropPlacement = useCallback(
+    (clientX: number, clientY: number): TimelinePlacement => {
+      const scroll = scrollRef.current;
+      const rect = scroll?.getBoundingClientRect();
+      // Track comes from the vertical drop position; start is the playhead.
+      const { track } = resolveTimelineAssetDrop(
+        {
+          rectLeft: rect?.left ?? 0,
+          rectTop: rect?.top ?? 0,
+          scrollLeft: scroll?.scrollLeft ?? 0,
+          scrollTop: scroll?.scrollTop ?? 0,
+          pixelsPerSecond: ppsRef.current,
+          duration: durationRef.current,
+          trackHeight: TRACK_H,
+          trackOrder: trackOrderRef.current,
+        },
+        clientX,
+        clientY,
+      );
+      const start = Math.max(0, usePlayerStore.getState().currentTime);
+      return { start, track };
+    },
+    [scrollRef, ppsRef, durationRef, trackOrderRef],
+  );
+
   const handleAssetDrop = useCallback(
-    // fallow-ignore-next-line complexity
     (e: React.DragEvent) => {
       e.preventDefault();
       setIsDragOver(false);
-      const scroll = scrollRef.current;
-      const rect = scroll?.getBoundingClientRect();
-      const layerById = new Map(timelineLayersRef.current.map((layer) => [layer.id, layer]));
-      const trackOrder = trackOrderRef.current
-        .map((id) => layerById.get(id)?.placementTrack)
-        .filter((track): track is number => track != null);
-      const dropInput = {
-        rectLeft: rect?.left ?? 0,
-        rectTop: rect?.top ?? 0,
-        scrollLeft: scroll?.scrollLeft ?? 0,
-        scrollTop: scroll?.scrollTop ?? 0,
-        pixelsPerSecond: ppsRef.current,
-        duration: durationRef.current,
-        trackHeight: TRACK_H,
-        trackOrder,
-      };
+      const placement = resolveDropPlacement(e.clientX, e.clientY);
+
       if (onFileDrop && e.dataTransfer.files.length > 0) {
-        void onFileDrop(
-          Array.from(e.dataTransfer.files),
-          scroll && rect ? resolveTimelineAssetDrop(dropInput, e.clientX, e.clientY) : undefined,
-        );
+        void onFileDrop(Array.from(e.dataTransfer.files), placement);
         return;
       }
       const assetPayload = e.dataTransfer.getData(TIMELINE_ASSET_MIME);
-      if (assetPayload && onAssetDrop && scroll && rect) {
-        try {
-          const parsed = JSON.parse(assetPayload) as { path?: string };
-          if (parsed.path)
-            void onAssetDrop(
-              parsed.path,
-              resolveTimelineAssetDrop(dropInput, e.clientX, e.clientY),
-            );
-        } catch {
-          /* ignore malformed drag payloads */
-        }
+      if (assetPayload && onAssetDrop) {
+        applyJsonDropPayload(assetPayload, (p) => p.path, onAssetDrop, placement);
         return;
       }
       const blockPayload = e.dataTransfer.getData(TIMELINE_BLOCK_MIME);
-      if (blockPayload && onBlockDrop && scroll && rect) {
-        try {
-          const parsed = JSON.parse(blockPayload) as { name?: string };
-          if (parsed.name)
-            void onBlockDrop(
-              parsed.name,
-              resolveTimelineAssetDrop(dropInput, e.clientX, e.clientY),
-            );
-        } catch {
-          /* ignore malformed drag payloads */
-        }
+      if (blockPayload && onBlockDrop) {
+        applyJsonDropPayload(blockPayload, (p) => p.name, onBlockDrop, placement);
       }
     },
-    [
-      onAssetDrop,
-      onBlockDrop,
-      onFileDrop,
-      scrollRef,
-      ppsRef,
-      durationRef,
-      trackOrderRef,
-      timelineLayersRef,
-    ],
+    [resolveDropPlacement, onFileDrop, onAssetDrop, onBlockDrop],
   );
 
-  return { isDragOver, setIsDragOver, handleAssetDragOver, handleAssetDrop };
+  return { isDragOver, handleAssetDragOver, handleAssetDrop, clearDropPreview };
 }