feat(studio): runtime-first dynamic keyframe system [8/10]

[miguel-heygen]

Summary

• Read GSAP keyframes from live runtime (tween.vars.keyframes) instead of AST only
• hasUnresolvedKeyframes / hasUnresolvedSelector flags on GsapAnimation
• scanAllRuntimeKeyframes discovers all keyframed tweens in the iframe
• materializeKeyframesInScript + unrollDynamicAnimations — on first edit, dynamic loops are replaced with individual static tl.to() calls
• Keyframe cache: interval-based runtime scan, dual-write keys, immediate update from mutation response
• easeEach placement fix (inside keyframes object, not tween vars level)
• Retry effect for cold-load animation fetch race

+773 LOC

[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): runtime-synced design panel + 3D props + split polish #1188
• fix(studio): overlay jump, delete-all, split polish [9/10] #1191
• feat(studio): runtime-first dynamic keyframe system [8/10] #1190 👈 (View in Graphite)
• feat(studio): split clip at playhead for media elements [7/10] #1189
• feat(studio): design panel, timeline polish, feature flag [6/6] #1172
• feat(studio): keyframe hooks wiring — session, cache, toolbar [5/6] #1171
• feat(studio): keyframe diamonds, navigation, context menu [4/6] #1170
• feat(studio): GSAP runtime bridge + optimistic updates [3/6] #1169
• feat(core): spring physics solver + runtime fixes [2/6] #1168
• feat(core): GSAP keyframe parsing, mutations, and API routes [1/6] #1167
• main

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

[jrusso1020]

The most architecturally consequential PR in the back half of the stack. +773/-38. Reshapes keyframe discovery from "AST-only" to "runtime-first": Studio reads tween.vars.keyframes from the live iframe rather than relying solely on the AST parse. Plus materializeKeyframesInScript / unrollDynamicAnimations to convert dynamic loops into individual tl.to() calls on first edit.

The key risk: AST↔runtime divergence

The "runtime-first" model means there are now two sources of truth for what a tween is:

1. AST parse of the source script.
2. Live tween.vars from the running iframe.

Some keyframes (the "dynamic" ones — generated by a JS loop like for (let i = 0; i < 10; i++) tl.to(...)) only exist in the runtime view, not the AST. The hasUnresolvedKeyframes / hasUnresolvedSelector flags + materializeKeyframesInScript are the bridge.

Things to verify:

1. Materialization is idempotent

Calling materializeKeyframesInScript on a script that's already been materialized should be a no-op. Otherwise repeated edits compound the unroll and the script grows linearly with edit count.

2. Runtime scan interval

PR body says "interval-based runtime scan". What interval? If it's too tight (< 200ms), it's a perf cost on every Studio session. If too loose (> 2s), the panel feels stale during animation creation. Worth a comment in the code explaining the chosen value.

3. Cold-load race + retry effect

"Retry effect for cold-load animation fetch race" — this hints at a known timing issue. The retry strategy matters:

• Bounded retries: if the runtime never produces tween data, the retry should eventually give up (not loop infinitely).
• Exponential backoff or fixed interval: either is fine, but document.
• User-visible feedback: if retry is exhausted, the user should see "couldn't load keyframes" rather than an empty panel.

4. unrollDynamicAnimations and edit semantics

When a dynamic loop like for (let i = 0; i < 10; i++) tl.to("#item-" + i, ...) is unrolled into 10 static tl.to() calls on first edit:

• The unroll is destructive — you lose the original loop expression. Confirm this is documented as an intentional, irreversible transformation (user can undo at the AST level, but they can't get the original loop back without writing it again).
• Selector resolution: each unrolled call gets a concrete selector. If the loop used "#item-" + i, the unrolled output should be "#item-0", "#item-1", etc. Verify against tests.
• Comment / docstring: the unroll comment ideally says "originally generated by loop at line N" so the human reader understands what happened.

5. easeEach placement fix

The fix is the right call — easeEach belongs inside the keyframes: {} object, not at the tween-vars level. This is consistent with GSAP's documented placement. The fix in this PR likely corrects a regression from earlier in the stack (looks like #1167's tween-level easeEach propagation logic had it at the wrong level for emit but right level for parse). Worth a quick parse↔serialize round-trip test that asserts easeEach ends up in the same JSON shape on both sides.

6. Dual-write cache keys

"Dual-write keys" in the keyframe cache — what's the second key for? Migration from old key shape? Coexistence with the legacy code path? Worth a comment explaining the dual-write window (and when one of them can be removed).

This is a meaty PR — I'd push for a screenshot or video showing the live-runtime keyframe panel responding to a scrub before merging.

Review by Jerrai (hyperframes specialist)