@docx-editor.dev/core/collaboration

isCollaborationFailureCodefunctionSource ↗

True when value is a [CollaborationFailureCode](CollaborationFailureCode) member.

declare function isCollaborationFailureCode(value: string): value is CollaborationFailureCode;

safeParticipantColorfunctionSource ↗

Return value when it is a color this engine can safely paint, otherwise undefined.

declare function safeParticipantColor(value: string | undefined): string | undefined;

CollaborationFailureinterfaceSource ↗

One collaboration failure: a typed code plus optional free-form detail.

interface CollaborationFailure

CollaborationIdentityinterfaceSource ↗

Human or automation identity attached to authored collaboration transactions.

interface CollaborationIdentity

CollaborationLocalSelectioninterfaceSource ↗

Selection published by the local editor through ephemeral awareness.

Publish an anchor address and a head address. Do not materialize every covered paragraph.

interface CollaborationLocalSelection

CollaborationModuleContributioninterfaceSource ↗

What a collaboration module contributes: the replica the surface attaches.

interface CollaborationModuleContribution

CollaborationParticipantinterfaceSource ↗

One validated identity visible through ephemeral collaboration presence.

interface CollaborationParticipant extends CollaborationIdentity

CollaborationRemoteSelectioninterfaceSource ↗

Stable remote selection resolved into this replica's canonical paragraph addresses.

Anchor and head may name different paragraphs. A collapsed caret is the same address twice.

interface CollaborationRemoteSelection

CollaborationRemoteSelectionAddressinterfaceSource ↗

One endpoint of a remote selection resolved into this replica's canonical addresses.

paragraphId is the stable w14:paraId. nodeId is replica-local and is used to paint.

interface CollaborationRemoteSelectionAddress

CollaborationSelectionAddressinterfaceSource ↗

One endpoint of a published selection: a stable paragraph id and a UTF-16 offset.

The wire payload carries only these two endpoints. The receiver walks its own canonical tree to find the paragraphs between them, so a select-all does not grow with document size.

interface CollaborationSelectionAddress

CollaborationStatusSnapshotinterfaceSource ↗

Cached status read. Same reference until status, reason, or last failure change.

interface CollaborationStatusSnapshot

EditorCollaborationSessioninterfaceSource ↗

Optional replication session attached to an editor or headless automation host.

Implementations own replication state only. The attached document port remains the authored authority for reads, layout, paint, and save.

interface EditorCollaborationSession

CollaborationFailureCodetypeSource ↗

Why a replica refused work, left ready, or failed a schema check.

Free-form extras (a transport phrase, a blob key, a store refusal) travel in [CollaborationFailure.detail](CollaborationFailure.detail), not here. invalid-shared-metadata follows that rule: it names one malformed field of the room's shared metadata, and which field is the detail. Distinct from invalid-document-id, which rejects a document id this host passed in. concurrent-seed reports two merged seed transactions in one room; the room cannot be repaired client-side — create a new room from saved bytes.

Two of these name a transport condition a host has to tell apart, because the answers are opposite. transport-disconnected recovers on its own, so wait. authentication-failed never does: the credential the provider re-sent was rejected, so refresh it and rejoin. transport remains the catch-all for a provider that reported neither.

type CollaborationFailureCode = 'already-initialized' | 'authentication-failed' | 'baseline-digest-mismatch' | 'baseline-too-large' | 'blob-digest-mismatch' | 'blob-read' | 'blob-store-full' | 'blob-too-large' | 'collaboration-session-destroyed' | 'collaboration-session-not-attached' | 'collaboration-session-not-ready' | 'collaboration-text-limit' | 'concurrent-seed' | 'document-id-mismatch' | 'duplicate-paragraph-id' | 'experimental-collaboration-body-text-only' | 'experimental-collaboration-existing-paragraphs-only' | 'experimental-collaboration-text-only' | 'experimental-collaboration-untracked-text-only' | 'immutable-baseline-changed' | 'immutable-metadata-changed' | 'initialization-aborted' | 'initialization-timeout' | 'invalid-baseline' | 'invalid-blob-descriptor' | 'invalid-bound' | 'invalid-document-id' | 'invalid-identity' | 'invalid-identity-color' | 'invalid-logical-id' | 'invalid-relationships' | 'invalid-session-id' | 'invalid-shared-metadata' | 'invalid-string' | 'local-mirror-failed' | 'materialize-dropped-content' | 'missing-blob' | 'missing-local-blob' | 'missing-root' | 'no-main-document-part' | 'not-initialized' | 'paragraph-set-mismatch' | 'port-already-attached' | 'protocol-version-mismatch' | 'prototype-key' | 'remote-apply-failed' | 'schema-version-mismatch' | 'shared-schema-invalid' | 'text-too-long' | 'too-many-attributes' | 'too-many-children' | 'too-many-nodes' | 'too-many-parts' | 'too-many-relationships' | 'transport' | 'transport-disconnected' | 'tree-too-deep' | 'unknown-logical-id' | 'unknown-paragraph-id' | 'unsafe-part-name' | 'unsupported-root-key';

CollaborationSelectionKindtypeSource ↗

How a published selection covers the document.

Absent or omitted means a character range. cells means the table rectangle whose corner cells contain the two endpoints. The payload still carries only those endpoints, so a large table selection does not grow with the number of selected cells.

type CollaborationSelectionKind = 'cells';

CollaborationStatustypeSource ↗

Lifecycle state of one collaboration replica.

One axis, because the only question a host has to answer is whether to tell the reader to wait or to reload:

- initializing — joining. Edits are refused. Recovers on its own. - ready — replicating. The only state that accepts edits. - disconnected — the transport dropped. The replica is intact and recovers on its own, so wait rather than reload. Edits are refused until reconnect by default; a session created with offline editing enabled keeps accepting them, and the buffered updates merge on reconnect. - error — this replica no longer agrees with the room. It does not recover: only a reload rejoins. [CollaborationStatusSnapshot.reason](CollaborationStatusSnapshot.reason) says why. - destroyed — torn down. Terminal.

type CollaborationStatus = 'initializing' | 'ready' | 'disconnected' | 'error' | 'destroyed';