@ai-matrx/office 0.8.13 → 0.8.15

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, CollabRpcClient, collabReplace } from '@ai-matrx/data/realtime/collab';
+import { OpSessionNotice, OpSession, OpTransport, OpPresence, OpSessionIncident, OpSessionStatus, AwarenessState, CollabRpcClient, collabReplace, OpDocumentAdapter } from '@ai-matrx/data/realtime/collab';
 import { IDocumentData } from '@univerjs/core';
 import { CommitReason } from '@ai-matrx/kit/working-copy';
 
@@ -385,7 +385,7 @@ interface DocsOtRoom {
  * through `encode`, so `encode` must not depend on key order or every acknowledgement looks like a mismatch.
  */
 declare function canonicalKeys<T>(v: T): T;
-interface UndoItem {
+interface UndoItem$1 {
     unitID?: string;
     undoMutations?: Array<{
         id: string;
@@ -398,11 +398,11 @@ interface UndoItem {
 }
 /** 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[]>;
+    undo: Map<string, UndoItem$1[]>;
+    redo: Map<string, UndoItem$1[]>;
 } | 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 rebaseUndoStack(items: UndoItem$1[], remote: DocsOp): number;
 declare function openDocsOtRoom(o: OpenDocsOtRoomOptions): DocsOtRoom;
 
 interface CaretRange {
@@ -536,4 +536,291 @@ declare function restoreDocumentSnapshot(args: {
     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 };
+/**
+ * Sheet co-editing transforms (C5a): the shapes. Pure data; no Univer import.
+ *
+ * Convention (COLLAB-DESIGN §6.4): `transform(x, y, side)` returns `x` rewritten to apply AFTER `y`, where
+ * `side` is x's side. The later-committed op always takes "left": it wins overwrites and sits first on
+ * position ties.
+ */
+/** One allowlisted Univer mutation as it travels: no `unitId` (the receiver re-addresses to its own unit). */
+interface SheetMutation {
+    readonly id: string;
+    readonly params: Readonly<Record<string, unknown>>;
+}
+interface Barrier {
+    readonly barrier: true;
+    readonly reason: string;
+}
+interface SheetRange {
+    startRow: number;
+    endRow: number;
+    startColumn: number;
+    endColumn: number;
+    rangeType?: number;
+    [k: string]: unknown;
+}
+
+/** A changeset: allowlisted sheet mutations in order. `null` / `[]` is the no-op. */
+type SheetOp = SheetMutation[] | null;
+/**
+ * The room's protocol (§6.4): Univer 1.0.4 + transformer `SHEET_TRANSFORMER_VERSION`. Any Univer or transformer
+ * change raises it; a room at another proto opens read-only for this build.
+ */
+declare const SHEETS_COLLAB_PROTO = 1;
+declare const SHEETS_EDIT_GROUP = "sheets.edit";
+/** One outermost command's traveling mutations, as the port hands them over. */
+interface SheetsLocalGroup {
+    kind: "group";
+    mutations: SheetMutation[];
+    /** The group's inverse against the pre-state (§6.3), or undefined when one of its mutations has none. */
+    inverse?: SheetMutation[];
+    /** The outermost command id (the change's label in a rollback notice). */
+    label: string | null;
+}
+/** A local change that cannot travel (no allowlist: a barrier id, an unknown id, a whole-style override …). */
+interface SheetsNotShared {
+    kind: "not_shared";
+    mutationId: string;
+    label: string | null;
+}
+type SheetsLocalEvent = SheetsLocalGroup | SheetsNotShared;
+/** What the workbook editor lends the room (implemented by `univerSheetsOtPort`). */
+interface SheetsOtPort {
+    onLocal(listener: (e: SheetsLocalEvent) => void): () => void;
+    /** True while a local command is still running (its group is not handed over yet). */
+    busy(): boolean;
+    /** Run `fn` once no local command is running (immediately when none is). */
+    whenIdle(fn: () => void): void;
+    /** Apply one committed mutation to this seat's workbook; throws when the editor refused it. */
+    applyRemote(m: SheetMutation): void;
+    /** The workbook as the editor holds it now (with resources), or null when none is mounted. */
+    snapshot(): unknown | null;
+    /** Replace the workbook's whole content (same unit id). */
+    load(snapshot: unknown): void;
+    /** Univer's undo/redo service and this seat's unit. */
+    undoTargets(): Array<{
+        service: unknown;
+        unitId: string;
+    }>;
+    /** Ask for a save (the record's one coalesced save). */
+    markDirty(): void;
+}
+type SheetsOtNotice = OpSessionNotice<SheetOp> | {
+    kind: "not_shared";
+    mutationId: string;
+} | {
+    kind: "not_live";
+};
+/**
+ * The adapter's transform: the C5a/C5b group transform, with `lost` widened by what y can no longer apply
+ * after x (y's `dropped` over x). The session tells an earlier author through `lost`; without this, an edit
+ * in a column a later op removed would vanish without a word.
+ */
+declare function transformSheetOp(x: SheetOp, y: SheetOp, side: "left" | "right"): Barrier | {
+    op: SheetOp;
+    lost: string[];
+    dropped: string[];
+};
+/**
+ * The wire form. Keys in one canonical order: the log stores groups as jsonb, which hands object keys back in
+ * its own order, and the session compares wire forms (its ack check) through `encode` (C3's rule).
+ */
+declare function encodeSheetOp(op: SheetOp): {
+    cmd: string;
+    mutations: {
+        id: string;
+        params: Readonly<Record<string, unknown>>;
+    }[];
+}[];
+declare function decodeSheetOp(groups: Array<{
+    mutations: Array<{
+        id: string;
+        params: unknown;
+    }>;
+}>): SheetOp;
+interface UndoItem {
+    unitID?: string;
+    undoMutations?: Array<{
+        id: string;
+        params: Record<string, unknown>;
+    }>;
+    redoMutations?: Array<{
+        id: string;
+        params: Record<string, unknown>;
+    }>;
+}
+/** §6.9: rebase one stack over a remote op; items that cannot follow are dropped. Returns how many were dropped. */
+declare function rebaseSheetUndoStack(items: UndoItem[], remote: SheetOp, unitId: string): number;
+interface SheetsOtAdapterHooks {
+    /** Called once per applied remote op that rebased this seat's undo stacks (for tests and logs). */
+    onUndoRebased?: (dropped: number) => void;
+}
+/** The `OpDocumentAdapter` over a sheets port, plus the held-remote queue the room drives. */
+interface SheetsOtAdapter extends OpDocumentAdapter<SheetOp> {
+    /** Remote ops held while a local command runs. */
+    held(): number;
+    /** A local group finished while remote ops were held: rebase it over them and them over it (Docs IME rule). */
+    rebaseLocalOverHeld(local: SheetMutation[]): SheetMutation[] | "barrier";
+    clearHeld(): void;
+}
+declare function createSheetsOtAdapter(port: SheetsOtPort, hooks?: SheetsOtAdapterHooks): SheetsOtAdapter;
+interface OpenSheetsOtRoomOptions {
+    port: SheetsOtPort;
+    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: SheetsOtNotice) => void;
+    onIncident?: (i: OpSessionIncident) => void;
+    onStatus?: (s: OpSessionStatus) => void;
+}
+interface SheetsOtRoom {
+    session: OpSession<SheetOp>;
+    /** 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`. */
+    replace(snapshot: unknown): Promise<void>;
+    /** This seat is the one that saves on its own. */
+    isSaver(): boolean;
+    stop(): void;
+}
+declare function openSheetsOtRoom(o: OpenSheetsOtRoomOptions): SheetsOtRoom;
+
+/**
+ * The `SheetsOtPort` over a live Univer workbook (COLLAB-DESIGN §6.3, §6.7, C0 items 4, 6, 7, C5a/C5b capture
+ * rules). The host lends Univer's services (it resolves them with its own tokens, so this module never pulls a
+ * second copy of Univer's DI into the app); this module does every capture rule:
+ *
+ * - FILTER. Only mutations of THIS seat's unit, never `onlyLocal` or `fromCollab` ones (formula results, our own
+ *   remote applies), never the never-travels class.
+ * - GROUP. By the outermost COMMAND (`beforeCommandExecuted` / `onCommandExecuted` depth), with a try/finally
+ *   around `executeCommand` so a command that mutates and then throws still closes its group (C0 surprise 7).
+ *   One hand-over per group: the formula annotation needs the whole group (a rewrite after a structural op is
+ *   `derived`, §21.2).
+ * - ALLOWLIST. `allowParams`; an id without one (a barrier id, an unknown id) makes the group `not_shared`.
+ * - THE THREE C5a RULES. Cell content is completed from the cell right after the mutation
+ *   (`completeCellContent`); a remove-merge names the exact merges it removed (`exactMergeRemovals`, merges read
+ *   right before the mutation); a style travels as its object, never a seat-local id. A whole-style override
+ *   (paste) is restated as a merge with explicit nulls, which every seat applies identically.
+ * - FORMULAS. `annotateFormulas` with the sheet names and defined names as they were before the command.
+ * - INVERSE from the APPLIED params against a COPY of the pre-state taken in `beforeCommandExecuted`
+ *   (C0 surprise 6). Families without a safe inverse leave it unknown.
+ */
+
+type Obj = Record<string, unknown>;
+type CommandInfo = {
+    id: string;
+    type?: number;
+    params?: unknown;
+};
+type Disposable = {
+    dispose: () => void;
+};
+/** Univer's command service as the workbook editor lends it. */
+interface SheetsCommandService {
+    onMutationExecutedForCollab(listener: (info: CommandInfo, options?: unknown) => void): Disposable;
+    beforeCommandExecuted(listener: (info: CommandInfo, options?: unknown) => void): Disposable;
+    onCommandExecuted(listener: (info: CommandInfo, options?: unknown) => void): Disposable;
+    syncExecuteCommand(id: string, params?: unknown, options?: unknown): unknown;
+    executeCommand?: (id: string, params?: unknown, options?: unknown) => Promise<unknown>;
+}
+interface SheetsWorksheetLike {
+    getSheetId(): string;
+    getName(): string;
+    getCellRaw(row: number, col: number): Obj | null | undefined;
+    getMergeData(): SheetRange[];
+}
+interface SheetsWorkbookLike {
+    getUnitId(): string;
+    getSheets(): SheetsWorksheetLike[];
+    getSheetBySheetId(id: string): SheetsWorksheetLike | null | undefined;
+    getStyles(): {
+        get(id: string): unknown;
+    };
+    getSnapshot(): unknown;
+}
+interface UniverSheetsOtPortOptions {
+    commandService: SheetsCommandService;
+    /** This seat's workbook unit right now (a content swap keeps the unit id). */
+    workbook(): SheetsWorkbookLike | null;
+    /** `IDefinedNamesService.getDefinedNameMap(unitId)`: defined-name id → entry. */
+    definedNames?(unitId: string): Record<string, {
+        name?: string;
+    }> | null | undefined;
+    /** `IResourceLoaderService.saveUnit(unitId)`: the snapshot with its resources (what a save stores). */
+    saveUnit?(unitId: string): unknown | null;
+    /** Univer's undo/redo service. */
+    undoRedo?(): unknown | null;
+    /** Replace the workbook's whole content, keeping its unit id. */
+    load(snapshot: unknown): void;
+    markDirty(): void;
+}
+declare function univerSheetsOtPort(o: UniverSheetsOtPortOptions): SheetsOtPort & {
+    dispose(): void;
+};
+
+/**
+ * The canonical Sheets state hash (COLLAB-DESIGN §7.2, C0 item 6, §21.3): two seats holding the same workbook
+ * hash equal, whatever their seat-local differences.
+ *
+ * - Dropped: the unit `id`, `rev`, the collab stamps, and per sheet `zoomRatio`, `scrollTop`, `scrollLeft`,
+ *   `selections`.
+ * - Style ids are seat-local (C0 surprise 4): every `s` id is replaced by its style object; `styles` is dropped.
+ * - A cell holding a formula (`f` or `si`) drops its computed `v` and `t`: recalculation timing differs per seat.
+ * - Empty values, cells and rows are dropped; keys are sorted.
+ * - `mergeData` is a set (Univer never reads its order); concurrent merges leave one set in two orders.
+ * - Resources are parsed and key-sorted, so the defined names (`SHEET_DEFINED_NAME_PLUGIN`, a map keyed by id)
+ *   are compared sorted by id; a `definedNames` list (the transform tests' seats) is sorted by id too.
+ */
+/** The canonical form of a workbook snapshot (`IWorkbookData`, optionally with a `definedNames` list). */
+declare function canonicalSheet(snapshot: unknown): unknown;
+declare const canonicalSheetString: (snapshot: unknown) => string;
+/** SHA-256 (hex) of the canonical form. Web Crypto, so the browser and Node compute the same hash. */
+declare function sheetsStateHash(snapshot: unknown): Promise<string>;
+
+/** `collab.ot_rooms` (§12.2): which workbooks without a room open one. */
+type WorkbookOtRoomsKnob = "off" | "new" | "all";
+/** Whether this workbook opens on the ordered log: its room exists, or the knob opens one. */
+declare function workbookUsesOrderedRoom(workbookId: string, knob: WorkbookOtRoomsKnob, isNewWorkbook: () => Promise<boolean>): Promise<boolean>;
+interface WorkbookOtRoomOptions {
+    workbookId: string;
+    uid: string;
+    /** One per open tab; never reused. */
+    clientId: string;
+    displayName?: string;
+    readAntiEntropyIntervalMs?: () => Promise<number>;
+    onAwareness?: (states: Map<number, AwarenessState>) => void;
+    onNotice?: (n: SheetsOtNotice) => void;
+    onIncident?: (i: OpSessionIncident) => void;
+    onStatus?: (s: OpSessionStatus) => void;
+}
+interface WorkbookOtRoomHandle {
+    session: OpSession<SheetOp>;
+    isSaver(): boolean;
+    /** The record's save: a checkpoint at a quiet point. False when this seat does not write now. */
+    write(reason: "manual" | string): Promise<boolean>;
+    /** Restore / whole import through `collab_replace`. */
+    replace(snapshot: unknown): Promise<void>;
+    /** This seat's cell, for the other seats' cursor rings. */
+    setCursor(c: {
+        sheetId: string | null;
+        row: number | null;
+        col: number | null;
+    }): void;
+    stop(): void;
+}
+/** Join the workbook's ordered-log room with the editor's port (`univerSheetsOtPort`). */
+declare function startWorkbookOtRoom(port: SheetsOtPort & {
+    dispose?: () => void;
+}, o: WorkbookOtRoomOptions): Promise<WorkbookOtRoomHandle>;
+
+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 OpenSheetsOtRoomOptions, type OtRoomsKnob, RICH_TEXT_EDITING, SENDER_VIEW_PARAMS, SHEETS_COLLAB_PROTO, SHEETS_EDIT_GROUP, type SheetOp, type SheetsCommandService, type SheetsLocalEvent, type SheetsLocalGroup, type SheetsNotShared, type SheetsOtAdapter, type SheetsOtAdapterHooks, type SheetsOtNotice, type SheetsOtPort, type SheetsOtRoom, type SheetsWorkbookLike, type SheetsWorksheetLike, type UniverSheetsOtPortOptions, WorkbookCollabSession, type WorkbookCollabSessionOptions, type WorkbookOtRoomHandle, type WorkbookOtRoomOptions, type WorkbookOtRoomsKnob, applyDocsOp, canonicalDocsSnapshot, canonicalDocsString, canonicalKeys, canonicalSheet, canonicalSheetString, composeDocsOps, createSheetsOtAdapter, decodeSheetOp, docsStateHash, documentOtFactory, documentUsesOrderedRoom, dropEmptyStyleRetains, encodeSheetOp, invertDocsOp, isCellEditorScratch, isNoopDocsOp, normalizeDocsOp, openDocsOtRoom, openSheetsOtRoom, rebaseSheetUndoStack, rebaseUndoStack, restoreDocumentSnapshot, sheetsStateHash, stampCovered, stampDeterministicIds, startWorkbookOtRoom, stripSenderView, takeCovered, transformDocsOp, transformSheetOp, transformTextX, undoStacksOf, univerSheetsOtPort, workbookUsesOrderedRoom };

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, CollabRpcClient, collabReplace } from '@ai-matrx/data/realtime/collab';
+import { OpSessionNotice, OpSession, OpTransport, OpPresence, OpSessionIncident, OpSessionStatus, AwarenessState, CollabRpcClient, collabReplace, OpDocumentAdapter } from '@ai-matrx/data/realtime/collab';
 import { IDocumentData } from '@univerjs/core';
 import { CommitReason } from '@ai-matrx/kit/working-copy';
 
@@ -385,7 +385,7 @@ interface DocsOtRoom {
  * through `encode`, so `encode` must not depend on key order or every acknowledgement looks like a mismatch.
  */
 declare function canonicalKeys<T>(v: T): T;
-interface UndoItem {
+interface UndoItem$1 {
     unitID?: string;
     undoMutations?: Array<{
         id: string;
@@ -398,11 +398,11 @@ interface UndoItem {
 }
 /** 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[]>;
+    undo: Map<string, UndoItem$1[]>;
+    redo: Map<string, UndoItem$1[]>;
 } | 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 rebaseUndoStack(items: UndoItem$1[], remote: DocsOp): number;
 declare function openDocsOtRoom(o: OpenDocsOtRoomOptions): DocsOtRoom;
 
 interface CaretRange {
@@ -536,4 +536,291 @@ declare function restoreDocumentSnapshot(args: {
     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 };
+/**
+ * Sheet co-editing transforms (C5a): the shapes. Pure data; no Univer import.
+ *
+ * Convention (COLLAB-DESIGN §6.4): `transform(x, y, side)` returns `x` rewritten to apply AFTER `y`, where
+ * `side` is x's side. The later-committed op always takes "left": it wins overwrites and sits first on
+ * position ties.
+ */
+/** One allowlisted Univer mutation as it travels: no `unitId` (the receiver re-addresses to its own unit). */
+interface SheetMutation {
+    readonly id: string;
+    readonly params: Readonly<Record<string, unknown>>;
+}
+interface Barrier {
+    readonly barrier: true;
+    readonly reason: string;
+}
+interface SheetRange {
+    startRow: number;
+    endRow: number;
+    startColumn: number;
+    endColumn: number;
+    rangeType?: number;
+    [k: string]: unknown;
+}
+
+/** A changeset: allowlisted sheet mutations in order. `null` / `[]` is the no-op. */
+type SheetOp = SheetMutation[] | null;
+/**
+ * The room's protocol (§6.4): Univer 1.0.4 + transformer `SHEET_TRANSFORMER_VERSION`. Any Univer or transformer
+ * change raises it; a room at another proto opens read-only for this build.
+ */
+declare const SHEETS_COLLAB_PROTO = 1;
+declare const SHEETS_EDIT_GROUP = "sheets.edit";
+/** One outermost command's traveling mutations, as the port hands them over. */
+interface SheetsLocalGroup {
+    kind: "group";
+    mutations: SheetMutation[];
+    /** The group's inverse against the pre-state (§6.3), or undefined when one of its mutations has none. */
+    inverse?: SheetMutation[];
+    /** The outermost command id (the change's label in a rollback notice). */
+    label: string | null;
+}
+/** A local change that cannot travel (no allowlist: a barrier id, an unknown id, a whole-style override …). */
+interface SheetsNotShared {
+    kind: "not_shared";
+    mutationId: string;
+    label: string | null;
+}
+type SheetsLocalEvent = SheetsLocalGroup | SheetsNotShared;
+/** What the workbook editor lends the room (implemented by `univerSheetsOtPort`). */
+interface SheetsOtPort {
+    onLocal(listener: (e: SheetsLocalEvent) => void): () => void;
+    /** True while a local command is still running (its group is not handed over yet). */
+    busy(): boolean;
+    /** Run `fn` once no local command is running (immediately when none is). */
+    whenIdle(fn: () => void): void;
+    /** Apply one committed mutation to this seat's workbook; throws when the editor refused it. */
+    applyRemote(m: SheetMutation): void;
+    /** The workbook as the editor holds it now (with resources), or null when none is mounted. */
+    snapshot(): unknown | null;
+    /** Replace the workbook's whole content (same unit id). */
+    load(snapshot: unknown): void;
+    /** Univer's undo/redo service and this seat's unit. */
+    undoTargets(): Array<{
+        service: unknown;
+        unitId: string;
+    }>;
+    /** Ask for a save (the record's one coalesced save). */
+    markDirty(): void;
+}
+type SheetsOtNotice = OpSessionNotice<SheetOp> | {
+    kind: "not_shared";
+    mutationId: string;
+} | {
+    kind: "not_live";
+};
+/**
+ * The adapter's transform: the C5a/C5b group transform, with `lost` widened by what y can no longer apply
+ * after x (y's `dropped` over x). The session tells an earlier author through `lost`; without this, an edit
+ * in a column a later op removed would vanish without a word.
+ */
+declare function transformSheetOp(x: SheetOp, y: SheetOp, side: "left" | "right"): Barrier | {
+    op: SheetOp;
+    lost: string[];
+    dropped: string[];
+};
+/**
+ * The wire form. Keys in one canonical order: the log stores groups as jsonb, which hands object keys back in
+ * its own order, and the session compares wire forms (its ack check) through `encode` (C3's rule).
+ */
+declare function encodeSheetOp(op: SheetOp): {
+    cmd: string;
+    mutations: {
+        id: string;
+        params: Readonly<Record<string, unknown>>;
+    }[];
+}[];
+declare function decodeSheetOp(groups: Array<{
+    mutations: Array<{
+        id: string;
+        params: unknown;
+    }>;
+}>): SheetOp;
+interface UndoItem {
+    unitID?: string;
+    undoMutations?: Array<{
+        id: string;
+        params: Record<string, unknown>;
+    }>;
+    redoMutations?: Array<{
+        id: string;
+        params: Record<string, unknown>;
+    }>;
+}
+/** §6.9: rebase one stack over a remote op; items that cannot follow are dropped. Returns how many were dropped. */
+declare function rebaseSheetUndoStack(items: UndoItem[], remote: SheetOp, unitId: string): number;
+interface SheetsOtAdapterHooks {
+    /** Called once per applied remote op that rebased this seat's undo stacks (for tests and logs). */
+    onUndoRebased?: (dropped: number) => void;
+}
+/** The `OpDocumentAdapter` over a sheets port, plus the held-remote queue the room drives. */
+interface SheetsOtAdapter extends OpDocumentAdapter<SheetOp> {
+    /** Remote ops held while a local command runs. */
+    held(): number;
+    /** A local group finished while remote ops were held: rebase it over them and them over it (Docs IME rule). */
+    rebaseLocalOverHeld(local: SheetMutation[]): SheetMutation[] | "barrier";
+    clearHeld(): void;
+}
+declare function createSheetsOtAdapter(port: SheetsOtPort, hooks?: SheetsOtAdapterHooks): SheetsOtAdapter;
+interface OpenSheetsOtRoomOptions {
+    port: SheetsOtPort;
+    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: SheetsOtNotice) => void;
+    onIncident?: (i: OpSessionIncident) => void;
+    onStatus?: (s: OpSessionStatus) => void;
+}
+interface SheetsOtRoom {
+    session: OpSession<SheetOp>;
+    /** 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`. */
+    replace(snapshot: unknown): Promise<void>;
+    /** This seat is the one that saves on its own. */
+    isSaver(): boolean;
+    stop(): void;
+}
+declare function openSheetsOtRoom(o: OpenSheetsOtRoomOptions): SheetsOtRoom;
+
+/**
+ * The `SheetsOtPort` over a live Univer workbook (COLLAB-DESIGN §6.3, §6.7, C0 items 4, 6, 7, C5a/C5b capture
+ * rules). The host lends Univer's services (it resolves them with its own tokens, so this module never pulls a
+ * second copy of Univer's DI into the app); this module does every capture rule:
+ *
+ * - FILTER. Only mutations of THIS seat's unit, never `onlyLocal` or `fromCollab` ones (formula results, our own
+ *   remote applies), never the never-travels class.
+ * - GROUP. By the outermost COMMAND (`beforeCommandExecuted` / `onCommandExecuted` depth), with a try/finally
+ *   around `executeCommand` so a command that mutates and then throws still closes its group (C0 surprise 7).
+ *   One hand-over per group: the formula annotation needs the whole group (a rewrite after a structural op is
+ *   `derived`, §21.2).
+ * - ALLOWLIST. `allowParams`; an id without one (a barrier id, an unknown id) makes the group `not_shared`.
+ * - THE THREE C5a RULES. Cell content is completed from the cell right after the mutation
+ *   (`completeCellContent`); a remove-merge names the exact merges it removed (`exactMergeRemovals`, merges read
+ *   right before the mutation); a style travels as its object, never a seat-local id. A whole-style override
+ *   (paste) is restated as a merge with explicit nulls, which every seat applies identically.
+ * - FORMULAS. `annotateFormulas` with the sheet names and defined names as they were before the command.
+ * - INVERSE from the APPLIED params against a COPY of the pre-state taken in `beforeCommandExecuted`
+ *   (C0 surprise 6). Families without a safe inverse leave it unknown.
+ */
+
+type Obj = Record<string, unknown>;
+type CommandInfo = {
+    id: string;
+    type?: number;
+    params?: unknown;
+};
+type Disposable = {
+    dispose: () => void;
+};
+/** Univer's command service as the workbook editor lends it. */
+interface SheetsCommandService {
+    onMutationExecutedForCollab(listener: (info: CommandInfo, options?: unknown) => void): Disposable;
+    beforeCommandExecuted(listener: (info: CommandInfo, options?: unknown) => void): Disposable;
+    onCommandExecuted(listener: (info: CommandInfo, options?: unknown) => void): Disposable;
+    syncExecuteCommand(id: string, params?: unknown, options?: unknown): unknown;
+    executeCommand?: (id: string, params?: unknown, options?: unknown) => Promise<unknown>;
+}
+interface SheetsWorksheetLike {
+    getSheetId(): string;
+    getName(): string;
+    getCellRaw(row: number, col: number): Obj | null | undefined;
+    getMergeData(): SheetRange[];
+}
+interface SheetsWorkbookLike {
+    getUnitId(): string;
+    getSheets(): SheetsWorksheetLike[];
+    getSheetBySheetId(id: string): SheetsWorksheetLike | null | undefined;
+    getStyles(): {
+        get(id: string): unknown;
+    };
+    getSnapshot(): unknown;
+}
+interface UniverSheetsOtPortOptions {
+    commandService: SheetsCommandService;
+    /** This seat's workbook unit right now (a content swap keeps the unit id). */
+    workbook(): SheetsWorkbookLike | null;
+    /** `IDefinedNamesService.getDefinedNameMap(unitId)`: defined-name id → entry. */
+    definedNames?(unitId: string): Record<string, {
+        name?: string;
+    }> | null | undefined;
+    /** `IResourceLoaderService.saveUnit(unitId)`: the snapshot with its resources (what a save stores). */
+    saveUnit?(unitId: string): unknown | null;
+    /** Univer's undo/redo service. */
+    undoRedo?(): unknown | null;
+    /** Replace the workbook's whole content, keeping its unit id. */
+    load(snapshot: unknown): void;
+    markDirty(): void;
+}
+declare function univerSheetsOtPort(o: UniverSheetsOtPortOptions): SheetsOtPort & {
+    dispose(): void;
+};
+
+/**
+ * The canonical Sheets state hash (COLLAB-DESIGN §7.2, C0 item 6, §21.3): two seats holding the same workbook
+ * hash equal, whatever their seat-local differences.
+ *
+ * - Dropped: the unit `id`, `rev`, the collab stamps, and per sheet `zoomRatio`, `scrollTop`, `scrollLeft`,
+ *   `selections`.
+ * - Style ids are seat-local (C0 surprise 4): every `s` id is replaced by its style object; `styles` is dropped.
+ * - A cell holding a formula (`f` or `si`) drops its computed `v` and `t`: recalculation timing differs per seat.
+ * - Empty values, cells and rows are dropped; keys are sorted.
+ * - `mergeData` is a set (Univer never reads its order); concurrent merges leave one set in two orders.
+ * - Resources are parsed and key-sorted, so the defined names (`SHEET_DEFINED_NAME_PLUGIN`, a map keyed by id)
+ *   are compared sorted by id; a `definedNames` list (the transform tests' seats) is sorted by id too.
+ */
+/** The canonical form of a workbook snapshot (`IWorkbookData`, optionally with a `definedNames` list). */
+declare function canonicalSheet(snapshot: unknown): unknown;
+declare const canonicalSheetString: (snapshot: unknown) => string;
+/** SHA-256 (hex) of the canonical form. Web Crypto, so the browser and Node compute the same hash. */
+declare function sheetsStateHash(snapshot: unknown): Promise<string>;
+
+/** `collab.ot_rooms` (§12.2): which workbooks without a room open one. */
+type WorkbookOtRoomsKnob = "off" | "new" | "all";
+/** Whether this workbook opens on the ordered log: its room exists, or the knob opens one. */
+declare function workbookUsesOrderedRoom(workbookId: string, knob: WorkbookOtRoomsKnob, isNewWorkbook: () => Promise<boolean>): Promise<boolean>;
+interface WorkbookOtRoomOptions {
+    workbookId: string;
+    uid: string;
+    /** One per open tab; never reused. */
+    clientId: string;
+    displayName?: string;
+    readAntiEntropyIntervalMs?: () => Promise<number>;
+    onAwareness?: (states: Map<number, AwarenessState>) => void;
+    onNotice?: (n: SheetsOtNotice) => void;
+    onIncident?: (i: OpSessionIncident) => void;
+    onStatus?: (s: OpSessionStatus) => void;
+}
+interface WorkbookOtRoomHandle {
+    session: OpSession<SheetOp>;
+    isSaver(): boolean;
+    /** The record's save: a checkpoint at a quiet point. False when this seat does not write now. */
+    write(reason: "manual" | string): Promise<boolean>;
+    /** Restore / whole import through `collab_replace`. */
+    replace(snapshot: unknown): Promise<void>;
+    /** This seat's cell, for the other seats' cursor rings. */
+    setCursor(c: {
+        sheetId: string | null;
+        row: number | null;
+        col: number | null;
+    }): void;
+    stop(): void;
+}
+/** Join the workbook's ordered-log room with the editor's port (`univerSheetsOtPort`). */
+declare function startWorkbookOtRoom(port: SheetsOtPort & {
+    dispose?: () => void;
+}, o: WorkbookOtRoomOptions): Promise<WorkbookOtRoomHandle>;
+
+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 OpenSheetsOtRoomOptions, type OtRoomsKnob, RICH_TEXT_EDITING, SENDER_VIEW_PARAMS, SHEETS_COLLAB_PROTO, SHEETS_EDIT_GROUP, type SheetOp, type SheetsCommandService, type SheetsLocalEvent, type SheetsLocalGroup, type SheetsNotShared, type SheetsOtAdapter, type SheetsOtAdapterHooks, type SheetsOtNotice, type SheetsOtPort, type SheetsOtRoom, type SheetsWorkbookLike, type SheetsWorksheetLike, type UniverSheetsOtPortOptions, WorkbookCollabSession, type WorkbookCollabSessionOptions, type WorkbookOtRoomHandle, type WorkbookOtRoomOptions, type WorkbookOtRoomsKnob, applyDocsOp, canonicalDocsSnapshot, canonicalDocsString, canonicalKeys, canonicalSheet, canonicalSheetString, composeDocsOps, createSheetsOtAdapter, decodeSheetOp, docsStateHash, documentOtFactory, documentUsesOrderedRoom, dropEmptyStyleRetains, encodeSheetOp, invertDocsOp, isCellEditorScratch, isNoopDocsOp, normalizeDocsOp, openDocsOtRoom, openSheetsOtRoom, rebaseSheetUndoStack, rebaseUndoStack, restoreDocumentSnapshot, sheetsStateHash, stampCovered, stampDeterministicIds, startWorkbookOtRoom, stripSenderView, takeCovered, transformDocsOp, transformSheetOp, transformTextX, undoStacksOf, univerSheetsOtPort, workbookUsesOrderedRoom };