@hyperframes/studio 0.6.106 → 0.6.108

package/src/styles/studio.css

@@ -20,6 +20,87 @@ body {
   overflow: hidden;
 }
 
+.hf-color-grading-number::-webkit-outer-spin-button,
+.hf-color-grading-number::-webkit-inner-spin-button {
+  margin: 0;
+  appearance: none;
+}
+
+.hf-color-grading-number {
+  -moz-appearance: textfield;
+  appearance: textfield;
+}
+
+.hf-color-grading-range {
+  height: 1.5rem;
+  cursor: default;
+  -webkit-appearance: none;
+  appearance: none;
+  background: transparent;
+}
+
+.hf-color-grading-range:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+.hf-color-grading-range::-webkit-slider-runnable-track {
+  height: 1.25rem;
+  border: 0;
+  background: transparent;
+}
+
+.hf-color-grading-range::-webkit-slider-thumb {
+  width: 0.625rem;
+  height: 1rem;
+  margin-top: 0.125rem;
+  border: 0;
+  border-radius: 999px;
+  -webkit-appearance: none;
+  appearance: none;
+  background: #ffffff;
+  box-shadow:
+    0 0 0 2px #0c0c0e,
+    0 1px 4px rgba(0, 0, 0, 0.55);
+  cursor: default;
+}
+
+.hf-color-grading-range::-moz-range-track {
+  height: 1.25rem;
+  border: 0;
+  background: transparent;
+}
+
+.hf-color-grading-range::-moz-range-thumb {
+  width: 0.625rem;
+  height: 1rem;
+  border: 0;
+  border-radius: 999px;
+  background: #ffffff;
+  box-shadow:
+    0 0 0 2px #0c0c0e,
+    0 1px 4px rgba(0, 0, 0, 0.55);
+  cursor: default;
+}
+
+.hf-color-grading-range:focus-visible {
+  outline: none;
+}
+
+.hf-color-grading-range:focus-visible::-webkit-slider-thumb {
+  box-shadow:
+    0 0 0 2px #0c0c0e,
+    0 0 0 4px rgba(60, 230, 172, 0.22),
+    0 1px 4px rgba(0, 0, 0, 0.55);
+}
+
+.hf-color-grading-range:focus-visible::-moz-range-thumb {
+  box-shadow:
+    0 0 0 2px #0c0c0e,
+    0 0 0 4px rgba(60, 230, 172, 0.22),
+    0 1px 4px rgba(0, 0, 0, 0.55);
+}
+
 #root {
   width: 100vw;
   /*

package/src/utils/mediaTypes.ts

@@ -2,6 +2,7 @@ export const IMAGE_EXT = /\.(jpg|jpeg|png|gif|webp|svg|ico)$/i;
 export const VIDEO_EXT = /\.(mp4|webm|mov)$/i;
 export const AUDIO_EXT = /\.(mp3|wav|ogg|m4a|aac)$/i;
 export const FONT_EXT = /\.(woff|woff2|ttf|ttc|otf|eot)$/i;
+export const LUT_EXT = /\.cube$/i;
 export const MEDIA_EXT = /\.(mp4|webm|mov|mp3|wav|ogg|m4a|aac|jpg|jpeg|png|gif|webp|svg|ico)$/i;
 
 export function isMediaFile(path: string): boolean {

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