@hyperframes/studio 0.8.90 → 0.8.92

package/src/player/components/timelineCollision.ts

@@ -1,6 +1,4 @@
 import type { TimelineElement } from "../store/playerStore";
-import { INSERT_BOUNDARY_BAND } from "./timelineLayout";
-import { isMainTrackElement } from "./timelineZones";
 
 /**
  * Keep a landing track inside the dragged clip's kind-zone: visual clips stay in
@@ -38,26 +36,6 @@ export function isInsertAllowedForZone(
   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
@@ -84,6 +62,50 @@ function outOfRangeZoneInsertRow(
   return desired < Math.min(...zoneTracks) ? zoneTop : zoneBottom;
 }
 
+const floorCenti = (v: number) => Math.floor(v * 100 + 1e-6) / 100;
+const ceilCenti = (v: number) => Math.ceil(v * 100 - 1e-6) / 100;
+
+/** Whether `candidate` is nearer `start` than `best`; a tie goes to the later time. */
+const isNearer = (candidate: number, best: number, start: number) => {
+  const gap = Math.abs(candidate - start) - Math.abs(best - start);
+  return gap < 0 || (gap === 0 && candidate > best);
+};
+
+/** The start nearest `start`, not below `minStart`, at which [start, start + duration) overlaps
+ *  no clip on `track`. Ties go to the later time. The gap after the row's last clip always fits,
+ *  so a row with no gap long enough puts the clip right after its last clip. `origin` is the
+ *  clip's own start on this track: keeping it rewrites nothing, so it fits between any edges. */
+export function resolveNearestFreeStart(
+  elements: readonly TimelineElement[],
+  track: number,
+  start: number,
+  duration: number,
+  excludeKey: string | null,
+  minStart = 0,
+  origin: number | null = null,
+): number {
+  const busy = elements
+    .filter((el) => (el.key ?? el.id) !== excludeKey && el.track === track)
+    .sort((a, b) => a.start - b.start);
+  let best = Number.POSITIVE_INFINITY;
+  let gapStart = minStart;
+  for (const el of [...busy, null]) {
+    const latest = el ? floorCenti(el.start - duration) : Number.POSITIVE_INFINITY;
+    if (latest >= gapStart) {
+      const candidate = Math.min(Math.max(start, gapStart), latest);
+      if (Math.abs(candidate - start) <= Math.abs(best - start)) best = candidate;
+    }
+    if (el) gapStart = Math.max(gapStart, ceilCenti(el.start + el.duration));
+  }
+  if (origin === null || origin < minStart || !isNearer(origin, best, start)) return best;
+  // Float slack at both ends: 0.333 + 1.733 is 2.0660000000000003, a hair past a neighbour at 2.066.
+  const [from, to] = [origin + 1e-6, origin + duration - 1e-6];
+  const clear = busy.every((el) => !timeRangesOverlap(from, to, el.start, el.start + el.duration));
+  return clear ? origin : best;
+}
+
+// Where a dragged clip lands: on the aimed row of its kind, at the nearest free time there. Only an aim outside all
+// rows, or into a kind with no row yet, opens a track (`insertRow`).
 export function resolveZoneDropPlacement(input: {
   order: number[];
   audioTracks: ReadonlySet<number>;
@@ -94,99 +116,54 @@ export function resolveZoneDropPlacement(input: {
   duration: number;
   dragKey: string;
   isAudio: boolean;
-  preferInsertAbove?: boolean;
-}): { track: number; insertRow: number | null } {
+  /** Lowest start the clip may take (every moving clip stays at or after its host's start). */
+  minStart?: number;
+  /** Where the dragged clip sits now. */
+  origin?: { track: number; start: number };
+}): { track: number; insertRow: number | null; start: number } {
   const { order, audioTracks, elements, desiredTrack, deliberateInsertRow } = input;
-  const { start, duration, dragKey, isAudio, preferInsertAbove } = input;
+  const { start, duration, dragKey, isAudio, minStart } = input;
   const audioRow = order.findIndex((t) => audioTracks.has(t));
 
   if (
     deliberateInsertRow !== null &&
     isInsertAllowedForZone(deliberateInsertRow, audioRow, isAudio)
   ) {
-    return { track: desiredTrack, insertRow: deliberateInsertRow };
+    return { track: desiredTrack, insertRow: deliberateInsertRow, start };
   }
 
   const desired = clampTrackToZone(desiredTrack, order, audioRow, isAudio);
   const zoneTracks = order.filter((t) => audioTracks.has(t) === isAudio);
-  const placement = resolvePlacement({
+  // Only when the aim is outside the rows, or the clip's zone has no row yet.
+  if (!zoneTracks.includes(desired)) {
+    const desiredRow = order.indexOf(desired);
+    const insertRow =
+      desiredRow < 0
+        ? outOfRangeZoneInsertRow(order, zoneTracks, audioRow, desired)
+        : desiredRow + 1;
+    return { track: desired, insertRow, start };
+  }
+  const origin = input.origin?.track === desired ? input.origin.start : null;
+  const freeStart = resolveNearestFreeStart(
     elements,
-    desiredTrack: desired,
+    desired,
     start,
     duration,
-    trackOrder: zoneTracks,
-    excludeKey: dragKey,
-  });
-  const originTrack = elements.find((element) => (element.key ?? element.id) === dragKey)?.track;
-  const snappedBackToOrigin =
-    originTrack != null && desired !== originTrack && placement.track === originTrack;
-  if (placement.needsInsert || snappedBackToOrigin) {
-    const desiredRow = order.indexOf(desired);
-    if (desiredRow < 0) {
-      return {
-        track: desired,
-        insertRow: outOfRangeZoneInsertRow(order, zoneTracks, audioRow, desired),
-      };
-    }
-    // When collision fallback found only the origin lane, insert on the far side
-    // of the aimed lane so normalization cannot turn the gesture into a no-op.
-    // Otherwise prefer the gap nearest the pointer, preserving normal insertion.
-    const originRow = originTrack == null ? -1 : order.indexOf(originTrack);
-    const insertAbove = snappedBackToOrigin
-      ? originRow > desiredRow
-      : preferInsertAbove && isInsertAllowedForZone(desiredRow, audioRow, isAudio);
-    const insertRow = insertAbove ? desiredRow : desiredRow + 1;
-    return { track: desired, insertRow };
-  }
-  return { track: placement.track, insertRow: null };
-}
-
-function landsOnMainTrack(landingTrack: number, isAudio: boolean): boolean {
-  return isMainTrackElement({
-    id: "",
-    tag: isAudio ? "audio" : "video",
-    start: 0,
-    duration: 0,
-    track: landingTrack,
-  });
-}
-
-/** An existing clip newly landing on an empty main track commits at start=0.
- *  No-op once the main track holds another clip, off the main track, or for
- *  a clip already resident there. `others` excludes the landing clip itself. */
-export function resolveMainTrackDropStart(
-  others: readonly TimelineElement[],
-  originTrack: number,
-  landingTrack: number,
-  isAudio: boolean,
-  desiredStart: number,
-): number {
-  if (originTrack === landingTrack || !landsOnMainTrack(landingTrack, isAudio)) {
-    return desiredStart;
-  }
-  return others.some(isMainTrackElement) ? desiredStart : 0;
+    dragKey,
+    minStart,
+    origin,
+  );
+  return { track: desired, insertRow: null, start: freeStart };
 }
 
 /**
- * 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). The default band
- * preserves collapsed-row behavior; production passes the concrete row's band.
+ * The row boundary a pointer opens a new track at, or null over a row. `rowFloat` is the pointer's
+ * position in row units from the top of the first row. Only the empty space above the first row
+ * (0) or below the last (`trackCount`) opens one: a drop anywhere on a row stays on that row.
  */
-export function resolveInsertRow(
-  rowFloat: number,
-  trackCount: number,
-  band: number = INSERT_BOUNDARY_BAND,
-): number | null {
-  if (trackCount === 0) return 0;
-  if (rowFloat <= 0) return 0;
+export function resolveInsertRow(rowFloat: number, trackCount: number): number | null {
+  if (trackCount === 0 || 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;
 }
 
@@ -218,67 +195,3 @@ export function isLaneFree(
       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.test.tsx

@@ -256,8 +256,10 @@ describe("useTimelineAssetDrop", () => {
 
 describe("resolveDropInsertRow", () => {
   const rows = [TRACK_H, TRACK_H, TRACK_H];
-  it("arms a new track at the boundary between two lanes", () => {
-    expect(resolveDropInsertRow(getTimelineRowTop(1, rows), rows, 3)).toBe(1);
+  it("stays on the row at the boundary between two rows", () => {
+    for (const dy of [-1, 0, 1]) {
+      expect(resolveDropInsertRow(getTimelineRowTop(1, rows) + dy, rows, 3)).toBeNull();
+    }
   });
   it("arms a new track above the first lane", () => {
     expect(resolveDropInsertRow(getTimelineRowTop(0, rows) - 4, rows, 3)).toBe(0);
@@ -274,20 +276,32 @@ describe("resolveDropInsertRow", () => {
 });
 
 describe("useTimelineAssetDrop new-track drops", () => {
-  it("previews and commits an insert row for an asset dropped between lanes", () => {
+  it("drops an asset released at the top edge of a row onto that row, with no new track", () => {
     const onAssetDrop = vi.fn();
     const view = renderHarness(onAssetDrop);
     const transfer = assetTransfer(JSON.stringify({ path: "assets/a.png" }));
     const y = getTimelineRowTop(1) + 1;
 
     act(() => view.api.handleAssetDragOver(dragEvent(transfer, 400, y)));
-    expect(view.api.dropPreview).toMatchObject({ start: 10, insertRow: 1 });
+    expect(view.api.dropPreview).toEqual({ start: 10, track: 1 });
+    act(() => view.api.handleAssetDrop(dragEvent(transfer, 400, y)));
+    expect(onAssetDrop).toHaveBeenCalledWith("assets/a.png", { start: 10, track: 1 });
+    act(() => view.root.unmount());
+  });
+
+  it("opens a new track for an asset released in the empty space above the first row", () => {
+    const onAssetDrop = vi.fn();
+    const view = renderHarness(onAssetDrop);
+    const transfer = assetTransfer(JSON.stringify({ path: "assets/a.png" }));
+    const y = getTimelineRowTop(0) - 4;
+
+    act(() => view.api.handleAssetDragOver(dragEvent(transfer, 400, y)));
     act(() => view.api.handleAssetDrop(dragEvent(transfer, 400, y)));
     expect(onAssetDrop).toHaveBeenCalledWith(
       "assets/a.png",
       expect.objectContaining({
         start: 10,
-        insertRow: 1,
+        insertRow: 0,
         trackOrder: Array.from({ length: 100 }, (_, index) => index),
       }),
     );

package/src/player/components/timelineDragDrop.ts

@@ -5,8 +5,7 @@ import {
   TIMELINE_COMPOSITION_MIME,
 } from "../../utils/timelineCompositionDrop";
 import {
-  getTimelineInsertBoundaryBand,
-  getTimelineRowPositionFromY,
+  getTimelineRowFromY,
   resolveTimelineAssetDrop,
   type TimelineRowGeometry,
 } from "./timelineLayout";
@@ -52,17 +51,17 @@ function canInsertTrackFor(types: readonly string[]): boolean {
   return types.includes("Files") || types.includes(TIMELINE_ASSET_MIME);
 }
 
-/** The row boundary a pointer at `contentY` arms for a new track, or null over a lane's middle. */
+/** The row boundary a pointer at `contentY` opens a new track at, or null over a row. */
 export function resolveDropInsertRow(
   contentY: number,
   rowHeights: readonly number[] | undefined,
   trackCount: number,
 ): number | null {
   if (trackCount === 0) return null;
-  const { rowFloat, rowHeight } = getTimelineRowPositionFromY(contentY, rowHeights);
+  const rowFloat = getTimelineRowFromY(contentY, rowHeights);
   // Past the last lane the drop already appends a track (getDefaultDroppedTrack).
   if (rowFloat >= trackCount) return null;
-  return resolveInsertRow(rowFloat, trackCount, getTimelineInsertBoundaryBand(rowHeight));
+  return resolveInsertRow(rowFloat, trackCount);
 }
 
 function placeDrop(
@@ -118,10 +117,9 @@ function applyTypedJsonDrop(
 }
 
 /**
- * Dropping an asset/file/block/composition onto the timeline places it at the
- * exact time and track it was dropped on, like CapCut (pointer placement on
- * every track but the magnetic main track). Supersedes the prior playhead
- * decision (#2291); playhead adds stay available, see useAddAssetAtPlayhead.
+ * Dropping an asset/file/block/composition onto the timeline places it on the row
+ * and at the time it was dropped on; an asset moves to that row's nearest free time.
+ * Supersedes the prior playhead decision (#2291); see useAddAssetAtPlayhead.
  */
 export function useTimelineAssetDrop({
   scrollRef,

package/src/player/components/timelineDragLanding.ts

@@ -1,12 +1,7 @@
 import type { TimelineElement } from "../store/playerStore";
 import type { DragCommitDeps } from "./timelineClipDragCommit";
-import type { DraggedClipState } from "./timelineClipDragTypes";
 import { classifyZone, normalizeToZones } from "./timelineZones";
-import { resolveMainTrackDropStart } from "./timelineCollision";
-import { isAudioTimelineElement } from "../../utils/timelineInspector";
-import { resolveExpandedHostAlias } from "./timelineAuthoredMoveTarget";
 import { sameSourceFile } from "./timelineAuthoredTrack";
-import { round3 } from "./timelineGaps";
 
 const keyOf = (e: TimelineElement) => e.key ?? e.id;
 
@@ -58,47 +53,3 @@ export function layoutAfterTrackInsert(
   );
   return { normalized, targetTrack, writable };
 }
-
-/** The start a solo clip lands at, for both the ghost and the commit: 0 on an empty
- *  main track, judged on the final lane (after the renumber and the host alias).
- *  Returned in the dragged clip's own frame. */
-export function resolveDragLandingStart(
-  drag: DraggedClipState,
-  deps: Pick<DragCommitDeps, "elements" | "trackOrder" | "selectedKeys">,
-): number {
-  const alias = resolveExpandedHostAlias(drag, deps);
-  const target = alias?.drag ?? drag;
-  const keys = alias?.selectedKeys ?? deps.selectedKeys;
-  const element = target.element;
-  const key = keyOf(element);
-  if (keys && keys.size > 1 && keys.has(key)) return drag.previewStart;
-
-  let landingTrack = target.previewTrack;
-  let renumbered = new Map<string, number>();
-  if (target.insertRow != null) {
-    const layout = layoutAfterTrackInsert(
-      element,
-      target.previewStart,
-      target.insertRow,
-      null,
-      deps,
-    );
-    if (layout) {
-      renumbered = new Map(layout.normalized.map((n) => [keyOf(n), n.track]));
-      landingTrack = renumbered.get(key) ?? layout.targetTrack;
-    }
-  }
-  const others = deps.elements
-    .filter((e) => keyOf(e) !== key)
-    .map((e) => (renumbered.has(keyOf(e)) ? { ...e, track: renumbered.get(keyOf(e))! } : e));
-  const snapped = resolveMainTrackDropStart(
-    others,
-    element.track,
-    landingTrack,
-    isAudioTimelineElement(element),
-    target.previewStart,
-  );
-  return snapped === target.previewStart
-    ? drag.previewStart
-    : round3(drag.previewStart + snapped - target.previewStart);
-}

package/src/player/components/timelineEditing.ts

@@ -51,6 +51,7 @@ export interface TimelineMoveInput {
   originScrollLeft?: number;
   currentScrollLeft?: number;
   pixelsPerSecond: number;
+  minStart?: number;
   maxStart: number;
   trackOrder: number[];
   layerOrder?: TimelineLayerId[];
@@ -127,7 +128,7 @@ export function resolveTimelineMove(
   const deltaTrack = Math.round(trackDeltaRaw);
   const nextStart = clamp(
     roundToCentiseconds(input.start + deltaTime),
-    0,
+    input.minStart ?? 0,
     Math.max(0, input.maxStart),
   );
 

package/src/player/components/timelineGroupEditing.ts

@@ -1,6 +1,7 @@
 import { clampPlaybackRate } from "@hyperframes/parsers/media-duration";
 import { roundToCenti } from "../../utils/rounding";
 import type { TimelineElement } from "../store/playerStore";
+import { clampToHostStart } from "../store/timelineElement";
 import { getTimelineEditCapabilities } from "./timelineEditCapabilities";
 
 const DEFAULT_TIMELINE_MIN_DURATION = 0.1;
@@ -88,6 +89,7 @@ export interface TimelineGroupTimingMember {
   duration: number;
   playbackStart?: number;
   playbackRate?: number;
+  minStart?: number;
 }
 
 export type TimelineGroupResizeEdge = "start" | "end";
@@ -107,7 +109,7 @@ function clampTimelineGroupMoveDelta(
   members: readonly TimelineGroupTimingMember[],
 ): number {
   if (members.length === 0) return 0;
-  const minDelta = Math.max(...members.map((member) => -member.start));
+  const minDelta = Math.max(...members.map((member) => -(member.start - (member.minStart ?? 0))));
   return roundTimelineTime(Math.max(rawDelta, minDelta));
 }
 
@@ -139,7 +141,9 @@ export function clampTimelineGroupResizeDelta(
   }
 
   // Rigid group: the applied delta is bounded by the most-constrained member.
-  const bounds = members.map((member) => clipStartTrimDeltaBounds(member, 0, minDuration));
+  const bounds = members.map((member) =>
+    clipStartTrimDeltaBounds(member, member.minStart ?? 0, minDuration),
+  );
   const minDelta = ceilTimelineTime(Math.max(...bounds.map((b) => b.minDelta)));
   const maxDelta = Math.min(...bounds.map((b) => b.maxDelta));
   const delta = roundTimelineTime(clamp(rawDelta, minDelta, maxDelta));
@@ -243,6 +247,7 @@ export function buildTimelineGroupResizeMembers(
         ? (element.playbackStart ?? 0)
         : element.playbackStart,
     playbackRate: element.playbackRate,
+    minStart: clampToHostStart(element, 0),
   }));
 }
 

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

@@ -1,8 +1,5 @@
 import { describe, it, expect } from "vitest";
 import {
-  CLIP_Y,
-  INSERT_BOUNDARY_BAND,
-  getTimelineInsertBoundaryBand,
   RULER_H,
   TRACK_H,
   LANE_H,
@@ -294,25 +291,3 @@ describe("getTimelineScrubTime", () => {
     expect(at(origin + 250, Number.NaN)).toBe(0);
   });
 });
-
-// The only production hook keeping resolveInsertRow's band aligned with the
-// rendered clip inset once rows can be taller than TRACK_H. Pinned directly so a
-// change to CLIP_Y or the invalid-height fallback can't silently drift it.
-describe("getTimelineInsertBoundaryBand", () => {
-  it("matches the fixed band for a plain track row", () => {
-    expect(getTimelineInsertBoundaryBand(TRACK_H)).toBe(INSERT_BOUNDARY_BAND);
-    expect(getTimelineInsertBoundaryBand(TRACK_H)).toBe(CLIP_Y / TRACK_H);
-  });
-
-  it("shrinks as the row grows, so the band stays CLIP_Y pixels tall", () => {
-    const expanded = TRACK_H + 2 * LANE_H;
-    expect(getTimelineInsertBoundaryBand(expanded)).toBeCloseTo(CLIP_Y / expanded, 10);
-    expect(getTimelineInsertBoundaryBand(expanded)).toBeLessThan(INSERT_BOUNDARY_BAND);
-  });
-
-  it("falls back to the plain-track band for a height that is not usable", () => {
-    for (const height of [0, -10, Number.NaN]) {
-      expect(getTimelineInsertBoundaryBand(height)).toBe(INSERT_BOUNDARY_BAND);
-    }
-  });
-});

package/src/player/components/timelineLayout.ts

@@ -54,11 +54,6 @@ export function getTimelineBeatEntries(
 export function getTimelineLaneTop(laneIndex: number): number {
   return TRACK_H + Math.max(0, Math.trunc(laneIndex)) * LANE_H;
 }
-/**
- * Collapsed-row characterization value for the new-track INSERT band. Runtime
- * hit-testing uses getTimelineInsertBoundaryBand with the concrete row height.
- */
-export const INSERT_BOUNDARY_BAND = CLIP_Y / TRACK_H;
 /**
  * Breathing room INSIDE the scroll area (CapCut-style), threaded through every
  * track-row y computation via {@link getTimelineRowTop} — never inline a magic
@@ -263,17 +258,6 @@ export function getTimelineRowFromY(
   return getTimelineRowGeometry(rowHeights).getRowFromY(contentY);
 }
 
-export function getTimelineRowPositionFromY(
-  contentY: number,
-  rowHeights: readonly number[] = EMPTY_ROW_HEIGHTS,
-): { rowFloat: number; row: number; fraction: number; rowHeight: number } {
-  return getTimelineRowGeometry(rowHeights).getRowPositionFromY(contentY);
-}
-
-/** Fractional insert band for the concrete row under a pointer. */
-export function getTimelineInsertBoundaryBand(rowHeight: number): number {
-  return CLIP_Y / validRowHeight(rowHeight);
-}
 /**
  * While a clip drag is live, the rendered timeline extends this far past the
  * ghost's end so the right-edge auto-scroll zone always has room to keep

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

@@ -1,10 +1,12 @@
 import { describe, it, expect } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
 import {
-  clampGroupMoveDelta,
+  groupMoveFloor,
   isMultiDragActive,
   isMultiDragPassenger,
   multiDragDeltaSeconds,
   multiDragPassengerOffsetPx,
+  resolveGroupMovers,
   type MultiDragPreviewInput,
 } from "./timelineMultiDragPreview";
 
@@ -92,36 +94,45 @@ describe("multiDragPassengerOffsetPx (rigid: every passenger shares the delta)",
   });
 });
 
-describe("clampGroupMoveDelta (rigid group move)", () => {
-  it("passes a rightward delta through unchanged (no right wall)", () => {
-    expect(clampGroupMoveDelta(3, [2, 5, 9])).toBe(3);
-    expect(clampGroupMoveDelta(1000, [0, 4])).toBe(1000);
-  });
+const at = (id: string, start: number, locked = false): TimelineElement => ({
+  id,
+  key: id,
+  tag: "video",
+  start,
+  duration: 1,
+  track: 0,
+  domId: id,
+  ...(locked ? { timelineLocked: true } : {}),
+});
 
-  it("passes a leftward delta through when no member would cross 0", () => {
-    // Leftmost member at 5, moving left by 3 → 2 ≥ 0, so unclamped.
-    expect(clampGroupMoveDelta(-3, [5, 8, 12])).toBe(-3);
+describe("groupMoveFloor (rigid group move)", () => {
+  it("lets the grabbed clip go as far left as the leftmost mover allows, and no further", () => {
+    expect(groupMoveFloor(at("g", 10), [at("g", 10), at("p", 1), at("q", 4)])).toBe(9);
+    expect(groupMoveFloor(at("g", 5), [at("g", 5), at("p", 8)])).toBe(0); // the grabbed clip is leftmost
   });
 
-  it("clamps a leftward delta so the leftmost member stops exactly at 0", () => {
-    // Leftmost at 2 → the furthest left the group can move is -2 (that member → 0).
-    // A pointer asking for -5 is clamped to -2: the grabbed clip stops with the
-    // formation instead of out-running it.
-    expect(clampGroupMoveDelta(-5, [2, 6, 10])).toBe(-2);
+  it("forbids any leftward move once a mover sits at 0", () => {
+    expect(groupMoveFloor(at("g", 3), [at("g", 3), at("p", 0)])).toBe(3);
   });
 
-  it("is bounded by the MOST-constrained (leftmost) member, not the grabbed one", () => {
-    // Grabbed clip is at 10; a passenger at 1 is the constraint. Max left = -1.
-    expect(clampGroupMoveDelta(-8, [10, 1, 4])).toBe(-1);
+  it("stops a nested mover at its host composition's start, and a lone clip at its own host", () => {
+    const nested = { ...at("p", 3), parentCompositionStart: 2 };
+    expect(groupMoveFloor(at("g", 10), [at("g", 10), nested])).toBe(9);
+    expect(groupMoveFloor(nested, [])).toBe(2);
   });
+});
+
+describe("resolveGroupMovers (the clips a group drag moves)", () => {
+  const elements = [at("g", 5), at("p", 2), at("locked", 0, true), at("other", 1)];
 
-  it("already-at-0 member forbids any leftward move", () => {
-    expect(clampGroupMoveDelta(-4, [0, 3, 7])).toBe(0);
-    // rightward still allowed
-    expect(clampGroupMoveDelta(2, [0, 3, 7])).toBe(2);
+  it("is every selected clip that can move, never a locked one or an unselected one", () => {
+    const movers = resolveGroupMovers(elements, new Set(["g", "p", "locked"]), "g");
+    expect(movers?.map((e) => e.id)).toEqual(["g", "p"]);
   });
 
-  it("returns the raw delta for an empty formation", () => {
-    expect(clampGroupMoveDelta(-9, [])).toBe(-9);
+  it("is null when the grabbed clip is not part of a multi-selection", () => {
+    expect(resolveGroupMovers(elements, new Set(["g"]), "g")).toBeNull();
+    expect(resolveGroupMovers(elements, new Set(["p", "other"]), "g")).toBeNull();
+    expect(resolveGroupMovers(elements, undefined, "g")).toBeNull();
   });
 });