SearSuite
← All packages

@searsuite/sear-assembly-plugin

Plugin lifecycle

Plugin and PluginSpec describe an optional feature. During assembly, a plugin can register services, state, commands, queries, observations, capabilities, and codecs. Registration establishes who owns a value and which operation may change it. A feature that owns Sheet fill, for example, keeps its fill matrix and commands in its own package while the assembly only connects it to an editor.

Use when: adding optional built-in or third-party behavior. Choose the lowest layer that owns the behavior: portable values in a domain package, feature state and commands in a plugin, platform conversion in a host adapter. A plugin should not reach into another feature's state or duplicate its finite values.

The composition root runs explicit lifecycle phases. A state contribution is available before commands and consumers that need it; successful commands publish committed changes to observers and renderers. Resources acquired during registration must be released in reverse order when setup fails or the editor is destroyed.

PluginManager coordinates registration. Runtime capabilities expose editor-owned services to the host without exposing its dependency-injection container. Session adapters capture transient values across a Workbook Sheet remount; document codecs and versioned OT contributions handle durable export and collaboration separately.

classEditorLifecycleError
class EditorLifecycleError extends SearError

Public error raised when lifecycle stack ownership is violated.

constructorEditorLifecycleError(code: EditorLifecycleErrorCode, message: string, details?: SearErrorDetails): EditorLifecycleError
propertyreadonly code: EditorLifecycleErrorCode

Stable machine-readable identifier for this error category.

Inherited members 9

Inherited from SearError.

classEditorLifecycleStack

Idempotent reverse-order disposer stack used by editor composition roots.

constructorEditorLifecycleStack(): EditorLifecycleStack
methodadd(disposer: (): void): void

Adds one owned resource disposer in acquisition order.

methoddispose(): void

Runs every disposer in reverse order and continues cleanup after individual failures.

classPlugin
class Plugin<SearCoreType, NodeTypeProperties, PluginStateType>

Base contract implemented by sheet and document plugins.

Plugins own their state, declare lifecycle hooks, transform transactions into state, and render scene nodes for their host core. Runtime packages should extend this contract rather than reaching into Core internals.

constructorPlugin<SearCoreType, NodeTypeProperties, PluginStateType>(__namedParameters: PluginSpec<PluginStateType>): Plugin<SearCoreType, NodeTypeProperties, PluginStateType>

Creates a plugin with its stable identity and initial state.

propertyreadonly depth: number

Draw and event ordering hint; lower values run earlier.

propertyreadonly documentState?: PluginDocumentStateContribution<PluginStateType, object> | readonly PluginDocumentStateContribution<PluginStateType, object>[]

Document-state export modules owned by this plugin state.

