@hyperframes/studio 0.7.58 → 0.7.60

package/src/hooks/useDomEditAttributeCommits.ts

@@ -25,6 +25,7 @@ interface DataAttributeCommitOptions {
   coalescePrefix: string;
   skipRefresh: boolean;
   refreshAfter?: boolean;
+  onSettled?: (ok: boolean) => void;
 }
 
 function resolveFullAttrName(attr: string, prefixData: boolean | undefined): string {
@@ -57,6 +58,25 @@ interface CapturedAttributeElement {
   previousValue: string | null;
 }
 
+interface CapturedMultiAttributeElement {
+  element: HTMLElement;
+  previousValues: Map<string, string | null>;
+}
+
+function captureMultiAttributeElement(
+  doc: Document | null | undefined,
+  selection: DomEditSelection,
+  activeCompPath: string | null,
+  fullAttrs: string[],
+): CapturedMultiAttributeElement | null {
+  const el = findPreviewAttributeElement(doc, selection, activeCompPath);
+  if (!el) return null;
+  const previousValues = new Map(
+    fullAttrs.map((fullAttr) => [fullAttr, el.getAttribute(fullAttr)]),
+  );
+  return { element: el, previousValues };
+}
+
 function captureAttributeElement(
   doc: Document | null | undefined,
   selection: DomEditSelection,
@@ -128,6 +148,7 @@ export function useDomEditAttributeCommits({
         onError: (error) => reportDomEditPersistFailure(domEditSelection, [op], error, showToast),
         shouldResync: () => isLatestCommit() && !!options.refreshAfter,
         resync: () => refreshDomEditSelectionFromPreview(domEditSelection),
+        onSettled: options.onSettled,
       });
     },
     [
@@ -140,6 +161,105 @@ export function useDomEditAttributeCommits({
     ],
   );
 
+  // Commits several data-* attributes on the SAME element in ONE persist call
+  // — needed when two attributes together describe a single logical value
+  // (e.g. a pinned timing range's start+duration): committing them through two
+  // separate sequential `commitDataAttribute` calls leaves a window where the
+  // second call resolves `domEditSelection` fresh from current hook state, so
+  // a selection change between the two awaits would misdirect it at the
+  // NEWLY selected element instead of the one being edited, and a failure of
+  // just the second call would leave the two attributes in an inconsistent
+  // half-applied state. Bundling them into one `PatchOperation[]` against an
+  // explicit, caller-supplied `selection` (not the "current" one) closes both
+  // gaps — matching `onCommitAnimatedProperties`'s same-shaped fix for GSAP
+  // property batches.
+  const commitDataAttributes = useCallback(
+    async (
+      selection: DomEditSelection,
+      attrs: Record<string, string | null>,
+      options: DataAttributeCommitOptions,
+    ) => {
+      const iframe = previewIframeRef.current;
+      const entries = Object.entries(attrs).map(([attr, value]) => ({
+        attr,
+        fullAttr: resolveFullAttrName(attr, true),
+        value,
+      }));
+      const commitKey = `${options.coalescePrefix}:${entries
+        .map((entry) => entry.attr)
+        .sort()
+        .join(",")}:${getDomEditTargetKey(selection)}`;
+      const isLatestCommit = bumpDomEditCommitMapVersion(
+        domAttributeCommitVersionRef.current,
+        commitKey,
+      );
+      const ops: PatchOperation[] = entries.map((entry) => ({
+        type: "attribute",
+        property: entry.attr,
+        value: entry.value,
+      }));
+      let captured: CapturedMultiAttributeElement | null = null;
+
+      await runDomEditCommit({
+        capture: () => {
+          captured = captureMultiAttributeElement(
+            iframe?.contentDocument,
+            selection,
+            activeCompPath,
+            entries.map((entry) => entry.fullAttr),
+          );
+        },
+        apply: () => {
+          if (!captured) return;
+          for (const entry of entries) {
+            const nextValue = entry.value === null || entry.value === "" ? null : entry.value;
+            setOrRemovePreviewAttribute(captured.element, entry.fullAttr, nextValue);
+          }
+        },
+        persist: () =>
+          persistDomEditOperations(selection, ops, {
+            label: options.label,
+            coalesceKey: commitKey,
+            skipRefresh: options.skipRefresh,
+          }),
+        shouldRevert: () => isLatestCommit(),
+        revert: () => {
+          if (!captured) return;
+          for (const entry of entries) {
+            setOrRemovePreviewAttribute(
+              captured.element,
+              entry.fullAttr,
+              captured.previousValues.get(entry.fullAttr) ?? null,
+            );
+          }
+        },
+        onError: (error) => reportDomEditPersistFailure(selection, ops, error, showToast),
+        shouldResync: () => isLatestCommit() && !!options.refreshAfter,
+        resync: () => refreshDomEditSelectionFromPreview(selection),
+        onSettled: options.onSettled,
+      });
+    },
+    [
+      activeCompPath,
+      persistDomEditOperations,
+      refreshDomEditSelectionFromPreview,
+      showToast,
+      previewIframeRef,
+    ],
+  );
+
+  const handleDomAttributesCommit = useCallback(
+    async (selection: DomEditSelection, attrs: Record<string, string>) => {
+      await commitDataAttributes(selection, attrs, {
+        label: "Edit timing",
+        coalescePrefix: "attrs",
+        skipRefresh: false,
+        refreshAfter: true,
+      });
+    },
+    [commitDataAttributes],
+  );
+
   const handleDomAttributeCommit = useCallback(
     async (attr: string, value: string) => {
       await commitDataAttribute(attr, value, {
@@ -153,11 +273,12 @@ export function useDomEditAttributeCommits({
   );
 
   const handleDomAttributeLiveCommit = useCallback(
-    async (attr: string, value: string | null) => {
+    async (attr: string, value: string | null, onSettled?: (ok: boolean) => void) => {
       await commitDataAttribute(attr, value, {
         label: `Edit ${attr.replace(/^(data-)?/, "").replace(/-/g, " ")}`,
         coalescePrefix: "attr-live",
         skipRefresh: true,
+        onSettled,
       });
     },
     [commitDataAttribute],
@@ -223,5 +344,6 @@ export function useDomEditAttributeCommits({
     handleDomAttributeCommit,
     handleDomAttributeLiveCommit,
     handleDomHtmlAttributeCommit,
+    handleDomAttributesCommit,
   };
 }

package/src/hooks/useDomEditCommits.test.tsx

@@ -34,7 +34,7 @@ interface RenderedDomEditCommits {
 
 interface RenderDomEditCommitsOptions {
   importedFontAssets?: ImportedFontAsset[];
-  writeProjectFile?: (path: string, content: string) => Promise<void>;
+  writeProjectFile?: (path: string, content: string, expectedContent?: string) => Promise<void>;
 }
 
 type FetchHandler = (
@@ -1050,6 +1050,46 @@ describe("useDomEditCommits style persist handling", () => {
     }
   });
 
+  it("uses the patched server content as the custom-font write precondition", async () => {
+    const patchedContent =
+      '<!doctype html><html><head></head><body><div data-hf-id="hf-card">Card</div></body></html>';
+    stubPatchFetch(
+      { ok: true, changed: true, matched: true, content: patchedContent },
+      patchedContent,
+    );
+    const { iframe, element } = createPreviewElement();
+    const selection = createSelection(element, {
+      textFields: [textField({ key: "self", value: "Card", source: "self", tagName: "div" })],
+    });
+    const writeProjectFile = vi.fn(async () => {});
+    const rendered = renderDomEditCommits(selection, iframe, { writeProjectFile });
+
+    try {
+      await act(async () => {
+        await rendered.hook.commitDomTextFields(
+          selection,
+          [textField({ key: "self", value: "Card", source: "self", tagName: "div" })],
+          {
+            importedFont: {
+              family: "Imported",
+              path: "fonts/Imported.woff2",
+              url: "/api/projects/p1/preview/fonts/Imported.woff2",
+            },
+          },
+        );
+      });
+
+      expect(writeProjectFile).toHaveBeenCalledWith(
+        "index.html",
+        expect.stringContaining("@font-face"),
+        patchedContent,
+      );
+      expect(rendered.showToast).not.toHaveBeenCalled();
+    } finally {
+      rendered.cleanup();
+    }
+  });
+
   it("keeps a rejected patch request (HTTP error) to one toast", async () => {
     const { rendered, cleanup } = renderStyleCommitWithFetch(async (input) => {
       const url = requestUrl(input);

package/src/hooks/useDomEditCommits.ts

@@ -12,11 +12,7 @@ import {
 import { buildDomEditPatchTarget, type DomEditSelection } from "../components/editor/domEditing";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
 import type { EditHistoryKind } from "../utils/editHistory";
-import type {
-  CommitDomEditPatchBatches,
-  DomEditPatchBatch,
-  PersistDomEditOperations,
-} from "./domEditCommitTypes";
+import type { CommitDomEditPatchBatches, PersistDomEditOperations } from "./domEditCommitTypes";
 import type { PatchOperation } from "../utils/sourcePatcher";
 import {
   DomEditPersistUnsafeValueError,
@@ -27,31 +23,16 @@ import { useDomEditPositionPatchCommit } from "./useDomEditPositionPatchCommit";
 import { useDomEditTextCommits } from "./useDomEditTextCommits";
 import { useDomGeometryCommits } from "./useDomGeometryCommits";
 import { useElementLifecycleOps } from "./useElementLifecycleOps";
-import { formatFieldsSuffix } from "./gsapScriptCommitHelpers";
-
-// ── Helpers ──
-
-function formatUnsafeFieldList(fields: Array<{ path: string }>): string {
-  return fields.map((field) => field.path).join(", ");
-}
-
-function getErrorDetail(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-async function readErrorResponseBody(
-  response: Response,
-): Promise<{ error?: string; fields?: string[] } | null> {
-  const contentType = response.headers.get("content-type") ?? "";
-  if (!contentType.includes("application/json")) return null;
-  return (await response.json().catch(() => null)) as { error?: string; fields?: string[] } | null;
-}
-
-function formatPatchRejectionMessage(body: { error?: string; fields?: string[] } | null): string {
-  if (!body?.error) return "Couldn't save edit";
-  return `Couldn't save edit: ${body.error}${formatFieldsSuffix(body.fields)}`;
-}
-
+import {
+  AtomicElementPatchConvergenceError,
+  batchesAreInlineStyleOnly,
+  formatPatchRejectionMessage,
+  formatUnsafeFieldList,
+  getErrorDetail,
+  patchElementBatches,
+  readErrorResponseBody,
+} from "./useDomEditCommitsHelpers";
+import { cutoverCommittedOrThrow, type CutoverResult } from "../utils/sdkCutover";
 interface RecordEditInput {
   label: string;
   kind: EditHistoryKind;
@@ -60,144 +41,12 @@ interface RecordEditInput {
   files: Record<string, { before: string; after: string }>;
 }
 
-/** Human-readable identifier for a batch patch target (for the unmatched warning). */
-function describeBatchPatchTarget(patch: DomEditPatchBatch["patches"][number]): string {
-  return patch.target.id ?? patch.target.hfId ?? patch.target.selector ?? "(unaddressed)";
-}
-
-/**
- * Surface server-reported unmatched patches. The server atomically refuses the
- * whole multi-file gesture; the caller uses `durable: false` to roll back and
- * reload, so report the refusal without turning it into a second failure.
- */
-function reportUnmatchedBatchPatches(batch: DomEditPatchBatch, matched: boolean[]): void {
-  const unmatchedIds = batch.patches
-    .filter((_, index) => matched[index] === false)
-    .map(describeBatchPatchTarget);
-  if (unmatchedIds.length === 0) return;
-  console.warn(
-    `[studio] z-index reorder: server could not match ${unmatchedIds.length} patch target(s) in ` +
-      `${batch.sourceFile} (the whole z-order gesture will revert on reload):`,
-    unmatchedIds.join(", "),
-  );
-  trackStudioSaveFailure({
-    source: "dom_edit",
-    error: new Error(`Batch patch target(s) unmatched: ${unmatchedIds.join(", ")}`),
-    filePath: batch.sourceFile,
-    mutationType: "z-reorder-unmatched",
-  });
-}
-
-interface AtomicElementPatchFile {
-  sourceFile: string;
-  changed: boolean;
-  matched?: boolean[];
-  before: string;
-  after: string;
-}
-
-class AtomicElementPatchConvergenceError extends Error {
-  constructor(message: string, options?: { cause?: unknown }) {
-    super(message, options);
-    this.name = "AtomicElementPatchConvergenceError";
-  }
-}
-
-// Keep the atomic response contract in one guard so callers do not compose validity.
-// fallow-ignore-next-line complexity
-function isAtomicElementPatchFile(value: unknown): value is AtomicElementPatchFile {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    "sourceFile" in value &&
-    typeof value.sourceFile === "string" &&
-    "changed" in value &&
-    typeof value.changed === "boolean" &&
-    (!("matched" in value) ||
-      (Array.isArray(value.matched) &&
-        value.matched.every((matched) => typeof matched === "boolean"))) &&
-    "before" in value &&
-    typeof value.before === "string" &&
-    "after" in value &&
-    typeof value.after === "string" &&
-    value.changed === (value.before !== value.after)
-  );
-}
-
-// This is the single client owner for dispatching and validating the aggregate
-// atomic endpoint. Splitting validation from the request would weaken that wire contract.
-// fallow-ignore-next-line complexity
-async function patchElementBatches(projectId: string, batches: DomEditPatchBatch[]) {
-  const body = JSON.stringify({ batches });
-  try {
-    const response = await fetch(
-      `/api/projects/${encodeURIComponent(projectId)}/file-mutations/patch-element-batches`,
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body,
-      },
-    );
-    if (!response.ok) {
-      const rejection = await readErrorResponseBody(response);
-      throw new StudioSaveHttpError(formatPatchRejectionMessage(rejection), response.status);
-    }
-    const result: unknown = await response.json().catch(() => null);
-    if (
-      typeof result !== "object" ||
-      result === null ||
-      !("durable" in result) ||
-      typeof result.durable !== "boolean" ||
-      !("files" in result) ||
-      !Array.isArray(result.files) ||
-      result.files.length !== batches.length ||
-      !result.files.every(isAtomicElementPatchFile) ||
-      (!result.durable && result.files.some((file) => file.changed))
-    ) {
-      throw new StudioSaveHttpError("Invalid atomic element patch response", 502);
-    }
-    const files = result.files.map((file, index) => {
-      const batch = batches[index];
-      const matched = file.matched ?? [];
-      if (
-        !batch ||
-        file.sourceFile !== batch.sourceFile ||
-        (matched.length !== 0 && matched.length !== batch.patches.length)
-      ) {
-        throw new StudioSaveHttpError("Invalid atomic element patch response", 502);
-      }
-      reportUnmatchedBatchPatches(batch, matched);
-      return {
-        ...file,
-        matched,
-        allMatched: matched.length === batch.patches.length && matched.every(Boolean),
-      };
-    });
-    return { durable: result.durable, files };
-  } catch (error) {
-    throw new AtomicElementPatchConvergenceError(getErrorDetail(error), { cause: error });
-  }
-}
-
-/**
- * A batch is reload-skippable only when it is style-only: every operation is an
- * `inline-style` write. The z-reorder commit applies those exact styles to the
- * live iframe DOM synchronously, so persisting them adds nothing the preview
- * doesn't already show. Any other op type (attribute / text-content / …) can
- * have server-side semantics the live DOM hasn't mirrored — reload for those.
- */
-function batchesAreInlineStyleOnly(batches: DomEditPatchBatch[]): boolean {
-  return batches.every((batch) =>
-    batch.patches.every((patch) => patch.operations.every((op) => op.type === "inline-style")),
-  );
-}
-
 export interface UseDomEditCommitsParams {
   activeCompPath: string | null;
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
   showToast: (message: string, tone?: "error" | "info") => void;
   queueDomEditSave: <T>(save: () => Promise<T>) => Promise<T>;
-  writeProjectFile: (path: string, content: string) => Promise<void>;
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
   domEditSaveTimestampRef: React.MutableRefObject<number>;
   editHistory: { recordEdit: (entry: RecordEditInput) => Promise<void> };
   fileTree: string[];
@@ -222,16 +71,20 @@ export interface UseDomEditCommitsParams {
    * path, whose session is already current) so a later SDK edit doesn't
    * serialize the pre-write doc and revert the server's change. */
   forceReloadSdkSession?: () => void;
-  /** Stage 7 Step 3c: called before the server-side patch path; returns true if SDK handled it. */
+  /** Stage 7 Step 3c: called before the server-side patch path. */
   onTrySdkPersist?: (
     selection: DomEditSelection,
     operations: PatchOperation[],
     originalContent: string,
     targetPath: string,
     options?: { label?: string; coalesceKey?: string; skipRefresh?: boolean },
-  ) => Promise<boolean>;
-  /** Stage 7 §3.1: called before the server-side delete path; returns true if SDK handled it. */
-  onTrySdkDelete?: (hfId: string, originalContent: string, targetPath: string) => Promise<boolean>;
+  ) => Promise<CutoverResult>;
+  /** Stage 7 §3.1: called before the server-side delete path. */
+  onTrySdkDelete?: (
+    hfId: string,
+    originalContent: string,
+    targetPath: string,
+  ) => Promise<CutoverResult>;
   /** Resolver-shadow tripwire for z-index reorder targets (telemetry-only, decoupled from cutover). */
   onReorderShadow?: (targets: string[]) => void;
 }
@@ -326,18 +179,17 @@ export function useDomEditCommits({
       // Skip the SDK path when prepareContent is set (e.g. @font-face injection
       // for a custom font): sdkCutoverPersist serializes only the patched DOM
       // and would drop the injected content. Let the server path run prepareContent.
-      if (
-        onTrySdkPersist &&
-        !options?.prepareContent &&
-        (await onTrySdkPersist(selection, operations, originalContent, targetPath, {
+      if (onTrySdkPersist && !options?.prepareContent) {
+        const cutover = await onTrySdkPersist(selection, operations, originalContent, targetPath, {
           label: options?.label,
           coalesceKey: options?.coalesceKey,
           skipRefresh: options?.skipRefresh,
-        }))
-      ) {
-        // SDK handled it — its in-memory doc is already current, so do NOT
-        // forceReload (that would echo-reload the session we just wrote).
-        return;
+        });
+        if (cutoverCommittedOrThrow(cutover)) {
+          // SDK handled it — its in-memory doc is already current, so do NOT
+          // forceReload (that would echo-reload the session we just wrote).
+          return;
+        }
       }
 
       // Mark the save timestamp before the file write so the SSE file-change
@@ -393,7 +245,7 @@ export function useDomEditCommits({
         const preparedContent = options.prepareContent(patchedContent, targetPath);
         if (preparedContent !== patchedContent) {
           try {
-            await writeProjectFile(targetPath, preparedContent);
+            await writeProjectFile(targetPath, preparedContent, patchedContent);
             finalContent = preparedContent;
           } catch (error) {
             // The patch above already landed on disk — only the prepareContent
@@ -523,6 +375,7 @@ export function useDomEditCommits({
     handleDomAttributeCommit,
     handleDomAttributeLiveCommit,
     handleDomHtmlAttributeCommit,
+    handleDomAttributesCommit,
     handleDomTextCommit,
     commitDomTextFields,
     handleDomTextFieldStyleCommit,
@@ -585,6 +438,7 @@ export function useDomEditCommits({
     handleDomAttributeCommit,
     handleDomAttributeLiveCommit,
     handleDomHtmlAttributeCommit,
+    handleDomAttributesCommit,
     handleDomTextCommit,
     commitDomTextFields,
     handleDomTextFieldStyleCommit,

package/src/hooks/useDomEditCommitsHelpers.ts

@@ -0,0 +1,158 @@
+import { StudioSaveHttpError, trackStudioSaveFailure } from "../utils/studioSaveDiagnostics";
+import type { DomEditPatchBatch } from "./domEditCommitTypes";
+import { formatFieldsSuffix } from "./gsapScriptCommitHelpers";
+
+export function formatUnsafeFieldList(fields: Array<{ path: string }>): string {
+  return fields.map((field) => field.path).join(", ");
+}
+
+export function getErrorDetail(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export async function readErrorResponseBody(
+  response: Response,
+): Promise<{ error?: string; fields?: string[] } | null> {
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("application/json")) return null;
+  return (await response.json().catch(() => null)) as { error?: string; fields?: string[] } | null;
+}
+
+export function formatPatchRejectionMessage(
+  body: { error?: string; fields?: string[] } | null,
+): string {
+  if (!body?.error) return "Couldn't save edit";
+  return `Couldn't save edit: ${body.error}${formatFieldsSuffix(body.fields)}`;
+}
+
+/** Human-readable identifier for a batch patch target (for the unmatched warning). */
+function describeBatchPatchTarget(patch: DomEditPatchBatch["patches"][number]): string {
+  return patch.target.id ?? patch.target.hfId ?? patch.target.selector ?? "(unaddressed)";
+}
+
+/**
+ * Surface server-reported unmatched patches. The server atomically refuses the
+ * whole multi-file gesture; the caller uses `durable: false` to roll back and
+ * reload, so report the refusal without turning it into a second failure.
+ */
+function reportUnmatchedBatchPatches(batch: DomEditPatchBatch, matched: boolean[]): void {
+  const unmatchedIds = batch.patches
+    .filter((_, index) => matched[index] === false)
+    .map(describeBatchPatchTarget);
+  if (unmatchedIds.length === 0) return;
+  console.warn(
+    `[studio] z-index reorder: server could not match ${unmatchedIds.length} patch target(s) in ` +
+      `${batch.sourceFile} (the whole z-order gesture will revert on reload):`,
+    unmatchedIds.join(", "),
+  );
+  trackStudioSaveFailure({
+    source: "dom_edit",
+    error: new Error(`Batch patch target(s) unmatched: ${unmatchedIds.join(", ")}`),
+    filePath: batch.sourceFile,
+    mutationType: "z-reorder-unmatched",
+  });
+}
+
+interface AtomicElementPatchFile {
+  sourceFile: string;
+  changed: boolean;
+  matched?: boolean[];
+  before: string;
+  after: string;
+}
+
+export class AtomicElementPatchConvergenceError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "AtomicElementPatchConvergenceError";
+  }
+}
+
+// Keep the atomic response contract in one guard so callers do not compose validity.
+// fallow-ignore-next-line complexity
+function isAtomicElementPatchFile(value: unknown): value is AtomicElementPatchFile {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "sourceFile" in value &&
+    typeof value.sourceFile === "string" &&
+    "changed" in value &&
+    typeof value.changed === "boolean" &&
+    (!("matched" in value) ||
+      (Array.isArray(value.matched) &&
+        value.matched.every((matched) => typeof matched === "boolean"))) &&
+    "before" in value &&
+    typeof value.before === "string" &&
+    "after" in value &&
+    typeof value.after === "string" &&
+    value.changed === (value.before !== value.after)
+  );
+}
+
+// This is the single client owner for dispatching and validating the aggregate
+// atomic endpoint. Splitting validation from the request would weaken that wire contract.
+// fallow-ignore-next-line complexity
+export async function patchElementBatches(projectId: string, batches: DomEditPatchBatch[]) {
+  const body = JSON.stringify({ batches });
+  try {
+    const response = await fetch(
+      `/api/projects/${encodeURIComponent(projectId)}/file-mutations/patch-element-batches`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body,
+      },
+    );
+    if (!response.ok) {
+      const rejection = await readErrorResponseBody(response);
+      throw new StudioSaveHttpError(formatPatchRejectionMessage(rejection), response.status);
+    }
+    const result: unknown = await response.json().catch(() => null);
+    if (
+      typeof result !== "object" ||
+      result === null ||
+      !("durable" in result) ||
+      typeof result.durable !== "boolean" ||
+      !("files" in result) ||
+      !Array.isArray(result.files) ||
+      result.files.length !== batches.length ||
+      !result.files.every(isAtomicElementPatchFile) ||
+      (!result.durable && result.files.some((file) => file.changed))
+    ) {
+      throw new StudioSaveHttpError("Invalid atomic element patch response", 502);
+    }
+    const files = result.files.map((file, index) => {
+      const batch = batches[index];
+      const matched = file.matched ?? [];
+      if (
+        !batch ||
+        file.sourceFile !== batch.sourceFile ||
+        (matched.length !== 0 && matched.length !== batch.patches.length)
+      ) {
+        throw new StudioSaveHttpError("Invalid atomic element patch response", 502);
+      }
+      reportUnmatchedBatchPatches(batch, matched);
+      return {
+        ...file,
+        matched,
+        allMatched: matched.length === batch.patches.length && matched.every(Boolean),
+      };
+    });
+    return { durable: result.durable, files };
+  } catch (error) {
+    throw new AtomicElementPatchConvergenceError(getErrorDetail(error), { cause: error });
+  }
+}
+
+/**
+ * A batch is reload-skippable only when it is style-only: every operation is an
+ * `inline-style` write. The z-reorder commit applies those exact styles to the
+ * live iframe DOM synchronously, so persisting them adds nothing the preview
+ * doesn't already show. Any other op type (attribute / text-content / …) can
+ * have server-side semantics the live DOM hasn't mirrored — reload for those.
+ */
+export function batchesAreInlineStyleOnly(batches: DomEditPatchBatch[]): boolean {
+  return batches.every((batch) =>
+    batch.patches.every((patch) => patch.operations.every((op) => op.type === "inline-style")),
+  );
+}