@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/tree-operations/content-write.d.ts

@@ -1,50 +1,73 @@
 /**
- * The content write: every byte that enters a node crosses `updateNodeContent`, the sole
- * re-parse transfer funnel (editor.md § 6, § 8), and the container twin that re-derives a
- * container's kind from its rebuilt raw.
+ * The content write: every byte that enters a node goes through `updateNodeContent` after
+ * `legalizeWrite` makes it legal for its position. Also re-derives a container's kind from its
+ * rebuilt raw (`docs/design/editor.md` § Structural operations).
  */
-import type { AnyBlockKind, CstNode } from '../core/nodes';
-import type { NodeView } from '../core/node-views';
+import type { CstNode } from '../core/nodes';
+import type { DocumentView, NodeView } from '../core/node-views';
 import { type GrammarView } from '../schema/block-openers';
+import { type BytesReading } from '../schema/container-raw';
+import { type LineEnding } from '../core/lines';
+import { type WriteMode } from '../schema/block-kind-descriptor';
 import type { SharingState } from './sharing';
 import { type StructuralChange } from './structural-change';
-import { type BodyParentArg, type NodeParent } from './node-primitives';
-/** 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). */
+import { type BodyParent, type BodyParentArg, type NodeParent } from './node-primitives';
+declare const legalWrite: unique symbol;
+/**
+ * Text made legal as a block's bytes by {@link legalizeWrite}, the one place that builds it, so
+ * a write that carries one has passed the kind's rule and its container's exactly once.
+ */
+export interface LegalWrite {
+    readonly text: string;
+    /** Where an offset into the text as the writer wrote it lands in the stored `text`. */
+    storedOffset(offset: number): number;
+    readonly [legalWrite]: true;
+}
+/** What {@link legalizeWrite} reads of a block's parent: its container and line ending. */
+export type WriteTarget = {
+    readonly children: readonly NodeView[];
+    readonly owner: NodeView | undefined;
+    readonly lineEnding: LineEnding;
+} | DocumentView;
+/**
+ * `text` made legal as the bytes of the block at `index`: its kind's `rawWrite`, then the
+ * container's `bodyWrite`, both reading the tree as it stands before the write.
+ */
+export declare function legalizeWrite(parent: WriteTarget, index: number, text: string, mode: WriteMode): LegalWrite;
+/** Writes `text` over the leaf at `index` in place, made legal for its position, for a write that
+ *  moves no block (a format toggle's marks); the caller copies the chain first and rebuilds it. */
+export declare function rewriteLeafInPlace(parent: BodyParent, index: number, text: string, grammar: GrammarView, sharing: SharingState): void;
+/** What a content write produced once its neighbours were fixed up: its change widened by every
+ *  merge, and the offset the written text starts at inside that change's window (nonzero once a
+ *  merge above absorbed it). */
 export interface SettledContent {
     change: StructuralChange;
     textStart: number;
 }
 /**
- * Update raw and re-parse. 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 in place, so routine typing keeps the node's object identity.
+ * Write and reparse the block; only a same-kind single-block edit writes in place, so typing keeps
+ * the node's identity. A plain string is made legal here; a {@link LegalWrite} already is.
  */
-export declare function updateNodeContent(parent: BodyParentArg, blockIndex: number, text: string, grammar?: GrammarView, sharing?: SharingState): SettledContent;
+export declare function updateNodeContent(parent: BodyParentArg, blockIndex: number, text: string | LegalWrite, grammar: GrammarView, sharing?: SharingState): SettledContent;
 /**
  * Refresh a node in place from its own reparse, keeping its object identity. The id resync is
  * unconditional: the reparse can change the child count while the caller reports `noop`.
  */
 export declare function adoptReparsedFields(target: CstNode, parsed: CstNode | undefined): void;
+/** Whether the grammar in effect still leaves `NEXT_PROSE_LINE` an ordinary paragraph. */
+export declare function probeLineOpensAsProse(grammar: GrammarView): boolean;
 /**
- * What the grammar opens `line` as, read in isolation: 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;
-/** Whether the ambient grammar still leaves `NEXT_PROSE_LINE` an ordinary paragraph. */
-export declare function probeLineOpensAsProse(grammar?: GrammarView): boolean;
-/**
- * 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 (editor.md § 8). Eligibility is the opener
- * registry: registering an opener is exactly the claim that `parse(raw)` reproduces the kind.
- */
-export declare function reclassifyContainer(parent: NodeParent, index: number, grammar?: GrammarView): CstNode | null;
-/**
- * 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.
+ * Replace the container at `index` when its rebuilt raw parses as a different kind; only a kind
+ * with an opener qualifies, since registering one claims `readBlocks(raw)` reproduces the kind.
  */
