@searsuite/sear-plugin-collab API reference

class CollaborationChannel extends CollaborationSession

Long-lived collaboration resource channel shared by standalone and embedded editors. It is the sole owner of transport, revision, pending submissions, ACK handling and rebase state.

constructorconstructor

CollaborationChannel(transport: CollabTransport | (): CollabTransport, platform: Pick<Platform, "warn" | "createId">): CollaborationChannel

transport: CollabTransport | (): CollabTransport
platform: Pick<Platform, "warn" | "createId">

methodapplyExternalEvent

applyExternalEvent(event: CollaborationExternalEvent): void

Applies one transport event while the owning editor dispatches its command.

event: CollaborationExternalEvent

methodattachRemoteApplier

attachRemoteApplier(applier: CollaborationRemoteOperationApplier): (): void

Attaches the one currently mounted editor and replays queued remote effects in revision order.

applier: CollaborationRemoteOperationApplier

methodconnect

connect(options: CollaborationConnectOptions): Promise<void>

options: CollaborationConnectOptions

methoddestroy

destroy(): void

methoddisconnect

disconnect(): void

methodenforceCommandBoundary

enforceCommandBoundary(assertWrite: (): void, runWithoutMutationAuthority?: <Value>(callback: (): Value): Value, dispatchExternalEvent: (event: CollaborationExternalEvent): void): void

Restricts public channel mutations after its owning editor finishes assembly.

assertWrite: (): void
runWithoutMutationAuthority: <Value>(callback: (): Value): Value
dispatchExternalEvent: (event: CollaborationExternalEvent): void

methodgetStatus

getStatus(): CollaborationStatus

methodregisterContributor

registerContributor(contribution: CollaborationContribution): void

Installs one open OT owner contract for the lifetime of this channel.

contribution: CollaborationContribution

methodsubmitLocal

submitLocal(ownerId: string, operations: readonly OTOperation[]): void

Queues a committed local operation batch through the shared collaboration engine.

ownerId: string
operations: readonly OTOperation[]

methodsubscribeStatus

subscribeStatus(listener: (status: CollaborationStatus): void): (): void

listener: (status: CollaborationStatus): void

classCollaborationChannelError source ↗

class CollaborationChannelError extends SearError

Stable public failures raised by a collaboration channel host.

constructorconstructor

CollaborationChannelError(code: CollaborationChannelErrorCode, message: string, details?: Record<string, unknown>): CollaborationChannelError

code: CollaborationChannelErrorCode
message: string
details: Record<string, unknown>

propertycode

readonly code: CollaborationChannelErrorCode

Stable machine-readable identifier for this error category.

Inherited members 9

Inherited from SearError.

classCollabTransport source ↗

class CollabTransport

Abstract transport layer. Swap implementations (WebSocket, BroadcastChannel, polling, etc.) without touching the plugin logic.

constructorconstructor

CollabTransport(): CollabTransport

propertysymbolstatic

readonly symbol: symbol

DI token for resolving CollabTransport.

methodconnect

connect(options: CollaborationTransportConnectOptions): Promise<void>

Opens the collaboration transport and begins receiving messages.

options: CollaborationTransportConnectOptions

methoddisconnect

disconnect(): void

Closes the collaboration transport and releases its listeners.

methodsend

send(message: CollaborationSubmission): void

Sends one encoded collaboration message through the transport.

message: CollaborationSubmission

classHeadlessCollabTransport source ↗

class HeadlessCollabTransport extends CollabTransport

Collaboration transport that keeps the plugin local to the current host.

constructorconstructor

HeadlessCollabTransport(): HeadlessCollabTransport

propertysymbolstatic

readonly symbol: symbol

DI token for resolving HeadlessCollabTransport.

methodconnect

connect(_options: CollaborationTransportConnectOptions): Promise<void>

Opens the collaboration transport and begins receiving messages.

_options: CollaborationTransportConnectOptions

methoddisconnect

disconnect(): void

Closes the collaboration transport and releases its listeners.

