@brass-build/client 0.1.0 → 0.3.0

package/src/document-engine.ts

@@ -0,0 +1,15 @@
+// The typed way for in-repo tooling (the benches, the fuzz harness) to wrap a
+// LoroDoc it already holds. It sits in a module of its own, outside what the
+// package entry reaches, so it can name Loro's types while the SDK's public
+// surface stays engine-neutral.
+
+import type { LoroDoc } from 'loro-crdt';
+
+import { Document, type DocumentOptions } from './documents.js';
+
+export function documentFromEngine(
+  engine: LoroDoc,
+  options?: DocumentOptions,
+): Document {
+  return Document._fromEngine(engine, options);
+}

package/src/document-signals.ts

@@ -9,7 +9,7 @@
 import { createEmitter } from './emitter.js';
 
 // Reason a Document's underlying doc was evicted. Mirrors the `doc_gone`
-// frame's `reason` (CONTRACT.md "Server-pushed `doc_gone`"). New literals land
+// frame's `reason`. New literals land
 // here as the platform grows transitions that evict open subscribers.
 // `moved`: the doc changed organization or project, so its access gate
 // changed and open subscribers re-establish under the new location.
@@ -19,7 +19,7 @@ export type DocumentGoneListener = (reason: DocumentGoneReason) => void;
 export type DocumentGoneUnsubscribe = () => void;
 
 // Opaque status of slow server-side work (hydration, extraction, push).
-// Mirrors the wire shape (CONTRACT.md "Server-pushed `doc_status`"). The app
+// Mirrors the wire shape of the server's status frame. The app
 // renders `message` verbatim, draws a bar from `progress`, and waits while
 // `pending`. No kind / phase / error code: the server owns all wording and can
 // change phases without any app change.
@@ -39,14 +39,14 @@ export type DocumentStatusListener = (status: DocumentWorkStatus) => void;
 export type DocumentStatusUnsubscribe = () => void;
 
 // Coarse divergence state of a drive-linked doc vs its source. Mirrors the
-// server's `tracking_state` (CONTRACT.md "Drive document tracking state"). The
+// server's `tracking_state`. The
 // app reads `state` to decide which affordance to show, never to pick wording
 // (that is server-authored `label` / `detail`).
 export type DocumentDriveTrackingState =
   | 'unhydrated'
   | 'synced'
-  | 'ahead'
   | 'behind'
+  | 'ahead'
   | 'diverged';
 
 // Which way the mirror flows. `two_way` links round-trip; `import_only` links
@@ -54,11 +54,11 @@ export type DocumentDriveTrackingState =
 // reads this to decide whether to show a Publish affordance at all.
 export type DriveMirrorDirection = 'two_way' | 'import_only';
 
-// The drive sync state of an open document, the read-side companion to
-// `doc.pushToDrive(...)`. Present only on drive-linked docs; `null` otherwise.
-// Lets an app show "you have unpublished edits" without polling. Words are
+// The drive sync state of an open document. Present only on drive-linked
+// docs; `null` otherwise. Lets an app show "you have unpublished edits"
+// without polling, while the hosted toolbar owns publishing itself. Words are
 // server-authored (`label` / `detail`, rendered verbatim); the app branches
