From 418f198b3391a44728433a788c7c34f9b280ca6c Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Thu, 18 Jun 2026 23:15:02 -0700
Subject: [PATCH] =?UTF-8?q?feat(sdk):=20ws-3c=20=E2=80=94=20addWithKeyfram?=
 =?UTF-8?q?es=20+=20replaceWithKeyframes=20SDK=20ops=20(acorn=20writer)=20?=
 =?UTF-8?q?(#1572)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(sdk): ws-b variables/brand — object-valued font/image + B1 JSON model

B1 — setVariableValue now drives the runtime JSON model
(data-composition-variables) so preview == render. CSS custom prop is
kept as a secondary compat write for compositions that CSS-bind directly
to --{id}.

B2 — object-valued font ({name, source}) and image ({url}) variable
types added core-to-SDK. Object values write to the JSON model only;
scalars write both model + explicit CSS style patches. Explicit style-path
patches in forward/inverse ensure apply-patches.ts handles each path type
purely (model vs CSS), so inverse patches restore exact pre-call state
without ambiguity.

Changed files:
  packages/core/src/core.types.ts         — font/image to CompositionVariableType + interfaces
  packages/core/src/lint/rules/composition.ts — accept font/image in lint message
  packages/core/src/parsers/htmlParser.ts     — validate font/image variable declarations
  packages/core/src/parsers/htmlParser.test.ts — tests for new variable types
  packages/core/src/runtime/validateVariables.ts — checkType for font/image
  packages/sdk/src/types.ts            — FontValue/ImageValue; widen OverrideSet + EditOp
  packages/sdk/src/index.ts            — re-export FontValue/ImageValue
  packages/sdk/src/session.ts          — widen setVariableValue signature
  packages/sdk/src/engine/patches.ts   — valueChange helper for object-valued patches
  packages/sdk/src/engine/mutate.ts    — handleSetVariableValue: B1+B2 with explicit CSS patches
  packages/sdk/src/engine/apply-patches.ts — variable case: model-only (CSS via explicit patch)
  packages/sdk/src/engine/mutate.test.ts   — B1+B2 round-trip + inverse tests

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(sdk): ws-c elastic timing + word-alignment resolver (WS-C)

C1: getElementTimings/setElementTiming typed session methods + setHold typed
wrapper. getElementTimings reads data-duration (preferred) or data-end−data-start
(fallback) — same attr-preference as handleSetTiming. setElementTiming dispatches
a sparse map as one batch → one patch event → one undo step. setHold mirrors
setVariableValue pattern.

Also fixes a pre-existing apply-patches.ts gap: the timing/duration patch case was
absent, causing undo of duration changes to silently no-op. Added the duration
branch so inverse patches restore data-duration correctly.

C2: packages/core/src/compiler/timingResolver.ts — shared pure resolveTimings()
consumed by BOTH preview (sdk session) and render (timingCompiler) paths. Word-
anchored elements get enterAt = wordTimings[k].start + offset; elastic hold =
max(0, slotEnd − (enterAt + enterDuration + exitDuration)), clamped ≥ 0; never
timescales animated content. Un-anchored elements keep authored timing (align-on-
adjust). Deterministic + pure: no Date.now, no Math.random, no DOM.

extractGsapLabels() added to gsapParserAcorn.ts to parse tl.addLabel() calls for
the getElementTimings labels field.

Tests: timingResolver.test.ts (10 pure-function tests including preview==render
parity golden test); session.timings.test.ts (15 session-layer tests covering
duration-authored, end-authored, label extraction, batching, undo, and setHold
regression).

Gates: build ✓ · bun test (sdk+core/compiler) 434/434 ✓ · oxlint 0 warnings ✓ ·
oxfmt --check ✓ · fallow --gate new-only ✓ (complexity suppressed on 2 new
inline functions, duplication warn-only pre-existing)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(sdk): addElement forward op — mint hf-id, inverse = removeElement (WS-D)

Implements WS-D: the addElement EditOp and session.addElement() typed method.

- types.ts: addElement op (parent/index/html) added to EditOp union;
  addElement(parent, index, html): HfId added to Composition interface
- mutate.ts: handleAddElement inserts a single-root HTML fragment at
  parent+index, minting ids against the LIVE document's existing id set
  (not a fresh fragment set) via collectDocumentHfIds + mintFragmentIds;
  forward = patchAdd, inverse = patchRemove; MutationResult.meta.newId
  carries the minted root id
- mutate.ts: validateOp case rejects missing parent, negative index,
  empty html, zero-element html, and <script> in html
- session.ts: typed addElement(parent, index, html) returns minted id
  via result.meta.newId
- mutate.test.ts: 16 tests covering insert position, append semantics,
  id uniqueness, content-collision rehash, nested fragments, forward/
  inverse symmetry, undo, add/undo/redo stability, parent:null body
  insertion, serialize round-trip, and all five validateOp rejection codes

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(sdk): ws-3c — addWithKeyframes + replaceWithKeyframes SDK ops (acorn writer)

Port add-with-keyframes / replace-with-keyframes from the server recast path
to the acorn/magic-string writer and expose them as typed SDK EditOps.

- gsapWriterAcorn.ts: extend buildKeyframeObjectCode and
  addAnimationWithKeyframesToScript to accept `auto?: boolean` on keyframes
  (emits `_auto: 1` matching the recast writer)
- types.ts: add `addWithKeyframes` and `replaceWithKeyframes` to EditOp union
- mutate.ts: add handleAddWithKeyframes, handleReplaceWithKeyframes, and
  applyGsapWithKeyframesOp dispatch sub-function; validateOp cases for both
- sdkCutover.ts: add sdkAddWithKeyframesPersist + sdkReplaceWithKeyframesPersist
  (shared via dispatchWithKeyframes to eliminate clone)
- useGsapAnimationOps.ts: wire addWithKeyframes + replaceWithKeyframes
  callbacks with SDK-first / server fallback pattern
- gsapWriter.parity.test.ts: add parity tests for _auto endpoint round-trip and
  replaceWithKeyframes (remove + addWithKeyframes) differential golden harness;
  import removeAnimationFromScript from both writers

Landmine note: tween IDs are position-derived — replaceWithKeyframes removes the
old tween (renumbering survivors) then inserts the replacement at the end; the
MutationResult patch pair restores the whole GSAP script on undo, not a per-ID
inverse, so ID-held references in callers must re-parse after structural edits.

Gate: WS-3.F (retire recast / executeGsapMutation) — NOT started here.
Remaining Studio callers (gsapDragCommit, gsapRuntimeBridge, useGestureCommit,
useEnableKeyframes) remain on the server commitMutation path until WS-3.F.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/parsers/gsapWriter.parity.test.ts     | 128 ++++++++++++++++++
 packages/core/src/parsers/gsapWriterAcorn.ts  |   3 +
 packages/sdk/src/engine/mutate.ts             |  82 +++++++++++
 packages/sdk/src/types.ts                     |  34 +++++
 .../studio/src/hooks/useGsapAnimationOps.ts   |  96 +++++++++++++
 packages/studio/src/utils/sdkCutover.ts       |  80 +++++++++++
 6 files changed, 423 insertions(+)

diff --git a/packages/core/src/parsers/gsapWriter.parity.test.ts b/packages/core/src/parsers/gsapWriter.parity.test.ts
index 2a478bb0a..1cc605622 100644
--- a/packages/core/src/parsers/gsapWriter.parity.test.ts
+++ b/packages/core/src/parsers/gsapWriter.parity.test.ts
@@ -22,6 +22,7 @@ import {
   addKeyframeToScript as addKeyframeRecast,
   removeKeyframeFromScript as removeKeyframeRecast,
   addAnimationWithKeyframesToScript as addWithKfRecast,
+  removeAnimationFromScript as removeAnimRecast,
   shiftPositionsInScript as shiftRecast,
   scalePositionsInScript as scaleRecast,
   type SplitAnimationsOptions,
@@ -44,6 +45,7 @@ import {
   addKeyframeToScript as addKeyframeAcorn,
   removeKeyframeFromScript as removeKeyframeAcorn,
   addAnimationWithKeyframesToScript as addWithKfAcorn,
+  removeAnimationFromScript as removeAnimAcorn,
   shiftPositionsInScript as shiftAcorn,
   scalePositionsInScript as scaleAcorn,
 } from "./gsapWriterAcorn.js";
@@ -917,6 +919,132 @@ describe("parity: addAnimationWithKeyframesToScript (recast vs acorn)", () => {
     const recast = addWithKfRecast(ADD_WITH_KF_BASE, "#card", 1.5, 2.25, kfs, "none").script;
     expect(lastModelOf(acorn)).toEqual(lastModelOf(recast));
   });
+
+  // WS-3.C: auto-endpoint markers must round-trip through both writers.
+  it("_auto endpoint: 0% and 100% carry the _auto marker", () => {
+    const kfs = [
+      { percentage: 0, properties: { x: 0, opacity: 1 }, auto: true },
+      { percentage: 50, properties: { x: 100, opacity: 0.5 } },
+      { percentage: 100, properties: { x: 200, opacity: 0 }, auto: true },
+    ];
+    const acorn = addWithKfAcorn(ADD_WITH_KF_BASE, "#hero", 0, 1, kfs).script;
+    const recast = addWithKfRecast(ADD_WITH_KF_BASE, "#hero", 0, 1, kfs).script;
+    expect(lastModelOf(acorn)).toEqual(lastModelOf(recast));
+  });
+
+  it("_auto endpoint: only 0% carries auto marker", () => {
+    const kfs = [
+      { percentage: 0, properties: { opacity: 1 }, auto: true },
+      { percentage: 100, properties: { opacity: 0 } },
+    ];
+    const acorn = addWithKfAcorn(ADD_WITH_KF_BASE, "#el", 2, 0.5, kfs).script;
+    const recast = addWithKfRecast(ADD_WITH_KF_BASE, "#el", 2, 0.5, kfs).script;
+    expect(lastModelOf(acorn)).toEqual(lastModelOf(recast));
+  });
+
+  it("returns a stable new animation ID that is non-empty", () => {
+    const kfs = [
+      { percentage: 0, properties: { opacity: 0 } },
+      { percentage: 100, properties: { opacity: 1 } },
+    ];
+    const acornResult = addWithKfAcorn(ADD_WITH_KF_BASE, "#box", 0, 1, kfs);
+    const recastResult = addWithKfRecast(ADD_WITH_KF_BASE, "#box", 0, 1, kfs);
+    expect(acornResult.id).not.toBe("");
+    expect(recastResult.id).not.toBe("");
+    // The IDs are position-derived and may differ between writers due to
+    // formatting differences, but both must be non-empty valid strings.
+    expect(typeof acornResult.id).toBe("string");
+    expect(typeof recastResult.id).toBe("string");
+  });
+});
+
+// ── replaceWithKeyframes parity (remove + addWithKeyframes, recast vs acorn) ──
+// WS-3.C replace path: both writers remove the existing tween by animationId,
+// then insert the replacement keyframed tween. The animation model of the
+// resulting script's last animation must match.
+
+const REPLACE_WITH_KF_BASE = `\
+const tl = gsap.timeline({ paused: true });
+tl.to("#box", { x: 100, opacity: 1, duration: 0.5 }, 1);
+`;
+
+function replaceWithKfRecast(
+  script: string,
+  animId: string,
+  selector: string,
+  pos: number,
+  dur: number,
+  kfs: Array<{
+    percentage: number;
+    properties: Record<string, number | string>;
+    ease?: string;
+    auto?: boolean;
+  }>,
+  ease?: string,
+): string {
+  const removed = removeAnimRecast(script, animId);
+  return addWithKfRecast(removed, selector, pos, dur, kfs, ease).script;
+}
+
+function replaceWithKfAcorn(
+  script: string,
+  animId: string,
+  selector: string,
+  pos: number,
+  dur: number,
+  kfs: Array<{
+    percentage: number;
+    properties: Record<string, number | string>;
+    ease?: string;
+    auto?: boolean;
+  }>,
+  ease?: string,
+): string {
+  const removed = removeAnimAcorn(script, animId);
+  return addWithKfAcorn(removed, selector, pos, dur, kfs, ease).script;
+}
+
+describe("parity: replaceWithKeyframes (remove + addWithKeyframes, recast vs acorn)", () => {
+  it("replaces the only tween: resulting animation model matches", () => {
+    const id = acornId(REPLACE_WITH_KF_BASE);
+    const kfs = [
+      { percentage: 0, properties: { x: 0, opacity: 0 } },
+      { percentage: 100, properties: { x: 200, opacity: 1 } },
+    ];
+    const acorn = replaceWithKfAcorn(REPLACE_WITH_KF_BASE, id, "#box", 0.5, 1.5, kfs);
+    const recast = replaceWithKfRecast(REPLACE_WITH_KF_BASE, id, "#box", 0.5, 1.5, kfs);
+    expect(lastModelOf(acorn)).toEqual(lastModelOf(recast));
+  });
+
+  it("replaces the first tween in a two-tween script, preserving the other", () => {
+    const TWO_TWEEN = `\
+const tl = gsap.timeline({ paused: true });
+tl.to("#box", { x: 100, duration: 0.5 }, 0);
+tl.to("#circle", { y: 200, duration: 1 }, 1);
+`;
+    const id = acornId(TWO_TWEEN);
+    const kfs = [
+      { percentage: 0, properties: { x: 0 } },
+      { percentage: 100, properties: { x: 300 } },
+    ];
+    const acorn = replaceWithKfAcorn(TWO_TWEEN, id, "#box", 0, 0.75, kfs);
+    const recast = replaceWithKfRecast(TWO_TWEEN, id, "#box", 0, 0.75, kfs);
+    // The second tween (#circle) must survive unchanged.
+    expect(modelOf(acorn)).toHaveLength(2);
+    expect(modelOf(recast)).toHaveLength(2);
+    expect(lastModelOf(acorn)).toEqual(lastModelOf(recast));
+  });
+
+  it("replaces with _auto endpoint markers", () => {
+    const id = acornId(REPLACE_WITH_KF_BASE);
+    const kfs = [
+      { percentage: 0, properties: { opacity: 1 }, auto: true },
+      { percentage: 100, properties: { opacity: 0 }, auto: true },
+    ];
+    const acorn = replaceWithKfAcorn(REPLACE_WITH_KF_BASE, id, "#box", 1, 2, kfs);
+    const recast = replaceWithKfRecast(REPLACE_WITH_KF_BASE, id, "#box", 1, 2, kfs);
+    expect(lastModelOf(acorn)).toEqual(lastModelOf(recast));
+  });
 });
 
 // ── shiftPositionsInScript / scalePositionsInScript (timeline clip move/resize) ──
