← All packages

API reference

@searsuite/sear-domain-editor

Editor-local query, observation, capability, and lifecycle contracts shared by facades.

28 exportsderived from source

classArrayIndexedSnapshotsource ↗
class ArrayIndexedSnapshot<TSnapshot, TItem, TKey> extends IndexedSnapshot<TSnapshot, TItem, TKey>

Array and Map backed implementation of IndexedSnapshot.

constructorconstructor
ArrayIndexedSnapshot<TSnapshot, TItem, TKey>(snapshot: TSnapshot, items: readonly TItem[], getKey: (item: TItem): TKey, getIndex: (item: TItem): number): ArrayIndexedSnapshot<TSnapshot, TItem, TKey>

Creates an indexed snapshot from ordered items and selector functions.

snapshot: TSnapshot
items: readonly TItem[]
getKey: (item: TItem): TKey
getIndex: (item: TItem): number
methodgetByIndex
getByIndex(index: number): TItem | null

Returns one item by its numeric index.

index: number
methodgetByKey
getByKey(key: TKey): TItem | null

Returns one item by its stable key.

key: TKey
methodgetKeysByIndexes
getKeysByIndexes(indexes: readonly number[]): readonly TKey[]

Returns keys for the supplied numeric indexes, preserving input order.

indexes: readonly number[]
Inherited members 2

Inherited from IndexedSnapshot.

classDocBlockLayoutDiffsource ↗
class DocBlockLayoutDiff

Compares two block-layout snapshots and exposes render-neutral reuse facts.

constructorconstructor
DocBlockLayoutDiff(entries: readonly DocBlockLayoutDiffEntry[]): DocBlockLayoutDiff
entries: readonly DocBlockLayoutDiffEntry[]
propertyentries
readonly entries: readonly DocBlockLayoutDiffEntry[]
methodgetChangedEntries
getChangedEntries(): readonly DocBlockLayoutDiffEntry[]
methodgetEntry
getEntry(id: DocNodeId): DocBlockLayoutDiffEntry | null
id: DocNodeId
methodgetReusableRasterCopies
getReusableRasterCopies(): readonly DocBlockRasterReuse[]
methodgetShiftedEntries
getShiftedEntries(): readonly DocBlockLayoutDiffEntry[]
methodhasChanges
hasChanges(): boolean
methodcomparestatic
compare(previous: DocLayoutCache | null, current: DocLayoutCache, options?: DocBlockLayoutDiffOptions): DocBlockLayoutDiff
previous: DocLayoutCache | null
current: DocLayoutCache
options: DocBlockLayoutDiffOptions
classDocLayoutCachesource ↗
class DocLayoutCache

Immutable snapshot of block-level document layout used by viewport and SceneGraph projection.

constructorconstructor
DocLayoutCache(snapshot: LayoutSnapshot, blocksOrIndex: IndexedSnapshot<LayoutSnapshot, DocBlockLayout, DocNodeId> | readonly DocBlockLayout[]): DocLayoutCache

Creates a layout cache from already computed block records.

snapshot: LayoutSnapshot

Layout snapshot used to derive this cache.

blocksOrIndex: IndexedSnapshot<LayoutSnapshot, DocBlockLayout, DocNodeId> | readonly DocBlockLayout[]

Top-level block layout records ordered by document position, or a custom indexed store.

memberblocks
blocks: unknown
membersnapshot
snapshot: unknown
methodgetBlockById
getBlockById(id: DocNodeId): DocBlockLayout | null

Returns the cached layout record for a document block id.

id: DocNodeId
methodgetBlockByIndex
getBlockByIndex(index: number): DocBlockLayout | null

Returns the cached layout record for a top-level block index.

index: number
methodgetBlockIdsByIndexes
getBlockIdsByIndexes(indexes: readonly number[]): readonly DocNodeId[]

Returns block ids for the supplied top-level block indexes.

indexes: readonly number[]
methodgetBlocksInVerticalRange
getBlocksInVerticalRange(top: number, bottom: number): readonly DocBlockLayout[]

Returns all cached block records intersecting the supplied vertical range.

top: number
bottom: number
methodgetContentLayoutReusableBlockIndexes
getContentLayoutReusableBlockIndexes(previous: DocLayoutCache): readonly number[]

Returns block indexes whose internal content layout can be reused from a previous cache.

