@hyperframes/studio 0.6.105 → 0.6.107

package/src/hooks/useGsapScriptCommits.ts

@@ -1,9 +1,11 @@
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
 import { findUnsafeMutationValues } from "@hyperframes/core/studio-api/finite-mutation";
 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 { createKeyedSerializer } from "./serializeByKey";
 import {
   GsapMutationHttpError,
   formatGsapMutationRejectionToast,
@@ -45,10 +47,16 @@ async function mutateGsapScript(
 // oxfmt-ignore
 // fallow-ignore-next-line complexity
 export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIframeRef, editHistory, domEditSaveTimestampRef, reloadPreview, onCacheInvalidate, onFileContentChanged, showToast, sdkSession }: GsapScriptCommitsParams) {
+  // Serializer for per-key commits (options.serializeKey). Keyed by
+  // `gsap:${animationId}:meta`, it chains a meta commit onto the prior one for
+  // the same animationId so their POSTs can't interleave — which is what made
+  // the shadow fidelity diff pair an op with a stale server result and report
+  // false ease mismatches. Held in a ref so the chain survives re-renders.
+  const serializerRef = useRef(createKeyedSerializer());
   // Pre-existing complexity (server mutate + history + reload branches); this PR
   // adds only a guarded shadow-fidelity dispatch.
   // fallow-ignore-next-line complexity
-  const commitMutation = useCallback(async (selection: DomEditSelection, mutation: Record<string, unknown>, options: CommitMutationOptions) => {
+  const runCommit = useCallback(async (selection: DomEditSelection, mutation: Record<string, unknown>, options: CommitMutationOptions) => {
     const pid = projectIdRef.current;
     if (!pid) return;
     const unsafeFields = findUnsafeMutationValues(mutation);
@@ -70,9 +78,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 +92,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 } } });
     }
@@ -97,6 +112,19 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
     }
     onCacheInvalidate();
   }, [projectIdRef, activeCompPath, previewIframeRef, editHistory, domEditSaveTimestampRef, reloadPreview, onCacheInvalidate, onFileContentChanged, showToast, sdkSession]);
+  // Every GSAP-script commit is a read-modify-write of one file. Overlapping
+  // commits to the SAME file (any op type, any animation) interleave server-side
+  // and make the shadow fidelity diff pair an op with a stale server result —
+  // the false ease/value mismatches this serializer exists to prevent. So
+  // serialize per target file by default; an explicit serializeKey overrides.
+  const commitMutation = useCallback(
+    (selection: DomEditSelection, mutation: Record<string, unknown>, options: CommitMutationOptions) => {
+      const file = selection.sourceFile || activeCompPath || "index.html";
+      const key = options.serializeKey ?? `gsap-file:${file}`;
+      return serializerRef.current(key, () => runCommit(selection, mutation, options));
+    },
+    [runCommit, activeCompPath],
+  );
   const trackGsapSaveFailure = useGsapSaveFailureTelemetry(activeCompPath);
   const commitMutationSafely = useSafeGsapCommitMutation(commitMutation, trackGsapSaveFailure, showToast);
   const propertyOps = useGsapPropertyDebounce(commitMutationSafely);

package/src/hooks/useGsapTweenCache.ts

@@ -211,6 +211,7 @@ export function useGsapAnimationsForElement(
             keyframes: runtime.keyframes,
             ...(runtime.easeEach ? { easeEach: runtime.easeEach } : {}),
           },
+          ...(runtime.arcPath ? { arcPath: runtime.arcPath } : {}),
         };
       });
     }
@@ -243,6 +244,7 @@ export function useGsapAnimationsForElement(
                     keyframes: runtimeEntry.keyframes,
                     ...(runtimeEntry.easeEach ? { easeEach: runtimeEntry.easeEach } : {}),
                   },
+                  ...(runtimeEntry.arcPath ? { arcPath: runtimeEntry.arcPath } : {}),
                 },
               ];
             }
