@hyperframes/studio 0.7.103 → 0.7.105

package/src/components/editor/useDomEditOverlayGestures.ts

@@ -30,7 +30,6 @@ import {
   type GroupOverlayItem,
   type OverlayRect,
   orientedOverlayRect,
-  resolveDomEditGroupOverlayRect,
 } from "./domEditOverlayGeometry";
 import {
   BLOCKED_MOVE_THRESHOLD_PX,
@@ -50,8 +49,15 @@ import {
   startGroupDrag as _startGroupDrag,
 } from "./domEditOverlayStartGesture";
 import { hugRectForElement } from "./domEditOverlayCrop";
-import { resolveSnapAdjustment, resolveEquidistanceGuides, SNAP_THRESHOLD_PX } from "./snapEngine";
+import {
+  resolveSnapAdjustment,
+  resolveEquidistanceGuides,
+  snapEngagedForTravel,
+  SNAP_THRESHOLD_PX,
+} from "./snapEngine";
 import { logResize, logResizeMove, logResizeSettle } from "../../utils/resizeDebug";
+import { logDrag, logDragSettle, readDragPositions } from "../../utils/dragDebug";
+import { createGroupDragMover } from "./groupDragMove";
 
 export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGesturesOptions) {
   const setDraftOverlayRect = (next: OverlayRect) => {
@@ -91,6 +97,8 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     },
   ) => _startGesture(kind, e, opts, options);
 
+  const moveGroupDrag = createGroupDragMover(opts, setDraftGroupOverlayItems);
+
   // fallow-ignore-next-line complexity
   const onPointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
     const g = opts.gestureRef.current;
@@ -114,55 +122,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     }
 
     if (groupG) {
-      let dx = e.clientX - groupG.startX;
-      let dy = e.clientY - groupG.startY;
-
-      const sc = groupG.snapContext;
-      if (sc?.snapEnabled && sc.targets.length > 0) {
-        const groupBounds = resolveDomEditGroupOverlayRect(
-          groupG.originItems.map((item) => item.rect),
-        );
-        if (groupBounds) {
-          const allTargets = sc.compositionTarget
-            ? [...sc.targets, sc.compositionTarget]
-            : sc.targets;
-          const snap = resolveSnapAdjustment({
-            movingRect: groupBounds,
-            proposedDx: dx,
-            proposedDy: dy,
-            targets: allTargets,
-            gridEdges: sc.gridEdges ?? undefined,
-            threshold: SNAP_THRESHOLD_PX,
-            disabled: e.altKey,
-          });
-          dx = snap.dx;
-          dy = snap.dy;
-          const movedRect = {
-            left: groupBounds.left + dx,
-            top: groupBounds.top + dy,
-            width: groupBounds.width,
-            height: groupBounds.height,
-          };
-          const spacingGuides = e.altKey
-            ? []
-            : resolveEquidistanceGuides({
-                movingRect: movedRect,
-                targets: allTargets,
-                threshold: SNAP_THRESHOLD_PX,
-              });
-          opts.snapGuidesRef.current = { guides: snap.guides, spacingGuides };
-        }
-      }
-      groupG.lastSnappedDx = dx;
-      groupG.lastSnappedDy = dy;
-
-      setDraftGroupOverlayItems(
-        groupG.originItems.map((item) => ({
-          ...item,
-          rect: { ...item.rect, left: item.rect.left + dx, top: item.rect.top + dy },
-        })),
-      );
-      for (const member of groupG.members) applyManualOffsetDragDraft(member, dx, dy);
+      moveGroupDrag(groupG, e);
       return;
     }
 
@@ -215,6 +175,9 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
           movingRect,
           proposedDx: dx,
           proposedDy: dy,
+          // Same reason as the group path: a snap on a drag that has not travelled
+          // yet moves the element while the pointer is still.
+          disabledForTravel: !snapEngagedForTravel(dx, dy),
           targets: allTargets,
           gridEdges: sc.gridEdges ?? undefined,
           threshold: SNAP_THRESHOLD_PX,
@@ -319,9 +282,14 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       opts.rafPausedRef.current = false;
       const rawDx = e.clientX - groupG.startX;
       const rawDy = e.clientY - groupG.startY;
