@univerjs-pro/collaboration-client 1.1.0 → 1.2.0

package/lib/locale/zh-TW.js

@@ -1 +1 @@
-const _0x3b8851=_0x5e7a;(function(_0x458da0,_0x2d6656){const _0x4880f6=_0x5e7a,_0x226fc1=_0x458da0();while(!![]){try{const _0x19d86d=parseInt(_0x4880f6(0x1f3))/0x1*(parseInt(_0x4880f6(0x1db))/0x2)+parseInt(_0x4880f6(0x1de))/0x3+-parseInt(_0x4880f6(0x1e0))/0x4*(-parseInt(_0x4880f6(0x1f1))/0x5)+parseInt(_0x4880f6(0x1ec))/0x6*(-parseInt(_0x4880f6(0x1ea))/0x7)+-parseInt(_0x4880f6(0x1f4))/0x8*(parseInt(_0x4880f6(0x1eb))/0x9)+parseInt(_0x4880f6(0x1ed))/0xa*(parseInt(_0x4880f6(0x1dd))/0xb)+-parseInt(_0x4880f6(0x1ee))/0xc;if(_0x19d86d===_0x2d6656)break;else _0x226fc1['push'](_0x226fc1['shift']());}catch(_0x37d32c){_0x226fc1['push'](_0x226fc1['shift']());}}}(_0x47fc,0x6e244));const e={'collaboration-client':{'collabClient':{'tooltip':{'reconnect':'點擊重新連線'}},'collabStatus':{'fetchMiss':_0x3b8851(0x1e2),'conflict':_0x3b8851(0x1e5),'notCollab':_0x3b8851(0x1e1),'synced':_0x3b8851(0x1e3),'syncing':_0x3b8851(0x1e9),'offline':'已離線，編輯將儲存在本機'},'session':{'connection-failed':_0x3b8851(0x1f2),'will-retry':_0x3b8851(0x1ef),'room-full':_0x3b8851(0x1d9),'join-failed':_0x3b8851(0x1e6),'room-not-exists':'加入協作失敗，您的編輯將暫存於本機。','room-permission-denied':_0x3b8851(0x1e7),'room-cnt-exceeds':'協作文件數量超過限制，您的編輯將暫存於本機。','collaboration-timeout':'伺服器未回應協作請求，您的編輯將儲存在本機。'},'conflict':{'title':_0x3b8851(0x1dc),'content':_0x3b8851(0x1e4)},'permission':{'title':_0x3b8851(0x1df),'content':_0x3b8851(0x1e8)},'collaboration':{'single-unit':{'warning':_0x3b8851(0x1da)},'closeRoom':'由於協作房間已關閉，編輯權限已被收回。'},'auth':{'needGotoLoginAlert':_0x3b8851(0x1f0)}}};function _0x5e7a(_0x3f4940,_0x1cfd05){_0x3f4940=_0x3f4940-0x1d9;const _0x47fc5e=_0x47fc();let _0x5e7a99=_0x47fc5e[_0x3f4940];return _0x5e7a99;}function _0x47fc(){const _0x3bae62=['沒有協作權限，您的編輯將暫存於本機。','您的操作與伺服器權限存在衝突。請將您的本機編輯儲存至其他地方，重新整理頁面後將會被捨棄。','同步中...','259nbSoVZ','99vKJwxg','47418WhBGHN','70eVkUSc','7097544RBEGxw','連線失敗，將在稍後重試連線。','您的登入已過期，點擊「確定」重新登入，點擊「取消」儲存您的本機編輯。','5tMjDit','連線失敗，請檢查您的網路。','503545sraJxd','68984GdEPIv','此文件協作人數已達上限，您的編輯將暫存於本機。','您在另一個分頁開啟了同一個檔案。為避免資料遺失，此分頁將無法進行編輯。','2VVXenT','協作衝突','1355739bhtQrz','105480mSqOzv','認證錯誤','113672DbtIwV','本機檔案','正在擷取伺服器資料...','已同步','您的本機文件與伺服器文件存在衝突。請將您的本機編輯儲存至其他地方，因為重新整理頁面後將會遺失。','編輯衝突','加入協作失敗，請稍後重試，您的編輯將暫存於本機。'];_0x47fc=function(){return _0x3bae62;};return _0x47fc();}export{e as default};
+function _0x4f67(_0x37b400,_0xa878c9){_0x37b400=_0x37b400-0x113;const _0x368765=_0x3687();let _0x4f67b5=_0x368765[_0x37b400];return _0x4f67b5;}const _0x2914f5=_0x4f67;(function(_0x11c453,_0x3134de){const _0xa3b454=_0x4f67,_0x34354d=_0x11c453();while(!![]){try{const _0x18c234=-parseInt(_0xa3b454(0x116))/0x1+parseInt(_0xa3b454(0x113))/0x2*(-parseInt(_0xa3b454(0x11e))/0x3)+-parseInt(_0xa3b454(0x128))/0x4*(parseInt(_0xa3b454(0x12e))/0x5)+-parseInt(_0xa3b454(0x118))/0x6*(-parseInt(_0xa3b454(0x127))/0x7)+-parseInt(_0xa3b454(0x12d))/0x8*(parseInt(_0xa3b454(0x129))/0x9)+-parseInt(_0xa3b454(0x122))/0xa+parseInt(_0xa3b454(0x114))/0xb*(parseInt(_0xa3b454(0x126))/0xc);if(_0x18c234===_0x3134de)break;else _0x34354d['push'](_0x34354d['shift']());}catch(_0x28af09){_0x34354d['push'](_0x34354d['shift']());}}}(_0x3687,0x839c9));function _0x3687(){const _0x26e3b6=['您的操作與伺服器權限存在衝突。請將您的本機編輯儲存至其他地方，重新整理頁面後將會被捨棄。','已同步','6348VlHQSA','736127VGSwPM','4iZRvyT','1368243XWoAUP','您在另一個分頁開啟了同一個檔案。為避免資料遺失，此分頁將無法進行編輯。','認證錯誤','連線失敗，請檢查您的網路。','40rvCMSL','5317320XKYKLl','11854MJBSmg','64823YnscKq','伺服器未回應協作請求，您的編輯將儲存在本機。','501223miiTlD','加入協作失敗，請稍後重試，您的編輯將暫存於本機。','30MFGwsb','您的本機文件與伺服器文件存在衝突。請將您的本機編輯儲存至其他地方，因為重新整理頁面後將會遺失。','此文件協作人數已達上限，您的編輯將暫存於本機。','您的登入已過期，點擊「確定」重新登入，點擊「取消」儲存您的本機編輯。','本機檔案','協作文件數量超過限制，您的編輯將暫存於本機。','393PuwtWd','編輯衝突','協作衝突','加入協作失敗，您的編輯將暫存於本機。','28620IDcTPh','同步中...'];_0x3687=function(){return _0x26e3b6;};return _0x3687();}const e={'collaboration-client':{'collabClient':{'tooltip':{'reconnect':'點擊重新連線'}},'collabStatus':{'fetchMiss':'正在擷取伺服器資料...','conflict':_0x2914f5(0x11f),'notCollab':_0x2914f5(0x11c),'synced':_0x2914f5(0x125),'syncing':_0x2914f5(0x123),'offline':'已離線，編輯將儲存在本機'},'session':{'connection-failed':_0x2914f5(0x12c),'will-retry':'連線失敗，將在稍後重試連線。','room-full':_0x2914f5(0x11a),'join-failed':_0x2914f5(0x117),'room-not-exists':_0x2914f5(0x121),'room-permission-denied':'沒有協作權限，您的編輯將暫存於本機。','room-cnt-exceeds':_0x2914f5(0x11d),'collaboration-timeout':_0x2914f5(0x115)},'conflict':{'title':_0x2914f5(0x120),'content':_0x2914f5(0x119)},'permission':{'title':_0x2914f5(0x12b),'content':_0x2914f5(0x124)},'collaboration':{'single-unit':{'warning':_0x2914f5(0x12a)},'closeRoom':'由於協作房間已關閉，編輯權限已被收回。'},'auth':{'needGotoLoginAlert':_0x2914f5(0x11b)}}};export{e as default};