@@ -358,19 +360,30 @@ export function usePopulateKeyframeCacheForFile(
 
     const sf = sourceFile;
     fetchParsedAnimations(projectId, sf).then((parsed) => {
-      if (!parsed) return;
+      if (!parsed) {
+        return;
+      }
       const { setKeyframeCache } = usePlayerStore.getState();
-      // Drop the file's stale entries (including the bare keys consumers read)
-      // before repopulating, so an element whose keyframes were removed and is
-      // absent from this scan doesn't keep showing diamonds.
       clearKeyframeCacheForFile(sf);
       const { elements } = usePlayerStore.getState();
+      console.log(
+        "[kf:static] elements in store:",
+        elements
+          .map((e) => e.domId)
+          .filter(Boolean)
+          .join(", "),
+      );
       const mergedByElement = new Map<string, GsapKeyframesData>();
       for (const anim of parsed.animations) {
         const id = extractIdFromSelector(anim.targetSelector);
         if (!id) continue;
+        if (anim.hasUnresolvedKeyframes) {
+          continue;
+        }
         const kfData = anim.keyframes ?? synthesizeFlatTweenKeyframes(anim);
-        if (!kfData) continue;
+        if (!kfData) {
+          continue;
+        }
         const tweenPos =
           anim.resolvedStart ?? (typeof anim.position === "number" ? anim.position : 0);
         const tweenDur = anim.duration ?? 1;
@@ -402,6 +415,12 @@ export function usePopulateKeyframeCacheForFile(
           mergedByElement.set(id, { ...kfData, keyframes: clipKeyframes });
         }
       }
+      console.log(
+        "[kf:static] merged elements:",
+        [...mergedByElement.keys()].join(", "),
+        "kf counts:",
+        [...mergedByElement.entries()].map(([k, v]) => `${k}:${v.keyframes.length}`).join(", "),
+      );
       for (const [id, kfData] of mergedByElement) {
         setKeyframeCache(`${sf}#${id}`, kfData);
         setKeyframeCache(id, kfData);
@@ -428,14 +447,37 @@ export function usePopulateKeyframeCacheForFile(
       const iframe =
         iframeRef?.current ?? document.querySelector<HTMLIFrameElement>("iframe[src*='/preview/']");
       if (!iframe) return false;
-      const scanned = scanAllRuntimeKeyframes(iframe);
+      // Clip dims per element so the scan converts tween-relative keyframes to
+      // clip-relative (matching the static path) instead of timeline-relative.
+      const clipById = new Map<string, { start: number; duration: number }>();
+      for (const el of usePlayerStore.getState().elements) {
+        if (el.domId) clipById.set(el.domId, { start: el.start, duration: el.duration });
+      }
+      const scanned = scanAllRuntimeKeyframes(iframe, clipById);
+      console.log(
+        "[kf:runtime] scanned",
+        scanned.size,
+        "elements:",
+        [...scanned.keys()].join(", "),
+      );
       if (scanned.size === 0) return false;
       const { setKeyframeCache, keyframeCache } = usePlayerStore.getState();
       for (const [id, data] of scanned) {
         const cacheKey = `${sf}#${id}`;
         const fallbackKey = `index.html#${id}`;
-        if (keyframeCache.has(cacheKey) || keyframeCache.has(fallbackKey) || keyframeCache.has(id))
+        const alreadyCached =
+          keyframeCache.has(cacheKey) || keyframeCache.has(fallbackKey) || keyframeCache.has(id);
+        if (alreadyCached) {
           continue;
+        }
+        console.log(
+          "[kf:runtime] adding runtime entry:",
+          id,
+          "kfs:",
+          data.keyframes.length,
+          "arc:",
+          !!data.arcPath,
+        );
         const entry = {
           format: "percentage" as const,
           keyframes: data.keyframes,

package/src/utils/sdkShadow.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it, vi, beforeEach } from "vitest";
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
 import {
   patchOpsToSdkEditOps,
   runShadowDelete,
@@ -10,8 +10,10 @@ import {
   SdkShadowMismatch,
 } from "./sdkShadow";
 import type { ShadowGsapOp } from "./sdkShadow";
+import { makeSelectorResolver } from "./sdkShadowGsapFidelity";
 import type { PatchOperation } from "./sourcePatcher";
 import { openComposition } from "@hyperframes/sdk";
+import { Window } from "happy-dom";
 
 // Capture sdk_shadow_dispatch telemetry for the non-PatchOperation runners.
 const trackedEvents: Array<{ event: string; props: Record<string, unknown> }> = [];
@@ -108,6 +110,7 @@ describe("sdkShadowDispatch (integration)", () => {
     expect(session.getElement("hf-box")?.inlineStyles.color).toBe("#00f");
   });
 
+  // fallow-ignore-next-line code-duplication
   it("does NOT false-mismatch a hyphenated style property (kebab op vs camelCase snapshot)", async () => {
     const { sdkShadowDispatch } = await import("./sdkShadow");
     const session = await openComposition(BASE_HTML);
@@ -147,6 +150,59 @@ describe("sdkShadowDispatch (integration)", () => {
     expect(session.getElement("hf-box")?.text).toBe("Updated");
   });
 
+  // Fix 2: text parity normalization. snapshot.text is trimmed by the SDK, so a
+  // trailing-whitespace-only difference between the op value and the snapshot must
+  // not flag.
+  it("does NOT false-mismatch trailing-whitespace-only text difference", async () => {
+    const { sdkShadowDispatch } = await import("./sdkShadow");
+    const session = await openComposition(BASE_HTML);
+
+    const ops: PatchOperation[] = [{ type: "text-content", property: "text", value: "World   " }];
+    const result = sdkShadowDispatch(session, "hf-box", ops);
+
+    expect(result.dispatched).toBe(true);
+    expect(result.mismatches).toHaveLength(0); // trimmed both sides
+  });
+
+  // Empty-string op value vs an absent (null) snapshot text must collapse to equal
+  // — both mean "no text content".
+  it("treats empty-string text op and null snapshot text as equal", async () => {
+    const { sdkShadowDispatch } = await import("./sdkShadow");
+    const EMPTY_HTML = /* html */ `<!DOCTYPE html>
+<html><body><img data-hf-id="hf-img" src="x.png" /></body></html>`;
+    const session = await openComposition(EMPTY_HTML);
+
+    const ops: PatchOperation[] = [{ type: "text-content", property: "text", value: "" }];
+    const result = sdkShadowDispatch(session, "hf-img", ops);
+
+    expect(result.dispatched).toBe(true);
+    expect(result.mismatches).toHaveLength(0); // "" vs null → both null
+  });
+
+  // Fix 3 verdict (REAL DIVERGENCE, not a readback artifact): the inline-style
+  // read-back already reads only the AUTHORED style attribute (getElementStyles →
+  // parseStyleAttr), never computed styles. The transform-origin divergence
+  // (expected null actual "center center") was a genuine SDK bug — setStyle
+  // removal of a HYPHENATED property silently no-opped because setElementStyles
+  // deleted the kebab key while the style map is keyed camelCase. Now FIXED in
+  // the SDK (model.ts setElementStyles normalizes the key via toCamel), so the
+  // shadow sees parity: removal applies and there is no mismatch.
+  it("reports clean removal of a hyphenated style (SDK setStyle kebab/camel fix)", async () => {
+    const { sdkShadowDispatch } = await import("./sdkShadow");
+    const TO_HTML = /* html */ `<!DOCTYPE html>
+<html><body><div data-hf-id="hf-box" style="transform-origin: center center">x</div></body></html>`;
+    const session = await openComposition(TO_HTML);
+
+    const ops: PatchOperation[] = [
+      { type: "inline-style", property: "transform-origin", value: null },
+    ];
+    const result = sdkShadowDispatch(session, "hf-box", ops);
+
+    // The SDK now removes the hyphenated property, so the shadow read-back agrees.
+    expect(result.dispatched).toBe(true);
+    expect(result.mismatches).toHaveLength(0);
+  });
+
   it("applies attribute op and reads back via session.getElement", async () => {
     const { sdkShadowDispatch } = await import("./sdkShadow");
     const session = await openComposition(BASE_HTML);
@@ -237,6 +293,35 @@ describe("runShadowDelete", () => {
       reason: "cannot_dispatch",
     });
   });
+
+  // Fix 4 verdict (REAL SDK id-resolution divergence, NOT a readback bug): when a
+  // bare hf-id collides between a sub-composition element (scopedId
+  // "hf-host/hf-dup") and a top-level sibling (scopedId "hf-dup"), removeElement
+  // resolves the bare id via resolveScoped → querySelector (document-order-first,
+  // removes the INNER instance), but getElement prefers the canonical top-level
+  // match (scopedId === id) which SURVIVES. The shadow then correctly reports
+  // expected "removed" / actual "present". The readback here is correct (it checks
+  // the same id it dispatched); the fix belongs in the SDK's id resolution
+  // (resolveScoped vs getElement agreement), not in this file.
+  const DUP_ID_HTML = /* html */ `<!DOCTYPE html><html><body>
+    <div data-hf-id="hf-root" data-hf-root>
+      <div data-hf-id="hf-host" data-composition-file="sub.html">
+        <div data-hf-id="hf-dup">inner</div>
+      </div>
+      <div data-hf-id="hf-dup">outer</div>
+    </div>
+  </body></html>`;
+
+  it("reports clean delete for a duplicate bare id (SDK resolves removeElement/getElement to the same instance)", async () => {
+    const session = await openComposition(DUP_ID_HTML);
+    runShadowDelete(session, "hf-dup");
+    // SDK fix (agree removeElement/getElement on duplicate bare ids): both now
+    // resolve a bare id to the canonical (top-level) instance, so removeElement
+    // drops exactly the element the readback checks → no mismatch. (Previously
+    // removeElement dropped the inner instance while the top-level survived,
+    // which this shadow correctly flagged; that divergence is now fixed.)
+    expect(lastShadow()).toMatchObject({ op: "delete", dispatched: true, mismatchCount: 0 });
+  });
 });
 
 describe("runShadowTiming", () => {
@@ -249,6 +334,38 @@ describe("runShadowTiming", () => {
     expect(el?.trackIndex).toBe(1);
     expect(lastShadow()).toMatchObject({ op: "timing", dispatched: true, mismatchCount: 0 });
   });
+
+  // Fix 1: float-precision tolerance. The SDK computes durations arithmetically
+  // (returning e.g. 3.0999999999999996); the server stores the rounded literal
+  // (3.1). A relative epsilon must treat these as equal, while a real difference
+  // still flags. A fake session returns the imprecise value on read-back.
+  type FakeTiming = { start?: number; duration?: number; trackIndex?: number };
+  function fakeTimingSession(readback: FakeTiming) {
+    return {
+      can: () => ({ ok: true }),
+      batch: (fn: () => void) => fn(),
+      dispatch: () => {},
+      getElement: () => readback,
+    } as unknown as Parameters<typeof runShadowTiming>[0];
+  }
+
+  it("does NOT flag float-precision duration drift (3.1 vs 3.0999999999999996)", () => {
+    const session = fakeTimingSession({ duration: 3.0999999999999996 });
+    runShadowTiming(session, "hf-clip", { duration: 3.1 });
+    expect(lastShadow()).toMatchObject({ op: "timing", dispatched: true, mismatchCount: 0 });
+  });
+
+  it("does NOT flag float-precision start drift (21.36 vs 21.360000000000014)", () => {
+    const session = fakeTimingSession({ start: 21.360000000000014 });
+    runShadowTiming(session, "hf-clip", { start: 21.36 });
+    expect(lastShadow()).toMatchObject({ op: "timing", dispatched: true, mismatchCount: 0 });
+  });
+
+  it("STILL flags a real duration difference (3.1 vs 3.5)", () => {
+    const session = fakeTimingSession({ duration: 3.5 });
+    runShadowTiming(session, "hf-clip", { duration: 3.1 });
+    expect(lastShadow()).toMatchObject({ op: "timing", dispatched: true, mismatchCount: 1 });
+  });
 });
 
 describe("runShadowGsapTween", () => {
@@ -304,6 +421,29 @@ describe("gsapFidelityMismatches", () => {
     expect(mismatches.some((m) => m.property === "duration")).toBe(true);
   });
 
+  it("does NOT flag sub-ULP float-formatting noise in duration", () => {
+    // 3.1 vs 3.0999999999999996 is the same value after writer round-trips;
+    // relative-epsilon compare must treat it as equal, not drift.
+    const sdk = `var tl = gsap.timeline({ paused: true });
+tl.to("[data-hf-id=\\"hf-box\\"]", { opacity: 1, duration: 3.1 }, 0);
+window.__timelines["t"] = tl;`;
+    const server = `var tl = gsap.timeline({ paused: true });
+tl.to("[data-hf-id=\\"hf-box\\"]", { opacity: 1, duration: 3.0999999999999996 }, 0);
+window.__timelines["t"] = tl;`;
+    expect(gsapFidelityMismatches(sdk, server)).toEqual([]);
+  });
+
+  it("STILL flags a real integer duration drift (2 vs 1) past the epsilon", () => {
+    const sdk = `var tl = gsap.timeline({ paused: true });
+tl.to("[data-hf-id=\\"hf-box\\"]", { opacity: 1, duration: 1 }, 0);
+window.__timelines["t"] = tl;`;
+    const server = `var tl = gsap.timeline({ paused: true });
+tl.to("[data-hf-id=\\"hf-box\\"]", { opacity: 1, duration: 2 }, 0);
+window.__timelines["t"] = tl;`;
+    const mismatches = gsapFidelityMismatches(sdk, server);
+    expect(mismatches.some((m) => m.property === "duration")).toBe(true);
+  });
+
   it("flags a tween present in one script but not the other", () => {
     const empty = `var tl = gsap.timeline({ paused: true });
 window.__timelines["t"] = tl;`;
@@ -345,6 +485,52 @@ window.__timelines["t"] = tl;`;
     // With a resolver: matched by element → no mismatch.
     expect(gsapFidelityMismatches(sdk, server, resolve)).toEqual([]);
   });
+
+  // Drive makeSelectorResolver against a real DOM (happy-dom shims the
+  // browser-only DOMParser the resolver depends on; the studio test env is node).
+  describe("makeSelectorResolver unifies selector forms (real DOM)", () => {
+    const origDomParser = (globalThis as { DOMParser?: unknown }).DOMParser;
+    beforeEach(() => {
+      (globalThis as { DOMParser?: unknown }).DOMParser = new Window().DOMParser;
+    });
+    afterEach(() => {
+      (globalThis as { DOMParser?: unknown }).DOMParser = origDomParser;
+    });
+
+    it("collapses #id / .class / [data-hf-id] for the SAME element to one key", () => {
+      // Element carries all three forms; the server may emit #id or .class while
+      // the SDK emits [data-hf-id]. All must resolve to the same canonical key.
+      const html = `<div data-hf-id="hf-9flp" class="caption-layer" id="intro-layer"></div>`;
+      const resolve = makeSelectorResolver(html);
+      const viaHfId = resolve('[data-hf-id="hf-9flp"]');
+      expect(resolve(".caption-layer")).toBe(viaHfId);
+      expect(resolve("#intro-layer")).toBe(viaHfId);
+    });
+
+    it("unifies SDK [data-hf-id] and server .class tweens in the fidelity diff", () => {
+      const html = `<div data-hf-id="hf-9flp" class="caption-layer"></div>`;
+      const resolve = makeSelectorResolver(html);
+      const sdkScript = `var tl = gsap.timeline({ paused: true });
+tl.from("[data-hf-id=\\"hf-9flp\\"]", { opacity: 0, duration: 1 }, 0);
+window.__timelines["t"] = tl;`;
+      const serverScript = `var tl = gsap.timeline({ paused: true });
+tl.from(".caption-layer", { opacity: 0, duration: 1 }, 0);
+window.__timelines["t"] = tl;`;
+      // Without unification these flag present/absent; the resolver collapses them.
+      expect(gsapFidelityMismatches(sdkScript, serverScript).length).toBeGreaterThan(0);
+      expect(gsapFidelityMismatches(sdkScript, serverScript, resolve)).toEqual([]);
+    });
+
+    it("collapses different selector forms for an element WITHOUT a data-hf-id", () => {
+      // No hf-id present: the resolver must still key both forms to the same node
+      // (not leave .class vs #id as distinct raw-selector keys).
+      const html = `<div class="caption-layer" id="intro-layer"></div>`;
+      const resolve = makeSelectorResolver(html);
+      expect(resolve(".caption-layer")).toBe(resolve("#intro-layer"));
+      // And it is NOT the raw selector fallback.
+      expect(resolve(".caption-layer")).not.toBe(".caption-layer");
+    });
+  });
 });
 
 describe("runShadowGsapFidelity", () => {

package/src/utils/sdkShadow.ts

@@ -12,6 +12,7 @@ import type { Composition } from "@hyperframes/sdk";
 import type { EditOp, GsapTweenSpec } from "@hyperframes/sdk";
 import { STUDIO_SDK_SHADOW_ENABLED } from "../components/editor/manualEditingAvailability";
 import { trackStudioEvent } from "./studioTelemetry";
+import { relEqual } from "./sdkShadowNumeric";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import type { PatchOperation } from "./sourcePatcher";
 
@@ -39,6 +40,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> = {};
@@ -121,13 +132,29 @@ function kebabToCamel(prop: string): string {
   return prop.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
 }
 
+// Text parity: the SDK snapshot.text is trimmed, so trim the op value too.
+// An empty string and absent text (null) are treated as equivalent (collapsed
+// to null) so "" vs null does not flag — both mean "no text content".
+function normalizeText(value: string | null | undefined): string | null {
+  if (value == null) return null;
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+}
+
 const OP_FIELD_RESOLVERS: Record<string, OpFieldResolver> = {
   "inline-style": (op, flat) => ({
     property: op.property,
     expected: op.value,
     actual: flat.styles[kebabToCamel(op.property)] ?? flat.styles[op.property] ?? null,
   }),
-  "text-content": (op, flat) => ({ property: "text", expected: op.value ?? "", actual: flat.text }),
+  // snapshot.text is already TRIMMED; trim the expected op value to match, so
+  // trailing-whitespace differences don't flag. Empty-vs-absent ("" vs null) is
+  // collapsed in checkOpParity. A genuinely different text value still flags.
+  "text-content": (op, flat) => ({
+    property: "text",
+    expected: normalizeText(op.value),
+    actual: normalizeText(flat.text),
+  }),
   attribute: (op, flat) => ({
     property: attrName(op.property),
     expected: op.value ?? null,
@@ -244,6 +271,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",
@@ -345,6 +389,20 @@ export interface ShadowTiming {
   trackIndex?: number;
 }
 
+// start/duration tolerate float-precision drift (SDK computes them
+// arithmetically, server stores a rounded literal) via the shared relative
+// epsilon; trackIndex (integer track slot) is compared exactly.
+function timingFieldEqual(
+  key: keyof ShadowTiming,
+  actual: number | null | undefined,
+  expected: number,
+): boolean {
+  if (typeof actual === "number" && key !== "trackIndex") {
+    return relEqual(actual, expected);
+  }
+  return actual === expected;
+}
+
 /** Shadow a timing edit. Parity: snapshot start/duration/trackIndex match. */
 export function runShadowTiming(
   session: Composition,
@@ -373,15 +431,14 @@ export function runShadowTiming(
     ];
     for (const [key, actual] of fields) {
       const expected = timing[key];
-      if (expected !== undefined && actual !== expected) {
-        mismatches.push({
-          kind: "value_mismatch",
-          hfId,
-          property: key,
-          expected: String(expected),
-          actual: actual == null ? null : String(actual),
-        });
-      }
+      if (expected === undefined || timingFieldEqual(key, actual, expected)) continue;
+      mismatches.push({
+        kind: "value_mismatch",
+        hfId,
+        property: key,
+        expected: String(expected),
+        actual: actual == null ? null : String(actual),
+      });
     }
     return mismatches;
   });

package/src/utils/sdkShadowGsapFidelity.ts

@@ -16,6 +16,7 @@ import { parseGsapScriptAcorn } from "@hyperframes/core/gsap-parser-acorn";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { STUDIO_SDK_SHADOW_ENABLED } from "../components/editor/manualEditingAvailability";
 import { trackStudioEvent } from "./studioTelemetry";
+import { relEqual } from "./sdkShadowNumeric";
 import type { SdkShadowMismatch, ShadowGsapOp } from "./sdkShadow";
 
 // Marker set must match document.ts extractGsapScript so both pick the same
@@ -24,7 +25,7 @@ function isGsapScriptBody(body: string): boolean {
   return body.includes("gsap") || body.includes("__timelines") || body.includes("ScrollTrigger");
 }
 
-function extractGsapScript(html: string): string | null {
+export function extractGsapScript(html: string): string | null {
   // Close tag is `</script[^>]*>` (not just `</script>`) — HTML5 ignores junk
   // before the `>`, e.g. `</script >` or `</script foo>` (CodeQL js/bad-tag-filter).
   const scripts = html.match(/<script\b[^>]*>([\s\S]*?)<\/script[^>]*>/gi);
@@ -73,17 +74,17 @@ function animByKey(
 // number-vs-string forms. Compare canonically — sort keys, coerce numeric
 // strings — so only real value drift registers, not formatting differences.
 
+// Coerce string operands to numbers, then compare with the shared relative
+// epsilon (relEqual) so float-formatting noise (3.1 vs 3.0999999999999996)
+// isn't flagged as drift while a real 2 vs 1 still is.
 function numericEqual(a: unknown, b: unknown): boolean {
   if (a === b) return true;
   const na = typeof a === "string" ? Number(a) : a;
   const nb = typeof b === "string" ? Number(b) : b;
-  return (
-    typeof na === "number" &&
-    typeof nb === "number" &&
-    !Number.isNaN(na) &&
-    !Number.isNaN(nb) &&
-    na === nb
-  );
+  if (typeof na !== "number" || typeof nb !== "number" || Number.isNaN(na) || Number.isNaN(nb)) {
+    return false;
+  }
+  return relEqual(na, nb);
 }
 
 function canonicalProps(obj: Record<string, unknown> | undefined): string {
@@ -187,27 +188,54 @@ export function resolveGsapFidelityArgs(
   return { before, op: shadowGsapOp, serverScript };
 }
 
-// Resolve a CSS selector to a canonical element id (data-hf-id) using the pre-op
-// document, so tweens that target the same element via different selectors
-// ([data-hf-id="X"] vs .X) match in the fidelity diff. Falls back to the raw
-// selector when it can't resolve (DOMParser unavailable, no match, bad selector).
+// Resolve a CSS selector to a canonical element key using the pre-op document,
+// so tweens that target the same element via different selectors
+// ([data-hf-id="X"] vs .X vs #X) collapse to one key in the fidelity diff.
+//
+// The SDK writer emits [data-hf-id="X"] while the server may emit a class/id
+// selector for the SAME element. Keying both forms to the same node prevents a
+// false present/absent mismatch. Resolution order, for whatever element the
+// selector matches:
+//   1. data-hf-id present  → "hfid:<id>"  (the common, stable case)
+//   2. no data-hf-id       → "node:<n>"   (per-document node index; identical
+//      regardless of which selector form found the node, so .x and [data-hf-id]
+//      pointing at the same attribute-less node still collapse)
+//   3. selector resolves to no node / parse error / no DOM → the raw selector
+//      (last resort; only diverges when the two writers genuinely target
+//      different — or unresolvable — nodes, which is real drift to surface)
+// The "hfid:"/"node:" prefixes are namespaced so a canonical key can never
+// collide with a raw-selector fallback.
 //
 // ponytail: first-match heuristic — querySelector returns the FIRST match, so an
-// ambiguous selector (e.g. .x shared by two elements) may map to a different id
-// than the SDK side's [data-hf-id] target and still flag present/absent. Safe
-// for studio templates (one tween per data-hf-id); upgrade to querySelectorAll +
-// uniqueness check if ambiguous selectors appear.
-function makeSelectorResolver(html: string): (sel: string) => string {
+// ambiguous selector (e.g. .x shared by two elements) may map to a different
+// node than the SDK side's [data-hf-id] target and still flag present/absent.
+// Safe for studio templates (one tween per element); upgrade to querySelectorAll
+// + uniqueness check if ambiguous selectors appear.
+export function makeSelectorResolver(html: string): (sel: string) => string {
   let doc: Document | null = null;
   try {
     doc = new DOMParser().parseFromString(html, "text/html");
   } catch {
     doc = null;
   }
+  // Stable per-node index so an attribute-less element keys identically no
+  // matter which selector form (class vs id vs [data-hf-id]) resolved it.
+  const nodeKeys = new WeakMap<Element, string>();
+  let nextNode = 0;
+  const keyForNode = (el: Element): string => {
+    const hfId = el.getAttribute("data-hf-id");
+    if (hfId != null && hfId !== "") return `hfid:${hfId}`;
+    const existing = nodeKeys.get(el);
+    if (existing != null) return existing;
+    const key = `node:${nextNode++}`;
+    nodeKeys.set(el, key);
+    return key;
+  };
   return (sel) => {
     if (!doc) return sel;
     try {
-      return doc.querySelector(sel)?.getAttribute("data-hf-id") ?? sel;
+      const el = doc.querySelector(sel);
+      return el ? keyForNode(el) : sel;
     } catch {
       return sel;
     }