feat(studio): GSAP drag/commit/bridge editing infra

[miguel-heygen]

Stack: GSAP keyframe + motion-path editing — drag/commit bridge (#1553 → #1561).

What

Infrastructure to edit GSAP-animated elements by direct manipulation: a runtime bridge that routes canvas drags into keyframe / tween source mutations instead of CSS patches.

Why

Dragging a GSAP-owned element via CSS corrupts its transform (GSAP owns style.transform and rewrites it every tick). Geometry edits must resolve the live tween and commit through script mutation.

How

• gsapRuntimeBridge.ts: resolves the live position tween for a selection and intercepts drag/resize/rotation.
• gsapDragCommit.ts: converts a drag delta into a keyframe / flat-tween edit (auto-converting a flat tween to keyframes when needed).
• useGsapAwareEditing.ts: routes geometry commits to the bridge, falling back to CSS only for non-GSAP elements.
• manualEditsDom.ts: GSAP-animated elements push the offset through gsap.set and keep translate:none rather than composing a CSS translate on top of GSAP's matrix.

Test plan

• Unit tests added (drag commit, runtime bridge, GSAP-aware apply)
• Manual studio drag of GSAP elements

[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
• 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 👈 (View in Graphite)
• 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]

Async-semantics axis — second-pass correction crediting @rames-jusso

Updating my take. Rames flagged the commitMutation facade's broken await semantics in a parallel review, and he's right. My initial pass declared it "internally consistent" because I checked what comes AFTER each await commitMutation(...) — and in useGestureCommit / useEnableKeyframes the next step is showToast(...) or return. I concluded the await was "vestigial but harmless." That was wrong — I missed that the showToast("Recorded N keyframes", "info") at useGestureCommit.ts:198 is itself a UI claim that depends on save success. With the facade's promise now resolving on next microtask (before the save lands), on a save failure the user sees:

1. The optimistic "Recorded N keyframes" toast (because we already "succeeded"), then
2. The wrapper's "Couldn't save animation: ..." toast from safeGsapCommit's .catch().

Two contradictory toasts. The outer try/catch in useGestureCommit is also dead for save errors now — they're swallowed by the wrapper, never re-thrown.

Verified findings (still valid)

• The facade type signature didn't change — outer fn still returns Promise<void> — so callers compile without warning. The semantic break is invisible to TypeScript.
• No pre-existing try/catch on the 2-arg facade path; the dead try/catch is in NEW code (useGestureCommit) added in this same PR.
• The 3-arg commitMutation(selection, mutation, options) chain is untouched — useGsapKeyframeOps.ts:121,192 continue to chain .catch() correctly on the underlying CommitMutation.

Endorsing Rames's fix

Easiest mitigation matches his suggestion: have useSafeGsapCommitMutation return the inner promise instead of returning void, so await semantics hold:

return useCallback(
  (selection, mutation, options) =>
    commitMutation(selection, mutation, options).catch((error) => {
      trackGsapSaveFailure(error, selection, mutation, options.label);
      showToast?.(`Couldn't save animation: ${getStudioSaveErrorMessage(error)}`, "error");
    }),
  [...],
);

That keeps the caller's await honest AND keeps the toast-on-error behavior. Drop the void prefix, return the chained promise.

Lesson for me

Tracing "what comes after the await" was the wrong frame. The right question was "does the resolution timestamp of this promise carry meaning to downstream UI claims?" — and showToast("Recorded...") IS such a claim. Calibration for the next async-semantics pass.

— Review by tai (pr-review)