feat(studio): shadow telemetry for GSAP keyframe ops (gsap_keyframe) (#1509)

vanceingalls · claude · web-flow · commit 4b4a3eb63dbf · 2026-06-16T12:27:48.000-07:00
* fix(studio): suppress shadow-parity false positives in timing + text runShadowTiming: compare start/duration with a relative epsilon (1e-6) instead of exact equality so float-precision drift (3.1 vs 3.0999999999999996, 21.36 vs 21.360000000000014) no longer flags; a real difference (3.1 vs 3.5) still flags. trackIndex stays exact. property:text resolver: trim both sides (snapshot.text is already trimmed) and collapse empty-string vs absent (null) text so trailing-whitespace and empty-vs-null no longer flag. Genuine text differences are unaffected; the per-keystroke length lag is a caller-side debounce concern. Adds tests for both fixes plus regression tests documenting two REAL SDK divergences the shadow correctly surfaces (transform-origin removal no-op; duplicate-bare-id delete resolution) — flagged, not fixed here. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(studio): shadow telemetry for GSAP keyframe ops (gsap_keyframe) Wire the SDK shadow-parity telemetry to cover GSAP keyframe add/remove, the primary unwired cutover signal, plus a defensive unmapped-PatchOperation guard. New packages/studio/src/utils/sdkShadowGsapKeyframe.ts: - ShadowKeyframeOp + keyframeOpToEditOp: maps studio percentage-based keyframe ops to SDK EditOps. add -> addGsapKeyframe{position:percentage}; remove -> removeGsapKeyframe{keyframeIndex}, resolving percentage -> index against the pre-op script with ~0.001 tolerance and a no-op-on-ambiguity guard for duplicate-percentage keyframes (PR #1498 landmine). - gsapKeyframeFidelityMismatches: reuses gsapFidelityMismatches for the tween-level diff and layers a keyframe-array comparison (which the base diff doesn't inspect), matched by GSAP animation id. - runShadowGsapKeyframeFidelity: serialize-diff runner emitting op tag gsap_keyframe (no keyframe reader on ElementSnapshot, so no existence path). useGsapKeyframeOps synthesizes shadowKeyframeOp for addKeyframe / addKeyframeBatch / removeKeyframe; the commit chokepoint dispatches the keyframe-fidelity diff alongside the existing tween-fidelity path. sdkShadow.ts: runShadowDispatch now emits dispatched:false reason:unmapped_type if a future PatchOperation type ever escapes patchOpsToSdkEditOps, so the gap surfaces in telemetry instead of vanishing. Tests: sdkShadowGsapKeyframe.test.ts (18) covers index resolution, op mapping, the ambiguity guard, the keyframe-aware diff, the runner, and the unmapped-type guard. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
diff --git a/packages/studio/src/hooks/gsapScriptCommitTypes.ts b/packages/studio/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;
@@ -21,6 +22,8 @@ export interface CommitMutationOptions {
   beforeReload?: () => void;
   /** 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 = (
diff --git a/packages/studio/src/hooks/useGsapKeyframeOps.ts b/packages/studio/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}%`);
diff --git a/packages/studio/src/hooks/useGsapScriptCommits.ts b/packages/studio/src/hooks/useGsapScriptCommits.ts
@@ -3,6 +3,7 @@ import { findUnsafeMutationValues } from "@hyperframes/core/studio-api/finite-mu
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { applySoftReload } from "../utils/gsapSoftReload";
 import { resolveGsapFidelityArgs, runShadowGsapFidelity } from "../utils/sdkShadowGsapFidelity";
+import { runShadowGsapKeyframeFidelity } from "../utils/sdkShadowGsapKeyframe";
 import { updateKeyframeCacheFromParsed } from "./gsapKeyframeCacheHelpers";
 import {
   GsapMutationHttpError,
@@ -70,9 +71,10 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
     domEditSaveTimestampRef.current = Date.now();
     // Shadow value fidelity: diff the SDK's GSAP writer output against the
     // server's, from the same pre-op file. Fire-and-forget; server authoritative.
-    // Only meta-level ops carry shadowGsapOp today (add / update-meta / delete via
-    // useGsapAnimationOps). Per-property and keyframe handlers (useGsapPropertyDebounce,
-    // useGsapKeyframeOps) intentionally don't synthesize one yet — deferred follow-up.
+    // Meta-level ops carry shadowGsapOp (add / update-meta / delete via
+    // useGsapAnimationOps); keyframe ops carry shadowKeyframeOp (add/remove via
+    // useGsapKeyframeOps, handled by the gsap_keyframe block below). Per-property
+    // handlers (useGsapPropertyDebounce) don't synthesize one yet — deferred follow-up.
     // scriptText is null when the composition has no GSAP script; nothing to diff.
     const fidelityArgs = resolveGsapFidelityArgs(
       sdkSession,
@@ -83,6 +85,12 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
     if (fidelityArgs) {
       void runShadowGsapFidelity(fidelityArgs.before, fidelityArgs.op, fidelityArgs.serverScript);
     }
+    // Keyframe value fidelity (gsap_keyframe): same serialize-diff approach, but
+    // the SDK has no keyframe reader so there is no live-existence path — the diff
+    // is the only signal. Guarded on a live session + both scripts to diff.
+    if (sdkSession && options.shadowKeyframeOp && result.before != null && result.scriptText != null) {
+      void runShadowGsapKeyframeFidelity(result.before, options.shadowKeyframeOp, result.scriptText);
+    }
     if (result.before != null && result.after != null) {
       await editHistory.recordEdit({ label: options.label, kind: "manual", coalesceKey: options.coalesceKey, files: { [targetPath]: { before: result.before, after: result.after } } });
     }
diff --git a/packages/studio/src/utils/sdkShadow.ts b/packages/studio/src/utils/sdkShadow.ts
@@ -39,6 +39,16 @@ function isShadowableOp(op: PatchOperation): boolean {
   return true;
 }
 
+// PatchOperation types patchOpsToSdkEditOps knows how to map. Used by
+// runShadowDispatch to flag any unmapped type as visible telemetry rather than
+// silently dropping it (see the unmapped_type guard there).
+const MAPPED_PATCH_OP_TYPES: ReadonlySet<string> = new Set([
+  "inline-style",
+  "text-content",
+  "attribute",
+  "html-attribute",
+]);
+
 export function patchOpsToSdkEditOps(hfId: string, ops: PatchOperation[]): EditOp[] {
   const result: EditOp[] = [];
   const styles: Record<string, string | null> = {};
@@ -260,6 +270,23 @@ export function runShadowDispatch(
     });
     return;
   }
+  // Defensive: patchOpsToSdkEditOps silently drops PatchOperation types it
+  // doesn't map. PatchOperation.type is a closed union today, but emit a visible
+  // unmapped_type event if a future type ever slips through, so the gap surfaces
+  // in telemetry instead of vanishing.
+  // Map to the type string before find, so a future unmapped type is read as a
+  // plain string (no object cast; find on the closed union narrows to never).
+  const unmappedType = ops.map((op) => op.type).find((t) => !MAPPED_PATCH_OP_TYPES.has(t));
+  if (unmappedType !== undefined) {
+    trackStudioEvent("sdk_shadow_dispatch", {
+      op: "property",
+      dispatched: false,
+      reason: "unmapped_type",
+      type: unmappedType,
+      mismatchCount: 0,
+    });
+    return;
+  }
   const result = sdkShadowDispatch(session, hfId, ops);
   trackStudioEvent("sdk_shadow_dispatch", {
     op: "property",
diff --git a/packages/studio/src/utils/sdkShadowGsapKeyframe.test.ts b/packages/studio/src/utils/sdkShadowGsapKeyframe.test.ts
diff --git a/packages/studio/src/utils/sdkShadowGsapKeyframe.ts b/packages/studio/src/utils/sdkShadowGsapKeyframe.ts
