feat(studio): smooth gesture recordings + editable easeEach in Animation panel

Two-layer smoothing for recorded gestures:
1. Gaussian-weighted moving average (radius=3) rounds off jittery pointer
   corners after RDP simplification
2. easeEach: power1.inOut on committed keyframes uses bezier interpolation

Animation panel Speed dropdown now correctly reads and writes easeEach for
keyframed tweens. Both the recast and acorn writers handle easeEach in
update-meta mutations.

Author: miguel-heygen

packages/core/src/parsers/gsapParser.ts

@@ -1243,13 +1243,17 @@ function applyEaseUpdate(varsArg: AstNode, ease: string): void {
   }
 }
 
-function applyUpdatesToCall(call: TweenCallInfo, updates: Partial<GsapAnimation>): void {
+function applyUpdatesToCall(
+  call: TweenCallInfo,
+  updates: Partial<GsapAnimation> & { easeEach?: string },
+): void {
   if (updates.properties) reconcileEditableProperties(call.varsArg, updates.properties);
   if (updates.fromProperties && call.method === "fromTo" && call.fromArg) {
     reconcileEditableProperties(call.fromArg, updates.fromProperties);
   }
   if (updates.duration !== undefined) setVarsKey(call.varsArg, "duration", updates.duration);
-  if (updates.ease !== undefined) applyEaseUpdate(call.varsArg, updates.ease);
+  if (updates.easeEach !== undefined) applyEaseUpdate(call.varsArg, updates.easeEach);
+  else if (updates.ease !== undefined) applyEaseUpdate(call.varsArg, updates.ease);
   if (updates.position !== undefined) {
     const posIdx = call.method === "fromTo" ? 3 : 2;
     call.node.arguments[posIdx] = parseExpr(valueToCode(updates.position));
@@ -1308,7 +1312,7 @@ function buildTweenStatementCode(timelineVar: string, anim: Omit<GsapAnimation,
 export function updateAnimationInScript(
   script: string,
   animationId: string,
-  updates: Partial<GsapAnimation>,
+  updates: Partial<GsapAnimation> & { easeEach?: string },
 ): string {
   let parsed: ParsedGsapAst;
   try {
@@ -1437,6 +1441,7 @@ export function addAnimationWithKeyframesToScript(
     auto?: boolean;
   }>,
   ease?: string,
+  easeEach?: string,
 ): { script: string; id: string } {
   let parsed: ParsedGsapAst;
   try {
@@ -1450,7 +1455,7 @@ export function addAnimationWithKeyframesToScript(
   }
 
   const selector = JSON.stringify(targetSelector);
-  const kfCode = buildKeyframeObjectCode(keyframes);
+  const kfCode = buildKeyframeObjectCode(keyframes, easeEach ? { easeEach } : undefined);
   const varEntries = [`keyframes: ${kfCode}`, `duration: ${valueToCode(duration)}`];
   if (ease) varEntries.push(`ease: ${JSON.stringify(ease)}`);
   const posCode = valueToCode(position);

packages/core/src/parsers/gsapWriterAcorn.ts

@@ -299,7 +299,7 @@ function findInsertionPoint(parsed: ParsedGsapAcornForWrite): number | null {
 export function updateAnimationInScript(
   script: string,
   animationId: string,
-  updates: Partial<GsapAnimation>,
+  updates: Partial<GsapAnimation> & { easeEach?: string },
 ): string {
   if (!Object.keys(updates).length) return script;
   const parsed = parseGsapScriptAcornForWrite(script);
@@ -324,13 +324,11 @@ export function updateAnimationInScript(
     if (updates.duration !== undefined) {
       upsertProp(ms, call.varsArg, "duration", updates.duration);
     }
-    if (updates.ease !== undefined) {
-      // For a keyframe tween, easing lives at keyframes.easeEach (per-keyframe),
-      // not a top-level ease. Writing top-level ease would leave the per-keyframe
-      // easing unchanged — the user's edit would silently do nothing.
+    const easeValue = updates.easeEach ?? updates.ease;
+    if (easeValue !== undefined) {
       const kfNode = keyframesObjectNode(call.varsArg);
-      if (kfNode) upsertProp(ms, kfNode, "easeEach", updates.ease);
-      else upsertProp(ms, call.varsArg, "ease", updates.ease);
+      if (kfNode) upsertProp(ms, kfNode, "easeEach", easeValue);
+      else upsertProp(ms, call.varsArg, "ease", easeValue);
     }
     if (updates.extras) {
       for (const [key, value] of Object.entries(updates.extras)) {
@@ -1338,14 +1336,15 @@ export function addAnimationWithKeyframesToScript(
     auto?: boolean;
   }>,
   ease?: string,
+  easeEach?: string,
 ): { script: string; id: string } {
   const parsed = parseGsapScriptAcornForWrite(script);
   if (!parsed) return { script, id: "" };
   const insertionPoint = findInsertionPoint(parsed);
   if (insertionPoint === null) return { script, id: "" };
 
   const sorted = [...keyframes].sort((a, b) => a.percentage - b.percentage);
-  const kfObjCode = buildKeyframeObjectCode(sorted);
+  const kfObjCode = buildKeyframeObjectCode(sorted, easeEach);
   const varParts = [`keyframes: ${kfObjCode}`, `duration: ${valueToCode(duration)}`];
   if (ease) varParts.push(`ease: ${JSON.stringify(ease)}`);
   const stmtCode = `${parsed.timelineVar}.to(${JSON.stringify(targetSelector)}, { ${varParts.join(", ")} }, ${valueToCode(position)});`;

packages/core/src/studio-api/routes/files.ts

@@ -437,7 +437,7 @@ type GsapMutationRequest =
   | {
       type: "update-meta";
       animationId: string;
-      updates: { duration?: number; ease?: string; position?: number };
+      updates: { duration?: number; ease?: string; easeEach?: string; position?: number };
     }
   | {
       type: "add";
@@ -552,6 +552,7 @@ type GsapMutationRequest =
         auto?: boolean;
       }>;
       ease?: string;
+      easeEach?: string;
     }
   | {
       type: "replace-with-keyframes";
@@ -827,6 +828,7 @@ function executeGsapMutationAcorn(
         body.duration,
         body.keyframes,
         body.ease,
+        body.easeEach,
       );
       return result.script;
     }

packages/studio/src/components/editor/AnimationCard.tsx

@@ -330,7 +330,8 @@ export const AnimationCard = memo(function AnimationCard({
   const [copied, setCopied] = useState(false);
 
   const methodLabel = METHOD_LABELS[animation.method] ?? animation.method;
-  const easeName = animation.ease ?? animation.keyframes?.easeEach ?? "none";
+  const easeName =
+    (animation.keyframes ? animation.keyframes.easeEach : undefined) ?? animation.ease ?? "none";
   const easeLabel = easeName.startsWith("custom(")
     ? "Custom curve"
     : (EASE_LABELS[easeName] ?? easeName);
@@ -440,23 +441,25 @@ export const AnimationCard = memo(function AnimationCard({
                   value={easeName.startsWith("custom(") ? "custom" : easeName}
                   options={[...SUPPORTED_EASES, "custom"]}
                   onChange={(next) => {
+                    const easeKey = animation.keyframes ? "easeEach" : "ease";
                     if (next === "custom") {
                       const points = controlPointsForGsapEase(
                         easeName !== "none" ? easeName : "power2.out",
                       );
                       const path = `M0,0 C${points.x1},${points.y1} ${points.x2},${points.y2} 1,1`;
-                      onUpdateMeta(animation.id, { ease: `custom(${path})` });
+                      onUpdateMeta(animation.id, { [easeKey]: `custom(${path})` });
                     } else {
-                      onUpdateMeta(animation.id, { ease: next });
+                      onUpdateMeta(animation.id, { [easeKey]: next });
                     }
                   }}
                 />
                 <EaseCurveSection
                   ease={easeName}
                   duration={animation.duration}
-                  onCustomEaseCommit={(customEase) =>
-                    onUpdateMeta(animation.id, { ease: customEase })
-                  }
+                  onCustomEaseCommit={(customEase) => {
+                    const easeKey = animation.keyframes ? "easeEach" : "ease";
+                    onUpdateMeta(animation.id, { [easeKey]: customEase });
+                  }}
                 />
               </>
             )}

packages/studio/src/hooks/useGestureCommit.ts

@@ -6,6 +6,7 @@ import { useState, useCallback, useRef, useEffect } from "react";
 import { editLog } from "../utils/editDebugLog";
 import { useGestureRecording } from "./useGestureRecording";
 import { simplifyGestureSamples } from "../utils/rdpSimplify";
+import { smoothGestureKeyframes } from "../utils/gestureSmoother";
 import { usePlayerStore } from "../player";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
@@ -150,10 +151,13 @@ export function useGestureCommit({
       }
       if (liveSession.commitMutation) {
         const recStart = recordingStartTimeRef.current;
-        const keyframes = sortedPcts.map((pct) => ({
+        const rawKeyframes = sortedPcts.map((pct) => ({
           percentage: pct,
           properties: simplified.get(pct) as Record<string, number | string>,
         }));
+        // Smooth jittery pointer input — Gaussian-weighted moving average
+        // rounds off sharp corners while preserving overall path shape.
+        const keyframes = smoothGestureKeyframes(rawKeyframes, 3);
         const hasPositionProps = keyframes.some((kf) =>
           Object.keys(kf.properties).some((k) => classifyPropertyGroup(k) === "position"),
         );
@@ -236,6 +240,7 @@ export function useGestureCommit({
                     position: roundTo3(recStart),
                     duration: roundTo3(duration),
                     keyframes: groupKfs,
+                    easeEach: "power1.inOut",
                   },
                   { label: "Gesture recording (new range)", softReload: true },
                 );
@@ -252,6 +257,7 @@ export function useGestureCommit({
                 position: roundTo3(recStart),
                 duration: roundTo3(duration),
                 keyframes: groupKfs,
+                easeEach: "power1.inOut",
               },
               { label: "Gesture recording", softReload: true },
             );

packages/studio/src/utils/gestureSmoother.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { smoothGestureKeyframes } from "./gestureSmoother";
+
+describe("smoothGestureKeyframes", () => {
+  it("returns input unchanged for ≤2 keyframes", () => {
+    const kfs = [
+      { percentage: 0, properties: { x: 0, y: 0 } },
+      { percentage: 100, properties: { x: 100, y: 100 } },
+    ];
+    expect(smoothGestureKeyframes(kfs, 3)).toEqual(kfs);
+  });
+
+  it("pins first and last keyframes", () => {
+    const kfs = [
+      { percentage: 0, properties: { x: 0 } },
+      { percentage: 50, properties: { x: 999 } },
+      { percentage: 100, properties: { x: 200 } },
+    ];
+    const result = smoothGestureKeyframes(kfs, 3);
+    expect(result[0].properties.x).toBe(0);
+    expect(result[result.length - 1].properties.x).toBe(200);
+  });
+
+  it("smooths a zigzag into a gentler curve", () => {
+    const kfs = [
+      { percentage: 0, properties: { x: 0 } },
+      { percentage: 25, properties: { x: 100 } },
+      { percentage: 50, properties: { x: 0 } },
+      { percentage: 75, properties: { x: 100 } },
+      { percentage: 100, properties: { x: 0 } },
+    ];
+    const result = smoothGestureKeyframes(kfs, 2);
+    const mid = result[2].properties.x as number;
+    // The sharp 0→100→0 zigzag should be softened — mid should be
+    // pulled toward the neighbors, not stay at exactly 0.
+    expect(mid).toBeGreaterThan(0);
+    expect(mid).toBeLessThan(100);
+  });
+
+  it("returns input unchanged with radius 0", () => {
+    const kfs = [
+      { percentage: 0, properties: { x: 0 } },
+      { percentage: 50, properties: { x: 999 } },
+      { percentage: 100, properties: { x: 0 } },
+    ];
+    expect(smoothGestureKeyframes(kfs, 0)).toEqual(kfs);
+  });
+});

packages/studio/src/utils/gestureSmoother.ts

@@ -0,0 +1,43 @@
+// ponytail: Gaussian-weighted moving average over gesture keyframes.
+// Rounds off jittery corners from raw pointer input while preserving
+// overall path shape. First/last keyframes are pinned (never moved).
+// Upgrade path: Catmull-Rom spline if users need curve-fitted paths.
+
+interface Keyframe {
+  percentage: number;
+  properties: Record<string, number | string>;
+}
+
+function gaussianWeight(distance: number, sigma: number): number {
+  return Math.exp(-(distance * distance) / (2 * sigma * sigma));
+}
+
+export function smoothGestureKeyframes(keyframes: Keyframe[], radius: number): Keyframe[] {
+  if (keyframes.length <= 2 || radius <= 0) return keyframes;
+  const sigma = radius / 2;
+  const numericKeys = new Set<string>();
+  for (const kf of keyframes) {
+    for (const [k, v] of Object.entries(kf.properties)) {
+      if (typeof v === "number") numericKeys.add(k);
+    }
+  }
+  if (numericKeys.size === 0) return keyframes;
+
+  return keyframes.map((kf, i) => {
+    if (i === 0 || i === keyframes.length - 1) return kf;
+    const smoothed: Record<string, number | string> = { ...kf.properties };
+    for (const key of numericKeys) {
+      let weightSum = 0;
+      let valueSum = 0;
+      for (let j = Math.max(0, i - radius); j <= Math.min(keyframes.length - 1, i + radius); j++) {
+        const v = keyframes[j].properties[key];
+        if (typeof v !== "number") continue;
+        const w = gaussianWeight(j - i, sigma);
+        weightSum += w;
+        valueSum += v * w;
+      }
+      if (weightSum > 0) smoothed[key] = Math.round((valueSum / weightSum) * 1000) / 1000;
+    }
+    return { percentage: kf.percentage, properties: smoothed };
+  });
+}