@brass-build/client 0.1.0

package/src/doc-url-sync.ts

@@ -0,0 +1,183 @@
+// Sync of the active document selection (id, plus branch when not the
+// default) to the page URL. `history.replaceState` pins the current
+// selection in place (boot restore, direct open); `history.pushState`
+// records a genuine navigation so Back / Forward step between the
+// documents and branches a user opened. Restored from the URL on boot
+// and on `popstate`.
+//
+// Query parameters, not path segments, because the host app owns its
+// own routing: a query param coexists with whatever route it is on,
+// whereas rewriting the path would collide with its router.
+//
+// All operations are best-effort and no-op outside a browser or when
+// the History API is unavailable (safe from SSR / Node tests).
+
+export const DEFAULT_DOC_URL_PARAM = 'doc';
+export const DEFAULT_BRANCH_URL_PARAM = 'branch';
+
+// One-shot params the hosted picker's redirect fallback returns the pick
+// on. Distinct from the app-facing `doc` / `branch` sync params so the
+// hand-off works even when the app has turned URL sync off (or renamed
+// those params): the SDK consumes these on boot regardless of
+// `syncDocToUrl`, opens the document, and strips them so they never
+// linger in the app's URL. Named with a `brass_` prefix so they can't
+// collide with an app's own query params.
+export const PICK_DOC_PARAM = 'brass_pick';
+export const PICK_BRANCH_PARAM = 'brass_pick_branch';
+
+// The active selection as carried in the URL. `branchId` is null for
+// the default branch, which is never written to the URL.
+export interface UrlSelection {
+  docId: string;
+  branchId: string | null;
+}
+
+function getWindow(): (Window & typeof globalThis) | null {
+  if (typeof window === 'undefined') return null;
+  return window;
+}
+
+export function readDocIdFromUrl(param: string): string | null {
+  const w = getWindow();
+  if (!w) return null;
+  try {
+    const url = new URL(w.location.href);
+    const value = url.searchParams.get(param);
+    return value && value.length > 0 ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeDocIdToUrl(docId: string, param: string): void {
+  const w = getWindow();
+  if (!w) return;
+  try {
+    const url = new URL(w.location.href);
+    if (url.searchParams.get(param) === docId) return;
+    url.searchParams.set(param, docId);
+    w.history.replaceState(w.history.state, '', url.toString());
+  } catch {
+    // History API unavailable or URL exotic: leave the URL alone.
+  }
+}
+
+export function clearDocIdFromUrl(param: string): void {
+  const w = getWindow();
+  if (!w) return;
+  try {
+    const url = new URL(w.location.href);
+    if (!url.searchParams.has(param)) return;
+    url.searchParams.delete(param);
+    w.history.replaceState(w.history.state, '', url.toString());
+  } catch {
+    // See `writeDocIdToUrl`.
+  }
+}
+
+// Read the active selection from the URL. Returns null when no document
+// is named, so a branch param alone never resurrects a selection.
+export function readUrlSelection(
+  docParam: string,
+  branchParam: string,
+): UrlSelection | null {
+  const w = getWindow();
+  if (!w) return null;
+  try {
+    const url = new URL(w.location.href);
+    const docId = url.searchParams.get(docParam);
+    if (!docId || docId.length === 0) return null;
+    const branch = url.searchParams.get(branchParam);
+    return { docId, branchId: branch && branch.length > 0 ? branch : null };
+  } catch {
+    return null;
+  }
+}
+
+// Write the active selection to the URL. `push` records a genuine
+// navigation; otherwise the current entry is replaced in place. The
+// branch param is set only for a non-default branch, so a default-branch
+// selection reads back as a bare `?doc=`. A write whose resulting URL
+// matches the current one is skipped, so a redundant push never plants
+// a duplicate entry.
+export function writeUrlSelection(
+  selection: UrlSelection,
+  docParam: string,
+  branchParam: string,
+  options: { push: boolean },
+): void {
+  const w = getWindow();
+  if (!w) return;
+  try {
+    const url = new URL(w.location.href);
+    url.searchParams.set(docParam, selection.docId);
+    if (selection.branchId !== null) {
+      url.searchParams.set(branchParam, selection.branchId);
+    } else {
+      url.searchParams.delete(branchParam);
+    }
+    const next = url.toString();
+    if (next === w.location.href) return;
+    if (options.push) {
+      w.history.pushState(w.history.state, '', next);
+    } else {
+      w.history.replaceState(w.history.state, '', next);
+    }
+  } catch {
+    // History API unavailable or URL exotic: leave the URL alone.
+  }
+}
+
+// Clear the active selection from the URL via `replaceState` (a clear
+// is never a navigation, so it pushes no history entry).
+export function clearUrlSelection(docParam: string, branchParam: string): void {
+  const w = getWindow();
+  if (!w) return;
+  try {
+    const url = new URL(w.location.href);
+    if (!url.searchParams.has(docParam) && !url.searchParams.has(branchParam)) {
+      return;
+    }
+    url.searchParams.delete(docParam);
+    url.searchParams.delete(branchParam);
+    w.history.replaceState(w.history.state, '', url.toString());
+  } catch {
+    // See `writeUrlSelection`.
+  }
+}
+
+// Read and CONSUME the hosted picker's one-shot pick from the URL: return
+// the selection the redirect fallback returned, and strip both pick params
+// in the same call (via `replaceState`, never a navigation) so a reload
+// can't reopen the pick and the params don't leak into the app's URL.
+// Returns null when no pick is present (the ordinary boot). Runs
+// independently of `syncDocToUrl`, since the redirect needs to hand a pick
+// back even to an app that manages its own selection.
+export function takePickFromUrl(): UrlSelection | null {
+  const w = getWindow();
+  if (!w) return null;
+  try {
+    const url = new URL(w.location.href);
+    const docId = url.searchParams.get(PICK_DOC_PARAM);
+    if (!docId || docId.length === 0) return null;
+    const branch = url.searchParams.get(PICK_BRANCH_PARAM);
+    const branchId = branch && branch.length > 0 ? branch : null;
+    url.searchParams.delete(PICK_DOC_PARAM);
+    url.searchParams.delete(PICK_BRANCH_PARAM);
+    w.history.replaceState(w.history.state, '', url.toString());
+    return { docId, branchId };
+  } catch {
+    return null;
+  }
+}
+
+// Subscribe to Back / Forward navigation. No-op outside a browser.
+// Only user-driven Back / Forward fires `popstate`; the SDK's own
+// push / replace writes do not, so a restore on `popstate` cannot feed
+// back into another history write.
+export function subscribePopState(listener: () => void): () => void {
+  const w = getWindow();
+  if (!w) return () => {};
+  w.addEventListener('popstate', listener);
+  return () => w.removeEventListener('popstate', listener);
+}

package/src/document-branches.ts

@@ -0,0 +1,124 @@
+// Document branches (alternate states of the same design): the reactive
+// list, the injected HTTP provider that lists / creates them, and the
+// optimistic-append on create.
+
+import type {
+  BranchSummary,
+  CreateBranchRequest,
+} from './documents-namespace.js';
+
+// Injected HTTP capability the controller's branch methods call through.
+export interface BranchProvider {
+  list(docId: string): Promise<{
+    default_branch_id: string;
+    branches: BranchSummary[];
+  }>;
+  create(docId: string, input: CreateBranchRequest): Promise<BranchSummary>;
+}
+
+export interface BranchControllerHost {
+  // Server identity; `null` on the offline / test path.
+  docId(): string | null;
+  // The branch the Document is open on (a new branch forks from here).
+  // `null` on the offline / test path.
+  branchId(): string | null;
+  // True when the doc is live (not closed / suspended).
+  isActive(): boolean;
+  // Fire the Document's `branches` subscribe event so a branch picker
+  // re-reads inside the existing subscribe handler.
+  onBranchesChanged(branches: readonly BranchSummary[]): void;
+}
+
+export class BranchController {
+  // Reactive branches list. Set by the factory's initial fetch, then by
+  // `refresh` and `create`. Empty until that fetch resolves.
+  private _branches: readonly BranchSummary[] = [];
+  private _defaultBranchId: string | null = null;
+  // `null` on the offline / test path with no transport.
+  private _provider: BranchProvider | null = null;
+
+  constructor(private readonly host: BranchControllerHost) {}
+
+  get branches(): readonly BranchSummary[] {
+    return this._branches;
+  }
+
+  get defaultBranchId(): string | null {
+    return this._defaultBranchId;
+  }
+
+  // Whether a provider is attached. The file-menu's branches submenu
+  // reads this to decide whether to offer "New branch...".
+  get hasProvider(): boolean {
+    return this._provider !== null;
+  }
+
+  // Set the branches list and fire the `branches` subscribe event.
+  set(
+    branches: readonly BranchSummary[],
+    defaultBranchId: string | null,
+  ): void {
+    this._branches = branches;
+    this._defaultBranchId = defaultBranchId;
+    this.host.onBranchesChanged(branches);
+  }
+
+  setProvider(provider: BranchProvider | null): void {
+    this._provider = provider;
+  }
+
+  // Re-fetch the branches list from the server. Useful after an
+  // out-of-band change another peer made; not normally needed because
+  // `create` updates the list automatically.
+  async refresh(): Promise<void> {
+    if (!this.host.isActive()) return;
+    const docId = this.host.docId();
+    if (docId === null || this._provider === null) return;
+    const { default_branch_id, branches } = await this._provider.list(docId);
+    if (!this.host.isActive()) return;
+    this.set(branches, default_branch_id);
+  }
+
+  // Create a new branch under this document, forked from the branch the
+  // Document is open on. Updates `branches` on success (optimistic
+  // append; the next refresh reconciles any drift).
+  async create(input: {
+    name?: string;
+    from_version?: number;
+  }): Promise<BranchSummary> {
+    if (!this.host.isActive()) {
+      throw new Error('Document is closed');
+    }
+    const docId = this.host.docId();
+    const branchId = this.host.branchId();
+    if (docId === null) {
+      throw new Error('createBranch: Document has no server identity');
+    }
+    if (branchId === null) {
+      throw new Error('createBranch: Document has no branch');
+    }
+    if (this._provider === null) {
+      throw new Error(
+        'createBranch: no provider attached. Opened via the SDK factory?',
+      );
+    }
+    const request: CreateBranchRequest = {
+      from_branch_id: branchId,
+    };
+    if (input.name !== undefined) request.name = input.name;
+    if (input.from_version !== undefined) {
+      request.from_version = input.from_version;
+    }
+    const branch = await this._provider.create(docId, request);
+    // Re-check liveness after the await, exactly as `refresh` does: a
+    // `close()` in flight nulls the host's Loro subscription and frees its
+    // doc, so firing the `branches` change (which re-attaches that
+    // subscription) would run against a freed document. The create already
+    // landed server-side, so still return the branch; just skip the
+    // reactive `set` a torn-down document can't consume.
+    if (!this.host.isActive()) return branch;
+    const next: BranchSummary[] = [...this._branches, branch];
+    this.set(next, this._defaultBranchId);
+    return branch;
+  }
+}

package/src/document-checkpoints.ts

@@ -0,0 +1,135 @@
+// Document version-history checkpoints: app-driven `createCheckpoint`
+// plus an implicit auto-checkpoint debounce that seals a marker after a
+// burst of local edits settles. Both also seal the undo step, unifying
+// "checkpoint" and "undo boundary": a deliberate save, an auto-seal on
+// idle, and a modeler's pointerUp all produce the same Ctrl-Z boundary.
+
+import type { DocumentCheckpoint } from './documents-namespace.js';
+
+export type CheckpointCreator = () => Promise<DocumentCheckpoint>;
+
+// Default auto-checkpoint debounce: sealed this long after the last
+// local edit, so every app gets a version-history timeline without
+// writing checkpoint code. 60s balances "user reaches a natural pause"
+// against snapshot-blob churn. Override or disable (0) via
+// `doc.setAutoCheckpointIntervalMs(...)`.
+const AUTO_CHECKPOINT_DEFAULT_MS = 60_000;
+
+export interface CheckpointSchedulerHost {
+  // Server identity; `null` on offline / test docs.
+  docId(): string | null;
+  // True when the doc is live (not closed / suspended). A manual
+  // `createCheckpoint` throws "Document is closed" otherwise.
+  isAttached(): boolean;
+  // True when an auto-checkpoint may fire: live AND at head (a
+  // historical checkout must not seal markers).
+  isAutoAllowed(): boolean;
+  // The version this Document shows (live-head seq or frozen checkout
+  // version). The checkpoint anchors here.
+  currentSeq(): number | null;
+  // Seal the current undo step. Safe to call when undo is absent.
+  sealUndoStep(): void;
+}
+
+export class CheckpointScheduler {
+  // Injected checkpoint-create hook (the Document owns no HTTP client).
+  // `null` on offline / test paths; a manual `create` then throws.
+  private _creator: CheckpointCreator | null = null;
+  // Debounce timer + bookkeeping. `_autoIntervalMs === 0` disables it;
+  // `_lastSeq` skips a fire that would clobber a manual checkpoint at
+  // the same seq.
+  private _autoTimer: ReturnType<typeof setTimeout> | null = null;
+  private _autoIntervalMs: number = AUTO_CHECKPOINT_DEFAULT_MS;
+  private _lastSeq: number | null = null;
+
+  constructor(private readonly host: CheckpointSchedulerHost) {}
+
+  setCreator(creator: CheckpointCreator | null): void {
+    this._creator = creator;
+  }
+
+  // Seal a checkpoint anchored to `host.currentSeq()`.
+  async create(): Promise<DocumentCheckpoint> {
+    if (!this.host.isAttached()) {
+      throw new Error('Document is closed');
+    }
+    if (this.host.docId() === null) {
+      throw new Error('createCheckpoint: Document has no server identity');
+    }
+    if (this._creator === null) {
+      throw new Error(
+        'createCheckpoint: no creator attached. Opened via the SDK factory?',
+      );
+    }
+    // Seal BEFORE the round-trip: the seal is synchronous, so mutates
+    // arriving during the await start a fresh undo step rather than
+    // folding into the pre-checkpoint one.
+    this.host.sealUndoStep();
+    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),
+    // so without this an idle period right after a manual save would
+    // replace the manual entry with an auto one.
+    this._lastSeq = result.version;
+    return result;
+  }
+
+  // Configure the auto-checkpoint debounce; `0` disables. Returns the
+  // prior value so a scoped override can restore.
+  setAutoIntervalMs(intervalMs: number): number {
+    if (!Number.isFinite(intervalMs) || intervalMs < 0) {
+      throw new Error('setAutoCheckpointIntervalMs: intervalMs must be >= 0');
+    }
+    const prev = this._autoIntervalMs;
+    this._autoIntervalMs = intervalMs;
+    if (intervalMs === 0 && this._autoTimer !== null) {
+      clearTimeout(this._autoTimer);
+      this._autoTimer = null;
+    }
+    return prev;
+  }
+
+  // Called from the Document's local-commit dispatch. Debounces so a
+  // burst of edits produces ONE marker when it settles. Skips when the
+  // interval is 0 or there is no creator; the fire's guard re-checks
+  // closed / suspended / checkout.
+  scheduleAuto(): void {
+    if (this._autoIntervalMs === 0) return;
+    if (this._creator === null) return;
+    if (this._autoTimer !== null) {
+      clearTimeout(this._autoTimer);
+    }
+    this._autoTimer = setTimeout(() => {
+      this._autoTimer = null;
+      void this._fireAuto();
+    }, this._autoIntervalMs);
+  }
+
+  // Cancel a pending auto-checkpoint (suspend / close).
+  cancelAuto(): void {
+    if (this._autoTimer !== null) {
+      clearTimeout(this._autoTimer);
+      this._autoTimer = null;
+    }
+  }
+
+  private async _fireAuto(): Promise<void> {
+    if (!this.host.isAutoAllowed()) return;
+    if (this._creator === null) return;
+    const seq = this.host.currentSeq();
+    if (seq === null) return;
+    // Already checkpointed at this exact version (manual seal a moment
+    // ago).
+    if (this._lastSeq === seq) return;
+    // Seal undo before the write so the user gets the Ctrl-Z boundary at
+    // their idle point even if the server write below fails.
+    this.host.sealUndoStep();
+    try {
+      const result = await this._creator();
+      this._lastSeq = result.version;
+    } catch {
+      // Best-effort: a rejection (rate limit, no write access, network)
+      // is swallowed; the next local edit reschedules.
+    }
+  }
+}