@agent-native/core 0.70.0 → 0.70.2

package/corpus/templates/content/app/components/editor/blockFieldSaveController.ts

@@ -0,0 +1,180 @@
+// Debounced save controller for an ADDITIONAL Blocks field's editor.
+//
+// Owns the only place that decides what is "saved" vs "dirty", so the rules are
+// testable without rendering the editor (which pulls in TipTap):
+//
+//  - A value is marked clean ONLY after the save promise RESOLVES. A failed save
+//    leaves the value dirty so it retries on the next edit or flush — it is never
+//    silently recorded as saved (review finding 6).
+//  - flush() persists the latest dirty content immediately, used on unmount /
+//    collapse so a debounce that has not fired yet is not dropped (finding 3).
+//  - mark() adopts fresh server content as the new confirmed baseline (e.g. an
+//    agent edit) without scheduling a save.
+//
+// SINGLE-FLIGHT + TRAILING (lost-update fix): the server write (set-document-
+// property → upsert) is unconditional, so the LAST request to reach the DB wins.
+// A monotonic sequence only protects local bookkeeping; it cannot reorder two
+// requests already in flight. So we guarantee server write order == issue order
+// by never having two saves in flight at once:
+//
+//   - At most ONE save() call is outstanding per field.
+//   - While a save is in flight, further edits do not start a new save; they
+//     coalesce into a single `pending` payload.
+//   - When the in-flight save settles, if `pending` still differs from the last
+//     confirmed value, exactly one trailing save is issued for the LATEST
+//     pending content. This repeats (one at a time) until quiescent.
+//   - flush() awaits the in-flight save (if any) and then sends the final
+//     pending content, so the last value committed at the DB is deterministically
+//     the latest content the user typed.
+
+export interface BlockFieldSaveController {
+  /** Record a user edit. Schedules a debounced save when the value is dirty. */
+  change(content: string): void;
+  /**
+   * Persist the latest dirty content now (unmount / collapse). Resolves after
+   * any in-flight save AND the resulting trailing save have settled, so the
+   * final DB value is the latest content.
+   */
+  flush(): Promise<void>;
+  /** Cancel any pending debounce without flushing. */
+  cancel(): void;
+  /** Adopt `content` as the confirmed-saved baseline (no save scheduled). */
+  mark(content: string): void;
+  /** The value last CONFIRMED persisted. */
+  readonly lastSaved: string;
+  /** The latest value the user has typed (may differ from lastSaved). */
+  readonly pending: string;
+  /** Whether a debounce timer is currently armed. */
+  readonly hasPendingTimer: boolean;
+  /** Whether a save() call is currently outstanding (in flight). */
+  readonly isSaving: boolean;
+  /**
+   * Whether this controller has CONFIRMED at least one local save (a save()
+   * resolved) since it was created. Once true, `lastSaved` is content this
+   * controller itself originated and persisted — so a server value that still
+   * differs from `lastSaved` is STALE (the server query hasn't refetched the
+   * just-saved value yet), not a genuinely newer external edit. Used by the
+   * remount seed/adopt path to avoid showing pre-save content. `mark()` (adopting
+   * fresh server content) clears it, since after a mark the baseline IS server.
+   */
+  readonly hasSavedLocally: boolean;
+}
+
+export function createBlockFieldSaveController(args: {
+  initialContent: string;
+  save: (content: string) => Promise<unknown>;
+  onError?: (error: unknown) => void;
+  debounceMs?: number;
+  setTimeoutFn?: typeof setTimeout;
+  clearTimeoutFn?: typeof clearTimeout;
+}): BlockFieldSaveController {
+  const debounceMs = args.debounceMs ?? 500;
+  const setTimeoutFn = args.setTimeoutFn ?? setTimeout;
+  const clearTimeoutFn = args.clearTimeoutFn ?? clearTimeout;
+
+  let lastSaved = args.initialContent;
+  let pending = args.initialContent;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  // Becomes true once a local save() resolves; cleared when mark() adopts a
+  // server value as the new baseline. See `hasSavedLocally` doc above.
+  let hasSavedLocally = false;
+
+  // The single in-flight save, or null when idle. Edits made while this is set
+  // do NOT start a new save; they update `pending` and a trailing save fires
+  // when this settles. This is what makes server write order == issue order.
+  let inFlight: Promise<void> | null = null;
+
+  function clearTimer() {
+    if (timer !== null) {
+      clearTimeoutFn(timer);
+      timer = null;
+    }
+  }
+
+  // Start exactly one save if one isn't already running and there is dirty
+  // content. When it settles SUCCESSFULLY, kick the next trailing save so the
+  // latest pending content always ends up as the final DB write — one at a time.
+  function kick() {
+    if (inFlight !== null) return; // single-flight: never overlap saves.
+    if (pending === lastSaved) return; // nothing dirty to persist.
+
+    const attempted = pending;
+    const promise = Promise.resolve(args.save(attempted))
+      .then(() => {
+        // Mark clean ONLY after the save actually succeeds.
+        lastSaved = attempted;
+        hasSavedLocally = true;
+        inFlight = null;
+        // A trailing edit may have landed while this save was in flight. Issue
+        // exactly one more save for the LATEST pending content. Bounded: stops
+        // once pending === lastSaved.
+        kick();
+      })
+      .catch((error) => {
+        // A failed save never records its value as clean, so the content stays
+        // dirty (finding 6) and retries on the NEXT change() or flush() — we do
+        // NOT auto-retry here, to avoid a tight retry storm against a failing
+        // backend.
+        inFlight = null;
+        args.onError?.(error);
+      });
+
+    inFlight = promise;
+  }
+
+  return {
+    change(content: string) {
+      pending = content;
+      clearTimer();
+      if (content === lastSaved) return;
+      timer = setTimeoutFn(() => {
+        timer = null;
+        kick();
+      }, debounceMs);
+    },
+    async flush() {
+      clearTimer();
+      // 1) Wait out any in-flight save so we never overlap with it (single-
+      //    flight) and so its successful trailing kick has fired.
+      while (inFlight !== null) {
+        await inFlight;
+      }
+      // 2) If the latest content still isn't persisted (a trailing edit, or the
+      //    in-flight save failed), send exactly one final save for the LATEST
+      //    pending content and await it. This is what makes the last value at the
+      //    DB deterministically the latest content. We do NOT loop on repeated
+      //    failure — flush is best-effort; a failed save stays dirty for the next
+      //    edit/flush.
+      if (pending !== lastSaved) {
+        kick();
+        if (inFlight !== null) await inFlight;
+      }
+    },
+    cancel() {
+      clearTimer();
+    },
+    mark(content: string) {
+      clearTimer();
+      lastSaved = content;
+      pending = content;
+      // The baseline is now server-provided content, not a local save the server
+      // hasn't echoed — so server props are no longer "behind" this controller.
+      hasSavedLocally = false;
+    },
+    get lastSaved() {
+      return lastSaved;
+    },
+    get pending() {
+      return pending;
+    },
+    get hasPendingTimer() {
+      return timer !== null;
+    },
+    get isSaving() {
+      return inFlight !== null;
+    },
+    get hasSavedLocally() {
+      return hasSavedLocally;
+    },
+  };
+}