package/lib/types/config/config.d.ts

@@ -28,7 +28,26 @@ export interface IUniverCollaborationClientConfig {
      * Override internal modules with custom implementations.
      */
     override?: DependencyOverride;
+    /**
+     * How long local edits are batched before they are sent as one changeset, in milliseconds. Edits made within
+     * this window after the first one go into the same changeset. This is a batching delay, not a network timeout;
+     * for the acknowledgement timeout see `changesetAckTimeout`.
+     * @default 2000
+     */
     sendChangesetTimeout?: number;
+    /**
+     * How long to wait for the server's acknowledgement of a changeset before sending it again, in milliseconds.
+     * Later resends wait twice as long each time, up to `maxChangesetAckTimeout`. The request that submits the
+     * changeset is given the same timeout.
+     * @default 20000
+     */
+    changesetAckTimeout?: number;
+    /**
+     * The longest wait between two resends of an unacknowledged changeset, in milliseconds. Set it equal to
+     * `changesetAckTimeout` for a constant interval.
+     * @default 120000
+     */
+    maxChangesetAckTimeout?: number;
     snapshotServerUrl?: string;
     collabSubmitChangesetUrl?: string;
     collabWebSocketUrl?: string;

package/lib/types/controllers/collaboration/changeset-submitter.d.ts

@@ -0,0 +1,132 @@
+import type { IChangeset } from '@univerjs-pro/collaboration';
+import type { ICollaborationSendOptions } from '../../services/socket/collaboration-socket.service';
+/** Why the awaiting changeset was sent again. */
+export type ChangesetResendReason = 'ack_timeout' | 'should_retry' | 'reconnect' | 'request_failed';
+/** Emitted every time an awaiting changeset is sent again. The first send is not an event. */
+export interface IChangesetResendEvent {
+    unitID: string;
+    reqId: number;
+    reason: ChangesetResendReason;
+    /** How many times the changeset has been resent, counting this one. */
+    attempt: number;
+    /** Milliseconds since the changeset was first sent. */
+    elapsedMs: number;
+    /** Mutations in the awaiting changeset plus pending mutations not yet sent. */
+    unsyncedMutationCount: number;
+    /** Milliseconds until the next resend if nothing is heard from the server. */
+    nextDelayMs: number;
+}
+export type ChangesetResendInfo = Omit<IChangesetResendEvent, 'unitID'>;
+/** The first wait for an acknowledgement before the awaiting changeset is resent. */
+export declare const DEFAULT_ACK_TIMEOUT = 20000;
+/** The longest wait for an acknowledgement between two resends. */
+export declare const MAX_ACK_TIMEOUT = 120000;
+/** The longest backoff between two resends requested by the server or caused by a failed request. */
+export declare const MAX_RETRY_TIMEOUT = 20000;
+/**
+ * Hands a changeset to the transport. `options.timeout` is how long the transport may wait for the server to
+ * answer: it equals the wait for the acknowledgement, so a request that is still unanswered when the changeset is
+ * sent again is given up at the same moment. The returned promise, when there is one, rejects when the request
+ * failed; its resolution is not used.
+ */
+export type SendChangeset = (changeset: IChangeset, options: ICollaborationSendOptions) => void | Promise<void>;
+/** What the bound state provides for a resend: the awaiting changeset as it currently is, and the unsynced count. */
+export interface IChangesetSubmitterSource {
+    changeset: IChangeset;
+    /** Mutations in the awaiting changeset plus pending mutations not yet sent. */
+    unsyncedMutationCount: number;
+}
+export interface IChangesetSubmitterOptions {
+    /** The first wait for an acknowledgement. Defaults to `DEFAULT_ACK_TIMEOUT`. */
+    ackTimeout?: number;
+    /** The longest wait between two resends. Defaults to `MAX_ACK_TIMEOUT`, and never less than `ackTimeout`. */
+    maxAckTimeout?: number;
+    onResend?: (info: ChangesetResendInfo) => void;
+    now?: () => number;
+}
+/**
+ * Submits one changeset and sends it again until the server acknowledges it.
+ *
+ * It is created when the changeset is first sent and handed from one state to the next while the
+ * changeset is kept, so the pending timer, the intervals and the attempt count survive state transitions.
+ * The states only tell it to `submit`, `requestRetry` and `dispose`; everything about delivery (timers, backoff,
+ * attempt counting) stays here. There is at most one timer at a time: every trigger replaces the previous one.
+ *
+ * - After every send, an acknowledgement timeout is armed (`ackTimeout`, then doubled up to `maxAckTimeout`).
+ *   The request itself is given the same timeout, so an unanswered request is cancelled when the changeset is
+ *   sent again.
+ * - A `changeset_should_retry` from the server replaces the timer with a short backoff (0, 1s, 2s, ... up to
+ *   `MAX_RETRY_TIMEOUT`). A request that fails for a transient reason (network error, 408, 429, 5xx) does the
+ *   same; other failures and the request timeout leave the timer alone. The two intervals are counted
+ *   independently.
+ * - A timer that fires while no state is bound (e.g. while missing changesets are fetched) is remembered and
+ *   runs as soon as the next awaiting state binds.
+ */
+export declare class ChangesetSubmitter {
+    private readonly _send;
+    private readonly _options;
+    private _attempt;
+    private readonly _firstSentAt;
+    private _ackTimeout;
+    private readonly _maxAckTimeout;
+    private _retryBackoff;
+    private _nextDelay;
+    private _timer;
+    private _pendingReason;
+    private _source;
+    /** Identifies the latest send; the outcome of an earlier send is ignored. */
+    private _sendToken;
+    private _disposed;
+    private readonly _now;
+    private _reqId;
+    constructor(reqId: number, _send: SendChangeset, _options?: IChangesetSubmitterOptions);
+    /** The request id of the changeset. It is assigned by the transport on the first send and read back then. */
+    get reqId(): number;
+    get attempt(): number;
+    get nextDelayMs(): number;
+    get elapsedMs(): number;
+    /**
+     * Bind the state that owns the awaiting changeset. `source` returns the changeset as it currently is (it may
+     * have been transformed since the last send) and the number of unsynced mutations. A resend that came due
+     * while nothing was bound runs now.
+     */
+    bind(source: () => IChangesetSubmitterSource): void;
+    /** Detach the current state while the changeset is handed to the next one. Timers keep running. */
+    unbind(): void;
+    /**
+     * Send the changeset and wait for its acknowledgement.
+     *
+     * Without `reason` this is the first send of the changeset, which is not reported as a resend. With `reason`
+     * it is a resend triggered outside this submitter (e.g. after a reconnect): it counts as an attempt and
+     * notifies the listener.
+     */
+    submit(changeset: IChangeset, unsyncedMutationCount: number, reason?: ChangesetResendReason): void;
+    /**
+     * Wait for the acknowledgement of a send that happened outside this submitter, e.g. a changeset restored
+     * from the cache that the entity resends itself.
+     */
+    armAckTimeout(): void;
+    /** The server asked for the changeset to be resent: replace the current timer with the short backoff. */
+    requestRetry(): void;
+    /** The changeset was acknowledged, rejected or dropped. */
+    dispose(): void;
+    private _deliver;
+    /**
+     * The request did not reach the server. A transient failure brings the next send forward to the short
+     * backoff; the acknowledgement timeout keeps its own count. A request that ran into its timeout is ignored:
+     * the changeset is being sent again at that very moment. So is the failure of a request that a later send
+     * superseded, e.g. when the server asked for a retry before the request was answered.
+     */
+    private _onRequestFailed;
+    private _schedule;
+    private _resend;
+    /** Count a resend and move the interval it belongs to; the request timeout follows the new interval. */
+    private _countResend;
+    private _notifyResend;
+    private _clearTimer;
+}
+/**
+ * How long to wait before sending again after a failed request, or `null` when the failure should not bring
+ * the next send forward.
+ */
+export declare function getRetryDelay(error: unknown, backoff: number): number | null;

package/lib/types/controllers/collaboration/collaboration-entity.d.ts

@@ -1,7 +1,9 @@
 import type { IDisposable, IMutationInfo, Nullable, UniverInstanceType } from '@univerjs/core';
 import type { Observable } from 'rxjs';
 import type { CollaborationSession } from '../../services/collaboration-session/collaboration-session';
-import type { CollaborationState, ICollaborationStateHandler, PrepareTransformSelectionsHandler, SyncEditingCollabCursorHandler, TransformIMEHandler, TransformRemoteChangesetByIMECache, TransformRemoteChangesetByStateCache, TransformSelectionsHandler, TransformStateHandler } from './collaboration-state';
+import type { IUnitCacheData } from '../../services/local-cache/local-cache.service';
+import type { IChangesetResendEvent } from './changeset-submitter';
+import type { CollaborationState, ICollaborationStateHandler, IConflictInfo, PrepareTransformSelectionsHandler, SyncEditingCollabCursorHandler, TransformIMEHandler, TransformRemoteChangesetByIMECache, TransformRemoteChangesetByStateCache, TransformSelectionsHandler, TransformStateHandler } from './collaboration-state';
 import { CompressMutationService, RevisionService } from '@univerjs-pro/collaboration';
 import { ICommandService, ILogService, Injector, IPermissionService, IUniverInstanceService, LocaleService, RxDisposable } from '@univerjs/core';
 import { DocStateChangeManagerService } from '@univerjs/docs';
@@ -11,6 +13,20 @@ import { ILocalCacheService } from '../../services/local-cache/local-cache.servi
 import { SheetTransformSelectionsService } from '../../services/range-selection/sheet-transform-selections.service';
 import { ISingleActiveUnitService } from '../../services/single-active-unit/single-active-unit.service';
 import { CollaborationStatus } from './collaboration-state';
+/**
+ * Emitted once when a unit enters the conflict state, after its offline cache has been cleared. Carries
+ * `IConflictInfo` and the local edits the server has not acknowledged.
+ */
+export interface ICollaborationConflictEvent extends IConflictInfo {
+    unitID: string;
+    /**
+     * The local edits the server has not acknowledged, in the format of the offline cache, or `null` when there are
+     * none. `awaitingChangeset` has been sent; whether the server applied it is unknown.
+     */
+    localChanges: IUnitCacheData | null;
+    /** Whether the offline cache of the unit was cleared. When `false`, a page reload replays the cached edits. */
+    cacheCleared: boolean;
+}
 /**
  * Each univer document instance would map to an `CollaborationEntity` to handle collaborated editing events.
  */
@@ -37,6 +53,12 @@ export declare abstract class CollaborationEntity extends RxDisposable {
     protected _changesetSessionId: string;
     protected _changesetReqId: number;
     readonly status$: Observable<CollaborationStatus>;
+    private readonly _changesetResend$;
+    /** Emits every time the awaiting changeset is sent again because it was not acknowledged. */
+    readonly changesetResend$: Observable<IChangesetResendEvent>;
+    private readonly _conflict$;
+    /** Emits once when the unit enters the conflict state, after its offline cache has been cleared. */
+    readonly conflict$: Observable<ICollaborationConflictEvent>;
     constructor(unitID: string, session: CollaborationSession, _type: UniverInstanceType, _injector: Injector, _compressMutationService: CompressMutationService, _localeService: LocaleService, _revisionService: RevisionService, _eventService: CollaborationUIEventService, _univerInstanceService: IUniverInstanceService, _logService: ILogService, _commandService: ICommandService, _permissionService: IPermissionService, _singleActiveUnitService?: ISingleActiveUnitService | undefined, _localCacheService?: ILocalCacheService | undefined);
     init(): Promise<void>;
     /**
@@ -45,6 +67,9 @@ export declare abstract class CollaborationEntity extends RxDisposable {
      */
     pauseCollaboration(): IDisposable;
     onLocalMutation(command: IMutationInfo): void;
+    /** Whether there are local mutations that the server has not acknowledged yet. */
+    hasWritePending(): boolean;
+    dispose(): void;
     private _updateState;
     protected _init(): Promise<CollaborationState>;
     /**
@@ -53,6 +78,8 @@ export declare abstract class CollaborationEntity extends RxDisposable {
     private _transitionLocked;
     private _unlockTransition;
     private _lockTransition;
+    /** Run one transition under the lock. The lock is released even when the state throws, so the next event can be handled. */
+    private _transit;
     protected _onLocalMutation(command: IMutationInfo): void;
     private _remoteChangesetQueue;
     private _onRemoteChangeset;

package/lib/types/controllers/collaboration/collaboration-state.d.ts

@@ -1,15 +1,18 @@
 import type { IAcknowledgedChangeset, IChangeset } from '@univerjs-pro/collaboration';
 import type { IMutationInfo, Nullable } from '@univerjs/core';
-import type { Observable } from 'rxjs';
+import type { IUnitCacheData } from '../../services/local-cache/local-cache.service';
 import type { ICollaborativeUndoRedoService } from '../../services/undoredo/collaborative-undoredo.service';
+import type { ChangesetResendInfo, ChangesetResendReason } from './changeset-submitter';
+import type { ICollaborationSendOptions } from '../../services/socket/collaboration-socket.service';
 import { ITransformService, RevisionService } from '@univerjs-pro/collaboration';
-import { ICommandService, IConfigService, ILogService, Injector, IPermissionService, IUniverInstanceService, LocaleService, UniverInstanceType, UserManagerService } from '@univerjs/core';
+import { ICommandService, IConfigService, ILogService, Injector, IPermissionService, IUniverInstanceService, UniverInstanceType, UserManagerService } from '@univerjs/core';
 import { CollaborationUIEventService } from '../../services/collaboration-ui-event/collaboration-ui-event';
 import { ILocalCacheService } from '../../services/local-cache/local-cache.service';
+import { ChangesetSubmitter } from './changeset-submitter';
 /** Provide both states when and after changing, so the parent could examine if state transition is correct. */
 export type StateChangeHandler = (before: CollaborationState, after: CollaborationState) => void;
 /** A network interface to send changeset and  */
-export type SendChangesetHandler = (changeset: IChangeset) => void;
+export type SendChangesetHandler = (changeset: IChangeset, options: ICollaborationSendOptions) => void | Promise<void>;
 export type MissingChangesetsHandler = (params: {
     from: number;
     to: number;
@@ -36,7 +39,57 @@ export interface ICollaborationStateHandler {
     onSyncEditingCollabCursor?: SyncEditingCollabCursorHandler;
     onTransformRemoteChangesetByIMECache?: TransformRemoteChangesetByIMECache;
     onTransformRemoteChangesetByStateCache?: TransformRemoteChangesetByStateCache;
+    /** The awaiting changeset was sent again. */
+    onChangesetResend?: (info: ChangesetResendInfo) => void;
+    /**
+     * The unit entered `ConflictState` and its recovery preparation is done: the unacknowledged local edits are backed
+     * up and the offline cache is cleared (`cacheCleared` tells whether that succeeded). Called once per conflict.
+     */
+    onConflict?: (info: IConflictInfo, localChanges: IUnitCacheData | null, cacheCleared: boolean) => void;
+    /** How long to wait for an acknowledgement before resending; see `IUniverCollaborationClientConfig`. */
+    resendTimeouts?: {
+        ackTimeout?: number;
+        maxAckTimeout?: number;
+    };
+}
+/** Why a unit entered `ConflictState`. */
+export type ConflictReason = 
+/** A remote changeset could not be transformed against the local edits. */
+'transform_failed'
+/** A remote changeset was transformed but one of its mutations failed to execute. */
+ | 'apply_failed'
+/** The server rejected the local changeset. */
+ | 'changeset_rejected'
+/** The server rejected the local changeset for lack of permission. */
+ | 'permission_rejected'
+/** Another collaborator reverted the unit to a historical revision. */
+ | 'remote_revert';
+/** The remote revert that caused a `remote_revert` conflict. */
+export interface IRemoteRevertInfo {
+    /** The revision that was restored. */
+    revision: number;
+    /** The member ID of the collaborator who restored it. */
+    memberId: string;
+    /** The user ID of the collaborator who restored it. */
+    userId: string;
+}
+/** Why a unit entered `ConflictState`. */
+export interface IConflictInfo {
+    reason: ConflictReason;
+    /** The error message, when the conflict was caused by an error. */
+    message?: string;
+    /** Present when `reason` is `remote_revert`. */
+    revert?: IRemoteRevertInfo;
+}
+/** A remote changeset was transformed successfully but executing its mutations failed. */
+export declare class RemoteChangesetApplyError extends Error {
+    readonly applyError: unknown;
+    constructor(applyError: unknown);
 }
+/** How a remote changeset relates to the local copy, see `CollaborationState._classifyRemoteChangeset`. */
+export type RemoteChangesetKind = 'echo' | 'remote_revert' | 'applied' | 'missing' | 'apply';
+/** How an acknowledgement relates to the local copy, see `CollaborationState._classifyAck`. */
+export type RemoteAckKind = 'ack_of_awaiting' | 'stale' | 'missing' | 'next';
 export declare enum CollaborationStatus {
     NOT_COLLAB = "not_collab",
     SYNCED = "synced",
@@ -47,20 +100,6 @@ export declare enum CollaborationStatus {
     CONFLICT = "conflict",
     OFFLINE = "offline"
 }
-/**
- * The retry of an awaiting changeset. It is handed from one state to the next while the awaiting changeset is
- * kept, so the pending timer, the backoff and the total retry time survive state transitions.
- */
-export interface IResendSchedule {
-    /** The pending retry. `undefined` once it has fired and the awaiting changeset was resent. */
-    timer: Observable<{
-        reqId: number;
-    }> | undefined;
-    /** The backoff before the next retry. */
-    timeout: number;
-    /** The total backoff spent on this awaiting changeset, bounded by `MAX_RETRY_TOTAL_TIMEOUT`. */
-    total: number;
-}
 /**
  * Use state machine to manage syncing states.
  * An explanation to how these states are transformed to each other.
@@ -82,7 +121,18 @@ export declare abstract class CollaborationState {
     constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: Nullable<IChangeset>, pendingMutations: IMutationInfo[], 
     /** State may change internally. Parent module should provide a callback to handle this event.  */
     _handler: ICollaborationStateHandler, _commandService: ICommandService, _undoRedoService: ICollaborativeUndoRedoService, _revisionService: RevisionService, _localCacheService?: ILocalCacheService | undefined);
-    abstract resend(): void;
+    /**
+     * Send the awaiting changeset again. Only states that keep an awaiting changeset implement it.
+     * @param reason Why the changeset is resent. Defaults to `reconnect`.
+     */
+    abstract resend(reason?: ChangesetResendReason): void;
+    /** Whether there are local mutations that the server has not acknowledged yet. */
+    hasLocalChanges(): boolean;
+    /** Release timers held by the state. Called when the entity is disposed while the state is current. */
+    dispose(): void;
+    /** Mutations in the awaiting changeset plus the pending mutations. */
+    protected _unsyncedMutationCount(): number;
+    protected _createChangesetSubmitter(changeset: IChangeset): ChangesetSubmitter;
     /**
      * Append a location mutation to collaboration queue.
      *
@@ -111,13 +161,48 @@ export declare abstract class CollaborationState {
     abstract toggleOffline(): CollaborationState;
     abstract toggleOnline(): CollaborationState;
     /**
-     * Check if there are some changesets missing. If true, the state should abort this changeset and request
-     * for missing changesets. Missing changesets will later be passed to `onRemoteChangeset` method.
+     * Classify a remote changeset against the local copy. Pure: nothing is requested from the server.
      *
-     * @param changeset The changeset sent from the remote collaboration server.
-     * @returns There is some changeset missing.
+     * - `echo`: the awaiting changeset came back as a broadcast, e.g. when the request was committed after the client
+     *   reconnected with another member id. It acknowledges the awaiting changeset even when the loaded snapshot
+     *   already contains its revision, so it is checked first.
+     * - `applied`: servers may deliver a changeset more than once or out of order, e.g. when several server nodes
+     *   relay changesets, or after the snapshot used to join already contains it. Applied revisions are ignored.
+     * - `missing`: there is a gap before this changeset. The missing changesets have to be fetched first.
+     * - `apply`: the changeset is the next revision and can be transformed and applied.
      */
-    protected _checkMissing(changeset: IChangeset | IAcknowledgedChangeset): boolean;
+    protected _classifyRemoteChangeset(changeset: IChangeset): RemoteChangesetKind;
+    /**
+     * Classify an acknowledgement against the local copy. Pure: nothing is requested from the server.
+     *
+     * - `ack_of_awaiting`: the revision is already applied but sid/reqId match the awaiting changeset, i.e. the
+     *   changeset was committed before the loaded snapshot, which already contains it.
+     * - `stale`: the revision is already applied and belongs to an earlier changeset.
+     * - `missing`: there is a gap before the acknowledged revision. The missing changesets have to be fetched first.
+     * - `next`: the acknowledged revision is the next one.
+     */
+    protected _classifyAck(ack: IAcknowledgedChangeset): RemoteAckKind;
+    /**
+     * Handle a remote changeset the way every online state does: an echo acknowledges the awaiting changeset, an
+     * applied revision is ignored, a gap is requested from the server before `onMissing` transits to
+     * `FetchingMissState`, and the next revision is handed to `onApply`.
+     */
+    protected _dispatchRemoteChangeset(changeset: IChangeset, handlers: {
+        onMissing: (changeset: IChangeset) => CollaborationState;
+        onApply: (changeset: IChangeset) => CollaborationState;
+        /** The unit was reverted on the server: enter `ConflictState` with `_remoteRevertInfo(changeset)`. */
+        onRemoteRevert: (changeset: IChangeset) => CollaborationState;
+    }): CollaborationState;
+    /** The conflict info of a remote changeset that reverts this unit. */
+    protected _remoteRevertInfo(changeset: IChangeset): IConflictInfo;
+    /** The conflict info of an error thrown while transforming or applying a remote changeset. */
+    protected _conflictInfoFromError(error: unknown): IConflictInfo;
+    /** The conflict info of a rejection from the server. */
+    protected _rejectionInfo(config?: {
+        isPermissionRej: boolean;
+    }): IConflictInfo;
+    /** Request the changesets after the current revision up to `revision`: left open, right closed. */
+    protected _requestMissingChangesets(revision: number): void;
     /** Transform undo redo mutations in the undo redo stack.  */
     protected _transformUndoredo(changeset: IChangeset): void;
     /** Transform selections by calling the selection manager service. */
@@ -129,15 +214,7 @@ export declare abstract class CollaborationState {
     protected _transformRemoteChangesetByStateCache(changeset: IChangeset): IChangeset;
     protected _syncEditingCollabCursor(changeset: IChangeset): void;
     protected _getCurrentRevision(): number;
-    /**
-     * Servers may deliver a changeset more than once or out of order, e.g. when several server nodes relay
-     * changesets, or after the snapshot used to join already contains it. Revisions already applied are ignored.
-     */
-    protected _isAppliedRevision(changeset: IChangeset): boolean;
-    /**
-     * The awaiting changeset may come back as a broadcast instead of an acknowledgement, e.g. when the request
-     * was committed after the client reconnected with another member id.
-     */
+    /** The awaiting changeset came back as a broadcast instead of an acknowledgement. */
     protected _isEchoedAwaitingChangeset(remoteChangeset: IChangeset): boolean;
     /**
      * The acknowledgement echoes the committed changeset, so it can be matched to the awaiting changeset by sid/reqId
@@ -160,6 +237,7 @@ export declare class SyncedState extends CollaborationState {
     constructor(unitID: string, type: UniverInstanceType, handler: ICollaborationStateHandler, revisionService: RevisionService, _injector: Injector, undoRedoService: ICollaborativeUndoRedoService, commandService: ICommandService, _logService: ILogService, _transformService: ITransformService, localCacheService?: ILocalCacheService | undefined);
     appendMutation(mutation: IMutationInfo): CollaborationState;
     onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    private _transformAndApply;
     private _onConflict;
     onRemoteAck(changeset: IAcknowledgedChangeset): CollaborationState;
     onRemoteRej(): CollaborationState;
@@ -187,6 +265,7 @@ export declare class PendingState extends CollaborationState {
     constructor(unitID: string, type: UniverInstanceType, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, _injector: Injector, _revisionService: RevisionService, _userManagerService: UserManagerService, _logService: ILogService, commandService: ICommandService, _configService: IConfigService, _transformService: ITransformService, _univerInstanceService: IUniverInstanceService, _undoRedoService: ICollaborativeUndoRedoService, _localCacheService?: ILocalCacheService);
     appendMutation(mutation: IMutationInfo): CollaborationState;
     onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    private _transformAndApply;
     onRemoteAck(changeset: IAcknowledgedChangeset): CollaborationState;
     onRemoteRej(): CollaborationState;
     onRemoteRetry(): CollaborationState;
@@ -195,6 +274,7 @@ export declare class PendingState extends CollaborationState {
     private _getSendChangesetTimeout;
     resend(): void;
     private _clearScheduledTask;
+    dispose(): void;
     private _onConflict;
 }
 /**
@@ -205,27 +285,25 @@ export declare class AwaitingState extends CollaborationState {
     private readonly _logService;
     private readonly _transformService;
     readonly status = CollaborationStatus.AWAITING;
-    private _resendTimeout;
-    private _maxTotalRetryTimeout;
-    private _resendTimer;
-    private _sender;
-    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: IChangeset, handler: ICollaborationStateHandler, schedule: IResendSchedule | undefined, _injector: Injector, revisionService: RevisionService, commandService: ICommandService, _logService: ILogService, _transformService: ITransformService, undoRedoService: ICollaborativeUndoRedoService, localCacheService?: ILocalCacheService);
+    /** Resends the awaiting changeset until it is acknowledged. Handed to the next state that keeps the changeset. */
+    private readonly _submitter;
+    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: IChangeset, handler: ICollaborationStateHandler, submitter: ChangesetSubmitter | undefined, _injector: Injector, revisionService: RevisionService, commandService: ICommandService, _logService: ILogService, _transformService: ITransformService, undoRedoService: ICollaborativeUndoRedoService, localCacheService?: ILocalCacheService);
     appendMutation(mutation: IMutationInfo): CollaborationState;
     onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    private _transformAndApply;
     onRemoteAck(changeset: IAcknowledgedChangeset): CollaborationState;
+    private _toSynced;
     onRemoteRej(config?: {
         isPermissionRej: boolean;
     }): CollaborationState;
     onRemoteRetry(changeset: IChangeset): CollaborationState;
     toggleOffline(): CollaborationState;
     toggleOnline(): CollaborationState;
-    resend(): void;
+    resend(reason?: ChangesetResendReason): void;
     private _onConflict;
-    private _subscribeResendTimer;
-    private _runScheduledResend;
-    /** The retry of the awaiting changeset, to hand to the next state that keeps the changeset. */
-    private _resendSchedule;
-    private _clearScheduledTask;
+    dispose(): void;
+    /** Detach from the submitter before the awaiting changeset is handed to the next state. */
+    private _detachSubmitter;
 }
 /**
  * Some local mutations are sent to the server and waiting for acknowledgement, yet still some local mutations
@@ -237,44 +315,51 @@ export declare class AwaitingWithPendingState extends CollaborationState {
     private readonly _transformService;
     private readonly localCacheService?;
     readonly status = CollaborationStatus.AWAITING_WITH_PENDING;
-    private _resendTimeout;
-    private _maxTotalRetryTimeout;
-    private _resendTimer;
-    private _sender;
-    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: IChangeset, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, schedule: IResendSchedule | undefined, _injector: Injector, revisionService: RevisionService, commandService: ICommandService, _logService: ILogService, _transformService: ITransformService, undoRedoService: ICollaborativeUndoRedoService, localCacheService?: ILocalCacheService | undefined);
+    /** Resends the awaiting changeset until it is acknowledged. Handed to the next state that keeps the changeset. */
+    private readonly _submitter;
+    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: IChangeset, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, submitter: ChangesetSubmitter | undefined, _injector: Injector, revisionService: RevisionService, commandService: ICommandService, _logService: ILogService, _transformService: ITransformService, undoRedoService: ICollaborativeUndoRedoService, localCacheService?: ILocalCacheService | undefined);
     appendMutation(mutation: IMutationInfo): CollaborationState;
     onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    private _transformAndApply;
     onRemoteAck(changeset: IAcknowledgedChangeset): CollaborationState;
+    /** Transit to `PendingState` to schedule another sending task. */
+    private _toPending;
     onRemoteRej(config?: {
         isPermissionRej: boolean;
     }): CollaborationState;
     onRemoteRetry(changeset: IChangeset): CollaborationState;
     toggleOffline(): CollaborationState;
     toggleOnline(): CollaborationState;
-    resend(): void;
+    resend(reason?: ChangesetResendReason): void;
     private _onConflict;
-    private _subscribeResendTimer;
-    private _runScheduledResend;
-    /** The retry of the awaiting changeset, to hand to the next state that keeps the changeset. */
-    private _resendSchedule;
-    private _clearScheduledTask;
+    dispose(): void;
+    /** Detach from the submitter before the awaiting changeset is handed to the next state. */
+    private _detachSubmitter;
 }
 /**
- * This state is special for handling collaboration conflicts.
- *
- * `ConflictState` is a dead end state. It cannot transit to any other state. User could only reload the page to
- * reload the document.
+ * A dead end state: the unit can no longer follow the server. Editing is disabled. `info` says why and `localChanges`
+ * holds the local edits the server has not acknowledged. Reported once through `CollaborationEntity.conflict$`.
  */
 export declare class ConflictState extends CollaborationState {
-    private _isPermissionRej;
+    readonly info: IConflictInfo;
     private readonly _permissionService;
-    private readonly _localeService;
     private readonly _userManagerService;
     private readonly _logService;
     private readonly _collaborationUIEventService;
     private readonly localCacheService?;
     readonly status = CollaborationStatus.CONFLICT;
-    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: Nullable<IChangeset>, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, _isPermissionRej: boolean | undefined, _permissionService: IPermissionService, commandService: ICommandService, undoRedoService: ICollaborativeUndoRedoService, revisionService: RevisionService, _localeService: LocaleService, _userManagerService: UserManagerService, _logService: ILogService, _collaborationUIEventService: CollaborationUIEventService, localCacheService?: ILocalCacheService | undefined);
+    /**
+     * The local edits the server has not acknowledged, in the format of the offline cache, or `null` when there are
+     * none. `awaitingChangeset` has been sent; whether the server applied it is unknown.
+     */
+    readonly localChanges: IUnitCacheData | null;
+    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: Nullable<IChangeset>, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, info: IConflictInfo, _permissionService: IPermissionService, commandService: ICommandService, undoRedoService: ICollaborativeUndoRedoService, revisionService: RevisionService, _userManagerService: UserManagerService, _logService: ILogService, _collaborationUIEventService: CollaborationUIEventService, localCacheService?: ILocalCacheService | undefined);
+    /**
+     * Back up the unacknowledged local edits, then clear the offline cache so that the next load does not replay them
+     * (a cache with pending edits would also make the loader fetch the cached revision). Only then is the conflict
+     * reported, so that the handler may reload the page safely.
+     */
+    private _prepareConflictRecovery;
     appendMutation(): CollaborationState;
     onRemoteChangeset(): CollaborationState;
     onRemoteAck(): CollaborationState;
