@miliastry/quasar 1.0.6 → 1.1.0

package/dist/types/Syntax/GreenNode.d.ts

@@ -0,0 +1,154 @@
+/**
+ * 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.
+ */
+export 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.
+ */
+export declare function greenNode(kind: string, text: string, children?: GreenNode[], leadingWidth?: number, trailingWidth?: number, ownWidth?: number): GreenNode;
+/**
+ * Absolute offsets of `node`'s children, given where `node` itself starts.
+ *
+ * Returns `children.length + 1` entries: entry `i` is where child `i` begins
+ * and entry `i + 1` is where it ends, so a run of children `[a, b)` spans
+ * `offsets[a] .. offsets[b]`.
+ *
+ * For code that walks the green tree and needs source positions — analyzers
+ * reporting diagnostics, transforms recording what they collapsed. Green nodes
+ * have no positions of their own, so a walk that needs them accumulates them,
+ * and this is the one-liner for doing that at a single level.
+ */
+export declare function childOffsets(node: GreenNode, start: number): number[];
+/**
+ * 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.
+ */
+export declare function greenLeaf(kind: string, text: string, width?: number): GreenNode;

package/dist/types/Syntax/GreenNodePool.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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.
+ */
+import { GreenNode } from './GreenNode';
+export interface GreenNodePoolStats {
+    size: number;
+    hits: number;
+    misses: number;
+    deduplicatedCount: number;
+    /** Number of hash collisions that were verified as true duplicates */
+    collisionHits: number;
+    /** Number of hash collisions that were false positives */
+    collisionMisses: number;
+}
+/**
+ * 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.
+ */
+export type InterningMode = 'leaves' | 'full';
+export declare class GreenNodePool {
+    private static _instance;
+    private readonly _mode;
+    private _leafCache;
+    private _nodeCache;
+    private _hits;
+    private _misses;
+    private _collisionHits;
+    private _collisionMisses;
+    /** Singleton instance accessor (for backward compatibility) */
+    static get instance(): GreenNodePool;
+    constructor(mode?: InterningMode);
+    /**
+     * Create a new isolated interner (for per-document use).
+     * The returned pool shares no cache with the singleton.
+     */
+    static create(mode?: InterningMode): GreenNodePool;
+    /**
+     * Intern (deduplicate) a leaf GreenNode.
+     * If an identical leaf exists in the pool, returns the cached instance.
+     * Leaf key: `kind:text` — deterministic, no collision possible.
+     */
+    internLeaf(kind: string, text: string, width?: number): GreenNode;
+    /**
+     * Intern an internal GreenNode (structural sharing).
+     *
+     * Strategy:
+     * 1. Compute hash from (kind, text, children's _hash values) — O(n) where n = children count
+     * 2. Look up hash in bucket — O(1) amortized
+     * 3. Verify with reference equality on children — O(n) but cache-friendly
+     * 4. If verified, return existing (structural sharing achieved)
+     * 5. If not, store and return new node
+     *
+     * Because children are interned bottom-up, identical children are the same reference.
+     * This makes reference equality a perfect structural equality check.
+     */
+    internNode(kind: string, text: string, children: GreenNode[], leadingWidth?: number, trailingWidth?: number): GreenNode;
+    /**
+     * Compute a bucket key for internal nodes.
+     * Uses (kind, text, children-count, first-child-hash) for fast bucketing.
+     * This gives O(1) bucket lookup in the common case.
+     */
+    private computeBucketKey;
+    private fnv1a;
+    private hashCombine;
+    /** Clear the pool cache */
+    clear(): void;
+    /** Get current pool statistics */
+    get stats(): GreenNodePoolStats;
+}
+/**
+ * Convenience helper for interning green leaves, over the shared singleton.
+ *
+ * The internal-node twin of this helper used to sit alongside it and was
+ * removed: nothing imported it, and it could not have worked if anything had.
+ * `GreenNodePool.instance` is built with the default `'leaves'` mode, and
+ * `internNode` returns a fresh `GreenNode` unconditionally in that mode — so
+ * the one thing the helper existed for, structural sharing of internal nodes,
+ * was unreachable through the only pool it could reach. Interning internal
+ * nodes is done by passing a `GreenNodePool.create('full')` to the parser,
+ * which is what `BBCodeDocumentModel` does per document.
+ */
+export declare function internGreenLeaf(kind: string, text: string, width?: number): GreenNode;

package/dist/types/Syntax/NodeMatcher.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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
+ */
+import { RedNode } from './RedNode';
+import type { NodeId } from '../Types/core';
+export type MatchStatus = 'exact' | 'moved' | 'updated' | 'inserted' | 'deleted' | 'merged' | 'split';
+export interface MatchResult {
+    oldNode: RedNode | null;
+    newNode: RedNode | null;
+    status: MatchStatus;
+    confidence: number;
+}
+export 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;
+    };
+}
+export 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;
+}

package/dist/types/Syntax/RedNode.d.ts

@@ -0,0 +1,280 @@
+/**
+ * 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.
+ */
+import { GreenNode } from './GreenNode';
+import type { NodeId, DocumentNode, NodeKind, NodeMetadata } from '../Types/core';
+import type { Diagnostic } from '../Types/diagnostics';
+import type { Range } from '../Types/tokens';
+export 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;
+    /**
+     * Push `delta` into every red node that lives under `node` — its title nodes
+     * as well as its children.
+     *
+     * The title subtree of a rich `[box=[b]heading[/b]]` is stored in
+     * `metadata.titleNodes`, never appended to `children`, so a loop over
+     * `children` alone leaves it at pre-edit offsets. That is not cosmetic:
+     * `findNodeAtOffset` consults `metadata.titleNodes` BEFORE `children`, so a
+     * stale title range mis-resolves caret, hover and selection inside the
+     * heading. Both shift paths — the recursive one and `materialize`'s ancestor
+     * loop — route through here so they cannot drift apart again.
+     */
+    private static shiftDescendants;
+    /**
+     * 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;
+}