@ai-matrx/office 0.7.0 → 0.8.0

package/dist/docs.d.ts

@@ -178,6 +178,60 @@ type CommandServiceLike = {
     syncExecuteCommand(id: string, params: MutationParams, options?: ExecuteOptions): unknown;
 };
 
+/**
+ * The Docs co-editing room on the ordered log (COLLAB-DESIGN §6, unit C3): the `OpDocumentAdapter` for
+ * `openOpSession` over a document's editors, plus saves, restore and the saver choice.
+ *
+ * - CAPTURE (§6.3). The document model hands over every local `doc.mutation.rich-text-editing` with the applied
+ *   params (the handler's own rewrite, C0 surprise 6), the pre-state cloned in `beforeCommandExecuted`, and the
+ *   outermost command id. `onlyLocal` / `fromCollab` never arrive here (the model filters them). Only `segmentId`
+ *   and `actions` travel; the inverse is computed from the APPLIED actions on a COPY (`invertWithDoc` mutates its
+ *   op). Each mutation goes to the session as it happens, so a remote apply can never land between a local
+ *   mutation and its hand-over; the command id rides along as the change's label.
+ * - APPLY (§6.7). `syncExecuteCommand(id, { unitId: own, segmentId, actions, textRanges: null,
+ *   noNeedSetTextRange: true }, { onlyLocal: true, fromCollab: true })` through the model (every view of the
+ *   document in this tab). A throw, `false`, or actions the handler emptied fail the apply: the session rebuilds,
+ *   never skips. While an IME composition is open, remote applies QUEUE (acks continue); a local op captured
+ *   meanwhile is rebased over the queue (`L' = T(L, Q, 'left')`, `Q' = T(Q, L, 'right')`), and the queue drains
+ *   at `compositionend`.
+ * - UNDO (§6.9). Each applied remote op rebases every stored undo and redo item of this seat
+ *   (`T(item, R1, 'left')`); `textRanges` and `layoutState` are stripped from rebased items; an item whose rebase
+ *   is a barrier, throws or comes back empty is dropped. Undo therefore only ever reverts this person's changes.
+ * - SAVES (§7.3). Only a quiet seat whose hash matches every peer at its rev saves, and only the chosen saver
+ *   (the lowest client id among seats publishing a quiet hash) saves on its own; a manual save always tries.
+ * - RESTORE (§20). A whole-document replace goes through `collab_replace`: the snapshot is loaded into this seat's
+ *   editor first, so the stored snapshot and its hash are the Univer-normalised form every seat will load.
+ */
+
+/** One local mutation as the document model hands it over. */
+interface DocsLocalMutation {
+    id: string;
+    params: unknown;
+    /** The document before this mutation (cloned in `beforeCommandExecuted`), when the view could supply it. */
+    pre: unknown | null;
+    /** The outermost command this mutation belongs to (the depth tracker with its try/finally guard). */
+    cmd: string | null;
+    /** Whether the mutation changes what a snapshot stores. */
+    content: boolean;
+}
+/** What the document model lends the room (implemented by `DocumentModel`). */
+interface DocsOtPort {
+    onLocal(listener: (m: DocsLocalMutation) => void): () => void;
+    /** Apply one committed mutation to every view of the document; throws when any view could not. */
+    applyRemote(id: string, params: Record<string, unknown>): void;
+    /** The document as the editor holds it now (`doc.save()`), or null when no view is mounted. */
+    snapshot(): unknown | null;
+    /** Replace the document in every view (and the kept editor). */
+    load(snapshot: unknown): void;
+    /** Univer's undo/redo service of each mounted view and the unit it holds. */
+    undoTargets(): Array<{
+        service: unknown;
+        unitId: string;
+    }>;
+    /** Ask for a save (the record's one coalesced save). */
+    markDirty(): void;
+}
+
 /**
  * THE DOCUMENT MODEL — the engine of one cloud document per tab.
  *
@@ -226,6 +280,8 @@ interface DocumentViewPort {
     remount: (snapshot: DocumentSnapshotData) => void;
     /** Whether this view may change the document (read at edit time). */
     editable: () => boolean;
