@hyperframes/studio 0.7.90 → 0.7.93

package/src/hooks/gsapRuntimeBridge.ts

@@ -26,18 +26,23 @@ import {
 import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
 import { resolveTweenDuration } from "../utils/globalTimeCompiler";
 import type { GsapDragCommitCallbacks } from "./gsapDragCommit";
-import { isInstantHold, selectorFromSelection } from "./gsapShared";
+import { isInstantHold, selectorFromSelection, writeTargetSelector } from "./gsapShared";
 import {
   findGsapPositionAnimation,
   pickClosestToPlayhead,
   readGsapPositionFromIframe,
 } from "./gsapPositionDetection";
 import { hasNonHoldTweenForElement } from "./gsapRuntimeKeyframes";
+import {
+  animationWritesAnyProperty,
+  directEditOutcomeForProperties,
+  type GsapEditOutcome,
+} from "./gsapEditOutcome";
 
 // Position channels — used to scope the "has a live position tween?" check so a
 // sibling rotation/scale animation never forces a static position hold into the
 // keyframe branch (which corrupts it into a frozen duration-0 keyframed tween).
-export const POSITION_CHANNELS = [
+export const POSITION_CHANNELS: string[] = [
   "x",
   "y",
   "xPercent",
@@ -50,6 +55,10 @@ export const POSITION_CHANNELS = [
   "translateX",
   "translateY",
 ];
+const POSITION_CHANNEL_SET = new Set<string>(POSITION_CHANNELS);
+
+const ROTATION_CHANNELS: string[] = ["rotation", "rotationX", "rotationY", "rotationZ"];
+const ROTATION_CHANNEL_SET = new Set<string>(ROTATION_CHANNELS);
 
 // ── Property-group tween resolution ───────────────────────────────────────
 
@@ -121,11 +130,40 @@ export type { GsapDragCommitCallbacks };
 /**
  * Attempt to handle a drag commit via the GSAP script mutation path.
  *
- * Returns a Promise that resolves to true if the drag was handled via GSAP
- * (caller should skip the CSS path), or false if no GSAP position animation
- * exists.
+ * Returns an explicit persisted/blocked outcome. Callers must reject blocked
+ * outcomes so the gesture layer restores its runtime and overlay drafts.
  */
 // fallow-ignore-next-line complexity
+async function preflightGsapDragIntercept(
+  selection: DomEditSelection,
+  animations: GsapAnimation[],
+  iframe: HTMLIFrameElement | null,
+  fetchFallbackAnimations?: () => Promise<GsapAnimation[]>,
+): Promise<GsapEditOutcome> {
+  const selector = selectorFromSelection(selection);
+  if (!selector) return { status: "blocked", reason: "no-selector" };
+
+  const fetchedAnimations = fetchFallbackAnimations ? await fetchFallbackAnimations() : [];
+  // The fallback API currently represents both a definitive empty parse and an
+  // exhausted fetch failure as `[]`. Keep the selected cache in the preflight
+  // set as well: ignoring it would let a transient fetch failure bypass helper /
+  // runtime-source ownership and reach a destructive split or property write.
+  const allKnownAnimations = [...animations, ...fetchedAnimations];
+  const editability = directEditOutcomeForProperties(allKnownAnimations, POSITION_CHANNEL_SET);
+  if (editability.status === "blocked") return editability;
+  const sourceAnimations = fetchedAnimations.length > 0 ? fetchedAnimations : animations;
+  const posAnim = findGsapPositionAnimation(sourceAnimations, selector);
+  const hasLivePosition = hasNonHoldTweenForElement(iframe, selector, undefined, POSITION_CHANNELS);
+
+  if (hasLivePosition && !posAnim) {
+    return { status: "blocked", reason: "source-uneditable" };
+  }
+  if (!posAnim && !writeTargetSelector(selection)) {
+    return { status: "blocked", reason: "no-selector" };
+  }
+  return { status: "persisted" };
+}
+
 export async function tryGsapDragIntercept(
   selection: DomEditSelection,
   offset: { x: number; y: number },
@@ -133,12 +171,20 @@ export async function tryGsapDragIntercept(
   iframe: HTMLIFrameElement | null,
   commitMutation: GsapDragCommitCallbacks["commitMutation"],
   fetchFallbackAnimations?: () => Promise<GsapAnimation[]>,
-  options?: { altKey?: boolean },
-): Promise<boolean> {
-  const selector = selectorFromSelection(selection);
-  if (!selector) {
-    return false;
+  options?: { altKey?: boolean; preflightOnly?: boolean; preflightPassed?: boolean },
+): Promise<GsapEditOutcome> {
+  if (!options?.preflightPassed) {
+    const preflight = await preflightGsapDragIntercept(
+      selection,
+      animations,
+      iframe,
+      fetchFallbackAnimations,
+    );
+    if (preflight.status === "blocked" || options?.preflightOnly) return preflight;
   }
+  const selector = selectorFromSelection(selection);
+  // The preflight above proves this; retain a defensive result for DOM churn.
+  if (!selector) return { status: "blocked", reason: "no-selector" };
 
   // Self-heal: enforce a single position write BEFORE committing. A corrupted
   // file can carry 2+ conflicting position writes for one selector (e.g. a
@@ -218,11 +264,11 @@ export async function tryGsapDragIntercept(
       commitMutation,
       fetchAnimations: fetchFallbackAnimations,
     });
-    return true;
+    return { status: "persisted" };
   }
 
   if (!posAnim) {
-    return false;
+    return { status: "blocked", reason: "source-uneditable" };
   }
 
   // Verify the anim ID is still valid in the current file. The React-state
@@ -251,7 +297,7 @@ export async function tryGsapDragIntercept(
   } else {
     await commitGsapPositionFromDrag(selection, posAnim, offset, gsapPos, iframe, selector, cbs);
   }
-  return true;
+  return { status: "persisted" };
 }
 
 // ── Runtime property readers (re-exported for external callers) ───────────
@@ -267,28 +313,47 @@ export async function tryGsapRotationIntercept(
   iframe: HTMLIFrameElement | null,
   commitMutation: GsapDragCommitCallbacks["commitMutation"],
   fetchFallbackAnimations?: () => Promise<GsapAnimation[]>,
-): Promise<boolean> {
-  const selector = selectorFromSelection(selection);
-  if (!selector) return false;
+): Promise<GsapEditOutcome> {
+  const selector = selectorFromSelection(selection) ?? writeTargetSelector(selection);
+  if (!selector) return { status: "blocked", reason: "no-selector" };
+
+  const fetchedAnimations = fetchFallbackAnimations ? await fetchFallbackAnimations() : [];
+  const workingAnimations = animations.length > 0 ? animations : fetchedAnimations;
+  const editability = directEditOutcomeForProperties(
+    [...animations, ...fetchedAnimations],
+    ROTATION_CHANNEL_SET,
+  );
+  if (editability.status === "blocked") return editability;
+  const postSplitFetch = workingAnimations.some((animation) => !animation.propertyGroup)
+    ? fetchFallbackAnimations
+    : undefined;
 
   // Resolve the rotation-group tween, splitting legacy mixed tweens if needed.
   const resolved = await resolveGroupTween(
     "rotation",
-    animations,
+    workingAnimations,
     selection,
     commitMutation,
-    fetchFallbackAnimations,
+    postSplitFetch,
   );
-  const resolvedAnimations = resolved?.animations ?? animations;
+  const resolvedAnimations = resolved?.animations ?? workingAnimations;
 
   // Fallback: legacy heuristic for hand-written scripts
-  let anim = resolved?.anim ?? null;
+  let anim =
+    resolved?.anim && animationWritesAnyProperty(resolved.anim, ROTATION_CHANNEL_SET)
+      ? resolved.anim
+      : null;
   if (!anim) {
-    anim = animations.find((a) => "rotation" in a.properties || a.keyframes) ?? null;
-    if (!anim && fetchFallbackAnimations) {
-      const fresh = await fetchFallbackAnimations();
-      anim = fresh.find((a) => "rotation" in a.properties || a.keyframes) ?? null;
-    }
+    anim =
+      workingAnimations.find((a) => animationWritesAnyProperty(a, ROTATION_CHANNEL_SET)) ?? null;
+  }
+
+  const liveSelector = selectorFromSelection(selection);
+  const hasLiveRotationTween = liveSelector
+    ? hasNonHoldTweenForElement(iframe, liveSelector, undefined, ROTATION_CHANNELS)
+    : false;
+  if (!anim && hasLiveRotationTween) {
+    return { status: "blocked", reason: "source-uneditable" };
   }
 
   // `angle` is the ABSOLUTE target rotation resolved by the gesture (gsap base +
@@ -307,7 +372,7 @@ export async function tryGsapRotationIntercept(
       commitMutation,
       fetchAnimations: fetchFallbackAnimations,
     });
-    return true;
+    return { status: "persisted" };
   }
 
   const pct = computeCurrentPercentage(selection, anim);
@@ -325,7 +390,7 @@ export async function tryGsapRotationIntercept(
       { commitMutation, fetchAnimations: fetchFallbackAnimations },
       "Rotate animation",
     );
-    return true;
+    return { status: "persisted" };
   }
 
   // fallow-ignore-next-line code-duplication
@@ -363,7 +428,7 @@ export async function tryGsapRotationIntercept(
     },
     { label: `Rotate (keyframe ${pct}%)`, softReload: true },
   );
