@ai-matrx/office 0.7.0 → 0.8.0

package/dist/univer-collab.d.cts

@@ -1,5 +1,8 @@
 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 { IDocumentData } from '@univerjs/core';
+import { CommitReason } from '@ai-matrx/kit/working-copy';
 
 /**
  * A saved snapshot names the collab-room entries it already holds, so a seat that boots from it never
@@ -210,4 +213,252 @@ declare const SENDER_VIEW_PARAMS: readonly string[];
 declare function stripSenderView(params: MutationParams): MutationParams;
 declare function isCellEditorScratch(info: Pick<CollabMutationInfo, "id">): boolean;
 
-export { COLLAB_COVERED_KEY, type CollabBase, type CollabMutationInfo, type CollabProviderLike, type CommandServiceLike, SENDER_VIEW_PARAMS, WorkbookCollabSession, type WorkbookCollabSessionOptions, isCellEditorScratch, stampCovered, stripSenderView, takeCovered };
+type Act = Record<string, any> & {
+    t: "i" | "r" | "d";
+    len: number;
+};
+/** One `lost` entry: what a transform dropped from either side (R1), for the author's notice. */
+interface DocsLost {
+    rule: string;
+    side: "insert" | "delete";
+    len: number;
+    text?: string;
+}
+/** The travelling shape of a Docs JSON op: text-x edits normalised (R1 zones, R5, no oldBody). */
+declare function normalizeDocsOp<T>(op: T): T;
+/** R6: a retain whose style lost every key to the other side is a plain retain. */
+declare function dropEmptyStyleRetains<T>(op: T): T;
+/** x rewritten to apply after y over one text-x body; `side` is x's side. Drops land in `lost` (R1). */
+declare function transformTextX(xIn: Act[], yIn: Act[], side: "left" | "right", lost?: DocsLost[]): Act[];
+/** A Docs operation: an ot-json1 op over the whole Univer snapshot (what `rich-text-editing` carries as `actions`). */
+type DocsOp = unknown[] | null;
+interface DocsTransformResult {
+    op: DocsOp;
+    lost: DocsLost[];
+}
+/**
+ * `T(x, y, side)` for Docs: ot-json1 `transformNoConflict` (never throws on DROP_COLLISION / RM_UNEXPECTED_CONTENT /
+ * BLACKHOLE, §3) with our text-x transform registered only for the duration of one call, so Univer's own apply is
+ * untouched even when the bundler shares one ot-json1 instance with `@univerjs/core`. R6 runs on the result.
+ */
+declare function transformDocsOp(x: DocsOp, y: DocsOp, side: "left" | "right"): DocsTransformResult;
+/** `a` then `b` as one op (TextX is the subtype every reader composes with). */
+declare function composeDocsOps(a: DocsOp, b: DocsOp): DocsOp;
+declare function isNoopDocsOp(op: DocsOp): boolean;
+/** Apply an op to a plain snapshot (tests, the fold). Univer's own JSONX, so TextX applies as the editor applies. */
+declare function applyDocsOp<T>(doc: T, op: DocsOp): T;
+/** The inverse of `op` against the state it applied to. JSONX.invertWithDoc MUTATES its op: invert a copy (C0). */
+declare function invertDocsOp(op: DocsOp, preDoc: unknown): DocsOp;
+/** Part of `proto` (§6.4): Univer 1.0.4 + this transformer, rules R1–R6. */
+declare const DOCS_TRANSFORM_VERSION = "univer-1.0.4+docs-ot-r6";
+
+/**
+ * The canonical Docs state hash (COLLAB-DESIGN §7.2; C0 item 6, `spikes/c0-collab/lib.mjs`).
+ *
+ * SHA-256 of the canonical snapshot: keys sorted, empty values dropped, the unit id and seat-local fields
+ * removed (revision counter, collab stamps, layout state, selections), adjacent equal text runs merged, split
+ * pieces of one custom range or decoration folded, and `paragraphId` dropped (Univer's TextX.apply mints a
+ * random one per seat, C0 surprise 3). Header, footer and note bodies get the same rules.
+ *
+ * Two seats with equal content hash equal; one character more hashes differently. Browser and Node: the
+ * digest is Web Crypto's.
+ */
+/** Never content: the collab stamps, revision counters, seat-local view state. */
+declare const DOC_LOCAL_KEYS: string[];
+/** The canonical Docs snapshot: content only, keys sorted, runs normalised, local fields removed. */
+declare function canonicalDocsSnapshot(snapshot: unknown): unknown;
+/** The canonical form as the string the hash digests (tests compare these directly). */
+declare const canonicalDocsString: (snapshot: unknown) => string;
+/** SHA-256 hex of the canonical snapshot (§7.2). */
+declare function docsStateHash(snapshot: unknown): Promise<string>;
+/**
+ * Ids every seat agrees on for a snapshot that lacks them (C0 surprise 5): a raw snapshot (an import, markdown)
+ * loaded on two seats would otherwise get two random `sectionId`s / `paragraphId`s. Missing ids become
+ * positional ones; ids already present are kept. Applied to every snapshot a room loads.
+ */
+declare function stampDeterministicIds<T>(snapshot: T): T;
+
+/**
+ * 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.
+ */
+
+declare const RICH_TEXT_EDITING = "doc.mutation.rich-text-editing";
+/**
+ * The room's protocol (§6.4): Univer 1.0.4 + transformer `DOCS_TRANSFORM_VERSION`. Any Univer or transformer
+ * change raises it; a room at another proto opens read-only for this build.
+ */
+declare const DOCS_COLLAB_PROTO = 1;
+/** 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;
+}
+type DocsOtNotice = OpSessionNotice<DocsOp> | {
+    kind: "not_shared";
+    mutationId: string;
+} | {
+    kind: "not_live";
+};
+interface OpenDocsOtRoomOptions {
+    port: DocsOtPort;
+    transport: OpTransport;
+    clientId: string;
+    presence?: OpPresence;
+    /** `collab_replace` for this room (restore, whole import). */
+    replace: (req: {
+        snapshot: unknown;
+        stateHash: string;
+        clientId: string;
+    }) => Promise<{
+        rev: number;
+        ref: string;
+    }>;
+    onNotice?: (n: DocsOtNotice) => void;
+    onIncident?: (i: OpSessionIncident) => void;
+    onStatus?: (s: OpSessionStatus) => void;
+    /** Watch IME composition here (default: `document`). */
+    compositionTarget?: Pick<Document, "addEventListener" | "removeEventListener"> | null;
+}
+interface DocsOtRoom {
+    session: OpSession<DocsOp>;
+    /** The record's save: a checkpoint at a quiet point (§7.3). False when this seat does not write now. */
+    write(reason: "manual" | string): Promise<boolean>;
+    /** Restore / whole import through `collab_replace` (§20). */
+    replace(snapshot: unknown): Promise<void>;
+    /** This seat is the one that saves on its own. */
+    isSaver(): boolean;
+    stop(): void;
+}
+interface UndoItem {
+    unitID?: string;
+    undoMutations?: Array<{
+        id: string;
+        params: Record<string, unknown>;
+    }>;
+    redoMutations?: Array<{
+        id: string;
+        params: Record<string, unknown>;
+    }>;
+}
+/** The Univer 1.0.4 fields the undo rebase reads; a forcing test fails if they move (Univer is pinned). */
+declare function undoStacksOf(service: unknown): {
+    undo: Map<string, UndoItem[]>;
+    redo: Map<string, UndoItem[]>;
+} | null;
+/** §6.9: rebase one stack over a remote op; items that cannot follow are dropped. Returns how many were dropped. */
+declare function rebaseUndoStack(items: UndoItem[], remote: DocsOp): number;
+declare function openDocsOtRoom(o: OpenDocsOtRoomOptions): DocsOtRoom;
+
+/**
+ * THE DOCUMENT MODEL — the engine of one cloud document per tab.
+ *
+ * Before this, the document lived only inside each `DocumentEditor`'s Univer
+ * instance. A remount (a board tile waking, a tile removed and undone, a route
+ * change and back) rebuilt the editor from the SERVER copy, so whatever the
+ * last save had not carried yet was gone; two mounts of one document were two
+ * editors, each saving full snapshots of its own copy (last write wins), each
+ * with its own realtime channel and its own collab room.
+ *
+ * The document is a record on THE one working-copy primitive
+ * (`@ai-matrx/kit/working-copy`, kind `udt_document`,
+ * `./documentModels.ts`): its save status, dirty and view count are Redux state
+ * (`workingCopies["udt_document:<id>"]`), its one coalesced save is the kind's.
+ * What Redux cannot hold — Univer's body — is this engine, registered on the
+ * record's session under the same key:
+ *
+ *  - BODY. Every local mutation in one view is replayed into every other view
+ *    of the document (the same mutation stream collab sends between machines),
+ *    so two views show one document. A new view boots from the engine's latest
+ *    state — a live view's snapshot, or the snapshot the last view left behind
+ *    — never the stale server copy while the record's session is alive.
+ *  - SIDE EFFECTS, ONCE. The snapshot realtime channel, the collab room, and
+ *    the pagehide / visibility / beforeunload flush are opened once per
+ *    document and closed once.
+ *  - THE EDITOR ITSELF, KEPT. Univer keeps its undo / redo history inside the
+ *    editor instance, so rebuilding the editor on a remount threw the history
+ *    away. When the last view leaves, its editor (a Univer instance with its
+ *    own DOM host) is parked here — off the page, alive — and the next view of
+ *    the document RE-ATTACHES that same instance to its own container instead
+ *    of booting a new one (`parkEditor` / `takeParkedEditor`). Undo and redo
+ *    therefore work across hide / show, a remount and a removed tile undone,
+ *    for as long as the record's session is warm; `close()` disposes it.
+ */
+
+type DocumentSnapshotData = Partial<IDocumentData>;
+/** 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>;
+/** Who else is in the document's room (shared by every view of it). */
+interface DocumentAwareness {
+    states: Map<number, AwarenessState>;
+    selfUid: string;
+}
+
+/** `collab.ot_rooms` (§12.2): which documents without a room open one. */
+type OtRoomsKnob = "off" | "new" | "all";
+/** Whether this document opens on the ordered log: its room exists, or the knob opens one. */
+declare function documentUsesOrderedRoom(documentId: string, knob: OtRoomsKnob, isNewDocument: () => Promise<boolean>): Promise<boolean>;
+interface DocumentOtFactoryOptions {
+    documentId: string;
+    uid: string;
+    /** One per open tab; never reused. */
+    clientId: string;
+    displayName?: string;
+    readAntiEntropyIntervalMs?: () => Promise<number>;
+    onNotice?: (n: DocsOtNotice) => void;
+    onIncident?: (i: OpSessionIncident) => void;
+    onStatus?: (s: OpSessionStatus) => void;
+}
+/** 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, composeDocsOps, docsStateHash, documentOtFactory, documentUsesOrderedRoom, dropEmptyStyleRetains, invertDocsOp, isCellEditorScratch, isNoopDocsOp, normalizeDocsOp, openDocsOtRoom, rebaseUndoStack, stampCovered, stampDeterministicIds, stripSenderView, takeCovered, transformDocsOp, transformTextX, undoStacksOf };

package/dist/univer-collab.d.ts

@@ -1,5 +1,8 @@
 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 { IDocumentData } from '@univerjs/core';
+import { CommitReason } from '@ai-matrx/kit/working-copy';
 
 /**
  * A saved snapshot names the collab-room entries it already holds, so a seat that boots from it never
@@ -210,4 +213,252 @@ declare const SENDER_VIEW_PARAMS: readonly string[];
 declare function stripSenderView(params: MutationParams): MutationParams;
 declare function isCellEditorScratch(info: Pick<CollabMutationInfo, "id">): boolean;
 
-export { COLLAB_COVERED_KEY, type CollabBase, type CollabMutationInfo, type CollabProviderLike, type CommandServiceLike, SENDER_VIEW_PARAMS, WorkbookCollabSession, type WorkbookCollabSessionOptions, isCellEditorScratch, stampCovered, stripSenderView, takeCovered };
+type Act = Record<string, any> & {
+    t: "i" | "r" | "d";
+    len: number;
+};
+/** One `lost` entry: what a transform dropped from either side (R1), for the author's notice. */
+interface DocsLost {
+    rule: string;
+    side: "insert" | "delete";
+    len: number;
+    text?: string;
+}
+/** The travelling shape of a Docs JSON op: text-x edits normalised (R1 zones, R5, no oldBody). */
+declare function normalizeDocsOp<T>(op: T): T;
+/** R6: a retain whose style lost every key to the other side is a plain retain. */
+declare function dropEmptyStyleRetains<T>(op: T): T;
+/** x rewritten to apply after y over one text-x body; `side` is x's side. Drops land in `lost` (R1). */
+declare function transformTextX(xIn: Act[], yIn: Act[], side: "left" | "right", lost?: DocsLost[]): Act[];
+/** A Docs operation: an ot-json1 op over the whole Univer snapshot (what `rich-text-editing` carries as `actions`). */
+type DocsOp = unknown[] | null;
+interface DocsTransformResult {
+    op: DocsOp;
+    lost: DocsLost[];
+}
+/**
+ * `T(x, y, side)` for Docs: ot-json1 `transformNoConflict` (never throws on DROP_COLLISION / RM_UNEXPECTED_CONTENT /
+ * BLACKHOLE, §3) with our text-x transform registered only for the duration of one call, so Univer's own apply is
+ * untouched even when the bundler shares one ot-json1 instance with `@univerjs/core`. R6 runs on the result.
+ */
+declare function transformDocsOp(x: DocsOp, y: DocsOp, side: "left" | "right"): DocsTransformResult;
+/** `a` then `b` as one op (TextX is the subtype every reader composes with). */
+declare function composeDocsOps(a: DocsOp, b: DocsOp): DocsOp;
+declare function isNoopDocsOp(op: DocsOp): boolean;
+/** Apply an op to a plain snapshot (tests, the fold). Univer's own JSONX, so TextX applies as the editor applies. */
+declare function applyDocsOp<T>(doc: T, op: DocsOp): T;
+/** The inverse of `op` against the state it applied to. JSONX.invertWithDoc MUTATES its op: invert a copy (C0). */
+declare function invertDocsOp(op: DocsOp, preDoc: unknown): DocsOp;
+/** Part of `proto` (§6.4): Univer 1.0.4 + this transformer, rules R1–R6. */
+declare const DOCS_TRANSFORM_VERSION = "univer-1.0.4+docs-ot-r6";
+
+/**
+ * The canonical Docs state hash (COLLAB-DESIGN §7.2; C0 item 6, `spikes/c0-collab/lib.mjs`).
+ *
+ * SHA-256 of the canonical snapshot: keys sorted, empty values dropped, the unit id and seat-local fields
+ * removed (revision counter, collab stamps, layout state, selections), adjacent equal text runs merged, split
+ * pieces of one custom range or decoration folded, and `paragraphId` dropped (Univer's TextX.apply mints a
+ * random one per seat, C0 surprise 3). Header, footer and note bodies get the same rules.
+ *
+ * Two seats with equal content hash equal; one character more hashes differently. Browser and Node: the
+ * digest is Web Crypto's.
+ */
+/** Never content: the collab stamps, revision counters, seat-local view state. */
+declare const DOC_LOCAL_KEYS: string[];
+/** The canonical Docs snapshot: content only, keys sorted, runs normalised, local fields removed. */
+declare function canonicalDocsSnapshot(snapshot: unknown): unknown;
+/** The canonical form as the string the hash digests (tests compare these directly). */
+declare const canonicalDocsString: (snapshot: unknown) => string;
+/** SHA-256 hex of the canonical snapshot (§7.2). */
+declare function docsStateHash(snapshot: unknown): Promise<string>;
+/**
+ * Ids every seat agrees on for a snapshot that lacks them (C0 surprise 5): a raw snapshot (an import, markdown)
+ * loaded on two seats would otherwise get two random `sectionId`s / `paragraphId`s. Missing ids become
+ * positional ones; ids already present are kept. Applied to every snapshot a room loads.
+ */
+declare function stampDeterministicIds<T>(snapshot: T): T;
+
+/**
+ * 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.
+ */
+
+declare const RICH_TEXT_EDITING = "doc.mutation.rich-text-editing";
+/**
+ * The room's protocol (§6.4): Univer 1.0.4 + transformer `DOCS_TRANSFORM_VERSION`. Any Univer or transformer
+ * change raises it; a room at another proto opens read-only for this build.
+ */
+declare const DOCS_COLLAB_PROTO = 1;
+/** 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;
+}
+type DocsOtNotice = OpSessionNotice<DocsOp> | {
+    kind: "not_shared";
+    mutationId: string;
+} | {
+    kind: "not_live";
+};
+interface OpenDocsOtRoomOptions {
+    port: DocsOtPort;
+    transport: OpTransport;
+    clientId: string;
+    presence?: OpPresence;
+    /** `collab_replace` for this room (restore, whole import). */
+    replace: (req: {
+        snapshot: unknown;
+        stateHash: string;
+        clientId: string;
+    }) => Promise<{
+        rev: number;
+        ref: string;
+    }>;
+    onNotice?: (n: DocsOtNotice) => void;
+    onIncident?: (i: OpSessionIncident) => void;
+    onStatus?: (s: OpSessionStatus) => void;
+    /** Watch IME composition here (default: `document`). */
+    compositionTarget?: Pick<Document, "addEventListener" | "removeEventListener"> | null;
+}
+interface DocsOtRoom {
+    session: OpSession<DocsOp>;
+    /** The record's save: a checkpoint at a quiet point (§7.3). False when this seat does not write now. */
+    write(reason: "manual" | string): Promise<boolean>;
+    /** Restore / whole import through `collab_replace` (§20). */
+    replace(snapshot: unknown): Promise<void>;
+    /** This seat is the one that saves on its own. */
+    isSaver(): boolean;
+    stop(): void;
+}
+interface UndoItem {
+    unitID?: string;
+    undoMutations?: Array<{
+        id: string;
+        params: Record<string, unknown>;
+    }>;
+    redoMutations?: Array<{
+        id: string;
+        params: Record<string, unknown>;
+    }>;
+}
+/** The Univer 1.0.4 fields the undo rebase reads; a forcing test fails if they move (Univer is pinned). */
+declare function undoStacksOf(service: unknown): {
+    undo: Map<string, UndoItem[]>;
+    redo: Map<string, UndoItem[]>;
+} | null;
+/** §6.9: rebase one stack over a remote op; items that cannot follow are dropped. Returns how many were dropped. */
+declare function rebaseUndoStack(items: UndoItem[], remote: DocsOp): number;
+declare function openDocsOtRoom(o: OpenDocsOtRoomOptions): DocsOtRoom;
+
+/**
+ * THE DOCUMENT MODEL — the engine of one cloud document per tab.
+ *
+ * Before this, the document lived only inside each `DocumentEditor`'s Univer
+ * instance. A remount (a board tile waking, a tile removed and undone, a route
+ * change and back) rebuilt the editor from the SERVER copy, so whatever the
+ * last save had not carried yet was gone; two mounts of one document were two
+ * editors, each saving full snapshots of its own copy (last write wins), each
+ * with its own realtime channel and its own collab room.
+ *
+ * The document is a record on THE one working-copy primitive
+ * (`@ai-matrx/kit/working-copy`, kind `udt_document`,
+ * `./documentModels.ts`): its save status, dirty and view count are Redux state
+ * (`workingCopies["udt_document:<id>"]`), its one coalesced save is the kind's.
+ * What Redux cannot hold — Univer's body — is this engine, registered on the
+ * record's session under the same key:
+ *
+ *  - BODY. Every local mutation in one view is replayed into every other view
+ *    of the document (the same mutation stream collab sends between machines),
+ *    so two views show one document. A new view boots from the engine's latest
+ *    state — a live view's snapshot, or the snapshot the last view left behind
+ *    — never the stale server copy while the record's session is alive.
+ *  - SIDE EFFECTS, ONCE. The snapshot realtime channel, the collab room, and
+ *    the pagehide / visibility / beforeunload flush are opened once per
+ *    document and closed once.
+ *  - THE EDITOR ITSELF, KEPT. Univer keeps its undo / redo history inside the
+ *    editor instance, so rebuilding the editor on a remount threw the history
+ *    away. When the last view leaves, its editor (a Univer instance with its
+ *    own DOM host) is parked here — off the page, alive — and the next view of
+ *    the document RE-ATTACHES that same instance to its own container instead
+ *    of booting a new one (`parkEditor` / `takeParkedEditor`). Undo and redo
+ *    therefore work across hide / show, a remount and a removed tile undone,
+ *    for as long as the record's session is warm; `close()` disposes it.
+ */
+
+type DocumentSnapshotData = Partial<IDocumentData>;
+/** 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>;
+/** Who else is in the document's room (shared by every view of it). */
+interface DocumentAwareness {
+    states: Map<number, AwarenessState>;
+    selfUid: string;
+}
+
+/** `collab.ot_rooms` (§12.2): which documents without a room open one. */
+type OtRoomsKnob = "off" | "new" | "all";
+/** Whether this document opens on the ordered log: its room exists, or the knob opens one. */
+declare function documentUsesOrderedRoom(documentId: string, knob: OtRoomsKnob, isNewDocument: () => Promise<boolean>): Promise<boolean>;
+interface DocumentOtFactoryOptions {
+    documentId: string;
+    uid: string;
+    /** One per open tab; never reused. */
+    clientId: string;
+    displayName?: string;
+    readAntiEntropyIntervalMs?: () => Promise<number>;
+    onNotice?: (n: DocsOtNotice) => void;
+    onIncident?: (i: OpSessionIncident) => void;
+    onStatus?: (s: OpSessionStatus) => void;
+}
+/** 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, composeDocsOps, docsStateHash, documentOtFactory, documentUsesOrderedRoom, dropEmptyStyleRetains, invertDocsOp, isCellEditorScratch, isNoopDocsOp, normalizeDocsOp, openDocsOtRoom, rebaseUndoStack, stampCovered, stampDeterministicIds, stripSenderView, takeCovered, transformDocsOp, transformTextX, undoStacksOf };