@hyperframes/studio 0.7.21 → 0.7.23

package/src/utils/sdkCutover.ts

@@ -8,115 +8,9 @@ import { trackStudioEvent } from "./studioTelemetry";
 import { markSelfWrite } from "../hooks/sdkSelfWriteRegistry";
 import { patchOpsToSdkEditOps } from "./sdkOpMapping";
 import { recordResolverParity, recordAnimationResolverParity } from "./sdkResolverShadow";
-import { isAllowedHtmlAttribute, isSafeAttributeValue } from "./htmlAttrSafety";
+import { shouldDeclineTextCutoverForTarget, shouldUseSdkCutover } from "./sdkCutoverEligibility";
 
-const CUTOVER_OP_TYPES = new Set<PatchOperation["type"]>([
-  "inline-style",
-  "text-content",
-  "attribute",
-  "html-attribute",
-]);
-
-// Mirrors the SDK's RESERVED_ATTRS (mutate.ts): a bare `attribute` op is
-// force-prefixed `data-`, so e.g. property "end" → "data-end", which the SDK
-// rejects with a throw. Detect that up front and decline the whole batch so it
-// takes the server path cleanly, instead of throwing inside the dispatch and
-// silently falling back per op.
-// ponytail: small mirror of the SDK set; if the SDK adds a reserved attr, a new
-// op for it just reverts to the (working) throw→fallback path until synced.
-const RESERVED_CUTOVER_ATTRS = new Set<string>([
-  "data-hf-id",
-  "data-composition-id",
-  "data-width",
-  "data-height",
-  "data-start",
-  "data-end",
-  "data-track-index",
-  "data-hold-start",
-  "data-hold-end",
-  "data-hold-fill",
-]);
-
-function sdkAttrName(op: PatchOperation): string | null {
-  if (op.type === "attribute") {
-    return op.property.startsWith("data-") ? op.property : `data-${op.property}`;
-  }
-  if (op.type === "html-attribute") return op.property;
-  return null;
-}
-
-function mapsToReservedAttr(op: PatchOperation): boolean {
-  const name = sdkAttrName(op);
-  // Lowercase to match the SDK's validateSetAttribute (it lowercases before the
-  // reserved check), so "DATA-START" is declined up front too; covers both
-  // `attribute` (prefixed) and `html-attribute` (raw) ops.
-  return name !== null && RESERVED_CUTOVER_ATTRS.has(name.toLowerCase());
-}
-
-// ─── html-attribute safety ───────────────────────────────────────────────────
-
-function hasUnsafeHtmlAttributeOp(ops: PatchOperation[]): boolean {
-  return ops.some(
-    (op) =>
-      op.type === "html-attribute" &&
-      (!isAllowedHtmlAttribute(op.property) ||
-        (op.value !== null && !isSafeAttributeValue(op.property, op.value))),
-  );
-}
-
-function hasTextContentOp(ops: PatchOperation[]): boolean {
-  return ops.some((op) => op.type === "text-content");
-}
-
-function targetChildren(target: unknown): unknown[] | null {
-  if (!target || typeof target !== "object" || !("children" in target)) return null;
-  const children = (target as { children?: unknown }).children;
-  return Array.isArray(children) ? children : null;
-}
-
-function elementTag(element: unknown): string | null {
-  if (!element || typeof element !== "object" || !("tag" in element)) return null;
-  const tag = (element as { tag?: unknown }).tag;
-  return typeof tag === "string" ? tag.toLowerCase() : null;
-}
-
-// Tags that are non-HTML namespace elements in a linkedom-parsed HTML body.
-// Mirrors the engine's `isHTMLElementTarget` (model.ts) which uses `instanceof
-// HTMLElement` — that runtime check catches the same set, but we can't use it
-// here because `target` is a plain SDK object, not a DOM Element. If linkedom
-// (or a future parser) surfaces additional foreign-content elements as
-// non-HTMLElement, add them here.
-const NON_HTML_CHILD_TAGS = new Set(["svg", "math"]);
-
-function shouldDeclineTextCutoverForTarget(target: unknown, ops: PatchOperation[]): boolean {
-  if (!hasTextContentOp(ops)) return false;
-  const children = targetChildren(target);
-  if (!children) return false;
-  // Legacy patch-element replaces the whole element for multi-child targets and
-  // for single non-HTML children. The SDK text patch stream stores a scalar
-  // inverse, so those shapes cannot be made both byte-identical and undo-safe
-  // here. Let the server path remain authoritative for them.
-  if (children.length > 1) return true;
-  const tag = elementTag(children[0]);
-  return tag !== null && NON_HTML_CHILD_TAGS.has(tag);
-}
-
-export function shouldUseSdkCutover(
-  flagEnabled: boolean,
-  hasSession: boolean,
-  hfId: string | null | undefined,
-  ops: PatchOperation[],
-): boolean {
-  return (
-    flagEnabled &&
-    hasSession &&
-    !!hfId &&
-    ops.length > 0 &&
-    ops.every((o) => CUTOVER_OP_TYPES.has(o.type)) &&
-    !ops.some(mapsToReservedAttr) &&
-    !hasUnsafeHtmlAttributeOp(ops)
-  );
-}
+export { shouldUseSdkCutover } from "./sdkCutoverEligibility";
 
 export interface CutoverDeps {
   editHistory: {
@@ -271,7 +165,13 @@ export async function sdkTimingPersist(
 ): Promise<boolean> {
   // Resolver tripwire — runs BEFORE the cutover gate (decoupled): records when
   // the SDK can't resolve a target the server timing path is addressing.
-  recordResolverParity(sdkSession, hfId, "setTiming");
+  const timingSrc = deps.readProjectFile;
+  void recordResolverParity(
+    sdkSession,
+    hfId,
+    "setTiming",
+    timingSrc ? () => timingSrc(targetPath) : undefined,
+  );
   // Dark-launch gate: without this, timing cutover runs whenever an SDK session
   // exists (it always does, for shadow/selection) — flipping the flag OFF would
   // NOT disable it. Gate here so flag-off routes back to the legacy server path.
@@ -313,8 +213,15 @@ export function sdkGsapTweenPersist(
   // animationId (animation-resolution parity). Done here, not via
   // dispatchGsapOpAndPersist's resolverTarget, because the gate below returns
   // before that call when cutover is off.
-  if (op.kind === "add") recordResolverParity(sdkSession, op.target, "addGsapTween");
-  else
+  if (op.kind === "add") {
+    const gsapSrc = deps.readProjectFile;
+    void recordResolverParity(
+      sdkSession,
+      op.target,
+      "addGsapTween",
+      gsapSrc ? () => gsapSrc(targetPath) : undefined,
+    );
+  } else
     recordAnimationResolverParity(
       sdkSession,
       op.animationId,
@@ -576,7 +483,9 @@ export async function sdkDeletePersist(
   deps: CutoverDeps,
 ): Promise<boolean> {
   // Resolver tripwire — runs BEFORE the cutover gate (decoupled).
-  recordResolverParity(sdkSession, hfId, "removeElement");
+  void recordResolverParity(sdkSession, hfId, "removeElement", () =>
+    Promise.resolve(originalContent),
+  );
   // Dark-launch gate: flag OFF → legacy server delete path.
   if (!STUDIO_SDK_CUTOVER_ENABLED) return false;
   if (!sdkSession || !sdkSession.getElement(hfId)) return false;

package/src/utils/sdkCutoverEligibility.ts

@@ -0,0 +1,116 @@
+/**
+ * Cutover eligibility checks: whether a batch of patch ops is safe to route
+ * through the SDK cutover path instead of the legacy server path. Split out of
+ * sdkCutover.ts (which hit the packages/studio 600-line filesize cap) — this
+ * block has no dependency on the persist/dispatch functions there.
+ */
+import type { PatchOperation } from "./sourcePatcher";
+import { isAllowedHtmlAttribute, isSafeAttributeValue } from "./htmlAttrSafety";
+
+const CUTOVER_OP_TYPES = new Set<PatchOperation["type"]>([
+  "inline-style",
+  "text-content",
+  "attribute",
+  "html-attribute",
+]);
+
+// Mirrors the SDK's RESERVED_ATTRS (mutate.ts): a bare `attribute` op is
+// force-prefixed `data-`, so e.g. property "end" → "data-end", which the SDK
+// rejects with a throw. Detect that up front and decline the whole batch so it
+// takes the server path cleanly, instead of throwing inside the dispatch and
+// silently falling back per op.
+// ponytail: small mirror of the SDK set; if the SDK adds a reserved attr, a new
+// op for it just reverts to the (working) throw→fallback path until synced.
+const RESERVED_CUTOVER_ATTRS = new Set<string>([
+  "data-hf-id",
+  "data-composition-id",
+  "data-width",
+  "data-height",
+  "data-start",
+  "data-end",
+  "data-track-index",
+  "data-hold-start",
+  "data-hold-end",
+  "data-hold-fill",
+]);
+
+function sdkAttrName(op: PatchOperation): string | null {
+  if (op.type === "attribute") {
+    return op.property.startsWith("data-") ? op.property : `data-${op.property}`;
+  }
+  if (op.type === "html-attribute") return op.property;
+  return null;
+}
+
+function mapsToReservedAttr(op: PatchOperation): boolean {
+  const name = sdkAttrName(op);
+  // Lowercase to match the SDK's validateSetAttribute (it lowercases before the
+  // reserved check), so "DATA-START" is declined up front too; covers both
+  // `attribute` (prefixed) and `html-attribute` (raw) ops.
+  return name !== null && RESERVED_CUTOVER_ATTRS.has(name.toLowerCase());
+}
+
+// ─── html-attribute safety ───────────────────────────────────────────────────
+
+function hasUnsafeHtmlAttributeOp(ops: PatchOperation[]): boolean {
+  return ops.some(
+    (op) =>
+      op.type === "html-attribute" &&
+      (!isAllowedHtmlAttribute(op.property) ||
+        (op.value !== null && !isSafeAttributeValue(op.property, op.value))),
+  );
+}
+
+function hasTextContentOp(ops: PatchOperation[]): boolean {
+  return ops.some((op) => op.type === "text-content");
+}
+
+function targetChildren(target: unknown): unknown[] | null {
+  if (!target || typeof target !== "object" || !("children" in target)) return null;
+  const children = (target as { children?: unknown }).children;
+  return Array.isArray(children) ? children : null;
+}
+
+function elementTag(element: unknown): string | null {
+  if (!element || typeof element !== "object" || !("tag" in element)) return null;
+  const tag = (element as { tag?: unknown }).tag;
+  return typeof tag === "string" ? tag.toLowerCase() : null;
+}
+
+// Tags that are non-HTML namespace elements in a linkedom-parsed HTML body.
+// Mirrors the engine's `isHTMLElementTarget` (model.ts) which uses `instanceof
+// HTMLElement` — that runtime check catches the same set, but we can't use it
+// here because `target` is a plain SDK object, not a DOM Element. If linkedom
+// (or a future parser) surfaces additional foreign-content elements as
+// non-HTMLElement, add them here.
+const NON_HTML_CHILD_TAGS = new Set(["svg", "math"]);
+
+export function shouldDeclineTextCutoverForTarget(target: unknown, ops: PatchOperation[]): boolean {
+  if (!hasTextContentOp(ops)) return false;
+  const children = targetChildren(target);
+  if (!children) return false;
+  // Legacy patch-element replaces the whole element for multi-child targets and
+  // for single non-HTML children. The SDK text patch stream stores a scalar
+  // inverse, so those shapes cannot be made both byte-identical and undo-safe
+  // here. Let the server path remain authoritative for them.
+  if (children.length > 1) return true;
+  const tag = elementTag(children[0]);
+  return tag !== null && NON_HTML_CHILD_TAGS.has(tag);
+}
+
+export function shouldUseSdkCutover(
+  flagEnabled: boolean,
+  hasSession: boolean,
+  hfId: string | null | undefined,
+  ops: PatchOperation[],
+): boolean {
+  return (
+    flagEnabled &&
+    hasSession &&
+    !!hfId &&
+    ops.length > 0 &&
+    ops.every((o) => CUTOVER_OP_TYPES.has(o.type)) &&
+    !ops.some(mapsToReservedAttr) &&
+    !hasUnsafeHtmlAttributeOp(ops)
+  );
+}

package/src/utils/sdkResolverShadow.test.ts

@@ -226,6 +226,53 @@ describe("C. Resolver-parity detection", () => {
     });
   });
 
+  it("C8 runtime-node filter: hfId absent from source → suppressed (not a resolver bug)", () => {
+    // The studio resolved a live-DOM element to an hf-id that the SDK session
+    // doesn't contain AND that never appears in the on-disk source — it's a
+    // node a composition <script> created at runtime (e.g. caption spans). Not
+    // a resolver divergence; suppress.
+    const session = { getElement: () => null, getElements: () => [] } as unknown as Parameters<
+      typeof sdkResolverShadowCheck
+    >[0];
+    const source = `<div data-hf-id="hf-static">no runtime id here</div>`;
+    const mismatches = sdkResolverShadowCheck(
+      session,
+      "hf-runtimeonly",
+      [{ type: "inline-style", property: "color", value: "red" }],
+      source,
+    );
+    expect(mismatches).toHaveLength(0);
+  });
+
+  it("C8 runtime-node filter: hfId PRESENT in source but missing from session → still flagged (real bug)", () => {
+    const session = { getElement: () => null, getElements: () => [] } as unknown as Parameters<
+      typeof sdkResolverShadowCheck
+    >[0];
+    const source = `<div data-hf-id="hf-realbug">in source, not in SDK session</div>`;
+    const mismatches = sdkResolverShadowCheck(
+      session,
+      "hf-realbug",
+      [{ type: "inline-style", property: "color", value: "red" }],
+      source,
+    );
+    expect(mismatches).toHaveLength(1);
+    expect(mismatches[0]?.kind).toBe("element_not_found");
+  });
+
+  it("C8 sourceHfIdCount: emitted element_not_found carries source occurrence count", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = { getElement: () => null, getElements: () => [] } as unknown as Composition;
+    // id present twice in source (duplicate-id ambiguity) but absent from session
+    const source = `<div data-hf-id="hf-dup">a</div><div data-hf-id="hf-dup">b</div>`;
+    runResolverShadow(
+      session,
+      "hf-dup",
+      [{ type: "inline-style", property: "color", value: "red" }],
+      source,
+    );
+    expect(lastShadow()?.sourceHfIdCount).toBe(2);
+  });
+
   it("C10: unmappable op type produces no mismatch (excluded, not flagged)", async () => {
     const session = await openComposition(BASE_HTML);
     // "unknown-op" is not in MAPPED_OP_TYPES, so it must be silently excluded.
@@ -298,7 +345,7 @@ describe("F. recordResolverParity", () => {
   it("emits element_not_found when the SDK cannot resolve the target", async () => {
     mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
     const session = await openComposition(BASE_HTML);
-    recordResolverParity(session, "hf-missing", "setTiming");
+    await recordResolverParity(session, "hf-missing", "setTiming");
     const ev = lastShadow();
     expect(ev?.mismatchCount).toBe(1);
     expect(ev?.opLabel).toBe("setTiming");
@@ -308,7 +355,7 @@ describe("F. recordResolverParity", () => {
   it("emits nothing when the target resolves (parity)", async () => {
     mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
     const session = await openComposition(BASE_HTML);
-    recordResolverParity(session, "hf-box", "removeElement");
+    await recordResolverParity(session, "hf-box", "removeElement");
     expect(trackedEvents.filter((e) => e.event === "sdk_resolver_shadow")).toHaveLength(0);
   });
 
@@ -316,7 +363,7 @@ describe("F. recordResolverParity", () => {
     mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = false;
     const session = await openComposition(BASE_HTML);
     const spy = vi.spyOn(session, "getElement");
-    recordResolverParity(session, "hf-missing", "setTiming");
+    await recordResolverParity(session, "hf-missing", "setTiming");
     expect(trackedEvents).toHaveLength(0);
     expect(spy).not.toHaveBeenCalled();
   });
@@ -324,9 +371,58 @@ describe("F. recordResolverParity", () => {
   it("never mutates the session (read-only resolver check)", async () => {
     mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
     const session = await openComposition(BASE_HTML);
-    recordResolverParity(session, "hf-box", "setTiming");
+    await recordResolverParity(session, "hf-box", "setTiming");
     expect(session.getElement("hf-box")?.inlineStyles.color).toBe("red"); // unchanged
   });
+
+  it("suppresses the emit when the hfId is absent from source (runtime node)", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(BASE_HTML);
+    await recordResolverParity(session, "hf-runtime", "setTiming", () =>
+      Promise.resolve('<div data-hf-id="hf-other"></div>'),
+    );
+    expect(trackedEvents.filter((e) => e.event === "sdk_resolver_shadow")).toHaveLength(0);
+  });
+
+  it("emits with sourceHfIdCount=1 when the hfId IS in source but missing from the session", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(BASE_HTML);
+    await recordResolverParity(session, "hf-ghost", "setTiming", () =>
+      Promise.resolve('<div data-hf-id="hf-ghost"></div>'),
+    );
+    const ev = lastShadow();
+    expect(ev?.mismatchCount).toBe(1);
+    expect(ev?.sourceHfIdCount).toBe(1);
+  });
+
+  it("reports sourceHfIdCount=2 for a duplicate-id source (ambiguity)", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(BASE_HTML);
+    await recordResolverParity(session, "hf-dup", "setTiming", () =>
+      Promise.resolve('<a data-hf-id="hf-dup"></a><b data-hf-id="hf-dup"></b>'),
+    );
+    expect(lastShadow()?.sourceHfIdCount).toBe(2);
+  });
+
+  it("emits without sourceHfIdCount when no reader is supplied (status quo)", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(BASE_HTML);
+    await recordResolverParity(session, "hf-missing", "setTiming");
+    const ev = lastShadow();
+    expect(ev?.mismatchCount).toBe(1);
+    expect(ev?.sourceHfIdCount).toBeUndefined();
+  });
+
+  it("fails open: a readSource error still emits (no suppression)", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(BASE_HTML);
+    await recordResolverParity(session, "hf-missing", "setTiming", () =>
+      Promise.reject(new Error("read failed")),
+    );
+    const ev = lastShadow();
+    expect(ev?.mismatchCount).toBe(1);
+    expect(ev?.sourceHfIdCount).toBeUndefined();
+  });
 });
 
 // ─── G. recordAnimationResolverParity (GSAP animationId ops) ──────────────────
@@ -395,7 +491,7 @@ describe("H. inlined sub-composition leaf", () => {
   it("recordResolverParity emits NOTHING for a bare leaf inside a sub-comp", async () => {
     mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
     const session = await openComposition(INLINED_HTML);
-    recordResolverParity(session, "hf-leaf", "setTiming");
+    await recordResolverParity(session, "hf-leaf", "setTiming");
     expect(trackedEvents.filter((e) => e.event === "sdk_resolver_shadow")).toHaveLength(0);
   });
 

package/src/utils/sdkResolverShadow.ts

@@ -82,6 +82,14 @@ type AttrMap = Record<string, string | null>;
  * Mirror resolveScoped here: exact scoped-path match, then canonical bare
  * match, then first bare match — the resolvability dispatch actually has.
  */
+// Count static `data-hf-id="<id>"` occurrences (both quote styles) in source.
+// Substring split, not regex — no escaping, and the id never contains a quote.
+function countHfIdInSource(source: string, id: string): number {
+  return (
+    source.split(`data-hf-id="${id}"`).length - 1 + (source.split(`data-hf-id='${id}'`).length - 1)
+  );
+}
+
 function resolveSnapshot(session: Composition, id: string): FlatEl | null {
   const els = session.getElements();
   const exact = els.find((el) => el.scopedId === id);
@@ -164,8 +172,20 @@ export function sdkResolverShadowCheck(
   session: Composition,
   hfId: string,
   ops: PatchOperation[],
+  sourceContent?: string,
 ): SdkResolverMismatch[] {
   if (!resolveSnapshot(session, hfId)) {
+    // Runtime-node filter: an hf-id absent from the on-disk source the SDK
+    // parsed was never in the static DOM — it belongs to an element a
+    // composition <script> creates at runtime (e.g. caption word/group spans),
+    // which the SDK session cannot model by design. That is NOT a resolver bug,
+    // so suppress it. An hf-id PRESENT in source but missing from the session IS
+    // a genuine resolver divergence (the v0.6.110 class) — keep emitting that.
+    // ponytail: substring match; biases toward keeping signal on a loose hit.
+    if (sourceContent !== undefined && !sourceContent.includes(hfId)) return [];
+    // Loose match here vs. countHfIdInSource's strict data-hf-id="..." match in the
+    // caller (runResolverShadow) means an emitted event can carry sourceHfIdCount: 0 —
+    // see the comment on that field in runResolverShadow for what 0 means in that case.
     return [{ kind: "element_not_found", hfId }];
   }
 
@@ -241,17 +261,34 @@ export function runResolverShadow(
   session: Composition,
   hfId: string | null | undefined,
   ops: PatchOperation[],
+  sourceContent?: string,
 ): void {
   if (!STUDIO_SDK_RESOLVER_SHADOW_ENABLED) return;
   if (!hfId) return;
   try {
-    const mismatches = sdkResolverShadowCheck(session, hfId, ops);
+    const mismatches = sdkResolverShadowCheck(session, hfId, ops, sourceContent);
     // Emit only on divergence — parity is silent, matching recordResolverParity
     // and recordAnimationResolverParity. Otherwise this fires a PostHog event on
     // every style/text/attr edit (the editor's chattiest path) at default-ON.
     if (mismatches.length === 0) return;
+    const isElementNotFound = mismatches.some((m) => m.kind === "element_not_found");
     trackStudioEvent("sdk_resolver_shadow", {
       hfId,
+      // sessionElementCount > 0 + element_not_found = runtime-only element;
+      // sessionElementCount === 0 = session is empty/broken (actionable).
+      sessionElementCount: session.getElements().length,
+      // Count of data-hf-id="<id>" occurrences in source for an emitted
+      // element_not_found. >1 = duplicate ids → resolver picked the wrong
+      // instance; =1 = single static node the SDK parse dropped (foreign-content
+      // exclusion / sub-comp inlining gap); =0 = the runtime-node filter above
+      // uses a loose substring match (biased toward keeping signal) while this
+      // count uses a strict attribute match — an emitted event with count 0
+      // means hfId appeared in source as plain text (e.g. a class name, comment,
+      // or script string) but never as a data-hf-id attribute. Treat 0 as "not
+      // a genuine attribute occurrence," not as a contradiction.
+      ...(isElementNotFound && sourceContent !== undefined
+        ? { sourceHfIdCount: countHfIdInSource(sourceContent, hfId) }
+        : {}),
       mismatchCount: mismatches.length,
       mismatches: JSON.stringify(redactMismatches(mismatches)),
     });
@@ -270,18 +307,42 @@ export function runResolverShadow(
  *
  * No-op when the shadow flag is off; never throws; never mutates the session.
  */
-export function recordResolverParity(
+export async function recordResolverParity(
   session: Composition | null | undefined,
   hfId: string | null | undefined,
   opLabel: string,
-): void {
+  readSource?: () => Promise<string | undefined>,
+): Promise<void> {
   if (!STUDIO_SDK_RESOLVER_SHADOW_ENABLED) return;
   if (!session || !hfId) return;
   try {
     if (resolveSnapshot(session, hfId)) return; // resolves — parity, nothing to record
+    // Capture BEFORE any await: this call is fire-and-forget (`void recordResolverParity(...)`)
+    // and the caller runs its own session mutation synchronously right after this call
+    // returns. getElements() caches and that cache is invalidated on dispatch, so reading
+    // the count after an await would silently reflect POST-edit state, not the pre-edit
+    // state this field exists to diagnose.
+    const sessionElementCount = session.getElements().length;
+    // Cheap check passed above, so the source read only runs on a real divergence.
+    let source: string | undefined;
+    if (readSource) {
+      try {
+        source = await readSource();
+      } catch {
+        source = undefined; // fail-open: a read error must not drop a real divergence
+      }
+    }
+    // Runtime-generated node the static parse can't model — suppress (mirrors the dom-edit path).
+    if (source !== undefined && !source.includes(hfId)) return;
     trackStudioEvent("sdk_resolver_shadow", {
       hfId,
       opLabel,
+      sessionElementCount,
+      // sourceHfIdCount: strict data-hf-id="..." attribute count. Can be 0 even
+      // on an emitted (non-suppressed) event — the suppression check above is a
+      // loose substring match (biased toward keeping signal); see the longer
+      // comment on this field in runResolverShadow for the full explanation.
+      ...(source !== undefined ? { sourceHfIdCount: countHfIdInSource(source, hfId) } : {}),
       mismatchCount: 1,
       mismatches: JSON.stringify([
         { kind: "element_not_found", hfId } satisfies SdkResolverMismatch,
@@ -310,11 +371,13 @@ export function recordAnimationResolverParity(
   if (!STUDIO_SDK_RESOLVER_SHADOW_ENABLED) return;
   if (!session || !animationId) return;
   try {
-    const resolves = session.getElements().some((el) => el.animationIds.includes(animationId));
+    const elements = session.getElements();
+    const resolves = elements.some((el) => el.animationIds.includes(animationId));
     if (resolves) return; // SDK locates the animation — parity
     trackStudioEvent("sdk_resolver_shadow", {
       animationId,
       opLabel,
+      sessionElementCount: elements.length,
       mismatchCount: 1,
       mismatches: JSON.stringify([
         { kind: "animation_not_found", animationId } satisfies SdkResolverMismatch,

package/src/utils/studioTelemetry.ts

@@ -1,4 +1,4 @@
-import { generateId } from "./generateId";
+import { resolveStudioDistinctId } from "../telemetry/distinctId";
 
 // PostHog public ingest key — write-only, safe to ship in the client bundle
 const POSTHOG_API_KEY = "phc_zjjbX0PnWxERXrMHhkEJWj9A9BhGVLRReICgsfTMmpx";
@@ -18,26 +18,12 @@ interface QueuedEvent {
 
 let queue: QueuedEvent[] = [];
 let flushTimer: ReturnType<typeof setInterval> | null = null;
-let distinctId: string | null = null;
 
+// Delegates to the single source of truth (telemetry/distinctId.ts) so `studio:*`
+// events share one id with `studio_*` / render events, and adopt the CLI's
+// distinct_id when the CLI launched Studio.
 function getDistinctId(): string {
-  if (distinctId) return distinctId;
-  try {
-    const stored = localStorage.getItem("hf-studio-anon-id");
-    if (stored) {
-      distinctId = stored;
-      return stored;
-    }
-  } catch {
-    // localStorage may be unavailable
-  }
-  distinctId = generateId();
-  try {
-    localStorage.setItem("hf-studio-anon-id", distinctId);
-  } catch {
-    // best-effort persistence
-  }
-  return distinctId;
+  return resolveStudioDistinctId();
 }
 
 function isEnabled(): boolean {