@hyperframes/studio 0.6.96 → 0.6.98

package/src/hooks/useGsapAwareEditing.ts

@@ -0,0 +1,242 @@
+/**
+ * GSAP-aware move/resize/rotation wrappers that intercept geometry commits
+ * for animated elements and route them through script mutation instead of
+ * CSS patching. Also exposes the animated-property commit, arc-path ops,
+ * and the thin `commitMutation` facade.
+ *
+ * Extracted from useDomEditSession to isolate the GSAP intercept routing
+ * from the rest of the editing orchestration.
+ */
+import { useCallback } from "react";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { STUDIO_GSAP_DRAG_INTERCEPT_ENABLED } from "../components/editor/manualEditingAvailability";
+import { GSAP_CSS_FALLBACK_BLOCKED_MESSAGE } from "./useDomGeometryCommits";
+import {
+  tryGsapDragIntercept,
+  tryGsapResizeIntercept,
+  tryGsapRotationIntercept,
+} from "./gsapRuntimeBridge";
+import { useAnimatedPropertyCommit } from "./useAnimatedPropertyCommit";
+import type { CommitMutation } from "./gsapScriptCommitTypes";
+
+export interface UseGsapAwareEditingParams {
+  domEditSelection: DomEditSelection | null;
+  selectedGsapAnimations: GsapAnimation[];
+  gsapCommitMutation: CommitMutation | null;
+  previewIframeRef: React.RefObject<HTMLIFrameElement | null>;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  bumpGsapCache: () => void;
+  makeFetchFallback: (selection: DomEditSelection) => () => Promise<GsapAnimation[]>;
+  trackGsapInteractionFailure: (
+    error: unknown,
+    selection: DomEditSelection,
+    mutationType: string,
+    label: string,
+  ) => void;
+  // DOM fallbacks (from useDomEditCommits)
+  handleDomPathOffsetCommit: (
+    selection: DomEditSelection,
+    next: { x: number; y: number },
+  ) => Promise<void>;
+  handleDomBoxSizeCommit: (
+    selection: DomEditSelection,
+    next: { width: number; height: number },
+  ) => Promise<void>;
+  handleDomRotationCommit: (selection: DomEditSelection, next: { angle: number }) => Promise<void>;
+  // GSAP script commit ops (from useGsapScriptCommits)
+  addGsapAnimation: (
+    sel: DomEditSelection,
+    method: "to" | "from" | "set" | "fromTo",
+    time?: number,
+  ) => Promise<void>;
+  convertToKeyframes: (sel: DomEditSelection, animId: string) => void;
+  setArcPath: (
+    sel: DomEditSelection,
+    animId: string,
+    config: {
+      enabled: boolean;
+      autoRotate?: boolean | number;
+      segments?: Array<{
+        curviness: number;
+        cp1?: { x: number; y: number };
+        cp2?: { x: number; y: number };
+      }>;
+    },
+  ) => void;
+  updateArcSegment: (
+    sel: DomEditSelection,
+    animId: string,
+    segmentIndex: number,
+    update: {
+      curviness?: number;
+      cp1?: { x: number; y: number };
+      cp2?: { x: number; y: number };
+    },
+  ) => void;
+}
+
+export function useGsapAwareEditing({
+  domEditSelection,
+  selectedGsapAnimations,
+  gsapCommitMutation,
+  previewIframeRef,
+  showToast,
+  bumpGsapCache,
+  makeFetchFallback,
+  trackGsapInteractionFailure,
+  handleDomPathOffsetCommit,
+  handleDomBoxSizeCommit,
+  handleDomRotationCommit,
+  addGsapAnimation,
+  convertToKeyframes,
+  setArcPath,
+  updateArcSegment,
+}: UseGsapAwareEditingParams) {
+  // ── GSAP-aware geometry commits ──
+
+  const handleGsapAwarePathOffsetCommit = useCallback(
+    async (selection: DomEditSelection, next: { x: number; y: number }) => {
+      const hasGsapAnims = selectedGsapAnimations.length > 0;
+      if (hasGsapAnims && !STUDIO_GSAP_DRAG_INTERCEPT_ENABLED) {
+        showToast(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE, "error");
+        throw new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
+      }
+      if (STUDIO_GSAP_DRAG_INTERCEPT_ENABLED && gsapCommitMutation) {
+        try {
+          const handled = await tryGsapDragIntercept(
+            selection,
+            next,
+            selectedGsapAnimations,
+            previewIframeRef.current,
+            gsapCommitMutation,
+            makeFetchFallback(selection),
+          );
+          if (handled) return;
+        } catch (error) {
+          trackGsapInteractionFailure(error, selection, "drag", "Move animated layer");
+          throw error;
+        }
+      }
+      return handleDomPathOffsetCommit(selection, next);
+    },
+    [
+      handleDomPathOffsetCommit,
+      selectedGsapAnimations,
+      gsapCommitMutation,
+      previewIframeRef,
+      makeFetchFallback,
+      trackGsapInteractionFailure,
+      showToast,
+    ],
+  );
+
+  const handleGsapAwareBoxSizeCommit = useCallback(
+    async (selection: DomEditSelection, next: { width: number; height: number }) => {
+      if (STUDIO_GSAP_DRAG_INTERCEPT_ENABLED && gsapCommitMutation) {
+        try {
+          const handled = await tryGsapResizeIntercept(
+            selection,
+            next,
+            selectedGsapAnimations,
+            previewIframeRef.current,
+            gsapCommitMutation,
+            makeFetchFallback(selection),
+          );
+          if (handled) return;
+        } catch (error) {
+          trackGsapInteractionFailure(error, selection, "resize", "Resize animated layer");
+          throw error;
+        }
+      }
+      return handleDomBoxSizeCommit(selection, next);
+    },
+    [
+      handleDomBoxSizeCommit,
+      selectedGsapAnimations,
+      gsapCommitMutation,
+      previewIframeRef,
+      makeFetchFallback,
+      trackGsapInteractionFailure,
+    ],
+  );
+
+  const handleGsapAwareRotationCommit = useCallback(
+    async (selection: DomEditSelection, next: { angle: number }) => {
+      if (STUDIO_GSAP_DRAG_INTERCEPT_ENABLED && gsapCommitMutation) {
+        try {
+          const handled = await tryGsapRotationIntercept(
+            selection,
+            next.angle,
+            selectedGsapAnimations,
+            previewIframeRef.current,
+            gsapCommitMutation,
+            makeFetchFallback(selection),
+          );
+          if (handled) return;
+        } catch (error) {
+          trackGsapInteractionFailure(error, selection, "rotation", "Rotate animated layer");
+          throw error;
+        }
+      }
+      return handleDomRotationCommit(selection, next);
+    },
+    [
+      handleDomRotationCommit,
+      selectedGsapAnimations,
+      gsapCommitMutation,
+      previewIframeRef,
+      makeFetchFallback,
+      trackGsapInteractionFailure,
+    ],
+  );
+
+  // ── Animated property commit ──
+
+  const commitAnimatedProperty = useAnimatedPropertyCommit({
+    selectedGsapAnimations,
+    gsapCommitMutation,
+    addGsapAnimation: (sel, method, time) => addGsapAnimation(sel, method, time),
+    convertToKeyframes: (sel, animId) => convertToKeyframes(sel, animId),
+    previewIframeRef,
+    bumpGsapCache,
+  });
+
+  // ── Arc path wrappers ──
+
+  const handleSetArcPath = useCallback(
+    (animId: string, config: Parameters<typeof setArcPath>[2]) => {
+      if (!domEditSelection) return;
+      setArcPath(domEditSelection, animId, config);
+    },
+    [domEditSelection, setArcPath],
+  );
+
+  const handleUpdateArcSegment = useCallback(
+    (animId: string, segmentIndex: number, update: Parameters<typeof updateArcSegment>[3]) => {
+      if (!domEditSelection) return;
+      updateArcSegment(domEditSelection, animId, segmentIndex, update);
+    },
+    [domEditSelection, updateArcSegment],
+  );
+
+  // ── Thin commitMutation facade ──
+
+  const commitMutation = useCallback(
+    async (mutation: Record<string, unknown>, options: { label: string; softReload?: boolean }) => {
+      if (!domEditSelection) return;
+      await gsapCommitMutation?.(domEditSelection, mutation, options);
+    },
+    [domEditSelection, gsapCommitMutation],
+  );
+
+  return {
+    handleGsapAwarePathOffsetCommit,
+    handleGsapAwareBoxSizeCommit,
+    handleGsapAwareRotationCommit,
+    commitAnimatedProperty,
+    handleSetArcPath,
+    handleUpdateArcSegment,
+    commitMutation,
+  };
+}

