refactor(studio): isolate clip drag lifecycle

[miguel-heygen]

What

Extract clip-drag pointer-session lifecycle handling into one focused helper without changing drag semantics.

Why

Virtualized rows can unmount during a pointer session. The drag lifecycle needs one stable actor that owns capture, movement, cancellation, and exactly-once terminal cleanup before rendering becomes windowed.

How

• Move pointer-session lifecycle logic out of the rendering hook.
• Keep the existing drag mutation and snapping behavior intact.
• Preserve explicit terminal cleanup so duplicate local/window events cannot commit twice.

This is D3 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 PR #2634, which remains 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 the focused Timeline interaction suite, full Studio suite, 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
• refactor(studio): isolate clip drag lifecycle #2698 👈 (View in Graphite)
• 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 A — rubric CORRECT

Role in stack: D3 refactor — clip-drag pointer-session lifecycle extracted to a mount-only helper so D5-D8 can virtualize rows without shredding an in-flight drag.

Root-cause fit: The extracted mountTimelineClipDragGestureLifecycle attaches pointermove/pointerup/pointercancel/keydown to window (never to a row DOM node), and every piece of live state is read through refs. Callsite is useMountEffect, the sanctioned single-effect wrapper. Net: a row scroll-out cannot detach listeners or nullify state — the survival property D5-D8 leans on.

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

• Extraction only, no semantic drift: useTimelineClipDrag.ts:1-6,29 deletes local resolveTimelineDragEscape import + inline handlers, delegates at :271-296.
• Window-scoped listeners with symmetric cleanup incl. capture:true on keydown: timelineClipDragGestureLifecycle.ts:236-249.
• Terminal cleanup null-first-then-commit blocks double-commit on duplicate up events: commitDragPointerUp (:191-206), commitResizePointerUp (:136-172) — ref cleared BEFORE commit; a second up sees null.
• Escape resets all four refs + group session in one pass: handleWindowKeyDown :213-232.
• File-list/additions match PR envelope (+287/-216 → +259 new file, +28/-216 modified).

Adversarial findings:

• P2 (note) — Non-ref params captured at mount: updateElement (Zustand, stable), restoreGroupResizeMembers (useCallback stable), React setters (stable). setShowPopover is a prop; if any parent supplies an inline function, the mount closure holds the first-render one for the hook's lifetime. Grep the caller before D5 lands to confirm stabilization.
• P2 (note) — PR body checks "Unit tests added/updated" but diff has zero test files. Behavior is exercised by the existing Timeline interaction suite, but the row-unmount-mid-drag guarantee itself — D3's core contribution — has no explicit test.

CI state: All required checks green.

Suggested next step: Land as-is. Before D5 merges, add one focused unit test that mounts the hook, starts a drag, unmounts+remounts the row's pointerdown wiring, moves the pointer, and asserts the drag preview updates + commits — that's the invariant this PR sets up and D5-D8 will silently rely on.

— Review by Via

[miguel-heygen]

Addressed at 6958e6186.

• Verified the sole caller passes the setter returned by useState, whose identity is stable across renders; no ref indirection is needed for setShowPopover.
• Added an explicit regression test that removes the originating row mid-gesture, then proves the window-scoped pointer move and pointer up still update and persist the drag.

[miguel-heygen]

Reviewed the exact #2698 delta (287a998..6958e61), not the rest of the stack.\n\nThe extraction preserves the prior gesture semantics while moving pointermove/up/cancel and Escape handling to window scope. Listener installation/removal is symmetric, capture options match, autoscroll is stopped on terminal paths, refs are cleared before commits, and the sole caller supplies Reacts stable state setter. The new lifecycle test now removes the source row mid-gesture and proves the window-scoped move/up path still previews and commits exactly once.\n\nOne non-blocking lifecycle note: clearSuppressedClick still schedules an untracked requestAnimationFrame, so dispose cannot cancel that callback. This behavior predates the extraction, but tracking/canceling it would make the helper fully self-contained under StrictMode/remount churn.\n\nCurrent exact-head lightweight checks are green/skipped as expected; Graphite mergeability remains pending because #2697 is downstack. This PR must not land until #2697s blocker is resolved, but I found no blocker in this delta.\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 clip-drag lifecycle extraction is behavior-preserving, cleans up its owned global listeners, and now covers row unmount during an active gesture.\n\n— Magi