@hyperframes/studio 0.8.115 → 0.8.116

package/src/hooks/useFileManager.ts

@@ -8,6 +8,7 @@ import { serializeStudioFileMutation } from "../utils/studioFileMutationCoordina
 import { useFileTree } from "./useFileTree";
 import { useEditorSave } from "./useEditorSave";
 import { useProjectFileWriter } from "./useProjectFileWriter";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 // ── Types ──
 
@@ -133,7 +134,7 @@ export function useFileManager({
         setEditingFile({ path, content: null });
         return;
       }
-      fetch(`/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(path)}`)
+      studioApiFetch(`/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(path)}`)
         .then((r) => {
           if (!r.ok) throw new Error(`Failed to load ${path} (${r.status})`);
           return r.json();
@@ -167,9 +168,12 @@ export function useFileManager({
       const requestId = ++revealRequestIdRef.current;
       const controller = new AbortController();
       revealAbortRef.current = controller;
-      fetch(`/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(sourceFile)}`, {
-        signal: controller.signal,
-      })
+      studioApiFetch(
+        `/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(sourceFile)}`,
+        {
+          signal: controller.signal,
+        },
+      )
         .then((r) => r.json())
         .then((data: { content?: string; version?: string }) => {
           if (requestId !== revealRequestIdRef.current) return;
@@ -200,7 +204,7 @@ export function useFileManager({
 
       const qs = dir ? `?dir=${encodeURIComponent(dir)}` : "";
       try {
-        const res = await fetch(`/api/projects/${encodeURIComponent(pid)}/upload${qs}`, {
+        const res = await studioApiFetch(`/api/projects/${encodeURIComponent(pid)}/upload${qs}`, {
           method: "POST",
           body: formData,
         });
@@ -246,7 +250,7 @@ export function useFileManager({
         content =
           '<!DOCTYPE html>\n<html>\n<head>\n  <meta charset="UTF-8">\n</head>\n<body>\n\n</body>\n</html>\n';
       }
-      const res = await fetch(
+      const res = await studioApiFetch(
         `/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(path)}`,
         {
           method: "POST",
@@ -270,7 +274,7 @@ export function useFileManager({
     async (path: string) => {
       const pid = projectIdRef.current;
       if (!pid) return;
-      const res = await fetch(
+      const res = await studioApiFetch(
         `/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(path + "/.gitkeep")}`,
         {
           method: "POST",
@@ -293,7 +297,7 @@ export function useFileManager({
     async (path: string) => {
       const pid = projectIdRef.current;
       if (!pid) return;
-      const res = await fetch(
+      const res = await studioApiFetch(
         `/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(path)}`,
         {
           method: "DELETE",
@@ -315,7 +319,7 @@ export function useFileManager({
     async (oldPath: string, newPath: string) => {
       const pid = projectIdRef.current;
       if (!pid) return;
-      const res = await fetch(
+      const res = await studioApiFetch(
         `/api/projects/${encodeURIComponent(pid)}/files/${encodeURIComponent(oldPath)}`,
         {
           method: "PATCH",
@@ -342,7 +346,7 @@ export function useFileManager({
     async (path: string) => {
       const pid = projectIdRef.current;
       if (!pid) return;
-      const res = await fetch(`/api/projects/${encodeURIComponent(pid)}/duplicate-file`, {
+      const res = await studioApiFetch(`/api/projects/${encodeURIComponent(pid)}/duplicate-file`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ path }),

package/src/hooks/useFileTree.ts

@@ -3,6 +3,7 @@ import { useState, useCallback, useEffect, useMemo, useRef } from "react";
 import { FONT_EXT } from "../utils/mediaTypes";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
 import { captureProjectProvenance } from "../components/feedback/projectProvenance";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 interface UseFileTreeOptions {
   projectId: string | null;
@@ -38,7 +39,7 @@ export function useFileTree({ projectId, projectIdRef }: UseFileTreeOptions) {
     if (!projectId) return;
     let cancelled = false;
     setFetched({ projectId, loaded: false, fileTree: [], compositionPaths: [], projectDir: null });
-    fetch(buildProjectApiPath(projectId))
+    studioApiFetch(buildProjectApiPath(projectId))
       // An unresolvable project answers 404 with a JSON body, so without this
       // the error path parsed cleanly and the success branch below recorded an
       // empty tree — and an empty provenance snapshot — for a project that was
@@ -84,7 +85,7 @@ export function useFileTree({ projectId, projectIdRef }: UseFileTreeOptions) {
     refreshAbortRef.current = controller;
     let data: { files?: string[]; compositions?: string[] };
     try {
-      const res = await fetch(buildProjectApiPath(pid), { signal: controller.signal });
+      const res = await studioApiFetch(buildProjectApiPath(pid), { signal: controller.signal });
       data = await res.json();
     } catch (err) {
       if (err instanceof DOMException && err.name === "AbortError") return;

package/src/hooks/useFrameCapture.ts

@@ -2,6 +2,7 @@ import { useMemo, useState, useCallback, useRef, type MouseEvent } from "react";
 import { useMountEffect } from "./useMountEffect";
 import { liveTime, usePlayerStore } from "../player";
 import { buildFrameCaptureFilename, buildFrameCaptureUrl } from "../utils/frameCapture";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 interface UseFrameCaptureParams {
   projectId: string | null;
@@ -67,7 +68,10 @@ export function useFrameCapture({
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), 30000);
         try {
-          const response = await fetch(href, { cache: "no-store", signal: controller.signal });
+          const response = await studioApiFetch(href, {
+            cache: "no-store",
+            signal: controller.signal,
+          });
           clearTimeout(timeout);
           if (!response.ok) {
             let msg = `Capture failed (${response.status})`;

package/src/hooks/useFreezeFrame.ts

@@ -6,6 +6,7 @@ import { buildProjectApiPath } from "../utils/projectRouting";
 import { markStudioWriteToken } from "../utils/studioFileVersion";
 import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
 import type { RecordEditInput } from "../utils/studioFileHistory";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 type ProjectFileWriter = (path: string, content: string, expectedContent?: string) => Promise<void>;
 
@@ -31,7 +32,7 @@ function errorOf(value: unknown): string | null {
 }
 
 async function readVersion(projectId: string, path: string): Promise<string> {
-  const response = await fetch(
+  const response = await studioApiFetch(
     buildProjectApiPath(projectId, `/files/${encodeURIComponent(path)}`),
   );
   const body: unknown = await response.json().catch(() => null);
@@ -53,7 +54,7 @@ export async function requestFreezeFrame(input: {
   const expectedVersion = await readVersion(input.projectId, input.path);
   const transactionToken = `freeze:${crypto.randomUUID()}`;
   markStudioWriteToken(transactionToken);
-  const response = await fetch(
+  const response = await studioApiFetch(
     buildProjectApiPath(input.projectId, "/file-mutations/freeze-frame"),
     {
       method: "POST",

package/src/hooks/useGroupCommits.ts

@@ -16,6 +16,7 @@ import {
   type ElementMatchSelection,
 } from "../utils/studioHelpers";
 import type { TimelineElement } from "../player";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 interface UseGroupCommitsParams extends DomEditCommitBaseParams {
   /** Resync the SDK session after a server-side write (the wrapper/unwrap changes
@@ -132,7 +133,7 @@ async function commitStructuralMutation(
     writeFile: deps.writeProjectFile,
     recordEdit: deps.editHistory.recordEdit,
     rewrite: async (originalContent) => {
-      const mutateResponse = await fetch(
+      const mutateResponse = await studioApiFetch(
         buildProjectApiPath(pid, `/file-mutations/${route}/${encodeURIComponent(targetPath)}`),
         {
           method: "POST",

package/src/hooks/useGsapAwareEditing.groupPlan.test.tsx

@@ -0,0 +1,160 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import type { DomEditGroupPathOffsetCommit } from "../components/editor/domEditOverlayGestures";
+import { usePlayerStore } from "../player/store/playerStore";
+import { trackStudioEditBlocked } from "../utils/studioSaveDiagnostics";
+import { GSAP_EDIT_BLOCK_COPY } from "./gsapEditOutcome";
+import { mountGsapAwareEditing } from "./useGsapAwareEditing.testHelpers";
+
+vi.mock("../utils/studioSaveDiagnostics", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../utils/studioSaveDiagnostics")>()),
+  trackStudioEditBlocked: vi.fn(),
+  trackStudioSaveFailure: vi.fn(),
+}));
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+beforeEach(() => {
+  usePlayerStore.setState({ autoKeyframeEnabled: true, currentTime: 1, activeKeyframePct: null });
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+  document.body.innerHTML = "";
+  Reflect.deleteProperty(window, "__timelines");
+});
+
+const positionTween = (id: string, extra: Partial<GsapAnimation> = {}) =>
+  ({
+    id: `#${id}-to-0-position`,
+    targetSelector: `#${id}`,
+    propertyGroup: "position",
+    method: "to",
+    properties: { x: 100 },
+    position: 0,
+    resolvedStart: 0,
+    duration: 2,
+    ease: "none",
+    ...extra,
+  }) as unknown as GsapAnimation;
+
+/** Three members GSAP is visibly moving, one `to` tween each in the file. */
+function mountGroup(animations: GsapAnimation[]) {
+  const elements = ["a", "b", "c"].map((id) => {
+    const el = Object.assign(document.createElement("div"), { id });
+    document.body.append(el);
+    return el;
+  });
+  const live = elements.map((el) => ({
+    targets: () => [el],
+    vars: { x: 100, duration: 2 },
+    duration: () => 2,
+    startTime: () => 0,
+  }));
+  const timelines = { root: { getChildren: () => live, duration: () => 2 } };
+  Reflect.set(window, "__timelines", timelines);
+  const iframe = {
+    contentWindow: { gsap: { getProperty: () => 0, set: vi.fn() }, __timelines: timelines },
+    contentDocument: document,
+  } as unknown as HTMLIFrameElement;
+  const commitMutation = Object.assign(vi.fn().mockResolvedValue(undefined), {
+    batch: vi.fn().mockResolvedValue(undefined),
+  });
+  const showToast = vi.fn();
+  const stageElementPositionOffset = vi.fn(() => ({ save: vi.fn(), rollback: vi.fn() }));
+  const { editing, root } = mountGsapAwareEditing({
+    gsapCommitMutation: commitMutation,
+    activeCompPath: "index.html",
+    previewIframeRef: { current: iframe },
+    showToast,
+    makeFetchFallback: () => async () => animations,
+    stageElementPositionOffset,
+  });
+  const groupCommit = (updates: DomEditGroupPathOffsetCommit[]) =>
+    editing().handleGsapAwareGroupPathOffsetCommit(updates);
+  const updates = elements.map((element) => ({
+    selection: {
+      element,
+      id: element.id,
+      selector: `#${element.id}`,
+    } as unknown as DomEditSelection,
+    next: { x: 30, y: 0 },
+  }));
+  const written = () => [
+    ...commitMutation.mock.calls.map((call) => call[1]),
+    ...commitMutation.batch.mock.calls.flatMap(([calls]) =>
+      calls.map((c: { mutation: unknown }) => c.mutation),
+    ),
+  ];
+  return { elements, iframe, updates, groupCommit, commitMutation, written, showToast, root };
+}
+
+describe("a group drag plans every member before its first write", () => {
+  it("refuses the whole group when one member's tween cannot take a keyframe", async () => {
+    const h = mountGroup([
+      positionTween("a"),
+      positionTween("b", { ease: undefined }),
+      positionTween("c"),
+    ]);
+    const styles = h.elements.map((el) => el.getAttribute("style"));
+
+    await expect(h.groupCommit(h.updates)).rejects.toMatchObject({
+      name: "GsapEditBlockedError",
+      reason: "keyframes-uneditable",
+      detail: "unknown-ease",
+    });
+
+    expect(h.written()).toEqual([]);
+    expect(h.commitMutation.batch).not.toHaveBeenCalled();
+    const gsap = (h.iframe.contentWindow as unknown as { gsap: { set: unknown } }).gsap;
+    expect(gsap.set).not.toHaveBeenCalled();
+    expect(h.elements.map((el) => el.getAttribute("style"))).toEqual(styles);
+    expect(h.showToast).toHaveBeenCalledTimes(1);
+    expect(h.showToast).toHaveBeenCalledWith(GSAP_EDIT_BLOCK_COPY["keyframes-uneditable"], "error");
+    expect(trackStudioEditBlocked).toHaveBeenCalledTimes(1);
+    expect(trackStudioEditBlocked).toHaveBeenCalledWith(expect.objectContaining({ targetId: "b" }));
+    act(() => h.root.unmount());
+  });
+
+  it("refuses members animated in two files, since the batch writes one file", async () => {
+    const h = mountGroup(["a", "b", "c"].map((id) => positionTween(id)));
+    const updates = h.updates.map((u, i) => ({
+      ...u,
+      selection: { ...u.selection, sourceFile: i === 2 ? "scenes/intro.html" : "index.html" },
+    }));
+
+    await expect(h.groupCommit(updates)).rejects.toMatchObject({ reason: "mixed-files" });
+
+    expect(h.written()).toEqual([]);
+    expect(trackStudioEditBlocked).toHaveBeenCalledWith(expect.objectContaining({ targetId: "c" }));
+    act(() => h.root.unmount());
+  });
+
+  it("writes a group whose members name the open file or leave it implied", async () => {
+    const h = mountGroup(["a", "b", "c"].map((id) => positionTween(id)));
+    const updates = h.updates.map((u, i) => ({
+      ...u,
+      selection: { ...u.selection, sourceFile: i === 0 ? "" : "index.html" },
+    }));
+
+    await h.groupCommit(updates);
+
+    expect(h.written()).toHaveLength(3);
+    act(() => h.root.unmount());
+  });
+
+  it("writes every member when each plan holds", async () => {
+    const h = mountGroup(["a", "b", "c"].map((id) => positionTween(id)));
+
+    await h.groupCommit(h.updates);
+
+    const ids = h.written().map((m) => (m as { animationId?: string }).animationId);
+    expect(ids).toEqual(["#a-to-0-position", "#b-to-0-position", "#c-to-0-position"]);
+    expect(h.showToast).not.toHaveBeenCalled();
+    act(() => h.root.unmount());
+  });
+});

package/src/hooks/useGsapAwareEditing.test.tsx

@@ -119,18 +119,21 @@ function mountResizeHandler(
 type AwareEditingParams = Parameters<typeof useGsapAwareEditing>[0];
 
 function mountGroupHandler({
-  gsapCommitMutation,
-  makeFetchFallback,
+  gsapCommitMutation = vi.fn().mockResolvedValue(undefined),
+  makeFetchFallback = () => vi.fn().mockResolvedValue([]),
   trackGsapInteractionFailure = vi.fn(),
   stageElementPositionOffset = vi.fn(),
   handleDomRotationCommit = vi.fn(),
-}: Pick<AwareEditingParams, "gsapCommitMutation" | "makeFetchFallback"> &
-  Partial<
-    Pick<
-      AwareEditingParams,
-      "trackGsapInteractionFailure" | "stageElementPositionOffset" | "handleDomRotationCommit"
-    >
-  >) {
+}: Partial<
+  Pick<
+    AwareEditingParams,
+    | "gsapCommitMutation"
+    | "makeFetchFallback"
+    | "trackGsapInteractionFailure"
+    | "stageElementPositionOffset"
+    | "handleDomRotationCommit"
+  >
+> = {}) {
   let groupCommit!: (
     updates: DomEditGroupPathOffsetCommit[],
   ) => Promise<void | import("../utils/previewFeatureUsage").GeometryCommitResult>;
@@ -216,8 +219,6 @@ describe("useGsapAwareEditing keeps the route a gesture chose at press", () => {
     const save = vi.fn().mockResolvedValue(undefined);
     const stageElementPositionOffset = vi.fn(() => ({ save, rollback: vi.fn() }));
     const { pathOffsetCommit, groupCommit, root } = mountGroupHandler({
-      gsapCommitMutation: vi.fn().mockResolvedValue(undefined),
-      makeFetchFallback: () => vi.fn().mockResolvedValue([]),
       stageElementPositionOffset,
     });
     const box = {
@@ -236,11 +237,7 @@ describe("useGsapAwareEditing keeps the route a gesture chose at press", () => {
 describe("useGsapAwareEditing refuses a group GSAP took over before writing any member", () => {
   it("writes no member when one CSS-route member has been folded since the press", async () => {
     const stageElementPositionOffset = vi.fn(() => ({ save: vi.fn(), rollback: vi.fn() }));
-    const { groupCommit, root } = mountGroupHandler({
-      gsapCommitMutation: vi.fn().mockResolvedValue(undefined),
-      makeFetchFallback: () => vi.fn().mockResolvedValue([]),
-      stageElementPositionOffset,
-    });
+    const { groupCommit, root } = mountGroupHandler({ stageElementPositionOffset });
     const card = {
       element: document.createElement("div"),
       id: "card",
@@ -268,7 +265,6 @@ describe("useGsapAwareEditing rotation routing", () => {
     const gsapCommitMutation = vi.fn();
     const h = mountGroupHandler({
       gsapCommitMutation,
-      makeFetchFallback: () => vi.fn().mockResolvedValue([]),
       handleDomRotationCommit,
     });
     const box = { element, id: "box", selector: "#box" } as unknown as DomEditSelection;
@@ -332,7 +328,6 @@ describe("useGsapAwareEditing shared-tween moves", () => {
     const commitMutation = vi.fn();
     const { pathOffsetCommit, root } = mountGroupHandler({
       gsapCommitMutation: commitMutation,
-      makeFetchFallback: () => vi.fn().mockResolvedValue([]),
       stageElementPositionOffset,
     });
     const word = { element: gsapPositioned("span"), hfId: "w0", selector: ".w" };
@@ -351,11 +346,7 @@ describe("useGsapAwareEditing shared-tween moves", () => {
     });
     const save = vi.fn().mockResolvedValue(undefined);
     const stageElementPositionOffset = vi.fn(() => ({ save, rollback: vi.fn() }));
-    const { groupCommit, root } = mountGroupHandler({
-      gsapCommitMutation: vi.fn().mockResolvedValue(undefined),
-      makeFetchFallback: () => vi.fn().mockResolvedValue([]),
-      stageElementPositionOffset,
-    });
+    const { groupCommit, root } = mountGroupHandler({ stageElementPositionOffset });
     const word = { element: gsapPositioned("span"), hfId: "w0", selector: ".w" };
     const box = { element: gsapPositioned("div"), id: "box", selector: "#box" };
     const plain = { element: document.createElement("div"), id: "plain", selector: "#plain" };
@@ -406,6 +397,7 @@ describe("useGsapAwareEditing anchored resize", () => {
       null,
       expect.any(Function),
       expect.any(Function),
+      undefined,
     );
     act(() => h.root.unmount());
   });
@@ -658,7 +650,6 @@ describe("useGsapAwareEditing anchored resize", () => {
     );
     const { groupCommit, root } = mountGroupHandler({
       gsapCommitMutation: commitMutation,
-      makeFetchFallback: () => vi.fn().mockResolvedValue([]),
     });
     const updates = [
       {
@@ -759,11 +750,7 @@ describe("useGsapAwareEditing anchored resize", () => {
     mocks.drag.mockImplementation(async (selection) => {
       throw selection.id === "a" ? failures[0] : failures[1];
     });
-    const { groupCommit, root } = mountGroupHandler({
-      gsapCommitMutation: vi.fn().mockResolvedValue(undefined),
-      makeFetchFallback: () => vi.fn().mockResolvedValue([]),
-      trackGsapInteractionFailure,
-    });
+    const { groupCommit, root } = mountGroupHandler({ trackGsapInteractionFailure });
     const updates = [
       {
         selection: { element: gsapPositioned("div"), id: "a", selector: "#a" },
@@ -782,6 +769,7 @@ describe("useGsapAwareEditing anchored resize", () => {
       updates[0]?.selection,
       "drag",
       "Move animated layer (group)",
+      true,
     );
     mocks.drag.mockReset();
     if (priorDragImplementation) mocks.drag.mockImplementation(priorDragImplementation);

package/src/hooks/useGsapAwareEditing.testHelpers.tsx

@@ -0,0 +1,42 @@
+import { vi } from "vitest";
+import { mountReactHarness } from "./domSelectionTestHarness";
+import { useGsapAwareEditing } from "./useGsapAwareEditing";
+import { useGsapInteractionFailureTelemetry } from "./useGsapInteractionFailureTelemetry";
+
+type Params = Parameters<typeof useGsapAwareEditing>[0];
+
+/**
+ * Mounts useGsapAwareEditing with no-op callbacks for every param not given, and the real
+ * failure telemetry toasting through `showToast`. `editing()` reads the latest render.
+ */
+export function mountGsapAwareEditing(
+  params: Partial<Omit<Params, "trackGsapInteractionFailure">> & Pick<Params, "showToast">,
+) {
+  let editing!: ReturnType<typeof useGsapAwareEditing>;
+  function Harness() {
+    editing = useGsapAwareEditing({
+      domEditSelection: null,
+      selectedGsapAnimations: [],
+      gsapCommitMutation: vi.fn().mockResolvedValue(undefined),
+      previewIframeRef: { current: null },
+      bumpGsapCache: vi.fn(),
+      makeFetchFallback: () => vi.fn().mockResolvedValue([]),
+      stageElementPositionOffset: vi.fn(),
+      handleDomBoxSizeCommit: vi.fn(),
+      handleDomRotationCommit: vi.fn(),
+      commitPositionPatchToHtml: vi.fn(),
+      addGsapAnimation: vi.fn(),
+      convertToKeyframes: vi.fn(),
+      setArcPath: vi.fn(),
+      updateArcSegment: vi.fn(),
+      ...params,
+      trackGsapInteractionFailure: useGsapInteractionFailureTelemetry(
+        "index.html",
+        params.showToast,
+      ),
+    });
+    return null;
+  }
+  const root = mountReactHarness(<Harness />);
+  return { editing: () => editing, root };
+}

package/src/hooks/useGsapAwareEditing.ts

@@ -49,6 +49,7 @@ export interface UseGsapAwareEditingParams {
   domEditSelection: DomEditSelection | null;
   selectedGsapAnimations: GsapAnimation[];
   gsapCommitMutation: CommitMutation | null;
+  activeCompPath?: string | null;
   previewIframeRef: React.RefObject<HTMLIFrameElement | null>;
   showToast: (message: string, tone?: "error" | "info") => void;
   bumpGsapCache: () => void;
@@ -61,6 +62,7 @@ export interface UseGsapAwareEditingParams {
     selection: DomEditSelection | null,
     mutationType: string,
     label: string,
+    toast?: boolean,
   ) => void;
   // DOM fallbacks (from useDomEditCommits)
   stageElementPositionOffset: (
@@ -117,6 +119,7 @@ export function useGsapAwareEditing({
   domEditSelection,
   selectedGsapAnimations,
   gsapCommitMutation,
+  activeCompPath,
   previewIframeRef,
   showToast,
   bumpGsapCache,
@@ -190,6 +193,7 @@ export function useGsapAwareEditing({
 
   const handleGsapAwareGroupPathOffsetCommit = useGsapAwareGroupMove({
     gsapCommitMutation,
+    activeCompPath,
     previewIframeRef,
     makeFetchFallback,
     trackGsapInteractionFailure,
@@ -285,6 +289,7 @@ export function useGsapAwareEditing({
                 previewIframeRef.current,
                 commitMutation,
                 makeFetchFallback(selection),
+                offset,
               );
               assertGsapEditPersisted(outcome);
               // Saved before the buffered GSAP writes, so their reload stays the gesture's last render.

package/src/hooks/useGsapAwareGroupMove.ts

@@ -9,24 +9,14 @@ import { gsapWritesPosition } from "./gsapRuntimeKeyframes";
 import { refuseGsapTakeover } from "./elementOffsetStager";
 import { tryGsapDragIntercept } from "./gsapRuntimeBridge";
 import { assertGsapEditPersisted } from "./gsapEditOutcome";
+import { firstPreflightFailure } from "./gsapGroupPreflight";
 
 // A distinct key keeps consecutive group drags in separate undo entries.
 let groupDragCommitCounter = 0;
 
-function firstPreflightFailure(
-  results: PromiseSettledResult<void>[],
-  updates: DomEditGroupPathOffsetCommit[],
-): { error: unknown; selection: DomEditSelection } | null {
-  for (const [index, result] of results.entries()) {
-    if (result.status !== "rejected") continue;
-    const selection = updates[index]?.selection;
-    if (selection) return { error: result.reason, selection };
-  }
-  return null;
-}
-
 export function useGsapAwareGroupMove({
   gsapCommitMutation,
+  activeCompPath,
   previewIframeRef,
   makeFetchFallback,
   trackGsapInteractionFailure,
@@ -35,6 +25,7 @@ export function useGsapAwareGroupMove({
 }: Pick<
   UseGsapAwareEditingParams,
   | "gsapCommitMutation"
+  | "activeCompPath"
   | "previewIframeRef"
   | "makeFetchFallback"
   | "trackGsapInteractionFailure"
@@ -44,10 +35,12 @@ export function useGsapAwareGroupMove({
   const handleGsapAwareGroupPathOffsetCommit = useCallback(
     async (
       updates: DomEditGroupPathOffsetCommit[],
+      options: { refusalToast?: boolean } = {},
     ): Promise<import("../utils/previewFeatureUsage").GeometryCommitResult> => {
       const writes = observeGsapGesture(gsapCommitMutation);
       const writer = writes.commit;
       if (!writer) return { ok: true, changed: false };
+      const toastRefusal = options.refusalToast !== false;
       // One coalesce key across slow writes keeps the group drag in one undo entry.
       const coalesceKey = `group-drag:${++groupDragCommitCounter}`;
       // Hold the render until every member is saved, or unwritten members snap back.
@@ -87,16 +80,16 @@ export function useGsapAwareGroupMove({
       // mutation, so a blocked member never leaves earlier siblings partially moved. Preflights
       // write nothing and share one in-flight parse per file, so they run together.
       const preflightResults = await Promise.allSettled(
-        updates.map(async ({ selection, plainTranslate }) => {
+        updates.map(async ({ selection, next, plainTranslate }) => {
           if (plainTranslate ?? !gsapWritesPosition(selection.element)) {
-            refuseGsapTakeover(selection.element, showToast);
+            refuseGsapTakeover(selection.element, toastRefusal ? showToast : () => {});
             return void offsetMembers.set(selection, true);
           }
           const animations = await makeFetchFallback(selection, { failOnFetchError: true })();
           preflightAnimations.set(selection, animations);
           const outcome = await tryGsapDragIntercept(
             selection,
-            { x: 0, y: 0 },
+            next,
             animations,
             previewIframeRef.current,
             coalescedCommit,
@@ -107,13 +100,19 @@ export function useGsapAwareGroupMove({
           assertGsapEditPersisted(outcome);
         }),
       );
-      const preflightFailure = firstPreflightFailure(preflightResults, updates);
+      const preflightFailure = firstPreflightFailure(
+        preflightResults,
+        updates,
+        offsetMembers,
+        activeCompPath,
+      );
       if (preflightFailure) {
         trackGsapInteractionFailure(
           preflightFailure.error,
           preflightFailure.selection,
           "drag",
           "Move animated layer (group)",
+          toastRefusal,
         );
         throw preflightFailure.error;
       }
@@ -167,6 +166,7 @@ export function useGsapAwareGroupMove({
     },
     [
       gsapCommitMutation,
+      activeCompPath,
       previewIframeRef,
       makeFetchFallback,
       trackGsapInteractionFailure,

package/src/hooks/useGsapInteractionFailureTelemetry.ts

@@ -4,8 +4,8 @@ import { trackStudioEditBlocked, trackStudioSaveFailure } from "../utils/studioS
 import { isGsapEditBlockedError } from "./gsapEditOutcome";
 import { wasAlreadyToasted } from "./domEditPersistFailure";
 
-function failureToast(error: unknown): string | null {
-  if (wasAlreadyToasted(error)) return null;
+function failureToast(error: unknown, toast: boolean): string | null {
+  if (!toast || wasAlreadyToasted(error)) return null;
   return isGsapEditBlockedError(error) ? error.message : "Failed to save animated edit.";
 }
 
@@ -14,7 +14,13 @@ export function useGsapInteractionFailureTelemetry(
   showToast: (message: string, tone?: "error" | "info") => void,
 ) {
   return useCallback(
-    (error: unknown, selection: DomEditSelection | null, mutationType: string, label: string) => {
+    (
+      error: unknown,
+      selection: DomEditSelection | null,
+      mutationType: string,
+      label: string,
+      toast?: boolean,
+    ) => {
       const report = isGsapEditBlockedError(error)
         ? trackStudioEditBlocked
         : trackStudioSaveFailure;
@@ -28,7 +34,7 @@ export function useGsapInteractionFailureTelemetry(
         targetSelector: selection?.selector,
         targetSourceFile: selection?.sourceFile,
       });
-      const message = failureToast(error);
+      const message = failureToast(error, toast !== false);
       if (message) showToast(message, "error");
     },
     [activeCompPath, showToast],