@hyperframes/studio 0.7.54 → 0.7.56

package/src/player/components/timelineCollision.ts

@@ -0,0 +1,263 @@
+import type { TimelineElement } from "../store/playerStore";
+
+/**
+ * Keep a landing track inside the dragged clip's kind-zone: visual clips stay in
+ * the rows ABOVE the first audio lane; audio clips stay AT/BELOW it. Prevents a
+ * clip from appearing to land in the wrong zone mid-drag (which normalizeToZones
+ * would then snap back). `audioRow` = index in `trackOrder` of the first audio
+ * lane, or -1 when there is no audio zone yet (then it's a no-op).
+ */
+export function clampTrackToZone(
+  targetTrack: number,
+  trackOrder: number[],
+  audioRow: number,
+  isAudio: boolean,
+): number {
+  if (audioRow < 0) return targetTrack;
+  const row = trackOrder.indexOf(targetTrack);
+  if (row < 0) return targetTrack;
+  if (isAudio) return row >= audioRow ? targetTrack : (trackOrder[audioRow] ?? targetTrack);
+  return row < audioRow ? targetTrack : (trackOrder[audioRow - 1] ?? targetTrack);
+}
+
+/**
+ * Whether a new-track insert at boundary `insertRow` is allowed for a clip of the
+ * given kind. Visual clips may only insert visual lanes (boundary at/above the top
+ * of the audio zone); audio clips may only insert audio lanes (boundary at/below
+ * it) — so audio clips CAN create a new audio track, and neither kind inserts into
+ * the other's zone. `audioRow` = first audio lane row, or -1 (no audio zone) → any.
+ */
+export function isInsertAllowedForZone(
+  insertRow: number,
+  audioRow: number,
+  isAudio: boolean,
+): boolean {
+  if (audioRow < 0) return true;
+  return isAudio ? insertRow >= audioRow : insertRow <= audioRow;
+}
+
+/**
+ * The full drop-placement decision for a dragged clip — one pure, testable unit.
+ * Enforces: NO time-overlap on a single track; a clip stays in its kind-zone;
+ * a new track is created only when needed. Order of resolution:
+ *   1. Deliberate boundary insert (pointer near a lane edge), if it's in the
+ *      clip's own zone → create a new track there.
+ *   2. Otherwise land on a lane: clamp the aimed track to the clip's zone, take it
+ *      if free at [start, start+duration), else the nearest FREE lane in the zone
+ *      (prefer up), else auto-create a new track right below the aimed lane.
+ * `audioTracks` = the set of track indices that currently hold audio (so the fn
+ * needs no element-kind import). Returns the landing `track` and, when a new track
+ * should be created, the `insertRow` boundary (else null).
+ *
+ * `preferInsertAbove` biases the auto-created track (occupied-aim → new adjacent
+ * track) toward the boundary ABOVE the aimed row instead of below it, so the new
+ * lane opens on whichever side of the aimed clip the pointer is nearer (the drag
+ * preview passes the pointer's sub-row half). A clip whose aimed span is occupied
+ * never snaps back to its origin — it relocates to a free lane, or (none free)
+ * gets a fresh track next to the aim. Default (below) preserves prior behaviour.
+ */
+/**
+ * Insert-row boundary for an out-of-range aim — a `desired` track that isn't a
+ * real lane: the sentinel minTrack-1 an upward create-drag emits (#2214-adjacent
+ * repro) or a beyond-the-bottom index a downward one does. Anchors the new track
+ * to a boundary of the clip's OWN kind-zone so a visual insert can never land
+ * past the audio zone (the old below = order.length fallback dropped it BELOW the
+ * audio lanes). Above the zone (`desired` < the zone's min lane) → the zone's TOP
+ * boundary; otherwise → its BOTTOM boundary (for a visual clip, the top of the
+ * audio zone). `zoneTracks` = this kind's lanes, in `order` sequence.
+ */
+function outOfRangeZoneInsertRow(
+  order: number[],
+  zoneTracks: number[],
+  audioRow: number,
+  desired: number,
+): number {
+  // No lane of this kind yet: fall to the split (audioRow) or the very top.
+  // A visual-only timeline has audioRow -1 (top); an all-audio one has it at 0.
+  if (zoneTracks.length === 0) return audioRow < 0 ? 0 : audioRow;
+  // zoneTracks preserves `order` sequence, so its ends map to the zone boundary
+  // rows: above the zone's min lane → its top boundary, else its bottom.
+  const zoneTop = order.indexOf(zoneTracks[0]);
+  const zoneBottom = order.indexOf(zoneTracks[zoneTracks.length - 1]) + 1;
+  return desired < Math.min(...zoneTracks) ? zoneTop : zoneBottom;
+}
+
+export function resolveZoneDropPlacement(input: {
+  order: number[];
+  audioTracks: ReadonlySet<number>;
+  elements: TimelineElement[];
+  desiredTrack: number;
+  deliberateInsertRow: number | null;
+  start: number;
+  duration: number;
+  dragKey: string;
+  isAudio: boolean;
+  preferInsertAbove?: boolean;
+}): { track: number; insertRow: number | null } {
+  const { order, audioTracks, elements, desiredTrack, deliberateInsertRow } = input;
+  const { start, duration, dragKey, isAudio, preferInsertAbove } = input;
+  const audioRow = order.findIndex((t) => audioTracks.has(t));
+
+  if (
+    deliberateInsertRow !== null &&
+    isInsertAllowedForZone(deliberateInsertRow, audioRow, isAudio)
+  ) {
+    return { track: desiredTrack, insertRow: deliberateInsertRow };
+  }
+
+  const desired = clampTrackToZone(desiredTrack, order, audioRow, isAudio);
+  const zoneTracks = order.filter((t) => audioTracks.has(t) === isAudio);
+  const placement = resolvePlacement({
+    elements,
+    desiredTrack: desired,
+    start,
+    duration,
+    trackOrder: zoneTracks,
+    excludeKey: dragKey,
+  });
+  if (placement.needsInsert) {
+    const desiredRow = order.indexOf(desired);
+    if (desiredRow < 0) {
+      return {
+        track: desired,
+        insertRow: outOfRangeZoneInsertRow(order, zoneTracks, audioRow, desired),
+      };
+    }
+    // Prefer the gap NEAREST the pointer: insert above the aimed row when the
+    // pointer sits in its upper half AND that boundary is in the clip's own zone
+    // (else the visual/audio split would be crossed) — otherwise fall to below.
+    // `desired` is clamped into the zone, so both boundaries stay in-zone.
+    const insertRow =
+      preferInsertAbove && isInsertAllowedForZone(desiredRow, audioRow, isAudio)
+        ? desiredRow
+        : desiredRow + 1;
+    return { track: desired, insertRow };
+  }
+  return { track: placement.track, insertRow: null };
+}
+
+/**
+ * Fallback half-width (fraction of a track height) of the insert band straddling
+ * a lane boundary — used only when the caller passes no explicit band. Production
+ * threads the geometry-exact `INSERT_BOUNDARY_BAND` (timelineLayout.ts, = the clip
+ * inset `CLIP_Y / TRACK_H`) so the band matches the rendered inter-clip gutter and
+ * NEVER reaches into a clip body. Kept in sync with that constant; do not widen it
+ * back toward the old 0.32 (which armed an insert across ~64% of every row — the
+ * misfire that turned a plain horizontal drag into a phantom track insert).
+ */
+const INSERT_BAND = 3 / 48;
+
+/**
+ * Decide whether a vertical drag is inserting a new track at a lane boundary.
+ * `rowFloat` is the pointer's position in track-height units from the top of the
+ * first lane (0 = top of lane 0). Returns the boundary row to insert at
+ * (0 = above the top lane, `trackCount` = below the bottom), or null when the
+ * pointer is over a lane's middle band (a normal move/target).
+ */
+export function resolveInsertRow(
+  rowFloat: number,
+  trackCount: number,
+  band: number = INSERT_BAND,
+): number | null {
+  if (trackCount === 0) return 0;
+  if (rowFloat <= 0) return 0;
+  if (rowFloat >= trackCount) return trackCount;
+  const lane = Math.floor(rowFloat);
+  const frac = rowFloat - lane;
+  if (frac < band) return lane;
+  if (frac > 1 - band) return lane + 1;
+  return null;
+}
+
+/** Half-open overlap test: [aStart, aEnd) intersects [bStart, bEnd). */
+export function timeRangesOverlap(
+  aStart: number,
+  aEnd: number,
+  bStart: number,
+  bEnd: number,
+): boolean {
+  return aStart < bEnd && bStart < aEnd;
+}
+
+/**
+ * True when no clip on `track` overlaps [start, end) — excluding the clip
+ * identified by `excludeKey` (the one being dragged).
+ */
+export function isLaneFree(
+  elements: TimelineElement[],
+  track: number,
+  start: number,
+  end: number,
+  excludeKey: string | null,
+): boolean {
+  return !elements.some(
+    (el) =>
+      (el.key ?? el.id) !== excludeKey &&
+      el.track === track &&
+      timeRangesOverlap(start, end, el.start, el.start + el.duration),
+  );
+}
+
+export interface PlacementInput {
+  elements: TimelineElement[];
+  desiredTrack: number;
+  start: number;
+  duration: number;
+  trackOrder: number[];
+  excludeKey: string | null;
+}
+
+export interface PlacementResult {
+  /** The lane the clip should land on. */
+  track: number;
+  /**
+   * True when no existing lane was free and the caller should insert a new
+   * track instead of landing on `track` (which is then the desired lane as a
+   * last-resort fallback). Consumed in later stages (2b/2c); stage 2a ignores it.
+   */
+  needsInsert: boolean;
+}
+
+/**
+ * Resolve where a dragged clip should land, avoiding overlap. If the desired
+ * lane is free, keep it. Otherwise search the nearest free lane, **preferring
+ * up** (all lanes above, nearest first), then down. If none is free, signal an
+ * insert and fall back to the desired lane.
+ */
+export function resolvePlacement({
+  elements,
+  desiredTrack,
+  start,
+  duration,
+  trackOrder,
+  excludeKey,
+}: PlacementInput): PlacementResult {
+  const end = start + duration;
+  const idx = trackOrder.indexOf(desiredTrack);
+  // desiredTrack is not one of the zone's lanes — the clip's kind-zone has no lane
+  // yet (e.g. an audio clip dropped on a visual-only timeline). This MUST be checked
+  // BEFORE the isLaneFree short-circuit below: a free-aimed span on a foreign-zone
+  // lane (an audio clip aimed at an empty stretch of a visual-only timeline) is
+  // "free" only because that lane belongs to the wrong zone. Landing there would
+  // put the clip in the wrong kind-zone, so signal an insert to create the zone's
+  // first lane instead — regardless of whether the aimed span is occupied (#2195).
+  if (idx === -1) return { track: desiredTrack, needsInsert: true };
+
+  if (isLaneFree(elements, desiredTrack, start, end, excludeKey)) {
+    return { track: desiredTrack, needsInsert: false };
+  }
+
+  // Prefer up: nearest lane above first, then the rest above.
+  for (let up = idx - 1; up >= 0; up--) {
+    if (isLaneFree(elements, trackOrder[up], start, end, excludeKey)) {
+      return { track: trackOrder[up], needsInsert: false };
+    }
+  }
+  // Then down: nearest lane below first.
+  for (let down = idx + 1; down < trackOrder.length; down++) {
+    if (isLaneFree(elements, trackOrder[down], start, end, excludeKey)) {
+      return { track: trackOrder[down], needsInsert: false };
+    }
+  }
+  return { track: desiredTrack, needsInsert: true };
+}

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