+      // The click that trails every pointerup has to be eaten either way. The
+      // gesture ref is already cleared above, so by the time it arrives the box
+      // no longer looks busy, and handleBoxClick hands it to the canvas as an
+      // ordinary click — which lands between the members, resolves to nothing,
+      // and deselects the group the drag just moved.
+      opts.suppressNextBoxClickRef.current = true;
       if (Math.hypot(rawDx, rawDy) < BLOCKED_MOVE_THRESHOLD_PX) {
         restoreGroupPathOffsets(groupG);
-        opts.suppressNextBoxClickRef.current = true;
         return;
       }
       const dx = groupG.lastSnappedDx ?? rawDx;
@@ -336,6 +304,17 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         selection: member.selection,
         next: applyManualOffsetDragCommit(member, dx, dy),
       }));
+      logDrag("drop", {
+        pointer: `${Math.round(rawDx)},${Math.round(rawDy)}`,
+        applied: `${Math.round(dx)},${Math.round(dy)}`,
+        committed: Object.fromEntries(
+          updates.map((update, index) => [
+            groupG.members[index]?.key ?? String(index),
+            `${Math.round(update.next.x)},${Math.round(update.next.y)}`,
+          ]),
+        ),
+        at: readDragPositions(groupG.members),
+      });
       void Promise.resolve(opts.onGroupPathOffsetCommitRef.current(updates))
         .catch(() => {
           for (const member of groupG.members) {
@@ -346,7 +325,15 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
               restoreStudioPathOffset(member.element, member.initialPathOffset);
           }
         })
-        .finally(() => endManualOffsetDragMembers(groupG.members));
+        .finally(() => {
+          logDrag("committed", { at: readDragPositions(groupG.members) });
+          endManualOffsetDragMembers(groupG.members);
+          // The gesture teardown resumes the paused timelines and re-seeks the
+          // player, which re-renders from whatever the preview currently holds.
+          // If the reloaded source has not landed yet that is the OLD position,
+          // so this is where a snap-back would show.
+          logDragSettle("settle", groupG.members);
+        });
       return;
     }
 

package/src/components/editor/useDomEditOverlayRects.ts