methodsend

send(_message: CollaborationSubmission): void

Sends one encoded collaboration message through the transport.

_message: CollaborationSubmission

classSheetCollaborationPlugin source ↗

class SheetCollaborationPlugin extends Plugin<SearCoreSheet, CellProperties, null>, SheetLifecycleController, CollaborationSession

Thin Sheet bridge around the editor-independent collaboration engine.

constructorconstructor

SheetCollaborationPlugin(channelBinding: CollaborationChannelBinding, plugins: PluginManager<SearCoreSheet, CellProperties>, commands: SheetCommandBus): SheetCollaborationPlugin

channelBinding: CollaborationChannelBinding
plugins: PluginManager<SearCoreSheet, CellProperties>
commands: SheetCommandBus

propertyinterestedIn

readonly interestedIn: string[]

Declares which Sheet OT action names this plugin is interested in. The engine will only call apply when a transaction contains at least one operation matching these action names, unless the transaction is owned by this plugin.

['uc', 'rr', 'rc'] — only called for UpdateCell, ResizeRow, ResizeCol
['*'] — called for any transaction (wildcard)
[] — only called for this plugin's own transactions

propertywarnOnDuplicateDepth

readonly warnOnDuplicateDepth: false

Whether PluginManager should warn when another ordered plugin shares this depth.

propertysymbolstatic

readonly symbol: typeof symbol

methodapply

apply(_state: null, _transaction: Transaction): null

Applies a transaction to plugin-owned state and returns the next state.

_state: null
_transaction: Transaction

methodconnect

connect(options: CollaborationConnectOptions): Promise<void>

options: CollaborationConnectOptions

methoddestroy

destroy(): void

methoddisconnect

disconnect(): void

methodgetPluginConfig

getPluginConfig(): null

Returns this plugin's runtime configuration view for the current core.

methodgetStatus

getStatus(): CollaborationStatus

methodonTransactionCommitted

onTransactionCommitted(transaction: Transaction): void

Runs only after every step in the enclosing pipeline has succeeded and all staged plugin state has been committed. Use it for derived caches, notifications, persistence, and transport; never perform those effects in apply, because a later pipeline step may still fail.

transaction: Transaction: A committed transaction from the completed pipeline.

methodregisterCommands

registerCommands(commands: SheetCommandBus): void

commands: SheetCommandBus

methodregisterObservations

registerObservations(observations: ObservationRegistry): void

observations: ObservationRegistry

methodregisterState

registerState(): { dataEngine: { enabled: boolean }; key: PluginKey; state: null }

Registers one or more plugin-owned state records with the host manager.

methodrender

render(): null

Produces scene nodes owned by this plugin for the current core state.

methodstart

start(_context: SheetLifecycleContext): void

_context: SheetLifecycleContext

Inherited members 27

Inherited from Plugin.

classWebSocketTransport source ↗

class WebSocketTransport extends CollabTransport

Browser WebSocket implementation of CollabTransport.

The authority validates and orders submitted operation batches while this adapter owns only WebSocket lifecycle and JSON framing.

constructorconstructor

WebSocketTransport(): WebSocketTransport

methodconnect

connect(options: CollaborationTransportConnectOptions): Promise<void>

Opens the collaboration transport and begins receiving messages.

options: CollaborationTransportConnectOptions

methoddisconnect

disconnect(): void

Closes the collaboration transport and releases its listeners.

methodsend

send(message: CollaborationSubmission): void

Sends one encoded collaboration message through the transport.

message: CollaborationSubmission

Inherited members 1

Inherited from CollabTransport.

symbol

interfaceCollaborationChannelBinding source ↗

interface CollaborationChannelBinding

DI value used to distinguish editor-owned channels from host-retained channels.

propertychannel

readonly channel: CollaborationChannel

propertyowner

readonly owner: "editor" | "host"

interfaceCollaborationConnectOptions source ↗

interface CollaborationConnectOptions

propertyresourceId

readonly resourceId: string

