@hyperframes/studio 0.8.104 → 0.8.106

package/src/components/editor/domEditOverlayStartGesture.ts

@@ -12,6 +12,7 @@ import {
 import { readCssRotationTarget, readRotationBase } from "./rotationDraft";
 import {
   beginStudioManualEditGesture,
+  endStudioManualEditGesture,
   captureStudioBoxSize,
   captureStudioPathOffset,
   captureStudioRotation,
@@ -81,48 +82,54 @@ export function startGroupDrag(
     }
     members.push(result.member);
   }
-  resetDragMoveLog();
-  logDrag("group-start", {
-    // A member whose mapping differs from its neighbours travels a different
-    // distance for the same pointer delta, which is the group coming apart.
-    members: Object.fromEntries(
-      members.map((member) => [
-        member.key,
-        {
-          map: `${member.screenToOffset.a.toFixed(3)},${member.screenToOffset.d.toFixed(3)}`,
-          base: `${Math.round(member.baseGsap.x)},${Math.round(member.baseGsap.y)}`,
-          offset: `${Math.round(member.initialOffset.x)},${Math.round(member.initialOffset.y)}`,
-        },
-      ]),
-    ),
-    at: readDragPositions(members),
-  });
+  try {
+    resetDragMoveLog();
+    logDrag("group-start", {
+      // A member whose mapping differs from its neighbours travels a different
+      // distance for the same pointer delta, which is the group coming apart.
+      members: Object.fromEntries(
+        members.map((member) => [
+          member.key,
+          {
+            map: `${member.screenToOffset.a.toFixed(3)},${member.screenToOffset.d.toFixed(3)}`,
+            base: `${Math.round(member.baseGsap.x)},${Math.round(member.baseGsap.y)}`,
+            offset: `${Math.round(member.initialOffset.x)},${Math.round(member.initialOffset.y)}`,
+          },
+        ]),
+      ),
+      at: readDragPositions(members),
+    });
 
-  const overlayEl = opts.overlayRef.current;
-  const iframe = opts.iframeRef.current;
-  const snapContext =
-    overlayEl && iframe
-      ? collectSnapContext({
-          overlayEl,
-          iframe,
-          excludeElements: buildExcludeElements({
+    const overlayEl = opts.overlayRef.current;
+    const iframe = opts.iframeRef.current;
+    const snapContext =
+      overlayEl && iframe
+        ? collectSnapContext({
+            overlayEl,
             iframe,
-            groupSelections: items.map((i) => i.selection),
-          }),
-        })
-      : undefined;
+            excludeElements: buildExcludeElements({
+              iframe,
+              groupSelections: items.map((i) => i.selection),
+            }),
+          })
+        : undefined;
 
-  e.preventDefault();
-  e.stopPropagation();
-  e.currentTarget.setPointerCapture(e.pointerId);
-  opts.rafPausedRef.current = true;
-  opts.groupGestureRef.current = {
-    startX: e.clientX,
-    startY: e.clientY,
-    originItems: items,
-    members,
-    snapContext,
-  };
+    e.preventDefault();
+    e.stopPropagation();
+    e.currentTarget.setPointerCapture(e.pointerId);
+    opts.rafPausedRef.current = true;
+    opts.groupGestureRef.current = {
+      startX: e.clientX,
+      startY: e.clientY,
+      originItems: items,
+      members,
+      snapContext,
+    };
+  } catch (error) {
+    opts.groupGestureRef.current = null;
+    restoreManualOffsetDragMembers(members);
+    throw error;
+  }
   return true;
 }
 
@@ -219,84 +226,89 @@ export function startGesture(
     }
   }
 
