← All packages

@searsuite/sear-render-engine

Render engines

DataEngine publishes typed field projections from state-owning features. SheetRenderEngine consumes the selected projections, tracks dirty regions, and schedules a frame. Render nodes and strategies turn those values into draw operations on a RenderContext; the host supplies the concrete drawing adapter.

A command changes owner state first. After commit, the relevant projection and dirty region determine what is repainted. Rendering a value does not make it durable document state: formula results, layout caches, and viewport data may be derived or local to one editor session.

A visual editor needs a render context, text shaping, input, and viewport adapters compatible with its host. RenderContextFactory helps the assembly obtain the chosen context; Canvas, SVG, and other concrete adapters stay outside the portable domain model. A headless editor can omit visual services.

Use when: building a visual host or contributing a rendering feature. Register the feature's data field or visual reader at its owner, then consume that projection in the render layer. Host event handlers should request edits through commands rather than changing render data directly.

classRenderEngine
class RenderEngine<NodeType, RenderCoordinatorManagerType>

Schedules frames and applies a render strategy to the current scene.

classRenderContextFactory

Factory registry for render-context implementations.

constructorRenderContextFactory(): RenderContextFactory
methodcreateContext(type: string | symbol, args: unknown): RenderContextstatic

Creates a render context for a registered type.

ReturnsNew render context instance.

type

Context type key.

args

Adapter-specific construction input.

methodregisterContext(type: string | symbol, contextCreator: (args: unknown): RenderContext): voidstatic

Registers a render-context creator.

type

Context type key.

contextCreator

Factory invoked by createContext().

classSheetRenderEngine
class SheetRenderEngine extends RenderEngine<CellProperties, SheetRenderCoordinatorManager>

Coordinates Sheet invalidation, frame scheduling, and screen-cache reuse.

Inherited members 6

Inherited from RenderEngine.

classDocRenderEngine
class DocRenderEngine extends RenderEngine<NodeProperties, RenderCoordinatorManager>

Document render engine that mirrors Sheet's fixed strategy chain.

Domain-specific layout and SceneGraph projection happen before this class. The render engine owns only SceneGraph painting, dirty marks, viewport resizing, and ordered strategy dispatch.

constructorDocRenderEngine(scrollManager: ScrollManager, renderContext: RenderContext, configEngine: ConfigEngine, renderCoordinatorManager: RenderCoordinatorManager, stage: SceneGraph<NodeProperties>, renderStrategyManager: RenderStrategyManager<NodeProperties>, screenRenderStrategy: ScreenRenderStrategy<NodeProperties>, dirtyRenderStrategy: DirtyRenderStrategy<NodeProperties>, stickyRenderStrategy: StickyRenderStrategy<NodeProperties>, overlayRenderStrategy: OverlayRenderStrategy<NodeProperties>): DocRenderEngine
propertyreadonly symbol: symbolstatic

DI token for resolving DocRenderEngine.

methodgetLastScreenRenderMode(): ScreenRenderFrameMode | null

Returns the screen strategy mode used by the last render pass, if it painted.

methodinitialize(): void

Initializes DocRenderEngine.

methodinvalidateScreenCache(): void

Invalidates the off-screen body cache used by the screen strategy.

methodmarkDirty(rect: PositionRect<templateLiteral>): void

Marks one document-world rectangle dirty for the next dirty pass.

methodrender(node: Node<NodeProperties>): void

Runs the configured document render strategies over the current scene graph.

methodresize(width: number, height: number, scale: number): void

Resizes all Doc render layers and invalidates screen-cache reuse.

methodsetBlockRasterCopyPlan(plan: BlockRasterCopyPlan | null): void

Supplies one layout-shift raster-copy plan for the next screen render pass.

methodsetViewport(viewport: DocRenderViewport): void

Updates the viewport model used by subsequent render frames.

methodsetViewScale(scale: number): void

Updates the view scale on every render strategy context.

Inherited members 5

Inherited from RenderEngine.

interfaceDocRenderViewport

Snapshot of the current document viewport used by render strategies.

propertyreadonly contentRect: PositionRectProps

Editable content rectangle inside the viewport.

propertyreadonly height: number

Visible viewport height in host-view units.

propertyreadonly width: number

Visible viewport width in host-view units.

Sheet data

classDataEngine

Base registry for plugin-owned data engines.

Concrete engines can register custom data types by plugin key while exposing their own initialization and read APIs.

constructorDataEngine(): DataEngine
propertyreadonly symbol: typeof symbolstatic

DI token for resolving the abstract data engine singleton.

