@brass-build/client 0.1.0

package/src/tail-ops.ts

@@ -0,0 +1,63 @@
+// Tail ops arrive in one of two shapes and are used in only one.
+//
+// An op that fit its durable row carries its bytes inline. One that
+// spilled to storage carries a short-lived signed URL instead, because a
+// join response holding several megabytes of base64 is a response the
+// server cannot build. Both mean the same thing to a reader: bytes to
+// apply, in seq order.
+//
+// Resolving at the parse boundary is what keeps that difference from
+// spreading. Every path that folds a tail in (a cold open, a reconnect,
+// a version preview) then works on inline blobs exactly as before, and
+// none of them has to be async to do it.
+
+import { BrassError } from './errors.js';
+
+/** A tail op as the server sends it. */
+export type WireTailOp =
+  | { seq: number; op_blob_b64: string }
+  | { seq: number; op_blob_url: string };
+
+/** A tail op with its bytes in hand. */
+export interface ResolvedTailOp {
+  seq: number;
+  op_blob_b64: string;
+}
+
+function isUrlOp(op: WireTailOp): op is { seq: number; op_blob_url: string } {
+  return typeof (op as { op_blob_url?: unknown }).op_blob_url === 'string';
+}
+
+/**
+ * Fetch any tail op whose bytes live behind a signed URL, leaving inline
+ * ops untouched, and return the tail in its original order.
+ *
+ * Ordering matters and concurrency does not disturb it: the fetches run
+ * together but each result lands back at its own index, so the caller
+ * still applies ops in ascending seq.
+ *
+ * A failed fetch throws rather than dropping the op. Skipping one would
+ * leave the reader a document missing an edit it will never be sent
+ * again, which reads as data loss; failing the join sends it back through
+ * a path that can succeed.
+ */
+export async function resolveTailOps(
+  tailOps: readonly WireTailOp[],
+  fetchImpl: typeof fetch = fetch,
+): Promise<ResolvedTailOp[]> {
+  if (!tailOps.some(isUrlOp)) {
+    return tailOps as ResolvedTailOp[];
+  }
+  return Promise.all(
+    tailOps.map(async (op) => {
+      if (!isUrlOp(op)) return op;
+      // The URL is pre-signed, so it carries no Brass headers: adding one
+      // would fall outside the signature and be refused.
+      const response = await fetchImpl(op.op_blob_url, { method: 'GET' });
+      if (!response.ok) {
+        throw new BrassError('Tail op fetch failed', { status: response.status });
+      }
+      return { seq: op.seq, op_blob_b64: await response.text() };
+    }),
+  );
+}

package/src/topic-lifecycle.ts

