feat(studio): on-canvas motion-path overlay

[miguel-heygen]

Stack: GSAP keyframe + motion-path editing — on-canvas overlay (#1553 → #1561).

What

Render the selected element's GSAP motion path over the canvas: a dashed polyline through its x/y keyframes (or motionPath waypoints) with a draggable diamond node at each. Dragging a node rewrites the keyframe and commits to source; clicking a node selects that keyframe and seeks to its time.

Why

Direct, visual editing of motion paths in the Studio, matching the keyframe diamonds in the timeline.

How

• MotionPathOverlay.tsx + MotionPathNode.tsx: SVG overlay drawn in declared composition coordinates, positioned over the preview iframe (which lives in the player's shadow DOM), so the path doesn't drift under GSAP transforms or canvas zoom/pan.
• Integrates the geometry/commit helpers; read-only while playing.
• useDomEditOverlayRects.ts / StudioPreviewArea.tsx / DomEditOverlay.tsx: overlay positioning + wiring.

Test plan

• Manual studio: path renders, nodes drag + commit, click-to-select-keyframe
• Verified across canvas zoom levels

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

[jrusso1020]

Approved at ba99ae07 per Rames D Jusso "stamp-ready with 3 nits." On-canvas motion-path overlay — UI layer, no architectural concerns. Deferring his 3 nits to inline resolution.

Reminder: PR body is the unfilled template (stack-wide process flag); please fill in before merge.

[vanceingalls]

Concurring with the consolidated stack review at HEAD 676ba067. One add: where the cheap test-gap-closing units live.

The 559-line overlay is mostly SVG render + pointer-event delegation into already-tested helpers (buildMotionPathGeometry, nearestPointOnPath, commitNode, commitAddWaypoint, parkPlayheadOnKeyframe). Two testable units could be lifted out with low ceremony and would pin the parts most prone to silent regression:

• elementHome (packages/studio/src/components/editor/MotionPathOverlay.tsx:53-78) — the DOM-walk plus --hf-studio-offset-x/y inclusion rule. A jsdom + manual offset-stubbing test pins the "translate var() detection" branch, which is exactly the clever-but-fragile heuristic prone to silent regression on iframe-realm changes.
• isPreviewHtmlElement (MotionPathOverlay.tsx:84-91) — the cross-realm constructor check. Four lines of test demonstrate the iframe-realm path.

The orchestrating render is genuinely event-delegation glue where unit value is low; an @testing-library/react smoke test that asserts "given a geometry, N nodes render at the expected coordinates" would be a cheap follow-up but is the lower-priority option. Not a blocker — these closures sharpen confidence post-merge rather than gate it.

Review by Via

[jrusso1020]

Re-approved at f9e5f4fd post-restack. On-canvas motion-path overlay; clean UI layer.

Echoing Via's R2 finding: two testable units worth extracting for cheap coverage closure — elementHome (MotionPathOverlay.tsx:53-78, DOM-walk + offset-rule, jsdom-testable) and isPreviewHtmlElement (:84-91, cross-realm constructor check, 4-line test). Non-blocking, fine as a follow-up.