@hyperframes/studio 0.7.55 → 0.7.57

package/src/player/components/timelineLayout.ts

@@ -7,104 +7,172 @@ 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;
+/**
+ * Fit-mode headroom (CapCut-style): "fit" maps `duration * 1.2` — not the bare
+ * duration — onto the viewport, so the composition ends at ~83% of the width
+ * and the trailing ~17% stays empty ruler + droppable lane surface (room to
+ * drag clips past the current end without first zooming out). Applied ONLY
+ * inside {@link getTimelineFitPps}, the single fit-pps source, so the ruler,
+ * lanes, playhead, marquee, and drag math all inherit it consistently. Manual
+ * zoom percentages stay defined relative to this fit basis (100% == fit).
+ */
+export const FIT_ZOOM_HEADROOM = 1.2;
 
 /* ── Tick generation ──────────────────────────────────────────────── */
-function getMajorTickInterval(duration: number, pixelsPerSecond?: number): number {
-  const zoomIntervals = [0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 15, 30, 60, 120, 300, 600];
+// fallow-ignore-next-line complexity
+function getMajorTickInterval(
+  duration: number,
+  pixelsPerSecond?: number,
+  frameRate?: number,
+): number {
+  // "Nice" NLE steps: 1-2-5 sub-second decades, then 1s/2s/5s/10s/15s/30s,
+  // minute multiples, and 15m/30m/1h so ultra-zoomed-out long comps still get
+  // readable (non-colliding) labels instead of the old 10m fallback everywhere.
+  const zoomIntervals = [
+    0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 15, 30, 60, 120, 300, 600, 900, 1800, 3600,
+  ];
+  let interval: number;
   if (Number.isFinite(pixelsPerSecond) && (pixelsPerSecond ?? 0) > 0) {
     const targetMajorPx = 88;
-    return (
-      zoomIntervals.find((interval) => interval * (pixelsPerSecond ?? 0) >= targetMajorPx) ?? 600
-    );
+    interval =
+      zoomIntervals.find((candidate) => candidate * (pixelsPerSecond ?? 0) >= targetMajorPx) ??
+      3600;
+  } else {
+    const durationIntervals = [0.25, 0.5, 1, 2, 5, 10, 15, 30, 60];
+    const target = duration / 6;
+    interval = durationIntervals.find((candidate) => candidate >= target) ?? 60;
+  }
+  // Frame display mode: labels are frame numbers, so a major step must be a
+  // WHOLE number of frames — sub-frame steps produce duplicate/uneven labels
+  // (e.g. 0.02s at 30fps is 0.6 frames → "0, 1, 1, 2, 2…"). Snap UP (ceil) so
+  // the label spacing never drops below the readability target.
+  if (Number.isFinite(frameRate) && (frameRate ?? 0) > 0) {
+    const fps = frameRate ?? 0;
+    return Math.max(1, Math.ceil(interval * fps - 1e-6)) / fps;
   }
-  const durationIntervals = [0.25, 0.5, 1, 2, 5, 10, 15, 30, 60];
-  const target = duration / 6;
-  return durationIntervals.find((interval) => interval >= target) ?? 60;
+  return interval;
 }
 
-function getMinorTickInterval(majorInterval: number, pixelsPerSecond?: number): number {
-  if (
-    Number.isFinite(pixelsPerSecond) &&
-    (pixelsPerSecond ?? 0) > 0 &&
-    (majorInterval / 2) * (pixelsPerSecond ?? 0) < 12
-  ) {
-    return 0;
+// 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). In frame display mode
+// the subdivision must also keep minor ticks on WHOLE frames (a minor tick at a
+// sub-frame time is not a seekable position), so only divisors of the major
+// step's frame count qualify — quarters, then fifths (15/30-frame majors),
+// thirds, halves.
+// fallow-ignore-next-line complexity
+function getMinorSubdivisions(
+  majorInterval: number,
+  pixelsPerSecond?: number,
+  frameRate?: number,
+): number {
+  const pps = Number.isFinite(pixelsPerSecond) ? (pixelsPerSecond ?? 0) : 0;
+  if (pps <= 0) return 4; // no zoom info (duration-fit mode): quarter ticks
+  const fps = Number.isFinite(frameRate) ? (frameRate ?? 0) : 0;
+  const majorFrames = fps > 0 ? Math.round(majorInterval * fps) : 0;
+  const candidates = fps > 0 ? [4, 5, 3, 2] : [4, 2];
+  for (const parts of candidates) {
+    if (fps > 0 && majorFrames % parts !== 0) continue;
+    if ((majorInterval / parts) * pps >= 8) return parts;
   }
-  return majorInterval / 2;
+  return 0;
+}
+
+// Ticks are exact multiples of the interval (multiplied per index, never
+// accumulated with `+=`, so long rulers don't drift), then rounded to 1µs to
+// keep values/keys clean without disturbing frame-exact positions like 2/30s.
+function roundTickValue(t: number): number {
+  return Math.round(t * 1e6) / 1e6;
 }
 
 export function generateTicks(
   duration: number,
   pixelsPerSecond?: number,
+  frameRate?: number,
 ): { major: number[]; minor: number[] } {
-  if (duration <= 0 || !Number.isFinite(duration) || duration > 7200)
+  if (duration <= 0 || !Number.isFinite(duration) || duration > 14400)
     return { major: [], minor: [] };
-  const majorInterval = getMajorTickInterval(duration, pixelsPerSecond);
-  const minorInterval = getMinorTickInterval(majorInterval, pixelsPerSecond);
+  const majorInterval = getMajorTickInterval(duration, pixelsPerSecond, frameRate);
+  const subdivisions = getMinorSubdivisions(majorInterval, pixelsPerSecond, frameRate);
+  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);
+  for (let i = 0; major.length < maxTicks; i++) {
+    const t = i * majorInterval;
+    if (t > duration + 0.001) break;
+    major.push(roundTickValue(t));
+    // 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 = t + k * minorInterval;
+      if (m <= duration + 0.001) minor.push(roundTickValue(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 +196,47 @@ 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 plus
+ * FIT_ZOOM_HEADROOM trailing headroom (CapCut-style — the comp never slams
+ * into the right edge), and 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 * FIT_ZOOM_HEADROOM, 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,
@@ -174,13 +283,33 @@ export function getTimelineScrollLeftForZoomAnchor(input: {
 }
 
 /* ── Playhead / canvas ────────────────────────────────────────────── */
+/**
+ * Width of the playhead wrapper element (== the diamond head chip's layout
+ * width, which the wrapper shrink-wraps to). The 1px vertical line inside
+ * PlayheadIndicator is centered at 50% of this wrapper, so the wrapper must be
+ * shifted LEFT by half this width for the line's center to land exactly on
+ * `GUTTER + time * pps` — see {@link getTimelinePlayheadLeft}.
+ */
+export const PLAYHEAD_HEAD_W = 9;
+
+/**
+ * The `left` for the playhead WRAPPER such that the vertical line's CENTER
+ * sits exactly on `GUTTER + time * pps` (the same x the ruler ticks center
+ * on) at every zoom level. Without the half-head offset the line sat
+ * `PLAYHEAD_HEAD_W / 2` px to the right of its ruler tick.
+ */
 export function getTimelinePlayheadLeft(time: number, pixelsPerSecond: number): number {
-  if (!Number.isFinite(time) || !Number.isFinite(pixelsPerSecond)) return GUTTER;
-  return GUTTER + Math.max(0, time) * Math.max(0, pixelsPerSecond);
+  if (!Number.isFinite(time) || !Number.isFinite(pixelsPerSecond)) {
+    return GUTTER - PLAYHEAD_HEAD_W / 2;
+  }
+  return GUTTER + Math.max(0, time) * Math.max(0, pixelsPerSecond) - PLAYHEAD_HEAD_W / 2;
 }
 
 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 +374,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 };
+}