methodenforceWriteBoundary(token: object): void

Restricts registered state and view changes to the owning runtime after setup.

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

Retrieves a plugin-owned data value.

ReturnsRegistered value, or void 0 when absent.

key

Plugin key to read.

methodgetDataTypeOptions(key: PluginKey): DataEngineRegistrationOptions<unknown> | undefined

Reads registration metadata for a plugin-owned data value.

ReturnsRegistration metadata, or void 0 when the key is not registered.

key

Plugin key to inspect.

methodgetDataViewFieldKeys(viewKey: string): string[]

Lists fields registered for one named data view.

ReturnsField names in registration order.

viewKey

Named data view to inspect.

methodgetRegisteredDataTypeKey(key: string): PluginKey | undefined

Resolves a transport-safe plugin-key string to the registered key object.

PluginKey construction intentionally creates a unique identity, so remote transports must resolve the received string back to this registry's existing key before creating a transaction for PluginManager.

ReturnsRegistered PluginKey, or void 0 when no state owner has that key.

key

Stable key string carried by a transport message.

methodhasDataType(key: PluginKey): boolean

Reports whether a plugin state has been registered with this engine.

ReturnsTrue when the key owns a DataEngine-visible state value.

key

Plugin key to inspect.

methodinitialize(): void

Initializes engine-owned registries or projections.

methodreadDataViewField<FieldType>(viewKey: string, fieldKey: string): FieldType | undefined

Reads one field from a named data view without materializing the whole view.

ReturnsField value, or void 0 when the field is unregistered or unavailable.

viewKey

Named data view containing the field.

fieldKey

Field to read.

methodregisterDataType<StateType>(key: PluginKey, value: StateType, options?: DataEngineRegistrationOptions<StateType>, token?: object): void

Registers a plugin-owned data value.

key

Plugin key owning the data.

value

Data value to store.

methodregisterDataViewField<StateType>(ownerKey: PluginKey, field: DataEngineViewFieldRegistration<StateType>, token?: object): void

Registers one field selector for a named data view.

ThrowsDataViewFieldDuplicateError when another owner already registered the same field in the same view.

ownerKey

Plugin key whose current state feeds the selector.

field

Named view field selector.

methodreplaceDataType(key: PluginKey, value: unknown, token?: object): void

Replaces a plugin-owned data value.

key

Plugin key owning the data.

value

New data value.

classDataViewFieldDuplicateError
class DataViewFieldDuplicateError extends SearError

Error thrown when two different state owners try to publish the same data view field.

constructorDataViewFieldDuplicateError(details: { existingOwnerKey: string; fieldKey: string; ownerKey: string; viewKey: string }): DataViewFieldDuplicateError

Creates a duplicate data view field error.

details

View key, field key, existing owner, and conflicting owner.

propertyreadonly code: "DATA_VIEW_FIELD_DUPLICATE"

Stable machine-readable code for duplicate data view field registrations.

Inherited members 9

Inherited from SearError.

classSheetDataEngine
class SheetDataEngine extends DataEngine

Data engine specialization for sheet matrix state.

constructorSheetDataEngine(): SheetDataEngine
methodinitialize(): void

Initializes sheet data projections.

Inherited members 11

Inherited from DataEngine.

classSheetDataPlugin
class SheetDataPlugin extends Plugin<unknown, CellProperties, SheetDataPluginState>

Plugin that owns the persisted sheet cell matrix.

It applies cell and sheet-structure transactions through MatrixOT and builds inverse OT payloads for inversion. Derived projections such as alignment and dimensions live in their own feature plugins.

constructorSheetDataPlugin(state: SheetDataPluginState, formatCodecs?: (): CellFormatTransferRegistry): SheetDataPlugin

Constructs the sheet data plugin.

state

Shared sheet data state.

propertyreadonly documentState: PluginDocumentStateContribution<SheetDataPluginState, SheetDataPluginState>

SheetDataPlugin owns the persisted sheet-data export module.

propertyinterestedIn: string[]

Sheet data reacts to cell changes and row/column structure edits from any command owner.

propertyreadonly transactionOT: { collaborative: boolean; definition: TransactionOTDefinition<MatrixOTOperation<unknown>>; ownerId: string; relations: OTTransformRelation<MatrixOTOperation<unknown>, MatrixOTOperation<unknown>>[] }

Sheet data transactions share the registered MatrixOT algebra.

propertyreadonly warnOnDuplicateDepth: false

Sheet data is state-only; duplicate render/event depth diagnostics do not apply.

propertyreadonly documentState: PluginDocumentStateContribution<SheetDataPluginState, SheetDataPluginState>static