A downstream flow shift changes absolute rect.y, so the whole block record cannot be reused. The renderer can still reuse the block's measured content shape when line count, visual size and flow height are unchanged.

previous: DocLayoutCache
methodhasBlockFlowLayoutChanged
hasBlockFlowLayoutChanged(previous: DocLayoutCache, blockId: DocNodeId): boolean

Returns whether one block's height-sensitive flow layout changed.

previous: DocLayoutCache
blockId: DocNodeId
methodhasFlowHeightChanged
hasFlowHeightChanged(previous: DocLayoutCache, blockId: DocNodeId): boolean

Returns whether one block's flow height changed compared with another cache.

previous: DocLayoutCache
blockId: DocNodeId
methodfromSnapshotstatic
fromSnapshot(document: readonly RichDocNode[], snapshot: LayoutSnapshot, previousCache?: DocLayoutCache | null): DocLayoutCache

Builds a block layout cache from a rich document and its layout snapshot.

document: readonly RichDocNode[]
snapshot: LayoutSnapshot
previousCache: DocLayoutCache | null
classDocLayoutEnginesource ↗
class DocLayoutEngine

Converts between DocCursorPos (path + char offset) and pixel coordinates (relative to the editor box top-left corner), using rich-text block measurements.

Mirrors the Y-positioning formula used by the document render layout so that cursor positions align with rendered glyphs.

constructorconstructor
DocLayoutEngine(blockFlowRegistry: RichTextBlockFlowRegistry): DocLayoutEngine
blockFlowRegistry: RichTextBlockFlowRegistry
propertysymbolstatic
readonly symbol: symbol

DI token for resolving DocLayoutEngine.

methodbuildSnapshot
buildSnapshot(doc: RichDocNode[], blockManager: RichTextBlockLayoutProvider, editorWidth: number, editorHeight: number, cellPadding?: number, verticalAlign?: DocVerticalAlign): LayoutSnapshot

Build a LayoutSnapshot from the current blockManager state.

Prerequisites: callers must add all document paragraphs to blockManager before building the snapshot.

doc: RichDocNode[]

The current RichDocNode[] being edited.

blockManager: RichTextBlockLayoutProvider

Layout provider that already holds the paragraph blocks.

editorWidth: number

Total pixel width of the editor box (including padding).

editorHeight: number

Total pixel height of the editor box (including padding).

cellPadding: number

Padding on each side (default 4).

verticalAlign: DocVerticalAlign

Vertical positioning strategy (default center for embedded cell editors).

methodbuildSnapshotForBlocks
buildSnapshotForBlocks(doc: RichDocNode[], blockManager: RichTextBlockLayoutProvider, blockIndexes: readonly number[], blockTops: readonly number[], editorWidth: number, cellPadding?: number): BlockLayoutSnapshot

Builds a snapshot for selected top-level document blocks.

The returned lines keep their full-document text paths, but only the requested blocks are materialized. Callers supply each block's document Y-position from a block-height index.

doc: RichDocNode[]
blockManager: RichTextBlockLayoutProvider
blockIndexes: readonly number[]
blockTops: readonly number[]
editorWidth: number
cellPadding: number
methodcursorToPoint
cursorToPoint(pos: DocCursorPos, snapshot: LayoutSnapshot): { height: number; x: number; y: number }

Convert a DocCursorPos to pixel coordinates relative to the editor box top-left corner.

Returns the position of the cursor bar's horizontal anchor (i.e. the x at which to draw the vertical cursor line, and the y passed to drawCursor), plus the line height needed to size the cursor bar.

pos: DocCursorPos
snapshot: LayoutSnapshot
methodfindLineIndex
findLineIndex(pos: DocCursorPos, snapshot: LayoutSnapshot): number

Returns the index into snapshot.lines for the line containing pos. Returns 0 if not found.

pos: DocCursorPos
snapshot: LayoutSnapshot
methodgetSelectionRects
getSelectionRects(sel: DocSelection, snapshot: LayoutSnapshot, originX: number, originY: number): { height: number; width: number; x: number; y: number }[]

Compute canvas-space rectangles for a non-collapsed DocSelection.

ReturnsArray of {x,y,width,height} rectangles in canvas coordinates.

sel: DocSelection

The current DocSelection (anchor + head).

snapshot: LayoutSnapshot

Layout snapshot from buildSnapshot.

originX: number

Absolute canvas X of the editor box top-left.

originY: number

Absolute canvas Y of the editor box top-left.

