SearSuite
← All packages

API reference

@searsuite/sear-render-strategy

Full, dirty-region, retained, and incremental rendering policies.

36 exportsderived from source

classBlockRasterCopyPlansource ↗
class BlockRasterCopyPlan

Raster-copy plan for layout shifts where unchanged blocks move within the viewport.

constructorconstructor
BlockRasterCopyPlan(viewport: PositionRectProps, clearViewportRects: readonly PositionRect<templateLiteral>[], cacheToViewportCopies: readonly RasterCopyRect[], invalidWorldRects: readonly PositionRect<templateLiteral>[]): BlockRasterCopyPlan
viewport: PositionRectProps
clearViewportRects: readonly PositionRect<templateLiteral>[]
cacheToViewportCopies: readonly RasterCopyRect[]
invalidWorldRects: readonly PositionRect<templateLiteral>[]
propertycacheToViewportCopies
readonly cacheToViewportCopies: readonly RasterCopyRect[]
propertyclearViewportRects
readonly clearViewportRects: readonly PositionRect<templateLiteral>[]
propertyinvalidWorldRects
readonly invalidWorldRects: readonly PositionRect<templateLiteral>[]
propertyviewport
readonly viewport: PositionRectProps
methodfromLayoutShiftstatic
fromLayoutShift(input: BlockRasterCopyPlanInput): BlockRasterCopyPlan | null
input: BlockRasterCopyPlanInput
classDirtyRegionCollectorsource ↗
class DirtyRegionCollector<T>

Collects frame-scoped dirty regions and builds dirty clip geometry.

The collector is intentionally independent from Sheet cells. It owns only rectangle collection, frame cleanup, stroke expansion and the concave union clip used when a dirty region must include both a changed area and the previously painted node bounds.

constructorconstructor
DirtyRegionCollector<T>(source: DirtyRegionSource<T>): DirtyRegionCollector<T>

Creates a collector around a frame-scoped dirty source.

source: DirtyRegionSource<T>

Dirty source owned by the host renderer.

methodclear
clear(): void

Clears all dirty rectangles from the underlying source.

methodcollect
collect(): PositionRect<T>[]

Returns all dirty rectangles accumulated for the current frame.

The source is not cleared by this method; callers should clear only after the frame's redraw work has succeeded or has been intentionally skipped.

methodcreateClipRegionstatic
createClipRegion<T>(dirtyRect: PositionRect<T>, nodeRect: PositionRect<T>, strokeWidth: number, useUnionClip: boolean): PositionRect<templateLiteral> | [number, number][]

Builds the repaint clip for one dirty region and one intersecting node.

Most nodes can repaint within the expanded dirty rectangle. Selection-like nodes may need a concave clip covering the union of the dirty region and the node's previous bounds so erased borders do not leave seams.

ReturnsA rectangle or polygon accepted by scene node draw calls.

dirtyRect: PositionRect<T>

Dirty rectangle in world coordinates.

nodeRect: PositionRect<T>

Node bounds in world coordinates.

strokeWidth: number

Stroke width used to expand both dirty and node bounds.

useUnionClip: boolean

Whether to compute the concave union boundary.

methoddedupePointsstatic
dedupePoints(points: [number, number][]): [number, number][]

Removes duplicated points while preserving first occurrence order.

ReturnsDeduplicated polygon points.

points: [number, number][]

Polygon points.

methodexpandstatic
expand<T>(rect: PositionRect<T>, padding: number): PositionRect<templateLiteral>

Expands a dirty rectangle by a symmetric stroke padding.

ReturnsExpanded rectangle suitable for clipping repaint work.

rect: PositionRect<T>

Dirty rectangle in world coordinates.

padding: number

Pixels added to every edge.

methodremoveCollinearstatic
removeCollinear(points: [number, number][]): [number, number][]

Drops middle vertices that lie on a straight line.

Degenerate polygons are preserved as-is so callers can fall back to a rectangle when the boundary cannot form a useful clip.

ReturnsCleaned polygon points.

points: [number, number][]

Polygon points in boundary order.

methodtraceUnionBoundarystatic
traceUnionBoundary(rectA: DirtyRegionBounds, rectB: DirtyRegionBounds): [number, number][]

Traces the outer boundary of the union of two axis-aligned rectangles.

The returned path may be concave and is intended for clip construction, not for hit testing or layout geometry.

ReturnsBoundary points in drawing order.

rectA: DirtyRegionBounds

First rectangle bounds.

rectB: DirtyRegionBounds

Second rectangle bounds.

classDirtyRenderStrategysource ↗
class DirtyRenderStrategy<NodeTypeProperties> extends RenderStrategy<NodeTypeProperties>

Incremental renderer that redraws only dirty regions.

It reads dirty rectangles from the registered dirty tracker, clears those regions on both on-screen and off-screen contexts, redraws intersected nodes, and finally resets the dirty tracker.

