@ai-matrx/office 0.8.12 → 0.8.13

package/dist/univer-collab.d.cts

@@ -1,6 +1,6 @@
 import * as Y from 'yjs';
 import { Awareness } from 'y-protocols/awareness';
-import { OpSessionNotice, OpSession, OpTransport, OpPresence, OpSessionIncident, OpSessionStatus, AwarenessState } from '@ai-matrx/data/realtime/collab';
+import { OpSessionNotice, OpSession, OpTransport, OpPresence, OpSessionIncident, OpSessionStatus, AwarenessState, CollabRpcClient, collabReplace } from '@ai-matrx/data/realtime/collab';
 import { IDocumentData } from '@univerjs/core';
 import { CommitReason } from '@ai-matrx/kit/working-copy';
 
@@ -336,6 +336,12 @@ interface DocsOtPort {
     }>;
     /** Ask for a save (the record's one coalesced save). */
     markDirty(): void;
+    /** This seat's text selection in the first view (body offsets), for presence (C8). Absent when no view can say. */
+    selection?(): Array<{
+        startOffset: number;
+        endOffset: number;
+        segmentId?: string;
+    }> | null;
 }
 type DocsOtNotice = OpSessionNotice<DocsOp> | {
     kind: "not_shared";
@@ -399,6 +405,20 @@ declare function undoStacksOf(service: unknown): {
 declare function rebaseUndoStack(items: UndoItem[], remote: DocsOp): number;
 declare function openDocsOtRoom(o: OpenDocsOtRoomOptions): DocsOtRoom;
 
+interface CaretRange {
+    start: number;
+    end: number;
+}
+/** One other seat's caret, ready to draw. */
+interface RemoteCaret {
+    /** The seat (Yjs client id as a string): two tabs of one person are two carets. */
+    key: string;
+    uid: string;
+    name: string;
+    color: string;
+    ranges: CaretRange[];
+}
+
 /**
  * THE DOCUMENT MODEL — the engine of one cloud document per tab.
  *
@@ -447,6 +467,8 @@ type DocumentOtFactory = (port: DocsOtPort, onAwareness: (awareness: DocumentAwa
 interface DocumentAwareness {
     states: Map<number, AwarenessState>;
     selfUid: string;
+    /** Other seats' carets and selections (ordered-log rooms only, C8), already moved through every edit applied since. */
+    carets?: RemoteCaret[];
 }
 
 /** `collab.ot_rooms` (§12.2): which documents without a room open one. */
@@ -467,4 +489,51 @@ interface DocumentOtFactoryOptions {
 /** The `DocumentModel.startOtRoom` factory for one document. */
 declare function documentOtFactory(o: DocumentOtFactoryOptions): DocumentOtFactory;
 
-export { COLLAB_COVERED_KEY, type CollabBase, type CollabMutationInfo, type CollabProviderLike, type CommandServiceLike, DOCS_COLLAB_PROTO, DOCS_TRANSFORM_VERSION, DOC_LOCAL_KEYS, type DocsLocalMutation, type DocsLost, type DocsOp, type DocsOtNotice, type DocsOtPort, type DocsOtRoom, type DocsTransformResult, type DocumentOtFactoryOptions, type OpenDocsOtRoomOptions, type OtRoomsKnob, RICH_TEXT_EDITING, SENDER_VIEW_PARAMS, WorkbookCollabSession, type WorkbookCollabSessionOptions, applyDocsOp, canonicalDocsSnapshot, canonicalDocsString, canonicalKeys, composeDocsOps, docsStateHash, documentOtFactory, documentUsesOrderedRoom, dropEmptyStyleRetains, invertDocsOp, isCellEditorScratch, isNoopDocsOp, normalizeDocsOp, openDocsOtRoom, rebaseUndoStack, stampCovered, stampDeterministicIds, stripSenderView, takeCovered, transformDocsOp, transformTextX, undoStacksOf };
+/**
+ * Restore a saved version of a document (COLLAB-DESIGN §6.2, §20): THE one path for History, so a document with a
+ * co-editing room is never restored behind its room's back.
+ *
+ * - Open in this tab: save the restored row, then the open editor swaps it in (`showSavedSnapshot`); an ordered-log
+ *   room sends it through `collab_replace` itself (`DocumentOtHandle.replace`).
+ * - Not open in this tab but the document has a room (another tab or person has it open, or its log is ahead of its
+ *   checkpoint): `collab_replace` writes the snapshot row, the `replace` op, the checkpoint and the frame in one
+ *   transaction, so every open seat reloads. A snapshot row alone left those seats stale.
+ * - No room: a snapshot row; the next open loads it.
+ */
+
+type DocumentRestoreResult = {
+    via: "open_editor";
+    snapshotId: string;
+} | {
+    via: "room";
+    rev: number;
+    snapshotId: string;
+} | {
+    via: "saved";
+    snapshotId: string;
+};
+interface DocumentRestoreDeps {
+    client: () => CollabRpcClient;
+    roomExists: (client: CollabRpcClient, documentId: string) => Promise<boolean>;
+    replace: typeof collabReplace;
+    stateHash: (snapshot: unknown) => Promise<string>;
+    hasOpenEditor: (documentId: string) => boolean;
+    showInOpenEditor: (documentId: string, row: {
+        id: string;
+        snapshot: unknown;
+    }) => Promise<boolean>;
+    saveRow: (args: {
+        documentId: string;
+        snapshot: unknown;
+        label: string | null;
+    }) => Promise<{
+        id: string;
+    }>;
+}
+declare function restoreDocumentSnapshot(args: {
+    documentId: string;
+    snapshot: unknown;
+    label: string | null;
+}, deps?: Partial<DocumentRestoreDeps>): Promise<DocumentRestoreResult>;
+
+export { COLLAB_COVERED_KEY, type CollabBase, type CollabMutationInfo, type CollabProviderLike, type CommandServiceLike, DOCS_COLLAB_PROTO, DOCS_TRANSFORM_VERSION, DOC_LOCAL_KEYS, type DocsLocalMutation, type DocsLost, type DocsOp, type DocsOtNotice, type DocsOtPort, type DocsOtRoom, type DocsTransformResult, type DocumentOtFactoryOptions, type DocumentRestoreDeps, type DocumentRestoreResult, type OpenDocsOtRoomOptions, type OtRoomsKnob, RICH_TEXT_EDITING, SENDER_VIEW_PARAMS, WorkbookCollabSession, type WorkbookCollabSessionOptions, applyDocsOp, canonicalDocsSnapshot, canonicalDocsString, canonicalKeys, composeDocsOps, docsStateHash, documentOtFactory, documentUsesOrderedRoom, dropEmptyStyleRetains, invertDocsOp, isCellEditorScratch, isNoopDocsOp, normalizeDocsOp, openDocsOtRoom, rebaseUndoStack, restoreDocumentSnapshot, stampCovered, stampDeterministicIds, stripSenderView, takeCovered, transformDocsOp, transformTextX, undoStacksOf };

package/dist/univer-collab.d.ts

@@ -1,6 +1,6 @@
 import * as Y from 'yjs';
 import { Awareness } from 'y-protocols/awareness';
-import { OpSessionNotice, OpSession, OpTransport, OpPresence, OpSessionIncident, OpSessionStatus, AwarenessState } from '@ai-matrx/data/realtime/collab';
+import { OpSessionNotice, OpSession, OpTransport, OpPresence, OpSessionIncident, OpSessionStatus, AwarenessState, CollabRpcClient, collabReplace } from '@ai-matrx/data/realtime/collab';
 import { IDocumentData } from '@univerjs/core';
 import { CommitReason } from '@ai-matrx/kit/working-copy';
 
@@ -336,6 +336,12 @@ interface DocsOtPort {
     }>;
     /** Ask for a save (the record's one coalesced save). */
     markDirty(): void;
+    /** This seat's text selection in the first view (body offsets), for presence (C8). Absent when no view can say. */
+    selection?(): Array<{
+        startOffset: number;
+        endOffset: number;
+        segmentId?: string;
+    }> | null;
 }
 type DocsOtNotice = OpSessionNotice<DocsOp> | {
     kind: "not_shared";
@@ -399,6 +405,20 @@ declare function undoStacksOf(service: unknown): {
 declare function rebaseUndoStack(items: UndoItem[], remote: DocsOp): number;
 declare function openDocsOtRoom(o: OpenDocsOtRoomOptions): DocsOtRoom;
 
+interface CaretRange {
+    start: number;
+    end: number;
+}
+/** One other seat's caret, ready to draw. */
+interface RemoteCaret {
+    /** The seat (Yjs client id as a string): two tabs of one person are two carets. */
+    key: string;
+    uid: string;
+    name: string;
+    color: string;
+    ranges: CaretRange[];
+}
+
 /**
  * THE DOCUMENT MODEL — the engine of one cloud document per tab.
  *
@@ -447,6 +467,8 @@ type DocumentOtFactory = (port: DocsOtPort, onAwareness: (awareness: DocumentAwa
 interface DocumentAwareness {
     states: Map<number, AwarenessState>;
     selfUid: string;
+    /** Other seats' carets and selections (ordered-log rooms only, C8), already moved through every edit applied since. */
+    carets?: RemoteCaret[];
 }
 
 /** `collab.ot_rooms` (§12.2): which documents without a room open one. */
@@ -467,4 +489,51 @@ interface DocumentOtFactoryOptions {
 /** The `DocumentModel.startOtRoom` factory for one document. */
 declare function documentOtFactory(o: DocumentOtFactoryOptions): DocumentOtFactory;
 
-export { COLLAB_COVERED_KEY, type CollabBase, type CollabMutationInfo, type CollabProviderLike, type CommandServiceLike, DOCS_COLLAB_PROTO, DOCS_TRANSFORM_VERSION, DOC_LOCAL_KEYS, type DocsLocalMutation, type DocsLost, type DocsOp, type DocsOtNotice, type DocsOtPort, type DocsOtRoom, type DocsTransformResult, type DocumentOtFactoryOptions, type OpenDocsOtRoomOptions, type OtRoomsKnob, RICH_TEXT_EDITING, SENDER_VIEW_PARAMS, WorkbookCollabSession, type WorkbookCollabSessionOptions, applyDocsOp, canonicalDocsSnapshot, canonicalDocsString, canonicalKeys, composeDocsOps, docsStateHash, documentOtFactory, documentUsesOrderedRoom, dropEmptyStyleRetains, invertDocsOp, isCellEditorScratch, isNoopDocsOp, normalizeDocsOp, openDocsOtRoom, rebaseUndoStack, stampCovered, stampDeterministicIds, stripSenderView, takeCovered, transformDocsOp, transformTextX, undoStacksOf };
+/**
+ * Restore a saved version of a document (COLLAB-DESIGN §6.2, §20): THE one path for History, so a document with a
+ * co-editing room is never restored behind its room's back.
+ *
+ * - Open in this tab: save the restored row, then the open editor swaps it in (`showSavedSnapshot`); an ordered-log
+ *   room sends it through `collab_replace` itself (`DocumentOtHandle.replace`).
+ * - Not open in this tab but the document has a room (another tab or person has it open, or its log is ahead of its
+ *   checkpoint): `collab_replace` writes the snapshot row, the `replace` op, the checkpoint and the frame in one
+ *   transaction, so every open seat reloads. A snapshot row alone left those seats stale.
+ * - No room: a snapshot row; the next open loads it.
+ */
+
+type DocumentRestoreResult = {
+    via: "open_editor";
+    snapshotId: string;
+} | {
+    via: "room";
+    rev: number;
+    snapshotId: string;
+} | {
+    via: "saved";
+    snapshotId: string;
+};
+interface DocumentRestoreDeps {
+    client: () => CollabRpcClient;
+    roomExists: (client: CollabRpcClient, documentId: string) => Promise<boolean>;
+    replace: typeof collabReplace;
+    stateHash: (snapshot: unknown) => Promise<string>;
+    hasOpenEditor: (documentId: string) => boolean;
+    showInOpenEditor: (documentId: string, row: {
+        id: string;
+        snapshot: unknown;
+    }) => Promise<boolean>;
+    saveRow: (args: {
+        documentId: string;
+        snapshot: unknown;
+        label: string | null;
+    }) => Promise<{
+        id: string;
+    }>;
+}
+declare function restoreDocumentSnapshot(args: {
+    documentId: string;
+    snapshot: unknown;
+    label: string | null;
+}, deps?: Partial<DocumentRestoreDeps>): Promise<DocumentRestoreResult>;
+
+export { COLLAB_COVERED_KEY, type CollabBase, type CollabMutationInfo, type CollabProviderLike, type CommandServiceLike, DOCS_COLLAB_PROTO, DOCS_TRANSFORM_VERSION, DOC_LOCAL_KEYS, type DocsLocalMutation, type DocsLost, type DocsOp, type DocsOtNotice, type DocsOtPort, type DocsOtRoom, type DocsTransformResult, type DocumentOtFactoryOptions, type DocumentRestoreDeps, type DocumentRestoreResult, type OpenDocsOtRoomOptions, type OtRoomsKnob, RICH_TEXT_EDITING, SENDER_VIEW_PARAMS, WorkbookCollabSession, type WorkbookCollabSessionOptions, applyDocsOp, canonicalDocsSnapshot, canonicalDocsString, canonicalKeys, composeDocsOps, docsStateHash, documentOtFactory, documentUsesOrderedRoom, dropEmptyStyleRetains, invertDocsOp, isCellEditorScratch, isNoopDocsOp, normalizeDocsOp, openDocsOtRoom, rebaseUndoStack, restoreDocumentSnapshot, stampCovered, stampDeterministicIds, stripSenderView, takeCovered, transformDocsOp, transformTextX, undoStacksOf };

package/dist/univer-collab.js

@@ -900,10 +900,10 @@ function canonicalRuns(runs) {
   }
   return out;
 }
-function foldPieces(items, keyOf) {
+function foldPieces(items, keyOf2) {
   const groups = /* @__PURE__ */ new Map();
   for (const it of items ?? []) {
-    const k = keyOf(it);
+    const k = keyOf2(it);
     const g = groups.get(k) ?? [];
     g.push(it);
     groups.set(k, g);
@@ -1220,6 +1220,120 @@ import {
   supabaseOpTransport
 } from "@ai-matrx/data/realtime/collab";
 
+// src/docs/document-model.ts
+import { TextX as TextX2 } from "@univerjs/core";
+
+// src/univer/openEditorContent.ts
+var replacers = /* @__PURE__ */ new Map();
+var keyOf = (kind, recordId) => `${kind}:${recordId}`;
+function hasOpenEditorContent(kind, recordId) {
+  return replacers.has(keyOf(kind, recordId));
+}
+async function showSavedSnapshot(kind, recordId, row) {
+  const replace = replacers.get(keyOf(kind, recordId));
+  if (!replace) return false;
+  await replace(row);
+  return true;
+}
+
+// src/docs/document-model.ts
+function moveRangesThroughBodyEdit(ranges, actions) {
+  const a = actions;
+  if (!Array.isArray(a) || a[0] !== "body") return null;
+  const sub = a[1];
+  if (!sub || sub.et !== "text-x" || !Array.isArray(sub.e)) return null;
+  const e = sub.e;
+  return ranges.map((r) => {
+    const collapsed = r.startOffset === r.endOffset;
+    const startOffset = TextX2.transformPosition(e, r.startOffset, collapsed);
+    return { startOffset, endOffset: collapsed ? startOffset : TextX2.transformPosition(e, r.endOffset, true) };
+  });
+}
+
+// src/docs/remote-carets.ts
+var CARET_HEARTBEAT_MS = 2e3;
+var CARET_STALE_MS = 12e3;
+var CARET_MAX_RANGES = 4;
+function publishedCaretFromSelection(sel, now) {
+  if (!sel || sel.length === 0) return null;
+  if (sel.some((r) => r.segmentId)) return null;
+  const ranges = sel.slice(0, CARET_MAX_RANGES).map((r) => ({ start: Math.min(r.startOffset, r.endOffset), end: Math.max(r.startOffset, r.endOffset) }));
+  return { ranges, at: now };
+}
+var sameRanges = (a, b) => a.length === b.length && a.every((r, i) => r.start === b[i].start && r.end === b[i].end);
+function readCaret(raw) {
+  const c = raw?.caret;
+  if (!c || !Array.isArray(c.ranges) || typeof c.at !== "number") return null;
+  const ranges = [];
+  for (const r of c.ranges.slice(0, CARET_MAX_RANGES)) {
+    const s = r?.start;
+    const e = r?.end;
+    if (typeof s !== "number" || typeof e !== "number" || !Number.isFinite(s) || !Number.isFinite(e) || s < 0 || e < 0) return null;
+    ranges.push({ start: s, end: e });
+  }
+  return ranges.length ? { ranges, at: c.at } : null;
+}
+var RemoteCaretBook = class {
+  constructor(selfClientId, now = Date.now) {
+    this.selfClientId = selfClientId;
+    this.now = now;
+  }
+  selfClientId;
+  now;
+  carets = /* @__PURE__ */ new Map();
+  /** Take the room's awareness states: new or republished carets replace ours, seats that left are dropped. Returns whether anything changed. */
+  ingest(states) {
+    let changed = false;
+    const seen = /* @__PURE__ */ new Set();
+    states.forEach((raw, id) => {
+      if (id === this.selfClientId) return;
+      const s = raw;
+      const caret = readCaret(raw);
+      if (!s || typeof s.uid !== "string" || !caret) return;
+      const key = String(id);
+      seen.add(key);
+      const prev = this.carets.get(key);
+      const name = typeof s.name === "string" && s.name ? s.name : "Someone";
+      const color = typeof s.color === "string" && s.color ? s.color : "#3b82f6";
+      if (prev && prev.at === caret.at && prev.name === name && prev.color === color) return;
+      this.carets.set(key, { key, uid: s.uid, name, color, ranges: caret.ranges, at: caret.at, seenAt: this.now() });
+      changed = true;
+    });
+    for (const key of [...this.carets.keys()]) {
+      if (!seen.has(key)) {
+        this.carets.delete(key);
+        changed = true;
+      }
+    }
+    return changed;
+  }
+  /** Move every caret through one body edit that was just applied (`actions` of a rich-text mutation). Returns whether any moved. */
+  shiftThrough(actions) {
+    let moved = false;
+    for (const c of this.carets.values()) {
+      const next = moveRangesThroughBodyEdit(c.ranges.map((r) => ({ startOffset: r.start, endOffset: r.end })), actions);
+      if (!next) return false;
+      const ranges = next.map((r) => ({ start: r.startOffset, end: r.endOffset }));
+      if (!sameRanges(ranges, c.ranges)) {
+        c.ranges = ranges;
+        moved = true;
+      }
+    }
+    return moved;
+  }
+  /** The carets to draw now (stale ones left out). */
+  list() {
+    const t = this.now();
+    const out = [];
+    for (const c of this.carets.values()) {
+      if (t - c.seenAt > CARET_STALE_MS) continue;
+      out.push({ key: c.key, uid: c.uid, name: c.name, color: c.color, ranges: c.ranges.map((r) => ({ ...r })) });
+    }
+    out.sort((a, b) => a.key.localeCompare(b.key));
+    return out;
+  }
+};
+
 // src/docs/document-service.ts
 import { requireOrganizationContext } from "@ai-matrx/api";
 import { getClaimsUser } from "@ai-matrx/auth";
@@ -1292,11 +1406,11 @@ function pickColor2(uid) {
   return palette[Math.abs(h) % palette.length] ?? "#ec4899";
 }
 function documentOtFactory(o) {
-  return async (port, onAwareness) => {
+  return async (basePort, onAwareness) => {
     const latest = await getLatestDocumentSnapshot(o.documentId);
     if (!latest.success) throw new Error(latest.error);
     if (!latest.data) {
-      const mounted = port.snapshot();
+      const mounted = basePort.snapshot();
       if (mounted) {
         const saved = await saveDocumentSnapshot({ documentId: o.documentId, snapshot: mounted, origin: "autosave" });
         if (!saved.success) throw new Error(saved.error);
@@ -1305,7 +1419,31 @@ function documentOtFactory(o) {
     const doc = new Y2.Doc();
     const awareness = new Awareness2(doc);
     awareness.setLocalState({ uid: o.uid, clientId: o.clientId, name: o.displayName ?? o.uid.slice(0, 8), color: pickColor2(o.uid), ts: Date.now() });
-    const publishAwareness = () => onAwareness({ states: new Map(awareness.getStates()), selfUid: o.uid });
+    const carets = new RemoteCaretBook(awareness.clientID);
+    const emit = () => onAwareness({ states: new Map(awareness.getStates()), selfUid: o.uid, carets: carets.list() });
+    const publishAwareness = () => {
+      carets.ingest(awareness.getStates());
+      emit();
+    };
+    const bodyActions = (params) => {
+      const p = params;
+      return p && !p.segmentId ? p.actions : void 0;
+    };
+    const port = {
+      ...basePort,
+      applyRemote(id, params) {
+        basePort.applyRemote(id, params);
+        const a = bodyActions(params);
+        if (a !== void 0 && carets.shiftThrough(a)) emit();
+      },
+      onLocal: (listener) => basePort.onLocal((m) => {
+        if (m.id === RICH_TEXT_EDITING) {
+          const a = bodyActions(m.params);
+          if (a !== void 0 && carets.shiftThrough(a)) emit();
+        }
+        listener(m);
+      })
+    };
     awareness.on("change", publishAwareness);
     const provider = new SupabaseYjsProvider({
       workbookId: o.documentId,
@@ -1341,11 +1479,31 @@ function documentOtFactory(o) {
       ...o.onStatus ? { onStatus: o.onStatus } : {}
     });
     await room.session.ready;
+    let lastKey = "";
+    let lastAt = 0;
+    const publishCaret = () => {
+      if (typeof document !== "undefined" && document.hidden) return;
+      let sel = null;
+      try {
+        sel = port.selection?.() ?? null;
+      } catch {
+        sel = null;
+      }
+      const t = Date.now();
+      const c = publishedCaretFromSelection(sel, t);
+      const key = c ? JSON.stringify(c.ranges) : "";
+      if (key === lastKey && (key === "" || t - lastAt < CARET_HEARTBEAT_MS)) return;
+      lastKey = key;
+      lastAt = t;
+      awareness.setLocalStateField("caret", c);
+    };
+    const caretTimer = setInterval(publishCaret, 120);
     return {
       isSaver: () => room.isSaver(),
       write: (reason) => room.write(reason),
       replace: (snapshot) => room.replace(snapshot),
       stop: () => {
+        clearInterval(caretTimer);
         room.stop();
         awareness.off("change", publishAwareness);
         provider.disconnect();
@@ -1355,6 +1513,43 @@ function documentOtFactory(o) {
     };
   };
 }
+
+// src/docs/document-restore.ts
+import { collabReplace as collabReplace2, collabRoomExists as collabRoomExists2 } from "@ai-matrx/data/realtime/collab";
+var defaultDeps = {
+  client: () => getDocsHost().getSupabase(),
+  roomExists: collabRoomExists2,
+  replace: collabReplace2,
+  stateHash: (snapshot) => docsStateHash(snapshot),
+  hasOpenEditor: (documentId) => hasOpenEditorContent("document", documentId),
+  showInOpenEditor: (documentId, row) => showSavedSnapshot("document", documentId, row),
+  async saveRow(args) {
+    const res = await saveDocumentSnapshot({ documentId: args.documentId, snapshot: args.snapshot, origin: "restored", label: args.label });
+    if (!res.success) throw new Error(res.error);
+    return { id: res.data.id };
+  }
+};
+async function restoreDocumentSnapshot(args, deps = {}) {
+  const d = { ...defaultDeps, ...deps };
+  if (d.hasOpenEditor(args.documentId)) {
+    const row2 = await d.saveRow(args);
+    await d.showInOpenEditor(args.documentId, { id: row2.id, snapshot: args.snapshot });
+    return { via: "open_editor", snapshotId: row2.id };
+  }
+  const client = d.client();
+  if (await d.roomExists(client, args.documentId)) {
+    const next = stampDeterministicIds(structuredClone(args.snapshot ?? {}));
+    const out = await d.replace(client, {
+      roomId: args.documentId,
+      snapshot: next,
+      stateHash: await d.stateHash(next),
+      origin: "restore"
+    });
+    return { via: "room", rev: out.rev, snapshotId: out.ref };
+  }
+  const row = await d.saveRow(args);
+  return { via: "saved", snapshotId: row.id };
+}
 export {
   COLLAB_COVERED_KEY,
   DOCS_COLLAB_PROTO,
@@ -1378,6 +1573,7 @@ export {
   normalizeDocsOp,
   openDocsOtRoom,
   rebaseUndoStack,
+  restoreDocumentSnapshot,
   stampCovered,
   stampDeterministicIds,
   stripSenderView,