package/src/hooks/useGsapKeyframeOps.ts

@@ -0,0 +1,167 @@
+import { useCallback } from "react";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { executeOptimistic } from "../utils/optimisticUpdate";
+import type { KeyframeCacheEntry } from "../player/store/playerStore";
+import { commitKeyframeAtTimeImpl } from "./gsapKeyframeCommit";
+import { readKeyframeSnapshot, writeKeyframeCache } from "./gsapKeyframeCacheHelpers";
+import type {
+  CommitMutation,
+  SafeGsapCommitMutation,
+  TrackGsapSaveFailure,
+} from "./gsapScriptCommitTypes";
+
+function executeOptimisticKeyframeCacheUpdate(options: {
+  sourceFile: string;
+  elementId: string | null | undefined;
+  apply: (entry: KeyframeCacheEntry) => KeyframeCacheEntry;
+  persist: () => Promise<void>;
+}): Promise<void> {
+  return executeOptimistic<KeyframeCacheEntry | undefined>({
+    apply: () => {
+      const prev = readKeyframeSnapshot(options.sourceFile, options.elementId);
+      if (prev) writeKeyframeCache(options.sourceFile, options.elementId, options.apply(prev));
+      return prev;
+    },
+    persist: options.persist,
+    rollback: (prev) => {
+      writeKeyframeCache(options.sourceFile, options.elementId, prev);
+    },
+  });
+}
+
+interface GsapKeyframeOpsParams {
+  activeCompPath: string | null;
+  commitMutation: CommitMutation;
+  commitMutationSafely: SafeGsapCommitMutation;
+  trackGsapSaveFailure: TrackGsapSaveFailure;
+}
+
+export function useGsapKeyframeOps({
+  activeCompPath,
+  commitMutation,
+  commitMutationSafely,
+  trackGsapSaveFailure,
+}: GsapKeyframeOpsParams) {
+  const addKeyframe = useCallback(
+    (
+      selection: DomEditSelection,
+      animationId: string,
+      percentage: number,
+      property: string,
+      value: number | string,
+    ) => {
+      const sourceFile = selection.sourceFile || activeCompPath || "index.html";
+      const mutation = {
+        type: "add-keyframe",
+        animationId,
+        percentage,
+        properties: { [property]: value },
+      };
+      void executeOptimisticKeyframeCacheUpdate({
+        sourceFile,
+        elementId: selection.id,
+        apply: (prev) => ({
+          ...prev,
+          keyframes: [...prev.keyframes, { percentage, properties: { [property]: value } }].sort(
+            (a, b) => a.percentage - b.percentage,
+          ),
+        }),
+        persist: () =>
+          commitMutation(selection, mutation, {
+            label: `Add keyframe at ${percentage}%`,
+            softReload: true,
+          }),
+      }).catch((error) => {
+        trackGsapSaveFailure(error, selection, mutation, `Add keyframe at ${percentage}%`);
+      });
+    },
+    [activeCompPath, commitMutation, trackGsapSaveFailure],
+  );
+
+  const addKeyframeBatch = useCallback(
+    (
+      selection: DomEditSelection,
+      animationId: string,
+      percentage: number,
+      properties: Record<string, number | string>,
+    ) => {
+      return commitMutation(
+        selection,
+        { type: "add-keyframe", animationId, percentage, properties },
+        { label: `Add keyframe at ${percentage}%`, softReload: true },
+      );
+    },
+    [commitMutation],
+  );
+
+  const removeKeyframe = useCallback(
+    (selection: DomEditSelection, animationId: string, percentage: number) => {
+      const sourceFile = selection.sourceFile || activeCompPath || "index.html";
+      const mutation = { type: "remove-keyframe", animationId, percentage };
+      void executeOptimisticKeyframeCacheUpdate({
+        sourceFile,
+        elementId: selection.id,
+        apply: (prev) => ({
+          ...prev,
+          keyframes: prev.keyframes.filter(
+            (kf) => Math.abs((kf.tweenPercentage ?? kf.percentage) - percentage) > 0.2,
+          ),
+        }),
+        persist: () =>
+          commitMutation(selection, mutation, {
+            label: `Remove keyframe at ${percentage}%`,
+            softReload: true,
+          }),
+      }).catch((error) => {
+        trackGsapSaveFailure(error, selection, mutation, `Remove keyframe at ${percentage}%`);
+      });
+    },
+    [activeCompPath, commitMutation, trackGsapSaveFailure],
+  );
+
+  const convertToKeyframes = useCallback(
+    (
+      selection: DomEditSelection,
+      animationId: string,
+      resolvedFromValues?: Record<string, number | string>,
+    ) => {
+      return commitMutation(
+        selection,
+        { type: "convert-to-keyframes", animationId, resolvedFromValues },
+        { label: "Convert to keyframes" },
+      );
+    },
+    [commitMutation],
+  );
+
+  const removeAllKeyframes = useCallback(
+    (selection: DomEditSelection, animationId: string) => {
+      commitMutationSafely(
+        selection,
+        { type: "remove-all-keyframes", animationId },
+        { label: "Remove all keyframes", softReload: true },
+      );
+    },
+    [commitMutationSafely],
+  );
+
+  const commitKeyframeAtTime = useCallback(
+    (
+      selection: DomEditSelection,
+      absoluteTime: number,
+      animations: GsapAnimation[],
+      properties: Record<string, number | string>,
+    ) => commitKeyframeAtTimeImpl(selection, absoluteTime, animations, properties, commitMutation),
+    [commitMutation],
+  );
+
+  return {
+    addKeyframe,
+    addKeyframeBatch,
+    removeKeyframe,
+    convertToKeyframes,
+    removeAllKeyframes,
+    commitKeyframeAtTime,
+  };
+}

