@voithos-labs/aragonite 0.10.2 → 0.10.4

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

@@ -1,132 +1,40 @@
 /**
- * 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`.
+ * The split and merge primitives, the two ops that re-tile a body's blocks around a caret, plus
+ * the join cleanup every destructive join crosses (live-mode.md § 4.5). They mutate and report;
+ * the settle around them is the ceremony's (`settle.ts`).
  */
-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 CstNode } from '../core/nodes';
+import type { 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;
+import { type BodyParentArg, type NodeParent } from './node-primitives';
 /** 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. */
+ *  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.
+ * The landing a site is about to consume, held to the primitive's answer (G1.34): 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.
+ * with the nodes being written, so the guard answers for sink N+1.
  */
 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.
+ * original ID and the whole structural suffix (a setext underline); the second half opens with a
+ * blank separator wherever one does structural work ({@link separatorSplitsOffNextLine}).
  */
 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
+ * `join.mergedRaw` with the delimiter runs the join orphaned at its seam dropped, live only
  * (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.
  */
@@ -134,7 +42,7 @@ export declare function cleanJoinedRaw(join: JoinSeam, presentationMode: Present
 /**
  * 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).
+ * where the two sides now meet.
  */
 export declare function cutRangeFromDisplay(node: NodeView, display: string, range: {
     start: number;
@@ -144,7 +52,7 @@ export declare function cutRangeFromDisplay(node: NodeView, display: string, ran
     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. */
+ *  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;
@@ -160,8 +68,7 @@ export interface MergeIntoPrevResult {
 }
 /**
  * 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
+ * reparsing concatenated raw, which preserves prev's component identity and IME state. 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;
@@ -170,127 +77,3 @@ export declare function mergeIntoPrevDeepLeaf(parent: BodyParentArg, blockIndex:
  * 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;