constructorconstructor
DirtyRenderStrategy<NodeTypeProperties>(renderContext: RenderContext, offScreenRenderContext: RenderContext, hitRenderContext: RenderContext, scrollManager: ScrollManager, configEngine: ConfigEngine, renderCoordinatorManager: RenderCoordinatorManager, stage: SceneGraph<NodeTypeProperties>, tree: Tree<PositionRect<templateLiteral>>, dirtyTree: GenerationalDirtyTracker): DirtyRenderStrategy<NodeTypeProperties>

Creates a RenderStrategy instance.

renderContext: RenderContext
offScreenRenderContext: RenderContext
hitRenderContext: RenderContext
scrollManager: ScrollManager
configEngine: ConfigEngine
renderCoordinatorManager: RenderCoordinatorManager
stage: SceneGraph<NodeTypeProperties>
tree: Tree<PositionRect<templateLiteral>>
dirtyTree: GenerationalDirtyTracker
propertysymbolstatic
readonly symbol: typeof symbol

DI token for resolving DirtyRenderStrategy.

methodgetContext
getContext(): RenderContext

Returns the screen render context used by this strategy.

methodgetNodeByCoordinates
getNodeByCoordinates(node: Node<NodeTypeProperties>, x: number, y: number): Node<NodeTypeProperties>[]

Dirty strategy does not currently expose coordinate lookup.

ThrowsError Always thrown until this API is implemented.

node: Node<NodeTypeProperties>
x: number
y: number
methodrender
render(node: Node<NodeTypeProperties>): void

Redraws all dirty regions for both render targets.

Each dirty rect is processed atomically: clearRect followed immediately by redraw of intersecting nodes. This guarantees that a later rect's clear can erase pixels re-painted by an earlier rect's redraw — critical for cases like cell-editor exit where the overflow area must stay clean despite the grid cell's TextNode redrawing overflow text into it.

node: Node<NodeTypeProperties>
Inherited members 9

Inherited from RenderStrategy.

classEventRenderStrategysource ↗
class EventRenderStrategy<NodeTypeProperties> extends RenderStrategy<NodeTypeProperties>

Render strategy dedicated to event-layer integration.

This strategy currently acts as a placeholder extension point. It shares the same contract as all render strategies so event visualization can be added later without changing orchestration code.

constructorconstructor
EventRenderStrategy<NodeTypeProperties>(renderContext: RenderContext, offScreenRenderContext: RenderContext, hitRenderContext: RenderContext, scrollManager: ScrollManager, configEngine: ConfigEngine, renderCoordinatorManager: RenderCoordinatorManager, stage: SceneGraph<NodeTypeProperties>, tree: Tree<PositionRect<templateLiteral>>, dirtyTree: GenerationalDirtyTracker): EventRenderStrategy<NodeTypeProperties>

Creates a RenderStrategy instance.

renderContext: RenderContext
offScreenRenderContext: RenderContext
hitRenderContext: RenderContext
scrollManager: ScrollManager
configEngine: ConfigEngine
renderCoordinatorManager: RenderCoordinatorManager
stage: SceneGraph<NodeTypeProperties>
tree: Tree<PositionRect<templateLiteral>>
dirtyTree: GenerationalDirtyTracker
propertysymbolstatic
readonly symbol: typeof symbol

DI token for resolving EventRenderStrategy.

methodgetContext
getContext(): RenderContext

Returns the context used by this strategy.

methodgetNodeByCoordinates
getNodeByCoordinates(node: Node<NodeTypeProperties>, x: number, y: number): Node<NodeTypeProperties>[]

Event-layer hit lookup is not implemented yet.

ThrowsError Always thrown until this API is implemented.

node: Node<NodeTypeProperties>
x: number
y: number
methodrender
render(node: Node<NodeTypeProperties>): void

Executes event-layer rendering.

Current implementation is intentionally a no-op.

node: Node<NodeTypeProperties>
Inherited members 9

Inherited from RenderStrategy.

classHitRenderStrategysource ↗
class HitRenderStrategy<NodeTypeProperties> extends RenderStrategy<NodeTypeProperties>

Strategy for hit-testing rendering and coordinate-to-node lookup.

The hit layer paints interactive nodes with unique colors on an off-screen canvas. Pointer coordinates are then resolved by reading back pixel colors and mapping them to scene nodes.

constructorconstructor
HitRenderStrategy<NodeTypeProperties>(renderContext: RenderContext, offScreenRenderContext: RenderContext, hitRenderContext: RenderContext, scrollManager: ScrollManager, configEngine: ConfigEngine, renderCoordinatorManager: RenderCoordinatorManager, stage: SceneGraph<NodeTypeProperties>, tree: Tree<PositionRect<templateLiteral>>, dirtyTree: GenerationalDirtyTracker, platform: Platform): HitRenderStrategy<NodeTypeProperties>

Creates a HitRenderStrategy instance.

