feat(studio): split clip at playhead for media elements [7/10]

[miguel-heygen]

Summary

• Add splitElementInHtml to core source mutation — clones element, adjusts timing/media-start
• split-element API endpoint
• handleTimelineElementSplit handler with media-only guard
• Clip context menu: right-click → Split at Xs
• S keyboard shortcut
• Toolbar split button (Phosphor Scissors icon)

+245 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
• feat(studio): split clip at playhead for media elements [7/10] #1189 👈 (View in Graphite)
• 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]

Clean focused PR — split a media clip at the playhead. +245/-0. Right-sized scope.

Verify before merge:

1. Media-only guard placement

PR body says "media-only guard" and "Split restricted to media only (video/audio/img)". Two layers needed:

• Server-side (in splitElementInHtml or the API endpoint): rejects split requests on non-media elements with a clean 400, not a silent no-op or partial mutation.
• Client-side: the right-click menu item + S shortcut don't fire on non-media selections.

If only client-side gates, an adversarial / agent caller can still POST a split mutation against a <div> and get unpredictable behavior. Worth checking both layers.

2. Splitting an element with keyframes

splitElementInHtml clones the element and adjusts timing/media-start. For a <video> with no keyframes, this is straightforward. For a media element that's also a GSAP tween target, what happens to the keyframes?

• Cloned element gets a new id (probably). Existing GSAP tween targets the old id → no longer targets the new clone. Acceptable? Or should the tween split too?
• If split happens at t=50% of the clip's window and the keyframes are at 0%/50%/100% of the clip, the post-split clip should arguably retain 50%/100% keyframes (relative) and the pre-split clip should retain 0%/50%. Likely out of scope for this PR (PR body says "media-only"), so the keyframe-target divergence is a non-issue — just confirm the documented contract.

3. Edge cases for the S shortcut

• Playhead at clip boundary: split at t=0 or t=clip.duration. Should be a no-op or produce zero-length clips? Test plan worth covering.
• Playhead outside any clip: no-op.
• Multiple clips selected: split applies to all? Just one? Reject?

4. Phosphor Scissors icon

Verify the icon is already in the project's existing icon set (Phosphor is likely already a dep). If this PR adds Phosphor for the first time, the dep addition belongs in the PR description.

Non-blocking

The splitElementInHtml function is now part of the core source mutation surface. If this gets called from agent flows or external consumers, document its semantics in the JSDoc — particularly the "what gets cloned" (style attrs? class attrs? data-* attrs?) contract.

Review by Jerrai (hyperframes specialist)