@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/tree-operations/settle.js

@@ -1,11 +1,12 @@
 /**
- * The separator settle every splice owes its neighbourhood (syntax-tree.md § Blank lines), the
- * seam absorb behind it (editor.md § 8), and the delete primitive built on both. `sharing` owns
- * every in-place write (G1.9); the retire census in `lint/separator-write-doors.test.ts` names
- * every door here.
+ * Recomputes the blank-line separators an edit left stale, merges neighbours that would re-read
+ * as one block on reload, and deletes a block on top of both (`docs/design/syntax-tree.md` § Blank
+ * lines). Every in-place write goes through `sharing`, so no undo snapshot sees it (G1.9), and
+ * `lint/separator-write-doors.test.ts` must list every function here that writes a separator.
  */
-import { isBlankParagraph, parse } from '../core/parser';
-import { trailingLineEnding, trimTrailingLineEnding } from '../core/lines';
+import { isBlankParagraph, readBlocks } from '../core/parser';
+import { firstLineEnding, ownTrailingLineEnding, splitLines, trimTrailingLineEnding } from '../core/lines';
+import { tableTakesLine } from '../core/parsers/table';
 import { devWarn } from '../dev-warn';
 import { assignChildIdsDeep } from '../block-id';
 import { tryGetBlockKindDescriptor } from '../schema/block-kind-descriptor';
@@ -13,14 +14,15 @@ import { dropChildSpans } from '../schema/child-spans';
 import { assertInvariant } from '../assert';
 import { checkStructuralDescriptor } from '../invariants/structural-descriptor';
 import { ensureUnsharedChild } from './unshare';