+    /** Univer's undo/redo service of this view's instance (the co-editing room rebases its items, §6.9). */
+    undoRedo?: () => unknown;
     /**
      * The Univer unit id of this view's mounted document. Every seat mounts its own unit, so a
      * mutation carries the SENDER's id and must be re-addressed to this view's unit before it is
@@ -257,6 +313,14 @@ interface DocumentModelDeps {
     /** A mutation could not be applied to a view: the app says so (a notice); the model re-syncs from the saved version. */
     onApplyFailed?: (documentId: string, mutationId: string, error: unknown) => void;
 }
+/** The document's room on the ordered log (COLLAB-DESIGN §6, C3), bound through `startOtRoom`. */
+interface DocumentOtHandle {
+    stop: () => void;
+    write: (reason: CommitReason) => Promise<boolean>;
+    replace: (snapshot: DocumentSnapshotData) => Promise<void>;
+    isSaver: () => boolean;
+}
+type DocumentOtFactory = (port: DocsOtPort, onAwareness: (awareness: DocumentAwareness) => void) => Promise<DocumentOtHandle | null>;
 /** A collab room (WorkbookCollabSession) bound to the model's command stream. */
 interface DocumentCollabHandle {
     stop: () => void;
@@ -314,6 +378,10 @@ declare class DocumentModel {
     private readonly knownSnapshots;
     private readonly collabListeners;
     private collab;
+    /** The ordered-log room (C3); exclusive with `collab` (the 0.6 relay room). */
+    private ot;
+    private otStarting;
+    private readonly otListeners;
     /** The saved snapshot the body started from, and the room entries it already holds. */
     private baseId;
     private baseCovered;
@@ -347,6 +415,13 @@ declare class DocumentModel {
     /** The kept editor, handed to the view that mounts next (null when none is kept). */
     takeParkedEditor(): ParkedDocumentEditor | null;
     private onViewMutation;
+    /**
+     * Per view: the outermost command running (a mutation's group label) and, while a room listens, the document
+     * before each rich-text mutation (its inverse is computed from the APPLIED actions against this copy). Univer's
+     * `executeCommand` has no `finally`: a command that mutates then throws never fires `onCommandExecuted`, so
+     * the depth is restored in a try/finally around the instance's `executeCommand` (C0 surprise 7).
+     */
+    private trackCommands;
     /** The unit id a view's document has (what a replayed mutation must be addressed to). */
     private unitIdOf;
     /** Replay one mutation into every view except `exceptViewId`, addressed to each view's own unit. */
@@ -390,7 +465,7 @@ declare class DocumentModel {
     replaceContent(row: {
         id: string;
         snapshot: DocumentSnapshotData;
-    }): void;
+    }): void | Promise<void>;
     /** A peer replaced the document: show the newest save (once). */
     private onPeerReplaced;
     /** A loaded row becomes the base: its content (what views mount) and the room entries it holds. */
@@ -404,6 +479,12 @@ declare class DocumentModel {
     private readonly virtualCommandService;
     /** Join the document's collab room once (the first view that asks). */
     startCollab(factory: DocumentCollabFactory): Promise<void>;
+    /** The model as the ordered-log room sees it (COLLAB-DESIGN §6.7: the model is the client, not the view). */
+    private readonly otPort;
+    /** Join the document's ordered-log room once (C3). Exclusive with `startCollab`. */
+    startOtRoom(factory: DocumentOtFactory): Promise<void>;
+    /** Which co-editing room this document is in right now. */
+    collabMode(): "ordered" | "relay" | null;
     isCollabHost(): boolean;
     getAwareness(): DocumentAwareness | null;
     subscribeAwareness(listener: () => void): () => void;
@@ -602,4 +683,4 @@ declare function documentBodyWriteHandler(deps: {
     assertWritable: (whatItBlocks: string) => void;
 }): DocumentBodyWriteHandler;
 
-export { type BodyEdit, type BodyText, type CreateDocumentArgs, DOCUMENT_BODY_MAX_LENGTH, DOCUMENT_DESCRIPTION_MAX_LENGTH, DOCUMENT_NAME_MAX_LENGTH, DOCUMENT_SAVE_DELAY_MS, type DocsHostPorts, type DocsSupabase, type DocumentAwareness, type DocumentBodyPort, type DocumentBodyWriteHandler, type DocumentCollabBase, type DocumentCollabFactory, type DocumentCollabHandle, DocumentModel, type DocumentModelDeps, type DocumentSnapshotData, type DocumentViewPort, EMOJI_GROUPS, type Glyph, MIN_FIT_ZOOM, type ParkedDocumentEditor, SPECIAL_GROUPS, type SaveDocumentSnapshotArgs, bodyTextOf, configureDocsHost, copyDocument, createDocument, deleteDocument, discardFailedDocument, documentBodyWriteHandler, documentSourceLabel, fitZoomRatio, getDocsHost, getDocument, getLatestDocumentSnapshot, listAccessibleDocuments, listDocumentSnapshots, listTrashedDocuments, moveDocument, planBodyEdit, renameDocument, restoreDocument, sanitizeUniverDocSnapshot, saveDocumentSnapshot, searchSymbols, updateDocumentDescription, validateDocumentBody, validateDocumentDescription, validateDocumentName, writeBodyText };
+export { type BodyEdit, type BodyText, type CreateDocumentArgs, DOCUMENT_BODY_MAX_LENGTH, DOCUMENT_DESCRIPTION_MAX_LENGTH, DOCUMENT_NAME_MAX_LENGTH, DOCUMENT_SAVE_DELAY_MS, type DocsHostPorts, type DocsSupabase, type DocumentAwareness, type DocumentBodyPort, type DocumentBodyWriteHandler, type DocumentCollabBase, type DocumentCollabFactory, type DocumentCollabHandle, DocumentModel, type DocumentModelDeps, type DocumentOtFactory, type DocumentOtHandle, type DocumentSnapshotData, type DocumentViewPort, EMOJI_GROUPS, type Glyph, MIN_FIT_ZOOM, type ParkedDocumentEditor, SPECIAL_GROUPS, type SaveDocumentSnapshotArgs, bodyTextOf, configureDocsHost, copyDocument, createDocument, deleteDocument, discardFailedDocument, documentBodyWriteHandler, documentSourceLabel, fitZoomRatio, getDocsHost, getDocument, getLatestDocumentSnapshot, listAccessibleDocuments, listDocumentSnapshots, listTrashedDocuments, moveDocument, planBodyEdit, renameDocument, restoreDocument, sanitizeUniverDocSnapshot, saveDocumentSnapshot, searchSymbols, updateDocumentDescription, validateDocumentBody, validateDocumentDescription, validateDocumentName, writeBodyText };

package/dist/docs.js

@@ -45,6 +45,9 @@ function takeCovered(snapshot) {
 }
 
 // src/docs/document-model.ts
+var RICH_TEXT_EDITING_ID = "doc.mutation.rich-text-editing";
+var COMMAND_TYPE = 0;
+var DEPTH_GUARDED = /* @__PURE__ */ Symbol.for("ai-matrx.office.docs.command-depth-guard");
 var DOCUMENT_SAVE_DELAY_MS = 2500;
 var viewIds = 0;
 var DocumentModel = class {
@@ -61,6 +64,10 @@ var DocumentModel = class {
   knownSnapshots = /* @__PURE__ */ new Set();
   collabListeners = /* @__PURE__ */ new Set();
   collab = null;
+  /** The ordered-log room (C3); exclusive with `collab` (the 0.6 relay room). */
+  ot = null;
+  otStarting = null;
+  otListeners = /* @__PURE__ */ new Set();
   /** The saved snapshot the body started from, and the room entries it already holds. */
   baseId = null;
   baseCovered = /* @__PURE__ */ new Set();
@@ -124,7 +131,14 @@ var DocumentModel = class {
     const subscription = port.commandService.onMutationExecutedForCollab(
       (info, options) => this.onViewMutation(id, info, options)
     );
-    this.views.set(id, { id, port, dispose: () => subscription.dispose() });
+    const view = { id, port, dispose: () => {
+    }, commands: [], pre: null };
+    const hooks = this.trackCommands(view);
+    view.dispose = () => {
+      subscription.dispose();
+      hooks();
+    };
+    this.views.set(id, view);
     if (!this.handle.hasPending()) {
       try {
         const mounted = port.snapshot();
@@ -137,8 +151,8 @@ var DocumentModel = class {
     return () => {
       if (detached) return;
       detached = true;
-      const view = this.views.get(id);
-      if (!view) return;
+      const view2 = this.views.get(id);
+      if (!view2) return;
       if (this.views.size === 1) {
         try {
           const snapshot = port.snapshot();
@@ -147,7 +161,7 @@ var DocumentModel = class {
           console.warn(`[document-model] could not keep ${this.documentId}'s last view's document`, error);
         }
       }
-      view.dispose();
+      view2.dispose();
       this.views.delete(id);
       if (this.lastEditedView === id) this.lastEditedView = null;
     };
@@ -177,8 +191,63 @@ var DocumentModel = class {
     this.lastEditedView = viewId;
     this.relay(info, viewId);
     for (const listener of this.collabListeners) listener(info, options);
+    if (this.otListeners.size && !options?.onlyLocal) {
+      const m = {
+        id: info.id,
+        params: info.params,
+        pre: info.id === RICH_TEXT_EDITING_ID ? view.pre : null,
+        cmd: view.commands[0] ?? null,
+        content: isContentMutation(info)
+      };
+      view.pre = null;
+      for (const listener of Array.from(this.otListeners)) listener(m);
+    }
     if (isContentMutation(info)) this.markDirty();
   }
+  /**
+   * Per view: the outermost command running (a mutation's group label) and, while a room listens, the document
+   * before each rich-text mutation (its inverse is computed from the APPLIED actions against this copy). Univer's
+   * `executeCommand` has no `finally`: a command that mutates then throws never fires `onCommandExecuted`, so
+   * the depth is restored in a try/finally around the instance's `executeCommand` (C0 surprise 7).
+   */
+  trackCommands(view) {
+    const cs = view.port.commandService;
+    if (typeof cs.beforeCommandExecuted !== "function" || typeof cs.onCommandExecuted !== "function") return () => {
+    };
+    const before = cs.beforeCommandExecuted((info) => {
+      if (info.type === COMMAND_TYPE) view.commands.push(info.id);
+      else if (info.id === RICH_TEXT_EDITING_ID && this.otListeners.size && !this.relaying) {
+        try {
+          const snap = view.port.snapshot();
+          view.pre = snap ? structuredClone(snap) : null;
+        } catch {
+          view.pre = null;
+        }
+      }
+    });
+    const after = cs.onCommandExecuted((info) => {
+      if (info.type !== COMMAND_TYPE) return;
+      const at = view.commands.lastIndexOf(info.id);
+      if (at >= 0) view.commands.splice(at, 1);
+    });
+    const guarded = cs;
+    if (typeof cs.executeCommand === "function" && !guarded[DEPTH_GUARDED]) {
+      const original = cs.executeCommand.bind(cs);
+      guarded[DEPTH_GUARDED] = true;
+      cs.executeCommand = async (id, params, options) => {
+        const depth = view.commands.length;
+        try {
+          return await original(id, params, options);
+        } finally {
+          if (view.commands.length > depth) view.commands.length = depth;
+        }
+      };
+    }
+    return () => {
+      before.dispose();
+      after.dispose();
+    };
+  }
   /** The unit id a view's document has (what a replayed mutation must be addressed to). */
   unitIdOf(view) {
     try {
@@ -242,6 +311,11 @@ var DocumentModel = class {
    * peer's edits reach it through the room). An explicit Save always writes.
    */
   async write(reason) {
+    if (this.ot) {
+      const wrote = await this.ot.write(reason);
+      if (wrote) this.deps.onSaved?.(this.documentId, reason === "manual" ? "manual" : "autosave");
+      return wrote;
+    }
     const snapshot = this.latest();
     if (!snapshot) throw new Error("There is no open document to save.");
     if (this.collab && !this.collab.isHost() && reason !== "manual") return false;
@@ -286,7 +360,7 @@ var DocumentModel = class {
    * person chooses; `overUnsaved` is "Take theirs" (`./documentModels.ts`).
    */
   async onRemoteSnapshot(snapshotId, { overUnsaved = false } = {}) {
-    if (this.collab) return;
+    if (this.collab || this.ot) return;
     if (this.knownSnapshots.has(snapshotId)) return;
     if (this.saving) return;
     if (this.hasUnsaved() && !overUnsaved) {
@@ -305,6 +379,7 @@ var DocumentModel = class {
    * room the peers reload it and the shared log is emptied.
    */
   replaceContent(row) {
+    if (this.ot) return this.ot.replace(row.snapshot);
     this.show(row);
     this.collab?.announceReplaced(row.id);
   }
@@ -388,7 +463,79 @@ var DocumentModel = class {
     }
     return this.collabStarting;
   }
+  /** The model as the ordered-log room sees it (COLLAB-DESIGN §6.7: the model is the client, not the view). */
+  otPort = {
+    onLocal: (listener) => {
+      this.otListeners.add(listener);
+      return () => void this.otListeners.delete(listener);
+    },
+    applyRemote: (id, params) => {
+      if (this.views.size === 0) throw new Error("no view of the document is mounted");
+      this.relaying = true;
+      try {
+        for (const view of this.views.values()) {
+          const unitId = this.unitIdOf(view);
+          const input = Array.isArray(params.actions) ? params.actions.length : 0;
+          const p = { ...params, ...unitId ? { unitId } : {}, textRanges: null, noNeedSetTextRange: true };
+          const ok = view.port.commandService.syncExecuteCommand(id, p, { onlyLocal: true, fromCollab: true });
+          if (ok === false) throw new Error(`"${id}" was refused by the editor`);
+          if (input > 0 && Array.isArray(p.actions) && p.actions.length === 0) throw new Error(`"${id}" was emptied by the editor`);
+        }
+      } finally {
+        this.relaying = false;
+      }
+      if (isContentMutation({ id, type: 2, params })) this.markDirty();
+    },
+    snapshot: () => this.latest(),
+    load: (snapshot) => {
+      const s2 = snapshot;
+      this.stored = s2;
+      this.savedFingerprint = contentFingerprint(s2);
+      this.relaying = true;
+      try {
+        for (const view of this.views.values()) view.port.remount(s2);
+        this.parked?.remount(s2);
+      } finally {
+        this.relaying = false;
+      }
+    },
+    undoTargets: () => {
+      const out = [];
+      for (const view of this.views.values()) {
+        const unitId = this.unitIdOf(view);
+        const service = view.port.undoRedo?.();
+        if (unitId && service) out.push({ service, unitId });
+      }
+      return out;
+    },
+    markDirty: () => this.markDirty()
+  };
+  /** Join the document's ordered-log room once (C3). Exclusive with `startCollab`. */
+  startOtRoom(factory) {
+    if (this.ot || this.collab) return Promise.resolve();
+    if (!this.otStarting) {
+      this.otStarting = factory(this.otPort, (awareness) => {
+        this.awareness = awareness;
+        for (const listener of Array.from(this.awarenessListeners)) listener();
+      }).then((handle) => {
+        if (!handle) return;
+        if (this.views.size === 0) {
+          handle.stop();
+          return;
+        }
+        this.ot = handle;
+      }).finally(() => {
+        this.otStarting = null;
+      });
+    }
+    return this.otStarting;
+  }
+  /** Which co-editing room this document is in right now. */
+  collabMode() {
+    return this.ot ? "ordered" : this.collab ? "relay" : null;
+  }
   isCollabHost() {
+    if (this.ot) return this.ot.isSaver();
     return this.collab ? this.collab.isHost() : true;
   }
   getAwareness() {
@@ -416,6 +563,8 @@ var DocumentModel = class {
   rest() {
     this.collab?.stop();
     this.collab = null;
+    this.ot?.stop();
+    this.ot = null;
     this.awareness = null;
   }
   closed = false;