methodpointToCursor
pointToCursor(px: number, py: number, snapshot: LayoutSnapshot): DocCursorPos

Convert a pixel position (relative to the editor box top-left) to the nearest DocCursorPos.

Used for click-to-position-cursor and drag-selection.

px: number
py: number
snapshot: LayoutSnapshot
classDocPageMapsource ↗
class DocPageMap

Maps document blocks to pages for viewport range queries and virtualization.

constructorconstructor
DocPageMap(pageHeight: number, pageGap: number, pages: readonly DocPageLayout[]): DocPageMap

Creates a page map from immutable page records.

pageHeight: number

Page height used by this map.

pageGap: number

Gap between pages in document coordinates.

pages: readonly DocPageLayout[]

Ordered page layout records.

propertypageGap
readonly pageGap: number

Gap between pages in document coordinates.

propertypageHeight
readonly pageHeight: number

Page height used by this map.

propertypages
readonly pages: readonly DocPageLayout[]

Ordered page layout records.

methodgetPage
getPage(index: number): DocPageLayout | null

Returns a page record by index.

index: number
methodgetPageIndexesForBlock
getPageIndexesForBlock(blockId: DocNodeId): readonly number[]

Returns page indexes that intersect a block id.

blockId: DocNodeId
methodgetPagesByIndexes
getPagesByIndexes(indexes: readonly number[]): readonly DocPageLayout[]

Returns pages for the supplied page indexes, preserving page order.

indexes: readonly number[]
methodgetPagesForBlock
getPagesForBlock(block: DocBlockLayout): readonly DocPageLayout[]

Returns all pages intersecting a block layout record.

block: DocBlockLayout
methodgetPagesInVerticalRange
getPagesInVerticalRange(top: number, bottom: number): readonly DocPageLayout[]

Returns all pages intersecting the supplied vertical document range.

top: number
bottom: number
methodfromLayoutCachestatic
fromLayoutCache(cache: DocLayoutCache, pageHeight: number, pageGap?: number): DocPageMap

Builds a page map by intersecting cached block rectangles with fixed-height pages.

cache: DocLayoutCache
pageHeight: number
pageGap: number
classDocViewportWindowsource ↗
class DocViewportWindow

Visible document window used to filter block and page layout ranges.

constructorconstructor
DocViewportWindow(x: number, y: number, width: number, height: number): DocViewportWindow

Creates a viewport window from document-space rectangle coordinates.

x: number

Left edge in document coordinates.

y: number

Top edge in document coordinates.

width: number

Visible width in document units.

height: number

Visible height in document units.

propertyheight
readonly height: number

Visible height in document units.

propertywidth
readonly width: number

Visible width in document units.

propertyx
readonly x: number

Left edge in document coordinates.

propertyy
readonly y: number

Top edge in document coordinates.

memberbottom
bottom: unknown
methodintersects
intersects(rect: DocLayoutRect): boolean

Returns whether this viewport intersects another document-space rectangle.

rect: DocLayoutRect
methodfromViewportstatic
fromViewport(viewport: { contentRect: DocLayoutRect }, scroll?: { x: number; y: number }): DocViewportWindow

Creates a document-space window from a viewport rectangle and scroll offsets.

viewport: { contentRect: DocLayoutRect }
scroll: { x: number; y: number }
classIndexedSnapshotsource ↗
class IndexedSnapshot<TSnapshot, TItem, TKey>

Generic immutable snapshot plus ordered, multi-key indexed item access.

propertyitems
readonly items: readonly TItem[]

Items in their canonical order.

propertysnapshot
readonly snapshot: TSnapshot
methodgetByIndex
getByIndex(index: number): TItem | null

Returns one item by its numeric index.

index: number
methodgetByKey
getByKey(key: TKey): TItem | null

Returns one item by its stable key.

key: TKey
methodgetKeysByIndexes
getKeysByIndexes(indexes: readonly number[]): readonly TKey[]

Returns keys for the supplied numeric indexes, preserving input order.

indexes: readonly number[]
classSearEditorsource ↗
class SearEditor

Injectable rich-document editor service placeholder.

The service owns document-editor initialization once a document assembly root is available. It is bound by symbol so consumers do not depend on string DI tokens.

constructorconstructor
SearEditor(): SearEditor

Constructs the editor service.

propertysymbolstatic
readonly symbol: symbol

DI token for resolving the editor service.

