@hyperframes/studio 0.8.48 → 0.8.50

package/src/shims/canvasBrowserStub.js

@@ -0,0 +1,50 @@
+/**
+ * Browser stub for the Node-only `canvas` package.
+ *
+ * linkedom's `HTMLCanvasElement` constructor calls `createCanvas(300, 150)`
+ * (300x150 being the HTML canvas default size). linkedom guards that import in
+ * a try/catch: the try requires the native `canvas` package, and the catch
+ * falls back to linkedom's own bundled canvas shim.
+ *
+ * That guard only works with a *runtime* require. Vite resolves the specifier
+ * statically, so the bundled form is a plain assignment that cannot throw, the
+ * catch never runs, and `createCanvas` lands `undefined`. Parsing any `<canvas>`
+ * tag then throws inside `openComposition`, Studio loses its SDK session for the
+ * whole composition, and every edit silently falls back to the server path — the
+ * resolver shadow does not run either, so it was invisible until
+ * `studio:sdk_session_unavailable` shipped in v0.8.47.
+ *
+ * Production telemetry over the 72h after the flip: 1065 of 1544 session-open
+ * failures were this crash, across a large share of 197 users. Canvas is common
+ * in compositions (Three.js, shaders, particle effects, charts).
+ *
+ * Aliasing `canvas` to this file makes the browser build resolve to a
+ * measurement-only canvas, which is all linkedom's static parse needs — nothing
+ * in the SDK rasterizes through it. It mirrors linkedom's own
+ * `commonjs/canvas-shim.cjs`, reimplemented here because linkedom's `exports`
+ * map does not expose that file.
+ */
+
+class BrowserCanvasStub {
+  constructor(width, height) {
+    this.width = width;
+    this.height = height;
+  }
+  /** linkedom only ever needs the element to exist; nothing draws through it. */
+  getContext() {
+    return null;
+  }
+  toDataURL() {
+    return "";
+  }
+}
+
+export function createCanvas(width, height) {
+  return new BrowserCanvasStub(width, height);
+}
+
+// linkedom consumes this as a DEFAULT import — `import Canvas from
+// '../../commonjs/canvas.cjs'` then `const {createCanvas} = Canvas` — so the
+// default export is the load-bearing one; the named export above is interop
+// belt-and-braces.
+export default { createCanvas };

package/src/utils/blockInstaller.test.ts

@@ -63,5 +63,9 @@ describe("addBlockToProject", () => {
     expect(source).toContain('data-start="2.5"');
     expect(source).toContain('data-duration="4.25"');
     expect(source).toContain('data-track-index="3"');
+    // hostKey addresses the new element the same way the timeline selects
+    // clips (sourceFile#domId), so the caller can select and reveal it.
+    expect(result?.hostKey).toBe("compositions/scene.html#camcorder-hud");
+    expect(source).toContain('id="camcorder-hud"');
   });
 });

package/src/utils/blockInstaller.ts

@@ -11,6 +11,7 @@ import { formatTimelineAttributeNumber } from "../player/components/timelineEdit
 import { saveProjectFilesWithHistory } from "./studioFileHistory";
 import type { EditHistoryKind } from "./editHistory";
 import { extendRootDurationInSource } from "./rootDuration";
