@voithos-labs/aragonite 0.10.1

package/dist/tree-operations/node-ops.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Kind-agnostic CST node mutations: path resolution, split, merge, delete, update. Children-array
+ * contract: an op mutating a container's top-level children takes the array as a parameter and
+ * mutates that, never `node.children` — the caller owns and republishes it, so a direct splice is
+ * overwritten. A descendant found by walking the live tree is the exception: mutate it in place on
+ * a caller-unshared spine (`unshare.ts`), a STRUCTURAL one via `commitMultiScope`.
+ */
+import type { AnyBlockKind, CstNode, Document } from '../core/nodes';
+import type { DocumentView, NodeView } from '../core/node-views';
+import { type GrammarView } from '../schema/block-openers';
+import { type CleanedJoin, type InlineResolverRef, type JoinSeam } from '../schema/inline-construct-policy';
+import type { PresentationMode } from '../presentation-mode';
+import type { SharingState } from './sharing';
+import { type StructuralChange } from './structural-change';
+/** A children array an op mutates structurally — splice, delete, reorder. */
+export type NodeParent = {
+    children: CstNode[];
+};
+/**
+ * A {@link NodeParent} that has answered which container owns it — the byte sinks need that
+ * answer for the owner's `bodyWrite` grammar and its wrap slots. Both nullable rather than
+ * optional so every byte-writing site answers: `undefined` is a real answer (the document
+ * root), skipping the question is a compile error.
+ */
+export type BodyParent = NodeParent & {
+    ownerKind: AnyBlockKind | undefined;
+    owner: CstNode | undefined;
+    /**
+     * The document root's foldable trailing line, when these children are its.
+     * Optional, not nullable: only a ceremony-backed site may carry it, because the settle
+     * that consumes it appends a block — the out-of-ceremony write paths stay slotless so a
+     * structural materialization is unrepresentable there.
+     */
+    suffix?: string;
+};
+/**
+ * What the byte sinks accept. A whole `Document` is admitted because it IS the answer
+ * (the root owns no body grammar); a bare `{ children }` literal still cannot compile.
+ */
+export type BodyParentArg = BodyParent | Document;
+/**
+ * What the separator settles accept: anything that can answer where the body starts, whether
+ * it holds the owner's kind directly (the container node, the Document) or the sink's answer
+ * to it ({@link BodyParentArg}, which this absorbs). Wider than the byte sinks: a settle
+ * writes a line ending, not body text.
+ */
+export type SeparatorParent = {
+    kind?: string;
+    ownerKind?: AnyBlockKind;
+    suffix?: string;
+    children?: CstNode[];
+    owner?: CstNode;
+};
+/**
+ * Text made legal as a child's raw inside a container of kind `ownerKind`. Exported for
+ * sinks that build their own bytes rather than handing text to {@link updateNodeContent}.
+ */
+export declare function normalizeBodyWrite(ownerKind: AnyBlockKind | undefined, raw: string): string;
+/**
+ * `raw` made legal as `node`'s OWN bytes — {@link normalizeBodyWrite}'s node-side twin, for the
+ * kind's own grammar rather than its container's. Sinks that REPLACE the node with a reparse of
+ * the result call this door: the reparse re-derives metadata from the bytes, so structure the
+ * rule restores from the old metadata (a fence closer a truncation consumed) must land first.
+ */
+export declare function normalizeOwnRaw(node: NodeView, raw: string): string;
+/**
+ * Write `raw` as `node`'s OWN bytes through its kind's rule — {@link normalizeOwnRaw}'s in-place
+ * sink. Every sink writing a leaf's bytes without the kind's surface in front of it owes one of
+ * the two (pinned by `lint/leaf-raw-write-rule`).
+ */
+export declare function writeOwnRaw(node: CstNode, raw: string, grammar: GrammarView | undefined): void;
+/**
+ * The paragraph mint. Every argument is required: a paragraph's raw ENDS in a line ending,
+ * so a mint site must answer which document it lands in (G4.20) rather than strand a lone
+ * LF in a CRLF file. Returns a fresh node every call — a shared instance would alias across
+ * tree positions and corrupt the snapshot/unshare model (G1.9).
+ */
+export declare function paragraphNode(leadingTrivia: string, text: string, lineEnding: string): CstNode;
+/** The empty-paragraph placeholder keeping an emptied document or container caret-addressable. */
+export declare function emptyParagraph(leadingTrivia: string, lineEnding: string): CstNode;
+export declare function nodeAt(doc: Document, path: number[]): CstNode | Document | null;
+export declare function nodeAt(doc: DocumentView, path: number[]): NodeView | DocumentView | null;
+/** `nodeAt` pre-narrowed through `isBlockNode`: null at the document root or on no match. */
+export declare function blockNodeAt(doc: Document, path: number[]): CstNode | null;
+export declare function blockNodeAt(doc: DocumentView, path: number[]): NodeView | null;
+/**
+ * Narrow a `nodeAt` result to `CstNode`. Structural, not kind-based: a plugin may mint
+ * `'document'` as a block kind, so only the absence of `raw` discriminates.
+ */
+export declare function isBlockNode(node: CstNode | Document): node is CstNode;
+export declare function isBlockNode(node: NodeView | DocumentView): node is NodeView;
+/** What a split leaves the caret: the structural splice, plus where the second half's head
+ *  landed — past `blockIndex + 1` when the first half reparsed to several blocks. */
+export interface SplitResult {
+    change: StructuralChange;
+    secondHalfIndex: number;
+}
+/**
+ * The landing a site is about to consume, held to the primitive's answer (G1.34). The
+ * top-level path seats the caret at it and the list path splices at it, so both cross this
+ * on their way to using it; a re-derived `blockIndex + 1` warns instead of shipping.
+ */
+export declare function assertSplitLanding(split: SplitResult, landing: number): void;
+/**
+ * What a one-slot sink is about to put in its slot, held to one node (G1.35). Asked at the WRITE
+ * with the nodes being written, so the guard answers for sink N+1 — one that skips the refusal its
+ * siblings make, or splices a plural replacement into a slot that holds one.
+ */
+export declare function assertSingleNodeSink(sink: string, installed: readonly CstNode[]): void;
+/**
+ * Split the node at `blockIndex` at raw `offset` (display-relative). The first half inherits the
+ * original ID and the whole structural suffix (a setext underline), which a plain cut would strand
+ * below as junk. The second half opens with a blank separator wherever one does structural work
+ * ({@link separatorSplitsOffNextLine}) — without it GFM lazy continuation folds the halves back
+ * into one block on reload.
+ */
+export declare function splitNode(parent: BodyParentArg, blockIndex: number, offset: number, sharing: SharingState | undefined, presentationMode: PresentationMode | undefined, linkRef: InlineResolverRef | undefined): SplitResult;
+/**
+ * The stand-in for whatever the user types into the second half: the maximally-continuable
+ * line, so the predicate answers for the worst case rather than one construct. Openers are
+ * arbitrary code, so no line is unclaimable by construction — {@link probeLineOpensAsProse}
+ * is the runtime check.
+ */
+export declare const NEXT_PROSE_LINE = "x";
+/** Whether the ambient grammar still leaves {@link NEXT_PROSE_LINE} an ordinary paragraph. */
+export declare function probeLineOpensAsProse(grammar?: GrammarView): boolean;
+/**
+ * `join.mergedRaw` with the delimiter runs the join orphaned at its seam dropped — live only,
+ * where those runs are unpainted and a literal concatenation surfaces bytes the reader never saw
+ * (live-mode.md § 4.5). The one registered cleaner verifies its own bytes and otherwise declines,
+ * leaving the literal join every other mode gets. Every destructive join crosses this door.
+ */
+export declare function cleanJoinedRaw(join: JoinSeam, presentationMode: PresentationMode | undefined): CleanedJoin;
+/**
+ * The bytes a single-block edit leaves when it deletes `range` out of `display`. A delete-then-
+ * insert is a join like any other, so it crosses the same cleanup, and the returned offset is
+ * where the two sides now meet (a cleanup that drops a run on the first side moves it).
+ */
+export declare function cutRangeFromDisplay(node: NodeView, display: string, range: {
+    start: number;
+    end: number;
+}, presentationMode: PresentationMode | undefined, linkRef: InlineResolverRef | undefined): {
+    display: string;
+    offset: number;
+};
+/** What a join leaves the caret: the structural splice, plus where the two blocks met in the
+ *  survivor's bytes — which a seam cleanup moves when it drops a run on the first block's side. */
+export interface MergeResult {
+    change: StructuralChange;
+    joinOffset: number;
+}
+/**
+ * `targetPath` is relative to `parent.children[blockIndex - 1]`: empty means prev itself
+ * is the leaf, non-empty walks into prev's container subtree.
+ */
+export interface MergeIntoPrevResult {
+    targetPath: number[];
+    joinOffset: number;
+    change: StructuralChange;
+}
+/**
+ * Merge `curr` into the deepest prose leaf of `prev`, writing into that leaf rather than
+ * reparsing concatenated raw — preserves prev's component identity, IME state, and the
+ * leaves' inline caches. Pass `sharing` to unshare everything the merge writes. Null when
+ * no mergeable leaf exists, so the caller can fall back to move-focus.
+ */
+export declare function mergeIntoPrevDeepLeaf(parent: BodyParentArg, blockIndex: number, sharing: SharingState | undefined, presentationMode: PresentationMode | undefined, linkRef: InlineResolverRef | undefined, grammar?: GrammarView): MergeIntoPrevResult | null;
+/**
+ * Merge the node at `blockIndex` with its successor; combined raw is re-parsed and the
+ * merged block inherits the current block's ID. Noop at the tail.
+ */
+export declare function mergeWithNext(parent: NodeParent, blockIndex: number, presentationMode: PresentationMode | undefined, linkRef: InlineResolverRef | undefined): MergeResult;
+/**
+ * Settle the separator at `index`: nothing above it needs one at the body head or below a blank
+ * block, where the parser would read the extra line as one more empty paragraph. Every splice
+ * that changes what precedes a block settles through this family (syntax-tree.md § Blank lines).
+ * `sharing` owns the write (G1.9).
+ */
+export declare function clearRedundantSeparator(parent: SeparatorParent, index: number, sharing?: SharingState): void;
+/**
+ * A blank block IS a blank line, so it and its follower share ONE separator: two of them reload
+ * as a second empty paragraph (G2.13). The follower's is the one that stands, so a later fill of
+ * this slot (a paste over a cut range) still finds the follower separated. The run-level twin
+ * {@link settleSeparatorOnBlank} keeps the first already-standing line instead, the same bytes
+ * the other way round.
+ */
+export declare function dropDoubledSeparator(parent: SeparatorParent, index: number, sharing?: SharingState): void;
+/**
+ * The separator a block takes back when it stops being blank: its own blank line was what stood
+ * between it and a non-blank predecessor. Call at the fill — {@link clearRedundantSeparator}
+ * frees a separator in exactly the cases this declines, and a block that was never blank keeps
+ * whatever its bytes earned (a paragraph under a heading needs none).
+ */
+export declare function restoreSeparatorOnFill(parent: SeparatorParent, index: number, sharing?: SharingState): void;
+/**
+ * The settle a block turning INTO a blank line owes: it joins the blank run around it, and a run
+ * carries exactly ONE separating line — across every block in it AND its follower, since a blank
+ * block is the follower's line too. The line already standing is the one kept, wherever in the
+ * run it sits; a mint lands at the run's head, the only slot one may take.
+ */
+export declare function settleSeparatorOnBlank(parent: SeparatorParent, index: number, sharing?: SharingState): void;
+/**
+ * The commit ceremony's settle door: derive the spliced window from the change and settle it
+ * against `before`, the pre-mutate children the ceremony still holds. Nodes surviving inside the
+ * window are not removals, so a coarse descriptor over an in-place write settles as one.
+ * `tracked` is the committing door's caret, carried through the folds. Returns the change widened
+ * by a tail line the settle materialized.
+ */
+export declare function settleSeparator(parent: SeparatorParent, before: readonly CstNode[], change: StructuralChange, sharing?: SharingState, tracked?: TrackedPosition): StructuralChange;
+/**
+ * The out-of-commit-scope twin of {@link settleSeparator}, for a container discovered by walking
+ * the live tree: it splices through the `childIds` door and reads the pre-splice span itself.
+ */
+export declare function spliceChildrenSettled(parent: CstNode | Document, at: number, removeCount: number, replacement: CstNode[], sharing?: SharingState): void;
+/**
+ * A byte position the folds carry with them: the slot it lives in, and its offset inside that
+ * slot's raw. Written in place, since each fold re-tiles the bytes under it.
+ */
+export interface TrackedPosition {
+    index: number;
+    offset: number;
+}
+/** What a splice settled: its change widened by every fold, and where a tracked index landed. */
+export interface SettledSplice {
+    change: StructuralChange;
+    landing: number;
+}
+/**
+ * The seam question at every join the splice at `at` disturbed — its window's two edges and the
+ * joins inside it — since a move can invalidate a join that was already correct. Each
+ * fold cascades downward, so the next seam is asked past what that one ate. `tracked` rides the
+ * folds for a caller placing a caret in bytes an absorb can move. `headProbe` names the one block
+ * whose bytes changed, letting each ask decline on its first line alone; dropped once anything
+ * folds, since the index it names has moved by then.
+ */
+export declare function absorbWindowSeams(parent: NodeParent, at: number, added: number, landing: number, change: StructuralChange, sharing?: SharingState, tracked?: TrackedPosition, headProbe?: number, onBeforeSplice?: () => void): SettledSplice;
+/** The materialized tail reported inside the sink's one contiguous window. */
+export declare function widenForTailMint(change: StructuralChange, before: number, after: number): StructuralChange;
+/**
+ * Remove the node at `blockIndex`, leaving the next sibling separated from its new predecessor
+ * and no more. Takes {@link BodyParentArg} because the settle can hand a freed line to the
+ * owner's wrap slots. Pass `sharing` to unshare the nodes written — the successor's trivia is
+ * the op's only in-place write.
+ */
+export declare function deleteNode(parent: BodyParentArg, blockIndex: number, sharing?: SharingState): StructuralChange;
+/** What a content write settled: its change widened by every fold, and the offset the written
+ *  text starts at inside that change's window — nonzero once a fold above absorbed it. */
+export interface SettledContent {
+    change: StructuralChange;
+    textStart: number;
+}
+/**
+ * Update raw and re-parse. The sole re-parse transfer funnel: a kind change mints the reparsed
+ * block into the slot rather than reassigning `kind` in place, and multi-block text mints every
+ * parsed block. Only a same-kind single-block edit writes fields in place, so routine typing keeps
+ * the node's object identity; `replacePreservingFirst` carries the id/ref across a mint. `sharing`
+ * owns the separator settle's writes, which land on the run's OTHER blocks.
+ */
+export declare function updateNodeContent(parent: BodyParentArg, blockIndex: number, text: string, grammar?: GrammarView, sharing?: SharingState): SettledContent;
+/**
+ * What the grammar opens `line` as, read in isolation — the opener-significance test, asked of
+ * the opener registry and never a kind list, so a kind registered later is covered the day it
+ * registers.
+ */
+export declare function lineOpensAs(line: string, grammar?: GrammarView): AnyBlockKind;
+/**
+ * Re-derive the container at `index` from its own (already rebuilt) raw, replacing it in
+ * the slot when that raw now opens as a different kind. The container twin of
+ * `updateNodeContent`'s kind-change arm (editor.md § 8), which no leaf reparse can see.
+ * Eligibility is the opener registry, not a kind list — registering an opener is exactly
+ * the claim that `parse(raw)` reproduces the kind, so re-deriving one without would destroy it.
+ */
+export declare function reclassifyContainer(parent: NodeParent, index: number, grammar?: GrammarView): CstNode | null;
+/**
+ * Map a post-edit caret offset (in the committed text) to the parsed block it falls in,
+ * as a local display offset. The first block's body starts at 0; an offset inside
+ * inter-block trivia lands at the next block's start; past-the-end clamps to the last.
+ */
+export declare function focusTargetInReplacement(nodes: readonly NodeView[], offset: number): {
+    index: number;
+    offset: number;
+};
+/**
+ * Where a caret at `offset` in the written text lands once {@link updateNodeContent}'s folds
+ * settled: an absorb ABOVE leaves the predecessor holding the bytes, so the slot the gesture
+ * named is gone and the offset carries what that predecessor put in front of it. Every caret
+ * door onto the content funnel asks this, so the settle is answered in one place.
+ */
+export declare function settledCaretTarget(settled: SettledContent, at: number, offset: number, children: readonly NodeView[]): {
+    index: number;
+    offset: number;
+};
+/** First node inherits the original block's leadingTrivia; subsequent nodes keep theirs. */
+export declare function normalizeReplacementTrivia(original: CstNode, replacement: CstNode[]): CstNode[];
+/** Ensure every container has at least one child block, so the cursor always has a target. */
+export declare function ensureEditableContainers(node: CstNode): void;