methodinitialize
initialize(): void

Initializes document-editor runtime state.

interfaceBlockLayoutSnapshotsource ↗
interface BlockLayoutSnapshot

Materialized layout for a subset of top-level document blocks.

propertyblocks
readonly blocks: readonly DocBlockLayout[]

Block records for the materialized blocks, using full-document indexes.

propertysnapshot
readonly snapshot: LayoutSnapshot

Line snapshot containing only the materialized block ranges.

interfaceDocBlockLayoutsource ↗
interface DocBlockLayout

Cached layout metadata for one top-level document block.

propertyflowHeight
readonly flowHeight: number

Flow height from this block top to the next block top, or visual height for the last block.

propertyid
readonly id: DocNodeId

Stable block identity used by retained render nodes.

propertyindex
readonly index: number

Zero-based top-level document block index.

propertylineEnd
readonly lineEnd: number

Exclusive index after the last layout line belonging to this block.

propertylineStart
readonly lineStart: number

Inclusive index of the first layout line belonging to this block.

propertyrect
readonly rect: DocLayoutRect

Document-space rectangle occupied by this block.

interfaceDocBlockLayoutDiffEntrysource ↗
interface DocBlockLayoutDiffEntry
propertycurrent
readonly current: DocBlockLayout | null
propertydeltaY
readonly deltaY: number
propertyid
readonly id: DocNodeId
propertyindex
readonly index: number
propertyprevious
readonly previous: DocBlockLayout | null
propertystatus
readonly status: DocBlockLayoutDiffStatus
interfaceDocBlockLayoutDiffOptionssource ↗
interface DocBlockLayoutDiffOptions
propertyreflowBlockIds
readonly reflowBlockIds?: ReadonlySet<DocNodeId>

Reflow blocks whose render output changed even if their measured layout shape did not.

propertyrepaintBlockIds
readonly repaintBlockIds?: ReadonlySet<DocNodeId>

Repaint blocks whose render output changed without invalidating layout cache.

interfaceDocBlockRasterReusesource ↗
interface DocBlockRasterReuse
propertydestination
readonly destination: DocLayoutRect
propertyid
readonly id: DocNodeId
propertyindex
readonly index: number
propertysource
readonly source: DocLayoutRect
interfaceDocBlockRenderDebugCopysource ↗
interface DocBlockRenderDebugCopy
propertydestination
readonly destination: DocBlockRenderDebugRect
propertysource
readonly source: DocBlockRenderDebugRect
interfaceDocBlockRenderDebugRectsource ↗
interface DocBlockRenderDebugRect
propertyheight
readonly height: number
propertywidth
readonly width: number
propertyx
readonly x: number
propertyy
readonly y: number
interfaceDocBlockRenderDebugSnapshotsource ↗
interface DocBlockRenderDebugSnapshot
propertychangedBlocks
readonly changedBlocks: readonly DocBlockRenderDebugRect[]
propertycopiedPixelArea
readonly copiedPixelArea: number
propertyframeMode
readonly frameMode: DocBlockRenderFrameMode
propertyincrementalRenderAccepted
readonly incrementalRenderAccepted: boolean
propertyincrementalRenderCandidate
readonly incrementalRenderCandidate?: DocBlockRenderPolicyCandidateDebugMetrics
propertyincrementalRenderReason
readonly incrementalRenderReason: string
propertyinvalidRedrawRects
readonly invalidRedrawRects: readonly DocBlockRenderDebugRect[]
propertyrasterCopies
readonly rasterCopies: readonly DocBlockRenderDebugCopy[]
propertyredrawnBlockCount
readonly redrawnBlockCount: number
propertyreusedBlocks
readonly reusedBlocks: readonly DocBlockRenderDebugRect[]
propertyshiftedBlocks
readonly shiftedBlocks: readonly DocBlockRenderDebugRect[]
propertyskippedBlockCount
readonly skippedBlockCount: number
interfaceDocBlockRenderPolicyCandidateDebugMetricssource ↗
interface DocBlockRenderPolicyCandidateDebugMetrics
propertycopiedAreaRatio
readonly copiedAreaRatio: number
propertycopiedPixelArea
readonly copiedPixelArea: number
propertycopyCount
readonly copyCount: number
propertyinvalidAreaRatio
readonly invalidAreaRatio: number
propertyinvalidPixelArea
readonly invalidPixelArea: number
propertyinvalidRectCount
readonly invalidRectCount: number
interfaceDocLayoutRectsource ↗
interface DocLayoutRect

