@brass-build/client 0.4.1 → 0.5.0

package/src/undo.ts

@@ -1,27 +1,31 @@
 // 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.
+// local-peer-scoped (reverts only this peer's ops), and the controller groups
+// Loro's per-commit stack items into the steps a reader undoes. Every stream
+// of one document is its own LoroDoc with its own controller, and an
+// `UndoGroup` makes them one stack: they share the step clock, so a step is
+// every commit between two seals in whichever streams took one, and the group
+// replays the newest step in each stream that holds a part of it.
 import { UndoManager, type LoroDoc } from './wasm-runtime.js';
 
 import type { UndoControllerOptions } from './types.js';
 
-// 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`.
+// Loro's time-based merge is permanently disabled. It merges adjacent changes
+// by timestamp, across a `sealStep` boundary, so one Ctrl-Z would revert more
+// than the last step. Every commit is its own Loro stack item, and the step a
+// commit belongs to is the tag `sealStep` advances.
 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;
 
+// Loro caps stack ITEMS, and a step is as many items as it has commits (a
+// typed word is one per keystroke). The controller caps STEPS itself (see
+// `_floor`), and Loro's item cap is a memory bound behind it. When that one
+// binds, Loro drops the oldest items, and the oldest step reverts only the
+// part of it that is left.
+const ITEMS_PER_STEP_CAP = 64;
+
 // Commit origin the paged marker (`meta.paged:<root>`) is stamped with, and
 // the one origin the undo stack ignores.
 //
@@ -33,101 +37,410 @@ const DEFAULT_MAX_UNDO_STEPS = 200;
 // excluded alongside it.
 export const PAGING_COMMIT_ORIGIN = 'brass.paging';
 
+// Commit origin of a write the app asked to keep off the reader's Undo stack
+// (`mutate(fn, { undoable: false })`, `markRead(..., { undoable: false })`):
+// an automatic pass the reader did not ask for, which their Undo must not
+// revert along with what they did.
+export const NON_UNDOABLE_COMMIT_ORIGIN = 'brass.auto';
+
 // Thin wrapper around Loro's UndoManager exposing only what the Document
 // needs. Owned by the Document; not part of the public SDK surface.
