feat(studio): stage 7 step 3c — sdk cutover for inline-style ops

Author: vanceingalls

packages/studio/src/components/editor/manualEditingAvailability.ts

@@ -104,4 +104,13 @@ export const STUDIO_SDK_SHADOW_ENABLED = resolveStudioBooleanEnvFlag(
   false,
 );
 
+// Stage 7 Step 3c: SDK cutover — routes inline-style ops through SDK dispatch
+// instead of the server patch-element API. Default false; enable via
+// VITE_STUDIO_SDK_CUTOVER_ENABLED=true. Requires SDK session to be open.
+export const STUDIO_SDK_CUTOVER_ENABLED = resolveStudioBooleanEnvFlag(
+  env,
+  ["VITE_STUDIO_SDK_CUTOVER_ENABLED"],
+  false,
+);
+
 export const STUDIO_MANUAL_EDITING_DISABLED_TITLE = "Manual editing is temporarily disabled";

packages/studio/src/hooks/useDomEditCommits.ts

@@ -81,6 +81,13 @@ interface RecordEditInput {
   files: Record<string, { before: string; after: string }>;
 }
 
+type TrySdkPersist = (
+  s: DomEditSelection,
+  ops: PatchOperation[],
+  html: string,
+  path: string,
+) => Promise<boolean>;
+
 export type PersistDomEditOperations = (
   selection: DomEditSelection,
   operations: PatchOperation[],
@@ -119,8 +126,8 @@ export interface UseDomEditCommitsParams {
     target: HTMLElement,
     options?: { preferClipAncestor?: boolean },
   ) => Promise<DomEditSelection | null>;
-  /** Stage 7 Step 3b: called after a successful server-side element patch. */
   onDomEditPersisted?: (selection: DomEditSelection, operations: PatchOperation[]) => void;
+  onTrySdkPersist?: TrySdkPersist;
 }
 
 export function useDomEditCommits({
@@ -142,6 +149,7 @@ export function useDomEditCommits({
   refreshDomEditSelectionFromPreview,
   buildDomSelectionFromTarget,
   onDomEditPersisted,
+  onTrySdkPersist,
 }: UseDomEditCommitsParams) {
   const resolveImportedFontAsset = useCallback(
     (fontFamilyValue: string): ImportedFontAsset | null => {
@@ -190,11 +198,10 @@ export function useDomEditCommits({
 
       if (options?.shouldSave && !options.shouldSave()) return;
 
-      const patchTarget = buildDomEditPatchTarget(selection);
+      if (onTrySdkPersist)
+        if (await onTrySdkPersist(selection, operations, originalContent, targetPath)) return;
 
-      // Mark the save timestamp before the file write so the SSE file-change
-      // handler suppresses the reload even if the event arrives before the
-      // response (the server writes the file and emits SSE during the fetch).
+      const patchTarget = buildDomEditPatchTarget(selection);
       domEditSaveTimestampRef.current = Date.now();
 
       const patchResponse = await fetch(
@@ -265,11 +272,10 @@ export function useDomEditCommits({
       domEditSaveTimestampRef,
       reloadPreview,
       onDomEditPersisted,
+      onTrySdkPersist,
     ],
   );
 
-  // ── Text & style commits (delegated to useDomEditTextCommits) ──
-
   const {
     handleDomStyleCommit,
     handleDomAttributeCommit,
@@ -290,8 +296,6 @@ export function useDomEditCommits({
     resolveImportedFontAsset,
   });
 
-  // ── Position patch helper ──
-
   // fallow-ignore-next-line complexity
   const commitPositionPatchToHtml = useCallback(
     (
@@ -322,8 +326,6 @@ export function useDomEditCommits({
     [persistDomEditOperations, queueDomEditSave, showToast],
   );
 
-  // ── Position commits ──
-
   const handleDomPathOffsetCommit = useCallback(
     (selection: DomEditSelection, next: { x: number; y: number }) => {
       applyStudioPathOffset(selection.element, next);
@@ -400,8 +402,6 @@ export function useDomEditCommits({
     [commitPositionPatchToHtml],
   );
 
-  // ── Motion commits (HTML-attribute–backed) ──
-
   // fallow-ignore-next-line complexity
   const handleDomMotionCommit = useCallback(
     (

packages/studio/src/hooks/useDomEditSession.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { shouldUseSdkCutover } from "../utils/sdkCutover";
+import type { PatchOperation } from "../utils/sourcePatcher";
+
+const styleOp = (property: string, value: string): PatchOperation => ({
+  type: "inline-style",
+  property,
+  value,
+});
+
+const attrOp = (property: string, value: string): PatchOperation => ({
+  type: "attribute",
+  property,
+  value,
+});
+
+describe("shouldUseSdkCutover", () => {
+  it("returns false when flag is disabled", () => {
+    expect(shouldUseSdkCutover(false, true, "hf-abc", [styleOp("color", "red")])).toBe(false);
+  });
+
+  it("returns false when no SDK session", () => {
+    expect(shouldUseSdkCutover(true, false, "hf-abc", [styleOp("color", "red")])).toBe(false);
+  });
+
+  it("returns false when selection has no hfId", () => {
+    expect(shouldUseSdkCutover(true, true, null, [styleOp("color", "red")])).toBe(false);
+    expect(shouldUseSdkCutover(true, true, undefined, [styleOp("color", "red")])).toBe(false);
+  });
+
+  it("returns false when ops include non-inline-style types", () => {
+    expect(
+      shouldUseSdkCutover(true, true, "hf-abc", [styleOp("color", "red"), attrOp("data-x", "1")]),
+    ).toBe(false);
+  });
+
+  it("returns false when ops array is empty", () => {
+    expect(shouldUseSdkCutover(true, true, "hf-abc", [])).toBe(false);
+  });
+
+  it("returns true when flag on, session present, hfId set, all ops inline-style", () => {
+    expect(shouldUseSdkCutover(true, true, "hf-abc", [styleOp("color", "red")])).toBe(true);
+    expect(
+      shouldUseSdkCutover(true, true, "hf-abc", [
+        styleOp("color", "red"),
+        styleOp("opacity", "0.5"),
+      ]),
+    ).toBe(true);
+  });
+});

packages/studio/src/hooks/useDomEditSession.ts

@@ -11,13 +11,14 @@ import { useDomEditPreviewSync } from "./useDomEditPreviewSync";
 import type { ImportedFontAsset } from "../components/editor/fontAssets";
 import type { EditHistoryKind } from "../utils/editHistory";
 import type { RightPanelTab } from "../utils/studioHelpers";
-import type { PatchTarget } from "../utils/sourcePatcher";
+import type { PatchOperation, PatchTarget } from "../utils/sourcePatcher";
 import type { SidebarTab } from "../components/sidebar/LeftSidebar";
 import { useAskAgentModal } from "./useAskAgentModal";
 import { useDomSelection } from "./useDomSelection";
 import { usePreviewInteraction } from "./usePreviewInteraction";
 import { useDomEditCommits } from "./useDomEditCommits";
 import { reportShadowDispatch } from "../utils/sdkShadow";
+import { sdkCutoverPersist } from "../utils/sdkCutover";
 import { useGsapScriptCommits } from "./useGsapScriptCommits";
 import {
   useGsapAnimationsForElement,
@@ -34,8 +35,6 @@ import {
 import { useAnimatedPropertyCommit } from "./useAnimatedPropertyCommit";
 import { useGsapSelectionHandlers } from "./useGsapSelectionHandlers";
 
-// ── Types ──
-
 interface RecordEditInput {
   label: string;
   kind: EditHistoryKind;
@@ -79,12 +78,9 @@ export interface UseDomEditSessionParams {
   openSourceForSelection?: (sourceFile: string, target: PatchTarget) => void;
   selectSidebarTab?: (tab: SidebarTab) => void;
   getSidebarTab?: () => SidebarTab;
-  /** Stage 7 Step 3b: SDK session for shadow dispatch parity tracking. */
   sdkSession?: Composition | null;
 }
 
-// ── Hook ──
-
 // fallow-ignore-next-line complexity
 export function useDomEditSession({
   projectId,
@@ -138,8 +134,6 @@ export function useDomEditSession({
     [openSourceForSelection, selectSidebarTab],
   );
 
-  // ── Selection (delegated to useDomSelection) ──
-
   const {
     domEditSelection,
     domEditGroupSelections,
@@ -170,8 +164,6 @@ export function useDomEditSession({
     rightPanelTab,
   });
 
-  // ── Agent modal (delegated to useAskAgentModal) ──
-
   const {
     agentModalOpen,
     agentModalAnchorPoint,
@@ -192,8 +184,6 @@ export function useDomEditSession({
     domEditSelection,
   });
 
-  // ── Preview interaction (delegated to usePreviewInteraction) ──
-
   const {
     handlePreviewCanvasMouseDown,
     handlePreviewCanvasPointerMove,
@@ -212,8 +202,7 @@ export function useDomEditSession({
     onClickToSource,
   });
 
-  // Sync DOM selection → timeline selectedElementId so that clip selection
-  // highlights and diamond playhead fills work on cold-load URL restore.
+  // Sync DOM selection → timeline selectedElementId for cold-load URL restore.
   useEffect(() => {
     if (!domEditSelection?.id) return;
     const { selectedElementId, elements, setSelectedElementId } = usePlayerStore.getState();
@@ -224,13 +213,9 @@ export function useDomEditSession({
     if (key && key !== selectedElementId) setSelectedElementId(key);
   }, [domEditSelection?.id]);
 
-  // ── GSAP script editing ──
-
   const { version: gsapCacheVersion, bump: bumpGsapCache } = useGsapCacheVersion();
 
-  // Bump GSAP cache when refreshKey changes (code-tab edits trigger iframe
-  // reload via refreshKey but don't go through commitMutation, so the cache
-  // would otherwise retain stale keyframe entries).
+  // Bump GSAP cache on refreshKey — code-tab edits bypass commitMutation.
   const prevRefreshKeyRef = useRef(refreshKey);
   // eslint-disable-next-line no-restricted-syntax
   useEffect(() => {
@@ -292,7 +277,16 @@ export function useDomEditSession({
     onFileContentChanged: updateEditingFileContent,
   });
 
-  // ── Commit handlers (delegated to useDomEditCommits) ──
+  const onTrySdkPersist = useCallback(
+    (sel: DomEditSelection, ops: PatchOperation[], html: string, path: string) =>
+      sdkCutoverPersist(sel, ops, html, path, sdkSession, {
+        editHistory,
+        writeProjectFile,
+        reloadPreview,
+        domEditSaveTimestampRef,
+      }),
+    [sdkSession, editHistory, writeProjectFile, reloadPreview, domEditSaveTimestampRef],
+  );
 
   const {
     resolveImportedFontAsset,
@@ -333,6 +327,7 @@ export function useDomEditSession({
     onDomEditPersisted: sdkSession
       ? (sel, ops) => reportShadowDispatch(sdkSession, sel, ops)
       : undefined,
+    onTrySdkPersist,
   });
 
   // GSAP-aware: intercept offset/resize/rotation to commit via script mutation when animated.