npm - @hyperframes/studio - Versions diffs - 0.6.105 → 0.6.107 - Mend

@hyperframes/studio 0.6.105 → 0.6.107

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

package/dist/assets/{index-BITwbxi-.css → index-BrhJl2JY.css} +1 -1
package/dist/assets/index-CVHV-S-B.js +296 -0
package/dist/assets/{index-NIdeStFw.js → index-P52mbTRb.js} +1 -1
package/dist/assets/{index-By4Ku5HI.js → index-zIK7PWvk.js} +1 -1
package/dist/index.html +2 -2
package/package.json +5 -5
package/src/components/StudioRightPanel.tsx +2 -0
package/src/components/editor/AnimationCard.tsx +8 -24
package/src/components/editor/ComputedTweenNotice.tsx +40 -0
package/src/components/editor/GsapAnimationSection.tsx +5 -24
package/src/components/editor/PropertyPanel.tsx +2 -0
package/src/components/editor/gsapAnimationCallbacks.ts +33 -0
package/src/components/editor/propertyPanelHelpers.ts +2 -0
package/src/contexts/DomEditContext.tsx +4 -0
package/src/hooks/gsapDragCommit.ts +90 -3
package/src/hooks/gsapRuntimeBridge.ts +70 -19
package/src/hooks/gsapRuntimeKeyframes.test.ts +47 -0
package/src/hooks/gsapRuntimeKeyframes.ts +198 -123
package/src/hooks/gsapScriptCommitTypes.ts +11 -0
package/src/hooks/serializeByKey.test.ts +83 -0
package/src/hooks/serializeByKey.ts +33 -0
package/src/hooks/useDomEditSession.ts +2 -0
package/src/hooks/useDomGeometryCommits.ts +9 -1
package/src/hooks/useGsapAnimationOps.ts +5 -1
package/src/hooks/useGsapAwareEditing.ts +21 -0
package/src/hooks/useGsapKeyframeOps.ts +21 -1
package/src/hooks/useGsapScriptCommits.ts +33 -5
package/src/hooks/useGsapTweenCache.ts +49 -7
package/src/utils/sdkShadow.test.ts +187 -1
package/src/utils/sdkShadow.ts +67 -10
package/src/utils/sdkShadowGsapFidelity.ts +46 -18
package/src/utils/sdkShadowGsapKeyframe.test.ts +265 -0
package/src/utils/sdkShadowGsapKeyframe.ts +257 -0
package/src/utils/sdkShadowNumeric.ts +11 -0
package/dist/assets/index-CKd39gmy.js +0 -296

package/src/utils/sdkShadowGsapKeyframe.test.ts ADDED Viewed

