@searsuite/sear-plugin-collab
Connect and observe a session
ConnectSheetCollaborationCommand starts a session over a host-provided transport. The status observation reports connection changes.
- classCollaborationChannel
-
class CollaborationChannel extends CollaborationSessionLong-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.
constructor CollaborationChannel(transport: CollabTransport | (): CollabTransport, platform: Pick<Platform, "warn" | "createId">): CollaborationChannelmethod applyExternalEvent(event: CollaborationExternalEvent): voidApplies one transport event while the owning editor dispatches its command.
method attachRemoteApplier(applier: CollaborationRemoteOperationApplier): (): voidAttaches the one currently mounted editor and replays queued remote effects in revision order.
method connect(options: CollaborationConnectOptions): Promise<void>method destroy(): voidmethod disconnect(): voidmethod enforceCommandBoundary(assertWrite: (): void, runWithoutMutationAuthority?: <Value>(callback: (): Value): Value, dispatchExternalEvent: (event: CollaborationExternalEvent): void): voidRestricts public channel mutations after its owning editor finishes assembly.
method getStatus(): CollaborationStatusmethod registerContributor(contribution: CollaborationContribution): voidInstalls one open OT owner contract for the lifetime of this channel.
method submitLocal(ownerId: string, operations: readonly OTOperation[]): voidQueues a committed local operation batch through the shared collaboration engine.
method subscribeStatus(listener: (status: CollaborationStatus): void): (): void - classCollaborationChannelError
-
class CollaborationChannelError extends SearErrorStable public failures raised by a collaboration channel host.
constructor CollaborationChannelError(code: CollaborationChannelErrorCode, message: string, details?: Record<string, unknown>): CollaborationChannelErrorproperty readonly code: CollaborationChannelErrorCodeStable machine-readable identifier for this error category.
Inherited members 9
Inherited from SearError.
- classCollabTransport
-
Abstract transport layer. Swap implementations (WebSocket, BroadcastChannel, polling, etc.) without touching the plugin logic.
constructor CollabTransport(): CollabTransportproperty readonly symbol: symbolstaticDI token for resolving CollabTransport.
method connect(options: CollaborationTransportConnectOptions): Promise<void>Opens the collaboration transport and begins receiving messages.
method disconnect(): voidCloses the collaboration transport and releases its listeners.
method send(message: CollaborationSubmission): voidSends one encoded collaboration message through the transport.
method subscribe(handler: (message: CollaborationServerMessage): void): (): voidSubscribes to server messages and returns an idempotent disposer.
- classHeadlessCollabTransport
-
class HeadlessCollabTransport extends CollabTransportCollaboration transport that keeps the plugin local to the current host.
constructor HeadlessCollabTransport(): HeadlessCollabTransportproperty readonly symbol: symbolstaticDI token for resolving HeadlessCollabTransport.
method connect(_options: CollaborationTransportConnectOptions): Promise<void>Opens the collaboration transport and begins receiving messages.
method disconnect(): voidCloses the collaboration transport and releases its listeners.
method send(_message: CollaborationSubmission): voidSends one encoded collaboration message through the transport.
method subscribe(_handler: (message: CollaborationServerMessage): void): (): voidSubscribes without producing network messages.
- classSheetCollaborationPlugin
-
class SheetCollaborationPlugin extends Plugin<SearCoreSheet, CellProperties, null>, SheetLifecycleController, CollaborationSessionThin Sheet bridge around the editor-independent collaboration engine.
constructor SheetCollaborationPlugin(channelBinding: CollaborationChannelBinding, plugins: PluginManager<SearCoreSheet, CellProperties>, commands: SheetCommandBus): SheetCollaborationPluginproperty readonly interestedIn: string[]Declares which Sheet OT action names this plugin is interested in. The engine will only call
applywhen 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
property readonly warnOnDuplicateDepth: falseWhether PluginManager should warn when another ordered plugin shares this depth.
property readonly symbol: typeof symbolstaticmethod apply(_state: null, _transaction: Transaction): nullApplies a transaction to plugin-owned state and returns the next state.
method connect(options: CollaborationConnectOptions): Promise<void>method destroy(): voidmethod disconnect(): voidmethod getPluginConfig(): nullReturns this plugin's runtime configuration view for the current core.
method getStatus(): CollaborationStatusmethod onTransactionCommitted(transaction: Transaction): voidRuns 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.
transactionA committed transaction from the completed pipeline.
method registerCommands(commands: SheetCommandBus): voidmethod registerObservations(observations: ObservationRegistry): voidmethod registerState(): { dataEngine: { enabled: boolean }; key: PluginKey; state: null }Registers one or more plugin-owned state records with the host manager.
method render(): nullProduces scene nodes owned by this plugin for the current core state.
method start(_context: SheetLifecycleContext): voidInherited members 27
Inherited from Plugin.
- depth
- documentState
- pluginKey
- transactionHistory
- transactionOT
- key
- dirtyRect
- enforceRuntimeWriteBoundary
- enforceStateWriteBoundary
- getState
- hasStateWriteBoundary
- lockCommittedState
- onClick
- onDblClick
- onInitialDataCell
- onInitialDataComplete
- onMouseDown
- onMouseMove
- onMouseUp
- onResize
- onScroll
- projectTransaction
- registerConfig
- sealRuntimeMetadata
- sealRuntimeMethods
- sealRuntimeWrites
- setState
- classWebSocketTransport
-
class WebSocketTransport extends CollabTransportBrowser WebSocket implementation of CollabTransport.
The authority validates and orders submitted operation batches while this adapter owns only WebSocket lifecycle and JSON framing.
constructor WebSocketTransport(): WebSocketTransportmethod connect(options: CollaborationTransportConnectOptions): Promise<void>Opens the collaboration transport and begins receiving messages.
method disconnect(): voidCloses the collaboration transport and releases its listeners.
method send(message: CollaborationSubmission): voidSends one encoded collaboration message through the transport.
method subscribe(handler: (message: CollaborationServerMessage): void): (): voidSubscribes to parsed server messages.
- interfaceCollaborationChannelBinding
-
interface CollaborationChannelBindingCollaborationChannelBinding: { symbol: symbol }DI value used to distinguish editor-owned channels from host-retained channels.
- interfaceCollaborationConnectOptions
- interfaceCollaborationSession
-
Host-facing lifecycle API independent from a concrete editor bridge.
- interfaceCollaborationStatus
-
property readonly error: unknownproperty readonly pendingCount: numberproperty readonly resourceId: string | nullproperty readonly revision: numberproperty readonly state: CollaborationConnectionState - interfaceCollaborationTransportConnectOptions
-
Connection parameters for one collaboration resource.
- interfaceConnectSheetCollaborationResult
-
interface ConnectSheetCollaborationResult extends SheetCommandResultCommand result that resolves when the collaboration transport is connected.
property readonly completion: Promise<void>Optional asynchronous completion of a command-owned external effect.
- typeCollaborationChannelErrorCode
-
type CollaborationChannelErrorCode = typeof CollaborationChannelErrorCode[keyof typeof CollaborationChannelErrorCode]CollaborationChannelErrorCode: { AttachmentConflict: "SEAR_COLLABORATION_ATTACHMENT_CONFLICT"; BoundaryInstalled: "SEAR_COLLABORATION_BOUNDARY_INSTALLED"; ContributorConflict: "SEAR_COLLABORATION_CONTRIBUTOR_CONFLICT"; Destroyed: "SEAR_COLLABORATION_CHANNEL_DESTROYED" } - typeCollaborationConnectionState
-
type CollaborationConnectionState = typeof CollaborationConnectionState[keyof typeof CollaborationConnectionState]CollaborationConnectionState: { Connecting: "connecting"; Disconnected: "disconnected"; Error: "error"; Online: "online" }Public lifecycle state of one collaboration session.
- variableCollaborationStatusObservation
-
CollaborationStatusObservation: StateObservationDefinition<CollaborationStatus>Editor-local collaboration connection and synchronization status.
- variableConnectSheetCollaborationCommand
-
ConnectSheetCollaborationCommand: SheetCommandDefinition<CollaborationConnectOptions, ConnectSheetCollaborationResult>Starts a Sheet collaboration session through the editor command bus.
- variableDisconnectSheetCollaborationCommand
-
DisconnectSheetCollaborationCommand: SheetCommandDefinition<void, SheetCommandResult>Disconnects a Sheet collaboration session through the editor command bus.
- variableCollaborationChannelErrorCodeType
-
CollaborationChannelErrorCodeType: { AttachmentConflict: "SEAR_COLLABORATION_ATTACHMENT_CONFLICT"; BoundaryInstalled: "SEAR_COLLABORATION_BOUNDARY_INSTALLED"; ContributorConflict: "SEAR_COLLABORATION_CONTRIBUTOR_CONFLICT"; Destroyed: "SEAR_COLLABORATION_CHANNEL_DESTROYED" } - variableCollaborationConnectionStateType
-
CollaborationConnectionStateType: { Connecting: "connecting"; Disconnected: "disconnected"; Error: "error"; Online: "online" }Public lifecycle state of one collaboration session.
Apply and exchange operations
Committed local operations are submitted to the channel; remote operations return through the apply commands and are rebased against pending work.
- interfaceCollaborationRemoteOperations
-
Remote operation batch delivered to the currently mounted editor bridge.
property readonly operations: readonly OTOperation[]property readonly ownerId: stringproperty readonly serverRevision: number - interfaceSheetApplyRemoteOperationsInput
-
Input for applying operations received from a collaboration transport.
property readonly operations: readonly Operation[]Remote operations after local OT transformation.
property readonly ownerId: stringStable collaboration owner id resolved through the local plugin registry.
- typeCollaborationExternalEvent
-
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
-
type CollaborationRemoteOperationApplier = (effect: CollaborationRemoteOperations): void - variableApplyRemoteOperationsCommand
-
ApplyRemoteOperationsCommand: SheetCommandDefinition<SheetApplyRemoteOperationsInput, SheetCommandResult>Command that applies remote collaboration operations through the normal pipeline.
- variableApplySheetCollaborationEventCommand
-
ApplySheetCollaborationEventCommand: SheetCommandDefinition<CollaborationExternalEvent, SheetCommandResult>Routes an external transport event into the owning Sheet command bus.
- interfaceCollaborationAcceptedBatch
-
Canonical operation batch accepted and ordered by the authority.
property readonly baseRevision: numberproperty readonly clientId: stringproperty readonly kind: "accepted"property readonly operationId: stringproperty readonly operationType: CollaborationOperationTypeproperty readonly ownerId: stringproperty readonly payload: OTEncodedValueproperty readonly protocolVersion: 1property readonly resourceId: stringproperty readonly serverRevision: number - typeCollaborationClientMessage
-
type CollaborationClientMessage = CollaborationSubmission - variableCollaborationProtocolVersion
-
CollaborationProtocolVersion: 1Current collaboration wire protocol version.
- interfaceCollaborationRejectedMessage
-
Explicit authority rejection; clients must not infer recovery from dropped frames.
property readonly code: stringproperty readonly kind: "rejected"property readonly message: stringproperty readonly operationId?: stringproperty readonly protocolVersion: 1property readonly resourceId: string - typeCollaborationServerMessage
-
type CollaborationServerMessage = CollaborationAcceptedBatch | CollaborationSyncMessage | CollaborationRejectedMessage - interfaceCollaborationSubmission
-
Client submission before the authority assigns a canonical revision.
property readonly baseRevision: numberproperty readonly clientId: stringproperty readonly kind: "submit"property readonly operationId: stringproperty readonly operationType: CollaborationOperationTypeproperty readonly ownerId: stringproperty readonly payload: OTEncodedValueproperty readonly protocolVersion: 1property readonly resourceId: string - interfaceCollaborationSyncMessage
-
Ordered catch-up response sent when a transport joins a resource.
property readonly batches: readonly CollaborationAcceptedBatch[]property readonly fromRevision: numberproperty readonly kind: "sync"property readonly protocolVersion: 1property readonly resourceId: stringproperty readonly serverRevision: number
No matching API entries.