+import { deriveTimelineStoreKeyForDomId } from "../player/lib/timelineElementHelpers";
 
 function getMaxZIndexFromIframe(iframe: HTMLIFrameElement | null): number {
   try {
@@ -174,7 +175,7 @@ function buildSubCompositionHtml({
 
 export async function addBlockToProject(
   opts: AddBlockOptions,
-): Promise<{ block: RegistryItem; compositionPath: string } | null> {
+): Promise<{ block: RegistryItem; compositionPath: string; hostKey: string } | null> {
   const {
     projectId,
     blockName,
@@ -213,8 +214,9 @@ export async function addBlockToProject(
       currentTime: opts.currentTime ?? 0,
     });
     const { width, height } = resolveTimelineAssetCompositionSize(originalContent);
+    const hostId = buildUniqueCompositionId(block.name, collectHtmlIds(originalContent));
     const subComposition = buildSubCompositionHtml({
-      id: buildUniqueCompositionId(block.name, collectHtmlIds(originalContent)),
+      id: hostId,
       compositionFile,
       start,
       duration,
@@ -242,7 +244,11 @@ export async function addBlockToProject(
     await refreshFileTree();
     reloadPreview();
 
-    return { block, compositionPath: compositionFile };
+    return {
+      block,
+      compositionPath: compositionFile,
+      hostKey: deriveTimelineStoreKeyForDomId(hostId, targetPath),
+    };
   } catch (error) {
     const message = error instanceof Error ? error.message : "Failed to add block";
     showToast(message);

package/src/utils/clipboardPayload.test.ts

@@ -33,10 +33,41 @@ describe("deduplicateIds", () => {
 });
 
 describe("serializeClipboardPayload / deserializeClipboardPayload", () => {
-  it("round-trips a timeline clip payload", () => {
+  it("round-trips a single-clip timeline payload", () => {
     const payload: ClipboardPayload = {
       kind: "timeline-clip",
-      html: '<img id="photo" src="a.png" data-start="1" data-duration="3" />',
+      clips: [
+        {
+          html: '<img id="photo" src="a.png" data-start="1" data-duration="3" />',
+          start: 1,
+          duration: 3,
+          track: 0,
+        },
+      ],
+      sourceFile: "index.html",
+    };
+    const json = serializeClipboardPayload(payload);
+    const parsed = deserializeClipboardPayload(json);
+    expect(parsed).toEqual(payload);
+  });
+
+  it("round-trips a group timeline-clip payload", () => {
+    const payload: ClipboardPayload = {
+      kind: "timeline-clip",
+      clips: [
+        {
+          html: '<img id="a" data-start="1" data-duration="0.5" />',
+          start: 1,
+          duration: 0.5,
+          track: 0,
+        },
+        {
+          html: '<img id="b" data-start="2" data-duration="0.5" />',
+          start: 2,
+          duration: 0.5,
+          track: 1,
+        },
+      ],
       sourceFile: "index.html",
     };
     const json = serializeClipboardPayload(payload);
@@ -59,4 +90,13 @@ describe("serializeClipboardPayload / deserializeClipboardPayload", () => {
     expect(deserializeClipboardPayload("not json")).toBeNull();
     expect(deserializeClipboardPayload('{"kind":"unknown"}')).toBeNull();
   });
+
+  it("returns null for a timeline-clip payload with no clips", () => {
+    const json = serializeClipboardPayload({
+      kind: "timeline-clip",
+      clips: [],
+      sourceFile: "index.html",
+    });
+    expect(deserializeClipboardPayload(json)).toBeNull();
+  });
 });

package/src/utils/clipboardPayload.ts

@@ -2,35 +2,35 @@ import { COMPOSITION_ROOT_OPEN_TAG_RE } from "./compositionPatterns";
 
 const CLIPBOARD_MARKER = "hyperframes-clipboard:v1";
 
-export interface ClipboardPayload {
-  kind: "timeline-clip" | "dom-element";
+/** One clip's copied markup plus the original placement needed to preserve
+ *  relative offsets and tracks across a group paste. */
+export interface TimelineClipboardClip {
   html: string;
-  sourceFile: string;
-  originSelector?: string;
-  originSelectorIndex?: number;
+  start: number;
+  duration: number;
+  track: number;
 }
 
-interface SerializedPayload {
-  _marker: string;
-  kind: "timeline-clip" | "dom-element";
-  html: string;
-  sourceFile: string;
-  originSelector?: string;
-  originSelectorIndex?: number;
-}
+export type ClipboardPayload =
+  | { kind: "timeline-clip"; clips: TimelineClipboardClip[]; sourceFile: string }
+  | {
+      kind: "dom-element";
+      html: string;
+      sourceFile: string;
+      originSelector?: string;
+      originSelectorIndex?: number;
+    };
+
+type SerializedPayload = { _marker: string } & ClipboardPayload;
 
 export function serializeClipboardPayload(payload: ClipboardPayload): string {
-  const data: SerializedPayload = {
-    _marker: CLIPBOARD_MARKER,
-    kind: payload.kind,
-    html: payload.html,
-    sourceFile: payload.sourceFile,
-    originSelector: payload.originSelector,
-    originSelectorIndex: payload.originSelectorIndex,
-  };
+  const data: SerializedPayload = { _marker: CLIPBOARD_MARKER, ...payload };
   return JSON.stringify(data);
 }
 
+// Each branch validates one wire shape at the trust boundary; splitting further
+// would fragment one parse into partial validators with no independent reuse.
+// fallow-ignore-next-line complexity
 export function deserializeClipboardPayload(json: string): ClipboardPayload | null {
   let parsed: unknown;
   try {
@@ -41,16 +41,35 @@ export function deserializeClipboardPayload(json: string): ClipboardPayload | nu
   if (!parsed || typeof parsed !== "object") return null;
   const obj = parsed as Record<string, unknown>;
   if (obj._marker !== CLIPBOARD_MARKER) return null;
-  if (obj.kind !== "timeline-clip" && obj.kind !== "dom-element") return null;
-  if (typeof obj.html !== "string" || typeof obj.sourceFile !== "string") return null;
-  return {
-    kind: obj.kind,
-    html: obj.html,
-    sourceFile: obj.sourceFile,
-    originSelector: typeof obj.originSelector === "string" ? obj.originSelector : undefined,
-    originSelectorIndex:
-      typeof obj.originSelectorIndex === "number" ? obj.originSelectorIndex : undefined,
-  };
+  if (typeof obj.sourceFile !== "string") return null;
+  if (obj.kind === "timeline-clip") {
+    if (!Array.isArray(obj.clips)) return null;
+    const clips = obj.clips.filter((c): c is TimelineClipboardClip => {
+      const clip = c as Partial<TimelineClipboardClip> | null;
+      return (
+        !!clip &&
+        typeof clip === "object" &&
+        typeof clip.html === "string" &&
+        typeof clip.start === "number" &&
+        typeof clip.duration === "number" &&
+        typeof clip.track === "number"
+      );
+    });
+    if (clips.length === 0) return null;
+    return { kind: "timeline-clip", clips, sourceFile: obj.sourceFile };
+  }
+  if (obj.kind === "dom-element") {
+    if (typeof obj.html !== "string") return null;
+    return {
+      kind: "dom-element",
+      html: obj.html,
+      sourceFile: obj.sourceFile,
+      originSelector: typeof obj.originSelector === "string" ? obj.originSelector : undefined,
+      originSelectorIndex:
+        typeof obj.originSelectorIndex === "number" ? obj.originSelectorIndex : undefined,
+    };
+  }
+  return null;
 }
 
 /**
@@ -59,6 +78,7 @@ export function deserializeClipboardPayload(json: string): ClipboardPayload | nu
  * the composition root if the selector doesn't match — so paste never silently
  * drops the content.
  */
+// fallow-ignore-next-line complexity
 export function insertAsSibling(
   source: string,
   newHtml: string,
@@ -110,6 +130,7 @@ export function insertAsSibling(
   return source + newHtml;
 }
 
+// fallow-ignore-next-line complexity
 function findClosingTagPosition(html: string, openTagStart: number): number {
   // Find the end of the opening tag
   const openTagEnd = html.indexOf(">", openTagStart);
@@ -156,9 +177,13 @@ function findClosingTagPosition(html: string, openTagStart: number): number {
   return -1;
 }
 
+/** An `id="..."` attribute, not `data-id="..."` or similar — only matches
+ *  when preceded by whitespace, the way every generated attribute is. */
+export const ID_ATTR_RE = /(?<=\s)id="([^"]+)"/;
+
 export function deduplicateIds(html: string, existingIds: string[]): string {
   const existingSet = new Set(existingIds);
-  return html.replace(/(?<=\s)id="([^"]+)"/g, (full, id: string) => {
+  return html.replace(new RegExp(ID_ATTR_RE.source, "g"), (full, id: string) => {
     if (!existingSet.has(id)) return full;
     let counter = 2;
     while (existingSet.has(`${id}-${counter}`)) counter++;

package/src/utils/previewSafeMargins.test.ts

@@ -0,0 +1,34 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  ACTION_SAFE_PERCENT,
+  SAFE_BOX_PERCENTS,
+  TITLE_SAFE_PERCENT,
+  safeBoxInsetPercent,
+} from "./previewSafeMargins";
+
+const SKILL_PATH = join(import.meta.dirname, "../../../../skills/hyperframes-studio/SKILL.md");
+
+describe("safe boxes", () => {
+  it("are the 90% and 80% boxes, inset 5% and 10% from every edge", () => {
+    expect(SAFE_BOX_PERCENTS).toEqual([90, 80]);
+    expect(SAFE_BOX_PERCENTS.map(safeBoxInsetPercent)).toEqual([5, 10]);
+  });
+});
+
+// Skipped until the hyperframes-studio skill exists on this branch.
+describe.runIf(existsSync(SKILL_PATH))("hyperframes-studio skill matches the constants", () => {
+  it("has a safe-margins line naming both percentages", () => {
+    const skill = readFileSync(SKILL_PATH, "utf8");
+    const line = skill
+      .split("\n")
+      .find(
+        (l) =>
+          /\bsafe margins?\b/i.test(l) &&
+          l.includes(`${ACTION_SAFE_PERCENT}%`) &&
+          l.includes(`${TITLE_SAFE_PERCENT}%`),
+      );
+    expect(line).toBeDefined();
+  });
+});

package/src/utils/previewSafeMargins.ts

@@ -0,0 +1,10 @@
+// Adobe Premiere default: action-safe and title-safe margins are 10% and 20% total (5% and 10% per edge).
+export const ACTION_SAFE_PERCENT = 90;
+export const TITLE_SAFE_PERCENT = 80;
+
+export const SAFE_BOX_PERCENTS = [ACTION_SAFE_PERCENT, TITLE_SAFE_PERCENT] as const;
+
+/** Inset from each frame edge, as a percent of the frame. */
+export function safeBoxInsetPercent(boxPercent: number): number {
+  return (100 - boxPercent) / 2;
+}

package/src/utils/razorSplitTransaction.test.ts

@@ -10,7 +10,6 @@ const element = (over: Partial<TimelineElement> = {}): TimelineElement => ({
   start: 0,
   duration: 4,
   track: 0,
-  timingSource: "authored",
   sourceFile: "index.html",
   ...over,
 });

package/src/utils/retryBudget.ts

@@ -0,0 +1,20 @@
+import type { MutableRefObject } from "react";
+
+export interface RetryBudgetState<K> {
+  id: K;
+  count: number;
+}
+
+// A target still resolving (a just-dropped/pasted/duplicated element, or a
+// preview still reloading) heals within a few retries; one that never will
+// would otherwise retry forever. A new id resets the count.
+export function recordRetryAttempt<K>(
+  ref: MutableRefObject<RetryBudgetState<K>>,
+  id: K,
+  maxRetries: number,
+): boolean {
+  const previous = ref.current;
+  const count = previous.id === id ? previous.count + 1 : 1;
+  ref.current = { id, count };
+  return count <= maxRetries;
+}

package/src/utils/sdkCanvasComposition.test.ts

@@ -0,0 +1,77 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { openComposition } from "@hyperframes/sdk";
+
+/**
+ * linkedom's HTMLCanvasElement constructor calls `createCanvas(300, 150)` from
+ * the Node-only `canvas` package. linkedom guards that import in a try/catch —
+ * try the native package, fall back to its own bundled shim — but a bundler
+ * resolves the require statically, so the catch never fires in the browser
+ * build and `createCanvas` lands undefined. Parsing any `<canvas>` tag then
+ * throws, `openComposition` rejects, and Studio silently loses its SDK session
+ * for the whole composition (no cutover, and the resolver shadow does not run
+ * either).
+ *
+ * Production telemetry, 72h after the v0.8.47 flip: 1065 of 1544
+ * `studio:sdk_session_unavailable` events were this crash, spread across a
+ * large share of 197 users. Canvas is common in compositions — Three.js,
+ * shaders, particle effects, charts.
+ *
+ * The fix is a `resolve.alias` in the studio's vite config pointing `canvas` at
+ * linkedom's own shim. This test pins the behaviour the alias has to preserve.
+ */
+const CANVAS_COMPOSITION = `<!doctype html>
+<html>
+  <body data-composition-id="main" data-width="1920" data-height="1080">
+    <div class="clip" data-start="0" data-duration="3">
+      <canvas id="scene" width="800" height="600"></canvas>
+    </div>
+  </body>
+</html>`;
+
+describe("openComposition with a <canvas> element", () => {
+  it("opens a session instead of throwing on createCanvas", async () => {
+    const session = await openComposition(CANVAS_COMPOSITION, { history: false });
+    expect(session).toBeTruthy();
+    session.dispose();
+  });
+
+  it("models the canvas element so edits can target it", async () => {
+    const session = await openComposition(CANVAS_COMPOSITION, { history: false });
+    // A composition whose elements cannot be modelled is a session the cutover
+    // path declines wholesale (sessionEmpty), which is the same silent bypass by
+    // a different route.
+    expect(session.getElements().length).toBeGreaterThan(0);
+    session.dispose();
+  });
+});
+
+describe("canvas browser-stub alias", () => {
+  // The two tests above pass with OR without the fix: vitest resolves
+  // `require('canvas')` at runtime, so linkedom's own try/catch fallback works
+  // here. Only the bundled build breaks. Nothing else in this suite can observe
+  // the bundler, so the alias itself is what has to be pinned — without this,
+  // deleting the alias reintroduces a crash that is invisible until it reaches
+  // production telemetry.
+  it("is configured, so the browser build never resolves the Node canvas package", () => {
+    const config = readFileSync(resolve(import.meta.dirname, "../../vite.config.ts"), "utf8");
+    expect(config).toMatch(
+      /\bcanvas:\s*resolve\(__dirname,\s*"src\/shims\/canvasBrowserStub\.js"\)/,
+    );
+  });
+
+  it("exports the createCanvas shape linkedom destructures", async () => {
+    const stub = await import("../shims/canvasBrowserStub.js");
+    // linkedom takes the DEFAULT import and destructures createCanvas off it
+    // (`import Canvas from '...'; const {createCanvas} = Canvas`), so the
+    // default export is the one that actually has to carry the function.
+    expect(typeof stub.default.createCanvas).toBe("function");
+    expect(typeof stub.createCanvas).toBe("function");
+    const canvas = stub.default.createCanvas(300, 150);
+    expect(canvas.width).toBe(300);
+    expect(canvas.height).toBe(150);
+    expect(canvas.getContext()).toBeNull();
+  });
+});

package/src/utils/sdkCutover.familyGate.test.ts

@@ -41,6 +41,10 @@ describe("SDK family gate mapping", () => {
         {} as never,
         deps,
       ),
-    ).resolves.toMatchObject({ status: "declined", reason: "ineligible_operation" });
+      // The dom family is off, so the gate declines on the FLAG, not on the op
+      // batch (which is a perfectly eligible inline-style edit). Before the
+      // reason split this reported `ineligible_operation`, which read as "the
+      // SDK cannot express this edit" when the truth was "this family is off".
+    ).resolves.toMatchObject({ status: "declined", reason: "feature_disabled" });
   });
 });

package/src/utils/sdkCutover.ts

@@ -7,8 +7,8 @@ import { patchOpsToSdkEditOps } from "./sdkOpMapping";
 import { recordResolverParity, recordAnimationResolverParity } from "./sdkResolverShadow";
 import {
   isResolverDisagreement,
+  sdkCutoverIneligibleReason,
   shouldDeclineTextCutoverForTarget,
-  shouldUseSdkCutover,
 } from "./sdkCutoverEligibility";
 import {
   asCutoverError,
@@ -81,11 +81,14 @@ export async function sdkCutoverPersist(
   deps: CutoverDeps,
   options?: CutoverOptions,
 ): Promise<CutoverResult> {
-  if (!shouldUseSdkCutover(sdkFamilyEnabled("dom"), !!sdkSession, selection.hfId, ops))
-    return declinedCutover("ineligible_operation", "dom");
+  // Name WHICH eligibility check failed: on v0.8.47 this one string covered 26 of
+  // 30 dom declines. The two below aren't properties of the batch, so they differ.
+  if (!sdkFamilyEnabled("dom")) return declinedCutover("feature_disabled", "dom");
   if (!sdkSession) return declinedCutover("session_unavailable", "dom");
   const hfId = selection.hfId;
-  if (!hfId) return declinedCutover("target_unaddressable", "dom");
+  const ineligible = sdkCutoverIneligibleReason(hfId, ops);
+  // `!hfId` is already a reason; testing it again narrows the type for the rest.
+  if (ineligible || !hfId) return declinedCutover(ineligible ?? "target_unaddressable", "dom");
   const target = sdkSession.getElement(hfId);
   if (!target)
     return declinedCutover("target_not_found", "dom", isResolverDisagreement(sdkSession, hfId));

package/src/utils/sdkCutoverEligibility.test.ts

@@ -1,6 +1,27 @@
 import { describe, expect, it } from "vitest";
 import type { PatchOperation } from "./sourcePatcher";
-import { shouldUseSdkCutover } from "./sdkCutoverEligibility";
+import { shouldUseSdkCutover, sdkCutoverIneligibleReason } from "./sdkCutoverEligibility";
+
+const styleOp = (property: string, value: string): PatchOperation => ({
+  type: "inline-style",
+  property,
+  value,
+});
+const textOp = (value: string): PatchOperation => ({
+  type: "text-content",
+  property: "text",
+  value,
+});
+const attrOp = (property: string, value: string): PatchOperation => ({
+  type: "attribute",
+  property,
+  value,
+});
+const htmlAttrOp = (property: string, value: string): PatchOperation => ({
+  type: "html-attribute",
+  property,
+  value,
+});
 
 const childStyleOp: PatchOperation = {
   type: "inline-style",
@@ -15,3 +36,77 @@ describe("shouldUseSdkCutover child-scoped operations", () => {
     expect(shouldUseSdkCutover(true, true, "hf-parent", [childStyleOp])).toBe(false);
   });
 });
+
+describe("sdkCutoverIneligibleReason", () => {
+  // `ineligible_operation` was one string covering four distinct causes, which
+  // made the post-flip decline telemetry unactionable: 26 of 30 declines on
+  // v0.8.47 landed there, with no way to separate a structural edit the SDK has
+  // no vocabulary for (expected, permanent) from a reserved-attribute or
+  // unsafe-attribute decline (narrower, and possibly fixable).
+  it("names an op type the SDK cannot express", () => {
+    expect(
+      sdkCutoverIneligibleReason("hf-abc", [
+        { type: "split", property: "x", value: "1" } as unknown as PatchOperation,
+      ]),
+    ).toBe("unsupported_op_type");
+  });
+
+  it("names a child-scoped op", () => {
+    expect(sdkCutoverIneligibleReason("hf-parent", [childStyleOp])).toBe("child_scoped_op");
+  });
+
+  it("names a reserved attribute", () => {
+    expect(sdkCutoverIneligibleReason("hf-abc", [attrOp("end", "2")])).toBe("reserved_attribute");
+    expect(sdkCutoverIneligibleReason("hf-abc", [htmlAttrOp("DATA-START", "1")])).toBe(
+      "reserved_attribute",
+    );
+  });
+
+  it("names an unsafe html attribute", () => {
+    expect(sdkCutoverIneligibleReason("hf-abc", [htmlAttrOp("onclick", "alert(1)")])).toBe(
+      "unsafe_html_attribute",
+    );
+    expect(sdkCutoverIneligibleReason("hf-abc", [htmlAttrOp("href", "javascript:alert(1)")])).toBe(
+      "unsafe_html_attribute",
+    );
+  });
+
+  it("names an empty batch and an unaddressable target", () => {
+    expect(sdkCutoverIneligibleReason("hf-abc", [])).toBe("no_ops");
+    expect(sdkCutoverIneligibleReason(null, [styleOp("color", "red")])).toBe(
+      "target_unaddressable",
+    );
+  });
+
+  it("returns null when the batch is eligible", () => {
+    expect(sdkCutoverIneligibleReason("hf-abc", [styleOp("color", "red")])).toBeNull();
+    expect(
+      sdkCutoverIneligibleReason("hf-abc", [
+        styleOp("color", "red"),
+        textOp("hello"),
+        attrOp("x", "1"),
+        htmlAttrOp("class", "foo"),
+      ]),
+    ).toBeNull();
+  });
+
+  // The reason function must not drift from the predicate it explains: a batch
+  // the gate accepts must have no reason, and one it declines must have one.
+  it("agrees with shouldUseSdkCutover on every case", () => {
+    const cases: PatchOperation[][] = [
+      [styleOp("color", "red")],
+      [textOp("hello")],
+      [attrOp("x", "1")],
+      [htmlAttrOp("class", "foo")],
+      [attrOp("end", "2")],
+      [htmlAttrOp("onclick", "alert(1)")],
+      [childStyleOp],
+      [{ type: "split", property: "x", value: "1" } as unknown as PatchOperation],
+      [],
+    ];
+    for (const ops of cases) {
+      const eligible = shouldUseSdkCutover(true, true, "hf-abc", ops);
+      expect(sdkCutoverIneligibleReason("hf-abc", ops) === null).toBe(eligible);
+    }
+  });
+});

package/src/utils/sdkCutoverEligibility.ts

@@ -123,21 +123,44 @@ export function isResolverDisagreement(session: Composition, hfId: string): bool
   }
 }
 
+/**
+ * Why a batch cannot take the SDK cutover path, or null when it can.
+ *
+ * `ineligible_operation` used to be a single decline reason covering all of
+ * these, which made the post-flip telemetry unactionable — a structural edit the
+ * SDK has no vocabulary for (expected and permanent) was indistinguishable from
+ * a reserved-attribute decline (narrow, and possibly worth fixing). The order
+ * mirrors `shouldUseSdkCutover`'s conjunction, so the first failing check names
+ * the reason.
+ */
+export type SdkCutoverIneligibleReason =
+  | "target_unaddressable"
+  | "no_ops"
+  | "unsupported_op_type"
+  | "child_scoped_op"
+  | "reserved_attribute"
+  | "unsafe_html_attribute";
+
+export function sdkCutoverIneligibleReason(
+  hfId: string | null | undefined,
+  ops: PatchOperation[],
+): SdkCutoverIneligibleReason | null {
+  if (!hfId) return "target_unaddressable";
+  if (ops.length === 0) return "no_ops";
+  if (!ops.every((o) => CUTOVER_OP_TYPES.has(o.type))) return "unsupported_op_type";
+  if (hasChildScopedOp(ops)) return "child_scoped_op";
+  if (ops.some(mapsToReservedAttr)) return "reserved_attribute";
+  if (hasUnsafeHtmlAttributeOp(ops)) return "unsafe_html_attribute";
+  return null;
+}
+
 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)) &&
-    // SDK edit ops target only the element hfId; child-scoped patch ops need the server path.
-    !hasChildScopedOp(ops) &&
-    !ops.some(mapsToReservedAttr) &&
-    !hasUnsafeHtmlAttributeOp(ops)
-  );
+  // Derived from the reason function so the two can never disagree about which
+  // batches are eligible.
+  return flagEnabled && hasSession && sdkCutoverIneligibleReason(hfId, ops) === null;
 }