-  // Rotation base: the angle the element shows. An element GSAP does not turn, or a plain-translate
-  // move, never asks GSAP: reading a property makes it bake the CSS into its transform.
-  const plain = !!pathOffsetMember?.plainTranslate || !gsapWritesRotation(sel.element);
-  const plainRotation = plain && kind === "rotate" ? readCssRotationTarget(sel.element) : null;
-  const rotation = { angle: readRotationBase(sel.element, plain) };
-  const overlayBounds = overlayEl?.getBoundingClientRect();
-  const centerX = (overlayBounds?.left ?? 0) + rect.left + rect.width / 2;
-  const centerY = (overlayBounds?.top ?? 0) + rect.top + rect.height / 2;
+  // A throw before the gesture is armed would leave its mark, and the mark holds every reload.
+  try {
+    // Rotation base: the angle the element shows. An element GSAP does not turn, or a plain-translate
+    // move, never asks GSAP: reading a property makes it bake the CSS into its transform.
+    const plain = !!pathOffsetMember?.plainTranslate || !gsapWritesRotation(sel.element);
+    const plainRotation = plain && kind === "rotate" ? readCssRotationTarget(sel.element) : null;
+    const rotation = { angle: readRotationBase(sel.element, plain) };
+    const overlayBounds = overlayEl?.getBoundingClientRect();
+    const centerX = (overlayBounds?.left ?? 0) + rect.left + rect.width / 2;
+    const centerY = (overlayBounds?.top ?? 0) + rect.top + rect.height / 2;
 
-  const iframe = opts.iframeRef.current;
+    const iframe = opts.iframeRef.current;
 
-  // For a center-anchored corner resize, capture the element's rendered CENTER (the
-  // centroid of its four real, rotation-aware corners) now, so per-frame anchoring
-  // can pin that exact point instead of an axis-aligned width/height delta (which
-  // only holds the center still when the element grows symmetrically from an
-  // unrotated layout box). Present whenever an anchor member exists (all corners).
-  let resizeFixedCenterStart: { x: number; y: number } | undefined;
-  if (kind === "resize" && pathOffsetMember && overlayEl && iframe) {
-    const corners = elementCornerOverlayPoints(overlayEl, iframe, sel.element);
-    if (corners) resizeFixedCenterStart = overlayCornersCentroid(corners);
-  }
-  const snapContext =
-    (kind === "drag" || kind === "resize") && overlayEl && iframe
-      ? collectSnapContext({
-          overlayEl,
-          iframe,
-          excludeElements: buildExcludeElements({ iframe, selection: sel }),
-        })
-      : undefined;
-  e.preventDefault();
-  e.stopPropagation();
-  e.currentTarget.setPointerCapture(e.pointerId);
-  opts.rafPausedRef.current = true;
-  opts.gestureRef.current = {
-    kind,
-    mode,
-    selection: sel,
-    startX: e.clientX,
-    startY: e.clientY,
-    centerX,
-    centerY,
-    initialPathOffset,
-    initialRotation: captureStudioRotation(sel.element),
-    initialBoxSize: captureStudioBoxSize(sel.element),
-    pathOffsetMember,
-    originLeft: rect.left,
-    originTop: rect.top,
-    originWidth: rect.width,
-    originHeight: rect.height,
-    actualWidth,
-    actualHeight,
-    actualRotation: rotation.angle,
-    plainRotation,
-    editScaleX: rect.editScaleX,
-    editScaleY: rect.editScaleY,
-    contentScaleX,
-    contentScaleY,
-    manualEditDragToken,
-    snapContext,
-    resizeHandle: kind === "resize" ? (options?.resizeHandle ?? "se") : undefined,
-    resizeFixedCenterStart,
-  };
-  if (kind === "resize") {
-    resetResizeMoveLog();
-    logResize("start", {
-      handle: options?.resizeHandle ?? "se",
-      pointer: { x: e.clientX, y: e.clientY },
-      center: { x: centerX, y: centerY },
-      origin: { left: rect.left, top: rect.top, w: rect.width, h: rect.height },
-      actual: { w: actualWidth, h: actualHeight },
-      editScale: { x: rect.editScaleX, y: rect.editScaleY },
-      contentScale: { x: contentScaleX, y: contentScaleY },
-      rotation: rotation.angle,
-      hasOffsetMember: !!pathOffsetMember,
-      fixedCenterStart: resizeFixedCenterStart ?? null,
-      initialBoxSize: opts.gestureRef.current?.initialBoxSize ?? null,
-      initialInlineStyle: sel.element.getAttribute("style"),
-    });
+    // A corner resize pins the centroid of the four rotation-aware corners: an axis-aligned
+    // size delta only holds the centre still for a symmetric, unrotated growth.
+    let resizeFixedCenterStart: { x: number; y: number } | undefined;
+    if (kind === "resize" && pathOffsetMember && overlayEl && iframe) {
+      const corners = elementCornerOverlayPoints(overlayEl, iframe, sel.element);
+      if (corners) resizeFixedCenterStart = overlayCornersCentroid(corners);
+    }
+    const snapContext =
+      (kind === "drag" || kind === "resize") && overlayEl && iframe
+        ? collectSnapContext({
+            overlayEl,
+            iframe,
+            excludeElements: buildExcludeElements({ iframe, selection: sel }),
+          })
+        : undefined;
+    e.preventDefault();
+    e.stopPropagation();
+    e.currentTarget.setPointerCapture(e.pointerId);
+    opts.rafPausedRef.current = true;
+    opts.gestureRef.current = {
+      kind,
+      mode,
+      selection: sel,
+      startX: e.clientX,
+      startY: e.clientY,
+      centerX,
+      centerY,
+      initialPathOffset,
+      initialRotation: captureStudioRotation(sel.element),
+      initialBoxSize: captureStudioBoxSize(sel.element),
+      pathOffsetMember,
+      originLeft: rect.left,
+      originTop: rect.top,
+      originWidth: rect.width,
+      originHeight: rect.height,
+      actualWidth,
+      actualHeight,
+      actualRotation: rotation.angle,
+      plainRotation,
+      editScaleX: rect.editScaleX,
+      editScaleY: rect.editScaleY,
+      contentScaleX,
+      contentScaleY,
+      manualEditDragToken,
+      snapContext,
+      resizeHandle: kind === "resize" ? (options?.resizeHandle ?? "se") : undefined,
+      resizeFixedCenterStart,
+    };
+    if (kind === "resize") {
+      resetResizeMoveLog();
+      logResize("start", {
+        handle: options?.resizeHandle ?? "se",
+        pointer: { x: e.clientX, y: e.clientY },
+        center: { x: centerX, y: centerY },
+        origin: { left: rect.left, top: rect.top, w: rect.width, h: rect.height },
+        actual: { w: actualWidth, h: actualHeight },
+        editScale: { x: rect.editScaleX, y: rect.editScaleY },
+        contentScale: { x: contentScaleX, y: contentScaleY },
+        rotation: rotation.angle,
+        hasOffsetMember: !!pathOffsetMember,
+        fixedCenterStart: resizeFixedCenterStart ?? null,
+        initialBoxSize: opts.gestureRef.current?.initialBoxSize ?? null,
+        initialInlineStyle: sel.element.getAttribute("style"),
+      });
+    }
+  } catch (error) {
+    opts.gestureRef.current = null;
+    if (pathOffsetMember) restoreManualOffsetDragMembers([pathOffsetMember]);
+    else if (manualEditDragToken) endStudioManualEditGesture(sel.element, manualEditDragToken);
+    throw error;
   }
   return true;
 }

