feat(studio): s7.5 — delete shadow scaffolding; keep cutover flag (dark launch) (#1462)

Removes the SDK shadow telemetry: STUDIO_SDK_SHADOW_ENABLED, sdkShadow.ts +
sdkShadowGsapFidelity/GsapKeyframe/Numeric and their tests, the runShadow*
call-sites across the GSAP/timeline hooks, and the onDomEditPersisted shadow
callback in useDomEditSession. Moves patchOpsToSdkEditOps into sdkCutover.ts.

KEEPS STUDIO_SDK_CUTOVER_ENABLED as a dark-launch kill-switch — default false,
enable per-environment via VITE_STUDIO_SDK_CUTOVER_ENABLED=true. shouldUseSdkCutover
stays flag-gated. The stack can merge with zero behavior change; cutover is
validated by flipping the flag, not by removing it.

Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com>

packages/studio/src/hooks/gsapScriptCommitTypes.ts

@@ -1,9 +1,6 @@
 import type { ParsedGsap } from "@hyperframes/core/gsap-parser";
-import type { Composition } from "@hyperframes/sdk";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import type { EditHistoryKind } from "../utils/editHistory";
-import type { ShadowGsapOp } from "../utils/sdkShadow";
-import type { ShadowKeyframeOp } from "../utils/sdkShadowGsapKeyframe";
 
 export interface MutationResult {
   ok: boolean;
@@ -28,10 +25,6 @@ export interface CommitMutationOptions {
    * (and under distinct keys) run concurrently as before.
    */
   serializeKey?: string;
-  /** Stage 7 Step 3b: typed SDK equivalent of this mutation for value-fidelity shadow. */
-  shadowGsapOp?: ShadowGsapOp;
-  /** Typed SDK equivalent of a keyframe mutation for keyframe value-fidelity shadow (gsap_keyframe). */
-  shadowKeyframeOp?: ShadowKeyframeOp;
 }
 
 export type CommitMutation = (
@@ -70,6 +63,4 @@ export interface GsapScriptCommitsParams {
   onCacheInvalidate: () => void;
   onFileContentChanged?: (path: string, content: string) => void;
   showToast: (message: string, tone?: "error" | "info") => void;
-  /** Stage 7 Step 3b: SDK session for shadow GSAP dispatch (server stays authoritative). */
-  sdkSession?: Composition | null;
 }

packages/studio/src/hooks/useDomEditSession.ts

@@ -1,4 +1,3 @@
-import type { Composition } from "@hyperframes/sdk";
 import type { TimelineElement } from "../player";
 import type { ImportedFontAsset } from "../components/editor/fontAssets";
 import type { EditHistoryKind } from "../utils/editHistory";
@@ -9,7 +8,6 @@ import { useAskAgentModal } from "./useAskAgentModal";
 import { useDomSelection } from "./useDomSelection";
 import { usePreviewInteraction } from "./usePreviewInteraction";
 import { useDomEditCommits } from "./useDomEditCommits";
-import { runShadowDispatch, runShadowDelete } from "../utils/sdkShadow";
 import { useGsapScriptCommits } from "./useGsapScriptCommits";
 import { useGsapCacheVersion } from "./useGsapTweenCache";
 import { useDomEditWiring } from "./useDomEditWiring";
@@ -60,8 +58,6 @@ 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 ──
@@ -100,7 +96,6 @@ export function useDomEditSession({
   openSourceForSelection,
   selectSidebarTab,
   getSidebarTab,
-  sdkSession,
 }: UseDomEditSessionParams) {
   void _setRefreshKey;
   void _readProjectFile;
@@ -194,7 +189,6 @@ export function useDomEditSession({
     onCacheInvalidate: bumpGsapCache,
     onFileContentChanged: updateEditingFileContent,
     showToast,
-    sdkSession,
   });
 
   // ── DOM commit handlers ──
@@ -234,10 +228,6 @@ export function useDomEditSession({
     clearDomSelection,
     refreshDomEditSelectionFromPreview,
     buildDomSelectionFromTarget,
-    onDomEditPersisted: sdkSession
-      ? (sel, ops) => runShadowDispatch(sdkSession, sel, ops)
-      : undefined,
-    onElementDeleted: sdkSession ? (sel) => runShadowDelete(sdkSession, sel.hfId) : undefined,
   });
 
   // ── Wiring: selection sync, GSAP cache, preview sync, selection handlers ──

packages/studio/src/hooks/useGsapAnimationOps.ts

@@ -1,8 +1,6 @@
 import { useCallback } from "react";
-import type { Composition } from "@hyperframes/sdk";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { roundTo3 } from "../utils/rounding";
-import { runShadowGsapTween, type ShadowGsapOp } from "../utils/sdkShadow";
 import {
   assignGsapTargetAutoIdIfNeeded,
   ensureElementAddressable,
@@ -15,8 +13,6 @@ interface GsapAnimationOpsParams {
   commitMutation: CommitMutation;
   commitMutationSafely: SafeGsapCommitMutation;
   showToast: (message: string, tone?: "error" | "info") => void;
-  /** Stage 7 Step 3b: SDK session for shadow GSAP dispatch (server stays authoritative). */
-  sdkSession?: Composition | null;
 }
 
 export function useGsapAnimationOps({
@@ -25,7 +21,6 @@ export function useGsapAnimationOps({
   commitMutation,
   commitMutationSafely,
   showToast,
-  sdkSession,
 }: GsapAnimationOpsParams) {
   const updateGsapMeta = useCallback(
     (
@@ -33,13 +28,6 @@ export function useGsapAnimationOps({
       animationId: string,
       updates: { duration?: number; ease?: string; position?: number },
     ) => {
-      // Shadow op (server animationId shares the SDK id-space): existence via
-      // runShadowGsapTween (live session) + value fidelity via the chokepoint.
-      const shadowGsapOp: ShadowGsapOp = {
-        kind: "set",
-        animationId,
-        properties: { duration: updates.duration, ease: updates.ease, position: updates.position },
-      };
       // coalesceKey groups rapid meta edits into one history entry. Request
       // serialization is now handled per-file at the commitMutation chokepoint
       // (useGsapScriptCommits), so no per-op serializeKey is needed here.
@@ -47,24 +35,21 @@ export function useGsapAnimationOps({
       commitMutationSafely(
         selection,
         { type: "update-meta", animationId, updates },
-        { label: "Edit GSAP animation", coalesceKey: metaKey, shadowGsapOp },
+        { label: "Edit GSAP animation", coalesceKey: metaKey },
       );
-      if (sdkSession) runShadowGsapTween(sdkSession, shadowGsapOp);
     },
-    [commitMutationSafely, sdkSession],
+    [commitMutationSafely],
   );
 
   const deleteGsapAnimation = useCallback(
     (selection: DomEditSelection, animationId: string) => {
-      const shadowGsapOp: ShadowGsapOp = { kind: "remove", animationId };
       commitMutationSafely(
         selection,
         { type: "delete", animationId, stripStudioEdits: true },
-        { label: "Delete GSAP animation", shadowGsapOp },
+        { label: "Delete GSAP animation" },
       );
-      if (sdkSession) runShadowGsapTween(sdkSession, shadowGsapOp);
     },
-    [commitMutationSafely, sdkSession],
+    [commitMutationSafely],
   );
 
   const deleteAllForSelector = useCallback(
@@ -78,8 +63,6 @@ export function useGsapAnimationOps({
     [commitMutation],
   );
 
-  // Pre-existing complexity (auto-id assignment + per-method defaults); this PR
-  // adds only a guarded shadow-op construction at the tail.
   const addGsapAnimation = useCallback(
     // fallow-ignore-next-line complexity
     async (
@@ -114,26 +97,6 @@ export function useGsapAnimationOps({
         fromTo: { x: 0, y: 0, opacity: 1 },
       };
 
-      // Shadow op (server stays authoritative). "set" has no SDK method, so it
-      // is not shadowed; otherwise: existence via runShadowGsapTween (live) +
-      // value fidelity via the chokepoint (shadowGsapOp in options).
-      const shadowGsapOp: ShadowGsapOp | undefined =
-        selection.hfId && method !== "set"
-          ? {
-              kind: "add",
-              target: selection.hfId,
-              tween: {
-                method,
-                position,
-                duration,
-                ease: "power2.out",
-                ...(method === "fromTo"
-                  ? { fromProperties: { opacity: 0 }, toProperties: toDefaults[method] }
-                  : { properties: toDefaults[method] ?? { opacity: 1 } }),
-              },
-            }
-          : undefined;
-
       await commitMutation(
         selection,
         {
@@ -146,12 +109,10 @@ export function useGsapAnimationOps({
           properties: toDefaults[method] ?? { opacity: 1 },
           fromProperties: method === "fromTo" ? { opacity: 0 } : undefined,
         },
-        { label: `Add GSAP ${method} animation`, shadowGsapOp },
+        { label: `Add GSAP ${method} animation` },
       );
-
-      if (sdkSession && shadowGsapOp) runShadowGsapTween(sdkSession, shadowGsapOp);
     },
-    [activeCompPath, commitMutation, projectIdRef, showToast, sdkSession],
+    [activeCompPath, commitMutation, projectIdRef, showToast],
   );
 
   return {

packages/studio/src/hooks/useGsapKeyframeOps.ts

@@ -1,6 +1,5 @@
 import { useCallback } from "react";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
-import type { ShadowKeyframeOp } from "../utils/sdkShadowGsapKeyframe";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { executeOptimistic } from "../utils/optimisticUpdate";
 import type { KeyframeCacheEntry } from "../player/store/playerStore";
@@ -59,13 +58,6 @@ export function useGsapKeyframeOps({
         percentage,
         properties: { [property]: value },
       };
-      // Shadow op (gsap_keyframe): SDK equivalent diffed via the commit chokepoint.
-      const shadowKeyframeOp: ShadowKeyframeOp = {
-        kind: "add",
-        animationId,
-        percentage,
-        properties: { [property]: value },
-      };
       void executeOptimisticKeyframeCacheUpdate({
         sourceFile,
         elementId: selection.id,
@@ -79,7 +71,6 @@ export function useGsapKeyframeOps({
           commitMutation(selection, mutation, {
             label: `Add keyframe at ${percentage}%`,
             softReload: true,
-            shadowKeyframeOp,
           }),
       }).catch((error) => {
         trackGsapSaveFailure(error, selection, mutation, `Add keyframe at ${percentage}%`);
@@ -95,16 +86,10 @@ export function useGsapKeyframeOps({
       percentage: number,
       properties: Record<string, number | string>,
     ) => {
-      const shadowKeyframeOp: ShadowKeyframeOp = {
-        kind: "add",
-        animationId,
-        percentage,
-        properties,
-      };
       return commitMutation(
         selection,
         { type: "add-keyframe", animationId, percentage, properties },
-        { label: `Add keyframe at ${percentage}%`, softReload: true, shadowKeyframeOp },
+        { label: `Add keyframe at ${percentage}%`, softReload: true },
       );
     },
     [commitMutation],
@@ -114,10 +99,6 @@ export function useGsapKeyframeOps({
     (selection: DomEditSelection, animationId: string, percentage: number) => {
       const sourceFile = selection.sourceFile || activeCompPath || "index.html";
       const mutation = { type: "remove-keyframe", animationId, percentage };
-      // Shadow op (gsap_keyframe): SDK has no %-based removeGsapKeyframe on main,
-      // so the runner resolves percentage → keyframeIndex against the pre-op
-      // script and no-ops on ambiguity (duplicate-percentage keyframes).
-      const shadowKeyframeOp: ShadowKeyframeOp = { kind: "remove", animationId, percentage };
       void executeOptimisticKeyframeCacheUpdate({
         sourceFile,
         elementId: selection.id,
@@ -131,7 +112,6 @@ export function useGsapKeyframeOps({
           commitMutation(selection, mutation, {
             label: `Remove keyframe at ${percentage}%`,
             softReload: true,
-            shadowKeyframeOp,
           }),
       }).catch((error) => {
         trackGsapSaveFailure(error, selection, mutation, `Remove keyframe at ${percentage}%`);

packages/studio/src/hooks/useGsapScriptCommits.ts

@@ -2,8 +2,6 @@ import { useCallback, useRef } from "react";
 import { findUnsafeMutationValues } from "@hyperframes/core/studio-api/finite-mutation";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { applySoftReload } from "../utils/gsapSoftReload";
-import { resolveGsapFidelityArgs, runShadowGsapFidelity } from "../utils/sdkShadowGsapFidelity";
-import { runShadowGsapKeyframeFidelity } from "../utils/sdkShadowGsapKeyframe";
 import { updateKeyframeCacheFromParsed } from "./gsapKeyframeCacheHelpers";
 import { createKeyedSerializer } from "./serializeByKey";
 import {
@@ -46,15 +44,12 @@ async function mutateGsapScript(
 
 // oxfmt-ignore
 // fallow-ignore-next-line complexity
-export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIframeRef, editHistory, domEditSaveTimestampRef, reloadPreview, onCacheInvalidate, onFileContentChanged, showToast, sdkSession }: GsapScriptCommitsParams) {
+export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIframeRef, editHistory, domEditSaveTimestampRef, reloadPreview, onCacheInvalidate, onFileContentChanged, showToast }: GsapScriptCommitsParams) {
   // Serializer for per-key commits (options.serializeKey). Keyed by
   // `gsap:${animationId}:meta`, it chains a meta commit onto the prior one for
-  // the same animationId so their POSTs can't interleave — which is what made
-  // the shadow fidelity diff pair an op with a stale server result and report
-  // false ease mismatches. Held in a ref so the chain survives re-renders.
+  // the same animationId so their POSTs can't interleave. Held in a ref so the
+  // chain survives re-renders.
   const serializerRef = useRef(createKeyedSerializer());
-  // Pre-existing complexity (server mutate + history + reload branches); this PR
-  // adds only a guarded shadow-fidelity dispatch.
   // fallow-ignore-next-line complexity
   const runCommit = useCallback(async (selection: DomEditSelection, mutation: Record<string, unknown>, options: CommitMutationOptions) => {
     const pid = projectIdRef.current;
@@ -76,28 +71,6 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
     }
     if (result.changed === false) return;
     domEditSaveTimestampRef.current = Date.now();
-    // Shadow value fidelity: diff the SDK's GSAP writer output against the
-    // server's, from the same pre-op file. Fire-and-forget; server authoritative.
-    // Meta-level ops carry shadowGsapOp (add / update-meta / delete via
-    // useGsapAnimationOps); keyframe ops carry shadowKeyframeOp (add/remove via
-    // useGsapKeyframeOps, handled by the gsap_keyframe block below). Per-property
-    // handlers (useGsapPropertyDebounce) don't synthesize one yet — deferred follow-up.
-    // scriptText is null when the composition has no GSAP script; nothing to diff.
-    const fidelityArgs = resolveGsapFidelityArgs(
-      sdkSession,
-      options.shadowGsapOp,
-      result.before,
-      result.scriptText,
-    );
-    if (fidelityArgs) {
-      void runShadowGsapFidelity(fidelityArgs.before, fidelityArgs.op, fidelityArgs.serverScript);
-    }
-    // Keyframe value fidelity (gsap_keyframe): same serialize-diff approach, but
-    // the SDK has no keyframe reader so there is no live-existence path — the diff
-    // is the only signal. Guarded on a live session + both scripts to diff.
-    if (sdkSession && options.shadowKeyframeOp && result.before != null && result.scriptText != null) {
-      void runShadowGsapKeyframeFidelity(result.before, options.shadowKeyframeOp, result.scriptText);
-    }
     if (result.before != null && result.after != null) {
       await editHistory.recordEdit({ label: options.label, kind: "manual", coalesceKey: options.coalesceKey, files: { [targetPath]: { before: result.before, after: result.after } } });
     }
@@ -111,12 +84,10 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
       reloadPreview();
     }
     onCacheInvalidate();
-  }, [projectIdRef, activeCompPath, previewIframeRef, editHistory, domEditSaveTimestampRef, reloadPreview, onCacheInvalidate, onFileContentChanged, showToast, sdkSession]);
+  }, [projectIdRef, activeCompPath, previewIframeRef, editHistory, domEditSaveTimestampRef, reloadPreview, onCacheInvalidate, onFileContentChanged, showToast]);
   // Every GSAP-script commit is a read-modify-write of one file. Overlapping
-  // commits to the SAME file (any op type, any animation) interleave server-side
-  // and make the shadow fidelity diff pair an op with a stale server result —
-  // the false ease/value mismatches this serializer exists to prevent. So
-  // serialize per target file by default; an explicit serializeKey overrides.
+  // commits to the SAME file (any op type, any animation) interleave server-side,
+  // so serialize per target file by default; an explicit serializeKey overrides.
   const commitMutation = useCallback(
     (selection: DomEditSelection, mutation: Record<string, unknown>, options: CommitMutationOptions) => {
       const file = selection.sourceFile || activeCompPath || "index.html";
@@ -128,7 +99,7 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
   const trackGsapSaveFailure = useGsapSaveFailureTelemetry(activeCompPath);
   const commitMutationSafely = useSafeGsapCommitMutation(commitMutation, trackGsapSaveFailure, showToast);
   const propertyOps = useGsapPropertyDebounce(commitMutationSafely);
-  const animationOps = useGsapAnimationOps({ projectIdRef, activeCompPath, commitMutation, commitMutationSafely, showToast, sdkSession });
+  const animationOps = useGsapAnimationOps({ projectIdRef, activeCompPath, commitMutation, commitMutationSafely, showToast });
   const keyframeOps = useGsapKeyframeOps({ activeCompPath, commitMutation, commitMutationSafely, trackGsapSaveFailure });
   const arcPathOps = useGsapArcPathOps(commitMutationSafely);
   return { commitMutation, ...propertyOps, ...animationOps, ...keyframeOps, ...arcPathOps };

packages/studio/src/hooks/useTimelineEditing.ts

@@ -1,11 +1,7 @@
 // Pre-existing-complex timeline hook (DOM patch + GSAP position shift/scale +
-// playback-start resolution); this PR adds guarded shadow-timing dispatches in
-// the move/resize .then() chains, which nudges several callbacks over the CC
-// threshold. The added branches are telemetry-only.
+// playback-start resolution).
 // fallow-ignore-file complexity
 import { useCallback, useRef } from "react";
-import type { Composition } from "@hyperframes/sdk";
-import { runShadowDelete, runShadowTiming } from "../utils/sdkShadow";
 import type { TimelineElement } from "../player";
 import { usePlayerStore } from "../player";
 import { useRazorSplit } from "./useRazorSplit";
@@ -60,8 +56,6 @@ interface UseTimelineEditingOptions {
   pendingTimelineEditPathRef: React.MutableRefObject<Set<string>>;
   uploadProjectFiles: (files: Iterable<File>, dir?: string) => Promise<string[]>;
   isRecordingRef?: React.RefObject<boolean>;
-  /** Stage 7 Step 3b: SDK session for shadow timing dispatch (server stays authoritative). */
-  sdkSession?: Composition | null;
 }
 
 // ── Hook ──
@@ -79,7 +73,6 @@ export function useTimelineEditing({
   pendingTimelineEditPathRef,
   uploadProjectFiles,
   isRecordingRef,
-  sdkSession,
 }: UseTimelineEditingOptions) {
   const projectIdRef = useRef(projectId);
   projectIdRef.current = projectId;
@@ -148,11 +141,6 @@ export function useTimelineEditing({
           value: String(updates.track),
         });
       }).then(() => {
-        if (sdkSession)
-          runShadowTiming(sdkSession, element.hfId, {
-            start: updates.start,
-            trackIndex: updates.track,
-          });
         const pid = projectIdRef.current;
         if (delta !== 0 && element.domId && pid) {
           return shiftGsapPositions(pid, filePath, element.domId, delta)
@@ -161,7 +149,7 @@ export function useTimelineEditing({
         }
       });
     },
-    [previewIframeRef, enqueueEdit, activeCompPath, reloadPreview, sdkSession],
+    [previewIframeRef, enqueueEdit, activeCompPath, reloadPreview],
   );
 
   const handleTimelineElementResize = useCallback(
@@ -205,11 +193,6 @@ export function useTimelineEditing({
         }
         return patched;
       }).then(() => {
-        if (sdkSession)
-          runShadowTiming(sdkSession, element.hfId, {
-            start: updates.start,
-            duration: updates.duration,
-          });
         const pid = projectIdRef.current;
         if (timingChanged && element.domId && pid) {
           return scaleGsapPositions(
@@ -227,7 +210,7 @@ export function useTimelineEditing({
         return reloadPreview();
       });
     },
-    [previewIframeRef, enqueueEdit, activeCompPath, reloadPreview, sdkSession],
+    [previewIframeRef, enqueueEdit, activeCompPath, reloadPreview],
   );
 
   const handleTimelineElementDelete = useCallback(
@@ -288,7 +271,6 @@ export function useTimelineEditing({
           );
         usePlayerStore.getState().setSelectedElementId(null);
         reloadPreview();
-        if (sdkSession) runShadowDelete(sdkSession, element.hfId);
         showToast(`Deleted ${label}. Use Undo to restore it.`, "info");
       } catch (error) {
         const message = error instanceof Error ? error.message : "Failed to delete timeline clip";
@@ -304,7 +286,6 @@ export function useTimelineEditing({
       domEditSaveTimestampRef,
       reloadPreview,
       isRecordingRef,
-      sdkSession,
     ],
   );