feat(studio): route GSAP tween add/update/delete through SDK (§3.5 PR1)

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

Author: vanceingalls

packages/studio/src/hooks/gsapScriptCommitTypes.ts

@@ -70,6 +70,7 @@ 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). */
+  /** Stage 7 §3.5: SDK session for routing GSAP tween ops through addGsapTween/setGsapTween/removeGsapTween. */
   sdkSession?: Composition | null;
+  writeProjectFile?: (path: string, content: string) => Promise<void>;
 }

packages/studio/src/hooks/useDomEditSession.ts

@@ -194,6 +194,7 @@ export function useDomEditSession({
     onFileContentChanged: updateEditingFileContent,
     showToast,
     sdkSession,
+    writeProjectFile,
   });
 
   // ── DOM commit handlers ──

packages/studio/src/hooks/useGsapAnimationOps.ts

@@ -2,14 +2,30 @@ 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 { sdkGsapTweenPersist } from "../utils/sdkCutover";
 import {
   assignGsapTargetAutoIdIfNeeded,
   ensureElementAddressable,
 } from "./gsapScriptCommitHelpers";
 import type { CommitMutation, SafeGsapCommitMutation } from "./gsapScriptCommitTypes";
+import type { EditHistoryKind } from "../utils/editHistory";
 
-interface GsapAnimationOpsParams {
+interface SdkAnimationDeps {
+  sdkSession?: Composition | null;
+  writeProjectFile?: (path: string, content: string) => Promise<void>;
+  editHistory?: {
+    recordEdit: (entry: {
+      label: string;
+      kind: EditHistoryKind;
+      coalesceKey?: string;
+      files: Record<string, { before: string; after: string }>;
+    }) => Promise<void>;
+  };
+  reloadPreview?: () => void;
+  domEditSaveTimestampRef?: React.MutableRefObject<number>;
+}
+
+interface GsapAnimationOpsParams extends SdkAnimationDeps {
   projectIdRef: React.MutableRefObject<string | null>;
   activeCompPath: string | null;
   commitMutation: CommitMutation;
@@ -26,49 +42,92 @@ export function useGsapAnimationOps({
   commitMutationSafely,
   showToast,
   sdkSession,
+  writeProjectFile,
+  editHistory,
+  reloadPreview,
+  domEditSaveTimestampRef,
 }: GsapAnimationOpsParams) {
   const updateGsapMeta = useCallback(
-    (
+    async (
       selection: DomEditSelection,
       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.
-      const metaKey = `gsap:${animationId}:meta`;
+      if (
+        sdkSession &&
+        writeProjectFile &&
+        editHistory &&
+        reloadPreview &&
+        domEditSaveTimestampRef
+      ) {
+        const targetPath = selection.sourceFile || activeCompPath || "index.html";
+        const handled = await sdkGsapTweenPersist(
+          targetPath,
+          { kind: "set", animationId, properties: updates },
+          sdkSession,
+          { editHistory, writeProjectFile, reloadPreview, domEditSaveTimestampRef },
+          { label: "Edit GSAP animation", coalesceKey: `gsap:${animationId}:meta` },
+        );
+        if (handled) return;
+      }
       commitMutationSafely(
         selection,
         { type: "update-meta", animationId, updates },
-        { label: "Edit GSAP animation", coalesceKey: metaKey, shadowGsapOp },
+        { label: "Edit GSAP animation", coalesceKey: `gsap:${animationId}:meta` },
       );
       if (sdkSession) runShadowGsapTween(sdkSession, shadowGsapOp);
     },
-    [commitMutationSafely, sdkSession],
+    [
+      commitMutationSafely,
+      activeCompPath,
+      sdkSession,
+      writeProjectFile,
+      editHistory,
+      reloadPreview,
+      domEditSaveTimestampRef,
+    ],
   );
 
   const deleteGsapAnimation = useCallback(
-    (selection: DomEditSelection, animationId: string) => {
-      const shadowGsapOp: ShadowGsapOp = { kind: "remove", animationId };
+    async (selection: DomEditSelection, animationId: string) => {
+      if (
+        sdkSession &&
+        writeProjectFile &&
+        editHistory &&
+        reloadPreview &&
+        domEditSaveTimestampRef
+      ) {
+        const targetPath = selection.sourceFile || activeCompPath || "index.html";
+        const handled = await sdkGsapTweenPersist(
+          targetPath,
+          { kind: "remove", animationId },
+          sdkSession,
+          { editHistory, writeProjectFile, reloadPreview, domEditSaveTimestampRef },
+          { label: "Delete GSAP animation" },
+        );
+        if (handled) return;
+      }
       commitMutationSafely(
         selection,
         { type: "delete", animationId, stripStudioEdits: true },
         { label: "Delete GSAP animation", shadowGsapOp },
       );
       if (sdkSession) runShadowGsapTween(sdkSession, shadowGsapOp);
     },
-    [commitMutationSafely, sdkSession],
+    [
+      commitMutationSafely,
+      activeCompPath,
+      sdkSession,
+      writeProjectFile,
+      editHistory,
+      reloadPreview,
+      domEditSaveTimestampRef,
+    ],
   );
 
   const deleteAllForSelector = useCallback(
     (selection: DomEditSelection, targetSelector: string) => {
+      // ponytail: no SDK op for delete-all-for-selector; stays server-authoritative
       void commitMutation(
         selection,
         { type: "delete-all-for-selector", targetSelector },
@@ -78,8 +137,7 @@ 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.
+  // fallow-ignore-next-line complexity
   const addGsapAnimation = useCallback(
     // fallow-ignore-next-line complexity
     async (
@@ -114,25 +172,34 @@ 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;
+      // SDK path: addGsapTween only supports from/to/fromTo; "set" stays server-side
+      if (
+        method !== "set" &&
+        selection.hfId &&
+        sdkSession &&
+        writeProjectFile &&
+        editHistory &&
+        reloadPreview &&
+        domEditSaveTimestampRef
+      ) {
+        const targetPath = selection.sourceFile || activeCompPath || "index.html";
+        const spec = {
+          method: method as "to" | "from" | "fromTo",
+          position,
+          duration,
+          ease: "power2.out" as const,
+          properties: toDefaults[method] ?? { opacity: 1 },
+          fromProperties: method === "fromTo" ? { opacity: 0 } : undefined,
+        };
+        const handled = await sdkGsapTweenPersist(
+          targetPath,
+          { kind: "add", target: selection.hfId, spec },
+          sdkSession,
+          { editHistory, writeProjectFile, reloadPreview, domEditSaveTimestampRef },
+          { label: `Add GSAP ${method} animation` },
+        );
+        if (handled) return;
+      }
 
       await commitMutation(
         selection,
@@ -151,7 +218,17 @@ export function useGsapAnimationOps({
 
       if (sdkSession && shadowGsapOp) runShadowGsapTween(sdkSession, shadowGsapOp);
     },
-    [activeCompPath, commitMutation, projectIdRef, showToast, sdkSession],
+    [
+      activeCompPath,
+      commitMutation,
+      projectIdRef,
+      showToast,
+      sdkSession,
+      writeProjectFile,
+      editHistory,
+      reloadPreview,
+      domEditSaveTimestampRef,
+    ],
   );
 
   return {