@@ -0,0 +1,217 @@
+// Pure per-topic subscription lifecycle for `BrassWsClient`. The client
+// owns the socket, timers, and frame queues; every decision about a
+// topic's subscription (what to send, when to hold or drop queued frames,
+// when to surface an error) comes from `step`'s transition table.
+//
+// Phases:
+//   - `idle`: not wanted. Errors and acks for it are ignored.
+//   - `subscribing`: wanted, first subscribe on this connection unacked
+//     (or not yet sendable). Topic-scoped frames are held until the ack.
+//   - `established`: acked; frames flow.
+//   - `retrying`: the one silent re-subscribe this connection grants is in
+//     flight after a mid-stream `not_subscribed` eviction. Further
+//     `not_subscribed` errors describe frames that predate the retry and
+//     are swallowed; any other reason is the retry's own rejection.
+//   - `tornDown`: rejected or evicted with the retry spent. Terminal until
+//     a fresh `user_subscribe` or the next socket transition prunes it.
+//     `retrySpent` survives into a same-connection re-subscribe so the
+//     retry stays one-per-topic-per-connection.
+//
+// Invariant: every transition into `tornDown` emits `send_unsubscribe`,
+// so no server-side subscription row can outlive the client-side state
+// (an orphan row would have its `last_seen` kept fresh by the heartbeat,
+// making it immune to the server's stale reaper).
+
+export type TopicPhase =
+  | 'idle'
+  | 'subscribing'
+  | 'established'
+  | 'retrying'
+  | 'tornDown';
+
+export interface TopicState {
+  phase: TopicPhase;
+  // True once this connection's one silent re-subscribe is consumed.
+  // Reset by `socket_open`.
+  retrySpent: boolean;
+}
+
+export const IDLE_TOPIC: TopicState = { phase: 'idle', retrySpent: false };
+
+export type TopicEvent =
+  | { type: 'user_subscribe' }
+  | { type: 'user_unsubscribe' }
+  | { type: 'socket_open' }
+  | { type: 'socket_closed' }
+  | { type: 'subscribed_ack' }
+  | { type: 'error'; reason: string };
+
+export type TopicEffect =
+  | { kind: 'send_subscribe' }
+  | { kind: 'send_unsubscribe' }
+  // Flush the frames held for the unacked subscribe, in order.
+  | { kind: 'flush_held' }
+  | { kind: 'drop_held' }
+  // Detach the topic's callbacks: further server frames must not reach
+  // them and the user's unsubscribe becomes a no-op.
+  | { kind: 'drop_listeners' }
+  | { kind: 'fire_error'; reason: string };
+
+export interface StepResult {
+  state: TopicState;
+  effects: TopicEffect[];
+}
+
+// True while topic-scoped frames must be held back: sending before the
+// `subscribed` ack races the server's SUB# row write and draws a spurious
+// `forbidden`.
+export function holdsFrames(state: TopicState): boolean {
+  return state.phase === 'subscribing' || state.phase === 'retrying';
+}
+
+const SEND_SUBSCRIBE: TopicEffect = { kind: 'send_subscribe' };
+const FLUSH_HELD: TopicEffect = { kind: 'flush_held' };
+const DROP_HELD: TopicEffect = { kind: 'drop_held' };
+
+// Rejection / spent-retry teardown. `send_unsubscribe` releases any
+// server-side row a completed retry may have re-created (the invariant in
+// the header); `unsubscribe` is idempotent server-side, so sending it when
+// no row exists is safe.
+function tearDown(state: TopicState, reason: string): StepResult {
+  return {
+    state: { phase: 'tornDown', retrySpent: state.retrySpent },
+    effects: [
+      DROP_HELD,
+      { kind: 'drop_listeners' },
+      { kind: 'send_unsubscribe' },
+      { kind: 'fire_error', reason },
+    ],
+  };
+}
+
+// A (re)opened socket grants a fresh retry and a fresh subscribe.
+function reopened(): StepResult {
+  return {
+    state: { phase: 'subscribing', retrySpent: false },
+    effects: [SEND_SUBSCRIBE],
+  };
+}
+
+function unsubscribed(): StepResult {
+  return {
+    state: IDLE_TOPIC,
+    effects: [DROP_HELD, { kind: 'send_unsubscribe' }],
+  };
+}
+
+export function step(state: TopicState, event: TopicEvent): StepResult {
+  switch (state.phase) {
+    case 'idle':
+      if (event.type === 'user_subscribe') {
+        return {
+          state: { phase: 'subscribing', retrySpent: false },
+          effects: [SEND_SUBSCRIBE],
+        };
+      }
+      return { state, effects: [] };
+
+    case 'subscribing':
+      switch (event.type) {
+        case 'subscribed_ack':
+          return {
+            state: { ...state, phase: 'established' },
+            effects: [FLUSH_HELD],
+          };
+        case 'error':
+          // Never established on this connection: the rejection is final.
+          return tearDown(state, event.reason);
+        case 'socket_open':
+          return reopened();
+        case 'socket_closed':
+          return { state, effects: [DROP_HELD] };
+        case 'user_unsubscribe':
+          return unsubscribed();
+        case 'user_subscribe':
+          return { state, effects: [] };
+      }
+      break;
+
+    case 'established':
+      switch (event.type) {
+        case 'error':
+          // A mid-stream `not_subscribed` is an eviction (the server
+          // dropped the subscription row while this client stayed alive,
+          // e.g. a presence reap that raced a live-but-quiet connection),
+          // not a rejection: recover silently with one re-subscribe per
+          // connection, keeping the listeners and held-frame queue. Any
+          // other reason is a genuine refusal (role, scope, membership)
+          // that a re-subscribe would just repeat.
+          if (event.reason === 'not_subscribed' && !state.retrySpent) {
+            return {
+              state: { phase: 'retrying', retrySpent: true },
+              effects: [SEND_SUBSCRIBE],
+            };
+          }
+          return tearDown(state, event.reason);
+        case 'subscribed_ack':
+          return { state, effects: [FLUSH_HELD] };
+        case 'socket_open':
+          return reopened();
+        case 'socket_closed':
+          return { state: { ...state, phase: 'subscribing' }, effects: [DROP_HELD] };
+        case 'user_unsubscribe':
+          return unsubscribed();
+        case 'user_subscribe':
+          return { state, effects: [] };
+      }
+      break;
+
+    case 'retrying':
+      switch (event.type) {
+        case 'error':
+          // An eviction draws errors for EVERY frame in flight against the
+          // reaped row; the trailing ones land while the retry's subscribe
+          // is unacked and describe frames that predate it, so the retry
+          // supersedes them. A non-`not_subscribed` reason in this window
+          // is the retry's own rejection.
+          if (event.reason === 'not_subscribed') {
+            return { state, effects: [] };
+          }
+          return tearDown(state, event.reason);
+        case 'subscribed_ack':
+          return {
+            state: { ...state, phase: 'established' },
+            effects: [FLUSH_HELD],
+          };
+        case 'socket_open':
+          return reopened();
+        case 'socket_closed':
+          return { state: { ...state, phase: 'subscribing' }, effects: [DROP_HELD] };
+        case 'user_unsubscribe':
+          return unsubscribed();
+        case 'user_subscribe':
+          return { state, effects: [] };
+      }
+      break;
+
+    case 'tornDown':
+      switch (event.type) {
+        case 'user_subscribe':
+          // Same-connection re-subscribe: a spent retry stays spent, so
+          // the fresh subscribe rides the retrying phase's error handling.
+          return {
+            state: {
+              phase: state.retrySpent ? 'retrying' : 'subscribing',
+              retrySpent: state.retrySpent,
+            },
+            effects: [SEND_SUBSCRIBE],
+          };
+        case 'socket_open':
+        case 'socket_closed':
+          return { state: IDLE_TOPIC, effects: [] };
+        default:
+          return { state, effects: [] };
+      }
+  }
+  return { state, effects: [] };
+}

