@hyperframes/studio 0.7.22 → 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

@@ -345,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");
@@ -355,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);
   });
 
@@ -363,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();
   });
@@ -371,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) ──────────────────
@@ -442,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

@@ -183,6 +183,9 @@ export function sdkResolverShadowCheck(
     // 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 }];
   }
 
@@ -275,10 +278,14 @@ export function runResolverShadow(
       // 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 (the runtime-node filter already dropped absent-from-
-      // source ids, so an emitted one is in source ≥1×). >1 = duplicate ids →
-      // resolver picked the wrong instance; =1 = single static node the SDK
-      // parse dropped (foreign-content exclusion / sub-comp inlining gap).
+      // 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) }
         : {}),
@@ -300,19 +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: session.getElements().length,
+      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,

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 {