Skip to content

Commit a468550

Browse files
feat(studio): keyframe system — parser, runtime, timeline UI, design panel, gesture recording (#1311)
* feat(studio): runtime hooks — global time compiler + keyframe runtime Add the runtime bridge layer: global time compilation (tween % → clip %), soft reload after mutations, runtime keyframe preview, and keyframe commit helper. * feat(studio): runtime hooks — global time compiler + keyframe runtime Add the runtime bridge layer: global time compilation (tween % → clip %), soft reload after mutations, runtime keyframe preview, and keyframe commit helper. * feat(studio): keyframe cache + commit hooks Add hooks for keyframe cache population (tween → clip-relative %), mutation dispatch, keyframe snapping, and audio beat detection. * feat(studio): timeline UI — dopesheet diamonds + keyboard nav Add dopesheet strip with diamond keyframe indicators, timeline property rows, keyboard navigation (J/Shift+J/Delete/K), and feature gate (STUDIO_KEYFRAMES_ENABLED defaults to false). * feat(studio): design panel — arc controls + ease curve + stagger Add arc path controls (curviness slider, auto-rotate), motion path SVG overlay, ease curve visualization, stagger controls, and expanded animation card. Includes border-radius editor dependency from #1217. * feat(studio): gesture recording core Add gesture recording engine with RAF sampling, modifier key property mapping (Shift→rotationXY, Alt→rotation, Cmd→opacity), Ramer-Douglas-Peucker simplification, and ghost trail SVG overlay. * fix(studio): keyframe drag + recording bug bash 21 fixes: capture GSAP base at drag start, translate:none before gsap.set, skip reapplyPathOffsets for GSAP elements, clamp recording seek, _auto flag for 100% keyframes, overlay flash fix, block edits during recording. * feat(studio): keyframe integration wiring + docs Wire App.tsx recording orchestration, TimelineToolbar K/R buttons, PropertyPanel per-property diamonds, shortcuts panel, toast notifications, and keyframes guide documentation. All gated on STUDIO_KEYFRAMES_ENABLED (default false).
1 parent 96b8d61 commit a468550

72 files changed

Lines changed: 4422 additions & 622 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/docs.json‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,6 @@
7474
{
7575
"group": "Guides",
7676
"pages": [
77-
"guides/mcp",
7877
"guides/pipeline",
7978
"guides/html-in-canvas",
8079
"guides/website-to-video",
@@ -85,6 +84,7 @@
8584
"guides/prompting",
8685
"guides/hyperframes-vs-remotion",
8786
"guides/gsap-animation",
87+
"guides/keyframes",
8888
"guides/rendering",
8989
"guides/remove-background",
9090
"guides/hdr",
@@ -227,7 +227,6 @@
227227
"pages": [
228228
"catalog/components/grain-overlay",
229229
"catalog/components/grid-pixelate-wipe",
230-
"catalog/components/motion-blur",
231230
"catalog/components/parallax-unzoom",
232231
"catalog/components/parallax-zoom",
233232
"catalog/components/shimmer-sweep",

‎docs/guides/keyframes.mdx‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
title: Keyframes & Arc Motion
3+
description: "Edit GSAP keyframes visually in Studio — timeline diamonds, arc motion paths, and gesture recording."
4+
---
5+
6+
Studio gives you visual tools to create and edit GSAP keyframes without writing code. You can adjust animation properties in the Design Panel, convert straight-line motion into curved arcs, and record gesture-based motion by dragging elements in the preview.
7+
8+
## Timeline Keyframe Diamonds
9+
10+
When you open a composition in Studio, the timeline shows **diamond markers** on clips that have GSAP animations. Each diamond represents a keyframe — a point in time where a property value is set.
11+
12+
- **Start diamond** — where the tween begins (e.g., `x: 0`)
13+
- **End diamond** — where the tween ends (e.g., `x: 1000`)
14+
- Elements with multiple tweens show multiple diamond pairs
15+
16+
<Note>
17+
Keyframe diamonds are synthesized from your GSAP tweens automatically. Every `.to()`, `.from()`, and `.fromTo()` call produces start and end markers on the timeline.
18+
</Note>
19+
20+
## Editing Animation Properties
21+
22+
Select any animated element in the preview or timeline to open the Design Panel. The **Animation** section shows:
23+
24+
- **Method badge** — `Animate`, `Animate In`, or `Animate Out` (maps to `.to()`, `.from()`, `.fromTo()`)
25+
- **Timing** — Length (duration) and Starts at (position on timeline)
26+
- **Speed** — The GSAP ease (e.g., `power2.inOut`, `back.out(3)`)
27+
- **Speed curve** — Visual preview of the easing function
28+
- **Properties** — Each animated property (Move X, Move Y, Scale, Opacity, etc.) with its target value
29+
30+
<Steps>
31+
<Step title="Select an element">
32+
Click an animated element in the preview or its clip in the timeline. The Design Panel opens on the right.
33+
</Step>
34+
<Step title="Edit property values">
35+
Change any property value directly — for example, set Move X to `500` to make the element travel 500px. Changes apply immediately via soft reload.
36+
</Step>
37+
<Step title="Change the ease">
38+
Click the ease dropdown (e.g., "Smooth ease") to pick a different easing function. The speed curve preview updates live.
39+
</Step>
40+
<Step title="Verify in Code tab">
41+
Switch to the Code tab to see the generated GSAP code. Every Design Panel edit writes valid GSAP that renders identically in preview and headless export.
42+
</Step>
43+
</Steps>
44+
45+
## Arc Motion
46+
47+
Arc Motion converts a straight-line x/y animation into a curved path using GSAP's MotionPathPlugin. Instead of moving in a straight diagonal, the element follows a smooth arc — like tossing an object into a basket.
48+
49+
### When to Use It
50+
51+
Use Arc Motion when an element has both `x` and `y` properties in a single tween. Common examples:
52+
- Add-to-cart animations (item arcs from product to cart icon)
53+
- Throw/toss effects
54+
- Any motion that should feel physical rather than robotic
55+
56+
### Step-by-Step
57+
58+
<Steps>
59+
<Step title="Select an element with x/y motion">
60+
The element must have a `.to()` tween with both Move X and Move Y properties. Select it in the preview or timeline.
61+
</Step>
62+
<Step title="Toggle Arc Motion ON">
63+
In the Animation section of the Design Panel, find the **Arc Motion** toggle below the property list. Switch it ON.
64+
</Step>
65+
<Step title="Adjust Curviness">
66+
The **Curviness** slider controls how exaggerated the arc is:
67+
- `0` — straight line (no curve)
68+
- `1` — gentle natural arc
69+
- `1.5–2.0` — smooth throw feel (recommended)
70+
- `3.0` — extreme loop
71+
72+
Scrub the timeline to preview the arc in real time.
73+
</Step>
74+
<Step title="Toggle Auto-Rotate (optional)">
75+
Enable **Auto-Rotate** to make the element rotate to face the direction of travel along the arc. This adds a "thrown" feel vs. a "floating" feel.
76+
</Step>
77+
<Step title="Verify the generated code">
78+
Switch to the Code tab. You'll see:
79+
80+
```javascript
81+
tl.to("#element", {
82+
scale: 0.4,
83+
opacity: 0,
84+
duration: 1.0,
85+
ease: "power2.inOut",
86+
motionPath: {
87+
path: [{x: 0, y: 0}, {x: 1400, y: -280}],
88+
curviness: 1.5,
89+
autoRotate: true
90+
}
91+
}, 1.0);
92+
```
93+
94+
The MotionPathPlugin CDN script is added automatically.
95+
</Step>
96+
<Step title="Disable to restore straight motion">
97+
Toggle Arc Motion OFF to restore the original `x` and `y` properties as flat tween values.
98+
</Step>
99+
</Steps>
100+
101+
<Note>
102+
Arc Motion works for flat `.to()` tweens with x/y properties. It synthesizes waypoints from `{x: 0, y: 0}` (start) to `{x: targetX, y: targetY}` (end). For more complex paths with intermediate waypoints, edit the `motionPath.path` array directly in the Code tab.
103+
</Note>
104+
105+
## Gesture Recording
106+
107+
Record motion by physically dragging an element in the preview while the timeline plays. The pointer path is simplified and converted into GSAP keyframes automatically.
108+
109+
<Steps>
110+
<Step title="Select an element">
111+
Click the element you want to animate in the preview.
112+
</Step>
113+
<Step title="Click Record or press R">
114+
In the Animation section of the Design Panel, click **Record gesture (R)** or press the R key. The timeline starts playing.
115+
</Step>
116+
<Step title="Drag the element">
117+
Move the element in the preview by dragging it. Your pointer motion is sampled at ~60fps. A trail overlay shows the path you're drawing.
118+
</Step>
119+
<Step title="Stop recording">
120+
Press R again or wait for the timeline to reach the end. Recording stops, the motion is simplified (reducing ~180 raw samples to 5–15 clean keyframes), and the keyframes are written to the GSAP script immediately.
121+
</Step>
122+
<Step title="Review or undo">
123+
The timeline seeks back to the recording start so you can scrub through the result. If you don't like it, press **Cmd+Z** to undo and try again.
124+
</Step>
125+
</Steps>
126+
127+
## Clipboard Context
128+
129+
The **clipboard icon** next to the element name in the Design Panel copies structured element context to your clipboard:
130+
131+
```
132+
Element: Title (#title)
133+
File: index.html:15
134+
Position: x=100, y=40
135+
Size: 264×43
136+
Tag: <div>
137+
Animation: from() 0.5s at 0s, ease: power2.out
138+
Properties: x: -40, opacity: 0
139+
```
140+
141+
Paste this into any AI agent prompt to give it spatial context about the element — its position, size, animation, and source location.

‎packages/core/src/runtime/init.ts‎

Lines changed: 68 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import { createThreeAdapter } from "./adapters/three";
99
import { createTypegpuAdapter } from "./adapters/typegpu";
1010
import { patchVideoTextureCompat } from "./adapters/video-texture-compat";
1111
import { createWaapiAdapter } from "./adapters/waapi";
12-
import { readElementPlaybackRate, refreshRuntimeMediaCache, syncRuntimeMedia } from "./media";
12+
import { refreshRuntimeMediaCache, syncRuntimeMedia } from "./media";
1313
import { probeAndCacheElementVolume, type VolumeKeyframe } from "./mediaVolumeEnvelope.js";
1414
import { createPickerModule } from "./picker";
1515
import { createRuntimePlayer } from "./player";
@@ -954,33 +954,13 @@ export function initSandboxRuntimeModular(): void {
954954
state.capturedTimeline.totalTime(seekTime, false);
955955
}
956956

957-
// Strip stale CSS offset artifacts from GSAP-targeted elements.
958-
// These leak into the HTML when the CSS offset path fires for a
959-
// GSAP-animated element (stale cache race). On reload, both the
960-
// offset and GSAP transform stack, doubling the visual position.
961-
const staleEls = document.querySelectorAll("[data-hf-studio-path-offset]");
962-
if (staleEls.length > 0 && state.capturedTimeline.getChildren) {
963-
const tweenTargets = new Set<Element>();
964-
try {
965-
for (const child of state.capturedTimeline.getChildren(true)) {
966-
if (typeof child.targets === "function") {
967-
for (const t of child.targets()) tweenTargets.add(t);
968-
}
969-
}
970-
} catch {
971-
/* timeline access guard */
972-
}
973-
for (const el of staleEls) {
974-
if (!tweenTargets.has(el)) continue;
975-
const htmlEl = el as HTMLElement;
976-
htmlEl.removeAttribute("data-hf-studio-path-offset");
977-
htmlEl.removeAttribute("data-hf-studio-original-translate");
978-
htmlEl.removeAttribute("data-hf-studio-original-inline-translate");
979-
htmlEl.style.removeProperty("--hf-studio-offset-x");
980-
htmlEl.style.removeProperty("--hf-studio-offset-y");
981-
htmlEl.style.removeProperty("translate");
982-
}
983-
}
957+
// GSAP bakes the CSS `translate` into style.transform on seek.
958+
// The Studio seek wrapper (installStudioManualEditSeekReapply) calls
959+
// reapplyPositionEditsAfterSeek to un-bake it. Call the apply hook
960+
// directly here as well, since the wrapper may not be installed yet
961+
// during initial rebind (timing race on first load / soft reload).
962+
const applyFn = (window as Record<string, unknown>).__hfStudioManualEditsApply;
963+
if (typeof applyFn === "function") applyFn();
984964
}
985965
if (resolution.diagnostics) {
986966
postRuntimeMessage({
@@ -1000,6 +980,51 @@ export function initSandboxRuntimeModular(): void {
1000980
mediaDurationFloorSeconds: resolution.mediaDurationFloorSeconds ?? null,
1001981
},
1002982
});
983+
// Stamp data-start / data-duration on GSAP-targeted elements that lack
984+
// them so the Studio timeline can discover individual animated elements.
985+
{
986+
const rootComp = resolveRootCompositionElement();
987+
const rootDuration = boundDuration > 0 ? boundDuration : 0;
988+
const dur = String(rootDuration > 0 ? rootDuration : 1);
989+
const seen = new Set<Element>();
990+
991+
// Stamp GSAP-targeted elements
992+
if (state.capturedTimeline.getChildren) {
993+
try {
994+
for (const child of state.capturedTimeline.getChildren(true)) {
995+
if (typeof child.targets !== "function") continue;
996+
for (const target of child.targets()) {
997+
if (!(target instanceof HTMLElement)) continue;
998+
if (target === rootComp) continue;
999+
if (target.hasAttribute("data-start")) continue;
1000+
if (seen.has(target)) continue;
1001+
seen.add(target);
1002+
target.setAttribute("data-start", "0");
1003+
target.setAttribute("data-duration", dur);
1004+
}
1005+
}
1006+
} catch {
1007+
/* timeline access guard */
1008+
}
1009+
}
1010+
1011+
// Stamp all ID'd children of the composition root so they appear
1012+
// in the timeline even without animations. Enables selecting and
1013+
// adding animations from the design panel on a blank canvas.
1014+
if (rootComp instanceof HTMLElement) {
1015+
for (const el of rootComp.querySelectorAll("[id]")) {
1016+
if (!(el instanceof HTMLElement)) continue;
1017+
if (el === rootComp) continue;
1018+
if (el.hasAttribute("data-start")) continue;
1019+
if (seen.has(el)) continue;
1020+
if (el.tagName === "SCRIPT" || el.tagName === "STYLE" || el.tagName === "LINK") continue;
1021+
seen.add(el);
1022+
el.setAttribute("data-start", "0");
1023+
el.setAttribute("data-duration", dur);
1024+
}
1025+
}
1026+
}
1027+
10031028
// (Re-)probe all already-bound media elements against the new timeline.
10041029
// Clear the cache first so elements probed against a prior timeline get fresh keyframes.
10051030
for (const el of metadataBoundMedia) {
@@ -1356,7 +1381,6 @@ export function initSandboxRuntimeModular(): void {
13561381
const mediaStart =
13571382
Number.parseFloat(element.dataset.playbackStart ?? element.dataset.mediaStart ?? "0") ||
13581383
0;
1359-
const playbackRate = readElementPlaybackRate(element);
13601384
const hostRemaining =
13611385
context.inheritedStart != null &&
13621386
context.inheritedDuration != null &&
@@ -1365,7 +1389,7 @@ export function initSandboxRuntimeModular(): void {
13651389
: null;
13661390
const sourceDuration =
13671391
Number.isFinite(element.duration) && element.duration > mediaStart
1368-
? Math.max(0, (element.duration - mediaStart) / playbackRate)
1392+
? Math.max(0, element.duration - mediaStart)
13691393
: null;
13701394
if (sourceDuration != null && hostRemaining != null) {
13711395
return Math.min(sourceDuration, hostRemaining);
@@ -1758,28 +1782,27 @@ export function initSandboxRuntimeModular(): void {
17581782
postState(true);
17591783
};
17601784

1761-
let buildListenerPending = false;
1762-
17631785
maybePublishRenderReady = () => {
1764-
if (!externalCompositionsReady) {
1765-
window.__renderReady = false;
1766-
return;
1767-
}
1768-
if (window.__hfTimelinesBuilding) {
1786+
if (!externalCompositionsReady || window.__hfTimelinesBuilding) {
17691787
window.__renderReady = false;
1770-
if (!buildListenerPending) {
1771-
buildListenerPending = true;
1772-
const onBuilt = () => {
1773-
buildListenerPending = false;
1774-
maybePublishRenderReady();
1775-
};
1776-
window.addEventListener("hf-timelines-built", onBuilt, { once: true });
1777-
}
17781788
return;
17791789
}
17801790
publishRenderReadyAfterTimelineBinding();
17811791
};
17821792

1793+
// When the GSAP tween-batching interceptor (HF_EARLY_STUB, fileServer.ts) is
1794+
// active, composition scripts queue tl.to() calls instead of executing them
1795+
// synchronously. Wait for the "hf-timelines-built" event before the first
1796+
// binding attempt so the transport clock receives the finished timeline
1797+
// duration instead of permanently publishing duration=0.
1798+
if (window.__hfTimelinesBuilding) {
1799+
window.__renderReady = false;
1800+
const onTimelinesBuilt = () => {
1801+
window.removeEventListener("hf-timelines-built", onTimelinesBuilt);
1802+
maybePublishRenderReady();
1803+
};
1804+
window.addEventListener("hf-timelines-built", onTimelinesBuilt);
1805+
}
17831806
maybePublishRenderReady();
17841807

17851808
// When the bundler inlines compositions, data-composition-src is removed so

0 commit comments

Comments
 (0)