@hyperframes/studio 0.7.92 → 0.7.93

package/src/hooks/gsapRuntimeBridge.test.ts

@@ -59,6 +59,67 @@ const stalePositionAnim = {
 afterEach(() => vi.restoreAllMocks());
 
 describe("tryGsapDragIntercept — stale-parse guard (no resurrection after delete-all)", () => {
+  async function runHelperOwnedDrag(fetchFallbackAnimations?: () => Promise<GsapAnimation[]>) {
+    const helperTween = {
+      ...stalePositionAnim,
+      provenance: { kind: "helper", fn: "slam", callSite: 1 },
+    } as GsapAnimation;
+    const commitMutation = vi.fn();
+    const result = await tryGsapDragIntercept(
+      selection,
+      { x: 10, y: 10 },
+      [helperTween],
+      fakeIframe("puck-b", []),
+      commitMutation,
+      fetchFallbackAnimations,
+    );
+    return { result, commitMutation };
+  }
+
+  it("blocks a live runtime position tween when no editable source mapping exists", async () => {
+    const liveTween = {
+      targets: () => [{ id: "puck-b" }],
+      vars: { y: 18, duration: 1 },
+      duration: () => 1,
+      startTime: () => 0,
+    };
+    const commitMutation = vi.fn();
+
+    const result = await tryGsapDragIntercept(
+      selection,
+      { x: 25, y: -10 },
+      [],
+      fakeIframe("puck-b", [liveTween]),
+      commitMutation,
+      vi.fn().mockResolvedValue([]),
+    );
+
+    expect(result).toEqual({ status: "blocked", reason: "source-uneditable" });
+    expect(commitMutation).not.toHaveBeenCalled();
+  });
+
+  it("blocks a selector that cannot safely address one writable element", async () => {
+    const selectorless = {
+      ...selection,
+      id: undefined,
+      selector: undefined,
+    } as unknown as DomEditSelection;
+    const result = await tryGsapDragIntercept(selectorless, { x: 1, y: 1 }, [], null, vi.fn());
+    expect(result).toEqual({ status: "blocked", reason: "no-selector" });
+  });
+
+  it("requires explicit unroll for helper-authored source and performs no mutation", async () => {
+    const { result, commitMutation } = await runHelperOwnedDrag();
+    expect(result).toEqual({ status: "blocked", reason: "unroll-required" });
+    expect(commitMutation).not.toHaveBeenCalled();
+  });
+
+  it("does not let an empty fallback response bypass cached helper provenance", async () => {
+    const { result, commitMutation } = await runHelperOwnedDrag(vi.fn().mockResolvedValue([]));
+    expect(result).toEqual({ status: "blocked", reason: "unroll-required" });
+    expect(commitMutation).not.toHaveBeenCalled();
+  });
+
   it("commits a static set (not the stale tween) when the runtime has no live position motion", async () => {
     const commitMutation = vi.fn();
     // Runtime empty (tween deleted) — readRuntimeKeyframes returns null, so the
@@ -73,7 +134,7 @@ describe("tryGsapDragIntercept — stale-parse guard (no resurrection after dele
       commitMutation,
     );
 
-    expect(handled).toBe(true);
+    expect(handled).toEqual({ status: "persisted" });
     // No existing `set` for the selector → one `add` mutation with `method:"set"`.
     expect(commitMutation).toHaveBeenCalledTimes(1);
     const [, mutation] = commitMutation.mock.calls[0];
@@ -112,7 +173,7 @@ describe("tryGsapDragIntercept — stale-parse guard (no resurrection after dele
       commitMutation,
     );
 
-    expect(handled).toBe(true);
+    expect(handled).toEqual({ status: "persisted" });
     const updates = commitMutation.mock.calls.filter(([, m]) => m.type === "update-properties");
     expect(updates).toHaveLength(1);
     expect(updates[0][1]).toEqual({
@@ -151,7 +212,7 @@ describe("tryGsapDragIntercept — stale-parse guard (no resurrection after dele
       commitMutation,
     );
 
-    expect(handled).toBe(true);
+    expect(handled).toEqual({ status: "persisted" });
     // One atomic in-place update, NOT an `add`/`add-keyframe`.
     const types = commitMutation.mock.calls.map(([, m]) => m.type);
     expect(types).toEqual(["update-properties"]);
@@ -179,6 +240,124 @@ describe("tryGsapDragIntercept — stale-parse guard (no resurrection after dele
 });
 
 describe("tryGsapRotationIntercept — instant holds", () => {
+  it("requires explicit unroll for helper-authored rotation before mutating", async () => {
+    const helperRotation = {
+      id: "#puck-b-to-rotation",
+      targetSelector: "#puck-b",
+      propertyGroup: "rotation",
+      method: "to",
+      properties: { rotation: 45 },
+      position: 0,
+      duration: 1,
+      provenance: { kind: "helper", fn: "spin", callSite: 1 },
+    } as unknown as GsapAnimation;
+    const commitMutation = vi.fn();
+
+    await expect(
+      tryGsapRotationIntercept(selection, 75, [helperRotation], null, commitMutation),
+    ).resolves.toEqual({ status: "blocked", reason: "unroll-required" });
+    expect(commitMutation).not.toHaveBeenCalled();
+  });
+
+  // Mirrors resize by design: both geometry routes must reuse one ownership parse.
+  // fallow-ignore-next-line code-duplication
+  it("reuses the ownership parse instead of fetching a resolved rotation group twice", async () => {
+    const rotationHold = {
+      id: "#puck-b-set-rotation",
+      targetSelector: "#puck-b",
+      propertyGroup: "rotation",
+      method: "set",
+      properties: { rotation: 45 },
+    } as unknown as GsapAnimation;
+    const fetchAnimations = vi.fn().mockResolvedValue([rotationHold]);
+    const commitMutation = vi.fn();
+
+    await expect(
+      tryGsapRotationIntercept(selection, 75, [], null, commitMutation, fetchAnimations),
+    ).resolves.toEqual({ status: "persisted" });
+    expect(fetchAnimations).toHaveBeenCalledTimes(1);
+    expect(commitMutation).toHaveBeenCalledWith(
+      selection,
+      expect.objectContaining({ type: "update-property", animationId: rotationHold.id }),
+      expect.anything(),
+    );
+  });
+
+  it("rejects a selectorless rotation instead of reporting a handled no-op", async () => {
+    const selectorless = {
+      ...selection,
+      id: undefined,
+      selector: undefined,
+    } as unknown as DomEditSelection;
+    const commitMutation = vi.fn();
+
+    await expect(
+      tryGsapRotationIntercept(selectorless, 75, [], null, commitMutation),
+    ).resolves.toEqual({ status: "blocked", reason: "no-selector" });
+    expect(commitMutation).not.toHaveBeenCalled();
+  });
+
+  it("blocks helper-authored 3D rotation channels before mutating the group", async () => {
+    const helperRotationX = {
+      id: "#puck-b-to-rotation",
+      targetSelector: "#puck-b",
+      propertyGroup: "rotation",
+      method: "to",
+      properties: { rotationX: 45 },
+      duration: 1,
+      provenance: { kind: "helper", fn: "tilt", callSite: 1 },
+    } as unknown as GsapAnimation;
+    const commitMutation = vi.fn();
+
+    await expect(
+      tryGsapRotationIntercept(selection, 75, [helperRotationX], null, commitMutation),
+    ).resolves.toEqual({ status: "blocked", reason: "unroll-required" });
+    expect(commitMutation).not.toHaveBeenCalled();
+  });
+
+  it("does not let an unrelated helper-authored skew tween block 2D rotation", async () => {
+    const helperSkew = {
+      id: "#puck-b-to-rotation",
+      targetSelector: "#puck-b",
+      propertyGroup: "rotation",
+      method: "to",
+      properties: { skewX: 12 },
+      duration: 1,
+      provenance: { kind: "helper", fn: "skew", callSite: 1 },
+    } as unknown as GsapAnimation;
+    const commitMutation = vi.fn();
+
+    await expect(
+      tryGsapRotationIntercept(selection, 75, [helperSkew], null, commitMutation),
+    ).resolves.toEqual({ status: "persisted" });
+    expect(commitMutation).toHaveBeenCalledWith(
+      selection,
+      expect.objectContaining({ type: "add", properties: { rotation: 75 } }),
+      expect.anything(),
+    );
+  });
+
+  it("blocks when runtime rotation exists but the authored tween cannot be resolved", async () => {
+    const liveRotation = {
+      targets: () => [{ id: "puck-b" }],
+      vars: { rotation: 45, duration: 1 },
+      duration: () => 1,
+      startTime: () => 0,
+    };
+    const commitMutation = vi.fn();
+
+    await expect(
+      tryGsapRotationIntercept(
+        selection,
+        75,
+        [],
+        fakeIframe("puck-b", [liveRotation]),
+        commitMutation,
+      ),
+    ).resolves.toEqual({ status: "blocked", reason: "source-uneditable" });
+    expect(commitMutation).not.toHaveBeenCalled();
+  });
+
   it("updates a duration-zero fromTo hold instead of converting it to keyframes", async () => {
     const rotationHold = {
       id: "#puck-b-fromTo-0-rotation",
@@ -201,7 +380,7 @@ describe("tryGsapRotationIntercept — instant holds", () => {
       commitMutation,
     );
 
-    expect(handled).toBe(true);
+    expect(handled).toEqual({ status: "persisted" });
     expect(commitMutation).toHaveBeenCalledTimes(1);
     expect(commitMutation.mock.calls[0]![1]).toEqual({
       type: "update-property",
@@ -243,40 +422,29 @@ describe("tryGsapDragIntercept — autoKeyframeEnabled toggle (#1808)", () => {
     },
   } as unknown as GsapAnimation;
 
-  it("shifts the whole tween instead of adding a keyframe when the toggle is off", async () => {
-    usePlayerStore.setState({ autoKeyframeEnabled: false, currentTime: 2 }); // playhead at 100%
+  async function runAutoKeyframeDrag(enabled: boolean) {
+    usePlayerStore.setState({ autoKeyframeEnabled: enabled, currentTime: 2 });
     const commitMutation = vi.fn();
-    const iframe = fakeIframe("puck-b", []);
-
     const handled = await tryGsapDragIntercept(
       selection,
       { x: -50, y: 0 },
       [keyframedPositionAnim],
-      iframe,
+      fakeIframe("puck-b", []),
       commitMutation,
     );
+    return { handled, types: commitMutation.mock.calls.map(([, mutation]) => mutation.type) };
+  }
 
-    expect(handled).toBe(true);
-    const types = commitMutation.mock.calls.map(([, m]) => m.type);
+  it("shifts the whole tween instead of adding a keyframe when the toggle is off", async () => {
+    const { handled, types } = await runAutoKeyframeDrag(false);
+    expect(handled).toEqual({ status: "persisted" });
     expect(types).toContain("replace-with-keyframes");
     expect(types).not.toContain("add-keyframe");
   });
 
   it("still adds/updates a keyframe at the playhead when the toggle is on (default)", async () => {
-    usePlayerStore.setState({ autoKeyframeEnabled: true, currentTime: 2 });
-    const commitMutation = vi.fn();
-    const iframe = fakeIframe("puck-b", []);
-
-    const handled = await tryGsapDragIntercept(
-      selection,
-      { x: -50, y: 0 },
-      [keyframedPositionAnim],
-      iframe,
-      commitMutation,
-    );
-
-    expect(handled).toBe(true);
-    const types = commitMutation.mock.calls.map(([, m]) => m.type);
+    const { handled, types } = await runAutoKeyframeDrag(true);
+    expect(handled).toEqual({ status: "persisted" });
     expect(types).not.toContain("replace-with-keyframes");
   });
 });
@@ -336,7 +504,7 @@ describe("tryGsapDragIntercept — motion paths", () => {
   it("creates a temporal keyframe at the exact playhead instead of redistributing path waypoints", async () => {
     const { commitMutation, handled } = await dragMotionPath(null);
 
-    expect(handled).toBe(true);
+    expect(handled).toEqual({ status: "persisted" });
     expect(commitMutation).toHaveBeenCalledWith(
       selection,
       {
@@ -363,7 +531,7 @@ describe("tryGsapDragIntercept — motion paths", () => {
   it("keeps an explicitly selected path waypoint as a spatial edit", async () => {
     const { commitMutation, handled } = await dragMotionPath(50);
 
-    expect(handled).toBe(true);
+    expect(handled).toEqual({ status: "persisted" });
     expect(commitMutation).toHaveBeenCalledWith(
       selection,
       {

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";