@brass-build/client 0.1.0 → 0.2.0

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/documents-namespace.ts

@@ -1,7 +1,7 @@
 // SDK surface: `Brass.documents.*`. The metadata surface: get /
-// thumbnails / branches. The editable surface (snapshot + ops +
-// mutate) is the `Document` runtime class via `Brass.openDocumentById`
-// / `Brass.createDocument`. Access-granting is hosted-only (the share
+// thumbnails. The editable surface (snapshot + ops + mutate) is the
+// `Document` runtime class via `Brass.openDocumentById` /
+// `Brass.createDocument`. Access-granting is hosted-only (the share
 // dialog), not a programmatic method here.
 
 import type { Document } from './documents.js';
@@ -305,6 +305,11 @@ export function createDocumentsNamespace(
   opts: DocumentsFactoryOptions,
 ): DocumentsNamespace & DocumentsInternalNamespace {
   const apiFetch = createApiFetch(opts);
+  // Identifies THIS client to the import claim, so two tabs of one app
+  // signed in as one user are two claimants and only one of them imports.
+  // Minted once per namespace, so re-claiming from this client refreshes
+  // its own claim rather than taking a second one.
+  const importClientId = randomToken();
 
   return {
     get(docId) {
@@ -452,12 +457,14 @@ export function createDocumentsNamespace(
       return apiFetch<ImportClaimResponse>({
         method: 'POST',
         path: `/documents/${encodeURIComponent(docId)}/import-claim`,
+        body: { client_id: importClientId },
       });
     },
     completeImport(docId) {
       return apiFetch<{ schema_ref: { app_id: string; schema_hash: string } }>({
         method: 'POST',
         path: `/documents/${encodeURIComponent(docId)}/import-complete`,
+        body: { client_id: importClientId },
       });
     },
     async getThumbnail(docId, options) {
@@ -477,6 +484,14 @@ export function createDocumentsNamespace(
   };
 }
 
+function randomToken(): string {
+  const g = globalThis as { crypto?: { randomUUID?: () => string } };
+  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
+  let s = '';
+  for (let i = 0; i < 32; i++) s += Math.floor(Math.random() * 16).toString(16);
+  return s;
+}
+
 // Reads `SetThumbnailInput.image` into base64 plus a resolved MIME
 // type. A `Blob` carries its own `type` (canvas `toBlob` sets it);
 // raw `ArrayBuffer` / `Uint8Array` bytes need an explicit