-  return true;
+  return { status: "persisted" };
 }
 
 export { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeKeyframes";

package/src/hooks/useAnimatedPropertyCommit.test.tsx

@@ -41,19 +41,45 @@ type Commit = (
 /** Renders the hook and hands its commit function to the caller via a ref callback. */
 function renderHookWith(
   animations: GsapAnimation[],
-  onMutation: (mutation: Record<string, unknown>, label: string) => void,
+  onMutation: (mutation: Record<string, unknown>, label: string) => unknown | Promise<unknown>,
   onReady: (commit: Commit) => void,
+  bumpGsapCache = vi.fn(),
+  onBatch?: (
+    calls: Array<{ mutation: Record<string, unknown>; options: { label: string } }>,
+    label: string,
+  ) => unknown | Promise<unknown>,
 ) {
   function Harness() {
+    const gsapCommitMutation = Object.assign(
+      async (
+        _sel: DomEditSelection,
+        mutation: Record<string, unknown>,
+        options: { label: string },
+      ) => {
+        await onMutation(mutation, options.label);
+      },
+      onBatch
+        ? {
+            batch: async (
+              calls: Array<{
+                selection: DomEditSelection;
+                mutation: Record<string, unknown>;
+                options: { label: string };
+              }>,
+              options: { label: string },
+            ) => {
+              await onBatch(calls, options.label);
+            },
+          }
+        : {},
+    );
     const { commitAnimatedProperties } = useAnimatedPropertyCommit({
       selectedGsapAnimations: animations,
-      gsapCommitMutation: async (_sel, mutation, options) => {
-        onMutation(mutation, options.label);
-      },
+      gsapCommitMutation,
       addGsapAnimation: vi.fn(),
       convertToKeyframes: vi.fn(),
       previewIframeRef: { current: null },
-      bumpGsapCache: vi.fn(),
+      bumpGsapCache,
     });
     onReady(commitAnimatedProperties);
     return null;
@@ -61,11 +87,106 @@ function renderHookWith(
   return mountReactHarness(<Harness />);
 }
 
+describe("useAnimatedPropertyCommit — ownership and rejection propagation", () => {
+  it("rejects a helper-authored property before sending a mutation", async () => {
+    const helperRotation = {
+      id: "#box-to-rotation",
+      targetSelector: "#box",
+      propertyGroup: "rotation",
+      method: "to",
+      properties: { rotationX: 10 },
+      provenance: { kind: "helper", fn: "spin", callSite: 1 },
+    } as unknown as GsapAnimation;
+    const mutations: Array<Record<string, unknown>> = [];
+    let commit!: Commit;
+    const root = renderHookWith(
+      [helperRotation],
+      (mutation) => mutations.push(mutation),
+      (ready) => (commit = ready),
+    );
+
+    await expect(commit(selection, { rotationX: 12 })).rejects.toMatchObject({
+      name: "GsapEditBlockedError",
+      reason: "unroll-required",
+    });
+    expect(mutations).toHaveLength(0);
+    act(() => root.unmount());
+  });
+
+  it("rejects runtime-computed property ownership before sending a mutation", async () => {
+    const runtimePosition = {
+      ...keyframedAnim,
+      hasUnresolvedKeyframes: true,
+    } as GsapAnimation;
+    const mutations: Array<Record<string, unknown>> = [];
+    let commit!: Commit;
+    const root = renderHookWith(
+      [runtimePosition],
+      (mutation) => mutations.push(mutation),
+      (ready) => (commit = ready),
+    );
+
+    await expect(commit(selection, { x: 50 })).rejects.toMatchObject({
+      reason: "source-uneditable",
+    });
+    expect(mutations).toHaveLength(0);
+    act(() => root.unmount());
+  });
+
+  it("rejects every property before a mixed-group commit can partially persist", async () => {
+    const helperOpacity = {
+      id: "#box-to-visual",
+      targetSelector: "#box",
+      propertyGroup: "visual",
+      method: "to",
+      properties: { opacity: 0.5 },
+      provenance: { kind: "helper", fn: "fade", callSite: 1 },
+    } as unknown as GsapAnimation;
+    const mutations: Array<Record<string, unknown>> = [];
+    let commit!: Commit;
+    const root = renderHookWith(
+      [helperOpacity],
+      (mutation) => mutations.push(mutation),
+      (ready) => (commit = ready),
+    );
+
+    await expect(commit(selection, { x: 50, opacity: 0.8 })).rejects.toMatchObject({
+      reason: "unroll-required",
+    });
+    expect(mutations).toHaveLength(0);
+    act(() => root.unmount());
+  });
+
+  it("rethrows a persistence failure to the telemetry wrapper", async () => {
+    const failure = new Error("save failed");
+    const bumpGsapCache = vi.fn();
+    let commit!: Commit;
+    const root = renderHookWith(
+      [keyframedAnim],
+      async () => {
+        throw failure;
+      },
+      (ready) => (commit = ready),
+      bumpGsapCache,
+    );
+
+    await expect(commit(selection, { x: 50 })).rejects.toBe(failure);
+    expect(bumpGsapCache).toHaveBeenCalledTimes(1);
+    act(() => root.unmount());
+  });
+});
+
 function renderCommitHook(
   mutations: Array<Record<string, unknown>>,
   onReady: (commit: Commit) => void,
 ) {
-  return renderHookWith([keyframedAnim], (mutation) => mutations.push(mutation), onReady);
+  return renderHookWith(
+    [keyframedAnim],
+    (mutation) => {
+      mutations.push(mutation);
+    },
+    onReady,
+  );
 }
 
 // Regression (#1808): a "3D transform" / design-panel property edit on an
@@ -74,35 +195,28 @@ function renderCommitHook(
 // off, it must shift the whole tween instead of adding/updating a keyframe
 // at the playhead.
 describe("useAnimatedPropertyCommit — autoKeyframeEnabled toggle (#1808)", () => {
-  it("shifts the whole tween instead of updating a keyframe when the toggle is off", async () => {
-    usePlayerStore.setState({ autoKeyframeEnabled: false, currentTime: 0 });
+  async function runCommitWithAutoKeyframe(enabled: boolean) {
+    usePlayerStore.setState({ autoKeyframeEnabled: enabled, currentTime: 0 });
     const mutations: Array<Record<string, unknown>> = [];
     let commit: Commit | undefined;
     const root = renderCommitHook(mutations, (fn) => (commit = fn));
+    await act(async () => commit!(selection, { x: 50 }));
+    act(() => root.unmount());
+    return mutations;
+  }
 
-    await act(async () => {
-      await commit!(selection, { x: 50 });
-    });
-
+  it("shifts the whole tween instead of updating a keyframe when the toggle is off", async () => {
+    const mutations = await runCommitWithAutoKeyframe(false);
     expect(mutations).toHaveLength(1);
     expect(mutations[0]!.type).toBe("replace-with-keyframes");
-    act(() => root.unmount());
   });
 
   it("still updates a keyframe at the playhead when the toggle is on (default)", async () => {
-    const mutations: Array<Record<string, unknown>> = [];
-    let commit: Commit | undefined;
-    const root = renderCommitHook(mutations, (fn) => (commit = fn));
-
-    await act(async () => {
-      await commit!(selection, { x: 50 });
-    });
-
+    const mutations = await runCommitWithAutoKeyframe(true);
     expect(mutations.some((m) => m.type === "update-keyframe" || m.type === "add-keyframe")).toBe(
       true,
     );
     expect(mutations.some((m) => m.type === "replace-with-keyframes")).toBe(false);
-    act(() => root.unmount());
   });
 });
 
@@ -125,7 +239,9 @@ describe("commitStaticSet group routing", () => {
   ) {
     return renderHookWith(
       [positionSet],
-      (mutation, label) => committed.push({ mutation, label }),
+      (mutation, label) => {
+        committed.push({ mutation, label });
+      },
       onReady,
     );
   }
@@ -173,7 +289,9 @@ describe("commitStaticSet group routing", () => {
     let commit!: Commit;
     renderHookWith(
       [positionSet, instantSizeHold],
-      (mutation, label) => committed.push({ mutation, label }),
+      (mutation, label) => {
+        committed.push({ mutation, label });
+      },
       (c) => (commit = c),
     );
 
@@ -191,4 +309,56 @@ describe("commitStaticSet group routing", () => {
     expect(committed.some(({ mutation }) => mutation.type === "add")).toBe(false);
     expect(committed[0]!.mutation.animationId).not.toBe(positionSet.id);
   });
+
+  it("persists multiple property groups in one atomic batch", async () => {
+    const committed: Array<{ mutation: Record<string, unknown>; label: string }> = [];
+    const batches: Array<{
+      calls: Array<{ mutation: Record<string, unknown>; options: { label: string } }>;
+      label: string;
+    }> = [];
+    let commit!: Commit;
+    const root = renderHookWith(
+      [positionSet],
+      (mutation, label) => committed.push({ mutation, label }),
+      (ready) => (commit = ready),
+      vi.fn(),
+      (calls, label) => batches.push({ calls, label }),
+    );
+
+    await act(async () => {
+      await commit(selection, { x: 400, width: 500 });
+    });
+
+    expect(committed).toHaveLength(0);
+    expect(batches).toHaveLength(1);
+    expect(batches[0]!.label).toBe("Set properties");
+    expect(batches[0]!.calls.map(({ mutation }) => mutation)).toEqual([
+      {
+        type: "update-properties",
+        animationId: positionSet.id,
+        properties: { x: 400 },
+      },
+      {
+        type: "add",
+        targetSelector: "#box",
+        method: "set",
+        position: 0,
+        properties: { width: 500 },
+        global: true,
+      },
+    ]);
+    act(() => root.unmount());
+  });
+
+  it("fails before sending anything when an atomic multi-group batch is unavailable", async () => {
+    const committed: Array<{ mutation: Record<string, unknown>; label: string }> = [];
+    let commit!: Commit;
+    const root = renderStaticHook(committed, (ready) => (commit = ready));
+
+    await expect(commit(selection, { x: 400, width: 500 })).rejects.toThrow(
+      "Atomic GSAP property batch is unavailable",
+    );
+    expect(committed).toHaveLength(0);
+    act(() => root.unmount());
+  });
 });