-export declare function settledCaretTarget(settled: SettledContent, at: number, offset: number, children: readonly NodeView[]): {
+export declare function reclassifyContainer(parent: NodeParent, index: number, grammar: GrammarView): CstNode | null;
+/** The container at `index` replaced by what its bytes read as, when its position holds that: the
+ *  same kind over other children, or one block of another kind that has an opener. */
+export declare function installReading(parent: NodeParent, index: number, reading: BytesReading, grammar: GrammarView): CstNode | null;
+/** Where a caret at `offset` in the written text ends up after {@link updateNodeContent}'s merges:
+ *  the block holding it and its offset there, counting what a merge above put in front. */
+export declare function settledCaretPosition(settled: SettledContent, at: number, offset: number, children: readonly NodeView[]): {
     index: number;
     offset: number;
 };
+export {};

package/dist/tree-operations/content-write.js

@@ -1,65 +1,115 @@
 /**
- * The content write: every byte that enters a node crosses `updateNodeContent`, the sole
- * re-parse transfer funnel (editor.md § 6, § 8), and the container twin that re-derives a
- * container's kind from its rebuilt raw.
+ * The content write: every byte that enters a node goes through `updateNodeContent` after
+ * `legalizeWrite` makes it legal for its position. Also re-derives a container's kind from its
+ * rebuilt raw (`docs/design/editor.md` § Structural operations).
  */
-import { isBlankParagraph, parse } from '../core/parser';
+import { isBlankParagraph } from '../core/parser';
 import { escalatedFenceLength, matchFenceOpen } from '../core/parsers/fence-syntax';
 import { isBlockOpenerRegistered } from '../schema/block-openers';
-import { trailingLineEnding } from '../core/lines';
-import { assignChildIdsDeep } from '../block-id';
-import { perfEnabled, recordContainerKindReparse } from '../perf/instruments';
-import { getBlockKindDescriptor, tryGetBlockKindDescriptor } from '../schema/block-kind-descriptor';
+import { lineOpensAs, parseContainerRaw, rebuildContainerRaw } from '../schema/container-raw';
+import { displayLines, documentLineEnding, firstLineEnding, joinDisplayLines, ownTrailingLineEnding } from '../core/lines';
+import { assignChildIdsDeep, idsAcrossReread } from '../block-id';
+import { getBlockKindDescriptor, mustHoldChild, tryGetBlockKindDescriptor } from '../schema/block-kind-descriptor';
 import { resyncChildIds } from './children';
 import { spliceMany } from './splice-many';
 import { replacePreservingFirst } from './structural-change';
-import { NEXT_PROSE_LINE, ensureEditableContainers, forBody, writeOwnRaw } from './node-primitives';
+import { taskMarkerCaretShift, writeKeepingTaskMarker } from './list/reconcile-task';
+import { fragmentReaderAt } from './list/task-paragraph';
+import { NEXT_PROSE_LINE, ensureEditableContainers, installOwnRaw, parentLineEnding } from './node-primitives';
 import { absorbWindowSeams, focusTargetInReplacement, releaseWrapPeel, restoreSeparatorAfterBlank, restoreSeparatorOnFill, settleSeparatorOnBlank, widenForTailMint } from './settle';
 /**
- * Update raw and re-parse. 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 in place, so routine typing keeps the node's object identity.
+ * `text` made legal as the bytes of the block at `index`: its kind's `rawWrite`, then the
+ * container's `bodyWrite`, both reading the tree as it stands before the write.
+ */
+export function legalizeWrite(parent, index, text, mode) {
+    const node = parent.children[index];
+    const owner = 'owner' in parent ? parent.owner : undefined;
+    const lineEnding = 'lineEnding' in parent ? parent.lineEnding : documentLineEnding(parent);
+    const ownRule = tryGetBlockKindDescriptor(node.kind)?.rawWrite;
+    const ownCtx = { node, mode, lineEnding };
+    const own = ownRule ? ownRule.normalize(text, ownCtx) : text;
+    const bodyRule = owner ? tryGetBlockKindDescriptor(owner.kind)?.bodyWrite : undefined;
+    // A child's bytes are never the container's own syntax, so the body rule reads them as content.
+    const bodyCtx = owner && { node: owner, mode: 'literal', lineEnding };
+    const stored = bodyRule && bodyCtx ? bodyRule.normalize(own, bodyCtx) : own;
+    // A list item takes a typed task marker out of its first paragraph, or gives one back.
+    const markerShift = index === 0 && owner ? taskMarkerCaretShift(owner, stored) : 0;
+    const storedOffset = (offset) => {
+        const inOwn = ownRule ? ownRule.mapOffset(text, offset, ownCtx) : offset;
+        const inBody = bodyRule && bodyCtx ? bodyRule.mapOffset(own, inOwn, bodyCtx) : inOwn;
+        return Math.max(inBody + markerShift, 0);
+    };
+    return { text: stored, storedOffset };
+}
+/** Writes `text` over the leaf at `index` in place, made legal for its position, for a write that
+ *  moves no block (a format toggle's marks); the caller copies the chain first and rebuilds it. */
+export function rewriteLeafInPlace(parent, index, text, grammar, sharing) {
+    const legal = legalizeWrite(parent, index, text, 'literal');
+    writeKeepingTaskMarker(parent.owner, parent.children, index, sharing, () => installOwnRaw(parent.children[index], legal.text, grammar));
+}
+/**
+ * Write and reparse the block; only a same-kind single-block edit writes in place, so typing keeps
+ * the node's identity. A plain string is made legal here; a {@link LegalWrite} already is.
  */
 export function updateNodeContent(parent, blockIndex, text, grammar, sharing) {
+    const legal = typeof text === 'string' ? legalizeWrite(parent, blockIndex, text, 'literal').text : text.text;
+    // Reconciled before the container's raw rebuild writes the list item's marker.
+    const owner = 'owner' in parent ? parent.owner : undefined;
+    return writeKeepingTaskMarker(owner, parent.children, blockIndex, sharing, () => writeAndSettleContent(parent, blockIndex, legal, grammar, sharing));
+}
+function writeAndSettleContent(parent, blockIndex, text, grammar, sharing) {
     const wasBlank = isBlankParagraph(parent.children[blockIndex]);
+    const indentMoved = leadingIndent(parent.children[blockIndex].raw) !== leadingIndent(text);
     const change = writeParsedContent(parent, blockIndex, text, grammar);
     const lastWritten = lastMintedIndex(change, blockIndex);
-    // One blank line served BOTH sides: it separated this block from the one above and stood in
-    // as the separator of the block beneath it. Ending it owes each their own.
+    // One blank line served both sides: it separated this block from the one above and stood in
+    // as the separator of the block beneath it. Filling it gives each side its own.
     if (wasBlank && !isBlankParagraph(parent.children[blockIndex])) {
         restoreSeparatorOnFill(parent, blockIndex, sharing);
         restoreSeparatorAfterBlank(parent, followerIndexAfter(change, blockIndex), sharing);
         releaseWrapPeel(parent, lastWritten);
-        return settleWriteSeams(parent, blockIndex, lastWritten, change, sharing);
+        return settleWriteSeams(parent, blockIndex, lastWritten, change, sharing, grammar);
     }
-    // The reverse transition: the block IS the separating line now, so the run it joins gives
-    // back the second one. The last block minted is the one that meets the follower.
+    // The reverse transition: the block is the separating line now, so the run it joins gives
+    // back the second one. The last block created is the one that meets the follower.
     if (!wasBlank && isBlankParagraph(parent.children[lastWritten])) {
         const settled = parent.children.length;
         settleSeparatorOnBlank(parent, lastWritten, sharing);
         const widened = widenForTailMint(change, settled, parent.children.length);
-        return settleWriteSeams(parent, blockIndex, lastWritten, widened, sharing);
+        return settleWriteSeams(parent, blockIndex, lastWritten, widened, sharing, grammar);
     }
-    // Same-kind typing INSIDE content must never pay a neighbour reparse.
-    if (change.op === 'noop')
+    // Same-kind typing skips the neighbour reparse unless the first line's indent moved, a blank line
+    // stays blank, or this block or the one above reads the lines below it (editor.md § 8).
+    if (change.op === 'noop' && !wasBlank && !indentMoved && !readerBeside(parent, blockIndex)) {
         return { change, textStart: 0 };
-    return settleWriteSeams(parent, blockIndex, lastWritten, change, sharing);
+    }
+    return settleWriteSeams(parent, blockIndex, lastWritten, change, sharing, grammar);
+}
+const leadingIndent = (text) => /^[ \t]*/.exec(text)[0];
+const readsFollowingLines = (node) => node !== undefined && tryGetBlockKindDescriptor(node.kind)?.readsFollowingLines === true;
+/** Whether the written block or the one right above it reads the lines below it with no blank
+ *  line between, where a write that kept its kind can still move the join. */
+function readerBeside(parent, blockIndex) {
+    const { children } = parent;
+    const below = children[blockIndex + 1];
+    return ((children[blockIndex].leadingTrivia === '' && readsFollowingLines(children[blockIndex - 1])) ||
+        (below?.leadingTrivia === '' && readsFollowingLines(children[blockIndex])));
 }
 /**
- * Ask every join the write disturbed and report where the written text ended up: an absorb
- * ABOVE leaves the predecessor standing, so its bytes now sit in front of the text.
+ * Merge across every join the write disturbed, and report where the written text ended up, since
+ * a merge into the block above puts that block's bytes in front of it.
  */
-function settleWriteSeams(parent, blockIndex, lastWritten, change, sharing) {
+function settleWriteSeams(parent, blockIndex, lastWritten, change, sharing, grammar) {
     const tracked = { index: blockIndex, offset: 0 };
-    const settled = absorbWindowSeams(parent, blockIndex, lastWritten - blockIndex + 1, blockIndex, change, sharing, tracked);
+    const settled = absorbWindowSeams(parent, blockIndex, lastWritten - blockIndex + 1, blockIndex, change, grammar, sharing, tracked);
     return {
         change: settled.change,
         textStart: textOffsetInWindow(parent.children, settled.change, tracked)
     };
 }
 /**
- * The tracked position as an offset in the settled window's committed text, the space every
- * caret door measures in, where the head block's own leading trivia is outside the window.
+ * The tracked position as an offset in the window's committed text, the space every caret
+ * placement measures in, where the head block's own leading blank lines are outside the window.
  */
 function textOffsetInWindow(children, change, tracked) {
     const at = change.op === 'noop' ? tracked.index : change.at;
@@ -74,49 +124,45 @@ function textOffsetInWindow(children, change, tracked) {
 function followerIndexAfter(change, blockIndex) {
     return change.op === 'replace' ? change.at + change.newCount : blockIndex + 1;
 }
-/** The last block the write left in the slot: a multi-block reparse mints past the first. */
+/** The last block the write left in the position: a multi-block reparse creates blocks past
+ *  the first. */
 function lastMintedIndex(change, blockIndex) {
     return change.op === 'replace' ? change.at + change.newCount - 1 : blockIndex;
 }
 /**
- * The written bytes parsed, with the construct they leave OPEN closed off first: an unterminated
- * construct reads every block below it as its body at the next parse, and the seam settle would
- * converge the live tree to exactly that reading.
+ * The written bytes parsed, with a construct they leave open closed first, or the next parse and
+ * the neighbour merge would read every block below it as its body.
  */
-function closeWrittenConstruct(parent, blockIndex, text, oldKind, grammar) {
-    // Fragment scope: this is one block's bytes, whatever its position, so a position-scoped
-    // kind must not mint here.
-    const parsed = parse(text, { grammar, scope: 'fragment' });
+function closeWrittenConstruct(parent, blockIndex, text, oldKind, read) {
+    const parsed = read(text);
     if (blockIndex + 1 >= parent.children.length)
         return { text, parsed };
     if (parsed.children.length === 1 && parsed.children[0].kind === oldKind)
         return { text, parsed };
-    const terminator = openConstructTerminator(text, parsed.children, grammar);
+    const terminator = openConstructTerminator(text, parsed.children, read);
     if (!terminator)
         return { text, parsed };
     const closed = text + terminator;
-    return { text: closed, parsed: parse(closed, { grammar, scope: 'fragment' }) };
+    return { text: closed, parsed: read(closed) };
 }
 /**
- * The terminator written bytes owe when their last construct absorbs to EOF, asked of the grammar
- * rather than a kind list. Null when the bytes terminate themselves, or when no fence opener
- * explains the absorb (the one family whose closer its opener determines).
+ * The closing line the bytes need when their last construct runs to end of file; null when they
+ * close themselves, or no fence opener explains the run.
  */
-function openConstructTerminator(text, blocks, grammar) {
-    // The terminator is a line of its own, so bytes whose last line is still open have none to
-    // append to (G4.20's unterminated tail slice, which absorbs nothing while it stands alone).
-    if (!text.endsWith('\n') || blocks.length === 0)
+function openConstructTerminator(text, blocks, read) {
+    // The closer is a line of its own, so bytes whose last line is unterminated have nowhere to
+    // put one: an unterminated tail slice absorbs nothing while it stands alone.
+    const ending = ownTrailingLineEnding(text);
+    if (ending === '' || blocks.length === 0)
         return null;
-    const ending = trailingLineEnding(text);
-    const probe = parse(text + ending + NEXT_PROSE_LINE + ending, { grammar, scope: 'fragment' });
+    const probe = read(text + ending + NEXT_PROSE_LINE + ending);
     if (probe.children.length !== blocks.length)
         return null;
-    const raw = blocks[blocks.length - 1].raw;
-    const nl = raw.indexOf('\n');
-    const opener = matchFenceOpen(nl < 0 ? raw : raw.slice(0, nl));
+    const [openerLine, ...bodyLines] = displayLines(blocks[blocks.length - 1].raw);
+    const opener = matchFenceOpen(openerLine.text);
     if (!opener)
         return null;
-    const body = nl < 0 ? '' : raw.slice(nl + 1);
+    const body = joinDisplayLines(bodyLines);
     const run = escalatedFenceLength(body, opener.marker, opener.length);
     return opener.indent + opener.marker.repeat(run) + ending;
 }
@@ -124,34 +170,32 @@ function writeParsedContent(parent, blockIndex, text, grammar) {
     const node = parent.children[blockIndex];
     const oldKind = node.kind;
     const oldDescriptor = getBlockKindDescriptor(oldKind);
-    // Ahead of every reparse below, so a write lands on the kind its committed bytes
-    // describe, not the kind the pre-escape text would parse to (`bodyWrite`).
-    const bodyText = forBody(parent, text);
-    // A context-dependent kind has no standalone recognizer, so reparsing would downgrade it:
-    // keep the kind and write raw through its own legality pass.
+    const lineEnding = parentLineEnding(parent);
+    // A context-dependent kind has no standalone recognizer, so reparsing would downgrade it.
     if (oldDescriptor.contextDependentKind) {
-        writeOwnRaw(node, bodyText, grammar);
+        installOwnRaw(node, text, grammar);
         return { op: 'noop' };
     }
-    const { text: newText, parsed: reparsed } = closeWrittenConstruct(parent, blockIndex, bodyText, oldKind, grammar);
+    const { text: newText, parsed: reparsed } = closeWrittenConstruct(parent, blockIndex, text, oldKind, fragmentReaderAt('owner' in parent ? parent.owner : undefined, blockIndex, grammar));
     const parsed = reparsed.children;
     const first = parsed[0];
     // A marker-consuming container (a GitHub alert) needs its raw rebuilt from the backfilled
-    // body, or G1.1 stale-raw fires.
+    // body, or raw and children disagree (G1.1).
     const firstBackfilled = !!first && isEmptyEditableContainer(first);
     if (first)
-        ensureEditableContainers(first);
-    // Text-leading blanks fold into the first block's raw (the single-block shape); the
-    // rest keep their own trivia.
+        ensureEditableContainers(first, lineEnding);
+    // Blank lines at the start of the text go into the first block's raw (as in the single-block
+    // case); the rest keep their own separators.
     if (parsed.length > 1) {
         const rest = parsed.slice(1);
         for (const sibling of rest)
-            ensureEditableContainers(sibling);
+            ensureEditableContainers(sibling, lineEnding);
         first.raw = first.leadingTrivia + first.raw;
         first.leadingTrivia = node.leadingTrivia;
         if (firstBackfilled)
-            reconcileBackfilledRaw(first);
-        // The peeled line has no follower inside the splice, so it stays in raw.
+            rebuildContainerRaw(first, grammar);
+        // The trailing blank line the parse split off has no follower inside the splice, so it
+        // stays in raw.
         rest[rest.length - 1].raw += reparsed.suffix;
         spliceMany(parent.children, blockIndex, 1, parsed);
         return replacePreservingFirst(blockIndex, 1, parsed.length);
@@ -163,14 +207,14 @@ function writeParsedContent(parent, blockIndex, text, grammar) {
         node.raw = newText;
         adoptReparsedFields(node, first);
         if (firstBackfilled)
-            reconcileBackfilledRaw(node);
+            rebuildContainerRaw(node, grammar);
         return { op: 'noop' };
     }
     const replacement = first ?? { kind: 'paragraph', leadingTrivia: '', raw: newText };
     replacement.raw = newText;
     replacement.leadingTrivia = node.leadingTrivia;
     if (firstBackfilled)
-        reconcileBackfilledRaw(replacement);
+        rebuildContainerRaw(replacement, grammar);
     parent.children.splice(blockIndex, 1, replacement);
     return replacePreservingFirst(blockIndex, 1, 1);
 }
@@ -186,71 +230,72 @@ export function adoptReparsedFields(target, parsed) {
     target.innerPrefix = parsed?.innerPrefix;
     target.innerSuffix = parsed?.innerSuffix;
 }
-/** A container `ensureEditableContainers` will backfill; read BEFORE the backfill runs. */
+/** A container `ensureEditableContainers` will backfill; read before the backfill runs. */
 function isEmptyEditableContainer(node) {
-    const d = getBlockKindDescriptor(node.kind);
-    return d.isContainer && d.blockFocus !== 'whole-block' && (node.children?.length ?? 0) === 0;
-}
-/**
- * Sync a just-backfilled container's `raw` to its synthesized body. Needed only for a
- * marker-consuming container whose typed raw lacks a blank body line (`> [!TYPE]`).
- */
-function reconcileBackfilledRaw(node) {
-    getBlockKindDescriptor(node.kind).rebuildRaw?.(node);
+    return mustHoldChild(node.kind) && (node.children?.length ?? 0) === 0;
 }
 // ── Container kind re-derivation ──
-/**
- * What the grammar opens `line` as, read in isolation: asked of the opener registry and never
- * a kind list, so a kind registered later is covered the day it registers.
- */
-export function lineOpensAs(line, grammar) {
-    return parse(`${line}\n`, { grammar, scope: 'fragment' }).children[0]?.kind ?? 'paragraph';
-}
-/** Whether the ambient grammar still leaves `NEXT_PROSE_LINE` an ordinary paragraph. */
+/** Whether the grammar in effect still leaves `NEXT_PROSE_LINE` an ordinary paragraph. */
 export function probeLineOpensAsProse(grammar) {
     return lineOpensAs(NEXT_PROSE_LINE, grammar) === 'paragraph';
 }
 /**
- * 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 (editor.md § 8). Eligibility is the opener
- * registry: registering an opener is exactly the claim that `parse(raw)` reproduces the kind.
+ * Replace the container at `index` when its rebuilt raw parses as a different kind; only a kind
+ * with an opener qualifies, since registering one claims `readBlocks(raw)` reproduces the kind.
  */
 export function reclassifyContainer(parent, index, grammar) {
     const node = parent.children[index];
-    if (!node)
+    if (!node || !tryGetBlockKindDescriptor(node.kind)?.isContainer)
+        return null;
+    if (!isBlockOpenerRegistered(node.kind))
+        return null;
+    return replaceWithParse(parent, index, parseContainerRaw(node.raw, grammar), grammar);
+}
+/** The container at `index` replaced by what its bytes read as, when its position holds that: the
+ *  same kind over other children, or one block of another kind that has an opener. */
+export function installReading(parent, index, reading, grammar) {
+    const node = parent.children[index];
+    if (!node || reading.outcome === 'kept')
         return null;
-    const descriptor = tryGetBlockKindDescriptor(node.kind);
-    if (!descriptor?.isContainer || !isBlockOpenerRegistered(node.kind))
+    if (reading.outcome === 'reread') {
+        // A child the re-read left alone keeps its id, so the block there stays mounted.
+        const children = reading.node.children ?? [];
+        reading.node.childIds = idsAcrossReread(node.children ?? [], node.childIds, children);
+        return installReplacement(parent, index, reading.node, grammar);
+    }
+    if (!isBlockOpenerRegistered(node.kind))
         return null;
-    if (perfEnabled())
-        recordContainerKindReparse();
-    const parsed = parse(node.raw, { grammar, scope: 'fragment' }).children;
-    // A container's raw is one block by construction; a multi-block reparse means bytes
-    // this seam has no slot for, left to the gesture that owns the mutation.
-    if (parsed.length !== 1 || parsed[0].kind === node.kind)
+    return replaceWithParse(parent, index, reading.blocks, grammar);
+}
+function replaceWithParse(parent, index, parsed, grammar) {
+    // A container's raw is one block by construction; a multi-block reparse means bytes this
+    // function has no position for, left to the edit that owns the mutation.
+    if (parsed.length !== 1 || parsed[0].kind === parent.children[index].kind)
         return null;
-    const replacement = parsed[0];
+    return installReplacement(parent, index, parsed[0], grammar);
+}
+function installReplacement(parent, index, replacement, grammar) {
+    const node = parent.children[index];
     const backfilled = isEmptyEditableContainer(replacement);
-    ensureEditableContainers(replacement);
-    // The slot's trivia is authoritative, so restore the bytes before overwriting it or
-    // anything the parse split off the front vanishes with it.
+    // A container spanning lines holds the document's ending in its bytes; only a one-line
+    // container, the last line of a document, falls back to LF.
+    ensureEditableContainers(replacement, firstLineEnding(node.raw) ?? '\n');
+    // The position's own `leadingTrivia` is authoritative, so restore the bytes before
+    // overwriting it or anything the parse split off the front vanishes with it.
     replacement.raw = node.raw;
     replacement.leadingTrivia = node.leadingTrivia;
     if (backfilled)
-        reconcileBackfilledRaw(replacement);
-    // A freshly-parsed node carries no childIds and this swap publishes under the slot's
-    // reused component instance, so undefined keys would reach the nested keyed `{#each}`.
+        rebuildContainerRaw(replacement, grammar);
+    // A freshly parsed node carries no `childIds`, and the swap reuses the position's component,
+    // so undefined keys would reach its nested keyed `{#each}`.
     assignChildIdsDeep(replacement);
     parent.children[index] = replacement;
-    // Write-then-re-read (tree-operations/unshare.ts header).
+    // Write, then re-read through the tree (`unshare.ts` header).
     return parent.children[index];
 }
-/**
- * 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.
- */
-export function settledCaretTarget(settled, at, offset, children) {
+/** Where a caret at `offset` in the written text ends up after {@link updateNodeContent}'s merges:
+ *  the block holding it and its offset there, counting what a merge above put in front. */
+export function settledCaretPosition(settled, at, offset, children) {
     const { change, textStart } = settled;
     if (change.op !== 'replace')
         return { index: at, offset };

package/dist/tree-operations/index.d.ts

@@ -3,14 +3,14 @@ export { nodeAt, emptyParagraph, paragraphNode, ensureEditableContainers, normal
 export { deleteNode, focusTargetInReplacement, restoreSeparatorOnFill, dropDoubledSeparator } from './settle';
 export { updateNodeContent, reclassifyContainer } from './content-write';
 export type { MergeIntoPrevResult, MergeResult, SplitResult } from './node-ops';
-export { splitNode, assertSplitLanding, assertSingleNodeSink, mergeWithNext, mergeIntoPrevDeepLeaf } from './node-ops';
+export { splitNode, assertSingleNodeSink, mergeWithNext, mergeIntoPrevDeepLeaf } from './node-ops';
 export { unwrapFirstItemFromList, mergeListItemIntoPrevious } from './list/unwrap-merge';
 export { renumberOrderedList, normalizeItemMarkerToList } from './list/ordered-markers';
 export { isItemUserEmpty } from './list/empty-check';
 export { buildExitReplacement } from './list/exit-replacement';
-export { reconcileTaskMetadata } from './list/reconcile-task';
-export { unwrapFirstChildFromQuote } from './blockquote';
-export { liftFirstChildKeepingContainer } from './container-lift';
+export { writeKeepingTaskMarker } from './list/reconcile-task';
+export { plainQuote } from './blockquote';
+export { liftFirstChild, sameContainer } from './container-lift';
 export { insertEmptyRow, insertEmptyColumn, deleteRow, deleteColumn, cycleAlignment } from './table-mutations';
 export { copyRectangleAsSubTable } from './sub-table-copy';
 export type { CellPos } from './sub-table-copy';

package/dist/tree-operations/index.js

@@ -1,14 +1,14 @@
 export { nodeAt, emptyParagraph, paragraphNode, ensureEditableContainers, normalizeReplacementTrivia } from './node-primitives';
 export { deleteNode, focusTargetInReplacement, restoreSeparatorOnFill, dropDoubledSeparator } from './settle';
 export { updateNodeContent, reclassifyContainer } from './content-write';
-export { splitNode, assertSplitLanding, assertSingleNodeSink, mergeWithNext, mergeIntoPrevDeepLeaf } from './node-ops';
+export { splitNode, assertSingleNodeSink, mergeWithNext, mergeIntoPrevDeepLeaf } from './node-ops';
 export { unwrapFirstItemFromList, mergeListItemIntoPrevious } from './list/unwrap-merge';
 export { renumberOrderedList, normalizeItemMarkerToList } from './list/ordered-markers';
 export { isItemUserEmpty } from './list/empty-check';
 export { buildExitReplacement } from './list/exit-replacement';
-export { reconcileTaskMetadata } from './list/reconcile-task';
-export { unwrapFirstChildFromQuote } from './blockquote';
-export { liftFirstChildKeepingContainer } from './container-lift';
+export { writeKeepingTaskMarker } from './list/reconcile-task';
+export { plainQuote } from './blockquote';
+export { liftFirstChild, sameContainer } from './container-lift';
 export { insertEmptyRow, insertEmptyColumn, deleteRow, deleteColumn, cycleAlignment } from './table-mutations';
 export { copyRectangleAsSubTable } from './sub-table-copy';
 export { cascadeCleanupEmptyAncestors } from './cleanup';

package/dist/tree-operations/keep-one-block.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The document always holds a block: a structural commit that leaves it none gives it one empty
+ * paragraph. The commit runs this step in both its branches, so no edit writes that paragraph.
+ */
+import type { StructuralChange } from './structural-change';
+import type { SharingState } from './sharing';
+import { type BodyParent } from './node-primitives';
+/** When `body` (the document's) has no children, gives it the empty paragraph and returns `change`
+ *  widened to cover it; `body.lineEnding` was read before the edit, so the paragraph keeps it. */
+export declare function keepOneBlock(body: BodyParent, change: StructuralChange, sharing: SharingState): StructuralChange;

package/dist/tree-operations/keep-one-block.js

@@ -0,0 +1,19 @@
+/**
+ * The document always holds a block: a structural commit that leaves it none gives it one empty
+ * paragraph. The commit runs this step in both its branches, so no edit writes that paragraph.
+ */
+import { emptyParagraph } from './node-primitives';
+/** When `body` (the document's) has no children, gives it the empty paragraph and returns `change`
+ *  widened to cover it; `body.lineEnding` was read before the edit, so the paragraph keeps it. */
+export function keepOneBlock(body, change, sharing) {
+    if (body.children.length > 0)
+        return change;
+    const filler = emptyParagraph('', body.lineEnding);
+    sharing.stamp(filler);
+    body.children.push(filler);
+    // With nothing left, the change's window started at 0 and held every block there was.
+    const removed = change.op === 'delete' || change.op === 'replace' ? change.count : 0;
+    return removed === 0
+        ? { op: 'insert', at: 0, count: 1 }
+        : { op: 'replace', at: 0, count: removed, newCount: 1 };
+}

package/dist/tree-operations/leaf-range.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Replacing a range of one leaf, and joining two leaves, the way in-leaf edits and merges
+ * write them: cut back to the painted text, off any surrogate pair, and in live mode with the
+ * delimiter runs the join strands dropped, typed text included (`docs/design/live-mode.md` § 4.5).
+ */
+import type { NodeView } from '../core/node-views';
+import { type LineEnding } from '../core/lines';
+import { type CleanedJoin, type JoinEndpoint, type JoinSeam } from '../schema/inline-construct-policy';
+import type { StoredAs } from '../schema/stored-as';
+export interface LeafRangeEdit {
+    /** The leaf's bytes after the edit, trailing line ending included. */
+    raw: string;
+    caret: number;
+    /** The range replaced: a drawn one cut back to the painted text, and off any surrogate pair. */
+    range: {
+        start: number;
+        end: number;
+    };
+    /** Whether `raw` is the range asked for spliced with nothing moved or cleaned, the edit the
+     *  browser makes itself, grapheme and IME handling included. */
+    matchesBrowserEdit: boolean;
+}
+/** `[start, end)` of `node` replaced by `typed`, the join cleaned against where `store` keeps it. */
+export declare function replaceRangeInLeaf(node: NodeView, range: {
+    start: number;
+    end: number;
+}, typed: string, store: StoredAs): LeafRangeEdit;
+/** The bytes `head` up to its offset and `tail` from its offset make with `typed` between them,
+ *  `seam` where `typed` starts. `tail`'s bytes take its kind's write rule, in `lineEnding`. */
+export declare function joinLeaves(head: JoinEndpoint, tail: JoinEndpoint, typed: string, store: StoredAs, lineEnding: LineEnding): CleanedJoin;
+/** `join.mergedRaw` minus the delimiter runs the join left unpaired, where the reading hides
+ *  delimiters. */
+export declare function cleanJoinedRaw(join: JoinSeam): CleanedJoin;