@hyperframes/studio 0.7.90 → 0.7.93

package/src/hooks/gsapResizeIntercept.test.ts

@@ -70,6 +70,8 @@ function keyframedScaleFixture(): GsapAnimation {
   } as unknown as GsapAnimation;
 }
 
+// Resize/rotation hold tests intentionally pin the same no-conversion contract.
+// fallow-ignore-next-line code-duplication
 it("updates a duration-zero size hold in place instead of converting it to keyframes", async () => {
   const el = document.createElement("div");
   el.id = "box";
@@ -96,7 +98,7 @@ it("updates a duration-zero size hold in place instead of converting it to keyfr
     commitMutation,
   );
 
-  expect(handled).toBe(true);
+  expect(handled).toEqual({ status: "persisted" });
   expect(commitMutation).toHaveBeenCalledTimes(1);
   expect(commitMutation.mock.calls[0]![1]).toEqual({
     type: "update-properties",
@@ -115,6 +117,92 @@ it("updates a duration-zero size hold in place instead of converting it to keyfr
   );
 });
 
+// fallow-ignore-next-line code-duplication
+it("requires explicit unroll for helper-authored resize before mutating", async () => {
+  const el = document.createElement("div");
+  el.id = "box";
+  document.body.append(el);
+  const selection = { id: "box", selector: "#box", element: el } as DomEditSelection;
+  const helperSize = {
+    id: "#box-to-size",
+    targetSelector: "#box",
+    propertyGroup: "size",
+    method: "to",
+    properties: { width: 150, height: 150 },
+    duration: 1,
+    provenance: { kind: "helper", fn: "grow", callSite: 1 },
+  } as unknown as GsapAnimation;
+  const commitMutation = vi.fn();
+
+  await expect(
+    tryGsapResizeIntercept(
+      selection,
+      { width: 344, height: 344 },
+      [helperSize],
+      null,
+      commitMutation,
+    ),
+  ).resolves.toEqual({ status: "blocked", reason: "unroll-required" });
+  expect(commitMutation).not.toHaveBeenCalled();
+});
+
+// fallow-ignore-next-line code-duplication
+it("reuses the ownership parse instead of fetching a resolved size group twice", async () => {
+  const el = document.createElement("div");
+  el.id = "box";
+  document.body.append(el);
+  const selection = { id: "box", selector: "#box", element: el } as DomEditSelection;
+  const sizeHold = {
+    id: "#box-set-size",
+    targetSelector: "#box",
+    propertyGroup: "size",
+    method: "set",
+    properties: { width: 150, height: 150 },
+  } as unknown as GsapAnimation;
+  const fetchAnimations = vi.fn().mockResolvedValue([sizeHold]);
+  const commitMutation = vi.fn();
+
+  await expect(
+    tryGsapResizeIntercept(
+      selection,
+      { width: 344, height: 344 },
+      [],
+      null,
+      commitMutation,
+      fetchAnimations,
+    ),
+  ).resolves.toEqual({ status: "persisted" });
+  expect(fetchAnimations).toHaveBeenCalledTimes(1);
+  expect(commitMutation).toHaveBeenCalledWith(
+    selection,
+    expect.objectContaining({ type: "update-properties", animationId: sizeHold.id }),
+    expect.anything(),
+  );
+});
+
+it("blocks when runtime size motion exists but the authored tween cannot be resolved", async () => {
+  const el = document.createElement("div");
+  el.id = "box";
+  document.body.append(el);
+  const selection = { id: "box", selector: "#box", element: el } as DomEditSelection;
+  const liveSizeTween = {
+    targets: () => [el],
+    vars: { width: 300, duration: 1 },
+    duration: () => 1,
+    startTime: () => 0,
+  };
+  const iframe = {
+    contentWindow: { __timelines: { main: { getChildren: () => [liveSizeTween] } } },
+    contentDocument: document,
+  } as unknown as HTMLIFrameElement;
+  const commitMutation = vi.fn();
+
+  await expect(
+    tryGsapResizeIntercept(selection, { width: 344, height: 344 }, [], iframe, commitMutation),
+  ).resolves.toEqual({ status: "blocked", reason: "source-uneditable" });
+  expect(commitMutation).not.toHaveBeenCalled();
+});
+
 it("computes a finite zero percentage for a zero-duration tween", () => {
   const animation = {
     id: "#box-to-0-size",
@@ -158,7 +246,7 @@ async function runResize(
     commitMutation as never,
     async () => [keyframedScaleFixture()],
   );
-  expect(handled).toBe(true);
+  expect(handled).toEqual({ status: "persisted" });
   return committed;
 }
 

package/src/hooks/gsapResizeIntercept.ts

@@ -24,11 +24,16 @@ import type { GsapDragCommitCallbacks } from "./gsapDragCommit";
 import { pickClosestToPlayhead, readGsapPositionFromIframe } from "./gsapPositionDetection";
 import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
 import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
-import { isInstantHold, selectorFromSelection } from "./gsapShared";
+import { isInstantHold, selectorFromSelection, writeTargetSelector } from "./gsapShared";
 import { roundTo3 } from "../utils/rounding";
 import { resolveGroupTween, POSITION_CHANNELS } from "./gsapRuntimeBridge";
 import { hasNonHoldTweenForElement } from "./gsapRuntimeKeyframes";
 import { logResize } from "../utils/resizeDebug";
+import {
+  animationWritesAnyProperty,
+  directEditOutcomeForProperties,
+  type GsapEditOutcome,
+} from "./gsapEditOutcome";
 
 const IDENTITY_ONE_PROPS = new Set(["opacity", "autoAlpha", "scale", "scaleX", "scaleY"]);
 
@@ -54,21 +59,44 @@ export async function tryGsapResizeIntercept(
   iframe: HTMLIFrameElement | null,
   commitMutation: GsapDragCommitCallbacks["commitMutation"],
   fetchFallbackAnimations?: () => Promise<GsapAnimation[]>,
-): Promise<boolean> {
+): Promise<GsapEditOutcome> {
+  const fetchedAnimations = fetchFallbackAnimations ? await fetchFallbackAnimations() : [];
+  const allKnownAnimations = [...animations, ...fetchedAnimations];
   // If the element already has a scale-group tween, resize should modify scale
   // (the user is resizing something whose visual size is driven by scale).
   // Otherwise, use the size group (width/height).
-  const hasScaleGroup = animations.some((a) => a.propertyGroup === "scale");
+  const hasScaleGroup = allKnownAnimations.some((a) => a.propertyGroup === "scale");
   const resizeGroup: PropertyGroupName = hasScaleGroup ? "scale" : "size";
+  const resizeProperties =
+    resizeGroup === "scale" ? new Set(["scale", "scaleX", "scaleY"]) : new Set(["width", "height"]);
+  const editability = directEditOutcomeForProperties(allKnownAnimations, resizeProperties);
+  if (editability.status === "blocked") return editability;
+  const workingAnimations = animations.length > 0 ? animations : fetchedAnimations;
+  // The initial ownership fetch already supplied the complete parse. Only retain
+  // the fetch callback when a legacy mixed tween may be split and must then be
+  // re-read; otherwise resolveGroupTween would perform the same network read twice.
+  const postSplitFetch = workingAnimations.some((animation) => !animation.propertyGroup)
+    ? fetchFallbackAnimations
+    : undefined;
   const resolved = await resolveGroupTween(
     resizeGroup,
-    animations,
+    workingAnimations,
     selection,
     commitMutation,
-    fetchFallbackAnimations,
+    postSplitFetch,
   );
 
-  let anim = resolved?.anim ?? null;
+  let anim =
+    resolved?.anim && animationWritesAnyProperty(resolved.anim, resizeProperties)
+      ? resolved.anim
+      : null;
+  const liveSelector = selectorFromSelection(selection);
+  const hasLiveResizeTween = liveSelector
+    ? hasNonHoldTweenForElement(iframe, liveSelector, undefined, [...resizeProperties])
+    : false;
+  if (!anim && hasLiveResizeTween) {
+    return { status: "blocked", reason: "source-uneditable" };
+  }
   logResize("intercept-enter", {
     hasScaleGroup,
     resizeGroup,
@@ -77,16 +105,16 @@ export async function tryGsapResizeIntercept(
     size,
   });
   if (!anim || isInstantHold(anim)) {
-    const sel = selectorFromSelection(selection);
-    if (!sel) return false;
-    const sizeSet = anim ?? findSizeSetAnimation(animations, sel, selection.element);
+    const sel = selectorFromSelection(selection) ?? writeTargetSelector(selection);
+    if (!sel) return { status: "blocked", reason: "no-selector" };
+    const sizeSet = anim ?? findSizeSetAnimation(workingAnimations, sel, selection.element);
 
     // If the element is animated (has a real tween, not just a static size
     // hold), keyframe the size at the playhead so other keyframes keep theirs —
     // instead of a global set that resizes every frame.
     if (resizeGroup === "size") {
       const animatedTween = pickClosestToPlayhead(
-        animations.filter((a) => !isInstantHold(a) && resolveTweenDuration(a) > 0),
+        workingAnimations.filter((a) => !isInstantHold(a) && resolveTweenDuration(a) > 0),
       );
       if (animatedTween) {
         logResize("intercept-route", { route: "keyframed-size", tweenId: animatedTween.id });
@@ -98,7 +126,7 @@ export async function tryGsapResizeIntercept(
           animatedTween,
           { commitMutation, fetchAnimations: fetchFallbackAnimations },
         );
-        if (handled) return true;
+        if (handled) return { status: "persisted" };
       }
     }
 
@@ -107,11 +135,11 @@ export async function tryGsapResizeIntercept(
       commitMutation,
       fetchAnimations: fetchFallbackAnimations,
     });
-    return true;
+    return { status: "persisted" };
   }
 
   const tweenDuration = resolveTweenDuration(anim);
-  if (tweenDuration <= 0) return false;
+  if (tweenDuration <= 0) return { status: "blocked", reason: "source-uneditable" };
 
   const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
   const pct = activeKeyframePct ?? computeCurrentPercentage(selection, anim);
@@ -273,7 +301,7 @@ export async function tryGsapResizeIntercept(
       "Resize animation",
     );
     await finalizeScaleResizeCommit();
-    return true;
+    return { status: "persisted" };
   }
 
   const ct = usePlayerStore.getState().currentTime;
@@ -385,7 +413,7 @@ export async function tryGsapResizeIntercept(
       },
     );
     await finalizeScaleResizeCommit();
-    return true;
+    return { status: "persisted" };
   }
 
   const SIZE_PROPS = new Set(["width", "height"]);
@@ -407,7 +435,7 @@ export async function tryGsapResizeIntercept(
     { label: `Resize (keyframe ${pct}%)`, softReload: true },
   );
   await finalizeScaleResizeCommit();
-  return true;
+  return { status: "persisted" };
 }
 
 // ── Rotation intercept ────────────────────────────────────────────────────

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,
       {