@searsuite/sear-render-cursor API reference

class CursorEngine

Abstract cursor presentation layer.

Responsibilities: translate a logical CursorToken into a concrete presentation (CSS cursor, Canvas sprite, Electron native cursor, test stub, …). Fully decoupled from the Plugin system and the rule system.

Contract:

mount() called once during plugin initialization, receives the render target.
apply() called on every cursor change; implementations must be idempotent.
unmount() called during plugin destruction; must clean up all side-effects.

constructorconstructor

CursorEngine(): CursorEngine

propertysymbolstatic

readonly symbol: symbol

DI token for resolving CursorEngine.

methodapply

apply(token: CursorToken): void

Applies a transaction to CursorEngine state.

token: CursorToken

methodmount

mount(target: unknown): void

Attaches this adapter to its host surface.

target: unknown

methodoverride

override(token: CursorToken | null): void

Lock the cursor to a fixed token (e.g. during cell editing). Pass null to release.

token: CursorToken | null

methodunmount

unmount(): void

Detaches this adapter from its host surface.

classCursorRegistry source ↗

class CursorRegistry

Stores cursor rules and resolves the correct CursorToken for a given CellProperties.

Resolution priority (highest → lowest):

Matching PositionCursorRule at the greatest layer — last registered wins
PredicateCursorRule { priority: 'high' } — last registered wins
RegionCursorRule — exact region match
TypeCursorRule — exact type match
PredicateCursorRule { priority: 'low' } — last registered wins
Fallback: 'default'

constructorconstructor

CursorRegistry(platform?: Platform): CursorRegistry

Creates a registry and optionally enables position-rule conflict diagnostics.

platform: Platform

propertysymbolstatic

readonly symbol: symbol

DI token for resolving CursorRegistry.

methodregister

register(rule: CursorRule): (): void

Registers a cursor rule and returns an idempotent disposer that restores the previous rule for the same key when applicable.

rule: CursorRule

methodregisterPosition

registerPosition(rule: Omit<PositionCursorRule, "kind">): (): void

Registers a coordinate-aware cursor rule without requiring callers to repeat the position-rule discriminator.

ReturnsAn idempotent disposer that restores the previous rule for its key.

rule: Omit<PositionCursorRule, "kind">: Position rule fields excluding the fixed kind discriminator.

methodresolve

resolve(properties: CellProperties | null, position?: CursorPosition): CursorToken

Resolves a logical cursor token without exposing presentation details.

properties: CellProperties | null: Hit-tested cell properties, if any.
position: CursorPosition: Pointer context used by registered coordinate rules.

classHeadlessCursorEngine source ↗

class HeadlessCursorEngine extends CursorEngine

Cursor adapter for environments that have no visible pointer.

constructorconstructor

HeadlessCursorEngine(): HeadlessCursorEngine

propertysymbolstatic

readonly symbol: symbol

DI token for resolving HeadlessCursorEngine.

methodapply

apply(_token: CursorToken): void

Applies a transaction to HeadlessCursorEngine state.

_token: CursorToken

methodmount

mount(_target: unknown): void

Attaches this adapter to its host surface.

_target: unknown

methodoverride

override(_token: CursorToken | null): void

Applies a temporary host cursor override.

_token: CursorToken | null

methodunmount

unmount(): void

Detaches this adapter from its host surface.

classSheetCursorPlugin source ↗

class SheetCursorPlugin extends Plugin<SearCoreSheet, CellProperties, ISheetCursorState>

Projects Sheet interaction state into host cursor behavior.

constructorconstructor

SheetCursorPlugin(cursorRegistry: CursorRegistry, cursorEngine: CursorEngine, coordinates: CoordinateEngine, renderContext: RenderContext): SheetCursorPlugin

Creates a SheetCursorPlugin instance.

cursorRegistry: CursorRegistry
cursorEngine: CursorEngine
coordinates: CoordinateEngine
renderContext: RenderContext

propertysymbolstatic

readonly symbol: symbol

DI token for resolving SheetCursorPlugin.

methodapply

apply(_state: ISheetCursorState, _tx: Transaction): ISheetCursorState | null

Applies a transaction to SheetCursorPlugin state.

_state: ISheetCursorState
_tx: Transaction

methodgetPluginConfig

getPluginConfig(): { }

Returns the plugin config.

methodonMouseMove

onMouseMove(_searCore: SearCoreSheet, event: EventWithOffsetAndTarget<CellProperties>): void

Returns void (not false) so the event continues to propagate to downstream plugins (selection, editor, etc.). See Guide.md §8: returning false blocks subsequent plugins.