propertyrevision

readonly revision?: number

propertyurl

readonly url: string

interfaceCollaborationRemoteOperations source ↗

interface CollaborationRemoteOperations

Remote operation batch delivered to the currently mounted editor bridge.

propertyoperations

readonly operations: readonly OTOperation[]

propertyownerId

readonly ownerId: string

propertyserverRevision

readonly serverRevision: number

interfaceCollaborationSession source ↗

interface CollaborationSession

Host-facing lifecycle API independent from a concrete editor bridge.

methodconnect

connect(options: CollaborationConnectOptions): Promise<void>

options: CollaborationConnectOptions

methoddisconnect

disconnect(): void

methodgetStatus

getStatus(): CollaborationStatus

interfaceCollaborationStatus source ↗

interface CollaborationStatus

propertyerror

readonly error: unknown

propertypendingCount

readonly pendingCount: number

propertyresourceId

readonly resourceId: string | null

propertyrevision

readonly revision: number

propertystate

readonly state: CollaborationConnectionState

interfaceCollaborationTransportConnectOptions source ↗

interface CollaborationTransportConnectOptions

Connection parameters for one collaboration resource.

propertyresourceId

readonly resourceId: string

propertyrevision

readonly revision: number

propertyurl

readonly url: string

interfaceConnectSheetCollaborationResult source ↗

interface ConnectSheetCollaborationResult extends SheetCommandResult

Command result that resolves when the collaboration transport is connected.

propertycompletion

readonly completion: Promise<void>

Optional asynchronous completion of a command-owned external effect.

Inherited members 3

Inherited from SheetCommandResult.

interfaceSheetApplyRemoteOperationsInput source ↗

interface SheetApplyRemoteOperationsInput

Input for applying operations received from a collaboration transport.

propertyoperations

readonly operations: readonly Operation[]

Remote operations after local OT transformation.

propertyownerId

readonly ownerId: string

Stable collaboration owner id resolved through the local plugin registry.

typeCollaborationChannelErrorCode source ↗

type CollaborationChannelErrorCode = typeof CollaborationChannelErrorCode[keyof typeof CollaborationChannelErrorCode]

typeCollaborationConnectionState source ↗

type CollaborationConnectionState = typeof CollaborationConnectionState[keyof typeof CollaborationConnectionState]

Public lifecycle state of one collaboration session.

typeCollaborationExternalEvent source ↗

type CollaborationExternalEvent = { epoch: number; kind: "connected"; resourceId: string } | { epoch: number; error: unknown; kind: "failed"; resourceId: string } | { epoch: number; kind: "message"; message: CollaborationServerMessage }

Transport event returned to the owning editor's command bus.

typeCollaborationRemoteOperationApplier source ↗

type CollaborationRemoteOperationApplier = (effect: CollaborationRemoteOperations): void

variableApplyRemoteOperationsCommand source ↗

ApplyRemoteOperationsCommand: SheetCommandDefinition<SheetApplyRemoteOperationsInput, SheetCommandResult>

Command that applies remote collaboration operations through the normal pipeline.

variableApplySheetCollaborationEventCommand source ↗

ApplySheetCollaborationEventCommand: SheetCommandDefinition<CollaborationExternalEvent, SheetCommandResult>

Routes an external transport event into the owning Sheet command bus.

variableCollaborationChannelBinding source ↗

CollaborationChannelBinding: { symbol: symbol }

variableCollaborationChannelErrorCode source ↗

CollaborationChannelErrorCode: { AttachmentConflict: "SEAR_COLLABORATION_ATTACHMENT_CONFLICT"; BoundaryInstalled: "SEAR_COLLABORATION_BOUNDARY_INSTALLED"; ContributorConflict: "SEAR_COLLABORATION_CONTRIBUTOR_CONFLICT"; Destroyed: "SEAR_COLLABORATION_CHANNEL_DESTROYED" }

variableCollaborationConnectionState source ↗