@@ -283,18 +368,17 @@ export declare class ConflictState extends CollaborationState {
     toggleOffline(): CollaborationState;
     toggleOnline(): CollaborationState;
     resend(): void;
-    private _prepareConflictRecovery;
     private _showConflictProcessingNotification;
-    private _showConflictNotification;
     private _disableEditing;
 }
 export declare class OfflineState extends CollaborationState {
     private readonly _injector;
+    private readonly _logService;
     readonly status = CollaborationStatus.OFFLINE;
-    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: Nullable<IChangeset>, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, _injector: Injector, revisionService: RevisionService, commandService: ICommandService, undoRedoService: ICollaborativeUndoRedoService, localCacheService?: ILocalCacheService);
+    constructor(unitID: string, type: UniverInstanceType, awaitingChangeset: Nullable<IChangeset>, pendingMutations: IMutationInfo[], handler: ICollaborationStateHandler, _injector: Injector, revisionService: RevisionService, commandService: ICommandService, undoRedoService: ICollaborativeUndoRedoService, _logService: ILogService, localCacheService?: ILocalCacheService);
     appendMutation(mutation: IMutationInfo): CollaborationState;
-    onRemoteChangeset(_changeset: IChangeset): CollaborationState;
-    onRemoteAck(): CollaborationState;
+    onRemoteChangeset(changeset: IChangeset): CollaborationState;
+    onRemoteAck(changeset: IAcknowledgedChangeset): CollaborationState;
     onRemoteRej(): CollaborationState;
     onRemoteRetry(): CollaborationState;
     toggleOffline(): CollaborationState;
