refactor(studio): extract timeline render contracts

[miguel-heygen]

What

Extract timeline rendering contracts and orchestration helpers needed by viewport virtualization.

Why

The original Timeline component mixed view-model construction, lane contracts, tick generation, selection lifecycle, modifier state, and player synchronization. Virtualization needs those decisions to have explicit owners without introducing parallel geometry or state paths.

How

• Introduce focused lane, ruler, view-model, selection, modifier, tick, and player-sync modules.
• Keep Timeline as the orchestrator while preserving existing rendering behavior.
• Reuse the extracted contracts in later row and clip windows.

This is D4 of the Family D draft review sequence. It targets current main after Family C landed; its Family D patch was replayed without semantic changes. It supersedes legacy PRs #2635 and #2636, which remain open for audit until landing.

Test plan

• Unit tests added/updated
• Manual testing performed
• Documentation updated (not applicable)

Validated on the exact Family D tip through Timeline and timeline-layout coverage, the full Studio suite, both package typechecks, formatting, lint, file-size checks, and the strict 50,000-element Chromium gate.

2026-07-29 rebase verification

• Replayed D1-D8 onto current main after Family C landed; git range-diff marks every old/new Family D commit exactly equivalent (=).
• oxfmt, oxlint, changed-file size gate, Studio typecheck, and Studio Server typecheck passed.
• Full Studio suite: 288 files passed, 3,168 tests passed, 18 todos. Full Studio Server suite: 29 files and 398 tests passed.
• Fallow CI audit exited successfully; its five minor observations are local duplication in existing test harness setup, not duplicated production decisions.
• Chrome 150 browser evidence: 1,000-element control passed 5/5; strict 50,000-element gate passed its 4/5 quorum with 10 mounted rows, 240 mounted clip roots, 995 timeline descendants, approved direct scrolling, and memory returned. Repeated samples showed the same host-timing outlier pattern on the exact pre-rebase control.

No merge was performed; this PR remains a draft.

[miguel-heygen]

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

• ci(studio): run the timeline viewport gate on studio changes #2884
• perf(studio): stop timeline scroll work when row virtualization is off #2883
• perf(studio): virtualize timeline clip windows #2703
• perf(studio): add timeline clip-window index primitive #2702
• perf(studio): add dev-gated timeline row virtualization #2701
• perf(studio): centralize timeline viewport geometry #2700
• refactor(studio): extract timeline render contracts #2699 👈 (View in Graphite)
• refactor(studio): isolate clip drag lifecycle #2698
• test(studio): gate timeline viewport performance in Chromium #2697
• perf(studio): define timeline viewport budgets and fixtures #2696
• main

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

[vanceingalls]

Verdict: APPROVE — grade B+ — rubric CORRECT

Role in stack: D4 refactor — pre-virtualization render-contract extraction. Stacks cleanly onto D3.

Root-cause fit: The extraction gives D5-D8 the seams they need: ticks (useTimelineTicks/timelineRulerGeometry), selection lifecycle (useTimelineSelectionLifecycle), shift modifier, preview-element derivation (getTimelinePreviewElement), duration & keyframe predicates (timelineViewModel), and the player-sync equality check (timelinePlayerSync). Row-height / thumbnail-request / context-menu-target contracts are still baked into the orchestrator — D4 explicitly scopes to ruler/selection/modifier/view-model, deferring is fine so long as D5 exposes row measurement without a re-extraction round.

Claims verified (file:line at HEAD 4edbc701):

• Timeline.tsx +21/-71: selectedElement/selectedElementRef/shiftHeld-effect/tick-useMemo/getPreviewElement bodies removed; only local consumers, no dangling refs.
• timelineLayout.ts -118/+2: tick logic moved out; re-exports formatTimelineTickLabel/generateTicks from ruler module — no import-path breakage.
• New files are .ts (hooks/helpers only, no JSX) — Fast Refresh compliant.
• Named exports only, import type on pure-type imports.
• No any, no @ts-ignore, no disabled tests, no new TODOs. Pre-existing eslint-disable react-hooks/exhaustive-deps moved verbatim.
• Bit-identical output: hasKeyframedTimelineClips, getEffectiveTimelineDuration, getTimelinePreviewElement, tick math, timelineElementsChanged line-for-line equivalent (identifier renames only).

Adversarial findings:

• Nit — element-identity duplication: the element.key ?? element.id fallback is inlined in getTimelinePreviewElement and useTimelineSelectionLifecycle. D5-D8 will need the same fallback for keying — worth a one-liner timelineElementIdentity(el) helper in timelineViewModel.ts now.
• Nit — narrowed union: useTimelineTicks accepts timeDisplayMode: "time" | "frame" inline instead of importing the store type; drifts silently if playerStore extends the mode.
• Nit — doc erosion: timelineRulerGeometry.ts drops the "Nice NLE steps" / "frame-labels-must-be-whole-frames" explanatory comments — the load-bearing why for these two functions.
• Nit — indirection: useTimelineTicks imports generateTicks from ./timelineLayout (which re-exports), not from source ./timelineRulerGeometry.

CI state: Required checks green.

Suggested next step: Land as-is. Address the element-identity helper in D5 where row/clip windows will re-introduce the key ?? id fallback, and consider a follow-up to restore the tick-generation docstrings.

— Review by Via

[miguel-heygen]

Addressed at 2b894982b.

• New render-contract code reuses the existing getTimelineElementIdentity owner.
• TimelineTimeDisplayMode now has one exported type owner.
• Restored the ruler’s explanatory comments about interval selection, whole-frame steps, subdivisions, drift avoidance, and the safety cap.
• Removed the timelineLayout tick re-export path; ruler consumers import the ruler geometry directly.

[miguel-heygen]

Reviewed the exact #2699 delta (6958e61..2b89498), not the rest of the stack.\n\nThe refactor is clean: ruler geometry, view-model derivation, selection lifecycle, Shift tracking, tick generation, and player-sync decisions move behind narrow modules without changing their algorithms. The current head also resolves the prior review drift: it reuses getTimelineElementIdentity, shares TimelineTimeDisplayMode, restores the semantic comments, and imports ruler geometry directly instead of through the Timeline re-export. Window listeners in the new Shift hook are paired with cleanup, and I found no new import cycle or production side effect.\n\nCoverage remains primarily behavioral through the existing Timeline/player tests rather than unit tests for every extracted pure helper; that is acceptable for this mechanical delta. Exact-head lightweight checks are green/skipped as expected, with Graphite mergeability pending on the downstack chain. It must wait for #2697s blocker, but this delta itself is approvable.\n\nGitHub will not let the shared author identity submit a formal approval, so recording the verdict as a PR comment.\n\nVerdict: APPROVE\nReasoning: The render-contract extraction preserves behavior, improves ownership boundaries, and introduces no lifecycle or dependency regression.\n\n— Magi