feat(studio): keyframes flag, gesture recording + timeline/selection refinements

[miguel-heygen]

Stack: GSAP keyframe + motion-path editing — feature flag, gesture recording, timeline polish (top of #1553 → #1561).

What

Ties the feature together and adds the remaining tooling:

• Feature flag gating keyframe editing (useEnableKeyframes).
• Gesture recording — record pointer motion over time and commit it as keyframes.
• Keyframe navigation UI (prev/next + add/remove/convert diamond per property).
• Razor split for clips, plus timeline / selection refinements.

Why

The keyframe/motion-path surface ships behind a flag; gesture recording gives a fast way to author motion; the navigation + razor tooling rounds out the timeline editing experience.

How

• useEnableKeyframes.ts: flag + enablement gate.
• useGestureRecording.ts: samples pointer position over the timeline, simplifies (RDP), and commits keyframes (merge into an overlapping tween, else add a new range).
• KeyframeNavigation.tsx: per-property diamond (add / remove / convert) + prev/next seek.
• useRazorSplit.ts: split a clip at the playhead.
• useDomSelection.ts / useStudioContextValue.ts / StudioHeader.tsx / NLELayout.tsx / RenderQueue.tsx: selection + timeline refinements (selection survives inspector collapse, etc.).

Test plan

• Unit tests added (keyframe navigation, enable-keyframes)
• Manual studio: gesture record → keyframes, navigation, razor split, selection persistence

[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

• feat(studio): keyframes flag, gesture recording + timeline/selection refinements #1561 👈 (View in Graphite)
• feat(studio): on-canvas motion-path overlay #1560
• feat(studio): motion-path geometry + commit helpers #1559
• feat(studio): GSAP drag/commit/bridge editing infra #1558
• feat(studio): GSAP runtime read layer + shared helpers #1557
• feat(cli): add keyframes command to surface motion paths #1556
• feat(core): route motion-path mutations through studio-api + fix clip stamping #1555
• feat(core): add GSAP keyframe + motion-path source mutations #1554
• chore(producer): shim __filename/__dirname in the CJS banner #1553
• main

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

[terencecho]

Stack-wide process note (Rames covered structure / 2 concerns on this PR)

Endorsing @rames-jusso's #1561 take in full — playerStore.ts:374-379 exposing the full Zustand store via window.__playerStore in prod is a real footgun (anyone with devtools access can call __playerStore.setState({...}) to mutate selection/elements/playing); and the clipToTweenPercentage 1-keyframe edge using a clipPct fallback IS the same pattern this PR fixes elsewhere. Both should land before merge.

Stack-wide process observation (non-blocking, easy fix for next stack)

All 9 PR descriptions across this stack are the unfilled PR template. For a stack with several PRs north of +500 LOC (and the +651/-4 core-mutations PR #1554 being load-bearing), the empty bodies mean reviewers (human and bot) and future archaeologists have nothing to anchor to — no "what / why / how / test plan" content. Commit messages cover the what well, but PR-body framing of why doesn't survive a bisect via the GitHub UI.

This stack is heavily test-backed and Graphite-anchored, so structural intent is recoverable from diff + commit messages. Not blocking — just a process nudge for the next stack.

Test-coverage map across the 9-PR stack (from my axis pass)

PR	Files	Test files	Notes
#1553	2	0	banner shim, n/a
#1554	5	2	strong (parity + parser units)
#1555	4	1	adequate
#1556	3	0	CLI surface, typical no-unit
#1557	7	3	strong
#1558	8	3	strong on new infra
#1559	6	2	strong on pure-logic helpers
#1560	5	0	UI overlay, typical no-unit
#1561	19	5	very strong

— Review by tai (pr-review)

[vanceingalls]

Concurring with the consolidated review's two author-response gates at HEAD 878d25a2 (both verified still open):

1. packages/studio/src/player/store/playerStore.ts:377-379 — window.__playerStore ships unguarded in prod. Verified at HEAD: only the SSR typeof window !== "undefined" guard wraps it; there is no import.meta.env.DEV or process.env.NODE_ENV === "development" gate. Production users get the full Zustand mutating surface via __playerStore.setState({...}).
2. packages/studio/src/components/editor/KeyframeNavigation.tsx:32-46 — clipToTweenPercentage 1-anchor edge. Verified at HEAD: if (mapped.length < 2) return clipPct; returns clip-relative clipPct when only one keyframe has a tweenPercentage, which is exactly the off-by-tween-offset silent no-op the PR's own comment block (:115-126) calls out as the bug pattern this PR is fixing. Identity-slope at one anchor (mapped[0].tweenPercentage! + (clipPct - mapped[0].percentage)) is the right fallback.

Two depth additions from my pass:

3. useEnableKeyframes behavioural change is migration-safe. The diff narrows scope to the "no existing animation" branch only — the kfAnim branch at useEnableKeyframes.ts:126-137 and the flat-anim branch are untouched. New behaviour: a single keyframe at the playhead via resolveNewTweenRange-clamped start, matching the stated intent ("creating 0%+100% up front showed two diamonds for a single add keyframe"). Existing compositions with keyframes already enabled take the unchanged kfAnim branch — they are not migrated. resolveNewTweenRange ships with regression coverage in useEnableKeyframes.test.ts including the auto-stamp data-start="0"/data-duration=14 scenario. Ungating is appropriate here because the regression risk is one-way (better, not worse) for a brand-new gesture.

4. Drive-by behavioural changes verified non-regressive. (a) Timeline-element key-form fix — buildTimelineElementKey recomputed with domId/selector to match the store's hash form; backed by useExpandedTimelineElements.test.ts (+34) and studioHelpers.test.ts (+32); a pure fix to a selection-highlight bug. (b) setSelectedElementId clearing activeKeyframePct — comment explains the diamond-click ordering invariant; sensible and contained. (c) findTimelineIdByAncestor — additive, tried only when findMatchingTimelineElementId returns null; tested. (d) StudioHeader no longer clears DOM selection on inspector-panel collapse — strictly less destructive than before; the orphaned clearDomSelection import is correctly removed. None of (a-d) is a regression for prior muscle memory.

Title note stands: STUDIO_KEYFRAMES_ENABLED is pre-existing on main at manualEditingAvailability.ts:73; this PR adds use sites, not the flag itself.

Review by Via