@@ -17,7 +17,7 @@ import {
   rectsEqual,
   resolveElementForOverlay,
   selectionCacheKey,
-  toVisibleOverlayRect,
+  orientedVisibleOverlayRect,
 } from "./domEditOverlayGeometry";
 
 function childRectsEqual(a: OverlayRect[], b: OverlayRect[]): boolean {
@@ -172,7 +172,9 @@ export function useDomEditOverlayRects({
             for (let i = 0; i < descendants.length; i++) {
               const child = descendants[i] as HTMLElement;
               if (!child.getBoundingClientRect) continue;
-              const r = toVisibleOverlayRect(overlayEl, iframe, child);
+              // Oriented, not axis-aligned: a child of a rotated element drew its
+              // outline square around the rotated glyphs instead of on them.
+              const r = orientedVisibleOverlayRect(overlayEl, iframe, child);
               if (r && r.width > 2 && r.height > 2) nextChildRects.push(r);
             }
             if (!childRectsEqual(childRectsRef.current, nextChildRects)) {

package/src/hooks/domSelectionTimelineMirror.ts

@@ -0,0 +1,73 @@
+import type { SelectElementOptions, TimelineElement } from "../player";
+import { findMatchingTimelineElementId, findTimelineIdByAncestor } from "../utils/studioHelpers";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { logSelect } from "../utils/selectDebug";
+
+interface TimelineMirrorDeps {
+  timelineElements: TimelineElement[];
+  getTimelineSelectionSet: () => ReadonlySet<string>;
+  setSelectedTimelineElementId: (id: string | null, options?: SelectElementOptions) => void;
+  setTimelineSelectionSet: (ids: Set<string>) => void;
+}
+
+/**
+ * Mirror a canvas selection onto the timeline: the whole set first, then the
+ * primary as its anchor.
+ *
+ * The timeline is the source of truth for what is selected and it syncs back —
+ * whatever it holds replaces the canvas selection a moment later. Announcing only
+ * the primary therefore drops every other member. Worse, anchoring with
+ * `preserveSet` on an id the set does not yet contain empties the set outright,
+ * and an empty set syncs back as "nothing is selected" — which is how adding a
+ * second element, or moving a group, could wipe the selection instead of keeping
+ * it. Publishing the members first is what makes the anchor a member, so
+ * preserving the set is meaningful rather than destructive.
+ */
+export function announceTimelineSelection(
+  deps: TimelineMirrorDeps,
+  group: DomEditSelection[],
+  primary: DomEditSelection | null,
+): void {
+  const {
+    timelineElements,
+    getTimelineSelectionSet,
+    setSelectedTimelineElementId,
+    setTimelineSelectionSet,
+  } = deps;
+  if (!primary) {
+    setTimelineSelectionSet(new Set());
+    setSelectedTimelineElementId(null);
+    return;
+  }
+  const timelineIdFor = (selection: DomEditSelection) =>
+    findMatchingTimelineElementId(selection, timelineElements) ??
+    findTimelineIdByAncestor(
+      selection.element,
+      timelineElements,
+      selection.sourceFile || "index.html",
+    );
+  const members = group.map(timelineIdFor).filter((id): id is string => Boolean(id));
+  const anchor = timelineIdFor(primary);
+  const publishedMembers = new Set(members);
+  if (anchor) publishedMembers.add(anchor);
+  const timelineAnchor = anchor ?? members[0] ?? null;
+  // A member with no timeline row of its own resolves to null and is dropped here,
+  // so a group can announce fewer ids than it has — or none, which reads back as an
+  // empty selection and takes the canvas selection with it.
+  logSelect("announce", {
+    group: group.length,
+    published: publishedMembers.size,
+    anchor,
+    anchorPublished: anchor != null && publishedMembers.has(anchor),
+  });
+  // A canvas target can be editable without owning a timeline row. Preserve that
+  // canvas-only selection when the timeline has nothing truthful to represent.
+  if (!timelineAnchor) return;
+  // A late async primary that already belongs to the live set must preserve the
+  // group. A fresh single click does not belong to it, so publish the singleton
+  // first; otherwise `preserveSet` clears the set and sync wipes the canvas.
+  if (group.length > 1 || !getTimelineSelectionSet().has(timelineAnchor)) {
+    setTimelineSelectionSet(publishedMembers);
+  }
+  setSelectedTimelineElementId(timelineAnchor, { preserveSet: true });
+}

package/src/hooks/gestureTransaction.test.ts

@@ -36,6 +36,7 @@ function runTwoMutationTransaction(
 describe("runGestureTransaction", () => {
   beforeEach(() => {
     trackStudioEventMock.mockReset();
+    localStorage.clear();
   });
 
   it("settles synchronously before persist reaches its first await", async () => {
@@ -249,7 +250,7 @@ describe("runGestureTransaction", () => {
       .spyOn(element, "getBoundingClientRect")
       .mockReturnValueOnce(rect(10.04, 20.05, 100.05, 80.05))
       .mockReturnValueOnce(rect(11.19, 17.89, 100.29, 78.99));
-    const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
     const now = vi.spyOn(performance, "now").mockReturnValueOnce(50).mockReturnValueOnce(58.44);
 
     await runGestureTransaction({
@@ -261,13 +262,7 @@ describe("runGestureTransaction", () => {
     });
 
     expect(getRect).toHaveBeenCalledTimes(2);
-    expect(error).toHaveBeenCalledWith(
-      "[hf-commit] persist changed pixels",
-      expect.objectContaining({
-        label: "Resize layer",
-        delta: expect.objectContaining({ x: expect.any(Number) }),
-      }),
-    );
+    expect(log).not.toHaveBeenCalled();
     expect(trackStudioEventMock).toHaveBeenCalledWith("commit_invariant_violation", {
       label: "Resize layer",
       delta_x: 1.2,
@@ -283,13 +278,13 @@ describe("runGestureTransaction", () => {
       expect.objectContaining({ pixel_asserted: true }),
     );
     now.mockRestore();
-    error.mockRestore();
+    log.mockRestore();
   });
 
   it("skips the pixel assertion for live position tweens", async () => {
     const element = document.createElement("div");
     const getRect = vi.spyOn(element, "getBoundingClientRect");
-    const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
 
     await runGestureTransaction({
       element,
@@ -301,11 +296,11 @@ describe("runGestureTransaction", () => {
     });
 
     expect(getRect).not.toHaveBeenCalled();
-    expect(error).not.toHaveBeenCalledWith("[hf-commit] persist changed pixels", expect.anything());
+    expect(log).not.toHaveBeenCalled();
     expect(trackStudioEventMock).not.toHaveBeenCalledWith(
       "commit_invariant_violation",
       expect.anything(),
     );
-    error.mockRestore();
+    log.mockRestore();
   });
 });

package/src/hooks/gestureTransaction.ts

@@ -4,6 +4,7 @@ import type {
   CommitMutationOptions,
 } from "./gsapScriptCommitTypes";
 import { trackStudioEvent } from "../utils/studioTelemetry";
+import { makeStudioDebugLogger } from "../utils/studioDebug";
 
 type PixelRect = Pick<DOMRect, "x" | "y" | "width" | "height">;
 
@@ -108,14 +109,7 @@ async function dispatchBufferedCommits(calls: BufferedCommit[]): Promise<number>
   return reloadsRequested(calls);
 }
 
-/**
- * Dev-only [hf-commit] lifecycle trace. The production observability lives in
- * the trackStudioEvent commit_* events (always on); these console lines are a
- * developer aid and stay out of end users' consoles.
- */
-function traceCommit(stage: string, data: Record<string, unknown>): void {
-  if (import.meta.env.DEV) console.info(`[hf-commit] ${stage}`, data);
-}
+const logCommit = makeStudioDebugLogger("commit");
 
 /**
  * Owns the visual + persistence + history lifecycle for one gesture release.
@@ -127,9 +121,9 @@ export function runGestureTransaction(tx: GestureTransaction): Promise<void> {
   let mutationCount = 0;
   let reloadCount = 0;
   const bufferedCommits: BufferedCommit[] = [];
-  traceCommit("start", { label: tx.label, coalesceKey });
+  logCommit("start", { label: tx.label, coalesceKey });
   tx.settle();
-  traceCommit("settled", { label: tx.label, coalesceKey });
+  logCommit("settled", { label: tx.label, coalesceKey });
 
   const before = !tx.skipPixelAssert ? readPixelRect(tx.element) : null;
   const commit: TxCommit = (commitMutation) => {
@@ -152,19 +146,12 @@ export function runGestureTransaction(tx: GestureTransaction): Promise<void> {
     .then(async () => {
       reloadCount = await dispatchBufferedCommits(bufferedCommits);
       const durationMs = Math.round(performance.now() - startedAt);
-      traceCommit("persisted", { label: tx.label, coalesceKey });
+      logCommit("persisted", { label: tx.label, coalesceKey });
       if (before) {
         const after = readPixelRect(tx.element);
         const delta = pixelDelta(before, after);
         if (exceedsPixelTolerance(delta)) {
-          if (import.meta.env.DEV) {
-            console.error("[hf-commit] persist changed pixels", {
-              label: tx.label,
-              before,
-              after,
-              delta,
-            });
-          }
+          logCommit("persist-changed-pixels", { label: tx.label, before, after, delta });
           trackStudioEvent("commit_invariant_violation", {
             label: tx.label,
             delta_x: roundToOneDecimal(delta.x),
@@ -193,7 +180,7 @@ export function runGestureTransaction(tx: GestureTransaction): Promise<void> {
         error_name: error instanceof Error ? error.name : "unknown",
         restore_ran: true,
       });
-      traceCommit("restore", { label: tx.label, coalesceKey });
+      logCommit("restore", { label: tx.label, coalesceKey });
       throw error;
     });
 }

package/src/hooks/gsapRuntimePatch.test.ts

@@ -523,3 +523,46 @@ describe("patchRuntimeTweenInPlace — composition isolation", () => {
     expect(otherTween.invalidate).not.toHaveBeenCalled();
   });
 });
+
+describe("patchRuntimeTweenInPlace — deferSeek", () => {
+  /**
+   * A group drag commits one member at a time. Each in-place patch used to seek,
+   * and a seek re-renders the WHOLE timeline — so every member still queued behind
+   * the current one got repainted from its un-patched tween, back to where it sat
+   * before the drag, and stayed there until its own patch landed. That is the jump.
+   */
+  it("does not seek while a group commit is still writing its other members", () => {
+    const a = { id: "a" };
+    const rendered = { a: 0, b: 0 };
+    const tweenA = makeTween({ vars: { x: 0 }, targetIds: ["a"], duration: 0 }, a);
+    const tweenB = makeTween({ vars: { x: 0 }, targetIds: ["b"], duration: 0 }, a);
+    const { iframe, seek } = fakeIframe(a, [tweenA, tweenB], {
+      onSeek: () => {
+        rendered.a = tweenA.vars.x as number;
+        rendered.b = tweenB.vars.x as number;
+      },
+    });
+
+    const first = patchRuntimeTweenInPlace(
+      iframe,
+      "#a",
+      { kind: "set", props: { x: 500 } },
+      undefined,
+      true,
+    );
+
+    expect(first).toBe(true);
+    expect(tweenA.vars.x).toBe(500);
+    // No repaint yet: "b" keeps the transform the gesture left on it instead of
+    // being rendered from its own tween, which still holds the pre-drag value.
+    expect(seek).not.toHaveBeenCalled();
+    expect(rendered).toEqual({ a: 0, b: 0 });
+
+    tweenB.vars.x = 600;
+    const last = patchRuntimeTweenInPlace(iframe, "#a", { kind: "set", props: { x: 500 } });
+
+    expect(last).toBe(true);
+    expect(seek).toHaveBeenCalledTimes(1);
+    expect(rendered).toEqual({ a: 500, b: 600 });
+  });
+});

package/src/hooks/gsapRuntimePatch.ts

@@ -277,12 +277,16 @@ function applyChange(tween: RuntimeTween, change: RuntimeTweenChange): boolean {
 /**
  * Edit one tween in `window.__timelines` in place + re-seek to the current playhead.
  * Returns `true` on a confident patch, `false` otherwise (caller soft-reloads).
+ *
+ * `deferSeek` skips the re-render, for a caller patching several tweens in a row
+ * that will render once after the last one.
  */
 export function patchRuntimeTweenInPlace(
   iframe: HTMLIFrameElement | null,
   selector: string,
   change: RuntimeTweenChange,
   compositionId?: string,
+  deferSeek = false,
 ): boolean {
   if (!iframe) return false;
   // A base `gsap.set` has no timeline tween to resolve — apply the value straight
@@ -312,7 +316,13 @@ export function patchRuntimeTweenInPlace(
     if (change.kind !== "keyframe-rebuild") {
       tween.invalidate?.();
     }
-    seekToCurrent(iframe, timeline);
+    // A seek re-renders the WHOLE timeline, not just the tween we patched. Under a
+    // multi-element commit that is a visible jump: the members still queued behind
+    // this one get repainted from their un-patched tweens, back to where they were
+    // before the gesture, and stay there until their own patch lands. Deferring
+    // leaves them showing the gesture's own transform, and the caller's last patch
+    // seeks once for the whole group.
+    if (!deferSeek) seekToCurrent(iframe, timeline);
     return true;
   } catch {
     return false;

package/src/hooks/gsapScriptCommitHelpers.ts

@@ -3,6 +3,7 @@ import type { DomEditSelection } from "../components/editor/domEditingTypes";
 
 export { PROPERTY_DEFAULTS } from "./gsapShared";
 import { idSelector, matchesExactlyOne } from "./gsapShared";
+import { studioWriteHeaders } from "../utils/studioFileVersion";
 
 /**
  * The selector to author a NEW tween against, minting an id on the element when
@@ -119,7 +120,7 @@ export async function assignGsapTargetAutoIdIfNeeded({
     `/api/projects/${encodeURIComponent(projectId)}/file-mutations/patch-element/${encodeURIComponent(targetPath)}`,
     {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
       body: JSON.stringify(patchBody),
     },
   );

package/src/hooks/gsapScriptCommitTypes.ts

@@ -22,6 +22,18 @@ export interface CommitMutationOptions {
   coalesceMs?: number;
   softReload?: boolean;
   skipReload?: boolean;
+  /**
+   * Write the source but leave the preview alone; the caller renders once when it
+   * is done. For a multi-write action like a group drag, rendering after each
+   * write shows a source where the members not yet written still hold their old
+   * values, so they snap back until their own write lands. This also defers the
+   * in-place runtime patch's seek, which re-renders the whole timeline and repaints
+   * the queued members the same way. Unlike `skipReload` this changes nothing about
+   * error handling — a failed write still throws.
+   */
+  deferPreviewSync?: boolean;
+  /** Shares an in-place patch miss with the final render of one multi-write action. */
+  previewFallbackLatch?: { pending: boolean };
   beforeReload?: () => void;
   /**
    * Serialize this commit against others sharing the same key. Used to chain
@@ -39,6 +51,14 @@ export interface CommitMutationOptions {
    * existing soft/full reload path. Structural edits omit this and reload as before.
    */
   instantPatch?: { selector: string; change: RuntimeTweenChange };
+  /**
+   * The same fast path for a batched commit: one patch per element the batch
+   * wrote, applied in order. All of them must land for the reload to be skipped
+   * — one that can't be applied leaves the preview half-patched, so the whole
+   * batch falls back to the reload. Only the last patch re-renders (see
+   * `deferSeek`), so a ten-element batch repaints once.
+   */
+  instantPatches?: Array<{ selector: string; change: RuntimeTweenChange }>;
 }
 
 export interface CommitMutationCall {

package/src/hooks/keyframeCacheAstLoad.test.ts

@@ -0,0 +1,108 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { fetchParsedAnimations } from "./keyframeCacheAstLoad";
+
+/**
+ * Parsing a composition is a whole-file read + parse on the server, and a
+ * multi-element action asks for the same file once per element. Callers that
+ * overlap in time share one request; a caller that comes after the last one
+ * settled does not, so a parse issued after a write is never served a
+ * pre-write answer.
+ */
+describe("fetchParsedAnimations — in-flight sharing", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function stubFetch(): { calls: () => number; settle: () => void } {
+    let calls = 0;
+    const pending: Array<() => void> = [];
+    vi.stubGlobal("fetch", () => {
+      calls++;
+      return new Promise((resolve) => {
+        pending.push(() =>
+          resolve({
+            ok: true,
+            json: () => Promise.resolve({ animations: [{ id: "a", targetSelector: "#a" }] }),
+          } as Response),
+        );
+      });
+    });
+    return {
+      calls: () => calls,
+      settle: () => {
+        for (const release of pending.splice(0, pending.length)) release();
+      },
+    };
+  }
+
+  it("serves overlapping reads of one file from a single request", async () => {
+    const fetchStub = stubFetch();
+
+    const pending = [
+      fetchParsedAnimations("p", "index.html"),
+      fetchParsedAnimations("p", "index.html"),
+      fetchParsedAnimations("p", "index.html"),
+    ];
+    fetchStub.settle();
+    const results = await Promise.all(pending);
+
+    expect(fetchStub.calls()).toBe(1);
+    expect(results.map((parsed) => parsed?.animations.length)).toEqual([1, 1, 1]);
+  });
+
+  it("does not share across files", async () => {
+    const fetchStub = stubFetch();
+
+    const pending = [
+      fetchParsedAnimations("p", "index.html"),
+      fetchParsedAnimations("p", "other.html"),
+    ];
+    fetchStub.settle();
+    await Promise.all(pending);
+
+    expect(fetchStub.calls()).toBe(2);
+  });
+
+  it("re-requests once the previous read has settled", async () => {
+    const fetchStub = stubFetch();
+
+    const first = fetchParsedAnimations("p", "index.html");
+    fetchStub.settle();
+    await first;
+    const second = fetchParsedAnimations("p", "index.html");
+    fetchStub.settle();
+    await second;
+
+    expect(fetchStub.calls()).toBe(2);
+  });
+
+  it("supersedes an in-flight pre-write parse with a fresh post-write read", async () => {
+    const releases: Array<(response: Response) => void> = [];
+    const fetch = vi.fn(
+      () =>
+        new Promise<Response>((resolve) => {
+          releases.push(resolve);
+        }),
+    );
+    vi.stubGlobal("fetch", fetch);
+    const response = (id: string) =>
+      ({
+        ok: true,
+        json: () => Promise.resolve({ animations: [{ id, targetSelector: `#${id}` }] }),
+      }) as Response;
+
+    const stale = fetchParsedAnimations("p", "index.html");
+    const fresh = fetchParsedAnimations("p", "index.html", { fresh: true });
+    expect(fetch).toHaveBeenCalledTimes(2);
+
+    releases[0]?.(response("stale"));
+    await stale;
+    const overlappingFreshRead = fetchParsedAnimations("p", "index.html");
+    expect(fetch).toHaveBeenCalledTimes(2);
+
+    releases[1]?.(response("fresh"));
+    const [freshResult, sharedResult] = await Promise.all([fresh, overlappingFreshRead]);
+    expect(freshResult?.animations[0]?.id).toBe("fresh");
+    expect(sharedResult?.animations[0]?.id).toBe("fresh");
+  });
+});

package/src/hooks/keyframeCacheAstLoad.ts

@@ -42,7 +42,35 @@ function hasAnimations(value: unknown): value is ParsedGsapAnimations {
   );
 }
 
-export async function fetchParsedAnimations(
+/**
+ * Requests for the same file that overlap in time, keyed `projectId|sourceFile`.
+ *
+ * Every parse re-reads and re-parses the whole composition server-side, and a
+ * multi-element action asks for the same file once per element. Sharing the
+ * in-flight promise makes that one request. Only OVERLAPPING calls share: the
+ * entry is dropped the moment it settles, so a call made after a write still
+ * gets a fresh parse.
+ */
+const inFlightParses = new Map<string, Promise<ParsedGsapAnimations | null>>();
+
+export function fetchParsedAnimations(
+  projectId: string,
+  sourceFile: string,
+  options: { fresh?: boolean } = {},
+): Promise<ParsedGsapAnimations | null> {
+  const key = `${projectId}|${sourceFile}`;
+  if (options.fresh) inFlightParses.delete(key);
+  const inFlight = inFlightParses.get(key);
+  if (inFlight) return inFlight;
+  const request = requestParsedAnimations(projectId, sourceFile).finally(() => {
+    // A superseded pre-write request must not evict the fresh post-write one.
+    if (inFlightParses.get(key) === request) inFlightParses.delete(key);
+  });
+  inFlightParses.set(key, request);
+  return request;
+}
+
+async function requestParsedAnimations(
   projectId: string,
   sourceFile: string,
 ): Promise<ParsedGsapAnimations | null> {

package/src/hooks/timelineTimingSync.ts

@@ -7,6 +7,7 @@ import { applySoftReload, applySoftReloadFinalization } from "../utils/gsapSoftR
 import { furthestClipEndFromDocument } from "../player/lib/timelineElementHelpers";
 import type { RecordEditInput } from "../utils/studioFileHistory";
 import { patchDocumentRootDuration } from "./timelineEditingGsap";
+import { studioWriteHeaders } from "../utils/studioFileVersion";
 
 class GsapPreviewConvergenceError extends Error {}
 class GsapOwnershipProtocolError extends GsapPreviewConvergenceError {}
@@ -58,6 +59,8 @@ async function rollbackOwnedMutation(
     `/api/projects/${encodeURIComponent(projectId)}/gsap-mutation-rollback/${encodeURIComponent(targetPath)}`,
     {
       method: "POST",
+      // Deliberately unclaimed: a rollback runs because a mutation did not
+      // converge, so let the restored file reload the preview.
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ expected, restore }),
     },
@@ -156,7 +159,7 @@ async function postGsapMutation(
       `/api/projects/${encodeURIComponent(projectId)}/gsap-mutations/${encodeURIComponent(filePath)}`,
       {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
+        headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
         body: JSON.stringify(mutation),
       },
     );