perf(studio): centralize timeline viewport geometry

[miguel-heygen]

What

Centralize the stable, layout-owned timeline viewport geometry used by row layout, visible-range derivation, scrolling snapshots, indexes, and playback consumers.

Scope boundary

This PR does not migrate every coordinate read to the cached geometry model. Gesture-time code in range selection, playhead interaction, reveal, editing, and drag preview intentionally keeps direct getBoundingClientRect() / scrollLeft reads where pointer freshness matters. The shared model owns stable layout geometry; live pointer handlers own live DOM coordinates.

How

• Add immutable TimelineRowGeometry snapshots with identity-based caching.
• Centralize viewport snapshots and time/content conversion.
• Reuse the existing canonical timeline element identity helper in the new element index.
• Keep project-reset state owned by the D1 helper while adding D5 session-boundary behavior.

Test plan

• Geometry, viewport, track-layout, element-index, player-store, and Timeline tests
• Full Studio suite
• Studio typecheck, oxfmt, and oxlint

Review fixes are included at head b15627d5e.

[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 👈 (View in Graphite)
• refactor(studio): extract timeline render contracts #2699
• 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.

[github-actions]

Fallow audit report

Found 5 findings.

Duplication (4)

Severity	Rule	Location	Description
minor	fallow/code-duplication	packages/studio/src/player/components/timelineClipDragGestureLifecycle.ts:56	Code clone group 1 (25 lines, 2 instances)
minor	fallow/code-duplication	packages/studio/src/player/components/useTimelineClipDrag.ts:359	Code clone group 1 (25 lines, 2 instances)
minor	fallow/code-duplication	packages/studio/src/player/components/useTimelineTrackLayout.test.ts:26	Code clone group 2 (25 lines, 2 instances)
minor	fallow/code-duplication	packages/studio/src/player/components/useTimelineTrackLayout.test.ts:73	Code clone group 2 (25 lines, 2 instances)

Health (1)

Severity	Rule	Location	Description
minor	fallow/high-crap-score	packages/studio/src/player/hooks/useTimelinePlayer.ts:69	'syncTimelineElements' has CRAP score 31.6 (threshold: 30.0, cyclomatic 10)

Generated by fallow.

[vanceingalls]

Verdict: APPROVE — grade B — rubric PARTIAL

Role in stack: D5 refactor — viewport geometry centralization (SSOT for scroll/zoom/time-to-x + row-index-to-y across drag, marquee, layout, active clips, scrub).

Root-cause fit: Good. New timelineViewportGeometry.ts owns time-range + row anchoring; useTimelineScrollViewport owns DOM reads (scrollLeft/Top/clientW/H + isScrolling + RO wiring + settled-timer). timelineLayout.ts owns row geometry as a frozen TimelineRowGeometry (binary-search y↔row over cumulative offsets, WeakMap-cached per height-array), consumed by drag/marquee/drop through rowGeometryRef.

Claims verified (file:line at HEAD 9e92dbc9):

• New module timelineViewportGeometry.ts:1-31 — getTimelineVisibleTimeRange + getTimelineScrollTopForGeometryChange.
• Snapshot hook useTimelineScrollViewport.ts:47-155 — rAF-throttled viewport publish + settled timer + RO + shortcut-hint sync.
• Row geometry SSOT timelineLayout.ts:78-172 — immutable TimelineRowGeometry, WeakMap cache, binary search in getRowFromY.
• Element indexes timelineElementIndexes.ts:1-43 — one scan per snapshot, WeakMap-cached; consumed by Timeline.tsx:118, useTimelineClipDrag.ts:761, playbackScrub.ts:6.
• Test coverage Timeline.test.ts:47-66, useTimelineScrollViewport.test.tsx, timelineElementIndexes.test.ts.

Adversarial findings:

• P2 — Callsite migration is partial. PR body claims "one geometry model owns scroll, drag, selection, layout, playback". useTimelineRangeSelection.ts:1155-1339 still does its own scrollRef.current?.getBoundingClientRect() / .scrollLeft / .scrollTop reads for pointer→content mapping; useTimelinePlayhead.ts (16 refs), useTimelineRevealClip.ts (10 refs), timelineEditing.ts (9 refs), timelineClipDragPreview.ts also bypass the snapshot. Defensible for pointer-freshness (state snapshot lags by rAF + settled timeout), but the body language is stronger than what shipped — worth naming the exceptions.
• P3 — setTimelineScale writer with no reader. playerStore.ts:480-486 adds non-reactive timelinePps/timelineFitPps, published from useTimelineGeometry.ts:465-467. No consumer exists. useTimelineEditPinning.ts:41 still pins via ppsRef.current / fitPpsRef.current. Docstring names pinTimelineZoomToCurrent, absent. Prep for D6 — call it out or drop it.
• P3 — In-place mutation on Zustand state. state.timelinePps = pps sidesteps set() — silent hazard if anyone selects this field via usePlayerStore(s => s.timelinePps). Comment warns "never read as render input", but the type is public. A Symbol-keyed scratch or plain module-level ref would advertise the contract more loudly.
• Nit — getTimelineVisibleTimeRange ships zero overscan; callers should know. end clamps to duration (comp), not displayDuration (extent) — semantically "visible clip time," which the name doesn't disclose.
• Nit — Reference stability: TimelineScrollViewportSnapshot is a fresh object every rAF while scrolling; downstream useMemo([viewport]) will re-run each frame. Consumers should destructure fields.

Standards: No new any, empty catch, TODO, disabled test. oxfmt/oxlint/typecheck pass. useEffect uses are external-system sync — permitted.

CI state: All 8 required checks pass. Graphite mergeability_check pending (transient).

Suggested next step: Land as-is (awaits Family D landing order). Follow-up: either delete the unused setTimelineScale/timelinePps writer or ship its consumer in D6, and document the pointer-freshness carve-out in the geometry module header.

— Review by Via

[miguel-heygen]

Addressed at b15627d5e.

• The PR body now explicitly limits the shared geometry claim to stable/layout-owned snapshots and documents the live DOM reads retained for pointer freshness.
• The new element index reuses the canonical timeline identity helper.
• The project reset snapshot now has one owner in D1; D5 only adds its session-boundary behavior.
• setTimelineScale and its non-reactive Zustand scratch fields predate Family D (introduced in feat(studio): revamps Studio + improves code quality #2291 / df29fa7a5) and are not changed by this PR, so that cleanup remains outside D5’s patch scope.

[miguel-heygen]

Exact-delta review at 02ca243f1a (additive to the existing review).

I audited all 29 changed files: the row-geometry/store/index production paths, every migrated caller, focused tests, and the Chromium harness. I am not treating the rest of the stack as evidence for this PR.

No new actionable finding. The geometry conversion remains symmetric at the boundaries; row snapshots are rebuilt from immutable array identities; session changes reset scroll ownership once; and the resource audit is clean (ResizeObserver, rAF, scroll-settle timer, PerformanceObserver, probe page, and browser are all released on their terminal paths). The PR body now accurately limits the SSOT claim to stable layout geometry and leaves gesture-time DOM reads explicitly live.

The exact functional CI is green. Graphite's remaining state is a stack/dependency gate, not a failing check in this delta.

Verdict: APPROVE
Reasoning: The exact delta preserves behavior while centralizing the stable geometry contract, and I found no additional correctness, lifecycle, or cleanup defect beyond feedback already recorded on the PR.

— Magi