@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/core/inline-render.js

@@ -1,13 +1,14 @@
 /**
- * DOM renderer for InlineNode trees. Over a widget-free range the fragment's textContent equals
- * raw.slice. Atomic widgets break that by design, contributing their own text or none and
- * carrying source bytes on `data-source-*`, so a raw offset is recovered only through the shared
- * walk (cursor/widget-offset.ts), never by counting textContent. Stated both ways by G2.4.
- *
- * Which of the spans minted here a mode leaves on screen is `inline/visibility.ts`.
+ * DOM renderer for inline node trees. Over a widget-free range the fragment's textContent equals
+ * raw.slice. Widgets break that by design, contributing their own text or none and carrying their
+ * source bytes on `data-source-*`, so a raw offset is recovered only through the shared DOM
+ * traversal (cursor/widget-offset.ts), never by counting textContent (G2.4). Which of the spans
+ * built here a mode leaves on screen is `inline/visibility.ts`.
  */
 import { buildCoreInlineWidget } from './inline/inline-widgets';
+import { codeSpanFence } from './inline/scan/code-spans';
 import { isAllowedHrefScheme } from './url-policy';
+import { firstDisplayLine } from './lines';
 // ── Marker helpers ──────────────────────────────────────────────────────────
 function markerSpan(text) {
     const span = document.createElement('span');
@@ -15,6 +16,19 @@ function markerSpan(text) {
     span.textContent = text;
     return span;
 }
+/**
+ * A hard break's marker, wrapped in the element the stylesheet draws a return glyph on where the
+ * marker's bytes do not show: the wrapper holds no text, so every offset and copy reads the bytes.
+ */
+function hardBreakMark(marker) {
+    const mark = document.createElement('span');
+    mark.className = 'md-hard-break';
+    // Trailing spaces are blank even where they paint, so source mode draws the glyph for them too.
+    if (marker.textContent?.startsWith(' '))
+        mark.setAttribute('data-trailing-spaces', '');
+    mark.appendChild(marker);
+    return mark;
+}
 function tagConstruct(el, node, opts) {
     if (opts.tagConstructMarkers) {
         el.setAttribute('data-construct-start', String(node.start));
@@ -29,8 +43,8 @@ function sourceSpan(raw, node, className) {
     span.textContent = raw.slice(node.start, node.end);
     return span;
 }
-/** The one href funnel for every sink — a consumer's rewrite, then the scheme allowlist; undefined
- *  reads as "render inert". Exported: the link card's Open button hands over a user-typed URL. */
+/** The one href path every DOM sink goes through: a consumer's rewrite, then the scheme allowlist.
+ *  Undefined means render inert. */
 export function resolveHref(opts, url) {
     if (url === undefined)
         return undefined;
@@ -43,15 +57,9 @@ export function resolveHref(opts, url) {
 // ── Inline code ─────────────────────────────────────────────────────────────
 function renderInlineCode(node, raw, opts) {
     const frag = document.createDocumentFragment();
-    // Every span is a slice of raw, never a parsed field that happens to agree — and each is its
-    // OWN slice: the opening fence is capped at half the node and the closing one read back off
-    // the tail, so a node nobody parsed (a plugin mint over unfenced bytes) still emits its bytes
-    // exactly once (G2.4).
-    const fenceLimit = node.start + Math.floor((node.end - node.start) / 2);
-    let contentStart = node.start;
-    while (contentStart < fenceLimit && raw[contentStart] === '`')
-        contentStart++;
-    const contentEnd = node.end - (contentStart - node.start);
+    const fence = codeSpanFence(node);
+    const contentStart = node.start + fence;
+    const contentEnd = node.end - fence;
     frag.appendChild(tagConstruct(markerSpan(raw.slice(node.start, contentStart)), node, opts));
     const code = document.createElement('code');
     code.className = 'inline-code-content';
@@ -90,9 +98,8 @@ function openWrapped(node, raw, tag, opts, container) {
     };
 }
 // ── Links ────────────────────────────────────────────────────────────────────
-// Markers come from raw.slice: the parsed url/title can differ from the source bytes. Every
-// split point is clamped to node.end — a plugin mint need not carry the bytes GFM's own link
-// does, and a search running past the node would render the NEXT node's source (G2.4).
+// Markers come from raw.slice, since the parsed url/title can differ from the source bytes. Split
+// points clamp to node.end: a plugin-made node need not carry GFM's own link bytes (G2.4).
 function openLink(node, raw, opts, container) {
     const children = node.children ?? [];
     if (children.length === 0) {
@@ -107,7 +114,7 @@ function openLink(node, raw, opts, container) {
     }
     const lastChild = children[children.length - 1];
     // The close marker splits into the text bracket's `]` and the trailing marker. Reference forms
-    // get their own `md-ref-label` class so CSS can dim them harder than inline markers.
+    // get their own `md-ref-label` class so CSS can style the label as metadata.
     const closingTextBracket = lastChild.end < node.end && raw[lastChild.end] === ']'
         ? raw.slice(lastChild.end, lastChild.end + 1)
         : '';
@@ -150,11 +157,8 @@ function openLink(node, raw, opts, container) {
     };
 }
 // ── Autolinks ────────────────────────────────────────────────────────────────
-/**
- * The angle form's `<`/`>` are construct syntax, so they render as markers the mode CSS can hide;
- * the bare URL/www/email forms are url text throughout. Read off the raw bytes, never `node.url`:
- * the bare forms synthesize a url (`http://`, `mailto:`) that is not a slice of the source.
- */
+/** The angle form's `<`/`>` render as markers the mode CSS can hide. Read off the raw bytes, never
+ *  `node.url`, which a bare form may synthesize (`http://`, `mailto:`). */
 function appendAutolink(node, raw, opts, container) {
     const href = resolveHref(opts, node.url);
     const el = document.createElement(href !== undefined ? 'a' : 'span');
@@ -180,9 +184,8 @@ function appendImageSource(node, raw, opts, container) {
     const altText = node.alt ?? '';
     const altStart = node.start + 2;
     const altEnd = altStart + altText.length;
-    // `alt` locates the split and never supplies text (openLink's rule), and only where it is
-    // literally those bytes: a minted image's markers need not be a GFM image's. Unlocatable
-    // falls back to unmarked source, since a construct nobody can decompose would collapse whole.
+    // `alt` only locates the split, and only where it is literally those bytes, since a plugin-made
+    // image need not be GFM's; an unlocatable one falls back to unmarked source.
     if (altEnd > node.end || !raw.startsWith(altText, altStart)) {
         container.appendChild(document.createTextNode(raw.slice(node.start, node.end)));
         return;
@@ -211,16 +214,10 @@ function renderNode(node, raw, opts, container) {
             // A text node carries the line ending so textContent equals raw byte-for-byte;
             // a `<br>` would diverge across browsers.
             const breakRaw = raw.slice(node.start, node.end);
-            const nlIdx = breakRaw.indexOf('\n');
-            // A node carrying no line ending (a plugin mint) is all marker: a -1 here would
-            // slice from the end and drop bytes.
-            const lineEndingStart = nlIdx === -1
-                ? breakRaw.length
-                : nlIdx > 0 && breakRaw[nlIdx - 1] === '\r'
-                    ? nlIdx - 1
-                    : nlIdx;
+            // The marker is the break's first line; a node with no line ending is all marker.
+            const lineEndingStart = firstDisplayLine(breakRaw).text.length;
             if (lineEndingStart > 0) {
-                container.appendChild(markerSpan(breakRaw.slice(0, lineEndingStart)));
+                container.appendChild(hardBreakMark(markerSpan(breakRaw.slice(0, lineEndingStart))));
             }
             container.appendChild(document.createTextNode(breakRaw.slice(lineEndingStart)));
             return null;
@@ -255,10 +252,9 @@ function renderNode(node, raw, opts, container) {
         case 'entityReference':
         case 'rawHtml':
         default:
-            // An invisible entity is not a widget, so the builder returns null and it keeps its
-            // literal-source span; anything the registry does not claim falls back the same way,
-            // mirroring the unknown-block fallback so every byte round-trips.
-            container.appendChild(buildCoreInlineWidget(node, raw, opts.buildPortalWidget) ??
+            // An invisible entity renders no widget and keeps its literal-source span, as does any
+            // kind the registry does not own, so every byte round-trips.
+            container.appendChild(buildCoreInlineWidget(node, raw, opts.buildPortalWidget, opts.grammar) ??
                 sourceSpan(raw, node, node.kind === 'entityReference'
                     ? 'md-entity'
                     : node.kind === 'rawHtml'
@@ -267,7 +263,7 @@ function renderNode(node, raw, opts, container) {
             return null;
     }
 }
-export function renderInlineNodes(nodes, raw, opts = {}) {
+export function renderInlineNodes(nodes, raw, opts) {
     // Iterative: nesting depth is input-controlled, so per-level recursion overflows the stack and
     // strands the block in the unhealable fallback. `scanChildren` is iterative for the same reason.
     const root = {
@@ -288,23 +284,21 @@ export function renderInlineNodes(nodes, raw, opts = {}) {
         if (child !== null)
             stack.push(child);
     }
-    if (opts.pendingBreakSeat)
-        paintPendingBreak(nodes, raw, root.content);
+    if (opts.pendingBreakAt !== undefined) {
+        paintPendingBreak(nodes, raw, opts.pendingBreakAt, root.content);
+    }
     return root.content;
 }
-/**
- * `insertHardBreak` at the end of a block writes `\` whose line ending IS the block's trailing
- * one, so until the next key supplies the following line CommonMark (and the scanner) read the
- * byte as literal text. Left as text it shows as a stray backslash and the caret stays on the
- * first line; painted like this the user sees the new line they asked for. A `br` adds no
- * textContent, so G1.28 holds; the walk seats offset `length` after the first anchor.
- */
-function paintPendingBreak(nodes, raw, frag) {
+/** The first of a pending hard break's two anchors, where the new line starts. */
+export const PENDING_BREAK_ANCHOR = 'br[data-caret-anchor="break"]';
+/** A `\` ending the block is a hard break the scanner reads as text until its next line exists;
+ *  a hidden marker plus two `br` anchors show that line without adding text. */
+function paintPendingBreak(nodes, raw, contentEnd, frag) {
     const last = nodes[nodes.length - 1];
     if (!last || last.kind !== 'text' || raw[last.end - 1] !== '\\')
         return;
-    const rest = raw.slice(last.end);
-    if (rest !== '' && rest !== '\n' && rest !== '\r\n')
+    // Only the block's own structure may follow the backslash: its line ending, or an underline.
+    if (last.end !== contentEnd)
         return;
     const tail = frag.lastChild;
     if (!tail || tail.nodeType !== Node.TEXT_NODE || !tail.textContent?.endsWith('\\'))
@@ -322,11 +316,8 @@ function paintPendingBreak(nodes, raw, frag) {
         frag.appendChild(anchor);
     }
 }
-/**
- * The leaf containing `offset`, preferring the right node at a boundary; `offset === end` only
- * matches the last node. Model-layer, touching no DOM: the DOM counterpart is
- * `findDomTextOffsetTarget` in cursor/widget-offset.ts.
- */
+/** The leaf containing `offset`, preferring the right node at a boundary; `offset === end` matches
+ *  only the last node. The DOM side is `findDomTextOffsetTarget` in `cursor/widget-offset.ts`. */
 export function findNodeAtOffset(nodes, offset) {
     // Descent never backtracks, the first containing sibling winning its level, so the answer is
     // the deepest containing node.

package/dist/core/lines.d.ts

@@ -1,33 +1,63 @@
-/** Line splitting preserving endings and offsets, plus the trailing-line-ending helpers. */
+/**
+ * Line splitting that keeps each line's ending and offsets, and the line-ending rule: a line the
+ * editor writes takes the document's ending ({@link documentLineEnding}), and per-line work reads
+ * each line's text without its ending ({@link displayLines}). Also GFM's whitespace, the one
+ * reading of blank and trimmed text for the parser and the editing code alike.
+ */
+import type { DocumentView } from './node-views';
+export type LineEnding = '\n' | '\r\n';
+export declare function isBlankLine(text: string): boolean;
+/** Whether `text` is blank lines only: spaces, tabs and line endings. The emptiness test for any
+ *  block's text, never `String.trim()`, which also drops a non-breaking space. */
+export declare function isBlankText(text: string): boolean;
+/** A line ending a pattern admits at the end of a line's text: the document's last line can end
+ *  in a lone `\r`, which the line splitter leaves in the text, and a plugin may pass an ending. */
+export declare const OPTIONAL_LINE_ENDING = "(?:\\r\\n?|\\n)?";
+/** GFM §2.1's whitespace character: space, tab, LF, VT, FF, CR. Narrower than JS `\s`. */
+export declare const WHITESPACE_CHARS = " \\t\\n\\v\\f\\r";
+export declare const WHITESPACE_CLASS = "[ \\t\\n\\v\\f\\r]";
+export declare const WHITESPACE_RUN: RegExp;
+export declare function isWhitespaceChar(ch: string | undefined): boolean;
+/** `text` without GFM whitespace at either end: what the spec means by "trimmed". */
+export declare function trimWhitespace(text: string): string;
 /** Length of `raw` excluding any trailing line ending (LF or CRLF). */
 export declare function displayLength(raw: string): number;
 export declare function trimTrailingLineEnding(raw: string): string;
+/** The ending `raw` actually carries, empty when it has none: {@link trimTrailingLineEnding}'s
+ *  complement, for code reattaching a block's own bytes. */
+export declare function ownTrailingLineEnding(raw: string): '' | LineEnding;
 /**
- * The ending `raw` actually carries — {@link trimTrailingLineEnding}'s complement, the two
- * partitioning `raw`. What {@link trailingLineEnding} answers instead is which ending the
- * DOCUMENT uses, so a site reattaching a block's own bytes reads this one (G4.20).
+ * The ending every line the editor writes into `doc` takes: the document's first line break, else
+ * LF. Read afresh on each call, which scans only up to that first break.
  */
-export declare function ownTrailingLineEnding(raw: string): '' | '\n' | '\r\n';
+export declare function documentLineEnding(doc: DocumentView): LineEnding;
+/** The first line break in `text`, or null when it holds none. In a document with one ending,
+ *  any break in a block's own bytes is the document's. */
+export declare function firstLineEnding(text: string): LineEnding | null;
+/** The ending `raw` closes with, else `fallback`, usually the document's ending: a block with no
+ *  ending of its own is the document's last line. */
+export declare function trailingLineEnding(raw: string, fallback: LineEnding): LineEnding;
+/** `text` closed with `ending` when its last line is open: a slice cut from a block would
+ *  otherwise run into whatever follows it once the bytes stand alone. */
+export declare function terminateLine(text: string, ending: LineEnding): string;
+/** Whether the last line of `text` holds only spaces and tabs, its ending aside. */
+export declare function endsInBlankLine(text: string): boolean;
+/** The first half of a UTF-16 surrogate pair, as a code unit (`charCodeAt`). */
+export declare function isHighSurrogate(unit: number): boolean;
+/** The second half of a UTF-16 surrogate pair, as a code unit (`charCodeAt`). */
+export declare function isLowSurrogate(unit: number): boolean;
 /**
- * `offset` moved off the interior of a surrogate pair, back to the pair's own start. Caret
- * offsets are UTF-16 code units, so a cut at one can halve an astral scalar and leave a lone
- * surrogate — bytes no UTF-8 encoder round-trips (`TextEncoder` yields U+FFFD) and no inverse
- * gesture restores. Scalars only: a grapheme cluster is a rendering question, and answering it
- * here would move a caret the author placed between two legitimately separate scalars.
+ * `offset` moved off the interior of a surrogate pair, back to the pair's start: a cut there
+ * leaves a lone surrogate, which no UTF-8 encoder round-trips. Code points only, not graphemes.
  */
 export declare function snapToScalarBoundary(raw: string, offset: number): number;
-/**
- * The block's authored trailing line ending. Every site that reattaches or mints one reads it
- * here (G4.20), so a CRLF-authored block keeps its ending and an unterminated one gets `\n`.
- */
-export declare function trailingLineEnding(raw: string): '\n' | '\r\n';
-/**
- * Keep a truncated slice line-terminated, borrowing `sourceRaw`'s own ending (G4.20). A slice
- * whose last line stays open swallows whatever follows it once the bytes stand alone.
- */
-export declare function terminateLine(text: string, sourceRaw: string): string;
-/** Paste entry points funnel through here so Windows CRLF does not leak into a note. */
+/** Every paste entry point goes through here, so the paste rules read LF whatever the clipboard
+ *  held; the paste writes the document's own ending back. */
 export declare function normalizeLineEndings(text: string): string;
+/** `text` with every line break written as `ending`: how LF text joins a document's own lines. */
+export declare function withLineEnding(text: string, ending: LineEnding): string;
+/** The line break starting at `offset` in `text`, empty when none starts there. */
+export declare function lineEndingAt(text: string, offset: number): '' | LineEnding;
 export interface ParsedLine {
     raw: string;
     text: string;
@@ -36,9 +66,20 @@ export interface ParsedLine {
     end: number;
 }
 export declare function splitLines(source: string): ParsedLine[];
-/**
- * Re-mint a `ParsedLine[]` after a per-line strip, as the container parsers do when they reparse
- * a prefix-stripped body. Recompute, not spread: reusing an input line's offsets after shortening
- * its text desyncs the offsets from the bytes.
- */
+export interface DisplayLine {
+    text: string;
+    ending: '' | LineEnding;
+}
+/** A block's display as lines, each apart from its ending. A display always has a last line, empty
+ *  after a final break, and {@link joinDisplayLines} puts the bytes back exactly. */
+export declare function displayLines(display: string): DisplayLine[];
+/** {@link displayLines}' first line, read without splitting the rest of `text`. */
+export declare function firstDisplayLine(text: string): DisplayLine;
+export declare function joinDisplayLines(lines: readonly DisplayLine[]): string;
+/** Columns of leading indentation, a tab advancing to the next multiple of four (GFM §2.2). */
+export declare function indentColumns(text: string): number;
+/** `text` with up to `columns` columns of indentation removed. A tab the cut splits is written as
+ *  the spaces it spans, since every later reparse reads the child's raw from column zero. */
+export declare function stripIndentColumns(text: string, columns: number): string;
+/** A `ParsedLine[]` rebuilt after a per-line strip, offsets recomputed from the stripped bytes. */
 export declare function remapStrippedLines(lines: ParsedLine[], stripLine: (line: ParsedLine, index: number) => string): ParsedLine[];

package/dist/core/lines.js

@@ -1,4 +1,37 @@
-/** Line splitting preserving endings and offsets, plus the trailing-line-ending helpers. */
+/**
+ * Line splitting that keeps each line's ending and offsets, and the line-ending rule: a line the
+ * editor writes takes the document's ending ({@link documentLineEnding}), and per-line work reads
+ * each line's text without its ending ({@link displayLines}). Also GFM's whitespace, the one
+ * reading of blank and trimmed text for the parser and the editing code alike.
+ */
+// ── Markdown whitespace ──────────────────────────────────────────────────────
+/** GFM §2.1: a blank line holds only spaces and tabs; a non-breaking space is content. */
+const NON_BLANK_CHAR = /[^ \t]/;
+export function isBlankLine(text) {
+    return !NON_BLANK_CHAR.test(text);
+}
+const BLANK_TEXT = /^(?:[ \t]|\r?\n)*$/;
+/** Whether `text` is blank lines only: spaces, tabs and line endings. The emptiness test for any
+ *  block's text, never `String.trim()`, which also drops a non-breaking space. */
+export function isBlankText(text) {
+    return BLANK_TEXT.test(text);
+}
+/** A line ending a pattern admits at the end of a line's text: the document's last line can end
+ *  in a lone `\r`, which the line splitter leaves in the text, and a plugin may pass an ending. */
+export const OPTIONAL_LINE_ENDING = '(?:\\r\\n?|\\n)?';
+/** GFM §2.1's whitespace character: space, tab, LF, VT, FF, CR. Narrower than JS `\s`. */
+export const WHITESPACE_CHARS = ' \\t\\n\\v\\f\\r';
+export const WHITESPACE_CLASS = `[${WHITESPACE_CHARS}]`;
+export const WHITESPACE_RUN = new RegExp(`${WHITESPACE_CLASS}+`);
+const WHITESPACE_CHAR = new RegExp(`^${WHITESPACE_CLASS}$`);
+const EDGE_WHITESPACE = new RegExp(`^${WHITESPACE_CLASS}+|${WHITESPACE_CLASS}+$`, 'g');
+export function isWhitespaceChar(ch) {
+    return ch !== undefined && WHITESPACE_CHAR.test(ch);
+}
+/** `text` without GFM whitespace at either end: what the spec means by "trimmed". */
+export function trimWhitespace(text) {
+    return text.replace(EDGE_WHITESPACE, '');
+}
 /** Length of `raw` excluding any trailing line ending (LF or CRLF). */
 export function displayLength(raw) {
     if (raw.endsWith('\r\n'))
@@ -10,46 +43,96 @@ export function displayLength(raw) {
 export function trimTrailingLineEnding(raw) {
     return raw.slice(0, displayLength(raw));
 }
-/**
- * The ending `raw` actually carries — {@link trimTrailingLineEnding}'s complement, the two
- * partitioning `raw`. What {@link trailingLineEnding} answers instead is which ending the
- * DOCUMENT uses, so a site reattaching a block's own bytes reads this one (G4.20).
- */
+/** The ending `raw` actually carries, empty when it has none: {@link trimTrailingLineEnding}'s
+ *  complement, for code reattaching a block's own bytes. */
 export function ownTrailingLineEnding(raw) {
     return raw.slice(displayLength(raw));
 }
+// ── The document's line ending ───────────────────────────────────────────────
 /**
- * `offset` moved off the interior of a surrogate pair, back to the pair's own start. Caret
- * offsets are UTF-16 code units, so a cut at one can halve an astral scalar and leave a lone
- * surrogate — bytes no UTF-8 encoder round-trips (`TextEncoder` yields U+FFFD) and no inverse
- * gesture restores. Scalars only: a grapheme cluster is a rendering question, and answering it
- * here would move a caret the author placed between two legitimately separate scalars.
+ * The ending every line the editor writes into `doc` takes: the document's first line break, else
+ * LF. Read afresh on each call, which scans only up to that first break.
  */
-export function snapToScalarBoundary(raw, offset) {
-    if (offset <= 0 || offset >= raw.length)
-        return offset;
-    const splitsPair = (raw.charCodeAt(offset - 1) & 0xfc00) === 0xd800 &&
-        (raw.charCodeAt(offset) & 0xfc00) === 0xdc00;
-    return splitsPair ? offset - 1 : offset;
+export function documentLineEnding(doc) {
+    return firstDocumentBreak(doc) ?? '\n';
 }
-/**
- * The block's authored trailing line ending. Every site that reattaches or mints one reads it
- * here (G4.20), so a CRLF-authored block keeps its ending and an unterminated one gets `\n`.
- */
-export function trailingLineEnding(raw) {
-    return raw.endsWith('\r\n') ? '\r\n' : '\n';
+function firstDocumentBreak(doc) {
+    let before = '';
+    for (const chunk of documentChunks(doc)) {
+        const at = chunk.indexOf('\n');
+        if (at >= 0)
+            return (at > 0 ? chunk[at - 1] : before) === '\r' ? '\r\n' : '\n';
+        if (chunk !== '')
+            before = chunk[chunk.length - 1];
+    }
+    return null;
+}
+function* documentChunks(doc) {
+    yield doc.prefix;
+    for (const child of doc.children) {
+        yield child.leadingTrivia ?? '';
+        yield child.raw;
+    }
+    yield doc.suffix;
+}
+/** The first line break in `text`, or null when it holds none. In a document with one ending,
+ *  any break in a block's own bytes is the document's. */
+export function firstLineEnding(text) {
+    const at = text.indexOf('\n');
+    if (at < 0)
+        return null;
+    return text[at - 1] === '\r' ? '\r\n' : '\n';
+}
+/** The ending `raw` closes with, else `fallback`, usually the document's ending: a block with no
+ *  ending of its own is the document's last line. */
+export function trailingLineEnding(raw, fallback) {
+    return ownTrailingLineEnding(raw) || fallback;
+}
+/** `text` closed with `ending` when its last line is open: a slice cut from a block would
+ *  otherwise run into whatever follows it once the bytes stand alone. */
+export function terminateLine(text, ending) {
+    return text.endsWith('\n') ? text : text + ending;
+}
+/** Whether the last line of `text` holds only spaces and tabs, its ending aside. */
+export function endsInBlankLine(text) {
+    const body = trimTrailingLineEnding(text);
+    return isBlankLine(body.slice(body.lastIndexOf('\n') + 1));
+}
+// ── Scalars ──────────────────────────────────────────────────────────────────
+/** The first half of a UTF-16 surrogate pair, as a code unit (`charCodeAt`). */
+export function isHighSurrogate(unit) {
+    return unit >= 0xd800 && unit <= 0xdbff;
+}
+/** The second half of a UTF-16 surrogate pair, as a code unit (`charCodeAt`). */
+export function isLowSurrogate(unit) {
+    return unit >= 0xdc00 && unit <= 0xdfff;
 }
 /**
- * Keep a truncated slice line-terminated, borrowing `sourceRaw`'s own ending (G4.20). A slice
- * whose last line stays open swallows whatever follows it once the bytes stand alone.
+ * `offset` moved off the interior of a surrogate pair, back to the pair's start: a cut there
+ * leaves a lone surrogate, which no UTF-8 encoder round-trips. Code points only, not graphemes.
  */
-export function terminateLine(text, sourceRaw) {
-    return text.endsWith('\n') ? text : text + trailingLineEnding(sourceRaw);
+export function snapToScalarBoundary(raw, offset) {
+    if (offset <= 0 || offset >= raw.length)
+        return offset;
+    const splitsPair = isHighSurrogate(raw.charCodeAt(offset - 1)) && isLowSurrogate(raw.charCodeAt(offset));
+    return splitsPair ? offset - 1 : offset;
 }
-/** Paste entry points funnel through here so Windows CRLF does not leak into a note. */
+// ── Splitting ────────────────────────────────────────────────────────────────
+/** Every paste entry point goes through here, so the paste rules read LF whatever the clipboard
+ *  held; the paste writes the document's own ending back. */
 export function normalizeLineEndings(text) {
     return text.replace(/\r\n/g, '\n');
 }
+/** `text` with every line break written as `ending`: how LF text joins a document's own lines. */
+export function withLineEnding(text, ending) {
+    return text.replace(/\r?\n/g, ending);
+}
+/** The line break starting at `offset` in `text`, empty when none starts there. */
+export function lineEndingAt(text, offset) {
+    if (text[offset] === '\n')
+        return '\n';
+    return text.startsWith('\r\n', offset) ? '\r\n' : '';
+}
 export function splitLines(source) {
     const lines = [];
     let start = 0;
@@ -68,11 +151,59 @@ export function splitLines(source) {
     }
     return lines;
 }
-/**
- * Re-mint a `ParsedLine[]` after a per-line strip, as the container parsers do when they reparse
- * a prefix-stripped body. Recompute, not spread: reusing an input line's offsets after shortening
- * its text desyncs the offsets from the bytes.
- */
+/** A block's display as lines, each apart from its ending. A display always has a last line, empty
+ *  after a final break, and {@link joinDisplayLines} puts the bytes back exactly. */
+export function displayLines(display) {
+    const lines = splitLines(display).map((line) => ({
+        text: line.text,
+        ending: line.lineEnding
+    }));
+    if (display === '' || display.endsWith('\n'))
+        lines.push({ text: '', ending: '' });
+    return lines;
+}
+/** {@link displayLines}' first line, read without splitting the rest of `text`. */
+export function firstDisplayLine(text) {
+    const at = text.indexOf('\n');
+    return displayLines(at < 0 ? text : text.slice(0, at + 1))[0];
+}
+export function joinDisplayLines(lines) {
+    return lines.map((line) => line.text + line.ending).join('');
+}
+// ── Indentation ──────────────────────────────────────────────────────────────
+/** Columns of leading indentation, a tab advancing to the next multiple of four (GFM §2.2). */
+export function indentColumns(text) {
+    let col = 0;
+    for (const char of text) {
+        if (char === ' ')
+            col++;
+        else if (char === '\t')
+            col += 4 - (col % 4);
+        else
+            break;
+    }
+    return col;
+}
+/** `text` with up to `columns` columns of indentation removed. A tab the cut splits is written as
+ *  the spaces it spans, since every later reparse reads the child's raw from column zero. */
+export function stripIndentColumns(text, columns) {
+    const leadLength = text.length - text.replace(/^[ \t]+/, '').length;
+    let col = 0;
+    let cut = 0;
+    while (cut < leadLength) {
+        const width = text[cut] === '\t' ? 4 - (col % 4) : 1;
+        if (col + width > columns)
+            break;
+        col += width;
+        cut++;
+    }
+    const straddles = cut < leadLength && col < columns;
+    const tabShifts = columns % 4 !== 0 && text.slice(cut, leadLength).includes('\t');
+    if (!straddles && !tabShifts)
+        return text.slice(cut);
+    return ' '.repeat(indentColumns(text) - columns) + text.slice(leadLength);
+}
+/** A `ParsedLine[]` rebuilt after a per-line strip, offsets recomputed from the stripped bytes. */
 export function remapStrippedLines(lines, stripLine) {
     let offset = 0;
     return lines.map((line, index) => {

package/dist/core/metadata-parity.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Whether a node's metadata is what a parse of its own bytes derives, key by key: the one compare
+ * behind every check and re-read that holds metadata to its bytes.
+ */
+import type { NodeView } from './node-views';
+/** The first metadata key whose live value differs from the reparse's, described, or null. */
+export declare function describeMetadataDivergence(live: NodeView, reparsed: NodeView): string | null;
+/** A value as a failure message quotes it: strings quoted, everything else as `String` prints it. */
+export declare function showValue(value: unknown): string;

package/dist/core/metadata-parity.js

@@ -0,0 +1,25 @@
+/**
+ * Whether a node's metadata is what a parse of its own bytes derives, key by key: the one compare
+ * behind every check and re-read that holds metadata to its bytes.
+ */
+/** The first metadata key whose live value differs from the reparse's, described, or null. */
+export function describeMetadataDivergence(live, reparsed) {
+    const liveMeta = (live.metadata ?? {});
+    const reMeta = (reparsed.metadata ?? {});
+    for (const key of new Set([...Object.keys(liveMeta), ...Object.keys(reMeta)])) {
+        if (!valuesEqual(liveMeta[key], reMeta[key])) {
+            return `${live.kind}.${key}: live ${showValue(liveMeta[key])} != reparsed ${showValue(reMeta[key])}`;
+        }
+    }
+    return null;
+}
+/** A value as a failure message quotes it: strings quoted, everything else as `String` prints it. */
+export function showValue(value) {
+    return typeof value === 'string' ? JSON.stringify(value) : String(value);
+}
+function valuesEqual(a, b) {
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((v, i) => v === b[i]);
+    }
+    return a === b;
+}

package/dist/core/node-views.d.ts

@@ -1,9 +1,9 @@
 /**
- * G1.9 in the type system (G3.8): a snapshot-shared node is read-only on its serialized bytes,
- * so a view freezes every byte-carrying field. `childIds`, `childSpans` and `ownerEpoch` are
- * editor bookkeeping, not round-trip bytes, and stay writable through a view. The ONE sanctioned
- * view-to-mutable door is the unshare seam (`tree-operations/unshare.ts`) plus the commit
- * ceremony's owned scope views (G4.13); everywhere else the source-scan lint holds the perimeter.
+ * A node shared with an undo snapshot is read-only on its serialized bytes (G1.9), and a view
+ * types that: every byte-carrying field is frozen. `childIds`, `childSpans` and `ownerEpoch` are
+ * editor bookkeeping, not round-trip bytes, and stay writable. The only casts from a view back to
+ * a mutable node are the copy-before-write in `tree-operations/unshare.ts` and the commit
+ * sequence's owned views (G4.13); a lint test holds that line everywhere else.
  */
 import type { CstNode, Document } from './nodes';
 type BytesWritableKey = 'childIds' | 'childSpans' | 'ownerEpoch';
@@ -15,7 +15,8 @@ export type BytesView<T> = T extends string | number | boolean | bigint | symbol
 };
 export type NodeView = BytesView<CstNode>;
 export type DocumentView = BytesView<Document>;
-/** A spine root the unshare seam accepts: the live document or a caller-owned children wrapper. */
+/** A root the copy-before-write in `tree-operations/unshare.ts` accepts: the live document or a
+ *  caller-owned children wrapper. */
 export type NodeParentView = {
     readonly children: readonly NodeView[];
 };

package/dist/core/node-views.js

@@ -1,8 +1,8 @@
 /**
- * G1.9 in the type system (G3.8): a snapshot-shared node is read-only on its serialized bytes,
- * so a view freezes every byte-carrying field. `childIds`, `childSpans` and `ownerEpoch` are
- * editor bookkeeping, not round-trip bytes, and stay writable through a view. The ONE sanctioned
- * view-to-mutable door is the unshare seam (`tree-operations/unshare.ts`) plus the commit
- * ceremony's owned scope views (G4.13); everywhere else the source-scan lint holds the perimeter.
+ * A node shared with an undo snapshot is read-only on its serialized bytes (G1.9), and a view
+ * types that: every byte-carrying field is frozen. `childIds`, `childSpans` and `ownerEpoch` are
+ * editor bookkeeping, not round-trip bytes, and stay writable. The only casts from a view back to
+ * a mutable node are the copy-before-write in `tree-operations/unshare.ts` and the commit
+ * sequence's owned views (G4.13); a lint test holds that line everywhere else.
  */
 export {};