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 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 A — rubric CORRECT

Role in stack: D7 data-structure — immutable per-row clip-window index (sorted-by-start + prefixMaxEnd + byIdentity) that D8's virtualizer will query for visible time-range slices.

Root-cause fit: Correct shape for the access pattern. Timeline queries are build-once (per tracks snapshot) / query-many-per-frame (scroll, zoom, overscan). Sorted-by-start with a monotonically non-decreasing prefixMaxEnd gives O(log n + k) queries via upperBoundStart(end) - 1 then walk-backward while prefixMaxEnd[cursor] >= range.start — classic Cormen interval-stabbing pruning, beats a segment tree in constant factors, no rebalance cost. Per-row scoping matches how the virtualizer will fetch one row at a time.

Claims verified (file:line at HEAD 143d281b):

• Immutable per-row + prefix-max: timelineClipIndex.ts:47-67 (Object.freeze on byStart, prefixMaxEnd, byIdentity, row entry, outer rows).
• Overlap query returns projection order: :110-118 (final sort by ordinal, then map to element).
• Identity pins survive filter: :105-108 (byIdentity.get(identity) ?? []).
• Half-open [start, end) semantics consistent: interval-at-range.end excluded (overlaps L90); zero-duration point at range.end correctly excluded. Tested at timelineClipIndex.test.ts:22-34.
• Negative-duration coerced to 0-duration point via Math.max(0, element.duration) (L34) — no infinite-result pathology; explicitly asserted.
• Non-finite guards on both start and duration — Infinity correctly excluded.
• 8 files, +399/-22. Matches PR body.

Adversarial findings:

• Nice-to-have — no property/fuzz test comparing query vs O(n) linear-scan reference; hand-crafted cases cover the edges but a 100-random × 100-query fuzz would raise confidence.
• Nice-to-have — in-place mutation of TimelineElement.start after index build leaves interval.start/end frozen but the returned element fresh. Safe under React/Zustand setElements (new array each time), but worth a one-line JSDoc so future callers don't reach in and mutate.
• Nice-to-have — range.end < range.start silently returns pins-only; consider an early assertion.
• Nice-to-have — Big-O not documented in module JSDoc.
• D7→D8 handoff note: rebuild-only. Correct for build-once/query-many; D8 must memoize on tracks identity. Flag for D8 review. (Confirmed D8 does memoize — see #2703 review.)

CI state: All required green.

Suggested next step: APPROVE and land. Ask D8 to (1) memoize on tracks identity (done), (2) add one fuzz test at the D7/D8 boundary comparing queryTimelineClipIndex against a linear-scan oracle over 1k random intervals, (3) add a one-line JSDoc on createTimelineClipIndex noting the "snapshot at build" mutation contract.

— Review by Via

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