feat(studio): multi-clip drag preview math

[ukimsanov]

What

new pure module timelineMultiDragPreview — group-drag passenger offsets and clamped group deltas (isMultiDragActive, multiDragDeltaSeconds, multiDragPassengerOffsetPx, clampGroupMoveDelta) with tests.

Why

the group-drag math, standalone and DOM-free.

How

new files only; consumed later by TimelineLanes.

Test plan

bunx vitest run timelineMultiDragPreview.test.ts; tsc --noEmit; fallow audit clean.

---

Stack position 6/25 — studio NLE overhaul (CapCut-parity timeline + canvas). Graphite manages bases; merge from #2192 upward. Temporary TEMP(studio-dnd) fallow entries (unwired-component windows) are all removed by #2213 (app-shell swap), whose tree is byte-identical to the fully-verified integration branch.

[ukimsanov]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(studio): assets/blocks panel behaviors + preview helpers #2216
• feat(studio): timeline visual refresh #2215
• feat(studio): clip thumbnail modules #2214
• feat(studio): app shell swap — mount EditorShell, retire the legacy engine #2213
• feat(studio): timeline glue swap — Timeline/TimelineCanvas onto the NLE engine #2212
• feat(studio): canvas glue swap — overlay, gestures, selection to final form #2211
• feat(studio): sidebar asset card (unwired) #2210
• feat(studio): NLE shell assembly (unwired) #2209
• feat(studio): canvas chrome components (unwired) #2208
• feat(studio): timeline interaction hooks and lanes component (unwired) #2207
• feat(studio): clip drag engine — preview and commit (unwired) #2206
• feat(studio): glue API coexistence layer for the NLE swap #2205
• feat(studio): NLE shell components — context provider, panes, overlays (unwired) #2204
• feat(studio): arrow-key nudge step math (unwired) #2203
• feat(studio): canvas context menu and z-order actions (unwired) #2202
• test(studio): characterization suites for resize commit and razor history #2201
• feat(studio): asset click policy and canvas nudge gate #2200
• feat(studio): timeline lane-zone model #2199
• feat(studio): timeline z-stacking sync model #2198
• feat(studio): multi-clip drag preview math #2197 👈 (View in Graphite)
• feat(studio): timeline magnetic snapping #2196
• feat(studio): timeline collision and placement model #2195
• feat(studio-server): files route extensions #2194
• feat(studio): seek-restore contract for player reloads #2193
• feat(studio): timeline leaf helpers — audio inspector, zoom math, UI prefs #2192
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miga-heygen]

Reviewed as part of the 25-PR NLE overhaul stack. Full stack review on #2205 (the keystone). No blockers on this PR. — Miga

[vanceingalls]

Verdict: LGTM (green) — rigid group, no shearing

A concise study in "the formation moves as one". Every passenger inherits the same delta; the leftmost member sets the floor; the grabbed clip stops with the group rather than out-running it. That is the correct model.

The pointed queries

• Group-clamping by the leftmost element (no shearing). packages/studio/src/player/components/timelineMultiDragPreview.ts:100–:106 — clampGroupMoveDelta reads minStart = Math.min(...memberStarts) and bounds rawDelta ≥ -minStart. The test at :113–:116 nails the invariant: grabbed clip at 10, passenger at 1, clampGroupMoveDelta(-8, [10, 1, 4]) === -1. The passenger — not the grabbed clip — sets the floor. This is precisely the "group shears if you per-element-clamp" bug the module documents at :90–:98.
• Individual snap participation vs group delta. The module's own docstring at :2–:20 is explicit: the preview start (draggedPreviewStart) is ALREADY group-clamped upstream (updateDraggedClipPreview runs clampGroupMoveDelta before setting it), so the delta this module returns is by construction the clamped delta. Passengers inherit it via multiDragPassengerOffsetPx (:74–:82). Snap participation happens for the grabbed clip at the upstream layer; the group moves rigidly by its outcome. That's the correct sequencing.
• Unit consistency. multiDragDeltaSeconds returns seconds (:52–:55); multiDragPassengerOffsetPx converts to pixels via explicit × pps at :81 and treats Number.isFinite(pps) ? pps : 0 (guards NaN input, tested at :86–:88). Clean boundary.
• Edge cases exercised. Zero-delta when inactive (:49), leftward negative delta (:45), NaN pps → 0 offset (:87), already-at-0 forbids further leftward (:118–:122), empty formation returns raw delta (:124).

One observation (not a blocker)

• Line :103 uses Math.min(...memberStarts) — for extremely large selections (10k+ elements) this can spread-args the call stack. Timeline selections are single-digit-to-dozens in practice, so purely theoretical. Would memberStarts.reduce((a, b) => a < b ? a : b) be more defensive? Yes. Necessary here? No.

R1 by Via