@hyperframes/studio 0.7.54 → 0.7.56

package/src/player/components/timelineLayout.ts

@@ -7,38 +7,66 @@ export const TRACK_H = 48;
 export const RULER_H = 24;
 export const CLIP_Y = 3;
 export const CLIP_HANDLE_W = 18;
-const TIMELINE_SCROLL_BUFFER = 20;
-
-/* ── Timeline duration ─────────────────────────────────────────────── */
+/**
+ * Half-width (as a fraction of TRACK_H) of the new-track INSERT band that
+ * straddles each lane boundary. Deliberately equals the clip's vertical inset
+ * (`CLIP_Y / TRACK_H`): a clip body fills [CLIP_Y, TRACK_H − CLIP_Y] of its row,
+ * so the ONLY region this band covers is the visible empty gutter between two
+ * clip bodies (plus the top/bottom breathing pads, handled separately by the
+ * rowFloat ≤ 0 / ≥ trackCount extremes). Aiming at a clip body is therefore a
+ * move-to-that-lane; only the inter-clip gap arms an insert — see resolveInsertRow.
+ * Threaded into resolveInsertRow by the drag preview so the hit band can never
+ * drift from the rendered clip geometry.
+ */
+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
+ * offset; a track row's top is always `RULER_H + TRACKS_TOP_PAD + row*TRACK_H`.
+ *
+ * - TRACKS_TOP_PAD: empty space between the (sticky) ruler and the first track
+ *   (~half a track height) so the first clip isn't jammed under the ruler.
+ * - TRACKS_BOTTOM_PAD: empty space below the last track (~1.5 track heights),
+ *   enough to comfortably drag a clip into the void to create a new bottom lane.
+ */
+export const TRACKS_TOP_PAD = 50;
+export const TRACKS_BOTTOM_PAD = Math.round(TRACK_H * 1.5);
 
