feat(studio): timeline collision and placement model

[ukimsanov]

What

new pure module timelineCollision — zone-aware drop placement (clampTrackToZone, resolveZoneDropPlacement, resolveInsertRow, resolvePlacement, lane/overlap predicates) with its full test suite.

Why

the no-overlap core of the NLE clip-drag engine; plain functions, no DOM, no React, no store writes.

How

new files only; type-only imports from the existing playerStore. First runtime consumer arrives with the drag-engine PRs.

Test plan

bunx vitest run timelineCollision.test.ts; tsc --noEmit; fallow audit clean (all exports test-consumed).

---

Stack position 4/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
• feat(studio): timeline magnetic snapping #2196
• feat(studio): timeline collision and placement model #2195 👈 (View in Graphite)
• 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) — pure math, complete coverage

Elementary, but pleasing in its restraint. The placement resolver has been reduced to a set of unit-consistent primitives — resolvePlacement, clampTrackToZone, isInsertAllowedForZone, resolveZoneDropPlacement — each modest, each testable, each with its coverage certificate in the sibling file.

The pointed queries

• Unit consistency (seconds throughout). packages/studio/src/player/components/timelineCollision.ts:127 — timeRangesOverlap(aStart, aEnd, bStart, bEnd) operates in seconds; end = start + duration is the sole arithmetic; no pixel term contaminates the calculation. resolveInsertRow at :105 is the only pixel-domain input (rowFloat in track-height units) and returns a boundary integer — cleanly typed at the boundary.
• Half-open at the edge. timeRangesOverlap uses strict < on both sides (:127). Clip A ending at t=5 and clip B starting at t=5 → 5 < 5 is false, so they are adjacent, not overlapping. Test file at :20 pins this explicitly (touching at 2 → false). The resolveZoneDropPlacement — shares a track for sequential (non-overlapping) clips case at :245 verifies the invariant end-to-end.
• Empty inputs. resolvePlacement with a desiredTrack outside trackOrder (:188) short-circuits to { track: desiredTrack, needsInsert: false } — defensive and correct. resolveInsertRow with trackCount === 0 (:110) returns 0 (insert-at-top). Both edges named in the focus are handled.
• Zone identity preserved. clampTrackToZone (:10) and isInsertAllowedForZone (:30) form the boundary; a visual clip clamped is guaranteed to remain in the visual zone (walks up to the last visual row), an audio clip clamped is guaranteed to remain in the audio zone. Cross-tested at :256–:290.
• Self-exclusion during drag. isLaneFree(excludeKey) at :139–:147 correctly filters the dragged clip out of its own collision computation — the "placeholder-scenario" test at :121–:133 nails it.

Cross-batch coherence

Half-open convention is consistent with #2198 (overlapsInTime uses < too, with an epsilon guard); adjacent-not-overlapping is the operative contract in both.

R1 by Via

[jrusso1020]

Re-review — the fix has a mirror bug in the same function

The commit that closes Abhai's flagged empty-zone case caught the occupied-aim path via the idx === -1 → needsInsert: true return at timelineCollision.ts:189-193. But the same class of bug exists one branch above at :184-186:

if (isLaneFree(elements, desiredTrack, from, to)) {
  return { track: desiredTrack, needsInsert: false };
}
const idx = trackOrder.indexOf(desiredTrack);
if (idx === -1) return { track: desiredTrack, needsInsert: true };

The isLaneFree short-circuit fires BEFORE the idx === -1 check. When an audio clip is dropped on a visual-only timeline at a free span aimed at the sole visual track, the module returns {track: <visual>, needsInsert: false} — violating the module's own stated invariant "a clip stays in its kind-zone."

Reproduced against the shipped functions:

Case: audio on visual-only, FREE aim    → {track:0, needsInsert:false}   ← wrong kind
Case: audio on visual-only, OCCUPIED    → {track:0, needsInsert:true}    ← the fix, correct
Case: visual on audio-only, FREE aim    → {track:0, needsInsert:false}   ← mirror

normalizeToZones (#2199) papers over the display, but the intermediate contract is wrong: any caller that reads needsInsert to drive a new-lane animation, or reads track before normalize runs, is misled. Same class as the original bug this PR closes.

Fix: hoist the idx === -1 → needsInsert: true return above the isLaneFree short-circuit — ~5 LOC. Add a test parallel to the :310 occupied-aim test that reproduces the FREE-aim scenario.

— Rames Jusso

[miguel-heygen]

Re-reviewed current head and verified the addressed feedback and required behavior. Approval is for this exact head; Graphite mergeability may still be pending.