feat(studio): timeline z-stacking sync model

[ukimsanov]

What

new pure module timelineStackingSync — lane order ↔ z-index reconciliation (laneIsAbove, computeStackingPatches) with tests.

Why

the single source of truth for how timeline lane order maps to canvas stacking; the ordering rules and tie-breaks live here.

How

new files only; consumed later by timelineZones and the stacking-sync hook.

Test plan

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

---

Stack position 7/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 👈 (View in Graphite)
• feat(studio): multi-clip drag preview math #2197
• 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) — permutation-preserving, cascade minimal

The z-stacking resolver's cleverness is in its restraint: try the single-clip patch first (authored z sacred), fall through to cascade only when ties or the z=0 floor make a single value inexpressible. And the cascade lifts only the neighbours that would otherwise no longer paint strictly above. Handsomely done.

The pointed queries

• Output is a valid permutation of inputs. packages/studio/src/player/components/timelineStackingSync.ts:230–:258 — patches are emitted through a changed: Map<key, zIndex> deduplicated by emitted: Set. No key appears twice; no key from elements is dropped from consideration (the resolver iterates every edited clip and every overlapping neighbour). By construction the patch set is a subset-permutation of the input keys, one z per key. No drops, no duplicates. Tested throughout — see the multi-clip test at :115–:120 ({ a: 7, b: 6 } is single-emit per key) and the cascade at :166–:180.
• Round-trip through normalizeToZones (cross-PR invariant with #2199). This is verified directly in #2199's test file at timelineZones.test.ts:332–:405 — lane-move → z patch → re-discovery orders lanes by that same z → identical lanes and qa-clean: drag video BELOW ralu → z patch → re-pack keeps it below, no oscillation. Both close the loop: computeStackingPatches(#2198) output projected onto TimelineElement.zIndex, fed back through normalizeToZones(#2199), yields a fixed point. That is the invariant this batch turns on and it is empirically nailed.
• Half-open overlap. overlapsInTime at :57–:59 uses < with an EPS = 1e-6 guard on the right side (a.start < b.start + b.duration - EPS). Different from #2195's exact strict-< — the epsilon defends against floating-point fuzz creating spurious overlaps in the stacking resolver (a visible artifact) where #2195 doesn't need it because a collision decision is boolean and idempotent. Justified divergence. Test at :109–:113: touching-but-not-overlapping intervals do NOT count — a (0..5) and b (5..5+5), no patch. Correct.
• Authored z sacred (fast path). trySingleZ at :162–:176 attempts a strictly-between integer first; only when minAbove - maxBelow < 2 or when the only above-neighbour is at z=0 does it fall to the cascade. Test at :50–:54 confirms already-correct edits yield no patch; :91–:101 confirms only-below / only-above bounds.
• Cascade minimality. liftAbove at :183–:196 sorts above-neighbours lowest-first and bumps each only if its current z ≤ the floor. Test at :166–:180 pins only the blockers move — a non-overlapping neighbour x is not touched.
• DOM-order tie-breaking. paintsAbove at :78–:82 uses domIndex when zs are equal — the sync sees the actual paint reality and doesn't under-patch on equal-z ties. Test at :145–:153 uses domIndex on equal-z clips and verifies the cascade fires.
• Audio exclusion. :123 filters out isAudio neighbours before the overlap set is computed. music neighbour test at :85–:89 pins the invariant.

Nits (non-blocking)

• overlapsInTime uses - EPS while timeRangesOverlap in #2195 uses exact <. The divergence is intentional and defensive here, but a one-line comment noting the choice would help a future reader who reads both files back-to-back and wonders whether the two are meant to align.

R1 by Via

[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.