package/src/player/components/timelineEditCapabilities.ts

@@ -0,0 +1,52 @@
+export interface TimelineEditCapabilities {
+  canMove: boolean;
+  canTrimStart: boolean;
+  canTrimEnd: boolean;
+}
+
+function isDeterministicTimelineWindow(input: {
+  tag: string;
+  compositionSrc?: string;
+  playbackStartAttr?: "media-start" | "playback-start";
+  sourceDuration?: number;
+}): boolean {
+  if (input.compositionSrc || input.playbackStartAttr != null) return true;
+  if (
+    input.sourceDuration != null &&
+    Number.isFinite(input.sourceDuration) &&
+    input.sourceDuration > 0
+  ) {
+    return true;
+  }
+  return ["video", "audio", "img"].includes(input.tag.toLowerCase());
+}
+
+export function hasPatchableTimelineTarget(input: { domId?: string; selector?: string }): boolean {
+  return Boolean(input.domId || input.selector);
+}
+
+export function getTimelineEditCapabilities(input: {
+  tag: string;
+  duration: number;
+  domId?: string;
+  selector?: string;
+  compositionSrc?: string;
+  playbackStart?: number;
+  playbackStartAttr?: "media-start" | "playback-start";
+  sourceDuration?: number;
+  timingSource?: "authored" | "implicit";
+  timelineLocked?: boolean;
+}): TimelineEditCapabilities {
+  if (input.timingSource === "implicit" || input.timelineLocked) {
+    return { canMove: false, canTrimStart: false, canTrimEnd: false };
+  }
+
+  const canPatch = hasPatchableTimelineTarget(input);
+  const hasFiniteDuration = Number.isFinite(input.duration) && input.duration > 0;
+  const hasDeterministicWindow = isDeterministicTimelineWindow(input);
+  return {
+    canMove: canPatch && (hasDeterministicWindow || hasFiniteDuration),
+    canTrimEnd: canPatch && hasFiniteDuration,
+    canTrimStart: canPatch && hasFiniteDuration,
+  };
+}

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

