@brass-build/client 0.1.0 → 0.3.0

package/src/session.ts

@@ -375,7 +375,14 @@ export function createDocumentSession(
     // `openError` message joins the signature so a switch from one failed open
     // to a different one (same 'error' status, no bound doc) still re-fires.
     const err = openError ? `${openError.status ?? ''}:${openError.message}` : '';
-    return `${status()}|${document?.id ?? ''}|${documentName ?? ''}|${load}|${err}|${cmds}`;
+    // The previewed version and the browsing flag are their own terms because
+    // nothing else in this signature follows them: a preview -> preview step
+    // holds the id, the name, the status and every command's enabled state
+    // (edit affordances are already disabled by the first checkout), so
+    // without these the step is a silent emit and the chrome rendering the
+    // preview keeps showing the version the reader stepped away from.
+    const ver = `${document?.version ?? ''}:${document?.versionBrowsing ? 1 : 0}`;
+    return `${status()}|${document?.id ?? ''}|${documentName ?? ''}|${load}|${err}|${ver}|${cmds}`;
   }
 
   function emit(): void {
@@ -386,7 +393,10 @@ export function createDocumentSession(
     // subscribe handler awaits whenReady sees it already resolved by the time
     // its listener runs.
     settleWhenReady();
-    for (const listener of listeners) {
+    // Copied before the walk, so a listener that detaches another still
+    // leaves it this fire: an entry removed from a `Set` before its turn is
+    // never visited.
+    for (const listener of Array.from(listeners)) {
       try {
         listener(session);
       } catch (err) {
@@ -533,8 +543,7 @@ export function createDocumentSession(
         // A `branches` event resolves `defaultBranchId`, which `urlBranch`
         // needs to drop a specified-but-default branch; re-sync in place so
         // the pinned branch settles once the default is known.
-        const kind = (event as { kind?: string } | undefined)?.kind;
-        if (kind === 'branches') syncUrlForActive('replace');
+        if (event.kind === 'branches') syncUrlForActive('replace');
         // Take the doc's name whenever it moves. A rename reaches the doc
         // from the server's `doc_meta` frame, which sets it directly, and
         // `documentName` is what the emit signature reads: without this the
@@ -564,7 +573,15 @@ export function createDocumentSession(
           // (access was genuinely lost in the move). Detach the moved doc first
           // so that failure parks the gone surface rather than rebinding a doc
           // that is itself gone.
+          //
+          // Detaching is what leaves the evicted copy to be disposed here:
+          // `activate` closes the document it detached itself, and it detached
+          // a null one. Nothing else holds this copy, and an evicted Document
+          // keeps its topic subscription and its LoroDoc until it is closed, so
+          // every move would otherwise leave one resident for the life of the
+          // page, taking a copy of every op the reopened document receives.
           const branch = urlBranch(next);
+          const evicted = next;
           document = null;
           documentName = null;
           void activate(
@@ -581,7 +598,9 @@ export function createDocumentSession(
             null,
             'skip',
             branch,
-          ).catch(() => markGoneRemote());
+          )
+            .catch(() => markGoneRemote())
+            .finally(() => closeQuietly(evicted));
           return;
         }
         // Evicted from under the viewer (remote delete, or a future eviction
@@ -712,11 +731,51 @@ export function createDocumentSession(
     const previousSpecifiedBranch = activeSpecifiedBranch;
     document = null;
     documentName = null;
+    // What the join's spilled ops have cost so far, and what the whole
+    // download was declared to be. Carried across the two phases so the pair
+    // reads as one figure. Per open, because a second open of the same
+    // document downloads it again.
+    let tailLoadedBytes = 0;
+    let downloadTotalBytes: number | null = null;
     emit();
     // Surface snapshot-download progress. Ignored once a newer open supersedes
     // this generation, so a slow stale download can't repaint the new open.
-    const onSnapshotProgress = (loaded: number, total: number | null): void => {
+    const onSnapshotProgress = (
+      loaded: number,
+      total: number | null,
+      phase?: 'snapshot' | 'tail',
+    ): void => {
       if (generation !== openGeneration) return;
+      // One download, reported once. A document whose ops spilled to storage
+      // fetches them from the join before the snapshot, so a load has two
+      // stretches of bytes arriving over the network with a reader watching.
+      // Which of them is on the wire is a fact about how the platform stores a
+      // document, not something a reader can act on, so both count into the
+      // same figure under the same word.
+      //
+      // The tail runs first and declares no total, so its bytes are carried
+      // into the snapshot's total once that is known. The percentage is then
+      // monotonic across the pair rather than filling twice.
+      if (phase === 'tail') {
+        tailLoadedBytes = loaded;
+        // The tail's total already includes the snapshot still to come, so the
+        // figure runs across both rather than filling once here and again
+        // after. Held for the snapshot phase, which reports only its own.
+        downloadTotalBytes = total;
+      }
+      if (phase !== 'tail') {
+        loaded += tailLoadedBytes;
+        if (downloadTotalBytes !== null) total = downloadTotalBytes;
+        else if (total !== null) total += tailLoadedBytes;
+      }
+      // Both phases fall through to the same reporting. The tail's total
+      // already covers the snapshot still to come, so a tail callback that
+      // reaches the total is a load with no snapshot phase behind it (an
+      // inline snapshot arrived with the join and declares no bytes), and
+      // the last byte of the download is the last progress event there will
+      // ever be. Reported as a fraction of its own phase instead, that load
+      // ends parked on a number that never moves again while the reader
+      // waits out the import.
       const complete = total !== null && total > 0 && loaded >= total;
       if (complete) {
         // Bytes are in; the remaining work (loro import, projection, render)
@@ -732,25 +791,22 @@ export function createDocumentSession(
       }
       emit();
     };
-    let doc: OpenedDocument;
-    try {
-      doc = await load(onSnapshotProgress);
-    } catch (err) {
+    // Give up on this open. A warm swap (previous doc present) rebinds it and
+    // only rejects the caller, so the working surface is never clobbered; with
+    // nothing to fall back to the session parks in 'error' so a status-gated
+    // app renders the failure, where a rebind would land on the empty state
+    // and read as the app's document-less home. `display` is what the app
+    // renders; it defaults to the platform's own open-failure copy.
+    function abandonOpen(err: unknown, display?: BrassError): never {
       if (generation === openGeneration) {
         loading = false;
         loadingMessage = null;
         loadingProgress = null;
-        // Rebind the previous document so the user keeps their editor.
         // 'replace' restores the URL without planting an entry for an open
         // that never happened.
         activeSpecifiedBranch = previousSpecifiedBranch;
-        // With no document to fall back to, a rebind lands on the empty state,
-        // which reads as the app's document-less home and hides the failure.
-        // Park the session in 'error' instead so a status-gated app renders
-        // the failure. A warm swap (previous doc present) keeps the editor and
-        // only rejects the caller, so the working surface is never clobbered.
         if (surfaceOpenError && previousDocument === null) {
-          openError = toDisplayError(err);
+          openError = display ?? toDisplayError(err);
           // Leave the URL pointing at the doc that failed ('skip', not the
           // 'replace' below that clears it for a null document): the error
           // surface corresponds to that id, so a reload re-shows it and the
@@ -766,6 +822,12 @@ export function createDocumentSession(
       }
       throw err;
     }
+    let doc: OpenedDocument;
+    try {
+      doc = await load(onSnapshotProgress);
+    } catch (err) {
+      abandonOpen(err);
+    }
     if (generation !== openGeneration) {
       // A newer open / close superseded this one. Discard the orphan (so its
       // WS subscription doesn't leak) plus the doc this generation detached.
@@ -815,6 +877,18 @@ export function createDocumentSession(
         return doc;
       }
     }
+    // The work ended with no content: the platform could not prepare this
+    // document, so the open failed. Binding it would present an empty
+    // document as ready, and the app would let the user work in it. The
+    // platform's own message is what the app renders.
+    if (doc._contentLoadFailed) {
+      closeQuietly(doc);
+      const failure = new BrassError(
+        doc.status?.message ?? OPEN_FAILED_MESSAGE,
+        { status: 0 },
+      );
+      abandonOpen(failure, failure);
+    }
     loading = false;
     loadingMessage = null;
     loadingProgress = null;

package/src/tail-ops.ts

@@ -16,7 +16,11 @@ import { BrassError } from './errors.js';
 /** A tail op as the server sends it. */
 export type WireTailOp =
   | { seq: number; op_blob_b64: string }
-  | { seq: number; op_blob_url: string };
+  // `op_blob_bytes` is what this entry costs to fetch, which is what lets a
+  // load know the whole of its download before it starts one. Optional
+  // because a server that predates it names no size, and a total built from
+  // what is named is still better than none.
+  | { seq: number; op_blob_url: string; op_blob_bytes?: number };
 
 /** A tail op with its bytes in hand. */
 export interface ResolvedTailOp {
@@ -28,13 +32,44 @@ function isUrlOp(op: WireTailOp): op is { seq: number; op_blob_url: string } {
   return typeof (op as { op_blob_url?: unknown }).op_blob_url === 'string';
 }
 
+/**
+ * What the spilled entries in this tail say they will cost to fetch.
+ *
+ * Read before any of them is fetched, so a load can state the whole of what it
+ * is about to download rather than discovering it. An entry naming no size
+ * counts zero, which understates the total: a bar that finishes early is a
+ * worse answer than one that never moves, and a much better one than a bar
+ * that goes backwards when the rest arrives.
+ */
+export function declaredTailBytes(tailOps: readonly WireTailOp[]): number {
+  let total = 0;
+  for (const op of tailOps) {
+    if (!isUrlOp(op)) continue;
+    const declared = (op as { op_blob_bytes?: unknown }).op_blob_bytes;
+    if (typeof declared === 'number' && declared > 0) total += declared;
+  }
+  return total;
+}
+
+/**
+ * How many spilled ops a join fetches at once.
+ *
+ * A browser refuses to open an unbounded number of sockets: past a few
+ * hundred in flight it fails the rest of them outright with
+ * `ERR_INSUFFICIENT_RESOURCES`, which arrives as a rejected fetch and
+ * fails the whole join. Chrome's own per-host cap is 6, so a higher bound
+ * here only queues inside the browser; this is low enough to stay clear of
+ * the failure and high enough that the queue drains at the connection
+ * limit rather than the loop's.
+ */
+const TAIL_FETCH_CONCURRENCY = 8;
+
 /**
  * Fetch any tail op whose bytes live behind a signed URL, leaving inline
  * ops untouched, and return the tail in its original order.
  *
- * Ordering matters and concurrency does not disturb it: the fetches run
- * together but each result lands back at its own index, so the caller
- * still applies ops in ascending seq.
+ * Ordering matters and concurrency does not disturb it: each result lands
+ * back at its own index, so the caller still applies ops in ascending seq.
  *
  * A failed fetch throws rather than dropping the op. Skipping one would
  * leave the reader a document missing an edit it will never be sent
@@ -44,20 +79,51 @@ function isUrlOp(op: WireTailOp): op is { seq: number; op_blob_url: string } {
 export async function resolveTailOps(
   tailOps: readonly WireTailOp[],
   fetchImpl: typeof fetch = fetch,
+  // Told how many BYTES of the spilled ops are in hand, as each lands. A
+  // document whose tail spilled fetches hundreds of objects here, eight at a
+  // time, inside the join and before anything else reports: without this the
+  // whole stretch is silent, and a load that is working looks exactly like one
+  // that has hung.
+  //
+  // Bytes rather than objects because this is half of one download, not a
+  // stage of its own. The snapshot that follows is measured in bytes, and a
+  // reader watching a load has no use for the distinction between an op that
+  // spilled and the snapshot it will be folded into.
+  onProgress?: (loadedBytes: number) => void,
 ): Promise<ResolvedTailOp[]> {
-  if (!tailOps.some(isUrlOp)) {
+  const spilled = tailOps.filter(isUrlOp).length;
+  if (spilled === 0) {
     return tailOps as ResolvedTailOp[];
   }
-  return Promise.all(
-    tailOps.map(async (op) => {
-      if (!isUrlOp(op)) return op;
+  const out: ResolvedTailOp[] = Array.from({ length: tailOps.length });
+  let loadedBytes = 0;
+  onProgress?.(0);
+  let next = 0;
+  const worker = async (): Promise<void> => {
+    for (;;) {
+      const i = next++;
+      if (i >= tailOps.length) return;
+      const op = tailOps[i]!;
+      if (!isUrlOp(op)) {
+        out[i] = op;
+        continue;
+      }
       // The URL is pre-signed, so it carries no Brass headers: adding one
       // would fall outside the signature and be refused.
       const response = await fetchImpl(op.op_blob_url, { method: 'GET' });
       if (!response.ok) {
         throw new BrassError('Tail op fetch failed', { status: response.status });
       }
-      return { seq: op.seq, op_blob_b64: await response.text() };
-    }),
+      const body = await response.text();
+      out[i] = { seq: op.seq, op_blob_b64: body };
+      loadedBytes += body.length;
+      onProgress?.(loadedBytes);
+    }
+  };
+  await Promise.all(
+    Array.from({ length: Math.min(TAIL_FETCH_CONCURRENCY, tailOps.length) }, () =>
+      worker(),
+    ),
   );
+  return out;
 }

package/src/topic-lifecycle.ts

@@ -17,6 +17,11 @@
 //     `retrySpent` survives into a same-connection re-subscribe so the
 //     retry stays one-per-topic-per-connection.
 //
+// A frame-scoped reason (`isFrameScopedReason`) is the exception to all of
+// that: it describes the frame the server could not process, not the
+// subscription it arrived on, so every live phase keeps its state and hands
+// the error to the topic's callbacks, which hold the frame that drew it.
+//
 // Invariant: every transition into `tornDown` emits `send_unsubscribe`,
 // so no server-side subscription row can outlive the client-side state
 // (an orphan row would have its `last_seen` kept fresh by the heartbeat,
@@ -55,6 +60,10 @@ export type TopicEffect =
   // Detach the topic's callbacks: further server frames must not reach
   // them and the user's unsubscribe becomes a no-op.
   | { kind: 'drop_listeners' }
+  // Hand the error to the topic's callbacks and leave the subscription
+  // alone. The callbacks own whatever frame drew it, so they own the
+  // recovery.
+  | { kind: 'deliver_error'; reason: string }
   | { kind: 'fire_error'; reason: string };
 
 export interface StepResult {
@@ -63,16 +72,28 @@ export interface StepResult {
 }
 
 // True while topic-scoped frames must be held back: sending before the
-// `subscribed` ack races the server's SUB# row write and draws a spurious
+// `subscribed` ack races the server's subscription record write and draws a spurious
 // `forbidden`.
 export function holdsFrames(state: TopicState): boolean {
   return state.phase === 'subscribing' || state.phase === 'retrying';
 }
 
+// True for a reason that judges one frame rather than the subscription.
+// `unavailable` answers a durable op write the server was authorised to
+// take and could not store right now, so the topic stays up and the writer
+// re-sends the op.
+export function isFrameScopedReason(reason: string): boolean {
+  return reason === 'unavailable';
+}
+
 const SEND_SUBSCRIBE: TopicEffect = { kind: 'send_subscribe' };
 const FLUSH_HELD: TopicEffect = { kind: 'flush_held' };
 const DROP_HELD: TopicEffect = { kind: 'drop_held' };
 
+function deliverError(state: TopicState, reason: string): StepResult {
+  return { state, effects: [{ kind: 'deliver_error', reason }] };
+}
+
 // Rejection / spent-retry teardown. `send_unsubscribe` releases any
 // server-side row a completed retry may have re-created (the invariant in
 // the header); `unsubscribe` is idempotent server-side, so sending it when
@@ -123,6 +144,9 @@ export function step(state: TopicState, event: TopicEvent): StepResult {
             effects: [FLUSH_HELD],
           };
         case 'error':
+          if (isFrameScopedReason(event.reason)) {
+            return deliverError(state, event.reason);
+          }
           // Never established on this connection: the rejection is final.
           return tearDown(state, event.reason);
         case 'socket_open':
@@ -139,6 +163,9 @@ export function step(state: TopicState, event: TopicEvent): StepResult {
     case 'established':
       switch (event.type) {
         case 'error':
+          if (isFrameScopedReason(event.reason)) {
+            return deliverError(state, event.reason);
+          }
           // A mid-stream `not_subscribed` is an eviction (the server
           // dropped the subscription row while this client stayed alive,
           // e.g. a presence reap that raced a live-but-quiet connection),
@@ -169,6 +196,9 @@ export function step(state: TopicState, event: TopicEvent): StepResult {
     case 'retrying':
       switch (event.type) {
         case 'error':
+          if (isFrameScopedReason(event.reason)) {
+            return deliverError(state, event.reason);
+          }
           // An eviction draws errors for EVERY frame in flight against the
           // reaped row; the trailing ones land while the retry's subscribe
           // is unacked and describe frames that predate it, so the retry

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { HostedUiTheme } from './hosted-ui.js';
+
 export interface BrassUser {
   sub: string;
   email?: string;
@@ -27,7 +29,7 @@ export interface BrassInitOptions {
   // `'light'`; `'auto'` follows the OS preference. An app that forces
   // its own theme should pass the matching value so the modal doesn't
   // mismatch the page that opened it.
-  hostedUiTheme?: 'light' | 'dark' | 'auto';
+  hostedUiTheme?: HostedUiTheme;
   // Open a document even when this app's declared schema cannot read it
   // (default off). Off, the platform refuses such an open and the SDK asks
   // the person whether to go ahead, so a bookmark or a reload cannot open
@@ -37,9 +39,10 @@ export interface BrassInitOptions {
   // Mirror the active document selection to the page URL (default on):
   // writes the doc id (and non-default branch) using `pushState` for a
   // genuine open / branch switch and `replaceState` to pin the boot
-  // selection, and restores from the URL on boot and `popstate`. Read
-  // the id directly via `Brass.docIdFromUrl()`. Opt out with `false`
-  // for an app that owns its URL state (e.g. its own router).
+  // selection, and restores from the URL on boot and `popstate`. The
+  // document the URL named is bound as `Brass.session.document`, so an
+  // app reads the active id from `session.document?.id`. Opt out with
+  // `false` for an app that owns its URL state (e.g. its own router).
   syncDocToUrl?: boolean;
   // Query-parameter name for the active doc id (default `'doc'`). Set to
   // disambiguate when the app's URL already uses `doc`.
@@ -73,3 +76,52 @@ export type UserChangeListener = (user: BrassUser | null) => void;
 // before init to get visibility into failures that an init wrapped
 // without a `.catch()` would otherwise swallow silently.
 export type ErrorListener = (error: Error) => void;
+
+export interface UndoControllerOptions {
+  // Cap on retained undo steps. Older steps drop off the bottom of the
+  // stack as new ones land.
+  maxUndoSteps?: number;
+}
+
+/**
+ * A document's own view of how its sync is going, as the client sees it.
+ *
+ * The server records what reached it, so the facts that separate a write
+ * that was lost from a client that is merely slow live only here. Read it
+ * when a save is taking longer than it should; `Brass.onError` reports
+ * failures, and this reports the state a failure has not yet been declared
+ * for.
+ */
+export interface DocSyncDiagnostics {
+  /** Ops committed locally that the server has not acknowledged. */
+  unackedOps: number;
+  /** How long the oldest of them has been waiting, in ms. 0 when none. */
+  oldestUnackedMs: number;
+  /**
+   * The oldest unacked op's correlator. The same id rides the op to the
+   * server, so it is what an operator matches a stuck save against the
+   * server's record of the write.
+   */
+  oldestClientOpId: string | null;
+  /**
+   * Sockets the SDK has opened since it was constructed, past the first.
+   * Every open document shares one socket, so this is a fact about the
+   * client rather than about this document, and it counts a deliberate
+   * close and re-open alongside a drop.
+   */
+  reconnects: number;
+  /**
+   * Since any acknowledgement landed on this socket, in ms, or null when
+   * none ever has. A connection answering nothing and one merely behind
+   * look the same from a single op's age; this is what tells them apart.
+   */
+  lastAckAgeMs: number | null;
+  /** Bytes on the socket against the transport's in-flight budget. */
+  inFlightBytes: number;
+  /** Ops too large for the socket, travelling over HTTP right now. */
+  httpOpsInFlight: number;
+  /** Rounds the durability handshake has spent reconciling. */
+  healRounds: number;
+  /** Whether the page is hidden, which throttles the client's timers. */
+  hidden: boolean;
+}

package/src/undo.ts

@@ -4,6 +4,8 @@
 // redo stack honest across other peers' edits.
 import { UndoManager, type LoroDoc } from 'loro-crdt';
 
+import type { UndoControllerOptions } from './types.js';
+
 // Loro's time-based merge is permanently disabled. The undo boundary here is
 // the checkpoint group bracket (`sealStep`), and the two are incompatible: a
 // nonzero merge interval merges adjacent changes by *timestamp*, and that
@@ -20,11 +22,16 @@ const UNDO_MERGE_INTERVAL_MS = 0;
 // entity sizes is a few hundred KB, well below anything that matters.
 const DEFAULT_MAX_UNDO_STEPS = 200;
 
-export interface UndoControllerOptions {
-  // Cap on retained undo steps. Older steps drop off the bottom of the
-  // stack as new ones land.
-  maxUndoSteps?: number;
-}
+// Commit origin the paged marker (`meta.paged:<root>`) is stamped with, and
+// the one origin the undo stack ignores.
+//
+// The marker says which shape a root's records are stored in, so it is a fact
+// about the store rather than a step the reader took: undoing it leaves the
+// pages the crossing mutation sealed behind a marker that says unpaged, which
+// every reader answers by handing back the page entries themselves. The write
+// that carries it therefore commits alone, so nothing an app authored is
+// excluded alongside it.
+export const PAGING_COMMIT_ORIGIN = 'brass.paging';
 
 // Thin wrapper around Loro's UndoManager exposing only what the Document
 // needs. Owned by the Document; not part of the public SDK surface.
@@ -42,6 +49,7 @@ export class UndoController {
     this._mgr = new UndoManager(loroDoc, {
       mergeInterval: UNDO_MERGE_INTERVAL_MS,
       maxUndoSteps: options?.maxUndoSteps ?? DEFAULT_MAX_UNDO_STEPS,
+      excludeOriginPrefixes: [PAGING_COMMIT_ORIGIN],
     });
     // Open the implicit group so commits before the first `createCheckpoint`
     // still bracket as one undo step.

package/src/unload-guard.ts

@@ -0,0 +1,91 @@
+// Native "leave site?" confirmation while a document holds ops the server
+// has not acked. Reloading or navigating away drops those ops with the tab,
+// so the browser's own prompt is the last point at which the writer can
+// choose to stay.
+//
+// One registry rather than a listener per document: several documents can be
+// open at once (and one the app has closed can still be parked in the SDK's
+// cache with ops in flight), while the prompt is a property of the page. The
+// registry keys on the owning Document so a count only ever leaves when that
+// document acks its ops or closes, and the listener is attached only while
+// the total is above zero. A permanently attached listener prompts on every
+// navigation, which teaches readers to dismiss it.
+
+export interface UnloadTarget {
+  addEventListener(type: 'beforeunload', listener: (e: Event) => void): void;
+  removeEventListener(type: 'beforeunload', listener: (e: Event) => void): void;
+}
+
+const outstandingByOwner = new Map<object, number>();
+let handler: ((e: Event) => void) | null = null;
+// The target the handler is attached to, so a detach cannot go to a
+// different one than the attach did.
+let attachedTo: UnloadTarget | null = null;
+// `undefined` means "resolve from the environment"; a test overrides it with
+// a fake target, or with `null` to stand in for a non-browser host.
+let targetOverride: UnloadTarget | null | undefined;
+
+function resolveTarget(): UnloadTarget | null {
+  if (targetOverride !== undefined) return targetOverride;
+  const candidate = (globalThis as { window?: unknown }).window;
+  if (typeof candidate !== 'object' || candidate === null) return null;
+  const target = candidate as Partial<UnloadTarget>;
+  if (typeof target.addEventListener !== 'function') return null;
+  if (typeof target.removeEventListener !== 'function') return null;
+  return target as UnloadTarget;
+}
+
+function sync(): void {
+  let total = 0;
+  for (const count of outstandingByOwner.values()) total += count;
+
+  if (total === 0) {
+    if (handler && attachedTo) {
+      attachedTo.removeEventListener('beforeunload', handler);
+    }
+    handler = null;
+    attachedTo = null;
+    return;
+  }
+  if (handler) return;
+  const target = resolveTarget();
+  if (!target) return;
+  handler = (e: Event): void => {
+    // `preventDefault` is the whole signal. Browsers show their own wording
+    // and ignore anything the handler returns or assigns.
+    e.preventDefault();
+  };
+  attachedTo = target;
+  target.addEventListener('beforeunload', handler);
+}
+
+// Report how many un-acked ops `owner` holds. Zero forgets it.
+/** @internal */
+export function trackUnsavedWork(owner: object, count: number): void {
+  if (count > 0) outstandingByOwner.set(owner, count);
+  else outstandingByOwner.delete(owner);
+  sync();
+}
+
+// Forget `owner` entirely, whatever it last reported. Called from
+// `Document.close()`, where the ops go away with the document.
+/** @internal */
+export function releaseUnsavedWork(owner: object): void {
+  if (!outstandingByOwner.delete(owner)) return;
+  sync();
+}
+
+// Point the guard at a fake target and drop every tracked owner, so one
+// test's documents cannot hold the listener open across the next.
+/** @internal */
+export function _setUnloadTargetForTesting(
+  target: UnloadTarget | null | undefined,
+): void {
+  if (handler && attachedTo) {
+    attachedTo.removeEventListener('beforeunload', handler);
+  }
+  handler = null;
+  attachedTo = null;
+  outstandingByOwner.clear();
+  targetOverride = target;
+}