fix(studio): make sdk cutover transactional

Author: jrusso1020

packages/studio/src/App.tsx

@@ -184,6 +184,7 @@ export function StudioApp() {
     uploadProjectFiles: fileManager.uploadProjectFiles,
     isRecordingRef: isGestureRecordingRef,
     sdkSession: editFlowSdkSession,
+    publishSdkSession: sdkHandle.publish,
     forceReloadSdkSession: sdkHandle.forceReload,
     handleDomZIndexReorderCommitRef,
   });
@@ -301,6 +302,7 @@ export function StudioApp() {
     selectSidebarTab: sidebarTabRef.current.select,
     getSidebarTab: sidebarTabRef.current.get,
     sdkSession: editFlowSdkSession,
+    publishSdkSession: sdkHandle.publish,
     forceReloadSdkSession: sdkHandle.forceReload,
   });
   domEditSelectionBridgeRef.current = domEditSession.domEditSelection;
@@ -559,6 +561,7 @@ export function StudioApp() {
                         recordingDuration={gestureRecording.recordingDuration}
                         onToggleRecording={recordingToggle}
                         sdkSession={sdkHandle.session}
+                        publishSdkSession={sdkHandle.publish}
                         reloadPreview={reloadPreview}
                         domEditSaveTimestampRef={domEditSaveTimestampRef}
                         recordEdit={editHistory.recordEdit}

packages/studio/src/components/DesignPanelPromoteProvider.tsx

@@ -35,6 +35,7 @@ export function DesignPanelPromoteProvider({
   const persist = useVariablesPersist({
     ...persistDeps,
     sdkSession: handle.session,
+    publishSdkSession: handle.publish,
     activeCompPath: targetPath,
   });
   return (

packages/studio/src/components/StudioRightPanel.tsx

@@ -56,6 +56,7 @@ export interface StudioRightPanelProps {
   onToggleRecording?: () => void;
   /** Dependencies for the Slideshow persist callback, threaded from App.tsx. */
   sdkSession: Composition | null;
+  publishSdkSession: (session: Composition) => void;
   reloadPreview: () => void;
   domEditSaveTimestampRef: MutableRefObject<number>;
   recordEdit: (entry: {
@@ -75,6 +76,7 @@ export function StudioRightPanel({
   recordingDuration,
   onToggleRecording,
   sdkSession,
+  publishSdkSession,
   reloadPreview,
   domEditSaveTimestampRef,
   recordEdit,
@@ -167,6 +169,7 @@ export function StudioRightPanel({
     recordEdit,
     reloadPreview,
     domEditSaveTimestampRef,
+    publishSdkSession,
   });
 
   // Notes path: persists are debounced in SlideshowPanel; coalesceKey ensures
@@ -179,6 +182,7 @@ export function StudioRightPanel({
     recordEdit,
     reloadPreview,
     domEditSaveTimestampRef,
+    publishSdkSession,
     coalesceKey: activeCompPath ? `slideshow-notes:${activeCompPath}` : "slideshow-notes",
   });
 
@@ -529,6 +533,7 @@ export function StudioRightPanel({
               ) : rightPanelTab === "variables" ? (
                 <VariablesPanel
                   sdkSession={sdkSession}
+                  publishSdkSession={publishSdkSession}
                   reloadPreview={reloadPreview}
                   domEditSaveTimestampRef={domEditSaveTimestampRef}
                   recordEdit={recordEdit}

packages/studio/src/components/panels/VariablesPanel.tsx

@@ -32,6 +32,7 @@ function shellSingleQuote(value: string): string {
 
 interface VariablesPanelProps {
   sdkSession: Composition | null;
+  publishSdkSession: (session: Composition) => void;
   reloadPreview: () => void;
   domEditSaveTimestampRef: MutableRefObject<number>;
   recordEdit: (entry: {
@@ -247,6 +248,7 @@ const EMPTY_STATE = (
 // fallow-ignore-next-line complexity
 export const VariablesPanel = memo(function VariablesPanel({
   sdkSession,
+  publishSdkSession,
   reloadPreview,
   domEditSaveTimestampRef,
   recordEdit,
@@ -285,6 +287,7 @@ export const VariablesPanel = memo(function VariablesPanel({
     recordEdit,
     reloadPreview,
     domEditSaveTimestampRef,
+    publishSdkSession,
   });
 
   const declarations = useMemo(

packages/studio/src/hooks/gsapScriptCommitTypes.ts

@@ -76,6 +76,8 @@ export interface GsapScriptCommitsParams {
   showToast: (message: string, tone?: "error" | "info") => void;
   /** Stage 7 §3.5: SDK session for routing GSAP tween ops through addGsapTween/setGsapTween/removeGsapTween. */
   sdkSession?: Composition | null;
+  /** Publish a fully persisted candidate SDK session. */
+  publishSdkSession?: (session: Composition) => void;
   writeProjectFile?: (path: string, content: string) => Promise<void>;
   /** Resync the in-memory SDK session after a server-authoritative write. */
   forceReloadSdkSession?: () => void;

packages/studio/src/hooks/useDomEditCommits.ts

@@ -20,6 +20,7 @@ import { useDomEditTextCommits } from "./useDomEditTextCommits";
 import { useDomGeometryCommits } from "./useDomGeometryCommits";
 import { useElementLifecycleOps } from "./useElementLifecycleOps";
 import { formatFieldsSuffix } from "./gsapScriptCommitHelpers";
+import { cutoverCommittedOrThrow, type CutoverResult } from "../utils/sdkCutover";
 
 // ── Helpers ──
 
@@ -81,16 +82,20 @@ export interface UseDomEditCommitsParams {
    * path, whose session is already current) so a later SDK edit doesn't
    * serialize the pre-write doc and revert the server's change. */
   forceReloadSdkSession?: () => void;
-  /** Stage 7 Step 3c: called before the server-side patch path; returns true if SDK handled it. */
+  /** Stage 7 Step 3c: called before the server-side patch path. */
   onTrySdkPersist?: (
     selection: DomEditSelection,
     operations: PatchOperation[],
     originalContent: string,
     targetPath: string,
     options?: { label?: string; coalesceKey?: string; skipRefresh?: boolean },
-  ) => Promise<boolean>;
-  /** Stage 7 §3.1: called before the server-side delete path; returns true if SDK handled it. */
-  onTrySdkDelete?: (hfId: string, originalContent: string, targetPath: string) => Promise<boolean>;
+  ) => Promise<CutoverResult>;
+  /** Stage 7 §3.1: called before the server-side delete path. */
+  onTrySdkDelete?: (
+    hfId: string,
+    originalContent: string,
+    targetPath: string,
+  ) => Promise<CutoverResult>;
   /** Resolver-shadow tripwire for z-index reorder targets (telemetry-only, decoupled from cutover). */
   onReorderShadow?: (targets: string[]) => void;
 }
@@ -185,18 +190,17 @@ export function useDomEditCommits({
       // Skip the SDK path when prepareContent is set (e.g. @font-face injection
       // for a custom font): sdkCutoverPersist serializes only the patched DOM
       // and would drop the injected content. Let the server path run prepareContent.
-      if (
-        onTrySdkPersist &&
-        !options?.prepareContent &&
-        (await onTrySdkPersist(selection, operations, originalContent, targetPath, {
+      if (onTrySdkPersist && !options?.prepareContent) {
+        const cutover = await onTrySdkPersist(selection, operations, originalContent, targetPath, {
           label: options?.label,
           coalesceKey: options?.coalesceKey,
           skipRefresh: options?.skipRefresh,
-        }))
-      ) {
-        // SDK handled it — its in-memory doc is already current, so do NOT
-        // forceReload (that would echo-reload the session we just wrote).
-        return;
+        });
+        if (cutoverCommittedOrThrow(cutover)) {
+          // SDK handled it — its in-memory doc is already current, so do NOT
+          // forceReload (that would echo-reload the session we just wrote).
+          return;
+        }
       }
 
       // Mark the save timestamp before the file write so the SSE file-change

packages/studio/src/hooks/useDomEditSession.ts

@@ -67,6 +67,7 @@ export interface UseDomEditSessionParams {
   selectSidebarTab?: (tab: SidebarTab) => void;
   getSidebarTab?: () => SidebarTab;
   sdkSession?: Composition | null;
+  publishSdkSession?: (session: Composition) => void;
   forceReloadSdkSession?: () => void;
 }
 
@@ -108,6 +109,7 @@ export function useDomEditSession({
   selectSidebarTab,
   getSidebarTab,
   sdkSession,
+  publishSdkSession,
   forceReloadSdkSession,
 }: UseDomEditSessionParams) {
   void _setRefreshKey;
@@ -217,6 +219,7 @@ export function useDomEditSession({
     onFileContentChanged: updateEditingFileContent,
     showToast,
     sdkSession,
+    publishSdkSession,
     writeProjectFile,
     forceReloadSdkSession,
   });
@@ -274,6 +277,8 @@ export function useDomEditSession({
               reloadPreview,
               domEditSaveTimestampRef,
               compositionPath: activeCompPath,
+              readProjectFile,
+              publishSession: publishSdkSession,
             },
             options,
           );
@@ -287,6 +292,8 @@ export function useDomEditSession({
             reloadPreview,
             domEditSaveTimestampRef,
             compositionPath: activeCompPath,
+            readProjectFile,
+            publishSession: publishSdkSession,
           })
       : undefined,
     // Resolver shadow for the z-index reorder edit: it takes the server path (no

packages/studio/src/hooks/useElementLifecycleOps.ts

@@ -9,6 +9,7 @@ import {
 } from "../components/editor/domEditing";
 import type { PatchOperation } from "../utils/sourcePatcher";
 import type { EditHistoryKind } from "../utils/editHistory";
+import { cutoverCommittedOrThrow, type CutoverResult } from "../utils/sdkCutover";
 
 interface RecordEditInput {
   label: string;
@@ -26,8 +27,12 @@ interface UseElementLifecycleOpsParams {
   projectIdRef: React.MutableRefObject<string | null>;
   reloadPreview: () => void;
   clearDomSelection: () => void;
-  /** Route delete through SDK when session resolves the hf-id; returns true if handled. */
-  onTrySdkDelete?: (hfId: string, originalContent: string, targetPath: string) => Promise<boolean>;
+  /** Route delete through SDK when session resolves the hf-id. */
+  onTrySdkDelete?: (
+    hfId: string,
+    originalContent: string,
+    targetPath: string,
+  ) => Promise<CutoverResult>;
   /** Resolver-shadow tripwire for the reordered targets (telemetry-only, decoupled from cutover). */
   onReorderShadow?: (targets: string[]) => void;
   /** Resync the SDK session after a server-fallback delete. */
@@ -85,7 +90,7 @@ export function useElementLifecycleOps({
 
         if (onTrySdkDelete && selection.hfId) {
           const handled = await onTrySdkDelete(selection.hfId, originalContent, targetPath);
-          if (handled) {
+          if (cutoverCommittedOrThrow(handled)) {
             clearDomSelection();
             usePlayerStore.getState().setSelectedElementId(null);
             showToast(`Deleted ${label}. Use Undo to restore it.`, "info");

packages/studio/src/hooks/useGsapAnimationOps.ts

@@ -7,6 +7,7 @@ import {
   sdkGsapDeleteAllForSelectorPersist,
   sdkAddWithKeyframesPersist,
   sdkReplaceWithKeyframesPersist,
+  cutoverCommittedOrThrow,
   type CutoverDeps,
 } from "../utils/sdkCutover";
 import {
@@ -52,7 +53,7 @@ export function useGsapAnimationOps({
           sdkDeps,
           { label: "Edit GSAP animation", coalesceKey: `gsap:${animationId}:meta` },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       commitMutationSafely(
         selection,
@@ -74,7 +75,7 @@ export function useGsapAnimationOps({
           sdkDeps,
           { label: "Delete GSAP animation" },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       commitMutationSafely(
         selection,
@@ -96,7 +97,7 @@ export function useGsapAnimationOps({
           sdkDeps,
           { label: "Delete all animations for element" },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       void commitMutation(
         selection,
@@ -162,7 +163,7 @@ export function useGsapAnimationOps({
           sdkDeps,
           { label: `Add GSAP ${method} animation` },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
 
       await commitMutation(
@@ -213,7 +214,7 @@ export function useGsapAnimationOps({
           sdkDeps,
           { label },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       void commitMutation(
         selection,
@@ -256,7 +257,7 @@ export function useGsapAnimationOps({
           sdkDeps,
           { label },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       void commitMutation(
         selection,

packages/studio/src/hooks/useGsapKeyframeOps.ts

@@ -8,6 +8,7 @@ import {
   sdkGsapRemoveKeyframePersist,
   sdkGsapRemoveAllKeyframesPersist,
   sdkGsapConvertToKeyframesPersist,
+  cutoverCommittedOrThrow,
   type CutoverDeps,
 } from "../utils/sdkCutover";
 import type { KeyframeCacheEntry } from "../player/store/playerStore";
@@ -120,7 +121,7 @@ export function useGsapKeyframeOps({
                 coalesceKey: `gsap:${animationId}:kf:${percentage}`,
               },
             );
-            if (handled) return;
+            if (cutoverCommittedOrThrow(handled)) return;
           }
           await commitMutation(selection, mutation, {
             label: `Add keyframe at ${percentage}%`,
@@ -152,7 +153,7 @@ export function useGsapKeyframeOps({
           sdkDeps,
           { label: `Add keyframe at ${percentage}%` },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       return commitMutation(
         selection,
@@ -191,7 +192,7 @@ export function useGsapKeyframeOps({
               sdkDeps,
               { label: `Remove keyframe at ${percentage}%` },
             );
-            if (handled) return;
+            if (cutoverCommittedOrThrow(handled)) return;
           }
           await commitMutation(selection, mutation, {
             label: `Remove keyframe at ${percentage}%`,
@@ -272,7 +273,7 @@ export function useGsapKeyframeOps({
           sdkDeps,
           { label: "Convert to keyframes" },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       return commitMutation(
         selection,
@@ -301,7 +302,7 @@ export function useGsapKeyframeOps({
           sdkDeps,
           { label: "Remove all keyframes" },
         );
-        if (handled) return;
+        if (cutoverCommittedOrThrow(handled)) return;
       }
       commitMutationSafely(
         selection,