@@ -693,7 +693,7 @@ describe("buildTimelineAgentPrompt", () => {
       prompt: "Move the title later and lower the music",
     });
 
-    expect(text).toContain("Time range: 0:01 - 0:04");
+    expect(text).toContain("Time range: 00:01 - 00:04");
     expect(text).toContain("#title (div)");
     expect(text).toContain("#music (audio)");
     expect(text).toContain("Move the title later and lower the music");

package/src/player/components/timelineEditing.ts

@@ -4,6 +4,13 @@ import type { StackingTimelineLayer, TimelineLayerId } from "./timelineTrackOrde
 import { resolveTimelineLayerStackingMove } from "./timelineLayerDrag";
 import { shouldShowTimelineLayerGroupHeader } from "./TimelineLayerGroupHeader";
 import type { TimelineStackingElement, TimelineStackingReorderIntent } from "./timelineStacking";
+import type { TimelineEditCapabilities } from "./timelineEditCapabilities";
+
+export {
+  getTimelineEditCapabilities,
+  hasPatchableTimelineTarget,
+} from "./timelineEditCapabilities";
+export type { TimelineEditCapabilities } from "./timelineEditCapabilities";
 
 import {
   applyClipStartTrimDelta,
@@ -245,12 +252,6 @@ export interface TimelinePromptElement {
   track: number;
 }
 
-export interface TimelineEditCapabilities {
-  canMove: boolean;
-  canTrimStart: boolean;
-  canTrimEnd: boolean;
-}
-
 export type BlockedTimelineEditIntent = "move" | "resize-start" | "resize-end";
 
 export interface TimelineRangeSelection {
@@ -362,59 +363,6 @@ export function selectTimelineElementsInMarquee({
   return selected;
 }
 
-function isDeterministicTimelineWindow(input: {
-  tag: string;
-  compositionSrc?: string;
-  playbackStartAttr?: "media-start" | "playback-start";
-  sourceDuration?: number;
-}): boolean {
-  if (input.compositionSrc) return true;
-  if (input.playbackStartAttr != null) return true;
-  if (
-    input.sourceDuration != null &&
-    Number.isFinite(input.sourceDuration) &&
-    input.sourceDuration > 0
-  ) {
-    return true;
-  }
-  const normalizedTag = input.tag.toLowerCase();
-  return ["video", "audio", "img"].includes(normalizedTag);
-}
-
-export function hasPatchableTimelineTarget(input: { domId?: string; selector?: string }): boolean {
-  return Boolean(input.domId || input.selector);
-}
-
-export function getTimelineEditCapabilities(input: {
-  tag: string;
-  duration: number;
-  domId?: string;
-  selector?: string;
-  compositionSrc?: string;
-  playbackStart?: number;
-  playbackStartAttr?: "media-start" | "playback-start";
-  sourceDuration?: number;
-  timingSource?: "authored" | "implicit";
-  timelineLocked?: boolean;
-}): TimelineEditCapabilities {
-  if (input.timingSource === "implicit" || input.timelineLocked) {
-    return {
-      canMove: false,
-      canTrimStart: false,
-      canTrimEnd: false,
-    };
-  }
-
-  const canPatch = hasPatchableTimelineTarget(input);
-  const hasFiniteDuration = Number.isFinite(input.duration) && input.duration > 0;
-  const hasDeterministicWindow = isDeterministicTimelineWindow(input);
-  return {
-    canMove: canPatch && (hasDeterministicWindow || hasFiniteDuration),
-    canTrimEnd: canPatch && hasFiniteDuration,
-    canTrimStart: canPatch && hasFiniteDuration,
-  };
-}
-
 export function resolveBlockedTimelineEditIntent(input: {
   width: number;
   offsetX: number;
@@ -525,3 +473,72 @@ export function buildTimelineElementAgentPrompt(element: {
 export function formatTimelineAttributeNumber(value: number): string {
   return Number(roundToCentiseconds(value).toFixed(2)).toString();
 }
+
+/**
+ * Apply one edge auto-scroll step: scroll `scroll` toward the edge zone the
+ * pointer is in, clamped to the scrollable range. Returns true when the
+ * container actually moved (the caller keeps its RAF running and re-runs its
+ * live preview), false when the pointer is outside the edge zones or the scroll
+ * is already clamped (the caller stops).
+ */
+export function applyTimelineAutoScrollStep(
+  scroll: HTMLElement,
+  clientX: number,
+  clientY: number,
+): boolean {
+  const delta = resolveTimelineAutoScroll(scroll.getBoundingClientRect(), clientX, clientY);
+  if (delta.x === 0 && delta.y === 0) return false;
+  const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
+  const maxScrollTop = Math.max(0, scroll.scrollHeight - scroll.clientHeight);
+  const nextScrollLeft = Math.max(0, Math.min(maxScrollLeft, scroll.scrollLeft + delta.x));
+  const nextScrollTop = Math.max(0, Math.min(maxScrollTop, scroll.scrollTop + delta.y));
+  if (nextScrollLeft === scroll.scrollLeft && nextScrollTop === scroll.scrollTop) return false;
+  scroll.scrollLeft = nextScrollLeft;
+  scroll.scrollTop = nextScrollTop;
+  return true;
+}
+
+/**
+ * Decide whether an edge auto-scroll RAF loop should start, stop, or stay as-is
+ * for the current pointer: "start" when the pointer is in an edge zone and no
+ * loop is running, "stop" when it left the zones while a loop is running,
+ * "none" otherwise.
+ */
+export function resolveTimelineAutoScrollLoopAction(
+  scroll: HTMLElement | null,
+  clientX: number,
+  clientY: number,
+  rafActive: boolean,
+): "start" | "stop" | "none" {
+  if (!scroll) return "none";
+  const delta = resolveTimelineAutoScroll(scroll.getBoundingClientRect(), clientX, clientY);
+  if (delta.x === 0 && delta.y === 0) return rafActive ? "stop" : "none";
+  return rafActive ? "none" : "start";
+}
+
+/**
+ * Escape cancels an in-progress clip drag / resize / blocked-drag: no commit,
+ * no undo entry — the previews live only in the gesture state, so clearing it
+ * restores the pre-drag timeline. `suppressClick` arms the click suppressor
+ * only when the gesture actually started, so the click generated by the
+ * eventual pointerup can't reselect or split the clip.
+ */
+export function resolveTimelineDragEscape(input: TimelineDragEscapeInput): {
+  cancel: boolean;
+  suppressClick: boolean;
+} {
+  if (input.key !== "Escape" || (!input.drag && !input.resize && !input.blocked)) {
+    return { cancel: false, suppressClick: false };
+  }
+  return {
+    cancel: true,
+    suppressClick: Boolean(input.drag?.started || input.resize?.started || input.blocked?.started),
+  };
+}
+
+export interface TimelineDragEscapeInput {
+  key: string;
+  drag: { started: boolean } | null;
+  resize: { started: boolean } | null;
+  blocked: { started: boolean } | null;
+}