CollaborationConnectionState: { Connecting: "connecting"; Disconnected: "disconnected"; Error: "error"; Online: "online" }

Public lifecycle state of one collaboration session.

variableCollaborationStatusObservation source ↗

CollaborationStatusObservation: StateObservationDefinition<CollaborationStatus>

Editor-local collaboration connection and synchronization status.

variableConnectSheetCollaborationCommand source ↗

ConnectSheetCollaborationCommand: SheetCommandDefinition<CollaborationConnectOptions, ConnectSheetCollaborationResult>

Starts a Sheet collaboration session through the editor command bus.

variableDisconnectSheetCollaborationCommand source ↗

DisconnectSheetCollaborationCommand: SheetCommandDefinition<void, SheetCommandResult>

Disconnects a Sheet collaboration session through the editor command bus.

interfaceCollaborationAcceptedBatch source ↗

interface CollaborationAcceptedBatch

Canonical operation batch accepted and ordered by the authority.

propertybaseRevision

readonly baseRevision: number

propertyclientId

readonly clientId: string

propertykind

readonly kind: "accepted"

propertyoperationId

readonly operationId: string

propertyoperationType

readonly operationType: CollaborationOperationType

propertyownerId

readonly ownerId: string

propertypayload

readonly payload: OTEncodedValue

propertyprotocolVersion

readonly protocolVersion: 1

propertyresourceId

readonly resourceId: string

propertyserverRevision

readonly serverRevision: number

variableCollaborationChannelErrorCodeType source ↗

CollaborationChannelErrorCodeType: { AttachmentConflict: "SEAR_COLLABORATION_ATTACHMENT_CONFLICT"; BoundaryInstalled: "SEAR_COLLABORATION_BOUNDARY_INSTALLED"; ContributorConflict: "SEAR_COLLABORATION_CONTRIBUTOR_CONFLICT"; Destroyed: "SEAR_COLLABORATION_CHANNEL_DESTROYED" }

typeCollaborationClientMessage source ↗

type CollaborationClientMessage = CollaborationSubmission

variableCollaborationConnectionStateType source ↗

CollaborationConnectionStateType: { Connecting: "connecting"; Disconnected: "disconnected"; Error: "error"; Online: "online" }

Public lifecycle state of one collaboration session.

variableCollaborationProtocolVersion source ↗

CollaborationProtocolVersion: 1

Current collaboration wire protocol version.

interfaceCollaborationRejectedMessage source ↗

interface CollaborationRejectedMessage

Explicit authority rejection; clients must not infer recovery from dropped frames.

propertycode

readonly code: string

propertykind

readonly kind: "rejected"

propertymessage

readonly message: string

propertyoperationId

readonly operationId?: string

propertyprotocolVersion

readonly protocolVersion: 1

propertyresourceId

readonly resourceId: string

typeCollaborationServerMessage source ↗

type CollaborationServerMessage = CollaborationAcceptedBatch | CollaborationSyncMessage | CollaborationRejectedMessage

interfaceCollaborationSubmission source ↗

interface CollaborationSubmission

Client submission before the authority assigns a canonical revision.

propertybaseRevision

readonly baseRevision: number

propertyclientId

readonly clientId: string

propertykind

readonly kind: "submit"

propertyoperationId

readonly operationId: string

propertyoperationType

readonly operationType: CollaborationOperationType

propertyownerId

readonly ownerId: string

propertypayload

readonly payload: OTEncodedValue

propertyprotocolVersion

readonly protocolVersion: 1

propertyresourceId

readonly resourceId: string

interfaceCollaborationSyncMessage source ↗

interface CollaborationSyncMessage

Ordered catch-up response sent when a transport joins a resource.

propertybatches

readonly batches: readonly CollaborationAcceptedBatch[]

propertyfromRevision

readonly fromRevision: number

propertykind

readonly kind: "sync"

propertyprotocolVersion

readonly protocolVersion: 1

propertyresourceId

readonly resourceId: string

propertyserverRevision

readonly serverRevision: number