@brass-build/client 0.2.0 → 0.3.0

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

package/src/documents-namespace.ts

@@ -94,10 +94,9 @@ export interface DocumentRecord extends DocumentSummary {
   // `organization_id`, so the hierarchy above the document can evolve
   // (folders / teams) without a client change.
   location_label: string | null;
-  // Whether someone can produce a file from this document: a platform
-  // codec, an opaque blob's stored bytes, or an app installed on the
-  // document's organization that declares an output for it. The server
-  // resolves it, so a newly exportable format needs no client change.
+  // Whether anything can produce a file from this document. The server
+  // resolves who would write it, so a newly exportable format needs no
+  // client change.
   downloadable: boolean;
 }
 
@@ -177,6 +176,11 @@ export interface DocumentCheckpoint {
 // changed" can read it). Omitted means no message.
 export interface PushToDriveInput {
   message?: string;
+  // The file's bytes, for a document the platform has no writer for: its
+  // own app serializes it. The SDK supplies these from the registered
+  // serializer, so nothing an app calls has to.
+  /** @internal */
+  bytes?: Uint8Array;
 }
 
 // Outcome of a successful push.
@@ -278,11 +282,11 @@ export interface DocumentsInternalNamespace {
     doc: Document,
     input?: PushToDriveInput,
   ): Promise<PushToDriveResult>;
-  // Fetch a presigned GET + descriptor for the original file behind an
-  // opaque-blob document, so an app that knows the format can download
-  // and parse it in-browser. Rejects with a `BrassError` when the doc is
-  // not a stored opaque blob or the caller cannot reach it (404). The
-  // per-doc instance method `doc.sourceBlob()` routes through this.
+  // Fetch a presigned GET + descriptor for the file a document was uploaded
+  // as, so an app that knows the format can download and parse it
+  // in-browser. Rejects with a `BrassError` when the document holds no such
+  // file or the caller cannot reach it (404). The per-doc instance method
+  // `doc.sourceBlob()` routes through this.
   sourceBlob(doc: Document): Promise<DocumentSourceBlob>;
   // The import-claim protocol behind `Brass.registerImporter`. The SDK
   // (never the app) claims the right to run the import of a stored
@@ -432,8 +436,14 @@ export function createDocumentsNamespace(
           { status: 400 },
         );
       }
-      const body: { message?: string } = {};
+      const body: {
+        message?: string;
+        content_base64?: string;
+      } = {};
       if (input?.message !== undefined) body.message = input.message;
+      if (input?.bytes !== undefined) {
+        body.content_base64 = bytesToBase64(input.bytes);
+      }
       const res = await apiFetch<PushToDriveResult>({
         method: 'POST',
         path: `/documents/${encodeURIComponent(docId)}/drive-sync/push`,