_searCore: SearCoreSheet
event: EventWithOffsetAndTarget<CellProperties>

methodregisterState

registerState(): { key: PluginKey; state: { } }

Registers the state.

methodrender

render(): null

Returns null: this plugin produces no scene nodes. Nothing is written to SceneGraph → DirtyTree, StickyRenderStrategy, and Hit Canvas are completely unaffected (Rule.md §1.4, §1.5).

Inherited members 29

Inherited from Plugin.

classWebCursorEngine source ↗

class WebCursorEngine extends CursorEngine

Browser CSS cursor implementation. Maps CursorToken to CSS cursor values (including SVG data URI custom cursors).

constructorconstructor

WebCursorEngine(): WebCursorEngine

methodapply

apply(token: CursorToken): void

Applies a transaction to WebCursorEngine state.

token: CursorToken

methodmount

mount(target: unknown): void

Attaches this adapter to its host surface.

target: unknown

methodoverride

override(token: CursorToken | null): void

Applies a temporary host cursor override.

token: CursorToken | null

methodregisterToken

registerToken(token: string, cssCursor: string): void

Allow third parties to extend or override Token → CSS mapping.

token: string
cssCursor: string

methodunmount

unmount(): void

Detaches this adapter from its host surface.

Inherited members 1

Inherited from CursorEngine.

symbol

interfaceCursorPosition source ↗

interface CursorPosition

Pointer coordinates supplied to a position cursor rule for one pointer event.

propertycore

core: SearCoreSheet

Sheet core whose current data and interaction state may inform the cursor decision.

propertyorigin

origin: EventWithOffset

Original host pointer event.

propertytarget

target: CellProperties | null

Hit-tested cell properties, or null when the pointer is not over a scene node.

propertyview

view: { x: number; y: number }

Pointer location relative to the rendered viewport.

propertyworld

world: { x: number; y: number }

Pointer location in scrollable sheet-world coordinates.

interfacePositionCursorRule source ↗

interface PositionCursorRule

Cursor rule evaluated from the pointer location rather than a hit node. Higher layers win over lower layers and all structural cursor rules. When multiple matching rules share the highest layer, the last registered rule wins and CursorRegistry reports the ambiguous registration once.

propertycursor

cursor: CursorToken

Logical cursor presented while this rule owns the pointer.

propertykey

key: string | symbol

Stable owner key used for replacement, removal, and conflict diagnostics.

propertykind

kind: "position"

propertylayer

layer: number

Precedence among position rules; larger values take precedence.

propertytest

test: (position: CursorPosition): boolean

Returns whether this rule owns the supplied pointer location.

interfacePredicateCursorRule source ↗

interface PredicateCursorRule

Fully custom predicate rule.

priority: 'high' → evaluated before region/type rules (e.g., isEdit override). priority: 'low' → evaluated after region/type rules as a fallback (default).

propertycursor

cursor: CursorToken

propertykey

key?: string | symbol

Predicates need an explicit key to replace a previous predicate rule.

propertykind

kind: "predicate"

propertypriority

priority?: "high" | "low"

propertytest

test: (properties: CellProperties): boolean

interfaceRegionCursorRule source ↗

interface RegionCursorRule

Exact region-match rule (highest priority among structural rules).

propertycursor

cursor: CursorToken

propertykey

key?: string | symbol

Optional extension key; defaults to the region identifier.

propertykind

kind: "region"

propertyregion

region: CellRegion

interfaceTypeCursorRule source ↗

interface TypeCursorRule

Type-field match rule (secondary match).

propertycellType

cellType: string | symbol

propertycursor

cursor: CursorToken

propertykey

key?: string | symbol

Optional extension key; defaults to the cell type.

propertykind

kind: "type"

typeCursorRule source ↗

type CursorRule = RegionCursorRule | TypeCursorRule | PredicateCursorRule | PositionCursorRule

Type contract for CursorRule.

typeCursorToken source ↗

type CursorToken = typeof CursorToken[keyof typeof CursorToken] | string & { }

Built-in tokens plus an extension point for third-party plugins.

variableCursorRuleKind source ↗

CursorRuleKind: { Position: "position"; Predicate: "predicate"; Region: "region"; Type: "type" }

variableCursorRulePriority source ↗

CursorRulePriority: { High: "high"; Low: "low" }

variableCursorToken source ↗

CursorToken: { Cell: "cell"; ColumnResize: "col-resize"; ColumnSelect: "col-select"; Copy: "copy"; Default: "default"; Grab: "grab"; Grabbing: "grabbing"; Move: "move"; … }

Built-in logical cursor names, unbound to any rendering technology.