package/src/components/editor/easeCurveSvg.tsx

@@ -56,7 +56,7 @@ export function MiniCurveSvg({
       <path
         d={d}
         fill="none"
-        stroke={active ? "#3CE6AC" : "#737373"}
+        className={active ? "stroke-accent-ink" : "stroke-text-muted"}
         strokeWidth="1.5"
         strokeLinecap="round"
       />

package/src/components/editor/gestureHoldsPreviewReload.test.tsx

@@ -0,0 +1,275 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { makeSelection } from "../../hooks/domSelectionTestHarness";
+import { useInlineTextEdit } from "../../hooks/useInlineTextEdit";
+import {
+  makePreview,
+  mountPlayerWithPreview,
+  paintShadow,
+  resetPlayerStore,
+  type TimelinePlayerApi,
+} from "../../player/hooks/timelinePlayerTestHarness";
+import type { DomEditSelection } from "./domEditing";
+import "./domEditOverlayTestMocks";
+import { DomEditOverlay } from "./DomEditOverlay";
+import { PreviewReadOnlyProvider } from "./previewReadOnlyContext";
+import { STUDIO_MANUAL_EDIT_GESTURE_ATTR } from "./manualEditsTypes";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const layout = vi.hoisted(() => ({
+  group: [] as unknown[],
+  rect: { left: 100, top: 100, width: 200, height: 100, editScaleX: 1, editScaleY: 1 },
+}));
+vi.mock("./useDomEditOverlayRects", () => ({
+  useDomEditOverlayRects: () => {
+    const { rect, group } = layout;
+    const groupOverlayItemsRef = { current: group };
+    const noop = () => undefined;
+    return {
+      overlayRect: rect,
+      overlayRectRef: { current: rect },
+      groupOverlayItems: group,
+      groupOverlayItemsRef,
+      hoverRect: null,
+      childRects: [],
+      setOverlayRect: noop,
+      setGroupOverlayItems: noop,
+    };
+  },
+}));
+vi.mock("../../utils/gsapSoftReload", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../utils/gsapSoftReload")>()),
+  ensureMotionPathPluginLoaded: vi.fn(),
+}));
+
+const BOX = '[data-dom-edit-selection-box="true"]';
+const RECT = layout.rect;
+const TWO_LAYERS = '<h1 id="title">Title</h1><p id="sub">Sub</p>';
+
+/** What the server serves: the file as the last commit left it. */
+let file = { title: "", sub: "" };
+const served = (query: string) =>
+  makePreview(
+    `<h1 id="title" style="${file.title}">Title</h1><p id="sub" style="${file.sub}">Sub</p>`,
+    query,
+  );
+
+let overlayRoot: Root;
+let player: ReturnType<typeof mountPlayerWithPreview>;
+
+const marked = (doc: Document) => doc.querySelectorAll(`[${STUDIO_MANUAL_EDIT_GESTURE_ATTR}]`);
+const byId = (iframe: HTMLIFrameElement | null, id: string) =>
+  iframe!.contentDocument!.getElementById(id) as HTMLElement;
+const api = (): TimelinePlayerApi => player.getApi();
+
+function pointer(target: Element, type: string, x: number, y: number) {
+  const init = { bubbles: true, cancelable: true, button: 0, pointerId: 1, clientX: x, clientY: y };
+  act(() => void target.dispatchEvent(new PointerEvent(type, init)));
+}
+
+/** The real player with a two-layer preview, and the real overlay editing it. */
+function mountEditor(group: boolean) {
+  file = { title: "", sub: "" };
+  const live = makePreview(TWO_LAYERS);
+  player = mountPlayerWithPreview(live);
+  const selections = ["title", "sub"].map((id) => makeSelection(id, byId(live, id)));
+  layout.group = group
+    ? selections.map((s) => ({ key: s.id, selection: s, element: s.element, rect: RECT }))
+    : [];
+  const write = (sel: DomEditSelection, next: { x: number; y: number }) => {
+    file = { ...file, [sel.id!]: `translate: ${next.x}px ${next.y}px` };
+    return Promise.resolve();
+  };
+  const onPathOffsetCommit = vi.fn(write);
+  const onGroupPathOffsetCommit = vi.fn(
+    async (updates: { selection: DomEditSelection; next: { x: number; y: number } }[]) => {
+      for (const { selection, next } of updates) await write(selection, next);
+    },
+  );
+  const host = document.body.appendChild(document.createElement("div"));
+  overlayRoot = createRoot(host);
+  const render = (readOnly: boolean) =>
+    act(() =>
+      overlayRoot.render(
+        <PreviewReadOnlyProvider readOnly={readOnly}>
+          <DomEditOverlay
+            iframeRef={api().iframeRef}
+            activeCompositionPath={null}
+            selection={group ? null : selections[0]!}
+            groupSelections={group ? selections : []}
+            hoverSelection={null}
+            onCanvasMouseDown={() => undefined}
+            onCanvasPointerMove={() => Promise.resolve(null)}
+            onCanvasPointerLeave={() => undefined}
+            onSelectionChange={() => undefined}
+            onBlockedMove={() => undefined}
+            onPathOffsetCommit={onPathOffsetCommit}
+            onGroupPathOffsetCommit={onGroupPathOffsetCommit}
+            onBoxSizeCommit={() => undefined}
+            onRotationCommit={() => undefined}
+          />
+        </PreviewReadOnlyProvider>,
+      ),
+    );
+  render(false);
+  const overlay = host.querySelector('[aria-label="Composition canvas"]') as HTMLElement;
+  return { live, overlay, box: overlay.querySelector(BOX)!, onPathOffsetCommit, render };
+}
+
+/** A reload whose shadow paints while the gesture is still live. */
+async function reloadMidGesture() {
+  act(() => api().refreshPlayer());
+  const shadow = served("?_t=1");
+  const gen = await paintShadow(api, shadow);
+  return { shadow, gen };
+}
+
+async function settle() {
+  await act(async () => {
+    for (let tick = 0; tick < 10; tick++) await Promise.resolve();
+  });
+}
+
+beforeEach(() => {
+  HTMLElement.prototype.setPointerCapture = () => undefined;
+  HTMLElement.prototype.releasePointerCapture = () => undefined;
+});
+
+afterEach(() => {
+  act(() => overlayRoot?.unmount());
+  act(() => player?.root.unmount());
+  layout.group = [];
+  document.body.innerHTML = "";
+  resetPlayerStore();
+});
+
+describe("a reload during a drag", () => {
+  it.each([
+    ["one layer", false],
+    ["a group", true],
+  ])(
+    "that paints before the drop of %s waits, then shows the drop from a fresh load",
+    async (_, group) => {
+      const { live, overlay, box } = mountEditor(group);
+      pointer(box, "pointerdown", 150, 150);
+      pointer(overlay, "pointermove", 170, 160);
+      pointer(overlay, "pointermove", 190, 170);
+      const held = await reloadMidGesture();
+      expect(api().iframeRef.current, "promoted under the pointer").toBe(live);
+
+      pointer(overlay, "pointerup", 190, 170);
+      await settle();
+      expect(byId(live, "title").style.getPropertyValue("translate")).toBe("40px 20px");
+      expect(file.title).toBe("translate: 40px 20px");
+      if (group) expect(file.sub).toBe("translate: 40px 20px");
+      expect(marked(live.contentDocument!)).toHaveLength(0);
+      expect(api().iframeRef.current, "the shadow loaded before the drop").toBe(live);
+
+      const fresh = served("?_t=2");
+      expect(await paintShadow(api, fresh)).toBeGreaterThan(held.gen);
+      expect(api().iframeRef.current).toBe(fresh);
+      expect(byId(fresh, "title").style.getPropertyValue("translate")).toBe("40px 20px");
+      if (group) expect(byId(fresh, "sub").style.getPropertyValue("translate")).toBe("40px 20px");
+    },
+  );
+
+  it("that paints after the drop shows the drop from a fresh load, not the file before it", async () => {
+    const { live, overlay, box } = mountEditor(false);
+    pointer(box, "pointerdown", 150, 150);
+    pointer(overlay, "pointermove", 190, 170);
+    act(() => api().refreshPlayer());
+    const beforeDrop = served("?_t=1");
+    pointer(overlay, "pointerup", 190, 170);
+    await settle();
+    expect(file.title).toBe("translate: 40px 20px");
+
+    const requested = await paintShadow(api, beforeDrop);
+    expect(api().iframeRef.current, "the file before the drop").toBe(live);
+    const fresh = served("?_t=2");
+    expect(await paintShadow(api, fresh)).toBeGreaterThan(requested);
+    expect(byId(fresh, "title").style.getPropertyValue("translate")).toBe("40px 20px");
+  });
+});
+
+type Editor = ReturnType<typeof mountEditor>;
+
+describe("every way a drag ends without a drop clears its mark and promotes the held reload", () => {
+  it.each([
+    ["pointercancel", (e: Editor) => pointer(e.overlay, "pointercancel", 0, 0)],
+    ["lostpointercapture", (e: Editor) => pointer(e.box, "lostpointercapture", 0, 0)],
+    ["window blur", () => act(() => void window.dispatchEvent(new Event("blur")))],
+    ["a switch to read-only", (e: Editor) => e.render(true)],
+    ["overlay unmount", () => act(() => overlayRoot.unmount())],
+  ])("%s", async (_, end) => {
+    const editor = mountEditor(false);
+    pointer(editor.box, "pointerdown", 150, 150);
+    pointer(editor.overlay, "pointermove", 190, 170);
+    expect(marked(editor.live.contentDocument!)).toHaveLength(1);
+    const held = await reloadMidGesture();
+    expect(api().iframeRef.current).toBe(editor.live);
+
+    end(editor);
+    await settle();
+    expect(marked(editor.live.contentDocument!)).toHaveLength(0);
+    expect(byId(editor.live, "title").style.getPropertyValue("translate")).not.toBe("40px 20px");
+    expect(editor.onPathOffsetCommit).not.toHaveBeenCalled();
+    expect(api().iframeRef.current, "nothing was saved, so the held copy is current").toBe(
+      held.shadow,
+    );
+  });
+
+  it("a press that throws before the drag is armed leaves no mark behind", async () => {
+    const editor = mountEditor(false);
+    HTMLElement.prototype.setPointerCapture = () => {
+      throw new Error("capture refused");
+    };
+    const swallow = (event: ErrorEvent) => event.preventDefault();
+    window.addEventListener("error", swallow);
+    try {
+      pointer(editor.box, "pointerdown", 150, 150);
+    } catch {
+      // React may rethrow the handler's error; either way the mark must be gone.
+    } finally {
+      window.removeEventListener("error", swallow);
+    }
+    expect(marked(editor.live.contentDocument!)).toHaveLength(0);
+    const { shadow } = await reloadMidGesture();
+    expect(api().iframeRef.current).toBe(shadow);
+  });
+});
+
+describe("an inline text edit", () => {
+  it("holds a reload while open, and the reload after it shows the saved text", async () => {
+    const live = makePreview(TWO_LAYERS);
+    player = mountPlayerWithPreview(live);
+    let land: () => void = () => {};
+    const onCommit = vi.fn(() => new Promise<void>((resolve) => (land = resolve)));
+    let controls: ReturnType<typeof useInlineTextEdit> | null = null;
+    function Editor() {
+      controls = useInlineTextEdit({ onCommit });
+      return null;
+    }
+    overlayRoot = createRoot(document.body.appendChild(document.createElement("div")));
+    act(() => overlayRoot.render(<Editor />));
+    act(() => void controls!.start(byId(live, "title")));
+    const held = await reloadMidGesture();
+    expect(api().iframeRef.current).toBe(live);
+
+    act(() => controls!.commit());
+    await settle();
+    expect(onCommit).toHaveBeenCalledTimes(1);
+    expect(marked(live.contentDocument!), "closed, though the save is still out").toHaveLength(0);
+    expect(api().iframeRef.current, "the held copy predates the text").toBe(live);
+    expect(api().previewSlots.find((slot) => slot.role === "shadow")?.gen).toBe(held.gen);
+
+    await act(async () => land());
+    await settle();
+    const afterSave = served("?_t=2");
+    expect(await paintShadow(api, afterSave)).toBeGreaterThan(held.gen);
+    expect(api().iframeRef.current).toBe(afterSave);
+  });
+});

