@miliastry/quasar 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,4563 @@
+/**
+ * DocumentEngine — GreenNode (Immutable Syntax Tree)
+ *
+ * The Green Tree is IMMUTABLE. It never changes after creation.
+ * This is the "compiled" representation of the source text.
+ *
+ * Properties:
+ * - Fully immutable (readonly)
+ * - Contains only structural information (kind, text, children, widths)
+ * - **No absolute position** — see below
+ * - No parent references
+ * - No identity (IDs live in Red Tree)
+ * - Can be shared across document versions
+ * - Safe to cache
+ *
+ * ─── Why there is no `range` ────────────────────────────────────────────────
+ *
+ * A green node knows how WIDE it is, not WHERE it is. That is the whole point:
+ * the two `[color=#e8b04b]` runs in a gradient are the same structure, and if
+ * each carried its own offsets they could never be the same object. Measured on
+ * the reference document: 1736 nodes, but only 702 distinct structures — 59.6%
+ * of the tree is duplicate.
+ *
+ * Position is a property of a node's PLACE in a tree, so it lives on the red
+ * node, which is the thing that has a place. `RedNode.range` computes it once
+ * at construction by accumulating widths from the root and caches it, so
+ * consumers see exactly the same `{start, end}` they always did.
+ *
+ * This also makes incremental editing cheaper: text inserted before a subtree
+ * changes where it is, not what it is, so nothing about it needs rebuilding.
+ * `shiftGreen` — which used to deep-copy every following sibling to bump its
+ * offsets — no longer exists, because there is nothing left to shift.
+ *
+ * ─── Why `width` is derived and never passed ────────────────────────────────
+ *
+ * `width = leadingWidth + (children ? Σ child widths : ownWidth) + trailingWidth`
+ *
+ * The partition invariant of roadmap point 14 — every character owned exactly
+ * once — used to be a runtime check that a careless caller could violate. Now
+ * it is arithmetic the constructor performs, so a tree that does not partition
+ * its source cannot be built. `Syntax/partition.ts` still exists to verify the
+ * one thing this cannot: that the root's width matches the source length.
+ *
+ * Inspired by Roslyn's Green Tree and SwiftSyntax.
+ */
+declare class GreenNode {
+    /** Syntax kind — maps to TokenKind for leaves, NodeKind for internals */
+    readonly kind: string;
+    /** Raw text of this node (empty for internal nodes) */
+    readonly text: string;
+    /** Child nodes */
+    readonly children: readonly GreenNode[];
+    /** Total width of this node in characters, delimiters included */
+    readonly width: number;
+    /** Whether this is a leaf (token) or internal node */
+    readonly isLeaf: boolean;
+    /**
+     * Characters this node owns BEFORE its first child — its opening delimiter.
+     * For `[b]hola[/b]` that is the 3 characters of `[b]`.
+     *
+     * `declare` is load-bearing here for the same reason as `_hashCache` below:
+     * a plain field declaration would emit a `defineProperty` per construction.
+     */
+    readonly leadingWidth: number;
+    /** Characters this node owns AFTER its last child — its closing delimiter. */
+    readonly trailingWidth: number;
+    /**
+     * Memoized structural hash — computed on first access, never invalidated.
+     *
+     * `declare` is load-bearing: with `target: ES2022`, TypeScript defaults
+     * `useDefineForClassFields` to true, so a plain field declaration emits a
+     * per-construction `defineProperty`. Measured on a 19.6 KB document that
+     * cost 23% of the parse phase (0.583 ms → 0.718 ms) for a slot most nodes
+     * never read. `declare` emits nothing; the constructor assigns it directly,
+     * which keeps the object shape monomorphic without the field-init overhead.
+     */
+    private _hashCache;
+    /**
+     * @param ownWidth  Width of a childless node's own content: the length of a
+     *                  `text` token, or the 1-2 characters of a newline. Ignored
+     *                  when there are children, whose widths sum to the same
+     *                  thing. An empty element like `[b][/b]` passes 0 and gets
+     *                  its width from its two delimiters.
+     */
+    constructor(kind: string, text: string, children?: GreenNode[], leadingWidth?: number, trailingWidth?: number, ownWidth?: number);
+    /**
+     * Structural hash of this subtree: `(kind, text, widths, children hashes)`.
+     *
+     * Two subtrees that render identically at different offsets ARE structurally
+     * identical — that is the entire premise of structural sharing, and now that
+     * green nodes carry no position it is simply true rather than something the
+     * hash had to be careful to arrange.
+     *
+     * The widths ARE folded in: they are structure, not position. A `text` leaf
+     * of width 4 and one of width 5 are different nodes.
+     *
+     * Computed lazily: parsing paths that never intern pay nothing. Safe to
+     * memoize because a GreenNode is immutable once constructed.
+     */
+    get _hash(): number;
+    /** Get child at index */
+    childAt(index: number): GreenNode | undefined;
+    /** Find first child matching predicate */
+    findChild(predicate: (n: GreenNode) => boolean): GreenNode | undefined;
+    /** Count of direct children */
+    get childCount(): number;
+    /** Check if this node has a specific kind */
+    isKind(kind: string): boolean;
+    /**
+     * Offset of this node's first child, relative to this node's own start.
+     * Equal to `leadingWidth`; named for the places that read it as a position.
+     */
+    get innerOffset(): number;
+    /** Width of the span between this node's delimiters. */
+    get innerWidth(): number;
+    /** Walk all descendants in pre-order */
+    walk(visitor: (node: GreenNode, depth: number) => void | 'skip', depth?: number): void;
+    /**
+     * Walk all descendants in pre-order, with each node's absolute offset.
+     *
+     * The replacement for the walks that used to read `node.range`. Offsets are
+     * accumulated on the way down, which is the only place they exist.
+     */
+    walkWithOffset(visitor: (node: GreenNode, start: number, depth: number) => void | 'skip', start?: number, depth?: number): void;
+    /** Convert to a debug string */
+    toString(depth?: number, start?: number): string;
+    /** Get the source text for this node, given where it starts. */
+    getSourceText(source: string, start: number): string;
+}
+/**
+ * Build an internal node. Its width comes from its children plus its own
+ * delimiters — there is no way to declare a width that disagrees with them.
+ */
+declare function greenNode(kind: string, text: string, children?: GreenNode[], leadingWidth?: number, trailingWidth?: number, ownWidth?: number): GreenNode;
+/**
+ * Build a token. `width` defaults to the text's own length, which is right for
+ * every leaf whose text IS its source (`text` nodes). Leaves whose `text` holds
+ * something else — `spacing` and `empty_line` carry `''` but occupy 1-2
+ * characters, element nodes carry their attributes — must pass it.
+ */
+declare function greenLeaf(kind: string, text: string, width?: number): GreenNode;
+
+/**
+ * DocumentEngine — Token & Trivia Types
+ *
+ * Tokens are the output of the Lexer and input to the Parser.
+ * Trivia is whitespace, newlines, formatting that is preserved
+ * but not semantically meaningful — inspired by Roslyn.
+ */
+type TriviaKind = 'whitespace' | 'newline' | 'carriage_return' | 'comment' | 'line_continuation';
+interface Trivia {
+    kind: TriviaKind;
+    text: string;
+    range: Range;
+}
+interface Range {
+    start: number;
+    end: number;
+}
+type TokenKind = 'open_tag' | 'close_tag' | 'self_closing_tag' | 'text' | 'newline' | 'whitespace' | 'attribute_name' | 'attribute_value' | 'equals' | 'quote' | 'end_of_file' | 'error';
+interface Token {
+    kind: TokenKind;
+    text: string;
+    range: Range;
+    /** Tag name or attribute name if applicable */
+    name?: string;
+    /** Full raw tag text including brackets: [b], [/color], [*] */
+    tagText?: string;
+    /** Raw attribute string (everything between tag name and closing ]) */
+    attrs?: string;
+    /** Trivia attached BEFORE this token (whitespace, newlines) */
+    leadingTrivia: Trivia[];
+    /** Trivia attached AFTER this token */
+    trailingTrivia: Trivia[];
+}
+interface TokenStream {
+    /** Peek at the current token without consuming */
+    peek(): Token;
+    /** Consume and return the current token, advance */
+    advance(): Token;
+    /** Look ahead n tokens (0 = next) */
+    lookAhead(n: number): Token;
+    /** Whether we've consumed all tokens */
+    isEof(): boolean;
+    /** Get current position in the stream */
+    position(): number;
+    /** Reset to a position */
+    seek(pos: number): void;
+    /** Get all remaining tokens */
+    remaining(): Token[];
+    /** Get all tokens */
+    getAll(): Token[];
+}
+
+/**
+ * DocumentEngine — Diagnostic Types
+ *
+ * Diagnostics are messages attached to specific nodes or ranges
+ * in the document tree. Inspired by VSCode's diagnostic model.
+ */
+
+type DiagnosticSeverity = 'hint' | 'info' | 'warning' | 'error';
+type DiagnosticTag = 'unnecessary' | 'deprecated' | 'unused' | 'redundant';
+interface Diagnostic {
+    /** Machine-readable code (e.g. 'invalid-color', 'missing-close-tag') */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Severity level */
+    severity: DiagnosticSeverity;
+    /** Optional tags for additional categorization */
+    tags: DiagnosticTag[];
+    /** Source range in the original text */
+    range: Range | null;
+    /** Node ID this diagnostic is attached to */
+    nodeId: NodeId | null;
+    /** Node kind for context */
+    nodeKind: NodeKind | null;
+    /** Source of this diagnostic (built-in, plugin name, etc.) */
+    source: string;
+    /** Optional related information */
+    related?: DiagnosticRelatedInfo[];
+    /** Optional fix suggestions */
+    fixes?: DiagnosticFix[];
+}
+interface DiagnosticRelatedInfo {
+    message: string;
+    range: Range | null;
+    nodeId: NodeId | null;
+}
+interface DiagnosticFix {
+    description: string;
+    /** Whether this fix is automatic or requires user confirmation */
+    isAutomatic: boolean;
+    /** The operations to apply as a fix */
+    operations: FixOperation[];
+}
+type FixOperation = {
+    kind: 'replace_text';
+    range: Range;
+    newText: string;
+} | {
+    kind: 'insert_text';
+    position: number;
+    text: string;
+} | {
+    kind: 'delete_range';
+    range: Range;
+} | {
+    kind: 'wrap_in_tag';
+    tagName: string;
+    range: Range;
+};
+interface DiagnosticCollection {
+    /** All diagnostics */
+    items: Diagnostic[];
+    /** Count by severity */
+    errorCount: number;
+    warningCount: number;
+    infoCount: number;
+    hintCount: number;
+    /** Quick access: only errors */
+    errors: Diagnostic[];
+    /** Quick access: only warnings */
+    warnings: Diagnostic[];
+}
+
+/**
+ * DocumentEngine — Core Types
+ *
+ * The foundational types for the entire Language Platform.
+ * Every layer builds on these.
+ */
+
+/** Stable identifier that survives incremental re-parses */
+type NodeId = string & {
+    readonly __brand: 'NodeId';
+};
+/**
+ * The semantic kind of a node in the document tree.
+ *
+ * Language-agnostic at the core — BBCode tags, Markdown headings,
+ * HTML elements, etc. all map to these.
+ */
+type NodeKind = 'document' | 'paragraph' | 'text' | 'bold' | 'italic' | 'underline' | 'strikethrough' | 'color' | 'font_size' | 'font' | 'code' | 'inline_code' | 'spoiler' | 'heading' | 'center' | 'right' | 'left' | 'url' | 'email' | 'profile' | 'image' | 'video' | 'audio' | 'imagemap' | 'imagemap_area' | 'svg' | 'quote' | 'notice' | 'spoilerbox' | 'box' | 'boxw' | 'list' | 'list_item' | 'zalgo' | 'aesthetic' | 'sparkle' | 'bubble' | 'flower' | 'gradient' | 'grow' | 'sinewave' | 'rainbow' | 'spacing' | 'empty_line' | 'group' | 'wnotice' | 'align' | 'tables' | 'table_row' | 'table_col' | 'table_th' | 'gallery' | 'columns' | 'separator' | 'scroll' | 'sup' | 'sub' | 'abbr' | 'mark' | 'kbd' | 'tooltip' | 'flip' | 'raw' | 'plain' | 'effect' | 'anim' | 'container' | 'style_tag' | 'guild' | 'map' | 'custom' | 'error' | 'unknown';
+type NodeAttributes = Record<string, string | number | boolean | null | undefined>;
+interface NodeMetadata {
+    /** Arbitrary extensions data (plugins can add here) */
+    [key: string]: unknown;
+}
+interface SourceRange {
+    start: number;
+    end: number;
+}
+/**
+ * The primary user-facing node in the Document Model.
+ *
+ * This is the Red Tree node — mutable, with identity.
+ * It wraps/holds reference to the Green Tree node for structural info.
+ */
+interface DocumentNode {
+    /** Stable ID that survives incremental re-parses */
+    id: NodeId;
+    /** Monotonically increasing version number for change tracking */
+    version: number;
+    /** Semantic kind */
+    kind: NodeKind;
+    /** Raw text content (for text leaves) */
+    text: string;
+    /** Tag-level attributes (e.g. color=#ff0000, size=150) */
+    attributes: NodeAttributes;
+    /** Arbitrary metadata (extensible by plugins) */
+    metadata: NodeMetadata;
+    /** Child nodes */
+    children: DocumentNode[];
+    /** Diagnostics attached to this specific node */
+    diagnostics: Diagnostic[];
+    /** Source position in the original text (for mapping back) */
+    sourceRange: SourceRange | null;
+    /** Reference back to parent (null for root) */
+    parentId: NodeId | null;
+    /** Whether this node is "synthetic" (not from source, e.g. auto-generated) */
+    isSynthetic: boolean;
+}
+type DocumentChangeKind = 'node_inserted' | 'node_deleted' | 'node_updated' | 'node_moved' | 'attribute_changed' | 'text_changed' | 'source_changed' | 'full_rebuild';
+interface DocumentChangeEvent {
+    kind: DocumentChangeKind;
+    nodeId: NodeId;
+    /** The affected node (after the change) */
+    node: DocumentNode | null;
+    /** Previous version of the node (before the change) */
+    previousNode: DocumentNode | null;
+    /** Additional context data */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * DocumentEngine — RedNode (Mutable Syntax Tree)
+ *
+ * The Red Tree wraps GreenNode and adds mutable state:
+ * - Parent references
+ * - Stable Node IDs
+ * - Version tracking
+ * - Diagnostic storage
+ *
+ * Multiple Red Trees can reference the same Green Tree
+ * (different views, different versions of edits).
+ *
+ * Inspired by Roslyn's Red Tree.
+ */
+
+declare class RedNode {
+    /** The underlying immutable green node */
+    readonly green: GreenNode;
+    /** Stable identity */
+    readonly id: NodeId;
+    /** Parent reference (null for root) */
+    parent: RedNode | null;
+    /** Children as red nodes */
+    children: RedNode[];
+    /** Version counter for change tracking */
+    version: number;
+    /** Diagnostics for this node */
+    diagnostics: Diagnostic[];
+    /** The semantic kind */
+    kind: NodeKind;
+    /** Additional metadata */
+    metadata: NodeMetadata;
+    /**
+     * Cached position of this node inside `parent.children`.
+     *
+     * `declare` is load-bearing — see the note on `GreenNode._hashCache`: with
+     * `target: ES2022` a plain field declaration emits a `defineProperty` on every
+     * construction, and this class is instantiated once per node per parse.
+     *
+     * The cache is *self-validating*: `index` only trusts it when
+     * `parent.children[_idxCache] === this`. That single reference compare is what
+     * makes it safe against code that mutates the `children` array directly
+     * (`treeTransformers` does `cloned.children = []`) instead of going through the
+     * mutation methods — a stale entry is detected and recomputed rather than
+     * silently returning a wrong index. `-1` never validates, so it is a safe
+     * initial value.
+     */
+    private _idxCache;
+    /**
+     * Absolute start offset in the source.
+     *
+     * This is the red tree's job now: a green node knows its width, not its
+     * place, so that identical structures can be the same object (see the header
+     * of `GreenNode.ts`). The offset is accumulated on the way down during
+     * construction — one addition per node — and stored, so `range` stays the
+     * O(1) property every consumer already assumes it is.
+     *
+     * Held as the `Range` object itself rather than a number plus a getter that
+     * builds one: `range` is read from 148 call sites, and allocating there would
+     * trade a parse-time win for a read-time cost on every consumer. This is the
+     * same shape green nodes used to hold, so nothing downstream changes.
+     *
+     * `declare` for the usual reason: no `defineProperty` per construction.
+     */
+    private _range;
+    /**
+     * Pending offset shift for this subtree, applied on first read.
+     *
+     * `setStart` defers the walk: it records how far the subtree moved instead of
+     * adding the delta to every node's `_range` on the spot. The shift is a single
+     * integer here, on the adopted subtree ROOT — the node `setStart` was called
+     * on. Any offset read (`range`, `innerStart`, `innerEnd`, `findNodeAtOffset`)
+     * materializes the nearest pending ancestor's subtree via {@link materialize}.
+     *
+     * Why this is sound: a mid-document edit displaces every adopted block after
+     * it by the same delta, so adoption alone (thousands of `setStart` calls) was
+     * walking thousands of nodes per keystroke — measured as the dominant phase
+     * of `buildRed` (3.5-5.8 ms on the 547 KB fixture). The BlockPatcher locates
+     * the edited window by reference identity and only ever reads the few changed
+     * blocks' ranges, so the displaced-but-unchanged subtrees stay pending
+     * indefinitely — the walk never happens.
+     *
+     * Contract for future readers: app-layer interaction code (hover, links,
+     * selection ranges) DOES read `range` on user interaction. The first such
+     * read after a mid-document edit fires the deferred walk for the displaced
+     * tail — a one-time cost off the keystroke path, which is exactly the trade
+     * the laziness makes. Do not "optimize" by reading ranges back into the
+     * per-keystroke pipeline; the patcher stays churn-based by design.
+     *
+     * Composition across reparses: a node re-adopted while its ancestor is still
+     * pending must end up at the SUM of both deltas. `setStart` recomputes the
+     * delta from the untouched base `_range`, which is exactly the pending
+     * ancestor's base too, so composing during `materialize` (add the ancestor's
+     * delta into a child's pending delta) stays consistent.
+     */
+    private _lazyShift;
+    constructor(green: GreenNode, options?: {
+        id?: NodeId;
+        parent?: RedNode | null;
+        kind?: NodeKind;
+        diagnostics?: Diagnostic[];
+        metadata?: NodeMetadata;
+        /** Absolute start offset. Defaults to the parent's inner offset. */
+        start?: number;
+    });
+    /**
+     * Move this node (and its subtree) to a new absolute offset.
+     *
+     * Only for the tree-building paths, which create a node before they know
+     * where its parent will put it. Callers that mutate a live tree should
+     * rebuild instead — a red node's offset must always agree with its place.
+     *
+     * The move is deferred, not walked: the delta is recorded as a pending
+     * shift and applied by any offset read the first time the subtree is
+     * actually touched. Adoption calls this once per displaced block (thousands
+     * on a mid-document edit), and almost none of those subtrees are read on the
+     * same keystroke's hot path — the BlockPatcher locates the edit window by
+     * reference identity and only reads the few changed blocks.
+     *
+     * Re-adoption composes: a node whose subtree was shifted in a previous
+     * reparse and never read still carries a pending `_lazyShift`. The new
+     * target is absolute, so the delta is measured from the CURRENT effective
+     * start (`_range.start + _lazyShift`) and accumulated, not overwritten —
+     * otherwise the earlier shift would be applied twice.
+     */
+    setStart(start: number): void;
+    /**
+     * Apply `delta` to `node`'s subtree, composing with any nested pending shift.
+     *
+     * A node with its own pending shift has a base `_range` the parent's delta is
+     * relative to as well (both were computed from the same pre-shift tree), so
+     * the parent's delta can be folded into the child's pending delta instead of
+     * into its `_range` — the child's later materialization applies the sum. This
+     * is what makes nested shifts across reparses compose without double counting.
+     */
+    private static applyShift;
+    /**
+     * Materialize every pending shift on the path from here to the root.
+     *
+     * Walks ancestors top-down (root-most first), applying each pending delta to
+     * its subtree. Top-down order matters: an ancestor's delta must land in a
+     * child's pending delta BEFORE the child's own materialization runs, or the
+     * two shifts would be applied to different bases. After the ancestors are
+     * settled, this node itself is materialized if it still carries a shift.
+     *
+     * The common case — nothing pending anywhere on the path — is one upward
+     * pointer walk that allocates nothing: `_range` is read from 148 call sites,
+     * and a per-read allocation there would show up in every phase. The chain
+     * array is only built after a pending shift is actually found.
+     */
+    private materialize;
+    private static _isMutating;
+    /**
+     * Run `fn` inside a mutation boundary, so the structural mutators below are
+     * allowed to run. Nests safely; the previous state is restored on exit.
+     *
+     * Not needed for building a fresh subtree — see {@link initChildren}.
+     */
+    static allowMutation<T>(fn: () => T): T;
+    private assertMutating;
+    get text(): string;
+    /** Absolute span in the source. */
+    get range(): Range;
+    /** Absolute offset of this node's first child, past its opening delimiter. */
+    get innerStart(): number;
+    /** Absolute offset where this node's closing delimiter begins. */
+    get innerEnd(): number;
+    get isLeaf(): boolean;
+    get childCount(): number;
+    childAt(index: number): RedNode | undefined;
+    /** Get the root of the tree */
+    get root(): RedNode;
+    /** Get the depth from root */
+    get depth(): number;
+    /** Get previous sibling */
+    get previousSibling(): RedNode | null;
+    /** Get next sibling */
+    get nextSibling(): RedNode | null;
+    /**
+     * Position of this node within its parent, or -1 for a root.
+     *
+     * O(1) in the steady state. The cached index is seeded by the mutation methods
+     * (so the construction path never searches at all) and verified by a single
+     * reference compare on read, falling back to `indexOf` only when it is stale.
+     *
+     * This getter is hot: `HTMLRenderer.isPrevBlockBoundary` walks siblings
+     * backwards, so an O(n) implementation here made rendering quadratic —
+     * measured 14.11 ms for 4000 root siblings, growing 2.6x per doubling.
+     */
+    get index(): number;
+    /** Walk all descendants in pre-order */
+    walk(visitor: (node: RedNode, depth: number) => void | 'skip', depth?: number): void;
+    /** Find a descendant by ID */
+    findById(id: NodeId): RedNode | null;
+    /**
+     * Find the deepest RedNode containing the given text offset.
+     *
+     * The range is half-open — a node owns `[start, end)` — y eso no es un
+     * detalle: con el final inclusivo, un offset que cae justo en una frontera
+     * pertenecía a DOS nodos, al que termina ahí y al que empieza. Como los
+     * hijos se recorren en orden, ganaba el que termina, así que preguntar por
+     * el principio de un nodo devolvía **el nodo anterior**.
+     *
+     * Se veía en el preview: en un degradado, cada carácter es su propio nodo
+     * de color, y hacer clic en la `m` de «Welcome» resaltaba la `o`. Monaco
+     * seleccionaba bien —usa el rango del nodo, no esta búsqueda—, así que el
+     * desfase era solo del resaltado, que es justo lo que hacía difícil verlo.
+     *
+     * La única excepción es el final del documento: un cursor aparcado tras el
+     * último carácter no tiene carácter que lo contenga, y la raíz lo reclama
+     * para que quien pregunte reciba algo con sentido.
+     */
+    findNodeAtOffset(offset: number): RedNode | null;
+    /**
+     * Adopt a fully-built array of children in one shot.
+     *
+     * Construction-only, and deliberately outside the mutation lock. The tree
+     * builders used to call `allowMutation(() => { for (…) appendChild(…) })` once
+     * **per node**, which on a 1736-node document meant 1736 closures, 1736
+     * `try/finally` frames and 1736 static-flag saves — pure ceremony, since a
+     * node that no caller has seen yet cannot be observed mid-mutation. This
+     * populates `children`, `parent` and the index cache in a single pass instead.
+     *
+     * `version` intentionally stays at 1: a freshly built node has not been
+     * *edited*, and bumping once per child would make the initial version an
+     * accidental child count.
+     *
+     * Only safe while `this` is still unreachable from the rest of the tree. Use
+     * `appendChild` and friends for anything after that.
+     */
+    initChildren(children: RedNode[]): void;
+    /**
+     * Append a child node.
+     * This creates a new RedNode wrapping the green node.
+     */
+    appendChild(child: RedNode): void;
+    /**
+     * Refresh the cached index of every child from `from` onwards.
+     *
+     * Called after a splice, which shifts the tail. This is O(n) but so is the
+     * splice it follows, so it costs nothing asymptotically and keeps reads O(1).
+     */
+    private reindexFrom;
+    /**
+     * Insert a child at a specific index.
+     */
+    insertChildAt(index: number, child: RedNode): void;
+    /**
+     * Remove a child by ID.
+     */
+    removeChild(id: NodeId): RedNode | null;
+    /**
+     * Replace a child with a new one by ID.
+     */
+    replaceChild(id: NodeId, newChild: RedNode): boolean;
+    /**
+     * Bump version (when attributes/metadata change without structural change).
+     */
+    bumpVersion(): void;
+    /** Convert to the public DocumentNode interface */
+    toDocumentNode(): DocumentNode;
+    /** Debug string */
+    toString(depth?: number): string;
+}
+
+/**
+ * DocumentEngine — NodeMatcher
+ *
+ * Matches nodes between old and new syntax trees after edits.
+ * Uses stable IDs, fingerprints, and source ranges to determine
+ * which nodes were moved, inserted, deleted, or unchanged.
+ *
+ * Critical for:
+ * - Maintaining selection across re-parses
+ * - Preserving scroll position
+ * - Smooth animations in visual blocks mode
+ * - Undo/redo integrity
+ */
+
+type MatchStatus = 'exact' | 'moved' | 'updated' | 'inserted' | 'deleted' | 'merged' | 'split';
+interface MatchResult {
+    oldNode: RedNode | null;
+    newNode: RedNode | null;
+    status: MatchStatus;
+    confidence: number;
+}
+interface NodeMatch {
+    /** Map from old node ID to new node */
+    oldToNew: Map<NodeId, RedNode>;
+    /** Map from new node ID to old node */
+    newToOld: Map<NodeId, RedNode>;
+    /** All matches */
+    matches: MatchResult[];
+    /** Statistics */
+    stats: {
+        exact: number;
+        moved: number;
+        updated: number;
+        inserted: number;
+        deleted: number;
+    };
+}
+declare class NodeMatcher {
+    /**
+     * Match nodes between old and new trees.
+     *
+     * Strategy (in order):
+     * 1. Match by stable ID (if present)
+     * 2. Match by fingerprint (content hash)
+     * 3. Match by source range overlap
+     * 4. Fall back to positional heuristic
+     */
+    match(oldRoot: RedNode, newRoot: RedNode): NodeMatch;
+    /**
+     * Phase 0 — descend in lockstep, pairing every subtree that did not change.
+     *
+     * At each level the common prefix and common suffix are trimmed by comparing
+     * `green._hash`, and only the window between them is descended into. That is
+     * what makes this robust to an edit that changes the number of children:
+     * requiring equal child counts before recursing sounds reasonable but means a
+     * single inserted node near the root disables the fast path for the whole
+     * tree — measured, it left `match` at 5.11 ms instead of 0.96 ms.
+     *
+     * Whatever is left in the middle window is handed to the fingerprint
+     * heuristic, which is the part that can cope with reordering.
+     */
+    private pairUnchanged;
+    /**
+     * Compute a content fingerprint for a node's subtree.
+     *
+     * Two nodes share a fingerprint iff their subtrees have the same pre-order
+     * sequence of (kind, text) pairs — the same equivalence the previous
+     * string-concatenating implementation tested, but as a 64-bit structural
+     * hash instead of an O(subtree) string built on every comparison.
+     */
+    fingerprint(node: RedNode): string;
+    /** Memoized, bottom-up fingerprint. O(n) across a whole tree. */
+    private fingerprintInto;
+}
+
+/**
+ * DocumentEngine — ChangeTracker
+ *
+ * Tracks text changes made to the document source.
+ * Used by IncrementalParser to determine what needs to be re-parsed.
+ */
+interface TextChange {
+    start: number;
+    end: number;
+    text: string;
+}
+/**
+ * Source range of a text edit, in BOTH coordinate systems.
+ *
+ * An edit sits between two documents: `start`/`end` describe the changed
+ * region in NEW-source coordinates (the current document), while `endOld` is
+ * the end of the replaced region in OLD-source coordinates. The incremental
+ * preview (`BlockPatcher`) uses `start`/`endOld` to locate the affected blocks
+ * in the PREVIOUS tree (whose offsets are pre-edit) and `start`/`end` in the
+ * new one — insertions or deletions between the two make the naive single-`end`
+ * wrong, which is exactly why both ends are kept.
+ */
+interface TextChangeRange {
+    /** Start of the edited region (identical in both coordinate systems). */
+    start: number;
+    /** End of the edited region, in new-source coordinates. */
+    end: number;
+    /** End of the replaced region, in old-source coordinates. */
+    endOld: number;
+}
+interface TextChangeStats {
+    totalChanges: number;
+    totalInserted: number;
+    totalDeleted: number;
+    lastChange: TextChange | null;
+}
+declare class ChangeTracker {
+    private changes;
+    private maxHistory;
+    constructor(maxHistory?: number);
+    /**
+     * Track a text change.
+     */
+    track(change: TextChange): void;
+    /**
+     * Get all tracked changes.
+     */
+    getAll(): TextChange[];
+    /**
+     * Get the most recent change.
+     */
+    getLast(): TextChange | null;
+    /**
+     * Get the affected range for the last N changes.
+     * Returns null if no changes have been tracked.
+     */
+    getAffectedRange(count?: number): {
+        start: number;
+        end: number;
+    } | null;
+    /**
+     * Clear change history.
+     */
+    clear(): void;
+    /**
+     * Get statistics about tracked changes.
+     */
+    getStats(): TextChangeStats;
+}
+
+/**
+ * DocumentEngine — IncrementalParser
+ *
+ * Re-parses the smallest region a text change can have affected, instead of
+ * the whole document.
+ *
+ * ─── Why this was rewritten (roadmap S5 / point 9) ──────────────────────────
+ *
+ * The previous implementation spliced RED nodes in place and never touched
+ * ranges. Three consequences, all measured:
+ *
+ *  - The re-parsed subtree came from `newSource.slice(start, end)`, so its
+ *    ranges were based at 0 and were grafted in without rebasing. Every offset
+ *    inside the edited region was wrong by `start`.
+ *  - Siblings after the splice and every ancestor kept their old ranges, so
+ *    the tree silently disagreed with the text it claimed to describe.
+ *  - It returned `newRootRed.green` — the OLD green root — so the model's
+ *    `_greenRoot` and `_redRoot` desynchronised permanently after the first
+ *    incremental edit.
+ *
+ * Rendering the result and comparing it against a full rebuild of the same
+ * final text: 3 of 6 realistic editing scenarios produced DIFFERENT HTML, and
+ * one grew 14 phantom nodes (1752 vs 1738).
+ *
+ * ─── How it works now ───────────────────────────────────────────────────────
+ *
+ * Everything happens on the GREEN tree, and the red tree is derived from it.
+ * That is not a stylistic choice: green nodes carry widths and no position, so
+ * a position is something only a red node has — and therefore only a red node
+ * can be wrong about.
+ *
+ *   1. Descend to the deepest node whose inner span (the part between its
+ *      delimiters) contains the change, refusing to enter the kinds whose
+ *      children depend on context outside them (see `OPAQUE_KINDS`).
+ *   2. Take the run of that node's children the change touches, widened by one
+ *      on each side, and re-parse just those.
+ *   3. Splice the result back over that run and rebuild the ancestor spine,
+ *      sharing every untouched subtree by reference.
+ *
+ * The unit is a RUN OF SIBLINGS, not a whole node. Re-parsing a container's
+ * entire contents because one character changed inside it meant typing into a
+ * 13 KB `[notice]` re-lexed 66% of the document per keystroke — and an edit at
+ * document level had no enclosing container at all, so it fell back to a full
+ * rebuild, which is exactly where the caret sits while you write the end of a
+ * post.
+ *
+ * Step 1 relies on the partition invariant from point 14: without it, "the
+ * part between the delimiters" is not a well-defined range, which is exactly
+ * why this repair was blocked on that work.
+ *
+ * When any precondition fails the parser returns a full rebuild rather than a
+ * plausible-looking wrong tree. `path` says which happened, `reason` says why.
+ */
+
+interface EditOperation {
+    kind: 'insert' | 'delete' | 'replace';
+    start: number;
+    end: number;
+    text: string;
+    /** The minimal range that needs re-parsing */
+    affectedStart: number;
+    affectedEnd: number;
+}
+/** Options a caller's parse callback must understand. */
+interface ReparseParseOptions {
+    /**
+     * Whether the text being parsed is document-level content. Inner spans of
+     * containers are not, and must not be grouped into paragraphs.
+     */
+    normalizeParagraphs: boolean;
+}
+interface ReparseResult {
+    green: GreenNode;
+    red: RedNode;
+    /** Nodes that were affected by the change */
+    affectedNodes: RedNode[];
+    /** Time taken in ms (total) */
+    duration: number;
+    /** Per-phase timing breakdown in ms */
+    timings: {
+        findAffected: number;
+        safeBoundary: number;
+        parse: number;
+        buildRed: number;
+        mutate: number;
+        other: number;
+    };
+    /** Which path was used */
+    path: 'incremental' | 'full_rebuild';
+    /** When `full_rebuild`, why the incremental path was declined. */
+    reason?: FallbackReason;
+}
+type FallbackReason = 
+/** No sibling window could be formed around the change. */
+'no-window'
+/** The change touches a container's own delimiter. */
+ | 'touches-delimiter'
+/** The region cannot be lexed in isolation — see `regionIsSelfContained`. */
+ | 'region-not-isolated'
+/** An unclosed `[` before the region could claim a `]` the edit creates. */
+ | 'open-bracket-before'
+/** The container covers so much of the document that a rebuild is cheaper. */
+ | 'region-too-large'
+/** The document is small enough that rebuilding it outright costs less. */
+ | 'document-too-small'
+/** The tree's ranges disagree with the source it is supposed to describe. */
+ | 'stale-ranges';
+interface IncrementalParserOptions {
+    /** Override `MIN_SOURCE_LENGTH`. Set to 0 to always attempt a splice. */
+    minSourceLength?: number;
+    /** Override `MAX_REGION_FRACTION`. */
+    maxRegionFraction?: number;
+}
+declare class IncrementalParser {
+    private readonly minSourceLength;
+    private readonly maxRegionFraction;
+    /**
+     * The thresholds are constructor options because they are performance
+     * tuning, not semantics: the tree that comes out is the same either way, so
+     * a caller with a different document profile — or a test that wants to
+     * exercise the splice on a two-line document — can move them without
+     * changing what the parser means.
+     */
+    constructor(options?: IncrementalParserOptions);
+    /**
+     * Reparse a tree after a text change.
+     *
+     * Always returns a result — either an incremental splice or a full rebuild.
+     * It never returns a tree whose ranges do not describe `newSource`.
+     */
+    reparse(oldRed: RedNode, oldGreen: GreenNode, change: TextChange, newSource: string, parseCallback: (text: string, options?: ReparseParseOptions) => GreenNode, buildRedCallback: (green: GreenNode) => RedNode): ReparseResult;
+    /**
+     * Find the run of sibling children a change can have affected.
+     *
+     * Two steps. First descend to the deepest node whose INNER span contains the
+     * change — inner rather than full, so a container's own delimiters never go
+     * back through the parser: an edit that touches `[colo|r=red]` changes what
+     * that element IS, and is handled by re-parsing it as part of its parent's
+     * window instead.
+     *
+     * Then pick the children that the change touches, widened by one on each
+     * side. The widening is what lets a deletion MERGE two nodes: removing the
+     * blank line between two paragraphs changes only the node in between, and
+     * without a neighbour on each side the re-parse could not see that the two
+     * survivors have to become one.
+     */
+    private findReparseWindow;
+    /**
+     * Nodes on the path from the root down to the change.
+     *
+     * Kept because it is part of the public surface and is genuinely useful for
+     * callers that want to know what an edit touched; the reparse itself no
+     * longer needs it.
+     */
+    findAffectedNodes(root: RedNode, change: TextChange): RedNode[];
+}
+
+/**
+ * DocumentEngine — SemanticAnalyzer
+ *
+ * Walks the Red Tree and produces diagnostics by applying
+ * semantic rules to the syntax tree.
+ *
+ * This is where language-specific validation happens.
+ * The analyzer is extensible via registered validators.
+ *
+ * Inspired by Roslyn's Semantic Model and LSP diagnostics.
+ */
+
+interface Validator {
+    /** Unique code for this validator (e.g. 'invalid-color') */
+    code: string;
+    /** Severity of issues found by this validator */
+    severity: DiagnosticSeverity;
+    /**
+     * Node kinds this validator can ever fire on. Omit to run on every node.
+     *
+     * Three of the five built-ins open with nothing but a kind test, so on a
+     * document of 1736 nodes they were called 1736 times each to answer a
+     * question the dispatcher can answer once. Declaring the kinds turns the
+     * call into a lookup that never happens.
+     */
+    kinds?: readonly string[];
+    /** Validate a node. Return diagnostics or null */
+    validate(node: RedNode, context: AnalyzerContext): Diagnostic | Diagnostic[] | null;
+}
+interface AnalyzerContext {
+    /**
+     * Every node in the tree, by id, for cross-reference validation.
+     *
+     * A getter, and deliberately: building this Map cost a second full walk of
+     * the tree plus 1736 `Map.set` calls — 23% of `analyze()` — and **no
+     * validator has ever read it**. It was built so that the caller could look up
+     * by id the node to attach each diagnostic to, which is the node the
+     * validator was looking at when it produced it. Validators that genuinely
+     * need cross-references still get it; everyone else stops paying for it.
+     */
+    readonly allNodes: Map<string, RedNode>;
+    /** Previously collected diagnostics */
+    diagnostics: DiagnosticCollection;
+    /** Source text for position lookups */
+    source: string;
+}
+interface AnalyzeResult {
+    diagnostics: DiagnosticCollection;
+    /** Time taken in ms */
+    duration: number;
+    /** Number of nodes analyzed */
+    nodesAnalyzed: number;
+}
+/**
+ * What `analyze()` actually returns: an {@link AnalyzeResult} plus the node
+ * index it had to build anyway for cross-reference lookups.
+ *
+ * Kept as a separate type, and deliberately NOT part of `AnalyzeResult`,
+ * because the index holds a strong reference to every node in the tree. A
+ * caller that stores an `AnalyzeResult` long-term (as `DocumentModel` does)
+ * must not pin an entire stale tree; one that needs the index gets it here and
+ * owns that decision explicitly.
+ */
+interface IndexedAnalyzeResult extends AnalyzeResult {
+    allNodes: Map<string, RedNode>;
+}
+declare class SemanticAnalyzer {
+    private validators;
+    /**
+     * The same validators, arranged for the walk instead of for lookup.
+     *
+     * `_always` run on every node; `_byKind` are the ones that declared their
+     * kinds. Iterating the Map itself allocated an iterator and a destructuring
+     * pair per node — 9% of `analyze()` spent on bookkeeping, not on validating.
+     *
+     * Rebuilt on register/unregister, which happen once at construction and
+     * essentially never afterwards.
+     */
+    private _always;
+    private _byKind;
+    constructor();
+    /**
+     * Register a validator.
+     */
+    register(validator: Validator): void;
+    /**
+     * Remove a validator.
+     */
+    unregister(code: string): void;
+    private rebuildDispatch;
+    /**
+     * Analyze a Red Tree and produce diagnostics.
+     */
+    analyze(root: RedNode, source: string): IndexedAnalyzeResult;
+    private registerBuiltinValidators;
+    /**
+     * Create a validator for a specific tag/kind.
+     * Convenience method for plugin authors.
+     */
+    createValidator(code: string, severity: DiagnosticSeverity, predicate: (node: RedNode, ctx: AnalyzerContext) => string | null): Validator;
+}
+
+/**
+ * DocumentEngine — Operation & Transaction Types
+ *
+ * Operations are the atomic units of change in the document.
+ * Every modification goes through operations, never direct mutation.
+ *
+ * Inspired by ProseMirror and Roslyn.
+ */
+
+type OperationKind = 'insert_node' | 'delete_node' | 'replace_node' | 'move_node' | 'update_attributes' | 'set_text' | 'insert_text' | 'delete_text' | 'replace_text' | 'wrap_in_tag' | 'unwrap_node' | 'split_node' | 'merge_nodes';
+interface BaseOperation {
+    kind: OperationKind;
+    /** Stable ID for the operation (for undo/redo pairing) */
+    id: string;
+    /** Whether this operation can be undone */
+    undoable: boolean;
+    /** Timestamp */
+    timestamp: number;
+}
+interface InsertNodeOperation extends BaseOperation {
+    kind: 'insert_node';
+    parentId: NodeId;
+    index: number;
+    node: RedNode;
+}
+interface DeleteNodeOperation extends BaseOperation {
+    kind: 'delete_node';
+    nodeId: NodeId;
+    /** The deleted node (stored for undo) */
+    node: RedNode;
+    parentId: NodeId;
+    index: number;
+}
+interface ReplaceNodeOperation extends BaseOperation {
+    kind: 'replace_node';
+    nodeId: NodeId;
+    newNode: RedNode;
+    oldNode: RedNode;
+}
+interface MoveNodeOperation extends BaseOperation {
+    kind: 'move_node';
+    nodeId: NodeId;
+    fromParentId: NodeId;
+    fromIndex: number;
+    toParentId: NodeId;
+    toIndex: number;
+}
+interface UpdateAttributesOperation extends BaseOperation {
+    kind: 'update_attributes';
+    nodeId: NodeId;
+    newAttributes: NodeAttributes;
+    oldAttributes: NodeAttributes;
+}
+interface SetTextOperation extends BaseOperation {
+    kind: 'set_text';
+    nodeId: NodeId;
+    newText: string;
+    oldText: string;
+}
+interface InsertTextOperation extends BaseOperation {
+    kind: 'insert_text';
+    nodeId: NodeId;
+    position: number;
+    text: string;
+}
+interface DeleteTextOperation extends BaseOperation {
+    kind: 'delete_text';
+    nodeId: NodeId;
+    position: number;
+    length: number;
+    text: string;
+}
+interface ReplaceTextOperation extends BaseOperation {
+    kind: 'replace_text';
+    nodeId: NodeId;
+    position: number;
+    length: number;
+    newText: string;
+    oldText: string;
+}
+interface WrapInTagOperation extends BaseOperation {
+    kind: 'wrap_in_tag';
+    nodeId: NodeId;
+    tagName: string;
+    attributes: NodeAttributes;
+}
+interface UnwrapNodeOperation extends BaseOperation {
+    kind: 'unwrap_node';
+    nodeId: NodeId;
+    parentId: NodeId;
+    children: RedNode[];
+}
+interface SplitNodeOperation extends BaseOperation {
+    kind: 'split_node';
+    nodeId: NodeId;
+    position: number;
+    leftNode: RedNode;
+    rightNode: RedNode;
+}
+interface MergeNodesOperation extends BaseOperation {
+    kind: 'merge_nodes';
+    leftNodeId: NodeId;
+    rightNodeId: NodeId;
+    mergedNode: RedNode;
+}
+type Operation = InsertNodeOperation | DeleteNodeOperation | ReplaceNodeOperation | MoveNodeOperation | UpdateAttributesOperation | SetTextOperation | InsertTextOperation | DeleteTextOperation | ReplaceTextOperation | WrapInTagOperation | UnwrapNodeOperation | SplitNodeOperation | MergeNodesOperation;
+
+/**
+ * DocumentEngine — UndoManager
+ *
+ * Manages the undo/redo history stack.
+ *
+ * Entries are source-text snapshots, not stored tree mutations: the model
+ * rebuilds from text on undo/redo, so an entry stays replayable even after
+ * intervening rebuilds have replaced every node id it could have referenced.
+ * (The previous design stored `Transaction`s, whose `invert()` was only
+ * defined for one of the six operation kinds and whose one-shot `_applied`
+ * flag made redo a silent no-op.)
+ *
+ * Inspired by VSCode's undo stack.
+ */
+interface UndoEntry {
+    /** Source text before the change */
+    before: string;
+    /** Source text after the change */
+    after: string;
+    label: string;
+    timestamp: number;
+}
+declare class UndoManager {
+    private undoStack;
+    private redoStack;
+    private maxSize;
+    constructor(maxSize?: number);
+    /**
+     * Push a change (as before/after source snapshots) onto the undo stack.
+     */
+    push(snapshot: {
+        before: string;
+        after: string;
+    }, label?: string): void;
+    /**
+     * Undo the last change.
+     */
+    undo(): UndoEntry | null;
+    /**
+     * Redo the last undone change.
+     */
+    redo(): UndoEntry | null;
+    /**
+     * Peek at the top of the undo stack without removing.
+     */
+    peekUndo(): UndoEntry | null;
+    /**
+     * Peek at the top of the redo stack without removing.
+     */
+    peekRedo(): UndoEntry | null;
+    /**
+     * Clear both stacks.
+     */
+    clear(): void;
+    /**
+     * Get the number of undoable actions.
+     */
+    get undoCount(): number;
+    /**
+     * Get the number of redoable actions.
+     */
+    get redoCount(): number;
+}
+
+/**
+ * DocumentEngine — TreeBuilder
+ *
+ * Converts a TokenStream into a GreenNode tree.
+ * This is the bridge between the Lexer and the Syntax Tree.
+ *
+ * The TreeBuilder is language-agnostic — it uses registry-based
+ * node factories to build the appropriate tree structure.
+ */
+
+interface BuildResult {
+    green: GreenNode;
+    red: RedNode;
+    tokens: Token[];
+}
+interface NodeFactory$1 {
+    /** Create a GreenNode from a token or sequence of tokens */
+    createGreen(tokens: Token[], stream: TokenStream): GreenNode | null;
+    /** Create a RedNode from a green node */
+    createRed(green: GreenNode, parent?: RedNode | null): RedNode;
+}
+declare class TreeBuilder {
+    private factories;
+    private defaultKind;
+    constructor(defaultKind?: NodeKind);
+    /**
+     * Register a node factory for a specific token kind or tag name.
+     */
+    register(kind: string, factory: NodeFactory$1): void;
+    /**
+     * Build a tree from a token stream.
+     */
+    build(stream: TokenStream): BuildResult;
+    /**
+     * Build a green tree from a token array.
+     * Uses registered factories to determine node structure.
+     *
+     * By default, creates a flat document structure.
+     * Language-specific builders (like BBCodeParser) override this.
+     */
+    buildGreen(tokens: Token[]): GreenNode;
+    /**
+     * Build a red tree from a green tree.
+     */
+    buildRed(green: GreenNode, parent?: RedNode | null, kind?: NodeKind): RedNode;
+    /**
+     * Create a RedNode directly from children (for language-specific parsers).
+     */
+    createRedFromChildren(kind: NodeKind, text: string, children: RedNode[], parent?: RedNode | null): RedNode;
+    private tagToKind;
+}
+
+/**
+ * DocumentEngine — Query Types
+ *
+ * CSS-inspired query selectors for the document tree.
+ * Enables queries like: `paragraph > bold`, `quote text`, `[color]`
+ */
+
+type QuerySelector = {
+    type: 'kind';
+    kind: NodeKind;
+} | {
+    type: 'tag';
+    tag: string;
+} | {
+    type: 'attribute';
+    name: string;
+    value?: string;
+} | {
+    type: 'has_attribute';
+    name: string;
+} | {
+    type: 'text';
+    pattern: string;
+} | {
+    type: 'has_child';
+    selector: QuerySelector;
+} | {
+    type: 'has_descendant';
+    selector: QuerySelector;
+} | {
+    type: 'nth_child';
+    n: number;
+} | {
+    type: 'first_child';
+} | {
+    type: 'last_child';
+} | {
+    type: 'position';
+    min?: number;
+    max?: number;
+} | {
+    type: 'depth';
+    min?: number;
+    max?: number;
+};
+type QueryCombinator = 'child' | 'descendant' | 'adjacent' | 'sibling';
+interface QueryStep {
+    selector: QuerySelector[];
+    combinator: QueryCombinator | 'root';
+}
+interface Query {
+    steps: QueryStep[];
+}
+interface QueryMatch {
+    node: RedNode;
+    /** How well this node matches (for sorting results) */
+    score: number;
+    /** The specific selectors that matched */
+    matchedSelectors: string[];
+}
+interface QueryResult {
+    matches: QueryMatch[];
+    total: number;
+    time: number;
+}
+
+/**
+ * DocumentEngine — QueryEngine
+ *
+ * CSS-inspired query engine for the document tree.
+ * Enables queries like:
+ *   query('paragraph > bold')
+ *   query('quote text')
+ *   query('[color]')
+ *   query('list > *')
+ *
+ * Useful for:
+ * - Finding nodes by structure
+ * - AI context gathering
+ * - Plugin discovery
+ * - Lint rule targeting
+ */
+
+declare class QueryEngine {
+    /**
+     * Execute a query against a RedNode tree.
+     */
+    execute(query: Query, root: RedNode): QueryResult;
+    /**
+     * Filter candidates by applying a query step's selectors.
+     */
+    private matchStep;
+    /**
+     * Check if a single node matches a single selector.
+     */
+    private matchesSelector;
+}
+
+/**
+ * DocumentEngine — EventBus
+ *
+ * Publish/subscribe event system for document changes.
+ * Each DocumentModel has its own EventBus instance.
+ *
+ * Events include:
+ * - document_changed (rebuild, edit, undo/redo)
+ * - node_changed (insert, delete, update, move)
+ * - diagnostic_updated
+ * - transaction_applied
+ * - cursor_moved
+ * - selection_changed
+ */
+
+type DocumentEventType = 'document_changed' | 'node_inserted' | 'node_deleted' | 'node_updated' | 'diagnostics_updated' | 'transaction_applied' | 'undo_performed' | 'redo_performed' | 'cursor_moved' | 'selection_changed';
+interface DocumentEvent {
+    type: DocumentEventType;
+    kind?: DocumentChangeKind;
+    version?: number;
+    source?: string;
+    nodeId?: NodeId;
+    nodeMatch?: NodeMatch | null;
+    change?: TextChange;
+    operations?: Operation[];
+    /**
+     * Where the change came from: `'local'` for user editing, anything else for
+     * programmatic/synced sources. Lets a collaboration layer ignore the echo
+     * of changes it applied itself. Absent on events with no single cause.
+     */
+    origin?: string;
+    timestamp: number;
+    [key: string]: unknown;
+}
+type DocumentEventHandler = (event: DocumentEvent) => void;
+declare class DocumentEventBus {
+    private listeners;
+    private history;
+    private maxHistory;
+    /**
+     * Record emitted events so `getHistory()` returns them. Off by default:
+     * nothing reads the history today, and a retained event pins its `source`
+     * string — and, through the lazy `nodeMatch` accessor, the entire previous
+     * red/green tree — so an always-on history held megabytes per document
+     * for nobody. Turn it on for debugging or replay tooling.
+     */
+    recordHistory: boolean;
+    /**
+     * Subscribe to an event type.
+     */
+    on(type: DocumentEventType, handler: DocumentEventHandler): () => void;
+    /**
+     * Whether any handler is subscribed to `type` (or to anything, if omitted).
+     *
+     * Emitters use this to skip building event payloads nobody will see — the
+     * common case, since a headless model has no subscribers at all.
+     */
+    hasListeners(type?: DocumentEventType): boolean;
+    /**
+     * Subscribe to all events.
+     */
+    onAny(handler: DocumentEventHandler): () => void;
+    /**
+     * Emit an event.
+     */
+    emit(event: DocumentEvent): void;
+    /**
+     * Remove a specific handler.
+     */
+    off(type: DocumentEventType, handler: DocumentEventHandler): void;
+    /**
+     * Get event history.
+     */
+    getHistory(): DocumentEvent[];
+    /**
+     * Clear all listeners and history.
+     */
+    clear(): void;
+}
+
+/**
+ * DocumentEngine — RenderTree
+ *
+ * An intermediate representation between DocumentModel and final output.
+ * The RenderTree is what the RenderPipeline processes.
+ *
+ * This abstraction allows:
+ * - Same DocumentModel → multiple render outputs (HTML, Canvas, SVG, PDF)
+ * - Plugin renderers that intercept/modify render nodes
+ * - Smooth visual transitions between document states
+ * - Partial rendering for performance
+ */
+
+type RenderVariant = 'html' | 'canvas' | 'svg' | 'pdf' | 'react' | 'text';
+interface RenderNode {
+    /** Semantic kind */
+    kind: NodeKind | string;
+    /** Text content */
+    text: string;
+    /** Child render nodes */
+    children: RenderNode[];
+    /** Props/attributes for the renderer */
+    props: Record<string, unknown>;
+    /** Which render variant this node targets */
+    variant?: RenderVariant;
+    /** CSS class names */
+    className?: string;
+    /** Inline styles */
+    style?: Record<string, string | number>;
+    /** Events/handlers (for interactive renders) */
+    events?: Record<string, string>;
+    /** Metadata for renderers */
+    metadata?: Record<string, unknown>;
+}
+declare class RenderTree {
+    /**
+     * Create a render tree from a document node.
+     */
+    static fromNode(kind: NodeKind | string, text?: string, children?: RenderNode[], props?: Record<string, unknown>): RenderNode;
+    /**
+     * Create a text render node.
+     */
+    static text(content: string): RenderNode;
+    /**
+     * Create a container render node.
+     */
+    static container(kind: NodeKind | string, children: RenderNode[], props?: Record<string, unknown>): RenderNode;
+    /**
+     * Serialize a render tree to HTML.
+     */
+    static toHTML(node: RenderNode): string;
+    private static kindToTag;
+    private static propsToHtml;
+    private static escapeHtml;
+}
+
+/**
+ * DocumentEngine — TagRegistry
+ *
+ * The central registry for all known tags/node kinds.
+ * This is the plugin extension point for adding new BBCode tags,
+ * custom node types, or even entire new languages.
+ *
+ * Each tag definition includes:
+ * - Parser handler (how to parse this tag from tokens)
+ * - Renderer (how to render this tag to HTML, Markdown, etc.)
+ * - Validator (semantic validation rules)
+ * - Toolbar definition (for the visual editor)
+ * - Property editor (for the properties panel)
+ *
+ * Inspired by VSCode's contribution points.
+ */
+
+interface TagHandlerContext {
+    node: RedNode;
+    source: string;
+    visitChildren: (node: RedNode) => string;
+    renderChild: (node: RedNode) => RenderNode;
+}
+interface TagDefinition {
+    /** The tag name (e.g. 'color', 'b', 'img') */
+    name: string;
+    /** Semantic kind */
+    kind: NodeKind;
+    /** Human-readable label */
+    label: string;
+    /** Category for grouping in UI */
+    category?: 'formatting' | 'layout' | 'media' | 'special' | 'text';
+    /** Icon name for UI */
+    icon?: string;
+    /** Whether this tag is inline (span) or block (div) */
+    isInline: boolean;
+    /** Whether this tag is self-closing */
+    isSelfClosing: boolean;
+    /** Whether this tag can contain children */
+    canHaveChildren: boolean;
+    /** Whether this tag is deprecated */
+    isDeprecated?: boolean;
+    /** Replacement tag name if deprecated */
+    deprecatedReplacement?: string;
+    /** Convert a RedNode back to BBCode text */
+    toBBCode?: (ctx: TagHandlerContext) => string;
+    /** Convert a RedNode to a RenderNode for the render pipeline */
+    toRenderNode?: (ctx: TagHandlerContext) => RenderNode;
+    /** Convert a RedNode to HTML string (legacy) */
+    toHTML?: (ctx: TagHandlerContext) => string;
+    /** Default attributes for new instances */
+    defaultAttributes?: () => NodeAttributes;
+    /** Additional validator for this specific tag */
+    validator?: Validator;
+    /** Toolbar button definition */
+    toolbar?: {
+        group: string;
+        label: string;
+        icon?: string;
+        shortcut?: string;
+    };
+    /** Properties panel definition */
+    properties?: PropertyDefinition[];
+}
+interface PropertyDefinition {
+    name: string;
+    label: string;
+    type: 'text' | 'color' | 'number' | 'select' | 'boolean' | 'slider';
+    defaultValue?: string | number | boolean;
+    options?: {
+        label: string;
+        value: string;
+    }[];
+    min?: number;
+    max?: number;
+    step?: number;
+    placeholder?: string;
+    description?: string;
+}
+type TagHandler = {
+    [K in keyof TagDefinition]: TagDefinition[K];
+};
+declare class TagRegistry {
+    private tags;
+    private kinds;
+    /** Names registered by the constructor — the language's own tags. */
+    private builtins;
+    /**
+     * Bumped on every register/unregister, so consumers that derive something
+     * from the registry (the parser's `extraTags` map) can memoize against it
+     * instead of rebuilding per parse.
+     */
+    version: number;
+    constructor();
+    /**
+     * Register a tag definition.
+     */
+    register(tag: TagDefinition): void;
+    /**
+     * Unregister a tag definition.
+     */
+    unregister(name: string): void;
+    /**
+     * Whether `name` is one of the language's own tags, as opposed to a
+     * plugin registration. The distinction matters: plugin tags must reach the
+     * parser (via `ParseOptions.extraTags`) and serialize with their own name,
+     * while builtins already have both behaviors hardcoded — routing them
+     * through the plugin path would change engine semantics.
+     */
+    isBuiltin(name: string): boolean;
+    /**
+     * tag name → kind for every non-builtin registration: the parser's
+     * `extraTags`. Returns `null` when there are none, so the common case
+     * costs one size comparison and no allocation.
+     */
+    customTags(): Map<string, NodeKind> | null;
+    /**
+     * Get a tag definition by name.
+     */
+    get(name: string): TagDefinition | undefined;
+    /**
+     * Get a tag definition by semantic kind.
+     */
+    getByKind(kind: NodeKind): TagDefinition | undefined;
+    /**
+     * Check if a tag is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered tags.
+     */
+    getAll(): TagDefinition[];
+    /**
+     * Get tags by category.
+     */
+    getByCategory(category: string): TagDefinition[];
+    /**
+     * Get tags by whether they are inline.
+     */
+    getInline(): TagDefinition[];
+    /**
+     * Get block-level tags.
+     */
+    getBlock(): TagDefinition[];
+    /**
+     * Register the built-in BBCode tags.
+     */
+    private registerBuiltins;
+}
+
+/**
+ * DocumentEngine — NodeFactory
+ *
+ * Creates DocumentNode instances, RedNode instances, and GreenNode
+ * instances from tag definitions. Centralizes node creation so
+ * plugins can provide custom node factories.
+ */
+
+declare class NodeFactory {
+    private registry;
+    constructor(registry: TagRegistry);
+    /**
+     * Create a RedNode from a tag definition.
+     */
+    createFromTag(tagName: string, attrs?: string, start?: number, end?: number, children?: RedNode[]): RedNode;
+    /**
+     * Create a text RedNode.
+     */
+    createText(text: string, start?: number, end?: number): RedNode;
+    /**
+     * Create a self-closing tag RedNode (like [*], [img]src[/img]).
+     */
+    createSelfClosing(tagName: string, attrs?: string, start?: number, end?: number): RedNode;
+    /**
+     * Create a document root RedNode.
+     */
+    createDocument(children?: RedNode[]): RedNode;
+}
+
+/**
+ * DocumentEngine — DocumentModel
+ *
+ * THE CORE of the Language Platform.
+ *
+ * The DocumentModel is the single source of truth for the document.
+ * BBCode is just ONE representation of this model.
+ * The model is language-agnostic and format-agnostic.
+ *
+ * Responsibilities:
+ * - Hold the current Red Tree
+ * - Manage incremental parsing
+ * - Coordinate transactions (undo/redo)
+ * - Emit change events
+ * - Provide query/find capabilities
+ * - Manage diagnostics
+ *
+ * Inspired by ProseMirror's EditorState and Roslyn's Document.
+ */
+
+interface DocumentModelOptions {
+    /** Initial source text */
+    source?: string;
+    /** Language identifier */
+    language?: string;
+    /** Maximum undo stack size */
+    maxUndo?: number;
+    /** Whether to auto-analyze on change */
+    autoAnalyze?: boolean;
+    /**
+     * Attempt incremental reparse on `applyChange`. Default `true`.
+     *
+     * Setting this to `false` makes every change a full rebuild. The result is
+     * identical either way — that is the incremental parser's contract, checked
+     * differentially over 22.100 edits — so this is a performance switch and a
+     * debugging aid, not a correctness one.
+     */
+    incremental?: boolean;
+    /**
+     * Reuse red subtrees across incremental reparses. Default `true`.
+     *
+     * When the splice shares a green subtree by reference, the old red subtree
+     * is adopted into the new tree instead of being rebuilt — building red was
+     * the largest phase of a keystroke. The trade is a contract: the previous
+     * `redRoot` is consumed by the adoption and must not be walked afterwards.
+     * No engine or app code does; this switch exists for any future consumer
+     * that needs the superseded tree to stay intact.
+     */
+    reuseRed?: boolean;
+}
+declare class DocumentModel {
+    private _source;
+    private _language;
+    private _redRoot;
+    private _greenRoot;
+    private _version;
+    readonly tagRegistry: TagRegistry;
+    readonly nodeFactory: NodeFactory;
+    readonly treeBuilder: TreeBuilder;
+    readonly nodeMatcher: NodeMatcher;
+    readonly semanticAnalyzer: SemanticAnalyzer;
+    readonly incrementalParser: IncrementalParser;
+    readonly changeTracker: ChangeTracker;
+    readonly undoManager: UndoManager;
+    readonly queryEngine: QueryEngine;
+    readonly events: DocumentEventBus;
+    private _diagnostics;
+    private _lastAnalyzeResult;
+    /**
+     * Source range of the last applied edit — see {@link TextChangeRange}.
+     * `null` after a full rebuild, which is not an edit.
+     */
+    private _lastChangeRange;
+    private _options;
+    private _analyzeTimeout;
+    /** The debounced post-edit work, kept so `ensureAnalyzed` can run it early. */
+    private _pendingAnalyze;
+    /** Last reparse timings breakdown (exposed for debugging) */
+    lastReparsePath: string;
+    /** Why the last reparse fell back to a full rebuild, if it did. */
+    lastReparseFallbackReason: FallbackReason | null;
+    lastReparseTimings: {
+        findAffected: number;
+        safeBoundary: number;
+        parse: number;
+        buildRed: number;
+        mutate: number;
+        other: number;
+    } | null;
+    constructor(options?: DocumentModelOptions);
+    get source(): string;
+    get language(): string;
+    get version(): number;
+    get redRoot(): RedNode | null;
+    get greenRoot(): GreenNode | null;
+    get diagnostics(): DiagnosticCollection | null;
+    get lastAnalyze(): AnalyzeResult | null;
+    /**
+     * The source range of the last applied edit, in new-source coordinates.
+     *
+     * `null` after a `rebuild` (there is no incremental edit to point at). The
+     * BlockPatcher reads this to reconcile only the blocks around the edit
+     * instead of walking the whole document. The same range is also attached to
+     * the current `redRoot` (`__changeRange`), so a consumer that only holds the
+     * AST — like the live preview — can find it without plumbing the model.
+     */
+    get lastChangeRange(): TextChangeRange | null;
+    /**
+     * Full rebuild from source text.
+     * Used for initial load or when incremental parsing isn't possible.
+     */
+    rebuild(source: string): void;
+    /**
+     * Install `nodeMatch` on an event as an accessor, so the match is only
+     * computed if a subscriber actually reads it.
+     *
+     * Matching two 1736-node trees costs ~3.5 ms and allocates a result entry per
+     * node plus five Maps/Sets — and it ran on *every* keystroke to populate a
+     * field that no subscriber in this codebase reads. The capability is real
+     * (preserving selection and scroll across re-parses is what it is for), so it
+     * stays available; it just stops running speculatively.
+     *
+     * Callers still write `event.nodeMatch` and see a `NodeMatch | null`. Note the
+     * closure keeps `oldRoot` alive for as long as the event object is retained.
+     */
+    private defineLazyNodeMatch;
+    /**
+     * Attach the last change range to a root node.
+     *
+     * The range travels with the AST so the preview can read it from the root it
+     * is about to patch — no prop drilling through workspace → window → preview.
+     * `__changeRange` is deliberately not part of RedNode's API; it is a runtime
+     * marker owned by the model (the BlockPatcher reads it with a cast).
+     */
+    private _attachChangeRange;
+    /**
+     * Apply a source text change (e.g. from Monaco editor input).
+     * Uses incremental parsing when possible.
+     *
+     * `origin` tags where the change came from — `'local'` (default) for the
+     * user's own editing, anything else for programmatic or synced sources
+     * (`'remote'`, `'sync'`, a peer id…). It travels on the emitted events, so
+     * a collaboration layer can tell its own echo apart from user edits — the
+     * classic infinite-loop bug when wiring a CRDT. See `QuasarCollab.MD`.
+     */
+    applyChange(change: TextChange, origin?: string): void;
+    /**
+     * Flush the debounced post-edit analysis, so `diagnostics` describes the
+     * *current* tree.
+     *
+     * `applyChange` defers analysis by a few milliseconds to keep the keystroke
+     * path lean. A caller that reads `diagnostics` synchronously right after an
+     * edit would otherwise be looking at the previous document's errors — which
+     * is exactly what the editor's error panel did.
+     */
+    ensureAnalyzed(): void;
+    /**
+     * Calculate a simple diff between the current source and the new source,
+     * then apply the change.
+     */
+    applyTextUpdate(newSource: string, origin?: string): void;
+    /**
+     * Execute operations within a transaction (undoable).
+     *
+     * Coherence contract: after a `transact` the model's `source`, green tree
+     * and red tree all describe the same document. The transaction mutates the
+     * red tree, the result is serialized back to text via `exportSource`, and
+     * the model rebuilds from that text — parse stays the single source of
+     * truth, exactly as in `applyChange`. (The previous implementation swapped
+     * `_redRoot` and left `_source`/`_greenRoot` describing the old document,
+     * so the next text edit diffed against a source the tree no longer matched.)
+     *
+     * Returns `true` if the document changed.
+     */
+    transact(operations: Operation[], label?: string): boolean;
+    /**
+     * Undo the last transaction.
+     *
+     * Undo/redo replay *source snapshots*, not stored tree mutations: a rebuild
+     * replaces every node id, so a retained `Transaction` could never be
+     * re-applied against the current tree — and its `invert()` was only defined
+     * for one of the six operation kinds anyway. Text is always replayable.
+     */
+    undo(): boolean;
+    /**
+     * Redo the last undone transaction. See `undo` for why this replays text.
+     */
+    redo(): boolean;
+    /**
+     * Run semantic analysis on the current tree.
+     */
+    analyze(): AnalyzeResult;
+    /**
+     * Find a node by its ID.
+     */
+    findNode(id: NodeId): RedNode | null;
+    /**
+     * Query the document tree.
+     */
+    query(q: Query): QueryResult;
+    /**
+     * Register a semantic validator.
+     */
+    registerValidator(validator: Validator): void;
+    /**
+     * Get the current document as a DocumentNode tree.
+     */
+    toDocumentNode(): DocumentNode | null;
+    /**
+     * Get the current source text.
+     */
+    toString(): string;
+    /**
+     * Parse source text to a GreenNode tree.
+     * Override this for language-specific parsing.
+     *
+     * `options.normalizeParagraphs === false` means the text is the inner span
+     * of a container rather than a whole document, and root-level grouping must
+     * be skipped. Languages without such grouping can ignore it.
+     */
+    protected parseToGreen(source: string, options?: ReparseParseOptions): GreenNode;
+    /**
+     * Build a RedNode tree from a GreenNode.
+     */
+    protected buildRedFromGreen(green: GreenNode): RedNode;
+    /**
+     * Build a red tree for `green`, reusing subtrees of `oldRed` where the green
+     * is shared by reference. The base model has no reuse-aware builder, so it
+     * falls back to a full build; language models override this
+     * (BBCodeDocumentModel uses `greenToRedNodeReusing`).
+     */
+    protected buildRedFromGreenReusing(green: GreenNode, oldRed: RedNode, stats?: {
+        adopted: number;
+    }): RedNode;
+    /**
+     * Serialize a red tree back to source text. `transact`/`undo`/`redo` rebuild
+     * from this text to keep source, green and red coherent.
+     *
+     * The base model has no syntax to serialize to, so this throws; language
+     * models override it (BBCodeDocumentModel uses the BBCodeExporter).
+     * Failing loudly here beats the alternative: silently desynchronizing the
+     * model's three representations.
+     */
+    protected exportSource(root: RedNode): string;
+}
+
+/**
+ * DocumentEngine — Lexer
+ *
+ * Tokenizes source text into a stream of Tokens with Trivia.
+ * Trivia includes whitespace, newlines, and formatting that is
+ * preserved in the token stream but not semantically significant.
+ *
+ * This is a LANGUAGE-INDEPENDENT lexer framework.
+ * Language-specific tokenization is provided via the LexerOptions.
+ *
+ * Inspired by Roslyn's lexer architecture.
+ */
+
+interface LexerRule {
+    /** Pattern to match at the current position */
+    pattern: RegExp;
+    /** Token kind to produce */
+    kind: TokenKind;
+    /** Optional: extract a name from the match (for tags) */
+    name?: (match: RegExpExecArray) => string;
+    /** Optional: extract attributes from the match */
+    attrs?: (match: RegExpExecArray) => string;
+}
+interface LexerOptions {
+    /** Language-specific tokenization rules */
+    rules: LexerRule[];
+    /** Characters that count as whitespace trivia */
+    whitespaceChars?: RegExp;
+    /** Characters that start a newline trivia */
+    newlineChars?: RegExp;
+    /** Whether to collect trivia */
+    collectTrivia?: boolean;
+    /** Lexer hooks: called before each token */
+    onToken?: (token: Token) => void;
+}
+declare class Lexer {
+    private options;
+    private source;
+    private pos;
+    private tokens;
+    constructor(options: LexerOptions);
+    /**
+     * Tokenize source text into a TokenStream.
+     */
+    tokenize(source: string): TokenStream;
+    /**
+     * Re-tokenize a portion of the source (for incremental parsing).
+     * Returns just the new tokens for the affected range.
+     */
+    retokenize(source: string, start: number, end: number): Token[];
+    private tryRules;
+    private scanTrivia;
+}
+
+/**
+ * DocumentEngine — RedNodeStore
+ *
+ * Canonical store for RedNodes. Ensures that structurally identical subtrees
+ * share the EXACT SAME RedNode instance in RAM.
+ *
+ * This is the RedNode-level complement to GreenNodePool (which handles
+ * structural sharing at the GreenNode level).
+ *
+ * Architecture:
+ * - Keyed by GreenNode._hash (deterministic structural hash)
+ * - Bottom-up: children are stored first, then parents reference them
+ * - Immutable structural data: once a RedNode is in the store, its `children`
+ *   array and `green` reference never change
+ * - Mutable metadata: the store's RedNode has canonical metadata (derived from
+ *   green.text). Position-specific metadata lives in PositionRef.localOverlay.
+ *
+ * Benefits:
+ * - Memory deduplication: 100 identical blocks = 1 RedNode + 99 lightweight refs
+ * - Render caching: BBCodeCanvas can memoize by canonicalId
+ * - Faster incremental parse: unchanged subtrees keep their RedNode identity
+ * - HTMLRenderer cache: same canonicalId = same HTML (cache hits)
+ */
+
+/**
+ * Derives a node's canonical metadata from its GreenNode.
+ *
+ * Injected rather than hardcoded: metadata extraction is *language* semantics
+ * (what `=#ff0000,#00ff00` means for a `gradient`), and this module sits in the
+ * language-agnostic `Syntax` layer. The BBCode implementation lives in
+ * `BBCode/BBCodeToGreenNode.ts`; pass it via the constructor.
+ */
+type MetadataExtractor = (green: GreenNode) => NodeMetadata;
+declare class RedNodeStore {
+    private canonicals;
+    private _hits;
+    private _misses;
+    private _collisions;
+    private readonly extractMetadata;
+    /**
+     * @param extractMetadata  How to derive canonical metadata from a green node.
+     *   Defaults to producing none — the store stays language-agnostic unless a
+     *   caller supplies the mapping.
+     */
+    constructor(extractMetadata?: MetadataExtractor);
+    /**
+     * Get or create a canonical RedNode for the given GreenNode.
+     *
+     * The store is keyed by `green._hash` — a 32-bit FNV structural hash — so a
+     * matching key is necessary but NOT sufficient proof of identity. The
+     * canonical pipeline (GreenNodePool interning) guarantees that structurally
+     * identical greens ARE the same object, which is what makes reference
+     * equality a sound discriminator:
+     *
+     * - same hash + same green reference  → HIT, reuse the canonical
+     * - same hash + different green       → COLLISION: a distinct subtree shares
+     *   the 32-bit hash. It is never reused as the registered canonical and never
+     *   overwrites it (that would corrupt every future hit for the registered
+     *   node). The colliding subtree simply loses canonicalization — rebuilt on
+     *   each call. Guarding correctness costs a rare dedup miss; the alternative
+     *   costs a wrong AST.
+     * - no hash entry                     → MISS, create and register
+     *
+     * Invariant preserved: a hash collision can never make one structure be
+     * represented by another structure's RedNode.
+     *
+     * @param green  The GreenNode to wrap
+     * @param metadata  Optional metadata to set (overrides intrinsic metadata)
+     * @param kind  Optional kind override
+     * @returns The canonical RedNode (shared if already exists)
+     */
+    getOrCreate(green: GreenNode, metadata?: NodeMetadata, kind?: NodeKind): RedNode;
+    /**
+     * Build a canonical RedNode for `green` WITHOUT registering it.
+     *
+     * Shared by the miss path (which registers the result) and the collision
+     * path (which must not). Both need the same bottom-up construction:
+     * children are canonicalized first, then the parent references them.
+     */
+    private buildCanonical;
+    /**
+     * Look up a canonical RedNode by its structural hash.
+     */
+    getByHash(hash: string): RedNode | undefined;
+    /**
+     * Check if a GreenNode already has a canonical RedNode.
+     */
+    has(green: GreenNode): boolean;
+    /**
+     * Get the number of unique canonical nodes.
+     */
+    get size(): number;
+    /**
+     * Get store statistics.
+     */
+    get stats(): {
+        size: number;
+        hits: number;
+        misses: number;
+        collisions: number;
+        deduplicationRatio: string;
+    };
+    /**
+     * Clear all canonical nodes.
+     */
+    clear(): void;
+}
+
+/**
+ * DocumentEngine — TreeDiffer
+ *
+ * Computes structural differences between two Red Trees.
+ * Produces a list of DiffOperations that can be used for:
+ * - Updating the UI with minimal DOM changes
+ * - Syncing with collaboration servers
+ * - Animation interpolation
+ * - Undo/redo granularity
+ *
+ * Inspired by React's reconciliation and ProseMirror's diff.
+ */
+
+type DiffKind = 'insert' | 'delete' | 'update' | 'move' | 'preserve';
+interface DiffOperation {
+    kind: DiffKind;
+    node: RedNode;
+    oldNode?: RedNode;
+    /** Index in parent */
+    oldIndex?: number;
+    newIndex?: number;
+    /** Parent node ID */
+    parentId?: string;
+}
+interface DiffResult {
+    operations: DiffOperation[];
+    /** Count by kind */
+    stats: {
+        inserts: number;
+        deletes: number;
+        updates: number;
+        moves: number;
+        preserves: number;
+    };
+    /** Time taken in ms */
+    duration: number;
+}
+declare class TreeDiffer {
+    /**
+     * Compute the diff between two Red Trees.
+     */
+    diff(oldRoot: RedNode, newRoot: RedNode): DiffResult;
+    private diffChildren;
+    /**
+     * Check if a node's content has changed.
+     */
+    private nodeContentChanged;
+    /**
+     * Deep equality check for content equivalence when pairing unmatched nodes.
+     */
+    private nodesAreEquivalent;
+}
+
+/**
+ * DocumentEngine — Visitor
+ *
+ * Base visitor pattern for traversing the Red Tree.
+ * All exporters and renderers extend this.
+ *
+ * Instead of switch statements on tag names, use the visitor pattern.
+ * New languages/exporters don't modify existing code.
+ *
+ * Inspired by SwiftSyntax's Visitor pattern.
+ */
+
+interface VisitorContext {
+    source: string;
+    options: Record<string, unknown>;
+}
+declare abstract class Visitor<T = string> {
+    protected context: VisitorContext;
+    /**
+     * Visit a node and produce an output value.
+     */
+    abstract visit(node: RedNode, context?: VisitorContext): T;
+    /**
+     * Visit all children and combine results.
+     */
+    visitChildren(node: RedNode, separator?: string): T[];
+    /**
+     * Get the text content of a node.
+     */
+    getText(node: RedNode): string;
+    /**
+     * Set the visitor context.
+     */
+    setContext(context: VisitorContext): void;
+}
+
+/**
+ * DocumentEngine — BBCodeExporter
+ *
+ * Exports the Document Model / Red Tree back to BBCode text.
+ * This is how the internal representation becomes editable text.
+ *
+ * Uses the TagRegistry to determine how each node serializes.
+ * Plugins can register custom serializers for custom tags.
+ */
+
+/**
+ * Export target for BBCodeExporter.
+ * - 'osu': Expands Miliastry/Lyne-native tags into osu!-compatible BBCode.
+ * - 'miliastry': Preserves Miliastry-native tags as-is for round-trip editing.
+ * - 'lyne': Preserves Lyne-native tags as-is for round-trip editing.
+ */
+type ExportTarget$1 = 'osu' | 'miliastry' | 'lyne';
+/**
+ * Tags que existen SOLO en Miliastry (registrados en el TagRegistry) y que
+ * osu! NO renderiza. Si un usuario pega `[shadow]`/`[zalgo]`/etc. en osu!,
+ * el texto sale roto (los corchetes se ven literalmente). Cuando el target
+ * es 'osu', estos tags se DEGRADAN a su contenido plano: mejor perder el
+ * efecto que romper la userpage. El target 'miliastry' los conserva.
+ */
+declare const MILIASTRY_ONLY_TAGS: Set<string>;
+declare const LYNE_ONLY_TAGS: Set<string>;
+declare class BBCodeExporter extends Visitor<string> {
+    private registry;
+    private depth;
+    private target;
+    constructor(registry?: TagRegistry, target?: ExportTarget$1);
+    /**
+     * Set the export target. Controls how Miliastry-native tags are serialized.
+     */
+    setTarget(target: ExportTarget$1): void;
+    /**
+     * Export a RedNode tree to BBCode.
+     */
+    visit(node: RedNode, context?: VisitorContext): string;
+    /**
+     * Export the entire document to BBCode.
+     * Optionally override the export target for this specific call.
+     */
+    export(root: RedNode, target?: ExportTarget$1): string;
+    private exportNode;
+    private kindToTagName;
+    private getTagAttributes;
+}
+
+interface UIBBBlock {
+    id: string;
+    type: string;
+    attributes?: Record<string, string>;
+    children: UIBBBlock[];
+    content?: string;
+}
+declare class BBBlocksExporter extends Visitor<UIBBBlock[]> {
+    private idCounter;
+    private generateId;
+    visit(node: RedNode, context?: VisitorContext): UIBBBlock[];
+    export(root: RedNode): UIBBBlock[];
+    private exportNode;
+}
+
+/**
+ * DocumentEngine — BBCodeToGreenNode
+ *
+ * Bridge between the existing BBCode Parser (BBBlock[]) and the
+ * DocumentEngine's GreenNode/RedNode syntax tree.
+ *
+ * This is how we integrate the mature, battle-tested BBCode parser
+ * with the new Language Platform architecture.
+ *
+ * The flow:
+ *   BBCode text
+ *   → parseBBCode() [existing] → BBBlock[]
+ *   → convertToGreenNode() [this] → GreenNode
+ *   → buildRedNode() [this] → RedNode
+ *   → DocumentModel
+ */
+
+type BBCodeDialect = 'osu' | 'miliastry' | 'lyne';
+declare const BBCODE_TAG_NAMES: readonly string[];
+declare function getBBCodeTagNames(dialect?: BBCodeDialect): readonly string[];
+declare function tagToNodeKind(tag: string | null, dialect?: BBCodeDialect): NodeKind;
+declare function nodeKindToTag(kind: NodeKind): string | null;
+declare function isBlockKind(kind: NodeKind): boolean;
+interface BBBlock {
+    id: string;
+    tag: string | null;
+    attrs: string;
+    content: string;
+    rawStart: number;
+    rawEnd: number;
+    children: BBBlock[];
+    attrChildren?: BBBlock[];
+    html?: string;
+}
+/**
+ * Convert a single BBBlock to a GreenNode.
+ * Recursively converts children.
+ */
+declare function bbBlockToGreenNode(block: BBBlock): GreenNode;
+/**
+ * Convert an array of BBBlock[] (the root of the existing parser's output)
+ * to a GreenNode tree.
+ *
+ * Note: This function is kept for backward compatibility with the old parser.
+ * The new DocumentEngine parser (Parser.ts + BBCodeLexer) produces GreenNode
+ * directly and does NOT go through BBBlock[].
+ */
+declare function bbBlocksToGreenTree(blocks: BBBlock[], source: string): GreenNode;
+/**
+ * Build a RedNode tree from a GreenNode.
+ * Similar to TreeBuilder.buildRed but uses actual kind from the green node
+ * and extracts BBCode metadata from attributes.
+ *
+ * When a RedNodeStore is provided, instance RedNodes are created with
+ * correct parent references copied from the canonical's metadata.
+ * The canonicalId (from green._hash) enables:
+ * - React.memo in BBCodeCanvas by canonicalId
+ * - HTMLRenderer cache by canonicalId
+ * - Diff optimization (same canonicalId = unchanged subtree)
+ * - Future PositionRef-based sharing
+ */
+declare function greenToRedNode(green: GreenNode, parent?: RedNode | null, store?: RedNodeStore, start?: number): RedNode;
+/**
+ * Convert a BBBlock array directly to a RedNode root.
+ * This is the main entry point for the bridge.
+ */
+declare function bbBlocksToRedTree(blocks: BBBlock[], source: string): RedNode;
+
+/**
+ * DocumentEngine — HTMLRenderer
+ *
+ * Renders the Document Model to HTML for preview.
+ * This is the main renderer for the visual BBCode preview.
+ *
+ * Uses the TagRegistry for custom rendering.
+ * Plugins can register custom renderers for preview components.
+ */
+
+interface HTMLRendererOptions {
+    /**
+     * Replicate osu! forum BBCode spacing quirks.
+     * Defaults to true for full compatibility with Miliastry.
+     * Set to false for a more logical, predictable rendering engine.
+     */
+    osuBehaviour?: boolean;
+    /** Registry for resolving custom tags */
+    registry?: TagRegistry;
+    /** BBCode dialect to render for ('osu' | 'miliastry' | 'lyne') */
+    dialect?: BBCodeDialect;
+    /** Visual theme for markup classes ('osu' | 'lyne' | 'miliastry') */
+    theme?: 'osu' | 'lyne' | 'miliastry';
+    /** Safe media proxy callback to rewrite image and media URLs */
+    mediaProxy?: (url: string) => string;
+    /** Resolver for entity links like profile, guild, map */
+    entityLinkResolver?: (kind: string, value: string) => {
+        href: string;
+        external?: boolean;
+    } | null;
+}
+declare class HTMLRenderer extends Visitor<string> {
+    private options;
+    constructor(options?: HTMLRendererOptions);
+    private readonly BLOCK_TAGS;
+    private readonly INLINE_TAGS;
+    /**
+     * The ` data-node-id="…"` attribute, or `''` for nodes nobody looks up.
+     *
+     * ─── Why this is not emitted on everything ──────────────────────────────
+     *
+     * It used to be, carrying `node.id` — a process-global counter minted per
+     * RedNode, so a reparse renames every node in the document. Measured on a
+     * one-character edit: zero ids survive.
+     *
+     * `DOMMorpher` already noted that this rules the ids out as morph KEYS. The
+     * larger cost is that it also breaks the morpher's prefix/suffix trim, which
+     * uses `isEqualNode` — a comparison that includes attributes. An attribute
+     * that always differs makes every element compare unequal, so the trim never
+     * fires and the morpher walks the whole document. Measured on one keystroke
+     * in the reference document: **1665 `setAttribute` calls across 1725
+     * elements**, to write new numbers meaning the same thing, when the actual
+     * change was 10 insertions and 9 removals.
+     *
+     * ─── Why BLOCKS, and not stable ids ─────────────────────────────────────
+     *
+     * Making the id stable was the obvious repair and it does not work. Keying on
+     * the node's SPAN was measured: an edit at the END drops the writes to 6, but
+     * an insertion shifts every offset after it, so an edit near the START still
+     * cost 1637 — and spans are longer strings than `nN`, so the emitted HTML grew
+     * 10%. Stability under insertion is not something a position can have.
+     *
+     * The real observation is that no consumer ever wanted these on inline nodes.
+     * Both readers in the app are block-level: `usePreviewClick` walks up with
+     * `closest('[data-node-id]')` for *block selection*, and `useBlockHighlight`
+     * highlights and scrolls to a *block*. Emitting ids on the per-character
+     * spans of a gradient did not just cost — it made `closest()` stop at a
+     * character instead of the block the click meant.
+     *
+     * So the attribute goes where it is read. Inline nodes carry no id, compare
+     * equal, and let `isEqualNode` skip their subtrees natively; the handful of
+     * block containers that do carry one are few enough that their churn is
+     * noise.
+     */
+    /**
+     * Text leaves emit their content directly, with no wrapper element.
+     *
+     * They used to come wrapped in `<span class="bb-text">` — one extra DOM
+     * element per text leaf, which is HALF the preview's elements (measured:
+     * 1726 → 851 on a 19.6 KB post, 17251 → 8510 on a 196 KB one). The class
+     * earned none of it: it has no CSS rule anywhere in the repo, carries no
+     * `data-node-id` (text is not an id-bearing kind, so click mapping and
+     * highlighting never looked at it), and every style a text leaf can have
+     * still emits its own `<span style="…">` below.
+     *
+     * A/B in a production build, steady state: flush 41.4 → 39.7 ms at 19.6 KB
+     * and 55.4 → 46.4 ms at 196 KB, plus ~27% less HTML to serialize and parse.
+     */
+    private textWrap;
+    /**
+     * A qué elementos se les pone `data-node-id`.
+     *
+     * `'all'` (por defecto) — a todos. Es lo que permite que un clic en
+     * CUALQUIER punto del preview señale ese nodo exacto en el editor: en un
+     * degradado cada carácter es su propio nodo, y sin id no hay nada a lo que
+     * `closest()` pueda agarrarse.
+     *
+     * Esto estuvo desactivado por una buena razón que ya no aplica. Los ids se
+     * regeneraban en cada parseo, así que el atributo cambiaba en TODOS los
+     * elementos por pulsación: `isEqualNode` no casaba nunca, el morpher no
+     * podía saltarse ningún subárbol y se medían 1665 `setAttribute` sobre 1725
+     * elementos para escribir números nuevos que significaban lo mismo. Con la
+     * identidad estable entre reparseos eso desapareció: un nodo que no cambia
+     * conserva su id, su HTML es idéntico y el camino rápido del morpher sigue
+     * funcionando.
+     *
+     * El coste que queda es el tamaño: ~10 bytes por elemento, que hay que
+     * serializar y parsear. Medido con A/B en la misma sesión sobre el post con
+     * degradados (19,6 KB, 852 elementos):
+     *
+     *   solo bloques (9 con id):   latencia 48 ms · p95  72 ms
+     *   todos      (808 con id):   latencia 56 ms · p95 104 ms
+     *
+     * Se paga a propósito: la precisión del clic es una función que se pidió, y
+     * 56 ms sigue holgadamente dentro de lo que se percibe como inmediato.
+     * `'blocks'` queda disponible para quien priorice la latencia, y `'none'`
+     * para los consumidores de solo lectura (foros, render estático): sin
+     * `data-node-id` en absoluto, el HTML es más pequeño y no hay nada que
+     * mantenga vivos los nodos del árbol.
+     */
+    static idMode: 'blocks' | 'all' | 'none';
+    private idAttr;
+    /**
+     * Kinds that carry `data-node-id`.
+     *
+     * The block containers a user can select or be scrolled to, plus the media
+     * nodes, which are atomic and clickable in their own right. Deliberately NOT
+     * `text` or any inline formatting kind — see {@link idAttr}.
+     */
+    private static readonly ID_BEARING_KINDS;
+    visit(node: RedNode): string;
+    render(root: RedNode): string;
+    /**
+     * Render every child and concatenate.
+     *
+     * Replaces the `children.map(c => this.renderNode(c)).join('')` idiom, which
+     * was repeated at 16 call sites and allocated a closure plus an intermediate
+     * array of N strings at every level of the tree. Appending to one string lets
+     * the engine use its rope representation instead.
+     */
+    /**
+     * Render the direct children of `node` to HTML (no wrapper element).
+     *
+     * Public so the incremental preview (`BlockPatcher`) can morph a block
+     * element's inner content without re-rendering the whole document.
+     */
+    renderChildren(node: RedNode): string;
+    private renderNode;
+    /** osu! quirk: newlines immediately preceding a [code] block are completely ignored */
+    private isNextCodeBlock;
+    /** Checks if this is the LAST empty_line right before a code block (skipping only spacing) */
+    private isImmediateEmptyLineBeforeCode;
+    private isPrevBlockBoundary;
+    private isTrailingBlockBoundary;
+    private renderError;
+    private wrapInline;
+    private wrapBlock;
+    /** #rgb / #rgba / #rrggbb / #rrggbbaa, a bare CSS color keyword, or rgb()/hsl(). */
+    private static readonly CSS_COLOR_RE;
+    /** Bare number — interpolated as a percentage. */
+    private static readonly CSS_SIZE_RE;
+    /** Font family list. Quotes are rejected outright; unquoted names are valid CSS. */
+    private static readonly CSS_FONT_RE;
+    /** Characters `escapeHtml` has to rewrite. Non-global on purpose: `test` must not carry `lastIndex`. */
+    private static readonly HTML_ESCAPE_RE;
+    private sanitizeColor;
+    private sanitizeFontSize;
+    private sanitizeFontFamily;
+    /** Keyword-or-number CSS values (font-weight, font-style, text-decoration). */
+    private isCssKeyword;
+    /** Read a metadata field, falling back to the raw tag attribute. */
+    private metaOrAttr;
+    private colorStyle;
+    private fontSizeStyle;
+    private fontStyle;
+    /**
+     * Extract the attribute value from a BBCode tag node.
+     *
+     * BBCode attributes come in the format `=VALUE` (e.g. `=#61afef`, `="Author"`,
+     * `=https://osu.ppy.sh`). This strips the leading `=` and any surrounding quotes.
+     *
+     * For tags without attrs (like text nodes, img content), returns the node text as-is.
+     */
+    private extractValue;
+    private renderLink;
+    private renderProfile;
+    private renderEntity;
+    private parseImgAttr;
+    private renderImage;
+    private renderVideo;
+    private renderAudio;
+    private hexToRgba;
+    private renderNotice;
+    private renderTables;
+    private renderGallery;
+    private renderColumns;
+    private renderSeparator;
+    private renderScroll;
+    private renderAbbr;
+    private renderTooltip;
+    private renderRaw;
+    private renderPlain;
+    private renderAlign;
+    private renderEffect;
+    private renderAnim;
+    private renderContainer;
+    private static readonly STYLE_PROP_WHITELIST;
+    private renderStyleTag;
+    private renderQuote;
+    private renderSpoilerbox;
+    private renderBox;
+    private renderTitle;
+    /**
+     * `[box=Title:#hex]`, `[tables=striped:#hex]`, `[columns=2:#hex]` → un
+     * ` style="--<suffix>-accent:#hex;"` del que el CSS deriva la paleta
+     * (título + chevron y borde en boxw; gradientes/header/hover en tables;
+     * borde + fondo en columns). Devuelve '' si no hay color válido.
+     */
+    private boxAccentStyle;
+    private renderList;
+    private renderListItem;
+    private renderCode;
+    private renderSVG;
+    /**
+     * Render an osu! BBCode imagemap.
+     *
+     * Structure:
+     *   [imagemap]
+     *   https://example.com/image.png    ← first line = image URL
+     *   10 20 50 60 https://... Label    ← subsequent lines = clickable areas
+     *   [/imagemap]
+     *
+     * Each area line format: x y width height url [label]
+     * All values are PERCENTAGES (0–100) relative to the image dimensions.
+     * Uses CSS absolute positioning with percentage coordinates.
+     */
+    private renderImagemap;
+    private collectNodeText;
+    private renderGradient;
+    /**
+     * Escape for both text content and double-quoted attribute values.
+     *
+     * `'` is included because attribute values elsewhere in the codebase (and in
+     * consumer-supplied tag handlers) may be single-quoted; leaving it raw makes
+     * the escaping context-dependent, which is how injections get reintroduced.
+     */
+    /**
+     * Escape the five HTML-significant characters.
+     *
+     * Was five chained `.replace(/x/g, …)` calls: five full scans of the string
+     * and up to five intermediate allocations for *every* text node, even though
+     * ordinary prose contains none of these characters. This tests once and
+     * returns the input untouched in that common case, then does a single pass
+     * when there is actually something to escape.
+     */
+    private escapeHtml;
+}
+
+/**
+ * DocumentEngine — DOMMorpher
+ *
+ * Reconciles and morphs an existing HTML DOM tree in-place to match a new HTML string.
+ * Operating on pure HTML string output from HTMLRenderer means ZERO changes to Quasar AST schemas.
+ *
+ * Features:
+ * - In-place attribute synchronization
+ * - In-place text node value updates
+ * - Preserves state of unchanged elements (spoilers, audio/video, selections)
+ * - Zero extra wrapper <div> elements
+ */
+declare function morphHTML(container: HTMLElement, newHTML: string): void;
+
+/**
+ * DocumentEngine — BlockPatcher
+ *
+ * Incremental rendering for the HTML preview.
+ *
+ * The naive path — `renderToHTML(root)` + `morphHTML(container, html)` on every
+ * keystroke — re-serializes the ENTIRE document to a string and, worse, makes
+ * the browser re-parse that whole string (`template.innerHTML`) even when only
+ * one character changed. Profiled on an 18.5 KB document: `morphHTML` ≈ 29.8 ms
+ * per keystroke, of which ~27 ms is the full-HTML parse (morph ≈ baseline
+ * `innerHTML=`). The parser itself is ~0.5 ms.
+ *
+ * This module makes the DOM update O(changed block) instead of O(document):
+ *
+ *   - The document's top-level children are the independent "blocks".
+ *   - With stable `data-node-id`s (see `preserveNodeIds`) a block that did not
+ *     change renders to the SAME html string, or is even the SAME RedNode
+ *     object (red-subtree reuse). Either way we can detect "unchanged" without
+ *     touching the DOM.
+ *   - Only changed blocks are re-rendered and re-morphed, in place, keyed by
+ *     their element.
+ *   - Structural edits — a block inserted, removed or reordered (Enter,
+ *     backspace between blocks, moving a block in the visual builder) — are
+ *     reconciled BY KEY too. The stable ids let us insert/remove/move ONLY the
+ *     affected elements, so every untouched block keeps its DOM identity and
+ *     runtime state (an open `<details>`, media playback). When the edit
+ *     script adds more blocks than the previous document had (a whole new
+ *     document patched into the same container, ids regenerated en masse) we
+ *     fall back to a full rebuild: one `innerHTML` parse beats N per-block
+ *     ones.
+ *
+ * DOM alignment — "runs": a top-level block may render to an element, to a
+ * bare text node (`text`, osu `spacing`/`empty_line` quirks) or to nothing
+ * (`''`, an empty text leaf). Two adjacent bare-text blocks are merged into a
+ * single text node by the HTML parser, so a block↔node 1:1 pairing would
+ * silently misalign after such a merge. The reconciliation therefore works on
+ * RUNS: consecutive bare-text blocks form one "text run" that maps to exactly
+ * one text node (mirroring the parser), and element blocks are their own runs.
+ * The run list is the exact 1:1 mirror of `container.childNodes`.
+ */
+
+interface PatchBlocksOptions {
+    /** Renderer used to serialize blocks. Defaults to a shared HTMLRenderer. */
+    renderer?: HTMLRenderer;
+    /** Called when a block fails to morph; the caller can log it. */
+    onError?: (err: unknown) => void;
+    /**
+     * The source range of the edit that produced `rootNode`, if known.
+     *
+     * Lets the patcher reconcile ONLY the runs overlapping the edit (O(edit))
+     * instead of walking the whole document — the difference between ~2ms and
+     * ~100ms per keystroke on a 500k-character document. Coordinates are in
+     * new-source space with the old end kept separately; see `TextChangeRange`.
+     * When omitted, the patcher falls back to the full keyed reconcile — and it
+     * also reads the range attached to the root by `DocumentModel`.
+     */
+    change?: TextChangeRange;
+    /**
+     * Minimum top-level blocks for the windowed path to run; below it the full
+     * keyed walk is cheaper than the windowed bookkeeping. Defaults to
+     * `MIN_WINDOWED_BLOCKS` (200). Tests force `0` to exercise the windowed
+     * path on small documents.
+     */
+    minWindowedBlocks?: number;
+}
+interface PatchBlocksStats {
+    /** Which path was taken. */
+    mode: 'full' | 'blocks';
+    /** Number of top-level blocks. */
+    total: number;
+    /** Blocks whose DOM was actually updated (0 = nothing changed). */
+    patched: number;
+    /** True when the windowed (O(edit)) reconcile ran, not the full keyed walk. */
+    windowed?: boolean;
+}
+/**
+ * Reconcile `container`'s children against `rootNode`'s top-level blocks.
+ *
+ * Inline edits morph only the changed block; structural edits (insert, remove,
+ * reorder) are reconciled by key so untouched blocks keep their DOM identity.
+ * Returns what was done so callers/tests can assert the fast path fired.
+ */
+declare function patchBlocksInto(container: HTMLElement, rootNode: RedNode | null, options?: PatchBlocksOptions): PatchBlocksStats;
+
+/**
+ * SVGRenderer (Runtime ForeignObject Strategy)
+ *
+ * Instead of attempting to calculate CSS layouts manually,
+ * this runtime renderer wraps the exact HTML output in an SVG <foreignObject>.
+ *
+ * This gives 100% precision with zero DOM scanning overhead for real-time previews.
+ */
+declare class SVGRenderer extends Visitor<string> {
+    private htmlRenderer;
+    visit(node: RedNode, context?: VisitorContext): string;
+    render(root: RedNode): string;
+}
+
+/**
+ * DocumentEngine — MarkdownExporter
+ *
+ * Exports the Document Model to Markdown.
+ * Demonstrates the format-agnostic power of the engine:
+ * BBCode in → DocumentModel → Markdown out.
+ *
+ * A single visitor, no parser changes needed.
+ */
+
+declare class MarkdownExporter extends Visitor<string> {
+    visit(node: RedNode): string;
+    export(node: RedNode): string;
+    private exportNode;
+    private renderTitleMarkdown;
+    /**
+     * Read a BBCode tag's `=VALUE` attribute.
+     *
+     * This previously read `node.properties` / `node.attributes`, neither of
+     * which exists on RedNode — so it silently returned `undefined` for every
+     * node and every call site fell through to its placeholder. That is why
+     * Markdown export dropped link targets and quote/box titles.
+     */
+    private extractValue;
+}
+
+/**
+ * DocumentEngine — JSONExporter
+ *
+ * Exports the Document Model to JSON.
+ * Useful for:
+ * - Saving/loading documents in a structured format
+ * - Sending over the wire (collaboration)
+ * - Debugging and inspecting the document tree
+ * - Import/export between different tools
+ */
+
+interface JSONDocument {
+    version: number;
+    kind: string;
+    nodes: JSONNode[];
+    metadata?: Record<string, unknown>;
+}
+interface JSONNode {
+    id: string;
+    kind: string;
+    text: string;
+    version: number;
+    children: JSONNode[];
+    attributes?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    range?: {
+        start: number;
+        end: number;
+    };
+}
+declare class JSONExporter extends Visitor<string> {
+    /**
+     * Export a RedNode tree to a JSON string.
+     */
+    visit(node: RedNode): string;
+    /**
+     * Export to a JSON object.
+     */
+    toJSON(node: RedNode): JSONDocument;
+    private serializeNode;
+}
+
+/**
+ * DocumentEngine — TiptapExporter
+ *
+ * Exports the Document Model to Tiptap (ProseMirror) JSON format.
+ * This proves how easily Quasar's AST bridges to visual WYSIWYG editors.
+ *
+ * Tiptap uses a JSON format structured like:
+ * {
+ *   type: "doc",
+ *   content: [
+ *     {
+ *       type: "paragraph",
+ *       content: [
+ *         { type: "text", text: "Hello ", marks: [{ type: "bold" }] }
+ *       ]
+ *     }
+ *   ]
+ * }
+ */
+
+interface TiptapNode {
+    type: string;
+    attrs?: Record<string, any>;
+    content?: TiptapNode[];
+    marks?: TiptapMark[];
+    text?: string;
+}
+interface TiptapMark {
+    type: string;
+    attrs?: Record<string, any>;
+}
+declare class TiptapExporter extends Visitor<string> {
+    visit(node: RedNode): string;
+    toTiptap(node: RedNode): TiptapNode;
+    private processChildren;
+    private processNode;
+    private kindToMark;
+    private kindToBlockType;
+}
+
+/**
+ * DocumentEngine — Transaction
+ *
+ * Groups operations into an atomic, undoable unit.
+ * Every modification to the document MUST go through a Transaction.
+ *
+ * Inspired by ProseMirror's Transaction system.
+ */
+
+declare class Transaction {
+    readonly operations: Operation[];
+    readonly id: string;
+    readonly timestamp: number;
+    private _applied;
+    constructor(operations: Operation[]);
+    /**
+     * Apply the transaction to a RedNode tree.
+     * Returns the updated tree or null if application failed.
+     */
+    apply(root: RedNode): RedNode | null;
+    /**
+     * Create the inverse transaction (for undo).
+     */
+    invert(root: RedNode): Transaction;
+    /**
+     * Get a human-readable label for this transaction.
+     */
+    getLabel(): string;
+    private applyOperation;
+    private applyInsert;
+    private applyDelete;
+    private applyReplace;
+    private applyMove;
+    private applySetText;
+}
+
+/**
+ * DocumentEngine — Command
+ *
+ * Commands are high-level user actions that MAY produce
+ * a Transaction (or multiple) to modify the document.
+ *
+ * Commands are stateless — they receive context and produce operations.
+ * This makes them testable, undoable, and safe for AI use.
+ *
+ * Inspired by ProseMirror's Commands and VSCode's Command system.
+ */
+
+interface CommandContext {
+    model: DocumentModel;
+    root: RedNode;
+    selection?: {
+        nodeId: string;
+        start: number;
+        end: number;
+    };
+}
+type CommandResult = {
+    success: boolean;
+    operations?: Operation[];
+    message?: string;
+};
+interface Command {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly shortcut?: string;
+    execute(ctx: CommandContext): CommandResult;
+    canExecute?(ctx: CommandContext): boolean;
+}
+
+/**
+ * DocumentEngine — CommandRegistry
+ *
+ * Central registry for all document commands.
+ * Commands can be added by plugins.
+ *
+ * Enables:
+ * - Keyboard shortcut binding
+ * - Toolbar integration
+ * - AI command execution
+ * - Menu integration
+ */
+
+declare class CommandRegistry {
+    private commands;
+    /**
+     * Register a command.
+     */
+    register(command: Command): void;
+    /**
+     * Unregister a command.
+     */
+    unregister(id: string): void;
+    /**
+     * Get a command by ID.
+     */
+    get(id: string): Command | undefined;
+    /**
+     * Check if a command is registered.
+     */
+    has(id: string): boolean;
+    /**
+     * Execute a command by ID.
+     */
+    execute(id: string, ctx: CommandContext): CommandResult;
+    /**
+     * Get all registered commands.
+     */
+    getAll(): Command[];
+    /**
+     * Get commands by a filter function.
+     */
+    filter(predicate: (cmd: Command) => boolean): Command[];
+    /**
+     * Get the count of registered commands.
+     */
+    get size(): number;
+}
+
+/**
+ * DocumentEngine — InsertText Command
+ *
+ * Inserts text at the current cursor position.
+ * Creates or reuses a text node.
+ */
+
+declare const InsertText: Command;
+
+/**
+ * DocumentEngine — DeleteNode Command
+ *
+ * Deletes a node from the document tree.
+ */
+
+declare const DeleteNode: Command;
+
+/**
+ * DocumentEngine — WrapInTag Command
+ *
+ * Wraps the current selection in a BBCode tag.
+ * E.g. selected text → [b]selected text[/b]
+ */
+
+declare const WrapInTag: Command;
+
+/**
+ * DocumentEngine — SplitNode & MergeNodes Commands
+ *
+ * Split a node at a position, or merge two adjacent nodes.
+ * Essential for block editing and backspace handling.
+ */
+
+declare const SplitNode: Command;
+declare const MergeNode: Command;
+
+/**
+ * DocumentEngine — Formatter
+ *
+ * Formats the document tree into "pretty" BBCode.
+ * Normalizes indentation, spacing, and whitespace.
+ *
+ * Uses the TagRegistry and Visitor pattern.
+ * Plugins can register custom formatters for custom tags.
+ */
+
+interface FormatOptions {
+    /** Whether to add newlines between block elements */
+    blockNewlines?: boolean;
+    /** Whether to normalize whitespace inside inline elements */
+    normalizeInlineWhitespace?: boolean;
+    /** Maximum line width (0 = no limit) */
+    maxLineWidth?: number;
+    /** Whether to collapse consecutive empty lines */
+    collapseEmptyLines?: boolean;
+    /** Indentation string */
+    indent?: string;
+}
+declare class Formatter {
+    /**
+     * Format a RedNode tree (extracts text while preserving exact layout/spacing).
+     */
+    format(root: RedNode): string;
+    /**
+     * Format a single node at a given depth.
+     */
+    private formatNode;
+}
+
+/**
+ * DocumentEngine — Linter
+ *
+ * Lints the document tree for issues.
+ * Similar to ESLint but for BBCode documents.
+ *
+ * Rules can be added via the Plugin API.
+ */
+
+type LintSeverity = 'error' | 'warning' | 'info' | 'hint';
+interface LintRule {
+    code: string;
+    severity: LintSeverity;
+    description: string;
+    validate(node: RedNode, context: LintContext): LintIssue | LintIssue[] | null;
+}
+interface LintContext {
+    source: string;
+    allNodes: Map<string, RedNode>;
+}
+interface LintIssue {
+    code: string;
+    message: string;
+    severity: LintSeverity;
+    nodeId: string;
+    range: {
+        start: number;
+        end: number;
+    } | null;
+    fix?: {
+        description: string;
+        apply: () => void;
+    };
+}
+interface LintResult {
+    issues: LintIssue[];
+    errorCount: number;
+    warningCount: number;
+    infoCount: number;
+    hintCount: number;
+}
+declare class Linter {
+    private rules;
+    constructor();
+    /**
+     * Register a lint rule.
+     */
+    register(rule: LintRule): void;
+    /**
+     * Unregister a lint rule.
+     */
+    unregister(code: string): void;
+    /**
+     * Lint a RedNode tree.
+     */
+    lint(root: RedNode, source: string): LintResult;
+    private registerBuiltinRules;
+}
+
+/**
+ * DocumentEngine — Symbol Types
+ *
+ * Symbol system for definitions and references in BBCode documents.
+ * Enables: go-to-definition, find-all-references, rename, etc.
+ *
+ * Inspired by Language Server Protocol (LSP).
+ */
+
+type SymbolKind = 'tag' | 'id_definition' | 'id_reference' | 'class' | 'property' | 'variable' | 'function' | 'module' | 'snippet' | 'template' | 'other';
+interface SymbolInfo {
+    /** Unique ID for this symbol */
+    id: string;
+    /** Symbol name (e.g. 'hero', 'my-block') */
+    name: string;
+    /** Symbol kind */
+    kind: SymbolKind;
+    /** The node that defines this symbol */
+    definitionNodeId: NodeId;
+    /** Source range of the definition */
+    definitionRange: SourceRange;
+    /** Container node (e.g. the document) */
+    containerNodeId: NodeId;
+    /** All references to this symbol */
+    references: Reference[];
+    /** Additional data */
+    data?: Record<string, unknown>;
+}
+interface Reference {
+    nodeId: NodeId;
+    range: SourceRange;
+    kind: 'definition' | 'reference' | 'implementation';
+}
+interface SymbolSearchResult {
+    symbol: SymbolInfo;
+    score: number;
+}
+
+/**
+ * DocumentEngine — SymbolTable
+ *
+ * Tracks symbols (definitions and references) in the document.
+ * Enables IDE features like:
+ * - Go to definition
+ * - Find all references
+ * - Rename symbol
+ * - Document outline
+ *
+ * In BBCode, symbols include:
+ * - [id=hero] → Definition
+ * - [goto=hero] → Reference
+ * - Named anchors and targets
+ */
+
+declare class SymbolTable {
+    private symbols;
+    private nodeToSymbolId;
+    /**
+     * Build the symbol table from a RedNode tree.
+     */
+    build(root: RedNode): void;
+    /**
+     * Get a symbol by name.
+     */
+    get(name: string): SymbolInfo | undefined;
+    /**
+     * Get the symbol associated with a node.
+     */
+    getSymbolForNode(nodeId: string): SymbolInfo | undefined;
+    /**
+     * Search for symbols by name.
+     */
+    search(query: string, maxResults?: number): SymbolSearchResult[];
+    /**
+     * Get all symbols.
+     */
+    getAll(): SymbolInfo[];
+    /**
+     * Clear all symbols.
+     */
+    clear(): void;
+    private addSymbol;
+    private createSymbolId;
+}
+
+/**
+ * DocumentEngine — RenderPipeline
+ *
+ * The Render Pipeline transforms a DocumentModel into renderable output.
+ * It sits between the model and the view layer.
+ *
+ * The pipeline is:
+ *   DocumentModel → RenderTree → HTML/SVG/Canvas/React
+ *
+ * Plugins can intercept at any stage:
+ * - Add/transform render nodes
+ * - Provide custom renderers for custom tags
+ * - Post-process the output
+ */
+
+type RenderPhase = 'build' | 'transform' | 'serialize';
+interface RenderHook {
+    phase: RenderPhase;
+    hook: (node: RenderNode, context: RenderContext) => RenderNode | null;
+}
+interface RenderContext {
+    variant: RenderVariant;
+    registry: TagRegistry;
+    source: string;
+}
+declare class RenderPipeline {
+    private hooks;
+    /**
+     * Register a render hook.
+     */
+    register(hook: RenderHook): void;
+    /**
+     * Unregister a render hook.
+     */
+    unregister(hook: RenderHook): void;
+    /**
+     * Render a RedNode tree to a string.
+     */
+    render(root: RedNode, variant: RenderVariant | undefined, registry: TagRegistry, source?: string): string;
+    /**
+     * Build a RenderNode tree from a RedNode tree.
+     */
+    private buildRenderTree;
+}
+
+/**
+ * DocumentEngine — PluginRegistry
+ *
+ * Manages the lifecycle of plugins/extensions.
+ * Each plugin registers contributions (tags, commands, validators, etc.)
+ * and can be loaded/unloaded at runtime.
+ *
+ * Inspired by VSCode's extension system.
+ */
+
+interface PluginManifest {
+    name: string;
+    version: string;
+    description?: string;
+    author?: string;
+    /** Dependencies on other plugins */
+    dependencies?: string[];
+}
+interface PluginContribution {
+    /** Tags to register */
+    tags?: TagDefinition[];
+    /** Commands to register */
+    commands?: Command[];
+    /** Semantic validators */
+    validators?: Validator[];
+    /** Lint rules */
+    lintRules?: LintRule[];
+    /** Render hooks */
+    renderHooks?: RenderHook[];
+    /** CSS to inject */
+    styles?: string[];
+    /** Initialization function */
+    activate?: () => void | Promise<void>;
+    /** Cleanup function */
+    deactivate?: () => void;
+}
+interface Plugin {
+    manifest: PluginManifest;
+    contributions: PluginContribution;
+    /** Whether the plugin is currently active */
+    active: boolean;
+}
+declare class PluginRegistry {
+    private plugins;
+    /**
+     * Register a plugin.
+     */
+    register(manifest: PluginManifest, contributions: PluginContribution): Plugin;
+    /**
+     * Unregister and deactivate a plugin.
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get a plugin by name.
+     */
+    get(name: string): Plugin | undefined;
+    /**
+     * Get all registered plugins.
+     */
+    getAll(): Plugin[];
+    /**
+     * Activate a plugin (calls activate function).
+     */
+    activate(plugin: Plugin): void;
+    /**
+     * Deactivate a plugin (calls deactivate function).
+     */
+    deactivate(plugin: Plugin): void;
+    /**
+     * Activate all registered plugins.
+     */
+    activateAll(): void;
+    /**
+     * Deactivate all plugins.
+     */
+    deactivateAll(): void;
+}
+
+/**
+ * DocumentEngine — PluginAPI
+ *
+ * The public API exposed to plugins.
+ * Plugin authors use this to register tags, commands, validators, etc.
+ *
+ * Inspired by VSCode's `vscode` module.
+ */
+
+declare class PluginAPI {
+    readonly model: DocumentModel;
+    readonly tags: TagRegistry;
+    readonly commands: CommandRegistry;
+    readonly semantic: SemanticAnalyzer;
+    readonly linter: Linter;
+    readonly renderer: RenderPipeline;
+    readonly plugins: PluginRegistry;
+    constructor(model: DocumentModel);
+    /**
+     * Register a plugin with all its contributions.
+     *
+     * Example:
+     * ```ts
+     * api.registerPlugin({
+     *   name: 'my-plugin',
+     *   version: '1.0.0'
+     * }, {
+     *   tags: [{ name: 'blur', kind: 'custom', ... }],
+     *   commands: [{ id: 'my-command', ... }]
+     * })
+     * ```
+     */
+    registerPlugin(manifest: PluginManifest, contributions: PluginContribution): void;
+    /**
+     * Unregister a plugin and remove its contributions.
+     */
+    unregisterPlugin(name: string): void;
+}
+
+/**
+ * DocumentEngine — GreenNodePool (Structural Sharing via Interning)
+ *
+ * Roslyn-grade GreenNode Deduplication Pool.
+ *
+ * Ensures that structurally identical subtrees share the EXACT SAME
+ * GreenNode memory address in RAM. This is structural sharing:
+ * when the same BBCode block is pasted 10 times, the parser creates
+ * GreenNodes for it ONCE, and all 10 copies reference the same objects.
+ *
+ * Architecture:
+ * - Flyweight Pattern: GreenNodes are pure structural data without parent pointers.
+ * - Hash-based lookup: O(1) amortized via _hash property on GreenNode.
+ * - Reference-equality verification: identical children = same reference (because
+ *   children are interned first, bottom-up construction guarantees this).
+ * - Per-document scope: interners are created per BBCodeDocumentModel, cleared on dispose.
+ *
+ * Key insight: because GreenNodes are immutable and children are interned bottom-up,
+ * two nodes with the same (kind, text, widths, children-references) are structurally
+ * identical. We use _hash for fast lookup, then verify with reference equality on
+ * children.
+ *
+ * ─── Why this used to be broken (roadmap S2) ────────────────────────────────
+ *
+ * Green nodes used to carry an absolute `range`, and the two halves of the pool
+ * disagreed about what to do with it:
+ *
+ *  - `internLeaf` keyed on `kind:text` alone, so the second `"Hello"` in a
+ *    document got back the node built for the FIRST one — carrying the first
+ *    one's offsets. Enabling the interner made every position downstream lie
+ *    silently: incremental reparse, `findNodeAtOffset`, diagnostics, the
+ *    Monaco↔AST mapping.
+ *  - `internNode` did the opposite and required identical start AND end before
+ *    deduplicating, which no two distinct occurrences can have. The same block
+ *    pasted ten times gave 0% dedup and 100% of the scanning cost.
+ *
+ * Neither was fixable while position lived on the green node, because those are
+ * the only two options: ignore it and lie, or respect it and never match. The
+ * fix was to remove position from the green tree entirely — see `GreenNode.ts`.
+ * Now `kind:text:width` genuinely identifies a leaf, and interning is simply
+ * correct.
+ */
+
+/**
+ * How much of the tree to deduplicate.
+ *
+ * Measured on the 19.6 KB reference document, against no interning at all:
+ *
+ * | mode     | parse time | green tree memory |
+ * |----------|------------|-------------------|
+ * | `leaves` | +16%       | −42%              |
+ * | `full`   | +110%      | −56%              |
+ *
+ * `leaves` is the default because it buys three quarters of the memory for a
+ * seventh of the time. Interning an internal node means hashing its whole
+ * subtree — `_hash` is lazy, so a parse that never interns never pays for it —
+ * and then walking its children to verify a bucket hit. Leaves cost one string
+ * key and one Map lookup, and they are where the duplication is: the reference
+ * document has 930 leaves and only 122 distinct ones.
+ */
+type InterningMode = 'leaves' | 'full';
+
+/**
+ * DocumentEngine — BBCodeDocumentModel
+ *
+ * A DocumentModel subclass that uses the DocumentEngine's built-in
+ * BBCode Lexer + Parser to produce GreenNode/RedNode trees.
+ *
+ * This COMPLETELY replaces the old BBCode parser (MiliastryNovaFeatures/BBCode/Parser).
+ * The old parser is DEPRECATED.
+ *
+ * Architecture:
+ *   BBCode text
+ *     ↓ BBCodeLexer.scanBBCode()
+ *   BBCodeToken[]
+ *     ↓ Parser.parseTokensToGreen()
+ *   GreenNode
+ *     ↓ BBCodeToGreenNode.greenToRedNode()
+ *   RedNode
+ *     ↓ HTMLRenderer.render()
+ *   HTML preview
+ *
+ * Usage:
+ *   const model = new BBCodeDocumentModel({ source: '[b]Hello[/b]' })
+ *   const html = new HTMLRenderer().render(model.redRoot!)
+ */
+
+interface BBCodeDocumentModelOptions extends DocumentModelOptions {
+    /** Source BBCode text to parse */
+    source?: string;
+    /** Language identifier (default: 'bbcode') */
+    language?: string;
+    /** Enforce strict tag nesting (disables osu! auto-close legacy behavior) */
+    strictMode?: boolean;
+    /** BBCode dialect to parse against ('osu' | 'miliastry' | 'lyne'). Default: 'miliastry'. */
+    dialect?: BBCodeDialect;
+    /** Alias for dialect ('osu' | 'miliastry' | 'lyne') */
+    mode?: BBCodeDialect;
+    /**
+     * Deduplicate structurally identical green nodes across the document.
+     *
+     * Off by default. It is correct now — see the header of `GreenNodePool.ts`
+     * for why it was not — but it is a memory/latency trade, and this engine's
+     * declared budget is latency: on the 19.6 KB reference document `'leaves'`
+     * costs 16% more parse time to save 42% of the green tree's memory. Turn it
+     * on for workloads that hold many documents at once; leave it off to type
+     * into one.
+     */
+    interning?: InterningMode;
+}
+declare class BBCodeDocumentModel extends DocumentModel {
+    private _strictMode;
+    private _dialect;
+    /** Per-document interner, or null when interning is off. */
+    private _interner;
+    /** Memoized parser `extraTags`, rebuilt only when the registry changes. */
+    private _extraTags;
+    private _extraTagsVersion;
+    constructor(options?: BBCodeDocumentModelOptions);
+    get dialect(): BBCodeDialect;
+    get root(): RedNode | null;
+    toHTML(renderer?: HTMLRenderer): string;
+    /**
+     * Parse BBCode text directly to a GreenNode tree using the
+     * DocumentEngine's built-in BBCode Lexer + Parser.
+     * No dependency on the deprecated old parser.
+     */
+    protected parseToGreen(source: string, options?: ReparseParseOptions): GreenNode;
+    /**
+     * Build a RedNode from a GreenNode, extracting metadata
+     * from BBCode attributes in the process.
+     */
+    protected buildRedFromGreen(green: GreenNode): RedNode;
+    /**
+     * Reuse-aware red build for the incremental path: adopts old red subtrees
+     * wherever the splice shared their green by reference. See the contract on
+     * `greenToRedNodeReusing` — the old tree is consumed.
+     */
+    protected buildRedFromGreenReusing(green: GreenNode, oldRed: RedNode, stats?: {
+        adopted: number;
+    }): RedNode;
+    /**
+     * Serialize the red tree back to BBCode, so `transact`/`undo`/`redo` can
+     * rebuild from text. Target 'miliastry' keeps native tags (gradient, grow,
+     * …) as-is instead of expanding them, which is what round-tripping needs.
+     */
+    protected exportSource(root: RedNode): string;
+}
+
+/**
+ * DocumentEngine — Position transforms
+ *
+ * Where does a position end up after a text edit?
+ *
+ * This is the primitive collaboration stands on: keeping carets, selections
+ * and remote cursors pointing at the same *content* while the text shifts
+ * under them — whether the edit came from the local user, a remote peer, or
+ * a programmatic `transact`. See `QuasarCollab.MD` for the architecture; the
+ * short version is that Quasar syncs TEXT, so mapping positions through
+ * `TextChange`s is all the transform machinery the engine needs. This module
+ * transforms positions, not changes-against-changes: convergence of
+ * concurrent edits is the CRDT's job, not ours.
+ */
+
+/**
+ * Which side a position sticks to when an edit happens exactly at it.
+ *
+ * A caret usually wants `'right'`: text inserted at the caret by someone else
+ * should push it forward (you keep typing after their insertion). The start
+ * of a persistent highlight usually wants `'left'`: text inserted exactly at
+ * its start belongs before the highlight, not inside it.
+ */
+type TransformBias = 'left' | 'right';
+/**
+ * Map `offset` through one change or an ordered sequence of changes.
+ *
+ * Rules, in order:
+ * - strictly before the edit → unchanged;
+ * - strictly after the replaced span → shifted by the length delta;
+ * - inside the replaced span → collapsed to the edit's boundary (`'left'` →
+ *   where the replacement starts, `'right'` → where it ends). A position
+ *   inside deleted text has no content to point at anymore; the boundary is
+ *   the only honest answer;
+ * - exactly at a pure insertion point → `bias` decides which side of the
+ *   inserted text it lands on.
+ */
+declare function transformOffset(offset: number, changes: TextChange | readonly TextChange[], bias?: TransformBias): number;
+/**
+ * Map a `{start, end}` range through one change or a sequence.
+ *
+ * The start sticks RIGHT and the end sticks LEFT, which is what preserves the
+ * selected content: text inserted exactly at a boundary lands OUTSIDE the
+ * range, so the range keeps covering exactly the characters it covered — it
+ * neither absorbs a neighbour's insertion nor leaks its own content. The
+ * result is clamped so it can never come out inverted; a range entirely
+ * inside deleted text collapses to a point at the edit boundary.
+ */
+declare function transformRange(range: {
+    start: number;
+    end: number;
+}, changes: TextChange | readonly TextChange[]): {
+    start: number;
+    end: number;
+};
+
+/**
+ * DocumentEngine — BoxDrawer
+ *
+ * Drawer-style open/close animation for the `<details>` elements that
+ * HTMLRenderer emits for `[box]` and `[spoilerbox]`. The box grows downwards
+ * and progressively uncovers its content, which stays anchored under the
+ * summary instead of popping in all at once.
+ *
+ * This lives in Quasar rather than in a consumer because Quasar is what emits
+ * the `<details>` in the first place — the same reason `morphHTML` lives here.
+ * Any host that renders Quasar output gets the behaviour by binding it once.
+ *
+ * Why not CSS: while a `<details>` is closed its content is not rendered, so
+ * there is no height to interpolate between. `::details-content` combined with
+ * `interpolate-size: allow-keywords` would solve it, but it is Chromium-only in
+ * practice and hosts running on WebKit would silently lose the animation.
+ * Measuring the real height and driving it with the Web Animations API works on
+ * every engine.
+ *
+ * Heights are measured, not computed from summary + padding + borders, because
+ * that arithmetic breaks as soon as a theme puts margins on the summary or the
+ * boxes are nested. Toggling `open` and reading the rect yields the exact
+ * height the element will settle at, whatever the stylesheet does.
+ */
+interface BoxDrawerOptions {
+    /** Length of a full open or close, in milliseconds. Partial travel is scaled down. */
+    durationMs?: number;
+    /** CSS easing function. */
+    easing?: string;
+}
+/**
+ * Animate one `<details>` to its opposite state, reversing cleanly when it is
+ * already mid-animation.
+ *
+ * Exported so hosts that toggle boxes programmatically (a keyboard command, an
+ * "expand all" action) go through the same animation as a click.
+ */
+declare function toggleBoxWithDrawer(details: HTMLDetailsElement, options?: BoxDrawerOptions): void;
+/**
+ * Intercept the native toggle of every box inside `root`.
+ *
+ * The listener is delegated rather than attached per box: hosts typically feed
+ * the preview through `morphHTML` on every keystroke, and per-element listeners
+ * would be torn down and re-attached continuously.
+ *
+ * @param root - container holding the rendered BBCode
+ * @returns disposer that removes the listener
+ */
+declare function bindBoxDrawer(root: HTMLElement, options?: BoxDrawerOptions): () => void;
+
+/**
+ * DocumentEngine — Visuals
+ *
+ * Catálogo de estilos visuales por plataforma para la previsualización
+ * de BBCode. Cada plataforma puede tener su propia apariencia sin
+ * modificar el renderer HTML.
+ *
+ * Uso:
+ *   // Importar como CSS directo (soportado por Next.js, Vite, Webpack):
+ *   import 'MiliastryPlatform/DocumentEngine/Visuals/osu.css'
+ *
+ *   // O desde un componente React:
+ *   import 'MiliastryPlatform/DocumentEngine/Visuals/osu.css'
+ *   // Luego en el JSX: <div className="bbcode-preview" ...
+ *
+ * Para cambiar de tema visual, solo cambia el import del CSS.
+ *
+ * Temas disponibles:
+ *   - osu  → Estilo visual inspirado en los foros de osu!
+ *   - miliastry → Estilo por defecto de Miliastry (próximamente)
+ */
+
+declare const visualThemes: readonly [{
+    readonly id: "osu";
+    readonly name: "osu! Forum Style";
+    readonly description: "Estilo visual inspirado en los foros de osu!";
+    readonly cssFile: "osu.css";
+}, {
+    readonly id: "lyne";
+    readonly name: "Lyne Style";
+    readonly description: "Estilo visual cyberpunk con cortes a 45° inspirado en Lyne";
+    readonly cssFile: "lyne.css";
+}];
+type VisualThemeId = (typeof visualThemes)[number]['id'];
+
+/**
+ * Quasar — Color Utilities
+ *
+ * Standalone color functions for gradient/grow/exporter interpolation.
+ * No external dependencies — pure math.
+ *
+ * Ported from TextStudio/lib/color.ts (originally backed by culori).
+ * These are the minimal subset needed for internal tag export.
+ */
+type Easing = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
+
+/**
+ * Quasar — Tree Transformers
+ *
+ * Apply effects (gradient, grow, rainbow, central, multi) across an entire RedNode tree.
+ * These functions walk the tree, track global text position,
+ * and wrap each text leaf in internal effect nodes
+ * with position metadata so the TagRegistry handlers produce
+ * correctly interpolated output.
+ *
+ * DESIGN:
+ *   Two-pass approach:
+ *     1. Collect total text length (for normalization)
+ *     2. Walk again, wrapping text nodes with effect nodes
+ *
+ *   Non-text nodes (img, video, audio, code blocks) are preserved unchanged.
+ *   Structural nodes (box, quote, list) recurse into children.
+ *   Formatting nodes (b, i, u, color) recurse — effects go INSIDE formatting.
+ *
+ *   Example:
+ *     Input:  [box][b]Hello[/b] World[/box]
+ *     Output: [box][b][gradient][b]H[/b][gradient][b]e[/b]...[/b]
+ *                    [gradient] W[/gradient]...[/gradient]
+ *
+ *   Actually simpler — each text leaf gets its own gradient node with
+ *   globalOffset metadata, and the handler does the interpolation.
+ */
+
+interface GradientEffect {
+    kind: 'gradient';
+    colors: string[];
+    unit?: 'character' | 'word' | 'line';
+    easing?: Easing;
+}
+interface GrowEffect {
+    kind: 'grow';
+    min?: number;
+    max?: number;
+    cycles?: number;
+}
+interface RainbowEffect {
+    kind: 'rainbow';
+    saturation?: number;
+    lightness?: number;
+    spread?: number;
+    offset?: number;
+}
+interface CentralGradientEffect {
+    kind: 'central_gradient';
+    colors: string[];
+    unit?: 'character' | 'word' | 'line';
+    easing?: Easing;
+}
+interface MultiGradientEffect {
+    kind: 'multi_gradient';
+    colors: string[];
+    mode?: 'wave' | 'pulse';
+    unit?: 'character' | 'word' | 'line';
+    easing?: Easing;
+}
+type TreeEffect = GradientEffect | GrowEffect | RainbowEffect | CentralGradientEffect | MultiGradientEffect;
+/**
+ * Count total plain text length across all text leaves in a tree.
+ */
+declare function countTextLength(node: RedNode): number;
+/**
+ * Apply a gradient effect across an entire RedNode tree.
+ *
+ * The gradient is computed across ALL text content in the tree,
+ * so color transitions span across structural boundaries:
+ *
+ *   [b]Hello[/b] World  →  [b][color=#FF0000]H[/color]...[/b][color=#00FF00]W[/color]...
+ *
+ * @param root    The RedNode tree to transform
+ * @param colors  Array of hex colors to interpolate across
+ * @param options.unit      Split unit: 'character' (default), 'word', or 'line'
+ * @param options.easing    Easing function: 'linear' (default), 'easeIn', 'easeOut', 'easeInOut'
+ * @returns A new RedNode tree with gradient applied
+ */
+declare function applyGradient(root: RedNode, colors: string[], options?: {
+    unit?: 'character' | 'word' | 'line';
+    easing?: Easing;
+}): RedNode;
+/**
+ * Apply a grow (size wave) effect across an entire RedNode tree.
+ *
+ * Size oscillates via sine wave across ALL text content:
+ *
+ *   [b]Hello[/b] World  →  [b][size=90]H[/size]...[/b][size=160]W[/size]...
+ *
+ * @param root    The RedNode tree to transform
+ * @param options.min       Minimum size % (default: 90)
+ * @param options.max       Maximum size % (default: 160)
+ * @param options.cycles    Number of sine cycles across text (default: 1)
+ * @returns A new RedNode tree with grow applied
+ */
+declare function applyGrow(root: RedNode, options?: {
+    min?: number;
+    max?: number;
+    cycles?: number;
+}): RedNode;
+/**
+ * Apply a rainbow effect across an entire RedNode tree.
+ *
+ * Hue rotates across ALL text content using HSL color space:
+ *
+ *   [b]Hello[/b] World  →  [b][color=#FF0000]H[/color]...[/b][color=#00FF00]W[/color]...
+ *
+ * @param root    The RedNode tree to transform
+ * @param options.saturation  Saturation 0-100 (default: 80)
+ * @param options.lightness   Lightness 0-100 (default: 60)
+ * @param options.spread      Hue spread in degrees (default: 300)
+ * @param options.offset      Starting hue offset in degrees (default: 0)
+ * @returns A new RedNode tree with rainbow applied
+ */
+declare function applyRainbow(root: RedNode, options?: {
+    saturation?: number;
+    lightness?: number;
+    spread?: number;
+    offset?: number;
+}): RedNode;
+/**
+ * Apply a central gradient across an entire RedNode tree.
+ *
+ * Gradient radiates from center outward (mirrored):
+ *
+ *   [b]Hello[/b] World  →  [b][color=#FF0000]H[/color]...[/b][color=#00FF00]W[/color]...
+ *
+ * @param root    The RedNode tree to transform
+ * @param colors  Array of hex colors to interpolate across
+ * @param options.unit      Split unit: 'character' (default), 'word', or 'line'
+ * @param options.easing    Easing function: 'linear' (default), 'easeIn', 'easeOut', 'easeInOut'
+ * @returns A new RedNode tree with central gradient applied
+ */
+declare function applyCentralGradient(root: RedNode, colors: string[], options?: {
+    unit?: 'character' | 'word' | 'line';
+    easing?: Easing;
+}): RedNode;
+/**
+ * Apply a multi gradient (wave or pulse) across an entire RedNode tree.
+ *
+ * Wave mode: sine wave pattern across colors.
+ * Pulse mode: repeating gradient segments.
+ *
+ * @param root    The RedNode tree to transform
+ * @param colors  Array of hex colors to interpolate across
+ * @param options.mode      'wave' (default) or 'pulse'
+ * @param options.unit      Split unit: 'character' (default), 'word', or 'line'
+ * @param options.easing    Easing function: 'linear' (default), 'easeIn', 'easeOut', 'easeInOut'
+ * @returns A new RedNode tree with multi gradient applied
+ */
+declare function applyMultiGradient(root: RedNode, colors: string[], options?: {
+    mode?: 'wave' | 'pulse';
+    unit?: 'character' | 'word' | 'line';
+    easing?: Easing;
+}): RedNode;
+/**
+ * Apply any supported effect across an entire RedNode tree.
+ */
+declare function applyEffect(root: RedNode, effect: TreeEffect): RedNode;
+
+interface DomToSVGOptions {
+    backgroundColor?: string;
+    includeBackground?: boolean;
+    /** Scale factor applied to all coordinates (default 1) */
+    scale?: number;
+}
+interface SVGLayerInfo {
+    id: string;
+    tag: string;
+    depth: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    type: 'image' | 'iframe' | 'audio' | 'background' | 'border' | 'group' | 'text';
+    text?: string;
+}
+interface DomToSVGResult {
+    svg: string;
+    width: number;
+    height: number;
+    layerCount: number;
+    layers: SVGLayerInfo[];
+}
+declare function domToSVG(root: HTMLElement, options?: DomToSVGOptions): string;
+declare function domToSVGResult(root: HTMLElement, options?: DomToSVGOptions): DomToSVGResult;
+
+interface TransformResult {
+    document: DocumentModel;
+    transaction?: Transaction;
+}
+interface Transformer {
+    /**
+     * Transforms a DocumentModel.
+     * Should ideally return a Transaction that contains the operations applied.
+     */
+    transform(document: DocumentModel): TransformResult;
+}
+
+declare class ASTOptimizer implements Transformer {
+    transform(document: DocumentModel): TransformResult;
+    private applyRules;
+    private static VOID_TAGS;
+    private static UNMERGEABLE;
+    private isEmptyNode;
+    /**
+     * Two `paragraph` siblings with *nothing* between them.
+     *
+     * `paragraph` is in {@link UNMERGEABLE} for good reason — paragraphs are block
+     * separators and collapsing them normally would change the document. But this
+     * particular shape is one the optimizer creates itself and the parser never
+     * does: paragraphs exist because a block element split the inline content, so
+     * when a rule deletes that block (an empty `[notice]`, say) the two halves are
+     * left as adjacent paragraphs that no longer have anything separating them.
+     *
+     * That was the whole non-idempotence bug. Exporting such a tree emits no
+     * separator, so re-parsing folds the two paragraphs back into one and a second
+     * optimizer pass finds more work to do. Merging here makes the tree agree with
+     * its own round-trip.
+     *
+     * Verified empirically before relying on it: across 202.764 nodes (both real
+     * fixtures plus 20.000 seeded random documents) the parser produced this shape
+     * **zero** times, so the rule can only ever fire on optimizer-made trees.
+     *
+     * `spaces` must be empty — paragraphs separated by real spacing or blank lines
+     * are a genuine authored break and must survive.
+     */
+    private isOrphanedParagraphPair;
+    private canMerge;
+    private getRank;
+}
+
+interface SineWaveOptions {
+    minSize: number;
+    maxSize: number;
+    frequency: number;
+    step: 'char' | 'word';
+    selectionRange?: {
+        start: number;
+        end: number;
+    };
+}
+declare class SineWaveTransformer implements Transformer {
+    private options;
+    constructor(options?: Partial<SineWaveOptions>);
+    transform(document: DocumentModel): TransformResult;
+}
+
+interface RainbowOptions {
+    saturation: number;
+    lightness: number;
+    spread: number;
+    offset: number;
+    selectionRange?: {
+        start: number;
+        end: number;
+    };
+}
+declare class RainbowTransformer implements Transformer {
+    private options;
+    constructor(options?: Partial<RainbowOptions>);
+    transform(document: DocumentModel): TransformResult;
+}
+
+interface GradientOptions {
+    from: string;
+    to: string;
+    unit: 'char' | 'word';
+    easing: Easing;
+    selectionRange?: {
+        start: number;
+        end: number;
+    };
+}
+declare class GradientTransformer implements Transformer {
+    private options;
+    constructor(options?: Partial<GradientOptions>);
+    transform(document: DocumentModel): TransformResult;
+}
+
+interface GrowOptions {
+    minSize: number;
+    maxSize: number;
+    cycles: number;
+    selectionRange?: {
+        start: number;
+        end: number;
+    };
+}
+declare class GrowTransformer implements Transformer {
+    private options;
+    constructor(options?: Partial<GrowOptions>);
+    transform(document: DocumentModel): TransformResult;
+}
+
+interface MarkdownDocumentModelOptions extends DocumentModelOptions {
+    source?: string;
+    language?: string;
+}
+declare class MarkdownDocumentModel extends DocumentModel {
+    constructor(options?: MarkdownDocumentModelOptions);
+    static fromMarkdown(source: string): MarkdownDocumentModel;
+    protected parseToGreen(source: string): GreenNode;
+    protected buildRedFromGreen(green: GreenNode): RedNode;
+    applyTextUpdate(newSource: string): void;
+    applyChange(change: any): void;
+}
+
+/**
+ * DocumentEngine — Markdown AST Nodes
+ */
+type MarkdownNode = MarkdownDocument | MarkdownParagraph | MarkdownHeading | MarkdownText | MarkdownCodeBlock | MarkdownCodeInline | MarkdownStrong | MarkdownEmphasis | MarkdownLink | MarkdownImage | MarkdownList | MarkdownListItem | MarkdownBlockquote | MarkdownSpoiler | MarkdownNotice | MarkdownSpacing | MarkdownEmptyLine;
+interface MarkdownDocument {
+    type: 'document';
+    children: MarkdownNode[];
+}
+interface MarkdownParagraph {
+    type: 'paragraph';
+    children: MarkdownNode[];
+}
+interface MarkdownHeading {
+    type: 'heading';
+    level: number;
+    children: MarkdownNode[];
+}
+interface MarkdownText {
+    type: 'text';
+    value: string;
+}
+interface MarkdownCodeBlock {
+    type: 'code_block';
+    lang: string;
+    value: string;
+}
+interface MarkdownCodeInline {
+    type: 'code_inline';
+    value: string;
+}
+interface MarkdownStrong {
+    type: 'strong';
+    children: MarkdownNode[];
+}
+interface MarkdownEmphasis {
+    type: 'emphasis';
+    children: MarkdownNode[];
+}
+interface MarkdownLink {
+    type: 'link';
+    url: string;
+    children: MarkdownNode[];
+}
+interface MarkdownImage {
+    type: 'image';
+    url: string;
+    alt: string;
+}
+interface MarkdownList {
+    type: 'list';
+    ordered: boolean;
+    children: MarkdownListItem[];
+}
+interface MarkdownListItem {
+    type: 'list_item';
+    children: MarkdownNode[];
+}
+interface MarkdownBlockquote {
+    type: 'blockquote';
+    children: MarkdownNode[];
+}
+/** `>!` spoiler block — produced by MarkdownParser, maps to BBCode [spoiler]. */
+interface MarkdownSpoiler {
+    type: 'spoiler';
+    children: MarkdownNode[];
+}
+/** `> [!NOTE]` callout — produced by MarkdownParser, maps to BBCode [notice]. */
+interface MarkdownNotice {
+    type: 'notice';
+    children: MarkdownNode[];
+}
+interface MarkdownSpacing {
+    type: 'spacing';
+}
+interface MarkdownEmptyLine {
+    type: 'empty_line';
+}
+
+declare function markdownAstToGreenTree(root: MarkdownNode): GreenNode;
+declare function markdownAstToRedTree(root: MarkdownNode): RedNode;
+
+interface HTMLDocumentModelOptions extends DocumentModelOptions {
+    source?: string;
+    language?: string;
+}
+declare class HTMLDocumentModel extends DocumentModel {
+    constructor(options?: HTMLDocumentModelOptions);
+    static fromHTML(source: string): HTMLDocumentModel;
+    protected parseToGreen(source: string): GreenNode;
+    protected buildRedFromGreen(green: GreenNode): RedNode;
+}
+
+declare function htmlStringToGreenTree(html: string): GreenNode;
+
+/**
+ * Quasar Analysis Framework — Pipeline Context
+ *
+ * PipelineContext is **read-only by contract**.  It is built *before*
+ * the pipeline starts and MUST NOT be modified by any pass.
+ *
+ * If a pass needs to make information available to downstream passes it
+ * should emit a Contribution rather than mutating the context.
+ *
+ * @immutable
+ */
+declare const PipelineMode: {
+    readonly Interactive: "interactive";
+    readonly Batch: "batch";
+    readonly Import: "import";
+};
+type PipelineMode = (typeof PipelineMode)[keyof typeof PipelineMode];
+declare const ExportTarget: {
+    readonly Osu: "osu";
+    readonly Miliastry: "miliastry";
+    readonly HTML: "html";
+    readonly Markdown: "markdown";
+};
+type ExportTarget = (typeof ExportTarget)[keyof typeof ExportTarget];
+interface PipelineContext {
+    /** Where this pipeline run originates from. */
+    readonly mode: PipelineMode;
+    /** The format we intend to export to (influences decisions). */
+    readonly target: ExportTarget;
+    /** Feature flags that may enable/disable certain behaviours. */
+    readonly featureFlags: Readonly<Record<string, boolean>>;
+    /** Free-form metadata provided by the caller (e.g. selection range). */
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Quasar Analysis Framework — Contribution Types
+ *
+ * Every AnalyzerPass produces an array of Contributions.  A Contribution
+ * is a discriminated union so that downstream consumers (DecisionPass,
+ * AnalysisReport consumers, debug UI) can switch on `kind` and get
+ * perfect TypeScript narrowing.
+ *
+ * @see AnalysisReport
+ */
+declare const ContributionKind: {
+    readonly Semantic: "semantic";
+    readonly Diagnostic: "diagnostic";
+    readonly Optimization: "optimization";
+    readonly Metrics: "metrics";
+};
+type ContributionKind = (typeof ContributionKind)[keyof typeof ContributionKind];
+/**
+ * A semantic pattern recognised in the tree (gradient, wave, rainbow,…).
+ * These describe *meaning* of the document, not just surface syntax.
+ */
+interface SemanticContribution {
+    readonly kind: typeof ContributionKind.Semantic;
+    readonly label: string;
+    readonly confidence: number;
+    readonly range: {
+        start: number;
+        end: number;
+    };
+    readonly metadata: Record<string, unknown>;
+    /** Human-readable description (optional). */
+    readonly description?: string;
+}
+/**
+ * A diagnostic (warning, error, info) attached to a range in the tree.
+ */
+interface DiagnosticContribution {
+    readonly kind: typeof ContributionKind.Diagnostic;
+    readonly severity: 'error' | 'warning' | 'info' | 'hint';
+    readonly message: string;
+    readonly range?: {
+        start: number;
+        end: number;
+    };
+    readonly code?: string;
+}
+/**
+ * An optimisation opportunity detected in the tree (mergeable colours,
+ * redundant wrapping, empty tags, …).
+ */
+interface OptimizationContribution {
+    readonly kind: typeof ContributionKind.Optimization;
+    readonly label: string;
+    readonly description: string;
+    readonly estimatedImprovement?: string;
+    readonly range: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * Aggregate metrics about the tree (character count, node depth, …).
+ */
+interface MetricsContribution {
+    readonly kind: typeof ContributionKind.Metrics;
+    readonly metrics: Record<string, number | string>;
+}
+type Contribution = SemanticContribution | DiagnosticContribution | OptimizationContribution | MetricsContribution;
+
+/**
+ * Quasar Analysis Framework — Analysis Report
+ *
+ * Once all AnalyzerPasses have run, their Contributions are collected
+ * into an immutable AnalysisReport.  This report is the sole input to
+ * the DecisionPass(es).
+ *
+ * We deliberately keep the aggregator simple for now — just an array
+ * of contributions.  As more pass types emerge we may introduce a
+ * structured Aggregator that indexes/categorises contributions.
+ *
+ * @see DecisionPass
+ */
+
+interface AnalysisReport {
+    /** All contributions gathered from every AnalyzerPass. */
+    readonly contributions: readonly Contribution[];
+    /** Total number of analysis passes that ran. */
+    readonly passCount: number;
+    /** Wall-clock time spent in analysis (ms). */
+    readonly elapsedMs: number;
+}
+
+/**
+ * Quasar Analysis Framework — Pass Contracts
+ *
+ * Each pass in the analysis/transform pipeline implements one of these
+ * specialized interfaces.  The three kinds mirror LLVM's pass structure:
+ *
+ *   Analysis  — observe the tree, produce Contributions (never mutate)
+ *   Decision  — consume an AnalysisReport, produce a TransformationPlan
+ *   Transform — mutate the tree according to a plan
+ *
+ * @see ARCHITECTURE.md (Analysis Framework)
+ */
+
+/** Every pass has an identity string and belongs to a stage. */
+interface Pass {
+    readonly id: string;
+}
+/**
+ * An AnalyzerPass observes the Green Tree and produces one or more
+ * Contributions.  It MUST NOT mutate the tree or the context.
+ */
+interface AnalyzerPass extends Pass {
+    run(tree: GreenNode, context: PipelineContext): Contribution[];
+}
+/**
+ * A DecisionPass consumes an AnalysisReport (which itself is the
+ * aggregated output of all AnalyzerPasses) and produces a
+ * TransformationPlan that describes *intended* tree mutations.
+ */
+interface DecisionPass extends Pass {
+    run(report: AnalysisReport, context: PipelineContext): TransformationPlan;
+}
+/**
+ * A TransformPass receives the current Green Tree together with a
+ * TransformationPlan and returns a **new** Green Tree.  It MUST NOT
+ * mutate the original tree — immutability guarantees deterministic
+ * replay and debugging.
+ */
+interface TransformPass extends Pass {
+    run(tree: GreenNode, plan: TransformationPlan, context: PipelineContext): GreenNode;
+}
+/**
+ * A single action described by a TransformationPlan.
+ * `kind` tells the TransformPass what to do; `payload` carries
+ * per-kind parameters.
+ */
+interface TransformAction {
+    readonly kind: string;
+    readonly payload: Record<string, unknown>;
+}
+/**
+ * Ordered set of actions that a DecisionPass produces.
+ */
+interface TransformationPlan {
+    readonly actions: readonly TransformAction[];
+}
+
+/**
+ * Quasar Analysis Framework — Pipeline Stage
+ *
+ * Passes are grouped into stages that execute in order:
+ *
+ *   1. Analysis  — observe the tree, produce Contributions
+ *   2. Decision  — consume the AnalysisReport, produce a TransformationPlan
+ *   3. Transform — apply the plan to produce a new Green Tree
+ *
+ * @see Pass
+ */
+declare const PipelineStage: {
+    readonly Analysis: "analysis";
+    readonly Decision: "decision";
+    readonly Transform: "transform";
+};
+type PipelineStage = (typeof PipelineStage)[keyof typeof PipelineStage];
+
+/**
+ * Quasar Analysis Framework — Pipeline
+ *
+ * The Pipeline is itself a Pass — it can be composed inside larger
+ * pipelines.  Execution is strictly ordered:
+ *
+ *   1. All analysis passes run, collecting contributions.
+ *   2. The aggregated AnalysisReport is fed to each decision pass.
+ *   3. Each transform pass receives the current tree + plan and
+ *      returns a new tree (never mutating the original).
+ *
+ * @example
+ * ```ts
+ * const pipeline = new Pipeline([
+ *   { stage: 'analysis', pass: new CharacterCountAnalyzer() },
+ * ])
+ * const report = pipeline.run(tree, context)
+ * ```
+ */
+
+interface StageEntry {
+    readonly stage: PipelineStage;
+    readonly pass: AnalyzerPass | DecisionPass | TransformPass;
+}
+interface PipelineResult {
+    /** The final (possibly transformed) Green Tree. */
+    readonly tree: GreenNode;
+    /** The aggregated analysis report. */
+    readonly report: AnalysisReport;
+}
+declare class Pipeline {
+    private readonly stages;
+    constructor(stages: readonly StageEntry[]);
+    /**
+     * Execute the full pipeline against `tree` with the given `context`.
+     *
+     * @returns The final tree and analysis report.
+     */
+    run(tree: GreenNode, context: PipelineContext): PipelineResult;
+    /**
+     * Use PipelineBuilder to construct a Pipeline:
+     *
+     * ```ts
+     * import { PipelineBuilder } from './PipelineBuilder'
+     * const pipeline = new PipelineBuilder()
+     *   .analysis(new CharacterCountAnalyzer())
+     *   .build()
+     * ```
+     */
+    private runAnalysis;
+    private runDecision;
+    private runTransform;
+    private buildReport;
+}
+
+/**
+ * Quasar Analysis Framework — Pipeline Builder
+ *
+ * Provides a fluent API for assembling a Pipeline from individually
+ * registered passes.  Each stage (analysis / decision / transform)
+ * has its own registration method so TypeScript catches misuse at
+ * compile time.
+ *
+ * @example
+ * ```ts
+ * const pipeline = Pipeline
+ *   .builder()
+ *   .analysis(new CharacterCountAnalyzer())
+ *   .decision(new DefaultDecision())
+ *   .transform(new CollapseGradientTransform())
+ *   .build()
+ * ```
+ */
+
+declare class PipelineBuilder {
+    private readonly passes;
+    /** Register one or more AnalyzerPasses (observation stage). */
+    analysis(...passes: AnalyzerPass[]): this;
+    /** Register one or more DecisionPasses (planning stage). */
+    decision(...passes: DecisionPass[]): this;
+    /** Register one or more TransformPasses (mutation stage). */
+    transform(...passes: TransformPass[]): this;
+    /** Build the Pipeline from the registered passes. */
+    build(): Pipeline;
+}
+
+/**
+ * Quasar Analysis Framework — Character Count Analyzer (Proof of Concept)
+ *
+ * The simplest possible AnalyzerPass: it walks the Green Tree and counts
+ * text characters.  This validates that the full pipeline works:
+ *
+ *   Green Tree → Analyzer → Contribution → Aggregated Report
+ *
+ * No algorithms, no colours, no decisions — just validating the pipe.
+ */
+
+declare class CharacterCountAnalyzer implements AnalyzerPass {
+    readonly id = "character-count";
+    run(tree: GreenNode, _context: PipelineContext): Contribution[];
+    private countChars;
+}
+
+/**
+ * Quasar Analysis Framework — Mergeable Color Analyzer
+ *
+ * Detects sequences of consecutive [color=#HEX] wrappers where ALL
+ * adjacent colours are identical.  These are optimisation opportunities:
+ * the user could merge them into a single `[color]` tag.
+ *
+ * Example:
+ *   [color=#FF0000]H[/color][color=#FF0000]e[/color] → mergeable
+ *   [color=#FF0000]H[/color][color=#EE1100]e[/color] → NOT mergeable
+ *
+ * @see OptimizationContribution
+ */
+
+declare class MergeableColorAnalyzer implements AnalyzerPass {
+    readonly id = "mergeable-color";
+    run(tree: GreenNode, _context: PipelineContext): Contribution[];
+    /**
+     * Walk the tree and find consecutive color nodes with identical colours.
+     */
+    private findMergeableColorSequences;
+    private emitMergeable;
+}
+
+/**
+ * Quasar Analysis Framework — Gradient Analyzer (v2)
+ *
+ * Detects sequences of [color=#HEX] tags that form a gradient pattern
+ * and reports them as SemanticContributions with a confidence score.
+ *
+ * ## Refinements over v1
+ *
+ * 1. **OKLab color space** — Uses OKLab (Bottosson 2020) for perceptual
+ *    colour distance instead of RGB.  Two colours with small OKLab distance
+ *    look nearly identical to the human eye, making gradient detection
+ *    much more accurate.
+ *
+ * 2. **Change-point detection** — Identifies gradient *stops* even when
+ *    plateaus (runs of identical colour) exist, so a sequence like
+ *    RRRR→G→BBBB is correctly parsed as a 3-stop gradient rather than
+ *    a failed linear interpolation.
+ *
+ * 3. **Sharper sigmoid (k=6)** — Better separation between "likely
+ *    gradient" and "maybe gradient" at the decision thresholds.
+ *
+ * ## Confidence features (weights sum to 1.0)
+ *
+ *   - uniformPerceptualSpacing  (+0.30)
+ *   - contiguousWrappers        (+0.25)
+ *   - noFormattingBreaks        (+0.15)
+ *   - monotonicProgression      (+0.20)
+ *   - lowPerceptualError        (+0.10)
+ *
+ * @see SemanticContribution
+ */
+
+interface GradientModel {
+    readonly colors: string[];
+    readonly easing: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
+    readonly stops: GradientStop[];
+    readonly rangeStart: number;
+    readonly rangeEnd: number;
+    readonly charCount: number;
+    readonly diagnostics: GradientDiagnostics;
+}
+interface GradientStop {
+    /** Hex colour at this stop */
+    readonly color: string;
+    /** Normalised position 0-1 */
+    readonly position: number;
+}
+interface GradientDiagnostics {
+    readonly uniformSpacing: boolean;
+    readonly monotonic: boolean;
+    readonly plateauCount: number;
+    readonly maxPerceptualError: number;
+    readonly stopCount: number;
+    readonly featureScores: Readonly<Record<string, number>>;
+}
+declare class GradientAnalyzer implements AnalyzerPass {
+    readonly id = "gradient-analyzer";
+    run(tree: GreenNode, _context: PipelineContext): Contribution[];
+    private findGradients;
+    /**
+     * Detect gradient stops from a sequence of hex colours, handling plateaus.
+     *
+     * Algorithm: Scan for "significant changes" in perceptual distance.
+     * Wherever the cumulative perceptual distance from the last stop exceeds a
+     * threshold, a new stop is recorded.  This naturally skips over plateaus.
+     */
+    private detectStops;
+    private buildDiagnostics;
+    private calculateRawScore;
+}
+
+/**
+ * Quasar Analysis Framework — Rainbow Analyzer
+ *
+ * Detects sequences of [color=#HEX] tags where the HSL hue rotates
+ * continuously while saturation and lightness remain approximately
+ * constant — the classic "rainbow" pattern.
+ *
+ * ## Confidence features
+ *
+ *   - hueRotation (+0.35) — hue changes monotonically (increasing or decreasing)
+ *   - stableSaturation (+0.20) — saturation stays within a narrow band
+ *   - stableLightness (+0.20) — lightness stays within a narrow band
+ *   - contiguousWrappers (+0.15) — no gaps in the colour sequence
+ *   - noFormattingBreaks (+0.10) — no formatting tags between colours
+ *
+ * @see SemanticContribution
+ */
+
+interface RainbowModel {
+    readonly colors: string[];
+    readonly hueStart: number;
+    readonly hueEnd: number;
+    readonly avgSaturation: number;
+    readonly avgLightness: number;
+    readonly rangeStart: number;
+    readonly rangeEnd: number;
+    readonly charCount: number;
+    readonly diagnostics: RainbowDiagnostics;
+}
+interface RainbowDiagnostics {
+    readonly hueDelta: number;
+    readonly saturationDeviation: number;
+    readonly lightnessDeviation: number;
+    readonly isContinuous: boolean;
+    readonly featureScores: Readonly<Record<string, number>>;
+}
+declare class RainbowAnalyzer implements AnalyzerPass {
+    readonly id = "rainbow-analyzer";
+    run(tree: GreenNode, _context: PipelineContext): Contribution[];
+    private findRainbows;
+    private extractHSL;
+    private analyzeRainbow;
+    private calculateRawScore;
+}
+
+/**
+ * Quasar Analysis Framework — Wave (Size Oscillation) Analyzer
+ *
+ * Detects sequences of [size=N] tags where the sizes follow a sinusoidal
+ * (or other periodic) oscillation pattern — the classic "wave/grow" effect.
+ *
+ * ## Confidence features
+ *
+ *   - periodicPattern (+0.35) — sizes follow a clear periodic pattern
+ *   - boundedRange (+0.20) — sizes stay within a plausible min-max range
+ *   - smoothTransitions (+0.20) — adjacent size differences are small
+ *   - contiguousWrappers (+0.15) — no gaps in the size sequence
+ *   - noFormattingBreaks (+0.10) — no formatting tags between size nodes
+ *
+ * @see SemanticContribution
+ */
+
+interface WaveModel {
+    readonly sizes: number[];
+    readonly minSize: number;
+    readonly maxSize: number;
+    readonly estimatedFrequency: number;
+    readonly rangeStart: number;
+    readonly rangeEnd: number;
+    readonly charCount: number;
+    readonly diagnostics: WaveDiagnostics;
+}
+interface WaveDiagnostics {
+    readonly periodicityScore: number;
+    readonly hasSymmetry: boolean;
+    readonly isBounded: boolean;
+    readonly transitionSmoothness: number;
+    readonly featureScores: Readonly<Record<string, number>>;
+}
+declare class WaveAnalyzer implements AnalyzerPass {
+    readonly id = "wave-analyzer";
+    run(tree: GreenNode, _context: PipelineContext): Contribution[];
+    private findWaves;
+    private analyzeWave;
+    private calculateRawScore;
+}
+
+/**
+ * Quasar Analysis Framework — Default Decision
+ *
+ * Consumes an AnalysisReport and produces a TransformationPlan.
+ * The decision logic depends on the PipelineContext:
+ *
+ *   - target === 'miliastry':
+ *       Aggressively collapses detected gradients (confidence ≥ 0.6).
+ *   - target === 'osu':
+ *       Only collapses very high-confidence gradients (confidence ≥ 0.95).
+ *   - mode === 'batch' || mode === 'import':
+ *       Uses the OSU threshold by default.
+ *
+ * Optimisation opportunities (mergeable colours) are always included
+ * regardless of target, but only when the count exceeds 1.
+ *
+ * @see DecisionPass
+ * @see TransformationPlan
+ */
+
+declare class DefaultDecision implements DecisionPass {
+    readonly id = "default-decision";
+    run(report: AnalysisReport, context: PipelineContext): TransformationPlan;
+    /** Map contribution label → transform action kind */
+    private labelToActionKind;
+    private handleSemantic;
+    private handleOptimization;
+}
+
+/**
+ * Quasar Analysis Framework — Collapse Gradient Transform
+ *
+ * Applies `collapse-gradient` actions from a TransformationPlan.
+ * Each action targets a sequence of adjacent [color] nodes and replaces
+ * them with a single [gradient] node containing all text children.
+ *
+ * The transform operates on the Green Tree and returns a new tree —
+ * it NEVER mutates the original.
+ *
+ * @example
+ * Before:
+ *   [color=#FF0000]H[/color][color=#EE1100]e[/color][color=#DD2200]l[/color]
+ * After:
+ *   [gradient=#FF0000,#EE1100,#DD2200]Hello[/gradient]
+ *
+ * @see TransformPass
+ */
+
+declare class CollapseGradientTransform implements TransformPass {
+    readonly id = "collapse-gradient";
+    run(tree: GreenNode, plan: TransformationPlan, _context: PipelineContext): GreenNode;
+    /**
+     * Walk the tree and collapse any sequences that fall within our ranges.
+     */
+    private transformNode;
+    /**
+     * Rebuild a node with the same kind/text/range but new children.
+     */
+    private rebuildNode;
+    /**
+     * Extract hex colour from a color node's text.
+     */
+    private extractHex;
+}
+
+/**
+ * Quasar Analysis Framework — Rainbow Collapse Transform
+ *
+ * Applies `collapse-rainbow` actions from a TransformationPlan.
+ * Replaces sequences of [color] nodes forming a hue-rotation pattern
+ * with a single [rainbow] node containing all text children.
+ *
+ * @example
+ * Before: [color=#FF0000]R[/color][color=#FFFF00]O[/color][color=#00FF00]Y[/color]
+ * After:  [rainbow]ROY[/rainbow]
+ */
+
+declare class RainbowCollapseTransform implements TransformPass {
+    readonly id = "rainbow-collapse";
+    run(tree: GreenNode, plan: TransformationPlan, _context: PipelineContext): GreenNode;
+    private transformNode;
+}
+
+/**
+ * Quasar Analysis Framework — Wave Collapse Transform
+ *
+ * Applies `collapse-wave` actions from a TransformationPlan.
+ * Replaces sequences of [size=N] nodes forming a sinusoidal pattern
+ * with a single [grow] node containing all text children and the
+ * detected size range in metadata.
+ *
+ * @example
+ * Before: [size=90]A[/size][size=150]B[/size][size=90]C[/size]
+ * After:  [grow]ABC[/grow]  (with metadata: min=90, max=150)
+ */
+
+declare class WaveCollapseTransform implements TransformPass {
+    readonly id = "wave-collapse";
+    run(tree: GreenNode, plan: TransformationPlan, _context: PipelineContext): GreenNode;
+    private transformNode;
+}
+
+/**
+ * Quasar Analysis Framework — Merge Colors Transform
+ *
+ * Applies `merge-colors` actions from a TransformationPlan.
+ * Each action targets a sequence of identical consecutive [color=#HEX]
+ * nodes and merges them into a single `[color]` wrapper with combined text.
+ *
+ * The transform operates on the Green Tree and returns a new tree —
+ * it NEVER mutates the original.
+ *
+ * @example
+ * Before:
+ *   [color=#FF0000]H[/color][color=#FF0000]e[/color][color=#FF0000]l[/color]
+ * After:
+ *   [color=#FF0000]Hel[/color]
+ *
+ * @see TransformPass
+ */
+
+declare class MergeColorsTransform implements TransformPass {
+    readonly id = "merge-colors";
+    run(tree: GreenNode, plan: TransformationPlan, _context: PipelineContext): GreenNode;
+    private transformNode;
+    private rebuildNode;
+    private extractHex;
+}
+
+export { ASTOptimizer, type AnalysisReport, type AnalyzeResult, type AnalyzerPass, type BBBlock, BBBlocksExporter, BBCODE_TAG_NAMES, type BBCodeDialect, BBCodeDocumentModel, type BBCodeDocumentModelOptions, BBCodeExporter, type BoxDrawerOptions, type BuildResult, type CentralGradientEffect, ChangeTracker, CharacterCountAnalyzer, CollapseGradientTransform, type Command, type CommandContext, CommandRegistry, type CommandResult, type Contribution, ContributionKind, type DecisionPass, DefaultDecision, DeleteNode, type Diagnostic, type DiagnosticContribution, type DiagnosticSeverity, type DiagnosticTag, type DiffKind, type DiffOperation, type DocumentChangeEvent, type DocumentEvent, DocumentEventBus, type DocumentEventHandler, DocumentModel, type DocumentNode, type DomToSVGOptions, type DomToSVGResult, type EditOperation, type ExportTarget$1 as ExportTarget, type FormatOptions, Formatter, GradientAnalyzer, type GradientDiagnostics, type GradientEffect, type GradientModel, type GradientOptions, type GradientStop, GradientTransformer, GreenNode, type GrowEffect, type GrowOptions, GrowTransformer, HTMLDocumentModel, HTMLRenderer, type HTMLRendererOptions, IncrementalParser, InsertText, JSONExporter, LYNE_ONLY_TAGS, Lexer, type LexerOptions, type LintResult, type LintRule, Linter, MILIASTRY_ONLY_TAGS, MarkdownDocumentModel, MarkdownExporter, type MatchResult, MergeColorsTransform, MergeNode, MergeableColorAnalyzer, type MetricsContribution, type MultiGradientEffect, type NodeAttributes, NodeFactory, type NodeKind, NodeMatcher, type NodeMetadata, type Operation, type OptimizationContribution, type Pass, Pipeline, PipelineBuilder, type PipelineContext, PipelineMode, type PipelineResult, PipelineStage, PluginAPI, type PluginContribution, type PluginManifest, PluginRegistry, type Query, QueryEngine, type QueryMatch, type QueryResult, RainbowAnalyzer, RainbowCollapseTransform, type RainbowDiagnostics, type RainbowEffect, type RainbowModel, type RainbowOptions, RainbowTransformer, RedNode, RedNodeStore, type Reference, type RenderNode, RenderPipeline, RenderTree, type RenderVariant, type SVGLayerInfo, SVGRenderer, SemanticAnalyzer, type SemanticContribution, type SineWaveOptions, SineWaveTransformer, type SourceRange, SplitNode, type SymbolInfo, type SymbolKind, type SymbolSearchResult, SymbolTable, type TagDefinition, type TagHandler, TagRegistry, type TextChange, TiptapExporter, type Token, type TokenKind, Transaction, type TransformAction, type TransformBias, type TransformPass, type TransformationPlan, type Transformer, TreeBuilder, TreeDiffer, type TreeEffect, type Trivia, type TriviaKind, type UIBBBlock, type UndoEntry, UndoManager, Visitor, type VisitorContext, type VisualThemeId, WaveAnalyzer, WaveCollapseTransform, type WaveDiagnostics, type WaveModel, WrapInTag, applyCentralGradient, applyEffect, applyGradient, applyGrow, applyMultiGradient, applyRainbow, bbBlockToGreenNode, bbBlocksToGreenTree, bbBlocksToRedTree, bindBoxDrawer, countTextLength, domToSVG, domToSVGResult, getBBCodeTagNames, greenLeaf, greenNode, greenToRedNode, htmlStringToGreenTree, isBlockKind, markdownAstToGreenTree, markdownAstToRedTree, morphHTML, nodeKindToTag, patchBlocksInto, tagToNodeKind, toggleBoxWithDrawer, transformOffset, transformRange, visualThemes };