@@ -0,0 +1,265 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { openComposition } from "@hyperframes/sdk";
+import {
+  resolveKeyframeIndexByPercentage,
+  keyframeOpToEditOp,
+  gsapKeyframeFidelityMismatches,
+  runShadowGsapKeyframeFidelity,
+  type ShadowKeyframeOp,
+} from "./sdkShadowGsapKeyframe";
+import { runShadowDispatch } from "./sdkShadow";
+import type { PatchOperation } from "./sourcePatcher";
+// Capture sdk_shadow_dispatch telemetry.
+const trackedEvents: Array<{ event: string; props: Record<string, unknown> }> = [];
+vi.mock("./studioTelemetry", () => ({
+  trackStudioEvent: (event: string, props: Record<string, unknown>) =>
+    trackedEvents.push({ event, props }),
+}));
+// STUDIO_SDK_SHADOW_ENABLED defaults true (no env override in test), so the
+// runners are active here without mocking the availability module.
+beforeEach(() => {
+  trackedEvents.length = 0;
+});
+const lastShadow = () =>
+  trackedEvents.filter((e) => e.event === "sdk_shadow_dispatch").at(-1)?.props;
+const ANIM_ID = "#hero-to-0-position";
+function gsapHtml(scriptBody: string): string {
+  return /* html */ `<!DOCTYPE html><html><body>
+  <div data-hf-id="hf-hero" id="hero" class="clip">x</div>
+  <script>
+${scriptBody}
+  window.__timelines = [tl];
+  </script>
+</body></html>`;
+}
+const KF_SCRIPT = `
+  const tl = gsap.timeline({ paused: true });
+  tl.to("#hero", { keyframes: { "0%": { x: 0 }, "50%": { x: 100 }, "100%": { x: 200 } }, duration: 5 }, 0);`;
+// A script body string (not full HTML) for the index-resolution helpers.
+const KF_SCRIPT_BODY = KF_SCRIPT;
+const DUP_SCRIPT_BODY = `
+  const tl = gsap.timeline({ paused: true });
+  tl.to("#hero", { keyframes: { "0%": { x: 0 }, "50%": { x: 100 }, "50%": { x: 150 }, "100%": { x: 200 } }, duration: 5 }, 0);`;
+describe("resolveKeyframeIndexByPercentage", () => {
+  it("resolves a unique percentage to its 0-based index", () => {
+    expect(resolveKeyframeIndexByPercentage(KF_SCRIPT_BODY, ANIM_ID, 50)).toEqual({
+      keyframeIndex: 1,
+    });
+    expect(resolveKeyframeIndexByPercentage(KF_SCRIPT_BODY, ANIM_ID, 100)).toEqual({
+      keyframeIndex: 2,
+    });
+  });
+  it("matches within ~0.001 tolerance", () => {
+    expect(resolveKeyframeIndexByPercentage(KF_SCRIPT_BODY, ANIM_ID, 50.0005).keyframeIndex).toBe(
+      1,
+    );
+  });
+  it("returns null with not_found when no percentage matches", () => {
+    expect(resolveKeyframeIndexByPercentage(KF_SCRIPT_BODY, ANIM_ID, 33)).toEqual({
+      keyframeIndex: null,
+      reason: "not_found",
+    });
+  });
+  it("returns null with no_keyframes for an unknown animation", () => {
+    expect(resolveKeyframeIndexByPercentage(KF_SCRIPT_BODY, "#nope-to-0", 50)).toEqual({
+      keyframeIndex: null,
+      reason: "no_keyframes",
+    });
+  });
+  it("returns null with no_keyframes when script is empty", () => {
+    expect(resolveKeyframeIndexByPercentage(null, ANIM_ID, 50).reason).toBe("no_keyframes");
+  });
+  it("no-ops on ambiguity (duplicate-percentage keyframes — PR #1498 landmine)", () => {
+    expect(resolveKeyframeIndexByPercentage(DUP_SCRIPT_BODY, ANIM_ID, 50)).toEqual({
+      keyframeIndex: null,
+      reason: "ambiguous",
+    });
+  });
+  // Regression: a from/fromTo tween's id may normalize to "-to-" on write, so a
+  // "-from-"/"-fromTo-" animationId must fall back to the converted id (matching
+  // the writer's locateAnimationWithFallback) — else the keyframe diff goes blind.
+  it("falls back from a -from- id to the -to- tween", () => {
+    const fromId = ANIM_ID.replace("-to-", "-from-");
+    expect(resolveKeyframeIndexByPercentage(KF_SCRIPT_BODY, fromId, 50)).toEqual({
+      keyframeIndex: 1,
+    });
+  });
+});
+describe("keyframeOpToEditOp", () => {
+  it("maps add → addGsapKeyframe with position = percentage", () => {
+    const op: ShadowKeyframeOp = {
+      kind: "add",
+      animationId: ANIM_ID,
+      percentage: 25,
+      properties: { x: 50 },
+    };
+    expect(keyframeOpToEditOp(op, KF_SCRIPT_BODY)).toEqual({
+      op: { type: "addGsapKeyframe", animationId: ANIM_ID, position: 25, value: { x: 50 } },
+    });
+  });
+  it("maps remove → removeGsapKeyframe with resolved index", () => {
+    const op: ShadowKeyframeOp = { kind: "remove", animationId: ANIM_ID, percentage: 50 };
+    expect(keyframeOpToEditOp(op, KF_SCRIPT_BODY)).toEqual({
+      op: { type: "removeGsapKeyframe", animationId: ANIM_ID, keyframeIndex: 1 },
+    });
+  });
+  it("returns null op + reason when remove percentage is ambiguous", () => {
+    const op: ShadowKeyframeOp = { kind: "remove", animationId: ANIM_ID, percentage: 50 };
+    expect(keyframeOpToEditOp(op, DUP_SCRIPT_BODY)).toEqual({ op: null, reason: "ambiguous" });
+  });
+});
+describe("gsapKeyframeFidelityMismatches", () => {
+  it("reports no mismatches when keyframe arrays match", () => {
+    expect(gsapKeyframeFidelityMismatches(KF_SCRIPT_BODY, KF_SCRIPT_BODY, ANIM_ID)).toEqual([]);
+  });
+  it("reports a keyframes mismatch when arrays diverge", () => {
+    const other = `
+      const tl = gsap.timeline({ paused: true });
+      tl.to("#hero", { keyframes: { "0%": { x: 0 }, "50%": { x: 999 }, "100%": { x: 200 } }, duration: 5 }, 0);`;
+    const mismatches = gsapKeyframeFidelityMismatches(KF_SCRIPT_BODY, other, ANIM_ID);
+    expect(mismatches.some((m) => m.property === "keyframes")).toBe(true);
+  });
+});
+describe("runShadowGsapKeyframeFidelity (add)", () => {
+  it("emits gsap_keyframe with a keyframes mismatch when SDK adds but server didn't", async () => {
+    const beforeHtml = gsapHtml(KF_SCRIPT);
+    // server script unchanged (server "failed" to add the 25% keyframe) → drift
+    const session = await openComposition(beforeHtml);
+    const serverScript = session
+      .serialize()
+      .match(/<script\b[^>]*>([\s\S]*?)<\/script[^>]*>/i)?.[1];
+    expect(serverScript).toBeTruthy();
+    const op: ShadowKeyframeOp = {
+      kind: "add",
+      animationId: ANIM_ID,
+      percentage: 25,
+      properties: { x: 50 },
+    };
+    await runShadowGsapKeyframeFidelity(beforeHtml, op, serverScript);
+    const props = lastShadow();
+    expect(props?.op).toBe("gsap_keyframe");
+    expect(props?.dispatched).toBe(true);
+    expect(props?.mismatchCount).toBe(1);
+  });
+  it("emits dispatched:true mismatchCount:0 when SDK and server agree", async () => {
+    const beforeHtml = gsapHtml(KF_SCRIPT);
+    // Build the server's resulting script by applying the same op via the SDK.
+    const serverSession = await openComposition(beforeHtml);
+    serverSession.batch(() =>
+      serverSession.dispatch({
+        type: "addGsapKeyframe",
+        animationId: ANIM_ID,
+        position: 25,
+        value: { x: 50 },
+      }),
+    );
+    const serverScript = serverSession
+      .serialize()
+      .match(/<script\b[^>]*>([\s\S]*?)<\/script[^>]*>/i)?.[1];
+    const op: ShadowKeyframeOp = {
+      kind: "add",
+      animationId: ANIM_ID,
+      percentage: 25,
+      properties: { x: 50 },
+    };
+    await runShadowGsapKeyframeFidelity(beforeHtml, op, serverScript);
+    const props = lastShadow();
+    expect(props?.op).toBe("gsap_keyframe");
+    expect(props?.dispatched).toBe(true);
+    expect(props?.mismatchCount).toBe(0);
+  });
+});
+describe("runShadowGsapKeyframeFidelity (remove)", () => {
+  it("no-ops with reason when remove percentage is ambiguous", async () => {
+    const beforeHtml = gsapHtml(DUP_SCRIPT_BODY);
+    const op: ShadowKeyframeOp = { kind: "remove", animationId: ANIM_ID, percentage: 50 };
+    await runShadowGsapKeyframeFidelity(beforeHtml, op, "non-empty-server-script gsap");
+    const props = lastShadow();
+    expect(props?.op).toBe("gsap_keyframe");
+    expect(props?.dispatched).toBe(false);
+    expect(props?.reason).toBe("ambiguous");
+  });
+  it("dispatches a resolved remove and diffs", async () => {
+    const beforeHtml = gsapHtml(KF_SCRIPT);
+    const serverSession = await openComposition(beforeHtml);
+    serverSession.batch(() =>
+      serverSession.dispatch({
+        type: "removeGsapKeyframe",
+        animationId: ANIM_ID,
+        keyframeIndex: 1,
+      }),
+    );
+    const serverScript = serverSession
+      .serialize()
+      .match(/<script\b[^>]*>([\s\S]*?)<\/script[^>]*>/i)?.[1];
+    const op: ShadowKeyframeOp = { kind: "remove", animationId: ANIM_ID, percentage: 50 };
+    await runShadowGsapKeyframeFidelity(beforeHtml, op, serverScript);
+    const props = lastShadow();
+    expect(props?.op).toBe("gsap_keyframe");
+    expect(props?.dispatched).toBe(true);
+    expect(props?.mismatchCount).toBe(0);
+  });
+});
+describe("runShadowGsapKeyframeFidelity (guards)", () => {
+  it("skips when there is no server script", async () => {
+    const op: ShadowKeyframeOp = {
+      kind: "add",
+      animationId: ANIM_ID,
+      percentage: 25,
+      properties: { x: 50 },
+    };
+    await runShadowGsapKeyframeFidelity(gsapHtml(KF_SCRIPT), op, null);
+    expect(lastShadow()).toBeUndefined();
+  });
+});
+describe("runShadowDispatch unmapped-type guard", () => {
+  const ELEMENT_HTML = /* html */ `<!DOCTYPE html><html><body>
+    <div data-hf-id="hf-box" style="color: red;">Hi</div>
+  </body></html>`;
+  it("emits unmapped_type when a PatchOperation type isn't mapped", async () => {
+    const session = await openComposition(ELEMENT_HTML);
+    // PatchOperation.type is a closed union today; cast to exercise the defensive
+    // guard for a future unmapped type.
+    const ops = [{ type: "future-op", property: "x", value: "1" } as unknown as PatchOperation];
+    runShadowDispatch(session, { hfId: "hf-box" } as never, ops);
+    const props = lastShadow();
+    expect(props?.op).toBe("property");
+    expect(props?.dispatched).toBe(false);
+    expect(props?.reason).toBe("unmapped_type");
+    expect(props?.type).toBe("future-op");
+  });
+  it("dispatches normally for known PatchOperation types", async () => {
+    const session = await openComposition(ELEMENT_HTML);
+    const ops: PatchOperation[] = [{ type: "inline-style", property: "color", value: "#00f" }];
+    runShadowDispatch(session, { hfId: "hf-box" } as never, ops);
+    const props = lastShadow();
+    expect(props?.dispatched).toBe(true);
+    expect(props?.reason).toBeUndefined();
+  });
+});

