@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.
constructor RenderEngine<NodeType, RenderCoordinatorManagerType>(scrollManager: ScrollManager, renderContext: RenderContext, configEngine: ConfigEngine, renderCoordinatorManager: RenderCoordinatorManagerType, renderStrategyManager: RenderStrategyManager<NodeType>): RenderEngine<NodeType, RenderCoordinatorManagerType>property readonly configEngine: ConfigEngineproperty readonly renderContext: RenderContextproperty readonly renderCoordinatorManager: RenderCoordinatorManagerTypeproperty readonly renderStrategyManager: RenderStrategyManager<NodeType>property readonly scrollManager: ScrollManagerproperty readonly symbol: symbolstaticDI token for resolving RenderEngine.
method initialize(): voidInitializes RenderEngine.
method invalidateScreenCache(): voidDiscard pixel-cache reuse before the next render.
method markDirty(rect: PositionRect<templateLiteral>): voidMarks a region or the current scene for rendering on the next frame.
method render(node: Node<NodeType>): voidRenders RenderEngine scene output.
method resize(width: number, height: number, scale: number): voidResizes the render target and invalidates dependent frame state.
method setViewScale(scale: number): voidUpdates the view scale.
- classRenderContextFactory
-
Factory registry for render-context implementations.
constructor RenderContextFactory(): RenderContextFactorymethod createContext(type: string | symbol, args: unknown): RenderContextstaticCreates a render context for a registered type.
ReturnsNew render context instance.
typeContext type key.
argsAdapter-specific construction input.
method registerContext(type: string | symbol, contextCreator: (args: unknown): RenderContext): voidstaticRegisters a render-context creator.
typeContext type key.
contextCreatorFactory invoked by createContext().
- classSheetRenderEngine
-
class SheetRenderEngine extends RenderEngine<CellProperties, SheetRenderCoordinatorManager>Coordinates Sheet invalidation, frame scheduling, and screen-cache reuse.
constructor SheetRenderEngine(scrollManager: ScrollManager, renderContext: RenderContext, offScreenRenderContext: RenderContext, hitRenderContext: RenderContext, configEngine: ConfigEngine, renderCoordinatorManager: SheetRenderCoordinatorManager, renderStrategyManager: RenderStrategyManager<CellProperties>, screenRenderStrategy: ScreenRenderStrategy<CellProperties>, dirtyRenderStrategy: DirtyRenderStrategy<CellProperties>, stickyRenderStrategy: StickyRenderStrategy<CellProperties>, overlayRenderStrategy: OverlayRenderStrategy<CellProperties>): SheetRenderEnginemethod apply(operations: MatrixOTOperation<number>[]): voidApplies a transaction to SheetRenderEngine state.
method getLayer(): voidReturns the layer.
method getStage(): voidReturns the stage.
method initialize(): voidInitializes SheetRenderEngine.
method invalidateScreenCache(): voidDrops retained screen content so the next frame repaints it.
method markDirty(rect: PositionRect<templateLiteral>): voidMarks a region or the current scene for rendering on the next frame.
method onClick(): voidHandles the click lifecycle event.
method onScroll(scrollManagerState: ScrollManagerState): voidHandles the scroll lifecycle event.
method render(node: Node<CellProperties>): voidRenders SheetRenderEngine scene output.
method resize(width: number, height: number, scale: number): voidResizes every canvas layer and invalidates scroll optimization buffers.
method setViewScale(scale: number): voidUpdates the view scale.
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.
constructor DocRenderEngine(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>): DocRenderEngineproperty readonly symbol: symbolstaticDI token for resolving DocRenderEngine.
method getLastScreenRenderMode(): ScreenRenderFrameMode | nullReturns the screen strategy mode used by the last render pass, if it painted.
method initialize(): voidInitializes DocRenderEngine.
method invalidateScreenCache(): voidInvalidates the off-screen body cache used by the screen strategy.
method markDirty(rect: PositionRect<templateLiteral>): voidMarks one document-world rectangle dirty for the next dirty pass.
method render(node: Node<NodeProperties>): voidRuns the configured document render strategies over the current scene graph.
method resize(width: number, height: number, scale: number): voidResizes all Doc render layers and invalidates screen-cache reuse.
method setBlockRasterCopyPlan(plan: BlockRasterCopyPlan | null): voidSupplies one layout-shift raster-copy plan for the next screen render pass.
method setViewport(viewport: DocRenderViewport): voidUpdates the viewport model used by subsequent render frames.
method setViewScale(scale: number): voidUpdates 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.
property readonly contentRect: PositionRectPropsEditable content rectangle inside the viewport.
property readonly height: numberVisible viewport height in host-view units.
property readonly width: numberVisible 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.
constructor DataEngine(): DataEngineproperty readonly symbol: typeof symbolstaticDI token for resolving the abstract data engine singleton.
method enforceWriteBoundary(token: object): voidRestricts registered state and view changes to the owning runtime after setup.
method getDataType<T>(key: PluginKey): T | undefinedRetrieves a plugin-owned data value.
ReturnsRegistered value, or void 0 when absent.
keyPlugin key to read.
method getDataTypeOptions(key: PluginKey): DataEngineRegistrationOptions<unknown> | undefinedReads registration metadata for a plugin-owned data value.
ReturnsRegistration metadata, or void 0 when the key is not registered.
keyPlugin key to inspect.
method getDataViewFieldKeys(viewKey: string): string[]Lists fields registered for one named data view.
ReturnsField names in registration order.
viewKeyNamed data view to inspect.
method getRegisteredDataTypeKey(key: string): PluginKey | undefinedResolves 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.
keyStable key string carried by a transport message.
method hasDataType(key: PluginKey): booleanReports whether a plugin state has been registered with this engine.
ReturnsTrue when the key owns a DataEngine-visible state value.
keyPlugin key to inspect.
method initialize(): voidInitializes engine-owned registries or projections.
method readDataViewField<FieldType>(viewKey: string, fieldKey: string): FieldType | undefinedReads one field from a named data view without materializing the whole view.
ReturnsField value, or void 0 when the field is unregistered or unavailable.
viewKeyNamed data view containing the field.
fieldKeyField to read.
method registerDataType<StateType>(key: PluginKey, value: StateType, options?: DataEngineRegistrationOptions<StateType>, token?: object): voidRegisters a plugin-owned data value.
keyPlugin key owning the data.
valueData value to store.
method registerDataViewField<StateType>(ownerKey: PluginKey, field: DataEngineViewFieldRegistration<StateType>, token?: object): voidRegisters one field selector for a named data view.
ThrowsDataViewFieldDuplicateError when another owner already registered the same field in the same view.
ownerKeyPlugin key whose current state feeds the selector.
fieldNamed view field selector.
method replaceDataType(key: PluginKey, value: unknown, token?: object): voidReplaces a plugin-owned data value.
keyPlugin key owning the data.
valueNew data value.
- classDataViewFieldDuplicateError
-
class DataViewFieldDuplicateError extends SearErrorError thrown when two different state owners try to publish the same data view field.
constructor DataViewFieldDuplicateError(details: { existingOwnerKey: string; fieldKey: string; ownerKey: string; viewKey: string }): DataViewFieldDuplicateErrorCreates a duplicate data view field error.
detailsView key, field key, existing owner, and conflicting owner.
property readonly 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 DataEngineData engine specialization for sheet matrix state.
constructor SheetDataEngine(): SheetDataEnginemethod initialize(): voidInitializes 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.
constructor SheetDataPlugin(state: SheetDataPluginState, formatCodecs?: (): CellFormatTransferRegistry): SheetDataPluginConstructs the sheet data plugin.
stateShared sheet data state.
property readonly documentState: PluginDocumentStateContribution<SheetDataPluginState, SheetDataPluginState>SheetDataPlugin owns the persisted sheet-data export module.
property interestedIn: string[]Sheet data reacts to cell changes and row/column structure edits from any command owner.
property readonly transactionOT: { collaborative: boolean; definition: TransactionOTDefinition<MatrixOTOperation<unknown>>; ownerId: string; relations: OTTransformRelation<MatrixOTOperation<unknown>, MatrixOTOperation<unknown>>[] }Sheet data transactions share the registered MatrixOT algebra.
property readonly warnOnDuplicateDepth: falseSheet data is state-only; duplicate render/event depth diagnostics do not apply.
property readonly documentState: PluginDocumentStateContribution<SheetDataPluginState, SheetDataPluginState>staticDocument-state export contribution for persisted sheet cells.
property readonly pluginKey: PluginKeystaticStable plugin key shared by all sheet data plugin instances.
property readonly symbol: symbolstaticDI token for resolving the sheet data plugin.
method apply(pluginState: SheetDataPluginState, transaction: Transaction): SheetDataPluginState | nullApplies sheet-data operations to the persisted cell matrix.
ReturnsUpdated plugin state, or null when the transaction has no relevant operations.
pluginStateCurrent sheet data state.
transactionTransaction containing MatrixOT-compatible operations.
method getPluginConfig(): nullSheet data has no render-time configuration.
method registerFormatTransfers(registry: SheetFormatTransferRegistry): voidContributes this owner's cell state to atomic range moves.
method registerQueries(queries: SheetDataQueryRegistry): voidPublishes a live read-only projection for consumers that do not need an export snapshot.
method registerRangeMoves(registry: SheetRangeMoveRegistry): voidmethod registerRangeReorders(registry: SheetRangeReorderRegistry): voidmethod registerState(): { dataEngine: { dataView: { fieldKey: string; select: (state: unknown): SheetMatrix; viewKey: string }[] }; key: PluginKey; state: SheetDataPluginState }Registers the sheet data matrix for commands, rendering, and collaboration.
method render(): Node<CellProperties>[]Sheet data does not render scene nodes directly.
ReturnsAn empty node list.
Inherited members 25
Inherited from Plugin.
- depth
- transactionHistory
- key
- dirtyRect
- enforceRuntimeWriteBoundary
- enforceStateWriteBoundary
- getState
- hasStateWriteBoundary
- lockCommittedState
- onClick
- onDblClick
- onInitialDataCell
- onInitialDataComplete
- onMouseDown
- onMouseMove
- onMouseUp
- onResize
- onScroll
- onTransactionCommitted
- projectTransaction
- registerConfig
- sealRuntimeMetadata
- sealRuntimeMethods
- sealRuntimeWrites
- setState
- interfaceDataEngineRegistrationOptions
-
interface DataEngineRegistrationOptions<StateType>Metadata associated with one DataEngine state registration.
property readonly 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.
property readonly fieldKey: stringField name written into the named view.
property readonly required?: booleanWhen false, missing owner state or void field values do not make the containing view unavailable.
property readonly select: (state: StateType): unknownReads the field value from the current owner state.
property readonly viewKey: stringNamed read model that receives the selected field.
- interfaceSheetCellDataReader
-
Read-only live cell-data projection exposed by SheetDataPlugin.
- interfaceSheetDataPluginState
-
State owned by SheetDataPlugin.
property sheetData: SheetMatrixMain sheet matrix containing persisted cell values.
- interfaceSheetDataQueryRegistry
-
Minimal query registry surface consumed by SheetDataPlugin.
- typeDataEngineViewFieldSelector
-
type DataEngineViewFieldSelector = { select: unknown }["select"]Selector used to publish one registered state field into a named data view.
- variableReadSheetCellDataQuery
-
ReadSheetCellDataQuery: ReadSheetCellDataQueryDefinitionReads 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.
matrixProjection matrix before the transaction.
operationsSource transaction operations.
createInvertibleProjection-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.
matrixMatrix to read.
colIndexColumn 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.
matrixMatrix to read.
rowIndexRow index to snapshot.
- functionreadSheetDataMatrix
-
readSheetDataMatrix(dataEngine: DataEngine): SheetMatrix | nullReads the persisted cell matrix published by SheetDataPlugin.
- functionregisterReadSheetCellDataQuery
-
registerReadSheetCellDataQuery(queries: SheetDataQueryRegistry, read: (): SheetMatrix): voidRegisters the live, read-only cell-data projection owned by SheetDataPlugin.
- interfaceCellMatrixElement
-
Persisted cell payload stored in the sheet matrix.
property formula?: stringFormula source text for formula cells; calculated results live in formula plugin state.
property formulaEvaluationMode?: "dynamic" | "legacy"Array evaluation mode used when the formula was entered.
property type: stringCell type identifier owned by the cell type catalog.
property value?: unknownRaw value whose shape is owned by the cell type.
- classSheetMatrix
-
class SheetMatrix extends CSRMatrix<CellMatrixElement>SheetMatrix public API.
constructor SheetMatrix(data?: { data: CellMatrixElement[]; indices: number[]; indptr: number[] }, shape?: [number, number]): SheetMatrixConstructs a CSRMatrix instance.
dataThe data for the matrix.
shapeThe shape of the matrix as [numRows, numCols].
method clone(): thisCopies stored cell payloads as well as sparse indexes.
Inherited members 34
Inherited from CSRMatrix.
- name
- ndim
- nnz
- shape
- addColumn
- addItem
- addListener
- addRow
- cloneCommittedView
- cloneDetached
- cloneForStaging
- deleteColumns
- deleteRows
- dispatch
- dot
- forEach
- forEachStored
- forEachStoredInRange
- forEachStoredInRow
- fromDense
- getCol
- getDefaultValue
- getItem
- getRow
- lockMutations
- multiply
- removeItem
- removeListener
- setDefaultValue
- sum
- swapColumn
- swapRow
- toArray
- transpose
Row and column sizes
Size and visibility fields determine which Sheet cells occupy the visible viewport.
- classVisibleRowDimensions
-
class VisibleRowDimensions extends DimensionsCSRMatrixDimension view shared by layout, hit testing, and rendering.
constructor VisibleRowDimensions(source: DimensionsCSRMatrix, visibility: SheetRowVisibility): VisibleRowDimensionsmethod getDefaultValue(): number | undefinedReturns the configured fallback used for absent sparse entries, if one exists.
method getDimensionsMap(): 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
Exampleconst matrix = new DimensionsCSRMatrix(...); const map = matrix.getDimensionsMap(); // [10, 30, 60]method getItem(row: number, column: number): number | nullRetrieves an item from the matrix at the specified row and column.
ReturnsThe item at the specified position or null if not present.
rowThe row index.
Inherited members 37
Inherited from DimensionsCSRMatrix.
- name
- ndim
- nnz
- shape
- addColumn
- addItem
- addListener
- addRow
- clone
- cloneCommittedView
- cloneDetached
- cloneForStaging
- deleteColumns
- deleteRows
- dispatch
- dot
- forEach
- forEachStored
- forEachStoredInRange
- forEachStoredInRow
- fromDense
- getCol
- getDimensionLeftBoundaryByIndex
- getDimensionRightBoundaryByIndex
- getLeftBoundaryColIndexByDimension
- getRightBoundaryColIndexByDimension
- getRow
- lockMutations
- multiply
- removeItem
- removeListener
- setDefaultValue
- sum
- swapColumn
- swapRow
- toArray
- transpose
- interfaceSheetRowVisibility
-
A Sheet presentation contribution that can suppress rows without changing their stored heights.
property readonly active: booleanproperty readonly version: numbermethod isRowFiltered(row: number): boolean - functionreadSheetRawRowSizes
-
readSheetRawRowSizes(dataEngine: DataEngine): DimensionsCSRMatrix | nullReads the resize owner's stored row heights, without presentation visibility.
- functionreadSheetColumnSizes
-
readSheetColumnSizes(dataEngine: DataEngine): DimensionsCSRMatrix | nullReads column dimensions published by SheetResizePlugin.
- functionreadSheetRowSizes
-
readSheetRowSizes(dataEngine: DataEngine): DimensionsCSRMatrix | nullReads row dimensions published by SheetResizePlugin.
- variableSheetColumnSizesFieldKey
-
SheetColumnSizesFieldKey: "sheet.resize.columnSizes"DataEngine field for column dimensions 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.
No matching API entries.