@brass-build/client 0.1.0

package/src/document-signals.ts

@@ -0,0 +1,234 @@
+// Document lifecycle signals: server-pushed listener-fanout surfaces a
+// Document exposes, separate from the CRDT state it wraps. Pure subscriber
+// registries with a load-bearing emit discipline:
+//
+//   - `GoneSignal`       fire-once-then-cache (a doc is evicted once)
+//   - `WorkStatusSignal` latest-retained, re-emit per phase
+//   - `DriveStatusSignal` latest-retained, fire-on-attach, dedup-on-emit
+
+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
+// 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.
+export type DocumentGoneReason = 'deleted' | 'moved';
+
+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
+// 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.
+export interface DocumentWorkStatus {
+  message: string;
+  progress?: number;
+  pending: boolean;
+  // Whether this work locks editing. Inbound work (hydration, extraction)
+  // replaces content, so the doc is read-only until it lands
+  // (`blocking: true`); an outbound push leaves content untouched, so editing
+  // stays open (`blocking: false`). Optional; absence is treated as blocking.
+  // `doc.readOnly` already folds this in, so apps rarely read it directly.
+  blocking?: boolean;
+}
+
+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
+// 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'
+  | 'diverged';
+
+// Which way the mirror flows. `two_way` links round-trip; `import_only` links
+// are one-directional (edits stay in Brass, no publish-back path). An app
+// 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
+// server-authored (`label` / `detail`, rendered verbatim); the app branches
+// only on `state` / `canPush` to decide whether to show an affordance.
+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.
+  driveType: string;
+  // The drive's user-facing name, server-authored and rendered verbatim.
+  driveName: string;
+  // The divergence state. `ahead` / `diverged` mean unpublished local edits.
+  state: DocumentDriveTrackingState;
+  // True when publishing would do something (local edits to save back and the
+  // link is not broken): the cue to surface a "Publish" affordance.
+  canPush: boolean;
+  // Server-authored short pill text (`null` when nothing worth surfacing).
+  label: string | null;
+  // Server-authored detail sentence for a tooltip (`null` when none).
+  detail: string | null;
+  // The link's backing connection was removed; the doc can no longer sync. The
+  // app surfaces a terminal "reconnect needed" state.
+  broken: boolean;
+  // True when a push overwrites the source wholesale instead of 3-way merging
+  // (the file-roundtrip path), so an app can warn that the source's newer
+  // version will be replaced, not merged.
+  pushReplacesRemote: boolean;
+  // Whether the link round-trips (`two_way`) or only imports (`import_only`).
+  // On `import_only`, `canPush` is always false; an app surfaces the class so
+  // a one-way import doesn't read as a live two-way mirror.
+  mirrorDirection: DriveMirrorDirection;
+  // Current external head ref, empty when the adapter could not produce one.
+  ref: string;
+  // ISO timestamp the ref was last refreshed, empty on a fresh stub.
+  refUpdatedAt: string;
+  // The source item's display name, for a "linked to <name>" tooltip.
+  itemName: string;
+  // Deep link to the source, so a link indicator can open it.
+  itemUrl: string;
+  // True while a push is in flight (submitted, running server-side, not yet
+  // confirmed). A push is asynchronous, so `state` stays `ahead` until it
+  // lands; an indicator reads this to hold a "Publishing..." state and hide
+  // the Publish affordance rather than re-deriving it. `detail` carries the
+  // server-authored progress line while it is `true`.
+  publishing: boolean;
+}
+
+export type DocumentDriveStatusListener = (
+  status: DocumentDriveStatus,
+) => void;
+export type DocumentDriveStatusUnsubscribe = () => void;
+
+// 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
+// Document calls. The shared emit discipline (swallow-and-log, fire-on-attach
+// in a microtask, retain the last value) lives in the primitive; the class
+// picks the options.
+
+// Fire-once-then-cache signal for `doc_gone`: listeners registered AFTER the
+// event still fire exactly once on attach (the `Promise`-resolution pattern),
+// so callback-wiring after the WS frame may have landed has no race. `mark` is
+// idempotent (both `doc:<id>` and `presence:doc:<id>` fan out a frame, so the
+// one-shot collapses them to a single listener fire).
+export class GoneSignal {
+  private readonly _emitter = createEmitter<DocumentGoneReason>({
+    fireOnAttach: true,
+    retain: 'oneShot',
+    onError: (err) => {
+      // A consumer throw must not strand the others or break the WS router.
+      console.error('[Brass] onGone listener threw:', err);
+    },
+  });
+
+  get reason(): DocumentGoneReason | null {
+    return this._emitter.retained ?? null;
+  }
+
+  on(cb: DocumentGoneListener): DocumentGoneUnsubscribe {
+    return this._emitter.on(cb);
+  }
+
+  mark(reason: DocumentGoneReason): void {
+    this._emitter.emit(reason);
+  }
+
+  // Drop app-side listeners (suspend / close). The cached reason is NOT
+  // cleared: a `_markGone` that already fired stays terminal across a suspend.
+  clearListeners(): void {
+    this._emitter.clear();
+  }
+}
+
+// Latest-retained, re-emit-per-phase signal for `doc_status`. Not one-shot:
+// phases arrive repeatedly until terminal (`pending: false`), and the latest
+// is retained so a late subscriber still sees the final state.
+export class WorkStatusSignal {
+  private readonly _emitter = createEmitter<DocumentWorkStatus>({
+    fireOnAttach: true,
+    retain: 'latest',
+    onError: (err) => {
+      console.error('[Brass] onStatus listener threw:', err);
+    },
+  });
+
+  get status(): DocumentWorkStatus | null {
+    return this._emitter.retained ?? null;
+  }
+
+  on(cb: DocumentStatusListener): DocumentStatusUnsubscribe {
+    return this._emitter.on(cb);
+  }
+
+  emit(status: DocumentWorkStatus): void {
+    this._emitter.emit(status);
+  }
+
+  clearListeners(): void {
+    this._emitter.clear();
+  }
+}
+
+// Latest-retained, fire-on-attach signal for `doc_drive_status`. Like
+// `WorkStatusSignal`, but `emit` short-circuits when the new status
+// deep-equals the retained one: drive status fans out on *every* METADATA row
+// change (rename, thumbnail, edit), so the equality gate keeps `onDriveStatus`
+// from re-firing when the tracking state didn't move.
+export class DriveStatusSignal {
+  private readonly _emitter = createEmitter<DocumentDriveStatus>({
+    fireOnAttach: true,
+    retain: 'latest',
+    equals: driveStatusEqual,
+    onError: (err) => {
+      console.error('[Brass] onDriveStatus listener threw:', err);
+    },
+  });
+
+  get status(): DocumentDriveStatus | null {
+    return this._emitter.retained ?? null;
+  }
+
+  on(cb: DocumentDriveStatusListener): DocumentDriveStatusUnsubscribe {
+    return this._emitter.on(cb);
+  }
+
+  emit(status: DocumentDriveStatus): void {
+    this._emitter.emit(status);
+  }
+
+  clearListeners(): void {
+    this._emitter.clear();
+  }
+}
+
+// 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.
+function driveStatusEqual(
+  a: DocumentDriveStatus,
+  b: DocumentDriveStatus,
+): boolean {
+  return (
+    a.driveType === b.driveType &&
+    a.driveName === b.driveName &&
+    a.state === b.state &&
+    a.canPush === b.canPush &&
+    a.label === b.label &&
+    a.detail === b.detail &&
+    a.broken === b.broken &&
+    a.pushReplacesRemote === b.pushReplacesRemote &&
+    a.mirrorDirection === b.mirrorDirection &&
+    a.ref === b.ref &&
+    a.refUpdatedAt === b.refUpdatedAt &&
+    a.publishing === b.publishing &&
+    a.itemName === b.itemName &&
+    a.itemUrl === b.itemUrl
+  );
+}