Document-state export contribution for persisted sheet cells.

propertyreadonly pluginKey: PluginKeystatic

Stable plugin key shared by all sheet data plugin instances.

propertyreadonly symbol: symbolstatic

DI token for resolving the sheet data plugin.

methodapply(pluginState: SheetDataPluginState, transaction: Transaction): SheetDataPluginState | null

Applies sheet-data operations to the persisted cell matrix.

ReturnsUpdated plugin state, or null when the transaction has no relevant operations.

pluginState

Current sheet data state.

transaction

Transaction containing MatrixOT-compatible operations.

methodgetPluginConfig(): null

Sheet data has no render-time configuration.

methodregisterFormatTransfers(registry: SheetFormatTransferRegistry): void

Contributes this owner's cell state to atomic range moves.

methodregisterQueries(queries: SheetDataQueryRegistry): void

Publishes a live read-only projection for consumers that do not need an export snapshot.

methodregisterRangeMoves(registry: SheetRangeMoveRegistry): void
methodregisterRangeReorders(registry: SheetRangeReorderRegistry): void
methodregisterState(): { dataEngine: { dataView: { fieldKey: string; select: (state: unknown): SheetMatrix; viewKey: string }[] }; key: PluginKey; state: SheetDataPluginState }

Registers the sheet data matrix for commands, rendering, and collaboration.

methodrender(): Node<CellProperties>[]

Sheet data does not render scene nodes directly.

ReturnsAn empty node list.

Inherited members 25

Inherited from Plugin.

interfaceDataEngineRegistrationOptions
interface DataEngineRegistrationOptions<StateType>

Metadata associated with one DataEngine state registration.

propertyreadonly dataView?: readonly DataEngineViewFieldRegistration<StateType>[]

Field selectors contributed by the registered state to named data views.

interfaceDataEngineViewFieldRegistration
interface DataEngineViewFieldRegistration<StateType>

Field metadata associated with one DataEngine state registration.

propertyreadonly fieldKey: string

Field name written into the named view.

propertyreadonly required?: boolean

When false, missing owner state or void field values do not make the containing view unavailable.

propertyreadonly select: (state: StateType): unknown

Reads the field value from the current owner state.

propertyreadonly viewKey: string

Named read model that receives the selected field.

interfaceSheetDataPluginState

State owned by SheetDataPlugin.

propertysheetData: SheetMatrix

Main sheet matrix containing persisted cell values.

typeDataEngineViewFieldSelector
type DataEngineViewFieldSelector = { select: unknown }["select"]

Selector used to publish one registered state field into a named data view.

variableReadSheetCellDataQuery
ReadSheetCellDataQuery: ReadSheetCellDataQueryDefinition

Reads the mounted editor's live cell matrix without creating a document snapshot.

variableSheetDataFieldNamespace
SheetDataFieldNamespace: "SheetDataFields"

Shared DataEngine view containing Sheet feature projections.

variableSheetDataMatrixFieldKey
SheetDataMatrixFieldKey: "sheet.data"

DataEngine field owned by SheetDataPlugin.

functioncreateInvertibleProjectedOperations
createInvertibleProjectedOperations<T>(matrix: CSRMatrix<T>, operations: Operation[], createInvertible: (matrix: CSRMatrix<T>, operation: Operation): MatrixOTOperation<T> | null): MatrixOTOperation<T>[]

Builds invertible operations for a matrix projection by replaying through a cloned snapshot.

ReturnsOrdered MatrixOT operations with completed inverse payloads.

matrix

Projection matrix before the transaction.

operations

Source transaction operations.

createInvertible

Projection-specific operation builder.

functionreadDenseColumn
readDenseColumn<T>(matrix: CSRMatrix<T>, colIndex: number): T | null[]

Reads a dense column snapshot from a sparse matrix.

ReturnsDense column including null entries for empty cells.

matrix

Matrix to read.

colIndex

Column index to snapshot.

functionreadDenseRow
readDenseRow<T>(matrix: CSRMatrix<T>, rowIndex: number): T | null[]

Reads a dense row snapshot from a sparse matrix.

ReturnsDense row including null entries for empty cells.

matrix

Matrix to read.

rowIndex

Row index to snapshot.

functionreadSheetDataMatrix
readSheetDataMatrix(dataEngine: DataEngine): SheetMatrix | null

Reads the persisted cell matrix published by SheetDataPlugin.

functionregisterReadSheetCellDataQuery
registerReadSheetCellDataQuery(queries: SheetDataQueryRegistry, read: (): SheetMatrix): void

