@hyperframes/studio 0.7.92 → 0.7.93

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

@@ -0,0 +1,215 @@
+// @vitest-environment happy-dom
+
+import React, { act, useRef, useState } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { TextAreaField } from "../components/editor/propertyPanelSections";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import type { LeftSidebarHandle } from "../components/sidebar/LeftSidebar";
+import { usePlayerStore } from "../player/store/playerStore";
+import { useAppHotkeys } from "./useAppHotkeys";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const timelineDelete = vi.fn(async () => undefined);
+const domDelete = vi.fn(async () => undefined);
+const keyframeDelete = vi.fn();
+const textCommits = vi.fn();
+let root: Root | null = null;
+
+function parentWithTextChild(): DomEditSelection {
+  const element = document.createElement("section");
+  element.id = "selected-card";
+  const child = document.createElement("span");
+  child.textContent = "Kicker";
+  element.append(child);
+  return {
+    element,
+    id: "selected-card",
+    selector: "#selected-card",
+    selectorIndex: 0,
+    label: "Selected card",
+    tagName: "section",
+    sourceFile: "index.html",
+    compositionPath: "index.html",
+    isCompositionHost: false,
+    isInsideLockedComposition: false,
+    boundingBox: { x: 0, y: 0, width: 320, height: 180 },
+    textContent: "Kicker",
+    dataAttributes: {},
+    inlineStyles: {},
+    computedStyles: {},
+    textFields: [
+      {
+        key: "child:0:span",
+        label: "Content",
+        value: "Kicker",
+        tagName: "span",
+        attributes: [],
+        inlineStyles: {},
+        computedStyles: {},
+        source: "child",
+        sourceChildIndex: 0,
+      },
+    ],
+    capabilities: {
+      canSelect: true,
+      canEditStyles: true,
+      canCrop: false,
+      canMove: true,
+      canResize: true,
+      canApplyManualOffset: true,
+      canApplyManualSize: true,
+      canApplyManualRotation: true,
+    },
+  };
+}
+
+function Harness() {
+  const [value, setValue] = useState("Kicker");
+  const [selectionRefreshed, setSelectionRefreshed] = useState(false);
+  const selectionRef = useRef<DomEditSelection | null>(parentWithTextChild());
+  const clearSelectionRef = useRef<() => void>(() => undefined);
+  const saveTimestampRef = useRef(0);
+  const leftSidebarRef = useRef<LeftSidebarHandle | null>(null);
+
+  useAppHotkeys({
+    handleTimelineElementDelete: timelineDelete,
+    handleTimelineElementSplit: vi.fn(async () => undefined),
+    handleDomEditElementDelete: domDelete,
+    domEditSelectionRef: selectionRef,
+    clearDomSelectionRef: clearSelectionRef,
+    editHistory: {
+      undo: vi.fn(async () => ({ ok: false })),
+      redo: vi.fn(async () => ({ ok: false })),
+      state: { undo: [], redo: [] },
+    },
+    readOptionalProjectFile: vi.fn(async () => ""),
+    readProjectFile: vi.fn(async () => ""),
+    writeProjectFile: vi.fn(async () => undefined),
+    domEditSaveTimestampRef: saveTimestampRef,
+    showToast: vi.fn(),
+    syncHistoryPreviewAfterApply: vi.fn(async () => undefined),
+    waitForPendingDomEditSaves: vi.fn(async () => undefined),
+    leftSidebarRef,
+    handleCopy: vi.fn(() => false),
+    handlePaste: vi.fn(async () => undefined),
+    handleCut: vi.fn(async () => false),
+    onResetKeyframes: vi.fn(() => false),
+    onDeleteSelectedKeyframes: keyframeDelete,
+  });
+
+  return (
+    <>
+      <TextAreaField
+        label="Content"
+        value={value}
+        onCommit={(next) => {
+          textCommits(next);
+          setValue(next);
+          // Text persistence rebuilds the selected parent's text-field model
+          // from the preview. Model that refresh: it must not transfer keyboard
+          // ownership away from the still-mounted Content editor.
+          setSelectionRefreshed(true);
+        }}
+      />
+      <button type="button" data-testid="canvas" data-selection-refreshed={selectionRefreshed}>
+        Canvas
+      </button>
+    </>
+  );
+}
+
+function setTextareaValue(textarea: HTMLTextAreaElement, value: string) {
+  const setter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, "value")?.set;
+  if (!setter) throw new Error("expected native textarea value setter");
+  setter.call(textarea, value);
+  textarea.dispatchEvent(new Event("input", { bubbles: true }));
+  textarea.setSelectionRange(value.length, value.length);
+}
+
+function pressBackspace(target: HTMLElement): KeyboardEvent {
+  const event = new KeyboardEvent("keydown", {
+    key: "Backspace",
+    bubbles: true,
+    cancelable: true,
+  });
+  target.dispatchEvent(event);
+  return event;
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  timelineDelete.mockClear();
+  domDelete.mockClear();
+  keyframeDelete.mockClear();
+  textCommits.mockClear();
+  usePlayerStore.getState().reset();
+  usePlayerStore.getState().setElements([
+    {
+      id: "selected-card",
+      tag: "section",
+      start: 0,
+      duration: 10,
+      track: 0,
+    },
+  ]);
+  usePlayerStore.getState().setSelectedElementId("selected-card");
+});
+
+afterEach(() => {
+  if (root) act(() => root?.unmount());
+  root = null;
+  document.body.innerHTML = "";
+  usePlayerStore.getState().reset();
+  vi.useRealTimers();
+});
+
+describe("useAppHotkeys text-field ownership", () => {
+  it("keeps two Backspaces in a child text editor across its scheduled save", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    root = createRoot(host);
+    act(() => root?.render(<Harness />));
+
+    const textarea = host.querySelector("textarea");
+    const canvas = host.querySelector<HTMLButtonElement>('[data-testid="canvas"]');
+    if (!textarea || !canvas) throw new Error("expected text editor and canvas target");
+
+    textarea.focus();
+    textarea.setSelectionRange(textarea.value.length, textarea.value.length);
+
+    const first = pressBackspace(textarea);
+    act(() => setTextareaValue(textarea, "Kicke"));
+    act(() => vi.advanceTimersByTime(120));
+
+    expect(first.defaultPrevented).toBe(false);
+    expect(textCommits).toHaveBeenLastCalledWith("Kicke");
+    expect(canvas.dataset.selectionRefreshed).toBe("true");
+    expect(document.activeElement).toBe(textarea);
+    expect(textarea.selectionStart).toBe(5);
+    expect(textarea.selectionEnd).toBe(5);
+
+    const second = pressBackspace(textarea);
+    act(() => setTextareaValue(textarea, "Kick"));
+    act(() => vi.advanceTimersByTime(120));
+
+    expect(second.defaultPrevented).toBe(false);
+    expect(textarea.value).toBe("Kick");
+    expect(textCommits.mock.calls).toEqual([["Kicke"], ["Kick"]]);
+    expect(document.activeElement).toBe(textarea);
+    expect(textarea.selectionStart).toBe(4);
+    expect(textarea.selectionEnd).toBe(4);
+    expect(timelineDelete).not.toHaveBeenCalled();
+    expect(domDelete).not.toHaveBeenCalled();
+    expect(keyframeDelete).not.toHaveBeenCalled();
+
+    canvas.focus();
+    const canvasDelete = pressBackspace(canvas);
+
+    expect(canvasDelete.defaultPrevented).toBe(true);
+    expect(timelineDelete).toHaveBeenCalledTimes(1);
+    expect(domDelete).not.toHaveBeenCalled();
+    expect(keyframeDelete).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useDomGeometryCommits.test.tsx

@@ -0,0 +1,61 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import {
+  applyStudioBoxSize,
+  applyStudioPathOffset,
+  applyStudioRotation,
+  readStudioBoxSize,
+  readStudioPathOffset,
+  readStudioRotation,
+} from "../components/editor/manualEdits";
+import { useDomGeometryCommits } from "./useDomGeometryCommits";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+describe("useDomGeometryCommits rollback", () => {
+  it("restores every optimistic geometry mutation when persistence rejects", async () => {
+    const element = document.createElement("div");
+    element.id = "box";
+    document.body.append(element);
+    applyStudioPathOffset(element, { x: 10, y: 20 });
+    applyStudioBoxSize(element, { width: 100, height: 80 });
+    applyStudioRotation(element, { angle: 15 });
+    const selection = {
+      id: "box",
+      selector: "#box",
+      element,
+    } as unknown as DomEditSelection;
+    const failure = new Error("save failed");
+    const commitPositionPatchToHtml = vi.fn().mockRejectedValue(failure);
+    let commits: ReturnType<typeof useDomGeometryCommits> | null = null;
+    const host = document.createElement("div");
+    const root = createRoot(host);
+
+    function Probe() {
+      commits = useDomGeometryCommits({
+        previewIframeRef: { current: null },
+        showToast: vi.fn(),
+        commitPositionPatchToHtml,
+      });
+      return null;
+    }
+
+    act(() => root.render(<Probe />));
+    await expect(commits!.handleDomPathOffsetCommit(selection, { x: 50, y: 60 })).rejects.toBe(
+      failure,
+    );
+    await expect(
+      commits!.handleDomBoxSizeCommit(selection, { width: 200, height: 160 }, { x: 30, y: 40 }),
+    ).rejects.toBe(failure);
+    await expect(commits!.handleDomRotationCommit(selection, { angle: 45 })).rejects.toBe(failure);
+
+    expect(readStudioPathOffset(element)).toEqual({ x: 10, y: 20 });
+    expect(readStudioBoxSize(element)).toEqual({ width: 100, height: 80 });
+    expect(readStudioRotation(element)).toEqual({ angle: 15 });
+    act(() => root.unmount());
+  });
+});

package/src/hooks/useDomGeometryCommits.ts

@@ -4,6 +4,12 @@ import {
   applyStudioPathOffset,
   applyStudioBoxSize,
   applyStudioRotation,
+  captureStudioPathOffset,
+  captureStudioBoxSize,
+  captureStudioRotation,
+  restoreStudioPathOffset,
+  restoreStudioBoxSize,
+  restoreStudioRotation,
   clearStudioPathOffset,
   clearStudioBoxSize,
   clearStudioRotation,
@@ -51,10 +57,14 @@ export function useDomGeometryCommits({
         showToast(error.message, "error");
         return Promise.reject(error);
       }
+      const before = captureStudioPathOffset(selection.element);
       applyStudioPathOffset(selection.element, next);
       return commitPositionPatchToHtml(selection, buildPathOffsetPatches(selection.element), {
         label: "Move layer",
         coalesceKey: `path-offset:${getDomEditTargetKey(selection)}`,
+      }).catch((error) => {
+        restoreStudioPathOffset(selection.element, before);
+        throw error;
       });
     },
     [commitPositionPatchToHtml, previewIframeRef, showToast],
@@ -71,6 +81,8 @@ export function useDomGeometryCommits({
         showToast(error.message, "error");
         return Promise.reject(error);
       }
+      const beforeSize = captureStudioBoxSize(selection.element);
+      const beforeOffset = offset ? captureStudioPathOffset(selection.element) : null;
       applyStudioBoxSize(selection.element, next);
       // Anchored-corner resize (NW/NE/SW) also moves the element to keep the
       // opposite corner fixed. Apply the offset and emit BOTH patch sets in a
@@ -86,6 +98,10 @@ export function useDomGeometryCommits({
       return commitPositionPatchToHtml(selection, patches, {
         label: "Resize layer box",
         coalesceKey: `box-size:${getDomEditTargetKey(selection)}`,
+      }).catch((error) => {
+        restoreStudioBoxSize(selection.element, beforeSize);
+        if (beforeOffset) restoreStudioPathOffset(selection.element, beforeOffset);
+        throw error;
       });
     },
     [commitPositionPatchToHtml, previewIframeRef, showToast],
@@ -98,10 +114,14 @@ export function useDomGeometryCommits({
         showToast(error.message, "error");
         return Promise.reject(error);
       }
+      const before = captureStudioRotation(selection.element);
       applyStudioRotation(selection.element, next);
       return commitPositionPatchToHtml(selection, buildRotationPatches(selection.element), {
         label: "Rotate layer",
         coalesceKey: `rotation:${getDomEditTargetKey(selection)}`,
+      }).catch((error) => {
+        restoreStudioRotation(selection.element, before);
+        throw error;
       });
     },
     [commitPositionPatchToHtml, previewIframeRef, showToast],

package/src/hooks/useEditorSave.test.tsx

@@ -0,0 +1,131 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useEditorSave, type EditorSaveHandle } from "./useEditorSave";
+import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+type WriteProjectFile = (path: string, content: string, expectedContent?: string) => Promise<void>;
+
+async function mountEditorSave(writeProjectFile: WriteProjectFile) {
+  const captured: { handle: EditorSaveHandle | null } = { handle: null };
+
+  function Probe() {
+    captured.handle = useEditorSave({
+      editingPathRef: { current: "index.html" },
+      projectIdRef: { current: "project-a" },
+      readProjectFile: vi.fn(async () => "before"),
+      writeProjectFile,
+      recordEdit: vi.fn(async () => undefined),
+      domEditSaveTimestampRef: { current: 0 },
+      setRefreshKey: vi.fn(),
+      showToast: vi.fn(),
+    });
+    return null;
+  }
+
+  const root = createRoot(document.createElement("div"));
+  await act(async () => root.render(<Probe />));
+  if (!captured.handle) throw new Error("Editor save handle was not mounted");
+
+  return {
+    handle: captured.handle,
+    unmount: () => act(async () => root.unmount()),
+  };
+}
+
+describe("useEditorSave pending work", () => {
+  beforeEach(() => {
+    vi.stubGlobal(
+      "requestAnimationFrame",
+      vi.fn(() => 41),
+    );
+    vi.stubGlobal("cancelAnimationFrame", vi.fn());
+  });
+
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("exposes and flushes the latest rAF-buffered source candidate", async () => {
+    const writeProjectFile = vi.fn(async () => undefined);
+    const mounted = await mountEditorSave(writeProjectFile);
+    act(() => mounted.handle.handleContentChange("studio candidate"));
+
+    expect(mounted.handle.getPendingCandidate()).toEqual({
+      projectId: "project-a",
+      path: "index.html",
+      content: "studio candidate",
+    });
+    await expect(mounted.handle.flushPendingSave()).resolves.toEqual({ status: "clean" });
+    expect(writeProjectFile).toHaveBeenCalledWith("index.html", "studio candidate", "before");
+
+    await mounted.unmount();
+  });
+
+  it("joins an in-flight source save instead of writing the frozen candidate twice", async () => {
+    let frame: FrameRequestCallback | null = null;
+    vi.stubGlobal(
+      "requestAnimationFrame",
+      vi.fn((callback: FrameRequestCallback) => {
+        frame = callback;
+        return 42;
+      }),
+    );
+    let finishWrite!: () => void;
+    const writeProjectFile = vi
+      .fn()
+      .mockImplementationOnce(
+        () =>
+          new Promise<void>((resolve) => {
+            finishWrite = resolve;
+          }),
+      )
+      .mockResolvedValue(undefined);
+    const mounted = await mountEditorSave(writeProjectFile);
+    act(() => mounted.handle.handleContentChange("candidate"));
+    act(() => frame?.(0));
+    await vi.waitFor(() => expect(writeProjectFile).toHaveBeenCalledOnce());
+
+    const drained = mounted.handle.flushPendingSave();
+    expect(writeProjectFile).toHaveBeenCalledOnce();
+    finishWrite();
+    await expect(drained).resolves.toEqual({ status: "clean" });
+    expect(writeProjectFile).toHaveBeenCalledOnce();
+    await mounted.unmount();
+  });
+
+  it("preserves conflict details when flushing a buffered source candidate", async () => {
+    const conflict = new StudioFileConflictError({
+      filePath: "index.html",
+      currentVersion: "external-v2",
+      currentContent: "external",
+      attemptedContent: "studio candidate",
+    });
+    const mounted = await mountEditorSave(async () => {
+      throw conflict;
+    });
+    act(() => mounted.handle.handleContentChange("studio candidate"));
+
+    await expect(mounted.handle.flushPendingSave()).resolves.toEqual({
+      status: "conflict",
+      error: conflict,
+    });
+
+    await mounted.unmount();
+  });
+
+  it("discards an rAF-buffered candidate without persisting it", async () => {
+    const writeProjectFile = vi.fn(async () => undefined);
+    const mounted = await mountEditorSave(writeProjectFile);
+    act(() => mounted.handle.handleContentChange("discard me"));
+    act(() => mounted.handle.discardPendingSave());
+
+    expect(mounted.handle.getPendingCandidate()).toBeNull();
+    await expect(mounted.handle.flushPendingSave()).resolves.toEqual({ status: "clean" });
+    expect(writeProjectFile).not.toHaveBeenCalled();
+    expect(cancelAnimationFrame).toHaveBeenCalledWith(41);
+
+    await mounted.unmount();
+  });
+});

package/src/hooks/useEditorSave.ts

@@ -2,6 +2,10 @@ import { useCallback, useRef } from "react";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
 import type { EditHistoryKind } from "../utils/editHistory";
 import { trackStudioEvent } from "../utils/studioTelemetry";
+import {
+  StudioFileConflictError,
+  type StudioSaveDrainResult,
+} from "../utils/studioSaveDiagnostics";
 
 interface RecordEditInput {
   label: string;
@@ -21,6 +25,25 @@ interface UseEditorSaveOptions {
   showToast: (message: string, tone?: "error" | "info") => void;
 }
 
+export interface EditorSaveCandidate {
+  projectId: string;
+  path: string;
+  content: string;
+}
+
+export type EditorSaveDrainResult = StudioSaveDrainResult;
+
+export interface EditorSaveHandle {
+  saveRafRef: React.MutableRefObject<number | null>;
+  handleContentChange: (content: string) => void;
+  /** Read by the external-reload reconciliation introduced in stack PR #2993. */
+  getPendingCandidate: () => EditorSaveCandidate | null;
+  /** Wired into the external-reload drain by stack PR #2993. */
+  flushPendingSave: () => Promise<EditorSaveDrainResult>;
+  /** Used by PR #2993 when the external version wins. */
+  discardPendingSave: () => void;
+}
+
 export function useEditorSave({
   editingPathRef,
   projectIdRef,
@@ -30,12 +53,70 @@ export function useEditorSave({
   domEditSaveTimestampRef,
   setRefreshKey,
   showToast,
-}: UseEditorSaveOptions) {
+}: UseEditorSaveOptions): EditorSaveHandle {
   const saveRafRef = useRef<number | null>(null);
   const refreshRafRef = useRef<number | null>(null);
   // One error toast per burst of failures — every keystroke retries the save,
   // and error toasts persist until dismissed, so don't stack duplicates.
   const lastFailureToastAtRef = useRef(0);
+  const pendingCandidateRef = useRef<EditorSaveCandidate | null>(null);
+  const inFlightRef = useRef<Promise<EditorSaveDrainResult> | null>(null);
+  const inFlightCandidateRef = useRef<EditorSaveCandidate | null>(null);
+
+  const reportFailure = useCallback(
+    (path: string, error: unknown) => {
+      trackStudioEvent("save_failure", {
+        source: "code_editor",
+        error_message: error instanceof Error ? error.message : "unknown",
+      });
+      const now = Date.now();
+      if (now - lastFailureToastAtRef.current > 5000) {
+        lastFailureToastAtRef.current = now;
+        showToast(
+          `Couldn't save ${path} — your latest edits are NOT persisted. Check the preview server; editing again retries the save.`,
+          "error",
+        );
+      }
+    },
+    [showToast],
+  );
+
+  const persistCandidate = useCallback(
+    (candidate: EditorSaveCandidate): Promise<EditorSaveDrainResult> => {
+      const task = saveProjectFilesWithHistory({
+        projectId: candidate.projectId,
+        label: "Edit source",
+        kind: "source",
+        coalesceKey: `source:${candidate.path}`,
+        files: { [candidate.path]: candidate.content },
+        readFile: readProjectFile,
+        writeFile: writeProjectFile,
+        recordEdit,
+      })
+        .then<EditorSaveDrainResult>(() => {
+          if (pendingCandidateRef.current === candidate) pendingCandidateRef.current = null;
+          if (refreshRafRef.current != null) cancelAnimationFrame(refreshRafRef.current);
+          refreshRafRef.current = requestAnimationFrame(() => setRefreshKey((k) => k + 1));
+          return { status: "clean" };
+        })
+        .catch<EditorSaveDrainResult>((error: unknown) => {
+          reportFailure(candidate.path, error);
+          return error instanceof StudioFileConflictError
+            ? { status: "conflict", error }
+            : { status: "failed", error };
+        })
+        .finally(() => {
+          if (inFlightRef.current === task) {
+            inFlightRef.current = null;
+            inFlightCandidateRef.current = null;
+          }
+        });
+      inFlightRef.current = task;
+      inFlightCandidateRef.current = candidate;
+      return task;
+    },
+    [readProjectFile, recordEdit, reportFailure, setRefreshKey, writeProjectFile],
+  );
 
   const handleContentChange = useCallback(
     (content: string) => {
@@ -44,53 +125,46 @@ export function useEditorSave({
       const path = editingPathRef.current;
       if (!path) return;
 
+      const candidate = { projectId: pid, path, content };
+      pendingCandidateRef.current = candidate;
+
       if (saveRafRef.current != null) cancelAnimationFrame(saveRafRef.current);
       saveRafRef.current = requestAnimationFrame(() => {
+        saveRafRef.current = null;
         domEditSaveTimestampRef.current = Date.now();
-        saveProjectFilesWithHistory({
-          projectId: pid,
-          label: "Edit source",
-          kind: "source",
-          coalesceKey: `source:${path}`,
-          files: { [path]: content },
-          readFile: readProjectFile,
-          writeFile: writeProjectFile,
-          recordEdit,
-        })
-          .then(() => {
-            if (refreshRafRef.current != null) cancelAnimationFrame(refreshRafRef.current);
-            refreshRafRef.current = requestAnimationFrame(() => setRefreshKey((k) => k + 1));
-          })
-          .catch((error) => {
-            trackStudioEvent("save_failure", {
-              source: "code_editor",
-              error_message: error instanceof Error ? error.message : "unknown",
-            });
-            const now = Date.now();
-            if (now - lastFailureToastAtRef.current > 5000) {
-              lastFailureToastAtRef.current = now;
-              showToast(
-                `Couldn't save ${path} — your latest edits are NOT persisted. Check the preview server; editing again retries the save.`,
-                "error",
-              );
-            }
-          });
+        void persistCandidate(candidate);
       });
     },
-    [
-      domEditSaveTimestampRef,
-      editingPathRef,
-      projectIdRef,
-      readProjectFile,
-      recordEdit,
-      setRefreshKey,
-      showToast,
-      writeProjectFile,
-    ],
+    [domEditSaveTimestampRef, editingPathRef, projectIdRef, persistCandidate],
   );
 
+  const flushPendingSave = useCallback(async (): Promise<EditorSaveDrainResult> => {
+    if (saveRafRef.current != null) {
+      cancelAnimationFrame(saveRafRef.current);
+      saveRafRef.current = null;
+    }
+    const candidate = pendingCandidateRef.current;
+    if (candidate && candidate === inFlightCandidateRef.current && inFlightRef.current) {
+      return inFlightRef.current;
+    }
+    if (candidate) {
+      domEditSaveTimestampRef.current = Date.now();
+      return persistCandidate(candidate);
+    }
+    return (await inFlightRef.current) ?? { status: "clean" };
+  }, [domEditSaveTimestampRef, persistCandidate]);
+
+  const discardPendingSave = useCallback(() => {
+    if (saveRafRef.current != null) cancelAnimationFrame(saveRafRef.current);
+    saveRafRef.current = null;
+    pendingCandidateRef.current = null;
+  }, []);
+
   return {
     saveRafRef,
     handleContentChange,
+    getPendingCandidate: () => pendingCandidateRef.current,
+    flushPendingSave,
+    discardPendingSave,
   };
 }