@hyperframes/studio 0.8.91 → 0.8.93

package/src/player/components/timelineMultiDragPreview.ts

@@ -1,3 +1,7 @@
+import type { TimelineElement } from "../store/playerStore";
+import { clampToHostStart } from "../store/timelineElement";
+import { canMoveTimelineElement } from "./timelineAuthoredMoveTarget";
+
 /**
  * Pure geometry for the LIVE multi-selection drag preview.
  *
@@ -9,11 +13,11 @@
  * behind individually — the whole formation moves by one delta, spacing locked.
  *
  * That single delta is the GRABBED clip's `draggedPreviewStart − draggedOriginStart`.
- * The preview start is ALREADY group-clamped upstream (updateDraggedClipPreview
- * runs clampGroupMoveDelta before setting it), so this delta is the clamped delta:
+ * The preview start is ALREADY group-clamped upstream (computeDragPreview floors it
+ * at groupMoveFloor), so this delta is the clamped delta:
  * the instant any member would cross 0 the grabbed clip stops and every passenger
  * stops with it — the formation never deforms. On DROP the commit shifts every
- * selected clip by this same delta (see timelineClipDragCommit / useTimelineClipDrag).
+ * moving clip (resolveGroupMovers) by this same delta (see timelineClipDragCommit).
  *
  * Track changes apply to the grabbed clip only (mirroring the commit); passengers
  * keep their lanes, so only their x moves.
@@ -81,29 +85,23 @@ export function multiDragPassengerOffsetPx(
   return multiDragDeltaSeconds(input) * pps;
 }
 
-/**
- * Clamp a group move so the WHOLE selection moves as ONE rigid formation.
- *
- * The grabbed clip proposes a raw delta (its desired preview start minus its
- * origin start, after its own snapping). Applied naively, a passenger could be
- * pushed below 0 (or past any other member bound), and the commit's per-clip
- * `Math.max(0, …)` would then deform the formation — the grabbed clip out-runs
- * the group while a passenger sticks at the wall. This ports main's model
- * (useTimelineClipGroupDrag / clampTimelineGroupMoveDelta): the applied delta is
- * bounded by the MOST-CONSTRAINED member, so the grabbed clip STOPS the instant
- * any member hits 0 and the formation never deforms.
- *
- * `memberStarts` are the pre-drag starts of every selected clip (the grabbed clip
- * included). Only the lower bound (start ≥ 0) constrains a move; the timeline has
- * no fixed right wall (the composition grows on commit).
- */
-export function clampGroupMoveDelta(
-  rawDelta: number,
-  members: readonly { start: number; minStart?: number }[],
+/** The selected clips a group drag moves: a locked clip swept into the selection stays put.
+ *  Null when the grabbed clip is not part of a multi-selection. */
+export function resolveGroupMovers(
+  elements: readonly TimelineElement[],
+  selectedKeys: ReadonlySet<string> | null | undefined,
+  dragKey: string,
+): TimelineElement[] | null {
+  if (!selectedKeys || selectedKeys.size <= 1 || !selectedKeys.has(dragKey)) return null;
+  return elements.filter((e) => selectedKeys.has(e.key ?? e.id) && canMoveTimelineElement(e));
+}
+
+/** The lowest start the grabbed clip may take so the whole group moves rigidly and no clip
+ *  crosses its own floor, its host composition's start (the commit floors each one there). */
+export function groupMoveFloor(
+  grabbed: TimelineElement,
+  movers: readonly TimelineElement[],
 ): number {
-  if (members.length === 0) return rawDelta;
-  // The member nearest its own floor bounds the move: delta ≥ -(start - minStart) for each.
-  const room = Math.min(...members.map((m) => m.start - (m.minStart ?? 0)));
-  const minDelta = room === 0 ? 0 : -room; // avoid -0
-  return rawDelta < minDelta ? minDelta : rawDelta;
+  const room = Math.min(...[grabbed, ...movers].map((e) => e.start - clampToHostStart(e, 0)));
+  return grabbed.start - room;
 }

package/src/player/components/timelineProviderStateBuilders.ts

@@ -5,23 +5,26 @@ import type {
 } from "./TimelineProvider";
 import type { ResizingClipState } from "./useTimelineClipDrag";
 import type { DraggedClipState } from "./timelineClipDragTypes";
-import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
+import { resolveGroupMovers, type MultiDragPreviewInput } from "./timelineMultiDragPreview";
 import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
+import type { TimelineElement } from "../store/playerStore";
 
 export function resolveMultiDragPreview(
   draggedClip: DraggedClipState | null,
   selectedKeys: ReadonlySet<string>,
+  elements: readonly TimelineElement[],
 ): MultiDragPreviewInput | null {
-  // The dragged clip is a free ghost; selected companions follow the same
-  // clamped delta so the formation stays rigid at the lane boundary.
+  // The dragged clip is a free ghost; the clips that move with it follow the same
+  // clamped delta so the formation stays rigid. A locked selected clip stays put.
   if (!draggedClip?.started) return null;
   const draggedKey = getTimelineElementIdentity(draggedClip.element);
+  const movers = resolveGroupMovers(elements, selectedKeys, draggedKey);
   return {
     dragStarted: true,
     draggedKey,
     draggedOriginStart: draggedClip.element.start,
     draggedPreviewStart: draggedClip.previewStart,
-    selectedKeys,
+    selectedKeys: movers ? new Set(movers.map(getTimelineElementIdentity)) : selectedKeys,
   };
 }
 

package/src/player/components/timelineShellMeta.tsx

@@ -0,0 +1,99 @@
+import type { MutableRefObject, PointerEvent } from "react";
+import type {
+  TimelineContainerProps,
+  TimelineMeta,
+  TimelineViewportProps,
+} from "./TimelineProvider";
+import {
+  buildTimelineMeta,
+  shouldIgnoreTimelinePointerDown,
+} from "./timelineProviderStateBuilders";
+import { TimelineRazorGuideOverlay } from "./TimelineRazorInteraction";
+import { LABEL_COL_W } from "./timelineLayout";
+import type { TimelineTheme } from "./timelineTheme";
+
+type ViewportHandlers = Pick<
+  TimelineViewportProps,
+  "onDragOver" | "onDragLeave" | "onDrop" | "onPointerMove" | "onPointerUp" | "onPointerCancel"
+>;
+
+export interface TimelineShellMetaInputs {
+  isDragOver: boolean;
+  hasFileDrop: boolean;
+  drop: Pick<ViewportHandlers, "onDragOver" | "onDragLeave" | "onDrop">;
+  pointer: Pick<ViewportHandlers, "onPointerMove" | "onPointerUp" | "onPointerCancel"> & {
+    onPointerDown: TimelineViewportProps["onPointerDown"];
+  };
+  setContainerRef: TimelineContainerProps["ref"];
+  setScrollRef: TimelineViewportProps["ref"];
+  focusProps: Pick<TimelineViewportProps, "onFocus" | "onBlur">;
+  elementCount: number;
+  activeTool: string;
+  shiftHeld: boolean;
+  labelMode: boolean;
+  contentOrigin: number;
+  zoomMode: "fit" | "manual";
+  theme: Pick<TimelineTheme, "shellBackground" | "shellBorder">;
+  razor: {
+    razorGuideX: number | null;
+    updateRazorGuide: TimelineContainerProps["onMouseMove"];
+    clearRazorGuide: () => void;
+    splitAllAtPointer: (event: PointerEvent<HTMLDivElement>) => boolean;
+  };
+  lastScrollLeftRef: MutableRefObject<number>;
+  recordTimelineScroll: (scroll: HTMLDivElement) => void;
+  syncScrollViewport: (scroll: HTMLDivElement, isScrolling?: boolean) => void;
+}
+
+/** The timeline shell's container and scroll viewport props: drop, pointer, scroll and razor wiring. */
+export function buildTimelineShellMeta(input: TimelineShellMetaInputs): TimelineMeta {
+  const { drop, pointer, razor, theme, activeTool } = input;
+  return buildTimelineMeta({
+    emptyState: { isDragOver: input.isDragOver, onFileDrop: input.hasFileDrop, ...drop },
+    container: {
+      ref: input.setContainerRef,
+      "aria-label": "Timeline track view",
+      "data-timeline-element-count": input.elementCount,
+      isDragOver: input.isDragOver,
+      activeTool,
+      shiftHeld: input.shiftHeld,
+      accentClass: "ring-1 ring-inset ring-studio-accent/60",
+      onMouseMove: razor.updateRazorGuide,
+      onMouseLeave: razor.clearRazorGuide,
+      style: {
+        touchAction: "pan-x pan-y",
+        background: theme.shellBackground,
+        borderColor: theme.shellBorder,
+      },
+    },
+    viewport: {
+      ref: input.setScrollRef,
+      tabIndex: -1,
+      labelMode: input.labelMode,
+      contentOrigin: input.contentOrigin,
+      zoomMode: input.zoomMode,
+      onScroll: (e) => {
+        input.lastScrollLeftRef.current = e.currentTarget.scrollLeft;
+        input.recordTimelineScroll(e.currentTarget);
+        input.syncScrollViewport(e.currentTarget, true);
+      },
+      ...input.focusProps,
+      ...drop,
+      onPointerDown: (e) => {
+        if (shouldIgnoreTimelinePointerDown(e.target)) return;
+        if (razor.splitAllAtPointer(e)) return;
+        pointer.onPointerDown(e);
+      },
+      onPointerMove: pointer.onPointerMove,
+      onPointerUp: pointer.onPointerUp,
+      onPointerCancel: pointer.onPointerCancel,
+      onLostPointerCapture: pointer.onPointerCancel,
+    },
+    elementCount: input.elementCount,
+    labelColumnWidth: LABEL_COL_W,
+    razorGuide:
+      activeTool === "razor" && razor.razorGuideX !== null ? (
+        <TimelineRazorGuideOverlay x={razor.razorGuideX} />
+      ) : null,
+  });
+}

package/src/player/components/useTimelineDragPreviewState.ts

@@ -0,0 +1,34 @@
+import { useCallback, useMemo } from "react";
+import type { TimelineElement } from "../store/playerStore";
+import type { DraggedClipState } from "./timelineClipDragTypes";
+import type { ResizingClipState } from "./useTimelineClipDrag";
+import {
+  resolveMultiDragPreview,
+  resolveResizingElementIds,
+} from "./timelineProviderStateBuilders";
+import { getTimelinePreviewElement } from "./timelineViewModel";
+import { resolveSnapGuide } from "./timelineSnapping";
+
+/** What the lanes draw for a live move or trim: the ghost, the clips riding along, the snap guide. */
+export function useTimelineDragPreviewState(
+  draggedClip: DraggedClipState | null,
+  resizingClip: ResizingClipState | null,
+  selectedElementIds: ReadonlySet<string>,
+  timelineElements: readonly TimelineElement[],
+) {
+  const getPreviewElement = useCallback(
+    (element: TimelineElement): TimelineElement => getTimelinePreviewElement(element, resizingClip),
+    [resizingClip],
+  );
+  const multiDragPreview = useMemo(
+    () => resolveMultiDragPreview(draggedClip, selectedElementIds, timelineElements),
+    [draggedClip, selectedElementIds, timelineElements],
+  );
+  return {
+    resizingElementIds: resolveResizingElementIds(resizingClip),
+    getPreviewElement,
+    draggedElement: draggedClip?.element ?? null,
+    multiDragPreview,
+    snapGuide: resolveSnapGuide(draggedClip, resizingClip),
+  };
+}

package/src/player/components/useTimelineProviderState.tsx

@@ -1,6 +1,6 @@
 import { useRef, useMemo, useCallback, useState } from "react";
 import { useAdjustedBeatAnalysis, useMusicBeatAnalysis } from "../../hooks/useMusicBeatAnalysis";
-import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { usePlayerStore } from "../store/playerStore";
 import { defaultTimelineTheme } from "./timelineTheme";
 import { useTimelinePlayhead } from "./useTimelinePlayhead";
 import { useTimelineZoom } from "./useTimelineZoom";
@@ -8,18 +8,14 @@ import { useTimelineAssetDrop } from "./timelineDragDrop";
 import { type KeyframeDiamondContextMenuState } from "./KeyframeDiamondContextMenu";
 import { useTimelineClipDrag } from "./useTimelineClipDrag";
 import type { ClipContextMenuState, TimelineContextValue } from "./TimelineProvider";
-import {
-  buildTimelineMeta,
-  resolveMultiDragPreview,
-  resolveResizingElementIds,
-  shouldIgnoreTimelinePointerDown,
-} from "./timelineProviderStateBuilders";
+import { buildTimelineShellMeta } from "./timelineShellMeta";
+import { useTimelineDragPreviewState } from "./useTimelineDragPreviewState";
 import { useTimelineOverlaysState } from "./useTimelineOverlaysState";
 import { useTimelineEditPinning } from "./useTimelineEditPinning";
 import { useTimelineStackingSync } from "./useTimelineStackingSync";
 import { useTimelineGeometry } from "./useTimelineGeometry";
 import { useAutoExpandKeyframedClips } from "./useAutoExpandKeyframedClips";
-import { GUTTER, LABEL_COL_W } from "./timelineLayout";
+import { GUTTER } from "./timelineLayout";
 import { useTimelineLabelColumn } from "./useTimelineLabelColumn";
 import { useTimelineKeyframeData } from "./useTimelineKeyframeData";
 import { useTimelineScrollViewport } from "./useTimelineScrollViewport";
@@ -33,9 +29,9 @@ import {
 } from "./useTimelineTrackLayout";
 import { useTimelineKeyframeHandlers } from "./useTimelineKeyframeHandlers";
 import { useTimelineGapHighlights } from "./useTimelineGapHighlights";
-import { TimelineRazorGuideOverlay, useTimelineRazorInteraction } from "./TimelineRazorInteraction";
+import { useTimelineRazorInteraction } from "./TimelineRazorInteraction";
 import { useTimelinePerformanceTelemetry } from "./useTimelinePerformanceTelemetry";
-import { getEffectiveTimelineDuration, getTimelinePreviewElement } from "./timelineViewModel";
+import { getEffectiveTimelineDuration } from "./timelineViewModel";
 import { useTimelineShiftModifier } from "./useTimelineShiftModifier";
 import { useTimelineTicks } from "./useTimelineTicks";
 import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
@@ -44,7 +40,6 @@ import { useTimelineActiveClips } from "./useTimelineActiveClips";
 import { useTimelineLaneMoveRefresh } from "./useTimelineLaneMoveRefresh";
 import { useTimelineLogicalFocus } from "./useTimelineLogicalFocus";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
-import { resolveSnapGuide } from "./timelineSnapping";
 export function useTimelineProviderState({
   onSeek,
   onDrillDown,
@@ -107,8 +102,7 @@ export function useTimelineProviderState({
   const selectedElementIds = usePlayerStore((s) => s.selectedElementIds);
   const focusedEaseSegment = usePlayerStore((s) => s.focusedEaseSegment);
   const { gsapAnimations, keyframeCache } = useTimelineKeyframeData(showKeyframes);
-  const namedAnimations = usePlayerStore((s) => s.gsapAnimations);
-  const { labelMode, contentOrigin } = useTimelineLabelColumn(namedAnimations, timelineElements);
+  const { labelMode, contentOrigin } = useTimelineLabelColumn(gsapAnimations, timelineElements);
   const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
   const currentTime = usePlayerStore((s) => s.currentTime);
   const beatDragging = usePlayerStore((s) => s.beatDragging);
@@ -223,7 +217,8 @@ export function useTimelineProviderState({
     sessionEpoch,
   });
   const displayLayout = useTimelineDisplayLayout(draggedClip, trackOrder, rowGeometry);
-  const resizingElementIds = resolveResizingElementIds(resizingClip);
+  const { resizingElementIds, getPreviewElement, draggedElement, multiDragPreview, snapGuide } =
+    useTimelineDragPreviewState(draggedClip, resizingClip, selectedElementIds, timelineElements);
   const { recordTimelineScroll } = useTimelinePerformanceTelemetry({
     totalClipCount: timelineElements.length,
     totalRowCount: displayLayout.displayTrackOrder.length,
@@ -422,12 +417,6 @@ export function useTimelineProviderState({
     timeDisplayMode,
     timelineFocus.rowVirtualizationActive ? renderTimeRange : undefined,
   );
-  const getPreviewElement = useCallback(
-    (element: TimelineElement): TimelineElement => getTimelinePreviewElement(element, resizingClip),
-    [resizingClip],
-  );
-  const draggedElement = draggedClip?.element ?? null;
-  const multiDragPreview = resolveMultiDragPreview(draggedClip, selectedElementIds);
   const canvasProps = {
     major,
     minor,
@@ -502,7 +491,7 @@ export function useTimelineProviderState({
     onMoveElement,
     beatDragging,
     draggedElement,
-    snapGuide: resolveSnapGuide(draggedClip, resizingClip),
+    snapGuide,
     multiDragPreview,
     onToggleTrackHidden: editContext.onToggleTrackHidden,
     onTogglePropertyGroupKeyframe: editContext.onTogglePropertyGroupKeyframe,
@@ -520,61 +509,34 @@ export function useTimelineProviderState({
       )),
     [holdNewClipContent, renderClipContent],
   );
-  const timelineMeta = buildTimelineMeta({
-    emptyState: {
-      isDragOver: assetDrop.isDragOver,
-      onFileDrop: !!onFileDrop,
+  const timelineMeta = buildTimelineShellMeta({
+    isDragOver: assetDrop.isDragOver,
+    hasFileDrop: !!onFileDrop,
+    drop: {
       onDragOver: assetDrop.handleAssetDragOver,
       onDragLeave: assetDrop.handleAssetDragLeave,
       onDrop: assetDrop.handleAssetDrop,
     },
-    container: {
-      ref: setContainerRef,
-      "aria-label": "Timeline track view",
-      "data-timeline-element-count": timelineElements.length,
-      isDragOver: assetDrop.isDragOver,
-      activeTool,
-      shiftHeld,
-      accentClass: "ring-1 ring-inset ring-studio-accent/60",
-      onMouseMove: updateRazorGuide,
-      onMouseLeave: clearRazorGuide,
-      style: {
-        touchAction: "pan-x pan-y",
-        background: theme.shellBackground,
-        borderColor: theme.shellBorder,
-      },
-    },
-    viewport: {
-      ref: setScrollRef,
-      tabIndex: -1,
-      labelMode,
-      contentOrigin,
-      zoomMode,
-      onScroll: (e) => {
-        lastScrollLeftRef.current = e.currentTarget.scrollLeft;
-        recordTimelineScroll(e.currentTarget);
-        syncScrollViewport(e.currentTarget, true);
-      },
-      ...timelineFocus.timelineFocusProps,
-      onDragOver: assetDrop.handleAssetDragOver,
-      onDragLeave: assetDrop.handleAssetDragLeave,
-      onDrop: assetDrop.handleAssetDrop,
-      onPointerDown: (e) => {
-        if (shouldIgnoreTimelinePointerDown(e.target)) return;
-        if (splitAllAtPointer(e)) return;
-        handlePointerDown(e);
-      },
+    pointer: {
+      onPointerDown: handlePointerDown,
       onPointerMove: handlePointerMove,
       onPointerUp: handlePointerUp,
       onPointerCancel: handlePointerCancel,
-      onLostPointerCapture: handlePointerCancel,
     },
+    setContainerRef,
+    setScrollRef,
+    focusProps: timelineFocus.timelineFocusProps,
     elementCount: timelineElements.length,
-    labelColumnWidth: LABEL_COL_W,
-    razorGuide:
-      activeTool === "razor" && razorGuideX !== null ? (
-        <TimelineRazorGuideOverlay x={razorGuideX} />
-      ) : null,
+    activeTool,
+    shiftHeld,
+    labelMode,
+    contentOrigin,
+    zoomMode,
+    theme,
+    razor: { razorGuideX, updateRazorGuide, clearRazorGuide, splitAllAtPointer },
+    lastScrollLeftRef,
+    recordTimelineScroll,
+    syncScrollViewport,
   });
   const contextValue: TimelineContextValue = {
     state: {

package/src/player/hooks/useTimelinePlayer.seek.test.ts

@@ -353,7 +353,11 @@ describe("useTimelinePlayer seek keepPlaying option (#834)", () => {
 describe("useTimelinePlayer RAF loop wrap-around", () => {
   type SeekCall = { time: number; options?: { keepPlaying?: boolean } };
 
-  function attachInstrumentedAdapter(api: ReturnType<typeof useTimelinePlayer>, duration = 30) {
+  function attachInstrumentedAdapter(
+    api: ReturnType<typeof useTimelinePlayer>,
+    duration = 30,
+    hooks: object = {},
+  ) {
     let currentTime = 0;
     let playing = false;
     const seekCalls: SeekCall[] = [];
@@ -377,6 +381,7 @@ describe("useTimelinePlayer RAF loop wrap-around", () => {
     };
     attachIframeWindow(api, {
       __player: adapter,
+      __hf: hooks,
       postMessage: () => {},
       scrollTo: () => {},
       addEventListener: () => {},
@@ -446,6 +451,29 @@ describe("useTimelinePlayer RAF loop wrap-around", () => {
     }
   });
 
+  it("tells the preview where the loop wraps to while it plays, and that it stopped looping", () => {
+    const raf = installRafCapture();
+    try {
+      const { api, root } = renderTimelinePlayerHarness();
+      const setLoopStart = vi.fn();
+      const { adapter } = attachInstrumentedAdapter(api, 30, { setLoopStart });
+      act(() => {
+        usePlayerStore.getState().setInPoint(2);
+        usePlayerStore.getState().setOutPoint(5);
+        api.play();
+      });
+      adapter.setTime(3);
+      act(() => void raf.flushOne());
+      expect(setLoopStart).toHaveBeenLastCalledWith(2);
+      act(() => usePlayerStore.getState().setLoopEnabled(false));
+      act(() => void raf.flushOne());
+      expect(setLoopStart).toHaveBeenLastCalledWith(null);
+      unmountWithAct(root);
+    } finally {
+      raf.restore();
+    }
+  });
+
   it("does not seek and pauses cleanly when forward playback reaches the end without loop", () => {
     const raf = installRafCapture();
     try {

package/src/player/hooks/useTimelinePlayer.ts

@@ -152,12 +152,18 @@ export function useTimelinePlayer({
     [],
   );
 
+  const setLoopStart = useCallback((seconds: number | null) => {
+    try {
+      (iframeRef.current?.contentWindow as IframeWindow | null)?.__hf?.setLoopStart?.(seconds);
+    } catch {}
+  }, []);
   const { startRAFLoop, stopRAFLoop, stopReverseLoop } = useTimelinePlayerLoop({
     rafRef,
     reverseRafRef,
     getAdapter,
     setCurrentTime,
     setIsPlaying,
+    setLoopStart,
   });
 
   const applyPlaybackRate = useCallback((rate: number) => {

package/src/player/hooks/useTimelinePlayerLoop.ts

@@ -22,6 +22,7 @@ interface UseTimelinePlayerLoopParams {
   getAdapter: () => PlaybackAdapter | null;
   setCurrentTime: (v: number) => void;
   setIsPlaying: (v: boolean) => void;
+  setLoopStart: (seconds: number | null) => void;
 }
 
 interface UseTimelinePlayerLoopResult {
@@ -36,6 +37,7 @@ export function useTimelinePlayerLoop({
   getAdapter,
   setCurrentTime,
   setIsPlaying,
+  setLoopStart,
 }: UseTimelinePlayerLoopParams): UseTimelinePlayerLoopResult {
   const stopReverseLoop = useCallback(() => {
     cancelAnimationFrame(reverseRafRef.current);
@@ -55,8 +57,10 @@ export function useTimelinePlayerLoop({
         const rawLoopStart = inPoint !== null ? inPoint : 0;
         const loopEnd = rawLoopStart < rawLoopEnd ? rawLoopEnd : dur;
         const loopStart = rawLoopStart < rawLoopEnd ? rawLoopStart : 0;
+        const looping = usePlayerStore.getState().loopEnabled && dur > 0;
+        setLoopStart(looping ? loopStart : null);
         if (time >= loopEnd) {
-          if (usePlayerStore.getState().loopEnabled && dur > 0) {
+          if (looping) {
             // keepPlaying skips the adapter's implicit pause; play() below is then a no-op.
             adapter.seek(loopStart, { keepPlaying: true });
             liveTime.notify(loopStart);
@@ -75,7 +79,7 @@ export function useTimelinePlayerLoop({
       rafRef.current = requestAnimationFrame(tick);
     };
     rafRef.current = requestAnimationFrame(tick);
-  }, [rafRef, getAdapter, setCurrentTime, setIsPlaying]);
+  }, [rafRef, getAdapter, setCurrentTime, setIsPlaying, setLoopStart]);
 
   const stopRAFLoop = useCallback(() => {
     cancelAnimationFrame(rafRef.current);

package/src/player/lib/playbackTypes.ts

@@ -69,5 +69,6 @@ export type IframeWindow = Window & {
   __hf?: {
     leasePausedMedia?: (el: HTMLMediaElement) => void;
     releasePausedMedia?: (el: HTMLMediaElement) => void;
+    setLoopStart?: (seconds: number | null) => void;
   };
 };

package/src/utils/timelineDropTrackInsert.test.ts

@@ -99,6 +99,54 @@ describe("applyTrackRenumbers", () => {
 });
 
 describe("resolveDropTrack", () => {
+  // Title shows on row 0; Music is written on track 0 too but shows on audio row 1.
+  const shown = (
+    id: string,
+    tag: string,
+    row: number,
+    track: number,
+    start: number,
+    length: number,
+  ) => ({
+    ...clip(id, row, start),
+    tag,
+    duration: length,
+    authoredTrack: track,
+  });
+  const title = shown("title", "div", 0, 0, 0, 10);
+  const music = shown("music", "audio", 1, 0, 2, 3);
+  const song = { id: "song", tag: "audio", start: 2, duration: 3 };
+  const drop = (elements: TimelineElement[], row: number, dropped = song) =>
+    resolveDropTrack({ source, elements, placement: { track: row }, dropped });
+
+  it("joins an audio row's file track at the nearest free time, not a new track", () => {
+    expect(drop([title, music], 1)).toMatchObject({ track: 0, start: 5 });
+  });
+
+  it("keeps an audio file dropped on a visual row off the audio clip on the track it is written to", () => {
+    expect(drop([title, music], 0)).toMatchObject({ track: 0, start: 5 });
+  });
+
+  it("writes a drop on a shown row to that row's file track and checks the clips there", () => {
+    const top = shown("top", "div", 0, 0, 0, 4);
+    const lower = shown("lower", "div", 1, 2, 0, 4); // file track 2, shown as row 1
+    const image = { id: "image", tag: "img", start: 1, duration: 3 };
+    expect(drop([top, lower], 1, image)).toMatchObject({ track: 2, start: 4 });
+  });
+
+  it("lets only clips of the dropped file's kind block it on the row", () => {
+    const title = clip("title", 0, 0);
+    const music = { ...clip("music", 0, 0), tag: "audio" };
+    const song = { id: "song", tag: "audio", start: 1, duration: 3 };
+    // An audio file shows in the audio rows wherever it is written, so a visual clip never blocks it.
+    expect(
+      resolveDropTrack({ source, elements: [title], placement: { track: 0 }, dropped: song }).start,
+    ).toBe(1);
+    expect(
+      resolveDropTrack({ source, elements: [music], placement: { track: 0 }, dropped: song }).start,
+    ).toBe(2);
+  });
+
   it("keeps the aimed lane and the source when no insert is asked for", () => {
     const out = resolveDropTrack({
       source,
@@ -106,7 +154,17 @@ describe("resolveDropTrack", () => {
       placement: { track: 2 },
       dropped,
     });
-    expect(out).toEqual({ source, track: 2 });
+    expect(out).toEqual({ source, track: 2, start: 5 });
+  });
+
+  it("moves a drop on an occupied row to that row's nearest free time, with no new track", () => {
+    const out = resolveDropTrack({
+      source,
+      elements,
+      placement: { track: 1 },
+      dropped: { ...dropped, start: 1 },
+    });
+    expect(out).toEqual({ source, track: 1, start: 2 });
   });
 
   it("returns the new lane and the source with the lanes below pushed down", () => {
@@ -117,6 +175,7 @@ describe("resolveDropTrack", () => {
       dropped,
     });
     expect(out.track).toBe(1);
+    expect(out.start).toBe(5);
     expect(out.source).toContain('id="b" data-start="0" data-track-index="2"');
   });
 

package/src/utils/timelineDropTrackInsert.ts

@@ -1,6 +1,9 @@
 import type { TimelineElement } from "../player";
 import { layoutAfterTrackInsert } from "../player/components/timelineDragLanding";
 import { canMoveTimelineElement } from "../player/components/timelineAuthoredMoveTarget";
+import { resolveNearestFreeStart } from "../player/components/timelineCollision";
+import { authoredTrackForLane } from "../player/components/timelineAuthoredTrack";
+import { isAudioTimelineElement } from "./timelineInspector";
 import type { TimelineDropPlacement } from "../player/components/timelineCallbacks";
 import { applyPatchByTarget, readAttributeByTarget } from "./sourcePatcher";
 import { buildPatchTarget } from "../hooks/timelineEditingHelpers";
@@ -67,17 +70,45 @@ export function applyTrackRenumbers(source: string, plan: DropTrackInsertPlan):
   return out;
 }
 
-/** The lane a dropped clip is written on and the source with any lanes pushed down to make room. */
+type DroppedClip = Pick<TimelineElement, "id" | "tag" | "start" | "duration">;
+
+/** The file track a drop on display row `lane` is written to, and its nearest free start there.
+ *  The timeline's own clips decide the track; `placed` clips only block, like same-kind clips there. */
+function resolveRowDrop(
+  elements: TimelineElement[],
+  placed: readonly TimelineElement[],
+  lane: number,
+  dropped: DroppedClip,
+): { track: number; start: number } {
+  const audio = isAudioTimelineElement(dropped);
+  const row = elements.filter((e) => e.track === lane);
+  const otherKindRow = row.length > 0 && !row.some((e) => isAudioTimelineElement(e) === audio);
+  const asClip = { ...dropped, key: dropped.id, track: lane, sourceFile: elements[0]?.sourceFile };
+  const track = otherKindRow ? lane : authoredTrackForLane(lane, elements, asClip);
+  const onTrack = [...elements, ...placed]
+    .filter((e) => isAudioTimelineElement(e) === audio && (e.authoredTrack ?? e.track) === track)
+    .map((e) => ({ ...e, track }));
+  return {
+    track,
+    start: resolveNearestFreeStart(onTrack, track, dropped.start, dropped.duration, null),
+  };
+}
+
+/** Where a dropped clip is written: the aimed row's file track at its nearest free time, or a new track. */
 export function resolveDropTrack(input: {
   source: string;
   elements: TimelineElement[];
+  /** Clips this drop gesture already wrote, which `elements` does not hold yet. */
+  placed?: readonly TimelineElement[];
   placement: TimelineDropPlacement;
-  dropped: Pick<TimelineElement, "id" | "tag" | "start" | "duration">;
-}): { source: string; track: number } {
+  dropped: DroppedClip;
+}): { source: string; track: number; start: number } {
   const { source, elements, placement, dropped } = input;
-  if (placement.insertRow == null) return { source, track: placement.track };
+  if (placement.insertRow == null) {
+    return { source, ...resolveRowDrop(elements, input.placed ?? [], placement.track, dropped) };
+  }
   const { insertRow, trackOrder } = placement;
   const plan = planDropTrackInsert({ elements, trackOrder, insertRow, dropped });
   if (!plan) throw new Error("Cannot open a new track here: a locked clip would have to move.");
-  return { source: applyTrackRenumbers(source, plan), track: plan.track };
+  return { source: applyTrackRenumbers(source, plan), track: plan.track, start: dropped.start };
 }