@hyperframes/studio 0.8.115 → 0.8.117

package/src/hooks/useAskAgentModal.ts

@@ -7,6 +7,7 @@ import { toProjectAbsolutePath, type AgentModalAnchorPoint } from "../utils/stud
 import { liveMarkupWithoutPreviewMarks } from "../utils/authoredSource";
 import { buildElementAgentPrompt, type DomEditSelection } from "../components/editor/domEditing";
 import { usePlayerStore } from "../player";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 // ── Types ──
 
@@ -55,7 +56,7 @@ export function useAskAgentModal({
 
       const targetPath = selection.sourceFile || activeCompPath || "index.html";
       try {
-        const response = await fetch(
+        const response = await studioApiFetch(
           buildProjectApiPath(pid, `/files/${encodeURIComponent(targetPath)}`),
         );
         if (!response.ok) return;

package/src/hooks/useBlockCatalog.ts

@@ -5,6 +5,7 @@ import {
   type BlockCategory,
   resolveBlockCategory,
 } from "../utils/blockCategories";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 type CatalogItem = RegistryItem & {
   category: BlockCategory;
@@ -14,7 +15,7 @@ let catalogCache: CatalogItem[] | null = null;
 let catalogRequest: Promise<CatalogItem[]> | null = null;
 
 function loadCatalog(): Promise<CatalogItem[]> {
-  catalogRequest ??= fetch("/api/registry/blocks")
+  catalogRequest ??= studioApiFetch("/api/registry/blocks")
     .then((response) => {
       if (!response.ok) throw new Error("Failed to load catalog");
       return response.json() as Promise<RegistryItem[]>;

package/src/hooks/useCaptionDetection.ts

@@ -5,6 +5,7 @@ import { useCaptionStore } from "../captions/store";
 import { acceptStudioRuntimeMessage } from "../player/lib/runtimeProtocol";
 import { useCaptionSync } from "../captions/hooks/useCaptionSync";
 import { parseCaptionComposition } from "../captions/parser";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 interface UseCaptionDetectionParams {
   projectId: string | null;
@@ -110,7 +111,7 @@ export function useCaptionDetection({
 
       activating = true;
       const srcPath = captionSrcPath;
-      fetch(buildProjectApiPath(projectId, `/files/${encodeURIComponent(srcPath)}`))
+      studioApiFetch(buildProjectApiPath(projectId, `/files/${encodeURIComponent(srcPath)}`))
         .then((r) => r.json())
         .then((data: { content?: string }) => {
           if (!data.content || !doc || !win || useCaptionStore.getState().isEditMode) return;

package/src/hooks/useCompositionContentLoader.ts

@@ -1,5 +1,6 @@
 import { buildProjectApiPath } from "../utils/projectRouting";
 import { useCallback } from "react";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 /**
  * Loads a composition file's content for the source editor when a composition
@@ -24,7 +25,7 @@ export function useCompositionContentLoader({
       if (!projectId) return;
       setActiveCompPath(comp.endsWith(".html") ? comp : null);
       setEditingFile({ path: comp, content: null });
-      fetch(buildProjectApiPath(projectId, `/files/${encodeURIComponent(comp)}`))
+      studioApiFetch(buildProjectApiPath(projectId, `/files/${encodeURIComponent(comp)}`))
         .then(async (r) => {
           if (!r.ok) throw new Error(`Failed to load ${comp} (${r.status})`);
           return r.json();

package/src/hooks/useDomEditCommitsHelpers.ts

@@ -7,6 +7,7 @@ import { buildProjectApiPath } from "../utils/projectRouting";
 import type { DomEditPatchBatch } from "./domEditCommitTypes";
 import { formatFieldsSuffix } from "./gsapScriptCommitHelpers";
 import { studioWriteHeaders } from "../utils/studioFileVersion";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 export function formatUnsafeFieldList(fields: Array<{ path: string }>): string {
   return fields.map((field) => field.path).join(", ");
@@ -99,7 +100,7 @@ function isAtomicElementPatchFile(value: unknown): value is AtomicElementPatchFi
 export async function patchElementBatches(projectId: string, batches: DomEditPatchBatch[]) {
   const body = JSON.stringify({ batches });
   try {
-    const response = await fetch(
+    const response = await studioApiFetch(
       `/api/projects/${encodeURIComponent(projectId)}/file-mutations/patch-element-batches`,
       {
         method: "POST",
@@ -178,7 +179,7 @@ export async function postPatchElement(
   body: unknown,
   showToast: ShowToast,
 ): Promise<PatchElementResponse> {
-  const response = await fetch(
+  const response = await studioApiFetch(
     buildProjectApiPath(
       projectId,
       `/file-mutations/patch-element/${encodeURIComponent(targetPath)}`,

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/useDomEditSession.test.tsx

@@ -10,6 +10,7 @@ import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import type { TimelineElement } from "../player";
 import type { UseDomEditSessionParams } from "./useDomEditSession";
 import { makeSelection } from "./domSelectionTestHarness";
+import { readTranslatePx } from "../components/editor/plainTranslate";
 
 const styleOp = (property: string, value: string): PatchOperation => ({
   type: "inline-style",
@@ -66,6 +67,7 @@ const groupSelectionSpy = vi.fn();
 const gsapCommitMutation = Object.assign(vi.fn(), { batch: vi.fn() });
 const neverParsed = new Promise<{ animations: GsapAnimation[] }>(() => undefined);
 const parsedFile = { current: neverParsed };
+const groupCommitSpy = vi.fn(async () => {});
 
 function createSessionParams(
   overrides: Partial<UseDomEditSessionParams> = {},
@@ -256,7 +258,7 @@ vi.mock("./usePreviewInteraction", () => ({
 vi.mock("./useGsapAwareEditing", () => ({
   useGsapAwareEditing: () => ({
     handleGsapAwarePathOffsetCommit: vi.fn(),
-    handleGsapAwareGroupPathOffsetCommit: vi.fn(),
+    handleGsapAwareGroupPathOffsetCommit: groupCommitSpy,
     handleGsapAwareBoxSizeCommit: vi.fn(),
     handleGsapAwareRotationCommit: vi.fn(),
     commitAnimatedProperty: vi.fn(),
@@ -605,3 +607,30 @@ describe("a shadow reload promoted without a host re-render", () => {
     act(() => root.unmount());
   });
 });
+
+describe("handleDomGroupMoveBy", () => {
+  it("saves through the group drag's commit, leaving a refusal for the host to explain", async () => {
+    const { useDomEditSession } = await import("./useDomEditSession");
+    const element = document.createElement("div");
+    document.body.append(element);
+    element.getBoundingClientRect = () => {
+      const { x, y } = readTranslatePx(element);
+      return new DOMRect(x, y, 40, 20);
+    };
+    const selection = makeSelection("card", element);
+    let moveBy!: ReturnType<typeof useDomEditSession>["handleDomGroupMoveBy"];
+    function Probe() {
+      moveBy = useDomEditSession(createSessionParams()).handleDomGroupMoveBy;
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(<Probe />));
+    await act(() => moveBy([{ selection, delta: { x: 10, y: 0 } }]));
+    expect(groupCommitSpy).toHaveBeenCalledWith(
+      [{ selection, next: { x: 10, y: 0 }, plainTranslate: true }],
+      { refusalToast: false },
+    );
+    act(() => root.unmount());
+    element.remove();
+  });
+});

package/src/hooks/useDomEditSession.ts

@@ -25,6 +25,7 @@ import { membersForDelete, timelineElementsForDelete } from "./domEditDeleteMemb
 import type { RecordEditInput } from "./domEditDeleteMembers";
 import type { DomEditTimelineParams } from "./useDomSelectionTypes";
 import { useLivePreviewIframe } from "./useLivePreviewIframe";
+import { moveDomGroupBy, type DomGroupMove } from "../components/editor/domGroupMoveBy";
 // Re-exported: the delete rule lives in its own module; callers and its test import it from here.
 export { membersForDelete };
 
@@ -445,6 +446,7 @@ export function useDomEditSession({
     domEditSelection,
     selectedGsapAnimations,
     gsapCommitMutation,
+    activeCompPath,
     previewIframeRef,
     showToast,
     bumpGsapCache,
@@ -459,6 +461,13 @@ export function useDomEditSession({
     setArcPath,
     updateArcSegment,
   });
+  const handleDomGroupMoveBy = useCallback(
+    (moves: DomGroupMove[]) =>
+      moveDomGroupBy(moves, (updates) =>
+        handleGsapAwareGroupPathOffsetCommit(updates, { refusalToast: false }),
+      ),
+    [handleGsapAwareGroupPathOffsetCommit],
+  );
   const { handleUpdateSegmentEase, handleUpdateKeyframeEase, handleSetAllKeyframeEases } =
     useKeyframeEaseCommits({ gsapCommitMutation, domEditSelectionRef });
   const committable = useCommitPreflightCapabilities({
@@ -497,6 +506,7 @@ export function useDomEditSession({
     handleDomAttributeBatchCommit,
     handleDomPathOffsetCommit: handleGsapAwarePathOffsetCommit,
     handleDomGroupPathOffsetCommit: handleGsapAwareGroupPathOffsetCommit,
+    handleDomGroupMoveBy,
     handleDomZIndexReorderCommit,
     handleDomBoxSizeCommit: handleGsapAwareBoxSizeCommit,
     handleDomRotationCommit: handleGsapAwareRotationCommit,

package/src/hooks/useDomEditTextCommits.test.tsx

@@ -350,6 +350,29 @@ describe("useDomEditTextCommits", () => {
     expect(outcome).toEqual({ ok: true, persistence });
   });
 
+  it("saves a style map on a selection as one patch, so it is one undo step", async () => {
+    const { iframe, element } = previewElement("<div id='card'>Original</div>", "card");
+    const persist = vi.fn().mockResolvedValue({ sourceFile: "index.html", changed: true });
+    const hook = renderTextCommitHook(
+      commitParams({
+        previewIframeRef: { current: iframe },
+        domEditSelection: null,
+        persistDomEditOperations: persist,
+      }),
+    );
+
+    await act(async () => {
+      await hook.handleDomStyleCommitForSelection(selectionFor(element), {
+        "border-width": "4px",
+        "border-style": "solid",
+      });
+    });
+
+    expect(persist).toHaveBeenCalledTimes(1);
+    expect(element.style.borderWidth).toBe("4px");
+    expect(element.style.borderStyle).toBe("solid");
+  });
+
   it("declines a style commit with no selection, without reaching the writer", async () => {
     const persistDomEditOperations = vi.fn().mockResolvedValue(undefined);
     const hook = renderTextCommitHook(

package/src/hooks/useDomEditTextCommits.ts

@@ -109,7 +109,11 @@ export function useDomEditTextCommits({
   });
 
   const handleDomStyleCommitForSelection = useCallback(
-    (selection: DomEditSelection, property: string, value: string): Promise<DomEditCommitOutcome> =>
+    (
+      selection: DomEditSelection,
+      propertyOrStylesAsOnePatch: string | Record<string, string>,
+      value = "",
+    ): Promise<DomEditCommitOutcome> =>
       commitDomStyles(
         {
           activeCompPath,
@@ -121,7 +125,9 @@ export function useDomEditTextCommits({
           resync: refreshDomEditSelectionFromPreview,
         },
         selection,
-        { [property]: value },
+        typeof propertyOrStylesAsOnePatch === "string"
+          ? { [propertyOrStylesAsOnePatch]: value }
+          : propertyOrStylesAsOnePatch,
       ),
     [
       activeCompPath,

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,
@@ -128,6 +125,7 @@ export function useDomGeometryCommit({
     domEditSelection: null,
     selectedGsapAnimations: NO_SELECTED_ANIMATIONS,
     gsapCommitMutation: gsap.commitMutation,
+    activeCompPath,
     previewIframeRef: iframeRef,
     showToast,
     bumpGsapCache,
@@ -173,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),