package/src/types.ts

@@ -0,0 +1,75 @@
+export interface BrassUser {
+  sub: string;
+  email?: string;
+  display_name?: string;
+  avatar_url?: string;
+}
+
+export interface BrassInitOptions {
+  // With nothing passed, the SDK resolves all four production origins.
+  // Naming any one of the four below opts out of that entirely, so a
+  // stack is addressed by its own origins rather than by a mix.
+  authBaseUrl?: string;
+  // Origin for the Brass data API (documents, organizations, users). The
+  // auth surface uses `authBaseUrl`.
+  apiBaseUrl?: string;
+  // WebSocket endpoint for document op and presence subscriptions. On
+  // its own hostname, so it cannot be derived from `apiBaseUrl`. Passing
+  // any other `*BaseUrl` leaves it unset on purpose: a production ws
+  // origin beside a hand-overridden HTTP origin would connect to a
+  // different stack and silently drop events, whereas unset fails loudly
+  // on `subscribe`.
+  wsBaseUrl?: string;
+  // Origin the Brass-hosted UI pages are served from. The hosted-UI
+  // launchers load `${dashboardBaseUrl}/embed/*` in a modal iframe.
+  dashboardBaseUrl?: string;
+  // Pin the hosted-UI modal + embed page to a theme. Defaults to
+  // `'light'`; `'auto'` follows the OS preference. An app that forces
+  // its own theme should pass the matching value so the modal doesn't
+  // mismatch the page that opened it.
+  hostedUiTheme?: 'light' | 'dark' | 'auto';
+  // Open a document even when this app's declared schema cannot read it
+  // (default off). Off, the platform refuses such an open and the SDK asks
+  // the person whether to go ahead, so a bookmark or a reload cannot open
+  // one silently. On, every open carries the answer already, which is what
+  // an app driving opens with nobody watching needs.
+  openIncompatibleDocuments?: boolean;
+  // Mirror the active document selection to the page URL (default on):
+  // writes the doc id (and non-default branch) using `pushState` for a
+  // genuine open / branch switch and `replaceState` to pin the boot
+  // selection, and restores from the URL on boot and `popstate`. Read
+  // the id directly via `Brass.docIdFromUrl()`. Opt out with `false`
+  // for an app that owns its URL state (e.g. its own router).
+  syncDocToUrl?: boolean;
+  // Query-parameter name for the active doc id (default `'doc'`). Set to
+  // disambiguate when the app's URL already uses `doc`.
+  docUrlParam?: string;
+  // Query-parameter name for a non-default branch (default `'branch'`).
+  // Present only when the active document is on a non-default branch.
+  branchUrlParam?: string;
+  // Set `document.title` to the active document's name (default on), so
+  // history entries are distinguishable, restoring the original title
+  // when no document is open. While a document is open the title is
+  // suffixed with the app name (`Doc name · App name`), taken from the
+  // page's own `<title>` at the first sync. Opt out with `false` for an
+  // app that manages its own title.
+  syncDocToTitle?: boolean;
+}
+
+// `'unknown'` is the bootstrap window before `Brass.init` settles,
+// distinct from `'signed-out'` (init settled, no user) so an app can
+// render a neutral state instead of flashing its sign-in CTA at a user
+// who turns out to be signed in. Then tracks every sign-in / sign-out.
+// `'guest'` is the anonymous-link case: the page was opened via a
+// public-link token (`?brass_link=`), so there is no signed-in user but
+// the session still opens a read-only document. An app renders its
+// working surface for `'signed-in'` OR `'guest'` (read-only), and its
+// sign-in CTA only for `'signed-out'`.
+export type AuthStatus = 'unknown' | 'signed-in' | 'signed-out' | 'guest';
+
+export type UserChangeListener = (user: BrassUser | null) => void;
+
+// Fired when Brass.init fails (bad / missing app_id, etc.). Register
+// before init to get visibility into failures that an init wrapped
+// without a `.catch()` would otherwise swallow silently.
+export type ErrorListener = (error: Error) => void;