+import { lacksSublistSeparator, settleSublistSeparator } from './list/sublist-separator';
 import { spliceChildren } from './children';
 import { spliceMany } from './splice-many';
 import { applyStructuralChangeToIdsRefs } from './structural-change';
 import { ensureEditableContainers } from './node-primitives';
 // ── Separators ──
 /**
- * Settle the separator at `index`: nothing needs one at the body head or below a blank block,
- * where the parser would read the extra line as one more empty paragraph.
+ * Drop the separator at `index` where nothing needs one: at the body head, or below a blank
+ * block, where the parser would read the extra line as one more empty paragraph.
  */
 export function clearRedundantSeparator(parent, index, sharing) {
     retireChildSpans(parent);
@@ -39,8 +41,8 @@ export function clearRedundantSeparator(parent, index, sharing) {
     absorbWrapPrefix(parent, bodyStart, index, freed);
 }
 /**
- * A blank block IS a blank line, so it and its follower share ONE separator (G2.13). The
- * follower's stands, so a later fill of this slot still finds the follower separated.
+ * A blank block is itself a blank line, so it and its follower share one separator (G2.13). The
+ * follower's is kept, so filling the blank block later still finds the follower separated.
  */
 export function dropDoubledSeparator(parent, index, sharing) {
     retireChildSpans(parent);
@@ -54,7 +56,7 @@ export function dropDoubledSeparator(parent, index, sharing) {
 }
 /**
  * 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.
+ * between it and a non-blank predecessor. Call when the block is filled.
  */
 export function restoreSeparatorOnFill(parent, index, sharing) {
     retireChildSpans(parent);
@@ -64,8 +66,8 @@ export function restoreSeparatorOnFill(parent, index, sharing) {
     mintSeparator(parent, index, sharing);
 }
 /**
- * The separator the block BELOW a consumed blank line takes back: the same mint minus the
- * blank-self guard, declined where its own follower already holds one (G2.13).
+ * The separator the block below a consumed blank line takes back, skipped for a blank block whose
+ * follower already holds one, since the two share it (G2.13).
  */
 export function restoreSeparatorAfterBlank(parent, index, sharing) {
     retireChildSpans(parent);
@@ -78,9 +80,8 @@ export function restoreSeparatorAfterBlank(parent, index, sharing) {
     mintSeparator(parent, index, sharing);
 }
 /**
- * The settle a block turning INTO a blank line owes: the run it joins carries exactly ONE
- * separating line across every block in it AND its follower. The line already standing is
- * kept; a mint lands at the run's head, the only slot one may take.
+ * A block turned blank joins a run that, with its follower, must carry exactly one separating line;
+ * a standing line is kept, and a new one goes at the run's head, the only place one may sit.
  */
 export function settleSeparatorOnBlank(parent, index, sharing) {
     retireChildSpans(parent);
@@ -100,13 +101,13 @@ export function settleSeparatorOnBlank(parent, index, sharing) {
         if (children[i].leadingTrivia !== '')
             standing.push(i);
     }
-    // A chrome line bounding the run beside PROSE eats one line as the wrap's peel
-    // (`innerPrefix`/`innerSuffix`), on top of the run's own count; an all-blank body owes none.
+    // A fence line at either end of the run strips one blank line into `innerPrefix`/`innerSuffix`
+    // on top of the run's own count when prose sits on the other side; an all-blank body needs none.
     const wrap = bodyWrapOf(parent);
     const slots = wrapSlotsOf(parent);
     const bodyEnd = children.length - 1;
-    // A run of two or more that IS the whole body sits against both chrome lines: the reload
-    // peels a line into each slot before it materializes a block, so it owes BOTH.
+    // A run of two or more that is the whole body sits against both fence lines, and the reload
+    // strips a line into each of `innerPrefix` and `innerSuffix`, so the run supplies both.
     const twoPeelBody = !!slots &&
         wrap?.afterOpenerLine === true &&
         wrap.beforeCloserLine === true &&
@@ -115,23 +116,24 @@ export function settleSeparatorOnBlank(parent, index, sharing) {
         start < end;
     const tailBelowProse = start > bodyStart && end === bodyEnd;
     if (slots && wrap?.beforeCloserLine && (tailBelowProse || twoPeelBody) && !slots.innerSuffix) {
-        slots.innerSuffix = trailingLineEnding(children[end].raw);
+        // A blank block's bytes are its line ending.
+        slots.innerSuffix = ownTrailingLineEnding(children[end].raw);
     }
-    // The reverse: a deletion can leave a lone blank as the WHOLE body, where the closer
-    // peel no longer engages beside the opener's, so the run gives the extra line back.
+    // The reverse: beside a lone blank block that is the whole body, the closer strips no line of
+    // its own apart from the opener's, so the run gives the extra line back.
     const loneBlankBody = start === bodyStart && end === bodyEnd && start === end;
     if (slots && loneBlankBody && slots.innerSuffix && (slots.innerPrefix || standing.length > 0)) {
         slots.innerSuffix = '';
     }
     const headUnderWrap = !!slots && wrap?.afterOpenerLine === true && start === bodyStart && end < bodyEnd;
-    // A line already standing IS the opener's peel on reload, so taking one as well would add a
-    // line; a two-peel body's count comes out of the slots, not out of the run.
+    // A line already standing is the one the reload strips against the opener, so taking another
+    // into `innerPrefix` would add a line; a `twoPeelBody` keeps its lines in the wrap fields.
     const takesOpenerPeel = twoPeelBody || (headUnderWrap && standing.length === 0);
     if (slots && takesOpenerPeel && !slots.innerPrefix) {
-        slots.innerPrefix = trailingLineEnding(children[start].raw);
+        slots.innerPrefix = ownTrailingLineEnding(children[start].raw);
     }
-    // Under the wrap the run keeps exactly one peel line, in `innerPrefix` or still standing;
-    // elsewhere a run with no line above it separates from nothing and materializes in full.
+    // Under the opener the run keeps exactly one stripped line, in `innerPrefix` or standing;
+    // elsewhere a run with nothing above it separates nothing, so every line is a block.
     let wanted;
     if (twoPeelBody)
         wanted = 0;
@@ -151,8 +153,24 @@ export function settleSeparatorOnBlank(parent, index, sharing) {
     materializeTailSuffix(parent, sharing);
 }
 /**
- * The give-back twin of {@link settleSeparatorOnBlank}'s closer peel: a tail that stops being
- * blank owes the borrowed `innerSuffix` line back, or the wrap emits a line nobody typed.
+ * The parser keeps a blank line beside a fence line in `innerPrefix`/`innerSuffix` only when body
+ * content sits past it, so an emptied body keeps neither, or it reloads with an extra blank block.
+ */
+function dropWrapOfEmptiedBody(parent) {
+    const slots = wrapSlotsOf(parent);
+    if (!slots || !bodyWrapOf(parent))
+        return;
+    if ((parent.children?.length ?? 0) > bodyStartIndex(parent))
+        return;
+    retireChildSpans(parent);
+    if (slots.innerPrefix)
+        slots.innerPrefix = '';
+    if (slots.innerSuffix)
+        slots.innerSuffix = '';
+}
+/**
+ * A tail block that stops being blank gives back the `innerSuffix` line {@link
+ * settleSeparatorOnBlank} lent it, or the container emits a line nobody typed.
  */
 export function releaseWrapPeel(parent, index) {
     retireChildSpans(parent);
@@ -169,43 +187,64 @@ export function releaseWrapPeel(parent, index) {
     slots.innerSuffix = '';
 }
 /**
- * The parse folds the document's one trailing blank line into `suffix` only while the tail block
- * is non-blank; once the tail turns blank the reload reads that line as its own empty paragraph,
- * so the settle materializes it. Document-level slot only. Returns the blocks appended.
+ * A body's trailing blank line stays in `suffix`/`innerSuffix` only while the tail block is
+ * non-blank; under a blank tail the reload reads it as a paragraph, so it becomes a block here.
  */
 function materializeTailSuffix(parent, sharing) {
     retireChildSpans(parent);
     const children = parent.children;
-    const suffix = parent.suffix;
-    if (!children || !suffix)
+    const slot = tailSuffixSlotOf(parent);
+    const suffix = slot?.read();
+    if (!children || !slot || !suffix)
         return 0;
-    // An emptied parent has no tail for the line to fold against, so it is the document's whole
-    // content and the reload reads it as the one block there is.
+    // An emptied parent has no tail block for the line to attach to, so the line is the body's
+    // whole content and the reload reads it as the one block there is.
     if (children.length > 0 && !isBlankParagraph(children[children.length - 1]))
         return 0;
     const minted = { kind: 'paragraph', leadingTrivia: '', raw: suffix };
     if (sharing)
         sharing.stamp(minted);
     children.push(minted);
-    parent.suffix = '';
+    slot.clear();
     return 1;
 }
-// ── The splice settle funnel ──
 /**
- * The settle every splice owes its neighbourhood, then the seam question over the window.
- * `removed` is the pre-splice span, the only place was-blank survives a splice; `tracked` rides
- * the folds for a door landing a caret in the spliced bytes.
+ * Where a body keeps its trailing blank line. A closer line strips a line of its own, which
+ * {@link settleSeparatorOnBlank} reconciles, so a body under one has no such slot here.
  */
-function settleSplicedWindow(parent, at, removed, added, change, sharing, tracked) {
+function tailSuffixSlotOf(parent) {
+    if (parent.suffix !== undefined) {
+        return { read: () => parent.suffix ?? '', clear: () => (parent.suffix = '') };
+    }
+    const owner = ownerNodeOf(parent);
+    const wrap = bodyWrapOf(parent);
+    if (!owner || wrap?.beforeCloserLine)
+        return undefined;
+    // An all-blank body under an opener line gives its first line to the opener on reload, which
+    // is the one the trailing line would have added.
+    const children = parent.children ?? [];
+    const openerTakesLine = wrap?.afterOpenerLine === true &&
+        !owner.innerPrefix &&
+        children.length > 0 &&
+        children.every(isBlankParagraph);
+    if (openerTakesLine)
+        return undefined;
+    return { read: () => owner.innerSuffix ?? '', clear: () => (owner.innerSuffix = '') };
+}
+// ── Settling a spliced window ──
+/** Recompute the separators around a splice, then merge neighbours that now read as one block.
+ *  `removed` is the only record of which blocks were blank; `tracked` follows the merges. */
+function settleSplicedWindow(parent, at, removed, vacated, added, change, grammar, sharing, tracked) {
     if (!parent.children)
         return change;
-    // Ahead of the arms: `settleSeparatorOnBlank` materializes the tail line itself, so a count
-    // read after it would leave that growth outside the window the sink reports.
+    // Read before the branches below: `settleSeparatorOnBlank` can append the tail line as a
+    // block, and a count read after it would leave that growth outside the reported window.
     const beforeMint = parent.children.length;
-    handDownVacatedSeparator(parent, at, removed[0]?.leadingTrivia ?? '', sharing);
+    handDownVacatedSeparator(parent, at, vacated, sharing);
     clearRedundantSeparator(parent, at, sharing);
     if (removed.some(isBlankParagraph)) {
-        // Both ends: the line was the slot's own AND the one below it stood on.
+        // Both ends: the removed blank line was this position's own separator and the one the
+        // block below stood on.
         restoreSeparatorAfterBlank(parent, at, sharing);
         if (added > 0)
             restoreSeparatorAfterBlank(parent, at + added, sharing);
@@ -214,18 +253,39 @@ function settleSplicedWindow(parent, at, removed, added, change, sharing, tracke
     else {
         settleSeparatorOnBlank(parent, at + Math.max(added - 1, 0), sharing);
     }
-    // Unconditional, and the funnel's only home for it: a delete window at the tail probes no
-    // slot, and the question is about the parent's LAST block.
+    settleEmptyMarkerLists(parent, at, added, sharing);
+    dropWrapOfEmptiedBody(parent);
+    // Unconditional, and only here: a delete window at the tail names no surviving block, and
+    // the question is about the parent's last block whatever the window.
     materializeTailSuffix(parent, sharing);
     const widened = widenForTailMint(change, beforeMint, parent.children.length);
-    // The seam question is part of SETTLING, not a rule each door carries, so door N+1 inherits
-    // it. A byte-shaped write reporting `noop` splices no window and is asked nothing.
-    return absorbWindowSeams(parent, at, added, at, widened, sharing, tracked, 
-    // A one-slot window names the one block whose bytes changed, which is what lets the seam
-    // above decline on its first line; a plural one names no single block.
+    // Merging neighbours is part of settling, not a rule each caller repeats, so a new caller
+    // inherits it. A write that reports `noop` splices no window and is asked nothing.
+    const absorbed = absorbWindowSeams(parent, at, added, at, widened, grammar, sharing, tracked, 
+    // A one-block window names the block whose bytes changed, which lets the join above it be
+    // refused on that block's first line alone; a wider window names no single block.
     added === 1 ? at : undefined).change;
+    // The parent's trailing line is asked again: a merge can turn the last block blank, and a
+    // blank last block is what makes that line a block of its own.
+    const beforeTailMint = parent.children.length;
+    materializeTailSuffix(parent, sharing);
+    return widenForTailMint(absorbed, beforeTailMint, parent.children.length);
+}
+/**
+ * A list landing under a paragraph with an empty first item, or left there by the splice, takes
+ * the blank line that keeps it a list; typing writes the same line when it rebuilds the list.
+ */
+function settleEmptyMarkerLists(parent, at, added, sharing) {
+    for (let i = at; i <= at + added && i < (parent.children?.length ?? 0); i++) {
+        if (!lacksSublistSeparator(parent.children, i))
+            continue;
+        if (sharing)
+            ensureUnsharedChild(parent, i, sharing);
+        settleSublistSeparator(parent.children, i);
+    }
 }
-/** Whoever takes the slot inherits its line, having none of its own ({@link deleteNode}'s rule). */
+/** The block that takes the vacated position inherits its separator when it has none of its own
+ *  ({@link deleteNode}'s rule). */
 function handDownVacatedSeparator(parent, at, vacated, sharing) {
     retireChildSpans(parent);
     const heir = parent.children?.[at];
@@ -235,23 +295,26 @@ function handDownVacatedSeparator(parent, at, vacated, sharing) {
     owned.leadingTrivia = vacated;
 }
 /**
- * The commit ceremony's settle door: derive the spliced window from the change and settle it
- * against `before`, the pre-mutate children. Nodes surviving inside the window are not removals,
- * so a coarse descriptor over an in-place write settles as one.
+ * The commit's entry point: recompute the separators around `change`'s window against `before`,
+ * the children before the mutation. A node that survives inside the window counts as kept.
  */
-export function settleSeparator(parent, before, change, sharing, tracked) {
+export function settleSeparator(parent, before, change, grammar, sharing, tracked) {
     const window = splicedWindow(change);
     const children = parent.children;
     if (!window || !children)
         return change;
-    // At the funnel's door, ahead of every arm: a window the mutate mis-derived reads `before`
-    // out of bounds and hands the arms a negative span, which each would clamp into silence.
+    // Checked here, before any branch: a window the mutation mis-derived reads `before` out of
+    // bounds and hands the branches a negative span, which each would silently clamp.
     assertInvariant('structural-descriptor', () => checkStructuralDescriptor(change, before.length));
     const survivors = new Set(children.slice(window.at, window.at + window.added));
     const removed = before
         .slice(window.at, window.at + window.removed)
         .filter((node) => !survivors.has(node));
-    return settleSplicedWindow(parent, window.at, removed, window.added, change, sharing, tracked);
+    // Only a block removed from the window's first position leaves a separator behind there; one
+    // absorbed below a surviving block (a forward join) takes its separator with it.
+    const first = before[window.at];
+    const vacated = first && !survivors.has(first) ? first.leadingTrivia : '';
+    return settleSplicedWindow(parent, window.at, removed, vacated, window.added, change, grammar, sharing, tracked);
 }
 function splicedWindow(change) {
     switch (change.op) {
@@ -266,29 +329,28 @@ function splicedWindow(change) {
     }
 }
 /**
- * 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.
+ * {@link settleSeparator} for a splice outside a commit scope, into a container found by walking
+ * the live tree; `spliceChildren` keeps its `childIds` in step.
  */
-export function spliceChildrenSettled(parent, at, removeCount, replacement, sharing) {
+export function spliceChildrenSettled(parent, at, removeCount, replacement, grammar, sharing) {
     const children = parent.children;
     if (!children || at < 0 || at > children.length)
         return;
     const removed = children.slice(at, at + removeCount);
     spliceChildren(parent, at, removeCount, replacement);
-    // `noop` in, so what comes back describes the SETTLE alone: `spliceChildren` already carried
-    // the door's own splice into `childIds`, and out of commit scope nothing else publishes.
-    const settled = settleSplicedWindow(parent, at, removed, replacement.length, { op: 'noop' }, sharing);
+    // `noop` goes in so the result describes the fix-up alone: `spliceChildren` already applied
+    // this function's own splice to `childIds`, and outside a commit scope nothing else writes them.
+    const settled = settleSplicedWindow(parent, at, removed, removed[0]?.leadingTrivia ?? '', replacement.length, { op: 'noop' }, grammar, sharing);
     const ids = parent.childIds;
     if (ids)
         applyStructuralChangeToIdsRefs(settled, ids, new Array(ids.length));
 }
 /**
- * A splice can leave neighbours whose adjacent bytes re-read as fewer blocks on reload. Absorb
- * while the window's own bytes parse to fewer blocks, which is the reload's reading; a blank run
- * is transparent to a container's continuation, so the window anchors at the nearest non-blank
- * block above the seam, never below `floor`, and cascades.
+ * Merge neighbours while their joined bytes reload as fewer blocks or move content into the head;
+ * blank lines don't end a container, so the window starts at the nearest non-blank block above.
  */
-export function absorbSeamReading(parent, seamLeft, floor, sharing, tracked, headProbe, onBeforeSplice) {
+export function absorbSeamReading(parent, seamLeft, floor, grammar, sharing, tracked, headProbe, onBeforeSplice) {
+    const read = (bytes) => readBlocks(bytes, { grammar, scope: 'fragment' });
     const children = parent.children;
     if (seamLeft < 0)
         return { at: 0, span: 0, eaten: 0, spliced: false };
@@ -299,36 +361,46 @@ export function absorbSeamReading(parent, seamLeft, floor, sharing, tracked, hea
     let span = seamLeft - at + 1;
     let eaten = 0;
     let spliced = false;
-    // Only the first pass: a fold re-tiles the window, so the probe's absolute index is stale.
+    // Only on the first pass: a merge re-divides the window, so the index is stale after one.
     let probe = headProbe;
     for (;;) {
-        // The candidate edge crosses a blank run too: the absorbed content sits on the
-        // run's far side (a list continues into indented code across any number of blanks).
+        // The window's far edge crosses a blank run too: the absorbed content sits on the run's
+        // far side (a list continues into indented code across any number of blank lines).
         let right = at + span;
         while (right < children.length && isBlankParagraph(children[right]))
             right++;
         const window = children.slice(at, Math.min(right + 1, children.length));
         if (window.length <= span || window.length < 2)
             break;
-        // A context-dependent kind has no standalone reading, so its seam is not askable.
+        if (separateTableFollower(parent, right, sharing, grammar))
+            break;
+        // A context-dependent kind has no standalone reading, so a join touching it cannot be asked.
         if (window.some((node) => tryGetBlockKindDescriptor(node.kind)?.contextDependentKind))
             break;
-        if (probe !== undefined && declinesOnHeadLine(window, probe - at))
+        if (probe !== undefined && declinesOnHeadLine(window, probe - at, read))
             break;
         probe = undefined;
-        const reparsed = parse(joinedWindowBytes(window, window.length), { scope: 'fragment' });
+        const bytes = joinedWindowBytes(window, window.length);
+        const reparsed = read(bytes);
         const blocks = reparsed.children;
-        if (blocks.length === 0 || blocks.length >= window.length)
+        // Content blocks only: the blank lines an absorbed block held come back as blank blocks.
+        if (blocks.length === 0 || contentCount(blocks) > contentCount(window))
             break;
-        // A fold may PROMOTE the head past what its bytes carry alone (a paragraph under the
+        // A count that did not drop is still a merge when the head took content from the block
+        // below: a blank run inside that block stays blank blocks while the rest moves up.
+        if (blocks.length >= window.length && !headTookContent(blocks[0], window))
+            break;
+        // A merge may promote the head beyond what its bytes carry alone (a paragraph under the
         // setext underline below it), so what must survive is the head's own reading, not its kind.
-        if (blocks[0].kind !== window[0].kind && !readsAsItselfAlone(window[0]))
+        if (blocks[0].kind !== window[0].kind && !readsAsItselfAlone(window[0], read))
             break;
         onBeforeSplice?.();
         absorbFragmentPeel(parent, at + window.length, reparsed.suffix, blocks, sharing);
         blocks[0].leadingTrivia = window[0].leadingTrivia;
+        // The window joins two blocks at least, so its bytes hold the document's line ending.
+        const lineEnding = firstLineEnding(bytes) ?? '\n';
         for (const block of blocks) {
-            ensureEditableContainers(block);
+            ensureEditableContainers(block, lineEnding);
             if (sharing)
                 sharing.stamp(block);
             assignChildIdsDeep(block);
@@ -343,20 +415,41 @@ export function absorbSeamReading(parent, seamLeft, floor, sharing, tracked, hea
     return { at, span, eaten, spliced };
 }
 /**
- * Whether a block's own bytes read back as that block. A structured container's children fail
- * this by construction (one list item's bytes read as a LIST), which is how a scope whose
- * children a document parse does NOT reproduce declines the seam question.
+ * Give a block an edit left right under a table a blank line, or the reload reads its first line
+ * as one more row; the edit made the block, so it stays that block.
  */
-function readsAsItselfAlone(node) {
-    const alone = parse(node.raw, { scope: 'fragment' }).children;
+function separateTableFollower(parent, index, sharing, grammar) {
+    const follower = parent.children[index];
+    if (parent.children[index - 1]?.kind !== 'table' || follower.leadingTrivia !== '')
+        return false;
+    // All of the follower's lines, not its first alone: an opener can need a later one to open.
+    const lines = splitLines(follower.raw);
+    if (lines.length === 0)
+        return false;
+    if (!tableTakesLine(lines, 0, lines.length, grammar))
+        return false;
+    retireChildSpans(parent);
+    mintSeparator(parent, index, sharing);
+    return true;
+}
+const contentCount = (nodes) => nodes.filter((node) => !isBlankParagraph(node)).length;
+/** Whether the reparse moved content into the head: more than the separating blank line, or,
+ *  for a container, that line alone, since its body reads an indented one as its own. */
+function headTookContent(head, window) {
+    const grew = head.raw.length - window[0].raw.length;
+    return grew > window[1].leadingTrivia.length || (head.children !== undefined && grew > 0);
+}
+/** Whether a block's own bytes read back as that block. A container's children never do (an
+ *  item's bytes read as a list), which keeps them out of the merge. */
+function readsAsItselfAlone(node, read) {
+    const alone = read(node.raw).children;
     return alone.length === 1 && alone[0].kind === node.kind;
 }
 /**
- * Decline-only pre-parse for a window whose LAST member is the block that changed: join the
- * others with only that block's first line. Block parsing is a left-to-right line scan, so a
- * block opening here opens in the full join too; a pass falls through to the real parse.
+ * A cheap refusal for a window ending in the changed block, parsing only that block's first line:
+ * block parsing scans lines left to right, so a block that opens here opens in the full join too.
  */
-function declinesOnHeadLine(window, member) {
+function declinesOnHeadLine(window, member, read) {
     if (member <= 0 || member !== window.length - 1)
         return false;
     const raw = window[member].raw;
@@ -364,10 +457,8 @@ function declinesOnHeadLine(window, member) {
     const joined = joinedWindowBytes(window, member) +
         window[member].leadingTrivia +
         (nl < 0 ? raw : raw.slice(0, nl + 1));
-    return parse(joined, { scope: 'fragment' }).children.length >= window.length;
+    return read(joined).children.length >= window.length;
 }
-/** How a fold reads a window: the head's raw, then each of the next `count - 1` members'
- *  leading trivia and raw. */
 function joinedWindowBytes(window, count) {
     let joined = window[0].raw;
     for (let i = 1; i < count; i++)
@@ -375,8 +466,8 @@ function joinedWindowBytes(window, count) {
     return joined;
 }
 /**
- * Where a byte position inside the folded window lands: the fold's own reparse re-tiles the
- * joined bytes, and a position past the window only shifts by what the fold ate.
+ * Where a byte position inside the merged window ends up: the merge's reparse re-divides the
+ * joined bytes, and a position past the window only shifts by the blocks the merge ate.
  */
 function retrackThroughFold(tracked, at, window, blocks) {
     const member = tracked.index - at;
@@ -397,11 +488,8 @@ function retrackThroughFold(tracked, at, window, blocks) {
     tracked.index = at + landed.index;
     tracked.offset = landed.offset;
 }
-/**
- * Map a post-edit caret offset (in the committed text) to the parsed block it falls in, as a
- * local display offset. An offset inside inter-block trivia lands at the next block's start;
- * past-the-end clamps to the last.
- */
+/** The block a caret offset into the committed bytes falls in, and its offset there. An offset in
+ *  the blank lines between blocks lands at the next block's start. */
 export function focusTargetInReplacement(nodes, offset) {
     let pos = 0;
     for (let i = 0; i < nodes.length; i++) {
@@ -415,19 +503,15 @@ export function focusTargetInReplacement(nodes, offset) {
     const last = nodes.length - 1;
     return { index: last, offset: trimTrailingLineEnding(nodes[last].raw).length };
 }
-/**
- * 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. `headProbe` names the one block whose bytes changed, letting each ask
- * decline on its first line alone; dropped once anything folds, since its index has moved.
- */
-export function absorbWindowSeams(parent, at, added, landing, change, sharing, tracked, headProbe, onBeforeSplice) {
+/** Merge across every join the splice at `at` disturbed, the joins inside the window included,
+ *  since a move can break a join that was correct. `headProbe` names the one changed block. */
+export function absorbWindowSeams(parent, at, added, landing, change, grammar, sharing, tracked, headProbe, onBeforeSplice) {
     let settled = null;
     let moved = landing;
     let seamLeft = at - 1;
     let last = at + added - 1;
     while (seamLeft <= last) {
-        const seam = absorbSeamReading(parent, seamLeft, 0, sharing, tracked, settled ? undefined : headProbe, onBeforeSplice);
+        const seam = absorbSeamReading(parent, seamLeft, 0, grammar, sharing, tracked, settled ? undefined : headProbe, onBeforeSplice);
         if (!seam.spliced) {
             seamLeft++;
             continue;
@@ -441,8 +525,8 @@ export function absorbWindowSeams(parent, at, added, landing, change, sharing, t
         return { change, landing: moved };
     return { change: foldAbsorbIntoChange(change, settled), landing: moved };
 }
-/** Two folds as ONE window, which is what a change descriptor reports. The walk is left to
- *  right, so `later` never opens above `earlier`'s post-splice span. */
+/** Two merges as one window, which is what a change descriptor reports. The walk is left to
+ *  right, so `later` never starts above `earlier`'s post-splice span. */
 function unionAbsorptions(earlier, later) {
     return {
         at: earlier.at,
@@ -451,18 +535,15 @@ function unionAbsorptions(earlier, later) {
         spliced: true
     };
 }
-/** Where `index` sits once `seam` folded: a slot inside the absorbed span collapses into it. */
+/** Where `index` sits once `seam` merged: a position inside the absorbed span collapses into it. */
 function indexAfterAbsorb(index, seam) {
     if (index < seam.at)
         return index;
     const absorbedTo = seam.at + seam.span + seam.eaten;
     return index >= absorbedTo ? index - seam.eaten : Math.min(index, seam.at + seam.span - 1);
 }
-/**
- * The absorbed window folded into the write's own, as the ONE contiguous window the sink
- * reports: `count` counts pre-write slots, so the union's span converts back across whatever
- * the write itself added or removed.
- */
+/** The merged window and the write's own as one contiguous change; `count` counts positions
+ *  before the write, so the span converts back across what the write added or removed. */
 function foldAbsorbIntoChange(change, seam) {
     const absorbedTo = seam.at + seam.span + seam.eaten;
     if (change.op === 'noop') {
@@ -488,18 +569,15 @@ function foldAbsorbIntoChange(change, seam) {
         idMap: composeFoldIdMap(change, seam, { lo, count, newCount, written, removed })
     };
 }
-/**
- * Identity through the fold: a slot the absorb did not re-mint still holds the block the change
- * put there, so its id composes through both steps instead of resetting. Slot 0 keeps the head
- * mapping wherever the walk has none, since a fold EXTENDS its head, kind promotion included.
- */
+/** A position the merge did not re-create keeps its block's id through both steps. Position 0
+ *  always maps to the head, since a merge extends its head, even when it changes its kind. */
 function composeFoldIdMap(change, seam, window) {
     const idMap = {};
     for (let slot = 0; slot < window.newCount; slot++) {
         const index = window.lo + slot;
         if (index >= seam.at && index < seam.at + seam.span)
             continue;
-        // Back through the fold: a slot past the absorbed span sat `eaten` further down before it.
+        // Back through the merge: a position past the absorbed span sat `eaten` further down before it.
         const spliced = index < seam.at ? index : index + seam.eaten;
         const old = preChangeIndex(change, spliced, window);
         if (old === null)
@@ -512,7 +590,8 @@ function composeFoldIdMap(change, seam, window) {
         idMap[0] = 0;
     return idMap;
 }
-/** Where `spliced` (a post-change index) stood before the change, or null for a slot it minted. */
+/** Where `spliced` (a post-change index) stood before the change, or null for a block the change
+ *  created. */
 function preChangeIndex(change, spliced, window) {
     if (change.op === 'noop')
         return spliced;
@@ -523,29 +602,31 @@ function preChangeIndex(change, spliced, window) {
     const inherited = change.op === 'replace' ? change.idMap?.[spliced - change.at] : undefined;
     return inherited === undefined ? null : change.at + inherited;
 }
-/**
- * Where the fragment parse's peeled trailing blank run goes. At the parent's tail it stays in the
- * last block's raw, the single-slot sink's rule; mid-document it joins the follower's run, where
- * one line separates and every later one is a block of its own (syntax-tree.md § Blank lines).
- */
+/** The fragment parse's trailing blank run stays in the last block's raw at the parent's tail and
+ *  joins the follower's run elsewhere (`docs/design/syntax-tree.md` § Blank lines). */
 function absorbFragmentPeel(parent, followerIndex, peel, blocks, sharing) {
     const follower = parent.children[followerIndex];
     if (!follower) {
         blocks[blocks.length - 1].raw += peel;
         return;
     }
-    if (peel === '')
+    // Blocks ending blank already hold the run's one separating line, so every line of the
+    // follower's own becomes a blank block of the run instead of a second separator.
+    const runSeparated = isBlankParagraph(blocks[blocks.length - 1]);
+    if (peel === '' && !(runSeparated && follower.leadingTrivia !== ''))
         return;
     const lines = blankLinesOf(peel + follower.leadingTrivia);
     const owned = sharing ? ensureUnsharedChild(parent, followerIndex, sharing) : follower;
-    owned.leadingTrivia = lines.length > 1 ? '' : lines[0];
-    for (let i = 1; i < lines.length; i++) {
-        blocks.push({ kind: 'paragraph', leadingTrivia: i === 1 ? lines[0] : '', raw: lines[i] });
+    owned.leadingTrivia = lines.length > 1 || runSeparated ? '' : lines[0];
+    const first = runSeparated ? 0 : 1;
+    for (let i = first; i < lines.length; i++) {
+        const trivia = !runSeparated && i === 1 ? lines[0] : '';
+        blocks.push({ kind: 'paragraph', leadingTrivia: trivia, raw: lines[i] });
     }
 }
 /** A blank run split back into the lines it is made of, each keeping its own ending. */
 const blankLinesOf = (run) => run.match(/[^\n]*\n|[^\n]+$/g) ?? [];
-/** The materialized tail reported inside the sink's one contiguous window. */
+/** The tail line that became a block, reported inside the caller's one contiguous window. */
 export function widenForTailMint(change, before, after) {
     const grown = after - before;
     if (grown === 0)
@@ -558,16 +639,18 @@ export function widenForTailMint(change, before, after) {
     if (change.op === 'replace' && change.at + change.newCount === before) {
         return { ...change, newCount: change.newCount + grown };
     }
-    // A delete that took the tail vacated the slot the mint lands in, so the two are one window.
+    // A delete that took the tail vacated the position the new block lands in, so the two are
+    // one window.
     if (change.op === 'delete' && change.at === before) {
         return { op: 'replace', at: change.at, count: change.count, newCount: grown };
     }
-    // The mint landed past a window that does not reach the tail, so no single contiguous
-    // span describes both; the parallel arrays would drift either way this widened it.
+    // The new block landed past a window that does not reach the tail, so no single contiguous
+    // span describes both; the parallel id arrays would drift either way this widened it.
     devWarn('tree-ops', 'a tail suffix materialized outside the reported window');
     return change;
 }
-/** A blank line off the node's own bytes (G4.20), where one does structural work at all. */
+/** Give the block at `index` a blank line where one separates anything; the line reuses the
+ *  ending of the block above, which is the document's. */
 function mintSeparator(parent, index, sharing) {
     const children = parent.children;
     if (!children || index <= bodyStartIndex(parent))
@@ -577,49 +660,48 @@ function mintSeparator(parent, index, sharing) {
     const owned = sharing
         ? ensureUnsharedChild(parent, index, sharing)
         : children[index];
-    owned.leadingTrivia = trailingLineEnding(owned.raw);
+    owned.leadingTrivia = ownTrailingLineEnding(children[index - 1].raw);
 }
-/** Reserved chrome is not a body block, so the body window opens past it. */
+/** A container's reserved title child is not a body block, so the body starts past it. */
 function bodyStartIndex(parent) {
     return bodyStartFor(ownerKindNameOf(parent));
 }
-/** The container's declared body wrap, whichever shape names the owner. */
+/** The owning container's declared body wrap, whichever parent shape names it. */
 function bodyWrapOf(parent) {
     const kind = ownerKindNameOf(parent);
     if (kind === undefined)
         return undefined;
     return tryGetBlockKindDescriptor(kind)?.bodyWrap;
 }
-/** The node carrying the wrap's peel slots: the sink's answer, or the parent when it IS the node. */
+/** The node holding `innerPrefix`/`innerSuffix`: the owner the caller named, or the parent itself
+ *  when it is a node. */
 function wrapSlotsOf(parent) {
     return ownerNodeOf(parent);
 }
-/** The container node these children belong to, where the caller answered for one. */
+/** The container node these children belong to, where the caller named one. */
 function ownerNodeOf(parent) {
     return parent.owner ?? ('raw' in parent ? parent : undefined);
 }
 /**
- * Every settle door rewrites bytes the owner's child spans describe while leaving the children's
- * shape alone, so the spans retire at the doors and the next rebuild re-derives them.
+ * Every separator write here changes bytes the owner's child spans describe without changing the
+ * children's shape, so the spans are dropped here and the next rebuild re-derives them.
  */
 function retireChildSpans(parent) {
     const owner = ownerNodeOf(parent);
     if (owner)
         dropChildSpans(owner);
 }
-/** The kind whose body these children are: the sink's answer, or the owner node's own. */
-function ownerKindNameOf(parent) {
-    return 'ownerKind' in parent ? parent.ownerKind : parent.kind;
+/** The kind whose body these children are: the named owner's, or the parent node's own. */
+export function ownerKindNameOf(parent) {
+    return 'owner' in parent ? parent.owner?.kind : parent.kind;
 }
 function bodyStartFor(kind) {
     if (kind === undefined)
         return 0;
     return tryGetBlockKindDescriptor(kind)?.reservedChrome ? 1 : 0;
 }
-/**
- * A chrome-wrapped container's parse peels the blank line against its opener into `innerPrefix`,
- * so a separator freed above the body head is that line: hand it over, or the peel eats the head.
- */
+/** The parser keeps the blank line after a fenced container's opener in `innerPrefix`, so a
+ *  separator freed at the body head moves there, or the reload takes the head's own line. */
 function absorbWrapPrefix(parent, bodyStart, index, freed) {
     const slots = wrapSlotsOf(parent);
     if (!slots || (slots.innerPrefix ?? '') !== '')
@@ -631,15 +713,12 @@ function absorbWrapPrefix(parent, bodyStart, index, freed) {
         return;
     if (index !== bodyStart && !isBlankParagraph(head))
         return;
-    slots.innerPrefix = trailingLineEnding(freed);
+    slots.innerPrefix = ownTrailingLineEnding(freed);
 }
 // ── Delete ──
-/**
- * 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; the successor's trivia is the op's only in-place write.
- */
-export function deleteNode(parent, blockIndex, sharing) {
+/** Remove the node at `blockIndex`, leaving its successor separated once and no more. Takes
+ *  {@link BodyParentArg} since the fix-up can move a freed line into the owner's `innerPrefix`. */
+export function deleteNode(parent, blockIndex, grammar, sharing, tracked) {
     if (blockIndex < 0 || blockIndex >= parent.children.length)
         return { op: 'noop' };
     const deleted = parent.children[blockIndex];
@@ -653,8 +732,8 @@ export function deleteNode(parent, blockIndex, sharing) {
     }
     parent.children.splice(blockIndex, 1);
     clearRedundantSeparator(parent, blockIndex, sharing);
-    // BOTH the survivor's edges: the delete puts it beside a new follower, and a merge door that
+    // Both of the survivor's edges: the delete puts it beside a new follower, and a merge that
     // rewrote its bytes can equally have stopped it interrupting the block above.
     const survivor = Math.max(blockIndex - 1, 0);
-    return absorbWindowSeams(parent, survivor, blockIndex - survivor, blockIndex, { op: 'delete', at: blockIndex, count: 1 }, sharing).change;
+    return absorbWindowSeams(parent, survivor, blockIndex - survivor, blockIndex, { op: 'delete', at: blockIndex, count: 1 }, grammar, sharing, tracked).change;
 }