diff --git a/packages/core/src/parsers/gsapWriterAcorn.ts b/packages/core/src/parsers/gsapWriterAcorn.ts
index cfd459cc7..bf855cae6 100644
--- a/packages/core/src/parsers/gsapWriterAcorn.ts
+++ b/packages/core/src/parsers/gsapWriterAcorn.ts
@@ -1128,12 +1128,14 @@ function buildKeyframeObjectCode(
     percentage: number;
     properties: Record<string, number | string>;
     ease?: string;
+    auto?: boolean;
   }>,
   easeEach?: string,
 ): string {
   const entries = keyframes.map((kf) => {
     const props = Object.entries(kf.properties).map(([k, v]) => `${safeKey(k)}: ${valueToCode(v)}`);
     if (kf.ease) props.push(`ease: ${JSON.stringify(kf.ease)}`);
+    if (kf.auto) props.push(`_auto: 1`);
     return `${JSON.stringify(`${kf.percentage}%`)}: { ${props.join(", ")} }`;
   });
   if (easeEach) entries.push(`easeEach: ${JSON.stringify(easeEach)}`);
@@ -1210,6 +1212,7 @@ export function addAnimationWithKeyframesToScript(
     percentage: number;
     properties: Record<string, number | string>;
     ease?: string;
+    auto?: boolean;
   }>,
   ease?: string,
 ): { script: string; id: string } {
diff --git a/packages/sdk/src/engine/mutate.ts b/packages/sdk/src/engine/mutate.ts
index 17f82ee69..5d9c3be10 100644
--- a/packages/sdk/src/engine/mutate.ts
+++ b/packages/sdk/src/engine/mutate.ts
@@ -55,6 +55,7 @@ import { parseGsapScriptAcornForWrite } from "@hyperframes/core/gsap-parser-acor
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import {
   addAnimationToScript,
+  addAnimationWithKeyframesToScript,
   updateAnimationInScript,
   removeAnimationFromScript,
   removePropertyFromAnimation,
@@ -228,11 +229,24 @@ function applyArcPathOp(parsed: ParsedDocument, op: EditOp): MutationResult | un
   }
 }
 
