@hyperframes/studio 0.7.28 → 0.7.30

package/src/hooks/useDomSelection.test.ts

@@ -0,0 +1,134 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import { installReactActEnvironment, makeSelection } from "./domSelectionTestHarness";
+import { useDomSelection } from "./useDomSelection";
+
+installReactActEnvironment();
+
+interface HarnessProps {
+  activeCompPath: string | null;
+  projectId: string | null;
+  refreshKey: number;
+}
+
+function renderHarness(initialProps: HarnessProps): {
+  current: () => ReturnType<typeof useDomSelection>;
+  rerender: (props: HarnessProps) => void;
+  cleanup: () => void;
+} {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  let currentHook: ReturnType<typeof useDomSelection> | null = null;
+
+  function Harness(props: HarnessProps) {
+    currentHook = useDomSelection({
+      projectId: props.projectId,
+      activeCompPath: props.activeCompPath,
+      isMasterView: false,
+      compIdToSrc: new Map(),
+      captionEditMode: false,
+      previewIframeRef: { current: null },
+      timelineElements: [],
+      setSelectedTimelineElementId: vi.fn(),
+      setRightCollapsed: vi.fn(),
+      setRightPanelTab: vi.fn(),
+      previewIframe: null,
+      refreshKey: props.refreshKey,
+      rightPanelTab: "design",
+    });
+    return null;
+  }
+
+  const rerender = (props: HarnessProps) => {
+    act(() => {
+      root.render(React.createElement(Harness, props));
+    });
+  };
+
+  rerender(initialProps);
+
+  return {
+    current: () => {
+      if (!currentHook) throw new Error("Expected hook result");
+      return currentHook;
+    },
+    rerender,
+    cleanup: () => {
+      act(() => root.unmount());
+      host.remove();
+    },
+  };
+}
+
+function setupSelectedHarness() {
+  const element = document.createElement("div");
+  element.id = "headline";
+  const selection = makeSelection("Headline", element);
+  const harness = renderHarness({
+    activeCompPath: "intro.html",
+    projectId: "project-1",
+    refreshKey: 0,
+  });
+  act(() => harness.current().applyDomSelection(selection));
+  return { selection, harness };
+}
+
+describe("useDomSelection", () => {
+  it("clears a committed selection when the active composition path changes", () => {
+    const { selection, harness } = setupSelectedHarness();
+    expect(harness.current().domEditSelection).toBe(selection);
+
+    harness.rerender({
+      activeCompPath: "outro.html",
+      projectId: "project-1",
+      refreshKey: 0,
+    });
+
+    expect(harness.current().domEditSelection).toBe(null);
+    harness.cleanup();
+  });
+
+  it("preserves a committed selection when composition identity is unchanged", () => {
+    const { selection, harness } = setupSelectedHarness();
+    harness.rerender({
+      activeCompPath: "intro.html",
+      projectId: "project-1",
+      refreshKey: 1,
+    });
+
+    expect(harness.current().domEditSelection).toBe(selection);
+    harness.cleanup();
+  });
+
+  it("preserves selection when clearing an already inactive group scope", () => {
+    const { selection, harness } = setupSelectedHarness();
+    act(() => harness.current().setActiveGroupElement(null));
+
+    expect(harness.current().domEditSelection).toBe(selection);
+    harness.cleanup();
+  });
+
+  it("preserves selection when entering the already active group scope", () => {
+    const group = document.createElement("div");
+    const child = document.createElement("span");
+    child.id = "headline";
+    group.append(child);
+    const selection = makeSelection("Headline", child);
+    const harness = renderHarness({
+      activeCompPath: "intro.html",
+      projectId: "project-1",
+      refreshKey: 0,
+    });
+
+    act(() => harness.current().setActiveGroupElement(group));
+    act(() => harness.current().applyDomSelection(selection));
+    act(() => harness.current().setActiveGroupElement(group));
+
+    expect(harness.current().domEditSelection).toBe(selection);
+    harness.cleanup();
+  });
+});

package/src/hooks/useDomSelection.ts

@@ -27,6 +27,18 @@ import { reapplyPositionEditsAfterSeek } from "../components/editor/manualEdits"
 
 // ── Types ──
 