+//
+// A step is every local commit between two `sealStep` calls, and the Document
+// seals only at a checkpoint, so a step spans a peer's edits whenever two
+// people work at once. Every commit is its own Loro stack item, tagged in
+// `onPush` with the step it belongs to, and `undo` / `redo` replay every item
+// at the top of the stack carrying the top item's tag, so a step reverts whole
+// however many commits it took.
+//
+// Loro's own group cannot hold a step. A peer's edit made after seeing only
+// some of a group's commits leaves the group impossible to undo fully (the
+// commits the peer saw stay in place, and no later undo removes them), and
+// commits ship as they are made, so any group of two or more commits can meet
+// that in ordinary collaboration. `undo-concurrent-delivery.test.ts` pins the
+// engine behaviour.
+//
+// One item per commit costs time on a long step: each Loro undo transforms the
+// rest of the stack against the remote edits recorded on it, so a step's undo
+// grows with its commit count times the remote edits interleaved with the
+// stack (`scripts/bench/undo-long-step.mts`).
 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) {
+  private readonly _maxSteps: number;
+  // Holds the tag of the step new local commits join, shared by every stream
+  // of the document. `sealStep` advances it.
+  private _clock: UndoClock;
+  private readonly _hooks: UndoControllerHooks;
+  // How many items at the bottom of the redo stack belong to a history a
+  // fresh commit in ANOTHER stream has since replaced. Loro clears this
+  // stack itself on a commit to this stream only.
+  private _redoRetired = 0;
+  // While `undo` / `redo` replays a step, the tag the items it pushes onto
+  // the opposite stack carry, so the step stays one step in both directions.
+  private _replaying: number | null = null;
+  // The tag of the item Loro last popped, which the item its replay pushes
+  // onto the opposite stack inherits. Loro pops before it pushes.
+  private _popped: number | null = null;
+  // Set when a replay's Loro call applied an item of another step (see
+  // `replay`), and while the controller puts that item back.
+  private _foreign: number | null = null;
+  private _restoring = false;
+  // Whether the replay popped an item of the step it replays.
+  private _poppedOwn = false;
+  // Tags of the steps on the undo stack, oldest first. Tags only grow up the
+  // stack, so a step past the cap is retired by raising `_floor` to its tag:
+  // `undo` never replays an item tagged at or below the floor.
+  private _undoSteps: number[] = [];
+  private _floor = -1;
+  // The tag of every item on each Loro stack, bottom first. Once a stack is
+  // at Loro's item cap, Loro loses the value `onPush` attaches to each item
+  // pushed from then on (loro-crdt 1.13.9 through 1.16.4), so the tag a
+  // replay reads comes from here whenever Loro's own reads back empty.
+  private _undoTags: number[] = [];
+  private _redoTags: number[] = [];
+  private readonly _itemCap: number;
+
+  constructor(
+    loroDoc: LoroDoc,
+    options?: UndoControllerOptions,
+    clock: UndoClock = new UndoGroup(),
+    hooks: UndoControllerHooks = {},
+  ) {
+    this._clock = clock;
+    this._hooks = hooks;
+    const maxSteps = options?.maxUndoSteps ?? DEFAULT_MAX_UNDO_STEPS;
+    if (!Number.isInteger(maxSteps) || maxSteps < 1) {
+      throw new RangeError(`maxUndoSteps must be an integer of at least 1, got ${maxSteps}`);
+    }
+    this._maxSteps = maxSteps;
+    this._itemCap = maxSteps * ITEMS_PER_STEP_CAP;
     this._mgr = new UndoManager(loroDoc, {
       mergeInterval: UNDO_MERGE_INTERVAL_MS,
-      maxUndoSteps: options?.maxUndoSteps ?? DEFAULT_MAX_UNDO_STEPS,
-      excludeOriginPrefixes: [PAGING_COMMIT_ORIGIN],
+      maxUndoSteps: this._itemCap,
+      excludeOriginPrefixes: [PAGING_COMMIT_ORIGIN, NON_UNDOABLE_COMMIT_ORIGIN],
+      onPush: (isUndo) => {
+        const tag = this._popped ?? this._replaying ?? this._clock.step;
+        this._popped = null;
+        const ownStep = this._replaying === null || tag === this._replaying;
+        if (!ownStep && !this._restoring) this._foreign = tag;
+        if (isUndo) {
+          if (ownStep && !this._restoring) this.recordUndoStep(tag);
+          // A local commit clears Loro's redo stack; a redo's own push does not.
+          if (this._replaying === null) {
+            this._redoTags = [];
+            this._redoRetired = 0;
+            this._hooks.onFreshCommit?.();
+          }
+        }
+        const tags = isUndo ? this._undoTags : this._redoTags;
+        tags.push(tag);
+        if (tags.length > this._itemCap) {
+          const dropped = tags.length - this._itemCap;
+          tags.splice(0, dropped);
+          if (!isUndo) this._redoRetired = Math.max(0, this._redoRetired - dropped);
+        }
+        this._hooks.onStackChange?.();
+        return { value: tag, cursors: [] };
+      },
+      onPop: (isUndo, meta) => {
+        const mirrored = (isUndo ? this._undoTags : this._redoTags).pop();
+        const tag = typeof meta.value === 'number' ? meta.value : mirrored;
+        this._popped = tag ?? null;
+        if (tag === this._replaying && !this._restoring) this._poppedOwn = true;
+        if (!isUndo && this._redoRetired > this._redoTags.length) {
+          this._redoRetired = this._redoTags.length;
+        }
+        this._hooks.onStackChange?.();
+      },
     });
-    // 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());
+  private topTag(dir: 'undo' | 'redo'): number | undefined {
+    const value = dir === 'undo' ? this._mgr.topUndoValue() : this._mgr.topRedoValue();
+    if (typeof value === 'number') return value;
+    const tags = dir === 'undo' ? this._undoTags : this._redoTags;
+    return tags[tags.length - 1];
   }
 
-  redo(): boolean {
-    return this.outsideGroup(() => this._mgr.redo());
+  private recordUndoStep(tag: number): void {
+    if (this._undoSteps[this._undoSteps.length - 1] === tag) return;
+    this._undoSteps.push(tag);
+    while (this._undoSteps.length > this._maxSteps) {
+      this._floor = Math.max(this._floor, this._undoSteps.shift()!);
+    }
   }
 
-  private outsideGroup(op: () => boolean): boolean {
-    if (this._groupOpen) {
-      this._mgr.groupEnd();
-      this._groupOpen = false;
-    }
+  // `beforeEach` runs before every Loro undo / redo the step takes, since each
+  // one is its own commit (the Document tags each with its commit origin).
+  undo(beforeEach?: () => void): boolean {
+    return this.replay('undo', beforeEach);
+  }
+
+  redo(beforeEach?: () => void): boolean {
+    return this.replay('redo', beforeEach);
+  }
+
+  // Replay this stream's part of step `tag`, which the group chose as the
+  // document's newest (undo) or most recently undone (redo) step.
+  replayStep(dir: 'undo' | 'redo', tag: number, beforeEach?: () => void): boolean {
+    return this.replay(dir, beforeEach, tag);
+  }
+
+  // The tag of the step this stream would replay next, or `undefined` when
+  // it has none: below the floor for undo, and past the retired items for
+  // redo.
+  peek(dir: 'undo' | 'redo'): number | undefined {
+    const tag = this.topTag(dir);
+    if (typeof tag !== 'number') return undefined;
+    if (dir === 'undo') return tag > this._floor ? tag : undefined;
+    return this.hasLiveRedo() ? tag : undefined;
+  }
+
+  // Tags at or below this have left the undo stack (see `_floor`).
+  get floor(): number {
+    return this._floor;
+  }
+
+  // Move to another document's step clock. Called when a stream joins its
+  // document, before it has taken any local commit.
+  useClock(clock: UndoClock): void {
+    this._clock = clock;
+  }
+
+  // A fresh commit in another stream of the document: the steps on this
+  // stream's redo stack belong to the history that commit replaced.
+  retireRedo(): void {
+    this._redoRetired = this._redoTags.length;
+  }
+
+  private hasLiveRedo(): boolean {
+    return this._redoRetired === 0 || this._redoTags.length > this._redoRetired;
+  }
+
+  // Loro skips an item whose replay would change nothing visible (a peer
+  // deleted what it edited) and pops the next one in the same call, which can
+  // belong to an older step or sit below `_floor`. The controller puts such an
+  // item straight back through the opposite stack, under its own tag, so one
+  // call replays one step. A step whose every item Loro skipped has still left
+  // the stack, so it counts as replayed and the call returns `true`.
+  private replay(dir: 'undo' | 'redo', beforeEach?: () => void, chosen?: number): boolean {
+    const top = (): number | undefined => this.topTag(dir);
+    const tag = chosen ?? this.peek(dir);
+    this._poppedOwn = false;
     try {
-      return op();
+      if (typeof tag === 'number' && top() === tag) {
+        this._replaying = tag;
+        while (top() === tag) {
+          beforeEach?.();
+          const moved = dir === 'undo' ? this._mgr.undo() : this._mgr.redo();
+          if (this._foreign !== null) {
+            this._restoring = true;
+            beforeEach?.();
+            if (dir === 'undo') this._mgr.redo();
+            else this._mgr.undo();
+            this._restoring = false;
+            this._foreign = null;
+          }
+          if (!moved) break;
+        }
+        if (dir === 'undo' && this._undoSteps[this._undoSteps.length - 1] === tag) {
+          this._undoSteps.pop();
+        }
+      }
     } finally {
-      this._mgr.groupStart();
-      this._groupOpen = true;
+      this._replaying = null;
+      this._restoring = false;
+      this._foreign = null;
+      this._popped = null;
+      // The next local commit starts a step of its own, so it never joins the
+      // step just replayed (an edit after a redo undoes on its own).
+      this._clock.step += 1;
     }
+    return this._poppedOwn;
   }
 
   canUndo(): boolean {
-    return this._mgr.canUndo();
+    const tag = this.topTag('undo');
+    return tag !== undefined && tag > this._floor && this._mgr.canUndo();
   }
 
   canRedo(): boolean {
-    return this._mgr.canRedo();
+    return this._mgr.canRedo() && this.hasLiveRedo();
   }
 
-  // Seal the current undo step: close the implicit group (commits since the
-  // previous seal collapse into one entry) and open a fresh one.
+  // Seal the current undo step: commits after this one join a new step.
   // `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).
+  // checkpoint is a Ctrl-Z boundary. Idempotent: an empty step has no items.
   sealStep(): void {
-    if (this._groupOpen) {
-      this._mgr.groupEnd();
-      this._groupOpen = false;
-    }
-    this._mgr.groupStart();
-    this._groupOpen = true;
+    this._clock.step += 1;
   }
 
   // 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;
+    this._undoSteps = [];
+    this._undoTags = [];
+    this._redoTags = [];
+    this._redoRetired = 0;
+    this._clock.step += 1;
   }
 
   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();
   }
 }
+
+// The step clock a controller tags its commits with.
+export interface UndoClock {
+  step: number;
+}
+
+export interface UndoControllerHooks {
+  // A local commit outside a replay landed on the undo stack.
+  onFreshCommit?: () => void;
+  // An item was pushed onto or popped off either stack. Runs inside Loro's
+  // callback, so it must not call back into the UndoManager.
+  onStackChange?: () => void;
+}
+
+// One stream's place in a document's undo group: the Document that holds the
+// stream's state.
+export interface UndoGroupMember {
+  /** @internal This stream's controller, or `null` when it has no CRDT. */
+  _undoController(): UndoController | null;
+  /** @internal Whether this stream may replay a step now: it takes writes
+   *  and is not showing a version. */
+  _undoEligible(): boolean;
+  /** @internal True inside a `mutate` callback on this stream. */
+  _undoMutating(): boolean;
+  /** @internal Replay this stream's part of step `tag`. */
+  _replayUndoStep(dir: 'undo' | 'redo', tag: number): boolean;
+}
+
+export interface UndoGroupOwner {
+  // Whether the document refuses every replay now (closed, or showing a
+  // version), whatever each stream's own state.
+  blocked(): boolean;
+  // Re-read the document's undo state for `subscribeUndoState`.
+  notify(): void;
+  // A stream other than the owner's took a fresh undoable commit.
+  memberCommitted(): void;
+}
+
+// The undo stack of one document, across its streams. The step clock is
+// shared, so tags only grow over time document-wide: the newest step is the
+// highest tag on top of any stream's undo stack, and the most recently undone
+// step is the lowest tag on top of any redo stack. Undo replays that tag in
+// every stream whose top carries it, so a step spanning streams reverts whole.
+export class UndoGroup implements UndoClock {
+  step = 0;
+  private readonly _members = new Set<UndoGroupMember>();
+  private _owner: { member: UndoGroupMember; hooks: UndoGroupOwner } | null = null;
+  private _notifyQueued = false;
+
+  setOwner(member: UndoGroupMember, hooks: UndoGroupOwner): void {
+    this._owner = { member, hooks };
+    this._members.add(member);
+  }
+
+  isOwner(member: UndoGroupMember): boolean {
+    return this._owner?.member === member;
+  }
+
+  add(member: UndoGroupMember): void {
+    this._members.add(member);
+  }
+
+  delete(member: UndoGroupMember): void {
+    this._members.delete(member);
+  }
+
+  seal(): void {
+    this.step += 1;
+  }
+
+  // A non-owner stream's stacks moved. Deferred, because the move is reported
+  // from inside the UndoManager, which the re-read calls back into.
+  changed(): void {
+    if (this._owner === null || this._notifyQueued) return;
+    this._notifyQueued = true;
+    queueMicrotask(() => {
+      this._notifyQueued = false;
+      this._owner?.hooks.notify();
+    });
+  }
+
+  // A fresh commit replaces the history every redo stack in the document
+  // undoes back into, not only the stack of the stream it landed in.
+  freshCommit(from: UndoGroupMember): void {
+    for (const member of this._members) {
+      if (member !== from) member._undoController()?.retireRedo();
+    }
+    if (this._owner !== null && this._owner.member !== from) {
+      this._owner.hooks.memberCommitted();
+    }
+  }
+
+  private eligible(): Array<{ member: UndoGroupMember; ctl: UndoController }> {
+    const out: Array<{ member: UndoGroupMember; ctl: UndoController }> = [];
+    if (this._owner?.hooks.blocked()) return out;
+    for (const member of this._members) {
+      const ctl = member._undoController();
+      if (ctl !== null && member._undoEligible()) out.push({ member, ctl });
+    }
+    return out;
+  }
+
+  // Each stream retires its oldest steps past its own cap, and a step one
+  // stream has retired is retired in every stream, so no Undo reverts part of
+  // one.
+  private floor(): number {
+    let floor = -1;
+    for (const member of this._members) {
+      const ctl = member._undoController();
+      if (ctl !== null) floor = Math.max(floor, ctl.floor);
+    }
+    return floor;
+  }
+
+  private next(dir: 'undo' | 'redo'): number | undefined {
+    let next: number | undefined;
+    for (const { ctl } of this.eligible()) {
+      const tag = ctl.peek(dir);
+      if (tag === undefined) continue;
+      if (next === undefined || (dir === 'undo' ? tag > next : tag < next)) next = tag;
+    }
+    if (dir === 'undo' && next !== undefined && next <= this.floor()) return undefined;
+    return next;
+  }
+
+  canUndo(): boolean {
+    const floor = this.floor();
+    return this.eligible().some(({ ctl }) => {
+      const tag = ctl.peek('undo');
+      return tag !== undefined && tag > floor && ctl.canUndo();
+    });
+  }
+
+  canRedo(): boolean {
+    return this.eligible().some(({ ctl }) => ctl.canRedo());
+  }
+
+  // True when a step was replayed. Refuses inside any stream's `mutate`
+  // callback, whose open transaction holds writes the replay would commit
+  // outside the op it ships.
+  replay(dir: 'undo' | 'redo'): boolean {
+    for (const member of this._members) {
+      if (member._undoMutating()) return false;
+    }
+    const tag = this.next(dir);
+    if (tag === undefined) return false;
+    let replayed = false;
+    for (const { member, ctl } of this.eligible()) {
+      if (ctl.peek(dir) !== tag) continue;
+      if (member._replayUndoStep(dir, tag)) replayed = true;
+    }
+    return replayed;
+  }
+}

package/src/version-bar.ts

@@ -37,6 +37,9 @@ export interface VersionBarDeps {
   // The resolved dashboard/embed origin (no trailing slash); the iframe
   // loads `${dashboardBaseUrl}/embed/version-bar`.
   dashboardBaseUrl: string;
+  // The app this bar serves, sent as `appId` in the embed's init so the embed
+  // can check the framing page may host it. `undefined` before `Brass.init()`.
+  appId: string | undefined;
   // Pins the embed's light/dark theme (matches the other hosted surfaces).
   theme?: 'light' | 'dark' | 'auto';
   // Intents from the embed, routed to the live active document. The two
@@ -141,7 +144,7 @@ export function createVersionBarFrame(
   const url = new URL(`${base}/embed/version-bar`);
   url.searchParams.set('theme', theme);
   iframe.src = url.toString();
-  iframe.title = 'Document version';
+  iframe.title = 'Version';
   Object.assign(iframe.style, {
     display: 'block',
     border: '0',
@@ -235,6 +238,7 @@ export function createVersionBarFrame(
         type: 'init',
         surface: 'version-bar',
         params: {
+          ...(deps.appId !== undefined ? { appId: deps.appId } : {}),
           docId: ctx.docId,
           ...(ctx.branch !== undefined ? { branch: ctx.branch } : {}),
           version: ctx.version,

package/src/version.ts

@@ -3,6 +3,6 @@
 // can measure the version distribution of deployed apps and time
 // compatibility windows against it. A unit test pins this to
 // package.json's version; the release bump touches both together.
-export const SDK_VERSION = '0.4.1';
+export const SDK_VERSION = '0.5.0';
 
 export const SDK_CLIENT_ID = `sdk/${SDK_VERSION}`;