@hyperframes/studio 0.8.111 → 0.8.112

package/src/player/components/useTimelineClipDrag.ts

@@ -16,6 +16,7 @@ import type { StackingPatch } from "./timelineStackingSync";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import {
   computeDragPreview,
+  createKeyboardClipDrag,
   computeResizePreview,
   trimPreviewTime,
   previewGroupResize,
@@ -29,6 +30,19 @@ import type {
 import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";
 import { dropMisalignedTrimPartners, linkedGestureKeys } from "./audioClipLink";
 import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
+import { useTimelineClipCapabilities } from "./timelineReadOnly";
+import { timelineClipFocusId } from "./timelineNavigationIdentity";
+import {
+  handleClipPickupKeyboardEvent,
+  scrollKeyboardInsertRow,
+  timelineKeyboardEventTarget,
+} from "./useTimelineKeyboardActor";
+import {
+  timelineTrackOrderChanged,
+  nextKeyboardInsertRow,
+  keyboardPickupInsertRow,
+  type TimelineTrackInsertLayout,
+} from "./timelineTrackInsertLayout";
 import type { TimelineRowGeometry } from "./timelineLayout";
 import {
   mountTimelineClipDragGestureLifecycle,
@@ -50,17 +64,10 @@ interface UseTimelineClipDragInput {
   ppsRef: React.RefObject<number>;
   durationRef: React.RefObject<number>;
   trackOrderRef: React.RefObject<number[]>;
+  trackInsertLayoutRef?: React.RefObject<TimelineTrackInsertLayout | undefined>;
   rowGeometryRef?: React.RefObject<TimelineRowGeometry>;
-  onMoveElement?: (
-    element: TimelineElement,
-    updates: Pick<TimelineElement, "start" | "track">,
-  ) => Promise<void> | void;
-  onMoveElements?: (
-    edits: Array<{
-      element: TimelineElement;
-      updates: Pick<TimelineElement, "start" | "track">;
-    }>,
-  ) => Promise<void> | void;
+  onMoveElement?: TimelineEditCallbacks["onMoveElement"];
+  onMoveElements?: TimelineEditCallbacks["onMoveElements"];
   onResizeElement?: (
     element: TimelineElement,
     updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
@@ -92,6 +99,7 @@ export function useTimelineClipDrag({
   ppsRef,
   durationRef,
   trackOrderRef,
+  trackInsertLayoutRef,
   rowGeometryRef,
   onMoveElement,
   onMoveElements,
@@ -107,6 +115,8 @@ export function useTimelineClipDrag({
   refreshAfterLaneMove,
   sessionEpoch = 0,
 }: UseTimelineClipDragInput) {
+  const getClipCapabilities = useTimelineClipCapabilities();
+  const commitGestureRef = useRef<() => void>(() => {});
   const updateElement = usePlayerStore((s) => s.updateElement);
   const rawBeatTimes = usePlayerStore((s) => s.beatAnalysis?.beatTimes ?? EMPTY_BEAT_TIMES);
   const rawBeatStrengths = usePlayerStore((s) => s.beatAnalysis?.beatStrengths ?? EMPTY_BEAT_TIMES);
@@ -207,7 +217,7 @@ export function useTimelineClipDrag({
   const cancelGestureRef = useRef<
     (options?: { updateReact?: boolean; suppressClick?: boolean }) => boolean
   >(() => false);
-  const beginGesture = useCallback((kind: TimelineGestureKind, pointerId: number) => {
+  const beginGesture = useCallback((kind: TimelineGestureKind, pointerId: number | null) => {
     if (lifecycleRef.current.phase === "active") cancelGestureRef.current();
     lifecycleRef.current = {
       kind,
@@ -310,14 +320,25 @@ export function useTimelineClipDrag({
         pps: ppsRef.current,
         duration: durationRef.current,
         trackOrder: trackOrderRef.current,
+        allowedInsertRows: trackInsertLayoutRef?.current?.allowedRows,
+        groupTracks: trackInsertLayoutRef?.current?.groupTracks,
         rowHeights: rowGeometryRef?.current.rowHeights,
+        rowGeometry: rowGeometryRef?.current,
         elements: elementsRef.current,
         selectedKeys: gestureSelectedKeysRef.current,
         buildSnapTargets,
         audioTracks: dragAudioTracksRef.current,
       });
     },
-    [scrollRef, ppsRef, durationRef, trackOrderRef, rowGeometryRef, buildSnapTargets],
+    [
+      scrollRef,
+      ppsRef,
+      durationRef,
+      trackOrderRef,
+      trackInsertLayoutRef,
+      rowGeometryRef,
+      buildSnapTargets,
+    ],
   );
 
   // Recompute the trim preview for a pointer x. Shared by the pointermove resize
@@ -445,6 +466,8 @@ export function useTimelineClipDrag({
 
   useMountEffect(() =>
     mountTimelineClipDragGestureLifecycle({
+      trackInsertLayoutRef,
+      commitGestureRef,
       onStackingPatchesRef,
       refreshAfterLaneMoveRef,
       readZIndexRef,
@@ -479,10 +502,91 @@ export function useTimelineClipDrag({
     }),
   );
 
+  useEffect(() => {
+    const movePickup = (drag: DraggedClipState, step: -1 | 1, viewport: HTMLDivElement | null) => {
+      const audioTracks = getTimelineElementIndexes(elementsRef.current).audioTracks;
+      const row = nextKeyboardInsertRow({
+        current: drag.insertRow ?? 0,
+        step,
+        order: trackOrderRef.current,
+        layout: trackInsertLayoutRef?.current,
+        audioTracks,
+        isAudio: audioTracks.has(drag.element.track),
+      });
+      if (row === null) return;
+      publishDraggedClip({ ...drag, insertRow: row });
+      if (viewport && rowGeometryRef)
+        scrollKeyboardInsertRow(viewport, rowGeometryRef.current, row);
+    };
+    const activePickup = (
+      event: KeyboardEvent,
+      drag: DraggedClipState,
+      viewport: HTMLDivElement | null,
+    ) => {
+      handleClipPickupKeyboardEvent(event, {
+        move: (step) => movePickup(drag, step, viewport),
+        commit: commitGestureRef.current,
+        cancel: cancelGestureRef.current,
+        focus: () =>
+          usePlayerStore
+            .getState()
+            .requestTimelineFocus(timelineClipFocusId(drag.element.key ?? drag.element.id)),
+      });
+    };
+    const pickup = (event: KeyboardEvent, viewport: HTMLDivElement) => {
+      const target = timelineKeyboardEventTarget(event.target, viewport);
+      const key = target?.dataset.elId;
+      if (key === undefined || !onMoveElementRef.current) return;
+      const element = getTimelineElementIndexes(elementsRef.current).byKey.get(key);
+      if (!element || !getClipCapabilities(element).canMove) return;
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      setShowPopover(false);
+      setRangeSelectionRef.current?.(null);
+      const row = keyboardPickupInsertRow(
+        trackOrderRef.current.indexOf(element.track),
+        trackInsertLayoutRef?.current?.allowedRows,
+      );
+      setDraggedClip(createKeyboardClipDrag(element, row, viewport.scrollLeft, viewport.scrollTop));
+    };
+    const handleKeyDown = (event: KeyboardEvent) => {
+      const drag = draggedClipRef.current;
+      const viewport = scrollRef.current;
+      if (drag) {
+        if (drag.pointerId === null) activePickup(event, drag, viewport);
+        return;
+      }
+      if (resizingClipRef.current) return;
+      if (event.key !== " " || event.repeat) return;
+      if (viewport) pickup(event, viewport);
+    };
+    window.addEventListener("keydown", handleKeyDown, true);
+    return () => window.removeEventListener("keydown", handleKeyDown, true);
+  }, [
+    getClipCapabilities,
+    publishDraggedClip,
+    rowGeometryRef,
+    scrollRef,
+    setDraggedClip,
+    setRangeSelectionRef,
+    setShowPopover,
+    trackOrderRef,
+    trackInsertLayoutRef,
+  ]);
+
   useEffect(() => {
     cancelGestureRef.current();
   }, [sessionEpoch]);
 
+  const previousOrderRef = useRef(trackOrderRef.current);
+  useEffect(() => {
+    const order = trackOrderRef.current;
+    const previous = previousOrderRef.current;
+    previousOrderRef.current = order;
+    if (draggedClipRef.current && timelineTrackOrderChanged(previous, order))
+      cancelGestureRef.current();
+  });
+
   return {
     draggedClip,
     setDraggedClip,

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

@@ -0,0 +1,59 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it } from "vitest";
+import { useTimelineDisplayLayout } from "./useTimelineTrackLayout";
+import { createTimelineRowGeometry } from "./timelineLayout";
+import type { DraggedClipState } from "./timelineClipDragTypes";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+it("opens one full lane at the insertion index without changing committed tracks", () => {
+  const order = [7, 3, 9];
+  const geometry = createTimelineRowGeometry(order, [48, 104, 48], { top: 0 });
+  const host = document.createElement("div");
+  const root = createRoot(host);
+  const drag: DraggedClipState = {
+    pointerId: 1,
+    element: { id: "clip", tag: "div", start: 1, duration: 2, track: 9 },
+    originClientX: 0,
+    originClientY: 0,
+    originScrollLeft: 0,
+    originScrollTop: 0,
+    pointerClientX: 0,
+    pointerClientY: 0,
+    pointerOffsetX: 0,
+    pointerOffsetY: 0,
+    previewStart: 1,
+    previewTrack: 3,
+    insertRow: 1,
+    snapTime: null,
+    snapType: null,
+    started: true,
+  };
+  function Probe({ active }: { active: DraggedClipState | null }) {
+    const layout = useTimelineDisplayLayout(active, order, geometry);
+    return (
+      <output>
+        {JSON.stringify({
+          order: layout.displayTrackOrder,
+          pinned: layout.draggedRowKey,
+          heights: layout.displayRowHeights,
+          below: layout.rowGeometry.getRowTop(2),
+        })}
+      </output>
+    );
+  }
+  act(() => root.render(<Probe active={drag} />));
+  const seen = JSON.parse(host.textContent!);
+  expect(seen.order).toHaveLength(4);
+  expect(seen.pinned).toBe(-1);
+  expect(seen.order.filter((key: number) => order.includes(key))).toEqual(order);
+  expect(order.includes(seen.order[1])).toBe(false);
+  expect(seen.heights).toEqual([48, 48, 104, 48]);
+  expect(seen.below).toBe(120);
+  expect(order).toEqual([7, 3, 9]);
+  act(() => root.render(<Probe active={null} />));
+  expect(JSON.parse(host.textContent!).order).toEqual(order);
+  act(() => root.unmount());
+});

package/src/player/components/useTimelineKeyboardActor.ts

@@ -1,6 +1,6 @@
 import { useCallback, useMemo, type FocusEvent, type KeyboardEvent, type RefObject } from "react";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
-import type { TimelineRowGeometry } from "./timelineLayout";
+import { RULER_H, TRACK_H, type TimelineRowGeometry } from "./timelineLayout";
 import {
   isTimelineNavigationKey,
   locateTimelineLogicalTarget,
@@ -17,14 +17,92 @@ interface TimelineKeyboardActorInput {
   onDrillDown?: (element: TimelineElement) => void;
 }
 
-function eventTarget(event: FocusEvent | KeyboardEvent): HTMLElement | null {
-  if (!(event.target instanceof Element)) return null;
+type ClipPickupAction =
+  | { kind: "move"; step: -1 | 1 }
+  | { kind: "commit" }
+  | { kind: "cancel" }
+  | { kind: "focus" }
+  | { kind: "consume" };
+
+function clipPickupKeyboardAction(event: {
+  key: string;
+  repeat: boolean;
+}): ClipPickupAction | null {
+  switch (event.key) {
+    case "ArrowUp":
+      return { kind: "move", step: -1 };
+    case "ArrowDown":
+      return { kind: "move", step: 1 };
+    case "Enter":
+      return { kind: event.repeat ? "focus" : "commit" };
+    case "Escape":
+      return { kind: "cancel" };
+    case " ":
+      return { kind: "consume" };
+    default:
+      return null;
+  }
+}
+
+export function handleClipPickupKeyboardEvent(
+  event: globalThis.KeyboardEvent,
+  actions: {
+    move: (step: -1 | 1) => void;
+    commit: () => void;
+    cancel: () => void;
+    focus: () => void;
+  },
+): void {
+  const action = clipPickupKeyboardAction(event);
+  if (!action) return;
+  event.preventDefault();
+  event.stopImmediatePropagation();
+  switch (action.kind) {
+    case "move":
+      actions.move(action.step);
+      break;
+    case "commit":
+      actions.commit();
+      actions.focus();
+      break;
+    case "cancel":
+      actions.cancel();
+      actions.focus();
+      break;
+    case "focus":
+      actions.focus();
+      break;
+    case "consume":
+      break;
+    default: {
+      const unreachable: never = action;
+      throw new Error(`Unknown pickup action: ${unreachable}`);
+    }
+  }
+}
+
+export function scrollKeyboardInsertRow(
+  viewport: HTMLDivElement,
+  geometry: TimelineRowGeometry,
+  row: number,
+): void {
+  const top = geometry.getRowTop(row);
+  if (top < viewport.scrollTop + RULER_H) viewport.scrollTop = Math.max(0, top - RULER_H);
+  else if (top + TRACK_H > viewport.scrollTop + viewport.clientHeight)
+    viewport.scrollTop = top + TRACK_H - viewport.clientHeight;
+}
+
+export function timelineKeyboardEventTarget(
+  target: EventTarget | null,
+  container: HTMLElement,
+): HTMLElement | null {
+  if (!(target instanceof Element)) return null;
   // Header actions stay native Tab stops because they have no row-level shortcut.
   // The nearest interactive ancestor wins so their events never masquerade as row events.
-  const target = event.target.closest<HTMLElement>(
+  const nearest = target.closest<HTMLElement>(
     "button, input, select, textarea, a[href], [contenteditable], [role='slider'], [data-timeline-focus-id]",
   );
-  return target?.dataset.timelineFocusId && event.currentTarget.contains(target) ? target : null;
+  return nearest?.dataset.timelineFocusId && container.contains(nearest) ? nearest : null;
 }
 
 function viewportPageSize(
@@ -87,7 +165,8 @@ export function useTimelineKeyboardActor({
 
   const onFocus = useCallback(
     (event: FocusEvent<HTMLElement>) => {
-      const id = eventTarget(event)?.dataset.timelineFocusId;
+      const id = timelineKeyboardEventTarget(event.target, event.currentTarget)?.dataset
+        .timelineFocusId;
       if (id && id !== focusedTargetId) usePlayerStore.getState().requestTimelineFocus(id);
     },
     // ponytail: This closure must see the current id or coordinator-driven focus bumps the nonce twice.
@@ -98,7 +177,7 @@ export function useTimelineKeyboardActor({
     // One handler owns navigation, context-menu, and disclosure keyboard semantics.
     // fallow-ignore-next-line complexity
     (event: KeyboardEvent<HTMLElement>) => {
-      const targetElement = eventTarget(event);
+      const targetElement = timelineKeyboardEventTarget(event.target, event.currentTarget);
       const id = targetElement?.dataset.timelineFocusId;
       if (!targetElement || !id) return;
       const located = locateTimelineLogicalTarget(logicalRows, id);

package/src/player/components/useTimelineProviderState.tsx

@@ -155,6 +155,7 @@ export function useTimelineProviderState({
     trackStyles,
     trackOrder,
     trackOrderRef,
+    trackInsertLayoutRef,
     laneCounts,
     rowGeometry,
     rowGeometryRef,
@@ -213,6 +214,7 @@ export function useTimelineProviderState({
     ppsRef,
     durationRef,
     trackOrderRef,
+    trackInsertLayoutRef,
     rowGeometryRef,
     onMoveElement: pinnedOnMoveElement,
     onMoveElements: pinnedOnMoveElements,
@@ -288,7 +290,7 @@ export function useTimelineProviderState({
     allowHorizontal: zoomMode === "manual",
     viewport,
     sessionEpoch,
-    draggedRowKey: draggedClip?.started ? draggedClip.previewTrack : undefined,
+    draggedRowKey: displayLayout.draggedRowKey,
     resizingElementIds,
     clipContextMenuRowKey: clipContextMenu?.element.track,
     keyframeContextMenuRowKey: kfContextMenu?.element.track,

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

@@ -0,0 +1,56 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it } from "vitest";
+import { createTimelineRowGeometry, type TimelineRowGeometry } from "./timelineLayout";
+import { useTimelineRowVirtualization } from "./useTimelineRowVirtualization";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+it("leaves the viewport still when a live preview lane is removed before the committed row arrives", () => {
+  const scroll = document.createElement("div");
+  scroll.scrollTop = 160;
+  const scrollRef = { current: scroll };
+  const lastScrollLeftRef = { current: 0 };
+  const host = document.createElement("div");
+  const root = createRoot(host);
+  const normal = createTimelineRowGeometry([0, 1, 2, 3, 4, 5], [48, 48, 48, 48, 48, 48]);
+  const preview = createTimelineRowGeometry([0, -1, 1, 2, 3, 4, 5], [48, 48, 48, 48, 48, 48, 48]);
+  const committed = createTimelineRowGeometry([0, 1, 2, 3, 4, 5, 6], [48, 48, 48, 48, 48, 48, 48]);
+  function Probe({
+    geometry,
+    draggedRowKey,
+  }: {
+    geometry: TimelineRowGeometry;
+    draggedRowKey?: number;
+  }) {
+    useTimelineRowVirtualization({
+      scrollRef,
+      rowGeometry: geometry,
+      draggedRowKey,
+      sessionEpoch: 0,
+      viewport: {
+        scrollTop: 160,
+        scrollLeft: 0,
+        clientWidth: 800,
+        clientHeight: 200,
+        scrollWidth: 800,
+        scrollHeight: 600,
+        isScrolling: false,
+      },
+      elements: [],
+      selectedElementId: null,
+      lastScrollLeftRef,
+      syncScrollViewport: () => {},
+    });
+    return null;
+  }
+  act(() => root.render(<Probe geometry={normal} />));
+  act(() => root.render(<Probe geometry={preview} draggedRowKey={-1} />));
+  expect(scroll.scrollTop).toBe(160);
+  act(() => root.render(<Probe geometry={normal} />));
+  expect(scroll.scrollTop).toBe(160);
+  act(() => root.render(<Probe geometry={committed} />));
+  expect(scroll.scrollTop).toBe(160);
+  act(() => root.unmount());
+});

package/src/player/components/useTimelineRowVirtualization.ts

@@ -103,6 +103,7 @@ export function useTimelineRowVirtualization({
   });
 
   const previousLayoutRef = useRef(rowGeometry);
+  const previousDraggedRowKeyRef = useRef(draggedRowKey);
   const previousSessionEpochRef = useRef(sessionEpoch);
   useLayoutEffect(() => {
     const scroll = scrollRef.current;
@@ -120,7 +121,7 @@ export function useTimelineRowVirtualization({
         previousGeometry,
         rowGeometry,
         scroll.scrollTop,
-        draggedRowKey !== undefined,
+        draggedRowKey !== undefined || previousDraggedRowKeyRef.current !== undefined,
       );
       if (nextScrollTop !== scroll.scrollTop) {
         scroll.scrollTop = nextScrollTop;
@@ -128,6 +129,7 @@ export function useTimelineRowVirtualization({
       }
     }
     previousLayoutRef.current = rowGeometry;
+    previousDraggedRowKeyRef.current = draggedRowKey;
   }, [draggedRowKey, lastScrollLeftRef, rowGeometry, scrollRef, sessionEpoch, syncScrollViewport]);
 
   return {

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

@@ -15,7 +15,7 @@ import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it } from "vitest";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
-import { useTimelineTrackDerivations } from "./useTimelineTrackDerivations";
+import { displayTrackOrder, useTimelineTrackDerivations } from "./useTimelineTrackDerivations";
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -100,4 +100,17 @@ describe("useTimelineTrackDerivations", () => {
     const { groups } = derive([clip("sfx-1", 0, { audioGroup: "sfx" })]);
     expect(groups[0]).toMatchObject({ id: "sfx", label: "sfx", volume: 1, hidden: false });
   });
+
+  it("gives hosts the drawn row order, members left out while their group is collapsed", () => {
+    const elements = [
+      clip("vo-1", 0, { audioGroup: "voiceover" }),
+      clip("music", 1),
+      clip("vo-2", 2, { audioGroup: "voiceover" }),
+    ];
+    expect(displayTrackOrder(elements, new Set())).toEqual(derive(elements).trackOrder);
+
+    usePlayerStore.setState({ collapsedGroupIds: new Set(["voiceover"]) });
+    expect(derive(elements).trackOrder).toEqual([-0.5, 1]);
+    expect(displayTrackOrder(elements, new Set(["voiceover"]))).toEqual([-0.5, 1]);
+  });
 });

package/src/player/components/useTimelineTrackDerivations.ts

@@ -170,12 +170,38 @@ function groupTimelineTracks(
   return { tracks, groups, trackGroupOf };
 }
 
+/** The timeline's rows top to bottom, as drawn: tracks by number, each audio group's anchor
+ *  row with its members under it. */
+function timelineDisplayTracks(
+  elements: readonly TimelineElement[],
+  collapsedGroupIds: ReadonlySet<string>,
+) {
+  const byTrack = new Map<number, TimelineElement[]>();
+  for (const el of elements) {
+    const list = byTrack.get(el.track) ?? [];
+    list.push(el);
+    byTrack.set(el.track, list);
+  }
+  const rawTracks = Array.from(byTrack.entries()).sort(([a], [b]) => a - b);
+  const grouped = groupTimelineTracks(rawTracks, collapsedGroupIds);
+  return { ...grouped, trackOrder: grouped.tracks.map(([trackNum]) => trackNum) };
+}
+
+/**
+ * The track number of each timeline row, top to bottom: pass the player store's `elements` and
+ * `collapsedGroupIds`. A group's anchor row is its first member's track minus 0.5.
+ */
+export function displayTrackOrder(
+  elements: readonly TimelineElement[],
+  collapsedGroupIds: ReadonlySet<string>,
+): number[] {
+  return timelineDisplayTracks(elements, collapsedGroupIds).trackOrder;
+}
+
 /**
  * Per-render track derivations Timeline.tsx feeds the canvas/lanes: the lane →
  * clip grouping (`tracks`, group-aware order), per-lane visual styles, the
- * matching `trackOrder`, and audio-group membership. Extracted from
- * Timeline.tsx as a cohesive unit (600-line studio cap); each memo keys on the
- * expanded display element set exactly as before.
+ * matching `trackOrder`, and audio-group membership.
  */
 export function useTimelineTrackDerivations(expandedElements: TimelineElement[]): {
   tracks: [number, TimelineElement[]][];
@@ -184,20 +210,10 @@ export function useTimelineTrackDerivations(expandedElements: TimelineElement[])
   groups: TimelineTrackGroupInfo[];
   trackGroupOf: Map<number, TimelineTrackGroupInfo>;
 } {
-  const rawTracks = useMemo(() => {
-    const map = new Map<number, TimelineElement[]>();
-    for (const el of expandedElements) {
-      const list = map.get(el.track) ?? [];
-      list.push(el);
-      map.set(el.track, list);
-    }
-    return Array.from(map.entries()).sort(([a], [b]) => a - b);
-  }, [expandedElements]);
-
   const collapsedGroupIds = usePlayerStore((s) => s.collapsedGroupIds);
-  const { tracks, groups, trackGroupOf } = useMemo(
-    () => groupTimelineTracks(rawTracks, collapsedGroupIds),
-    [rawTracks, collapsedGroupIds],
+  const { tracks, groups, trackGroupOf, trackOrder } = useMemo(
+    () => timelineDisplayTracks(expandedElements, collapsedGroupIds),
+    [expandedElements, collapsedGroupIds],
   );
 
   const trackStyles = useMemo(() => {
@@ -208,7 +224,5 @@ export function useTimelineTrackDerivations(expandedElements: TimelineElement[])
     return map;
   }, [tracks]);
 
-  const trackOrder = useMemo(() => tracks.map(([trackNum]) => trackNum), [tracks]);
-
   return { tracks, trackStyles, trackOrder, groups, trackGroupOf };
 }

package/src/player/components/useTimelineTrackLayout.ts

@@ -6,6 +6,7 @@ import { elementAutomationLanes, groupAutomationLanes } from "./automationLaneDa
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { DraggedClipState } from "./timelineClipDragTypes";
 import { useTimelineTrackDerivations } from "./useTimelineTrackDerivations";
+import { buildTimelineTrackInsertLayout } from "./timelineTrackInsertLayout";
 import {
   TRACK_H,
   createTimelineRowGeometry,
@@ -246,6 +247,12 @@ export function useTimelineTrackLayout(
     useTimelineTrackDerivations(expandedElements);
   const trackOrderRef = useRef(trackOrder);
   trackOrderRef.current = trackOrder;
+  const trackInsertLayout = useMemo(
+    () => (groups.length > 0 ? buildTimelineTrackInsertLayout(trackOrder, groups) : undefined),
+    [trackOrder, groups],
+  );
+  const trackInsertLayoutRef = useRef(trackInsertLayout);
+  trackInsertLayoutRef.current = trackInsertLayout;
   const { laneCounts, rowGeometry, rowGeometryRef, rowHeights } = useTimelineRowHeights(
     tracks,
     gsapAnimations,
@@ -260,6 +267,7 @@ export function useTimelineTrackLayout(
     trackStyles,
     trackOrder,
     trackOrderRef,
+    trackInsertLayoutRef,
     laneCounts,
     rowGeometry,
     rowGeometryRef,
@@ -283,27 +291,40 @@ function useDisplayRowHeights(
   );
 }
 
+function insertPreviewTrack(trackOrder: number[], preview: number) {
+  const result: number[] = [];
+  let inserted = false;
+  for (const key of trackOrder) {
+    if (!inserted && Number.isInteger(key) && key > preview) {
+      result.push(preview);
+      inserted = true;
+    }
+    result.push(key);
+  }
+  if (!inserted) result.push(preview);
+  return result;
+}
+
 function useDisplayTrackOrder(draggedClip: DraggedClipState | null, trackOrder: number[]) {
+  const started = draggedClip?.started === true;
+  const insertRow = draggedClip?.insertRow ?? null;
+  const previewTrack = draggedClip?.previewTrack;
   return useMemo(() => {
-    if (!draggedClip?.started || trackOrder.includes(draggedClip.previewTrack)) return trackOrder;
+    if (!started || previewTrack === undefined) return trackOrder;
+    if (insertRow !== null) {
+      const pendingKey = trackOrder.reduce((lowest, key) => Math.min(lowest, key), 0) - 1;
+      const displayOrder = [...trackOrder];
+      displayOrder.splice(insertRow, 0, pendingKey);
+      return displayOrder;
+    }
+    if (trackOrder.includes(previewTrack)) return trackOrder;
     // A group's members sit out of raw numeric order (pulled under their
     // anchor row), so a plain numeric sort here would undo that grouping the
     // moment a clip drags onto a brand-new track. Insert the new preview
     // track only relative to other REAL (integer) tracks, leaving any
     // fractional group-anchor keys exactly where grouping placed them.
-    const preview = draggedClip.previewTrack;
-    const result: number[] = [];
-    let inserted = false;
-    for (const key of trackOrder) {
-      if (!inserted && Number.isInteger(key) && key > preview) {
-        result.push(preview);
-        inserted = true;
-      }
-      result.push(key);
-    }
-    if (!inserted) result.push(preview);
-    return result;
-  }, [draggedClip, trackOrder]);
+    return insertPreviewTrack(trackOrder, previewTrack);
+  }, [started, insertRow, previewTrack, trackOrder]);
 }
 
 export function useTimelineDisplayLayout(
@@ -317,7 +338,15 @@ export function useTimelineDisplayLayout(
     () => createTimelineRowGeometry(displayTrackOrder, displayRowHeights, rowGeometry.padding),
     [displayTrackOrder, displayRowHeights, rowGeometry.padding],
   );
+  let draggedRowKey: number | undefined;
+  if (draggedClip?.started) {
+    draggedRowKey =
+      draggedClip.insertRow !== null
+        ? displayRowGeometry.rowKeys[draggedClip.insertRow]
+        : draggedClip.previewTrack;
+  }
   return {
+    draggedRowKey,
     displayTrackOrder,
     displayRowHeights: displayRowGeometry.rowHeights,
     rowGeometry: displayRowGeometry,