Rectangle contract used by document layout planning without binding to a render target.

propertyheight
readonly height: number

Height in document units.

propertywidth
readonly width: number

Width in document units.

propertyx
readonly x: number

Left edge in document coordinates.

propertyy
readonly y: number

Top edge in document coordinates.

interfaceDocPageLayoutsource ↗
interface DocPageLayout

Layout metadata for one document page.

propertyblockIds
readonly blockIds: readonly DocNodeId[]

Block ids that intersect this page.

propertyindex
readonly index: number

Zero-based page index.

propertyrect
readonly rect: DocLayoutRect

Page rectangle in document coordinates.

interfaceDocViewportRangesource ↗
interface DocViewportRange

Inclusive visible block/page range within the current document viewport.

propertyendBlock
readonly endBlock: number

Last top-level document block index included in the buffered viewport.

propertyendPage
readonly endPage: number

Last page index included in the buffered viewport.

propertystartBlock
readonly startBlock: number

First top-level document block index included in the buffered viewport.

propertystartPage
readonly startPage: number

First page index included in the buffered viewport.

interfaceDocViewportScrollSourcesource ↗
interface DocViewportScrollSource

Minimal scroll/viewport contract needed to compute a document viewport range.

methodgetShape
getShape(): readonly [number, number]

Returns the viewport width/height.

methodgetState
getState(): { x: number; y: number }

Returns the current scroll offset in document coordinates.

interfaceLayoutLinesource ↗
interface LayoutLine

A single wrapped line inside the editor, with full path metadata for bidirectional cursor ↔ pixel coordinate mapping.

propertychars
chars: RichTextChar[]

Per-character measurements for this line.

propertycharStartOffset
charStartOffset: number

Char offset (within the text node) of the FIRST character on this line. e.g. if a text node wraps at char 20, the second line has charStartOffset=20.

propertycursorXOffsets
cursorXOffsets?: number[]

Cursor boundary x offsets relative to this line's x, one entry per char boundary.

propertyfontAscent
fontAscent: number

Font ascent: distance from baseline to top of tallest glyph on this line.

propertyheight
height: number

Line height in CSS/canvas pixels.

propertytextNodePath
textNodePath: number[]

Full path to the text node this line belongs to.

For a flat document (paragraph → single text node): textNodePath = [paraIndex, 0]

The path mirrors DocCursorPos.path semantics: a cursor at { path: textNodePath, offset } lives on this line when charStartOffset &lt;= offset &lt;= charStartOffset + chars.length.

propertyx
x: number

Left edge of text, relative to editor box top-left (includes cellPadding).

propertyy
y: number

Y coordinate used for fillText/cursor drawing, relative to editor box top-left. This is the baseline consumed by document render nodes so cursor pixel coordinates align with rendered text.

interfaceLayoutSnapshotsource ↗
interface LayoutSnapshot

Pre-computed layout for the entire editing session.

propertylines
lines: LayoutLine[]
typeDocBlockLayoutDiffStatussource ↗
type DocBlockLayoutDiffStatus = "unchanged" | "shifted" | "changed" | "added" | "removed"
typeDocBlockRenderFrameModesource ↗
type DocBlockRenderFrameMode = "rebuild" | "full" | "scroll" | "block-copy" | "skipped"
typeDocVerticalAlignsource ↗
type DocVerticalAlign = "top" | "center"

Vertical positioning strategy for a laid-out document frame.

functioncomputeViewportRangesource ↗
computeViewportRange(scrollSource: DocViewportScrollSource, layoutCache: DocLayoutCache, pageMap: DocPageMap, offset?: { x: number; y: number }): DocViewportRange

Computes the visible document block/page range from scroll state and cached layout.

This mirrors Sheet's viewport-range helper at the responsibility level: convert viewport bounds to inclusive start/end indexes and include a one-item buffer on each side. Consumers decide how to query blocks/pages or render.

scrollSource: DocViewportScrollSource
layoutCache: DocLayoutCache
pageMap: DocPageMap
offset: { x: number; y: number }
functionlockLayoutSnapshotsource ↗
lockLayoutSnapshot(snapshot: LayoutSnapshot): LayoutSnapshot

Locks a completed layout so readers cannot change cursor or render geometry.

snapshot: LayoutSnapshot