@hyperframes/studio 0.7.55 → 0.7.57

package/src/hooks/useDomEditCommits.test.tsx

@@ -6,6 +6,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { MutableRefObject } from "react";
 import type { DomEditSelection, DomEditTextField } from "../components/editor/domEditing";
 import type { ImportedFontAsset } from "../components/editor/fontAssets";
+import { usePlayerStore } from "../player";
 import { StudioSaveHttpError } from "../utils/studioSaveDiagnostics";
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import { useDomEditCommits } from "./useDomEditCommits";
@@ -27,6 +28,7 @@ interface RenderedDomEditCommits {
   hook: ReturnType<typeof useDomEditCommits>;
   showToast: ReturnType<typeof makeShowToast>;
   recordEdit: ReturnType<typeof vi.fn<() => Promise<void>>>;
+  reloadPreview: ReturnType<typeof vi.fn>;
   cleanup: () => void;
 }
 
@@ -209,6 +211,7 @@ function renderDomEditCommits(
   const previewIframeRef: MutableRefObject<HTMLIFrameElement | null> = { current: iframe };
   const projectIdRef: MutableRefObject<string | null> = { current: "p1" };
   const domEditSaveTimestampRef: MutableRefObject<number> = { current: 0 };
+  const reloadPreview = vi.fn();
 
   function Probe() {
     captured.current = useDomEditCommits({
@@ -223,7 +226,7 @@ function renderDomEditCommits(
       importedFontAssetsRef: { current: options.importedFontAssets ?? [] },
       projectId: "p1",
       projectIdRef,
-      reloadPreview: vi.fn(),
+      reloadPreview,
       domEditSelection: selection,
       applyDomSelection: vi.fn(),
       clearDomSelection: vi.fn(),
@@ -244,6 +247,7 @@ function renderDomEditCommits(
     hook: captured.current,
     showToast,
     recordEdit,
+    reloadPreview,
     cleanup: () => {
       act(() => {
         root.unmount();
@@ -253,6 +257,246 @@ function renderDomEditCommits(
   } satisfies RenderedDomEditCommits;
 }
 
+describe("useDomEditCommits z-index reorder persistence", () => {
+  beforeEach(() => {
+    ensureCssEscape();
+    vi.clearAllMocks();
+    vi.unstubAllGlobals();
+    document.body.replaceChildren();
+  });
+
+  it("persists an N-element reorder with one batch POST, one undo entry, and NO iframe reload", async () => {
+    const original =
+      '<div id="a" style="z-index: 1"></div><div id="b" style="z-index: 2"></div><div id="c" style="z-index: 3"></div>';
+    const after =
+      '<div id="a" style="z-index: 3"></div><div id="b" style="z-index: 2"></div><div id="c" style="z-index: 1"></div>';
+    const fetchMock = vi.fn(
+      async (
+        input: Parameters<typeof fetch>[0],
+        _init?: Parameters<typeof fetch>[1],
+      ): Promise<Response> => {
+        const url = requestUrl(input);
+        if (url.includes("/api/projects/p1/files/")) return jsonResponse({ content: original });
+        if (url.includes("/file-mutations/patch-elements-batch/")) {
+          return jsonResponse({
+            ok: true,
+            changed: true,
+            matched: [true, true, true],
+            content: after,
+          });
+        }
+        if (url.includes("/file-mutations/patch-element/")) {
+          return jsonResponse({ ok: true, changed: true, matched: true, content: after });
+        }
+        throw new Error(`Unexpected fetch: ${url}`);
+      },
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    const { iframe, element } = createPreviewElement(
+      '<div data-hf-id="hf-card"></div><div id="b"></div><div id="c"></div>',
+    );
+    element.id = "a";
+    const elements = [
+      element,
+      iframe.contentDocument!.getElementById("b")!,
+      iframe.contentDocument!.getElementById("c")!,
+    ];
+    const rendered = renderDomEditCommits(createSelection(element), iframe);
+
+    try {
+      await act(async () => {
+        await rendered.hook.handleDomZIndexReorderCommit(
+          elements.map((item, index) => ({
+            element: item,
+            zIndex: 3 - index,
+            id: item.id,
+            sourceFile: "index.html",
+          })),
+          "z-reorder:test",
+        );
+      });
+
+      const batchPosts = fetchMock.mock.calls.filter(([input]) =>
+        requestUrl(input).includes("/file-mutations/patch-elements-batch/"),
+      );
+      const singlePosts = fetchMock.mock.calls.filter(([input]) =>
+        requestUrl(input).includes("/file-mutations/patch-element/"),
+      );
+      expect(batchPosts).toHaveLength(1);
+      expect(singlePosts).toHaveLength(0);
+      expect(JSON.parse(String(batchPosts[0]?.[1]?.body))).toEqual({
+        patches: expect.arrayContaining([
+          expect.objectContaining({ target: expect.objectContaining({ id: "a" }) }),
+          expect.objectContaining({ target: expect.objectContaining({ id: "b" }) }),
+          expect.objectContaining({ target: expect.objectContaining({ id: "c" }) }),
+        ]),
+      });
+      expect(rendered.recordEdit).toHaveBeenCalledTimes(1);
+      expect(rendered.recordEdit).toHaveBeenCalledWith({
+        label: "Reorder layers",
+        kind: "manual",
+        coalesceKey: "z-reorder:test",
+        files: { "index.html": { before: original, after } },
+      });
+      // FIX: a z-only reorder must NOT remount the preview iframe ("the blink").
+      // The live DOM + store already hold the final state and the server matched
+      // every style-only patch, so the reload is provably redundant.
+      expect(rendered.reloadPreview).not.toHaveBeenCalled();
+    } finally {
+      rendered.cleanup();
+    }
+  });
+
+  it("falls back to reloading when the server response omits matched[]", async () => {
+    // Without a matched[] confirmation the persist can't be proven in sync with
+    // the live DOM — the skip-reload path must not engage.
+    const original = '<div id="a" style="z-index: 1"></div>';
+    const after = '<div id="a" style="z-index: 2"></div>';
+    const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]): Promise<Response> => {
+      const url = requestUrl(input);
+      if (url.includes("/api/projects/p1/files/")) return jsonResponse({ content: original });
+      if (url.includes("/file-mutations/patch-elements-batch/")) {
+        return jsonResponse({ ok: true, changed: true, content: after });
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const { iframe, element } = createPreviewElement();
+    element.id = "a";
+    const rendered = renderDomEditCommits(createSelection(element), iframe);
+
+    try {
+      await act(async () => {
+        await rendered.hook.handleDomZIndexReorderCommit([
+          { element, zIndex: 2, id: "a", sourceFile: "index.html" },
+        ]);
+      });
+
+      expect(rendered.recordEdit).toHaveBeenCalledTimes(1);
+      expect(rendered.reloadPreview).toHaveBeenCalledTimes(1);
+    } finally {
+      rendered.cleanup();
+    }
+  });
+
+  it("warns and reports telemetry for unmatched batch patches without throwing", async () => {
+    // The server reports per-patch matched[]: #b was not found in the source.
+    // The matched subset persisted, so the commit must complete (no rollback of
+    // applied state) while surfacing the partial failure. An unmatched target
+    // also means the live DOM shows z-order the disk lacks, so the skip-reload
+    // path must NOT engage — the reload reconverges the preview with disk.
+    const original = '<div id="a" style="z-index: 1"></div>';
+    const after = '<div id="a" style="z-index: 2"></div>';
+    const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]): Promise<Response> => {
+      const url = requestUrl(input);
+      if (url.includes("/api/projects/p1/files/")) return jsonResponse({ content: original });
+      if (url.includes("/file-mutations/patch-elements-batch/")) {
+        return jsonResponse({ ok: true, changed: true, matched: [true, false], content: after });
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { iframe, element } = createPreviewElement(
+      '<div data-hf-id="hf-card"></div><div id="b"></div>',
+    );
+    element.id = "a";
+    const second = iframe.contentDocument!.getElementById("b")!;
+    const rendered = renderDomEditCommits(createSelection(element), iframe);
+
+    try {
+      await act(async () => {
+        await rendered.hook.handleDomZIndexReorderCommit([
+          { element, zIndex: 2, id: "a", sourceFile: "index.html" },
+          { element: second, zIndex: 1, id: "b", sourceFile: "index.html" },
+        ]);
+      });
+
+      // No throw: the applied live state stays, the matched subset is recorded.
+      expect(element.style.zIndex).toBe("2");
+      expect(second.style.zIndex).toBe("1");
+      expect(rendered.recordEdit).toHaveBeenCalledTimes(1);
+      expect(rendered.reloadPreview).toHaveBeenCalledTimes(1);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("could not match 1 patch target(s) in index.html"),
+        "b",
+      );
+      expect(trackStudioEvent).toHaveBeenCalledWith(
+        "save_failure",
+        expect.objectContaining({
+          mutation_type: "z-reorder-unmatched",
+          file_path: "index.html",
+          error_message: expect.stringContaining("b"),
+        }),
+      );
+    } finally {
+      warnSpy.mockRestore();
+      rendered.cleanup();
+    }
+  });
+
+  it("rolls back live state after a failed batch POST without a disk write-back", async () => {
+    const original = '<div id="a" style="z-index: 7"></div><div id="b"></div>';
+    const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]): Promise<Response> => {
+      const url = requestUrl(input);
+      if (url.includes("/api/projects/p1/files/")) return jsonResponse({ content: original });
+      if (url.includes("/file-mutations/patch-elements-batch/")) {
+        return jsonResponse({ error: "batch rejected" }, 500);
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const writeProjectFile = vi.fn(async () => {});
+    const { iframe, element } = createPreviewElement(
+      '<div data-hf-id="hf-card" style="z-index: 7"></div><div id="b"></div>',
+    );
+    element.id = "a";
+    const second = iframe.contentDocument!.getElementById("b")!;
+    usePlayerStore.getState().setElements([
+      { id: "a", tag: "div", start: 0, duration: 1, track: 0, zIndex: 7, hasExplicitZIndex: true },
+      { id: "b", tag: "div", start: 0, duration: 1, track: 1, zIndex: 0, hasExplicitZIndex: false },
+    ]);
+    const rendered = renderDomEditCommits(createSelection(element), iframe, { writeProjectFile });
+
+    try {
+      let rejection: unknown;
+      await act(async () => {
+        try {
+          await rendered.hook.handleDomZIndexReorderCommit([
+            { element, zIndex: 2, id: "a", sourceFile: "index.html", key: "a" },
+            { element: second, zIndex: 1, id: "b", sourceFile: "index.html", key: "b" },
+          ]);
+        } catch (error) {
+          rejection = error;
+        }
+      });
+
+      expect(rejection).toBeInstanceOf(Error);
+      expect((rejection as Error).message).toContain("batch rejected");
+      expect(element.style.zIndex).toBe("7");
+      expect(second.style.zIndex).toBe("");
+      expect(
+        usePlayerStore
+          .getState()
+          .elements.map(({ zIndex, hasExplicitZIndex }) => ({ zIndex, hasExplicitZIndex })),
+      ).toEqual([
+        { zIndex: 7, hasExplicitZIndex: true },
+        { zIndex: 0, hasExplicitZIndex: false },
+      ]);
+      expect(writeProjectFile).not.toHaveBeenCalled();
+      expect(rendered.recordEdit).not.toHaveBeenCalled();
+      expect(rendered.reloadPreview).not.toHaveBeenCalled();
+      expect(
+        fetchMock.mock.calls.filter(([input]) =>
+          requestUrl(input).includes("/file-mutations/patch-elements-batch/"),
+        ),
+      ).toHaveLength(1);
+    } finally {
+      rendered.cleanup();
+    }
+  });
+});
+
 async function commitStyleAgainst(response: Parameters<typeof stubPatchFetch>[0]) {
   stubPatchFetch(response);
   const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});

package/src/hooks/useDomEditCommits.ts

@@ -4,11 +4,19 @@ import { FONT_EXT } from "../utils/mediaTypes";
 
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import { primaryFontFamilyValue } from "../utils/studioFontHelpers";
-import { createStudioSaveHttpError } from "../utils/studioSaveDiagnostics";
+import {
+  createStudioSaveHttpError,
+  StudioSaveHttpError,
+  trackStudioSaveFailure,
+} from "../utils/studioSaveDiagnostics";
 import { buildDomEditPatchTarget, type DomEditSelection } from "../components/editor/domEditing";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
 import type { EditHistoryKind } from "../utils/editHistory";
-import type { PersistDomEditOperations } from "./domEditCommitTypes";
+import type {
+  CommitDomEditPatchBatches,
+  DomEditPatchBatch,
+  PersistDomEditOperations,
+} from "./domEditCommitTypes";
 import type { PatchOperation } from "../utils/sourcePatcher";
 import {
   DomEditPersistUnsafeValueError,
@@ -20,6 +28,7 @@ import { useDomEditTextCommits } from "./useDomEditTextCommits";
 import { useDomGeometryCommits } from "./useDomGeometryCommits";
 import { useElementLifecycleOps } from "./useElementLifecycleOps";
 import { formatFieldsSuffix } from "./gsapScriptCommitHelpers";
+import { readProjectFileContent } from "../utils/studioFileHistory";
 
 // ── Helpers ──
 
@@ -48,9 +57,87 @@ interface RecordEditInput {
   label: string;
   kind: EditHistoryKind;
   coalesceKey?: string;
+  coalesceMs?: number;
   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 matched subset already
+ * persisted, so this must NOT throw (a throw would roll back applied state) —
+ * warn and emit save-failure telemetry with a distinct reason instead.
+ */
+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} (their z-order 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",
+  });
+}
+
+async function patchElementBatch(projectId: string, batch: DomEditPatchBatch) {
+  const before = await readProjectFileContent(projectId, batch.sourceFile);
+  const response = await fetch(
+    `/api/projects/${encodeURIComponent(projectId)}/file-mutations/patch-elements-batch/${encodeURIComponent(batch.sourceFile)}`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ patches: batch.patches }),
+    },
+  );
+  if (!response.ok) {
+    const rejection = await readErrorResponseBody(response);
+    throw new StudioSaveHttpError(formatPatchRejectionMessage(rejection), response.status);
+  }
+  const result = (await response.json()) as {
+    changed?: boolean;
+    matched?: boolean[];
+    content?: string;
+  };
+  if (Array.isArray(result.matched)) reportUnmatchedBatchPatches(batch, result.matched);
+  return {
+    sourceFile: batch.sourceFile,
+    changed: result.changed === true,
+    // Skip-reload safety: the persist is only provably in sync with the live
+    // DOM when the server confirmed EVERY patch target matched. A missing /
+    // short matched[] is treated as unknown (false) so the caller falls back
+    // to reloading rather than silently diverging from disk.
+    allMatched:
+      Array.isArray(result.matched) &&
+      result.matched.length === batch.patches.length &&
+      result.matched.every(Boolean),
+    before,
+    after: typeof result.content === "string" ? result.content : before,
+  };
+}
+
+/**
+ * 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>;
@@ -271,6 +358,7 @@ export function useDomEditCommits({
         label: options?.label ?? "Edit layer",
         kind: "manual",
         coalesceKey: options?.coalesceKey,
+        coalesceMs: options?.coalesceMs,
         files: { [targetPath]: { before: originalContent, after: finalContent } },
       });
       forceReloadSdkSession?.();
@@ -292,6 +380,77 @@ export function useDomEditCommits({
     ],
   );
 
+  const commitDomEditPatchBatches: CommitDomEditPatchBatches = useCallback(
+    (batches, options) =>
+      queueDomEditSave(async () => {
+        const pid = projectIdRef.current;
+        if (!pid) throw new Error("No active project");
+        const unsafeFields = batches.flatMap((batch) =>
+          batch.patches.flatMap((patch) => findUnsafeDomPatchValues(patch)),
+        );
+        if (unsafeFields.length > 0) {
+          showToast("Couldn't save edit because it contains invalid layout values", "error");
+          throw new DomEditPersistUnsafeValueError(
+            `DOM patch contains unsafe values: ${formatUnsafeFieldList(unsafeFields)}`,
+            { alreadyToasted: true },
+          );
+        }
+
+        domEditSaveTimestampRef.current = Date.now();
+        const results = await Promise.all(batches.map((batch) => patchElementBatch(pid, batch)));
+        const files = Object.fromEntries(
+          results
+            .filter((result) => result.changed)
+            .map((result) => [result.sourceFile, { before: result.before, after: result.after }]),
+        );
+        if (Object.keys(files).length === 0) return;
+        await editHistory.recordEdit({
+          label: options.label,
+          kind: "manual",
+          coalesceKey: options.coalesceKey,
+          files,
+        });
+        forceReloadSdkSession?.();
+        // A z-only reorder already applied its inline styles to the live iframe
+        // DOM (and the store) synchronously, so remounting the iframe here only
+        // produces a visible blink. Skip the reload when the caller asked for it
+        // AND the persist is provably in sync: style-only ops, every target
+        // matched. Any unmatched patch means the live DOM now shows state disk
+        // doesn't hold — reload so the preview reconverges. (The SSE/file-watcher
+        // reload is independently suppressed by domEditSaveTimestampRef above.)
+        const skipSafe =
+          options.skipReload === true &&
+          batchesAreInlineStyleOnly(batches) &&
+          results.every((result) => result.allMatched);
+        if (!skipSafe) reloadPreview();
+      }).catch((error) => {
+        const alreadyToasted =
+          (error instanceof StudioSaveHttpError ||
+            error instanceof DomEditPersistUnsafeValueError) &&
+          error.alreadyToasted;
+        if (!alreadyToasted) {
+          showToast(error instanceof Error ? error.message : "Failed to reorder layers", "error");
+        }
+        trackStudioSaveFailure({
+          source: "dom_edit",
+          error,
+          filePath: batches.map((batch) => batch.sourceFile).join(","),
+          mutationType: "z-reorder",
+          label: options.label,
+        });
+        throw error;
+      }),
+    [
+      domEditSaveTimestampRef,
+      editHistory,
+      forceReloadSdkSession,
+      projectIdRef,
+      queueDomEditSave,
+      reloadPreview,
+      showToast,
+    ],
+  );
+
   // ── Text & style commits (delegated to useDomEditTextCommits) ──
 
   const {
@@ -352,7 +511,7 @@ export function useDomEditCommits({
     onTrySdkDelete,
     onReorderShadow,
     forceReloadSdkSession,
-    commitPositionPatchToHtml,
+    commitDomEditPatchBatches,
   });
 
   return {

package/src/hooks/useDomEditPositionPatchCommit.ts

@@ -15,6 +15,7 @@ interface UseDomEditPositionPatchCommitParams {
 interface PositionPatchOptions {
   label: string;
   coalesceKey: string;
+  coalesceMs?: number;
   skipRefresh?: boolean;
 }
 
@@ -30,6 +31,7 @@ export function useDomEditPositionPatchCommit({
         await persistDomEditOperations(selection, patches, {
           label: options.label,
           coalesceKey: options.coalesceKey,
+          coalesceMs: options.coalesceMs,
           skipRefresh: options.skipRefresh ?? true,
         });
       }).catch((error) => {

package/src/hooks/useDomEditSession.ts

@@ -1,6 +1,6 @@
 import { useCallback } from "react";
 import { trackStudioEvent } from "../utils/studioTelemetry";
-import type { TimelineElement } from "../player";
+import type { SelectElementOptions, TimelineElement } from "../player";
 import type { ImportedFontAsset } from "../components/editor/fontAssets";
 import type { EditHistoryKind } from "../utils/editHistory";
 import type { RightPanelTab } from "../utils/studioHelpers";
@@ -38,7 +38,7 @@ export interface UseDomEditSessionParams {
   compositionLoading: boolean;
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
   timelineElements: TimelineElement[];
-  setSelectedTimelineElementId: (id: string | null) => void;
+  setSelectedTimelineElementId: (id: string | null, options?: SelectElementOptions) => void;
   setRightCollapsed: (collapsed: boolean) => void;
   setRightPanelTab: (tab: RightPanelTab) => void;
   showToast: (message: string, tone?: "error" | "info") => void;

package/src/hooks/useDomEditTextCommits.test.tsx

@@ -0,0 +1,135 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection, DomEditTextField } from "../components/editor/domEditing";
+import { mountReactHarness } from "./domSelectionTestHarness";
+import { useDomEditTextCommits, type UseDomEditTextCommitsParams } from "./useDomEditTextCommits";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+interface Deferred<T> {
+  promise: Promise<T>;
+  resolve: (value: T | PromiseLike<T>) => void;
+  reject: (reason?: unknown) => void;
+}
+
+function createDeferred<T>(): Deferred<T> {
+  let resolve: Deferred<T>["resolve"] | undefined;
+  let reject: Deferred<T>["reject"] | undefined;
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  if (!resolve || !reject) throw new Error("deferred callbacks were not initialized");
+  return { promise, resolve, reject };
+}
+
+function textField(value: string): DomEditTextField {
+  return {
+    key: "self",
+    label: "Text",
+    value,
+    tagName: "div",
+    attributes: [],
+    inlineStyles: {},
+    computedStyles: {},
+    source: "self",
+  };
+}
+
+function selectionFor(element: HTMLElement): DomEditSelection {
+  return {
+    id: element.id,
+    element,
+    label: "Card",
+    tagName: "div",
+    sourceFile: "index.html",
+    compositionPath: "index.html",
+    isCompositionHost: false,
+    isInsideLockedComposition: false,
+    boundingBox: { x: 0, y: 0, width: 100, height: 100 },
+    textContent: element.textContent,
+    dataAttributes: {},
+    inlineStyles: {},
+    computedStyles: {},
+    textFields: [textField(element.textContent ?? "")],
+    capabilities: {
+      canSelect: true,
+      canEditStyles: true,
+      canCrop: true,
+      canMove: true,
+      canResize: true,
+      canApplyManualOffset: true,
+      canApplyManualSize: true,
+      canApplyManualRotation: true,
+    },
+  };
+}
+
+let cleanup: (() => void) | null = null;
+
+function renderTextCommitHook(params: UseDomEditTextCommitsParams) {
+  const captured: { hook: ReturnType<typeof useDomEditTextCommits> | null } = { hook: null };
+  function TextCommitProbe() {
+    captured.hook = useDomEditTextCommits(params);
+    return null;
+  }
+  const root = mountReactHarness(<TextCommitProbe />);
+  cleanup = () => act(() => root.unmount());
+  if (!captured.hook) throw new Error("hook did not initialize");
+  return captured.hook;
+}
+
+afterEach(() => {
+  cleanup?.();
+  cleanup = null;
+  document.body.replaceChildren();
+  vi.restoreAllMocks();
+});
+
+describe("useDomEditTextCommits", () => {
+  it("does not let a stale failed fields commit revert newer text", async () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const doc = iframe.contentDocument;
+    if (!doc) throw new Error("expected iframe document");
+    doc.body.innerHTML = '<div id="card">Original</div>';
+    const element = doc.getElementById("card");
+    const HTMLElementCtor = doc.defaultView?.HTMLElement;
+    if (!HTMLElementCtor || !(element instanceof HTMLElementCtor)) {
+      throw new Error("expected preview element");
+    }
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const selection = selectionFor(element);
+    const stalePersist = createDeferred<void>();
+    const persistDomEditOperations = vi
+      .fn()
+      .mockImplementationOnce(() => stalePersist.promise)
+      .mockResolvedValueOnce(undefined);
+    const hook = renderTextCommitHook({
+      activeCompPath: "index.html",
+      previewIframeRef: { current: iframe },
+      showToast: vi.fn(),
+      domEditSelection: selection,
+      applyDomSelection: vi.fn(),
+      refreshDomEditSelectionFromPreview: vi.fn(),
+      buildDomSelectionFromTarget: vi.fn(async () => null),
+      persistDomEditOperations,
+      resolveImportedFontAsset: () => null,
+    });
+
+    let staleCommit: Promise<void> | undefined;
+    act(() => {
+      staleCommit = hook.commitDomTextFields(selection, [textField("Stale")]);
+    });
+    await act(async () => {
+      await hook.commitDomTextFields(selection, [textField("Newest")]);
+    });
+    stalePersist.reject(new Error("stale request failed"));
+    await act(async () => {
+      await staleCommit;
+    });
+
+    expect(element.innerHTML).toBe("Newest");
+  });
+});