perf(studio): add timeline clip-window index primitive

[miguel-heygen]

What

Add the immutable per-row clip-window index primitive consumed by D8.

Exact-PR scope

This PR deliberately does not call the index from Timeline, pass a render range, or change runtime rendering by itself. Runtime horizontal clip/ruler windowing and actor-pin wiring land in the immediate child PR, #2703.

How

• Build intervals in original projection order and sort a query view by clip start.
• Build balanced max trees for positive-duration ends and zero/negative-duration point starts.
• Prune both branches that cannot reach the requested time window, avoiding the prior prefix-max full backward scan.
• Query overlaps with half-open boundaries and union explicit identity pins.
• Restore original projection order before returning results.

Construction is O(n log n) from sorting. The overlap tree walk is O((k + 1) log n) for k matches; identity-pin lookup is proportional to pinned matches, followed by sorting the unique result set back into projection order.

Test plan

• 50,000-clip adversarial row: one early full-duration clip plus 49,999 ended clips queried near the end
• Deterministic randomized oracle coverage
• Boundary, point, duplicate-identity, pin, immutable-snapshot, and fractional-row coverage
• Full Studio suite: 291 files / 3,195 tests
• Studio typecheck, oxfmt, and oxlint
• Exact-tip Chrome 50k virtualized gate passed required quorum through D8 adoption

Review fixes are included at head 06c0f1df5.

[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 👈 (View in Graphite)
• perf(studio): add dev-gated timeline row virtualization #2701
• perf(studio): centralize timeline viewport geometry #2700
• 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 9 findings.

Duplication (6)

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

Health (3)

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)
minor	fallow/high-crap-score	packages/studio/src/player/lib/timelineClipIndex.ts:41	'createTimelineClipMaxTrees' has CRAP score 31.6 (threshold: 30.0, cyclomatic 10)
minor	fallow/high-crap-score	packages/studio/tests/e2e/timeline-virtualization.mjs:388	'<arrow>' has CRAP score 30.0 (threshold: 30.0, cyclomatic 5)

Generated by fallow.

[miguel-heygen]

Addressed at 4f820c4e3.

• Added deterministic randomized fuzz coverage against a linear oracle across windows, negative/zero durations, scoped identities, and actor pins.
• Added construction/rebuild and query complexity documentation without overstating the backward scan’s worst case.
• Reused the canonical timeline element identity helper in both index code and tests.

[miguel-heygen]

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

Important — this PR does not yet window the runtime clip/ruler render path. Repository-wide use at this head finds no production caller of createTimelineClipIndex or queryTimelineClipIndex; Timeline never computes/passes renderTimeRange; and useTimelineTicks.ts:12-14 still calls generateTicks without the new range. The only non-test references to TimelineTimeRange are optional helper/prop definitions. Therefore the exact delta still scans and renders the complete horizontal project, despite the title/body saying visible clip windows are indexed and actor pins are preserved. If adoption intentionally belongs to the next stack PR, scope this PR honestly as index/windowing primitives; otherwise wire and integration-test the behavior here.

Important — the advertised visible-window bound is not guaranteed by the prefix-max scan. timelineClipIndex.ts:111-116 walks backward while the prefix maximum crosses the range start. One early full-duration clip makes that prefix maximum large for every later position, so a query near the end scans all preceding short, already-finished clips: O(total row clips) work to return one overlapping clip. The current “long-lived earlier interval” test has only two entries and the randomized oracle checks correctness, not visited work. Add an adversarial 50k shape and either use a structure that can prune both branches (for example an interval/segment tree) or explicitly narrow the complexity/performance claim.

The overlap boundaries, duplicate identities, pin union, projection order, fractional row keys, and randomized oracle are otherwise well tested.

Verdict: REQUEST CHANGES
Reasoning: The exact PR currently has no runtime performance effect, and its core query can still degrade to the full-row scan the PR claims to remove.

— Magi

[miguel-heygen]

Resolved at 06c0f1df5.

Scope is now explicit in both the commit/PR title and body: D7 adds the clip-window index primitive only. It has no production caller and no runtime render effect at this exact PR; #2703 is the immediate child that wires the primitive into Timeline, ruler ranges, and actor pins.

The prefix-max backward scan is replaced with balanced max trees:

• one tree stores maximum positive-duration ends;
• one stores maximum point starts for zero/negative-duration clip semantics;
• the query prunes either branch when neither tree can reach the requested window.

This prevents one early full-duration clip from forcing a scan through every already-ended clip. The complexity claim is narrowed to the implemented bound: O((k + 1) log n) for the overlap walk, plus pin lookup and result-order sorting.

A new adversarial test builds 50,000 clips—one early full-duration clip and 49,999 short ended clips—then queries a late window. The complete clip-index suite, randomized oracle, full Studio suite (291 files / 3,195 tests), and exact-tip 50k Chromium gate pass.

The base branch was changed.