package/corpus/templates/content/app/components/editor/blockFieldSaveRegistry.ts

@@ -0,0 +1,179 @@
+// Module-level registry of ONE shared save controller per Blocks-field key.
+//
+// PROBLEM (cross-instance write inversion — what the per-key lane could NOT fix):
+//   A non-primary Blocks field saves through a debounced controller, and one
+//   controller was created PER `AdditionalBlockEditor` mount. The editor unmounts
+//   on collapse and remounts on reopen under the SAME `documentId:propertyId`
+//   key. Across that collapse→reopen, two controller instances for the same key
+//   can exist briefly: the OLD instance's unmount-flush is still settling while a
+//   NEW instance accepts a newer edit. Each controller has its OWN pending and
+//   in-flight state, so they cannot see each other's recency.
+//
+//   The per-key serialization lane only ordered saves by ENQUEUE order. With two
+//   independent controllers the enqueue interleaving can be
+//   oldA → newC → oldB (the old controller issues a trailing save AFTER the new
+//   controller's edit), so a STALE value lands last and the user's newest edit is
+//   lost. Enqueue order can't capture content-recency across two controllers.
+//
+// FIX (one shared controller per key, ref-counted):
+//   There is exactly ONE controller instance per `documentId:propertyId` key, so
+//   there is exactly ONE `pending` value, ONE in-flight save, and a single
+//   single-flight + trailing pipeline for the field — regardless of how many
+//   editor instances mount/unmount/collapse/reopen. "Newest-wins WITHIN one
+//   controller" (already guaranteed by the controller) now applies across ALL
+//   instances, because there is only ever the one controller. An older save can
+//   never overwrite a newer one for the same field.
+//
+//   - acquire(key, factory): returns the SAME controller for a key, creating it
+//     once (via `factory`) and bumping a ref-count. Concurrent editor instances
+//     for the same key share it.
+//   - release(key): decrements the ref-count. When it reaches 0 we do NOT evict
+//     immediately: we flush-then-evict. The final flush still lands, and a quick
+//     reopen BEFORE the flush settles re-acquires the SAME instance (ref-count
+//     goes back above 0, eviction is cancelled) — so there is never a competing
+//     second controller for the key.
+//
+// This subsumes the lane for cross-instance ordering: with a single controller
+// per key, the lane has nothing left to serialize. The lane is therefore removed
+// (see git history) to avoid two mechanisms that could disagree.
+
+import type { BlockFieldSaveController } from "./blockFieldSaveController";
+
+interface Entry {
+  controller: BlockFieldSaveController;
+  refCount: number;
+  // Set while a flush-then-evict is pending after refCount hit 0. If a reopen
+  // re-acquires before the flush settles, we clear this so the entry is NOT
+  // evicted out from under the live instance.
+  evicting: boolean;
+}
+
+const registry = new Map<string, Entry>();
+
+/**
+ * Acquire the shared controller for `key`, creating it once via `factory`.
+ * Increments the ref-count and cancels any in-progress eviction so a reopen
+ * reuses the live instance rather than racing a fresh one.
+ */
+export function acquireBlockFieldSaveController(
+  key: string,
+  factory: () => BlockFieldSaveController,
+): BlockFieldSaveController {
+  const entry = ensureEntry(key, factory);
+  entry.refCount += 1;
+  // A reopen before a pending eviction settled: keep the instance alive.
+  entry.evicting = false;
+  return entry.controller;
+}
+
+/**
+ * Return the EXISTING shared controller for `key`, or undefined if none is
+ * registered yet. Does NOT create an entry and does NOT change the ref-count.
+ *
+ * Used during render to seed a remount's displayed content from the live
+ * controller's latest pending value. If no controller exists yet there is no
+ * pending content to recover, so the caller falls back to the server value —
+ * which is correct. Crucially, peeking never creates an unreferenced entry, so a
+ * render that is discarded before commit (concurrent/StrictMode) leaks nothing;
+ * the lasting entry is only created by the formal acquire in the mount effect.
+ */
+export function peekBlockFieldSaveController(
+  key: string,
+): BlockFieldSaveController | undefined {
+  return registry.get(key)?.controller;
+}
+
+function ensureEntry(
+  key: string,
+  factory: () => BlockFieldSaveController,
+): Entry {
+  let entry = registry.get(key);
+  if (!entry) {
+    entry = { controller: factory(), refCount: 0, evicting: false };
+    registry.set(key, entry);
+  }
+  return entry;
+}
+
+function controllerIsDirty(controller: BlockFieldSaveController): boolean {
+  return controller.pending !== controller.lastSaved;
+}
+
+/**
+ * Release one reference to the controller for `key`. When the last reference is
+ * released we flush-then-evict: flush the latest dirty content so a debounce
+ * that hadn't fired is not dropped, then remove the entry ONLY if it is still
+ * unreferenced after the flush settles (a reopen during the flush re-acquires
+ * the same instance and cancels the eviction).
+ */
+export function releaseBlockFieldSaveController(key: string): void {
+  const entry = registry.get(key);
+  if (!entry) return;
+  entry.refCount -= 1;
+  if (entry.refCount > 0) return;
+
+  // Last reference gone: flush the final pending content, then evict once it
+  // has fully settled — but only if nobody re-acquired in the meantime.
+  entry.evicting = true;
+  const settle = () => {
+    const current = registry.get(key);
+    // Evict only if it is the SAME entry, still unreferenced, and still marked
+    // for eviction (a reopen would have flipped `evicting` off / refCount up).
+    if (current === entry && current.refCount === 0 && current.evicting) {
+      if (controllerIsDirty(current.controller)) {
+        current.evicting = false;
+        return;
+      }
+      registry.delete(key);
+      // Drop the per-key save-impl ref alongside the controller. It is only
+      // cleared on test reset otherwise, so without this it accumulates one
+      // entry per key for the lifetime of the page. A subsequent re-acquire of
+      // the same key recreates a fresh impl ref via blockFieldSaveImplRef (the
+      // hook writes its current impl every render before the acquire effect), so
+      // there is no stale closure. Only delete here — never while refCount > 0
+      // or a reopen is pending — because the live factory closes over this ref.
+      saveImpls.delete(key);
+    }
+  };
+  // flush() resolves after any in-flight save AND the trailing save have
+  // settled, so the final DB value is the latest content before we drop state.
+  Promise.resolve(entry.controller.flush()).then(settle, settle);
+}
+
+// The shared controller for a key is created ONCE, but each editor mount carries
+// its own `save` implementation (a fresh `useSetDocumentProperty(...).mutateAsync`
+// closure per render). To keep one controller while still calling the freshest
+// impl, the controller's `save` reads through a per-key impl ref that every mount
+// updates on acquire. The save TARGET (documentId:propertyId) is fixed by the key,
+// so this only swaps the function identity, never the field it writes to.
+type SaveImpl = (value: string) => Promise<unknown>;
+const saveImpls = new Map<string, { current: SaveImpl }>();
+
+/**
+ * The mutable save-impl ref for `key`, created on first use. The shared
+ * controller's factory closes over this ref; each mount writes its latest impl.
+ */
+export function blockFieldSaveImplRef(key: string): { current: SaveImpl } {
+  let ref = saveImpls.get(key);
+  if (!ref) {
+    ref = {
+      current: () =>
+        Promise.reject(
+          new Error(`No save impl registered for block field "${key}"`),
+        ),
+    };
+    saveImpls.set(key, ref);
+  }
+  return ref;
+}
+
+/** Test-only: how many controllers the registry currently holds. */
+export function activeControllerCount(): number {
+  return registry.size;
+}
+
+/** Test-only: reset the registry between tests. */
+export function __resetBlockFieldSaveRegistry(): void {
+  registry.clear();
+  saveImpls.clear();
+}