+export interface ApplyDomSelectionOptions {
+  revealPanel?: boolean;
+  additive?: boolean;
+  preserveGroup?: boolean;
+}
+
+export interface ResolveDomSelectionOptions {
+  preferClipAncestor?: boolean;
+  skipSourceProbe?: boolean;
+  activeGroupElement?: HTMLElement | null;
+}
+
 export interface UseDomSelectionParams {
   projectId: string | null;
   activeCompPath: string | null;
@@ -61,29 +73,17 @@ export interface UseDomSelectionReturn {
   // Callbacks
   applyDomSelection: (
     selection: DomEditSelection | null,
-    options?: {
-      revealPanel?: boolean;
-      additive?: boolean;
-      preserveGroup?: boolean;
-    },
+    options?: ApplyDomSelectionOptions,
   ) => void;
   clearDomSelection: () => void;
   buildDomSelectionFromTarget: (
     target: HTMLElement,
-    options?: {
-      preferClipAncestor?: boolean;
-      skipSourceProbe?: boolean;
-      activeGroupElement?: HTMLElement | null;
-    },
+    options?: ResolveDomSelectionOptions,
   ) => Promise<DomEditSelection | null>;
   resolveDomSelectionFromPreviewPoint: (
     clientX: number,
     clientY: number,
-    options?: {
-      preferClipAncestor?: boolean;
-      skipSourceProbe?: boolean;
-      activeGroupElement?: HTMLElement | null;
-    },
+    options?: ResolveDomSelectionOptions,
   ) => Promise<DomEditSelection | null>;
   resolveAllDomSelectionsFromPreviewPoint: (
     clientX: number,
@@ -130,6 +130,7 @@ export function useDomSelection({
   const domEditGroupSelectionsRef = useRef<DomEditSelection[]>(domEditGroupSelections);
   const domEditHoverSelectionRef = useRef<DomEditSelection | null>(domEditHoverSelection);
   const activeGroupElementRef = useRef<HTMLElement | null>(activeGroupElement);
+  const compositionIdentityRef = useRef({ activeCompPath, projectId });
 
   // Keep refs in sync with state
   domEditSelectionRef.current = domEditSelection;
@@ -230,6 +231,8 @@ export function useDomSelection({
   // the user isn't left with an out-of-scope element selected.
   const setActiveGroupElement = useCallback(
     (el: HTMLElement | null) => {
+      if (activeGroupElementRef.current === el) return;
+      activeGroupElementRef.current = el;
       setActiveGroupElementState(el);
       applyDomSelection(null, { revealPanel: false });
     },
@@ -454,6 +457,17 @@ export function useDomSelection({
     updateDomEditHoverSelection(null);
   }, [activeCompPath, projectId, previewIframe, refreshKey, updateDomEditHoverSelection]);
 
+  // Clear committed selection only when the composition identity actually changes.
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    const previous = compositionIdentityRef.current;
+    if (previous.activeCompPath === activeCompPath && previous.projectId === projectId) return;
+    compositionIdentityRef.current = { activeCompPath, projectId };
+    activeGroupElementRef.current = null;
+    setActiveGroupElementState(null);
+    applyDomSelection(null, { revealPanel: false });
+  }, [activeCompPath, projectId, applyDomSelection]);
+
   // Clear hover conditionally (caption mode, matches selection, disconnected element)
   // eslint-disable-next-line no-restricted-syntax
   useEffect(() => {

package/src/hooks/usePreviewInteraction.test.ts

@@ -0,0 +1,260 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { usePlayerStore } from "../player";
+import { installReactActEnvironment, makeSelection } from "./domSelectionTestHarness";
+import { usePreviewInteraction } from "./usePreviewInteraction";
+
+installReactActEnvironment();
+
+function createPreviewIframe(playerPause?: () => void): HTMLIFrameElement {
+  const iframe = document.createElement("iframe");
+  if (playerPause) {
+    Object.defineProperty(iframe, "contentWindow", {
+      configurable: true,
+      value: {
+        __player: {
+          getTime: () => 3.25,
+          pause: playerPause,
+        },
+      },
+    });
+  }
+  return iframe;
+}
+
+interface HarnessArgs {
+  previewIframe: HTMLIFrameElement | null;
+  resolveDomSelectionFromPreviewPoint: (
+    clientX: number,
+    clientY: number,
+    options?: { activeGroupElement?: HTMLElement | null },
+  ) => Promise<DomEditSelection | null>;
+  resolveAllDomSelectionsFromPreviewPoint?: (
+    clientX: number,
+    clientY: number,
+  ) => Promise<DomEditSelection[]>;
+  applyDomSelection: (
+    selection: DomEditSelection | null,
+    options?: { revealPanel?: boolean; additive?: boolean; preserveGroup?: boolean },
+  ) => void;
+  setActiveGroupElement?: (el: HTMLElement | null) => void;
+  mouseDownOptions?: {
+    preferClipAncestor?: boolean;
+    hoverSelection?: DomEditSelection | null;
+  };
+}
+
+function renderHarness(args: HarnessArgs): {
+  canvas: HTMLDivElement;
+  cleanup: () => void;
+} {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+
+  function Harness() {
+    const interaction = usePreviewInteraction({
+      captionEditMode: false,
+      compositionLoading: false,
+      previewIframeRef: { current: args.previewIframe },
+      showToast: vi.fn(),
+      applyDomSelection: args.applyDomSelection,
+      resolveDomSelectionFromPreviewPoint: args.resolveDomSelectionFromPreviewPoint,
+      resolveAllDomSelectionsFromPreviewPoint:
+        args.resolveAllDomSelectionsFromPreviewPoint ?? vi.fn(async () => []),
+      updateDomEditHoverSelection: vi.fn(),
+      setActiveGroupElement: args.setActiveGroupElement ?? vi.fn(),
+    });
+
+    return React.createElement("div", {
+      id: "canvas",
+      onMouseDown: (event: React.MouseEvent<HTMLDivElement>) => {
+        void interaction.handlePreviewCanvasMouseDown(event, args.mouseDownOptions);
+      },
+    });
+  }
+
+  act(() => {
+    root.render(React.createElement(Harness));
+  });
+
+  const canvas = host.querySelector("#canvas");
+  if (!(canvas instanceof HTMLDivElement)) throw new Error("Expected canvas div");
+
+  return {
+    canvas,
+    cleanup: () => {
+      act(() => root.unmount());
+      host.remove();
+    },
+  };
+}
+
+async function dispatchMouseDown(canvas: HTMLDivElement, init: MouseEventInit): Promise<void> {
+  await act(async () => {
+    canvas.dispatchEvent(
+      new MouseEvent("mousedown", {
+        bubbles: true,
+        cancelable: true,
+        clientX: 50,
+        clientY: 60,
+        ...init,
+      }),
+    );
+    await Promise.resolve();
+    await Promise.resolve();
+  });
+}
+
+describe("usePreviewInteraction", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("pauses playback before resolving a click and falls back to the tracked hover selection", async () => {
+    const order: string[] = [];
+    const playerPause = vi.fn(() => {
+      order.push("pause");
+    });
+    const element = document.createElement("div");
+    element.id = "headline";
+    const hoverSelection = makeSelection("Headline", element);
+    const applyDomSelection = vi.fn();
+    const resolveDomSelectionFromPreviewPoint = vi.fn(async () => {
+      order.push("resolve");
+      return null;
+    });
+    const { canvas, cleanup } = renderHarness({
+      previewIframe: createPreviewIframe(playerPause),
+      resolveDomSelectionFromPreviewPoint,
+      applyDomSelection,
+      mouseDownOptions: { preferClipAncestor: false, hoverSelection },
+    });
+
+    await dispatchMouseDown(canvas, {});
+
+    expect(order[0]).toBe("pause");
+    expect(applyDomSelection).toHaveBeenCalledWith(hoverSelection);
+    cleanup();
+  });
+
+  it("treats a double-click on a regular element as a plain selection", async () => {
+    const element = document.createElement("div");
+    element.id = "headline";
+    const selection = makeSelection("Headline", element);
+    const applyDomSelection = vi.fn();
+    let resolveCount = 0;
+    const resolveDomSelectionFromPreviewPoint = vi.fn(async () => {
+      resolveCount += 1;
+      return resolveCount === 1 ? selection : null;
+    });
+    const { canvas, cleanup } = renderHarness({
+      previewIframe: null,
+      resolveDomSelectionFromPreviewPoint,
+      applyDomSelection,
+    });
+
+    await dispatchMouseDown(canvas, { detail: 2 });
+
+    expect(applyDomSelection).toHaveBeenCalledWith(selection);
+    expect(applyDomSelection).not.toHaveBeenCalledWith(null, { revealPanel: false });
+    cleanup();
+  });
+
+  it("preserves group drill-in on double-click", async () => {
+    const group = document.createElement("div");
+    group.setAttribute("data-hf-group", "hero");
+    const child = document.createElement("span");
+    child.id = "headline";
+    group.append(child);
+    const groupSelection = makeSelection("Hero Group", group);
+    const childSelection = makeSelection("Headline", child);
+    const applyDomSelection = vi.fn();
+    const setActiveGroupElement = vi.fn();
+    const resolveDomSelectionFromPreviewPoint = vi.fn(
+      async (
+        _clientX: number,
+        _clientY: number,
+        options?: { activeGroupElement?: HTMLElement | null },
+      ) => (options?.activeGroupElement === group ? childSelection : groupSelection),
+    );
+    const { canvas, cleanup } = renderHarness({
+      previewIframe: null,
+      resolveDomSelectionFromPreviewPoint,
+      applyDomSelection,
+      setActiveGroupElement,
+    });
+
+    await dispatchMouseDown(canvas, { detail: 2 });
+
+    expect(setActiveGroupElement).toHaveBeenCalledWith(group);
+    expect(applyDomSelection).toHaveBeenCalledWith(childSelection);
+    cleanup();
+  });
+
+  it("cycles stacked candidates on a rapid second click at the same spot", async () => {
+    const topElement = document.createElement("div");
+    topElement.id = "top";
+    const bottomElement = document.createElement("div");
+    bottomElement.id = "bottom";
+    const topSelection = makeSelection("Top", topElement);
+    const bottomSelection = makeSelection("Bottom", bottomElement);
+    const applyDomSelection = vi.fn();
+    const resolveDomSelectionFromPreviewPoint = vi.fn(async () => topSelection);
+    const resolveAllDomSelectionsFromPreviewPoint = vi.fn(async () => [
+      topSelection,
+      bottomSelection,
+    ]);
+    const { canvas, cleanup } = renderHarness({
+      previewIframe: null,
+      resolveDomSelectionFromPreviewPoint,
+      resolveAllDomSelectionsFromPreviewPoint,
+      applyDomSelection,
+    });
+
+    await dispatchMouseDown(canvas, { detail: 1 });
+    await dispatchMouseDown(canvas, { detail: 2 });
+
+    expect(applyDomSelection).toHaveBeenNthCalledWith(1, topSelection);
+    expect(applyDomSelection).toHaveBeenNthCalledWith(2, bottomSelection);
+    cleanup();
+  });
+
+  it("resumes playback when a click resolves to nothing (dead-zone / deselect)", async () => {
+    usePlayerStore.setState({ isPlaying: true });
+    const applyDomSelection = vi.fn();
+    const resolveDomSelectionFromPreviewPoint = vi.fn(async () => null);
+    const { canvas, cleanup } = renderHarness({
+      previewIframe: createPreviewIframe(vi.fn()),
+      resolveDomSelectionFromPreviewPoint,
+      applyDomSelection,
+    });
+
+    await dispatchMouseDown(canvas, {});
+
+    expect(applyDomSelection).toHaveBeenCalledWith(null, { revealPanel: false });
+    expect(usePlayerStore.getState().isPlaying).toBe(true);
+    cleanup();
+  });
+
+  it("does not resume playback on deselect when it was already paused", async () => {
+    usePlayerStore.setState({ isPlaying: false });
+    const applyDomSelection = vi.fn();
+    const resolveDomSelectionFromPreviewPoint = vi.fn(async () => null);
+    const { canvas, cleanup } = renderHarness({
+      previewIframe: createPreviewIframe(vi.fn()),
+      resolveDomSelectionFromPreviewPoint,
+      applyDomSelection,
+    });
+
+    await dispatchMouseDown(canvas, {});
+
+    expect(applyDomSelection).toHaveBeenCalledWith(null, { revealPanel: false });
+    expect(usePlayerStore.getState().isPlaying).toBe(false);
+    cleanup();
+  });
+});

package/src/hooks/usePreviewInteraction.ts

@@ -3,6 +3,7 @@ import { liveTime, usePlayerStore } from "../player";
 import { pauseStudioPreviewPlayback } from "../utils/studioPreviewHelpers";
 import { STUDIO_PREVIEW_SELECTION_ENABLED } from "../components/editor/manualEditingAvailability";
 import { type DomEditSelection } from "../components/editor/domEditing";
+import type { ApplyDomSelectionOptions, ResolveDomSelectionOptions } from "./useDomSelection";
 import { trackStudioEvent } from "../utils/studioTelemetry";
 
 // ── Types ──
@@ -16,16 +17,12 @@ export interface UsePreviewInteractionParams {
   // From useDomSelection
   applyDomSelection: (
     selection: DomEditSelection | null,
-    options?: { revealPanel?: boolean; additive?: boolean; preserveGroup?: boolean },
+    options?: ApplyDomSelectionOptions,
   ) => void;
   resolveDomSelectionFromPreviewPoint: (
     clientX: number,
     clientY: number,
-    options?: {
-      preferClipAncestor?: boolean;
-      skipSourceProbe?: boolean;
-      activeGroupElement?: HTMLElement | null;
-    },
+    options?: ResolveDomSelectionOptions,
   ) => Promise<DomEditSelection | null>;
   resolveAllDomSelectionsFromPreviewPoint: (
     clientX: number,
@@ -46,6 +43,11 @@ interface ClickCycleState {
   at: number;
 }
 
+export interface PreviewMouseDownOptions {
+  preferClipAncestor?: boolean;
+  hoverSelection?: DomEditSelection | null;
+}
+
 const CYCLE_RADIUS_PX = 6;
 const CYCLE_WINDOW_MS = 600;
 // Manual double-click window. `e.detail` can't be trusted here: the first click
@@ -72,9 +74,19 @@ export function usePreviewInteraction({
   const cycleRef = useRef<ClickCycleState | null>(null);
   const lastDownRef = useRef<{ t: number; x: number; y: number } | null>(null);
 
+  const pausePreviewPlayback = useCallback(() => {
+    const pausedTime = pauseStudioPreviewPlayback(previewIframeRef.current);
+    const playerStore = usePlayerStore.getState();
+    playerStore.setIsPlaying(false);
+    if (pausedTime != null) {
+      playerStore.setCurrentTime(pausedTime);
+      liveTime.notify(pausedTime);
+    }
+  }, [previewIframeRef]);
+
   const handlePreviewCanvasMouseDown = useCallback(
     // fallow-ignore-next-line complexity
-    async (e: React.MouseEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
+    async (e: React.MouseEvent<HTMLDivElement>, options?: PreviewMouseDownOptions) => {
       if (!STUDIO_PREVIEW_SELECTION_ENABLED || captionEditMode || compositionLoading) return;
 
       // Manual double-click detection (see DOUBLE_CLICK_MS): the first click
@@ -87,12 +99,26 @@ export function usePreviewInteraction({
           downTs - lastDown.t < DOUBLE_CLICK_MS &&
           Math.hypot(e.clientX - lastDown.x, e.clientY - lastDown.y) < DOUBLE_CLICK_RADIUS_PX);
       lastDownRef.current = { t: downTs, x: e.clientX, y: e.clientY };
+      const wasPlaying = usePlayerStore.getState().isPlaying;
+      pausePreviewPlayback();
+      // A click that resolves to nothing (dead-zone / deselect) shouldn't leave
+      // playback paused — pausing before sampling only exists to keep the hit
+      // target stable while resolving; resume if nothing was selected.
+      const resumeIfNothingSelected = () => {
+        if (wasPlaying) usePlayerStore.getState().setIsPlaying(true);
+      };
 
       // Double-click a group → drill into it and select the child under the
       // pointer (resolve with the group as the explicit drill-in scope, since the
       // activeGroupElement state hasn't re-rendered yet within this handler).
       if (isDoubleClick && !e.shiftKey) {
         const hit = await resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY);
+        const cycle = cycleRef.current;
+        const hasStackCycleAtSpot =
+          cycle !== null &&
+          cycle.candidates.length > 1 &&
+          Math.hypot(e.clientX - cycle.x, e.clientY - cycle.y) < CYCLE_RADIUS_PX &&
+          downTs - cycle.at < CYCLE_WINDOW_MS;
         if (hit?.element.hasAttribute("data-hf-group")) {
           e.preventDefault();
           e.stopPropagation();
@@ -105,6 +131,18 @@ export function usePreviewInteraction({
           applyDomSelection(child ?? hit);
           return;
         }
+        if (
+          hit &&
+          !hasStackCycleAtSpot &&
+          !hit.element.hasAttribute("data-composition-src") &&
+          !hit.element.hasAttribute("data-composition-file")
+        ) {
+          e.preventDefault();
+          e.stopPropagation();
+          cycleRef.current = null;
+          applyDomSelection(hit);
+          return;
+        }
       }
 
       const now = Date.now();
@@ -119,10 +157,16 @@ export function usePreviewInteraction({
       if (e.shiftKey) {
         // Additive selection — no cycling
         cycleRef.current = null;
-        const nextSelection = await resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY, {
-          preferClipAncestor: options?.preferClipAncestor ?? false,
-        });
-        if (!nextSelection) return;
+        const nextSelection =
+          (await resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY, {
+            preferClipAncestor: options?.preferClipAncestor ?? false,
+          })) ??
+          options?.hoverSelection ??
+          null;
+        if (!nextSelection) {
+          resumeIfNothingSelected();
+          return;
+        }
         e.preventDefault();
         e.stopPropagation();
         applyDomSelection(nextSelection, { additive: true });
@@ -156,9 +200,11 @@ export function usePreviewInteraction({
           activeGroupElement: null,
         });
       }
+      nextSelection = nextSelection ?? options?.hoverSelection ?? null;
       if (!nextSelection) {
         cycleRef.current = null;
         applyDomSelection(null, { revealPanel: false });
+        resumeIfNothingSelected();
         return;
       }
       e.preventDefault();
@@ -180,6 +226,7 @@ export function usePreviewInteraction({
       captionEditMode,
       compositionLoading,
       onClickToSource,
+      pausePreviewPlayback,
       resolveAllDomSelectionsFromPreviewPoint,
       resolveDomSelectionFromPreviewPoint,
       setActiveGroupElement,
@@ -225,14 +272,8 @@ export function usePreviewInteraction({
   );
 
   const handleDomManualDragStart = useCallback(() => {
-    const pausedTime = pauseStudioPreviewPlayback(previewIframeRef.current);
-    const playerStore = usePlayerStore.getState();
-    playerStore.setIsPlaying(false);
-    if (pausedTime != null) {
-      playerStore.setCurrentTime(pausedTime);
-      liveTime.notify(pausedTime);
-    }
-  }, [previewIframeRef]);
+    pausePreviewPlayback();
+  }, [pausePreviewPlayback]);
 
   return {
     handlePreviewCanvasMouseDown,

package/src/utils/sdkCutoverEligibility.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import type { PatchOperation } from "./sourcePatcher";
+import { shouldUseSdkCutover } from "./sdkCutoverEligibility";
+
+const childStyleOp: PatchOperation = {
+  type: "inline-style",
+  property: "color",
+  value: "blue",
+  childSelector: ":scope > span",
+  childIndex: 0,
+};
+
+describe("shouldUseSdkCutover child-scoped operations", () => {
+  it("declines child-scoped operations because SDK patch ops target only the parent hfId", () => {
+    expect(shouldUseSdkCutover(true, true, "hf-parent", [childStyleOp])).toBe(false);
+  });
+});

package/src/utils/sdkCutoverEligibility.ts

@@ -61,19 +61,23 @@ function hasUnsafeHtmlAttributeOp(ops: PatchOperation[]): boolean {
   );
 }
 
+function hasChildScopedOp(ops: PatchOperation[]): boolean {
+  return ops.some((op) => op.childSelector !== undefined);
+}
+
 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;
+  const children = target.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;
+  const tag = element.tag;
   return typeof tag === "string" ? tag.toLowerCase() : null;
 }
 
@@ -110,6 +114,8 @@ export function shouldUseSdkCutover(
     !!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)
   );