@hyperframes/studio 0.8.99 → 0.8.101

package/src/hooks/useAppHotkeys.previewForwarding.test.tsx

@@ -7,10 +7,15 @@ import type { DomEditSelection } from "../components/editor/domEditing";
 import { usePlayerStore } from "../player/store/playerStore";
 import { useAppHotkeys } from "./useAppHotkeys";
 import { mountReactHarness } from "./domSelectionTestHarness";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
 const domDelete = vi.fn(async () => undefined);
+const historyUndo = vi.fn(async () => ({ ok: false }));
+const historyRedo = vi.fn(async () => ({ ok: false }));
 let root: Root | null = null;
 let sync: ((iframe: HTMLIFrameElement | null) => void) | null = null;
 
@@ -35,8 +40,8 @@ function Harness() {
     domEditSelectionRef: selectionRef,
     clearDomSelectionRef: useRef<() => void>(() => undefined),
     editHistory: {
-      undo: vi.fn(async () => ({ ok: false })),
-      redo: vi.fn(async () => ({ ok: false })),
+      undo: historyUndo,
+      redo: historyRedo,
       state: { undo: [], redo: [] },
     },
     readOptionalProjectFile: vi.fn(async () => ""),
@@ -62,6 +67,9 @@ afterEach(() => {
   document.body.innerHTML = "";
   usePlayerStore.getState().reset();
   domDelete.mockClear();
+  historyUndo.mockClear();
+  historyRedo.mockClear();
+  vi.mocked(trackStudioEvent).mockClear();
 });
 
 describe("preview iframe hotkey forwarding", () => {
@@ -87,4 +95,61 @@ describe("preview iframe hotkey forwarding", () => {
 
     expect(domDelete).toHaveBeenCalledTimes(1);
   });
+
+  function mountWithPreview(): Window & typeof globalThis {
+    root = mountReactHarness(<Harness />);
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    act(() => sync?.(iframe));
+    const inner = iframe.contentWindow as (Window & typeof globalThis) | null;
+    if (!inner) throw new Error("expected an iframe window");
+    return inner;
+  }
+
+  async function press(inner: Window & typeof globalThis, init: KeyboardEventInit) {
+    await act(async () => {
+      inner.document.body.dispatchEvent(
+        new inner.KeyboardEvent("keydown", { ...init, bubbles: true }),
+      );
+    });
+  }
+
+  it("takes one tracked undo step per Cmd+Z pressed inside the preview", async () => {
+    await press(mountWithPreview(), { key: "z", ctrlKey: true });
+
+    expect(historyUndo).toHaveBeenCalledTimes(1);
+    expect(trackStudioEvent).toHaveBeenCalledTimes(1);
+    expect(trackStudioEvent).toHaveBeenCalledWith("keyboard_shortcut", { action: "undo" });
+  });
+
+  it.each([
+    ["Shift+Cmd+Z", { key: "Z", metaKey: true, shiftKey: true }],
+    ["Ctrl+Y", { key: "y", ctrlKey: true }],
+  ])("takes one tracked redo step per %s pressed inside the preview", async (_, init) => {
+    await press(mountWithPreview(), init);
+
+    expect(historyRedo).toHaveBeenCalledTimes(1);
+    expect(trackStudioEvent).toHaveBeenCalledTimes(1);
+    expect(trackStudioEvent).toHaveBeenCalledWith("keyboard_shortcut", { action: "redo" });
+  });
+
+  it("stops handling preview keys once the app unmounts", async () => {
+    root = mountReactHarness(<Harness />);
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const inner = iframe.contentWindow as (Window & typeof globalThis) | null;
+    if (!inner) throw new Error("expected an iframe window");
+    const add = vi.spyOn(inner, "addEventListener");
+    const remove = vi.spyOn(inner, "removeEventListener");
+    act(() => sync?.(iframe));
+    act(() => root?.unmount());
+    root = null;
+
+    await press(inner, { key: "z", ctrlKey: true });
+
+    expect(historyUndo).not.toHaveBeenCalled();
+    // happy-dom removes a listener whatever its capture flag; a browser does not, so pin the flag.
+    expect(add).toHaveBeenCalled();
+    expect(remove.mock.calls).toEqual(add.mock.calls);
+  });
 });

package/src/hooks/useAppHotkeys.ts

@@ -8,13 +8,7 @@ import {
   applyCaptionModelToIframe,
   isCaptionPreviewVisible,
 } from "../captions/components/CaptionOverlayUtils";
-import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";
-import {
-  type HotkeyCallbacks,
-  dispatchModifierKey,
-  dispatchPlainKey,
-  handleUndoRedoKey,
-} from "./appHotkeysDispatch";
+import { type HotkeyCallbacks, dispatchModifierKey, dispatchPlainKey } from "./appHotkeysDispatch";
 import {
   useEditHistoryActions,
   type EditHistoryHandle,
@@ -36,9 +30,14 @@ function safeAddListener(t: EventTarget | null, type: string, h: EventListener,
     /* cross-origin */
   }
 }
-function safeRemoveListener(t: EventTarget | null, type: string, h: EventListener) {
+function safeRemoveListener(
+  t: EventTarget | null,
+  type: string,
+  h: EventListener,
+  capture = false,
+) {
   try {
-    t?.removeEventListener(type, h);
+    t?.removeEventListener(type, h, capture);
   } catch {
     /* cross-origin */
   }
@@ -86,6 +85,7 @@ interface UseAppHotkeysParams {
   writeProjectFile: (path: string, content: string) => Promise<void>;
   showToast: (message: string, tone?: "error" | "info") => void;
   syncHistoryPreviewAfterApply: UseEditHistoryActionsOptions["syncHistoryPreviewAfterApply"];
+  showHistoryRestoreNow?: UseEditHistoryActionsOptions["showHistoryRestoreNow"];
   waitForPendingDomEditSaves: () => Promise<void>;
   handleCopy: () => boolean;
   handlePaste: () => Promise<void>;
@@ -124,6 +124,7 @@ export function useAppHotkeys({
   writeProjectFile,
   showToast,
   syncHistoryPreviewAfterApply,
+  showHistoryRestoreNow,
   waitForPendingDomEditSaves,
   handleCopy,
   handlePaste,
@@ -150,6 +151,7 @@ export function useAppHotkeys({
     writeProjectFile,
     showToast,
     syncHistoryPreviewAfterApply,
+    showHistoryRestoreNow,
     waitForPendingDomEditSaves,
     onAfterUndoRedo,
     activeCompPath,
@@ -229,52 +231,23 @@ export function useAppHotkeys({
 
   // ── Preview iframe forwarding ──
 
-  const handleHistoryHotkey = useCallback((event: KeyboardEvent) => {
-    if (!(event.metaKey || event.ctrlKey) || shouldIgnoreHistoryShortcut(event.target)) return;
-    handleUndoRedoKey(
-      event,
-      () => void cbRef.current.handleUndo(),
-      () => void cbRef.current.handleRedo(),
-    );
-  }, []);
-
   /**
-   * Give the preview iframe the app's hotkeys, because a keypress lands in
-   * whichever document has focus and clicking the canvas puts focus in there.
-   *
-   * Must run on every iframe LOAD, not once when the element mounts: a reload
-   * keeps the same element (so no ref callback) and the same WindowProxy (so an
-   * identity check sees no change) while replacing the inner window that holds
-   * the listeners. Attaching once left Delete dead in the canvas after the first
-   * reload — press it with a selection and nothing happened, no toast, nothing
-   * to explain it — while undo/redo kept working because they re-attached here.
+   * Give the preview iframe the app's hotkeys: clicking the canvas puts focus in there.
+   * Runs on every iframe LOAD: a reload keeps the element and WindowProxy but replaces the
+   * inner window holding the listeners, which once left Delete dead after the first reload.
    */
   const syncPreviewHotkeys = useCallback(
     (iframe: HTMLIFrameElement | null) => {
       previewHistoryCleanupRef.current?.();
       previewHistoryCleanupRef.current = null;
       const win = iframeContentWindow(iframe);
-      let doc: Document | null = null;
-      try {
-        doc = iframe?.contentDocument ?? null;
-      } catch {
-        doc = null;
-      }
-      if (!win && !doc) return;
-      const handler = handleHistoryHotkey as EventListener;
+      if (!win) return;
       const appHandler = handleAppKeyDown as EventListener;
-      safeAddListener(win, "keydown", handler, true);
-      // Window only: the history pair also listens on the document, and a
-      // capture listener on both would run the app handler twice per press.
+      // Window only: a capture listener on the document too would run it twice per press.
       safeAddListener(win, "keydown", appHandler, true);
-      doc?.addEventListener("keydown", handleHistoryHotkey, true);
-      previewHistoryCleanupRef.current = () => {
-        safeRemoveListener(win, "keydown", handler);
-        safeRemoveListener(win, "keydown", appHandler);
-        doc?.removeEventListener("keydown", handleHistoryHotkey, true);
-      };
+      previewHistoryCleanupRef.current = () => safeRemoveListener(win, "keydown", appHandler, true);
     },
-    [handleAppKeyDown, handleHistoryHotkey],
+    [handleAppKeyDown],
   );
 
   useEffect(

package/src/hooks/useDomEditCommits.test.tsx

@@ -228,7 +228,9 @@ function renderDomEditCommits(
       applyDomSelection: vi.fn(),
       clearDomSelection: vi.fn(),
       refreshDomEditSelectionFromPreview: vi.fn(),
-      buildDomSelectionFromTarget: vi.fn(async () => null),
+      buildDomSelectionFromTarget: vi.fn(async (target: HTMLElement) =>
+        target === selection.element ? selection : null,
+      ),
       onTrySdkPersist: options.onTrySdkPersist,
       readOnlyPreview: false,
     });
@@ -893,7 +895,7 @@ describe("useDomEditCommits rich-text persist handling", () => {
     }
   });
 
-  it("does not retarget a commit onto a replacement preview node", async () => {
+  it("does not retarget a commit onto a replacement preview node, and says the text was not saved", async () => {
     const fetchMock = stubPatchFetch({ ok: true, changed: true, matched: true });
     const html = '<span style="color: blue">After</span>';
     const { iframe, element } = createPreviewElement(`<div data-hf-id="hf-card">${html}</div>`);
@@ -902,6 +904,7 @@ describe("useDomEditCommits rich-text persist handling", () => {
     replacement.dataset.hfId = "hf-card";
     replacement.innerHTML = "Reloaded elsewhere";
     element.replaceWith(replacement);
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
 
     try {
       await act(async () => {
@@ -914,8 +917,14 @@ describe("useDomEditCommits rich-text persist handling", () => {
 
       expect(replacement.innerHTML).toBe("Reloaded elsewhere");
       expect(fetchMock).not.toHaveBeenCalled();
-      expect(rendered.showToast).not.toHaveBeenCalled();
+      expect(rendered.showToast).toHaveBeenCalledWith(
+        expect.stringMatching(
+          /Couldn't save the text edit: the text's element is gone from the preview/,
+        ),
+        "error",
+      );
     } finally {
+      errorSpy.mockRestore();
       rendered.cleanup();
     }
   });

package/src/hooks/useDomEditCommits.ts

@@ -7,6 +7,7 @@ import { StudioSaveHttpError, trackStudioSaveFailure } from "../utils/studioSave
 import type { DomEditSelection } from "../components/editor/domEditing";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
 import type { CommitDomEditPatchBatches } from "./domEditCommitTypes";
+import type { ResolveDomSelectionOptions } from "./useDomSelectionTypes";
 import type { PatchOperation } from "../utils/sourcePatcher";
 import { DomEditPersistUnsafeValueError } from "./domEditPersistFailure";
 import { useDomEditPersist, type RecordEditInput } from "./useDomEditPersist";
@@ -46,7 +47,7 @@ export interface UseDomEditCommitsParams {
   refreshDomEditSelectionFromPreview: (selection: DomEditSelection) => void;
   buildDomSelectionFromTarget: (
     target: HTMLElement,
-    options?: { preferClipAncestor?: boolean },
+    options?: ResolveDomSelectionOptions,
   ) => Promise<DomEditSelection | null>;
   /** Resync the in-memory SDK session after a SERVER-side write (NOT the SDK
    * path, whose session is already current) so a later SDK edit doesn't

package/src/hooks/useDomEditTextCommits.test.tsx

@@ -125,13 +125,20 @@ afterEach(() => {
 });
 
 describe("useDomEditTextCommits", () => {
-  function richTextProbe() {
-    const { iframe, element } = previewElement('<h1 id="t">Old</h1>', "t");
+  function richTextProbe(
+    html = '<h1 id="t">Old</h1>',
+    overrides: (doc: Document) => Partial<UseDomEditTextCommitsParams> = () => ({}),
+  ) {
+    const { iframe, element } = previewElement(html, "t");
     const persist = vi.fn().mockResolvedValue(undefined);
+    const showToast = vi.fn();
     const base = commitParams({
       previewIframeRef: { current: iframe },
       domEditSelection: selectionFor(element),
+      buildDomSelectionFromTarget: vi.fn(async (target: HTMLElement) => selectionFor(target)),
       persistDomEditOperations: persist,
+      showToast,
+      ...overrides(element.ownerDocument),
     });
     const captured: { hook: ReturnType<typeof useDomEditTextCommits> | null } = { hook: null };
     function Probe({ readOnlyPreview }: { readOnlyPreview: boolean }) {
@@ -143,13 +150,25 @@ describe("useDomEditTextCommits", () => {
     const save = captured.hook!.handleDomRichTextCommit;
     const commit = { element, html: "New", previousHtml: "Old" };
     element.innerHTML = "New";
-    return { root, Probe, persist, element, save: () => act(async () => save(commit)) };
+    return {
+      root,
+      Probe,
+      persist,
+      showToast,
+      element,
+      save: () => act(async () => save(commit)),
+    };
   }
 
-  it("saves in-place text while the preview is editable", async () => {
-    const { persist, save } = richTextProbe();
+  it("saves in-place text while the preview is editable, and refreshes the selection it edited", async () => {
+    const applyDomSelection = vi.fn();
+    const { persist, element, save } = richTextProbe(undefined, () => ({ applyDomSelection }));
     await save();
     expect(persist).toHaveBeenCalledTimes(1);
+    expect(applyDomSelection).toHaveBeenCalledWith(
+      expect.objectContaining({ element }),
+      expect.objectContaining({ preserveGroup: true }),
+    );
   });
 
   it("refuses in-place text once the preview turns read-only, through an earlier handler, and puts the old text back", async () => {
@@ -160,6 +179,44 @@ describe("useDomEditTextCommits", () => {
     expect(element.innerHTML).toBe("Old");
   });
 
+  it("saves the edited element, and leaves the selection alone, when the selection is another element or none", async () => {
+    for (const selected of ["card", null]) {
+      const applyDomSelection = vi.fn();
+      const { persist, element, save } = richTextProbe(
+        '<div id="card"><p id="t">Old</p></div>',
+        (doc) => ({
+          domEditSelection: selected ? selectionFor(doc.getElementById(selected)!) : null,
+          applyDomSelection,
+          buildDomSelectionFromTarget: vi.fn(async (target: HTMLElement) => ({
+            ...selectionFor(target),
+            label: "Resolved from the edited element",
+          })),
+        }),
+      );
+      await save();
+      expect(persist).toHaveBeenCalledTimes(1);
+      expect(persist.mock.calls[0]![0]).toMatchObject({
+        element,
+        label: "Resolved from the edited element",
+      });
+      expect(applyDomSelection).not.toHaveBeenCalled();
+      cleanup?.();
+      cleanup = null;
+    }
+  });
+
+  it("says so and puts the old text back when the edited text cannot be saved", async () => {
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const { persist, showToast, element, save } = richTextProbe(undefined, () => ({
+      buildDomSelectionFromTarget: vi.fn(async () => null),
+    }));
+    await save();
+    expect(persist).not.toHaveBeenCalled();
+    expect(showToast).toHaveBeenCalledWith(expect.stringContaining("Couldn't save"), "error");
+    expect(error).toHaveBeenCalled();
+    expect(element.innerHTML).toBe("Old");
+  });
+
   it("keeps concurrent text commit ownership isolated by target", async () => {
     const { iframe, element: firstElement } = previewElement(
       "<div id='first'>First</div><div id='second'>Second</div>",

package/src/hooks/useDomEditTextCommits.ts

@@ -29,6 +29,7 @@ import {
 import { commitDomStyles } from "./domStyleCommit";
 import { useDomEditAttributeCommits } from "./useDomEditAttributeCommits";
 import type { InlineTextEditCommit } from "./useInlineTextEdit";
+import type { ResolveDomSelectionOptions } from "./useDomSelectionTypes";
 
 // ── Types ──
 
@@ -44,7 +45,7 @@ export interface UseDomEditTextCommitsParams {
   refreshDomEditSelectionFromPreview: (selection: DomEditSelection) => void;
   buildDomSelectionFromTarget: (
     target: HTMLElement,
-    options?: { preferClipAncestor?: boolean },
+    options?: ResolveDomSelectionOptions,
   ) => Promise<DomEditSelection | null>;
   persistDomEditOperations: PersistDomEditOperations;
   resolveImportedFontAsset: (fontFamilyValue: string) => ImportedFontAsset | null;
@@ -56,15 +57,6 @@ function canCommitInlineTextSelection(selection: DomEditSelection, element: HTML
   return canEditElementTextInline(element);
 }
 
-function ownsCurrentPreviewElement(
-  selection: DomEditSelection,
-  element: HTMLElement,
-  document: Document | null | undefined,
-): document is Document {
-  if (!document || !element.isConnected) return false;
-  return element === selection.element && element.ownerDocument === document;
-}
-
 async function resyncDomTextSelectionFromPreview(
   doc: Document | null | undefined,
   selection: DomEditSelection,
@@ -96,6 +88,8 @@ export function useDomEditTextCommits({
 }: UseDomEditTextCommitsParams) {
   const latestReadOnlyPreviewRef = useRef(readOnlyPreview);
   latestReadOnlyPreviewRef.current = readOnlyPreview;
+  const latestSelectionRef = useRef(domEditSelection);
+  latestSelectionRef.current = domEditSelection;
   const domTextCommitVersionRef = useRef(new Map<string, symbol>());
   const domStyleCommitVersionRef = useRef(new Map<string, symbol>());
 
@@ -238,29 +232,36 @@ export function useDomEditTextCommits({
    */
   const handleDomRichTextCommit = useCallback(
     async ({ element, html, previousHtml }: InlineTextEditCommit) => {
-      if (!domEditSelection) return;
-      if (latestReadOnlyPreviewRef.current) {
+      const putBack = () => {
         if (element.isConnected && element.innerHTML === html) element.innerHTML = previousHtml;
-        return;
+      };
+      if (latestReadOnlyPreviewRef.current) return putBack();
+      const refuse = (reason: string) => {
+        console.error("[Studio] text edit not saved:", reason, element);
+        showToast(`Couldn't save the text edit: ${reason}`, "error");
+        putBack();
+      };
+      // The edited node, not the current selection: a press can open an edit on a child of what
+      // is selected, and a host can clear the selection before the edit closes.
+      const doc = previewIframeRef.current?.contentDocument;
+      if (!doc || !element.isConnected || element.ownerDocument !== doc) {
+        return refuse("the text's element is gone from the preview");
+      }
+      const selection = await buildDomSelectionFromTarget(element, {
+        exactTarget: true,
+        skipSourceProbe: true,
+      });
+      if (selection?.element !== element) {
+        return refuse("this text was not found in the composition's source");
+      }
+      // The same gate that let the edit open, not the design panel's field rule: an element
+      // whose text holds a line break has no fields, and editing in place rewrites its markup.
+      if (!canCommitInlineTextSelection(selection, element)) {
+        return refuse("this text can't be edited in place");
       }
-      // The same gate that let the edit open, not the design panel's.
-      //
-      // The panel's rule is about its text fields, and it has none for an
-      // element whose text contains a line break: a `<span>` holding `<br>`s
-      // is not a leaf, so nothing inside is a field and the element reports no
-      // editable text at all. Editing in place does not use fields — it
-      // rewrites the element's own markup — so refusing on that rule refused
-      // elements the caret had just been opened in, and every colour the user
-      // chose was dropped on the way out with nothing said about it.
-      if (!canCommitInlineTextSelection(domEditSelection, element)) return;
-      const iframe = previewIframeRef.current;
-      const doc = iframe?.contentDocument;
-      // A preview reload replaces the document. Never resolve this commit onto
-      // the replacement node: it did not own the edit or its rollback snapshot.
-      if (!ownsCurrentPreviewElement(domEditSelection, element, doc)) return;
       const isLatestTextCommit = bumpDomEditCommitMapVersion(
         domTextCommitVersionRef.current,
-        getDomEditTargetKey(domEditSelection),
+        getDomEditTargetKey(selection),
       );
       const operations = [buildDomEditRichTextPatchOperation(html)];
       let appliedHtml = "";
@@ -274,7 +275,7 @@ export function useDomEditTextCommits({
           appliedHtml = element.innerHTML;
         },
         persist: async () => {
-          await persistDomEditOperations(domEditSelection, operations, {
+          await persistDomEditOperations(selection, operations, {
             label: "Edit text",
             skipRefresh: true,
             shouldSave: isLatestTextCommit,
@@ -288,13 +289,13 @@ export function useDomEditTextCommits({
             element.innerHTML = previousHtml;
           }
         },
-        onError: (error) =>
-          reportDomEditPersistFailure(domEditSelection, operations, error, showToast),
-        shouldResync: isLatestTextCommit,
+        onError: (error) => reportDomEditPersistFailure(selection, operations, error, showToast),
+        // Re-select only what is still selected: the selection may have moved on, or a host cleared it.
+        shouldResync: () => isLatestTextCommit() && latestSelectionRef.current?.element === element,
         resync: () =>
           resyncDomTextSelectionFromPreview(
             doc,
-            domEditSelection,
+            selection,
             activeCompPath,
             buildDomSelectionFromTarget,
             applyDomSelection,
@@ -306,7 +307,6 @@ export function useDomEditTextCommits({
       activeCompPath,
       applyDomSelection,
       buildDomSelectionFromTarget,
-      domEditSelection,
       persistDomEditOperations,
       previewIframeRef,
       showToast,

package/src/hooks/useDomGeometryCommit.test.tsx

@@ -16,6 +16,11 @@ vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
 
 const SOURCE = '<div id="card">Card</div><div id="other">Other</div>';
 
+/** GSAP already renders this element's transform, so a move takes the GSAP writer. */
+function gsapPositioned(element: HTMLElement): HTMLElement {
+  return Object.assign(element, { _gsap: { renderTransform: () => {} } });
+}
+
 /** A warm parse where only another element animates, and a GSAP writer answering `status`. */
 function stubServer(status = 200, parseStatus = 200) {
   const mutations: unknown[] = [];
@@ -116,7 +121,8 @@ describe("useDomGeometryCommit, from the package entry", () => {
       onRotationCommit: hook().commitRotation,
     };
 
-    const outcome = await overlayCommits.onPathOffsetCommit(makeSelection("card", element), {
+    const card = makeSelection("card", gsapPositioned(element));
+    const outcome = await overlayCommits.onPathOffsetCommit(card, {
       x: 40,
       y: 20,
     });
@@ -132,6 +138,56 @@ describe("useDomGeometryCommit, from the package entry", () => {
     unmount();
   });
 
+  function stubPatchServer(patchStatus = 200) {
+    const calls = { urls: [] as string[], patches: [] as unknown[] };
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+        const url = String(input instanceof Request ? input.url : input);
+        calls.urls.push(url);
+        if (url.includes("/patch-element/")) calls.patches.push(JSON.parse(String(init?.body)));
+        const saved = { ok: true, changed: true, matched: true, content: "AFTER", version: "v2" };
+        const body = url.includes("/files/") ? { content: SOURCE } : saved;
+        const status = url.includes("/patch-element/") ? patchStatus : 200;
+        return new Response(JSON.stringify(body), {
+          status,
+          headers: { "content-type": "application/json" },
+        });
+      }),
+    );
+    return calls;
+  }
+
+  it("saves a GSAP-free move as its inline translate, with no GSAP script and no animation read", async () => {
+    const calls = stubPatchServer();
+    const { element, recordEdit, hook, unmount } = renderHost();
+
+    const card = makeSelection("card", element);
+    await expect(hook().commitPathOffset(card, { x: 130.5, y: 90 })).resolves.toEqual({ ok: true });
+
+    expect(element.style.getPropertyValue("translate")).toBe("130.5px 90px");
+    expect(calls.patches).toEqual([
+      expect.objectContaining({
+        operations: [{ type: "inline-style", property: "translate", value: "130.5px 90px" }],
+      }),
+    ]);
+    expect(calls.urls.filter((url) => url.includes("gsap"))).toEqual([]);
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+    unmount();
+  });
+
+  it("puts a GSAP-free element's translate back when its move cannot be saved", async () => {
+    stubPatchServer(500);
+    const { element, hook, unmount } = renderHost();
+    element.style.setProperty("translate", "40px 30px");
+
+    await expect(
+      hook().commitPathOffset(makeSelection("card", element), { x: 1, y: 2 }),
+    ).rejects.toThrow();
+    expect(element.style.getPropertyValue("translate")).toBe("40px 30px");
+    unmount();
+  });
+
   it("keeps the same commits across renders, so the overlay's handlers stay put", () => {
     stubServer();
     const { hook, rerender, unmount } = renderHost();
@@ -148,7 +204,7 @@ describe("useDomGeometryCommit, from the package entry", () => {
     const { element, recordEdit, hook, unmount } = renderHost({ showToast });
 
     await expect(
-      hook().commitPathOffset(makeSelection("card", element), { x: 40, y: 20 }),
+      hook().commitPathOffset(makeSelection("card", gsapPositioned(element)), { x: 40, y: 20 }),
     ).rejects.toThrow();
     expect(recordEdit).not.toHaveBeenCalled();
     expect(showToast).toHaveBeenCalledWith(expect.any(String), "error");
@@ -204,7 +260,8 @@ describe("useDomGeometryCommit, from the package entry", () => {
     const mutations = stubServer();
     const { element, recordEdit, hook, unmount } = renderHost();
 
-    const move = hook().commitPathOffset(makeSelection("card", element), { x: 40, y: 20 });
+    const card = makeSelection("card", gsapPositioned(element));
+    const move = hook().commitPathOffset(card, { x: 40, y: 20 });
     await hook().waitForPendingSaves();
 
     expect(mutations).toHaveLength(1);
@@ -280,7 +337,8 @@ describe("useDomGeometryCommit, one word of a staggered phrase", () => {
       offsetLeft: { get: () => 100 + (Number.parseFloat(word.style.left) || 0) },
       offsetTop: { get: () => 200 + (Number.parseFloat(word.style.top) || 0) },
     });
-    return { ...makeSelection("How", word), id: undefined, selector: ".w", hfId: "hf-w0" };
+    const selection = makeSelection("How", gsapPositioned(word));
+    return { ...selection, id: undefined, selector: ".w", hfId: "hf-w0" };
   }
 
   it("saves left/top on the dragged word only and never rewrites the shared tween", async () => {

package/src/hooks/useDomGeometryCommits.test.tsx

@@ -147,8 +147,10 @@ describe("useDomGeometryCommits read-only preview", () => {
 });
 
 describe("useDomGeometryCommits element position offset", () => {
-  it("persists left/top on the element and no translate offset", async () => {
-    const element = document.createElement("span");
+  it("persists left/top on a word a shared tween positions, and no translate offset", async () => {
+    const element = Object.assign(document.createElement("span"), {
+      _gsap: { renderTransform: () => {} },
+    });
     Object.defineProperties(element, {
       offsetLeft: { get: () => 100 + (Number.parseFloat(element.style.left) || 0) },
       offsetTop: { get: () => 200 + (Number.parseFloat(element.style.top) || 0) },