package/corpus/templates/content/app/components/editor/previewDocumentSaveController.ts

@@ -0,0 +1,244 @@
+// Debounced save controller for the row PEEK's primary "Content" body (and its
+// title), which — unlike the full-page editor — does NOT use Yjs collab and so
+// persists through a plain debounced `update-document` write.
+//
+// WHY THIS EXISTS (data-loss fix): the peek used a bare `setTimeout` whose
+// pending value lived only inside the timer closure. Every lifecycle transition
+// that could happen before the ~450ms debounce fired — switching to another row,
+// the peek editor unmounting, or the sheet closing / "Open page" navigating —
+// CLEARED that timer instead of FLUSHING it, so the latest primary-body edit was
+// dropped. The additional (non-primary) Blocks fields already flush-on-release
+// via blockFieldSaveController; this controller gives the primary path the SAME
+// durability, modeled directly on that controller:
+//
+//  - A payload is marked clean ONLY after its save promise RESOLVES. A failed
+//    save leaves it dirty so it retries on the next edit or flush — never
+//    silently recorded as saved.
+//  - flush() persists the latest dirty payload immediately (row-switch / unmount
+//    / close / Open-page), so a debounce that has not fired yet is not dropped.
+//  - mark() adopts fresh server content as the new confirmed baseline (e.g. an
+//    agent edit) without scheduling a save.
+//
+// ONE CONTROLLER PER DOCUMENT ID (race-class elimination): this controller is
+// bound to a SINGLE `documentId` for its entire life and NEVER retargets. The
+// peek services many rows over its lifetime by acquiring a per-doc controller
+// from `previewDocumentSaveRegistry` and releasing it on row-switch — exactly
+// like the additional Blocks fields, which mount/unmount per (document, field)
+// and never rebase a live controller's target. Two prior bugs came from the old
+// single-controller-with-rebased-target design and are now STRUCTURALLY
+// impossible:
+//
+//   1. Lane queue-jump (the per-doc serialization lane's `running`/`tail`
+//      microtask gap). Gone: with a single-flight controller per doc id there is
+//      never more than one save in flight for the id, so there is nothing to
+//      serialize across — the lane is deleted entirely (no second mechanism).
+//   2. Stale completion after rebase. An OLD-row in-flight save that resolved
+//      AFTER a row-switch `mark()` used to overwrite the SHARED controller's
+//      `lastSaved` with the old payload and trigger a redundant save against the
+//      NEW row's baseline. Gone: each controller's `lastSaved`/`pending`/in-flight
+//      state belongs to ITS doc only; a stale completion can only ever advance
+//      ITS OWN baseline (correct), never another row's, because the controller's
+//      doc id is fixed at creation.
+//
+// SINGLE-FLIGHT + TRAILING (lost-update safety): the server write is
+// unconditional (last request to the DB wins). Because at most one save() per
+// controller is ever outstanding, server write order == issue order for the doc.
+// While a save is in flight, edits coalesce into one `pending` payload; when it
+// settles, exactly one trailing save fires for the LATEST payload if it differs.
+//
+// SYNCHRONOUS FINAL DISPATCH (async-flush-vs-sync-teardown race fix): call sites
+// invoke flush() fire-and-forget on row-switch / close / Open-page / unmount, so
+// the final write must be DISPATCHED (save() invoked) before the caller tears
+// down or navigates. flush() therefore issues the final save SYNCHRONOUSLY — it
+// does NOT await the in-flight save first. The save is bound to this controller's
+// fixed doc id, so it can never be retargeted; single-flight guarantees it does
+// not overlap a prior save for the id.
+
+export interface PreviewDocumentPayload {
+  title: string;
+  content: string;
+}
+
+export interface PreviewDocumentSaveController {
+  /** The document id this controller is permanently bound to. */
+  readonly documentId: string;
+  /** Record a title edit. Schedules a debounced save when dirty. */
+  changeTitle(title: string): void;
+  /** Record a content (primary body) edit. Schedules a debounced save when dirty. */
+  changeContent(content: string): void;
+  /**
+   * Persist the latest dirty payload now (row-switch / unmount / close /
+   * Open-page). The final save is DISPATCHED SYNCHRONOUSLY before this returns,
+   * bound to this controller's fixed document id — so a fire-and-forget caller
+   * can tear down / navigate immediately and the trailing edit still lands on the
+   * correct document. The returned promise resolves once that final save (and any
+   * in-flight save it waited behind) has settled.
+   */
+  flush(): Promise<void>;
+  /** Cancel any pending debounce without flushing. */
+  cancel(): void;
+  /** Adopt `payload` as the confirmed-saved baseline (no save scheduled). */
+  mark(payload: PreviewDocumentPayload): void;
+  /** The payload last CONFIRMED persisted. */
+  readonly lastSaved: PreviewDocumentPayload;
+  /** The latest payload the user has typed (may differ from lastSaved). */
+  readonly pending: PreviewDocumentPayload;
+  /** Whether a debounce timer is currently armed. */
+  readonly hasPendingTimer: boolean;
+  /** Whether a save() call is currently outstanding (in flight). */
+  readonly isSaving: boolean;
+  /**
+   * Whether this controller has confirmed at least one local save since creation.
+   * Until the server query echoes that payload, clean local state is newer than
+   * stale item/document props and must be preserved on quick preview reopens.
+   */
+  readonly hasSavedLocally: boolean;
+}
+
+function payloadsEqual(a: PreviewDocumentPayload, b: PreviewDocumentPayload) {
+  return a.title === b.title && a.content === b.content;
+}
+
+export function createPreviewDocumentSaveController(args: {
+  /**
+   * The document id this controller persists to, fixed for its entire life. A
+   * controller NEVER changes which document it targets — switching rows acquires
+   * a different controller (see previewDocumentSaveRegistry).
+   */
+  documentId: string;
+  initial: PreviewDocumentPayload;
+  /** Persist `payload` to this controller's document. */
+  save: (
+    documentId: string,
+    payload: PreviewDocumentPayload,
+  ) => Promise<unknown>;
+  onSaved?: (payload: PreviewDocumentPayload) => void;
+  onError?: (error: unknown) => void;
+  debounceMs?: number;
+  setTimeoutFn?: typeof setTimeout;
+  clearTimeoutFn?: typeof clearTimeout;
+}): PreviewDocumentSaveController {
+  const documentId = args.documentId;
+  const debounceMs = args.debounceMs ?? 450;
+  const setTimeoutFn = args.setTimeoutFn ?? setTimeout;
+  const clearTimeoutFn = args.clearTimeoutFn ?? clearTimeout;
+
+  let lastSaved: PreviewDocumentPayload = { ...args.initial };
+  let pending: PreviewDocumentPayload = { ...args.initial };
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let hasSavedLocally = false;
+
+  // The single in-flight save, or null when idle. A debounced edit made while
+  // this is set does NOT start a new save; it updates `pending` and a trailing
+  // save fires when this settles. At most one save per controller is ever
+  // outstanding, so server write order == issue order for this document id.
+  let inFlight: Promise<void> | null = null;
+
+  function clearTimer() {
+    if (timer !== null) {
+      clearTimeoutFn(timer);
+      timer = null;
+    }
+  }
+
+  // Start exactly one save if one isn't already running and there is dirty
+  // content. On SUCCESS the baseline advances to `attempted` (only what we
+  // actually persisted is ever marked clean) and the next trailing save is
+  // kicked. A failure leaves the payload dirty for the next edit/flush — it is
+  // never silently recorded as saved.
+  function kick() {
+    if (inFlight !== null) return; // single-flight: never overlap saves.
+    if (payloadsEqual(pending, lastSaved)) return; // nothing dirty.
+
+    const attempted = { ...pending };
+    const promise = Promise.resolve(args.save(documentId, attempted))
+      .then(() => {
+        lastSaved = attempted;
+        hasSavedLocally = true;
+        inFlight = null;
+        args.onSaved?.(attempted);
+        // A trailing edit may have landed while this save was in flight. Issue
+        // exactly one more for the LATEST payload. Bounded: stops once quiescent.
+        kick();
+      })
+      .catch((error) => {
+        inFlight = null;
+        args.onError?.(error);
+      });
+    inFlight = promise;
+  }
+
+  function schedule() {
+    clearTimer();
+    if (payloadsEqual(pending, lastSaved)) return;
+    timer = setTimeoutFn(() => {
+      timer = null;
+      kick();
+    }, debounceMs);
+  }
+
+  return {
+    documentId,
+    changeTitle(title: string) {
+      pending = { ...pending, title };
+      schedule();
+    },
+    changeContent(content: string) {
+      pending = { ...pending, content };
+      schedule();
+    },
+    flush() {
+      clearTimer();
+      // Nothing dirty: no-op, no double-save of clean content. If a save is
+      // still settling, return it so the caller can await full quiescence.
+      if (payloadsEqual(pending, lastSaved)) {
+        return inFlight ?? Promise.resolve();
+      }
+      // The latest payload still isn't persisted (a trailing edit, or a debounce
+      // that hasn't fired). Dispatch the final save SYNCHRONOUSLY — kick() issues
+      // it now if the lane is idle. Bound to this controller's fixed doc id, so a
+      // fire-and-forget caller can tear down immediately and the write still lands
+      // on the correct document. If a save IS already in flight, single-flight
+      // skips dispatch here and its success kicks the trailing save for the latest
+      // payload; we return a promise that resolves once that trailing save (the
+      // one carrying `pending`) has settled.
+      kick();
+      return waitUntilPersisted({ ...pending });
+    },
+    cancel() {
+      clearTimer();
+    },
+    mark(payload: PreviewDocumentPayload) {
+      clearTimer();
+      lastSaved = { ...payload };
+      pending = { ...payload };
+      hasSavedLocally = false;
+    },
+    get lastSaved() {
+      return { ...lastSaved };
+    },
+    get pending() {
+      return { ...pending };
+    },
+    get hasPendingTimer() {
+      return timer !== null;
+    },
+    get isSaving() {
+      return inFlight !== null;
+    },
+    get hasSavedLocally() {
+      return hasSavedLocally;
+    },
+  };
+
+  // Resolve once `target` has been confirmed persisted (or the controller went
+  // quiescent because a failed save left it dirty — flush is best-effort and does
+  // not loop on repeated failure). Chains strictly on the in-flight save promise,
+  // so it never busy-waits and always tracks the real settle of the trailing
+  // save that carries `target`.
+  function waitUntilPersisted(target: PreviewDocumentPayload): Promise<void> {
+    if (payloadsEqual(lastSaved, target)) return Promise.resolve();
+    if (inFlight === null) return Promise.resolve(); // quiescent (e.g. failed).
+    return inFlight.then(() => waitUntilPersisted(target));
+  }
+}