renderContext: RenderContext
offScreenRenderContext: RenderContext
hitRenderContext: RenderContext
scrollManager: ScrollManager
configEngine: ConfigEngine
renderCoordinatorManager: RenderCoordinatorManager
stage: SceneGraph<NodeTypeProperties>
tree: Tree<PositionRect<templateLiteral>>
dirtyTree: GenerationalDirtyTracker
platform: Platform
propertysymbolstatic
readonly symbol: typeof symbol

DI token for resolving HitRenderStrategy.

methoddebouncedRender
debouncedRender(node: Node<NodeTypeProperties>): void

Actually performs the hit-canvas rendering after debounce.

node: Node<NodeTypeProperties>

Node to render

methoddestroy
destroy(): void

Cancels deferred hit-layer work when the owning editor is destroyed.

methodflushPendingScrollRender
flushPendingScrollRender(): void

Ensures a pointer event never reads a hit layer from before the latest scroll-driven scene rebuild. The normal path remains frame-coalesced; this only runs when the user interacts before that frame is delivered.

methodgetContext
getContext(): RenderContext

Get the current rendering context.

ReturnsRenderContext

methodgetNodeByCoordinates
getNodeByCoordinates(node: Node<NodeTypeProperties>, x: number, y: number): Node<NodeTypeProperties>[]

Get all nodes at the given (x, y) coordinate by reading the hit-canvas pixel.

ReturnsArray of nodes at the given coordinate

node: Node<NodeTypeProperties>

Root node to search from

x: number

X coordinate

y: number

Y coordinate

methodrender
render(node: Node<NodeTypeProperties>, delay?: number): void

Debounced render entry. Only the last call within the delay will trigger rendering.

node: Node<NodeTypeProperties>

Node to render

delay: number

Debounce delay in ms

methodrenderImmediate
renderImmediate(node: Node<NodeTypeProperties>): void

Render the hit canvas immediately, bypassing the debounce timer.

Used after viewport-culled plugins rebuild their scene nodes during scroll. Since new FixBoxNode instances get new random color keys, the hit canvas must be redrawn before the next click event. The normal debounced path would keep resetting the timer during continuous scrolling, leaving the hit canvas stale and clicks unresolvable.

node: Node<NodeTypeProperties>
methodrenderOnNextFrame
renderOnNextFrame(node: Node<NodeTypeProperties>): void

Schedules a hit-layer refresh for the next frame. Wheel events can be delivered many times per frame; only the newest rebuilt scene matters.

node: Node<NodeTypeProperties>
Inherited members 9

Inherited from RenderStrategy.

classIncrementalRenderPolicysource ↗
class IncrementalRenderPolicy

Decides whether an incremental render candidate is worth using for the next frame.

constructorconstructor
IncrementalRenderPolicy(): IncrementalRenderPolicy
propertysymbolstatic
readonly symbol: typeof symbol

DI token for resolving IncrementalRenderPolicy.

methodevaluate
evaluate(candidate: IncrementalRenderCandidate, limits?: IncrementalRenderPolicyLimits): IncrementalRenderDecision
candidate: IncrementalRenderCandidate
limits: IncrementalRenderPolicyLimits
classOverlayRenderStrategysource ↗
class OverlayRenderStrategy<NodeTypeProperties> extends RenderStrategy<NodeTypeProperties>

Render pass that paints editor overlays at the very end of the pipeline.

This pass guarantees edit-mode visuals stay above sticky headers and any other layers by drawing nodes with isEdit after StickyRenderStrategy.

constructorconstructor
OverlayRenderStrategy<NodeTypeProperties>(renderContext: RenderContext, offScreenRenderContext: RenderContext, hitRenderContext: RenderContext, scrollManager: ScrollManager, configEngine: ConfigEngine, renderCoordinatorManager: RenderCoordinatorManager, stage: SceneGraph<NodeTypeProperties>, tree: Tree<PositionRect<templateLiteral>>, dirtyTree: GenerationalDirtyTracker): OverlayRenderStrategy<NodeTypeProperties>

Creates a RenderStrategy instance.

renderContext: RenderContext
offScreenRenderContext: RenderContext
hitRenderContext: RenderContext
scrollManager: ScrollManager
configEngine: ConfigEngine
renderCoordinatorManager: RenderCoordinatorManager
stage: SceneGraph<NodeTypeProperties>
tree: Tree<PositionRect<templateLiteral>>
dirtyTree: GenerationalDirtyTracker
propertysymbolstatic
readonly symbol: typeof symbol

DI token for resolving OverlayRenderStrategy.

methodgetContext
getContext(): RenderContext

Returns the context.

methodgetNodeByCoordinates
getNodeByCoordinates(node: Node<NodeTypeProperties>, x: number, y: number): Node<NodeTypeProperties>[]

Returns the node by coordinates.