package/src/hooks/useGsapPropertyDebounce.ts

@@ -0,0 +1,135 @@
+import { useCallback, useEffect, useRef } from "react";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { PROPERTY_DEFAULTS } from "./gsapScriptCommitHelpers";
+import type { SafeGsapCommitMutation } from "./gsapScriptCommitTypes";
+
+const DEBOUNCE_MS = 150;
+
+export function useGsapPropertyDebounce(commitMutationSafely: SafeGsapCommitMutation) {
+  const pendingPropertyEditRef = useRef<{
+    selection: DomEditSelection;
+    animationId: string;
+    property: string;
+    value: number | string;
+  } | null>(null);
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const flushPendingPropertyEdit = useCallback(() => {
+    const pending = pendingPropertyEditRef.current;
+    if (!pending) return;
+    pendingPropertyEditRef.current = null;
+    const { selection, animationId, property, value } = pending;
+    commitMutationSafely(
+      selection,
+      { type: "update-property", animationId, property, value },
+      {
+        label: `Edit GSAP ${property}`,
+        coalesceKey: `gsap:${animationId}:${property}`,
+        softReload: true,
+      },
+    );
+  }, [commitMutationSafely]);
+
+  const updateGsapProperty = useCallback(
+    (
+      selection: DomEditSelection,
+      animationId: string,
+      property: string,
+      value: number | string,
+    ) => {
+      pendingPropertyEditRef.current = { selection, animationId, property, value };
+      if (debounceTimerRef.current) clearTimeout(debounceTimerRef.current);
+      debounceTimerRef.current = setTimeout(flushPendingPropertyEdit, DEBOUNCE_MS);
+    },
+    [flushPendingPropertyEdit],
+  );
+
+  useEffect(() => {
+    return () => {
+      if (debounceTimerRef.current) clearTimeout(debounceTimerRef.current);
+      flushPendingPropertyEdit();
+    };
+  }, [flushPendingPropertyEdit]);
+
+  const addGsapProperty = useCallback(
+    (selection: DomEditSelection, animationId: string, property: string) => {
+      let defaultValue = PROPERTY_DEFAULTS[property] ?? 0;
+      const el = selection.element;
+      if (property === "width" || property === "height") {
+        const rect = el.getBoundingClientRect();
+        defaultValue = Math.round(property === "width" ? rect.width : rect.height);
+      } else if (property === "opacity" || property === "autoAlpha") {
+        const cs = el.ownerDocument.defaultView?.getComputedStyle(el);
+        defaultValue = cs ? Number.parseFloat(cs.opacity) || 1 : 1;
+      }
+      commitMutationSafely(
+        selection,
+        { type: "add-property", animationId, property, defaultValue },
+        { label: `Add GSAP ${property}` },
+      );
+    },
+    [commitMutationSafely],
+  );
+
+  const removeGsapProperty = useCallback(
+    (selection: DomEditSelection, animationId: string, property: string) => {
+      commitMutationSafely(
+        selection,
+        { type: "remove-property", animationId, property },
+        { label: `Remove GSAP ${property}` },
+      );
+    },
+    [commitMutationSafely],
+  );
+
+  const updateGsapFromProperty = useCallback(
+    (
+      selection: DomEditSelection,
+      animationId: string,
+      property: string,
+      value: number | string,
+    ) => {
+      commitMutationSafely(
+        selection,
+        { type: "update-from-property", animationId, property, value },
+        {
+          label: `Edit GSAP from-${property}`,
+          coalesceKey: `gsap:${animationId}:from:${property}`,
+        },
+      );
+    },
+    [commitMutationSafely],
+  );
+
+  const addGsapFromProperty = useCallback(
+    (selection: DomEditSelection, animationId: string, property: string) => {
+      const defaultValue = PROPERTY_DEFAULTS[property] ?? 0;
+      commitMutationSafely(
+        selection,
+        { type: "add-from-property", animationId, property, defaultValue },
+        { label: `Add GSAP from-${property}` },
+      );
+    },
+    [commitMutationSafely],
+  );
+
+  const removeGsapFromProperty = useCallback(
+    (selection: DomEditSelection, animationId: string, property: string) => {
+      commitMutationSafely(
+        selection,
+        { type: "remove-from-property", animationId, property },
+        { label: `Remove GSAP from-${property}` },
+      );
+    },
+    [commitMutationSafely],
+  );
+
+  return {
+    updateGsapProperty,
+    addGsapProperty,
+    removeGsapProperty,
+    updateGsapFromProperty,
+    addGsapFromProperty,
+    removeGsapFromProperty,
+  };
+}