@hyperframes/studio 0.6.106 → 0.6.107

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;
     }

package/src/utils/sdkShadowGsapKeyframe.test.ts

@@ -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();
+  });
+});