node: Node<NodeTypeProperties>
x: number
y: number
methodrender
render(node: Node<NodeTypeProperties>): void

Renders OverlayRenderStrategy scene output.

node: Node<NodeTypeProperties>
Inherited members 9

Inherited from RenderStrategy.

classRasterCopyExecutorsource ↗
class RasterCopyExecutor

Executes raster copies between render contexts with transform isolation.

The executor owns the identity-transform save/restore wrapper used by Canvas viewport copy paths. Retained targets can avoid this executor entirely by selecting a full-frame rebuild through context capabilities.

constructorconstructor
RasterCopyExecutor(): RasterCopyExecutor
propertysymbolstatic
readonly symbol: typeof symbol

DI token for resolving RasterCopyExecutor.

methodcopy
copy(source: RenderContext, destination: RenderContext, copy: RasterCopyRect): void

Copies a rectangular pixel region from one render target into another.

source: RenderContext

Source render context.

destination: RenderContext

Destination render context.

copy: RasterCopyRect

Source and destination rectangles in viewport coordinates.

methodcopyNatural
copyNatural(source: RenderContext, destination: RenderContext, x?: number, y?: number): void

Copies the source target at its natural size to a viewport-space origin.

This keeps initial off-screen cache priming compatible with existing Canvas behavior where the complete visible backing store is cloned after first paint.

source: RenderContext

Source render context.

destination: RenderContext

Destination render context.

x: number

Destination x-coordinate.

y: number

Destination y-coordinate.

classRasterCopyPlansource ↗
class RasterCopyPlan

Immutable plan for reusing viewport pixels across render targets.

A plan describes the off-screen-to-visible copy for a scroll frame, the newly exposed viewport rectangle that still needs node redraw, and the final visible-to-off-screen copy that refreshes the cache after redraw.

constructorconstructor
RasterCopyPlan(viewport: PositionRect<templateLiteral>, cacheToViewportCopy: RasterCopyRect, blankViewportRect: PositionRect<templateLiteral>, blankWorldRect: PositionRect<templateLiteral>, viewportToCacheCopy: RasterCopyRect): RasterCopyPlan

Creates a raster copy plan.

viewport: PositionRect<templateLiteral>

Viewport rectangle in viewport coordinates.

cacheToViewportCopy: RasterCopyRect

Copy from the cached frame into the visible target.

blankViewportRect: PositionRect<templateLiteral>

Newly exposed viewport-space area to redraw.

blankWorldRect: PositionRect<templateLiteral>

Newly exposed world-space area to query from the scene.

viewportToCacheCopy: RasterCopyRect

Copy from the visible target back into the cache.

propertyblankViewportRect
readonly blankViewportRect: PositionRect<templateLiteral>

Newly exposed viewport-space area to redraw.

propertyblankWorldRect
readonly blankWorldRect: PositionRect<templateLiteral>

Newly exposed world-space area to query from the scene.

propertycacheToViewportCopy
readonly cacheToViewportCopy: RasterCopyRect

Copy from the cached frame into the visible target.

propertyviewport
readonly viewport: PositionRect<templateLiteral>

Viewport rectangle in viewport coordinates.

propertyviewportToCacheCopy
readonly viewportToCacheCopy: RasterCopyRect

Copy from the visible target back into the cache.

methodcreateViewportToCacheCopystatic
createViewportToCacheCopy(viewport: PositionRectProps): RasterCopyRect

Creates a full-viewport copy from the visible target into the frame cache.

ReturnsCopy rectangle with identical source and destination bounds.

viewport: PositionRectProps

Viewport-space bounds to copy.

methodfromScrollstatic
fromScroll(viewport: PositionRect<templateLiteral>, scrollState: ScrollManagerState): RasterCopyPlan

Builds the scroll-copy plan used by Canvas viewport renderers.

The delta convention follows RenderStrategy: delta is previous minus current, while drawImage source offsets use current minus previous.

ReturnsPlan for copy, exposed-area redraw, and cache refresh.

viewport: PositionRect<templateLiteral>

Visible viewport rectangle in viewport coordinates.

scrollState: ScrollManagerState

Current scroll snapshot.

classRenderStrategysource ↗
class RenderStrategy<T>

Base abstraction for all render strategies.

A render strategy encapsulates one rendering concern (screen layer, hit layer, sticky overlays, dirty-region redraw, etc.) and shares a common life-cycle:

  1. Receive scroll updates from ScrollManager.
  2. Derive absolute scroll position and frame delta.
  3. Trigger strategy-specific rendering.
  4. Persist previous scroll state for the next frame comparison.

Subclasses only need to implement how they render, which context they expose, and how they perform coordinate-based node lookup for their layer.

constructorconstructor
RenderStrategy<T>(renderContext: RenderContext, offScreenRenderContext: RenderContext, hitRenderContext: RenderContext, scrollManager: ScrollManager, configEngine: ConfigEngine, renderCoordinatorManager: RenderCoordinatorManager, stage: SceneGraph<T>, tree: Tree<PositionRect<templateLiteral>>, dirtyTree: GenerationalDirtyTracker): RenderStrategy<T>

