@brass-build/client 0.1.0 → 0.3.0

package/src/version-bar.ts

@@ -9,13 +9,23 @@
 // grow with no SDK or app change.
 //
 // Bridge protocol (shared envelope `__brass_embed: 1`):
-//   host -> iframe:  init{surface,params} | version-changed{version}
-//   iframe -> host:  ready | resize{height} | preview{version}
-//                    | return-to-head | fork{fromVersion} | browse
+//   host -> iframe:  init{surface,params}
+//                    | version-changed{version, requestId?, ok?}
+//   iframe -> host:  ready | resize{height} | preview{version, requestId?}
+//                    | return-to-head{requestId?} | fork{fromVersion} | browse
 //                    | error{code,message}
+//
+// A navigating intent (`preview` / `return-to-head`) is CONFIRMED: the host
+// awaits the document method it routes to and answers with the version the
+// document actually shows afterwards, plus whether the intent was accepted.
+// The bar moves optimistically on the click, so without that answer a refused
+// checkout (a document pinned to a version, a materialise that failed) leaves
+// it naming a version nothing is showing, and nothing later corrects it: the
+// host's own re-render is driven by the session, which does not notify on a
+// preview -> preview step.
+
+import { EMBED_ENVELOPE, EMBED_PROTOCOL_VERSION } from './embed-protocol.js';
 
-const ENVELOPE = '__brass_embed';
-const PROTOCOL_VERSION = 1;
 // Collapsed until the embed reports `ready`, so the load moment shows a
 // themed placeholder strip rather than an empty white iframe (no flash, no
 // layout jump: the placeholder reserves the strip's height).
