@brass-build/client 0.2.0 → 0.4.0

package/src/document-checkpoints.ts

@@ -29,6 +29,9 @@ export interface CheckpointSchedulerHost {
   currentSeq(): number | null;
   // Seal the current undo step. Safe to call when undo is absent.
   sealUndoStep(): void;
+  // Resolve `true` once every op this client has committed locally has been
+  // acked; `false` when the document went, or the acks stopped arriving.
+  whenLocalOpsSaved(): Promise<boolean>;
 }
 
 export class CheckpointScheduler {
@@ -65,6 +68,26 @@ export class CheckpointScheduler {
     // arriving during the await start a fresh undo step rather than
     // folding into the pre-checkpoint one.
     this.host.sealUndoStep();
+    // The anchor is a SERVER seq, and an op the app just committed holds one
+    // only once it is acked, so a checkpoint sealed with writes outstanding
+    // sits below the work the caller is saving: an app that writes and then
+    // saves a version (the file importer's one-undo-step seal is this shape)
+    // marks a point its own edits are missing from, and restoring it loses
+    // them. Waiting for the acks is what makes the marker describe the state
+    // the caller has.
+    const saved = await this.host.whenLocalOpsSaved();
+    if (!this.host.isAttached()) {
+      throw new Error('Document is closed');
+    }
+    // Sealing anyway is the failure this wait exists to prevent, and it fails
+    // quietly: the marker looks like a saved version and restores to a state
+    // missing the work the caller asked to save. Refusing hands the app a
+    // state it can act on instead.
+    if (!saved) {
+      throw new Error(
+        'createCheckpoint: the document has changes that are not saved yet',
+      );
+    }
     const result = await this._creator();
     // Record the seq so a pending auto-checkpoint at the same version
     // skips its fire. The server Put is unconditional (last-write-wins),
@@ -116,6 +139,13 @@ export class CheckpointScheduler {
   private async _fireAuto(): Promise<void> {
     if (!this.host.isAutoAllowed()) return;
     if (this._creator === null) return;
+    // Same anchor rule as `create`. The debounce usually outlasts the acks,
+    // so this ordinarily resolves at once; what it covers is a burst whose
+    // last ops are still draining when the timer fires. Best-effort here, so
+    // a seal that cannot confirm the writes skips and the next local edit
+    // reschedules it.
+    if (!(await this.host.whenLocalOpsSaved())) return;
+    if (!this.host.isAutoAllowed()) return;
     const seq = this.host.currentSeq();
     if (seq === null) return;
     // Already checkpointed at this exact version (manual seal a moment

package/src/document-contents.ts

@@ -0,0 +1,104 @@
+// A whole document read out as plain JSON, from the bytes a join delivers.
+//
+// The caller is a detached reader: `@brass-build/cli`, which fetches a
+// document's snapshot and tail and wants what it holds, with no session, no
+// socket, and no app around it. That read is the store's own business, so it
+// lives here beside `flattenPagedLookup` rather than being reassembled by
+// whoever needs it. A second implementation of the paging precedence is the
+// bug this module exists to prevent.
+//
+// The whole document, not a window over it. A reader building against an
+// example file needs the record TYPES the file carries, and a prefix of a
+// store does not carry them: an import arrives grouped by entity type, so the
+// first records of a large file are a couple of types out of hundreds. The
+// caller holding the document locally can answer any question about it; a
+// caller holding a slice can only answer the ones the slice happens to cover.
+//
+// Nothing here is bounded, and that is deliberate: this runs on a developer's
+// machine, which is the only place a large document fits. The platform's own
+// join refuses rather than serving a partial document, so the bytes handed in
+// are complete or they are not served at all.
+
+// Through the runtime seam, not from `loro-crdt` directly: which engine build
+// this package carries is decided by the two `wasm-runtime` halves, and a
+// third module naming the dependency is an import the browser substitution
+// does not reach. The reader is synchronous by design, so it takes the engine
+// and not `ensureWasmReady`: its caller holds the bytes already, which means
+// something upstream has opened a document and readied the runtime.
+import { LoroDoc } from './wasm-runtime.js';
+import {
+  META_KEY,
+  flattenPagedLookup,
+  isPagedMarker,
+  pagedRootKey,
+} from './record-paging.js';
+
+/** A document's root containers, each read whole, keyed as the document
+ *  keys them. A map root reads back as the object an app sees through
+ *  `doc.map(key)`, a list as its items, a text root as its string. The JSON
+ *  types tell them apart, so nothing here restates the container kind. */
+export type DocumentContents = Record<string, unknown>;
+
+/**
+ * Materialise a document from a join's bytes and read every root.
+ *
+ * `snapshot` is the compacted state (null for a document that has never been
+ * compacted) and `ops` the tail that follows it, in seq order. Both are the
+ * shapes `GET /documents/{docId}?include=snapshot` delivers, once its inline
+ * and presigned entries are resolved to bytes.
+ */
+export function readDocumentContents(
+  snapshot: Uint8Array | null,
+  ops: readonly Uint8Array[],
+): DocumentContents {
+  const doc = new LoroDoc();
+  if (snapshot !== null) doc.import(snapshot);
+  for (const op of ops) doc.import(op);
+  return readRoots(doc);
+}
+
+// A root container id is `cid:root-<name>:<Type>`; the name arrives as the
+// key, so only the type suffix is read.
+function containerType(containerId: string): string {
+  return containerId.slice(containerId.lastIndexOf(':') + 1);
+}
+
+function readRoots(doc: LoroDoc): DocumentContents {
+  const contents: DocumentContents = {};
+  // Root ids only, so the enumeration converts nothing: each root below
+  // decides its own read.
+  for (const [key, containerId] of Object.entries(doc.getShallowValue())) {
+    switch (containerType(String(containerId))) {
+      case 'Map':
+        contents[key] = readMapRoot(doc, key);
+        break;
+      case 'List':
+        contents[key] = doc.getList(key).toJSON();
+        break;
+      case 'MovableList':
+        contents[key] = doc.getMovableList(key).toJSON();
+        break;
+      case 'Text':
+        contents[key] = doc.getText(key).toString();
+        break;
+      default:
+        // A container type this build does not read. Named with a null so
+        // the root's existence survives the read rather than the document
+        // appearing not to have it.
+        contents[key] = null;
+    }
+  }
+  return contents;
+}
+
+function readMapRoot(doc: LoroDoc, key: string): Record<string, unknown> {
+  // Whether the store is paged is read from the root's own `meta` key, which
+  // is authoritative: in an unpaged store every key is a record key, a
+  // reserved-looking one included, because nothing refused it before the
+  // store was written.
+  const paged = isPagedMarker(doc.getMap(META_KEY).get(pagedRootKey(key)));
+  // One bulk conversion, then the flatten: a per-container walk of a large
+  // map costs work that grows with the map's own container count.
+  const lookup = doc.getMap(key).toJSON() as Record<string, unknown>;
+  return flattenPagedLookup(lookup, paged);
+}

package/src/document-signals.ts

@@ -45,8 +45,8 @@ export type DocumentStatusUnsubscribe = () => void;
 export type DocumentDriveTrackingState =
   | 'unhydrated'
   | 'synced'
-  | 'ahead'
   | 'behind'
+  | 'ahead'
   | 'diverged';
 
 // Which way the mirror flows. `two_way` links round-trip; `import_only` links
@@ -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

@@ -16,6 +16,7 @@ import type {
   DocumentSubscriber,
   DocumentUnsubscribe,
   EntityProxy,
+  RootKind,
 } from './documents.js';
 import type { DocumentStreamInfo } from './documents-namespace.js';
 import type {
@@ -25,7 +26,12 @@ import type {
   DocumentStatusUnsubscribe,
   DocumentWorkStatus,
 } from './document-signals.js';
-import type { ListHandle, MapHandle, OrderedMapHandle } from './handle-types.js';
+import type {
+  ListHandle,
+  MapHandle,
+  OrderedMapHandle,
+  TextHandle,
+} 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
@@ -78,6 +84,14 @@ export class DocumentStream {
     this._inner.mutate<E>(fn);
   }
 
+  roots(): Record<string, RootKind> {
+    return this._inner.roots();
+  }
+
+  text(key: string): TextHandle {
+    return this._inner.text(key);
+  }
+
   toJSON(): Record<string, unknown> {
     return this._inner.toJSON();
   }

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)),
+        );
+      }
     }
   }