Creates a RenderStrategy instance.

renderContext: RenderContext
offScreenRenderContext: RenderContext
hitRenderContext: RenderContext
scrollManager: ScrollManager
configEngine: ConfigEngine
renderCoordinatorManager: RenderCoordinatorManager
stage: SceneGraph<T>
tree: Tree<PositionRect<templateLiteral>>
dirtyTree: GenerationalDirtyTracker
propertydirtyTree
readonly dirtyTree: GenerationalDirtyTracker
propertyhitRenderContext
readonly hitRenderContext: RenderContext
propertyoffScreenRenderContext
readonly offScreenRenderContext: RenderContext
propertyrenderContext
readonly renderContext: RenderContext
propertyrenderCoordinatorManager
readonly renderCoordinatorManager: RenderCoordinatorManager
propertyscrollManager
readonly scrollManager: ScrollManager
propertystage
readonly stage: SceneGraph<T>
propertytree
readonly tree: Tree<PositionRect<templateLiteral>>
methodgetContext
getContext(): RenderContext

Returns the render context owned by this strategy.

methodgetNodeByCoordinates
getNodeByCoordinates(node: Node<T>, x: number, y: number): Node<T>[]

Resolves nodes around the provided coordinates for this strategy layer.

node: Node<T>
x: number
y: number
methodgetViewScaleContexts
getViewScaleContexts(): readonly RenderContext[]

Render contexts whose view scale is owned by this strategy.

Strategies that introduce an additional layer can override this method and include its context. RenderStrategyManager de-duplicates shared contexts before applying a scale change.

methodrender
render(node: Node<T>): void

Renders the target node tree according to the strategy semantics.

node: Node<T>
classRenderStrategyManagersource ↗
class RenderStrategyManager<NodeTypeProperties>

Registry and lookup manager for render strategies.

The render engine uses this manager to compose a strategy pipeline by name. Names can be string keys or symbols to avoid collisions in plugin scenarios.

constructorconstructor
RenderStrategyManager<NodeTypeProperties>(): RenderStrategyManager<NodeTypeProperties>
propertysymbolstatic
readonly symbol: symbol

DI token for resolving RenderStrategyManager.

methodaddStrategy
addStrategy(name: string | Symbol, strategy: RenderStrategy<NodeTypeProperties>): void

Registers or replaces a strategy under the provided key.

name: string | Symbol
strategy: RenderStrategy<NodeTypeProperties>
methodaddStrategyAfter
addStrategyAfter(reference: string | Symbol, name: string | Symbol, strategy: RenderStrategy<NodeTypeProperties>): void

Inserts a strategy immediately after an existing strategy.

reference: string | Symbol
name: string | Symbol
strategy: RenderStrategy<NodeTypeProperties>
methodaddStrategyBefore
addStrategyBefore(reference: string | Symbol, name: string | Symbol, strategy: RenderStrategy<NodeTypeProperties>): void

Inserts a strategy immediately before an existing strategy.

reference: string | Symbol
name: string | Symbol
strategy: RenderStrategy<NodeTypeProperties>
methodenforceCommandBoundary
enforceCommandBoundary(isExecuting: (): boolean): void

Closes direct strategy and view-scale changes after Sheet startup.

isExecuting: (): boolean
methodgetAllStrategy
getAllStrategy(): RenderStrategy<NodeTypeProperties>[]

Returns all currently registered strategies in insertion order.

methodgetStrategy
getStrategy(name: string | Symbol): RenderStrategy<NodeTypeProperties> | undefined

Retrieves a strategy by key.

name: string | Symbol
methodsetViewScale
setViewScale(scale: number): void

Propagates view scale to every context contributed by registered strategies. Shared base/off-screen/hit contexts are updated once.

scale: number
classScreenRenderStrategysource ↗
class ScreenRenderStrategy<NodeTypeProperties> extends RenderStrategy<NodeTypeProperties>

Base abstraction for all render strategies.

A render strategy encapsulates one rendering concern (screen layer, hit layer, sticky overlays, dirty-region redraw, etc.) and shares a common life-cycle:

  1. Receive scroll updates from ScrollManager.
  2. Derive absolute scroll position and frame delta.
  3. Trigger strategy-specific rendering.
  4. Persist previous scroll state for the next frame comparison.

Subclasses only need to implement how they render, which context they expose, and how they perform coordinate-based node lookup for their layer.

constructorconstructor
ScreenRenderStrategy<NodeTypeProperties>(renderContext: RenderContext, offScreenRenderContext: RenderContext, hitRenderContext: RenderContext, scrollManager: ScrollManager, configEngine: ConfigEngine, renderCoordinatorManager: RenderCoordinatorManager, stage: SceneGraph<NodeTypeProperties>, tree: Tree<PositionRect<templateLiteral>>, dirtyTree: GenerationalDirtyTracker, rasterCopyExecutor: RasterCopyExecutor): ScreenRenderStrategy<NodeTypeProperties>

