@hyperframes/studio 0.7.92 → 0.7.93

package/src/hooks/gsapDragCommit.test.ts

@@ -1,6 +1,6 @@
 // @vitest-environment happy-dom
 
-import { describe, expect, it, beforeEach } from "vitest";
+import { describe, expect, it, beforeEach, vi } from "vitest";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { commitGsapPositionFromDrag } from "./gsapDragPositionCommit";
@@ -9,6 +9,7 @@ import {
   commitStaticGsapRotation,
   commitStaticGsapSize,
   findExistingPositionWrite,
+  materializeIfDynamic,
   parkPlayheadOnKeyframe,
   type GsapDragCommitCallbacks,
 } from "./gsapDragCommit";
@@ -27,6 +28,43 @@ const selection = (): DomEditSelection =>
     },
   }) as unknown as DomEditSelection;
 
+function selectorlessSelection(): DomEditSelection {
+  return {
+    selector: ".shared",
+    element: document.createElement("div"),
+  } as unknown as DomEditSelection;
+}
+
+describe("lower GSAP commit helpers fail closed", () => {
+  it("rejects instead of silently dropping a static position write without a stable selector", async () => {
+    const commitMutation = vi.fn();
+    await expect(
+      commitStaticGsapPosition(
+        selectorlessSelection(),
+        { x: 10, y: 20 },
+        { x: 0, y: 0 },
+        ".shared",
+        null,
+        { commitMutation },
+      ),
+    ).rejects.toMatchObject({ name: "GsapEditBlockedError", reason: "no-selector" });
+    expect(commitMutation).not.toHaveBeenCalled();
+  });
+
+  it("rejects runtime-dynamic materialization instead of rewriting source during a gesture", async () => {
+    const commitMutation = vi.fn();
+    await expect(
+      materializeIfDynamic(
+        { ...flatTween(), hasUnresolvedKeyframes: true },
+        null,
+        commitMutation,
+        selection(),
+      ),
+    ).rejects.toMatchObject({ name: "GsapEditBlockedError", reason: "source-uneditable" });
+    expect(commitMutation).not.toHaveBeenCalled();
+  });
+});
+
 const flatTween = (): GsapAnimation =>
   ({
     id: "#puck-a-to",

package/src/hooks/gsapDragCommit.ts

@@ -9,14 +9,14 @@ import {
   STUDIO_ORIGINAL_HEIGHT_ATTR,
 } from "../components/editor/manualEditsTypes";
 import { usePlayerStore } from "../player/store/playerStore";
-import { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeKeyframes";
 import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
 import { roundTo3 } from "../utils/rounding";
-import { computeElementPercentage, idSelector, writeTargetSelector } from "./gsapShared";
+import { computeElementPercentage, writeTargetSelector } from "./gsapShared";
 import { computeDraggedGsapPosition } from "./draggedGsapPosition";
 import type { RuntimeTweenChange } from "./gsapRuntimePatch";
 import { isGestureTransactionCommit, runGestureTransaction } from "./gestureTransaction";
 import { setPatchFromUpdateProperty } from "./gsapDragStaticSetHelpers";
+import { GsapEditBlockedError } from "./gsapEditOutcome";
 export {
   findExistingPositionWrite,
   findRotationSetAnimation,
@@ -87,7 +87,7 @@ async function replaceKeyframedPositionHold(
   commitMutation: GsapDragCommitCallbacks["commitMutation"],
 ): Promise<void> {
   const target = newTweenTarget(selection);
-  if (!target) return;
+  if (!target) throw new GsapEditBlockedError("no-selector");
   const persist = async (commit: GsapDragCommitCallbacks["commitMutation"]) => {
     await commit(
       selection,
@@ -130,40 +130,12 @@ export async function materializeIfDynamic(
   selection: DomEditSelection,
 ): Promise<string | void> {
   if (!anim.hasUnresolvedKeyframes && !anim.hasUnresolvedSelector) return;
-
-  if (anim.hasUnresolvedSelector) {
-    const allScanned = scanAllRuntimeKeyframes(iframe);
-    if (allScanned.size === 0) return;
-    const allElements = Array.from(allScanned.entries()).map(([id, data]) => ({
-      selector: idSelector(id),
-      keyframes: data.keyframes,
-      easeEach: data.easeEach,
-    }));
-    await commitMutation(
-      selection,
-      {
-        type: "materialize-keyframes",
-        animationId: anim.id,
-        keyframes: allScanned.get(selection.id ?? "")?.keyframes ?? [],
-        allElements,
-      },
-      { label: "Unroll dynamic animations", skipReload: true },
-    );
-    return `${anim.targetSelector}-to-0`;
-  }
-
-  const runtime = readRuntimeKeyframes(iframe, anim.targetSelector);
-  if (!runtime || runtime.keyframes.length === 0) return;
-  await commitMutation(
-    selection,
-    {
-      type: "materialize-keyframes",
-      animationId: anim.id,
-      keyframes: runtime.keyframes,
-      easeEach: runtime.easeEach,
-    },
-    { label: "Materialize dynamic keyframes", skipReload: true },
-  );
+  // Geometry commits must never rewrite runtime/computed source implicitly.
+  // The explicit Unroll action owns that source-destructive transition.
+  void iframe;
+  void commitMutation;
+  void selection;
+  throw new GsapEditBlockedError("source-uneditable");
 }
 
 // ── Drag → GSAP position math ──────────────────────────────────────────────
@@ -219,7 +191,7 @@ export async function commitStaticGsapPosition(
   // The patch reuses the WRITTEN target so the runtime moves exactly the element
   // the source write names.
   const target = newTweenTarget(selection);
-  if (!target) return;
+  if (!target) throw new GsapEditBlockedError("no-selector");
   await callbacks.commitMutation(
     selection,
     {
@@ -277,7 +249,7 @@ export async function commitStaticGsapRotation(
   }
   // New static hold → off-timeline `gsap.set` (no 0% keyframe marker) + instant patch.
   const target = newTweenTarget(selection);
-  if (!target) return;
+  if (!target) throw new GsapEditBlockedError("no-selector");
   await callbacks.commitMutation(
     selection,
     {
@@ -331,7 +303,7 @@ export async function commitStaticGsapSize(
     return;
   }
   const target = newTweenTarget(selection);
-  if (!target) return;
+  if (!target) throw new GsapEditBlockedError("no-selector");
   await callbacks.commitMutation(
     selection,
     {

package/src/hooks/gsapEditOutcome.ts

@@ -0,0 +1,72 @@
+import { editabilityForProvenance, type GsapAnimation } from "@hyperframes/core/gsap-parser";
+
+export type GsapEditBlockReason = "no-selector" | "unroll-required" | "source-uneditable";
+
+export type GsapEditOutcome =
+  | { status: "persisted" }
+  | { status: "blocked"; reason: GsapEditBlockReason };
+
+const COPY: Record<GsapEditBlockReason, string> = {
+  "no-selector": "This layer needs a stable selector before Studio can save the edit.",
+  "unroll-required":
+    "This motion comes from a helper or loop. Choose Unroll to edit it explicitly.",
+  "source-uneditable": "This animation is computed at runtime. Edit the animation in the Code tab.",
+};
+
+export class GsapEditBlockedError extends Error {
+  constructor(readonly reason: GsapEditBlockReason) {
+    super(COPY[reason]);
+    this.name = "GsapEditBlockedError";
+  }
+}
+
+export function assertGsapEditPersisted(outcome: GsapEditOutcome): void {
+  if (outcome.status === "blocked") throw new GsapEditBlockedError(outcome.reason);
+}
+
+function assertGsapAnimationDirectlyEditable(animation: GsapAnimation): void {
+  const editability = editabilityForProvenance(animation.provenance);
+  if (editability === "unroll") throw new GsapEditBlockedError("unroll-required");
+  if (
+    editability === "source" ||
+    animation.hasUnresolvedKeyframes ||
+    animation.hasUnresolvedSelector
+  ) {
+    throw new GsapEditBlockedError("source-uneditable");
+  }
+}
+
+export function isGsapEditBlockedError(error: unknown): error is GsapEditBlockedError {
+  return error instanceof GsapEditBlockedError;
+}
+
+export function animationWritesAnyProperty(
+  animation: GsapAnimation,
+  properties: ReadonlySet<string>,
+): boolean {
+  return (
+    Object.keys(animation.properties ?? {}).some((property) => properties.has(property)) ||
+    Object.keys(animation.fromProperties ?? {}).some((property) => properties.has(property)) ||
+    !!animation.keyframes?.keyframes.some((keyframe) =>
+      Object.keys(keyframe.properties).some((property) => properties.has(property)),
+    )
+  );
+}
+
+/** Fail-closed ownership check shared by drag, resize, rotate, and inspector edits. */
+export function directEditOutcomeForProperties(
+  animations: GsapAnimation[],
+  properties: ReadonlySet<string>,
+): GsapEditOutcome {
+  try {
+    for (const animation of animations) {
+      if (animationWritesAnyProperty(animation, properties)) {
+        assertGsapAnimationDirectlyEditable(animation);
+      }
+    }
+    return { status: "persisted" };
+  } catch (error) {
+    if (isGsapEditBlockedError(error)) return { status: "blocked", reason: error.reason };
+    throw error;
+  }
+}

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 ────────────────────────────────────────────────────