feat(studio): timeline lane-zone model

[ukimsanov]

What

new pure module timelineZones — visual/audio track-zone classification (classifyZone) and normalizeToZones, which re-packs lanes into zone-consistent rows; tests cover the stacking/zones interaction.

Why

completes the z-model started in the stacking-sync PR.

How

new files; consumes isAudioTimelineElement (leaf-helpers PR) and computeStackingPatches (stacking-sync PR); type-only playerStore imports.

Test plan

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

---

Stack position 8/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 👈 (View in Graphite)
• 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
• 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) — the keystone of the two-way agreement

The most consequential math in this batch, and the tests reflect it: a whole section is devoted to the qa-clean regression that motivated the rewrite (whole-track ordering by MAX z carried a low-z clip above a covering higher-z clip), a section to reload stability, and a section to the round-trip with #2198's computeStackingPatches. Round-trip convergence is not asserted merely by construction — it is exercised end-to-end.

The pointed queries

• Correctness of normalizeToZones — no zone identity violations. packages/studio/src/player/components/timelineZones.ts:164–:198 splits elements into visual and audio arrays (:170–:174 by classifyZone), packs each independently, and never reassigns across zones. A clip in zone X remains in zone X after re-packing — the identity property. #2199's tests at :76–:87 (drops audio below the visual lanes even when sharing a track index, groups multiple audio tracks at the bottom) verify this end-to-end.
• Empty and single-lane edges. :165 short-circuits an empty input (return elements — same reference, no reallocation). Single-element inputs pack into lane 0 (verified implicitly by all one-clip contexts). No off-by-one at zero.
• Stacking invariants preserved. The per-clip pack at :100–:117 sorts by zOf(b) - zOf(a) || b.domIndex - a.domIndex || key — deterministic, stable, and (critically) using the INPUT domIndex, not the mutated lane, as the tie-break. The comment at :86–:88 flags this correction from the historical oscillation bug (tie-breaking on the mutated output caused non-termination). Test at :187–:195 (tie-breaks equal-z overlapping clips on the STABLE id, not the mutated lane) pins the invariant.
• Fixed point / idempotence. :99–:107, :197–:206, :252–:256, :308–:315 all pass. The claim normalizeToZones(normalizeToZones(x)) === normalizeToZones(x) is asserted structurally (lane per id equal after two passes) across multiple shapes.
• Round-trip with #2198 — the cross-PR invariant. :332–:405 is the money test. Two scenarios: (1) authored order a(z=1)/b(z=5), user drags a above b, computeStackingPatches emits a→6, re-normalize returns a to lane 0 — convergent. (2) qa-clean drag video below ralu → cascade patches → re-normalize places video below ralu. Both scenarios also verify computeStackingPatches(renormalized) === [] — the fixed-point signature. This is the invariant Batch-A pivots on and it is nailed.
• Reload stability. :208–:219, :258–:262 verify that fresh objects with the same z produce identical lanes across two independent normalizations. Discovery re-runs are deterministic.
• Half-open overlap. :25–:27 mirrors #2198 with the same EPS = 1e-6 — consistent within the stacking half of this batch.

Nits (non-blocking)

• The zone-identity property (visual stays visual, audio stays audio) is guaranteed by construction (:170–:174) but never asserted directly. A one-line invariant test on a mixed input would document what the split ensures — nice-to-have, not needed.
• The EPS = 1e-6 epsilon convention is now in two files (timelineStackingSync.ts and here). Consider a shared TIMELINE_EPSILON constant at some point to avoid drift if one is ever tuned — cosmetic.

R1 by Via