Creates a screen render strategy with injected render targets and copy executor.

renderContext: RenderContext
offScreenRenderContext: RenderContext
hitRenderContext: RenderContext
scrollManager: ScrollManager
configEngine: ConfigEngine
renderCoordinatorManager: RenderCoordinatorManager
stage: SceneGraph<NodeTypeProperties>
tree: Tree<PositionRect<templateLiteral>>
dirtyTree: GenerationalDirtyTracker
rasterCopyExecutor: RasterCopyExecutor
propertysymbolstatic
readonly symbol: typeof symbol

DI token for resolving ScreenRenderStrategy.

methodconfigureRuntime
configureRuntime(runtime: ScreenRenderStrategyRuntime<NodeTypeProperties>): void

Configures host-specific viewport, query, and drawing semantics.

runtime: ScreenRenderStrategyRuntime<NodeTypeProperties>
methodgetContext
getContext(): RenderContext

Returns the current render context.

The returned context targets the on-screen canvas.

methodgetNodeByCoordinates
getNodeByCoordinates(node: Node<NodeTypeProperties>, x: number, y: number): Node<NodeTypeProperties>[]

Not implemented: Finds nodes at the given coordinates.

ThrowsError

node: Node<NodeTypeProperties>
x: number
y: number
methodrender
render(node: Node<NodeTypeProperties>): void

Renders the scene graph node using an off-screen buffer for efficient scrolling.

node: Node<NodeTypeProperties>

The root node to render.

Inherited members 9

Inherited from RenderStrategy.

classStickyRenderStrategysource ↗
class StickyRenderStrategy<NodeTypeProperties> extends RenderStrategy<NodeTypeProperties>

StickyRenderStrategy is responsible for rendering all StickyNode instances. It should be used after the main render strategy to overlay sticky elements.

constructorconstructor
StickyRenderStrategy<NodeTypeProperties>(renderContext: RenderContext, offScreenRenderContext: RenderContext, hitRenderContext: RenderContext, scrollManager: ScrollManager, configEngine: ConfigEngine, renderCoordinatorManager: RenderCoordinatorManager, stage: SceneGraph<NodeTypeProperties>, tree: Tree<PositionRect<templateLiteral>>, dirtyTree: GenerationalDirtyTracker): StickyRenderStrategy<NodeTypeProperties>

Creates a RenderStrategy instance.

renderContext: RenderContext
offScreenRenderContext: RenderContext
hitRenderContext: RenderContext
scrollManager: ScrollManager
configEngine: ConfigEngine
renderCoordinatorManager: RenderCoordinatorManager
stage: SceneGraph<NodeTypeProperties>
tree: Tree<PositionRect<templateLiteral>>
dirtyTree: GenerationalDirtyTracker
propertysymbolstatic
readonly symbol: typeof symbol

DI token for resolving StickyRenderStrategy.

methodgetContext
getContext(): RenderContext

Returns the current render context.

methodgetNodeByCoordinates
getNodeByCoordinates(node: Node<NodeTypeProperties>, x: number, y: number): Node<NodeTypeProperties>[]

Not implemented: Finds nodes at the given coordinates.

ThrowsError

node: Node<NodeTypeProperties>
x: number
y: number
methodrender
render(node: Node<NodeTypeProperties>): void

Renders all StickyNode descendants of the given node. Sticky nodes are positioned according to their sticky logic (top/left).

node: Node<NodeTypeProperties>

The root node to search for StickyNode descendants.

Inherited members 9

Inherited from RenderStrategy.

classViewportFrameCachesource ↗
class ViewportFrameCache

Manages the off-screen viewport frame used by Canvas scroll optimization.

The cache wraps RenderContext.isDrawn so consumers do not need to reach into the render target directly. It provides explicit operations for clearing, priming after first paint, and refreshing after an incremental scroll redraw.

constructorconstructor
ViewportFrameCache(cacheContext: RenderContext, copyExecutor: RasterCopyExecutor): ViewportFrameCache

Creates a viewport frame cache facade.

cacheContext: RenderContext

Off-screen render target that stores the last complete base frame.

copyExecutor: RasterCopyExecutor

Raster copy executor used for cache synchronization.

methodclear
clear(viewport: PositionRectProps): void

Clears the cached viewport with an identity transform.

viewport: PositionRectProps

Viewport-space rectangle to erase from the cache.

methodinvalidate
invalidate(): void

Marks the cached frame invalid so the next render performs a full prime.

methodisReady
isReady(): boolean

Returns whether the cache already contains a complete base frame.

methodmarkReady
markReady(): void

Marks the cached frame ready after a complete frame has been copied in.

