@vscode/markdown-editor 0.0.2-0 → 0.0.2-2

package/dist/index.d.ts

@@ -1,6 +1,1769 @@
-export * from './core/index.js';
-export * from './parser/index.js';
-export * from './model/index.js';
-export * from './commands/index.js';
-export * from './view/index.js';
-export * from './highlighter/index.js';
+import { Disposable } from './_observables/index';
+import { IDisposable } from './_observables/index';
+import { IObservable } from './_observables/index';
+import { IObservableWithChange } from './_observables/index';
+import { ISettableObservable } from './_observables/index';
+import { ITransaction } from './_observables/index';
+import { MonarchTokenizer } from 'monaco-editor/esm/vs/editor/standalone/common/monarch/monarchLexer.js';
+
+/** Every concrete node kind, for exhaustive consumer-side dispatch. */
+export declare type AnyAstNode = TextAstNode | MarkerAstNode | GlueAstNode | ThematicBreakAstNode | StrongAstNode | EmphasisAstNode | StrikethroughAstNode | InlineCodeAstNode | InlineMathAstNode | LinkAstNode | ImageAstNode | HeadingAstNode | ParagraphAstNode | CodeBlockAstNode | MathBlockAstNode | BlockQuoteAstNode | ListAstNode | ListItemAstNode | TableAstNode | TableRowAstNode | TableCellAstNode | DocumentAstNode;
+
+declare type AnyViewData = DocumentViewData | BlockViewData | InlineViewData | ListItemViewData | TableRowViewData | TableCellViewData | MarkerViewData | GlueViewData;
+
+export declare abstract class AstNode {
+    abstract readonly kind: string;
+    abstract get children(): readonly AstNode[];
+    /**
+     * A stable identity. Every node has one: it is minted on construction and
+     * carried across edits by reconciliation, so a node that survives an edit
+     * (even with changed content) keeps the same id.
+     */
+    readonly id: number;
+    /** Rebuild this node with each child replaced by `map.get(child) ?? child`. */
+    abstract mapChildren(map: ReadonlyMap<AstNode, AstNode>): AstNode;
+    private _length;
+    get length(): number;
+    /**
+     * True when `other` has the same content. Containers compare children *by
+     * identity* (`===`): bottom-up reconciliation substitutes reused old
+     * instances into the fresh tree first, so equal children already share
+     * instances — keeping this O(children), not O(subtree). Leaves have no
+     * children, so {@link _localEquals} is their whole comparison.
+     */
+    structurallyEqual(other: AstNode): boolean;
+    /** Compares only this node's own scalar fields (kind/length already match). */
+    protected _localEquals(_other: this): boolean;
+    /**
+     * A copy of this node that adopts `id`. Reconciliation uses this to carry an
+     * old identity onto a node whose content changed. Nodes are immutable value
+     * holders, so a shallow prototype copy with `id` overridden is sound.
+     */
+    cloneWithId(id: number): this;
+}
+
+export declare interface AstVisualization {
+    $fileExtension: 'ast.w';
+    source: string;
+    root: AstVisualizationNode;
+}
+
+declare interface AstVisualizationNode {
+    label: string;
+    range: [start: number, endExclusive: number];
+    children?: AstVisualizationNode[];
+}
+
+export declare type BlockAstNode = HeadingAstNode | ParagraphAstNode | CodeBlockAstNode | MathBlockAstNode | ThematicBreakAstNode | BlockQuoteAstNode | ListAstNode | TableAstNode;
+
+/**
+ * One block's place in the rendered document.
+ *
+ * `height` is in CSS pixels. It is either a real DOM measurement
+ * (`isMeasured: true`) or an estimate produced when the block is not
+ * currently mounted (`isMeasured: false`). Estimates exist so virtual
+ * rendering can size the scroll container without mounting every block.
+ *
+ * `visualLineMap` and `viewNode` are set only when the block is mounted
+ * and measured. Cursor positioning, selection painting and up/down
+ * navigation read through `visualLineMap`; the debug view walks
+ * `viewNode` to enumerate text leaves for per-character introspection.
+ * Unmeasured blocks have neither.
+ */
+export declare interface BlockMeasurement {
+    readonly block: BlockAstNode;
+    readonly absoluteStart: number;
+    readonly height: number;
+    readonly isMeasured: boolean;
+    readonly visualLineMap: VisualLineMap | undefined;
+    readonly viewNode: ViewNode | undefined;
+}
+
+export declare class BlockQuoteAstNode extends AstNode {
+    readonly content: readonly (MarkerAstNode | BlockAstNode | GlueAstNode)[];
+    readonly kind = "blockQuote";
+    constructor(content: readonly (MarkerAstNode | BlockAstNode | GlueAstNode)[]);
+    get children(): readonly AstNode[];
+    get blocks(): readonly BlockAstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+}
+
+declare class BlockQuoteViewData {
+    readonly ast: BlockQuoteAstNode;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "blockQuote";
+    constructor(ast: BlockQuoteAstNode, content: readonly AnyViewData[]);
+}
+
+declare type BlockViewData = HeadingViewData | ParagraphViewData | CodeBlockViewData | MathBlockViewData | ThematicBreakViewData | BlockQuoteViewData | ListViewData | TableViewData;
+
+/**
+ * Base view node for everything the editor renders, generic over the
+ * {@link AnyViewData view-data} it renders so subclasses get a precisely-typed
+ * {@link data} (e.g. `BlockViewNode<HeadingViewData>`). Every view-data kind has
+ * a subclass whose constructor builds the node's DOM and, recursively,
+ * constructs its child view nodes — so *constructing a node is rendering it*.
+ * There is no separate render pass: the view tree is the result of construction,
+ * and {@link createViewNode} is the single entry point that turns a `ViewData`
+ * into a node (reusing a `previous` node untouched when it still matches).
+ *
+ * The name is historical — it is the base for inline and leaf nodes too — but
+ * top-level blocks are always instances of it, and {@link element}/{@link block}
+ * are the conveniences {@link EditorView} uses for those.
+ */
+export declare class BlockViewNode<T extends AnyViewData = AnyViewData> extends ViewNode {
+    readonly data: T;
+    constructor(data: T, dom: globalThis.Node, children: readonly ViewNode[]);
+    get block(): BlockAstNode;
+    get element(): HTMLElement;
+    /**
+     * Whether this already-built node can stand in for `data` unchanged. The
+     * builder preserves view-data identity for any subtree whose ast and
+     * selection-derived flags are unchanged (see `buildDocumentViewData`), so a
+     * single identity check captures "nothing in my subtree changed" — and its
+     * whole subtree, and any session it owns, are kept as-is.
+     */
+    canReuse(data: AnyViewData): boolean;
+    /**
+     * Called by the view after this block is mounted and measured, with the
+     * block's rendered height in px. The default is a no-op; subclasses whose
+     * active/inactive renderings have different intrinsic heights (e.g. a math
+     * block) override this to remember a height to reserve across the toggle.
+     */
+    recordMeasuredHeight(_height: number): void;
+}
+
+export declare interface BlockViewOptions {
+    readonly renderCustomCodeBlock?: (language: string, content: string) => HTMLElement | undefined;
+    readonly onToggleCheckbox?: (item: ListItemAstNode, newChecked: boolean) => void;
+    /**
+     * Opens a link's URL. Called when the user activates a link: a plain click
+     * while the link's block is inactive (rendered), or a Ctrl/Cmd+click while it
+     * is active (source shown). Defaults to `window.open(url, '_blank')`.
+     */
+    readonly onOpenLink?: (url: string, event: MouseEvent) => void;
+    /**
+     * Colours fenced code blocks. When set, a code block's content is rendered
+     * as a sequence of token spans instead of one plain text node. This is the
+     * non-incremental path: the snapshot is read once at render time.
+     */
+    readonly syntaxHighlighter?: ISyntaxHighlighter;
+    /**
+     * Pluggable renderer for the *inactive* (rendered) form of a math node —
+     * both `$$…$$` blocks and inline `$…$`. When set and it returns a result,
+     * its {@link MathRendering.dom} replaces the default opaque `katex.render`
+     * output, and its {@link MathRendering.segments} let parts of the rendered
+     * math (e.g. individual identifier glyphs) map back to source ranges so the
+     * caret can land inside them. Returning `undefined` falls back to the
+     * default whole-node KaTeX leaf. The active (source) form is unaffected.
+     *
+     * This is the seam used to explore in-place editing of rendered math (see
+     * `katexEditableIdentifiers.ts`).
+     */
+    readonly renderMath?: (request: MathRenderRequest) => MathRendering | undefined;
+}
+
+export declare class CodeBlockAstNode extends AstNode {
+    readonly language: string;
+    readonly content: readonly (MarkerAstNode | GlueAstNode)[];
+    readonly kind = "codeBlock";
+    private _previous?;
+    private _contentEdit?;
+    constructor(language: string, content: readonly (MarkerAstNode | GlueAstNode)[]);
+    get children(): readonly AstNode[];
+    get openFence(): MarkerAstNode | undefined;
+    get closeFence(): MarkerAstNode | undefined;
+    get code(): MarkerAstNode | undefined;
+    /** Relative start offset of the {@link code} marker within this block. */
+    get codeOffset(): number;
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    protected _localEquals(o: this): boolean;
+    /**
+     * A copy of this block carrying an incremental link to `previous`:
+     * `contentEdit` (in the block's *content* coordinates) turns `previous`'s
+     * content into this one. Uses a weak reference so the previous tree can be
+     * garbage-collected.
+     */
+    withCodeDiff(previous: CodeBlockAstNode, contentEdit: StringEdit): CodeBlockAstNode;
+    /**
+     * When this block was incrementally derived from `previous` (same
+     * fences/language, edit entirely within the content), returns the
+     * content-coordinate edit; otherwise `undefined`.
+     */
+    getDiff(previous: CodeBlockAstNode): CodeBlockDiff | undefined;
+}
+
+/**
+ * Describes how a {@link CodeBlockAstNode} was incrementally derived from a previous
+ * one: {@link stringEdit} (in the block's *content* coordinates) turns the
+ * previous content into this one.
+ */
+declare interface CodeBlockDiff {
+    readonly stringEdit: StringEdit;
+}
+
+declare class CodeBlockViewData {
+    readonly ast: CodeBlockAstNode;
+    /** Active: render the fenced source; inactive: the (custom/highlighted) block. */
+    readonly showMarkup: boolean;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "codeBlock";
+    constructor(ast: CodeBlockAstNode, 
+    /** Active: render the fenced source; inactive: the (custom/highlighted) block. */
+    showMarkup: boolean, content: readonly AnyViewData[]);
+}
+
+/**
+ * A fenced code block. It owns its incremental
+ * {@link ISyntaxHighlighterDocument} session: constructing the node creates (or
+ * adopts from `previous`) the session, and disposing the node disposes it, so
+ * colouring stays incremental across edits — the session is reused and
+ * `update`d rather than rebuilt. A node at any depth owns a session; the only
+ * difference today is that the parser links `getDiff` for top-level code blocks
+ * only, so a nested block currently builds a fresh session on each rebuild.
+ */
+export declare class CodeBlockViewNode extends BlockViewNode<CodeBlockViewData> {
+    private _session;
+    /**
+     * Subscription that re-tokenises the rendered `<code>` in place whenever the
+     * session advances its {@link ISyntaxHighlighterDocument.snapshot} *without*
+     * a source edit (an async grammar finishing, a live recolour). It is tied to
+     * this node's lifetime, but like {@link _session} it must be disposed
+     * manually: a node reused as `previous` for a rebuild is never `dispose`d
+     * (see {@link reconcileDomChildren}), so the rebuilding constructor disposes
+     * its predecessor's subscription explicitly.
+     */
+    private _snapshotSub;
+    constructor(data: CodeBlockViewData, options: BlockViewOptions | undefined, previous: ViewNode | undefined);
+    dispose(): void;
+}
+
+/**
+ * A {@link MonacoSyntaxHighlighter} preloaded with a handful of common Monarch
+ * grammars (plus the usual short aliases). Unknown languages fall back to an
+ * unstyled single token, so the highlighter is always safe to call.
+ *
+ * The Monarch runtime and grammar definitions are injected so this package
+ * depends on `monaco-editor` for types only.
+ */
+export declare function createDefaultMonacoSyntaxHighlighter(monaco: IMonarchApi, grammars: IDefaultMonarchGrammars): MonacoSyntaxHighlighter;
+
+export declare type CursorCommand = (ctx: CursorCommandContext) => SourceOffset;
+
+export declare interface CursorCommandContext {
+    readonly text: string;
+    readonly selection: Selection_2;
+    readonly document: DocumentAstNode;
+    readonly activeBlock: BlockAstNode | undefined;
+}
+
+export declare const cursorDocumentEnd: CursorCommand;
+
+export declare const cursorDocumentStart: CursorCommand;
+
+export declare const cursorDown: VisualCursorCommand;
+
+export declare const cursorLeft: CursorCommand;
+
+export declare const cursorLineEnd: CursorCommand;
+
+export declare const cursorLineStart: CursorCommand;
+
+export declare const cursorMoveLeft: CursorCommand;
+
+export declare interface CursorMoveResult {
+    readonly offset: SourceOffset;
+    readonly desiredColumn: number | undefined;
+}
+
+export declare const cursorMoveRight: CursorCommand;
+
+export declare const cursorRight: CursorCommand;
+
+export declare const cursorUp: VisualCursorCommand;
+
+/**
+ * Owns the blinking cursor DOM element.
+ *
+ * The rendering pipeline is a single `derived` whose compute callback
+ * asks the {@link VisualLineMap} for the caret rect at the current
+ * offset, writes it to {@link element}, and returns a
+ * {@link CursorViewRendering} value as proof. An autorun keeps the
+ * derived subscribed.
+ */
+export declare class CursorView extends Disposable {
+    private readonly _parent;
+    readonly element: HTMLElement;
+    readonly rendering: IObservable<CursorViewRendering>;
+    constructor(_parent: HTMLElement, options: CursorViewOptions);
+}
+
+export declare interface CursorViewOptions {
+    readonly offset: IObservable<SourceOffset | undefined>;
+    readonly visualLineMap: IObservable<VisualLineMap>;
+}
+
+export declare class CursorViewRendering {
+    readonly offset: SourceOffset;
+    readonly visible: boolean;
+    readonly rect: Rect2D;
+    constructor(offset: SourceOffset, visible: boolean, rect: Rect2D);
+}
+
+export declare const cursorWordLeft: CursorCommand;
+
+export declare const cursorWordRight: CursorCommand;
+
+export declare const deleteLeft: EditCommand;
+
+export declare const deleteRight: EditCommand;
+
+export declare const deleteWordLeft: EditCommand;
+
+export declare const deleteWordRight: EditCommand;
+
+export declare class DocumentAstNode extends AstNode {
+    readonly content: readonly (BlockAstNode | GlueAstNode)[];
+    readonly kind = "document";
+    constructor(content: readonly (BlockAstNode | GlueAstNode)[]);
+    get children(): readonly AstNode[];
+    get blocks(): readonly BlockAstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+}
+
+/** A mounted block: its view node paired with where it starts in the source. */
+export declare interface DocumentBlock {
+    readonly node: BlockViewNode;
+    readonly absoluteStart: number;
+}
+
+/** A top-level block plus the document-level state the renderer applies to it. */
+declare interface DocumentBlockViewData {
+    readonly ast: BlockAstNode;
+    readonly absoluteStart: number;
+    /** Whether the selection reaches this block (drives `md-block-active`). */
+    readonly isActive: boolean;
+    readonly view: BlockViewData;
+}
+
+/** A mounted document child: a block or a run of inter-block glue. */
+declare interface DocumentChildViewData {
+    readonly absoluteStart: number;
+    /** For a block: selection reaches it. For glue: a neighbouring block is active. */
+    readonly isActive: boolean;
+    readonly view: BlockViewData | GlueViewData;
+    readonly kind: 'block' | 'glue';
+}
+
+/**
+ * The view-data root. Mirrors {@link DocumentAstNode}: {@link blocks} holds only
+ * its top-level blocks (each wrapped with where it starts and whether it is
+ * active), while {@link children} additionally interleaves the rendered
+ * document-level glue (the blank lines between blocks) in source order.
+ */
+declare class DocumentViewData {
+    readonly ast: DocumentAstNode;
+    readonly blocks: readonly DocumentBlockViewData[];
+    /**
+     * Blocks and inter-block glue interleaved in source order — the actual
+     * mount sequence. {@link blocks} is the block-only projection used for
+     * measurement and selection.
+     */
+    readonly children: readonly DocumentChildViewData[];
+    readonly kind = "document";
+    constructor(ast: DocumentAstNode, blocks: readonly DocumentBlockViewData[], 
+    /**
+     * Blocks and inter-block glue interleaved in source order — the actual
+     * mount sequence. {@link blocks} is the block-only projection used for
+     * measurement and selection.
+     */
+    children: readonly DocumentChildViewData[]);
+}
+
+/**
+ * Immutable view of the document's block sequence — the document-level
+ * analogue of {@link BlockViewNode}. Each {@link create} maps the
+ * {@link DocumentViewData} (the AST overlaid with selection-derived flags) to
+ * the block sequence, reusing the previous node's blocks by view-data identity,
+ * rebuilding only what changed, and patching its {@link contentDomNode}'s
+ * children to match.
+ *
+ * Like a {@link BlockViewNode}, it owns its DOM: the first `create` allocates
+ * the content element, and every later `create` keeps the previous node's
+ * element rather than making a new one. The element is therefore stable
+ * across rebuilds:
+ *
+ *     create(viewData, …, old).contentDomNode === old.contentDomNode
+ *
+ * so a parent can mount it once and never re-parent it.
+ *
+ * Because it is rebuilt rather than mutated, {@link EditorView} can hold the
+ * whole block cache as one value and simply swap it each frame, instead of
+ * carrying a mutable entry array and the reconcile bookkeeping itself.
+ *
+ * It is itself a {@link ViewNode} (the root of the view-node tree), so DOM ↔
+ * source mapping such as {@link ViewNode.resolveSource} is inherited: a hit on
+ * any descendant lifts up the parent chain to here, yielding an absolute
+ * document offset.
+ */
+export declare class DocumentViewNode extends ViewNode {
+    readonly blocks: readonly DocumentBlock[];
+    static create(viewData: DocumentViewData, options: BlockViewOptions | undefined, previous: DocumentViewNode | undefined): DocumentViewNode;
+    private constructor();
+    /** The stable content element this document mounts its children into. */
+    get contentDomNode(): HTMLElement;
+}
+
+/**
+ * A DOM node paired with a caret offset inside it. The node is an arbitrary
+ * {@link globalThis.Node} (a Text node for a caret inside text, an Element for
+ * a hit on element-only content), and `offset` is the caret offset within it.
+ */
+export declare interface DomPosition {
+    readonly node: globalThis.Node;
+    readonly offset: number;
+}
+
+export declare type EditCommand = (ctx: CursorCommandContext) => {
+    readonly edit: StringEdit;
+    readonly selection: Selection_2;
+} | undefined;
+
+/**
+ * Translates raw browser input (mouse, keyboard, EditContext) into model
+ * mutations. Knows about DOM event types but never reads/writes the DOM
+ * directly — it asks the {@link EditorView} to broker DOM↔source-offset
+ * conversions so the model stays free of view types.
+ *
+ * Owns the only non-derivable controller state:
+ * - `_desiredColumn` — sticky column for up/down navigation
+ */
+export declare class EditorController extends Disposable {
+    private readonly _model;
+    private readonly _view;
+    private _desiredColumn;
+    constructor(_model: EditorModel, _view: EditorView);
+    private readonly _handleTextUpdate;
+    private readonly _handleMouseDown;
+    private _makeCursorContext;
+    private _makeVisualCursorContext;
+    private _executeCursorCommand;
+    private _executeEditCommand;
+    private _executeVisualCursorCommand;
+    /** Move the cursor down one visual line (Arrow Down). */
+    cursorDown(extend?: boolean): void;
+    /** Move the cursor up one visual line (Arrow Up). */
+    cursorUp(extend?: boolean): void;
+    private readonly _handleCopy;
+    private readonly _handleCut;
+    private readonly _handlePaste;
+    private _selectedText;
+    private readonly _handleKeyDown;
+}
+
+export declare class EditorModel {
+    private readonly _parser;
+    /**
+     * The most recent edit applied to {@link sourceText}, used by
+     * {@link document} to let the parser link incrementally edited code
+     * blocks. Only trusted when it exactly bridges the previous and current
+     * source text (see {@link document}).
+     */
+    private _pendingEdit;
+    readonly sourceText: ISettableObservable<StringValue, void>;
+    /**
+     * The current selection, or `undefined` when the editor has no caret
+     * (e.g. an inactive/unfocused rendering).
+     */
+    readonly selection: ISettableObservable<Selection_2 | undefined, void>;
+    /**
+     * Forces the rendered active-block set. `undefined` (the default)
+     * derives the set from the current selection range (see
+     * {@link activeBlocks}). The sentinel {@link NO_ACTIVE_BLOCKS} forces
+     * "no active block" — useful in fixtures that always want the
+     * collapsed/inactive rendering.
+     */
+    readonly activeBlocksOverride: ISettableObservable<readonly BlockAstNode[] | typeof NO_ACTIVE_BLOCKS | undefined, void>;
+    readonly cursorOffset: IObservableWithChange<number | undefined, void>;
+    /**
+     * The parsed document. Threads the previous document into the parser so
+     * unchanged blocks keep their object identity across reparses (see
+     * {@link MarkdownParser.parse}). Writing `previous` inside the compute is
+     * a safe optimization: `derived` only recomputes when `sourceText`
+     * changes, and the result is structurally identical to a full reparse.
+     */
+    readonly document: IObservableWithChange<DocumentAstNode, void>;
+    /**
+     * Block that contains the cursor (selection's active end). Used by
+     * cursor navigation to know which block's marker ranges count as
+     * visible. Unaffected by {@link activeBlocksOverride} because
+     * navigation is independent of rendering.
+     */
+    readonly activeBlock: IObservableWithChange<BlockAstNode | undefined, void>;
+    /**
+     * All blocks whose source range intersects the current selection.
+     * The rendering side uses this to decide which blocks render in
+     * their expanded (markers-visible) form. When the selection is
+     * collapsed this is a one-element set holding {@link activeBlock}.
+     */
+    readonly activeBlocks: IObservableWithChange<Set<BlockAstNode>, void>;
+    applyEdit(edit: StringEdit): void;
+    applyEditForSelection(edit: StringEdit): void;
+}
+
+/**
+ * Pure-render view of an {@link EditorModel}.
+ *
+ * Invariant (the whole point of this file):
+ *
+ *     view(model + Δ) = view(model) + Δ
+ *
+ * The DOM the view produces is a function of the model. The only state the
+ * view holds is *DOM management*: the cached `BlockViewNode` instances and the
+ * `EditContext`. Anything that influences correctness but is not derivable
+ * from the model lives elsewhere:
+ *
+ *   - measured heights and per-block visual line maps  →  {@link MeasuredLayoutModel}
+ *   - desired column, drag-time freeze                 →  EditorController
+ *
+ * The view does not own a controller — callers construct an
+ * `EditorController` separately and pass it the view, so input handling is
+ * explicit and the view stays a pure renderer.
+ *
+ * The view writes into the measured-layout model as a side effect of
+ * rendering. It never reads its own measurements during rendering, so
+ * there is no feedback loop.
+ */
+export declare class EditorView extends Disposable {
+    private readonly _model;
+    private readonly _options?;
+    readonly element: HTMLElement;
+    readonly editContext: EditContext;
+    readonly measuredLayout: MeasuredLayoutModel;
+    private readonly _cursorView;
+    private readonly _selectionView;
+    /**
+     * The mounted block sequence, in source order. Rebuilt (not mutated) each
+     * frame by {@link DocumentViewNode.create}; the view just swaps one
+     * immutable node for the next. Never used for source-of-truth lookups
+     * (those go through the measured-layout model).
+     */
+    private readonly _document;
+    /** The current view-node tree (AST overlaid with rendered DOM), for debugging. */
+    get documentViewNode(): IObservable<DocumentViewNode | undefined>;
+    /**
+     * Last frame's view-data overlay, threaded back into
+     * {@link buildDocumentViewData} so any subtree whose ast and selection flags
+     * are unchanged keeps its view-data object — which lets the renderer reuse
+     * its DOM by identity.
+     */
+    private _previousViewData;
+    /** The current view-data tree (AST overlaid with selection flags), for debugging. */
+    private readonly _viewData;
+    get viewData(): IObservable<DocumentViewData | undefined>;
+    /**
+     * The block cache projected for views (selection painting) that need to
+     * react to mount/unmount. Derived from {@link _document}, so it stays in
+     * lock-step without any manual bookkeeping.
+     */
+    private readonly _selectionBlocksObs;
+    constructor(_model: EditorModel, _options?: EditorViewOptions | undefined);
+    focus(): void;
+    /**
+     * Client coordinates → absolute source offset (any block). Used during
+     * drag to keep extending the selection even when the pointer leaves the
+     * original block.
+     */
+    resolveOffsetFromPoint(point: Point2D): SourceOffset | undefined;
+    /**
+     * Whether a client point falls on the rendered document content, as
+     * opposed to the surrounding editor padding (the green area). Uses DOM
+     * containment rather than the content node's bounding box so that markers
+     * which overflow into the padding (e.g. a heading's `##`, which renders in
+     * the left margin) still count as content. Overlays (cursor, selection)
+     * have `pointer-events: none`, so the hit-test sees through them.
+     */
+    isPointInContent(point: Point2D): boolean;
+    private readonly _renderAutorun;
+    /** Current mounted blocks, or empty before the first render. */
+    private get _blocks();
+    /**
+     * Measure each mounted block's rect and per-block visual line map, then
+     * publish the result into the {@link MeasuredLayoutModel}. The model
+     * is not read here, so there is no feedback loop into the render autorun.
+     */
+    private _publishMeasurements;
+}
+
+export declare interface EditorViewOptions extends BlockViewOptions {
+    /**
+     * Extra class names added to the editor root element, e.g. a theme class
+     * such as `'md-theme-default'` or `'github-markdown-theme'`. Theme styles
+     * are scoped under these classes, so the editor is unstyled (base chrome
+     * only) unless a theme class is supplied.
+     */
+    readonly classNames?: readonly string[];
+}
+
+export declare class EmphasisAstNode extends AstNode {
+    readonly openMarker: MarkerAstNode;
+    readonly content: readonly (InlineAstNode | GlueAstNode)[];
+    readonly closeMarker: MarkerAstNode;
+    readonly kind = "emphasis";
+    constructor(openMarker: MarkerAstNode, content: readonly (InlineAstNode | GlueAstNode)[], closeMarker: MarkerAstNode);
+    get children(): readonly AstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+}
+
+declare class EmphasisViewData {
+    readonly ast: EmphasisAstNode;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "emphasis";
+    constructor(ast: EmphasisAstNode, content: readonly AnyViewData[]);
+}
+
+/**
+ * Source offset (relative to `root`) of the node with `target`'s id, or
+ * `undefined` when it is not in the tree. Ids are stable across edits, so this
+ * locates a node even after reconciliation has rebuilt the tree around it.
+ */
+export declare function findNodeOffsetById(root: AstNode, target: AstNode): number | undefined;
+
+export declare function findWordAt(text: string, offset: number): {
+    start: number;
+    end: number;
+};
+
+export declare function findWordBoundaryLeft(text: string, offset: number): number;
+
+export declare function findWordBoundaryRight(text: string, offset: number): number;
+
+export declare function getAnnotatedSource(node: AstNode, source: string, offset?: number): string;
+
+/** Non-semantic syntactic glue: whitespace, padding, table pipes. */
+export declare class GlueAstNode extends LeafAstNode {
+    readonly content: string;
+    readonly glueKind?: string | undefined;
+    readonly kind = "glue";
+    constructor(content: string, glueKind?: string | undefined);
+    protected _localEquals(o: this): boolean;
+}
+
+declare class GlueViewData {
+    readonly ast: GlueAstNode;
+    readonly visible: boolean;
+    /**
+     * Whether a source newline in this glue gets a visible `↵`. True only in
+     * inline flow, where the newline collapses to a space and the `↵` reveals
+     * the line ending hiding there; between block-level siblings (list items,
+     * block children) the break is already visible, so no `↵` is drawn.
+     */
+    readonly decorateNewline: boolean;
+    readonly kind = "glue";
+    constructor(ast: GlueAstNode, visible: boolean, 
+    /**
+     * Whether a source newline in this glue gets a visible `↵`. True only in
+     * inline flow, where the newline collapses to a space and the `↵` reveals
+     * the line ending hiding there; between block-level siblings (list items,
+     * block children) the break is already visible, so no `↵` is drawn.
+     */
+    decorateNewline: boolean);
+}
+
+export declare class HeadingAstNode extends AstNode {
+    readonly level: 1 | 2 | 3 | 4 | 5 | 6;
+    readonly marker: MarkerAstNode;
+    readonly content: readonly (InlineAstNode | GlueAstNode)[];
+    readonly kind = "heading";
+    constructor(level: 1 | 2 | 3 | 4 | 5 | 6, marker: MarkerAstNode, content: readonly (InlineAstNode | GlueAstNode)[]);
+    get children(): readonly AstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    protected _localEquals(o: this): boolean;
+}
+
+declare class HeadingViewData {
+    readonly ast: HeadingAstNode;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "heading";
+    constructor(ast: HeadingAstNode, content: readonly AnyViewData[]);
+}
+
+/** The Monarch language definitions the default highlighter wires up. */
+export declare interface IDefaultMonarchGrammars {
+    typescript: unknown;
+    javascript: unknown;
+    css: unknown;
+    html: unknown;
+    python: unknown;
+    rust: unknown;
+    shell: unknown;
+}
+
+export declare class ImageAstNode extends AstNode {
+    readonly alt: string;
+    readonly url: string;
+    readonly content: readonly (MarkerAstNode | GlueAstNode)[];
+    readonly kind = "image";
+    constructor(alt: string, url: string, content: readonly (MarkerAstNode | GlueAstNode)[]);
+    get children(): readonly AstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    protected _localEquals(o: this): boolean;
+}
+
+declare class ImageViewData {
+    readonly ast: ImageAstNode;
+    /** Active: render the `![alt](url)` source; inactive: the `<img>`. */
+    readonly showMarkup: boolean;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "image";
+    constructor(ast: ImageAstNode, 
+    /** Active: render the `![alt](url)` source; inactive: the `<img>`. */
+    showMarkup: boolean, content: readonly AnyViewData[]);
+}
+
+/**
+ * The slice of monaco's Monarch internals the highlighter needs at runtime.
+ *
+ * `monaco-editor` is only a *type* dependency of this package; the caller (who
+ * owns a real monaco runtime) passes these in, keeping monaco out of the bundle.
+ */
+export declare interface IMonarchApi {
+    /** Compiles a Monarch language definition into the internal lexer form. */
+    compile(languageId: string, json: unknown): unknown;
+    MonarchTokenizer: new (languageService: unknown, standaloneThemeService: unknown, languageId: string, lexer: unknown, configurationService: unknown) => MonarchTokenizer;
+}
+
+export declare type InlineAstNode = TextAstNode | StrongAstNode | EmphasisAstNode | StrikethroughAstNode | InlineCodeAstNode | InlineMathAstNode | LinkAstNode | ImageAstNode;
+
+export declare class InlineCodeAstNode extends AstNode {
+    readonly content: readonly (MarkerAstNode | GlueAstNode)[];
+    readonly kind = "inlineCode";
+    constructor(content: readonly (MarkerAstNode | GlueAstNode)[]);
+    get children(): readonly AstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+}
+
+declare class InlineCodeViewData {
+    readonly ast: InlineCodeAstNode;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "inlineCode";
+    constructor(ast: InlineCodeAstNode, content: readonly AnyViewData[]);
+}
+
+export declare class InlineMathAstNode extends AstNode {
+    readonly content: readonly (MarkerAstNode | GlueAstNode)[];
+    readonly kind = "inlineMath";
+    constructor(content: readonly (MarkerAstNode | GlueAstNode)[]);
+    get children(): readonly AstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+}
+
+declare class InlineMathViewData {
+    readonly ast: InlineMathAstNode;
+    /** Active: render the `$…$` source; inactive: the KaTeX output. */
+    readonly showMarkup: boolean;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "inlineMath";
+    constructor(ast: InlineMathAstNode, 
+    /** Active: render the `$…$` source; inactive: the KaTeX output. */
+    showMarkup: boolean, content: readonly AnyViewData[]);
+}
+
+declare type InlineViewData = TextViewData | StrongViewData | EmphasisViewData | StrikethroughViewData | InlineCodeViewData | InlineMathViewData | LinkViewData | ImageViewData;
+
+/**
+ * A Markdown hard line break: a `\n` whose preceding line ends with two spaces.
+ * Any spaces already trailing the insertion point count toward the two, so the
+ * line never accumulates more than the two needed to form the break.
+ */
+export declare const insertHardLineBreak: EditCommand;
+
+export declare const insertLineBreak: EditCommand;
+
+export declare const insertParagraph: EditCommand;
+
+export declare function insertText(text: string): EditCommand;
+
+/**
+ * An immutable view of one document's tokens at a point in time. It may be a
+ * thin view over the highlighter's mutable state: once the underlying document
+ * advances, calling a stale snapshot is allowed to throw.
+ *
+ * Token stability: across snapshots `S1 -> S2` (with the change delivered as a
+ * {@link LengthEdit}), `getTokens(r)` returns the same tokens for any range `r`
+ * not touched by that edit. Only ranges the edit reports as changed may recolour.
+ */
+export declare interface ISyntaxHighlightedSnapshot {
+    /**
+     * Tokens covering a region that contains `queryRange`. Tokens are never
+     * split: the returned {@link SnapshotTokens.range} is `queryRange` *grown*
+     * to whole-token boundaries, so a token that straddles an end of
+     * `queryRange` is returned in full. The result is dense over that grown
+     * range — `sum(token.length) === range.length` — which is why the range is
+     * returned alongside the tokens.
+     */
+    getTokens(queryRange: OffsetRange): SnapshotTokens;
+}
+
+export declare interface ISyntaxHighlighter {
+    create(language: string, initialText: string): ISyntaxHighlighterDocument;
+}
+
+export declare interface ISyntaxHighlighterDocument extends IDisposable {
+    /**
+     * Apply a source edit. The {@link snapshot} updates synchronously within
+     * `tx`, and the change it carries is the *minimal* {@link LengthEdit} that
+     * actually re-coloured — not the whole document.
+     */
+    update(edit: StringEdit, tx: ITransaction): void;
+    /**
+     * The current snapshot. Its change reason is a {@link LengthEdit} mapping
+     * the previous snapshot's offsets to this one's wherever tokens changed.
+     */
+    readonly snapshot: IObservableWithChange<ISyntaxHighlightedSnapshot, LengthEdit>;
+}
+
+declare abstract class LeafAstNode extends AstNode {
+    abstract readonly content: string;
+    get children(): readonly AstNode[];
+    get length(): number;
+    mapChildren(): AstNode;
+}
+
+/**
+ * A set of disjoint, sorted {@link LengthReplacement}s — the length-only
+ * counterpart of {@link StringEdit}. Used as the change reason of an
+ * observable so observers learn which offset ranges of the previous value map
+ * to which ranges of the new value (and thus what to invalidate) without
+ * carrying the new content itself.
+ */
+export declare class LengthEdit {
+    static readonly empty: LengthEdit;
+    static single(replacement: LengthReplacement): LengthEdit;
+    static replace(replaceRange: OffsetRange, newLength: number): LengthEdit;
+    readonly replacements: readonly LengthReplacement[];
+    constructor(replacements: readonly LengthReplacement[]);
+    get isEmpty(): boolean;
+    equals(other: LengthEdit): boolean;
+    toString(): string;
+}
+
+/**
+ * A single "the text in `replaceRange` now spans `newLength` characters"
+ * statement. Unlike {@link StringReplacement} it carries no text — it only
+ * describes *where* and *by how much* something changed, not *what to*.
+ *
+ * For syntax highlighting it means: the characters that used to occupy
+ * `replaceRange` are replaced by `newLength` characters whose tokens may now
+ * be coloured differently. A same-length replacement (`replaceRange.length ===
+ * newLength`) therefore means "these characters kept their positions but got
+ * re-coloured".
+ */
+export declare class LengthReplacement {
+    readonly replaceRange: OffsetRange;
+    readonly newLength: number;
+    static replace(replaceRange: OffsetRange, newLength: number): LengthReplacement;
+    constructor(replaceRange: OffsetRange, newLength: number);
+    get lengthDelta(): number;
+    equals(other: LengthReplacement): boolean;
+    toString(): string;
+}
+
+export declare class LinkAstNode extends AstNode {
+    readonly url: string;
+    readonly content: readonly (MarkerAstNode | InlineAstNode | GlueAstNode)[];
+    readonly kind = "link";
+    constructor(url: string, content: readonly (MarkerAstNode | InlineAstNode | GlueAstNode)[]);
+    get children(): readonly AstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    protected _localEquals(o: this): boolean;
+}
+
+declare class LinkViewData {
+    readonly ast: LinkAstNode;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "link";
+    constructor(ast: LinkAstNode, content: readonly AnyViewData[]);
+}
+
+export declare class ListAstNode extends AstNode {
+    readonly ordered: boolean;
+    readonly content: readonly (ListItemAstNode | GlueAstNode)[];
+    readonly kind = "list";
+    constructor(ordered: boolean, content: readonly (ListItemAstNode | GlueAstNode)[]);
+    get children(): readonly AstNode[];
+    get items(): readonly ListItemAstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    protected _localEquals(o: this): boolean;
+}
+
+export declare class ListItemAstNode extends AstNode {
+    readonly marker: MarkerAstNode;
+    readonly content: readonly (BlockAstNode | GlueAstNode)[];
+    readonly checked?: boolean | undefined;
+    readonly leadingTrivia?: GlueAstNode | undefined;
+    readonly kind = "listItem";
+    constructor(marker: MarkerAstNode, content: readonly (BlockAstNode | GlueAstNode)[], checked?: boolean | undefined, leadingTrivia?: GlueAstNode | undefined);
+    get children(): readonly AstNode[];
+    get blocks(): readonly BlockAstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    protected _localEquals(o: this): boolean;
+}
+
+declare class ListItemViewData {
+    readonly ast: ListItemAstNode;
+    /** Whether the selection reaches this item (reveals its markers). */
+    readonly isActive: boolean;
+    readonly content: readonly AnyViewData[];
+    /** 1-based list nesting depth, used to size the indentation gutter. */
+    readonly level: number;
+    readonly kind = "listItem";
+    constructor(ast: ListItemAstNode, 
+    /** Whether the selection reaches this item (reveals its markers). */
+    isActive: boolean, content: readonly AnyViewData[], 
+    /** 1-based list nesting depth, used to size the indentation gutter. */
+    level: number);
+}
+
+declare class ListViewData {
+    readonly ast: ListAstNode;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "list";
+    constructor(ast: ListAstNode, content: readonly AnyViewData[]);
+}
+
+/**
+ * Parses markdown into a {@link DocumentAstNode}.
+ *
+ * When given the `previous` document and the `edit` that produced the new
+ * text, it reuses unchanged subtrees and carries node identities across the
+ * edit (see {@link parseIncremental}), so views can diff cheaply and code
+ * blocks keep their incremental highlighting sessions.
+ */
+export declare class MarkdownParser {
+    parse(text: StringValue, previous?: DocumentAstNode, edit?: StringEdit): DocumentAstNode;
+}
+
+/** A semantic syntax marker (heading `#`, fences, brackets, list bullet, …). */
+export declare class MarkerAstNode extends LeafAstNode {
+    readonly markerKind: string;
+    readonly content: string;
+    readonly kind = "marker";
+    constructor(markerKind: string, content: string);
+    protected _localEquals(o: this): boolean;
+}
+
+declare class MarkerViewData {
+    readonly ast: MarkerAstNode;
+    readonly visible: boolean;
+    readonly kind = "marker";
+    constructor(ast: MarkerAstNode, visible: boolean);
+}
+
+export declare class MathBlockAstNode extends AstNode {
+    readonly content: readonly (MarkerAstNode | GlueAstNode)[];
+    readonly kind = "mathBlock";
+    constructor(content: readonly (MarkerAstNode | GlueAstNode)[]);
+    get children(): readonly AstNode[];
+    get code(): MarkerAstNode | undefined;
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+}
+
+declare class MathBlockViewData {
+    readonly ast: MathBlockAstNode;
+    /** Active: render the source; inactive: the KaTeX output. */
+    readonly showMarkup: boolean;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "mathBlock";
+    constructor(ast: MathBlockAstNode, 
+    /** Active: render the source; inactive: the KaTeX output. */
+    showMarkup: boolean, content: readonly AnyViewData[]);
+}
+
+/** Result of a {@link BlockViewOptions.renderMath} renderer. */
+export declare interface MathRendering {
+    /** Host element to mount (the rendered math output). */
+    readonly dom: HTMLElement;
+    /** Source-mapped spans within {@link dom} (need not tile the whole node). */
+    readonly segments: readonly MathSourceSegment[];
+}
+
+/** Input to a {@link BlockViewOptions.renderMath} renderer. */
+export declare interface MathRenderRequest {
+    /** The LaTeX source of the math content (without the `$$`/`$` fences). */
+    readonly latex: string;
+    /** `true` for a `$$…$$` block, `false` for inline `$…$`. */
+    readonly displayMode: boolean;
+    /** CSS class the host element must carry (editor styling/measurement hooks). */
+    readonly className: string;
+    /** Full source length of the math node (fences/`$` included). */
+    readonly nodeLength: number;
+    /** Offset of {@link latex} within the node (i.e. after the opening fence/`$`). */
+    readonly contentStart: number;
+}
+
+/**
+ * A span of the rendered math output that maps to a slice of source. The
+ * renderer reports these for the parts it can map (e.g. identifier glyphs);
+ * the editor tiles the gaps between them so the whole math node stays mapped.
+ */
+export declare interface MathSourceSegment {
+    /** A DOM node (ideally a Text node) within the rendered output. */
+    readonly dom: globalThis.Node;
+    /** Start offset of the mapped slice, relative to the math node's start. */
+    readonly start: number;
+    /** Source length of the mapped slice. */
+    readonly length: number;
+}
+
+/**
+ * Immutable record of one rendered debug frame.
+ */
+export declare class MeasuredLayoutDebugRendering {
+    readonly blockCount: number;
+    readonly mountedCount: number;
+    readonly lineCount: number;
+    /** Absolute source offsets that map to a rendered DOM character. */
+    readonly mappedOffsets: ReadonlySet<number>;
+    constructor(blockCount: number, mountedCount: number, lineCount: number, 
+    /** Absolute source offsets that map to a rendered DOM character. */
+    mappedOffsets: ReadonlySet<number>);
+}
+
+/**
+ * Debug view for a {@link MeasuredLayoutModel}.
+ *
+ * Exposes two DOM nodes the caller can place independently:
+ *
+ *  - {@link overlayElement} — absolutely positioned; the caller mounts it
+ *    inside the editor element so dashed line-bands and run-boxes line up
+ *    with the editor's client coordinates.
+ *  - {@link infoElement} — block-flow; the caller mounts it as a sibling
+ *    *below* the editor. Contains the per-block summary table that used
+ *    to live on the overlay.
+ *
+ * Same pattern as `CursorView` / `SelectionView`: the rendering pipeline
+ * is a single `derived` whose compute callback writes the DOM and returns
+ * a {@link MeasuredLayoutDebugRendering} value as proof. An autorun keeps
+ * the derived subscribed.
+ */
+export declare class MeasuredLayoutDebugView extends Disposable {
+    private readonly _overlayParent;
+    readonly overlayElement: HTMLElement;
+    readonly infoElement: HTMLElement;
+    readonly rendering: IObservable<MeasuredLayoutDebugRendering>;
+    /** Absolute source offsets that map to a rendered DOM character. */
+    readonly mappedOffsets: IObservable<ReadonlySet<number>>;
+    /** Whether the dashed line-bands and run boxes are drawn (persisted). */
+    private readonly _showLineRects;
+    constructor(_overlayParent: HTMLElement, options: MeasuredLayoutDebugViewOptions);
+}
+
+export declare interface MeasuredLayoutDebugViewOptions {
+    readonly model: MeasuredLayoutModel;
+    /**
+     * DEBUG ONLY. Maps an absolute source offset to a fill color for that
+     * character's glyph rect. The fixture passes the same function to the
+     * raw-source view so a character and its rect share one color — a
+     * mismatch exposes a source ↔ DOM mapping bug.
+     */
+    readonly colorForOffset?: (offset: number) => string | undefined;
+    /**
+     * DEBUG ONLY. Shared "currently hovered source offset". When set, the
+     * overlay isolates the matching glyph rect; the fixture passes the same
+     * observable to the raw-source view so hovering either side highlights the
+     * same character in both. Hovering a rect writes this; `undefined` clears.
+     */
+    readonly hoveredOffset?: ISettableObservable<number | undefined>;
+}
+
+/**
+ * The set of measurements/estimates the view has produced for the current
+ * document. This is the "view → derived facts about layout" channel: the
+ * view writes here as a side effect of rendering and measuring; the
+ * controller (and selection/cursor rendering) reads from here.
+ *
+ * Keeping these facts in their own observable model — instead of as ad-hoc
+ * fields on the view — preserves the invariant
+ *
+ *     view(model + Δ) = view(model) + Δ
+ *
+ * i.e. the view becomes a pure function of (EditorModel, MeasuredLayoutModel).
+ * Everything else that depends on layout (controller, commands) goes
+ * through this model and never touches view fields directly.
+ */
+export declare class MeasuredLayoutModel {
+    readonly measurements: ISettableObservable<readonly BlockMeasurement[], void>;
+    /**
+     * Concatenated visual line map across all mounted blocks. Lines are
+     * left in DOM (client-coordinate) y order — each per-block map already
+     * uses absolute client coordinates from `getClientRects()`, so the
+     * concatenation is well-formed without re-sorting.
+     */
+    readonly visualLineMap: IObservableWithChange<VisualLineMap, void>;
+}
+
+/**
+ * {@link ISyntaxHighlighter} backed by monaco's Monarch tokenizer.
+ *
+ * Highlighting is synchronous and incremental: an edit only re-runs the
+ * tokenizer from the first changed line onward (earlier lines and their saved
+ * end-states are reused), and the {@link LengthEdit} delivered with the new
+ * snapshot is the minimal char range whose colour actually changed.
+ *
+ * Only Monarch's *classic* tokenizer path is used, which needs neither a theme
+ * nor the DOM, so this runs headless (Node, workers) as well as in the browser.
+ */
+export declare class MonacoSyntaxHighlighter implements ISyntaxHighlighter {
+    private readonly _monaco;
+    private readonly _grammars;
+    private readonly _tokenizers;
+    /**
+     * @param _monaco The Monarch runtime ({@link IMonarchApi}), injected so this
+     * package depends on `monaco-editor` for types only.
+     * @param _grammars Maps a language id to its Monarch language definition.
+     */
+    constructor(_monaco: IMonarchApi, _grammars: ReadonlyMap<string, unknown>);
+    create(language: string, initialText: string): ISyntaxHighlighterDocument;
+    dispose(): void;
+    private _tokenizerFor;
+}
+
+/**
+ * Move the cursor one position left or right, skipping over hidden marker
+ * ranges in inactive blocks (and inactive items of an active list).
+ */
+export declare function nextCursorPosition(doc: DocumentAstNode, activeBlock: BlockAstNode | undefined, cursor: number, direction: 'left' | 'right'): number;
+
+declare const NO_ACTIVE_BLOCKS: unique symbol;
+
+export declare class OffsetRange {
+    readonly start: number;
+    readonly endExclusive: number;
+    static fromTo(start: number, endExclusive: number): OffsetRange;
+    static ofLength(length: number): OffsetRange;
+    static ofStartAndLength(start: number, length: number): OffsetRange;
+    static emptyAt(offset: number): OffsetRange;
+    constructor(start: number, endExclusive: number);
+    get isEmpty(): boolean;
+    get length(): number;
+    delta(offset: number): OffsetRange;
+    deltaStart(offset: number): OffsetRange;
+    deltaEnd(offset: number): OffsetRange;
+    contains(offset: number): boolean;
+    containsRange(other: OffsetRange): boolean;
+    intersects(other: OffsetRange): boolean;
+    intersectsOrTouches(other: OffsetRange): boolean;
+    intersect(other: OffsetRange): OffsetRange | undefined;
+    join(other: OffsetRange): OffsetRange;
+    isBefore(other: OffsetRange): boolean;
+    isAfter(other: OffsetRange): boolean;
+    substring(str: string): string;
+    slice<T>(arr: readonly T[]): T[];
+    equals(other: OffsetRange): boolean;
+    toString(): string;
+}
+
+export declare class ParagraphAstNode extends AstNode {
+    readonly content: readonly (InlineAstNode | GlueAstNode)[];
+    readonly kind = "paragraph";
+    constructor(content: readonly (InlineAstNode | GlueAstNode)[]);
+    get children(): readonly AstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+}
+
+declare class ParagraphViewData {
+    readonly ast: ParagraphAstNode;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "paragraph";
+    constructor(ast: ParagraphAstNode, content: readonly AnyViewData[]);
+}
+
+/**
+ * Immutable point in 2D space, in CSS-pixel client coordinates.
+ */
+export declare class Point2D {
+    readonly x: number;
+    readonly y: number;
+    static readonly ZERO: Point2D;
+    constructor(x: number, y: number);
+    translate(dx: number, dy: number): Point2D;
+}
+
+/**
+ * Immutable axis-aligned rectangle in 2D space, in CSS-pixel client
+ * coordinates. `x`/`y` is the top-left corner, growing right/down.
+ *
+ * Half-open in both dimensions: `right` and `bottom` are excluded.
+ */
+export declare class Rect2D {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    static readonly EMPTY: Rect2D;
+    static fromPointPoint(left: number, top: number, right: number, bottom: number): Rect2D;
+    static fromPointSize(x: number, y: number, width: number, height: number): Rect2D;
+    private constructor();
+    get left(): number;
+    get top(): number;
+    get right(): number;
+    get bottom(): number;
+    get topLeft(): Point2D;
+    containsX(x: number): boolean;
+    containsY(y: number): boolean;
+    containsPoint(p: Point2D): boolean;
+    /** Same y/height, zero-width band at `x = this.left`. Useful for caret rects derived from a line. */
+    withZeroWidthAt(x: number): Rect2D;
+    translate(dx: number, dy: number): Rect2D;
+}
+
+export declare const selectAll: SelectionCommand;
+
+export declare function selectBlock(ctx: CursorCommandContext, blockRange: OffsetRange): Selection_2;
+
+declare class Selection_2 {
+    readonly anchor: SourceOffset;
+    readonly active: SourceOffset;
+    static collapsed(offset: SourceOffset): Selection_2;
+    constructor(anchor: SourceOffset, active: SourceOffset);
+    get isCollapsed(): boolean;
+    get isForward(): boolean;
+    get range(): OffsetRange;
+    collapseToActive(): Selection_2;
+    withActive(active: SourceOffset): Selection_2;
+}
+export { Selection_2 as Selection }
+
+/**
+ * One mounted block, as far as selection painting is concerned. The view
+ * supplies its block cache in this shape so the selection layer never has
+ * to reach back into private view state.
+ */
+export declare interface SelectionBlock {
+    readonly block: BlockAstNode;
+    readonly absoluteStart: number;
+    readonly viewNode: ViewNode;
+    readonly element: HTMLElement;
+}
+
+export declare type SelectionCommand = (ctx: CursorCommandContext, offset: SourceOffset) => Selection_2;
+
+export declare interface SelectionRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+
+/**
+ * Owns the SVG overlay that paints the selection.
+ *
+ * Rendering is *line-based*, not glyph-based:
+ *
+ *  1. Each {@link VisualLine} overlapping the selection produces one rect
+ *     using the full line-box height (so the selection has even, line-
+ *     height bands instead of jagged glyph rects).
+ *  2. Inter-block gaps fully inside the selection become connector rects.
+ *  3. All rects are grouped into vertically-adjacent clusters and each
+ *     cluster is rendered as a single connected polygon with rounded
+ *     corners.
+ *
+ * To keep the polygon connected without gaps, "middle" lines (any line
+ * that is neither the first nor the last selected line in the document)
+ * are extended to their full line extent, while the first and last lines
+ * are clipped to the actual selection start/end. This is the standard
+ * envelope shape used by IDE selection rendering.
+ */
+export declare class SelectionView extends Disposable {
+    private readonly _parent;
+    readonly element: SVGSVGElement;
+    readonly rendering: IObservable<SelectionViewRendering>;
+    private readonly _path;
+    constructor(_parent: HTMLElement, options: SelectionViewOptions);
+}
+
+export declare interface SelectionViewOptions {
+    readonly selection: IObservable<Selection_2 | undefined>;
+    readonly visualLineMap: IObservable<VisualLineMap>;
+    readonly blocks: IObservable<readonly SelectionBlock[]>;
+}
+
+export declare class SelectionViewRendering {
+    readonly rects: readonly SelectionRect[];
+    constructor(rects: readonly SelectionRect[]);
+}
+
+export declare const selectWord: SelectionCommand;
+
+/**
+ * A run of {@link Token}s together with the exact {@link OffsetRange} they
+ * cover.
+ *
+ * Because tokens are returned whole (never clipped), this is the natural unit
+ * of structural comparison: for any region untouched by an edit, two snapshots
+ * return an equal `SnapshotTokens` (same `range`, same token lengths/classes).
+ */
+export declare interface SnapshotTokens {
+    readonly range: OffsetRange;
+    readonly tokens: readonly Token[];
+}
+
+export declare type SourceOffset = number;
+
+export declare class StrikethroughAstNode extends AstNode {
+    readonly openMarker: MarkerAstNode;
+    readonly content: readonly (InlineAstNode | GlueAstNode)[];
+    readonly closeMarker: MarkerAstNode;
+    readonly kind = "strikethrough";
+    constructor(openMarker: MarkerAstNode, content: readonly (InlineAstNode | GlueAstNode)[], closeMarker: MarkerAstNode);
+    get children(): readonly AstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+}
+
+declare class StrikethroughViewData {
+    readonly ast: StrikethroughAstNode;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "strikethrough";
+    constructor(ast: StrikethroughAstNode, content: readonly AnyViewData[]);
+}
+
+export declare class StringEdit {
+    static readonly empty: StringEdit;
+    static single(replacement: StringReplacement): StringEdit;
+    static replace(range: OffsetRange, text: string): StringEdit;
+    static insert(offset: number, text: string): StringEdit;
+    static delete(range: OffsetRange): StringEdit;
+    readonly replacements: readonly StringReplacement[];
+    constructor(replacements: readonly StringReplacement[]);
+    get isEmpty(): boolean;
+    apply(base: string): string;
+    inverse(original: string): StringEdit;
+    equals(other: StringEdit): boolean;
+    mapOffset(offset: number): number;
+    toString(): string;
+}
+
+export declare class StringReplacement {
+    readonly replaceRange: OffsetRange;
+    readonly newText: string;
+    static insert(offset: number, text: string): StringReplacement;
+    static replace(range: OffsetRange, text: string): StringReplacement;
+    static delete(range: OffsetRange): StringReplacement;
+    constructor(replaceRange: OffsetRange, newText: string);
+    get isEmpty(): boolean;
+    equals(other: StringReplacement): boolean;
+    toString(): string;
+}
+
+export declare class StringValue {
+    readonly value: string;
+    constructor(value: string);
+    get length(): number;
+    substring(range: OffsetRange): string;
+    toString(): string;
+}
+
+export declare class StrongAstNode extends AstNode {
+    readonly openMarker: MarkerAstNode;
+    readonly content: readonly (InlineAstNode | GlueAstNode)[];
+    readonly closeMarker: MarkerAstNode;
+    readonly kind = "strong";
+    constructor(openMarker: MarkerAstNode, content: readonly (InlineAstNode | GlueAstNode)[], closeMarker: MarkerAstNode);
+    get children(): readonly AstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+}
+
+declare class StrongViewData {
+    readonly ast: StrongAstNode;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "strong";
+    constructor(ast: StrongAstNode, content: readonly AnyViewData[]);
+}
+
+export declare class TableAstNode extends AstNode {
+    readonly content: readonly (TableRowAstNode | GlueAstNode)[];
+    readonly kind = "table";
+    constructor(content: readonly (TableRowAstNode | GlueAstNode)[]);
+    get children(): readonly AstNode[];
+    private get _rows();
+    get headerRow(): TableRowAstNode | undefined;
+    get delimiterRow(): TableRowAstNode | undefined;
+    get bodyRows(): readonly TableRowAstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+}
+
+export declare class TableCellAstNode extends AstNode {
+    readonly content: readonly (InlineAstNode | MarkerAstNode | GlueAstNode)[];
+    readonly kind = "tableCell";
+    constructor(content: readonly (InlineAstNode | MarkerAstNode | GlueAstNode)[]);
+    get children(): readonly AstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+}
+
+declare class TableCellViewData {
+    readonly ast: TableCellAstNode;
+    /** Whether the selection reaches this cell (reveals its inline markers). */
+    readonly isActive: boolean;
+    /** Whether the owning table is active (reveals the structural pipes). */
+    readonly showTableGlue: boolean;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "tableCell";
+    constructor(ast: TableCellAstNode, 
+    /** Whether the selection reaches this cell (reveals its inline markers). */
+    isActive: boolean, 
+    /** Whether the owning table is active (reveals the structural pipes). */
+    showTableGlue: boolean, content: readonly AnyViewData[]);
+}
+
+export declare class TableRowAstNode extends AstNode {
+    readonly content: readonly (TableCellAstNode | GlueAstNode)[];
+    readonly kind = "tableRow";
+    constructor(content: readonly (TableCellAstNode | GlueAstNode)[]);
+    get children(): readonly AstNode[];
+    get cells(): readonly TableCellAstNode[];
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+}
+
+declare class TableRowViewData {
+    readonly ast: TableRowAstNode;
+    readonly isDelimiter: boolean;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "tableRow";
+    constructor(ast: TableRowAstNode, isDelimiter: boolean, content: readonly AnyViewData[]);
+}
+
+declare class TableViewData {
+    readonly ast: TableAstNode;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "table";
+    constructor(ast: TableAstNode, content: readonly AnyViewData[]);
+}
+
+/**
+ * Source range (relative to `item`) of a task list item's `[x]`/`[ ]`
+ * checkbox, or `undefined` when the item is not a task item. The checkbox is
+ * plain glue in the AST, so a host that wants to toggle it locates the literal
+ * `[x]`/`[ ]` token here.
+ */
+export declare function taskCheckboxRange(item: ListItemAstNode): OffsetRange | undefined;
+
+/** Real document text (an {@link InlineAstNode}). */
+export declare class TextAstNode extends LeafAstNode {
+    readonly content: string;
+    readonly kind = "text";
+    constructor(content: string);
+    protected _localEquals(o: this): boolean;
+}
+
+declare class TextViewData {
+    readonly ast: TextAstNode;
+    readonly showWhitespace: boolean;
+    readonly leftWordBoundary: boolean;
+    readonly rightWordBoundary: boolean;
+    readonly kind = "text";
+    /**
+     * Whether non-obvious whitespace in this text is revealed (block is active).
+     * `leftWordBoundary`/`rightWordBoundary` say whether the inline sibling on
+     * that side ends/starts with visible word content (e.g. inline code, a link,
+     * emphasis); a single space touching such a sibling is obvious and stays
+     * undecorated, just like a space between two words within this leaf.
+     */
+    constructor(ast: TextAstNode, showWhitespace: boolean, leftWordBoundary?: boolean, rightWordBoundary?: boolean);
+}
+
+export declare class ThematicBreakAstNode extends AstNode {
+    readonly content: readonly (MarkerAstNode | GlueAstNode)[];
+    readonly kind = "thematicBreak";
+    constructor(content: readonly (MarkerAstNode | GlueAstNode)[]);
+    get children(): readonly AstNode[];
+    get marker(): MarkerAstNode | undefined;
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+}
+
+declare class ThematicBreakViewData {
+    readonly ast: ThematicBreakAstNode;
+    /** Active: reveal the source markup (`---`) instead of the rendered rule. */
+    readonly showMarkup: boolean;
+    /** Marker (and any absorbed trailing glue), rendered only when active. */
+    readonly content: readonly AnyViewData[];
+    readonly kind = "thematicBreak";
+    constructor(ast: ThematicBreakAstNode, 
+    /** Active: reveal the source markup (`---`) instead of the rendered rule. */
+    showMarkup: boolean, 
+    /** Marker (and any absorbed trailing glue), rendered only when active. */
+    content: readonly AnyViewData[]);
+}
+
+/**
+ * A coloured run of `length` characters. Tokens are *dense* and *offset-free*:
+ * a snapshot's tokens for a range cover it exactly, back to back, so
+ * `sum(token.length) === range.length`. A token never stores where it is — its
+ * position is implied by the lengths of the tokens before it, mirroring how the
+ * rest of the editor keeps source offsets out of its data structures.
+ */
+export declare class Token {
+    readonly length: number;
+    /** CSS class for this run, or `undefined` for an unstyled run. */
+    readonly className: string | undefined;
+    constructor(length: number, 
+    /** CSS class for this run, or `undefined` for an unstyled run. */
+    className: string | undefined);
+}
+
+/**
+ * Immutable view of an AST node. Pairs `ast` with its rendered `dom` and a
+ * mirror of `ast.children` as ViewNode children. Source offsets are NEVER
+ * stored — they are recomputed by walking and summing `ast.length` of
+ * preceding siblings, just like the AST itself.
+ *
+ * Leaves are ViewNodes with no children. A leaf whose `dom` is a Text node
+ * participates in source mapping; a leaf whose `dom` is an Element does not
+ * (e.g. KaTeX-rendered math, or `<hr>` for a thematic break).
+ */
+export declare class ViewNode extends Disposable {
+    readonly ast: AstNode;
+    readonly dom: globalThis.Node;
+    private _children;
+    constructor(ast: AstNode, dom: globalThis.Node, children?: readonly ViewNode[]);
+    /** This node's view children (a mirror of `ast.children`). */
+    get children(): readonly ViewNode[];
+    /**
+     * Replace this node's children in place, disposing the old ones and
+     * re-pointing the new ones' parent to this node. The node value is still
+     * conceptually immutable with respect to its `ast`/`dom` *identity*; this
+     * is used only when a node patches its own DOM subtree in place (a code
+     * block re-tokenising on a highlighter recolour), where the source-mapping
+     * leaves must follow the new DOM text nodes without rebuilding the node
+     * itself.
+     */
+    protected _replaceChildren(children: readonly ViewNode[]): void;
+    dispose(): void;
+    /**
+     * The number of source characters this node spans. Defaults to the length
+     * of its {@link ast}; a synthetic leaf that subdivides one ast node (a
+     * decorated-whitespace character, a code-block token span) shares that ast
+     * for identity but overrides this with the length of its own slice, so the
+     * renderer never has to fabricate an AST node just to carry a length.
+     */
+    get sourceLength(): number;
+    /**
+     * The DOM node a parent mounts for this child. It is {@link dom} for almost
+     * everything; a marker is the exception — its `dom` is the inner Text node
+     * (so source ↔ DOM mapping lands on it) while the node it mounts is the
+     * wrapping `<span>`.
+     */
+    get mountNode(): globalThis.Node;
+    /** The view node that rendered this node's parent, or `undefined` for a root. */
+    get parent(): ViewNode | undefined;
+    /**
+     * Closest view node owning `domNode`: the node itself if registered, else
+     * the nearest registered ancestor. Returns `undefined` if the DOM node is
+     * outside any view tree.
+     */
+    static forDom(domNode: globalThis.Node | null): ViewNode | undefined;
+    /**
+     * This node's start offset within its parent's local source space: the sum
+     * of the `ast.length` of the siblings before it. Polymorphic via
+     * {@link _localOffsetOfChild} so a parent whose children do not map
+     * linearly (e.g. it hides or reorders some) can override how its children
+     * are placed.
+     */
+    localOffsetInParent(): number;
+    /** Start offset of `child` within this node's local source space. */
+    protected _localOffsetOfChild(child: ViewNode): number;
+    /**
+     * Map a DOM hit that lands on THIS node's own representation into a source
+     * range in this node's local space `[0, ast.length)`. Polymorphic: a text
+     * leaf maps the caret offset 1:1; an element-only node (KaTeX math, `<hr>`,
+     * an image, a hidden marker) has no internal text mapping and snaps to its
+     * start by default — subclasses may override (e.g. to snap to the nearer
+     * edge by x).
+     */
+    getLocalSourceRange(pos: DomPosition): OffsetRange;
+    /**
+     * DOM hit (any node + offset within it) → source offset relative to THIS
+     * node, or `undefined` when the hit is outside this node's subtree. Enters
+     * the tree at the closest owning view node ({@link forDom}), maps the hit
+     * into that node's local space ({@link getLocalSourceRange}), then lifts the
+     * range up the parent chain — adding each node's {@link localOffsetInParent} —
+     * until it reaches this node.
+     */
+    resolveSource(pos: DomPosition): number | undefined;
+    /**
+     * Source offset → DOM position. `nodeOffset` is the absolute source
+     * offset of THIS node's start. Returns a position into a DOM Text node,
+     * descending into children based on accumulated lengths.
+     */
+    sourceToDom(localSourceOffset: number, nodeSourceOffset?: number): DomPosition | undefined;
+    /** Visit every text-bearing leaf in this subtree with its absolute offset. */
+    forEachTextLeaf(nodeOffset: number, visitor: (leaf: ViewNode, leafOffset: number) => void): void;
+}
+
+export declare type VisualCursorCommand = (ctx: VisualCursorCommandContext) => CursorMoveResult;
+
+export declare interface VisualCursorCommandContext extends CursorCommandContext {
+    readonly lineMap: VisualLineMap;
+    readonly desiredColumn: number | undefined;
+}
+
+export declare function visualizeAst(root: AstNode, source: string): AstVisualization;
+
+/**
+ * One visual line of rendered text: a horizontal band
+ * (`rect.top`..`rect.bottom`) split into one or more {@link VisualRun}s
+ * arranged left-to-right.
+ */
+export declare class VisualLine {
+    readonly rect: Rect2D;
+    readonly runs: readonly VisualRun[];
+    constructor(rect: Rect2D, runs: readonly VisualRun[]);
+    containsOffset(offset: SourceOffset): boolean;
+    /**
+     * How `offset` relates to this line's runs:
+     *   - `'covers'`: a run starts at or strictly contains the offset
+     *     (`start <= offset < endExclusive`) — the caret belongs on this line.
+     *   - `'end'`: the offset is only some run's trailing boundary
+     *     (`offset === endExclusive`) with no run covering it — a line-break
+     *     boundary the caret should leave for the next line.
+     *   - `'none'`: no run touches the offset.
+     */
+    offsetMembership(offset: SourceOffset): 'covers' | 'end' | 'none';
+    /**
+     * Min `|offset - r|` over offsets `r` in any of this line's runs. Used
+     * to pick the nearest line when no run actually covers the offset.
+     */
+    sourceDistanceTo(offset: SourceOffset): number;
+    /**
+     * x of the caret position before `offset` on this line. When `offset`
+     * is past all runs (trailing whitespace / blank line), returns the
+     * right edge of the last run; when before all runs, returns the left
+     * edge of the first run.
+     */
+    xAtOffset(offset: SourceOffset): number;
+    /**
+     * Snap `x` to the nearest offset on this line. If `x` falls inside a
+     * run, the offset is interpolated by character fraction; otherwise it
+     * snaps to the closer edge of the nearest run.
+     */
+    offsetAtX(x: number): SourceOffset;
+}
+
+/**
+ * Geometry of the rendered document, as a map from source offsets to 2D
+ * positions and back.
+ *
+ * Structure (top to bottom):
+ *
+ *     VisualLineMap   = ordered list of VisualLines
+ *     VisualLine      = a horizontal band [rect.top, rect.bottom) split
+ *                       into one or more VisualRuns
+ *     VisualRun       = a contiguous source range painted at a rectangle
+ *                       on the line
+ *
+ * Invariants:
+ *   - `lines[i].rect.bottom <= lines[i+1].rect.top + ε`
+ *   - For any offset `o` covered by some run on line `L`:
+ *       `xAtOffset(o)` is inside that run's horizontal range
+ *       `xAtOffset(o)` is inside `L.rect.left..L.rect.right`
+ *
+ * The "map" goes both ways:
+ *   - SourceOffset → (line, x) via {@link lineIndexOfOffset} + {@link xAtOffset}
+ *   - Point2D → SourceOffset       via {@link offsetAtPoint}
+ *
+ * Both directions are total but not bijective: many offsets at a line
+ * boundary map to the same `x`, and large areas of the document
+ * (padding, gaps) map onto the nearest offset on the nearest line.
+ *
+ * Rendering a caret rect from these primitives is a consumer concern:
+ *
+ *     const i = map.lineIndexOfOffset(o);
+ *     const caretRect = map.lineRect(i).withZeroWidthAt(map.xAtOffset(o));
+ */
+export declare class VisualLineMap {
+    readonly lines: readonly VisualLine[];
+    static readonly EMPTY: VisualLineMap;
+    static measure(blockViews: readonly {
+        readonly absoluteStart: number;
+        readonly viewNode: ViewNode;
+    }[]): VisualLineMap;
+    constructor(lines: readonly VisualLine[]);
+    get lineCount(): number;
+    get isEmpty(): boolean;
+    lineRect(lineIndex: number): Rect2D;
+    /**
+     * Line whose runs cover the offset, or the nearest line by source
+     * distance if no run covers it.
+     *
+     * An offset that is only a run's *trailing* boundary (`offset ===
+     * endExclusive`) — most notably the source offset just past a
+     * line-breaking `\n`, which a zero-width run reports as its end on the line
+     * it terminates — belongs to the START of the NEXT line instead. Preferring
+     * the line that actually *starts* the offset makes the caret advance past a
+     * newline to the next line rather than collapsing onto the previous line's
+     * end (which would render two distinct offsets at the same caret position).
+     * The first such trailing-boundary line is remembered as a fallback for the
+     * document's very last offset, where no later line starts it.
+     */
+    lineIndexOfOffset(offset: SourceOffset): number;
+    /**
+     * x of the caret position before `offset`, on the line returned by
+     * {@link lineIndexOfOffset}. Returns `0` when the map is empty.
+     */
+    xAtOffset(offset: SourceOffset): number;
+    /**
+     * Line whose vertical band contains `y`, clamped to the first/last
+     * line when `y` is outside the document.
+     */
+    lineIndexAtY(y: number): number;
+    /**
+     * Snap a 2D point to the nearest source offset. Uses `y` to pick a
+     * line, then `x` to pick an offset within it. Up/down navigation
+     * uses {@link offsetInLineAtX} directly to preserve desired column.
+     */
+    offsetAtPoint(point: Point2D): SourceOffset;
+    /** Snap `x` to the nearest offset on a specific line. */
+    offsetInLineAtX(lineIndex: number, x: number): SourceOffset;
+}
+
+/**
+ * One contiguous run of text painted on a single visual line.
+ *
+ * When constructed with a {@link VisualRunSource}, `xAtOffset` returns the
+ * pixel-exact x of the caret before character `offset` by measuring the
+ * prefix `[textNodeStart, textNodeStart + (offset - sourceStart))` with a
+ * DOM `Range`. Without a source it falls back to linear interpolation
+ * across `rect.width`.
+ */
+export declare class VisualRun {
+    readonly sourceRange: OffsetRange;
+    readonly rect: Rect2D;
+    readonly source?: VisualRunSource | undefined;
+    constructor(sourceRange: OffsetRange, rect: Rect2D, source?: VisualRunSource | undefined);
+    get sourceStart(): SourceOffset;
+    get sourceEndExclusive(): SourceOffset;
+    get sourceLength(): number;
+    containsOffset(offset: SourceOffset): boolean;
+    sourceDistanceTo(offset: SourceOffset): number;
+    xAtOffset(offset: SourceOffset): number;
+    offsetAtX(x: number): SourceOffset;
+}
+
+/**
+ * The DOM source of a {@link VisualRun}. When set, `xAtOffset` and
+ * `offsetAtX` measure exact glyph positions via `Range.getBoundingClientRect`
+ * instead of linear interpolation across the run's rect. This matters for
+ * proportional fonts where character widths differ a lot (e.g. `m` vs `i`)
+ * and a caret placed by interpolation lands several pixels inside the
+ * wrong character.
+ *
+ * Hand-built runs (tests) omit this; their `xAtOffset` falls back to
+ * linear interpolation.
+ */
+declare interface VisualRunSource {
+    readonly textNode: Text;
+    /** Offset within `textNode.data` corresponding to `sourceRange.start`. */
+    readonly textNodeStart: number;
+}
+
+export { }