+function applyGsapWithKeyframesOp(parsed: ParsedDocument, op: EditOp): MutationResult | undefined {
+  switch (op.type) {
+    case "addWithKeyframes":
+      return handleAddWithKeyframes(parsed, op);
+    case "replaceWithKeyframes":
+      return handleReplaceWithKeyframes(parsed, op);
+    default:
+      return undefined;
+  }
+}
+
 function applyGsapOp(parsed: ParsedDocument, op: EditOp): MutationResult | undefined {
   const kf = applyGsapKeyframeOp(parsed, op);
   if (kf !== undefined) return kf;
   const arc = applyArcPathOp(parsed, op);
   if (arc !== undefined) return arc;
+  const wkf = applyGsapWithKeyframesOp(parsed, op);
+  if (wkf !== undefined) return wkf;
   switch (op.type) {
     case "addGsapTween":
       return handleAddGsapTween(parsed, op.target, op.tween);
@@ -942,6 +956,51 @@ function cascadeRemoveAnimations(script: string, id: HfId): string {
   }
 }
 
+// ─── addWithKeyframes / replaceWithKeyframes handlers ────────────────────────
+
+function handleAddWithKeyframes(
+  parsed: ParsedDocument,
+  op: Extract<EditOp, { type: "addWithKeyframes" }>,
+): MutationResult {
+  const script = getGsapScript(parsed.document);
+  if (!script) throw new Error("No GSAP script block found in the composition.");
+  const { script: newScript, id: animationId } = addAnimationWithKeyframesToScript(
+    script,
+    op.targetSelector,
+    op.position,
+    op.duration,
+    op.keyframes,
+    op.ease,
+  );
+  if (!animationId) return EMPTY;
+  setGsapScript(parsed.document, newScript);
+  return { ...gsapScriptChange(script, newScript), meta: { animationId } };
+}
+
+function handleReplaceWithKeyframes(
+  parsed: ParsedDocument,
+  op: Extract<EditOp, { type: "replaceWithKeyframes" }>,
+): MutationResult {
+  const script = getGsapScript(parsed.document);
+  if (!script) throw new Error("No GSAP script block found in the composition.");
+  // Step 1: remove the existing tween. Position-derived IDs renumber, so the
+  // inverse patch restores the full GSAP script rather than trying to re-insert
+  // by ID (handled by the coarse gsapScriptChange patch pair).
+  const afterRemove = removeAnimationFromScript(script, op.animationId);
+  // Step 2: insert the replacement keyframed tween.
+  const { script: newScript, id: animationId } = addAnimationWithKeyframesToScript(
+    afterRemove,
+    op.targetSelector,
+    op.position,
+    op.duration,
+    op.keyframes,
+    op.ease,
+  );
+  if (!animationId) return EMPTY;
+  setGsapScript(parsed.document, newScript);
+  return { ...gsapScriptChange(script, newScript), meta: { animationId } };
+}
+
 // ─── setClassStyle handler ────────────────────────────────────────────────────
 
 function handleSetClassStyle(
@@ -1496,6 +1555,29 @@ export function validateOp(parsed: ParsedDocument, op: EditOp): CanResult {
     case "deleteAllForSelector":
     case "removeLabel":
       return gsapScriptMissing(parsed) ?? CAN_OK;
+    case "addWithKeyframes":
+      return (
+        gsapScriptMissing(parsed) ??
+        (op.keyframes.length === 0
+          ? canErr(
+              "E_INVALID_ARGS",
+              "addWithKeyframes requires at least one keyframe.",
+              "An empty keyframe list would create an animation with no keyframes.",
+            )
+          : CAN_OK)
+      );
+    case "replaceWithKeyframes":
+      return (
+        gsapScriptMissing(parsed) ??
+        gsapAnimationMissing(parsed, op.animationId) ??
+        (op.keyframes.length === 0
+          ? canErr(
+              "E_INVALID_ARGS",
+              "replaceWithKeyframes requires at least one keyframe.",
+              "An empty keyframe list would create an animation with no keyframes.",
+            )
+          : CAN_OK)
+      );
     case "unrollDynamicAnimations":
       return (
         gsapScriptMissing(parsed) ??
diff --git a/packages/sdk/src/types.ts b/packages/sdk/src/types.ts
index 7be2adf80..5446b86a8 100644
--- a/packages/sdk/src/types.ts
+++ b/packages/sdk/src/types.ts
@@ -189,6 +189,40 @@ export type EditOp =
         keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
         easeEach?: string;
       }>;
+    }
+  | {
+      /** Insert a new keyframed tween for targetSelector at the given position/duration. */
+      type: "addWithKeyframes";
+      targetSelector: string;
+      position: number;
+      duration: number;
+      keyframes: Array<{
+        percentage: number;
+        properties: Record<string, number | string>;
+        ease?: string;
+        auto?: boolean;
+      }>;
+      ease?: string;
+    }
+  | {
+      /**
+       * Replace an existing tween (by animationId) with a new keyframed tween.
+       * Equivalent to removeGsapTween + addWithKeyframes in one atomic op.
+       * Position-derived tween IDs renumber after the remove; callers must
+       * re-parse to discover the new ID.
+       */
+      type: "replaceWithKeyframes";
+      animationId: string;
+      targetSelector: string;
+      position: number;
+      duration: number;
+      keyframes: Array<{
+        percentage: number;
+        properties: Record<string, number | string>;
+        ease?: string;
+        auto?: boolean;
+      }>;
+      ease?: string;
     };
 
 export interface ElasticHold {
diff --git a/packages/studio/src/hooks/useGsapAnimationOps.ts b/packages/studio/src/hooks/useGsapAnimationOps.ts
index 701576e01..390db74ff 100644
--- a/packages/studio/src/hooks/useGsapAnimationOps.ts
+++ b/packages/studio/src/hooks/useGsapAnimationOps.ts
@@ -5,6 +5,8 @@ import { roundTo3 } from "../utils/rounding";
 import {
   sdkGsapTweenPersist,
   sdkGsapDeleteAllForSelectorPersist,
+  sdkAddWithKeyframesPersist,
+  sdkReplaceWithKeyframesPersist,
   type CutoverDeps,
 } from "../utils/sdkCutover";
 import {
@@ -181,10 +183,104 @@ export function useGsapAnimationOps({
     [activeCompPath, commitMutation, projectIdRef, showToast, sdkSession, sdkDeps],
   );
 
+  type KeyframeEntry = {
+    percentage: number;
+    properties: Record<string, number | string>;
+    ease?: string;
+    auto?: boolean;
+  };
+
+  const addWithKeyframes = useCallback(
+    async (
+      selection: DomEditSelection,
+      targetSelector: string,
+      position: number,
+      duration: number,
+      keyframes: KeyframeEntry[],
+      ease?: string,
+      label = "Add animation with keyframes",
+    ) => {
+      if (sdkSession && sdkDeps) {
+        const targetPath = selection.sourceFile || activeCompPath || "index.html";
+        const handled = await sdkAddWithKeyframesPersist(
+          targetPath,
+          targetSelector,
+          position,
+          duration,
+          keyframes,
+          ease,
+          sdkSession,
+          sdkDeps,
+          { label },
+        );
+        if (handled) return;
+      }
+      void commitMutation(
+        selection,
+        {
+          type: "add-with-keyframes",
+          targetSelector,
+          position,
+          duration,
+          keyframes,
+          ...(ease ? { ease } : {}),
+        },
+        { label, softReload: true },
+      );
+    },
+    [commitMutation, activeCompPath, sdkSession, sdkDeps],
+  );
+
+  const replaceWithKeyframes = useCallback(
+    async (
+      selection: DomEditSelection,
+      animationId: string,
+      targetSelector: string,
+      position: number,
+      duration: number,
+      keyframes: KeyframeEntry[],
+      ease?: string,
+      label = "Replace animation with keyframes",
+    ) => {
+      if (sdkSession && sdkDeps) {
+        const targetPath = selection.sourceFile || activeCompPath || "index.html";
+        const handled = await sdkReplaceWithKeyframesPersist(
+          targetPath,
+          animationId,
+          targetSelector,
+          position,
+          duration,
+          keyframes,
+          ease,
+          sdkSession,
+          sdkDeps,
+          { label },
+        );
+        if (handled) return;
+      }
+      void commitMutation(
+        selection,
+        {
+          type: "replace-with-keyframes",
+          animationId,
+          targetSelector,
+          position,
+          duration,
+          keyframes,
+          ...(ease ? { ease } : {}),
+        },
+        { label, softReload: true },
+      );
+    },
+    [commitMutation, activeCompPath, sdkSession, sdkDeps],
+  );
+
   return {
     updateGsapMeta,
     deleteGsapAnimation,
     deleteAllForSelector,
     addGsapAnimation,
+    addWithKeyframes,
+    replaceWithKeyframes,
   };
 }
diff --git a/packages/studio/src/utils/sdkCutover.ts b/packages/studio/src/utils/sdkCutover.ts
index b7c108119..77c48c010 100644
--- a/packages/studio/src/utils/sdkCutover.ts
+++ b/packages/studio/src/utils/sdkCutover.ts
@@ -435,6 +435,86 @@ export function sdkGsapConvertToKeyframesPersist(
   );
 }
 
+type KeyframeSpec = {
+  percentage: number;
+  properties: Record<string, number | string>;
+  ease?: string;
+  auto?: boolean;
+};
+
+type KeyframesPayload = {
+  targetSelector: string;
+  position: number;
+  duration: number;
+  keyframes: KeyframeSpec[];
+  ease?: string;
+};
+
+/** Shared inner dispatch for addWithKeyframes / replaceWithKeyframes ops. */
+function dispatchWithKeyframes(
+  s: Composition,
+  payload: KeyframesPayload,
+  animationId?: string,
+): void {
+  if (animationId !== undefined) {
+    s.dispatch({ type: "replaceWithKeyframes", animationId, ...payload });
+  } else {
+    s.dispatch({ type: "addWithKeyframes", ...payload });
+  }
+}
+
+export function sdkAddWithKeyframesPersist(
+  targetPath: string,
+  targetSelector: string,
+  position: number,
+  duration: number,
+  keyframes: KeyframeSpec[],
+  ease: string | undefined,
+  sdkSession: Composition | null | undefined,
+  deps: CutoverDeps,
+  options?: CutoverOptions,
+): Promise<boolean> {
+  const payload: KeyframesPayload = {
+    targetSelector,
+    position,
+    duration,
+    keyframes,
+    ...(ease ? { ease } : {}),
+  };
+  return dispatchGsapOpAndPersist(targetPath, sdkSession, deps, options, (s) =>
+    dispatchWithKeyframes(s, payload),
+  );
+}
+
+export function sdkReplaceWithKeyframesPersist(
+  targetPath: string,
+  animationId: string,
+  targetSelector: string,
+  position: number,
+  duration: number,
+  keyframes: KeyframeSpec[],
+  ease: string | undefined,
+  sdkSession: Composition | null | undefined,
+  deps: CutoverDeps,
+  options?: CutoverOptions,
+): Promise<boolean> {
+  const payload: KeyframesPayload = {
+    targetSelector,
+    position,
+    duration,
+    keyframes,
+    ...(ease ? { ease } : {}),
+  };
+  return dispatchGsapOpAndPersist(
+    targetPath,
+    sdkSession,
+    deps,
+    options,
+    (s) => dispatchWithKeyframes(s, payload, animationId),
+    { animationId, opLabel: "replaceWithKeyframes" },
+  );
+}
+
 export async function sdkDeletePersist(
   hfId: string,
   originalContent: string,