package/src/components/editor/manualEditsDom.ts

@@ -46,9 +46,42 @@ export function beginStudioManualEditGesture(element: HTMLElement): string {
   return token;
 }
 
+const GESTURE_ENDED = "hf-manual-edit-gesture-ended";
+
 export function endStudioManualEditGesture(element: HTMLElement, token?: string): void {
   if (token && element.getAttribute(STUDIO_MANUAL_EDIT_GESTURE_ATTR) !== token) return;
+  if (!element.hasAttribute(STUDIO_MANUAL_EDIT_GESTURE_ATTR)) return;
   element.removeAttribute(STUDIO_MANUAL_EDIT_GESTURE_ATTR);
+  const doc = element.ownerDocument;
+  doc.dispatchEvent(new (doc.defaultView?.Event ?? Event)(GESTURE_ENDED));
+}
+
+export function isStudioManualEditGestureLiveIn(doc: Document): boolean {
+  return doc.querySelector(`[${STUDIO_MANUAL_EDIT_GESTURE_ATTR}]`) !== null;
+}
+
+/** Runs `run` once the last gesture in `doc` ends; the returned function stops waiting. */
+export function afterStudioManualEditGestures(doc: Document, run: () => void): () => void {
+  const onEnded = () => {
+    if (isStudioManualEditGestureLiveIn(doc)) return;
+    stop();
+    run();
+  };
+  const stop = () => doc.removeEventListener(GESTURE_ENDED, onEnded);
+  doc.addEventListener(GESTURE_ENDED, onEnded);
+  return stop;
+}
+
+const gestureSaves = new WeakMap<Document, number>();
+
+export function studioManualEditSavesIn(doc: Document): number {
+  return gestureSaves.get(doc) ?? 0;
+}
+
+/** A gesture's save in `element`'s document: a reload requested before it shows the file before it. */
+export function noteStudioManualEditSave(element: HTMLElement): void {
+  const doc = element.ownerDocument;
+  gestureSaves.set(doc, studioManualEditSavesIn(doc) + 1);
 }
 
 function isStudioManualEditGestureActive(element: HTMLElement): boolean {
@@ -253,9 +286,9 @@ function stripGsapTranslateFromTransform(element: HTMLElement): void {
 // — as the non-GSAP path does — composes ON TOP of GSAP's transform, and the
 // subsequent strip/reapply math compounds into a runaway matrix that flings the
 // element off-canvas. So for GSAP-animated elements we keep `translate: none`
-// and push the offset straight into GSAP's x/y via gsap.set; the var() offset is
-// still persisted (buildPathOffsetPatches), and GSAP re-reads it at init on
-// reload. Returns true when handled as GSAP (caller must skip the CSS path).
+// and push the offset straight into GSAP's x/y via gsap.set; the var() offset an
+// older Studio saved stays in the file, and GSAP re-reads it at init on reload.
+// Returns true when handled as GSAP (caller must skip the CSS path).
 // fallow-ignore-next-line complexity
 function applyStudioPathOffsetViaGsap(
   element: HTMLElement,