@@ -315,8 +399,11 @@ export declare class FetchingMissState extends CollaborationState {
      */
     private _acknowledgedAwaitingRevision;
     private _queuedRemoteChangesets;
-    /** The retry of the awaiting changeset. The next awaiting state runs it after the fetch. */
-    private _resendSchedule;
+    /**
+     * The resends of the awaiting changeset. It is not bound while the gap is fetched: a resend that comes due
+     * meanwhile runs once the next awaiting state binds it.
+     */
+    private _submitter;
     private readonly _injector;
     private readonly _logService;
     private readonly _transformService;
@@ -329,8 +416,11 @@ export declare class FetchingMissState extends CollaborationState {
      * the acknowledged server revision here.
      */
     _acknowledgedAwaitingRevision: Nullable<number>, _queuedRemoteChangesets: IChangeset[], handler: ICollaborationStateHandler, 
-    /** The retry of the awaiting changeset. The next awaiting state runs it after the fetch. */
-    _resendSchedule: IResendSchedule | undefined, _injector: Injector, revisionService: RevisionService, _logService: ILogService, commandService: ICommandService, undoRedoService: ICollaborativeUndoRedoService, _transformService: ITransformService, localCacheService?: ILocalCacheService | undefined);
+    /**
+     * The resends of the awaiting changeset. It is not bound while the gap is fetched: a resend that comes due
+     * meanwhile runs once the next awaiting state binds it.
+     */
+    _submitter: ChangesetSubmitter | undefined, _injector: Injector, revisionService: RevisionService, _logService: ILogService, commandService: ICommandService, undoRedoService: ICollaborativeUndoRedoService, _transformService: ITransformService, localCacheService?: ILocalCacheService | undefined);
     onMissedChangesetFetched(changesets: IChangeset[]): CollaborationState;
     private _handleRemoteChangesets;
     private _transformAndApplyRemoteChangeset;