propertyinterestedIn: 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.

  • [&#39;uc&#39;, &#39;rr&#39;, &#39;rc&#39;] — only called for UpdateCell, ResizeRow, ResizeCol
  • [&#39;*&#39;] — called for any transaction (wildcard)
  • [] — only called for this plugin's own transactions
propertypluginKey: PluginKey

Stable plugin key used by PluginManager and SceneGraph ownership maps.

propertyreadonly transactionHistory?: PluginTransactionHistoryAdapter

Optional history behavior for transactions owned by this plugin.

propertyreadonly transactionOT?: PluginTransactionOTContribution<OTOperation>

Shared transaction algebra used by history and collaboration.

propertyreadonly warnOnDuplicateDepth: boolean

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

memberkey
key: unknown
methodapply(pluginState: PluginStateType, transaction: Transaction): PluginStateType | null

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

methoddirtyRect(searCore: SearCoreType, transaction: Transaction): PositionRect<unknown> | null | undefined

Optional. Return the pixel-space dirty rectangle that needs to be redrawn after this plugin processes transaction.

When implemented, SearCoreSheet.dispatch will call markDirty with the returned rect and skip a full-canvas re-render for this plugin. When omitted (or when null/undefined is returned), dispatch falls back to a full render pass.

methodenforceRuntimeWriteBoundary(assertWrite: (): void): void

Installs the editor's command check for plugin-owned runtime sessions.

methodenforceStateWriteBoundary(commitToken: object): void

Restricts state replacement to the owning editor's commit phase.

methodgetPluginConfig(searCore: SearCoreType): unknown

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

methodgetState(): PluginStateType

Returns the plugin-owned state currently registered with the manager.

methodhasStateWriteBoundary(): boolean

Reports whether the owning runtime has taken control of state replacement.

methodlockCommittedState(state: PluginStateType): void

Optionally locks a committed plugin-owned local state value against retained handles.

methodonClick(earCore: SearCoreType, event: EventWithOffsetAndTarget<NodeTypeProperties>): boolean | void

Plugin pointer event handlers.

Return value contract:

  • Return false to stop subsequent plugins from handling the same event.
  • Return true / undefined / void to continue dispatching.

This mechanism allows a plugin to explicitly suppress downstream handlers after it has consumed an event, replacing the old coupled approach where one plugin directly modified another plugin's state.

methodonDblClick(earCore: SearCoreType, event: EventWithOffsetAndTarget<NodeTypeProperties>): boolean | void

Handles a double-click pointer event.

methodonInitialDataCell(searCore: SearCoreType, cell: unknown, row: number, col: number): void

Receives one non-empty cell during SearCoreSheet's shared startup scan. The scan runs once after every plugin state has been registered, so plugins can build derived indexes without independently traversing the whole sheet.

methodonInitialDataComplete(searCore: SearCoreType): void

Called after the final cell of the shared startup scan is delivered.

methodonMouseDown(searCore: SearCoreType, event: EventWithOffsetAndTarget<NodeTypeProperties>): boolean | void

Handles the start of a pointer press sequence.

methodonMouseMove(searCore: SearCoreType, event: EventWithOffsetAndTarget<NodeTypeProperties>): boolean | void

Handles pointer movement over the host surface.

methodonMouseUp(searCore: SearCoreType, event: EventWithOffsetAndTarget<NodeTypeProperties>): boolean | void

Handles the end of a pointer press sequence.

methodonResize(): void

Optional hook invoked when the host viewport or sheet dimensions change.

methodonScroll(scrollManagerState: ScrollManagerState): void

Receives scroll state changes from the active scroll manager.

methodonTransactionCommitted(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

A committed transaction from the completed pipeline.

methodprojectTransaction(state: PluginStateType, transaction: Transaction): readonly Transaction<Operation>[]

Purely plans owner-targeted prerequisites before another owner's explicit transaction. Sheet runtimes stage these once, atomically with the original transaction, and retain them in the command pipeline for history and collaboration. Never mutate input state.

methodregisterConfig(): PluginConfigRegistration<Record<string, unknown>>[]

Registers default configuration values owned by this plugin.

methodregisterState(): PluginStateRegistration<PluginStateType> | PluginStateRegistration<unknown>[]

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

methodrender(searCore: SearCoreType, offset?: { x: number; y: number }): Node<NodeTypeProperties> | Node<NodeTypeProperties>[] | null

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

methodsealRuntimeMetadata(): void

Fixes transaction and export metadata after the editor takes ownership.

methodsealRuntimeMethods(): void

Pins transaction and render hooks after plugin startup.

methodsealRuntimeWrites(): void

Closes runtime-owned extension writes after every plugin has initialized and started.

methodsetState(state: PluginStateType, commitToken?: object): void

Replaces the plugin-owned state after an apply or runtime transition.

classPluginKey

Stable unique key assigned to one plugin instance.

Plugin managers use this key to store state, render nodes, and diagnostics without requiring plugin classes to be singleton values.

constructorPluginKey(key?: string): PluginKey

Constructs a key using the provided base name.

key

Human-readable plugin key prefix.

propertyreadonly key: string

Unique plugin key string.

classPluginManager
class PluginManager<SearCoreType, NodeTypeProperties>

Ordered registry that owns plugin instances for one core/editor runtime.

constructorPluginManager<SearCoreType, NodeTypeProperties>(platform?: Platform): PluginManager<SearCoreType, NodeTypeProperties>

Creates a PluginManager bound to the host diagnostics channel when available.

propertyreadonly symbol: symbolstatic

DI token for resolving the runtime plugin manager.

methodclearPlugins(token?: object): void

Removes all registered plugins during host teardown.

methodenforceWriteBoundary(token: object): void

Gives the owning runtime exclusive registry write access after assembly.

methodforEach(callbackfn: (plugin: Plugin<SearCoreType, NodeTypeProperties, any>): void): void

Visits plugins in depth order so event, apply and render flows stay deterministic.

methodgetAllPlugins(): Plugin<SearCoreType, NodeTypeProperties, any>[]

Returns all registered plugins in insertion order.

methodgetCollaborativeTransactionPlugin(ownerId: string): Plugin<SearCoreType, NodeTypeProperties, any> | undefined

Resolves a stable collaboration owner to its editor-local plugin instance.

methodgetCollaborativeTransactionPlugins(): readonly Plugin<SearCoreType, NodeTypeProperties, any>[]

Lists collaborative transaction owners registered in this runtime.

methodgetDocumentStateContributions(): readonly RegisteredPluginDocumentStateContribution[]

Lists document-state export contributions registered by plugin state owners.

methodgetPluginState<T>(key: PluginKey): T | undefined

Returns the state owned by a registered plugin key, if present.

methodgetTransactionHistoryAdapter(transaction: Transaction): PluginTransactionHistoryAdapter | undefined

Returns the history adapter contributed by a transaction's state owner.

methodgetTransactionOTContribution(transaction: Transaction): PluginTransactionOTContribution<OTOperation> | undefined

Returns the shared transaction OT contribution for one local transaction owner.

methodinvertTransaction(transaction: Transaction): Transaction<Operation> | null

Inverts a transaction through its owner's registered OT definition.

methodregisterPlugin<T>(plugin: Plugin<SearCoreType, NodeTypeProperties, T>, token?: object): void

Registers a plugin under its key and rejects duplicate ownership.

methodtransformTransaction(transaction: Transaction, other: Transaction): Transaction<Operation> | null

Rebases a retained transaction over another committed transaction through the shared registry.

methodunregisterPlugin(pluginOrKey: string | PluginKey | Plugin<SearCoreType, NodeTypeProperties, any>, token?: object): void

Unregisters a plugin and clears the manager-owned state reference.

interfacePluginSpec
interface PluginSpec<T>

Immutable identity and initial state used to construct a plugin instance.

propertykey: PluginKey

Stable key under which the plugin registers state, config and scene nodes.

propertystate: T

Initial state owned by the plugin.

typeEditorLifecycleErrorCode
type EditorLifecycleErrorCode = typeof EditorLifecycleErrorCode[keyof typeof EditorLifecycleErrorCode] EditorLifecycleErrorCode: { MultipleDisposalFailures: "SEAR_EDITOR_LIFECYCLE_MULTIPLE_DISPOSAL_FAILURES"; StackDisposed: "SEAR_EDITOR_LIFECYCLE_STACK_DISPOSED" }

Stable machine-readable errors raised by editor lifecycle stacks.

typePluginExtension
type PluginExtension = PluginCommandExtension<CommandBus> & conditional & conditional & conditional & conditional

Minimal host-extension contract shared by Sheet, Doc, and Workbook plugin types.

Host controls

classHeadlessToolbar
class HeadlessToolbar extends SearToolbar

Toolbar implementation for hosts without a UI surface.

constructorHeadlessToolbar(): HeadlessToolbar
propertyreadonly symbol: symbolstatic

DI token for resolving HeadlessToolbar.

methoddestroy(): void

Releases resources owned by SearToolbar.

methodmount(_target: unknown): void

Attaches this adapter to its host surface.

classSearFormulaBar

Platform-neutral lifecycle for a Sheet formula input surface.

constructorSearFormulaBar(): SearFormulaBar
propertyreadonly symbol: symbolstatic
methoddestroy(): void
methodmount(target: unknown): void
classSearToolbar

Platform-neutral toolbar lifecycle contract.

constructorSearToolbar(): SearToolbar
propertyreadonly symbol: symbolstatic

DI token for resolving SearToolbar.

methoddestroy(): void

Releases resources owned by SearToolbar.

methodmount(target: unknown): void

Attaches this adapter to its host surface.

Commands, queries, and observations

interfacePluginCommandExtension
interface PluginCommandExtension<CommandBus>

Plugin capability for registering typed commands against one host command bus.

methodregisterCommands(commands: CommandBus): void

Registers every stable command id owned by this plugin.

interfacePluginCommandRegistrar
interface PluginCommandRegistrar<CommandBus>

Required-method view used by host assemblies when invoking command registration.

methodregisterCommands(commands: CommandBus): void

Registers every stable command id owned by this plugin.

interfacePluginObservationExtension
interface PluginObservationExtension<ObservationRegistry>

Plugin capability for registering typed observations against one host observation registry.

methodregisterObservations(observations: ObservationRegistry): void

Registers every typed state and event observation source owned by this plugin.

interfacePluginObservationRegistrar
interface PluginObservationRegistrar<ObservationRegistry>

Required-method view used by host assemblies when invoking observation registration.

methodregisterObservations(observations: ObservationRegistry): void

Registers every typed state and event observation source owned by this plugin.

interfacePluginQueryRegistrar
interface PluginQueryRegistrar<QueryRegistry>
methodregisterQueries(queries: QueryRegistry): void
functionhasPluginCommandRegistrar
hasPluginCommandRegistrar<CommandBus>(plugin: unknown): plugin

Returns whether a plugin contributes command registration for the current host.

functionhasPluginObservationRegistrar
hasPluginObservationRegistrar<ObservationRegistry>(plugin: unknown): plugin

Returns whether a plugin contributes observation registration for the current host.

functionhasPluginQueryRegistrar
hasPluginQueryRegistrar<QueryRegistry>(plugin: unknown): plugin

Plugin state and transactions

interfacePluginConfigRegistration
interface PluginConfigRegistration<ConfigType>

Default configuration contributed by one plugin during editor setup.

propertyreadonly config: ConfigType

Plain configuration values consumed and wrapped by ConfigEngine.

propertyreadonly key: PluginKey

Plugin key that owns this configuration unit.

interfacePluginDataEngineRegistrationOptions
interface PluginDataEngineRegistrationOptions<PluginStateType>

Controls whether a plugin state registration is exposed through DataEngine and data views.

propertyreadonly dataView?: readonly PluginDataViewFieldRegistration<PluginStateType>[]

Field selectors contributed by this state to named read-only data views.

propertyreadonly enabled?: boolean

When false, Core keeps the plugin private to PluginManager and skips DataEngine registration.

interfacePluginDataViewFieldRegistration
interface PluginDataViewFieldRegistration<PluginStateType>

Describes one plugin-owned field exposed to a named DataEngine read-only view.

propertyreadonly fieldKey: string

Field name written into the named view. Duplicate names in one view are rejected by DataEngine.

propertyreadonly required?: boolean

When false, a missing state or void field does not make the containing view unavailable.

propertyreadonly select: (state: PluginStateType): unknown

Reads the field value from the current plugin-owned state whenever the view is requested.

propertyreadonly viewKey: string

Named data view that receives this field, such as a sheet-level read model.

interfacePluginDocumentStateCodec
interface PluginDocumentStateCodec<TDocumentState>

JSON-export codec shape supplied by a plugin-owned document-state module.

propertyreadonly key: string
methoddeserialize(payload: unknown, path: string): Partial<TDocumentState>
methodserialize(state: TDocumentState): unknown
interfacePluginDocumentStateContribution
interface PluginDocumentStateContribution<TOwnerState, TDocumentState>

Document-state export contribution owned by one plugin state owner.

propertyreadonly codec: PluginDocumentStateCodec<TDocumentState>
propertyreadonly key: string
methodcapture(ownerState: TOwnerState): Partial<TDocumentState> | undefined
interfacePluginStateRegistration
interface PluginStateRegistration<PluginStateType>

State registration returned by plugins during editor initialization.

propertyreadonly dataEngine?: PluginDataEngineRegistrationOptions<PluginStateType>

DataEngine exposure metadata for this state registration.

propertyreadonly key: PluginKey

Plugin key that owns the registered state.

propertyreadonly state: PluginStateType

State value to register for that plugin key.

interfacePluginTransactionHistoryAdapter

Converts one plugin-owned transaction into history operations and rebases retained history over transactions that committed later.

methodinvert(transaction: Transaction): Transaction<Operation> | null

Creates the transaction that reverses the supplied committed transaction.

methodtransform(transaction: Transaction, other: Transaction): Transaction<Operation> | null

Rebases a retained transaction over a transaction that committed later.

interfacePluginTransactionHistoryOperations

Operation-level functions used to build one plugin-owned history adapter.

methodinvert(operations: Operation[]): Operation[]

Reverses an operation list in rollback order.

methodtransform(operations: Operation[], other: Operation[]): Operation[]

Rebases an operation list over operations that committed later.

interfacePluginTransactionOTContribution
interface PluginTransactionOTContribution<OperationType>

Transaction algebra and collaboration metadata contributed by one state owner.

propertyreadonly collaborative?: boolean

Whether committed transactions owned by this plugin may cross a collaboration transport.

propertyreadonly definition: TransactionOTDefinition<OperationType>

Versioned operation family used by history and collaboration.

propertyreadonly ownerId: string

Stable wire identity independent from process-local PluginKey suffixes.

propertyreadonly relations?: readonly OTTransformRelation<OTOperation, OTOperation>[]

Explicit relations needed by third-party operation families.

interfaceRegisteredPluginDocumentStateContribution

Document-state export contribution bound to the plugin instance that owns the source state.

propertyreadonly contribution: PluginDocumentStateContribution<unknown>
propertyreadonly plugin: Plugin<unknown, NodeProperties, unknown>
typePluginDataViewFieldSelector
type PluginDataViewFieldSelector = { select: unknown }["select"]

Controls whether a plugin state registration is exposed through DataEngine and collaboration.

functionassertSheetContributionWrite
assertSheetContributionWrite(owner: object): void

Checks registration changes without adding work to query or planning paths.

functioncreatePluginTransactionHistoryAdapter
createPluginTransactionHistoryAdapter(operations: PluginTransactionHistoryOperations): PluginTransactionHistoryAdapter

Creates a transaction history adapter while preserving owner identity and metadata.

functionsealSheetContributionWrites
sealSheetContributionWrites(owner: object, assertWrite: (): void): void

Seals setup-time Sheet contribution registries after editor startup.

Capabilities and session state

Capabilities expose editor-local services to plugins. Session state captures local UI state for restore without making it document content.

classRuntimeCapabilityError
class RuntimeCapabilityError extends SearError

Public error raised when a runtime capability contract is violated.

constructorRuntimeCapabilityError(code: RuntimeCapabilityErrorCode, message: string, details?: SearErrorDetails): RuntimeCapabilityError
propertyreadonly code: RuntimeCapabilityErrorCode

Stable machine-readable identifier for this error category.

Inherited members 9

Inherited from SearError.

classRuntimeCapabilityRegistry
class RuntimeCapabilityRegistry extends RuntimeCapabilityReader

Editor-local registry shared by Sheet, Doc and Workbook assemblies.

constructorRuntimeCapabilityRegistry(owner?: string): RuntimeCapabilityRegistry
methoddestroy(): void

Permanently closes the registry and releases all published values.

methodenforceWriteBoundary(assertWrite: (): void): void

Requires editor command dispatch for capability changes after assembly.

methodget<T>(capability: RuntimeCapability<T>): T | undefined
methodgetRegisteredCapabilityIds(): readonly string[]
methodhas(capability: RuntimeCapability<unknown>): boolean
methodregister<T>(capability: RuntimeCapability<T>, value: T): (): void

Registers one value and returns an idempotent disposer for that registration.

methodrequire<T>(capability: RuntimeCapability<T>): T
classSessionStateError
class SessionStateError extends SearError

Error raised when a session-state contributor violates its registry contract.

constructorSessionStateError(code: SessionStateErrorCode, message: string, details?: SearErrorDetails): SessionStateError

Creates a session-state contract error.

propertyreadonly code: SessionStateErrorCode

Stable machine-readable error code.

Inherited members 9

Inherited from SearError.

classSessionStateRegistry

Editor-local coordinator for all built-in and plugin-contributed session state.

constructorSessionStateRegistry(): SessionStateRegistry
propertyreadonly symbol: typeof symbolstatic

DI token for resolving the editor-local registry.

methodassertRestorationOpen(): void

Rejects a retained contributor restore callback after editor initialization.

methodcapture(): SessionStateSnapshot

Captures every registered contributor while preserving state whose owner is not loaded.

methodclear(lifecycleToken?: object): void

Clears contributors and retained state owned by this registry instance.

methodgetCompletedRestorePhases(): readonly SessionStateRestorePhase[]

Returns restore phases already completed by this editor lifecycle.

methodgetRegisteredStateIds(): readonly string[]

Returns sorted ids for currently registered contributors.

methodloadSnapshot(snapshot: SessionStateSnapshot): void

Loads a complete snapshot before lifecycle restoration begins.

methodregister<State>(definition: SessionStateDefinition<State>, adapter: SessionStateAdapter<State>): (): void

Registers one state owner and returns an idempotent disposer.

methodrestorePhase(phase: SessionStateRestorePhase): void

Restores every registered contributor assigned to one ordered lifecycle phase.

methodsealRestoration(lifecycleToken: object): void

Closes initialization-only restore operations for an assembled editor.

interfacePluginRuntimeCapabilityExtension
interface PluginRuntimeCapabilityExtension<RuntimeCapabilityRegistry>

Plugin capability for publishing typed editor-owned services to plugins and hosts.

methodregisterCapabilities(registry: RuntimeCapabilityRegistry): void

Registers every runtime capability owned by this plugin.

interfacePluginRuntimeCapabilityRegistrar
interface PluginRuntimeCapabilityRegistrar<RuntimeCapabilityRegistry>

Required-method view used by host assemblies when invoking capability registration.

methodregisterCapabilities(registry: RuntimeCapabilityRegistry): void
interfacePluginSessionStateExtension
interface PluginSessionStateExtension<SessionStateRegistry>

Plugin capability for registering editor-local session capture and restore behavior.

methodregisterSessionState(registry: SessionStateRegistry): void

Registers every local session value owned by this plugin.

interfacePluginSessionStateRegistrar
interface PluginSessionStateRegistrar<SessionStateRegistry>

Required-method view used by host assemblies when invoking session-state registration.

methodregisterSessionState(registry: SessionStateRegistry): void

Registers every local session value owned by this plugin.

interfaceRuntimeCapability
interface RuntimeCapability<T>

Typed token used to publish an editor-owned runtime service to plugins and hosts.

propertyreadonly id: string
propertyreadonly symbol: symbol
propertyreadonly type?: T

Phantom member preserving the capability value type.

interfaceSessionStateAdapter
interface SessionStateAdapter<State>

Captures and restores one detached local session value.

propertyreadonly restoreAfter?: readonly SessionStateDefinition<unknown>[]

Contributors in the same phase that must restore before this one when they are registered.

propertyreadonly restorePhase: SessionStateRestorePhase

Lifecycle phase in which restore() may safely update the owning feature.

methodcapture(): State | undefined

Returns plain data or a supported built-in value; custom class instances are not session snapshots.

methodrestore(state: State): void

Restores local state during the declared lifecycle phase.

interfaceSessionStateDefinition
interface SessionStateDefinition<State>

Typed identity owned and exported by one local-state contributor.

propertyreadonly id: string

Stable, globally unique id used in the in-memory session snapshot.

propertyreadonly stateType?: State

Compile-time state carrier; never populated at runtime.

typeRuntimeCapabilityErrorCode
type RuntimeCapabilityErrorCode = typeof RuntimeCapabilityErrorCode[keyof typeof RuntimeCapabilityErrorCode] RuntimeCapabilityErrorCode: { InvalidDefinition: "SEAR_RUNTIME_CAPABILITY_INVALID_DEFINITION"; NotRegistered: "SEAR_RUNTIME_CAPABILITY_NOT_REGISTERED"; RegistrationConflict: "SEAR_RUNTIME_CAPABILITY_REGISTRATION_CONFLICT"; RegistryDestroyed: "SEAR_RUNTIME_CAPABILITY_REGISTRY_DESTROYED" }

Supported runtime capability error codes.

typeSessionStateErrorCode
type SessionStateErrorCode = typeof SessionStateErrorCode[keyof typeof SessionStateErrorCode] SessionStateErrorCode: { invalidDefinition: "SEAR_SESSION_STATE_INVALID_DEFINITION"; invalidRestoreDependency: "SEAR_SESSION_STATE_INVALID_RESTORE_DEPENDENCY"; invalidRestoreOrder: "SEAR_SESSION_STATE_INVALID_RESTORE_ORDER"; invalidRestorePhase: "SEAR_SESSION_STATE_INVALID_RESTORE_PHASE"; registrationConflict: "SEAR_SESSION_STATE_REGISTRATION_CONFLICT"; restoreDependencyCycle: "SEAR_SESSION_STATE_RESTORE_DEPENDENCY_CYCLE"; restoreInProgress: "SEAR_SESSION_STATE_RESTORE_IN_PROGRESS"; restorePhaseClosed: "SEAR_SESSION_STATE_RESTORE_PHASE_CLOSED"; … }

Supported session-state error codes.

typeSessionStateRestorePhase
type SessionStateRestorePhase = typeof SessionStateRestorePhase[keyof typeof SessionStateRestorePhase] SessionStateRestorePhase: { AfterInitialize: "afterInitialize"; BeforeInitialize: "beforeInitialize" }

A supported local-state restoration phase.

typeSessionStateSnapshot
type SessionStateSnapshot = Readonly<Record<string, unknown>>

Opaque in-memory snapshot keyed by contributor-owned definition ids.

functioncloneSessionStateValue
cloneSessionStateValue<T>(value: T): T

Copies a session snapshot without trusting extension-provided clone hooks.

functioncreateRuntimeCapabilityReader
createRuntimeCapabilityReader(registry: RuntimeCapabilityRegistry, hidden?: readonly RuntimeCapability<unknown>[]): RuntimeCapabilityReader

Exposes selected capabilities without handing hosts the mutable registry itself.

functiondefineRuntimeCapability
defineRuntimeCapability<T>(id: string): RuntimeCapability<T>

Creates an immutable runtime capability definition with a stable process-wide identity.

functiondefineSessionState
defineSessionState<State>(id: string): SessionStateDefinition<State>

Creates an immutable typed identity for one local session value.

functionhasPluginRuntimeCapabilityRegistrar
hasPluginRuntimeCapabilityRegistrar<RuntimeCapabilityRegistry>(plugin: unknown): plugin

Returns whether a plugin publishes runtime capabilities for the current editor.

functionhasPluginSessionStateRegistrar
hasPluginSessionStateRegistrar<SessionStateRegistry>(plugin: unknown): plugin

Returns whether a plugin contributes local session-state registration for the current host.

functionreadSessionState
readSessionState<State>(snapshot: SessionStateSnapshot, definition: SessionStateDefinition<State>): State | undefined

Reads one contributor value from an opaque snapshot through its typed definition.

Move and reorder ranges

Feature contributions supply the analysis and operation needed to move state with a Sheet range.

classSheetRangeMoveRegistry

Editor-local range-move planning extension point shared by state owners.

constructorSheetRangeMoveRegistry(): SheetRangeMoveRegistry
propertyreadonly symbol: typeof symbolstatic
methodanalyze(context: SheetRangeMoveContext): SheetRangeMoveAnalysis

Assesses all owner constraints without planning or publishing any mutation.

methoddestroy(): void

Releases all editor-owned registrations.

methodhasConflict(context: SheetRangeMoveContext): boolean

Validates all owners before testing destination conflicts.

methodplan(context: SheetRangeMoveContext): readonly SheetRangeMovePlan[]

Plans all owners against the same pre-move state.

methodregister(contribution: SheetRangeMoveContribution): (): void

Registers one owner and returns an idempotent disposer.

classSheetRangeMoveRejectedError
class SheetRangeMoveRejectedError extends SearError

A rejected assessment retains the state owner's stable diagnostic code.

constructorSheetRangeMoveRejectedError(analysis: { context: SheetRangeMoveContext; issue: { code: string; details: SearErrorDetails; message: string; ownerId: string }; status: "blocked" }): SheetRangeMoveRejectedError

Creates the command failure from the same assessment consumed by preview.

propertyreadonly code: string

Stable machine-readable identifier for this error category.

Inherited members 9

Inherited from SearError.

classSheetStructureMoveRegistry

Editor-local preflight and operation planning for complete-axis moves.

constructorSheetStructureMoveRegistry(): SheetStructureMoveRegistry
propertyreadonly symbol: typeof symbolstatic
methoddestroy(): void

Releases editor-owned contributions.

methodplan(context: SheetStructureMoveContext): readonly Operation[]

Validates the original intent before compiling dependent operation updates.

methodregister(contribution: SheetStructureMoveContribution): (): void

Registers one contribution with order-independent, idempotent disposal.

interfaceSheetMoveRange

Zero-based inclusive bounds of a cell range.

propertyreadonly end: readonly [number, number]
propertyreadonly start: readonly [number, number]
interfaceSheetRangeMoveContext

Normalized source and destination of a same-sheet cell move.

propertyreadonly destination: SheetMoveRange
propertyreadonly source: SheetMoveRange
interfaceSheetRangeMoveContribution

A state owner's participation in range moves, independent of storage representation.

propertyreadonly id: string

Unique registration identity, conventionally &lt;owner&gt;.rangeMove; not a document field or operation target.

methodhasConflict(context: SheetRangeMoveContext): boolean

Reports whether destination data outside the source would be replaced.

methodplan(context: SheetRangeMoveContext): readonly SheetRangeMovePlan[]

Reads current state and produces an isolated operation plan.

methodtransformPlans(context: SheetRangeMoveContext, plans: readonly SheetRangeMovePlan[]): readonly SheetRangeMovePlan[]

Rewrites plans after every state owner has contributed, for derived references.

methodvalidate(context: SheetRangeMoveContext): void

Reads owner-specific invariants without mutation; rejected constraints throw a SearError.

interfaceSheetRangeMovePlan

Operations produced by one state owner without mutating its live state.

propertyreadonly operations: readonly Operation[]
propertyreadonly target: PluginKey
interfaceSheetRangeReorderContext

One stable row permutation within an inclusive cell range.

propertyreadonly destinationOf: (row: number): number

Maps a source row to its final row; columns never change.

propertyreadonly range: SheetMoveRange
interfaceSheetRangeRuleEntry
interface SheetRangeRuleEntry<Rule>

A feature-owned rule and the rectangle it covers.

propertyreadonly range: SheetMoveRange
propertyreadonly rule: Rule
interfaceSheetRangeRuleFragment
interface SheetRangeRuleFragment<Rule>

One retained or relocated piece of an original rule.

propertyreadonly original: SheetRangeRuleEntry<Rule>
propertyreadonly placement: "retained" | "moved"
propertyreadonly range: SheetMoveRange
interfaceSheetStructureMoveContext

One original-state structure permutation owned by a matrix plugin.

propertyreadonly operations: readonly Operation[]
propertyreadonly target: PluginKey
interfaceSheetStructureMoveContribution

Owner-local validation and dependent edits compiled before a structure move is staged.

propertyreadonly id: string
methodtransformOperations(context: SheetStructureMoveContext): readonly Operation[]
methodvalidate(context: SheetStructureMoveContext): void
typeSheetRangeMoveAnalysis
type SheetRangeMoveAnalysis = { context: SheetRangeMoveContext; status: typeof SheetRangeMoveStatus.Allowed | typeof SheetRangeMoveStatus.RequiresConfirmation } | { context: SheetRangeMoveContext; issue: { code: string; details: SearErrorDetails; message: string; ownerId: string }; status: typeof SheetRangeMoveStatus.Blocked }

A move assessment contains no operations and never mutates document state.

variableSheetRangeMoveStatus
SheetRangeMoveStatus: { Allowed: "allowed"; Blocked: "blocked"; RequiresConfirmation: "requiresConfirmation" }

Canonical outcomes shared by move preview and execution.

functioncreateSheetRangeRuleMoveContribution
createSheetRangeRuleMoveContribution<Rule>(adapter: SheetRangeRuleMoveAdapter<Rule>): SheetRangeMoveContribution

Creates a range-move contribution for rules that can be split at cell boundaries.

functionintersectSheetMoveRanges
intersectSheetMoveRanges(left: SheetMoveRange, right: SheetMoveRange): SheetMoveRange | null

Returns the shared inclusive area of two ranges, if any.

functionisPointInSheetMoveRange
isPointInSheetMoveRange(range: SheetMoveRange, row: number, column: number): boolean

Tests inclusive range membership.

functionsubtractSheetMoveRange
subtractSheetMoveRange(original: SheetMoveRange, cut: SheetMoveRange): SheetMoveRange[]

Removes one inclusive rectangle, retaining at most four disjoint pieces.

functiontranslateSheetMoveRange
translateSheetMoveRange(range: SheetMoveRange, source: SheetMoveRange, destination: SheetMoveRange): SheetMoveRange

Translates a rule fragment by the source-to-destination displacement.

Transfer formats

Format transfer contributions copy feature-owned formatting alongside cell values.

interfaceSheetFormatTransferContribution

Optional state-owner contribution to format painting.

propertyreadonly id: string
methodcapture(source: SheetMoveRange): SheetFormatTransferSnapshot
methodclear(range: SheetMoveRange): readonly SheetFormatTransferPlan[]

Plans removal of this owner's explicit formats without changing cell content.

methodplanCaptured(portable: unknown, destination: SheetMoveRange): readonly SheetFormatTransferPlan[]

Plans a captured source pattern using this owner's current target state.

interfaceSheetFormatTransferPlan

One owner's isolated plan; only the owner interprets its operations.

propertyreadonly operations: readonly Operation[]
propertyreadonly target: PluginKey
interfaceSheetFormatTransferRegistrar

Optional plugin lifecycle extension for format-transfer registration.

methodregisterFormatTransfers(registry: SheetFormatTransferRegistry): void
interfaceSheetFormatTransferSnapshot

Captured format data, independent of subsequent source changes.

propertyreadonly portable?: unknown

Captured owner data that can be planned against another Sheet instance.

methodplan(destination: SheetMoveRange, targetRegistry?: SheetFormatTransferRegistry): readonly SheetFormatTransferPlan[]
interfaceSheetPortableFormatTransfer

Serializable owner snapshot for a transient clipboard payload.

propertyreadonly id: string
propertyreadonly portable: unknown
typeSheetFormatRange
type SheetFormatRange = SheetMoveRange

Inclusive range shared by format-transfer owners and hosts.

functioncreateMatrixFormatTransfer
createMatrixFormatTransfer<Value>(id: string, target: PluginKey, readMatrix: (): SheetFormatMatrix<Value>): Required<SheetFormatTransferContribution>

Captures sparse persisted formats and tiles them over an inclusive target.