-// only on `state` / `canPush` to decide whether to show an affordance.
+// only on `state` / `canPush`.
 export interface DocumentDriveStatus {
   // Adapter type token; an app may key an icon off it. The human label is
   // `driveName`, so an app never maps the type to a vendor name itself.
@@ -99,6 +99,11 @@ export interface DocumentDriveStatus {
   // the Publish affordance rather than re-deriving it. `detail` carries the
   // server-authored progress line while it is `true`.
   publishing: boolean;
+  /** The drive's own words about the file the last publish delivered, set
+   *  only where the drive answered that it could not read it. The publish
+   *  succeeded and the artifact exists; the drive's reader rejects it, which
+   *  a person otherwise meets as an error inside the drive. */
+  sourceUnreadable?: string;
 }
 
 export type DocumentDriveStatusListener = (
@@ -106,6 +111,32 @@ export type DocumentDriveStatusListener = (
 ) => void;
 export type DocumentDriveStatusUnsubscribe = () => void;
 
+// Where a document that mirrors nothing can be published: the drive its
+// project is linked to, which takes it as a NEW file. A drive-linked
+// document has `driveStatus` and no targets; this is the state before the
+// first publish, which is what a document added to a linked project (an
+// upload, or one an app created there) sits in.
+//
+// Words are server-authored (`detail`, rendered verbatim), as everywhere
+// else a drive is described.
+export interface DrivePublishTarget {
+  // Adapter type token; an app may key an icon off it.
+  driveType: string;
+  // The drive's user-facing name.
+  driveName: string;
+  // What the linked container is called on the drive, so a surface can say
+  // where the file lands.
+  containerName: string;
+  // The sentence a publish affordance renders, verbatim.
+  detail: string;
+  // True while a publish is in flight, so the affordance holds rather than
+  // inviting a second artifact.
+  publishing: boolean;
+  // The last publish attempt failed, in which case `detail` carries the
+  // server's account of why rather than the resting sentence.
+  publishFailed: boolean;
+}
+
 // Each signal is a `createEmitter` composed with the retain / attach / dedup
 // policy its wire event needs, wrapped in a small class only to keep the
 // domain-named methods (`mark`, `emit`, `status`, `clearListeners`) the
@@ -208,6 +239,86 @@ export class DriveStatusSignal {
   }
 }
 
+// How the publish of a document that mirrors nothing is going. Server-
+// authored: `detail` replaces the target's resting sentence while present,
+// and is rendered verbatim.
+export interface DrivePublishState {
+  // A publish is running on the server.
+  publishing: boolean;
+  // The last publish attempt failed; `detail` says what the server made of
+  // it.
+  failed: boolean;
+  // The sentence to render, or null to fall back to the target's resting
+  // copy.
+  detail: string | null;
+}
+
+const RESTING_PUBLISH: DrivePublishState = {
+  publishing: false,
+  failed: false,
+  detail: null,
+};
+
+// Where an unlinked document can be published, and how its publish is going.
+//
+// The TARGETS are seeded from the join alone, because the set only changes
+// when the document becomes a mirror and the drive status arriving is that
+// event, so the open factory clears them when one does. The STATE moves
+// while the document is open: the first publish creates the artifact, so
+// until it lands there is no drive status to report progress or failure
+// through, and a `doc_drive_publish` frame carries it instead.
+export class DrivePublishTargetSignal {
+  private _target: DrivePublishTarget | null = null;
+  private _state: DrivePublishState = RESTING_PUBLISH;
+  private readonly _listeners = new Set<() => void>();
+
+  get target(): DrivePublishTarget | null {
+    return this._target;
+  }
+
+  get state(): DrivePublishState {
+    return this._state;
+  }
+
+  set(target: DrivePublishTarget | null): void {
+    this._target = target;
+    // The join states the same thing the frames do, so a reopen starts from
+    // the server's current answer rather than from the last frame's.
+    this._state = {
+      publishing: target?.publishing === true,
+      failed: target?.publishFailed === true,
+      detail: null,
+    };
+    this._notify();
+  }
+
+  setState(state: DrivePublishState): void {
+    this._state = state;
+    this._notify();
+  }
+
+  onState(cb: () => void): () => void {
+    this._listeners.add(cb);
+    return () => {
+      this._listeners.delete(cb);
+    };
+  }
+
+  // Paired with the other signals' method of the same name: a parked or
+  // closed Document must not reach an app callback registered by a session
+  // that is over.
+  clearListeners(): void {
+    this._listeners.clear();
+  }
+
+  // Both mutators notify. A reader renders the targets and the state
+  // together, so a change to either is a change to what it draws, and one
+  // silent mutator would leave that reader showing the other half.
+  private _notify(): void {
+    for (const cb of this._listeners) cb();
+  }
+}
+
 // Field-by-field equality for the drive status. The shape is flat (all
 // scalars), so a key compare suffices; explicit rather than JSON.stringify so
 // a future non-scalar field forces a conscious update here.
@@ -228,6 +339,7 @@ function driveStatusEqual(
     a.ref === b.ref &&
     a.refUpdatedAt === b.refUpdatedAt &&
     a.publishing === b.publishing &&
+    a.sourceUnreadable === b.sourceUnreadable &&
     a.itemName === b.itemName &&
     a.itemUrl === b.itemUrl
   );

package/src/document-streams.ts

@@ -18,7 +18,14 @@ import type {
   EntityProxy,
 } from './documents.js';
 import type { DocumentStreamInfo } from './documents-namespace.js';
-import type { ListHandle, MapHandle, OrderedMapHandle } from './handles.js';
+import type {
+  DocumentGoneListener,
+  DocumentGoneUnsubscribe,
+  DocumentStatusListener,
+  DocumentStatusUnsubscribe,
+  DocumentWorkStatus,
+} from './document-signals.js';
+import type { ListHandle, MapHandle, OrderedMapHandle } from './handle-types.js';
 
 // The wiring `Document.stream()` runs on: list/create manifests over
 // HTTP, and open a stream's line (join + WS subscribe) returning the
@@ -79,6 +86,50 @@ export class DocumentStream {
     return this._inner.subscribe(cb);
   }
 
+  // Whether this stream's writes are landing, which is a property of its own
+  // line: its snapshot carries its own capacity verdict, its ops are its own,
+  // and its own grant decides whether it takes writes. `subscribe` fires when
+  // `savingCount` or `atCapacity` moves, as it does on the document.
+
+  // True when this stream refuses local writes: `mutate` throws and edit
+  // affordances should be disabled.
+  get readOnly(): boolean {
+    return this._inner.readOnly;
+  }
+
+  // Locally-issued ops on this stream the server has not acked yet. This
+  // stream's own line: `doc.savingCount` is the one that adds the streams up,
+  // and the default stream's inner IS the document, so reading that here would
+  // report every other stream's writes as this one's.
+  get savingCount(): number {
+    return this._inner._ownSavingCount;
+  }
+
+  // True when this stream has stopped accepting changes because it reached the
+  // largest size the platform can keep. The ceiling is per stream, so a
+  // document can hold one full stream and keep taking writes on the rest.
+  get atCapacity(): boolean {
+    return this._inner.atCapacity;
+  }
+
+  // The latest opaque work-status for this stream, or `null` when no slow
+  // server-side work is in flight. Render `message` verbatim.
+  get status(): DocumentWorkStatus | null {
+    return this._inner.status;
+  }
+
+  // Subscribe to this stream's work-status updates. Fires once on attach when
+  // a status is already known.
+  onStatus(cb: DocumentStatusListener): DocumentStatusUnsubscribe {
+    return this._inner.onStatus(cb);
+  }
+
+  // Fires once when the server reports this stream's state evicted. A late
+  // listener fires on registration if the eviction already happened.
+  onGone(cb: DocumentGoneListener): DocumentGoneUnsubscribe {
+    return this._inner.onGone(cb);
+  }
+
   // Per-stream undo/redo: each stream keeps its own local-edit stack
   // (its edits are its own CRDT commits). The doc-level `doc.undo()`
   // covers only the default stream.
@@ -109,18 +160,40 @@ export class DocumentStream {
   }
 
   /** @internal Preview this stream at a historical line seq, or return it
-   * to its live head when `seq` is undefined. Driven by the parent
-   * Document's version preview so a partitioned document previews
-   * consistently across streams. A no-op when the inner has no checkout
-   * fetcher (a guest line, which holds no token to fetch at-version), so
-   * such a stream stays live. */
-  async _previewAt(seq: number | undefined): Promise<void> {
+   * to its live head. Driven by the parent Document's version preview so a
+   * partitioned document previews consistently across streams.
+   * `parentPreviewing` says which of the two a `seq`-less call means: the
+   * parent stepping into a version that records nothing for this line, or the
+   * parent returning to its head. A no-op when the inner has no checkout
+   * fetcher (a guest line, which holds no token to fetch at-version), so such
+   * a stream stays live; a guest line refuses writes anyway. */
+  async _previewAt(seq: number | undefined, parentPreviewing = false): Promise<void> {
     const inner = this._inner;
     if (seq !== undefined && inner._hasCheckoutFetcher()) {
       await inner._checkoutVersion(seq);
-    } else if (inner._isCheckedOut()) {
-      inner.returnToHead();
+      return;
+    }
+    if (seq === undefined && parentPreviewing) {
+      // The preview's checkpoint records no seq for this line, because the
+      // stream did not exist when it was taken. There is no historical state
+      // this stream can honestly show, and returning it to its head shows two
+      // moments at once: the document's past beside this stream's present.
+      // Worse, it would leave the stream taking writes while the document
+      // reports read-only, and those writes land on the live head and outlive
+      // the preview. Hold it read-only for as long as the parent is browsing.
+      inner._setVersionBrowsing(true);
+      return;
     }
+    inner._setVersionBrowsing(false);
+    // Returned whether or not a preview has LANDED on this line, because a
+    // checkout of it can be in flight and unapplied, and the return is what
+    // supersedes that fetch (it bumps the line's own generation before it
+    // looks at anything). Asking whether the line is checked out first is
+    // what lets an in-flight one land after the reader has already gone back
+    // to the head, leaving the stream showing a moment the document left.
+    // Throws on a line with no live head of its own, which the callers
+    // treat the same as any other per-stream failure.
+    inner.returnToHead();
   }
 
   /** @internal Close the stream's own transport + state. Called by the
@@ -129,4 +202,17 @@ export class DocumentStream {
   _close(): void {
     if (this._ownsInner) this._inner.close();
   }
+
+  /** @internal Park the stream's own state alongside the parent's park, so a
+   * stream an app holds across `doc.close()` stops calling it back and refuses
+   * writes the way the parent does. A no-op for the default stream, whose
+   * inner is the parent and is already parking. */
+  _suspend(): void {
+    if (this._ownsInner) this._inner._suspend();
+  }
+
+  /** @internal Pair of `_suspend`, run when the parent resumes. */
+  _resume(): void {
+    if (this._ownsInner) this._inner._resume();
+  }
 }

package/src/document-thumbnail-capture.ts

@@ -1,6 +1,14 @@
-// Document thumbnail auto-capture: screenshots a registered canvas after each
-// local edit settles and uploads it as the thumbnail. One debounce timer, an
-// injected uploader, and a one-shot WebGL diagnostic.
+// Document thumbnail auto-capture: screenshots a registered canvas and uploads
+// it as the thumbnail.
+//
+// The edit trigger debounces a capture after each local commit, so a
+// continuous drag uploads once when it settles. The seed trigger covers a
+// document whose picture is older than its content: an import writes no local
+// commit on the reader's client, and a document nobody has edited yet has none
+// at all. It samples the canvas and uploads the frame it settles on, because
+// the drawn-but-wrong empty editor is on screen from the first frame (measured
+// on the deployed DXF editor: grid at ~0.4s, drawing 0.8s to 4.2s after the
+// records land), so neither blankness nor a fixed delay separates the two.
 
 // A canvas the SDK screenshots for the thumbnail. A getter form is accepted
 // for apps that build or rebuild the canvas lazily.
@@ -18,6 +26,22 @@ export type ThumbnailUploader = (
 // so a continuous drag uploads once when it settles, not once per frame.
 const THUMBNAIL_CAPTURE_DEBOUNCE_MS = 1500;
 
+// Seed watch: sample interval, equal samples that count as settled, give-up
+// bound, and captures per watch. The window is a bound rather than a wait,
+// since the watch ends as soon as it has what it needs; what it sizes is how
+// long a document nothing has drawn yet stays worth sampling. A cold
+// environment (first load of the bundle, first parse, a slow machine) has been
+// measured taking over twenty seconds to draw a 150 KB DXF.
+const SEED_SAMPLE_MS = 500;
+const SEED_WINDOW_MS = 120_000;
+const SEED_SETTLED_SAMPLES = 2;
+const SEED_MAX_CAPTURES = 2;
+
+// Edge of the square the fingerprint downsamples to. Small enough that a
+// sample costs nothing on the render thread, large enough that a drawing does
+// not average away into the background it sits on.
+const FINGERPRINT_EDGE = 64;
+
 // Longest-edge cap (device pixels) for an uploaded thumbnail: a generous
 // product ceiling, an upper bound on the size any Brass surface sensibly
 // paints a thumbnail at with retina headroom. The largest surface (the
@@ -57,6 +81,9 @@ export interface ThumbnailCaptureHost {
   // True when the doc is still attached, re-checked after the async toBlob +
   // upload boundary so a capture in flight when the doc closes does not upload.
   isAttached(): boolean;
+  // Called once an upload lands, so the host can record which version of the
+  // document now has a picture.
+  onCaptured?(): void;
 }
 
 export class ThumbnailCapture {
@@ -70,6 +97,26 @@ export class ThumbnailCapture {
   // offline / test path, where the canvas is tracked but never captured, so
   // apps can register one early without hitting the server in tests.
   private _uploader: ThumbnailUploader | null = null;
+  // Seed-watch state: the interval, the fingerprint the watch will not upload,
+  // the last sample and how many times it has repeated, the sample budget, and
+  // how many frames the watch has captured.
+  private _seedTimer: ReturnType<typeof setInterval> | null = null;
+  private _seedHeld: string | null = null;
+  private _seedLast: string | null = null;
+  private _seedRepeats = 0;
+  private _seedSamplesLeft = 0;
+  private _seedCaptures = 0;
+  // A seed was owed while no canvas was registered, so an app that builds its
+  // renderer after it has the content still gets one.
+  private _seedOwed = false;
+  // Whether this instance has landed an upload. Decides whether an edit may
+  // supersede a seed watch, and nothing else.
+  private _uploaded = false;
+  // A failed upload has been reported, so a document the server keeps
+  // refusing warns once rather than once per edit.
+  private _warnedCaptureFailure = false;
+  // Detaches the page-lifecycle listeners while a canvas is registered.
+  private _detachLifecycle: (() => void) | null = null;
 
   constructor(private readonly host: ThumbnailCaptureHost) {}
 
@@ -80,9 +127,16 @@ export class ThumbnailCapture {
     this._canvas = source;
     // A re-register gets one more chance to surface the missing-buffer warn.
     this._warnedFor = null;
+    this._attachLifecycle();
+    if (this._seedOwed) {
+      this._seedOwed = false;
+      this.armSeed();
+    }
     return () => {
       if (this._canvas === source) {
         this._canvas = null;
+        this._detachLifecycle?.();
+        this._detachLifecycle = null;
         this.cancel();
       }
     };
@@ -96,6 +150,16 @@ export class ThumbnailCapture {
   // edits produces ONE upload when it settles.
   schedule(): void {
     if (this._canvas === null) return;
+    // An edit supersedes a seed watch once the document HAS a picture: the
+    // person is drawing, so the debounce owns it from here and a second upload
+    // of the same moment costs a second snapshot seal. Until then the watch
+    // runs on, because an edit is often the reader's last act before they
+    // leave, and cancelling on it hands the document's only chance at a
+    // picture to a debounce that has to outlive the tab.
+    if (this._uploaded) {
+      this._stopSeed();
+      this._seedOwed = false;
+    }
     if (this._timer !== null) clearTimeout(this._timer);
     this._timer = setTimeout(() => {
       this._timer = null;
@@ -103,20 +167,188 @@ export class ThumbnailCapture {
     }, THUMBNAIL_CAPTURE_DEBOUNCE_MS);
   }
 
+  // Called when the document's picture is older than its content: at open, and
+  // again whenever content arrives with no local commit behind it. Arming a
+  // running watch refreshes its budget, so a burst of arriving ops is one
+  // watch that outlives the burst.
+  armSeed(): void {
+    const el = this._resolveCanvas();
+    if (el === null) {
+      this._seedOwed = true;
+      return;
+    }
+    this._seedSamplesLeft = Math.ceil(SEED_WINDOW_MS / SEED_SAMPLE_MS);
+    if (this._seedTimer !== null) return;
+    this._seedHeld = null;
+    this._seedLast = null;
+    this._seedRepeats = 0;
+    this._seedCaptures = 0;
+    this._seedTimer = setInterval(() => this._sampleSeed(), SEED_SAMPLE_MS);
+  }
+
+  // A page going away is a deadline: take the frame now rather than waiting
+  // out a debounce the tab will not survive. `visibilitychange` covers the
+  // tab switch as well, which is the case with room for the upload to finish.
+  private _attachLifecycle(): void {
+    if (this._detachLifecycle !== null) return;
+    if (typeof document === 'undefined' || typeof window === 'undefined') {
+      return;
+    }
+    const onHidden = (): void => {
+      if (document.visibilityState === 'visible') return;
+      this._flushPending();
+    };
+    const onPageHide = (): void => this._flushPending();
+    document.addEventListener('visibilitychange', onHidden);
+    window.addEventListener('pagehide', onPageHide);
+    this._detachLifecycle = () => {
+      document.removeEventListener('visibilitychange', onHidden);
+      window.removeEventListener('pagehide', onPageHide);
+    };
+  }
+
+  private _flushPending(): void {
+    if (this._timer !== null) {
+      clearTimeout(this._timer);
+      this._timer = null;
+      void this._capture();
+      return;
+    }
+    // A watch holding a frame it has not uploaded takes it, for the same
+    // reason its own deadline does: this frame beats no frame.
+    if (
+      this._seedTimer !== null &&
+      this._seedLast !== null &&
+      this._seedLast !== this._seedHeld
+    ) {
+      this._takeSeed(this._seedLast);
+    }
+  }
+
   // Cancel a pending capture (canvas unregistered / suspend / close).
   cancel(): void {
     if (this._timer !== null) {
       clearTimeout(this._timer);
       this._timer = null;
     }
+    this._stopSeed();
+  }
+
+  // Release for good. The page-lifecycle listeners are held on `document` and
+  // `window` rather than on anything the Document owns, so cancelling the
+  // timers does not reach them: without this they outlive every closed
+  // document, each retaining its uploader closure and firing on every tab
+  // switch for the life of the page.
+  destroy(): void {
+    this.cancel();
+    this._detachLifecycle?.();
+    this._detachLifecycle = null;
+    this._canvas = null;
+    this._seedOwed = false;
+  }
+
+  private _stopSeed(): void {
+    if (this._seedTimer !== null) {
+      clearInterval(this._seedTimer);
+      this._seedTimer = null;
+    }
+    this._seedHeld = null;
+    this._seedLast = null;
+    this._seedRepeats = 0;
+  }
+
+  private _sampleSeed(): void {
+    if (!this.host.isCaptureAllowed()) {
+      this._stopSeed();
+      return;
+    }
+    const el = this._resolveCanvas();
+    if (el === null) {
+      this._stopSeed();
+      this._seedOwed = true;
+      return;
+    }
+    const now = this._fingerprint(el);
+    this._seedSamplesLeft -= 1;
+    // A canvas with no layout yet is not a frame, so it neither settles nor
+    // counts against the budget's meaning; the watch just waits for one.
+    if (now === null) {
+      if (this._seedSamplesLeft <= 0) this._stopSeed();
+      return;
+    }
+    if (now !== this._seedHeld) {
+      if (now === this._seedLast) this._seedRepeats += 1;
+      else this._seedRepeats = 0;
+      this._seedLast = now;
+      if (this._seedRepeats >= SEED_SETTLED_SAMPLES - 1) {
+        this._takeSeed(now);
+        return;
+      }
+    }
+    if (this._seedSamplesLeft <= 0) {
+      // Still redrawing at the deadline: the latest frame is a truer picture
+      // of the document than no picture, and a further wait has no end.
+      const moved = this._seedLast !== null && this._seedLast !== this._seedHeld;
+      if (moved) this._takeSeed(this._seedLast!);
+      else this._stopSeed();
+    }
+  }
+
+  // Upload a settled frame. The first one is a picture of the document, or of
+  // the editor about to draw it: an app that mounts its canvas before it has
+  // drawn holds an empty grid for as long as the drawing takes. So the watch
+  // stays on for a second settle, which lands at the same version and
+  // overwrites the first. A third is an app redrawing on its own.
+  private _takeSeed(frame: string): void {
+    this._seedHeld = frame;
+    this._seedRepeats = 0;
+    this._seedCaptures += 1;
+    if (this._seedCaptures >= SEED_MAX_CAPTURES || this._seedSamplesLeft <= 0) {
+      this._stopSeed();
+    }
+    void this._capture();
+  }
+
+  // A cheap perceptual fingerprint: the canvas downsampled into a small square
+  // and folded into a string. It reads through the same front buffer `toBlob`
+  // does, so a canvas the capture would read blank fingerprints blank too and
+  // the watch expires instead of uploading it.
+  private _fingerprint(el: HTMLCanvasElement): string | null {
+    // A canvas the page has not laid out yet (the browser's 1x1 default until
+    // the app sizes it) carries no frame to compare.
+    if (el.width <= 1 || el.height <= 1) return null;
+    try {
+      const off = document.createElement('canvas');
+      off.width = FINGERPRINT_EDGE;
+      off.height = FINGERPRINT_EDGE;
+      const ctx = off.getContext('2d', { willReadFrequently: true });
+      if (!ctx) return 'unreadable';
+      ctx.drawImage(el, 0, 0, FINGERPRINT_EDGE, FINGERPRINT_EDGE);
+      const { data } = ctx.getImageData(0, 0, FINGERPRINT_EDGE, FINGERPRINT_EDGE);
+      let h1 = 0x811c9dc5;
+      let h2 = 0x01000193;
+      for (let i = 0; i < data.length; i += 4) {
+        const px = (data[i]! << 24) | (data[i + 1]! << 16) | (data[i + 2]! << 8) | data[i + 3]!;
+        h1 = Math.imul(h1 ^ px, 0x01000193);
+        h2 = Math.imul(h2 + px, 0x85ebca6b) ^ (h2 >>> 13);
+      }
+      return `${h1 >>> 0}:${h2 >>> 0}`;
+    } catch {
+      // A tainted canvas throws here exactly as it would in the capture, so
+      // treating every read as the same value expires the watch.
+      return 'unreadable';
+    }
+  }
+
+  private _resolveCanvas(): HTMLCanvasElement | null {
+    if (this._canvas === null) return null;
+    return typeof this._canvas === 'function' ? this._canvas() : this._canvas;
   }
 
   private async _capture(): Promise<void> {
     if (!this.host.isCaptureAllowed()) return;
-    if (this._canvas === null) return;
     if (this._uploader === null) return;
-    const el =
-      typeof this._canvas === 'function' ? this._canvas() : this._canvas;
+    const el = this._resolveCanvas();
     if (!el) return;
     this._warnIfWebglContextWillProduceBlankCapture(el);
     try {
@@ -134,9 +366,21 @@ export class ThumbnailCapture {
       });
       if (!this.host.isAttached()) return;
       await this._uploader(image, target.width, target.height);
-    } catch {
-      // Best-effort: rate-limit rejection, lack of write access, or a
-      // transient failure is swallowed; the next local edit reschedules.
+      this._uploaded = true;
+      this.host.onCaptured?.();
+    } catch (err) {
+      // Best-effort: a rate-limit rejection, a lack of write access, or a
+      // transient failure leaves the document on its last picture, and the
+      // next edit or arrival reschedules. Reported once, because the refusals
+      // that persist (no write access, an oversized image) are otherwise
+      // indistinguishable from a capture that never ran.
+      if (!this._warnedCaptureFailure) {
+        this._warnedCaptureFailure = true;
+        console.warn(
+          '@brass-build/client: uploading the document thumbnail failed: ' +
+            (err instanceof Error ? err.message : String(err)),
+        );
+      }
     }
   }