@hyperframes/studio 0.6.105 → 0.6.107

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -1,9 +1,15 @@
 /**
  * Read GSAP keyframe data from the live runtime in the preview iframe.
  * Used to discover dynamic keyframes that the AST parser can't resolve
- * (loops, variables, computed selectors).
+ * (data-driven loops, fetched values, computed selectors).
+ *
+ * Keyframe percentages returned here are TWEEN-RELATIVE (0–100 within the
+ * tween), matching the static parser. Callers convert to clip-relative via
+ * `toAbsoluteTime` + the element's clip start/duration. `scanAllRuntimeKeyframes`
+ * does that conversion itself when given a `clipById` map.
  */
-import { parsePercentageKeyframes } from "./gsapShared";
+import { buildArcPath, type ArcPathConfig } from "@hyperframes/core/gsap-parser-acorn";
+import { parsePercentageKeyframes, toAbsoluteTime } from "./gsapShared";
 import { roundTo3 } from "../utils/rounding";
 
 interface RuntimeTween {
@@ -18,155 +24,224 @@ interface RuntimeTimeline {
   duration?: () => number;
 }
 
-export function readRuntimeKeyframes(
-  iframe: HTMLIFrameElement | null,
-  selector: string,
-  compositionId?: string,
-): {
-  keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
+type Pct = { percentage: number; properties: Record<string, number | string> };
+type ReadTween = { keyframes: Pct[]; easeEach?: string; arcPath?: ArcPathConfig };
+
+export interface RuntimeKeyframeEntry {
+  keyframes: Pct[];
   easeEach?: string;
-} | null {
-  if (!iframe?.contentWindow) return null;
+  /** Present when the live tween uses motionPath — drives the Arc Motion panel. */
+  arcPath?: ArcPathConfig;
+  /** Absolute start time of the source tween (seconds). */
+  tweenStart: number;
+  /** Duration of the source tween (seconds). */
+  tweenDuration: number;
+}
 
-  let timelines: Record<string, RuntimeTimeline | undefined> | undefined;
+/** Clip start/duration per element id, to convert tween-relative % to clip-relative. */
+export type ClipDims = Map<string, { start: number; duration: number }>;
+
+const FLAT_SKIP_KEYS = new Set([
+  "ease",
+  "duration",
+  "delay",
+  "stagger",
+  "motionPath",
+  "overwrite",
+  "immediateRender",
+  "onComplete",
+  "onUpdate",
+  "onStart",
+  "keyframes",
+]);
+
+function timelinesOf(iframe: HTMLIFrameElement | null): Record<string, RuntimeTimeline> | null {
+  if (!iframe?.contentWindow) return null;
   try {
-    timelines = (
-      iframe.contentWindow as unknown as { __timelines?: Record<string, RuntimeTimeline> }
-    ).__timelines;
+    return (
+      (iframe.contentWindow as unknown as { __timelines?: Record<string, RuntimeTimeline> })
+        .__timelines ?? null
+    );
   } catch {
     return null;
   }
-  if (!timelines) return null;
+}
+
+function isXY(p: unknown): p is { x: number; y: number } {
+  return !!p && typeof (p as any).x === "number" && typeof (p as any).y === "number";
+}
+
+/** Coordinates + curviness from a live `vars.motionPath` value (object or array form), or null. */
+function coordsFromMotionPath(mp: unknown): {
+  coords: Array<{ x: number; y: number }>;
+  curviness: number;
+  autoRotate: boolean | number;
+  isCubic: boolean;
+} | null {
+  if (!mp || typeof mp !== "object") return null;
+  const obj = mp as Record<string, unknown>;
+  const pathVal = Array.isArray(mp) ? mp : obj.path;
+  if (!Array.isArray(pathVal)) return null;
+  const coords = pathVal.filter(isXY).map((p) => ({ x: p.x, y: p.y }));
+  if (coords.length < 2) return null;
+  const curviness = typeof obj.curviness === "number" ? obj.curviness : 1;
+  const autoRotate = typeof obj.autoRotate === "number" ? obj.autoRotate : obj.autoRotate === true;
+  return { coords, curviness, autoRotate, isCubic: obj.type === "cubic" };
+}
+
+/** Build an arcPath config from a live `vars.motionPath` value. */
+export function arcPathFromMotionPathValue(mp: unknown): ArcPathConfig | undefined {
+  const parsed = coordsFromMotionPath(mp);
+  if (!parsed) return undefined;
+  return buildArcPath(parsed.coords, parsed.curviness, parsed.autoRotate, parsed.isCubic)?.arcPath;
+}
+
+function flatTweenKeyframes(vars: Record<string, unknown>): Pct[] | null {
+  const properties: Record<string, number | string> = {};
+  for (const [k, v] of Object.entries(vars)) {
+    if (FLAT_SKIP_KEYS.has(k)) continue;
+    if (typeof v === "number") properties[k] = roundTo3(v);
+    else if (typeof v === "string") properties[k] = v;
+  }
+  if (Object.keys(properties).length === 0) return null;
+  return [
+    { percentage: 0, properties },
+    { percentage: 100, properties },
+  ];
+}
+
+/** Tween-relative keyframes + optional arcPath for one live tween, or null. */
+function readTween(vars: Record<string, unknown>): ReadTween | null {
+  if (vars.keyframes && typeof vars.keyframes === "object") {
+    const parsed = parsePercentageKeyframes(vars.keyframes as Record<string, unknown>);
+    if (parsed) return parsed;
+  }
+  const mp = coordsFromMotionPath(vars.motionPath);
+  if (mp) {
+    const shape = buildArcPath(mp.coords, mp.curviness, mp.autoRotate, mp.isCubic);
+    if (shape) {
+      const n = shape.waypoints.length;
+      const keyframes = shape.waypoints.map((wp, i) => ({
+        percentage: n > 1 ? Math.round((i / (n - 1)) * 100) : 0,
+        properties: { x: wp.x, y: wp.y },
+      }));
+      return { keyframes, arcPath: shape.arcPath };
+    }
+  }
+  const flat = flatTweenKeyframes(vars);
+  return flat ? { keyframes: flat } : null;
+}
+
+function matchesElement(tween: RuntimeTween, el: Element): boolean {
+  if (!tween.targets) return false;
+  for (const t of tween.targets()) {
+    if (t === el || (el.id && (t as Element).id === el.id)) return true;
+  }
+  return false;
+}
 
+function tweenTiming(tween: RuntimeTween): { start: number; duration: number } {
+  const rawStart = typeof tween.startTime === "function" ? tween.startTime() : 0;
+  const rawDur = typeof tween.duration === "function" ? tween.duration() : 0;
+  return {
+    start: Number.isFinite(rawStart) ? rawStart : 0,
+    duration: Number.isFinite(rawDur) ? rawDur : 0,
+  };
+}
+
+/**
+ * Read keyframes (incl. motionPath arcs) for one selector from the live timeline.
+ * Returns tween-relative percentages; callers convert to clip-relative.
+ */
+export function readRuntimeKeyframes(
+  iframe: HTMLIFrameElement | null,
+  selector: string,
+  compositionId?: string,
+): ReadTween | null {
+  const timelines = timelinesOf(iframe);
+  if (!timelines) return null;
   const tlId = compositionId || Object.keys(timelines)[0];
   if (!tlId) return null;
   const timeline = timelines[tlId];
   if (!timeline?.getChildren) return null;
 
-  let doc: Document | null = null;
+  let targetEl: Element | null = null;
   try {
-    doc = iframe.contentDocument;
+    targetEl = iframe?.contentDocument?.querySelector(selector) ?? null;
   } catch {
     return null;
   }
-  if (!doc) return null;
-
-  const targetEl = doc.querySelector(selector);
   if (!targetEl) return null;
 
   for (const tween of timeline.getChildren(true)) {
-    if (!tween.targets || !tween.vars) continue;
-    let matches = false;
-    for (const t of tween.targets()) {
-      if (t === targetEl || (targetEl.id && t.id === targetEl.id)) {
-        matches = true;
-        break;
-      }
-    }
-    if (!matches) continue;
-
-    const vars = tween.vars;
-    if (!vars.keyframes || typeof vars.keyframes !== "object") continue;
-
-    const parsed = parsePercentageKeyframes(vars.keyframes as Record<string, unknown>);
-    if (parsed) return parsed;
+    if (!tween.vars || !matchesElement(tween, targetEl)) continue;
+    const read = readTween(tween.vars);
+    if (read) return read;
   }
   return null;
 }
 
-// fallow-ignore-next-line complexity
-export function scanAllRuntimeKeyframes(iframe: HTMLIFrameElement | null): Map<
-  string,
-  {
-    keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
-    easeEach?: string;
-  }
-> {
-  const result = new Map<
-    string,
-    {
-      keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
-      easeEach?: string;
-    }
-  >();
-  if (!iframe?.contentWindow) return result;
+/** Convert tween-relative keyframes to clip-relative % using the element's clip dims. */
+function toClipRelative(
+  keyframes: Pct[],
+  tweenStart: number,
+  tweenDuration: number,
+  clip: { start: number; duration: number } | undefined,
+): Pct[] {
+  if (!clip || clip.duration <= 0) return keyframes;
+  return keyframes.map((kf) => {
+    const abs = toAbsoluteTime(tweenStart, tweenDuration, kf.percentage);
+    return { ...kf, percentage: Math.round(((abs - clip.start) / clip.duration) * 100000) / 1000 };
+  });
+}
 
-  let timelines: Record<string, RuntimeTimeline | undefined> | undefined;
-  try {
-    timelines = (
-      iframe.contentWindow as unknown as { __timelines?: Record<string, RuntimeTimeline> }
-    ).__timelines;
-  } catch {
-    return result;
+function buildEntry(
+  read: ReadTween,
+  start: number,
+  duration: number,
+  clip: { start: number; duration: number } | undefined,
+): RuntimeKeyframeEntry {
+  return {
+    keyframes: toClipRelative(read.keyframes, start, duration, clip),
+    tweenStart: start,
+    tweenDuration: duration,
+    ...(read.easeEach ? { easeEach: read.easeEach } : {}),
+    ...(read.arcPath ? { arcPath: read.arcPath } : {}),
+  };
+}
+
+/** Record one tween's keyframes under each target id (first-tween-per-id wins). */
+function addScanEntry(
+  result: Map<string, RuntimeKeyframeEntry>,
+  tween: RuntimeTween,
+  clipById?: ClipDims,
+): void {
+  if (!tween.targets || !tween.vars) return;
+  const read = readTween(tween.vars);
+  if (!read) return;
+  const { start, duration } = tweenTiming(tween);
+  for (const target of tween.targets()) {
+    const id = (target as HTMLElement).id;
+    if (id && !result.has(id)) result.set(id, buildEntry(read, start, duration, clipById?.get(id)));
   }
-  if (!timelines) return result;
+}
 
+/**
+ * Scan every live tween, grouping keyframes by element id. Percentages are
+ * tween-relative unless `clipById` is supplied, in which case each entry's
+ * keyframes are converted to clip-relative. First keyframe-bearing tween per
+ * element wins (the common single-primary-tween case).
+ */
+export function scanAllRuntimeKeyframes(
+  iframe: HTMLIFrameElement | null,
+  clipById?: ClipDims,
+): Map<string, RuntimeKeyframeEntry> {
+  const result = new Map<string, RuntimeKeyframeEntry>();
+  const timelines = timelinesOf(iframe);
+  if (!timelines) return result;
   for (const timeline of Object.values(timelines)) {
     if (!timeline?.getChildren) continue;
-    const tlDuration = typeof timeline.duration === "function" ? timeline.duration() : 0;
-
-    for (const tween of timeline.getChildren(true)) {
-      if (!tween.targets || !tween.vars) continue;
-      const vars = tween.vars;
-
-      if (vars.keyframes && typeof vars.keyframes === "object") {
-        const parsed = parsePercentageKeyframes(vars.keyframes as Record<string, unknown>);
-        if (parsed) {
-          for (const target of tween.targets()) {
-            const id = (target as HTMLElement).id;
-            if (id && !result.has(id)) {
-              result.set(id, parsed);
-            }
-          }
-          continue;
-        }
-      }
-
-      // Flat tweens: synthesize start + end keyframe entries
-      if (!tlDuration || tlDuration <= 0) continue;
-      const tweenStart = typeof tween.startTime === "function" ? tween.startTime() : undefined;
-      if (typeof tweenStart !== "number" || !Number.isFinite(tweenStart)) continue;
-      const tweenDur = typeof tween.duration === "function" ? tween.duration() : 0;
-
-      const startPct = Math.round((tweenStart / tlDuration) * 1000) / 10;
-      const endPct =
-        tweenDur > 0 ? Math.round(((tweenStart + tweenDur) / tlDuration) * 1000) / 10 : startPct;
-      const properties: Record<string, number | string> = {};
-      const skip = new Set([
-        "ease",
-        "duration",
-        "delay",
-        "stagger",
-        "motionPath",
-        "overwrite",
-        "immediateRender",
-        "onComplete",
-        "onUpdate",
-        "onStart",
-      ]);
-      for (const [k, v] of Object.entries(vars)) {
-        if (skip.has(k)) continue;
-        if (typeof v === "number") properties[k] = roundTo3(v);
-        else if (typeof v === "string") properties[k] = v;
-      }
-      if (Object.keys(properties).length === 0) continue;
-
-      for (const target of tween.targets()) {
-        const id = (target as HTMLElement).id;
-        if (!id) continue;
-        const existing = result.get(id);
-        const entries = existing ?? { keyframes: [] };
-        entries.keyframes.push({ percentage: startPct, properties });
-        if (endPct !== startPct) {
-          entries.keyframes.push({ percentage: endPct, properties });
-        }
-        if (!existing) result.set(id, entries);
-      }
-    }
-  }
-
-  for (const entry of result.values()) {
-    entry.keyframes.sort((a, b) => a.percentage - b.percentage);
+    for (const tween of timeline.getChildren(true)) addScanEntry(result, tween, clipById);
   }
   return result;
 }

package/src/hooks/gsapScriptCommitTypes.ts

@@ -3,6 +3,7 @@ import type { Composition } from "@hyperframes/sdk";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import type { EditHistoryKind } from "../utils/editHistory";
 import type { ShadowGsapOp } from "../utils/sdkShadow";
+import type { ShadowKeyframeOp } from "../utils/sdkShadowGsapKeyframe";
 
 export interface MutationResult {
   ok: boolean;
@@ -19,8 +20,18 @@ export interface CommitMutationOptions {
   softReload?: boolean;
   skipReload?: boolean;
   beforeReload?: () => void;
+  /**
+   * Serialize this commit against others sharing the same key. Used to chain
+   * per-animationId GSAP meta updates so overlapping read-modify-write POSTs to
+   * one file can't interleave — which would pair the shadow fidelity diff with a
+   * stale server result and report false ease mismatches. Commits without a key
+   * (and under distinct keys) run concurrently as before.
+   */
+  serializeKey?: string;
   /** Stage 7 Step 3b: typed SDK equivalent of this mutation for value-fidelity shadow. */
   shadowGsapOp?: ShadowGsapOp;
+  /** Typed SDK equivalent of a keyframe mutation for keyframe value-fidelity shadow (gsap_keyframe). */
+  shadowKeyframeOp?: ShadowKeyframeOp;
 }
 
 export type CommitMutation = (

package/src/hooks/serializeByKey.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { createKeyedSerializer } from "./serializeByKey";
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+describe("createKeyedSerializer", () => {
+  it("runs same-key tasks strictly in order (second awaits the first)", async () => {
+    const run = createKeyedSerializer();
+    const order: string[] = [];
+    const first = deferred<void>();
+
+    const p1 = run("k", async () => {
+      order.push("1-start");
+      await first.promise;
+      order.push("1-end");
+    });
+    const p2 = run("k", async () => {
+      order.push("2-start");
+    });
+
+    // Second task must not start until the first finishes.
+    await Promise.resolve();
+    expect(order).toEqual(["1-start"]);
+
+    first.resolve();
+    await Promise.all([p1, p2]);
+    expect(order).toEqual(["1-start", "1-end", "2-start"]);
+  });
+
+  it("does not block tasks under different keys", async () => {
+    const run = createKeyedSerializer();
+    const order: string[] = [];
+    const blockA = deferred<void>();
+
+    const pa = run("a", async () => {
+      order.push("a-start");
+      await blockA.promise;
+      order.push("a-end");
+    });
+    const pb = run("b", async () => {
+      order.push("b-start");
+      order.push("b-end");
+    });
+
+    // Different key runs to completion while "a" is still blocked.
+    await pb;
+    expect(order).toEqual(["a-start", "b-start", "b-end"]);
+
+    blockA.resolve();
+    await pa;
+    expect(order).toEqual(["a-start", "b-start", "b-end", "a-end"]);
+  });
+
+  it("does not wedge a key when a prior task rejects", async () => {
+    const run = createKeyedSerializer();
+    const order: string[] = [];
+
+    const p1 = run("k", async () => {
+      order.push("1");
+      throw new Error("boom");
+    });
+    await expect(p1).rejects.toThrow("boom");
+
+    const p2 = run("k", async () => {
+      order.push("2");
+    });
+    await p2;
+    expect(order).toEqual(["1", "2"]);
+  });
+
+  it("propagates the task's resolved value to its caller", async () => {
+    const run = createKeyedSerializer();
+    await expect(run("k", async () => 42)).resolves.toBe(42);
+  });
+});

package/src/hooks/serializeByKey.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-key task serializer. Tasks sharing a key run strictly in order: a new
+ * task for a key awaits the prior task for that key before starting, so their
+ * effects (e.g. overlapping read-modify-write POSTs to one file) can't
+ * interleave. Tasks under different keys are independent and never block each
+ * other.
+ *
+ * Used to serialize GSAP meta-update commits per animationId so the shadow
+ * fidelity diff always pairs an op with the server result that includes it —
+ * without globally serializing unrelated commits.
+ */
+export function createKeyedSerializer() {
+  const inFlight = new Map<string, Promise<unknown>>();
+
+  return function run<T>(key: string, task: () => Promise<T>): Promise<T> {
+    const prior = inFlight.get(key) ?? Promise.resolve();
+    // Chain onto the prior task regardless of how it settled; a rejected prior
+    // commit must not wedge the key forever.
+    const next = prior.then(task, task);
+    inFlight.set(key, next);
+    // Once this task settles, drop it from the map if nothing newer replaced it,
+    // so completed keys don't leak.
+    void next.then(
+      () => {
+        if (inFlight.get(key) === next) inFlight.delete(key);
+      },
+      () => {
+        if (inFlight.get(key) === next) inFlight.delete(key);
+      },
+    );
+    return next;
+  };
+}

package/src/hooks/useDomEditSession.ts

@@ -334,6 +334,7 @@ export function useDomEditSession({
     commitAnimatedProperty,
     handleSetArcPath,
     handleUpdateArcSegment,
+    handleUnroll,
     commitMutation,
   } = useGsapAwareEditing({
     domEditSelection,
@@ -420,6 +421,7 @@ export function useDomEditSession({
     commitAnimatedProperty,
     handleSetArcPath,
     handleUpdateArcSegment,
+    handleUnroll,
     invalidateGsapCache: bumpGsapCache,
     previewIframeRef,
     commitMutation,

package/src/hooks/useDomGeometryCommits.ts

@@ -42,7 +42,15 @@ export function useDomGeometryCommits({
 }: UseDomGeometryCommitsParams) {
   const handleDomPathOffsetCommit = useCallback(
     (selection: DomEditSelection, next: { x: number; y: number }) => {
-      if (isElementGsapTargeted(previewIframeRef.current, selection.element)) {
+      const gsapBlocked = isElementGsapTargeted(previewIframeRef.current, selection.element);
+      console.log(
+        "[drag:7] handleDomPathOffsetCommit (CSS path)",
+        JSON.stringify({
+          sel: selection.id,
+          gsapBlocked,
+        }),
+      );
+      if (gsapBlocked) {
         const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
         showToast(error.message, "error");
         return Promise.reject(error);

package/src/hooks/useGsapAnimationOps.ts

@@ -40,10 +40,14 @@ export function useGsapAnimationOps({
         animationId,
         properties: { duration: updates.duration, ease: updates.ease, position: updates.position },
       };
+      // coalesceKey groups rapid meta edits into one history entry. Request
+      // serialization is now handled per-file at the commitMutation chokepoint
+      // (useGsapScriptCommits), so no per-op serializeKey is needed here.
+      const metaKey = `gsap:${animationId}:meta`;
       commitMutationSafely(
         selection,
         { type: "update-meta", animationId, updates },
-        { label: "Edit GSAP animation", coalesceKey: `gsap:${animationId}:meta`, shadowGsapOp },
+        { label: "Edit GSAP animation", coalesceKey: metaKey, shadowGsapOp },
       );
       if (sdkSession) runShadowGsapTween(sdkSession, shadowGsapOp);
     },

package/src/hooks/useGsapAwareEditing.ts

@@ -98,6 +98,17 @@ export function useGsapAwareEditing({
   const handleGsapAwarePathOffsetCommit = useCallback(
     async (selection: DomEditSelection, next: { x: number; y: number }) => {
       const hasGsapAnims = selectedGsapAnimations.length > 0;
+      console.log(
+        "[drag:3] handleGsapAwarePathOffsetCommit",
+        JSON.stringify({
+          sel: selection.id,
+          offset: next,
+          hasGsapAnims,
+          interceptEnabled: STUDIO_GSAP_DRAG_INTERCEPT_ENABLED,
+          animCount: selectedGsapAnimations.length,
+          animIds: selectedGsapAnimations.map((a) => a.id).slice(0, 5),
+        }),
+      );
       if (hasGsapAnims && !STUDIO_GSAP_DRAG_INTERCEPT_ENABLED) {
         showToast(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE, "error");
         throw new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
@@ -230,6 +241,15 @@ export function useGsapAwareEditing({
     [domEditSelection, gsapCommitMutation],
   );
 
+  // Unroll all computed (helper/loop) tweens in the active timeline into literal
+  // tweens, so the clicked keyframe becomes directly editable. Visual no-op.
+  const handleUnroll = useCallback(() => {
+    void commitMutation(
+      { type: "unroll-timeline" },
+      { label: "Unroll to literal tweens", softReload: true },
+    );
+  }, [commitMutation]);
+
   return {
     handleGsapAwarePathOffsetCommit,
     handleGsapAwareBoxSizeCommit,
@@ -237,6 +257,7 @@ export function useGsapAwareEditing({
     commitAnimatedProperty,
     handleSetArcPath,
     handleUpdateArcSegment,
+    handleUnroll,
     commitMutation,
   };
 }

package/src/hooks/useGsapKeyframeOps.ts

@@ -1,5 +1,6 @@
 import { useCallback } from "react";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { ShadowKeyframeOp } from "../utils/sdkShadowGsapKeyframe";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { executeOptimistic } from "../utils/optimisticUpdate";
 import type { KeyframeCacheEntry } from "../player/store/playerStore";
@@ -58,6 +59,13 @@ export function useGsapKeyframeOps({
         percentage,
         properties: { [property]: value },
       };
+      // Shadow op (gsap_keyframe): SDK equivalent diffed via the commit chokepoint.
+      const shadowKeyframeOp: ShadowKeyframeOp = {
+        kind: "add",
+        animationId,
+        percentage,
+        properties: { [property]: value },
+      };
       void executeOptimisticKeyframeCacheUpdate({
         sourceFile,
         elementId: selection.id,
@@ -71,6 +79,7 @@ export function useGsapKeyframeOps({
           commitMutation(selection, mutation, {
             label: `Add keyframe at ${percentage}%`,
             softReload: true,
+            shadowKeyframeOp,
           }),
       }).catch((error) => {
         trackGsapSaveFailure(error, selection, mutation, `Add keyframe at ${percentage}%`);
@@ -86,10 +95,16 @@ export function useGsapKeyframeOps({
       percentage: number,
       properties: Record<string, number | string>,
     ) => {
+      const shadowKeyframeOp: ShadowKeyframeOp = {
+        kind: "add",
+        animationId,
+        percentage,
+        properties,
+      };
       return commitMutation(
         selection,
         { type: "add-keyframe", animationId, percentage, properties },
-        { label: `Add keyframe at ${percentage}%`, softReload: true },
+        { label: `Add keyframe at ${percentage}%`, softReload: true, shadowKeyframeOp },
       );
     },
     [commitMutation],
@@ -99,6 +114,10 @@ export function useGsapKeyframeOps({
     (selection: DomEditSelection, animationId: string, percentage: number) => {
       const sourceFile = selection.sourceFile || activeCompPath || "index.html";
       const mutation = { type: "remove-keyframe", animationId, percentage };
+      // Shadow op (gsap_keyframe): SDK has no %-based removeGsapKeyframe on main,
+      // so the runner resolves percentage → keyframeIndex against the pre-op
+      // script and no-ops on ambiguity (duplicate-percentage keyframes).
+      const shadowKeyframeOp: ShadowKeyframeOp = { kind: "remove", animationId, percentage };
       void executeOptimisticKeyframeCacheUpdate({
         sourceFile,
         elementId: selection.id,
@@ -112,6 +131,7 @@ export function useGsapKeyframeOps({
           commitMutation(selection, mutation, {
             label: `Remove keyframe at ${percentage}%`,
             softReload: true,
+            shadowKeyframeOp,
           }),
       }).catch((error) => {
         trackGsapSaveFailure(error, selection, mutation, `Remove keyframe at ${percentage}%`);