@hyperframes/studio 0.8.116 → 0.8.117

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.116",
+  "version": "0.8.117",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/parsers": "0.8.116",
-    "@hyperframes/player": "0.8.116",
-    "@hyperframes/core": "0.8.116",
-    "@hyperframes/sdk": "0.8.116",
-    "@hyperframes/studio-server": "0.8.116",
-    "@hyperframes/shader-transitions": "0.8.116"
+    "@hyperframes/core": "0.8.117",
+    "@hyperframes/parsers": "0.8.117",
+    "@hyperframes/sdk": "0.8.117",
+    "@hyperframes/shader-transitions": "0.8.117",
+    "@hyperframes/studio-server": "0.8.117",
+    "@hyperframes/player": "0.8.117"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.116"
+    "@hyperframes/producer": "0.8.117"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/editor/DomEditOverlay.tsx

@@ -94,6 +94,7 @@ export interface DomEditOverlayProps {
     next: { width: number; height: number },
     offset?: { x: number; y: number },
     restore?: () => void,
+    route?: { plainTranslate: boolean },
   ) => Promise<unknown> | void;
   onRotationCommit: (selection: DomEditSelection, next: RotationCommit) => Promise<unknown> | void;
   onStyleCommit?: (property: string, value: string) => Promise<unknown> | void;

package/src/components/editor/domEditOverlayGestures.ts

@@ -275,6 +275,7 @@ export type UseDomEditOverlayGesturesOptions = {
       n: { width: number; height: number },
       offset?: { x: number; y: number },
       restore?: () => void,
+      route?: { plainTranslate: boolean },
     ) => Promise<unknown> | void
   >;
   onRotationCommitRef: RefObject<

package/src/components/editor/domEditOverlayStartGesture.ts

@@ -32,7 +32,7 @@ import {
   type UseDomEditOverlayGesturesOptions,
 } from "./domEditOverlayGestures";
 import { collectSnapContext, buildExcludeElements } from "./snapTargetCollection";
-import { gsapWritesRotation } from "../../hooks/gsapRuntimeKeyframes";
+import { editsPlainCss } from "../../hooks/gsapRuntimeKeyframes";
 import { logResize, resetResizeMoveLog } from "../../utils/resizeDebug";
 import { logDrag, readDragPositions, resetDragMoveLog } from "../../utils/dragDebug";
 