-// Committed timeline length: root duration or the furthest committed clip end,
-// with NO live drag/resize preview. This drives the zoom (fit-to-width pps) so
-// the pixels-per-second mapping stays fixed while you drag — otherwise a clip
-// dragged past the end grows the duration, shrinks pps, and jumps under the
-// pointer (a positive-feedback loop). The zoom re-fits once on drop.
-export function computeTimelineBasisDuration(
-  rootDuration: number,
-  clipEnds: readonly number[],
-): number {
-  const safeDur = Number.isFinite(rootDuration) ? rootDuration : 0;
-  if (clipEnds.length === 0) return safeDur;
-  const maxEnd = Math.max(safeDur, ...clipEnds);
-  return Number.isFinite(maxEnd) ? maxEnd : safeDur;
+/**
+ * The y (content-space) of the top edge of track ROW index `row` (0 = first
+ * displayed lane). The single source of truth for row→y — the ruler height plus
+ * the top breathing pad plus whole track lanes above it. Every clip/ghost/
+ * placeholder/insertion top and every pointer-y→row inversion goes through this
+ * (or its inverse in {@link getTimelineRowFromY}) so the pad can never drift.
+ */
+export function getTimelineRowTop(row: number): number {
+  return RULER_H + TRACKS_TOP_PAD + row * TRACK_H;
 }
 
-// Displayed length: the basis plus any active drag/resize preview end, so the
-// ruler and track width grow to follow a clip dragged past the current end
-// (with the zoom held fixed, the extra length becomes scrollable content).
-export function computeTimelineEffectiveDuration(
-  basisDuration: number,
-  previewEnds: readonly (number | null)[],
-): number {
-  let maxEnd = basisDuration;
-  for (const end of previewEnds) {
-    if (end != null && Number.isFinite(end)) maxEnd = Math.max(maxEnd, end);
-  }
-  return maxEnd;
+/**
+ * Inverse of {@link getTimelineRowTop}: the fractional row index for a content-
+ * space y (used for insert-row / drop-lane decisions). Subtracts the ruler and
+ * top pad before dividing by the track height.
+ */
+export function getTimelineRowFromY(contentY: number): number {
+  return (contentY - RULER_H - TRACKS_TOP_PAD) / TRACK_H;
 }
+/**
+ * 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
+ * stepping — that's what lets a drag extend the timeline past its current
+ * rendered width (see Timeline.tsx displayContentWidth).
+ */
+export const DRAG_EXTEND_MARGIN_PX = 160;
+/**
+ * The rendered timeline always spans at least this many seconds of ruler +
+ * track lanes, even when the composition is shorter — the empty space on the
+ * right is a real, drag/drop-enabled surface (clips can be moved into it; the
+ * composition grows on commit, content-driven). In fit mode the fit pps is
+ * derived against this floor, so a 10s comp renders as ~1/6 of the viewport
+ * with 60s of ruler after it.
+ */
+export const MIN_TIMELINE_EXTENT_S = 60;
 
 /* ── Tick generation ──────────────────────────────────────────────── */
 function getMajorTickInterval(duration: number, pixelsPerSecond?: number): number {
@@ -54,15 +82,15 @@ function getMajorTickInterval(duration: number, pixelsPerSecond?: number): numbe
   return durationIntervals.find((interval) => interval >= target) ?? 60;
 }
 
-function getMinorTickInterval(majorInterval: number, pixelsPerSecond?: number): number {
-  if (
-    Number.isFinite(pixelsPerSecond) &&
-    (pixelsPerSecond ?? 0) > 0 &&
-    (majorInterval / 2) * (pixelsPerSecond ?? 0) < 12
-  ) {
-    return 0;
-  }
-  return majorInterval / 2;
+// How many equal parts to split each major interval into for minor ticks. Prefer
+// quarters (4) so the midpoint stays a minor tick; fall back to halves (2) then
+// none (0) as ticks get too dense to read (< ~8px apart).
+function getMinorSubdivisions(majorInterval: number, pixelsPerSecond?: number): number {
+  const pps = Number.isFinite(pixelsPerSecond) ? (pixelsPerSecond ?? 0) : 0;
+  if (pps <= 0) return 4; // no zoom info (duration-fit mode): quarter ticks
+  if ((majorInterval / 4) * pps >= 8) return 4;
+  if ((majorInterval / 2) * pps >= 8) return 2;
+  return 0;
 }
 
 export function generateTicks(
@@ -72,39 +100,25 @@ export function generateTicks(
   if (duration <= 0 || !Number.isFinite(duration) || duration > 7200)
     return { major: [], minor: [] };
   const majorInterval = getMajorTickInterval(duration, pixelsPerSecond);
-  const minorInterval = getMinorTickInterval(majorInterval, pixelsPerSecond);
+  const subdivisions = getMinorSubdivisions(majorInterval, pixelsPerSecond);
+  const minorInterval = subdivisions > 0 ? majorInterval / subdivisions : 0;
   const major: number[] = [];
   const minor: number[] = [];
   const maxTicks = 2000; // Safety cap to prevent runaway tick generation
   for (let t = 0; t <= duration + 0.001 && major.length < maxTicks; t += majorInterval) {
     const rounded = Math.round(t * 100) / 100;
     major.push(rounded);
-    if (minorInterval > 0 && major.length + minor.length < maxTicks) {
-      const midpoint = Math.round((t + minorInterval) * 100) / 100;
-      if (midpoint <= duration + 0.001) minor.push(midpoint);
+    // Emit the (subdivisions - 1) minor ticks between this major and the next.
+    for (let k = 1; k < subdivisions && major.length + minor.length < maxTicks; k++) {
+      const m = Math.round((t + k * minorInterval) * 100) / 100;
+      if (m <= duration + 0.001) minor.push(m);
     }
   }
   return { major, minor };
 }
 
-/**
- * Ticks spanning the full visible ruler width, not just the composition, so a
- * zoomed-out ruler stays filled with labels instead of ending mid-panel. The
- * major/minor interval is driven by pixelsPerSecond (pixel spacing), so widening
- * the range keeps spacing identical — it only adds ticks past the content end.
- */
-export function generateVisibleTicks(
-  effectiveDuration: number,
-  pixelsPerSecond: number,
-  viewportWidth: number,
-  gutter: number,
-): { major: number[]; minor: number[] } {
-  const visible = viewportWidth > gutter ? (viewportWidth - gutter) / pixelsPerSecond : 0;
-  return generateTicks(Math.max(effectiveDuration, visible), pixelsPerSecond);
-}
-
 export function formatTimelineTickLabel(time: number, duration: number, majorInterval: number) {
-  if (!Number.isFinite(time)) return "0:00";
+  if (!Number.isFinite(time)) return "00:00";
   const safeTime = Math.max(0, time);
   if (majorInterval < 0.1) {
     const totalHundredths = Math.round(safeTime * 100);
@@ -128,6 +142,45 @@ export function formatTimelineTickLabel(time: number, duration: number, majorInt
   return formatTime(safeTime);
 }
 
+/* ── Width / duration derivation ──────────────────────────────────── */
+/**
+ * Fit-mode pixels-per-second: fill the viewport with the composition, but
+ * never map fewer than MIN_TIMELINE_EXTENT_S seconds onto it — a short comp
+ * takes a fraction of the width and the remaining ruler runs to 1:00.
+ * Manual zoom multiplies this base, so the floor only anchors the default.
+ */
+export function getTimelineFitPps(viewportWidth: number, effectiveDuration: number): number {
+  const safeDuration =
+    Number.isFinite(effectiveDuration) && effectiveDuration > 0 ? effectiveDuration : 0;
+  const span = Math.max(safeDuration, MIN_TIMELINE_EXTENT_S);
+  if (!Number.isFinite(viewportWidth) || viewportWidth <= GUTTER) return 100;
+  return (viewportWidth - GUTTER - 2) / span;
+}
+
+/**
+ * The rendered timeline extent in px. Always covers, whichever is largest:
+ * the actual clip content, the visible viewport (no dead black after short
+ * content — CapCut-style), a live drag or resize ghost plus the auto-scroll
+ * margin (drag/trim-to-extend), and the MIN_TIMELINE_EXTENT_S floor. Only the
+ * RENDERED extent grows; clip positions/durations are untouched.
+ */
+export function getTimelineDisplayContentWidth(input: {
+  trackContentWidth: number;
+  viewportWidth: number;
+  pps: number;
+  dragGhostEndPx?: number;
+  resizeGhostEndPx?: number;
+}): number {
+  const safePps = Number.isFinite(input.pps) ? Math.max(input.pps, 0) : 0;
+  return Math.max(
+    input.trackContentWidth,
+    input.viewportWidth - GUTTER - 2,
+    input.dragGhostEndPx ?? 0,
+    input.resizeGhostEndPx ?? 0,
+    MIN_TIMELINE_EXTENT_S * safePps,
+  );
+}
+
 /* ── Scroll / zoom helpers ────────────────────────────────────────── */
 export function shouldAutoScrollTimeline(
   zoomMode: ZoomMode,
@@ -180,7 +233,10 @@ export function getTimelinePlayheadLeft(time: number, pixelsPerSecond: number):
 }
 
 export function getTimelineCanvasHeight(trackCount: number): number {
-  return RULER_H + Math.max(0, trackCount) * TRACK_H + TIMELINE_SCROLL_BUFFER;
+  // RULER_H + top pad + lanes + bottom pad. The old TIMELINE_SCROLL_BUFFER is
+  // subsumed by TRACKS_BOTTOM_PAD (which is larger), so the drag-into-void space
+  // below the last lane is real scrollable surface, not a hidden buffer.
+  return RULER_H + TRACKS_TOP_PAD + Math.max(0, trackCount) * TRACK_H + TRACKS_BOTTOM_PAD;
 }
 
 /* ── UI helpers ───────────────────────────────────────────────────── */
@@ -245,12 +301,15 @@ export function resolveTimelineAssetDrop(
   clientY: number,
 ): { start: number; track: number } {
   const x = clientX - input.rectLeft + input.scrollLeft - GUTTER;
-  const y = clientY - input.rectTop + input.scrollTop - RULER_H;
+  const contentY = clientY - input.rectTop + input.scrollTop;
   const start = Math.max(
     0,
     Math.min(input.duration, Math.round((x / Math.max(input.pixelsPerSecond, 1)) * 100) / 100),
   );
-  const rowIndex = Math.floor(y / Math.max(input.trackHeight, 1));
+  // Row from the shared row→y inverse so the top pad is honoured; a drop in the
+  // pad above the first lane floors to row 0, a drop in the bottom pad rounds
+  // past the last lane (getDefaultDroppedTrack then appends a new track).
+  const rowIndex = Math.floor(getTimelineRowFromY(contentY));
   return {
     start,
     track: getDefaultDroppedTrack(input.trackOrder, rowIndex),

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

@@ -0,0 +1,197 @@
+import { describe, it, expect } from "vitest";
+import {
+  MARQUEE_DRAG_THRESHOLD_PX,
+  isMarqueeDrag,
+  isTimelineRulerPress,
+  getMarqueeRect,
+  getTimelineClipRect,
+  computeMarqueeSelection,
+} from "./timelineMarquee";
+import { GUTTER, TRACK_H, RULER_H, CLIP_Y, getTimelineRowTop } from "./timelineLayout";
+
+describe("isTimelineRulerPress", () => {
+  const rectTop = 500; // scroll container's viewport top
+
+  it("treats a press inside the ruler band as a ruler press (unscrolled)", () => {
+    expect(isTimelineRulerPress(rectTop, rectTop)).toBe(true);
+    expect(isTimelineRulerPress(rectTop + RULER_H - 1, rectTop)).toBe(true);
+  });
+
+  it("treats a press below the ruler band as a body press", () => {
+    expect(isTimelineRulerPress(rectTop + RULER_H, rectTop)).toBe(false);
+    expect(isTimelineRulerPress(rectTop + RULER_H + 100, rectTop)).toBe(false);
+  });
+
+  it("stays a ruler press when the body is scrolled down (sticky ruler)", () => {
+    // The ruler is position:sticky — scrolled down, its VISUAL band is still
+    // the top RULER_H px of the container. Content-space math
+    // (clientY - rectTop + scrollTop) would report y = 10 + 300 = 310 ≥ RULER_H
+    // and misclassify this as a body/marquee press; viewport-space math must
+    // still classify it as a ruler press regardless of scrollTop.
+    const scrollTop = 300;
+    const clientY = rectTop + 10; // visually on the stuck ruler
+    const contentSpaceY = clientY - rectTop + scrollTop;
+    expect(contentSpaceY).toBeGreaterThanOrEqual(RULER_H); // the old, broken signal
+    expect(isTimelineRulerPress(clientY, rectTop)).toBe(true);
+  });
+
+  it("honors a custom ruler height", () => {
+    expect(isTimelineRulerPress(rectTop + 30, rectTop, 32)).toBe(true);
+    expect(isTimelineRulerPress(rectTop + 33, rectTop, 32)).toBe(false);
+  });
+});
+
+describe("isMarqueeDrag", () => {
+  it("treats sub-threshold movement as a click, not a drag", () => {
+    expect(isMarqueeDrag(100, 50, 100, 50)).toBe(false);
+    expect(
+      isMarqueeDrag(
+        100,
+        50,
+        100 + MARQUEE_DRAG_THRESHOLD_PX - 1,
+        50 + MARQUEE_DRAG_THRESHOLD_PX - 1,
+      ),
+    ).toBe(false);
+  });
+
+  it("becomes a drag once either axis passes the threshold", () => {
+    expect(isMarqueeDrag(100, 50, 100 + MARQUEE_DRAG_THRESHOLD_PX, 50)).toBe(true);
+    expect(isMarqueeDrag(100, 50, 100, 50 + MARQUEE_DRAG_THRESHOLD_PX)).toBe(true);
+    expect(isMarqueeDrag(100, 50, 100 - MARQUEE_DRAG_THRESHOLD_PX, 50)).toBe(true);
+  });
+});
+
+describe("getMarqueeRect", () => {
+  it("builds a rect from origin to current for a down-right drag", () => {
+    expect(getMarqueeRect(10, 20, 110, 70)).toEqual({ left: 10, top: 20, width: 100, height: 50 });
+  });
+
+  it("normalizes negative drags (up-left) into a positive rect", () => {
+    expect(getMarqueeRect(110, 70, 10, 20)).toEqual({ left: 10, top: 20, width: 100, height: 50 });
+  });
+
+  it("normalizes mixed-direction drags (down-left / up-right)", () => {
+    expect(getMarqueeRect(110, 20, 10, 70)).toEqual({ left: 10, top: 20, width: 100, height: 50 });
+    expect(getMarqueeRect(10, 70, 110, 20)).toEqual({ left: 10, top: 20, width: 100, height: 50 });
+  });
+
+  it("yields a zero-size rect when the pointer has not moved", () => {
+    expect(getMarqueeRect(42, 42, 42, 42)).toEqual({ left: 42, top: 42, width: 0, height: 0 });
+  });
+});
+
+describe("getTimelineClipRect", () => {
+  const trackOrder = [0, 2, 5];
+
+  it("maps start/duration to x via pps and the track row to y via the shared row→y helper", () => {
+    const rect = getTimelineClipRect({ start: 2, duration: 3, track: 2 }, trackOrder, 100);
+    expect(rect).toEqual({
+      left: GUTTER + 200,
+      top: getTimelineRowTop(1) + CLIP_Y,
+      width: 300,
+      height: TRACK_H - CLIP_Y * 2,
+    });
+  });
+
+  it("places the first visible track below the ruler + top breathing pad", () => {
+    const rect = getTimelineClipRect({ start: 0, duration: 1, track: 0 }, trackOrder, 50);
+    expect(rect?.top).toBe(getTimelineRowTop(0) + CLIP_Y);
+    expect(rect?.left).toBe(GUTTER);
+  });
+
+  it("uses the row index in trackOrder, not the raw track number", () => {
+    const rect = getTimelineClipRect({ start: 0, duration: 1, track: 5 }, trackOrder, 50);
+    expect(rect?.top).toBe(getTimelineRowTop(2) + CLIP_Y);
+  });
+
+  it("enforces the 4px minimum rendered width", () => {
+    const rect = getTimelineClipRect({ start: 0, duration: 0.01, track: 0 }, trackOrder, 10);
+    expect(rect?.width).toBe(4);
+  });
+
+  it("returns null for a track that is not displayed or an invalid pps", () => {
+    expect(getTimelineClipRect({ start: 0, duration: 1, track: 9 }, trackOrder, 100)).toBeNull();
+    expect(getTimelineClipRect({ start: 0, duration: 1, track: 0 }, trackOrder, 0)).toBeNull();
+    expect(getTimelineClipRect({ start: 0, duration: 1, track: 0 }, trackOrder, NaN)).toBeNull();
+  });
+});
+
+describe("computeMarqueeSelection", () => {
+  // Two visible tracks: row 0 = track 0, row 1 = track 1. pps 100.
+  const trackOrder = [0, 1];
+  const pps = 100;
+  const clips = [
+    { id: "a", start: 0, duration: 1, track: 0 }, // x [32,132], row 0
+    { id: "b", start: 2, duration: 1, track: 0 }, // x [232,332], row 0
+    { id: "c", start: 0.5, duration: 1, track: 1 }, // x [82,182], row 1
+  ];
+  const row0Top = getTimelineRowTop(0) + CLIP_Y;
+  const row1Top = getTimelineRowTop(1) + CLIP_Y;
+
+  it("selects only the clips the marquee rect intersects", () => {
+    const marquee = { left: GUTTER, top: row0Top, width: 50, height: 10 };
+    const { ids, primaryId } = computeMarqueeSelection({ clips, trackOrder, pps, marquee });
+    expect(ids).toEqual(new Set(["a"]));
+    expect(primaryId).toBe("a");
+  });
+
+  it("selects across tracks when the rect spans multiple rows", () => {
+    const marquee = { left: GUTTER, top: row0Top, width: 60, height: row1Top - row0Top + 5 };
+    const { ids } = computeMarqueeSelection({ clips, trackOrder, pps, marquee });
+    expect(ids).toEqual(new Set(["a", "c"]));
+  });
+
+  it("excludes clips outside the rect horizontally", () => {
+    const marquee = { left: GUTTER + 140, top: row0Top, width: 50, height: 10 };
+    const { ids } = computeMarqueeSelection({ clips, trackOrder, pps, marquee });
+    expect(ids).toEqual(new Set());
+  });
+
+  it("returns null primaryId and keeps the base when nothing is hit (additive)", () => {
+    const marquee = { left: GUTTER + 140, top: row0Top, width: 50, height: 10 };
+    const { ids, primaryId } = computeMarqueeSelection({
+      clips,
+      trackOrder,
+      pps,
+      marquee,
+      baseSelection: ["b"],
+    });
+    expect(ids).toEqual(new Set(["b"]));
+    expect(primaryId).toBeNull();
+  });
+
+  it("unions additive base selection with new hits; primary comes from the marquee", () => {
+    const marquee = { left: GUTTER, top: row1Top, width: 100, height: 10 };
+    const { ids, primaryId } = computeMarqueeSelection({
+      clips,
+      trackOrder,
+      pps,
+      marquee,
+      baseSelection: ["b"],
+    });
+    expect(ids).toEqual(new Set(["b", "c"]));
+    expect(primaryId).toBe("c");
+  });
+
+  it("shrinking the rect live drops clips it no longer covers", () => {
+    const wide = { left: GUTTER, top: row0Top, width: 320, height: 10 };
+    const narrow = { left: GUTTER, top: row0Top, width: 80, height: 10 };
+    expect(computeMarqueeSelection({ clips, trackOrder, pps, marquee: wide }).ids).toEqual(
+      new Set(["a", "b"]),
+    );
+    expect(computeMarqueeSelection({ clips, trackOrder, pps, marquee: narrow }).ids).toEqual(
+      new Set(["a"]),
+    );
+  });
+
+  it("ignores clips on hidden/undisplayed tracks", () => {
+    const marquee = { left: 0, top: 0, width: 10000, height: 10000 };
+    const { ids } = computeMarqueeSelection({
+      clips: [{ id: "x", start: 0, duration: 1, track: 7 }],
+      trackOrder,
+      pps,
+      marquee,
+    });
+    expect(ids).toEqual(new Set());
+  });
+});

package/src/player/components/timelineMarquee.ts

@@ -0,0 +1,112 @@
+import { GUTTER, TRACK_H, RULER_H, CLIP_Y, getTimelineRowTop } from "./timelineLayout";
+import { rectsOverlap, type Rect } from "../../utils/marqueeGeometry";
+
+/** Pointer must travel at least this far (either axis) before a pointerdown on
+ *  the empty timeline body becomes a marquee drag instead of a plain click. */
+export const MARQUEE_DRAG_THRESHOLD_PX = 4;
+
+/** Minimum rendered clip width, mirrors TimelineClip's `Math.max(w, 4)`. */
+const MIN_CLIP_W = 4;
+
+export interface MarqueeClipInput {
+  id: string;
+  start: number;
+  duration: number;
+  track: number;
+}
+
+/**
+ * Ruler-vs-body decision for a pointerdown on the timeline scroll container.
+ *
+ * The ruler is `position: sticky; top: 0` — once the body is scrolled down its
+ * VISUAL position stays pinned to the container top while its LAYOUT position
+ * scrolls away. The hit test must therefore use VIEWPORT-space y (clientY
+ * relative to the scroll container's bounding rect), NOT content-space y
+ * (clientY - rect.top + scrollTop), which misclassifies a press on the stuck
+ * ruler as a body/marquee press whenever scrollTop > 0.
+ */
+export function isTimelineRulerPress(
+  clientY: number,
+  scrollRectTop: number,
+  rulerHeight: number = RULER_H,
+): boolean {
+  return clientY - scrollRectTop < rulerHeight;
+}
+
+export function isMarqueeDrag(
+  originX: number,
+  originY: number,
+  currentX: number,
+  currentY: number,
+  threshold: number = MARQUEE_DRAG_THRESHOLD_PX,
+): boolean {
+  return Math.abs(currentX - originX) >= threshold || Math.abs(currentY - originY) >= threshold;
+}
+
+/** Normalized marquee rect (canvas/content coordinates) from the drag origin and
+ *  the current pointer — handles drags in any direction (negative deltas). */
+export function getMarqueeRect(
+  originX: number,
+  originY: number,
+  currentX: number,
+  currentY: number,
+): Rect {
+  return {
+    left: Math.min(originX, currentX),
+    top: Math.min(originY, currentY),
+    width: Math.abs(currentX - originX),
+    height: Math.abs(currentY - originY),
+  };
+}
+
+/**
+ * A clip's rendered rect in canvas/content coordinates (the same space the
+ * marquee rect lives in): x from GUTTER + start * pps, y from the clip's row
+ * index within the visible track order (RULER_H + row * TRACK_H + CLIP_Y).
+ * Returns null when the clip's track is not currently displayed.
+ */
+export function getTimelineClipRect(
+  clip: Pick<MarqueeClipInput, "start" | "duration" | "track">,
+  trackOrder: number[],
+  pps: number,
+): Rect | null {
+  const row = trackOrder.indexOf(clip.track);
+  if (row < 0 || !Number.isFinite(pps) || pps <= 0) return null;
+  return {
+    left: GUTTER + clip.start * pps,
+    top: getTimelineRowTop(row) + CLIP_Y,
+    width: Math.max(clip.duration * pps, MIN_CLIP_W),
+    height: TRACK_H - CLIP_Y * 2,
+  };
+}
+
+export interface MarqueeSelectionResult {
+  /** Every clip id the marquee currently covers (plus the additive base). */
+  ids: Set<string>;
+  /** The last marquee-hit clip in element order — the primary selection.
+   *  Null when the marquee covers nothing new (caller keeps its current primary). */
+  primaryId: string | null;
+}
+
+/**
+ * Live marquee selection: every clip whose rendered rect intersects the marquee.
+ * `baseSelection` (shift/cmd-additive) is unioned in but never affects primaryId.
+ */
+export function computeMarqueeSelection(input: {
+  clips: MarqueeClipInput[];
+  trackOrder: number[];
+  pps: number;
+  marquee: Rect;
+  baseSelection?: Iterable<string>;
+}): MarqueeSelectionResult {
+  const ids = new Set<string>(input.baseSelection ?? []);
+  let primaryId: string | null = null;
+  for (const clip of input.clips) {
+    const rect = getTimelineClipRect(clip, input.trackOrder, input.pps);
+    if (rect && rectsOverlap(rect, input.marquee)) {
+      ids.add(clip.id);
+      primaryId = clip.id;
+    }
+  }
+  return { ids, primaryId };
+}

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

@@ -0,0 +1,127 @@
+import { describe, it, expect } from "vitest";
+import {
+  clampGroupMoveDelta,
+  isMultiDragActive,
+  isMultiDragPassenger,
+  multiDragDeltaSeconds,
+  multiDragPassengerOffsetPx,
+  type MultiDragPreviewInput,
+} from "./timelineMultiDragPreview";
+
+const base = (over: Partial<MultiDragPreviewInput> = {}): MultiDragPreviewInput => ({
+  dragStarted: true,
+  draggedKey: "a",
+  draggedOriginStart: 2,
+  draggedPreviewStart: 5,
+  selectedKeys: new Set(["a", "b", "c"]),
+  ...over,
+});
+
+describe("isMultiDragActive", () => {
+  it("is active when a started drag's clip is part of a 2+ selection", () => {
+    expect(isMultiDragActive(base())).toBe(true);
+  });
+
+  it("is inactive before the drag starts", () => {
+    expect(isMultiDragActive(base({ dragStarted: false }))).toBe(false);
+  });
+
+  it("is inactive for a single-clip selection (single-drag behavior)", () => {
+    expect(isMultiDragActive(base({ selectedKeys: new Set(["a"]) }))).toBe(false);
+  });
+
+  it("is inactive when the dragged clip is not itself selected", () => {
+    expect(isMultiDragActive(base({ draggedKey: "z" }))).toBe(false);
+  });
+});
+
+describe("multiDragDeltaSeconds (the one formation delta)", () => {
+  it("is the grabbed clip's preview − origin start when active", () => {
+    // The preview start is already group-clamped upstream, so this delta is the
+    // clamped delta every member (ghost + passengers) moves by.
+    expect(multiDragDeltaSeconds(base())).toBe(3);
+  });
+
+  it("supports a leftward (negative) delta", () => {
+    expect(multiDragDeltaSeconds(base({ draggedPreviewStart: 0.5 }))).toBeCloseTo(-1.5);
+  });
+
+  it("is zero when no multi-drag is active", () => {
+    expect(multiDragDeltaSeconds(base({ selectedKeys: new Set(["a"]) }))).toBe(0);
+  });
+});
+
+describe("isMultiDragPassenger", () => {
+  it("marks a selected non-dragged clip as a passenger", () => {
+    expect(isMultiDragPassenger("b", base())).toBe(true);
+    expect(isMultiDragPassenger("c", base())).toBe(true);
+  });
+
+  it("never marks the dragged clip itself (it is the free ghost)", () => {
+    expect(isMultiDragPassenger("a", base())).toBe(false);
+  });
+
+  it("never marks an unselected clip", () => {
+    expect(isMultiDragPassenger("d", base())).toBe(false);
+  });
+
+  it("marks nothing when the drag is a single-drag", () => {
+    const single = base({ selectedKeys: new Set(["a"]) });
+    expect(isMultiDragPassenger("b", single)).toBe(false);
+  });
+});
+
+describe("multiDragPassengerOffsetPx (rigid: every passenger shares the delta)", () => {
+  it("converts the one formation delta to pixels for every passenger", () => {
+    // Both passengers move by the SAME 3s × 100pps = 300px — spacing locked.
+    expect(multiDragPassengerOffsetPx("b", 100, base())).toBe(300);
+    expect(multiDragPassengerOffsetPx("c", 100, base())).toBe(300);
+  });
+
+  it("is zero for the dragged clip and for non-passengers", () => {
+    expect(multiDragPassengerOffsetPx("a", 100, base())).toBe(0);
+    expect(multiDragPassengerOffsetPx("d", 100, base())).toBe(0);
+  });
+
+  it("is zero for a non-finite pps", () => {
+    expect(multiDragPassengerOffsetPx("b", Number.NaN, base())).toBe(0);
+  });
+
+  it("follows a leftward delta", () => {
+    expect(multiDragPassengerOffsetPx("c", 50, base({ draggedPreviewStart: 0 }))).toBe(-100);
+  });
+});
+
+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);
+  });
+
+  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);
+  });
+
+  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("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("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("returns the raw delta for an empty formation", () => {
+    expect(clampGroupMoveDelta(-9, [])).toBe(-9);
+  });
+});