package/src/document-streams.ts

@@ -0,0 +1,132 @@
+// Per-stream scope of a Document. A document is a container of streams:
+// named, independently-loadable CRDT units. `doc.stream(name)` resolves
+// one and returns this wrapper; only the streams an app touches are
+// downloaded, imported, and subscribed, so open cost scales with use,
+// not with the whole document.
+//
+// Each non-default stream is backed by its own internal Document wired
+// to the stream's line (its own snapshot + op channel); the wrapper
+// exposes the per-stream subset of the Document surface. The `default`
+// stream wraps the parent Document itself, so `doc.stream('default')`
+// and the doc-level handles read the same state.
+
+import type {
+  Document,
+  DocumentMutator,
+  DocumentSubscriber,
+  DocumentUnsubscribe,
+  EntityProxy,
+} from './documents.js';
+import type { DocumentStreamInfo } from './documents-namespace.js';
+import type { ListHandle, MapHandle, OrderedMapHandle } from './handles.js';
+
+// The wiring `Document.stream()` runs on: list/create manifests over
+// HTTP, and open a stream's line (join + WS subscribe) returning the
+// internal Document that holds its state. Installed by the SDK open
+// factory; absent on offline / test docs, where stream methods throw
+// with a clear message.
+export interface StreamRuntime {
+  list(): Promise<DocumentStreamInfo[]>;
+  create(name: string): Promise<DocumentStreamInfo>;
+  openLine(lineId: string): Promise<Document>;
+}
+
+export class DocumentStream {
+  // The stream's name within the document ('default' for the document's
+  // own default state).
+  readonly name: string;
+  /** @internal The Document holding this stream's state. For a
+   *  non-default stream that is its own line's Document; for `default` it
+   *  is the parent itself, which is why `_ownsInner` gates the close. */
+  readonly _inner: Document;
+  // True when this wrapper owns its inner Document (a non-default
+  // stream): closing the parent closes it. The default stream's inner IS
+  // the parent, which owns its own lifecycle.
+  private readonly _ownsInner: boolean;
+
+  /** @internal */
+  constructor(name: string, inner: Document, ownsInner: boolean) {
+    this.name = name;
+    this._inner = inner;
+    this._ownsInner = ownsInner;
+  }
+
+  // Typed container handles, scoped to this stream. Same surface and
+  // semantics as the doc-level `doc.map` / `doc.list` / `doc.orderedMap`.
+  map<T = unknown>(key: string): MapHandle<T> {
+    return this._inner.map<T>(key);
+  }
+
+  list<T = unknown>(key: string): ListHandle<T> {
+    return this._inner.list<T>(key);
+  }
+
+  orderedMap<T = unknown>(mapKey: string, orderKey: string): OrderedMapHandle<T> {
+    return this._inner.orderedMap<T>(mapKey, orderKey);
+  }
+
+  mutate<E extends object = EntityProxy>(
+    fn: (d: DocumentMutator<E>) => void,
+  ): void {
+    this._inner.mutate<E>(fn);
+  }
+
+  toJSON(): Record<string, unknown> {
+    return this._inner.toJSON();
+  }
+
+  subscribe(cb: DocumentSubscriber): DocumentUnsubscribe {
+    return this._inner.subscribe(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.
+  undo(): boolean {
+    return this._inner.undo();
+  }
+
+  redo(): boolean {
+    return this._inner.redo();
+  }
+
+  // Seal the stream's open undo group, so the next local edit starts a
+  // fresh undo step. Local and synchronous (no server call). Call it
+  // when a user operation completes: commits group into one step until
+  // sealed (the same same-stroke collapsing the doc-level undo has), so
+  // an app that never seals gets one giant step per session. The
+  // cross-stream operation recipe in `docs/streams.md` is built on this.
+  sealUndoStep(): void {
+    this._inner._sealUndoStep();
+  }
+
+  /** @internal The stream's live head seq (advanced by its own op channel),
+   *  or `null` before the transport resolves it. Internal for the same
+   *  reason the document's is, and a stream has even less use for one: it
+   *  carries no checkpoint machinery to anchor. */
+  get currentSeq(): number | null {
+    return this._inner.currentSeq;
+  }
+
+  /** @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> {
+    const inner = this._inner;
+    if (seq !== undefined && inner._hasCheckoutFetcher()) {
+      await inner._checkoutVersion(seq);
+    } else if (inner._isCheckedOut()) {
+      inner.returnToHead();
+    }
+  }
+
+  /** @internal Close the stream's own transport + state. Called by the
+   * parent Document's close; a no-op for the default stream, whose inner
+   * is the parent itself. */
+  _close(): void {
+    if (this._ownsInner) this._inner.close();
+  }
+}

package/src/document-thumbnail-capture.ts

@@ -0,0 +1,191 @@
+// 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.
+
+// A canvas the SDK screenshots for the thumbnail. A getter form is accepted
+// for apps that build or rebuild the canvas lazily.
+export type CanvasSource =
+  | HTMLCanvasElement
+  | (() => HTMLCanvasElement | null);
+
+export type ThumbnailUploader = (
+  image: Blob,
+  width: number,
+  height: number,
+) => Promise<void>;
+
+// Debounce window: a screenshot is taken this long after the last local edit,
+// so a continuous drag uploads once when it settles, not once per frame.
+const THUMBNAIL_CAPTURE_DEBOUNCE_MS = 1500;
+
+// 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
+// version-history timeline, ~200px) clears 2x DPR with room, while this still
+// sheds the multi-megapixel frames a full-resolution 3D / map / CAD canvas
+// would upload. Standalone (not derived from a CSS size) because the display
+// sizes live in the frontend and this is a published SDK; a smaller
+// per-surface derivative is a server-side concern.
+const MAX_THUMBNAIL_CAPTURE_EDGE = 512;
+
+// Cap the longest edge to `maxEdge`, preserving aspect ratio, never upscaling:
+// a canvas within the cap is uploaded at native size (`scaled: false`), so the
+// common small-canvas case skips the offscreen redraw. The returned dimensions
+// are what the uploader reports, so they stay matched to the bytes.
+export function fitWithinMaxEdge(
+  width: number,
+  height: number,
+  maxEdge: number,
+): { width: number; height: number; scaled: boolean } {
+  const longest = Math.max(width, height);
+  if (!Number.isFinite(longest) || longest <= 0 || longest <= maxEdge) {
+    return { width, height, scaled: false };
+  }
+  const ratio = maxEdge / longest;
+  return {
+    width: Math.max(1, Math.round(width * ratio)),
+    height: Math.max(1, Math.round(height * ratio)),
+    scaled: true,
+  };
+}
+
+export interface ThumbnailCaptureHost {
+  // True when a capture may run: the doc is live (not closed / suspended) and
+  // showing head (not a historical checkout), so a viewer or checkout never
+  // re-uploads a frame.
+  isCaptureAllowed(): boolean;
+  // 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;
+}
+
+export class ThumbnailCapture {
+  // Canvas registered via `useCanvas`; `null` for the common non-canvas app.
+  private _canvas: CanvasSource | null = null;
+  private _timer: ReturnType<typeof setTimeout> | null = null;
+  // The canvas already warned about `preserveDrawingBuffer: false`, so the
+  // warn fires once per canvas; reset on `useCanvas` for a re-register.
+  private _warnedFor: HTMLCanvasElement | null = null;
+  // Injected upload hook (the Document owns no HTTP client). `null` on the
+  // 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;
+
+  constructor(private readonly host: ThumbnailCaptureHost) {}
+
+  // Register a canvas (element or lazy getter) to screenshot as the thumbnail.
+  // Returns an unregister handle; re-registering replaces. The caller
+  // (Document) arms its Loro subscriber so local commits reach `schedule()`.
+  useCanvas(source: CanvasSource): () => void {
+    this._canvas = source;
+    // A re-register gets one more chance to surface the missing-buffer warn.
+    this._warnedFor = null;
+    return () => {
+      if (this._canvas === source) {
+        this._canvas = null;
+        this.cancel();
+      }
+    };
+  }
+
+  setUploader(uploader: ThumbnailUploader | null): void {
+    this._uploader = uploader;
+  }
+
+  // Called from the Document's local-commit dispatch; debounces so a burst of
+  // edits produces ONE upload when it settles.
+  schedule(): void {
+    if (this._canvas === null) return;
+    if (this._timer !== null) clearTimeout(this._timer);
+    this._timer = setTimeout(() => {
+      this._timer = null;
+      void this._capture();
+    }, THUMBNAIL_CAPTURE_DEBOUNCE_MS);
+  }
+
+  // Cancel a pending capture (canvas unregistered / suspend / close).
+  cancel(): void {
+    if (this._timer !== null) {
+      clearTimeout(this._timer);
+      this._timer = null;
+    }
+  }
+
+  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;
+    if (!el) return;
+    this._warnIfWebglContextWillProduceBlankCapture(el);
+    try {
+      const target = fitWithinMaxEdge(
+        el.width,
+        el.height,
+        MAX_THUMBNAIL_CAPTURE_EDGE,
+      );
+      const source = target.scaled ? this._downscale(el, target) : el;
+      const image = await new Promise<Blob>((resolve, reject) => {
+        source.toBlob((blob) => {
+          if (blob) resolve(blob);
+          else reject(new Error('thumbnail capture: canvas produced no image'));
+        }, 'image/png');
+      });
+      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.
+    }
+  }
+
+  // Redraw an oversized canvas into an offscreen 2D canvas at the capped
+  // dimensions. `drawImage` reads the source's front buffer, so the WebGL
+  // `preserveDrawingBuffer` caveat above applies here too. If a 2D context
+  // can't be acquired, fall back to the full-resolution source: one oversized
+  // upload beats a missing thumbnail.
+  private _downscale(
+    el: HTMLCanvasElement,
+    target: { width: number; height: number },
+  ): HTMLCanvasElement {
+    const off = document.createElement('canvas');
+    off.width = target.width;
+    off.height = target.height;
+    const ctx = off.getContext('2d');
+    if (!ctx) return el;
+    ctx.drawImage(el, 0, 0, target.width, target.height);
+    return off;
+  }
+
+  // Warn once per canvas if its WebGL context lacks
+  // `preserveDrawingBuffer: true`: without it `toBlob` reads back a blank
+  // frame (the spec lets the browser discard the drawing buffer after
+  // compositing), so the upload silently stores a blank PNG with no
+  // diagnostic. Harmless on 2D / SVG canvases (no WebGL context to inspect).
+  private _warnIfWebglContextWillProduceBlankCapture(
+    el: HTMLCanvasElement,
+  ): void {
+    if (this._warnedFor === el) return;
+    if (typeof el.getContext !== 'function') return;
+    let gl: WebGLRenderingContext | WebGL2RenderingContext | null = null;
+    try {
+      gl =
+        (el.getContext('webgl2') as WebGL2RenderingContext | null) ??
+        (el.getContext('webgl') as WebGLRenderingContext | null);
+    } catch {
+      return;
+    }
+    if (!gl) return;
+    const attributes = gl.getContextAttributes();
+    if (attributes && attributes.preserveDrawingBuffer === false) {
+      this._warnedFor = el;
+      console.warn(
+        '@brass-build/client: useCanvas captured a blank thumbnail because ' +
+          'the WebGL context was created with preserveDrawingBuffer: false. ' +
+          'Pass preserveDrawingBuffer: true when creating the WebGL context ' +
+          '(e.g., new THREE.WebGLRenderer({ preserveDrawingBuffer: true })).',
+      );
+    }
+  }
+}