package/src/utils/sdkShadowGsapKeyframe.ts ADDED Viewed

@@ -0,0 +1,257 @@
+/**
+ * GSAP keyframe-op shadow (serialize round-trip diff). New module for the Stage 7
+ * shadow-parity push — kept out of sdkShadow.ts / sdkShadowGsapFidelity.ts so the
+ * shared files stay untouched (only additive imports) and the studio 600-line cap
+ * holds.
+ *
+ * Unlike tweens, the SDK exposes NO keyframe reader on ElementSnapshot, so there
+ * is no existence-parity path here. Instead we compare the two writers' output:
+ * open a fresh SDK doc from the server's pre-op file, dispatch the equivalent
+ * keyframe op, serialize, and diff the SDK's GSAP script against the server's
+ * resulting script.
+ *
+ * gsapFidelityMismatches (reused) matches tweens by resolved target element +
+ * method + position and diffs tween-level fields — but it does NOT look inside a
+ * tween's `keyframes` array. Keyframe drift therefore needs a dedicated diff,
+ * layered on top of the reused tween-level diff, matched by the GSAP animation id.
+ *
+ * SDK mapping (main, pre PR #1498 percentage-variant):
+ *   add    → addGsapKeyframe{animationId, position: percentage, value: properties}
+ *   remove → removeGsapKeyframe{animationId, keyframeIndex} — the studio op is
+ *            percentage-based, so we resolve percentage → index against the pre-op
+ *            script (KF_PERCENT_TOLERANCE, aligned with the writer ~0.001) and
+ *            no-op on ambiguity (duplicate-percentage keyframes can't be told
+ *            apart by percentage — landmine from PR #1498).
+ */
+import { openComposition } from "@hyperframes/sdk";
+import type { EditOp } from "@hyperframes/sdk";
+import { parseGsapScriptAcorn } from "@hyperframes/core/gsap-parser-acorn";
+import type { GsapPercentageKeyframe } from "@hyperframes/core/gsap-parser";
+import { STUDIO_SDK_SHADOW_ENABLED } from "../components/editor/manualEditingAvailability";
+import { trackStudioEvent } from "./studioTelemetry";
+import type { SdkShadowMismatch } from "./sdkShadow";
+import {
+  extractGsapScript,
+  gsapFidelityMismatches,
+  makeSelectorResolver,
+} from "./sdkShadowGsapFidelity";
+// Match the GSAP writer's percentage equality tolerance so a remove resolves to
+// the same keyframe the server would pick (writer rounds to ~3 decimals).
+const KF_PERCENT_TOLERANCE = 0.001;
+export type ShadowKeyframeOp =
+  | {
+      kind: "add";
+      animationId: string;
+      percentage: number;
+      properties: Record<string, number | string>;
+    }
+  | { kind: "remove"; animationId: string; percentage: number };
+// ─── percentage → SDK op mapping ──────────────────────────────────────────────
+function findAnimationKeyframes(
+  script: string,
+  animationId: string,
+): GsapPercentageKeyframe[] | null {
+  const parsed = parseGsapScriptAcorn(script);
+  // Match the writer's locateAnimationWithFallback (gsapParser.ts): a from/fromTo
+  // tween's derived id may be normalized to "-to-" on write, so fall back to the
+  // converted id when the exact one isn't found — otherwise the keyframe diff
+  // goes blind (both scripts resolve null → falsely "clean") on converted tweens.
+  const convertedId = animationId.replace(/-from-|-fromTo-/, "-to-");
+  const anim =
+    parsed.animations.find((a) => a.id === animationId) ??
+    parsed.animations.find((a) => a.id === convertedId);
+  return anim?.keyframes?.keyframes ?? null;
+}
+export interface KeyframeRemoveResolution {
+  /** Resolved 0-based index, or null when it can't be safely resolved. */
+  keyframeIndex: number | null;
+  /** Why no index — for telemetry when keyframeIndex is null. */
+  reason?: "no_keyframes" | "not_found" | "ambiguous";
+}
+/**
+ * Resolve a percentage-based remove to a keyframe index against the pre-op
+ * script. Returns null index (with a reason) when there are no keyframes, the
+ * percentage matches none, or — per the PR #1498 landmine — more than one
+ * keyframe shares the percentage (can't be disambiguated by percentage alone).
+ * Pure + exported so the mapping is unit-testable without an SDK session.
+ */
+export function resolveKeyframeIndexByPercentage(
+  script: string | null | undefined,
+  animationId: string,
+  percentage: number,
+): KeyframeRemoveResolution {
+  if (!script) return { keyframeIndex: null, reason: "no_keyframes" };
+  const kfs = findAnimationKeyframes(script, animationId);
+  if (!kfs || kfs.length === 0) return { keyframeIndex: null, reason: "no_keyframes" };
+  const matches: number[] = [];
+  for (let i = 0; i < kfs.length; i++) {
+    if (Math.abs(kfs[i]?.percentage - percentage) <= KF_PERCENT_TOLERANCE) matches.push(i);
+  }
+  if (matches.length === 0) return { keyframeIndex: null, reason: "not_found" };
+  if (matches.length > 1) return { keyframeIndex: null, reason: "ambiguous" };
+  return { keyframeIndex: matches[0] };
+}
+/**
+ * Map a studio keyframe op to the SDK EditOp. For a remove this needs the pre-op
+ * script to resolve percentage → index; returns null (with a reason) when the
+ * index can't be safely resolved so the caller can emit a no-op-with-reason
+ * event instead of dispatching the wrong keyframe.
+ */
+export function keyframeOpToEditOp(
+  op: ShadowKeyframeOp,
+  beforeScript: string | null | undefined,
+): { op: EditOp } | { op: null; reason: string } {
+  if (op.kind === "add") {
+    return {
+      op: {
+        type: "addGsapKeyframe",
+        animationId: op.animationId,
+        position: op.percentage,
+        value: op.properties,
+      },
+    };
+  }
+  const resolved = resolveKeyframeIndexByPercentage(beforeScript, op.animationId, op.percentage);
+  if (resolved.keyframeIndex === null) {
+    return { op: null, reason: resolved.reason ?? "unresolved" };
+  }
+  return {
+    op: {
+      type: "removeGsapKeyframe",
+      animationId: op.animationId,
+      keyframeIndex: resolved.keyframeIndex,
+    },
+  };
+}
+// ─── Keyframe-aware fidelity diff ─────────────────────────────────────────────
+function canonicalKeyframe(kf: GsapPercentageKeyframe): string {
+  const props: Record<string, unknown> = {};
+  for (const key of Object.keys(kf.properties).sort()) {
+    const v = kf.properties[key];
+    props[key] =
+      typeof v === "string" && v.trim() !== "" && !Number.isNaN(Number(v)) ? Number(v) : v;
+  }
+  return JSON.stringify({ pct: Math.round(kf.percentage * 1000) / 1000, ease: kf.ease, props });
+}
+function canonicalKeyframes(kfs: GsapPercentageKeyframe[] | null): string {
+  if (!kfs) return "[]";
+  return JSON.stringify(
+    [...kfs].sort((a, b) => a.percentage - b.percentage).map(canonicalKeyframe),
+  );
+}
+/**
+ * Diff two GSAP scripts for a keyframe op: the reused tween-level diff PLUS a
+ * keyframe-array comparison for the targeted animation (which the tween-level
+ * diff doesn't inspect). Reports a `keyframes` value_mismatch when the SDK and
+ * server keyframe arrays diverge canonically.
+ */
+export function gsapKeyframeFidelityMismatches(
+  sdkScript: string,
+  serverScript: string,
+  animationId: string,
+  resolveSelector?: (sel: string) => string,
+): SdkShadowMismatch[] {
+  const mismatches = gsapFidelityMismatches(sdkScript, serverScript, resolveSelector);
+  const sdkKfs = findAnimationKeyframes(sdkScript, animationId);
+  const serverKfs = findAnimationKeyframes(serverScript, animationId);
+  const sdkCanon = canonicalKeyframes(sdkKfs);
+  const serverCanon = canonicalKeyframes(serverKfs);
+  if (sdkCanon !== serverCanon) {
+    mismatches.push({
+      kind: "value_mismatch",
+      hfId: animationId,
+      property: "keyframes",
+      expected: serverCanon,
+      actual: sdkCanon,
+    });
+  }
+  return mismatches;
+}
+// ─── Telemetry runner ─────────────────────────────────────────────────────────
+/**
+ * Shadow a GSAP keyframe op: open a fresh SDK doc from the server's pre-op file,
+ * apply the equivalent keyframe op, serialize, and diff against the server's
+ * resulting script. Emits sdk_shadow_dispatch op: "gsap_keyframe". Async,
+ * fire-and-forget; server stays authoritative. No-op when shadow is disabled.
+ */
+export async function runShadowGsapKeyframeFidelity(
+  beforeHtml: string | null | undefined,
+  op: ShadowKeyframeOp,
+  serverScript: string | null | undefined,
+): Promise<void> {
+  if (!STUDIO_SDK_SHADOW_ENABLED) return;
+  // No server script to diff against → skip the (costly) openComposition.
+  if (!serverScript || !beforeHtml) return;
+  const beforeScript = extractGsapScript(beforeHtml);
+  const mapped = keyframeOpToEditOp(op, beforeScript);
+  if (mapped.op === null) {
+    // Ambiguous / not-found percentage: don't dispatch the wrong keyframe.
+    trackStudioEvent("sdk_shadow_dispatch", {
+      op: "gsap_keyframe",
+      dispatched: false,
+      reason: mapped.reason,
+      mismatchCount: 0,
+    });
+    return;
+  }
+  const editOp = mapped.op;
+  try {
+    const session = await openComposition(beforeHtml);
+    const verdict = session.can(editOp);
+    if (!verdict.ok) {
+      trackStudioEvent("sdk_shadow_dispatch", {
+        op: "gsap_keyframe",
+        dispatched: false,
+        reason: "cannot_dispatch",
+        code: verdict.code,
+        mismatchCount: 0,
+      });
+      return;
+    }
+    session.batch(() => session.dispatch(editOp));
+    const sdkScript = extractGsapScript(session.serialize());
+    if (sdkScript == null) {
+      trackStudioEvent("sdk_shadow_dispatch", {
+        op: "gsap_keyframe",
+        dispatched: false,
+        reason: "no_sdk_script",
+        mismatchCount: 0,
+      });
+      return;
+    }
+    const mismatches = gsapKeyframeFidelityMismatches(
+      sdkScript,
+      serverScript,
+      op.animationId,
+      makeSelectorResolver(beforeHtml),
+    );
+    trackStudioEvent("sdk_shadow_dispatch", {
+      op: "gsap_keyframe",
+      dispatched: true,
+      mismatchCount: mismatches.length,
+      mismatches: JSON.stringify(mismatches),
+    });
+  } catch (err) {
+    trackStudioEvent("sdk_shadow_dispatch", {
+      op: "gsap_keyframe",
+      dispatched: false,
+      reason: "fidelity_error",
+      error: String(err),
+      mismatchCount: 0,
+    });
+  }
+}

package/src/utils/sdkShadowNumeric.ts ADDED Viewed

@@ -0,0 +1,11 @@
+/**
+ * Relative-epsilon numeric equality shared by the shadow diffs (timing parity +
+ * GSAP value fidelity). Both writers round-trip durations/positions through JS
+ * number formatting, so a value like 3.1 can read back as 3.0999999999999996.
+ * Treat values within 1e-6 * max(1, |a|, |b|) as equal — tight enough that a
+ * real 2 vs 1 (or 0.5 vs 0.49) still flags, loose enough to absorb float noise.
+ */
+export function relEqual(a: number, b: number): boolean {
+  if (a === b) return true;
+  return Math.abs(a - b) <= 1e-6 * Math.max(1, Math.abs(a), Math.abs(b));
+}