@@ -234,7 +234,7 @@ export function startGesture(
   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 plain = !!pathOffsetMember?.plainTranslate || editsPlainCss(sel.element, "rotate");
     const plainRotation = plain && kind === "rotate" ? readCssRotationTarget(sel.element) : null;
     const rotation = { angle: readRotationBase(sel.element, plain) };
     const overlayBounds = overlayEl?.getBoundingClientRect();

package/src/components/editor/manualOffsetDrag.ts

@@ -11,7 +11,7 @@ import {
   type StudioPathOffsetSnapshot,
 } from "./manualEdits";
 import { computeDraggedGsapPosition } from "../../hooks/draggedGsapPosition";
-import { gsapWritesBox, gsapWritesPosition } from "../../hooks/gsapRuntimeKeyframes";
+import { editsPlainCss } from "../../hooks/gsapRuntimeKeyframes";
 import { readTranslatePx, UNREADABLE_TRANSLATE, writeTranslatePx } from "./plainTranslate";
 import type { StudioEditRevert } from "../../utils/studioPendingEdits";
 
@@ -318,8 +318,8 @@ export function createManualOffsetDragMember(input: {
   rect: ManualOffsetDragRect;
   gesture?: "drag" | "nudge" | "resize"; // resize: the anchor that keeps its centre planted
 }): ManualOffsetDragMemberResult {
-  const gsapOwns = input.gesture === "resize" ? gsapWritesBox : gsapWritesPosition;
-  const plainTranslate = !!input.gesture && !gsapOwns(input.element);
+  const plainTranslate =
+    !!input.gesture && editsPlainCss(input.element, input.gesture === "resize" ? "resize" : "move");
   // The APPLIED offset, never a dormant var, so a stale one can't fling the element off-screen.
   const initialOffset = plainTranslate
     ? readTranslatePx(input.element)

package/src/components/editor/plainTranslate.ts

@@ -1,5 +1,5 @@
 import { roundTo3 } from "../../utils/rounding";
-import { gsapWritesPosition, gsapWritesRotation } from "../../hooks/gsapRuntimeKeyframes";
+import { editsPlainCss } from "../../hooks/gsapRuntimeKeyframes";
 import { readCssRotation } from "../../hooks/draggedGsapPosition";
 import { readStudioPathOffset, readStudioRotation, styleUsesStudioOffset } from "./manualEditsDom";
 import { splitTopLevelWhitespace } from "./manualEditsStyleHelpers";
@@ -142,10 +142,12 @@ export function writeTranslatePx(el: HTMLElement, p: Point): void {
 }
 
 /** The position the panel shows and edits: the translate a move writes, unless GSAP positions it. */
-export function readMoveOffset(el: HTMLElement, plainTranslate = !gsapWritesPosition(el)): Point {
+export function readMoveOffset(el: HTMLElement, plainTranslate = editsPlainCss(el, "move")): Point {
   return plainTranslate ? readTranslatePx(el) : readStudioPathOffset(el);
 }
 
 export function readShownRotation(el: HTMLElement): { angle: number } {
-  return gsapWritesRotation(el) ? readStudioRotation(el) : { angle: roundTo3(readCssRotation(el)) };
+  return editsPlainCss(el, "rotate")
+    ? { angle: roundTo3(readCssRotation(el)) }
+    : readStudioRotation(el);
 }

package/src/components/editor/propertyPanelHelpers.ts

@@ -9,7 +9,7 @@ import {
   playbackStartAttributeForElement,
   readPlaybackStartAttributes,
 } from "../../player/lib/timelineElementHelpers";
-import { GSAP_TRANSFORM_KEYS, gsapWritesPosition } from "../../hooks/gsapRuntimeKeyframes";
+import { editsPlainCss, GSAP_TRANSFORM_KEYS } from "../../hooks/gsapRuntimeKeyframes";
 
 export type {
   BackgroundRemovalProgress,
@@ -496,7 +496,7 @@ export function readGsapRuntimeValuesForPanel(
     const el = findPreviewNode(iframe.contentDocument, element);
     if (!el) return null;
     const propKeys = collectPanelPropKeys(gsapAnimations);
-    const readsTransform = gsapWritesPosition(el);
+    const readsTransform = !editsPlainCss(el, "move");
     const result: Record<string, number> = {};
     for (const prop of propKeys) {
       if (!readsTransform && GSAP_TRANSFORM_KEYS.has(prop)) continue;

package/src/components/editor/propertyPanelTransformCommit.ts

@@ -1,4 +1,4 @@
-import { gsapWritesPosition } from "../../hooks/gsapRuntimeKeyframes";
+import { editsPlainCss } from "../../hooks/gsapRuntimeKeyframes";
 import type { DomEditSelection } from "./domEditingTypes";
 import { readStudioBoxSize } from "./manualEdits";
 import { readMoveOffset, UNREADABLE_TRANSLATE } from "./plainTranslate";
@@ -75,7 +75,7 @@ export function createTransformCommitHandlers({
       )
     )
       return;
-    const plainTranslate = !gsapWritesPosition(element.element);
+    const plainTranslate = editsPlainCss(element.element, "move");
     const current = readMoveOffset(element.element, plainTranslate);
     if (!Number.isFinite(current.x) || !Number.isFinite(current.y))
       return void showToast?.(UNREADABLE_TRANSLATE);

package/src/components/editor/rotationDraft.ts

@@ -51,7 +51,8 @@ export interface CssRotationTarget {
   inline: boolean;
 }
 
-export type RotationCommit = { angle: number; plain?: CssRotationTarget };
+export type PressChoseGsap = null;
+export type RotationCommit = { angle: number; plain?: CssRotationTarget | PressChoseGsap };
 
 const TRANSLATE = /^translate(?:3d|X|Y|Z)?\(/i;
 const OWN_TURN = /^rotate\(\s*-?[\d.]+(?:e[+-]?\d+)?deg\s*\)$/i;

package/src/components/editor/useDomEditOverlayGestures.ts

@@ -442,7 +442,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       }
       // Hold the final angle while the commit lands.
       applyRotationDraft(sel.element, finalRotation.angle, g.plainRotation);
-      const commit = g.plainRotation ? { ...finalRotation, plain: g.plainRotation } : finalRotation;
+      const commit = { ...finalRotation, plain: g.plainRotation };
       void Promise.resolve(opts.onRotationCommitRef.current(sel, commit))
         .then((result) => trackPreviewEditResult("rotate", "drag", result))
         .catch((error) => {
@@ -536,7 +536,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         if (finalOffset) restoreStudioPathOffset(sel.element, g.initialPathOffset);
       };
       void Promise.resolve(
-        opts.onBoxSizeCommitRef.current(sel, finalSize, finalOffset ?? undefined, restore),
+        opts.onBoxSizeCommitRef.current(sel, finalSize, finalOffset ?? undefined, restore, member),
       )
         .then((result) => trackPreviewEditResult("resize", "drag", result))
         .catch((error) => {

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -449,12 +449,12 @@ export const ROTATION_CHANNELS: string[] = [
 
 /** GSAP owns this element's position: a tween or hold writes it, or GSAP already renders its
  *  transform (a CSS translate would then apply twice). Everything else moves by plain CSS. */
-export function gsapWritesPosition(el: Element): boolean {
+function gsapWritesPosition(el: Element): boolean {
   return gsapRendersTransform(el) || gsapWritesChannels(el, MOVE_CHANNELS);
 }
 
 /** `gsapWritesPosition` for a rotate: everything else turns by its own CSS `rotate`. */
-export function gsapWritesRotation(el: Element): boolean {
+function gsapWritesRotation(el: Element): boolean {
   return gsapRendersTransform(el) || gsapWritesChannels(el, ROTATION_CHANNELS);
 }
 
@@ -474,10 +474,23 @@ const BOX_CHANNELS = [
 ];
 
 /** GSAP owns this element's box: its position, or any property the CSS box writer sets. Else a resize writes CSS. */
-export function gsapWritesBox(el: Element): boolean {
+function gsapWritesBox(el: Element): boolean {
   return gsapWritesPosition(el) || gsapWritesChannels(el, BOX_CHANNELS);
 }
 
+export type EditGesture = "move" | "resize" | "rotate";
+const GSAP_OWNS: Record<EditGesture, (el: Element) => boolean> = {
+  move: gsapWritesPosition,
+  resize: gsapWritesBox,
+  rotate: gsapWritesRotation,
+};
+
+/** The one GSAP-or-CSS route decision. Make it when an edit starts and carry it: mid-gesture
+ *  writes make GSAP render the element, so asking again at commit can flip the route. */
+export function editsPlainCss(el: Element, gesture: EditGesture): boolean {
+  return !GSAP_OWNS[gesture](el);
+}
+
 /** `hasNonHoldTweenForElement` for an element in hand, read from its own window's timelines. */
 export function elementHasNonHoldTween(el: Element, channels?: string[]): boolean {
   const win = el.ownerDocument.defaultView as {

package/src/hooks/gsapScriptCommitTypes.ts

@@ -44,7 +44,7 @@ export interface CommitMutationOptions {
    * error handling — a failed write still throws.
    */
   deferPreviewSync?: boolean;
-  /** Shares an in-place patch miss with the final render of one multi-write action. */
+  /** Carries a deferred write not yet on screen (no patch, or a missed one) to the final render. */
   previewFallbackLatch?: { pending: boolean };
   beforeReload?: () => void;
   /**

package/src/hooks/plainRotation.ts

@@ -27,7 +27,11 @@ export function savePlainRotation(
     ? buildClearRotationPatches(element)
     : [];
   if (patches.length) clearStudioRotation(element);
-  const drawn = applyCssRotation(element, next.angle, patches.length ? undefined : next.plain);
+  const drawn = applyCssRotation(
+    element,
+    next.angle,
+    patches.length ? undefined : (next.plain ?? undefined),
+  );
   patches.push(...drawn);
   const turn = drawn.at(-1)!;
   return commitPositionPatchToHtml(selection, patches, {

package/src/hooks/useDomEditPersist.test.tsx

@@ -0,0 +1,335 @@
+// @vitest-environment happy-dom
+import { act, createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import type { PatchOperation } from "../utils/sourcePatcher";
+import type { CutoverResult } from "../utils/sdkCutover";
+import { studioManualEditSavesIn } from "../components/editor/manualEditsDom";
+import {
+  DomEditPersistPreparedWriteError,
+  DomEditPersistUnresolvableError,
+  DomEditPersistUnsafeValueError,
+} from "./domEditPersistFailure";
+import type { PersistDomEditOperations } from "./domEditCommitTypes";
+import { jsonResponse, requestUrl } from "./fetchStubTestUtils";
+import { useDomEditPersist, type UseDomEditPersistParams } from "./useDomEditPersist";
+
+const trackStudioEvent = vi.fn();
+const reseekPreviewRuntime = vi.fn();
+vi.mock("../utils/studioTelemetry", () => ({
+  trackStudioEvent: (...args: unknown[]) => trackStudioEvent(...args),
+}));
+vi.mock("./timelineTrackVisibility", () => ({
+  reseekPreviewRuntime: (...args: unknown[]) => reseekPreviewRuntime(...args),
+}));
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+const SOURCE = '<div data-hf-id="hf-card" style="color: red">Card</div>';
+const PATCHED = '<div data-hf-id="hf-card" style="color: blue">Card</div>';
+const OPERATIONS: PatchOperation[] = [{ type: "inline-style", property: "color", value: "blue" }];
+const selection = {
+  hfId: "hf-card",
+  selector: '[data-hf-id="hf-card"]',
+  selectorIndex: 0,
+  sourceFile: "index.html",
+} as DomEditSelection;
+
+function stubServer(patchResponse: Record<string, unknown>) {
+  const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0], _init?: RequestInit) => {
+    const url = requestUrl(input);
+    if (url.includes("/api/projects/p1/files/")) return jsonResponse({ content: SOURCE });
+    if (url.includes("/api/projects/p1/file-mutations/patch-element/")) {
+      return jsonResponse(patchResponse);
+    }
+    throw new Error(`Unexpected fetch: ${url}`);
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+const CHANGED = { changed: true, content: PATCHED, path: "index.html", version: "v2" };
+const PREPARED = PATCHED.replace("Card", "Card!");
+const sdkResult = (result: CutoverResult) => vi.fn(async (): Promise<CutoverResult> => result);
+
+const patchPosts = (fetchMock: ReturnType<typeof stubServer>) =>
+  fetchMock.mock.calls.filter(([input]) => requestUrl(input).includes("/patch-element/"));
+
+let unmount: (() => void) | null = null;
+
+function renderPersist(over: Partial<UseDomEditPersistParams> = {}) {
+  const params: UseDomEditPersistParams = {
+    activeCompPath: "index.html",
+    previewIframeRef: { current: null },
+    showToast: vi.fn(),
+    queueDomEditSave: (save) => save(),
+    writeProjectFile: vi.fn(async () => {}),
+    editHistory: { recordEdit: vi.fn(async () => {}) },
+    projectIdRef: { current: "p1" },
+    reloadPreview: vi.fn(),
+    forceReloadSdkSession: vi.fn(),
+    ...over,
+  };
+  const captured: { persist: PersistDomEditOperations | null } = { persist: null };
+  function Probe() {
+    captured.persist = useDomEditPersist(params);
+    return null;
+  }
+  const root = createRoot(document.createElement("div"));
+  act(() => root.render(createElement(Probe)));
+  unmount = () => act(() => root.unmount());
+  if (!captured.persist) throw new Error("hook did not initialize");
+  return { persist: captured.persist, params };
+}
+
+describe("useDomEditPersist", () => {
+  beforeEach(() => {
+    trackStudioEvent.mockReset();
+    reseekPreviewRuntime.mockReset();
+  });
+  afterEach(() => {
+    unmount?.();
+    unmount = null;
+    vi.unstubAllGlobals();
+  });
+
+  it("patches the source, records the edit and reloads the preview", async () => {
+    const fetchMock = stubServer({
+      changed: true,
+      content: PATCHED,
+      path: "index.html",
+      version: "v2",
+    });
+    const { persist, params } = renderPersist();
+
+    const outcome = await persist(selection, OPERATIONS, { label: "Recolor" });
+
+    expect(outcome).toEqual({ sourceFile: "index.html", version: "v2", changed: true });
+    const [, init] = patchPosts(fetchMock)[0]!;
+    expect(JSON.parse(String(init?.body))).toEqual({
+      target: { hfId: "hf-card", selector: '[data-hf-id="hf-card"]', selectorIndex: 0 },
+      operations: OPERATIONS,
+    });
+    expect(params.editHistory.recordEdit).toHaveBeenCalledWith({
+      label: "Recolor",
+      coalesceKey: undefined,
+      coalesceMs: undefined,
+      files: { "index.html": { before: SOURCE, after: PATCHED } },
+    });
+    expect(params.forceReloadSdkSession).toHaveBeenCalledTimes(1);
+    expect(params.reloadPreview).toHaveBeenCalledTimes(1);
+    expect(reseekPreviewRuntime).not.toHaveBeenCalled();
+  });
+
+  it("with skipRefresh reseeks the preview instead of reloading it", async () => {
+    stubServer({ changed: true, content: PATCHED, path: "index.html", version: "v2" });
+    const { persist, params } = renderPersist();
+
+    await persist(selection, OPERATIONS, { skipRefresh: true });
+
+    expect(params.reloadPreview).not.toHaveBeenCalled();
+    expect(reseekPreviewRuntime).toHaveBeenCalledTimes(1);
+  });
+
+  it("an unchanged patch records nothing and reports changed: false", async () => {
+    stubServer({ changed: false, matched: true, path: "index.html", version: "v1" });
+    const { persist, params } = renderPersist();
+
+    const outcome = await persist(selection, OPERATIONS);
+
+    expect(outcome).toEqual({ sourceFile: "index.html", version: "v1", changed: false });
+    expect(params.editHistory.recordEdit).not.toHaveBeenCalled();
+    expect(params.reloadPreview).not.toHaveBeenCalled();
+  });
+
+  it("an unmatched target throws and is reported once per target", async () => {
+    stubServer({ changed: false, matched: false });
+    const { persist } = renderPersist();
+
+    await expect(persist(selection, OPERATIONS)).rejects.toBeInstanceOf(
+      DomEditPersistUnresolvableError,
+    );
+    await expect(persist(selection, OPERATIONS)).rejects.toBeInstanceOf(
+      DomEditPersistUnresolvableError,
+    );
+
+    expect(trackStudioEvent).toHaveBeenCalledTimes(1);
+    expect(trackStudioEvent).toHaveBeenCalledWith(
+      "save_skipped_unresolvable",
+      expect.objectContaining({ target_selector: '[data-hf-id="hf-card"]' }),
+    );
+  });
+
+  it("refuses a non-finite layout value before any request, with a toast", async () => {
+    const fetchMock = stubServer({ changed: true });
+    const { persist, params } = renderPersist();
+
+    await expect(
+      persist({ ...selection, selectorIndex: Number.NaN }, OPERATIONS),
+    ).rejects.toBeInstanceOf(DomEditPersistUnsafeValueError);
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(params.showToast).toHaveBeenCalledWith(
+      "Couldn't save edit because it contains invalid layout values",
+      "error",
+    );
+  });
+
+  it("a committed SDK cutover skips the server patch and the reload", async () => {
+    const fetchMock = stubServer({ changed: true });
+    const onTrySdkPersist = vi.fn(
+      async (): Promise<CutoverResult> => ({
+        status: "committed",
+        version: "sdk-3",
+        before: SOURCE,
+        after: PATCHED,
+      }),
+    );
+    const { persist, params } = renderPersist({ onTrySdkPersist });
+
+    const outcome = await persist(selection, OPERATIONS, { label: "Recolor" });
+
+    expect(outcome).toEqual({ sourceFile: "index.html", version: "sdk-3", changed: true });
+    expect(onTrySdkPersist).toHaveBeenCalledWith(selection, OPERATIONS, SOURCE, "index.html", {
+      label: "Recolor",
+      coalesceKey: undefined,
+      skipRefresh: undefined,
+    });
+    expect(patchPosts(fetchMock)).toHaveLength(0);
+    expect(params.reloadPreview).not.toHaveBeenCalled();
+    expect(params.forceReloadSdkSession).not.toHaveBeenCalled();
+  });
+
+  it("records the edit once, and reloads only after the record has settled", async () => {
+    stubServer(CHANGED);
+    let finishRecord = () => {};
+    const recordEdit = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          finishRecord = resolve;
+        }),
+    );
+    const { persist, params } = renderPersist({ editHistory: { recordEdit } });
+
+    const saving = persist(selection, OPERATIONS);
+    await vi.waitFor(() => expect(recordEdit).toHaveBeenCalledTimes(1));
+    expect(params.reloadPreview).not.toHaveBeenCalled();
+    finishRecord();
+    await saving;
+
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+    expect(params.reloadPreview).toHaveBeenCalledTimes(1);
+  });
+
+  it("writes prepared content after the patch and records it as the saved file", async () => {
+    stubServer(CHANGED);
+    const { persist, params } = renderPersist();
+
+    const outcome = await persist(selection, OPERATIONS, { prepareContent: () => PREPARED });
+
+    expect(params.writeProjectFile).toHaveBeenCalledWith("index.html", PREPARED, PATCHED);
+    expect(params.editHistory.recordEdit).toHaveBeenCalledWith(
+      expect.objectContaining({ files: { "index.html": { before: SOURCE, after: PREPARED } } }),
+    );
+    expect(params.reloadPreview).toHaveBeenCalledTimes(1);
+    expect(outcome).toBeUndefined();
+  });
+
+  it("a failed prepared write keeps the patch, reloads, then rejects", async () => {
+    stubServer(CHANGED);
+    const { persist, params } = renderPersist({
+      writeProjectFile: vi.fn(async () => {
+        throw new Error("disk full");
+      }),
+    });
+
+    const saving = persist(selection, OPERATIONS, { prepareContent: () => PREPARED });
+
+    await expect(saving).rejects.toBeInstanceOf(DomEditPersistPreparedWriteError);
+    expect(params.editHistory.recordEdit).toHaveBeenCalledWith(
+      expect.objectContaining({ files: { "index.html": { before: SOURCE, after: PATCHED } } }),
+    );
+    expect(params.reloadPreview).toHaveBeenCalledTimes(1);
+    expect(params.showToast).toHaveBeenCalledWith(
+      "Saved, but couldn't finish updating index.html: disk full",
+      "error",
+    );
+  });
+
+  it("a declined SDK cutover falls back to the server patch", async () => {
+    const fetchMock = stubServer(CHANGED);
+    const onTrySdkPersist = sdkResult({ status: "declined", reason: "unsupported" });
+    const { persist, params } = renderPersist({ onTrySdkPersist });
+
+    await persist(selection, OPERATIONS);
+
+    expect(onTrySdkPersist).toHaveBeenCalledTimes(1);
+    expect(patchPosts(fetchMock)).toHaveLength(1);
+    expect(params.editHistory.recordEdit).toHaveBeenCalledTimes(1);
+  });
+
+  it("a failed SDK cutover rethrows without a server patch", async () => {
+    const fetchMock = stubServer(CHANGED);
+    const error = new Error("sdk broke");
+    const { persist } = renderPersist({ onTrySdkPersist: sdkResult({ status: "failed", error }) });
+
+    await expect(persist(selection, OPERATIONS)).rejects.toBe(error);
+    expect(patchPosts(fetchMock)).toHaveLength(0);
+  });
+
+  it("an imported font or prepared content skips the SDK and goes to the server", async () => {
+    const fetchMock = stubServer(CHANGED);
+    const onTrySdkPersist = sdkResult({ status: "declined", reason: "unused" });
+    const { persist } = renderPersist({ onTrySdkPersist });
+    const importedFont = { family: "Inter", path: "fonts/inter.woff2", url: "/fonts/inter.woff2" };
+
+    await persist(selection, OPERATIONS, { importedFont });
+    await persist(selection, OPERATIONS, { prepareContent: (html) => html });
+
+    expect(onTrySdkPersist).not.toHaveBeenCalled();
+    const [[, fontInit]] = patchPosts(fetchMock);
+    expect(JSON.parse(String(fontInit?.body)).fontFaceCss).toContain("Inter");
+    expect(patchPosts(fetchMock)).toHaveLength(2);
+  });
+
+  it("counts a save on the edited element's document until it settles", async () => {
+    stubServer(CHANGED);
+    const element = document.createElement("div");
+    const { persist } = renderPersist();
+    const before = studioManualEditSavesIn(document);
+
+    const saving = persist({ ...selection, element }, OPERATIONS);
+    expect(studioManualEditSavesIn(document)).toBe(before + 1);
+    await saving;
+
+    expect(studioManualEditSavesIn(document)).toBe(before + 2);
+  });
+
+  it("does nothing when shouldSave says no", async () => {
+    const fetchMock = stubServer({ changed: true });
+    const { persist } = renderPersist();
+
+    await expect(persist(selection, OPERATIONS, { shouldSave: () => false })).resolves.toBe(
+      undefined,
+    );
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("refuses to save once the active project has changed", async () => {
+    stubServer({ changed: true });
+    const projectIdRef = { current: "p1" as string | null };
+    const { persist, params } = renderPersist({
+      projectIdRef,
+      queueDomEditSave: async (save) => {
+        projectIdRef.current = "p2";
+        return save();
+      },
+    });
+
+    await expect(persist(selection, OPERATIONS)).rejects.toThrow(
+      "Active project changed before the edit could be saved",
+    );
+    expect(params.editHistory.recordEdit).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useDomGeometryCommit.test.tsx

@@ -1,7 +1,7 @@
 // @vitest-environment happy-dom
 import { act, createElement, useRef } from "react";
 import { createRoot } from "react-dom/client";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi } from "vitest";
 import {
   useDomGeometryCommit,
   usePlayerStore,
@@ -108,6 +108,10 @@ afterEach(() => {
 });
 
 describe("useDomGeometryCommit, from the package entry", () => {
+  it("takes the host's own preview reload, with no fallback", () => {
+    expectTypeOf<UseDomGeometryCommitOptions["reloadPreview"]>().toEqualTypeOf<() => void>();
+  });
+
   it("plugs into DomEditOverlay and saves a move as one GSAP write and one undo step", async () => {
     const mutations = stubServer();
     const { element, recordEdit, hook, unmount } = renderHost();

package/src/hooks/useDomGeometryCommit.ts

@@ -26,8 +26,8 @@ import { useMountEffect } from "./useMountEffect";
  * mounts; drain `waitForPendingSaves` before switching projects.
  */
 export interface UseDomGeometryCommitOptions extends UseDomStyleCommitOptions {
-  /** Called when a save cannot patch the preview in place; defaults to reloading the iframe. */
-  reloadPreview?: () => void;
+  /** Reloads the host's preview when a save cannot patch it in place. */
+  reloadPreview: () => void;
 }
 
 export interface DomGeometryCommits {
@@ -42,6 +42,7 @@ export interface DomGeometryCommits {
     next: { width: number; height: number },
     offset?: { x: number; y: number },
     restore?: () => void,
+    route?: { plainTranslate: boolean },
   ) => Promise<DomEditCommitOutcome>;
   commitRotation: (
     selection: DomEditSelection,
@@ -70,17 +71,13 @@ export function useDomGeometryCommit({
   projectIdRef.current = projectId;
   const pending = useRef(new Set<Promise<GeometryCommitResult | undefined>>()).current;
   const editHistory = useMemo(() => ({ recordEdit }), [recordEdit]);
-  const reload = useCallback(
-    () => (reloadPreview ? reloadPreview() : iframeRef.current?.contentWindow?.location.reload()),
-    [reloadPreview, iframeRef],
-  );
   const { bump: bumpGsapCache } = useGsapCacheVersion();
   const gsap = useGsapScriptCommits({
     projectIdRef,
     activeCompPath,
     previewIframeRef: iframeRef,
     editHistory,
-    reloadPreview: reload,
+    reloadPreview,
     onCacheInvalidate: bumpGsapCache,
     showToast,
     writeProjectFile,
@@ -174,8 +171,8 @@ export function useDomGeometryCommit({
         saved(() => handleGsapAwarePathOffsetCommit(selection, next, modifiers)),
       commitGroupPathOffset: (updates) =>
         saved(() => handleGsapAwareGroupPathOffsetCommit(updates)),
-      commitBoxSize: (selection, next, offset, restore) =>
-        saved(() => handleGsapAwareBoxSizeCommit(selection, next, offset, restore), restore),
+      commitBoxSize: (selection, next, offset, restore, route) =>
+        saved(() => handleGsapAwareBoxSizeCommit(selection, next, offset, restore, route), restore),
       commitRotation: (selection, next) =>
         saved(() => handleGsapAwareRotationCommit(selection, next)),
       waitForPendingSaves: () => Promise.allSettled([...pending]).then(noop),