methodprimeFromVisibleFrame
primeFromVisibleFrame(visibleContext: RenderContext, viewport: PositionRectProps): void

Primes the cache from the visible frame after a first full paint.

visibleContext: RenderContext

Visible render target containing a complete base frame.

viewport: PositionRectProps

Viewport-space rectangle to clear before copying.

methodrefreshFromVisibleFrame
refreshFromVisibleFrame(visibleContext: RenderContext, viewport: PositionRectProps): void

Refreshes the cache from the visible target after incremental redraw.

visibleContext: RenderContext

Visible render target containing the latest base frame.

viewport: PositionRectProps

Viewport-space rectangle to copy into the cache.

interfaceBlockRasterCopyCandidatesource ↗
interface BlockRasterCopyCandidate
propertydestination
readonly destination: PositionRectProps
propertysource
readonly source: PositionRectProps
interfaceBlockRasterCopyPlanInputsource ↗
interface BlockRasterCopyPlanInput
propertyclearWorldRects
readonly clearWorldRects: readonly PositionRectProps[]
propertycopies
readonly copies: readonly BlockRasterCopyCandidate[]
propertyinvalidWorldRects
readonly invalidWorldRects: readonly PositionRectProps[]
propertyscrollState
readonly scrollState: Pick<ScrollManagerState, "x" | "y">
propertyviewport
readonly viewport: PositionRectProps
interfaceDirtyRegionBoundssource ↗
interface DirtyRegionBounds

Boundary represented by four world-space edges.

propertyx1
readonly x1: number

Left edge in world coordinates.

propertyx2
readonly x2: number

Right edge in world coordinates.

propertyy1
readonly y1: number

Top edge in world coordinates.

propertyy2
readonly y2: number

Bottom edge in world coordinates.

interfaceDirtyRegionSourcesource ↗
interface DirtyRegionSource<T>

Minimal dirty-region storage contract consumed by DirtyRegionCollector.

Sheet uses GenerationalDirtyTracker; future document renderers can provide a block/page dirty source with the same boundary, query and frame-clear contract without depending on Sheet scene internals.

methodclear
clear(): void

Clears dirty state after the owning frame has consumed it.

methodgetBoundary
getBoundary(): PositionRect<T>

Returns the total query boundary that contains all possible dirty entries.

methodquery
query(range: PositionRect<T>): PositionRect<T>[]

Returns dirty rectangles intersecting the provided query range.

range: PositionRect<T>
interfaceIncrementalRenderCandidatesource ↗
interface IncrementalRenderCandidate

Measured cost shape for one proposed incremental render frame.

propertycopiedArea
readonly copiedArea: number

Total destination pixel area copied from the retained/off-screen frame cache.

propertycopyCount
readonly copyCount: number

Number of raster copy rectangles in the candidate plan.

propertyinvalidArea
readonly invalidArea: number

Total world pixel area that still needs redraw after raster reuse.

propertyinvalidRectCount
readonly invalidRectCount: number

Number of invalid redraw rectangles in the candidate plan.

propertyviewport
readonly viewport: Pick<PositionRectProps, "width" | "height">

Viewport dimensions used as the baseline for area ratios.

interfaceIncrementalRenderDecisionsource ↗
interface IncrementalRenderDecision
propertyaccepted
readonly accepted: boolean
propertyreason
readonly reason: IncrementalRenderDecisionReason
interfaceIncrementalRenderPolicyLimitssource ↗
interface IncrementalRenderPolicyLimits

Guardrails used to decide whether an incremental render plan is cheaper and safe enough to use.

propertymaxCopiedAreaRatio
readonly maxCopiedAreaRatio: number

Maximum total copied pixel area divided by viewport area. Values above 1 allow overlapping or repeated copies.

propertymaxCopyCount
readonly maxCopyCount: number

Maximum number of raster copy rectangles allowed in one frame.

propertymaxInvalidAreaRatio
readonly maxInvalidAreaRatio: number

Maximum invalid redraw area divided by viewport area after raster copies have been applied.

propertymaxInvalidRectCount
readonly maxInvalidRectCount: number

Maximum number of invalid redraw rectangles allowed in one frame.

interfaceRasterCopyRectsource ↗
interface RasterCopyRect

Source and destination rectangles for one raster copy.

propertydestination
readonly destination: PositionRectProps

Destination pixels inside the destination render target, expressed in viewport coordinates.

propertysource
readonly source: PositionRectProps

Source pixels inside the source render target, expressed in viewport coordinates.

interfaceRenderContextCapabilitiessource ↗
interface RenderContextCapabilities

Capability snapshot used by viewport render coordinators before choosing a raster strategy.