package/src/undo.ts

@@ -0,0 +1,125 @@
+// Per-Document undo/redo, backed by Loro's UndoManager: undo is
+// local-peer-scoped (reverts only this peer's ops), group bracketing collapses
+// same-stroke edits into one entry, and remote-import bookkeeping keeps the
+// redo stack honest across other peers' edits.
+import { UndoManager, type LoroDoc } from 'loro-crdt';
+
+// Loro's time-based merge is permanently disabled. The undo boundary here is
+// the checkpoint group bracket (`sealStep`), and the two are incompatible: a
+// nonzero merge interval merges adjacent changes by *timestamp*, and that
+// merge reaches ACROSS a `groupEnd()` / `groupStart()` seal, collapsing two
+// separately-sealed steps into one. That silently violates the "every
+// checkpoint is an undo boundary" contract (one Ctrl-Z reverts more than the
+// last operation and the rendered state jumps past where the user expected).
+// Same-stroke collapsing is still handled, by the open group not the clock:
+// every commit between two seals brackets into one entry. Apps tune
+// granularity via `setAutoCheckpointIntervalMs` and `createCheckpoint`.
+const UNDO_MERGE_INTERVAL_MS = 0;
+
+// Cap on retained undo steps (Loro's default is 100). 200 at typical AEC
+// entity sizes is a few hundred KB, well below anything that matters.
+const DEFAULT_MAX_UNDO_STEPS = 200;
+
+export interface UndoControllerOptions {
+  // Cap on retained undo steps. Older steps drop off the bottom of the
+  // stack as new ones land.
+  maxUndoSteps?: number;
+}
+
+// Thin wrapper around Loro's UndoManager exposing only what the Document
+// needs. Owned by the Document; not part of the public SDK surface.
+export class UndoController {
+  private readonly _mgr: UndoManager;
+  // Whether an implicit group is open. The Document keeps one open between
+  // checkpoints so `createCheckpoint` is THE undo boundary: every commit
+  // between two checkpoints collapses into one step. `sealStep` closes and
+  // reopens the group, the only way to force a boundary into Loro's stack
+  // (Loro has no "force boundary here" primitive). This is a hard boundary
+  // only because the merge interval is disabled (see above).
+  private _groupOpen = false;
+
+  constructor(loroDoc: LoroDoc, options?: UndoControllerOptions) {
+    this._mgr = new UndoManager(loroDoc, {
+      mergeInterval: UNDO_MERGE_INTERVAL_MS,
+      maxUndoSteps: options?.maxUndoSteps ?? DEFAULT_MAX_UNDO_STEPS,
+    });
+    // Open the implicit group so commits before the first `createCheckpoint`
+    // still bracket as one undo step.
+    this._mgr.groupStart();
+    this._groupOpen = true;
+  }
+
+  // undo/redo run OUTSIDE the implicit group: Loro groups every commit while a
+  // group is open, INCLUDING the one a `redo()` / `undo()` itself produces, so
+  // running them inside would fold the reapplied step into the group and the
+  // next sealed edit would merge with it (one Ctrl-Z reverts both). Closing
+  // first also makes unsealed pending commits their own boundary.
+  undo(): boolean {
+    return this.outsideGroup(() => this._mgr.undo());
+  }
+
+  redo(): boolean {
+    return this.outsideGroup(() => this._mgr.redo());
+  }
+
+  private outsideGroup(op: () => boolean): boolean {
+    if (this._groupOpen) {
+      this._mgr.groupEnd();
+      this._groupOpen = false;
+    }
+    try {
+      return op();
+    } finally {
+      this._mgr.groupStart();
+      this._groupOpen = true;
+    }
+  }
+
+  canUndo(): boolean {
+    return this._mgr.canUndo();
+  }
+
+  canRedo(): boolean {
+    return this._mgr.canRedo();
+  }
+
+  // Seal the current undo step: close the implicit group (commits since the
+  // previous seal collapse into one entry) and open a fresh one.
+  // `createCheckpoint` and the auto-checkpoint scheduler call this so every
+  // checkpoint is a Ctrl-Z boundary. Idempotent: calling twice with no
+  // intervening commit is safe (Loro collapses the empty group).
+  sealStep(): void {
+    if (this._groupOpen) {
+      this._mgr.groupEnd();
+      this._groupOpen = false;
+    }
+    this._mgr.groupStart();
+    this._groupOpen = true;
+  }
+
+  // Drop both stacks. Called by `_applySnapshot`: the prior entries reference a
+  // state the new snapshot superseded.
+  clear(): void {
+    // Close the open group first so `clear()` sees a clean state (defensive;
+    // Loro's `clear` drops both stacks regardless).
+    if (this._groupOpen) {
+      this._mgr.groupEnd();
+      this._groupOpen = false;
+    }
+    this._mgr.clear();
+    this._mgr.groupStart();
+    this._groupOpen = true;
+  }
+
+  free(): void {
+    if (this._groupOpen) {
+      try {
+        this._mgr.groupEnd();
+      } catch {
+        // Best-effort; the underlying manager is about to free.
+      }
+      this._groupOpen = false;
+    }
+    this._mgr.free();
+  }
+}