@@ -338,6 +428,8 @@ export declare class FetchingMissState extends CollaborationState {
     private _acknowledgeAwaiting;
     /** The awaiting changeset was committed before the loaded snapshot, so there is no new revision to count. */
     private _dropAcknowledgedAwaiting;
+    private _disposeSubmitter;
+    dispose(): void;
     resend(): void;
     appendMutation(mutation: IMutationInfo<object>): CollaborationState;
     onRemoteChangeset(changeset: IChangeset): CollaborationState;

package/lib/types/controllers/collaboration/collaboration.controller.d.ts

@@ -14,8 +14,15 @@ export declare class CollaborationController extends RxDisposable {
     constructor(_injector: Injector, _collabSessionService: CollaborationSessionService, _configService: IConfigService, _univerInstanceService: IUniverInstanceService);
     dispose(): void;
     getCollabEntity(id: string): Nullable<CollaborationEntity>;
+    /** The entities of every unit that is collaborating now. */
+    getCollabEntities(): CollaborationEntity[];
     getCollabEntity$(id: string): Observable<CollaborationEntity>;
     readyForCollab(id: string): Promise<void>;
+    /**
+     * Whether a unit has local mutations that the server has not acknowledged yet.
+     * @param unitId The unit to check. When omitted, every collaborating unit is checked.
+     */
+    hasWritePending(unitId?: string): boolean;
     private _init;
     /**
      * Start collaboration on a document.