propertyrequiresExplicitNodeClear
readonly requiresExplicitNodeClear: boolean
propertyrequiresFrameRebuild
readonly requiresFrameRebuild: boolean
propertysupportsDirtyRedraw
readonly supportsDirtyRedraw: boolean
interfaceScreenRenderStrategyRuntimesource ↗
interface ScreenRenderStrategyRuntime<NodeTypeProperties>
propertyconsumeBlockRasterCopyPlan
readonly consumeBlockRasterCopyPlan?: (): BlockRasterCopyPlan | null

Consumes a pending block-copy plan for layout-shift frames, if the host has one.

propertydrawNodes
readonly drawNodes?: (input: { context: RenderContext; nodes: readonly Node<NodeTypeProperties>[]; scrollState: ScrollManagerState; worldRect: PositionRect<templateLiteral> }): void

Draws already queried nodes into the visible render context.

propertyforceFullRepaint
readonly forceFullRepaint?: (): boolean

Forces a full visible body repaint even when the off-screen cache is ready.

propertygetScrollState
readonly getScrollState?: (): ScrollManagerState

Returns the scroll state used for world queries and raster copy deltas.

propertygetViewport
readonly getViewport?: (): PositionRect<templateLiteral>

Returns the viewport-space rectangle covered by this screen layer.

propertyisScrollStateChanged
readonly isScrollStateChanged?: (scrollState: ScrollManagerState): boolean

Returns whether the current scroll state requires a scroll-copy frame.

propertyonFrameRendered
readonly onFrameRendered?: (mode: ScreenRenderFrameMode): void

Called after a full, scroll, or rebuilt frame is rendered.

propertyqueryNodes
readonly queryNodes?: (root: Node<NodeTypeProperties>, worldRect: PositionRect<templateLiteral>): readonly Node<NodeTypeProperties>[]

Returns screen-body nodes to draw for the supplied world-space rectangle.

propertyrequiresFrameRebuild
readonly requiresFrameRebuild?: (): boolean

Returns whether this frame should rebuild a retained render target.

propertytoWorldRect
readonly toWorldRect?: (viewportRect: PositionRect<templateLiteral>, scrollState: ScrollManagerState): PositionRect<templateLiteral>

Maps a viewport-space repaint rectangle to a world-space query rectangle.

typeIncrementalRenderDecisionReasonsource ↗
type IncrementalRenderDecisionReason = typeof IncrementalRenderDecisionReason[keyof typeof IncrementalRenderDecisionReason]
typeScreenRenderFrameModesource ↗
type ScreenRenderFrameMode = "rebuild" | "full" | "scroll" | "block-copy"

ScreenRenderStrategy handles rendering with an off-screen buffer to optimize scroll performance. It minimizes redraws by copying unchanged regions and only re-rendering areas affected by scrolling.

Rendering modes:

  • First frame: full draw to screen, then clone into off-screen buffer.
  • Scroll frame: blit preserved region from off-screen, redraw only newly exposed strip, then sync back to off-screen.
variableDEFAULT_INCREMENTAL_RENDER_POLICY_LIMITSsource ↗
DEFAULT_INCREMENTAL_RENDER_POLICY_LIMITS: IncrementalRenderPolicyLimits
variableIncrementalRenderDecisionReasonsource ↗
IncrementalRenderDecisionReason: { Accepted: "accepted"; EmptyViewport: "empty-viewport"; ExcessiveCopiedArea: "excessive-copied-area"; ExcessiveCopyCount: "excessive-copy-count"; ExcessiveInvalidArea: "excessive-invalid-area"; ExcessiveInvalidRectCount: "excessive-invalid-rect-count"; NotCandidate: "not-candidate" }
functionclearViewportsource ↗
clearViewport(context: RenderContext, viewport: PositionRectProps): void
context: RenderContext
viewport: PositionRectProps
functionclearViewportRectsource ↗
clearViewportRect(context: RenderContext, rect: PositionRectProps): void
context: RenderContext
rect: PositionRectProps
functioncreateViewportFrameCachesource ↗
createViewportFrameCache(cacheContext: RenderContext, copyExecutor: RasterCopyExecutor): ViewportFrameCache
cacheContext: RenderContext
copyExecutor: RasterCopyExecutor
functionreadRenderContextCapabilitiessource ↗
readRenderContextCapabilities(context: RenderContext): RenderContextCapabilities
context: RenderContext
functionrequiresViewportExplicitNodeClearsource ↗
requiresViewportExplicitNodeClear(context: RenderContext): boolean
context: RenderContext
functionrequiresViewportFrameRebuildsource ↗
requiresViewportFrameRebuild(context: RenderContext): boolean
context: RenderContext
functionsupportsViewportDirtyRedrawsource ↗
supportsViewportDirtyRedraw(context: RenderContext): boolean
context: RenderContext
functionworldRectToViewportClearRectsource ↗
worldRectToViewportClearRect<T>(rect: PositionRect<T>, scrollX: number, scrollY: number, padding: number): PositionRect<templateLiteral>
rect: PositionRect<T>
scrollX: number
scrollY: number
padding: number