Registers the live, read-only cell-data projection owned by SheetDataPlugin.

interfaceCellMatrixElement

Persisted cell payload stored in the sheet matrix.

propertyformula?: string

Formula source text for formula cells; calculated results live in formula plugin state.

propertyformulaEvaluationMode?: "dynamic" | "legacy"

Array evaluation mode used when the formula was entered.

propertytype: string

Cell type identifier owned by the cell type catalog.

propertyvalue?: unknown

Raw value whose shape is owned by the cell type.

classSheetMatrix
class SheetMatrix extends CSRMatrix<CellMatrixElement>

SheetMatrix public API.

constructorSheetMatrix(data?: { data: CellMatrixElement[]; indices: number[]; indptr: number[] }, shape?: [number, number]): SheetMatrix

Constructs a CSRMatrix instance.

data

The data for the matrix.

shape

The shape of the matrix as [numRows, numCols].

methodclone(): this

Copies stored cell payloads as well as sparse indexes.

Inherited members 34

Inherited from CSRMatrix.

Row and column sizes

Size and visibility fields determine which Sheet cells occupy the visible viewport.

classVisibleRowDimensions
class VisibleRowDimensions extends DimensionsCSRMatrix

Dimension view shared by layout, hit testing, and rendering.

constructorVisibleRowDimensions(source: DimensionsCSRMatrix, visibility: SheetRowVisibility): VisibleRowDimensions
methodgetDefaultValue(): number | undefined

Returns the configured fallback used for absent sparse entries, if one exists.

methodgetDimensionsMap(): number[]

Computes and returns the cumulative dimension map.

The dimensions map stores the cumulative sum of all dimension values up to each column. For example, if dimensions are [10, 20, 30], the map is [10, 30, 60]. This allows O(1) lookups of boundaries without recalculating sums.

Result is cached until the matrix is modified. Cache is automatically invalidated when rows/columns are added, deleted, or modified.

ReturnsArray where element i contains the sum of dimensions 0..i Time Complexity: O(rows * cols) on first call or after modification, O(1) for cached result

Example
const matrix = new DimensionsCSRMatrix(...);
const map = matrix.getDimensionsMap(); // [10, 30, 60]
methodgetItem(row: number, column: number): number | null

Retrieves an item from the matrix at the specified row and column.

ReturnsThe item at the specified position or null if not present.

row

The row index.

Inherited members 37

Inherited from DimensionsCSRMatrix.

interfaceSheetRowVisibility

A Sheet presentation contribution that can suppress rows without changing their stored heights.

functionreadSheetRawRowSizes
readSheetRawRowSizes(dataEngine: DataEngine): DimensionsCSRMatrix | null

Reads the resize owner's stored row heights, without presentation visibility.

functionreadSheetColumnHiddenOriginalSizes
readSheetColumnHiddenOriginalSizes(dataEngine: DataEngine): CSRMatrix<number> | null

Reads original column sizes captured while columns are hidden.

functionreadSheetColumnSizes
readSheetColumnSizes(dataEngine: DataEngine): DimensionsCSRMatrix | null

Reads column dimensions published by SheetResizePlugin.

functionreadSheetRowHiddenOriginalSizes
readSheetRowHiddenOriginalSizes(dataEngine: DataEngine): CSRMatrix<number> | null

Reads original row sizes captured while rows are hidden.

functionreadSheetRowSizes
readSheetRowSizes(dataEngine: DataEngine): DimensionsCSRMatrix | null

Reads row dimensions published by SheetResizePlugin.

variableSheetColumnHiddenOriginalSizesFieldKey
SheetColumnHiddenOriginalSizesFieldKey: "sheet.resize.columnHiddenOriginalSizes"

DataEngine field for original dimensions of hidden columns owned by SheetResizePlugin.

variableSheetColumnSizesFieldKey
SheetColumnSizesFieldKey: "sheet.resize.columnSizes"

DataEngine field for column dimensions owned by SheetResizePlugin.

variableSheetRowHiddenOriginalSizesFieldKey
SheetRowHiddenOriginalSizesFieldKey: "sheet.resize.rowHiddenOriginalSizes"

DataEngine field for original dimensions of hidden rows owned by SheetResizePlugin.

variableSheetRowSizesFieldKey
SheetRowSizesFieldKey: "sheet.resize.rowSizes"

DataEngine field for row dimensions owned by SheetResizePlugin.

variableSheetRowVisibilityFieldKey
SheetRowVisibilityFieldKey: "sheet.filter.rowVisibility"

Neutral field contract re-exported by the plugin that owns the contribution.