@@ -29,14 +39,17 @@ export interface VersionBarDeps {
   dashboardBaseUrl: string;
   // Pins the embed's light/dark theme (matches the other hosted surfaces).
   theme?: 'light' | 'dark' | 'auto';
-  // The fallback platform-session pointer, handed to the embed so it can
-  // authenticate when its framed cookie is blocked (incognito / Safari ITP).
-  getSessionToken?: () => string | null | undefined;
-  // Intents from the embed, routed to the live active document.
-  checkoutVersion: (version: number) => void;
-  returnToHead: () => void;
+  // Intents from the embed, routed to the live active document. The two
+  // navigating ones settle (a rejection is a refused intent, which the frame
+  // reports back rather than swallowing).
+  checkoutVersion: (version: number) => Promise<void>;
+  returnToHead: () => Promise<void>;
   fork: (fromVersion: number, name?: string) => void;
   browse: () => void;
+  // The version the active document shows right now (`null` at the live
+  // head). Read after an intent settles, so the answer describes the
+  // document rather than the request.
+  currentVersion: () => number | null;
   // Dismiss the bar. The bar stays open through the whole browsing session
   // (including once returned to the live head), so it is closed only by the
   // user's explicit "Close", never as a side effect of navigation.
@@ -52,6 +65,10 @@ export interface VersionBarContext {
   // The active branch's display name when on a non-default branch, else
   // undefined. The bar composes a branch-from-version's initial name from it.
   branchName?: string | undefined;
+  // True when the document is pinned to this version and has no live channel
+  // (a cold open at a version). Stepping and returning to the head are both
+  // refused on that shape, so the bar offers neither.
+  pinned?: boolean;
 }
 
 export interface VersionBarFrame {
@@ -67,6 +84,10 @@ function clampHeight(h: number): number {
   return Math.max(MIN_HEIGHT, Math.min(MAX_HEIGHT, Math.round(h)));
 }
 
+// How long the embed has to say it is ready before the SDK-drawn fallback
+// takes the strip. Matches the hosted-UI launcher's own long window.
+const VERSION_BAR_READY_TIMEOUT_MS = 10_000;
+
 export function createVersionBarFrame(
   root: HTMLElement,
   deps: VersionBarDeps,
@@ -81,6 +102,37 @@ export function createVersionBarFrame(
   placeholder.className = 'b-version-loading';
   placeholder.textContent = 'Loading version controls...';
 
+  // Shown when the embed reports it cannot render (not signed in in this
+  // framing context, an account mismatch). The bar is the only surface that
+  // returns a document to its live head, so collapsing the strip on that
+  // failure would leave the reader in a read-only preview with nothing to
+  // leave it by; this carries the two controls that need no timeline.
+  const fallback = document.createElement('div');
+  fallback.className = 'b-version-fallback';
+  fallback.hidden = true;
+  const fallbackText = document.createElement('span');
+  fallbackText.className = 'b-version-fallback-msg';
+  const fallbackHead = document.createElement('button');
+  fallbackHead.type = 'button';
+  fallbackHead.textContent = 'Return to latest';
+  fallbackHead.onclick = () => {
+    void deps.returnToHead().catch(() => {});
+  };
+  const fallbackClose = document.createElement('button');
+  fallbackClose.type = 'button';
+  fallbackClose.textContent = 'Close';
+  fallbackClose.onclick = () => deps.close();
+  fallback.append(fallbackText, fallbackHead, fallbackClose);
+
+  function renderFallback(): void {
+    const pinned = ctx?.pinned === true;
+    const previewing = deps.currentVersion() !== null;
+    fallbackText.textContent = previewing
+      ? 'Viewing an earlier version'
+      : 'Latest version';
+    fallbackHead.hidden = !previewing || pinned;
+  }
+
   const iframe = document.createElement('iframe');
   const url = new URL(`${base}/embed/version-bar`);
   url.searchParams.set('theme', theme);
@@ -95,10 +147,46 @@ export function createVersionBarFrame(
     background: 'transparent',
   } satisfies Partial<CSSStyleDeclaration>);
 
-  root.append(placeholder, iframe);
+  root.append(placeholder, fallback, iframe);
 
   let ctx: VersionBarContext | null = null;
   let ready = false;
+  // Set once the embed reports it cannot render, so the fallback strip owns
+  // the surface and a later `update` does not restore the dead iframe.
+  let failed = false;
+  let destroyed = false;
+  // Armed whenever the iframe is pointed at the embed. Returning a document to
+  // its live head is this bar's exclusive capability, so an embed that never
+  // loads at all (a host CSP that refuses the frame, an offline reader, a
+  // blocking extension) would otherwise leave the placeholder up forever and
+  // the reader in a read-only preview with no control to leave it by. The
+  // `error` message covers an embed that loaded and refused; nothing covers
+  // one that never answers, which is why this is a timer rather than a
+  // handler.
+  let readyTimer: ReturnType<typeof setTimeout> | undefined;
+
+  // Hand the strip to the SDK-drawn fallback, which carries the two controls
+  // that need no timeline (return to latest, close).
+  function enterFallback(): void {
+    if (destroyed || failed) return;
+    failed = true;
+    if (readyTimer !== undefined) {
+      clearTimeout(readyTimer);
+      readyTimer = undefined;
+    }
+    placeholder.style.display = 'none';
+    iframe.style.height = '0';
+    fallback.hidden = false;
+    renderFallback();
+  }
+
+  function armReadyTimer(): void {
+    if (readyTimer !== undefined) clearTimeout(readyTimer);
+    readyTimer = setTimeout(() => {
+      readyTimer = undefined;
+      if (!ready) enterFallback();
+    }, VERSION_BAR_READY_TIMEOUT_MS);
+  }
   // The version last delivered to the embed (via `init` or `version-changed`).
   // The host re-renders on many events (a commit, a saving-count bump, ...),
   // each calling `update`, but only an ACTUAL version change should reach the
@@ -107,11 +195,10 @@ export function createVersionBarFrame(
   let deliveredVersion: number | null | undefined = undefined;
 
   function postInit(): void {
-    const sid = deps.getSessionToken?.();
     if (!ctx) return;
     iframe.contentWindow?.postMessage(
       {
-        [ENVELOPE]: PROTOCOL_VERSION,
+        [EMBED_ENVELOPE]: EMBED_PROTOCOL_VERSION,
         type: 'init',
         surface: 'version-bar',
         params: {
@@ -119,7 +206,7 @@ export function createVersionBarFrame(
           ...(ctx.branch !== undefined ? { branch: ctx.branch } : {}),
           version: ctx.version,
           ...(ctx.branchName !== undefined ? { branchName: ctx.branchName } : {}),
-          ...(sid ? { sessionToken: sid } : {}),
+          ...(ctx.pinned ? { pinned: true } : {}),
         },
       },
       origin,
@@ -127,14 +214,64 @@ export function createVersionBarFrame(
     deliveredVersion = ctx.version;
   }
 
+  // Answer a navigating intent with what the document shows now. `ok` is
+  // whether the intent itself was accepted, which the version alone cannot
+  // say: a checkout the server rounded down and one that was refused both
+  // report a version other than the requested one, and the bar keeps the
+  // reader's step position for the first and reverts it for the second.
+  function confirmIntent(requestId: unknown, ok: boolean): void {
+    // An intent settles a turn after it was routed, by which time the bar may
+    // have been torn down (the reader closed it, the document changed). There
+    // is nothing listening then, and posting into a removed frame is an error
+    // that would surface as an unhandled rejection in the app.
+    if (!ready || destroyed) return;
+    const version = deps.currentVersion();
+    deliveredVersion = version;
+    iframe.contentWindow?.postMessage(
+      {
+        [EMBED_ENVELOPE]: EMBED_PROTOCOL_VERSION,
+        type: 'version-changed',
+        version,
+        ok,
+        ...(typeof requestId === 'string' ? { requestId } : {}),
+      },
+      origin,
+    );
+  }
+
+  // Intents still awaiting their answer. While one is in flight, `update()`
+  // stays quiet: the checkout it runs fires the host's subscribers before its
+  // promise resolves, so a render lands here ahead of `confirmIntent`, and an
+  // uncorrelated `version-changed` posted then reaches the embed as a phantom
+  // external move one message before the answer to its own step. The answer
+  // reads the live version at settle time, so nothing the quiet window saw is
+  // lost.
+  let intentsInFlight = 0;
+
+  function runIntent(requestId: unknown, intent: () => Promise<void>): void {
+    intentsInFlight += 1;
+    const settle = (ok: boolean) => (): void => {
+      // Decremented in every outcome. A count this leaves above zero silences
+      // `update()` for the life of the bar, so an external version change
+      // would never reach the embed again.
+      intentsInFlight -= 1;
+      confirmIntent(requestId, ok);
+    };
+    void intent().then(settle(true), settle(false));
+  }
+
   function onMessage(event: MessageEvent): void {
     if (event.origin !== origin) return;
     if (event.source !== iframe.contentWindow) return;
     const data = event.data as Record<string, unknown> | null;
-    if (!data || data[ENVELOPE] !== PROTOCOL_VERSION) return;
+    if (!data || data[EMBED_ENVELOPE] !== EMBED_PROTOCOL_VERSION) return;
     switch (data['type']) {
       case 'ready': {
         ready = true;
+        if (readyTimer !== undefined) {
+          clearTimeout(readyTimer);
+          readyTimer = undefined;
+        }
         placeholder.style.display = 'none';
         iframe.style.height = `${READY_HEIGHT}px`;
         postInit();
@@ -148,12 +285,12 @@ export function createVersionBarFrame(
       case 'preview': {
         const v = data['version'];
         if (typeof v === 'number' && Number.isInteger(v) && v >= 0) {
-          deps.checkoutVersion(v);
+          runIntent(data['requestId'], () => deps.checkoutVersion(v));
         }
         break;
       }
       case 'return-to-head': {
-        deps.returnToHead();
+        runIntent(data['requestId'], () => deps.returnToHead());
         break;
       }
       case 'fork': {
@@ -173,16 +310,17 @@ export function createVersionBarFrame(
         break;
       }
       case 'error': {
-        // The embed could not render (e.g. not signed in in this context).
-        // Collapse rather than leave a dead strip; the app still gates its
-        // own editing on `doc.readOnly`.
-        placeholder.style.display = 'none';
-        iframe.style.height = '0';
+        // The embed loaded and reported it cannot render (not signed in in
+        // this context, an account mismatch).
+        enterFallback();
         break;
       }
     }
   }
 
+  // Armed here rather than beside the `src` assignment above, which runs
+  // before `readyTimer` is initialised.
+  armReadyTimer();
   window.addEventListener('message', onMessage);
 
   return {
@@ -194,28 +332,47 @@ export function createVersionBarFrame(
       // just pushes the new version down.
       if (prev && (prev.docId !== next.docId || prev.branch !== next.branch)) {
         // Reload the iframe: reset ready, restore the placeholder, and the
-        // new page will `ready` -> we re-`init` with the new context.
+        // new page will `ready` -> we re-`init` with the new context. A fresh
+        // page gets a fresh verdict, so the failed state resets with it.
         ready = false;
+        failed = false;
         deliveredVersion = undefined;
+        fallback.hidden = true;
         placeholder.style.display = '';
         iframe.style.height = '0';
         iframe.src = url.toString();
+        armReadyTimer();
+        return;
+      }
+      if (failed) {
+        renderFallback();
         return;
       }
       // Only an actual version change reaches the embed (dedup), so a
       // re-render that didn't move the version can't clobber the bar's state.
-      if (ready && next.version !== deliveredVersion) {
+      // A change while an intent is in flight is that intent's own doing and
+      // is delivered by its answer instead.
+      if (ready && intentsInFlight === 0 && next.version !== deliveredVersion) {
         deliveredVersion = next.version;
         iframe.contentWindow?.postMessage(
-          { [ENVELOPE]: PROTOCOL_VERSION, type: 'version-changed', version: next.version },
+          { [EMBED_ENVELOPE]: EMBED_PROTOCOL_VERSION, type: 'version-changed', version: next.version },
           origin,
         );
       }
     },
     destroy(): void {
+      destroyed = true;
+      // A bar torn down mid-intent leaves the count standing; a rebuilt bar
+      // gets a fresh closure, but this keeps the teardown total.
+      intentsInFlight = 0;
+      if (readyTimer !== undefined) {
+        clearTimeout(readyTimer);
+        readyTimer = undefined;
+      }
       window.removeEventListener('message', onMessage);
       iframe.remove();
       placeholder.remove();
+      fallback.remove();
     },
   };
 }

package/src/version.ts

@@ -3,6 +3,6 @@
 // can measure the version distribution of deployed apps and time
 // compatibility windows against it. A unit test pins this to
 // package.json's version; the release bump touches both together.
-export const SDK_VERSION = '0.1.0';
+export const SDK_VERSION = '0.3.0';
 
 export const SDK_CLIENT_ID = `sdk/${SDK_VERSION}`;

package/src/vite.ts

@@ -8,37 +8,202 @@
 // plugin excludes the dep from prebundling (leaving it for the build-time
 // WASM loaders) and bumps the prebundle target to es2022.
 //
-// `vite-plugin-wasm` and `vite-plugin-top-level-await` remain the caller's
-// responsibility: they must land before `brassVite()` in the plugin list.
+// `vite-plugin-wasm` remains the caller's responsibility: it must land before
+// `brassVite()` in the plugin list.
 
-// Names of the WASM-shipping deps the SDK pulls in. Append rather
-// than replace when adding a new WASM dep: a consumer who has both
-// installed during a migration window needs both excluded.
-const WASM_DEPS: readonly string[] = ['loro-crdt'];
+// Every WASM-shipping dep the SDK pulls in, and the entry that loads it
+// asynchronously. Add an entry rather than replacing the list: a consumer who
+// has two installed during a migration window needs both handled, and this is
+// the one place any of them is named, so an app's own config never is.
+//
+// A default browser entry fetches its module with a SYNCHRONOUS
+// XMLHttpRequest while it evaluates, so an app freezes its main thread for the
+// whole download before it paints, whether or not anyone opens a document, and
+// the freeze grows with the reader's latency rather than with the app. An
+// `asyncEntry` hands the same module to the bundler's own asset pipeline,
+// which loads it asynchronously and leaves the main thread free. Selecting one
+// emits a top-level await, so it is reachable only on a build target that
+// accepts one, and the synchronous entry is what keeps every other target
+// building.
+const WASM_DEPS: readonly { specifier: string; asyncEntry: string }[] = [
+  { specifier: 'loro-crdt', asyncEntry: 'loro-crdt/bundler' },
+];
+
+// A specifier matched whole. A string `find` matches by prefix, which would
+// also catch the async entry the alias points AT and resolve it to itself.
+const wholeSpecifier = (specifier: string): RegExp =>
+  new RegExp(`^${specifier.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`);
+
+// The shape this plugin reads and returns, declared here rather than imported
+// so the SDK does not depend on Vite to describe its own plugin.
+//
+// Each field has to be at least as WIDE as Vite's own, because Vite passes its
+// `UserConfig` into the `config` hook and a hook declared over a narrower
+// config is not assignable to Vite's `Plugin`. `target` is the one that bites:
+// esbuild types it `string | string[]`, so declaring it `string` makes
+// `plugins: [brassVite()]` fail to type-check in a consumer's own
+// `vite.config.ts` (verified against Vite 5, 6 and 7; Vite 8 narrowed its own
+// type and hid it). The plugin only ever passes the value through, so the
+// wider type costs nothing here.
+interface ViteAliasEntry {
+  find: string | RegExp;
+  replacement: string;
+}
+
+interface ViteBuildOptions {
+  target?: string | string[] | false;
+}
 
 interface ViteUserConfig {
+  build?: ViteBuildOptions;
+  // Vite 8 lets a consumer set the browser build's target per environment, and
+  // that value, not the top-level one, is what the client bundle is built to.
+  environments?: { client?: { build?: ViteBuildOptions } };
+  resolve?: {
+    alias?: Record<string, string> | readonly ViteAliasEntry[];
+  };
   optimizeDeps?: {
     exclude?: string[];
-    esbuildOptions?: { target?: string };
+    esbuildOptions?: { target?: string | string[] };
   };
 }
 
 interface VitePlugin {
   name: string;
-  config(config: ViteUserConfig): ViteUserConfig;
+  config(config: ViteUserConfig): Promise<ViteUserConfig>;
+}
+
+// Vite 8 prebundles with rolldown, which handles top-level await on its own
+// and deprecates `optimizeDeps.esbuildOptions`. Setting it there does nothing
+// except print a deprecation warning naming this plugin, on every `vite dev`
+// and every `vite build` a consumer runs. Read from the running Vite rather
+// than from the consumer's manifest, and treat an unreadable version as an
+// older Vite, where the target bump is what makes the WASM dep load at all.
+//
+// The specifier is held in a variable so `tsc` does not resolve it. Vite is
+// neither a dependency nor a peer dependency here (the config shapes above are
+// declared for the same reason), so a literal specifier fails the build
+// wherever Vite is absent, which includes `npm install` in this package
+// itself. At runtime the import reaches the Vite running the build.
+const VITE_PACKAGE = 'vite';
+
+async function viteMajor(): Promise<number | null> {
+  try {
+    const { version } = (await import(VITE_PACKAGE)) as { version?: string };
+    const major = Number.parseInt(version ?? '', 10);
+    return Number.isFinite(major) ? major : null;
+  } catch {
+    return null;
+  }
+}
+
+// Browser versions that first shipped top-level await, by the engine names
+// esbuild accepts in a target string. A target naming an engine absent here is
+// read as unsupported.
+const TOP_LEVEL_AWAIT_SINCE: Readonly<Record<string, number>> = {
+  chrome: 89,
+  edge: 89,
+  firefox: 89,
+  safari: 15,
+  ios: 15,
+  opera: 75,
+  node: 14.8,
+  es: 2022,
+  hermes: Number.POSITIVE_INFINITY,
+  ie: Number.POSITIVE_INFINITY,
+};
+
+// Vite's own named targets. `modules` (the Vite 5 / 6 default) resolves to
+// browsers predating top-level await; `baseline-widely-available` (the Vite 7 /
+// 8 default) resolves to ones that carry it.
+const NAMED_TARGET_SUPPORT: Readonly<Record<string, boolean>> = {
+  esnext: true,
+  'baseline-widely-available': true,
+  modules: false,
+};
+
+function targetSupportsTopLevelAwait(target: string): boolean {
+  const t = target.trim().toLowerCase();
+  const named = NAMED_TARGET_SUPPORT[t];
+  if (named !== undefined) return named;
+  const parsed = /^([a-z]+)([\d.]+)$/.exec(t);
+  if (!parsed) return false;
+  const since = TOP_LEVEL_AWAIT_SINCE[parsed[1] as string];
+  if (since === undefined) return false;
+  const version = Number.parseFloat(parsed[2] as string);
+  return Number.isFinite(version) && version >= since;
+}
+
+// Whether the build this plugin is configuring can carry a top-level await.
+// An unreadable or unrecognised target answers `false`, so the worst a wrong
+// reading costs is the synchronous entry a consumer already has.
+function buildAcceptsTopLevelAwait(
+  config: ViteUserConfig,
+  major: number | null,
+): boolean {
+  const target = config.environments?.client?.build?.target ?? config.build?.target;
+  // No explicit target: the answer is Vite's own default, which carries
+  // top-level await from Vite 7 (`baseline-widely-available`) and not before
+  // (`modules`).
+  if (target === undefined) return major !== null && major >= 7;
+  if (target === false) return false;
+  const targets = Array.isArray(target) ? target : [target];
+  return targets.length > 0 && targets.every(targetSupportsTopLevelAwait);
+}
+
+// A consumer who already resolves the WASM dep themselves owns that decision,
+// so the plugin adds nothing that would take it over.
+function aliasesWasmDep(config: ViteUserConfig): boolean {
+  const alias = config.resolve?.alias;
+  if (!alias) return false;
+  const specifiers = WASM_DEPS.map((dep) => dep.specifier);
+  if (Array.isArray(alias)) {
+    return alias.some((entry) =>
+      specifiers.some((specifier) =>
+        typeof entry.find === 'string'
+          ? entry.find === specifier
+          : entry.find.test(specifier),
+      ),
+    );
+  }
+  return Object.keys(alias as Record<string, string>).some((key) =>
+    specifiers.includes(key),
+  );
 }
 
 export function brassVite(): VitePlugin {
   return {
     name: 'brass-build:vite',
-    config(config) {
+    async config(config) {
+      const major = await viteMajor();
+      const useAsyncEntry = buildAcceptsTopLevelAwait(config, major) && !aliasesWasmDep(config);
       const existingExclude = config.optimizeDeps?.exclude ?? [];
-      const exclude = Array.from(new Set([...existingExclude, ...WASM_DEPS]));
+      const exclude = Array.from(
+        new Set([
+          ...existingExclude,
+          ...WASM_DEPS.map((dep) => dep.specifier),
+          ...(useAsyncEntry ? WASM_DEPS.map((dep) => dep.asyncEntry) : []),
+        ]),
+      );
+      const resolve = useAsyncEntry
+        ? {
+            resolve: {
+              alias: WASM_DEPS.map((dep) => ({
+                find: wholeSpecifier(dep.specifier),
+                replacement: dep.asyncEntry,
+              })) as ViteAliasEntry[],
+            },
+          }
+        : {};
+      if (major !== null && major >= 8) {
+        return { ...resolve, optimizeDeps: { exclude } };
+      }
       const existingTarget = config.optimizeDeps?.esbuildOptions?.target;
       // Don't downgrade if a consumer has already pinned a newer
       // target; only raise from the Vite default (which lacks TLA).
       const target = existingTarget ?? 'es2022';
       return {
+        ...resolve,
         optimizeDeps: {
           exclude,
           esbuildOptions: { target },

package/src/when-saved.ts

@@ -0,0 +1,66 @@
+// Waiting out a document's own unsaved ops.
+//
+// `savingCount` counts the ops this client has committed locally and the
+// server has not acked, so a caller that needs the server to hold what the
+// app just wrote waits on it: the import completion, and the checkpoint
+// anchor, both of which describe a state rather than an intention.
+
+import type { Document } from './documents.js';
+
+// How often the wait re-checks. A closing document drops its subscribers
+// without firing them, so this is the only thing that ends the wait for one
+// that goes while writes are draining.
+const SAVED_POLL_MS = 1_000;
+
+// How long the OLDEST outstanding op may go unacked before the wait gives
+// up. An op the server never received is never acked and never re-sent
+// beyond the transport's own attempts, and `savingCount` then stays above
+// zero for the document's life, so a wait with no bound hangs its caller
+// forever. Read off the oldest op rather than off elapsed time, so a bulk
+// write that takes minutes never trips it: there, every op acks promptly
+// and the oldest is always young. Three forced-resend cycles wide (the
+// transport forces one at 60s), so the wait outlasts the recovery it is
+// waiting on.
+const SAVED_STALL_MS = 180_000;
+
+/**
+ * Resolve `true` once the document has no locally-issued op waiting for its
+ * server ack; `false` when the document is no longer live, or the acks
+ * stopped arriving.
+ *
+ * `false` does not say the writes were lost, only that this wait cannot say
+ * they landed. A caller about to record something permanent against them (an
+ * import completion, a checkpoint anchor) has to stop on it.
+ *
+ * @internal
+ */
+export function whenSaved(doc: Document): Promise<boolean> {
+  if (doc.savingCount === 0) return Promise.resolve(true);
+  return new Promise<boolean>((resolve) => {
+    let off: (() => void) | undefined;
+    let poll: ReturnType<typeof setInterval> | undefined;
+    const settle = (saved: boolean): void => {
+      off?.();
+      if (poll !== undefined) clearInterval(poll);
+      resolve(saved);
+    };
+    try {
+      off = doc.subscribe(() => {
+        if (doc.savingCount === 0) settle(true);
+      });
+    } catch {
+      // The document closed, so nothing more is going to be acked.
+      resolve(false);
+      return;
+    }
+    poll = setInterval(() => {
+      if (doc.savingCount === 0) return settle(true);
+      if (!doc._isLive) return settle(false);
+      if (doc.diagnostics().oldestUnackedMs >= SAVED_STALL_MS) settle(false);
+    }, SAVED_POLL_MS);
+    // Node keeps the process alive for a pending interval; this one is
+    // bookkeeping for a wait that ends on its own, so it must not.
+    (poll as { unref?: () => void }).unref?.();
+    if (doc.savingCount === 0) settle(true);
+  });
+}